td-barrage 0.1.0

package/README.md

@@ -0,0 +1,133 @@
+# td-barrage
+
+A small TypeScript queue runner for OpenCode tasks. It loads a JSON task file, resolves dependencies, runs ready tasks through the OpenCode SDK, persists state after every transition, and resumes interrupted work on the next invocation.
+
+## Requirements
+
+- Node.js 20.11 or newer
+- npm
+- OpenCode available when running against a real server
+
+## Install
+
+In a target project:
+
+```sh
+npm install --save-dev td-barrage
+```
+
+Or run ad-hoc without installing:
+
+```sh
+npx td-barrage --tasks queue.json
+```
+
+Once installed, the `td-barrage` CLI is on the project `PATH`:
+
+```sh
+npx td-barrage --tasks queue.json
+```
+
+For local development on this package:
+
+```sh
+npm install
+npm run build
+```
+
+## Task File
+
+Task files use a top-level `tasks` array. A bare array is also accepted when loading.
+
+```json
+{
+  "tasks": [
+    {
+      "id": "build",
+      "prompt": "Create .queue/results/build.json with {\"status\":\"ok\"}.",
+      "success": { "strategy": "result_json", "path": ".queue/results/build.json" }
+    },
+    {
+      "id": "verify",
+      "prompt": "Verify the build result and create .queue/results/verify.json with {\"status\":\"ok\"}.",
+      "dependsOn": ["build"],
+      "timeoutMs": 600000,
+      "maxAttempts": 2,
+      "success": { "strategy": "result_json", "path": ".queue/results/verify.json" }
+    }
+  ]
+}
+```
+
+Supported task fields:
+
+- `id`: unique task id
+- `prompt`: prompt sent to OpenCode
+- `dependsOn`: dependency ids
+- `status`: `pending`, `running`, `done`, `failed`, or `blocked`
+- `attempts`: persisted attempt counter
+- `maxAttempts`: per-task retry limit
+- `timeoutMs`: per-task prompt timeout
+- `cwd`: per-task working directory
+- `resultPath`: optional metadata field
+- `success`: `default`, `file_exists`, or `result_json`
+- `recoveryNotes`, `error`, `startedAt`, `finishedAt`: runtime metadata
+
+## CLI
+
+```sh
+npm run dev -- --tasks queue.json
+npm run dev -- queue.json --max-attempts 3 --cwd /path/to/work --results-dir .queue/results
+npm run dev -- --tasks queue.json --dry-run
+npm run dev -- --tasks queue.json --json
+```
+
+Exit codes:
+
+- `0`: all reachable tasks completed
+- `1`: at least one task failed or became blocked
+- `2`: CLI usage or missing task-file error
+
+## Success Checks
+
+`default` succeeds unconditionally.
+
+`file_exists` succeeds when the configured path exists relative to the task cwd.
+
+`result_json` succeeds when the configured JSON file parses and contains `"status": "ok"`.
+
+## Recovery
+
+On startup, any task persisted as `running` is reset to `pending`, annotated in `recoveryNotes`, and retried. The `attempts` counter is preserved, so a task that crashed mid-run still counts that attempt.
+
+## Scripts
+
+```sh
+npm test
+npm run test:watch
+npm run typecheck
+npm run build
+npm run test:integration
+```
+
+Integration tests are excluded by default. Run them with:
+
+```sh
+RUN_INTEGRATION=1 npm run test:integration
+```
+
+Optional integration environment variables:
+
+- `OPENCODE_BIN`: OpenCode executable, default `opencode`
+- `OPENCODE_PORT`: server port, default `4096`
+
+## Architecture
+
+The orchestrator accepts its dependencies as arguments:
+
+- `client`: OpenCode client seam
+- `fs`: filesystem seam
+- `clock`: timer seam for timeout tests
+- `log`: human or JSON event logger
+
+This keeps most behavior covered by fast unit tests using a fake client and in-memory filesystem.

package/dist/client.d.ts

@@ -0,0 +1,9 @@
+import type { OpenCodeClient } from "./orchestrator.js";
+export interface ClientOptions {
+    baseUrl?: string;
+    hostname?: string;
+    port?: number;
+    timeout?: number;
+    config?: unknown;
+}
+export declare function createOpenCodeClient(options?: ClientOptions): Promise<OpenCodeClient>;

package/dist/client.js

