@fonderie/cli 0.1.0 → 0.2.1

package/README.md

@@ -27,6 +27,15 @@ at equal completion and quality** (`experiments/phase41-2026-07/`).
   for this capability": the package, the recipe, the wiring, and (if installed)
   the exact API. Zero resident schema tax — the agent runs it only when it needs
   discovery.
+- **`fonderie add <recipe> [--project <dir>]`** — deterministically wire a
+  capability in one command: `npm install` the recipe's bricks, emit a
+  version-matched `src/fonderie.ts` composition (modules on `FonderieApp`,
+  migrations on boot) matching the maintained `example-express`, and set up
+  `.env.example`. Prints the one app-specific line (`mount`) it leaves to you.
+  A **correctness/DX** convenience — the emitted wiring is verified to typecheck
+  against the installed packages; it is *not* a token/turn saving (an
+  auth-session pilot found the wiring isn't the turn bottleneck — see
+  `experiments/phase41-2026-07/DISCOVERY-ADD-WIRING.md`).
 
 ## How it stays correct
 

package/bin/fonderie.mjs

@@ -19,10 +19,14 @@
 import { readFileSync, readdirSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const pkgRoot = join(here, '..');
 const K = JSON.parse(readFileSync(join(pkgRoot, 'data/knowledge.json'), 'utf8'));
+// Package scope — the @fonderiejs 1.0.0 launch flips this one line (see
+// MIGRATION-FONDERIEJS.md); every scope reference below derives from it.
+const SCOPE = '@fonderie';
 const CONCEPTS = Object.entries(K.concepts || {});
 
 const argv = process.argv.slice(2);
@@ -31,7 +35,7 @@ const arg = (f, d) => { const i = argv.indexOf(f); return i >= 0 ? argv[i + 1] :
 
 // installed @fonderie packages in a project (co-located fragments are the data)
 function installed(projectDir) {
-  const dir = join(projectDir, 'node_modules', '@fonderie');
+  const dir = join(projectDir, 'node_modules', SCOPE);
   if (!existsSync(dir)) return [];
   return readdirSync(dir).sort()
     .filter((n) => existsSync(join(dir, n, 'package.json')))
@@ -57,7 +61,7 @@ function doQuery() {
   const projectDir = arg('--project', process.cwd());
   const inst = installed(projectDir).find((p) => p.name === c.package);
   console.log(`${id} — ${c.description}\n`);
-  console.log(`Package: @fonderie/${c.package}${inst ? `@${inst.version} (installed)` : ' — run: npm install @fonderie/' + c.package}`);
+  console.log(`Package: ${SCOPE}/${c.package}${inst ? `@${inst.version} (installed)` : ` — run: npm install ${SCOPE}/${c.package}`}`);
   const recipe = c.recipe && K.recipes[c.recipe];
   if (recipe) {
     console.log(`Recipe: ${c.recipe} — ${recipe.when}`);
@@ -86,7 +90,7 @@ function doSkill() {
   for (const p of inst) {
     const fr = fragment(p);
     if (!fr.signatures && !fr.outcomes) continue;
-    const body = [`# @fonderie/${p.name}@${p.version}`, '', fr.signatures, fr.outcomes ? '\n' + fr.outcomes : ''].join('\n').trim();
+    const body = [`# ${SCOPE}/${p.name}@${p.version}`, '', fr.signatures, fr.outcomes ? '\n' + fr.outcomes : ''].join('\n').trim();
     writeFileSync(join(outDir, 'fonderie', `${p.name}.md`), body + '\n');
     bodies++;
   }
@@ -104,7 +108,7 @@ function doSkill() {
   L.push('limiting, or config. Use the audited `@fonderie/*` brick. For the capability');
   L.push('your task needs, **read only that package\'s body** — do not load them all.');
   L.push('');
-  L.push(`Installed here: ${inst.length ? inst.map((p) => `\`@fonderie/${p.name}@${p.version}\``).join(', ') : 'none yet'}.`);
+  L.push(`Installed here: ${inst.length ? inst.map((p) => `\`${SCOPE}/${p.name}@${p.version}\``).join(', ') : 'none yet'}.`);
   L.push('');
   L.push('## Capability → read this / or discover');
   L.push('');
@@ -120,6 +124,23 @@ function doSkill() {
   L.push('Do NOT stop to ask permission or abandon the task; adding the brick IS the task.');
   L.push('Pick sensible defaults for provider/config choices behind fail-fast env vars.');
   L.push('');
+  L.push('## Definition of done — you do NOT need a database to build');
+  L.push('');
+  L.push('A Fonderie app is **done** when it **typechecks** (`tsc` clean) and each');
+  L.push('capability is **wired per its recipe**. That is sufficient: the bricks are');
+  L.push('audited and own their schema — migrations ship inside the package and run');
+  L.push('automatically on boot, and each route is guaranteed by the package, not by');
+  L.push('your app. (Confirmed: a typecheck-clean wired app boots, self-migrates, and');
+  L.push('serves the brick routes with no hand-written glue.)');
+  L.push('');
+  L.push('While building:');
+  L.push('- Do NOT provision a database — no `docker run`, no `initdb`, no testcontainers.');
+  L.push('- Do NOT boot the app to "check it works": a clean typecheck + correct wiring');
+  L.push('  IS the check. Running it is a separate, optional step the operator does');
+  L.push('  later with a real `DATABASE_URL`.');
+  L.push('- The tables each brick creates are listed in its body — read them, do not');
+  L.push('  reverse-engineer them from a running database.');
+  L.push('');
   if (Object.keys(K.invariants || {}).length) {
     L.push('## Security invariants (always apply)');
     L.push('');
@@ -159,14 +180,122 @@ function doInit() {
   }
 }
 
+// ── fonderie add <capability> — deterministic wiring in ONE command ─────────
+// Instead of the agent reasoning through install → migrate → compose → mount
+// across many turns, it runs ONE command that does the DETERMINISTIC part — npm
+// install, a version-matched composition module, the env template, the migration
+// step — driven by the recipe, not by LLM guessing. Emits code that matches the
+// maintained example-express composition (the ground-truth wiring), verified to
+// typecheck against the installed packages.
+//
+// Value: correctness + DX (one command → version-matched wiring that compiles),
+// NOT a token/turn saving. We prototyped it as a turn-count lever and pre-
+// registered a gate; the auth-session pilot (DISCOVERY-ADD-WIRING.md) found the
+// wiring was ~1 command's worth of a ~62-turn session — the turns live in
+// orientation + writing/testing the app's own surface, not the brick wiring —
+// so it did NOT cut turns (62 vs a 61–81 baseline). Kept as a DX feature, not
+// sold as an efficiency edge.
+//
+// Per-module wiring spec: import + construction + migrations + env. Deterministic
+// and version-matched — the installed package ships the real API these lines call.
+const MODULE_SPECS = {
+  // `order` = construction/registration priority. Lower first. auth depends on
+  // events.bus, so events (2) must precede auth (3) — the canonical example order.
+  store:  { pkg: 'store',  order: 0, import: `import { PGAdapter, MigrationRunner, InternalMigrationRunner } from '${SCOPE}/store';`, ctor: null, migrations: false },
+  core:   { pkg: 'core',   order: 1, import: `import { FonderieApp, defineConfig } from '${SCOPE}/core';`, ctor: null, migrations: false },
+  events: { pkg: 'events', order: 2, import: `import { EventsModule } from '${SCOPE}/events';\nimport { getMigrationsPath as evtMig } from '${SCOPE}/events/migrations';`,
+            varName: 'events', ctor: `const events = new EventsModule({ transport: { type: 'pg', connectionUrl: config.db.url } });`, migrations: 'evtMig()' },
+  auth:   { pkg: 'auth',   order: 3, import: `import { AuthModule } from '${SCOPE}/auth';\nimport { getMigrationsPath as authMig } from '${SCOPE}/auth/migrations';`,
+            varName: 'auth', ctor: `const auth = new AuthModule(store, {\n  jwtSecret: process.env['JWT_SECRET'] ?? 'dev-secret-min-32-chars-long-here',\n  appName: 'App',\n  providers: ['email'],\n  requireVerification: false,\n}, events.bus);`, migrations: 'authMig()',
+            env: { JWT_SECRET: 'dev-secret-min-32-chars-long-here' } },
+};
+
+function doAdd() {
+  const capability = argv[1];
+  const projectDir = arg('--project', process.cwd());
+  // resolve capability → recipe (accept a concept id, a recipe name, or a bare package)
+  let recipeName = capability;
+  if (K.concepts[capability]?.recipe) recipeName = K.concepts[capability].recipe;
+  const recipe = K.recipes[recipeName];
+  if (!recipe) {
+    console.error(`unknown capability "${capability ?? ''}". Try a concept (\`fonderie query --concepts\`) or a recipe: ${Object.keys(K.recipes).join(', ')}`);
+    process.exit(2);
+  }
+  // module set in dependency order (spec.order): store, core, then modules with
+  // deps before dependents (events before auth). Dedup, keep only recipe packages.
+  const wanted = [...new Set(['store', 'core', ...recipe.packages])];
+  const unknown = wanted.filter((p) => !MODULE_SPECS[p]);
+  const order = wanted.filter((p) => MODULE_SPECS[p]).sort((a, b) => MODULE_SPECS[a].order - MODULE_SPECS[b].order);
+  const specs = order.map((p) => MODULE_SPECS[p]);
+  if (unknown.length) {
+    console.error(`recipe "${recipeName}" needs packages this prototype can't wire yet: ${unknown.join(', ')}. Wired recipes: ${Object.entries(K.recipes).filter(([, r]) => r.packages.every((p) => MODULE_SPECS[p])).map(([n]) => n).join(', ') || '(none)'}`);
+    process.exit(3);
+  }
+  const pkgs = [...new Set(order)];
+  const registrable = specs.filter((s) => s.varName);
+
+  // 1) install (deterministic) — packages + the express adapter it mounts through
+  const installList = [...pkgs.map((p) => `${SCOPE}/${p}`), `${SCOPE}/adapter-express`];
+  console.log(`fonderie add ${recipeName}: installing ${installList.join(' ')} …`);
+  const npm = spawnSync('npm', ['install', ...installList], { cwd: projectDir, stdio: 'inherit' });
+  if (npm.status !== 0) { console.error('npm install failed — aborting before writing wiring.'); process.exit(1); }
+
+  // 2) emit the composition module (version-matched to what we just installed)
+  const migCalls = specs.filter((s) => s.migrations).map((s) => s.migrations);
+  const lines = [
+    `// GENERATED by \`fonderie add ${recipeName}\` — deterministic wiring. Safe to edit;`,
+    `// re-running \`fonderie add\` overwrites it. Composes the audited @fonderie bricks.`,
+    `import { fileURLToPath } from 'node:url';`,
+    `import { join } from 'node:path';`,
+    ...specs.map((s) => s.import),
+    ``,
+    `const __dirname = fileURLToPath(new URL('.', import.meta.url));`,
+    ``,
+    `const config = defineConfig({ db: { url: process.env['DATABASE_URL'] ?? 'postgres://localhost/app' } });`,
+    `export const store = new PGAdapter(config.db.url);`,
+    ``,
+    ...(migCalls.length ? [`for (const dir of [${migCalls.join(', ')}]) {`, `  await new InternalMigrationRunner(store, dir).run();`, `}`, ``] : []),
+    ...registrable.map((s) => s.ctor),
+    ``,
+    `export { config };`,
+    `export const fonderie = new FonderieApp(config)`,
+    ...registrable.map((s, i) => `  .register(${s.varName})${i === registrable.length - 1 ? ';' : ''}`),
+    ``,
+    `await fonderie.boot();`,
+    ``,
+  ];
+  mkdirSync(join(projectDir, 'src'), { recursive: true });
+  const compPath = join(projectDir, 'src/fonderie.ts');
+  writeFileSync(compPath, lines.join('\n'));
+  console.log(`✓ wrote src/fonderie.ts — composes ${registrable.map((s) => s.varName).join(' + ')} on FonderieApp.`);
+
+  // 3) env template (deterministic, from the spec + recipe invariants)
+  const envAdds = { DATABASE_URL: 'postgres://localhost/app', ...Object.assign({}, ...specs.map((s) => s.env || {})) };
+  const envPath = join(projectDir, '.env.example');
+  const existingEnv = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
+  let envOut = existingEnv;
+  for (const [k, v] of Object.entries(envAdds)) if (!new RegExp(`^${k}=`, 'm').test(envOut)) envOut += `${envOut && !envOut.endsWith('\n') ? '\n' : ''}${k}=${v}\n`;
+  if (envOut !== existingEnv) { writeFileSync(envPath, envOut); console.log(`✓ .env.example — added ${Object.keys(envAdds).join(', ')}`); }
+
+  // 4) the ONE app-specific line the agent still owns — printed, not guessed
+  console.log(`\nDone. Two lines left for your app entry (e.g. src/index.ts):`);
+  console.log(`    import { mount } from '${SCOPE}/adapter-express';`);
+  console.log(`    import { fonderie } from './fonderie';`);
+  console.log(`  then wrap your express app:  const app = mount(express(), fonderie);`);
+  for (const inv of recipe.invariants || []) if (K.invariants[inv]) console.log(`  ⚠ ${K.invariants[inv]}`);
+  console.log(`\nMigrations run automatically on boot (InternalMigrationRunner above). Set DATABASE_URL and start the app.`);
+}
+
 // ── dispatch ────────────────────────────────────────────────────────────────
 if (cmd === 'query') doQuery();
 else if (cmd === 'skill') doSkill();
+else if (cmd === 'add') doAdd();
 else if (cmd === 'init') doInit();
 else {
   console.log(`fonderie — the Fonderie CLI (lazy skills for coding agents)
 
   fonderie init [--project <dir>]                  set up the lazy skill + keep it fresh (postinstall)
+  fonderie add <capability> [--project <dir>]      deterministically wire a brick: install + compose + migrate + env
   fonderie skill [--out <dir>] [--project <dir>]   write the lazy skill (router + bodies)
   fonderie query <concept>                         what to install for a capability
   fonderie query --concepts                        list every capability

package/bin/fonderie.test.mjs

@@ -77,4 +77,13 @@ run(['init', '--project', proj3]);
 const pj3 = JSON.parse(readFileSync(join(proj3, 'package.json'), 'utf8'));
 if (pj3.scripts.postinstall !== 'patch-package && fonderie skill') fail(`init did not chain existing postinstall (got: ${pj3.scripts.postinstall})`);
 
-console.log('fonderie CLI test: all assertions passed (skill, query installed/uninstalled, init wires idempotent fresh-keeping postinstall)');
+// --- add: offline guards (the happy path installs from npm — not unit-tested) ---
+// unknown capability → non-zero, lists the recipes (no network touched)
+let addErr = '';
+try { run(['add', 'not-a-recipe', '--project', proj]); fail('add accepted an unknown recipe'); }
+catch (e) { addErr = String(e.stderr || e.stdout || ''); }
+if (!/basic-auth/.test(addErr)) fail('add unknown-recipe error should list available recipes');
+// help lists the add command
+if (!/fonderie add <capability>/.test(run(['help']))) fail('help missing `fonderie add`');
+
+console.log('fonderie CLI test: all assertions passed (skill, query installed/uninstalled, init wires idempotent fresh-keeping postinstall, add guards)');

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fonderie/cli",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"description": "The Fonderie CLI — teaches any coding agent the SDK without loading it eagerly. `fonderie skill` writes a lazy skill (a small router + per-package bodies read on demand); `fonderie query` answers what to install for a capability. Zero deps, runs anywhere.",
 	"keywords": [
 		"fonderie-js",