@geminix/gxpm 0.1.0

package/core/runs.ts

@@ -0,0 +1,288 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { getIssuePaths, readIssueState } from "./state";
+import { resolveSessionId } from "./session";
+import { classifyError, type ErrorType } from "./resilience";
+import { getWorkflowEventEmitter } from "./workflow-event-emitter";
+
+export const RUN_STATUSES = [
+  "preparing-workspace",
+  "building-prompt",
+  "launching-agent",
+  "streaming-turn",
+  "succeeded",
+  "failed",
+  "timed-out",
+  "stalled",
+  "canceled-by-reconciliation",
+] as const;
+
+export type RunStatus = (typeof RUN_STATUSES)[number];
+
+export const TERMINAL_RUN_STATUSES = [
+  "succeeded",
+  "failed",
+  "timed-out",
+  "stalled",
+  "canceled-by-reconciliation",
+] as const satisfies readonly RunStatus[];
+
+export type TerminalRunStatus = (typeof TERMINAL_RUN_STATUSES)[number];
+
+export interface RunEvent {
+  schemaVersion: 1;
+  type: string;
+  timestamp: string;
+  status: RunStatus;
+  message?: string;
+  payload?: Record<string, unknown>;
+}
+
+export interface RunRecord {
+  schemaVersion: 1;
+  issueId: string;
+  runId: string;
+  attempt: number;
+  status: RunStatus;
+  createdAt: string;
+  updatedAt: string;
+  sessionId: string;
+  workspacePath?: string;
+  failureReason?: string;
+  errorType?: ErrorType;
+  events: RunEvent[];
+}
+
+export interface StartRunInput {
+  root?: string;
+  issueId: string;
+  runId?: string;
+  attempt?: number;
+  status?: RunStatus | string;
+  workspacePath?: string;
+  message?: string;
+  payload?: Record<string, unknown>;
+}
+
+export interface AppendRunEventInput {
+  root?: string;
+  issueId: string;
+  runId: string;
+  type: string;
+  status?: RunStatus | string;
+  message?: string;
+  failureReason?: string;
+  errorType?: ErrorType;
+  payload?: Record<string, unknown>;
+}
+
+export interface RunRefInput {
+  root?: string;
+  issueId: string;
+  runId: string;
+}
+
+export function startRun(input: StartRunInput): RunRecord {
+  const root = input.root ?? process.cwd();
+  readIssueState({ root, issueId: input.issueId });
+  const now = new Date().toISOString();
+  const status = assertRunStatus(input.status ?? "preparing-workspace");
+  const run: RunRecord = {
+    schemaVersion: 1,
+    issueId: input.issueId,
+    runId: input.runId ? assertRunId(input.runId) : createRunId(now),
+    attempt: normalizeAttempt(input.attempt),
+    status,
+    createdAt: now,
+    updatedAt: now,
+    sessionId: resolveSessionId(),
+    workspacePath: input.workspacePath,
+    events: [
+      {
+        schemaVersion: 1,
+        type: "run.started",
+        timestamp: now,
+        status,
+        message: input.message,
+        payload: input.payload,
+      },
+    ],
+  };
+
+  try {
+    mkdirSync(runsDir(root, input.issueId), { recursive: true });
+    writeRunRecord(root, run);
+  } catch (rawError) {
+    const error = rawError instanceof Error ? rawError : new Error(String(rawError));
+    run.errorType = classifyError(error);
+    // Write what we can before re-throwing so the error type is discoverable
+    try {
+      writeRunRecord(root, run);
+    } catch {
+      // ignore secondary write failure
+    }
+    throw error;
+  }
+
+  getWorkflowEventEmitter().emit({
+    type: "run_started",
+    issueId: input.issueId,
+    runId: run.runId,
+    status: run.status,
+    timestamp: now,
+  });
+
+  return run;
+}
+
+export function appendRunEvent(input: AppendRunEventInput): RunRecord {
+  const root = input.root ?? process.cwd();
+  const run = readRun({ root, issueId: input.issueId, runId: input.runId });
+  const now = new Date().toISOString();
+  const status = assertRunStatus(input.status ?? run.status);
+
+  let errorType = input.errorType;
+  if (!errorType && input.failureReason) {
+    errorType = classifyError(new Error(input.failureReason));
+  }
+
+  const updated: RunRecord = {
+    ...run,
+    status,
+    updatedAt: now,
+    failureReason: input.failureReason ?? run.failureReason,
+    errorType: errorType ?? run.errorType,
+    events: [
+      ...run.events,
+      {
+        schemaVersion: 1,
+        type: input.type,
+        timestamp: now,
+        status,
+        message: input.message,
+        payload: input.payload,
+      },
+    ],
+  };
+
+  try {
+    writeRunRecord(root, updated);
+  } catch (rawError) {
+    const error = rawError instanceof Error ? rawError : new Error(String(rawError));
+    updated.errorType = classifyError(error);
+    try {
+      writeRunRecord(root, updated);
+    } catch {
+      // ignore secondary write failure
+    }
+    throw error;
+  }
+
+  if (isTerminalRunStatus(status)) {
+    if (status === "failed" || status === "timed-out" || status === "stalled" || status === "canceled-by-reconciliation") {
+      getWorkflowEventEmitter().emit({
+        type: "run_failed",
+        issueId: input.issueId,
+        runId: input.runId,
+        failureReason: input.failureReason,
+        timestamp: now,
+      });
+    } else {
+      getWorkflowEventEmitter().emit({
+        type: "run_completed",
+        issueId: input.issueId,
+        runId: input.runId,
+        status,
+        timestamp: now,
+      });
+    }
+  }
+
+  return updated;
+}
+
+export function readRun(input: RunRefInput): RunRecord {
+  const root = input.root ?? process.cwd();
+  const file = runPath(root, input.issueId, input.runId);
+  if (!existsSync(file)) {
+    throw new Error(`Run not found: ${input.runId}`);
+  }
+  return JSON.parse(readFileSync(file, "utf8")) as RunRecord;
+}
+
+export function deleteRun(input: RunRefInput): boolean {
+  const root = input.root ?? process.cwd();
+  const file = runPath(root, input.issueId, input.runId);
+  if (!existsSync(file)) {
+    return false;
+  }
+  unlinkSync(file);
+  return true;
+}
+
+export function listRuns(input: { root?: string; issueId: string }): RunRecord[] {
+  const root = input.root ?? process.cwd();
+  readIssueState({ root, issueId: input.issueId });
+  const dir = runsDir(root, input.issueId);
+  if (!existsSync(dir)) {
+    return [];
+  }
+
+  return readdirSync(dir)
+    .filter((name) => name.endsWith(".json"))
+    .map((name) => JSON.parse(readFileSync(join(dir, name), "utf8")) as RunRecord)
+    .sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0));
+}
+
+export function isTerminalRunStatus(status: RunStatus): status is TerminalRunStatus {
+  return TERMINAL_RUN_STATUSES.includes(status as TerminalRunStatus);
+}
+
+function writeRunRecord(root: string, run: RunRecord) {
+  writeFileSync(runPath(root, run.issueId, run.runId), `${JSON.stringify(run, null, 2)}\n`);
+}
+
+function runsDir(root: string, issueId: string) {
+  return join(getIssuePaths(root, issueId).issueDir, "runs");
+}
+
+function runPath(root: string, issueId: string, runId: string) {
+  return join(runsDir(root, issueId), `${assertRunId(runId)}.json`);
+}
+
+export function createRunId(timestamp: string) {
+  const compact = timestamp.replace(/[-:.TZ]/g, "").slice(0, 14);
+  return `run-${compact}-${randomUUID().slice(0, 8)}`;
+}
+
+function assertRunId(value: string) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value)) {
+    throw new Error(`Invalid run id: ${value}`);
+  }
+  return value;
+}
+
+function assertRunStatus(value: string): RunStatus {
+  if (!RUN_STATUSES.includes(value as RunStatus)) {
+    throw new Error(`Invalid run status: ${value}`);
+  }
+  return value as RunStatus;
+}
+
+function normalizeAttempt(value: number | undefined) {
+  if (value === undefined) {
+    return 1;
+  }
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error("run attempt must be a positive integer");
+  }
+  return value;
+}

