okmodel 0.0.0 → 0.1.0

package/dist/tooling/cli.js

@@ -0,0 +1,193 @@
+import"../shared/y9m15dfv.js";
+import {
+  formatPlan,
+  buildProject,
+  generateProject,
+  planProject,
+  checkProject
+} from "../shared/kynx7vbm.js";
+import {
+  OkmError2
+} from "../shared/ycwz42az.js";
+
+// src/tooling/cli.ts
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/tooling/migrate/commands.ts
+async function run(argv, io) {
+  const cwd = io?.cwd ?? process.cwd();
+  const stdout = io?.stdout ?? ((text) => process.stdout.write(text));
+  const [command, ...rest] = argv;
+  if (command === "build") {
+    const directory = await buildProject(cwd);
+    stdout(`${directory}
+`);
+    return;
+  }
+  if (command === "check") {
+    await checkProject(cwd);
+    stdout(`ok
+`);
+    return;
+  }
+  if (command === "generate") {
+    const parsed = splitFlags(rest);
+    const path = await generateProject(cwd, parsed.name ?? "migration", parsed.flags);
+    stdout(path === undefined ? `no changes
+` : `${path}
+`);
+    return;
+  }
+  if (command === "dev") {
+    const { devProject } = await import("../shared/vkm3q4x1.js");
+    stdout(await devProject(cwd));
+    return;
+  }
+  if (command === "push") {
+    const { pushProject } = await import("../shared/g2v6gnc8.js");
+    stdout(await pushProject(cwd, invoke(splitFlags(rest))));
+    return;
+  }
+  if (command === "migrate") {
+    const sub = rest[0];
+    const parsed = splitFlags(rest.slice(1));
+    if (sub === "plan") {
+      if (parsed.name === undefined) {
+        throw new OkmError2("invalid", "okm migrate plan needs a name.");
+      }
+      stdout(formatPlan(await planProject(cwd, parsed.name, parsed.flags)));
+      return;
+    }
+    if (sub === "apply") {
+      const { applyProject } = await import("../shared/g2v6gnc8.js");
+      stdout(await applyProject(cwd, invoke(parsed)));
+      return;
+    }
+    if (sub === "status") {
+      const { statusProject } = await import("../shared/ax16zpvm.js");
+      stdout(await statusProject(cwd, invoke(parsed)));
+      return;
+    }
+  }
+  throw new OkmError2("invalid", `Unknown command ${command ?? ""}.`);
+}
+function invoke(parsed) {
+  return {
+    ...parsed.target !== undefined ? { target: parsed.target } : {},
+    allowProtected: parsed.allowProtected,
+    allowPooler: parsed.allowPooler,
+    ...parsed.lockTimeoutMs !== undefined ? { lockTimeoutMs: parsed.lockTimeoutMs } : {},
+    ...parsed.statementTimeoutMs !== undefined ? { statementTimeoutMs: parsed.statementTimeoutMs } : {}
+  };
+}
+function splitFlags(args) {
+  const flags = [];
+  const positionals = [];
+  let target;
+  let allowProtected = false;
+  let allowPooler = false;
+  let lockTimeoutMs;
+  let statementTimeoutMs;
+  for (let index = 0;index < args.length; index += 1) {
+    const arg = args[index] ?? "";
+    if (arg === "--replace") {
+      const value = args[index + 1];
+      if (value === undefined) {
+        throw new OkmError2("OKM1541", "--replace needs table.column.old=new.", {
+          fix: { summary: "Pass --replace <table>.<column>.<old>=<new>." }
+        });
+      }
+      flags.push(value);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--replace=")) {
+      flags.push(arg.slice("--replace=".length));
+      continue;
+    }
+    if (arg === "--allow-protected") {
+      allowProtected = true;
+      continue;
+    }
+    if (arg === "--allow-pooler") {
+      allowPooler = true;
+      continue;
+    }
+    if (arg === "--target") {
+      const value = args[index + 1];
+      if (value === undefined || value.startsWith("--")) {
+        throw new OkmError2("OKM1853", "--target needs a name.", {
+          fix: { summary: "Pass --target <name>." }
+        });
+      }
+      target = value;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--target=")) {
+      target = arg.slice("--target=".length);
+      continue;
+    }
+    if (arg === "--lock-timeout" || arg === "--statement-timeout") {
+      const value = numberFlag(arg, args[index + 1]);
+      if (arg === "--lock-timeout")
+        lockTimeoutMs = value;
+      else
+        statementTimeoutMs = value;
+      index += 1;
+      continue;
+    }
+    positionals.push(arg);
+  }
+  return {
+    name: positionals[0],
+    flags,
+    target,
+    allowProtected,
+    allowPooler,
+    lockTimeoutMs,
+    statementTimeoutMs
+  };
+}
+function numberFlag(flag, value) {
+  const parsed = value === undefined ? Number.NaN : Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new OkmError2("invalid", `${flag} needs a number of milliseconds.`, {
+      fix: { summary: `Pass ${flag} <milliseconds>.` }
+    });
+  }
+  return parsed;
+}
+
+// src/tooling/cli.ts
+var here = dirname(fileURLToPath(import.meta.url));
+var packageJsonPath = join(here, "..", "..", "package.json");
+if (process.argv.includes("--version")) {
+  process.stdout.write(`${readPackageVersion(packageJsonPath)}
+`);
+} else if (process.argv.length > 2) {
+  try {
+    await run(process.argv.slice(2));
+  } catch (error) {
+    if (error instanceof OkmError2) {
+      process.stderr.write(`${error.code}: ${error.message}
+${error.fix.summary}
+`);
+      process.exitCode = 1;
+    } else {
+      throw error;
+    }
+  }
+}
+function readPackageVersion(path) {
+  const parsed = JSON.parse(readFileSync(path, "utf8"));
+  if (!isRecord(parsed) || typeof parsed.version !== "string") {
+    throw new Error(`No string version in ${path}`);
+  }
+  return parsed.version;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}

