@runa-cmd/core 0.1.0

package/dist/parse/resolve.js

@@ -0,0 +1,240 @@
+/**
+ * @runa-cmd/core — Value resolution pipeline
+ *
+ * Merge priority: CLI args > env vars > config file > Zod defaults.
+ * Maps positionals to args by insertion order.
+ * Pre-coerces number strings before Zod .parse().
+ */
+import { ZodError, z } from 'zod';
+import { ValidationError } from '../errors.js';
+import { walkSchema } from './schema-walker.js';
+import { isVariadic } from './variadic.js';
+// ─── Positional Mapping ─────────────────────────────────────
+function mapPositionals(positionals, argsSchemas) {
+    const keys = Object.keys(argsSchemas);
+    const result = {};
+    if (keys.length === 0) {
+        // No args defined but positionals provided
+        if (positionals.length > 0) {
+            throw new ValidationError([
+                {
+                    code: 'custom',
+                    message: `Unexpected positional argument: '${positionals[0]}'`,
+                    path: [],
+                },
+            ]);
+        }
+        return result;
+    }
+    // Check if last arg is variadic
+    const lastKey = keys[keys.length - 1];
+    if (!lastKey)
+        return result;
+    const lastSchema = argsSchemas[lastKey];
+    const lastIsVariadic = lastSchema ? isVariadic(lastSchema) : false;
+    const fixedCount = lastIsVariadic ? keys.length - 1 : keys.length;
+    // Check for extra positionals without variadic
+    if (!lastIsVariadic && positionals.length > keys.length) {
+        throw new ValidationError([
+            {
+                code: 'custom',
+                message: `Unexpected positional argument: '${positionals[keys.length]}'`,
+                path: [],
+            },
+        ]);
+    }
+    // Map fixed positionals
+    for (let i = 0; i < fixedCount; i++) {
+        const key = keys[i];
+        if (!key)
+            continue;
+        if (i < positionals.length) {
+            result[key] = positionals[i];
+        }
+        // If not provided, omit — let Zod handle required/optional validation
+    }
+    // Map variadic (remaining positionals go to last key as array)
+    if (lastIsVariadic) {
+        result[lastKey] = positionals.slice(fixedCount);
+    }
+    return result;
+}
+// ─── Value Resolution ───────────────────────────────────────
+function resolveOptionValues(parseArgsValues, longAliasMap, optionsSchemas, optionsMeta, configValues, env, optionsMetadata) {
+    const resolved = {};
+    // Build a set of number fields for pre-coercion
+    const numberFields = new Set();
+    for (const meta of optionsMetadata) {
+        if (meta.zodType === 'number') {
+            numberFields.add(meta.name);
+        }
+    }
+    // First, apply long alias mappings to parseArgs values
+    const normalizedValues = { ...parseArgsValues };
+    for (const [alias, canonical] of Object.entries(longAliasMap)) {
+        if (alias in normalizedValues && !(canonical in normalizedValues)) {
+            normalizedValues[canonical] = normalizedValues[alias];
+            delete normalizedValues[alias];
+        }
+    }
+    for (const key of Object.keys(optionsSchemas)) {
+        // Priority 1: CLI arg
+        if (key in normalizedValues && normalizedValues[key] !== undefined) {
+            let value = normalizedValues[key];
+            // Pre-coerce numbers from string
+            if (numberFields.has(key) && typeof value === 'string') {
+                const num = Number(value);
+                if (!Number.isNaN(num)) {
+                    value = num;
+                }
+            }
+            resolved[key] = value;
+            continue;
+        }
+        // Priority 2: Environment variable
+        const envName = optionsMeta?.[key]?.env;
+        if (envName && envName in env && env[envName] !== undefined) {
+            let value = env[envName];
+            // Pre-coerce numbers from string
+            if (numberFields.has(key) && typeof value === 'string') {
+                const num = Number(value);
+                if (!Number.isNaN(num)) {
+                    value = num;
+                }
+            }
+            resolved[key] = value;
+            continue;
+        }
+        // Priority 3: Config file value
+        if (configValues && key in configValues && configValues[key] !== undefined) {
+            let value = configValues[key];
+            // Pre-coerce numbers from string (config values are usually already typed,
+            // but defensive handling)
+            if (numberFields.has(key) && typeof value === 'string') {
+                const num = Number(value);
+                if (!Number.isNaN(num)) {
+                    value = num;
+                }
+            }
+            resolved[key] = value;
+        }
+        // Priority 4: Omit — let Zod .default() handle it
+    }
+    return resolved;
+}
+/**
+ * Rewrite Zod issues into user-friendly CLI error messages.
+ * Handles common cases: missing required args/options, invalid enums, wrong types.
+ */
+function humanizeArgIssues(issues, argsSchemas) {
+    const metadata = walkSchema(argsSchemas);
+    const metaByName = new Map(metadata.map((m) => [m.name, m]));
+    return issues.map((issue) => {
+        const name = issue.path[0];
+        if (typeof name !== 'string')
+            return issue;
+        const param = metaByName.get(name);
+        // Missing required arg: Zod v4 produces "Invalid input: expected X, received undefined"
+        if (issue.code === 'invalid_type' && issue.message.includes('received undefined')) {
+            return {
+                code: 'custom',
+                message: `Missing required argument: <${name}>${param?.description ? ` — ${param.description}` : ''}`,
+                path: issue.path,
+            };
+        }
+        // Invalid enum value (Zod v4 uses 'invalid_value' for enums)
+        if (issue.code === 'invalid_value' && param?.enumValues) {
+            return {
+                code: 'custom',
+                message: `Invalid value for <${name}>. Expected one of: ${param.enumValues.join(', ')}`,
+                path: issue.path,
+            };
+        }
+        return issue;
+    });
+}
+function humanizeOptionIssues(issues, optionsSchemas) {
+    const metadata = walkSchema(optionsSchemas);
+    const metaByName = new Map(metadata.map((m) => [m.name, m]));
+    return issues.map((issue) => {
+        const name = issue.path[0];
+        if (typeof name !== 'string')
+            return issue;
+        const param = metaByName.get(name);
+        // Missing required option
+        if (issue.code === 'invalid_type' && issue.message.includes('received undefined')) {
+            return {
+                code: 'custom',
+                message: `Missing required option: --${name}${param?.description ? ` — ${param.description}` : ''}`,
+                path: issue.path,
+            };
+        }
+        // Invalid enum value
+        if (issue.code === 'invalid_value' && param?.enumValues) {
+            return {
+                code: 'custom',
+                message: `Invalid value for --${name}. Expected one of: ${param.enumValues.join(', ')}`,
+                path: issue.path,
+            };
+        }
+        // Wrong type (e.g. expected number, got string)
+        if (issue.code === 'invalid_type') {
+            const expected = issue.expected;
+            return {
+                code: 'custom',
+                message: `Invalid value for --${name}: expected ${String(expected)}`,
+                path: issue.path,
+            };
+        }
+        return issue;
+    });
+}
+// ─── Public API ─────────────────────────────────────────────
+/**
+ * Resolve values from all sources and validate through Zod.
+ *
+ * Pipeline:
+ * 1. Map positionals to args by insertion order
+ * 2. Merge option values (CLI > env > config)
+ * 3. Pre-coerce number strings
+ * 4. Validate through Zod schemas
+ * 5. Return typed results or throw ValidationError
+ */
+export function resolveValues(input) {
+    const { parseArgsResult, longAliasMap = {}, schemas, meta, configValues, env = process.env, } = input;
+    // ─── Args resolution ─────────────────────────────────
+    let parsedArgs = {};
+    if (schemas.args && Object.keys(schemas.args).length > 0) {
+        const rawArgs = mapPositionals(parseArgsResult.positionals, schemas.args);
+        // Build Zod object schema for args and validate
+        const argsZodSchema = z.object(schemas.args);
+        try {
+            parsedArgs = argsZodSchema.parse(rawArgs);
+        }
+        catch (err) {
+            if (err instanceof ZodError) {
+                throw new ValidationError(humanizeArgIssues(err.issues, schemas.args));
+            }
+            throw err;
+        }
+    }
+    // ─── Options resolution ──────────────────────────────
+    let parsedOptions = {};
+    if (schemas.options && Object.keys(schemas.options).length > 0) {
+        const optionsMetadata = walkSchema(schemas.options);
+        const rawOptions = resolveOptionValues(parseArgsResult.values, longAliasMap, schemas.options, meta?.options, configValues, env, optionsMetadata);
+        // Build Zod object schema for options and validate
+        const optionsZodSchema = z.object(schemas.options);
+        try {
+            parsedOptions = optionsZodSchema.parse(rawOptions);
+        }
+        catch (err) {
+            if (err instanceof ZodError) {
+                throw new ValidationError(humanizeOptionIssues(err.issues, schemas.options));
+            }
+            throw err;
+        }
+    }
+    return { parsedArgs, parsedOptions };
+}
+//# sourceMappingURL=resolve.js.map

