@metaobjectsdev/sdk 0.11.6-rc.1 → 0.12.0-rc.1

package/agent-context/skills/metaobjects-codegen/references/python.md

@@ -0,0 +1,76 @@
+# Python codegen specifics
+
+The Python port targets FastAPI consumers. Codegen runs through the **`metaobjects`
+console-script** (`pip install metaobjects`). As on every port, schema migrations
+are **Node-`meta`-owned** (ADR-0015): `meta migrate` / `meta verify --db` run
+through the Node `meta` tool — the Python CLI has **no `migrate` subcommand** and
+`metaobjects verify --db` is rejected. Everything below is `metaobjects`.
+
+## Install
+
+```bash
+pip install metaobjects                 # provides the `metaobjects` console-script
+# consumer runtime deps (you provide these — codegen does not pin them):
+pip install "pydantic>=2" fastapi
+```
+
+## Run
+
+```bash
+metaobjects gen ./metadata --out ./generated [--package <pkg>]
+metaobjects gen ./metadata --out ./generated --generators entity,routes,filter-allowlist
+metaobjects verify ./metadata --codegen        # codegen-drift gate (regenerate into a
+                                               # temp dir + diff vs the committed --out tree)
+```
+
+`metaobjects verify` defaults to `--codegen` (the codegen-output drift gate; it shares
+the exact `gen` code path so the two can't diverge). `--templates` is the prompt/template
+drift gate (see the prompts reference). Schema migration + live-DB drift are **not**
+`metaobjects` — they run through the Node `meta` tool (see the migration reference).
+
+## Generators
+
+Wire generators by their stable name (`--generators <names>`), or run the default set.
+Output lands under `--out` (with the `@generated` guard header). Metadata is the same
+canonical JSON every port reads (fused-key form, `source.rdb` + `@table`, `@column` for
+a renamed physical column).
+
+| Stable name | Output |
+|---|---|
+| `entity` | one **Pydantic model** per `object.entity` / projection (the `entity-model` generator): typed fields from the metadata, nullability from `@required`, `@maxLength`/validators, enum fields → a Python `Enum`. This is the typed data model. |
+| `routes` | a **FastAPI `APIRouter`** per writable entity (`source.rdb @kind="table"`) on the cross-port REST contract (`?filter[field][op]=`, `?sort=field:asc`, `?limit`/`?offset`, `?withCount=1` envelope, 400/404 envelopes). The router declares a repository **`Protocol`** you implement and inject. |
+| `filter-allowlist` | per-entity filter allowlist (FR-009 — the server-side field+operator allowlist the routes validate against). |
+| `payload` / `output-parser` / `output-prompt` / `extractor` / `render-helper` / `trace-helper` | the `template.output` prompt-pillar artifacts — see the **prompts** reference. |
+| `template` | the generic Mustache `template` primitive. |
+
+## No ORM — you own persistence (unlike the C# port)
+
+Python codegen emits the **Pydantic models + the FastAPI routers**, but **no ORM /
+persistence layer and no runnable server**. Two things you hand-write:
+
+1. **The repository** — each generated router depends on a repository `Protocol`;
+   implement it against your datastore (SQLAlchemy / asyncpg) and inject it.
+2. **The app entrypoint** — there is no generated `main.py`. Create one and mount the
+   routers:
+   ```python
+   from fastapi import FastAPI
+   from generated.author_router import router as author_router
+   app = FastAPI()
+   app.include_router(author_router)
+   ```
+
+## Known gaps (current — may require a hand-edit)
+
+- **Single-field, `int` PKs only.** The generated router/repository assume a single
+  `int` primary key (`id: int`). Non-`int` single-field PKs and composite PKs need a
+  hand-edit until specified.
+- **DTO = `dict[str, Any]`.** Request bodies for `POST`/`PATCH`/`PUT` are typed
+  `dto: dict[str, Any]` and responses return `Any`; the repository `Protocol` uses
+  `Any` for the row type. The typed Pydantic model from the `entity` generator exists —
+  you can tighten the router signatures to it by hand.
+
+## Re-scaffold this context
+
+`metaobjects agent-docs --server python [--out <dir>]` (re)scaffolds the slim always-on
+Markdown + these `metaobjects-*` skills into the project — the Python tool bundles the
+agent-context tree, so a Python consumer needs no Node `meta`.

package/agent-context/skills/metaobjects-codegen/references/typescript.md

@@ -129,6 +129,10 @@ Generated files carry an `@generated by @metaobjectsdev/codegen-ts` header; the
 runner overwrites those and refuses to touch files without it. Hand-customizations
 that metadata can't express live in sibling `<Entity>.extra.ts` files.
 
+**Output format:** `meta gen` (and the CLI generally) is TTY-aware — human-readable
+text on a terminal, TOON on a pipe or agent. Override with `--format toon|json|text`.
+TOON is the structured default for agents; `--format json` is also available.
+
 ## Multiple output targets
 
 A `targets: { web: { outDir }, api: { outDir } }` registry plus a per-generator

package/agent-context/skills/metaobjects-verify/SKILL.md

@@ -37,9 +37,9 @@ can't drift by construction).
 - **`--db`** — schema drift. Introspects the live database and fails if it has
   diverged from metadata. This is a **schema concern, so it is the Node toolchain's
   job regardless of your server language** (see migrations below). On the JVM ports
-  a runtime startup validator catches generated-table drift at app boot as a
-  complementary check, but the authoritative DB-vs-metadata gate is the Node
-  `verify --db`.
+  a runtime startup validator *can* catch generated-table drift at app boot as an
+  optional complementary check (if your project wires one), but the authoritative
+  DB-vs-metadata gate is the Node `verify --db`.
 
 - **`--codegen`** — regeneration drift. Re-runs generation and diffs the result
   against the committed generated files; a non-empty diff means someone edited

package/agent-context/skills/metaobjects-verify/references/migration.md

@@ -21,8 +21,45 @@ npm install --save-dev @metaobjectsdev/cli @metaobjectsdev/migrate-ts
 You point the tool at the **same database your server connects to** — its
 connection is independent of your runtime tier.
 
+## Output format
+
+`meta migrate` (and the CLI generally) is TTY-aware: when stdout is a terminal it
+emits human-readable text; when piped to an agent or CI system it defaults to TOON
+(a compact, unambiguous machine-readable format). Override with `--format`:
+
+```bash
+meta migrate ... --format toon   # TOON (machine-readable, the pipe/agent default)
+meta migrate ... --format json   # JSON
+meta migrate ... --format text   # human-readable text (the TTY default)
+```
+
+Structured errors and next-step hints are also emitted on stdout (not stderr) in the
+active format, so callers can parse them without scraping stderr.
+
 ## The workflow
 
+### Fresh database: baseline first
+
+The default `meta migrate` path is **offline** — it diffs metadata against a
+committed schema snapshot rather than the live DB. On a fresh database there is no
+snapshot yet; run the `baseline` step once before the first migration generate:
+
+```bash
+meta migrate baseline --dialect sqlite     # seed snapshot from metadata (no DB needed)
+meta migrate baseline --dialect postgres   # same for Postgres
+meta migrate baseline --from-db --db postgresql://... --dialect postgres
+                                           # alternative: seed from live DB (for existing schemas)
+```
+
+`baseline` writes a reference snapshot to `.metaobjects/migrations/` and exits
+without emitting any SQL. After this, `meta migrate --dialect <d> --slug <name>`
+operates offline against that snapshot.
+
+If you run `meta migrate` before baselining, the CLI surfaces a structured
+next-step hint pointing to the exact `baseline` command.
+
+### Generating a migration
+
 1. **Generate a migration** by diffing metadata vs the prior state (the live DB or a
    committed snapshot). The engine emits paired `up.sql` + `down.sql`:
 

package/agent-context/templates/always-on.md.mustache

@@ -6,7 +6,7 @@ MetaObjects is a metadata standard: typed metadata in `metaobjects/` is the dura
 spine; generated code is the disposable artifact. Regenerate with `{{codegenCommand}}`.
 
 ## Principles
-- Pattern-derivable from metadata = codegen, never hand-write (FKs, CRUD, validators, finders).
+- Pattern-derivable from metadata = codegen, never hand-write — FKs, CRUD, validators, finders, and the database schema and migrations. The schema is a disposable, generated artifact: change the metadata and regenerate, never hand-write SQL.
 - Never hand-edit generated files — change the metadata and regenerate (three-way merge preserves hand-written regions).
 - Use the generated constants for any string that names metadata.
 - The loaded metadata model is READ-ONLY — never inject nodes or mutate the tree at load time (no "enrich the model on load" hooks). Need an extra field/column? Author it in the metadata, or derive it during codegen (read the metadata, emit output). Mutating the loaded model makes it diverge from what's declared — a bad practice reserved for very rare cases.

package/dist/agent-context/assemble.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../../src/agent-context/assemble.ts"],"names":[],"mappings":"AAEA,OAAO,EAAe,KAAK,aAAa,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AA4BzE,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAAG,aAAa,EAAE,CAoCrF"}
+{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../../src/agent-context/assemble.ts"],"names":[],"mappings":"AAEA,OAAO,EAAe,KAAK,aAAa,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAiCzE,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAAG,aAAa,EAAE,CAsCrF"}

package/dist/agent-context/assemble.js

@@ -13,7 +13,12 @@ function stackLine(contentRoot, stack) {
     const serverPart = stack.servers.length ? stack.servers.join(", ") + " server" : "no server";
     const clientPart = stack.clients.length ? stack.clients.join(", ") + " client" : "no client";
     return {
-        line: `Stack: ${serverPart}, ${clientPart}; migrations are TS.`,
+        // Describe only what the stack actually declares — never assert a migration
+        // binding (the tool states invariants; the project states bindings). The
+        // "schema + migrations are metadata-derived" invariant lives in the template
+        // principle, and the always-installed metaobjects-verify/migration reference
+        // fragment carries the project-agnostic how. See issue #1.
+        line: `Stack: ${serverPart}, ${clientPart}.`,
         codegenCommand: meta ? meta.codegenCommand : "meta gen",
     };
 }
@@ -41,10 +46,12 @@ export function assemble(opts) {
         out.push({ path: `.claude/skills/${skill}/SKILL.md`, contents: body });
         const refDir = join(skillDir, "references");
         if (existsSync(refDir) && statSync(refDir).isDirectory()) {
+            // Deploy-all: every reference fragment is installed; the agent reads the
+            // one(s) matching its stack (SKILL.md points to them). Robust to
+            // stack-detection misses — a narrow/empty stack never starves the agent.
             const refs = readdirSync(refDir)
                 .filter((f) => f.endsWith(".md"))
                 .map((f) => f.replace(/\.md$/, ""))
-                .filter((token) => stack.tokens.has(token))
                 .sort();
             for (const token of refs) {
                 out.push({

package/dist/agent-context/assemble.js.map

@@ -1 +1 @@
-{"version":3,"file":"assemble.js","sourceRoot":"","sources":["../../src/agent-context/assemble.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"assemble.js","sourceRoot":"","sources":["../../src/agent-context/assemble.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/sdk",
-  "version": "0.11.6-rc.1",
+  "version": "0.12.0-rc.1",
   "description": "Workspace helpers and agent-docs utilities for MetaObjects projects.",
   "type": "module",
   "main": "./dist/index.js",
@@ -56,7 +56,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@metaobjectsdev/metadata": "0.11.6-rc.1",
+    "@metaobjectsdev/metadata": "0.12.0-rc.1",
     "zod": "^3.23.0"
   },
   "devDependencies": {

package/scripts/regen-agent-context-conformance.ts

@@ -0,0 +1,31 @@
+// Regenerate the agent-context conformance goldens from the assembler.
+// Run after an intentional change to assemble() (e.g. deploy-all references):
+//   bun scripts/regen-agent-context-conformance.ts
+import {
+  readFileSync, writeFileSync, mkdirSync, rmSync, existsSync, readdirSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { assemble } from "../src/agent-context/assemble.js";
+import { makeStack } from "../src/agent-context/resolve.js";
+
+const CONTENT_ROOT = join(import.meta.dir, "../../../../../agent-context");
+const CORPUS = join(import.meta.dir, "../../../../../fixtures/agent-context-conformance");
+
+for (const name of readdirSync(CORPUS)) {
+  const dir = join(CORPUS, name);
+  if (!existsSync(join(dir, "stack.json"))) continue;
+  const spec = JSON.parse(readFileSync(join(dir, "stack.json"), "utf8")) as {
+    servers: string[];
+    clients: string[];
+  };
+  const stack = makeStack(spec.servers as never, spec.clients as never);
+  const files = assemble({ contentRoot: CONTENT_ROOT, stack });
+  const expDir = join(dir, "expected");
+  rmSync(expDir, { recursive: true, force: true });
+  for (const f of files) {
+    const out = join(expDir, f.path);
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, f.contents);
+  }
+  console.log(`${name} -> ${files.length} files`);
+}

package/src/agent-context/assemble.ts

@@ -16,7 +16,12 @@ function stackLine(contentRoot: string, stack: Stack): { line: string; codegenCo
   const serverPart = stack.servers.length ? stack.servers.join(", ") + " server" : "no server";
   const clientPart = stack.clients.length ? stack.clients.join(", ") + " client" : "no client";
   return {
-    line: `Stack: ${serverPart}, ${clientPart}; migrations are TS.`,
+    // Describe only what the stack actually declares — never assert a migration
+    // binding (the tool states invariants; the project states bindings). The
+    // "schema + migrations are metadata-derived" invariant lives in the template
+    // principle, and the always-installed metaobjects-verify/migration reference
+    // fragment carries the project-agnostic how. See issue #1.
+    line: `Stack: ${serverPart}, ${clientPart}.`,
     codegenCommand: meta ? meta.codegenCommand : "meta gen",
   };
 }
@@ -48,10 +53,12 @@ export function assemble(opts: { contentRoot: string; stack: Stack }): Assembled
 
     const refDir = join(skillDir, "references");
     if (existsSync(refDir) && statSync(refDir).isDirectory()) {
+      // Deploy-all: every reference fragment is installed; the agent reads the
+      // one(s) matching its stack (SKILL.md points to them). Robust to
+      // stack-detection misses — a narrow/empty stack never starves the agent.
       const refs = readdirSync(refDir)
         .filter((f) => f.endsWith(".md"))
         .map((f) => f.replace(/\.md$/, ""))
-        .filter((token) => stack.tokens.has(token))
         .sort();
       for (const token of refs) {
         out.push({