fix(cli,codegen-ts): unblock the TS newcomer quickstart (migrate trap + nodenext imports)

Two pre-launch first-touch fixes so a newcomer following the docs reaches a
working app under a stock toolchain.

1. `meta migrate baseline` greenfield trap (cli). An offline baseline (no
   --from-db) recorded the metadata's DESIRED schema as already-applied, so on an
   empty/new database no CREATE TABLE was ever emitted and the generated server
   500'd "no such table" -- while the CLI reported success at every step.
   - runBaseline now introspects the target --db and REFUSES (exit 2, writes no
     snapshot) when it proves the DB is empty; every other offline baseline still
     writes the snapshot but WARNs that it emits no DDL.
   - The no-snapshot hint, the `meta gen` success hint, and `meta migrate --help`
     now route to the working `meta migrate --from-db --db <url> --dialect <d>
     --slug init --apply` path instead of the `baseline` trap.

2. nodenext-safe generated imports (codegen-ts). Generated relative imports were
   un-extensioned (`./Author`, `../db`), failing TS2835 under a stock `tsc --init`
   (nodenext) config; the repo's own bundler tsconfig masked it.
   - The `extStyle` default flips to "js" and `meta init` scaffolds
     `extStyle: "js"` + `.js`-extensioned owned-generator imports. `.js`
     specifiers resolve under both nodenext and bundler, so this is strictly more
     compatible.
   - relativeModuleSpecifier now extension-styles a relative dbImport too
     (`../db` -> `../db.js`), guarded against double-extension and bare packages.

Gated by a new nodenext compile gate (real generated output, zero TS2835), a
greenfield baseline-guard suite, and a jiti config-load regression for the
scaffolded `.js` imports. Docs (ports/typescript.md) updated to match.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XeGSV3StPCcJGZNNJ4ZfAb

Author: dmealing

docs/ports/typescript.md

@@ -46,14 +46,15 @@ imports those local copies; `meta gen` runs from them, not from the package.
 // metaobjects.config.ts
 import { defineConfig } from "@metaobjectsdev/cli";
 // Owned generators scaffolded by `meta init` — yours to edit (ADR-0034).