package/dist/parse/resolve.js.map

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

package/dist/parse/schema-walker.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @runa-cmd/core — Zod Schema Walker
+ *
+ * Walks Zod schemas to extract parameter metadata (type, default, required,
+ * description, enum values, variadic). This is the ONLY module that accesses
+ * Zod v4 internal `._zod.def` — if Zod changes internals, only this file
+ * needs updating.
+ */
+import type { ZodType } from 'zod';
+import type { ParamMetadata } from '../types.js';
+/**
+ * Walk a record of Zod schemas and extract parameter metadata for each key.
+ * Keys are returned in insertion order (Object.entries preserves it).
+ */
+export declare function walkSchema(schemas: Record<string, ZodType>): ParamMetadata[];
+/**
+ * Walk a single Zod schema and extract its metadata.
+ * Used by other modules that need to inspect individual schemas.
+ */
+export declare function walkSingleSchema(name: string, schema: ZodType): ParamMetadata;
+//# sourceMappingURL=schema-walker.d.ts.map

package/dist/parse/schema-walker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-walker.d.ts","sourceRoot":"","sources":["../../src/parse/schema-walker.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAa,MAAM,aAAa,CAAC;AA6I5D;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,EAAE,CAmB5E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,aAAa,CAa7E"}

package/dist/parse/schema-walker.js

