opensip-cli 0.1.13 → 0.1.15

package/dist/commands/suite/orchestrator.js

@@ -0,0 +1,216 @@
+import { performance } from 'node:perf_hooks';
+import { EXIT_CODES } from '@opensip-cli/contracts';
+import { currentLogger, currentScope, generatePrefixedId, } from '@opensip-cli/core';
+import { buildMaybeDispatchExternal } from '../../bootstrap/bind-external-dispatch.js';
+import { bindToolCliContext } from '../../bootstrap/bind-tool-context.js';
+import { runWithSuiteRunContext } from '../../bootstrap/run-plane.js';
+import { assembleOptsFromSpec } from '../assemble-opts.js';
+import { dispatchOutput } from '../mount-command-spec.js';
+import { createCapturingContext } from './capturing-context.js';
+import { validateSuite } from './validate-suite.js';
+class DirectProcessExit extends Error {
+    code;
+    constructor(code) {
+        super(`process.exit(${code})`);
+        this.code = code;
+    }
+}
+export async function runSuite(input) {
+    const suite = validateSuite({
+        name: input.name,
+        suite: input.suite,
+        tools: input.tools,
+    });
+    const suiteRunId = generatePrefixedId('suite');
+    const started = performance.now();
+    const log = currentLogger();
+    log.info?.({
+        evt: 'cli.suite.run.start',
+        suite: suite.name,
+        suiteRunId,
+        stepCount: suite.steps.length,
+    });
+    const steps = await runWithSuiteRunContext({ suiteRunId, suiteName: suite.name }, () => runStepsSerially({
+        suite,
+        suiteRunId,
+        ctx: input.ctx,
+        suiteOpts: input.suiteOpts,
+    }));
+    const exitCode = Math.max(0, ...steps.map((step) => step.exitCode));
+    const durationMs = Math.max(0, performance.now() - started);
+    log.info?.({
+        evt: 'cli.suite.run.complete',
+        suite: suite.name,
+        suiteRunId,
+        exitCode,
+        durationMs,
+    });
+    return {
+        type: 'suite-run',
+        suite: suite.name,
+        suiteRunId,
+        exitCode,
+        durationMs,
+        steps,
+    };
+}
+async function runStepsSerially(args) {
+    const summaries = [];
+    let chain = Promise.resolve();
+    for (const step of args.suite.steps) {
+        chain = chain.then(async () => {
+            summaries.push(await runStep({
+                suite: args.suite,
+                suiteRunId: args.suiteRunId,
+                step,
+                ctx: args.ctx,
+                suiteOpts: args.suiteOpts,
+            }));
+        });
+    }
+    await chain;
+    return summaries;
+}
+async function runStep(args) {
+    const started = performance.now();
+    const bound = bindToolCliContext(args.step.tool, args.ctx);
+    const capture = createCapturingContext(bound);
+    // ADR-0054 out-of-process dispatch must run through the CAPTURING context, not
+    // the raw bound ctx. For an external-provenance step the worker replay
+    // (`replayResult`) calls `ctx.setExitCode` with the tool's verdict exit code;
+    // binding the hook to `capture.context` routes that into the capture's exit slot
+    // (`capture.getExitCode()`) so the external step participates in the suite
+    // worst-of aggregation exactly like the in-process handler (which already runs
+    // against `capture.context`). Binding to `bound` instead dropped the external
+    // step's exit code (it never reached the slot, so a findings/regression verdict
+    // silently aggregated to 0) AND leaked the code into the outer host context — the
+    // same isolation the bundled path preserves. (04↔05 regression: external adapter
+    // as a suite step.)
+    Object.assign(capture.context, {
+        maybeDispatchExternal: buildMaybeDispatchExternal(args.step.tool, capture.context),
+    });
+    const opts = stepOpts(args.step, args.suiteOpts);
+    const hooks = capture.context;
+    const diagnostics = currentScope()?.diagnostics;
+    const log = currentLogger();
+    let errorMessage;
+    let exitCode = EXIT_CODES.SUCCESS;
+    try {
+        diagnostics?.event('execute', 'debug', `suite step '${args.step.spec.name}' started`, {
+            suite: args.suite.name,
+            suiteRunId: args.suiteRunId,
+            tool: args.step.tool.metadata.id,
+            command: args.step.spec.name,
+        });
+        exitCode = await withProcessExitGuard(async () => {
+            hooks.resetRun?.();
+            hooks.beginRun?.();
+            const dispatched = await hooks.maybeDispatchExternal?.(args.step.spec.name, opts, args.step.positionals);
+            if (dispatched === true)
+                return capture.getExitCode() ?? EXIT_CODES.SUCCESS;
+            const result = await args.step.spec.handler(opts, capture.context);
+            hooks.completeRun?.(result);
+            await dispatchOutput(result, args.step.spec, opts, args.step.positionals, capture.context);
+            return capture.getExitCode() ?? EXIT_CODES.SUCCESS;
+        }, (code) => {
+            // A bundled step called `process.exit(code)` directly: route the code into
+            // the capture's last-write-wins slot (the single per-step exit source of
+            // truth) just as `setExitCode` would, then record it.
+            capture.context.setExitCode(code);
+            log.warn?.({
+                evt: 'cli.suite.run.step',
+                suite: args.suite.name,
+                suiteRunId: args.suiteRunId,
+                tool: args.step.tool.metadata.id,
+                command: args.step.spec.name,
+                exitCode: code,
+                msg: 'Bundled step called process.exit directly; captured as step verdict.',
+            });
+        });
+        diagnostics?.event('execute', 'debug', `suite step '${args.step.spec.name}' completed`, {
+            suite: args.suite.name,
+            suiteRunId: args.suiteRunId,
+            tool: args.step.tool.metadata.id,
+            command: args.step.spec.name,
+            exitCode,
+        });
+        diagnostics?.counter('suite.steps.completed', 1);
+        // @fitness-ignore-next-line exit-code-correctness -- suite steps convert thrown step failures into a non-zero step summary; runSuite later returns the max step exit code.
+    }
+    catch (error) {
+        exitCode = EXIT_CODES.RUNTIME_ERROR;
+        errorMessage = error instanceof Error ? error.message : String(error);
+        diagnostics?.event('execute', 'error', `suite step '${args.step.spec.name}' failed`, {
+            suite: args.suite.name,
+            suiteRunId: args.suiteRunId,
+            tool: args.step.tool.metadata.id,
+            command: args.step.spec.name,
+            exitCode,
+            error: errorMessage,
+        });
+        log.error?.({
+            evt: 'cli.suite.run.step.error',
+            suite: args.suite.name,
+            suiteRunId: args.suiteRunId,
+            tool: args.step.tool.metadata.id,
+            command: args.step.spec.name,
+            error: errorMessage,
+        });
+    }
+    const durationMs = Math.max(0, performance.now() - started);
+    log.info?.({
+        evt: 'cli.suite.run.step',
+        suite: args.suite.name,
+        suiteRunId: args.suiteRunId,
+        tool: args.step.tool.metadata.id,
+        command: args.step.spec.name,
+        exitCode,
+        durationMs,
+    });
+    return {
+        tool: args.step.tool.metadata.name,
+        stableId: args.step.tool.metadata.id,
+        command: args.step.spec.name,
+        exitCode,
+        durationMs,
+        ...(errorMessage === undefined ? {} : { error: errorMessage }),
+    };
+}
+function stepOpts(step, suiteOpts) {
+    const assembled = assembleOptsFromSpec({
+        options: step.spec.options,
+        suppliedValues: step.args,
+    }).opts;
+    const common = {};
+    for (const key of step.spec.commonFlags) {
+        const value = suiteOpts[key];
+        if (value !== undefined)
+            common[key] = value;
+    }
+    if (step.spec.commonFlags.includes('cwd') && common.cwd === undefined) {
+        common.cwd = process.cwd();
+    }
+    return { ...common, ...assembled, _args: step.positionals };
+}
+async function withProcessExitGuard(fn, onDirectExit) {
+    // eslint-disable-next-line @typescript-eslint/unbound-method -- process.exit has no `this` contract; identity must be restored after the guard.
+    const original = process.exit;
+    // @fitness-ignore-next-line throws-documentation -- this private guard intentionally throws a sentinel so direct process.exit calls become suite step exit codes.
+    process.exit = (code) => {
+        throw new DirectProcessExit(typeof code === 'number' ? code : 0);
+    };
+    try {
+        return await fn();
+    }
+    catch (error) {
+        if (error instanceof DirectProcessExit) {
+            onDirectExit(error.code);
+            return error.code;
+        }
+        throw error;
+    }
+    finally {
+        process.exit = original;
+    }
+}
+//# sourceMappingURL=orchestrator.js.map

