whiteport-design-studio 0.1.0

package/tools/cli/lib/ide-configs.js

@@ -0,0 +1,104 @@
+/**
+ * IDE Configuration - Maps IDEs to their config file paths.
+ * For each IDE, we write a WDS agent activation instructions file.
+ */
+
+const path = require('node:path');
+const fs = require('fs-extra');
+
+// IDE definitions: where each IDE expects its instructions/rules file
+const IDE_MAP = {
+  'claude-code': { dir: '.claude', file: 'instructions.md', label: 'Claude Code', append: true },
+  cursor: { dir: '.cursor/rules', file: 'wds.mdc', label: 'Cursor' },
+  windsurf: { dir: '.windsurf', file: 'rules/wds.md', label: 'Windsurf' },
+  cline: { dir: '.clinerules', file: 'wds.md', label: 'Cline' },
+  'github-copilot': { dir: '.github', file: 'copilot-instructions.md', label: 'GitHub Copilot', append: true },
+  roo: { dir: '.roo', file: 'commands/wds.md', label: 'Roo Code' },
+  codex: { dir: '.codex', file: 'prompts/wds.md', label: 'Codex' },
+  gemini: { dir: '.gemini', file: 'commands/wds.md', label: 'Gemini' },
+  qwen: { dir: '.qwen', file: 'commands/wds.md', label: 'Qwen' },
+  trae: { dir: '.trae', file: 'rules/wds.md', label: 'Trae' },
+  'kiro-cli': { dir: '.kiro', file: 'wds-instructions.md', label: 'Kiro CLI' },
+  'rovo-dev': { dir: '.rovodev', file: 'subagents/wds.md', label: 'Rovo Dev' },
+  crush: { dir: '.crush', file: 'commands/wds.md', label: 'Crush' },
+  auggie: { dir: '.augment', file: 'commands/wds.md', label: 'Auggie' },
+  antigravity: { dir: '.agent', file: 'workflows/wds.md', label: 'Antigravity' },
+  iflow: { dir: '.iflow', file: 'commands/wds.md', label: 'iFlow' },
+  opencode: { dir: '.opencode', file: 'agent/wds.md', label: 'OpenCode' },
+};
+
+/**
+ * Get list of IDE choices for the prompt
+ */
+function getIdeChoices() {
+  return Object.entries(IDE_MAP).map(([value, config]) => ({
+    name: config.label,
+    value,
+  }));
+}
+
+/**
+ * Generate the WDS instructions content
+ */
+function generateInstructions(wdsFolder) {
+  return `
+# Whiteport Design Studio (WDS) Agents
+
+This project uses the Whiteport Design Studio methodology with AI agents.
+WDS files are installed in the \`${wdsFolder}/\` directory.
+
+## Available Agents
+
+To activate a WDS agent, load and follow the instructions in the agent file:
+
+- **Mimir** (Orchestrator & Guide): Read \`${wdsFolder}/agents/mimir-orchestrator.md\` - Start here if you're new to WDS
+- **Saga** (Analyst): Read \`${wdsFolder}/agents/saga-analyst.md\` - Product Brief & Trigger Mapping (Phases 1-2)
+- **Idunn** (Product Manager): Read \`${wdsFolder}/agents/idunn-pm.md\` - Platform Requirements & Design Deliveries (Phases 3, 6)
+- **Freya** (UX Designer): Read \`${wdsFolder}/agents/freya-ux.md\` - UX Design, Design System & Testing (Phases 4-5, 7-8)
+
+## How to Activate
+
+Tell the AI: "Read and activate the agent in \`${wdsFolder}/agents/[agent-name].md\`"
+
+The agent will load its persona, read the project config, greet you, and show its menu.
+
+## Project Configuration
+
+Project settings are stored in \`${wdsFolder}/config.yaml\`. Agents load this automatically on activation.
+`.trim();
+}
+
+/**
+ * Write IDE config file for the selected IDE
+ */
+async function writeIdeConfig(projectDir, ide, wdsFolder) {
+  const config = IDE_MAP[ide];
+  if (!config) {
+    throw new Error(`Unknown IDE: ${ide}`);
+  }
+
+  const content = generateInstructions(wdsFolder);
+  const filePath = path.join(projectDir, config.dir, config.file);
+
+  // Ensure parent directory exists
+  await fs.ensureDir(path.dirname(filePath));
+
+  // If append mode and file exists, append with separator
+  if (config.append && await fs.pathExists(filePath)) {
+    const existing = await fs.readFile(filePath, 'utf8');
+    if (!existing.includes('Whiteport Design Studio')) {
+      await fs.writeFile(filePath, existing + '\n\n' + content + '\n', 'utf8');
+    }
+  } else {
+    await fs.writeFile(filePath, content + '\n', 'utf8');
+  }
+
+  return { filePath, label: config.label };
+}
+
+module.exports = {
+  IDE_MAP,
+  getIdeChoices,
+  generateInstructions,
+  writeIdeConfig,
+};

