burgee 0.5.0 → 0.6.0

package/dist/execute.js

@@ -1,5 +1,6 @@
 import { dirname } from 'node:path';
 import { parseArgs } from 'node:util';
+import { ConfigError, explain, resolve as resolveLayers } from 'seniority';
 import { detectAgent } from './agent.js';
 import { ExitCode, isExitCode } from './exit-code.js';
 import { renderHelp } from './help.js';
@@ -7,7 +8,6 @@ import { Manifest } from './manifest.js';
 import { serveMcp } from './mcp.js';
 import { camel, kebab } from './names.js';
 import { nearestPackage } from './pkg.js';
-import { ConfigError, explain, resolve as resolveLayers } from './precedence.js';
 import { commandSchemaOf, machineJson, schemaOf, summaryOf } from './schema.js';
 import { checkDefinition, checkRelations, coerce, UsageError } from './validate.js';
 function helpFields(c) {
@@ -159,7 +159,7 @@ function packageLayer(pkg, name) {
     return typeof field === 'object' && field !== null && !Array.isArray(field) ? { path: pkg.path, data: field } : undefined;
 }
 async function configLayers(name, values, io) {
-    const { discover } = await import('./config.js');
+    const { discover } = await import('seniority');
     const explicit = values['config'];
     const disabled = values['noConfig'] === true;
     const loaded = await discover({ name, cwd: io.cwd, env: io.env, ...(typeof explicit === 'string' ? { explicit } : {}), disabled });

package/dist/index.d.ts

@@ -11,6 +11,6 @@ export { camel, checkDefinition, kebab, UsageError } from './validate.js';
 export { AGENT_PROBES, detectAgent, type AgentProbe, type Detection } from './agent.js';
 export { renderHelp, type HelpOptions, type HelpTheme, type HelpToken } from './help.js';
 export { annotationsOf, MCP_PROTOCOL_VERSION, serveMcp, toolsOf, type Invoke, type ServeOptions, type Tool, type ToolAnnotations } from './mcp.js';
-export { ConfigError, envName, explain, resolve, screaming, type Candidate, type Layers, type Provenance, type Resolution, type Source } from './precedence.js';
+export { ConfigError, envName, explain, resolve, screaming, type Candidate, type Layers, type Provenance, type Resolution, type Source } from 'seniority';
 export { commandSchemaOf, inputSchemaOf, schemaOf, summaryOf, type CommandSchema, type JsonSchema, type ProgramSchema, type SchemaSummary } from './schema.js';
 export { definePlugin, Manifest, type ArgumentSpec, type CommandNode, type Effects, type Example, type Hook, type LazyModule, type OptionSpec, type ActionRequiredSpec, type Plugin, type Relation, type RunContext, type StandardResult, type StandardSchemaV1, } from './manifest.js';

package/dist/index.js

@@ -4,6 +4,6 @@ export { camel, checkDefinition, kebab, UsageError } from './validate.js';
 export { AGENT_PROBES, detectAgent } from './agent.js';
 export { renderHelp } from './help.js';
 export { annotationsOf, MCP_PROTOCOL_VERSION, serveMcp, toolsOf } from './mcp.js';
-export { ConfigError, envName, explain, resolve, screaming } from './precedence.js';
+export { ConfigError, envName, explain, resolve, screaming } from 'seniority';
 export { commandSchemaOf, inputSchemaOf, schemaOf, summaryOf } from './schema.js';
 export { definePlugin, Manifest, } from './manifest.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "burgee",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "An agent-native CLI framework, drop-in compatible with commander and yargs. One declaration; help, --json, --schema, --mcp and completions all projected from it.",
   "license": "MIT",
   "type": "module",
@@ -96,7 +96,8 @@
     "provenance": true
   },
   "dependencies": {
-    "roundel": "^0.3.0"
+    "roundel": "^0.3.0",
+    "seniority": "^0.1.0"
   },
   "devDependencies": {
     "vitest": "^5.0.0"

package/dist/config.d.ts

@@ -1,28 +0,0 @@
-import { type Layer } from './precedence.js';
-export interface Discovery {
-    name: string;
-    cwd: string;
-    env: Record<string, string | undefined>;
-    /** `--config <path>`. */
-    explicit?: string;
-    /** `--no-config`. */
-    disabled?: boolean;
-}
-export interface Loaded extends Layer {
-    /** The files merged, outermost first — what `--explain` shows. */
-    chain: string[];
-}
-/** Objects merge recursively; anything else, the later value wins. */
-export declare function deepMerge(base: Record<string, unknown>, over: Record<string, unknown>): Record<string, unknown>;
-/** Load a file and everything it extends, outermost first, the file's own keys winning. */
-export declare function loadWithExtends(path: string, seen?: string[]): Promise<Loaded>;
-/** The discovery order as candidate paths, first hit wins; each entry says why it was tried. */
-export declare function candidates(d: Discovery): {
-    path: string;
-    reason: string;
-}[];
-/**
- * Discover and load. `package.json#<name>` is not a file here — the engine reads the
- * owning package.json itself and treats the field as its own layer, below config.
- */
-export declare function discover(d: Discovery): Promise<Loaded | undefined>;

package/dist/config.js

@@ -1,98 +0,0 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { ConfigError } from './precedence.js';
-const EXTENSIONS = ['.json', '.mjs', '.js', '.cjs'];
-const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
-export function deepMerge(base, over) {
-    const out = new Map(Object.entries(base));
-    for (const [k, v] of Object.entries(over)) {
-        const prev = out.get(k);
-        out.set(k, isObject(prev) && isObject(v) ? deepMerge(prev, v) : v);
-    }
-    return Object.fromEntries(out);
-}
-async function loadFile(path) {
-    if (path.endsWith('.json')) {
-        try {
-            const parsed = JSON.parse(readFileSync(path, 'utf8'));
-            if (!isObject(parsed))
-                throw new ConfigError(`${path} must contain an object`);
-            return parsed;
-        }
-        catch (cause) {
-            if (cause instanceof ConfigError)
-                throw cause;
-            throw new ConfigError(`${path} is not valid JSON`, cause instanceof Error ? cause.message : undefined);
-        }
-    }
-    const mod = (await import(pathToFileURL(path).href));
-    const value = typeof mod.default === 'function' ? await mod.default() : mod.default;
-    if (!isObject(value))
-        throw new ConfigError(`${path} must export an object (or a function returning one)`);
-    return value;
-}
-function resolveExtends(spec, from) {
-    if (spec.startsWith('.') || isAbsolute(spec))
-        return resolve(dirname(from), spec);
-    try {
-        return createRequire(from).resolve(spec);
-    }
-    catch {
-        throw new ConfigError(`${from} extends "${spec}", which cannot be resolved`, 'use a relative path or an installed package');
-    }
-}
-function extendsList(value) {
-    if (typeof value === 'string')
-        return [value];
-    return Array.isArray(value) ? value.map(String) : [];
-}
-export async function loadWithExtends(path, seen = []) {
-    if (seen.includes(path))
-        throw new ConfigError(`config extends itself: ${[...seen, path].join(' → ')}`);
-    const own = await loadFile(path);
-    const parents = own['extends'];
-    const specs = extendsList(parents);
-    let data = {};
-    const chain = [];
-    for (const spec of specs) {
-        const parent = await loadWithExtends(resolveExtends(spec, path), [...seen, path]);
-        data = deepMerge(data, parent.data);
-        chain.push(...parent.chain);
-    }
-    const { extends: _ignored, ...rest } = own;
-    return { path, data: deepMerge(data, rest), chain: [...chain, path] };
-}
-const userConfigDir = (env) => {
-    const base = env['XDG_CONFIG_HOME'] ?? (env['HOME'] === undefined ? undefined : join(env['HOME'], '.config'));
-    return base;
-};
-export function candidates(d) {
-    const out = [];
-    const fromEnv = d.env[`${d.name.toUpperCase().replaceAll('-', '_')}_CONFIG`];
-    if (fromEnv !== undefined)
-        out.push({ path: resolve(d.cwd, fromEnv), reason: `${d.name.toUpperCase().replaceAll('-', '_')}_CONFIG` });
-    for (const ext of EXTENSIONS)
-        out.push({ path: join(d.cwd, `${d.name}.config${ext}`), reason: 'current directory' });
-    const user = userConfigDir(d.env);
-    if (user !== undefined)
-        out.push({ path: join(user, d.name, 'config.json'), reason: 'user config directory' });
-    return out;
-}
-export async function discover(d) {
-    if (d.disabled === true)
-        return undefined;
-    if (d.explicit !== undefined) {
-        const path = resolve(d.cwd, d.explicit);
-        if (!existsSync(path))
-            throw new ConfigError(`config file not found: ${path}`, 'check --config, or drop it to use discovery');
-        return await loadWithExtends(path);
-    }
-    const found = candidates(d)
-        .map((c) => c.path)
-        .find((path) => existsSync(path));
-    if (found === undefined)
-        return undefined;
-    return await loadWithExtends(found);
-}

package/dist/precedence.d.ts

@@ -1,55 +0,0 @@
-/**
- * One precedence order, fixed and not configurable (commander-env V1–V3, V5):
- *
- *     flag > env > config file > package.json field > default
- *
- * `resolve` is pure — it takes the layers and returns the values with their provenance —
- * which is what makes `--explain` trustworthy and `meta.provenance` cheap. Env applies
- * only to the options the running command declares (yargs #873), never to a sibling's.
- */
-import { type OptionSpec } from './manifest.js';
-export type Source = 'flag' | 'env' | 'config' | 'package' | 'default';
-export interface Provenance {
-    source: Source;
-    /** The env name, the config file, or `package.json` — where a person would look. */
-    location?: string;
-}
-export interface Candidate {
-    source: Source;
-    location: string;
-    /** `undefined` when the layer had nothing for this option. */
-    value: unknown;
-}
-export interface Layer {
-    path: string;
-    data: Record<string, unknown>;
-}
-export interface Layers {
-    /** What the user typed: only options present on the command line. */
-    flags: Record<string, unknown>;
-    env: Record<string, string | undefined>;
-    /** With a prefix, an option without `env:` reads `PREFIX_OPTION_NAME` (R2). */
-    envPrefix?: string;
-    config?: Layer;
-    /** The `package.json` field named after the program, when present. */
-    pkg?: Layer;
-}
-export interface Resolution {
-    values: Record<string, unknown>;
-    provenance: Record<string, Provenance>;
-    candidates: Record<string, Candidate[]>;
-}
-/** A value that cannot be used as configured: exit CONFIG (3), never a stack (E1, E3). */
-export declare class ConfigError extends Error {
-    readonly hint?: string | undefined;
-    constructor(message: string, hint?: string | undefined);
-}
-/** `region` → `REGION`, `dryRun` → `DRY_RUN`, `log-level` → `LOG_LEVEL` (yargs #2005: never camel-cased back). */
-export declare function screaming(name: string): string;
-export declare function envName(name: string, spec: OptionSpec, prefix: string | undefined): string | undefined;
-/** Booleans from env accept one spelling each way (R7). */
-export declare function envBoolean(raw: string): boolean | undefined;
-/** Every declared option, resolved through the layers; a missing required one is left undefined for the caller to report. */
-export declare function resolve(specs: Record<string, OptionSpec>, layers: Layers): Resolution;
-/** `--explain <option>`: the winning source and every candidate it beat, or that was unset (V3). */
-export declare function explain(name: string, resolution: Resolution): string;

package/dist/precedence.js

@@ -1,100 +0,0 @@
-export class ConfigError extends Error {
-    hint;
-    constructor(message, hint) {
-        super(message);
-        this.hint = hint;
-    }
-}
-export function screaming(name) {
-    return name
-        .replaceAll(/([a-z0-9])([A-Z])/g, '$1_$2')
-        .replaceAll('-', '_')
-        .toUpperCase();
-}
-export function envName(name, spec, prefix) {
-    if (spec.env !== undefined)
-        return spec.env;
-    return prefix === undefined ? undefined : `${prefix}_${screaming(name)}`;
-}
-const TRUE = new Set(['1', 'true', 'yes']);
-const FALSE = new Set(['0', 'false', 'no']);
-export function envBoolean(raw) {
-    const v = raw.trim().toLowerCase();
-    if (TRUE.has(v))
-        return true;
-    if (FALSE.has(v))
-        return false;
-    return undefined;
-}
-function fromEnv(name, spec, layers) {
-    const variable = envName(name, spec, layers.envPrefix);
-    if (variable === undefined)
-        return undefined;
-    if (spec.type === 'boolean' && layers.envPrefix !== undefined) {
-        const negated = `${layers.envPrefix}_NO_${screaming(name)}`;
-        if (layers.env[negated] !== undefined) {
-            throw new ConfigError(`${negated} is not supported`, `set ${variable}=false instead`);
-        }
-    }
-    const raw = layers.env[variable];
-    if (raw === undefined)
-        return { source: 'env', location: variable, value: undefined };
-    if (spec.type !== 'boolean')
-        return { source: 'env', location: variable, value: raw };
-    const parsed = envBoolean(raw);
-    if (parsed === undefined)
-        throw new ConfigError(`${variable}="${raw}" is not a boolean`, `use ${variable}=true or ${variable}=false`);
-    return { source: 'env', location: variable, value: parsed };
-}
-function candidatesFor(name, spec, layers) {
-    const out = [{ source: 'flag', location: `--${name}`, value: layers.flags[name] }];
-    const env = fromEnv(name, spec, layers);
-    if (env !== undefined)
-        out.push(env);
-    if (layers.config !== undefined)
-        out.push({ source: 'config', location: layers.config.path, value: layers.config.data[name] });
-    if (layers.pkg !== undefined)
-        out.push({ source: 'package', location: layers.pkg.path, value: layers.pkg.data[name] });
-    out.push({ source: 'default', location: 'default', value: spec.default });
-    return out;
-}
-export function resolve(specs, layers) {
-    const values = new Map();
-    const provenance = new Map();
-    const candidates = new Map();
-    for (const [name, spec] of Object.entries(specs)) {
-        const list = candidatesFor(name, spec, layers);
-        candidates.set(name, list);
-        const winner = list.find((c) => c.value !== undefined);
-        if (winner === undefined)
-            continue;
-        values.set(name, winner.value);
-        provenance.set(name, winner.source === 'default' ? { source: 'default' } : { source: winner.source, location: winner.location });
-    }
-    return { values: Object.fromEntries(values), provenance: Object.fromEntries(provenance), candidates: Object.fromEntries(candidates) };
-}
-const describe = (c) => {
-    switch (c.source) {
-        case 'flag':
-            return `flag ${c.location}`;
-        case 'env':
-            return `env ${c.location}`;
-        case 'config':
-            return `config file ${c.location}`;
-        case 'package':
-            return `package.json field in ${c.location}`;
-        case 'default':
-            return 'default';
-    }
-};
-export function explain(name, resolution) {
-    const list = resolution.candidates[name];
-    if (list === undefined)
-        return `${name} is not an option of this command\n`;
-    const winner = list.find((c) => c.value !== undefined);
-    const head = winner === undefined ? `${name} is unset` : `${name} = ${JSON.stringify(winner.value)}   from ${describe(winner)}`;
-    const rest = list
-        .filter((c) => c !== winner)
-        .map((c) => `${describe(c)} ${c.value === undefined ? '(unset)' : JSON.stringify(c.value)}`);
-    return `${head}\n${rest.length === 0 ? '' : `         candidates: ${rest.join(', ')}\n`}`;
-}