xcoder-dna 1.3.1 → 1.4.0

package/dist/cli/delegate.d.ts

@@ -0,0 +1,90 @@
+import type { Command } from "commander";
+/** The closed allowlist of agent CLIs that may be reached through `xcoder`. */
+export declare const DELEGABLE_TARGETS: readonly ["jarvis", "litebro", "bugfinder"];
+export type DelegableTarget = (typeof DELEGABLE_TARGETS)[number];
+/** Shell convention for "command not found", identical on every platform. */
+export declare const EXIT_ENOENT = 127;
+/**
+ * Interrupted. POSIX would be 128+SIGINT (130); Windows has no signal-number
+ * convention, so one deterministic, testable constant is used everywhere.
+ */
+export declare const EXIT_INTERRUPTED = 130;
+export interface DelegateSpec {
+    /** Allowlisted target name as typed by the user. */
+    readonly target: DelegableTarget;
+    /** Executable name on PATH, used when the workspace build is absent. */
+    readonly bin: string;
+    /** Workspace-relative built entry point, tried before PATH. */
+    readonly fallbackModule: string;
+    /** One-line description used in command help. */
+    readonly summary: string;
+}
+/** Minimal child handle — the subset of ChildProcess this module relies on. */
+export interface ChildHandle {
+    once(event: "exit", listener: (code: number | null, signal: string | null) => void): unknown;
+    once(event: "error", listener: (error: NodeJS.ErrnoException) => void): unknown;
+    kill(signal?: NodeJS.Signals | number): boolean;
+}
+export interface SpawnOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    stdio: "inherit";
+    shell: false;
+}
+export type SpawnFn = (cmd: string, argv: readonly string[], opts: SpawnOptions) => ChildHandle;
+export interface DelegateDeps {
+    readonly spawn?: SpawnFn;
+    readonly resolveBin?: (spec: DelegateSpec, cwd: string) => {
+        command: string;
+        argv: string[];
+    } | null;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly cwd?: string;
+    readonly stderr?: NodeJS.WritableStream;
+}
+/** The jarvis spec, shared by the `xcoder` CLI and the aggregator's DISPATCH. */
+export declare const JARVIS_SPEC: DelegateSpec;
+export declare function isDelegableTarget(name: string): name is DelegableTarget;
+/** The spec for an allowlisted target, or `undefined` for anything else. */
+export declare function delegateSpec(target: string): DelegateSpec | undefined;
+/**
+ * Resolve what to execute.
+ *
+ * The workspace build is tried first so a developer running from a checkout gets
+ * the code they just built; PATH is the declared fallback once published. The
+ * choice is returned so callers can log it (Spoofing control, design T4).
+ */
+export declare function resolveDelegateCommand(spec: DelegateSpec, cwd: string): {
+    command: string;
+    argv: string[];
+} | null;
+/**
+ * Run the child with `argv` verbatim and return the code the parent must exit with.
+ *
+ * Never builds a command string, never parses, normalises, reorders or drops an
+ * argument, and never throws for an expected condition (spawn failure → 1).
+ */
+export declare function runDelegated(spec: DelegateSpec, argv: readonly string[], deps?: DelegateDeps): Promise<number>;
+/**
+ * Register `<target> [args...]` on `parent` with pure passthrough semantics.
+ *
+ * Registering makes the target discoverable in `xcoder --help`. Argument
+ * handling belongs to `extractDelegatedArg`, because commander would otherwise
+ * consume root options that the child legitimately accepts.
+ */
+export declare function registerDelegatedCommand(parent: Command, spec: DelegateSpec): void;
+export interface DelegatedInvocation {
+    readonly spec: DelegateSpec;
+    /** Everything after the target, untouched. */
+    readonly args: string[];
+    /** Index of the target token in the argv that was scanned. */
+    readonly index: number;
+}
+/**
+ * Detect a delegation from raw argv, before commander sees anything.
+ *
+ * Returns `undefined` for every ordinary invocation, so existing commands are
+ * parsed exactly as before. When a target is found, everything after it is
+ * returned untouched — the parent never validates a child flag.
+ */
+export declare function extractDelegatedArg(argv: readonly string[]): DelegatedInvocation | undefined;

