burgee 0.5.0 → 0.6.1

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/dist/yargs/cliui.d.ts

@@ -1,21 +1,17 @@
+import { type WrapOptions } from "linegauge";
 /**
- * cliui 9 — the column layout yargs' usage renders through — with the string-width,
- * strip-ansi and wrap-ansi it depends on, ported for `burgee/yargs`. The wrapping
+ * cliui 9 — the column layout yargs' usage renders through — with the wrap-ansi it depends
+ * on, ported for `burgee/yargs`. Width and escape-stripping come from linegauge. The wrapping
  * arithmetic is byte-for-byte the upstream's: yargs' usage tests compare whole help
  * screens.
  */
-export declare function stripAnsi(str: string): string;
-export declare function stringWidth(input: string): number;
-interface WrapOptions {
-    hard?: boolean;
-    wordWrap?: boolean;
-    trim?: boolean;
-}
+export declare const stripAnsi: (str: string) => string;
+export declare const stringWidth: (input: string) => number;
 export declare function wrapAnsi(string: string, columns: number, options?: WrapOptions): string;
 export interface Column {
     text: string;
     width?: number | undefined;
-    align?: 'right' | 'left' | 'center';
+    align?: "right" | "left" | "center";
     padding: number[];
     border?: boolean;
 }

package/dist/yargs/cliui.js

@@ -1,221 +1,36 @@
+import { strip, width, wrap } from "linegauge";
 /**
- * cliui 9 — the column layout yargs' usage renders through — with the string-width,
- * strip-ansi and wrap-ansi it depends on, ported for `burgee/yargs`. The wrapping
+ * cliui 9 — the column layout yargs' usage renders through — with the wrap-ansi it depends
+ * on, ported for `burgee/yargs`. Width and escape-stripping come from linegauge. The wrapping
  * arithmetic is byte-for-byte the upstream's: yargs' usage tests compare whole help
  * screens.
  */
