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
63 changes: 44 additions & 19 deletions .claude/rules/20-init-host-isolation.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,47 @@
# `init` host isolation

`bin/forgeplan-web.mjs init` runs in the user's project directory. It
MUST write only inside `<cwd>/.forgeplan-web/`, with **one** narrow
exception: appending an ignore rule for `.forgeplan-web/` to the host's
`.gitignore` (see ADR-001). Every other host write is forbidden.
`bin/forgeplan-web.mjs init` runs in the user's project directory. Its
write boundary depends on the resolved scope (PRD-025 / RFC-021):

## Forbidden writes from `init`
- **Project scope** (`--scope project`, or `-y` without `--scope`, or the
user picks "project" interactively): writes only inside
`<cwd>/.forgeplan-web/`, with **one** narrow exception — appending an
ignore rule for `.forgeplan-web/` to the host's `.gitignore` (see
ADR-001). Every other host write is forbidden.
- **User scope** (`--scope user`, or the user picks "user" interactively):
writes only inside `~/.forgeplan-web/` (resolved from `os.homedir()`,
per RFC-021 / ADR-004). The host project's `.gitignore` MUST NOT be
touched — the home directory is workspace-agnostic and the user-scope
scaffold is shared across projects, so an "ignore" hint in any
individual project would be misleading. User scope likewise does NOT
require a `.forgeplan/` workspace in the cwd at install time; the
workspace is bound at `start` time via `FORGEPLAN_CWD`.

## Forbidden writes from `init` (both scopes)

- The host's `package.json`, `pnpm-lock.yaml`, `package-lock.json`,
`yarn.lock`.
- The host's `.npmrc`, `.editorconfig`, or any other root config.
- The host's `node_modules/`.
- The host's `.forgeplan/` (the workspace is *read* via the bundled
`forgeplan` CLI; never written by us).
- Any file outside `<cwd>/.forgeplan-web/` other than the single
`.gitignore` exception below.
- Under `--scope user`: the host's `.gitignore` MUST NOT be created,
read-then-rewritten, or appended. User scope is gitignore-silent.
- Any file outside the resolved target directory (project: `<cwd>/.forgeplan-web/`,
user: `~/.forgeplan-web/`) other than the single `.gitignore`
exception below — and that exception applies to project scope only.

## Allowed writes

- Anything inside `<cwd>/.forgeplan-web/`.
- `<cwd>/.forgeplan-web/forgeplan-web.json` (workspace pointer the
SvelteKit server reads at runtime).
- `<cwd>/.gitignore` — **append-only**, with these constraints:
- **Project scope** only: anything inside `<cwd>/.forgeplan-web/`,
including `<cwd>/.forgeplan-web/forgeplan-web.json` (workspace pointer
the SvelteKit server reads at runtime).
- **User scope** only: anything inside `~/.forgeplan-web/`, including
`~/.forgeplan-web/forgeplan-web.json`. The `workspaceRoot` field in
the user-scope config is `null` at init-time (the user-scope dist is
workspace-agnostic; `start` binds the workspace from cwd or
`FORGEPLAN_CWD` at runtime).
- **Project scope** only: `<cwd>/.gitignore` — **append-only**, with these constraints:
- Add at most one ignore line: `.forgeplan-web/`.
- The append is idempotent. Detection regex per line:
`^[ \t]*\.forgeplan-web\/?[ \t]*$`. If a matching line is already
Expand All @@ -46,13 +66,18 @@ idempotent, reversible, and opt-out — see ADR-001.

## Verification