package/tools/cli/lib/installer.js

@@ -0,0 +1,257 @@
+/**
+ * WDS Installer - Core orchestrator
+ * Copies WDS source files, compiles agents, creates folder structure, sets up IDE.
+ */
+
+const path = require('node:path');
+const fs = require('fs-extra');
+const chalk = require('chalk');
+const ora = require('ora');
+const yaml = require('js-yaml');
+const inquirer = require('inquirer').default || require('inquirer');
+const { compileAgentFile } = require('./compiler');
+const { writeIdeConfig } = require('./ide-configs');
+
+class Installer {
+  constructor() {
+    // Resolve directories relative to this file (tools/cli/lib/ -> up 3 levels)
+    const repoRoot = path.resolve(__dirname, '..', '..', '..');
+    this.srcDir = path.join(repoRoot, 'src');
+    this.docsDir = path.join(repoRoot, 'docs');
+  }
+
+  /**
+   * Main installation flow
+   * @param {Object} config - Configuration from UI prompts
+   */
+  async install(config) {
+    const { projectDir, wdsFolder, ides, project_type, design_experience } = config;
+    const wdsDir = path.join(projectDir, wdsFolder);
+
+    // Check if already installed
+    if (await fs.pathExists(wdsDir)) {
+      console.log(chalk.yellow(`\n  ${wdsFolder}/ already exists.`));
+      const { action } = await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'action',
+          message: 'What would you like to do?',
+          choices: [
+            { name: 'Update - Replace WDS files, keep config.yaml', value: 'update' },
+            { name: 'Fresh install - Remove everything and start over', value: 'fresh' },
+            { name: 'Cancel', value: 'cancel' },
+          ],
+        },
+      ]);
+
+      if (action === 'cancel') {
+        return { success: false };
+      }
+
+      if (action === 'fresh') {
+        const removeSpinner = ora('Removing existing WDS installation...').start();
+        await fs.remove(wdsDir);
+        removeSpinner.succeed('Old installation removed');
+      } else if (action === 'update') {
+        // Preserve config.yaml during update
+        const configPath = path.join(wdsDir, 'config.yaml');
+        let savedConfig = null;
+        if (await fs.pathExists(configPath)) {
+          savedConfig = await fs.readFile(configPath, 'utf8');
+        }
+
+        const removeSpinner = ora('Updating WDS files...').start();
+        await fs.remove(wdsDir);
+        removeSpinner.succeed('Old files cleared');
+
+        // Will be restored after copy
+        config._savedConfigYaml = savedConfig;
+      }
+    }
+
+    console.log('');
+
+    // Step 1: Copy source files
+    const spinner = ora('Copying WDS files...').start();
+    try {
+      await this.copySrcFiles(wdsDir);
+      spinner.succeed('WDS files copied');
+    } catch (err) {
+      spinner.fail('Failed to copy WDS files');
+      throw err;
+    }
+
+    // Step 2: Write config.yaml
+    const configSpinner = ora('Writing configuration...').start();
+    try {
+      await this.writeConfig(wdsDir, config);
+      configSpinner.succeed('Configuration saved');
+    } catch (err) {
+      configSpinner.fail('Failed to write configuration');
+      throw err;
+    }
+
+    // Step 3: Compile agents
+    const agentSpinner = ora('Compiling agents...').start();
+    try {
+      const agents = await this.compileAgents(wdsDir, wdsFolder);
+      agentSpinner.succeed(`Compiled ${agents.length} agents`);
+    } catch (err) {
+      agentSpinner.fail('Failed to compile agents');
+      throw err;
+    }
+
+    // Step 4: Create docs folder structure
+    const docsSpinner = ora('Creating project folders...').start();
+    try {
+      await this.createDocsFolders(projectDir);
+      docsSpinner.succeed('Project folders created');
+    } catch (err) {
+      docsSpinner.fail('Failed to create project folders');
+      throw err;
+    }
+
+    // Step 5: Set up IDEs
+    const ideList = ides || (config.ide ? [config.ide] : []);
+    const ideSpinner = ora(`Setting up ${ideList.length} IDE(s)...`).start();
+    try {
+      const labels = [];
+      for (const ide of ideList) {
+        const result = await writeIdeConfig(projectDir, ide, wdsFolder);
+        labels.push(result.label);
+      }
+      ideSpinner.succeed(`Configured: ${labels.join(', ')}`);
+    } catch (err) {
+      ideSpinner.fail('Failed to set up IDEs');
+      throw err;
+    }
+
+    // Step 6: Copy learning & reference material (optional)
+    if (config.include_learning) {
+      const learnSpinner = ora('Copying learning & reference material...').start();
+      try {
+        await this.copyLearningMaterial(wdsDir);
+        learnSpinner.succeed('Learning & reference material added');
+      } catch (err) {
+        learnSpinner.fail('Failed to copy learning material');
+        throw err;
+      }
+    }
+
+    return { success: true, wdsDir, projectDir };
+  }
+
+  /**
+   * Copy src/ content into the target WDS directory
+   */
+  async copySrcFiles(wdsDir) {
+    const contentDirs = ['agents', 'data', 'gems', 'templates', 'workflows'];
+
+    for (const dir of contentDirs) {
+      const src = path.join(this.srcDir, dir);
+      const dest = path.join(wdsDir, dir);
+      if (await fs.pathExists(src)) {
+        await fs.copy(src, dest);
+      }
+    }
+
+    // Copy module.yaml
+    const moduleYaml = path.join(this.srcDir, 'module.yaml');
+    if (await fs.pathExists(moduleYaml)) {
+      await fs.copy(moduleYaml, path.join(wdsDir, 'module.yaml'));
+    }
+  }
+
+  /**
+   * Write config.yaml from user answers (or restore saved config on update)
+   */
+  async writeConfig(wdsDir, config) {
+    // On update, restore the user's existing config
+    if (config._savedConfigYaml) {
+      await fs.writeFile(path.join(wdsDir, 'config.yaml'), config._savedConfigYaml, 'utf8');
+      return;
+    }
+
+    const configData = {
+      user_name: config.user_name || 'Designer',
+      communication_language: config.communication_language || 'en',
+      document_output_language: config.document_output_language || 'en',
+      output_folder: 'docs',
+      wds_folder: config.wdsFolder,
+      project_type: config.project_type,
+      design_experience: config.design_experience,
+    };
+
+    const yamlStr = yaml.dump(configData, { lineWidth: -1 });
+    await fs.writeFile(path.join(wdsDir, 'config.yaml'), `# WDS Configuration - Generated by installer\n${yamlStr}`, 'utf8');
+  }
+
+  /**
+   * Compile all .agent.yaml files in the agents directory
+   */
+  async compileAgents(wdsDir, wdsFolder) {
+    const agentsDir = path.join(wdsDir, 'agents');
+    const files = await fs.readdir(agentsDir);
+    const agentFiles = files.filter((f) => f.endsWith('.agent.yaml'));
+    const results = [];
+
+    for (const file of agentFiles) {
+      const yamlPath = path.join(agentsDir, file);
+      const result = compileAgentFile(yamlPath, { wdsFolder });
+      results.push(result);
+    }
+
+    return results;
+  }
+
+  /**
+   * Copy learning & reference material into the WDS directory
+   */
+  async copyLearningMaterial(wdsDir) {
+    const learningDirs = ['getting-started', 'learn-wds', 'method', 'models', 'tools'];
+    const excludeDirs = ['course-explainers', 'Webinars'];
+
+    for (const dir of learningDirs) {
+      const src = path.join(this.docsDir, dir);
+      const dest = path.join(wdsDir, dir);
+      if (await fs.pathExists(src)) {
+        await fs.copy(src, dest, {
+          filter: (srcPath) => {
+            const relative = path.relative(src, srcPath);
+            const topDir = relative.split(path.sep)[0];
+            return !excludeDirs.includes(topDir);
+          },
+        });
+      }
+    }
+  }
+
+  /**
+   * Create the WDS docs folder structure
+   */
+  async createDocsFolders(projectDir) {
+    const docsPath = path.join(projectDir, 'docs');
+    const folders = [
+      'A-Product-Brief',
+      'B-Trigger-Map',
+      'C-Platform-Requirements',
+      'C-Scenarios',
+      'D-Design-System',
+      'E-PRD/Design-Deliveries',
+      'F-Agent-Dialogs',
+    ];
+
+    for (const folder of folders) {
+      const folderPath = path.join(docsPath, folder);
+      await fs.ensureDir(folderPath);
+
+      // Add .gitkeep to preserve empty directories
+      const gitkeepPath = path.join(folderPath, '.gitkeep');
+      if (!(await fs.pathExists(gitkeepPath))) {
+        await fs.writeFile(gitkeepPath, '# This file ensures the directory is tracked by git\n');
+      }
+    }
+  }
+}
+
+module.exports = { Installer };

