tubeless 0.1.0

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

@@ -0,0 +1,84 @@
+import type { CliBooleanParam, CliCheckpointConfig, CliCommandDescriptor, CliContext, CliParams, CliParamsSchema, CliStringParam } from "./cli-types.js";
+import { type Pipeline, type PipelineHooks, type PipelinePlan, type PipelineRunOptions } from "./pipeline.js";
+import { type PipelineReporterConfig } from "./reporter-entry.js";
+export type PipelineCliBuiltins = {
+    step: CliStringParam & {
+        multiple: true;
+    };
+    target: CliStringParam & {
+        multiple: true;
+    };
+    continueOnError: CliBooleanParam;
+};
+export type PipelineCliValues<TSchema extends CliParamsSchema> = CliParams<TSchema> & {
+    step: readonly string[];
+    target: readonly string[];
+    continueOnError: boolean;
+};
+export type PipelineCliParseResult<TSchema extends CliParamsSchema> = {
+    kind: "values";
+    values: PipelineCliValues<TSchema>;
+} | {
+    kind: "help";
+    helpText: string;
+} | {
+    kind: "error";
+    errors: readonly string[];
+    helpText: string;
+};
+/** Selection-only input for a side-effect-free pipeline command plan. */
+export interface PipelineCommandPlanInput {
+    dryRun?: boolean;
+    step?: readonly string[];
+    target?: readonly string[];
+}
+export interface PipelineCommand<TSchema extends CliParamsSchema, TResult> {
+    readonly descriptor: CliCommandDescriptor;
+    /** Plan without parsing or requiring domain parameters. */
+    plan(input?: PipelineCommandPlanInput): PipelinePlan;
+    parse(argv?: readonly string[], context?: Partial<CliContext>): PipelineCliParseResult<TSchema>;
+    /** Validate structured form values without tokenizing argv. */
+    parseValues(values: Record<string, unknown>, context?: Partial<CliContext>): PipelineCliParseResult<TSchema>;
+    /** Execute already validated form values. */
+    execute(values: PipelineCliValues<TSchema>, context?: Partial<CliContext>): Promise<TResult>;
+    run(argv?: readonly string[], context?: Partial<CliContext>): Promise<TResult>;
+    main(argv?: readonly string[], context?: Partial<CliContext>): Promise<void>;
+}
+export interface PipelineCommandHookContext<TSchema extends CliParamsSchema> {
+    context: CliContext;
+    values: PipelineCliValues<TSchema>;
+}
+export type PipelineCommandHookSets<TResult> = PipelineHooks<TResult> | readonly PipelineHooks<TResult>[];
+export type PipelineCommandHookConfig<TResult, TSchema extends CliParamsSchema> = PipelineCommandHookSets<TResult> | ((input: PipelineCommandHookContext<TSchema>) => PipelineCommandHookSets<TResult> | undefined);
+type PipelineCommandMapOptions<TOptions extends object, TSchema extends CliParamsSchema> = (values: PipelineCliValues<TSchema>, context: CliContext) => PipelineRunOptions<TOptions> | Promise<PipelineRunOptions<TOptions>>;
+type DefaultPipelineCommandOptions<TSchema extends CliParamsSchema> = Omit<PipelineCliValues<TSchema>, "continueOnError" | "dryRun" | "resume" | "step" | "target">;
+type CanDefaultPipelineCommandOptions<TOptions extends object, TSchema extends CliParamsSchema> = DefaultPipelineCommandOptions<TSchema> extends TOptions ? Exclude<keyof TSchema, keyof TOptions> extends never ? true : false : false;
+interface DefinePipelineCommandConfigBase<TResult, TSchema extends CliParamsSchema> {
+    /** Defaults to pipeline.id. */
+    name?: string;
+    description?: string;
+    /** Extra flags beyond the command and pipeline built-ins. */
+    params?: TSchema;
+    /** Extra parameter keys accepted in positional order. */
+    positionals?: readonly (keyof TSchema & string)[];
+    checkpoint?: CliCheckpointConfig;
+    /** Additional lifecycle hooks, or a factory resolved from parsed values and CLI context. */
+    hooks?: PipelineCommandHookConfig<TResult, TSchema>;
+    /** Configure plain/interactive reporting, or disable it. Defaults to automatic mode. */
+    reporter?: false | PipelineReporterConfig;
+    /** Print domain-specific result lines after a successful run. */
+    summarize?(result: TResult, values: PipelineCliValues<TSchema>, context: CliContext): readonly string[] | void;
+    validate?(values: PipelineCliValues<TSchema>, context: CliContext): string[] | void;
+}
+/** Configuration for a typed pipeline command. Mapping is optional only for compatible flags. */
+export type DefinePipelineCommandConfig<TOptions extends object, TResult, TSchema extends CliParamsSchema> = DefinePipelineCommandConfigBase<TResult, TSchema> & (CanDefaultPipelineCommandOptions<TOptions, TSchema> extends true ? {
+    /** Override the default same-name flag-to-option mapping. */
+    mapOptions?: PipelineCommandMapOptions<TOptions, TSchema>;
+} : {
+    /** Required when parsed flags do not already satisfy the pipeline's domain options. */
+    mapOptions: PipelineCommandMapOptions<TOptions, TSchema>;
+});
+/** Turn a typed pipeline into a command with selection, plan, and reporting defaults. */
+export declare function definePipelineCommand<TOptions extends object, TResult, const TSchema extends CliParamsSchema = {}>(pipeline: Pipeline<TOptions, TResult>, config: DefinePipelineCommandConfig<NoInfer<TOptions>, TResult, TSchema>): PipelineCommand<TSchema, TResult>;
+export {};
+//# sourceMappingURL=cli-pipeline-command.d.ts.map

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

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