-const ANSI_PATTERN = '[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]+)*|[a-zA-Z\\d]+(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?\\u0007)|(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-ntqry=><~]))';
-export function stripAnsi(str) {
-    return typeof str === 'string' ? str.replace(new RegExp(ANSI_PATTERN, 'g'), '') : str;
-}
-const segmenter = new Intl.Segmenter();
-const EMOJI = new RegExp('^\\p{RGI_Emoji}$', 'v');
-function isWide(code) {
-    return ((code >= 0x1100 && code <= 0x115f) ||
-        code === 0x2329 ||
-        code === 0x232a ||
-        (code >= 0x2e80 && code <= 0x303e) ||
-        (code >= 0x3041 && code <= 0x33ff) ||
-        (code >= 0x3400 && code <= 0x4dbf) ||
-        (code >= 0x4e00 && code <= 0x9fff) ||
-        (code >= 0xa000 && code <= 0xa4cf) ||
-        (code >= 0xa960 && code <= 0xa97f) ||
-        (code >= 0xac00 && code <= 0xd7a3) ||
-        (code >= 0xf900 && code <= 0xfaff) ||
-        (code >= 0xfe10 && code <= 0xfe19) ||
-        (code >= 0xfe30 && code <= 0xfe6f) ||
-        (code >= 0xff00 && code <= 0xff60) ||
-        (code >= 0xffe0 && code <= 0xffe6) ||
-        (code >= 0x1f300 && code <= 0x1f64f) ||
-        (code >= 0x1f900 && code <= 0x1f9ff) ||
-        (code >= 0x20000 && code <= 0x3fffd));
-}
-export function stringWidth(input) {
-    if (typeof input !== 'string' || input.length === 0)
-        return 0;
-    const string = stripAnsi(input);
-    if (string.length === 0)
-        return 0;
-    let width = 0;
-    for (const { segment } of segmenter.segment(string)) {
-        const code = segment.codePointAt(0);
-        if (code <= 0x1f || (code >= 0x7f && code <= 0x9f))
-            continue;
-        if ((code >= 0x200b && code <= 0x200f) || code === 0xfeff)
-            continue;
-        if (code >= 0x300 && code <= 0x36f)
-            continue;
-        if (EMOJI.test(segment)) {
-            width += 2;
-            continue;
-        }
-        width += isWide(code) ? 2 : 1;
-    }
-    return width;
-}
-/** ansi-styles' open→close map, the part wrap-ansi reads. */
-function closeCode(code) {
-    if (code === 1 || code === 2)
-        return 22;
-    if (code === 3)
-        return 23;
-    if (code === 4)
-        return 24;
-    if (code === 7)
-        return 27;
-    if (code === 8)
-        return 28;
-    if (code === 9)
-        return 29;
-    if ((code >= 30 && code <= 37) || (code >= 90 && code <= 97))
-        return 39;
-    if ((code >= 40 && code <= 47) || (code >= 100 && code <= 107))
-        return 49;
-    return undefined;
-}
-const ESC = '\u001B';
-const ESCAPES = new Set([ESC, '\u009B']);
-const END_CODE = 39;
-const ANSI_ESCAPE_BELL = '\u0007';
-const ANSI_CSI = '[';
-const ANSI_OSC = ']';
-const ANSI_SGR_TERMINATOR = 'm';
-const ANSI_ESCAPE_LINK = `${ANSI_OSC}8;;`;
-const wrapAnsiCode = (code) => `${ESC}${ANSI_CSI}${code}${ANSI_SGR_TERMINATOR}`;
-const wrapAnsiHyperlink = (uri) => `${ESC}${ANSI_ESCAPE_LINK}${uri}${ANSI_ESCAPE_BELL}`;
-const wordLengths = (string) => string.split(' ').map((character) => stringWidth(character));
-function wrapWord(rows, word, columns) {
-    const characters = [...word];
-    let isInsideEscape = false;
-    let isInsideLinkEscape = false;
-    let visible = stringWidth(stripAnsi(rows.at(-1)));
-    for (const [index, character] of characters.entries()) {
-        const characterLength = stringWidth(character);
-        if (visible + characterLength <= columns)
-            rows[rows.length - 1] += character;
-        else {
-            rows.push(character);
-            visible = 0;
-        }
-        if (ESCAPES.has(character)) {
-            isInsideEscape = true;
-            isInsideLinkEscape = characters.slice(index + 1).join('').startsWith(ANSI_ESCAPE_LINK);
-        }
-        if (isInsideEscape) {
-            if (isInsideLinkEscape) {
-                if (character === ANSI_ESCAPE_BELL) {
-                    isInsideEscape = false;
-                    isInsideLinkEscape = false;
-                }
-            }
-            else if (character === ANSI_SGR_TERMINATOR)
-                isInsideEscape = false;
-            continue;
-        }
-        visible += characterLength;
-        if (visible === columns && index < characters.length - 1) {
-            rows.push('');
-            visible = 0;
-        }
-    }
-    if (!visible && rows.at(-1).length > 0 && rows.length > 1)
-        rows[rows.length - 2] += rows.pop();
-}
-function stringVisibleTrimSpacesRight(string) {
-    const words = string.split(' ');
-    let last = words.length;
-    while (last > 0) {
-        if (stringWidth(words[last - 1]) > 0)
-            break;
-        last--;
-    }
-    if (last === words.length)
-        return string;
-    return words.slice(0, last).join(' ') + words.slice(last).join('');
-}
-function execWrap(string, columns, options = {}) {
-    if (options.trim !== false && string.trim() === '')
-        return '';
-    let returnValue = '';
-    let escapeCode;
-    let escapeUrl;
-    const lengths = wordLengths(string);
-    let rows = [''];
-    for (const [index, word] of string.split(' ').entries()) {
-        if (options.trim !== false)
-            rows[rows.length - 1] = rows.at(-1).trimStart();
-        let rowLength = stringWidth(rows.at(-1));
-        if (index !== 0) {
-            if (rowLength >= columns && (options.wordWrap === false || options.trim === false)) {
-                rows.push('');
-                rowLength = 0;
-            }
-            if (rowLength > 0 || options.trim === false) {
-                rows[rows.length - 1] += ' ';
-                rowLength++;
-            }
-        }
-        const length = lengths[index];
-        if (options.hard && length > columns) {
-            const remainingColumns = columns - rowLength;
-            const breaksStartingThisLine = 1 + Math.floor((length - remainingColumns - 1) / columns);
-            const breaksStartingNextLine = Math.floor((length - 1) / columns);
-            if (breaksStartingNextLine < breaksStartingThisLine)
-                rows.push('');
-            wrapWord(rows, word, columns);
-            continue;
-        }
-        if (rowLength + length > columns && rowLength > 0 && length > 0) {
-            if (options.wordWrap === false && rowLength < columns) {
-                wrapWord(rows, word, columns);
-                continue;
-            }
-            rows.push('');
-        }
-        if (rowLength + length > columns && options.wordWrap === false) {
-            wrapWord(rows, word, columns);
-            continue;
-        }
-        rows[rows.length - 1] += word;
-    }
-    if (options.trim !== false)
-        rows = rows.map(stringVisibleTrimSpacesRight);
-    const pre = [...rows.join('\n')];
-    for (const [index, character] of pre.entries()) {
-        returnValue += character;
-        if (ESCAPES.has(character)) {
-            const found = new RegExp(`(?:\\${ANSI_CSI}(?<code>\\d+)m|\\${ANSI_ESCAPE_LINK}(?<uri>.*)${ANSI_ESCAPE_BELL})`).exec(pre.slice(index).join(''));
-            const groups = found?.groups ?? {};
-            if (groups.code !== undefined) {
-                const code = Number.parseFloat(groups.code);
-                escapeCode = code === END_CODE ? undefined : code;
-            }
-            else if (groups.uri !== undefined)
-                escapeUrl = groups.uri.length === 0 ? undefined : groups.uri;
-        }
-        const code = closeCode(Number(escapeCode));
-        if (pre[index + 1] === '\n') {
-            if (escapeUrl)
-                returnValue += wrapAnsiHyperlink('');
-            if (escapeCode && code)
-                returnValue += wrapAnsiCode(code);
-        }
-        else if (character === '\n') {
-            if (escapeCode && code)
-                returnValue += wrapAnsiCode(escapeCode);
-            if (escapeUrl)
-                returnValue += wrapAnsiHyperlink(escapeUrl);
-        }
-    }
-    return returnValue;
-}
+/*
+ * `width` and `strip` are linegauge's — measuring text and removing escapes is the layer
+ * below this one, and this file had its own copies of both. They were not merely duplicated,
+ * they were wrong: the ITU T.416 sub-parameter form `ESC[38:2::255:0:0m`, which chalk emits
+ * for truecolor, left `:2::255:0:0m` behind and measured a 13-column string as 25. linegauge
+ * fixed that in its own `strip`; burgee inherited nothing because it was not asking.
+ *
+ * The names stay, because `usage.ts` and `shim.ts` import them and the upstream port reads
+ * the way cliui reads.
+ */
+export const stripAnsi = (str) => typeof str === "string" ? strip(str) : str;
+export const stringWidth = (input) => typeof input === "string" ? width(input) : 0;
+/*
+ * The wrap is linegauge's too. This file carried a wrap-ansi port — ansi-styles' open→close
+ * map, an escape-state machine over every character, hyperlink re-opening — to wrap a line
+ * without breaking the styling across it. That is the same job `linegauge/wrap` exists for
+ * and grades against wrap-ansi, so burgee kept a second implementation of a thing the layer
+ * below already owned.
+ *
+ * Checked before swapping, because yargs' usage tests compare whole help screens: the two
+ * agreed on all ten shapes probed — plain prose at several widths, an unbreakable word,
+ * SGR-coloured text, single characters, CJK, an embedded newline, leading and trailing
+ * spaces, empty, and a string exactly the column width.
+ */
 export function wrapAnsi(string, columns, options) {
-    return String(string)
-        .normalize()
-        .replace(/\r\n/g, '\n')
-        .split('\n')
-        .map((line) => execWrap(line, columns, options))
-        .join('\n');
+    return wrap(String(string).normalize().replace(/\r\n/g, "\n"), columns, options);
 }
 const align = { right: alignRight, center: alignCenter };
 const top = 0;