package/dist/tooling/errors/registry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Doctor text for every OKM code in spec §21.
+ *
+ * This module is not on the runtime entry. A process that never explains a
+ * code does not load it. Titles stay short. The summary and the fix are the
+ * page `okm doctor <code>` will print.
+ */
+/** One code in the error registry. */
+export type ErrorDoc = {
+    /** Spec code, for example `OKM1020`. */
+    readonly code: string;
+    /** Short name. */
+    readonly title: string;
+    /** What went wrong. */
+    readonly summary: string;
+    /** What to do. */
+    readonly fix: string;
+};
+/**
+ * Every OKM code spec §21 names, in numeric order.
+ *
+ * OKM1111 is a dynamic call the driver's capabilities do not allow.
+ */
+export declare const ERROR_DOCS: readonly ErrorDoc[];
+/**
+ * Looks up one code.
+ *
+ * The map is built on the first call, not at import.
+ *
+ * @param code - Spec code, for example `OKM1401`
+ * @returns The doctor entry, or `undefined` when the code is not in spec §21
+ */
+export declare function errorDoc(code: string): ErrorDoc | undefined;

package/dist/tooling/migrate/apply.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Applies migrations on one target.
+ *
+ * A run holds a session advisory lock. Transactional steps of one migration
+ * share a transaction. Steps Postgres cannot run there (`CREATE INDEX
+ * CONCURRENTLY`, `ADD VALUE`, `VACUUM`) are their own steps. Each finished
+ * step is a history row. A later apply skips those rows.
+ */
+import { type PlanStep } from "./plan.js";
+import type { StoredMigration } from "./files.js";
+import { type InvokeFlags } from "./policy.js";
+/** One step with its index in the migration file. */
+export type IndexedStep = {
+    readonly index: number;
+    readonly step: PlanStep;
+};
+/** Steps that commit together, or one step that cannot. */
+export type ApplyUnit = {
+    readonly migrationId: string;
+    readonly catalogHash: string;
+    /** True when this unit is the last step of its migration. */
+    readonly finishes: boolean;
+    readonly transactional: boolean;
+    readonly steps: readonly IndexedStep[];
+};
+/** What {@link applyTarget} needs. The URL is resolved by the caller. */
+export type ApplyRequest = {
+    readonly url: string;
+    readonly target: string;
+    readonly protected: boolean;
+    readonly allowProtected?: boolean;
+    readonly allowPooler?: boolean;
+    readonly searchPath?: string;
+    readonly lockTimeoutMs?: number;
+    readonly statementTimeoutMs?: number;
+    readonly retries?: number;
+    readonly migrations: readonly StoredMigration[];
+    /** Runs after the advisory lock is held and before the first step. */
+    readonly onLocked?: () => void;
+};
+/** Migrations that ran at least one step in this invocation. */
+export type ApplyReport = {
+    readonly target: string;
+    readonly applied: readonly string[];
+};
+/**
+ * Groups pending steps into the transactions apply will run.
+ *
+ * A step Postgres cannot run inside a transaction is its own unit even when
+ * the plan marked it transactional.
+ *
+ * @param migration - One file
+ * @param done - Keys `${migrationId}:${stepIndex}` already in history
+ * @returns Units in apply order
+ */
+export declare function applyUnits(migration: StoredMigration, done: ReadonlySet<string>): readonly ApplyUnit[];
+/**
+ * Applies pending migrations on one target.
+ *
+ * The connection is reserved for the whole run so the advisory lock stays
+ * session-scoped. Lock timeout retries that step. Any other failure stops
+ * at that step.
+ *
+ * @param request - Target, flags, and the migrations to consider
+ * @returns The target and the migration ids that ran
+ */
+export declare function applyTarget(request: ApplyRequest): Promise<ApplyReport>;
+/**
+ * Applies the migrations in the project to the selected target.
+ *
+ * @param cwd - Project directory
+ * @param flags - `--target`, protection, pooler, and timeouts
+ * @returns Text for stdout, including the target name
+ */
+export declare function applyProject(cwd: string, flags: InvokeFlags): Promise<string>;
+/**
+ * Prototype sync. Blocked on a protected target.
+ *
+ * A target named production is not special. Protection is the `protected`
+ * flag (spec §19.8). The plan's statements run as one migration.
+ *
+ * @param cwd - Project directory
+ * @param flags - Target and protection flags
+ * @returns Text for stdout
+ */
+export declare function pushProject(cwd: string, flags: InvokeFlags): Promise<string>;

