@warpgogol/forge 2.8.0 → 2.8.2

package/os/mission/handlers/archive.ts

@@ -0,0 +1,453 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Mission archive handler — moves terminal-state mission directories (state: closed
+or state: aborted in mission.yaml) into status-specific subdirectories under
+missions/archive/<state>/ and moves non-terminal (open) directories found in
+archive subdirectories back to missions/.
+</purpose>
+<non-goals>
+  <item>Does not validate mission manifest schema — reads only the state field.</item>
+  <item>Does not change mission.yaml — only moves directories on disk.</item>
+  <item>Does not import from @warpgogol/* packages — uses node:fs, node:child_process, and yaml only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0573: implement mission.archive command.</item>
+  <item>RFC-0573: extract moveMissionDir helper to eliminate Phase 1/2 duplication.</item>
+  <item>RFC-0801: add service-folder cleanup (node_modules, dist, .astro, .wrangler, .cache, .turbo) before archive move.</item>
+  <item>RFC-0733: add pinned-files pre-check — skip pinned mission directories with warning instead of moving them.</item>
+  <item>RFC-0804: auto-refresh pnpm-lock.yaml after directory moves.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { parse as parseYaml } from "yaml";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import { trashPath } from "../../../src/utils/fs-trash.ts";
+import {
+  MISSIONS_DIR,
+  ARCHIVE_DIR_NAME,
+  MISSION_TERMINAL_STATUSES,
+  type MissionArchiveMove,
+  type MissionArchiveSkip,
+  type MissionArchiveResult,
+} from "../types.ts";
+import { loadPinnedManifest, isPinned, isIntraDirMove } from "../../core/handlers/pinned-check.ts";
+
+const SERVICE_FOLDERS = [
+  "node_modules",
+  "dist",
+  ".astro",
+  ".wrangler",
+  ".cache",
+  ".turbo",
+] as const;
+
+async function cleanServiceFolders(workpieceDir: string): Promise<string[]> {
+  const removed: string[] = [];
+  for (const folder of SERVICE_FOLDERS) {
+    const target = path.join(workpieceDir, folder);
+    if (existsSync(target)) {
+      await fs.rm(target, { recursive: true, force: true });
+      removed.push(folder);
+    }
+  }
+  return removed;
+}
+
+async function readMissionState(missionDir: string): Promise<string | null> {
+  const manifestPath = path.join(missionDir, "mission.yaml");
+  try {
+    const raw = await fs.readFile(manifestPath, "utf8");
+    const parsed = parseYaml(raw) as Record<string, unknown>;
+    const state = parsed?.state;
+    if (typeof state === "string") return state.trim();
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+interface MoveAttempt {
+  moved: MissionArchiveMove | null;
+  skip: MissionArchiveSkip | null;
+}
+
+async function moveMissionDir(
+  sourcePath: string,
+  targetPath: string,
+  targetParentDir: string,
+  missionId: string,
+  state: string,
+  sourceRel: string,
+  targetRel: string,
+  direction: "into-archive" | "out-of-archive",
+  dryRun: boolean,
+  logger?: { info: (msg: string) => void; warn: (msg: string) => void },
+): Promise<MoveAttempt> {
+  if (existsSync(targetPath)) {
+    return { moved: null, skip: { missionId, dir: sourceRel, reason: "destination exists" } };
+  }
+
+  if (!dryRun) {
+    if (targetParentDir) {
+      await fs.mkdir(targetParentDir, { recursive: true });
+    }
+
+    // RFC-0801: Clean service folders from workpiece before move.
+    // node_modules/, dist/, .astro/, .wrangler/, .cache/, .turbo/ contain
+    // broken symlinks and stale build artifacts that waste disk space in archive.
+    // Aborted missions may not have a workpiece/ directory — skip gracefully.
+    const workpieceDir = path.join(sourcePath, "workpiece");
+    if (existsSync(workpieceDir)) {
+      try {
+        const removed = await cleanServiceFolders(workpieceDir);
+        if (removed.length > 0 && logger) {
+          logger.info(`    cleaned service folders: ${removed.join(", ")}`);
+        }
+      } catch (cleanupErr) {
+        // Non-fatal: log warning and continue with move
+        if (logger) {
+          logger.warn(
+            `  Warning: service folder cleanup failed for ${missionId}: ${cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)}`,
+          );
+        }
+      }
+    }
+
+    try {
+      await fs.rename(sourcePath, targetPath);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return {
+          moved: null,
+          skip: { missionId, dir: sourceRel, reason: "already moved by another process" },
+        };
+      }
+      throw err;
+    }
+
+    // Post-rename cleanup: a watcher or IDE may recreate stale cache
+    // directories (e.g. .astro/) at the source path after the rename.
+    // Remove the resurrected source so it doesn't leave orphan directories.
+    if (existsSync(sourcePath)) {
+      await trashPath(sourcePath);
+    }
+  }
+
+  return {
+    moved: { missionId, state, from: sourceRel, to: targetRel, direction },
+    skip: null,
+  };
+}
+
+export async function runMissionArchive(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<MissionArchiveResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const missionsPath = path.join(workspaceRoot, MISSIONS_DIR);
+
+  const dryRun = context.dryRun || input.flags["dry-run"] === true;
+  const statusFilter = input.flags["status"] as string | undefined;
+
+  if (statusFilter && !MISSION_TERMINAL_STATUSES.includes(statusFilter as never)) {
+    throw new Error(
+      `Invalid --status "${statusFilter}". Must be one of: ${MISSION_TERMINAL_STATUSES.join(", ")}`,
+    );
+  }
+
+  const moved: MissionArchiveMove[] = [];
+  const skipped: MissionArchiveSkip[] = [];
+
+  // RFC-0733: Load pinned manifest once per invocation
+  let pinnedManifest = null;
+  try {
+    pinnedManifest = await loadPinnedManifest(workspaceRoot);
+  } catch {
+    // Malformed manifest — skip pre-check
+  }
+
+  if (!existsSync(missionsPath)) {
+    if (outputFormat === "pretty") {
+      if (dryRun) {
+        logger.info("[dry-run] mission.archive: no missions/ directory — nothing to do");
+      } else {
+        logger.info("mission.archive: no missions/ directory — nothing to do");
+      }
+    }
+    return {
+      data: { command: "mission.archive", status: "ok", moved, skipped, dryRun },
+      summary: dryRun
+        ? "[dry-run] No missions/ directory — nothing to do"
+        : "No missions/ directory — nothing to do",
+    };
+  }
+
+  // Phase 1: Scan missions/ for terminal-state missions to move into archive
+  const rootEntries = await fs.readdir(missionsPath, { withFileTypes: true });
+
+  // Stale symlink cleanup: IDEs or file watchers may recreate symlinks to
+  // archived mission directories after mission.archive has moved them.
+  // These symlinks break pnpm workspace resolution and mission number derivation.
+  // Trash them before they can cause downstream issues.
+  for (const e of rootEntries) {
+    if (e.isSymbolicLink() && e.name !== ARCHIVE_DIR_NAME) {
+      const symlinkPath = path.join(missionsPath, e.name);
+      const sourceRel = `${MISSIONS_DIR}/${e.name}`;
+      if (!dryRun) {
+        await trashPath(symlinkPath);
+      }
+      skipped.push({
+        missionId: e.name,
+        dir: sourceRel,
+        reason: "stale symlink — trashed",
+      });
+      if (outputFormat === "pretty") {
+        logger.warn(`  stale symlink: trashed ${sourceRel}`);
+      }
+    }
+  }
+
+  const rootDirs = rootEntries
+    .filter((e) => e.isDirectory() && !e.isSymbolicLink() && e.name !== ARCHIVE_DIR_NAME)
+    .map((e) => e.name);
+
+  for (const missionId of rootDirs) {
+    const missionDir = path.join(missionsPath, missionId);
+    const state = await readMissionState(missionDir);
+
+    if (state === null) {
+      skipped.push({
+        missionId,
+        dir: `${MISSIONS_DIR}/${missionId}`,
+        reason: "unreadable manifest",
+      });
+      continue;
+    }
+
+    const isTerminal = MISSION_TERMINAL_STATUSES.includes(state as never);
+
+    if (!isTerminal) {
+      skipped.push({
+        missionId,
+        dir: `${MISSIONS_DIR}/${missionId}`,
+        reason: `state ${state} is non-terminal`,
+      });
+      continue;
+    }
+
+    if (statusFilter && state !== statusFilter) {
+      skipped.push({
+        missionId,
+        dir: `${MISSIONS_DIR}/${missionId}`,
+        reason: `state ${state} does not match --status ${statusFilter}`,
+      });
+      continue;
+    }
+
+    const targetDir = path.join(missionsPath, ARCHIVE_DIR_NAME, state);
+    const targetPath = path.join(targetDir, missionId);
+    const targetRel = `${MISSIONS_DIR}/${ARCHIVE_DIR_NAME}/${state}/${missionId}`;
+    const sourceRel = `${MISSIONS_DIR}/${missionId}`;
+
+    // RFC-0733: Check if mission directory is pinned before moving
+    // Gap fix: exempt intra-directory moves (dir stays within the same pinned parent)
+    if (
+      pinnedManifest &&
+      isPinned(pinnedManifest, sourceRel) &&
+      !isIntraDirMove(pinnedManifest, sourceRel, targetRel)
+    ) {
+      skipped.push({
+        missionId,
+        dir: sourceRel,
+        reason: "pinned (protected by .forge/pinned.yaml)",
+      });
+      if (outputFormat === "pretty") {
+        logger.warn(`  pinned: skipping ${sourceRel} (protected)`);
+      }
+      continue;
+    }
+
+    const result = await moveMissionDir(
+      missionDir,
+      targetPath,
+      targetDir,
+      missionId,
+      state,
+      sourceRel,
+      targetRel,
+      "into-archive",
+      dryRun,
+      logger,
+    );
+    if (result.skip) {
+      skipped.push(result.skip);
+      continue;
+    }
+    if (result.moved) moved.push(result.moved);
+  }
+
+  // Phase 2: Scan missions/archive/<state>/ for non-terminal missions to move back
+  const archivePath = path.join(missionsPath, ARCHIVE_DIR_NAME);
+  if (existsSync(archivePath)) {
+    const stateDirs = await fs.readdir(archivePath, { withFileTypes: true });
+    const stateDirNames = stateDirs.filter((e) => e.isDirectory()).map((e) => e.name);
+
+    for (const stateDirName of stateDirNames) {
+      const stateDirPath = path.join(archivePath, stateDirName);
+      const archivedMissions = await fs.readdir(stateDirPath, { withFileTypes: true });
+      const archivedDirNames = archivedMissions.filter((e) => e.isDirectory()).map((e) => e.name);
+
+      for (const missionId of archivedDirNames) {
+        const archivedMissionDir = path.join(stateDirPath, missionId);
+        const state = await readMissionState(archivedMissionDir);
+
+        if (state === null) {
+          skipped.push({
+            missionId,
+            dir: `${MISSIONS_DIR}/${ARCHIVE_DIR_NAME}/${stateDirName}/${missionId}`,
+            reason: "unreadable manifest",
+          });
+          continue;
+        }
+
+        const isTerminal = MISSION_TERMINAL_STATUSES.includes(state as never);
+
+        if (isTerminal) {
+          skipped.push({
+            missionId,
+            dir: `${MISSIONS_DIR}/${ARCHIVE_DIR_NAME}/${stateDirName}/${missionId}`,
+            reason: `already archived (${state})`,
+          });
+          continue;
+        }
+
+        // Non-terminal in archive — move back to missions/
+        const targetPath = path.join(missionsPath, missionId);
+        const targetRel = `${MISSIONS_DIR}/${missionId}`;
+        const sourceRel = `${MISSIONS_DIR}/${ARCHIVE_DIR_NAME}/${stateDirName}/${missionId}`;
+
+        // RFC-0733: Check if mission directory is pinned before moving
+        // Gap fix: exempt intra-directory moves (dir stays within the same pinned parent)
+        if (
+          pinnedManifest &&
+          isPinned(pinnedManifest, sourceRel) &&
+          !isIntraDirMove(pinnedManifest, sourceRel, targetRel)
+        ) {
+          skipped.push({
+            missionId,
+            dir: sourceRel,
+            reason: "pinned (protected by .forge/pinned.yaml)",
+          });
+          if (outputFormat === "pretty") {
+            logger.warn(`  pinned: skipping ${sourceRel} (protected)`);
+          }
+          continue;
+        }
+
+        const result = await moveMissionDir(
+          archivedMissionDir,
+          targetPath,
+          "",
+          missionId,
+          state,
+          sourceRel,
+          targetRel,
+          "out-of-archive",
+          dryRun,
+          logger,
+        );
+        if (result.skip) {
+          skipped.push(result.skip);
+          continue;
+        }
+        if (result.moved) moved.push(result.moved);
+      }
+    }
+  }
+
+  if (outputFormat === "pretty") {
+    if (dryRun) {
+      logger.info(
+        `[dry-run] mission.archive: would move ${moved.length} mission(s), skip ${skipped.length}`,
+      );
+    } else {
+      logger.success(
+        `mission.archive: moved ${moved.length} mission(s), skipped ${skipped.length}`,
+      );
+    }
+    for (const m of moved) {
+      logger.info(`  ${m.direction}: ${m.missionId} (${m.state}) ${m.from} → ${m.to}`);
+    }
+  }
+
+  // RFC-0804: Post-move lockfile refresh
+  if (!dryRun && moved.length > 0) {
+    try {
+      execSync("pnpm install", {
+        cwd: workspaceRoot,
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 120_000,
+      });
+      const lockfileStatus = execSync("git status --porcelain pnpm-lock.yaml", {
+        cwd: workspaceRoot,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+      if (lockfileStatus) {
+        execSync("git add pnpm-lock.yaml", {
+          cwd: workspaceRoot,
+          stdio: ["pipe", "pipe", "pipe"],
+        });
+        for (const m of moved) {
+          execSync(`git add -A ${JSON.stringify(m.to)}`, {
+            cwd: workspaceRoot,
+            stdio: ["pipe", "pipe", "pipe"],
+          });
+          if (existsSync(m.from)) continue;
+          execSync(`git rm -r --cached --ignore-unmatch ${JSON.stringify(m.from)}`, {
+            cwd: workspaceRoot,
+            stdio: ["pipe", "pipe", "pipe"],
+          });
+        }
+        execSync(
+          `git commit -m ${JSON.stringify(`chore: refresh pnpm-lock.yaml after mission.archive (${moved.length} moved)`)}`,
+          { cwd: workspaceRoot, stdio: ["pipe", "pipe", "pipe"] },
+        );
+        logger.info(`  Committed pnpm-lock.yaml refresh (${moved.length} missions archived)`);
+      }
+    } catch (refreshErr) {
+      logger.warn(
+        `  Lockfile refresh failed after archive — lockfile may be stale. Run 'pnpm install' manually: ${refreshErr instanceof Error ? refreshErr.message : String(refreshErr)}`,
+      );
+    }
+  }
+
+  return {
+    data: {
+      command: "mission.archive",
+      status: "ok",
+      moved,
+      skipped,
+      dryRun,
+    },
+    summary: dryRun
+      ? `[dry-run] Would move ${moved.length} mission(s), skip ${skipped.length}`
+      : `Moved ${moved.length} mission(s), skipped ${skipped.length}`,
+    nextSteps: [
+      {
+        action: "Run: pnpm exec werkstatt run mission.list --json to verify active missions",
+        kind: "optional",
+      },
+    ],
+  };
+}

package/os/mission/index.ts

@@ -0,0 +1 @@
+export { forgeMissionModule } from "./mission.module.ts";

package/os/mission/mission.module.ts

@@ -0,0 +1,48 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Register the mission 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-0573: initial forgeMissionModule registering mission.archive command.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { ForgeModule } from "../../src/forge-module.ts";
+
+export const forgeMissionModule: ForgeModule = {
+  name: "forge-mission",
+  version: "0.1.0",
+  async register(registry) {
+    const { runMissionArchive } = await import("./handlers/archive.ts");
+
+    registry.registerCommand({
+      name: "mission.archive",
+      description:
+        "Move terminal-state mission directories (state: closed or aborted in " +
+        "mission.yaml) into missions/archive/<state>/<missionId>/ subdirectories. " +
+        "Bidirectional: moves open missions found in archive subdirectories back " +
+        "to missions/. Use --dry-run to preview. Use --status to filter to a " +
+        "single terminal status (closed, aborted). " +
+        "Prefer the docs.archive umbrella command unless you need to archive only missions.",
+      scope: "workspace",
+      mutatesState: true,
+      writes: ["missions/*", "missions/archive/**"],
+      reads: ["missions/**"],
+      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 (closed, aborted).",
+        },
+      },
+      execute: runMissionArchive,
+    });
+  },
+};

package/os/mission/types.ts

@@ -0,0 +1,41 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Type definitions for the mission archive domain — mission directory discovery,
+manifest state extraction, 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-0573: initial mission archive types.</item>
+</CHANGE_SUMMARY>
+*/
+
+export const MISSIONS_DIR = "missions";
+export const ARCHIVE_DIR_NAME = "archive";
+
+export const MISSION_TERMINAL_STATUSES = ["closed", "aborted"] as const;
+
+export interface MissionArchiveMove {
+  missionId: string;
+  state: string;
+  from: string;
+  to: string;
+  direction: "into-archive" | "out-of-archive";
+}
+
+export interface MissionArchiveSkip {
+  missionId: string;
+  dir: string;
+  reason: string;
+}
+
+export interface MissionArchiveResult {
+  command: "mission.archive";
+  status: "ok";
+  moved: MissionArchiveMove[];
+  skipped: MissionArchiveSkip[];
+  dryRun: boolean;
+}

package/os/naming/index.ts

@@ -0,0 +1,14 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Expose forge naming lint command handlers through a stable package subpath.</purpose>
+<non-goals>
+  <item>Do not register project-specific naming commands.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0374: initial naming module barrel.</item>
+</CHANGE_SUMMARY>
+*/
+
+export { forgeNamingModule } from "./naming.module.ts";
+export { runNamingConventionLint } from "./naming-convention.ts";