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

package/src/bin.ts

@@ -50,9 +50,11 @@ import {
   upgradeCheckExitCode,
 } from "./commands/upgrade-check.js";
 
+import { itemNames, unknownFlags, wantsHelp } from "./args.js";
 import { loadAppEnv } from "./env-files.js";
+import { workspaceRootVariable } from "./commands/create.js";
 import { resolveRegistryDir } from "./registry-bundle.js";
-import { readRegistryCatalogue } from "./registry-items.js";
+import { findWorkspaceRoot, readRegistryCatalogue } from "./registry-items.js";
 import { MIGRATION_LOCATIONS, resolveMigrationsDir } from "./migrations-dir.js";
 
 /**
@@ -85,7 +87,7 @@ function usage(): string {
     "intelligo <command>",
     "",
     "  create [dir]      Scaffold an app, then install the registry pages you pick",
-    "                    (--items a,b | --all, --yes, --no-install)",
+    "                    (--items a,b | --all, --yes, --no-install, --name <name>)",
     "  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",
@@ -93,7 +95,8 @@ function usage(): string {
     "                    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,",
+    "  sync [items…]     Install registry pages from this release's registry",
+    "                    (names space- or comma-separated),",
     "                    keeping seams and merging messages (--force replaces",
     "                    hand-edited files; --check only reports, exit 1 on drift)",
     "",
@@ -178,17 +181,72 @@ async function runMigrate(
   }
 }
 
+function flagsOk(
+  command: string,
+  args: readonly string[],
+  allowed: readonly string[]
+): boolean {
+  const unknown = unknownFlags(args, allowed);
+  if (unknown.length === 0) return true;
+  console.error(
+    `intelligo ${command}: unknown argument ${unknown.join(" ")}` +
+      (allowed.length ? ` (it takes ${allowed.join(", ")}).` : ".")
+  );
+  return false;
+}
+
+function runAdd(rest: readonly string[]): number {
+  if (!flagsOk("add", rest, ["--force"])) return 2;
+  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;
+  }
+  if (feature === "pnpm-standalone" && findWorkspaceRoot(process.cwd())) {
+    console.error(
+      "intelligo add pnpm-standalone: this app is a member of a pnpm workspace, and a " +
+        "workspace file of its own would take it out; the workspace root's settings apply."
+    );
+    return 1;
+  }
+  const result = addFeature(feature, {
+    appRoot: process.cwd(),
+    templatesDir: TEMPLATES_DIR,
+    frameworkVersion: FRAMEWORK_VERSION,
+    force: rest.includes("--force"),
+    // Computed, not recorded: an app made before the variable existed
+    // has no value for it.
+    variables:
+      feature === "app-scaffold"
+        ? workspaceRootVariable(process.cwd())
+        : undefined,
+  });
+  console.log(formatAddResult(result));
+  return addExitCode(result);
+}
+
 async function main(): Promise<number> {
   const [, , command = "help", ...rest] = process.argv;
 
+  if (wantsHelp(rest)) {
+    console.log(usage());
+    return 0;
+  }
+
   // The commands that read the app's configuration see what the app
-  // itself would: its .env.local and .env, under anything the shell set.
+  // itself would: its .env.local and .env, then the pnpm workspace
+  // root's, under anything the shell set.
   if (command === "doctor" || command === "migrate" || command === "upgrade") {
     loadAppEnv(process.cwd());
   }
 
   switch (command) {
     case "doctor": {
+      if (!flagsOk("doctor", rest, [])) return 2;
       const results = runChecks();
       console.log(formatResults(results));
       return exitCodeFor(results);
@@ -217,32 +275,24 @@ async function main(): Promise<number> {
       // 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 flags = parseCreateFlags(rest);
+      if (flags.unknown.length > 0) {
+        console.error(
+          `intelligo create: unknown argument ${flags.unknown.join(" ")}.\n`
+        );
+        console.error(usage());
+        return 2;
       }
-      const result = addFeature(feature, {
-        appRoot: process.cwd(),
+      return runCreate(flags, {
         templatesDir: TEMPLATES_DIR,
         frameworkVersion: FRAMEWORK_VERSION,
-        force: rest.includes("--force"),
+        interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
       });
-      console.log(formatAddResult(result));
-      return addExitCode(result);
     }
+    case "add":
+      return runAdd(rest);
     case "upgrade": {
+      if (!flagsOk("upgrade", rest, ["--check"])) return 2;
       if (!rest.includes("--check")) {
         console.error("Only `upgrade --check` is implemented.");
         console.error(
@@ -260,6 +310,7 @@ async function main(): Promise<number> {
       return upgradeCheckExitCode(report);
     }
     case "sync": {
+      if (!flagsOk("sync", rest, ["--check", "--force"])) return 2;
       const registryDir = resolveRegistryDir(TEMPLATES_DIR);
       if (!registryDir) {
         console.error(
@@ -280,10 +331,7 @@ async function main(): Promise<number> {
             "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
-      );
+      const selection = selectItems(itemNames(rest), context);
       if (!selection.ok) {
         console.error(selection.message);
         return 1;
@@ -298,6 +346,8 @@ async function main(): Promise<number> {
       });
     }
     case "help":
+    case "--help":
+    case "-h":
       console.log(usage());
       return 0;
     default:

package/src/commands/add.ts

@@ -85,6 +85,9 @@ export function substitute(
   );
 }
 
+/** A `__NAME__` placeholder the variables did not fill. */
+const PLACEHOLDER = /__[A-Z][A-Z0-9_]*__/;
+
 const VERCEL_CONFIG = "vercel.json";
 
 /**
@@ -145,16 +148,35 @@ export function addFeature(feature: string, options: AddOptions): AddResult {
   const recorded: GeneratedFile[] = [];
   const handedOver = new Set(previous?.handedOver ?? []);
 
+  // Re-generating a feature substitutes what it was generated with, so
+  // `add app-scaffold` in an app `create` made takes the app's own name;
+  // values passed now fill in or replace them.
+  const variables =
+    previous?.variables || options.variables
+      ? { ...previous?.variables, ...options.variables }
+      : undefined;
+
+  // Checked before anything is written, so a refusal leaves no half-made
+  // feature behind.
+  for (const file of spec.files) {
+    const unfilled = substitute(
+      readFileSync(path.join(options.templatesDir, file.template), "utf8"),
+      variables
+    ).match(PLACEHOLDER);
+    if (unfilled) {
+      throw new Error(
+        `${feature} needs a value for ${unfilled[0]} that only \`intelligo create\` supplies — ` +
+          "run `intelligo create <directory>`, or `intelligo create .` in an empty one."
+      );
+    }
+  }
+
   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
-    );
-
+    const contents = substitute(readFileSync(source, "utf8"), variables);
     if (existsSync(target) && !options.force) {
       const current = hashContents(readFileSync(target, "utf8"));
       const known = previousByPath.get(file.target);
@@ -190,13 +212,7 @@ export function addFeature(feature: string, options: AddOptions): AddResult {
 
   writeManifest(
     options.appRoot,
-    recordFeature(
-      manifest,
-      feature,
-      spec.templateVersion,
-      recorded,
-      options.variables
-    )
+    recordFeature(manifest, feature, spec.templateVersion, recorded, variables)
   );
 
   return result;

package/src/commands/create-flow.ts

@@ -24,7 +24,7 @@ import {
   formatNextSteps,
   isOccupied,
 } from "./create.js";
-import { syncApply, type SyncContext } from "./sync.js";
+import { recordItems, syncApply, type SyncContext } from "./sync.js";
 import { resolveRegistryDir } from "../registry-bundle.js";
 import {
   detectPackageManager,
@@ -54,11 +54,25 @@ export type CreateFlags = {
    * range, because that is what works everywhere else.
    */
   linkWorkspace: boolean;
