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

package/package.json

@@ -1,15 +1,28 @@
 {
   "name": "@intelligo-dev/cli",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.14",
+  "description": "The Intelligo CLI: scaffold an AI SaaS app, generate owned source, and check its migrations and upgrades.",
+  "keywords": [
+    "intelligo",
+    "ai-saas",
+    "saas",
+    "typescript",
+    "cli",
+    "scaffold",
+    "shadcn",
+    "migrations",
+    "nextjs"
+  ],
   "license": "Apache-2.0",
+  "author": "Turtuvshin Byambaa <toroo.byamba@gmail.com>",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/intelligo-mn/framework.git",
+    "url": "git+https://github.com/intelligo-dev/intelligo.git",
     "directory": "packages/cli"
   },
-  "homepage": "https://github.com/intelligo-mn/framework#readme",
+  "homepage": "https://intelligo.dev/docs/packages/cli",
   "bugs": {
-    "url": "https://github.com/intelligo-mn/framework/issues"
+    "url": "https://github.com/intelligo-dev/intelligo/issues"
   },
   "type": "module",
   "bin": {
@@ -22,23 +35,36 @@
     }
   },
   "dependencies": {
-    "pg": "^8.18.0"
+    "@clack/prompts": "^1.8.1",
+    "pg": "8.18.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
-    "@types/pg": "^8.16.0",
-    "typescript": "^5.7.2"
+    "@types/node": "^26.6.1",
+    "@types/pg": "^8.23.1",
+    "typescript": "^5.9.3"
   },
   "files": [
     "dist",
-    "templates"
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__/**",
+    "templates",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "!dist/**/*.tsbuildinfo"
   ],
   "publishConfig": {
     "access": "public"
   },
+  "engines": {
+    "node": ">=22.14"
+  },
+  "sideEffects": false,
   "scripts": {
     "type-check": "tsc --noEmit",
     "lint": "eslint .",
-    "build": "tsc -p tsconfig.build.json"
+    "build": "node scripts/sync-registry-requires.mjs && tsc -p tsconfig.build.json && node ../../scripts/fix-esm-extensions.mjs dist"
   }
 }