package/dist/commands/suite/orchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.js","sourceRoot":"","sources":["../../../src/commands/suite/orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EACL,aAAa,EACb,YAAY,EACZ,kBAAkB,GAGnB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,0BAA0B,EAAE,MAAM,2CAA2C,CAAC;AACvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC1E,OAAO,EAAE,sBAAsB,EAAuB,MAAM,8BAA8B,CAAC;AAC3F,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAgD,MAAM,qBAAqB,CAAC;AAKlG,MAAM,iBAAkB,SAAQ,KAAK;IACd;IAArB,YAAqB,IAAY;QAC/B,KAAK,CAAC,gBAAgB,IAAI,GAAG,CAAC,CAAC;QADZ,SAAI,GAAJ,IAAI,CAAQ;IAEjC,CAAC;CACF;AAUD,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,KAAoB;IACjD,MAAM,KAAK,GAAG,aAAa,CAAC;QAC1B,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,KAAK,EAAE,KAAK,CAAC,KAAK;KACnB,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC/C,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAClC,MAAM,GAAG,GAAG,aAAa,EAAE,CAAC;IAE5B,GAAG,CAAC,IAAI,EAAE,CAAC;QACT,GAAG,EAAE,qBAAqB;QAC1B,KAAK,EAAE,KAAK,CAAC,IAAI;QACjB,UAAU;QACV,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM;KAC9B,CAAC,CAAC;IAEH,MAAM,KAAK,GAAG,MAAM,sBAAsB,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,CACrF,gBAAgB,CAAC;QACf,KAAK;QACL,UAAU;QACV,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,SAAS,EAAE,KAAK,CAAC,SAAS;KAC3B,CAAC,CACH,CAAC;IACF,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IACpE,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC;IAE5D,GAAG,CAAC,IAAI,EAAE,CAAC;QACT,GAAG,EAAE,wBAAwB;QAC7B,KAAK,EAAE,KAAK,CAAC,IAAI;QACjB,UAAU;QACV,QAAQ;QACR,UAAU;KACX,CAAC,CAAC;IAEH,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,KAAK,CAAC,IAAI;QACjB,UAAU;QACV,QAAQ;QACR,UAAU;QACV,KAAK;KACN,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,gBAAgB,CAAC,IAK/B;IACC,MAAM,SAAS,GAAuB,EAAE,CAAC;IACzC,IAAI,KAAK,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAE9B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACpC,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE;YAC5B,SAAS,CAAC,IAAI,CACZ,MAAM,OAAO,CAAC;gBACZ,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,IAAI;gBACJ,GAAG,EAAE,IAAI,CAAC,GAAG;gBACb,SAAS,EAAE,IAAI,CAAC,SAAS;aAC1B,CAAC,CACH,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,KAAK,CAAC;IACZ,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,KAAK,UAAU,OAAO,CAAC,IAMtB;IACC,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAClC,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3D,MAAM,OAAO,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;IAC9C,+EAA+E;IAC/E,uEAAuE;IACvE,8EAA8E;IAC9E,iFAAiF;IACjF,2EAA2E;IAC3E,+EAA+E;IAC/E,8EAA8E;IAC9E,gFAAgF;IAChF,kFAAkF;IAClF,iFAAiF;IACjF,oBAAoB;IACpB,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE;QAC7B,qBAAqB,EAAE,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC;KACnF,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,OAAO,CAAC,OAA0C,CAAC;IACjE,MAAM,WAAW,GAAG,YAAY,EAAE,EAAE,WAAW,CAAC;IAChD,MAAM,GAAG,GAAG,aAAa,EAAE,CAAC;IAC5B,IAAI,YAAgC,CAAC;IACrC,IAAI,QAAQ,GAAW,UAAU,CAAC,OAAO,CAAC;IAC1C,IAAI,CAAC;QACH,WAAW,EAAE,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,eAAe,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,WAAW,EAAE;YACpF,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;YACtB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE;YAChC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;SAC7B,CAAC,CAAC;QACH,QAAQ,GAAG,MAAM,oBAAoB,CACnC,KAAK,IAAI,EAAE;YACT,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC;YACnB,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC;YACnB,MAAM,UAAU,GAAG,MAAM,KAAK,CAAC,qBAAqB,EAAE,CACpD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EACnB,IAAI,EACJ,IAAI,CAAC,IAAI,CAAC,WAAW,CACtB,CAAC;YACF,IAAI,UAAU,KAAK,IAAI;gBAAE,OAAO,OAAO,CAAC,WAAW,EAAE,IAAI,UAAU,CAAC,OAAO,CAAC;YAC5E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;YACnE,KAAK,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC;YAC5B,MAAM,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;YAC3F,OAAO,OAAO,CAAC,WAAW,EAAE,IAAI,UAAU,CAAC,OAAO,CAAC;QACrD,CAAC,EACD,CAAC,IAAI,EAAE,EAAE;YACP,2EAA2E;YAC3E,yEAAyE;YACzE,sDAAsD;YACtD,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;YAClC,GAAG,CAAC,IAAI,EAAE,CAAC;gBACT,GAAG,EAAE,oBAAoB;gBACzB,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;gBACtB,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE;gBAChC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;gBAC5B,QAAQ,EAAE,IAAI;gBACd,GAAG,EAAE,sEAAsE;aAC5E,CAAC,CAAC;QACL,CAAC,CACF,CAAC;QACF,WAAW,EAAE,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,eAAe,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,aAAa,EAAE;YACtF,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;YACtB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE;YAChC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YAC5B,QAAQ;SACT,CAAC,CAAC;QACH,WAAW,EAAE,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC,CAAC;QACjD,2KAA2K;IAC7K,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,QAAQ,GAAG,UAAU,CAAC,aAAa,CAAC;QACpC,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,WAAW,EAAE,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,eAAe,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,UAAU,EAAE;YACnF,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;YACtB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE;YAChC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YAC5B,QAAQ;YACR,KAAK,EAAE,YAAY;SACpB,CAAC,CAAC;QACH,GAAG,CAAC,KAAK,EAAE,CAAC;YACV,GAAG,EAAE,0BAA0B;YAC/B,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;YACtB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE;YAChC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YAC5B,KAAK,EAAE,YAAY;SACpB,CAAC,CAAC;IACL,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC;IAE5D,GAAG,CAAC,IAAI,EAAE,CAAC;QACT,GAAG,EAAE,oBAAoB;QACzB,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;QACtB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE;QAChC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QAC5B,QAAQ;QACR,UAAU;KACX,CAAC,CAAC;IAEH,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI;QAClC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE;QACpC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QAC5B,QAAQ;QACR,UAAU;QACV,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;KAC/D,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CACf,IAAwB,EACxB,SAA4C;IAE5C,MAAM,SAAS,GAAG,oBAAoB,CAAC;QACrC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO;QAC1B,cAAc,EAAE,IAAI,CAAC,IAAI;KAC1B,CAAC,CAAC,IAAI,CAAC;IACR,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QACxC,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC/C,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QACtE,MAAM,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAC7B,CAAC;IACD,OAAO,EAAE,GAAG,MAAM,EAAE,GAAG,SAAS,EAAE,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;AAC9D,CAAC;AAED,KAAK,UAAU,oBAAoB,CACjC,EAAyB,EACzB,YAAoC;IAEpC,gJAAgJ;IAChJ,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAC9B,kKAAkK;IACjK,OAAyD,CAAC,IAAI,GAAG,CAAC,IAAa,EAAE,EAAE;QAClF,MAAM,IAAI,iBAAiB,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE,CAAC,CAAC;IACF,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,iBAAiB,EAAE,CAAC;YACvC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACzB,OAAO,KAAK,CAAC,IAAI,CAAC;QACpB,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;YAAS,CAAC;QACR,OAAoD,CAAC,IAAI,GAAG,QAAQ,CAAC;IACxE,CAAC;AACH,CAAC"}

