@intelligo-dev/cli 1.0.0-beta.1 → 1.0.0-beta.14

package/src/commands/migrate-check.ts

@@ -0,0 +1,298 @@
+/**
+ * `intelligo migrate --check`
+ *
+ * Answers "would deploying this code against that database work?"
+ * without changing anything. Two failure modes matter and neither is
+ * visible from the code alone:
+ *
+ *   - migrations the database has not applied yet (deploying now runs
+ *     code against an older schema);
+ *   - migrations the database has applied that this checkout does not
+ *     contain (the database is ahead — usually a rollback in progress).
+ *
+ * Drizzle records applied migrations in `drizzle.__drizzle_migrations`
+ * by content hash. A database provisioned with `db:push` has the
+ * schema but no rows there at all, which this reports distinctly:
+ * "unmanaged" is a different problem from "behind", and baselining is
+ * the fix (see the migrations README).
+ *
+ * The framework's chain is one baseline. A database that ran the pre-1.0
+ * chain holds its hashes, which `legacy-chain.json` (next to the
+ * journal) lists: they are reported as `legacy`, not as unknown, and a
+ * database holding all of them is `adoptable` — its schema is the
+ * baseline's, so `migrate` records the baseline without running it.
+ *
+ * The exit code is 1 whenever anything is pending or the database is
+ * ahead, which a brand-new database and a stale one share. A deploy
+ * gate that must tell them apart reads `migrate --check --json`: one
+ * JSON object on stdout, same exit code, whose `state` is
+ *
+ *   - `up_to_date` — every migration is applied;
+ *   - `pending`    — a migrated database is behind this checkout;
+ *   - `fresh`      — no migration records and none of the framework's
+ *                    tables: an empty database, `migrate` applies the chain;
+ *   - `unmanaged`  — the tables exist with no records (`db:push`);
+ *   - `ahead`      — applied migrations this checkout does not contain;
+ *   - `legacy`     — the pre-1.0 chain; `adoptable` says whether
+ *                    `migrate` can take it over.
+ *
+ * Beside `state` it carries `exitCode`, `chain`, `applied`, `pending`,
+ * `unknown`, `legacy`, `legacyMissing` and `adoptable`.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import { readMigrationChain } from "../migrations.js";
+
+export type MigrateCheckResult = {
+  /** Journal tags this checkout knows about, in order. */
+  chain: string[];
+  /** Applied according to the database. */
+  applied: string[];
+  /** In the chain but not applied — a deploy would run against an older schema. */
+  pending: string[];
+  /** Applied but absent from this checkout — the database is ahead. */
+  unknown: string[];
+  /**
+   * True when the migrations table is empty or missing while the
+   * schema exists — a push-provisioned database that needs baselining.
+   */
+  unmanaged: boolean;
+  /** Pre-1.0 migrations the database ran, by tag. */
+  legacy: string[];
+  /** Length of the pre-1.0 chain (0 when this checkout ships none). */
+  legacyChainLength: number;
+  /**
+   * Pre-1.0 migrations the database has not run, by tag, in chain
+   * order — empty unless it ran some of them.
+   */
+  legacyMissing: string[];
+  /**
+   * The database ran the whole pre-1.0 chain and not the baseline:
+   * `migrate` records the baseline as applied without running it.
+   */
+  adoptable: boolean;
+};
+
+/** The pre-1.0 chain's tags and hashes, if this checkout ships them. */
+export function readLegacyChain(
+  migrationsDir: string
+): Array<{ tag: string; hash: string; alternates?: string[] }> {
+  const file = path.join(migrationsDir, "legacy-chain.json");
+  if (!existsSync(file)) return [];
+  const parsed = JSON.parse(readFileSync(file, "utf8")) as {
+    entries?: Array<{ tag: string; hash: string; alternates?: string[] }>;
+  };
+  return parsed.entries ?? [];
+}
+
+/** Drizzle hashes the file contents with sha256. */
+export function hashMigration(sql: string): string {
+  return createHash("sha256").update(sql).digest("hex");
+}
+
+type QueryFn = (sql: string) => Promise<Array<{ hash: string }>>;
+
+export async function migrateCheck(
+  migrationsDir: string,
+  query: QueryFn
+): Promise<MigrateCheckResult> {
+  const chain = readMigrationChain(migrationsDir);
+
+  const hashToTag = new Map<string, string>();
+  for (const tag of chain.journalTags) {
+    const file = path.join(migrationsDir, `${tag}.sql`);
+    try {
+      hashToTag.set(hashMigration(readFileSync(file, "utf8")), tag);
+    } catch {
+      // readMigrationChain already reports files the journal names but
+      // that are not on disk; nothing to hash here.
+    }
+  }
+
+  let rows: Array<{ hash: string }> = [];
+  let tableMissing = false;
+  try {
+    rows = await query(
+      `SELECT hash FROM drizzle.__drizzle_migrations ORDER BY created_at`
+    );
+  } catch {
+    tableMissing = true;
+  }
+
+  const legacyChain = readLegacyChain(migrationsDir);
+  // A migration can be recorded under more than one hash: npm's
+  // 1.0.0-beta.6 shipped different bytes for three of them.
+  const legacyByHash = new Map(
+    legacyChain.flatMap((e) =>
+      [e.hash, ...(e.alternates ?? [])].map((h) => [h, e.tag] as const)
+    )
+  );
+
+  const appliedHashes = new Set(rows.map((r) => r.hash));
+  const applied: string[] = [];
+  const unknown: string[] = [];
+  const legacy: string[] = [];
+  for (const hash of appliedHashes) {
+    const tag = hashToTag.get(hash);
+    const legacyTag = legacyByHash.get(hash);
+    if (tag) applied.push(tag);
+    else if (legacyTag) legacy.push(legacyTag);
+    else unknown.push(hash.slice(0, 12));
+  }
+
+  const appliedTags = new Set(applied);
+  const pending = chain.journalTags.filter((t) => !appliedTags.has(t));
+  const baseline = chain.journalTags[0];
+
+  return {
+    chain: chain.journalTags,
+    applied,
+    pending,
+    unknown,
+    unmanaged: tableMissing || appliedHashes.size === 0,
+    legacy,
+    legacyChainLength: legacyChain.length,
+    legacyMissing:
+      legacy.length > 0
+        ? legacyChain.map((e) => e.tag).filter((t) => !legacy.includes(t))
+        : [],
+    adoptable:
+      legacyChain.length > 0 &&
+      legacy.length === legacyChain.length &&
+      baseline !== undefined &&
+      !appliedTags.has(baseline),
+  };
+}
+
+/**
+ * `schemaExists` is whether the framework's tables are in the database
+ * (`SCHEMA_PROBE_SQL`). When the caller did not probe, a database with
+ * no records gets the cautious `db:push` wording.
+ */
+export function formatMigrateCheck(
+  r: MigrateCheckResult,
+  schemaExists?: boolean
+): string {
+  const lines: string[] = [];
+
+  if (r.unmanaged && schemaExists === false) {
+    lines.push(
+      `! This database is empty: no migration records and none of the ` +
+        `framework's tables. \`intelligo migrate\` applies all ` +
+        `${r.chain.length} migration(s).`
+    );
+  } else if (r.unmanaged) {
+    lines.push(
+      `! This database has no migration records. If it was provisioned with ` +
+        `db:push, baseline it before running migrate — otherwise migrate will ` +
+        `try to apply all ${r.chain.length} migrations. See README.md in ` +
+        `@intelligo-dev/core's src/db/migrations.`
+    );
+  }
+
+  if (r.adoptable) {
+    lines.push(
+      `! This database ran the framework's pre-1.0 migration chain. migrate ` +
+        `records ${r.chain[0]} as applied without running it (the schema is ` +
+        `already there), then applies what follows. Tables the old chain ` +
+        `created that the framework no longer owns are left untouched.`
+    );
+  } else if (isPartialLegacy(r)) {
+    lines.push(`✗ ${partialLegacyMessage(r)}`);
+  }
+
+  if (r.unknown.length > 0) {
+    lines.push(
+      `✗ Database is ahead: ${r.unknown.length} applied migration(s) are not in ` +
+        `this checkout (${r.unknown.join(", ")})`
+    );
+  }
+
+  if (r.pending.length > 0) {
+    lines.push(
+      `✗ ${r.pending.length} migration(s) pending: ${r.pending.join(", ")}`
+    );
+  } else if (!r.unmanaged) {
+    lines.push(`✓ Up to date (${r.applied.length}/${r.chain.length} applied)`);
+  }
+
+  return lines.join("\n");
+}
+
+/** Non-zero when deploying this code would run against a stale schema. */
+export function migrateCheckExitCode(r: MigrateCheckResult): number {
+  return r.pending.length > 0 || r.unknown.length > 0 ? 1 : 0;
+}
+
+/** A partial pre-1.0 chain: neither adoptable nor migratable from here. */
+export function isPartialLegacy(r: MigrateCheckResult): boolean {
+  return r.legacy.length > 0 && r.legacy.length < r.legacyChainLength;
+}
+
+/**
+ * The last pre-1.0 migration any published `@intelligo-dev/core`
+ * carries: 1.0.0-beta.6 shipped the chain through it, and the versions
+ * that carried the rest were never published.
+ */
+export const LAST_PUBLISHED_LEGACY_TAG = "0042_sessions_active_organization_id";
+
+/**
+ * Why a partial pre-1.0 chain is refused and where the way forward is
+ * written down. No published version finishes the chain, so the
+ * message names what is missing and points at the README's options
+ * instead of at a version to install.
+ */
+export function partialLegacyMessage(r: MigrateCheckResult): string {
+  const shown = r.legacyMissing.slice(0, 6);
+  const more = r.legacyMissing.length - shown.length;
+  return (
+    `This database ran ${r.legacy.length} of the ${r.legacyChainLength} ` +
+    `pre-1.0 migrations; it has not run ${shown.join(", ")}` +
+    `${more > 0 ? ` and ${more} more` : ""}. No published ` +
+    `@intelligo-dev/core finishes that chain: 1.0.0-beta.6 ships it ` +
+    `through ${LAST_PUBLISHED_LEGACY_TAG}, and the versions that carried ` +
+    `the rest never reached npm. Apply the missing migrations' SQL from ` +
+    `your own copy of it, or bring the schema to the baseline and record ` +
+    `it as applied — see "Databases from before 1.0" in README.md in ` +
+    `@intelligo-dev/core's src/db/migrations.`
+  );
+}
+
+export type MigrateState =
+  "up_to_date" | "pending" | "fresh" | "ahead" | "unmanaged" | "legacy";
+
+/**
+ * One word for what the check found, most urgent first: a database that
+ * is ahead or on the pre-1.0 chain is that before it is anything else.
+ * `schemaExists` separates an empty database from a push-provisioned one.
+ */
+export function migrateState(
+  r: MigrateCheckResult,
+  schemaExists: boolean
+): MigrateState {
+  if (r.unknown.length > 0) return "ahead";
+  if (r.legacy.length > 0) return "legacy";
+  if (r.unmanaged) return schemaExists ? "unmanaged" : "fresh";
+  return r.pending.length > 0 ? "pending" : "up_to_date";
+}
+
+/** The `--json` report: `state` first, then the detail behind it. */
+export function formatMigrateCheckJson(
+  r: MigrateCheckResult,
+  schemaExists: boolean
+): string {
+  return JSON.stringify({
+    state: migrateState(r, schemaExists),
+    exitCode: migrateCheckExitCode(r),
+    chain: r.chain,
+    applied: r.applied,
+    pending: r.pending,
+    unknown: r.unknown,
+    legacy: r.legacy,
+    legacyMissing: r.legacyMissing,
+    adoptable: r.adoptable,
+  });
+}

