@ashlr/hub 2.2.0

package/dist/core/plugins/registry.js

@@ -0,0 +1,415 @@
+/**
+ * core/plugins/registry.ts — M33 plugin discovery, load, and accessors.
+ *
+ * CONTRACT RULES (non-negotiable):
+ *  - discoverPlugins NEVER imports plugin code. It only reads manifest.json.
+ *  - loadEnabledPlugins gate chain (in order):
+ *      1. ASHLR_NO_PLUGINS=1 → return [] immediately.
+ *      2. killSwitchOn() → return [] + audit 'plugin:load' refused.
+ *      3. Only names in cfg.plugins?.enabled ?? [] (default empty → load NOTHING).
+ *      4. Manifest valid + apiVersion compatible (via readManifest).
+ *      5. verifyIntegrity passes.
+ *      6. await import(pathToFileURL(entry).href) in try/catch.
+ *      7. activate(host) raced against timeout.
+ *      8. Capability filter: drop contributions whose kind is not declared.
+ *  - A failing plugin is skipped (audited), NEVER fatal.
+ *  - Module-level memo cache: one load per process.
+ *  - homedir() re-resolved at call time for test HOME relocation.
+ *
+ * ZERO RUNTIME DEPS: only Node builtins + local imports.
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve as resolvePath } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { audit } from '../sandbox/audit.js';
+import { killSwitchOn } from '../sandbox/policy.js';
+import { readManifest } from './manifest.js';
+import { verifyIntegrity } from './integrity.js';
+import { buildHostApi } from './host-api.js';
+import { wrapScanner, validateTemplate, wrapCommand } from './wrappers.js';
+// ---------------------------------------------------------------------------
+// Timeout control (exported for tests via _setActivateTimeoutForTest)
+// ---------------------------------------------------------------------------
+/** Default activate() timeout in milliseconds. */
+const DEFAULT_ACTIVATE_TIMEOUT_MS = 5000;
+/** Current activate timeout; overridable for tests. */
+let _activateTimeoutMs = DEFAULT_ACTIVATE_TIMEOUT_MS;
+/**
+ * Override the activate() timeout for tests. Pass undefined to reset to default.
+ * Named with underscore prefix per house test-seam convention.
+ */
+export function _setActivateTimeoutForTest(ms) {
+    _activateTimeoutMs = ms !== undefined ? ms : DEFAULT_ACTIVATE_TIMEOUT_MS;
+}
+// ---------------------------------------------------------------------------
+// Module-level cache (one load per process)
+// ---------------------------------------------------------------------------
+/** Memoised result of loadEnabledPlugins, keyed on JSON-sorted enabled names. */
+let _cache = null;
+/**
+ * Reset the plugin cache. For tests only — allows re-loading after config changes.
+ * Named with underscore prefix per house test-seam convention.
+ */
+export function _resetPluginCacheForTest() {
+    _cache = null;
+}
+// ---------------------------------------------------------------------------
+// discoverPlugins — list ~/.ashlr/plugins/*/, read manifests
+// ---------------------------------------------------------------------------
+/**
+ * Discover all plugin directories under ~/.ashlr/plugins/.
+ * For each subdirectory, attempts to read and validate manifest.json.
+ *
+ * NEVER imports plugin code — manifest read only.
+ * NEVER throws.
+ *
+ * homedir() is resolved at call time so tests can relocate HOME.
+ */
+export function discoverPlugins() {
+    try {
+        const pluginsDir = join(homedir(), '.ashlr', 'plugins');
+        let entries;
+        try {
+            entries = readdirSync(pluginsDir);
+        }
+        catch {
+            // Plugins dir absent — no plugins discovered.
+            return [];
+        }
+        const results = [];
+        for (const entry of entries) {
+            const dir = join(pluginsDir, entry);
+            // Only descend into directories (skip files, symlinks, etc.).
+            try {
+                const st = statSync(dir);
+                if (!st.isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const result = readManifest(dir);
+            if (result.ok) {
+                results.push({ dir, manifest: result.manifest, ok: true });
+            }
+            else {
+                results.push({ dir, ok: false, reason: result.reason });
+            }
+        }
+        return results;
+    }
+    catch {
+        return [];
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal: raceActivate — activate with timeout
+// ---------------------------------------------------------------------------
+/**
+ * Race plugin.activate(host) against a timeout.
+ * Returns contributions on success, or throws on timeout/error.
+ */
+function raceActivate(plugin, host) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error('plugin activate() timed out'));
+        }, _activateTimeoutMs);
+        Promise.resolve()
+            .then(() => plugin.activate(host))
+            .then((contributions) => {
+            clearTimeout(timer);
+            resolve(contributions);
+        })
+            .catch((err) => {
+            clearTimeout(timer);
+            reject(err instanceof Error ? err : new Error(String(err)));
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Internal: filterContributions — drop undeclared capability kinds
+// ---------------------------------------------------------------------------
+/**
+ * Drop contributions whose kind is not declared in manifest.capabilities.
+ * Audits a 'plugin:capability-violation' for each dropped kind.
+ */
+function filterContributions(name, manifest, raw) {
+    const caps = new Set(manifest.capabilities);
+    const filtered = {};
+    if (raw.scanners !== undefined) {
+        if (caps.has('scanner')) {
+            filtered.scanners = raw.scanners;
+        }
+        else {
+            audit({
+                action: 'plugin:capability-violation',
+                repo: null,
+                sandboxId: null,
+                summary: `plugin "${name}" contributed scanners but did not declare 'scanner' capability`,
+                result: 'refused',
+            });
+        }
+    }
+    if (raw.templates !== undefined) {
+        if (caps.has('template')) {
+            filtered.templates = raw.templates;
+        }
+        else {
+            audit({
+                action: 'plugin:capability-violation',
+                repo: null,
+                sandboxId: null,
+                summary: `plugin "${name}" contributed templates but did not declare 'template' capability`,
+                result: 'refused',
+            });
+        }
+    }
+    if (raw.providers !== undefined) {
+        if (caps.has('provider')) {
+            filtered.providers = raw.providers;
+        }
+        else {
+            audit({
+                action: 'plugin:capability-violation',
+                repo: null,
+                sandboxId: null,
+                summary: `plugin "${name}" contributed providers but did not declare 'provider' capability`,
+                result: 'refused',
+            });
+        }
+    }
+    if (raw.commands !== undefined) {
+        if (caps.has('command')) {
+            filtered.commands = raw.commands;
+        }
+        else {
+            audit({
+                action: 'plugin:capability-violation',
+                repo: null,
+                sandboxId: null,
+                summary: `plugin "${name}" contributed commands but did not declare 'command' capability`,
+                result: 'refused',
+            });
+        }
+    }
+    return filtered;
+}
+// ---------------------------------------------------------------------------
+// loadEnabledPlugins — the main loader
+// ---------------------------------------------------------------------------
+/**
+ * Load all enabled plugins per cfg.plugins.enabled gate chain.
+ *
+ * Gate chain (each step audited):
+ *  1. ASHLR_NO_PLUGINS=1 → return [].
+ *  2. killSwitchOn() → return [] + audit refused.
+ *  3. cfg.plugins?.enabled ?? [] (default empty → load NOTHING).
+ *  4. Manifest valid + apiVersion compatible.
+ *  5. verifyIntegrity passes.
+ *  6. await import(pathToFileURL(entry).href).
+ *  7. activate(host) raced against timeout.
+ *  8. Capability filter.
+ *
+ * A failing plugin is skipped (audited), never fatal.
+ * Results are cached per process (keyed on sorted enabled names).
+ */
+export async function loadEnabledPlugins(cfg) {
+    // Gate 1: ASHLR_NO_PLUGINS
+    if (process.env.ASHLR_NO_PLUGINS === '1') {
+        return [];
+    }
+    // Gate 2: kill switch
+    if (killSwitchOn()) {
+        audit({
+            action: 'plugin:load',
+            repo: null,
+            sandboxId: null,
+            summary: 'plugin loading refused: kill switch is ON',
+            result: 'refused',
+        });
+        return [];
+    }
+    // Gate 3: enabled list (default empty = load nothing)
+    const enabled = cfg.plugins?.enabled ?? [];
+    if (enabled.length === 0) {
+        return [];
+    }
+    // Cache key: sorted enabled names (order-independent)
+    const cacheKey = JSON.stringify([...enabled].sort());
+    if (_cache !== null) {
+        const cached = _cache.get(cacheKey);
+        if (cached !== undefined) {
+            return cached;
+        }
+    }
+    const pluginsDir = join(homedir(), '.ashlr', 'plugins');
+    const loaded = [];
+    for (const name of enabled) {
+        const dir = join(pluginsDir, name);
+        // Gate 4: read + validate manifest (also checks apiVersion range)
+        const manifestResult = readManifest(dir);
+        if (!manifestResult.ok) {
+            audit({
+                action: 'plugin:load',
+                repo: null,
+                sandboxId: null,
+                summary: `plugin "${name}" refused: invalid manifest — ${manifestResult.reason}`,
+                result: 'refused',
+            });
+            continue;
+        }
+        const manifest = manifestResult.manifest;
+        const entryPath = resolvePath(dir, manifest.entry);
+        // Gate 5: integrity verification
+        const integrityResult = verifyIntegrity(cfg, name, entryPath);
+        if (!integrityResult.ok) {
+            audit({
+                action: 'plugin:load',
+                repo: null,
+                sandboxId: null,
+                summary: `plugin "${name}" refused: integrity check failed — ${integrityResult.reason ?? 'unknown'}`,
+                result: 'refused',
+            });
+            continue;
+        }
+        // Gate 6: dynamic import
+        let pluginModule;
+        try {
+            pluginModule = await import(pathToFileURL(entryPath).href);
+        }
+        catch (err) {
+            audit({
+                action: 'plugin:load',
+                repo: null,
+                sandboxId: null,
+                summary: `plugin "${name}" error: import failed — ${err instanceof Error ? err.message : String(err)}`,
+                result: 'error',
+            });
+            continue;
+        }
+        // Resolve module default export or named 'plugin' export
+        let plugin;
+        if (pluginModule !== null && typeof pluginModule === 'object') {
+            const mod = pluginModule;
+            if ('default' in mod) {
+                plugin = mod['default'];
+            }
+            else if ('plugin' in mod) {
+                plugin = mod['plugin'];
+            }
+            else {
+                plugin = pluginModule;
+            }
+        }
+        else {
+            plugin = pluginModule;
+        }
+        // Validate AshlrPlugin shape (must have activate function)
+        if (plugin === null ||
+            typeof plugin !== 'object' ||
+            typeof plugin['activate'] !== 'function') {
+            audit({
+                action: 'plugin:load',
+                repo: null,
+                sandboxId: null,
+                summary: `plugin "${name}" error: module does not export an AshlrPlugin (missing activate function)`,
+                result: 'error',
+            });
+            continue;
+        }
+        const ashlrPlugin = plugin;
+        // Gate 7: activate with timeout
+        const host = buildHostApi(manifest, cfg);
+        let contributions;
+        try {
+            contributions = await raceActivate(ashlrPlugin, host);
+        }
+        catch (err) {
+            audit({
+                action: 'plugin:load',
+                repo: null,
+                sandboxId: null,
+                summary: `plugin "${name}" error: activate() failed — ${err instanceof Error ? err.message : String(err)}`,
+                result: 'error',
+            });
+            continue;
+        }
+        // Gate 8: capability filter (drops undeclared kinds + audits violations)
+        const filtered = filterContributions(name, manifest, contributions);
+        audit({
+            action: 'plugin:load',
+            repo: null,
+            sandboxId: null,
+            summary: `plugin "${name}" loaded successfully`,
+            result: 'ok',
+        });
+        loaded.push({ name, manifest, contributions: filtered });
+    }
+    // Store in cache
+    if (_cache === null) {
+        _cache = new Map();
+    }
+    _cache.set(cacheKey, loaded);
+    return loaded;
+}
+// ---------------------------------------------------------------------------
+// Accessors — async helpers over loadEnabledPlugins
+// ---------------------------------------------------------------------------
+/**
+ * Get all plugin scanners, wrapped for safety (timeout, cap, scrub, namespace).
+ * Returns wrapped functions (repo: string) => Promise<WorkItem[]>.
+ */
+export async function getPluginScanners(cfg) {
+    const plugins = await loadEnabledPlugins(cfg);
+    const wrapped = [];
+    for (const p of plugins) {
+        for (const scanner of (p.contributions.scanners ?? [])) {
+            wrapped.push(wrapScanner(p.name, scanner));
+        }
+    }
+    return wrapped;
+}
+/**
+ * Get all plugin templates, validated (id-prefixed, path-checked).
+ */
+export async function getPluginTemplates(cfg) {
+    const plugins = await loadEnabledPlugins(cfg);
+    const templates = [];
+    for (const p of plugins) {
+        for (const t of p.contributions.templates ?? []) {
+            const validated = validateTemplate(p.name, t);
+            if (validated !== null) {
+                templates.push(validated);
+            }
+        }
+    }
+    return templates;
+}
+/**
+ * Get all plugin providers (raw, as contributed after capability filtering).
+ */
+export async function getPluginProviders(cfg) {
+    const plugins = await loadEnabledPlugins(cfg);
+    const providers = [];
+    for (const p of plugins) {
+        for (const provider of p.contributions.providers ?? []) {
+            providers.push(provider);
+        }
+    }
+    return providers;
+}
+/**
+ * Get all plugin commands, wrapped for safety (audit, exit-code catch).
+ */
+export async function getPluginCommands(cfg) {
+    const plugins = await loadEnabledPlugins(cfg);
+    const commands = [];
+    for (const p of plugins) {
+        for (const cmd of p.contributions.commands ?? []) {
+            commands.push(wrapCommand(p.name, cmd));
+        }
+    }
+    return commands;
+}
+//# sourceMappingURL=registry.js.map

package/dist/core/plugins/registry.js.map

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

package/dist/core/plugins/types.d.ts

@@ -0,0 +1,182 @@
+/**
+ * core/plugins/types.ts — M33 plugin-system public types.
+ *
+ * CONTRACT RULES (non-negotiable):
+ *  - PLUGIN_API_VERSION is the host's current API version. Plugins declare a
+ *    semver RANGE in manifest.apiVersion; loadEnabledPlugins verifies
+ *    compatibility before import.
+ *  - PluginHost carries ONLY a deep-frozen copy of the plugin's own settings
+ *    and an allowlisted VIEW of config — never the full AshlrConfig.
+ *  - PluginContributions may include scanners, templates, providers, commands.
+ *    Contributions whose kind is not declared in manifest.capabilities are
+ *    DROPPED by the registry gate (capability-violation audit).
+ *  - definePlugin is an identity helper so plugin authors get full type-checking
+ *    on their module default export without an explicit cast.
+ *  - Never throws from any type-level helper; all guards are pure.
+ */
+import type { WorkItem, ProjectTemplate } from '../types.js';
+/**
+ * The API version this host implements. Plugins declare a semver RANGE in
+ * manifest.apiVersion; only compatible ranges are loaded.
+ * Bumped when the PluginHost shape or contribution contracts change.
+ */
+export declare const PLUGIN_API_VERSION = "1.0.0";
+/**
+ * The set of capability kinds a plugin may declare. A plugin may only
+ * contribute items whose kind appears in manifest.capabilities — undeclared
+ * contributions are DROPPED and audited as 'plugin:capability-violation'.
+ */
+export type PluginCapability = 'scanner' | 'template' | 'provider' | 'command';
+/**
+ * Parsed, validated shape of a plugin's manifest.json.
+ *
+ * VALIDATION RULES (enforced by readManifest — never assumed by callers):
+ *  - name: ^[a-z][a-z0-9-]{0,39}$ AND must equal basename(dir).
+ *  - version: plugin's own semver (informational; not range-evaluated).
+ *  - apiVersion: semver RANGE evaluated against PLUGIN_API_VERSION.
+ *    Supported forms: exact "1.0.0", caret "^1.0.0", tilde "~1.0.0", wildcard "1.x".
+ *  - entry: relative path ("./index.js"); must resolve INSIDE the plugin dir
+ *    (path-string containment check; entry file may not exist at discovery time).
+ *  - capabilities: non-empty array of PluginCapability.
+ *  - No __proto__ / constructor / prototype keys anywhere in the object.
+ */
+export interface PluginManifest {
+    /** Plugin name — must match ^[a-z][a-z0-9-]{0,39}$ and equal basename(dir). */
+    name: string;
+    /** The plugin's own semver (e.g. "0.1.0"). */
+    version: string;
+    /**
+     * Semver RANGE the plugin requires of the host API.
+     * Forms: exact "1.0.0", caret "^1.0.0", tilde "~1.0.0", wildcard "1.x" / "1.0.x".
+     */
+    apiVersion: string;
+    /** Short human-readable description. */
+    description?: string;
+    /**
+     * Relative ESM entry path from the plugin dir (e.g. "./index.js").
+     * Must resolve INSIDE the plugin dir — no ".." segments, no absolute paths.
+     */
+    entry: string;
+    /** What this plugin contributes. Only declared kinds may appear in contributions. */
+    capabilities: PluginCapability[];
+    /** Optional link to plugin docs or homepage. */
+    homepage?: string;
+}
+/**
+ * The host API handed to a plugin's activate() function.
+ * Every property is read-only and frozen; the plugin cannot mutate host state.
+ *
+ * SAFETY:
+ *  - `settings` is a deep-frozen structuredClone of cfg.plugins.settings[name] only.
+ *    The plugin NEVER receives the full AshlrConfig.
+ *  - `view` is a frozen, allowlisted projection — never the raw config.
+ *  - `audit()` prefixes every action with "plugin:<name>:" automatically.
+ *  - `log()` writes to stderr, prefixed "[plugin:<name>]".
+ *  - `dataDir` is ~/.ashlr/plugin-data/<name>/; created eagerly on buildHostApi.
+ */
+export interface PluginHost {
+    /** The host's current API version (PLUGIN_API_VERSION). */
+    readonly apiVersion: string;
+    /** The name of this plugin (from its manifest). */
+    readonly pluginName: string;
+    /**
+     * Write a log line to stderr. Output is prefixed "[plugin:<name>]".
+     * Never throws.
+     */
+    log(msg: string): void;
+    /**
+     * Emit an audit record. The action is automatically namespaced as
+     * "plugin:<name>:<action>" so plugin audit traffic is identifiable.
+     * Delegates to core/sandbox/audit.ts audit(); never throws.
+     */
+    audit(action: string, summary: string): void;
+    /**
+     * Deep-frozen copy of cfg.plugins.settings[<name>] — the plugin's own
+     * key/value settings ONLY. Never the full AshlrConfig.
+     */
+    readonly settings: Readonly<Record<string, unknown>>;
+    /**
+     * Frozen, allowlisted projection of the host config. Contains only
+     * non-sensitive fields that plugins legitimately need.
+     * Never the raw AshlrConfig.
+     */
+    readonly view: Readonly<{
+        editor: string;
+        staleDays: number;
+    }>;
+    /**
+     * Absolute path to ~/.ashlr/plugin-data/<name>/.
+     * Created eagerly by buildHostApi; the plugin may read/write here freely.
+     */
+    readonly dataDir: string;
+}
+/** A scanner contributed by a plugin. */
+export interface PluginScanner {
+    /** Stable scanner id (e.g. "my-linter"). Namespaced on load: plugin:<name>:<id>. */
+    id: string;
+    /**
+     * Scan a repo and return discovered WorkItems. Must not throw — errors should
+     * be caught internally and return []. Called with a 15-second AbortSignal.
+     */
+    scan(repo: string, ctx: {
+        signal: AbortSignal;
+    }): Promise<WorkItem[]>;
+}
+/** A provider spec contributed by a plugin. */
+export interface PluginProviderSpec {
+    /** Stable provider id. */
+    id: string;
+    /** Whether this provider runs locally or in the cloud. */
+    tier: 'local' | 'cloud';
+    /** Environment variable names this provider requires. */
+    envKeys?: string[];
+    /** Probe availability. Should resolve quickly; never throw. */
+    probe(): Promise<unknown>;
+    /** Create a client instance. */
+    createClient(opts: {
+        model?: string;
+    }): Promise<unknown>;
+}
+/** A CLI command contributed by a plugin. */
+export interface PluginCommandSpec {
+    /** The sub-command name (e.g. "lint"). Invoked as `ashlr plugin <name> <cmd>`. */
+    name: string;
+    /** Short description shown in help. */
+    description: string;
+    /**
+     * Run the command. Return exit code (0 = success). Must not throw — the
+     * wrapper catches throws and returns exit code 1.
+     */
+    run(args: string[], host: PluginHost): Promise<number>;
+}
+/**
+ * What a plugin contributes to the host after activate() resolves.
+ * Contributions whose kind is not declared in manifest.capabilities are
+ * silently DROPPED and audited by the registry gate.
+ */
+export interface PluginContributions {
+    scanners?: PluginScanner[];
+    templates?: ProjectTemplate[];
+    providers?: PluginProviderSpec[];
+    commands?: PluginCommandSpec[];
+}
+/**
+ * The interface a plugin module must satisfy. The module's default export (or
+ * named `plugin` export) must implement this.
+ *
+ * `activate(host)` is called once per process, raced against a 5-second
+ * timeout. May be sync or async. Must not throw — failures are isolated by the
+ * registry loader.
+ */
+export interface AshlrPlugin {
+    activate(host: PluginHost): PluginContributions | Promise<PluginContributions>;
+}
+/**
+ * Identity helper for plugin authors. Wrap your plugin object to get full
+ * TypeScript checking without an explicit cast:
+ *
+ *   export default definePlugin({ activate(host) { ... } });
+ *
+ * At runtime this is a pure identity function — zero overhead.
+ */
+export declare function definePlugin(p: AshlrPlugin): AshlrPlugin;

package/dist/core/plugins/types.js

@@ -0,0 +1,40 @@
+/**
+ * core/plugins/types.ts — M33 plugin-system public types.
+ *
+ * CONTRACT RULES (non-negotiable):
+ *  - PLUGIN_API_VERSION is the host's current API version. Plugins declare a
+ *    semver RANGE in manifest.apiVersion; loadEnabledPlugins verifies
+ *    compatibility before import.
+ *  - PluginHost carries ONLY a deep-frozen copy of the plugin's own settings
+ *    and an allowlisted VIEW of config — never the full AshlrConfig.
+ *  - PluginContributions may include scanners, templates, providers, commands.
+ *    Contributions whose kind is not declared in manifest.capabilities are
+ *    DROPPED by the registry gate (capability-violation audit).
+ *  - definePlugin is an identity helper so plugin authors get full type-checking
+ *    on their module default export without an explicit cast.
+ *  - Never throws from any type-level helper; all guards are pure.
+ */
+// ---------------------------------------------------------------------------
+// Host API version
+// ---------------------------------------------------------------------------
+/**
+ * The API version this host implements. Plugins declare a semver RANGE in
+ * manifest.apiVersion; only compatible ranges are loaded.
+ * Bumped when the PluginHost shape or contribution contracts change.
+ */
+export const PLUGIN_API_VERSION = '1.0.0';
+// ---------------------------------------------------------------------------
+// definePlugin — identity helper
+// ---------------------------------------------------------------------------
+/**
+ * Identity helper for plugin authors. Wrap your plugin object to get full
+ * TypeScript checking without an explicit cast:
+ *
+ *   export default definePlugin({ activate(host) { ... } });
+ *
+ * At runtime this is a pure identity function — zero overhead.
+ */
+export function definePlugin(p) {
+    return p;
+}
+//# sourceMappingURL=types.js.map

package/dist/core/plugins/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/plugins/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAiL1C,8EAA8E;AAC9E,iCAAiC;AACjC,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,CAAc;IACzC,OAAO,CAAC,CAAC;AACX,CAAC"}