@runa-cmd/core 0.1.0 → 0.2.0-beta.1

package/dist/lifecycle.js

@@ -41,9 +41,11 @@ export function createHookRegistry() {
                     try {
                         await handler(context);
                     }
-                    catch {
-                        // Cleanup errors are swallowed to ensure all handlers run.
-                        // Plugin cleanup errors are reported separately.
+                    catch (err) {
+                        // ADR-0009: never rethrown (all handlers must run), but the
+                        // handler's own defect must not vanish — log to stderr.
+                        // Plugin cleanup() errors are reported separately.
+                        console.error('runa: cleanup hook threw:', err);
                     }
                 }
                 return { shortCircuited: false };

package/dist/lifecycle.js.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AA0BA;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IACjC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA2B,CAAC;IAEpD,OAAO;QACN,QAAQ,CAAC,IAAc,EAAE,OAAoB;YAC5C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzB,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACxB,CAAC;YACD,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAChC,IAAI,IAAI,EAAE,CAAC;gBACV,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACpB,CAAC;QACF,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,IAAc,EAAE,OAAoB;YAC9C,MAAM,YAAY,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YAC9C,IAAI,cAAc,GAAG,KAAK,CAAC;YAE3B,IAAI,IAAI,KAAK,eAAe,EAAE,CAAC;gBAC9B,kEAAkE;gBAClE,IAAI,eAAe,GAAG,KAAK,CAAC;gBAC5B,MAAM,mBAAmB,GAAgB;oBACxC,GAAG,OAAO;oBACV,YAAY,EAAE,GAAG,EAAE;wBAClB,eAAe,GAAG,IAAI,CAAC;oBACxB,CAAC;iBACD,CAAC;gBAEF,KAAK,MAAM,OAAO,IAAI,YAAY,EAAE,CAAC;oBACpC,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAC;oBACnC,IAAI,eAAe,EAAE,CAAC;wBACrB,cAAc,GAAG,IAAI,CAAC;wBACtB,MAAM;oBACP,CAAC;gBACF,CAAC;gBACD,OAAO,EAAE,cAAc,EAAE,CAAC;YAC3B,CAAC;YAED,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACxB,4DAA4D;gBAC5D,KAAK,MAAM,OAAO,IAAI,YAAY,EAAE,CAAC;oBACpC,IAAI,CAAC;wBACJ,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;oBACxB,CAAC;oBAAC,MAAM,CAAC;wBACR,2DAA2D;wBAC3D,iDAAiD;oBAClD,CAAC;gBACF,CAAC;gBACD,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;YAClC,CAAC;YAED,qDAAqD;YACrD,KAAK,MAAM,OAAO,IAAI,YAAY,EAAE,CAAC;gBACpC,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;YACxB,CAAC;YAED,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;QAClC,CAAC;QAED,WAAW,CAAC,IAAc;YACzB,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACjC,CAAC;KACD,CAAC;AACH,CAAC"}
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AA0BA;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IACjC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA2B,CAAC;IAEpD,OAAO;QACN,QAAQ,CAAC,IAAc,EAAE,OAAoB;YAC5C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzB,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACxB,CAAC;YACD,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAChC,IAAI,IAAI,EAAE,CAAC;gBACV,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACpB,CAAC;QACF,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,IAAc,EAAE,OAAoB;YAC9C,MAAM,YAAY,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YAC9C,IAAI,cAAc,GAAG,KAAK,CAAC;YAE3B,IAAI,IAAI,KAAK,eAAe,EAAE,CAAC;gBAC9B,kEAAkE;gBAClE,IAAI,eAAe,GAAG,KAAK,CAAC;gBAC5B,MAAM,mBAAmB,GAAgB;oBACxC,GAAG,OAAO;oBACV,YAAY,EAAE,GAAG,EAAE;wBAClB,eAAe,GAAG,IAAI,CAAC;oBACxB,CAAC;iBACD,CAAC;gBAEF,KAAK,MAAM,OAAO,IAAI,YAAY,EAAE,CAAC;oBACpC,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAC;oBACnC,IAAI,eAAe,EAAE,CAAC;wBACrB,cAAc,GAAG,IAAI,CAAC;wBACtB,MAAM;oBACP,CAAC;gBACF,CAAC;gBACD,OAAO,EAAE,cAAc,EAAE,CAAC;YAC3B,CAAC;YAED,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACxB,4DAA4D;gBAC5D,KAAK,MAAM,OAAO,IAAI,YAAY,EAAE,CAAC;oBACpC,IAAI,CAAC;wBACJ,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;oBACxB,CAAC;oBAAC,OAAO,GAAG,EAAE,CAAC;wBACd,4DAA4D;wBAC5D,wDAAwD;wBACxD,mDAAmD;wBACnD,OAAO,CAAC,KAAK,CAAC,2BAA2B,EAAE,GAAG,CAAC,CAAC;oBACjD,CAAC;gBACF,CAAC;gBACD,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;YAClC,CAAC;YAED,qDAAqD;YACrD,KAAK,MAAM,OAAO,IAAI,YAAY,EAAE,CAAC;gBACpC,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;YACxB,CAAC;YAED,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;QAClC,CAAC;QAED,WAAW,CAAC,IAAc;YACzB,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACjC,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/parse/adapters/zod-v4.d.ts

@@ -0,0 +1,3 @@
+import type { SchemaAdapter } from '../schema-adapter.js';
+export declare const zodV4Adapter: SchemaAdapter;
+//# sourceMappingURL=zod-v4.d.ts.map

package/dist/parse/adapters/zod-v4.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-v4.d.ts","sourceRoot":"","sources":["../../../src/parse/adapters/zod-v4.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,aAAa,EAAqB,MAAM,sBAAsB,CAAC;AAsJ7E,eAAO,MAAM,YAAY,EAAE,aAyB1B,CAAC"}

package/dist/parse/adapters/zod-v4.js

@@ -0,0 +1,106 @@
+// ─── Helper: access ._zod.def safely ───────────────────────
+function getZodDef(schema) {
+    const s = schema;
+    if (!s._zod?.def) {
+        throw new Error('Cannot introspect Zod schema: ._zod.def is missing. Ensure you are using Zod v4.');
+    }
+    return s._zod.def;
+}
+function getDescription(schema) {
+    const s = schema;
+    return s.description;
+}
+function unwrapSchema(schema) {
+    let isOptional = false;
+    let defaultValue;
+    let hasDefault = false;
+    let description = getDescription(schema);
+    let current = schema;
+    // Iteratively unwrap layers
+    const maxDepth = 10; // safety limit
+    for (let i = 0; i < maxDepth; i++) {
+        const def = getZodDef(current);
+        if (def.type === 'optional') {
+            isOptional = true;
+            current = def.innerType;
+            if (!description)
+                description = getDescription(current);
+            continue;
+        }
+        if (def.type === 'default') {
+            isOptional = true; // defaults make the field optional from the user's perspective
+            hasDefault = true;
+            defaultValue = def.defaultValue;
+            current = def.innerType;
+            if (!description)
+                description = getDescription(current);
+            continue;
+        }
+        if (def.type === 'nullable') {
+            current = def.innerType;
+            if (!description)
+                description = getDescription(current);
+            continue;
+        }
+        // Base type reached
+        break;
+    }
+    return {
+        baseDef: getZodDef(current),
+        isOptional,
+        hasDefault,
+        defaultValue: hasDefault ? defaultValue : undefined,
+        description,
+    };
+}
+// ─── Detect base type ───────────────────────────────────────
+function detectParamType(def) {
+    switch (def.type) {
+        case 'string':
+            return { kind: 'string' };
+        case 'number':
+        case 'int':
+            return { kind: 'number' };
+        case 'boolean':
+            return { kind: 'boolean' };
+        case 'enum': {
+            // Zod v4 uses `entries` (object { staging: 'staging', prod: 'prod' })
+            // not `values` (array). Extract the values from the entries object.
+            const entries = def.entries;
+            const values = entries ? Object.values(entries) : undefined;
+            return { kind: 'enum', enumValues: values };
+        }
+        case 'array': {
+            const item = detectParamType(unwrapSchema(def.element).baseDef);
+            return { kind: 'array', itemKind: item.kind, enumValues: item.enumValues };
+        }
+        default:
+            // Fallback: treat unknown types as string
+            return { kind: 'string' };
+    }
+}
+// ─── Adapter ────────────────────────────────────────────────
+export const zodV4Adapter = {
+    name: 'zod-v4',
+    supports(schema) {
+        if (schema === null || (typeof schema !== 'object' && typeof schema !== 'function')) {
+            return false;
+        }
+        const s = schema;
+        return s._zod?.def !== undefined;
+    },
+    describe(schema) {
+        const { baseDef, isOptional, hasDefault, defaultValue, description } = unwrapSchema(schema);
+        const { kind, enumValues, itemKind } = detectParamType(baseDef);
+        return {
+            kind,
+            isOptional,
+            hasDefault,
+            defaultValue,
+            enumValues,
+            itemKind,
+            description,
+        };
+    },
+};
+//# sourceMappingURL=zod-v4.js.map

package/dist/parse/adapters/zod-v4.js.map

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

package/dist/parse/deprecated.d.ts

@@ -0,0 +1,12 @@
+import type { OptionMeta } from '../types.js';
+export interface DeprecationInput {
+    /** Keys of the util.parseArgs result: holds only what the user passed */
+    provided: string[];
+    longAliasMap: Record<string, string>;
+    optionMeta?: Record<string, OptionMeta>;
+    configValues?: Record<string, unknown>;
+    env?: Record<string, string | undefined>;
+}
+/** The warnings for every deprecated option set from the CLI, env or config. */
+export declare function deprecationWarnings(input: DeprecationInput): string[];
+//# sourceMappingURL=deprecated.d.ts.map

package/dist/parse/deprecated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecated.d.ts","sourceRoot":"","sources":["../../src/parse/deprecated.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAChC,yEAAyE;IACzE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CACzC;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAcrE"}

package/dist/parse/deprecated.js

@@ -0,0 +1,21 @@
+/**
+ * @runa-cmd/core — Deprecated option warnings
+ *
+ * `meta.options[name].deprecated` declares the notice once. It is shown in help
+ * and, through this module, whenever the option is actually used.
+ */
+import { longFlag } from '../flag-name.js';
+/** The warnings for every deprecated option set from the CLI, env or config. */
+export function deprecationWarnings(input) {
+    const { provided, longAliasMap, optionMeta, configValues, env = process.env } = input;
+    const fromCli = new Set(provided.map((key) => longAliasMap[key] ?? key));
+    return Object.entries(optionMeta ?? {}).flatMap(([name, meta]) => {
+        if (!meta.deprecated)
+            return [];
+        const isUsed = fromCli.has(name) ||
+            (meta.env !== undefined && env[meta.env] !== undefined) ||
+            configValues?.[name] !== undefined;
+        return isUsed ? [`Warning: ${longFlag(name)} is deprecated. ${meta.deprecated}`] : [];
+    });
+}
+//# sourceMappingURL=deprecated.js.map

package/dist/parse/deprecated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecated.js","sourceRoot":"","sources":["../../src/parse/deprecated.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAY3C,gFAAgF;AAChF,MAAM,UAAU,mBAAmB,CAAC,KAAuB;IAC1D,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;IACtF,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IAEzE,OAAO,MAAM,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE;QAChE,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,OAAO,EAAE,CAAC;QAEhC,MAAM,MAAM,GACX,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;YACjB,CAAC,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;YACvD,YAAY,EAAE,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC;QAEpC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,YAAY,QAAQ,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACvF,CAAC,CAAC,CAAC;AACJ,CAAC"}

package/dist/parse/parseargs-bridge.d.ts

@@ -10,6 +10,16 @@ export interface ParseArgsBridgeConfig {
     parseArgsConfig: ParseArgsConfig;
     /** Maps long alias names → canonical option name */
     longAliasMap: Record<string, string>;
+    /**
+     * Every key util.parseArgs may legitimately produce for this config:
+     * canonical option names + registered long aliases, plus a defensive
+     * `no-{name}` per boolean option (parseArgs folds `--no-x` into `x: false`
+     * under allowNegative — pinned by parseargs-negation.test.ts — but the
+     * allowance guards against a future representation change).
+     */
+    knownKeys: Set<string>;
+    /** Canonical names of boolean options (for the strict check's `no-*` allowance) */
+    booleanKeys: Set<string>;
 }
 /**
  * Build a util.parseArgs configuration from schema walker output.

package/dist/parse/parseargs-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseargs-bridge.d.ts","sourceRoot":"","sources":["../../src/parse/parseargs-bridge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAI7D,MAAM,WAAW,qBAAqB;IACrC,eAAe,EAAE,eAAe,CAAC;IACjC,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAID;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CACnC,QAAQ,EAAE,aAAa,EAAE,EACzB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EACvC,OAAO,CAAC,EAAE,OAAO,GACf,qBAAqB,CAsDvB"}
+{"version":3,"file":"parseargs-bridge.d.ts","sourceRoot":"","sources":["../../src/parse/parseargs-bridge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAI7D,MAAM,WAAW,qBAAqB;IACrC,eAAe,EAAE,eAAe,CAAC;IACjC,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC;;;;;;OAMG;IACH,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB,mFAAmF;IACnF,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AAID;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CACnC,QAAQ,EAAE,aAAa,EAAE,EACzB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EACvC,OAAO,CAAC,EAAE,OAAO,GACf,qBAAqB,CAiEvB"}

package/dist/parse/parseargs-bridge.js

@@ -1,3 +1,4 @@
+import { flagName } from '../flag-name.js';
 // ─── Public API ─────────────────────────────────────────────
 /**
  * Build a util.parseArgs configuration from schema walker output.
@@ -9,6 +10,8 @@
 export function buildParseArgsConfig(metadata, optionMeta, hasArgs) {
     const options = {};
     const longAliasMap = {};
+    const knownKeys = new Set();
+    const booleanKeys = new Set();
     for (const param of metadata) {
         // Map Zod type → parseArgs type
         // boolean → 'boolean' (enables --no-* negation)
@@ -16,6 +19,7 @@ export function buildParseArgsConfig(metadata, optionMeta, hasArgs) {
         const parseArgsType = param.zodType === 'boolean' ? 'boolean' : 'string';
         const optConfig = {
             type: parseArgsType,
+            ...(param.isArray ? { multiple: true } : {}),
         };
         // Extract aliases from meta
         const meta = optionMeta?.[param.name];
@@ -26,7 +30,8 @@ export function buildParseArgsConfig(metadata, optionMeta, hasArgs) {
                     const longName = alias.slice(2);
                     longAliasMap[longName] = param.name;
                     // Register the long alias in parseArgs too
-                    options[longName] = { type: parseArgsType };
+                    options[longName] = { type: parseArgsType, ...(param.isArray ? { multiple: true } : {}) };
+                    knownKeys.add(longName);
                 }
                 else if (alias.startsWith('-') && alias.length === 2) {
                     // Short alias: single char after '-'
@@ -34,12 +39,19 @@ export function buildParseArgsConfig(metadata, optionMeta, hasArgs) {
                 }
             }
         }
-        // Set boolean defaults so parseArgs returns them correctly
-        // For booleans with defaults, pass the default to parseArgs
-        if (parseArgsType === 'boolean' && param.defaultValue !== undefined) {
-            optConfig.default = param.defaultValue;
+        // The flag is registered, not the key: `--darkColor` must stay unknown.
+        // It maps back like any long alias, so `--no-dark-mode` needs nothing else.
+        const flag = flagName(param.name);
+        if (flag !== param.name)
+            longAliasMap[flag] = param.name;
+        // Never pass schema defaults here: a value from parseArgs counts as a CLI
+        // argument and would beat env and config. Zod applies them last.
+        options[flag] = optConfig;
+        knownKeys.add(flag);
+        if (parseArgsType === 'boolean') {
+            booleanKeys.add(flag);
+            knownKeys.add(`no-${flag}`);
         }
-        options[param.name] = optConfig;
     }
     return {
         parseArgsConfig: {
@@ -49,6 +61,8 @@ export function buildParseArgsConfig(metadata, optionMeta, hasArgs) {
             allowNegative: true, // Enable --no-* boolean negation
         },
         longAliasMap,
+        knownKeys,
+        booleanKeys,
     };
 }
 //# sourceMappingURL=parseargs-bridge.js.map

package/dist/parse/parseargs-bridge.js.map

@@ -1 +1 @@
-{"version":3,"file":"parseargs-bridge.js","sourceRoot":"","sources":["../../src/parse/parseargs-bridge.ts"],"names":[],"mappings":"AAiBA,+DAA+D;AAE/D;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CACnC,QAAyB,EACzB,UAAuC,EACvC,OAAiB;IAEjB,MAAM,OAAO,GAA4C,EAAE,CAAC;IAC5D,MAAM,YAAY,GAA2B,EAAE,CAAC;IAEhD,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC9B,gCAAgC;QAChC,gDAAgD;QAChD,0DAA0D;QAC1D,MAAM,aAAa,GAAyB,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC;QAE/F,MAAM,SAAS,GAKX;YACH,IAAI,EAAE,aAAa;SACnB,CAAC;QAEF,4BAA4B;QAC5B,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,IAAI,EAAE,KAAK,EAAE,CAAC;YACjB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBAChC,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC5B,sEAAsE;oBACtE,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;oBAChC,YAAY,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC;oBACpC,2CAA2C;oBAC3C,OAAO,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;gBAC7C,CAAC;qBAAM,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACxD,qCAAqC;oBACrC,SAAS,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBAC5B,CAAC;YACF,CAAC;QACF,CAAC;QAED,2DAA2D;QAC3D,4DAA4D;QAC5D,IAAI,aAAa,KAAK,SAAS,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACrE,SAAS,CAAC,OAAO,GAAG,KAAK,CAAC,YAAuB,CAAC;QACnD,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;IACjC,CAAC;IAED,OAAO;QACN,eAAe,EAAE;YAChB,OAAO;YACP,gBAAgB,EAAE,OAAO,IAAI,KAAK;YAClC,MAAM,EAAE,KAAK,EAAE,uCAAuC;YACtD,aAAa,EAAE,IAAI,EAAE,iCAAiC;SACtD;QACD,YAAY;KACZ,CAAC;AACH,CAAC"}
+{"version":3,"file":"parseargs-bridge.js","sourceRoot":"","sources":["../../src/parse/parseargs-bridge.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAqB3C,+DAA+D;AAE/D;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CACnC,QAAyB,EACzB,UAAuC,EACvC,OAAiB;IAEjB,MAAM,OAAO,GAA4C,EAAE,CAAC;IAC5D,MAAM,YAAY,GAA2B,EAAE,CAAC;IAChD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IACpC,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;IAEtC,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC9B,gCAAgC;QAChC,gDAAgD;QAChD,0DAA0D;QAC1D,MAAM,aAAa,GAAyB,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC;QAE/F,MAAM,SAAS,GAIX;YACH,IAAI,EAAE,aAAa;YACnB,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5C,CAAC;QAEF,4BAA4B;QAC5B,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,IAAI,EAAE,KAAK,EAAE,CAAC;YACjB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBAChC,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC5B,sEAAsE;oBACtE,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;oBAChC,YAAY,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC;oBACpC,2CAA2C;oBAC3C,OAAO,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;oBAC1F,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBACzB,CAAC;qBAAM,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACxD,qCAAqC;oBACrC,SAAS,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBAC5B,CAAC;YACF,CAAC;QACF,CAAC;QAED,wEAAwE;QACxE,4EAA4E;QAC5E,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,IAAI,KAAK,KAAK,CAAC,IAAI;YAAE,YAAY,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC;QAEzD,0EAA0E;QAC1E,iEAAiE;QACjE,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;QAC1B,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpB,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;YACjC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACtB,SAAS,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;QAC7B,CAAC;IACF,CAAC;IAED,OAAO;QACN,eAAe,EAAE;YAChB,OAAO;YACP,gBAAgB,EAAE,OAAO,IAAI,KAAK;YAClC,MAAM,EAAE,KAAK,EAAE,uCAAuC;YACtD,aAAa,EAAE,IAAI,EAAE,iCAAiC;SACtD;QACD,YAAY;QACZ,SAAS;QACT,WAAW;KACX,CAAC;AACH,CAAC"}

package/dist/parse/resolve.d.ts

@@ -3,7 +3,7 @@
  *
  * Merge priority: CLI args > env vars > config file > Zod defaults.
  * Maps positionals to args by insertion order.
- * Pre-coerces number strings before Zod .parse().
+ * Pre-coerces number and boolean strings before Zod .parse().
  */
 import { type ZodType } from 'zod';
 import type { OptionMeta } from '../types.js';
@@ -34,6 +34,35 @@ export interface ResolveOutput {
     parsedArgs: Record<string, unknown>;
     parsedOptions: Record<string, unknown>;
 }
+/**
+ * Decide which tokens after `--` are operands and which stay in ctx.rest
+ * (ADR-0022): they fill the positionals still empty, where a variadic counts
+ * as one. So `lint -- -a -b` fills `files`, while `lint a.ts -- --fix` keeps
+ * `--fix` for ctx.rest.
+ */
+export declare function distributeRest(positionals: string[], rest: string[], argsSchemas: Record<string, ZodType>): {
+    positionals: string[];
+    rest: string[];
+};
+/**
+ * Pre-coerce a string to a number for z.number() fields.
+ * Empty/whitespace-only strings are returned UNCHANGED — Number('') === 0
+ * and Number('  ') === 0 would silently fabricate a value. Leaving the
+ * string intact lets Zod reject it as invalid_type, which flows through
+ * the existing humanizer to a ValidationError (exit 2).
+ *
+ * Exported for unit testing only — not part of the public API (not in index.ts).
+ */
+export declare function coerceNumberValue(value: unknown): unknown;
+/**
+ * Pre-coerce a string to a boolean for z.boolean() fields. Env vars are always
+ * strings, and `--flag=false` also reaches here as one. Anything but
+ * true/false/1/0 is returned UNCHANGED so Zod rejects it instead of guessing:
+ * `MINIFY=quizas` must not silently mean either value.
+ *
+ * Exported for unit testing only — not part of the public API (not in index.ts).
+ */
+export declare function coerceBooleanValue(value: unknown): unknown;
 /**
  * Resolve values from all sources and validate through Zod.
  *
@@ -45,4 +74,18 @@ export interface ResolveOutput {
  * 5. Return typed results or throw ValidationError
  */
 export declare function resolveValues(input: ResolveInput): ResolveOutput;
+export interface ResolveToolInput {
+    /** The call's arguments, as one object */
+    input: Record<string, unknown>;
+    schemas: ResolveInput['schemas'];
+    meta?: ResolveInput['meta'];
+    configValues?: Record<string, unknown>;
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Same resolution as resolveValues, from an object instead of parsed argv. Each
+ * key names its target, so there are no positions, tokens or aliases to read:
+ * arrays, objects and numbers arrive as they are, and data is never a route.
+ */
+export declare function resolveToolInput(toolInput: ResolveToolInput): ResolveOutput;
 //# sourceMappingURL=resolve.d.ts.map

package/dist/parse/resolve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/parse/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAY,KAAK,OAAO,EAAK,MAAM,KAAK,CAAC;AAEhD,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,aAAa,CAAC;AAM7D,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,WAAW,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC5B,qCAAqC;IACrC,eAAe,EAAE,eAAe,CAAC;IACjC,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,sBAAsB;IACtB,OAAO,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,CAAC;IACF,4CAA4C;IAC5C,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;KAAE,CAAC;IAChD,yBAAyB;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,aAAa;IAC7B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAkOD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,CAwDhE"}
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/parse/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAY,KAAK,OAAO,EAAK,MAAM,KAAK,CAAC;AAGhD,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,aAAa,CAAC;AAM7D,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,WAAW,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC5B,qCAAqC;IACrC,eAAe,EAAE,eAAe,CAAC;IACjC,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,sBAAsB;IACtB,OAAO,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,CAAC;IACF,4CAA4C;IAC5C,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;KAAE,CAAC;IAChD,yBAAyB;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,aAAa;IAC7B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AA6DD;;;;;GAKG;AACH,wBAAgB,cAAc,CAC7B,WAAW,EAAE,MAAM,EAAE,EACrB,IAAI,EAAE,MAAM,EAAE,EACd,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC;IAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAW3C;AAID;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKzD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM1D;AAoKD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,CAyBhE;AAED,MAAM,WAAW,gBAAgB;IAChC,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CACzC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,gBAAgB,GAAG,aAAa,CAiC3E"}