@davidorex/pi-jit-agents 0.14.6 → 0.28.0

package/CHANGELOG.md

@@ -1 +1,50 @@
 # Changelog
+
+All notable changes to this package are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/). This package has had two public npm releases (`0.14.6`, `0.26.0`); the entries below are scoped to its published surface (`src/`, `schemas/`, `templates/`), and `[Unreleased]` holds changes since `0.26.0`.
+
+## [Unreleased]
+
+## [0.28.0] - 2026-06-03
+
+### Added
+- Six whole-block delegator macros (`render_decisions`, `render_features`, `render_framework_gaps`, `render_layer_plans`, `render_research`, `render_spec_reviews`) in `shared/macros.md` as thin wrappers over per-item macros (`dce327d`)
+- `array_key` column on the `CANONICAL_MACRO_NAMES` registry, surfacing block_kind ≠ data-key divergences (framework-gaps→gaps, layer-plans→plans, spec-reviews→reviews); reader call-sites use the `.macro_name` property (`0fb6149`)
+- `TraceEntry` `extension_load_warning` entry kind (`8030c61`)
+- Grant-clamp infrastructure: `CompiledAgent.tools` + `DispatchContext.parentGrant`; `spec.tools` threaded through `compileAgent`; `GrantViolationError` clamping child-tools to a subset of the parent grant at the `executeAgent` dispatch boundary (`dee01a5`, `4e9a866`, `a273ab9`)
+
+### Changed
+- Relocated the agent-template tree `packages/pi-workflows/templates/` → `packages/pi-jit-agents/templates/` and added a `bundledTemplateDir()` export; consumer call-sites rewired (`d71b48e`)
+- Neutralized `.project` references in agent-reachable code strings (`5024158`)
+- Stripped development-history citations from `agent-trace.schema.json` (`2f3ef47`)
+
+## [0.26.0] - 2026-05-25
+
+Covers `v0.14.6..v0.26.0` for the package's published surface.
+
+### Added
+- `contextBlocks` widened to `(string | ContextBlockRef)[]` for per-item injection; object-form `contextBlocks` wired through `compileAgent`; multi-entry-same-name injection (`9f7eb42`, `4d1fd1d`, `a0c6467`)
+- Renderer registry mapping block kinds to per-item Nunjucks macro refs; composition-primitive surface symmetry (three tools, Nunjucks global, macro wiring) (`38fb27e`, `5341b2b`)
+- `x-prompt-budget` enforcement primitive + narrative-field annotations on six newer block schemas (`be7a168`)
+
+### Changed
+- Context-block delimiters adopt the pi 0.75.x XML-tag convention (`d153877`)
+- Migrated consumers to the pi-context `context` vocabulary; retired per-item-macro duplication via shared helpers + a canonical-name registry map (`187c094`, `161bf4e`, `188f351`, `80b6915`)
+- Migrated pi-mono peer-deps `@mariozechner/*` → `@earendil-works/*` at `^0.74.0` (`e5ab8ad`)
+
+### Fixed
+- `compile.ts` catches `BootstrapNotFoundError` at `projectDir` + `buildIdIndex` call sites (`ba58d78`)
+- Empty-prefix guard + cross-block status-vocab check + name-based error catches (`4fb4d1e`)
+
+## [0.14.6] - 2026-04-28
+
+Covers the package from its extraction (`239f718`, 2026-04-12) through its first public release.
+
+### Added
+- Initial extraction of `@davidorex/pi-jit-agents`: agent spec compilation (`agent-spec`), agent-trace SDK, and the verdict/agent-trace/trace-config schemas (`239f718`)
+- Monitor classify trace capture aligned to canonical pi (`1bc36ba`)
+
+### Changed
+- Bumped pi-mono `0.63.1` → `0.70.2`; migrated TypeBox v0.34 → v1.x via a hybrid import strategy (`11a4069`)
+
+### Fixed
+- Provider-aware `toolChoice` normalization at the execute boundary (`ce37772`)

package/README.md

@@ -18,7 +18,7 @@ There is one concept of "agent" regardless of whether a workflow step or a monit
 The package owns four public surfaces:
 
 - `loadAgent(name, ctx) → AgentSpec` — resolves spec from discovery tiers, fully resolves all path fields to absolute
-- `compileAgent(spec, ctx) → CompiledAgent` — renders templates, injects `contextBlocks` from `.project/`, composes final prompts
+- `compileAgent(spec, ctx) → CompiledAgent` — renders templates, injects `contextBlocks` from the substrate directory, composes final prompts
 - `executeAgent(compiled, dispatch) → JitAgentResult` — in-process LLM dispatch with phantom tool enforcement
 - `agentContract(spec) → AgentContract` — projection for introspection, no execution
 
