@warpgogol/forge 2.1.0 → 2.2.0

package/dist/os/program/handlers/validate.js

@@ -0,0 +1,164 @@
+/*
+<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 { discoverProgram, findPacketEntry, resolvePacketPath, parsePacketFile, verifyNormativeSources, gitBranch, gitHead, gitIsClean, } from "../discovery.js";
+import { findActiveLeases, isLeaseStale } from "../lease.js";
+import { validateSealTransition } from "../state.js";
+export async function runValidate(input, context) {
+    const program = input.flags.program;
+    const packetId = input.flags.packet;
+    const phase = input.flags.phase ?? "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.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.message),
+            },
+        ]);
+    }
+    const violations = [];
+    // 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, packetId, phase, violations) {
+    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)`,
+    };
+}
+//# sourceMappingURL=validate.js.map

package/dist/os/program/handlers/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../../os/program/handlers/validate.ts"],"names":[],"mappings":"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"}

package/dist/os/program/lease.d.ts

@@ -0,0 +1,39 @@
+import { type ProgramPacketLease } from "./schemas.ts";
+export declare function leaseDir(workspaceRoot: string, program: string): string;
+export declare function leasePath(workspaceRoot: string, program: string, packetId: string): string;
+/**
+ * Generate a random opaque lease token (32 bytes hex).
+ */
+export declare function generateLeaseToken(): string;
+/**
+ * Hash a lease token for storage. Only the hash is persisted.
+ */
+export declare function hashLeaseToken(token: string): string;
+/**
+ * Read a lease file. Returns null if no lease exists.
+ */
+export declare function readLease(workspaceRoot: string, program: string, packetId: string): ProgramPacketLease | null;
+/**
+ * Write a lease file atomically.
+ */
+export declare function writeLease(workspaceRoot: string, program: string, lease: ProgramPacketLease): void;
+/**
+ * Delete a lease file.
+ */
+export declare function deleteLease(workspaceRoot: string, program: string, packetId: string): void;
+/**
+ * Check if any active lease exists for a program (any packet).
+ */
+export declare function findActiveLeases(workspaceRoot: string, program: string): Array<{
+    packetId: string;
+    lease: ProgramPacketLease;
+}>;
+/**
+ * Check if a lease is stale (heartbeat exceeded timeout).
+ */
+export declare function isLeaseStale(lease: ProgramPacketLease, now?: Date): boolean;
+/**
+ * Update heartbeat timestamp on an existing lease.
+ */
+export declare function updateHeartbeat(workspaceRoot: string, program: string, packetId: string, now?: Date): ProgramPacketLease;
+//# sourceMappingURL=lease.d.ts.map

package/dist/os/program/lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease.d.ts","sourceRoot":"","sources":["../../../os/program/lease.ts"],"names":[],"mappings":"AAkBA,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAMjF,wBAAgB,QAAQ,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,wBAAgB,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1F;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAMD;;GAEG;AACH,wBAAgB,SAAS,CACvB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,kBAAkB,GAAG,IAAI,CAW3B;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,kBAAkB,GACxB,IAAI,CAMN;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAK1F;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,GACd,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAmBxD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,kBAAkB,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,CAKvF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,GAAG,GAAE,IAAiB,GACrB,kBAAkB,CAWpB"}

package/dist/os/program/lease.js

