@ahmed-3m/idea2prototype 0.9.1 → 1.0.1

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.1';
 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`);
   }
@@ -189,9 +227,29 @@ const FEATURES = {
   },
 };
 
+// api-crud resource names that would collide with another feature's data
+// store, route file, or URL path — in EITHER add order, so a file-exists
+// check alone can't catch them. "users" is the dangerous one: a CRUD resource
+// over data/users.json serves auth-local's salts + hashes to anonymous GETs
+// and lets anonymous POSTs plant login-capable accounts.
+const RESERVED_RESOURCES = new Map([
+  ['users', 'auth-local stores accounts in data/users.json'],
+  ['auth', 'auth-local owns routes/auth.mjs and /api/auth/*'],
+  ['jobs', 'worker-jobs owns data/jobs.json, routes/jobs.mjs and /api/jobs'],
+  ['uploads', 'upload owns routes/uploads.mjs and /api/uploads'],
+  ['events', 'sse owns /api/events'],
+  ['sse', 'sse owns routes/sse.mjs'],
+  ['ping', 'rate-limit owns /api/ping'],
+  ['ratelimit', 'rate-limit owns routes/ratelimit.mjs'],
+  ['cors', 'cors owns routes/cors.mjs'],
+  ['cors-ping', 'cors owns /api/cors-ping'],
+  ['health', 'the server answers /api/health itself'],
+]);
+
 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];
@@ -207,6 +265,9 @@ async function cmdAdd(rest) {
     if (!/^[a-z][a-z0-9-]*$/.test(resource)) {
       die(`invalid resource name "${resource}" — lowercase letters, digits, dashes`);
     }
+    if (RESERVED_RESOURCES.has(resource)) {
+      die(`resource name "${resource}" is reserved — ${RESERVED_RESOURCES.get(resource)}; pick another name`);
+    }
     opts.resource = resource;
   }
 
@@ -236,32 +297,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 +348,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 +399,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 +419,61 @@ 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' };
+  if (!syntaxPassed) return { name: 'tests', status: 'skip', detail: 'skipped (syntax failed)', cause: 'syntax' };
+  const testFiles = (await discoverTestFiles(projectDir)).map((f) => relative(projectDir, f));
+  if (!testFiles.length) {
+    return {
+      name: 'tests',
+      status: 'skip',
+      detail: 'no test files found',
+      cause: 'no-tests',
+      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 covers syntax + boot 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 +505,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,11 +542,28 @@ async function stepTests(projectDir, syntaxPassed) {
   };
 }
 
-async function stepBoot(projectDir, testsPassed, marker) {
-  if (!testsPassed) return { name: 'boot', status: 'skip', detail: 'skipped (tests failed)' };
-  // Library projects have no server to probe — boot = import the public API.
-  if (marker?.template === 'library') return bootLibrary(projectDir);
-  return bootServer(projectDir, marker);
+async function stepBoot(projectDir, testsStep, marker) {
+  if (testsStep.status === 'fail') return { name: 'boot', status: 'skip', detail: 'skipped (tests failed)' };
+  // A syntax failure is why nothing ran — importing broken code proves nothing.
+  if (testsStep.cause === 'syntax') return { name: 'boot', status: 'skip', detail: 'skipped (syntax failed)' };
+  // "No tests found" is NOT a reason to skip boot: a project without tests is
+  // exactly the one whose only remaining evidence is whether it starts (a
+  // server that throws in start() used to verify PASS on syntax alone).
+  //
+  // Boot runs in THIS process, so the project's cwd-relative paths (the
+  // templates' ROOT/routes/data, a foreign readFileSync('config.json')) must
+  // resolve against the project — as they do for the tests step (cwd:
+  // projectDir) and for `npm start`. Otherwise `verify <dir>` from elsewhere
+  // boots a different app than `verify` from inside it.
+  const previousCwd = process.cwd();
+  process.chdir(projectDir);
+  try {
+    // Library projects have no server to probe — boot = import the public API.
+    if (marker?.template === 'library') return await bootLibrary(projectDir);
+    return await bootServer(projectDir, marker);
+  } finally {
+    process.chdir(previousCwd);
+  }
 }
 
 async function bootLibrary(projectDir) {
@@ -444,73 +587,103 @@ async function bootServer(projectDir, marker) {
   if (!existsSync(serverPath)) return { name: 'boot', status: 'skip', detail: 'no server.mjs' };
 
   const started = Date.now();
-  let app; // closed in finally once started — a leaked listener hangs the process forever
-  // The import ran but no app handle came back to close: the module may hold
+  let app; // closed below once started — a leaked listener hangs the process forever
+  // The import ran but no closable app handle came back: the module may hold
   // its own listeners (foreign entry points often listen at import time).
   // Mark the step so runChecks exits explicitly after printing the verdict —
   // those handles are unreachable from here and would hang the process.
   const leakedImport = { unreachableHandles: true };
+  let result;
   try {
     const mod = await withTimeout(import(pathToFileURL(serverPath).href), 15_000, 'server import');
     if (typeof mod.start !== 'function') {
       return { name: 'boot', status: 'skip', detail: 'server.mjs does not export start()', ...leakedImport };
     }
     app = await withTimeout(mod.start(0), 10_000, 'server start');
-    // redirect: 'manual' — never follow a redirect off the probe target; the
-    // 3xx itself counts as serving (foreign ok-range is 200–399).
-    const probe = async (path) =>
-      withTimeout(fetch(`http://127.0.0.1:${app.port}${path}`, { redirect: 'manual' }), 10_000, `${path} request`);
-    let res = await probe('/api/health');
-    let detail = `GET /api/health -> ${res.status}`;
-    // Foreign projects (verify mode) may not implement our template's health
-    // route — a server that starts and serves its own surface still boots.
-    let rootProbed = false;
-    if (res.status === 404) {
-      res = await probe('/');
-      detail = `GET /api/health -> 404, GET / -> ${res.status}`;
-      rootProbed = true;
-    }
-    const body = await res.json().catch(() => ({}));
-
-    // Scaffolded projects follow the template contract (health returns
-    // {"status":"ok"}); foreign projects only have to start and serve.
-    const ok = marker
-      ? res.status === 200 && body.status === 'ok'
-      : res.status >= 200 && res.status < 400;
-    if (!ok) {
-      return { name: 'boot', status: 'fail', detail: `${detail} ${JSON.stringify(body)}` };
-    }
+    result = await probeServer(app, marker, started);
+  } catch (err) {
+    result = { name: 'boot', status: 'fail', detail: String(err?.message ?? err) };
+  }
+  // Not a finally: a close() that throws or never settles must not replace
+  // the verdict (foreign handles are untrusted) — it only flags the exit.
+  if (!(await closeApp(app))) Object.assign(result, leakedImport);
+  return result;
+}
 