+  /** `--name <name>` — the project name, when it is not the directory's. */
+  name?: string;
+  /** Flags `create` does not know. */
+  unknown: string[];
 };
 
+const CREATE_FLAGS = [
+  "--all",
+  "--yes",
+  "-y",
+  "--no-install",
+  "--link-workspace",
+];
+
 export function parseCreateFlags(args: readonly string[]): CreateFlags {
   let target: string | undefined;
   let items: string[] | undefined;
+  let name: string | undefined;
+  const unknown: string[] = [];
   for (let i = 0; i < args.length; i++) {
     const arg = args[i]!;
     if (arg === "--items" || arg.startsWith("--items=")) {
@@ -67,13 +81,23 @@ export function parseCreateFlags(args: readonly string[]): CreateFlags {
         .split(",")
         .map((s) => s.trim())
         .filter(Boolean);
-    } else if (!arg.startsWith("-") && target === undefined) {
+    } else if (arg === "--name" || arg.startsWith("--name=")) {
+      const value = arg === "--name" ? args[++i] : arg.slice(7);
+      if (!value?.trim() || value.startsWith("-")) unknown.push(arg);
+      else name = value;
+    } else if (arg.startsWith("-")) {
+      if (!CREATE_FLAGS.includes(arg)) unknown.push(arg);
+    } else if (target === undefined) {
       target = arg;
+    } else {
+      unknown.push(arg);
     }
   }
   return {
     target,
     items,
+    name,
+    unknown,
     all: args.includes("--all"),
     yes: args.includes("--yes") || args.includes("-y"),
     install: !args.includes("--no-install"),
@@ -164,7 +188,7 @@ export async function runCreate(
   if (!target) {
     if (!interactive) {
       console.error(
-        "Usage: intelligo create <directory> [--items a,b | --all] [--yes] [--no-install]"
+        "Usage: intelligo create <directory> [--items a,b | --all] [--yes] [--no-install] [--name <name>]"
       );
       return 1;
     }
@@ -218,15 +242,25 @@ export async function runCreate(
     templatesDir: context.templatesDir,
     frameworkVersion: context.frameworkVersion,
     linkWorkspace: flags.linkWorkspace,
+    name: flags.name,
+    packageManager,
   });
   const appRoot = path.resolve(target);
   if (interactive) {
     p.log.success(`Scaffolded ${result.written.length} files in ${target}`);
   }
 
-  // 4. The pages — only with approval.
+  // 4. The pages — only with approval, but recorded now, so a bare
+  // `intelligo sync` installs them if this install does not.
   const workspaceRoot = findWorkspaceRoot(appRoot);
   const plan = installPlan(items, { appRoot, packageManager, workspaceRoot });
+  if (plan) {
+    recordItems(plan.items, {
+      appRoot,
+      requires: catalogue.requires,
+      frameworkVersion: context.frameworkVersion,
+    });
+  }
   const commands: Command[] = plan
     ? [...(plan.install ? [plan.install] : []), plan.sync]
     : [];

package/src/commands/create.ts

@@ -20,8 +20,14 @@
 import { existsSync, mkdirSync, readdirSync } from "node:fs";
 import path from "node:path";
 
-import { addFeature, formatAddResult, type AddResult } from "./add.js";
 import {
+  addFeature,
+  formatAddResult,
+  readCatalogue,
+  type AddResult,
+} from "./add.js";
+import {
+  findWorkspaceRoot,
   formatCommand,
   type Command,
   type PackageManager,
@@ -39,6 +45,15 @@ export type CreateOptions = {
    * protocol used outside a workspace".
    */
   linkWorkspace?: boolean;
+  /** The project name, when it is not the directory's. */
+  name?: string;
+  /**
+   * The package manager that will install the app. Under pnpm, an app
+   * outside any workspace also gets `pnpm-standalone`: its own
+   * workspace file declining the dependency build scripts pnpm 10+
+   * would otherwise stop the install over.
+   */
+  packageManager?: PackageManager;
 };
 
 /** A package name and product slug derived from the directory name. */
@@ -57,17 +72,23 @@ export function deriveNames(target: string): {
   return { appName: slug, appSlug: slug };
 }
 
+/** A fresh repository — `git init`, then `intelligo create .` — is still empty. */
+const IGNORED_ENTRIES = new Set([".git"]);
+
 export function isOccupied(target: string): boolean {
   const dir = path.resolve(target);
-  return existsSync(dir) && readdirSync(dir).length > 0;
+  return (
+    existsSync(dir) &&
+    readdirSync(dir).some((entry) => !IGNORED_ENTRIES.has(entry))
+  );
 }
 
 /** Scaffolding into an occupied directory is how people lose work. */
 export function assertNotOccupied(target: string): void {
   if (isOccupied(target)) {
     throw new Error(
-      `${path.resolve(target)} is not empty. Create the app in a new directory, or use ` +
-        `\`intelligo add app-scaffold\` inside an existing one.`
+      `${path.resolve(target)} is not empty. Create the app in a new directory, ` +
+        "or in an empty one (a .git directory may already be there)."
     );
   }
 }
@@ -76,11 +97,13 @@ export function createApp(options: CreateOptions): AddResult {
   const target = path.resolve(options.target);
 
   assertNotOccupied(target);
+  // Before the directory exists, so a name that slugifies to nothing
+  // leaves nothing behind.
+  const { appName, appSlug } = deriveNames(options.name || target);
   mkdirSync(target, { recursive: true });
+  const workspaceRoot = findWorkspaceRoot(target);
 
-  const { appName, appSlug } = deriveNames(target);
-
-  return addFeature("app-scaffold", {
+  const scaffold = addFeature("app-scaffold", {
     appRoot: target,
     templatesDir: options.templatesDir,
     frameworkVersion: options.frameworkVersion,
@@ -90,8 +113,43 @@ export function createApp(options: CreateOptions): AddResult {
       __INTELLIGO_DEP__: options.linkWorkspace
         ? "workspace:*"
         : `^${options.frameworkVersion}`,
+      ...workspaceRootVariable(target),
     },
   });
+
+  // A member of a parent workspace installs from that root; a workspace
+  // file of its own would take it out of it.
+  const standalone =
+    options.packageManager === "pnpm" &&
+    workspaceRoot === null &&
+    STANDALONE in readCatalogue(options.templatesDir);
+  if (!standalone) return scaffold;
+
+  const pnpm = addFeature(STANDALONE, {
+    appRoot: target,
+    templatesDir: options.templatesDir,
+    frameworkVersion: options.frameworkVersion,
+  });
+  return { ...scaffold, written: [...scaffold.written, ...pnpm.written] };
+}
+
+const STANDALONE = "pnpm-standalone";
+
+/**
+ * `__WORKSPACE_ROOT__` for the scaffold's next.config: a JavaScript
+ * literal naming the enclosing pnpm workspace's root relative to the
+ * app, or null when the app is not a member of one — the rule `doctor`
+ * and `migrate` load env files by.
+ */
+export function workspaceRootVariable(target: string): Record<string, string> {
+  const root = findWorkspaceRoot(path.resolve(target));
+  return {
+    __WORKSPACE_ROOT__: root
+      ? JSON.stringify(
+          path.relative(path.resolve(target), root).split(path.sep).join("/")
+        )
+      : "null",
+  };
 }
 
 export type NextSteps = {

package/src/commands/doctor.ts

@@ -41,6 +41,8 @@ type ItemRequires = {
 
 export type RegistryRequires = {
   scaffold: string[];
+  /** Files an item ships once and the deployment then owns. */
+  seams?: Record<string, string>;
   items: Record<string, ItemRequires>;
 };
 
@@ -256,6 +258,103 @@ function checkModelIds(root: string, source: string): CheckResult[] {
 const OPAQUE_REGISTRATION =
   /\bregisterModels?\s*\(\s*(?![\s[{]|DEFAULT_MODELS\s*[,)])/;
 
+/**
+ * A seam's feature keys are the deployment's own choice, so they are
+ * not an item requirement; a literal key the app's copy still names but
+ * lib/plans.ts does not register is worth a warning.
+ */
+function checkSeamFeatures(
+  root: string,
+  seams: Record<string, string> | undefined,
+  plans: ReturnType<typeof reexportedSource> | null
+): CheckResult[] {
+  if (!plans || plans.unresolved.length) return [];
+  const results: CheckResult[] = [];
+  for (const seam of Object.keys(seams ?? {})) {
+    const abs = path.join(root, seam);
+    if (!existsSync(abs)) continue;
+    const keys = new Set(
+      [
+        ...readFileSync(abs, "utf8").matchAll(
+          /featureKey:\s*["']([^"']+)["']/g
+        ),
+      ].map((m) => m[1]!)
+    );
+    const unregistered = [...keys].filter(
+      (key) => !hasObjectKey(plans.text, key)
+    );
+    if (unregistered.length === 0) continue;
+    results.push({
+      name: `seam:${seam}`,
+      status: "warn",
+      detail: `${unregistered.map((key) => `"${key}"`).join(", ")} ${unregistered.length === 1 ? "is" : "are"} not registered in lib/plans.ts — a gate on an unregistered key is denied (403)`,
+    });
+  }
+  return results;
+}
+
+const VITEST_CONFIGS = [
+  "vitest.config.ts",
+  "vitest.config.mts",
+  "vitest.config.cts",
+  "vitest.config.js",
+  "vitest.config.mjs",
+  "vitest.config.cjs",
+];
+
+/** `PRODUCT_SLUG = "acme"` or `setDefaultProductSlug("acme")` in the composition root. */
+const PRODUCT_SLUG_LITERAL =
+  /(?:\bPRODUCT_SLUG\s*=|\bsetDefaultProductSlug\s*\()\s*["'`]([^"'`]+)["'`]/;
+
+function checkBillingProduct(
+  fromEnv: string | undefined,
+  rootSource: string | null
+): CheckResult {
+  const setsDefault =
+    rootSource !== null && /\bsetDefaultProductSlug\s*\(/.test(rootSource);
+  const inCode = rootSource?.match(PRODUCT_SLUG_LITERAL)?.[1];
+  if (fromEnv && setsDefault && inCode && fromEnv !== inCode) {
+    return {
+      name: "billing",
+      status: "warn",
+      detail:
+        `INTELLIGO_BILLING_PRODUCT is "${fromEnv}" but the composition root sets "${inCode}". ` +
+        "At runtime the composition root wins; the variable only misleads tooling that reads it — make them agree",
+    };
+  }
+  if (fromEnv) {
+    return { name: "billing", status: "ok", detail: `Product: ${fromEnv}` };
+  }
+  if (setsDefault) {
+    return {
+      name: "billing",
+      status: "ok",
+      detail: `Product: ${inCode ?? "set"} by setDefaultProductSlug() in the composition root`,
+    };
+  }
+  return {
+    name: "billing",
+    status: "warn",
+    detail:
+      "no product — set INTELLIGO_BILLING_PRODUCT, or call setDefaultProductSlug() " +
+      "in the composition root, or plan lookups resolve to nothing",
+  };
+}
+
+/**
+ * Whether `name` is installed where the app resolves packages from: its
+ * own node_modules or any directory above it, a workspace root's
+ * included.
+ */
+function resolvesFrom(root: string, name: string): boolean {
+  for (let dir = path.resolve(root); ; dir = path.dirname(dir)) {
+    if (existsSync(path.join(dir, "node_modules", name, "package.json"))) {
+      return true;
+    }
+    if (path.dirname(dir) === dir) return false;
+  }
+}
+
 export function runChecks(options: DoctorOptions = {}): CheckResult[] {
   const root = options.root ?? process.cwd();
   const env = options.env ?? process.env;
@@ -294,22 +393,15 @@ export function runChecks(options: DoctorOptions = {}): CheckResult[] {
 
   // 3. Billing product. The engine has no built-in default catalogue;
   //    an unset product means every plan lookup returns nothing and
-  //    quotas silently read as zero.
-  results.push(
-    env.INTELLIGO_BILLING_PRODUCT
-      ? {
-          name: "billing",
-          status: "ok",
-          detail: `Product: ${env.INTELLIGO_BILLING_PRODUCT}`,
-        }
-      : {
-          name: "billing",
-          status: "warn",
-          detail:
-            "INTELLIGO_BILLING_PRODUCT unset — the composition root must call " +
-            "setDefaultProductSlug(), or plan lookups resolve to nothing",
-        }
-  );
+  //    quotas silently read as zero. The composition root sets it at
+  //    boot; the variable lets tooling see it without booting.
+  const compositionRoot = ["lib/intelligo.ts", "lib/intelligo.tsx"]
+    .map((rel) => path.join(root, rel))
+    .find((file) => existsSync(file));
+  const rootSource = compositionRoot
+    ? stripComments(readFileSync(compositionRoot, "utf8"))
+    : null;
+  results.push(checkBillingProduct(env.INTELLIGO_BILLING_PRODUCT, rootSource));
 
   // 4. Installed registry items against registry/requires.json: the
   //    sibling items they import from, the scaffold files they import,
@@ -383,6 +475,8 @@ export function runChecks(options: DoctorOptions = {}): CheckResult[] {
             }
       );
     }
+
+    results.push(...checkSeamFeatures(root, requires.seams, plans));
   }
 
   // 4b. Maintenance route. It refuses to serve without a strong
@@ -428,10 +522,6 @@ export function runChecks(options: DoctorOptions = {}): CheckResult[] {
   //     admission with no price to estimate against: every request is
   //     refused with `unknown_model`, at runtime, on a deployment whose
   //     only mistake was omitting one line.
-  const compositionRoot = ["lib/intelligo.ts", "lib/intelligo.tsx"]
-    .map((rel) => path.join(root, rel))
-    .find((file) => existsSync(file));
-
   if (compositionRoot) {
     const source = readFileSync(compositionRoot, "utf8");
     const registers = /\bregisterModels?\s*\(/.test(stripComments(source));
@@ -456,6 +546,25 @@ export function runChecks(options: DoctorOptions = {}): CheckResult[] {
     if (registers) results.push(...checkModelIds(root, source));
   }
 
+  // 4e. A test config whose runner is not installed fails at the first
+  //     `vitest run`, with a module error that does not say why.
+  const vitestConfig = VITEST_CONFIGS.find((file) =>
+    existsSync(path.join(root, file))
+  );
+  if (vitestConfig) {
+    results.push(
+      resolvesFrom(root, "vitest")
+        ? { name: "tests", status: "ok", detail: "vitest is installed" }
+        : {
+            name: "tests",
+            status: "warn",
+            detail:
+              `${vitestConfig} is here but vitest does not resolve from the app — ` +
+              "`pnpm add -D vitest`",
+          }
+    );
+  }
+
   // 5. Generated source. A conflict — template and consumer both
   //    moved — is the one state an upgrade cannot resolve on its own.
   const manifest = readManifest(root);