@@ -0,0 +1,67 @@
+export async function createOpenCodeClient(options = {}) {
+    const importSdk = new Function("specifier", "return import(specifier)");
+    const sdk = (await importSdkWithFallback(importSdk));
+    if (typeof sdk.createOpencodeClient === "function") {
+        return wrapSdkClient(sdk.createOpencodeClient({ ...options, throwOnError: true }));
+    }
+    if (typeof sdk.createOpencode === "function") {
+        const created = (await sdk.createOpencode(options));
+        if (created.client)
+            return wrapSdkClient(created.client);
+    }
+    const Client = (sdk.OpenCode ?? sdk.Opencode ?? sdk.Client ?? sdk.default);
+    if (!Client) {
+        throw new Error("Unable to locate an OpenCode SDK client export.");
+    }
+    return new Client(options);
+}
+function wrapSdkClient(client) {
+    const sessionDirs = new Map();
+    const raw = client;
+    return {
+        session: {
+            create: async (input) => {
+                const result = unwrapData(await raw.session.create({ directory: input.cwd, title: "orchestrator task" }));
+                const id = result.id;
+                if (typeof id !== "string" || id.length === 0) {
+                    throw new Error("OpenCode SDK session.create did not return a session id.");
+                }
+                sessionDirs.set(id, input.cwd);
+                return { id };
+            },
+            prompt: async (sessionId, input) => {
+                const directory = sessionDirs.get(sessionId) ?? process.cwd();
+                const abort = async () => {
+                    await raw.session.abort?.({ sessionID: sessionId, directory });
+                };
+                if (input.signal?.aborted)
+                    await abort();
+                input.signal?.addEventListener("abort", abort, { once: true });
+                try {
+                    return await raw.session.prompt({
+                        sessionID: sessionId,
+                        directory,
+                        parts: [{ type: "text", text: input.prompt }],
+                    }, { signal: input.signal });
+                }
+                finally {
+                    input.signal?.removeEventListener("abort", abort);
+                }
+            },
+        },
+    };
+}
+function unwrapData(value) {
+    if (value && typeof value === "object" && "data" in value) {
+        return value.data;
+    }
+    return value;
+}
+async function importSdkWithFallback(importSdk) {
+    try {
+        return await importSdk("@opencode-ai/sdk/v2");
+    }
+    catch {
+        return importSdk("@opencode-ai/sdk");
+    }
+}

package/dist/deps.d.ts

@@ -0,0 +1,4 @@
+import type { Task } from "./schema.js";
+export type DependencyState = "ready" | "waiting" | "blocked";
+export declare function dependencyState(task: Task, tasks: Task[]): DependencyState;
+export declare function topologicalOrder(tasks: Task[]): Task[];

package/dist/deps.js

@@ -0,0 +1,41 @@
+export function dependencyState(task, tasks) {
+    const byId = new Map(tasks.map((candidate) => [candidate.id, candidate]));
+    for (const depId of task.dependsOn) {
+        const dep = byId.get(depId);
+        if (!dep)
+            return "blocked";
+        if (dep.status === "failed" || dep.status === "blocked")
+            return "blocked";
+        if (dep.status !== "done")
+            return "waiting";
+    }
+    return "ready";
+}
+export function topologicalOrder(tasks) {
+    const byId = new Map(tasks.map((task) => [task.id, task]));
+    const visiting = new Set();
+    const visited = new Set();
+    const ordered = [];
+    function visit(task, stack) {
+        if (visited.has(task.id))
+            return;
+        if (visiting.has(task.id)) {
+            const cycleStart = stack.indexOf(task.id);
+            const cycle = [...stack.slice(cycleStart), task.id].join(" -> ");
+            throw new Error(`Dependency cycle detected: ${cycle}`);
+        }
+        visiting.add(task.id);
+        for (const depId of task.dependsOn) {
+            const dep = byId.get(depId);
+            if (!dep)
+                throw new Error(`Task "${task.id}" depends on missing task "${depId}"`);
+            visit(dep, [...stack, task.id]);
+        }
+        visiting.delete(task.id);
+        visited.add(task.id);
+        ordered.push(task);
+    }
+    for (const task of tasks)
+        visit(task, []);
+    return ordered;
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import { type OpenCodeClient } from "./orchestrator.js";
+export interface MainDeps {
+    fs?: typeof fs;
+    client?: OpenCodeClient;
+    stdout?: Pick<NodeJS.WritableStream, "write">;
+    stderr?: Pick<NodeJS.WritableStream, "write">;
+}
+export declare function main(argv?: string[], deps?: MainDeps): Promise<number>;

package/dist/index.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import process from "node:process";
+import { parseArgs } from "node:util";
+import { createOpenCodeClient } from "./client.js";
+import { topologicalOrder } from "./deps.js";
+import { createLogger } from "./log.js";
+import { defaultResultsDir, runOrchestrator } from "./orchestrator.js";
+import { loadTasks } from "./tasks.js";
+export async function main(argv = process.argv.slice(2), deps = {}) {
+    const stdout = deps.stdout ?? process.stdout;
+    const stderr = deps.stderr ?? process.stderr;
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            tasks: { type: "string", short: "t" },
+            "max-attempts": { type: "string" },
+            cwd: { type: "string" },
+            "results-dir": { type: "string" },
+            json: { type: "boolean", default: false },
+            "dry-run": { type: "boolean", default: false },
+        },
+    });
+    const tasksPath = parsed.values.tasks ?? parsed.positionals[0];
+    if (!tasksPath) {
+        stderr.write("Missing tasks file. Pass --tasks <path> or a positional path.\n");
+        return 2;
+    }
+    const queueFs = deps.fs ?? fs;
+    const cwd = parsed.values.cwd ?? process.cwd();
+    const logger = createLogger(Boolean(parsed.values.json), stdout);
+    const maxAttempts = parsed.values["max-attempts"] ? Number(parsed.values["max-attempts"]) : undefined;
+    const resultsDir = parsed.values["results-dir"] ?? defaultResultsDir(cwd);
+    if (maxAttempts !== undefined && (!Number.isInteger(maxAttempts) || maxAttempts < 1)) {
+        stderr.write("--max-attempts must be a positive integer.\n");
+        return 2;
+    }
+    try {
+        if (parsed.values["dry-run"]) {
+            const taskFile = await loadTasks(tasksPath, queueFs);
+            const ordered = topologicalOrder(taskFile.tasks);
+            logger.event({ type: "dry_run", taskIds: ordered.map((task) => task.id) });
+            return 0;
+        }
+        const client = deps.client ?? (await createOpenCodeClient());
+        const summary = await runOrchestrator({
+            tasksPath,
+            client,
+            fs: queueFs,
+            log: logger,
+            cwd,
+            resultsDir,
+            maxAttempts,
+        });
+        return summary.failed > 0 || summary.blocked > 0 ? 1 : 0;
+    }
+    catch (error) {
+        const code = isMissingFile(error) ? 2 : 1;
+        stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return code;
+    }
+}
+function isMissingFile(error) {
+    return Boolean(error &&
+        typeof error === "object" &&
+        (("code" in error && error.code === "ENOENT") ||
+            (error instanceof Error && error.message.includes("ENOENT"))));
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    process.exitCode = await main();
+}

