tubeless 0.1.0

package/dist/child-execution.js

@@ -0,0 +1,270 @@
+import { throwIfAborted } from "./abort.js";
+import { runConcurrent } from "./batch.js";
+import { toMappedChildStepProgress, } from "./mapped-child-progress.js";
+import { hasVisibleStepProgress } from "./progress.js";
+import { createRunId, RUN_MODEL_VERSION, } from "./pipeline.js";
+export class PipelineChildError extends Error {
+    cancelled;
+    constructor(message, cancelled = false, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.cancelled = cancelled;
+        this.name = "PipelineChildError";
+    }
+}
+function childTracingOptions(context, itemKey = context.trace?.itemKey) {
+    return context.tracing ? { ...context.tracing, itemKey } : undefined;
+}
+function duplicateValues(values) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const value of values) {
+        if (seen.has(value))
+            duplicates.add(value);
+        seen.add(value);
+    }
+    return [...duplicates];
+}
+function childRunOptions(options, dryRun) {
+    return { ...options, dryRun };
+}
+function childRunControls(options) {
+    return {
+        continueOnError: options.continueOnError,
+        dryRun: options.dryRun,
+        stepIds: options.stepIds,
+        targets: options.targets,
+    };
+}
+function isConcurrencyFunction(concurrency) {
+    return typeof concurrency === "function";
+}
+function failedPlanRun(pipeline, options, context, errors) {
+    const now = context.now ?? Date.now;
+    const startedAtMs = now();
+    const result = {
+        pipelineId: pipeline.id,
+        dryRun: options.dryRun === true,
+        errors: [...errors],
+        finalized: false,
+        finishedAtMs: now(),
+        runId: context.runId ?? createRunId(pipeline.id),
+        startedAtMs,
+        status: "failed",
+        steps: [],
+        version: RUN_MODEL_VERSION,
+    };
+    if (context.parentRunId)
+        result.parentRunId = context.parentRunId;
+    return result;
+}
+function firstChildFailure(result) {
+    const firstFailedStep = result.steps.find(({ status }) => status === "failed" || status === "cancelled");
+    const firstError = firstFailedStep && "error" in firstFailedStep ? firstFailedStep.error : result.errors[0];
+    return {
+        failureLocation: firstFailedStep?.id ?? firstError?.stepId ?? "unknown step",
+        message: firstError?.message ?? "unknown error",
+    };
+}
+async function runChildPipeline(pipeline, options, context, hooks, dependencies, messagePrefix = "") {
+    const plan = pipeline.plan(childRunControls(options));
+    if (!plan.ok) {
+        const firstError = plan.errors[0];
+        const result = failedPlanRun(pipeline, options, context, plan.errors);
+        throw dependencies.createExecutionError(result, `${messagePrefix}could not start: ${firstError?.message ?? "invalid plan"}`);
+    }
+    const result = await pipeline.run(options, { ...context, hooks });
+    if (result.status !== "completed") {
+        const { failureLocation, message } = firstChildFailure(result);
+        throw dependencies.createExecutionError(result, `${messagePrefix}failed at ${failureLocation}: ${message}`);
+    }
+    return result;
+}
+export function createSingleChildRunner(config, dependencies) {
+    return async (inputs, context) => {
+        const childOptions = childRunOptions(config.mapOptions(inputs, context), context.dryRun);
+        const baseChildContext = {
+            cwd: context.cwd,
+            log: context.log,
+            now: context.now,
+            parentRunId: context.runId,
+            signal: context.signal,
+            sleep: context.sleep,
+            tracing: childTracingOptions(context),
+        };
+        // Preview plan only for progress totals; invalid plans throw from runChildPipeline.
+        const childPlan = config.pipeline.plan(childRunControls(childOptions));
+        const selectedStepCount = childPlan.ok
+            ? childPlan.steps.filter((step) => step.selected).length
+            : 0;
+        const terminalSteps = new Set();
+        const report = (step, message, terminal = false) => {
+            if (terminal)
+                terminalSteps.add(step.id);
+            context.reportProgress({
+                completed: terminalSteps.size,
+                total: Math.max(1, selectedStepCount),
+                message: `${config.pipeline.id}/${step.name ?? step.id}: ${message}`,
+            });
+        };
+        const childHooks = {
+            onStepStart: ({ step }) => report(step, "started"),
+            onStepProgress: ({ progress, step }) => {
+                if (!hasVisibleStepProgress(progress))
+                    return;
+                report(step, progress.message ?? `${progress.completed} completed`);
+            },
+            onStepComplete: ({ step }) => report(step, "complete", true),
+            onStepSkip: ({ reason, step }) => report(step, `skipped: ${reason}`, reason !== "filtered"),
+            onStepCancel: ({ error, step }) => report(step, `cancelled: ${error.message}`, true),
+            onStepFail: ({ error, step }) => report(step, `failed: ${error.message}`, true),
+        };
+        const childResult = await runChildPipeline(config.pipeline, childOptions, baseChildContext, childHooks, dependencies, `Child pipeline ${config.pipeline.id} `);
+        return config.mapResult
+            ? config.mapResult(childResult.value, childResult, context)
+            : childResult.value;
+    };
+}
+export function createMappedChildRunner(config, dependencies) {
+    return async (inputs, context) => {
+        const items = [...(await config.items(inputs, context))];
+        const keys = items.map((item, index) => config.key(item, index));
+        const duplicateKeys = duplicateValues(keys);
+        if (duplicateKeys.length > 0) {
+            throw new PipelineChildError(`Mapped child pipeline ${config.pipeline.id} received duplicate item keys: ${duplicateKeys.join(", ")}`);
+        }
+        const concurrency = Math.max(1, isConcurrencyFunction(config.concurrency)
+            ? config.concurrency(inputs, context)
+            : (config.concurrency ?? 1));
+        const active = new Map();
+        const childTerminalSteps = new Map();
+        let finishedItems = 0;
+        let failedItems = 0;
+        let stepsPerItem = 0;
+        let plannedChildSteps = 0;
+        let plannedItems = 0;
+        let terminalChildSteps = 0;
+        const publishProgress = (spotlight) => {
+            const snapshot = {
+                active,
+                concurrency,
+                failedItems,
+                finishedItems,
+                itemCount: items.length,
+                plannedChildSteps,
+                plannedItems,
+                stepsPerItem,
+                terminalChildSteps,
+                spotlight,
+            };
+            context.reportProgress(toMappedChildStepProgress(snapshot, config.progress));
+        };
+        const markChildTerminal = (itemKey, stepId, label) => {
+            let seen = childTerminalSteps.get(itemKey);
+            if (!seen) {
+                seen = new Set();
+                childTerminalSteps.set(itemKey, seen);
+            }
+            if (!seen.has(stepId)) {
+                seen.add(stepId);
+                terminalChildSteps += 1;
+            }
+            active.set(itemKey, label);
+            publishProgress();
+        };
+        if (items.length === 0) {
+            publishProgress();
+            return [];
+        }
+        publishProgress();
+        const outcomes = await runConcurrent(items, { concurrency, signal: context.signal }, async (item, itemIndex) => {
+            const key = keys[itemIndex];
+            active.set(key, "starting");
+            publishProgress();
+            try {
+                throwIfAborted(context.signal, `Mapped child pipeline ${config.pipeline.id}`);
+                const childOptions = childRunOptions(config.mapOptions(item, itemIndex, inputs, context), context.dryRun);
+                // Preview plan for live fan-out progress; invalid plans throw from runChildPipeline.
+                const childPlan = config.pipeline.plan(childRunControls(childOptions));
+                if (childPlan.ok) {
+                    const plannedSteps = childPlan.steps.filter((step) => step.selected).length;
+                    plannedChildSteps += plannedSteps;
+                    plannedItems += 1;
+                    if (plannedSteps > stepsPerItem)
+                        stepsPerItem = plannedSteps;
+                }
+                const childHooks = {
+                    onStepStart: ({ step }) => {
+                        active.set(key, step.name ?? step.id);
+                        publishProgress();
+                    },
+                    onStepProgress: ({ progress, step }) => {
+                        if (!hasVisibleStepProgress(progress))
+                            return;
+                        const detail = progress.message ??
+                            (progress.total !== undefined
+                                ? `${progress.completed}/${progress.total}`
+                                : `${progress.completed}`);
+                        active.set(key, `${step.name ?? step.id}:${detail}`);
+                        publishProgress();
+                    },
+                    onStepComplete: ({ step }) => markChildTerminal(key, step.id, `${step.name ?? step.id}:complete`),
+                    onStepSkip: ({ reason, step }) => {
+                        if (reason === "filtered")
+                            return;
+                        markChildTerminal(key, step.id, `${step.name ?? step.id}:skipped:${reason}`);
+                    },
+                    onStepCancel: ({ step }) => markChildTerminal(key, step.id, `${step.name ?? step.id}:cancelled`),
+                    onStepFail: ({ step }) => markChildTerminal(key, step.id, `${step.name ?? step.id}:failed`),
+                };
+                const childResult = await runChildPipeline(config.pipeline, childOptions, {
+                    cwd: context.cwd,
+                    log: context.log,
+                    now: context.now,
+                    parentRunId: context.runId,
+                    signal: context.signal,
+                    sleep: context.sleep,
+                    tracing: childTracingOptions(context, key),
+                }, childHooks, dependencies);
+                const seen = childTerminalSteps.get(key) ?? new Set();
+                if (childPlan.ok) {
+                    for (const planStep of childPlan.steps) {
+                        if (!planStep.selected || seen.has(planStep.id))
+                            continue;
+                        seen.add(planStep.id);
+                        terminalChildSteps += 1;
+                    }
+                }
+                childTerminalSteps.set(key, seen);
+                const value = config.mapResult
+                    ? config.mapResult(childResult.value, childResult, item, itemIndex, context)
+                    : childResult.value;
+                active.delete(key);
+                finishedItems += 1;
+                publishProgress(`${key}: completed`);
+                return { key, ok: true, value };
+            }
+            catch (error) {
+                const cause = error instanceof Error ? error : new Error(String(error));
+                active.delete(key);
+                failedItems += 1;
+                publishProgress(`${key}: failed`);
+                return { error: cause, key, ok: false };
+            }
+        });
+        const failures = outcomes.filter((outcome) => !outcome.ok);
+        if (failures.length > 0) {
+            const details = failures.map(({ error, key }) => `${key}: ${error.message}`).join("; ");
+            const cancelled = failures.every(({ error }) => dependencies.isCancellation(error, context));
+            const primaryFailure = cancelled
+                ? failures[0]
+                : (failures.find(({ error }) => !dependencies.isCancellation(error, context)) ??
+                    failures[0]);
+            throw new PipelineChildError(`Mapped child pipeline ${config.pipeline.id} failed for ${failures.length} item(s): ${details}`, cancelled, primaryFailure?.error);
+        }
+        // SAFETY: when failures.length === 0 every outcome was produced by the
+        // success branch (return { key, ok: true, value }), so each outcome is
+        // necessarily `{ ok: true }`; the assertion narrows the union accordingly.
+        return outcomes.map((outcome) => outcome.value);
+    };
+}
+//# sourceMappingURL=child-execution.js.map