- `git status` in the host project after `init` must show changes only
inside `.forgeplan-web/` and (at most) a single appended block at the
end of `.gitignore`.
- The `init()` function in `bin/forgeplan-web.mjs` must not call
`writeFileSync` / `copyFileSync` / `mkdirSync` with any path that
does not resolve under `target` (`.forgeplan-web/`) or under the
host's `.gitignore`.
- Running `init` twice must not duplicate the `.gitignore` entry.
- After `init -y` or `init --scope project`: `git status` in the host
project must show changes only inside `.forgeplan-web/` and (at most)
a single appended block at the end of `.gitignore`.
- After `init --scope user`: `git status` in the cwd must show **no**
changes at all. All writes land under `~/.forgeplan-web/`.
- `runInit()` in `bin/commands/init.mjs` must not call `writeFileSync`
/ `copyFileSync` / `mkdirSync` with any path that does not resolve
under the resolved scope target (`<cwd>/.forgeplan-web/` or
`~/.forgeplan-web/`) — and, only under project scope, the host's
`.gitignore`.
- Running `init -y` twice must not duplicate the `.gitignore` entry.
- Running `init -y --no-gitignore` must not touch `.gitignore` at all
(no create, no append, no read-then-rewrite).
- `ensureGitignore` is called from `runInit` only when `scope ===
"project"`; user-scope code paths must not even invoke it.
41 changes: 40 additions & 1 deletion .claude/rules/22-readonly-proxy.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ revision of this rule. See PRD-012 / RFC-011.

## Allow-list extension: `/api/update-check` (non-forgeplan)

`/api/update-check` is the **single** non-forgeplan endpoint permitted from
`/api/update-check` is one of the non-forgeplan endpoints permitted from
`/api/*`. It probes the npm registry for the latest published version of
`@forgeplan/web` so the UI can surface an "Update available" affordance.

Expand All @@ -52,6 +52,40 @@ Any additional non-forgeplan endpoint (whether it hits npm, GitHub,
crates.io, or anything else) requires a new Forgeplan artifact and a fresh
amendment to this rule. See PRD-013 / RFC-012.

## Allow-list extension: `/api/instances` (non-forgeplan)

`/api/instances` is the second non-forgeplan endpoint permitted from
`/api/*`. It exposes a read-only mirror of the global instance registry at
`~/.forgeplan-web/instances.json` (PRD-027 / RFC-023 / SPEC-003 / ADR-004) so
the UI can surface an instance switcher (PRD-029, Wave 6).

Constraints (every one of these is enforceable from the diff):

- Method: `GET` only.
- File path: the registry file is resolved as
`path.join(os.homedir(), ".forgeplan-web", "instances.json")` —
**no interpolation, no env override, no user input** on the path.
- **No spawn, no `fs.write*` / `fs.mkdir*` / `fs.rename*` / `fs.unlink*`**.
The endpoint MUST NOT mutate the registry; mutations live exclusively in
`bin/lib/registry.mjs`. The endpoint reads via `node:fs.readFileSync`
only and applies an in-process liveness sweep (`process.kill(pid, 0)` +
heartbeat freshness ≤ 60 s) before returning.
- No Forgeplan invocation, no network call, no host filesystem mutation.
The only side-effect is a process-local in-memory cache (2 s TTL, single
inflight promise) inside
`template/src/shared/server/registry.ts#readInstances`.
- Response shape mirrors the standard envelope: `{ ok, data: { instances },
cmd: "registry:read", error? }`. `instances` MUST conform to the
SPEC-003 v1 row shape (id / host / port / pid / scope / workspaceRoot /
projectName / startedAt / heartbeatAt / webVersion / forgeplanCli);
malformed rows are silently dropped from the live view.
- Errors (file read, JSON parse) MUST fall back to `{ ok: false, error,
data: { instances: [] } }` — never throw.

Any additional non-forgeplan endpoint (whether it hits npm, GitHub,
crates.io, the local filesystem outside the registry, or anything else)
requires a new Forgeplan artifact and a fresh amendment to this rule.

## Forbidden `forgeplan` subcommands from any `/api/*` endpoint

Any subcommand that mutates the workspace:
Expand Down Expand Up @@ -97,3 +131,8 @@ browser invalidates that.
- `grep -RIn "fetch(" template/src/routes/api/` must show external URLs
only inside `update-check/+server.ts`, and the URL must appear as a
string literal (`https://registry.npmjs.org/@forgeplan/web/latest`).
- `template/src/routes/api/instances/+server.ts` MUST NOT contain any
`spawn`, `execFile`, `writeFileSync`, `renameSync`, or `mkdirSync`
call (read-only constraint above). The reader
`template/src/shared/server/registry.ts` MAY only call
`existsSync` + `readFileSync` against `~/.forgeplan-web/instances.json`.
118 changes: 80 additions & 38 deletions .claude/rules/23-bin-zero-deps.md
Original file line number Diff line number Diff line change
@@ -1,31 +1,50 @@
# `bin/` zero runtime dependencies
# `bin/` near-zero runtime dependencies (amended by ADR-003)