package/dist/tooling/migrate/commands.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `okm` command dispatch.
+ *
+ * The bin wrapper imports {@link run}. Importing this module does not parse
+ * `process.argv`.
+ */
+/** Where a command reads the project and writes its text. */
+export type CommandIo = {
+    readonly cwd?: string;
+    readonly stdout?: (text: string) => void;
+};
+/**
+ * Runs one `okm` invocation.
+ *
+ * `--version` stays in the bin. This function handles `build`, `check`,
+ * `generate`, `dev`, `push`, and `migrate plan`, `apply`, and `status`.
+ *
+ * @param argv - Arguments after the program name
+ * @param io - Working directory and stdout. Defaults to the process
+ */
+export declare function run(argv: readonly string[], io?: CommandIo): Promise<void>;

package/dist/tooling/migrate/config.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Project configuration for `okm`.
+ *
+ * Exported from `okmodel/migrate`. The runtime entry stays free of tooling.
+ */
+/** One migration target. A string is the URL. Protection defaults to false. */
+export type TargetInput = string | {
+    readonly url?: string;
+    /** Refuses contract, push, and other non-expand work unless `--allow-protected`. */
+    readonly protected?: boolean;
+};
+/** Paths and targets `okm` reads. */
+export type MigrateConfig = {
+    /** Module that exports the built schema. */
+    readonly schema: string;
+    /** Directory of table files. `okm check` reports one that the schema does not import. */
+    readonly tables?: string;
+    /** Directory of generated SQL. Defaults to `migrations`. */
+    readonly migrations?: string;
+    /** Build output. Defaults to `.okm`. */
+    readonly out?: string;
+    /**
+     * The one target named `default`.
+     *
+     * A direct Postgres URL, not a pooler. Use {@link MigrateConfig.targets} when
+     * there is more than one.
+     */
+    readonly database?: TargetInput;
+    /** Named targets. Replaces `database`. */
+    readonly targets?: Readonly<Record<string, TargetInput>>;
+    /** Apply against a known pooler URL. The default refuses those hosts. */
+    readonly allowPooler?: boolean;
+    /** Milliseconds for `lock_timeout` and `statement_timeout` during apply. */
+    readonly timeouts?: {
+        readonly lock?: number;
+        readonly statement?: number;
+    };
+};
+/**
+ * Returns the config unchanged.
+ *
+ * `database` is one target named `default`. `targets` is the named map.
+ * Commands that touch a database require `--target` when several exist.
+ *
+ * @param config - Schema module, directories, and targets
+ * @returns The same config
+ */
+export declare function defineConfig(config: MigrateConfig): MigrateConfig;