@@ -28,7 +28,7 @@ Subprocess dispatch stays in pi-workflows. The package never reads from `.pi/`
 
 Agent specs are searched in this order:
 
-1. `{cwd}/.project/agents/{name}.agent.yaml` — project-level overrides
+1. `{cwd}/<substrate-dir>/agents/{name}.agent.yaml` — project-level overrides
 2. `{userDir ?? ~/.pi/agent/agents/}/{name}.agent.yaml` — user-global overrides
 3. `{builtinDir}/{name}.agent.yaml` — consumer-supplied builtins
 

package/dist/agent-spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-spec.d.ts","sourceRoot":"","sources":["../src/agent-spec.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAmCzD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CA6C1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,CAkB/E"}
+{"version":3,"file":"agent-spec.d.ts","sourceRoot":"","sources":["../src/agent-spec.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,SAAS,EAAmB,WAAW,EAAE,MAAM,YAAY,CAAC;AAuI1E;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAiD1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,CAyB/E"}

package/dist/agent-spec.js

@@ -7,6 +7,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { tryResolveContextDir } from "@davidorex/pi-context/context-dir";
 import { parse as parseYaml } from "yaml";
 import { AgentNotFoundError, AgentParseError } from "./errors.js";
 /**
@@ -43,6 +44,60 @@ function resolveSpecPath(value, specDir) {
         return value;
     return path.resolve(specDir, value);
 }
+/**
+ * Validate and normalise a single `contextBlocks` entry.
+ *
+ * Accepts:
+ * - a non-empty string (whole-block reference, the established surface), or
+ * - an object with a required string `name` and optional `item` (string),
+ *   `focus` (record of string→string), and `depth` (non-negative number).
+ *
+ * Throws `AgentParseError` with a descriptive message naming the offending
+ * entry's index and the failing constraint. Plan 4 (Wave 2) consumes the
+ * resulting union shape; this helper does not assign any runtime semantics.
+ */
+function parseContextBlockEntry(entry, index, agentName, filePath) {
+    if (typeof entry === "string") {
+        if (entry.length === 0) {
+            throw new AgentParseError(agentName, filePath, new Error(`contextBlocks[${index}]: bare-string entry must be non-empty`));
+        }
+        return entry;
+    }
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+        throw new AgentParseError(agentName, filePath, new Error(`contextBlocks[${index}]: entry must be a string or an object with at least { name: string }; got ${Array.isArray(entry) ? "array" : entry === null ? "null" : typeof entry}`));
+    }
+    const obj = entry;
+    if (typeof obj.name !== "string" || obj.name.length === 0) {
+        throw new AgentParseError(agentName, filePath, new Error(`contextBlocks[${index}]: object form requires a non-empty string \`name\` field`));
+    }
+    const out = { name: obj.name };
+    if (obj.item !== undefined) {
+        if (typeof obj.item !== "string" || obj.item.length === 0) {
+            throw new AgentParseError(agentName, filePath, new Error(`contextBlocks[${index}].item: when present must be a non-empty string`));
+        }
+        out.item = obj.item;
+    }
+    if (obj.focus !== undefined) {
+        if (obj.focus === null || typeof obj.focus !== "object" || Array.isArray(obj.focus)) {
+            throw new AgentParseError(agentName, filePath, new Error(`contextBlocks[${index}].focus: when present must be an object mapping string keys to string values`));
+        }
+        const focus = {};
+        for (const [k, v] of Object.entries(obj.focus)) {
+            if (typeof v !== "string") {
+                throw new AgentParseError(agentName, filePath, new Error(`contextBlocks[${index}].focus.${k}: value must be a string; got ${typeof v}`));
+            }
+            focus[k] = v;
+        }
+        out.focus = focus;
+    }
+    if (obj.depth !== undefined) {
+        if (typeof obj.depth !== "number" || !Number.isFinite(obj.depth) || obj.depth < 0 || !Number.isInteger(obj.depth)) {
+            throw new AgentParseError(agentName, filePath, new Error(`contextBlocks[${index}].depth: when present must be a non-negative integer; got ${String(obj.depth)}`));
+        }
+        out.depth = obj.depth;
+    }
+    return out;
+}
 /**
  * Parse a YAML agent spec file into a fully-resolved AgentSpec.
  *
@@ -89,7 +144,9 @@ export function parseAgentYaml(filePath) {
         inputSchema: spec.input,
         outputFormat: spec.output?.format,
         outputSchema: resolveSpecPath(spec.output?.schema, specDir),
-        contextBlocks: Array.isArray(spec.contextBlocks) ? spec.contextBlocks : undefined,
+        contextBlocks: Array.isArray(spec.contextBlocks)
+            ? spec.contextBlocks.map((entry, index) => parseContextBlockEntry(entry, index, spec.name || name, filePath))
+            : undefined,
         loadedFrom: specDir,
     };
 }
@@ -108,11 +165,18 @@ export function parseAgentYaml(filePath) {
  */
 export function createAgentLoader(ctx) {
     const userTier = ctx.userDir ?? path.join(os.homedir(), ".pi", "agent", "agents");
+    // Resolve the project tier once (FGAP-074 C3): pointer-less repos degrade by
+    // omitting the project-tier search path so the loader still searches the
+    // user/builtin tiers and ultimately throws its normal AgentNotFoundError
+    // (NOT BootstrapNotFoundError). `agentsDir(cwd)` was `<contextDir>/agents`,
+    // so the inline equivalent is `path.join(base, "agents", ...)`.
+    const base = tryResolveContextDir(ctx.cwd);
     return (name) => {
-        const searchPaths = [
-            path.join(ctx.cwd, ".project", "agents", `${name}.agent.yaml`),
-            path.join(userTier, `${name}.agent.yaml`),
-        ];
+        const searchPaths = [];
+        if (base !== null) {
+            searchPaths.push(path.join(base, "agents", `${name}.agent.yaml`));
+        }
+        searchPaths.push(path.join(userTier, `${name}.agent.yaml`));
         if (ctx.builtinDir) {
             searchPaths.push(path.join(ctx.builtinDir, `${name}.agent.yaml`));
         }

package/dist/agent-spec.js.map

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

package/dist/budget-enforcer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Render-time prompt-budget enforcement primitive.
+ *
+ * Reads `x-prompt-budget` annotations from a JSON Schema field and, when the
+ * rendered output exceeds the declared budget, returns tail-truncated output
+ * plus a structured warning. Annotation absence is pass-through; malformed
+ * annotations throw with the field path named in the error.
+ *
+ * Plan 5 of the per-item-macros work ships this primitive plus the schema
+ * annotations themselves (`.project/schemas/*.schema.json`). Per-item macros
+ * (Plans 6 and 7) consume the primitive to gate field rendering.
+ *
+ * Token measurement is intentionally a coarse approximation: whitespace +
+ * Unicode-punctuation split, not a tokenizer-accurate count tied to any
+ * specific model. The aim is a render-time signal, not a billing surface.
+ */
+export interface PromptBudget {
+    tokens?: number;
+    words?: number;
+}
+export interface BudgetWarning {
+    field: string;
+    budget: PromptBudget;
+    actual: {
+        tokens: number;
+        words: number;
+    };
+    truncated: boolean;
+}
+export interface BudgetResult {
+    output: string;
+    warning: BudgetWarning | null;
+}
+/**
+ * If the schema field at `fieldPath` declares `x-prompt-budget`, measure
+ * `rendered` and return tail-truncated output + warning when over budget.
+ * If the field has no annotation, return `{ output: rendered, warning: null }`.
+ *
+ * Empty `rendered` short-circuits to pass-through regardless of annotation —
+ * there is nothing to measure or truncate.
+ */
+export declare function enforceBudget(rendered: string, schema: object, fieldPath: string): BudgetResult;
+//# sourceMappingURL=budget-enforcer.d.ts.map

package/dist/budget-enforcer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-enforcer.d.ts","sourceRoot":"","sources":["../src/budget-enforcer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,YAAY;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,SAAS,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;CAC9B;AA6HD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,CAkC/F"}

package/dist/budget-enforcer.js

@@ -0,0 +1,172 @@
+/**
+ * Render-time prompt-budget enforcement primitive.
+ *
+ * Reads `x-prompt-budget` annotations from a JSON Schema field and, when the
+ * rendered output exceeds the declared budget, returns tail-truncated output
+ * plus a structured warning. Annotation absence is pass-through; malformed
+ * annotations throw with the field path named in the error.
+ *
+ * Plan 5 of the per-item-macros work ships this primitive plus the schema
+ * annotations themselves (`.project/schemas/*.schema.json`). Per-item macros
+ * (Plans 6 and 7) consume the primitive to gate field rendering.
+ *
+ * Token measurement is intentionally a coarse approximation: whitespace +
+ * Unicode-punctuation split, not a tokenizer-accurate count tied to any
+ * specific model. The aim is a render-time signal, not a billing surface.
+ */
+const TRUNCATION_MARKER = "[…truncated to budget]";
+/**
+ * Approximate token count: split on Unicode whitespace + punctuation, drop empties.
+ * Not tokenizer-accurate; meant as a render-time proxy for prompt-size signal.
+ */
+function countTokens(text) {
+    if (text === "")
+        return 0;
+    return text.split(/[\s\p{P}]+/u).filter(Boolean).length;
+}
+/**
+ * Word count: whitespace split, drop empties.
+ */
+function countWords(text) {
+    if (text === "")
+        return 0;
+    return text.split(/\s+/).filter(Boolean).length;
+}
+/**
+ * Resolve a JSON-pointer-style path against a schema object.
+ *
+ * Path interpretation:
+ * - Leading "/" is optional; treated as the root delimiter.
+ * - Segments are split on "/" with no JSON Pointer escape handling
+ *   (we do not encounter "~" or "/" inside schema keys in practice).
+ * - Each segment is looked up as a property key on the current node.
+ * - Returns null if any segment is missing.
+ *
+ * Example: "/properties/research/items/properties/findings_summary"
+ */
+function resolveSchemaField(schema, fieldPath) {
+    const trimmed = fieldPath.startsWith("/") ? fieldPath.slice(1) : fieldPath;
+    if (trimmed === "")
+        return schema;
+    const segments = trimmed.split("/");
+    let cursor = schema;
+    for (const segment of segments) {
+        if (cursor === null || typeof cursor !== "object")
+            return null;
+        const next = cursor[segment];
+        if (next === undefined)
+            return null;
+        cursor = next;
+    }
+    if (cursor === null || typeof cursor !== "object")
+        return null;
+    return cursor;
+}
+/**
+ * Validate a raw `x-prompt-budget` annotation into a typed PromptBudget.
+ * Throws AgentBudgetError-style Error naming the field on malformed input.
+ */
+function parseBudget(raw, fieldPath) {
+    if (raw === null || typeof raw !== "object") {
+        throw new Error(`x-prompt-budget at ${fieldPath} must be an object, got ${typeof raw}`);
+    }
+    const obj = raw;
+    const out = {};
+    if ("tokens" in obj) {
+        const t = obj.tokens;
+        if (typeof t !== "number" || !Number.isFinite(t) || t < 0 || !Number.isInteger(t)) {
+            throw new Error(`x-prompt-budget at ${fieldPath}: tokens must be a non-negative integer, got ${JSON.stringify(t)}`);
+        }
+        out.tokens = t;
+    }
+    if ("words" in obj) {
+        const w = obj.words;
+        if (typeof w !== "number" || !Number.isFinite(w) || w < 0 || !Number.isInteger(w)) {
+            throw new Error(`x-prompt-budget at ${fieldPath}: words must be a non-negative integer, got ${JSON.stringify(w)}`);
+        }
+        out.words = w;
+    }
+    if (out.tokens === undefined && out.words === undefined) {
+        throw new Error(`x-prompt-budget at ${fieldPath} declares neither tokens nor words; at least one must be present`);
+    }
+    return out;
+}
+/**
+ * Tail-truncate `text` so that it fits both `maxTokens` and `maxWords` (when set).
+ * Strategy: binary-search the smallest character-prefix length whose token+word
+ * counts (with the marker appended) satisfy both budgets. The marker itself
+ * adds a small fixed cost that is included in the count.
+ *
+ * If `text` already fits, returns `text` unchanged with `truncated: false`.
+ */
+function tailTruncate(text, budget) {
+    const fitsBudget = (s) => {
+        if (budget.tokens !== undefined && countTokens(s) > budget.tokens)
+            return false;
+        if (budget.words !== undefined && countWords(s) > budget.words)
+            return false;
+        return true;
+    };
+    if (fitsBudget(text)) {
+        return { output: text, truncated: false };
+    }
+    // If even the marker alone is over budget, return just the marker (best effort).
+    if (!fitsBudget(TRUNCATION_MARKER)) {
+        return { output: TRUNCATION_MARKER, truncated: true };
+    }
+    // Binary-search the largest prefix length such that prefix + " " + marker fits.
+    let lo = 0;
+    let hi = text.length;
+    let best = 0;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const candidate = `${text.slice(0, mid).trimEnd()} ${TRUNCATION_MARKER}`;
+        if (fitsBudget(candidate)) {
+            best = mid;
+            lo = mid + 1;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    const output = `${text.slice(0, best).trimEnd()} ${TRUNCATION_MARKER}`;
+    return { output, truncated: true };
+}
+/**
+ * If the schema field at `fieldPath` declares `x-prompt-budget`, measure
+ * `rendered` and return tail-truncated output + warning when over budget.
+ * If the field has no annotation, return `{ output: rendered, warning: null }`.
+ *
+ * Empty `rendered` short-circuits to pass-through regardless of annotation —
+ * there is nothing to measure or truncate.
+ */
+export function enforceBudget(rendered, schema, fieldPath) {
+    if (rendered === "") {
+        return { output: "", warning: null };
+    }
+    const fieldNode = resolveSchemaField(schema, fieldPath);
+    if (fieldNode === null) {
+        return { output: rendered, warning: null };
+    }
+    const annotation = fieldNode["x-prompt-budget"];
+    if (annotation === undefined) {
+        return { output: rendered, warning: null };
+    }
+    const budget = parseBudget(annotation, fieldPath);
+    const actualTokens = countTokens(rendered);
+    const actualWords = countWords(rendered);
+    const overTokens = budget.tokens !== undefined && actualTokens > budget.tokens;
+    const overWords = budget.words !== undefined && actualWords > budget.words;
+    if (!overTokens && !overWords) {
+        return { output: rendered, warning: null };
+    }
+    const { output, truncated } = tailTruncate(rendered, budget);
+    const warning = {
+        field: fieldPath,
+        budget,
+        actual: { tokens: actualTokens, words: actualWords },
+        truncated,
+    };
+    return { output, warning };
+}
+//# sourceMappingURL=budget-enforcer.js.map

package/dist/budget-enforcer.js.map

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

package/dist/compile.d.ts

@@ -1,4 +1,43 @@
+import { type ItemLocation } from "@davidorex/pi-context";
+import type nunjucks from "nunjucks";
+import { type BudgetWarning } from "./budget-enforcer.js";
+import type { RendererRegistry } from "./renderer-registry.js";
 import type { AgentSpec, CompileContext, CompiledAgent } from "./types.js";
+/**
+ * Register the composition-time Nunjucks globals on a template environment.
+ *
+ * Three globals are registered, scoped to the closure-captured state passed in:
+ *
+ *   - `resolve(id)` — looks up an item by ID via the lazy idIndex; returns
+ *                     ItemLocation or null. Used by macros to dispatch
+ *                     cross-block references.
+ *   - `render_recursive(loc, depth)` — renders an item via the registered
+ *                     per-item macro (resolved through the renderer registry).
+ *                     Cycle-detected via the visited set.
+ *   - `enforceBudget(rendered, blockName, fieldPathOrShorthand)` — measures
+ *                     rendered text against the field's `x-prompt-budget`
+ *                     annotation, returning truncated output when over budget;
+ *                     pass-through when annotation absent. Truncation warnings
+ *                     are appended to `warningsCollector` (closure-captured by
+ *                     the caller) so callers can surface them after compile
+ *                     returns.
+ *
+ * Used by both `compileAgent` (this module) and `renderItemById` in pi-workflows
+ * — the single source of truth for the composition-globals contract. Adding
+ * a new global, changing a signature, or adjusting a fallback means editing
+ * here and the contract propagates to every caller.
+ *
+ * The visited-set lifetime is one call to this function — sequential calls on
+ * the same env get isolated cycle scopes. addGlobal overwrites prior bindings,
+ * which is intentional (each composition pass owns its own scope).
+ */
+export declare function registerCompositionGlobals(opts: {
+    env: nunjucks.Environment;
+    cwd: string;
+    rendererRegistry: RendererRegistry | undefined;
+    getIdIndex: () => Map<string, ItemLocation>;
+    warningsCollector: BudgetWarning[];
+}): void;
 /**
  * Compile an AgentSpec into a CompiledAgent.
  *

package/dist/compile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../src/compile.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA8B3E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,cAAc,GAAG,aAAa,CAiEhF"}
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../src/compile.ts"],"names":[],"mappings":"AAcA,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGxE,OAAO,KAAK,QAAQ,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,sBAAsB,CAAC;AAKzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAmB,MAAM,YAAY,CAAC;AAE5F;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAChD,GAAG,EAAE,QAAQ,CAAC,WAAW,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC/C,UAAU,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC5C,iBAAiB,EAAE,aAAa,EAAE,CAAC;CACnC,GAAG,IAAI,CA+EP;AA8DD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,cAAc,GAAG,aAAa,CAiXhF"}