@fonderie/cli 0.8.0 → 0.9.0

package/bin/fonderie.mjs

@@ -477,6 +477,7 @@ else if (cmd === 'init') doInit();
 else if (cmd === 'config') resourceCmd('config', '/admin/config').catch((e) => { console.error(e.message); process.exit(1); });
 else if (cmd === 'secret') resourceCmd('secret', '/admin/secrets').catch((e) => { console.error(e.message); process.exit(1); });
 else if (cmd === 'template') resourceCmd('template', '/admin/templates').catch((e) => { console.error(e.message); process.exit(1); });
+else if (cmd === 'migrate') doMigrate().catch((e) => { console.error(e.message); process.exit(1); });
 else if (cmd === 'admin') adminCmd().catch((e) => { console.error(e.message); process.exit(1); });
 else {
   console.log(`fonderie — the Fonderie CLI (lazy skills for coding agents)
@@ -487,6 +488,12 @@ else {
   fonderie query <concept>                         what to install for a capability
   fonderie query --concepts                        list every capability
 
+  fonderie migrate --status [--app <dir>]          what is pending, and what each one will do
+  fonderie migrate --check  [--app <dir>]          exit 1 if a pending migration deletes data (CI gate)
+      reports only — the app's own runner applies, because the ORDER is the app's
+      to declare. In CI: fonderie migrate --check && npm run migrate
+      DATABASE_URL must be the SESSION or DIRECT url, never the transaction pooler
+
   fonderie config <get|set|delete|history|rollback> [key] [value] [--env <e>] [--if-version <n>] [--to-version <n>]
   fonderie secret <get|set|delete|history|rollback|reveal> [key] [value] [--env <e>] ...
   fonderie template <get|set|delete|history|rollback> [type] [text] [--locale <l>] [--subject <s>] [--html <h>] ...
@@ -501,3 +508,165 @@ else {
 Zero deps. No MCP server. A binary + markdown that runs in any agent harness.`);
   if (cmd && cmd !== 'help' && cmd !== '--help') process.exit(2);
 }
