@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/activity-log/types.js

@@ -0,0 +1,50 @@
+/**
+ * Activity Log Types
+ *
+ * Type definitions for `.aiwg/activity.log` entries. The wire format is
+ * frozen by the activity-log rule (`agentic/code/addons/aiwg-utils/rules/activity-log.md`):
+ *
+ *     ## [YYYY-MM-DD HH:MM] <operation> | <summary>
+ *
+ * @issue #934
+ * @issue #964
+ */
+/**
+ * Valid operation tokens. The activity-log rule freezes this set;
+ * additions require updating the rule too.
+ */
+export const ACTIVITY_OPERATIONS = [
+    'ingest',
+    'create',
+    'update',
+    'delete',
+    'query',
+    'lint',
+    'deploy',
+    'archive',
+    'promote',
+];
+export function isActivityOperation(s) {
+    return ACTIVITY_OPERATIONS.includes(s);
+}
+/**
+ * Format an entry as the canonical wire line (no trailing newline).
+ *
+ * Wire format: `## [YYYY-MM-DD HH:MM] <operation> | <summary>`
+ */
+export function formatEntry(entry) {
+    const ts = formatUtcTimestamp(entry.timestamp);
+    return `## [${ts}] ${entry.operation} | ${entry.summary}`;
+}
+/**
+ * Format a Date as the canonical "YYYY-MM-DD HH:MM" UTC timestamp.
+ */
+export function formatUtcTimestamp(d) {
+    const yyyy = d.getUTCFullYear();
+    const mm = String(d.getUTCMonth() + 1).padStart(2, '0');
+    const dd = String(d.getUTCDate()).padStart(2, '0');
+    const HH = String(d.getUTCHours()).padStart(2, '0');
+    const MM = String(d.getUTCMinutes()).padStart(2, '0');
+    return `${yyyy}-${mm}-${dd} ${HH}:${MM}`;
+}
+//# sourceMappingURL=types.js.map

package/dist/src/agents/agent-deployer.js

