@fractary/core 0.3.3 → 0.5.0

package/dist/config/loader.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @fractary/core - Unified Configuration Loader
+ *
+ * Builds on yaml-config.ts to provide a unified configuration object
+ * with integrated authentication support.
+ */
+import { CoreYamlConfig, ConfigLoadOptions, WorkConfig, RepoConfig, LogsConfig, FileConfig, SpecConfig, DocsConfig, CodexConfig } from '../common/yaml-config';
+import type { TokenProvider, GitHubAppConfig } from '../auth/types';
+/**
+ * Load environment variables from .env files
+ *
+ * This function explicitly loads .env files - it must be called manually
+ * rather than being a side effect of importing the module.
+ *
+ * Searches for .env files in the following order:
+ * 1. Current working directory
+ * 2. Project root (directory containing .fractary or .git)
+ *
+ * @param options Loading options
+ * @returns true if .env was loaded, false if no .env file found
+ *
+ * @example
+ * ```typescript
+ * import { loadEnv, loadConfig } from '@fractary/core';
+ *
+ * // Explicitly load .env before loading config
+ * loadEnv();
+ * const config = await loadConfig();
+ * ```
+ */
+export declare function loadEnv(options?: {
+    cwd?: string;
+    force?: boolean;
+}): boolean;
+/**
+ * Check if environment variables have been loaded
+ *
+ * @returns true if loadEnv() has been called successfully
+ */
+export declare function isEnvLoaded(): boolean;
+/**
+ * GitHub configuration extracted from yaml config
+ */
+export interface ExtractedGitHubConfig {
+    /** Personal access token (from handlers.github.token or environment) */
+    token?: string;
+    /** GitHub organization name */
+    organization?: string;
+    /** GitHub project (owner/repo format) */
+    project?: string;
+    /** GitHub App configuration */
+    app?: GitHubAppConfig;
+}
+/**
+ * Loaded configuration with authentication
+ *
+ * Extends the raw YAML configuration with computed authentication.
+ */
+export interface LoadedConfig {
+    /** Raw configuration version */
+    version: string;
+    /** GitHub configuration extracted from work/repo handlers */
+    github?: ExtractedGitHubConfig;
+    /** Token provider for GitHub authentication (if configured) */
+    tokenProvider?: TokenProvider;
+    /** Work tracking configuration */
+    work?: WorkConfig;
+    /** Repository management configuration */
+    repo?: RepoConfig;
+    /** Logs management configuration */
+    logs?: LogsConfig;
+    /** File storage configuration */
+    file?: FileConfig;
+    /** Specification management configuration */
+    spec?: SpecConfig;
+    /** Documentation management configuration */
+    docs?: DocsConfig;
+    /** Codex configuration */
+    codex?: CodexConfig;
+    /** Raw configuration (for advanced use cases) */
+    raw: CoreYamlConfig;
+}
+/**
+ * Configuration loader options
+ */
+export interface LoadConfigOptions extends ConfigLoadOptions {
+    /** Skip creating token provider (useful for non-GitHub operations) */
+    skipAuth?: boolean;
+}
+/**
+ * Load unified configuration with authentication
+ *
+ * This function:
+ * 1. Loads and parses the YAML configuration
+ * 2. Extracts GitHub configuration from handlers
+ * 3. Creates a TokenProvider for authentication (if configured)
+ * 4. Returns a unified config object
+ *
+ * Note: dotenv should be imported at the entry point, so environment
+ * variables are already loaded when this function is called.
+ *
+ * @param options Configuration loading options
+ * @returns Loaded configuration with authentication
+ *
+ * @example
+ * ```typescript
+ * const config = await loadConfig();
+ *
+ * if (config.tokenProvider) {
+ *   const token = await config.tokenProvider.getToken();
+ *   // Use token for API calls
+ * }
+ * ```
+ */
+export declare function loadConfig(options?: LoadConfigOptions): Promise<LoadedConfig>;
+/**
+ * Load configuration synchronously (without token provider)
+ *
+ * Useful for cases where you only need the configuration data
+ * without authentication.
+ *
+ * @param options Configuration loading options
+ * @returns Loaded configuration without token provider
+ */
+export declare function loadConfigSync(options?: ConfigLoadOptions): Omit<LoadedConfig, 'tokenProvider'>;
+//# sourceMappingURL=loader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAEL,cAAc,EACd,iBAAiB,EACjB,UAAU,EACV,UAAU,EACV,UAAU,EACV,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACZ,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAgB,eAAe,EAAE,MAAM,eAAe,CAAC;AAOlF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,OAAO,CAAC,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CA8BhF;AAED;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,GAAG,CAAC,EAAE,eAAe,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAEhB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAE/B,+DAA+D;IAC/D,aAAa,CAAC,EAAE,aAAa,CAAC;IAE9B,kCAAkC;IAClC,IAAI,CAAC,EAAE,UAAU,CAAC;IAElB,0CAA0C;IAC1C,IAAI,CAAC,EAAE,UAAU,CAAC;IAElB,oCAAoC;IACpC,IAAI,CAAC,EAAE,UAAU,CAAC;IAElB,iCAAiC;IACjC,IAAI,CAAC,EAAE,UAAU,CAAC;IAElB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,UAAU,CAAC;IAElB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,UAAU,CAAC;IAElB,0BAA0B;IAC1B,KAAK,CAAC,EAAE,WAAW,CAAC;IAEpB,iDAAiD;IACjD,GAAG,EAAE,cAAc,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,sEAAsE;IACtE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAqED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,YAAY,CAAC,CA+CvF;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,iBAAsB,GAAG,IAAI,CAAC,YAAY,EAAE,eAAe,CAAC,CAwBnG"}

