@vibe-agent-toolkit/utils 0.2.0-rc.3 → 0.2.0-rc.4

package/dist/timing-dump.js

@@ -18,9 +18,14 @@
  * 2. A dump failure is written to **stderr and never thrown**. These run from
  *    an `exit` listener, where a throw changes the process's exit behaviour, and
  *    they must never touch stdout, which carries vat's report.
- * 3. A pid can file more than one dump. `vat validate` spawns the vat binary
- *    once per phase and pids are reused, so `<stem>-<pid>.json` genuinely
- *    collides; the name gains a counter rather than overwriting.
+ * 3. A pid can file more than one dump, and the name is CLAIMED rather than
+ *    checked. `vat validate` spawns the vat binary once per phase and pids are
+ *    reused, so `<stem>-<pid>.json` genuinely collides; worse, worker threads
+ *    SHARE their parent's pid, so a thread pool's whole cohort competes for one
+ *    `<stem>-<pid>` sequence at the same instant. The name gains a counter
+ *    rather than overwriting, and the counter is settled by
+ *    {@link EXCLUSIVE_CREATE} so the OS — not a check-then-write gap — decides
+ *    who won it.
  * 4. The process's own wall and CPU time is read ONCE, at dump time. It is a
  *    lifetime figure for the process and never a duration of the measured work;
  *    its value is the RATIO, which tells a reader whether the wall-timed
@@ -42,7 +47,7 @@
  * thing a reader has to be able to trust identically. What each seam keeps for
  * itself is its accumulator shape, its dump body and the noun it is called by.
  */
-import { existsSync, writeFileSync } from 'node:fs';
+import { writeFileSync } from 'node:fs';
 import { safePath } from './path-core.js';
 import { mkdirSyncReal } from './path-utils.js';
 /** `process.cpuUsage()` reports microseconds; a dump reports milliseconds. */
@@ -51,10 +56,27 @@ const MICROSECONDS_PER_MS = 1000;
 const MS_PER_SECOND = 1000;
 /**
  * Ceiling on the pid-collision search. A directory holding this many dumps for
- * one pid is a runaway, not a collision; overwriting the last slot is a better
- * outcome than spinning.
+ * one pid is a runaway, not a collision, and giving up on a reported line is a
+ * better outcome than spinning.
+ *
+ * Exhausting it does NOT fall back to overwriting the last slot. That was the
+ * old behaviour, and it destroyed a dump for the same reason the check-then-
+ * write gap did — silently, and precisely when the directory was busiest.
  */
-const MAX_DUMP_COLLISIONS = 1000;
+export const MAX_DUMP_COLLISIONS = 1000;
+/**
+ * The `writeFileSync` flag that makes claiming a name atomic.
+ *
+ * `wx` is create-exclusive: the OS fails the call with `EEXIST` when the path
+ * already exists, so exactly one caller wins each name no matter how many are
+ * racing for it. Asking `existsSync` first and writing second is two operations
+ * with a gap in between, and threads sharing a pid land in that gap routinely —
+ * a measured 8-worker parse pool lost 6 of 9 dumps to it, reporting 44 of 172
+ * documents as if that were the whole run.
+ */
+const EXCLUSIVE_CREATE = 'wx';
+/** How the failure line names the ceiling case, so it reads unlike an OS error. */
+const CEILING_DETAIL = `every name up to the ${String(MAX_DUMP_COLLISIONS)}-collision ceiling was already claimed`;
 /**
  * Reduce a raw env value to a directory or `null`.
  *
@@ -119,46 +141,90 @@ export function readTimingProcess() {
     };
 }
 /**
- * Pick a dump path that does not already exist.
+ * The nth candidate name in one pid's dump sequence.
+ *
+ * @param directory - Directory dumps are written to
+ * @param stem - Basename and pid, already joined
+ * @param collision - 0 for the unsuffixed name, then the collision counter
+ * @returns The candidate path
+ */
+function timingDumpCandidate(directory, stem, collision) {
+    const suffix = collision === 0 ? '' : `-${String(collision)}`;
+    return safePath.join(directory, `${stem}${suffix}.json`);
+}
+/**
+ * Whether a caught write failure means somebody else already holds the name.
+ *
+ * @param error - Whatever `writeFileSync` threw
+ * @returns `true` only for `EEXIST`, which is a lost race and not a fault
+ */
+function isNameAlreadyTaken(error) {
+    return error instanceof Error && 'code' in error && error.code === 'EEXIST';
+}
+/**
+ * Claim a name by creating it, and fill it in the same operation.
+ *
+ * Choosing the name and writing it CANNOT be two steps: whatever separates them
+ * is a window in which another writer takes the name that was just declared
+ * free, and the loser's dump disappears with no error raised anywhere. So each
+ * candidate is written create-exclusively ({@link EXCLUSIVE_CREATE}) and an
+ * `EEXIST` — the OS saying somebody else got there — advances to the next
+ * counter rather than overwriting.
  *
  * @param directory - Directory dumps are written to
  * @param basename - Basename stem; the pid and any collision counter follow
- * @returns An unused path, or the last candidate tried
+ * @param contents - The already-serialized dump body
+ * @returns Which name was claimed, or why none could be
  */