package/tools/cli/lib/ui.js

@@ -0,0 +1,127 @@
+/**
+ * WDS Installer UI - Banner, prompts, and success message.
+ */
+
+const chalk = require('chalk');
+const figlet = require('figlet');
+const inquirer = require('inquirer').default || require('inquirer');
+const path = require('node:path');
+const { getIdeChoices } = require('./ide-configs');
+
+class UI {
+  /**
+   * Display the WDS ASCII banner
+   */
+  displayBanner() {
+    try {
+      const banner = figlet.textSync('WDS', { font: 'Standard' });
+      console.log(chalk.cyan(banner));
+    } catch {
+      console.log(chalk.cyan.bold('\n  W D S'));
+    }
+    console.log(chalk.white.bold('  Whiteport Design Studio'));
+    console.log(chalk.dim('  Strategic design methodology for AI-powered workflows\n'));
+  }
+
+  /**
+   * Run the full prompt flow and return config
+   */
+  async promptInstall() {
+    this.displayBanner();
+
+    const projectDir = process.cwd();
+    console.log(chalk.white(`  Target: ${chalk.cyan(projectDir)}`));
+    console.log(chalk.dim(`  Agents and workflows will be installed in ${chalk.white('_wds/')}\n`));
+
+    // Confirm directory
+    const { confirmDir } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'confirmDir',
+        message: 'Install WDS in this directory?',
+        default: true,
+      },
+    ]);
+
+    if (!confirmDir) {
+      return { cancelled: true };
+    }
+
+    // Collect configuration
+    const answers = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'user_name',
+        message: 'Your name (agents will greet you by name):',
+        default: 'Designer',
+      },
+      {
+        type: 'list',
+        name: 'project_type',
+        message: 'What type of project are you working on?',
+        choices: [
+          { name: 'Digital Product - Multiple scenarios with more complex structure', value: 'digital_product' },
+          { name: 'Single Scenario - Simple web sites and flat navigation', value: 'single_scenario' },
+          { name: 'Single Page - Landing pages or simple one page web sites', value: 'single_page' },
+          { name: 'Custom - Specialized structure, define later', value: 'custom' },
+        ],
+        default: 'digital_product',
+      },
+      {
+        type: 'list',
+        name: 'design_experience',
+        message: 'What is your design experience level?',
+        choices: [
+          { name: 'Beginner - New to UX design, provide detailed guidance', value: 'beginner' },
+          { name: 'Intermediate - Familiar with design concepts, balanced approach', value: 'intermediate' },
+          { name: 'Expert - Experienced designer, be direct and efficient', value: 'expert' },
+        ],
+        default: 'intermediate',
+      },
+      {
+        type: 'confirm',
+        name: 'include_learning',
+        message: 'Include learning & reference material in _wds/?',
+        default: true,
+      },
+      {
+        type: 'checkbox',
+        name: 'ides',
+        message: 'Which AI IDE/tools are you using? (Space to select, Enter to confirm)',
+        choices: getIdeChoices(),
+        validate: (answer) => answer.length > 0 ? true : 'Select at least one IDE.',
+      },
+    ]);
+
+    return {
+      projectDir,
+      ...answers,
+      wdsFolder: '_wds',
+      cancelled: false,
+    };
+  }
+
+  /**
+   * Display success message with next steps
+   */
+  displaySuccess(wdsFolder) {
+    console.log('');
+    console.log(chalk.green.bold('  Installation complete!'));
+    console.log('');
+    console.log(chalk.white('  Next steps:'));
+    console.log(chalk.dim(`  1. Open your project in your AI IDE`));
+    console.log(chalk.dim(`  2. Ask the AI to activate an agent from ${chalk.cyan(wdsFolder + '/agents/')}:`));
+    console.log(chalk.cyan(`     "Read and activate the agent in ${wdsFolder}/agents/mimir-orchestrator.md"`));
+    console.log('');
+    console.log(chalk.white(`  Agents installed in ${chalk.cyan(wdsFolder + '/agents/')}:`));
+    console.log(chalk.dim(`  - Mimir (Orchestrator) - Start here if you're new`));
+    console.log(chalk.dim(`  - Saga  (Analyst)      - Product Brief & Trigger Mapping`));
+    console.log(chalk.dim(`  - Idunn (PM)           - Platform Requirements & Deliveries`));
+    console.log(chalk.dim(`  - Freya (Designer)     - UX Design & Testing`));
+    console.log('');
+    console.log(chalk.dim('  Learn more: https://github.com/whiteport-collective/whiteport-design-studio'));
+    console.log('');
+  }
+}
+
+module.exports = { UI };

