@topogram/cli 0.3.73 → 0.3.75

package/src/generator/runtime/environment/index.js

@@ -43,7 +43,7 @@ function buildEnvironmentPlan(graph, options = {}) {
   const runtimeReference = runtimeReferenceFor(graph, options);
   const topology = resolveRuntimeTopology(graph, options);
   const { apiProjection, uiProjection, dbProjection } = getDefaultEnvironmentProjections(graph, options);
-  const dbLifecycle = dbProjection ? generateDbLifecyclePlan(graph, { ...options, projectionId: dbProjection.id }) : null;
+  const dbLifecycle = dbProjection ? generateDbLifecyclePlan(graph, { ...options, projectionId: dbProjection.id, runtime: topology.primaryDb || undefined }) : null;
   const dbEngine = dbLifecycle?.engine || null;
   const profile = options.profileId || (dbEngine === "sqlite" || !dbProjection ? "local_process" : "local_docker");
   const usesDocker = profile === "local_docker";
@@ -67,7 +67,8 @@ function buildEnvironmentPlan(graph, options = {}) {
         generator: runtime.generator,
         port: runtime.port ?? null,
         uses_api: runtime.api || null,
-        uses_database: runtime.database || null
+        uses_database: runtime.database || null,
+        ...(runtime.kind === "database" && runtime.migration ? { migration: runtime.migration } : {})
       }))
     },
     projections: {
@@ -145,7 +146,8 @@ function buildEnvironmentPlan(graph, options = {}) {
         engine: component.id === topology.primaryDb?.id ? dbEngine : null,
         port: component.port,
         dir: topology.dbDir(component),
-        env: dbEnvVarsForComponent(component, { primary: component.id === topology.primaryDb?.id })
+        env: dbEnvVarsForComponent(component, { primary: component.id === topology.primaryDb?.id }),
+        ...(component.migration ? { migration: component.migration } : {})
       }))
     },
     ports: {
@@ -329,7 +331,8 @@ ${dockerSection}
 - ${hasWeb && hasApi ? "The generated web app talks to `PUBLIC_TOPOGRAM_API_BASE_URL`." : hasWeb ? "The generated web app is standalone." : "No web surface is generated."}
 - ${hasNative ? "Native app scaffolds use the same UI surface contracts as web surfaces." : "No native surface is generated."}
 - If \`.env\` is missing, generated scripts fall back to \`.env.example\`.
-- The DB lifecycle scripts remain the source of truth for greenfield bootstrap and brownfield migration.
+- Generated-owned DB lifecycle scripts remain the source of truth for greenfield bootstrap and generated migrations.
+- Maintained DB lifecycle scripts emit proposals only and never apply migrations.
 `;
 }
 
@@ -349,6 +352,10 @@ function renderEnvironmentBootstrapDbScript(plan) {
     return `(cd "$ROOT_DIR/${component.dir}" && TOPOGRAM_ENV_FILE=/dev/null ${assignments} bash ./scripts/db-bootstrap-or-migrate.sh)`;
   });
   const primaryApi = plan.runtimes.apis[0];
