@barnum/barnum 0.2.3 → 0.3.0

package/barnum-config-schema.json

@@ -1,408 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "ConfigFile",
-  "description": "Top-level Barnum configuration file format.\n\nDefines a workflow as a directed graph of steps. Each step processes tasks and can spawn follow-up tasks on other steps.",
-  "type": "object",
-  "required": [
-    "steps"
-  ],
-  "properties": {
-    "$schema": {
-      "description": "Optional JSON Schema URL for editor validation (e.g., `\"./node_modules/@barnum/barnum/barnum-config-schema.json\"`). Ignored at runtime.",
-      "writeOnly": true,
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "entrypoint": {
-      "description": "Name of the step that starts the workflow. When set, the CLI accepts `--entrypoint-value` to provide the initial task value (defaults to `{}`). When omitted, `--initial-state` must provide explicit `[{\"kind\": \"StepName\", \"value\": ...}]` tasks.",
-      "default": null,
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "options": {
-      "description": "Global runtime options (timeout, retries, concurrency). Individual steps can override these via their own `options` field.",
-      "default": {
-        "max_concurrency": null,
-        "max_retries": 0,
-        "retry_on_invalid_response": true,
-        "retry_on_timeout": true,
-        "timeout": null
-      },
-      "allOf": [
-        {
-          "$ref": "#/definitions/Options"
-        }
-      ]
-    },
-    "steps": {
-      "description": "The steps that make up this workflow. Each step defines how to process a task and which steps it can spawn follow-up tasks on.",
-      "type": "array",
-      "items": {
-        "$ref": "#/definitions/StepFile"
-      }
-    }
-  },
-  "additionalProperties": false,
-  "definitions": {
-    "ActionFile": {
-      "description": "How a step processes tasks. Set `\"kind\": \"Pool\"` to send tasks to AI agents, or `\"kind\": \"Command\"` to run a local shell script.",
-      "oneOf": [
-        {
-          "description": "Send the task to the agent pool. An AI agent receives the task's `value` along with the `instructions` (markdown prompt) and produces a JSON array of follow-up tasks.",
-          "type": "object",
-          "required": [
-            "instructions",
-            "kind"
-          ],
-          "properties": {
-            "instructions": {
-              "description": "Markdown prompt shown to the agent processing this task. This is the core of what tells the agent what to do. Use `{\"inline\": \"...\"}` to write the markdown directly, or `{\"link\": \"path/to/file.md\"}` to reference an external file.",
-              "allOf": [
-                {
-                  "$ref": "#/definitions/MaybeLinked_for_String"
-                }
-              ]
-            },
-            "kind": {
-              "type": "string",
-              "enum": [
-                "Pool"
-              ]
-            }
-          }
-        },
-        {
-          "description": "Run a local shell command instead of sending to an agent. Use this for deterministic transformations, fan-out, or glue logic.",
-          "type": "object",
-          "required": [
-            "kind",
-            "script"
-          ],
-          "properties": {
-            "kind": {
-              "type": "string",
-              "enum": [
-                "Command"
-              ]
-            },
-            "script": {
-              "description": "Shell script to execute.\n\n**Input (stdin):** JSON object: `{\"kind\": \"<step name>\", \"value\": <payload>}`. Use `jq '.value'` to extract the payload, or `jq -r '.value.fieldName'` for a specific field.\n\n**Output (stdout):** JSON array of follow-up tasks to spawn: `[{\"kind\": \"NextStep\", \"value\": {...}}, ...]`. Each `kind` must be a step name listed in this step's `next` array. Return `[]` to spawn no follow-ups.",
-              "type": "string"
-            }
-          }
-        }
-      ]
-    },
-    "FinallyHook": {
-      "description": "Finally hook. Runs after a task and all its descendants complete.\n\nIn JSON: `{\"kind\": \"Command\", \"script\": \"./finally-hook.sh\"}`\n\n**stdin:** The task's original value payload as JSON. **stdout:** JSON array of follow-up tasks: `[{\"kind\": \"StepName\", \"value\": {...}}, ...]`. Return `[]` for no follow-ups.",
-      "oneOf": [
-        {
-          "description": "Run a shell command as the finally hook.",
-          "type": "object",
-          "required": [
-            "kind",
-            "script"
-          ],
-          "properties": {
-            "kind": {
-              "type": "string",
-              "enum": [
-                "Command"
-              ]
-            },
-            "script": {
-              "description": "Shell script to execute. Receives the task's original value as JSON on stdin, must write a JSON array of follow-up tasks on stdout.",
-              "type": "string"
-            }
-          }
-        }
-      ]
-    },
-    "MaybeLinked_for_String": {
-      "description": "Content that can be inline or linked to a file.\n\nIn config files: - `{\"inline\": <value>}` → content provided directly in the config - `{\"link\": \"path\"}` → content loaded from a file (path relative to the config file)",
-      "anyOf": [
-        {
-          "description": "Inline content.",
-          "type": "object",
-          "required": [
-            "inline"
-          ],
-          "properties": {
-            "inline": {
-              "description": "The content value, provided directly in the config file.",
-              "type": "string"
-            }
-          }
-        },
-        {
-          "description": "Link to a file whose contents will be loaded at runtime.",
-          "type": "object",
-          "required": [
-            "link"
-          ],
-          "properties": {
-            "link": {
-              "description": "Relative path to the file (resolved relative to the config file's directory).",
-              "type": "string"
-            }
-          }
-        }
-      ]
-    },
-    "Options": {
-      "description": "Global runtime options for task execution. All fields have sensible defaults.",
-      "type": "object",
-      "properties": {
-        "max_concurrency": {
-          "description": "Maximum concurrent tasks (None = unlimited).",
-          "default": null,
-          "type": [
-            "integer",
-            "null"
-          ],
-          "format": "uint",
-          "minimum": 0.0
-        },
-        "max_retries": {
-          "description": "Maximum retries per task (default: 0).",
-          "default": 0,
-          "type": "integer",
-          "format": "uint32",
-          "minimum": 0.0
-        },
-        "retry_on_invalid_response": {
-          "description": "Whether to retry when agent returns invalid response (default: true).",
-          "default": true,
-          "type": "boolean"
-        },
-        "retry_on_timeout": {
-          "description": "Whether to retry when agent times out (default: true).",
-          "default": true,
-          "type": "boolean"
-        },
-        "timeout": {
-          "description": "Timeout in seconds for each task (None = no timeout).",
-          "default": null,
-          "type": [
-            "integer",
-            "null"
-          ],
-          "format": "uint64",
-          "minimum": 0.0
-        }
-      },
-      "additionalProperties": false
-    },
-    "PostHook": {
-      "description": "Post-action hook. Inspects or modifies the action's outcome.\n\nIn JSON: `{\"kind\": \"Command\", \"script\": \"./post-hook.sh\"}`\n\n**stdin:** Tagged JSON describing the outcome (`\"kind\": \"Success\"`, `\"Timeout\"`, `\"Error\"`, or `\"PreHookError\"`). On success, includes an `input`, `output`, and `next` (follow-up tasks) field. **stdout:** Same tagged JSON, possibly modified (e.g., filtering `next`).",
-      "oneOf": [
-        {
-          "description": "Run a shell command as the post hook.",
-          "type": "object",
-          "required": [
-            "kind",
-            "script"
-          ],
-          "properties": {
-            "kind": {
-              "type": "string",
-              "enum": [
-                "Command"
-              ]
-            },
-            "script": {
-              "description": "Shell script to execute. Receives the action outcome as JSON on stdin, must write the (possibly modified) outcome as JSON on stdout.",
-              "type": "string"
-            }
-          }
-        }
-      ]
-    },
-    "PreHook": {
-      "description": "Pre-action hook. Transforms the task value before the action runs.\n\nIn JSON: `{\"kind\": \"Command\", \"script\": \"./pre-hook.sh\"}`\n\n**stdin:** Task value payload (e.g., `{\"path\": \"/src\"}`). **stdout:** Modified value payload (same shape).",
-      "oneOf": [
-        {
-          "description": "Run a shell command as the pre hook.",
-          "type": "object",
-          "required": [
-            "kind",
-            "script"
-          ],
-          "properties": {
-            "kind": {
-              "type": "string",
-              "enum": [
-                "Command"
-              ]
-            },
-            "script": {
-              "description": "Shell script to execute. Receives the task's value as JSON on stdin, must write the (possibly modified) value as JSON on stdout.",
-              "type": "string"
-            }
-          }
-        }
-      ]
-    },
-    "SchemaRef": {
-      "description": "A JSON Schema for validating task payloads. Can be provided inline or loaded from a file.\n\n- Inline: write the JSON Schema object directly, e.g. `{\"type\": \"object\", \"properties\": {...}}` - Linked: `{\"link\": \"path/to/schema.json\"}` to reference an external file (path relative to config file)",
-      "anyOf": [
-        {
-          "description": "Reference to an external JSON Schema file. The path is relative to the config file's directory.",
-          "type": "object",
-          "required": [
-            "link"
-          ],
-          "properties": {
-            "link": {
-              "description": "Relative path to the JSON Schema file (e.g., `\"schemas/task.json\"`).",
-              "type": "string"
-            }
-          }
-        },
-        {
-          "description": "Inline JSON Schema object (any valid JSON Schema)."
-        }
-      ]
-    },
-    "StepFile": {
-      "description": "A named step in the workflow. Steps are the nodes of the task graph.\n\nExecution order for each task: `pre` hook → `action` → `post` hook. The `finally` hook runs after the task **and all of its descendant tasks** complete.",
-      "type": "object",
-      "required": [
-        "action",
-        "name"
-      ],
-      "properties": {
-        "action": {
-          "description": "How this step processes tasks — either send to the agent pool (`Pool`) or run a local shell command (`Command`).",
-          "allOf": [
-            {
-              "$ref": "#/definitions/ActionFile"
-            }
-          ]
-        },
-        "finally": {
-          "description": "Shell script that runs after this task **and all tasks it spawned (recursively)** have completed.\n\n**stdin:** The task's original `value` payload as JSON (same as what the pre hook received — just the value, not the full task wrapper).\n\n**stdout:** A JSON array of follow-up tasks to spawn: `[{\"kind\": \"StepName\", \"value\": {...}}, ...]`. Each `kind` must be a valid step name. Return `[]` to spawn no follow-ups.\n\nUse this for cleanup, aggregation, or spawning a final summarization step after an entire subtree of work completes.",
-          "default": null,
-          "anyOf": [
-            {
-              "$ref": "#/definitions/FinallyHook"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "name": {
-          "description": "Unique name for this step (e.g., `\"Analyze\"`, `\"Implement\"`, `\"Review\"`). This is the string used as `kind` when creating tasks: `{\"kind\": \"ThisStepName\", \"value\": {...}}`.",
-          "type": "string"
-        },
-        "next": {
-          "description": "Step names this step is allowed to spawn follow-up tasks on. Each string must match the `name` of another step in this config. An empty array means this is a terminal step (no follow-ups).",
-          "default": [],
-          "type": "array",
-          "items": {
-            "type": "string"
-          }
-        },
-        "options": {
-          "description": "Per-step options that override the global `options`. Only the fields you set here take effect; everything else falls through to the global defaults.",
-          "default": {
-            "max_retries": null,
-            "retry_on_invalid_response": null,
-            "retry_on_timeout": null,
-            "timeout": null
-          },
-          "allOf": [
-            {
-              "$ref": "#/definitions/StepOptions"
-            }
-          ]
-        },
-        "post": {
-          "description": "Shell script that runs **after** the action completes (or fails).\n\n**stdin:** A tagged JSON object describing the outcome. The `kind` field indicates what happened:\n\n- `{\"kind\": \"Success\", \"input\": <value>, \"output\": <agent_output>, \"next\": [<tasks>]}` — Action succeeded. `next` contains the follow-up tasks to spawn. - `{\"kind\": \"Timeout\", \"input\": <value>}` — Action timed out. - `{\"kind\": \"Error\", \"input\": <value>, \"error\": \"<message>\"}` — Action failed. - `{\"kind\": \"PreHookError\", \"input\": <value>, \"error\": \"<message>\"}` — Pre hook failed.\n\n**stdout:** The same tagged JSON object, possibly modified. Typically you modify the `next` array in `Success` to filter, rewrite, or add follow-up tasks.",
-          "default": null,
-          "anyOf": [
-            {
-              "$ref": "#/definitions/PostHook"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "pre": {
-          "description": "Shell script that runs **before** the action.\n\n**stdin:** The task's `value` payload as JSON (e.g., `{\"path\": \"/src\"}`). This is just the value — not the full `{\"kind\": ..., \"value\": ...}` wrapper.\n\n**stdout:** The (possibly modified) value payload as JSON. Must be the same shape. The modified value is what the action receives.\n\nUse this to enrich or transform the task before the action sees it (e.g., adding timestamps, resolving paths, fetching metadata).",
-          "default": null,
-          "anyOf": [
-            {
-              "$ref": "#/definitions/PreHook"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "value_schema": {
-          "description": "JSON Schema that validates the `value` payload for tasks on this step. When set, tasks whose `value` doesn't conform are rejected. When omitted, any JSON value is accepted.",
-          "default": null,
-          "anyOf": [
-            {
-              "$ref": "#/definitions/SchemaRef"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        }
-      },
-      "additionalProperties": false
-    },
-    "StepOptions": {
-      "description": "Per-step option overrides. Only set the fields you want to override; omitted fields inherit from the global `options`.",
-      "type": "object",
-      "properties": {
-        "max_retries": {
-          "description": "Maximum retries for tasks on this step (overrides global `max_retries`).",
-          "default": null,
-          "type": [
-            "integer",
-            "null"
-          ],
-          "format": "uint32",
-          "minimum": 0.0
-        },
-        "retry_on_invalid_response": {
-          "description": "Whether to retry when an agent returns an invalid response on this step (overrides global `retry_on_invalid_response`).",
-          "default": null,
-          "type": [
-            "boolean",
-            "null"
-          ]
-        },
-        "retry_on_timeout": {
-          "description": "Whether to retry when an agent times out on this step (overrides global `retry_on_timeout`).",
-          "default": null,
-          "type": [
-            "boolean",
-            "null"
-          ]
-        },
-        "timeout": {
-          "description": "Timeout in seconds for tasks on this step (overrides global `timeout`).",
-          "default": null,
-          "type": [
-            "integer",
-            "null"
-          ],
-          "format": "uint64",
-          "minimum": 0.0
-        }
-      },
-      "additionalProperties": false
-    }
-  }
-}

package/cli.js

@@ -1,20 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-
-var bin = require('.');
-var spawn = require('child_process').spawn;
-var chmodSync = require('fs').chmodSync;
-
-var input = process.argv.slice(2);
-
-if (bin != null) {
-  try {
-    chmodSync(bin, 0o755);
-  } catch {}
-
-  spawn(bin, input, { stdio: 'inherit' }).on('exit', process.exit);
-} else {
-  throw new Error(
-    `Platform "${process.platform} (${process.arch})" not supported.`
-  );
-}

package/index.js

@@ -1,23 +0,0 @@
-'use strict';
-
-const path = require('path');
-
-let binary;
-
-if (process.platform === 'darwin' && process.arch === 'x64') {
-  binary = path.join(__dirname, 'artifacts', 'macos-x64', 'barnum');
-} else if (process.platform === 'darwin' && process.arch === 'arm64') {
-  binary = path.join(__dirname, 'artifacts', 'macos-arm64', 'barnum');
-} else if (process.platform === 'linux' && process.arch === 'x64') {
-  binary = path.join(__dirname, 'artifacts', 'linux-x64', 'barnum');
-} else if (process.platform === 'linux' && process.arch === 'arm64') {
-  binary = path.join(__dirname, 'artifacts', 'linux-arm64', 'barnum');
-} else if (process.platform === 'win32' && process.arch === 'x64') {
-  binary = path.join(__dirname, 'artifacts', 'win-x64', 'barnum.exe');
-} else {
-  throw new Error(
-    `Platform "${process.platform} (${process.arch})" not supported.`
-  );
-}
-
-module.exports = binary;