@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

package/dist/src/extensions/registry.js

@@ -0,0 +1,368 @@
+/**
+ * Extension Registry
+ *
+ * Provides efficient storage, indexing, and retrieval of AIWG extensions.
+ * Supports O(1) lookup by ID, type-based indexing, and command alias resolution.
+ *
+ * @architecture @.aiwg/architecture/unified-extension-schema.md
+ * @tests @test/unit/extensions/registry.test.ts
+ * @version 1.0.0
+ */
+/**
+ * Extension registry for storing and querying extensions
+ *
+ * Maintains multiple indexes for efficient lookup:
+ * - Primary storage: Map<id, Extension> for O(1) lookup by ID
+ * - Type index: Map<type, Set<id>> for filtering by type
+ * - Alias map: Map<alias, id> for command resolution
+ *
+ * @example
+ * ```typescript
+ * const registry = new ExtensionRegistry();
+ *
+ * // Register an extension
+ * registry.register(myExtension);
+ *
+ * // Lookup by ID (O(1))
+ * const ext = registry.get('mention-wire');
+ *
+ * // Get all commands
+ * const commands = registry.getByType('command');
+ *
+ * // Resolve command alias
+ * const id = registry.resolveCommand('wire'); // Returns 'mention-wire'
+ * ```
+ */
+export class ExtensionRegistry {
+    /**
+     * Primary storage: extension ID to Extension
+     *
+     * Provides O(1) lookup by ID.
+     */
+    extensions = new Map();
+    /**
+     * Type index: extension type to Set of extension IDs
+     *
+     * Enables efficient filtering by type.
+     */
+    byType = new Map();
+    /**
+     * Alias map: command alias to extension ID
+     *
+     * Enables O(1) command resolution by name or alias.
+     */
+    aliasMap = new Map();
+    /**
+     * Qualified name map: `{namespace}-{id}` to extension ID
+     *
+     * Enables lookup by canonical namespaced slug (e.g. `aiwg-sync` → `sync`).
+     * Only populated for skills/commands that carry a `namespace` field.
+     */
+    qualifiedNameMap = new Map();
+    /**
+     * Register an extension in the registry
+     *
+     * If an extension with the same ID already exists, it will be replaced.
+     * Automatically updates type index and registers command aliases.
+     *
+     * @param extension - Extension to register
+     *
+     * @example
+     * ```typescript
+     * registry.register({
+     *   id: 'mention-wire',
+     *   type: 'command',
+     *   name: 'Mention Wire',
+     *   // ... other fields
+     * });
+     * ```
+     */
+    register(extension) {
+        const { id } = extension;
+        // If extension already exists, remove it from old type index
+        const existing = this.extensions.get(id);
+        if (existing) {
+            this.removeFromTypeIndex(existing);
+        }
+        // Store extension
+        this.extensions.set(id, extension);
+        // Add to type index
+        this.addToTypeIndex(extension);
+        // Register command aliases if present
+        if ((extension.type === 'command' || extension.type === 'skill') && 'aliases' in extension.metadata) {
+            const aliases = extension.metadata.aliases;
+            if (Array.isArray(aliases)) {
+                aliases.forEach((alias) => {
+                    this.registerAlias(alias, id);
+                });
+            }
+        }
+        // Register primary command/skill name
+        if (extension.type === 'command' || extension.type === 'skill') {
+            this.aliasMap.set(id, id);
+        }
+        // Register qualified name for namespaced skills/commands
+        if ((extension.type === 'skill' || extension.type === 'command') && 'namespace' in extension.metadata) {
+            const namespace = extension.metadata.namespace;
+            if (namespace) {
+                const prefix = `${namespace}-`;
+                const qualifiedName = id.startsWith(prefix) ? id : `${prefix}${id}`;
+                this.qualifiedNameMap.set(qualifiedName, id);
+            }
+        }
+    }
+    /**
+     * Get extension by ID
+     *
+     * O(1) lookup via Map.
+     *
+     * @param id - Extension ID
+     * @returns Extension if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const ext = registry.get('mention-wire');
+     * if (ext) {
+     *   console.log(ext.name);
+     * }
+     * ```
+     */
+    get(id) {
+        return this.extensions.get(id);
+    }
+    /**
+     * Get all extensions of a specific type
+     *
+     * Uses type index for efficient filtering.
+     *
+     * @param type - Extension type to filter by
+     * @returns Array of extensions of the specified type
+     *
+     * @example
+     * ```typescript
+     * const commands = registry.getByType('command');
+     * const agents = registry.getByType('agent');
+     * ```
+     */
+    getByType(type) {
+        const ids = this.byType.get(type);
+        if (!ids || ids.size === 0) {
+            return [];
+        }
+        const extensions = [];
+        for (const id of ids) {
+            const ext = this.extensions.get(id);
+            if (ext) {
+                extensions.push(ext);
+            }
+        }
+        return extensions;
+    }
+    /**
+     * Resolve a command name or alias to extension ID
+     *
+     * O(1) lookup via Map.
+     *
+     * @param command - Command name or alias
+     * @returns Extension ID if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const id = registry.resolveCommand('wire'); // 'mention-wire'
+     * const ext = registry.get(id);
+     * ```
+     */
+    resolveCommand(command) {
+        return this.aliasMap.get(command);
+    }
+    /**
+     * Register a command alias
+     *
+     * Associates an alias with an extension ID. The extension does not
+     * need to be registered first.
+     *
+     * @param alias - Command alias
+     * @param extensionId - Target extension ID
+     *
+     * @example
+     * ```typescript
+     * registry.registerAlias('wire', 'mention-wire');
+     * registry.registerAlias('w', 'mention-wire');
+     * ```
+     */
+    registerAlias(alias, extensionId) {
+        this.aliasMap.set(alias, extensionId);
+    }
+    /**
+     * Resolve a qualified namespaced name to an extension ID.
+     *
+     * Accepts either the canonical qualified slug (`aiwg-sync`) or the bare ID (`sync`).
+     * Falls back to bare ID lookup when no qualified name match is found.
+     *
+     * @param qualifiedName - Qualified skill name (e.g. `aiwg-sync`) or bare ID
+     * @returns Extension ID if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const id = registry.resolveQualifiedName('aiwg-sync'); // 'sync'
+     * const ext = registry.get(id);
+     * ```
+     */
+    resolveQualifiedName(qualifiedName) {
+        return this.qualifiedNameMap.get(qualifiedName) ?? this.extensions.get(qualifiedName)?.id;
+    }
+    /**
+     * Get all registered extensions
+     *
+     * Returns a new array containing all extensions. Modifications to the
+     * returned array will not affect the registry.
+     *
+     * @returns Array of all extensions
+     *
+     * @example
+     * ```typescript
+     * const all = registry.getAll();
+     * console.log(`Registry contains ${all.length} extensions`);
+     * ```
+     */
+    getAll() {
+        return Array.from(this.extensions.values());
+    }
+    /**
+     * Get count of registered extensions
+     *
+     * @returns Number of extensions in the registry
+     *
+     * @example
+     * ```typescript
+     * console.log(`${registry.size} extensions registered`);
+     * ```
+     */
+    get size() {
+        return this.extensions.size;
+    }
+    /**
+     * Check if extension exists in registry
+     *
+     * O(1) lookup via Map.
+     *
+     * @param id - Extension ID to check
+     * @returns True if extension exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (registry.has('mention-wire')) {
+     *   console.log('Extension is registered');
+     * }
+     * ```
+     */
+    has(id) {
+        return this.extensions.has(id);
+    }
+    /**
+     * Clear the registry
+     *
+     * Removes all extensions, type index entries, and aliases.
+     *
+     * @example
+     * ```typescript
+     * registry.clear();
+     * console.log(registry.size); // 0
+     * ```
+     */
+    clear() {
+        this.extensions.clear();
+        this.byType.clear();
+        this.aliasMap.clear();
+        this.qualifiedNameMap.clear();
+    }
+    /**
+     * Add extension to type index
+     *
+     * @private
+     * @param extension - Extension to index
+     */
+    addToTypeIndex(extension) {
+        const { id, type } = extension;
+        let typeSet = this.byType.get(type);
+        if (!typeSet) {
+            typeSet = new Set();
+            this.byType.set(type, typeSet);
+        }
+        typeSet.add(id);
+    }
+    /**
+     * Remove extension from type index
+     *
+     * @private
+     * @param extension - Extension to remove from index
+     */
+    removeFromTypeIndex(extension) {
+        const { id, type } = extension;
+        const typeSet = this.byType.get(type);
+        if (typeSet) {
+            typeSet.delete(id);
+            // Clean up empty sets
+            if (typeSet.size === 0) {
+                this.byType.delete(type);
+            }
+        }
+    }
+}
+// ============================================
+// Singleton Instance
+// ============================================
+/**
+ * Global registry instance
+ *
+ * Singleton instance shared across all calls to getRegistry().
+ */
+let globalRegistry = null;
+/**
+ * Get the global registry instance
+ *
+ * Returns a singleton ExtensionRegistry instance. All calls to this
+ * function return the same instance, allowing state to be shared
+ * across the application.
+ *
+ * @returns Global ExtensionRegistry instance
+ *
+ * @example
+ * ```typescript
+ * import { getRegistry } from './registry.js';
+ *
+ * const registry = getRegistry();
+ * registry.register(myExtension);
+ *
+ * // Later, in another module
+ * const sameRegistry = getRegistry();
+ * console.log(sameRegistry.has('my-extension')); // true
+ * ```
+ */
+export function getRegistry() {
+    if (!globalRegistry) {
+        globalRegistry = new ExtensionRegistry();
+    }
+    return globalRegistry;
+}
+/**
+ * Create a new registry instance
+ *
+ * Returns a new, independent ExtensionRegistry instance. Use this when
+ * you need an isolated registry for testing or scoped operations.
+ *
+ * @returns New ExtensionRegistry instance
+ *
+ * @example
+ * ```typescript
+ * import { createRegistry } from './registry.js';
+ *
+ * const testRegistry = createRegistry();
+ * testRegistry.register(testExtension);
+ * // testRegistry is independent of global registry
+ * ```
+ */
+export function createRegistry() {
+    return new ExtensionRegistry();
+}
+//# sourceMappingURL=registry.js.map