package/dist/cli-pipeline-command.js

@@ -0,0 +1,185 @@
+import { createCommand } from "./cli-command.js";
+import { flagName } from "./cli-parser.js";
+import { markPipelineCommand } from "./pipeline-command-marker.js";
+import {} from "./pipeline.js";
+import { createPipelineReporter } from "./reporter-entry.js";
+import { TUBELESS_WORKBENCH_EXIT_CODE } from "./workbench-shared.js";
+const PIPELINE_COMMAND_KEYS = new Set(["continueOnError", "plan", "step", "target"]);
+const PIPELINE_COMMAND_FLAGS = new Set(["continue-on-error", "plan", "step", "target"]);
+function assertNoPipelineCommandConflicts(params) {
+    for (const [key, param] of Object.entries(params)) {
+        if (PIPELINE_COMMAND_KEYS.has(key)) {
+            throw new Error(`"${key}" is a reserved parameter provided automatically by pipeline commands; remove it from params.`);
+        }
+        const flag = flagName(key, param);
+        if (PIPELINE_COMMAND_FLAGS.has(flag)) {
+            throw new Error(`--${flag} is a reserved flag provided automatically by pipeline commands; remove "${key}" from params or give it a different flag name.`);
+        }
+    }
+}
+function normalizePipelineCliValues(values) {
+    // SAFETY: `PipelineCliValues<TSchema>` is `CliParams<TSchema>` plus the builtin
+    // `step`/`target`/`continueOnError` keys, all of which `CliParams<PipelineCliBuiltins & TSchema>`
+    // already provides, so the runtime shape matches the target type.
+    const pipelineValues = values;
+    const { continueOnError, step, target } = pipelineValues;
+    return {
+        ...pipelineValues,
+        continueOnError,
+        step,
+        target: target ?? [],
+    };
+}
+function normalizePipelineHookSets(hooks) {
+    if (!hooks)
+        return [];
+    // SAFETY: a non-array `PipelineCommandHookSets` is always a single `PipelineHooks`.
+    return Array.isArray(hooks) ? [...hooks] : [hooks];
+}
+function isHookConfigFunction(config) {
+    return typeof config === "function";
+}
+function defaultPipelineCommandOptions(values) {
+    const { continueOnError, dryRun, resume, step, target, ...domainValues } = values;
+    return domainValues;
+}
+/** Turn a typed pipeline into a command with selection, plan, and reporting defaults. */
+export function definePipelineCommand(pipeline, config) {
+    // SAFETY: `config.params` is declared as `TSchema`; the empty-object fallback is only
+    // reached when the caller omits `params`, which is exactly the `{}` schema case.
+    const userParams = config.params ?? {};
+    assertNoPipelineCommandConflicts(userParams);
+    const targetFlagEnabled = pipeline.targetIds.length > 0;
+    const bridgeParams = {
+        step: {
+            type: "string",
+            multiple: true,
+            choices: pipeline.stepIds,
+            description: `Run exactly this step. Steps: ${pipeline.stepIds.join(", ")}`,
+        },
+        continueOnError: {
+            type: "boolean",
+            description: "Continue independent work after a step fails.",
+        },
+    };
+    if (targetFlagEnabled) {
+        bridgeParams.target = {
+            type: "string",
+            multiple: true,
+            choices: pipeline.targetIds,
+            description: `Run this declared target and its prerequisites. Targets: ${pipeline.targetIds.join(", ")}`,
+        };
+    }
+    // SAFETY: `bridgeParams` supplies the `PipelineCliBuiltins` keys and `userParams` is
+    // `TSchema`, so the merged object satisfies `PipelineCliBuiltins & TSchema`.
+    const params = { ...bridgeParams, ...userParams };
+    const commandConfig = {
+        name: config.name ?? pipeline.id,
+        description: config.description,
+        params,
+        positionals: config.positionals,
+        checkpoint: config.checkpoint,
+        validate: (values, context) => {
+            const pipelineValues = normalizePipelineCliValues(values);
+            const errors = config.validate?.(pipelineValues, context) ?? [];
+            if (pipelineValues.step.length > 0 && pipelineValues.target.length > 0) {
+                return ["--step and --target cannot be used together.", ...errors];
+            }
+            return errors.length > 0 ? errors : undefined;
+        },
+        run: async (values, cliContext) => {
+            const pipelineValues = normalizePipelineCliValues(values);
+            let mapped;
+            if (config.mapOptions) {
+                mapped = await config.mapOptions(pipelineValues, cliContext);
+            }
+            else {
+                // SAFETY: `defaultPipelineCommandOptions` returns exactly the domain options the
+                // `CanDefaultPipelineCommandOptions` constraint guarantees map to `TOptions`.
+                mapped = defaultPipelineCommandOptions(pipelineValues);
+            }
+            const controls = {
+                dryRun: values.dryRun,
+                continueOnError: pipelineValues.continueOnError,
+            };
+            if (pipelineValues.step.length > 0) {
+                controls.stepIds = pipelineValues.step;
+            }
+            if (targetFlagEnabled && pipelineValues.target.length > 0) {
+                controls.targets = pipelineValues.target;
+            }
+            const reporter = config.reporter === false
+                ? undefined
+                : createPipelineReporter({ log: cliContext.log, ...(config.reporter ?? {}) });
+            const runtimeContext = reporter ? { ...cliContext, log: reporter.log } : cliContext;
+            let result;
+            try {
+                const configuredHooks = isHookConfigFunction(config.hooks)
+                    ? config.hooks({ context: runtimeContext, values: pipelineValues })
+                    : config.hooks;
+                const hooks = [
+                    ...normalizePipelineHookSets(cliContext.pipelineContext?.hooks),
+                    ...(reporter ? [reporter.hooks] : []),
+                    ...normalizePipelineHookSets(configuredHooks),
+                ];
+                // SAFETY: `mapped` is `TOptions` and `controls` is `PipelineRunControls`, so the
+                // merged object satisfies `PipelineRunOptions<TOptions>`.
+                const options = { ...mapped, ...controls };
+                result = await pipeline.runOrThrow(options, {
+                    ...cliContext.pipelineContext,
+                    cwd: runtimeContext.cwd,
+                    log: runtimeContext.log,
+                    hooks: hooks.length > 0 ? hooks : undefined,
+                    signal: runtimeContext.signal,
+                });
+            }
+            finally {
+                reporter?.dispose();
+            }
+            for (const line of config.summarize?.(result, pipelineValues, cliContext) ?? []) {
+                cliContext.log.log(line);
+            }
+            return result;
+        },
+    };
+    const command = createCommand(commandConfig, undefined, {
+        validation: TUBELESS_WORKBENCH_EXIT_CODE.validation,
+    });
+    function parse(argv = process.argv.slice(2), contextOverrides) {
+        const result = command.parse(argv, contextOverrides);
+        return result.kind === "values"
+            ? { kind: "values", values: normalizePipelineCliValues(result.values) }
+            : result;
+    }
+    function plan(input = {}) {
+        const controls = {
+            dryRun: input.dryRun === true,
+        };
+        if (input.step && input.step.length > 0) {
+            controls.stepIds = input.step;
+        }
+        if (input.target && input.target.length > 0) {
+            controls.targets = input.target;
+        }
+        return pipeline.plan(controls);
+    }
+    function parseValues(values, contextOverrides) {
+        const result = command.parseValues(values, contextOverrides);
+        return result.kind === "values"
+            ? { kind: "values", values: normalizePipelineCliValues(result.values) }
+            : result;
+    }
+    return markPipelineCommand({
+        descriptor: command.descriptor,
+        execute: (values, contextOverrides) => 
+        // SAFETY: `execute` receives `PipelineCliValues<TSchema>` from the public interface,
+        // which is a subtype of `CliParams<PipelineCliBuiltins & TSchema>`.
+        command.execute(values, contextOverrides),
+        parse,
+        parseValues,
+        plan,
+        run: command.run,
+        main: command.main,
+    });
+}
+//# sourceMappingURL=cli-pipeline-command.js.map

