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

package/src/commands/create-flow.ts

@@ -1,7 +1,10 @@
 /**
  * The conversation around `createApp`: ask what the flags did not say,
  * scaffold, and install the chosen registry items once the developer
- * has approved the commands that do it.
+ * has approved the commands that do it. The items go in through
+ * `intelligo sync` — one `shadcn add` per item from the registry this
+ * CLI carries, recorded in the manifest — exactly as a later sync
+ * would put them back.
  *
  * Nothing runs on the developer's machine without their say-so. In a
  * terminal the commands are shown and confirmed; without one (CI, a
@@ -21,15 +24,18 @@ import {
   formatNextSteps,
   isOccupied,
 } from "./create.js";
+import { recordItems, syncApply, type SyncContext } from "./sync.js";
+import { resolveRegistryDir } from "../registry-bundle.js";
 import {
   detectPackageManager,
+  findWorkspaceRoot,
   formatCommand,
-  hasLocalShadcn,
   installPlan,
   readRegistryCatalogue,
   shortDescription,
   withDependencies,
   type Command,
+  type InstallPlan,
 } from "../registry-items.js";
 
 export type CreateFlags = {
@@ -48,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=")) {
@@ -61,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"),
@@ -97,6 +127,47 @@ function run(c: Command, cwd: string): boolean {
   return result.status === 0;
 }
 
+/**
+ * Run the plan: the dependency install, then the sync. Returns the
+ * commands still to run by hand — none when both succeeded.
+ */
+async function installPages(
+  plan: InstallPlan,
+  options: {
+    appRoot: string;
+    interactive: boolean;
+    show: (c: Command) => string;
+    syncContext: SyncContext;
+  }
+): Promise<Command[]> {
+  const { appRoot, interactive, show } = options;
+  const say = (line: string) =>
+    interactive ? p.log.step(line) : console.log(line);
+  const fail = (message: string) =>
+    interactive ? p.log.error(message) : console.error(message);
+  if (plan.install) {
+    say(`› ${show(plan.install)}`);
+    if (!run(plan.install, plan.install.cwd ?? appRoot)) {
+      fail(
+        `\`${show(plan.install)}\` failed — the scaffold is in place; run the rest by hand.`
+      );
+      return [plan.install, plan.sync];
+    }
+  }
+  say(`› ${show(plan.sync)}`);
+  const code = await syncApply(plan.items, options.syncContext, {
+    force: true,
+    log: say,
+  });
+  if (code !== 0) {
+    fail(
+      "The pages did not all install — the scaffold is in place; re-run the sync by hand."
+    );
+    return [plan.sync];
+  }
+  return [];
+}
+
 export async function runCreate(
   flags: CreateFlags,
   context: {
@@ -117,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;
     }
@@ -171,21 +242,41 @@ 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.
-  const plan = installPlan(items, { appRoot, packageManager });
-  let approved = plan.length > 0 && flags.install && flags.yes;
-  if (plan.length > 0 && flags.install && !flags.yes && interactive) {
-    const needsInstall = !hasLocalShadcn(appRoot);
-    p.note(plan.map(formatCommand).join("\n"), "Commands to run in " + target);
+  // 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]
+    : [];
+  const show = (c: Command) => formatCommand(c, appRoot);
+  const registryDir = resolveRegistryDir(context.templatesDir);
+  if (plan && flags.install && !registryDir) {
+    console.error(
+      "This CLI has no bundled registry to install pages from — in the framework repository, run `pnpm registry:build` first."
+    );
+  }
+  let approved = plan !== null && flags.install && flags.yes && !!registryDir;
+  if (plan && flags.install && registryDir && !flags.yes && interactive) {
+    p.note(commands.map(show).join("\n"), "Commands to run in " + target);
     const answer = await p.confirm({
-      message: needsInstall
-        ? `shadcn is not installed yet — install the dependencies (shadcn included) with ${packageManager} and add ${items.length} page(s)?`
+      message: plan.install
+        ? `shadcn is not installed yet — install the dependencies (shadcn included) with ${plan.install.command}${workspaceRoot ? " from the workspace root" : ""} and add ${items.length} page(s)?`
         : `Add ${items.length} page(s) with shadcn?`,
     });
     if (bail(answer, `The scaffold is in ${target}; nothing was installed.`))
@@ -193,27 +284,26 @@ export async function runCreate(
     approved = answer;
   }
 
-  let pending: Command[] = [];
-  if (approved) {
-    for (const [i, command] of plan.entries()) {
-      if (interactive) p.log.step(formatCommand(command));
-      else console.log(`› ${formatCommand(command)}`);
-      if (!run(command, appRoot)) {
-        pending = plan.slice(i);
-        const message = `\`${formatCommand(command)}\` failed — the scaffold is in place; run the rest by hand.`;
-        if (interactive) p.log.error(message);
-        else console.error(message);
-        break;
-      }
-    }
-  } else {
-    pending = plan;
-  }
+  const pending =
+    approved && plan && registryDir
+      ? await installPages(plan, {
+          appRoot,
+          interactive,
+          show,
+          syncContext: {
+            appRoot,
+            registryDir,
+            requires: catalogue.requires,
+            frameworkVersion: context.frameworkVersion,
+          },
+        })
+      : commands;
 
   const next = {
-    packageManager,
+    packageManager: workspaceRoot ? ("pnpm" as const) : packageManager,
     installed: approved && pending.length === 0,
     pending,
+    workspaceRoot,
   };
   if (interactive) {
     p.note(formatNextSteps(target, next), "Next");

package/src/commands/create.ts

@@ -9,17 +9,25 @@
  *
  * In a terminal it asks for the project name when none is given, then
  * which registry pages to install (`--items a,b` or `--all` answer that
- * without asking). The pages are installed by the shadcn CLI the scaffold
- * declares, after the dependencies — and only once you approve the exact
- * commands, or pass `--yes`. `--no-install` stops after the scaffold and
- * prints them instead.
+ * without asking). The pages are installed by `intelligo sync` — one
+ * `shadcn add` per item, from the registry this CLI carries — after the
+ * dependencies (from the root of a parent pnpm workspace when the app is
+ * a member of one), and only once you approve the exact commands, or
+ * pass `--yes`. `--no-install` stops after the scaffold and prints them
+ * instead.
  */
 
 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,
@@ -37,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. */
@@ -55,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)."
     );
   }
 }
