@akanjs/cli 2.4.0 → 2.4.1-rc.1

package/index-45aj5ry0.js

@@ -0,0 +1,990 @@
+// @bun
+import {
+  AkanContextAnalyzer
+} from "./index-8rc0bm04.js";
+import {
+  WorkflowExecutor,
+  compactWorkflowInputs,
+  createDryRunWorkflowApplyReport,
+  createWorkflowApplyReport,
+  createWorkflowBaselineSummary,
+  createWorkflowPlan,
+  createWorkflowValidationRunReport,
+  getWorkflowSpec,
+  jsonText,
+  listWorkflowSpecs,
+  readWorkflowRunArtifact,
+  renderWorkflowApply,
+  renderWorkflowExplain,
+  renderWorkflowList,
+  renderWorkflowPlan,
+  renderWorkflowRunArtifact,
+  renderWorkflowValidation,
+  workflowCommandsForPlan,
+  workflowPlanApproval,
+  writeWorkflowRunArtifact
+} from "./index-h6ca6qg0.js";
+import {
+  runner
+} from "./index-hdqztm58.js";
+
+// pkgs/@akanjs/cli/workflow/workflow.runner.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import path from "path";
+import { capitalize } from "akanjs/common";
+
+// pkgs/@akanjs/cli/workflows/shared.ts
+var sysInputs = {
+  app: {
+    type: "string",
+    required: true,
+    description: "Target app or library name."
+  }
+};
+var moduleInput = {
+  module: {
+    type: "string",
+    required: true,
+    description: "Target domain, service, or scalar module name."
+  }
+};
+var baseValidation = [
+  { command: "akan sync <app-or-lib>", reason: "Refresh generated Akan files from source conventions.", kind: "sync" },
+  {
+    command: "akan lint <app-or-lib-or-pkg>",
+    reason: "Validate formatting, imports, and static lint rules.",
+    kind: "lint"
+  }
+];
+
+// pkgs/@akanjs/cli/workflows/addEnumField.ts
+var addEnumFieldWorkflowSpec = {
+  schemaVersion: 1,
+  name: "add-enum-field",
+  description: "Plan an enum field addition with option and dictionary coverage.",
+  whenToUse: "Use when the user asks to add a field with a closed set of values.",
+  inputs: {
+    ...sysInputs,
+    ...moduleInput,
+    field: { type: "string", required: true, description: "Name of the enum field to add." },
+    values: { type: "string-list", required: true, description: "Comma-separated enum values." },
+    default: { type: "string", description: "Optional default enum value." }
+  },
+  optionalSurfaces: {
+    dictionary: "include",
+    option: "include",
+    template: "infer",
+    unit: "infer",
+    view: "infer",
+    store: "infer"
+  },
+  steps: [
+    {
+      id: "inspect-module",
+      title: "Inspect module",
+      tool: "inspectModule",
+      description: "Read module files and existing enum conventions."
+    },
+    {
+      id: "update-constant",
+      title: "Update enum field",
+      tool: "updateConstantEnumField",
+      description: "Plan enum type and field shape changes."
+    },
+    {
+      id: "update-dictionary",
+      title: "Update dictionary",
+      tool: "updateDictionaryEnum",
+      description: "Plan enum labels and field labels."
+    },
+    {
+      id: "update-option",
+      title: "Update options",
+      tool: "updateOptionEnum",
+      description: "Plan option entries used by UI controls."
+    },
+    {
+      id: "sync-generated",
+      title: "Sync generated files",
+      tool: "syncTarget",
+      description: "Refresh generated files after enum source changes."
+    },
+    {
+      id: "validate-target",
+      title: "Validate target",
+      tool: "lintTarget",
+      description: "Run validation commands for the target."
+    }
+  ],
+  predictedChanges: [
+    { target: "*/lib/<module>/<module>.constant.ts", action: "modify", reason: "Enum field shape is added." },
+    { target: "*/lib/<module>/<module>.dictionary.ts", action: "modify", reason: "Enum labels are added." },
+    { target: "*/lib/<module>/<module>.option.ts", action: "modify", reason: "Enum options may be added." }
+  ],
+  validation: [
+    ...baseValidation,
+    { command: "akan typecheck <app-name>", reason: "Validate enum usage across module surfaces.", kind: "typecheck" }
+  ],
+  completionCriteria: ["Enum values are represented.", "Labels and options exist.", "Sync, lint, and typecheck pass."]
+};
+
+// pkgs/@akanjs/cli/workflows/addField.ts
+var addFieldWorkflowSpec = {
+  schemaVersion: 1,
+  name: "add-field",
+  description: "Plan a field addition across domain and selected UI surfaces.",
+  whenToUse: "Use when the user asks to add a new field to an existing domain module.",
+  inputs: {
+    ...sysInputs,
+    ...moduleInput,
+    field: { type: "string", required: true, description: "Name of the field to add." },
+    type: {
+      type: "string",
+      required: true,
+      description: "Field type or scalar name. Use Int for integer fields or Float for decimal fields; do not use Number."
+    },
+    values: { type: "string-list", description: "Comma-separated enum values when type is enum." },
+    default: {
+      type: "string",
+      description: "Optional default value. plan/apply coerce by field type: Int/Float to numeric literals, Boolean to true/false, Date to new Date(...), String/scalar to string literals, and enum only when the value is in values."
+    },
+    surfaces: {
+      type: "string-list",
+      description: "Optional UI surfaces to update, comma-separated. Use template to auto-update simple generated Template forms; View/Unit stay planned as manual review."
+    },
+    includeInLight: {
+      type: "boolean",
+      description: "Whether to add the field to the Light<Model> projection used by list/card displays."
+    }
+  },
+  optionalSurfaces: {
+    dictionary: "include",
+    template: "infer",
+    unit: "infer",
+    view: "infer",
+    store: "infer"
+  },
+  steps: [
+    {
+      id: "inspect-module",
+      title: "Inspect module",
+      tool: "inspectModule",
+      description: "Read module files and detect existing field/UI patterns."
+    },
+    {
+      id: "update-constant",
+      title: "Update constant",
+      tool: "updateConstantField",
+      description: "Plan the source-of-truth field shape change."
+    },
+    {
+      id: "update-dictionary",
+      title: "Update dictionary",
+      tool: "updateDictionaryField",
+      description: "Plan field labels and user-facing text."
+    },
+    {
+      id: "update-ui-surfaces",
+      title: "Update UI surfaces",
+      tool: "updateUiSurfaces",
+      description: "Plan optional Template, Unit, View, and Store updates according to inferred surfaces.",
+      when: "optionalSurfaces.* is include or infer"
+    },
+    {
+      id: "sync-generated",
+      title: "Sync generated files",
+      tool: "syncTarget",
+      description: "Refresh generated files after source changes."
+    },
+    {
+      id: "validate-target",
+      title: "Validate target",
+      tool: "lintTarget",
+      description: "Run validation commands for the target."
+    }
+  ],
+  predictedChanges: [
+    {
+      target: "*/lib/<module>/<module>.constant.ts",
+      action: "modify",
+      applyScope: "auto",
+      reason: "Field shape is added."
+    },
+    {
+      target: "*/lib/<module>/<module>.dictionary.ts",
+      action: "modify",
+      applyScope: "auto",
+      reason: "Field label is added."
+    },
+    {
+      target: "*/lib/<module>/<Module>.Template.tsx",
+      action: "modify",
+      applyScope: "manual-review",
+      reason: "Form surface may include the field."
+    },
+    {
+      target: "*/lib/cnst.ts",
+      action: "sync",
+      applyScope: "generated-sync",
+      reason: "Generated constants may change after sync."
+    },
+    {
+      target: "*/lib/dict.ts",
+      action: "sync",
+      applyScope: "generated-sync",
+      reason: "Generated dictionary barrel may change after sync."
+    }
+  ],
+  validation: [
+    ...baseValidation,
+    {
+      command: "akan typecheck <app-name>",
+      reason: "Validate cross-surface TypeScript contracts after field changes.",
+      kind: "typecheck"
+    }
+  ],
+  completionCriteria: [
+    "Field exists in source-of-truth module shape.",
+    "Dictionary labels cover the field.",
+    "Generated files are refreshed.",
+    "Lint and typecheck pass."
+  ]
+};
+
+// pkgs/@akanjs/cli/workflows/addMutation.ts
+var addMutationWorkflowSpec = {
+  schemaVersion: 1,
+  name: "add-mutation",
+  description: "Plan a server mutation and matching signal/store/UI action surface.",
+  whenToUse: "Use when the user asks for a new state-changing module action.",
+  inputs: {
+    ...sysInputs,
+    ...moduleInput,
+    mutation: { type: "string", required: true, description: "Mutation/action name." }
+  },
+  optionalSurfaces: {
+    service: "include",
+    signal: "include",
+    store: "infer",
+    util: "infer",
+    unit: "infer",
+    view: "infer",
+    dictionary: "include"
+  },
+  steps: [
+    {
+      id: "inspect-module",
+      title: "Inspect module",
+      tool: "inspectModule",
+      description: "Read service, signal, store, and UI action patterns."
+    },
+    {
+      id: "update-service",
+      title: "Update service",
+      tool: "updateServiceMutation",
+      description: "Plan the server-side mutation method."
+    },
+    {
+      id: "update-signal",
+      title: "Update signal",
+      tool: "updateSignalMutation",
+      description: "Plan the client/server signal mutation binding."
+    },
+    {
+      id: "update-action-surfaces",
+      title: "Update action surfaces",
+      tool: "updateActionSurfaces",
+      description: "Plan optional store and UI action changes."
+    },
+    {
+      id: "sync-generated",
+      title: "Sync generated files",
+      tool: "syncTarget",
+      description: "Refresh generated service and signal barrels."
+    },
+    {
+      id: "validate-target",
+      title: "Validate target",
+      tool: "lintTarget",
+      description: "Run validation commands for the target."
+    }
+  ],
+  predictedChanges: [
+    {
+      target: "*/lib/<module>/<module>.service.ts",
+      action: "modify",
+      applyScope: "auto",
+      reason: "Service mutation method stub is added."
+    },
+    {
+      target: "*/lib/<module>/<module>.signal.ts",
+      action: "modify",
+      applyScope: "auto",
+      reason: "Signal endpoint mutation is added."
+    },
+    { target: "*/lib/srv.ts", action: "sync", reason: "Generated service barrel may change after sync." },
+    { target: "*/lib/sig.ts", action: "sync", reason: "Generated signal barrel may change after sync." }
+  ],
+  validation: [
+    ...baseValidation,
+    {
+      command: "akan typecheck <app-name>",
+      reason: "Validate mutation contracts across service and signal.",
+      kind: "typecheck"
+    }
+  ],
+  completionCriteria: ["Service and signal contracts align.", "Generated files are refreshed.", "Validation passes."]
+};
+
+// pkgs/@akanjs/cli/workflows/addSlice.ts
+var addSliceWorkflowSpec = {
+  schemaVersion: 1,
+  name: "add-slice",
+  description: "Plan a list/query slice across data access, signal, and view surfaces.",
+  whenToUse: "Use when the user asks for a filtered list, tab, segment, or reusable query slice.",
+  inputs: {
+    ...sysInputs,
+    ...moduleInput,
+    slice: { type: "string", required: true, description: "Slice or query name." }
+  },
+  optionalSurfaces: {
+    service: "include",
+    signal: "include",
+    zone: "infer",
+    page: "infer",
+    dictionary: "include"
+  },
+  steps: [
+    {
+      id: "inspect-module",
+      title: "Inspect module",
+      tool: "inspectModule",
+      description: "Read existing query, slice, zone, and page loading patterns."
+    },
+    {
+      id: "update-service-query",
+      title: "Update service query",
+      tool: "updateServiceSlice",
+      description: "Plan the query helper or filter handling."
+    },
+    {
+      id: "update-signal-slice",
+      title: "Update signal slice",
+      tool: "updateSignalSlice",
+      description: "Plan the signal slice contract."
+    },
+    {
+      id: "connect-view-surfaces",
+      title: "Connect view surfaces",
+      tool: "connectSliceSurfaces",
+      description: "Plan optional Zone and page loader changes."
+    },
+    {
+      id: "sync-generated",
+      title: "Sync generated files",
+      tool: "syncTarget",
+      description: "Refresh generated files after slice changes."
+    },
+    {
+      id: "validate-target",
+      title: "Validate target",
+      tool: "lintTarget",
+      description: "Run validation commands for the target."
+    }
+  ],
+  predictedChanges: [
+    {
+      target: "*/lib/<module>/<module>.service.ts",
+      action: "modify",
+      applyScope: "auto",
+      reason: "Query helper method stub is added."
+    },
+    {
+      target: "*/lib/<module>/<module>.signal.ts",
+      action: "modify",
+      applyScope: "auto",
+      reason: "Signal slice entry is added."
+    },
+    {
+      target: "*/lib/<module>/<Module>.Zone.tsx",
+      action: "modify",
+      applyScope: "manual-review",
+      reason: "Zone may connect slice state."
+    },
+    { target: "*/lib/sig.ts", action: "sync", reason: "Generated signal barrel may change after sync." }
+  ],
+  validation: [
+    ...baseValidation,
+    {
+      command: "akan build <app-name>",
+      reason: "Validate page and list surfaces when a slice changes app behavior.",
+      kind: "custom"
+    }
+  ],
+  completionCriteria: [
+    "Slice query and signal shape align.",
+    "Optional view surfaces are planned.",
+    "Validation passes."
+  ]
+};
+
+// pkgs/@akanjs/cli/workflows/createModule.ts
+var createModuleWorkflowSpec = {
+  schemaVersion: 1,
+  name: "create-module",
+  description: "Plan a new database-backed domain module using Akan module conventions.",
+  whenToUse: "Use when the user asks for a new business entity with constant, service, signal, store, and UI surfaces.",
+  inputs: {
+    ...sysInputs,
+    module: { type: "string", required: true, description: "Name of the module to create." }
+  },
+  optionalSurfaces: {
+    page: "infer",
+    template: "include",
+    unit: "include",
+    view: "include"
+  },
+  steps: [
+    {
+      id: "inspect-system",
+      title: "Inspect target system",
+      tool: "inspectSystem",
+      description: "Check the target app or library before planning new module files."
+    },
+    {
+      id: "create-module",
+      title: "Create module",
+      tool: "createModule",
+      description: "Use the existing create-module primitive to scaffold conventional module files."
+    },
+    {
+      id: "sync-generated",
+      title: "Sync generated files",
+      tool: "syncTarget",
+      description: "Refresh generated barrels after adding a module."
+    },
+    {
+      id: "validate-target",
+      title: "Validate target",
+      tool: "lintTarget",
+      description: "Run validation commands that prove the scaffold matches Akan conventions."
+    }
+  ],
+  predictedChanges: [
+    { target: "*/lib/<module>/*", action: "create", reason: "New module source files are scaffolded." },
+    { target: "*/lib/cnst.ts", action: "sync", reason: "Generated constant barrel may include the new module." },
+    { target: "*/lib/srv.ts", action: "sync", reason: "Generated service barrel may include the new module." },
+    { target: "*/lib/sig.ts", action: "sync", reason: "Generated signal barrel may include the new module." }
+  ],
+  validation: baseValidation,
+  completionCriteria: [
+    "Module abstract and conventional files exist.",
+    "Generated files are refreshed with sync.",
+    "Lint passes for the target."
+  ]
+};
+
+// pkgs/@akanjs/cli/workflows/createScalar.ts
+var createScalarWorkflowSpec = {
+  schemaVersion: 1,
+  name: "create-scalar",
+  description: "Plan a reusable scalar value module without database ownership.",
+  whenToUse: "Use when the user asks for a reusable value object, primitive domain type, or shared scalar.",
+  inputs: {
+    ...sysInputs,
+    scalar: { type: "string", required: true, description: "Name of the scalar to create." }
+  },
+  optionalSurfaces: {
+    dictionary: "include"
+  },
+  steps: [
+    {
+      id: "inspect-system",
+      title: "Inspect target system",
+      tool: "inspectSystem",
+      description: "Check the target app or library before planning a scalar."
+    },
+    {
+      id: "create-scalar",
+      title: "Create scalar",
+      tool: "createScalar",
+      description: "Use the existing create-scalar primitive to scaffold scalar files."
+    },
+    {
+      id: "sync-generated",
+      title: "Sync generated files",
+      tool: "syncTarget",
+      description: "Refresh generated barrels after adding a scalar."
+    },
+    {
+      id: "validate-target",
+      title: "Validate target",
+      tool: "lintTarget",
+      description: "Run validation commands for the scalar target."
+    }
+  ],
+  predictedChanges: [
+    { target: "*/lib/__scalar/<scalar>/*", action: "create", reason: "New scalar source files are scaffolded." }
+  ],
+  validation: baseValidation,
+  completionCriteria: ["Scalar files exist under __scalar.", "Generated files are refreshed.", "Lint passes."]
+};
+
+// pkgs/@akanjs/cli/workflows/createUi.ts
+var createUiWorkflowSpec = {
+  schemaVersion: 1,
+  name: "create-ui",
+  description: "Plan creation of a conventional module UI surface.",
+  whenToUse: "Use when the user asks for a View, Unit, Template, Zone, or Util component for an existing module.",
+  inputs: {
+    ...sysInputs,
+    ...moduleInput,
+    surface: {
+      type: "string",
+      required: true,
+      description: "UI surface to create.",
+      allowedValues: ["view", "unit", "template", "zone", "util"]
+    }
+  },
+  optionalSurfaces: {
+    dictionary: "infer",
+    store: "infer"
+  },
+  steps: [
+    {
+      id: "inspect-module",
+      title: "Inspect module",
+      tool: "inspectModule",
+      description: "Read existing module context and component files."
+    },
+    {
+      id: "create-ui",
+      title: "Create UI surface",
+      tool: "createUi",
+      description: "Create the requested UI surface through an Akan primitive."
+    },
+    {
+      id: "sync-generated",
+      title: "Sync generated files",
+      tool: "syncTarget",
+      description: "Refresh UI barrels after adding a component."
+    },
+    {
+      id: "validate-target",
+      title: "Validate target",
+      tool: "lintTarget",
+      description: "Run validation commands for the target."
+    }
+  ],
+  predictedChanges: [
+    { target: "*/lib/<module>/<Module>.<Surface>.tsx", action: "create", reason: "New UI component is created." },
+    { target: "*/ui/index.ts", action: "sync", reason: "Generated UI barrel may include the new component." }
+  ],
+  validation: baseValidation,
+  completionCriteria: ["Requested UI surface exists.", "UI barrels are refreshed.", "Lint passes."]
+};
+
+// pkgs/@akanjs/cli/workflows/index.ts
+var workflowSpecs = [
+  createModuleWorkflowSpec,
+  createScalarWorkflowSpec,
+  createUiWorkflowSpec,
+  addFieldWorkflowSpec,
+  addEnumFieldWorkflowSpec,
+  addMutationWorkflowSpec,
+  addSliceWorkflowSpec
+];
+
+// pkgs/@akanjs/cli/workflow/workflow.runner.ts
+var resolvePath = (filePath) => path.isAbsolute(filePath) ? filePath : path.join(process.cwd(), filePath);
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isWorkflowPlan = (value) => {
+  if (!isRecord(value))
+    return false;
+  return value.schemaVersion === 1 && value.mode === "plan" && typeof value.workflow === "string";
+};
+var isWorkflowApplyReport = (value) => {
+  if (!isRecord(value))
+    return false;
+  return value.schemaVersion === 1 && (value.mode === "apply" || value.mode === "dry-run") && isWorkflowPlan(value.plan);
+};
+var isWorkflowRunArtifact = (value) => {
+  if (!isRecord(value))
+    return false;
+  return value.schemaVersion === 1 && (typeof value.mode === "string" || typeof value.command === "string");
+};
+var failedPlan = (workflow, diagnostics) => ({
+  schemaVersion: 1,
+  workflow,
+  mode: "plan",
+  inputs: {},
+  optionalSurfaces: {},
+  steps: [],
+  predictedChanges: [],
+  validation: [],
+  diagnostics,
+  recommendations: [],
+  requiresApproval: true,
+  approval: workflowPlanApproval
+});
+var failedApplyReport = (workflow, diagnostics, plan) => createWorkflowApplyReport({
+  workflow,
+  mode: "apply",
+  changedFiles: [],
+  generatedFiles: [],
+  commands: [],
+  diagnostics,
+  nextActions: [],
+  plan: plan ?? failedPlan(workflow, diagnostics)
+});
+var commandForShell = (command) => command.startsWith("akan ") ? `bun run ${command}` : command;
+var inferValidationKind = (command) => {
+  if (command.kind)
+    return command.kind;
+  if (/\bakan\s+sync\b/.test(command.command))
+    return "sync";
+  if (/\bakan\s+lint\b/.test(command.command))
+    return "lint";
+  if (/\bakan\s+typecheck\b/.test(command.command))
+    return "typecheck";
+  if (/\bakan\s+doctor\b/.test(command.command))
+    return "doctor";
+  return "custom";
+};
+var classifyValidationFailure = (command, error) => {
+  const output = `${error.stdout ?? ""}
+${error.stderr ?? ""}
+${error.message ?? ""}`.toLowerCase();
+  if (error.code === 127 || output.includes("command not found") || output.includes("bun: command not found")) {
+    return "environment";
+  }
+  if (output.includes("biome.json") || output.includes("biome configuration") || output.includes("configuration file") || output.includes("invalid configuration") || output.includes("failed to load")) {
+    return "workspace-config";
+  }
+  const kind = inferValidationKind(command);
+  if (kind === "lint" || kind === "typecheck" || kind === "sync")
+    return "source-change";
+  return "unknown";
+};
+var defaultValidationExecutor = (workspace) => async (command) => {
+  const kind = inferValidationKind(command);
+  try {
+    const stdout = await workspace.spawn("bash", ["-lc", commandForShell(command.command)], {
+      cwd: workspace.workspaceRoot
+    });
+    return {
+      command: command.command,
+      reason: command.reason,
+      kind,
+      status: "passed",
+      exitCode: 0,
+      stdout
+    };
+  } catch (error) {
+    const commandError = error;
+    return {
+      command: command.command,
+      reason: command.reason,
+      kind,
+      status: "failed",
+      exitCode: commandError.code ?? 1,
+      failureScope: classifyValidationFailure(command, commandError),
+      stdout: commandError.stdout,
+      stderr: commandError.stderr ?? commandError.message
+    };
+  }
+};
+var readJsonFile = async (filePath) => JSON.parse(await readFile(resolvePath(filePath), "utf8"));
+var planInputString = (plan, key) => {
+  const value = plan.inputs[key];
+  return typeof value === "string" ? value : "";
+};
+var workflowPathsForPlanLike = (plan) => {
+  const app = planInputString(plan, "app");
+  const module = planInputString(plan, "module");
+  const moduleClass = module ? capitalize(module) : "<Module>";
+  return plan.predictedChanges.map((change) => change.target.replace(/^\*\//, app ? `apps/${app}/` : "").replaceAll("<module>", module || "<module>").replaceAll("<Module>", moduleClass));
+};
+var workflowDiagnosticFromDoctor = (diagnostic, fallbackScope) => ({
+  severity: diagnostic.severity,
+  code: diagnostic.code,
+  message: diagnostic.message,
+  scope: diagnostic.scope ?? fallbackScope,
+  failureScope: (diagnostic.scope ?? fallbackScope) === "baseline" ? "workspace-config" : (diagnostic.scope ?? fallbackScope) === "workflow" ? "source-change" : "unknown",
+  context: diagnostic.context
+});
+var baselineBlockerCachePath = (workflow) => `.akan/workflows/baseline/${workflow}.json`;
+var blockerFingerprint = (blocker) => [blocker.failureScope, blocker.code, blocker.command ?? "", blocker.kind ?? "", blocker.message].join("|");
+var applyBaselineBlockerCache = async (workspace, report) => {
+  const cacheableBlockers = report.knownBlockers.filter((blocker) => blocker.failureScope === "workspace-config" || blocker.failureScope === "environment");
+  if (cacheableBlockers.length === 0)
+    return report;
+  const cachePath = baselineBlockerCachePath(report.workflow);
+  const cached = (await workspace.exists(cachePath) ? await workspace.readJson(cachePath) : null) ?? { schemaVersion: 1, workflow: report.workflow, blockers: [] };
+  const knownFingerprints = new Set(cached.blockers.map((blocker) => blocker.fingerprint));
+  const now = new Date().toISOString();
+  const blockers = new Map(cached.blockers.map((blocker) => [blocker.fingerprint, blocker]));
+  for (const blocker of cacheableBlockers) {
+    const fingerprint = blockerFingerprint(blocker);
+    blockers.set(fingerprint, {
+      fingerprint,
+      code: blocker.code,
+      message: blocker.message,
+      failureScope: blocker.failureScope,
+      command: blocker.command,
+      kind: blocker.kind,
+      lastSeenAt: now
+    });
+  }
+  await workspace.writeFile(cachePath, jsonText({ schemaVersion: 1, workflow: report.workflow, blockers: [...blockers.values()] }), { silent: true });
+  const knownBlockers = report.knownBlockers.map((blocker) => {
+    if (!knownFingerprints.has(blockerFingerprint(blocker)))
+      return blocker;
+    return {
+      ...blocker,
+      known: true,
+      message: `Known baseline blocker, unrelated to this source change: ${blocker.message}`
+    };
+  });
+  return {
+    ...report,
+    knownBlockers,
+    baselineSummary: {
+      ...report.baselineSummary,
+      knownBlockerCount: knownBlockers.filter((blocker) => blocker.known).length
+    }
+  };
+};
+var withBaselineDetailsPolicy = (report, includeBaselineDetails) => {
+  const baselineDiagnostics = report.baselineDiagnostics ?? [];
+  return {
+    ...report,
+    baselineSummary: createWorkflowBaselineSummary(baselineDiagnostics, {
+      detailsIncluded: includeBaselineDetails,
+      knownBlockerCount: report.knownBlockers.filter((blocker) => blocker.known).length
+    }),
+    baselineDiagnostics: includeBaselineDetails ? baselineDiagnostics : []
+  };
+};
+
+class WorkflowRunner extends runner("workflow") {
+  list({ format = "markdown" } = {}) {
+    const workflows = listWorkflowSpecs(workflowSpecs);
+    if (format === "json")
+      return jsonText({
+        schemaVersion: 1,
+        workflows: workflows.map(({ name, description, whenToUse }) => ({ name, description, whenToUse }))
+      });
+    return renderWorkflowList(workflows);
+  }
+  explain(workflow, { format = "markdown" } = {}) {
+    const spec = getWorkflowSpec(workflowSpecs, workflow);
+    if (!spec)
+      throw new Error(`Unknown workflow: ${workflow}. Run \`akan workflow list\` to see available workflows.`);
+    return format === "json" ? jsonText(spec) : renderWorkflowExplain(spec);
+  }
+  async plan(workflow, inputs, { format = "markdown", out = null } = {}) {
+    const spec = getWorkflowSpec(workflowSpecs, workflow);
+    if (!spec)
+      throw new Error(`Unknown workflow: ${workflow}. Run \`akan workflow list\` to see available workflows.`);
+    const plan = createWorkflowPlan(spec, compactWorkflowInputs(inputs));
+    if (out) {
+      const outPath = resolvePath(out);
+      await mkdir(path.dirname(outPath), { recursive: true });
+      await writeFile(outPath, jsonText(plan));
+    }
+    return format === "json" ? jsonText(plan) : renderWorkflowPlan(plan);
+  }
+  async apply(planPath, {
+    dryRun = false,
+    format = "markdown",
+    registry,
+    workspace
+  } = {}) {
+    const renderApplyReport = async (report) => {
+      if (!workspace)
+        return renderWorkflowApply(report, format);
+      const { artifact } = await writeWorkflowRunArtifact(workspace, report);
+      return renderWorkflowApply(artifact, format);
+    };
+    let plan;
+    try {
+      const parsed = JSON.parse(await readFile(resolvePath(planPath), "utf8"));
+      if (!isWorkflowPlan(parsed)) {
+        const report = failedApplyReport("unknown", [
+          {
+            severity: "error",
+            code: "workflow-plan-invalid",
+            message: `Workflow plan file is invalid: ${planPath}.`
+          }
+        ]);
+        return await renderApplyReport(report);
+      }
+      plan = parsed;
+    } catch (error) {
+      const report = failedApplyReport("unknown", [
+        {
+          severity: "error",
+          code: "workflow-plan-read-failed",
+          message: `Could not read workflow plan file: ${planPath}. ${error instanceof Error ? error.message : ""}`.trim()
+        }
+      ]);
+      return await renderApplyReport(report);
+    }
+    const spec = getWorkflowSpec(workflowSpecs, plan.workflow);
+    if (!spec) {
+      const report = failedApplyReport(plan.workflow, [
+        {
+          severity: "error",
+          code: "workflow-unknown",
+          message: `Unknown workflow in plan: ${plan.workflow}.`
+        }
+      ], plan);
+      return await renderApplyReport(report);
+    }
+    if (dryRun)
+      return await renderApplyReport(createDryRunWorkflowApplyReport(plan));
+    if (!registry) {
+      const report = failedApplyReport(plan.workflow, [
+        {
+          severity: "error",
+          code: "workflow-registry-missing",
+          message: "Workflow apply requires a step runner registry."
+        }
+      ], plan);
+      return await renderApplyReport(report);
+    }
+    return await renderApplyReport(await new WorkflowExecutor(registry, workspace).apply(plan));
+  }
+  async validate(runIdOrPlan, {
+    format = "markdown",
+    workspace,
+    execute,
+    includeBaselineDetails = false
+  }) {
+    const loaded = await this.loadValidationTarget(runIdOrPlan, workspace);
+    const doctor = await AkanContextAnalyzer.doctor(workspace, {
+      strict: true,
+      runIdOrPlan,
+      changedFiles: loaded.changedFiles
+    });
+    const report = withBaselineDetailsPolicy(await applyBaselineBlockerCache(workspace, await createWorkflowValidationRunReport({
+      workflow: loaded.plan?.workflow ?? loaded.workflow,
+      source: loaded.source,
+      plan: loaded.plan,
+      commands: loaded.commands,
+      execute: execute ?? defaultValidationExecutor(workspace),
+      diagnostics: loaded.diagnostics,
+      baselineDiagnostics: (doctor.baselineDiagnostics ?? []).map((diagnostic) => workflowDiagnosticFromDoctor(diagnostic, "baseline")),
+      workflowDiagnostics: (doctor.workflowDiagnostics ?? []).map((diagnostic) => workflowDiagnosticFromDoctor(diagnostic, "workflow")),
+      repairActions: loaded.repairActions
+    })), includeBaselineDetails);
+    await writeWorkflowRunArtifact(workspace, report);
+    return renderWorkflowValidation(report, format);
+  }
+  async report(runId, { format = "markdown", workspace }) {
+    try {
+      return renderWorkflowRunArtifact(await readWorkflowRunArtifact(workspace, runId), format);
+    } catch (error) {
+      const report = await createWorkflowValidationRunReport({
+        runId,
+        workflow: "unknown",
+        source: { type: "run-report", runId },
+        commands: [],
+        execute: async (command) => ({
+          command: command.command,
+          reason: command.reason,
+          status: "failed",
+          exitCode: 1
+        }),
+        diagnostics: [
+          {
+            severity: "error",
+            code: "workflow-run-read-failed",
+            message: `Could not read workflow run report: ${runId}. ${error instanceof Error ? error.message : ""}`.trim()
+          }
+        ]
+      });
+      return renderWorkflowValidation(report, format);
+    }
+  }
+  async loadValidationTarget(runIdOrPlan, workspace) {
+    const loadFromArtifact = (artifact, sourcePath) => {
+      if (isWorkflowApplyReport(artifact)) {
+        return {
+          workflow: artifact.workflow,
+          source: { type: "apply-report", path: sourcePath, runId: artifact.runId },
+          plan: artifact.plan,
+          commands: artifact.recommendedValidationCommands.length ? artifact.recommendedValidationCommands : workflowCommandsForPlan(artifact.plan),
+          diagnostics: artifact.diagnostics,
+          changedFiles: artifact.changedFiles.map((file) => file.path),
+          repairActions: []
+        };
+      }
+      if ("mode" in artifact && artifact.mode === "validate") {
+        return {
+          workflow: artifact.workflow,
+          source: { type: "run-report", runId: artifact.runId },
+          plan: artifact.plan,
+          commands: artifact.plan ? workflowCommandsForPlan(artifact.plan) : [],
+          diagnostics: artifact.diagnostics,
+          changedFiles: [],
+          repairActions: artifact.repairActions
+        };
+      }
+      return {
+        workflow: "unknown",
+        source: { type: "run-report", runId: runIdOrPlan },
+        plan: undefined,
+        commands: [],
+        diagnostics: [
+          {
+            severity: "error",
+            code: "workflow-validation-source-unsupported",
+            message: `Workflow validation source is not supported: ${runIdOrPlan}.`
+          }
+        ],
+        changedFiles: [],
+        repairActions: []
+      };
+    };
+    try {
+      const parsed = await readJsonFile(runIdOrPlan);
+      if (isWorkflowPlan(parsed)) {
+        return {
+          workflow: parsed.workflow,
+          source: { type: "plan", path: resolvePath(runIdOrPlan) },
+          plan: parsed,
+          commands: workflowCommandsForPlan(parsed),
+          diagnostics: parsed.diagnostics,
+          changedFiles: workflowPathsForPlanLike(parsed),
+          repairActions: []
+        };
+      }
+      if (isWorkflowRunArtifact(parsed))
+        return loadFromArtifact(parsed, resolvePath(runIdOrPlan));
+    } catch {}
+    try {
+      const artifact = await readWorkflowRunArtifact(workspace, runIdOrPlan);
+      return loadFromArtifact(artifact, runIdOrPlan);
+    } catch (error) {
+      return {
+        workflow: "unknown",
+        source: { type: "run-report", runId: runIdOrPlan },
+        plan: undefined,
+        commands: [],
+        diagnostics: [
+          {
+            severity: "error",
+            code: "workflow-validation-source-read-failed",
+            message: `Could not read workflow validation source: ${runIdOrPlan}. ${error instanceof Error ? error.message : ""}`.trim()
+          }
+        ],
+        changedFiles: [],
+        repairActions: []
+      };
+    }
+  }
+}
+
+export { WorkflowRunner };