@beignet/cli 0.0.41 → 0.0.42

package/src/explain.ts

@@ -8,14 +8,10 @@ import {
   mapApp,
   projectAppMap,
 } from "./app-map.js";
+import { appMapNodeKinds } from "./app-map-schema.js";
 
 /** Targets supported by `beignet explain` and the MCP `explain` tool. */
-export const explainTargetKinds = [
-  "feature",
-  "route",
-  "provider",
-  "diagnostic",
-] as const;
+export const explainTargetKinds = [...appMapNodeKinds, "diagnostic"] as const;
 
 /** One supported explanation target kind. */
 export type ExplainTargetKind = (typeof explainTargetKinds)[number];
@@ -32,6 +28,8 @@ export type ExplainTarget = {
   kind: ExplainTargetKind;
   id: string;
   name: string;
+  runtimeName?: string;
+  feature?: string;
   source?: AppMapSource;
   status?: AppMapNodeStatus;
   details?: Record<string, unknown>;
@@ -318,8 +316,13 @@ function resolveTargetNode(
   const nodeKind: AppMapNodeKind = kind;
   const candidates = appMap.nodes.filter((node) => node.kind === nodeKind);
   const query = normalized(target);
+  const idMatches = candidates.filter((node) => normalized(node.id) === query);
+  if (idMatches.length === 1) return idMatches[0];
+
   let matches = candidates.filter((node) =>
-    aliasesForNode(node).some((alias) => normalized(alias) === query),
+    aliasesForNode(node).some(
+      (alias) => normalized(alias) === query && normalized(node.id) !== query,
+    ),
   );
 
   if (kind === "provider" && matches.length === 0) {
@@ -353,18 +356,27 @@ function resolveTargetNode(
     );
   }
 
-  const available = candidates
-    .map((node) => node.name)
+  const available = [...new Set(candidates.map(canonicalNodeSelector))]
     .sort()
     .slice(0, 20);
   throw new Error(
-    `Could not explain ${kind} "${target}". ${available.length > 0 ? `Available ${kind}s: ${available.join(", ")}.` : `This app has no mapped ${kind}s.`}`,
+    `Could not explain ${kind} "${target}". ${available.length > 0 ? `Available ${kind} targets: ${available.join(", ")}.` : `This app has no mapped ${kind} targets.`}`,
   );
 }
 
+function canonicalNodeSelector(node: AppMapNode): string {
+  return node.runtimeName ?? node.name;
+}
+
 function aliasesForNode(node: AppMapNode): string[] {
-  const aliases = [node.id, node.name];
+  const aliases = [node.id, node.name, node.source.file];
   if (node.runtimeName) aliases.push(node.runtimeName);
+  if (node.source.exportName) {
+    aliases.push(
+      node.source.exportName,
+      `${node.source.file}#${node.source.exportName}`,
+    );
+  }
   if (node.id.includes("#"))
     aliases.push(node.id.slice(node.id.lastIndexOf("#") + 1));
   if (node.kind === "route" && typeof node.details?.path === "string") {
@@ -412,6 +424,8 @@ function nodeTarget(
     kind,
     id: node.id,
     name: node.name,
+    ...(node.runtimeName ? { runtimeName: node.runtimeName } : {}),
+    ...(node.feature ? { feature: node.feature } : {}),
     source: node.source,
     ...(node.status ? { status: node.status } : {}),
     ...(node.details ? { details: node.details } : {}),
@@ -654,16 +668,7 @@ function suggestedActions(
   findings: ExplainFinding[],
   targetDir: string,
 ): ExplainSuggestedAction[] {
-  const inspectCommand =
-    target.kind === "feature"
-      ? `beignet map --feature ${target.name} --json`
-      : target.kind === "route"
-        ? "beignet routes --json"
-        : target.kind === "provider"
-          ? "beignet provider audit --json"
-          : findings.some((finding) => finding.source === "lint")
-            ? "beignet lint --json"
-            : "beignet doctor --strict --json";
+  const inspectCommand = inspectCommandForTarget(target, findings);
   const actions: ExplainSuggestedAction[] = [
     {
       kind: "inspect",
@@ -688,6 +693,35 @@ function suggestedActions(
   return actions;
 }
 
+function inspectCommandForTarget(
+  target: ExplainTarget,
+  findings: ExplainFinding[],
+): string {
+  if (target.kind === "feature") {
+    return `beignet map --feature ${target.name} --json`;
+  }
+  if (
+    target.kind === "contract" ||
+    target.kind === "route" ||
+    target.kind === "route-group" ||
+    target.kind === "openapi"
+  ) {
+    return "beignet routes --json";
+  }
+  if (target.kind === "port" || target.kind === "provider") {
+    return "beignet provider audit --json";
+  }
+  if (target.kind === "diagnostic") {
+    return findings.every((finding) => finding.source === "lint")
+      ? "beignet lint --json"
+      : "beignet doctor --strict --json";
+  }
+  if (target.feature) {
+    return `beignet map --feature ${target.feature} --json`;
+  }
+  return `beignet map --kind ${target.kind} --json`;
+}
+
 function providerRegistrationSources(target: ExplainTarget): AppMapSource[] {
   if (target.kind !== "provider") return [];
   const sources = target.details?.registrationSources;
@@ -722,29 +756,103 @@ function explainSummary(
   return `${target.name} is ${target.status ?? "mapped"} with ${countLabel(edges.length, "relationship")}, ${countLabel(fileCount, "source")}, and ${countLabel(findings.length, "relevant finding")}.`;
 }
 
+const conventionsByTargetKind = {
+  feature: [
+    "Feature-owned contracts, use cases, policies, ports, workflows, clients, components, and tests stay under features/<feature>/.",
+    "Feature route groups and workflow artifacts register through the central server entrypoints.",
+  ],
+  contract: [
+    "Contracts own HTTP method, path, schemas, responses, metadata, and route errors.",
+    "Contracts stay transport-focused and bind to application behavior through feature routes.",
+  ],
+  route: [
+    "Routes bind contracts to use cases and policies without importing concrete infrastructure.",
+    "Feature route groups compose centrally in server/routes.ts and runtime route adapters stay thin.",
+  ],
+  "route-group": [
+    "Feature route groups are declared in features/<feature>/routes.ts and composed centrally in server/routes.ts.",
+    "Route groups bind contracts to use cases while preserving the app's dependency direction.",
+  ],
+  "use-case": [
+    "Use cases own validated application workflows and may depend on ports, policies, and domain code, not concrete infrastructure or UI.",
+    "Use cases remain callable outside HTTP so routes, tasks, jobs, and agent capabilities can reuse the same behavior.",
+  ],
+  policy: [
+    "Feature policies own business authorization for resources owned by that feature.",
+    "Authorization remains enforced in application workflows even when contract metadata also declares an ability.",
+  ],
+  ability: [
+    "An ability belongs to the policy of the feature that owns the resource being authorized.",
+    "Contracts may name authorization abilities, while policies and use cases enforce the business rule.",
+  ],
+  event: [
+    "Events represent facts that happened and belong to the feature that owns the fact.",
+    "Durable event publication registers through the app's workflow and outbox boundaries.",
+  ],
+  listener: [
+    "Listeners react to registered events and delegate application work through ports, jobs, notifications, or use cases.",
+    "Feature listeners register through the central listener registry used by runtime wiring and integrity checks.",
+  ],
+  job: [
+    "Jobs represent background work and remain explicit at provider-backed execution boundaries.",
+    "Feature jobs register through central runtime or outbox registries before workers can dispatch them.",
+  ],
+  schedule: [
+    "Schedules represent time-based triggers and delegate work to application workflows.",
+    "Feature schedules register centrally so runtime wiring, doctor, and beignet schedule run inspect the same surface.",
+  ],
+  task: [
+    "Tasks are explicit operational entrypoints for maintenance, backfills, and other bounded application work.",
+    "Feature tasks register centrally so beignet task run and runtime integrity checks use the same definitions.",
+  ],
+  notification: [
+    "Notifications represent user-facing communication intent, separate from provider-specific delivery.",
+    "Queued notification definitions register with the central notification and job runtime.",
+  ],
+  upload: [
+    "Uploads define feature-owned validation and storage workflows while storage remains behind an app port.",
+    "Upload route adapters stay thin and reuse the registered feature upload definition.",
+  ],
+  "agent-capability": [
+    "Agent capabilities expose curated, validated inputs and outputs by adapting existing application use cases.",
+    "Delegated context and authorization resolve centrally before an agent capability executes.",
+  ],
+  registry: [
+    "Registries explicitly compose feature declarations into the runtime surface inspected by doctor and app-map.",
+    "Central registries remain the source of truth for runtime wiring and integrity checks.",
+  ],
+  port: [
+    "Ports define app-facing dependency interfaces; infrastructure adapters provide their concrete implementations.",
+    "App ports wire through infra/port-wiring.ts and remain available to use cases through application context.",
+  ],
+  provider: [
+    "Ports define app-facing interfaces, providers adapt external systems, and app infrastructure wires them together.",
+    "Lifecycle providers register in server/providers.ts and provider-backed app ports wire through infra/port-wiring.ts.",
+  ],
+  table: [
+    "Database tables remain infrastructure-owned persistence details rather than domain or use-case dependencies.",
+    "Configured schema sources and migrations must describe the same deployed database surface.",
+  ],
+  openapi: [
+    "OpenAPI documents derive from the same registered contract surface served by the application.",
+    "Documented methods, paths, schemas, errors, and operation IDs stay aligned with their contracts.",
+  ],
+  entrypoint: [
+    "Runtime entrypoints compose the server or expose thin framework adapters over registered routes.",
+    "Entrypoints reuse central context, routes, providers, and workflow registries instead of duplicating application behavior.",
+  ],
+  test: [
+    "Feature behavior tests stay under features/<feature>/tests and exercise use cases, routes, policies, workflows, and UI.",
+    "Infrastructure and server integration tests may remain adjacent to the modules they exercise.",
+  ],
+  diagnostic: [
+    "Doctor findings describe framework convention drift; lint findings describe dependency-direction violations.",
+    "Fix the app structure or wiring named by the finding, then run the complete validation loop.",
+  ],
+} as const satisfies Record<ExplainTargetKind, readonly string[]>;
+
 function conventionsFor(kind: ExplainTargetKind): string[] {
-  switch (kind) {
-    case "feature":
-      return [
-        "Feature-owned contracts, use cases, policies, ports, workflows, clients, components, and tests stay under features/<feature>/.",
-        "Feature route groups and workflow artifacts register through the central server entrypoints.",
-      ];
-    case "route":
-      return [
-        "Contracts own HTTP method, path, schemas, responses, metadata, and route errors; routes bind contracts to use cases.",
-        "Feature route groups compose centrally in server/routes.ts and runtime route adapters stay thin.",
-      ];
-    case "provider":
-      return [
-        "Ports define app-facing interfaces, providers adapt external systems, and app infrastructure wires them together.",
-        "Lifecycle providers register in server/providers.ts and provider-backed app ports wire through infra/port-wiring.ts.",
-      ];
-    case "diagnostic":
-      return [
-        "Doctor findings describe framework convention drift; lint findings describe dependency-direction violations.",
-        "Fix the app structure or wiring named by the finding, then run the complete validation loop.",
-      ];
-  }
+  return [...conventionsByTargetKind[kind]];
 }
 
 function scopeFiles(nodes: AppMapNode[], edges: AppMapEdge[]): Set<string> {

package/src/index.ts

@@ -19,9 +19,16 @@ import {
   type CreateProviderName,
   completionShellChoices,
   createProviderChoices,
+  type DatabaseCommand,
   type DatabaseName,
+  type DatabaseSchemaDialect,
+  type DatabaseSchemaTable,
+  type DoctorFixOperationId,
   databaseChoices,
+  databaseSchemaDialectChoices,
+  databaseSchemaTableChoices,
   databaseStartCommand,
+  doctorFixOperationIds,
   type MakeFeatureAddon,
   type MakeFeatureRecipe,
   makeFeatureAddonChoices,
@@ -143,21 +150,6 @@ type DbFlags = {
   cwd?: string;
 };
 
-type DatabaseSchemaDialect = "sqlite" | "postgres" | "mysql";
-type DatabaseSchemaTable = "audit" | "idempotency" | "outbox";
-
-const databaseSchemaDialectChoices = [
-  "sqlite",
-  "postgres",
-  "mysql",
-] as const satisfies readonly DatabaseSchemaDialect[];
-
-const databaseSchemaTableChoices = [
-  "audit",
-  "idempotency",
-  "outbox",
-] as const satisfies readonly DatabaseSchemaTable[];
-
 type DbSchemaSyncFlags = DbFlags & {
   dialect?: DatabaseSchemaDialect;
   tables?: readonly DatabaseSchemaTable[];
@@ -258,6 +250,9 @@ type DoctorFlags = {
   json?: boolean;
   strict?: boolean;
   fix?: boolean;
+  dryRun?: boolean;
+  plan?: string;
+  only?: readonly DoctorFixOperationId[];
   cwd?: string;
   format?: OutputFormat;
 };
@@ -925,16 +920,37 @@ function explainCommand(kind: ExplainTargetKind) {
   });
 }
 
+const explainRouteCommands = {
+  ability: explainCommand("ability"),
+  "agent-capability": explainCommand("agent-capability"),
+  contract: explainCommand("contract"),
+  diagnostic: explainCommand("diagnostic"),
+  entrypoint: explainCommand("entrypoint"),
+  event: explainCommand("event"),
+  feature: explainCommand("feature"),
+  job: explainCommand("job"),
+  listener: explainCommand("listener"),
+  notification: explainCommand("notification"),
+  openapi: explainCommand("openapi"),
+  policy: explainCommand("policy"),
+  port: explainCommand("port"),
+  provider: explainCommand("provider"),
+  registry: explainCommand("registry"),
+  route: explainCommand("route"),
+  "route-group": explainCommand("route-group"),
+  schedule: explainCommand("schedule"),
+  table: explainCommand("table"),
+  task: explainCommand("task"),
+  test: explainCommand("test"),
+  upload: explainCommand("upload"),
+  "use-case": explainCommand("use-case"),
+} satisfies Record<ExplainTargetKind, ReturnType<typeof explainCommand>>;
+
 const explainRoutes = buildRouteMap({
   docs: {
     brief: "Explain mapped Beignet app concepts with source evidence.",
   },
-  routes: {
-    diagnostic: explainCommand("diagnostic"),
-    feature: explainCommand("feature"),
-    provider: explainCommand("provider"),
-    route: explainCommand("route"),
-  },
+  routes: explainRouteCommands,
 });
 
 const doctorCommand = buildCommand<DoctorFlags, [], CliContext>({
@@ -956,27 +972,103 @@ const doctorCommand = buildCommand<DoctorFlags, [], CliContext>({
         withNegated: false,
         brief: "Apply low-risk fixes before reporting.",
       },
+      dryRun: {
+        ...dryRunFlag,
+        brief: "Preview an exact doctor fix plan without writing files.",
+      },
+      plan: parsedStringFlag(
+        "Apply only when the current repair plan matches this plan ID.",
+      ),
+      only: {
+        kind: "enum",
+        values: doctorFixOperationIds,
+        optional: true,
+        variadic: ",",
+        brief: "Apply only these repair operation IDs. Requires --plan.",
+      },
       cwd: cwdFlag,
       format: formatFlag,
-    },
+    } satisfies FlagParametersForType<DoctorFlags, CliContext>,
   },
   loader: async () => {
-    const { applyDoctorFixes, formatDoctor, formatDoctorGithub, inspectApp } =
-      await import("./inspect.js");
+    const {
+      applyDoctorFixPlan,
+      applyDoctorFixesWithResult,
+      createDoctorFixInspectionResult,
+      formatDoctor,
+      formatDoctorFixPlan,
+      formatDoctorFixPlanGithub,
+      formatDoctorGithub,
+      inspectApp,
+      planDoctorFixes,
+    } = await import("./inspect.js");
 
     return async function runDoctor(this: CliContext, flags: DoctorFlags) {
       const format = resolveOutputFormat(flags);
-      const fixes = flags.fix
-        ? await applyDoctorFixes({
+      const only = flags.only ?? [];
+      if (flags.dryRun && !flags.fix) {
+        throw new Error("doctor --dry-run requires --fix.");
+      }
+      if (flags.plan && !flags.fix) {
+        throw new Error("doctor --plan requires --fix.");
+      }
+      if (flags.dryRun && flags.plan) {
+        throw new Error("doctor --dry-run cannot be combined with --plan.");
+      }
+      if (flags.dryRun && only.length > 0) {
+        throw new Error(
+          "doctor --dry-run previews the complete plan; use --only when applying it.",
+        );
+      }
+      if (only.length > 0 && !flags.plan) {
+        throw new Error("doctor --only requires --plan.");
+      }
+
+      if (flags.dryRun) {
+        const plan = await planDoctorFixes({
+          cwd: flags.cwd,
+          strict: Boolean(flags.strict),
+        });
+        writeOutput(
+          this,
+          format === "json"
+            ? JSON.stringify(plan, null, 2)
+            : format === "github"
+              ? formatDoctorFixPlanGithub(plan)
+              : formatDoctorFixPlan(plan, { color: useColor() }),
+        );
+        if (
+          plan.diagnostics.some(
+            (diagnostic) =>
+              diagnostic.severity === "error" ||
+              (flags.strict && diagnostic.severity === "warning"),
+          )
+        ) {
+          this.process.exitCode = 1;
+        }
+        return;
+      }
+
+      const applied = flags.plan
+        ? await applyDoctorFixPlan({
             cwd: flags.cwd,
             strict: Boolean(flags.strict),
+            planId: flags.plan,
+            ...(only.length > 0 ? { fixIds: only } : {}),
           })
-        : [];
-      const result = await inspectApp({
+        : flags.fix
+          ? await applyDoctorFixesWithResult({
+              cwd: flags.cwd,
+              strict: Boolean(flags.strict),
+            })
+          : undefined;
+      const inspected = await inspectApp({
         cwd: flags.cwd,
         strict: Boolean(flags.strict),
       });
-      result.fixes = fixes;
+      const result = applied
+        ? createDoctorFixInspectionResult(inspected, applied)
+        : inspected;
       writeOutput(
         this,
         format === "json"
@@ -1241,9 +1333,7 @@ const providerRoutes = buildRouteMap({
   },
 });
 
-type DatabaseCommandName = "generate" | "migrate" | "reset" | "seed";
-
-function databaseCommand(command: DatabaseCommandName) {
+function databaseCommand(command: DatabaseCommand) {
   return buildCommand<DbFlags, [], CliContext>({
     docs: {
       brief: `Run the app's db:${command} script.`,
@@ -1252,13 +1342,18 @@ function databaseCommand(command: DatabaseCommandName) {
       flags: dbFlagParameters,
     },
     loader: async () => {
-      const { runDatabaseCommand } = await import("./db.js");
+      const { defaultDatabaseCommandMaxOutputBytes, runDatabaseCommand } =
+        await import("./db.js");
 
       return async function runDb(this: CliContext, flags: DbFlags) {
+        const captureOutput = Boolean(flags.json);
         const result = await runDatabaseCommand({
           command,
           cwd: flags.cwd,
-          captureOutput: Boolean(flags.json),
+          captureOutput,
+          maxOutputBytes: captureOutput
+            ? defaultDatabaseCommandMaxOutputBytes
+            : undefined,
           dryRun: Boolean(flags.dryRun),
         });
 
@@ -1329,7 +1424,7 @@ const dbRoutes = buildRouteMap({
     reset: databaseCommand("reset"),
     schema: dbSchemaRoutes,
     seed: databaseCommand("seed"),
-  },
+  } satisfies Record<DatabaseCommand | "schema", unknown>,
 });
 
 const taskRunCommand = buildCommand<TaskRunFlags, [string], CliContext>({