@skillit/core 1.5.0

package/dist/canonical.js

@@ -0,0 +1,148 @@
+/**
+ * Canonicalization pass — deterministic post-render normalization.
+ *
+ * Operates on `RenderedSkill` (string content), NOT on the `ExtractedSkill` IR.
+ *
+ * Division of responsibility (see specs/001-mcp-extract-bundle/research.md §2):
+ *   - Array ordering of tools/resources/prompts is the ADAPTER's job. Each
+ *     adapter emits items in sorted order directly from the IR. We do NOT
+ *     parse rendered markdown sections and reorder entries here — that would
+ *     be the wrong layer.
+ *   - This module handles the post-render invariants that any adapter's
+ *     output should satisfy to be content-identical across runs:
+ *       1. YAML frontmatter key sort
+ *       2. Line endings normalized to LF
+ *       3. Trailing whitespace trimmed per line
+ *       4. Runs of 2+ blank lines collapsed to 1
+ *       5. Optional regex-based pattern stripping (e.g., timestamps)
+ *
+ * Must be idempotent: `canonicalize(canonicalize(x))` equals `canonicalize(x)`.
+ *
+ * @module canonical
+ */
+import YAML from 'yaml';
+/**
+ * Normalize a `RenderedSkill` so repeat runs produce content-identical output.
+ *
+ * @param skill - rendered skill to normalize; input is not mutated
+ * @param opts - optional pattern list for stripping nondeterministic prose fragments
+ * @returns new `RenderedSkill` with canonicalized content
+ */
+export function canonicalize(skill, opts) {
+    return {
+        skill: canonicalizeFile(skill.skill, opts),
+        references: skill.references.map((f) => canonicalizeFile(f, opts))
+    };
+}
+function canonicalizeFile(file, opts) {
+    return {
+        filename: file.filename,
+        content: canonicalizeContent(file.content, opts),
+        tokens: file.tokens
+    };
+}
+function canonicalizeContent(content, opts) {
+    // 1. Line endings: normalize CRLF / CR to LF up front.
+    let normalized = content.replace(/\r\n?/g, '\n');
+    // 2. Frontmatter key sort (if a leading YAML block is present).
+    const fmMatch = normalized.match(/^---\n([\s\S]*?)\n---(\n|$)/);
+    if (fmMatch && fmMatch[1] !== undefined) {
+        const rawFrontmatter = fmMatch[1];
+        const sortedFrontmatter = sortFrontmatter(rawFrontmatter);
+        const rest = normalized.slice(fmMatch[0].length);
+        normalized = `---\n${sortedFrontmatter}\n---\n${rest}`;
+    }
+    // 3. Optional pattern stripping (e.g., timestamps).
+    if (opts?.stripPatterns) {
+        for (const pattern of opts.stripPatterns) {
+            // Preserve pattern as-is; callers own whether it's global.
+            normalized = normalized.replace(pattern, '');
+        }
+    }
+    // 4. Whitespace normalization.
+    //    - Trim trailing whitespace on each line.
+    //    - Collapse runs of 2+ blank lines to a single blank line.
+    const lines = normalized.split('\n').map((line) => line.replace(/[ \t]+$/, ''));
+    const collapsed = [];
+    let blankRun = 0;
+    for (const line of lines) {
+        if (line === '') {
+            blankRun += 1;
+            if (blankRun <= 1)
+                collapsed.push(line);
+        }
+        else {
+            blankRun = 0;
+            collapsed.push(line);
+        }
+    }
+    return collapsed.join('\n');
+}
+/**
+ * Sort keys in a YAML frontmatter block alphabetically while preserving the
+ * original line formatting (quote style, indentation, block-vs-flow) for each
+ * value.
+ *
+ * Strategy: split the block into top-level key "chunks" — a line starting with
+ * `<key>:` at column 0, plus all subsequent lines that are either blank or
+ * indented (continuations, block scalar bodies, nested mappings, arrays).
+ * Sort chunks by key; rejoin. This round-trips losslessly because we never
+ * re-serialize the values.
+ *
+ * If the frontmatter cannot be parsed as a simple top-level mapping (e.g. it's
+ * a scalar or sequence at the root, or there are no top-level key lines), we
+ * leave the block untouched. The `yaml` package still validates it — we parse
+ * once to confirm it's a mapping, then discard the parsed value.
+ */
+function sortFrontmatter(raw) {
+    // Confirm the block parses to a mapping before attempting a line-based sort.
+    let parsed;
+    try {
+        parsed = YAML.parse(raw);
+    }
+    catch {
+        return raw; // malformed — preserve as-is (whitespace pass still applies)
+    }
+    if (parsed === null ||
+        parsed === undefined ||
+        typeof parsed !== 'object' ||
+        Array.isArray(parsed)) {
+        return raw;
+    }
+    const lines = raw.split('\n');
+    // Group lines into chunks keyed by the first top-level `key:` we see.
+    // A top-level key line matches: starts with a non-space character, contains `:`,
+    // with key made of characters permitted in a YAML plain scalar key.
+    const topLevelKeyRe = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:/;
+    const chunks = [];
+    let preamble = []; // lines before the first key (usually empty)
+    let current = null;
+    for (const line of lines) {
+        const m = line.match(topLevelKeyRe);
+        if (m && !line.startsWith(' ') && !line.startsWith('\t')) {
+            // New top-level key starts here.
+            if (current)
+                chunks.push(current);
+            current = { key: m[1], lines: [line] };
+        }
+        else if (current) {
+            current.lines.push(line);
+        }
+        else {
+            preamble.push(line);
+        }
+    }
+    if (current)
+        chunks.push(current);
+    if (chunks.length === 0)
+        return raw;
+    chunks.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    const out = [...preamble];
+    for (const chunk of chunks)
+        out.push(...chunk.lines);
+    // Drop any trailing empty strings that arose from the original's trailing \n.
+    while (out.length > 0 && out[out.length - 1] === '')
+        out.pop();
+    return out.join('\n');
+}
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

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

