agentic-qe 3.8.13 → 3.9.0

package/dist/plugins/cache.js

@@ -0,0 +1,149 @@
+/**
+ * Agentic QE v3 - Plugin Cache (IMP-09)
+ *
+ * Versioned immutable cache for installed plugins.
+ * Stores plugins at `.agentic-qe/plugins/{name}@{version}/`.
+ * Once cached, a version is never modified — only new versions are added.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+// ============================================================================
+// PluginCache
+// ============================================================================
+export class PluginCache {
+    cacheDir;
+    keepVersions;
+    constructor(options = {}) {
+        this.cacheDir = options.cacheDir
+            ?? path.join(process.cwd(), '.agentic-qe', 'plugins');
+        this.keepVersions = options.keepVersions ?? 2;
+    }
+    /** Check if a specific version is cached. */
+    has(name, version) {
+        const dir = this.versionDir(name, version);
+        return fs.existsSync(dir) && fs.existsSync(path.join(dir, 'qe-plugin.json'));
+    }
+    /** Get the cached path for a plugin version, or undefined if not cached. */
+    get(name, version) {
+        if (!this.has(name, version))
+            return undefined;
+        const dir = this.versionDir(name, version);
+        const raw = fs.readFileSync(path.join(dir, 'qe-plugin.json'), 'utf-8');
+        const manifest = JSON.parse(raw);
+        const stat = fs.statSync(dir);
+        return {
+            manifest,
+            path: dir,
+            cachedAt: stat.birthtime.toISOString(),
+        };
+    }
+    /**
+     * Store a plugin in the cache by copying from a source directory.
+     * Returns the cache path. If already cached, returns the existing path
+     * (immutable — no overwrite).
+     */
+    store(manifest, sourceDir) {
+        const dir = this.versionDir(manifest.name, manifest.version);
+        if (fs.existsSync(dir)) {
+            // Already cached — immutable, don't overwrite
+            return dir;
+        }
+        // Copy source to cache
+        fs.mkdirSync(dir, { recursive: true });
+        this.copyDir(sourceDir, dir);
+        // Write the manifest (ensure it's present even if source didn't have it at root)
+        fs.writeFileSync(path.join(dir, 'qe-plugin.json'), JSON.stringify(manifest, null, 2));
+        // Cleanup old versions
+        this.pruneOldVersions(manifest.name);
+        return dir;
+    }
+    /** Remove a specific cached version. */
+    remove(name, version) {
+        const dir = this.versionDir(name, version);
+        if (!fs.existsSync(dir))
+            return false;
+        fs.rmSync(dir, { recursive: true, force: true });
+        return true;
+    }
+    /** List all cached versions for a plugin. */
+    listVersions(name) {
+        const pluginDir = path.join(this.cacheDir, name);
+        if (!fs.existsSync(pluginDir))
+            return [];
+        const results = [];
+        const entries = fs.readdirSync(pluginDir);
+        for (const entry of entries) {
+            const fullPath = path.join(pluginDir, entry);
+            const manifestPath = path.join(fullPath, 'qe-plugin.json');
+            if (fs.existsSync(manifestPath)) {
+                try {
+                    const raw = fs.readFileSync(manifestPath, 'utf-8');
+                    const manifest = JSON.parse(raw);
+                    const stat = fs.statSync(fullPath);
+                    results.push({
+                        manifest,
+                        path: fullPath,
+                        cachedAt: stat.birthtime.toISOString(),
+                    });
+                }
+                catch {
+                    // Skip corrupted entries
+                }
+            }
+        }
+        return results;
+    }
+    /** List all cached plugins (latest version of each). */
+    listAll() {
+        if (!fs.existsSync(this.cacheDir))
+            return [];
+        const results = [];
+        const entries = fs.readdirSync(this.cacheDir);
+        for (const name of entries) {
+            const versions = this.listVersions(name);
+            if (versions.length > 0) {
+                // Return the latest version (lexicographic semver sort)
+                versions.sort((a, b) => b.manifest.version.localeCompare(a.manifest.version));
+                results.push(versions[0]);
+            }
+        }
+        return results;
+    }
+    // --------------------------------------------------------------------------
+    // Internal
+    // --------------------------------------------------------------------------
+    versionDir(name, version) {
+        return path.join(this.cacheDir, name, version);
+    }
+    pruneOldVersions(name) {
+        const versions = this.listVersions(name);
+        if (versions.length <= this.keepVersions)
+            return;
+        // Sort oldest first
+        versions.sort((a, b) => a.cachedAt.localeCompare(b.cachedAt));
+        const toRemove = versions.slice(0, versions.length - this.keepVersions);
+        for (const cached of toRemove) {
+            fs.rmSync(cached.path, { recursive: true, force: true });
+        }
+    }
+    copyDir(src, dest) {
+        if (!fs.existsSync(src))
+            return;
+        const entries = fs.readdirSync(src, { withFileTypes: true });
+        for (const entry of entries) {
+            const srcPath = path.join(src, entry.name);
+            const destPath = path.join(dest, entry.name);
+            if (entry.isDirectory()) {
+                // Skip .git directories
+                if (entry.name === '.git' || entry.name === 'node_modules')
+                    continue;
+                fs.mkdirSync(destPath, { recursive: true });
+                this.copyDir(srcPath, destPath);
+            }
+            else {
+                fs.copyFileSync(srcPath, destPath);
+            }
+        }
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/plugins/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Agentic QE v3 - Plugin Architecture (IMP-09)
+ *
+ * External plugin system for QE domain extensions.
+ * Supports local, GitHub, and npm plugin sources.
+ */
+export { type QEPluginManifest, type ManifestValidationResult, validateManifest, parseManifest } from './manifest';
+export { PluginCache, type CachedPlugin, type PluginCacheOptions } from './cache';
+export { PluginResolver, type ResolvedPlugin, type ResolutionResult } from './resolver';
+export { checkPluginSecurity, isNameSafe, type SecurityCheckResult } from './security';
+export { PluginLifecycleManager, type InstallResult, type PluginInfo, type PluginLifecycleOptions } from './lifecycle';
+export { LocalPluginSource, type PluginSource } from './sources/local';
+export { GitHubPluginSource } from './sources/github';
+export { NpmPluginSource } from './sources/npm';
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/index.js

@@ -0,0 +1,15 @@
+/**
+ * Agentic QE v3 - Plugin Architecture (IMP-09)
+ *
+ * External plugin system for QE domain extensions.
+ * Supports local, GitHub, and npm plugin sources.
+ */
+export { validateManifest, parseManifest } from './manifest';
+export { PluginCache } from './cache';
+export { PluginResolver } from './resolver';
+export { checkPluginSecurity, isNameSafe } from './security';
+export { PluginLifecycleManager } from './lifecycle';
+export { LocalPluginSource } from './sources/local';
+export { GitHubPluginSource } from './sources/github';
+export { NpmPluginSource } from './sources/npm';
+//# sourceMappingURL=index.js.map

package/dist/plugins/lifecycle.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Agentic QE v3 - Plugin Lifecycle Manager (IMP-09)
+ *
+ * Orchestrates the full plugin lifecycle:
+ *   discover -> validate -> resolve deps -> cache -> load -> register
+ *
+ * Integrates with:
+ *   - Plugin sources (local, GitHub, npm) for discovery
+ *   - Plugin cache for versioned immutable storage
+ *   - Plugin resolver for dependency ordering
+ *   - Plugin security for validation
+ *   - Kernel PluginLoader for registration
+ */
+import type { QEPluginManifest } from './manifest';
+import { PluginCache } from './cache';
+import { type ResolutionResult } from './resolver';
+import { type PluginSource } from './sources/local';
+export interface PluginLifecycleOptions {
+    /** Plugin cache instance */
+    cache?: PluginCache;
+    /** Additional plugin sources beyond local */
+    sources?: PluginSource[];
+}
+export interface InstallResult {
+    success: boolean;
+    manifest?: QEPluginManifest;
+    cachePath?: string;
+    errors: string[];
+    securityViolations: string[];
+}
+export interface PluginInfo {
+    name: string;
+    version: string;
+    description: string;
+    domains: string[];
+    source: string;
+    cachePath: string;
+}
+export declare class PluginLifecycleManager {
+    private readonly cache;
+    private readonly resolver;
+    private readonly sources;
+    constructor(options?: PluginLifecycleOptions);
+    /**
+     * Install a plugin from a given location.
+     * Runs the full lifecycle: resolve -> validate -> security check -> cache.
+     * Disabled via AQE_PLUGINS_DISABLED=true.
+     */
+    install(location: string, sourceType?: string): Promise<InstallResult>;
+    /**
+     * Remove a plugin from the cache.
+     */
+    remove(name: string, version?: string): boolean;
+    /**
+     * List all installed plugins.
+     */
+    list(): PluginInfo[];
+    /**
+     * Resolve load order for all cached plugins.
+     */
+    resolveLoadOrder(): ResolutionResult;
+    /**
+     * Register a plugin source.
+     */
+    registerSource(source: PluginSource): void;
+}
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/plugins/lifecycle.js

@@ -0,0 +1,175 @@
+/**
+ * Agentic QE v3 - Plugin Lifecycle Manager (IMP-09)
+ *
+ * Orchestrates the full plugin lifecycle:
+ *   discover -> validate -> resolve deps -> cache -> load -> register
+ *
+ * Integrates with:
+ *   - Plugin sources (local, GitHub, npm) for discovery
+ *   - Plugin cache for versioned immutable storage
+ *   - Plugin resolver for dependency ordering
+ *   - Plugin security for validation
+ *   - Kernel PluginLoader for registration
+ */
+import { validateManifest } from './manifest';
+import { PluginCache } from './cache';
+import { PluginResolver } from './resolver';
+import { checkPluginSecurity } from './security';
+import { LocalPluginSource } from './sources/local';
+// ============================================================================
+// PluginLifecycleManager
+// ============================================================================
+export class PluginLifecycleManager {
+    cache;
+    resolver;
+    sources = new Map();
+    constructor(options = {}) {
+        this.cache = options.cache ?? new PluginCache();
+        this.resolver = new PluginResolver();
+        // Register default local source
+        const localSource = new LocalPluginSource();
+        this.sources.set('local', localSource);
+        // Register additional sources
+        if (options.sources) {
+            for (const source of options.sources) {
+                this.sources.set(source.type, source);
+            }
+        }
+    }
+    // --------------------------------------------------------------------------
+    // Public API
+    // --------------------------------------------------------------------------
+    /**
+     * Install a plugin from a given location.
+     * Runs the full lifecycle: resolve -> validate -> security check -> cache.
+     * Disabled via AQE_PLUGINS_DISABLED=true.
+     */
+    async install(location, sourceType = 'local') {
+        if (process.env.AQE_PLUGINS_DISABLED === 'true') {
+            return {
+                success: false,
+                errors: ['Plugin loading is disabled (AQE_PLUGINS_DISABLED=true)'],
+                securityViolations: [],
+            };
+        }
+        const errors = [];
+        // 1. Get the source
+        const source = this.sources.get(sourceType);
+        if (!source) {
+            return {
+                success: false,
+                errors: [`Unknown source type: ${sourceType}. Available: ${[...this.sources.keys()].join(', ')}`],
+                securityViolations: [],
+            };
+        }
+        // 2. Resolve manifest from source
+        let manifest;
+        try {
+            manifest = await source.resolve(location);
+        }
+        catch (err) {
+            return {
+                success: false,
+                errors: [`Failed to resolve plugin: ${err instanceof Error ? err.message : String(err)}`],
+                securityViolations: [],
+            };
+        }
+        // 3. Validate manifest
+        const validation = validateManifest(manifest);
+        if (!validation.valid) {
+            return {
+                success: false,
+                manifest,
+                errors: validation.errors,
+                securityViolations: [],
+            };
+        }
+        // 4. Security check
+        const security = checkPluginSecurity(manifest);
+        if (!security.safe) {
+            return {
+                success: false,
+                manifest,
+                errors: ['Plugin failed security checks'],
+                securityViolations: security.violations,
+            };
+        }
+        // 5. Check if already cached
+        if (this.cache.has(manifest.name, manifest.version)) {
+            const cached = this.cache.get(manifest.name, manifest.version);
+            return {
+                success: true,
+                manifest,
+                cachePath: cached.path,
+                errors: [],
+                securityViolations: [],
+            };
+        }
+        // 6. Get plugin path and store in cache
+        let pluginPath;
+        try {
+            pluginPath = await source.getPluginPath(location);
+        }
+        catch (err) {
+            return {
+                success: false,
+                manifest,
+                errors: [`Failed to get plugin path: ${err instanceof Error ? err.message : String(err)}`],
+                securityViolations: [],
+            };
+        }
+        const cachePath = this.cache.store(manifest, pluginPath);
+        return {
+            success: true,
+            manifest,
+            cachePath,
+            errors,
+            securityViolations: [],
+        };
+    }
+    /**
+     * Remove a plugin from the cache.
+     */
+    remove(name, version) {
+        if (version) {
+            return this.cache.remove(name, version);
+        }
+        // Remove all versions
+        const versions = this.cache.listVersions(name);
+        let removed = false;
+        for (const v of versions) {
+            if (this.cache.remove(name, v.manifest.version)) {
+                removed = true;
+            }
+        }
+        return removed;
+    }
+    /**
+     * List all installed plugins.
+     */
+    list() {
+        const cached = this.cache.listAll();
+        return cached.map(c => ({
+            name: c.manifest.name,
+            version: c.manifest.version,
+            description: c.manifest.description,
+            domains: c.manifest.domains,
+            source: 'cached',
+            cachePath: c.path,
+        }));
+    }
+    /**
+     * Resolve load order for all cached plugins.
+     */
+    resolveLoadOrder() {
+        const all = this.cache.listAll();
+        return this.resolver.resolve(all.map(c => c.manifest));
+    }
+    /**
+     * Register a plugin source.
+     */
+    registerSource(source) {
+        this.sources.set(source.type, source);
+    }
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/plugins/manifest.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Agentic QE v3 - Plugin Manifest Schema & Validation (IMP-09)
+ *
+ * Defines the `qe-plugin.json` manifest format that external QE domain
+ * plugins must provide. Includes validation logic for name, version,
+ * entry point, and permissions.
+ */
+import type { DomainName } from '../shared/types';
+export interface QEPluginManifest {
+    /** Plugin name (e.g., "aqe-plugin-sap-testing") */
+    name: string;
+    /** Semantic version */
+    version: string;
+    /** Human-readable description */
+    description: string;
+    /** Author name or org */
+    author: string;
+    /** Domains this plugin adds or extends */
+    domains: DomainName[];
+    /** Dependencies on other plugins (name -> semver range) */
+    dependencies?: Record<string, string>;
+    /** Relative path to the main module entry point */
+    entryPoint: string;
+    /** Hook event -> handler path mappings */
+    hooks?: Record<string, string>;
+    /** Minimum AQE version required */
+    minAqeVersion?: string;
+    /** Required permissions */
+    permissions?: string[];
+}
+export interface ManifestValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Validate a plugin manifest. Returns structured errors and warnings.
+ */
+export declare function validateManifest(manifest: unknown): ManifestValidationResult;
+/**
+ * Parse and validate a manifest from a JSON string or object.
+ * Throws on invalid manifests.
+ */
+export declare function parseManifest(input: string | object): QEPluginManifest;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/plugins/manifest.js

@@ -0,0 +1,173 @@
+/**
+ * Agentic QE v3 - Plugin Manifest Schema & Validation (IMP-09)
+ *
+ * Defines the `qe-plugin.json` manifest format that external QE domain
+ * plugins must provide. Includes validation logic for name, version,
+ * entry point, and permissions.
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+/** Regex for valid plugin names: lowercase, alphanumeric, hyphens */
+const VALID_NAME_REGEX = /^[a-z][a-z0-9-]*$/;
+/** Regex for semver: major.minor.patch with optional pre-release */
+const SEMVER_REGEX = /^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$/;
+/** Reserved name prefixes that third-party plugins cannot use */
+const RESERVED_PREFIXES = ['aqe-core-', 'agentic-qe-core-'];
+/** Maximum name length */
+const MAX_NAME_LENGTH = 64;
+/** Maximum description length */
+const MAX_DESCRIPTION_LENGTH = 500;
+// ============================================================================
+// Validation
+// ============================================================================
+/**
+ * Validate a plugin manifest. Returns structured errors and warnings.
+ */
+export function validateManifest(manifest) {
+    const errors = [];
+    const warnings = [];
+    if (!manifest || typeof manifest !== 'object') {
+        return { valid: false, errors: ['Manifest must be a non-null object'], warnings: [] };
+    }
+    const m = manifest;
+    // --- Required fields ---
+    if (!m.name || typeof m.name !== 'string') {
+        errors.push('name is required and must be a string');
+    }
+    else {
+        validateName(m.name, errors, warnings);
+    }
+    if (!m.version || typeof m.version !== 'string') {
+        errors.push('version is required and must be a string');
+    }
+    else if (!SEMVER_REGEX.test(m.version)) {
+        errors.push(`version "${m.version}" is not valid semver (expected: major.minor.patch)`);
+    }
+    if (!m.description || typeof m.description !== 'string') {
+        errors.push('description is required and must be a string');
+    }
+    else if (m.description.length > MAX_DESCRIPTION_LENGTH) {
+        warnings.push(`description exceeds ${MAX_DESCRIPTION_LENGTH} characters`);
+    }
+    if (!m.author || typeof m.author !== 'string') {
+        errors.push('author is required and must be a string');
+    }
+    if (!Array.isArray(m.domains) || m.domains.length === 0) {
+        errors.push('domains is required and must be a non-empty array');
+    }
+    else {
+        for (const d of m.domains) {
+            if (typeof d !== 'string') {
+                errors.push('Each domain must be a string');
+                break;
+            }
+        }
+    }
+    if (!m.entryPoint || typeof m.entryPoint !== 'string') {
+        errors.push('entryPoint is required and must be a string');
+    }
+    else {
+        validateEntryPoint(m.entryPoint, errors);
+    }
+    // --- Optional fields ---
+    if (m.dependencies !== undefined) {
+        if (typeof m.dependencies !== 'object' || m.dependencies === null || Array.isArray(m.dependencies)) {
+            errors.push('dependencies must be an object mapping plugin names to semver ranges');
+        }
+        else {
+            for (const [depName, depVersion] of Object.entries(m.dependencies)) {
+                if (typeof depVersion !== 'string') {
+                    errors.push(`Dependency "${depName}" must have a string version range`);
+                }
+            }
+        }
+    }
+    if (m.hooks !== undefined) {
+        if (typeof m.hooks !== 'object' || m.hooks === null || Array.isArray(m.hooks)) {
+            errors.push('hooks must be an object mapping event names to handler paths');
+        }
+        else {
+            for (const [, handlerPath] of Object.entries(m.hooks)) {
+                if (typeof handlerPath !== 'string') {
+                    errors.push('Hook handler paths must be strings');
+                    break;
+                }
+                if (handlerPath.includes('..')) {
+                    errors.push(`Hook handler path "${handlerPath}" must not contain ".." (path traversal)`);
+                }
+            }
+        }
+    }
+    if (m.minAqeVersion !== undefined) {
+        if (typeof m.minAqeVersion !== 'string' || !SEMVER_REGEX.test(m.minAqeVersion)) {
+            warnings.push('minAqeVersion should be valid semver');
+        }
+    }
+    if (m.permissions !== undefined) {
+        if (!Array.isArray(m.permissions)) {
+            errors.push('permissions must be an array of strings');
+        }
+        else {
+            for (const p of m.permissions) {
+                if (typeof p !== 'string') {
+                    errors.push('Each permission must be a string');
+                    break;
+                }
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}
+/**
+ * Parse and validate a manifest from a JSON string or object.
+ * Throws on invalid manifests.
+ */
+export function parseManifest(input) {
+    const parsed = typeof input === 'string' ? JSON.parse(input) : input;
+    const result = validateManifest(parsed);
+    if (!result.valid) {
+        throw new Error(`Invalid plugin manifest:\n  - ${result.errors.join('\n  - ')}`);
+    }
+    return parsed;
+}
+// ============================================================================
+// Internal Validators
+// ============================================================================
+function validateName(name, errors, warnings) {
+    if (name.length > MAX_NAME_LENGTH) {
+        errors.push(`name must be ${MAX_NAME_LENGTH} characters or fewer`);
+    }
+    if (!VALID_NAME_REGEX.test(name)) {
+        errors.push('name must be lowercase alphanumeric with hyphens, starting with a letter');
+    }
+    // Check for non-ASCII characters
+    // eslint-disable-next-line no-control-regex
+    if (/[^\x00-\x7F]/.test(name)) {
+        errors.push('name must contain only ASCII characters');
+    }
+    for (const prefix of RESERVED_PREFIXES) {
+        if (name.startsWith(prefix)) {
+            errors.push(`name cannot start with reserved prefix "${prefix}"`);
+        }
+    }
+    // Warn on overly generic names
+    if (['plugin', 'test', 'tool'].includes(name)) {
+        warnings.push(`name "${name}" is very generic — consider a more descriptive name`);
+    }
+}
+function validateEntryPoint(entryPoint, errors) {
+    // Block path traversal
+    if (entryPoint.includes('..')) {
+        errors.push('entryPoint must not contain ".." (path traversal)');
+    }
+    // Block absolute paths
+    if (entryPoint.startsWith('/') || entryPoint.startsWith('\\')) {
+        errors.push('entryPoint must be a relative path');
+    }
+    // Must end in .js or .ts
+    if (!entryPoint.endsWith('.js') && !entryPoint.endsWith('.ts') && !entryPoint.endsWith('.mjs')) {
+        errors.push('entryPoint must end in .js, .ts, or .mjs');
+    }
+}
+//# sourceMappingURL=manifest.js.map

package/dist/plugins/resolver.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Agentic QE v3 - Plugin Dependency Resolver (IMP-09)
+ *
+ * DFS dependency resolution with cycle detection.
+ * Given a set of plugin manifests, produces a topologically-sorted
+ * load order where dependencies are loaded before dependents.
+ */
+import type { QEPluginManifest } from './manifest';
+export interface ResolvedPlugin {
+    manifest: QEPluginManifest;
+    /** Order index (0 = load first) */
+    order: number;
+}
+export interface ResolutionResult {
+    /** Plugins in dependency-safe load order */
+    ordered: ResolvedPlugin[];
+    /** Unresolvable dependencies (plugin -> missing deps) */
+    missing: Map<string, string[]>;
+}
+export declare class PluginResolver {
+    /**
+     * Resolve plugin load order via DFS topological sort.
+     *
+     * @param manifests - All available plugin manifests
+     * @returns Ordered list of plugins safe to load sequentially
+     * @throws Error if a dependency cycle is detected
+     */
+    resolve(manifests: QEPluginManifest[]): ResolutionResult;
+    /**
+     * Check if a specific plugin can be loaded given the currently loaded set.
+     */
+    canLoad(manifest: QEPluginManifest, loaded: Set<string>): {
+        canLoad: boolean;
+        missingDeps: string[];
+    };
+}
+//# sourceMappingURL=resolver.d.ts.map