@ahmed-3m/idea2prototype 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 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.
+- CI: release publishes now fail loudly when `NPM_TOKEN` is missing instead of skipping with a warning — npmjs is the documented primary channel, and a mirror-only release with a green run would silently invert the README's install claims. Manual `workflow_dispatch` without the secret keeps the visible skip.
+
 ## 0.9.0
 
 - Feature: `add worker-jobs` — the worker template's persistent job queue as a feature module for web/api projects: `enqueue`/`list`/`registerHandler`, `data/jobs.json` persistence, 3 attempts with a terminal `failed` state, disposable demo routes `POST/GET /api/jobs`. `enqueue` auto-kicks a background drain; concurrent enqueues share one serialized drain, so double-processing is designed out, and the drain exits on an empty queue (no long-lived timer; server `close()` unaffected). Closes the previously documented "web app + background jobs" cross-template gap. Review-hardened: memoized cold load (concurrent first enqueues share one array), chained atomic store writes (write-to-tmp + rename; a failed write can't poison later ones or leave a half-written store), honest drain diagnostics, handler contract documented.

package/README.md

@@ -15,7 +15,7 @@ Idea2Prototype check — PASS (3/3)
   boot    PASS  GET /api/health -> 200, GET / -> 200 in 45ms
 ```
 
-**Status:** v0.8.0 · actively maintained · 0.x — the check/verify contract and template shapes are stable; new capabilities arrive as `add` modules.
+**Status:** v0.9.0 · actively maintained · 0.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).
 
@@ -56,25 +56,27 @@ Templates: `web` (static frontend + health + auto-loading routes), `api` (JSON A
 
 ## Quickstart
 
-**Any agent or plain shell — works from a clean clone:**
+**Any agent or plain shell — npx straight off npmjs, no clone needed:**
 
 ```bash
-git clone https://github.com/ahmed-3m/idea2prototype
-node idea2prototype/skills/idea2prototype/scripts/idea2prototype.mjs new my-app --template web --name "My App" --idea "recipe box"
+npx @ahmed-3m/idea2prototype new my-app --template web --name "My App" --idea "recipe box"
 cd my-app && npm start          # http://127.0.0.1:3000
 npm run check                   # the verdict above
-node ../idea2prototype/skills/idea2prototype/scripts/idea2prototype.mjs add api-crud --resource recipes
+npx @ahmed-3m/idea2prototype add api-crud --resource recipes
 npm run check                   # still PASS — now with CRUD tests
 ```
 
-**Using npx** the same session is shorter:
+**From a clean clone** (offline / air-gapped, or pinning the engine alongside the project):
 
 ```bash