package/dist/config-renderer.d.ts

@@ -0,0 +1,16 @@
+import type { ExtractedConfigSurface } from './config-types.js';
+/**
+ * Render ExtractedConfigSurface[] as SKILL.md inline sections.
+ *
+ * CLI surfaces → ## Commands
+ * Config/env surfaces → ## Configuration
+ */
+export declare function renderConfigSurfaceSection(surfaces: ExtractedConfigSurface[] | undefined): string;
+/**
+ * Render ExtractedConfigSurface[] as per-option detail for reference files.
+ *
+ * CLI surfaces → # Commands with ## commandName / #### --flag
+ * Config/env surfaces → # Configuration with ## InterfaceName / #### propertyName
+ */
+export declare function renderConfigReference(surfaces: ExtractedConfigSurface[] | undefined): string;
+//# sourceMappingURL=config-renderer.d.ts.map

package/dist/config-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-renderer.d.ts","sourceRoot":"","sources":["../src/config-renderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAyB,MAAM,mBAAmB,CAAC;AAMvF;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,sBAAsB,EAAE,GAAG,SAAS,GAAG,MAAM,CAiBjG;AA8HD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,sBAAsB,EAAE,GAAG,SAAS,GAAG,MAAM,CAiB5F"}

package/dist/config-renderer.js

