scm-method 1.0.0

package/tools/format-workflow-md.js

@@ -0,0 +1,263 @@
+/**
+ * SCM Workflow Markdown Formatter
+ *
+ * Formats mixed markdown + XML workflow instruction files with:
+ * - 2-space XML indentation
+ * - Preserved markdown content
+ * - Proper tag nesting
+ * - Consistent formatting
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+class WorkflowFormatter {
+  constructor(options = {}) {
+    this.indentSize = options.indentSize || 2;
+    this.preserveMarkdown = options.preserveMarkdown !== false;
+    this.verbose = options.verbose || false;
+  }
+
+  /**
+   * Format a workflow markdown file
+   */
+  format(filePath) {
+    if (this.verbose) {
+      console.log(`Formatting: ${filePath}`);
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    const formatted = this.formatContent(content);
+
+    // Only write if content changed
+    if (content === formatted) {
+      if (this.verbose) {
+        console.log(`- No changes: ${filePath}`);
+      }
+      return false;
+    } else {
+      fs.writeFileSync(filePath, formatted, 'utf8');
+      if (this.verbose) {
+        console.log(`✓ Formatted: ${filePath}`);
+      }
+      return true;
+    }
+  }
+
+  /**
+   * Format content string with stateful indentation tracking
+   */
+  formatContent(content) {
+    const lines = content.split('\n');
+    const formatted = [];
+    let indentLevel = 0;
+    let inCodeBlock = false;
+    let checkBlockDepth = 0; // Track nested check blocks
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmed = line.trim();
+
+      // Track code blocks (don't format inside them)
+      if (trimmed.startsWith('```')) {
+        if (inCodeBlock) {
+          inCodeBlock = false;
+        } else {
+          inCodeBlock = true;
+        }
+        formatted.push(line);
+        continue;
+      }
+
+      // Don't format inside code blocks
+      if (inCodeBlock) {
+        formatted.push(line);
+        continue;
+      }
+
+      // Handle XML tags
+      if (this.isXMLLine(trimmed)) {
+        const result = this.formatXMLLine(trimmed, indentLevel, checkBlockDepth, i, lines);
+        formatted.push(result.line);
+        indentLevel = result.nextIndent;
+        checkBlockDepth = result.nextCheckDepth;
+      } else if (trimmed === '') {
+        // Preserve blank lines
+        formatted.push('');
+      } else {
+        // Markdown content - preserve as-is but maintain current indent if inside XML
+        formatted.push(line);
+      }
+    }
+
+    return formatted.join('\n');
+  }
+
+  /**
+   * Check if line contains XML tag
+   */
+  isXMLLine(line) {
+    return /^<[a-zA-Z-]+(\s|>|\/)/.test(line) || /^<\/[a-zA-Z-]+>/.test(line);
+  }
+
+  /**
+   * Format a single XML line with context awareness
+   */
+  formatXMLLine(line, currentIndent, checkDepth, lineIndex, allLines) {
+    const trimmed = line.trim();
+    let indent = currentIndent;
+    let nextIndent = currentIndent;
+    let nextCheckDepth = checkDepth;
+
+    // Get the tag name
+    const tagMatch = trimmed.match(/^<\/?([a-zA-Z-]+)/);
+    const tagName = tagMatch ? tagMatch[1] : '';
+
+    // Closing tag - decrease indent before this line
+    if (trimmed.startsWith('</')) {
+      indent = Math.max(0, currentIndent - 1);
+      nextIndent = indent;
+
+      // If closing a step, reset check depth
+      if (tagName === 'step' || tagName === 'workflow') {
+        nextCheckDepth = 0;
+      }
+    }
+    // Self-closing tags (opens and closes on same line)
+    // EXCEPT <check> tags which create logical blocks
+    else if (this.isSelfClosingTag(trimmed) && tagName !== 'check') {
+      // These don't change indent level
+      indent = currentIndent;
+      nextIndent = currentIndent;
+    }
+    // Opening tags
+    else if (trimmed.startsWith('<')) {
+      // Check if this is a <check> tag - these create logical blocks
+      if (tagName === 'check') {
+        indent = currentIndent;
+        // Check tags increase indent for following content
+        nextIndent = currentIndent + 1;
+        nextCheckDepth = checkDepth + 1;
+      }
+      // <action> tags inside check blocks stay at current indent
+      else if (tagName === 'action' && checkDepth > 0) {
+        indent = currentIndent;
+        nextIndent = currentIndent; // Don't increase further
+      }
+      // Other tags close check blocks and return to structural level
+      else if (checkDepth > 0) {
+        // Close all check blocks - return to base structural level
+        indent = Math.max(0, currentIndent - checkDepth);
+        nextIndent = indent + 1;
+        nextCheckDepth = 0;
+      }
+      // Regular opening tags (no check blocks active)
+      else {
+        indent = currentIndent;
+        nextIndent = currentIndent + 1;
+      }
+    }
+
+    const indentStr = ' '.repeat(indent * this.indentSize);
+    return {
+      line: indentStr + trimmed,
+      nextIndent: nextIndent,
+      nextCheckDepth: nextCheckDepth,
+    };
+  }
+
+  /**
+   * Check if tag opens and closes on same line
+   */
+  isSelfClosingTag(line) {
+    // Self-closing with />
+    if (line.endsWith('/>')) {
+      return true;
+    }
+    // Opens and closes on same line: <tag>content</tag>
+    const match = line.match(/^<([a-zA-Z-]+)(\s[^>]*)?>.*<\/\1>$/);
+    return match !== null;
+  }
+
+  /**
+   * Check if tag is a block-level structural tag
+   */
+  isBlockLevelTag(tagName) {
+    return ['step', 'workflow', 'check'].includes(tagName);
+  }
+}
+
+/**
+ * CLI Entry Point
+ */
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    console.log(`
+SCM Workflow Markdown Formatter
+
+Usage:
+  node format-workflow-md.js <file-pattern> [options]
+
+Options:
+  --verbose, -v     Verbose output
+  --check, -c       Check formatting without writing (exit 1 if changes needed)
+  --help, -h        Show this help
+
+Examples:
+  node format-workflow-md.js src/**/instructions.md
+  node format-workflow-md.js "src/modules/bmb/**/*.md" --verbose
+  node format-workflow-md.js file.md --check
+`);
+    process.exit(0);
+  }
+
+  const verbose = args.includes('--verbose') || args.includes('-v');
+  const check = args.includes('--check') || args.includes('-c');
+
+  // Remove flags from args
+  const files = args.filter((arg) => !arg.startsWith('-'));
+
+  const formatter = new WorkflowFormatter({ verbose });
+  let hasChanges = false;
+  let formattedCount = 0;
+
+  // Process files
+  for (const pattern of files) {
+    // For now, treat as direct file path
+    // TODO: Add glob support for patterns
+    if (fs.existsSync(pattern)) {
+      const stat = fs.statSync(pattern);
+      if (stat.isFile()) {
+        const changed = formatter.format(pattern);
+        if (changed) {
+          hasChanges = true;
+          formattedCount++;
+        }
+      } else if (stat.isDirectory()) {
+        console.error(`Error: ${pattern} is a directory. Please specify file paths.`);
+      }
+    } else {
+      console.error(`Error: File not found: ${pattern}`);
+    }
+  }
+
+  if (verbose || formattedCount > 0) {
+    console.log(`\nFormatted ${formattedCount} file(s)`);
+  }
+
+  if (check && hasChanges) {
+    console.error('\n❌ Some files need formatting. Run without --check to format.');
+    process.exit(1);
+  }
+
+  process.exit(0);
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+module.exports = { WorkflowFormatter };

