@wopr-network/defcon 0.2.0

package/dist/execution/provision-worktree.d.ts

@@ -0,0 +1,16 @@
+export interface ProvisionWorktreeResult {
+    worktreePath: string;
+    branch: string;
+    repo: string;
+}
+export declare function parseIssueNumber(issueKey: string): string;
+export declare function repoName(repo: string): string;
+export declare function validateRepoName(name: string): string;
+export declare function buildBranch(issueKey: string): string;
+export declare function buildWorktreePath(repo: string, issueKey: string, basePath: string): string;
+export declare function provisionWorktree(opts: {
+    repo: string;
+    issueKey: string;
+    basePath?: string;
+    cloneRoot?: string;
+}): ProvisionWorktreeResult;

package/dist/execution/provision-worktree.js

@@ -0,0 +1,123 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+export function parseIssueNumber(issueKey) {
+    const match = issueKey.match(/^[A-Za-z]+[-](\d+)$/);
+    if (!match) {
+        throw new Error(`Invalid issue key: ${issueKey}. Expected format: WOP-123`);
+    }
+    return match[1];
+}
+export function repoName(repo) {
+    const parts = repo.replace(/\/$/, "").split("/");
+    return parts[parts.length - 1] || repo;
+}
+export function validateRepoName(name) {
+    if (!/^[a-zA-Z0-9._-]+$/.test(name)) {
+        throw new Error(`Invalid repo name: ${name}`);
+    }
+    if (name === "." || name === "..") {
+        throw new Error(`Invalid repo name: ${name}`);
+    }
+    return name;
+}
+export function buildBranch(issueKey) {
+    const num = parseIssueNumber(issueKey);
+    return `agent/coder-${num}/${issueKey.toLowerCase()}`;
+}
+export function buildWorktreePath(repo, issueKey, basePath) {
+    const name = repoName(repo);
+    const num = parseIssueNumber(issueKey);
+    return join(basePath, `wopr-${name}-coder-${num}`);
+}
+function run(cmd, args, cwd) {
+    try {
+        return execFileSync(cmd, args, {
+            cwd,
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+    }
+    catch (err) {
+        const e = err;
+        throw new Error(`${cmd} ${args.join(" ")} failed: ${e.stderr ?? e.message ?? String(err)}`);
+    }
+}
+export function provisionWorktree(opts) {
+    const basePath = opts.basePath ?? join(homedir(), "worktrees");
+    const cloneRoot = opts.cloneRoot ?? homedir();
+    const name = validateRepoName(repoName(opts.repo));
+    const clonePath = join(cloneRoot, name);
+    if (!resolve(clonePath).startsWith(`${resolve(cloneRoot)}/`) && resolve(clonePath) !== resolve(cloneRoot)) {
+        throw new Error(`Repo name escapes cloneRoot: ${name}`);
+    }
+    const worktreePath = buildWorktreePath(opts.repo, opts.issueKey, basePath);
+    const branch = buildBranch(opts.issueKey);
+    // Idempotent: if worktree already exists, verify and return
+    if (existsSync(worktreePath)) {
+        try {
+            run("git", ["rev-parse", "--git-dir"], worktreePath);
+            const currentBranch = run("git", ["rev-parse", "--abbrev-ref", "HEAD"], worktreePath);
+            if (currentBranch !== branch) {
+                throw new Error(`Worktree at ${worktreePath} is on branch ${currentBranch}, expected ${branch}`);
+            }
+            const remoteUrl = run("git", ["remote", "get-url", "origin"], worktreePath);
+            const repoPath = opts.repo.replace(/\.git$/, "");
+            const urlMatchesRepo = remoteUrl.endsWith(`/${repoPath}`) ||
+                remoteUrl.endsWith(`/${repoPath}.git`) ||
+                remoteUrl.endsWith(`:${repoPath}`) ||
+                remoteUrl.endsWith(`:${repoPath}.git`);
+            if (!urlMatchesRepo) {
+                throw new Error(`Worktree at ${worktreePath} has unexpected remote: ${remoteUrl} (expected to contain ${opts.repo})`);
+            }
+            return { worktreePath, branch, repo: opts.repo };
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.startsWith("Worktree at")) {
+                throw err;
+            }
+            throw new Error(`Path ${worktreePath} exists but is not a git worktree`);
+        }
+    }
+    // Clone if repo not present
+    if (!existsSync(clonePath)) {
+        const cloneUrl = `https://github.com/${opts.repo}.git`;
+        process.stderr.write(`Cloning ${cloneUrl} to ${clonePath}...\n`);
+        run("git", ["clone", cloneUrl, clonePath]);
+    }
+    // Fetch latest
+    process.stderr.write(`Fetching origin in ${clonePath}...\n`);
+    run("git", ["fetch", "origin"], clonePath);
+    // Create worktree
+    process.stderr.write(`Creating worktree at ${worktreePath}...\n`);
+    const defaultBranchRef = run("git", ["symbolic-ref", "refs/remotes/origin/HEAD", "--short"], clonePath);
+    const defaultBranch = defaultBranchRef.replace("origin/", "");
+    try {
+        run("git", ["worktree", "add", worktreePath, "-b", branch, `origin/${defaultBranch}`], clonePath);
+    }
+    catch (err) {
+        // Branch may already exist — check if a worktree with the right branch is now present
+        if (existsSync(worktreePath)) {
+            try {
+                run("git", ["rev-parse", "--git-dir"], worktreePath);
+                const currentBranch = run("git", ["rev-parse", "--abbrev-ref", "HEAD"], worktreePath);
+                if (currentBranch === branch) {
+                    // Worktree already exists on the correct branch — idempotent success
+                    return { worktreePath, branch, repo: opts.repo };
+                }
+            }
+            catch {
+                // fall through to rethrow original error
+            }
+        }
+        throw err;
+    }
+    // Install dependencies
+    const hasPnpmLock = existsSync(join(worktreePath, "pnpm-lock.yaml"));
+    const hasYarnLock = existsSync(join(worktreePath, "yarn.lock"));
+    const installCmd = hasPnpmLock ? "pnpm" : hasYarnLock ? "yarn" : "npm";
+    process.stderr.write(`Running ${installCmd} install in ${worktreePath}...\n`);
+    execFileSync(installCmd, ["install"], { cwd: worktreePath, stdio: "inherit" });
+    return { worktreePath, branch, repo: opts.repo };
+}

package/dist/execution/tool-schemas.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod/v4";
+export declare const FlowClaimSchema: z.ZodObject<{
+    worker_id: z.ZodOptional<z.ZodString>;
+    role: z.ZodString;
+    flow: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const FlowGetPromptSchema: z.ZodObject<{
+    entity_id: z.ZodString;
+}, z.core.$strip>;
+export declare const FlowReportSchema: z.ZodObject<{
+    entity_id: z.ZodString;
+    signal: z.ZodString;
+    artifacts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    worker_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const FlowFailSchema: z.ZodObject<{
+    entity_id: z.ZodString;
+    error: z.ZodString;
+}, z.core.$strip>;
+export declare const QueryEntitySchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export declare const QueryEntitiesSchema: z.ZodObject<{
+    flow: z.ZodString;
+    state: z.ZodString;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const QueryInvocationsSchema: z.ZodObject<{
+    entity_id: z.ZodString;
+}, z.core.$strip>;
+export declare const QueryFlowSchema: z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strip>;
+export declare const FlowSeedSchema: z.ZodObject<{
+    flow: z.ZodString;
+    refs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        adapter: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$loose>>>;
+}, z.core.$strip>;

package/dist/execution/tool-schemas.js

@@ -0,0 +1,44 @@
+import { z } from "zod/v4";
+export const FlowClaimSchema = z.object({
+    worker_id: z.string().min(1).optional(),
+    role: z.string().min(1),
+    flow: z.string().min(1).optional(),
+});
+export const FlowGetPromptSchema = z.object({
+    entity_id: z.string().min(1),
+});
+export const FlowReportSchema = z.object({
+    entity_id: z.string().min(1),
+    signal: z.string().min(1),
+    artifacts: z.record(z.string(), z.unknown()).optional(),
+    worker_id: z.string().min(1).optional(),
+});
+export const FlowFailSchema = z.object({
+    entity_id: z.string().min(1),
+    error: z.string().min(1),
+});
+export const QueryEntitySchema = z.object({
+    id: z.string().min(1),
+});
+export const QueryEntitiesSchema = z.object({
+    flow: z.string().min(1),
+    state: z.string().min(1),
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+});
+export const QueryInvocationsSchema = z.object({
+    entity_id: z.string().min(1),
+});
+export const QueryFlowSchema = z.object({
+    name: z.string().min(1),
+});
+export const FlowSeedSchema = z.object({
+    flow: z.string().min(1),
+    refs: z
+        .record(z.string(), z
+        .object({
+        adapter: z.string().min(1),
+        id: z.string().min(1),
+    })
+        .passthrough())
+        .optional(),
+});

package/dist/gates/blocking-graph.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Custom gate: checks whether all Linear blockers for an entity's issue
+ * have corresponding merged PRs on GitHub.
+ *
+ * Referenced by seed as: "gates/blocking-graph.ts:isUnblocked"
+ *
+ * NOTE: Function gates are not yet evaluated by the engine (gate-evaluator.ts
+ * throws for type "function"). This file exists as the implementation target
+ * for when function gate support lands.
+ *
+ * NOTE: This file is intentionally outside src/ — it is loaded dynamically at
+ * runtime, not compiled by the main build.
+ */
+import type { Entity } from "../src/repositories/interfaces.js";
+export interface BlockingGraphResult {
+    passed: boolean;
+    output: string;
+}
+/**
+ * Check if all blocking issues for the given entity have merged PRs.
+ *
+ * Expects entity.refs.linear.id to be the Linear issue ID.
+ * Uses LINEAR_API_KEY env var for authentication.
+ * Uses `gh` CLI to check PR merge status on GitHub.
+ */
+export declare function isUnblocked(entity: Entity): Promise<BlockingGraphResult>;

package/dist/gates/blocking-graph.js

@@ -0,0 +1,102 @@
+/**
+ * Custom gate: checks whether all Linear blockers for an entity's issue
+ * have corresponding merged PRs on GitHub.
+ *
+ * Referenced by seed as: "gates/blocking-graph.ts:isUnblocked"
+ *
+ * NOTE: Function gates are not yet evaluated by the engine (gate-evaluator.ts
+ * throws for type "function"). This file exists as the implementation target
+ * for when function gate support lands.
+ *
+ * NOTE: This file is intentionally outside src/ — it is loaded dynamically at
+ * runtime, not compiled by the main build.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { LinearClient } from "@linear/sdk";
+const execFileAsync = promisify(execFile);
+/**
+ * Check if all blocking issues for the given entity have merged PRs.
+ *
+ * Expects entity.refs.linear.id to be the Linear issue ID.
+ * Uses LINEAR_API_KEY env var for authentication.
+ * Uses `gh` CLI to check PR merge status on GitHub.
+ */
+export async function isUnblocked(entity) {
+    const linearApiKey = process.env.LINEAR_API_KEY;
+    if (!linearApiKey) {
+        return { passed: false, output: "LINEAR_API_KEY not set" };
+    }
+    const issueId = entity.refs?.linear?.id;
+    if (!issueId) {
+        return { passed: false, output: "Entity has no linear ref" };
+    }
+    const client = new LinearClient({ apiKey: linearApiKey });
+    let issue;
+    let inverseRelations;
+    try {
+        issue = await client.issue(issueId);
+        inverseRelations = await issue.inverseRelations();
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { passed: false, output: `Linear API error: ${message}` };
+    }
+    const blockers = inverseRelations.nodes.filter((r) => r.type === "blocks");
+    if (blockers.length === 0) {
+        return { passed: true, output: "No blockers" };
+    }
+    const unmerged = [];
+    for (const relation of blockers) {
+        try {
+            const blockerIssue = await relation.issue;
+            if (!blockerIssue)
+                continue;
+            const identifier = blockerIssue.identifier;
+            // Resolve the PR via Linear attachment — the attachment URL tells us which repo
+            const attachments = await blockerIssue.attachments();
+            const prAttachment = attachments.nodes.find((a) => {
+                if (!a.url)
+                    return false;
+                let hostname;
+                try {
+                    hostname = new URL(a.url).hostname;
+                }
+                catch {
+                    return false;
+                }
+                return hostname === "github.com" && a.url.includes("/pull/");
+            });
+            if (!prAttachment?.url) {
+                unmerged.push(`${identifier} (no PR found)`);
+                continue;
+            }
+            const match = prAttachment.url.match(/github\.com\/([^/]+\/[^/]+)\/pull\/(\d+)/);
+            if (!match) {
+                unmerged.push(`${identifier} (unrecognized PR URL)`);
+                continue;
+            }
+            const [, repo, prNum] = match;
+            try {
+                const { stdout } = await execFileAsync("gh", ["pr", "view", prNum, "--repo", repo, "--json", "state", "--jq", ".state"], { timeout: 10000 });
+                if (stdout.trim() !== "MERGED") {
+                    unmerged.push(identifier);
+                }
+            }
+            catch {
+                unmerged.push(`${identifier} (gh check failed)`);
+            }
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            unmerged.push(`(blocker check failed: ${errMsg})`);
+        }
+    }
+    if (unmerged.length > 0) {
+        return {
+            passed: false,
+            output: `Blocked by unmerged: ${unmerged.join(", ")}`,
+        };
+    }
+    return { passed: true, output: `All ${blockers.length} blockers merged` };
+}

package/dist/gates/test/bad-return-gate.d.ts

@@ -0,0 +1 @@
+export declare function check(): unknown;

package/dist/gates/test/bad-return-gate.js

@@ -0,0 +1,4 @@
+// Fixture: returns wrong shape (no `passed` boolean) to test return-shape validation
+export function check() {
+    return { status: "ok" }; // wrong shape — missing `passed`
+}

package/dist/gates/test/passing-gate.d.ts

@@ -0,0 +1,2 @@
+import type { GateEvalResult } from "../../src/engine/gate-evaluator.js";
+export declare function check(): GateEvalResult;

package/dist/gates/test/passing-gate.js

@@ -0,0 +1,3 @@
+export function check() {
+    return { passed: true, output: "all good", timedOut: false };
+}

package/dist/gates/test/slow-gate.d.ts

@@ -0,0 +1,2 @@
+import type { GateEvalResult } from "../../src/engine/gate-evaluator.js";
+export declare function check(): Promise<GateEvalResult>;

package/dist/gates/test/slow-gate.js

@@ -0,0 +1,5 @@
+export function check() {
+    return new Promise(() => {
+        // intentionally never resolves — for timeout testing
+    });
+}

package/dist/gates/test/throwing-gate.d.ts

@@ -0,0 +1 @@
+export declare function check(): never;

package/dist/gates/test/throwing-gate.js

@@ -0,0 +1,3 @@
+export function check() {
+    throw new Error("gate exploded");
+}

package/dist/logger.d.ts

@@ -0,0 +1,8 @@
+export interface Logger {
+    error(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    debug(msg: string, ...args: unknown[]): void;
+}
+export declare const consoleLogger: Logger;
+export declare const noopLogger: Logger;

package/dist/logger.js

@@ -0,0 +1,12 @@
+export const consoleLogger = {
+    error: (msg, ...args) => console.error(msg, ...args),
+    warn: (msg, ...args) => console.warn(msg, ...args),
+    info: (msg, ...args) => console.info(msg, ...args),
+    debug: (msg, ...args) => console.debug(msg, ...args),
+};
+export const noopLogger = {
+    error: () => { },
+    warn: () => { },
+    info: () => { },
+    debug: () => { },
+};

package/dist/main.d.ts

@@ -0,0 +1,14 @@
+import Database from "better-sqlite3";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import * as schema from "./repositories/drizzle/schema.js";
+export declare function createDatabase(dbPath?: string): {
+    db: ReturnType<typeof drizzle<typeof schema>>;
+    sqlite: Database.Database;
+};
+export declare function runMigrations(db: ReturnType<typeof drizzle>, migrationsFolder?: string): void;
+export declare function bootstrap(dbPath?: string): {
+    db: ReturnType<typeof drizzle>;
+    sqlite: Database.Database;
+};
+export * from "./api/wire-types.js";
+export * from "./engine/index.js";

package/dist/main.js

@@ -0,0 +1,28 @@
+import Database from "better-sqlite3";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import { migrate } from "drizzle-orm/better-sqlite3/migrator";
+import { DB_PATH } from "./config/db-path.js";
+import * as schema from "./repositories/drizzle/schema.js";
+export function createDatabase(dbPath = DB_PATH) {
+    const sqlite = new Database(dbPath);
+    sqlite.pragma("journal_mode = WAL");
+    sqlite.pragma("foreign_keys = ON");
+    const db = drizzle(sqlite, { schema });
+    return { db, sqlite };
+}
+export function runMigrations(db, migrationsFolder = "./drizzle") {
+    migrate(db, { migrationsFolder });
+}
+export function bootstrap(dbPath = DB_PATH) {
+    const { db, sqlite } = createDatabase(dbPath);
+    try {
+        runMigrations(db);
+    }
+    catch (err) {
+        sqlite.close();
+        throw err;
+    }
+    return { db, sqlite };
+}
+export * from "./api/wire-types.js";
+export * from "./engine/index.js";

package/dist/repositories/drizzle/entity.repo.d.ts

@@ -0,0 +1,27 @@
+import type { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
+import type { Artifacts, Entity, IEntityRepository, Refs } from "../interfaces.js";
+import type * as schema from "./schema.js";
+type Db = BetterSQLite3Database<typeof schema>;
+export declare class DrizzleEntityRepository implements IEntityRepository {
+    private db;
+    constructor(db: Db);
+    private toEntity;
+    create(flowId: string, initialState: string, refs?: Refs): Promise<Entity>;
+    get(id: string): Promise<Entity | null>;
+    findByFlowAndState(flowId: string, state: string, limit?: number): Promise<Entity[]>;
+    hasAnyInFlowAndState(flowId: string, stateNames: string[]): Promise<boolean>;
+    transition(id: string, toState: string, _trigger: string, artifacts?: Partial<Artifacts>, _invocationId?: string | null): Promise<Entity>;
+    updateArtifacts(id: string, artifacts: Partial<Artifacts>): Promise<void>;
+    claim(flowId: string, state: string, agentId: string): Promise<Entity | null>;
+    claimById(entityId: string, agentId: string): Promise<Entity | null>;
+    release(entityId: string, agentId: string): Promise<void>;
+    appendSpawnedChild(parentId: string, entry: {
+        childId: string;
+        childFlow: string;
+        spawnedAt: string;
+    }): Promise<void>;
+    reapExpired(ttlMs: number): Promise<string[]>;
+    setAffinity(entityId: string, workerId: string, role: string, expiresAt: Date): Promise<void>;
+    clearExpiredAffinity(): Promise<string[]>;
+}
+export {};