@metaobjectsdev/cli 0.5.0-rc.1

package/src/index.ts

@@ -0,0 +1,109 @@
+import { resolve } from "node:path";
+import { log } from "./lib/log.js";
+export { defineConfig } from "@metaobjectsdev/codegen-ts";
+export type { MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
+
+const VERSION = "0.2.0";
+
+const HELP_TEXT = `meta — MetaObjects CLI (v${VERSION})
+
+USAGE:
+  meta <command> [flags]
+
+COMMANDS:
+  init                  Scaffold metaobjects/ + .metaobjects/ in the current repo
+  init --refresh-docs   Refresh .metaobjects/AGENTS.md + CLAUDE.md after CLI upgrades
+  gen [<entity>...]     Codegen TS targets from metaobjects/ entities
+  export                Flatten loaded metadata to one canonical JSON artifact
+  migrate               Diff metadata vs live DB; emit migration SQL files
+  --version, -v         Print version
+  --help, -h            Print this help
+
+GLOBAL OPTIONS:
+  --cwd <path>, -C <path>   Run as if launched from <path> (default: current directory)
+
+GEN FLAGS:
+  --dry-run             Compute and print, don't write
+  <entity> [<entity>]   Positional filter on entity names
+  (outDir, dialect, dbImport, extStyle are read from metaobjects.config.ts)
+
+EXPORT FLAGS:
+  --out <file>          Write output to a file (default: stdout)
+
+MIGRATE FLAGS:
+  --db <url>            DB connection URL (required, or set DATABASE_URL or config)
+                        Supports: file:, libsql:, postgres:, postgresql:
+  --dialect sqlite|postgres   Optional override (auto-detected from URL scheme)
+  --out-dir <path>      Migration directory (default: ./.metaobjects/migrations)
+  --slug <name>         Required when changes are present (e.g., add-user-shipping)
+  --allow <csv>         Comma-separated destructive-change permissions:
+                        drop-column,drop-table,type-change,drop-index,drop-fk,nullable-to-not-null
+  --on-ambiguous abort|rename|drop-add   Default abort
+  --dry-run             Print SQL to stdout, don't write
+
+Other commands (ingest, mcp, serve, install-hooks, audit, capture, promote)
+ship in later sub-projects. See https://metaobjects.com for docs.
+`;
+
+export async function run(argv: string[]): Promise<number> {
+  // Extract the global --cwd / -C flag (anywhere in argv). A relative path
+  // resolves against the real process.cwd(). Absent → process.cwd().
+  let cwd = process.cwd();
+  const cleaned: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--cwd" || a === "-C") {
+      const val = argv[i + 1];
+      if (val === undefined) {
+        log.error(`${a} requires a path argument`);
+        return 2;
+      }
+      cwd = resolve(process.cwd(), val);
+      i++; // consume the value
+      continue;
+    }
+    if (a.startsWith("--cwd=")) {
+      const val = a.slice("--cwd=".length);
+      if (val === "") {
+        log.error("--cwd= requires a path argument");
+        return 2;
+      }
+      cwd = resolve(process.cwd(), val);
+      continue;
+    }
+    cleaned.push(a);
+  }
+
+  const [cmd, ...rest] = cleaned;
+  switch (cmd) {
+    case undefined:
+    case "--help":
+    case "-h":
+      log.info(HELP_TEXT);
+      return 0;
+    case "--version":
+    case "-v":
+      log.info(VERSION);
+      return 0;
+    case "init": {
+      const { initCommand } = await import("./commands/init.js");
+      return initCommand(rest, cwd);
+    }
+    case "gen": {
+      const { genCommand } = await import("./commands/gen.js");
+      return genCommand(rest, cwd);
+    }
+    case "export": {
+      const { exportCommand } = await import("./commands/export.js");
+      return exportCommand(rest, cwd);
+    }
+    case "migrate": {
+      const { migrateCommand } = await import("./commands/migrate.js");
+      return migrateCommand(rest, cwd);
+    }
+    default:
+      log.error(`Unknown command: ${cmd}`);
+      log.info(HELP_TEXT);
+      return 2;
+  }
+}

package/src/lib/args.ts

