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

package/workflow/plan.ts

@@ -0,0 +1,375 @@
+import { capitalize } from "akanjs/common";
+import { coerceFieldDefault, moduleSourcePaths } from "./source";
+import type {
+  WorkflowDiagnostic,
+  WorkflowInputSpec,
+  WorkflowInputValue,
+  WorkflowPlan,
+  WorkflowPlanInputs,
+  WorkflowRecommendation,
+  WorkflowSpec,
+  WorkflowSurfaceMode,
+} from "./types";
+import { addFieldUiPolicyForType } from "./uiPolicy";
+
+const surfaceModes = new Set<WorkflowSurfaceMode>(["infer", "include", "skip"]);
+
+const parseStringList = (value: unknown) => {
+  if (Array.isArray(value)) {
+    const values = value.filter((item): item is string => typeof item === "string" && item.trim().length > 0);
+    return values.length === value.length ? values : null;
+  }
+  if (typeof value !== "string") return null;
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+};
+
+const normalizeInputValue = (name: string, spec: WorkflowInputSpec, value: unknown): WorkflowInputValue | null => {
+  if (spec.type === "string") return typeof value === "string" && value.length > 0 ? value : null;
+  if (spec.type === "string-list") {
+    const values = parseStringList(value);
+    return values && values.length > 0 ? values : null;
+  }
+  if (spec.type === "boolean") {
+    if (typeof value === "boolean") return value;
+    if (typeof value !== "string") return null;
+    const lowered = value.trim().toLowerCase();
+    if (lowered === "true") return true;
+    if (lowered === "false") return false;
+    return null;
+  }
+  if (typeof value === "string" && surfaceModes.has(value as WorkflowSurfaceMode)) return value as WorkflowSurfaceMode;
+  throw new Error(`Unsupported workflow input value for ${name}`);
+};
+
+export const listWorkflowSpecs = (specs: readonly WorkflowSpec[]) =>
+  [...specs].sort((a, b) => a.name.localeCompare(b.name));
+
+export const getWorkflowSpec = (specs: readonly WorkflowSpec[], name: string) =>
+  specs.find((spec) => spec.name === name) ?? null;
+
+export const compactWorkflowInputs = (inputs: WorkflowPlanInputs) =>
+  Object.fromEntries(Object.entries(inputs).filter(([, value]) => value !== null && value !== ""));
+
+const addFieldTargetRoot = (app: string | null) => (app ? `apps/${app}` : "*");
+
+const addFieldPaths = (inputs: Record<string, WorkflowInputValue>) => {
+  const app = typeof inputs.app === "string" ? inputs.app : null;
+  const module = typeof inputs.module === "string" ? inputs.module : "<module>";
+  const paths = moduleSourcePaths(module);
+  const root = addFieldTargetRoot(app);
+  return {
+    constant: `${root}/${paths.constant}`,
+    dictionary: `${root}/${paths.dictionary}`,
+    template: `${root}/${paths.template}`,
+    unit: `${root}/${paths.unit}`,
+    view: `${root}/${paths.view}`,
+  };
+};
+
+const selectedAddFieldSurfaces = (inputs: Record<string, WorkflowInputValue>) =>
+  Array.isArray(inputs.surfaces) ? new Set(inputs.surfaces) : null;
+
+const addFieldDefaultCoercion = (inputs: Record<string, WorkflowInputValue>) => {
+  const typeName = typeof inputs.type === "string" ? inputs.type : null;
+  const defaultValue = typeof inputs.default === "string" ? inputs.default : null;
+  if (!typeName || defaultValue === null) return null;
+  if (typeName.toLowerCase() === "number" || typeName.toLowerCase() === "numeric") return null;
+  const enumValues = Array.isArray(inputs.values) ? inputs.values : null;
+  return coerceFieldDefault(typeName.toLowerCase() === "enum" ? "enum" : typeName, defaultValue, { enumValues });
+};
+
+const createAddFieldDefaultRecommendations = (inputs: Record<string, WorkflowInputValue>): WorkflowRecommendation[] => {
+  const field = typeof inputs.field === "string" ? inputs.field : "<field>";
+  const coercion = addFieldDefaultCoercion(inputs);
+  if (!coercion?.normalized || !coercion.expression) return [];
+  return [
+    {
+      code: "add-field-default-normalized",
+      kind: "manual-action",
+      confidence: "high",
+      message: `Default for ${field} will be normalized to ${coercion.normalizedType} literal ${coercion.expression}.`,
+      action: "Review the normalized default in the apply report if this value should stay unset.",
+    },
+  ];
+};
+
+const createAddFieldRecommendations = (inputs: Record<string, WorkflowInputValue>): WorkflowRecommendation[] => {
+  const app = typeof inputs.app === "string" ? inputs.app : "<app-or-lib>";
+  const module = typeof inputs.module === "string" ? inputs.module : "<module>";
+  const field = typeof inputs.field === "string" ? inputs.field : "<field>";
+  const typeName = typeof inputs.type === "string" ? inputs.type : null;
+  if (!typeName) return [];
+
+  const policy = addFieldUiPolicyForType(typeName);
+  const normalizedType = policy.normalizedType;
+  const paths = addFieldPaths(inputs);
+  const surfaces = selectedAddFieldSurfaces(inputs);
+  const templateRequested = surfaces?.has("template") ?? false;
+  const includeInLight = inputs.includeInLight === true;
+  return [
+    ...(normalizedType === "Int" || normalizedType === "Float"
+      ? [
+          {
+            code: "add-field-import",
+            kind: "import" as const,
+            target: paths.constant,
+            confidence: "high" as const,
+            message: `Import ${normalizedType} from "akanjs/base" before writing field(${normalizedType}).`,
+          },
+        ]
+      : []),
+    {
+      code: "add-field-placement-constant",
+      kind: "placement",
+      target: paths.constant,
+      confidence: "high",
+      message: `Insert ${field}: field(${normalizedType}) in ${capitalize(module)}Input.`,
+    },
+    {
+      code: "add-field-placement-dictionary",
+      kind: "placement",
+      target: paths.dictionary,
+      confidence: "high",
+      message: `Add dictionary labels for ${module}.${field}.`,
+    },
+    {
+      code: "add-field-component",
+      kind: "ui-component",
+      target: paths.template,
+      confidence: policy.confidence,
+      action: templateRequested
+        ? `apply_workflow will try to add ${policy.component} to Template when the existing Template has a safe generated field-list pattern.`
+        : `Recommended component is ${policy.component}. Pass surfaces=["template"] when this field should be rendered in the Template form.`,
+      message: `Recommended UI component for ${field} (${normalizedType}): ${policy.component}.`,
+    },
+    ...(!surfaces
+      ? [
+          {
+            code: "add-field-template-surface-choice",
+            kind: "manual-action" as const,
+            target: paths.template,
+            action: `Choose whether to expose ${field} in Template by passing surfaces=["template"].`,
+            confidence: "medium" as const,
+            message: `Template exposure for ${module}.${field} is not selected yet.`,
+          },
+        ]
+      : []),
+    ...(!includeInLight
+      ? [
+          {
+            code: "add-field-light-projection-choice",
+            kind: "manual-action" as const,
+            target: paths.constant,
+            action: `Pass includeInLight=true when ${field} should appear in Light${capitalize(module)} list/card projections.`,
+            confidence: "medium" as const,
+            message: `Light projection exposure for ${module}.${field} is not selected yet.`,
+          },
+        ]
+      : []),
+    ...(includeInLight
+      ? [
+          {
+            code: "add-field-light-projection",
+            kind: "placement" as const,
+            target: paths.constant,
+            confidence: "high" as const,
+            message: `Add ${field} to Light${capitalize(module)} projection fields.`,
+          },
+        ]
+      : []),
+    ...(surfaces && !templateRequested
+      ? [
+          {
+            code: "add-field-ui-surface-skip",
+            kind: "manual-action" as const,
+            target: paths.template,
+            confidence: "medium" as const,
+            message: `Template is not included in surfaces, so ${module}.${field} will not be auto-rendered there.`,
+          },
+        ]
+      : []),
+    {
+      code: "add-field-ui-manual-review",
+      kind: "manual-action",
+      target: paths.template,
+      action: `Review ${app}:${module} UI after apply. Template auto-edit requires a generated ${module}Form hook and Layout.Template field list; Unit/View are not auto-edited because list/card placement depends on local layout. Candidate positions: Layout.Template before the closing tag, Light${capitalize(
+        module,
+      )} projection array for list data, and Unit/View card sections for display.`,
+      confidence: "medium",
+      message: "UI manual review includes the reason auto-edit may be skipped and candidate insertion positions.",
+    },
+    ...createAddFieldDefaultRecommendations(inputs),
+  ];
+};
+
+const createWorkflowPlanPredictedChanges = (
+  spec: WorkflowSpec,
+  inputs: Record<string, WorkflowInputValue>,
+): WorkflowPlan["predictedChanges"] => {
+  if (spec.name !== "add-field") return spec.predictedChanges;
+  const paths = addFieldPaths(inputs);
+  const surfaces = selectedAddFieldSurfaces(inputs);
+  const includeInLight = inputs.includeInLight === true;
+  return [
+    {
+      target: paths.constant,
+      action: "modify",
+      applyScope: "auto",
+      reason: includeInLight ? "Field shape and Light projection are added." : "Field shape is added.",
+    },
+    {
+      target: paths.dictionary,
+      action: "modify",
+      applyScope: "auto",
+      reason: "Field label is added.",
+    },
+    ...(!surfaces || surfaces.has("template")
+      ? [
+          {
+            target: paths.template,
+            action: "modify" as const,
+            applyScope: surfaces?.has("template") ? ("auto" as const) : ("manual-review" as const),
+            reason: surfaces?.has("template")
+              ? "Template form is selected for safe-pattern auto insertion."
+              : "Form surface may include the field.",
+          },
+        ]
+      : []),
+    {
+      target: `${addFieldTargetRoot(typeof inputs.app === "string" ? inputs.app : null)}/lib/cnst.ts`,
+      action: "sync",
+      applyScope: "generated-sync",
+      reason: "Generated constants may change after sync.",
+    },
+    {
+      target: `${addFieldTargetRoot(typeof inputs.app === "string" ? inputs.app : null)}/lib/dict.ts`,
+      action: "sync",
+      applyScope: "generated-sync",
+      reason: "Generated dictionary barrel may change after sync.",
+    },
+  ];
+};
+
+const createWorkflowPlanOptionalSurfaces = (
+  spec: WorkflowSpec,
+  inputs: Record<string, WorkflowInputValue>,
+): Record<string, WorkflowSurfaceMode> => {
+  const optionalSurfaces = spec.optionalSurfaces ?? {};
+  const surfaces = selectedAddFieldSurfaces(inputs);
+  if (spec.name !== "add-field" || !surfaces) return optionalSurfaces;
+  return Object.fromEntries(
+    Object.entries(optionalSurfaces).map(([surface, mode]) => [surface, surfaces.has(surface) ? "include" : mode]),
+  );
+};
+
+const createWorkflowPlanRecommendations = (
+  spec: WorkflowSpec,
+  inputs: Record<string, WorkflowInputValue>,
+): WorkflowRecommendation[] => [
+  {
+    code: "workflow-apply-first",
+    kind: "auto-apply",
+    confidence: "high",
+    action: "Call apply_workflow with the MCP planPath before editing source files directly.",
+    message: `Apply the ${spec.name} plan through apply_workflow when MCP returns planPath or next.tool=apply_workflow.`,
+  },
+  {
+    code: "workflow-validate-apply-report",
+    kind: "validation",
+    confidence: "high",
+    action:
+      "After apply_workflow, call run_validation with validationTarget when present; otherwise use applyReportPath.",
+    message: "Validate the apply report artifact so diagnostics and recommendations follow the actual apply result.",
+  },
+  ...(spec.name === "add-field" ? createAddFieldRecommendations(inputs) : []),
+];
+
+export const createWorkflowPlan = (spec: WorkflowSpec, rawInputs: Record<string, unknown>): WorkflowPlan => {
+  const inputs: Record<string, WorkflowInputValue> = {};
+  const diagnostics: WorkflowDiagnostic[] = [];
+
+  for (const [name, inputSpec] of Object.entries(spec.inputs)) {
+    const rawValue = rawInputs[name];
+    if (rawValue === undefined || rawValue === null || rawValue === "") {
+      if (inputSpec.required) {
+        diagnostics.push({
+          severity: "error",
+          code: "workflow-input-missing",
+          input: name,
+          message: `Workflow ${spec.name} requires input "${name}".`,
+        });
+      }
+      continue;
+    }
+
+    const value = normalizeInputValue(name, inputSpec, rawValue);
+    if (value === null) {
+      diagnostics.push({
+        severity: "error",
+        code: "workflow-input-invalid",
+        input: name,
+        message: `Workflow ${spec.name} input "${name}" must be ${inputSpec.type}.`,
+      });
+      continue;
+    }
+    if (inputSpec.allowedValues && typeof value === "string" && !inputSpec.allowedValues.includes(value)) {
+      diagnostics.push({
+        severity: "error",
+        code: "workflow-input-not-allowed",
+        input: name,
+        message: `Workflow ${spec.name} input "${name}" must be one of: ${inputSpec.allowedValues.join(", ")}.`,
+      });
+      continue;
+    }
+    inputs[name] = value;
+  }
+
+  const fieldType = inputs.type;
+  if (
+    spec.name === "add-field" &&
+    typeof fieldType === "string" &&
+    (fieldType.toLowerCase() === "number" || fieldType.toLowerCase() === "numeric")
+  ) {
+    diagnostics.push({
+      severity: "error",
+      code: "primitive-field-type-unsupported",
+      input: "type",
+      message: `Field type "${fieldType}" is ambiguous in Akan. Use Int for integer fields or Float for decimal fields.`,
+    });
+  }
+  if (spec.name === "add-field") {
+    const defaultCoercion = addFieldDefaultCoercion(inputs);
+    if (defaultCoercion?.diagnostic) {
+      diagnostics.push({
+        ...defaultCoercion.diagnostic,
+        code: "workflow-default-value-invalid",
+        message: `Plan input default is not valid for ${defaultCoercion.normalizedType}: ${defaultCoercion.diagnostic.message}`,
+      });
+    } else if (defaultCoercion?.normalized && defaultCoercion.expression) {
+      diagnostics.push({
+        severity: "warning",
+        code: "workflow-default-value-normalized",
+        input: "default",
+        failureScope: "source-change",
+        message: `Plan input default will be written as ${defaultCoercion.normalizedType} literal ${defaultCoercion.expression}.`,
+      });
+    }
+  }
+
+  return {
+    schemaVersion: 1,
+    workflow: spec.name,
+    mode: "plan",
+    inputs,
+    optionalSurfaces: createWorkflowPlanOptionalSurfaces(spec, inputs),
+    steps: spec.steps,
+    predictedChanges: createWorkflowPlanPredictedChanges(spec, inputs),
+    validation: spec.validation,
+    diagnostics,
+    recommendations: createWorkflowPlanRecommendations(spec, inputs),
+    requiresApproval: true,
+  };
+};