-function nextTimingDumpPath(directory, basename) {
+function claimTimingDump(directory, basename, contents) {
     const stem = `${basename}-${String(process.pid)}`;
-    let candidate = safePath.join(directory, `${stem}.json`);
-    for (let collision = 1; 
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- operator-supplied diagnostic directory from a VAT_*_TIMING variable
-    collision <= MAX_DUMP_COLLISIONS && existsSync(candidate); collision += 1) {
-        candidate = safePath.join(directory, `${stem}-${String(collision)}.json`);
+    for (let collision = 0; collision <= MAX_DUMP_COLLISIONS; collision += 1) {
+        const candidate = timingDumpCandidate(directory, stem, collision);
+        try {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- operator-supplied diagnostic directory from a VAT_*_TIMING variable
+            writeFileSync(candidate, contents, { encoding: 'utf-8', flag: EXCLUSIVE_CREATE });
+            return { outcome: 'written', path: candidate };
+        }
+        catch (error) {
+            if (!isNameAlreadyTaken(error))
+                return { outcome: 'failed', path: candidate, error };
+        }
     }
-    return candidate;
+    return {
+        outcome: 'exhausted',
+        path: timingDumpCandidate(directory, stem, MAX_DUMP_COLLISIONS),
+    };
 }
 /**
  * Write one seam's dump, if the seam is on.
  *
  * The body is built lazily, inside this call, so a disabled seam never pays to
- * snapshot accumulators nobody will read.
+ * snapshot accumulators nobody will read — and a `build` that throws is reported
+ * like any other failure, because this runs from an `exit` listener where a
+ * throw would change the process's exit behaviour.
  *
  * @param noun - What the seam is called, for any failure line
  * @param directory - Where to write, or `null` when the seam is off
  * @param basename - Basename stem for the file
  * @param build - Produces the dump body
- * @returns The path written, or `null` when the seam is off or the write failed
+ * @returns The path written, or `null` when the seam is off or nothing was written
  */
 export function writeTimingDump(noun, directory, basename, build) {
     if (directory === null)
         return null;
-    const target = nextTimingDumpPath(directory, basename);
+    let claim;
     try {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- operator-supplied diagnostic directory from a VAT_*_TIMING variable
-        writeFileSync(target, `${JSON.stringify(build(), null, 2)}\n`, 'utf-8');
+        claim = claimTimingDump(directory, basename, `${JSON.stringify(build(), null, 2)}\n`);
     }
     catch (error) {
-        reportTimingDumpFailure(noun, target, error);
+        // Only `build()` and its serialization can reach here; every filesystem
+        // failure is already an outcome rather than a throw.
+        reportTimingDumpFailure(noun, directory, error);
         return null;
     }
-    return target;
+    if (claim.outcome === 'written')
+        return claim.path;
+    reportTimingDumpFailure(noun, claim.path, claim.outcome === 'exhausted' ? CEILING_DETAIL : claim.error);
+    return null;
 }
 //# sourceMappingURL=timing-dump.js.map

package/dist/timing-dump.js.map

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

package/eslint/index.cjs

@@ -54,6 +54,7 @@ const rules = {
   'no-self-package-import': require('./rules/no-self-package-import.cjs'),
   'require-justified-skip': require('./rules/require-justified-skip.cjs'),
   'no-bare-symlink-in-tests': require('./rules/no-bare-symlink-in-tests.cjs'),
+  'no-process-exit-in-phase': require('./rules/no-process-exit-in-phase.cjs'),
 };
 
 /**
@@ -136,6 +137,14 @@ const RECOMMENDED_EXCLUDE = new Set([
   // ride in `recommended`; that is a public-API change and has not been made.
   // VAT enables the whole rule explicitly, scoped to its own conventions.
   'no-bare-symlink-in-tests',
+  // Excluded because it keys on a NAMING CONVENTION that is VAT's, not a
+  // portable fact — the same reason `no-unsafe-root-join` is excluded above. The
+  // hazard it guards is real and general (an in-process orchestrator whose step
+  // calls `process.exit()` silently skips every later step), but the marker is
+  // the `…Phase` suffix, and an adopter with an unrelated `computeRenderPhase()`
+  // that legitimately exits would get a finding they cannot act on. It ships in
+  // `rules` and VAT enables it explicitly, scoped to its own orchestrators.
+  'no-process-exit-in-phase',
 ]);
 
 /**

package/eslint/index.d.cts

@@ -47,13 +47,20 @@ declare namespace plugin {
     rules: Record<string, RuleModule>;
     configs: {
       /**
-       * The cross-platform safety core: 18 of the 22 rules, 15 `error` / 3 `warn`.
-       * Four are excluded, for three reasons: `no-test-scoped-functions` and
-       * `require-justified-skip` are positions on test style rather than
-       * portability facts; `no-unsafe-root-join` keys on naming rather than taint;
-       * and `no-raw-text-decode` names a decoding seam that only exists in the
-       * consuming repo. All four still ship in `rules` and are enabled by naming
-       * them.
+       * The cross-platform safety core: 18 of the 25 rules, 15 `error` / 3 `warn`.
+       *
+       * Seven are excluded, for four reasons. `no-test-scoped-functions`,
+       * `require-justified-skip` and `no-bare-symlink-in-tests` are positions on
+       * TEST STYLE rather than portability facts. `no-unsafe-root-join` and
+       * `no-process-exit-in-phase` key on NAMING rather than on the property they
+       * care about (taint, and an orchestrated call site). `no-raw-text-decode`
+       * names a decoding SEAM that only exists in the consuming repo. And
+       * `no-self-package-import` REQUIRES an option this config cannot supply.
+       *
+       * All seven still ship in `rules` and are enabled by naming them — which is
+       * what this repo's own `eslint.config.js` does. The count above is asserted
+       * by `packages/utils/test/eslint/rules.test.ts`, so it cannot drift
+       * unnoticed the way it did when this comment said "four".
        */
       recommended: FlatConfig;
     };

package/eslint/rules/no-process-exit-in-phase.cjs

@@ -0,0 +1,117 @@
+/**
+ * ESLint Rule: no-process-exit-in-phase
+ *
+ * Forbid `process.exit()` inside a phase entry point — a function whose name
+ * ends in `Phase`.
+ *
+ * ## Why this rule exists
+ *
+ * `vat validate`, `vat verify` and `vat build` used to run each phase as a
+ * SEPARATE CHILD PROCESS. A `process.exit()` inside a phase was then perfectly
+ * safe: it ended that child, the parent read the exit code, and the run carried
+ * on to the next phase. Nothing about the code said so — the safety came
+ * entirely from the process boundary.
+ *
+ * That boundary is gone. Phases now run in the orchestrator's own process, so a
+ * surviving `process.exit()` ends THE WHOLE RUN: every later phase is silently
+ * skipped, the parent's aggregation never happens, and the process exits 0-or-1
+ * having done half the work with nothing in the document to say so. It is the
+ * worst shape of failure this codebase has — a confident, well-formed, wrong
+ * answer — and it cannot be caught by a type, because `process.exit()`
+ * typechecks anywhere.
+ *
+ * A phase must RETURN `{ document, exitCode }` and let its caller decide whether
+ * to print and exit (a command-line run) or to fold the result into the run (an
+ * orchestrated one).
+ *
+ * ## Why the name is the marker
+ *
+ * The `…Phase` suffix is the convention every phase entry point already follows
+ * (`runResourcesValidatePhase`, `runSkillsBuildPhase`, …). Keying the rule to it
+ * means a new phase is protected the moment it is named like one, with no list
+ * to keep in sync — a list is the thing that goes stale silently, which is the
+ * defect class this rule exists to prevent in the first place.
+ *
+ * The thin Commander wrappers that CALL these functions keep their
+ * `process.exit()`: deciding how the process ends is exactly their job, and they
+ * are not named `…Phase`.
+ */
+
+/** Does this call expression read as `process.exit(...)`? */
+function isProcessExitCall(node) {
+  const { callee } = node;
+  return (
+    callee.type === 'MemberExpression' &&
+    !callee.computed &&
+    callee.object.type === 'Identifier' &&
+    callee.object.name === 'process' &&
+    callee.property.type === 'Identifier' &&
+    callee.property.name === 'exit'
+  );
+}
+
+/**
+ * The declared name of a function-ish node, however it was declared.
+ *
+ * Covers the three spellings a phase entry point can legitimately take: a
+ * function declaration, a `const x = function () {}`, and a `const x = () => {}`.
+ * A rule that only understood declarations would be silently inert against an
+ * arrow const — the same blind spot `no-test-scoped-functions` documents.
+ */
+function functionName(node) {
+  if (node.id && node.id.type === 'Identifier') return node.id.name;
+
+  const { parent } = node;
+  if (parent && parent.type === 'VariableDeclarator' && parent.id.type === 'Identifier') {
+    return parent.id.name;
+  }
+  if (parent && parent.type === 'Property' && parent.key.type === 'Identifier') {
+    return parent.key.name;
+  }
+  return undefined;
+}
+
+const FUNCTION_TYPES = new Set([
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'ArrowFunctionExpression',
+]);
+
+/** The nearest enclosing function named like a phase entry point, if any. */
+function enclosingPhaseName(node) {
+  for (let current = node.parent; current; current = current.parent) {
+    if (!FUNCTION_TYPES.has(current.type)) continue;
+    const name = functionName(current);
+    if (name !== undefined && name.endsWith('Phase')) return name;
+  }
+  return undefined;
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Forbid process.exit() inside a phase entry point, where it would end the whole orchestrated run',
+      category: 'Agentic Code Safety',
+      recommended: true,
+    },
+    fixable: null,
+    schema: [],
+    messages: {
+      exitInPhase:
+        "'{{name}}' is a phase entry point, so process.exit() here ends the ENTIRE run — every later phase is skipped and the orchestrator never aggregates. Return { document, exitCode } instead and let the caller decide how the process ends.",
+    },
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (!isProcessExitCall(node)) return;
+        const name = enclosingPhaseName(node);
+        if (name === undefined) return;
+        context.report({ node, messageId: 'exitInPhase', data: { name } });
+      },
+    };
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/utils",
-  "version": "0.2.0-rc.3",
+  "version": "0.2.0-rc.4",
   "type": "module",
   "description": "Core utility functions shared across the vibe-agent-toolkit packages",
   "sideEffects": [
@@ -54,9 +54,9 @@
       "types": "./dist/zod.d.ts",
       "import": "./dist/zod.js"
     },