@@ -0,0 +1,129 @@
+/*
+<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 } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// Lease directory
+// ---------------------------------------------------------------------------
+export function leaseDir(workspaceRoot, program) {
+    return path.join(workspaceRoot, ".forge", "program-leases", program);
+}
+export function leasePath(workspaceRoot, program, packetId) {
+    return path.join(leaseDir(workspaceRoot, program), `${packetId}.json`);
+}
+// ---------------------------------------------------------------------------
+// Token utilities
+// ---------------------------------------------------------------------------
+/**
+ * Generate a random opaque lease token (32 bytes hex).
+ */
+export function generateLeaseToken() {
+    return randomBytes(32).toString("hex");
+}
+/**
+ * Hash a lease token for storage. Only the hash is persisted.
+ */
+export function hashLeaseToken(token) {
+    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, program, packetId) {
+    const p = leasePath(workspaceRoot, program, packetId);
+    if (!fs.existsSync(p))
+        return null;
+    const raw = fs.readFileSync(p, "utf8");
+    const parsed = JSON.parse(raw);
+    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, program, lease) {
+    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, program, packetId) {
+    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, program) {
+    const dir = leaseDir(workspaceRoot, program);
+    if (!fs.existsSync(dir))
+        return [];
+    const results = [];
+    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);
+        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, now = new Date()) {
+    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, program, packetId, now = new Date()) {
+    const existing = readLease(workspaceRoot, program, packetId);
+    if (!existing) {
+        throw new Error(`PROGRAM-PACKET-05: no lease found for ${packetId}`);
+    }
+    const updated = {
+        ...existing,
+        heartbeatAt: now.toISOString(),
+    };
+    writeLease(workspaceRoot, program, updated);
+    return updated;
+}
+//# sourceMappingURL=lease.js.map

package/dist/os/program/lease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease.js","sourceRoot":"","sources":["../../../os/program/lease.ts"],"names":[],"mappings":"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"}

package/dist/os/program/program.module.d.ts

@@ -0,0 +1,3 @@
+import type { ForgeModule } from "../../src/forge-module.ts";
+export declare const forgeProgramModule: ForgeModule;
+//# sourceMappingURL=program.module.d.ts.map

package/dist/os/program/program.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.module.d.ts","sourceRoot":"","sources":["../../../os/program/program.module.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,eAAO,MAAM,kBAAkB,EAAE,WAoMhC,CAAC"}

package/dist/os/program/program.module.js

