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

package/src/commands/migrate-check.ts

@@ -0,0 +1,257 @@
+/**
+ * `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` 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;
+  /**
+   * 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 }> {
+  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 }>;
+  };
+  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);
+  const legacyByHash = new Map(legacyChain.map((e) => [e.hash, e.tag]));
+
+  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,
+    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 (r.legacy.length > 0 && r.legacy.length < r.legacyChainLength) {
+    lines.push(
+      `✗ This database ran ${r.legacy.length} of the ${r.legacyChainLength} ` +
+        `pre-1.0 migrations. Finish that chain with @intelligo-dev/core ` +
+        `1.0.0-beta.7 (\`intelligo migrate\`) before upgrading.`
+    );
+  }
+
+  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;
+}
+
+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,
+    adoptable: r.adoptable,
+  });
+}

package/src/commands/migrate.ts

@@ -0,0 +1,234 @@
+/**
+ * `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,
+  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:
+        `This database ran ${check.legacy.length} of the ` +
+        `${check.legacyChainLength} pre-1.0 migrations. Finish that chain ` +
+        `with @intelligo-dev/core 1.0.0-beta.7 (\`intelligo migrate\`) ` +
+        `before upgrading.`,
+    };
+  }
+
+  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/upgrade-check.ts

@@ -0,0 +1,157 @@
+/**
+ * `intelligo upgrade --check`
+ *
+ * Reports what a template upgrade would do, and does nothing. Upgrades
+ * never overwrite consumer source, so the interesting output is not
+ * "these templates changed" but "these changed AND you have edited
+ * them" — the set where the consumer has to make a decision.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import { readCatalogue, substitute } from "./add.js";
+import { hashContents, readManifest, type Manifest } from "../manifest.js";
+
+export type UpgradeItem = {
+  feature: string;
+  path: string;
+  /**
+   * - `current`    — generated file matches the current template
+   * - `outdated`   — template changed; the local copy is untouched, so
+   *                  re-generating is safe
+   * - `conflict`   — template changed AND the consumer edited the file
+   * - `customized` — consumer edited it; template unchanged
+   * - `deleted`    — consumer removed it
+   * - `new`        — the template has a file this app was never given
+   */
+  state: "current" | "outdated" | "conflict" | "customized" | "deleted" | "new";
+};
+
+export type UpgradeReport = {
+  installedVersion: Record<string, string>;
+  templateVersion: Record<string, string>;
+  items: UpgradeItem[];
+};
+
+export type UpgradeCheckOptions = {
+  appRoot: string;
+  templatesDir: string;
+};
+
+export function upgradeCheck(options: UpgradeCheckOptions): UpgradeReport {
+  const manifest: Manifest | null = readManifest(options.appRoot);
+  if (!manifest) {
+    return { installedVersion: {}, templateVersion: {}, items: [] };
+  }
+
+  const catalogue = readCatalogue(options.templatesDir);
+  const report: UpgradeReport = {
+    installedVersion: {},
+    templateVersion: {},
+    items: [],
+  };
+
+  for (const [feature, entry] of Object.entries(manifest.features)) {
+    const spec = catalogue[feature];
+    report.installedVersion[feature] = entry.templateVersion;
+    if (spec) report.templateVersion[feature] = spec.templateVersion;
+
+    const targetToTemplate = new Map(
+      (spec?.files ?? []).map((f) => [f.target, f.template])
+    );
+
+    for (const target of newFiles(spec, entry.files)) {
+      report.items.push({ feature, path: target, state: "new" });
+    }
+
+    for (const file of entry.files) {
+      const abs = path.join(options.appRoot, file.path);
+      if (!existsSync(abs)) {
+        report.items.push({ feature, path: file.path, state: "deleted" });
+        continue;
+      }
+
+      const localHash = hashContents(readFileSync(abs, "utf8"));
+      const customized = localHash !== file.hash;
+
+      // Compare against the template as it would be written for THIS
+      // app: the recorded hash is of substituted content, so the raw
+      // template never matches a file carrying a placeholder.
+      const templateRel = targetToTemplate.get(file.path);
+      let templateChanged = false;
+      if (templateRel) {
+        const templateHash = hashContents(
+          substitute(
+            readFileSync(path.join(options.templatesDir, templateRel), "utf8"),
+            entry.variables
+          )
+        );
+        templateChanged = templateHash !== file.hash;
+      }
+
+      report.items.push({
+        feature,
+        path: file.path,
+        state: templateChanged
+          ? customized
+            ? "conflict"
+            : "outdated"
+          : customized
+            ? "customized"
+            : "current",
+      });
+    }
+  }
+
+  return report;
+}
+
+/** The feature's files the manifest has no record of: added to the template since. */
+function newFiles(
+  spec: { files: { target: string }[] } | undefined,
+  recorded: { path: string }[]
+): string[] {
+  const known = new Set(recorded.map((file) => file.path));
+  return (spec?.files ?? [])
+    .map((file) => file.target)
+    .filter((target) => !known.has(target));
+}
+
+export function formatUpgradeReport(r: UpgradeReport): string {
+  if (r.items.length === 0) {
+    return "No generated files recorded — nothing to upgrade.";
+  }
+
+  const label: Record<UpgradeItem["state"], string> = {
+    current: "✓ up to date",
+    outdated: "↑ template changed — safe to re-run `intelligo add`",
+    conflict: "! template changed AND you edited it — review the diff",
+    customized: "= yours (template unchanged)",
+    deleted: "✗ removed by you",
+    new: "+ new in the template — `intelligo add` writes it",
+  };
+
+  const lines: string[] = [];
+  for (const [feature, installed] of Object.entries(r.installedVersion)) {
+    const latest = r.templateVersion[feature];
+    lines.push(
+      latest && latest !== installed
+        ? `${feature}: ${installed} → ${latest}`
+        : `${feature}: ${installed}`
+    );
+    for (const item of r.items.filter((i) => i.feature === feature)) {
+      lines.push(`  ${label[item.state]}  ${item.path}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Non-zero only on conflicts. An outdated-but-untouched file is not a
+ * problem to fail a build over; a file that changed on both sides is a
+ * decision someone has to make.
+ */
+export function upgradeCheckExitCode(r: UpgradeReport): number {
+  return r.items.some((i) => i.state === "conflict") ? 1 : 0;
+}

package/src/env-files.ts

@@ -0,0 +1,31 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parseEnv } from "node:util";
+
+/**
+ * The env files a Next.js app reads, in the order it reads them: an
+ * earlier file wins, and a variable already set in the shell wins over
+ * every file.
+ *
+ * `migrate` and `doctor` run outside Next, so without this a fresh app
+ * whose `DATABASE_URL` lives in `.env.local` — exactly what the
+ * quickstart says to do — would fail with "DATABASE_URL is required".
+ */
+export const ENV_FILES = [".env.local", ".env"] as const;
+
+export function loadAppEnv(
+  root: string,
+  env: NodeJS.ProcessEnv = process.env
+): string[] {
+  const loaded: string[] = [];
+  for (const name of ENV_FILES) {
+    const file = path.join(root, name);
+    if (!existsSync(file)) continue;
+    const values = parseEnv(readFileSync(file, "utf8"));
+    for (const [key, value] of Object.entries(values)) {
+      if (env[key] === undefined) env[key] = value;
+    }
+    loaded.push(name);
+  }
+  return loaded;
+}