-import { entityFile } from "./codegen/generators/entity";
-import { queriesFile } from "./codegen/generators/queries";
-import { routesFile } from "./codegen/generators/routes";
-import { barrel } from "./codegen/generators/barrel";
+import { entityFile } from "./codegen/generators/entity.js";
+import { queriesFile } from "./codegen/generators/queries.js";
+import { routesFile } from "./codegen/generators/routes.js";
+import { barrel } from "./codegen/generators/barrel.js";
 
 export default defineConfig({
   outDir: "src/generated",
   dialect: "postgres",                 // "postgres" | "sqlite" | "d1"
+  extStyle: "js",                      // ".js"-extensioned imports — nodenext- AND bundler-safe ("none" to opt out)
   apiPrefix: "/api",
   columnNamingStrategy: "snake_case",  // "snake_case" | "literal" | "kebab-case"
   generators: [entityFile(), queriesFile(), routesFile(), barrel()],
@@ -135,20 +136,20 @@ brand-new project there's no snapshot yet:
 
 ```bash
 meta migrate --dialect sqlite --slug init
-# meta: migrate: no schema snapshot at .../.schema.sqlite.json;
-#   run `meta migrate baseline --dialect sqlite` first
+# meta: migrate: no schema snapshot at .../.schema.sqlite.json. For a new project
+#   run `meta migrate --from-db --db <url> --dialect sqlite --slug init --apply`
+#   to create your tables, or `meta migrate baseline --from-db --db <url>` to
+#   adopt an existing database.
 ```
 
-**Do not follow that hint on a database that doesn't exist yet.** `meta
-migrate baseline` (without `--from-db`) derives the "existing" snapshot
-**from your metadata** — it records your entities' target shape as already
-applied, even against an empty/nonexistent database. Every subsequent `meta
-migrate` then reports `no changes` (exit 0) forever, and no table is ever
-created — a silent failure that only surfaces later, at the API layer, as
-`SQLITE_ERROR: no such table`.
-
-For a brand-new database, introspect the (empty) live DB instead and apply
-immediately — this is the correct one-time bootstrap command:
+The CLI points you at the right command (above). Avoid the `meta migrate
+baseline` subcommand **without** `--from-db` on a database that doesn't exist
+yet: an offline baseline derives the "existing" snapshot **from your metadata**,
+recording your entities' target shape as already applied. No table is ever
+created, and every subsequent `meta migrate` reports `no changes` (exit 0) — a
+silent failure that only surfaces later, at the API layer, as `SQLITE_ERROR: no
+such table`. (`meta migrate baseline` now refuses when it can see the target
+`--db` is empty, but the safe path for a new project is simply:)
 
 ```bash
 npx meta migrate --from-db --db file:dev.sqlite --dialect sqlite --slug init --apply
@@ -170,28 +171,20 @@ meta migrate --dialect d1                                        # Cloudflare D1
 
 ### Typecheck the generated code
 
-`npx tsc` (the hint every `meta gen`/`meta migrate` prints) needs a
-`tsconfig.json` that matches how the generated code is written: relative
-imports with **no file extensions**, resolved bundler-style — the same
-convention this repo's own `server/typescript/tsconfig.base.json` uses. A
-fresh `tsc --init` on some TypeScript versions instead defaults to Node's
-native ESM resolution (`"module": "nodenext"` / `"node16"`), which *requires*
-extensioned relative imports (`./Author.js`) and fails on every generated file
-with `TS2835`. Set:
-
-```jsonc
-// tsconfig.json
-{
-  "compilerOptions": {
-    "module": "esnext",
-    "moduleResolution": "bundler"
-    // ...your other options
-  }
-}
-```
-
-and make sure `package.json` has `"type": "module"` — MetaObjects generates
-ESM only, no CommonJS.
+`npx tsc` (the hint every `meta gen`/`meta migrate` prints) works out of the
+box with a stock `tsc --init` tsconfig: the generated code emits
+`.js`-extensioned relative imports (`import { Author } from "./Author.js"`),
+which resolve correctly under **both** Node's native ESM resolution
+(`"module": "nodenext"`, the `tsc --init` default) **and** bundler-style
+resolution (`"moduleResolution": "bundler"`, Vite/esbuild/tsx). The one project
+setting to check: `package.json` must have `"type": "module"` — MetaObjects
+generates ESM only, no CommonJS. (The `.js` extension names the compiled output;
+`tsc`/your bundler resolves it back to the `.ts` source — this is the standard
+Node-ESM TypeScript convention.)
+
+If you prefer un-extensioned imports (some legacy bundler setups), set
+`extStyle: "none"` in `metaobjects.config.ts` and use `"moduleResolution":
+"bundler"`.
 
 ## Use
 
@@ -218,7 +211,7 @@ export const db = drizzle(createClient({ url: "file:dev.sqlite" }));
 ```ts
 // src/server.ts
 import Fastify from "fastify";
-import { authorRoutes } from "./generated/Author.routes";
+import { authorRoutes } from "./generated/Author.routes.js";
 
 const app = Fastify();
 await app.register(authorRoutes);   // mounts GET/POST/PATCH/PUT/DELETE for Author
@@ -252,15 +245,16 @@ difference is the framework adapter the emitted code talks to.
 // metaobjects.config.ts
 import { defineConfig } from "@metaobjectsdev/cli";
 // Owned generators scaffolded by `meta init` (ADR-0034 scaffold-and-own).
-import { entityFile } from "./codegen/generators/entity";
-import { queriesFile } from "./codegen/generators/queries";
-import { barrel } from "./codegen/generators/barrel";
+import { entityFile } from "./codegen/generators/entity.js";
+import { queriesFile } from "./codegen/generators/queries.js";
+import { barrel } from "./codegen/generators/barrel.js";
 // Hono routes have no reference template yet — still imported from the package.
 import { routesFileHono } from "@metaobjectsdev/codegen-ts/generators";
 
 export default defineConfig({
   outDir: "src/generated",
   dialect: "sqlite",                    // or "postgres" / "d1"
+  extStyle: "js",
   apiPrefix: "/api",
   generators: [entityFile(), queriesFile(), routesFileHono(), barrel()],
 });
@@ -277,7 +271,7 @@ import {
   AuthorUpdateSchema,
   AuthorFilterAllowlist,
   AuthorSortAllowlist,
-} from "./Author";
+} from "./Author.js";
 import { mountCrudRoutes } from "@metaobjectsdev/runtime-ts/hono";
 import type { Hono } from "hono";
 
@@ -304,7 +298,7 @@ Consumer wiring (Workers example):
 ```ts
 import { Hono } from "hono";
 import { drizzle } from "drizzle-orm/d1";
-import { registerAuthorRoutes } from "./generated/Author.routes.hono";
+import { registerAuthorRoutes } from "./generated/Author.routes.hono.js";
 
 interface Env { DB: D1Database }
 
@@ -371,7 +365,7 @@ export function safeParseNpcResponse(text: string):
 Consumer wiring:
 
 ```ts
-import { parseNpcResponse, safeParseNpcResponse } from "./generated/NpcResponse.output";
+import { parseNpcResponse, safeParseNpcResponse } from "./generated/NpcResponse.output.js";
 
 const llmResponse = await myLlmProvider.call(promptText);
 

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

@@ -55,14 +55,14 @@ function buildMetaobjectsConfigBody(dialect: "sqlite" | "postgres" | "d1" = "sql
 // reference templates into ./codegen/generators/ — they are YOURS to edit, and
 // \`meta gen\` runs from these local copies, not from the package. Read each file's
 // header doc-block for what it emits and how to customize it.
-import { entityFile } from "./codegen/generators/entity";
-import { queriesFile } from "./codegen/generators/queries";
-import { routesFile } from "./codegen/generators/routes";
-import { barrel } from "./codegen/generators/barrel";
+import { entityFile } from "./codegen/generators/entity.js";
+import { queriesFile } from "./codegen/generators/queries.js";
+import { routesFile } from "./codegen/generators/routes.js";
+import { barrel } from "./codegen/generators/barrel.js";
 
 export default defineConfig({
   outDir:    "src/generated",
-  extStyle:  "none",
+  extStyle:  "js",   // ".js"-extensioned relative imports — safe under Node ESM / tsc nodenext AND bundlers
   dbImport:  "../db",
   dialect:   "${dialect}",
   apiPrefix: "",     // set to "/api" if your routes mount under /api

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

@@ -8,7 +8,7 @@ import { formatMigrateResult, formatMigrateResultToon, type BlockedEntry, type A
 import { formatMigrateResultJson } from "../lib/output-json.js";
 import type { OutputFormat } from "../lib/format.js";
 import { toonEncode } from "../lib/format.js";
-import { buildKyselyFromUrl } from "../lib/kysely.js";
+import { buildKyselyFromUrl, redactUrl } from "../lib/kysely.js";
 import { log } from "../lib/log.js";
 import { loadMemory } from "@metaobjectsdev/sdk";
 import { loadMetaobjectsConfig } from "../lib/load-metaobjects-config.js";
@@ -54,8 +54,10 @@ USAGE:
   meta migrate [baseline] [flags]
 
 SUBCOMMANDS:
-  baseline             Seed the committed reference snapshot (no migration emitted).
-                       Required before the first offline generate.
+  baseline             Snapshot an EXISTING database's schema as the reference point
+                       (use with --from-db). NOTE: for a brand-new/empty database use
+                       the greenfield example below, NOT baseline — an offline baseline
+                       records your metadata as already-applied and emits no CREATE TABLE.
 
 MIGRATE FLAGS:
   --db <url>           DB connection URL (required for live-introspect / --apply / --rollback)
@@ -80,10 +82,13 @@ MIGRATE FLAGS:
   --help, -h           Print this help
 
 EXAMPLES:
-  meta migrate baseline --dialect sqlite
-  meta migrate --dialect sqlite --slug add-users
-  meta migrate --db file:local.db --slug add-orders
+  # New project — create tables in a fresh database (introspect → diff → CREATE TABLE → apply):
+  meta migrate --from-db --db file:dev.sqlite --dialect sqlite --slug init --apply
+  # Later — add a schema change and apply it:
+  meta migrate --db file:dev.sqlite --dialect sqlite --slug add-users --apply
   meta migrate --db postgresql://localhost/mydb --slug add-index --apply
+  # Adopt an existing database — snapshot its current schema first:
+  meta migrate baseline --from-db --db postgresql://localhost/mydb
 `;
 
 /** Emit a structured error on stdout (not stderr) in the active format, per axi. */
@@ -112,6 +117,47 @@ function mapOnAmbiguous(v: "abort" | "rename" | "drop-add"): AmbiguousResolution
   return v === "drop-add" ? "drop+add" : v;
 }
 
+/**
+ * The command that actually creates tables in a fresh/empty database. This is the
+ * correct first step for a brand-new project — it introspects the (empty) DB, diffs
+ * metadata against it to produce every CREATE TABLE, and applies them. Offline
+ * `baseline` is NOT this: it records the desired schema as already-applied and emits
+ * no DDL (launch-blocker B1).
+ */
+function greenfieldCreateCmd(dialect: string | undefined): string {
+  const d = dialect ?? "sqlite";
+  return `meta migrate --from-db --db <url> --dialect ${d} --slug init --apply`;
+}
+
+/** The command to adopt a database that already exists (snapshot its live schema). */
+function adoptExistingDbCmd(): string {
+  return "meta migrate baseline --from-db --db <url>";
+}
+
+/** Shared `emitStructuredError` detail — points at the greenfield-create and
+ *  adopt-existing commands. Used by the empty-DB refusal and the no-snapshot hint. */
+function nextStepsDetail(dialect: string | undefined): string {
+  return `run \`${greenfieldCreateCmd(dialect)}\` to create tables, or \`${adoptExistingDbCmd()}\` to adopt an existing database`;
+}
+
+/** Table count of the target DB, or undefined when it can't be reached/introspected
+ *  (any failure ⇒ unknown ⇒ never block; the caller warns instead of refusing). */
+async function countLiveTables(
+  url: string,
+  dialect: ResolvedMigrateConfig["dialect"],
+): Promise<number | undefined> {
+  try {
+    const kysely = await buildKyselyFromUrl(url, dialect);
+    try {
+      return (await introspect(kysely.db, kysely.dialect)).tables.length;
+    } finally {
+      await kysely.close();
+    }
+  } catch {
+    return undefined;
+  }
+}
+
 function summarizeChanges(changes: Change[]): Record<string, number> {
   const counts: Record<string, number> = {};
   for (const c of changes) {
@@ -486,7 +532,7 @@ export async function migrateCommand(
 export async function runBaseline(
   config: ResolvedMigrateConfig,
   metaRoot: string,
-  _fmt: OutputFormat = "text",
+  fmt: OutputFormat = "text",
 ): Promise<number> {
   if (config.dialect === undefined) {
     log.error(`migrate baseline: --dialect required (or set migrate.dialect in .metaobjects/config.json)`);
@@ -514,6 +560,33 @@ export async function runBaseline(
       await kysely.close();
     }
   } else {
+    // Greenfield-trap guard (launch-blocker B1). An offline baseline records the
+    // metadata's DESIRED schema as the already-applied baseline; on an empty/new
+    // database that silently suppresses every CREATE TABLE forever. When we can see
+    // the target --db and PROVE it has no tables, refuse and point at the working
+    // greenfield path. In every OTHER case — no --db, a non-empty --db, or a --db we
+    // couldn't reach — we still write the snapshot but WARN: an offline baseline is
+    // only correct when the database already matches the metadata, and emits no DDL.
+    const liveTableCount = config.databaseUrl !== undefined
+      ? await countLiveTables(config.databaseUrl, config.dialect)
+      : undefined;
+    if (liveTableCount === 0) {
+      // `liveTableCount === 0` ⇒ databaseUrl was defined (countLiveTables only
+      // returns a number when it introspected a real connection).
+      log.error(
+        `migrate baseline: the database at ${redactUrl(config.databaseUrl!)} has no tables — ` +
+        `baselining now would record your metadata as already-applied and no CREATE TABLE ` +
+        `would ever be emitted. For a new/empty database run \`${greenfieldCreateCmd(config.dialect)}\` ` +
+        `to create your tables (or \`${adoptExistingDbCmd()}\` to adopt an existing database).`,
+      );
+      emitStructuredError("migrate baseline: target database is empty", nextStepsDetail(config.dialect), fmt);
+      return 2;
+    }
+    log.warn(
+      `migrate baseline (offline): recording your metadata's schema as the already-applied ` +
+      `baseline — this emits NO CREATE TABLE. Use it only if your database already matches ` +
+      `your metadata; for a new/empty database run \`${greenfieldCreateCmd(config.dialect)}\` instead.`,
+    );
     let metadata;
     // Load metaobjects.config.ts ONCE, up front, for BOTH the consumer providers
     // and the columnNamingStrategy — mirroring the DB path (and `meta gen`) so
@@ -603,13 +676,17 @@ export async function runOfflineGenerate(
     return 2;
   }
   if (snapshot === null) {
-    log.error(`migrate: no schema snapshot at ${path}; run \`meta migrate baseline --dialect ${config.dialect}\` first`);
-    // Structured next-step on stdout so callers / agents can parse it, in the active format.
-    emitStructuredError(
-      "no schema snapshot",
-      `first run \`meta migrate baseline --dialect ${config.dialect}\``,
-      fmt,
+    // For a brand-new project the working first step is the greenfield --from-db …
+    // --apply path (introspect the empty DB, diff, CREATE TABLE, apply), NOT the
+    // offline `baseline` subcommand — offline baseline records the desired schema as
+    // already-applied and would suppress every CREATE TABLE (launch-blocker B1).
+    log.error(
+      `migrate: no schema snapshot at ${path}. For a new project run ` +
+      `\`${greenfieldCreateCmd(config.dialect)}\` to create your tables, or ` +
+      `\`${adoptExistingDbCmd()}\` to adopt an existing database.`,
     );
+    // Structured next-step on stdout so callers / agents can parse it, in the active format.
+    emitStructuredError("no schema snapshot", nextStepsDetail(config.dialect), fmt);
     return 2;
   }
 

server/typescript/packages/cli/src/lib/output.ts

@@ -184,7 +184,7 @@ export function genResultToData(result: GenResultShape): {
     : parts.join(", ");
   const help = result.files.length === 0
     ? ["author entities under metaobjects/ then re-run `meta gen`"]
-    : ["typecheck the generated code with `npx tsc`", "run schema with `meta migrate --db <url> --slug <name>`"];
+    : ["typecheck the generated code with `npx tsc`", "create your database tables with `meta migrate --from-db --db <url> --dialect <sqlite|postgres> --slug init --apply`"];
   return { gen: result.files.map((f) => ({ file: f.path, status: f.status })), summary, help };
 }
 

server/typescript/packages/cli/test/load-metaobjects-config.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "bun:test";
-import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { loadMetaobjectsConfig } from "../src/lib/load-metaobjects-config.js";
@@ -32,4 +32,41 @@ describe("loadMetaobjectsConfig", () => {
       rmSync(dir, { recursive: true, force: true });
     }
   });
+
+  // Regression for the launch-B3 nodenext fix: `meta init` now scaffolds the
+  // ADR-0034 owned-generator imports with a `.js` extension (nodenext-safe). The
+  // jiti-based loader must still resolve those relative `.js` specifiers to the
+  // on-disk `.ts` files when it loads the config — otherwise `meta gen` breaks on
+  // a freshly-scaffolded project.
+  test("resolves scaffolded owned-generator imports written with a `.js` extension", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "mo-cfg-jsext-"));
+    try {
+      mkdirSync(join(dir, "codegen", "generators"), { recursive: true });
+      writeFileSync(
+        join(dir, "codegen", "generators", "entity.ts"),
+        // A minimal Generator factory — the loader only needs the module to
+        // resolve and the factory to produce a generator-shaped object.
+        `export function entityFile() { return { name: "entity-file", generate: () => [] }; }\n`,
+      );
+      writeFileSync(
+        join(dir, "metaobjects.config.ts"),
+        [
+          `import { defineConfig } from "@metaobjectsdev/codegen-ts";`,
+          `import { entityFile } from "./codegen/generators/entity.js";`,
+          `export default defineConfig({`,
+          `  outDir: "src/generated",`,
+          `  extStyle: "js",`,
+          `  dbImport: "../db",`,
+          `  dialect: "sqlite",`,
+          `  generators: [entityFile()],`,
+          `});`,
+        ].join("\n"),
+      );
+      const cfg = await loadMetaobjectsConfig(dir);
+      expect(cfg.generators.length).toBe(1);
+      expect(cfg.extStyle).toBe("js");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });