[E00-S01-T06] Document local non-container developer path #373

2026-08-28T08:52:17Z

bot-implementer commented

2026-08-28 08:52:17 +00:00

What changed

Documents the local non-container developer path so an engineer can install, build and run EPPP without Docker for [E00-S01-T06] Document local non-container developer path (#159):

docs/development/non-container.md (new) — the developer guide:
- Install — prerequisites (Git, Node.js 24.x, pnpm 11.23.0 via Corepack), clone, corepack enable, pnpm install --frozen-lockfile; explains why the install is frozen and that lockfile changes must be committed
- Build — pnpm build (compiles all workspace packages to dist/) and pnpm typecheck (tsc --noEmit across packages)
- Run — pnpm --filter @personal-blog/server start, with an honest note that at bootstrap apps/server is a placeholder module (loads and exits 0; the Fastify 5 application shell that turns it into a serving process lands in a later story) and the general node <pkg>/dist/index.js pattern for any package
- Test — pnpm test (node:test suites under tests/, currently the 10-test architecture-import suite)
- Smoke-check sequence from a clean clone, workspace layout, troubleshooting table, and explicit out-of-scope list (root script wiring is E00-S01-T05; Docker Compose baseline is E00-S02)
apps/server/package.json — adds a minimal start script (node dist/index.js) so the documented run step is a first-class pnpm command consistent with build/typecheck. No source behavior change: the entrypoint stays a bootstrap placeholder (its story is the Fastify 5 shell). No new dependencies — pnpm-lock.yaml untouched.

Explicitly out of scope per the brief: root build/test scripts (E00-S01-T05) and Docker Compose baseline (E00-S02) — neither is touched; this PR only documents usage of the former and explicitly excludes the latter.

Criterion → test table

Acceptance criterion Evidence / test

a local non-container developer path is documented docs/development/non-container.md added at docs/development/non-container.md; covers the full non-container path (install → build → run → test) with a smoke-check section; container path explicitly deferred to E00-S02

the document covers install, build and run steps Documented steps executed from a clean clone (no node_modules/, no dist/): pnpm install --frozen-lockfile → exit 0, "Already up to date" (lockfile untouched, git status clean apart from the two commits) ✓; pnpm build → 3/3 packages emit dist/, exit 0 ✓; pnpm typecheck → 3/3 packages pass --noEmit, exit 0 ✓; run step pnpm --filter @personal-blog/server start → loads compiled entrypoint, exit 0 ✓ (plus node apps/server/dist/index.js direct, exit 0)

Test plan executed

Clean-state install: pnpm install --frozen-lockfile (pnpm 11.23.0, same as CI) from a clone with no node_modules/dist → success, lockfile unchanged by the change ✓
pnpm build → apps/server, packages/core, extensions/example all Done, dist/ emitted per package (exit 0) ✓
pnpm typecheck → 3/3 packages pass --noEmit (exit 0) ✓
pnpm test → tests/architecture-import.test.mjs 10/10 pass (exit 0) ✓
Run step: pnpm --filter @personal-blog/server start and node apps/server/dist/index.js both exit 0 ✓
CI parity: pnpm install --frozen-lockfile still passes after the start script addition; pnpm -r list --depth -1 lists all 4 workspace projects (exit 0); apps/server/package.json parses as valid JSON ✓

Risks / notes

The start script is a run-path convenience for the documentation task; the server's real behavior (HTTP serving) is owned by the Fastify 5 application shell story and deliberately not implemented here — the placeholder entrypoint is unchanged.
Documentation-only change plus one script line; rollback is a revert of the two commits (no runtime data, no dependencies, no CI workflow changes).
CI on this PR runs the existing frozen-install job (Node 24, corepack, frozen lockfile, workspace group listing) — nothing about the change affects it.

Closes #159

## What changed Documents the local **non-container** developer path so an engineer can install, build and run EPPP without Docker for [E00-S01-T06] Document local non-container developer path (#159): - **`docs/development/non-container.md`** (new) — the developer guide: - **Install** — prerequisites (Git, Node.js 24.x, pnpm 11.23.0 via Corepack), clone, `corepack enable`, `pnpm install --frozen-lockfile`; explains why the install is frozen and that lockfile changes must be committed - **Build** — `pnpm build` (compiles all workspace packages to `dist/`) and `pnpm typecheck` (`tsc --noEmit` across packages) - **Run** — `pnpm --filter @personal-blog/server start`, with an honest note that at bootstrap `apps/server` is a placeholder module (loads and exits 0; the Fastify 5 application shell that turns it into a serving process lands in a later story) and the general `node <pkg>/dist/index.js` pattern for any package - **Test** — `pnpm test` (`node:test` suites under `tests/`, currently the 10-test architecture-import suite) - Smoke-check sequence from a clean clone, workspace layout, troubleshooting table, and explicit out-of-scope list (root script wiring is E00-S01-T05; Docker Compose baseline is E00-S02) - **`apps/server/package.json`** — adds a minimal `start` script (`node dist/index.js`) so the documented run step is a first-class pnpm command consistent with `build`/`typecheck`. No source behavior change: the entrypoint stays a bootstrap placeholder (its story is the Fastify 5 shell). No new dependencies — `pnpm-lock.yaml` untouched. Explicitly out of scope per the brief: root build/test scripts (E00-S01-T05) and Docker Compose baseline (E00-S02) — neither is touched; this PR only documents usage of the former and explicitly excludes the latter. ## Criterion → test table | Acceptance criterion | Evidence / test | | --- | --- | | a local non-container developer path is documented | `docs/development/non-container.md` added at `docs/development/non-container.md`; covers the full non-container path (install → build → run → test) with a smoke-check section; container path explicitly deferred to E00-S02 | | the document covers install, build and run steps | Documented steps executed from a **clean clone** (no `node_modules/`, no `dist/`): `pnpm install --frozen-lockfile` → exit 0, "Already up to date" (lockfile untouched, `git status` clean apart from the two commits) ✓; `pnpm build` → 3/3 packages emit `dist/`, exit 0 ✓; `pnpm typecheck` → 3/3 packages pass `--noEmit`, exit 0 ✓; run step `pnpm --filter @personal-blog/server start` → loads compiled entrypoint, exit 0 ✓ (plus `node apps/server/dist/index.js` direct, exit 0) | ## Test plan executed - Clean-state install: `pnpm install --frozen-lockfile` (pnpm 11.23.0, same as CI) from a clone with no `node_modules`/`dist` → success, lockfile unchanged by the change ✓ - `pnpm build` → `apps/server`, `packages/core`, `extensions/example` all `Done`, `dist/` emitted per package (exit 0) ✓ - `pnpm typecheck` → 3/3 packages pass `--noEmit` (exit 0) ✓ - `pnpm test` → `tests/architecture-import.test.mjs` 10/10 pass (exit 0) ✓ - Run step: `pnpm --filter @personal-blog/server start` and `node apps/server/dist/index.js` both exit 0 ✓ - CI parity: `pnpm install --frozen-lockfile` still passes after the `start` script addition; `pnpm -r list --depth -1` lists all 4 workspace projects (exit 0); `apps/server/package.json` parses as valid JSON ✓ ## Risks / notes - The `start` script is a run-path convenience for the documentation task; the server's real behavior (HTTP serving) is owned by the Fastify 5 application shell story and deliberately not implemented here — the placeholder entrypoint is unchanged. - Documentation-only change plus one script line; rollback is a revert of the two commits (no runtime data, no dependencies, no CI workflow changes). - CI on this PR runs the existing `frozen-install` job (Node 24, corepack, frozen lockfile, workspace group listing) — nothing about the change affects it. Closes #159

bot-implementer added 2 commits 2026-08-28 08:52:18 +00:00

docs: add local non-container developer path guide (E00-S01-T06) 72c53494a1

feat(server): add start script for compiled entrypoint (E00-S01-T06)

CI / Frozen lockfile install (pull_request) Successful in 48s

Details

21485aed44

kpcto merged commit bd8c94982a into main

2026-08-28 08:59:03 +00:00

kpcto deleted branch feature/159

2026-08-28 08:59:04 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Fabrika/PersonalBlog#373