@ahmed-3m/idea2prototype 0.9.1 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.0.0
+
+First stable release. The scaffold contract — route objects, check/verify verdicts, `add`-module shapes — is frozen as-is; 1.x commits to additive changes only.
+
+- Stress: every finding of the 2026-10-20 stress test (#49–#60) triaged and resolved. Data stores that fail to parse are quarantined (`data/<name>.json.corrupt-<ts>`, original bytes preserved) instead of silently wiped; single-writer and stateless-token semantics documented in the README; `ci.yml` runs with minimal permissions; README status line pinned by CI.
+- Fix: `verify` (judge mode) discovers tests by node:test's own conventions (`*.test.{js,mjs,cjs}`, `test-*.js`, `*-test.js`/`*_test.js`, `test.js`, and everything under a `test/` dir, at any depth) — no more false PASS when failing tests live outside `tests/*.test.mjs` — and never reads or executes anything under `uploads/`, `data/`, `dist/`, `coverage/`, or `node_modules/`. The verdict header names its mode, boot-skip names the real cause, and an empty directory fails.
+- Fix: `new` validates everything before writing a single file — reserved Windows device names (CON, NUL, COM1–9, …) and a 200-char cap apply to the final directory name AND every path component that will be created; quotes/backslashes/control characters in `--name`/`--idea` die instead of poisoning the JSON manifest mid-scaffold.
+- Fix: the CLI never silently ignores input it doesn't understand — unknown flags, empty or flag-like flag values, and extra positional arguments die with the allowed list on every command; nested `new sub/proj` (missing parents created) works while an unusable parent dies with a readable message; a hung test run reports a `tests timed out` verdict on every supported Node (22's file-level runner timeout and 24's spawn-budget timeout both covered).
+- Fix: `rateLimit({...})` instances own their buckets — independently configured wrappers no longer drain one shared budget (#54).
+- Fix: the server templates answer oversize bodies with 413 before destroying the socket (up to 2× the limit drained so the 413 can be delivered; beyond that destroyed to bound the cost), turn contract-violating handler returns into clean 500s, clamp non-standard statuses, and send `null` for `[status]`-only returns. Both web and api templates are covered by live e2e tests.
+- Fix: the package identity is scoped everywhere in-repo — `package.json` is `@ahmed-3m/idea2prototype` (what the release pipeline actually publishes); `publish.yml` no longer rewrites the name at publish time; tarball/global installs and the engine's registry-pin detection agree (pinned by a consistency test).
+- CI: SHA-pinned actions upgraded to current majors (checkout v7.0.1, setup-node v7.1.0) plus weekly Dependabot bump-PRs so the pins stop rotting; nothing auto-merges.
+- Benchmark: the 10-spec paired benchmark set is complete (this release archives specs 5–6 and 8–10: quiz, pomodoro, echo chat, habit tracker, word-counter CLI; spec 7 landed in 0.9.0). Across n=10: hand-written LOC −10%…−64% on 7 of 8 build-type specs (spec 6 at parity) and generated tests 2–3× the control's (parity on spec 6), full-depth verify vs. the control's recurring boot-skip; wall-clock split honestly, with the from-scratch arm faster on several small builds. All rubrics pre-registered; all judges mechanical.
+- Tests: engine + consistency suite 46 → 69.
+
 ## 0.9.1
 
 - Fix: scaffolds made through a published install (`npx`, `npm i -g`) now pin registry coordinates in the check script (`npx -y @ahmed-3m/idea2prototype@<scaffold-version> check`) instead of an absolute path into the volatile npx cache — `npm run check` survives `npm cache clean` and runs on a second machine. Checkouts (repo clone, plugin cache) still pin the stable local engine path; the exact-version guarantee is unchanged either way. Template placeholder renamed `__IDEA2PROTOTYPE_BIN__` → `__IDEA2PROTOTYPE_CMD__` to match the broader contract.

package/README.md

@@ -15,7 +15,7 @@ Idea2Prototype check — PASS (3/3)
   boot    PASS  GET /api/health -> 200, GET / -> 200 in 45ms
 ```
 
-**Status:** v0.9.0 · actively maintained · 0.x — the check/verify contract and template shapes are stable; new capabilities arrive as `add` modules.
+**Status:** v1.0.0 · actively maintained · 1.x — the check/verify contract and template shapes are stable; new capabilities arrive as `add` modules.
 
 That verdict is the whole idea: an agent building a prototype should **never generate boilerplate it didn't need to, and never read logs it didn't need to**. The syntax step covers server code (`node --check`) and every `.js` under `public/`, recursively (parsed as both ESM and classic script — only code broken in both modes fails).
 
@@ -54,6 +54,8 @@ Idea2Prototype moves all three to deterministic code: `new` scaffolds a running,
 
 Templates: `web` (static frontend + health + auto-loading routes), `api` (JSON API + route manifest), `cli` (arg-parsed tool), `worker` (persistent job queue with retries), `library` (importable module: `createStore` + `memoAsync`). All Node >= 18.17, built-in `node:test`, zero installs — ever.
 
+**JSON stores are single-writer.** Every `data/*.json` store is an in-memory list persisted on write by ONE server process — run two servers on the same project dir and each will clobber the other's acknowledged writes on its next persist (last writer wins the whole file). A store that fails to parse on first read is never silently wiped: it is quarantined as `data/<name>.json.corrupt-<timestamp>` (the original bytes are preserved for recovery) and the process starts empty with a loud stderr note. `auth-local` sessions are stateless HMAC tokens — logout clears the browser cookie only; a copied token stays valid until it expires.
+
 ## Quickstart
 
 **Any agent or plain shell — npx straight off npmjs, no clone needed:**
@@ -111,7 +113,7 @@ The generated CRUD test then needs a session instead of anonymous POSTs — regi
 
 ## Benchmarks
 
-`benchmarks/specs.md` is a pre-registered protocol: paired 2-arm design (same agent with vs. without the harness), blind functional judges, a symmetric verifier (`i2p verify`), and hypotheses stated up front. Results land in that file as they're measured — failures included. Three specs are archived: specs 1–2 (web app, API) favor the harness (23% fewer hand-written LOC, 2× tests, zero runner-compat failures — the control's from-scratch `npm test` broke on Node 24/Windows); spec 3 (micro-CLI) is an honest loss on speed and LOC — fixed overhead dominates tiny builds — with reliability and function at parity.
+`benchmarks/specs.md` is a pre-registered protocol: paired 2-arm design (same agent with vs. without the harness), blind functional judges, a symmetric verifier (`i2p verify`), and hypotheses stated up front. Results land in that file as they're measured — failures included. Ten specs are archived. Specs 1–2 (web app, API) favor the harness (23% fewer hand-written LOC, 2× tests, zero runner-compat failures — the control's from-scratch `npm test` broke on Node 24/Windows); spec 3 (micro-CLI) is an honest loss on speed and LOC — fixed overhead dominates tiny builds — with reliability and function at parity; spec 4 (expense tracker) wrote ~43% fewer hand-written LOC with 3× tests; spec 7 (bookmarks API + tag filter) is the strongest result at ~64%. Across the set the pattern holds: hand-written LOC −10%…−64% on 7 of 8 build-type specs (spec 6 at parity), generated tests 2–3× the control's, full-depth verify against the control's recurring boot-skip — while the from-scratch arm stays faster on several small builds, recorded as such.
 
 ## Design rules
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ahmed-3m/idea2prototype",
-  "version": "0.9.1",
-  "description": "Turn ideas into tested prototypes — token-lean scaffolds + one-command verification for any coding agent. Zero dependencies.",
+  "version": "1.0.0",
+  "description": "Turn ideas into tested prototypes \u2014 token-lean scaffolds + one-command verification for any coding agent. Zero dependencies.",
   "type": "module",
   "license": "MIT",
   "author": "ahmed-3m",

package/skills/idea2prototype/SKILL.md

@@ -92,4 +92,6 @@ Then `check` — the anon-401/authed-201 contract and the rest of the CRUD suite
 - `check` exits non-zero on failure, prints at most 3 failure notes — fix those, re-run. A trailing `note` line about scaffold/engine version drift is informational, not a failure. `check --json` gives the same verdict machine-readable. `verify [dir]` runs the same verdict on any Node project (benchmark/judge mode).
 - If the user asks for dependencies (a framework, a database), ask once, then add via `npm install` and extend the tests accordingly.
 - Projects are plain Node — `npm start` (web/api), `node cli.mjs help` (cli), `import ... from './index.mjs'` (library); no other tooling assumed.
+- JSON stores (`data/*.json`) are single-writer: one server process per project dir — a second server's persist clobbers the first's acknowledged writes. A store that fails to parse on first read is quarantined (`data/<name>.json.corrupt-<ts>`, original bytes preserved) and the process starts empty with a loud stderr note — never a silent wipe.
+- `auth-local` session tokens are stateless HMAC: logout clears the browser cookie only, and a token copied before logout stays valid until it expires — production-ish apps should shorten the TTL or add a server-side revocation list (the route's docblock says the same).
 - Templates are single-purpose: no cross-template composition exists. If a task needs background jobs inside a web/api project, `add worker-jobs` brings the worker template's queue in as a feature — no need to scaffold both. Feature composition (`auth-local` × `api-crud`, `rate-limit`, `cors`, `sse` streaming, `worker-jobs`) is supported; template composition is not.

package/skills/idea2prototype/scripts/idea2prototype.mjs

@@ -18,7 +18,7 @@ import { spawnSync } from 'node:child_process';
 import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-const VERSION = '0.9.1';
+const VERSION = '1.0.0';
 const PKG_NAME = '@ahmed-3m/idea2prototype';
 const HERE = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(HERE, '..', 'templates');
@@ -49,6 +49,7 @@ async function cmdNew(rest) {
   const opts = parseFlags(rest, ['template', 'name', 'idea']);
   const dir = opts._[0];
   if (!dir) die('usage: idea2prototype new <dir> [--template web|api|cli|worker|library] [--name "..."] [--idea "..."]');
+  checkPositionalCount(opts, 1, 'new takes one directory name (new <dir>)');
 
   const template = opts.template ?? 'web';
   const templateDir = join(TEMPLATES_DIR, template);
@@ -60,10 +61,47 @@ async function cmdNew(rest) {
   if (!/^[a-z0-9][a-z0-9-_]*$/.test(slug)) {
     die(`invalid directory name "${slug}" — use letters, digits, dashes, underscores`);
   }
+  // Windows reserved device names (CON, NUL, COM1-9, ...) create directories
+  // PowerShell cannot even enter. Reject on every platform so a scaffold
+  // stays portable, not just usable where it was created.
+  const RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/;
+  if (RESERVED.test(slug)) {
+    die(`"${slug}" is a reserved Windows device name — pick a different directory name`);
+  }
+  if (slug.length > 200) {
+    die(`directory name too long (${slug.length} chars, max 200) — nested scaffold files can exceed Windows MAX_PATH`);
+  }
+  // Same portability bar for every component `new` may CREATE: without this,
+  // `new con/proj` scaffolds inside a reserved-name dir via the back door.
+  for (const part of dir.split(/[\\/]+/).filter(Boolean).slice(0, -1)) {
+    const component = part.toLowerCase();
+    if (RESERVED.test(component)) {
+      die(`"${part}" is a reserved Windows device name — pick a different directory name`);
+    }
+    if (component.length > 200) {
+      die(`directory name too long (${component.length} chars, max 200) — nested scaffold files can exceed Windows MAX_PATH`);
+    }
+  }
   const name = (opts.name ?? basename(resolve(dir))).replace(/[<>]/g, '');
   const idea = opts.idea ?? '(describe the idea in one sentence)';
+  // --name/--idea land verbatim in the JSON manifest and generated files; a
+  // quote or backslash would poison the manifest AFTER all files are on disk.
+  // Reject before writing anything.
+  for (const [flag, value] of [['--name', name], ['--idea', idea]]) {
+    if (/["\\\u0000-\u001f]/.test(value)) {
+      die(`invalid ${flag} value — quotes, backslashes, and control characters are not allowed`);
+    }
+  }
 
   const target = resolve(process.cwd(), dir);
+  // cp(recursive) creates missing intermediate parents, so nested `new sub/proj`
+  // is a supported input — create them here, where an unusable path (a file in
+  // the prefix, no permissions) dies with a readable message instead of ENOENT.
+  try {
+    await mkdir(dirname(target), { recursive: true });
+  } catch (err) {
+    die(`cannot create "${dir}" — parent path does not exist or is not a directory${err?.code ? ` (${err.code})` : ''}`);
+  }
   if (existsSync(target) && readdirSyncSafe(target).length > 0) {
     die(`"${target}" exists and is not empty — idea2prototype never overwrites existing files`);
   }
@@ -192,6 +230,7 @@ const FEATURES = {
 async function cmdAdd(rest) {
   const feature = rest[0]?.startsWith('--') ? undefined : rest[0];
   const opts = parseFlags(rest.slice(feature ? 1 : 0), ['resource']);
+  checkPositionalCount(opts, 0, 'add takes one feature name (add <feature>)');
   const available = Object.keys(FEATURES).join(', ');
   if (!feature) die(`usage: idea2prototype add <feature> — available: ${available}`);
   const def = FEATURES[feature];
@@ -236,32 +275,41 @@ async function cmdAdd(rest) {
 // check / verify — the compact verdict
 // ---------------------------------------------------------------------------
 async function cmdCheck(rest) {
-  const opts = parseFlags(rest, []);
+  const opts = parseFlags(rest, [], ['json']);
+  checkPositionalCount(opts, 0, 'check takes no arguments — run it from inside the project');
   await loadMarker(); // must run inside a idea2prototype project
-  return runChecks(process.cwd(), 'json' in opts);
+  return runChecks(process.cwd(), 'json' in opts, 'check');
 }
 
 // verify: run the same verdict on ANY Node project — used to judge projects
 // this tool never scaffolded (benchmark control arm, external code).
 async function cmdVerify(rest) {
-  const dir = rest.find((a) => !a.startsWith('--'));
+  const opts = parseFlags(rest, [], ['json']);
+  checkPositionalCount(opts, 1, 'verify takes one optional directory (verify [dir])');
+  const dir = opts._[0];
   const target = resolve(process.cwd(), dir ?? '.');
   if (!existsSync(target) || !statSync(target).isDirectory()) {
     die(`no such directory: ${target}`);
   }
-  return runChecks(target, rest.includes('--json'));
+  return runChecks(target, 'json' in opts, 'verify');
 }
 
-async function runChecks(projectDir, asJson) {
+async function runChecks(projectDir, asJson, mode = 'check') {
   const marker = await readMarker(projectDir); // null for foreign projects (verify mode)
   const steps = [];
   const syntax = await stepSyntax(projectDir);
   steps.push(syntax);
   const tests = await stepTests(projectDir, syntax.status === 'pass');
   steps.push(tests);
-  const boot = await stepBoot(projectDir, tests.status === 'pass', marker);
+  const boot = await stepBoot(projectDir, tests, marker);
   steps.push(boot);
 
+  // An empty directory is not a project: judge mode must not hand out a
+  // green verdict for a dir with nothing to check (no sources, no tests).
+  if (!marker && tests.status === 'skip' && steps[0].files === 0) {
+    steps.push({ name: 'project', status: 'fail', detail: 'no Node project found (no sources parsed, no test files)' });
+  }
+
   const failed = steps.filter((s) => s.status === 'fail');
   const summary = failed.length === 0 ? 'PASS' : 'FAIL';
   const passedCount = steps.filter((s) => s.status === 'pass').length;
@@ -278,7 +326,7 @@ async function runChecks(projectDir, asJson) {
     }, null, 2));
   } else {
     SAY(``);
-    SAY(`Idea2Prototype check — ${summary} (${passedCount}/${steps.length} passed)  [${projectDir}]`);
+    SAY(`Idea2Prototype ${mode} — ${summary} (${passedCount}/${steps.length} passed)  [${projectDir}]`);
     for (const s of steps) {
       const icon = s.status === 'pass' ? 'PASS ' : s.status === 'fail' ? 'FAIL ' : 'SKIP ';
       SAY(`  ${s.name.padEnd(7)} ${icon} ${s.detail}`);
@@ -329,8 +377,8 @@ async function stepSyntax(projectDir) {
     detail = `${serverFiles.length} files parse clean`;
   }
   return failures.length
-    ? { name: 'syntax', status: 'fail', detail, notes: failures.slice(0, 3) }
-    : { name: 'syntax', status: 'pass', detail };
+    ? { name: 'syntax', status: 'fail', detail, notes: failures.slice(0, 3), files: total }
+    : { name: 'syntax', status: 'pass', detail, files: total };
 }
 
 // Browser JS can't take the plain `node --check <file>` path: an .js file
@@ -349,22 +397,60 @@ function parsesClean(source, inputType) {
   return res.status === 0;
 }
 
+// Test discovery for judge mode, mirroring `node --test`'s own default
+// conventions: **/*.test.{js,mjs,cjs}, test.js, test-*.*, *-test.*/_*_test.*
+// basenames at any depth, plus EVERY .js/.mjs/.cjs under a `test/` directory
+// (any depth) — so projects this tool never scaffolded are judged by their
+// real tests instead of silently passing with none found.
+// Untrusted (uploads/) and generated (dist/, coverage/, data/, public/)
+// trees are never entered: the syntax step already refuses to READ uploads,
+// and discovery must not hand an uploaded *.test.js to `node --test` to
+// EXECUTE. Dot-dirs and node_modules are skipped the same way.
+const TEST_DIR_SKIP = new Set(['node_modules', 'public', 'data', 'uploads', 'dist', 'coverage']);
+const TEST_BASENAME = /^(test(?:-.+)?|.+[._-]test)\.(js|mjs|cjs)$/;
+
+async function discoverTestFiles(projectDir) {
+  const found = new Set();
+  const JS = /\.(js|mjs|cjs)$/;
+  async function walk(dir, depth, underTestDir) {
+    if (depth > 6) return;
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || TEST_DIR_SKIP.has(entry.name)) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full, depth + 1, underTestDir || entry.name === 'test');
+      } else if (underTestDir ? JS.test(entry.name) : TEST_BASENAME.test(entry.name)) {
+        found.add(full);
+      }
+    }
+  }
+  await walk(projectDir, 0, false);
+  return [...found].sort();
+}
+
 async function stepTests(projectDir, syntaxPassed) {
-  const testDir = join(projectDir, 'tests');
   if (!syntaxPassed) return { name: 'tests', status: 'skip', detail: 'skipped (syntax failed)' };
-  let testFiles = [];
-  try {
-    testFiles = (await readdir(testDir)).filter((f) => f.endsWith('.test.mjs')).sort();
-  } catch {
-    return { name: 'tests', status: 'skip', detail: 'no tests/ directory' };
+  const testFiles = (await discoverTestFiles(projectDir)).map((f) => relative(projectDir, f));
+  if (!testFiles.length) {
+    return {
+      name: 'tests',
+      status: 'skip',
+      detail: 'no test files found',
+      notes: ['looked for node:test conventions (*.test.{js,mjs,cjs}, test-*.js, *-test.js, *_test.js, test.js, and every .js/.mjs/.cjs under a test/ directory), skipping node_modules, uploads, data, dist, coverage, public — if your tests live elsewhere, this verdict is syntax-only'],
+    };
   }
-  if (!testFiles.length) return { name: 'tests', status: 'skip', detail: 'no *.test.mjs files' };
 
   // Pass explicit file paths: glob args to `node --test` are Node >= 21 only.
   // Strip NODE_TEST_CONTEXT so a check spawned from inside a test runner
   // doesn't put the child into child-reporter mode (no TAP summary).
   const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => k !== 'NODE_TEST_CONTEXT'));
