homegraph 1.5.2 → 1.5.4

package/dist/addons/init-template.js

@@ -0,0 +1,290 @@
+"use strict";
+/**
+ * Addon scaffold generator (`homegraph addon init`).
+ *
+ * Produces a publishable npm package skeleton with the `homegraph` marker,
+ * an `enrich` stub, and a worked Jira example (parse ticket refs → fetch
+ * details → return supplements).
+ *
+ * @module addons/init-template
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAddonScaffold = createAddonScaffold;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function packageJson(name, lang) {
+    const entry = lang === 'ts' ? './dist/index.js' : './index.mjs';
+    return JSON.stringify({
+        name,
+        version: '0.1.0',
+        description: 'HomeGraph addon: enrich spec-mine prompts with external requirement data',
+        type: 'module',
+        exports: { '.': entry },
+        files: lang === 'ts' ? ['dist', 'examples'] : ['index.mjs', 'examples'],
+        scripts: lang === 'ts' ? { build: 'tsc' } : undefined,
+        // TypeScript needs the homegraph type declarations to compile.
+        devDependencies: lang === 'ts' ? { homegraph: 'latest' } : undefined,
+        homegraph: { addon: true, api: 1 },
+    }, null, 2) + '\n';
+}
+function tsconfig() {
+    return JSON.stringify({
+        compilerOptions: {
+            target: 'ES2022',
+            module: 'NodeNext',
+            moduleResolution: 'NodeNext',
+            outDir: 'dist',
+            declaration: true,
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+        },
+        include: ['index.ts'],
+    }, null, 2) + '\n';
+}
+/** Shared body of the enrich stub — identical for JS and TS. */
+function enrichBody() {
+    return `  const supplements = [];
+  for (const commit of input.commits) {
+    const match = /([A-Z]+-\\d+)/.exec(commit.commitMessage);
+    if (match) {
+      supplements.push({
+        key: match[1],
+        text: \`Requirement \${match[1]}: replace this with fetched details.\`,
+        commitHash: commit.commitHash,
+      });
+    }
+  }
+  return supplements;
+`;
+}
+function indexSource(name, lang) {
+    const head = `/**
+ * ${name} — HomeGraph spec-mine addon.
+ *
+ * Contract (api 1) — implement at least one hook:
+ *   - enrich(input):      add external requirement context (e.g. Jira) as
+ *                         supplements; HomeGraph dedupes by \`key\` and renders
+ *                         them into a "## Supplement" prompt section.
+ *   - buildPrompt(ctx):   optional escape hatch that takes over the whole
+ *                         prompt assembly (see ctx.limits — a soft contract).
+ *
+ * Data shapes (all passed in — you never run git):
+ *
+ *   input                { clusterId, commits }
+ *   input.commits[i]     { commitHash, commitMessage, author, timestamp }
+ *     - commitMessage    first line of the commit message
+ *     - timestamp        unix seconds
+ *
+ *   Supplement           { key?, text, commitHash? }
+ *     - key              opaque dedupe id (e.g. the ticket key); without it,
+ *                        exact-text dedup is used
+ *     - text             required — the requirement description you assembled
+ *     - commitHash       optional — surfaced for traceability
+ *
+ *   buildPrompt ctx      { cluster, supplements, template, limits }
+ *     - cluster          { id, commits, primaryFiles, primarySymbols }
+ *     - supplements      already deduplicated by HomeGraph
+ *     - template         output template (default or user --template)
+ *     - limits           { maxContextChars, maxSupplementChars } — soft
+ *                        contract you are expected to honor
+ *
+ * Return one Supplement per requirement. Both hooks are optional but at
+ * least one must be implemented.
+`;
+    if (lang === 'ts') {
+        return (`import type { EnrichInput, Supplement } from 'homegraph';\n\n` +
+            head +
+            ` */\n\n` +
+            `export async function enrich(input: EnrichInput): Promise<Supplement[]> {\n` +
+            enrichBody() +
+            `}\n`);
+    }
+    return (head +
+        ` * @param {import('homegraph').EnrichInput} input - one commit cluster.
+ * @returns {Promise<import('homegraph').Supplement[]>}
+ */
+
+export async function enrich(input) {
+` +
+        enrichBody() +
+        `}
+`);
+}
+const JIRA_EXAMPLE = `// Worked example: fetch requirement details from Jira and render them as
+// supplements. Standalone — drop this file into any addon's examples/ dir.
+//
+// Data shapes (enrich input / Supplement / buildPrompt ctx): see the
+// contract comment at the top of index.mjs.
+//
+//   const JIRA_BASE = process.env.JIRA_BASE_URL ?? 'https://your-domain.atlassian.net';
+//   const JIRA_EMAIL = process.env.JIRA_EMAIL ?? '';
+//   const JIRA_TOKEN = process.env.JIRA_API_TOKEN ?? '';
+//   const TICKET_RE = /([A-Z]+-\\d+)/g;
+
+export async function enrich(input) {
+  const seen = new Set();
+  const supplements = [];
+  for (const commit of input.commits) {
+    for (const match of commit.commitMessage.matchAll(TICKET_RE)) {
+      const key = match[1];
+      if (seen.has(key)) continue; // dedupe across commits in the cluster
+      seen.add(key);
+      supplements.push({ key, text: await fetchTicket(key), commitHash: commit.commitHash });
+    }
+  }
+  return supplements;
+}
+
+async function fetchTicket(key) {
+  if (!JIRA_TOKEN) return \`\${key}: set JIRA_API_TOKEN to fetch details.\`;
+  const res = await fetch(\`\${JIRA_BASE}/rest/api/3/issue/\${key}\`, {
+    headers: { Authorization: 'Basic ' + btoa(JIRA_EMAIL + ':' + JIRA_TOKEN) },
+  });
+  if (!res.ok) return \`\${key}: fetch failed (\${res.status}).\`;
+  const issue = await res.json();
+  const summary = issue.fields?.summary ?? '(no summary)';
+  const description = issue.fields?.description ?? '';
+  return \`\${key} — \${summary}\\n\${description}\`;
+}
+`;
+const BUILD_PROMPT_EXAMPLE = `// buildPrompt example — the optional escape hatch that takes over the whole
+// prompt assembly. Copy it into index.mjs (or re-export it). When an addon
+// implements both hooks, buildPrompt wins for assembly while enrich still
+// runs first — its supplements reach you via ctx.supplements.
+//
+// Input  ctx: { cluster, supplements, template, limits }
+//   - cluster:     { id, commits, primaryFiles, primarySymbols }
+//   - supplements: already deduplicated by HomeGraph
+//   - template:    output template (default or user --template)
+//   - limits:      { maxContextChars, maxSupplementChars } — soft contract
+// Output: the full user prompt string. Throwing falls back to the default
+// assembler, so you can experiment freely.
+export async function buildPrompt(ctx) {
+  const { cluster, supplements, template } = ctx;
+
+  // Your own section first, then the built-in structure.
+  const supplementLines = supplements.map(
+    (s) => \`- \${s.text}\${s.commitHash ? \` (commit \${s.commitHash.slice(0, 7)})\` : ''}\`,
+  );
+
+  return [
+    supplements.length > 0 ? '## Supplement' : null,
+    ...(supplements.length > 0 ? supplementLines : []),
+    '',
+    \`## Cluster Context — \${cluster.commits.length} commits\`,
+    \`Primary files: \${cluster.primaryFiles.join(', ') || '(none)'}\`,
+    \`Primary symbols: \${cluster.primarySymbols.join(', ') || '(none)'}\`,
+    '',
+    '---',
+    '',
+    'Fill in this template:',
+    '',
+    template,
+  ]
+    .filter(Boolean)
+    .join('\\n');
+}
+`;
+const README = `# HomeGraph Addon
+
+A pluggable extension for \`homegraph spec mine\`: enrich cluster prompts with
+external requirement context (Jira, internal trackers, APIs) without
+HomeGraph knowing any ticket format.
+
+## Contract (api 1)
+
+- \`enrich(input)\` → \`Supplement[]\`
+  - \`input\`: \`{ clusterId, commits }\` — HomeGraph passes every commit it
+    already knows, never re-runs git.
+  - \`input.commits[i]\`: \`{ commitHash, commitMessage, author, timestamp }\`
+    (commitMessage is the first line; timestamp is unix seconds).
+  - Return one \`Supplement\` per requirement:
+    - \`key\` (optional): opaque dedupe id (e.g. the ticket key); without it,
+      exact-text dedup is used.
+    - \`text\` (required): the requirement description you assembled
+      (title / URL / body all fine).
+    - \`commitHash\` (optional): surfaced for traceability.
+  - HomeGraph renders supplements into a \`## Supplement\` prompt section.
+- \`buildPrompt(ctx)\` (optional escape hatch) — takes over prompt assembly
+  entirely. \`ctx\`: \`{ cluster, supplements, template, limits }\`
+  - \`cluster\`: \`{ id, commits, primaryFiles, primarySymbols }\`
+  - \`supplements\`: already deduplicated by HomeGraph.
+  - \`template\`: the output template (default or user \`--template\`).
+  - \`limits\`: \`{ maxContextChars, maxSupplementChars }\` — a soft contract
+    you are expected to honor.
+
+Implement at least one hook. The \`homegraph\` field in package.json must
+declare \`{ "addon": true, "api": 1 }\`.
+
+## Local usage
+
+    homegraph addon install ./path/to/this/addon
+
+See \`examples/jira.mjs\` for enrich and \`examples/build-prompt.mjs\` for prompt assembly.
+`;
+/**
+ * Create the addon scaffold in `parentDir/<name>`. Returns the paths of the
+ * files created (absolute). Throws when the target directory already exists.
+ */
+function createAddonScaffold(name, parentDir, lang) {
+    const addonDir = path.join(parentDir, name);
+    if (fs.existsSync(addonDir)) {
+        throw new Error(`Directory already exists: ${addonDir}`);
+    }
+    const files = {
+        'package.json': packageJson(name, lang),
+        README: README,
+        'examples/jira.mjs': JIRA_EXAMPLE,
+        'examples/build-prompt.mjs': BUILD_PROMPT_EXAMPLE,
+    };
+    if (lang === 'ts') {
+        files['tsconfig.json'] = tsconfig();
+        files['index.ts'] = indexSource(name, lang);
+    }
+    else {
+        files['index.mjs'] = indexSource(name, lang);
+    }
+    const created = [];
+    for (const [rel, content] of Object.entries(files)) {
+        const filePath = path.join(addonDir, rel);
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, content, 'utf-8');
+        created.push(filePath);
+    }
+    return created;
+}
+//# sourceMappingURL=init-template.js.map