package/dist/child-execution.js.map

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

package/dist/cli-command.d.ts

@@ -0,0 +1,29 @@
+import { type CheckpointStore } from "./checkpoint.js";
+import { type CliCommand, type CliCommandConfig, type CliContext, type CliParams, type CliParamsSchema } from "./cli-types.js";
+export declare function resolveContext(overrides?: Partial<CliContext>): CliContext;
+interface ManagedMainSignal {
+    context: CliContext;
+    wasInterrupted(): boolean;
+    cleanup(): void;
+}
+/**
+ * Give real CLI entrypoints graceful cancellation without making `run()` or
+ * `parse()` mutate process-global signal handlers. Embedded callers can pass
+ * their own signal through the context instead.
+ */
+export declare function manageMainSignal(context: CliContext): ManagedMainSignal;
+/**
+ * An in-memory-only `CheckpointStore` seeded from `seed`: reads and `record()` behave
+ * exactly like a real store for the rest of this run, but `flush()`/`clear()` never touch
+ * disk. Every dry-run path hands `run` one of these instead of the real store — the
+ * managed-checkpoint contract is that a dry run never writes to the checkpoint file, no
+ * matter what `run` does with `context.checkpoint` (`record`/`flush`/`clear`, directly or
+ * via `withCheckpointedBatch`).
+ */
+export declare function inMemoryCheckpointView(seed: ReadonlyMap<string, unknown>): CheckpointStore;
+export declare function createCommand<const TSchema extends CliParamsSchema, TResult = void>(config: CliCommandConfig<TSchema, TResult>, prepareContext?: (values: CliParams<TSchema>, context: CliContext) => CliContext, mainExits?: {
+    validation?: number;
+}): CliCommand<TSchema, TResult>;
+export declare function defineCommand<const TSchema extends CliParamsSchema, TResult = void>(config: CliCommandConfig<TSchema, TResult>): CliCommand<TSchema, TResult>;
+export {};
+//# sourceMappingURL=cli-command.d.ts.map