@@ -0,0 +1,121 @@
+// ─── 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;
+    }
+    // If we found a default via the wrapper, keep it.
+    // If not, defaultValue stays undefined.
+    return {
+        baseSchema: current,
+        baseDef: getZodDef(current),
+        isOptional,
+        defaultValue: hasDefault ? defaultValue : undefined,
+        description,
+    };
+}
+// ─── Detect base type ───────────────────────────────────────
+function detectParamType(def) {
+    switch (def.type) {
+        case 'string':
+            return { zodType: 'string' };
+        case 'number':
+        case 'int':
+            return { zodType: 'number' };
+        case 'boolean':
+            return { zodType: '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 { zodType: 'enum', enumValues: values };
+        }
+        case 'array':
+            return { zodType: 'array' };
+        default:
+            // Fallback: treat unknown types as string
+            return { zodType: 'string' };
+    }
+}
+// ─── Public API ─────────────────────────────────────────────
+/**
+ * Walk a record of Zod schemas and extract parameter metadata for each key.
+ * Keys are returned in insertion order (Object.entries preserves it).
+ */
+export function walkSchema(schemas) {
+    const result = [];
+    for (const [name, schema] of Object.entries(schemas)) {
+        const { baseDef, isOptional, defaultValue, description } = unwrapSchema(schema);
+        const { zodType, enumValues } = detectParamType(baseDef);
+        result.push({
+            name,
+            zodType,
+            isOptional,
+            defaultValue,
+            isArray: zodType === 'array',
+            enumValues,
+            description,
+        });
+    }
+    return result;
+}
+/**
+ * Walk a single Zod schema and extract its metadata.
+ * Used by other modules that need to inspect individual schemas.
+ */
+export function walkSingleSchema(name, schema) {
+    const { baseDef, isOptional, defaultValue, description } = unwrapSchema(schema);
+    const { zodType, enumValues } = detectParamType(baseDef);
+    return {
+        name,
+        zodType,
+        isOptional,
+        defaultValue,
+        isArray: zodType === 'array',
+        enumValues,
+        description,
+    };
+}
+//# sourceMappingURL=schema-walker.js.map

package/dist/parse/schema-walker.js.map

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