package/dist/addons/init-template.js.map

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

package/dist/addons/loader.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Runtime addon loading.
+ *
+ * Deterministic lookup, never a directory scan: read the registry
+ * (`addons.json`), then for each enabled entry resolve its install directory
+ * by name and validate + import it. Missing / invalid / disabled entries are
+ * skipped with a warning — a broken addon must never break the host flow.
+ *
+ * @module addons/loader
+ */
+import { LoadedAddon } from './types';
+/**
+ * Load all enabled, registered addons for a repository, in registry order.
+ * Registry order is the deterministic priority order for consumers that need
+ * one winner (e.g. `buildPrompt`).
+ */
+export declare function loadAddons(repoRoot: string): Promise<LoadedAddon[]>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/addons/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/addons/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtC;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAiCzE"}

package/dist/addons/loader.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Runtime addon loading.
+ *
+ * Deterministic lookup, never a directory scan: read the registry
+ * (`addons.json`), then for each enabled entry resolve its install directory
+ * by name and validate + import it. Missing / invalid / disabled entries are
+ * skipped with a warning — a broken addon must never break the host flow.
+ *
+ * @module addons/loader
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAddons = loadAddons;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const errors_1 = require("../errors");
+const registry_1 = require("./registry");
+const paths_1 = require("./paths");
+const validate_1 = require("./validate");
+/**
+ * Load all enabled, registered addons for a repository, in registry order.
+ * Registry order is the deterministic priority order for consumers that need
+ * one winner (e.g. `buildPrompt`).
+ */
+async function loadAddons(repoRoot) {
+    const registry = (0, registry_1.readRegistry)(repoRoot);
+    const out = [];
+    for (const entry of registry.addons) {
+        if (!entry.enabled)
+            continue;
+        const pkgDir = (0, paths_1.addonPkgDir)(repoRoot, entry.name);
+        if (!fs.existsSync(path.join(pkgDir, 'package.json'))) {
+            (0, errors_1.logWarn)(`Addon ${entry.name} is registered but not installed — skipping`, {
+                repoRoot,
+                name: entry.name,
+            });
+            continue;
+        }
+        const validation = await (0, validate_1.validateAddonPackage)(pkgDir);
+        if (!validation.ok) {
+            (0, errors_1.logWarn)(`Addon ${entry.name} failed validation — skipping`, {
+                name: entry.name,
+                reason: validation.reason,
+            });
+            continue;
+        }
+        out.push({
+            name: entry.name,
+            version: validation.version ?? entry.version,
+            module: validation.module,
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=loader.js.map

package/dist/addons/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/addons/loader.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAeH,gCAiCC;AA9CD,uCAAyB;AACzB,2CAA6B;AAC7B,sCAAoC;AACpC,yCAA0C;AAC1C,mCAAsC;AACtC,yCAAkD;AAGlD;;;;GAIG;AACI,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,MAAM,QAAQ,GAAG,IAAA,uBAAY,EAAC,QAAQ,CAAC,CAAC;IACxC,MAAM,GAAG,GAAkB,EAAE,CAAC;IAE9B,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QACpC,IAAI,CAAC,KAAK,CAAC,OAAO;YAAE,SAAS;QAE7B,MAAM,MAAM,GAAG,IAAA,mBAAW,EAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC;YACtD,IAAA,gBAAO,EAAC,SAAS,KAAK,CAAC,IAAI,6CAA6C,EAAE;gBACxE,QAAQ;gBACR,IAAI,EAAE,KAAK,CAAC,IAAI;aACjB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,MAAM,UAAU,GAAG,MAAM,IAAA,+BAAoB,EAAC,MAAM,CAAC,CAAC;QACtD,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC;YACnB,IAAA,gBAAO,EAAC,SAAS,KAAK,CAAC,IAAI,+BAA+B,EAAE;gBAC1D,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO;YAC5C,MAAM,EAAE,UAAU,CAAC,MAAO;SAC3B,CAAC,CAAC;IACL,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/addons/manager.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Addon install management (npm as the install engine).
+ *
+ * `npm install --prefix <addonsRoot>` handles all package mechanics —
+ * resolution, integrity, transitive dependencies, local paths, git URLs —
+ * so HomeGraph never reimplements package resolution. The registry records
+ * the concrete resolved version (never the requested range) to prevent
+ * silent drift.
+ *
+ * Version policy (v1 of the addon format):
+ * - **No silent downgrades.** Re-installing a name that is already
+ *   registered compares the target version against the installed one and
+ *   refuses anything older — the user must `remove` first.
+ * - **Upgrades preserve the previous version.** The installed package
+ *   directory is renamed aside to a rollback backup before npm runs; a
+ *   failed install/validation restores it, so a bad upgrade can never
+ *   leave the store without the previous working copy.
+ *
+ * Both policies apply to registry packages and local-path packages alike
+ * (a local-path "package" is a symlink npm manages; rename/restore is
+ * symmetric). The one carve-out is the name-resolution fallback path
+ * (git URLs etc., where the package name is only known *after* npm runs) —
+ * it cannot gate or back up in advance.
+ *
+ * @module addons/manager
+ */
+import { AddonRegistryEntry } from './types';
+/** Result of a successful install. */
+export interface InstallResult {
+    name: string;
+    version: string;
+}
+/** Options for `installAddon`. */
+export interface InstallOptions {
+    /** Whether the new entry starts enabled (default true). */
+    enable: boolean;
+    /** Pre-resolved package name (from `npm view`/local package.json). */
+    name?: string;
+}
+/** Package identity + install source, resolved from an install spec. */
+export interface PackageInfo {
+    name: string;
+    source: 'registry' | 'local';
+}
+/** Whether an install spec points at a local path (dir or tarball). */
+export declare function isLocalPathSpec(spec: string): boolean;
+/**
+ * Resolve the npm package name and install source for an install spec, or
+ * `null` when neither a local package.json nor `npm view` yields a name.
+ *
+ * - Local paths (`./x`, `../x`, absolute, `file:`) → read package.json.
+ * - Everything else (names, scoped names, ranges, dist-tags) → `npm view`.
+ */
+export declare function resolvePackageInfo(pkgSpec: string): PackageInfo | null;
+/** Package name only — compatibility shim over {@link resolvePackageInfo}. */
+export declare function resolvePackageName(pkgSpec: string): string | null;
+/**
+ * Install an addon package and register it.
+ *
+ * Throws on failure (npm error, invalid addon, unresolvable name, or a
+ * downgrade attempt against an installed version). The registry is written
+ * only after validation succeeds. When re-installing an existing name
+ * (upgrade), the previous files are preserved and restored on failure.
+ */
+export declare function installAddon(repoRoot: string, pkgSpec: string, options: InstallOptions): Promise<InstallResult>;
+/**
+ * Unregister an addon, optionally deleting its files. Returns `false` when
+ * the name was not registered.
+ */
+export declare function removeAddon(repoRoot: string, name: string, options: {
+    purge: boolean;
+}): boolean;
+/**
+ * List registered addons with their on-disk status (installed vs missing).
+ */
+export declare function listAddons(repoRoot: string): Array<AddonRegistryEntry & {
+    installed: boolean;
+}>;
+/** Options for `updateAddon`. */
+export interface UpdateOptions {
+    /**
+     * Force the newest published version (`<name>@latest`, the registry
+     * dist-tag) instead of the recorded range. Registry-package entries only —
+     * local-path entries have no dist-tag and are rejected.
+     */
+    latest?: boolean;
+}
+/** Result of updating a single addon (`from === to` means no change). */
+export interface UpdateResult {
+    name: string;
+    from: string;
+    to: string;
+}
+/** npm spec for an update: bare name follows the recorded range, `@latest` forces the dist-tag. */
+export declare function resolveUpdateSpec(name: string, latest: boolean): string;
+/**
+ * Update registered addon(s) to the latest version within the configured
+ * range (re-running `npm install` on the registered name, then recording the
+ * newly resolved version). Each update preserves the previous files and
+ * restores them on failure, so a bad upgrade never loses the working copy.
+ *
+ * Returns the names+versions that were updated; entries whose validation
+ * failed after install are logged and skipped (previous version kept).
+ */
+export declare function updateAddon(repoRoot: string, name?: string, options?: UpdateOptions): Promise<UpdateResult[]>;
+//# sourceMappingURL=manager.d.ts.map

package/dist/addons/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/addons/manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAWH,OAAO,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE7C,sCAAsC;AACtC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,MAAM,EAAE,OAAO,CAAC;IAChB,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAoCD,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC;CAC9B;AAED,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CA2BtE;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEjE;AAqID;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CA0ExB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAC1B,OAAO,CAcT;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,GACf,KAAK,CAAC,kBAAkB,GAAG;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,CAAC,CAQpD;AAED,iCAAiC;AACjC,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,mGAAmG;AACnG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAEvE;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,EAAE,CAAC,CA+CzB"}