@warpgogol/forge 2.8.0 → 2.8.2

package/os/plan/frontmatter-io.ts

@@ -0,0 +1,82 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Plan frontmatter file I/O — recursive file discovery and YAML frontmatter
+parsing for plan files under docs/plans/.
+</purpose>
+<non-goals>
+  <item>Do not validate plan content — that is a future concern.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0521: initial plan frontmatter I/O.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+import { PLAN_FILE_PATTERN } from "./types.ts";
+
+export interface ParsedPlan {
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+
+export function parsePlanFile(source: string): ParsedPlan {
+  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 listPlanFiles(planDirPath: 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("plan-0000") &&
+          entry.name !== "README.md" &&
+          PLAN_FILE_PATTERN.test(entry.name)
+        ) {
+          results.push(relativePath);
+        }
+      }
+    } catch {
+      // Directory doesn't exist or is unreadable — return empty
+    }
+  }
+
+  await scanDir(planDirPath, "");
+  return results.sort();
+}
+
+export async function readAndParsePlan(
+  planDirPath: string,
+  fileName: string,
+): Promise<{ fileName: string; parsed: ParsedPlan } | undefined> {
+  try {
+    const filePath = path.join(planDirPath, fileName);
+    const content = await fs.readFile(filePath, "utf-8");
+    return { fileName, parsed: parsePlanFile(content) };
+  } catch {
+    return undefined;
+  }
+}
+
+export function extractRfcIdFromPlanFile(fileName: string): string | undefined {
+  const match = path.basename(fileName).match(/^plan-(rfc-\d{4})-/i);
+  return match ? match[1]!.toUpperCase() : undefined;
+}

package/os/plan/handlers/archive.ts