+  const primaryApiDatabase = primaryApi?.uses_database
+    ? plan.runtimes.databases.find((component) => component.id === primaryApi.uses_database)
+    : null;
+  const seedAllowed = Boolean(primaryApi?.uses_database) && primaryApiDatabase?.migration?.ownership !== "maintained";
   if (plan.runtimes.databases.length === 0) {
     return renderEnvAwareShellScript([
       'echo "No database runtimes are configured; skipping DB bootstrap."'
@@ -366,9 +373,11 @@ function renderEnvironmentBootstrapDbScript(plan) {
     ...dbBootstrapLines,
     'if [[ "${TOPOGRAM_SEED_DEMO:-true}" != "false" ]]; then',
     ...apiDatabaseExportLines(primaryApi),
-    ...(primaryApi?.uses_database
+    ...(seedAllowed
       ? [`(cd "$ROOT_DIR/${primaryApi.dir}" && npm install && npm exec -- prisma generate --schema prisma/schema.prisma && npm exec -- prisma db push --schema prisma/schema.prisma --skip-generate && npm run seed:demo)`]
-      : ['echo "No DB-backed API component is configured; skipping demo seed."']),
+      : [primaryApi?.uses_database
+        ? 'echo "Primary API uses a maintained database runtime; skipping generated demo seed."'
+        : 'echo "No DB-backed API component is configured; skipping demo seed."']),
     "fi"
   ]);
 }

package/src/generator/runtime/shared/index.js

@@ -27,6 +27,7 @@ import { defaultProjectConfigForGraph, validateProjectConfig } from "../../../pr
  * @property {string|null} [api]
  * @property {string|null} [database]
  * @property {Record<string, string>} [env]
+ * @property {import("../../../project-config.js").RuntimeMigrationStrategy} [migration]
  * @property {RuntimeComponent|null} [apiRuntime]
  * @property {RuntimeComponent|null} [databaseRuntime]
  * @property {RuntimeComponent|null} [apiComponent] Legacy adapter alias for apiRuntime.

package/src/generator/surfaces/databases/lifecycle-shared.js

@@ -17,11 +17,65 @@ function defaultInputPathForGraph(graph, options = {}) {
   return ".";
 }
 
+function runtimeMigrationStrategyForProjection(projection, options = {}) {
+  const projectionId = projection?.id || options.projectionId || null;
+  const runtime = options.runtime || options.component || null;
+  if (runtime?.kind === "database" && runtime?.migration && (!projectionId || runtime.projection?.id === projectionId || runtime.projection === projectionId)) {
+    return runtime.migration;
+  }
+
+  const topologyRuntime = (options.topology?.dbRuntimes || options.topology?.runtimes || [])
+    .find((entry) => entry?.kind === "database" && entry?.migration && (entry.projection?.id === projectionId || entry.projection === projectionId));
+  if (topologyRuntime?.migration) {
+    return topologyRuntime.migration;
+  }
+
+  const configRuntime = (options.projectConfig?.topology?.runtimes || [])
+    .find((entry) => entry?.kind === "database" && entry?.migration && entry.projection === projectionId);
+  return configRuntime?.migration || null;
+}
+
+function normalizeMigrationStrategy(strategy) {
+  if (!strategy) {
+    return {
+      ownership: "generated",
+      tool: "sql",
+      apply: "script",
+      statePath: null,
+      snapshotPath: null,
+      schemaPath: null,
+      migrationsPath: null,
+      defaulted: true
+    };
+  }
+  return {
+    ownership: strategy.ownership || "generated",
+    tool: strategy.tool || "sql",
+    apply: strategy.apply || (strategy.ownership === "maintained" ? "never" : "script"),
+    statePath: strategy.statePath || null,
+    snapshotPath: strategy.snapshotPath || null,
+    schemaPath: strategy.schemaPath || null,
+    migrationsPath: strategy.migrationsPath || null,
+    defaulted: false
+  };
+}
+
+function pathJoinPosix(...parts) {
+  return parts.filter(Boolean).join("/").replace(/\/+/g, "/");
+}
+
 function dbLifecyclePlan(graph, projection, options = {}) {
   const contract = buildDbProjectionContract(graph, projection);
   const snapshot = normalizeDbSchemaSnapshot(contract);
   const engine = snapshot.engine;
   const ormProfiles = engine === "postgres" ? ["prisma", "drizzle"] : ["prisma"];
+  const migrationStrategy = normalizeMigrationStrategy(runtimeMigrationStrategyForProjection(projection, options));
+  const generatedStateRoot = migrationStrategy.statePath || "state";
+  const proposalStateRoot = "state";
+  const stateRoot = migrationStrategy.ownership === "generated" ? generatedStateRoot : proposalStateRoot;
+  const currentSnapshot = migrationStrategy.ownership === "maintained" && migrationStrategy.snapshotPath
+    ? migrationStrategy.snapshotPath
+    : pathJoinPosix(stateRoot, "current.snapshot.json");
 
   return {
     type: "db_lifecycle_plan",
@@ -31,19 +85,26 @@ function dbLifecyclePlan(graph, projection, options = {}) {
     ormProfiles,
     runtimeProfile: ormProfiles.includes("prisma") ? "prisma" : null,
     inputPath: defaultInputPathForGraph(graph, options),
+    migrationStrategy,
     state: {
-      currentSnapshot: "state/current.snapshot.json",
-      desiredSnapshot: "state/desired.snapshot.json",
-      migrationPlan: "state/migration.plan.json",
-      migrationSql: "state/migration.sql"
+      root: stateRoot,
+      currentSnapshot,
+      desiredSnapshot: pathJoinPosix(stateRoot, "desired.snapshot.json"),
+      migrationPlan: pathJoinPosix(stateRoot, "migration.plan.json"),
+      migrationSql: pathJoinPosix(stateRoot, "migration.sql")
     },
     bundle: {
       emptySnapshot: "snapshots/empty.snapshot.json",
       prismaSchema: ormProfiles.includes("prisma") ? "prisma/schema.prisma" : null,
       drizzleSchema: engine === "postgres" ? "drizzle/schema.ts" : null
     },
+    proposals: {
+      schemaPath: migrationStrategy.schemaPath,
+      migrationsPath: migrationStrategy.migrationsPath,
+      snapshotPath: migrationStrategy.snapshotPath
+    },
     environment: {
-      required: ["DATABASE_URL"],
+      required: migrationStrategy.ownership === "maintained" ? [] : ["DATABASE_URL"],
       optional:
         engine === "postgres"
           ? ["DATABASE_ADMIN_URL", "TOPOGRAM_BIN", "TOPOGRAM_INPUT_PATH", "TOPOGRAM_DB_STATE_DIR"]
@@ -75,6 +136,14 @@ function dbLifecyclePlan(graph, projection, options = {}) {
         "persist desired snapshot as current"
       ],
       safety: "manual migration required plans are never auto-applied"
+    },
+    behavior: {
+      ownership: migrationStrategy.ownership,
+      tool: migrationStrategy.tool,
+      apply: migrationStrategy.apply,
+      appliesMigrations: migrationStrategy.ownership === "generated" && migrationStrategy.apply === "script",
+      writesGeneratedState: migrationStrategy.ownership === "generated",
+      proposalOnly: migrationStrategy.ownership === "maintained"
     }
   };
 }
@@ -108,10 +177,28 @@ function renderDbLifecycleEnvExample(projection, plan) {
 }
 
 function renderDbLifecycleReadme(plan) {
+  const proposalLines = [
+    plan.proposals.snapshotPath ? `- Current snapshot source: \`${plan.proposals.snapshotPath}\`` : null,
+    plan.proposals.schemaPath ? `- Maintained schema path: \`${plan.proposals.schemaPath}\`` : null,
+    plan.proposals.migrationsPath ? `- Maintained migrations path: \`${plan.proposals.migrationsPath}\`` : null
+  ].filter(Boolean).join("\n");
+  const modeText = plan.behavior.proposalOnly
+    ? `Maintained proposal mode. Topogram emits desired snapshots, migration plans, SQL proposals, and schema proposals, but these scripts do not apply migrations to the database. A human or agent must adapt accepted proposals into the maintained migration system.`
+    : `Generated apply mode. Topogram owns this lifecycle bundle and scripts may apply supported generated SQL migrations. Unsupported or destructive migration plans stop for manual review.`;
   return `# ${plan.projection.name} Lifecycle
 
 This bundle gives agents a repeatable database workflow for projection \`${plan.projection.id}\`.
 
+## Migration Strategy
+
+- Ownership: \`${plan.migrationStrategy.ownership}\`
+- Tool: \`${plan.migrationStrategy.tool}\`
+- Apply: \`${plan.migrationStrategy.apply}\`
+- Defaulted: \`${plan.migrationStrategy.defaulted ? "yes" : "no"}\`
+
+${modeText}
+${proposalLines ? `\n${proposalLines}\n` : ""}
+
 ## Modes
 
 - Greenfield: run \`./scripts/db-bootstrap-or-migrate.sh\` with no current snapshot
@@ -143,6 +230,12 @@ ${plan.environment.optional.map((name) => `- \`${name}\``).join("\n")}
 
 function renderDbLifecycleCommonScript(plan) {
   const engine = plan.engine;
+  const configuredStatePath = plan.migrationStrategy.ownership === "generated" && plan.migrationStrategy.statePath
+    ? plan.migrationStrategy.statePath
+    : "";
+  const configuredSnapshotPath = plan.migrationStrategy.ownership === "maintained" && plan.migrationStrategy.snapshotPath
+    ? plan.migrationStrategy.snapshotPath
+    : "";
   return `#!/usr/bin/env bash
 set -euo pipefail
 
@@ -219,9 +312,24 @@ discover_input_path() {
 }
 TOPOGRAM_BIN="$(find_topogram_bin)"
 INPUT_PATH="$(discover_input_path)"
+if [[ -f "$INPUT_PATH/topogram.project.json" ]]; then
+  PROJECT_ROOT="$INPUT_PATH"
+else
+  PROJECT_ROOT="$(cd "$INPUT_PATH/.." && pwd)"
+fi
 PROJECTION_ID="${plan.projection.id}"
-STATE_DIR="\${TOPOGRAM_DB_STATE_DIR:-$BUNDLE_DIR/state}"
-CURRENT_SNAPSHOT="$STATE_DIR/current.snapshot.json"
+CONFIGURED_STATE_PATH=${JSON.stringify(configuredStatePath)}
+CONFIGURED_SNAPSHOT_PATH=${JSON.stringify(configuredSnapshotPath)}
+if [[ -n "$CONFIGURED_STATE_PATH" ]]; then
+  STATE_DIR="\${TOPOGRAM_DB_STATE_DIR:-$PROJECT_ROOT/$CONFIGURED_STATE_PATH}"
+else
+  STATE_DIR="\${TOPOGRAM_DB_STATE_DIR:-$BUNDLE_DIR/state}"
+fi
+if [[ -n "$CONFIGURED_SNAPSHOT_PATH" ]]; then
+  CURRENT_SNAPSHOT="$PROJECT_ROOT/$CONFIGURED_SNAPSHOT_PATH"
+else
+  CURRENT_SNAPSHOT="$STATE_DIR/current.snapshot.json"
+fi
 DESIRED_SNAPSHOT="$STATE_DIR/desired.snapshot.json"
 PLAN_JSON="$STATE_DIR/migration.plan.json"
 MIGRATION_SQL="$STATE_DIR/migration.sql"
@@ -429,7 +537,7 @@ ${engine === "sqlite" ? `  normalize_sqlite_database_url
 `;
 }
 
-function renderDbStatusScript() {
+function renderDbStatusScript(plan) {
   return `#!/usr/bin/env bash
 set -euo pipefail
 . "$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)/db-common.sh"
@@ -440,11 +548,26 @@ if [[ -f "$CURRENT_SNAPSHOT" ]]; then
   generate_migration_plan "$CURRENT_SNAPSHOT"
   cat "$PLAN_JSON"
 else
-  echo '{"mode":"greenfield","currentSnapshot":null}'
+  echo ${JSON.stringify(plan.behavior.proposalOnly ? '{"mode":"maintained_proposal","currentSnapshot":null}' : '{"mode":"greenfield","currentSnapshot":null}')}
 fi
 `;
 }
 
+function renderMaintainedDbBootstrapScript() {
+  return `#!/usr/bin/env bash
+set -euo pipefail
+. "$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)/db-common.sh"
+
+generate_desired_snapshot
+generate_sql_migration "$EMPTY_SNAPSHOT"
+
+echo "Maintained database runtime: bootstrap is proposal-only."
+echo "Desired snapshot: $DESIRED_SNAPSHOT"
+echo "SQL proposal: $MIGRATION_SQL"
+echo "No migration was applied. Review and adapt the proposal into the maintained database migration system."
+`;
+}
+
 function renderDbBootstrapScript() {
   return `#!/usr/bin/env bash
 set -euo pipefail
@@ -489,6 +612,30 @@ echo "Greenfield bootstrap complete."
 `;
 }
 
+function renderMaintainedDbMigrateScript() {
+  return `#!/usr/bin/env bash
+set -euo pipefail
+. "$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)/db-common.sh"
+
+generate_desired_snapshot
+
+if [[ ! -f "$CURRENT_SNAPSHOT" ]]; then
+  echo "Maintained database runtime: current snapshot not found at $CURRENT_SNAPSHOT." >&2
+  echo "Create the reviewed snapshot first, then rerun this proposal command." >&2
+  exit 1
+fi
+
+generate_migration_plan "$CURRENT_SNAPSHOT"
+ensure_supported_plan
+generate_sql_migration "$CURRENT_SNAPSHOT"
+
+echo "Maintained database runtime: migration proposal generated."
+echo "Migration plan: $PLAN_JSON"
+echo "SQL proposal: $MIGRATION_SQL"
+echo "No migration was applied. Review and adapt the proposal into the maintained database migration system."
+`;
+}
+
 function renderDbMigrateScript() {
   return `#!/usr/bin/env bash
 set -euo pipefail
@@ -524,6 +671,21 @@ echo "Brownfield migration complete."
 `;
 }
 
+function renderMaintainedDbBootstrapOrMigrateScript() {
+  return `#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/db-common.sh"
+
+if [[ -f "$CURRENT_SNAPSHOT" ]]; then
+  exec bash "$SCRIPT_DIR/db-migrate.sh"
+fi
+
+exec bash "$SCRIPT_DIR/db-bootstrap.sh"
+`;
+}
+
 function renderDbBootstrapOrMigrateScript() {
   return `#!/usr/bin/env bash
 set -euo pipefail
@@ -571,10 +733,10 @@ function generateDbLifecycleBundle(graph, projection, options = {}) {
     "README.md": renderDbLifecycleReadme(plan),
     ".env.example": renderDbLifecycleEnvExample(projection, plan),
     "scripts/db-common.sh": renderDbLifecycleCommonScript(plan),
-    "scripts/db-status.sh": renderDbStatusScript(),
-    "scripts/db-bootstrap.sh": renderDbBootstrapScript(),
-    "scripts/db-migrate.sh": renderDbMigrateScript(),
-    "scripts/db-bootstrap-or-migrate.sh": renderDbBootstrapOrMigrateScript(),
+    "scripts/db-status.sh": renderDbStatusScript(plan),
+    "scripts/db-bootstrap.sh": plan.behavior.proposalOnly ? renderMaintainedDbBootstrapScript() : renderDbBootstrapScript(),
+    "scripts/db-migrate.sh": plan.behavior.proposalOnly ? renderMaintainedDbMigrateScript() : renderDbMigrateScript(),
+    "scripts/db-bootstrap-or-migrate.sh": plan.behavior.proposalOnly ? renderMaintainedDbBootstrapOrMigrateScript() : renderDbBootstrapOrMigrateScript(),
     "snapshots/empty.snapshot.json": `${JSON.stringify(renderEmptySnapshotForProjection(projection), null, 2)}\n`,
     "state/.gitkeep": ""
   };

package/src/import/extractors/cli/generic.js

@@ -1,5 +1,7 @@
 // @ts-check
 
+import path from "node:path";
+
 import {
   findImportFiles,
   idHintify,
@@ -12,6 +14,7 @@ import {
 
 const CLI_SOURCE_PATTERN = /(^|\/)(bin|cli|command|commands|parser|help)(\/|[-_.A-Za-z0-9]*\.(?:js|mjs|cjs|ts))$/i;
 const JS_SOURCE_PATTERN = /\.(?:js|mjs|cjs|ts)$/i;
+const NON_AUTHORITATIVE_CLI_PATH_PATTERN = /(^|\/)(test|tests|__tests__|fixtures|fixture|expected|snapshots|snapshot|mock|mocks|candidates|docs-generated)(\/|$)|\.(?:test|spec)\.(?:js|mjs|cjs|ts)$/i;
 
 /**
  * @param {string} value
@@ -21,6 +24,18 @@ function normalizePath(value) {
   return value.replaceAll("\\", "/");
 }
 
+/**
+ * CLI import should prefer public command surfaces, not tests or fixture strings
+ * that happen to look like command help.
+ * @param {any} paths
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function isAuthoritativeCliSource(paths, filePath) {
+  const normalized = normalizePath(normalizeImportRelativePath(paths, filePath));
+  return !NON_AUTHORITATIVE_CLI_PATH_PATTERN.test(normalized);
+}
+
 /**
  * @param {string} commandId
  * @returns {string}
@@ -29,24 +44,44 @@ function capabilityIdForCommand(commandId) {
   return `cap_${idHintify(commandId)}`;
 }
 
+/**
+ * @param {string} rawLine
+ * @returns {{ text: string, terminalOutput: boolean }}
+ */
+function normalizePotentialHelpLine(rawLine) {
+  const trimmed = rawLine.trim();
+  const terminalOutput = /^(?:console\.(?:log|error|warn)|print)\(\s*["'`]/.test(trimmed) || /^echo\s+["'`]/.test(trimmed);
+  return {
+    terminalOutput,
+    text: trimmed
+      .replace(/^\s*(?:console\.(?:log|error|warn)\(|print\(|echo\s+)?["'`]*/, "")
+      .replace(/["'`),;]*\s*$/, "")
+      .trim()
+  };
+}
+
 /**
  * @param {string} text
+ * @param {Set<string>} binNames
  * @returns {string[]}
  */
-function extractUsageLines(text) {
+function extractUsageLines(text, binNames) {
   const lines = [];
   for (const rawLine of text.split(/\r?\n/)) {
-    const line = rawLine
-      .replace(/^\s*(?:console\.log\(|print\(|echo\s+)?["'`]*/, "")
-      .replace(/["'`),;]*\s*$/, "")
-      .trim();
+    const { text: line, terminalOutput } = normalizePotentialHelpLine(rawLine);
     if (!line) continue;
     const usageMatch = line.match(/(?:^|\b)Usage:\s*(.+)$/i);
     if (usageMatch?.[1]) {
       lines.push(usageMatch[1].trim());
       continue;
     }
-    if (/^[a-zA-Z][\w.-]+(?:\s+[a-zA-Z][\w:-]+)+(?:\s|$)/.test(line) && /(?:--[a-zA-Z][\w:-]*|<[^>]+>|\[[^\]]+\])/.test(line)) {
+    const firstToken = line.split(/\s+/)[0];
+    if (
+      terminalOutput &&
+      (binNames.size === 0 || binNames.has(firstToken)) &&
+      /^[a-zA-Z][\w.-]+(?:\s+[a-zA-Z][\w:-]+)+(?:\s|$)/.test(line) &&
+      /(?:--[a-zA-Z][\w:-]*|<[^>]+>|\[[^\]]+\])/.test(line)
+    ) {
       lines.push(line);
     }
   }
@@ -167,19 +202,79 @@ function dedupeRecords(records, keyFn) {
 
 /**
  * @param {any} context
- * @returns {{ packageFiles: string[], sourceFiles: string[] }}
+ * @param {string[]} packageFiles
+ * @returns {{ binNames: Set<string>, binTargets: Set<string>, findings: any[], provenance: string[] }}
+ */
+function inspectPackageCliMetadata(context, packageFiles) {
+  const binNames = new Set();
+  const binTargets = new Set();
+  const findings = [];
+  const provenance = [];
+
+  for (const packagePath of packageFiles) {
+    const pkg = readJsonIfExists(packagePath);
+    if (!pkg) continue;
+    const relPath = normalizeImportRelativePath(context.paths, packagePath);
+    const bin = pkg.bin;
+    if (typeof bin === "string") {
+      const binName = pkg.name ? String(pkg.name).split("/").pop() : "cli";
+      binNames.add(binName);
+      binTargets.add(path.resolve(path.dirname(packagePath), bin));
+      provenance.push(`${relPath}#bin`);
+    } else if (bin && typeof bin === "object") {
+      for (const [name, target] of Object.entries(bin)) {
+        binNames.add(name);
+        if (typeof target === "string") {
+          binTargets.add(path.resolve(path.dirname(packagePath), target));
+        }
+      }
+      provenance.push(`${relPath}#bin`);
+    }
+    for (const [name, command] of Object.entries(pkg.scripts || {})) {
+      if (/^(cli|bin|start|check|test|verify)(:|$)/.test(name) || /\b(node|tsx|ts-node)\b.+\b(cli|bin)\b/i.test(String(command))) {
+        findings.push({
+          kind: "cli_script",
+          name,
+          command,
+          source: relPath
+        });
+      }
+    }
+  }
+
+  return { binNames, binTargets, findings, provenance };
+}
+
+/**
+ * @param {any} context
+ * @returns {{ packageFiles: string[], sourceFiles: string[], binNames: Set<string>, findings: any[], provenance: string[] }}
  */
 function discoverCliSources(context) {
   const packageFiles = findImportFiles(context.paths, (/** @type {string} */ filePath) => /package\.json$/i.test(filePath));
+  const packageMetadata = inspectPackageCliMetadata(context, packageFiles);
   const sourceFiles = findImportFiles(context.paths, (/** @type {string} */ filePath) => {
     const normalized = normalizePath(filePath);
+    if (!isAuthoritativeCliSource(context.paths, filePath)) {
+      return false;
+    }
     return JS_SOURCE_PATTERN.test(normalized) && (
       CLI_SOURCE_PATTERN.test(normalized) ||
       normalized.includes("/src/cli/") ||
       normalized.includes("/commands/")
     );
   });
-  return { packageFiles, sourceFiles };
+  for (const binTarget of packageMetadata.binTargets) {
+    if (JS_SOURCE_PATTERN.test(binTarget)) {
+      sourceFiles.push(binTarget);
+    }
+  }
+  return {
+    packageFiles,
+    sourceFiles: [...new Set(sourceFiles)].sort(),
+    binNames: packageMetadata.binNames,
+    findings: packageMetadata.findings,
+    provenance: packageMetadata.provenance
+  };
 }
 
 export const genericCliExtractor = {
@@ -187,7 +282,7 @@ export const genericCliExtractor = {
   track: "cli",
   /** @param {any} context */
   detect(context) {
-    const { packageFiles, sourceFiles } = discoverCliSources(context);
+    const { packageFiles, sourceFiles, binNames } = discoverCliSources(context);
     const hasBin = packageFiles.some((filePath) => {
       const pkg = readJsonIfExists(filePath);
       return Boolean(pkg?.bin);
@@ -196,53 +291,25 @@ export const genericCliExtractor = {
     return {
       score,
       reasons: [
-        hasBin ? "package.json declares a CLI bin" : null,
+        hasBin ? `package.json declares ${binNames.size || 1} CLI bin${binNames.size === 1 ? "" : "s"}` : null,
         sourceFiles.length ? `${sourceFiles.length} CLI-like source files found` : null
       ].filter(Boolean)
     };
   },
   /** @param {any} context */
   extract(context) {
-    const { packageFiles, sourceFiles } = discoverCliSources(context);
-    const findings = [];
+    const { sourceFiles, binNames, findings, provenance } = discoverCliSources(context);
     const commands = [];
     const options = [];
     const outputs = [];
     const effects = [];
     const examples = [];
     const capabilities = [];
-    const binNames = new Set();
-    const provenance = [];
-
-    for (const packagePath of packageFiles) {
-      const pkg = readJsonIfExists(packagePath);
-      if (!pkg) continue;
-      const relPath = normalizeImportRelativePath(context.paths, packagePath);
-      const bin = pkg.bin;
-      if (typeof bin === "string") {
-        binNames.add(pkg.name ? String(pkg.name).split("/").pop() : "cli");
-      } else if (bin && typeof bin === "object") {
-        for (const name of Object.keys(bin)) {
-          binNames.add(name);
-        }
-      }
-      for (const [name, command] of Object.entries(pkg.scripts || {})) {
-        if (/^(cli|bin|start|check|test|verify)(:|$)/.test(name) || /\b(node|tsx|ts-node)\b.+\b(cli|bin)\b/i.test(String(command))) {
-          findings.push({
-            kind: "cli_script",
-            name,
-            command,
-            source: relPath
-          });
-        }
-      }
-      provenance.push(`${relPath}#bin`);
-    }
 
     for (const sourcePath of sourceFiles) {
       const sourceText = readTextIfExists(sourcePath) || "";
       const relPath = normalizeImportRelativePath(context.paths, sourcePath);
-      const usageLines = extractUsageLines(sourceText);
+      const usageLines = extractUsageLines(sourceText, binNames);
       if (usageLines.length === 0) {
         continue;
       }