@aiwg/cli 2026.8.0 → 2026.8.2

package/tools/agents/providers/copilot.mjs

@@ -0,0 +1,659 @@
+/**
+ * GitHub Copilot Provider
+ *
+ * Deploys agents in GitHub Copilot .agent.md format (Markdown with YAML frontmatter).
+ * Commands deploy as prompt files (.prompt.md) in .github/prompts/.
+ * Rules deploy as path-scoped instructions (.instructions.md) in .github/instructions/.
+ *
+ * Deployment paths:
+ *   - Agents: .github/agents/ (.agent.md)
+ *   - Commands: .github/prompts/ (.prompt.md)
+ *   - Skills: .github/skills/
+ *   - Rules: .github/instructions/ (.instructions.md)
+ *
+ * Special features:
+ *   - .agent.md format with YAML frontmatter + markdown body
+ *   - .prompt.md format for commands (invocable as /command in Copilot Chat)
+ *   - .instructions.md format with applyTo globs for path-scoped rules
+ *   - Tool mapping to Copilot built-in tools
+ *   - Creates copilot-instructions.md
+ */
+
+import realFs from 'fs';
+import { createRequire } from 'module';
+const _require = createRequire(import.meta.url);
+const staticModelCatalog = _require('../../../agentic/code/providers/model-catalog.v1.json');
+let fs;
+try { const gfs = _require('graceful-fs'); gfs.gracefulify(realFs); fs = realFs; } catch { fs = realFs; }
+import path from 'path';
+import {
+  ensureDir,
+  listMdFiles,
+  listMdFilesRecursive,
+  deployFiles,
+  inferAgentCategory,
+  toKebabCase,
+  initializeFrameworkWorkspace,
+  getAddonAgentFiles,
+  getAddonCommandFiles,
+  getAddonRuleFiles,
+  getAddonSkillDirs,
+  listSkillDirs,
+  deploySkillDir,
+  deploySkillsWithKernelRouting,
+  isKernelSkill,
+  pruneStaleAiwgSkills,
+  computeAllKernelNames,
+  normalizeDeploymentMode,
+  collectFrameworkArtifacts,
+  listOnDemandRuleFiles,
+  writeOnDemandRuleIndex,
+  cleanupOldRuleFiles,
+  filterCommandsAgainstSkills,
+  deploySoulCompanions,
+  loadRuntimeModelCatalog
+} from './base.mjs';
+const modelCatalog = loadRuntimeModelCatalog(staticModelCatalog);
+
+// ============================================================================
+// Provider Configuration
+// ============================================================================
+
+export const name = 'copilot';
+export const aliases = [];
+
+export const paths = {
+  agents: '.github/agents/',
+  commands: '.github/prompts/',
+  // Skills sequestered under .github/.aiwg/skills/ — index-driven discovery (#1212).
+  skills: '.github/.aiwg/skills/',
+  rules: '.github/instructions/'
+};
+
+// Kernel skills (always-loaded) deploy to the platform-native dir.
+export const kernelSkillsPath = '.github/skills/';
+
+export const support = {
+  agents: 'native',
+  commands: 'native',
+  skills: 'conventional',
+  rules: 'native'
+};
+
+export const capabilities = {
+  skills: true,
+  rules: true,
+  aggregatedOutput: false,
+  yamlFormat: false
+};
+
+// ============================================================================
+// Model Mapping
+// ============================================================================
+
+/**
+ * Map model shorthand to GitHub Copilot format.
+ * Resolve semantic AIWG roles through the current provider catalog.
+ */
+export function mapModel(originalModel, modelCfg, modelsConfig) {
+  const copilotModels = {
+    'opus': modelCatalog.providers.copilot.roles.reasoning.id,
+    'sonnet': modelCatalog.providers.copilot.roles.coding.id,
+    'haiku': modelCatalog.providers.copilot.roles.efficiency.id
+  };
+
+  // Handle override models first
+  if (modelCfg.reasoningModel || modelCfg.codingModel || modelCfg.efficiencyModel) {
+    const clean = (originalModel || 'sonnet').toLowerCase().replace(/['"]/g, '');
+    if (/opus/i.test(clean)) return modelCfg.reasoningModel || copilotModels.opus;
+    if (/haiku/i.test(clean)) return modelCfg.efficiencyModel || copilotModels.haiku;
+    return modelCfg.codingModel || copilotModels.sonnet;
+  }
+
+  const clean = (originalModel || 'sonnet').toLowerCase().replace(/['"]/g, '');
+
+  for (const [key, value] of Object.entries(copilotModels)) {
+    if (clean.includes(key)) return value;
+  }
+
+  return copilotModels.sonnet; // default
+}
+
+// ============================================================================
+// Tool Mapping
+// ============================================================================
+
+/**
+ * Get Copilot tools based on category and original tools.
+ * Uses Copilot's built-in tool names (search/codebase, edit, web/fetch, agent, terminal).
+ */
+export function getTools(category, toolsString) {
+  // Map AIWG tools to GitHub Copilot built-in tools
+  const toolMap = {
+    'Read': 'search/codebase',
+    'Write': 'edit',
+    'MultiEdit': 'edit',
+    'Edit': 'edit',
+    'Bash': 'terminal',
+    'WebFetch': 'web/fetch',
+    'Glob': 'search/codebase',
+    'Grep': 'search/codebase',
+    'Task': 'agent',
+    'Agent': 'agent'
+  };
+
+  // Default tools by category
+  const categoryDefaults = {
+    analysis: ['search/codebase', 'web/fetch'],
+    documentation: ['search/codebase', 'edit', 'web/fetch'],
+    planning: ['search/codebase', 'web/fetch'],
+    implementation: ['search/codebase', 'edit', 'terminal', 'web/fetch', 'agent']
+  };
+
+  // If tools specified, map them
+  if (toolsString) {
+    let originalTools = [];
+    if (toolsString.startsWith('[')) {
+      try {
+        originalTools = JSON.parse(toolsString);
+      } catch (e) {
+        originalTools = toolsString.replace(/[\[\]"']/g, '').split(/[,\s]+/).filter(Boolean);
+      }
+    } else {
+      originalTools = toolsString.split(/[,\s]+/).filter(Boolean);
+    }
+
+    const mappedTools = new Set();
+    for (const tool of originalTools) {
+      const cleanTool = tool.replace(/\(.*\)/, '').trim();
+      const mapped = toolMap[cleanTool];
+      if (mapped) mappedTools.add(mapped);
+    }
+
+    if (mappedTools.size > 0) {
+      return Array.from(mappedTools);
+    }
+  }
+
+  // Fall back to category defaults
+  return categoryDefaults[category] || categoryDefaults.implementation;
+}
+
+// ============================================================================
+// Content Transformation
+// ============================================================================
+
+/**
+ * Transform AIWG agent to GitHub Copilot .agent.md format.
+ * Output: YAML frontmatter with name, description, tools, model + markdown body (system prompt).
+ */
+export function transformAgent(srcPath, content, opts) {
+  const { modelsConfig = {} } = opts;
+
+  // Parse existing frontmatter
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!fmMatch) return content;
+
+  const [, frontmatter, body] = fmMatch;
+
+  // Extract metadata
+  const name = frontmatter.match(/name:\s*(.+)/)?.[1]?.trim();
+  const description = frontmatter.match(/description:\s*(.+)/)?.[1]?.trim();
+  const modelMatch = frontmatter.match(/model:\s*(.+)/)?.[1]?.trim();
+  const toolsMatch = frontmatter.match(/tools:\s*(.+)/)?.[1]?.trim();
+  const categoryMatch = frontmatter.match(/category:\s*(.+)/)?.[1]?.trim();
+
+  // Map model to Copilot format
+  const copilotModel = mapModel(modelMatch, opts, modelsConfig);
+
+  // Determine agent category
+  const category = categoryMatch || inferAgentCategory(name, body);
+
+  // Get Copilot-specific tools
+  const copilotTools = getTools(category, toolsMatch);
+
+  // Build YAML frontmatter
+  const fmLines = [
+    '---',
+    `name: ${name || 'aiwg-agent'}`,
+    `description: ${description || 'AIWG SDLC agent'}`
+  ];
+
+  if (copilotTools.length > 0) {
+    fmLines.push(`tools: [${copilotTools.map(t => `'${t}'`).join(', ')}]`);
+  }
+
+  fmLines.push(`model: ${copilotModel}`);
+  fmLines.push('---');
+
+  // Body is the system prompt (markdown)
+  const cleanBody = body.trim();
+  return fmLines.join('\n') + '\n\n' + cleanBody + '\n';
+}
+
+/**
+ * Transform AIWG command to GitHub Copilot .prompt.md format.
+ * Output: YAML frontmatter with name, description, model, tools + markdown body.
+ * Users invoke via /command-name in Copilot Chat.
+ */
+export function transformCommand(srcPath, content, opts) {
+  const { modelsConfig = {} } = opts;
+
+  // Parse existing frontmatter
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!fmMatch) {
+    // No frontmatter, create simple prompt format
+    const firstLine = content.split('\n')[0];
+    const description = firstLine.replace(/^#\s*/, '').trim() || 'AIWG command';
+    const cmdName = toKebabCase(description);
+
+    return `---\nname: ${cmdName}\ndescription: ${description}\nmodel: gpt-4o\n---\n\n${content.trim()}\n`;
+  }
+
+  const [, frontmatter, body] = fmMatch;
+
+  // Extract metadata
+  const description = frontmatter.match(/description:\s*(.+)/)?.[1]?.trim();
+  const argumentHint = frontmatter.match(/argument-hint:\s*(.+)/)?.[1]?.trim()?.replace(/^["']|["']$/g, '');
+  const modelMatch = frontmatter.match(/model:\s*(.+)/)?.[1]?.trim();
+  const toolsMatch = frontmatter.match(/(?:allowed-tools|tools):\s*(.+)/)?.[1]?.trim();
+  const cmdName = toKebabCase(description || 'aiwg-command');
+
+  // Map model
+  const copilotModel = mapModel(modelMatch, opts, modelsConfig);
+
+  // Map tools from allowed-tools
+  const copilotTools = getTools('implementation', toolsMatch);
+
+  // Build YAML frontmatter
+  const fmLines = [
+    '---',
+    `name: ${cmdName}`,
+    `description: ${description || 'AIWG command'}`
+  ];
+
+  if (copilotTools.length > 0) {
+    fmLines.push(`tools: [${copilotTools.map(t => `'${t}'`).join(', ')}]`);
+  }
+
+  fmLines.push(`model: ${copilotModel}`);
+
+  if (argumentHint) {
+    fmLines.push(`argument-hint: "${argumentHint}"`);
+  }
+
+  fmLines.push('---');
+
+  const cleanBody = body.trim();
+  return fmLines.join('\n') + '\n\n' + cleanBody + '\n';
+}
+
+/**
+ * Transform AIWG rule to GitHub Copilot .instructions.md format.
+ * Output: YAML frontmatter with name, description, applyTo + rule body.
+ */
+export function transformRule(srcPath, content, opts) {
+  // Rules may have frontmatter or be plain markdown
+  let frontmatter = '';
+  let body = content;
+
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (fmMatch) {
+    frontmatter = fmMatch[1];
+    body = fmMatch[2];
+  }
+
+  // Extract name from frontmatter or first heading
+  let name = frontmatter && frontmatter.match(/name:\s*(.+)/)?.[1]?.trim();
+  if (!name) {
+    const headingMatch = body.match(/^#\s+(.+)/m);
+    name = headingMatch ? headingMatch[1].trim() : path.basename(srcPath, '.md');
+  }
+
+  // Extract description from frontmatter or first bold line
+  let description = frontmatter && frontmatter.match(/description:\s*(.+)/)?.[1]?.trim();
+  if (!description) {
+    const scopeMatch = body.match(/\*\*(?:Scope|Summary)\*\*:\s*(.+)/);
+    description = scopeMatch ? scopeMatch[1].trim() : name;
+  }
+
+  // Derive applyTo from rule content or filename
+  const applyTo = deriveApplyTo(srcPath, body);
+
+  // Build instructions format
+  const fmLines = [
+    '---',
+    `name: ${name}`,
+    `description: ${description}`
+  ];
+
+  if (applyTo) {
+    fmLines.push(`applyTo: '${applyTo}'`);
+  }
+
+  fmLines.push('---');
+
+  const cleanBody = body.trim();
+  return fmLines.join('\n') + '\n\n' + cleanBody + '\n';
+}
+
+/**
+ * Derive applyTo glob patterns from rule content and filename.
+ */
+function deriveApplyTo(srcPath, body) {
+  const filename = path.basename(srcPath).toLowerCase();
+  const content = body.toLowerCase();
+
+  // Security rules apply to code files
+  if (filename.includes('security') || filename.includes('token') ||
+      content.includes('vulnerability') || content.includes('owasp')) {
+    return '**/*.{ts,js,mjs,cjs,py,go,java,rs}';
+  }
+
+  // Documentation rules apply to markdown
+  if (filename.includes('diagram') || filename.includes('documentation') ||
+      filename.includes('doc-') || content.includes('documentation artifact')) {
+    return '**/*.md';
+  }
+
+  // Agent/deployment rules apply to agent definitions
+  if (filename.includes('agent-deployment') || filename.includes('agent-')) {
+    return '**/*.{md,yaml,yml}';
+  }
+
+  // Code style/implementation rules
+  if (filename.includes('code') || filename.includes('implementation') ||
+      filename.includes('test') || filename.includes('lint')) {
+    return '**/*.{ts,js,mjs,cjs}';
+  }
+
+  // Default: apply to all files
+  return '**/*';
+}
+
+// ============================================================================
+// Deployment Functions
+// ============================================================================
+
+/**
+ * Deploy agents to .github/agents/ as .agent.md files
+ */
+export function deployAgents(agentFiles, targetDir, opts) {
+  const destDir = path.join(targetDir, paths.agents);
+  ensureDir(destDir, opts.dryRun);
+  return deployFiles(agentFiles, destDir, { ...opts, fileExtension: '.agent.md', injectPlatform: true }, transformAgent);
+}
+
+/**
+ * Deploy commands to .github/prompts/ as .prompt.md files
+ */
+export function deployCommands(commandFiles, targetDir, opts) {
+  const destDir = path.join(targetDir, paths.commands);
+  ensureDir(destDir, opts.dryRun);
+  return deployFiles(commandFiles, destDir, { ...opts, fileExtension: '.prompt.md' }, transformCommand);
+}
+
+/**
+ * Deploy skills with kernel-vs-standard routing (#1212/#1216) plus
+ * .agents/skills/ cross-agent compatibility (PUW-012 #1113).
+ *   - kernel skills → .github/skills/         (platform-native, always-loaded)
+ *   - standard      → .github/.aiwg/skills/   (index-discoverable)
+ *   - cross-agent compatibility mirror is preserved at .agents/skills/.
+ */
+export function deploySkills(skillDirs, targetDir, opts) {
+  const standardDestDir = path.join(targetDir, paths.skills);
+  const kernelDestDir = path.join(targetDir, kernelSkillsPath);
+  deploySkillsWithKernelRouting(skillDirs, standardDestDir, kernelDestDir, opts);
+
+  // Cross-agent compatibility: .agents/skills/ — honors #1217 no-copy
+  // default. Filter to kernel-only unless operator opts in via env var.
+  const copyStandardSkills = opts?.copyStandardSkills === true;
+  const crossAgentSkills = copyStandardSkills
+    ? skillDirs
+    : skillDirs.filter(d => isKernelSkill(d));
+  if (crossAgentSkills.length > 0) {
+    const crossAgentDir = path.join(targetDir, '.agents', 'skills');
+    ensureDir(crossAgentDir, opts.dryRun);
+    if (!opts.dryRun) {
+      console.log(`Deploying cross-agent skills to ${path.relative(process.cwd(), crossAgentDir)}...`);
+    } else {
+      console.log(`[dry-run] Would deploy cross-agent skills to .agents/skills/`);
+    }
+    for (const skillDir of crossAgentSkills) {
+      deploySkillDir(skillDir, crossAgentDir, opts);
+    }
+  }
+}
+
+/**
+ * Deploy rules to .github/instructions/ as .instructions.md files
+ */
+export function deployRules(ruleFiles, targetDir, opts) {
+  const destDir = path.join(targetDir, paths.rules);
+  ensureDir(destDir, opts.dryRun);
+  cleanupOldRuleFiles(destDir, opts);
+  return deployFiles(ruleFiles, destDir, { ...opts, fileExtension: '.instructions.md' }, transformRule);
+}
+
+// ============================================================================
+// copilot-instructions.md
+// ============================================================================
+
+/**
+ * Create copilot-instructions.md from template
+ */
+export function createCopilotInstructions(target, srcRoot, dryRun) {
+  const templatePath = path.join(srcRoot, 'agentic', 'code', 'frameworks', 'sdlc-complete', 'templates', 'copilot', 'copilot-instructions.md.aiwg-template');
+  const githubDir = path.join(target, '.github');
+  const destPath = path.join(githubDir, 'copilot-instructions.md');
+
+  if (!fs.existsSync(templatePath)) {
+    console.warn(`Copilot instructions template not found at ${templatePath}`);
+    return;
+  }
+
+  const template = fs.readFileSync(templatePath, 'utf8');
+
+  // Ensure .github directory exists
+  if (!dryRun && !fs.existsSync(githubDir)) {
+    fs.mkdirSync(githubDir, { recursive: true });
+  }
+
+  if (fs.existsSync(destPath)) {
+    const existing = fs.readFileSync(destPath, 'utf8');
+
+    if (existing.includes('<!-- AIWG SDLC Framework Integration -->') ||
+        existing.includes('## AIWG SDLC Framework')) {
+      console.log('copilot-instructions.md already contains AIWG section, skipping');
+      return;
+    }
+
+    const markerIndex = template.indexOf('<!-- AIWG SDLC Framework Integration -->');
+    const aiwgSection = markerIndex !== -1 ? template.slice(markerIndex) : template;
+    const combined = existing.trimEnd() + '\n\n---\n\n' + aiwgSection.trim() + '\n';
+
+    if (dryRun) {
+      console.log(`[dry-run] Would update existing copilot-instructions.md with AIWG section`);
+    } else {
+      fs.writeFileSync(destPath, combined, 'utf8');
+      console.log('Updated copilot-instructions.md with AIWG SDLC framework section');
+    }
+  } else {
+    if (dryRun) {
+      console.log(`[dry-run] Would create copilot-instructions.md from template`);
+    } else {
+      fs.writeFileSync(destPath, template, 'utf8');
+      console.log('Created copilot-instructions.md from template');
+    }
+  }
+}
+
+// ============================================================================
+// Post-Deployment
+// ============================================================================
+
+export async function postDeploy(targetDir, opts) {
+  initializeFrameworkWorkspace(targetDir, opts.mode, opts.dryRun, opts.srcRoot);
+
+  // Create copilot-instructions.md
+  createCopilotInstructions(targetDir, opts.srcRoot, opts.dryRun);
+}
+
+// ============================================================================
+// File Extension
+// ============================================================================
+
+export function getFileExtension(type) {
+  switch (type) {
+    case 'agent': return '.agent.md';
+    case 'command': return '.prompt.md';
+    case 'rule': return '.instructions.md';
+    default: return '.md';
+  }
+}
+
+// ============================================================================
+// Main Deploy Function
+// ============================================================================
+
+export async function deploy(opts) {
+  const {
+    srcRoot,
+    target,
+    mode,
+    deployCommands: shouldDeployCommands,
+    deploySkills: shouldDeploySkills,
+    deployRules: shouldDeployRules,
+    commandsOnly,
+    skillsOnly,
+    rulesOnly,
+    dryRun
+  } = opts;
+
+  console.log(`\n=== GitHub Copilot Provider ===`);
+  console.log(`Target: ${target}`);
+  console.log(`Mode: ${mode}`);
+
+  const agentFiles = [];
+  const commandFiles = [];
+  const skillDirs = [];
+  const ruleFiles = [];
+  const normalizedMode = normalizeDeploymentMode(mode);
+
+  // All addons (dynamically discovered)
+  if (normalizedMode === 'general' || normalizedMode === 'sdlc' || normalizedMode === 'both' || normalizedMode === 'all') {
+    agentFiles.push(...getAddonAgentFiles(srcRoot));
+
+    if (shouldDeployCommands || commandsOnly) {
+      commandFiles.push(...getAddonCommandFiles(srcRoot));
+    }
+
+    if (shouldDeploySkills || skillsOnly) {
+      skillDirs.push(...getAddonSkillDirs(srcRoot));
+  
+    // Holistic post-deploy cleanup of stale AIWG-managed kernel
+    // skills (renamed/removed sources). Uses the global kernel set
+    // (computeAllKernelNames walks all source frameworks/addons),
+    // not just this-call's skillDirs, because aiwg use invokes
+    // deploy-agents.mjs multiple times.
+    {
+      const _kernelDestDir = path.isAbsolute(kernelSkillsPath)
+        ? kernelSkillsPath
+        : path.join(target, kernelSkillsPath);
+      pruneStaleAiwgSkills(_kernelDestDir, computeAllKernelNames(srcRoot), opts);
+    }
+  }
+
+    if (shouldDeployRules || rulesOnly) {
+      ruleFiles.push(...getAddonRuleFiles(srcRoot));
+    }
+  }
+
+  const frameworkArtifacts = collectFrameworkArtifacts(srcRoot, normalizedMode, {
+    includeAgents: true,
+    includeCommands: shouldDeployCommands || commandsOnly,
+    includeSkills: shouldDeploySkills || skillsOnly,
+    includeRules: shouldDeployRules || rulesOnly,
+    recursiveCommands: true,
+    consolidatedSdlcRules: true
+  });
+  agentFiles.push(...frameworkArtifacts.agents);
+  const soulFiles = [...(frameworkArtifacts.souls || [])];
+  commandFiles.push(...frameworkArtifacts.commands);
+  skillDirs.push(...frameworkArtifacts.skills);
+  ruleFiles.push(...frameworkArtifacts.rules);
+
+  // Deploy
+  if (!commandsOnly && !skillsOnly && !rulesOnly) {
+    console.log(`\nDeploying ${agentFiles.length} agents (.agent.md format)...`);
+    deployAgents(agentFiles, target, opts);
+
+    // Deploy soul companion files alongside agents
+    if (soulFiles.length > 0) {
+      const destDir = path.join(target, paths.agents);
+      console.log(`\nDeploying ${soulFiles.length} soul files...`);
+      deploySoulCompanions(soulFiles, destDir, opts);
+    }
+  }
+
+  // Filter commands that collide with skills (skills take precedence)
+  const filteredCommands = (shouldDeploySkills || skillsOnly)
+    ? filterCommandsAgainstSkills(commandFiles, skillDirs)
+    : commandFiles;
+
+  if (shouldDeployCommands || commandsOnly) {
+    console.log(`\nDeploying ${filteredCommands.length} commands (.prompt.md format)...`);
+    deployCommands(filteredCommands, target, opts);
+  }
+
+  if (shouldDeploySkills || skillsOnly) {
+    console.log(`\nDeploying ${skillDirs.length} skills...`);
+    deploySkills(skillDirs, target, opts);
+  }
+
+  if (shouldDeployRules || rulesOnly) {
+    console.log(`\nDeploying ${ruleFiles.length} rules...`);
+    deployRules(ruleFiles, target, opts);
+
+    // On-demand index (#1675): list the MEDIUM/LOW rules tier-gated out of the
+    // always-on set so agents can fetch them via `aiwg show rule`.
+    const onDemandCount = writeOnDemandRuleIndex(
+      path.join(target, paths.rules),
+      listOnDemandRuleFiles(srcRoot),
+      opts,
+    );
+    if (onDemandCount > 0) {
+      console.log(`  On-demand rules (not inlined): ${onDemandCount} → RULES-ONDEMAND.md`);
+    }
+  }
+
+  await postDeploy(target, opts);
+
+  console.log('\n=== Copilot deployment complete ===\n');
+}
+
+// ============================================================================
+// Default Export
+// ============================================================================
+
+export default {
+  name,
+  aliases,
+  paths,
+  kernelSkillsPath,
+  support,
+  capabilities,
+  transformAgent,
+  transformCommand,
+  transformRule,
+  mapModel,
+  getTools,
+  deployAgents,
+  deployCommands,
+  deploySkills,
+  deployRules,
+  createCopilotInstructions,
+  postDeploy,
+  getFileExtension,
+  deploy
+};