-  const fileArgs = testFiles.map((f) => join('tests', f));
+  const fileArgs = testFiles.map((f) => f.split(sep).join('/'));
   // Serial execution trades wall-clock for determinism — scale the spawn
   // budget with the file count so slow-but-passing suites aren't killed
   // (90s floor, 30s per file, 5-minute ceiling).
@@ -396,6 +482,23 @@ async function stepTests(projectDir, syntaxPassed) {
     res = spawnSync(process.execPath, ['--test', ...fileArgs], spawnOpts);
     out = capture(res);
   }
+  // A hung test run surfaces two ways, by Node version. 22's runner enforces
+  // --test-timeout at the FILE level: a top-level infinite loop is killed by
+  // the runner itself (~15s, "testTimeoutFailure" + "# cancelled 1", clean
+  // exit). 24's runner never fires there, so the spawn budget is the only
+  // bound (ETIMEDOUT, no summary). Both must read as a timeout verdict —
+  // never "? failed of ?" or spawn plumbing.
+  const fileTimeoutMs = /test timed out after (\d+)ms/.exec(out)?.[1];
+  if (res.error?.code === 'ETIMEDOUT' || fileTimeoutMs !== undefined) {
+    return {
+      name: 'tests',
+      status: 'fail',
+      detail: res.error?.code === 'ETIMEDOUT'
+        ? `tests timed out after ${Math.round(spawnOpts.timeout / 1000)}s — no summary produced`
+        : `tests timed out — the runner's own timeout killed the blocked test (after ${fileTimeoutMs}ms)`,
+      notes: ['a test file blocked past every bound — infinite loop, hung worker, or slower than the per-test budget?'],
+    };
+  }
   const counts = {};
   for (const m of out.matchAll(/^# (tests|pass|fail|skipped|cancelled) (\d+)$/gm)) counts[m[1]] = Number(m[2]);
 
@@ -416,8 +519,14 @@ async function stepTests(projectDir, syntaxPassed) {
   };
 }
 
-async function stepBoot(projectDir, testsPassed, marker) {
-  if (!testsPassed) return { name: 'boot', status: 'skip', detail: 'skipped (tests failed)' };
+async function stepBoot(projectDir, testsStep, marker) {
+  if (testsStep.status === 'fail') return { name: 'boot', status: 'skip', detail: 'skipped (tests failed)' };
+  if (testsStep.status === 'skip') {
+    // Name the actual cause — a syntax failure is why nothing ran, not
+    // "no tests found" ("skipped (…)" details unwrap to their inner cause).
+    const cause = testsStep.detail.replace(/^skipped \((.*)\)$/, '$1');
+    return { name: 'boot', status: 'skip', detail: `skipped (${cause})` };
+  }
   // Library projects have no server to probe — boot = import the public API.
   if (marker?.template === 'library') return bootLibrary(projectDir);
   return bootServer(projectDir, marker);
@@ -510,7 +619,9 @@ async function bootServer(projectDir, marker) {
 // ---------------------------------------------------------------------------
 // list / help
 // ---------------------------------------------------------------------------
-async function cmdList() {
+async function cmdList(rest) {
+  const opts = parseFlags(rest, []);
+  checkPositionalCount(opts, 0, 'list takes no arguments');
   const templates = (await readdir(TEMPLATES_DIR, { withFileTypes: true }))
     .filter((d) => d.isDirectory() && d.name !== 'features')
     .map((d) => d.name);
@@ -521,8 +632,10 @@ async function cmdList() {
 // map — compact repo map (paths + LOC + exports) so an agent can decide what
 // to read instead of loading whole files into context.
 async function cmdMap(rest) {
-  const dir = rest.find((a) => !a.startsWith('--'));
-  const asJson = rest.includes('--json');
+  const opts = parseFlags(rest, [], ['json']);
+  checkPositionalCount(opts, 1, 'map takes one optional directory (map [dir])');
+  const dir = opts._[0];
+  const asJson = 'json' in opts;
   const root = resolve(process.cwd(), dir ?? '.');
   if (!existsSync(root) || !statSync(root).isDirectory()) die(`no such directory: ${root}`);
 
@@ -594,14 +707,25 @@ const withTimeout = (promise, ms, label) => {
   return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
 };
 
-function parseFlags(args, valueFlags) {
+function parseFlags(args, valueFlags, booleanFlags = []) {
   const out = { _: [] };
+  const allowed = [
+    ...valueFlags.map((f) => `--${f} <value>`),
+    ...booleanFlags.map((f) => `--${f}`),
+  ].join(', ') || 'none';
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg.startsWith('--')) {
       const key = arg.slice(2);
-      if (valueFlags.includes(key)) out[key] = args[++i];
-      else out[key] = true;
+      if (valueFlags.includes(key)) {
+        const val = args[++i];
+        if (val === undefined || val === '' || val.startsWith('-')) die(`flag "${arg}" needs a value (allowed: ${allowed})`);
+        out[key] = val;
+      } else if (booleanFlags.includes(key)) {
+        out[key] = true;
+      } else {
+        die(`unknown flag "${arg}" (allowed: ${allowed})`);
+      }
     } else {
       out._.push(arg);
     }
@@ -609,6 +733,13 @@ function parseFlags(args, valueFlags) {
   return out;
 }
 
+// Positionals beyond what a command consumes die instead of being silently
+// ignored — `check ./proj` that quietly ignores ./proj is a silent wrong answer.
+function checkPositionalCount(opts, max, what) {
+  const extra = opts._[max];
+  if (extra !== undefined) die(`unexpected argument "${extra}" — ${what}`);
+}
+
 // Canonical marker reader: null when absent or unparseable.
 async function readMarker(projectDir) {
   try {
@@ -705,7 +836,7 @@ try {
     case 'check': await cmdCheck(rest); break;
     case 'verify': await cmdVerify(rest); break;
     case 'map': await cmdMap(rest); break;
-    case 'list': await cmdList(); break;
+    case 'list': await cmdList(rest); break;
     case 'version': case '--version': case '-v': SAY(VERSION); break;
     case 'help': case undefined: case '--help': case '-h': help(); break;
     default: die(`unknown command "${command}" — run: idea2prototype help`);

package/skills/idea2prototype/templates/api/.idea2prototype.json

@@ -1,6 +1,6 @@
 {
   "tool": "idea2prototype",
-  "version": "0.9.1",
+  "version": "1.0.0",
   "template": "api",
   "name": "{{name}}",
   "slug": "{{slug}}",

package/skills/idea2prototype/templates/api/server.mjs

@@ -15,7 +15,7 @@ async function loadApiRoutes() {
   try {
     files = await readdir(ROUTES_DIR);
   } catch {
-    return routes; // no routes yet — health + index only
+    return routes;
   }
   for (const file of files.filter((f) => f.endsWith('.mjs')).sort()) {
     const mod = await import(pathToFileURL(join(ROUTES_DIR, file)).href);
@@ -41,22 +41,42 @@ function matchRoute(route, url) {
 function readRawBody(req, limit = 10e6) {
   return new Promise((resolve, reject) => {
     let size = 0;
+    let tooLarge = false;
     const chunks = [];
     req.on('data', (chunk) => {
       size += chunk.length;
+      // Oversize policy: drain up to 2x limit so a clean 413 can still be
+      // delivered at end(); past 2x, destroy the socket to bound the cost of
+      // absorbing junk — those clients see a connection reset, deliberately.
       if (size > limit) {
-        reject(new Error('body too large'));
-        req.destroy();
+        tooLarge = true;
+        if (size > limit * 2) {
+          req.destroy();
+          const err = new Error('body too large');
+          err.code = 'BODY_TOO_LARGE';
+          reject(err);
+        }
       } else {
         chunks.push(chunk);
       }
     });
-    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('end', () => {
+      if (tooLarge) {
+        const err = new Error('body too large');
+        err.code = 'BODY_TOO_LARGE';
+        reject(err);
+      } else {
+        resolve(Buffer.concat(chunks));
+      }
+    });
     req.on('error', reject);
   });
 }
 
 function sendJson(res, status, payload, headers = {}) {
+  // Handlers are user code — a bogus status must degrade to a clean 500, not
+  // throw inside writeHead and leak Node internals ("Invalid status code: b").
+  if (!Number.isInteger(status) || status < 100 || status > 599) status = 500;
   if (status === 204 || status === 304) {
     res.writeHead(status, headers);
     return res.end();
@@ -65,7 +85,9 @@ function sendJson(res, status, payload, headers = {}) {
     res.writeHead(status, { 'content-length': payload.length, ...headers });
     return res.end(payload);
   }
-  const data = JSON.stringify(payload);
+  // [status] with no payload serializes as null — JSON.stringify(undefined)
+  // returns undefined and Buffer.byteLength would throw on it.
+  const data = JSON.stringify(payload ?? null);
   res.writeHead(status, {
     'content-type': 'application/json; charset=utf-8',
     'content-length': Buffer.byteLength(data),
@@ -94,7 +116,10 @@ export async function start(port = Number(process.env.PORT ?? 3000)) {
           try {
             raw = await readRawBody(req);
           } catch (err) {
-            return sendJson(res, 400, { error: err.message });
+            if (err.code === 'BODY_TOO_LARGE') {
+              return sendJson(res, 413, { error: 'body too large' });
+            }
+            return sendJson(res, 400, { error: String(err?.message ?? err) });
           }
           if ((req.headers['content-type'] ?? '').includes('multipart/form-data')) {
             ctx.rawBody = raw;
@@ -111,6 +136,12 @@ export async function start(port = Number(process.env.PORT ?? 3000)) {
         // ctx.res (e.g. Server-Sent Events) returns nothing — the stream
         // stays open past this request; don't try to send a JSON response.
         if (res.headersSent || res.writableEnded) return;
+        // Contract-violating returns (a bare string, undefined, ...) must be
+        // a clean 500 — destructuring them would leak parser plumbing
+        // ("result is not iterable") into the response.
+        if (!Array.isArray(result)) {
+          return sendJson(res, 500, { error: 'handler returned an invalid result (expected [status, payload, headers?])' });
+        }
         const [status, payload, headers] = result;
         return sendJson(res, status, payload, headers);
       }

package/skills/idea2prototype/templates/cli/.idea2prototype.json

@@ -1,6 +1,6 @@
 {
   "tool": "idea2prototype",
-  "version": "0.9.1",
+  "version": "1.0.0",
   "template": "cli",
   "name": "{{name}}",
   "slug": "{{slug}}",

package/skills/idea2prototype/templates/features/api-crud/route.tmpl.mjs

@@ -1,26 +1,56 @@
 // Idea2Prototype feature: api-crud — resource "{{resource}}"
 // Contract: handlers return [status, payload]; the server sends payload as JSON.
 // Persistence: JSON file at data/{{resource}}.json (created on first write).
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 
 const STORE_PATH = join(process.cwd(), 'data', '{{resource}}.json');
-let cache = null;
+let ready = null; // memoized cold load: concurrent first callers share ONE array
 
-async function load() {
-  if (cache) return cache;
-  try {
-    cache = JSON.parse(await readFile(STORE_PATH, 'utf8'));
-  } catch {
-    cache = [];
+function load() {
+  if (!ready) {
+    ready = (async () => {
+      let cache = null;
+      let raw = null;
+      try {
+        raw = await readFile(STORE_PATH, 'utf8');
+      } catch (err) {
+        if (err?.code !== 'ENOENT') console.error(`[{{resource}}] could not read data store (${err?.code ?? err}) — starting empty`);
+      }
+      if (raw !== null) {
+        try {
+          cache = JSON.parse(raw);
+        } catch {
+          cache = null;
+        }
+      }
+      if (raw === null || cache === null || !Array.isArray(cache)) {
+        // A store that exists but is corrupt (unparseable, or not a list) must
+        // never be silently wiped — the next persist() would overwrite data
+        // that may still be recoverable. Quarantine it, say so loudly, start
+        // empty. If even the quarantine rename fails, do NOT pretend it is
+        // safe: the original file WILL be overwritten by the next persist.
+        if (raw !== null) {
+          const quarantine = `${STORE_PATH}.corrupt-${Date.now().toString(36)}`;
+          try {
+            await rename(STORE_PATH, quarantine);
+            console.error(`[{{resource}}] data store is not a valid JSON list — quarantined as ${quarantine}; starting empty`);
+          } catch (err) {
+            console.error(`[{{resource}}] data store is corrupt AND could not be quarantined (${err?.code ?? err}) — the next write will overwrite it`);
+          }
+        }
+        cache = [];
+      }
+      return cache;
+    })();
   }
-  return cache;
+  return ready;
 }
 
 async function persist() {
   await mkdir(join(process.cwd(), 'data'), { recursive: true });
-  await writeFile(STORE_PATH, JSON.stringify(cache, null, 2));
+  await writeFile(STORE_PATH, JSON.stringify(await load(), null, 2));
 }
 
 function requireObject(body) {

package/skills/idea2prototype/templates/features/auth-local/route.tmpl.mjs

@@ -3,7 +3,7 @@
 // Compose into other routes: import { requireAuth } from './auth.mjs'
 //   methods: { GET: requireAuth(async (ctx) => [200, { hello: ctx.user.username }]) }
 import { createHmac, randomUUID, scryptSync, timingSafeEqual } from 'node:crypto';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 const USERS_FILE = join(process.cwd(), 'data', 'users.json');
@@ -11,22 +11,51 @@ const SECRET_FILE = join(process.cwd(), 'data', '.auth-secret');
 const COOKIE_NAME = 'i2p_session';
 const SESSION_TTL_MS = 24 * 60 * 60 * 1000;
 
-let usersCache = null;
+let usersReady = null; // memoized cold load: concurrent first callers share ONE array
 let secretCache = null;
 
-async function loadUsers() {
-  if (usersCache) return usersCache;
-  try {
-    usersCache = JSON.parse(await readFile(USERS_FILE, 'utf8'));
-  } catch {
-    usersCache = [];
+function loadUsers() {
+  if (!usersReady) {
+    usersReady = (async () => {
+      let usersCache = null;
+      let raw = null;
+      try {
+        raw = await readFile(USERS_FILE, 'utf8');
+      } catch (err) {
+        if (err?.code !== 'ENOENT') console.error(`[auth] could not read users store (${err?.code ?? err}) — starting empty`);
+      }
+      if (raw !== null) {
+        try {
+          usersCache = JSON.parse(raw);
+        } catch {
+          usersCache = null;
+        }
+      }
+      if (raw === null || usersCache === null || !Array.isArray(usersCache)) {
+        // A users store that exists but is corrupt must never be silently
+        // wiped — the next register would overwrite every account. Quarantine,
+        // say so, start empty (accounts can be re-registered; the old file is
+        // preserved). If the rename itself fails, say THAT loudly too.
+        if (raw !== null) {
+          const quarantine = `${USERS_FILE}.corrupt-${Date.now().toString(36)}`;
+          try {
+            await rename(USERS_FILE, quarantine);
+            console.error(`[auth] users store is not a valid JSON list — quarantined as ${quarantine}; starting empty`);
+          } catch (err) {
+            console.error(`[auth] users store is corrupt AND could not be quarantined (${err?.code ?? err}) — the next write will overwrite it`);
+          }
+        }
+        usersCache = [];
+      }
+      return usersCache;
+    })();
   }
-  return usersCache;
+  return usersReady;
 }
 
 async function persistUsers() {
   await mkdir(join(process.cwd(), 'data'), { recursive: true });
-  await writeFile(USERS_FILE, JSON.stringify(usersCache, null, 2));
+  await writeFile(USERS_FILE, JSON.stringify(await loadUsers(), null, 2));
 }
 
 async function getSecret() {
@@ -147,6 +176,11 @@ export default [
   {
     path: '/api/auth/logout',
     methods: {
+      // Clears the BROWSER cookie only. Session tokens are stateless HMAC —
+      // there is no server-side session store, so a token copied before
+      // logout keeps authenticating until it expires (SESSION_TTL_MS).
+      // Anything user-facing on top of this demo should shorten the TTL or
+      // add a server-side revocation list.
       POST: async () => [200, { ok: true }, { 'set-cookie': clearedCookie() }],
     },
   },

package/skills/idea2prototype/templates/features/rate-limit/route.tmpl.mjs

@@ -3,9 +3,7 @@
 // Compose into any route handler: import { rateLimit } from './ratelimit.mjs'
 //   methods: { GET: rateLimit({ max: 10, windowMs: 60_000 })(async (ctx) => [200, { ok: true }]) }
 
-const buckets = new Map(); // key -> { count, resetAt }
 const CLEANUP_INTERVAL_MS = 60_000;
-let lastCleanup = 0;
 
 /**
  * Wrap a route handler with a per-key fixed-window limiter.
@@ -15,8 +13,12 @@ let lastCleanup = 0;
  * e.g. keyFn: (ctx) => ctx.req.headers['x-forwarded-for'] ?? 'local'.
  * Over-limit requests get 429 + Retry-After; allowed ones pass
  * through with X-RateLimit-* headers merged into the response.
+ * Each rateLimit({...}) instance owns its OWN buckets: independently
+ * configured wrappers never drain each other's budget.
  */
 export function rateLimit({ max = 60, windowMs = 60_000, keyFn } = {}) {
+  const buckets = new Map(); // key -> { count, resetAt }
+  let lastCleanup = 0;
   return (handler) => async (ctx) => {
     const key = keyFn ? keyFn(ctx) : (ctx.req?.socket?.remoteAddress ?? 'local');
     const now = Date.now();

package/skills/idea2prototype/templates/features/rate-limit/test.tmpl.mjs

@@ -3,8 +3,8 @@ import assert from 'node:assert/strict';
 import { start } from '../server.mjs';
 import { rateLimit } from '../routes/ratelimit.mjs';
 
-// NOTE: both tests share the module-level rate buckets; the second test uses
-// custom keys so it is independent of the first test's IP bucket.
+// NOTE: each rateLimit({...}) instance owns its own buckets (the map lives
+// inside the factory) — that independence is pinned by the third test.
 
 test('GET /api/ping allows max then returns 429 with limit headers', async (t) => {
   const app = await start(0);
@@ -46,3 +46,23 @@ test('rateLimit: custom keyFn isolates clients into separate buckets', async ()
   const retryAfter = Number(second[2]['Retry-After']);
   assert.ok(retryAfter >= 59 && retryAfter <= 60, `unexpected Retry-After ${retryAfter}`);
 });
+
+test('rateLimit: independently configured wrappers never share budget', async () => {
+  // exhaust a tight limiter, then prove a loose limiter's FIRST request
+  // still sees a full budget (module-level buckets used to leak the count
+  // across wrappers — cross-route lockout)
+  const tight = rateLimit({ max: 1, windowMs: 60_000, keyFn: (ctx) => ctx.key })(
+    async () => [200, { which: 'tight' }],
+  );
+  const loose = rateLimit({ max: 50, windowMs: 60_000, keyFn: (ctx) => ctx.key })(
+    async () => [200, { which: 'loose' }],
+  );
+
+  await tight({ key: 'carol', req: {} }); // tight budget spent
+  assert.equal((await tight({ key: 'carol', req: {} }))[0], 429);
+
+  const [status, , headers] = await loose({ key: 'carol', req: {} }); // same client, other route
+  assert.equal(status, 200); // NOT locked out by the tight wrapper
+  assert.equal(headers['X-RateLimit-Limit'], '50');
+  assert.equal(headers['X-RateLimit-Remaining'], '49'); // full budget, not 48
+});

package/skills/idea2prototype/templates/features/worker-jobs/jobs.tmpl.mjs

@@ -19,11 +19,31 @@ let ready = null; // memoized cold load: concurrent first callers share ONE arra
 function load() {
   if (!ready) {
     ready = (async () => {
+      let raw = null;
       try {
-        jobs = JSON.parse(await readFile(STORE_PATH, 'utf8'));
+        raw = await readFile(STORE_PATH, 'utf8');
       } catch (err) {
-        if (err?.code !== 'ENOENT') {
-          console.error(`[jobs] could not read ${STORE_PATH} (${err?.message ?? err}) — starting empty`);
+        if (err?.code !== 'ENOENT') console.error(`[jobs] could not read store (${err?.code ?? err}) — starting empty`);
+      }
+      if (raw !== null) {
+        try {
+          jobs = JSON.parse(raw);
+        } catch {
+          jobs = null;
+        }
+      }
+      if (raw === null || jobs === null || !Array.isArray(jobs)) {
+        // A store that exists but is corrupt must never be silently wiped —
+        // the next persist would overwrite recoverable job history. Quarantine
+        // it, say so loudly, start empty.
+        if (raw !== null) {
+          const quarantine = `${STORE_PATH}.corrupt-${Date.now().toString(36)}`;
+          try {
+            await rename(STORE_PATH, quarantine);
+            console.error(`[jobs] store is not a valid JSON list — quarantined as ${quarantine}; starting empty`);
+          } catch (err) {
+            console.error(`[jobs] store is corrupt AND could not be quarantined (${err?.code ?? err}) — the next write will overwrite it`);
+          }
         }
         jobs = [];
       }

package/skills/idea2prototype/templates/library/.idea2prototype.json

@@ -1,6 +1,6 @@
 {
   "tool": "idea2prototype",
-  "version": "0.9.1",
+  "version": "1.0.0",
   "template": "library",
   "name": "{{name}}",
   "slug": "{{slug}}",

package/skills/idea2prototype/templates/web/.idea2prototype.json

@@ -1,6 +1,6 @@
 {
   "tool": "idea2prototype",
-  "version": "0.9.1",
+  "version": "1.0.0",
   "template": "web",
   "name": "{{name}}",
   "slug": "{{slug}}",

package/skills/idea2prototype/templates/web/server.mjs

@@ -52,22 +52,42 @@ function matchRoute(route, url) {
 function readRawBody(req, limit = 10e6) {
   return new Promise((resolve, reject) => {
     let size = 0;
+    let tooLarge = false;
     const chunks = [];
     req.on('data', (chunk) => {
       size += chunk.length;
+      // Oversize policy: drain up to 2x limit so a clean 413 can still be
+      // delivered at end(); past 2x, destroy the socket to bound the cost of
+      // absorbing junk — those clients see a connection reset, deliberately.
       if (size > limit) {
-        reject(new Error('body too large'));
-        req.destroy();
+        tooLarge = true;
+        if (size > limit * 2) {
+          req.destroy();
+          const err = new Error('body too large');
+          err.code = 'BODY_TOO_LARGE';
+          reject(err);
+        }
       } else {
         chunks.push(chunk);
       }
     });
-    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('end', () => {
+      if (tooLarge) {
+        const err = new Error('body too large');
+        err.code = 'BODY_TOO_LARGE';
+        reject(err);
+      } else {
+        resolve(Buffer.concat(chunks));
+      }
+    });
     req.on('error', reject);
   });
 }
 
 function sendJson(res, status, payload, headers = {}) {
+  // Handlers are user code — a bogus status must degrade to a clean 500, not
+  // throw inside writeHead and leak Node internals ("Invalid status code: b").
+  if (!Number.isInteger(status) || status < 100 || status > 599) status = 500;
   if (status === 204 || status === 304) {
     res.writeHead(status, headers);
     return res.end();
@@ -76,7 +96,9 @@ function sendJson(res, status, payload, headers = {}) {
     res.writeHead(status, { 'content-length': payload.length, ...headers });
     return res.end(payload);
   }
-  const data = JSON.stringify(payload);
+  // [status] with no payload serializes as null — JSON.stringify(undefined)
+  // returns undefined and Buffer.byteLength would throw on it.
+  const data = JSON.stringify(payload ?? null);
   res.writeHead(status, {
     'content-type': 'application/json; charset=utf-8',
     'content-length': Buffer.byteLength(data),
@@ -105,7 +127,10 @@ export async function start(port = Number(process.env.PORT ?? 3000)) {
           try {
             raw = await readRawBody(req);
           } catch (err) {
-            return sendJson(res, 400, { error: err.message });
+            if (err.code === 'BODY_TOO_LARGE') {
+              return sendJson(res, 413, { error: 'body too large' });
+            }
+            return sendJson(res, 400, { error: String(err?.message ?? err) });
           }
           if ((req.headers['content-type'] ?? '').includes('multipart/form-data')) {
             ctx.rawBody = raw;
@@ -122,6 +147,12 @@ export async function start(port = Number(process.env.PORT ?? 3000)) {
         // ctx.res (e.g. Server-Sent Events) returns nothing — the stream
         // stays open past this request; don't try to send a JSON response.
         if (res.headersSent || res.writableEnded) return;
+        // Contract-violating returns (a bare string, undefined, ...) must be
+        // a clean 500 — destructuring them would leak parser plumbing
+        // ("result is not iterable") into the response.
+        if (!Array.isArray(result)) {
+          return sendJson(res, 500, { error: 'handler returned an invalid result (expected [status, payload, headers?])' });
+        }
         const [status, payload, headers] = result;
         return sendJson(res, status, payload, headers);
       }

package/skills/idea2prototype/templates/worker/.idea2prototype.json

@@ -1,6 +1,6 @@
 {
   "tool": "idea2prototype",
-  "version": "0.9.1",
+  "version": "1.0.0",
   "template": "worker",
   "name": "{{name}}",
   "slug": "{{slug}}",

package/skills/idea2prototype/templates/worker/worker.mjs

@@ -14,11 +14,31 @@ let ready = null; // memoized cold load: concurrent first callers share ONE arra
 function load() {
   if (!ready) {
     ready = (async () => {
+      let raw = null;
       try {
-        jobs = JSON.parse(await readFile(STORE_PATH, 'utf8'));
+        raw = await readFile(STORE_PATH, 'utf8');
       } catch (err) {
-        if (err?.code !== 'ENOENT') {
-          console.error(`[jobs] could not read ${STORE_PATH} (${err?.message ?? err}) — starting empty`);
+        if (err?.code !== 'ENOENT') console.error(`[jobs] could not read store (${err?.code ?? err}) — starting empty`);
+      }
+      if (raw !== null) {
+        try {
+          jobs = JSON.parse(raw);
+        } catch {
+          jobs = null;
+        }
+      }
+      if (raw === null || jobs === null || !Array.isArray(jobs)) {
+        // A store that exists but is corrupt must never be silently wiped —
+        // the next persist would overwrite recoverable job history. Quarantine
+        // it, say so loudly, start empty.
+        if (raw !== null) {
+          const quarantine = `${STORE_PATH}.corrupt-${Date.now().toString(36)}`;
+          try {
+            await rename(STORE_PATH, quarantine);
+            console.error(`[jobs] store is not a valid JSON list — quarantined as ${quarantine}; starting empty`);
+          } catch (err) {
+            console.error(`[jobs] store is corrupt AND could not be quarantined (${err?.code ?? err}) — the next write will overwrite it`);
+          }
         }
         jobs = [];
       }