package/dist/commands/suite/suite-add.d.ts

@@ -0,0 +1,18 @@
+import { type Tool } from '@opensip-cli/core';
+export interface SuiteAddInput {
+    readonly suite: string;
+    readonly tool: string;
+    readonly command: string;
+    readonly argPairs: readonly string[];
+    readonly tools: readonly Tool[];
+    readonly projectRoot: string;
+    readonly configPath?: string;
+}
+export interface SuiteAddOutput {
+    readonly configPath: string;
+    readonly changed: boolean;
+    readonly tool: Tool;
+    readonly args: Readonly<Record<string, unknown>>;
+}
+export declare function addSuiteStep(input: SuiteAddInput): SuiteAddOutput;
+//# sourceMappingURL=suite-add.d.ts.map

package/dist/commands/suite/suite-add.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suite-add.d.ts","sourceRoot":"","sources":["../../../src/commands/suite/suite-add.ts"],"names":[],"mappings":"AAIA,OAAO,EAAqC,KAAK,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAKjF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAClD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc,CAkBjE"}

package/dist/commands/suite/suite-add.js

@@ -0,0 +1,130 @@
+// @fitness-ignore-file dogfood-one-config-document-ratchet -- `suite add` is the host-owned config authoring command: it intentionally edits opensip-cli.config.yml and does not participate in runtime config loading.
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ConfigurationError, currentLogger } from '@opensip-cli/core';
+import { isMap, isSeq, parseDocument } from 'yaml';
+const MAX_EDITABLE_CONFIG_BYTES = 1_000_000;
+export function addSuiteStep(input) {
+    const tool = resolveTool(input.tool, input.tools);
+    const command = tool.commandSpecs?.find((spec) => spec.name === input.command);
+    if (command === undefined) {
+        throw new ConfigurationError(`Tool '${tool.metadata.name}' has no command '${input.command}'.`, { code: 'CONFIG.SUITE_ADD.UNKNOWN_COMMAND' });
+    }
+    const configPath = input.configPath ?? join(input.projectRoot, 'opensip-cli.config.yml');
+    const args = parseArgPairs(input.argPairs);
+    const changed = appendSuiteStep(configPath, input.suite, {
+        tool: tool.metadata.id,
+        name: tool.metadata.name,
+        command: command.name,
+        ...(Object.keys(args).length === 0 ? {} : { args }),
+    });
+    return { configPath, changed, tool, args };
+}
+function resolveTool(selector, tools) {
+    const matches = tools.filter((tool) => tool.metadata.id === selector || tool.metadata.name === selector);
+    if (matches.length === 1) {
+        const [match] = matches;
+        if (match !== undefined)
+            return match;
+    }
+    if (matches.length > 1) {
+        throw new ConfigurationError(`Tool selector '${selector}' matched multiple tools. Use a UUID.`, {
+            code: 'CONFIG.SUITE_ADD.AMBIGUOUS_TOOL',
+        });
+    }
+    throw new ConfigurationError(`Unknown tool '${selector}'.`, {
+        code: 'CONFIG.SUITE_ADD.UNKNOWN_TOOL',
+    });
+}
+function parseArgPairs(pairs) {
+    const args = {};
+    for (const pair of pairs) {
+        const eq = pair.indexOf('=');
+        if (eq <= 0) {
+            throw new ConfigurationError(`Invalid --arg '${pair}'. Expected key=value.`, {
+                code: 'CONFIG.SUITE_ADD.INVALID_ARG',
+            });
+        }
+        args[pair.slice(0, eq)] = parseScalar(pair.slice(eq + 1));
+    }
+    return args;
+}
+function parseScalar(raw) {
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    if (/^-?\d+(\.\d+)?$/.test(raw))
+        return Number(raw);
+    return raw;
+}
+function appendSuiteStep(configPath, suiteName, step) {
+    const doc = readOrCreateDocument(configPath);
+    const root = ensureRootMap(doc, configPath);
+    let suites = root.get('suites');
+    if (!isMap(suites)) {
+        suites = doc.createNode({});
+        root.set('suites', suites);
+    }
+    const suitesMap = suites;
+    let suite = suitesMap.get(suiteName);
+    if (!isMap(suite)) {
+        suite = doc.createNode({ steps: [] });
+        suitesMap.set(suiteName, suite);
+    }
+    const suiteMap = suite;
+    let seq = suiteMap.get('steps');
+    if (seq === undefined) {
+        seq = doc.createNode([]);
+        suiteMap.set('steps', seq);
+    }
+    if (!isSeq(seq)) {
+        throw new ConfigurationError(`Cannot edit suites.${suiteName}.steps in ${configPath}.`, {
+            code: 'CONFIG.SUITE_ADD.INVALID_STEPS',
+        });
+    }
+    const yamlSeq = seq;
+    const stepKey = JSON.stringify(step);
+    if (yamlSeq.items.some((item) => JSON.stringify(yamlNodeToJson(item)) === stepKey)) {
+        currentLogger().info?.({
+            evt: 'cli.suite.add.duplicate_step',
+            suite: suiteName,
+            configPath,
+            msg: 'Suite step already exists; leaving config unchanged.',
+        });
+        return false;
+    }
+    yamlSeq.add(step);
+    writeFileSync(configPath, doc.toString(), 'utf8');
+    return true;
+}
+function yamlNodeToJson(item) {
+    if (item && typeof item === 'object' && 'toJSON' in item) {
+        return item.toJSON();
+    }
+    return item;
+}
+function readOrCreateDocument(configPath) {
+    if (!existsSync(configPath))
+        return parseDocument('');
+    const stat = statSync(configPath);
+    if (stat.size > MAX_EDITABLE_CONFIG_BYTES) {
+        throw new ConfigurationError(`Cannot edit ${configPath}: file is larger than ${MAX_EDITABLE_CONFIG_BYTES} bytes.`, { code: 'CONFIG.SUITE_ADD.CONFIG_TOO_LARGE' });
+    }
+    const doc = parseDocument(readFileSync(configPath, 'utf8'));
+    if (doc.errors.length > 0) {
+        const first = doc.errors[0]?.message ?? 'unknown YAML error';
+        throw new ConfigurationError(`Cannot edit ${configPath}: ${first}.`, {
+            code: 'CONFIG.SUITE_ADD.MALFORMED_YAML',
+        });
+    }
+    return doc;
+}
+function ensureRootMap(doc, configPath) {
+    doc.contents ??= doc.createNode({});
+    if (!isMap(doc.contents)) {
+        throw new ConfigurationError(`Cannot edit ${configPath}: opensip-cli.config.yml must start with a YAML map.`, { code: 'CONFIG.SUITE_ADD.NON_MAP_CONFIG' });
+    }
+    return doc.contents;
+}
+//# sourceMappingURL=suite-add.js.map

