@metaobjectsdev/cli 0.24.4 → 0.24.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/cli",
-  "version": "0.24.4",
+  "version": "0.24.5",
   "description": "CLI for MetaObjects: scaffold, codegen, migrate, and drift-detection commands.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -49,15 +49,15 @@
   ],
   "dependencies": {
     "@libsql/kysely-libsql": "^0.4.0",
-    "@metaobjectsdev/codegen-ts": "0.24.4",
-    "@metaobjectsdev/codegen-ts-react": "0.24.4",
-    "@metaobjectsdev/codegen-ts-tanstack": "0.24.4",
-    "@metaobjectsdev/docs-site": "0.24.4",
-    "@metaobjectsdev/metadata": "0.24.4",
-    "@metaobjectsdev/migrate-ts": "0.24.4",
-    "@metaobjectsdev/render": "0.24.4",
-    "@metaobjectsdev/runtime-ts": "0.24.4",
-    "@metaobjectsdev/sdk": "0.24.4",
+    "@metaobjectsdev/codegen-ts": "0.24.5",
+    "@metaobjectsdev/codegen-ts-react": "0.24.5",
+    "@metaobjectsdev/codegen-ts-tanstack": "0.24.5",
+    "@metaobjectsdev/docs-site": "0.24.5",
+    "@metaobjectsdev/metadata": "0.24.5",
+    "@metaobjectsdev/migrate-ts": "0.24.5",
+    "@metaobjectsdev/render": "0.24.5",
+    "@metaobjectsdev/runtime-ts": "0.24.5",
+    "@metaobjectsdev/sdk": "0.24.5",
     "@toon-format/toon": "^2.3.0",
     "jiti": "^2.4.0"
   },
@@ -76,7 +76,7 @@
     "@types/pg": "^8.0.0",
     "bun-types": "latest",
     "drizzle-orm": "^0.45.1",
-    "fastify": "^4.28.1",
+    "fastify": "^5.6.2",
     "kysely": "^0.27.0",
     "pg": "^8.0.0",
     "pg-mem": "^3.0.4",

package/src/commands/eject.ts