package/dist/log.d.ts

@@ -0,0 +1,29 @@
+export type LogEvent = {
+    type: "task_started";
+    taskId: string;
+    attempt: number;
+} | {
+    type: "task_done";
+    taskId: string;
+} | {
+    type: "task_failed";
+    taskId: string;
+    error: string;
+} | {
+    type: "task_blocked";
+    taskId: string;
+    reason: string;
+} | {
+    type: "summary";
+    summary: unknown;
+} | {
+    type: "dry_run";
+    taskIds: string[];
+} | {
+    type: "server";
+    message: string;
+};
+export interface Logger {
+    event(event: LogEvent): void;
+}
+export declare function createLogger(json: boolean, stream?: Pick<NodeJS.WritableStream, "write">): Logger;

package/dist/log.js

@@ -0,0 +1,26 @@
+export function createLogger(json, stream = process.stdout) {
+    return {
+        event(event) {
+            if (json) {
+                stream.write(`${JSON.stringify({ time: new Date().toISOString(), ...event })}\n`);
+                return;
+            }
+            stream.write(`${formatHuman(event)}\n`);
+        },
+    };
+}
+function formatHuman(event) {
+    if (event.type === "task_started")
+        return `starting ${event.taskId} (attempt ${event.attempt})`;
+    if (event.type === "task_done")
+        return `done ${event.taskId}`;
+    if (event.type === "task_failed")
+        return `failed ${event.taskId}: ${event.error}`;
+    if (event.type === "task_blocked")
+        return `blocked ${event.taskId}: ${event.reason}`;
+    if (event.type === "summary")
+        return `summary ${JSON.stringify(event.summary)}`;
+    if (event.type === "dry_run")
+        return event.taskIds.join("\n");
+    return event.message;
+}

package/dist/orchestrator.d.ts

@@ -0,0 +1,46 @@
+import { type SuccessFs } from "./success.js";
+import { type TaskFs } from "./tasks.js";
+import type { Logger } from "./log.js";
+export declare const DEFAULT_TIMEOUT_MS: number;
+export declare const DEFAULT_MAX_ATTEMPTS = 2;
+export interface OpenCodeClient {
+    session: {
+        create(input: {
+            cwd: string;
+        }): Promise<{
+            id: string;
+        } | string>;
+        prompt(sessionId: string, input: {
+            prompt: string;
+            signal?: AbortSignal;
+        }): Promise<unknown>;
+    };
+}
+export interface Clock {
+    now(): Date;
+    setTimeout(callback: () => void, ms: number): ReturnType<typeof setTimeout>;
+    clearTimeout(handle: ReturnType<typeof setTimeout>): void;
+}
+export interface OrchestratorFs extends TaskFs, SuccessFs {
+}
+export interface OrchestratorOptions {
+    tasksPath: string;
+    client: OpenCodeClient;
+    fs?: OrchestratorFs;
+    clock?: Clock;
+    log?: Logger;
+    cwd?: string;
+    resultsDir?: string;
+    maxAttempts?: number;
+    timeoutMs?: number;
+}
+export interface Summary {
+    total: number;
+    pending: number;
+    running: number;
+    done: number;
+    failed: number;
+    blocked: number;
+}
+export declare function runOrchestrator(options: OrchestratorOptions): Promise<Summary>;
+export declare function defaultResultsDir(cwd: string): string;

package/dist/orchestrator.js