package/dist/parse/variadic.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @runa-cmd/core — Variadic arg validation
+ *
+ * Validates that z.array() positional args appear only as the last arg
+ * and that at most one variadic arg exists per command.
+ * These checks run at definition time (when defineCommand() is called).
+ */
+import type { ZodType } from 'zod';
+/**
+ * Check if a Zod schema is a z.array() type.
+ * Unwraps optional/default/nullable wrappers to find the base type.
+ */
+export declare function isVariadic(schema: ZodType): boolean;
+/**
+ * Validate variadic arg constraints:
+ * 1. z.array() is only allowed as the LAST positional arg
+ * 2. At most one z.array() per command
+ *
+ * Throws RunaError at definition time if constraints are violated.
+ */
+export declare function validateVariadicArgs(args: Record<string, ZodType>): void;
+//# sourceMappingURL=variadic.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"variadic.d.ts","sourceRoot":"","sources":["../../src/parse/variadic.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAsBnC;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAyBnD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAsCxE"}

package/dist/parse/variadic.js

@@ -0,0 +1,71 @@
+import { RunaError } from '../errors.js';
+function getDefType(schema) {
+    const s = schema;
+    return s._zod?.def?.type ?? 'unknown';
+}
+// ─── Public API ─────────────────────────────────────────────
+/**
+ * Check if a Zod schema is a z.array() type.
+ * Unwraps optional/default/nullable wrappers to find the base type.
+ */
+export function isVariadic(schema) {
+    let current = schema;
+    const maxDepth = 10;
+    for (let i = 0; i < maxDepth; i++) {
+        const defType = getDefType(current);
+        if (defType === 'array') {
+            return true;
+        }
+        // Unwrap wrappers
+        if (defType === 'optional' || defType === 'default' || defType === 'nullable') {
+            const s = current;
+            const inner = s._zod?.def?.innerType;
+            if (inner) {
+                current = inner;
+                continue;
+            }
+        }
+        return false;
+    }
+    return false;
+}
+/**
+ * Validate variadic arg constraints:
+ * 1. z.array() is only allowed as the LAST positional arg
+ * 2. At most one z.array() per command
+ *
+ * Throws RunaError at definition time if constraints are violated.
+ */
+export function validateVariadicArgs(args) {
+    const keys = Object.keys(args);
+    const arrayIndices = [];
+    for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        if (!key)
+            continue;
+        const schema = args[key];
+        if (schema && isVariadic(schema)) {
+            arrayIndices.push({ name: key, index: i });
+        }
+    }
+    // No arrays → valid
+    if (arrayIndices.length === 0) {
+        return;
+    }
+    // Multiple arrays → invalid
+    if (arrayIndices.length > 1) {
+        const names = arrayIndices.map((a) => `'${a.name}'`).join(', ');
+        throw new RunaError(`Only one variadic arg is allowed per command. Found: ${names}.`, {
+            code: 'INVALID_VARIADIC_ARGS',
+            exitCode: 1,
+        });
+    }
+    // Single array but not in last position → invalid
+    const arrayEntry = arrayIndices[0];
+    if (arrayEntry && arrayEntry.index !== keys.length - 1) {
+        throw new RunaError(`Variadic arg '${arrayEntry.name}' must be the last positional argument. ` +
+            `Found at position ${arrayEntry.index} of ${keys.length}.`, { code: 'INVALID_VARIADIC_POSITION', exitCode: 1 });
+    }
+    // Single array in last position → valid
+}
+//# sourceMappingURL=variadic.js.map

