fix(cli): meta init declares what meta gen's output imports, not just what its generators do

A brand-new project could not run the next step the tool itself prints. `npm init -y`,
install the CLI, `meta init`, `meta gen`, then `npx tsc` — the line `meta gen` ends on —
and pnpm reported NINE TS2307s across all three generated files, on five specifiers the
generated code imports and no manifest declared: drizzle-orm, zod, fastify,
`@metaobjectsdev/runtime-ts` and its `/drizzle-fastify` subpath. Under npm, hoisting out
of the CLI's own tree hides four of the five and only fastify fails; the release smoke
test runs both arms for exactly this reason.

`addScaffoldDevDependencies` already fixed this defect one layer in, and its docstring
records why: the generator sources under `codegen/generators/` import
`@metaobjectsdev/codegen-ts` and `@metaobjectsdev/metadata`, nothing declared them, and
"the scaffold arrived un-typecheckable: ten TS2307s on files `meta init` had just
written." The identical argument reaches one layer further out — to the code `meta gen`
writes — and nobody followed it there.

They go in `dependencies`, not `devDependencies`: generated routes and queries are
application source that runs in production. The two build-time packages stay where they
are.

The RANGES are read from `@metaobjectsdev/runtime-ts`'s own `peerDependencies` rather
than written into the scaffolder. That package already declares the versions its helpers
are built against, bounded above (the peer-range gate enforces the bound), so a second
copy here would be a second thing to keep in step, and the failure mode of drift is an
adopter installing a major nothing was tested against. A range that cannot be read means
the package is SKIPPED, never guessed at.

Proven against the published artifact, not just locally: the pnpm arm of the rc.3 smoke
test went from 9 errors to `tsc --noEmit` exit 0 with exactly these four declarations
added and nothing else changed.

The gate asks the question the manifest can answer. Every test that runs `gen` scaffolds
into `test/fixtures/__tmp__/` DELIBERATELY, so node resolution walks up into cli's own
node_modules where fastify, drizzle-orm and zod all sit — `mkGenProjectDir`'s comment
says so outright. That is why the generated imports resolved in every existing test for a
reason having nothing to do with the adopter's manifest, and why none of them could see
this. The new test runs in the same place and asks whether the scaffolder DECLARED each
bare specifier, which is answerable from the manifest alone and is what a strict
installer enforces. It also asserts the four specifiers are really present in the output,
so a regression that stops emitting them cannot make it pass vacuously.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01At3v6M6uqECZ2Sb5eUv6YY

Author: dmealing

server/typescript/packages/cli/src/commands/init.ts

@@ -2,6 +2,7 @@ import { mkdir, writeFile, readFile, readdir, stat, rm } from "node:fs/promises"
 import { join } from "node:path";
 import { basename, dirname } from "node:path";
 import { existsSync as existsSyncWrap, readFileSync as readFileSyncWrap } from "node:fs";