package/dist/cli/delegate.js

@@ -0,0 +1,220 @@
+// xcoder:version 6 | xcoder:task task-691585 | xcoder:updated 2026-11-05T05:46:07.113Z | xcoder:subtask code-st-b5251b
+// Cross-CLI delegation seam.
+//
+// `xcoder jarvis <args...>` runs the real `jarvis` binary in a child process
+// and forwards every argument verbatim. This module owns that seam and nothing
+// else: it does not know what jarvis does, and it never interprets a child flag.
+//
+// Why a subprocess and not an import: boundary rule 1 (`scripts/check-boundaries.mjs`)
+// forbids one agent importing another, and the `xcoder` bin lives in
+// `@xcoder/sdlc-agent`. The only legal shared home for this code is this library.
+//
+// Why argv is pre-extracted instead of parsed by commander: commander eagerly
+// consumes root options (`--config`, `--workspace`) it sees after a subcommand,
+// which would silently swallow a child flag. The workspace already solves this
+// class of problem the same way for `--config` and `--wbc` (see `wbc-arg.ts`),
+// so delegation follows that precedent rather than adding a new parsing mode.
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+/** The closed allowlist of agent CLIs that may be reached through `xcoder`. */
+export const DELEGABLE_TARGETS = ["jarvis", "litebro", "bugfinder"];
+/** Shell convention for "command not found", identical on every platform. */
+export const EXIT_ENOENT = 127;
+/**
+ * Interrupted. POSIX would be 128+SIGINT (130); Windows has no signal-number
+ * convention, so one deterministic, testable constant is used everywhere.
+ */
+export const EXIT_INTERRUPTED = 130;
+/** The jarvis spec, shared by the `xcoder` CLI and the aggregator's DISPATCH. */
+export const JARVIS_SPEC = {
+    target: "jarvis",
+    bin: "jarvis",
+    fallbackModule: path.join("packages", "jarvis-agent", "dist", "program.js"),
+    summary: "Jarvis — ReAct agent with scoped memory and an enforced tool allowlist",
+};
+const SPECS = {
+    jarvis: JARVIS_SPEC,
+    litebro: {
+        target: "litebro",
+        bin: "litebro",
+        fallbackModule: path.join("packages", "litebro", "dist", "cli.js"),
+        summary: "Litebro — tool-less planner/broker",
+    },
+    bugfinder: {
+        target: "bugfinder",
+        bin: "bugfinder",
+        fallbackModule: path.join("packages", "qa-agent", "dist", "qa-cli.js"),
+        summary: "Bugfinder — the QA agent",
+    },
+};
+export function isDelegableTarget(name) {
+    return DELEGABLE_TARGETS.includes(name);
+}
+/** The spec for an allowlisted target, or `undefined` for anything else. */
+export function delegateSpec(target) {
+    return isDelegableTarget(target) ? SPECS[target] : undefined;
+}
+/**
+ * Resolve what to execute.
+ *
+ * The workspace build is tried first so a developer running from a checkout gets
+ * the code they just built; PATH is the declared fallback once published. The
+ * choice is returned so callers can log it (Spoofing control, design T4).
+ */
+export function resolveDelegateCommand(spec, cwd) {
+    const local = path.resolve(cwd, spec.fallbackModule);
+    if (existsSync(local))
+        return { command: process.execPath, argv: [local] };
+    return { command: spec.bin, argv: [] };
+}
+function validTargetsMessage() {
+    return `valid targets: ${DELEGABLE_TARGETS.join(", ")}`;
+}
+/**
+ * Run the child with `argv` verbatim and return the code the parent must exit with.
+ *
+ * Never builds a command string, never parses, normalises, reorders or drops an
+ * argument, and never throws for an expected condition (spawn failure → 1).
+ */
+export async function runDelegated(spec, argv, deps = {}) {
+    const stderr = deps.stderr ?? process.stderr;
+    if (!isDelegableTarget(spec.target)) {
+        stderr.write(`xcoder: '${spec.target}' is not a delegable target — ${validTargetsMessage()}\n`);
+        return 1;
+    }
+    const cwd = deps.cwd ?? process.cwd();
+    const resolve = deps.resolveBin ?? ((s, c) => resolveDelegateCommand(s, c));
+    const launch = resolve(spec, cwd);
+    if (launch === null) {
+        stderr.write(`xcoder: cannot find '${spec.bin}' — install it or build the workspace (${spec.fallbackModule}). ${validTargetsMessage()}\n`);
+        return EXIT_ENOENT;
+    }
+    if (deps.env?.XCODER_DELEGATE_VERBOSE ?? process.env.XCODER_DELEGATE_VERBOSE) {
+        // Counts and identifiers only: never the arguments themselves (no task text,
+        // no PII), never the environment.
+        stderr.write(`xcoder: delegating to ${spec.target} via ${launch.command} (${argv.length} argument${argv.length === 1 ? "" : "s"})\n`);
+    }
+    const spawnFn = deps.spawn ?? spawn;
+    const env = deps.env ?? process.env;
+    return new Promise((resolvePromise) => {
+        let child;
+        try {
+            child = spawnFn(launch.command, [...launch.argv, ...argv], {
+                cwd,
+                env,
+                stdio: "inherit",
+                shell: false,
+            });
+        }
+        catch (err) {
+            // Fail closed: a delegation that never started is not a success.
+            stderr.write(`xcoder: failed to start '${spec.bin}': ${err.message}\n`);
+            resolvePromise(1);
+            return;
+        }
+        const forward = (signal) => {
+            try {
+                child.kill(signal);
+            }
+            catch {
+                // The child is already gone; the exit handler owns the outcome.
+            }
+        };
+        const onSigint = () => forward("SIGINT");
+        const onSigterm = () => forward("SIGTERM");
+        process.on("SIGINT", onSigint);
+        process.on("SIGTERM", onSigterm);
+        const settle = (code) => {
+            process.off("SIGINT", onSigint);
+            process.off("SIGTERM", onSigterm);
+            resolvePromise(code);
+        };
+        child.once("error", (err) => {
+            if (err.code === "ENOENT") {
+                stderr.write(`xcoder: cannot find '${spec.bin}' — ${validTargetsMessage()}\n`);
+                settle(EXIT_ENOENT);
+                return;
+            }
+            stderr.write(`xcoder: '${spec.bin}' failed to start: ${err.message}\n`);
+            settle(1);
+        });
+        child.once("exit", (code, _signal) => {
+            if (code !== null) {
+                // The child's own exit code is the parent's, unchanged (0/1/2 all pass through).
+                settle(code);
+                return;
+            }
+            settle(EXIT_INTERRUPTED);
+        });
+    });
+}
+/**
+ * Register `<target> [args...]` on `parent` with pure passthrough semantics.
+ *
+ * Registering makes the target discoverable in `xcoder --help`. Argument
+ * handling belongs to `extractDelegatedArg`, because commander would otherwise
+ * consume root options that the child legitimately accepts.
+ */
+export function registerDelegatedCommand(parent, spec) {
+    parent
+        .command(`${spec.target} [args...]`)
+        .description(`${spec.summary}. Every argument is forwarded verbatim.`)
+        .helpOption(false)
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .action(async (_args, _opts, cmd) => {
+        const code = await runDelegated(spec, cmd.args);
+        process.exitCode = code;
+    });
+}
+/**
+ * Root options that take a value, so their value is never mistaken for a target.
+ *
+ * Closed on purpose: a wildcard here would let any argument become a command,
+ * and dropping an entry here would make `xcoder -task jarvis` run the `jarvis`
+ * binary instead of a task called "jarvis". Options with an *optional* value
+ * (`--resume`, `--debug-tools`) are listed too: their value can look exactly
+ * like a target, so the conservative reading is "do not delegate".
+ */
+const ROOT_OPTIONS_WITH_VALUE = new Set([
+    "--config",
+    "-w",
+    "--workspace",
+    "--wbc",
+    "--wbs",
+    "-task",
+    "--task",
+    "--design",
+    "--code",
+    "--defect",
+    "--budget",
+    "--max-healing",
+    "-c",
+    "--concurrency",
+    "--model",
+    "--spinner",
+    "--resume",
+    "--debug-tools",
+]);
+/**
+ * Detect a delegation from raw argv, before commander sees anything.
+ *
+ * Returns `undefined` for every ordinary invocation, so existing commands are
+ * parsed exactly as before. When a target is found, everything after it is
+ * returned untouched — the parent never validates a child flag.
+ */
+export function extractDelegatedArg(argv) {
+    for (let i = 2; i < argv.length; i++) {
+        const token = argv[i];
+        if (ROOT_OPTIONS_WITH_VALUE.has(token)) {
+            i++; // skip this option's value
+            continue;
+        }
+        if (token.startsWith("-"))
+            continue;
+        const spec = delegateSpec(token);
+        return spec ? { spec, args: argv.slice(i + 1), index: i } : undefined;
+    }
+    return undefined;
+}

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { SubAgent } from "./agents/sub-agent.js";
 export { addBacklogItem, updateBacklogItem, listBacklogItems, getBacklogItem } from "./backlog/backlog-store.js";
 export { runPoPick } from "./backlog/po-agent.js";
 export { runBenchmark, compareReports } from "./bench/run.js";