@@ -0,0 +1,238 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Plan archive handler — moves plan files whose parent RFC has terminal status
+into status-specific subdirectories under docs/plans/archive/ and moves
+non-terminal files found in subdirectories back to the root.
+</purpose>
+<non-goals>
+  <item>Does not validate plan content.</item>
+  <item>Does not change plan frontmatter — only moves files on disk.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0521: implement plan.archive command.</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 { listPlanFiles, extractRfcIdFromPlanFile } from "../frontmatter-io.ts";
+import { loadRfcStatusMap } from "../../rfc/frontmatter-io.ts";
+import type { ArchiveMove, ArchiveSkip } from "../../rfc/handlers/archive.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import { PLAN_DIR } from "../types.ts";
+import type { PlanArchiveResult } from "../types.ts";
+import { loadPinnedManifest, isPinned, isIntraDirMove } from "../../core/handlers/pinned-check.ts";
+
+const TERMINAL_STATUSES = ["implemented", "rejected", "superseded"] as const;
+
+export async function runPlanArchive(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<PlanArchiveResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const planDirPath = path.join(workspaceRoot, PLAN_DIR);
+  const rfcDirPath = path.join(workspaceRoot, "docs", "rfcs");
+
+  const dryRun = context.dryRun || input.flags["dry-run"] === true;
+  const statusFilter = input.flags["status"] as string | undefined;
+
+  if (statusFilter && !TERMINAL_STATUSES.includes(statusFilter as never)) {
+    throw new Error(
+      `Invalid --status "${statusFilter}". Must be one of: ${TERMINAL_STATUSES.join(", ")}`,
+    );
+  }
+
+  const files = await listPlanFiles(planDirPath);
+  const rfcStatusMap = await loadRfcStatusMap(rfcDirPath);
+  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 rfcId = extractRfcIdFromPlanFile(fileName);
+    const relFile = path.join(PLAN_DIR, fileName);
+    const basename = path.basename(fileName);
+
+    if (!rfcId) {
+      skipped.push({ id: "UNKNOWN", file: relFile, reason: "no RFC id in filename" });
+      continue;
+    }
+
+    const rfcStatus = rfcStatusMap.get(rfcId);
+    if (!rfcStatus) {
+      skipped.push({ id: rfcId, file: relFile, reason: "parent RFC not found" });
+      continue;
+    }
+
+    const isTerminal =
+      rfcStatus === "implemented" || rfcStatus === "rejected" || rfcStatus === "superseded";
+    const isInArchive = fileName.includes("/");
+
+    if (statusFilter && rfcStatus !== statusFilter) {
+      skipped.push({
+        id: rfcId,
+        file: relFile,
+        reason: `parent RFC status ${rfcStatus} does not match --status ${statusFilter}`,
+      });
+      continue;
+    }
+
+    if (isTerminal && !isInArchive) {
+      const targetDir = path.join(planDirPath, "archive", rfcStatus);
+      const targetPath = path.join(targetDir, basename);
+      const targetRel = path.join(PLAN_DIR, "archive", rfcStatus, 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: rfcId,
+          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: rfcId, 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(planDirPath, fileName), targetPath);
+        } catch (err) {
+          if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+            skipped.push({ id: rfcId, file: relFile, reason: "already moved by another process" });
+            continue;
+          }
+          throw err;
+        }
+      }
+
+      moved.push({
+        id: rfcId,
+        file: targetRel,
+        status: rfcStatus,
+        from: relFile,
+        to: targetRel,
+        direction: "into-archive",
+      });
+    } else if (!isTerminal && isInArchive) {
+      const targetPath = path.join(planDirPath, basename);
+      const targetRel = path.join(PLAN_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: rfcId,
+          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: rfcId, file: relFile, reason: "destination exists" });
+        continue;
+      } catch {
+        // destination doesn't exist — proceed
+      }
+
+      if (!dryRun) {
+        try {
+          await fs.rename(path.join(planDirPath, fileName), targetPath);
+        } catch (err) {
+          if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+            skipped.push({ id: rfcId, file: relFile, reason: "already moved by another process" });
+            continue;
+          }
+          throw err;
+        }
+      }
+
+      moved.push({
+        id: rfcId,
+        file: targetRel,
+        status: rfcStatus,
+        from: relFile,
+        to: targetRel,
+        direction: "out-of-archive",
+      });
+    } else if (isTerminal && isInArchive) {
+      skipped.push({ id: rfcId, file: relFile, reason: `already archived (${rfcStatus})` });
+    } else {
+      skipped.push({
+        id: rfcId,
+        file: relFile,
+        reason: `parent RFC status ${rfcStatus} is non-terminal`,
+      });
+    }
+  }
+
+  if (outputFormat === "pretty") {
+    if (dryRun) {
+      logger.info(
+        `[dry-run] plan.archive: would move ${moved.length} file(s), skip ${skipped.length}`,
+      );
+    } else {
+      logger.success(`plan.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: "plan.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 plan.list --json to verify archive status",
+        kind: "optional",
+      },
+    ],
+  };
+}

package/os/plan/index.ts

@@ -0,0 +1,23 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Barrel export for the plan domain — types, module, and handlers.</purpose>
+<non-goals>
+  <item>Do not implement plan logic here; delegate to handlers/ and plan.module.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0521: initial plan module barrel.</item>
+</CHANGE_SUMMARY>
+*/
+
+export { forgePlanModule } from "./plan.module.ts";
+export { runPlanArchive } from "./handlers/archive.ts";
+export {
+  listPlanFiles,
+  parsePlanFile,
+  readAndParsePlan,
+  extractRfcIdFromPlanFile,
+  type ParsedPlan,
+} from "./frontmatter-io.ts";
+export type { PlanArchiveResult, PlanArchiveMove, PlanArchiveSkip } from "./types.ts";
+export { PLAN_DIR, PLAN_FILE_PATTERN } from "./types.ts";

package/os/plan/plan.module.ts

@@ -0,0 +1,48 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Register the plan archive command with the forge kernel registry.</purpose>
+<non-goals>
+  <item>Do not implement handler logic here — delegate to handlers/archive.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0521: initial forgePlanModule registering plan.archive command.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { ForgeModule } from "../../src/forge-module.ts";
+
+export const forgePlanModule: ForgeModule = {
+  name: "forge-plan",
+  version: "0.1.0",
+  async register(registry) {
+    const { runPlanArchive } = await import("./handlers/archive.ts");
+
+    registry.registerCommand({
+      name: "plan.archive",
+      description:
+        "Move plan files whose parent RFC has terminal status " +
+        "(implemented, rejected, superseded) into docs/plans/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 plans.",
+      scope: "workspace",
+      mutatesState: true,
+      writes: ["docs/plans/*.md", "docs/plans/archive/**"],
+      reads: ["docs/plans/**/*.md", "docs/rfcs/**/*.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: runPlanArchive,
+    });
+  },
+};

package/os/plan/types.ts

@@ -0,0 +1,29 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Type definitions for the plan archive domain — plan file discovery, parsing,
+and archive result shapes.
+</purpose>
+<non-goals>
+  <item>Do not define archive handler logic here — that lives in handlers/archive.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0521: initial plan archive types.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { ArchiveMove, ArchiveSkip } from "../rfc/handlers/archive.ts";
+
+export const PLAN_DIR = "docs/plans";
+export const PLAN_FILE_PATTERN = /^plan-rfc-\d{4}-/;
+
+export interface PlanArchiveResult {
+  command: "plan.archive";
+  status: "ok";
+  moved: ArchiveMove[];
+  skipped: ArchiveSkip[];
+  dryRun: boolean;
+}
+
+export type { ArchiveMove as PlanArchiveMove, ArchiveSkip as PlanArchiveSkip };