@warpgogol/forge 2.8.0 → 2.8.2

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

@@ -0,0 +1,301 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge pinned.validate — checks the working tree against .forge/pinned.yaml.
+Scans git diff (staged or last-commit) for delete/move/modify operations on
+pinned files. Supports --allow-pinned-override for audited escape hatch,
+--json for structured output, and --mode ci for CI integration.</purpose>
+<non-goals>
+  <item>Does not create or modify the manifest — use pinned.init.</item>
+  <item>Does not install hooks or CI workflows — use pinned.init.</item>
+  <item>Does not block archive commands — that is the pre-check utility in pinned-check.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0733: initial pinned.validate handler with staged/ci modes, override, audit log, manifest integrity check.</item>
+  <item>Gap fix: read FORGE_PINNED_OVERRIDE env var for pre-commit hook override support.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import path from "node:path";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import {
+  loadPinnedManifest,
+  isPinned,
+  PINNED_MANIFEST_PATH,
+  PinnedManifestMalformedError,
+} from "./pinned-check.ts";
+import type {
+  PinnedManifest,
+  PinnedValidateMode,
+  PinnedValidateResult,
+  PinnedViolation,
+} from "./pinned-types.ts";
+
+const execAsync = promisify(exec);
+const AUDIT_LOG_PATH = path.join(".forge", "pinned-audit.log");
+
+/**
+ * Parse git diff --name-status output into file entries with operation types.
+ * Git status codes:
+ *   D = deleted, R = renamed (move), M = modified, A = added, C = copied
+ * Format: "R100\tdocs/old.md\tdocs/new.md" or "D\tdocs/file.md"
+ */
+function parseGitNameStatus(
+  output: string,
+): Array<{ relPath: string; operation: PinnedViolation["operation"] }> {
+  const entries: Array<{ relPath: string; operation: PinnedViolation["operation"] }> = [];
+  const lines = output.trim().split("\n").filter(Boolean);
+
+  for (const line of lines) {
+    const parts = line.split("\t");
+    if (parts.length < 2) continue;
+
+    const statusCode = parts[0] ?? "";
+    const oldPath = parts[1] ?? "";
+    const newPath = parts[2] ?? oldPath;
+
+    if (statusCode.startsWith("D")) {
+      entries.push({ relPath: oldPath, operation: "delete" });
+    } else if (statusCode.startsWith("R") || statusCode.startsWith("C")) {
+      entries.push({ relPath: oldPath, operation: "move" });
+      if (newPath !== oldPath) {
+        entries.push({ relPath: newPath, operation: "move" });
+      }
+    } else if (statusCode.startsWith("M")) {
+      entries.push({ relPath: oldPath, operation: "modify" });
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Check manifest integrity by comparing current manifest against the last-committed version.
+ * If entries have been removed, return a tampered violation.
+ */
+async function checkManifestIntegrity(
+  repoRoot: string,
+  manifest: PinnedManifest,
+): Promise<PinnedViolation | null> {
+  try {
+    const { stdout } = await execAsync(`git show HEAD:${PINNED_MANIFEST_PATH}`, {
+      cwd: repoRoot,
+      encoding: "utf8",
+    });
+    // Parse the committed manifest to compare entry paths
+    const { parse: parseYaml } = await import("yaml");
+    const committedParsed = parseYaml(stdout) as Record<string, unknown> | null;
+    if (!committedParsed || !Array.isArray(committedParsed["pinned"])) {
+      return null;
+    }
+    const committedEntries = (committedParsed["pinned"] as Array<Record<string, unknown>>).map(
+      (e) => String(e["path"] ?? ""),
+    );
+    const currentPaths = new Set(manifest.pinned.map((e) => e.path));
+
+    for (const committedPath of committedEntries) {
+      if (!currentPaths.has(committedPath)) {
+        return {
+          path: PINNED_MANIFEST_PATH,
+          mode: "freeze",
+          operation: "modify",
+          reason: `PINNED_MANIFEST_TAMPERED: entry "${committedPath}" was removed from the manifest`,
+        };
+      }
+    }
+  } catch {
+    // No committed manifest — nothing to compare against. This is normal for new repos.
+  }
+
+  return null;
+}
+
+/**
+ * Append an override event to the audit log. Uses fs.appendFile for atomic per-line writes.
+ */
+async function appendAuditLog(
+  repoRoot: string,
+  entry: {
+    timestamp: string;
+    path: string;
+    mode: string;
+    reason: string;
+  },
+): Promise<void> {
+  const logPath = path.join(repoRoot, AUDIT_LOG_PATH);
+  const line = JSON.stringify(entry) + "\n";
+  await fs.appendFile(logPath, line, "utf8");
+}
+
+export async function runPinnedValidate(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<PinnedValidateResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+
+  const mode: PinnedValidateMode =
+    (input.flags["mode"] as PinnedValidateMode | undefined) ?? "staged";
+  const json = input.flags["json"] === true || outputFormat === "json";
+  const flagRaw = input.flags["allow-pinned-override"];
+  const flagOverrides: string[] = flagRaw
+    ? Array.isArray(flagRaw)
+      ? (flagRaw as string[])
+      : [flagRaw as string]
+    : [];
+
+  // Gap fix: also read FORGE_PINNED_OVERRIDE env var (comma-separated paths).
+  // This allows the pre-commit hook to support overrides without changing the hook script.
+  // Operator sets: FORGE_PINNED_OVERRIDE=docs/rfcs/rfc-0076.md git commit
+  const envOverride = process.env["FORGE_PINNED_OVERRIDE"];
+  const envOverrides: string[] = envOverride
+    ? envOverride
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : [];
+
+  const overrides: string[] = [...flagOverrides, ...envOverrides];
+
+  // Load manifest
+  let manifest: PinnedManifest | null;
+  try {
+    manifest = await loadPinnedManifest(workspaceRoot);
+  } catch (err) {
+    if (err instanceof PinnedManifestMalformedError) {
+      return {
+        data: {
+          command: "pinned.validate",
+          status: "fail",
+          violations: [],
+          overrides: [],
+        },
+        exitCode: 2,
+        summary: `Error: ${err.message}`,
+      };
+    }
+    throw err;
+  }
+
+  if (!manifest) {
+    const msg = "No .forge/pinned.yaml found — pinned-files protection inactive.";
+    if (!json) {
+      logger.info(msg);
+    }
+    return {
+      data: {
+        command: "pinned.validate",
+        status: "pass",
+        violations: [],
+        overrides: [],
+      },
+      summary: msg,
+    };
+  }
+
+  // Get git diff
+  let diffOutput: string;
+  try {
+    if (mode === "ci") {
+      const { stdout } = await execAsync("git diff --name-status HEAD~1 HEAD", {
+        cwd: workspaceRoot,
+        encoding: "utf8",
+      });
+      diffOutput = stdout;
+    } else {
+      const { stdout } = await execAsync("git diff --cached --name-status", {
+        cwd: workspaceRoot,
+        encoding: "utf8",
+      });
+      diffOutput = stdout;
+    }
+  } catch {
+    diffOutput = "";
+  }
+
+  const changedFiles = parseGitNameStatus(diffOutput);
+
+  // Check each changed file against the manifest
+  const allViolations: PinnedViolation[] = [];
+  for (const { relPath, operation } of changedFiles) {
+    const entry = isPinned(manifest, relPath);
+    if (entry) {
+      // For protect mode, only delete and move are violations — modify is allowed
+      if (entry.mode === "protect" && operation === "modify") {
+        continue;
+      }
+      allViolations.push({
+        path: relPath,
+        mode: entry.mode,
+        operation,
+        reason: entry.reason,
+      });
+    }
+  }
+
+  // Check manifest integrity (tamper detection)
+  const tamperViolation = await checkManifestIntegrity(workspaceRoot, manifest);
+  if (tamperViolation) {
+    allViolations.push(tamperViolation);
+  }
+
+  // Filter out overridden violations
+  const overrideSet = new Set(overrides);
+  const remainingViolations: PinnedViolation[] = [];
+  const appliedOverrides: string[] = [];
+
+  for (const v of allViolations) {
+    if (overrideSet.has(v.path)) {
+      appliedOverrides.push(v.path);
+      // Log to audit file
+      await appendAuditLog(workspaceRoot, {
+        timestamp: new Date().toISOString(),
+        path: v.path,
+        mode: v.mode,
+        reason: v.reason,
+      });
+    } else {
+      remainingViolations.push(v);
+    }
+  }
+
+  const status: "pass" | "fail" = remainingViolations.length > 0 ? "fail" : "pass";
+  const result: PinnedValidateResult = {
+    command: "pinned.validate",
+    status,
+    violations: remainingViolations,
+    overrides: appliedOverrides,
+  };
+
+  if (!json) {
+    if (status === "pass") {
+      if (appliedOverrides.length > 0) {
+        logger.success(
+          `pinned.validate: passed with ${appliedOverrides.length} override(s) (logged to audit)`,
+        );
+      } else {
+        logger.success("pinned.validate: no violations");
+      }
+    } else {
+      logger.error(`pinned.validate: ${remainingViolations.length} violation(s) found`);
+      for (const v of remainingViolations) {
+        logger.error(`  ${v.operation}: ${v.path} (mode: ${v.mode}) — ${v.reason}`);
+      }
+    }
+  }
+
+  return {
+    data: result,
+    exitCode: status === "pass" ? 0 : 1,
+    summary:
+      status === "pass"
+        ? `No violations${appliedOverrides.length > 0 ? ` (${appliedOverrides.length} override(s) applied)` : ""}`
+        : `${remainingViolations.length} violation(s) found`,
+  };
+}

package/os/core/handlers/profile-resolve.ts

@@ -0,0 +1,92 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Shared active profile resolution for lifecycle commands (forge.dev, forge.build, forge.validate). Reads forge.yaml, resolves the active profile id, loads the profile YAML, and returns the StackProfile or null.</purpose>
+<non-goals>
+  <item>Do not implement command-specific logic — this is shared resolution only.</item>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0674: initial shared profile resolution for lifecycle commands.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { resolveForgeRoot } from "../../../src/config/forge-config.ts";
+import { listStackProfiles, type StackProfile } from "../../../src/profiles/stack-profile.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../../../src/types.ts";
+
+export interface ResolvedProfile {
+  profile: StackProfile;
+  profilePath: string;
+}
+
+function readProfileIdFromForgeYaml(workspaceRoot: string): string | undefined {
+  const configPath = path.join(workspaceRoot, "forge.yaml");
+  if (!fs.existsSync(configPath)) {
+    return undefined;
+  }
+  try {
+    const raw = fs.readFileSync(configPath, "utf8");
+    const parsed = parseYaml(raw) as Record<string, unknown>;
+    if (typeof parsed["profile"] === "string") {
+      return parsed["profile"];
+    }
+    const project = parsed["project"] as Record<string, unknown> | undefined;
+    if (project && Array.isArray(project["stack"]) && project["stack"].length > 0) {
+      return project["stack"][0] as string;
+    }
+  } catch {
+    // forge.yaml not parseable — no profile
+  }
+  return undefined;
+}
+
+export interface LifecycleFlags {
+  dryRun: boolean;
+  profileIdOverride?: string;
+}
+
+export function resolveLifecycleFlags(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): LifecycleFlags {
+  return {
+    dryRun: context.dryRun || input.flags["dry-run"] === true,
+    profileIdOverride:
+      typeof input.flags["profile"] === "string" ? (input.flags["profile"] as string) : undefined,
+  };
+}
+
+export function resolveActiveProfile(
+  workspaceRoot: string,
+  forgeRoot?: string,
+  profileIdOverride?: string,
+): ResolvedProfile | null {
+  const root = forgeRoot ?? resolveForgeRoot(workspaceRoot);
+  const profiles = listStackProfiles(root);
+
+  if (profiles.length === 0) {
+    return null;
+  }
+
+  let profileId: string | undefined = profileIdOverride;
+
+  if (!profileId) {
+    profileId = readProfileIdFromForgeYaml(workspaceRoot);
+  }
+
+  if (!profileId) {
+    return null;
+  }
+
+  const profile = profiles.find((p) => p.id === profileId);
+  if (!profile) {
+    return null;
+  }
+
+  const profilePath = path.join(root, "profiles", `${profileId}.yaml`);
+  return { profile, profilePath };
+}

package/os/core/handlers/release-prepare.ts

@@ -0,0 +1,294 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge.release.prepare — bundle built artifacts into a release package with a manifest. Supports --dry-run, --json, --profile.</purpose>
+<non-goals>
+  <item>Do not implement publish logic — that lives in release-publish.ts.</item>
+  <item>Do not import from @warpgogol/* in autonomous modules — os/core/ may import from @warpgogol/*.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0680: initial forge.release.prepare handler with manifest generation, artifact hashing, --dry-run.</item>
+  <item>RFC-0680 review fix: remove unused artifactId param from findBuiltArtifacts (A-2).</item>
+  <item>RFC-0680 review fix: use writeFileIfChanged for manifest write (B-1, DNA-34).</item>
+  <item>RFC-0680 review fix: document validationPassed semantics (G-3).</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readFile, copyFile, mkdir, stat } from "node:fs/promises";
+import { join, basename } from "node:path";
+import { createHash } from "node:crypto";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import { resolveActiveProfile, resolveLifecycleFlags } from "./profile-resolve.ts";
+import { loadWorkspaceDeps } from "./workspace-deps.ts";
+import { writeFileIfChanged } from "../../../src/utils/fs-idempotent.ts";
+import type { ProfileRelease } from "../../../src/profiles/profile-schema.ts";
+
+export interface ReleaseManifest {
+  schemaVersion: string;
+  releaseId: string;
+  profileId: string;
+  version: string;
+  createdAt: string;
+  artifacts: Array<{
+    artifactId: string;
+    path: string;
+    hash: string;
+    size: number;
+    deterministic: boolean;
+  }>;
+  determinismChecked: boolean;
+  validationPassed: boolean;
+}
+
+export interface ForgeReleasePrepareResult {
+  command: "forge.release.prepare";
+  profileId: string;
+  releaseDir: string;
+  manifest: ReleaseManifest;
+}
+
+function generateReleaseId(profileId: string, shortHash: string): string {
+  const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, -5);
+  return `${profileId}-${ts}-${shortHash}`;
+}
+
+async function readVersionFromPackageJson(workspaceRoot: string): Promise<string> {
+  try {
+    const raw = await readFile(join(workspaceRoot, "package.json"), "utf8");
+    const pkg = JSON.parse(raw) as { version?: string };
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+async function findBuiltArtifacts(
+  workspaceRoot: string,
+  extensions: string[],
+  produceOutput?: string,
+): Promise<string[]> {
+  if (produceOutput) {
+    const { collectFiles } = await loadWorkspaceDeps();
+    const outputPattern = produceOutput.replace("{composition}", "*");
+    const basePattern = basename(outputPattern);
+    const isGlob = basePattern.includes("*");
+    if (!isGlob) {
+      const fullPath = join(workspaceRoot, produceOutput);
+      try {
+        const _s = await stat(fullPath);
+        return [fullPath];
+      } catch {
+        return [];
+      }
+    }
+    // Extract extension from the output pattern (e.g. "*.mp4" → ".mp4")
+    const extMatch = basePattern.match(/(\.[^.]+)$/);
+    const outputExts = extMatch ? [extMatch[1]] : extensions;
+    const distDir = join(workspaceRoot, "dist");
+    const files = await collectFiles(distDir, {
+      extensions: outputExts,
+      ignore: (name) => name.startsWith("-") || name.startsWith("old-") || name === ".DS_Store",
+    });
+    const regex = new RegExp(
+      "^" + basePattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$",
+    );
+    return files.filter((f) => regex.test(basename(f)));
+  }
+  const { collectFiles } = await loadWorkspaceDeps();
+  const distDir = join(workspaceRoot, "dist");
+  return collectFiles(distDir, {
+    extensions,
+    ignore: (name) => name.startsWith("-") || name.startsWith("old-") || name === ".DS_Store",
+  });
+}
+
+export async function runReleasePrepare(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<ForgeReleasePrepareResult>> {
+  const { workspaceRoot, logger } = context;
+  const { dryRun, profileIdOverride } = resolveLifecycleFlags(input, context);
+
+  const resolved = resolveActiveProfile(workspaceRoot, context.forgeRoot, profileIdOverride);
+  if (!resolved) {
+    return {
+      data: {
+        command: "forge.release.prepare",
+        profileId: "",
+        releaseDir: "",
+        manifest: {
+          schemaVersion: "1",
+          releaseId: "",
+          profileId: "",
+          version: "",
+          createdAt: "",
+          artifacts: [],
+          determinismChecked: false,
+          validationPassed: false,
+        },
+      },
+      exitCode: 1,
+      summary: "No active profile found. Set `profile` in forge.yaml or use --profile <id>.",
+      nextSteps: [{ action: "Set profile in forge.yaml or use --profile <id>", kind: "required" }],
+    };
+  }
+
+  const { profile } = resolved;
+
+  if (!profile.release) {
+    return {
+      data: {
+        command: "forge.release.prepare",
+        profileId: profile.id,
+        releaseDir: "",
+        manifest: {
+          schemaVersion: "1",
+          releaseId: "",
+          profileId: profile.id,
+          version: "",
+          createdAt: "",
+          artifacts: [],
+          determinismChecked: false,
+          validationPassed: false,
+        },
+      },
+      exitCode: 1,
+      summary: `Profile ${profile.id} does not declare a release configuration.`,
+    };
+  }
+
+  const releaseConfig: ProfileRelease = profile.release;
+  const releaseDir = join(workspaceRoot, releaseConfig.outputDir);
+
+  const artifacts = profile.artifacts ?? [];
+  const includeArtifacts = releaseConfig.includeArtifacts;
+  const filteredArtifacts = includeArtifacts
+    ? artifacts.filter((a) => includeArtifacts.includes(a.id))
+    : artifacts.filter((a) => a.produce?.output);
+
+  const version = await readVersionFromPackageJson(workspaceRoot);
+
+  const manifestArtifacts: ReleaseManifest["artifacts"] = [];
+  let allHashes = "";
+
+  for (const artifact of filteredArtifacts) {
+    const builtFiles = await findBuiltArtifacts(
+      workspaceRoot,
+      artifact.extensions,
+      artifact.produce?.output,
+    );
+
+    if (builtFiles.length === 0) {
+      return {
+        data: {
+          command: "forge.release.prepare",
+          profileId: profile.id,
+          releaseDir: "",
+          manifest: {
+            schemaVersion: "1",
+            releaseId: "",
+            profileId: profile.id,
+            version,
+            createdAt: "",
+            artifacts: [],
+            determinismChecked: false,
+            validationPassed: false,
+          },
+        },
+        exitCode: 1,
+        summary: `Artifact ${artifact.id} has no built output — run \`forge build\` first.`,
+      };
+    }
+
+    for (const builtFile of builtFiles) {
+      const relPath = builtFile.replace(workspaceRoot + "/", "");
+      let hash = "";
+      let size = 0;
+
+      if (!dryRun) {
+        const { byteHashFile } = await loadWorkspaceDeps();
+        hash = await byteHashFile(builtFile);
+        const stats = await stat(builtFile);
+        size = stats.size;
+        allHashes += hash;
+      }
+
+      manifestArtifacts.push({
+        artifactId: artifact.id,
+        path: relPath,
+        hash,
+        size,
+        deterministic: artifact.determinism?.hashable ?? false,
+      });
+    }
+  }
+
+  const shortHash = allHashes
+    ? createHash("sha256").update(allHashes).digest("hex").slice(0, 8)
+    : "dryrun00";
+  const releaseId = generateReleaseId(profile.id, shortHash);
+  const createdAt = new Date().toISOString();
+
+  const manifest: ReleaseManifest = {
+    schemaVersion: "1",
+    releaseId,
+    profileId: profile.id,
+    version,
+    createdAt,
+    artifacts: manifestArtifacts,
+    determinismChecked: false,
+    validationPassed: true,
+  };
+
+  // G-3 note: validationPassed is set to true because forge.release.prepare
+  // does not run validation itself — the operator is expected to run
+  // `forge.validate` before `forge.release.prepare`. This mirrors the
+  // prepare-then-publish separation: prepare assumes prior validation.
+
+  if (dryRun) {
+    logger.info(`[dry-run] forge.release.prepare — profile: ${profile.id}`);
+    logger.info(`  releaseId: ${releaseId}`);
+    logger.info(`  version: ${version}`);
+    logger.info(`  outputDir: ${releaseConfig.outputDir}`);
+    for (const a of manifestArtifacts) {
+      logger.info(`  artifact: ${a.artifactId} — ${a.path}`);
+    }
+    return {
+      data: {
+        command: "forge.release.prepare",
+        profileId: profile.id,
+        releaseDir: releaseConfig.outputDir,
+        manifest,
+      },
+      summary: `[dry-run] Release prepared: ${manifestArtifacts.length} artifact(s), releaseId: ${releaseId}`,
+    };
+  }
+
+  await mkdir(releaseDir, { recursive: true });
+
+  for (const a of manifestArtifacts) {
+    const srcPath = join(workspaceRoot, a.path);
+    const dstPath = join(releaseDir, basename(a.path));
+    await copyFile(srcPath, dstPath);
+  }
+
+  const manifestPath = join(releaseDir, releaseConfig.manifestName);
+  await writeFileIfChanged(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+
+  logger.success(`  Release prepared: ${manifestArtifacts.length} artifact(s)`);
+  logger.info(`  Manifest: ${manifestPath}`);
+
+  return {
+    data: {
+      command: "forge.release.prepare",
+      profileId: profile.id,
+      releaseDir: releaseConfig.outputDir,
+      manifest,
+    },
+    summary: `Release prepared: ${manifestArtifacts.length} artifact(s), releaseId: ${releaseId}`,
+  };
+}