@@ -0,0 +1,367 @@
+/**
+ * Agent Deployer
+ *
+ * Core deployment engine for multi-platform agent deployment.
+ *
+ * @implements @.aiwg/requirements/use-cases/UC-002-deploy-sdlc-framework.md
+ * @architecture @.aiwg/architecture/software-architecture-doc.md - Section 2.1 CLI Entry Point
+ * @nfr @.aiwg/requirements/nfr-modules/performance.md - NFR-PERF-002 (<10s deployment)
+ * @tests @test/unit/agents/agent-deployer.test.ts
+ * @depends @src/agents/agent-validator.ts
+ * @depends @src/agents/agent-packager.ts
+ * @agent-catalog @agentic/code/frameworks/sdlc-complete/agents/
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { existsSync } from 'fs';
+import { AgentValidator } from './agent-validator.js';
+import { AgentPackager } from './agent-packager.js';
+import { getProviderDefinition } from '../providers/provider-definitions.js';
+export class AgentDeployer {
+    validator;
+    packager;
+    constructor() {
+        this.validator = new AgentValidator();
+        this.packager = new AgentPackager();
+    }
+    /**
+     * Deploy agents to target platform
+     */
+    async deploy(target, options = {}) {
+        const result = {
+            platform: target.platform,
+            projectPath: target.projectPath,
+            deployed: [],
+            skipped: [],
+            failed: [],
+            totalAgents: 0,
+            deployedCount: 0,
+            skippedCount: 0,
+            failedCount: 0,
+        };
+        try {
+            // Load agents from default locations
+            const agents = await this.loadAgents();
+            result.totalAgents = agents.length;
+            if (options.verbose) {
+                console.log(`Loaded ${agents.length} agents`);
+            }
+            // Filter agents by options
+            const filteredAgents = this.filterAgents(agents, options);
+            if (options.verbose) {
+                console.log(`Deploying ${filteredAgents.length} agents after filtering`);
+            }
+            // Validate agents
+            const validationResults = await this.validator.validateBatch(filteredAgents);
+            const validAgents = validationResults
+                .filter((r) => r.valid)
+                .map((r) => r.agent);
+            // Report validation failures
+            const invalidAgents = validationResults.filter((r) => !r.valid);
+            for (const invalid of invalidAgents) {
+                result.failed.push({
+                    agent: invalid.agent,
+                    error: `Validation failed: ${invalid.issues
+                        .filter((i) => i.type === 'error')
+                        .map((i) => i.message)
+                        .join(', ')}`,
+                });
+                result.failedCount++;
+            }
+            // Create backup if requested
+            if (options.backup && !options.dryRun) {
+                result.backupPath = await this.createBackup(target);
+                if (options.verbose) {
+                    console.log(`Backup created: ${result.backupPath}`);
+                }
+            }
+            // Deploy each valid agent
+            for (const agent of validAgents) {
+                try {
+                    const deployResult = await this.deployAgent(agent, target, options);
+                    if (deployResult.success) {
+                        result.deployed.push(deployResult);
+                        result.deployedCount++;
+                    }
+                    else {
+                        result.skipped.push(agent);
+                        result.skippedCount++;
+                    }
+                }
+                catch (error) {
+                    result.failed.push({
+                        agent,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    result.failedCount++;
+                }
+            }
+        }
+        catch (error) {
+            throw new Error(`Deployment failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return result;
+    }
+    /**
+     * Deploy agents to multiple targets
+     */
+    async deployBatch(targets, options = {}) {
+        const results = new Map();
+        for (const target of targets) {
+            const key = `${target.platform}:${target.projectPath}`;
+            const result = await this.deploy(target, options);
+            results.set(key, result);
+        }
+        return results;
+    }
+    /**
+     * Load agents from source directories
+     */
+    async loadAgents(sourcePath) {
+        const agents = [];
+        const searchPaths = [];
+        if (sourcePath) {
+            searchPaths.push(sourcePath);
+        }
+        else {
+            // Default search paths
+            const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+            const aiwgPath = path.join(homeDir, '.local/share/ai-writing-guide/agents');
+            const localAgents = path.join(process.cwd(), 'agents');
+            const sdlcAgents = path.join(homeDir, '.local/share/ai-writing-guide/agentic/code/frameworks/sdlc-complete/agents');
+            if (existsSync(aiwgPath))
+                searchPaths.push(aiwgPath);
+            if (existsSync(sdlcAgents))
+                searchPaths.push(sdlcAgents);
+            if (existsSync(localAgents))
+                searchPaths.push(localAgents);
+        }
+        // Load agents from all search paths
+        for (const searchPath of searchPaths) {
+            const pathAgents = await this.loadAgentsFromPath(searchPath);
+            agents.push(...pathAgents);
+        }
+        // Remove duplicates by name (prefer earlier paths)
+        const uniqueAgents = new Map();
+        for (const agent of agents) {
+            if (!uniqueAgents.has(agent.metadata.name)) {
+                uniqueAgents.set(agent.metadata.name, agent);
+            }
+        }
+        return Array.from(uniqueAgents.values());
+    }
+    /**
+     * Load agents from a specific path
+     */
+    async loadAgentsFromPath(dirPath) {
+        const agents = [];
+        if (!existsSync(dirPath)) {
+            return agents;
+        }
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name.endsWith('.md')) {
+                // Skip template and README files
+                if (entry.name === 'agent-template.md' ||
+                    entry.name === 'README.md' ||
+                    entry.name === 'manifest.md') {
+                    continue;
+                }
+                const filePath = path.join(dirPath, entry.name);
+                try {
+                    const agent = await this.parseAgentFile(filePath);
+                    if (agent) {
+                        agents.push(agent);
+                    }
+                }
+                catch (error) {
+                    // Skip files that fail to parse
+                    console.warn(`Warning: Failed to parse ${filePath}: ${error}`);
+                }
+            }
+        }
+        return agents;
+    }
+    /**
+     * Parse agent file
+     */
+    async parseAgentFile(filePath) {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const metadata = this.parseFrontmatter(content);
+        if (!metadata.name) {
+            // Use filename as fallback
+            metadata.name = path.basename(filePath, '.md');
+        }
+        // Load agent even if description is missing - validation will catch it
+        // Extract content (remove frontmatter)
+        const contentWithoutFrontmatter = this.removeFrontmatter(content);
+        return {
+            metadata,
+            content: contentWithoutFrontmatter,
+            filePath,
+            fileName: path.basename(filePath),
+        };
+    }
+    /**
+     * Parse YAML frontmatter
+     */
+    parseFrontmatter(content) {
+        const metadata = {};
+        // Match frontmatter between --- delimiters
+        const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+        if (!frontmatterMatch) {
+            return metadata;
+        }
+        const frontmatter = frontmatterMatch[1];
+        const lines = frontmatter.split('\n');
+        for (const line of lines) {
+            const match = line.match(/^(\w+):\s*(.+)$/);
+            if (match) {
+                const key = match[1].trim();
+                const value = match[2].trim();
+                switch (key) {
+                    case 'name':
+                        metadata.name = value;
+                        break;
+                    case 'description':
+                        metadata.description = value;
+                        break;
+                    case 'category':
+                        metadata.category = value;
+                        break;
+                    case 'model':
+                        metadata.model = value;
+                        break;
+                    case 'version':
+                        metadata.version = value;
+                        break;
+                    case 'tools':
+                        metadata.tools = value.split(',').map((t) => t.trim());
+                        break;
+                    case 'dependencies':
+                        metadata.dependencies = value.split(',').map((d) => d.trim());
+                        break;
+                }
+            }
+        }
+        return metadata;
+    }
+    /**
+     * Remove frontmatter from content
+     */
+    removeFrontmatter(content) {
+        const match = content.match(/^---\s*\n[\s\S]*?\n---\s*\n([\s\S]*)$/);
+        return match ? match[1].trim() : content;
+    }
+    /**
+     * Filter agents by options
+     */
+    filterAgents(agents, options) {
+        let filtered = agents;
+        // Filter by category
+        if (options.categories && options.categories.length > 0) {
+            filtered = filtered.filter((agent) => agent.metadata.category &&
+                options.categories.includes(agent.metadata.category));
+        }
+        // Filter by name
+        if (options.agentNames && options.agentNames.length > 0) {
+            filtered = filtered.filter((agent) => options.agentNames.includes(agent.metadata.name));
+        }
+        return filtered;
+    }
+    /**
+     * Deploy a single agent
+     */
+    async deployAgent(agent, target, options) {
+        const agentsDir = this.getAgentsDirectory(target);
+        const fileName = this.packager.getFileName(agent, target.platform);
+        const targetPath = path.join(agentsDir, fileName);
+        // Check if file exists and force is not set
+        if (existsSync(targetPath) && !options.force) {
+            return {
+                agent,
+                success: false,
+                targetPath,
+                error: 'File exists (use --force to overwrite)',
+            };
+        }
+        // Dry run: don't write files
+        if (options.dryRun) {
+            return {
+                agent,
+                success: true,
+                targetPath,
+            };
+        }
+        // Package agent for platform
+        const packaged = await this.packager.package(agent, target.platform);
+        // Create directory if needed
+        await fs.mkdir(agentsDir, { recursive: true });
+        // Write file
+        await fs.writeFile(targetPath, packaged.content, 'utf-8');
+        return {
+            agent,
+            success: true,
+            targetPath,
+        };
+    }
+    /**
+     * Get agents directory for platform
+     */
+    getAgentsDirectory(target) {
+        if (target.agentsPath) {
+            return path.resolve(target.projectPath, target.agentsPath);
+        }
+        const definition = getProviderDefinition(target.platform);
+        const agentsPath = definition?.paths.artifacts.agents ?? '';
+        return path.resolve(target.projectPath, agentsPath);
+    }
+    /**
+     * Create backup of existing agents
+     */
+    async createBackup(target) {
+        const agentsDir = this.getAgentsDirectory(target);
+        if (!existsSync(agentsDir)) {
+            return ''; // Nothing to backup
+        }
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const backupPath = path.join(target.projectPath, `.agents-backup-${timestamp}`);
+        await fs.cp(agentsDir, backupPath, { recursive: true });
+        return backupPath;
+    }
+    /**
+     * Rollback to previous backup
+     */
+    async rollback(backupPath, target) {
+        if (!existsSync(backupPath)) {
+            throw new Error(`Backup not found: ${backupPath}`);
+        }
+        const agentsDir = this.getAgentsDirectory(target);
+        // Remove current agents directory
+        if (existsSync(agentsDir)) {
+            await fs.rm(agentsDir, { recursive: true, force: true });
+        }
+        // Restore from backup
+        await fs.cp(backupPath, agentsDir, { recursive: true });
+    }
+    /**
+     * Get installed version of an agent
+     */
+    async getInstalledVersion(agentName, target) {
+        const agentsDir = this.getAgentsDirectory(target);
+        const fileName = `${agentName}${this.packager.getFileExtension(target.platform)}`;
+        const filePath = path.join(agentsDir, fileName);
+        if (!existsSync(filePath)) {
+            return null;
+        }
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            const metadata = this.parseFrontmatter(content);
+            return metadata.version || null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=agent-deployer.js.map

package/dist/src/agents/agent-packager.js

@@ -0,0 +1,271 @@
+/**
+ * Agent Packager
+ *
+ * Converts agents to platform-specific formats.
+ */
+import { getProviderDefinition } from '../providers/provider-definitions.js';
+export class AgentPackager {
+    getAgentFormatAdapters() {
+        return {
+            'claude-markdown': (agent) => this.convertToClaudeFormat(agent),
+            'cursor-json': (agent) => this.convertToCursorFormat(agent),
+            'codex-markdown': (agent) => this.convertToCodexFormat(agent),
+            'copilot-markdown': (agent) => this.convertToGenericFormat(agent),
+            'factory-droid': (agent) => this.convertToClaudeFormat(agent),
+            'generic-markdown': (agent) => this.convertToGenericFormat(agent),
+            'windsurf-markdown': (agent) => this.convertToWindsurfFormat(agent),
+        };
+    }
+    /**
+     * Package agent for target platform
+     */
+    async package(agent, platform) {
+        const definition = getProviderDefinition(platform);
+        if (!definition) {
+            throw new Error(`Unknown platform: ${platform}`);
+        }
+        const adapterKey = definition.adapters.agentFormat;
+        const adapter = this.getAgentFormatAdapters()[adapterKey];
+        if (!adapter) {
+            throw new Error(`Unknown agent format adapter '${adapterKey}' for platform: ${platform}`);
+        }
+        return {
+            agent,
+            content: adapter(agent),
+            format: definition.id,
+        };
+    }
+    /**
+     * Convert to Claude Code format (.md with YAML frontmatter)
+     */
+    convertToClaudeFormat(agent) {
+        const { metadata, content } = agent;
+        const lines = [];
+        // Add frontmatter
+        lines.push('---');
+        lines.push(`name: ${metadata.name}`);
+        lines.push(`description: ${metadata.description}`);
+        if (metadata.model) {
+            lines.push(`model: ${metadata.model}`);
+        }
+        if (metadata.modelRole) {
+            lines.push(`model-role: ${metadata.modelRole}`);
+        }
+        if (metadata.modelTier) {
+            lines.push(`model-tier: ${metadata.modelTier}`);
+        }
+        if (metadata.tools && metadata.tools.length > 0) {
+            lines.push(`tools: ${metadata.tools.join(', ')}`);
+        }
+        if (metadata.category) {
+            lines.push(`category: ${metadata.category}`);
+        }
+        if (metadata.version) {
+            lines.push(`version: ${metadata.version}`);
+        }
+        if (metadata.dependencies && metadata.dependencies.length > 0) {
+            lines.push(`dependencies: ${metadata.dependencies.join(', ')}`);
+        }
+        lines.push('---');
+        lines.push('');
+        // Add content
+        lines.push(content);
+        return lines.join('\n');
+    }
+    /**
+     * Convert to Cursor format (JSON-based)
+     */
+    convertToCursorFormat(agent) {
+        const { metadata, content } = agent;
+        // Cursor uses JSON format with lowercase tool names
+        const tools = metadata.tools?.map((t) => t.toLowerCase()) || [];
+        const cursorAgent = {
+            name: metadata.name,
+            description: metadata.description,
+            prompt: content,
+            tools,
+            ...(metadata.model && { model: metadata.model }),
+            ...(metadata.modelRole && { modelRole: metadata.modelRole }),
+            ...(metadata.modelTier && { modelTier: metadata.modelTier }),
+            ...(metadata.category && { category: metadata.category }),
+            ...(metadata.version && { version: metadata.version }),
+            ...(metadata.dependencies && { dependencies: metadata.dependencies }),
+        };
+        return JSON.stringify(cursorAgent, null, 2);
+    }
+    /**
+     * Convert to OpenAI Codex format (YAML-based with specific structure)
+     */
+    convertToCodexFormat(agent) {
+        const { metadata, content } = agent;
+        const lines = [];
+        // Codex uses YAML frontmatter similar to Claude
+        lines.push('---');
+        lines.push(`agent_name: ${metadata.name}`);
+        lines.push(`description: ${metadata.description}`);
+        if (metadata.tools && metadata.tools.length > 0) {
+            lines.push('capabilities:');
+            for (const tool of metadata.tools) {
+                lines.push(`  - ${tool.toLowerCase()}`);
+            }
+        }
+        if (metadata.model) {
+            lines.push(`preferred_model: ${metadata.model}`);
+        }
+        if (metadata.modelRole) {
+            lines.push(`model-role: ${metadata.modelRole}`);
+        }
+        if (metadata.modelTier) {
+            lines.push(`model-tier: ${metadata.modelTier}`);
+        }
+        if (metadata.category) {
+            lines.push(`category: ${metadata.category}`);
+        }
+        if (metadata.version) {
+            lines.push(`version: ${metadata.version}`);
+        }
+        lines.push('---');
+        lines.push('');
+        // Add system prompt header
+        lines.push('# System Instructions');
+        lines.push('');
+        lines.push(content);
+        return lines.join('\n');
+    }
+    /**
+     * Convert to generic format (plain markdown with minimal frontmatter)
+     */
+    convertToGenericFormat(agent) {
+        const { metadata, content } = agent;
+        const lines = [];
+        // Minimal YAML frontmatter
+        lines.push('---');
+        lines.push(`name: ${metadata.name}`);
+        lines.push(`description: ${metadata.description}`);
+        if (metadata.version) {
+            lines.push(`version: ${metadata.version}`);
+        }
+        lines.push('---');
+        lines.push('');
+        // Add metadata as comments
+        lines.push('<!--');
+        if (metadata.category) {
+            lines.push(`Category: ${metadata.category}`);
+        }
+        if (metadata.model) {
+            lines.push(`Preferred Model: ${metadata.model}`);
+        }
+        if (metadata.modelRole) {
+            lines.push(`Model Role: ${metadata.modelRole}`);
+        }
+        if (metadata.modelTier) {
+            lines.push(`Model Tier: ${metadata.modelTier}`);
+        }
+        if (metadata.tools && metadata.tools.length > 0) {
+            lines.push(`Tools: ${metadata.tools.join(', ')}`);
+        }
+        if (metadata.dependencies && metadata.dependencies.length > 0) {
+            lines.push(`Dependencies: ${metadata.dependencies.join(', ')}`);
+        }
+        lines.push('-->');
+        lines.push('');
+        // Add content
+        lines.push(content);
+        return lines.join('\n');
+    }
+    /**
+     * Convert to Windsurf format (plain markdown, no YAML frontmatter)
+     *
+     * Windsurf uses AGENTS.md for directory-scoped instructions.
+     * Individual agent definitions use clean markdown sections.
+     */
+    convertToWindsurfFormat(agent) {
+        const { metadata, content } = agent;
+        const lines = [];
+        // Windsurf prefers clean markdown without YAML frontmatter
+        lines.push(`### ${metadata.name}`);
+        lines.push('');
+        // Only add description if present
+        if (metadata.description) {
+            lines.push(`> ${metadata.description}`);
+            lines.push('');
+        }
+        // Include capabilities in a structured way
+        if (metadata.tools && metadata.tools.length > 0) {
+            lines.push('<capabilities>');
+            for (const tool of metadata.tools) {
+                lines.push(`- ${tool}`);
+            }
+            lines.push('</capabilities>');
+            lines.push('');
+        }
+        // Add model info if present
+        if (metadata.model) {
+            lines.push(`**Model**: ${metadata.model}`);
+            lines.push('');
+        }
+        if (metadata.modelRole || metadata.modelTier) {
+            lines.push(`**Model Policy**: ${metadata.modelRole ?? 'coding'}/${metadata.modelTier ?? 'standard'}`);
+            lines.push('');
+        }
+        // Add the agent's system instructions
+        lines.push(content);
+        return lines.join('\n');
+    }
+    /**
+     * Get file extension for platform
+     */
+    getFileExtension(platform) {
+        return getProviderDefinition(platform)?.smithPaths.fileExtension ?? '.md';
+    }
+    /**
+     * Get filename for agent
+     */
+    getFileName(agent, platform) {
+        const ext = this.getFileExtension(platform);
+        return `${agent.metadata.name}${ext}`;
+    }
+    /**
+     * Package multiple agents
+     */
+    async packageBatch(agents, platform) {
+        const packaged = [];
+        for (const agent of agents) {
+            packaged.push(await this.package(agent, platform));
+        }
+        return packaged;
+    }
+    /**
+     * Create combined AGENTS.md file (for platforms that support it)
+     */
+    async createCombinedFile(agents, platform) {
+        const lines = [];
+        lines.push('# Available Agents');
+        lines.push('');
+        lines.push(`Platform: ${platform}`);
+        lines.push(`Total Agents: ${agents.length}`);
+        lines.push('');
+        // Table of contents
+        lines.push('## Table of Contents');
+        lines.push('');
+        for (const agent of agents) {
+            lines.push(`- [${agent.metadata.name}](#${agent.metadata.name.replace(/-/g, '')})`);
+        }
+        lines.push('');
+        // Individual agents
+        for (let i = 0; i < agents.length; i++) {
+            const agent = agents[i];
+            const packaged = await this.package(agent, platform);
+            if (i > 0) {
+                lines.push('');
+                lines.push('---');
+                lines.push('');
+            }
+            lines.push(`## ${agent.metadata.name}`);
+            lines.push('');
+            lines.push(packaged.content);
+        }
+        return lines.join('\n');
+    }
+}
+//# sourceMappingURL=agent-packager.js.map