okmodel 0.0.0 → 0.1.1

package/dist/shared/zhc5vmgf.js

@@ -0,0 +1,257 @@
+import {
+  isConnectionSqlstate,
+  isConnectionFailure
+} from "./ngk8gj61.js";
+import {
+  OkmError2,
+  stripRowValues,
+  matchingParen
+} from "./ycwz42az.js";
+
+// src/dialects/pg/errors.ts
+function mapPostgresError(error, options) {
+  if (error instanceof OkmError2)
+    return error;
+  if (!isDriverError(error))
+    return OkmError2.from(error);
+  const kind = kindOf(error);
+  const columns = columnsOf(error);
+  const fieldReason = kind === "not_null" ? "not_null" : reasonOf(kind, error.table, error.constraint);
+  const values = options?.includeValues === true ? valuesOf(error.detail, columns) : undefined;
+  const code = kind === "outcome_unknown" ? "OKM1401" : kind;
+  return new OkmError2(code, summaryOf(kind, error, columns, fieldReason), {
+    kind,
+    fieldReason,
+    ...error.table !== undefined ? { table: error.table } : {},
+    ...columns.length > 0 ? { columns } : {},
+    ...error.constraint !== undefined ? { constraint: error.constraint } : {},
+    ...error.sqlstate !== undefined ? { sqlstate: error.sqlstate } : {},
+    batchIndex: error.batchIndex,
+    cause: error.cause ?? error,
+    ...options?.includeValues === true && values !== undefined ? { includeValues: true, values } : {},
+    ...options?.http !== undefined ? { http: options.http } : {}
+  });
+}
+function isDriverError(error) {
+  if (!(error instanceof Error) || error.name !== "DriverError")
+    return false;
+  return "batchIndex" in error;
+}
+function kindOf(error) {
+  if (error.kind === "timeout" || error.kind === "cancelled" || error.kind === "outcome_unknown") {
+    return error.kind;
+  }
+  const sqlstate = error.sqlstate;
+  if (sqlstate !== undefined) {
+    const mapped = kindFromSqlstate(sqlstate);
+    if (mapped !== undefined)
+      return mapped;
+  }
+  if (isConnectionFailure(error))
+    return "unavailable";
+  return "driver";
+}
+function kindFromSqlstate(sqlstate) {
+  switch (sqlstate) {
+    case "23505":
+      return "unique";
+    case "23502":
+      return "not_null";
+    case "23514":
+      return "check";
+    case "23503":
+    case "23001":
+      return "foreign_key";
+    case "23P01":
+      return "exclusion";
+    case "23000":
+      return "conflict";
+    case "40001":
+      return "serialization";
+    case "40P01":
+      return "deadlock";
+    case "55P03":
+      return "lock_timeout";
+    case "57014":
+      return "timeout";
+    case "40003":
+      return "outcome_unknown";
+    case "25006":
+      return "read_only";
+    default:
+      if (isConnectionSqlstate(sqlstate))
+        return "unavailable";
+      if (sqlstate.startsWith("22"))
+        return "invalid";
+      if (sqlstate.startsWith("53"))
+        return "unavailable";
+      return;
+  }
+}
+function reasonOf(kind, table, constraint) {
+  if (constraint === undefined || constraint.length === 0)
+    return kind;
+  if (table !== undefined) {
+    if (constraint === `${table}_pkey`)
+      return "pkey";
+    const prefix = `${table}_`;
+    if (constraint.startsWith(prefix)) {
+      const rest = constraint.slice(prefix.length);
+      const nameKey = nameKeyOf(rest);
+      if (nameKey !== undefined)
+        return nameKey;
+    }
+  }
+  return constraint;
+}
+function nameKeyOf(rest) {
+  const tags = ["_fkey", "_check", "_key"];
+  for (const tag of tags) {
+    if (rest.endsWith(tag) && rest.length > tag.length)
+      return rest.slice(0, -tag.length);
+  }
+  return;
+}
+function columnsOf(error) {
+  if (error.column !== undefined && error.column.length > 0)
+    return [unquote(error.column)];
+  const detail = error.detail;
+  if (detail !== undefined) {
+    const fromKey = keyColumns(detail);
+    if (fromKey.length > 0)
+      return fromKey;
+  }
+  const fromMessage = quotedColumn(error.message);
+  return fromMessage === undefined ? [] : [fromMessage];
+}
+function keyColumns(detail) {
+  const marker = "Key (";
+  const start = detail.indexOf(marker);
+  if (start === -1)
+    return [];
+  const open = start + marker.length - 1;
+  const end = matchingParen(detail, open);
+  if (end === undefined)
+    return [];
+  return splitList(detail.slice(open + 1, end));
+}
+function valuesOf(detail, columns) {
+  if (detail === undefined || columns.length === 0)
+    return;
+  const marker = "=(";
+  const start = detail.indexOf(marker);
+  if (start === -1)
+    return;
+  const open = start + 1;
+  const end = matchingParen(detail, open);
+  if (end === undefined)
+    return;
+  const parts = splitList(detail.slice(open + 1, end));
+  if (parts.length !== columns.length)
+    return;
+  const values = {};
+  for (let index = 0;index < columns.length; index += 1) {
+    const column = columns[index];
+    const value = parts[index];
+    if (column === undefined || value === undefined)
+      continue;
+    values[column] = value;
+  }
+  return values;
+}
+function quotedColumn(message) {
+  const marker = 'column "';
+  const start = message.indexOf(marker);
+  if (start === -1)
+    return;
+  const from = start + marker.length;
+  const end = message.indexOf('"', from);
+  if (end === -1)
+    return;
+  return message.slice(from, end);
+}
+function splitList(inner) {
+  const parts = inner.split(",");
+  const names = [];
+  for (const part of parts) {
+    const name = unquote(part.trim());
+    if (name.length > 0)
+      names.push(name);
+  }
+  return names;
+}
+function unquote(name) {
+  if (name.startsWith('"') && name.endsWith('"') && name.length >= 2) {
+    return name.slice(1, -1);
+  }
+  return name;
+}
+function summaryOf(kind, error, columns, fieldReason) {
+  const label = labelOf(kind);
+  if (kind === "driver")
+    return stripRowValues(error.message);
+  const where = place(error.table, columns);
+  if (where === undefined)
+    return label;
+  if (fieldReason === kind)
+    return `${label} on ${where}`;
+  return `${label} on ${where} (${fieldReason})`;
+}
+function place(table, columns) {
+  if (table === undefined && columns.length === 0)
+    return;
+  if (table === undefined)
+    return columns.join(", ");
+  if (columns.length === 0)
+    return table;
+  if (columns.length === 1)
+    return `${table}.${columns[0] ?? ""}`;
+  return `${table} (${columns.join(", ")})`;
+}
+function labelOf(kind) {
+  switch (kind) {
+    case "unique":
+      return "Unique violation";
+    case "not_null":
+      return "Not-null violation";
+    case "check":
+      return "Check violation";
+    case "foreign_key":
+      return "Foreign key violation";
+    case "exclusion":
+      return "Exclusion violation";
+    case "conflict":
+      return "Conflict";
+    case "invalid":
+      return "Invalid value";
+    case "serialization":
+      return "Serialization failure";
+    case "deadlock":
+      return "Deadlock";
+    case "lock_timeout":
+      return "Lock timeout";
+    case "timeout":
+      return "The call timed out";
+    case "cancelled":
+      return "The call was cancelled";
+    case "unavailable":
+      return "The database is unavailable";
+    case "outcome_unknown":
+      return "The commit outcome is unknown";
+    case "read_only":
+      return "The database is read-only";
+    case "schema_drift":
+      return "The database schema does not match this build";
+    case "not_found":
+      return "No row was found";
+    case "not_unique":
+      return "More than one row was found";
+    case "forbidden":
+      return "The operation is forbidden";
+    case "driver":
+      return "Driver error";
+  }
+}
+export {
+  mapPostgresError
+};

package/dist/tooling/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tooling/cli.js

@@ -0,0 +1,193 @@
+import"../shared/y9m15dfv.js";
+import {
+  formatPlan,
+  buildProject,
+  generateProject,
+  planProject,
+  checkProject
+} from "../shared/05w44d8g.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/kprcwaha.js");
+    stdout(await devProject(cwd));
+    return;
+  }
+  if (command === "push") {
+    const { pushProject } = await import("../shared/m3ypagh5.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/m3ypagh5.js");
+      stdout(await applyProject(cwd, invoke(parsed)));
+      return;
+    }
+    if (sub === "status") {
+      const { statusProject } = await import("../shared/523ft3e8.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[];