patchwork-os 0.2.0-beta.0 → 0.2.0-beta.10

package/dist/recipes/dependencyGraph.js

@@ -61,6 +61,7 @@ export function buildDependencyGraph(steps) {
     }
     const topologicalOrder = [];
     while (queue.length > 0) {
+        // biome-ignore lint/style/noNonNullAssertion: queue.length > 0 guard ensures shift() is defined
         const stepId = queue.shift();
         topologicalOrder.push(stepId);
         const dependents = adjacency.get(stepId) ?? [];
@@ -163,13 +164,15 @@ export async function executeWithDependencies(graph, executeStep, options) {
             resolvers.delete(stepId);
         }
     }
-    // Execute with concurrency limit
+    // Execute with concurrency limit (clamp to 1 so maxConcurrency:0 or negative never busy-loops)
+    const concurrency = Math.max(1, options.maxConcurrency);
     const executing = [];
     const queue = [...graph.topologicalOrder];
     async function processQueue() {
         while (queue.length > 0 || executing.length > 0) {
             // Start new steps if under concurrency limit
-            while (executing.length < options.maxConcurrency && queue.length > 0) {
+            while (executing.length < concurrency && queue.length > 0) {
+                // biome-ignore lint/style/noNonNullAssertion: queue.length > 0 guard ensures shift() is defined
                 const stepId = queue.shift();
                 // C2: push before attaching .then() so indexOf is never -1
                 let resolveSlot;
@@ -192,8 +195,13 @@ export async function executeWithDependencies(graph, executeStep, options) {
 }
 /** Get steps that can run immediately (no unresolved dependencies) */
 export function getReadySteps(graph, completed) {
-    return graph.steps
-        .filter((s) => !completed.has(s.stepId) && s.awaits.every((dep) => completed.has(dep)))
-        .map((s) => s.stepId);
+    const result = [];
+    for (const s of graph.steps) {
+        if (!completed.has(s.stepId) &&
+            s.awaits.every((dep) => completed.has(dep))) {
+            result.push(s.stepId);
+        }
+    }
+    return result;
 }
 //# sourceMappingURL=dependencyGraph.js.map

package/dist/recipes/dependencyGraph.js.map

@@ -1 +1 @@
-{"version":3,"file":"dependencyGraph.js","sourceRoot":"","sources":["../../src/recipes/dependencyGraph.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dependencyGraph.js","sourceRoot":"","sources":["../../src/recipes/dependencyGraph.ts"],"names":[],"mappings":"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"}

package/dist/recipes/githubInstallSource.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Parses + allowlists the `github:<owner>/<repo>/(recipes|bundles)/<name>`
+ * source format used by `POST /recipes/install`.
+ *
+ * Before this module existed, the install handler hard-coded
+ * `github:patchworkos/recipes/...` everywhere — every URL, every
+ * prefix match. Third-party orgs / forks / private mirrors could not
+ * host recipe catalogs even though the rest of the install pipeline
+ * (SSRF guard, parser, scheduler) is org-agnostic.
+ *
+ * Allowlist policy:
+ *   - Always includes `patchworkos/recipes` (backward compat).
+ *   - Operator opts in additional `<owner>/<repo>` entries via the
+ *     `PATCHWORK_RECIPE_REPO_ALLOWLIST` env var (comma-separated).
+ *   - Allowlist matching is case-insensitive (GitHub itself is).
+ *   - Both owner and repo segments must match the strict regex
+ *     `[a-z0-9_.-]{1,100}` AFTER lowercasing — guards against
+ *     traversal segments smuggled into the source string.
+ *
+ * The default-only behaviour matches the audit recommendation: real
+ * multi-org support is opt-in, so existing single-org deployments
+ * don't see a behaviour change.
+ */
+export type GithubInstallKind = "recipe" | "bundle";
+export interface ParsedGithubInstallSource {
+    kind: GithubInstallKind;
+    owner: string;
+    repo: string;
+    /** Recipe name (single basename) or bundle name. */
+    name: string;
+}
+export type GithubInstallParseResult = {
+    ok: true;
+    parsed: ParsedGithubInstallSource;
+} | {
+    ok: false;
+    code: "bad_shape" | "bad_segment" | "not_allowlisted";
+    error: string;
+};
+export declare const SEGMENT_RE: RegExp;
+/**
+ * Read the runtime allowlist. Combines the always-on default with
+ * whatever the operator has set in PATCHWORK_RECIPE_REPO_ALLOWLIST.
+ * Entries are lowercased + de-duplicated; trailing whitespace, empty
+ * fragments, and shapes that don't look like `owner/repo` are
+ * silently dropped (logging here is the install handler's job, not
+ * this pure helper's).
+ */
+export declare function loadAllowlist(env?: NodeJS.ProcessEnv): string[];
+/**
+ * Parse a `github:owner/repo/(recipes|bundles)/name` source string
+ * against the active allowlist. Pure — does NOT fetch anything; the
+ * install handler is responsible for the network leg and the SSRF
+ * guard. Returns a discriminated union the caller can map to a 400
+ * (bad_shape / bad_segment) or 403 (not_allowlisted) response.
+ */
+export declare function parseGithubInstallSource(source: string, allowlist?: ReadonlyArray<string>): GithubInstallParseResult;
+/**
+ * Build the raw.githubusercontent URL for a parsed install source.
+ * Always pulls `main` branch HEAD — version pinning is on the
+ * deferred audit backlog.
+ */
+export declare function buildGithubRawUrl(parsed: ParsedGithubInstallSource): string;
+/**
+ * Build the `api.github.com` Contents-API URL for a parsed install
+ * source. Used as a FALLBACK when `raw.githubusercontent.com` is
+ * unreachable — many corporate / proxied networks block the raw host
+ * even when `api.github.com` is allowed. Combined with the
+ * `Accept: application/vnd.github.raw` request header (see
+ * `fetchGithubInstallFile`), this endpoint returns the raw file bytes
+ * directly — no base64 decode needed. Public repos work unauthenticated.
+ */
+export declare function buildGithubApiUrl(parsed: ParsedGithubInstallSource): string;
+/**
+ * Fetch a recipe / bundle file for a parsed `github:` install source
+ * with a raw-host-first, API-fallback strategy.
+ *
+ *   1. Try `raw.githubusercontent.com` (fast path, no rate limit).
+ *   2. If that throws a network error OR returns a non-ok response,
+ *      fall back to `api.github.com/repos/.../contents/...` with the
+ *      `Accept: application/vnd.github.raw` header (returns raw bytes).
+ *
+ * Return contract — designed so the caller's existing error mapping
+ * (502 / `fetch_network_error`, 404 not-found, upstream-error) is
+ * unchanged:
+ *
+ *   - `{ ok: true, response }` — a usable ok `Response`, from whichever
+ *     host succeeded. Caller reads the body as before.
+ *   - `{ ok: false, kind: "not_found", response }` — BOTH hosts agree
+ *     the file does not exist (raw 404 AND api 404). Caller surfaces
+ *     this as a genuine not-found (404), not a network error.
+ *   - `{ ok: false, kind: "upstream_error", response }` — a non-ok,
+ *     non-404 HTTP response (e.g. 5xx / 403 rate-limit). Caller maps
+ *     the upstream status as today.
+ *   - `{ ok: false, kind: "network_error", error }` — both hosts threw
+ *     a network-level error (DNS / connect / abort). Caller surfaces
+ *     the existing 502 `fetch_network_error` shape.
+ *
+ * Intentional edge case: when raw returns 404 but the api fallback
+ * *network-errors* (rather than also returning 404), the result is
+ * classified `not_found`, not `network_error`. This is a deliberate
+ * conservative call — a raw 404 is a strong signal the file is absent,
+ * and reporting "not found" is more actionable than a generic network
+ * error. Do not "fix" this to prefer network_error without weighing
+ * that tradeoff (see the matching test case).
+ *
+ * `signal` (caller's AbortController) and timeout behaviour are
+ * preserved — the same signal is passed to both fetch attempts.
+ */
+export type GithubInstallFetchResult = {
+    ok: true;
+    response: Response;
+} | {
+    ok: false;
+    kind: "not_found";
+    response: Response;
+} | {
+    ok: false;
+    kind: "upstream_error";
+    response: Response;
+} | {
+    ok: false;
+    kind: "network_error";
+    error: unknown;
+};
+export declare function fetchGithubInstallFile(parsed: ParsedGithubInstallSource, init?: {
+    signal?: AbortSignal;
+}): Promise<GithubInstallFetchResult>;

package/dist/recipes/githubInstallSource.js

@@ -0,0 +1,206 @@
+/**
+ * Parses + allowlists the `github:<owner>/<repo>/(recipes|bundles)/<name>`
+ * source format used by `POST /recipes/install`.
+ *
+ * Before this module existed, the install handler hard-coded
+ * `github:patchworkos/recipes/...` everywhere — every URL, every
+ * prefix match. Third-party orgs / forks / private mirrors could not
+ * host recipe catalogs even though the rest of the install pipeline
+ * (SSRF guard, parser, scheduler) is org-agnostic.
+ *
+ * Allowlist policy:
+ *   - Always includes `patchworkos/recipes` (backward compat).
+ *   - Operator opts in additional `<owner>/<repo>` entries via the
+ *     `PATCHWORK_RECIPE_REPO_ALLOWLIST` env var (comma-separated).
+ *   - Allowlist matching is case-insensitive (GitHub itself is).
+ *   - Both owner and repo segments must match the strict regex
+ *     `[a-z0-9_.-]{1,100}` AFTER lowercasing — guards against
+ *     traversal segments smuggled into the source string.
+ *
+ * The default-only behaviour matches the audit recommendation: real
+ * multi-org support is opt-in, so existing single-org deployments
+ * don't see a behaviour change.
+ */
+const DEFAULT_ALLOWLIST = ["patchworkos/recipes"];
+export const SEGMENT_RE = /^(?!.*\.\.)[a-z0-9_.-]{1,100}$/;
+/**
+ * Read the runtime allowlist. Combines the always-on default with
+ * whatever the operator has set in PATCHWORK_RECIPE_REPO_ALLOWLIST.
+ * Entries are lowercased + de-duplicated; trailing whitespace, empty
+ * fragments, and shapes that don't look like `owner/repo` are
+ * silently dropped (logging here is the install handler's job, not
+ * this pure helper's).
+ */
+export function loadAllowlist(env = process.env) {
+    const fromEnv = (env.PATCHWORK_RECIPE_REPO_ALLOWLIST ?? "")
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter((s) => s.length > 0 && s.includes("/"));
+    return Array.from(new Set([...DEFAULT_ALLOWLIST, ...fromEnv]));
+}
+/**
+ * Parse a `github:owner/repo/(recipes|bundles)/name` source string
+ * against the active allowlist. Pure — does NOT fetch anything; the
+ * install handler is responsible for the network leg and the SSRF
+ * guard. Returns a discriminated union the caller can map to a 400
+ * (bad_shape / bad_segment) or 403 (not_allowlisted) response.
+ */
+export function parseGithubInstallSource(source, allowlist = loadAllowlist()) {
+    if (!source.startsWith("github:")) {
+        return {
+            ok: false,
+            code: "bad_shape",
+            error: "source must start with 'github:'",
+        };
+    }
+    // After the `github:` prefix we expect <owner>/<repo>/<kind>/<name>.
+    // We split into exactly 4 segments — extra trailing slashes or
+    // missing components are rejected with `bad_shape` so the response
+    // is actionable.
+    const tail = source.slice("github:".length);
+    const segments = tail.split("/");
+    if (segments.length !== 4) {
+        return {
+            ok: false,
+            code: "bad_shape",
+            error: "source must match 'github:<owner>/<repo>/(recipes|bundles)/<name>'",
+        };
+    }
+    const [ownerRaw, repoRaw, kindRaw, nameRaw] = segments;
+    const owner = ownerRaw.toLowerCase();
+    const repo = repoRaw.toLowerCase();
+    if (!SEGMENT_RE.test(owner) || !SEGMENT_RE.test(repo)) {
+        return {
+            ok: false,
+            code: "bad_segment",
+            error: "owner and repo must match [a-z0-9_.-]{1,100}",
+        };
+    }
+    if (kindRaw !== "recipes" && kindRaw !== "bundles") {
+        return {
+            ok: false,
+            code: "bad_shape",
+            error: "third path segment must be 'recipes' or 'bundles'",
+        };
+    }
+    // Reuse the strict basename predicate inline rather than importing
+    // recipeInstall.ts here (circular deps), but match its rules:
+    // single segment, no `..`, no slashes, conservative charset, ≤100.
+    if (!SEGMENT_RE.test(nameRaw.toLowerCase())) {
+        return {
+            ok: false,
+            code: "bad_segment",
+            error: "name must match [a-z0-9_.-]{1,100}",
+        };
+    }
+    const allowSet = new Set(allowlist.map((s) => s.toLowerCase()));
+    if (!allowSet.has(`${owner}/${repo}`)) {
+        return {
+            ok: false,
+            code: "not_allowlisted",
+            error: `'${owner}/${repo}' is not in the recipe-repo allowlist. Set PATCHWORK_RECIPE_REPO_ALLOWLIST=${owner}/${repo} to opt in.`,
+        };
+    }
+    return {
+        ok: true,
+        parsed: {
+            kind: kindRaw === "recipes" ? "recipe" : "bundle",
+            owner,
+            repo,
+            name: nameRaw,
+        },
+    };
+}
+/**
+ * The repo-relative path of the file for a parsed install source.
+ * `recipes/<name>/<name>.yaml` or `bundles/<name>/patchwork-bundle.json`.
+ */
+function repoRelativePath(parsed) {
+    if (parsed.kind === "recipe") {
+        return `recipes/${parsed.name}/${parsed.name}.yaml`;
+    }
+    return `bundles/${parsed.name}/patchwork-bundle.json`;
+}
+/**
+ * Build the raw.githubusercontent URL for a parsed install source.
+ * Always pulls `main` branch HEAD — version pinning is on the
+ * deferred audit backlog.
+ */
+export function buildGithubRawUrl(parsed) {
+    return `https://raw.githubusercontent.com/${parsed.owner}/${parsed.repo}/main/${repoRelativePath(parsed)}`;
+}
+/**
+ * Build the `api.github.com` Contents-API URL for a parsed install
+ * source. Used as a FALLBACK when `raw.githubusercontent.com` is
+ * unreachable — many corporate / proxied networks block the raw host
+ * even when `api.github.com` is allowed. Combined with the
+ * `Accept: application/vnd.github.raw` request header (see
+ * `fetchGithubInstallFile`), this endpoint returns the raw file bytes
+ * directly — no base64 decode needed. Public repos work unauthenticated.
+ */
+export function buildGithubApiUrl(parsed) {
+    return `https://api.github.com/repos/${parsed.owner}/${parsed.repo}/contents/${repoRelativePath(parsed)}?ref=main`;
+}
+export async function fetchGithubInstallFile(parsed, init = {}) {
+    const rawUrl = buildGithubRawUrl(parsed);
+    let rawResponse = null;
+    let rawNetworkError = null;
+    try {
+        rawResponse = await fetch(rawUrl, {
+            signal: init.signal,
+            redirect: "follow",
+        });
+    }
+    catch (err) {
+        rawNetworkError = err;
+    }
+    // Fast path: raw host returned a usable response.
+    if (rawResponse?.ok) {
+        return { ok: true, response: rawResponse };
+    }
+    // Raw host either threw OR returned non-ok → try the API fallback.
+    const apiUrl = buildGithubApiUrl(parsed);
+    let apiResponse = null;
+    let apiNetworkError = null;
+    try {
+        apiResponse = await fetch(apiUrl, {
+            signal: init.signal,
+            redirect: "follow",
+            headers: { Accept: "application/vnd.github.raw" },
+        });
+    }
+    catch (err) {
+        apiNetworkError = err;
+    }
+    if (apiResponse?.ok) {
+        return { ok: true, response: apiResponse };
+    }
+    // Neither host yielded an ok body. Decide which failure to surface.
+    //
+    // A non-404 HTTP failure (5xx / 403 rate-limit) is the most
+    // actionable signal — prefer it over a 404 from the other host, so a
+    // transient upstream problem isn't misreported as "recipe missing".
+    // The API response is the more authoritative of the two here (raw is
+    // a CDN; the API gives proper status codes), so check it first.
+    if (apiResponse && apiResponse.status !== 404) {
+        return { ok: false, kind: "upstream_error", response: apiResponse };
+    }
+    if (rawResponse && rawResponse.status !== 404) {
+        return { ok: false, kind: "upstream_error", response: rawResponse };
+    }
+    // Whatever is left is a genuine 404 from one or both hosts → keep
+    // the not-found distinction so the caller surfaces a 404, not a 502.
+    if (apiResponse && apiResponse.status === 404) {
+        return { ok: false, kind: "not_found", response: apiResponse };
+    }
+    if (rawResponse && rawResponse.status === 404) {
+        return { ok: false, kind: "not_found", response: rawResponse };
+    }
+    // Both hosts threw network errors.
+    return {
+        ok: false,
+        kind: "network_error",
+        error: apiNetworkError ?? rawNetworkError,
+    };
+}
+//# sourceMappingURL=githubInstallSource.js.map

package/dist/recipes/githubInstallSource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"githubInstallSource.js","sourceRoot":"","sources":["../../src/recipes/githubInstallSource.ts"],"names":[],"mappings":"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"}

package/dist/recipes/haltCategory.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Halt-category derivation.
+ *
+ * PR1c of the Val-inspired plan. PR1 attached a `haltReason` sentence to
+ * every error-status StepResult; this module categorises those sentences
+ * into a small bounded enum so the dashboard / metrics layer can count
+ * them over time. Foundation for "is the haltReason work actually
+ * surfacing useful signal, or is everything landing in `unknown`?"
+ *
+ * The mapping is intentionally pattern-based against the 5 phrases
+ * emitted by yamlRunner.ts. Keep this file and those phrases in sync.
+ * When a new error site is added, add a category here AND a test.
+ */
+export type HaltCategory = "agent_silent_fail" | "agent_narration_only" | "agent_threw" | "tool_threw" | "tool_error"
+/** Write blocked by the global kill-switch (#422). Distinct from a real tool failure. */
+ | "kill_switch"
+/** Recipe's `tokensMax` budget breached (PR2b). */
+ | "budget_exceeded"
+/** Per-step `expect` assertion failed (slice 2). */
+ | "expect_failed"
+/** Per-step wall-clock `timeout_ms` exceeded (sandbox-alternative slice). */
+ | "step_timeout"
+/**
+ * Connector returned 401/403 — token expired or scopes insufficient.
+ * Actionable: user should reconnect from /connections.
+ */
+ | "auth_failure"
+/**
+ * External service returned 429 / rate limit. Actionable: retry later
+ * or back off the cron cadence.
+ */
+ | "rate_limited"
+/**
+ * Transport failed before the request reached the service
+ * (ECONNREFUSED, ENOTFOUND, fetch failed). Distinct from a 4xx/5xx
+ * from the service itself — usually a local network / DNS issue.
+ */
+ | "network_error"
+/**
+ * Tool needed a connector that isn't configured for this workspace.
+ * Actionable: install/connect from /connections.
+ */
+ | "missing_connector"
+/** Whole-recipe failure (e.g. circular dependencies) — has no step row. */
+ | "run_level" | "unknown";
+/**
+ * Human-readable label per category. Shared by the `halts` CLI, the
+ * `recipe doctor` command, and (mirrored) the dashboard, so the wording
+ * stays consistent across surfaces.
+ */
+export declare const HALT_CATEGORY_LABELS: Record<HaltCategory, string>;
+/**
+ * Actionable one-liner per category — "what to do about it". Shared by
+ * the `halts` CLI and `recipe doctor` so SSH / mobile users get the fix
+ * hint without opening the dashboard.
+ */
+export declare const HALT_CATEGORY_HINTS: Record<HaltCategory, string>;
+export declare function categoriseHaltReason(reason: string | undefined): HaltCategory;
+export interface HaltSummary {
+    /** Total error-status step results scanned. */
+    total: number;
+    /** Per-category counts; categories with zero hits are omitted. */
+    byCategory: Partial<Record<HaltCategory, number>>;
+    /** Most recent 5 halt reasons (verbatim) for surfacing in the UI. */
+    recent: Array<{
+        reason: string;
+        category: HaltCategory;
+        runSeq: number;
+    }>;
+}
+interface HaltSummaryInputRun {
+    seq: number;
+    /** Top-level run status — `run_level` halts are runs with status === "error" but no error stepResults (e.g. circular-dep failure before any step ran). */
+    status?: "running" | "done" | "error" | "cancelled" | "interrupted";
+    /** Top-level errorMessage — surfaced as a `run_level` halt when no per-step halts cover it. */
+    errorMessage?: string;
+    stepResults?: Array<{
+        status: "ok" | "skipped" | "error";
+        haltReason?: string;
+        /** Pre-tagged category from yamlRunner throw site — avoids regex re-derivation when present. */
+        haltCategory?: HaltCategory;
+    }>;
+}
+/**
+ * Aggregate halt categories across a set of runs. Runs are expected to be
+ * sorted newest-first so `recent` reflects the most recent halts.
+ *
+ * A run contributes:
+ * - one entry per error-status stepResult that has a `haltReason`
+ * - plus one `run_level` entry if `status === "error"` and there were no
+ *   per-step halts that already explained it (avoids double-counting).
+ */
+export declare function summariseHalts(runs: HaltSummaryInputRun[]): HaltSummary;
+/**
+ * Format a `HaltSummary` as Prometheus text-exposition lines for the
+ * `bridge_recipe_halts{category="..."} N` gauge. Returns an empty array
+ * when the summary is empty (no HELP/TYPE block emitted in that case so
+ * Prom scrapers don't see an orphan declaration).
+ *
+ * Surfaced via `/metrics` so users with their own observability stack
+ * can dashboard halts without using Patchwork's UI.
+ */
+export declare function haltSummaryToPrometheus(summary: HaltSummary): string[];
+/**
+ * Derive a one-sentence haltReason from a step's error-status + raw error
+ * string. Used by `chainedRunner` to mirror the convention emitted by
+ * `yamlRunner`. Returns `undefined` for non-error rows or missing error.
+ *
+ * Pattern-matches the same phrases `categoriseHaltReason` knows about,
+ * so chained-run haltReasons categorise into the same buckets.
+ */
+export declare function deriveHaltReasonFromError(opts: {
+    stepId: string;
+    toolName?: string;
+    isAgent?: boolean;
+    status: "ok" | "skipped" | "error";
+    error?: string;
+}): string | undefined;
+export {};