forgeos 0.1.0-alpha.0

package/src/forge/cli/doctor.ts

@@ -0,0 +1,209 @@
+import { nodeFileSystem } from "../compiler/fs/index.ts";
+import { join } from "node:path";
+import { GENERATED_DIR } from "../compiler/emitter/constants.ts";
+import { run as runGenerate } from "../compiler/orchestrator/run.ts";
+import { stripDeterministicHeader } from "../compiler/primitives/header.ts";
+import type { TableMapEntry } from "../compiler/data-graph/sql/serialize.ts";
+import type { FrontendGraph } from "../compiler/types/frontend-graph.ts";
+import type { Diagnostic } from "../compiler/types/diagnostic.ts";
+
+export interface DoctorCheck {
+  name: string;
+  ok: boolean;
+  severity: "error" | "warning";
+  message?: string;
+}
+
+export interface DoctorResult {
+  ok: boolean;
+  checks: DoctorCheck[];
+  exitCode: 0 | 1;
+}
+
+function present(workspaceRoot: string, name: string, relative: string): DoctorCheck {
+  const ok = nodeFileSystem.exists(join(workspaceRoot, relative));
+  return {
+    name,
+    ok,
+    severity: "error",
+    message: ok ? undefined : `missing ${relative}`,
+  };
+}
+
+function readGeneratedJson<T>(workspaceRoot: string, relative: string): T | null {
+  const absolute = join(workspaceRoot, relative);
+  if (!nodeFileSystem.exists(absolute)) {
+    return null;
+  }
+  try {
+    return JSON.parse(stripDeterministicHeader(nodeFileSystem.readText(absolute) ?? "")) as T;
+  } catch {
+    return null;
+  }
+}
+
+function isUuidLike(value: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+
+function hasUuidTenantColumns(tableMap: Record<string, TableMapEntry>): boolean {
+  return Object.values(tableMap).some((entry) => {
+    if (!entry.tenantScoped || !entry.tenantIdColumn) {
+      return false;
+    }
+    return entry.columns.some(
+      (column) => column.name === entry.tenantIdColumn && column.sqlType === "uuid",
+    );
+  });
+}
+
+function frontendDiagnosticChecks(frontendGraph: FrontendGraph | null): DoctorCheck[] {
+  return (frontendGraph?.diagnostics ?? []).map((diagnostic, index) => ({
+    name: `frontend-diagnostic-${index + 1}`,
+    ok: false,
+    severity: diagnostic.severity === "error" ? "error" : "warning",
+    message: `${diagnostic.code}: ${diagnostic.fixHint ?? diagnostic.message}`,
+  }));
+}
+
+function capabilityDiagnosticChecks(capabilityMap: { diagnostics?: Diagnostic[] } | null): DoctorCheck[] {
+  return (capabilityMap?.diagnostics ?? []).map((diagnostic, index) => ({
+    name: `capability-diagnostic-${index + 1}`,
+    ok: false,
+    severity: diagnostic.severity === "error" ? "error" as const : "warning" as const,
+    message: `${diagnostic.code}: ${diagnostic.fixHint ?? diagnostic.message}`,
+  }));
+}
+
+function frontendDevAuthChecks(
+  frontendGraph: FrontendGraph | null,
+  tableMap: Record<string, TableMapEntry>,
+): DoctorCheck[] {
+  if (!frontendGraph || !hasUuidTenantColumns(tableMap)) {
+    return [];
+  }
+  return frontendGraph.providers
+    .filter((provider) => provider.devAuthTenantId && !isUuidLike(provider.devAuthTenantId))
+    .map((provider) => ({
+      name: "frontend-dev-auth-tenant",
+      ok: false,
+      severity: "warning" as const,
+      message: `${provider.file} devAuth tenantId '${provider.devAuthTenantId}' is not UUID-like, but tenant tables use uuid tenant ids`,
+    }));
+}
+
+export async function runDoctorCommand(options: {
+  workspaceRoot: string;
+}): Promise<DoctorResult> {
+  const checks: DoctorCheck[] = [
+    present(options.workspaceRoot, "agents-md", "AGENTS.md"),
+    present(options.workspaceRoot, "forge-lock", "forge.lock"),
+    present(options.workspaceRoot, "agent-contract", `${GENERATED_DIR}/agentContract.json`),
+    present(options.workspaceRoot, "capability-map", `${GENERATED_DIR}/capabilityMap.json`),
+    present(options.workspaceRoot, "runtime-matrix", `${GENERATED_DIR}/runtimeMatrix.json`),
+    present(options.workspaceRoot, "data-graph", `${GENERATED_DIR}/dataGraph.json`),
+    present(options.workspaceRoot, "policies", `${GENERATED_DIR}/policyRegistry.json`),
+    present(options.workspaceRoot, "secrets", `${GENERATED_DIR}/secretRegistry.json`),
+    present(options.workspaceRoot, "client", `${GENERATED_DIR}/clientManifest.json`),
+    present(options.workspaceRoot, "frontend", `${GENERATED_DIR}/frontendGraph.json`),
+    present(options.workspaceRoot, "live-query", `${GENERATED_DIR}/liveQueryRegistry.json`),
+  ];
+
+  const generateCheck = await runGenerate({
+    workspaceRoot: options.workspaceRoot,
+    check: true,
+    dryRun: false,
+    json: false,
+    concurrency: 4,
+  });
+  checks.push({
+    name: "generated",
+    ok: generateCheck.exitCode === 0,
+    severity: "error",
+    message:
+      generateCheck.exitCode === 0
+        ? undefined
+        : "generated artifacts are stale; run forge generate",
+  });
+
+  const deployManifest = join(options.workspaceRoot, "deploy", "deployManifest.json");
+  if (nodeFileSystem.exists(deployManifest)) {
+    checks.push(
+      present(options.workspaceRoot, "self-host-compose", "deploy/docker-compose.yml"),
+      present(options.workspaceRoot, "self-host-env", "deploy/.env.example"),
+    );
+  }
+
+  const webRoot = join(options.workspaceRoot, "web");
+  if (nodeFileSystem.exists(webRoot)) {
+    const frontendGraph = readGeneratedJson<FrontendGraph>(
+      options.workspaceRoot,
+      `${GENERATED_DIR}/frontendGraph.json`,
+    );
+    const dbJson = readGeneratedJson<{ tableMap: Record<string, TableMapEntry> }>(
+      options.workspaceRoot,
+      `${GENERATED_DIR}/db.json`,
+    );
+    checks.push({
+      name: "frontend-root",
+      ok: frontendGraph?.present === true,
+      severity: "error",
+      message: frontendGraph?.present === true ? undefined : "web/ exists but frontendGraph does not detect it",
+    });
+    checks.push({
+      name: "frontend-bridge",
+      ok: (frontendGraph?.bridgeFiles.length ?? 0) > 0,
+      severity: "warning",
+      message:
+        (frontendGraph?.bridgeFiles.length ?? 0) > 0
+          ? undefined
+          : "missing web/lib/forge.ts bridge to generated client",
+    });
+    checks.push({
+      name: "frontend-provider",
+      ok: (frontendGraph?.providers.length ?? 0) > 0 || frontendGraph?.framework === "static",
+      severity: "warning",
+      message:
+        (frontendGraph?.providers.length ?? 0) > 0 || frontendGraph?.framework === "static"
+          ? undefined
+          : "missing ForgeProvider in web app",
+    });
+    checks.push({
+      name: "frontend-routes",
+      ok: (frontendGraph?.routes.length ?? 0) > 0,
+      severity: "warning",
+      message:
+        (frontendGraph?.routes.length ?? 0) > 0
+          ? undefined
+          : "no frontend routes detected in web/",
+    });
+    checks.push(...frontendDiagnosticChecks(frontendGraph));
+    checks.push(...capabilityDiagnosticChecks(readGeneratedJson<{ diagnostics?: Diagnostic[] }>(
+      options.workspaceRoot,
+      `${GENERATED_DIR}/capabilityMap.json`,
+    )));
+    checks.push(...frontendDevAuthChecks(frontendGraph, dbJson?.tableMap ?? {}));
+  }
+
+  const ok = checks.every((check) => check.ok || check.severity === "warning");
+  return {
+    ok,
+    checks,
+    exitCode: ok ? 0 : 1,
+  };
+}
+
+export function formatDoctorJson(result: DoctorResult): string {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}
+
+export function formatDoctorHuman(result: DoctorResult): string {
+  const lines = ["Forge Doctor", ""];
+  for (const check of result.checks) {
+    const marker = check.ok ? "OK" : check.severity === "warning" ? "WARN" : "FAIL";
+    lines.push(`${marker} ${check.name}${check.message ? ` - ${check.message}` : ""}`);
+  }
+  lines.push("");
+  lines.push(result.ok ? "Project is coherent." : "Project needs attention.");
+  return `${lines.join("\n")}\n`;
+}

package/src/forge/cli/feature.ts

@@ -0,0 +1,485 @@
+import { nodeFileSystem } from "../compiler/fs/index.ts";
+import { join, normalize, relative, resolve } from "node:path";
+import { createDiagnostic } from "../compiler/diagnostics/create.ts";
+import { run } from "../compiler/orchestrator/run.ts";
+import { serializeCanonical } from "../compiler/primitives/serialize.ts";
+import type { Diagnostic } from "../compiler/types/diagnostic.ts";
+import { runMakeCommand } from "./make.ts";
+import {
+  buildFeaturePlan,
+  FEATURE_APPLIED_DIR,
+  FEATURE_PLAN_DIR,
+  parseFeatureBlueprint,
+  readFeaturePlan,
+  renderFeatureDiff,
+  renderFeaturePlanMarkdown,
+  writeFeaturePlan,
+  writeText,
+} from "../feature/compiler.ts";
+import { FEATURE_EXAMPLES } from "../feature/examples.ts";
+import type {
+  FeatureApplyRecord,
+  FeatureCommandOptions,
+  FeaturePlan,
+  FeatureResult,
+} from "../feature/types.ts";
+
+interface SnapshotFile {
+  file: string;
+  existed: boolean;
+  content?: string;
+}
+
+interface FeatureSnapshot {
+  schemaVersion: "0.1.0";
+  featureId: string;
+  files: SnapshotFile[];
+}
+
+function diagnostic(
+  severity: Diagnostic["severity"],
+  code: string,
+  message: string,
+  file?: string,
+): Diagnostic {
+  return createDiagnostic({
+    severity,
+    code,
+    message,
+    ...(file ? { file } : {}),
+  });
+}
+
+function absPath(workspaceRoot: string, file: string): string {
+  const root = resolve(workspaceRoot);
+  const absolute = resolve(root, normalize(file));
+  const rel = relative(root, absolute);
+  if (rel.startsWith("..") || resolve(rel) === rel) {
+    throw new Error(`refusing to access outside workspace: ${file}`);
+  }
+  return absolute;
+}
+
+function readText(workspaceRoot: string, file: string): string | null {
+  const absolute = absPath(workspaceRoot, file);
+  if (!nodeFileSystem.exists(absolute)) {
+    return null;
+  }
+  return (nodeFileSystem.readText(absolute) ?? "");
+}
+
+function snapshotPath(plan: FeaturePlan): string {
+  return `${FEATURE_PLAN_DIR}/${plan.id}/snapshot.json`;
+}
+
+function appliedPath(featureId: string): string {
+  return `${FEATURE_APPLIED_DIR}/${featureId}.json`;
+}
+
+function readAppliedRecord(workspaceRoot: string, featureId: string): FeatureApplyRecord | null {
+  const content = readText(workspaceRoot, appliedPath(featureId));
+  return content ? (JSON.parse(content) as FeatureApplyRecord) : null;
+}
+
+function listAppliedRecords(workspaceRoot: string): FeatureApplyRecord[] {
+  const dir = absPath(workspaceRoot, FEATURE_APPLIED_DIR);
+  if (!nodeFileSystem.exists(dir)) {
+    return [];
+  }
+  return nodeFileSystem
+    .readDir(dir)
+    .map((entry) => entry.name)
+    .filter((file) => file.endsWith(".json"))
+    .sort()
+    .map((file) => JSON.parse((nodeFileSystem.readText(join(dir, file)) ?? "")) as FeatureApplyRecord);
+}
+
+function writeSnapshot(workspaceRoot: string, plan: FeaturePlan): void {
+  const files = plan.rollback.trackedFiles.map((file): SnapshotFile => {
+    const content = readText(workspaceRoot, file);
+    return {
+      file,
+      existed: content !== null,
+      ...(content !== null ? { content } : {}),
+    };
+  });
+  const snapshot: FeatureSnapshot = {
+    schemaVersion: "0.1.0",
+    featureId: plan.id,
+    files,
+  };
+  writeText(workspaceRoot, snapshotPath(plan), serializeCanonical(snapshot));
+}
+
+function restoreSnapshot(workspaceRoot: string, plan: FeaturePlan): Diagnostic[] {
+  const raw = readText(workspaceRoot, snapshotPath(plan));
+  if (!raw) {
+    return [
+      diagnostic(
+        "error",
+        "FORGE_FEATURE_BLUEPRINT_INVALID",
+        `missing snapshot for feature '${plan.id}'`,
+      ),
+    ];
+  }
+  const snapshot = JSON.parse(raw) as FeatureSnapshot;
+  for (const file of snapshot.files) {
+    if (file.existed) {
+      writeText(workspaceRoot, file.file, file.content ?? "");
+    } else {
+      nodeFileSystem.remove(absPath(workspaceRoot, file.file));
+    }
+  }
+  return [];
+}
+
+async function runGenerateChecks(options: FeatureCommandOptions): Promise<Diagnostic[]> {
+  const diagnostics: Diagnostic[] = [];
+  if (!options.noGenerate) {
+    const generated = await run({
+      workspaceRoot: options.workspaceRoot,
+      check: false,
+      dryRun: false,
+      json: false,
+      concurrency: 4,
+    });
+    diagnostics.push(...generated.errors, ...generated.warnings);
+  }
+  if (!options.noVerify) {
+    const check = await run({
+      workspaceRoot: options.workspaceRoot,
+      check: true,
+      dryRun: false,
+      json: false,
+      concurrency: 4,
+    });
+    diagnostics.push(...check.errors, ...check.warnings);
+    if (check.exitCode !== 0) {
+      diagnostics.push(
+        diagnostic(
+          "error",
+          "FORGE_FEATURE_BLUEPRINT_INVALID",
+          "post-apply forge generate --check failed",
+        ),
+      );
+    }
+  }
+  return diagnostics;
+}
+
+function buildPlanFromOptions(options: FeatureCommandOptions): FeatureResult {
+  if (!options.blueprintPath) {
+    return {
+      ok: false,
+      diagnostics: [
+        diagnostic("error", "FORGE_FEATURE_BLUEPRINT_INVALID", "feature command requires a blueprint path"),
+      ],
+      exitCode: 1,
+    };
+  }
+  const parsed = parseFeatureBlueprint(options.workspaceRoot, options.blueprintPath);
+  if (!parsed.blueprint) {
+    return { ok: false, diagnostics: parsed.diagnostics, exitCode: 1 };
+  }
+  const plan = buildFeaturePlan(options.workspaceRoot, parsed.blueprint);
+  const diagnostics = [...parsed.diagnostics, ...plan.diagnostics];
+  const ok = !diagnostics.some((item) => item.severity === "error");
+  return {
+    ok,
+    blueprint: parsed.blueprint,
+    plan,
+    diagnostics,
+    exitCode: ok ? 0 : 1,
+  };
+}
+
+async function applyFeature(options: FeatureCommandOptions): Promise<FeatureResult> {
+  const planned = buildPlanFromOptions(options);
+  if (!planned.plan || !planned.blueprint) {
+    return planned;
+  }
+  const existing = readAppliedRecord(options.workspaceRoot, planned.plan.id);
+  if (existing?.blueprintHash === planned.plan.blueprintHash) {
+    return {
+      ok: true,
+      plan: planned.plan,
+      record: existing,
+      explanation: `Feature ${planned.plan.id} already applied with same blueprint hash. Nothing to do.`,
+      diagnostics: [],
+      exitCode: 0,
+    };
+  }
+  if (existing && existing.blueprintHash !== planned.plan.blueprintHash && !options.update) {
+    return {
+      ok: false,
+      plan: planned.plan,
+      record: existing,
+      diagnostics: [
+        diagnostic(
+          "error",
+          "FORGE_FEATURE_HASH_MISMATCH",
+          `feature '${planned.plan.id}' exists with a different blueprint hash; use --update to apply changes`,
+        ),
+      ],
+      exitCode: 1,
+    };
+  }
+  if (planned.plan.risk.level === "high" && !options.allowHighRisk) {
+    return {
+      ok: false,
+      plan: planned.plan,
+      diagnostics: [
+        diagnostic(
+          "error",
+          "FORGE_FEATURE_BLUEPRINT_INVALID",
+          `feature '${planned.plan.id}' is high risk; rerun with --allow-high-risk`,
+        ),
+      ],
+      exitCode: 1,
+    };
+  }
+  if (options.dryRun || !options.yes) {
+    writeFeaturePlan(options.workspaceRoot, planned.plan);
+    return {
+      ...planned,
+      explanation: options.dryRun
+        ? "Dry run only; no files were changed."
+        : "Plan written. Rerun with --yes to apply.",
+    };
+  }
+
+  writeFeaturePlan(options.workspaceRoot, planned.plan);
+  writeSnapshot(options.workspaceRoot, planned.plan);
+
+  const diagnostics: Diagnostic[] = [...planned.diagnostics];
+  for (const makeOption of planned.plan.makeOptions) {
+    const result = await runMakeCommand({
+      ...makeOption,
+      dryRun: false,
+      apply: true,
+      yes: true,
+      noGenerate: true,
+      noVerify: true,
+      keepFailed: true,
+    });
+    diagnostics.push(...result.diagnostics);
+    if (!result.ok) {
+      break;
+    }
+  }
+
+  if (!diagnostics.some((item) => item.severity === "error")) {
+    diagnostics.push(...await runGenerateChecks(options));
+  }
+
+  let ok = !diagnostics.some((item) => item.severity === "error");
+  if (!ok && !options.keepFailed) {
+    diagnostics.push(...restoreSnapshot(options.workspaceRoot, planned.plan));
+  }
+
+  ok = !diagnostics.some((item) => item.severity === "error");
+  const record: FeatureApplyRecord = {
+    schemaVersion: "0.1.0",
+    featureId: planned.plan.id,
+    blueprintName: planned.plan.blueprintName,
+    blueprintHash: planned.plan.blueprintHash,
+    status: ok ? "applied" : "rolled-back",
+    filesCreated: planned.plan.filesToCreate.map((file) => file.file).sort(),
+    filesModified: planned.plan.filesToModify.map((patch) => patch.file).sort(),
+    commandsRun: planned.plan.commandsToRun,
+    result: { ok },
+  };
+  writeText(options.workspaceRoot, appliedPath(planned.plan.id), serializeCanonical(record));
+
+  return {
+    ok,
+    plan: planned.plan,
+    record,
+    diagnostics,
+    exitCode: ok ? 0 : 1,
+  };
+}
+
+function inspectFeature(options: FeatureCommandOptions): FeatureResult {
+  const featureId = options.featureId ?? "";
+  const record = readAppliedRecord(options.workspaceRoot, featureId);
+  const plan = readFeaturePlan(options.workspaceRoot, featureId) ?? undefined;
+  if (!record && !plan) {
+    return {
+      ok: false,
+      diagnostics: [
+        diagnostic("error", "FORGE_FEATURE_BLUEPRINT_INVALID", `feature '${featureId}' was not found`),
+      ],
+      exitCode: 1,
+    };
+  }
+  return { ok: true, record: record ?? undefined, plan, diagnostics: [], exitCode: 0 };
+}
+
+async function rollbackFeature(options: FeatureCommandOptions): Promise<FeatureResult> {
+  const featureId = options.featureId ?? "";
+  const plan = readFeaturePlan(options.workspaceRoot, featureId);
+  if (!plan) {
+    return {
+      ok: false,
+      diagnostics: [
+        diagnostic("error", "FORGE_FEATURE_BLUEPRINT_INVALID", `feature plan '${featureId}' was not found`),
+      ],
+      exitCode: 1,
+    };
+  }
+  const diagnostics = restoreSnapshot(options.workspaceRoot, plan);
+  if (!options.noGenerate) {
+    diagnostics.push(...await runGenerateChecks({ ...options, noVerify: true }));
+  }
+  const ok = !diagnostics.some((item) => item.severity === "error");
+  const record = readAppliedRecord(options.workspaceRoot, plan.id);
+  if (record) {
+    record.status = "rolled-back";
+    record.result = { ok };
+    writeText(options.workspaceRoot, appliedPath(plan.id), serializeCanonical(record));
+  }
+  return {
+    ok,
+    plan,
+    record: record ?? undefined,
+    diagnostics,
+    explanation: `Rolled back feature ${plan.id}.`,
+    exitCode: ok ? 0 : 1,
+  };
+}
+
+function examples(options: FeatureCommandOptions): FeatureResult {
+  const names = Object.keys(FEATURE_EXAMPLES).sort();
+  if (!options.exampleName) {
+    return { ok: true, examples: names, diagnostics: [], exitCode: 0 };
+  }
+  const example = FEATURE_EXAMPLES[options.exampleName];
+  if (!example) {
+    return {
+      ok: false,
+      examples: names,
+      diagnostics: [
+        diagnostic("error", "FORGE_FEATURE_BLUEPRINT_INVALID", `unknown feature example '${options.exampleName}'`),
+      ],
+      exitCode: 1,
+    };
+  }
+  if (options.writePath) {
+    writeText(options.workspaceRoot, options.writePath, serializeCanonical(example));
+  }
+  return {
+    ok: true,
+    blueprint: example,
+    examples: names,
+    explanation: options.writePath ? `Wrote ${options.writePath}` : undefined,
+    diagnostics: [],
+    exitCode: 0,
+  };
+}
+
+export async function runFeatureCommand(options: FeatureCommandOptions): Promise<FeatureResult> {
+  if (options.action === "examples") {
+    return examples(options);
+  }
+  if (options.action === "list") {
+    return {
+      ok: true,
+      records: listAppliedRecords(options.workspaceRoot),
+      diagnostics: [],
+      exitCode: 0,
+    };
+  }
+  if (options.action === "inspect") {
+    return inspectFeature(options);
+  }
+  if (options.action === "rollback") {
+    return rollbackFeature(options);
+  }
+
+  const planned = buildPlanFromOptions(options);
+  if (options.action === "validate") {
+    return {
+      ok: planned.ok,
+      blueprint: planned.blueprint,
+      diagnostics: planned.diagnostics,
+      exitCode: planned.exitCode,
+    };
+  }
+  if (options.action === "plan") {
+    if (planned.plan && planned.ok) {
+      writeFeaturePlan(options.workspaceRoot, planned.plan);
+    }
+    return planned;
+  }
+  if (options.action === "diff") {
+    return {
+      ...planned,
+      diff: planned.plan ? renderFeatureDiff(planned.plan) : undefined,
+    };
+  }
+  if (options.action === "apply") {
+    return applyFeature(options);
+  }
+  return {
+    ok: false,
+    diagnostics: [
+      diagnostic("error", "FORGE_FEATURE_BLUEPRINT_INVALID", `unsupported feature action ${options.action}`),
+    ],
+    exitCode: 1,
+  };
+}
+
+export function formatFeatureJson(result: FeatureResult): string {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}
+
+function formatDiagnostics(diagnostics: Diagnostic[]): string {
+  if (diagnostics.length === 0) {
+    return "";
+  }
+  return `\nDiagnostics:\n${diagnostics
+    .map((item) => `- ${item.severity} ${item.code}: ${item.message}`)
+    .join("\n")}\n`;
+}
+
+export function formatFeatureHuman(result: FeatureResult): string {
+  if (result.examples && !result.blueprint) {
+    return `Available examples:\n${result.examples.map((name) => `- ${name}`).join("\n")}\n${formatDiagnostics(result.diagnostics)}`;
+  }
+  if (result.diff) {
+    return result.diff;
+  }
+  if (result.plan) {
+    const lines = [
+      `Feature plan: ${result.plan.blueprintName}`,
+      "",
+      result.plan.summary,
+      "",
+      `Risk: ${result.plan.risk.level}`,
+      "",
+      "Creates:",
+      ...(result.plan.filesToCreate.length > 0
+        ? result.plan.filesToCreate.map((file) => `- ${file.file}`)
+        : ["- none"]),
+      "",
+      "Modifies:",
+      ...(result.plan.filesToModify.length > 0
+        ? result.plan.filesToModify.map((patch) => `- ${patch.file}`)
+        : ["- none"]),
+    ];
+    if (result.record) {
+      lines.push("", `Status: ${result.record.status}`);
+    }
+    if (result.explanation) {
+      lines.push("", result.explanation);
+    }
+    return `${lines.join("\n")}\n${formatDiagnostics(result.diagnostics)}`;
+  }
+  if (result.records) {
+    return `Applied features:\n${result.records.map((record) => `- ${record.featureId} ${record.status}`).join("\n") || "- none"}\n`;
+  }
+  return `Feature ${result.ok ? "ok" : "failed"}\n${result.explanation ?? ""}${formatDiagnostics(result.diagnostics)}`;
+}
+
+export { renderFeaturePlanMarkdown };