@tingrudeng/worker-review-orchestrator-cli 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -25,11 +25,13 @@ This package is meant to pair with the `worker-review-orchestrator` skill, but i
 - `dispatch`
   - POST a dispatch payload to `/api/dispatches`
   - Supports `--target-worker-id` to pin all tasks in the payload to one worker
+  - Supports `--require-existing-worker` to verify the target worker or worker pool is already online in `/api/dashboard/snapshot` before posting
 - `dispatch-task`
   - Build and POST a single-task dispatch payload from CLI flags
   - Preferred when the control layer wants to send one focused task without hand-writing `dispatch.json`
   - Supports `--worker-prompt` and `--context-markdown` for inline string inputs
-  - Does NOT support file paths for prompt or context; use `--worker-prompt` or `--context-markdown` with literal strings
+  - Supports `--worker-prompt-file` and `--context-markdown-file` for file-backed prompt/context inputs
+  - Supports `--require-existing-worker` to reject dispatch when no matching online worker exists
 - `watch`
   - Poll `/api/dashboard/snapshot` until a task reaches `review`, `failed`, `merged`, or `blocked`
 - `decide`
@@ -52,6 +54,7 @@ This package is meant to pair with the `worker-review-orchestrator` skill, but i
 ```bash
 forgeflow-review-orchestrator dispatch --dispatcher-url http://127.0.0.1:8787 --input dispatch.json
 forgeflow-review-orchestrator dispatch --dispatcher-url http://127.0.0.1:8787 --input dispatch.json --target-worker-id trae-remote-forgeflow
+forgeflow-review-orchestrator dispatch --dispatcher-url http://127.0.0.1:8787 --input dispatch.json --target-worker-id trae-local-forgeflow --require-existing-worker
 forgeflow-review-orchestrator dispatch-task --dispatcher-url http://127.0.0.1:8787 --repo TingRuDeng/ForgeFlow --default-branch main --task-id task-1 --title "Update docs" --pool trae --branch-name ai/trae/task-1 --allowed-paths docs/**,README.md --acceptance "pnpm typecheck,git diff --check" --target-worker-id trae-remote-forgeflow
 forgeflow-review-orchestrator dispatch-task --dispatcher-url http://127.0.0.1:8787 --repo TingRuDeng/ForgeFlow --default-branch main --task-id task-1 --title "Refactor auth" --pool codex --branch-name ai/codex/auth --allowed-paths "packages/auth/**" --acceptance "pnpm typecheck" --worker-prompt "You are a codex worker. Refactor the auth module." --context-markdown "# Context\n\nFocus on packages/auth only."
 forgeflow-review-orchestrator watch --dispatcher-url http://127.0.0.1:8787 --task-id dispatch-1:task-1
@@ -63,6 +66,8 @@ forgeflow-review-orchestrator inspect --dispatcher-url http://127.0.0.1:8787 --t
 
 When `--target-worker-id` is set, the CLI injects that worker id into every task and assignment package before posting the dispatch. This keeps the existing `dispatch.json` shape but gives the control layer an explicit way to target `trae-local-forgeflow` or `trae-remote-forgeflow`.
 
+When `--require-existing-worker` is set, the CLI fetches `/api/dashboard/snapshot` before dispatch and hard-fails if the pinned target worker is offline or if no online worker exists for the required task pool. Use this when the control layer must reuse an already running dispatcher + worker runtime instead of implicitly relying on a later bootstrap step.
+
 Use `dispatch-task` for the common case of one worker task with one branch, one `allowedPaths` list, and one `acceptance` list. Keep `dispatch --input` for more complex multi-task or prebuilt payloads.
 
 For control-layer review flow, prefer this CLI over calling lower-level review-decision scripts directly. Keep the scripts as compatibility and implementation detail, but use `forgeflow-review-orchestrator decide` as the default operator entrypoint.

package/dist/cli.js

@@ -51,7 +51,9 @@ function printHelp() {
 Usage:
   forgeflow-review-orchestrator dispatch --dispatcher-url http://127.0.0.1:8787 --input dispatch.json
   forgeflow-review-orchestrator dispatch --dispatcher-url http://127.0.0.1:8787 --input dispatch.json --target-worker-id trae-remote-forgeflow
+  forgeflow-review-orchestrator dispatch --dispatcher-url http://127.0.0.1:8787 --input dispatch.json --require-existing-worker
   forgeflow-review-orchestrator dispatch-task --dispatcher-url http://127.0.0.1:8787 --repo TingRuDeng/ForgeFlow --default-branch main --task-id task-1 --title "Update docs" --pool trae --branch-name ai/trae/task-1 --allowed-paths docs/**,README.md --acceptance "pnpm typecheck,git diff --check"
+  forgeflow-review-orchestrator dispatch-task --dispatcher-url http://127.0.0.1:8787 --repo TingRuDeng/ForgeFlow --default-branch main --task-id task-1 --title "Update docs" --pool trae --branch-name ai/trae/task-1 --target-worker-id trae-local-forgeflow --require-existing-worker
   forgeflow-review-orchestrator dispatch-task --dispatcher-url http://127.0.0.1:8787 --repo TingRuDeng/ForgeFlow --default-branch main --task-id task-1 --title "Update docs" --pool trae --branch-name ai/trae/task-1 --worker-prompt-file prompts/worker.md --context-markdown-file context/task.md
   forgeflow-review-orchestrator watch --dispatcher-url http://127.0.0.1:8787 --task-id dispatch-1:task-1
   forgeflow-review-orchestrator watch --dispatcher-url http://127.0.0.1:8787 --task-id dispatch-1:task-1 --summary
@@ -89,6 +91,7 @@ export async function runCli(argv, partialDeps = {}) {
         const result = await deps.runDispatch({
             dispatcherUrl,
             input,
+            requireExistingWorker: options.requireExistingWorker === true,
             targetWorkerId: typeof options.targetWorkerId === "string" ? options.targetWorkerId : undefined,
             requestTimeoutMs: typeof options.requestTimeoutMs === "number" ? options.requestTimeoutMs : undefined,
         });
@@ -136,6 +139,7 @@ export async function runCli(argv, partialDeps = {}) {
             dispatcherUrl,
             input: "-",
             payload,
+            requireExistingWorker: options.requireExistingWorker === true,
             requestTimeoutMs: typeof options.requestTimeoutMs === "number" ? options.requestTimeoutMs : undefined,
         });
         deps.log(JSON.stringify(result, null, 2));

package/dist/dispatch.d.ts

@@ -4,6 +4,7 @@ export interface DispatchOptions {
     input: string;
     payload?: DispatchInput;
     targetWorkerId?: string;
+    requireExistingWorker?: boolean;
     requestTimeoutMs?: number;
     fetchImpl?: typeof globalThis.fetch;
     readStdin?: () => Promise<string>;

package/dist/dispatch.js

@@ -90,10 +90,67 @@ export function applyDispatchTargetWorker(payload, targetWorkerId) {
         packages: applyTargetWorkerToRecords(payload.packages, normalizedTargetWorkerId),
     };
 }
+function normalizeString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
+function isOnlineWorkerStatus(status) {
+    return status === "idle" || status === "busy";
+}
+function formatWorkerInventory(workers) {
+    if (workers.length === 0) {
+        return "none";
+    }
+    return workers.map((worker) => {
+        const id = normalizeString(worker.id) || "<unknown>";
+        const pool = normalizeString(worker.pool) || "<unknown-pool>";
+        const status = normalizeString(worker.status) || "<unknown-status>";
+        return `${id}(${pool},${status})`;
+    }).join(", ");
+}
+async function ensureExistingWorkersAvailable(payload, options) {
+    const client = createJsonHttpClient(options.dispatcherUrl, {
+        fetchImpl: options.fetchImpl,
+        requestTimeoutMs: options.requestTimeoutMs,
+    });
+    const snapshot = await client.request("/api/dashboard/snapshot");
+    const workers = Array.isArray(snapshot.workers) ? snapshot.workers : [];
+    const onlineWorkers = workers.filter((worker) => isOnlineWorkerStatus(worker.status));
+    if (onlineWorkers.length === 0) {
+        throw new Error(`require-existing-worker check failed: dispatcher snapshot has no online workers. Snapshot workers: ${formatWorkerInventory(workers)}`);
+    }
+    const tasks = Array.isArray(payload.tasks) ? payload.tasks : [];
+    const targetWorkerIds = [...new Set(tasks.map((task) => normalizeString(task.targetWorkerId) || normalizeString(task.target_worker_id)).filter((value) => Boolean(value)))];
+    if (targetWorkerIds.length > 0) {
+        for (const targetWorkerId of targetWorkerIds) {
+            const matchedWorker = onlineWorkers.find((worker) => normalizeString(worker.id) === targetWorkerId);
+            if (!matchedWorker) {
+                throw new Error(`require-existing-worker check failed: target worker "${targetWorkerId}" is not online. Online workers: ${formatWorkerInventory(onlineWorkers)}`);
+            }
+        }
+        return;
+    }
+    const requiredPools = [...new Set(tasks.map((task) => normalizeString(task.pool)).filter((value) => Boolean(value)))];
+    if (requiredPools.length === 0) {
+        throw new Error("require-existing-worker check failed: every dispatch task must declare a pool or targetWorkerId");
+    }
+    for (const pool of requiredPools) {
+        const hasOnlineWorker = onlineWorkers.some((worker) => normalizeString(worker.pool) === pool);
+        if (!hasOnlineWorker) {
+            throw new Error(`require-existing-worker check failed: no online worker available for pool "${pool}". Online workers: ${formatWorkerInventory(onlineWorkers)}`);
+        }
+    }
+}
 export async function runDispatch(options) {
     const payload = options.payload
         ? applyDispatchTargetWorker(options.payload, options.targetWorkerId)
         : applyDispatchTargetWorker(await loadDispatchInput(options.input, options.readStdin), options.targetWorkerId);
+    if (options.requireExistingWorker) {
+        await ensureExistingWorkersAvailable(payload, options);
+    }
     const client = createJsonHttpClient(options.dispatcherUrl, {
         fetchImpl: options.fetchImpl,
         requestTimeoutMs: options.requestTimeoutMs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tingrudeng/worker-review-orchestrator-cli",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.3",
   "private": false,
   "license": "Apache-2.0",
   "repository": {
@@ -17,7 +17,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "forgeflow-review-orchestrator": "./dist/cli.js"
+    "forgeflow-review-orchestrator": "dist/cli.js"
   },
   "exports": {
     ".": {