crewhaus 0.2.4 → 0.3.0

package/dist/fleet.d.ts

@@ -1,3 +1,4 @@
+import { type FailureClass } from "@crewhaus/errors";
 import type { Manifest } from "@crewhaus/spec-registry";
 /** The spec file that roots a standalone harness. */
 export declare const HARNESS_SPEC_FILENAME = "crewhaus.yaml";
@@ -165,6 +166,41 @@ export type FleetRunner = (opts: {
     readonly exitCode: number;
     readonly tail: string;
 }>;
+/**
+ * Is `entryPath` the Bun standalone-executable virtual-FS sentinel — i.e. are
+ * we running a `bun build --compile` single-file binary rather than
+ * `bun run …/index.ts`? Bun rewrites the entry (`process.argv[1]` / `Bun.main`)
+ * to a path inside its embedded root: `/$bunfs/root/<name>` on POSIX,
+ * `B:\~BUN\root\<name>` on Windows.
+ */
+export declare function isCompiledEntryPath(entryPath: string): boolean;
+/** The runtime facts the self-invoke argv depends on, injected so the builder
+ *  is a pure function: production passes the live `process.execPath` +
+ *  `Bun.main`; tests pass fixed strings for either mode. */
+export type SelfInvokeContext = {
+    /** The real running executable — `bun` in dev, the compiled binary itself
+     *  when compiled (`process.execPath`, NOT `process.argv[0]`, which the
+     *  compiled runtime reports as the literal string `"bun"`). */
+    readonly execPath: string;
+    /** The entry path as the runtime sees it (`process.argv[1]` / `Bun.main`):
+     *  the real `…/index.ts` in dev, the `/$bunfs/…` sentinel when compiled. */
+    readonly entryPath: string;
+};
+/**
+ * Build the argv to re-invoke THIS running CLI in a child process with
+ * `childArgv` (e.g. `["doctor"]`) — correct under BOTH `bun run
+ * apps/cli/src/index.ts …` and a `bun build --compile` single-file binary.
+ *
+ * The compiled case is the subtle one. A standalone binary RE-INJECTS its own
+ * embedded entry every time it is spawned, so the child already receives
+ * `[<exe>, /$bunfs/root/<name>, ...childArgv]`. If we ALSO passed our own
+ * `entryPath` (the `/$bunfs/…` sentinel) it would land in the child's user
+ * args and be parsed as the subcommand — the v0.2.4 bug where `fleet run
+ * doctor` reported `unknown subcommand: /$bunfs/root/crewhaus-…` for every
+ * harness. So: compiled → `[execPath, ...childArgv]` and let Bun supply the
+ * entry; dev → `[execPath, entryPath, ...childArgv]` with the real script path.
+ */
+export declare function fleetSelfInvokeArgv(ctx: SelfInvokeContext, childArgv: ReadonlyArray<string>): string[];
 /** Per-harness confirm seam for `--allow-mutating` (interactive prompt in the
  *  CLI; a predicate in tests). Returning false skips that harness. */
 export type ConfirmMutating = (inv: HarnessInventory, argv: ReadonlyArray<string>) => Promise<boolean>;
@@ -203,5 +239,19 @@ export type RunFleetBulkReport = {
  * runner is the sole side-effect surface, injected for testability.
  */
 export declare function runFleetBulk(opts: RunFleetBulkOptions): Promise<RunFleetBulkReport>;
+/**
+ * v0.3.0 Goal 6 — decode a child process's exit code back into its failure
+ * class + report title. The coded exits are the documented `EXIT_CODES`
+ * contract every terminal surface (die(), the compiled-bundle catch
+ * wrappers) now honours, so fleet can say "out of funding" instead of
+ * "exit 31" without parsing any output. Titles mirror the
+ * `BUILTIN_FAILURE_CLASSES` wording (recovery-engine) for the provider
+ * classes and the `EXIT_CODES` doc comments for the rest. Exit 0 and
+ * unmapped codes return undefined (a plain `exit N` line).
+ */
+export declare function describeFleetExit(exitCode: number): {
+    readonly class: FailureClass;
+    readonly title: string;
+} | undefined;
 /** Render a bulk-run report as summary lines for `fleet run`. */
 export declare function formatBulkReport(report: RunFleetBulkReport): ReadonlyArray<string>;

package/dist/fleet.js

@@ -49,6 +49,7 @@
  */
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { EXIT_CODES } from "@crewhaus/errors";
 import { extractFeedbackRecords, mergeFeedback } from "./feedback";
 /** The spec file that roots a standalone harness. */
 export const HARNESS_SPEC_FILENAME = "crewhaus.yaml";
@@ -426,6 +427,35 @@ export function matchesFilter(inv, filter) {
     const glob = new Bun.Glob(filter);
     return glob.match(inv.specName) || glob.match(basenameOf(inv.dir));
 }
+/**
+ * Is `entryPath` the Bun standalone-executable virtual-FS sentinel — i.e. are
+ * we running a `bun build --compile` single-file binary rather than
+ * `bun run …/index.ts`? Bun rewrites the entry (`process.argv[1]` / `Bun.main`)
+ * to a path inside its embedded root: `/$bunfs/root/<name>` on POSIX,
+ * `B:\~BUN\root\<name>` on Windows.
+ */
+export function isCompiledEntryPath(entryPath) {
+    return (entryPath.includes("/$bunfs/") || entryPath.includes("\\~BUN\\") || entryPath.includes("/~BUN/"));
+}
+/**
+ * Build the argv to re-invoke THIS running CLI in a child process with
+ * `childArgv` (e.g. `["doctor"]`) — correct under BOTH `bun run
+ * apps/cli/src/index.ts …` and a `bun build --compile` single-file binary.
+ *
+ * The compiled case is the subtle one. A standalone binary RE-INJECTS its own
+ * embedded entry every time it is spawned, so the child already receives
+ * `[<exe>, /$bunfs/root/<name>, ...childArgv]`. If we ALSO passed our own
+ * `entryPath` (the `/$bunfs/…` sentinel) it would land in the child's user
+ * args and be parsed as the subcommand — the v0.2.4 bug where `fleet run
+ * doctor` reported `unknown subcommand: /$bunfs/root/crewhaus-…` for every
+ * harness. So: compiled → `[execPath, ...childArgv]` and let Bun supply the
+ * entry; dev → `[execPath, entryPath, ...childArgv]` with the real script path.
+ */
+export function fleetSelfInvokeArgv(ctx, childArgv) {
+    return isCompiledEntryPath(ctx.entryPath)
+        ? [ctx.execPath, ...childArgv]
+        : [ctx.execPath, ctx.entryPath, ...childArgv];
+}
 /**
  * Run one subcommand across the filtered fleet. Read-only commands run
  * unconditionally on every matched harness; a mutating command (only reachable
@@ -462,6 +492,35 @@ export async function runFleetBulk(opts) {
     }
     return { plan, results, failed, passed, skipped };
 }
+/**
+ * v0.3.0 Goal 6 — decode a child process's exit code back into its failure
+ * class + report title. The coded exits are the documented `EXIT_CODES`
+ * contract every terminal surface (die(), the compiled-bundle catch
+ * wrappers) now honours, so fleet can say "out of funding" instead of
+ * "exit 31" without parsing any output. Titles mirror the
+ * `BUILTIN_FAILURE_CLASSES` wording (recovery-engine) for the provider
+ * classes and the `EXIT_CODES` doc comments for the rest. Exit 0 and
+ * unmapped codes return undefined (a plain `exit N` line).
+ */
+export function describeFleetExit(exitCode) {
+    const table = {
+        [EXIT_CODES.generic]: { class: "unknown", title: "unclassified failure" },
+        [EXIT_CODES.spec]: { class: "spec", title: "spec parse/validation failed" },
+        [EXIT_CODES.config]: { class: "config", title: "config / missing env" },
+        [EXIT_CODES.auth]: { class: "auth", title: "provider rejected the credentials" },
+        [EXIT_CODES.billing]: { class: "billing", title: "provider account out of funding" },
+        [EXIT_CODES.rate_limit]: {
+            class: "rate_limit",
+            title: "provider rate limit still exceeded after retries",
+        },
+        [EXIT_CODES.crewhaus_budget]: {
+            class: "crewhaus_budget",
+            title: "run stopped by the configured budget cap",
+        },
+        [EXIT_CODES.tool]: { class: "tool", title: "tool / MCP failure" },
+    };
+    return table[exitCode];
+}
 /** Render a bulk-run report as summary lines for `fleet run`. */
 export function formatBulkReport(report) {
     const cmd = report.plan.argv.join(" ");
@@ -475,7 +534,12 @@ export function formatBulkReport(report) {
             continue;
         }
         const mark = r.exitCode === 0 ? "✓" : "✗";
-        lines.push(`${mark} ${r.inv.specName} — exit ${r.exitCode}`);
+        // v0.3.0 Goal 6 — a coded exit renders its failure title inline:
+        //   ✗ support-bot — provider account out of funding · exit 31
+        const described = r.exitCode !== 0 ? describeFleetExit(r.exitCode ?? 0) : undefined;
+        lines.push(described !== undefined
+            ? `${mark} ${r.inv.specName} — ${described.title} · exit ${r.exitCode}`
+            : `${mark} ${r.inv.specName} — exit ${r.exitCode}`);
         const tail = (r.tail ?? "").trim();
         if (tail !== "") {
             for (const line of tail.split("\n").slice(-3))
@@ -483,6 +547,18 @@ export function formatBulkReport(report) {
         }
     }
     lines.push("");
-    lines.push(`summary: ${report.passed} passed, ${report.failed} failed, ${report.skipped} skipped`);
+    // v0.3.0 Goal 6 — class-keyed failure rollup: `2 failed (billing ×1,
+    // unknown ×1)` so a fleet-wide funding outage reads at a glance.
+    const classCounts = new Map();
+    for (const r of report.results) {
+        if (!r.ran || r.exitCode === 0 || r.exitCode === undefined)
+            continue;
+        const cls = describeFleetExit(r.exitCode)?.class ?? "unknown";
+        classCounts.set(cls, (classCounts.get(cls) ?? 0) + 1);
+    }
+    const rollup = classCounts.size > 0
+        ? ` (${[...classCounts.entries()].map(([cls, n]) => `${cls} ×${n}`).join(", ")})`
+        : "";
+    lines.push(`summary: ${report.passed} passed, ${report.failed} failed${rollup}, ${report.skipped} skipped`);
     return lines;
 }