Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
---
depth: standard
id: EVID-036
kind: evidence
last_modified_at: 2026-05-09T11:38:56.840360+00:00
last_modified_by: claude-code/2.1.138
links:
- target: PRD-031
relation: informs
status: active
title: Drop precompressed assets — build/smoke/probe measurements
---

# EVID-036: Drop precompressed assets — build/smoke/probe measurements

| Field | Value |
|-------|-------|
| Status | Draft |
| Created | 2026-05-09 |
| Valid Until | 2026-08-09 |
| Target | PRD-031 |

## Structured Fields

evidence_type: measurement
verdict: supports
congruence_level: 3

## Measurement

Built `@forgeplan/web` after flipping `template/svelte.config.js` from
`adapter()` to `adapter({ precompress: false })`. Measured against
PRD-031 SC-1 / SC-2 / SC-3 / SC-4 / SC-5 directly on the post-build
`dist/` and `dist-nightly/` directories and on a live server spawned
from a scratch `init`. All commands executed in
`/Users/nikitafedorov/Desktop/Projects/forgeplan-web` on
`darwin 25.4.0` against the same `develop` branch the change was made on.

Commands:

```bash
# SC-1: precompressed sibling count
find dist dist-nightly -name '*.br' -o -name '*.gz' | wc -l

# SC-2: per-image size
du -sh dist dist-nightly

# SC-3 + SC-4: live server probe
SCRATCH=$(mktemp -d) && cd "$SCRATCH" && mkdir -p .forgeplan
node /…/bin/forgeplan-web.mjs init -y --image nightly
PORT=15998 node .forgeplan-web/index.js &
curl -sI http://127.0.0.1:15998/_app/immutable/entry/app.DvKYkSiM.js
curl -sI -H 'Accept-Encoding: br, gzip' \
http://127.0.0.1:15998/_app/immutable/entry/app.DvKYkSiM.js
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:15998/

# SC-5: smoke
npm run smoke
```

## Result

| SC | Metric | Before | After | Pass? |
|-----|--------|--------|-------|-------|
| SC-1 | precompressed siblings (`*.br` + `*.gz` under both `dist*/client/`) | 84 | **0** | ✅ |
| SC-2 | `du -sh dist` | 2.0M | **1.5M** (-25%) | ✅ (< 3M cap) |
| SC-2 | `du -sh dist-nightly` | 2.0M | **1.5M** (-25%) | ✅ (< 3M cap) |
| SC-3 | `GET /` HTTP status (live server, scratch dir) | 200 | **200** | ✅ |
| SC-4 | `/api/health` returns `ok` (smoke run) | ok | **ok** (project=shim) | ✅ |
| SC-5 | `npm run smoke` exit code | 0 | **0** (`ALL IMAGES PASS`) | ✅ |

`scripts/build.mjs` post-build report after the change:

```
[build] dist/ ready (1.40M, image=stable, features=0)
[build] dist-nightly/ ready (1.40M, image=nightly, features=0)
[build] done. images built: stable, nightly
```

Asset-compression probe (3047-byte `app.DvKYkSiM.js`):

```
--- without Accept-Encoding ---
HTTP/1.1 200 OK
Content-Length: 3047
--- with Accept-Encoding: br, gzip ---
HTTP/1.1 200 OK
Content-Length: 3047
```