package/workflow/primitive.ts

@@ -0,0 +1,59 @@
+import type { PrimitiveFormat, PrimitiveWriteReport } from "./types";
+import { jsonText } from "./utils";
+
+export const createPrimitiveWriteReport = ({
+  command,
+  status,
+  changedFiles = [],
+  generatedFiles = [],
+  validationCommands = [],
+  diagnostics = [],
+  nextActions = [],
+}: Omit<PrimitiveWriteReport, "schemaVersion" | "status"> & {
+  status?: PrimitiveWriteReport["status"];
+}): PrimitiveWriteReport => ({
+  schemaVersion: 1,
+  command,
+  status: status ?? (diagnostics.some((diagnostic) => diagnostic.severity === "error") ? "failed" : "passed"),
+  changedFiles,
+  generatedFiles,
+  validationCommands,
+  diagnostics,
+  nextActions,
+});
+
+export const renderPrimitiveWriteReport = (report: PrimitiveWriteReport) =>
+  [
+    `# Primitive Write: ${report.command}`,
+    "",
+    `- Status: ${report.status}`,
+    "",
+    "## Changed Files",
+    ...(report.changedFiles.length
+      ? report.changedFiles.map((file) => `- \`${file.action}\` ${file.path}: ${file.reason}`)
+      : ["- none"]),
+    "",
+    "## Generated Files",
+    ...(report.generatedFiles.length
+      ? report.generatedFiles.map((file) => `- \`${file.action}\` ${file.path}: ${file.reason}`)
+      : ["- none"]),
+    "",
+    "## Validation Commands",
+    ...(report.validationCommands.length
+      ? report.validationCommands.map((validation) => `- \`${validation.command}\`: ${validation.reason}`)
+      : ["- none"]),
+    "",
+    "## Diagnostics",
+    ...(report.diagnostics.length
+      ? report.diagnostics.map((diagnostic) => `- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`)
+      : ["- none"]),
+    "",
+    "## Next Actions",
+    ...(report.nextActions.length
+      ? report.nextActions.map((action) => `- \`${action.command}\`: ${action.reason}`)
+      : ["- none"]),
+    "",
+  ].join("\n");
+
+export const renderPrimitiveReport = (report: PrimitiveWriteReport, format: PrimitiveFormat = "markdown") =>
+  format === "json" ? jsonText(report) : renderPrimitiveWriteReport(report);