package/tools/installer/README.md

@@ -0,0 +1,60 @@
+# SCM CLI Tool
+
+## Installing external repo SCM official modules
+
+For external official modules to be discoverable during install, ensure an entry for the external repo is added to external-official-modules.yaml.
+
+For community modules - this will be handled in a different way. This file is only for registration of modules under the scm-code-org.
+
+## Post-Install Notes
+
+Modules can display setup guidance to users after configuration is collected during `npx scm-method install`. Notes are defined in the module's own `module.yaml` — no changes to the installer are needed.
+
+### Simple Format
+
+Always displayed after the module is configured:
+
+```yaml
+post-install-notes: |
+  Thank you for choosing the XYZ Cool Module
+  For Support about this Module call 555-1212
+```
+
+### Conditional Format
+
+Display different messages based on a config question's answer:
+
+```yaml
+post-install-notes:
+  config_key_name:
+    value1: |
+      Instructions for value1...
+    value2: |
+      Instructions for value2...
+```
+
+Values without an entry (e.g., `none`) display nothing. Multiple config keys can each have their own conditional notes.
+
+### Example: TEA Module
+
+The TEA module uses the conditional format keyed on `tea_browser_automation`:
+
+```yaml
+post-install-notes:
+  tea_browser_automation:
+    cli: |
+      Playwright CLI Setup:
+        npm install -g @playwright/cli@latest
+        playwright-cli install --skills
+    mcp: |
+      Playwright MCP Setup (two servers):
+        1. playwright    — npx @playwright/mcp@latest
+        2. playwright-test — npx playwright run-test-mcp-server
+    auto: |
+      Playwright CLI Setup:
+        ...
+      Playwright MCP Setup (two servers):
+        ...
+```
+
+When a user selects `auto`, they see both CLI and MCP instructions. When they select `none`, nothing is shown.

