@vibe-agent-toolkit/utils 0.1.42 → 0.2.0-rc.10

package/dist/link-auth/build-headers.js

@@ -1,58 +0,0 @@
-/**
- * Render auth-header templates with rendered values, and a structural
- * redaction helper for serialization.
- *
- * `buildHeaders` renders each header value template against a context that
- * carries `${token}` plus any named captures / vars from the rewrite step.
- * `redactHeaders` masks `Authorization` values for any caller that needs to
- * serialize headers into logs, errors, or cache entries — the design's §8
- * "tokens never leak" claim depends on every such site routing through this.
- *
- * Per design issue #113 §4 (auth.headers vocabulary) and §8 (redaction is
- * structural; Authorization values never appear in serialized output).
- */
-import { renderTemplate } from './template.js';
-export const REDACTED_VALUE = '<redacted>';
-/**
- * Header names whose values must be masked when serialized.
- *
- * v1 ships only `authorization` because that is the only secret-bearing
- * header the current macros emit. **Omission is the security risk** — any
- * future macro that emits a header carrying a secret (`Cookie`,
- * `Proxy-Authorization`, `X-API-Key`, custom bearer-style headers) must add
- * that name here, or the token will silently leak through serialization.
- * Extending the set is not the dangerous edit; forgetting to extend it is.
- */
-const SENSITIVE_HEADER_NAMES = new Set(['authorization']);
-/**
- * Render a map of header templates into a map of concrete header values.
- *
- * @throws {TemplateMissingVarError} if a header template references an
- *   unknown context key
- * @throws {TemplateSyntaxError} from a malformed template expression
- * @throws {UnknownTransformError} from a template calling an unknown transform
- */
-export function buildHeaders(templates, context) {
-    const headers = Object.create(null);
-    for (const [name, template] of Object.entries(templates)) {
-        headers[name] = renderTemplate(template, context);
-    }
-    return headers;
-}
-/**
- * Return a copy of `headers` with sensitive values replaced by `REDACTED_VALUE`.
- * Header-name matching is case-insensitive but exact (no prefix matching) — a
- * header like `X-Authorization-Foo` is NOT considered sensitive.
- *
- * **Input must be a plain key-value object.** A `Headers` instance (Web Fetch
- * API) or a `Map` yields `[]` from `Object.entries` and would silently no-op
- * redaction — converting to a plain object is the caller's responsibility.
- */
-export function redactHeaders(headers) {
-    const redacted = Object.create(null);
-    for (const [name, value] of Object.entries(headers)) {
-        redacted[name] = SENSITIVE_HEADER_NAMES.has(name.toLowerCase()) ? REDACTED_VALUE : value;
-    }
-    return redacted;
-}
-//# sourceMappingURL=build-headers.js.map