package/dist/commands/suite/suite-add.js.map

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

package/dist/commands/suite/suite-command-specs.d.ts

@@ -0,0 +1,4 @@
+import { type HostSpec } from '../host-subcommand-shared.js';
+import type { CliCommandsContext } from '../shared.js';
+export declare function buildSuiteGroupLeaves(ctx: CliCommandsContext): readonly HostSpec[];
+//# sourceMappingURL=suite-command-specs.d.ts.map

package/dist/commands/suite/suite-command-specs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suite-command-specs.d.ts","sourceRoot":"","sources":["../../../src/commands/suite/suite-command-specs.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,QAAQ,EACd,MAAM,8BAA8B,CAAC;AAMtC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AA0JvD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,kBAAkB,GAAG,SAAS,QAAQ,EAAE,CAElF"}

package/dist/commands/suite/suite-command-specs.js

@@ -0,0 +1,150 @@
+import { suitesConfigSchema } from '@opensip-cli/config';
+import { EXIT_CODES } from '@opensip-cli/contracts';
+import { currentScope } from '@opensip-cli/core';
+import { COMMAND_RESULT, defineCommand, PROJECT_SCOPE, } from '../host-subcommand-shared.js';
+import { runSuite } from './orchestrator.js';
+import { addSuiteStep } from './suite-add.js';
+import { validateSuite } from './validate-suite.js';
+function configuredSuites() {
+    return suitesConfigSchema.parse(currentScope()?.configDocument?.suites ?? {});
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function parseArg(raw, previous) {
+    return [...(isStringArray(previous) ? previous : []), raw];
+}
+function buildSuiteRunSpec(ctx) {
+    return defineCommand({
+        name: 'run',
+        description: 'Run a configured suite in one shared project scope',
+        commonFlags: ['cwd', 'json', 'quiet', 'verbose', 'debug', 'reportTo', 'apiKey', 'open'],
+        args: [{ name: 'name', description: 'Configured suite name' }],
+        scope: PROJECT_SCOPE,
+        output: COMMAND_RESULT,
+        handler: async (rawOpts) => {
+            if (ctx.toolContext === undefined) {
+                ctx.setExitCode(EXIT_CODES.CONFIGURATION_ERROR);
+                return {
+                    type: 'error',
+                    message: 'suite run requires the full ToolCliContext handle.',
+                    exitCode: EXIT_CODES.CONFIGURATION_ERROR,
+                };
+            }
+            const opts = rawOpts;
+            const name = String(opts._args?.[0] ?? '');
+            const suite = configuredSuites()[name];
+            if (suite === undefined) {
+                ctx.setExitCode(EXIT_CODES.CONFIGURATION_ERROR);
+                return {
+                    type: 'error',
+                    message: `Unknown suite '${name}'.`,
+                    exitCode: EXIT_CODES.CONFIGURATION_ERROR,
+                };
+            }
+            const result = await runSuite({
+                name,
+                suite,
+                tools: currentScope()?.tools.list() ?? [],
+                ctx: ctx.toolContext,
+                suiteOpts: opts,
+            });
+            ctx.setExitCode(result.exitCode);
+            return result;
+        },
+    });
+}
+function buildSuiteListSpec() {
+    return defineCommand({
+        name: 'list',
+        description: 'List configured suites and their resolved steps',
+        commonFlags: ['json'],
+        scope: PROJECT_SCOPE,
+        output: COMMAND_RESULT,
+        handler: () => {
+            const tools = currentScope()?.tools.list() ?? [];
+            const suites = configuredSuites();
+            const result = {
+                type: 'suite-list',
+                totalCount: Object.keys(suites).length,
+                suites: Object.entries(suites).map(([name, suite]) => {
+                    const validated = validateSuite({ name, suite, tools });
+                    return {
+                        name,
+                        ...(suite.description === undefined ? {} : { description: suite.description }),
+                        steps: validated.steps.map((step) => ({
+                            tool: step.tool.metadata.name,
+                            stableId: step.tool.metadata.id,
+                            command: step.spec.name,
+                            args: step.args,
+                        })),
+                    };
+                }),
+            };
+            return Promise.resolve(result);
+        },
+    });
+}
+function buildSuiteAddSpec(ctx) {
+    return defineCommand({
+        name: 'add',
+        description: 'Add a tool command step to a configured suite',
+        commonFlags: ['json', 'cwd'],
+        args: [{ name: 'name', description: 'Suite name' }],
+        options: [
+            {
+                flag: '--tool',
+                value: '<name-or-uuid>',
+                description: 'Tool name or stable UUID',
+                required: true,
+            },
+            {
+                flag: '--command',
+                value: '<name>',
+                description: 'Tool command name',
+                required: true,
+            },
+            {
+                flag: '--arg',
+                value: '<key=value>',
+                description: 'Tool option value to write into the suite step',
+                variadic: true,
+                arrayDefault: [],
+                parse: parseArg,
+            },
+        ],
+        scope: PROJECT_SCOPE,
+        output: COMMAND_RESULT,
+        handler: (rawOpts) => {
+            const scope = currentScope();
+            const opts = rawOpts;
+            const suite = String(opts._args?.[0] ?? '');
+            const project = scope?.projectContext;
+            const output = addSuiteStep({
+                suite,
+                tool: opts.tool ?? '',
+                command: opts.command ?? '',
+                argPairs: opts.arg ?? [],
+                tools: scope?.tools.list() ?? [],
+                projectRoot: project?.projectRoot ?? process.cwd(),
+                configPath: project?.configPath,
+            });
+            const result = {
+                type: 'suite-add',
+                suite,
+                tool: output.tool.metadata.name,
+                stableId: output.tool.metadata.id,
+                command: opts.command ?? '',
+                configPath: output.configPath,
+                changed: output.changed,
+            };
+            if (!output.changed)
+                ctx.setExitCode(EXIT_CODES.SUCCESS);
+            return result;
+        },
+    });
+}
+export function buildSuiteGroupLeaves(ctx) {
+    return [buildSuiteRunSpec(ctx), buildSuiteListSpec(), buildSuiteAddSpec(ctx)];
+}
+//# sourceMappingURL=suite-command-specs.js.map

package/dist/commands/suite/suite-command-specs.js.map

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

package/dist/commands/suite/validate-suite.d.ts

@@ -0,0 +1,21 @@
+import { type CommandSpec, type Tool, type ToolCliContext } from '@opensip-cli/core';
+import type { SuiteDefinition, SuiteStep } from '@opensip-cli/config';
+export interface ValidatedSuiteStep {
+    readonly index: number;
+    readonly tool: Tool;
+    readonly spec: CommandSpec<unknown, ToolCliContext>;
+    readonly config: SuiteStep;
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly positionals: readonly unknown[];
+}
+export interface ValidatedSuite {
+    readonly name: string;
+    readonly description?: string;
+    readonly steps: readonly ValidatedSuiteStep[];
+}
+export declare function validateSuite(args: {
+    readonly name: string;
+    readonly suite: SuiteDefinition;
+    readonly tools: readonly Tool[];
+}): ValidatedSuite;
+//# sourceMappingURL=validate-suite.d.ts.map

package/dist/commands/suite/validate-suite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-suite.d.ts","sourceRoot":"","sources":["../../../src/commands/suite/validate-suite.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,IAAI,EACT,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAI3B,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAgBtE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,QAAQ,CAAC,WAAW,EAAE,SAAS,OAAO,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC/C;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;CACjC,GAAG,cAAc,CAuBjB"}