@intelligo-dev/cli 1.0.0-beta.13 → 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

@@ -3,11 +3,10 @@
  * is, what else it needs installed first, and the commands that install
  * a selection into a fresh app.
  *
- * Installing is the shadcn CLI's job, not this package's — the items
- * are shadcn-schema JSON served at intelligo.dev/r, and the scaffold's
- * components.json already names that registry as `@intelligo`. What the
- * CLI adds is the order: an item that imports a sibling's files
- * (requires.json `items`) has to land after it.
+ * 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";
@@ -79,10 +78,23 @@ export function detectPackageManager(
   return name === "npm" || name === "yarn" || name === "bun" ? name : "pnpm";
 }
 
-export type Command = { command: string; args: string[] };
+export type Command = {
+  command: string;
+  args: string[];
+  /** Where it runs, when not the app itself (a parent workspace's root). */
+  cwd?: string;
+};
 
-export function formatCommand(c: Command): string {
-  return [c.command, ...c.args].join(" ");
+/**
+ * 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[]> = {
@@ -97,36 +109,129 @@ 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;
+};
+
 /**
- * The commands that put `items` into the app at `appRoot`: install the
- * dependencies when shadcn is not there yet (the scaffold declares it),
- * then the design-system base, then the items in dependency order.
- * `--overwrite` because the base replaces the scaffold's globals.css,
- * and items that share a file agree on it — the same flags the
- * reference app is regenerated with.
+ * 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 }
-): Command[] {
-  if (items.length === 0) return [];
-  const [command, ...exec] = EXEC[options.packageManager];
-  const add = (names: string[]): Command => ({
-    command: command!,
-    args: [
-      ...exec,
-      "shadcn",
-      "add",
-      ...names.map((n) => `@intelligo/${n}`),
-      "--yes",
-      "--overwrite",
-    ],
-  });
-  return [
-    ...(hasLocalShadcn(options.appRoot)
-      ? []
-      : [{ command: options.packageManager, args: ["install"] }]),
-    add(["intelligo"]),
-    add([...items]),
-  ];
+  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/app-scaffold/intelligo.ts.tpl

@@ -14,12 +14,9 @@ import "server-only";
  */
 
 import {
+  createBillingExecutions,
   ensureBillingSettingsRow,
   ensurePlanRows,
-  reserveQuota,
-  recordTokenUsage,
-  releaseReservation,
-  findSettlementByRequestId,
 } from "@intelligo-dev/billing";
 import { DEFAULT_MARGIN_BP } from "@intelligo-dev/executions/pricing";
 import {
@@ -33,7 +30,6 @@ import { assertEnv } from "@intelligo-dev/core/env";
 import { setRequestContextSource } from "@intelligo-dev/core/request-context";
 import {
   DEFAULT_MODELS,
-  createExecutions,
   registerModels,
 } from "@intelligo-dev/executions";
 import { nextRequestContext } from "@intelligo-dev/next";
@@ -135,45 +131,8 @@ function bind(): void {
   registerModels(DEFAULT_MODELS);
 }
 
-export const executions = createExecutions({
-  async checkEntitlement({ workspaceId, requestId, model }) {
-    // Passing requestId makes admission atomic: the worst-case cost is
-    // reserved in the same transaction that reads the balance, so
-    // concurrent requests cannot all pass.
-    const quota = await reserveQuota(workspaceId, { modelId: model, requestId });
-    return {
-      allowed: quota.allowed,
-      code: quota.code,
-      reason: quota.reason,
-      // The hold, as an amount with its currency.
-      estimated: quota.estimated,
-      usingTrialCredits: quota.usingTrialCredits,
-    };
-  },
-
-  async settleUsage(s) {
-    // Returns what was charged and which pool funded it; the lifecycle
-    // records the amount and its currency on the execution row.
-    return recordTokenUsage({
-      workspaceId: s.workspaceId,
-      userId: s.userId ?? "",
-      model: s.model ?? "unknown",
-      agent: s.capability,
-      inputTokens: s.inputTokens,
-      outputTokens: s.outputTokens,
-      totalTokens: s.totalTokens,
-      usingTrialCredits: s.usingTrialCredits,
-      requestId: s.requestId,
-      metadata: s.metadata,
-    });
-  },
-
-  async releaseHold({ requestId }) {
-    await releaseReservation(requestId);
-  },
-
-  // Lets executions.reconcile() tell a settling row whose charge
-  // committed from one whose charge never happened.
-  findSettlement: ({ workspaceId, requestId }) =>
-    findSettlementByRequestId(workspaceId, requestId),
-});
+// The execution boundary, bound to the billing engine: admission
+// reserves the worst-case cost atomically, settlement records usage and
+// deducts credits, reconcile() can tell a committed charge from none.
+// Pass a port to replace one.
+export const executions = createBillingExecutions();

package/templates/manifest.json

@@ -151,5 +151,24 @@
         "target": "app/api/cron/maintenance/route.ts"
       }
     ]
+  },
+  "vitest": {
+    "templateVersion": "1.0.0",
+    "description": "A Vitest setup for the app's own tests: the `@` alias, a `server-only` stub, and the `@intelligo-dev/*` packages inlined so the stub reaches them",
+    "files": [
+      {
+        "template": "vitest/vitest.config.ts.tpl",
+        "target": "vitest.config.ts"
+      },
+      {
+        "template": "vitest/server-only.ts.tpl",
+        "target": "tests/stubs/server-only.ts"
+      }
+    ],
+    "nextSteps": [
+      "Install the runner: pnpm add -D vitest",
+      "Add a script to package.json: \"test\": \"vitest run\"",
+      "Write tests beside the code as *.test.ts; mock @ai-sdk/* providers so CI makes no model calls"
+    ]
   }
 }