package/tools/installer/cli-utils.js

@@ -0,0 +1,181 @@
+const path = require('node:path');
+const os = require('node:os');
+const prompts = require('./prompts');
+
+const CLIUtils = {
+  /**
+   * Get version from package.json
+   */
+  getVersion() {
+    try {
+      const packageJson = require(path.join(__dirname, '..', '..', 'package.json'));
+      return packageJson.version || 'Unknown';
+    } catch {
+      return 'Unknown';
+    }
+  },
+
+  /**
+   * Display SCM logo and version using @clack intro + box
+   */
+  async displayLogo() {
+    const version = this.getVersion();
+    const color = await prompts.getColor();
+
+    // ASCII art logo
+    const logo = [
+        ` ███████╗ ██████╗███╗   ███╗`
+        ` ██╔════╝██╔════╝████╗ ████║`
+        ` ███████╗██║     ██╔████╔██║`
+        ` ╚════██║██║     ██║╚██╔╝██║`
+        ` ███████║╚██████╗██║ ╚═╝ ██║`
+        ` ╚══════╝ ╚═════╝╚═╝     ╚═╝`
+    ]
+      .map((line) => color.yellow(line))
+      .join('\n');
+
+    const tagline = ' Build a Great product';
+
+    await prompts.box(`${logo}\n${tagline}`, `v${version}`, {
+      contentAlign: 'center',
+      rounded: true,
+      formatBorder: color.blue,
+    });
+  },
+
+  /**
+   * Display section header
+   * @param {string} title - Section title
+   * @param {string} subtitle - Optional subtitle
+   */
+  async displaySection(title, subtitle = null) {
+    await prompts.note(subtitle || '', title);
+  },
+
+  /**
+   * Display info box
+   * @param {string|Array} content - Content to display
+   * @param {Object} options - Box options
+   */
+  async displayBox(content, options = {}) {
+    let text = content;
+    if (Array.isArray(content)) {
+      text = content.join('\n\n');
+    }
+
+    const color = await prompts.getColor();
+    const borderColor = options.borderColor || 'cyan';
+    const colorMap = { green: color.green, red: color.red, yellow: color.yellow, cyan: color.cyan, blue: color.blue };
+    const formatBorder = colorMap[borderColor] || color.cyan;
+
+    await prompts.box(text, options.title, {
+      rounded: options.borderStyle === 'round' || options.borderStyle === undefined,
+      formatBorder,
+    });
+  },
+
+  /**
+   * Display module configuration header
+   * @param {string} moduleName - Module name (fallback if no custom header)
+   * @param {string} header - Custom header from module.yaml
+   * @param {string} subheader - Custom subheader from module.yaml
+   */
+  async displayModuleConfigHeader(moduleName, header = null, subheader = null) {
+    const title = header || `Configuring ${moduleName.toUpperCase()} Module`;
+    await prompts.note(subheader || '', title);
+  },
+
+  /**
+   * Display module with no custom configuration
+   * @param {string} moduleName - Module name (fallback if no custom header)
+   * @param {string} header - Custom header from module.yaml
+   * @param {string} subheader - Custom subheader from module.yaml
+   */
+  async displayModuleNoConfig(moduleName, header = null, subheader = null) {
+    const title = header || `${moduleName.toUpperCase()} Module - No Custom Configuration`;
+    await prompts.note(subheader || '', title);
+  },
+
+  /**
+   * Display step indicator
+   * @param {number} current - Current step
+   * @param {number} total - Total steps
+   * @param {string} description - Step description
+   */
+  async displayStep(current, total, description) {
+    const progress = `[${current}/${total}]`;
+    await prompts.log.step(`${progress} ${description}`);
+  },
+
+  /**
+   * Display completion message
+   * @param {string} message - Completion message
+   */
+  async displayComplete(message) {
+    const color = await prompts.getColor();
+    await prompts.box(`\u2728 ${message}`, 'Complete', {
+      rounded: true,
+      formatBorder: color.green,
+    });
+  },
+
+  /**
+   * Display error message
+   * @param {string} message - Error message
+   */
+  async displayError(message) {
+    const color = await prompts.getColor();
+    await prompts.box(`\u2717 ${message}`, 'Error', {
+      rounded: true,
+      formatBorder: color.red,
+    });
+  },
+
+  /**
+   * Format list for display
+   * @param {Array} items - Items to display
+   * @param {string} prefix - Item prefix
+   */
+  formatList(items, prefix = '\u2022') {
+    return items.map((item) => `  ${prefix} ${item}`).join('\n');
+  },
+
+  /**
+   * Clear previous lines
+   * @param {number} lines - Number of lines to clear
+   */
+  clearLines(lines) {
+    for (let i = 0; i < lines; i++) {
+      process.stdout.moveCursor(0, -1);
+      process.stdout.clearLine(1);
+    }
+  },
+
+  /**
+   * Display module completion message
+   * @param {string} moduleName - Name of the completed module
+   * @param {boolean} clearScreen - Whether to clear the screen first (deprecated, always false now)
+   */
+  displayModuleComplete(moduleName, clearScreen = false) {
+    // No longer clear screen or show boxes - just a simple completion message
+    // This is deprecated but kept for backwards compatibility
+  },
+
+  /**
+   * Expand path with ~ expansion
+   * @param {string} inputPath - Path to expand
+   * @returns {string} Expanded path
+   */
+  expandPath(inputPath) {
+    if (!inputPath) return inputPath;
+
+    // Expand ~ to home directory
+    if (inputPath.startsWith('~')) {
+      return path.join(os.homedir(), inputPath.slice(1));
+    }
+
+    return inputPath;
+  },
+};
+
+module.exports = { CLIUtils };