-    // #18: a health route alone can certify an app whose every real route
-    // 500s — also probe the root. 4xx on / is legitimate (API-only projects),
-    // a 5xx root is a real defect. Symmetric for scaffolded and foreign
-    // projects; a request error here surfaces via the outer catch.
-    if (!rootProbed) {
-      const root = await probe('/');
-      detail += `, GET / -> ${root.status}`;
-      if (root.status >= 500) {
-        return { name: 'boot', status: 'fail', detail: `${detail} — root serves an error` };
-      }
+// start(0) may hand back the template contract ({ port, close() }) or, in
+// foreign projects, a bare listening http.Server — read the port from either.
+function appPort(app) {
+  return app?.port ?? app?.address?.()?.port ?? app?.server?.address?.()?.port;
+}
+
+// Close whatever start() returned: a promise-returning close() (template
+// contract) or a callback-style http.Server close(cb). Returns false when
+// nothing closable came back or the close failed/hung — the caller then
+// exits explicitly instead of hanging on handles it cannot reach.
+async function closeApp(app) {
+  if (typeof app?.close !== 'function') return false;
+  try {
+    app.closeAllConnections?.(); // bare http.Server: drop keep-alive sockets so close(cb) settles
+    await withTimeout(new Promise((resolve, reject) => {
+      const ret = app.close((err) => (err ? reject(err) : resolve()));
+      if (typeof ret?.then === 'function') ret.then(resolve, reject);
+    }), 5_000, 'server close');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function probeServer(app, marker, started) {
+  const port = appPort(app);
+  if (!Number.isInteger(port)) {
+    return { name: 'boot', status: 'fail', detail: 'start() returned no port — expected { port, close() } or a listening http.Server' };
+  }
+  // redirect: 'manual' — never follow a redirect off the probe target; the
+  // 3xx itself counts as serving (foreign ok-range is 200–399).
+  const probe = async (path) =>
+    withTimeout(fetch(`http://127.0.0.1:${port}${path}`, { redirect: 'manual' }), 10_000, `${path} request`);
+  let res = await probe('/api/health');
+  let detail = `GET /api/health -> ${res.status}`;
+  // Foreign projects (verify mode) may not implement our template's health
+  // route — a server that starts and serves its own surface still boots.
+  let rootProbed = false;
+  if (res.status === 404) {
+    res = await probe('/');
+    detail = `GET /api/health -> 404, GET / -> ${res.status}`;
+    rootProbed = true;
+  }
+  const body = await res.json().catch(() => ({}));
+
+  // Scaffolded projects follow the template contract (health returns
+  // {"status":"ok"}); foreign projects only have to start and serve.
+  const ok = marker
+    ? res.status === 200 && body.status === 'ok'
+    : res.status >= 200 && res.status < 400;
+  if (!ok) {
+    return { name: 'boot', status: 'fail', detail: `${detail} ${JSON.stringify(body)}` };
+  }
+
+  // #18: a health route alone can certify an app whose every real route
+  // 500s — also probe the root. 4xx on / is legitimate (API-only projects),
+  // a 5xx root is a real defect. Symmetric for scaffolded and foreign
+  // projects; a request error here surfaces via bootServer's catch.
+  if (!rootProbed) {
+    const root = await probe('/');
+    detail += `, GET / -> ${root.status}`;
+    if (root.status >= 500) {
+      return { name: 'boot', status: 'fail', detail: `${detail} — root serves an error` };
     }
-    return { name: 'boot', status: 'pass', detail: `${detail} in ${Date.now() - started}ms` };
-  } catch (err) {
-    // Import or start() threw before app was assigned → nothing was closed.
-    // (Probe failures after a successful start still run the finally close.)
-    return {
-      name: 'boot',
-      status: 'fail',
-      detail: String(err?.message ?? err),
-      ...(app ? {} : leakedImport),
-    };
-  } finally {
-    if (typeof app?.close === 'function') await app.close().catch(() => {});
   }
+  return { name: 'boot', status: 'pass', detail: `${detail} in ${Date.now() - started}ms` };
 }
 
 // ---------------------------------------------------------------------------
 // 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 +694,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 +769,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 +795,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 +898,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.1",
   "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.1",
   "template": "cli",
   "name": "{{name}}",
   "slug": "{{slug}}",