package/dist/link-auth/build-headers.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"build-headers.js","sourceRoot":"","sources":["../../src/link-auth/build-headers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,MAAM,CAAC,MAAM,cAAc,GAAG,YAAY,CAAC;AAE3C;;;;;;;;;GASG;AACH,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC;AAE/E;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,SAAiC,EACjC,OAA+B;IAE/B,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAA2B,CAAC;IAC9D,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACzD,OAAO,CAAC,IAAI,CAAC,GAAG,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,OAA+B;IAC3D,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAA2B,CAAC;IAC/D,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,QAAQ,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC;IAC3F,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/link-auth/expand-macro.d.ts

@@ -1,38 +0,0 @@
-/**
- * Macro loader + expander.
- *
- * Loads the bundled `macros.yaml` once at module init and exposes
- * `expandMacro(name, overrides?)` which deep-merges the named macro with any
- * adopter overrides. The merge is "adopter wins": objects merge recursively,
- * arrays and primitives are replaced wholesale (no element-wise array merge).
- *
- * The shipped macro file is at `link-auth/macros.yaml`, copied into the dist
- * tree by `packages/dev-tools/src/copy-yaml-assets.ts` during build so the
- * runtime `fs.readFileSync(new URL('./macros.yaml', import.meta.url))`
- * resolves in both source-mode (vitest) and built-mode (dist).
- *
- * Per design issue #113 §5 (macros are config, not a privileged code path).
- */
-/**
- * Thrown when a `use: <name>` references a macro not in the shipped set.
- * Message lists the available macros so a typo surfaces clearly.
- */
-export declare class UnknownMacroError extends Error {
-    constructor(name: string, available: readonly string[]);
-}
-/**
- * Look up a macro by name and deep-merge optional adopter overrides on top.
- *
- * Merge semantics:
- *   - Plain objects merge recursively (sibling keys preserved).
- *   - Arrays are replaced wholesale (override's array wins; no concat).
- *   - Primitives are replaced.
- *   - `undefined` in an override is treated as "not provided" (base wins).
- *
- * The returned object and all nested plain objects use null prototypes so
- * `__proto__` / `constructor` keys can never poison consumers.
- *
- * @throws {UnknownMacroError} if `name` is not in the shipped macro set
- */
-export declare function expandMacro(name: string, overrides?: Record<string, unknown>): Record<string, unknown>;
-//# sourceMappingURL=expand-macro.d.ts.map

package/dist/link-auth/expand-macro.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"expand-macro.d.ts","sourceRoot":"","sources":["../../src/link-auth/expand-macro.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAyCH;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE;CAIvD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYzB"}

package/dist/link-auth/expand-macro.js

@@ -1,133 +0,0 @@
-/**
- * Macro loader + expander.
- *
- * Loads the bundled `macros.yaml` once at module init and exposes
- * `expandMacro(name, overrides?)` which deep-merges the named macro with any
- * adopter overrides. The merge is "adopter wins": objects merge recursively,
- * arrays and primitives are replaced wholesale (no element-wise array merge).
- *
- * The shipped macro file is at `link-auth/macros.yaml`, copied into the dist
- * tree by `packages/dev-tools/src/copy-yaml-assets.ts` during build so the
- * runtime `fs.readFileSync(new URL('./macros.yaml', import.meta.url))`
- * resolves in both source-mode (vitest) and built-mode (dist).
- *
- * Per design issue #113 §5 (macros are config, not a privileged code path).
- */
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { parse as parseYaml } from 'yaml';
-let macrosCache;
-/**
- * Load macros lazily on first use rather than at module init.
- *
- * Why lazy: vitest tests elsewhere in the repo mock `node:fs` (replacing
- * `readFileSync` with `vi.fn()` that returns `undefined`). If we eagerly read
- * at module load, any unrelated test that imports `@vibe-agent-toolkit/utils`
- * and mocks fs crashes inside `parseYaml(undefined)` — module-init code runs
- * unconditionally, before the mock-setup intent reaches our file.
- *
- * Lazy load makes module import side-effect-free; only callers of
- * `expandMacro` pay the fs cost. `macrosPath` is also computed here (not at
- * module top level) so that merely importing this module leaves no `new URL()`
- * reference for bundler static analysis to trip over.
- */
-function getMacros() {
-    if (macrosCache !== undefined)
-        return macrosCache;
-    // Path is derived from `import.meta.url`, not user input — points at the
-    // shipped macros.yaml asset next to this module in both src and dist trees.
-    const macrosPath = fileURLToPath(new URL('./macros.yaml', import.meta.url));
-    // eslint-disable-next-line security/detect-non-literal-fs-filename
-    const macrosFileContent = readFileSync(macrosPath, 'utf8');
-    const parsed = parseYaml(macrosFileContent);
-    if (!isPlainObject(parsed)) {
-        throw new Error('macros.yaml: expected top-level object mapping macro name → provider config.');
-    }
-    macrosCache = freezeMacros(parsed);
-    return macrosCache;
-}
-/**
- * Thrown when a `use: <name>` references a macro not in the shipped set.
- * Message lists the available macros so a typo surfaces clearly.
- */
-export class UnknownMacroError extends Error {
-    constructor(name, available) {
-        super(`Unknown macro "${name}". Available: ${available.join(', ')}.`);
-        this.name = 'UnknownMacroError';
-    }
-}
-/**
- * Look up a macro by name and deep-merge optional adopter overrides on top.
- *
- * Merge semantics:
- *   - Plain objects merge recursively (sibling keys preserved).
- *   - Arrays are replaced wholesale (override's array wins; no concat).
- *   - Primitives are replaced.
- *   - `undefined` in an override is treated as "not provided" (base wins).
- *
- * The returned object and all nested plain objects use null prototypes so
- * `__proto__` / `constructor` keys can never poison consumers.
- *
- * @throws {UnknownMacroError} if `name` is not in the shipped macro set
- */
-export function expandMacro(name, overrides) {
-    const macros = getMacros();
-    const base = macros[name];
-    if (base === undefined) {
-        throw new UnknownMacroError(name, Object.keys(macros));
-    }
-    if (overrides === undefined) {
-        return cloneWithNullProto(base);
-    }
-    const merged = deepMerge(base, overrides);
-    // Top-level result is guaranteed object here because base is.
-    return merged;
-}
-function deepMerge(base, override) {
-    if (override === undefined)
-        return base;
-    if (!isPlainObject(base) || !isPlainObject(override))
-        return cloneValue(override);
-    const result = Object.create(null);
-    for (const [key, value] of Object.entries(base)) {
-        result[key] = cloneValue(value);
-    }
-    for (const [key, value] of Object.entries(override)) {
-        const existing = Object.hasOwn(result, key) ? result[key] : undefined;
-        if (isPlainObject(existing) && isPlainObject(value)) {
-            result[key] = deepMerge(existing, value);
-        }
-        else {
-            result[key] = cloneValue(value);
-        }
-    }
-    return result;
-}
-function cloneValue(value) {
-    if (Array.isArray(value))
-        return value.map(cloneValue);
-    if (isPlainObject(value))
-        return cloneWithNullProto(value);
-    return value;
-}
-function cloneWithNullProto(obj) {
-    const cloned = Object.create(null);
-    for (const [key, value] of Object.entries(obj)) {
-        cloned[key] = cloneValue(value);
-    }
-    return cloned;
-}
-function freezeMacros(parsed) {
-    const frozen = Object.create(null);
-    for (const [name, value] of Object.entries(parsed)) {
-        if (!isPlainObject(value)) {
-            throw new Error(`macros.yaml: macro "${name}" is not an object.`);
-        }
-        frozen[name] = cloneWithNullProto(value);
-    }
-    return frozen;
-}
-function isPlainObject(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
-//# sourceMappingURL=expand-macro.js.map

package/dist/link-auth/expand-macro.js.map

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

package/dist/link-auth/macros.yaml

@@ -1,50 +0,0 @@
-# linkAuth provider macros — shipped defaults referenced by `use: <name>` in
-# adopter `vibe-agent-toolkit.config.yaml` files.
-#
-# Each entry is a full provider config in the §4 vocabulary (match, rewrite,
-# auth, token, check). Adopters reference a macro by name and may deep-merge
-# overrides on top — see design issue #113 §5.
-#
-# Adding a new host is intended to be a config-only PR: append an entry here
-# and add unit tests. Only `vocabulary` changes (e.g. a new transform) require
-# engine code.
-
-github:
-  match:
-    host: github.com
-  rewrite:
-    - when: '^https://github\.com/(?<owner>[^/]+)/(?<repo>[^/]+)/(?:blob|tree)/(?<ref>[^/]+)/(?<path>.+)$'
-      to: 'https://api.github.com/repos/${owner}/${repo}/contents/${path}?ref=${ref}'
-  auth:
-    headers:
-      Authorization: 'Bearer ${token}'
-      Accept: application/vnd.github+json
-  token:
-    - command: gh auth token
-    - env: GITHUB_TOKEN
-  check:
-    method: GET
-    aliveStatus: [200]
-    notFoundMeaning: ambiguous
-
-sharepoint:
-  match:
-    host: '*.sharepoint.com'
-    excludeHost:
-      - '*-my.sharepoint.com'
-  rewrite:
-    - when: '^(?<u>https://.+)$'
-      vars:
-        shareId: 'u!${base64url(u)}'
-      to: 'https://graph.microsoft.com/v1.0/shares/${shareId}/driveItem'
-  auth:
-    headers:
-      Authorization: 'Bearer ${token}'
-  # SharePoint has no zero-config token source (design §5.1 note): a SharePoint-
-  # scoped token requires an Entra app registration; the stock `az` token does
-  # not work. Adopter must supply their own token command.
-  token: []
-  check:
-    method: GET
-    aliveStatus: [200]
-    notFoundMeaning: dead

package/dist/link-auth/resolve-token.d.ts

@@ -1,83 +0,0 @@
-/**
- * Token resolution — ordered, first-non-empty-wins.
- *
- * Iterates a provider's `token` source list and returns the first source that
- * yields a non-empty value. Two source shapes:
- *   - `{ env: "NAME" }`                — read from process env (no trimming)
- *   - `{ command: argv }`              — run a command, return trimmed stdout
- *   - `{ command: "gh auth token" }`   — convenience: whitespace-tokenized into
- *     argv. **Not** passed through a shell — operators (`|`, `&&`, `$(...)`)
- *     become literal argv elements, per the design's §6.1 sharp-edge note.
- *
- * Command sources can be disabled at runtime with `VAT_LINKAUTH_ALLOW_COMMAND=0`
- * (or by passing `allowCommand: false` in deps). Useful in security-sensitive
- * environments where arbitrary command execution is undesirable.
- *
- * Returns `undefined` if every source fails or yields an empty/whitespace
- * value — the caller's `resolveAuthenticatedUrl` translates that to the
- * `unverified` outcome (surfaced as `LINK_AUTH_UNVERIFIED` by the validator).
- *
- * Per design issue #113 §4 (token vocabulary) and §6.1 (command execution,
- * `safeExecSync`-backed, `shell: false`).
- */
-export type TokenSource = {
-    readonly env: string;
-} | {
-    readonly command: string | readonly string[];
-};
-export interface TokenResolutionDeps {
-    /**
-     * Environment lookup map. Defaults to `process.env`. Injectable for tests so
-     * unit tests don't depend on ambient environment state.
-     */
-    readonly env: Record<string, string | undefined>;
-    /**
-     * Command runner. Defaults to `safeExecResult`-wrapped invocation. Injectable
-     * for tests. Receives argv; returns `success` + `stdout`. Should NOT throw
-     * for normal exec failures (return `success: false` instead). Throws are
-     * propagated by `resolveToken` — they indicate operator-level bugs.
-     */
-    readonly runCommand: (argv: readonly string[]) => {
-        success: boolean;
-        stdout: string;
-    };
-    /**
-     * Whether `{ command: ... }` sources are allowed. Defaults to reading
-     * `VAT_LINKAUTH_ALLOW_COMMAND` from the resolved `env` map (not ambient
-     * `process.env`), so a caller supplying a curated `deps.env` can control the
-     * flag without touching real process state. Set to `false` (or set
-     * `VAT_LINKAUTH_ALLOW_COMMAND=0` in the env) to skip all command sources and
-     * rely solely on env-var sources — useful in locked-down CI or security reviews.
-     */
-    readonly allowCommand: boolean;
-}
-/**
- * Return a copy of the given env with all `GIT_*` keys removed. Case-insensitive
- * on the key so Windows env vars (which are case-insensitive at the OS level,
- * though `process.env` preserves original case) can't sneak through as e.g.
- * `Git_Dir`.
- *
- * Exported for unit testing and for callers assembling their own `runCommand`
- * who want the exact same scrub `defaultRunCommand` applies.
- *
- * Rationale: `vat resources validate` is often invoked from git pre-commit
- * hooks, which pre-set `GIT_DIR` / `GIT_WORK_TREE` / `GIT_INDEX_FILE`. These
- * poison any nested tool that shells out to git, notably `gh auth token`.
- */
-export declare function scrubGitEnv(source: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
-/**
- * Default `runCommand` implementation — exported so callers that want to
- * memoize per-validate-run can wrap it without duplicating the spawn logic.
- * Forwards to `safeExecResult` (no shell, argv-based), with `GIT_*` vars
- * stripped from the child env — see {@link scrubGitEnv}.
- */
-export declare const defaultRunCommand: TokenResolutionDeps['runCommand'];
-/**
- * Resolve a token from an ordered list of sources.
- *
- * @returns the first non-empty value, or `undefined` if every source failed.
- * @throws whatever the injected `runCommand` throws (operator-level bug; not
- *   swallowed). Standard `safeExecResult` does not throw under normal use.
- */
-export declare function resolveToken(sources: readonly TokenSource[], deps?: Partial<TokenResolutionDeps>): string | undefined;
-//# sourceMappingURL=resolve-token.d.ts.map

package/dist/link-auth/resolve-token.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"resolve-token.d.ts","sourceRoot":"","sources":["../../src/link-auth/resolve-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,MAAM,MAAM,WAAW,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAEtG,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAEjD;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAEvF;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAIxE;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,mBAAmB,CAAC,YAAY,CAO/D,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,IAAI,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAClC,MAAM,GAAG,SAAS,CAWpB"}

package/dist/link-auth/resolve-token.js

@@ -1,101 +0,0 @@
-/**
- * Token resolution — ordered, first-non-empty-wins.
- *
- * Iterates a provider's `token` source list and returns the first source that
- * yields a non-empty value. Two source shapes:
- *   - `{ env: "NAME" }`                — read from process env (no trimming)
- *   - `{ command: argv }`              — run a command, return trimmed stdout
- *   - `{ command: "gh auth token" }`   — convenience: whitespace-tokenized into
- *     argv. **Not** passed through a shell — operators (`|`, `&&`, `$(...)`)
- *     become literal argv elements, per the design's §6.1 sharp-edge note.
- *
- * Command sources can be disabled at runtime with `VAT_LINKAUTH_ALLOW_COMMAND=0`
- * (or by passing `allowCommand: false` in deps). Useful in security-sensitive
- * environments where arbitrary command execution is undesirable.
- *
- * Returns `undefined` if every source fails or yields an empty/whitespace
- * value — the caller's `resolveAuthenticatedUrl` translates that to the
- * `unverified` outcome (surfaced as `LINK_AUTH_UNVERIFIED` by the validator).
- *
- * Per design issue #113 §4 (token vocabulary) and §6.1 (command execution,
- * `safeExecSync`-backed, `shell: false`).
- */
-import { safeExecResult } from '../safe-exec.js';
-/**
- * Return a copy of the given env with all `GIT_*` keys removed. Case-insensitive
- * on the key so Windows env vars (which are case-insensitive at the OS level,
- * though `process.env` preserves original case) can't sneak through as e.g.
- * `Git_Dir`.
- *
- * Exported for unit testing and for callers assembling their own `runCommand`
- * who want the exact same scrub `defaultRunCommand` applies.
- *
- * Rationale: `vat resources validate` is often invoked from git pre-commit
- * hooks, which pre-set `GIT_DIR` / `GIT_WORK_TREE` / `GIT_INDEX_FILE`. These
- * poison any nested tool that shells out to git, notably `gh auth token`.
- */
-export function scrubGitEnv(source) {
-    return Object.fromEntries(Object.entries(source).filter(([k]) => !k.toUpperCase().startsWith('GIT_')));
-}
-/**
- * Default `runCommand` implementation — exported so callers that want to
- * memoize per-validate-run can wrap it without duplicating the spawn logic.
- * Forwards to `safeExecResult` (no shell, argv-based), with `GIT_*` vars
- * stripped from the child env — see {@link scrubGitEnv}.
- */
-export const defaultRunCommand = (argv) => {
-    if (argv.length === 0)
-        return { success: false, stdout: '' };
-    const [bin, ...args] = argv;
-    if (bin === undefined)
-        return { success: false, stdout: '' };
-    const result = safeExecResult(bin, [...args], { encoding: 'utf8', env: scrubGitEnv(process.env) });
-    const stdout = typeof result.stdout === 'string' ? result.stdout : result.stdout.toString('utf8');
-    return { success: result.success, stdout };
-};
-/**
- * Resolve a token from an ordered list of sources.
- *
- * @returns the first non-empty value, or `undefined` if every source failed.
- * @throws whatever the injected `runCommand` throws (operator-level bug; not
- *   swallowed). Standard `safeExecResult` does not throw under normal use.
- */
-export function resolveToken(sources, deps) {
-    const env = deps?.env ?? process.env;
-    const runCommand = deps?.runCommand ?? defaultRunCommand;
-    const allowCommand = deps?.allowCommand ?? (env['VAT_LINKAUTH_ALLOW_COMMAND'] !== '0');
-    for (const source of sources) {
-        if (!allowCommand && 'command' in source)
-            continue;
-        const value = tryResolveSource(source, env, runCommand);
-        if (value !== undefined && value.length > 0)
-            return value;
-    }
-    return undefined;
-}
-function tryResolveSource(source, env, runCommand) {
-    if ('env' in source) {
-        // Object.hasOwn defends against env names like "__proto__" returning
-        // Object.prototype via the prototype chain.
-        if (!Object.hasOwn(env, source.env))
-            return undefined;
-        return env[source.env];
-    }
-    const argv = toArgv(source.command);
-    if (argv.length === 0)
-        return undefined;
-    const result = runCommand(argv);
-    if (!result.success)
-        return undefined;
-    const trimmed = result.stdout.trim();
-    return trimmed.length === 0 ? undefined : trimmed;
-}
-function toArgv(command) {
-    if (Array.isArray(command))
-        return command;
-    // Whitespace-tokenize the string form. Empty segments (from multiple spaces)
-    // are filtered. Shell operators ('|', '&&', etc.) become literal argv, NOT
-    // pipes — see design §6.1.
-    return command.split(/\s+/).filter((s) => s.length > 0);
-}
-//# sourceMappingURL=resolve-token.js.map

package/dist/link-auth/resolve-token.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"resolve-token.js","sourceRoot":"","sources":["../../src/link-auth/resolve-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AA8BjD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,MAAyB;IACnD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CACvD,CAAC;AACzB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAsC,CAAC,IAAI,EAAE,EAAE;IAC3E,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAC7D,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAC5B,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAC7D,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACnG,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAClG,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;AAC7C,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,OAA+B,EAC/B,IAAmC;IAEnC,MAAM,GAAG,GAAG,IAAI,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACrC,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,IAAI,iBAAiB,CAAC;IACzD,MAAM,YAAY,GAAG,IAAI,EAAE,YAAY,IAAI,CAAC,GAAG,CAAC,4BAA4B,CAAC,KAAK,GAAG,CAAC,CAAC;IAEvF,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC,YAAY,IAAI,SAAS,IAAI,MAAM;YAAE,SAAS;QACnD,MAAM,KAAK,GAAG,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;QACxD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;IAC5D,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,gBAAgB,CACvB,MAAmB,EACnB,GAAuC,EACvC,UAA6C;IAE7C,IAAI,KAAK,IAAI,MAAM,EAAE,CAAC;QACpB,qEAAqE;QACrE,4CAA4C;QAC5C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC;YAAE,OAAO,SAAS,CAAC;QACtD,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAExC,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IACtC,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACrC,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AACpD,CAAC;AAED,SAAS,MAAM,CAAC,OAAmC;IACjD,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAC3C,6EAA6E;IAC7E,2EAA2E;IAC3E,2BAA2B;IAC3B,OAAQ,OAAkB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACtE,CAAC"}

package/dist/link-auth/resolve.d.ts

@@ -1,102 +0,0 @@
-/**
- * Public API for the linkAuth pure engine.
- *
- * `resolveAuthenticatedUrl(url, config)` is the single entry point per design
- * §6: select the first provider whose `match.host` claims the URL, run its
- * rewrite pipeline, resolve a token, build the auth headers, and return
- * everything the caller needs to issue an authenticated fetch.
- *
- * Three outcomes:
- *   - `{ fetchUrl, headers }`              — ready to fetch (provider claimed,
- *                                            rewrite matched, token resolved)
- *   - `{ outcome: 'unsupported' }`         — no provider claims the host, OR
- *                                            host matched but no rewrite did
- *                                            (per §4: "the provider does not
- *                                            claim the URL for rewriting")
- *   - `{ outcome: 'unverified', reason }`  — claimed and rewrote, but no token
- *                                            source resolved a non-empty value
- *
- * Per design issue #113 §6.
- */
-import { type TokenResolutionDeps, type TokenSource } from './resolve-token.js';
-import { type RewriteRule } from './rewrite.js';
-import { type ProviderMatch } from './select-provider.js';
-export interface ProviderAuth {
-    readonly headers: Record<string, string>;
-}
-/**
- * Optional content-fetch header overrides (design issue #113 §6.2).
- *
- * Health-check and content retrieval often need different `Accept` (or other)
- * headers. The canonical example: GitHub's `application/vnd.github+json`
- * returns 200 for any size but omits bytes >1 MiB, while
- * `application/vnd.github.raw` streams the bytes inline. The provider declares
- * `auth.headers` for health-check and an optional `fetch.headers` for content
- * retrieval. Both are templated against the same context (URL captures + token).
- */
-export interface ProviderFetch {
-    readonly headers: Record<string, string>;
-}
-export interface ProviderCheck {
-    readonly method: 'GET' | 'HEAD';
-    readonly aliveStatus: readonly number[];
-    readonly notFoundMeaning: 'ambiguous' | 'dead';
-}
-export interface Provider {
-    readonly match: ProviderMatch;
-    readonly rewrite: readonly RewriteRule[];
-    readonly auth: ProviderAuth;
-    /**
-     * Optional — present when a provider needs different headers for content
-     * retrieval than for health-check. Absent for hosts where one header set
-     * does both jobs.
-     */
-    readonly fetch?: ProviderFetch;
-    readonly token: readonly TokenSource[];
-    readonly check: ProviderCheck;
-}
-export interface LinkAuthConfig {
-    readonly providers: readonly Provider[];
-    /**
-     * Optional content-cache config (consumed by the slice-3 content-fetch
-     * primitive, not by the engine itself). The engine stays stateless; this
-     * field rides along on the config object so the primitive doesn't need a
-     * second source of truth.
-     */
-    readonly cache?: {
-        readonly ttlMinutes?: number;
-    };
-}
-export type ResolveOutcome = {
-    readonly fetchUrl: string;
-    readonly headers: Record<string, string>;
-    /**
-     * Expanded fetch-mode headers, only present when the provider declared
-     * a `fetch` block. Templated against the same context as `headers`
-     * (URL captures + resolved token), so callers do not need to re-resolve
-     * the token to send these. Per §6.2 — content-fetch consumers send
-     * these instead of (or merged over) `headers` for the request body.
-     */
-    readonly fetchHeaders?: Record<string, string>;
-    /**
-     * The matched provider's `check` block, passed through so the post-fetch
-     * classifier (in `packages/resources`) can route status codes to outcomes
-     * without re-running `selectProvider`. Reading this from the engine —
-     * rather than asking the validator to re-derive it — keeps the
-     * provider-match decision in exactly one place.
-     */
-    readonly check: ProviderCheck;
-} | {
-    readonly outcome: 'unsupported';
-} | {
-    readonly outcome: 'unverified';
-    readonly reason: string;
-};
-/**
- * Resolve an authenticated fetch plan for `url` against the configured providers.
- *
- * @param deps - Optional dependency injection for token resolution (`env` map
- *   + `runCommand`). Production callers omit this; tests supply mocks.
- */
-export declare function resolveAuthenticatedUrl(url: string, config: LinkAuthConfig, deps?: Partial<TokenResolutionDeps>): ResolveOutcome;
-//# sourceMappingURL=resolve.d.ts.map

package/dist/link-auth/resolve.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/link-auth/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,WAAW,EACjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,WAAW,EAAc,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,sBAAsB,CAAC;AAE1E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,WAAW,GAAG,MAAM,CAAC;CAChD;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;CACH;AAED,MAAM,MAAM,cAAc,GACtB;IACE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;CAC/B,GACD;IAAE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;CAAE,GACnC;IAAE,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,cAAc,EACtB,IAAI,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAClC,cAAc,CAqChB"}