diff --git a/.forgeplan/evidence/EVID-036-drop-precompressed-assets-build-smoke-probe-measurements.md b/.forgeplan/evidence/EVID-036-drop-precompressed-assets-build-smoke-probe-measurements.md new file mode 100644 index 0000000..b0ae00f --- /dev/null +++ b/.forgeplan/evidence/EVID-036-drop-precompressed-assets-build-smoke-probe-measurements.md @@ -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 | + + diff --git a/.forgeplan/prds/PRD-014-reduce-dist-size-by-bundling-server-with-esbuild.md b/.forgeplan/prds/PRD-014-reduce-dist-size-by-bundling-server-with-esbuild.md index 1ba1474..dde170e 100644 --- a/.forgeplan/prds/PRD-014-reduce-dist-size-by-bundling-server-with-esbuild.md +++ b/.forgeplan/prds/PRD-014-reduce-dist-size-by-bundling-server-with-esbuild.md @@ -228,3 +228,4 @@ Then используется именно /custom/path/forgeplan, а не де > **Next step**: создать RFC-013 с архитектурой бандла + эджкейсами. + diff --git a/.forgeplan/prds/PRD-030-feature-flag-and-image-system-promote-experimental-bundle-to-stable-default.md b/.forgeplan/prds/PRD-030-feature-flag-and-image-system-promote-experimental-bundle-to-stable-default.md index 4e0a510..b039594 100644 --- a/.forgeplan/prds/PRD-030-feature-flag-and-image-system-promote-experimental-bundle-to-stable-default.md +++ b/.forgeplan/prds/PRD-030-feature-flag-and-image-system-promote-experimental-bundle-to-stable-default.md @@ -300,3 +300,4 @@ And neither directory contains a `node_modules/` subdirectory + diff --git a/.forgeplan/prds/PRD-031-drop-precompressed-client-assets-from-tarball.md b/.forgeplan/prds/PRD-031-drop-precompressed-client-assets-from-tarball.md new file mode 100644 index 0000000..7b660d0 --- /dev/null +++ b/.forgeplan/prds/PRD-031-drop-precompressed-client-assets-from-tarball.md @@ -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). + + + + diff --git a/template/svelte.config.js b/template/svelte.config.js index 0a17a14..5da1367 100644 --- a/template/svelte.config.js +++ b/template/svelte.config.js @@ -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'