@akanjs/devkit 2.3.9-rc.3 → 2.3.9-rc.4

package/akanContext.ts

@@ -713,8 +713,14 @@ export class AkanContextAnalyzer {
     };
   }
 
-  static findModules(context: AkanWorkspaceContext, moduleName?: string | null) {
-    const modules = [...context.apps, ...context.libs].flatMap((sys) => sys.modules);
+  static findModules(
+    context: AkanWorkspaceContext,
+    moduleName?: string | null,
+    { app = null }: { app?: string | null } = {},
+  ) {
+    const modules = [...context.apps, ...context.libs]
+      .filter((sys) => !app || sys.name === app)
+      .flatMap((sys) => sys.modules);
     return moduleName
       ? modules.filter((module) => module.name === moduleName || module.folderName === moduleName)
       : modules;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.3.9-rc.3",
+  "version": "2.3.9-rc.4",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -32,7 +32,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.3.9-rc.3",
+    "akanjs": "2.3.9-rc.4",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/workflow/artifacts.ts

@@ -0,0 +1,396 @@
+import type { Workspace } from "../commandDecorators";
+import type {
+  GeneratedSyncState,
+  PrimitiveChangedFile,
+  PrimitiveGeneratedFile,
+  RepairAction,
+  RepairReport,
+  WorkflowApplyCommand,
+  WorkflowApplyReport,
+  WorkflowDiagnostic,
+  WorkflowFailureScope,
+  WorkflowKnownBlocker,
+  WorkflowPlan,
+  WorkflowRunArtifact,
+  WorkflowRunSource,
+  WorkflowValidationCommandResult,
+  WorkflowValidationRunReport,
+  WorkflowValidationStatus,
+} from "./types";
+import { commandStatus, jsonText, uniqueBy, workflowStatus } from "./utils";
+
+export const createWorkflowApplyReport = ({
+  workflow,
+  mode,
+  changedFiles = [],
+  generatedFiles = [],
+  appliedCommands = [],
+  recommendedValidationCommands,
+  commands = [],
+  diagnostics = [],
+  recommendations = [],
+  nextActions = [],
+  plan,
+}: Omit<
+  WorkflowApplyReport,
+  | "schemaVersion"
+  | "runId"
+  | "applyReportPath"
+  | "validationTarget"
+  | "status"
+  | "appliedCommands"
+  | "recommendedValidationCommands"
+  | "commands"
+  | "recommendations"
+> & {
+  appliedCommands?: WorkflowApplyCommand[];
+  recommendedValidationCommands?: WorkflowApplyCommand[];
+  commands?: WorkflowApplyCommand[];
+  recommendations?: WorkflowApplyReport["recommendations"];
+}): WorkflowApplyReport => {
+  const validationCommands = recommendedValidationCommands ?? commands;
+  return {
+    schemaVersion: 1,
+    workflow,
+    mode,
+    status: workflowStatus(diagnostics),
+    changedFiles: uniqueBy(changedFiles, (file) => `${file.action}:${file.path}:${file.reason}`),
+    generatedFiles: uniqueBy(generatedFiles, (file) => `${file.action}:${file.path}:${file.reason}`),
+    appliedCommands: uniqueBy(appliedCommands, (command) => command.command),
+    recommendedValidationCommands: uniqueBy(validationCommands, (command) => command.command),
+    commands: uniqueBy(validationCommands, (command) => command.command),
+    diagnostics,
+    recommendations: uniqueBy(recommendations, (recommendation) => `${recommendation.kind}:${recommendation.code}`),
+    nextActions: uniqueBy(nextActions, (action) => action.command),
+    plan,
+  };
+};
+
+export const resolveWorkflowCommand = (command: string, plan: WorkflowPlan) => {
+  const target = typeof plan.inputs.app === "string" ? plan.inputs.app : "<app-or-lib>";
+  return command
+    .replaceAll("<app-or-lib-or-pkg>", target)
+    .replaceAll("<app-or-lib>", target)
+    .replaceAll("<app-name>", target);
+};
+
+export const workflowCommandsForPlan = (plan: WorkflowPlan) =>
+  plan.validation.map((validation) => ({
+    command: resolveWorkflowCommand(validation.command, plan),
+    reason: validation.reason,
+    kind: validation.kind,
+  })) satisfies WorkflowApplyCommand[];
+
+export const workflowRunsDir = ".akan/workflows/runs";
+
+export const createWorkflowRunId = (prefix = "run") =>
+  `${prefix}-${new Date()
+    .toISOString()
+    .replace(/[-:.TZ]/g, "")
+    .slice(0, 14)}-${Math.random().toString(36).slice(2, 8)}`;
+
+const getRunId = (artifact: WorkflowRunArtifact) => {
+  if ("runId" in artifact && artifact.runId) return artifact.runId;
+  return createWorkflowRunId("mode" in artifact ? artifact.mode : artifact.kind);
+};
+
+export const workflowRunArtifactPath = (runId: string) => `${workflowRunsDir}/${runId}.json`;
+
+const withWorkflowRunMetadata = (
+  artifact: WorkflowRunArtifact,
+  runId: string,
+  artifactPath: string,
+): WorkflowRunArtifact => {
+  if ("mode" in artifact && (artifact.mode === "apply" || artifact.mode === "dry-run")) {
+    return { ...artifact, runId, applyReportPath: artifactPath, validationTarget: artifactPath };
+  }
+  if ("kind" in artifact) return { ...artifact, runId, repairReportPath: artifactPath };
+  return artifact;
+};
+
+export const writeWorkflowRunArtifact = async (workspace: Workspace, artifact: WorkflowRunArtifact) => {
+  const runId = getRunId(artifact);
+  const artifactPath = workflowRunArtifactPath(runId);
+  const artifactWithMetadata = withWorkflowRunMetadata(artifact, runId, artifactPath);
+  await workspace.writeFile(artifactPath, jsonText(artifactWithMetadata), { silent: true });
+  return { runId, path: artifactPath, artifact: artifactWithMetadata };
+};
+
+export const workflowSyncDir = ".akan/workflows/sync";
+
+const syncStateSlug = (target: string) =>
+  target
+    .trim()
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+
+export const workflowSyncStatePath = (target: string) => `${workflowSyncDir}/${syncStateSlug(target) || "target"}.json`;
+
+export const generatedFilePathsForTarget = (targetRoot: string, reason = "Generated files were refreshed by sync.") =>
+  [
+    { path: `${targetRoot}/lib/cnst.ts`, action: "sync", reason },
+    { path: `${targetRoot}/lib/dict.ts`, action: "sync", reason },
+    { path: `${targetRoot}/lib/option.ts`, action: "sync", reason },
+    { path: `${targetRoot}/lib/index.ts`, action: "sync", reason },
+  ] satisfies PrimitiveGeneratedFile[];
+
+export const writeGeneratedSyncState = async (workspace: Workspace, state: GeneratedSyncState) => {
+  const statePath = workflowSyncStatePath(state.target);
+  await workspace.writeFile(statePath, jsonText(state), { silent: true });
+  return statePath;
+};
+
+export const readWorkflowRunArtifact = async (workspace: Workspace, runId: string) => {
+  const artifactPath = workflowRunArtifactPath(runId);
+  if (!(await workspace.exists(artifactPath))) throw new Error(`Workflow run artifact does not exist: ${artifactPath}`);
+  return (await workspace.readJson(artifactPath)) as WorkflowRunArtifact;
+};
+
+export type WorkflowValidationCommandExecutor = (
+  command: WorkflowApplyCommand,
+) => Promise<WorkflowValidationCommandResult>;
+
+const failedCommandScopes = (commands: readonly WorkflowValidationCommandResult[]) =>
+  commands.filter((command) => command.status === "failed").map((command) => command.failureScope ?? "unknown");
+
+const errorDiagnosticScopes = (diagnostics: readonly WorkflowDiagnostic[]) =>
+  diagnostics
+    .filter((diagnostic) => diagnostic.severity === "error")
+    .map(
+      (diagnostic) =>
+        diagnostic.failureScope ??
+        (diagnostic.scope === "baseline"
+          ? "workspace-config"
+          : diagnostic.scope === "workflow"
+            ? "source-change"
+            : "unknown"),
+    );
+
+const hasScopeFailure = (
+  scopes: readonly WorkflowFailureScope[],
+  scope: WorkflowFailureScope,
+  diagnostics: readonly WorkflowDiagnostic[] = [],
+) =>
+  scopes.includes(scope) ||
+  diagnostics.some((diagnostic) => diagnostic.severity === "error" && diagnostic.failureScope === scope);
+
+const statusForScope = (
+  commands: readonly WorkflowValidationCommandResult[],
+  diagnostics: readonly WorkflowDiagnostic[],
+  scopes: readonly WorkflowFailureScope[],
+  expectedScope: WorkflowFailureScope,
+): WorkflowValidationStatus => {
+  const hasCommands = commands.length > 0 || diagnostics.length > 0;
+  if (!hasCommands) return "unknown";
+  return hasScopeFailure(scopes, expectedScope, diagnostics) ? "failed" : "passed";
+};
+
+const createKnownBlockers = (
+  commands: readonly WorkflowValidationCommandResult[],
+  diagnostics: readonly WorkflowDiagnostic[],
+): WorkflowKnownBlocker[] => {
+  const commandBlockers = commands
+    .filter(
+      (command) =>
+        command.status === "failed" &&
+        (command.failureScope === "workspace-config" || command.failureScope === "environment"),
+    )
+    .map((command) => ({
+      code: `workflow-validation-${command.failureScope}`,
+      message: `${command.failureScope === "environment" ? "Environment" : "Workspace configuration"} blocker: ${command.command}`,
+      failureScope: command.failureScope ?? "unknown",
+      command: command.command,
+      kind: command.kind,
+      count: 1,
+    }));
+  const diagnosticBlockers = diagnostics
+    .filter(
+      (diagnostic) =>
+        diagnostic.severity === "error" &&
+        (diagnostic.failureScope === "workspace-config" ||
+          diagnostic.failureScope === "environment" ||
+          diagnostic.scope === "baseline"),
+    )
+    .map((diagnostic) => ({
+      code: diagnostic.code,
+      message: diagnostic.message,
+      failureScope: diagnostic.failureScope ?? ("workspace-config" as const),
+      command: diagnostic.command,
+      kind: diagnostic.kind,
+      count: 1,
+    }));
+  const grouped = new Map<string, WorkflowKnownBlocker>();
+  for (const blocker of [...commandBlockers, ...diagnosticBlockers]) {
+    const key = `${blocker.failureScope}:${blocker.code}:${blocker.command ?? ""}:${blocker.message}`;
+    const existing = grouped.get(key);
+    if (existing) existing.count += blocker.count;
+    else grouped.set(key, blocker);
+  }
+  return [...grouped.values()];
+};
+
+const createValidationStatuses = (
+  commands: readonly WorkflowValidationCommandResult[],
+  diagnostics: readonly WorkflowDiagnostic[],
+) => {
+  const scopes = [...failedCommandScopes(commands), ...errorDiagnosticScopes(diagnostics)];
+  const sourceStatus = statusForScope(commands, diagnostics, scopes, "source-change");
+  const workspaceStatus =
+    hasScopeFailure(scopes, "workspace-config", diagnostics) || hasScopeFailure(scopes, "environment", diagnostics)
+      ? "failed"
+      : commands.length || diagnostics.length
+        ? "passed"
+        : "unknown";
+  const overallStatus = hasScopeFailure(scopes, "source-change", diagnostics)
+    ? "failed"
+    : hasScopeFailure(scopes, "workspace-config", diagnostics)
+      ? "blocked-by-workspace-config"
+      : hasScopeFailure(scopes, "environment", diagnostics)
+        ? "blocked-by-environment"
+        : workflowStatus(diagnostics) === "failed" || commandStatus(commands) === "failed"
+          ? "failed"
+          : "passed";
+  return { sourceStatus, workspaceStatus, overallStatus };
+};
+
+export const createWorkflowValidationRunReport = async ({
+  runId = createWorkflowRunId("validation"),
+  workflow,
+  source,
+  plan,
+  commands,
+  execute,
+  diagnostics = [],
+  baselineDiagnostics = [],
+  workflowDiagnostics = [],
+  repairActions = [],
+}: {
+  runId?: string;
+  workflow: string;
+  source: WorkflowRunSource;
+  plan?: WorkflowPlan;
+  commands: WorkflowApplyCommand[];
+  execute: WorkflowValidationCommandExecutor;
+  diagnostics?: WorkflowDiagnostic[];
+  baselineDiagnostics?: WorkflowDiagnostic[];
+  workflowDiagnostics?: WorkflowDiagnostic[];
+  repairActions?: RepairAction[];
+}): Promise<WorkflowValidationRunReport> => {
+  const results: WorkflowValidationCommandResult[] = [];
+  for (const command of commands) {
+    results.push(await execute(command));
+  }
+  const commandDiagnostics = results.flatMap((result) =>
+    result.status === "failed"
+      ? [
+          {
+            severity: "error" as const,
+            code: "workflow-validation-command-failed",
+            message: `Validation command failed: ${result.command}`,
+            command: result.command,
+            kind: result.kind,
+            failureScope: result.failureScope,
+          },
+        ]
+      : [],
+  );
+  const reportDiagnostics = [...diagnostics, ...commandDiagnostics];
+  const scopedDiagnostics = [...reportDiagnostics, ...baselineDiagnostics, ...workflowDiagnostics];
+  const statuses = createValidationStatuses(results, scopedDiagnostics);
+  return {
+    schemaVersion: 1,
+    runId,
+    workflow,
+    mode: "validate",
+    source,
+    status: statuses.overallStatus === "passed" ? "passed" : "failed",
+    ...statuses,
+    knownBlockers: createKnownBlockers(results, scopedDiagnostics),
+    commands: results,
+    diagnostics: reportDiagnostics,
+    baselineDiagnostics,
+    workflowDiagnostics,
+    repairActions: uniqueBy(repairActions, (action) => action.command),
+    nextActions: results
+      .filter((result) => result.status === "failed")
+      .map((result) => ({ command: result.command, reason: "Re-run this validation command after repair." })),
+    plan,
+  };
+};
+
+export const createDryRunWorkflowApplyReport = (plan: WorkflowPlan) => {
+  const changedFiles: PrimitiveChangedFile[] = plan.predictedChanges.flatMap((change) => {
+    if (change.action !== "create" && change.action !== "modify") return [];
+    return [
+      {
+        path: change.target,
+        action: change.action,
+        reason: change.reason,
+      },
+    ];
+  });
+  const generatedFiles: PrimitiveGeneratedFile[] = plan.predictedChanges.flatMap((change) => {
+    if (change.action !== "sync") return [];
+    return [
+      {
+        path: change.target,
+        action: "sync",
+        reason: change.reason,
+      },
+    ];
+  });
+  const diagnostics = [...plan.diagnostics];
+  return createWorkflowApplyReport({
+    workflow: plan.workflow,
+    mode: "dry-run",
+    changedFiles,
+    generatedFiles,
+    commands: workflowCommandsForPlan(plan),
+    diagnostics,
+    recommendations: plan.recommendations,
+    nextActions: workflowCommandsForPlan(plan),
+    plan,
+  });
+};
+
+export const createRepairReport = ({
+  command,
+  kind,
+  target = null,
+  diagnostics = [],
+  repairActions = [],
+  nextActions = [],
+  commands = [],
+  generatedFiles = [],
+  syncedAt,
+}: Omit<
+  RepairReport,
+  | "schemaVersion"
+  | "runId"
+  | "repairReportPath"
+  | "status"
+  | "target"
+  | "diagnostics"
+  | "repairActions"
+  | "nextActions"
+  | "commands"
+> &
+  Partial<
+    Pick<
+      RepairReport,
+      "target" | "diagnostics" | "repairActions" | "nextActions" | "commands" | "generatedFiles" | "syncedAt"
+    >
+  >): RepairReport => ({
+  schemaVersion: 1,
+  command,
+  kind,
+  target,
+  status: workflowStatus(diagnostics) === "failed" || commandStatus(commands) === "failed" ? "failed" : "passed",
+  diagnostics,
+  repairActions: uniqueBy(repairActions, (action) => action.command),
+  nextActions: uniqueBy(nextActions, (action) => action.command),
+  commands,
+  generatedFiles,
+  ...(syncedAt ? { syncedAt } : {}),
+});

package/workflow/executor.ts

@@ -0,0 +1,258 @@
+import { capitalize } from "akanjs/common";
+import type { Sys, Workspace } from "../commandDecorators";
+import { AppExecutor, LibExecutor } from "../executors";
+import { createWorkflowApplyReport, workflowCommandsForPlan } from "./artifacts";
+import type {
+  PrimitiveChangedFile,
+  PrimitiveGeneratedFile,
+  PrimitiveNextAction,
+  PrimitiveWriteReport,
+  WorkflowApplyCommand,
+  WorkflowDiagnostic,
+  WorkflowInputValue,
+  WorkflowPlan,
+  WorkflowPrimitiveOperations,
+  WorkflowStep,
+  WorkflowStepRegistry,
+  WorkflowStepResult,
+} from "./types";
+
+export const workflowStepKey = (workflow: string, stepId: string) => `${workflow}:${stepId}`;
+
+export const primitiveReportToWorkflowStepResult = (report: PrimitiveWriteReport): WorkflowStepResult => ({
+  changedFiles: report.changedFiles,
+  generatedFiles: report.generatedFiles,
+  commands: report.validationCommands,
+  diagnostics: report.diagnostics,
+  recommendations: [],
+  nextActions: report.nextActions,
+});
+
+const workflowStringInput = (value: WorkflowInputValue | undefined) => (typeof value === "string" ? value : null);
+const workflowStringListInput = (value: WorkflowInputValue | undefined) =>
+  Array.isArray(value) ? value.join(",") : null;
+
+const resolveWorkflowSys = async (workspace: Workspace, target: string | null): Promise<Sys | null> => {
+  if (!target) return null;
+  const [apps, libs] = await workspace.getSyss();
+  if (apps.includes(target)) return AppExecutor.from(workspace, target);
+  if (libs.includes(target)) return LibExecutor.from(workspace, target);
+  return null;
+};
+
+const targetMissing = (input = "app"): WorkflowDiagnostic => ({
+  severity: "error",
+  code: "workflow-target-missing",
+  input,
+  message: "Workflow target app or library was not found.",
+});
+
+const inputMissing = (input: string): WorkflowDiagnostic => ({
+  severity: "error",
+  code: "workflow-input-missing",
+  input,
+  message: `Workflow input "${input}" is required for apply.`,
+});
+
+const unsupportedInput = (input: string, message: string): WorkflowDiagnostic => ({
+  severity: "error",
+  code: "workflow-input-unsupported",
+  input,
+  message,
+});
+
+const addFieldUiSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult => {
+  const app = workflowStringInput(plan.inputs.app);
+  const module = workflowStringInput(plan.inputs.module) ?? "<module>";
+  const field = workflowStringInput(plan.inputs.field) ?? "<field>";
+  const typeName = workflowStringInput(plan.inputs.type);
+  const isNumeric = typeName === "Int" || typeName === "Float" || typeName === "integer" || typeName === "float";
+  const moduleClassName = capitalize(module);
+  const target = `${app ? `apps/${app}` : "*"}/lib/${module}/${moduleClassName}.Template.tsx`;
+  return {
+    recommendations: [
+      {
+        code: "add-field-ui-surface-review",
+        kind: "manual-action",
+        target,
+        action: isNumeric
+          ? `Review ${moduleClassName} Template/Unit/View/Store surfaces before adding ${field}; confirm the local Field.Text numeric parser/formatter, validation rule, and dictionary label pattern.`
+          : `Add ${field} to ${moduleClassName} UI surfaces only when the local Field.* pattern is clear.`,
+        confidence: "medium",
+        message: isNumeric
+          ? `No UI file was modified automatically because a safe numeric input component pattern is not yet detected for ${module}.${field}.`
+          : `Review Template/Unit/View/Store surfaces for ${module}.${field}; no UI file was modified automatically.`,
+      },
+    ],
+    nextActions: [
+      {
+        command: `akan workflow explain ${plan.workflow}`,
+        reason: "Review UI surface guidance before manually editing ambiguous UI files.",
+      },
+    ],
+  };
+};
+
+export const createWorkflowStepRegistry = ({
+  workspace,
+  createModule,
+  createScalar,
+  createUi,
+  addField,
+  addEnumField,
+}: WorkflowPrimitiveOperations): WorkflowStepRegistry => {
+  const inspect = async () => undefined;
+  const commandOnly = async () => undefined;
+
+  return {
+    inspectSystem: inspect,
+    inspectModule: inspect,
+    syncTarget: commandOnly,
+    lintTarget: commandOnly,
+    [workflowStepKey("create-module", "create-module")]: async (_step, plan) => {
+      const app = workflowStringInput(plan.inputs.app);
+      const module = workflowStringInput(plan.inputs.module);
+      const sys = await resolveWorkflowSys(workspace, app);
+      if (!sys || !module) return { diagnostics: [!sys ? targetMissing() : inputMissing("module")] };
+      return primitiveReportToWorkflowStepResult(await createModule(sys, module));
+    },
+    [workflowStepKey("create-scalar", "create-scalar")]: async (_step, plan) => {
+      const app = workflowStringInput(plan.inputs.app);
+      const scalar = workflowStringInput(plan.inputs.scalar);
+      const sys = await resolveWorkflowSys(workspace, app);
+      if (!sys || !scalar) return { diagnostics: [!sys ? targetMissing() : inputMissing("scalar")] };
+      return primitiveReportToWorkflowStepResult(await createScalar(sys, scalar));
+    },
+    [workflowStepKey("create-ui", "create-ui")]: async (_step, plan) => {
+      const surface = workflowStringInput(plan.inputs.surface);
+      if (surface !== "view" && surface !== "unit" && surface !== "template") {
+        return {
+          diagnostics: [
+            unsupportedInput("surface", "Workflow apply currently supports create-ui surfaces: view, unit, template."),
+          ],
+        };
+      }
+      return primitiveReportToWorkflowStepResult(
+        await createUi({
+          app: workflowStringInput(plan.inputs.app),
+          module: workflowStringInput(plan.inputs.module),
+          surface,
+        }),
+      );
+    },
+    [workflowStepKey("add-field", "update-constant")]: async (_step, plan) => {
+      if (workflowStringInput(plan.inputs.type)?.toLowerCase() === "enum") {
+        return primitiveReportToWorkflowStepResult(
+          await addEnumField({
+            app: workflowStringInput(plan.inputs.app),
+            module: workflowStringInput(plan.inputs.module),
+            field: workflowStringInput(plan.inputs.field),
+            values: workflowStringListInput(plan.inputs.values),
+            defaultValue: workflowStringInput(plan.inputs.default),
+          }),
+        );
+      }
+      return primitiveReportToWorkflowStepResult(
+        await addField({
+          app: workflowStringInput(plan.inputs.app),
+          module: workflowStringInput(plan.inputs.module),
+          field: workflowStringInput(plan.inputs.field),
+          type: workflowStringInput(plan.inputs.type),
+          defaultValue: workflowStringInput(plan.inputs.default),
+        }),
+      );
+    },
+    [workflowStepKey("add-field", "update-dictionary")]: inspect,
+    [workflowStepKey("add-field", "update-ui-surfaces")]: async (_step, plan) => addFieldUiSurfaceInspection(plan),
+    [workflowStepKey("add-enum-field", "update-constant")]: async (_step, plan) =>
+      primitiveReportToWorkflowStepResult(
+        await addEnumField({
+          app: workflowStringInput(plan.inputs.app),
+          module: workflowStringInput(plan.inputs.module),
+          field: workflowStringInput(plan.inputs.field),
+          values: workflowStringListInput(plan.inputs.values),
+          defaultValue: workflowStringInput(plan.inputs.default),
+        }),
+      ),
+    [workflowStepKey("add-enum-field", "update-dictionary")]: inspect,
+    [workflowStepKey("add-enum-field", "update-option")]: inspect,
+  };
+};
+
+export const createWorkflowStepCommandResult = (
+  step: WorkflowStep,
+  command: string,
+  reason: string,
+): WorkflowStepResult => ({
+  commands: [{ command, reason, stepId: step.id }],
+  nextActions: [{ command, reason }],
+});
+
+export class WorkflowExecutor {
+  constructor(private readonly registry: WorkflowStepRegistry) {}
+
+  async apply(plan: WorkflowPlan) {
+    const changedFiles: PrimitiveChangedFile[] = [];
+    const generatedFiles: PrimitiveGeneratedFile[] = [];
+    const recommendedValidationCommands: WorkflowApplyCommand[] = [];
+    const diagnostics: WorkflowDiagnostic[] = [...plan.diagnostics];
+    const recommendations = [...plan.recommendations];
+    const nextActions: PrimitiveNextAction[] = [];
+
+    if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+      return createWorkflowApplyReport({
+        workflow: plan.workflow,
+        mode: "apply",
+        changedFiles,
+        generatedFiles,
+        recommendedValidationCommands,
+        diagnostics,
+        recommendations,
+        nextActions,
+        plan,
+      });
+    }
+
+    recommendedValidationCommands.push(...workflowCommandsForPlan(plan));
+    nextActions.push(...workflowCommandsForPlan(plan));
+
+    for (const step of plan.steps) {
+      const runner =
+        this.registry[workflowStepKey(plan.workflow, step.id)] ?? this.registry[step.tool] ?? this.registry[step.id];
+      if (!runner) {
+        diagnostics.push({
+          severity: "error",
+          code: "workflow-step-unsupported",
+          message: `Workflow ${plan.workflow} step "${step.id}" is not supported by workflow apply yet.`,
+        });
+        nextActions.push({
+          command: `akan workflow explain ${plan.workflow}`,
+          reason: "Review the unsupported workflow step before retrying apply.",
+        });
+        break;
+      }
+
+      const result = await runner(step, plan);
+      if (!result) continue;
+      changedFiles.push(...(result.changedFiles ?? []));
+      generatedFiles.push(...(result.generatedFiles ?? []));
+      recommendedValidationCommands.push(...(result.commands ?? []));
+      diagnostics.push(...(result.diagnostics ?? []));
+      recommendations.push(...(result.recommendations ?? []));
+      nextActions.push(...(result.nextActions ?? []));
+      if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) break;
+    }
+
+    return createWorkflowApplyReport({
+      workflow: plan.workflow,
+      mode: "apply",
+      changedFiles,
+      generatedFiles,
+      recommendedValidationCommands,
+      diagnostics,
+      recommendations,
+      nextActions,
+      plan,
+    });
+  }
+}