@warpgogol/forge 2.7.0 → 2.8.1

package/os/adr/adr.module.ts

@@ -0,0 +1,158 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Register the Architectural Decision Record (ADR) command domain with the forge kernel registry.</purpose>
+<non-goals>
+  <item>Do not implement command logic here; implementations live in handlers/*.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0366: register adr.create, adr.validate, and adr.list commands.</item>
+  <item>RFC-0521: migrated from packages/os/site-kernel/src/adr/ to packages/forge/os/adr/ as forgeAdrModule.</item>
+  <item>RFC-0727: register adr.implement.stamp command for atomic ADR status transition.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { ForgeModule } from "../../src/forge-module.ts";
+
+export const forgeAdrModule: ForgeModule = {
+  name: "forge-adr",
+  version: "0.1.0",
+
+  async register(registry) {
+    const { runAdrList, runAdrCreate } = await import("./handlers/list-create.ts");
+    const { runAdrValidate } = await import("./handlers/validate.ts");
+    const { runAdrArchive } = await import("./handlers/archive.ts");
+    const { runAdrImplementStamp } = await import("./handlers/implement-stamp.ts");
+
+    registry.registerCommand({
+      name: "adr.list",
+      description:
+        "List all ADRs. Filter with --status, --scope, --decider flags. " +
+        "Use --json for machine-readable output. " +
+        "Parses frontmatter on the fly — no index file needed.",
+      scope: "workspace",
+      flags: {
+        status: {
+          kind: "string",
+          description: "Filter by ADR status (e.g. proposed, accepted, superseded).",
+        },
+        scope: {
+          kind: "string",
+          description: "Filter by ADR scope (package, app, workspace).",
+        },
+        decider: { kind: "string", description: "Filter by decider string." },
+      },
+      reads: ["docs/adrs/**/*.md"],
+      execute: runAdrList,
+    });
+
+    registry.registerCommand({
+      name: "adr.create",
+      description:
+        "Create a new ADR draft from the template. " +
+        'Pass --title "Short title" (required). ' +
+        "Optional: --scope, --decider, --status, --related. " +
+        "Always creates status: proposed unless overridden. " +
+        "AI agents are allowed to use this command.",
+      scope: "workspace",
+      mutatesState: true,
+      writes: ["docs/adrs/adr-*.md"],
+      reads: ["docs/adrs/**/*.md"],
+      cacheable: false,
+      flags: {
+        title: { kind: "string", required: true, description: "Short imperative ADR title." },
+        scope: {
+          kind: "string",
+          default: "package",
+          description: "ADR scope: package | app | workspace.",
+        },
+        decider: {
+          kind: "string",
+          default: "architecture",
+          description: "ADR decider, e.g. architecture or human:<handle>.",
+        },
+        status: {
+          kind: "string",
+          default: "proposed",
+          description: "ADR status: proposed | accepted | superseded | rejected.",
+        },
+        related: {
+          kind: "string",
+          description: "Comma-separated list of related RFC/ADR ids (e.g. RFC-0365,RFC-0001).",
+        },
+      },
+      execute: runAdrCreate,
+    });
+
+    registry.registerCommand({
+      name: "adr.validate",
+      description:
+        "Validate ADR frontmatter schema, required markdown sections, " +
+        "referential integrity (supersedes/supersededBy), and id/filename consistency. " +
+        "Pass --id to validate a single file, or run without arguments for all.",
+      scope: "workspace",
+      flags: {
+        id: { kind: "string", description: "Target a single ADR by id (e.g. ADR-0003)." },
+      },
+      reads: ["docs/adrs/**/*.md"],
+      execute: runAdrValidate,
+    });
+
+    registry.registerCommand({
+      name: "adr.archive",
+      description:
+        "Move terminal-status ADR files (implemented, rejected, superseded) into " +
+        "docs/adrs/archive/<status>/ subdirectories. Bidirectional: moves non-terminal " +
+        "files found in subdirectories back to root. Use --dry-run to preview. " +
+        "Use --status to filter to a single terminal status. " +
+        "Prefer the docs.archive umbrella command unless you need to archive only ADRs.",
+      scope: "workspace",
+      mutatesState: true,
+      writes: ["docs/adrs/*.md", "docs/adrs/archive/**"],
+      reads: ["docs/adrs/**/*.md"],
+      cacheable: false,
+      flags: {
+        "dry-run": {
+          kind: "boolean",
+          description: "Preview what would be moved without touching the filesystem.",
+        },
+        status: {
+          kind: "string",
+          description: "Filter to a single terminal status (implemented, rejected, superseded).",
+        },
+      },
+      execute: runAdrArchive,
+    });
+
+    registry.registerCommand({
+      name: "adr.implement.stamp",
+      description:
+        "Atomically transition an ADR from accepted/proposed to implemented. " +
+        "Validates preconditions (status, implementation commit, file cleanliness, " +
+        "concurrent safety) and mutates frontmatter in one atomic write. " +
+        "Use --dry-run to preview without mutating.",
+      scope: "workspace",
+      mutatesState: true,
+      writes: ["docs/adrs/*.md"],
+      reads: ["docs/adrs/**/*.md"],
+      cacheable: false,
+      flags: {
+        id: {
+          kind: "string",
+          required: true,
+          description: "Target ADR id (e.g. ADR-0003).",
+        },
+        "implementation-commit": {
+          kind: "string",
+          required: true,
+          description: "SHA of the implementation commit.",
+        },
+        "dry-run": {
+          kind: "boolean",
+          description: "Preview without mutating the ADR file.",
+        },
+      },
+      execute: runAdrImplementStamp,
+    });
+  },
+};