@@ -74,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,
@@ -88,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 = {
@@ -98,6 +158,8 @@ export type NextSteps = {
   installed: boolean;
   /** Install commands the developer declined, or that did not get to run. */
   pending?: Command[];
+  /** The parent pnpm workspace the app is a member of, installed from its root. */
+  workspaceRoot?: string | null;
 };
 
 /** A path the reader can paste into a shell, spaces and quotes included. */
@@ -109,14 +171,20 @@ function shellQuote(value: string): string {
 
 export function formatNextSteps(target: string, next: NextSteps): string {
   const pm = next.packageManager;
+  const appRoot = path.resolve(target);
+  const install: Command = {
+    command: pm,
+    args: ["install"],
+    cwd: next.workspaceRoot ?? appRoot,
+  };
   return [
-    `cd ${shellQuote(path.relative(process.cwd(), path.resolve(target)) || ".")}`,
+    `cd ${shellQuote(path.relative(process.cwd(), appRoot) || ".")}`,
     "cp .env.example .env.local   # then fill it in",
     ...(next.pending?.length
-      ? next.pending.map(formatCommand)
+      ? next.pending.map((c) => formatCommand(c, appRoot))
       : next.installed
         ? []
-        : [`${pm} install`]),
+        : [formatCommand(install, appRoot)]),
     `${pm === "npm" ? "npm run" : pm} dev`,
   ].join("\n");
 }

package/src/commands/doctor.ts

@@ -10,6 +10,12 @@ import { parseEnv } from "node:util";
 
 import { inspectMigrationChain, readMigrationChain } from "../migrations.js";
 import { readManifest } from "../manifest.js";
+import {
+  checkExports,
+  hasObjectKey,
+  reexportedSource,
+  stripComments,
+} from "../module-exports.js";
 import {
   MODEL_CATALOGUE_LOCATIONS,
   readCatalogueModelIds,
@@ -35,20 +41,11 @@ 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>;
 };
 
-/**
- * Block and line comments removed, so a check cannot be satisfied — or
- * defeated — by prose. The composition root's own doc comment names
- * `registerModels` in several of the templates.
- */
-function stripComments(text: string): string {
-  return text
-    .replace(/\/\*[\s\S]*?\*\//g, "")
-    .replace(/(^|[^:])\/\/.*$/gm, "$1");
-}
-
 /**
  * templates/registry-requires.json is a build-time copy of
  * packages/registry/requires.json (scripts/sync-registry-requires.mjs),
@@ -261,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;
@@ -299,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,
@@ -328,13 +415,17 @@ export function runChecks(options: DoctorOptions = {}): CheckResult[] {
       [".ts", ".tsx", ".js", ".jsx", ".json", ""].some((ext) =>
         existsSync(path.join(root, rel + ext))
       );
-    const plansSource = existsSync(path.join(root, "lib/plans.ts"))
-      ? readFileSync(path.join(root, "lib/plans.ts"), "utf8")
-      : null;
+    // lib/plans.ts and whatever it re-exports — a catalogue defined in
+    // a workspace package counts — comments stripped.
+    const plansFile = ["lib/plans.ts", "lib/plans.tsx"]
+      .map((rel) => path.join(root, rel))
+      .find((file) => existsSync(file));
+    const plans = plansFile ? reexportedSource(plansFile, root) : null;
 
     for (const [name, item] of Object.entries(requires.items)) {
       if (!existsSync(path.join(root, item.marker))) continue;
       const problems: string[] = [];
+      const notes: string[] = [];
 
       for (const dep of item.items ?? []) {
         const marker = requires.items[dep]?.marker;
@@ -350,23 +441,22 @@ export function runChecks(options: DoctorOptions = {}): CheckResult[] {
           .map((ext) => path.join(root, file + ext))
           .find((p) => existsSync(p));
         if (!abs) continue; // reported above as a missing file
-        const source = readFileSync(abs, "utf8");
-        const missing = names.filter(
-          (n) =>
-            !new RegExp(
-              `export\\s+(?:default\\s+)?(?:async\\s+)?(?:const|function\\*?|let|var|class)\\s+${n}\\b`
-            ).test(source) &&
-            !new RegExp(`export\\s*\\{[^}]*\\b${n}\\b`).test(source)
-        );
+        const { missing, unresolved } = checkExports(abs, names, root);
         if (missing.length) {
           problems.push(`${file} must export ${missing.join(", ")}`);
+        } else if (unresolved.length) {
+          notes.push(
+            `${file}: could not read ${unresolved.map((u) => `\`export * from "${u}"\``).join(", ")} — assumed to provide ${names.join(", ")}`
+          );
         }
       }
       for (const feature of item.features ?? []) {
-        if (
-          plansSource !== null &&
-          !new RegExp(`\\b${feature}\\b\\s*:`).test(plansSource)
-        ) {
+        if (!plans || hasObjectKey(plans.text, feature)) continue;
+        if (plans.unresolved.length) {
+          notes.push(
+            `the "${feature}" feature key is not in lib/plans.ts, and ${plans.unresolved.join(", ")} could not be read to confirm it`
+          );
+        } else {
           problems.push(
             `register the "${feature}" feature key in lib/plans.ts — an unregistered key is denied (403)`
           );
@@ -375,7 +465,9 @@ export function runChecks(options: DoctorOptions = {}): CheckResult[] {
 
       results.push(
         problems.length === 0
-          ? { name: `item:${name}`, status: "ok", detail: "requirements met" }
+          ? notes.length === 0
+            ? { name: `item:${name}`, status: "ok", detail: "requirements met" }
+            : { name: `item:${name}`, status: "warn", detail: notes.join("; ") }
           : {
               name: `item:${name}`,
               status: "error",
@@ -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);