package/workflow/render.ts

@@ -0,0 +1,252 @@
+import type {
+  RepairReport,
+  WorkflowApplyReport,
+  WorkflowFormat,
+  WorkflowPlan,
+  WorkflowRunArtifact,
+  WorkflowSpec,
+  WorkflowValidationRunReport,
+} from "./types";
+import { jsonText } from "./utils";
+
+export const renderWorkflowList = (specs: readonly WorkflowSpec[]) =>
+  [
+    "# Akan Workflows",
+    "",
+    ...specs.flatMap((spec) => [`- \`${spec.name}\`: ${spec.description}`, `  - When: ${spec.whenToUse}`]),
+    "",
+  ].join("\n");
+
+export const renderWorkflowExplain = (spec: WorkflowSpec) =>
+  [
+    `# Workflow: ${spec.name}`,
+    "",
+    spec.description,
+    "",
+    "## When To Use",
+    spec.whenToUse,
+    "",
+    "## Inputs",
+    ...Object.entries(spec.inputs).map(
+      ([name, input]) =>
+        `- \`${name}\`${input.required ? " (required)" : ""}: ${input.description}${
+          input.allowedValues ? ` Allowed: ${input.allowedValues.join(", ")}.` : ""
+        }`,
+    ),
+    "",
+    "## Optional Surfaces",
+    ...Object.entries(spec.optionalSurfaces ?? {}).map(([name, mode]) => `- \`${name}\`: ${mode}`),
+    "",
+    "## Steps",
+    ...spec.steps.map((step, index) => `${index + 1}. \`${step.id}\` (${step.tool}): ${step.description}`),
+    "",
+    "## Validation",
+    ...spec.validation.map((validation) => `- \`${validation.command}\`: ${validation.reason}`),
+    "",
+  ].join("\n");
+
+export const renderWorkflowPlan = (plan: WorkflowPlan) =>
+  [
+    `# Workflow Plan: ${plan.workflow}`,
+    "",
+    `- Mode: ${plan.mode}`,
+    `- Requires approval: ${plan.requiresApproval}`,
+    "",
+    "## Inputs",
+    ...Object.entries(plan.inputs).map(
+      ([name, value]) => `- \`${name}\`: ${Array.isArray(value) ? value.join(", ") : value}`,
+    ),
+    "",
+    "## Optional Surfaces",
+    ...Object.entries(plan.optionalSurfaces).map(([name, mode]) => `- \`${name}\`: ${mode}`),
+    "",
+    "## Steps",
+    ...plan.steps.map((step, index) => `${index + 1}. \`${step.id}\` (${step.tool}): ${step.description}`),
+    "",
+    "## Predicted Changes",
+    ...plan.predictedChanges.map((change) => {
+      const scope = change.applyScope ? ` (${change.applyScope})` : "";
+      return `- \`${change.action}\`${scope} ${change.target}: ${change.reason}`;
+    }),
+    "",
+    "## Validation",
+    ...plan.validation.map((validation) => `- \`${validation.command}\`: ${validation.reason}`),
+    "",
+    "## Diagnostics",
+    ...(plan.diagnostics.length
+      ? plan.diagnostics.map((diagnostic) => `- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`)
+      : ["- none"]),
+    "",
+    "## Recommendations",
+    ...(plan.recommendations.length
+      ? plan.recommendations.map((recommendation) => `- [${recommendation.kind}] ${recommendation.message}`)
+      : ["- none"]),
+    "",
+  ].join("\n");
+
+const renderRecommendation = (recommendation: WorkflowApplyReport["recommendations"][number]) => {
+  const target = recommendation.target ? ` ${recommendation.target}` : "";
+  const action = recommendation.action ? ` Action: ${recommendation.action}` : "";
+  return `- [${recommendation.kind}]${target} ${recommendation.message}${action}`;
+};
+
+const renderDiagnostic = (diagnostic: WorkflowApplyReport["diagnostics"][number]) =>
+  `- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`;
+
+export const renderWorkflowApplyReport = (report: WorkflowApplyReport) => {
+  const manualReviewItems = [
+    ...report.diagnostics.filter((diagnostic) => diagnostic.severity === "warning").map(renderDiagnostic),
+    ...report.recommendations
+      .filter((recommendation) => recommendation.kind === "manual-action")
+      .map(renderRecommendation),
+  ];
+  const validationBlockers = report.diagnostics
+    .filter(
+      (diagnostic) =>
+        diagnostic.severity === "error" &&
+        (diagnostic.failureScope === "workspace-config" || diagnostic.failureScope === "environment"),
+    )
+    .map(renderDiagnostic);
+  return [
+    `# Workflow Apply: ${report.workflow}`,
+    "",
+    `- Mode: ${report.mode}`,
+    `- Status: ${report.status}`,
+    ...(report.validationTarget ? [`- Validation target: ${report.validationTarget}`] : []),
+    "",
+    "## Automatically Modified",
+    ...(report.changedFiles.length
+      ? report.changedFiles.map((file) => `- \`${file.action}\` ${file.path}: ${file.reason}`)
+      : ["- none"]),
+    "",
+    "## Generated Sync",
+    ...(report.generatedFiles.length
+      ? report.generatedFiles.map((file) => `- \`${file.action}\` ${file.path}: ${file.reason}`)
+      : ["- none"]),
+    "",
+    "## Applied Commands",
+    ...(report.appliedCommands.length
+      ? report.appliedCommands.map((command) => `- \`${command.command}\`: ${command.reason}`)
+      : ["- none"]),
+    "",
+    "## Recommended Validation Commands",
+    ...(report.recommendedValidationCommands.length
+      ? report.recommendedValidationCommands.map((command) => `- \`${command.command}\`: ${command.reason}`)
+      : ["- none"]),
+    "",
+    "## User Review Required",
+    ...(manualReviewItems.length ? manualReviewItems : ["- none"]),
+    "",
+    "## Validation Blockers",
+    ...(validationBlockers.length
+      ? validationBlockers
+      : report.recommendedValidationCommands.length
+        ? ["- none detected during apply; run validation with the validation target for command-level blockers."]
+        : ["- none"]),
+    "",
+    "## Diagnostics",
+    ...(report.diagnostics.length ? report.diagnostics.map(renderDiagnostic) : ["- none"]),
+    "",
+    "## Recommendations",
+    ...(report.recommendations.length ? report.recommendations.map(renderRecommendation) : ["- none"]),
+    "",
+    "## Next Actions",
+    ...(report.nextActions.length
+      ? report.nextActions.map((action) => `- \`${action.command}\`: ${action.reason}`)
+      : ["- none"]),
+    "",
+  ].join("\n");
+};
+
+export const renderWorkflowApply = (report: WorkflowApplyReport, format: WorkflowFormat = "markdown") =>
+  format === "json" ? jsonText(report) : renderWorkflowApplyReport(report);
+
+export const renderWorkflowValidationRunReport = (report: WorkflowValidationRunReport) =>
+  [
+    `# Workflow Validation: ${report.workflow}`,
+    "",
+    `- Run: ${report.runId}`,
+    `- Status: ${report.status}`,
+    `- Source status: ${report.sourceStatus}`,
+    `- Workspace status: ${report.workspaceStatus}`,
+    `- Overall status: ${report.overallStatus}`,
+    "",
+    "## Status Summary",
+    `- Required source-change validation: ${report.summary.sourceChange}`,
+    `- Generated sync validation: ${report.summary.generatedSync}`,
+    `- Workspace configuration validation: ${report.summary.workspaceConfig}`,
+    `- Environment validation: ${report.summary.environment}`,
+    "",
+    "## Known Blockers",
+    ...(report.knownBlockers.length
+      ? report.knownBlockers.map((blocker) => {
+          const command = blocker.command ? ` \`${blocker.command}\`` : "";
+          const count = blocker.count > 1 ? ` (${blocker.count}x)` : "";
+          const known = blocker.known ? " known" : "";
+          return `- [${blocker.failureScope}${known}]${command}${count}: ${blocker.message}`;
+        })
+      : ["- none"]),
+    "",
+    "## Commands",
+    ...(report.commands.length
+      ? report.commands.map((command) => {
+          const scope = command.failureScope ? ` (${command.failureScope})` : "";
+          return `- [${command.status}] \`${command.command}\`${scope}: ${command.reason}`;
+        })
+      : ["- none"]),
+    "",
+    "## Diagnostics",
+    ...(report.diagnostics.length
+      ? report.diagnostics.map((diagnostic) => `- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`)
+      : ["- none"]),
+    "",
+    "## Repair Actions",
+    ...(report.repairActions.length
+      ? report.repairActions.map((action) => `- \`${action.command}\`: ${action.reason}`)
+      : ["- none"]),
+    "",
+    "## Next Actions",
+    ...(report.nextActions.length
+      ? report.nextActions.map((action) => `- \`${action.command}\`: ${action.reason}`)
+      : ["- none"]),
+    "",
+  ].join("\n");
+
+export const renderWorkflowValidation = (report: WorkflowValidationRunReport, format: WorkflowFormat = "markdown") =>
+  format === "json" ? jsonText(report) : renderWorkflowValidationRunReport(report);
+
+export const renderRepairReportMarkdown = (report: RepairReport) =>
+  [
+    `# Akan Repair: ${report.kind}`,
+    "",
+    `- Status: ${report.status}`,
+    `- Target: ${report.target ?? "none"}`,
+    "",
+    "## Commands",
+    ...(report.commands.length
+      ? report.commands.map((command) => `- [${command.status}] \`${command.command}\`: ${command.reason}`)
+      : ["- none"]),
+    "",
+    "## Diagnostics",
+    ...(report.diagnostics.length
+      ? report.diagnostics.map((diagnostic) => `- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`)
+      : ["- none"]),
+    "",
+    "## Next Actions",
+    ...(report.nextActions.length
+      ? report.nextActions.map((action) => `- \`${action.command}\`: ${action.reason}`)
+      : ["- none"]),
+    "",
+  ].join("\n");
+
+export const renderRepairReport = (report: RepairReport, format: WorkflowFormat = "markdown") =>
+  format === "json" ? jsonText(report) : renderRepairReportMarkdown(report);
+
+export const renderWorkflowRunArtifact = (artifact: WorkflowRunArtifact, format: WorkflowFormat = "markdown") => {
+  if ("kind" in artifact) return renderRepairReport(artifact, format);
+  if ("mode" in artifact && artifact.mode === "validate") return renderWorkflowValidation(artifact, format);
+  if ("mode" in artifact && (artifact.mode === "apply" || artifact.mode === "dry-run")) {
+    return renderWorkflowApply(artifact, format);
+  }
+  return jsonText(artifact);
+};