wogiflow 1.0.0

package/bin/flow

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+
+/**
+ * Wogi Flow CLI Entry Point
+ *
+ * This is the main entry point for the `flow` command when installed globally via npm.
+ * It handles both global commands (init, upgrade, version) and project-local commands
+ * by delegating to the project's scripts/flow when in a project context.
+ *
+ * Usage:
+ *   flow init              # Initialize a new project
+ *   flow upgrade           # Upgrade an existing project
+ *   flow --version         # Show version
+ *   flow <command>         # Project commands (when in a project)
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { spawn } = require('child_process');
+
+// Package info
+const packageJson = require('../package.json');
+const VERSION = packageJson.version;
+
+// Global commands that don't require a project context
+const GLOBAL_COMMANDS = ['init', 'upgrade', 'version', '--version', '-v', '--help', '-h', 'skill', 'channel'];
+
+/**
+ * Find the project root by looking for .workflow directory
+ * @returns {string|null} Project root path or null if not in a project
+ */
+function findProjectRoot() {
+  let dir = process.cwd();
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    if (fs.existsSync(path.join(dir, '.workflow'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+
+  return null;
+}
+
+/**
+ * Execute a project-local flow command
+ * @param {string} projectRoot - Project root directory
+ * @param {string[]} args - Command arguments
+ */
+function executeProjectCommand(projectRoot, args) {
+  const projectFlow = path.join(projectRoot, 'scripts', 'flow');
+
+  if (!fs.existsSync(projectFlow)) {
+    console.error('Error: scripts/flow not found in project');
+    console.error('Run `flow upgrade` to update the project structure');
+    process.exit(1);
+  }
+
+  // Spawn the project's flow script
+  // Note: shell: false (default) prevents command injection
+  const child = spawn(projectFlow, args, {
+    cwd: projectRoot,
+    stdio: 'inherit'
+  });
+
+  child.on('exit', (code) => {
+    process.exit(code || 0);
+  });
+
+  child.on('error', (err) => {
+    console.error(`Failed to execute: ${err.message}`);
+    process.exit(1);
+  });
+}
+
+/**
+ * Show version information
+ */
+function showVersion() {
+  console.log(`wogi-flow v${VERSION}`);
+}
+
+/**
+ * Show help information
+ */
+function showHelp() {
+  console.log(`
+Wogi Flow v${VERSION}
+AI-powered development workflow management
+
+Usage: flow <command> [options]
+
+Global Commands:
+  init                 Initialize Wogi Flow in a new project
+  upgrade              Upgrade an existing project to latest version
+  --version, -v        Show version number
+  --help, -h           Show this help message
+
+Project Commands (run in a project directory):
+  status               Show project status
+  ready                Show available tasks
+  start <task>         Start working on a task
+  story "<title>"      Create a new story
+  health               Check workflow health
+  models               Model management commands
+  ... and many more
+
+For project command help, run: flow --help (in a project directory)
+
+Examples:
+  flow init                    # Set up Wogi Flow in current directory
+  flow init --cli claude       # Initialize with Claude Code
+  flow upgrade                 # Upgrade project to latest version
+  flow status                  # Show project overview (in project)
+
+Documentation: https://github.com/Wogi-Git/wogi-flow
+`);
+}
+
+/**
+ * Main entry point
+ */
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  // Handle version flag
+  if (command === '--version' || command === '-v' || command === 'version') {
+    showVersion();
+    return;
+  }
+
+  // Handle help flag
+  if (command === '--help' || command === '-h' || !command) {
+    const projectRoot = findProjectRoot();
+    if (projectRoot && command !== '--help' && command !== '-h') {
+      // In a project without args - show project help
+      executeProjectCommand(projectRoot, ['--help']);
+    } else {
+      showHelp();
+    }
+    return;
+  }
+
+  // Handle global commands
+  if (command === 'init') {
+    // Load and run installer
+    const installer = require('../lib/installer');
+    installer.init(args.slice(1));
+    return;
+  }
+
+  if (command === 'upgrade') {
+    // Load and run upgrader
+    const upgrader = require('../lib/upgrader');
+    upgrader.upgrade(args.slice(1));
+    return;
+  }
+
+  if (command === 'skill') {
+    // Skill registry commands
+    const projectRoot = findProjectRoot();
+    if (!projectRoot && args[1] !== 'list') {
+      console.error('Error: Not in a Wogi Flow project');
+      console.error('Use `flow init` to initialize a new project');
+      process.exit(1);
+    }
+    if (projectRoot) {
+      // In project context - delegate to project scripts
+      executeProjectCommand(projectRoot, args);
+    } else {
+      // Outside project - only allow list
+      const skillRegistry = require('../lib/skill-registry');
+      skillRegistry.skill(args.slice(1));
+    }
+    return;
+  }
+
+  if (command === 'channel') {
+    // Release channel management
+    const releaseChannel = require('../lib/release-channel');
+    releaseChannel.channel(args.slice(1));
+    return;
+  }
+
+  // For all other commands, try to find project context
+  const projectRoot = findProjectRoot();
+
+  if (!projectRoot) {
+    console.error('Error: Not in a Wogi Flow project');
+    console.error('');
+    console.error('To initialize a new project:');
+    console.error('  flow init');
+    console.error('');
+    console.error('To see all options:');
+    console.error('  flow --help');
+    process.exit(1);
+  }
+
+  // Execute project-local command
+  executeProjectCommand(projectRoot, args);
+}
+
+main();

package/lib/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+/**
+ * Wogi Flow Library Index
+ *
+ * Main entry point for the wogi-flow package.
+ * Exports all public modules for programmatic usage.
+ *
+ * @module wogi-flow
+ */
+
+const { init } = require('./installer');
+const { upgrade } = require('./upgrader');
+const { skill } = require('./skill-registry');
+const { channel, CHANNELS, getLatestVersion } = require('./release-channel');
+const utils = require('./utils');
+
+module.exports = {
+  init,
+  upgrade,
+  skill,
+  channel,
+
+  // Release channel utilities
+  CHANNELS,
+  getLatestVersion,
+
+  // Shared utilities
+  utils,
+
+  // Version info
+  version: require('../package.json').version
+};

package/lib/installer.js

@@ -0,0 +1,467 @@
+#!/usr/bin/env node
+
+/**
+ * Wogi Flow Installer
+ *
+ * Handles project initialization with `flow init`.
+ * Creates the .workflow directory structure, configures CLI bridges,
+ * and sets up the project for use with the selected AI CLI.
+ *
+ * @module lib/installer
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+// Shared utilities
+const { copyDir, safeReadJson } = require('./utils');
+
+// Package root (where wogi-flow is installed)
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+// Supported CLIs
+const SUPPORTED_CLIS = {
+  claude: {
+    name: 'Claude Code',
+    dir: '.claude',
+    configFile: 'CLAUDE.md',
+    description: 'Anthropic Claude Code CLI'
+  },
+  gemini: {
+    name: 'Gemini CLI',
+    dir: '.gemini',
+    configFile: 'GEMINI.md',
+    description: 'Google Gemini CLI'
+  },
+  opencode: {
+    name: 'OpenCode',
+    dir: '.opencode',
+    configFile: 'config.yaml',
+    description: 'OpenCode CLI'
+  }
+};
+
+// Default configuration
+const DEFAULT_CONFIG = {
+  version: '1.9.0',
+  projectName: '',
+  cli: 'claude',
+  strictMode: true,
+  releaseChannel: 'stable'
+};
+
+/**
+ * Parse command line arguments with bounds checking
+ * @param {string[]} args - Command line arguments
+ * @returns {Object} Parsed options
+ */
+function parseArgs(args) {
+  const options = {
+    cli: null,
+    force: false,
+    yes: false,
+    help: false
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--cli' || arg === '-c') {
+      // Bounds check before accessing next argument
+      if (i + 1 >= args.length) {
+        console.error('Error: --cli requires a value');
+        options.help = true;
+        break;
+      }
+      options.cli = args[++i];
+    } else if (arg === '--force' || arg === '-f') {
+      options.force = true;
+    } else if (arg === '--yes' || arg === '-y') {
+      options.yes = true;
+    } else if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Show help message
+ */
+function showHelp() {
+  console.log(`
+Usage: flow init [options]
+
+Initialize Wogi Flow in the current directory.
+
+Options:
+  --cli, -c <name>    Select CLI (claude, gemini, opencode)
+  --force, -f         Overwrite existing configuration
+  --yes, -y           Accept all defaults without prompting
+  --help, -h          Show this help message
+
+Examples:
+  flow init                    # Interactive setup
+  flow init --cli claude       # Initialize with Claude Code
+  flow init --cli claude -y    # Quick setup with defaults
+  flow init --force            # Reinitialize existing project
+`);
+}
+
+/**
+ * Create readline interface for user input
+ * @returns {readline.Interface}
+ */
+function createReadline() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+}
+
+/**
+ * Ask a question and get user input
+ * @param {readline.Interface} rl - Readline interface
+ * @param {string} question - Question to ask
+ * @param {string} defaultValue - Default value
+ * @returns {Promise<string>} User's answer
+ */
+function ask(rl, question, defaultValue = '') {
+  const prompt = defaultValue ? `${question} [${defaultValue}]: ` : `${question}: `;
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      resolve(answer.trim() || defaultValue);
+    });
+  });
+}
+
+/**
+ * Ask a yes/no question
+ * @param {readline.Interface} rl - Readline interface
+ * @param {string} question - Question to ask
+ * @param {boolean} defaultValue - Default value
+ * @returns {Promise<boolean>}
+ */
+async function askYesNo(rl, question, defaultValue = true) {
+  const hint = defaultValue ? '[Y/n]' : '[y/N]';
+  const answer = await ask(rl, `${question} ${hint}`, '');
+  if (!answer) return defaultValue;
+  return answer.toLowerCase().startsWith('y');
+}
+
+/**
+ * Select from a list of options
+ * @param {readline.Interface} rl - Readline interface
+ * @param {string} question - Question to ask
+ * @param {Object} options - Options object {key: {name, description}}
+ * @param {string} defaultKey - Default selection
+ * @returns {Promise<string>} Selected key
+ */
+async function selectOption(rl, question, options, defaultKey) {
+  console.log(`\n${question}`);
+  const keys = Object.keys(options);
+  keys.forEach((key, index) => {
+    const opt = options[key];
+    const marker = key === defaultKey ? '>' : ' ';
+    console.log(`  ${marker} ${index + 1}. ${opt.name} - ${opt.description}`);
+  });
+
+  const answer = await ask(rl, 'Enter number or name', defaultKey);
+
+  // Check if answer is a number
+  const num = parseInt(answer, 10);
+  if (!isNaN(num) && num >= 1 && num <= keys.length) {
+    return keys[num - 1];
+  }
+
+  // Check if answer matches a key
+  if (options[answer.toLowerCase()]) {
+    return answer.toLowerCase();
+  }
+
+  return defaultKey;
+}
+
+// copyDir is imported from ./utils
+
+/**
+ * Create the .workflow directory structure
+ * @param {string} projectRoot - Project root directory
+ * @param {Object} config - Configuration options
+ */
+function createWorkflowStructure(projectRoot, config) {
+  const workflowDir = path.join(projectRoot, '.workflow');
+
+  // Create main directories
+  const dirs = [
+    'state',
+    'changes/general',
+    'models',
+    'templates',
+    'agents',
+    'bridges',
+    'roadmap',
+    'specs',
+    'verifications'
+  ];
+
+  for (const dir of dirs) {
+    fs.mkdirSync(path.join(workflowDir, dir), { recursive: true });
+  }
+
+  // Create config.json
+  const configPath = path.join(workflowDir, 'config.json');
+  const configContent = {
+    version: config.version,
+    projectName: config.projectName,
+    cli: config.cli,
+    enforcement: {
+      strictMode: config.strictMode,
+      requireTasks: true,
+      requireApproval: true
+    },
+    releaseChannel: config.releaseChannel,
+    autoUpdate: {
+      enabled: true,
+      notifyOnly: true
+    }
+  };
+  fs.writeFileSync(configPath, JSON.stringify(configContent, null, 2));
+
+  // Create ready.json
+  const readyPath = path.join(workflowDir, 'state', 'ready.json');
+  const readyContent = {
+    lastUpdated: new Date().toISOString(),
+    ready: [],
+    inProgress: [],
+    blocked: [],
+    recentlyCompleted: []
+  };
+  fs.writeFileSync(readyPath, JSON.stringify(readyContent, null, 2));
+
+  // Create empty state files
+  const stateFiles = [
+    { name: 'request-log.md', content: '# Request Log\n\nAutomatic log of all requests that changed files.\n\n---\n' },
+    { name: 'decisions.md', content: '# Project Decisions\n\nKey decisions and patterns for this project.\n\n---\n' },
+    { name: 'app-map.md', content: '# Application Map\n\nComponent registry for this project.\n\n---\n' },
+    { name: 'progress.md', content: '# Progress Notes\n\nSession handoff notes.\n\n---\n' }
+  ];
+
+  for (const file of stateFiles) {
+    const filePath = path.join(workflowDir, 'state', file.name);
+    if (!fs.existsSync(filePath)) {
+      fs.writeFileSync(filePath, file.content);
+    }
+  }
+
+  // Create model registry
+  const registryPath = path.join(workflowDir, 'models', 'registry.json');
+  const registryContent = {
+    version: '1.0',
+    lastUpdated: new Date().toISOString(),
+    models: {}
+  };
+  fs.writeFileSync(registryPath, JSON.stringify(registryContent, null, 2));
+
+  // Copy templates from package
+  const packageTemplates = path.join(PACKAGE_ROOT, '.workflow', 'templates');
+  const projectTemplates = path.join(workflowDir, 'templates');
+  if (fs.existsSync(packageTemplates)) {
+    copyDir(packageTemplates, projectTemplates);
+  }
+
+  // Copy agents from package
+  const packageAgents = path.join(PACKAGE_ROOT, '.workflow', 'agents');
+  const projectAgents = path.join(workflowDir, 'agents');
+  if (fs.existsSync(packageAgents)) {
+    copyDir(packageAgents, projectAgents);
+  }
+
+  // Copy bridges from package
+  const packageBridges = path.join(PACKAGE_ROOT, '.workflow', 'bridges');
+  const projectBridges = path.join(workflowDir, 'bridges');
+  if (fs.existsSync(packageBridges)) {
+    copyDir(packageBridges, projectBridges);
+  }
+
+  console.log('  Created .workflow/ directory structure');
+}
+
+/**
+ * Create CLI-specific configuration
+ * @param {string} projectRoot - Project root directory
+ * @param {string} cliKey - CLI identifier
+ * @param {Object} config - Configuration
+ */
+function createCLIConfig(projectRoot, cliKey, config) {
+  const cli = SUPPORTED_CLIS[cliKey];
+  if (!cli) {
+    console.error(`Unknown CLI: ${cliKey}`);
+    return;
+  }
+
+  const cliDir = path.join(projectRoot, cli.dir);
+  fs.mkdirSync(cliDir, { recursive: true });
+
+  // Create CLI-specific config file
+  if (cliKey === 'claude') {
+    const claudeMd = `# Project Instructions
+
+You are an AI development assistant using the Wogi Flow methodology.
+
+## Quick Start
+
+\`\`\`bash
+cat .workflow/config.json      # Read config
+cat .workflow/state/ready.json # Check tasks
+\`\`\`
+
+## Core Commands
+
+- \`/wogi-ready\` - Show available tasks
+- \`/wogi-start TASK-X\` - Start a task
+- \`/wogi-status\` - Project overview
+
+Generated by Wogi Flow v${config.version}
+`;
+    fs.writeFileSync(path.join(cliDir, 'CLAUDE.md'), claudeMd);
+
+    // Create skills directory
+    fs.mkdirSync(path.join(cliDir, 'skills'), { recursive: true });
+
+    // Create docs directory
+    fs.mkdirSync(path.join(cliDir, 'docs'), { recursive: true });
+
+    // Create rules directory
+    fs.mkdirSync(path.join(cliDir, 'rules'), { recursive: true });
+  }
+
+  console.log(`  Created ${cli.dir}/ for ${cli.name}`);
+}
+
+/**
+ * Copy scripts from package to project
+ * @param {string} projectRoot - Project root directory
+ */
+function copyScripts(projectRoot) {
+  const packageScripts = path.join(PACKAGE_ROOT, 'scripts');
+  const projectScripts = path.join(projectRoot, 'scripts');
+
+  if (fs.existsSync(packageScripts)) {
+    copyDir(packageScripts, projectScripts);
+
+    // Make flow script executable
+    const flowScript = path.join(projectScripts, 'flow');
+    if (fs.existsSync(flowScript)) {
+      fs.chmodSync(flowScript, '755');
+    }
+
+    console.log('  Copied scripts/ directory');
+  }
+}
+
+/**
+ * Main initialization function
+ * @param {string[]} args - Command line arguments
+ */
+async function init(args) {
+  const options = parseArgs(args);
+
+  if (options.help) {
+    showHelp();
+    return;
+  }
+
+  const projectRoot = process.cwd();
+  const workflowDir = path.join(projectRoot, '.workflow');
+
+  // Check for existing installation
+  if (fs.existsSync(workflowDir) && !options.force) {
+    console.log('Wogi Flow is already initialized in this directory.');
+    console.log('Use --force to reinitialize.');
+    return;
+  }
+
+  console.log('\n🚀 Wogi Flow Installer\n');
+
+  let config = { ...DEFAULT_CONFIG };
+
+  // Detect project name from package.json or directory name
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  const pkg = safeReadJson(packageJsonPath);
+  if (pkg && pkg.name) {
+    config.projectName = pkg.name;
+  } else {
+    config.projectName = path.basename(projectRoot);
+  }
+
+  // Interactive or quick mode
+  if (options.yes) {
+    // Use defaults and CLI option if provided
+    config.cli = options.cli || 'claude';
+    console.log(`Using quick mode with ${SUPPORTED_CLIS[config.cli].name}`);
+  } else {
+    // Interactive mode
+    const rl = createReadline();
+
+    try {
+      // Confirm project name
+      config.projectName = await ask(rl, 'Project name', config.projectName);
+
+      // Select CLI
+      config.cli = options.cli || await selectOption(
+        rl,
+        'Which AI CLI are you using?',
+        SUPPORTED_CLIS,
+        'claude'
+      );
+
+      // Enable strict mode?
+      config.strictMode = await askYesNo(
+        rl,
+        'Enable strict mode (require tasks for changes)?',
+        true
+      );
+
+      // Confirm
+      console.log('\nConfiguration:');
+      console.log(`  Project: ${config.projectName}`);
+      console.log(`  CLI: ${SUPPORTED_CLIS[config.cli].name}`);
+      console.log(`  Strict Mode: ${config.strictMode ? 'Yes' : 'No'}`);
+
+      const proceed = await askYesNo(rl, '\nProceed with installation?', true);
+      if (!proceed) {
+        console.log('Installation cancelled.');
+        rl.close();
+        return;
+      }
+
+      rl.close();
+    } catch (err) {
+      rl.close();
+      throw err;
+    }
+  }
+
+  console.log('\nInstalling Wogi Flow...\n');
+
+  // Create structure
+  createWorkflowStructure(projectRoot, config);
+
+  // Create CLI config
+  createCLIConfig(projectRoot, config.cli, config);
+
+  // Copy scripts
+  copyScripts(projectRoot);
+
+  console.log('\n✅ Wogi Flow initialized successfully!\n');
+  console.log('Next steps:');
+  console.log('  1. Review .workflow/config.json');
+  console.log('  2. Run `./scripts/flow status` to see project status');
+  console.log('  3. Create your first task with `./scripts/flow story "Task title"`');
+  console.log('');
+}
+
+module.exports = { init };