package/dist/parse/variadic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variadic.js","sourceRoot":"","sources":["../../src/parse/variadic.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAczC,SAAS,UAAU,CAAC,MAAe;IAClC,MAAM,CAAC,GAAG,MAA2C,CAAC;IACtD,OAAO,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,IAAI,SAAS,CAAC;AACvC,CAAC;AAED,+DAA+D;AAE/D;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAAe;IACzC,IAAI,OAAO,GAAG,MAAM,CAAC;IACrB,MAAM,QAAQ,GAAG,EAAE,CAAC;IAEpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;QAEpC,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC;QACb,CAAC;QAED,kBAAkB;QAClB,IAAI,OAAO,KAAK,UAAU,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;YAC/E,MAAM,CAAC,GAAG,OAA4C,CAAC;YACvD,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,SAAS,CAAC;YACrC,IAAI,KAAK,EAAE,CAAC;gBACX,OAAO,GAAG,KAAK,CAAC;gBAChB,SAAS;YACV,CAAC;QACF,CAAC;QAED,OAAO,KAAK,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAA6B;IACjE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,YAAY,GAA2C,EAAE,CAAC;IAEhE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,MAAM,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAClC,YAAY,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;QAC5C,CAAC;IACF,CAAC;IAED,oBAAoB;IACpB,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO;IACR,CAAC;IAED,4BAA4B;IAC5B,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChE,MAAM,IAAI,SAAS,CAAC,wDAAwD,KAAK,GAAG,EAAE;YACrF,IAAI,EAAE,uBAAuB;YAC7B,QAAQ,EAAE,CAAC;SACX,CAAC,CAAC;IACJ,CAAC;IAED,kDAAkD;IAClD,MAAM,UAAU,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,UAAU,IAAI,UAAU,CAAC,KAAK,KAAK,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,SAAS,CAClB,iBAAiB,UAAU,CAAC,IAAI,0CAA0C;YACzE,qBAAqB,UAAU,CAAC,KAAK,OAAO,IAAI,CAAC,MAAM,GAAG,EAC3D,EAAE,IAAI,EAAE,2BAA2B,EAAE,QAAQ,EAAE,CAAC,EAAE,CAClD,CAAC;IACH,CAAC;IAED,wCAAwC;AACzC,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @runa-cmd/core — Plugin system
+ *
+ * definePlugin() — validate and return plugin config
+ * Plugin host — resolve lazy imports, topological sort, setup/cleanup orchestration
+ * Capability validation via PluginAPI proxy
+ */
+import type { ZodType } from 'zod';
+import type { CLISchema, CommandTree, HookHandler, HookName, Middleware, OptionMeta, PluginAPI, PluginCapabilities, PluginConfig } from './types.js';
+/**
+ * Validate and return a PluginConfig.
+ * Passthrough with shape validation — ensures required fields exist.
+ */
+export declare function definePlugin(config: PluginConfig): PluginConfig;
+type PluginInput = PluginConfig | (() => Promise<{
+    default: PluginConfig;
+}>);
+/**
+ * Resolve a list of plugin inputs (direct configs or lazy imports)
+ * into resolved PluginConfig objects.
+ */
+export declare function resolvePlugins(plugins: PluginInput[]): Promise<PluginConfig[]>;
+/**
+ * Sort plugins in dependency order using Kahn's algorithm.
+ * Detects circular dependencies and missing dependencies.
+ */
+export declare function topologicalSort(plugins: PluginConfig[]): PluginConfig[];
+export interface PluginHostRefs {
+    commands: CommandTree;
+    globalOptions: Record<string, ZodType>;
+    globalMeta: {
+        options: Record<string, OptionMeta>;
+    };
+    middleware: Middleware[];
+    hookRegister: (name: HookName, handler: HookHandler) => void;
+    getSchema: () => CLISchema;
+}
+/**
+ * Create a PluginAPI for a specific plugin, enforcing capability checks.
+ */
+export declare function createPluginAPI(pluginName: string, capabilities: PluginCapabilities | undefined, refs: PluginHostRefs): PluginAPI;
+/**
+ * Call setup(api) for each plugin in topological order.
+ */
+export declare function runPluginSetup(plugins: PluginConfig[], refs: PluginHostRefs): Promise<void>;
+/**
+ * Call cleanup() for each plugin in REVERSE topological order.
+ * Each cleanup is wrapped in try/catch — failures don't prevent others from running.
+ * Returns collected errors.
+ */
+export declare function runPluginCleanup(plugins: PluginConfig[]): Promise<Error[]>;
+export {};
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,OAAO,KAAK,EACX,SAAS,EAET,WAAW,EACX,WAAW,EACX,QAAQ,EACR,UAAU,EACV,UAAU,EACV,SAAS,EACT,kBAAkB,EAClB,YAAY,EACZ,MAAM,YAAY,CAAC;AAIpB;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAc/D;AAID,KAAK,WAAW,GAAG,YAAY,GAAG,CAAC,MAAM,OAAO,CAAC;IAAE,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC,CAAC;AAE7E;;;GAGG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CA2BpF;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAmEvE;AAID,MAAM,WAAW,cAAc;IAC9B,QAAQ,EAAE,WAAW,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,UAAU,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;KAAE,CAAC;IACpD,UAAU,EAAE,UAAU,EAAE,CAAC;IACzB,YAAY,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;IAC7D,SAAS,EAAE,MAAM,SAAS,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC9B,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,kBAAkB,GAAG,SAAS,EAC5C,IAAI,EAAE,cAAc,GAClB,SAAS,CAkDX;AAID;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAKjG;AAID;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAiBhF"}