+import { createRequire } from "node:module";
 import { DEFAULT_CONFIG, ConfigSchema, saveConfig, PACKAGE_MANIFEST_FILE, DEFAULT_METADATA_DIR, DEFAULT_METAOBJECTS_DIR } from "@metaobjectsdev/sdk";
 import {
   assemble, resolveAgentContextRoot, planScaffold,
@@ -774,6 +775,7 @@ async function ensureEsmPackageType(cwd: string, result: InitResult): Promise<vo
   const declaredType = pkg.type;   // read BEFORE the mutation below overwrites it
   pkg.type = "module";
   const added = addScaffoldDevDependencies(pkg);
+  const addedRuntime = addScaffoldRuntimeDependencies(pkg);
   // Preserve the file's existing indentation rather than reformatting someone's manifest.
   const indent = /\n(\s+)"/.exec(raw)?.[1] ?? "  ";
   await writeFile(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`, "utf8");
@@ -798,6 +800,13 @@ async function ensureEsmPackageType(cwd: string, result: InitResult): Promise<vo
         "Run your package manager's install before `meta gen`.",
     );
   }
+  if (addedRuntime.length > 0) {
+    result.warnings.push(
+      `added ${addedRuntime.join(" + ")} to dependencies — the code \`meta gen\` writes ` +
+        "imports them, so `npx tsc` reports TS2307 on the generated files until they are " +
+        "installed. Run your package manager's install before `meta gen`.",
+    );
+  }
 }
 
 /**
@@ -844,6 +853,86 @@ function addScaffoldDevDependencies(pkg: Record<string, unknown>): string[] {
   return added;
 }
 
+/**
+ * The third-party packages the scaffolded suite's GENERATED OUTPUT imports, each named
+ * with the artifact that imports it. This is the set, not the ranges — see
+ * `scaffoldRuntimeDependencies` for where those come from.
+ *
+ * `@metaobjectsdev/runtime-ts` is deliberately not here: its range is the CLI's own
+ * version, like the two build-time packages above, not a peer range read off itself.
+ */
+const SCAFFOLD_OUTPUT_PEERS = [
+  "drizzle-orm",   // <Entity>.ts (the table + column builders) and <Entity>.queries.ts
+  "zod",           // <Entity>.ts — the Insert/Update schemas
+  "fastify",       // <Entity>.routes.ts — `import type { FastifyInstance }`
+] as const;
+
+/**
+ * The runtime dependencies of the code `meta gen` will WRITE, for `dependencies`.
+ *
+ * `addScaffoldDevDependencies` above fixed this defect one layer in: the generator
+ * SOURCES under `codegen/generators/` import `@metaobjectsdev/codegen-ts` and
+ * `@metaobjectsdev/metadata`, nothing declared them, and the scaffold arrived
+ * un-typecheckable. The same argument reaches one layer further out and was not
+ * followed there. Generated `<Entity>.ts` / `.queries.ts` / `.routes.ts` import
+ * drizzle-orm, zod, fastify and `@metaobjectsdev/runtime-ts/drizzle-fastify` — five
+ * specifiers, none declared — so `npx tsc`, which is the next step `meta gen` itself
+ * prints, reported NINE TS2307s on a brand-new project that had done nothing wrong.
+ * npm hides four of the five by hoisting them out of the CLI's own tree; pnpm's strict
+ * layout, which is the point of testing both, shows all five.
+ *
+ * `dependencies`, not `devDependencies`: generated routes and queries are application
+ * source that runs in production. The two build-time packages stay where they are.
+ *
+ * The RANGES are read from `@metaobjectsdev/runtime-ts`'s own `peerDependencies` rather
+ * than written here. That package already declares the versions its helpers are built
+ * against, bounded above (the peer-range gate enforces the bound), so a second copy of
+ * those ranges in the scaffolder is a second thing to keep in step — and the failure
+ * mode of drift is an adopter installing a major nothing was tested against. If a range
+ * cannot be read, the package is SKIPPED rather than guessed at, and `meta gen` still
+ * type-checks for anyone whose manifest already declares it.
+ */
+function scaffoldRuntimeDependencies(): Record<string, string> {
+  const wanted: Record<string, string> = {
+    "@metaobjectsdev/runtime-ts": `^${cliVersion()}`,
+  };
+  const peers = runtimeTsPeerRanges();
+  for (const name of SCAFFOLD_OUTPUT_PEERS) {
+    const range = peers[name];
+    if (range !== undefined) wanted[name] = range;
+  }
+  return wanted;
+}
+
+/** `@metaobjectsdev/runtime-ts`'s declared peer ranges, or `{}` if it cannot be read. */
+function runtimeTsPeerRanges(): Record<string, string> {
+  try {
+    const req = createRequire(import.meta.url);
+    const manifestPath = req.resolve("@metaobjectsdev/runtime-ts/package.json");
+    const manifest = JSON.parse(readFileSyncWrap(manifestPath, "utf8")) as PackageManifest;
+    return (manifest.peerDependencies ?? {}) as Record<string, string>;
+  } catch {
+    return {};
+  }
+}
+
+/** Adds any missing `scaffoldRuntimeDependencies()` to `dependencies`. Only ever ADDS a
+ *  missing key — an existing pin, in any of the four dependency fields, is the user's. */
+function addScaffoldRuntimeDependencies(pkg: Record<string, unknown>): string[] {
+  const deps = (pkg.dependencies ?? {}) as Record<string, string>;
+  const declared = declaredDependencyNames(pkg as PackageManifest);
+  const added: string[] = [];
+  for (const [name, range] of Object.entries(scaffoldRuntimeDependencies())) {
+    if (declared.has(name)) continue;
+    deps[name] = range;
+    added.push(name);
+  }
+  if (added.length > 0) {
+    pkg.dependencies = Object.fromEntries(Object.entries(deps).sort(([a], [b]) => a.localeCompare(b)));
+  }
+  return added;
+}
+
 /** True when the project has hand-written CommonJS at the root (excluding tooling dirs). */
 async function hasCommonJsSources(cwd: string): Promise<boolean> {
   const SKIP = new Set(["node_modules", ".git", "dist", "build", ".metaobjects", "codegen"]);

server/typescript/packages/cli/test/scaffold-output-imports-declared.test.ts

@@ -0,0 +1,106 @@
+// Everything `meta gen` WRITES must be resolvable from what `meta init` DECLARED.
+//
+// It was not. A brand-new project — `npm init -y`, install the CLI, `meta init`,
+// `meta gen`, then `npx tsc`, which is the next step `meta gen` itself prints —
+// reported NINE TS2307s under pnpm, on five specifiers the generated files import and
+// no manifest declared: drizzle-orm, zod, fastify, `@metaobjectsdev/runtime-ts` and its
+// `/drizzle-fastify` subpath. npm hides four of the five by hoisting them out of the
+// CLI's own dependency tree; pnpm's strict layout shows all five, which is why the
+// release smoke test runs both.
+//
+// `addScaffoldDevDependencies` had already fixed this defect ONE LAYER IN — the
+// generator sources under `codegen/generators/` import `@metaobjectsdev/codegen-ts` and
+// `@metaobjectsdev/metadata`, and its own docstring records the scaffold arriving
+// un-typecheckable with ten TS2307s. The identical argument reaches the generated
+// output and nobody followed it there.
+//
+// Why no existing test could see it: every test that runs `gen` scaffolds into
+// `test/fixtures/__tmp__/`, deliberately, so that node resolution walks up into cli's
+// OWN node_modules — where fastify, drizzle-orm and zod all sit as devDependencies.
+// `mkGenProjectDir`'s comment says so outright. So the generated imports resolved in
+// every test for a reason that has nothing to do with the adopter's manifest. This test
+// runs in the same place and asks a different question: not "does it resolve here" but
+// "did the scaffolder DECLARE it", which is answerable from the manifest alone and is
+// exactly what a strict installer will enforce.
+import { describe, test, expect } from "bun:test";
+import { mkdtempSync, mkdirSync, rmSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { initCommand } from "../src/commands/init.js";
+import { declaredDependencyNames, type PackageManifest } from "../src/lib/package-manifest.js";
+
+const PROBE_ENTITY = JSON.stringify({
+  metadata: {
+    package: "probe",
+    children: [{
+      "object.entity": {
+        name: "Author",
+        children: [
+          { "source.rdb": { "@table": "authors" } },
+          { "field.string": { name: "id" } },
+          { "field.string": { name: "penName", "@column": "pen_name" } },
+          { "identity.primary": { "@fields": ["id"] } },
+        ],
+      },
+    }],
+  },
+}, null, 2);
+
+/** Bare package specifiers imported by a generated file — not relative, not `node:`.
+ *  A subpath resolves to its package (`@scope/pkg/sub` -> `@scope/pkg`), which is what
+ *  a manifest declares. */
+function bareImports(source: string): Set<string> {
+  const found = new Set<string>();
+  for (const m of source.matchAll(/(?:^|\n)\s*(?:import|export)[\s\S]*?from\s+"([^"]+)"/g)) {
+    const spec = m[1];
+    if (spec === undefined || spec.startsWith(".") || spec.startsWith("node:")) continue;
+    const parts = spec.split("/");
+    found.add(spec.startsWith("@") ? parts.slice(0, 2).join("/") : (parts[0] ?? spec));
+  }
+  return found;
+}
+
+describe("meta init declares what meta gen's output imports", () => {
+  test("every bare specifier in the generated files is a declared dependency", async () => {
+    // In-package, so `gen` can resolve the scaffolded generators' own imports.
+    const root = join(import.meta.dirname, "fixtures", "__tmp__");
+    mkdirSync(root, { recursive: true });
+    const dir = mkdtempSync(join(root, "scaffold-deps-"));
+    try {
+      // The `npm init -y` shape, which is the documented first step.
+      writeFileSync(
+        join(dir, "package.json"),
+        `${JSON.stringify({ name: "probe", version: "1.0.0", type: "commonjs" }, null, 2)}\n`,
+      );
+      expect(await initCommand([], dir)).toBe(0);
+      writeFileSync(join(dir, "metaobjects", "meta.common.json"), PROBE_ENTITY);
+      const { genCommand } = await import("../src/commands/gen.js");
+      expect(await genCommand([], dir)).toBe(0);
+
+      const outDir = join(dir, "src", "generated");
+      const emitted = readdirSync(outDir).filter((f) => f.endsWith(".ts"));
+      expect(emitted.length).toBeGreaterThan(0);
+
+      const declared = declaredDependencyNames(
+        JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as PackageManifest,
+      );
+      const undeclared: string[] = [];
+      for (const file of emitted) {
+        for (const spec of bareImports(readFileSync(join(outDir, file), "utf8"))) {
+          if (!declared.has(spec)) undeclared.push(`${file} imports ${spec}`);
+        }
+      }
+      // Named individually: the failure an adopter sees is a list of TS2307s, and the
+      // useful message here is the same list, before they ever run tsc.
+      expect(undeclared).toEqual([]);
+
+      // ...and the specifiers that caused this test to exist are really present in the
+      // output, so a regression that stops EMITTING them cannot make it pass vacuously.
+      const all = new Set(emitted.flatMap((f) => [...bareImports(readFileSync(join(outDir, f), "utf8"))]));
+      for (const required of ["drizzle-orm", "zod", "fastify", "@metaobjectsdev/runtime-ts"]) {
+        expect([...all]).toContain(required);
+      }
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});