+
+// ── migrate ─────────────────────────────────────────────────────────────────
+//
+//   fonderie migrate --status     what is pending, and what each one will do
+//   fonderie migrate --check      exit 1 if any pending migration is destructive
+//
+// APPLYING IS NOT HERE, deliberately. The order migrations run in is the app's
+// to declare — it interleaves brick migrations with its own (LeadEasyGen's app
+// tables reference auth's), and a CLI guessing that order would eventually
+// guess wrong in a way that only shows up on a fresh database. The app already
+// has a runner that knows its order; this reports on it and gates it.
+//
+// The CI shape this is built for:
+//
+//   fonderie migrate --check && npm run migrate
+//
+// --check fails the deploy on a destructive migration until someone approves
+// it, because "the pipeline ran it" is no better than "the boot ran it" — it is
+// further from a human, not closer.
+//
+// Zero deps preserved: @fonderie/store is resolved from the APP's node_modules
+// (this runs inside a consuming app, where it is already installed), never
+// added as a dependency of the CLI.
+// classifyMigration landed in a later @fonderie/store; against an older one the
+// command still lists migrations, it just cannot label their impact.
+const classify = (store, sql) =>
+  typeof store.classifyMigration === 'function'
+    ? store.classifyMigration(sql)
+    : { impact: 'unknown', destructive: [] };
+
+async function doMigrate() {
+  const cwd = arg('--project', process.cwd());
+  const appDir = arg('--app', null);
+  const dry = argv.includes('--dry-run');
+  const url = process.env['DATABASE_URL'];
+  // --dry-run answers "what would these migrations do", which needs no database:
+  // it classifies every file rather than only the pending ones. Useful reviewing
+  // a PR, and it is how discovery is tested without standing a server up.
+  if (!url && !dry) {
+    console.error('migrate: set DATABASE_URL.');
+    console.error('  In CI use the SESSION or DIRECT Postgres URL, not the transaction');
+    console.error('  pooler — a pooler lends a backend per transaction.');
+    process.exit(1);
+  }
+
+  const { pathToFileURL } = await import('node:url');
+  const scope = join(cwd, 'node_modules', '@fonderie');
+
+  // These packages are ESM-only: their exports maps carry "import" but no
+  // "require", so createRequire().resolve() answers ERR_PACKAGE_PATH_NOT_EXPORTED
+  // for every one of them. Read the map and join the path instead.
+  const resolveExport = (pkg, sub) => {
+    try {
+      const pj = JSON.parse(readFileSync(join(scope, pkg, 'package.json'), 'utf8'));
+      const ent = pj.exports?.[sub];
+      const rel = typeof ent === 'string' ? ent : (ent?.import ?? ent?.default);
+      return rel ? join(scope, pkg, rel) : null;
+    } catch { return null; }
+  };
+
+  const storeEntry = resolveExport('store', '.');
+  let store;
+  try {
+    store = await import(pathToFileURL(storeEntry).href);
+  } catch {
+    console.error(`migrate: @fonderie/store is not installed in ${cwd}.`);
+    process.exit(1);
+  }
+
+  // Every installed brick that ships migrations, plus the app's own. Order is
+  // irrelevant here: this reports and classifies, it does not apply.
+  const dirs = [];
+  if (existsSync(scope)) {
+    for (const pkg of readdirSync(scope).sort()) {
+      const entry = resolveExport(pkg, './migrations');
+      if (!entry) continue; // no migrations subpath — most packages
+      try {
+        const mod = await import(pathToFileURL(entry).href);
+        if (typeof mod.getMigrationsPath === 'function') dirs.push([pkg, mod.getMigrationsPath()]);
+      } catch { /* unreadable — skip rather than fail the whole report */ }
+    }
+  }
+  if (appDir) dirs.push(['app', join(cwd, appDir)]);
+  if (dirs.length === 0) {
+    console.error('migrate: found no migrations. Pass --app <dir> for the app’s own.');
+    process.exit(1);
+  }
+
+  if (dry) {
+    let flagged = 0;
+    for (const [name, dir] of dirs) {
+      const files = readdirSync(dir).filter((f) => f.endsWith('.sql')).sort();
+      if (files.length === 0) continue;
+      console.log(`\n${name}: ${files.length} migration(s)`);
+      for (const file of files) {
+        const { impact, destructive: stmts } = classify(store, readFileSync(join(dir, file), 'utf8'));
+        if (impact === 'destructive') {
+          flagged++;
+          console.log(`  ✖ ${file}  DESTRUCTIVE`);
+          for (const st of stmts) console.log(`      ${st.slice(0, 100)}`);
+        } else {
+          console.log(`  · ${file}`);
+        }
+      }
+    }
+    console.log(`\n${flagged} of the migrations found delete data.`);
+    return;
+  }
+
+  const adapter = new store.PGAdapter(url);
+  let destructive = 0;
+  let pendingTotal = 0;
+  // A database with nothing applied yet has no data to lose: brick history
+  // legitimately drops columns earlier migrations in the same set created
+  // (billing's 004 drops the workspace_id its 001 added). Flagging those would
+  // refuse every first-time install, which is the wrong end of the trade.
+  let everApplied = false;
+  try {
+    const scanned = [];
+    for (const [name, dir] of dirs) {
+      const pending = await new store.InternalMigrationRunner(adapter, dir).pending();
+      const total = readdirSync(dir).filter((f) => f.endsWith('.sql')).length;
+      if (pending.length < total) everApplied = true;
+      scanned.push([name, dir, pending]);
+    }
+    for (const [name, dir, pending] of scanned) {
+      if (pending.length === 0) continue;
+      pendingTotal += pending.length;
+      console.log(`\n${name}: ${pending.length} pending`);
+      for (const file of pending) {
+        const sql = readFileSync(join(dir, file), 'utf8');
+        const { impact, destructive: stmts } = classify(store, sql);
+        if (impact === 'destructive' && everApplied) {
+          destructive++;
+          console.log(`  ✖ ${file}  DESTRUCTIVE`);
+          for (const s of stmts) console.log(`      ${s.slice(0, 100)}`);
+        } else {
+          console.log(`  · ${file}`);
+        }
+      }
+    }
+  } finally {
+    // The pool holds the event loop open; without this the CLI never exits.
+    await adapter.end();
+  }
+
+  if (pendingTotal === 0) {
+    console.log('up to date — nothing pending.');
+    return;
+  }
+  console.log(
+    everApplied
+      ? `\n${pendingTotal} pending, ${destructive} destructive.`
+      : `\n${pendingTotal} pending — first-time setup, nothing to lose.`,
+  );
+  if (destructive > 0 && argv.includes('--check')) {
+    console.error('\nRefusing: a pending migration deletes data. No down-migration');
+    console.error('brings it back — a recreated empty table is not a rollback. Take a');
+    console.error('backup, then approve this deploy explicitly.');
+    process.exit(1);
+  }
+}