@@ -0,0 +1,282 @@
+// FR-040 §4.2(a) — `meta eject <generator>` takes ownership of any reference-template
+// generator, in any package, at any time after `meta init`. ADR-0034 scaffold-and-own
+// has `init` copy four of them eagerly (entity, queries, routes, barrel); this is the
+// SAME copy operation, generalised to every ejectable name and callable on demand — for
+// a generator you skipped at init time, or one a package gained since.
+import { mkdir, writeFile, stat, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { cliVersion } from "../lib/version.js";
+import * as coreTpl from "@metaobjectsdev/codegen-ts";
+import * as reactTpl from "@metaobjectsdev/codegen-ts-react";
+import * as tanstackTpl from "@metaobjectsdev/codegen-ts-tanstack";
+import { parseEjectArgs } from "../lib/args.js";
+import { log } from "../lib/log.js";
+import { declaredDependencyNames, readPackageManifest } from "../lib/package-manifest.js";
+
+// Mirrors `OWNED_GENERATORS_DIR` in init.ts's `writeOwnedGenerators` — same directory,
+// same never-clobber-without-consent contract. Kept as its own local constant rather
+// than shared: eject is a standalone operation on ANY name, not a byproduct of init,
+// and the two call sites have no other state in common worth coupling over one string.
+const OWNED_GENERATORS_DIR = "codegen/generators";
+
+interface TemplateSource {
+  packageName: string;
+  names: readonly string[];
+  /** That package's own `src/reference/` directory. */
+  root: () => string;
+}
+
+// One registry, three packages — a package that gains templates later registers itself
+// here and `meta eject` picks it up with no other change.
+//
+// Each entry exposes its reference ROOT rather than a read function. The packages' own
+// `readReferenceTemplate` narrows its parameter to a literal union, so calling it with
+// a CLI-supplied `string` used to need a generic `asserts name is N` helper — ~20 lines
+// to re-establish, for the compiler, a fact `resolveSource` has ALREADY established at
+// runtime by selecting this entry via `names.includes(name)`. Reading from the root
+// deletes that machinery without weakening anything: membership is still checked, once,
+// where the untrusted value enters.
+const SOURCES: TemplateSource[] = [
+  {
+    packageName: "@metaobjectsdev/codegen-ts",
+    names: coreTpl.REFERENCE_GENERATOR_NAMES,
+    root: coreTpl.resolveReferenceRoot,
+  },
+  {
+    packageName: "@metaobjectsdev/codegen-ts-react",
+    names: reactTpl.REFERENCE_GENERATOR_NAMES,
+    root: reactTpl.resolveReferenceRoot,
+  },
+  {
+    packageName: "@metaobjectsdev/codegen-ts-tanstack",
+    names: tanstackTpl.REFERENCE_GENERATOR_NAMES,
+    root: tanstackTpl.resolveReferenceRoot,
+  },
+];
+
+function resolveSource(name: string): TemplateSource | undefined {
+  return SOURCES.find((s) => s.names.includes(name));
+}
+
+/** Every ejectable name, in registry order (stable — matches `meta eject --list`). */
+export function ejectableNames(): string[] {
+  return SOURCES.flatMap((s) => s.names);
+}
+
+// Every reference template's header documents its own paste-ready import line, e.g.
+// codegen-ts/src/reference/entity.ts:
+//   // Then import it LOCALLY in metaobjects.config.ts:
+//   //   import { entityFile } from "./codegen/generators/entity.js";
+// Extracting it here — rather than re-deriving an export symbol from the file name —
+// means eject can never drift from what the template itself already tells a human to
+// paste, and needs no per-name export-symbol map: a generator's exported symbol does
+// NOT follow its file name (`hooks.ts` exports `tanstackQuery`, `routes-hono.ts`
+// exports `routesFileHono`, `grid.ts` exports `tanstackGrid`).
+const HEADER_IMPORT_RE = /^\/\/\s+(import \{ \w+ \} from "\.\/codegen\/generators\/[\w.-]+\.js";)\s*$/m;
+
+/** The bound symbol out of the already-validated import line — same single source of
+ *  truth as the line itself, so the "replace this binding" message can never name a
+ *  symbol the template does not actually export. */
+function extractExportName(importLine: string, name: string): string {
+  const match = /^import \{ (\w+) \}/.exec(importLine);
+  if (!match?.[1]) {
+    throw new Error(`reference template "${name}" has an unparseable import line: ${importLine}`);
+  }
+  return match[1];
+}
+
+function extractImportLine(templateSource: string, name: string): string {
+  const match = HEADER_IMPORT_RE.exec(templateSource);
+  if (!match?.[1]) {
+    throw new Error(
+      `reference template "${name}" has no documented "// import { ... }" header line — ` +
+        "cannot report the import line to paste.",
+    );
+  }
+  return match[1];
+}
+
+async function fileExists(p: string): Promise<boolean> {
+  try {
+    return (await stat(p)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export interface EjectOptions {
+  cwd: string;
+  name: string;
+  /** Overwrite an already-ejected file. Without it, eject NEVER clobbers — matching
+   *  `writeOwnedGenerators`'s unconditional preserve-if-present rule in init.ts. */
+  force?: boolean;
+}
+
+export interface EjectResult {
+  path: string;
+  importLine: string;
+  /** The symbol the template exports — the binding to REPLACE in the config. */
+  exportName: string;
+  /** The package the generator currently comes from, i.e. the import to remove. */
+  packageName: string;
+  /** Advisory lines about packages the ejected file imports but the project lacks. */
+  dependencyNotes: string[];
+  status: "created" | "preserved";
+}
+
+/** The `@metaobjectsdev/*` packages an ejected template imports, read from the file
+ *  itself rather than from a per-name table — the template is the only thing that
+ *  knows, and a table would drift from it the moment a template gains an import. */
+function requiredPackages(templateSource: string): string[] {
+  const found = new Set<string>();
+  // The optional trailing group matches a SUBPATH and is deliberately not captured: what
+  // has to be installed is the package, and `@metaobjectsdev/metadata/constants` is a
+  // real, documented subpath this codebase already uses (the browser-safe pure-constants
+  // entry). Requiring the closing quote straight after the package name — as this did —
+  // made any such import match nothing at all, so a template gaining one would get no
+  // note. That is the drift this function exists to prevent, reappearing inside the
+  // function itself.
+  for (const m of templateSource.matchAll(/from\s+"(@metaobjectsdev\/[\w-]+)(?:\/[\w./-]+)?"/g)) {
+    if (m[1] !== undefined) found.add(m[1]);
+  }
+  return [...found].sort();
+}
+
+/**
+ * An ejected file is ordinary source in the adopter's repo, so its imports must be
+ * declared dependencies or their `tsc` reports TS2307 on the file we just told them
+ * they own — and under a strict (pnpm/npm) node_modules layout `meta gen` cannot
+ * resolve it either. `meta init` already calls this out by ADDING the two packages its
+ * four scaffolded generators need; the on-demand templates import two more
+ * (codegen-ts-react, codegen-ts-tanstack) that nothing declares.
+ *
+ * This REPORTS rather than edits: init is a scaffolder writing a whole project and has
+ * a manifest in hand, while eject copies one file into a repo whose dependency policy
+ * (workspace protocol, catalog, pinned ranges) is the adopter's. Naming the exact
+ * missing package and the version to match is the useful half; silently rewriting
+ * someone's manifest is not.
+ */
+export async function dependencyNotesForTemplate(cwd: string, templateSource: string): Promise<string[]> {
+  const required = requiredPackages(templateSource);
+  if (required.length === 0) return [];
+
+  const pkg = readPackageManifest(cwd);
+  if (pkg === undefined) {
+    // No readable manifest — say what the file needs and let the adopter place it.
+    return [`This file imports: ${required.join(", ")}. Make sure each is installed.`];
+  }
+  const declared = declaredDependencyNames(pkg);
+
+  const missing = required.filter((p) => !declared.has(p));
+  if (missing.length === 0) return [];
+  return [
+    `The ejected file imports ${missing.join(", ")}, which your package.json does not ` +
+    "declare — your typecheck will report TS2307 until it does. Install with:",
+    `  npm i -D ${missing.map((p) => `${p}@^${cliVersion()}`).join(" ")}`,
+  ];
+}
+
+export async function ejectGenerator(opts: EjectOptions): Promise<EjectResult> {
+  const source = resolveSource(opts.name);
+  if (source === undefined) {
+    throw new Error(
+      `unknown generator "${opts.name}". Ejectable generators: ${ejectableNames().join(", ")}. ` +
+        "Run `meta eject --list` to see them grouped by package.",
+    );
+  }
+
+  const templateSource = await readFile(join(source.root(), `${opts.name}.ts`), "utf8");
+  const importLine = extractImportLine(templateSource, opts.name);
+  const exportName = extractExportName(importLine, opts.name);
+  const rel = `${OWNED_GENERATORS_DIR}/${opts.name}.ts`;
+  const abs = join(opts.cwd, rel);
+  const notes = await dependencyNotesForTemplate(opts.cwd, templateSource);
+  const common = {
+    path: rel,
+    importLine,
+    exportName,
+    packageName: source.packageName,
+    dependencyNotes: notes,
+  };
+
+  if (!opts.force && (await fileExists(abs))) {
+    return { ...common, status: "preserved" };
+  }
+
+  await mkdir(join(opts.cwd, OWNED_GENERATORS_DIR), { recursive: true });
+  await writeFile(abs, templateSource, "utf8");
+  return { ...common, status: "created" };
+}
+
+function listOutput(): string {
+  const lines: string[] = [];
+  lines.push("Ejectable generators (copy any of these into codegen/generators/ and own it):");
+  lines.push("");
+  for (const source of SOURCES) {
+    lines.push(`${source.packageName}:`);
+    lines.push(`  ${source.names.join(", ")}`);
+    lines.push("");
+  }
+  lines.push("Run: meta eject <name>");
+  return lines.join("\n");
+}
+
+export async function ejectCommand(args: string[], cwd: string): Promise<number> {
+  let flags;
+  try {
+    flags = parseEjectArgs(args);
+  } catch (err) {
+    log.error((err as Error).message);
+    return 2;
+  }
+
+  if (flags.list) {
+    log.info(listOutput());
+    return 0;
+  }
+
+  if (flags.name === undefined) {
+    log.error("meta eject requires a generator name, or --list to see what's ejectable.");
+    return 2;
+  }
+
+  try {
+    const result = await ejectGenerator({ cwd, name: flags.name, force: flags.force });
+    if (result.status === "preserved") {
+      log.info(`${result.path} already exists — left untouched (pass --force to overwrite).`);
+    } else {
+      log.info(`Ejected "${flags.name}" -> ${result.path}. You own it now (ADR-0034 scaffold-and-own).`);
+    }
+    // REPLACE, never "paste". A generator reaches `generators: [...]` under ONE binding,
+    // so a reader told to "paste" gets a duplicate identifier at best — and at worst
+    // deletes nothing, keeps `formFile()` in the array bound to the PACKAGE import, and
+    // silently runs the packaged generator while editing the ejected file. That failure
+    // is invisible and is the exact one ejecting exists to prevent.
+    //
+    // But eject reads no config, so it cannot know WHICH of the three states this project
+    // is in, and stating one of them as fact is wrong in the other two — including for the
+    // four `meta init` scaffolds, whose config already imports from ./codegen/generators/,
+    // which is precisely the `meta eject <name> --force` re-sync case. Name the goal, then
+    // the three branches; the reader knows which one they are looking at.
+    log.info(`In metaobjects.config.ts, "${result.exportName}" must resolve to this file:`);
+    log.info(`  ${result.importLine}`);
+    log.info(
+      `  - If it is imported from "${result.packageName}", REPLACE that import with the ` +
+      "line above. Adding a second one leaves `generators` bound to the PACKAGED " +
+      "generator, and your edits to this file do nothing.",
+    );
+    log.info(
+      "  - If it is already imported from ./codegen/generators/ (what `meta init` " +
+      "scaffolds), it points here already — nothing to change.",
+    );
+    log.info(
+      `  - If ${result.exportName}() is not in \`generators\` yet, add the import above ` +
+      "AND the entry.",
+    );
+    for (const line of result.dependencyNotes) log.info(line);
+    return 0;
+  } catch (err) {
+    log.error((err as Error).message);
+    return 1;
+  }
+}

package/src/commands/init.ts

@@ -11,13 +11,34 @@ import { resolveStack } from "../lib/detect-stack.js";
 import { parseInitArgs } from "../lib/args.js";
 import { log } from "../lib/log.js";
 import { cliVersion } from "../lib/version.js";
+import { declaredDependencyNames, type PackageManifest } from "../lib/package-manifest.js";
 import { findWranglerConfig, parseWranglerConfig } from "@metaobjectsdev/migrate-ts";
-import { readReferenceTemplate, REFERENCE_GENERATOR_NAMES } from "@metaobjectsdev/codegen-ts";
+import { readReferenceTemplate, type ReferenceGeneratorName } from "@metaobjectsdev/codegen-ts";
 
 // ADR-0034 scaffold-and-own — `meta init` copies the codegen reference templates into
 // the consumer's repo so they OWN them; metaobjects.config.ts imports them locally.
 const OWNED_GENERATORS_DIR = "codegen/generators";
 
+// The FOUR reference generators `meta init` copies EAGERLY — deliberately an explicit
+// literal, not derived from @metaobjectsdev/codegen-ts's REFERENCE_GENERATOR_NAMES (the
+// full list of everything `meta eject` can copy). Looping over that array unconditionally
+// used to mean init scaffolded whatever it contained: when a later task registered
+// "routes-hono" there, init started writing an unwired Hono generator nothing in the
+// scaffolded config imports, on every fresh project, silently. This constant is the
+// scaffolded metaobjects.config.ts's import list (buildMetaobjectsConfigBody below) made
+// explicit and checkable — anything else is eject-on-demand via `meta eject <name>`, which
+// exists exactly so eager copying isn't the only way to take ownership of a template.
+const SCAFFOLDED_GENERATOR_NAMES: readonly ReferenceGeneratorName[] = ["entity", "queries", "routes", "barrel"];
+
+// The scaffolded config's outDir + dbImport, as named constants so the throwing-stub
+// path below is DERIVED from the same values the config template embeds rather than
+// duplicated as a second literal that could drift from it.
+const SCAFFOLD_OUT_DIR = "src/generated";
+const SCAFFOLD_DB_IMPORT = "../db";
+// "src/generated" + "../db" -> "src/db" -> "src/db.ts" (dbImport resolves relative
+// to outDir, same as the module specifier a generated route file emits).
+const DB_STUB_REL_PATH = `${join(SCAFFOLD_OUT_DIR, SCAFFOLD_DB_IMPORT)}.ts`;
+
 const META_COMMON_JSON = JSON.stringify(
   {
     metadata: {
@@ -87,9 +108,18 @@ import { routesFile } from "./codegen/generators/routes.js";
 import { barrel } from "./codegen/generators/barrel.js";
 
 export default defineConfig({
-  outDir:    "src/generated",
-  extStyle:  "js",   // ".js"-extensioned relative imports — safe under Node ESM / tsc nodenext AND bundlers
-  dbImport:  "../db",
+  outDir:    "${SCAFFOLD_OUT_DIR}",
+  extStyle:  "js",   // ".js"-extensioned relative imports — correct for Node ESM and \`tsc\` with
+                     // nodenext, which is what a fresh project has. BUNDLERS DISAGREE: this fails
+                     // outright under Turbopack (even between two generated files, so the whole
+                     // generated tree goes unresolvable), while Vite and esbuild accept it and
+                     // webpack needs \`resolve.extensionAlias\`. If a generated import fails to
+                     // resolve, set "none" and retest — do not assume this line covers your bundler.
+  dbImport:  "${SCAFFOLD_DB_IMPORT}",   // routesFile() below emits \`import { db } from …\` — meta init
+                        // scaffolded ${DB_STUB_REL_PATH} as a THROWING STUB (types clean, no
+                        // driver chosen) so meta gen and tsc pass; replace it with your real
+                        // Drizzle connection before running the app.
+                        // (queriesFile() takes db as a parameter and never reads this.)
   dialect:   "${dialect}",
   apiPrefix: "",     // set to "/api" if your routes mount under /api
   generators: [
@@ -107,10 +137,76 @@ export default defineConfig({
 `;
 }
 
-const NEXT_STEPS = `
+// The throwing-stub scaffolded at `dbImport`'s resolved path (DB_STUB_REL_PATH,
+// "src/db.ts" by default). It exists so `meta gen` and a fresh project's FIRST
+// `tsc` both succeed with no driver chosen and no dependency added — deliberately
+// NOT a real connection. Every generated route only ever passes `db` straight
+// through to `mountCrudRoutes(...)`; nothing reads a property off it at import
+// time, so a value typed `unknown` (not `any`) satisfies every call site while
+// making a genuine runtime use (mountCrudRoutes calling `db.select()` etc.) throw
+// immediately with an actionable message instead of failing to resolve at all.
+// Built as an array of plain single-quoted lines (not a template literal) so the
+// backticks and quotes inside the comment/message need no escaping.
+const DB_STUB_BODY = [
+  "// `meta init` scaffolded this file because the generated Fastify routes",
+  '// `import { db } from "../db.js"` (see `dbImport` in metaobjects.config.ts) —',
+  "// a module that has to exist for `meta gen` and `tsc` to succeed. MetaObjects",
+  "// cannot fill it in for real without choosing a database driver on your",
+  "// behalf (better-sqlite3 vs @libsql/client vs pg vs postgres.js) and adding a",
+  "// dependency you may not want, so this is a STUB, not a connection.",
+  "//",
+  "// It type-checks and satisfies every generated import, but throws the first",
+  "// time anything actually touches `db` at runtime. Replace the export below",
+  "// with your real Drizzle connection, e.g.:",
+  "//",
+  '//   import { drizzle } from "drizzle-orm/better-sqlite3";',
+  '//   import Database from "better-sqlite3";',
+  '//   export const db = drizzle(new Database("dev.sqlite"));',
+  "//",
+  "// (swap the driver import for your dialect — see",
+  "// https://github.com/metaobjectsdev/metaobjects/blob/main/docs/recipes/wiring-generated-queries.md",
+  "// for SQLite/libsql, Cloudflare D1, Postgres and multi-tenant setups.)",
+  "",
+  "const UNWIRED_MESSAGE =",
+  '  "src/db.ts is still the scaffolded stub meta init wrote — it cannot choose " +',
+  "  \"a database driver for you. Replace 'export const db = ...' below with \" +",
+  '  "your real Drizzle connection, e.g.:\\n\\n" +',
+  "  \"  import { drizzle } from 'drizzle-orm/better-sqlite3';\\n\" +",
+  "  \"  import Database from 'better-sqlite3';\\n\" +",
+  "  \"  export const db = drizzle(new Database('dev.sqlite'));\\n\";",
+  "",
+  "function unwired(): never {",
+  "  throw new Error(UNWIRED_MESSAGE);",
+  "}",
+  "",
+  "/**",
+  " * Stand-in for your real Drizzle database connection. Generated code only",
+  " * ever passes `db` straight through to `mountCrudRoutes(...)` — it never",
+  " * reads a property off it at import time — so this typechecks everywhere",
+  " * `db` is used, and throws the message above the first time anything really",
+  " * touches it.",
+  " */",
+  "export const db: unknown = new Proxy({}, { get: unwired });",
+  "",
+].join("\n");
+
+// Printed only when the stub was ACTUALLY written this run. It is gated on having just
+// written the scaffolded config (see the db-stub block in `init`), so a re-run in a
+// project that keeps its own config writes nothing — and a block claiming otherwise is
+// the same "asserting things about its own scaffold that aren't true" defect the rest of
+// this file was corrected for.
+const DB_STUB_NOTE = `Also scaffolded ${DB_STUB_REL_PATH}: a THROWING STUB standing in for your database
+connection, so the generated routes' \`db\` import resolves and the first tsc is clean.
+Replace it with a real connection before running the app — until you do, the first
+request that touches \`db\` throws with instructions.
+`;
+
+const SCAFFOLD_SUMMARY = `
 Initialized metaobjects/ + .metaobjects/ + metaobjects.config.ts
 Codegen generators copied to codegen/generators/ — they're YOURS to edit (ADR-0034 scaffold-and-own).
+`;
 
+const NEXT_STEPS = `
 Next steps:
   0. Everything here is ESM — package.json needs "type": "module" (init sets it
      unless the project has CommonJS sources; without it the first tsc fails).
@@ -329,11 +425,16 @@ async function wireRootMemory(cwd: string, result: InitResult, dryRun = false):
  * `codegen/generators/<name>.ts` so they own them. Each file is written only if absent,
  * so a re-run with --force never clobbers a hand-edited generator. The scaffolded
  * metaobjects.config.ts imports these local copies (not the package `/generators` export).
+ *
+ * Copies SCAFFOLDED_GENERATOR_NAMES only — the four the scaffolded config actually
+ * wires — not every name @metaobjectsdev/codegen-ts happens to register. Anything else
+ * (routes-hono, and any UI-tier template from codegen-ts-react/-tanstack) is reached with
+ * `meta eject <name>`, not by eager copying.
  */
 async function writeOwnedGenerators(opts: InitOptions, result: InitResult): Promise<void> {
   const dir = join(opts.cwd, OWNED_GENERATORS_DIR);
   await mkdir(dir, { recursive: true });
-  for (const name of REFERENCE_GENERATOR_NAMES) {
+  for (const name of SCAFFOLDED_GENERATOR_NAMES) {
     const rel = `${OWNED_GENERATORS_DIR}/${name}.ts`;
     const abs = join(dir, `${name}.ts`);
     if (await fileExists(abs)) {
@@ -475,8 +576,8 @@ export async function init(opts: InitOptions): Promise<InitResult> {
       `.metaobjects/${PACKAGE_MANIFEST_FILE}`,
     );
     result.created.push(".metaobjects/AGENTS.md", ".metaobjects/CLAUDE.md", ".claude/skills/metaobjects-*", AGENT_CONTEXT_MANIFEST_PATH);
-    for (const name of REFERENCE_GENERATOR_NAMES) result.created.push(`${OWNED_GENERATORS_DIR}/${name}.ts`);
-    result.created.push("metaobjects.config.ts", ".gitignore");
+    for (const name of SCAFFOLDED_GENERATOR_NAMES) result.created.push(`${OWNED_GENERATORS_DIR}/${name}.ts`);
+    result.created.push("metaobjects.config.ts", DB_STUB_REL_PATH, ".gitignore");
     return result;
   }
 
@@ -524,11 +625,54 @@ export async function init(opts: InitOptions): Promise<InitResult> {
 
   // Scaffold metaobjects.config.ts at the project root. Never overwrite if it exists.
   const forgeConfigPath = join(opts.cwd, "metaobjects.config.ts");
-  if (!(await fileExists(forgeConfigPath))) {
+  const wroteScaffoldedConfig = !(await fileExists(forgeConfigPath));
+  if (wroteScaffoldedConfig) {
     await writeFile(forgeConfigPath, buildMetaobjectsConfigBody(opts.d1 ? "d1" : "sqlite"), "utf8");
     result.created.push("metaobjects.config.ts");
   }
 
+  // Scaffold the `dbImport` throwing stub at DB_STUB_REL_PATH ("src/db.ts" by
+  // default) — ONLY if absent, so a re-run never clobbers a user's real db module
+  // (same "write once" precedent as writeOwnedGenerators above). Without this, the
+  // scaffolded config declares `dbImport: "../db"` pointing at a module `meta init`
+  // never creates, and a fresh project's FIRST `tsc` fails to resolve it.
+  //
+  // Gated on having just WRITTEN that config, not merely on the stub being absent.
+  // DB_STUB_REL_PATH is derived from SCAFFOLD_OUT_DIR + SCAFFOLD_DB_IMPORT — the
+  // scaffold's own constants — so it describes where the SCAFFOLDED config points and
+  // nowhere else. Re-running `meta init` in a project that already has a config with
+  // its own `outDir`/`dbImport` preserves that config (above) and would otherwise still
+  // drop a src/db.ts that nothing in the project references: a stray file, in the
+  // adopter's application source, answering a question they had already answered.
+  const dbStubPath = join(opts.cwd, DB_STUB_REL_PATH);
+  const dbStubExists = await fileExists(dbStubPath);
+  if (wroteScaffoldedConfig && !dbStubExists) {
+    await mkdir(dirname(dbStubPath), { recursive: true });
+    await writeFile(dbStubPath, DB_STUB_BODY, "utf8");
+    result.created.push(DB_STUB_REL_PATH);
+  } else if (dbStubExists) {
+    // "preserved" means a file we would have written was left alone. Skipping because
+    // this project keeps its own config is not preservation — there is nothing there.
+    result.preserved.push(DB_STUB_REL_PATH);
+  } else {
+    // Neither written nor preserved: this project keeps its own config AND has no stub.
+    // Usually correct — its `dbImport` points at a real module somewhere else. But it is
+    // ALSO what a scaffolded project looks like after someone deletes or moves src/db.ts,
+    // and `meta init --force` cannot tell those apart: `wroteScaffoldedConfig` is only
+    // "no config existed", so it is false for the config init itself wrote. Silently
+    // doing nothing there leaves the scaffolded `dbImport: "../db"` and the generated
+    // routes' `import { db } from "../db.js"` pointing at nothing, and the adopter meets
+    // it as a TS2307 from `tsc` with no word from the command that could have said so.
+    // Say it here rather than writing: dropping a file into a project that owns its
+    // config is what the branch above deliberately refuses.
+    result.warnings.push(
+      `${DB_STUB_REL_PATH} was not scaffolded — this project has its own ` +
+      "metaobjects.config.ts, so init leaves the database module to it. If that config's " +
+      `\`dbImport\` resolves to ${DB_STUB_REL_PATH}, create it or the generated routes will ` +
+      "not resolve.",
+    );
+  }
+
   // Scaffold a minimal root .gitignore ONLY when the project has none — never
   // clobber a user's existing one (they may have their own rules).
   const rootGitignorePath = join(opts.cwd, ".gitignore");
@@ -598,6 +742,7 @@ async function ensureEsmPackageType(cwd: string, result: InitResult): Promise<vo
     return;
   }
 
+  const declaredType = pkg.type;   // read BEFORE the mutation below overwrites it
   pkg.type = "module";
   const added = addScaffoldDevDependencies(pkg);
   // Preserve the file's existing indentation rather than reformatting someone's manifest.
@@ -606,9 +751,16 @@ async function ensureEsmPackageType(cwd: string, result: InitResult): Promise<vo
   // Past tense, deliberately: this reports an edit already made. The imperative
   // ("set `\"type\": \"module\"`") read as a TODO on the one line a newcomer sees
   // last, so a scaffold that had just done the right thing looked like it had failed.
+  //
+  // And it must not claim the manifest was SILENT on the point: `npm init -y` writes
+  // `"type": "commonjs"` explicitly (npm 11.x), which is the dominant first-touch path,
+  // so "declared no module system" was false exactly where it is read most. Report what
+  // was actually there.
+  const previous = typeof declaredType === "string" ? declaredType : undefined;
   result.warnings.push(
-    'package.json declared no module system — set `"type": "module"` for you, because ' +
-      "MetaObjects scaffolds and generates ESM, which a CommonJS project cannot compile.",
+    `package.json ${previous === undefined ? "declared no module system" : `declared "type": "${previous}"`} — ` +
+      'set `"type": "module"` for you, because MetaObjects scaffolds and generates ESM, ' +
+      "which a CommonJS project cannot compile.",
   );
   if (added.length > 0) {
     result.warnings.push(
@@ -643,10 +795,17 @@ function addScaffoldDevDependencies(pkg: Record<string, unknown>): string[] {
     "@metaobjectsdev/metadata": `^${version}`,
   };
   const dev = (pkg.devDependencies ?? {}) as Record<string, string>;
-  const deps = (pkg.dependencies ?? {}) as Record<string, string>;
+  // "Already declared" spans all four dependency fields — the shared rule, so this
+  // cannot drift from what `meta eject` means by the same words. It used to ask only
+  // dependencies + devDependencies, which meant a project declaring codegen-ts as a
+  // PEER dependency (correct for a library whose consumer supplies the version) got it
+  // added to devDependencies as well: the same package pinned twice in one manifest,
+  // and a second physical copy is the class-identity split this repo has been bitten
+  // by twice.
+  const declared = declaredDependencyNames(pkg as PackageManifest);
   const added: string[] = [];
   for (const [name, range] of Object.entries(wanted)) {
-    if (dev[name] !== undefined || deps[name] !== undefined) continue;
+    if (declared.has(name)) continue;
     dev[name] = range;
     added.push(name);
   }
@@ -697,8 +856,18 @@ function buildD1MigrateBlock(cwd: string): Record<string, unknown> {
   return block;
 }
 
-export function nextStepsBlock(): string {
-  return NEXT_STEPS;
+/**
+ * The post-init message.
+ *
+ * @param dbStubWritten whether THIS run wrote {@link DB_STUB_REL_PATH}. Required rather
+ *   than defaulted, because a default would silently restore the bug this parameter
+ *   exists to close: the note used to be part of one static string and so claimed the
+ *   stub on every run, including the `meta init --force` in a project keeping its own
+ *   `metaobjects.config.ts`, where the stub is deliberately not written. Callers pass
+ *   `result.created.includes(DB_STUB_REL_PATH)` — the same list the message describes.
+ */
+export function nextStepsBlock(dbStubWritten: boolean): string {
+  return SCAFFOLD_SUMMARY + (dbStubWritten ? DB_STUB_NOTE : "") + NEXT_STEPS;
 }
 
 async function dirExists(p: string): Promise<boolean> {
@@ -763,7 +932,7 @@ export async function initCommand(args: string[], cwd: string): Promise<number>
         }
         for (const w of result.warnings) log.warn(w);
       } else {
-        log.info(nextStepsBlock());
+        log.info(nextStepsBlock(result.created.includes(DB_STUB_REL_PATH)));
         // Surface any scaffold warnings (e.g. the #77 monorepo-subdir agent-context
         // discovery warning) — these are otherwise dropped on the normal init path.
         for (const w of result.warnings) log.warn(w);

package/src/commands/verify.ts

@@ -949,9 +949,16 @@ export async function verifyCommand(
     if (result.changes.length === 0) return [];
 
     return [
+      // `meta migrate --from-db` is NOT the repair: it writes a snapshot only when it has
+      // changes to EMIT, so on a database that already matches the metadata it reports
+      // "no schema changes / nothing to do", writes nothing, and leaves the stale snapshot
+      // exactly as it was — so this gate fails again, identically, with the user having
+      // been told everything is in sync. `baseline --from-db` rewrites it unconditionally,
+      // which is the whole point of the subcommand.
       `the committed schema snapshot disagrees with ${displayUrl} ` +
         `(${result.changes.length} difference(s)) — the next 'meta migrate' would emit DDL from it ` +
-        `and fail at apply. Re-derive it with 'meta migrate --from-db --db <url> --dialect ${dialect}'.`,
+        `and fail at apply. Re-derive it with ` +
+        `'meta migrate baseline --from-db --db <url> --dialect ${dialect}'.`,
       ...summarizeDrift(result.changes),
     ];
   }