@@ -0,0 +1,296 @@
+// ---------------------------------------------------------------------------
+// Inline SKILL.md sections
+// ---------------------------------------------------------------------------
+/**
+ * Render ExtractedConfigSurface[] as SKILL.md inline sections.
+ *
+ * CLI surfaces → ## Commands
+ * Config/env surfaces → ## Configuration
+ */
+export function renderConfigSurfaceSection(surfaces) {
+    if (!surfaces || surfaces.length === 0)
+        return '';
+    const cli = surfaces.filter((s) => s.sourceType === 'cli');
+    const config = surfaces.filter((s) => s.sourceType !== 'cli');
+    const parts = [];
+    if (cli.length > 0) {
+        parts.push(renderCommandsSection(cli));
+    }
+    if (config.length > 0) {
+        parts.push(renderConfigSection(config));
+    }
+    return parts.join('\n\n');
+}
+function renderCommandsSection(surfaces) {
+    const lines = ['## Commands'];
+    for (const surface of surfaces) {
+        lines.push('');
+        lines.push(`### ${surface.name}`);
+        if (surface.description) {
+            lines.push('');
+            lines.push(surface.description);
+        }
+        if (surface.usage) {
+            lines.push('');
+            lines.push('**Usage:**');
+            lines.push('```');
+            lines.push(surface.usage);
+            lines.push('```');
+        }
+        if (surface.options.length > 0) {
+            lines.push('');
+            lines.push(renderOptionsTable(surface.options, 'cli'));
+        }
+        if (surface.arguments && surface.arguments.length > 0) {
+            lines.push('');
+            lines.push('**Arguments:**');
+            for (const arg of surface.arguments) {
+                const req = arg.required ? ' *(required)*' : '';
+                const def = arg.defaultValue ? ` — default: \`${arg.defaultValue}\`` : '';
+                const desc = arg.description ? ` — ${arg.description}` : '';
+                lines.push(`- \`${arg.name}\`${req}${def}${desc}`);
+            }
+        }
+        if (surface.useWhen && surface.useWhen.length > 0) {
+            lines.push('');
+            lines.push('**Use when:**');
+            for (const item of surface.useWhen) {
+                lines.push(`- ${item}`);
+            }
+        }
+        if (surface.avoidWhen && surface.avoidWhen.length > 0) {
+            lines.push('');
+            lines.push('**Avoid when:**');
+            for (const item of surface.avoidWhen) {
+                lines.push(`- ${item}`);
+            }
+        }
+        if (surface.pitfalls && surface.pitfalls.length > 0) {
+            lines.push('');
+            lines.push('**Pitfalls:**');
+            for (const item of surface.pitfalls) {
+                lines.push(`- ${item}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+function renderConfigSection(surfaces) {
+    const lines = ['## Configuration'];
+    // Config tables always go in references/config.md — SKILL.md gets a compact pointer.
+    // A single config surface: show name + description + option count + pitfalls.
+    // Multiple config surfaces: just point to the reference file.
+    if (surfaces.length === 1) {
+        const s = surfaces[0];
+        const desc = s.description ? ` — ${s.description}` : '';
+        lines.push('');
+        lines.push(`**${s.name}**${desc} (${s.options.length} options — see references/config.md)`);
+        if (s.pitfalls && s.pitfalls.length > 0) {
+            lines.push('');
+            lines.push('**Pitfalls:**');
+            for (const item of s.pitfalls) {
+                lines.push(`- ${item}`);
+            }
+        }
+        return lines.join('\n');
+    }
+    // Multiple surfaces: skip the bullet list — just point to config.md
+    lines.push('');
+    lines.push(`${surfaces.length} configuration interfaces — see references/config.md for details.`);
+    return lines.join('\n');
+}
+function renderOptionsTable(options, mode) {
+    const flagCol = mode === 'cli' ? 'Flag' : 'Key';
+    const rows = [
+        `| ${flagCol} | Type | Required | Default | Env | Description |`,
+        `| --- | --- | --- | --- | --- | --- |`
+    ];
+    for (const opt of options) {
+        const key = mode === 'cli'
+            ? opt.cliShort
+                ? `\`${opt.cliFlag}\` / \`${opt.cliShort}\``
+                : `\`${opt.cliFlag ?? opt.name}\``
+            : `\`${opt.configKey ?? opt.name}\``;
+        const required = opt.required ? 'yes' : 'no';
+        const def = opt.defaultValue ? `\`${opt.defaultValue}\`` : '—';
+        const env = opt.envVar ? `\`${opt.envVar}\`` : '—';
+        const desc = opt.description.replace(/\|/g, '\\|');
+        rows.push(`| ${key} | \`${opt.type}\` | ${required} | ${def} | ${env} | ${desc} |`);
+    }
+    return rows.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Detailed reference files
+// ---------------------------------------------------------------------------
+/**
+ * Render ExtractedConfigSurface[] as per-option detail for reference files.
+ *
+ * CLI surfaces → # Commands with ## commandName / #### --flag
+ * Config/env surfaces → # Configuration with ## InterfaceName / #### propertyName
+ */
+export function renderConfigReference(surfaces) {
+    if (!surfaces || surfaces.length === 0)
+        return '';
+    const cli = surfaces.filter((s) => s.sourceType === 'cli');
+    const config = surfaces.filter((s) => s.sourceType !== 'cli');
+    const parts = [];
+    if (cli.length > 0) {
+        parts.push(renderCommandsReference(cli));
+    }
+    if (config.length > 0) {
+        parts.push(renderConfigDetailReference(config));
+    }
+    return parts.join('\n\n');
+}
+function renderCommandsReference(surfaces) {
+    const lines = ['# Commands'];
+    for (const surface of surfaces) {
+        lines.push('');
+        lines.push(`## ${surface.name}`);
+        if (surface.description) {
+            lines.push('');
+            lines.push(surface.description);
+        }
+        if (surface.usage) {
+            lines.push('');
+            lines.push('```');
+            lines.push(surface.usage);
+            lines.push('```');
+        }
+        if (surface.remarks) {
+            lines.push('');
+            lines.push(surface.remarks);
+        }
+        if (surface.options.length > 0) {
+            lines.push('');
+            lines.push('### Options');
+            for (const opt of surface.options) {
+                const heading = opt.cliFlag ?? `--${opt.name}`;
+                lines.push('');
+                lines.push(`#### ${heading}`);
+                renderOptionDetail(opt, lines);
+            }
+        }
+        if (surface.arguments && surface.arguments.length > 0) {
+            lines.push('');
+            lines.push('### Arguments');
+            for (const arg of surface.arguments) {
+                lines.push('');
+                lines.push(`#### \`${arg.name}\``);
+                lines.push('');
+                lines.push(arg.description);
+                if (arg.required) {
+                    lines.push('');
+                    lines.push('**Required:** yes');
+                }
+                if (arg.variadic) {
+                    lines.push('');
+                    lines.push('**Variadic:** yes');
+                }
+                if (arg.defaultValue) {
+                    lines.push('');
+                    lines.push(`**Default:** \`${arg.defaultValue}\``);
+                }
+            }
+        }
+        if (surface.useWhen && surface.useWhen.length > 0) {
+            lines.push('');
+            lines.push('### Use when');
+            for (const item of surface.useWhen) {
+                lines.push(`- ${item}`);
+            }
+        }
+        if (surface.pitfalls && surface.pitfalls.length > 0) {
+            lines.push('');
+            lines.push('### NEVER');
+            for (const item of surface.pitfalls) {
+                lines.push(`- ${item}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+function renderConfigDetailReference(surfaces) {
+    const lines = ['# Configuration'];
+    for (const surface of surfaces) {
+        lines.push('');
+        lines.push(`## ${surface.name}`);
+        if (surface.description) {
+            lines.push('');
+            lines.push(surface.description);
+        }
+        if (surface.remarks) {
+            lines.push('');
+            lines.push(surface.remarks);
+        }
+        if (surface.options.length > 0) {
+            lines.push('');
+            lines.push('### Properties');
+            for (const opt of surface.options) {
+                const heading = opt.configKey ?? opt.name;
+                lines.push('');
+                lines.push(`#### ${heading}`);
+                renderOptionDetail(opt, lines);
+            }
+        }
+        if (surface.useWhen && surface.useWhen.length > 0) {
+            lines.push('');
+            lines.push('### Use when');
+            for (const item of surface.useWhen) {
+                lines.push(`- ${item}`);
+            }
+        }
+        if (surface.pitfalls && surface.pitfalls.length > 0) {
+            lines.push('');
+            lines.push('### NEVER');
+            for (const item of surface.pitfalls) {
+                lines.push(`- ${item}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+function renderOptionDetail(opt, lines) {
+    lines.push('');
+    lines.push(opt.description);
+    lines.push('');
+    lines.push(`**Type:** \`${opt.type}\``);
+    if (opt.required) {
+        lines.push('');
+        lines.push('**Required:** yes');
+    }
+    if (opt.defaultValue) {
+        lines.push('');
+        lines.push(`**Default:** \`${opt.defaultValue}\``);
+    }
+    if (opt.envVar) {
+        lines.push('');
+        lines.push(`**Environment:** \`${opt.envVar}\``);
+    }
+    if (opt.remarks) {
+        lines.push('');
+        lines.push(opt.remarks);
+    }
+    if (opt.useWhen && opt.useWhen.length > 0) {
+        lines.push('');
+        lines.push('**Use when:**');
+        for (const item of opt.useWhen) {
+            lines.push(`- ${item}`);
+        }
+    }
+    if (opt.avoidWhen && opt.avoidWhen.length > 0) {
+        lines.push('');
+        lines.push('**Avoid when:**');
+        for (const item of opt.avoidWhen) {
+            lines.push(`- ${item}`);
+        }
+    }
+    if (opt.pitfalls && opt.pitfalls.length > 0) {
+        lines.push('');
+        lines.push('**Pitfalls:**');
+        for (const item of opt.pitfalls) {
+            lines.push(`- ${item}`);
+        }
+    }
+}
+//# sourceMappingURL=config-renderer.js.map

package/dist/config-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-renderer.js","sourceRoot":"","sources":["../src/config-renderer.ts"],"names":[],"mappings":"AAEA,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAA8C;IACvF,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAElD,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,KAAK,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,KAAK,CAAC,CAAC;IAE9D,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnB,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC;IACzC,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAED,SAAS,qBAAqB,CAAC,QAAkC;IAC/D,MAAM,KAAK,GAAa,CAAC,aAAa,CAAC,CAAC;IAExC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAElC,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;YACxB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAClC,CAAC;QAED,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACzB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAClB,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC1B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;QAED,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;QACzD,CAAC;QAED,IAAI,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YAC7B,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;gBACpC,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChD,MAAM,GAAG,GAAG,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,iBAAiB,GAAG,CAAC,YAAY,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC1E,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC5D,KAAK,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,IAAI,KAAK,GAAG,GAAG,GAAG,GAAG,IAAI,EAAE,CAAC,CAAC;YACrD,CAAC;QACH,CAAC;QAED,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;YAC5B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;gBACnC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;QAED,IAAI,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;YAC9B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;gBACrC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;QAED,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;YAC5B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;gBACpC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,mBAAmB,CAAC,QAAkC;IAC7D,MAAM,KAAK,GAAa,CAAC,kBAAkB,CAAC,CAAC;IAE7C,qFAAqF;IACrF,8EAA8E;IAC9E,8DAA8D;IAC9D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAE,CAAC;QACvB,MAAM,IAAI,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,IAAI,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,sCAAsC,CAAC,CAAC;QAE5F,IAAI,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;YAC5B,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;gBAC9B,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,oEAAoE;IACpE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,mEAAmE,CAAC,CAAC;IAClG,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,kBAAkB,CAAC,OAAgC,EAAE,IAAsB;IAClF,MAAM,OAAO,GAAG,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;IAEhD,MAAM,IAAI,GAAa;QACrB,KAAK,OAAO,oDAAoD;QAChE,uCAAuC;KACxC,CAAC;IAEF,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,MAAM,GAAG,GACP,IAAI,KAAK,KAAK;YACZ,CAAC,CAAC,GAAG,CAAC,QAAQ;gBACZ,CAAC,CAAC,KAAK,GAAG,CAAC,OAAO,UAAU,GAAG,CAAC,QAAQ,IAAI;gBAC5C,CAAC,CAAC,KAAK,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,IAAI,IAAI;YACpC,CAAC,CAAC,KAAK,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC;QAEzC,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;QAC7C,MAAM,GAAG,GAAG,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,YAAY,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;QAC/D,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;QACnD,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAEnD,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,QAAQ,GAAG,CAAC,IAAI,QAAQ,QAAQ,MAAM,GAAG,MAAM,GAAG,MAAM,IAAI,IAAI,CAAC,CAAC;IACtF,CAAC;IAED,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAA8C;IAClF,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAElD,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,KAAK,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,KAAK,CAAC,CAAC;IAE9D,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnB,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,2BAA2B,CAAC,MAAM,CAAC,CAAC,CAAC;IAClD,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAED,SAAS,uBAAuB,CAAC,QAAkC;IACjE,MAAM,KAAK,GAAa,CAAC,YAAY,CAAC,CAAC;IAEvC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAEjC,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;YACxB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAClC,CAAC;QAED,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAClB,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC1B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;QAED,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC;QAED,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;YAC1B,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;gBAClC,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC;gBAC/C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACf,KAAK,CAAC,IAAI,CAAC,QAAQ,OAAO,EAAE,CAAC,CAAC;gBAC9B,kBAAkB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;QAED,IAAI,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;YAC5B,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;gBACpC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACf,KAAK,CAAC,IAAI,CAAC,UAAU,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC;gBACnC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACf,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;gBAC5B,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;oBACjB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;oBACf,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;gBAClC,CAAC;gBACD,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;oBACjB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;oBACf,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;gBAClC,CAAC;gBACD,IAAI,GAAG,CAAC,YAAY,EAAE,CAAC;oBACrB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;oBACf,KAAK,CAAC,IAAI,CAAC,kBAAkB,GAAG,CAAC,YAAY,IAAI,CAAC,CAAC;gBACrD,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YAC3B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;gBACnC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;QAED,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YACxB,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;gBACpC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,2BAA2B,CAAC,QAAkC;IACrE,MAAM,KAAK,GAAa,CAAC,iBAAiB,CAAC,CAAC;IAE5C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAEjC,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;YACxB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAClC,CAAC;QAED,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC;QAED,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YAC7B,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;gBAClC,MAAM,OAAO,GAAG,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,IAAI,CAAC;gBAC1C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACf,KAAK,CAAC,IAAI,CAAC,QAAQ,OAAO,EAAE,CAAC,CAAC;gBAC9B,kBAAkB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;QAED,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YAC3B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;gBACnC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;QAED,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YACxB,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;gBACpC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,kBAAkB,CAAC,GAA0B,EAAE,KAAe;IACrE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE5B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,eAAe,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC;IAExC,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QACjB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAClC,CAAC;IAED,IAAI,GAAG,CAAC,YAAY,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,kBAAkB,GAAG,CAAC,YAAY,IAAI,CAAC,CAAC;IACrD,CAAC;IAED,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,sBAAsB,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC;IACnD,CAAC;IAED,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QAChB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;IAED,IAAI,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QAC5B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,IAAI,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAC9B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;YACjC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QAC5B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;YAChC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/config-types.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The source type of a configuration surface:
+ * - 'cli'    — a command-line command or subcommand
+ * - 'config' — a configuration file (e.g. JSON, YAML, TOML)
+ * - 'env'    — environment variables
+ */
+export type ConfigSourceType = 'cli' | 'config' | 'env';
+/**
+ * Describes a single configuration surface: a CLI command, config file schema,
+ * or environment-variable group that an agent may need to invoke or populate.
+ */
+export interface ExtractedConfigSurface {
+    /** Human-readable name of this surface (e.g. "build", "jest.config.ts") */
+    name: string;
+    /** Short prose description of what this surface controls or triggers */
+    description: string;
+    /**
+     * The kind of surface: CLI command/subcommand, config file, or env-var group.
+     * Agents use this to decide how to surface the information (flag syntax vs key
+     * path vs environment variable name).
+     */
+    sourceType: ConfigSourceType;
+    /**
+     * Optional canonical usage example (e.g. `pnpm build --watch`).
+     * Shown verbatim so agents can copy-paste directly.
+     */
+    usage?: string;
+    /** All options (flags, config keys, env vars) accepted by this surface */
+    options: ExtractedConfigOption[];
+    /** Positional arguments accepted by this CLI surface, in order */
+    arguments?: ExtractedConfigArgument[];
+    /** Nested subcommands of this CLI surface (recursive) */
+    subcommands?: ExtractedConfigSurface[];
+    /**
+     * Conditions under which an agent should prefer this surface.
+     * Mirrors the @useWhen JSDoc pattern used elsewhere in ExtractedSkill.
+     */
+    useWhen?: string[];
+    /**
+     * Conditions under which an agent should avoid this surface.
+     * Mirrors the @avoidWhen JSDoc pattern used elsewhere in ExtractedSkill.
+     */
+    avoidWhen?: string[];
+    /**
+     * Known pitfalls, footguns, or common mistakes for this surface.
+     * Mirrors the @never JSDoc pattern used elsewhere in ExtractedSkill.
+     */
+    pitfalls?: string[];
+    /**
+     * Extended expert notes about this surface — edge cases, interaction effects,
+     * or nuances not captured by the description. Mirrors the @remarks JSDoc pattern.
+     */
+    remarks?: string;
+}
+/**
+ * A single configurable option within a surface: a CLI flag, a config-file key,
+ * or an environment variable (or any combination of the three).
+ */
+export interface ExtractedConfigOption {
+    /** Canonical name for this option (used as the display key) */
+    name: string;
+    /**
+     * The long CLI flag for this option, including leading dashes
+     * (e.g. `--output-dir`). Omit if this option is not exposed via CLI.
+     */
+    cliFlag?: string;
+    /**
+     * The short CLI flag alias (e.g. `-o`).
+     * Omit if there is no short form.
+     */
+    cliShort?: string;
+    /**
+     * The dot-notation key path in a config file (e.g. `output.dir`).
+     * Omit if this option is not settable in a config file.
+     */
+    configKey?: string;
+    /**
+     * The environment variable name that sets this option (e.g. `OUTPUT_DIR`).
+     * Omit if this option is not settable via environment variable.
+     */
+    envVar?: string;
+    /**
+     * TypeScript-style type expression for the accepted value
+     * (e.g. `string`, `number`, `boolean`, `'esm' | 'cjs'`).
+     */
+    type: string;
+    /** Short prose description of what this option controls */
+    description: string;
+    /** Whether this option must be supplied for the surface to function */
+    required: boolean;
+    /**
+     * The default value when the option is not explicitly set.
+     * Serialised as a string (e.g. `"true"`, `"4000"`, `"\"dist\""`).
+     */
+    defaultValue?: string;
+    /**
+     * Extended expert notes about this option — interaction effects, precedence
+     * rules, or platform-specific behaviour.
+     */
+    remarks?: string;
+    /**
+     * Conditions under which an agent should set this option.
+     * Mirrors the @useWhen JSDoc pattern.
+     */
+    useWhen?: string[];
+    /**
+     * Conditions under which an agent should avoid setting this option.
+     * Mirrors the @avoidWhen JSDoc pattern.
+     */
+    avoidWhen?: string[];
+    /**
+     * Known pitfalls or common mistakes when using this option.
+     * Mirrors the @never JSDoc pattern.
+     */
+    pitfalls?: string[];
+    /**
+     * Logical grouping label for this option (e.g. "Output", "Performance").
+     * Agents can use this to cluster related options in generated documentation.
+     */
+    category?: string;
+}
+/**
+ * A positional command-line argument accepted by a CLI surface.
+ * Positional arguments are ordered and do not use flag prefixes.
+ */
+export interface ExtractedConfigArgument {
+    /** Symbolic name of this argument as shown in usage strings (e.g. `<file>`) */
+    name: string;
+    /** Short prose description of what this argument represents */
+    description: string;
+    /** Whether the caller must supply this argument */
+    required: boolean;
+    /**
+     * Whether this argument is variadic (accepts one or more values,
+     * typically represented as `...<files>` in usage strings).
+     */
+    variadic: boolean;
+    /**
+     * The default value used when the argument is omitted (only meaningful
+     * when `required` is false). Serialised as a string.
+     */
+    defaultValue?: string;
+}
+//# sourceMappingURL=config-types.d.ts.map

package/dist/config-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-types.d.ts","sourceRoot":"","sources":["../src/config-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,QAAQ,GAAG,KAAK,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IAEb,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,UAAU,EAAE,gBAAgB,CAAC;IAE7B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,0EAA0E;IAC1E,OAAO,EAAE,qBAAqB,EAAE,CAAC;IAEjC,kEAAkE;IAClE,SAAS,CAAC,EAAE,uBAAuB,EAAE,CAAC;IAEtC,yDAAyD;IACzD,WAAW,CAAC,EAAE,sBAAsB,EAAE,CAAC;IAEvC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IAErB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IAEpB,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IAErB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IAEb,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IAEpB,mDAAmD;IACnD,QAAQ,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}

package/dist/config-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=config-types.js.map

package/dist/config-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-types.js","sourceRoot":"","sources":["../src/config-types.ts"],"names":[],"mappings":""}