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

package/src/commands/upgrade-check.ts

@@ -0,0 +1,160 @@
+/**
+ * `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,
+      ...(entry.handedOver ?? []).map((handed) => ({ path: handed })),
+    ])) {
+      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;
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+/**
+ * @intelligo-dev/cli — operational commands for an Intelligo application.
+ *
+ * Exported as functions as well as a binary so CI can call the checks
+ * directly (see the migration-chain gate) without shelling out.
+ */
+
+export {
+  runChecks,
+  formatResults,
+  exitCodeFor,
+  type CheckResult,
+  type DoctorOptions,
+} from "./commands/doctor.js";
+
+export {
+  migrateCheck,
+  hashMigration,
+  formatMigrateCheck,
+  migrateCheckExitCode,
+  type MigrateCheckResult,
+} from "./commands/migrate-check.js";
+
+export {
+  readMigrationChain,
+  inspectMigrationChain,
+  type MigrationChain,
+  type ChainProblem,
+} from "./migrations.js";
+
+/**
+ * Where the framework's chain lives. Exported because a consumer's own
+ * operational scripts — baselining a push-provisioned database, a
+ * one-off audit — otherwise hardcode
+ * `node_modules/@intelligo-dev/core/src/db/migrations`, which is right
+ * in an application and wrong in the framework repository, and which
+ * silently stops being either if the package layout ever changes.
+ */
+export { resolveMigrationsDir, MIGRATION_LOCATIONS } from "./migrations-dir.js";

package/src/manifest.ts

@@ -0,0 +1,147 @@
+/**
+ * Generated-source manifest.
+ *
+ * Intelligo generates starting source into the consumer's repository
+ * and then stops owning it. That promise needs a mechanism,
+ * because "never overwrite a customized file" requires knowing which
+ * files were generated, from which template version, and whether the
+ * consumer has since edited them.
+ *
+ * The manifest records a content hash per generated file at the moment
+ * it was written. A file whose hash still matches was not touched and
+ * can be re-generated safely; one whose hash differs is the consumer's
+ * code now, and an upgrade may only show them a diff.
+ *
+ * Deliberately not a lockfile of package versions: it tracks template
+ * provenance, not dependencies.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+export const MANIFEST_FILE = "intelligo.manifest.json";
+
+export type GeneratedFile = {
+  /** Path relative to the consumer application root. */
+  path: string;
+  /** sha256 of the contents Intelligo wrote. */
+  hash: string;
+};
+
+export type FeatureEntry = {
+  templateVersion: string;
+  files: GeneratedFile[];
+  /**
+   * Placeholder substitutions the files were generated with
+   * (`__APP_NAME__` → "acme"). Recorded so an upgrade check can hash the
+   * template *as it would be written for this app*; the raw template
+   * would make every substituted file look permanently outdated.
+   */
+  variables?: Record<string, string>;
+  /**
+   * Files this feature wrote that a registry install has since replaced
+   * (the scaffold's globals.css once the design-system base lands):
+   * `intelligo sync` owns them now, so `upgrade --check` neither
+   * compares them nor offers them as new, and `add` does not write them
+   * back.
+   */
+  handedOver?: string[];
+};
+
+/**
+ * Registry items `intelligo sync` installed: which items the app keeps
+ * in sync, the framework version they came from, and — per installed
+ * file that is not a seam or a message file — the hash of the file as
+ * written (after shadcn's normalisation, see `asInstalled`). A file
+ * whose hash still matches was not edited since, so a newer registry
+ * may replace it; one that differs was edited by hand.
+ */
+export type RegistryEntry = {
+  version: string;
+  items: string[];
+  files: Record<string, string>;
+};
+
+export type Manifest = {
+  schemaVersion: 1;
+  frameworkVersion: string;
+  features: Record<string, FeatureEntry>;
+  registry?: RegistryEntry;
+};
+
+export function hashContents(contents: string): string {
+  return createHash("sha256").update(contents).digest("hex");
+}
+
+export function emptyManifest(frameworkVersion: string): Manifest {
+  return { schemaVersion: 1, frameworkVersion, features: {} };
+}
+
+export function readManifest(appRoot: string): Manifest | null {
+  const file = path.join(appRoot, MANIFEST_FILE);
+  if (!existsSync(file)) return null;
+  return JSON.parse(readFileSync(file, "utf8")) as Manifest;
+}
+
+export function writeManifest(appRoot: string, manifest: Manifest): void {
+  writeFileSync(
+    path.join(appRoot, MANIFEST_FILE),
+    `${JSON.stringify(manifest, null, 2)}\n`
+  );
+}
+
+/**
+ * Record a feature's generated files, replacing any previous entry for
+ * the same feature — re-generating is how a consumer accepts a new
+ * template version, and the recorded hashes must then describe what is
+ * actually on disk.
+ */
+export function recordFeature(
+  manifest: Manifest,
+  feature: string,
+  templateVersion: string,
+  files: GeneratedFile[],
+  variables?: Record<string, string>
+): Manifest {
+  const handedOver = manifest.features[feature]?.handedOver;
+  return {
+    ...manifest,
+    features: {
+      ...manifest.features,
+      [feature]: {
+        templateVersion,
+        files,
+        ...(variables ? { variables } : {}),
+        ...(handedOver?.length ? { handedOver } : {}),
+      },
+    },
+  };
+}
+
+/**
+ * Move `paths` out of a feature's generated files into its `handedOver`
+ * list. A no-op for a feature the manifest does not record.
+ */
+export function handOver(
+  manifest: Manifest,
+  feature: string,
+  paths: readonly string[]
+): Manifest {
+  const entry = manifest.features[feature];
+  if (!entry || paths.length === 0) return manifest;
+  const moved = new Set(paths);
+  return {
+    ...manifest,
+    features: {
+      ...manifest.features,
+      [feature]: {
+        ...entry,
+        files: entry.files.filter((f) => !moved.has(f.path)),
+        handedOver: [
+          ...new Set([...(entry.handedOver ?? []), ...paths]),
+        ].sort(),
+      },
+    },
+  };
+}

