@warpgogol/forge 2.8.0 → 2.8.2

package/os/program/handlers/seal.ts

@@ -0,0 +1,332 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Command handler for program.packet.seal — Steward finalizes a packet
+against the predecessor's completion commit, updates packet state from draft
+to sealed, and records the seal in the program manifest (RFC-0856).</purpose>
+<non-goals>
+  <item>Do not commit — seal writes files only; canonical commit is separate.</item>
+  <item>Do not import from @warpgogol/* — forge must remain dependency-free.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0856: initial seal command handler.</item>
+  <item>RFC-0857: reciprocal specRef/materializedAs mapping verification for spec-node packets (AC-7).</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import { writeFileAtomic } from "../../../src/utils/fs-atomic.ts";
+import {
+  discoverProgram,
+  findPacketEntry,
+  resolvePacketPath,
+  parsePacketFile,
+  verifyNormativeSources,
+  gitBranch,
+  gitHead,
+  gitIsClean,
+} from "../discovery.ts";
+import { findActiveLeases, isLeaseStale } from "../lease.ts";
+import { validateSealTransition, type PacketViolation } from "../state.ts";
+import type { ProgramManifest, ProgramPacket, ProgramPacketIndexEntry } from "../schemas.ts";
+
+export interface SealResultData {
+  command: string;
+  status: "pass" | "fail";
+  program: string;
+  packetId: string;
+  filesModified: string[];
+  violations: PacketViolation[];
+}
+
+export async function runSeal(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<SealResultData>> {
+  const program = input.flags.program as string | undefined;
+  const packetId = input.flags.packet as string | undefined;
+  const steward = input.flags.steward as string | undefined;
+  const _idempotencyKey = input.flags["idempotency-key"] as string | undefined;
+
+  if (!program || !packetId || !steward) {
+    return {
+      data: {
+        command: "program.packet.seal",
+        status: "fail",
+        program: program ?? "<missing>",
+        packetId: packetId ?? "<missing>",
+        filesModified: [],
+        violations: [
+          {
+            rule: "PROGRAM-PACKET-01",
+            message: "--program, --packet, and --steward are required",
+          },
+        ],
+      },
+      exitCode: 1,
+      summary: "program.packet.seal: missing required flags",
+    };
+  }
+
+  const { workspaceRoot } = context;
+
+  // Discover program
+  let programLocation;
+  try {
+    programLocation = discoverProgram(workspaceRoot, program);
+  } catch (err) {
+    return sealFail(program, packetId, [
+      { rule: "PROGRAM-PACKET-01", message: String((err as Error).message) },
+    ]);
+  }
+
+  if (!programLocation) {
+    return sealFail(program, packetId, [
+      { rule: "PROGRAM-PACKET-01", message: `program ${program} not found` },
+    ]);
+  }
+
+  const { manifest, manifestPath, programDir } = programLocation;
+
+  // Find packet entry
+  const entry = findPacketEntry(manifest, packetId);
+  if (!entry) {
+    return sealFail(program, packetId, [
+      { rule: "PROGRAM-PACKET-01", message: `packet ${packetId} not found` },
+    ]);
+  }
+
+  // Parse packet file
+  let packet: ProgramPacket;
+  try {
+    packet = parsePacketFile(resolvePacketPath(programDir, entry));
+  } catch (err) {
+    return sealFail(program, packetId, [
+      { rule: "PROGRAM-PACKET-01", message: String((err as Error).message) },
+    ]);
+  }
+
+  // Verify normative source hashes
+  const hashViolations = verifyNormativeSources(workspaceRoot, packet);
+  if (hashViolations.length > 0) {
+    return sealFail(
+      program,
+      packetId,
+      hashViolations.map((v) => ({
+        rule: "PROGRAM-PACKET-07",
+        path: v.path,
+        message: `normative source hash mismatch: expected ${v.expected}, got ${v.actual}`,
+      })),
+    );
+  }
+
+  // Git state
+  let branch = "";
+  let head = "";
+  try {
+    branch = gitBranch(workspaceRoot);
+    head = gitHead(workspaceRoot);
+  } catch {
+    return sealFail(program, packetId, [
+      { rule: "PROGRAM-PACKET-02", message: "failed to read git state" },
+    ]);
+  }
+
+  // Check for active leases
+  const activeLeases = findActiveLeases(workspaceRoot, program);
+  const hasActiveLease = activeLeases.some(
+    (l) => l.packetId === packetId && !isLeaseStale(l.lease),
+  );
+
+  let isClean = false;
+  try {
+    isClean = gitIsClean(workspaceRoot);
+  } catch {
+    // ignore
+  }
+
+  // Validate transition
+  const violations = validateSealTransition(manifest, entry, packet, {
+    branch,
+    head,
+    isClean,
+    hasActiveLease,
+  });
+
+  if (violations.length > 0) {
+    return sealFail(program, packetId, violations);
+  }
+
+  // RFC-0857 AC-7: For spec-node packets, verify reciprocal specRef/materializedAs mapping
+  if (entry.decisionKind === "spec-node" && entry.resolvedRfc) {
+    const specViolation = verifySpecNodeMapping(workspaceRoot, entry);
+    if (specViolation) {
+      return sealFail(program, packetId, [specViolation]);
+    }
+  }
+
+  // --- Perform seal ---
+  const filesModified: string[] = [];
+
+  // 1. Update packet file: state → sealed, baseCommit → head (for non-bootstrap)
+  const packetPath = resolvePacketPath(programDir, entry);
+  const packetRaw = fs.readFileSync(packetPath, "utf8");
+  const packetFmMatch = packetRaw.match(/^---\n([\s\S]*?)\n---/);
+  if (!packetFmMatch) {
+    return sealFail(program, packetId, [
+      { rule: "PROGRAM-PACKET-01", message: "missing frontmatter in packet file" },
+    ]);
+  }
+  const packetFm = parseYaml(packetFmMatch[1]) as Record<string, unknown>;
+  packetFm.state = "sealed";
+  if (entry.dependsOnPacket === null) {
+    // Bootstrap packet: baseCommit stays null (set by completion)
+  } else {
+    packetFm.baseCommit = head;
+  }
+  const newPacketFm = stringifyYaml(packetFm);
+  const newPacketRaw = `---\n${newPacketFm}---\n${packetRaw.slice(packetFmMatch[0].length)}`;
+  writeFileAtomic(packetPath, newPacketRaw);
+  filesModified.push(path.relative(workspaceRoot, packetPath));
+
+  // 2. Update program manifest: packet state → sealed
+  const manifestRaw = fs.readFileSync(manifestPath, "utf8");
+  const manifestParsed = parseYaml(manifestRaw) as ProgramManifest;
+  const packetIdx = manifestParsed.packets.findIndex((p) => p.packetId === packetId);
+  if (packetIdx === -1) {
+    return sealFail(program, packetId, [
+      { rule: "PROGRAM-PACKET-01", message: "packet not found in manifest" },
+    ]);
+  }
+  manifestParsed.packets[packetIdx].state = "sealed";
+  if (entry.dependsOnPacket !== null) {
+    manifestParsed.packets[packetIdx].baseCommit = head;
+  }
+  const newManifestRaw = stringifyYaml(manifestParsed);
+  writeFileAtomic(manifestPath, newManifestRaw);
+  filesModified.push(path.relative(workspaceRoot, manifestPath));
+
+  return {
+    data: {
+      command: "program.packet.seal",
+      status: "pass",
+      program,
+      packetId,
+      filesModified,
+      violations: [],
+    },
+    exitCode: 0,
+    summary: `program.packet.seal: ${packetId} sealed on ${branch}@${head.slice(0, 8)}`,
+  };
+}
+
+function sealFail(
+  program: string,
+  packetId: string,
+  violations: PacketViolation[],
+): ForgeCommandResult<SealResultData> {
+  return {
+    data: {
+      command: "program.packet.seal",
+      status: "fail",
+      program,
+      packetId,
+      filesModified: [],
+      violations,
+    },
+    exitCode: 1,
+    summary: `program.packet.seal: ${packetId} failed with ${violations.length} violation(s)`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// RFC-0857 AC-7: Reciprocal specRef/materializedAs mapping verification
+// ---------------------------------------------------------------------------
+
+function verifySpecNodeMapping(
+  workspaceRoot: string,
+  entry: ProgramPacketIndexEntry,
+): PacketViolation | null {
+  const governingDecision = entry.governingDecision;
+  const slashIdx = governingDecision.indexOf("/");
+  if (slashIdx === -1) {
+    return {
+      rule: "PROGRAM-PACKET-12",
+      message: `spec-node governingDecision "${governingDecision}" is not in <spec-id>/<node-id> format`,
+    };
+  }
+  const specId = governingDecision.slice(0, slashIdx);
+  const nodeId = governingDecision.slice(slashIdx + 1);
+
+  // Check forge-spec.yaml for materializedAs matching resolvedRfc
+  const specPath = path.join(workspaceRoot, "docs", "specs", specId, "forge-spec.yaml");
+  if (!fs.existsSync(specPath)) {
+    return {
+      rule: "PROGRAM-PACKET-12",
+      message: `spec file not found: docs/specs/${specId}/forge-spec.yaml`,
+    };
+  }
+
+  const specRaw = fs.readFileSync(specPath, "utf8");
+  const specParsed = parseYaml(specRaw) as {
+    rfcs?: Array<{ id: string; materializedAs?: string }>;
+  };
+  const specNode = specParsed.rfcs?.find((r) => r.id === nodeId);
+  if (!specNode) {
+    return {
+      rule: "PROGRAM-PACKET-12",
+      message: `spec node ${nodeId} not found in docs/specs/${specId}/forge-spec.yaml`,
+    };
+  }
+
+  if (specNode.materializedAs !== entry.resolvedRfc) {
+    return {
+      rule: "PROGRAM-PACKET-12",
+      message: `materializedAs (${specNode.materializedAs ?? "null"}) does not match resolvedRfc (${entry.resolvedRfc}) for ${nodeId}`,
+    };
+  }
+
+  // Check RFC file for reciprocal specRef
+  const rfcPath = path.join(workspaceRoot, "docs", "rfcs", `${entry.resolvedRfc.toLowerCase()}.md`);
+  if (!fs.existsSync(rfcPath)) {
+    return {
+      rule: "PROGRAM-PACKET-12",
+      message: `RFC file not found: docs/rfcs/${entry.resolvedRfc.toLowerCase()}.md`,
+    };
+  }
+
+  const rfcRaw = fs.readFileSync(rfcPath, "utf8");
+  const rfcFmMatch = rfcRaw.match(/^---\n([\s\S]*?)\n---/);
+  if (!rfcFmMatch) {
+    return {
+      rule: "PROGRAM-PACKET-12",
+      message: `missing frontmatter in ${entry.resolvedRfc}`,
+    };
+  }
+
+  const rfcFm = parseYaml(rfcFmMatch[1]) as { specRef?: string; status?: string };
+  const expectedSpecRef = `${specId}/${nodeId}`;
+  if (rfcFm.specRef !== expectedSpecRef) {
+    return {
+      rule: "PROGRAM-PACKET-12",
+      message: `specRef (${rfcFm.specRef ?? "null"}) does not match expected ${expectedSpecRef} in ${entry.resolvedRfc}`,
+    };
+  }
+
+  // RFC must be accepted or implemented
+  if (rfcFm.status !== "accepted" && rfcFm.status !== "implemented") {
+    return {
+      rule: "PROGRAM-PACKET-12",
+      message: `${entry.resolvedRfc} status is "${rfcFm.status}", expected "accepted" or "implemented"`,
+    };
+  }
+
+  return null;
+}

package/os/program/handlers/validate.ts

@@ -0,0 +1,213 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Command handler for program.packet.validate — read-only validation
+of a program packet against schema, source hashes, branch/head, and state
+machine rules (RFC-0856).</purpose>
+<non-goals>
+  <item>Do not mutate files — validate is read-only.</item>
+  <item>Do not import from @warpgogol/* — forge must remain dependency-free.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0856: initial validate command handler.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import {
+  discoverProgram,
+  findPacketEntry,
+  resolvePacketPath,
+  parsePacketFile,
+  verifyNormativeSources,
+  gitBranch,
+  gitHead,
+  gitIsClean,
+} from "../discovery.ts";
+import { findActiveLeases, isLeaseStale } from "../lease.ts";
+import { validateSealTransition, type PacketViolation } from "../state.ts";
+
+export interface ValidateResultData {
+  command: string;
+  status: "pass" | "fail";
+  program: string;
+  packetId: string;
+  phase: string;
+  branch: string;
+  head: string;
+  violations: PacketViolation[];
+}
+
+export async function runValidate(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<ValidateResultData>> {
+  const program = input.flags.program as string | undefined;
+  const packetId = input.flags.packet as string | undefined;
+  const phase = (input.flags.phase as string | undefined) ?? "draft";
+
+  if (!program || !packetId) {
+    return {
+      data: {
+        command: "program.packet.validate",
+        status: "fail",
+        program: program ?? "<missing>",
+        packetId: packetId ?? "<missing>",
+        phase,
+        branch: "",
+        head: "",
+        violations: [
+          {
+            rule: "PROGRAM-PACKET-01",
+            message: "both --program and --packet are required",
+          },
+        ],
+      },
+      exitCode: 1,
+      summary: "program.packet.validate: missing required flags",
+    };
+  }
+
+  const { workspaceRoot } = context;
+
+  // Discover program
+  let programLocation;
+  try {
+    programLocation = discoverProgram(workspaceRoot, program);
+  } catch (err) {
+    return failResult(program, packetId, phase, [
+      {
+        rule: "PROGRAM-PACKET-01",
+        message: String((err as Error).message),
+      },
+    ]);
+  }
+
+  if (!programLocation) {
+    return failResult(program, packetId, phase, [
+      {
+        rule: "PROGRAM-PACKET-01",
+        message: `program ${program} not found in docs/plans/`,
+      },
+    ]);
+  }
+
+  const { manifest, programDir } = programLocation;
+
+  // Find packet entry
+  const entry = findPacketEntry(manifest, packetId);
+  if (!entry) {
+    return failResult(program, packetId, phase, [
+      {
+        rule: "PROGRAM-PACKET-01",
+        message: `packet ${packetId} not found in program manifest`,
+      },
+    ]);
+  }
+
+  // Parse packet file
+  let packet;
+  try {
+    packet = parsePacketFile(resolvePacketPath(programDir, entry));
+  } catch (err) {
+    return failResult(program, packetId, phase, [
+      {
+        rule: "PROGRAM-PACKET-01",
+        message: String((err as Error).message),
+      },
+    ]);
+  }
+
+  const violations: PacketViolation[] = [];
+
+  // Verify normative source hashes
+  const hashViolations = verifyNormativeSources(workspaceRoot, packet);
+  for (const v of hashViolations) {
+    violations.push({
+      rule: "PROGRAM-PACKET-07",
+      path: v.path,
+      message: `normative source hash mismatch: expected ${v.expected}, got ${v.actual}`,
+    });
+  }
+
+  // Check git state
+  let branch = "";
+  let head = "";
+  try {
+    branch = gitBranch(workspaceRoot);
+    head = gitHead(workspaceRoot);
+  } catch {
+    violations.push({
+      rule: "PROGRAM-PACKET-02",
+      message: "failed to read git state",
+    });
+  }
+
+  // Check for active leases
+  const activeLeases = findActiveLeases(workspaceRoot, program);
+  const hasActiveLease = activeLeases.some(
+    (l) => l.packetId === packetId && !isLeaseStale(l.lease),
+  );
+
+  // Validate seal transition (covers most validation rules)
+  let isClean = false;
+  try {
+    isClean = gitIsClean(workspaceRoot);
+  } catch {
+    // ignore
+  }
+
+  const sealViolations = validateSealTransition(manifest, entry, packet, {
+    branch,
+    head,
+    isClean,
+    hasActiveLease,
+  });
+  violations.push(...sealViolations);
+
+  const status = violations.length === 0 ? "pass" : "fail";
+
+  return {
+    data: {
+      command: "program.packet.validate",
+      status,
+      program,
+      packetId,
+      phase,
+      branch,
+      head,
+      violations,
+    },
+    exitCode: status === "pass" ? 0 : 1,
+    summary:
+      status === "pass"
+        ? `program.packet.validate: ${packetId} passed (${phase})`
+        : `program.packet.validate: ${packetId} failed with ${violations.length} violation(s)`,
+  };
+}
+
+function failResult(
+  program: string,
+  packetId: string,
+  phase: string,
+  violations: PacketViolation[],
+): ForgeCommandResult<ValidateResultData> {
+  return {
+    data: {
+      command: "program.packet.validate",
+      status: "fail",
+      program,
+      packetId,
+      phase,
+      branch: "",
+      head: "",
+      violations,
+    },
+    exitCode: 1,
+    summary: `program.packet.validate: ${packetId} failed with ${violations.length} violation(s)`,
+  };
+}

package/os/program/lease.ts

@@ -0,0 +1,156 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Untracked lease management for program packets. Lease files live
+under .forge/program-leases/<program>/ and contain only the token hash.
+Raw tokens are never persisted to disk.</purpose>
+<non-goals>
+  <item>Do not store raw lease tokens — only the SHA-256 hash.</item>
+  <item>Do not import from @warpgogol/* — forge must remain dependency-free.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0856: initial lease management.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { programPacketLeaseSchema, type ProgramPacketLease } from "./schemas.ts";
+
+// ---------------------------------------------------------------------------
+// Lease directory
+// ---------------------------------------------------------------------------
+
+export function leaseDir(workspaceRoot: string, program: string): string {
+  return path.join(workspaceRoot, ".forge", "program-leases", program);
+}
+
+export function leasePath(workspaceRoot: string, program: string, packetId: string): string {
+  return path.join(leaseDir(workspaceRoot, program), `${packetId}.json`);
+}
+
+// ---------------------------------------------------------------------------
+// Token utilities
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a random opaque lease token (32 bytes hex).
+ */
+export function generateLeaseToken(): string {
+  return randomBytes(32).toString("hex");
+}
+
+/**
+ * Hash a lease token for storage. Only the hash is persisted.
+ */
+export function hashLeaseToken(token: string): string {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+// ---------------------------------------------------------------------------
+// Lease CRUD (untracked files)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a lease file. Returns null if no lease exists.
+ */
+export function readLease(
+  workspaceRoot: string,
+  program: string,
+  packetId: string,
+): ProgramPacketLease | null {
+  const p = leasePath(workspaceRoot, program, packetId);
+  if (!fs.existsSync(p)) return null;
+
+  const raw = fs.readFileSync(p, "utf8");
+  const parsed = JSON.parse(raw) as Record<string, unknown>;
+  const result = programPacketLeaseSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new Error(`PROGRAM-PACKET-01: malformed lease at ${p}: ${result.error.message}`);
+  }
+  return result.data;
+}
+
+/**
+ * Write a lease file atomically.
+ */
+export function writeLease(
+  workspaceRoot: string,
+  program: string,
+  lease: ProgramPacketLease,
+): void {
+  const dir = leaseDir(workspaceRoot, program);
+  fs.mkdirSync(dir, { recursive: true });
+  const p = leasePath(workspaceRoot, program, lease.packetId);
+  const content = JSON.stringify(lease, null, 2) + "\n";
+  fs.writeFileSync(p, content);
+}
+
+/**
+ * Delete a lease file.
+ */
+export function deleteLease(workspaceRoot: string, program: string, packetId: string): void {
+  const p = leasePath(workspaceRoot, program, packetId);
+  if (fs.existsSync(p)) {
+    fs.unlinkSync(p);
+  }
+}
+
+/**
+ * Check if any active lease exists for a program (any packet).
+ */
+export function findActiveLeases(
+  workspaceRoot: string,
+  program: string,
+): Array<{ packetId: string; lease: ProgramPacketLease }> {
+  const dir = leaseDir(workspaceRoot, program);
+  if (!fs.existsSync(dir)) return [];
+
+  const results: Array<{ packetId: string; lease: ProgramPacketLease }> = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    const p = path.join(dir, entry.name);
+    const raw = fs.readFileSync(p, "utf8");
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    const result = programPacketLeaseSchema.safeParse(parsed);
+    if (result.success) {
+      results.push({
+        packetId: result.data.packetId,
+        lease: result.data,
+      });
+    }
+  }
+  return results;
+}
+
+/**
+ * Check if a lease is stale (heartbeat exceeded timeout).
+ */
+export function isLeaseStale(lease: ProgramPacketLease, now: Date = new Date()): boolean {
+  const heartbeatMs = Date.parse(lease.heartbeatAt);
+  if (Number.isNaN(heartbeatMs)) return true;
+  const elapsed = now.getTime() - heartbeatMs;
+  return elapsed > lease.timeoutSeconds * 1000;
+}
+
+/**
+ * Update heartbeat timestamp on an existing lease.
+ */
+export function updateHeartbeat(
+  workspaceRoot: string,
+  program: string,
+  packetId: string,
+  now: Date = new Date(),
+): ProgramPacketLease {
+  const existing = readLease(workspaceRoot, program, packetId);
+  if (!existing) {
+    throw new Error(`PROGRAM-PACKET-05: no lease found for ${packetId}`);
+  }
+  const updated: ProgramPacketLease = {
+    ...existing,
+    heartbeatAt: now.toISOString(),
+  };
+  writeLease(workspaceRoot, program, updated);
+  return updated;
+}