package/dist/cli-pipeline-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-pipeline-command.js","sourceRoot":"","sources":["../src/cli-pipeline-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAW3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAMN,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,sBAAsB,EAA+B,MAAM,qBAAqB,CAAC;AAC1F,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AA8GrE,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC,CAAC,iBAAiB,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AACrF,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC,CAAC,mBAAmB,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AAExF,SAAS,gCAAgC,CAAC,MAAuB;IAC/D,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,qBAAqB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CACb,IAAI,GAAG,+FAA+F,CACvG,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAClC,IAAI,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CACb,KAAK,IAAI,4EAA4E,GAAG,iDAAiD,CAC1I,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,0BAA0B,CACjC,MAAgD;IAEhD,gFAAgF;IAChF,kGAAkG;IAClG,kEAAkE;IAClE,MAAM,cAAc,GAAG,MAAoC,CAAC;IAC5D,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,cAAc,CAAC;IACzD,OAAO;QACL,GAAG,cAAc;QACjB,eAAe;QACf,IAAI;QACJ,MAAM,EAAE,MAAM,IAAI,EAAE;KACrB,CAAC;AACJ,CAAC;AAED,SAAS,yBAAyB,CAChC,KAAmD;IAEnD,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,oFAAoF;IACpF,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAA+B,CAAC,CAAC;AAC/E,CAAC;AAED,SAAS,oBAAoB,CAC3B,MAA+D;IAI/D,OAAO,OAAO,MAAM,KAAK,UAAU,CAAC;AACtC,CAAC;AAED,SAAS,6BAA6B,CACpC,MAAkC;IAElC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,YAAY,EAAE,GAAG,MAAM,CAAC;IAClF,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,qBAAqB,CAKnC,QAAqC,EACrC,MAAwE;IAExE,sFAAsF;IACtF,iFAAiF;IACjF,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,IAAK,EAAc,CAAC;IACpD,gCAAgC,CAAC,UAAU,CAAC,CAAC;IAE7C,MAAM,iBAAiB,GAAG,QAAQ,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;IACxD,MAAM,YAAY,GAAoB;QACpC,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,WAAW,EAAE,iCAAiC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;SAC5E;QACD,eAAe,EAAE;YACf,IAAI,EAAE,SAAS;YACf,WAAW,EAAE,+CAA+C;SAC7D;KACF,CAAC;IACF,IAAI,iBAAiB,EAAE,CAAC;QACtB,YAAY,CAAC,MAAM,GAAG;YACpB,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,QAAQ,CAAC,SAAS;YAC3B,WAAW,EAAE,4DAA4D,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;SACzG,CAAC;IACJ,CAAC;IAED,qFAAqF;IACrF,6EAA6E;IAC7E,MAAM,MAAM,GAAG,EAAE,GAAG,YAAY,EAAE,GAAG,UAAU,EAAmC,CAAC;IAEnF,MAAM,aAAa,GAAG;QACpB,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,QAAQ,CAAC,EAAE;QAChC,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,MAAM;QACN,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE;YAC5B,MAAM,cAAc,GAAG,0BAA0B,CAAU,MAAM,CAAC,CAAC;YACnE,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC,cAAc,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;YAChE,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,cAAc,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvE,OAAO,CAAC,8CAA8C,EAAE,GAAG,MAAM,CAAC,CAAC;YACrE,CAAC;YACD,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;QAChD,CAAC;QACD,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE;YAChC,MAAM,cAAc,GAAG,0BAA0B,CAAU,MAAM,CAAC,CAAC;YACnE,IAAI,MAAgB,CAAC;YACrB,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;gBACtB,MAAM,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;YAC/D,CAAC;iBAAM,CAAC;gBACN,iFAAiF;gBACjF,8EAA8E;gBAC9E,MAAM,GAAG,6BAA6B,CAAC,cAAc,CAAa,CAAC;YACrE,CAAC;YACD,MAAM,QAAQ,GAAwB;gBACpC,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,eAAe,EAAE,cAAc,CAAC,eAAe;aAChD,CAAC;YACF,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACnC,QAAQ,CAAC,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC;YACzC,CAAC;YACD,IAAI,iBAAiB,IAAI,cAAc,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC1D,QAAQ,CAAC,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC;YAC3C,CAAC;YAED,MAAM,QAAQ,GACZ,MAAM,CAAC,QAAQ,KAAK,KAAK;gBACvB,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,sBAAsB,CAAU,EAAE,GAAG,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;YAC3F,MAAM,cAAc,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,UAAU,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;YACpF,IAAI,MAAe,CAAC;YACpB,IAAI,CAAC;gBACH,MAAM,eAAe,GAAG,oBAAoB,CAAC,MAAM,CAAC,KAAK,CAAC;oBACxD,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;oBACnE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;gBACjB,MAAM,KAAK,GAA6B;oBACtC,GAAG,yBAAyB,CAAC,UAAU,CAAC,eAAe,EAAE,KAAK,CAAC;oBAC/D,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;oBACrC,GAAG,yBAAyB,CAAC,eAAe,CAAC;iBAC9C,CAAC;gBAEF,iFAAiF;gBACjF,0DAA0D;gBAC1D,MAAM,OAAO,GAAG,EAAE,GAAG,MAAM,EAAE,GAAG,QAAQ,EAAkC,CAAC;gBAC3E,MAAM,GAAG,MAAM,QAAQ,CAAC,UAAU,CAAC,OAAO,EAAE;oBAC1C,GAAG,UAAU,CAAC,eAAe;oBAC7B,GAAG,EAAE,cAAc,CAAC,GAAG;oBACvB,GAAG,EAAE,cAAc,CAAC,GAAG;oBACvB,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;oBAC3C,MAAM,EAAE,cAAc,CAAC,MAAM;iBAC9B,CAAC,CAAC;YACL,CAAC;oBAAS,CAAC;gBACT,QAAQ,EAAE,OAAO,EAAE,CAAC;YACtB,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,cAAc,EAAE,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC;gBAChF,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC3B,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;KACiE,CAAC;IAErE,MAAM,OAAO,GAAG,aAAa,CAAC,aAAa,EAAE,SAAS,EAAE;QACtD,UAAU,EAAE,4BAA4B,CAAC,UAAU;KACpD,CAAC,CAAC;IAEH,SAAS,KAAK,CACZ,IAAI,GAAsB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAC/C,gBAAsC;QAEtC,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;QACrD,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;YAC7B,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,0BAA0B,CAAU,MAAM,CAAC,MAAM,CAAC,EAAE;YAChF,CAAC,CAAC,MAAM,CAAC;IACb,CAAC;IAED,SAAS,IAAI,CAAC,KAAK,GAA6B,EAAE;QAChD,MAAM,QAAQ,GAAwB;YACpC,MAAM,EAAE,KAAK,CAAC,MAAM,KAAK,IAAI;SAC9B,CAAC;QACF,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxC,QAAQ,CAAC,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC;QAChC,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5C,QAAQ,CAAC,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC;QAClC,CAAC;QACD,OAAO,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACjC,CAAC;IAED,SAAS,WAAW,CAClB,MAA+B,EAC/B,gBAAsC;QAEtC,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;QAC7D,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;YAC7B,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,0BAA0B,CAAU,MAAM,CAAC,MAAM,CAAC,EAAE;YAChF,CAAC,CAAC,MAAM,CAAC;IACb,CAAC;IAED,OAAO,mBAAmB,CAAC;QACzB,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,OAAO,EAAE,CAAC,MAAM,EAAE,gBAAgB,EAAE,EAAE;QACpC,qFAAqF;QACrF,oEAAoE;QACpE,OAAO,CAAC,OAAO,CAAC,MAAkD,EAAE,gBAAgB,CAAC;QACvF,KAAK;QACL,WAAW;QACX,IAAI;QACJ,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,IAAI,EAAE,OAAO,CAAC,IAAI;KACnB,CAAC,CAAC;AACL,CAAC"}