@@ -240,21 +55,24 @@ export class UI {
     }
     div(...args) {
         if (args.length === 0)
-            this.div('');
-        if (this.wrap && this.shouldApplyLayoutDSL(...args) && typeof args[0] === 'string')
+            this.div("");
+        if (this.wrap &&
+            this.shouldApplyLayoutDSL(...args) &&
+            typeof args[0] === "string")
             return this.applyLayoutDSL(args[0]);
-        const cols = args.map((arg) => (typeof arg === 'string' ? this.colFromString(arg) : arg));
+        const cols = args.map((arg) => typeof arg === "string" ? this.colFromString(arg) : arg);
         this.rows.push(cols);
         return cols;
     }
     shouldApplyLayoutDSL(...args) {
-        return args.length === 1 && typeof args[0] === 'string' && /[\t\n]/.test(args[0]);
+        return (args.length === 1 && typeof args[0] === "string" && /[\t\n]/.test(args[0]));
     }
     applyLayoutDSL(str) {
-        const rows = str.split('\n').map((row) => row.split('\t'));
+        const rows = str.split("\n").map((row) => row.split("\t"));
         let leftColumnWidth = 0;
         rows.forEach((columns) => {
-            if (columns.length > 1 && stringWidth(columns[0]) > leftColumnWidth) {
+            if (columns.length > 1 &&
+                stringWidth(columns[0]) > leftColumnWidth) {
                 leftColumnWidth = Math.min(Math.floor(this.width * 0.5), stringWidth(columns[0]));
             }
         });
@@ -271,8 +89,20 @@ export class UI {
         return { text, padding: this.measurePadding(text) };
     }
     measurePadding(str) {
+        // An unanchored `\s*$` was the upstream spelling, and it is quadratic: the engine
+        // retries at every position, so a cell of 50,000 spaces then an `x` costs 1,346 ms
+        // here — CodeQL alert 35, "polynomial regular expression used on uncontrolled data",
+        // raised once `stripAnsi` became library input. Spaces, not the tabs the alert names:
+        // a tab routes into `applyLayoutDSL`, which splits on it long before this runs.
+        // `trim{Start,End}` remove exactly the set `\s` matches (WhiteSpace + LineTerminator)
+        // and are linear, so this is the same measurement without the backtracking.
         const noAnsi = stripAnsi(str);
-        return [0, /\s*$/.exec(noAnsi)[0].length, 0, /^\s*/.exec(noAnsi)[0].length];
+        return [
+            0,
+            noAnsi.length - noAnsi.trimEnd().length,
+            0,
+            noAnsi.length - noAnsi.trimStart().length,
+        ];
     }
     toString() {
         const lines = [];
@@ -282,36 +112,36 @@ export class UI {
         return lines
             .filter((line) => !line.hidden)
             .map((line) => line.text)
-            .join('\n');
+            .join("\n");
     }
     rowToString(row, lines) {
         this.rasterize(row).forEach((rrow, r) => {
-            let str = '';
+            let str = "";
             rrow.forEach((col, c) => {
                 const column = row[c];
                 const { width } = column;
                 const wrapWidth = this.negatePadding(column);
                 let ts = col;
                 if (wrapWidth > stringWidth(col))
-                    ts += ' '.repeat(wrapWidth - stringWidth(col));
-                if (column.align && column.align !== 'left' && this.wrap) {
+                    ts += " ".repeat(wrapWidth - stringWidth(col));
+                if (column.align && column.align !== "left" && this.wrap) {
                     const fn = align[column.align];
                     ts = fn(ts, wrapWidth);
                     if (stringWidth(ts) < wrapWidth)
-                        ts += ' '.repeat((width || 0) - stringWidth(ts) - 1);
+                        ts += " ".repeat((width || 0) - stringWidth(ts) - 1);
                 }
                 const padding = column.padding || [0, 0, 0, 0];
                 if (padding[left])
-                    str += ' '.repeat(padding[left]);
-                str += addBorder(column, ts, '| ');
+                    str += " ".repeat(padding[left]);
+                str += addBorder(column, ts, "| ");
                 str += ts;
-                str += addBorder(column, ts, ' |');
+                str += addBorder(column, ts, " |");
                 if (padding[right])
-                    str += ' '.repeat(padding[right]);
+                    str += " ".repeat(padding[right]);
                 if (r === 0 && lines.length > 0)
                     str = this.renderInline(str, lines.at(-1));
             });
-            lines.push({ text: str.replace(/ +$/, ''), span: row.span });
+            lines.push({ text: str.replace(/ +$/, ""), span: row.span });
         });
         return lines;
     }
@@ -329,7 +159,9 @@ export class UI {
         if (leadingWhitespace < targetTextWidth)
             return source;
         previousLine.hidden = true;
-        return target.trimEnd() + ' '.repeat(leadingWhitespace - targetTextWidth) + source.trimStart();
+        return (target.trimEnd() +
+            " ".repeat(leadingWhitespace - targetTextWidth) +
+            source.trimStart());
     }
     rasterize(row) {
         const rrows = [];
@@ -338,16 +170,18 @@ export class UI {
         row.forEach((col, c) => {
             col.width = widths[c];
             if (this.wrap)
-                wrapped = wrapAnsi(col.text, this.negatePadding(col), { hard: true }).split('\n');
+                wrapped = wrapAnsi(col.text, this.negatePadding(col), {
+                    hard: true,
+                }).split("\n");
             else
-                wrapped = col.text.split('\n');
+                wrapped = col.text.split("\n");
             if (col.border) {
-                wrapped.unshift(`.${'-'.repeat(this.negatePadding(col) + 2)}.`);
-                wrapped.push(`'${'-'.repeat(this.negatePadding(col) + 2)}'`);
+                wrapped.unshift(`.${"-".repeat(this.negatePadding(col) + 2)}.`);
+                wrapped.push(`'${"-".repeat(this.negatePadding(col) + 2)}'`);
             }
             if (col.padding) {
-                wrapped.unshift(...new Array(col.padding[top] || 0).fill(''));
-                wrapped.push(...new Array(col.padding[bottom] || 0).fill(''));
+                wrapped.unshift(...new Array(col.padding[top] || 0).fill(""));
+                wrapped.push(...new Array(col.padding[bottom] || 0).fill(""));
             }
             wrapped.forEach((str, r) => {
                 if (!rrows[r])
@@ -355,7 +189,7 @@ export class UI {
                 const rrow = rrows[r];
                 for (let i = 0; i < c; i++) {
                     if (rrow[i] === undefined)
-                        rrow.push('');
+                        rrow.push("");
                 }
                 rrow.push(str);
             });
@@ -384,18 +218,18 @@ export class UI {
             return undefined;
         });
         const unsetWidth = unset ? Math.floor(remainingWidth / unset) : 0;
-        return widths.map((w, i) => (w === undefined ? Math.max(unsetWidth, minWidth(row[i])) : w));
+        return widths.map((w, i) => w === undefined ? Math.max(unsetWidth, minWidth(row[i])) : w);
     }
 }
 function addBorder(col, ts, style) {
     if (col.border) {
         if (/[.']-+[.']/.test(ts))
-            return '';
+            return "";
         if (ts.trim().length !== 0)
             return style;
-        return '  ';
+        return "  ";
     }
-    return '';
+    return "";
 }
 function minWidth(col) {
     const padding = col.padding || [];
@@ -405,7 +239,7 @@ function minWidth(col) {
     return min;
 }
 function getWindowWidth() {
-    if (typeof process === 'object' && process.stdout && process.stdout.columns)
+    if (typeof process === "object" && process.stdout && process.stdout.columns)
         return process.stdout.columns;
     return 80;
 }
@@ -413,7 +247,7 @@ function alignRight(str, width) {
     str = str.trim();
     const strWidth = stringWidth(str);
     if (strWidth < width)
-        return ' '.repeat(width - strWidth) + str;
+        return " ".repeat(width - strWidth) + str;
     return str;
 }
 function alignCenter(str, width) {
@@ -421,7 +255,7 @@ function alignCenter(str, width) {
     const strWidth = stringWidth(str);
     if (strWidth >= width)
         return str;
-    return ' '.repeat((width - strWidth) >> 1) + str;
+    return " ".repeat((width - strWidth) >> 1) + str;
 }
 export function cliui(opts) {
     return new UI({ width: opts?.width || getWindowWidth(), wrap: opts?.wrap });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "burgee",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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,9 @@
     "provenance": true
   },
   "dependencies": {
-    "roundel": "^0.3.0"
+    "linegauge": "^0.2.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`}`;
-}