package/src/migrations-dir.ts

@@ -0,0 +1,25 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * Where the framework's migration chain lives, relative to the
+ * directory the CLI is run from.
+ *
+ * Two layouts are real: the framework repository itself, where core is
+ * a workspace package, and a consumer application, where core arrives
+ * from the registry and ships its migrations inside the package (they
+ * are in `files`, next to `dist`). The first match wins, so a checkout
+ * that has both — the framework repo — reads its own source.
+ */
+export const MIGRATION_LOCATIONS = [
+  "packages/core/src/db/migrations",
+  "node_modules/@intelligo-dev/core/src/db/migrations",
+] as const;
+
+export function resolveMigrationsDir(root: string): string | null {
+  for (const relative of MIGRATION_LOCATIONS) {
+    const dir = path.join(root, relative);
+    if (existsSync(dir)) return dir;
+  }
+  return null;
+}

package/src/migrations.ts

@@ -0,0 +1,133 @@
+/**
+ * Migration-chain inspection.
+ *
+ * Drizzle keeps two sources of truth: the `.sql` files on disk and
+ * `meta/_journal.json`, which is what `drizzle-kit migrate` actually
+ * reads. Nothing keeps them in step: a file missing from the journal is
+ * silently skipped by `migrate`, while `drizzle-kit push` from
+ * `schema.ts` hides the gap.
+ *
+ * The drift is invisible until someone provisions a database from the
+ * migrations, at which point it is a production incident rather than a
+ * CI failure. These helpers make it a check.
+ */
+
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+export type JournalEntry = {
+  idx: number;
+  version: string;
+  when: number;
+  tag: string;
+  breakpoints: boolean;
+};
+
+export type MigrationChain = {
+  dir: string;
+  /** `.sql` files present on disk, sorted by their numeric prefix. */
+  files: string[];
+  /** Tags drizzle-kit will actually apply, in order. */
+  journalTags: string[];
+  /** On disk but absent from the journal — `migrate` skips these. */
+  unregistered: string[];
+  /** In the journal but missing from disk — `migrate` fails on these. */
+  missing: string[];
+};
+
+function tagOf(file: string): string {
+  return file.replace(/\.sql$/, "");
+}
+
+export function readMigrationChain(dir: string): MigrationChain {
+  const files = readdirSync(dir)
+    .filter((f) => f.endsWith(".sql"))
+    .sort();
+
+  let journalTags: string[] = [];
+  try {
+    const journal = JSON.parse(
+      readFileSync(path.join(dir, "meta", "_journal.json"), "utf8")
+    ) as { entries?: JournalEntry[] };
+    journalTags = (journal.entries ?? []).map((e) => e.tag);
+  } catch {
+    // No journal at all is itself the maximal drift: every file is
+    // unregistered, which the caller reports.
+    journalTags = [];
+  }
+
+  const registered = new Set(journalTags);
+  const onDisk = new Set(files.map(tagOf));
+
+  return {
+    dir,
+    files,
+    journalTags,
+    unregistered: files.map(tagOf).filter((t) => !registered.has(t)),
+    missing: journalTags.filter((t) => !onDisk.has(t)),
+  };
+}
+
+export type ChainProblem = { level: "error" | "warn"; message: string };
+
+export function inspectMigrationChain(chain: MigrationChain): ChainProblem[] {
+  const problems: ChainProblem[] = [];
+
+  if (chain.files.length === 0) {
+    problems.push({ level: "error", message: `No .sql files in ${chain.dir}` });
+    return problems;
+  }
+
+  if (chain.missing.length > 0) {
+    problems.push({
+      level: "error",
+      message:
+        `Journal references ${chain.missing.length} migration(s) that are not on disk ` +
+        `(drizzle-kit migrate will fail): ${chain.missing.join(", ")}`,
+    });
+  }
+
+  if (chain.unregistered.length > 0) {
+    problems.push({
+      level: "error",
+      message:
+        `${chain.unregistered.length} of ${chain.files.length} migration files are not in ` +
+        `meta/_journal.json, so drizzle-kit migrate skips them: ` +
+        `${chain.unregistered.slice(0, 5).join(", ")}` +
+        (chain.unregistered.length > 5 ? ", …" : ""),
+    });
+  }
+
+  // Numbering problems. Two files sharing a prefix is worse than a
+  // gap: `migrate` orders by tag, so which one runs first depends on
+  // the rest of the filename rather than on intent.
+  const numbers = chain.files
+    .map((f) => Number.parseInt(f.slice(0, 4), 10))
+    .filter((n) => Number.isFinite(n));
+
+  const seen = new Map<number, number>();
+  for (const n of numbers) seen.set(n, (seen.get(n) ?? 0) + 1);
+  const duplicates = [...seen.entries()]
+    .filter(([, count]) => count > 1)
+    .map(([n]) => String(n).padStart(4, "0"));
+  if (duplicates.length > 0) {
+    problems.push({
+      level: "warn",
+      message: `Duplicate migration prefixes (apply order is filename-dependent): ${duplicates.join(", ")}`,
+    });
+  }
+
+  const unique = [...new Set(numbers)].sort((a, b) => a - b);
+  for (let i = 1; i < unique.length; i++) {
+    const prev = unique[i - 1]!;
+    const cur = unique[i]!;
+    if (cur > prev + 1) {
+      problems.push({
+        level: "warn",
+        message: `Gap in migration numbering: ${String(prev).padStart(4, "0")} → ${String(cur).padStart(4, "0")}`,
+      });
+    }
+  }
+
+  return problems;
+}