package/dist/cli-types.d.ts

@@ -0,0 +1,220 @@
+import type { CheckpointStore } from "./checkpoint.js";
+import type { PipelineContext, PipelineLogger } from "./pipeline.js";
+/**
+ * Typed command-line entry points for scripts, mirroring how `definePipeline` turns a
+ * declarative step list into a runnable pipeline: declare a flag schema once and get a
+ * fully-typed, validated `values` object handed to `run`, instead of each script hand-
+ * rolling its own `process.argv` scanning and `as` casts.
+ */
+export type CliParamType = "string" | "number" | "boolean" | "path";
+interface CliParamBase {
+    /** Shown next to the flag in generated `--help` output. */
+    description?: string;
+    /** Overrides the derived `--flag-name`; defaults to the kebab-case of the schema key. */
+    flag?: string;
+    /** Optional one-letter alias, for example `short: "v"` enables `-v`. */
+    short?: string;
+    /**
+     * Optional environment-variable fallback. Explicit argv values always win;
+     * the environment value is validated like argv but never echoed in errors.
+     */
+    env?: string;
+}
+export interface CliStringParam extends CliParamBase {
+    type: "string";
+    choices?: readonly string[];
+    default?: string;
+    optional?: boolean;
+    /** Repeatable: `--flag a --flag b` accumulates into `readonly string[]`, `[]` when absent. Cannot combine with `default`. */
+    multiple?: boolean;
+}
+export interface CliNumberParam extends CliParamBase {
+    type: "number";
+    default?: number;
+    optional?: boolean;
+    integer?: boolean;
+    min?: number;
+    max?: number;
+    /** Repeatable: `--flag 1 --flag 2` accumulates into `readonly number[]`, `[]` when absent. Cannot combine with `default`. */
+    multiple?: boolean;
+}
+export interface CliBooleanParam extends CliParamBase {
+    type: "boolean";
+    /** Defaults to `false`. A bare `--flag` sets `true`; `--no-flag` sets `false`. */
+    default?: boolean;
+}
+export interface CliPathParam extends CliParamBase {
+    type: "path";
+    /** Relative defaults and values are resolved against `context.cwd`, like `definePaths`. */
+    default?: string;
+    optional?: boolean;
+    /** Validates the resolved path exists before `run` is called. */
+    mustExist?: boolean;
+    /** Only checked when `mustExist` is true; asserts the resolved path's kind. */
+    kind?: "file" | "directory";
+}
+export type CliParam = CliStringParam | CliNumberParam | CliBooleanParam | CliPathParam;
+export type CliParamsSchema = Record<string, CliParam>;
+/** JSON-safe description of one validated command parameter for non-terminal clients. */
+export interface CliParameterDescriptor {
+    readonly choices?: readonly string[];
+    readonly default?: string | number | boolean;
+    readonly description?: string;
+    readonly environment?: string;
+    readonly flag: string;
+    readonly integer?: boolean;
+    readonly key: string;
+    readonly max?: number;
+    readonly min?: number;
+    readonly multiple: boolean;
+    readonly mustExist?: boolean;
+    readonly pathKind?: "directory" | "file";
+    readonly positional: boolean;
+    readonly required: boolean;
+    readonly short?: string;
+    readonly type: CliParamType;
+}
+/** Immutable, presentation-neutral command contract shared by CLI and UI adapters. */
+export interface CliCommandDescriptor {
+    readonly description?: string;
+    readonly name: string;
+    readonly parameters: readonly CliParameterDescriptor[];
+}
+type CliScalarStringValue<P extends CliParam> = P extends {
+    choices: readonly (infer TChoice extends string)[];
+} ? TChoice : string;
+type CliParamValue<P extends CliParam> = P extends {
+    type: "string";
+} ? P extends {
+    multiple: true;
+} ? readonly CliScalarStringValue<P>[] : CliScalarStringValue<P> : P extends {
+    type: "number";
+} ? P extends {
+    multiple: true;
+} ? readonly number[] : number : P extends {
+    type: "boolean";
+} ? boolean : P extends {
+    type: "path";
+} ? string : never;
+/**
+ * A field is optional in the parsed output only when it's explicitly marked `optional:
+ * true` (booleans never are — an absent boolean flag just means `false`). A field with a
+ * `default` is also always present at runtime, but that's already covered: schemas
+ * shouldn't combine `default` with `optional: true`, and if one does, the parsed type is
+ * merely wider than necessary (`T | undefined` instead of `T`), never wrong.
+ */
+type CliParamIsOptional<P extends CliParam> = P extends {
+    type: "boolean";
+} ? false : P extends {
+    multiple: true;
+} ? false : P extends {
+    optional: true;
+} ? true : false;
+type RequiredCliParams<TSchema extends CliParamsSchema> = {
+    [K in keyof TSchema as CliParamIsOptional<TSchema[K]> extends true ? never : K]: CliParamValue<TSchema[K]>;
+};
+type OptionalCliParams<TSchema extends CliParamsSchema> = {
+    [K in keyof TSchema as CliParamIsOptional<TSchema[K]> extends true ? K : never]?: CliParamValue<TSchema[K]>;
+};
+/**
+ * Every command's parsed values include `dryRun` and `resume`, whether or not `TSchema`
+ * declares them. `resume` is `false` unless `--resume` is passed or `checkpoint.defaultResume`
+ * is `true`; it's meaningful even without `checkpoint` configured — a command can implement
+ * its own "is this done" check and just read `values.resume` directly.
+ */
+export type CliParams<TSchema extends CliParamsSchema> = {
+    dryRun: boolean;
+    resume: boolean;
+} & RequiredCliParams<TSchema> & OptionalCliParams<TSchema>;
+export interface CliContext {
+    cwd: string;
+    /** Environment used for `param.env` fallbacks. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    log: PipelineLogger;
+    /** Optional executor-only context used when this command runs a pipeline. */
+    pipelineContext?: Omit<PipelineContext, "cwd" | "log" | "signal">;
+    /** Optional caller-owned cancellation signal forwarded to command work. */
+    signal?: AbortSignal;
+    /** Present whenever the command's `checkpoint` config is set; see `CliCheckpointConfig`. */
+    checkpoint?: CheckpointStore;
+}
+export type CliParseResult<TSchema extends CliParamsSchema> = {
+    kind: "values";
+    values: CliParams<TSchema>;
+} | {
+    kind: "help";
+    helpText: string;
+} | {
+    kind: "error";
+    errors: readonly string[];
+    helpText: string;
+};
+export declare class CliValidationError extends Error {
+    readonly errors: readonly string[];
+    readonly helpText: string;
+    constructor(errors: readonly string[], helpText: string);
+}
+export declare class CliHelpRequested extends Error {
+    readonly helpText: string;
+    constructor(helpText: string);
+}
+export interface CliCheckpointConfig {
+    /** Relative paths resolve against `context.cwd`, like `CliPathParam`. */
+    path: string;
+    /**
+     * Defaults to `true`: a fully successful, non-dry-run `run` clears the checkpoint —
+     * the one-shot resumable-job pattern (start fresh next time). Set `false` for an
+     * incrementally-growing "done" set (e.g. entity enrichment) that must never auto-clear,
+     * since clearing it would cause already-processed items to be reprocessed.
+     */
+    clearOnSuccess?: boolean;
+    /**
+     * Defaults to `false`: start fresh unless `--resume` is passed. Set `true` to always
+     * resume by default (skip already-recorded items every run); `--no-resume` is the free
+     * opt-out, since boolean flags already support `--no-<flag>` negation.
+     */
+    defaultResume?: boolean;
+}
+export interface CliCommandConfig<TSchema extends CliParamsSchema, TResult> {
+    /** Shown in generated usage text; defaults to the running script's file name. */
+    name?: string;
+    description?: string;
+    /** `dryRun`/`--dry-run` and `-h`/`--help` are provided automatically; don't redeclare them. */
+    params: TSchema;
+    /**
+     * Schema keys accepted in positional order. Flags for an earlier positional
+     * let the next positional fill the next unset field; a repeatable positional
+     * must be last.
+     */
+    positionals?: readonly (keyof TSchema & string)[];
+    /**
+     * Opts into a managed checkpoint file. Adds a reserved `--resume`/`--no-resume` flag
+     * (also don't redeclare a `resume` param) and populates `context.checkpoint` before
+     * `run` is called: resolved fresh (existing file cleared) unless resuming, and cleared
+     * again after a successful non-dry-run unless `clearOnSuccess` is `false`.
+     */
+    checkpoint?: CliCheckpointConfig;
+    /** Runs after every field passes its own validation; return error messages to reject. */
+    validate?(values: CliParams<TSchema>, context: CliContext): string[] | void;
+    run(values: CliParams<TSchema>, context: CliContext): TResult | Promise<TResult>;
+}
+export interface CliCommand<TSchema extends CliParamsSchema, TResult> {
+    /** Structured schema metadata for adapters that should not parse generated help text. */
+    readonly descriptor: CliCommandDescriptor;
+    /** Pure: parses and validates without calling `run` or touching the process. */
+    parse(argv?: readonly string[], context?: Partial<CliContext>): CliParseResult<TSchema>;
+    /** Validates structured parameter values without tokenizing command-line arguments. */
+    parseValues(values: Record<string, unknown>, context?: Partial<CliContext>): CliParseResult<TSchema>;
+    /** Calls `run` from already validated parameter values. */
+    execute(values: CliParams<TSchema>, context?: Partial<CliContext>): Promise<TResult>;
+    /** Parses and calls `run`; throws `CliValidationError`/`CliHelpRequested` instead of running it. */
+    run(argv?: readonly string[], context?: Partial<CliContext>): Promise<TResult>;
+    /**
+     * Entry point for `if (import.meta.main) void command.main();`. Prints help/errors and
+     * sets `process.exitCode` — never calls `process.exit`, so buffered output still flushes
+     * — instead of throwing.
+     */
+    main(argv?: readonly string[], context?: Partial<CliContext>): Promise<void>;
+}
+export {};
+//# sourceMappingURL=cli-types.d.ts.map

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

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