package/src/commands/migrate.ts

@@ -0,0 +1,228 @@
+/**
+ * `intelligo migrate` — apply the framework's migration chain.
+ *
+ * A consumer application has two migration chains in one database:
+ * the framework's, shipped inside `@intelligo-dev/core` (its `.sql`
+ * files and journal are in the package's `files`), and its own, which
+ * drizzle-kit generates from the tables the application owns. They
+ * must not share a journal — drizzle-kit applies by timestamp, so a
+ * framework migration published after the consumer generated one of
+ * theirs would be silently skipped — and a consumer cannot write into
+ * `node_modules` anyway. So the framework chain is applied by this
+ * command, into drizzle's default `drizzle.__drizzle_migrations`
+ * table, and the consumer's chain by `drizzle-kit migrate` from their
+ * own `drizzle.config.ts`, into a table of its own (the scaffold sets
+ * `migrations.table` to `__app_migrations`).
+ *
+ * Migrations are selected by content hash (what `migrate --check`
+ * compares), not by drizzle's journal-timestamp rule, and are recorded
+ * in the same table drizzle's migrator writes — see
+ * `readPendingMigrations` for why.
+ *
+ * The one thing this refuses to do is guess. A database with the
+ * framework's tables but no migration records was provisioned with
+ * `db:push`; applying the whole chain to it would fail part-way (not
+ * every migration is `IF NOT EXISTS`-guarded) and leave the records
+ * half-written. Baselining is the fix, and it is deliberately a manual
+ * step — see `packages/core/src/db/migrations/README.md`.
+ */
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import {
+  hashMigration,
+  isPartialLegacy,
+  migrateCheck,
+  partialLegacyMessage,
+  type MigrateCheckResult,
+} from "./migrate-check.js";
+
+export type ApplyDecision =
+  | {
+      action: "apply";
+      pending: string[];
+      /** Recorded as applied without running: the schema is already there. */
+      adopted: string[];
+    }
+  | { action: "noop" }
+  | { action: "refuse"; reason: string };
+
+/**
+ * What to do with a database, given the check result and whether the
+ * framework's schema already exists in it. Pure, so the three states
+ * that matter — empty, push-provisioned, behind — are unit-testable
+ * without a database.
+ */
+export function decideApply(
+  check: MigrateCheckResult,
+  schemaExists: boolean
+): ApplyDecision {
+  if (check.unknown.length > 0) {
+    return {
+      action: "refuse",
+      reason:
+        `Database is ahead: ${check.unknown.length} applied migration(s) are ` +
+        `not in this checkout (${check.unknown.join(", ")}). Upgrade ` +
+        `@intelligo-dev/core before migrating, or restore the database.`,
+    };
+  }
+
+  if (isPartialLegacy(check)) {
+    return { action: "refuse", reason: partialLegacyMessage(check) };
+  }
+
+  if (check.adoptable) {
+    const [baseline, ...rest] = check.pending;
+    return {
+      action: "apply",
+      adopted: baseline ? [baseline] : [],
+      pending: rest,
+    };
+  }
+
+  if (check.unmanaged && schemaExists) {
+    return {
+      action: "refuse",
+      reason:
+        `This database has the framework's tables but no migration records — ` +
+        `it was provisioned with db:push. Baseline it before running migrate, ` +
+        `otherwise all ${check.chain.length} migrations would be applied to ` +
+        `tables that already exist. See README.md in @intelligo-dev/core's ` +
+        `src/db/migrations.`,
+    };
+  }
+
+  if (check.pending.length === 0) return { action: "noop" };
+
+  return { action: "apply", pending: check.pending, adopted: [] };
+}
+
+type QueryFn = (sql: string) => Promise<Array<Record<string, unknown>>>;
+
+/**
+ * One migration ready to run: its statements and the journal entry it
+ * will be recorded under. `createdAt` is the journal's `when`, which is
+ * what drizzle-kit writes to `created_at` too, so records made here and
+ * records made by drizzle's own migrator are indistinguishable.
+ */
+export type PendingMigration = {
+  tag: string;
+  hash: string;
+  createdAt: number;
+  statements: string[];
+};
+
+/**
+ * Read the pending migrations off disk, in journal order.
+ *
+ * The chain is applied by content hash — the same key `migrate --check`
+ * compares — and not by drizzle's rule of "every entry whose journal
+ * timestamp is greater than the last applied row's". That rule depends
+ * on `when` values increasing monotonically, which a hand-numbered
+ * journal does not guarantee: an entry numbered below an applied one is
+ * skipped silently while the check reports it pending. Selecting by hash makes "pending" mean exactly what the check says.
+ */
+export function readPendingMigrations(
+  migrationsDir: string,
+  pendingTags: string[]
+): PendingMigration[] {
+  const journal = JSON.parse(
+    readFileSync(path.join(migrationsDir, "meta", "_journal.json"), "utf8")
+  ) as {
+    entries?: Array<{ tag: string; when: number; breakpoints?: boolean }>;
+  };
+  const byTag = new Map((journal.entries ?? []).map((e) => [e.tag, e]));
+
+  return pendingTags.map((tag) => {
+    const entry = byTag.get(tag);
+    if (!entry) throw new Error(`${tag} is pending but not in the journal`);
+    const sql = readFileSync(path.join(migrationsDir, `${tag}.sql`), "utf8");
+    const statements = (
+      entry.breakpoints === false
+        ? [sql]
+        : sql.split("--> statement-breakpoint")
+    )
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+    return { tag, hash: hashMigration(sql), createdAt: entry.when, statements };
+  });
+}
+
+/** The records table drizzle's migrator uses, created the way it creates it. */
+export const MIGRATIONS_TABLE_SQL = [
+  `CREATE SCHEMA IF NOT EXISTS "drizzle"`,
+  `CREATE TABLE IF NOT EXISTS "drizzle"."__drizzle_migrations" (id SERIAL PRIMARY KEY, hash text NOT NULL, created_at bigint)`,
+];
+
+export type ApplyMigrationsOptions = {
+  migrationsDir: string;
+  /** Runs a read-only query and returns its rows. */
+  query: QueryFn;
+  /**
+   * Applies the given migrations in order, all in one transaction,
+   * recording each in `drizzle.__drizzle_migrations` as it goes.
+   */
+  run: (pending: PendingMigration[]) => Promise<void>;
+};
+
+export type ApplyMigrationsResult = ApplyDecision & {
+  /** After the run, for the summary line and for `noop` detection. */
+  chainLength: number;
+};
+
+/**
+ * `users` is the first table the framework creates (auth), so its
+ * presence with no migration records is the push-provisioned signature.
+ */
+export const SCHEMA_PROBE_SQL = `SELECT to_regclass('public.users') AS rel`;
+
+export async function applyMigrations(
+  options: ApplyMigrationsOptions
+): Promise<ApplyMigrationsResult> {
+  const check = await migrateCheck(
+    options.migrationsDir,
+    async (sql) => (await options.query(sql)) as Array<{ hash: string }>
+  );
+
+  const probe = await options.query(SCHEMA_PROBE_SQL);
+  const schemaExists = probe.length > 0 && probe[0]!.rel != null;
+
+  const decision = decideApply(check, schemaExists);
+  if (decision.action === "apply") {
+    // An adopted migration is recorded with no statements: its schema is
+    // already in the database.
+    const adopted = readPendingMigrations(
+      options.migrationsDir,
+      decision.adopted
+    ).map((m) => ({ ...m, statements: [] }));
+    await options.run([
+      ...adopted,
+      ...readPendingMigrations(options.migrationsDir, decision.pending),
+    ]);
+  }
+
+  return { ...decision, chainLength: check.chain.length };
+}
+
+export function formatApplyResult(r: ApplyMigrationsResult): string {
+  switch (r.action) {
+    case "refuse":
+      return `✗ ${r.reason}`;
+    case "noop":
+      return `✓ Nothing to apply (${r.chainLength}/${r.chainLength} applied)`;
+    case "apply":
+      return [
+        ...r.adopted.map(
+          (tag) =>
+            `✓ Adopted ${tag}: this database ran the pre-1.0 chain, so its schema is already there`
+        ),
+        `✓ Applied ${r.pending.length} migration(s):`,
+        ...r.pending.map((tag) => `    ${tag}`),
+      ].join("\n");
+  }
+}
+
+export function applyExitCode(r: ApplyMigrationsResult): number {
+  return r.action === "refuse" ? 1 : 0;
+}

