optionkit 0.0.1 → 0.0.3

package/dist/optionkit.js

@@ -0,0 +1,663 @@
+import { constants } from 'node:fs';
+import { access, mkdir, readFile, realpath, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { detectPackageManager, installPackage } from '@antfu/install-pkg';
+import { catalog } from './_generated/catalog.js';
+import { importPackageIfAvailable, resolvePackage } from './resolve.js';
+const REQUIRED_CLI_DEPENDENCY_SPECIFIERS = [
+    `fireargs@${catalog.fireargs}`,
+    `zod@${catalog.zod}`,
+];
+const CLEAN_STACK_SPECIFIER = `clean-stack@${catalog['clean-stack']}`;
+const installPromises = new Map();
+const cleanStackPromises = new Map();
+/**
+ * Load the CLI adapter on demand. Every command input is transparently augmented
+ * with environment bindings and conflict-free short flags.
+ */
+export async function createOptionKit(settings = {}) {
+    const packageInfo = await consumingPackage(settings);
+    const loaded = await loadDependencies(packageInfo.root, settings);
+    const environmentPrefix = resolveEnvironmentPrefix(settings.environmentPrefix, settings.projectName ?? packageInfo.name);
+    return {
+        f: createAdapter(loaded.f, loaded.z, environmentPrefix, settings),
+        z: loaded.z,
+        environmentPrefix,
+        packageRoot: packageInfo.root,
+        dependencySource: loaded.source,
+        formatError: error => formatError(error, loaded.cleanStack),
+    };
+}
+async function consumingPackage(settings) {
+    const root = settings.packageRoot
+        ? path.resolve(settings.packageRoot)
+        : await findPackageRoot(await discoveryStart(settings.moduleUrl));
+    const manifest = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+    const name = settings.projectName ?? manifest.name;
+    if (typeof name !== 'string' || name.trim() === '') {
+        throw new TypeError('The consuming package must have a name or set projectName.');
+    }
+    return { name, root };
+}
+async function discoveryStart(moduleUrl) {
+    const candidate = moduleUrl === undefined
+        ? process.argv[1] ?? process.cwd()
+        : moduleUrl instanceof URL || moduleUrl.startsWith('file:')
+            ? fileURLToPath(moduleUrl)
+            : moduleUrl;
+    const absolute = path.resolve(candidate);
+    try {
+        return await realpath(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+async function findPackageRoot(start) {
+    let current;
+    try {
+        current = (await stat(start)).isDirectory() ? start : path.dirname(start);
+    }
+    catch {
+        current = path.extname(start) === '' ? start : path.dirname(start);
+    }
+    while (true) {
+        const manifest = path.join(current, 'package.json');
+        try {
+            await access(manifest, constants.R_OK);
+            return current;
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current) {
+                throw new Error(`Could not find a package.json above ${JSON.stringify(start)}.`);
+            }
+            current = parent;
+        }
+    }
+}
+async function loadDependencies(packageRoot, settings) {
+    const project = await importDependencies(packageRoot);
+    const invocationDirectory = path.resolve(settings.invocationDirectory ?? process.cwd());
+    const detected = await detectPackageManager(invocationDirectory);
+    const packageManager = detected ?? 'npm';
+    const installRoot = path.resolve(settings.cacheDirectory ?? packageRoot);
+    const installSource = settings.cacheDirectory ? 'cache' : 'package-root';
+    if (settings.cacheDirectory)
+        await ensureCachePackage(installRoot);
+    if (project) {
+        const projectCleanStack = await importCleanStack(packageRoot, settings.log);
+        const cleanStack = projectCleanStack ?? await cachedCleanStack(installRoot, packageManager, settings.log);
+        return { ...project, cleanStack, source: 'project' };
+    }
+    let installation = installPromises.get(installRoot);
+    if (!installation) {
+        installation = installAndImport(installRoot, packageManager, installSource, settings.log);
+        installPromises.set(installRoot, installation);
+    }
+    try {
+        return await installation;
+    }
+    catch (error) {
+        installPromises.delete(installRoot);
+        throw error;
+    }
+}
+async function installAndImport(installRoot, packageManager, source, log) {
+    const cleanStack = await cachedCleanStack(installRoot, packageManager, log);
+    const existing = await importDependencies(installRoot);
+    if (existing)
+        return { ...existing, cleanStack, source };
+    log?.('Installing required CLI dependencies.', {
+        installDirectory: installRoot,
+        packages: REQUIRED_CLI_DEPENDENCY_SPECIFIERS,
+        packageManager,
+    });
+    try {
+        await installWithoutSaving(REQUIRED_CLI_DEPENDENCY_SPECIFIERS, installRoot, packageManager);
+    }
+    catch (error) {
+        log?.('Could not install required CLI dependencies.', {
+            error: formatError(error, cleanStack),
+        });
+        throw error;
+    }
+    const installed = await importDependencies(installRoot);
+    if (!installed) {
+        const unresolved = ['fireargs', 'zod'].filter(name => !resolvePackage(name, installRoot));
+        throw new Error(`CLI dependencies were installed but ${unresolved.join(' and ') || 'their exports'} could not be resolved from ${installRoot}.`);
+    }
+    log?.('Required CLI dependencies are ready.', { installDirectory: installRoot });
+    return { ...installed, cleanStack, source };
+}
+async function importDependencies(root) {
+    const [adapter, zod] = await Promise.all([
+        importPackageIfAvailable('fireargs', root),
+        importPackageIfAvailable('zod', root),
+    ]);
+    if (!adapter || !zod)
+        return undefined;
+    const requiredBuilders = ['argument', 'command', 'option', 'program'];
+    if (!adapter.f || requiredBuilders.some(name => typeof adapter.f[name] !== 'function')) {
+        throw new TypeError('The resolved CLI adapter does not expose its required builder functions.');
+    }
+    if (!zod.z || typeof zod.z.object !== 'function') {
+        throw new TypeError('The resolved Zod package does not expose z.object().');
+    }
+    return { f: adapter.f, z: zod.z };
+}
+async function cachedCleanStack(cacheRoot, packageManager, log) {
+    let installation = cleanStackPromises.get(cacheRoot);
+    if (!installation) {
+        installation = installCleanStack(cacheRoot, packageManager, log);
+        cleanStackPromises.set(cacheRoot, installation);
+    }
+    return installation;
+}
+async function installCleanStack(installRoot, packageManager, log) {
+    const existing = await importCleanStack(installRoot, log);
+    if (existing)
+        return existing;
+    log?.('Installing optional stack cleaner.', {
+        installDirectory: installRoot,
+        package: CLEAN_STACK_SPECIFIER,
+        packageManager,
+    });
+    try {
+        await installWithoutSaving(CLEAN_STACK_SPECIFIER, installRoot, packageManager);
+        const installed = await importCleanStack(installRoot, log);
+        if (installed)
+            log?.('Optional stack cleaner is ready.', { installDirectory: installRoot });
+        return installed;
+    }
+    catch (error) {
+        log?.('Optional stack cleaner is unavailable.', { error: formatError(error) });
+        return undefined;
+    }
+}
+async function importCleanStack(root, log) {
+    try {
+        return (await importPackageIfAvailable('clean-stack', root))
+            ?.default;
+    }
+    catch (error) {
+        log?.('Optional stack cleaner could not be loaded.', { error: formatError(error) });
+        return undefined;
+    }
+}
+function formatError(error, cleanStack) {
+    const stack = error instanceof Error
+        ? error.stack ?? `${error.name}: ${error.message}`
+        : String(error);
+    if (!cleanStack)
+        return stack;
+    try {
+        return cleanStack(stack, { pretty: true });
+    }
+    catch {
+        return stack;
+    }
+}
+async function ensureCachePackage(cacheRoot) {
+    await mkdir(cacheRoot, { recursive: true });
+    const manifest = path.join(cacheRoot, 'package.json');
+    try {
+        await writeFile(manifest, `${JSON.stringify({ name: 'optionkit-cli-cache', private: true, type: 'module' }, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST'))
+            throw error;
+    }
+}
+const INSTALL_STATE_FILES = [
+    'package.json',
+    'bun.lock',
+    'bun.lockb',
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    'yarn.lock',
+];
+async function installWithoutSaving(packages, installRoot, packageManager) {
+    const snapshots = new Map();
+    for (const name of INSTALL_STATE_FILES) {
+        const filename = path.join(installRoot, name);
+        try {
+            snapshots.set(filename, await readFile(filename));
+        }
+        catch (error) {
+            if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+                throw error;
+            snapshots.set(filename, undefined);
+        }
+    }
+    try {
+        await installPackage(packages, {
+            additionalArgs: agent => noSaveArguments(agent),
+            cwd: installRoot,
+            packageManager,
+            preferOffline: true,
+            silent: true,
+        });
+    }
+    finally {
+        for (const [filename, content] of snapshots) {
+            if (content)
+                await writeFile(filename, content);
+            else
+                await rm(filename, { force: true });
+        }
+    }
+}
+function noSaveArguments(agent) {
+    if (agent === 'bun')
+        return ['--no-save'];
+    if (agent === 'npm')
+        return ['--no-save', '--package-lock=false'];
+    if (agent === 'pnpm')
+        return ['--lockfile=false'];
+    if (agent === 'yarn')
+        return ['--no-lockfile'];
+    return [];
+}
+function createAdapter(adapter, zod, environmentPrefix, settings) {
+    const environmentBindings = new WeakMap();
+    return {
+        ...adapter,
+        command(configuration = {}) {
+            const { passThroughArguments, ...fireargsConfiguration } = configuration;
+            const passThrough = passThroughArguments === true ||
+                (typeof passThroughArguments === 'object' && passThroughArguments !== null);
+            const builder = adapter.command(passThrough
+                ? {
+                    allowExcessArguments: true,
+                    allowUnknownOption: true,
+                    enablePositionalOptions: true,
+                    jsonOption: false,
+                    llmsOption: false,
+                    passThroughOptions: true,
+                    ...fireargsConfiguration,
+                }
+                : fireargsConfiguration);
+            return {
+                input(schema) {
+                    const commandInput = passThrough
+                        ? addPassThroughArgument(schema, adapter, zod, passThroughArguments)
+                        : schema;
+                    const { adapted, bindings } = adaptInputSchema(commandInput, adapter, zod, environmentPrefix, settings);
+                    const inputBuilder = builder.input(adapted);
+                    return {
+                        output(output) {
+                            const outputBuilder = inputBuilder.output(output);
+                            const attach = (route) => {
+                                environmentBindings.set(route, bindings);
+                                wrapStructuredEnvironment(route, () => bindings);
+                                return route;
+                            };
+                            return {
+                                handler(handler) {
+                                    return attach(outputBuilder.handler(handler));
+                                },
+                                render(render) {
+                                    const handlerBuilder = outputBuilder.render(render);
+                                    return {
+                                        handler(handler) {
+                                            return attach(handlerBuilder.handler(handler));
+                                        },
+                                    };
+                                },
+                            };
+                        },
+                    };
+                },
+            };
+        },
+        program(configuration = {}) {
+            const builder = adapter.program(configuration);
+            return {
+                router(routes) {
+                    const program = builder.router(routes);
+                    wrapStructuredEnvironment(program, (argv, options) => {
+                        const selected = selectedLeaf(program, argv, options);
+                        return selected ? environmentBindings.get(selected) ?? [] : [];
+                    });
+                    return program;
+                },
+            };
+        },
+    };
+}
+function addPassThroughArgument(schema, adapter, zod, configuration) {
+    const object = objectSchema(schema);
+    if ('args' in object.shape) {
+        throw new TypeError('passThroughArguments reserves the input field "args".');
+    }
+    const description = typeof configuration === 'object'
+        ? configuration.description
+        : undefined;
+    const args = adapter.argument().schema(zod.array(zod.string()).default([]).describe(description ?? 'Arguments passed to the executable.'));
+    return object.safeExtend({ args });
+}
+function adaptInputSchema(schema, adapter, zod, environmentPrefix, settings) {
+    const object = objectSchema(schema);
+    const shape = object.shape;
+    const registered = Object.fromEntries(Object.entries(shape).flatMap(([key, field]) => {
+        const configuration = registeredFieldConfiguration(field, zod);
+        return configuration ? [[key, configuration]] : [];
+    }));
+    const configurations = optionConfigurations(shape, environmentPrefix, zod, settings, registered);
+    const fields = Object.fromEntries(Object.entries(shape).map(([key, field]) => {
+        if (registered[key]?.kind === 'argument')
+            return [key, field];
+        return [key, adapter.option(configurations[key]).schema(field)];
+    }));
+    const bindings = Object.entries(configurations).flatMap(([key, configuration]) => {
+        if (configuration.env === undefined ||
+            configuration.parse !== undefined ||
+            structuredValueKind(shape[key], zod) !== 'array')
+            return [];
+        return [{
+                env: configuration.env,
+                name: configuration.name ?? toCliKey(key),
+                short: configuration.short,
+            }];
+    });
+    return {
+        adapted: object.safeExtend(fields),
+        bindings,
+    };
+}
+function objectSchema(schema) {
+    let candidate = schema;
+    while (candidate && typeof candidate === 'object') {
+        if ('shape' in candidate) {
+            const shape = candidate.shape;
+            if (shape && typeof shape === 'object')
+                return candidate;
+        }
+        if (!('unwrap' in candidate) || typeof candidate.unwrap !== 'function')
+            break;
+        candidate = candidate.unwrap();
+    }
+    throw new TypeError('createOptionKit requires a Zod object schema, optionally wrapped as readonly.');
+}
+function resolveEnvironmentPrefix(configured, projectName) {
+    if (configured === false)
+        return false;
+    const translated = toEnvironmentKey(configured ?? projectName);
+    if (!translated)
+        throw new TypeError('The environment prefix must contain a letter or number.');
+    return `${translated}_`;
+}
+function toCliKey(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/gu, '$1-$2')
+        .replace(/([A-Z])([A-Z][a-z])/gu, '$1-$2')
+        .toLowerCase();
+}
+function optionConfigurations(shape, environmentPrefix, zod, settings, registered = {}) {
+    const keys = Object.keys(shape).filter(key => registered[key]?.kind !== 'argument');
+    const overrides = Object.fromEntries(keys.map(key => {
+        const existing = registered[key];
+        const existingOption = existing?.kind === 'option'
+            ? Object.fromEntries(Object.entries(existing).filter(([name]) => name !== 'kind'))
+            : {};
+        return [key, { ...settings.fields?.[key], ...existingOption }];
+    }));
+    const shorts = generatedShortFlags(keys, overrides, settings);
+    return Object.fromEntries(keys.map(key => {
+        const override = overrides?.[key];
+        const generated = {};
+        if (environmentPrefix !== false && override?.env !== false) {
+            generated.env = override?.env ?? `${environmentPrefix}${toEnvironmentKey(key)}`;
+            const kind = structuredValueKind(shape[key], zod);
+            if (kind === 'object' && !override?.parse)
+                generated.parse = structuredValueParser(kind);
+        }
+        if (override?.short !== false && (override?.short ?? shorts[key])) {
+            generated.short = typeof override?.short === 'string'
+                ? normalizeShort(override.short, key)
+                : shorts[key];
+        }
+        if (override) {
+            const { env: _env, short: _short, parse, ...rest } = override;
+            Object.assign(generated, rest);
+            if (parse)
+                generated.parse = parse;
+        }
+        return [key, generated];
+    }));
+}
+function registeredFieldConfiguration(schema, zod, seen = new Set()) {
+    if (seen.has(schema))
+        return undefined;
+    seen.add(schema);
+    const metadata = zod.globalRegistry.get(schema);
+    const registered = metadata?.fireargs;
+    if (registered && typeof registered === 'object' && 'kind' in registered) {
+        const kind = registered.kind;
+        if (kind === 'argument' || kind === 'option') {
+            return registered;
+        }
+    }
+    if (schema instanceof zod.ZodPipe) {
+        return registeredFieldConfiguration(schema.in, zod, seen);
+    }
+    const wrapper = schema;
+    return typeof wrapper.unwrap === 'function'
+        ? registeredFieldConfiguration(wrapper.unwrap(), zod, seen)
+        : undefined;
+}
+/**
+ * Fireargs handles structured argv values, but an environment variable reaches
+ * Commander as one string. Detect only unambiguous JSON containers so scalar
+ * coercion and Fireargs' native parsing remain untouched.
+ */
+function structuredValueKind(schema, zod, seen = new Set()) {
+    if (!schema || seen.has(schema))
+        return undefined;
+    seen.add(schema);
+    if (schema instanceof zod.ZodArray || schema instanceof zod.ZodTuple)
+        return 'array';
+    if (schema instanceof zod.ZodObject || schema instanceof zod.ZodRecord)
+        return 'object';
+    if (schema instanceof zod.ZodUnion) {
+        const kinds = schema.options.map(option => (structuredValueKind(option, zod, new Set(seen)))).filter((kind) => kind !== undefined);
+        const unique = new Set(kinds);
+        return unique.size === 1 ? kinds[0] : undefined;
+    }
+    if (schema instanceof zod.ZodPipe) {
+        return structuredValueKind(schema.in, zod, seen);
+    }
+    const wrapper = schema;
+    return typeof wrapper.unwrap === 'function'
+        ? structuredValueKind(wrapper.unwrap(), zod, seen)
+        : undefined;
+}
+function structuredValueParser(kind) {
+    return ((value) => decodeStructuredValue(value, kind));
+}
+function decodeStructuredValue(value, kind) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        // A non-JSON string may still be useful to an array schema or a union.
+    }
+    return kind === 'array' ? splitArrayValue(value) ?? value : value;
+}
+function wrapStructuredEnvironment(route, bindings) {
+    const parse = route.parseAsync.bind(route);
+    route.parseAsync = async (argv, options) => {
+        const active = bindings(argv, options);
+        if (!active.length)
+            return parse(argv, options);
+        const effectiveArgv = [...(argv ?? process.argv)];
+        const userOffset = argvOffset(options);
+        const userArguments = effectiveArgv.slice(userOffset);
+        const insertion = effectiveArgv.indexOf('--', userOffset);
+        const injected = [];
+        const previous = new Map();
+        for (const binding of active) {
+            const value = process.env[binding.env];
+            if (value === undefined)
+                continue;
+            previous.set(binding.env, value);
+            delete process.env[binding.env];
+            if (hasOption(userArguments, binding))
+                continue;
+            const decoded = decodeStructuredValue(value, 'array');
+            const values = Array.isArray(decoded) ? decoded : [decoded];
+            for (const item of values)
+                injected.push(`--${binding.name}=${stringifyCliValue(item)}`);
+        }
+        effectiveArgv.splice(insertion === -1 ? effectiveArgv.length : insertion, 0, ...injected);
+        try {
+            return await parse(effectiveArgv, options);
+        }
+        finally {
+            for (const [name, value] of previous)
+                process.env[name] = value;
+        }
+    };
+}
+function selectedLeaf(program, argv, options) {
+    const args = (argv ?? process.argv).slice(argvOffset(options));
+    let current = program;
+    let offset = 0;
+    while (current.commands?.length) {
+        let selected;
+        let selectedAt = -1;
+        for (let index = offset; index < args.length; index += 1) {
+            const token = args[index];
+            if (!token || token.startsWith('-'))
+                continue;
+            selected = current.commands.find(command => (command.name?.() === token || command.aliases?.().includes(token)));
+            if (selected) {
+                selectedAt = index;
+                break;
+            }
+        }
+        if (!selected)
+            return undefined;
+        current = selected;
+        offset = selectedAt + 1;
+    }
+    return current;
+}
+function argvOffset(options) {
+    if (options?.from === 'user')
+        return 0;
+    if (options?.from === 'electron')
+        return 1;
+    return 2;
+}
+function hasOption(args, binding) {
+    const long = `--${binding.name}`;
+    const short = binding.short ? `-${binding.short}` : undefined;
+    return args.some(argument => (argument === long ||
+        argument.startsWith(`${long}=`) ||
+        (short !== undefined && (argument === short || argument.startsWith(`${short}=`)))));
+}
+function stringifyCliValue(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value === null || typeof value !== 'object')
+        return String(value);
+    return JSON.stringify(value);
+}
+/** Split comma- or whitespace-delimited shell words without interpreting operators. */
+function splitArrayValue(value) {
+    const result = [];
+    let token = '';
+    let quote;
+    let escaped = false;
+    let started = false;
+    for (const character of value) {
+        if (escaped) {
+            token += character;
+            escaped = false;
+            started = true;
+        }
+        else if (character === '\\') {
+            escaped = true;
+            started = true;
+        }
+        else if (quote) {
+            if (character === quote)
+                quote = undefined;
+            else
+                token += character;
+            started = true;
+        }
+        else if (character === '"' || character === "'") {
+            quote = character;
+            started = true;
+        }
+        else if (character === ',' || /\s/u.test(character)) {
+            if (started)
+                result.push(token);
+            token = '';
+            started = false;
+        }
+        else {
+            token += character;
+            started = true;
+        }
+    }
+    if (quote || escaped)
+        return undefined;
+    if (started)
+        result.push(token);
+    return result;
+}
+function generatedShortFlags(keys, overrides, settings) {
+    if (settings.shortFlags === false)
+        return {};
+    const reserved = new Set(['h', ...(settings.reservedShortFlags ?? [])].map(value => value.toLowerCase()));
+    const explicit = new Map();
+    for (const key of keys) {
+        const value = overrides?.[key]?.short;
+        if (typeof value !== 'string')
+            continue;
+        const normalized = normalizeShort(value, key);
+        const owner = explicit.get(normalized);
+        if (owner)
+            throw new TypeError(`Short flag -${normalized} is configured for both ${owner} and ${key}.`);
+        if (reserved.has(normalized))
+            throw new TypeError(`Short flag -${normalized} is reserved.`);
+        explicit.set(normalized, key);
+    }
+    const candidates = new Map();
+    for (const key of keys) {
+        if (overrides?.[key]?.short !== undefined)
+            continue;
+        const longName = overrides?.[key]?.name ?? key;
+        const candidate = toEnvironmentKey(longName).charAt(0).toLowerCase();
+        if (!candidate || reserved.has(candidate) || explicit.has(candidate))
+            continue;
+        candidates.set(candidate, [...(candidates.get(candidate) ?? []), key]);
+    }
+    const result = {};
+    for (const [candidate, owners] of candidates) {
+        if (owners.length === 1)
+            result[owners[0]] = candidate;
+    }
+    return result;
+}
+function normalizeShort(value, key) {
+    const normalized = value.replace(/^-+/u, '').toLowerCase();
+    if (!/^[a-z0-9]$/u.test(normalized)) {
+        throw new TypeError(`Short flag for ${key} must be one letter or digit.`);
+    }
+    return normalized;
+}
+function toEnvironmentKey(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/gu, '$1_$2')
+        .replace(/^@/u, '')
+        .replace(/[^a-zA-Z0-9]+/gu, '_')
+        .replace(/^_+|_+$/gu, '')
+        .toUpperCase();
+}
+//# sourceMappingURL=optionkit.js.map