-    "./template": {
-      "types": "./dist/template-entry.d.ts",
-      "import": "./dist/template-entry.js"
+    "./skill-test": {
+      "types": "./dist/skill-test/index.d.ts",
+      "import": "./dist/skill-test/index.js"
     },
     "./yaml": {
       "types": "./dist/yaml.d.ts",
@@ -90,17 +90,15 @@
     "README.md"
   ],
   "scripts": {
-    "build": "rimraf --glob dist \"*.tsbuildinfo\" && tsc && tsx ../dev-tools/src/copy-yaml-assets.ts",
+    "build": "rimraf --glob dist \"*.tsbuildinfo\" && tsc",
     "test:unit": "vitest run",
     "test:integration": "vitest run --config vitest.integration.config.ts",
-    "test:system": "vitest run --config vitest.system.config.ts",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "clean": "rimraf dist *.tsbuildinfo"
   },
   "dependencies": {
     "@vibe-validate/git": "0.20.1",
-    "handlebars": "^4.7.8",
     "ignore": "^7.0.5",
     "picomatch": "^4.0.3",
     "which": "^5.0.0",

package/dist/link-auth/build-headers.d.ts

@@ -1,34 +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).
- */
-export declare const REDACTED_VALUE = "<redacted>";
-/**
- * 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 declare function buildHeaders(templates: Record<string, string>, context: Record<string, string>): Record<string, string>;
-/**
- * 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 declare function redactHeaders(headers: Record<string, string>): Record<string, string>;
-//# sourceMappingURL=build-headers.d.ts.map

package/dist/link-auth/build-headers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"build-headers.d.ts","sourceRoot":"","sources":["../../src/link-auth/build-headers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,eAAO,MAAM,cAAc,eAAe,CAAC;AAc3C;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMrF"}

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;AA+CH;;;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"}