ac-framework 1.3.0 → 1.5.0

package/src/commands/init.js

@@ -1,3 +1,16 @@
+/**
+ * init.js
+ * ──────────────────────────────────────────────────────────────────
+ * `acfm init` — Interactive wizard that installs AC Framework
+ * modules into the user's project.
+ *
+ * Flags:
+ *   --latest          Download the latest framework from GitHub
+ *                     instead of using the bundled npm version.
+ *   --branch <name>   GitHub branch to pull (implies --latest).
+ * ──────────────────────────────────────────────────────────────────
+ */
+
 import chalk from 'chalk';
 import gradient from 'gradient-string';
 import inquirer from 'inquirer';
@@ -11,7 +24,9 @@ import {
   existsInTarget,
   copyModule,
   copyMdFile,
+  FRAMEWORK_PATH,
 } from '../services/installer.js';
+import { downloadWithSpinner, cleanupTempDir } from '../services/github-sync.js';
 import {
   matrixRain,
   scanAnimation,
@@ -25,6 +40,8 @@ import {
 
 const acGradient = gradient(['#6C5CE7', '#00CEC9', '#0984E3']);
 
+// ── Helpers ──────────────────────────────────────────────────────
+
 function buildChoices(folders) {
   const choices = [];
 
@@ -160,215 +177,264 @@ async function selectMdFiles(selected, targetDir) {
   return requiredMd;
 }
 
-export async function initCommand() {
-  const targetDir = process.cwd();
+// ── Main command ─────────────────────────────────────────────────
 
-  // ── Step 1/4: Scan ──────────────────────────────────────────────
-  await stepHeader(1, 4, 'Scanning framework modules');
-  await scanAnimation('Indexing available modules', 1000);
-  console.log();
+export async function initCommand(options = {}) {
+  const targetDir = process.cwd();
 
-  await matrixRain(1800);
+  // --branch implies --latest
+  const useLatest = !!(options.latest || options.branch);
 
-  let folders;
-  try {
-    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.'));
-    process.exit(1);
-  }
+  // Dynamic step counting: +1 step when downloading from GitHub
+  const stepOffset = useLatest ? 1 : 0;
+  const totalSteps = 4 + stepOffset;
 
-  if (folders.length === 0) {
-    console.log(chalk.hex('#FDCB6E')('  No modules found in framework directory.'));
-    process.exit(0);
-  }
+  // Framework source: bundled by default, overridden by --latest
+  let frameworkPath = FRAMEWORK_PATH;
+  let tempDir = null;
 
-  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')}`);
-  console.log();
-  await animatedSeparator(60);
-  console.log();
-
-  // ── Step 2/4: Select ────────────────────────────────────────────
-  await stepHeader(2, 4, 'Select your assistants');
-
-  const key = (k) => chalk.hex('#2D3436').bgHex('#636E72')(` ${k} `);
-  console.log(
-    `  ${key('↑↓')} ${chalk.hex('#636E72')('navigate')}  ` +
-    `${key('Space')} ${chalk.hex('#636E72')('toggle')}  ` +
-    `${key('Enter')} ${chalk.hex('#636E72')('confirm')}`
-  );
-  console.log();
-
-  const choices = buildChoices(folders);
-
-  const { selected } = await inquirer.prompt([
-    {
-      type: 'checkbox',
-      name: 'selected',
-      message: acGradient('Choose modules to install:'),
-      choices,
-      pageSize: 15,
-      loop: false,
-      validate(answer) {
-        if (answer.length === 0) {
-          return chalk.hex('#D63031')('Select at least one module. Use Space to toggle.');
+  try {
+    // ── Download (only with --latest / --branch) ──────────────────
+    if (useLatest) {
+      await stepHeader(1, totalSteps, 'Downloading latest framework');
+
+      const branchLabel = options.branch || 'main';
+      const branchBadge = chalk.hex('#2D3436').bgHex('#6C5CE7').bold(` ${branchLabel} `);
+      console.log(`  ${chalk.hex('#636E72')('Branch:')} ${branchBadge}`);
+      console.log();
+
+      try {
+        const result = await downloadWithSpinner({
+          branch: options.branch,
+        });
+        tempDir = result.tempDir;
+        frameworkPath = result.tempDir;
+
+        if (result.commitSha) {
+          const shaBadge = chalk.hex('#2D3436').bgHex('#00CEC9').bold(` ${result.commitSha.slice(0, 7)} `);
+          console.log(`  ${shaBadge} ${chalk.hex('#636E72')('latest commit')}`);
         }
-        return true;
-      },
-    },
-  ]);
+        console.log();
+      } catch (err) {
+        console.log();
+        console.log(chalk.hex('#FDCB6E')(`  ⚠  ${err.message}`));
+        console.log(chalk.hex('#636E72')('  Falling back to bundled version...\n'));
+        frameworkPath = FRAMEWORK_PATH;
+      }
+    }
+
+    // ── Step: Scan ────────────────────────────────────────────────
+    await stepHeader(1 + stepOffset, totalSteps, 'Scanning framework modules');
+    await scanAnimation('Indexing available modules', 1000);
+    console.log();
 
-  console.log();
+    await matrixRain(1800);
 
-  // ── Check module conflicts ──────────────────────────────────────
-  const bundledForCheck = [];
-  for (const folder of selected) {
-    if (BUNDLED[folder]) {
-      bundledForCheck.push(...BUNDLED[folder]);
+    let folders;
+    try {
+      folders = await getSelectableModules(frameworkPath);
+    } catch {
+      console.log(chalk.hex('#D63031')('  ✗ Error: Could not read framework directory.'));
+      console.log(chalk.hex('#636E72')('  Make sure ac-framework is installed correctly.'));
+      process.exit(1);
     }
-  }
-  const allForCheck = [...selected, ...bundledForCheck, ...ALWAYS_INSTALL];
-  const existing = [];
-  for (const folder of allForCheck) {
-    if (await existsInTarget(targetDir, folder)) {
-      existing.push(folder);
+
+    if (folders.length === 0) {
+      console.log(chalk.hex('#FDCB6E')('  No modules found in framework directory.'));
+      process.exit(0);
     }
-  }
 
-  if (existing.length > 0) {
+    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')}`);
+    console.log();
+    await animatedSeparator(60);
+    console.log();
+
+    // ── Step: Select ──────────────────────────────────────────────
+    await stepHeader(2 + stepOffset, totalSteps, 'Select your assistants');
+
+    const key = (k) => chalk.hex('#2D3436').bgHex('#636E72')(` ${k} `);
     console.log(
-      chalk.hex('#FDCB6E')('  ⚠  These modules already exist in your project:\n')
+      `  ${key('↑↓')} ${chalk.hex('#636E72')('navigate')}  ` +
+      `${key('Space')} ${chalk.hex('#636E72')('toggle')}  ` +
+      `${key('Enter')} ${chalk.hex('#636E72')('confirm')}`
     );
-    for (const folder of existing) {
-      console.log(
-        chalk.hex('#FDCB6E')('     ▸ ') +
-        chalk.hex('#DFE6E9')(formatFolderName(folder)) +
-        chalk.hex('#636E72')(` (${folder})`)
-      );
-    }
     console.log();
 
-    const { overwrite } = await inquirer.prompt([
+    const choices = buildChoices(folders);
+
+    const { selected } = await inquirer.prompt([
       {
-        type: 'confirm',
-        name: 'overwrite',
-        message: chalk.hex('#FDCB6E')('Overwrite existing modules?'),
-        default: false,
+        type: 'checkbox',
+        name: 'selected',
+        message: acGradient('Choose modules to install:'),
+        choices,
+        pageSize: 15,
+        loop: false,
+        validate(answer) {
+          if (answer.length === 0) {
+            return chalk.hex('#D63031')('Select at least one module. Use Space to toggle.');
+          }
+          return true;
+        },
       },
     ]);
 
-    if (!overwrite) {
-      const filtered = selected.filter((f) => !existing.includes(f));
-      const autoFiltered = ALWAYS_INSTALL.filter((f) => !existing.includes(f));
-      if (filtered.length === 0 && autoFiltered.length === 0) {
-        console.log(chalk.hex('#636E72')('\n  Nothing new to install. Exiting.\n'));
-        process.exit(0);
+    console.log();
+
+    // ── 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 existsInTarget(targetDir, folder)) {
+        existing.push(folder);
       }
-      selected.length = 0;
-      selected.push(...filtered);
-      const newCount = chalk.hex('#00CEC9').bold(filtered.length + autoFiltered.length);
+    }
+
+    if (existing.length > 0) {
       console.log(
-        '\n  ' + chalk.hex('#B2BEC3')('Continuing with ') + newCount + chalk.hex('#B2BEC3')(' new module(s)...') + '\n'
+        chalk.hex('#FDCB6E')('  ⚠  These modules already exist in your project:\n')
       );
+      for (const folder of existing) {
+        console.log(
+          chalk.hex('#FDCB6E')('     ▸ ') +
+          chalk.hex('#DFE6E9')(formatFolderName(folder)) +
+          chalk.hex('#636E72')(` (${folder})`)
+        );
+      }
+      console.log();
+
+      const { overwrite } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'overwrite',
+          message: chalk.hex('#FDCB6E')('Overwrite existing modules?'),
+          default: false,
+        },
+      ]);
+
+      if (!overwrite) {
+        const filtered = selected.filter((f) => !existing.includes(f));
+        const autoFiltered = ALWAYS_INSTALL.filter((f) => !existing.includes(f));
+        if (filtered.length === 0 && autoFiltered.length === 0) {
+          console.log(chalk.hex('#636E72')('\n  Nothing new to install. Exiting.\n'));
+          process.exit(0);
+        }
+        selected.length = 0;
+        selected.push(...filtered);
+        const newCount = chalk.hex('#00CEC9').bold(filtered.length + autoFiltered.length);
+        console.log(
+          '\n  ' + chalk.hex('#B2BEC3')('Continuing with ') + newCount + chalk.hex('#B2BEC3')(' new module(s)...') + '\n'
+        );
+      }
     }
-  }
-
-  // ── Reveal selection ────────────────────────────────────────────
-  console.log(chalk.hex('#B2BEC3')('  Selected modules:\n'));
-
-  const selectedItems = selected.map((folder) => {
-    const desc = DESCRIPTIONS[folder] || '';
-    return chalk.hex('#DFE6E9').bold(formatFolderName(folder)) +
-      (desc ? chalk.hex('#636E72')(` · ${desc}`) : '');
-  });
-  selectedItems.push(
-    chalk.hex('#DFE6E9').bold('Openspec') +
-    chalk.hex('#636E72')(` · ${DESCRIPTIONS['openspec']}`) +
-    chalk.hex('#6C5CE7').italic(' (auto)')
-  );
 
-  await revealList(selectedItems, { prefix: '◆', color: '#00CEC9', delay: 40 });
+    // ── Reveal selection ──────────────────────────────────────────
+    console.log(chalk.hex('#B2BEC3')('  Selected modules:\n'));
 
-  console.log();
+    const selectedItems = selected.map((folder) => {
+      const desc = DESCRIPTIONS[folder] || '';
+      return chalk.hex('#DFE6E9').bold(formatFolderName(folder)) +
+        (desc ? chalk.hex('#636E72')(` · ${desc}`) : '');
+    });
+    selectedItems.push(
+      chalk.hex('#DFE6E9').bold('Openspec') +
+      chalk.hex('#636E72')(` · ${DESCRIPTIONS['openspec']}`) +
+      chalk.hex('#6C5CE7').italic(' (auto)')
+    );
 
-  // ── Step 3/4: Instruction Files ─────────────────────────────────
-  await animatedSeparator(60);
-  console.log();
-  await stepHeader(3, 4, 'Instruction files');
+    await revealList(selectedItems, { prefix: '◆', color: '#00CEC9', delay: 40 });
 
-  const mdFiles = await selectMdFiles(selected, targetDir);
+    console.log();
 
-  // 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 });
+    // ── Step: Instruction Files ───────────────────────────────────
+    await animatedSeparator(60);
     console.log();
-  }
+    await stepHeader(3 + stepOffset, totalSteps, 'Instruction files');
 
-  // ── Final confirmation ──────────────────────────────────────────
-  const { confirm } = await inquirer.prompt([
-    {
-      type: 'confirm',
-      name: 'confirm',
-      message: chalk.hex('#B2BEC3')('Proceed with installation?'),
-      default: true,
-    },
-  ]);
-
-  if (!confirm) {
-    console.log(chalk.hex('#636E72')('\n  Installation cancelled.\n'));
-    process.exit(0);
-  }
+    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();
+    }
 
-  // ── Step 4/4: Install ───────────────────────────────────────────
-  console.log();
-  await animatedSeparator(60);
-  console.log();
-  await stepHeader(4, 4, 'Installing modules');
+    // ── Final confirmation ────────────────────────────────────────
+    const { confirm } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'confirm',
+        message: chalk.hex('#B2BEC3')('Proceed with installation?'),
+        default: true,
+      },
+    ]);
 
-  const allToInstall = expandWithBundled(selected);
-  let installed = 0;
-  const errors = [];
+    if (!confirm) {
+      console.log(chalk.hex('#636E72')('\n  Installation cancelled.\n'));
+      process.exit(0);
+    }
 
-  // Install module folders
-  for (const folder of allToInstall) {
-    const displayName = formatFolderName(folder);
-    try {
-      await installWithAnimation(displayName, async () => {
-        await copyModule(folder, targetDir);
-      });
-      installed++;
-    } catch (err) {
-      errors.push({ folder, error: err.message });
+    // ── Step: Install ─────────────────────────────────────────────
+    console.log();
+    await animatedSeparator(60);
+    console.log();
+    await stepHeader(4 + stepOffset, totalSteps, 'Installing modules');
+
+    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 () => {
+          await copyModule(folder, targetDir, frameworkPath);
+        });
+        installed++;
+      } catch (err) {
+        errors.push({ folder, error: err.message });
+      }
+      await sleep(80);
     }
-    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 });
+    // Install .md instruction files
+    for (const md of mdFiles) {
+      try {
+        await installWithAnimation(md, async () => {
+          await copyMdFile(md, targetDir, frameworkPath);
+        });
+        installed++;
+      } catch (err) {
+        errors.push({ folder: md, error: err.message });
+      }
+      await sleep(80);
     }
-    await sleep(80);
-  }
 
-  // ── Final result ────────────────────────────────────────────────
-  if (errors.length === 0) {
-    await celebrateSuccess(installed, targetDir);
-  } else {
-    await showFailureSummary(installed, errors);
+    // ── Final result ──────────────────────────────────────────────
+    if (errors.length === 0) {
+      await celebrateSuccess(installed, targetDir);
+    } else {
+      await showFailureSummary(installed, errors);
+    }
+  } finally {
+    // Always clean up the temp directory if we downloaded from GitHub
+    if (tempDir) {
+      await cleanupTempDir(tempDir);
+    }
   }
 }