@@ -0,0 +1,201 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Register the program packet control plane commands with the forge
+kernel registry (RFC-0856).</purpose>
+<non-goals>
+  <item>Do not implement command logic here — handlers live in handlers/*.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0856: initial program module registration.</item>
+</CHANGE_SUMMARY>
+*/
+export const forgeProgramModule = {
+    name: "forge-program",
+    version: "0.1.0",
+    async register(registry) {
+        const { runValidate } = await import("./handlers/validate.js");
+        const { runSeal } = await import("./handlers/seal.js");
+        const { runLease } = await import("./handlers/lease.js");
+        const { runComplete } = await import("./handlers/complete.js");
+        registry.registerCommand({
+            name: "program.packet.validate",
+            description: "Validate a program packet against schema, source hashes, branch/head, " +
+                "and state machine rules. Read-only. " +
+                "Usage: program.packet.validate --program=RFC-XXXX --packet=NNN-foo --phase=draft --json",
+            scope: "workspace",
+            supportsAllSites: false,
+            flags: {
+                program: {
+                    kind: "string",
+                    required: true,
+                    description: "Program RFC id (e.g. RFC-0855).",
+                },
+                packet: {
+                    kind: "string",
+                    required: true,
+                    description: "Packet id (e.g. 010-node-24).",
+                },
+                phase: {
+                    kind: "string",
+                    description: "Validation phase: draft, sealed, active, or completion.",
+                },
+                json: {
+                    kind: "boolean",
+                    description: "Machine-readable JSON output.",
+                },
+            },
+            reads: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
+            cacheable: false,
+            execute: runValidate,
+        });
+        registry.registerCommand({
+            name: "program.packet.seal",
+            description: "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. Does not commit — use ecosystem.commit after. " +
+                "Usage: program.packet.seal --program=RFC-XXXX --packet=NNN-foo " +
+                "--steward=human:id --idempotency-key=<key> --json",
+            scope: "workspace",
+            supportsAllSites: false,
+            mutatesState: true,
+            flags: {
+                program: {
+                    kind: "string",
+                    required: true,
+                    description: "Program RFC id.",
+                },
+                packet: {
+                    kind: "string",
+                    required: true,
+                    description: "Packet id to seal.",
+                },
+                steward: {
+                    kind: "string",
+                    required: true,
+                    description: "Steward actor id (human:<id> or agent:<id>).",
+                },
+                "idempotency-key": {
+                    kind: "string",
+                    description: "Idempotency key for retry-safe sealing.",
+                },
+                json: {
+                    kind: "boolean",
+                    description: "Machine-readable JSON output.",
+                },
+            },
+            writes: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
+            reads: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
+            cacheable: false,
+            execute: runSeal,
+        });
+        registry.registerCommand({
+            name: "program.packet.lease",
+            description: "Manage the exclusive local executor lease for a sealed packet. " +
+                "Actions: start, heartbeat, release, recover. " +
+                "Raw lease tokens are never persisted — only the SHA-256 hash. " +
+                "Usage: program.packet.lease --program=RFC-XXXX --packet=NNN-foo " +
+                "--action=start --executor=agent:id --json",
+            scope: "workspace",
+            supportsAllSites: false,
+            flags: {
+                program: {
+                    kind: "string",
+                    required: true,
+                    description: "Program RFC id.",
+                },
+                packet: {
+                    kind: "string",
+                    required: true,
+                    description: "Packet id.",
+                },
+                action: {
+                    kind: "string",
+                    required: true,
+                    description: "Lease action: start, heartbeat, release, or recover.",
+                },
+                executor: {
+                    kind: "string",
+                    description: "Executor actor id (required for --action=start).",
+                },
+                steward: {
+                    kind: "string",
+                    description: "Steward actor id (required for --action=recover).",
+                },
+                "lease-token": {
+                    kind: "string",
+                    description: "Opaque lease token (required for heartbeat and release).",
+                },
+                reason: {
+                    kind: "string",
+                    description: "Recovery reason (required for --action=recover).",
+                },
+                json: {
+                    kind: "boolean",
+                    description: "Machine-readable JSON output.",
+                },
+            },
+            writes: [".forge/program-leases/**"],
+            reads: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
+            cacheable: false,
+            execute: runLease,
+        });
+        registry.registerCommand({
+            name: "program.packet.complete",
+            description: "Steward validates the implementation range, writes the completion report, " +
+                "and updates the program manifest. Supports --bootstrap for packet 000. " +
+                "Does not commit — use ecosystem.commit after. " +
+                "Usage: program.packet.complete --program=RFC-XXXX --packet=NNN-foo " +
+                "--steward=human:id --lease-token=<token> --implementation-head=<sha> --json",
+            scope: "workspace",
+            supportsAllSites: false,
+            mutatesState: true,
+            flags: {
+                program: {
+                    kind: "string",
+                    required: true,
+                    description: "Program RFC id.",
+                },
+                packet: {
+                    kind: "string",
+                    required: true,
+                    description: "Packet id to complete.",
+                },
+                steward: {
+                    kind: "string",
+                    required: true,
+                    description: "Steward actor id (must differ from executor).",
+                },
+                "lease-token": {
+                    kind: "string",
+                    description: "Lease token (required for non-bootstrap).",
+                },
+                "implementation-head": {
+                    kind: "string",
+                    description: "SHA of the implementation head commit (required for non-bootstrap).",
+                },
+                "idempotency-key": {
+                    kind: "string",
+                    description: "Idempotency key for retry-safe completion.",
+                },
+                bootstrap: {
+                    kind: "boolean",
+                    description: "Bootstrap completion (packet 000 only).",
+                },
+                "seal-commit": {
+                    kind: "string",
+                    description: "Seal commit SHA (required for --bootstrap).",
+                },
+                json: {
+                    kind: "boolean",
+                    description: "Machine-readable JSON output.",
+                },
+            },
+            writes: ["docs/plans/**/completions/**", "docs/plans/**/program.yaml"],
+            reads: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
+            cacheable: false,
+            execute: runComplete,
+        });
+    },
+};
+//# sourceMappingURL=program.module.js.map

package/dist/os/program/program.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.module.js","sourceRoot":"","sources":["../../../os/program/program.module.ts"],"names":[],"mappings":"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"}