@@ -0,0 +1,119 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { dependencyState } from "./deps.js";
+import { checkSuccess } from "./success.js";
+import { loadTasks, saveTasks } from "./tasks.js";
+export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+export const DEFAULT_MAX_ATTEMPTS = 2;
+const defaultClock = {
+    now: () => new Date(),
+    setTimeout: (callback, ms) => setTimeout(callback, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+export async function runOrchestrator(options) {
+    const queueFs = options.fs ?? fs;
+    const taskFile = await loadTasks(options.tasksPath, queueFs);
+    await saveTasks(options.tasksPath, taskFile, queueFs);
+    while (true) {
+        let progressed = false;
+        for (const task of taskFile.tasks) {
+            if (!isRunnable(task, options.maxAttempts))
+                continue;
+            const state = dependencyState(task, taskFile.tasks);
+            if (state === "waiting")
+                continue;
+            if (state === "blocked") {
+                task.status = "blocked";
+                task.error = "Dependency failed, blocked, or missing.";
+                task.finishedAt = nowIso(options.clock);
+                options.log?.event({ type: "task_blocked", taskId: task.id, reason: task.error });
+                await saveTasks(options.tasksPath, taskFile, queueFs);
+                progressed = true;
+                continue;
+            }
+            await runTask(task, taskFile.tasks, options, queueFs);
+            progressed = true;
+        }
+        if (!progressed)
+            break;
+    }
+    const summary = summarize(taskFile.tasks);
+    options.log?.event({ type: "summary", summary });
+    return summary;
+}
+async function runTask(task, tasks, options, queueFs) {
+    const clock = options.clock ?? defaultClock;
+    const cwd = task.cwd ?? options.cwd ?? process.cwd();
+    const timeoutMs = task.timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxAttempts = task.maxAttempts ?? options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    task.status = "running";
+    task.attempts += 1;
+    task.startedAt = clock.now().toISOString();
+    task.finishedAt = undefined;
+    task.error = undefined;
+    options.log?.event({ type: "task_started", taskId: task.id, attempt: task.attempts });
+    await saveTasks(options.tasksPath, { tasks }, queueFs);
+    try {
+        const session = await options.client.session.create({ cwd });
+        const sessionId = typeof session === "string" ? session : session.id;
+        const controller = new AbortController();
+        await withTimeout(options.client.session.prompt(sessionId, { prompt: task.prompt, signal: controller.signal }), timeoutMs, clock, controller);
+        const success = await checkSuccess(task.success, { fs: queueFs, cwd });
+        if (!success)
+            throw new Error("Success check failed.");
+        task.status = "done";
+        task.finishedAt = clock.now().toISOString();
+        options.log?.event({ type: "task_done", taskId: task.id });
+    }
+    catch (error) {
+        task.error = error instanceof Error ? error.message : String(error);
+        task.status = task.attempts >= maxAttempts ? "failed" : "pending";
+        task.finishedAt = clock.now().toISOString();
+        options.log?.event({ type: "task_failed", taskId: task.id, error: task.error });
+    }
+    await saveTasks(options.tasksPath, { tasks }, queueFs);
+}
+function isRunnable(task, globalMaxAttempts = DEFAULT_MAX_ATTEMPTS) {
+    if (task.status === "pending")
+        return true;
+    if (task.status !== "failed")
+        return false;
+    const maxAttempts = task.maxAttempts ?? globalMaxAttempts;
+    return task.attempts < maxAttempts;
+}
+async function withTimeout(promise, timeoutMs, clock, controller) {
+    let timeoutHandle;
+    const timeout = new Promise((_, reject) => {
+        timeoutHandle = clock.setTimeout(() => {
+            controller.abort();
+            reject(new Error(`Prompt timed out after ${timeoutMs}ms.`));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        if (timeoutHandle)
+            clock.clearTimeout(timeoutHandle);
+    }
+}
+function summarize(tasks) {
+    const summary = {
+        total: tasks.length,
+        pending: 0,
+        running: 0,
+        done: 0,
+        failed: 0,
+        blocked: 0,
+    };
+    for (const task of tasks) {
+        summary[task.status] += 1;
+    }
+    return summary;
+}
+function nowIso(clock = defaultClock) {
+    return clock.now().toISOString();
+}
+export function defaultResultsDir(cwd) {
+    return path.join(cwd, ".queue", "results");
+}

package/dist/schema.d.ts

@@ -0,0 +1,392 @@
+import { z } from "zod";
+export declare const taskStatuses: readonly ["pending", "running", "done", "failed", "blocked"];
+export declare const successCheckSchema: z.ZodDefault<z.ZodDiscriminatedUnion<"strategy", [z.ZodObject<{
+    strategy: z.ZodLiteral<"file_exists">;
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    strategy: "file_exists";
+    path: string;
+}, {
+    strategy: "file_exists";
+    path: string;
+}>, z.ZodObject<{
+    strategy: z.ZodLiteral<"result_json">;
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    strategy: "result_json";
+    path: string;
+}, {
+    strategy: "result_json";
+    path: string;
+}>, z.ZodObject<{
+    strategy: z.ZodLiteral<"default">;
+}, "strip", z.ZodTypeAny, {
+    strategy: "default";
+}, {
+    strategy: "default";
+}>]>>;
+export declare const taskSchema: z.ZodObject<{
+    id: z.ZodString;
+    prompt: z.ZodString;
+    dependsOn: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    status: z.ZodDefault<z.ZodEnum<["pending", "running", "done", "failed", "blocked"]>>;
+    attempts: z.ZodDefault<z.ZodNumber>;
+    maxAttempts: z.ZodOptional<z.ZodNumber>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    cwd: z.ZodOptional<z.ZodString>;
+    resultPath: z.ZodOptional<z.ZodString>;
+    success: z.ZodOptional<z.ZodDefault<z.ZodDiscriminatedUnion<"strategy", [z.ZodObject<{
+        strategy: z.ZodLiteral<"file_exists">;
+        path: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        strategy: "file_exists";
+        path: string;
+    }, {
+        strategy: "file_exists";
+        path: string;
+    }>, z.ZodObject<{
+        strategy: z.ZodLiteral<"result_json">;
+        path: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        strategy: "result_json";
+        path: string;
+    }, {
+        strategy: "result_json";
+        path: string;
+    }>, z.ZodObject<{
+        strategy: z.ZodLiteral<"default">;
+    }, "strip", z.ZodTypeAny, {
+        strategy: "default";
+    }, {
+        strategy: "default";
+    }>]>>>;
+    recoveryNotes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    error: z.ZodOptional<z.ZodString>;
+    startedAt: z.ZodOptional<z.ZodString>;
+    finishedAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "pending" | "running" | "done" | "failed" | "blocked";
+    id: string;
+    prompt: string;
+    dependsOn: string[];
+    attempts: number;
+    recoveryNotes: string[];
+    maxAttempts?: number | undefined;
+    timeoutMs?: number | undefined;
+    cwd?: string | undefined;
+    resultPath?: string | undefined;
+    success?: {
+        strategy: "file_exists";
+        path: string;
+    } | {
+        strategy: "result_json";
+        path: string;
+    } | {
+        strategy: "default";
+    } | undefined;
+    error?: string | undefined;
+    startedAt?: string | undefined;
+    finishedAt?: string | undefined;
+}, {
+    id: string;
+    prompt: string;
+    status?: "pending" | "running" | "done" | "failed" | "blocked" | undefined;
+    dependsOn?: string[] | undefined;
+    attempts?: number | undefined;
+    maxAttempts?: number | undefined;
+    timeoutMs?: number | undefined;
+    cwd?: string | undefined;
+    resultPath?: string | undefined;
+    success?: {
+        strategy: "file_exists";
+        path: string;
+    } | {
+        strategy: "result_json";
+        path: string;
+    } | {
+        strategy: "default";
+    } | undefined;
+    recoveryNotes?: string[] | undefined;
+    error?: string | undefined;
+    startedAt?: string | undefined;
+    finishedAt?: string | undefined;
+}>;
+export declare const taskFileSchema: z.ZodUnion<[z.ZodObject<{
+    tasks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        prompt: z.ZodString;
+        dependsOn: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        status: z.ZodDefault<z.ZodEnum<["pending", "running", "done", "failed", "blocked"]>>;
+        attempts: z.ZodDefault<z.ZodNumber>;
+        maxAttempts: z.ZodOptional<z.ZodNumber>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+        cwd: z.ZodOptional<z.ZodString>;
+        resultPath: z.ZodOptional<z.ZodString>;
+        success: z.ZodOptional<z.ZodDefault<z.ZodDiscriminatedUnion<"strategy", [z.ZodObject<{
+            strategy: z.ZodLiteral<"file_exists">;
+            path: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            strategy: "file_exists";
+            path: string;
+        }, {
+            strategy: "file_exists";
+            path: string;
+        }>, z.ZodObject<{
+            strategy: z.ZodLiteral<"result_json">;
+            path: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            strategy: "result_json";
+            path: string;
+        }, {
+            strategy: "result_json";
+            path: string;
+        }>, z.ZodObject<{
+            strategy: z.ZodLiteral<"default">;
+        }, "strip", z.ZodTypeAny, {
+            strategy: "default";
+        }, {
+            strategy: "default";
+        }>]>>>;
+        recoveryNotes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        error: z.ZodOptional<z.ZodString>;
+        startedAt: z.ZodOptional<z.ZodString>;
+        finishedAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status: "pending" | "running" | "done" | "failed" | "blocked";
+        id: string;
+        prompt: string;
+        dependsOn: string[];
+        attempts: number;
+        recoveryNotes: string[];
+        maxAttempts?: number | undefined;
+        timeoutMs?: number | undefined;
+        cwd?: string | undefined;
+        resultPath?: string | undefined;
+        success?: {
+            strategy: "file_exists";
+            path: string;
+        } | {
+            strategy: "result_json";
+            path: string;
+        } | {
+            strategy: "default";
+        } | undefined;
+        error?: string | undefined;
+        startedAt?: string | undefined;
+        finishedAt?: string | undefined;
+    }, {
+        id: string;
+        prompt: string;
+        status?: "pending" | "running" | "done" | "failed" | "blocked" | undefined;
+        dependsOn?: string[] | undefined;
+        attempts?: number | undefined;
+        maxAttempts?: number | undefined;
+        timeoutMs?: number | undefined;
+        cwd?: string | undefined;
+        resultPath?: string | undefined;
+        success?: {
+            strategy: "file_exists";
+            path: string;
+        } | {
+            strategy: "result_json";
+            path: string;
+        } | {
+            strategy: "default";
+        } | undefined;
+        recoveryNotes?: string[] | undefined;
+        error?: string | undefined;
+        startedAt?: string | undefined;
+        finishedAt?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    tasks: {
+        status: "pending" | "running" | "done" | "failed" | "blocked";
+        id: string;
+        prompt: string;
+        dependsOn: string[];
+        attempts: number;
+        recoveryNotes: string[];
+        maxAttempts?: number | undefined;
+        timeoutMs?: number | undefined;
+        cwd?: string | undefined;
+        resultPath?: string | undefined;
+        success?: {
+            strategy: "file_exists";
+            path: string;
+        } | {
+            strategy: "result_json";
+            path: string;
+        } | {
+            strategy: "default";
+        } | undefined;
+        error?: string | undefined;
+        startedAt?: string | undefined;
+        finishedAt?: string | undefined;
+    }[];
+}, {
+    tasks: {
+        id: string;
+        prompt: string;
+        status?: "pending" | "running" | "done" | "failed" | "blocked" | undefined;
+        dependsOn?: string[] | undefined;
+        attempts?: number | undefined;
+        maxAttempts?: number | undefined;
+        timeoutMs?: number | undefined;
+        cwd?: string | undefined;
+        resultPath?: string | undefined;
+        success?: {
+            strategy: "file_exists";
+            path: string;
+        } | {
+            strategy: "result_json";
+            path: string;
+        } | {
+            strategy: "default";
+        } | undefined;
+        recoveryNotes?: string[] | undefined;
+        error?: string | undefined;
+        startedAt?: string | undefined;
+        finishedAt?: string | undefined;
+    }[];
+}>, z.ZodEffects<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    prompt: z.ZodString;
+    dependsOn: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    status: z.ZodDefault<z.ZodEnum<["pending", "running", "done", "failed", "blocked"]>>;
+    attempts: z.ZodDefault<z.ZodNumber>;
+    maxAttempts: z.ZodOptional<z.ZodNumber>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    cwd: z.ZodOptional<z.ZodString>;
+    resultPath: z.ZodOptional<z.ZodString>;
+    success: z.ZodOptional<z.ZodDefault<z.ZodDiscriminatedUnion<"strategy", [z.ZodObject<{
+        strategy: z.ZodLiteral<"file_exists">;
+        path: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        strategy: "file_exists";
+        path: string;
+    }, {
+        strategy: "file_exists";
+        path: string;
+    }>, z.ZodObject<{
+        strategy: z.ZodLiteral<"result_json">;
+        path: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        strategy: "result_json";
+        path: string;
+    }, {
+        strategy: "result_json";
+        path: string;
+    }>, z.ZodObject<{
+        strategy: z.ZodLiteral<"default">;
+    }, "strip", z.ZodTypeAny, {
+        strategy: "default";
+    }, {
+        strategy: "default";
+    }>]>>>;
+    recoveryNotes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    error: z.ZodOptional<z.ZodString>;
+    startedAt: z.ZodOptional<z.ZodString>;
+    finishedAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "pending" | "running" | "done" | "failed" | "blocked";
+    id: string;
+    prompt: string;
+    dependsOn: string[];
+    attempts: number;
+    recoveryNotes: string[];
+    maxAttempts?: number | undefined;
+    timeoutMs?: number | undefined;
+    cwd?: string | undefined;
+    resultPath?: string | undefined;
+    success?: {
+        strategy: "file_exists";
+        path: string;
+    } | {
+        strategy: "result_json";
+        path: string;
+    } | {
+        strategy: "default";
+    } | undefined;
+    error?: string | undefined;
+    startedAt?: string | undefined;
+    finishedAt?: string | undefined;
+}, {
+    id: string;
+    prompt: string;
+    status?: "pending" | "running" | "done" | "failed" | "blocked" | undefined;
+    dependsOn?: string[] | undefined;
+    attempts?: number | undefined;
+    maxAttempts?: number | undefined;
+    timeoutMs?: number | undefined;
+    cwd?: string | undefined;
+    resultPath?: string | undefined;
+    success?: {
+        strategy: "file_exists";
+        path: string;
+    } | {
+        strategy: "result_json";
+        path: string;
+    } | {
+        strategy: "default";
+    } | undefined;
+    recoveryNotes?: string[] | undefined;
+    error?: string | undefined;
+    startedAt?: string | undefined;
+    finishedAt?: string | undefined;
+}>, "many">, {
+    tasks: {
+        status: "pending" | "running" | "done" | "failed" | "blocked";
+        id: string;
+        prompt: string;
+        dependsOn: string[];
+        attempts: number;
+        recoveryNotes: string[];
+        maxAttempts?: number | undefined;
+        timeoutMs?: number | undefined;
+        cwd?: string | undefined;
+        resultPath?: string | undefined;
+        success?: {
+            strategy: "file_exists";
+            path: string;
+        } | {
+            strategy: "result_json";
+            path: string;
+        } | {
+            strategy: "default";
+        } | undefined;
+        error?: string | undefined;
+        startedAt?: string | undefined;
+        finishedAt?: string | undefined;
+    }[];
+}, {
+    id: string;
+    prompt: string;
+    status?: "pending" | "running" | "done" | "failed" | "blocked" | undefined;
+    dependsOn?: string[] | undefined;
+    attempts?: number | undefined;
+    maxAttempts?: number | undefined;
+    timeoutMs?: number | undefined;
+    cwd?: string | undefined;
+    resultPath?: string | undefined;
+    success?: {
+        strategy: "file_exists";
+        path: string;
+    } | {
+        strategy: "result_json";
+        path: string;
+    } | {
+        strategy: "default";
+    } | undefined;
+    recoveryNotes?: string[] | undefined;
+    error?: string | undefined;
+    startedAt?: string | undefined;
+    finishedAt?: string | undefined;
+}[]>]>;
+export type TaskStatus = (typeof taskStatuses)[number];
+export type SuccessCheck = z.input<typeof successCheckSchema>;
+export type Task = z.infer<typeof taskSchema>;
+export type TaskFile = {
+    tasks: Task[];
+};
+export declare function parseTaskFile(value: unknown): TaskFile;
+export declare function validateTaskGraph(tasks: Task[]): void;

package/dist/schema.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+export const taskStatuses = ["pending", "running", "done", "failed", "blocked"];
+export const successCheckSchema = z
+    .discriminatedUnion("strategy", [
+    z.object({
+        strategy: z.literal("file_exists"),
+        path: z.string().min(1),
+    }),
+    z.object({
+        strategy: z.literal("result_json"),
+        path: z.string().min(1),
+    }),
+    z.object({
+        strategy: z.literal("default"),
+    }),
+])
+    .default({ strategy: "default" });
+export const taskSchema = z.object({
+    id: z.string().min(1),
+    prompt: z.string().min(1),
+    dependsOn: z.array(z.string().min(1)).default([]),
+    status: z.enum(taskStatuses).default("pending"),
+    attempts: z.number().int().min(0).default(0),
+    maxAttempts: z.number().int().min(1).optional(),
+    timeoutMs: z.number().int().positive().optional(),
+    cwd: z.string().min(1).optional(),
+    resultPath: z.string().min(1).optional(),
+    success: successCheckSchema.optional(),
+    recoveryNotes: z.array(z.string()).default([]),
+    error: z.string().optional(),
+    startedAt: z.string().datetime().optional(),
+    finishedAt: z.string().datetime().optional(),
+});
+export const taskFileSchema = z.union([
+    z.object({
+        tasks: z.array(taskSchema),
+    }),
+    z.array(taskSchema).transform((tasks) => ({ tasks })),
+]);
+export function parseTaskFile(value) {
+    const parsed = taskFileSchema.parse(value);
+    validateTaskGraph(parsed.tasks);
+    return parsed;
+}
+export function validateTaskGraph(tasks) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const task of tasks) {
+        if (seen.has(task.id))
+            duplicates.add(task.id);
+        seen.add(task.id);
+    }
+    if (duplicates.size > 0) {
+        throw new Error(`Duplicate task id: ${Array.from(duplicates).join(", ")}`);
+    }
+    for (const task of tasks) {
+        if (task.dependsOn.includes(task.id)) {
+            throw new Error(`Task "${task.id}" cannot depend on itself`);
+        }
+        for (const dep of task.dependsOn) {
+            if (!seen.has(dep)) {
+                throw new Error(`Task "${task.id}" depends on missing task "${dep}"`);
+            }
+        }
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,18 @@
+import { spawn, type ChildProcess } from "node:child_process";
+export interface StartServerOptions {
+    command?: string;
+    args?: string[];
+    port: number;
+    host?: string;
+    timeoutMs?: number;
+    pollMs?: number;
+    spawnProcess?: typeof spawn;
+    portOpen?: (host: string, port: number) => Promise<boolean>;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+export interface StopServerOptions {
+    graceMs?: number;
+}
+export declare function startServer(options: StartServerOptions): Promise<ChildProcess>;
+export declare function stopServer(child: Pick<ChildProcess, "kill" | "killed" | "exitCode" | "once">, options?: StopServerOptions): Promise<void>;

package/dist/server.js

@@ -0,0 +1,60 @@
+import { spawn } from "node:child_process";
+import net from "node:net";
+export async function startServer(options) {
+    const command = options.command ?? "opencode";
+    const args = options.args ?? ["serve", "--port", String(options.port)];
+    const host = options.host ?? "127.0.0.1";
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const pollMs = options.pollMs ?? 100;
+    const portOpen = options.portOpen ?? isPortOpen;
+    const wait = options.sleep ?? sleep;
+    const now = options.now ?? Date.now;
+    const child = (options.spawnProcess ?? spawn)(command, args, {
+        stdio: "ignore",
+        detached: false,
+    });
+    const startedAt = now();
+    while (now() - startedAt < timeoutMs) {
+        if (await portOpen(host, options.port))
+            return child;
+        if (child.exitCode !== null)
+            throw new Error(`Server exited before port ${options.port} opened.`);
+        await wait(pollMs);
+    }
+    child.kill("SIGTERM");
+    throw new Error(`Timed out waiting for ${host}:${options.port}.`);
+}
+export async function stopServer(child, options = {}) {
+    const graceMs = options.graceMs ?? 5_000;
+    if (child.exitCode !== null)
+        return;
+    child.kill("SIGTERM");
+    await new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+            if (child.exitCode === null)
+                child.kill("SIGKILL");
+            resolve();
+        }, graceMs);
+        child.once("exit", () => {
+            clearTimeout(timeout);
+            resolve();
+        });
+    });
+}
+async function isPortOpen(host, port) {
+    return new Promise((resolve) => {
+        const socket = net.createConnection({ host, port });
+        socket.once("connect", () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.once("error", () => resolve(false));
+        socket.setTimeout(250, () => {
+            socket.destroy();
+            resolve(false);
+        });
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/success.d.ts

@@ -0,0 +1,10 @@
+import type { SuccessCheck } from "./schema.js";
+export interface SuccessFs {
+    readFile(path: string, encoding: "utf8"): Promise<string>;
+    access(path: string): Promise<void>;
+}
+export interface SuccessOptions {
+    fs: SuccessFs;
+    cwd: string;
+}
+export declare function checkSuccess(check: SuccessCheck | undefined, options: SuccessOptions): Promise<boolean>;

package/dist/success.js

@@ -0,0 +1,28 @@
+import path from "node:path";
+export async function checkSuccess(check, options) {
+    if (!check || check.strategy === "default")
+        return true;
+    if (check.strategy === "file_exists") {
+        try {
+            await options.fs.access(resolvePath(options.cwd, check.path));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    if (check.strategy === "result_json") {
+        try {
+            const raw = await options.fs.readFile(resolvePath(options.cwd, check.path), "utf8");
+            const parsed = JSON.parse(raw);
+            return parsed.status === "ok";
+        }
+        catch {
+            return false;
+        }
+    }
+    throw new Error(`Unknown success strategy: ${check.strategy}`);
+}
+function resolvePath(cwd, candidate) {
+    return path.isAbsolute(candidate) ? candidate : path.join(cwd, candidate);
+}

package/dist/tasks.d.ts

@@ -0,0 +1,11 @@
+import { type TaskFile } from "./schema.js";
+export interface TaskFs {
+    readFile(path: string, encoding: "utf8"): Promise<string>;
+    writeFile(path: string, data: string, encoding: "utf8"): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    mkdir(path: string, options: {
+        recursive: true;
+    }): Promise<unknown>;
+}
+export declare function loadTasks(filePath: string, fs: TaskFs): Promise<TaskFile>;
+export declare function saveTasks(filePath: string, taskFile: TaskFile, fs: TaskFs): Promise<void>;

package/dist/tasks.js

@@ -0,0 +1,30 @@
+import path from "node:path";
+import { parseTaskFile } from "./schema.js";
+export async function loadTasks(filePath, fs) {
+    const raw = await fs.readFile(filePath, "utf8");
+    const parsed = parseTaskFile(JSON.parse(raw));
+    let recovered = false;
+    const tasks = parsed.tasks.map((task) => {
+        if (task.status !== "running")
+            return task;
+        recovered = true;
+        return {
+            ...task,
+            status: "pending",
+            recoveryNotes: [
+                ...task.recoveryNotes,
+                `Recovered running task at ${new Date().toISOString()}; reset to pending.`,
+            ],
+            startedAt: undefined,
+        };
+    });
+    return recovered ? { tasks } : parsed;
+}
+export async function saveTasks(filePath, taskFile, fs) {
+    parseTaskFile(taskFile);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    const payload = `${JSON.stringify(taskFile, null, 2)}\n`;
+    await fs.writeFile(tempPath, payload, "utf8");
+    await fs.rename(tempPath, filePath);
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "td-barrage",
+  "version": "0.1.0",
+  "description": "TypeScript queue runner that loads a JSON task file, resolves dependencies, runs tasks through the OpenCode SDK, and resumes interrupted work.",
+  "type": "module",
+  "engines": {
+    "node": ">=20.11"
+  },
+  "bin": {
+    "td-barrage": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/josh-theory/td-barrage.git"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "RUN_INTEGRATION=1 vitest run test/integration.test.ts",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "@opencode-ai/sdk": "^1.15.10",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0"
+  }
+}