-npx @ahmed-3m/idea2prototype new my-app --template web --name "My App" --idea "recipe box"
-cd my-app && npm start && npx @ahmed-3m/idea2prototype add api-crud --resource recipes && npm run check
+git clone https://github.com/ahmed-3m/idea2prototype
+node idea2prototype/skills/idea2prototype/scripts/idea2prototype.mjs new my-app --template web --name "My App" --idea "recipe box"
+cd my-app && npm start          # http://127.0.0.1:3000
+node ../idea2prototype/skills/idea2prototype/scripts/idea2prototype.mjs add api-crud --resource recipes
+npm run check                   # still PASS — now with CRUD tests
 ```
 
-It is also mirrored on the GitHub Packages registry as `@ahmed-3m/idea2prototype` (published automatically per release) — note that registry asks consumers for a token in `.npmrc` even for public packages, so treat it as a mirror, not the primary channel.
+Every release publishes `@ahmed-3m/idea2prototype` to npmjs.org — the primary channel — and mirrors it on the GitHub Packages registry under the same name; that registry asks consumers for a token in `.npmrc` even for public packages, so treat it as the mirror. (`npm i -g @ahmed-3m/idea2prototype` gets you the short `i2p` command the table above uses.)
 
 **ZCode plugin:** add this repo's marketplace, install `idea2prototype`, then pick the skill in the composer or use `/proto-new a recipe box with search`.
 
@@ -119,7 +121,7 @@ The generated CRUD test then needs a session instead of anonymous POSTs — regi
 4. **No destructive operations.** `new` refuses non-empty directories.
 5. **Portable core.** One `.mjs` engine; plugin/skill/npm wrappers are sugar.
 
-One deliberate tradeoff: a scaffolded project's `npm run check` invokes the exact engine that scaffolded it, so older prototypes keep the behavior they were built with (run a newer engine by hand and it reports the drift note). An `npx`-driven check is on the roadmap.
+One deliberate tradeoff: a scaffolded project's `npm run check` invokes the exact engine version that scaffolded it — a clone-scaffolded project pins the sibling engine path, an npx-scaffolded project pins registry coordinates (`npx -y @ahmed-3m/idea2prototype@<version> check`), so a cleared npx cache or a second machine just re-fetches the same version — and older prototypes keep the behavior they were built with (run a newer engine by hand and it reports the drift note). An always-current check remains on the roadmap.
 
 Another boundary worth naming: templates are single-purpose and do not compose with each other — features compose within a template (auth × CRUD, rate-limit, cors, sse, worker-jobs). The one gap this used to leave — a web/api app that also needs background jobs — is closed by `add worker-jobs`, which brings the worker template's persistent queue in as a feature module; anything bigger than that still scaffolds as the primary template with the smaller part hand-built.
 

package/agents/AGENTS.md

@@ -2,23 +2,25 @@
 
 Copy this file into any project where your coding agent should build with idea2prototype. Works with any agent that reads AGENTS.md conventions.
 
-You have `idea2prototype` (`i2p`) available — a zero-dependency prototype tool. Use it instead of hand-writing scaffolding. If the npm package isn't installed or available, run the engine directly instead of `npx idea2prototype`: `node <path-to-idea2prototype-repo>/skills/idea2prototype/scripts/idea2prototype.mjs <command>`.
+You have `idea2prototype` (`i2p`) available — a zero-dependency prototype tool. Use it instead of hand-writing scaffolding. If the npm package isn't installed or available, run the engine directly instead of `npx @ahmed-3m/idea2prototype`: `node <path-to-idea2prototype-repo>/skills/idea2prototype/scripts/idea2prototype.mjs <command>`.
 
 ## Commands
 
-- `npx idea2prototype new <dir> --template web|api|cli|worker|library` — scaffold a running, tested project (~0 tokens vs 10–30k hand-written)
-- `npx idea2prototype add api-crud --resource <name>` — JSON-file CRUD resource + roundtrip tests
-- `npx idea2prototype add auth-local` — register/login/logout/me (scrypt + signed cookies) + tests; `requireAuth` protects other routes
-- `npx idea2prototype add upload` — multipart file uploads + fetch-back + tests
-- `npx idea2prototype add rate-limit` — per-key fixed-window limiter (429 + Retry-After headers); `rateLimit()` wraps any handler
-- `npx idea2prototype add cors` — CORS wrapper (preflight + access-control-* headers, origin allowlists); `cors()` wraps any handler
+- `npx @ahmed-3m/idea2prototype new <dir> --template web|api|cli|worker|library` — scaffold a running, tested project (~0 tokens vs 10–30k hand-written)
+- `npx @ahmed-3m/idea2prototype add api-crud --resource <name>` — JSON-file CRUD resource + roundtrip tests
+- `npx @ahmed-3m/idea2prototype add auth-local` — register/login/logout/me (scrypt + signed cookies) + tests; `requireAuth` protects other routes
+- `npx @ahmed-3m/idea2prototype add upload` — multipart file uploads + fetch-back + tests
+- `npx @ahmed-3m/idea2prototype add rate-limit` — per-key fixed-window limiter (429 + Retry-After headers); `rateLimit()` wraps any handler
+- `npx @ahmed-3m/idea2prototype add cors` — CORS wrapper (preflight + access-control-* headers, origin allowlists); `cors()` wraps any handler
+- `npx @ahmed-3m/idea2prototype add sse` — Server-Sent Events stream (`GET /api/events`) + heartbeats
+- `npx @ahmed-3m/idea2prototype add worker-jobs` — persistent background job queue (`data/jobs.json`, 3 attempts) with demo routes
 - `npm run check` (inside a project) — syntax + tests + boot, ~10-line verdict
-- `npx idea2prototype map` — paths + LOC + exports; read this before opening files
+- `npx @ahmed-3m/idea2prototype map` — paths + LOC + exports; read this before opening files
 
 ## Workflow
 
 1. Scaffold with `new`, then fill `PROTOTYPE.md` (Goal ≤ 3 bullets, 1–3 core flows, out-of-scope).
 2. Never hand-write files the tool owns (`server.mjs`, scaffold `tests/`, `package.json`). Add capabilities with `add`, not from scratch.
 3. After every meaningful change: `npm run check`. Read the verdict only — never run tests directly, never read raw logs.
-4. Need context? `i2p map` first; open only the files you're changing.
+4. Need context? `npx @ahmed-3m/idea2prototype map` first; open only the files you're changing.
 5. Done = check PASS + spec flows work. Report the verdict lines.

package/agents/CLAUDE.md

@@ -2,23 +2,25 @@
 
 Copy this file into any project where your coding agent should build with idea2prototype. Works with any agent that reads AGENTS.md/CLAUDE.md conventions.
 
-You have `idea2prototype` (`i2p`) available — a zero-dependency prototype tool. Use it instead of hand-writing scaffolding. If the npm package isn't installed or available, run the engine directly instead of `npx idea2prototype`: `node <path-to-idea2prototype-repo>/skills/idea2prototype/scripts/idea2prototype.mjs <command>`.
+You have `idea2prototype` (`i2p`) available — a zero-dependency prototype tool. Use it instead of hand-writing scaffolding. If the npm package isn't installed or available, run the engine directly instead of `npx @ahmed-3m/idea2prototype`: `node <path-to-idea2prototype-repo>/skills/idea2prototype/scripts/idea2prototype.mjs <command>`.
 
 ## Commands
 
-- `npx idea2prototype new <dir> --template web|api|cli|worker|library` — scaffold a running, tested project (~0 tokens vs 10–30k hand-written)
-- `npx idea2prototype add api-crud --resource <name>` — JSON-file CRUD resource + roundtrip tests
-- `npx idea2prototype add auth-local` — register/login/logout/me (scrypt + signed cookies) + tests; `requireAuth` protects other routes
-- `npx idea2prototype add upload` — multipart file uploads + fetch-back + tests
-- `npx idea2prototype add rate-limit` — per-key fixed-window limiter (429 + Retry-After headers); `rateLimit()` wraps any handler
-- `npx idea2prototype add cors` — CORS wrapper (preflight + access-control-* headers, origin allowlists); `cors()` wraps any handler
+- `npx @ahmed-3m/idea2prototype new <dir> --template web|api|cli|worker|library` — scaffold a running, tested project (~0 tokens vs 10–30k hand-written)
+- `npx @ahmed-3m/idea2prototype add api-crud --resource <name>` — JSON-file CRUD resource + roundtrip tests
+- `npx @ahmed-3m/idea2prototype add auth-local` — register/login/logout/me (scrypt + signed cookies) + tests; `requireAuth` protects other routes
+- `npx @ahmed-3m/idea2prototype add upload` — multipart file uploads + fetch-back + tests
+- `npx @ahmed-3m/idea2prototype add rate-limit` — per-key fixed-window limiter (429 + Retry-After headers); `rateLimit()` wraps any handler
+- `npx @ahmed-3m/idea2prototype add cors` — CORS wrapper (preflight + access-control-* headers, origin allowlists); `cors()` wraps any handler
+- `npx @ahmed-3m/idea2prototype add sse` — Server-Sent Events stream (`GET /api/events`) + heartbeats
+- `npx @ahmed-3m/idea2prototype add worker-jobs` — persistent background job queue (`data/jobs.json`, 3 attempts) with demo routes
 - `npm run check` (inside a project) — syntax + tests + boot, ~10-line verdict
-- `npx idea2prototype map` — paths + LOC + exports; read this before opening files
+- `npx @ahmed-3m/idea2prototype map` — paths + LOC + exports; read this before opening files
 
 ## Workflow
 
 1. Scaffold with `new`, then fill `PROTOTYPE.md` (Goal ≤ 3 bullets, 1–3 core flows, out-of-scope).
 2. Never hand-write files the tool owns (`server.mjs`, scaffold `tests/`, `package.json`). Add capabilities with `add`, not from scratch.
 3. After every meaningful change: `npm run check`. Read the verdict only — never run tests directly, never read raw logs.
-4. Need context? `i2p map` first; open only the files you're changing.
+4. Need context? `npx @ahmed-3m/idea2prototype map` first; open only the files you're changing.
 5. Done = check PASS + spec flows work. Report the verdict lines.

package/package.json

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

package/skills/idea2prototype/scripts/idea2prototype.mjs

@@ -18,7 +18,8 @@ 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.0';
+const VERSION = '0.9.1';
+const PKG_NAME = '@ahmed-3m/idea2prototype';
 const HERE = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(HERE, '..', 'templates');
 const FEATURES_DIR = join(TEMPLATES_DIR, 'features');
@@ -27,6 +28,20 @@ const TEXT_EXTENSIONS = new Set(['.md', '.json', '.html', '.js', '.mjs', '.css',
 const SAY = (...args) => console.log(...args);
 const FAIL = (...args) => console.error(...args);
 
+// The scaffold's `npm run check` must keep invoking the engine that built it.
+// From a published install (npx cache, npm i -g) the engine lives inside a
+// volatile node_modules dir that a cache clean or a second machine erases —
+// pin the registry coordinates instead, which re-fetch the exact version.
+// From a source checkout (repo clone, plugin cache) the local path is stable.
+// The JSON.stringify wrapper keeps the command embeddable in package.json.
+function engineCheckCommand() {
+  const enginePath = fileURLToPath(import.meta.url);
+  const command = enginePath.includes(join('node_modules', PKG_NAME))
+    ? `npx -y ${PKG_NAME}@${VERSION} check`
+    : `node "${enginePath}" check`;
+  return JSON.stringify(command).slice(1, -1); // embed inside the template's JSON string value
+}
+
 // ---------------------------------------------------------------------------
 // new
 // ---------------------------------------------------------------------------
@@ -58,7 +73,7 @@ async function cmdNew(rest) {
     '{{name}}': name,
     '{{slug}}': slug,
     '{{idea}}': idea,
-    __IDEA2PROTOTYPE_BIN__: JSON.stringify(fileURLToPath(import.meta.url)).slice(1, -1),
+    __IDEA2PROTOTYPE_CMD__: engineCheckCommand(),
   });
 
   const markerPath = join(target, '.idea2prototype.json');

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

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

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

@@ -5,6 +5,6 @@
   "private": true,
   "scripts": {
     "start": "node server.mjs",
-    "check": "node \"__IDEA2PROTOTYPE_BIN__\" check"
+    "check": "__IDEA2PROTOTYPE_CMD__"
   }
 }

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

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

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

@@ -5,6 +5,6 @@
   "private": true,
   "bin": { "{{slug}}": "cli.mjs" },
   "scripts": {
-    "check": "node \"__IDEA2PROTOTYPE_BIN__\" check"
+    "check": "__IDEA2PROTOTYPE_CMD__"
   }
 }

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

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

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

@@ -7,6 +7,6 @@
   "exports": { ".": "./index.mjs" },
   "files": ["index.mjs"],
   "scripts": {
-    "check": "node \"__IDEA2PROTOTYPE_BIN__\" check"
+    "check": "__IDEA2PROTOTYPE_CMD__"
   }
 }

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

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

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

@@ -5,6 +5,6 @@
   "private": true,
   "scripts": {
     "start": "node server.mjs",
-    "check": "node \"__IDEA2PROTOTYPE_BIN__\" check"
+    "check": "__IDEA2PROTOTYPE_CMD__"
   }
 }

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

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

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

@@ -5,6 +5,6 @@
   "private": true,
   "scripts": {
     "start": "node worker.mjs",
-    "check": "node \"__IDEA2PROTOTYPE_BIN__\" check"
+    "check": "__IDEA2PROTOTYPE_CMD__"
   }
 }