package/src/model-catalogue.ts

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * Where the shipped model catalogue (`DEFAULT_MODELS`) can be read from,
+ * relative to the directory the CLI is run from: the framework
+ * repository's own source, then the installed package's source, then
+ * its build. The CLI reads the file rather than importing the package,
+ * so `doctor` works in an app whose dependencies do not even load.
+ */
+export const MODEL_CATALOGUE_LOCATIONS = [
+  "packages/executions/src/pricing.ts",
+  "node_modules/@intelligo-dev/executions/src/pricing.ts",
+  "node_modules/@intelligo-dev/executions/dist/pricing.js",
+] as const;
+
+/**
+ * The ids `DEFAULT_MODELS` prices, or null when no catalogue file is
+ * found or the declaration is not in it.
+ */
+export function readCatalogueModelIds(root: string): Set<string> | null {
+  for (const relative of MODEL_CATALOGUE_LOCATIONS) {
+    const file = path.join(root, relative);
+    if (!existsSync(file)) continue;
+    const text = readFileSync(file, "utf8");
+    const start = text.indexOf("export const DEFAULT_MODELS");
+    if (start === -1) continue;
+    return new Set(
+      [
+        ...text.slice(start).matchAll(/\bid:\s*"([a-z0-9-]+\/[a-z0-9._-]+)"/g),
+      ].map((m) => m[1]!)
+    );
+  }
+  return null;
+}