Skip to content

See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.

Blueprints: fixes from a first real run on a PRD

Hayden Smithf6895acbe4af
diff --git a/skills/floorplan/SKILL.md b/skills/floorplan/SKILL.md
index 59f0b77..f240ddf 100644
--- a/skills/floorplan/SKILL.md
+++ b/skills/floorplan/SKILL.md
@@ -26,10 +26,10 @@ If the user wants to plan something they haven't built ("here's my PRD", "I want
1. **Read the input.** A PRD file, a pasted message, or a document they point you at. Ask 2–3 questions only if something fundamental is open (who uses it, web or mobile, does anyone sign in, does money change hands); otherwise decide and record it as an assumption.
2. **Read [references/blueprint.md](references/blueprint.md)**, then [references/schema.md](references/schema.md) for architecture.json.
3. **Write `floorplan/plan.json`**: every planned file and endpoint, what each screen calls, which outside services and data each part uses, who may use each endpoint, your assumptions and the open questions. If the PRD is only in the chat, save it as `docs/prd.md` and use that as `source`, so the map and later questions can refer back to it.
-4. **Run `node ${CLAUDE_SKILL_DIR}/scripts/plan.mjs <root>`.** Fix what it reports and run it again until it's clean.
-5. **Write `floorplan/architecture.json`** as for a code map (parts, external nodes, 1–3 flows for the PRD's main user stories, a tour), with globs covering the planned paths. Plain language for everyone, as in step 4 below.
-6. **Run build.mjs** (step 5 below), then **show it** with open.mjs (step 8). Skip describe.mjs and recent.mjs: names and descriptions come from plan.json.
-7. **Report:** the shape of the system in 3–5 lines, the stack you chose, your main assumptions, and the design review's questions and warnings. Tell them each part has **Build this with Claude** (or Codex) for a ready request to build just that part, and that they can ask you to change the plan.
+4. **Write `floorplan/architecture.json`** as for a code map (parts, external nodes for the services and data plan.json names, 1–3 flows for the PRD's main user stories, a tour), with globs covering the planned paths. Plain language for everyone, as in step 4 below.
+5. **Run `node ${CLAUDE_SKILL_DIR}/scripts/plan.mjs <root>`, then build.mjs** (step 5 below). Fix what they report until both are clean. Skip describe.mjs and recent.mjs: names and descriptions come from plan.json. A blueprint adds no notes to CLAUDE.local.md, since there's no code to look up yet.
+6. **Show it** with open.mjs (step 8).
+7. **Report** (instead of step 8's report): the URL; the shape of the system in 3–5 lines; the stack you chose; your main assumptions; and the design review's questions and warnings. Tell them each part has **Build this with Claude** (or Codex) for a ready request to build just that part, that plan.json and architecture.json are theirs to edit or to ask you to change, and that the map stays out of git.
To change a blueprint, edit plan.json and architecture.json and run `refresh.mjs`, which redraws it from plan.json. Once the code exists and the user wants a map of it, run `refresh.mjs <root> --from-code`, then carry on as for a refresh. plan.json stays where it is.
diff --git a/skills/floorplan/assets/ui/06-blueprint.js b/skills/floorplan/assets/ui/06-blueprint.js
index 56b544d..1c29414 100644
--- a/skills/floorplan/assets/ui/06-blueprint.js
+++ b/skills/floorplan/assets/ui/06-blueprint.js
@@ -7,6 +7,7 @@
const BP = SC && SC.graph.meta.blueprint;
if (!BP) return;
const { h } = SC;
+ const Cap = (t) => t[0].toUpperCase() + t.slice(1);
const A = SC.agent || { name: 'Claude', app: 'Claude Code' };
const G = SC.graph;
@@ -30,7 +31,10 @@
SC.on('render', addPill);
SC.on('ready', addPill);
- const ACCESS = { public: 'anyone', 'signed-in': 'signed-in users', staff: 'staff', webhook: 'the service that sends it, which must prove it', internal: 'only our own services' };
+ const ACCESS = { public: 'anyone', 'signed-in': 'signed-in users', team: 'only the team that runs the service', webhook: 'the service that sends it, which must prove it', internal: 'only our own services' };
+ /** "for signed-in users: managers of that location", or the open question when nobody decided. */
+ const whoMay = (r) => !r.access ? 'who may use it isn’t decided yet: ask me'
+ : `for ${r.access === 'signed-in' && r.who ? r.who : ACCESS[r.access] || r.access}${r.publicBecause ? `, because ${r.publicBecause.replace(/\.$/, '')}` : ''}`;
SC.addPanelSection('overview', () => ({
html: `<div class="sec"><h3>Blueprint</h3>
@@ -63,7 +67,7 @@
`\nFiles to create:`,
...fl.map((f) => `- ${f.p}: ${f.name}${f.d ? `. ${f.d}` : ''}`),
eps.length ? `\nEndpoints to create (keep the method, path and who may use them exactly as planned):` : '',
- ...eps.map((r) => `- ${r.m} ${r.p} (${r.access ? `for ${ACCESS[r.access] || r.access}` : 'who may use it isn’t decided yet: ask me'}): ${r.name}${r.d ? `. ${r.d}` : ''}`),
+ ...eps.map((r) => `- ${r.m} ${r.p} (${whoMay(r)}): ${r.name}${r.d ? `. ${r.d}` : ''}`),
deps.size ? `\nIt relies on: ${[...deps.values()].join('; ')}.` : '',
questions.length ? `\nStill undecided (ask me before building what depends on it):\n${questions.map((q) => `- ${q}`).join('\n')}` : '',
`\nBefore writing code, read these parts of plan.json, and check which of the things it relies on exist yet; if some don't, tell me and suggest what to build first. Keep the plan's file paths and names. If the plan looks wrong or incomplete for this part, tell me before changing it. When it's done, run it or its tests and tell me how to try it.`,
@@ -72,6 +76,13 @@
SC.addPanelSection('item', (id) => {
if (!id || typeof id !== 'string') return '';
+ // an endpoint: who the plan lets use it
+ if (id.startsWith('r:')) {
+ const r = SC.routes[+id.slice(2)];
+ if (!r) return '';
+ const text = !r.access ? 'Not decided yet. The design review lists it.' : `${Cap(r.access === 'signed-in' && r.who ? r.who : ACCESS[r.access] || r.access)}.${r.publicBecause ? ` Open on purpose: ${r.publicBecause}` : ''}`;
+ return `<div class="sec"><h3>Who may use it</h3><p class="pd">${h(text)}</p></div>`;
+ }
const i = SC.info(id);
if (!i || (i.type === 'node' && i.n.kind === 'external') || !filesIn(id).length) return '';
return {
diff --git a/skills/floorplan/references/blueprint.md b/skills/floorplan/references/blueprint.md
index f29d727..298ae3d 100644
--- a/skills/floorplan/references/blueprint.md
+++ b/skills/floorplan/references/blueprint.md
@@ -12,12 +12,12 @@ Contents: [Planning well](#planning-well) · [plan.json](#planjson) · [Checks](
## Planning well
-- **Plan to the level of files and endpoints**, not just boxes. Screens, the design review and the build prompts all depend on it. A small product is typically 15–60 files and 10–40 endpoints. Don't plan every helper: one file per page, per group of endpoints, per outside service and per kind of saved data is about right.
+- **Plan to the level of files and endpoints**, not just boxes. Screens, the design review and the build prompts all depend on it. A small product is typically 15–60 files and 10–40 endpoints. Don't plan every helper: one file per page, per group of endpoints, per outside service and per kind of saved data is about right. Where the stack puts one handler per URL (Next.js `route.ts`, SvelteKit `+server.ts`), plan it that way; more files is fine.
- **Pick a sensible, common stack** unless the PRD names one, and list it in `stack`. Prefer what a solo builder working with AI would choose: a Next.js or React website, a Node or Python server, Postgres, Stripe, a hosted email service. Use real, conventional paths for that stack (`web/app/checkout/page.tsx`, `api/src/routes/orders.ts`).
- **Every screen the PRD describes is a file with a `screen` URL.** Give each screen `calls` for the endpoints it uses and `uses` for the parts it's built from.
-- **Every endpoint gets `access`.** Decide it from the PRD. If the PRD is silent and it matters, leave it out (the review will flag it) or add a question.
-- **Don't invent requirements.** Where the PRD doesn't say and you had to choose, write the choice in `assumptions`. Where the answer changes what gets built and you can't reasonably choose, add it to `questions` with the parts it affects. Ask the user 2–3 questions up front only if the PRD leaves something fundamental open (who uses it, web or mobile, does anyone sign in, does money change hands).
-- **Outside services and data stores are `external` nodes** in architecture.json (Stripe, the database, an email service). Files reach them through `services` and `data` in plan.json.
+- **Every endpoint gets `access`**, and `who` when only some signed-in people may use it ("managers of that location", "the account owner"). Decide it from the PRD. If the PRD is silent and it matters, leave it out (the review will flag it) or add a question. An endpoint that must be open to anyone and changes data (sign-in codes, sign-up, guest checkout) gets `publicBecause`: why, and what stops abuse.
+- **Don't invent requirements.** Where the PRD doesn't say and you had to choose, write the choice in `assumptions`. Where the answer changes what gets built and you can't reasonably choose, add it to `questions` with the parts it affects. Carry every open question the PRD lists into `questions` unless the PRD settles it elsewhere; if you planned around the likely answer, say so in `assumptions` too. Ask the user 2–3 questions up front only if the PRD leaves something fundamental open (who uses it, web or mobile, does anyone sign in, does money change hands).
+- **Outside services and data stores are `external` nodes** in architecture.json (Stripe, the database, an email service). Files reach them through `services` and `data` in plan.json. Put `data` on the files that talk to the database directly (a database helper, or each data-access file), not on every file that uses them: Screens follow `uses` down to them.
- **Background work** (scheduled emails, nightly jobs, queue workers) gets its own files and a `worker` node.
## plan.json
@@ -63,13 +63,17 @@ Contents: [Planning well](#planning-well) · [plan.json](#planjson) · [Checks](
| `path` | the URL, starting with `/`. Use `:name` for parts that change (`/api/orders/:id`) |
| `file` | the planned file that handles it. Required |
| `name`, `description` | as for files |
-| `access` | who may use it: `public` (anyone), `signed-in`, `staff`, `webhook` (another company's service, which must prove it's them) or `internal` (only your own services) |
+| `access` | who may use it: `public` (anyone), `signed-in`, `team` (only the people who run the service, for its own admin pages, not the app's users), `webhook` (another company's service, which must prove it's them) or `internal` (only your own services) |
+| `who` | with `signed-in`: which signed-in people, in a few words ("managers of that location", "the account owner"). Leave it out when any signed-in user may |
+| `publicBecause` | with `public`: why it has to be open, and what limits abuse ("sign-in has to work before anyone is signed in; 5 codes per number per hour"). The design review stops flagging an open endpoint that has one |
-Node `paths` globs in architecture.json assign planned files to parts, the same as for code. Aim for no unassigned files.
+Node `paths` globs in architecture.json assign planned files to parts, the same as for code. Aim for no unassigned files. Folder names in brackets (`app/orders/[id]/**`) match literally.
+
+plan.mjs's "calls to planned endpoints" counts each call; the build's "http" links count each caller-to-file connection plus links to outside services, so the two numbers differ.
## What the design review checks
-- endpoints that change data and are open to anyone (worth a second look, though sign-up and guest checkout are legitimate);
+- endpoints that change data and are open to anyone, unless `publicBecause` explains why;
- endpoints with no `access` decided;
- every open question, pointing at the parts it affects;
- endpoints no planned screen or service calls;
diff --git a/skills/floorplan/references/schema.md b/skills/floorplan/references/schema.md
index 9fdafb7..a9d9abc 100644
--- a/skills/floorplan/references/schema.md
+++ b/skills/floorplan/references/schema.md
@@ -52,6 +52,7 @@ Kinds, briefly:
### Glob syntax
- `**` matches any number of directories, `*` stays within one path segment, `?` matches one character, `{a,b}` is alternation.
+- A whole folder name in brackets, like `[id]`, `[...slug]` or `[[...slug]]` (Next.js, SvelteKit), matches that folder literally: `app/orders/[id]/**`. Elsewhere, `[abc]` matches one of those characters.
- A pattern with no wildcard also matches as a directory: `backend/app` equals `backend/app/**`.
- Paths are relative to the codebase root. In a multi-repo root they start with the repo folder.
diff --git a/skills/floorplan/scripts/build.mjs b/skills/floorplan/scripts/build.mjs
index 0c1a78b..c423777 100644
--- a/skills/floorplan/scripts/build.mjs
+++ b/skills/floorplan/scripts/build.mjs
@@ -339,7 +339,7 @@ for (const f of included) {
const pct = included.length ? (unassigned.length / included.length) * 100 : 0;
const report = [];
if (errors.length) {
- report.push(`✗ ${errors.length} error(s) in ${path.relative(root, archFile)}:`);
+ report.push(`✗ ${errors.length} error(s) in ${path.relative(root, archFile)}${scan.blueprint ? ' or plan.json' : ''}:`);
for (const e of errors) report.push(` - ${e}`);
}
if (warnings.length) {
@@ -405,7 +405,7 @@ const graph = {
}),
routes: routesIn.map((r) => {
const d = routeDesc.get(routeKey(r));
- return { f: r.file, m: r.method, p: r.path, l: r.line, h: r.handler || null, name: d?.name || r.name || fallbackRouteName(r), d: d?.d || r.desc || r.doc || '', ...(d?.d || r.desc ? {} : { auto: true }), ...(d?.review ? { review: d.review } : {}), ...(r.doc ? { doc: r.doc } : {}), ...(r.access ? { access: r.access } : {}) };
+ return { f: r.file, m: r.method, p: r.path, l: r.line, h: r.handler || null, name: d?.name || r.name || fallbackRouteName(r), d: d?.d || r.desc || r.doc || '', ...(d?.d || r.desc ? {} : { auto: true }), ...(d?.review ? { review: d.review } : {}), ...(r.doc ? { doc: r.doc } : {}), ...(r.access ? { access: r.access } : {}), ...(r.who ? { who: r.who } : {}), ...(r.publicBecause ? { publicBecause: r.publicBecause } : {}) };
}),
links: [...links.values()],
flows: outFlows,
diff --git a/skills/floorplan/scripts/lib/blueprint.mjs b/skills/floorplan/scripts/lib/blueprint.mjs
index 83c0f23..bd3aeb5 100644
--- a/skills/floorplan/scripts/lib/blueprint.mjs
+++ b/skills/floorplan/scripts/lib/blueprint.mjs
@@ -11,7 +11,8 @@ import path from 'node:path';
import { classify, toPosix } from './common.mjs';
import { matchCalls } from './routes.mjs';
-export const ACCESS = ['public', 'signed-in', 'staff', 'webhook', 'internal'];
+// who may use an endpoint. "team" is the people who run the service (its own admin pages), not the app's users.
+export const ACCESS = ['public', 'signed-in', 'team', 'webhook', 'internal'];
const METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'CALL', 'ANY'];
const WRITE = new Set(['POST', 'PUT', 'PATCH', 'DELETE', 'CALL']);
const isStr = (v) => typeof v === 'string' && v.trim().length > 0;
@@ -58,9 +59,11 @@ export function planToScan(plan, root) {
const key = routeKey(method, e.path);
if (seen.has(key)) return err(`${where} duplicates an earlier endpoint`);
seen.add(key);
- if (e.access !== undefined && !ACCESS.includes(e.access)) err(`${where}.access "${e.access}" must be one of ${ACCESS.join(', ')}`);
+ if (e.access !== undefined && !ACCESS.includes(e.access)) err(`${where}.access "${e.access}" must be one of ${ACCESS.join(', ')}${e.access === 'staff' ? ' ("team" is your own team; for some of the app’s users, use "signed-in" with "who")' : ''}`);
+ if (e.who !== undefined && !isStr(e.who)) err(`${where}.who must be a few words, e.g. "managers of that location"`);
+ if (e.publicBecause !== undefined && !isStr(e.publicBecause)) err(`${where}.publicBecause must say why it is open to anyone`);
if (ACCESS.includes(e.access)) access[key] = e.access;
- routes.push({ file, method, path: e.path, line: 0, ...(ACCESS.includes(e.access) ? { access: e.access } : {}), ...(isStr(e.name) ? { name: e.name.trim() } : {}), ...(isStr(e.description) ? { desc: e.description.trim() } : {}) });
+ routes.push({ file, method, path: e.path, line: 0, ...(ACCESS.includes(e.access) ? { access: e.access } : {}), ...(isStr(e.who) ? { who: e.who.trim() } : {}), ...(isStr(e.publicBecause) ? { publicBecause: e.publicBecause.trim() } : {}), ...(isStr(e.name) ? { name: e.name.trim() } : {}), ...(isStr(e.description) ? { desc: e.description.trim() } : {}) });
});
const routeKeys = new Set(routes.map((r) => routeKey(r.method, r.path)));
@@ -147,7 +150,8 @@ export function buildPlanHealth({ graph, scan }) {
// ---------- who may call each endpoint ----------
const accessOf = (r) => bp.access?.[routeKey(r.m, r.p)];
- const openWrites = routes.map((r, i) => ({ r, i })).filter(({ r }) => accessOf(r) === 'public' && WRITE.has(r.m));
+ // open on purpose, with a reason (publicBecause), counts as reviewed
+ const openWrites = routes.map((r, i) => ({ r, i })).filter(({ r }) => accessOf(r) === 'public' && WRITE.has(r.m) && !r.publicBecause);
if (openWrites.length) issues.push({
id: 'plan-open-writes', kind: 'unprotected-endpoint', severity: 'medium',
title: openWrites.length === 1 ? 'Anyone could change data through one planned endpoint' : `Anyone could change data through ${openWrites.length} planned endpoints`,
@@ -155,17 +159,17 @@ export function buildPlanHealth({ graph, scan }) {
items: openWrites.slice(0, 24).map(({ i }) => 'r:' + i),
notes: Object.fromEntries(openWrites.slice(0, 24).map(({ i }) => ['r:' + i, 'Planned as open to anyone, and changes data'])),
locations: [],
- fix: [`Design review of floorplan/plan.json: these planned endpoints change data and are marked "access": "public":`, ...openWrites.map(({ r }) => line(r)), ``, `For each one, tell me in plain words whether a stranger should really be able to use it. Where they shouldn't, change its access to "signed-in" or "staff" in plan.json. Where it must stay public (sign-up, guest checkout), add a note on what limits abuse (rate limits, a CAPTCHA, email confirmation) to the endpoint's description. Ask me if you're unsure.`, rebuild].join('\n'),
+ fix: [`Design review of floorplan/plan.json: these planned endpoints change data and are marked "access": "public":`, ...openWrites.map(({ r }) => line(r)), ``, `For each one, tell me in plain words whether a stranger should really be able to use it. Where they shouldn't, change its access to "signed-in" (with "who" if only some users may) in plan.json. Where it must stay public (sign-in, sign-up, guest checkout), set "publicBecause" to why, including what limits abuse (rate limits, a CAPTCHA, email confirmation). Ask me if you're unsure.`, rebuild].join('\n'),
});
const unknown = routes.map((r, i) => ({ r, i })).filter(({ r }) => !accessOf(r));
if (unknown.length) issues.push({
id: 'plan-no-access', kind: 'unprotected-endpoint', severity: 'medium',
title: unknown.length === 1 ? 'The plan doesn’t say who may use one endpoint' : `The plan doesn’t say who may use ${unknown.length} endpoints`,
- detail: `Deciding who can use each part of the system now (anyone, signed-in customers, staff, another service) is much easier than adding sign-in checks after it's built.`,
+ detail: `Deciding who can use each part of the system now (anyone, signed-in customers, only managers, your own team, another service) is much easier than adding sign-in checks after it's built.`,
items: unknown.slice(0, 24).map(({ i }) => 'r:' + i),
notes: Object.fromEntries(unknown.slice(0, 24).map(({ i }) => ['r:' + i, 'Who may use this isn’t decided'])),
locations: [],
- fix: [`Design review of floorplan/plan.json: these planned endpoints have no "access" set:`, ...unknown.map(({ r }) => line(r)), ``, `For each, choose who may use it: "public" (anyone), "signed-in", "staff", "webhook" (another company's service, which must prove it's them) or "internal" (only our own services). Base it on the PRD; ask me where the PRD doesn't say.`, rebuild].join('\n'),
+ fix: [`Design review of floorplan/plan.json: these planned endpoints have no "access" set:`, ...unknown.map(({ r }) => line(r)), ``, `For each, choose who may use it: "public" (anyone), "signed-in" (plus "who" when only some users may, such as "managers of that location"), "team" (only the people who run the service), "webhook" (another company's service, which must prove it's them) or "internal" (only our own services). Base it on the PRD; ask me where the PRD doesn't say.`, rebuild].join('\n'),
});
// ---------- open questions from the PRD ----------
diff --git a/skills/floorplan/scripts/lib/common.mjs b/skills/floorplan/scripts/lib/common.mjs
index 72c40e6..b68994e 100644
--- a/skills/floorplan/scripts/lib/common.mjs
+++ b/skills/floorplan/scripts/lib/common.mjs
@@ -33,6 +33,12 @@ export function globToRegExp(glob) {
if (c === '{') { braces++; re += '(?:'; i++; continue; }
if (c === '}' && braces) { braces--; re += ')'; i++; continue; }
if (c === ',' && braces) { re += '|'; i++; continue; }
+ // a whole segment like [id], [...slug] or [[...slug]] is a folder name (Next.js, SvelteKit), not a character class
+ if (c === '[' && (i === 0 || g[i - 1] === '/')) {
+ const end = g.indexOf('/', i) < 0 ? g.length : g.indexOf('/', i);
+ const seg = g.slice(i, end);
+ if (/^\[\[?(\.\.\.)?[A-Za-z_$][\w$-]*\]\]?$/.test(seg)) { re += seg.replace(/[.[\]$]/g, '\\$&'); i = end; continue; }
+ }
if (c === '[') {
const j = g.indexOf(']', i + 1);
if (j > i) { re += '[' + g.slice(i + 1, j).replace(/^!/, '^').replace(/\\/g, '\\\\') + ']'; i = j + 1; continue; }
@@ -94,7 +100,7 @@ export const HARD_IGNORE_DIRS = new Set([
export const MAP_DIR = 'floorplan';
export const LEGACY_MAP_DIR = 'show-code';
/** True for a folder holding a map, so a project's own folder that happens to be called "floorplan" isn't taken for one. */
-export const isMapDir = (d) => ['architecture.json', 'graph.json', '.cache'].some((f) => fs.existsSync(path.join(d, f)));
+export const isMapDir = (d) => ['architecture.json', 'plan.json', 'graph.json', '.cache'].some((f) => fs.existsSync(path.join(d, f)));
/**
* Keeps the map folder out of git: its own .gitignore ignores everything in it, itself included, so
* nothing in the project's tracked files changes. Returns a warning when git already tracks files
diff --git a/skills/floorplan/scripts/plan.mjs b/skills/floorplan/scripts/plan.mjs
index 2b0c87b..a35600a 100644
--- a/skills/floorplan/scripts/plan.mjs
+++ b/skills/floorplan/scripts/plan.mjs
@@ -22,6 +22,16 @@ let plan;
try { plan = JSON.parse(fs.readFileSync(planFile, 'utf8')); } catch (e) { fail(`plan.json is not valid JSON: ${e.message}`); }
const { scan, errors, warnings } = planToScan(plan, root);
+// "services" and "data" name nodes in architecture.json: check them now if it's written
+const archFile = path.join(outDir, 'architecture.json');
+if (scan && fs.existsSync(archFile)) {
+ let ids = null;
+ try { ids = (JSON.parse(fs.readFileSync(archFile, 'utf8')).nodes || []).map((n) => n?.id).filter(Boolean); } catch {}
+ if (ids) for (const l of scan.nodeLinks) if (!ids.includes(l.to)) {
+ const near = ids.find((id) => id.toLowerCase().startsWith(l.to.toLowerCase().slice(0, 3)));
+ errors.push(`files "${l.from}".${l.kind === 'data' ? 'data' : 'services'} "${l.to}" is not a node id in architecture.json${near ? ` (did you mean "${near}"?)` : ''}`);
+ }
+}
const out = [];
if (errors.length) { out.push(`✗ ${errors.length} error(s) in ${toPosix(path.relative(root, planFile))}:`); for (const e of errors) out.push(` - ${e}`); }
if (warnings.length) { out.push(`! ${warnings.length} warning(s):`); for (const w of warnings.slice(0, 40)) out.push(` - ${w}`); }
@@ -35,11 +45,11 @@ const bp = scan.blueprint;
const byDir = new Map();
for (const f of scan.files) { const d = f.path.split('/').slice(0, -1).slice(0, 2).join('/') || '.'; byDir.set(d, (byDir.get(d) || 0) + 1); }
if (out.length) out.push('');
-out.push(`BLUEPRINT ${scan.files.length} planned files · ${scan.routes.length} endpoints · ${scan.http.length} calls matched · ${scan.nodeLinks.length} links to services and data`);
+out.push(`BLUEPRINT ${scan.files.length} planned files · ${scan.routes.length} endpoints · ${scan.http.length} calls to planned endpoints · ${scan.nodeLinks.length} links to services and data`);
for (const [d, n] of [...byDir].sort((a, b) => b[1] - a[1]).slice(0, 15)) out.push(` ${String(n).padStart(4)} ${d}/`);
const screens = scan.files.filter((f) => f.screens).length;
if (screens) out.push(`SCREENS ${screens} planned`);
if (bp.questions.length) out.push(`OPEN QUESTIONS ${bp.questions.length} (shown in Health until answered)`);
out.push('');
-out.push(`✓ wrote ${toPosix(path.relative(root, outFile))}. Next: write or update floorplan/architecture.json, then run build.mjs.`);
+out.push(`✓ wrote ${toPosix(path.relative(root, outFile))}. Next: run build.mjs${fs.existsSync(archFile) ? '' : ' once floorplan/architecture.json is written'}.`);
console.log(out.join('\n'));
diff --git a/skills/floorplan/scripts/status.mjs b/skills/floorplan/scripts/status.mjs
index dc76ac5..c1513cd 100644
--- a/skills/floorplan/scripts/status.mjs
+++ b/skills/floorplan/scripts/status.mjs
@@ -13,7 +13,8 @@ try {
const graphFile = path.join(dir, 'graph.json');
const hasArch = fs.existsSync(path.join(dir, 'architecture.json'));
if (!fs.existsSync(graphFile)) {
- console.log(hasArch ? 'architecture.json exists but was never built: run build.mjs.' : 'none: no floorplan here yet (fresh run).');
+ const hasPlan = fs.existsSync(path.join(dir, 'plan.json'));
+ console.log(hasPlan ? 'a blueprint was started (plan.json) but never drawn: write architecture.json if it is missing, then run plan.mjs and build.mjs.' : hasArch ? 'architecture.json exists but was never built: run build.mjs.' : 'none: no floorplan here yet (fresh run).');
process.exit(0);
}
const g = JSON.parse(fs.readFileSync(graphFile, 'utf8'));
diff --git a/tests/blueprint.test.mjs b/tests/blueprint.test.mjs
index b8bda2d..9ddf3f6 100644
--- a/tests/blueprint.test.mjs
+++ b/tests/blueprint.test.mjs
@@ -30,7 +30,7 @@ function withPlan(change) {
const fails = (fn) => { try { fn(); } catch (e) { return String(e.stdout || '') + String(e.stderr || ''); } assert.fail('expected the script to fail'); };
test('the planned files and endpoints are on the map, named as the plan names them', () => {
- assert.match(planOut, /BLUEPRINT {2}21 planned files · 11 endpoints · 9 calls matched · 5 links to services and data/);
+ assert.match(planOut, /BLUEPRINT {2}21 planned files · 11 endpoints · 9 calls to planned endpoints · 5 links to services and data/);
assert.equal(graph.files.length, 21);
assert.equal(graph.files.filter((f) => f.auto).length, 0, 'every file is described');
assert.equal(graph.routes.length, 11);
@@ -66,14 +66,15 @@ test('Health is a design review of the plan', () => {
const issues = graph.health.issues;
const titles = issues.map((i) => `${i.severity} ${i.title}`);
assert.deepEqual(titles, [
- 'medium Anyone could change data through 2 planned endpoints',
+ 'medium Anyone could change data through one planned endpoint',
'medium The plan doesn’t say who may use one endpoint',
'medium Can owners cancel a walk for free, and up to when?',
'low Nothing in the plan uses one endpoint',
'low One planned file isn’t connected to anything',
]);
const routesOf = (i) => i.items.filter((id) => id.startsWith('r:')).map((id) => `${graph.routes[+id.slice(2)].m} ${graph.routes[+id.slice(2)].p}`).sort();
- assert.deepEqual(routesOf(issues[0]), ['POST /api/auth/login', 'POST /api/auth/signup']);
+ // sign-in is open on purpose (publicBecause says why), so only sign-up is flagged
+ assert.deepEqual(routesOf(issues[0]), ['POST /api/auth/signup']);
assert.deepEqual(routesOf(issues[1]), ['DELETE /api/walkers/:id']);
assert.deepEqual(issues[2].items.sort(), ['f:web/app/bookings/page.tsx', `r:${graph.routes.findIndex((r) => r.p === '/api/bookings/:id/cancel')}`].sort());
assert.deepEqual(routesOf(issues[3]), ['DELETE /api/walkers/:id']);
@@ -91,6 +92,23 @@ test('the map page marks it as a blueprint, and Ask knows there is no code to re
assert.ok(!fs.existsSync(path.join(root, 'CLAUDE.local.md')));
});
+test('an endpoint says which signed-in people may use it', () => {
+ const r = graph.routes.find((x) => x.p === '/api/walker/schedule');
+ assert.equal(r.access, 'signed-in');
+ assert.equal(r.who, 'walkers');
+ assert.match(graph.routes.find((x) => x.p === '/api/auth/login').publicBecause, /sign in before they are signed in/);
+});
+
+test('a project holding only plan.json can be planned before architecture.json exists', () => {
+ const r = makeProject({ 'PRD.md': '# A plan' });
+ try {
+ fs.mkdirSync(path.join(r, 'floorplan'));
+ fs.copyFileSync(path.join(FIXTURE, 'floorplan', 'plan.json'), path.join(r, 'floorplan', 'plan.json'));
+ assert.match(run('status.mjs', r), /a blueprint was started \(plan\.json\) but never drawn/);
+ assert.match(run('plan.mjs', r), /run build\.mjs once floorplan\/architecture\.json is written/);
+ } finally { cleanup(r); }
+});
+
test('plan.mjs names what is wrong with a plan', () => {
const r = withPlan((p) => {
p.files[0].uses.push('web/components/WalkerCrad.tsx');
@@ -98,22 +116,31 @@ test('plan.mjs names what is wrong with a plan', () => {
p.endpoints[1].file = 'api/src/routes/walker.ts';
p.files[1].calls.push('POST /api/payments');
p.files[2].calls.push('cancel it');
+ p.endpoints[2].access = 'staff';
+ p.files.find((f) => f.services).services = ['strpe'];
});
try {
const out = fails(() => run('plan.mjs', r));
assert.match(out, /files "web\/app\/page\.tsx"\.uses "web\/components\/WalkerCrad\.tsx" is not one of the planned files/);
- assert.match(out, /access "everyone" must be one of public, signed-in, staff, webhook, internal/);
+ assert.match(out, /access "everyone" must be one of public, signed-in, team, webhook, internal/);
assert.match(out, /\.file "api\/src\/routes\/walker\.ts" is not one of the planned files/);
assert.match(out, /calls "cancel it" must look like "POST \/api\/orders"/);
assert.match(out, /calls "POST \/api\/payments" matches no planned endpoint/);
+ assert.match(out, /access "staff" must be one of .* \("team" is your own team; for some of the app’s users, use "signed-in" with "who"\)/);
+ assert.match(out, /services "strpe" is not a node id in architecture\.json \(did you mean "stripe"\?\)/);
} finally { cleanup(r); }
});
test('build.mjs catches a service that is not a node', () => {
const r = withPlan((p) => { p.files.find((f) => f.services).services = ['strpe']; });
try {
+ // plan.mjs checks this when architecture.json exists; without it, the build is the safety net
+ const arch = path.join(r, 'floorplan', 'architecture.json'), saved = fs.readFileSync(arch);
+ fs.rmSync(arch);
run('plan.mjs', r);
+ fs.writeFileSync(arch, saved);
const out = fails(() => run('build.mjs', r, '--no-claude-md'));
+ assert.match(out, /error\(s\) in floorplan.architecture\.json or plan\.json/);
assert.match(out, /names "strpe" in its services, which is not a node id in architecture\.json — did you mean "stripe"\?/);
} finally { cleanup(r); }
});
diff --git a/tests/fixtures/blueprint/floorplan/plan.json b/tests/fixtures/blueprint/floorplan/plan.json
index 96acd27..a8d732a 100644
--- a/tests/fixtures/blueprint/floorplan/plan.json
+++ b/tests/fixtures/blueprint/floorplan/plan.json
@@ -38,10 +38,10 @@
{ "method": "POST", "path": "/api/bookings", "file": "api/src/routes/bookings.ts", "name": "Book a walk", "description": "Holds the slot and starts the card payment.", "access": "signed-in" },
{ "method": "GET", "path": "/api/bookings", "file": "api/src/routes/bookings.ts", "name": "My walks", "description": "The signed-in owner's walks.", "access": "signed-in" },
{ "method": "POST", "path": "/api/bookings/:id/cancel", "file": "api/src/routes/bookings.ts", "name": "Cancel a walk", "description": "Cancels a walk and refunds it if allowed.", "access": "signed-in" },
- { "method": "POST", "path": "/api/auth/login", "file": "api/src/routes/auth.ts", "name": "Sign in", "description": "Checks the email and password.", "access": "public" },
+ { "method": "POST", "path": "/api/auth/login", "file": "api/src/routes/auth.ts", "name": "Sign in", "description": "Checks the email and password.", "access": "public", "publicBecause": "people have to sign in before they are signed in; 5 wrong tries lock the account for 15 minutes" },
{ "method": "POST", "path": "/api/auth/signup", "file": "api/src/routes/auth.ts", "name": "Create an account", "description": "Creates an owner account.", "access": "public" },
- { "method": "GET", "path": "/api/walker/schedule", "file": "api/src/routes/walks.ts", "name": "Today's walks", "description": "The signed-in walker's walks for today.", "access": "staff" },
- { "method": "POST", "path": "/api/walks/:id/complete", "file": "api/src/routes/walks.ts", "name": "Mark a walk done", "description": "Records that a walk happened.", "access": "staff" },
+ { "method": "GET", "path": "/api/walker/schedule", "file": "api/src/routes/walks.ts", "name": "Today's walks", "description": "The signed-in walker's walks for today.", "access": "signed-in", "who": "walkers" },
+ { "method": "POST", "path": "/api/walks/:id/complete", "file": "api/src/routes/walks.ts", "name": "Mark a walk done", "description": "Records that a walk happened.", "access": "signed-in", "who": "the walker doing that walk" },
{ "method": "POST", "path": "/api/webhooks/stripe", "file": "api/src/routes/webhooks.ts", "name": "Payment went through", "description": "Stripe's message that a card payment succeeded.", "access": "webhook" },
{ "method": "DELETE", "path": "/api/walkers/:id", "file": "api/src/routes/admin.ts", "name": "Remove a walker", "description": "Removes a walker who has left." }
]
diff --git a/tests/helpers-lib.test.mjs b/tests/helpers-lib.test.mjs
index 90bbdca..eec1516 100644
--- a/tests/helpers-lib.test.mjs
+++ b/tests/helpers-lib.test.mjs
@@ -20,6 +20,15 @@ test('globs: ** spans folders, * stays in one, braces and bare folders work', ()
assert.ok(g('./src/', 'src/a.ts'), 'leading ./ and trailing / are ignored');
});
+test('globs: a bracketed folder name ([id], [...slug]) is a folder, not a character class', () => {
+ const g = (glob, p) => compileGlob(glob).test(p);
+ assert.ok(g('app/orders/[id]/**', 'app/orders/[id]/page.tsx'));
+ assert.ok(!g('app/orders/[id]/**', 'app/orders/i/page.tsx'));
+ assert.ok(g('app/[...slug]', 'app/[...slug]/page.tsx'));
+ assert.ok(g('app/[[...slug]]/page.tsx', 'app/[[...slug]]/page.tsx'));
+ assert.ok(g('src/file[12].ts', 'src/file2.ts'), 'inside a name, brackets still match one character');
+});
+
test('globs: a more specific pattern scores higher', () => {
assert.ok(compileGlob('api/routes/**').specificity > compileGlob('api/**').specificity);
});