@ydtb/specsmd 0.1.22

package/lib/installer.js

@@ -0,0 +1,406 @@
+const fs = require('fs-extra');
+const path = require('path');
+const prompts = require('prompts');
+const yaml = require('js-yaml');
+const CLIUtils = require('./cli-utils');
+const InstallerFactory = require('./InstallerFactory');
+const { FLOWS, LINKS } = require('./constants');
+const analytics = require('./analytics');
+
+// Use theme from CLIUtils for consistent styling
+const { theme } = CLIUtils;
+
+/**
+ * Categorize an error for analytics tracking
+ * @param {Error} error - The error to categorize
+ * @returns {string} Error category
+ */
+function categorizeError(error) {
+    const message = (error.message || '').toLowerCase();
+
+    if (message.includes('permission') || message.includes('eacces')) {
+        return 'file_permission';
+    }
+    if (message.includes('enoent') || message.includes('not found')) {
+        return 'file_not_found';
+    }
+    if (message.includes('network') || message.includes('enotfound') || message.includes('timeout')) {
+        return 'network';
+    }
+    if (message.includes('enospc') || message.includes('disk')) {
+        return 'disk_space';
+    }
+    return 'unknown';
+}
+
+/**
+ * Count files in a directory recursively
+ * @param {string} dir - Directory path
+ * @returns {Promise<number>} File count
+ */
+async function countFiles(dir) {
+    let count = 0;
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                count += await countFiles(path.join(dir, entry.name));
+            } else {
+                count++;
+            }
+        }
+    } catch {
+        // Ignore errors (directory might not exist)
+    }
+    return count;
+}
+
+async function detectTools() {
+  const detected = [];
+  const installers = InstallerFactory.getInstallers();
+
+  for (const installer of installers) {
+    if (await installer.detect()) {
+      detected.push(installer.key);
+    }
+  }
+  return detected;
+}
+
+async function install() {
+  // Initialize analytics (respects opt-out env vars)
+  analytics.init();
+  await analytics.trackInstallerStarted();
+
+  const installStartTime = Date.now();
+
+  await CLIUtils.displayLogo();
+  CLIUtils.displayHeader('Installation', '');
+
+  // Step 1: Detect agentic coding tools
+  const detectedToolKeys = await detectTools();
+  const installers = InstallerFactory.getInstallers();
+  const detectedNames = installers
+    .filter(i => detectedToolKeys.includes(i.key))
+    .map(i => i.name);
+
+  CLIUtils.displayStep(1, 4, 'Detecting agentic coding tools...');
+  if (detectedNames.length > 0) {
+    CLIUtils.displayStatus('', `Detected: ${detectedNames.join(', ')}`, 'success');
+  } else {
+    CLIUtils.displayStatus('', 'No agentic coding tools detected', 'warning');
+  }
+  console.log('');
+
+  // Step 2: Select tools
+  CLIUtils.displayStep(2, 4, 'Select target tools');
+
+  // Build choices with descriptive formatting
+  const toolChoices = installers.map(installer => ({
+    title: installer.name + (detectedToolKeys.includes(installer.key) ? theme.dim(' (detected)') : ''),
+    value: installer.key,
+    selected: detectedToolKeys.includes(installer.key)
+  }));
+
+  console.log(theme.dim('  [Space] toggle  [Enter] confirm  [a] toggle all'));
+  console.log(theme.dim(`  ${theme.success('[x]')} = selected    ${theme.dim('[ ]')} = not selected\n`));
+
+  const { selectedToolKeys } = await prompts({
+    type: 'multiselect',
+    name: 'selectedToolKeys',
+    message: 'Choose tools:',
+    choices: toolChoices,
+    min: 1,
+    instructions: false
+  });
+
+  if (!selectedToolKeys || selectedToolKeys.length === 0) {
+    CLIUtils.displayError('Installation cancelled - no tools selected');
+    process.exit(1);
+  }
+
+  // Track IDE selection (await to ensure delivery before potential cancel)
+  await analytics.trackIdesConfirmed(selectedToolKeys);
+
+  // Step 3: Select Flow
+  console.log('');
+  CLIUtils.displayStep(3, 4, 'Select SDLC flow');
+  console.log(theme.dim(`  Learn more about flows: ${LINKS.flows}\n`));
+  const flowChoices = Object.entries(FLOWS).map(([key, flow]) => ({
+    title: `${flow.name} - ${flow.description}${flow.message || ''}`,
+    value: key,
+    disabled: flow.disabled
+  }));
+
+  const { selectedFlow } = await prompts({
+    type: 'select',
+    name: 'selectedFlow',
+    message: 'Which SDLC flow would you like to install?',
+    choices: flowChoices
+  });
+
+  if (!selectedFlow) {
+    CLIUtils.displayError('Installation cancelled');
+    process.exit(1);
+  }
+
+  // Track flow selection (await to ensure delivery before potential cancel)
+  await analytics.trackFlowSelected(selectedFlow);
+
+  // Step 4: Install flow files
+  console.log('');
+  CLIUtils.displayStep(4, 4, `Installing ${FLOWS[selectedFlow].name} flow...`);
+
+  try {
+    const filesCreated = await installFlow(selectedFlow, selectedToolKeys);
+
+    // Track successful installation for each tool
+    const durationMs = Date.now() - installStartTime;
+    for (const toolKey of selectedToolKeys) {
+      analytics.trackInstallationCompleted(toolKey, selectedFlow, durationMs, filesCreated);
+    }
+
+    CLIUtils.displaySuccess(`${FLOWS[selectedFlow].name} flow installed successfully!`, 'Installation Complete');
+
+    // Get selected tool names for next steps message
+    const selectedToolNames = installers
+      .filter(i => selectedToolKeys.includes(i.key))
+      .map(i => i.name);
+
+    const nextSteps = [
+      `Read .specsmd/${selectedFlow}/quick-start.md for getting started`,
+      `Open ${selectedToolNames.join(' or ')} and run /specsmd-master-agent`
+    ];
+    CLIUtils.displayNextSteps(nextSteps);
+
+    // Display IDE extension info with brand colors
+    console.log('\n' + theme.primary('─'.repeat(72)));
+    console.log(CLIUtils.logoGradient('  ★ IDE Extension'));
+    console.log(theme.primary('─'.repeat(72)));
+    console.log('');
+    console.log('  ' + CLIUtils.logoGradient('Enhance your experience with the specsmd IDE extension!'));
+    console.log('');
+    console.log(`  ${theme.primary('Learn more:')}                ${LINKS.ideExtension}`);
+    console.log(`  ${theme.primary('VS Code:')}                   ${LINKS.vscodeMarketplace}`);
+    console.log(`  ${theme.primary('Cursor/Antigravity/Windsurf:')} ${LINKS.openVsx}`);
+    console.log('');
+    console.log(theme.primary('─'.repeat(72)) + '\n');
+    console.log('');
+  } catch (error) {
+    // Track installation failure
+    const errorCategory = categorizeError(error);
+    for (const toolKey of selectedToolKeys) {
+      analytics.trackInstallationFailed(toolKey, errorCategory, selectedFlow);
+    }
+
+    CLIUtils.displayError(`Installation failed: ${error.message}`);
+    console.log(theme.dim('\nRolling back changes...'));
+    await rollback(selectedFlow, selectedToolKeys);
+    CLIUtils.displayStatus('', 'Installation rolled back', 'warning');
+    process.exit(1);
+  }
+}
+
+async function installFlow(flowKey, toolKeys) {
+  const flowPath = path.join(__dirname, '..', 'flows', FLOWS[flowKey].path);
+
+  // Step 1: Install commands for each tool
+  // Pass empty config since config.yaml is removed
+  const dummyConfig = {};
+  for (const toolKey of toolKeys) {
+    const installer = InstallerFactory.getInstaller(toolKey);
+    if (installer) {
+      await installer.installCommands(flowPath, dummyConfig);
+    }
+  }
+
+  // Step 2: Install shared flow config
+  const specsmdDir = '.specsmd';
+  const targetFlowDir = path.join(specsmdDir, flowKey);
+
+  console.log(theme.dim(`  Installing flow resources to ${targetFlowDir}/...`));
+  await fs.ensureDir(targetFlowDir);
+
+  // Copy agents
+  await fs.copy(path.join(flowPath, 'agents'), path.join(targetFlowDir, 'agents'));
+
+  // Copy internal agent capabilities (legacy check)
+  if (await fs.pathExists(path.join(flowPath, 'agent-capabilities'))) {
+    await fs.copy(path.join(flowPath, 'agent-capabilities'), path.join(targetFlowDir, 'agent-capabilities'));
+  }
+
+  // Copy bolt-types if they exist (legacy check)
+  if (await fs.pathExists(path.join(flowPath, 'bolt-types'))) {
+    await fs.copy(path.join(flowPath, 'bolt-types'), path.join(targetFlowDir, 'bolt-types'));
+  }
+
+  // Copy skills, templates, shared (now at flow root level, not nested in .specsmd)
+  if (await fs.pathExists(path.join(flowPath, 'skills'))) {
+    await fs.copy(path.join(flowPath, 'skills'), path.join(targetFlowDir, 'skills'));
+  }
+  if (await fs.pathExists(path.join(flowPath, 'templates'))) {
+    await fs.copy(path.join(flowPath, 'templates'), path.join(targetFlowDir, 'templates'));
+  }
+  if (await fs.pathExists(path.join(flowPath, 'shared'))) {
+    await fs.copy(path.join(flowPath, 'shared'), path.join(targetFlowDir, 'shared'));
+  }
+  if (await fs.pathExists(path.join(flowPath, 'scripts'))) {
+    await fs.copy(path.join(flowPath, 'scripts'), path.join(targetFlowDir, 'scripts'));
+  }
+
+  // Copy config files
+  if (await fs.pathExists(path.join(flowPath, 'memory-bank.yaml'))) {
+    await fs.copy(path.join(flowPath, 'memory-bank.yaml'), path.join(targetFlowDir, 'memory-bank.yaml'));
+  }
+  if (await fs.pathExists(path.join(flowPath, 'context-config.yaml'))) {
+    await fs.copy(path.join(flowPath, 'context-config.yaml'), path.join(targetFlowDir, 'context-config.yaml'));
+  }
+  if (await fs.pathExists(path.join(flowPath, 'quick-start.md'))) {
+    await fs.copy(path.join(flowPath, 'quick-start.md'), path.join(targetFlowDir, 'quick-start.md'));
+  }
+
+  // Copy docs
+  await fs.copy(path.join(flowPath, 'README.md'), path.join(targetFlowDir, 'README.md'));
+
+  if (await fs.pathExists(path.join(flowPath, 'constitution.md'))) {
+    await fs.copy(path.join(flowPath, 'constitution.md'), path.join(targetFlowDir, 'constitution.md'));
+  }
+
+  CLIUtils.displayStatus('', 'Installed flow resources', 'success');
+
+  // NOTE: memory-bank/ is NOT created during installation
+  // It will be created when user runs project-init
+  // This allows us to detect if project is initialized by checking for memory-bank/standards/
+
+  // Step 3: Create manifest
+  const manifest = {
+    flow: flowKey,
+    version: require('../package.json').version,
+    installed_at: new Date().toISOString(),
+    tools: toolKeys
+  };
+
+  await fs.writeFile(
+    path.join(specsmdDir, 'manifest.yaml'),
+    yaml.dump(manifest),
+    'utf8'
+  );
+
+  CLIUtils.displayStatus('', 'Created installation manifest', 'success');
+
+  // Count files created for analytics
+  const filesCreated = await countFiles(specsmdDir);
+  return filesCreated;
+}
+
+async function rollback(flowKey, toolKeys) {
+  // Remove tool command files
+  for (const toolKey of toolKeys) {
+    const installer = InstallerFactory.getInstaller(toolKey);
+    if (installer) {
+      const commandsDir = installer.commandsDir;
+      if (await fs.pathExists(commandsDir)) {
+        const files = await fs.readdir(commandsDir);
+        for (const file of files) {
+          if (file.startsWith('specsmd-')) {
+            await fs.remove(path.join(commandsDir, file));
+          }
+        }
+      }
+    }
+  }
+
+  // Remove .specsmd directory
+  if (await fs.pathExists('.specsmd')) {
+    await fs.remove('.specsmd');
+  }
+}
+
+async function uninstall() {
+  CLIUtils.displayHeader('Uninstall', '');
+
+  // Check if specsmd is installed
+  if (!await fs.pathExists('.specsmd/manifest.yaml')) {
+    CLIUtils.displayWarning('specsmd is not installed in this project');
+    return;
+  }
+
+  // Read manifest
+  const manifestContent = await fs.readFile('.specsmd/manifest.yaml', 'utf8');
+  const manifest = yaml.load(manifestContent);
+
+  const installers = InstallerFactory.getInstallers();
+  // Support both old 'ides' key and new 'tools' key for backward compatibility
+  const installedToolKeys = manifest.tools || manifest.ides || [];
+  const installedNames = installers
+    .filter(i => installedToolKeys.includes(i.key))
+    .map(i => i.name);
+
+  console.log(theme.dim(`Found installation: ${FLOWS[manifest.flow].name} flow`));
+  console.log(theme.dim(`Installed for: ${installedNames.join(', ')}\n`));
+
+  const { confirm } = await prompts({
+    type: 'confirm',
+    name: 'confirm',
+    message: 'Are you sure you want to uninstall specsmd?',
+    initial: false
+  });
+
+  if (!confirm) {
+    CLIUtils.displayStatus('', 'Uninstall cancelled', 'warning');
+    return;
+  }
+
+  // Ask about memory bank
+  const { keepMemoryBank } = await prompts({
+    type: 'confirm',
+    name: 'keepMemoryBank',
+    message: 'Keep memory-bank folder? (Contains your project artifacts)',
+    initial: true
+  });
+
+  console.log(theme.primary('\nUninstalling...\n'));
+
+  try {
+    // Remove command files
+    for (const toolKey of installedToolKeys) {
+      const installer = InstallerFactory.getInstaller(toolKey);
+      if (installer) {
+        const commandsDir = installer.commandsDir;
+        if (await fs.pathExists(commandsDir)) {
+          console.log(theme.dim(`  Removing commands from ${commandsDir}/...`));
+          const files = await fs.readdir(commandsDir);
+          for (const file of files) {
+            if (file.startsWith('specsmd-')) {
+              await fs.remove(path.join(commandsDir, file));
+            }
+          }
+        }
+      }
+    }
+
+    // Remove .specsmd directory
+    console.log(theme.dim('  Removing .specsmd/...'));
+    await fs.remove('.specsmd');
+
+    // Optionally remove memory-bank
+    if (!keepMemoryBank && await fs.pathExists('memory-bank')) {
+      console.log(theme.dim('  Removing memory-bank/...'));
+      await fs.remove('memory-bank');
+    }
+
+    CLIUtils.displaySuccess('Uninstall complete!', 'Complete');
+    if (keepMemoryBank) {
+      console.log(theme.dim('memory-bank/ was preserved\n'));
+    }
+  } catch (error) {
+    CLIUtils.displayError(`Uninstall failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  install,
+  uninstall
+};
+

package/lib/installers/AntigravityInstaller.js

@@ -0,0 +1,22 @@
+const ToolInstaller = require('./ToolInstaller');
+const path = require('path');
+
+class AntigravityInstaller extends ToolInstaller {
+    get key() {
+        return 'antigravity';
+    }
+
+    get name() {
+        return 'Google Antigravity';
+    }
+
+    get commandsDir() {
+        return path.join('.agent', 'workflows');
+    }
+
+    get detectPath() {
+        return '.agent';
+    }
+}
+
+module.exports = AntigravityInstaller;

package/lib/installers/ClaudeInstaller.js

@@ -0,0 +1,85 @@
+const ToolInstaller = require('./ToolInstaller');
+const fs = require('fs-extra');
+const path = require('path');
+const CLIUtils = require('../cli-utils');
+const { theme } = CLIUtils;
+
+class ClaudeInstaller extends ToolInstaller {
+    get key() {
+        return 'claude';
+    }
+
+    get name() {
+        return 'Claude Code';
+    }
+
+    get commandsDir() {
+        return path.join('.claude', 'commands');
+    }
+
+    get agentsDir() {
+        return path.join('.claude', 'agents');
+    }
+
+    get detectPath() {
+        return '.claude';
+    }
+
+    /**
+     * Override to install both commands and agents
+     */
+    async installCommands(flowPath, config) {
+        // Install commands (default behavior)
+        const installedCommands = await super.installCommands(flowPath, config);
+
+        // Install agents
+        const installedAgents = await this.installAgents(flowPath, config);
+
+        return [...installedCommands, ...installedAgents];
+    }
+
+    /**
+     * Install agents to .claude/agents/
+     * Uses the commands folder as source (same files serve as both commands and agents)
+     */
+    async installAgents(flowPath, config) {
+        const targetAgentsDir = this.agentsDir;
+        console.log(theme.dim(`  Installing agents to ${targetAgentsDir}/...`));
+        await fs.ensureDir(targetAgentsDir);
+
+        const commandsSourceDir = path.join(flowPath, 'commands');
+
+        if (!await fs.pathExists(commandsSourceDir)) {
+            console.log(theme.dim(`  No commands folder found at ${commandsSourceDir}`));
+            return [];
+        }
+
+        const agentFiles = await fs.readdir(commandsSourceDir);
+        const installedFiles = [];
+
+        for (const agentFile of agentFiles) {
+            if (agentFile.endsWith('.md')) {
+                try {
+                    const sourcePath = path.join(commandsSourceDir, agentFile);
+                    const prefix = (config && config.command && config.command.prefix) ? `${config.command.prefix}-` : '';
+                    const targetFileName = `specsmd-${prefix}${agentFile}`;
+                    const targetPath = path.join(targetAgentsDir, targetFileName);
+
+                    const content = await fs.readFile(sourcePath, 'utf8');
+                    await fs.outputFile(targetPath, content, 'utf8');
+                    installedFiles.push(targetFileName);
+                } catch (err) {
+                    console.log(theme.warning(`  Failed to install agent ${agentFile}: ${err.message}`));
+                }
+            }
+        }
+
+        if (installedFiles.length > 0) {
+            CLIUtils.displayStatus('', `Installed ${installedFiles.length} agents for ${this.name}`, 'success');
+        }
+
+        return installedFiles;
+    }
+}
+
+module.exports = ClaudeInstaller;

package/lib/installers/ClineInstaller.js

@@ -0,0 +1,21 @@
+const ToolInstaller = require('./ToolInstaller');
+
+class ClineInstaller extends ToolInstaller {
+    get key() {
+        return 'cline';
+    }
+
+    get name() {
+        return 'Cline';
+    }
+
+    get commandsDir() {
+        return '.clinerules';
+    }
+
+    get detectPath() {
+        return '.clinerules';
+    }
+}
+
+module.exports = ClineInstaller;

package/lib/installers/CodexInstaller.js

@@ -0,0 +1,21 @@
+const ToolInstaller = require('./ToolInstaller');
+
+class CodexInstaller extends ToolInstaller {
+    get key() {
+        return 'codex';
+    }
+
+    get name() {
+        return 'Codex';
+    }
+
+    get commandsDir() {
+        return '.codex';
+    }
+
+    get detectPath() {
+        return '.codex';
+    }
+}
+
+module.exports = CodexInstaller;

package/lib/installers/CopilotInstaller.js

@@ -0,0 +1,113 @@
+const ToolInstaller = require('./ToolInstaller');
+const fs = require('fs-extra');
+const path = require('path');
+const CLIUtils = require('../cli-utils');
+const { theme } = CLIUtils;
+
+class CopilotInstaller extends ToolInstaller {
+    get key() {
+        return 'copilot';
+    }
+
+    get name() {
+        return 'GitHub Copilot';
+    }
+
+    get commandsDir() {
+        return path.join('.github', 'prompts');
+    }
+
+    get agentsDir() {
+        return path.join('.github', 'agents');
+    }
+
+    get detectPath() {
+        return '.github';
+    }
+
+    /**
+     * Override to install both commands and agents
+     */
+    async installCommands(flowPath, config) {
+        const installedCommands = await this.installCommandFiles(flowPath, config);
+        const installedAgents = await this.installAgentFiles(flowPath, config);
+        return [...installedCommands, ...installedAgents];
+    }
+
+    /**
+     * Install prompts to .github/prompts/ with .prompt.md extension
+     */
+    async installCommandFiles(flowPath, config) {
+        const targetDir = this.commandsDir;
+        console.log(theme.dim(`  Installing prompts to ${targetDir}/...`));
+        await fs.ensureDir(targetDir);
+
+        const sourceDir = path.join(flowPath, 'commands');
+
+        if (!await fs.pathExists(sourceDir)) {
+            console.log(theme.dim(`  No commands folder found at ${sourceDir}`));
+            return [];
+        }
+
+        const files = await fs.readdir(sourceDir);
+        const installedFiles = [];
+
+        for (const file of files) {
+            if (file.endsWith('.md')) {
+                const sourcePath = path.join(sourceDir, file);
+                const prefix = (config && config.command && config.command.prefix) ? `${config.command.prefix}-` : '';
+                // Transform .md to .prompt.md for Copilot prompts
+                const targetFileName = `specsmd-${prefix}${file}`.replace(/\.md$/, '.prompt.md');
+                const targetPath = path.join(targetDir, targetFileName);
+
+                await fs.copy(sourcePath, targetPath);
+                installedFiles.push(targetFileName);
+            }
+        }
+
+        if (installedFiles.length > 0) {
+            CLIUtils.displayStatus('', `Installed ${installedFiles.length} prompts for ${this.name}`, 'success');
+        }
+        return installedFiles;
+    }
+
+    /**
+     * Install agents to .github/agents/ with .agent.md extension
+     * Uses the commands folder as source (same files serve as both commands and agents)
+     */
+    async installAgentFiles(flowPath, config) {
+        const targetDir = this.agentsDir;
+        console.log(theme.dim(`  Installing agents to ${targetDir}/...`));
+        await fs.ensureDir(targetDir);
+
+        const sourceDir = path.join(flowPath, 'commands');
+
+        if (!await fs.pathExists(sourceDir)) {
+            console.log(theme.dim(`  No commands folder found at ${sourceDir}`));
+            return [];
+        }
+
+        const files = await fs.readdir(sourceDir);
+        const installedFiles = [];
+
+        for (const file of files) {
+            if (file.endsWith('.md')) {
+                const sourcePath = path.join(sourceDir, file);
+                const prefix = (config && config.command && config.command.prefix) ? `${config.command.prefix}-` : '';
+                // Transform .md to .agent.md for Copilot agents
+                const targetFileName = `specsmd-${prefix}${file}`.replace(/\.md$/, '.agent.md');
+                const targetPath = path.join(targetDir, targetFileName);
+
+                await fs.copy(sourcePath, targetPath);
+                installedFiles.push(targetFileName);
+            }
+        }
+
+        if (installedFiles.length > 0) {
+            CLIUtils.displayStatus('', `Installed ${installedFiles.length} agents for ${this.name}`, 'success');
+        }
+        return installedFiles;
+    }
+}
+
+module.exports = CopilotInstaller;