package/core/safe-path.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { normalizePath, isPathInsideRoot, assertPathInsideRoot, ensureInside } from "./safe-path";
+import { resolve, join } from "node:path";
+import { mkdtempSync, rmSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+
+let tmpDir: string;
+
+function setupTmp() {
+  tmpDir = mkdtempSync(join(tmpdir(), "safe-path-test-"));
+  mkdirSync(join(tmpDir, "foo", "bar"), { recursive: true });
+}
+
+function cleanupTmp() {
+  if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
+}
+
+describe("normalizePath", () => {
+  it("resolves relative paths", () => {
+    expect(normalizePath(".")).toBe(resolve("."));
+  });
+
+  it("normalizes trailing slashes", () => {
+    const p = normalizePath("/tmp/");
+    expect(p.endsWith("/")).toBe(false);
+  });
+});
+
+describe("isPathInsideRoot", () => {
+  beforeEach(() => setupTmp());
+  afterEach(() => cleanupTmp());
+
+  it("returns true for paths inside root", () => {
+    expect(isPathInsideRoot(tmpDir, join(tmpDir, "foo"))).toBe(true);
+    expect(isPathInsideRoot(tmpDir, join(tmpDir, "foo", "bar"))).toBe(true);
+  });
+
+  it("returns true for root itself", () => {
+    expect(isPathInsideRoot(tmpDir, tmpDir)).toBe(true);
+  });
+
+  it("returns false for paths outside root", () => {
+    expect(isPathInsideRoot(tmpDir, "/usr")).toBe(false);
+    expect(isPathInsideRoot(join(tmpDir, "foo"), join(tmpDir, "bar"))).toBe(false);
+  });
+
+  it("returns false for traversal escapes", () => {
+    expect(isPathInsideRoot(tmpDir, join(tmpDir, "..", "etc"))).toBe(false);
+  });
+});
+
+describe("assertPathInsideRoot", () => {
+  beforeEach(() => setupTmp());
+  afterEach(() => cleanupTmp());
+
+  it("does not throw for valid paths", () => {
+    expect(() => assertPathInsideRoot(tmpDir, join(tmpDir, "foo"))).not.toThrow();
+  });
+
+  it("throws for escaped paths", () => {
+    expect(() => assertPathInsideRoot(tmpDir, "/usr")).toThrow("Path escapes allowed root");
+  });
+});
+
+describe("ensureInside", () => {
+  beforeEach(() => setupTmp());
+  afterEach(() => cleanupTmp());
+
+  it("accepts single root", () => {
+    expect(() => ensureInside(join(tmpDir, "foo"), tmpDir)).not.toThrow();
+  });
+
+  it("accepts multiple roots if one matches", () => {
+    expect(() => ensureInside(join(tmpDir, "foo"), ["/usr", tmpDir])).not.toThrow();
+  });
+
+  it("throws if none match", () => {
+    expect(() => ensureInside("/usr", ["/tmp", "/var"])).toThrow("Path escape blocked");
+  });
+});

package/core/safe-path.ts

@@ -0,0 +1,60 @@
+/**
+ * Safe Path — shared path escape guard.
+ *
+ * Extracted from core/gate.ts and core/workspace-runtime.ts.
+ * All file-system writes must validate target paths through these utilities.
+ */
+
+import { realpathSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+
+/**
+ * Normalize a path for comparison.
+ * Resolves symlinks via realpathSync if available; falls back to resolve.
+ */
+export function normalizePath(path: string): string {
+  const resolved = resolve(path).replace(/\/+$/, "");
+  try {
+    return realpathSync.native(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+/**
+ * Check whether `candidate` is inside `root` (inclusive).
+ */
+export function isPathInsideRoot(root: string, candidate: string): boolean {
+  const normalizedRoot = normalizePath(root);
+  const normalizedCandidate = normalizePath(candidate);
+  const rel = relative(normalizedRoot, normalizedCandidate);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+/**
+ * Assert that `candidate` is inside `root`. Throws if not.
+ */
+export function assertPathInsideRoot(root: string, candidate: string): void {
+  if (!isPathInsideRoot(root, candidate)) {
+    throw new Error(
+      `Path escapes allowed root: candidate=${resolve(candidate)} root=${normalizePath(root)}`
+    );
+  }
+}
+
+/**
+ * Ensure a write target is inside one of the allowed roots.
+ * Accepts multiple allowed roots (e.g. project root + tmp dir).
+ */
+export function ensureInside(
+  target: string,
+  allowedRoot: string | readonly string[]
+): void {
+  const roots = Array.isArray(allowedRoot) ? allowedRoot : [allowedRoot];
+  const ok = roots.some((root) => isPathInsideRoot(root, target));
+  if (!ok) {
+    throw new Error(
+      `Path escape blocked: target=${resolve(target)} allowedRoots=${roots.map(normalizePath).join(", ")}`
+    );
+  }
+}

package/core/sdd-gate.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect } from "bun:test";
+import { runSddGate, extractConstitutionCheck, formatSddGateResult } from "./sdd-gate";
+
+describe("runSddGate", () => {
+  it("passes when all automated checks are true", () => {
+    const result = runSddGate({
+      capabilityDeclared: true,
+      testStrategyDefined: true,
+      simplicityJustified: true,
+      integrationPathClear: true,
+    });
+    expect(result.passed).toBe(true);
+    expect(result.failedChecks).toHaveLength(0);
+    expect(result.passedChecks).toHaveLength(4);
+  });
+
+  it("fails when any automated check is false", () => {
+    const result = runSddGate({
+      capabilityDeclared: true,
+      testStrategyDefined: false,
+      simplicityJustified: true,
+      integrationPathClear: true,
+    });
+    expect(result.passed).toBe(false);
+    expect(result.failedChecks.length).toBeGreaterThan(0);
+    expect(result.failedChecks[0].article).toContain("Test-First");
+  });
+
+  it("fails when all automated checks are missing", () => {
+    const result = runSddGate({});
+    expect(result.passed).toBe(false);
+    expect(result.failedChecks).toHaveLength(4);
+  });
+
+  it("includes manual review articles", () => {
+    const result = runSddGate({
+      capabilityDeclared: true,
+      testStrategyDefined: true,
+      simplicityJustified: true,
+      integrationPathClear: true,
+    });
+    expect(result.manualReviewArticles.length).toBeGreaterThan(0);
+    expect(result.manualReviewArticles.some((a) => a.includes("Anti-Abstraction"))).toBe(true);
+  });
+});
+
+describe("extractConstitutionCheck", () => {
+  it("extracts valid constitution check", () => {
+    const payload = {
+      constitutionCheck: {
+        capabilityDeclared: true,
+        capabilitySlice: "execution.multi-agent",
+        testStrategyDefined: true,
+        testStrategy: "unit + integration",
+        simplicityJustified: true,
+        simplicityJustification: "3 modules",
+        integrationPathClear: true,
+        integrationPath: "real CLI in worktree",
+      },
+    };
+    const result = extractConstitutionCheck(payload);
+    expect(result).not.toBeNull();
+    expect(result!.capabilityDeclared).toBe(true);
+    expect(result!.capabilitySlice).toBe("execution.multi-agent");
+  });
+
+  it("returns null when constitutionCheck is missing", () => {
+    expect(extractConstitutionCheck({})).toBeNull();
+  });
+
+  it("handles partial data with defaults", () => {
+    const payload = { constitutionCheck: { capabilityDeclared: true } };
+    const result = extractConstitutionCheck(payload);
+    expect(result!.capabilityDeclared).toBe(true);
+    expect(result!.testStrategyDefined).toBe(false);
+  });
+});
+
+describe("formatSddGateResult", () => {
+  it("formats passed result", () => {
+    const result = runSddGate({
+      capabilityDeclared: true,
+      testStrategyDefined: true,
+      simplicityJustified: true,
+      integrationPathClear: true,
+    });
+    const text = formatSddGateResult(result);
+    expect(text).toContain("PASSED");
+    expect(text).toContain("✅");
+  });
+
+  it("formats failed result", () => {
+    const result = runSddGate({ capabilityDeclared: false });
+    const text = formatSddGateResult(result);
+    expect(text).toContain("FAILED");
+    expect(text).toContain("❌");
+  });
+});

package/core/sdd-gate.ts

@@ -0,0 +1,134 @@
+/**
+ * SDD Gate — automated Nine Articles checker.
+ *
+ * Validates that an implementation-plan artifact passes the Phase -1 Gates
+ * before allowing triage → plan advancement.
+ *
+ * Articles checked automatically:
+ *   1. Capability-First      → constitutionCheck.capabilityDeclared
+ *   3. Test-First            → constitutionCheck.testStrategyDefined
+ *   7. Simplicity Gate       → constitutionCheck.simplicityJustified
+ *   9. Integration-First     → constitutionCheck.integrationPathClear
+ *
+ * Articles requiring human judgment (not automated here):
+ *   2. CLI Interface Mandate, 4. Composition, 5. Explicit, 6. Fail Fast, 8. Anti-Abstraction
+ */
+
+export interface ConstitutionCheck {
+  capabilityDeclared: boolean;
+  capabilitySlice?: string;
+  testStrategyDefined: boolean;
+  testStrategy?: string;
+  simplicityJustified: boolean;
+  simplicityJustification?: string;
+  integrationPathClear: boolean;
+  integrationPath?: string;
+}
+
+export interface SddGateResult {
+  passed: boolean;
+  /** Which articles passed */
+  passedChecks: string[];
+  /** Which articles failed with reasons */
+  failedChecks: { article: string; reason: string }[];
+  /** Human-judgment articles that require manual review */
+  manualReviewArticles: string[];
+}
+
+const AUTOMATED_ARTICLES = [
+  { key: "capabilityDeclared", name: "Capability-First (Article 1)" },
+  { key: "testStrategyDefined", name: "Test-First (Article 3)" },
+  { key: "simplicityJustified", name: "Simplicity Gate (Article 7)" },
+  { key: "integrationPathClear", name: "Integration-First (Article 9)" },
+] as const;
+
+const MANUAL_ARTICLES = [
+  "CLI Interface Mandate (Article 2)",
+  "Composition over Inheritance (Article 4)",
+  "Explicit over Implicit (Article 5)",
+  "Fail Fast, Fail Loud (Article 6)",
+  "Anti-Abstraction (Article 8)",
+];
+
+/**
+ * Run automated SDD constitution checks against a constitutionCheck payload.
+ */
+export function runSddGate(check: Partial<ConstitutionCheck>): SddGateResult {
+  const passedChecks: string[] = [];
+  const failedChecks: { article: string; reason: string }[] = [];
+
+  for (const article of AUTOMATED_ARTICLES) {
+    const value = check[article.key as keyof ConstitutionCheck];
+    if (value === true) {
+      passedChecks.push(article.name);
+    } else {
+      failedChecks.push({
+        article: article.name,
+        reason: `${article.key} is not true`,
+      });
+    }
+  }
+
+  return {
+    passed: failedChecks.length === 0,
+    passedChecks,
+    failedChecks,
+    manualReviewArticles: MANUAL_ARTICLES,
+  };
+}
+
+/**
+ * Validate a raw implementation-plan payload and return a typed ConstitutionCheck.
+ * Returns null if the payload does not contain a constitutionCheck field.
+ */
+export function extractConstitutionCheck(
+  planPayload: Record<string, unknown>
+): ConstitutionCheck | null {
+  const raw = planPayload.constitutionCheck;
+  if (!raw || typeof raw !== "object") return null;
+
+  const c = raw as Record<string, unknown>;
+  return {
+    capabilityDeclared: c.capabilityDeclared === true,
+    capabilitySlice: typeof c.capabilitySlice === "string" ? c.capabilitySlice : undefined,
+    testStrategyDefined: c.testStrategyDefined === true,
+    testStrategy: typeof c.testStrategy === "string" ? c.testStrategy : undefined,
+    simplicityJustified: c.simplicityJustified === true,
+    simplicityJustification: typeof c.simplicityJustification === "string" ? c.simplicityJustification : undefined,
+    integrationPathClear: c.integrationPathClear === true,
+    integrationPath: typeof c.integrationPath === "string" ? c.integrationPath : undefined,
+  };
+}
+
+/**
+ * Format SDD gate result for CLI output.
+ */
+export function formatSddGateResult(result: SddGateResult): string {
+  const lines: string[] = [];
+
+  lines.push(`SDD Constitution Check: ${result.passed ? "✅ PASSED" : "❌ FAILED"}`);
+  lines.push("");
+
+  if (result.passedChecks.length > 0) {
+    lines.push("Automated checks passed:");
+    for (const name of result.passedChecks) {
+      lines.push(`  ✅ ${name}`);
+    }
+  }
+
+  if (result.failedChecks.length > 0) {
+    lines.push("");
+    lines.push("Automated checks failed:");
+    for (const item of result.failedChecks) {
+      lines.push(`  ❌ ${item.article}: ${item.reason}`);
+    }
+  }
+
+  lines.push("");
+  lines.push("Manual review required:");
+  for (const name of result.manualReviewArticles) {
+    lines.push(`  ⚠️  ${name}`);
+  }
+
+  return lines.join("\n");
+}