package/dist/tooling/migrate/dev.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `okm dev`.
+ *
+ * When a target named `dev` is configured, the command names it. Otherwise it
+ * creates a PGlite database in `.okm/dev-db`.
+ */
+/**
+ * Starts the dev database.
+ *
+ * A configured target named `dev` is used as it is. With no such target,
+ * PGlite is opened on `.okm/dev-db` so the directory exists for the app.
+ *
+ * @param cwd - Project directory
+ * @returns The target line, or the data directory
+ */
+export declare function devProject(cwd: string): Promise<string>;

package/dist/tooling/migrate/equal.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Structural equality for two catalogs.
+ *
+ * Introspection stamps the same provenance on every object, so the canonical
+ * document is the comparison. Authoring text is not compared to a reprint.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+/**
+ * Reports whether two catalogs serialise to the same bytes.
+ *
+ * @param left - First catalog
+ * @param right - Second catalog
+ * @returns `true` when the canonical documents match
+ */
+export declare function catalogsEqual(left: Catalog, right: Catalog): boolean;

package/dist/tooling/migrate/files.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Migration files on disk: SQL from {@link formatPlan} plus the catalog hash.
+ */
+import { type PlanStep } from "./plan.js";
+/** One migration the applier can run and resume. */
+export type StoredMigration = {
+    readonly id: string;
+    readonly catalogHash: string;
+    readonly steps: readonly PlanStep[];
+};
+/**
+ * Loads `*.sql` migrations and the sibling catalog snapshot.
+ *
+ * Files are applied in name order. A SQL file without its catalog is refused.
+ *
+ * @param directory - Migrations directory. Missing means there are none
+ * @returns Migrations in apply order
+ */
+export declare function loadMigrations(directory: string): readonly StoredMigration[];

package/dist/tooling/migrate/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Public entry for `okmodel/migrate`.
+ *
+ * `defineConfig` and its types. The CLI imports planning and apply helpers
+ * from their modules, so those names are not exported.
+ */
+export { defineConfig, type MigrateConfig, type TargetInput } from "./config.js";

package/dist/tooling/migrate/index.js

@@ -0,0 +1,7 @@
+// src/tooling/migrate/config.ts
+function defineConfig(config) {
+  return config;
+}
+export {
+  defineConfig
+};

