|
| 1 | +# Command-line tools (per-port CLI matrix) |
| 2 | + |
| 3 | +MetaObjects deliberately does **not** ship one universal binary. Per the CLI |
| 4 | +architecture locked in |
| 5 | +[`docs/superpowers/specs/2026-05-30-ts-schema-authority-consolidation-design.md`](../superpowers/specs/2026-05-30-ts-schema-authority-consolidation-design.md) |
| 6 | +and [ADR-0015](../../spec/decisions/ADR-0015-single-shared-migrate-engine.md), the |
| 7 | +command surface splits in two: |
| 8 | + |
| 9 | +- **Schema is language-agnostic** — it operates on the shared canonical metadata + |
| 10 | + a DB connection. It lives in **one canonical Node `meta` CLI** (`migrate`, |
| 11 | + `verify --db`), used by any project regardless of backend language, shipped as a |
| 12 | + standalone binary so non-TS adopters need no Node toolchain for schema ops. This |
| 13 | + is the "Flyway/Atlas-style standalone tool" model — not re-implemented per |
| 14 | + language. |
| 15 | +- **Codegen is inherently language-specific** (`codegen-spring` is Java, |
| 16 | + `codegen-ts` is TS, …) — so it runs in **each language's own build tool**. There |
| 17 | + is no unified codegen binary, no proxying, and no `meta-ts`/`meta-java` names. |
| 18 | + |
| 19 | +## The matrix |
| 20 | + |
| 21 | +| Capability | Tool | Invocation | Notes | |
| 22 | +|---|---|---|---| |
| 23 | +| Project scaffold (`init`) | Node `meta` | `meta init` | TS projects | |
| 24 | +| **Schema migrate** | **Node `meta`** | `meta migrate` | **any backend** — schema is Node-only (ADR-0015) | |
| 25 | +| **Schema drift** (`verify --db`) | **Node `meta`** | `meta verify --db` | **any backend** — live-DB drift, Node-only | |
| 26 | +| TS codegen | Node `meta` | `meta gen` | TS projects | |
| 27 | +| C# codegen | `dotnet meta` | `dotnet meta gen` / `verify` | a .NET tool (`ToolCommandName=dotnet-meta`); invoked `dotnet meta` so it never shadows the Node `meta` | |
| 28 | +| Java/Kotlin codegen | Maven plugin | `mvn metaobjects:generate` (`meta:gen`) | Kotlin generators run through the same goal — see below | |
| 29 | +| Java/Kotlin codegen drift | Maven plugin | `mvn metaobjects:verify` (`meta:verify`) | regenerate + fail on drift vs committed output (generator-neutral) | |
| 30 | +| Python codegen | console-script | `metaobjects gen` / `verify` | `[project.scripts] metaobjects` — **not** `meta` (that's the Node schema CLI) | |
| 31 | + |
| 32 | +## Two meanings of `verify` — keep them distinct |
| 33 | + |
| 34 | +- **Schema `verify --db`** (Node `meta`, any backend): live-DB drift — does the |
| 35 | + database match the metadata? Node-only, ADR-0015. |
| 36 | +- **Codegen `verify`** (`dotnet meta verify`, `mvn meta:verify`, `metaobjects |
| 37 | + verify`): regenerate code from metadata into a temp location and fail if it |
| 38 | + differs from the committed generated output — "a teammate changed metadata |
| 39 | + without regenerating → caught". This is the enterprise-CI primitive added per |
| 40 | + port; it does **not** touch a database. |
| 41 | +- (Separately, the FR-004 **template/prompt** drift check — `Renderer.verify` — |
| 42 | + also surfaces under `verify` in the ports that ship it; it checks `{{...}}` |
| 43 | + references against the payload VO. It is a third, orthogonal facet.) |
| 44 | + |
| 45 | +## Schema is Node-only — by design |
| 46 | + |
| 47 | +No port other than the Node `meta` exposes `migrate` or `verify --db`. The C#, |
| 48 | +Java, Python, and Kotlin command surfaces are **codegen only** (`gen` + codegen |
| 49 | +`verify`). The Java port's former `meta:migrate` / live-DB `meta:verify` Maven |
| 50 | +goals and the C#/Python migrate surfaces were removed in the schema-authority |
| 51 | +consolidation; the only schema entry point anywhere is the Node `meta`. |
| 52 | + |
| 53 | +## Running Kotlin codegen via Maven |
| 54 | + |
| 55 | +`codegen-kotlin`'s generators extend `MultiFileDirectGeneratorBase` — the same |
| 56 | +generator SPI the `meta:gen` Mojo loads — so they run through the existing goal |
| 57 | +with no Kotlin-specific Mojo. Configure a Kotlin generator on the Maven plugin: |
| 58 | + |
| 59 | +```xml |
| 60 | +<plugin> |
| 61 | + <groupId>com.metaobjects</groupId> |
| 62 | + <artifactId>metaobjects-maven-plugin</artifactId> |
| 63 | + <configuration> |
| 64 | + <generators> |
| 65 | + <generator> |
| 66 | + <classname>com.metaobjects.generator.kotlin.KotlinEntityGenerator</classname> |
| 67 | + <args><outputDir>${project.build.directory}/generated-sources/kotlin</outputDir></args> |
| 68 | + </generator> |
| 69 | + </generators> |
| 70 | + </configuration> |
| 71 | +</plugin> |
| 72 | +``` |
| 73 | + |
| 74 | +`mvn metaobjects:generate` emits the Kotlin sources; `mvn metaobjects:verify` |
| 75 | +codegen-drift-checks them. See `server/java/codegen-kotlin/README.md` for the full |
| 76 | +generator list. |
0 commit comments