package/dist/cli-types.js

@@ -0,0 +1,19 @@
+export class CliValidationError extends Error {
+    errors;
+    helpText;
+    constructor(errors, helpText) {
+        super(`Invalid command-line arguments:\n${errors.map((error) => `  - ${error}`).join("\n")}`);
+        this.errors = errors;
+        this.helpText = helpText;
+        this.name = "CliValidationError";
+    }
+}
+export class CliHelpRequested extends Error {
+    helpText;
+    constructor(helpText) {
+        super(helpText);
+        this.helpText = helpText;
+        this.name = "CliHelpRequested";
+    }
+}
+//# sourceMappingURL=cli-types.js.map

package/dist/cli-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-types.js","sourceRoot":"","sources":["../src/cli-types.ts"],"names":[],"mappings":"AA2KA,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAEhC,MAAM;IACN,QAAQ;IAFnB,YACW,MAAyB,EACzB,QAAgB;QAEzB,KAAK,CAAC,oCAAoC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;sBAHrF,MAAM;wBACN,QAAQ;QAGjB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACpB,QAAQ;IAA7B,YAAqB,QAAgB;QACnC,KAAK,CAAC,QAAQ,CAAC,CAAC;wBADG,QAAQ;QAE3B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+export { CliHelpRequested, CliValidationError, type CliBooleanParam, type CliCheckpointConfig, type CliCommand, type CliCommandConfig, type CliCommandDescriptor, type CliContext, type CliNumberParam, type CliParam, type CliParameterDescriptor, type CliParams, type CliParamsSchema, type CliParamType, type CliParseResult, type CliPathParam, type CliStringParam, } from "./cli-types.js";
+export { defineCommand } from "./cli-command.js";
+export { definePipelineCommand, type DefinePipelineCommandConfig, type PipelineCliBuiltins, type PipelineCliParseResult, type PipelineCliValues, type PipelineCommand, type PipelineCommandHookConfig, type PipelineCommandHookContext, type PipelineCommandHookSets, type PipelineCommandPlanInput, } from "./cli-pipeline-command.js";
+export { normalizeMultiSelectChoices, parseMultiSelectInput, promptMultiSelect, type MultiSelectChoice, type MultiSelectResult, type ParseMultiSelectInputOptions, type PromptMultiSelectOptions, } from "./prompt-select.js";
+export { TUBELESS_WORKBENCH_EXIT_CODE } from "./workbench-shared.js";
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,sBAAsB,EAC3B,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EACL,qBAAqB,EACrB,KAAK,2BAA2B,EAChC,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,GAC9B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,EACrB,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,4BAA4B,EACjC,KAAK,wBAAwB,GAC9B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/cli.js