+export { DELEGABLE_TARGETS, EXIT_ENOENT, EXIT_INTERRUPTED, JARVIS_SPEC, delegateSpec, extractDelegatedArg, isDelegableTarget, registerDelegatedCommand, resolveDelegateCommand, runDelegated, type DelegateDeps, type DelegateSpec, type DelegableTarget } from "./cli/delegate.js";
 export { registerSwarmCommand } from "./cli/swarm.js";
 export { registerTaskCommand } from "./cli/task.js";
 export { extractWbcArg } from "./cli/wbc-arg.js";

package/dist/index.js

@@ -1,3 +1,4 @@
+// xcoder:version 2 | xcoder:task task-691585 | xcoder:updated 2026-11-05T05:45:12.986Z | xcoder:subtask code-st-b5251b
 // Public barrel — the only import path other packages may use.
 export { runDebate } from "./agents/ai-chat-debate.js";
 export { writeReport } from "./agents/ai-chat-report-writer.js";
@@ -8,6 +9,7 @@ export { SubAgent } from "./agents/sub-agent.js";
 export { addBacklogItem, updateBacklogItem, listBacklogItems, getBacklogItem } from "./backlog/backlog-store.js";
 export { runPoPick } from "./backlog/po-agent.js";
 export { runBenchmark, compareReports } from "./bench/run.js";