package/dist/config/loader.js

@@ -0,0 +1,277 @@
+"use strict";
+/**
+ * @fractary/core - Unified Configuration Loader
+ *
+ * Builds on yaml-config.ts to provide a unified configuration object
+ * with integrated authentication support.
+ */
+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.loadEnv = loadEnv;
+exports.isEnvLoaded = isEnvLoaded;
+exports.loadConfig = loadConfig;
+exports.loadConfigSync = loadConfigSync;
+const dotenv = __importStar(require("dotenv"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const yaml_config_1 = require("../common/yaml-config");
+const auth_1 = require("../auth");
+const yaml_config_2 = require("../common/yaml-config");
+/** Track whether loadEnv has been called */
+let envLoaded = false;
+/**
+ * Load environment variables from .env files
+ *
+ * This function explicitly loads .env files - it must be called manually
+ * rather than being a side effect of importing the module.
+ *
+ * Searches for .env files in the following order:
+ * 1. Current working directory
+ * 2. Project root (directory containing .fractary or .git)
+ *
+ * @param options Loading options
+ * @returns true if .env was loaded, false if no .env file found
+ *
+ * @example
+ * ```typescript
+ * import { loadEnv, loadConfig } from '@fractary/core';
+ *
+ * // Explicitly load .env before loading config
+ * loadEnv();
+ * const config = await loadConfig();
+ * ```
+ */
+function loadEnv(options = {}) {
+    const { cwd = process.cwd(), force = false } = options;
+    // Skip if already loaded (unless force is true)
+    if (envLoaded && !force) {
+        return true;
+    }
+    // Try loading from current working directory first
+    const cwdEnvPath = path.join(cwd, '.env');
+    if (fs.existsSync(cwdEnvPath)) {
+        dotenv.config({ path: cwdEnvPath });
+        envLoaded = true;
+        return true;
+    }
+    // Try loading from project root
+    try {
+        const projectRoot = (0, yaml_config_2.findProjectRoot)(cwd);
+        const rootEnvPath = path.join(projectRoot, '.env');
+        if (fs.existsSync(rootEnvPath)) {
+            dotenv.config({ path: rootEnvPath });
+            envLoaded = true;
+            return true;
+        }
+    }
+    catch {
+        // findProjectRoot failed - that's okay
+    }
+    return false;
+}
+/**
+ * Check if environment variables have been loaded
+ *
+ * @returns true if loadEnv() has been called successfully
+ */
+function isEnvLoaded() {
+    return envLoaded;
+}
+/**
+ * Extract GitHub configuration from yaml config
+ *
+ * Looks for GitHub configuration in:
+ * 1. work.handlers.github
+ * 2. repo.handlers.github
+ *
+ * @param config Raw yaml configuration
+ * @returns Extracted GitHub configuration or undefined
+ */
+function extractGitHubConfig(config) {
+    // Try work handlers first
+    const workGithub = config.work?.handlers?.github;
+    const repoGithub = config.repo?.handlers?.github;
+    // Merge configurations (work takes priority for auth, repo for project info)
+    const github = {};
+    let hasConfig = false;
+    // Extract token
+    if (workGithub?.token) {
+        github.token = workGithub.token;
+        hasConfig = true;
+    }
+    else if (repoGithub?.token) {
+        github.token = repoGithub.token;
+        hasConfig = true;
+    }
+    // Extract organization
+    if (workGithub?.organization) {
+        github.organization = workGithub.organization;
+        hasConfig = true;
+    }
+    else if (repoGithub?.organization) {
+        github.organization = repoGithub.organization;
+        hasConfig = true;
+    }
+    // Extract project (owner/repo)
+    if (workGithub?.project) {
+        github.project = workGithub.project;
+        hasConfig = true;
+    }
+    else if (repoGithub?.project) {
+        github.project = repoGithub.project;
+        hasConfig = true;
+    }
+    else if (workGithub?.owner && workGithub?.repo) {
+        github.project = `${workGithub.owner}/${workGithub.repo}`;
+        hasConfig = true;
+    }
+    else if (repoGithub?.owner && repoGithub?.repo) {
+        github.project = `${repoGithub.owner}/${repoGithub.repo}`;
+        hasConfig = true;
+    }
+    // Extract GitHub App config
+    const appConfig = workGithub?.app || repoGithub?.app;
+    if (appConfig?.id && appConfig?.installation_id) {
+        github.app = {
+            id: String(appConfig.id),
+            installation_id: String(appConfig.installation_id),
+            private_key_path: appConfig.private_key_path,
+            private_key_env_var: appConfig.private_key_env_var,
+        };
+        hasConfig = true;
+    }
+    return hasConfig ? github : undefined;
+}
+/**
+ * Load unified configuration with authentication
+ *
+ * This function:
+ * 1. Loads and parses the YAML configuration
+ * 2. Extracts GitHub configuration from handlers
+ * 3. Creates a TokenProvider for authentication (if configured)
+ * 4. Returns a unified config object
+ *
+ * Note: dotenv should be imported at the entry point, so environment
+ * variables are already loaded when this function is called.
+ *
+ * @param options Configuration loading options
+ * @returns Loaded configuration with authentication
+ *
+ * @example
+ * ```typescript
+ * const config = await loadConfig();
+ *
+ * if (config.tokenProvider) {
+ *   const token = await config.tokenProvider.getToken();
+ *   // Use token for API calls
+ * }
+ * ```
+ */
+async function loadConfig(options = {}) {
+    const { skipAuth = false, ...yamlOptions } = options;
+    // Load raw YAML configuration
+    const raw = (0, yaml_config_1.loadYamlConfig)(yamlOptions);
+    // Handle case where config file doesn't exist
+    if (!raw) {
+        return {
+            version: '0.0.0',
+            raw: { version: '0.0.0' },
+        };
+    }
+    // Extract GitHub configuration
+    const github = extractGitHubConfig(raw);
+    // Create token provider (unless skipped)
+    let tokenProvider;
+    if (!skipAuth && github) {
+        try {
+            const githubConfig = {
+                token: github.token,
+                organization: github.organization,
+                project: github.project,
+                app: github.app,
+            };
+            tokenProvider = (0, auth_1.createTokenProvider)(githubConfig);
+        }
+        catch {
+            // Token provider creation failed - that's okay, it's optional
+            // The user might not have configured authentication yet
+        }
+    }
+    return {
+        version: raw.version || '0.0.0',
+        github,
+        tokenProvider,
+        work: raw.work,
+        repo: raw.repo,
+        logs: raw.logs,
+        file: raw.file,
+        spec: raw.spec,
+        docs: raw.docs,
+        codex: raw.codex,
+        raw,
+    };
+}
+/**
+ * Load configuration synchronously (without token provider)
+ *
+ * Useful for cases where you only need the configuration data
+ * without authentication.
+ *
+ * @param options Configuration loading options
+ * @returns Loaded configuration without token provider
+ */
+function loadConfigSync(options = {}) {
+    const raw = (0, yaml_config_1.loadYamlConfig)(options);
+    if (!raw) {
+        return {
+            version: '0.0.0',
+            raw: { version: '0.0.0' },
+        };
+    }
+    const github = extractGitHubConfig(raw);
+    return {
+        version: raw.version || '0.0.0',
+        github,
+        work: raw.work,
+        repo: raw.repo,
+        logs: raw.logs,
+        file: raw.file,
+        spec: raw.spec,
+        docs: raw.docs,
+        codex: raw.codex,
+        raw,
+    };
+}
+//# sourceMappingURL=loader.js.map

package/dist/config/loader.js.map

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

package/dist/docs/index.d.ts

@@ -2,7 +2,12 @@
  * @fractary/core - Docs Module
  *
  * Documentation management and organization.
+ *
+ * Doc types are now stored as YAML/Markdown files in the doc-types/ directory
+ * at the repository root. Use DocTypeRegistry to load and access them.
  */
 export { DocsManager } from './manager';
+export { DocTypeRegistry } from './type-registry';
+export type { CustomDocTypeConfig, DocTypeRegistryConfig } from './type-registry';
 export * from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/docs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docs/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAClF,cAAc,SAAS,CAAC"}

package/dist/docs/index.js

@@ -3,6 +3,9 @@
  * @fractary/core - Docs Module
  *
  * Documentation management and organization.
+ *
+ * Doc types are now stored as YAML/Markdown files in the doc-types/ directory
+ * at the repository root. Use DocTypeRegistry to load and access them.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -19,8 +22,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DocsManager = void 0;
+exports.DocTypeRegistry = exports.DocsManager = void 0;
 var manager_1 = require("./manager");
 Object.defineProperty(exports, "DocsManager", { enumerable: true, get: function () { return manager_1.DocsManager; } });
+var type_registry_1 = require("./type-registry");
+Object.defineProperty(exports, "DocTypeRegistry", { enumerable: true, get: function () { return type_registry_1.DocTypeRegistry; } });
 __exportStar(require("./types"), exports);
 //# sourceMappingURL=index.js.map

package/dist/docs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/docs/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;;;;;;;;;;;;;;AAEH,qCAAwC;AAA/B,sGAAA,WAAW,OAAA;AACpB,0CAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/docs/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;;;;;;;;;;;;;;;AAEH,qCAAwC;AAA/B,sGAAA,WAAW,OAAA;AACpB,iDAAkD;AAAzC,gHAAA,eAAe,OAAA;AAExB,0CAAwB"}

package/dist/docs/manager.d.ts

@@ -10,25 +10,52 @@ import { Doc, DocFormat, DocMetadata, DocSearchQuery, DocsManagerConfig } from '
 export declare class DocsManager {
     private docsDir;
     private defaultFormat;
+    private metadataMode;
     constructor(config: DocsManagerConfig);
     private ensureDir;
     private getDocPath;
     private getMetadataPath;
     private getFileExtension;
+    /**
+     * Determine the effective metadata mode for a document format
+     * Frontmatter only makes sense for markdown files
+     */
+    private getEffectiveMetadataMode;
+    /**
+     * Parse frontmatter from markdown content
+     */
+    private parseFrontmatter;
+    /**
+     * Write frontmatter to markdown content
+     */
+    private writeFrontmatter;
+    /**
+     * Extract body content from content that may have frontmatter
+     */
+    private extractBody;
     /**
      * Create a new document
+     * @param id - Document identifier
+     * @param content - Document body content (without frontmatter)
+     * @param metadata - Document metadata
+     * @param format - Document format (default: markdown)
      */
     createDoc(id: string, content: string, metadata: DocMetadata, format?: DocFormat): Promise<Doc>;
     /**
      * Get a document by ID
+     * Supports both frontmatter and sidecar metadata modes
      */
     getDoc(id: string): Promise<Doc | null>;
     /**
      * Update a document
+     * @param id - Document identifier
+     * @param content - New body content (without frontmatter)
+     * @param metadata - Metadata fields to update (merged with existing)
      */
     updateDoc(id: string, content: string, metadata?: Partial<DocMetadata>): Promise<Doc | null>;
     /**
      * Delete a document
+     * Removes both the document file and any sidecar metadata file if it exists
      */
     deleteDoc(id: string): Promise<boolean>;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/docs/manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EACL,GAAG,EACH,SAAS,EACT,WAAW,EACX,cAAc,EACd,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAY;gBAErB,MAAM,EAAE,iBAAiB;IAMrC,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,gBAAgB;IAUxB;;OAEG;IACG,SAAS,CACb,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,WAAW,EACrB,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,GAAG,CAAC;IA2Bf;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IA6B7C;;OAEG;IACG,SAAS,CACb,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC9B,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IA2BtB;;OAEG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAoB7C;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IA4BhC;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAsDvD;;OAEG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAI9C"}
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/docs/manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EACL,GAAG,EACH,SAAS,EACT,WAAW,EACX,cAAc,EACd,iBAAiB,EAElB,MAAM,SAAS,CAAC;AAUjB;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAY;IACjC,OAAO,CAAC,YAAY,CAAe;gBAEvB,MAAM,EAAE,iBAAiB;IAOrC,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,gBAAgB;IAUxB;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAOhC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAiDxB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAuCxB;;OAEG;IACH,OAAO,CAAC,WAAW;IAKnB;;;;;;OAMG;IACG,SAAS,CACb,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,WAAW,EACrB,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,GAAG,CAAC;IAmCf;;;OAGG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAwC7C;;;;;OAKG;IACG,SAAS,CACb,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC9B,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAsCtB;;;OAGG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqB7C;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IA4BhC;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IA2DvD;;OAEG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAI9C"}