@metaobjectsdev/cli 1.0.12 → 1.1.0

package/README.md

@@ -4,6 +4,8 @@ The MetaObjects CLI — scaffolds `metaobjects/` + `.metaobjects/`, runs codegen
 
 **Status:** v0.3. TS reference implementation with Projects D–G shipped end-to-end.
 
+**Upgrading from 1.0.x:** see the [1.0 to 1.1 upgrade guide](https://github.com/metaobjectsdev/metaobjects/blob/v1.1.0/docs/features/migrations/upgrading-1.0-to-1.1.md) before you regenerate. It lists every step and change that needs action, per port.
+
 ## Install
 
 ```bash
@@ -67,8 +69,15 @@ $EDITOR metaobjects/meta.myapp.json    # see .metaobjects/AGENTS.md for format
 #    how many files it would emit, so you can see what your metadata already asks for.
 meta gen --list --probe
 
-# 4. Take the ones you want. Prints the import, the entry to wire, and what to install.
-meta eject entity queries routes barrel
+# 4. Wire the ones you want. The catalog prints the import that runs each generator as
+#    shipped; add it to metaobjects.config.ts and call it in `generators: [...]`.
+#    What to install is on the structured row only (`install.dev`, `install.runtime`),
+#    beside the config keys the generator reads (`configKeys`):
+meta gen --list --format json
+
+#    Need to change what one emits? Copy it into your repo and own it. Prints the import
+#    to swap in, the entry to wire, and what to install.
+meta eject entity
 
 #    Need an output none of them emits (OpenAPI, JSON Schema, a client, docs)? Write your
 #    own: this scaffolds a working, commented generator and wires it into the config.
@@ -92,7 +101,7 @@ These apply to every command:
 
 Running `meta` with no arguments prints a concise status line (whether a `metaobjects/` directory is present) plus the most relevant next-step commands, rather than the full manual.
 
-**Exit codes:** `0` success (including idempotent no-op runs), `1` runtime error, `2` usage error (bad flag, missing required argument, invalid `--format`). For agent-friendliness, structured errors and next-step hints are emitted on **stdout** in the active `--format` (not stderr), so callers can parse them without scraping stderr.
+**Exit codes:** `0` success (including idempotent no-op runs, such as `meta init` on an initialized project), `1` runtime error (including metadata that does not load, in every command), `2` usage error (bad flag, missing required argument, invalid `--format`). An unknown flag is refused by name with the command's valid flags listed. Under `--format json|toon` stdout carries exactly one document — narration goes to stderr — and `meta verify` and `meta migrate` put their errors in that document too; the other commands print errors on stderr.
 
 ## Commands
 
@@ -100,7 +109,7 @@ Running `meta` with no arguments prints a concise status line (whether a `metaob
 
 Scaffolds `metaobjects/` (visible entity declarations, with a placeholder `meta.common.json`), `.metaobjects/` (hidden tool state: `config.json`, `AGENTS.md`, `CLAUDE.md`, `.gitignore`, `.gen-state/`), an **empty** `codegen/generators/` plus its `tsconfig.codegen.json`, and `metaobjects.config.ts` at the repo root.
 
-**It copies no generators and declares no dependencies.** Codegen is opt-in (ADR-0034 Amendment 2): the scaffolded config carries `generators: []` and a comment pointing at the catalog. `meta gen --list --probe` shows what each generator would emit for your model; `meta eject <name>...` copies the ones you choose into `codegen/generators/` — **yours to edit** — and prints the import line, the entry to add, the install command and any config keys those generators read. `meta gen` runs your local copies, never the package's.
+**It copies no generators and declares no dependencies.** Codegen is opt-in (ADR-0034 Amendment 2): the scaffolded config carries `generators: []` and a comment pointing at the catalog. `meta gen --list --probe` shows what each generator would emit for your model, with the import line that runs it as shipped; `meta gen --list --format json` adds what to install (`install.dev`, `install.runtime`) and the config keys each generator reads (`configKeys`), which the text listing does not print. Import a generator from its package to use it unchanged; `meta eject <name>...` copies the ones you want to change into `codegen/generators/` — **yours to edit** — and prints the import line to swap in, the entry to add, the install command and any config keys those generators read. `meta gen` runs whatever `generators: [...]` holds: the package's generator where you imported it, your copy where you ejected it.
 
 Flags:
 - `--force` — overwrite scaffold files (memory records preserved)
@@ -169,7 +178,7 @@ Flags:
 - `--allow <csv>` — destructive-change permissions: `drop-column,drop-table,type-change,drop-index,drop-fk,drop-check,drop-view,drop-view-cascade,adopt-view,nullable-to-not-null,drop-identity-default`
 - `--on-ambiguous abort|rename|drop-add` (default `abort`) — non-interactive
 - `--rename-table [schema.]old=new` / `--rename-column [schema.]table.old=new` — declare a rename (repeatable), so the migration is `RENAME` instead of drop+add whatever the rename heuristic makes of the names. Refused if nothing matches. See [Renames and populated tables](../../../../docs/features/migrations-and-drift.md#renames-and-populated-tables).
-- `--dry-run` — print SQL pair to stdout, write nothing
+- `--dry-run` — print the SQL pair, write nothing (under `--format json|toon` the pair is the document's `sql` field, so stdout stays one parseable document)
 - `--apply` — after writing migration files, immediately apply all pending migrations against the DB (runs `up.sql` for each unapplied entry, tracked in the migration ledger). Mutually exclusive with `--rollback`. Postgres and SQLite only (D1 uses `--apply` to invoke `wrangler d1 migrations apply` instead).
 - `--rollback <version>` — roll back applied migrations newer than `<version>` by running their `down.sql` in reverse order, ledger-tracked. Pass an empty string (`--rollback ""`) to roll back everything. Mutually exclusive with `--apply`. Postgres and SQLite only.
 
@@ -185,15 +194,11 @@ Flags:
 
 Two config files, by design:
 
-**`metaobjects.config.ts`** (at repo root) — generator wiring and codegen knobs, type-checked TS. It starts with `generators: []`; each import below appears when you `meta eject` that generator, which copies it into `codegen/generators/` (ADR-0034 scaffold-and-own) and prints the line to add:
+**`metaobjects.config.ts`** (at repo root) — generator wiring and codegen knobs, type-checked TS. It starts with `generators: []`. Import a stock generator from its package to run it as shipped (`meta gen --list` prints each line):
 
 ```ts
 import { defineConfig } from "@metaobjectsdev/cli";
-import { entityFile } from "./codegen/generators/entity";
-import { queriesFile } from "./codegen/generators/queries";
-import { routesFile } from "./codegen/generators/routes";
-import { namesFile } from "./codegen/generators/names";
-import { barrel } from "./codegen/generators/barrel";
+import { entityFile, queriesFile, routesFile, namesFile, barrel } from "@metaobjectsdev/codegen-ts/generators";
 
 export default defineConfig({
   outDir: "packages/database/src/generated",
@@ -205,9 +210,14 @@ export default defineConfig({
 });
 ```
 
-> Importing these generator factories from `@metaobjectsdev/codegen-ts/generators`
-> still works but is **deprecated** (ADR-0034) — own a local copy instead. The
-> package export will be removed in a future major.
+To change what one emits, `meta eject <name>` copies it into `codegen/generators/`
+(ADR-0034 scaffold-and-own) and prints the local import to put in place of the package
+one, for example `import { entityFile } from "./codegen/generators/entity";`. The factory
+keeps its name, so nothing else in the config changes.
+
+> `entityFile`, `queriesFile`, `routesFile` and `barrel` were removed from
+> `@metaobjectsdev/codegen-ts/generators` at 1.0 and restored in 1.1 (ADR-0034
+> Amendment 5). Both the import and an owned copy are supported.
 
 ### Multiple output targets
 
@@ -217,11 +227,9 @@ concern — declare named **targets** and point generators at them with `target`
 
 ```ts
 import { defineConfig } from "@metaobjectsdev/cli";
-// Owned generators — copied in by `meta eject` (ADR-0034 scaffold-and-own).
-import { entityFile } from "./codegen/generators/entity";
-import { queriesFile } from "./codegen/generators/queries";
-import { routesFile } from "./codegen/generators/routes";
-import { barrel } from "./codegen/generators/barrel";
+// Stock generators, run as shipped. An owned copy (`meta eject`) is wired the same way,
+// from "./codegen/generators/<name>".
+import { entityFile, queriesFile, routesFile, barrel } from "@metaobjectsdev/codegen-ts/generators";
 import { formFile } from "@metaobjectsdev/codegen-ts-react";
 import { tanstackQuery, tanstackGrid } from "@metaobjectsdev/codegen-ts-tanstack";
 
@@ -306,7 +314,7 @@ Precedence for `meta migrate`: CLI flag > env var (`DATABASE_URL` only) > `.meta
 ### Metadata sources (`sources`)
 
 `sources` is the single authority on **where metadata lives**. Every read command
-(`gen`, `migrate`, `verify`, `docs`, `export`) resolves it. When the key is absent or
+(`gen`, `migrate`, `verify`, `export`) resolves it. When the key is absent or
 empty — which is what `meta init` scaffolds — it takes its default value, the
 `metaobjects/` directory beside the config, so existing projects are unaffected.
 
@@ -349,8 +357,10 @@ means everything; `exclude` applies after `include`; matching is case-sensitive.
 
 **The collection always loads in full — `scope` filters output, never input.** It
 applies to `meta gen` and to `meta verify --codegen` (which regenerates under the
-same scope, so a scoped `gen` is not reported as drift). `meta docs` and `meta export`
-are deliberately **not** scoped — they inspect the loaded collection. `meta gen
+same scope, so a scoped `gen` is not reported as drift). The documentation generators are
+not scoped: the model pages, the api reference, the agent pages and the site document the
+whole loaded collection, whatever `scope` says. `meta export` is deliberately **not** scoped — it
+inspects the loaded collection. `meta gen
 <Entity>` arguments intersect with `scope`; both must pass.
 
 The TypeScript-only per-generator `filter` function is unchanged and remains the

package/dist/bin/meta.js

@@ -2,6 +2,18 @@
 // Note: this .ts source file is executed by Bun in the workspace (not Node).
 // The shebang stays as `node` so tsc copies it unchanged to dist/bin/meta.js,
 // keeping the published CLI runnable by Node for npm consumers.
-import { run } from "../src/index.js";
-run(process.argv.slice(2)).then((code) => process.exit(code));
+//
+// A bare version probe is answered here, from a leaf module that imports only node
+// builtins, BEFORE the command graph loads. `src/index.ts` statically pulls in the sdk
+// and codegen-ts, so answering `--version` there cost ~10x a bare `node` start on every
+// probe. Everything else — including a version flag in any other position — falls
+// through to `run()`, which stays the single owner of the general case.
+import { cliVersion, isVersionFlag } from "../src/lib/version.js";
+const argv = process.argv.slice(2);
+if (argv.length === 1 && isVersionFlag(argv[0])) {
+    console.log(cliVersion());
+    process.exit(0);
+}
+const { run } = await import("../src/index.js");
+process.exit(await run(argv));
 //# sourceMappingURL=meta.js.map

package/dist/bin/meta.js.map

@@ -1 +1 @@
-{"version":3,"file":"meta.js","sourceRoot":"","sources":["../../bin/meta.ts"],"names":[],"mappings":";AACA,6EAA6E;AAC7E,8EAA8E;AAC9E,gEAAgE;AAChE,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AACtC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC"}
+{"version":3,"file":"meta.js","sourceRoot":"","sources":["../../bin/meta.ts"],"names":[],"mappings":";AACA,6EAA6E;AAC7E,8EAA8E;AAC9E,gEAAgE;AAChE,EAAE;AACF,mFAAmF;AACnF,uFAAuF;AACvF,wFAAwF;AACxF,kFAAkF;AAClF,wEAAwE;AACxE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAElE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACnC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAChD,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;IAC1B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AACD,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAChD,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC"}

package/dist/src/commands/docs.d.ts

@@ -1,15 +1,2 @@
-/**
- * How a caller other than the CLI wants `meta docs` to behave.
- *
- * `verify --docs` runs this exact command into a temp directory and diffs the result, so
- * that the gate and the door can never be two implementations of "what the docs are". The
- * only thing it needs differently is silence: a verify run announcing "meta docs — wrote 8
- * entity pages" in the middle of its own report describes work the user is not getting.
- */
-export interface DocsCommandOptions {
-    /** Suppress the informational output. Warnings and errors still print — a docs run that
-     *  degraded is something a verify caller must see, not something to swallow. */
-    silent?: boolean;
-}
-export declare function docsCommand(args: string[], cwd: string, opts?: DocsCommandOptions): Promise<number>;
+export declare function docsCommand(_args: string[], _cwd: string): Promise<number>;
 //# sourceMappingURL=docs.d.ts.map

package/dist/src/commands/docs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../src/commands/docs.ts"],"names":[],"mappings":"AA6OA;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC;oFACgF;IAChF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA+ED,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,kBAAkB,GACxB,OAAO,CAAC,MAAM,CAAC,CAqcjB"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../src/commands/docs.ts"],"names":[],"mappings":"AAYA,wBAAsB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGhF"}