`bin/forgeplan-web.mjs` is invoked by `npx @forgeplan/web init` and
`npx @forgeplan/web start`. The bin script itself MUST run with Node
built-ins only — it does its job (copy `dist/` into `.forgeplan-web/`,
spawn `node .forgeplan-web/index.js`) without needing any third-party
import.
`bin/forgeplan-web.mjs` is invoked by `npx @forgeplan/web init`,
`npx @forgeplan/web update`, and `npx @forgeplan/web start`. The bin
script does its job (copy `dist/` into `.forgeplan-web/`, spawn
`node .forgeplan-web/index.js`) with Node built-ins plus exactly **one**
allow-listed CLI library: `citty` (per ADR-003).

## Allowed in `bin/`
ADR-003 amended the historical "zero-dep" rule to a **named-allowlist**
rule: `citty` (and any of its transitive deps) is the **only** named
exception. Adding any other third-party import to `bin/` requires a new
ADR — not an amendment to this one.

## Allowed in `bin/` (amended by ADR-003)

- `node:*` modules (`node:fs`, `node:child_process`, `node:path`,
`node:url`, `node:os`, `node:crypto`, `node:util`).
- Relative imports of sibling `.mjs` files **inside `bin/`** (e.g.
`import { … } from "./banner.mjs"`). These are first-party code that
ships in the `bin/` folder of the published tarball; they introduce
no third-party resolution at `npx` time. Each such sibling file is
itself bound by this rule (zero `node_modules/` imports, `node:*`-only).
- Relative imports of sibling `.mjs` files inside `bin/` (e.g.
`import { … } from "./banner.mjs"`, `from "./lib/config.mjs"`,
`from "./commands/init.mjs"`). These are first-party code that ships
in the `bin/` folder of the published tarball; they introduce no
third-party resolution at `npx` time. Each such sibling file is
itself bound by this rule (`node:*` + `citty` only, plus relative
siblings).
- **`citty`** — CLI framework providing `defineCommand`, `runMain`,
`parseArgs`, typed args, auto-help, and subcommand routing. Pinned
to `^0.2.2` (caret-minor). Bumping major/minor requires re-evaluating
ADR-003. As of `citty@0.2.2` the package has zero runtime
`dependencies` (it bundles its own helpers and uses
`node:util.parseArgs`); should a future version reintroduce
transitive deps, those are covered by this rule too as long as they
are pulled by `citty` and not declared at the root.
- Synchronous I/O (`mkdirSync`, `cpSync`, …) — the script is short and
CLI-bound; readability beats event-loop nicety.

## Forbidden in `bin/`

- Any `import` from a third-party package.
- Any `require()` from `node_modules/` at the package root.
- Spawning `node_modules/.bin/*` binaries from the package root (root
has no `node_modules`).
- Adding entries to the root `package.json#dependencies` to support the
bin script.
- Any third-party import OTHER than `citty` (and any transitive deps
it pulls). E.g. `chalk`, `commander`, `yargs`, `figlet`, `prompts`,
`ora`, `kleur` are all forbidden. If you think one is needed, open a
new ADR.
- Any `require()` from `node_modules/` at the package root that is not
resolved through citty.
- Spawning `node_modules/.bin/*` binaries from the package root.
- Adding any other entry to root `package.json#dependencies` to support
the bin script. Currently allowed: `{ "citty": "^0.2.2" }` — and
nothing else.

## Note on `dist/` and `dist-experimental/`

Expand All @@ -43,8 +62,8 @@ The published tarball ships **two** pre-built artifacts (PRD-014 / RFC-013):

In both cases the bin script only `spawn()`s `node` against the
artifact's `index.js` — it never imports anything from the artifact's
internals. This rule is about the bin script itself staying zero-dep;
the artifacts are governed by rule 21.
internals. This rule is about the bin script itself staying bound to
the citty + node:* allow-list; the artifacts are governed by rule 21.

After the bundled shape graduates from `--experimental` (see
`TODO(rfc-013-graduation)` in `bin/forgeplan-web.mjs` and
Expand All @@ -53,10 +72,13 @@ tarball and this section will collapse to one paragraph.

## Required

- The root `package.json` must keep `dependencies` empty (or absent). It
may have `devDependencies` for repo tooling (currently: `esbuild` for
building `dist-experimental/`). The published tarball ships `bin/`
(zero-dep), `dist/` (with its own `node_modules/`),
- The root `package.json` must keep `dependencies` to **exactly** the
citty entry: `{ "citty": "^0.2.2" }` (caret-minor pin per ADR-003).
No other runtime deps allowed at the root. `devDependencies` for
repo tooling are unconstrained by this rule (currently: `esbuild`).
- The published tarball ships `bin/` (incl. `bin/cli.mjs`,
`bin/commands/*.mjs`, `bin/lib/*.mjs`, `bin/banner.mjs`,
`bin/forgeplan-web.mjs`), `dist/` (with its own `node_modules/`),
`dist-experimental/` (single bundle, no `node_modules/`), and
`README.md`.
- `package.json#engines` pins Node ≥ `^20.19.0 || >=22.12.0`. Any change
Expand All @@ -67,31 +89,51 @@ tarball and this section will collapse to one paragraph.
`npx @forgeplan/web init` is the user's first contact with the package.
The package itself is pre-built — `init` is a `cp -r` of `dist/` into
`.forgeplan-web/`, and `start` is a `spawn(node, dist/index.js)`. The bin
must not pull in third-party code that npm would have to resolve before
invocation; doing so would re-introduce the exact latency we removed by
shipping a pre-built artifact.
must not pull in arbitrary third-party code that npm would have to
resolve before invocation; doing so would re-introduce the exact latency
we removed by shipping a pre-built artifact. The citty exception is
ADR-003's deliberate trade-off: ~5KB / ~50ms for subcommand routing,
typed args, auto-help, and a future prompt hook (#111).

## Verification

```bash
# bin/* must only import node:* modules or relative sibling .mjs files.
# Allowed: from 'node:fs', from "./banner.mjs", from "../bin/x.mjs"
# Forbidden: from 'chalk', from 'figlet', from any bare specifier.
# bin/* must only import node:* modules, citty, or relative sibling .mjs files.
# Allowed: from 'node:fs', from 'citty', from "./banner.mjs",
# from "./lib/config.mjs", from "./commands/init.mjs"
# Forbidden: from 'chalk', from 'commander', from any other bare specifier.
# Also handles multi-line `import { … } from "node:fs";` because we match
# the `from "…"` line itself, regardless of where the `import` keyword sits.
for f in bin/*.mjs; do
fail=0
for f in $(find bin -name '*.mjs' -type f); do
hits=$(grep -E "(from|require\()\s*['\"]" "$f" \
| grep -vE "(from|require\()\s*['\"]node:" \
| grep -vE "(from|require\()\s*['\"](node:|citty['\"])" \
| grep -vE "(from|require\()\s*['\"]\\.{1,2}/" || true)
if [ -z "$hits" ]; then
echo "OK ($f): no third-party deps"
echo "OK ($f): bin allow-list (node:*, citty, relative)"
else
echo "FAIL ($f): third-party imports found:"
echo "FAIL ($f): non-allow-listed imports found:"
echo "$hits"
exit 1
fail=1
fi
done

# root package must not declare runtime deps
node -e "const p=require('./package.json'); if (p.dependencies && Object.keys(p.dependencies).length) { console.error('FAIL: runtime deps present', p.dependencies); process.exit(1)} else { console.log('OK: no runtime deps') }"
[ "$fail" -eq 0 ] || exit 1

# root package may declare ONLY citty as runtime dep
node -e "
const p = require('./package.json');
const deps = p.dependencies || {};
const keys = Object.keys(deps).sort();
const allowed = ['citty'];
const extra = keys.filter((k) => !allowed.includes(k));
if (extra.length) {
console.error('FAIL: unexpected runtime deps', extra);
process.exit(1);
}
if (!deps.citty) {
console.error('FAIL: citty missing from dependencies (ADR-003 invariant I3)');
process.exit(1);
}
console.log('OK: root deps = { citty:', deps.citty, '}');
"
```
Loading
Loading