package/tools/cli/wds-cli.js

@@ -0,0 +1,43 @@
+const { program } = require('commander');
+const path = require('node:path');
+const fs = require('node:fs');
+
+// Fix for stdin issues when running through npm on Windows
+if (process.stdin.isTTY) {
+  try {
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+
+    if (process.platform === 'win32') {
+      process.stdin.on('error', () => {});
+    }
+  } catch {
+    // Silently ignore - some environments may not support these operations
+  }
+}
+
+// Load package.json for version info
+const packageJson = require('../../package.json');
+
+// Load install command
+const installCommand = require('./commands/install');
+
+// Set up program
+program
+  .version(packageJson.version)
+  .description('Whiteport Design Studio - Strategic design methodology for AI-powered workflows');
+
+// Register install command
+const cmd = program.command(installCommand.command).description(installCommand.description);
+for (const option of installCommand.options || []) {
+  cmd.option(...option);
+}
+cmd.action(installCommand.action);
+
+// Parse arguments
+program.parse(process.argv);
+
+// Show help if no command provided
+if (process.argv.slice(2).length === 0) {
+  program.outputHelp();
+}

package/tools/wds-npx-wrapper.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+/**
+ * WDS CLI - Direct execution wrapper for npx
+ * Ensures proper execution when run via npx from npm registry.
+ */
+
+const { execSync } = require('node:child_process');
+const path = require('node:path');
+const fs = require('node:fs');
+
+// Check if we're running in an npx temporary directory
+const isNpxExecution = __dirname.includes('_npx') || __dirname.includes('.npm');
+
+if (isNpxExecution) {
+  // Running via npx - spawn child process to preserve user's working directory
+  const args = process.argv.slice(2);
+  const cliPath = path.join(__dirname, 'cli', 'wds-cli.js');
+
+  if (!fs.existsSync(cliPath)) {
+    console.error('Error: Could not find wds-cli.js at', cliPath);
+    console.error('Current directory:', __dirname);
+    process.exit(1);
+  }
+
+  try {
+    execSync(`node "${cliPath}" ${args.join(' ')}`, {
+      stdio: 'inherit',
+      cwd: process.cwd(),
+    });
+  } catch (error) {
+    process.exit(error.status || 1);
+  }
+} else {
+  // Local execution - use require
+  require('./cli/wds-cli.js');
+}