package/tools/installer/commands/install.js

@@ -0,0 +1,80 @@
+const path = require('node:path');
+const prompts = require('../prompts');
+const { Installer } = require('../core/installer');
+const { UI } = require('../ui');
+
+const installer = new Installer();
+const ui = new UI();
+
+module.exports = {
+  command: 'install',
+  description: 'Install scm Core agents and tools',
+  options: [
+    ['-d, --debug', 'Enable debug output for manifest generation'],
+    ['--directory <path>', 'Installation directory (default: current directory)'],
+    ['--modules <modules>', 'Comma-separated list of module IDs to install (e.g., "bmm,bmb")'],
+    [
+      '--tools <tools>',
+      'Comma-separated list of tool/IDE IDs to configure (e.g., "claude-code,cursor"). Use "none" to skip tool configuration.',
+    ],
+    ['--custom-content <paths>', 'Comma-separated list of paths to custom modules/agents/workflows'],
+    ['--action <type>', 'Action type for existing installations: install, update, or quick-update'],
+    ['--user-name <name>', 'Name for agents to use (default: system username)'],
+    ['--communication-language <lang>', 'Language for agent communication (default: English)'],
+    ['--document-output-language <lang>', 'Language for document output (default: English)'],
+    ['--output-folder <path>', 'Output folder path relative to project root (default: _scm-output)'],
+    ['-y, --yes', 'Accept all defaults and skip prompts where possible'],
+  ],
+  action: async (options) => {
+    try {
+      // Set debug flag as environment variable for all components
+      if (options.debug) {
+        process.env.SCM_DEBUG_MANIFEST = 'true';
+        await prompts.log.info('Debug mode enabled');
+      }
+
+      const config = await ui.promptInstall(options);
+
+      // Handle cancel
+      if (config.actionType === 'cancel') {
+        await prompts.log.warn('Installation cancelled.');
+        process.exit(0);
+      }
+
+      // Handle quick update separately
+      if (config.actionType === 'quick-update') {
+        const result = await installer.quickUpdate(config);
+        await prompts.log.success('Quick update complete!');
+        await prompts.log.info(`Updated ${result.moduleCount} modules with preserved settings (${result.modules.join(', ')})`);
+        process.exit(0);
+      }
+
+      // Regular install/update flow
+      const result = await installer.install(config);
+
+      // Check if installation was cancelled
+      if (result && result.cancelled) {
+        process.exit(0);
+      }
+
+      // Check if installation succeeded
+      if (result && result.success) {
+        process.exit(0);
+      }
+    } catch (error) {
+      try {
+        if (error.fullMessage) {
+          await prompts.log.error(error.fullMessage);
+        } else {
+          await prompts.log.error(`Installation failed: ${error.message}`);
+        }
+        if (error.stack) {
+          await prompts.log.message(error.stack);
+        }
+      } catch {
+        console.error(error.fullMessage || error.message || error);
+      }
+      process.exit(1);
+    }
+  },
+};

