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

package/src/module-exports.ts

@@ -0,0 +1,266 @@
+/**
+ * What a TypeScript module exports, read from its text — enough for
+ * `doctor` to confirm an app provides the names an installed item
+ * imports, without compiling or running the app.
+ *
+ * It understands declarations (`export const|function|class|type|
+ * interface|enum …`), export lists with aliases (`export { a as b }`),
+ * re-exports (`export { x } from "…"`, `export * from "…"`) and the
+ * imports a bare export list re-exports. Modules are resolved the way
+ * the app would: relative paths, the `@/` alias, and packages through
+ * node resolution from the app's root (a workspace package included).
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+/**
+ * Block and line comments removed, so a check cannot be satisfied — or
+ * defeated — by prose.
+ */
+export function stripComments(text: string): string {
+  return text
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/(^|[^:])\/\/.*$/gm, "$1");
+}
+
+export function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export type ModuleShape = {
+  /** Names exported by this module itself, or re-exported by name. */
+  names: Set<string>;
+  /** Exported name → the module it is re-exported from, when it is. */
+  reexports: Map<string, string>;
+  /** `export * from "…"` specifiers. */
+  stars: string[];
+  /** Local name → the module it was imported from. */
+  imports: Map<string, string>;
+};
+
+const DECLARATION =
+  /\bexport\s+(?:declare\s+)?(?:default\s+)?(?:abstract\s+)?(?:async\s+)?(?:const|let|var|function\s*\*?|class|type|interface|enum)\s+([A-Za-z_$][\w$]*)/g;
+const EXPORT_LIST =
+  /\bexport\s+(?:type\s+)?\{([^}]*)\}(?:\s*from\s*["']([^"']+)["'])?/g;
+const EXPORT_STAR =
+  /\bexport\s+(?:type\s+)?\*\s*(?:as\s+([A-Za-z_$][\w$]*)\s+)?from\s*["']([^"']+)["']/g;
+const IMPORT =
+  /\bimport\s+(?:type\s+)?([\w$]+\s*,?\s*)?(?:\{([^}]*)\}|\*\s*as\s+([\w$]+))?\s*from\s*["']([^"']+)["']/g;
+
+/** `a`, `type a`, `a as b` → [local, exported]. */
+function specifiers(list: string): Array<[string, string]> {
+  return list
+    .split(",")
+    .map((s) => s.trim().replace(/^type\s+/, ""))
+    .filter(Boolean)
+    .map((s) => {
+      const [local, exported] = s.split(/\s+as\s+/).map((x) => x.trim());
+      return [local!, exported ?? local!];
+    });
+}
+
+/** The shape of a module's text; comments are stripped first. */
+export function moduleShape(source: string): ModuleShape {
+  const text = stripComments(source);
+  const shape: ModuleShape = {
+    names: new Set(),
+    reexports: new Map(),
+    stars: [],
+    imports: new Map(),
+  };
+  for (const m of text.matchAll(IMPORT)) {
+    const from = m[4]!;
+    const defaultName = m[1]?.replace(/[\s,]/g, "");
+    if (defaultName) shape.imports.set(defaultName, from);
+    if (m[3]) shape.imports.set(m[3], from);
+    for (const [, local] of specifiers(m[2] ?? "")) {
+      shape.imports.set(local, from);
+    }
+  }
+  for (const m of text.matchAll(DECLARATION)) shape.names.add(m[1]!);
+  for (const m of text.matchAll(EXPORT_LIST)) {
+    for (const [local, exported] of specifiers(m[1]!)) {
+      shape.names.add(exported);
+      const from = m[2] ?? shape.imports.get(local);
+      if (from) shape.reexports.set(exported, from);
+    }
+  }
+  for (const m of text.matchAll(EXPORT_STAR)) {
+    if (m[1]) shape.names.add(m[1]);
+    else shape.stars.push(m[2]!);
+  }
+  return shape;
+}
+
+const EXTENSIONS = [".ts", ".tsx", ".mts", ".d.ts", ".js", ".mjs", ".jsx"];
+
+function resolveFile(base: string): string | null {
+  const isFile = (p: string) => existsSync(p) && statSync(p).isFile();
+  if (isFile(base)) return base;
+  // TypeScript sources import siblings with the `.js` they compile to.
+  const stem = base.replace(/\.(?:m?js|jsx)$/, "");
+  for (const ext of EXTENSIONS) if (isFile(stem + ext)) return stem + ext;
+  for (const ext of EXTENSIONS) {
+    const index = path.join(base, `index${ext}`);
+    if (isFile(index)) return index;
+  }
+  return null;
+}
+
+/** The first file path an `exports` condition object leads to. */
+function pickCondition(entry: unknown): string | null {
+  if (typeof entry === "string") return entry;
+  if (!entry || typeof entry !== "object") return null;
+  const record = entry as Record<string, unknown>;
+  for (const key of ["import", "default", "node", "require", "types"]) {
+    const hit = key in record ? pickCondition(record[key]) : null;
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/** A package's module file from its package.json `exports`, `module` or `main`. */
+function packageFile(specifier: string, appRoot: string): string | null {
+  const parts = specifier.split("/");
+  const name = specifier.startsWith("@")
+    ? parts.slice(0, 2).join("/")
+    : parts[0]!;
+  const subpath = `.${specifier.slice(name.length)}`;
+  let dir = path.resolve(appRoot);
+  for (;;) {
+    const manifestFile = path.join(dir, "node_modules", name, "package.json");
+    if (existsSync(manifestFile)) {
+      const pkgDir = path.dirname(manifestFile);
+      const manifest = JSON.parse(readFileSync(manifestFile, "utf8")) as {
+        exports?: unknown;
+        module?: string;
+        main?: string;
+      };
+      const exp = manifest.exports;
+      let target: string | null = null;
+      if (typeof exp === "string") target = subpath === "." ? exp : null;
+      else if (exp && typeof exp === "object") {
+        const map = exp as Record<string, unknown>;
+        const keyed = Object.keys(map).some((k) => k.startsWith("."));
+        target = pickCondition(
+          keyed ? map[subpath] : subpath === "." ? map : null
+        );
+      }
+      if (!target && subpath === ".")
+        target = manifest.module ?? manifest.main ?? "index";
+      if (!target && subpath !== ".") target = subpath;
+      return target ? resolveFile(path.join(pkgDir, target)) : null;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * The file a module specifier leads to from `fromFile`, or null when it
+ * cannot be found: relative, the `@/` alias, then node resolution from
+ * the app's root.
+ */
+export function resolveModule(
+  specifier: string,
+  fromFile: string,
+  appRoot: string
+): string | null {
+  if (specifier.startsWith(".")) {
+    return resolveFile(path.resolve(path.dirname(fromFile), specifier));
+  }
+  if (specifier.startsWith("@/")) {
+    return resolveFile(path.join(appRoot, specifier.slice(2)));
+  }
+  const fromPackage = packageFile(specifier, appRoot);
+  if (fromPackage) return fromPackage;
+  try {
+    const resolved = createRequire(path.join(appRoot, "package.json")).resolve(
+      specifier
+    );
+    return existsSync(resolved) ? resolved : null;
+  } catch {
+    return null;
+  }
+}
+
+export type ExportCheck = {
+  /** Names the module provably does not export. */
+  missing: string[];
+  /**
+   * `export * from` specifiers that could not be read: the names not
+   * found elsewhere are assumed to come from them.
+   */
+  unresolved: string[];
+};
+
+/**
+ * Which of `names` the module at `file` does not export, following
+ * `export * from` into the modules it can resolve.
+ */
+export function checkExports(
+  file: string,
+  names: readonly string[],
+  appRoot: string,
+  seen: Set<string> = new Set()
+): ExportCheck {
+  seen.add(file);
+  const shape = moduleShape(readFileSync(file, "utf8"));
+  let missing = names.filter((n) => !shape.names.has(n));
+  const unresolved: string[] = [];
+  for (const star of shape.stars) {
+    if (missing.length === 0) break;
+    const target = resolveModule(star, file, appRoot);
+    if (!target) {
+      unresolved.push(star);
+      continue;
+    }
+    if (seen.has(target)) continue;
+    const inner = checkExports(target, missing, appRoot, seen);
+    missing = inner.missing;
+    unresolved.push(...inner.unresolved);
+  }
+  return unresolved.length > 0
+    ? { missing: [], unresolved }
+    : { missing, unresolved };
+}
+
+/**
+ * The text of a module and of every module it re-exports from —
+ * `export … from`, `export * from`, and imports a bare export list
+ * passes on — comments stripped. What a `lib/plans.ts` that re-exports
+ * a workspace package's catalogue actually defines.
+ */
+export function reexportedSource(
+  file: string,
+  appRoot: string,
+  depth = 3
+): { text: string; unresolved: string[] } {
+  const seen = new Set<string>();
+  const unresolved: string[] = [];
+  const texts: string[] = [];
+  const visit = (current: string, left: number) => {
+    if (seen.has(current)) return;
+    seen.add(current);
+    const source = readFileSync(current, "utf8");
+    texts.push(stripComments(source));
+    if (left === 0) return;
+    const shape = moduleShape(source);
+    for (const spec of new Set([...shape.reexports.values(), ...shape.stars])) {
+      const target = resolveModule(spec, current, appRoot);
+      if (target) visit(target, left - 1);
+      else unresolved.push(spec);
+    }
+  };
+  visit(file, depth);
+  return { text: texts.join("\n"), unresolved };
+}
+
+/** An object key `key:` or `"key":`, not a longer identifier ending in it. */
+export function hasObjectKey(text: string, key: string): boolean {
+  const k = escapeRegExp(key);
+  return new RegExp(`(?:(?<![\\w$-])${k}|["'\`]${k}["'\`])\\s*:`).test(text);
+}

package/src/registry-bundle.ts

@@ -0,0 +1,103 @@
+/**
+ * The page registry as this CLI ships it.
+ *
+ * The build copies packages/registry/public/r — the same shadcn-schema
+ * JSON intelligo.dev/r serves — into templates/registry, so the items a
+ * CLI installs are the ones built with the packages of its own version:
+ * `@intelligo-dev/cli@X` syncs the pages of framework X, never whatever
+ * the site deployed last. In the framework repository, before a build,
+ * the freshly built registry stands in for the bundle.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+export type RegistryFile = {
+  path: string;
+  type: string;
+  target?: string;
+  content?: string;
+};
+
+export type RegistryItemJson = {
+  name: string;
+  type: string;
+  files?: RegistryFile[];
+  registryDependencies?: string[];
+};
+
+/** How items name each other; resolved against this registry. */
+export const NAMESPACE = "@intelligo/";
+
+export function resolveRegistryDir(templatesDir: string): string | null {
+  const candidates = [
+    path.join(templatesDir, "registry"),
+    // packages/cli/templates → packages/registry/public/r
+    path.resolve(templatesDir, "..", "..", "registry", "public", "r"),
+  ];
+  return (
+    candidates.find((dir) => existsSync(path.join(dir, "intelligo.json"))) ??
+    null
+  );
+}
+
+export function hasRegistryItem(dir: string, name: string): boolean {
+  return (
+    /^[a-z0-9-]+$/.test(name) && existsSync(path.join(dir, `${name}.json`))
+  );
+}
+
+export function readRegistryItem(dir: string, name: string): RegistryItemJson {
+  if (!hasRegistryItem(dir, name)) {
+    throw new Error(`Unknown registry item "${name}".`);
+  }
+  return JSON.parse(
+    readFileSync(path.join(dir, `${name}.json`), "utf8")
+  ) as RegistryItemJson;
+}
+
+/** Where shadcn writes a file of an item. */
+export function installedPath(
+  item: Pick<RegistryItemJson, "type">,
+  file: RegistryFile
+): string | null {
+  if (file.target) return file.target;
+  if (item.type === "registry:ui") {
+    return `components/ui/${path.basename(file.path)}`;
+  }
+  return null;
+}
+
+/**
+ * A file as `shadcn add` writes it: the CLI drops the comment block that
+ * opens a file, so that header is not part of any comparison.
+ */
+export function asInstalled(source: string): string {
+  return source.replace(/^(?:\s*(?:\/\*[\s\S]*?\*\/|\/\/[^\n]*))*\s*/, "");
+}
+
+/**
+ * The named items and every Intelligo item they pull in through
+ * `@intelligo/<name>`, transitively, dependencies first — the set of
+ * files one `shadcn add` of each name writes. Dependencies outside the
+ * namespace (shadcn's own `utils`, `skeleton`…) are not this registry's
+ * to check.
+ */
+export function registryClosure(
+  dir: string,
+  names: readonly string[]
+): string[] {
+  const order: string[] = [];
+  const seen = new Set<string>();
+  const visit = (name: string) => {
+    if (seen.has(name)) return;
+    seen.add(name);
+    const item = readRegistryItem(dir, name);
+    for (const dep of item.registryDependencies ?? []) {
+      if (dep.startsWith(NAMESPACE)) visit(dep.slice(NAMESPACE.length));
+    }
+    order.push(name);
+  };
+  for (const name of names) visit(name);
+  return order;
+}

package/src/registry-items.ts

@@ -0,0 +1,237 @@
+/**
+ * The registry's pages as `intelligo create` offers them: what each one
+ * is, what else it needs installed first, and the commands that install
+ * a selection into a fresh app.
+ *
+ * Installing goes through `intelligo sync` (commands/sync.ts): one
+ * `shadcn add` per item from the registry bundled with this CLI, in the
+ * order requires.json `items` implies — an item that imports a
+ * sibling's files lands after it.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import type { RegistryRequires } from "./commands/doctor.js";
+
+export type RegistryItem = { title: string; description: string };
+export type RegistryCatalogue = {
+  items: Record<string, RegistryItem>;
+  requires: RegistryRequires;
+};
+
+/** Both files are build-time copies from packages/registry (see scripts/). */
+export function readRegistryCatalogue(templatesDir: string): RegistryCatalogue {
+  const read = (file: string) =>
+    JSON.parse(readFileSync(path.join(templatesDir, file), "utf8"));
+  return {
+    items: (
+      read("registry-items.json") as { items: Record<string, RegistryItem> }
+    ).items,
+    requires: read("registry-requires.json") as RegistryRequires,
+  };
+}
+
+/** The description's opening clause — short enough for one picker line. */
+export function shortDescription(description: string, max = 64): string {
+  const head = description.split(/[:.]\s|\s—\s/)[0]!.trim();
+  return head.length <= max ? head : `${head.slice(0, max - 1).trimEnd()}…`;
+}
+
+/**
+ * The selection plus everything it depends on, dependencies first.
+ * Unknown names throw rather than being dropped: a typo in `--items`
+ * should not quietly install less than was asked for.
+ */
+export function withDependencies(
+  selected: readonly string[],
+  requires: RegistryRequires
+): string[] {
+  const order: string[] = [];
+  const seen = new Set<string>();
+  const visit = (name: string) => {
+    if (seen.has(name)) return;
+    const entry = requires.items[name];
+    if (!entry) {
+      throw new Error(
+        `Unknown registry item "${name}". Available: ${Object.keys(requires.items).join(", ")}`
+      );
+    }
+    seen.add(name);
+    for (const dependency of entry.items ?? []) visit(dependency);
+    order.push(name);
+  };
+  for (const name of selected) visit(name);
+  return order;
+}
+
+export type PackageManager = "pnpm" | "npm" | "yarn" | "bun";
+
+/**
+ * Whichever manager ran the CLI (`pnpm dlx`, `npx`, `bunx`… all set
+ * npm_config_user_agent), else pnpm — the one the scaffold documents.
+ */
+export function detectPackageManager(
+  userAgent: string | undefined = process.env.npm_config_user_agent
+): PackageManager {
+  const name = userAgent?.split("/")[0];
+  return name === "npm" || name === "yarn" || name === "bun" ? name : "pnpm";
+}
+
+export type Command = {
+  command: string;
+  args: string[];
+  /** Where it runs, when not the app itself (a parent workspace's root). */
+  cwd?: string;
+};
+
+/**
+ * The command as a reader pastes it from `from` (the app's directory):
+ * a command that runs elsewhere is wrapped in a `cd`.
+ */
+export function formatCommand(c: Command, from?: string): string {
+  const line = [c.command, ...c.args].join(" ");
+  if (!c.cwd || !from || path.resolve(c.cwd) === path.resolve(from)) {
+    return line;
+  }
+  return `(cd ${path.relative(from, c.cwd) || "."} && ${line})`;
+}
+
+const EXEC: Record<PackageManager, string[]> = {
+  pnpm: ["pnpm", "exec"],
+  npm: ["npx"],
+  yarn: ["yarn"],
+  bun: ["bunx"],
+};
+
+/** Whether the app has its own shadcn binary, i.e. dependencies are installed. */
+export function hasLocalShadcn(appRoot: string): boolean {
+  return existsSync(path.join(appRoot, "node_modules", ".bin", "shadcn"));
+}
+
+/** The `packages:` globs of a pnpm-workspace.yaml (`!` exclusions kept). */
+export function workspaceGlobs(yaml: string): string[] {
+  const globs: string[] = [];
+  let inPackages = false;
+  for (const raw of yaml.split(/\r?\n/)) {
+    const line = raw.replace(/\s+#.*$/, "");
+    const key = /^packages\s*:\s*(.*)$/.exec(line);
+    if (key) {
+      const flow = /^\[(.*)\]$/.exec(key[1]!.trim());
+      if (flow) {
+        for (const g of flow[1]!.split(",")) {
+          const glob = g.trim().replace(/^["']|["']$/g, "");
+          if (glob) globs.push(glob);
+        }
+      } else inPackages = true;
+      continue;
+    }
+    if (!inPackages) continue;
+    const entry = /^\s+-\s*(.+?)\s*$/.exec(line);
+    if (entry) globs.push(entry[1]!.replace(/^["']|["']$/g, ""));
+    else if (/^\S/.test(line)) inPackages = false;
+  }
+  return globs;
+}
+
+function globToRegExp(glob: string): RegExp {
+  const pattern = glob
+    .replace(/^\.\//, "")
+    .replace(/\/+$/, "")
+    .split(/(\*\*|\*|\?)/)
+    .map((part) =>
+      part === "**"
+        ? ".*"
+        : part === "*"
+          ? "[^/]*"
+          : part === "?"
+            ? "[^/]"
+            : part.replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    )
+    .join("");
+  return new RegExp(`^${pattern}$`);
+}
+
+/**
+ * The root of the pnpm workspace that has `appRoot` as a member, if
+ * any: the nearest pnpm-workspace.yaml above the app, when one of its
+ * `packages` globs matches the app's path and no `!` glob excludes it.
+ * Installing from there updates the workspace's one lockfile instead of
+ * starting a nested one in the app.
+ */
+export function findWorkspaceRoot(appRoot: string): string | null {
+  const app = path.resolve(appRoot);
+  let dir = path.dirname(app);
+  for (;;) {
+    const file = path.join(dir, "pnpm-workspace.yaml");
+    if (existsSync(file)) {
+      const rel = path.relative(dir, app).split(path.sep).join("/");
+      const globs = workspaceGlobs(readFileSync(file, "utf8"));
+      const included = globs
+        .filter((g) => !g.startsWith("!"))
+        .some((g) => globToRegExp(g).test(rel));
+      const excluded = globs
+        .filter((g) => g.startsWith("!"))
+        .some((g) => globToRegExp(g.slice(1)).test(rel));
+      return included && !excluded ? dir : null;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** The design-system base, installed before any page. */
+const BASE = "intelligo";
+
+export type InstallPlan = {
+  /**
+   * The dependency install, when shadcn is not there yet (the scaffold
+   * declares it) — run from the parent workspace's root when the app is
+   * a member of one.
+   */
+  install: Command | null;
+  /** The items `intelligo sync` installs: the base first, then the pages in dependency order. */
+  items: string[];
+  /** The same sync as a command, for a reader to run by hand. */
+  sync: Command;
+};
+
+/**
+ * How `items` get into the app at `appRoot`: the dependencies first
+ * when shadcn is missing, then `intelligo sync` of the base and every
+ * item — one `shadcn add` per item in dependency order, from the
+ * registry bundled with this CLI, with `--force` because a fresh
+ * scaffold's files (globals.css, the theme provider) are the registry's
+ * to replace. Null when nothing was picked.
+ */
+export function installPlan(
+  items: readonly string[],
+  options: {
+    appRoot: string;
+    packageManager: PackageManager;
+    workspaceRoot?: string | null;
+  }
+): InstallPlan | null {
+  if (items.length === 0) return null;
+  const packageManager = options.workspaceRoot
+    ? "pnpm"
+    : options.packageManager;
+  const [command, ...exec] = EXEC[packageManager];
+  const synced = [BASE, ...items.filter((n) => n !== BASE)];
+  return {
+    install: hasLocalShadcn(options.appRoot)
+      ? null
+      : {
+          command: packageManager,
+          args: ["install"],
+          cwd: options.workspaceRoot ?? options.appRoot,
+        },
+    items: synced,
+    sync: {
+      command: command!,
+      args: [...exec, "intelligo", "sync", ...synced, "--force"],
+      cwd: options.appRoot,
+    },
+  };
+}

package/templates/admin-page/admin-page.tsx.tpl

@@ -1,11 +1,10 @@
 /**
- * The Intelligo operational console, mounted in your app.
+ * The operational console, mounted in your app.
  *
  * The screen itself ships from @intelligo-dev/admin so every deployment
  * shows the same operational truth — a fork could quietly stop showing
  * you unsettled executions. What is generated here is only the mount:
- * the route, the authorization call, and your own page chrome
- * (ADR-0002).
+ * the route, the authorization call, and your own page chrome.
  *
  * Access is gated on PLATFORM_ADMIN_EMAILS, not on a workspace role.
  * Workspace `owner` is per-tenant and every signup has one.

package/templates/app-scaffold/assistant-route.ts.tpl

@@ -5,7 +5,7 @@
  * it runs inside an execution — entitlement decided, worst-case cost
  * held, usage settled, audit emitted. Swap `callModel` for a Mastra
  * agent, an AI SDK call, or anything else and nothing around it
- * changes (ADR-0003).
+ * changes.
  */
 
 import { requireWorkspace } from "@intelligo-dev/auth";
@@ -15,7 +15,7 @@ import { CAPABILITIES, composeIntelligo, executions } from "@/lib/intelligo";
 export const maxDuration = 60;
 
 async function callModel(prompt: string) {
-  // Replace this with your framework's call.
+  // Your AI framework's call goes here.
   const inputTokens = Math.max(1, Math.ceil(prompt.length / 4));
   return {
     text: `Echo: ${prompt}`,

package/templates/app-scaffold/auth-route.ts.tpl

@@ -0,0 +1,10 @@
+/**
+ * Better-Auth's HTTP mount.
+ *
+ * Every call the auth client makes is a request to `/api/auth/*` on
+ * this app's own origin; without this file every sign-in POST answers
+ * 404. The handlers come from `@intelligo-dev/next`, so the app never
+ * depends on `better-auth` directly.
+ */
+
+export { GET, POST } from "@intelligo-dev/next/auth";

package/templates/app-scaffold/components.json.tpl

@@ -1,6 +1,6 @@
 {
   "$schema": "https://ui.shadcn.com/schema.json",
-  "style": "new-york",
+  "style": "base-nova",
   "rsc": true,
   "tsx": true,
   "tailwind": {
@@ -19,5 +19,9 @@
     "lib": "@/lib",
     "hooks": "@/hooks"
   },
-  "registries": {}
+  "registries": {
+    "@intelligo": "https://intelligo.dev/r/{name}.json"
+  },
+  "menuColor": "default",
+  "menuAccent": "subtle"
 }