→ Sirv (adapter-node's static layer) serves uncompressed bytes when
precompressed siblings are absent. There is **no** `Content-Encoding`
header in either response. PRD-031 R-1 ("uncompressed first-load wire
traffic") is therefore real, not just theoretical — but it lands on a
loopback `127.0.0.1` connection in the canonical deployment, where the
cost is negligible.

## Interpretation

Option A from issue #120 (disable `precompress` at adapter level) is
implemented and verified end-to-end. All five PRD-031 success criteria
pass on the first build. Tarball saving is ~520K per image (~1.04 MB
total across both images) — exactly the figure forecast in the issue
body. Live server still serves `GET /` HTTP 200 from a freshly
initialised scratch dir; smoke matrix passes with `ALL IMAGES PASS`.

The compression-probe result confirms the documented trade-off (R-1):
sirv does NOT compress on-the-fly; clients receive uncompressed bytes.
For local-first deployments (`127.0.0.1`, single user) this is
negligible. If a future user reports slow first-load over a slow
network, the mitigation path is documented in PRD-031 (flip
`precompress` back to `true`, or wire an on-the-fly compression
middleware in `template/src/hooks.server.ts`).

This evidence supports activating PRD-031 with `R_eff > 0`.

## Congruence Level Justification

CL3 (same context, penalty 0.0): the measurement was executed against
the exact build artifacts (`dist/`, `dist-nightly/`) and the exact bin
script (`bin/forgeplan-web.mjs init … && node .forgeplan-web/index.js`)
that PRD-031 governs, on the same `develop` branch the change was
landed on. No proxy environment, no benchmark surrogate, no cached
result — direct measurement on the surface the PRD describes.

## Related Artifacts

| Artifact | Relation |
|----------|----------|
| PRD-031 | informs |


Original file line number Diff line number Diff line change
Expand Up @@ -228,3 +228,4 @@ Then используется именно /custom/path/forgeplan, а не де

> **Next step**: создать RFC-013 с архитектурой бандла + эджкейсами.


Original file line number Diff line number Diff line change
Expand Up @@ -300,3 +300,4 @@ And neither directory contains a `node_modules/` subdirectory




Original file line number Diff line number Diff line change
@@ -0,0 +1,210 @@
---
depth: standard
id: PRD-031
kind: prd
last_modified_at: 2026-05-09T11:34:37.535120+00:00
last_modified_by: claude-code/2.1.138
links:
- target: PRD-014
relation: based_on
- target: PRD-030
relation: based_on
status: active
title: Drop precompressed client assets from tarball
---

---
id: PRD-031
title: "Drop precompressed client assets from tarball"
status: Draft
author: fedorovvvv
created: 2026-05-09
updated: 2026-05-09
priority: P2
depth: standard
domain: general
projectType: cli_tool
stepsCompleted: []
---

# PRD-031: Drop precompressed client assets from tarball

## Progress

```
Phase 0 ████████████████████████ 1/1 (100%)
─────────────────────────────────────────────────
TOTAL 1/1 (100%)
```

---

## Executive Summary

### Vision

Ship a smaller `@forgeplan/web` tarball by removing 84 precompressed
`*.br` / `*.gz` client siblings emitted by `@sveltejs/adapter-node` —
saving ~520K per `dist*/` artifact (~29% of the experimental tarball)
without measurably degrading the local-first user experience.

### Problem

`@sveltejs/adapter-node` defaults to `precompress: true`, so every
`dist*/client/` carries 21 `.br` + 21 `.gz` files alongside the
originals (~520K). The tarball ships **two** images (`dist/` for
`stable`, `dist-nightly/` for `nightly`), so users pay the cost twice
on every `npm install` / `npx` invocation.

The runtime CPU savings precompressed assets buy (sirv serving the
cached `.br`/`.gz` directly) are negligible for the canonical
deployment shape: `npx @forgeplan/web start` on `127.0.0.1` for one
local user, behind no CDN. Every user pays the install cost; almost
nobody benefits from the runtime saving.

**Impact**: ~520K × 2 dists = ~1.04 MB of dead weight on every
install. After PR #117 minified the server bundle (1.4 MB → 683 KB),
precompressed client assets are now the largest fixed cost in
`dist-nightly/`.

### Target Users

| Persona | Описание | Ключевая боль |
|---------|----------|---------------|
| Local-first user | Runs `npx @forgeplan/web start` on `127.0.0.1` | Pays install cost (tarball download + extraction) for runtime savings they will never measure |
| CI runner | Installs `@forgeplan/web` in throwaway environments | Slower cold installs because of inflated tarball |

### Differentiators

- Single-flag adapter change (Option A from issue #120) — minimal
blast radius, fully reversible by flipping `precompress` back to
`true`.
- Aligned with `npx @forgeplan/web` philosophy: the package is
optimized for fast first-run on a developer machine, not for
high-throughput public-facing serving.

---

## Success Criteria

| ID | Criterion | Metric | Current | Target | Timeframe | How to Measure |
|----|-----------|--------|---------|--------|-----------|----------------|
| SC-1 | Precompressed siblings absent from both shipped images | count of `*.br` + `*.gz` under `dist/client/` ∪ `dist-nightly/client/` after `npm run build` | 84 | 0 | This PR | `find dist dist-nightly -name '*.br' -o -name '*.gz' \| wc -l` |
| SC-2 | Each tarball image stays under PRD-014 SC-1 cap | `du -sh dist*/` | 2.0M each | ≤ 1.5M each (target) / ≤ 3M (cap) | This PR | `du -sh dist dist-nightly` |
| SC-3 | `start` still serves usable HTML | HTTP status of `GET /` after `npx @forgeplan/web start` | 200 | 200 | This PR | scratch-dir manual probe (see EVID) |
| SC-4 | `/api/health` still returns `ok` | endpoint response | `{ ok: true }` | `{ ok: true }` | This PR | manual probe |
| SC-5 | No regression in `npm run smoke` | smoke exit code | 0 | 0 | This PR | `npm run smoke` |

---

## Product Scope

### MVP (In-Scope)

- Pass `precompress: false` to `adapter()` in `template/svelte.config.js`.
- Re-build both images (`dist/` + `dist-nightly/`) and verify the
precompressed siblings are gone.
- Smoke test the bin script against a scratch dir end-to-end.
- Document the trade-off (no precompressed cache; sirv now serves
uncompressed or compresses on-the-fly per `Accept-Encoding`).

### Out of Scope

- Lowering `DIST_*_MAX_BYTES` cap in `scripts/build.mjs` — separate
decision (PRD candidate).
- RFC-013 graduation / legacy `dist/` removal — owned by PRD-014.
- Adding a custom sirv compression middleware to recover the runtime
saving — only if a measured regression appears.

### Growth Vision

- If real users complain about uncompressed first-load wire size
over slow networks, revisit by either (a) flipping `precompress`
back on, or (b) wiring an on-the-fly compression middleware in
`template/src/hooks.server.ts`.

---

## User Journeys

### Journey 1: Local-first user installs and starts

**Цель пользователя**: Spin up the Forgeplan web viewer in a working repo.

| Шаг | Действие пользователя | Ответ системы | Заметки |
|-----|----------------------|---------------|---------|
| 1 | `npx @forgeplan/web init -y` | Copies `dist/` (~1.5 MB target) into `.forgeplan-web/` | Smaller download than today |
| 2 | `npx @forgeplan/web start` | Spawns node, listens on `127.0.0.1:5174` | No precompressed cache hit on assets |
| 3 | Opens `http://127.0.0.1:5174` | Browser receives HTML; CSS/JS load | sirv serves assets uncompressed or via on-the-fly gzip per `Accept-Encoding` (TBD by smoke) |

**Результат**: Same UX, smaller install footprint.

### Journey 2: CI runner does throwaway install

**Цель пользователя**: Validate Forgeplan integration in CI.

| Шаг | Действие пользователя | Ответ системы | Заметки |
|-----|----------------------|---------------|---------|
| 1 | `npm i -g @forgeplan/web@latest` | Pulls smaller tarball, faster cold install | Saves ~1 MB per cold install across both images |
| 2 | `forgeplan-web --version` | Prints version | Unaffected by this change |

**Результат**: Faster CI cold start, no functional change.

---

## Functional Requirements

| ID | Category | Priority | Requirement | Journey |
|----|----------|----------|-------------|---------|
| FR-001 | Build | Must | Build pipeline can emit `dist*/client/` directories with no `*.br` and no `*.gz` siblings | Journey 1, Journey 2 |
| FR-002 | Runtime | Must | `start` command can serve an HTTP 200 on `GET /` and `/api/health` from a freshly initialised `.forgeplan-web/` that contains no precompressed siblings | Journey 1 |
| FR-003 | Runtime | Should | Browser can render a usable page (CSS + JS load successfully) when the static-asset middleware has no precompressed siblings to fall back to | Journey 1 |

---

## Non-Functional Requirements

| ID | Category | Requirement | Metric | Condition | Measurement |
|----|----------|-------------|--------|-----------|-------------|
| NFR-001 | Size | System shall emit each `dist*/` artifact below the existing cap | ≤ 3 MB | After `npm run build` for both `stable` and `nightly` images | `du -sh dist dist-nightly` + `scripts/build.mjs` cap assertion |
| NFR-002 | Reversibility | System shall allow restoring precompressed assets by flipping a single boolean | 1 line in `template/svelte.config.js` | Forever | Diff inspection |
| NFR-003 | Compatibility | System shall not regress `npm run smoke` exit code | exit code = 0 | Local + CI matrix (ubuntu/macos/windows) | `npm run smoke` |

---

## Risks & Mitigations

| ID | Risk | Probability | Impact | Mitigation | Owner |
|----|------|-------------|--------|------------|-------|
| R-1 | Without precompressed siblings, sirv serves assets uncompressed → +700 KB first-load wire traffic for users on slow links | Medium | Low (local-first deployments dominate) | Document in README + this PRD; if real complaints surface, add an on-the-fly gzip middleware in `template/src/hooks.server.ts` or revert to `precompress: true` | fedorovvvv |
| R-2 | A future custom hook in `template/` assumes `.br`/`.gz` siblings exist | Low | Medium | Grep template for `\.br` / `\.gz` references in this PR; none found at time of writing | fedorovvvv |
| R-3 | Adapter-node behavior changes in a future major version, making `precompress: false` ineffective | Low | Low | Pinned via `template/package.json#dependencies`; bump-with-test is the existing process | fedorovvvv |

---

## Affected Files

- `template/svelte.config.js` — flip `adapter()` → `adapter({ precompress: false })`.
- `dist/`, `dist-nightly/` — regenerated by `npm run build` (no source-controlled change beyond the regenerated bundles).

## Related Artifacts

| Artifact | Relation | Status |
|----------|----------|--------|
| PRD-014 | parent (tarball-size cap SC-1) | active |
| PRD-030 | parent (dual-image pipeline `stable` + `nightly`) | active |
| PR #117 | predecessor (server bundle minify, 1.4 MB → 683 KB) | merged |
| Issue #120 | source | open (this PRD closes it) |

---

> **Decision recorded (closes issue #120 acceptance criterion 1)**:
> Option A — disable precompress at the adapter level. Rejected:
> Option B (build.mjs strip — strictly more code for the same runtime
> behaviour) and Option C (keep `.br` only — half the size win for
> ~zero additional safety, since a sirv fallback regression would still
> need investigation).




2 changes: 1 addition & 1 deletion template/svelte.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
const config = {
preprocess: vitePreprocess(),
kit: {
adapter: adapter(),
adapter: adapter({ precompress: false }),
files: {
assets: 'static',
lib: 'src/shared'
Expand Down
Loading