package/tools/installer/commands/status.js

@@ -0,0 +1,65 @@
+const path = require('node:path');
+const prompts = require('../prompts');
+const { Installer } = require('../core/installer');
+const { Manifest } = require('../core/manifest');
+const { UI } = require('../ui');
+
+const installer = new Installer();
+const manifest = new Manifest();
+const ui = new UI();
+
+module.exports = {
+  command: 'status',
+  description: 'Display scm installation status and module versions',
+  options: [],
+  action: async (options) => {
+    try {
+      // Find the scm directory
+      const projectDir = process.cwd();
+      const { scmDir } = await installer.findBmadDir(projectDir);
+
+      // Check if scm directory exists
+      const fs = require('fs-extra');
+      if (!(await fs.pathExists(scmDir))) {
+        await prompts.log.warn('No SCM installation found in the current directory.');
+        await prompts.log.message(`Expected location: ${scmDir}`);
+        await prompts.log.message('Run "scm install" to set up a new installation.');
+        process.exit(0);
+        return;
+      }
+
+      // Read manifest
+      const manifestData = await manifest._readRaw(scmDir);
+
+      if (!manifestData) {
+        await prompts.log.warn('No SCM installation manifest found.');
+        await prompts.log.message('Run "scm install" to set up a new installation.');
+        process.exit(0);
+        return;
+      }
+
+      // Get installation info
+      const installation = manifestData.installation || {};
+      const modules = manifestData.modules || [];
+
+      // Check for available updates (only for external modules)
+      const availableUpdates = await manifest.checkForUpdates(scmDir);
+
+      // Display status
+      await ui.displayStatus({
+        installation,
+        modules,
+        availableUpdates,
+        scmDir,
+      });
+
+      process.exit(0);
+    } catch (error) {
+      await prompts.log.error(`Status check failed: ${error.message}`);
+      if (process.env.SCM_DEBUG) {
+        await prompts.log.message(error.stack);
+      }
+      process.exit(1);
+    }
+  },
+};