package/bin/fonderie.test.mjs

@@ -5,7 +5,7 @@
 // Zero deps; exits non-zero on failure.
 
 import { execFileSync, execFile } from 'node:child_process';
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, symlinkSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -93,6 +93,60 @@ if (!/basic-auth/.test(addErr)) fail('add unknown-recipe error should list avail
 // help lists the add command
 if (!/fonderie add <capability>/.test(run(['help']))) fail('help missing `fonderie add`');
 
+// --- migrate: the guard that needs no database ---
+// Without DATABASE_URL it must refuse AND say which connection mode to use.
+// The pooler advice is the point: a transaction pooler lends a backend per
+// statement, and pointing a migration at one is the mistake this text exists
+// to prevent. Applying is NOT tested here — it needs a live database, and the
+// ordering it would apply belongs to the app, not this CLI.
+let migErr = '';
+try {
+  run(['migrate', '--status'], { env: { ...process.env, DATABASE_URL: '' } });
+  fail('migrate ran without DATABASE_URL');
+} catch (e) { migErr = String(e.stderr || e.stdout || ''); }
+if (!/DATABASE_URL/.test(migErr)) fail('migrate should name DATABASE_URL when it is unset');
+if (!/pooler/i.test(migErr)) fail('migrate should warn against the transaction pooler');
+if (!/fonderie migrate/.test(run(['help']))) fail('help missing `fonderie migrate`');
+console.log('  ✓ migrate guards (DATABASE_URL required, pooler warning, help listed)');
+
+// --- migrate --dry-run: discovery + classification, no database ---
+// This is the path that was broken first time round. These packages are
+// ESM-ONLY — exports maps carry "import" but no "require" — so
+// createRequire().resolve() answers ERR_PACKAGE_PATH_NOT_EXPORTED for every
+// brick, inside a catch, and the command silently discovered nothing. The fake
+// brick below is deliberately shaped that way so a regression fails here.
+{
+  const mp = mkdtempSync(join(tmpdir(), 'fonderie-migrate-'));
+  const brick = join(mp, 'node_modules', '@fonderie', 'demo');
+  const sqlDir = join(brick, 'dist', 'migrations', 'sql');
+  mkdirSync(sqlDir, { recursive: true });
+  writeFileSync(join(mp, 'package.json'), JSON.stringify({ name: 'app', type: 'module' }));
+  writeFileSync(
+    join(brick, 'package.json'),
+    JSON.stringify({
+      name: '@fonderie/demo',
+      type: 'module',
+      exports: { './migrations': { types: './dist/migrations/index.d.ts', import: './dist/migrations/index.js' } },
+    }),
+  );
+  writeFileSync(
+    join(brick, 'dist', 'migrations', 'index.js'),
+    `import { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\nexport const getMigrationsPath = () => join(dirname(fileURLToPath(import.meta.url)), 'sql');\n`,
+  );
+  writeFileSync(join(sqlDir, '001_create.sql'), 'CREATE TABLE demo (id int);');
+  writeFileSync(join(sqlDir, '002_drop.sql'), 'DROP TABLE demo CASCADE;');
+  // The real store, so classification is the shipped one and not a stub.
+  symlinkSync(join(here, '..', '..', 'store'), join(mp, 'node_modules', '@fonderie', 'store'), 'dir');
+
+  const outDry = run(['migrate', '--dry-run', '--project', mp], { env: { ...process.env, DATABASE_URL: '' } });
+  if (!/demo: 2 migration/.test(outDry)) fail('dry-run did not discover the ESM-only brick: ' + outDry);
+  if (!/001_create\.sql/.test(outDry)) fail('dry-run missed the additive migration');
+  if (!/✖ 002_drop\.sql\s+DESTRUCTIVE/.test(outDry)) fail('dry-run did not flag the drop: ' + outDry);
+  if (!/DROP TABLE demo CASCADE/.test(outDry)) fail('dry-run should print the statement that earned the label');
+  if (!/1 of the migrations found delete data/.test(outDry)) fail('dry-run summary wrong: ' + outDry);
+  console.log('  ✓ migrate --dry-run (ESM-only exports discovered, drop flagged with its statement)');
+}
+
 // ── config/secret management commands (thin client over the admin API) ──────
 // Uses async execFile so the in-process http fixture can respond (execFileSync
 // would block the event loop and deadlock the server).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fonderie/cli",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"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": [
 		"fonderiejs",