package/os/adr/frontmatter-io.ts

@@ -0,0 +1,80 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Shared ADR frontmatter file I/O — list ADR files and parse their YAML frontmatter
+without validating the shape.
+</purpose>
+<non-goals>
+  <item>Do not validate frontmatter shape — that is the validate handler.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0366: mirror the RFC frontmatter-io contract for ADRs.</item>
+  <item>RFC-0521: migrated from packages/os/site-kernel/src/adr/ to packages/forge/os/adr/.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+
+export interface ParsedAdr {
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+
+export function parseAdrFile(source: string): ParsedAdr {
+  const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) {
+    return { frontmatter: {}, body: source };
+  }
+  return {
+    frontmatter: (YAML.parse(match[1]!) ?? {}) as Record<string, unknown>,
+    body: match[2] ?? "",
+  };
+}
+
+export async function listAdrFiles(adrDirPath: string): Promise<string[]> {
+  const results: string[] = [];
+
+  async function scanDir(dirPath: string, relativePrefix: string): Promise<void> {
+    try {
+      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+      for (const entry of entries) {
+        const relativePath = relativePrefix ? `${relativePrefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+          await scanDir(path.join(dirPath, entry.name), relativePath);
+        } else if (
+          entry.isFile() &&
+          entry.name.endsWith(".md") &&
+          !entry.name.startsWith("adr-0000") &&
+          entry.name !== "README.md"
+        ) {
+          results.push(relativePath);
+        }
+      }
+    } catch {
+      // Directory doesn't exist or is unreadable — return empty
+    }
+  }
+
+  await scanDir(adrDirPath, "");
+  return results.sort();
+}
+
+export function adrFileMatchesId(fileName: string, targetId: string): boolean {
+  return path.basename(fileName).toLowerCase().startsWith(targetId.toLowerCase());
+}
+
+export async function readAndParseAdr(
+  adrDirPath: string,
+  fileName: string,
+): Promise<{ fileName: string; parsed: ParsedAdr } | undefined> {
+  try {
+    const filePath = path.join(adrDirPath, fileName);
+    const content = await fs.readFile(filePath, "utf-8");
+    return { fileName, parsed: parseAdrFile(content) };
+  } catch {
+    return undefined;
+  }
+}

package/os/adr/handlers/archive.ts

@@ -0,0 +1,244 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+ADR archive handler — moves terminal-status ADR files into status-specific
+subdirectories under docs/adrs/archive/ and moves non-terminal files found
+in subdirectories back to the root.
+</purpose>
+<non-goals>
+  <item>Does not validate ADR content — use adr.validate for that.</item>
+  <item>Does not change ADR frontmatter — only moves files on disk.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0367: implement adr.archive command for terminal-status file archiving.</item>
+  <item>RFC-0521: migrated from packages/os/site-kernel/src/adr/ to packages/forge/os/adr/.</item>
+  <item>RFC-0733: add pinned-files pre-check — skip pinned files with warning instead of moving them.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { listAdrFiles, readAndParseAdr } from "../frontmatter-io.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import { ADR_DIR } from "../types.ts";
+import { loadPinnedManifest, isPinned, isIntraDirMove } from "../../core/handlers/pinned-check.ts";
+
+export const ADR_TERMINAL_STATUSES = ["implemented", "rejected", "superseded"] as const;
+
+export interface ArchiveMove {
+  id: string;
+  file: string;
+  status: string;
+  from: string;
+  to: string;
+  direction: "into-archive" | "out-of-archive";
+}
+
+export interface ArchiveSkip {
+  id: string;
+  file: string;
+  reason: string;
+}
+
+export interface AdrArchiveResult {
+  command: "adr.archive";
+  status: "ok";
+  moved: ArchiveMove[];
+  skipped: ArchiveSkip[];
+  dryRun: boolean;
+}
+
+export async function runAdrArchive(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<AdrArchiveResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const adrDirPath = path.join(workspaceRoot, ADR_DIR);
+
+  const dryRun = context.dryRun || input.flags["dry-run"] === true;
+  const statusFilter = input.flags["status"] as string | undefined;
+
+  if (statusFilter && !ADR_TERMINAL_STATUSES.includes(statusFilter as never)) {
+    throw new Error(
+      `Invalid --status "${statusFilter}". Must be one of: ${ADR_TERMINAL_STATUSES.join(", ")}`,
+    );
+  }
+
+  const files = await listAdrFiles(adrDirPath);
+  const moved: ArchiveMove[] = [];
+  const skipped: ArchiveSkip[] = [];
+
+  // RFC-0733: Load pinned manifest once per invocation
+  let pinnedManifest = null;
+  try {
+    pinnedManifest = await loadPinnedManifest(workspaceRoot);
+  } catch {
+    // Malformed manifest — skip pre-check
+  }
+
+  for (const fileName of files) {
+    const result = await readAndParseAdr(adrDirPath, fileName);
+    if (!result) {
+      skipped.push({
+        id: "UNKNOWN",
+        file: path.join(ADR_DIR, fileName),
+        reason: "unreadable frontmatter",
+      });
+      continue;
+    }
+
+    const fm = result.parsed.frontmatter;
+    const id = String(fm["id"] ?? "UNKNOWN");
+    const status = String(fm["status"] ?? "").trim();
+    const isTerminal = status === "implemented" || status === "rejected" || status === "superseded";
+    const isInArchive = fileName.includes("/");
+    const relFile = path.join(ADR_DIR, fileName);
+    const basename = path.basename(fileName);
+
+    if (statusFilter && status !== statusFilter) {
+      skipped.push({
+        id,
+        file: relFile,
+        reason: `status ${status} does not match --status ${statusFilter}`,
+      });
+      continue;
+    }
+
+    if (isTerminal && !isInArchive) {
+      const targetDir = path.join(adrDirPath, "archive", status);
+      const targetPath = path.join(targetDir, basename);
+      const targetRel = path.join(ADR_DIR, "archive", status, basename);
+
+      // RFC-0733: Check if file is pinned before moving
+      // Gap fix: exempt intra-directory moves (file stays within the same pinned dir)
+      if (
+        pinnedManifest &&
+        isPinned(pinnedManifest, relFile) &&
+        !isIntraDirMove(pinnedManifest, relFile, targetRel)
+      ) {
+        skipped.push({ id, file: relFile, reason: "pinned (protected by .forge/pinned.yaml)" });
+        if (outputFormat === "pretty") {
+          logger.warn(`  pinned: skipping ${relFile} (protected)`);
+        }
+        continue;
+      }
+
+      try {
+        await fs.access(targetPath);
+        skipped.push({ id, file: relFile, reason: "destination exists" });
+        continue;
+      } catch {
+        // destination doesn't exist — proceed
+      }
+
+      if (!dryRun) {
+        await fs.mkdir(targetDir, { recursive: true });
+        try {
+          await fs.rename(path.join(adrDirPath, fileName), targetPath);
+        } catch (err) {
+          if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+            skipped.push({ id, file: relFile, reason: "already moved by another process" });
+            continue;
+          }
+          throw err;
+        }
+      }
+
+      moved.push({
+        id,
+        file: targetRel,
+        status,
+        from: relFile,
+        to: targetRel,
+        direction: "into-archive",
+      });
+    } else if (!isTerminal && isInArchive) {
+      const targetPath = path.join(adrDirPath, basename);
+      const targetRel = path.join(ADR_DIR, basename);
+
+      // RFC-0733: Check if file is pinned before moving
+      // Gap fix: exempt intra-directory moves (file stays within the same pinned dir)
+      if (
+        pinnedManifest &&
+        isPinned(pinnedManifest, relFile) &&
+        !isIntraDirMove(pinnedManifest, relFile, targetRel)
+      ) {
+        skipped.push({ id, file: relFile, reason: "pinned (protected by .forge/pinned.yaml)" });
+        if (outputFormat === "pretty") {
+          logger.warn(`  pinned: skipping ${relFile} (protected)`);
+        }
+        continue;
+      }
+
+      try {
+        await fs.access(targetPath);
+        skipped.push({ id, file: relFile, reason: "destination exists" });
+        continue;
+      } catch {
+        // destination doesn't exist — proceed
+      }
+
+      if (!dryRun) {
+        try {
+          await fs.rename(path.join(adrDirPath, fileName), targetPath);
+        } catch (err) {
+          if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+            skipped.push({ id, file: relFile, reason: "already moved by another process" });
+            continue;
+          }
+          throw err;
+        }
+      }
+
+      moved.push({
+        id,
+        file: targetRel,
+        status,
+        from: relFile,
+        to: targetRel,
+        direction: "out-of-archive",
+      });
+    } else if (isTerminal && isInArchive) {
+      skipped.push({ id, file: relFile, reason: `already archived (${status})` });
+    } else {
+      skipped.push({ id, file: relFile, reason: `status ${status} is non-terminal` });
+    }
+  }
+
+  if (outputFormat === "pretty") {
+    if (dryRun) {
+      logger.info(
+        `[dry-run] adr.archive: would move ${moved.length} file(s), skip ${skipped.length}`,
+      );
+    } else {
+      logger.success(`adr.archive: moved ${moved.length} file(s), skipped ${skipped.length}`);
+    }
+    for (const m of moved) {
+      logger.info(`  ${m.direction}: ${m.id} (${m.status}) ${m.from} → ${m.to}`);
+    }
+  }
+
+  return {
+    data: {
+      command: "adr.archive",
+      status: "ok",
+      moved,
+      skipped,
+      dryRun,
+    },
+    summary: dryRun
+      ? `[dry-run] Would move ${moved.length} file(s), skip ${skipped.length}`
+      : `Moved ${moved.length} file(s), skipped ${skipped.length}`,
+    nextSteps: [
+      {
+        action: "Run: pnpm exec werkstatt run adr.list --json to verify archive status",
+        kind: "optional",
+      },
+    ],
+  };
+}