@@ -0,0 +1,157 @@
+import { parseArgs } from "node:util";
+
+// ---------------------------------------------------------------------------
+// init flags
+// ---------------------------------------------------------------------------
+
+export interface InitFlags {
+  force: boolean;
+  quiet: boolean;
+  printOnly: boolean;
+  refreshDocs: boolean;
+}
+
+export function parseInitArgs(argv: string[]): InitFlags {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      force: { type: "boolean", default: false },
+      quiet: { type: "boolean", default: false },
+      "print-only": { type: "boolean", default: false },
+      "refresh-docs": { type: "boolean", default: false },
+    },
+    strict: true,
+    allowPositionals: false,
+  });
+  return {
+    force: !!values.force,
+    quiet: !!values.quiet,
+    printOnly: !!values["print-only"],
+    refreshDocs: !!values["refresh-docs"],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// gen flags — minimal: metaobjects.config.ts holds outDir/dialect/dbImport/extStyle
+// ---------------------------------------------------------------------------
+
+export interface GenFlags {
+  dryRun: boolean;
+  entities: string[];
+}
+
+export function parseGenArgs(argv: string[]): GenFlags {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    options: {
+      "dry-run": { type: "boolean", default: false },
+    },
+    strict: true,
+    allowPositionals: true,
+  });
+  return {
+    dryRun: !!values["dry-run"],
+    entities: positionals,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// export flags
+// ---------------------------------------------------------------------------
+
+export interface ExportFlags {
+  out: string | undefined;
+}
+
+export function parseExportArgs(argv: string[]): ExportFlags {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      out: { type: "string" },
+    },
+    strict: true,
+    allowPositionals: false,
+  });
+  return {
+    out: values.out,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// migrate flags
+// ---------------------------------------------------------------------------
+
+const DIALECTS = ["sqlite", "postgres"] as const;
+type Dialect = (typeof DIALECTS)[number];
+
+const ALLOW_TOKENS = [
+  "drop-column",
+  "drop-table",
+  "type-change",
+  "drop-index",
+  "drop-fk",
+  "nullable-to-not-null",
+] as const;
+type AllowToken = (typeof ALLOW_TOKENS)[number];
+
+const ON_AMBIGUOUS = ["abort", "rename", "drop-add"] as const;
+type OnAmbiguous = (typeof ON_AMBIGUOUS)[number];
+
+export interface MigrateFlags {
+  db: string | undefined;
+  dialect: Dialect | undefined;
+  outDir: string | undefined;
+  slug: string | undefined;
+  allow: AllowToken[];
+  onAmbiguous: OnAmbiguous | undefined;
+  dryRun: boolean;
+}
+
+export function parseMigrateArgs(argv: string[]): MigrateFlags {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      "db": { type: "string" },
+      "dialect": { type: "string" },
+      "out-dir": { type: "string" },
+      "slug": { type: "string" },
+      "allow": { type: "string" },
+      "on-ambiguous": { type: "string" },
+      "dry-run": { type: "boolean", default: false },
+    },
+    strict: true,
+    allowPositionals: false,
+  });
+
+  const dialect = values.dialect as string | undefined;
+  if (dialect !== undefined && !DIALECTS.includes(dialect as Dialect)) {
+    throw new Error(`invalid --dialect '${dialect}'; expected: ${DIALECTS.join(", ")}`);
+  }
+
+  const onAmb = values["on-ambiguous"] as string | undefined;
+  if (onAmb !== undefined && !ON_AMBIGUOUS.includes(onAmb as OnAmbiguous)) {
+    throw new Error(`invalid --on-ambiguous '${onAmb}'; expected: ${ON_AMBIGUOUS.join(", ")}`);
+  }
+
+  const allowRaw = (values.allow as string | undefined) ?? "";
+  const allowTokens = allowRaw.length === 0
+    ? []
+    : allowRaw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  for (const tok of allowTokens) {
+    if (!ALLOW_TOKENS.includes(tok as AllowToken)) {
+      throw new Error(
+        `invalid --allow token '${tok}'; expected one of: ${ALLOW_TOKENS.join(", ")}`,
+      );
+    }
+  }
+
+  return {
+    db: values.db as string | undefined,
+    dialect: dialect as Dialect | undefined,
+    outDir: values["out-dir"] as string | undefined,
+    slug: values.slug as string | undefined,
+    allow: allowTokens as AllowToken[],
+    onAmbiguous: onAmb as OnAmbiguous | undefined,
+    dryRun: !!values["dry-run"],
+  };
+}