package/src/commands/sync-messages.ts

@@ -0,0 +1,114 @@
+/**
+ * Message files under `intelligo sync`: the registry's keys an app's
+ * copy lacks, the merge that keeps the app's values, and the other
+ * locales checked against the app's English copy.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+export type Json = Record<string, unknown>;
+
+const isObject = (v: unknown): v is Json =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** Dotted paths of every leaf in `registry` that `app` lacks. */
+export function missingMessageKeys(
+  registry: Json,
+  app: Json,
+  prefix = ""
+): string[] {
+  return Object.entries(registry).flatMap(([key, value]) => {
+    const at = prefix ? `${prefix}.${key}` : key;
+    if (!(key in app)) return [at];
+    const mine = app[key];
+    return isObject(value) && isObject(mine)
+      ? missingMessageKeys(value, mine, at)
+      : [];
+  });
+}
+
+/**
+ * The registry's messages with the app's copy laid over them: every key
+ * the registry has is present, every value the app set wins, and keys
+ * only the app has (its own nav entries, product copy) are kept.
+ */
+export function mergeMessages(registry: Json, app: Json): Json {
+  const out: Json = {};
+  for (const [key, value] of Object.entries(registry)) {
+    const mine = app[key];
+    out[key] =
+      key in app
+        ? isObject(value) && isObject(mine)
+          ? mergeMessages(value, mine)
+          : mine
+        : value;
+  }
+  for (const [key, value] of Object.entries(app)) {
+    if (!(key in out)) out[key] = value;
+  }
+  return out;
+}
+
+export const isMessages = (target: string) =>
+  target.startsWith("messages/") && target.endsWith(".json");
+
+/** The locale the registry ships messages in. */
+const SOURCE_LOCALE = "en";
+
+/**
+ * The app's locales, from `locales: [...]` in i18n/routing.ts — the
+ * source locale alone when there is no such file or list.
+ */
+export function appLocales(appRoot: string): string[] {
+  const file = path.join(appRoot, "i18n", "routing.ts");
+  if (!existsSync(file)) return [SOURCE_LOCALE];
+  const list = /\blocales\s*:\s*\[([^\]]*)\]/.exec(readFileSync(file, "utf8"));
+  const locales = [...(list?.[1] ?? "").matchAll(/["'`]([^"'`]+)["'`]/g)].map(
+    (m) => m[1]!
+  );
+  return locales.length > 0 ? locales : [SOURCE_LOCALE];
+}
+
+export type LocaleEntry = {
+  item: string;
+  path: string;
+  state: "current" | "locale-behind";
+  missingKeys?: string[];
+};
+
+/**
+ * Every other locale's copy of the namespaces the registry ships,
+ * against the app's English file on disk — the merged copy, product
+ * keys included, which is what the other locales translate. A missing
+ * file lacks every key.
+ */
+export function localeEntries(
+  appRoot: string,
+  files: readonly { item: string; target: string }[]
+): LocaleEntry[] {
+  const others = appLocales(appRoot).filter((l) => l !== SOURCE_LOCALE);
+  if (others.length === 0) return [];
+  const prefix = `messages/${SOURCE_LOCALE}/`;
+  const entries: LocaleEntry[] = [];
+  for (const { item, target } of files) {
+    if (!target.startsWith(prefix) || !target.endsWith(".json")) continue;
+    const english = path.join(appRoot, target);
+    if (!existsSync(english)) continue;
+    const source = JSON.parse(readFileSync(english, "utf8")) as Json;
+    for (const locale of others) {
+      const rel = `messages/${locale}/${target.slice(prefix.length)}`;
+      const abs = path.join(appRoot, rel);
+      const missingKeys = missingMessageKeys(
+        source,
+        existsSync(abs) ? (JSON.parse(readFileSync(abs, "utf8")) as Json) : {}
+      );
+      entries.push(
+        missingKeys.length > 0
+          ? { item, path: rel, state: "locale-behind", missingKeys }
+          : { item, path: rel, state: "current" }
+      );
+    }
+  }
+  return entries;
+}