package/dist/tooling/migrate/plan.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Diffs two catalogs into an ordered, classified plan.
+ *
+ * Renames are applied to a copy of the previous catalog before the diff, so
+ * a declared rename is not a drop and an add. An unexplained drop-and-add is
+ * OKM1530. The planner never prompts.
+ *
+ * Picklist and enum removals are expand `UPDATE`s plus a contract swap
+ * (D131). Those data steps are plain statements here. Batching them is P52.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+import type { DeclaredRename } from "../../dialects/pg/declarations.js";
+import { type Replacement } from "./values.js";
+/** Expand, contract, or a step that is neither. */
+export type MigrationClass = "expand" | "contract" | "unclassified";
+/**
+ * One statement in a plan.
+ *
+ * `backfill` is data; P16B runs it as written. `transactional: false` marks a
+ * step that cannot share a transaction with a later use (`ALTER TYPE … ADD
+ * VALUE`, spec 19.2).
+ */
+export type PlanStep = {
+    readonly sql: string;
+    readonly class: MigrationClass;
+    readonly action: "ddl" | "backfill";
+    readonly lock: string;
+    readonly transactional: boolean;
+};
+/** A named plan and the class of its strictest step. */
+export type MigrationPlan = {
+    readonly name: string;
+    readonly class: MigrationClass;
+    readonly steps: readonly PlanStep[];
+};
+/** What the planner needs besides the two catalogs. */
+export type PlanRequest = {
+    readonly before: Catalog;
+    readonly after: Catalog;
+    readonly renames?: readonly DeclaredRename[];
+    readonly replacements?: readonly Replacement[];
+    readonly schema?: string;
+    /** Concrete schema written into the SQL. Identities stay logical. */
+    readonly name?: string;
+};
+/**
+ * Builds a plan from catalog `before` to catalog `after`.
+ *
+ * @param request - Catalogs, declared renames, and `--replace` flags
+ * @returns Steps in apply order, with one class for the plan
+ */
+export declare function planMigration(request: PlanRequest): MigrationPlan;
+/**
+ * Prints a plan. The text is SQL plus class comments, never TypeScript.
+ *
+ * @param plan - Plan from {@link planMigration}
+ * @returns The text `okm generate` writes and `okm migrate plan` prints
+ */
+export declare function formatPlan(plan: MigrationPlan): string;
+/**
+ * Reads a plan written by {@link formatPlan}.
+ *
+ * @param text - SQL file text
+ * @returns The plan. The header class is kept when the file has no steps
+ */
+export declare function parsePlan(text: string): MigrationPlan;
+/**
+ * Renames whose previous name is absent from the last snapshot.
+ *
+ * No snapshot means nothing is stale: there is no history to disagree with.
+ *
+ * @param previous - Last migration catalog, or `undefined` when there is none
+ * @param renames - Declarations on the current schema
+ * @returns Messages, empty when every rename still matches
+ */
+export declare function staleRenames(previous: Catalog | undefined, renames: readonly DeclaredRename[]): readonly string[];

package/dist/tooling/migrate/policy.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Target names, the aliasing guard, pooler refusal, and the protection policy.
+ *
+ * One function, {@link assertTargetPolicy}, is what every entry point calls.
+ * Protection is a property of the target. It is not read from `NODE_ENV`.
+ */
+import type { MigrateConfig } from "./config.js";
+/** An operation the policy table allows or blocks. */
+export type PolicyOperation = "plan" | "status" | "check" | "drift" | "verify" | "pull" | "catalog-export" | "inspect" | "expand" | "reference" | "provision" | "contract" | "unclassified" | "push" | "backfill" | "seed" | "history-repair" | "drop" | "rollback";
+/** Flags shared by commands that touch a target. */
+export type InvokeFlags = {
+    readonly target?: string;
+    readonly allowProtected: boolean;
+    readonly allowPooler: boolean;
+    readonly lockTimeoutMs?: number;
+    readonly statementTimeoutMs?: number;
+};
+/** A resolved migration target. The plan stores the name, not the URL. */
+export type TargetRecord = {
+    readonly name: string;
+    readonly url: string;
+    readonly protected: boolean;
+    readonly host: string;
+    readonly port: string;
+    readonly database: string;
+};
+/**
+ * Refuses an operation the target's protection does not allow.
+ *
+ * `--allow-protected` is per invocation. It does not lift `drop` or `rollback`.
+ * `provision` is allowed here; the caller still refuses a target that is not empty.
+ *
+ * @param target - Name and protection flag
+ * @param operation - What the entry point is about to do
+ * @param allowProtected - The invocation passed `--allow-protected`
+ */
+export declare function assertTargetPolicy(target: {
+    readonly name: string;
+    readonly protected: boolean;
+}, operation: PolicyOperation, allowProtected?: boolean): void;
+/**
+ * Fails when targets on one host, port, and database disagree about protection.
+ *
+ * Two unprotected targets may share a database. The comparison ignores schema.
+ *
+ * @param targets - Resolved targets
+ */
+export declare function assertTargetAlias(targets: readonly TargetRecord[]): void;
+/**
+ * Refuses a known pooler URL.
+ *
+ * Apply needs one session for the advisory lock. A transaction-mode pooler
+ * does not keep that session. `--allow-pooler` is the override.
+ *
+ * @param url - Target URL
+ * @param allowPooler - The invocation opted in
+ */
+export declare function assertDirectConnection(url: string, allowPooler: boolean): void;
+/**
+ * Lists configured targets.
+ *
+ * `database` is the target named `default`. `targets` replaces it. Setting
+ * both is refused.
+ *
+ * @param config - Project config
+ * @returns Targets in name order
+ */
+export declare function listTargets(config: MigrateConfig): readonly TargetRecord[];
+/**
+ * Picks the target a command that must not guess will use.
+ *
+ * One configured target is that target. Several require `name` (OKM1853).
+ *
+ * @param config - Project config
+ * @param name - `--target`, when the command passed one
+ * @returns The target
+ */
+export declare function selectTarget(config: MigrateConfig, name: string | undefined): TargetRecord;