package/dist/cli-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-command.d.ts","sourceRoot":"","sources":["../src/cli-command.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAavE,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,eAAe,EAErB,MAAM,gBAAgB,CAAC;AAGxB,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAS1E;AAED,UAAU,iBAAiB;IACzB,OAAO,EAAE,UAAU,CAAC;IACpB,cAAc,IAAI,OAAO,CAAC;IAC1B,OAAO,IAAI,IAAI,CAAC;CACjB;AAID;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,iBAAiB,CAmBvE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,CAa1F;AAED,wBAAgB,aAAa,CAAC,KAAK,CAAC,OAAO,SAAS,eAAe,EAAE,OAAO,GAAG,IAAI,EACjF,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC1C,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,UAAU,KAAK,UAAU,EAChF,SAAS,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAClC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CA2Q9B;AA+CD,wBAAgB,aAAa,CAAC,KAAK,CAAC,OAAO,SAAS,eAAe,EAAE,OAAO,GAAG,IAAI,EACjF,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,GACzC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAE9B"}

package/dist/cli-command.js

@@ -0,0 +1,314 @@
+import * as path from "path";
+import { openCheckpoint } from "./checkpoint.js";
+import { assertNoDuplicateFlags, assertValidEnvironmentFallbacks, assertValidMultipleParams, assertValidPositionals, buildEffectiveSchema, commandDescriptor, renderHelp, resolveParam, tokenize, } from "./cli-parser.js";
+import { CliHelpRequested, CliValidationError, } from "./cli-types.js";
+import { isCliValidationError, isPipelineExecutionError, toExitCode } from "./workbench-shared.js";
+export function resolveContext(overrides) {
+    return {
+        cwd: overrides?.cwd ?? process.cwd(),
+        env: overrides?.env ?? process.env,
+        log: overrides?.log ?? console,
+        pipelineContext: overrides?.pipelineContext,
+        signal: overrides?.signal,
+        checkpoint: overrides?.checkpoint,
+    };
+}
+const SIGINT_EXIT_CODE = 130;
+/**
+ * Give real CLI entrypoints graceful cancellation without making `run()` or
+ * `parse()` mutate process-global signal handlers. Embedded callers can pass
+ * their own signal through the context instead.
+ */
+export function manageMainSignal(context) {
+    if (context.signal) {
+        return { context, wasInterrupted: () => false, cleanup: () => { } };
+    }
+    const controller = new AbortController();
+    let interrupted = false;
+    const onSigint = () => {
+        interrupted = true;
+        context.log.warn("SIGINT received; cancelling pipeline work.");
+        controller.abort();
+    };
+    process.once("SIGINT", onSigint);
+    return {
+        context: { ...context, signal: controller.signal },
+        wasInterrupted: () => interrupted,
+        cleanup: () => process.removeListener("SIGINT", onSigint),
+    };
+}
+/**
+ * An in-memory-only `CheckpointStore` seeded from `seed`: reads and `record()` behave
+ * exactly like a real store for the rest of this run, but `flush()`/`clear()` never touch
+ * disk. Every dry-run path hands `run` one of these instead of the real store — the
+ * managed-checkpoint contract is that a dry run never writes to the checkpoint file, no
+ * matter what `run` does with `context.checkpoint` (`record`/`flush`/`clear`, directly or
+ * via `withCheckpointedBatch`).
+ */
+export function inMemoryCheckpointView(seed) {
+    const entries = new Map(seed);
+    return {
+        has: (key) => entries.has(key),
+        record: (key, meta) => {
+            entries.set(key, meta);
+        },
+        entries: () => entries,
+        flush: () => { },
+        clear: () => {
+            entries.clear();
+        },
+    };
+}
+export function createCommand(config, prepareContext, mainExits) {
+    const effectiveParams = buildEffectiveSchema(config.params, config.checkpoint);
+    assertNoDuplicateFlags(effectiveParams);
+    assertValidMultipleParams(effectiveParams);
+    assertValidEnvironmentFallbacks(effectiveParams);
+    const positionals = [...(config.positionals ?? [])];
+    assertValidPositionals(positionals, effectiveParams);
+    const descriptor = commandDescriptor(config, effectiveParams, positionals);
+    function parseWithContext(argv, context) {
+        const helpText = renderHelp(descriptor.name, descriptor.description, effectiveParams, positionals);
+        const tokenized = tokenize(argv, effectiveParams, positionals);
+        if (tokenized.help) {
+            return { kind: "help", helpText };
+        }
+        const errors = [...tokenized.errors];
+        const values = {};
+        for (const [key, param] of Object.entries(effectiveParams)) {
+            const argvValue = tokenized.values.get(key);
+            const envValue = argvValue === undefined && param.env ? context.env?.[param.env] : undefined;
+            values[key] = resolveParam(key, param, argvValue ?? envValue, context.cwd, errors, argvValue !== undefined ? "argv" : envValue !== undefined ? "env" : "default");
+        }
+        if (errors.length > 0) {
+            return { kind: "error", errors, helpText };
+        }
+        // SAFETY: `values` was populated by `resolveParam` for every key in `effectiveParams`,
+        // which is exactly the schema `TSchema` describes, so its runtime shape matches `CliParams<TSchema>`.
+        const typedValues = values;
+        const validationErrors = config.validate?.(typedValues, context) ?? [];
+        if (validationErrors.length > 0) {
+            return { kind: "error", errors: validationErrors, helpText };
+        }
+        return { kind: "values", values: typedValues };
+    }
+    function parse(argv = process.argv.slice(2), contextOverrides) {
+        return parseWithContext(argv, resolveContext(contextOverrides));
+    }
+    function parseStructuredWithContext(structuredValues, context) {
+        const helpText = renderHelp(descriptor.name, descriptor.description, effectiveParams, positionals);
+        const errors = [];
+        const values = {};
+        for (const key of Object.keys(structuredValues)) {
+            if (!Object.prototype.hasOwnProperty.call(effectiveParams, key)) {
+                errors.push(`Unknown parameter: ${key}`);
+            }
+        }
+        for (const [key, param] of Object.entries(effectiveParams)) {
+            const provided = structuredValues[key];
+            const raw = normalizeStructuredValue(key, param, provided, errors);
+            if (provided !== undefined && raw === undefined) {
+                values[key] = undefined;
+                continue;
+            }
+            const envValue = raw === undefined && param.env ? context.env?.[param.env] : undefined;
+            values[key] = resolveParam(key, param, raw ?? envValue, context.cwd, errors, raw !== undefined ? "argv" : envValue !== undefined ? "env" : "default");
+        }
+        if (errors.length > 0)
+            return { kind: "error", errors, helpText };
+        // SAFETY: `values` was populated by `resolveParam` for every key in `effectiveParams`,
+        // which is exactly the schema `TSchema` describes, so its runtime shape matches `CliParams<TSchema>`.
+        const typedValues = values;
+        const validationErrors = config.validate?.(typedValues, context) ?? [];
+        return validationErrors.length > 0
+            ? { kind: "error", errors: validationErrors, helpText }
+            : { kind: "values", values: typedValues };
+    }
+    /**
+     * No-op unless `config.checkpoint` is set. Respects a caller-provided `context.checkpoint`
+     * override (e.g. a stub in tests) instead of opening the real file. Otherwise opens (or
+     * clears, if not resuming) the checkpoint before `run` is called — never on the `--help`/
+     * error paths, since those return before this is reached.
+     */
+    function attachCheckpoint(context, values) {
+        const checkpointConfig = config.checkpoint;
+        if (!checkpointConfig) {
+            return context;
+        }
+        const resolvedPath = path.isAbsolute(checkpointConfig.path)
+            ? checkpointConfig.path
+            : path.join(context.cwd, checkpointConfig.path);
+        // A caller-provided context.checkpoint (e.g. a stub in tests) is used as the
+        // underlying store instead of opening the real file, but every rule below — fresh
+        // clearing, dry-run wrapping, resume detection/logging — still applies to it; only
+        // the "where does the store come from" step is skipped.
+        const store = context.checkpoint ?? openCheckpoint(resolvedPath);
+        const hadExisting = store.entries().size > 0;
+        if (values.resume) {
+            if (hadExisting) {
+                context.log.log(`Resuming from checkpoint: ${store.entries().size} item(s) already recorded.`);
+            }
+            else {
+                // Without this, --resume against a missing/wrong-path/already-cleared checkpoint
+                // silently starts fresh — the exact failure mode that's dangerous for
+                // clearOnSuccess: false workflows, where "fresh" quietly means "reprocess
+                // everything already done".
+                context.log.warn(`--resume was passed, but no checkpoint was found at ${resolvedPath}; starting fresh.`);
+            }
+            // A dry run must never write to the checkpoint file, even while resuming — an
+            // in-memory view seeded with the real entries previews it accurately without risk.
+            return {
+                ...context,
+                checkpoint: values.dryRun ? inMemoryCheckpointView(store.entries()) : store,
+            };
+        }
+        if (!hadExisting) {
+            return {
+                ...context,
+                checkpoint: values.dryRun ? inMemoryCheckpointView(store.entries()) : store,
+            };
+        }
+        if (values.dryRun) {
+            // Dry run must not touch the file — neither clearing it nor writing new progress —
+            // but the preview should still reflect what a real fresh run would see: an empty
+            // "done" set, not the stale entries a --resume invocation would use.
+            context.log.log("Dry run: leaving existing checkpoint untouched (would start fresh).");
+            return { ...context, checkpoint: inMemoryCheckpointView(new Map()) };
+        }
+        store.clear();
+        context.log.log("Starting fresh — cleared existing checkpoint.");
+        return { ...context, checkpoint: store };
+    }
+    /** No-op unless `config.checkpoint` is set, a store is attached, and the run wasn't a dry run. */
+    function finalizeCheckpoint(context, values) {
+        const checkpointConfig = config.checkpoint;
+        if (!checkpointConfig || !context.checkpoint || values.dryRun) {
+            return;
+        }
+        if (checkpointConfig.clearOnSuccess === false) {
+            return;
+        }
+        context.checkpoint.clear();
+    }
+    async function executeValues(values, context) {
+        const preparedContext = prepareContext?.(values, context) ?? context;
+        const runContext = attachCheckpoint(preparedContext, values);
+        const value = await config.run(values, runContext);
+        finalizeCheckpoint(runContext, values);
+        return value;
+    }
+    function parseValues(values, contextOverrides) {
+        const context = resolveContext(contextOverrides);
+        return parseStructuredWithContext(values, context);
+    }
+    async function execute(values, contextOverrides) {
+        return executeValues(values, resolveContext(contextOverrides));
+    }
+    async function run(argv = process.argv.slice(2), contextOverrides) {
+        const context = resolveContext(contextOverrides);
+        const result = parseWithContext(argv, context);
+        if (result.kind === "help")
+            throw new CliHelpRequested(result.helpText);
+        if (result.kind === "error")
+            throw new CliValidationError(result.errors, result.helpText);
+        return executeValues(result.values, context);
+    }
+    async function main(argv = process.argv.slice(2), contextOverrides) {
+        const context = resolveContext(contextOverrides);
+        let result;
+        try {
+            result = parseWithContext(argv, context);
+        }
+        catch (error) {
+            context.log.error(error instanceof Error ? (error.stack ?? error.message) : String(error));
+            process.exitCode =
+                mainExits || isCliValidationError(error) || isPipelineExecutionError(error)
+                    ? toExitCode(error)
+                    : 1;
+            return;
+        }
+        if (result.kind === "help") {
+            context.log.log(result.helpText);
+            process.exitCode = 0;
+            return;
+        }
+        if (result.kind === "error") {
+            for (const error of result.errors) {
+                context.log.error(`Error: ${error}`);
+            }
+            context.log.error("");
+            context.log.error(result.helpText);
+            process.exitCode = mainExits?.validation ?? 1;
+            return;
+        }
+        const managedSignal = manageMainSignal(context);
+        try {
+            const preparedContext = prepareContext?.(result.values, managedSignal.context) ?? managedSignal.context;
+            const runContext = attachCheckpoint(preparedContext, result.values);
+            await config.run(result.values, runContext);
+            if (!managedSignal.wasInterrupted()) {
+                finalizeCheckpoint(runContext, result.values);
+            }
+        }
+        catch (error) {
+            context.log.error(error instanceof Error ? (error.stack ?? error.message) : String(error));
+            process.exitCode = managedSignal.wasInterrupted()
+                ? SIGINT_EXIT_CODE
+                : mainExits || isCliValidationError(error) || isPipelineExecutionError(error)
+                    ? toExitCode(error)
+                    : 1;
+        }
+        finally {
+            if (managedSignal.wasInterrupted()) {
+                process.exitCode = SIGINT_EXIT_CODE;
+            }
+            managedSignal.cleanup();
+        }
+    }
+    return { descriptor, execute, parse, parseValues, run, main };
+}
+function normalizeStructuredValue(key, param, value, errors) {
+    if (value === undefined)
+        return undefined;
+    const label = `--${param.flag ?? key}`;
+    if (param.type === "boolean") {
+        if (typeof value === "boolean")
+            return value;
+        errors.push(`${label} must be a boolean value.`);
+        return undefined;
+    }
+    if ((param.type === "number" || param.type === "string") && param.multiple === true) {
+        if (!Array.isArray(value)) {
+            errors.push(`${label} must be an array.`);
+            return undefined;
+        }
+        if (param.type === "number") {
+            if (!value.every((item) => typeof item === "number" && Number.isFinite(item))) {
+                errors.push(`${label} must contain only finite numbers.`);
+                return undefined;
+            }
+            return value.map(String);
+        }
+        if (!value.every((item) => typeof item === "string")) {
+            errors.push(`${label} must contain only strings.`);
+            return undefined;
+        }
+        return [...value];
+    }
+    if (param.type === "number") {
+        if (typeof value !== "number" || !Number.isFinite(value)) {
+            errors.push(`${label} must be a finite number.`);
+            return undefined;
+        }
+        return String(value);
+    }
+    if (typeof value !== "string") {
+        errors.push(`${label} must be a string value.`);
+        return undefined;
+    }
+    return value;
+}
+export function defineCommand(config) {
+    return createCommand(config);
+}
+//# sourceMappingURL=cli-command.js.map