@@ -0,0 +1,6 @@
+export { CliHelpRequested, CliValidationError, } from "./cli-types.js";
+export { defineCommand } from "./cli-command.js";
+export { definePipelineCommand, } from "./cli-pipeline-command.js";
+export { normalizeMultiSelectChoices, parseMultiSelectInput, promptMultiSelect, } from "./prompt-select.js";
+export { TUBELESS_WORKBENCH_EXIT_CODE } from "./workbench-shared.js";
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,kBAAkB,GAgBnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EACL,qBAAqB,GAUtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,EACrB,iBAAiB,GAKlB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/env.d.ts

@@ -0,0 +1,2 @@
+export declare function requireEnv(varName: string, usedBy: string): string;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAMlE"}

package/dist/env.js

@@ -0,0 +1,8 @@
+export function requireEnv(varName, usedBy) {
+    const value = process.env[varName];
+    if (!value) {
+        throw new Error(`${varName} is required for ${usedBy}`);
+    }
+    return value;
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,MAAc;IACxD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,oBAAoB,MAAM,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/file-utils.d.ts

@@ -0,0 +1,4 @@
+export declare function writeJson(filePath: string, value: unknown): void;
+export declare function readJson<T>(filePath: string): T;
+export declare function resetDir(dirPath: string): void;
+//# sourceMappingURL=file-utils.d.ts.map

package/dist/file-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-utils.d.ts","sourceRoot":"","sources":["../src/file-utils.ts"],"names":[],"mappings":"AAGA,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAkBhE;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,CAM/C;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAG9C"}

package/dist/file-utils.js

@@ -0,0 +1,35 @@
+import * as fs from "fs";
+import * as path from "path";
+export function writeJson(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    // Write to a sibling temp file and rename over the destination rather than
+    // writeFileSync-ing the target directly: a crash mid-write would otherwise
+    // leave truncated JSON. Rename is atomic on the same filesystem (same pattern
+    // as openCheckpoint flush).
+    const tmpPath = `${filePath}.tmp-${process.pid}`;
+    try {
+        fs.writeFileSync(tmpPath, `${JSON.stringify(value, null, 2)}\n`);
+        fs.renameSync(tmpPath, filePath);
+    }
+    catch (error) {
+        try {
+            fs.rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // Best-effort cleanup; surface the original write/rename error.
+        }
+        throw error;
+    }
+}
+export function readJson(filePath) {
+    // SAFETY: the caller's type parameter T is the contract for the file's
+    // contents; the file is expected to hold JSON matching T (files written by
+    // writeJson round-trip). JSON.parse returns `any`, so the assertion only
+    // documents the caller's guarantee — it performs no runtime narrowing.
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+}
+export function resetDir(dirPath) {
+    fs.rmSync(dirPath, { recursive: true, force: true });
+    fs.mkdirSync(dirPath, { recursive: true });
+}
+//# sourceMappingURL=file-utils.js.map