package/src/lib/config.ts

@@ -0,0 +1,78 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ConfigSchema, type Config, DEFAULT_METAOBJECTS_DIR } from "@metaobjectsdev/sdk";
+import type { GenFlags, MigrateFlags } from "./args.js";
+
+// ---------------------------------------------------------------------------
+// Built-in defaults
+// ---------------------------------------------------------------------------
+
+const MIGRATE_DEFAULTS = {
+  outDir: "./.metaobjects/migrations",
+  databaseUrl: undefined as string | undefined,
+  dialect: undefined as "sqlite" | "postgres" | undefined,
+  onAmbiguous: "abort" as const,
+  allow: [] as string[],
+};
+
+// ---------------------------------------------------------------------------
+// Resolved option shapes
+// ---------------------------------------------------------------------------
+
+export interface ResolvedGenConfig {
+  dryRun: boolean;
+  entities: string[];
+}
+
+export interface ResolvedMigrateConfig {
+  outDir: string;
+  databaseUrl: string | undefined;
+  dialect: "sqlite" | "postgres" | undefined;
+  onAmbiguous: "abort" | "rename" | "drop-add";
+  allow: string[];
+  slug: string | undefined;
+  dryRun: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Config loader (silent if file missing)
+// ---------------------------------------------------------------------------
+
+async function tryLoadConfig(metaRoot: string): Promise<Config | undefined> {
+  try {
+    const raw = await readFile(join(metaRoot, DEFAULT_METAOBJECTS_DIR, "config.json"), "utf8");
+    return ConfigSchema.parse(JSON.parse(raw));
+  } catch {
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public resolvers
+// ---------------------------------------------------------------------------
+
+export function resolveGenConfig(flags: GenFlags): ResolvedGenConfig {
+  return { dryRun: flags.dryRun, entities: flags.entities };
+}
+
+export async function resolveMigrateConfig(
+  flags: MigrateFlags,
+  metaRoot: string,
+): Promise<ResolvedMigrateConfig> {
+  const config = await tryLoadConfig(metaRoot);
+  const cfgBlock = config?.migrate ?? {};
+
+  const envUrl = process.env.DATABASE_URL;
+
+  return {
+    outDir: flags.outDir ?? cfgBlock.outDir ?? MIGRATE_DEFAULTS.outDir,
+    databaseUrl: flags.db ?? envUrl ?? cfgBlock.databaseUrl ?? MIGRATE_DEFAULTS.databaseUrl,
+    dialect: flags.dialect ?? cfgBlock.dialect ?? MIGRATE_DEFAULTS.dialect,
+    onAmbiguous: flags.onAmbiguous ?? cfgBlock.onAmbiguous ?? MIGRATE_DEFAULTS.onAmbiguous,
+    allow: flags.allow.length > 0
+      ? flags.allow
+      : (cfgBlock.allow ?? MIGRATE_DEFAULTS.allow),
+    slug: flags.slug,
+    dryRun: flags.dryRun,
+  };
+}

package/src/lib/kysely.ts

@@ -0,0 +1,114 @@
+import { Kysely } from "kysely";
+
+export type Dialect = "sqlite" | "postgres";
+
+export interface KyselyHandle {
+  db: Kysely<Record<string, unknown>>;
+  dialect: Dialect;
+  /** URL with credentials redacted, safe for display. */
+  displayUrl: string;
+  /** Idempotent — safe to call multiple times. */
+  close: () => Promise<void>;
+}
+
+/**
+ * Infer dialect from URL scheme. Throws if the scheme isn't recognized.
+ */
+export function inferDialect(url: string): Dialect {
+  const match = /^([a-z]+):/i.exec(url);
+  if (match === null) {
+    throw new Error(`unrecognized URL '${url}'; expected scheme prefix like file:, libsql:, postgres:, postgresql:`);
+  }
+  const scheme = match[1]!.toLowerCase();
+  switch (scheme) {
+    case "file":
+    case "libsql":
+      return "sqlite";
+    case "postgres":
+    case "postgresql":
+      return "postgres";
+    default:
+      throw new Error(
+        `unrecognized URL scheme '${scheme}'; supported: file, libsql, postgres, postgresql`,
+      );
+  }
+}
+
+/**
+ * Strip credentials from a URL for display. Returns unchanged if no userinfo.
+ */
+export function redactUrl(url: string): string {
+  return url.replace(/^([a-z]+:\/\/)([^:@/]+):([^@]+)@/i, "$1$2:***@");
+}
+
+/**
+ * Construct a Kysely instance from a URL.
+ *
+ * For sqlite/libsql, requires `@libsql/kysely-libsql` peer dep.
+ * For postgres, requires `pg` peer dep.
+ *
+ * Surfaces an install hint if the peer dep is missing.
+ */
+export async function buildKyselyFromUrl(
+  url: string,
+  dialectOverride?: Dialect,
+): Promise<KyselyHandle> {
+  const dialect = dialectOverride ?? inferDialect(url);
+  const displayUrl = redactUrl(url);
+
+  if (dialect === "sqlite") {
+    type LibsqlDialectCtor = new (opts: { url: string }) => ConstructorParameters<typeof Kysely<Record<string, unknown>>>[0]["dialect"];
+    let LibsqlDialect: LibsqlDialectCtor;
+    try {
+      const mod = await import("@libsql/kysely-libsql");
+      LibsqlDialect = mod.LibsqlDialect as unknown as LibsqlDialectCtor;
+    } catch {
+      throw new Error(
+        `dialect 'sqlite' requires '@libsql/kysely-libsql'; install it: 'bun add @libsql/kysely-libsql'`,
+      );
+    }
+    const db = new Kysely<Record<string, unknown>>({ dialect: new LibsqlDialect({ url }) });
+    let closed = false;
+    return {
+      db,
+      dialect,
+      displayUrl,
+      close: async () => {
+        if (closed) return;
+        closed = true;
+        try { await db.destroy(); } catch { /* swallow */ }
+      },
+    };
+  }
+
+  // postgres
+  type PgPoolModule = { Pool: new (opts: { connectionString: string }) => unknown; default?: { Pool: new (opts: { connectionString: string }) => unknown } };
+  let pg: PgPoolModule;
+  let PostgresDialect: typeof import("kysely").PostgresDialect;
+  try {
+    pg = await import("pg") as unknown as PgPoolModule;
+    ({ PostgresDialect } = await import("kysely"));
+  } catch {
+    throw new Error(
+      `dialect 'postgres' requires 'pg'; install it: 'bun add pg'`,
+    );
+  }
+  const PoolCtor = pg.Pool ?? pg.default?.Pool;
+  if (PoolCtor === undefined) {
+    throw new Error(`dialect 'postgres' requires 'pg' (no Pool export found)`);
+  }
+  const pool = new PoolCtor({ connectionString: url });
+  const db = new Kysely<Record<string, unknown>>({ dialect: new PostgresDialect({ pool: pool as never }) });
+  let closed = false;
+  return {
+    db,
+    dialect,
+    displayUrl,
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      try { await db.destroy(); } catch { /* swallow */ }
+      try { await (pool as unknown as { end: () => Promise<void> }).end(); } catch { /* swallow */ }
+    },
+  };
+}

package/src/lib/load-metaobjects-config.ts

@@ -0,0 +1,89 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createJiti } from "jiti";
+import type { MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
+
+const CONFIG_FILE = "metaobjects.config.ts";
+
+// Resolve @metaobjectsdev/codegen-ts from the CLI's own node_modules so that
+// metaobjects.config.ts (which lives in the user's project) can import it even
+// when the user's project has no direct dependency on the package.
+//
+// When compiled: import.meta.url is dist/src/lib/load-metaobjects-config.js — four
+// levels up (past lib/, src/, dist/) reaches the CLI package root (packages/cli/).
+// When run as TS source (e.g. bun test): import.meta.url is src/lib/load-metaobjects-config.ts
+// — three levels up (past lib/, src/) reaches the package root.
+const _thisFile = fileURLToPath(import.meta.url);
+const _isCompiled = _thisFile.includes("/dist/");
+const _cliDir = resolve(_thisFile, _isCompiled ? "../../../.." : "../../..");
+const _require = createRequire(import.meta.url);
+// Each aliased specifier maps to a compiled-output path and a TS-source path,
+// relative to _cliDir. When running from compiled output we resolve into the
+// package's dist/; when running TS source directly (bun test, `meta` run from
+// the workspace) we resolve into src/ so the CLI never depends on a stale,
+// unrebuilt dist/.
+//
+// The three workspace deps resolve through the CLI's own node_modules.
+// @metaobjectsdev/cli is this package itself, so it resolves directly from
+// _cliDir rather than through node_modules (which would be a non-existent
+// self-referential symlink).
+const CLI_PKG_PATHS: Record<string, { dist: string; src: string }> = {
+  "@metaobjectsdev/codegen-ts": {
+    dist: "node_modules/@metaobjectsdev/codegen-ts/dist/index.js",
+    src: "node_modules/@metaobjectsdev/codegen-ts/src/index.ts",
+  },
+  "@metaobjectsdev/codegen-ts/generators": {
+    dist: "node_modules/@metaobjectsdev/codegen-ts/dist/generators/index.js",
+    src: "node_modules/@metaobjectsdev/codegen-ts/src/generators/index.ts",
+  },
+  "@metaobjectsdev/codegen-ts-tanstack": {
+    dist: "node_modules/@metaobjectsdev/codegen-ts-tanstack/dist/index.js",
+    src: "node_modules/@metaobjectsdev/codegen-ts-tanstack/src/index.ts",
+  },
+  "@metaobjectsdev/cli": {
+    dist: "dist/src/index.js",
+    src: "src/index.ts",
+  },
+};
+
+function resolveCliPkg(specifier: string): string {
+  const paths = CLI_PKG_PATHS[specifier];
+  if (paths !== undefined) {
+    return resolve(_cliDir, _isCompiled ? paths.dist : paths.src);
+  }
+  return _require.resolve(specifier);
+}
+
+export async function loadMetaobjectsConfig(projectRoot: string): Promise<MetaobjectsGenConfig> {
+  const fullPath = resolve(projectRoot, CONFIG_FILE);
+  if (!existsSync(fullPath)) {
+    throw new Error(
+      `metaobjects.config.ts not found at ${fullPath}. Run 'meta init' to scaffold one.`,
+    );
+  }
+  // Use import.meta.url as base so jiti resolves workspace deps (@metaobjectsdev/*)
+  // from the CLI's own node_modules, not from the user's project root.
+  // The alias map redirects codegen-ts imports to the CLI's own copy so that
+  // user projects don't need @metaobjectsdev/codegen-ts as a direct dependency.
+  const jiti = createJiti(import.meta.url, {
+    interopDefault: true,
+    alias: {
+      "@metaobjectsdev/codegen-ts": resolveCliPkg("@metaobjectsdev/codegen-ts"),
+      "@metaobjectsdev/codegen-ts/generators": resolveCliPkg("@metaobjectsdev/codegen-ts/generators"),
+      "@metaobjectsdev/codegen-ts-tanstack": resolveCliPkg("@metaobjectsdev/codegen-ts-tanstack"),
+      "@metaobjectsdev/cli": resolveCliPkg("@metaobjectsdev/cli"),
+    },
+  });
+  const raw = (await jiti.import(fullPath)) as MetaobjectsGenConfig | { default: MetaobjectsGenConfig };
+  // jiti's interopDefault doesn't always unwrap the default export when accessed
+  // across module boundaries — explicitly unwrap if present.
+  const cfg = (raw && typeof raw === "object" && "default" in raw && raw.default
+    ? (raw as { default: MetaobjectsGenConfig }).default
+    : raw) as MetaobjectsGenConfig;
+  if (!cfg || typeof cfg !== "object" || !Array.isArray(cfg.generators)) {
+    throw new Error(`metaobjects.config.ts at ${fullPath} did not export a valid MetaobjectsGenConfig (missing 'generators' array).`);
+  }
+  return cfg;
+}

package/src/lib/log.ts

@@ -0,0 +1,5 @@
+export const log = {
+  info: (msg: string) => console.log(msg),
+  warn: (msg: string) => console.error(`meta: ${msg}`),
+  error: (msg: string) => console.error(`meta: ${msg}`),
+};