@beignet/cli 0.0.40 → 0.0.42

package/src/index.ts

@@ -13,14 +13,22 @@ import {
   type StricliProcess,
   text_en,
 } from "@stricli/core";
+import { type AppMapNodeKind, appMapNodeKinds } from "./app-map-schema.js";
 import {
   type CompletionShell,
   type CreateProviderName,
   completionShellChoices,
   createProviderChoices,
+  type DatabaseCommand,
   type DatabaseName,
+  type DatabaseSchemaDialect,
+  type DatabaseSchemaTable,
+  type DoctorFixOperationId,
   databaseChoices,
+  databaseSchemaDialectChoices,
+  databaseSchemaTableChoices,
   databaseStartCommand,
+  doctorFixOperationIds,
   type MakeFeatureAddon,
   type MakeFeatureRecipe,
   makeFeatureAddonChoices,
@@ -36,6 +44,7 @@ import {
 } from "./choices.js";
 // Type-only: the runtime module stays behind the create command's lazy loader.
 import type { CreateSelections } from "./create-prompts.js";
+import type { ExplainTargetKind } from "./explain.js";
 import type { AddProviderPresetResult } from "./provider-add.js";
 import { getCliVersion } from "./version.js";
 
@@ -106,6 +115,13 @@ type RoutesFlags = {
   cwd?: string;
 };
 
+type MapFlags = RoutesFlags & {
+  feature?: string;
+  kind?: readonly AppMapNodeKind[];
+};
+
+type ExplainFlags = RoutesFlags;
+
 type LintFlags = {
   json?: boolean;
   cwd?: string;
@@ -134,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[];
@@ -249,6 +250,9 @@ type DoctorFlags = {
   json?: boolean;
   strict?: boolean;
   fix?: boolean;
+  dryRun?: boolean;
+  plan?: string;
+  only?: readonly DoctorFixOperationId[];
   cwd?: string;
   format?: OutputFormat;
 };
@@ -366,6 +370,21 @@ const routesFlagParameters = {
   cwd: cwdFlag,
 } satisfies FlagParametersForType<RoutesFlags, CliContext>;
 
+const mapFlagParameters = {
+  json: jsonFlag,
+  feature: parsedStringFlag(
+    "Project one feature and its direct relationships.",
+  ),
+  kind: {
+    kind: "enum",
+    values: appMapNodeKinds,
+    optional: true,
+    variadic: ",",
+    brief: "Include only these node kinds. Accepts comma-separated values.",
+  },
+  cwd: cwdFlag,
+} satisfies FlagParametersForType<MapFlags, CliContext>;
+
 const lintFlagParameters = {
   json: jsonFlag,
   cwd: cwdFlag,
@@ -585,6 +604,19 @@ const providerPresetPositional = {
   ],
 } as const;
 
+function explainTargetPositional(kind: ExplainTargetKind) {
+  return {
+    kind: "tuple",
+    parameters: [
+      {
+        parse: parseString,
+        placeholder: kind,
+        brief: `${kind[0]?.toUpperCase()}${kind.slice(1)} to explain.`,
+      },
+    ],
+  } as const;
+}
+
 function resolveOutputFormat(flags: {
   json?: boolean;
   format?: OutputFormat;
@@ -829,6 +861,98 @@ const routesCommand = buildCommand<RoutesFlags, [], CliContext>({
   },
 });
 
+const mapCommand = buildCommand<MapFlags, [], CliContext>({
+  docs: {
+    brief: "Map the app's architecture and registered workflows.",
+    fullDescription:
+      "Build a deterministic graph of features, HTTP contracts, routes, use cases, policies, workflows, ports, providers, OpenAPI, tests, dependencies, and doctor findings.",
+  },
+  parameters: {
+    flags: mapFlagParameters,
+  },
+  loader: async () => {
+    const { formatAppMap, mapApp, projectAppMap } = await import(
+      "./app-map.js"
+    );
+
+    return async function runMap(this: CliContext, flags: MapFlags) {
+      const result = projectAppMap(
+        await mapApp({ cwd: flags.cwd, strict: true }),
+        {
+          feature: flags.feature,
+          kinds: flags.kind,
+        },
+      );
+      writeOutput(
+        this,
+        flags.json ? JSON.stringify(result, null, 2) : formatAppMap(result),
+      );
+    };
+  },
+});
+
+function explainCommand(kind: ExplainTargetKind) {
+  return buildCommand<ExplainFlags, [string], CliContext>({
+    docs: {
+      brief: `Explain one mapped Beignet ${kind}.`,
+      fullDescription:
+        "Returns source-backed relationships, conventions, findings, suggested files, and follow-up commands without generating advice or changing the app.",
+    },
+    parameters: {
+      flags: routesFlagParameters,
+      positional: explainTargetPositional(kind),
+    },
+    loader: async () => {
+      const { explainApp, formatExplain } = await import("./explain.js");
+
+      return async function runExplain(
+        this: CliContext,
+        flags: ExplainFlags,
+        target: string,
+      ) {
+        const result = await explainApp({ kind, target, cwd: flags.cwd });
+        writeOutput(
+          this,
+          flags.json ? JSON.stringify(result, null, 2) : formatExplain(result),
+        );
+      };
+    },
+  });
+}
+
+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: explainRouteCommands,
+});
+
 const doctorCommand = buildCommand<DoctorFlags, [], CliContext>({
   docs: {
     brief: "Inspect app wiring and framework conventions.",
@@ -848,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"
@@ -1035,7 +1235,7 @@ const lintCommand = buildCommand<LintFlags, [], CliContext>({
 const mcpCommand = buildCommand<McpFlags, [], CliContext>({
   docs: {
     brief:
-      "Run a Model Context Protocol server exposing this app's routes, doctor, lint, and generators over stdio.",
+      "Run a Model Context Protocol server exposing the app map, validation, and generators over stdio.",
   },
   parameters: {
     flags: {
@@ -1133,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.`,
@@ -1144,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),
         });
 
@@ -1221,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>({
@@ -2109,7 +2312,7 @@ const makeRoutes = buildRouteMap({
 const rootRoutes = buildRouteMap({
   docs: {
     brief: "Beignet CLI",
-    fullDescription: `Create apps, generate framework files, inspect routes, and check Beignet conventions.
+    fullDescription: `Create apps, generate framework files, map and explain architecture, inspect routes, and check Beignet conventions.
 
 Run npm create beignet@latest (or bun create beignet) to scaffold a new app.`,
   },
@@ -2119,7 +2322,9 @@ Run npm create beignet@latest (or bun create beignet) to scaffold a new app.`,
     create: createCommand,
     db: dbRoutes,
     doctor: doctorCommand,
+    explain: explainRoutes,
     lint: lintCommand,
+    map: mapCommand,
     make: makeRoutes,
     mcp: mcpCommand,
     outbox: outboxRoutes,
@@ -2431,6 +2636,7 @@ ${openStep}
 
 Inspect the app:
   ${cli} routes
+  ${cli} map
   ${cli} check
 
 Generate a feature: