@warpgogol/forge 2.8.0 → 2.8.2

package/os/core/handlers/pinned-check.ts

@@ -0,0 +1,200 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Shared pre-check utility for the forge pinned-files protection system (RFC-0733).
+Loads the pinned manifest from .forge/pinned.yaml and provides an isPinned lookup
+that all archive handlers call before moving files. Manifest loading is cached
+per invocation — loadPinnedManifest is called once and the result is reused.</purpose>
+<non-goals>
+  <item>Does not implement validation logic (git diff parsing, violation detection) — use pinned-validate.ts.</item>
+  <item>Does not implement manifest creation — use pinned-init.ts.</item>
+  <item>Does not enforce overrides or audit logging — that is pinned-validate.ts responsibility.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0733: initial pinned-check utility — loadPinnedManifest, isPinned, checkFilesForPinned.</item>
+  <item>Gap fix: add isIntraDirMove to exempt moves within the same pinned directory (e.g. rfc.archive moves docs/rfcs/x.md → docs/rfcs/archive/implemented/x.md).</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import type { PinnedEntry, PinnedManifest, PinnedMode, PinnedViolation } from "./pinned-types.ts";
+
+const PINNED_DIR = ".forge";
+const PINNED_FILE = "pinned.yaml";
+
+/**
+ * Path to the pinned manifest relative to the repository root.
+ */
+export const PINNED_MANIFEST_PATH = path.join(PINNED_DIR, PINNED_FILE);
+
+/**
+ * Error thrown when the manifest exists but is malformed (invalid YAML or missing required fields).
+ */
+export class PinnedManifestMalformedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PinnedManifestMalformedError";
+  }
+}
+
+/**
+ * Load and parse the pinned manifest from .forge/pinned.yaml.
+ * Returns null if the file does not exist (protection is opt-in).
+ * Throws PinnedManifestMalformedError if the file exists but is not valid YAML
+ * or does not contain a `pinned` array.
+ */
+export async function loadPinnedManifest(repoRoot: string): Promise<PinnedManifest | null> {
+  const manifestPath = path.join(repoRoot, PINNED_MANIFEST_PATH);
+
+  let content: string;
+  try {
+    content = await fs.readFile(manifestPath, "utf8");
+  } catch {
+    return null;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(content);
+  } catch (err) {
+    throw new PinnedManifestMalformedError(
+      `pinned.yaml is not valid YAML: ${String((err as Error).message)}`,
+    );
+  }
+
+  if (!parsed || typeof parsed !== "object") {
+    throw new PinnedManifestMalformedError(
+      "pinned.yaml must contain a top-level object with a `pinned` array",
+    );
+  }
+
+  const obj = parsed as Record<string, unknown>;
+  if (!Array.isArray(obj["pinned"])) {
+    throw new PinnedManifestMalformedError("pinned.yaml is missing required `pinned` array field");
+  }
+
+  const entries: PinnedEntry[] = [];
+  for (const raw of obj["pinned"]) {
+    if (!raw || typeof raw !== "object") {
+      throw new PinnedManifestMalformedError(
+        "pinned.yaml: each entry must be an object with path, mode, and reason",
+      );
+    }
+    const entry = raw as Record<string, unknown>;
+    const entryPath = entry["path"];
+    const entryMode = entry["mode"];
+    const entryReason = entry["reason"];
+
+    if (typeof entryPath !== "string" || !entryPath) {
+      throw new PinnedManifestMalformedError(
+        "pinned.yaml: each entry must have a non-empty `path` string",
+      );
+    }
+    if (entryMode !== "protect" && entryMode !== "freeze") {
+      throw new PinnedManifestMalformedError(
+        `pinned.yaml: entry "${entryPath}" has invalid mode "${String(entryMode)}" — must be "protect" or "freeze"`,
+      );
+    }
+    if (typeof entryReason !== "string" || !entryReason) {
+      throw new PinnedManifestMalformedError(
+        `pinned.yaml: entry "${entryPath}" must have a non-empty reason string`,
+      );
+    }
+
+    entries.push({
+      path: entryPath,
+      mode: entryMode as PinnedMode,
+      reason: entryReason,
+    });
+  }
+
+  return { pinned: entries };
+}
+
+/**
+ * Check if a relative file path matches a pinned entry.
+ *
+ * Path matching rules:
+ * - Exact match: if the entry path equals the file path, it matches.
+ * - Directory match: if the entry path ends with `/`, it matches any file
+ *   that starts with the directory prefix (recursive).
+ *
+ * Returns the matching PinnedEntry or null if no match.
+ */
+export function isPinned(manifest: PinnedManifest, relPath: string): PinnedEntry | null {
+  const normalizedRelPath = relPath.replace(/\\/g, "/");
+
+  for (const entry of manifest.pinned) {
+    const normalizedEntryPath = entry.path.replace(/\\/g, "/");
+
+    if (normalizedEntryPath.endsWith("/")) {
+      if (normalizedRelPath.startsWith(normalizedEntryPath)) {
+        return entry;
+      }
+    } else if (normalizedRelPath === normalizedEntryPath) {
+      return entry;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Check if a move from sourceRel to destRel stays within the same pinned directory.
+ * This exempts intra-directory moves (e.g. rfc.archive moves
+ * docs/rfcs/rfc-0076.md → docs/rfcs/archive/implemented/rfc-0076.md)
+ * from the pinned pre-check, since the file hasn't left the protected directory.
+ *
+ * Only applies to directory-pinned entries (path ends with `/`).
+ * Returns true if the same pinned directory entry matches both source and dest.
+ */
+export function isIntraDirMove(
+  manifest: PinnedManifest,
+  sourceRel: string,
+  destRel: string,
+): boolean {
+  const normalizedSource = sourceRel.replace(/\\/g, "/");
+  const normalizedDest = destRel.replace(/\\/g, "/");
+
+  for (const entry of manifest.pinned) {
+    const normalizedEntryPath = entry.path.replace(/\\/g, "/");
+    if (normalizedEntryPath.endsWith("/")) {
+      if (
+        normalizedSource.startsWith(normalizedEntryPath) &&
+        normalizedDest.startsWith(normalizedEntryPath)
+      ) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Batch-check multiple file paths against the manifest.
+ * Returns violations for files that match a pinned entry.
+ * The operation type is determined by the caller (delete, move, or modify).
+ */
+export function checkFilesForPinned(
+  manifest: PinnedManifest,
+  files: Array<{ relPath: string; operation: PinnedViolation["operation"] }>,
+): PinnedViolation[] {
+  const violations: PinnedViolation[] = [];
+
+  for (const { relPath, operation } of files) {
+    const entry = isPinned(manifest, relPath);
+    if (entry) {
+      violations.push({
+        path: relPath,
+        mode: entry.mode,
+        operation,
+        reason: entry.reason,
+      });
+    }
+  }
+
+  return violations;
+}

package/os/core/handlers/pinned-init.ts

@@ -0,0 +1,333 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge pinned.init — creates .forge/pinned.yaml with default foundation
+entries, installs pre-commit hook, adds audit log to .gitignore, and optionally
+generates CI workflow. Idempotent: re-running merges defaults with existing entries.</purpose>
+<non-goals>
+  <item>Does not validate the manifest — use pinned.validate.</item>
+  <item>Does not enforce protection on archive commands — that is pinned-check.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0733: initial pinned.init handler with manifest creation, hook installation, gitignore update, and CI workflow generation.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import { writeFileIfChanged } from "../../../src/utils/fs-idempotent.ts";
+import { PINNED_MANIFEST_PATH, loadPinnedManifest } from "./pinned-check.ts";
+import type { PinnedEntry, PinnedManifest } from "./pinned-types.ts";
+
+const PRE_COMMIT_HOOK_MARKER = "# forge:pinned-check";
+const AUDIT_LOG_REL_PATH = ".forge/pinned-audit.log";
+
+/**
+ * Default pinned entries for a forge-consuming repository.
+ * These are re-added by pinned.init if missing from an existing manifest.
+ */
+export const DEFAULT_PINNED_ENTRIES: PinnedEntry[] = [
+  {
+    path: ".forge/pinned.yaml",
+    mode: "freeze",
+    reason: "Self-protection — manifest must not be tampered with",
+  },
+  {
+    path: "docs/rfcs/rfc-0000-template.md",
+    mode: "freeze",
+    reason: "RFC template — required for rfc.create",
+  },
+  {
+    path: "docs/adrs/adr-0000-template.md",
+    mode: "freeze",
+    reason: "ADR template — required for adr.create",
+  },
+  {
+    path: "docs/audits/audit-0000-template.md",
+    mode: "freeze",
+    reason: "Audit template — required for audit creation",
+  },
+  {
+    path: "docs/plans/plan-0000-template.md",
+    mode: "freeze",
+    reason: "Plan template — required for plan creation",
+  },
+  {
+    path: "docs/architecture-dna.md",
+    mode: "freeze",
+    reason: "Architecture DNA invariants — foundational governance document",
+  },
+  {
+    path: "forge.yaml",
+    mode: "protect",
+    reason: "Forge configuration — required for all forge commands",
+  },
+  {
+    path: "package.json",
+    mode: "protect",
+    reason: "Root package.json — workspace manifest",
+  },
+  {
+    path: "pnpm-workspace.yaml",
+    mode: "protect",
+    reason: "Workspace definition",
+  },
+  {
+    path: "AGENTS.md",
+    mode: "protect",
+    reason: "Agent rules manifest",
+  },
+  {
+    path: "PREFERENCES.md",
+    mode: "protect",
+    reason: "Operator preferences",
+  },
+  {
+    path: "docs/rfcs/",
+    mode: "protect",
+    reason: "RFC directory — structural foundation",
+  },
+  {
+    path: "docs/adrs/",
+    mode: "protect",
+    reason: "ADR directory — structural foundation",
+  },
+  {
+    path: "docs/audits/",
+    mode: "protect",
+    reason: "Audit directory — structural foundation",
+  },
+  {
+    path: "docs/plans/",
+    mode: "protect",
+    reason: "Plan directory — structural foundation",
+  },
+  {
+    path: "docs/sessions/",
+    mode: "protect",
+    reason: "Session directory — structural foundation",
+  },
+  {
+    path: "docs/explorations/",
+    mode: "protect",
+    reason: "Exploration directory — structural foundation",
+  },
+  {
+    path: "docs/specs/",
+    mode: "protect",
+    reason: "Spec snapshots — immutable vendored content",
+  },
+  {
+    path: "missions/",
+    mode: "protect",
+    reason: "Missions directory — structural foundation",
+  },
+];
+
+const PRE_COMMIT_HOOK_SCRIPT = `#!/bin/sh
+${PRE_COMMIT_HOOK_MARKER}
+# Installed by forge pinned.init — do not remove this marker block.
+# Pinned-files protection: blocks commits that delete/move/modify pinned files.
+# To override: FORGE_PINNED_OVERRIDE=path1,path2 git commit
+forge pinned.validate || exit 1
+`;
+
+const CI_WORKFLOW_TEMPLATE = `name: pinned-files
+on: [push, pull_request]
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      - run: npm install -g @warpgogol/forge
+      - run: forge pinned.validate --mode ci --json
+`;
+
+/**
+ * Merge default entries with existing manifest entries.
+ * - Re-adds missing default entries (forge expects them).
+ * - Never overwrites or removes custom entries.
+ */
+function mergeManifest(existing: PinnedManifest | null, defaults: PinnedEntry[]): PinnedManifest {
+  if (!existing) {
+    return { pinned: [...defaults] };
+  }
+
+  const existingPaths = new Set(existing.pinned.map((e) => e.path));
+  const merged = [...existing.pinned];
+
+  for (const def of defaults) {
+    if (!existingPaths.has(def.path)) {
+      merged.push(def);
+    }
+  }
+
+  return { pinned: merged };
+}
+
+/**
+ * Install or merge the pre-commit hook.
+ * If a hook exists, appends the forge check with a marker for idempotent re-installation.
+ */
+async function installPreCommitHook(
+  repoRoot: string,
+): Promise<"created" | "updated" | "unchanged"> {
+  const hookPath = path.join(repoRoot, ".git", "hooks", "pre-commit");
+
+  let existingContent: string;
+  try {
+    existingContent = await fs.readFile(hookPath, "utf8");
+  } catch {
+    // No existing hook — create new
+    await fs.mkdir(path.dirname(hookPath), { recursive: true });
+    await writeFileIfChanged(hookPath, PRE_COMMIT_HOOK_SCRIPT);
+    await fs.chmod(hookPath, 0o755);
+    return "created";
+  }
+
+  // Check if forge hook is already present
+  if (existingContent.includes(PRE_COMMIT_HOOK_MARKER)) {
+    return "unchanged";
+  }
+
+  // Append forge hook to existing hook
+  const mergedContent = existingContent + "\n" + PRE_COMMIT_HOOK_SCRIPT;
+  await writeFileIfChanged(hookPath, mergedContent);
+  await fs.chmod(hookPath, 0o755);
+  return "updated";
+}
+
+/**
+ * Add .forge/pinned-audit.log to .gitignore (or append to existing).
+ */
+async function addToGitignore(repoRoot: string): Promise<"created" | "updated" | "unchanged"> {
+  const gitignorePath = path.join(repoRoot, ".gitignore");
+  const entry = AUDIT_LOG_REL_PATH;
+
+  let existingContent: string;
+  try {
+    existingContent = await fs.readFile(gitignorePath, "utf8");
+  } catch {
+    // No .gitignore — create new
+    await writeFileIfChanged(gitignorePath, entry + "\n");
+    return "created";
+  }
+
+  // Check if entry already exists
+  const lines = existingContent.split("\n");
+  if (lines.some((l) => l.trim() === entry)) {
+    return "unchanged";
+  }
+
+  // Append entry
+  const mergedContent = existingContent.trimEnd() + "\n" + entry + "\n";
+  await writeFileIfChanged(gitignorePath, mergedContent);
+  return "updated";
+}
+
+/**
+ * Generate CI workflow file.
+ */
+async function generateCiWorkflow(repoRoot: string): Promise<"created" | "unchanged"> {
+  const workflowPath = path.join(repoRoot, ".github", "workflows", "pinned-check.yml");
+  await fs.mkdir(path.dirname(workflowPath), { recursive: true });
+  await writeFileIfChanged(workflowPath, CI_WORKFLOW_TEMPLATE);
+  return "created";
+}
+
+export interface PinnedInitResult {
+  command: "pinned.init";
+  status: "ok";
+  manifestPath: string;
+  manifestAction: "created" | "merged" | "unchanged";
+  entriesCount: number;
+  hookAction: "created" | "updated" | "unchanged";
+  gitignoreAction: "created" | "updated" | "unchanged";
+  ciWorkflowAction: "created" | "unchanged" | "skipped";
+}
+
+export async function runPinnedInit(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<PinnedInitResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const ci = input.flags["ci"] === true;
+
+  // Load existing manifest (if any)
+  let existingManifest: PinnedManifest | null = null;
+  try {
+    existingManifest = await loadPinnedManifest(workspaceRoot);
+  } catch {
+    // Malformed manifest — will be overwritten with defaults
+    existingManifest = null;
+  }
+
+  // Merge with defaults
+  const merged = mergeManifest(existingManifest, DEFAULT_PINNED_ENTRIES);
+
+  // Determine action
+  const manifestAction: "created" | "merged" | "unchanged" =
+    existingManifest === null
+      ? "created"
+      : merged.pinned.length > existingManifest.pinned.length
+        ? "merged"
+        : "unchanged";
+
+  // Write manifest
+  const manifestFullPath = path.join(workspaceRoot, PINNED_MANIFEST_PATH);
+  await fs.mkdir(path.dirname(manifestFullPath), { recursive: true });
+  const manifestContent = stringifyYaml(merged);
+  await writeFileIfChanged(manifestFullPath, manifestContent);
+
+  // Install pre-commit hook
+  const hookAction = await installPreCommitHook(workspaceRoot);
+
+  // Add to .gitignore
+  const gitignoreAction = await addToGitignore(workspaceRoot);
+
+  // Optional CI workflow
+  let ciWorkflowAction: "created" | "unchanged" | "skipped" = "skipped";
+  if (ci) {
+    ciWorkflowAction = await generateCiWorkflow(workspaceRoot);
+  }
+
+  const result: PinnedInitResult = {
+    command: "pinned.init",
+    status: "ok",
+    manifestPath: PINNED_MANIFEST_PATH,
+    manifestAction,
+    entriesCount: merged.pinned.length,
+    hookAction,
+    gitignoreAction,
+    ciWorkflowAction,
+  };
+
+  if (outputFormat === "pretty") {
+    logger.success(
+      `pinned.init: manifest ${manifestAction} (${merged.pinned.length} entries), hook ${hookAction}, gitignore ${gitignoreAction}` +
+        (ci ? `, CI workflow ${ciWorkflowAction}` : ""),
+    );
+  }
+
+  return {
+    data: result,
+    summary: `Manifest ${manifestAction} with ${merged.pinned.length} entries, hook ${hookAction}, gitignore ${gitignoreAction}`,
+    nextSteps: [
+      {
+        action: "Commit .forge/pinned.yaml and .gitignore changes",
+        kind: "required",
+      },
+      ...(ci
+        ? [{ action: "Commit .github/workflows/pinned-check.yml", kind: "required" as const }]
+        : []),
+    ],
+  };
+}

package/os/core/handlers/pinned-types.ts

@@ -0,0 +1,50 @@
+/*
+<MODULE_CONTRACT>
+<purpose>TypeScript contracts for the forge pinned-files protection system (RFC-0733).
+Defines the manifest, entry, violation, and result types used by pinned.init,
+pinned.validate, and the shared pre-check utility.</purpose>
+<non-goals>
+  <item>Does not implement validation logic — use pinned-check.ts and pinned-validate.ts.</item>
+  <item>Does not implement manifest creation — use pinned-init.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0733: initial pinned-files type contracts — PinnedEntry, PinnedManifest, PinnedViolation, PinnedValidateOptions, PinnedValidateResult.</item>
+</CHANGE_SUMMARY>
+*/
+
+export type PinnedMode = "protect" | "freeze";
+
+export type PinnedOperation = "delete" | "move" | "modify";
+
+export interface PinnedEntry {
+  path: string;
+  mode: PinnedMode;
+  reason: string;
+}
+
+export interface PinnedManifest {
+  pinned: PinnedEntry[];
+}
+
+export interface PinnedViolation {
+  path: string;
+  mode: PinnedMode;
+  operation: PinnedOperation;
+  reason: string;
+}
+
+export type PinnedValidateMode = "staged" | "ci";
+
+export interface PinnedValidateOptions {
+  allowPinnedOverride?: string[];
+  mode?: PinnedValidateMode;
+  json?: boolean;
+}
+
+export interface PinnedValidateResult {
+  command: "pinned.validate";
+  status: "pass" | "fail";
+  violations: PinnedViolation[];
+  overrides: string[];
+}