package/dist/tooling/migrate/project.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `okm build`, `okm generate`, `okm check`, and `okm migrate plan`.
+ *
+ * Build writes the catalog it already validated. Check and dev read
+ * `.catalog`, which runs that validation. Generate writes SQL only.
+ */
+import { type DeclaredRename } from "../../dialects/pg/declarations.js";
+import type { Catalog } from "../../contracts/catalog/types.js";
+import { type MigrateConfig } from "./config.js";
+import { type MigrationPlan } from "./plan.js";
+/**
+ * Validates the schema and writes `.okm/`.
+ *
+ * @param cwd - Project directory
+ * @returns The output directory
+ */
+export declare function buildProject(cwd: string): Promise<string>;
+/**
+ * Plans the current schema against the latest snapshot and writes SQL.
+ *
+ * An empty plan writes nothing. The file is SQL, not TypeScript.
+ *
+ * @param cwd - Project directory
+ * @param name - Migration name
+ * @param flags - `--replace` values
+ * @returns The SQL path, or `undefined` when nothing changed
+ */
+export declare function generateProject(cwd: string, name: string, flags: readonly string[]): Promise<string | undefined>;
+/**
+ * Plans and returns the text. Nothing is written.
+ *
+ * @param cwd - Project directory
+ * @param name - Plan name
+ * @param flags - `--replace` values
+ * @returns The plan
+ */
+export declare function planProject(cwd: string, name: string, flags: readonly string[]): Promise<MigrationPlan>;
+/**
+ * Validates the schema, then reports stale renames and unlisted table files.
+ *
+ * @param cwd - Project directory
+ */
+export declare function checkProject(cwd: string): Promise<void>;
+/**
+ * Table files whose names do not appear in the schema module.
+ *
+ * @param schemaSource - Source text of the schema module
+ * @param fileNames - File names in the tables directory
+ * @returns Files `okm check` reports as OKM1024
+ */
+export declare function unlistedTableFiles(schemaSource: string, fileNames: readonly string[]): readonly string[];
+/**
+ * The catalogs `okm push` diffs, after stale renames are refused.
+ *
+ * @param cwd - Project directory
+ * @returns The previous snapshot, the current catalog, and declared renames
+ */
+export declare function projectHead(cwd: string): Promise<{
+    readonly previous: Catalog;
+    readonly catalog: Catalog;
+    readonly renames: readonly DeclaredRename[];
+}>;
+/**
+ * Loads `okmodel.config.ts`.
+ *
+ * @param cwd - Project directory
+ * @returns The config object
+ */
+export declare function loadConfig(cwd: string): Promise<MigrateConfig>;