package/src/bin.ts

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+/**
+ * intelligo <command>
+ *
+ * The shebang targets node because that is what runs the *published*
+ * binary from dist/. In this workspace the source is run with
+ * `pnpm exec tsx packages/cli/src/bin.ts`.
+ *
+ * Deliberately tiny: the commands are library functions, and this file
+ * only maps argv onto them, opens a database connection when one is
+ * needed, and picks an exit code.
+ */
+
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  addFeature,
+  formatAddResult,
+  addExitCode,
+  readCatalogue,
+} from "./commands/add.js";
+import { exitCodeFor, formatResults, runChecks } from "./commands/doctor.js";
+import {
+  formatMigrateCheck,
+  formatMigrateCheckJson,
+  migrateCheck,
+  migrateCheckExitCode,
+} from "./commands/migrate-check.js";
+import {
+  MIGRATIONS_TABLE_SQL,
+  SCHEMA_PROBE_SQL,
+  applyExitCode,
+  applyMigrations,
+  formatApplyResult,
+} from "./commands/migrate.js";
+import {
+  formatSyncReport,
+  installedFrameworkVersion,
+  selectItems,
+  syncApply,
+  syncCheck,
+  syncCheckExitCode,
+  type SyncContext,
+} from "./commands/sync.js";
+import {
+  formatUpgradeReport,
+  upgradeCheck,
+  upgradeCheckExitCode,
+} from "./commands/upgrade-check.js";
+
+import { loadAppEnv } from "./env-files.js";
+import { resolveRegistryDir } from "./registry-bundle.js";
+import { readRegistryCatalogue } from "./registry-items.js";
+import { MIGRATION_LOCATIONS, resolveMigrationsDir } from "./migrations-dir.js";
+
+/**
+ * Templates ship with the CLI package.
+ *
+ * `fileURLToPath`, not `new URL(...).pathname`: on Windows the latter
+ * yields `/C:/Users/...`, which every path operation after it treats as
+ * a root-relative path that does not exist. The CLI is the first thing
+ * a new user runs, so it is the worst place to be silently
+ * platform-specific.
+ */
+const TEMPLATES_DIR = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "templates"
+);
+
+/**
+ * Recorded in the manifest so an upgrade knows what wrote a file, and
+ * emitted as the dependency range of a scaffolded app. Read from this
+ * package's own manifest so a release cannot ship with a stale literal
+ * — `../package.json` resolves from src/ and from dist/ alike.
+ */
+const FRAMEWORK_VERSION: string = createRequire(import.meta.url)(
+  "../package.json"
+).version;
+
+function usage(): string {
+  return [
+    "intelligo <command>",
+    "",
+    "  create [dir]      Scaffold an app, then install the registry pages you pick",
+    "                    (--items a,b | --all, --yes, --no-install)",
+    "  doctor            Report configuration and migration-chain problems",
+    "  migrate           Apply the framework's migration chain to DATABASE_URL",
+    "  migrate --check   Compare the framework's migrations to a database",
+    "                    (--json: one object whose `state` is up_to_date | pending |",
+    "                    fresh | ahead | unmanaged | legacy)",
+    "  add <feature>     Generate consumer-owned source (--force to overwrite)",
+    "  upgrade --check   Show what a template upgrade would change",
+    "  sync [items…]     Install registry pages from this release's registry,",
+    "                    keeping seams and merging messages (--force replaces",
+    "                    hand-edited files; --check only reports, exit 1 on drift)",
+    "",
+  ].join("\n");
+}
+
+async function runMigrate(
+  mode: "check" | "apply",
+  json = false
+): Promise<number> {
+  const url = process.env.DATABASE_URL;
+  if (!url) {
+    console.error(
+      `DATABASE_URL is required for \`migrate${mode === "check" ? " --check" : ""}\`.`
+    );
+    return 1;
+  }
+
+  const migrationsDir = resolveMigrationsDir(process.cwd());
+  if (!migrationsDir) {
+    console.error(
+      `No migrations directory (looked in ${MIGRATION_LOCATIONS.join(", ")}) — run from the workspace root, with @intelligo-dev/core installed.`
+    );
+    return 1;
+  }
+
+  // Imported lazily so `doctor` — the command you reach for when the
+  // app will not start — never needs a database driver to load.
+  const { Client } = await import("pg");
+  const client = new Client({ connectionString: url });
+  await client.connect();
+
+  try {
+    if (mode === "check") {
+      const result = await migrateCheck(
+        migrationsDir,
+        async (sql) => (await client.query<{ hash: string }>(sql)).rows
+      );
+      const probe = await client.query<{ rel: string | null }>(
+        SCHEMA_PROBE_SQL
+      );
+      const schemaExists = probe.rows[0]?.rel != null;
+      console.log(
+        json
+          ? formatMigrateCheckJson(result, schemaExists)
+          : formatMigrateCheck(result, schemaExists)
+      );
+      return migrateCheckExitCode(result);
+    }
+
+    // Applied here rather than by drizzle's migrator: the pending set is
+    // chosen by content hash — what `migrate --check` compares — and
+    // recorded in drizzle's own table, in one transaction, so a failure
+    // part-way leaves neither statements nor records behind.
+    const result = await applyMigrations({
+      migrationsDir,
+      query: async (sql) => (await client.query(sql)).rows,
+      run: async (pending) => {
+        await client.query("BEGIN");
+        try {
+          for (const ddl of MIGRATIONS_TABLE_SQL) await client.query(ddl);
+          for (const migration of pending) {
+            for (const statement of migration.statements) {
+              await client.query(statement);
+            }
+            await client.query(
+              `INSERT INTO "drizzle"."__drizzle_migrations" ("hash", "created_at") VALUES ($1, $2)`,
+              [migration.hash, migration.createdAt]
+            );
+          }
+          await client.query("COMMIT");
+        } catch (error) {
+          await client.query("ROLLBACK");
+          throw error;
+        }
+      },
+    });
+    console.log(formatApplyResult(result));
+    return applyExitCode(result);
+  } finally {
+    await client.end();
+  }
+}
+
+async function main(): Promise<number> {
+  const [, , command = "help", ...rest] = process.argv;
+
+  // The commands that read the app's configuration see what the app
+  // itself would: its .env.local and .env, under anything the shell set.
+  if (command === "doctor" || command === "migrate" || command === "upgrade") {
+    loadAppEnv(process.cwd());
+  }
+
+  switch (command) {
+    case "doctor": {
+      const results = runChecks();
+      console.log(formatResults(results));
+      return exitCodeFor(results);
+    }
+    case "migrate": {
+      // Applying is the default, so a mistyped flag (`--dry-run`,
+      // `--chek`) must not fall through to it.
+      const unknown = rest.filter(
+        (arg) => arg !== "--check" && arg !== "--json"
+      );
+      if (unknown.length > 0) {
+        console.error(
+          `intelligo migrate: unknown argument ${unknown.join(" ")}. ` +
+            "Use `intelligo migrate` to apply, `--check` to only report, " +
+            "and `--json` with `--check` for a machine-readable answer."
+        );
+        return 2;
+      }
+      return runMigrate(
+        rest.includes("--check") ? "check" : "apply",
+        rest.includes("--json")
+      );
+    }
+    case "create": {
+      // Imported lazily so the prompts library loads only for the one
+      // command that converses.
+      const { parseCreateFlags, runCreate } =
+        await import("./commands/create-flow.js");
+      return runCreate(parseCreateFlags(rest), {
+        templatesDir: TEMPLATES_DIR,
+        frameworkVersion: FRAMEWORK_VERSION,
+        interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+      });
+    }
+    case "add": {
+      const feature = rest.find((a) => !a.startsWith("--"));
+      if (!feature) {
+        const catalogue = readCatalogue(TEMPLATES_DIR);
+        console.error("Usage: intelligo add <feature>\n");
+        for (const [name, spec] of Object.entries(catalogue)) {
+          console.error(`  ${name.padEnd(16)} ${spec.description}`);
+        }
+        return 1;
+      }
+      const result = addFeature(feature, {
+        appRoot: process.cwd(),
+        templatesDir: TEMPLATES_DIR,
+        frameworkVersion: FRAMEWORK_VERSION,
+        force: rest.includes("--force"),
+      });
+      console.log(formatAddResult(result));
+      return addExitCode(result);
+    }
+    case "upgrade": {
+      if (!rest.includes("--check")) {
+        console.error("Only `upgrade --check` is implemented.");
+        console.error(
+          "Applying an upgrade means re-running `intelligo add` for the " +
+            "features it reports as outdated — deliberately your call, " +
+            "since the files are yours."
+        );
+        return 1;
+      }
+      const report = upgradeCheck({
+        appRoot: process.cwd(),
+        templatesDir: TEMPLATES_DIR,
+      });
+      console.log(formatUpgradeReport(report));
+      return upgradeCheckExitCode(report);
+    }
+    case "sync": {
+      const registryDir = resolveRegistryDir(TEMPLATES_DIR);
+      if (!registryDir) {
+        console.error(
+          "This CLI has no bundled registry — in the framework repository, run `pnpm registry:build` first."
+        );
+        return 1;
+      }
+      const context: SyncContext = {
+        appRoot: process.cwd(),
+        registryDir,
+        requires: readRegistryCatalogue(TEMPLATES_DIR).requires,
+        frameworkVersion: FRAMEWORK_VERSION,
+      };
+      const installed = installedFrameworkVersion(context.appRoot);
+      if (installed && installed !== FRAMEWORK_VERSION) {
+        console.error(
+          `! @intelligo-dev/core is ${installed} but this CLI carries the ${FRAMEWORK_VERSION} registry — ` +
+            "run the CLI of the same version (`pnpm exec intelligo`), or pages and packages will disagree."
+        );
+      }
+      const selection = selectItems(
+        rest.filter((a) => !a.startsWith("-")),
+        context
+      );
+      if (!selection.ok) {
+        console.error(selection.message);
+        return 1;
+      }
+      if (rest.includes("--check")) {
+        const report = syncCheck(selection.items, context);
+        console.log(formatSyncReport(report));
+        return syncCheckExitCode(report);
+      }
+      return syncApply(selection.items, context, {
+        force: rest.includes("--force"),
+      });
+    }
+    case "help":
+      console.log(usage());
+      return 0;
+    default:
+      console.error(`Unknown command: ${command}\n`);
+      console.error(usage());
+      return 1;
+  }
+}
+
+main().then(
+  (code) => process.exit(code),
+  (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+);

package/src/commands/add.ts

@@ -0,0 +1,255 @@
+/**
+ * `intelligo add <feature>` — generate consumer-owned source.
+ *
+ * "Owned" is the operative word: the files land in the
+ * consumer's repository and Intelligo stops deciding what is in them.
+ * The manifest records what was written and its hash so a later
+ * upgrade can tell an untouched file from one the consumer has made
+ * their own, and refuse to overwrite the latter.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import {
+  emptyManifest,
+  hashContents,
+  readManifest,
+  recordFeature,
+  writeManifest,
+  type GeneratedFile,
+} from "../manifest.js";
+
+export type TemplateFile = { template: string; target: string };
+/** A route the feature needs called on a schedule (five-field cron). */
+export type TemplateCron = { path: string; schedule: string };
+export type TemplateFeature = {
+  templateVersion: string;
+  description: string;
+  /** Set when a registry item supersedes this template feature. */
+  deprecated?: string;
+  files: TemplateFile[];
+  cron?: TemplateCron;
+  /** What the developer still does by hand once the files are written. */
+  nextSteps?: string[];
+};
+export type TemplateCatalogue = Record<string, TemplateFeature>;
+
+export function readCatalogue(templatesDir: string): TemplateCatalogue {
+  return JSON.parse(
+    readFileSync(path.join(templatesDir, "manifest.json"), "utf8")
+  ) as TemplateCatalogue;
+}
+
+export type AddResult = {
+  feature: string;
+  /** The catalogue's deprecation notice, when the feature has one. */
+  deprecated?: string;
+  written: string[];
+  /** Present and modified by the consumer — left untouched. */
+  skippedCustomized: string[];
+  /** Present but not ours (no manifest record) — left untouched. */
+  skippedUnknown: string[];
+  /**
+   * The feature's schedule and what became of it: `written` to a new
+   * vercel.json, already `present` in the app's own, or `manual` — the
+   * app has a vercel.json without it, which is the consumer's to edit.
+   */
+  cron?: TemplateCron & { status: "written" | "present" | "manual" };
+  /** The catalogue's steps left to the developer, printed after the files. */
+  nextSteps?: string[];
+};
+
+export type AddOptions = {
+  appRoot: string;
+  templatesDir: string;
+  frameworkVersion: string;
+  /** Re-write files the consumer has customized. Off by default. */
+  force?: boolean;
+  /**
+   * Placeholder substitutions applied to template contents, e.g.
+   * `{ __APP_NAME__: "acme" }`. Applied before hashing, so the
+   * recorded hash describes what actually landed on disk.
+   */
+  variables?: Record<string, string>;
+};
+
+export function substitute(
+  contents: string,
+  variables: Record<string, string> | undefined
+): string {
+  if (!variables) return contents;
+  return Object.entries(variables).reduce(
+    (out, [key, value]) => out.split(key).join(value),
+    contents
+  );
+}
+
+const VERCEL_CONFIG = "vercel.json";
+
+/**
+ * Schedule the cron in vercel.json when the app has none. An existing
+ * one is deployment configuration the consumer wrote: it is read to see
+ * whether the path is already scheduled, never written. The file is not
+ * recorded in the manifest either — it is the consumer's from the start.
+ */
+function scheduleCron(
+  appRoot: string,
+  cron: TemplateCron
+): "written" | "present" | "manual" {
+  const file = path.join(appRoot, VERCEL_CONFIG);
+  if (!existsSync(file)) {
+    const config = {
+      $schema: "https://openapi.vercel.sh/vercel.json",
+      crons: [cron],
+    };
+    writeFileSync(file, JSON.stringify(config, null, 2) + "\n");
+    return "written";
+  }
+  try {
+    const config = JSON.parse(readFileSync(file, "utf8")) as {
+      crons?: Array<{ path?: string }>;
+    };
+    return config.crons?.some((c) => c.path === cron.path)
+      ? "present"
+      : "manual";
+  } catch {
+    return "manual";
+  }
+}
+
+export function addFeature(feature: string, options: AddOptions): AddResult {
+  const catalogue = readCatalogue(options.templatesDir);
+  const spec = catalogue[feature];
+  if (!spec) {
+    throw new Error(
+      `Unknown feature "${feature}". Available: ${Object.keys(catalogue).join(", ")}`
+    );
+  }
+
+  const manifest =
+    readManifest(options.appRoot) ?? emptyManifest(options.frameworkVersion);
+  const previous = manifest.features[feature];
+  const previousByPath = new Map(
+    (previous?.files ?? []).map((f) => [f.path, f])
+  );
+
+  const result: AddResult = {
+    feature,
+    written: [],
+    skippedCustomized: [],
+    skippedUnknown: [],
+  };
+  if (spec.deprecated) result.deprecated = spec.deprecated;
+  if (spec.nextSteps?.length) result.nextSteps = spec.nextSteps;
+  const recorded: GeneratedFile[] = [];
+  const handedOver = new Set(previous?.handedOver ?? []);
+
+  for (const file of spec.files) {
+    // A registry item replaced it; `intelligo sync` keeps it now.
+    if (handedOver.has(file.target)) continue;
+    const source = path.join(options.templatesDir, file.template);
+    const target = path.join(options.appRoot, file.target);
+    const contents = substitute(
+      readFileSync(source, "utf8"),
+      options.variables
+    );
+
+    if (existsSync(target) && !options.force) {
+      const current = hashContents(readFileSync(target, "utf8"));
+      const known = previousByPath.get(file.target);
+
+      if (!known) {
+        // Not ours: a file we never generated already occupies the
+        // path. Overwriting it would destroy work we cannot attribute.
+        result.skippedUnknown.push(file.target);
+        continue;
+      }
+      if (current !== known.hash) {
+        result.skippedCustomized.push(file.target);
+        // Keep the ORIGINAL hash: it is the baseline that says "this is
+        // customized", and replacing it with the current hash would
+        // silently re-adopt the consumer's file as ours.
+        recorded.push(known);
+        continue;
+      }
+    }
+
+    mkdirSync(path.dirname(target), { recursive: true });
+    writeFileSync(target, contents);
+    recorded.push({ path: file.target, hash: hashContents(contents) });
+    result.written.push(file.target);
+  }
+
+  if (spec.cron) {
+    result.cron = {
+      ...spec.cron,
+      status: scheduleCron(options.appRoot, spec.cron),
+    };
+  }
+
+  writeManifest(
+    options.appRoot,
+    recordFeature(
+      manifest,
+      feature,
+      spec.templateVersion,
+      recorded,
+      options.variables
+    )
+  );
+
+  return result;
+}
+
+export function formatAddResult(r: AddResult): string {
+  const lines = [`${r.feature}:`];
+  if (r.deprecated) lines.push(`  ⚠ deprecated: ${r.deprecated}`);
+  for (const f of r.written) lines.push(`  + ${f}`);
+  for (const f of r.skippedCustomized)
+    lines.push(`  = ${f} (yours — left alone; use --force to overwrite)`);
+  for (const f of r.skippedUnknown)
+    lines.push(`  ! ${f} (already exists and was not generated by Intelligo)`);
+  if (r.cron?.status === "written")
+    lines.push(`  + ${VERCEL_CONFIG} (${r.cron.path} on "${r.cron.schedule}")`);
+  if (
+    r.written.length === 0 &&
+    r.skippedCustomized.length === 0 &&
+    r.skippedUnknown.length === 0 &&
+    r.cron?.status !== "written"
+  )
+    lines.push("  nothing to do");
+  if (r.cron) lines.push(...cronNextSteps(r.cron));
+  if (r.nextSteps?.length) {
+    lines.push("", "  Next:", ...r.nextSteps.map((step) => `  - ${step}`));
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Non-zero when a file the feature needs is still missing: one that
+ * exists but was not generated by Intelligo was left alone, so the
+ * feature is not installed as the catalogue describes it.
+ */
+export function addExitCode(r: AddResult): number {
+  return r.skippedUnknown.length > 0 ? 1 : 0;
+}
+
+function cronNextSteps(cron: NonNullable<AddResult["cron"]>): string[] {
+  const entry = JSON.stringify({ path: cron.path, schedule: cron.schedule });
+  const lines = ["", "  Next:"];
+  if (cron.status === "manual") {
+    lines.push(
+      `  - ${VERCEL_CONFIG} is yours and was left alone. Add to its "crons":`,
+      `      ${entry}`
+    );
+  }
+  lines.push(
+    "  - Set CRON_SECRET (32+ characters). Vercel sends it as the Bearer token itself.",
+    "  - Vercel Hobby runs a cron at most once a day and refuses a deployment that",
+    `    asks for more. On Hobby, or on any other host, remove the ${VERCEL_CONFIG} entry`,
+    "    and call the route from your own scheduler at the same cadence:",
+    `      curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://<your-app>${cron.path}`
+  );
+  return lines;
+}