ac-framework 1.1.0 → 1.3.0

package/src/commands/init.js

@@ -1,39 +1,30 @@
-import { readdir, cp, access, rm } from 'node:fs/promises';
-import { join, resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
 import gradient from 'gradient-string';
 import inquirer from 'inquirer';
-import { DESCRIPTIONS, formatFolderName, sleep } from '../utils/helpers.js';
+import { DESCRIPTIONS, ASSISTANT_ICONS, BUNDLED, ALWAYS_INSTALL } from '../config/constants.js';
+import { IDE_MD_MAP, AVAILABLE_MD_FILES, MD_DESCRIPTIONS } from '../config/ide-mapping.js';
+import { formatFolderName, sleep } from '../utils/helpers.js';
+import { detectIDE } from '../services/detector.js';
+import {
+  getSelectableModules,
+  expandWithBundled,
+  existsInTarget,
+  copyModule,
+  copyMdFile,
+} from '../services/installer.js';
 import {
   matrixRain,
   scanAnimation,
   animatedSeparator,
   revealList,
-  progressBar,
   installWithAnimation,
   celebrateSuccess,
   showFailureSummary,
   stepHeader,
 } from '../ui/animations.js';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
 const acGradient = gradient(['#6C5CE7', '#00CEC9', '#0984E3']);
 
-const ALWAYS_INSTALL = ['openspec'];
-
-async function getFrameworkFolders() {
-  const frameworkPath = resolve(__dirname, '../../framework');
-  const entries = await readdir(frameworkPath, { withFileTypes: true });
-
-  return entries
-    .filter((entry) => entry.isDirectory() && !ALWAYS_INSTALL.includes(entry.name))
-    .map((entry) => entry.name)
-    .sort((a, b) => a.localeCompare(b));
-}
-
 function buildChoices(folders) {
   const choices = [];
 
@@ -46,7 +37,7 @@ function buildChoices(folders) {
   for (const folder of folders) {
     const desc = DESCRIPTIONS[folder] || '';
     const displayName = formatFolderName(folder);
-    const icon = getAssistantIcon(folder);
+    const icon = ASSISTANT_ICONS[folder] || '◦';
     const label =
       `${chalk.hex('#636E72')(icon)} ${chalk.hex('#DFE6E9').bold(displayName)}` +
       (desc ? chalk.hex('#636E72')(` · ${desc}`) : '');
@@ -60,58 +51,128 @@ function buildChoices(folders) {
   return choices;
 }
 
-function getAssistantIcon(folder) {
-  const icons = {
-    '.agent': '⊡',
-    '.amazonq': '◈',
-    '.augment': '◇',
-    '.claude': '◉',
-    '.cline': '◎',
-    '.clinerules': '◎',
-    '.codebuddy': '◈',
-    '.codex': '⊞',
-    '.continue': '▹',
-    '.cospec': '⊙',
-    '.crush': '◆',
-    '.cursor': '▸',
-    '.factory': '⊟',
-    '.gemini': '◇',
-    '.github': '◈',
-    '.iflow': '▹',
-    '.kilocode': '◎',
-    '.opencode': '⊡',
-    '.qoder': '◇',
-    '.qwen': '◈',
-    '.roo': '◆',
-    '.trae': '▸',
-    '.windsurf': '◇',
-  };
-  return icons[folder] || '◦';
+/**
+ * Given the user's selected modules, determine which unique .md files
+ * are needed. Returns a de-duplicated sorted array.
+ */
+function getMdFilesForSelection(selectedModules) {
+  const mdSet = new Set();
+  for (const mod of selectedModules) {
+    const md = IDE_MD_MAP[mod];
+    if (md) {
+      mdSet.add(md);
+    }
+  }
+  return [...mdSet].sort();
 }
 
-async function checkExisting(targetDir, folder) {
-  try {
-    await access(join(targetDir, folder));
-    return true;
-  } catch {
-    return false;
+/**
+ * Step 3: Handle .md instruction file selection.
+ * Returns the final list of .md files to install.
+ */
+async function selectMdFiles(selected, targetDir) {
+  // Determine required .md files based on module selection
+  let requiredMd = getMdFilesForSelection(selected);
+
+  // Attempt IDE auto-detection
+  const detected = detectIDE();
+  if (detected.ide) {
+    const detectedBadge = chalk.hex('#2D3436').bgHex('#00CEC9').bold(` ${detected.ide} `);
+    console.log(`  ${chalk.hex('#636E72')('Auto-detected:')} ${detectedBadge}`);
+    console.log();
+  }
+
+  // Show which .md files will be installed
+  if (requiredMd.length > 0) {
+    console.log(chalk.hex('#B2BEC3')('  Instruction files for your selection:\n'));
+    for (const md of requiredMd) {
+      const desc = MD_DESCRIPTIONS[md] || '';
+      console.log(
+        chalk.hex('#00CEC9')('  ◆ ') +
+        chalk.hex('#DFE6E9').bold(md) +
+        (desc ? chalk.hex('#636E72')(` · ${desc}`) : '')
+      );
+    }
+    console.log();
+  } else {
+    console.log(chalk.hex('#636E72')('  No instruction files needed for your selection.\n'));
+  }
+
+  // Offer additional .md files
+  const available = AVAILABLE_MD_FILES.filter((f) => !requiredMd.includes(f));
+  if (available.length > 0) {
+    const { wantMore } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'wantMore',
+      message: chalk.hex('#B2BEC3')('Install additional instruction files?'),
+      default: false,
+    }]);
+
+    if (wantMore) {
+      const { additional } = await inquirer.prompt([{
+        type: 'checkbox',
+        name: 'additional',
+        message: acGradient('Select additional files:'),
+        choices: available.map((f) => ({
+          name: chalk.hex('#DFE6E9').bold(f) +
+                chalk.hex('#636E72')(` · ${MD_DESCRIPTIONS[f] || ''}`),
+          value: f,
+          short: f,
+        })),
+        pageSize: 10,
+      }]);
+      requiredMd = [...requiredMd, ...additional];
+    }
+  }
+
+  // Check for existing .md files
+  const existingMd = [];
+  for (const md of requiredMd) {
+    if (await existsInTarget(targetDir, md)) {
+      existingMd.push(md);
+    }
+  }
+
+  if (existingMd.length > 0) {
+    console.log(
+      chalk.hex('#FDCB6E')('  ⚠  These instruction files already exist:\n')
+    );
+    for (const md of existingMd) {
+      console.log(
+        chalk.hex('#FDCB6E')('     ▸ ') +
+        chalk.hex('#DFE6E9')(md)
+      );
+    }
+    console.log();
+
+    const { overwriteMd } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'overwriteMd',
+      message: chalk.hex('#FDCB6E')('Overwrite existing instruction files?'),
+      default: false,
+    }]);
+
+    if (!overwriteMd) {
+      requiredMd = requiredMd.filter((f) => !existingMd.includes(f));
+    }
   }
+
+  return requiredMd;
 }
 
 export async function initCommand() {
   const targetDir = process.cwd();
 
-  // ── Step 1: Scan ───────────────────────────────────────────────
-  await stepHeader(1, 3, 'Scanning framework modules');
+  // ── Step 1/4: Scan ──────────────────────────────────────────────
+  await stepHeader(1, 4, 'Scanning framework modules');
   await scanAnimation('Indexing available modules', 1000);
   console.log();
 
-  // Matrix rain transition
   await matrixRain(1800);
 
   let folders;
   try {
-    folders = await getFrameworkFolders();
+    folders = await getSelectableModules();
   } catch {
     console.log(chalk.hex('#D63031')('  ✗ Error: Could not read framework directory.'));
     console.log(chalk.hex('#636E72')('  Make sure ac-framework is installed correctly.'));
@@ -123,7 +184,6 @@ export async function initCommand() {
     process.exit(0);
   }
 
-  // Module count display
   const countBadge = chalk.hex('#2D3436').bgHex('#00CEC9').bold(` ${folders.length} `);
   const autoBadge = chalk.hex('#2D3436').bgHex('#6C5CE7').bold(' +openspec ');
   console.log(`  ${countBadge} ${chalk.hex('#B2BEC3')('assistant modules found')}  ${autoBadge} ${chalk.hex('#636E72')('auto-included')}`);
@@ -131,10 +191,9 @@ export async function initCommand() {
   await animatedSeparator(60);
   console.log();
 
-  // ── Step 2: Select ─────────────────────────────────────────────
-  await stepHeader(2, 3, 'Select your assistants');
+  // ── Step 2/4: Select ────────────────────────────────────────────
+  await stepHeader(2, 4, 'Select your assistants');
 
-  // Controls hint with styled keys
   const key = (k) => chalk.hex('#2D3436').bgHex('#636E72')(` ${k} `);
   console.log(
     `  ${key('↑↓')} ${chalk.hex('#636E72')('navigate')}  ` +
@@ -164,11 +223,17 @@ export async function initCommand() {
 
   console.log();
 
-  // ── Check conflicts ────────────────────────────────────────────
-  const allForCheck = [...selected, ...ALWAYS_INSTALL];
+  // ── Check module conflicts ──────────────────────────────────────
+  const bundledForCheck = [];
+  for (const folder of selected) {
+    if (BUNDLED[folder]) {
+      bundledForCheck.push(...BUNDLED[folder]);
+    }
+  }
+  const allForCheck = [...selected, ...bundledForCheck, ...ALWAYS_INSTALL];
   const existing = [];
   for (const folder of allForCheck) {
-    if (await checkExisting(targetDir, folder)) {
+    if (await existsInTarget(targetDir, folder)) {
       existing.push(folder);
     }
   }
@@ -204,13 +269,14 @@ export async function initCommand() {
       }
       selected.length = 0;
       selected.push(...filtered);
+      const newCount = chalk.hex('#00CEC9').bold(filtered.length + autoFiltered.length);
       console.log(
-        chalk.hex('#B2BEC3')(`\n  Continuing with ${chalk.hex('#00CEC9').bold(filtered.length + autoFiltered.length)} new module(s)...\n`)
+        '\n  ' + chalk.hex('#B2BEC3')('Continuing with ') + newCount + chalk.hex('#B2BEC3')(' new module(s)...') + '\n'
       );
     }
   }
 
-  // ── Confirm selection with animated reveal ─────────────────────
+  // ── Reveal selection ────────────────────────────────────────────
   console.log(chalk.hex('#B2BEC3')('  Selected modules:\n'));
 
   const selectedItems = selected.map((folder) => {
@@ -228,6 +294,26 @@ export async function initCommand() {
 
   console.log();
 
+  // ── Step 3/4: Instruction Files ─────────────────────────────────
+  await animatedSeparator(60);
+  console.log();
+  await stepHeader(3, 4, 'Instruction files');
+
+  const mdFiles = await selectMdFiles(selected, targetDir);
+
+  // Show combined summary if there are .md files
+  if (mdFiles.length > 0) {
+    console.log(chalk.hex('#B2BEC3')('  Instruction files to install:\n'));
+    const mdItems = mdFiles.map((md) => {
+      const desc = MD_DESCRIPTIONS[md] || '';
+      return chalk.hex('#DFE6E9').bold(md) +
+        (desc ? chalk.hex('#636E72')(` · ${desc}`) : '');
+    });
+    await revealList(mdItems, { prefix: '◆', color: '#6C5CE7', delay: 40 });
+    console.log();
+  }
+
+  // ── Final confirmation ──────────────────────────────────────────
   const { confirm } = await inquirer.prompt([
     {
       type: 'confirm',
@@ -242,43 +328,44 @@ export async function initCommand() {
     process.exit(0);
   }
 
-  // ── Step 3: Install ────────────────────────────────────────────
+  // ── Step 4/4: Install ───────────────────────────────────────────
   console.log();
   await animatedSeparator(60);
   console.log();
-  await stepHeader(3, 3, 'Installing modules');
+  await stepHeader(4, 4, 'Installing modules');
 
-  const frameworkPath = resolve(__dirname, '../../framework');
-  const allToInstall = [...selected, ...ALWAYS_INSTALL];
+  const allToInstall = expandWithBundled(selected);
   let installed = 0;
   const errors = [];
 
+  // Install module folders
   for (const folder of allToInstall) {
     const displayName = formatFolderName(folder);
-
     try {
       await installWithAnimation(displayName, async () => {
-        const src = join(frameworkPath, folder);
-        const dest = join(targetDir, folder);
-
-        await cp(src, dest, { recursive: true, force: true });
-
-        // Remove node_modules if present (e.g. .opencode)
-        try {
-          await rm(join(dest, 'node_modules'), { recursive: true, force: true });
-        } catch {
-          // Fine if it doesn't exist
-        }
+        await copyModule(folder, targetDir);
       });
       installed++;
     } catch (err) {
       errors.push({ folder, error: err.message });
     }
+    await sleep(80);
+  }
 
+  // Install .md instruction files
+  for (const md of mdFiles) {
+    try {
+      await installWithAnimation(md, async () => {
+        await copyMdFile(md, targetDir);
+      });
+      installed++;
+    } catch (err) {
+      errors.push({ folder: md, error: err.message });
+    }
     await sleep(80);
   }
 
-  // ── Final result ───────────────────────────────────────────────
+  // ── Final result ────────────────────────────────────────────────
   if (errors.length === 0) {
     await celebrateSuccess(installed, targetDir);
   } else {

package/src/config/constants.js

@@ -0,0 +1,64 @@
+// Modules that are always installed regardless of user selection.
+export const ALWAYS_INSTALL = ['openspec'];
+
+// When a key module is selected, its bundled companions are auto-installed.
+export const BUNDLED = {
+  '.cline': ['.clinerules'],
+};
+
+// Folders that should never appear in the selection list because they are
+// installed automatically as part of a bundled assistant.
+export const HIDDEN_FOLDERS = new Set(Object.values(BUNDLED).flat());
+
+// Human-readable descriptions for each module, used in the selection UI.
+export const DESCRIPTIONS = {
+  '.agent': 'Generic Agent Framework',
+  '.amazonq': 'AWS Amazon Q',
+  '.augment': 'Augment Code Assistant',
+  '.claude': 'Anthropic Claude Code',
+  '.cline': 'Cline VS Code Extension',
+  '.codebuddy': 'CodeBuddy Assistant',
+  '.codex': 'OpenAI Codex CLI',
+  '.continue': 'Continue.dev IDE Extension',
+  '.cospec': 'OpenSpec Native Framework',
+  '.crush': 'Crush Assistant',
+  '.cursor': 'Cursor IDE',
+  '.factory': 'Factory Assistant',
+  '.gemini': 'Google Gemini',
+  '.github': 'GitHub Copilot',
+  '.iflow': 'iFlow Assistant',
+  '.kilocode': 'Kilo Code',
+  '.opencode': 'OpenCode Framework',
+  '.qoder': 'Qoder Assistant',
+  '.qwen': 'Qwen (Alibaba Cloud)',
+  '.roo': 'Roo Code Extension',
+  '.trae': 'Trae IDE',
+  '.windsurf': 'Windsurf IDE',
+  'openspec': 'OpenSpec Configuration',
+};
+
+// Icons for each assistant, used in the selection UI.
+export const ASSISTANT_ICONS = {
+  '.agent': '⊡',
+  '.amazonq': '◈',
+  '.augment': '◇',
+  '.claude': '◉',
+  '.cline': '◎',
+  '.codebuddy': '◈',
+  '.codex': '⊞',
+  '.continue': '▹',
+  '.cospec': '⊙',
+  '.crush': '◆',
+  '.cursor': '▸',
+  '.factory': '⊟',
+  '.gemini': '◇',
+  '.github': '◈',
+  '.iflow': '▹',
+  '.kilocode': '◎',
+  '.opencode': '⊡',
+  '.qoder': '◇',
+  '.qwen': '◈',
+  '.roo': '◆',
+  '.trae': '▸',
+  '.windsurf': '◇',
+};

package/src/config/ide-mapping.js

@@ -0,0 +1,47 @@
+/**
+ * Maps each IDE/assistant module folder to the .md instruction file
+ * it expects in the project root. `null` means no .md file is needed
+ * (the assistant uses a different mechanism, like .clinerules).
+ */
+export const IDE_MD_MAP = {
+  '.agent': 'AGENTS.md',
+  '.amazonq': 'AGENTS.md',
+  '.augment': 'AGENTS.md',
+  '.claude': 'CLAUDE.md',
+  '.cline': null,
+  '.codebuddy': 'AGENTS.md',
+  '.codex': 'AGENTS.md',
+  '.continue': 'AGENTS.md',
+  '.cospec': 'AGENTS.md',
+  '.crush': 'AGENTS.md',
+  '.cursor': 'AGENTS.md',
+  '.factory': 'AGENTS.md',
+  '.gemini': 'GEMINI.md',
+  '.github': 'copilot-instructions.md',
+  '.iflow': 'AGENTS.md',
+  '.kilocode': 'AGENTS.md',
+  '.opencode': 'AGENTS.md',
+  '.qoder': 'AGENTS.md',
+  '.qwen': 'QWEN.md',
+  '.roo': 'AGENTS.md',
+  '.trae': 'AGENTS.md',
+  '.windsurf': 'AGENTS.md',
+};
+
+/**
+ * All unique .md files available for installation.
+ */
+export const AVAILABLE_MD_FILES = [
+  ...new Set(Object.values(IDE_MD_MAP).filter(Boolean)),
+].sort();
+
+/**
+ * Human-readable descriptions for the .md instruction files.
+ */
+export const MD_DESCRIPTIONS = {
+  'AGENTS.md': 'Generic agent instructions (used by most assistants)',
+  'CLAUDE.md': 'Anthropic Claude Code instructions',
+  'GEMINI.md': 'Google Gemini instructions',
+  'QWEN.md': 'Qwen (Alibaba Cloud) instructions',
+  'copilot-instructions.md': 'GitHub Copilot instructions',
+};

package/src/index.js

@@ -0,0 +1,4 @@
+export { getSelectableModules, expandWithBundled, copyModule, copyMdFile } from './services/installer.js';
+export { detectIDE } from './services/detector.js';
+export { ALWAYS_INSTALL, BUNDLED, DESCRIPTIONS } from './config/constants.js';
+export { IDE_MD_MAP, AVAILABLE_MD_FILES } from './config/ide-mapping.js';

package/src/services/detector.js

@@ -0,0 +1,30 @@
+/**
+ * Attempts to detect the current IDE/editor from environment variables.
+ * Returns { ide, module } where `ide` is a display name and `module` is
+ * the corresponding framework folder. Both are null when undetectable.
+ */
+export function detectIDE() {
+  const env = process.env;
+
+  // Cursor: sets CURSOR_TRACE_DIR or other CURSOR_* vars
+  if (env.CURSOR_TRACE_DIR || Object.keys(env).some((k) => k.startsWith('CURSOR_'))) {
+    return { ide: 'Cursor', module: '.cursor' };
+  }
+
+  // Windsurf: sets WINDSURF_* vars
+  if (Object.keys(env).some((k) => k.startsWith('WINDSURF_'))) {
+    return { ide: 'Windsurf', module: '.windsurf' };
+  }
+
+  // Trae: sets TRAE_* vars
+  if (Object.keys(env).some((k) => k.startsWith('TRAE_'))) {
+    return { ide: 'Trae', module: '.trae' };
+  }
+
+  // VS Code / GitHub Copilot (without Cursor/Windsurf/Trae)
+  if (env.TERM_PROGRAM === 'vscode' || env.VSCODE_PID || env.VSCODE_CWD) {
+    return { ide: 'VS Code (Copilot)', module: '.github' };
+  }
+
+  return { ide: null, module: null };
+}

package/src/services/installer.js

@@ -0,0 +1,77 @@
+import { cp, rm, access, readdir } from 'node:fs/promises';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ALWAYS_INSTALL, BUNDLED, HIDDEN_FOLDERS } from '../config/constants.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Absolute path to the bundled framework/ directory inside this package. */
+export const FRAMEWORK_PATH = resolve(__dirname, '../../framework');
+
+/**
+ * Returns sorted list of selectable assistant folder names from framework/.
+ * Excludes ALWAYS_INSTALL items, HIDDEN_FOLDERS, and non-directories.
+ */
+export async function getSelectableModules() {
+  const entries = await readdir(FRAMEWORK_PATH, { withFileTypes: true });
+  return entries
+    .filter(
+      (e) =>
+        e.isDirectory() &&
+        !ALWAYS_INSTALL.includes(e.name) &&
+        !HIDDEN_FOLDERS.has(e.name),
+    )
+    .map((e) => e.name)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Expand a list of selected modules to include bundled companions
+ * and ALWAYS_INSTALL items. Returns the full installation list.
+ */
+export function expandWithBundled(selected) {
+  const bundled = [];
+  for (const folder of selected) {
+    if (BUNDLED[folder]) {
+      bundled.push(...BUNDLED[folder]);
+    }
+  }
+  return [...selected, ...bundled, ...ALWAYS_INSTALL];
+}
+
+/**
+ * Check whether a folder or file already exists in the target directory.
+ */
+export async function existsInTarget(targetDir, name) {
+  try {
+    await access(join(targetDir, name));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Copy a single module folder from framework/ to targetDir.
+ * Removes node_modules inside the destination if present.
+ */
+export async function copyModule(folder, targetDir) {
+  const src = join(FRAMEWORK_PATH, folder);
+  const dest = join(targetDir, folder);
+  await cp(src, dest, { recursive: true, force: true });
+
+  try {
+    await rm(join(dest, 'node_modules'), { recursive: true, force: true });
+  } catch {
+    // Fine if it doesn't exist
+  }
+}
+
+/**
+ * Copy a single .md instruction file from framework/ to targetDir root.
+ */
+export async function copyMdFile(mdFileName, targetDir) {
+  const src = join(FRAMEWORK_PATH, mdFileName);
+  const dest = join(targetDir, mdFileName);
+  await cp(src, dest, { force: true });
+}