forge-server 0.1.0

package/dist/knowledge/registry.js

@@ -0,0 +1,361 @@
+// RepoRegistry — manages repo registration, manifest reading, and git detection.
+//
+// Registration flow:
+//   1. Resolve the repo path (absolute)
+//   2. Read .forge/manifest.yaml — required; if absent, returns an error result
+//   3. Resolve git remote origin URL (best-effort; local-only repos work too)
+//   4. Compute a stable repo ID: SHA-256(remote URL) first 12 hex chars, or
+//      SHA-256(absolute path) if no remote
+//   5. Upsert the repo row in SQLite
+//   6. Check if knowledge YAML content hash changed (compare manifest_hash)
+//   7. If changed (or newly registered), trigger KnowledgeHydrator to re-sync
+//      all knowledge items into Qdrant's knowledge collection
+//   8. Return registration result
+//
+// The registry operates standalone (no pipeline project required). Used by
+// both the MCP registration tools and the CLI `forge register` command.
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { parse, stringify } from 'yaml';
+import { KnowledgeYamlStore } from './store.js';
+import { logger } from '../util/logger.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const FORGE_DIR_NAME = '.forge';
+const MANIFEST_FILE = 'manifest.yaml';
+const KNOWLEDGE_CATEGORY_FILES = [
+    'gotchas.yaml',
+    'patterns.yaml',
+    'decisions.yaml',
+    'conventions.yaml',
+];
+// ---------------------------------------------------------------------------
+// RepoRegistry
+// ---------------------------------------------------------------------------
+export class RepoRegistry {
+    db;
+    hydrator;
+    constructor(db, hydrator) {
+        this.db = db;
+        this.hydrator = hydrator;
+    }
+    // ---------------------------------------------------------------------------
+    // register — primary entry point (spec B5 signature)
+    // ---------------------------------------------------------------------------
+    /**
+     * Register (or update) a repo at `path`.
+     *
+     * Requires a .forge/manifest.yaml to exist at <path>/.forge/manifest.yaml.
+     * If the manifest is absent, throws an error describing the fix.
+     *
+     * Steps:
+     *   1. Read manifest from .forge/manifest.yaml
+     *   2. Resolve git origin URL
+     *   3. Generate repo_id from origin URL (or path hash if no remote)
+     *   4. Upsert into SQLite repos table
+     *   5. Compute knowledge content hash and compare with stored hash
+     *   6. If hash changed (or newly registered), hydrate Qdrant knowledge collection
+     *   7. Return RegisterResult
+     */
+    async register(path, options) {
+        const repoPath = resolve(path);
+        const forgePath = join(repoPath, FORGE_DIR_NAME);
+        const manifestPath = join(forgePath, MANIFEST_FILE);
+        // Manifest is required. Return a clear error if absent.
+        if (!existsSync(manifestPath)) {
+            throw new Error(`No .forge/manifest.yaml found at ${forgePath}. ` +
+                `Run \`forge init\` in the repo first, or call initForge() to create the directory structure.`);
+        }
+        const manifest = this.readManifest(forgePath);
+        if (!manifest) {
+            throw new Error(`Failed to parse .forge/manifest.yaml at ${forgePath}. ` +
+                `Check the file for syntax errors.`);
+        }
+        // Resolve git remote and generate repo ID.
+        const remote = this.resolveGitOrigin(repoPath);
+        const repoId = manifest.repo_id_override
+            ? manifest.repo_id_override
+            : this.generateRepoId(remote ?? repoPath);
+        const name = manifest.name;
+        const stack = manifest.stack;
+        const sharing = manifest.sharing;
+        const org = manifest.org ?? null;
+        const now = Date.now();
+        // Compute knowledge content hash for change detection.
+        const yamlStore = new KnowledgeYamlStore(forgePath);
+        const knowledgeHash = yamlStore.getContentHash();
+        // Check existing row.
+        const existing = this.db.get(`SELECT * FROM repos WHERE id = ?`, [repoId]);
+        const newlyRegistered = !existing;
+        const knowledgeChanged = !existing || existing.manifest_hash !== knowledgeHash;
+        if (existing) {
+            this.db.run(`UPDATE repos
+         SET name = ?, path = ?, remote = ?, stack = ?, sharing = ?,
+             org = ?, last_seen_at = ?, manifest_hash = ?
+         WHERE id = ?`, [
+                name, repoPath, remote ?? null, JSON.stringify(stack),
+                sharing, org, now, knowledgeHash, repoId,
+            ]);
+            logger.info('RepoRegistry.register: repo updated', { repoId, name });
+        }
+        else {
+            this.db.run(`INSERT INTO repos
+           (id, name, path, remote, stack, sharing, org, registered_at, last_seen_at, manifest_hash)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+                repoId, name, repoPath, remote ?? null, JSON.stringify(stack),
+                sharing, org, now, now, knowledgeHash,
+            ]);
+            logger.info('RepoRegistry.register: repo registered', { repoId, name });
+        }
+        // Hydrate Qdrant knowledge collection if content changed.
+        let knowledgeItemsLoaded = 0;
+        if (knowledgeChanged && this.hydrator) {
+            try {
+                knowledgeItemsLoaded = await this.hydrator.hydrate(repoId, sharing);
+                logger.info('RepoRegistry.register: knowledge hydrated', {
+                    repoId,
+                    itemCount: knowledgeItemsLoaded,
+                });
+            }
+            catch (err) {
+                // Hydration failure is non-fatal — registration proceeds.
+                logger.warn('RepoRegistry.register: knowledge hydration failed (non-fatal)', {
+                    repoId,
+                    error: String(err),
+                });
+            }
+        }
+        else if (!this.hydrator) {
+            logger.debug('RepoRegistry.register: no hydrator configured, skipping knowledge sync', {
+                repoId,
+            });
+        }
+        return {
+            repo_id: repoId,
+            name,
+            path: repoPath,
+            remote: remote ?? undefined,
+            stack,
+            sharing,
+            newly_registered: newlyRegistered,
+            knowledge_items_loaded: knowledgeItemsLoaded,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // initForge — create .forge/ directory structure (spec B5 method)
+    // ---------------------------------------------------------------------------
+    /**
+     * Initialize the .forge/ directory in a repo at `repoPath`.
+     * Creates:
+     *   .forge/manifest.yaml          — from provided manifest
+     *   .forge/knowledge/gotchas.yaml
+     *   .forge/knowledge/patterns.yaml
+     *   .forge/knowledge/decisions.yaml
+     *   .forge/knowledge/conventions.yaml
+     *   .forge/.gitignore             — excludes .forge.db
+     *
+     * All files are created only if they do not already exist.
+     * Returns { forgePath, filesCreated } listing the paths that were created.
+     */
+    initForge(repoPath, manifest) {
+        const absRepoPath = resolve(repoPath);
+        const forgePath = join(absRepoPath, FORGE_DIR_NAME);
+        const knowledgeDir = join(forgePath, 'knowledge');
+        const filesCreated = [];
+        // Create .forge/ directory
+        if (!existsSync(forgePath)) {
+            mkdirSync(forgePath, { recursive: true });
+            filesCreated.push(forgePath);
+        }
+        // Create .forge/knowledge/ subdirectory
+        if (!existsSync(knowledgeDir)) {
+            mkdirSync(knowledgeDir, { recursive: true });
+            filesCreated.push(knowledgeDir);
+        }
+        // Write manifest.yaml
+        const manifestPath = join(forgePath, MANIFEST_FILE);
+        if (!existsSync(manifestPath)) {
+            const yamlContent = stringify(manifest, { indent: 2 });
+            writeFileSync(manifestPath, yamlContent, 'utf8');
+            filesCreated.push(manifestPath);
+        }
+        // Create empty YAML category files
+        for (const file of KNOWLEDGE_CATEGORY_FILES) {
+            const filePath = join(knowledgeDir, file);
+            if (!existsSync(filePath)) {
+                writeFileSync(filePath, '[]\n', 'utf8');
+                filesCreated.push(filePath);
+            }
+        }
+        // Create .gitignore to exclude local SQLite database
+        const gitignorePath = join(forgePath, '.gitignore');
+        if (!existsSync(gitignorePath)) {
+            writeFileSync(gitignorePath, '.forge.db\n', 'utf8');
+            filesCreated.push(gitignorePath);
+        }
+        logger.info('RepoRegistry.initForge: .forge/ directory initialized', {
+            forgePath,
+            filesCreated: filesCreated.length,
+        });
+        return { forgePath, filesCreated };
+    }
+    // ---------------------------------------------------------------------------
+    // Manifest reading (spec B5 signature: takes forgePath, not repoPath)
+    // ---------------------------------------------------------------------------
+    /**
+     * Read and parse .forge/manifest.yaml from `forgePath` (the .forge/ directory).
+     * Returns null if the file is absent or unparseable.
+     *
+     * NOTE: This method takes the .forge/ directory path, NOT the repo root.
+     * Callers that have the repo root should pass join(repoPath, '.forge').
+     */
+    readManifest(forgePath) {
+        const manifestPath = join(forgePath, MANIFEST_FILE);
+        if (!existsSync(manifestPath))
+            return null;
+        return this._parseManifestFile(manifestPath);
+    }
+    // ---------------------------------------------------------------------------
+    // Git origin resolution (public — spec B5)
+    // ---------------------------------------------------------------------------
+    /**
+     * Resolve the git remote origin URL for the repo at `repoPath`.
+     * Uses `git -C <repoPath> config --get remote.origin.url`.
+     * Returns null if the path is not a git repo or has no origin.
+     */
+    resolveGitOrigin(repoPath) {
+        try {
+            const output = execFileSync('git', ['-C', repoPath, 'config', '--get', 'remote.origin.url'], {
+                encoding: 'utf-8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+                timeout: 3000,
+            }).trim();
+            return output || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Repo ID generation (public — spec B5)
+    // ---------------------------------------------------------------------------
+    /**
+     * Generate a stable repo ID from a remote URL or local path.
+     * Uses SHA-256, returns first 12 hex characters.
+     *
+     * For remote URLs: normalises to strip .git suffix and trailing slashes
+     * before hashing so that git@github.com:org/repo and
+     * https://github.com/org/repo.git produce the same ID.
+     */
+    generateRepoId(remoteOrPath) {
+        const normalised = remoteOrPath
+            .trim()
+            .replace(/\.git$/, '')
+            .replace(/\/$/, '')
+            .toLowerCase();
+        return createHash('sha256').update(normalised).digest('hex').slice(0, 12);
+    }
+    // ---------------------------------------------------------------------------
+    // Query helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Get a registered repo by ID.
+     * Returns null if not found.
+     */
+    getRepo(repoId) {
+        const row = this.db.get(`SELECT * FROM repos WHERE id = ?`, [repoId]);
+        return row ? this._rowToRepo(row) : null;
+    }
+    /**
+     * List all registered repos sorted by last_seen_at descending.
+     * Returns repos augmented with knowledge_count (total items in Qdrant).
+     * knowledge_count is always 0 when Qdrant is not available — it is a
+     * best-effort annotation, not a blocking query.
+     */
+    listRepos() {
+        const rows = this.db.all(`SELECT * FROM repos ORDER BY last_seen_at DESC`);
+        return rows.map((row) => ({
+            ...this._rowToRepo(row),
+            // knowledge_count: Qdrant query is async; this is a synchronous method.
+            // Return 0 — callers that need counts should call vectorStore.getKnowledgeCount()
+            // separately or use async listReposWithCounts() if added later.
+            knowledge_count: 0,
+        }));
+    }
+    /**
+     * Update the last_seen_at timestamp for a repo.
+     * Called on session-start to record that the repo is actively being used.
+     */
+    touch(repoId) {
+        this.db.run(`UPDATE repos SET last_seen_at = ? WHERE id = ?`, [Date.now(), repoId]);
+    }
+    /**
+     * Remove a repo from the registry.
+     * Does NOT remove Qdrant knowledge items — call hydrator.removeRepo() separately
+     * if you want to clean up vector data.
+     */
+    removeRepo(repoId) {
+        this.db.run(`DELETE FROM repos WHERE id = ?`, [repoId]);
+        logger.info('RepoRegistry.removeRepo: repo removed from SQLite', { repoId });
+    }
+    // ---------------------------------------------------------------------------
+    // Backward-compat helpers (camelCase API — kept for existing callers)
+    // ---------------------------------------------------------------------------
+    /** Whether a .forge/ directory exists in the given repo path. */
+    forgeDirectoryExists(repoPath) {
+        const targetPath = resolve(repoPath ?? process.cwd());
+        return existsSync(join(targetPath, FORGE_DIR_NAME));
+    }
+    /** Find a registered repo by its filesystem path. */
+    findRepoByPath(repoPath) {
+        const absPath = resolve(repoPath);
+        const row = this.db.get(`SELECT * FROM repos WHERE path = ?`, [absPath]);
+        return row ? this._rowToRepo(row) : null;
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    _parseManifestFile(manifestPath) {
+        try {
+            const content = readFileSync(manifestPath, 'utf8');
+            const parsed = parse(content);
+            return parsed ?? null;
+        }
+        catch (err) {
+            logger.warn('RepoRegistry._parseManifestFile: failed to read manifest', {
+                path: manifestPath,
+                error: String(err),
+            });
+            return null;
+        }
+    }
+    _repoNameFromPath(repoPath) {
+        // basename handles both forward and backslash separators via path.basename
+        return basename(repoPath) || 'unknown';
+    }
+    _rowToRepo(row) {
+        let stack;
+        try {
+            stack = JSON.parse(row.stack);
+        }
+        catch {
+            stack = [];
+        }
+        return {
+            id: row.id,
+            name: row.name,
+            path: row.path,
+            remote: row.remote,
+            stack,
+            sharing: row.sharing,
+            org: row.org,
+            registeredAt: row.registered_at,
+            lastSeenAt: row.last_seen_at,
+            manifestHash: row.manifest_hash,
+        };
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/knowledge/registry.js.map

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

package/dist/knowledge/search.d.ts

@@ -0,0 +1,114 @@
+import type { QdrantVectorStore } from '../storage/qdrant-store.js';
+import type { KnowledgeCategory, KnowledgeItem } from '../util/types.js';
+/**
+ * Result shape returned from KnowledgeSearch.search().
+ * Uses snake_case field names to match the MCP tool response contract.
+ */
+export interface KnowledgeSearchResult {
+    id: string;
+    category: string;
+    title: string;
+    content: string;
+    confidence: number;
+    stack_tags: string[];
+    source_repo: string;
+    relevance_score: number;
+}
+export interface KnowledgeSearchOptions {
+    repoId?: string;
+    category?: KnowledgeCategory;
+    stackTags?: string[];
+    minConfidence?: number;
+    limit?: number;
+    scoreThreshold?: number;
+}
+export declare class KnowledgeSearch {
+    private readonly vectorStore;
+    constructor(vectorStore: QdrantVectorStore);
+    /**
+     * Semantic search across knowledge items stored in the Qdrant knowledge
+     * collection.
+     *
+     * Options:
+     *   category          — filter to a single KnowledgeCategory
+     *   stack_tags        — filter to items that share at least one tag (OR match)
+     *   repo_id           — used for same-repo scoring boost; also hard-filters
+     *                       when include_cross_repo is false
+     *   limit             — max results to return (default 10)
+     *   include_cross_repo— include items from other repos (default true)
+     *   min_confidence    — minimum confidence score (default 0.3)
+     *
+     * Returns results sorted descending by relevance_score.
+     * Returns [] when Qdrant is unavailable — never throws.
+     */
+    search(query: string, options?: {
+        category?: KnowledgeCategory;
+        stack_tags?: string[];
+        repo_id?: string;
+        limit?: number;
+        include_cross_repo?: boolean;
+        min_confidence?: number;
+    }): Promise<KnowledgeSearchResult[]>;
+    /**
+     * Increment access_count and update accessed_at for a knowledge item.
+     * Optionally bumps the confidence score by boostAmount.
+     *
+     * Called when an agent actively consumes a knowledge item — access signals
+     * genuine utility and nudges confidence upward.
+     * Silent on Qdrant failure (non-fatal side effect).
+     */
+    boostConfidence(knowledgeId: string, boostAmount?: number): Promise<void>;
+    /**
+     * Return gotcha items optionally filtered by stack tags.
+     * Uses Qdrant filter (category=gotcha) plus optional stack_tags OR match.
+     * Results sorted by confidence descending.
+     * Gracefully returns [] on Qdrant unavailability.
+     */
+    getGotchas(stack?: string[], limit?: number, minConfidence?: number): Promise<KnowledgeItem[]>;
+    /**
+     * Return pattern items optionally filtered by domain.
+     * `domain` is treated as a stack tag (single-element array) for consistency.
+     * Results sorted by confidence descending.
+     * Gracefully returns [] on Qdrant unavailability.
+     */
+    getPatterns(domain?: string, limit?: number, minConfidence?: number): Promise<KnowledgeItem[]>;
+    /** Convenience: search with category=gotcha. Backward-compat camelCase API. */
+    searchGotchas(query: string, opts?: Omit<KnowledgeSearchOptions, 'category'>): Promise<KnowledgeSearchResult[]>;
+    /** Convenience: search with category=decision. Backward-compat camelCase API. */
+    searchDecisions(query: string, opts?: Omit<KnowledgeSearchOptions, 'category'>): Promise<KnowledgeSearchResult[]>;
+    /** Convenience: search with category=pattern. Backward-compat camelCase API. */
+    searchPatterns(query: string, opts?: Omit<KnowledgeSearchOptions, 'category'>): Promise<KnowledgeSearchResult[]>;
+    /** Convenience: search with category=convention. Backward-compat camelCase API. */
+    searchConventions(query: string, opts?: Omit<KnowledgeSearchOptions, 'category'>): Promise<KnowledgeSearchResult[]>;
+    /** True when the vector store is configured and healthy. */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Retrieve knowledge items by category using Qdrant filter scroll (no
+     * semantic query). Falls back to semantic search when filterKnowledge is
+     * not yet available on the store.
+     */
+    private _getByCategory;
+    /**
+     * Build the Qdrant filter object from search option components.
+     *
+     * We construct the full Qdrant filter shape directly here (not relying on
+     * QdrantVectorStore.buildFilter) because we need both "must" (AND) and
+     * "should" (OR) conditions which the simple flat-map builder cannot express.
+     *
+     * Qdrant filter reference:
+     *   { must: [...], should: [...], must_not: [...] }
+     *   Each condition: { key: string, match: { value } } or { key, range: { gte } }
+     */
+    private _buildQdrantFilter;
+    /**
+     * Convert a KnowledgePayload from Qdrant into a KnowledgeItem.
+     * Returns null if required fields are missing.
+     */
+    private _payloadToKnowledgeItem;
+    /**
+     * Convert a KnowledgeSearchResult back to a KnowledgeItem shape.
+     * Used as a fallback when filterKnowledge is not available on the store.
+     */
+    private _resultToKnowledgeItem;
+}
+//# sourceMappingURL=search.d.ts.map

package/dist/knowledge/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/knowledge/search.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAoB,MAAM,kBAAkB,CAAC;AAM3F;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAID,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAaD,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAAX,WAAW,EAAE,iBAAiB;IAM3D;;;;;;;;;;;;;;;OAeG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,iBAAiB,CAAC;QAC7B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,GACA,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAgHnC;;;;;;;OAOG;IACG,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAyD7E;;;;;OAKG;IACG,UAAU,CACd,KAAK,CAAC,EAAE,MAAM,EAAE,EAChB,KAAK,SAAK,EACV,aAAa,SAAM,GAClB,OAAO,CAAC,aAAa,EAAE,CAAC;IAI3B;;;;;OAKG;IACG,WAAW,CACf,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,SAAK,EACV,aAAa,SAAM,GAClB,OAAO,CAAC,aAAa,EAAE,CAAC;IAS3B,+EAA+E;IACzE,aAAa,CACjB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,UAAU,CAAC,GAC9C,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAUnC,iFAAiF;IAC3E,eAAe,CACnB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,UAAU,CAAC,GAC9C,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAUnC,gFAAgF;IAC1E,cAAc,CAClB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,UAAU,CAAC,GAC9C,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAUnC,mFAAmF;IAC7E,iBAAiB,CACrB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,UAAU,CAAC,GAC9C,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAUnC,4DAA4D;IACtD,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAQrC;;;;OAIG;YACW,cAAc;IA6D5B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,kBAAkB;IAsE1B;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAoB/B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;CAc/B"}