package/dist/src/extensions/shadow-resolver.js

@@ -0,0 +1,271 @@
+/**
+ * Shadow Resolver
+ *
+ * Implements the override / shadow-resolution policy from
+ * `.aiwg/architecture/adr-override-shadow-policy.md` (#1041) for project-local
+ * artifact bundles deployed via `aiwg use` / `aiwg refresh`.
+ *
+ * Resolves the seven cases from ADR §4:
+ *
+ *   1. No collision — deploy normally
+ *   2. Non-safety-critical shadow — deploy + warn
+ *   3. Safety-critical shadow with `overrides:` declaration — deploy + prominent warn
+ *   4. Safety-critical shadow without `overrides:` — REFUSE
+ *   5. Phantom override (declared override has no upstream match) — REFUSE
+ *   6. Two project-local bundles export the same id — REFUSE both
+ *   7. git-installed source collides with project-local — same as 2/3/4 against cache
+ *
+ * Inputs: the project-local bundles (from `discoverProjectLocalBundles`) and
+ * an upstream registry (from `buildUpstreamRegistry`). Outputs a per-artifact
+ * verdict that the deployment pipeline consumes to decide what to write to
+ * provider paths.
+ *
+ * @implements #1036
+ */
+import { readdir, readFile, stat } from 'fs/promises';
+import { join, basename } from 'path';
+const ARTIFACT_DIRS = {
+    agents: 'agent',
+    skills: 'skill',
+    rules: 'rule',
+    commands: 'command',
+};
+const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---/;
+const ID_LINE_RE = /^id\s*:\s*['"]?([^'"\n]+?)['"]?\s*$/m;
+const NAME_LINE_RE = /^name\s*:\s*['"]?([^'"\n]+?)['"]?\s*$/m;
+function parseId(raw) {
+    const m = FRONTMATTER_RE.exec(raw);
+    if (!m)
+        return {};
+    return {
+        id: ID_LINE_RE.exec(m[1])?.[1]?.trim(),
+        name: NAME_LINE_RE.exec(m[1])?.[1]?.trim(),
+    };
+}
+/** Enumerate the artifacts a project-local bundle would deploy by walking its
+ * source `agents/`, `skills/`, `rules/`, `commands/` subdirs — same pattern as
+ * `deployOneProjectLocalBundle` and `countBundleSourceArtifacts` in use.ts. */
+export async function enumerateBundleArtifacts(bundlePath) {
+    const out = [];
+    for (const [dirName, type] of Object.entries(ARTIFACT_DIRS)) {
+        const artifactDir = join(bundlePath, dirName);
+        let entries;
+        try {
+            entries = await readdir(artifactDir);
+        }
+        catch {
+            continue;
+        }
+        if (type === 'skill') {
+            for (const entry of entries) {
+                const skillDir = join(artifactDir, entry);
+                try {
+                    const st = await stat(skillDir);
+                    if (!st.isDirectory())
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                let id = entry;
+                try {
+                    const skillMd = await readFile(join(skillDir, 'SKILL.md'), 'utf-8');
+                    const fm = parseId(skillMd);
+                    id = fm.name ?? fm.id ?? entry;
+                }
+                catch {
+                    // No SKILL.md — fall back to dir name
+                }
+                out.push({ id, type, sourcePath: skillDir });
+            }
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.endsWith('.md'))
+                continue;
+            if (entry === 'README.md' || entry === 'RULES-INDEX.md' || entry === 'INDEX.md')
+                continue;
+            const filePath = join(artifactDir, entry);
+            let id = basename(entry, '.md');
+            try {
+                const raw = await readFile(filePath, 'utf-8');
+                const fm = parseId(raw);
+                id = fm.id ?? fm.name ?? id;
+            }
+            catch {
+                // Read failure — fall back to filename
+            }
+            out.push({ id, type, sourcePath: filePath });
+        }
+    }
+    return out;
+}
+/** Resolve overrides + shadows for a set of project-local bundles against an
+ * upstream registry. Pure function — no filesystem side effects beyond reading
+ * the bundle artifact files for id extraction. */
+export async function resolveShadows(bundles, upstream, options = {}) {
+    const strictPhantomOverrides = options.strictPhantomOverrides ?? true;
+    const resolutions = [];
+    const blockedBundleIds = new Set();
+    // Pre-pass: case 6 — duplicate project-local bundle ids (cross-bundle, by
+    // artifact id+type). Discovery already rejects same-type duplicate bundle
+    // ids (#1041 §4 case 6 at the bundle level); here we additionally guard
+    // against two distinct bundles exporting an artifact with the same id+type.
+    const projectLocalArtifacts = new Map();
+    // Enumerate every artifact in every bundle once.
+    const enumerated = [];
+    for (const bundle of bundles) {
+        const arts = await enumerateBundleArtifacts(bundle.bundlePath);
+        enumerated.push({ bundle, arts });
+        for (const art of arts) {
+            const key = `${art.type}:${art.id}`;
+            const list = projectLocalArtifacts.get(key) ?? [];
+            list.push({ bundle, art });
+            projectLocalArtifacts.set(key, list);
+        }
+    }
+    for (const { bundle, arts } of enumerated) {
+        const declaredOverrides = new Set(bundle.manifest.overrides ?? []);
+        // Case 5 pre-pass: validate every declared override resolves to *some*
+        // upstream artifact (any type). Phantom overrides refuse the bundle.
+        for (const overrideId of declaredOverrides) {
+            if (!upstream.byId.has(overrideId)) {
+                resolutions.push({
+                    bundleId: bundle.id,
+                    bundleLocalPath: bundle.localPath,
+                    artifactId: overrideId,
+                    artifactType: 'rule', // unknown — picked nominal type for surface
+                    artifactSourcePath: bundle.manifestPath,
+                    verdict: 'refuse-phantom',
+                    message: `Phantom override: '${overrideId}' declared in ${bundle.manifestPath} but no upstream artifact has that id.`,
+                    blocking: strictPhantomOverrides,
+                    prominent: false,
+                });
+                if (strictPhantomOverrides)
+                    blockedBundleIds.add(bundle.id);
+            }
+        }
+        for (const art of arts) {
+            const key = `${art.type}:${art.id}`;
+            // Case 6 — duplicate project-local artifact id+type across bundles
+            const projectLocalGroup = projectLocalArtifacts.get(key) ?? [];
+            if (projectLocalGroup.length > 1) {
+                const others = projectLocalGroup
+                    .filter((p) => p.bundle.id !== bundle.id)
+                    .map((p) => p.bundle.localPath);
+                resolutions.push({
+                    bundleId: bundle.id,
+                    bundleLocalPath: bundle.localPath,
+                    artifactId: art.id,
+                    artifactType: art.type,
+                    artifactSourcePath: art.sourcePath,
+                    verdict: 'refuse-duplicate',
+                    message: `Duplicate project-local ${art.type} '${art.id}' also exported by: ${others.join(', ')}`,
+                    blocking: true,
+                    prominent: false,
+                });
+                blockedBundleIds.add(bundle.id);
+                continue;
+            }
+            const upstreamMatch = upstream.byKey.get(key);
+            // Case 1 — no collision
+            if (!upstreamMatch) {
+                resolutions.push({
+                    bundleId: bundle.id,
+                    bundleLocalPath: bundle.localPath,
+                    artifactId: art.id,
+                    artifactType: art.type,
+                    artifactSourcePath: art.sourcePath,
+                    verdict: 'deploy',
+                    message: '',
+                    blocking: false,
+                    prominent: false,
+                });
+                continue;
+            }
+            const acknowledged = declaredOverrides.has(art.id);
+            if (upstreamMatch.safetyCritical) {
+                if (acknowledged) {
+                    // Case 3 — safety-critical with explicit override
+                    resolutions.push({
+                        bundleId: bundle.id,
+                        bundleLocalPath: bundle.localPath,
+                        artifactId: art.id,
+                        artifactType: art.type,
+                        artifactSourcePath: art.sourcePath,
+                        upstream: upstreamMatch,
+                        verdict: 'deploy-acknowledged',
+                        message: `SAFETY-CRITICAL SHADOW: ${art.type} '${art.id}' overridden by ${art.sourcePath}.\n` +
+                            `  Acknowledge: this disables upstream safeguard at ${upstreamMatch.sourcePath}.\n` +
+                            `  Use 'aiwg doctor' to review all active shadows.`,
+                        blocking: false,
+                        prominent: true,
+                    });
+                }
+                else {
+                    // Case 4 — refuse
+                    resolutions.push({
+                        bundleId: bundle.id,
+                        bundleLocalPath: bundle.localPath,
+                        artifactId: art.id,
+                        artifactType: art.type,
+                        artifactSourcePath: art.sourcePath,
+                        upstream: upstreamMatch,
+                        verdict: 'refuse-unsafe',
+                        message: `Refused to shadow safety-critical upstream ${art.type} '${art.id}'. ` +
+                            `Add 'overrides: ["${art.id}"]' to ${bundle.manifestPath} to authorize the override.`,
+                        blocking: true,
+                        prominent: true,
+                    });
+                    blockedBundleIds.add(bundle.id);
+                }
+                continue;
+            }
+            // Case 2 — non-safety shadow
+            const sourceLabel = upstreamMatch.source === 'cache' ? 'git-installed' : 'bundled';
+            resolutions.push({
+                bundleId: bundle.id,
+                bundleLocalPath: bundle.localPath,
+                artifactId: art.id,
+                artifactType: art.type,
+                artifactSourcePath: art.sourcePath,
+                upstream: upstreamMatch,
+                verdict: 'deploy-with-warning',
+                message: `Shadow: ${art.type} '${art.id}' — project-local at ${art.sourcePath} ` +
+                    `overrides ${sourceLabel} at ${upstreamMatch.sourcePath}`,
+                blocking: false,
+                prominent: false,
+            });
+        }
+    }
+    const shadows = resolutions.filter((r) => r.upstream !== undefined);
+    return { resolutions, blockedBundleIds, shadows };
+}
+/** Format a multi-resolution summary suitable for stderr or doctor output. */
+export function formatShadowReport(result) {
+    if (result.resolutions.length === 0)
+        return '';
+    const lines = [];
+    const blockers = result.resolutions.filter((r) => r.blocking);
+    const warnings = result.resolutions.filter((r) => !r.blocking && (r.verdict === 'deploy-with-warning' || r.verdict === 'deploy-acknowledged'));
+    if (blockers.length > 0) {
+        lines.push('── Project-local shadow resolution: blocked artifacts ──');
+        for (const r of blockers) {
+            lines.push(`  ✗ [${r.verdict}] ${r.bundleId} :: ${r.artifactType}/${r.artifactId}`);
+            for (const ml of r.message.split('\n'))
+                lines.push(`    ${ml}`);
+        }
+        lines.push('');
+    }
+    if (warnings.length > 0) {
+        lines.push('── Project-local shadows ──');
+        for (const r of warnings) {
+            const marker = r.prominent ? '!!' : '⚠';
+            lines.push(`  ${marker} [${r.verdict}] ${r.bundleId} :: ${r.artifactType}/${r.artifactId}`);
+            for (const ml of r.message.split('\n'))
+                lines.push(`    ${ml}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=shadow-resolver.js.map