+export { DELEGABLE_TARGETS, EXIT_ENOENT, EXIT_INTERRUPTED, JARVIS_SPEC, delegateSpec, extractDelegatedArg, isDelegableTarget, registerDelegatedCommand, resolveDelegateCommand, runDelegated } from "./cli/delegate.js";
 export { registerSwarmCommand } from "./cli/swarm.js";
 export { registerTaskCommand } from "./cli/task.js";
 export { extractWbcArg } from "./cli/wbc-arg.js";

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const XCODER_VERSION = "1.3.0";
+export declare const XCODER_VERSION = "1.4.0";
 export declare const XCODER_BUILD_TIMESTAMP = "2026-10-26T00:00:00.000Z";

package/dist/version.js

@@ -1,4 +1,5 @@
+// xcoder:version 1 | xcoder:task task-762833 | xcoder:updated 2026-11-05T05:18:45.488Z | xcoder:subtask code-st-bb4289
 // AUTO-GENERATED by scripts/inject-version.mjs — DO NOT EDIT
 // Regenerate: npm run build (or: node scripts/inject-version.mjs)
-export const XCODER_VERSION = "1.3.0";
+export const XCODER_VERSION = "1.4.0";
 export const XCODER_BUILD_TIMESTAMP = "2026-10-26T00:00:00.000Z";

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "xcoder-dna",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Reusable Xcoder components: tools, skills, swarm, sub-agent runtime and shared orchestration primitives.",
+  "license": "MIT",
+  "author": "Neural Node Labs",
   "type": "module",
   "engines": {
     "node": ">=20"