cad-workflow 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taha K
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# CAD Workflow - Clean Agentic Dev
+
+Workflow Claude Code pour le developpement assiste par IA avec **Clean Architecture Hexagonale** et **TDD**.
+
+## Installation
+
+```bash
+npx cad-workflow install
+```
+
+L'installateur interactif vous pose quelques questions :
+
+1. **Nom du projet**
+2. **Stack** : Mobile (React Native Expo + NestJS), Web (Angular/React + NestJS), ou Backend-only (NestJS)
+3. **Gestion des tickets** : Jira (connexion automatique) ou Local (stories en markdown)
+
+Fichiers installes dans votre projet :
+
+- `CLAUDE.md` - Instructions pour Claude Code
+- `.claude/agents/` - Agents specialises selon votre stack
+- `.claude/commands/` - 9 commandes de workflow (+ jira-setup si Jira)
+- `.claude/skills/` - Skills (clean code, hexa, TDD, mutation testing)
+- `.cad/config.yaml` - Configuration du workflow
+- `.cad/workflow-status.yaml` - Etat du workflow
+- `docs/` - Structure de documentation
+
+Si Jira est selectionne :
+- `.mcp.json` - Configuration MCP Atlassian
+- `.claude/settings.local.json` - Credentials Jira (non commite)
+
+## Mise a jour
+
+```bash
+npx cad-workflow update
+```
+
+Met a jour les fichiers CAD (agents, commands, skills) sans toucher a vos fichiers personnalises (CLAUDE.md, config, docs/).
+
+## Status
+
+```bash
+npx cad-workflow status
+```
+
+Affiche la version installee, la stack, le mode de tickets, et verifie les mises a jour.
+
+## Workflow
+
+```
+/cad [description de la feature]
+```
+
+Repondez `OK` apres chaque phase pour continuer. Si interrompu :
+
+```
+/cad continue
+```
+
+## Commandes
+
+| Commande | Phase | Description |
+|----------|-------|-------------|
+| `/status` | - | Afficher le status actuel |
+| `/cad` | 1-7 | Workflow complet orchestre |
+| `/comprendre` | 1 | Analyse et clarification du besoin |
+| `/concevoir` | 2 | Design et plan d'implementation |
+| `/implementer` | 3 | Implementation TDD |
+| `/review` | 4 | Review code + mutation tests |
+| `/e2e` | 5 | Tests end-to-end |
+| `/documenter` | 6 | Documentation |
+| `/commit` | 7 | Formatage, linting, commit |
+
+## Stacks
+
+| Stack | Agents | Skills |
+|-------|--------|--------|
+| **Mobile** | backend-developer, backend-reviewer, mobile-developer, mobile-reviewer, orchestrator | clean-hexa-backend, clean-hexa-mobile, mutation-testing |
+| **Web** | backend-developer, backend-reviewer, frontend-developer, frontend-reviewer, orchestrator | clean-hexa-backend, clean-hexa-frontend, mutation-testing |
+| **Backend-only** | backend-developer, backend-reviewer, orchestrator | clean-hexa-backend, mutation-testing |
+
+## MCPs recommandes
+
+- **context7** : Documentation a jour (ajouter "use context7" dans vos prompts)
+- **playwright** : Automatisation tests E2E
+
+## Licence
+
+MIT - Voir [LICENSE](LICENSE)

package/bin/cli.js

@@ -0,0 +1,529 @@
+#!/usr/bin/env node
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const yaml = require('js-yaml');
+const Mustache = require('mustache');
+const { prompt } = require('enquirer');
+
+const pkg = require('../package.json');
+
+// Resolve the user's project directory
+const PROJECT_DIR = process.env.CAD_CWD || process.cwd();
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const SRC_DIR = path.join(PACKAGE_ROOT, 'src');
+const CONFIG_PATH = path.join(PACKAGE_ROOT, 'config', 'install-config.yaml');
+const CLAUDE_DIR = path.join(PROJECT_DIR, '.claude');
+const MANIFEST_PATH = path.join(CLAUDE_DIR, '.cad-manifest.json');
+
+// Disable Mustache HTML escaping (we deal with plain text, not HTML)
+Mustache.escape = (text) => text;
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+function readManifest() {
+  if (fs.existsSync(MANIFEST_PATH)) {
+    return fs.readJSONSync(MANIFEST_PATH);
+  }
+  return null;
+}
+
+function writeManifest(data) {
+  fs.ensureDirSync(CLAUDE_DIR);
+  fs.writeJSONSync(MANIFEST_PATH, data, { spaces: 2 });
+}
+
+function loadConfig() {
+  const content = fs.readFileSync(CONFIG_PATH, 'utf8');
+  return yaml.load(content);
+}
+
+function collectFiles(dir, base) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const rel = path.join(base, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectFiles(path.join(dir, entry.name), rel));
+    } else {
+      results.push(rel);
+    }
+  }
+  return results;
+}
+
+function evaluateCondition(condition, answers) {
+  if (!condition) return true;
+  const match = condition.match(/(\w+)\s*==\s*(\w+)/);
+  if (match) {
+    const [, key, value] = match;
+    return answers[key] === value;
+  }
+  return true;
+}
+
+function interpolate(template, values) {
+  return template.replace(/\{(\w+)\}/g, (_, key) => values[key] || `{${key}}`);
+}
+
+function addToGitignore(targetDir, filePath) {
+  const gitignorePath = path.join(targetDir, '.gitignore');
+  let content = '';
+  if (fs.existsSync(gitignorePath)) {
+    content = fs.readFileSync(gitignorePath, 'utf8');
+  }
+  if (!content.includes(filePath)) {
+    content = content.trimEnd() + `\n\n# CAD Workflow - credentials (ne pas commiter)\n${filePath}\n`;
+    fs.writeFileSync(gitignorePath, content, 'utf8');
+  }
+}
+
+// ─── Install Logic ──────────────────────────────────────────────────
+
+async function runInstall() {
+  const config = loadConfig();
+
+  // Check if already installed
+  const existing = readManifest();
+  if (existing) {
+    console.log(
+      chalk.yellow(`\n  CAD v${existing.version} is already installed (${existing.installedAt}).`)
+    );
+    console.log(chalk.yellow('  Use `cad-workflow update` to update.\n'));
+    return;
+  }
+
+  // Welcome message
+  console.log(chalk.cyan(config.welcome_message));
+
+  // ── Interactive prompts ──
+
+  const answers = {
+    directory_name: path.basename(PROJECT_DIR),
+  };
+
+  // Project name
+  const projectNameAnswer = await prompt({
+    type: 'input',
+    name: 'project_name',
+    message: config.project_name.prompt,
+    initial: config.project_name.default.replace('{directory_name}', answers.directory_name),
+  });
+  answers.project_name = projectNameAnswer.project_name;
+
+  // Stack selection
+  const stackAnswer = await prompt({
+    type: 'select',
+    name: 'stack',
+    message: config.stack.prompt,
+    choices: config.stack['single-select'].map((opt) => ({
+      name: opt.value,
+      message: opt.label,
+      hint: opt.description,
+    })),
+    initial: config.stack['single-select'].findIndex((s) => s.value === config.stack.default),
+  });
+  answers.stack = stackAnswer.stack;
+
+  // Ticket management
+  const ticketAnswer = await prompt({
+    type: 'select',
+    name: 'ticket_management',
+    message: config.ticket_management.prompt,
+    choices: config.ticket_management['single-select'].map((opt) => ({
+      name: opt.value,
+      message: opt.label,
+      hint: opt.description,
+    })),
+    initial: config.ticket_management['single-select'].findIndex(
+      (t) => t.value === config.ticket_management.default
+    ),
+  });
+  answers.ticket_management = ticketAnswer.ticket_management;
+
+  // Jira prompts (conditional)
+  if (answers.ticket_management === 'jira') {
+    const jiraAnswers = await prompt([
+      {
+        type: 'input',
+        name: 'jira_url',
+        message: config.jira_url.prompt,
+        initial: config.jira_url.placeholder,
+        validate: (value) => {
+          const regex = new RegExp(config.jira_url.validation);
+          return regex.test(value) || config.jira_url.validation_error;
+        },
+      },
+      {
+        type: 'input',
+        name: 'jira_email',
+        message: config.jira_email.prompt,
+        validate: (value) => {
+          const regex = new RegExp(config.jira_email.validation);
+          return regex.test(value) || config.jira_email.validation_error;
+        },
+      },
+      {
+        type: 'password',
+        name: 'jira_token',
+        message:
+          config.jira_token.prompt +
+          ' (créer sur https://id.atlassian.com/manage-profile/security/api-tokens)',
+      },
+      {
+        type: 'input',
+        name: 'jira_project_key',
+        message: config.jira_project_key.prompt,
+        initial: config.jira_project_key.placeholder,
+        validate: (value) => {
+          const regex = new RegExp(config.jira_project_key.validation);
+          return regex.test(value) || config.jira_project_key.validation_error;
+        },
+      },
+    ]);
+    Object.assign(answers, jiraAnswers);
+  }
+
+  // Workflow config defaults
+  answers.min_coverage = config.workflow_config.min_coverage.default;
+  answers.min_mutation_score = config.workflow_config.min_mutation_score.default;
+  answers.timestamp = new Date().toISOString();
+
+  // ── File installation ──
+
+  console.log(chalk.gray('\n  Installing CAD workflow...\n'));
+  const copied = [];
+
+  // 1. Create directories
+  for (const dir of config.directories) {
+    fs.ensureDirSync(path.join(PROJECT_DIR, dir));
+  }
+  for (const condDir of config.conditional_directories) {
+    if (evaluateCondition(condDir.condition, answers)) {
+      fs.ensureDirSync(path.join(PROJECT_DIR, condDir.path));
+    }
+  }
+
+  // 2. Copy base commands
+  const baseDir = path.join(SRC_DIR, 'base');
+  const commandsSrc = path.join(baseDir, 'commands');
+  const commandsDest = path.join(CLAUDE_DIR, 'commands');
+  if (fs.existsSync(commandsSrc)) {
+    fs.copySync(commandsSrc, commandsDest, { overwrite: true });
+    copied.push(...collectFiles(commandsDest, '.claude/commands'));
+    console.log(chalk.gray('  Copied commands'));
+  }
+
+  // 3. Copy base skills
+  const skillsSrc = path.join(baseDir, 'skills');
+  const skillsDest = path.join(CLAUDE_DIR, 'skills');
+  if (fs.existsSync(skillsSrc)) {
+    fs.copySync(skillsSrc, skillsDest, { overwrite: true });
+    copied.push(...collectFiles(skillsDest, '.claude/skills'));
+    console.log(chalk.gray('  Copied base skills'));
+  }
+
+  // 4. Copy CLAUDE.md
+  const claudeMdSrc = path.join(baseDir, 'CLAUDE.md');
+  const claudeMdDest = path.join(PROJECT_DIR, 'CLAUDE.md');
+  if (!fs.existsSync(claudeMdDest)) {
+    fs.copySync(claudeMdSrc, claudeMdDest);
+    copied.push('CLAUDE.md');
+    console.log(chalk.gray('  Copied CLAUDE.md'));
+  } else {
+    console.log(chalk.yellow('  CLAUDE.md already exists, skipped'));
+  }
+
+  // 5. Copy stack-specific files (agents + skills)
+  const stackConfig = config.stack['single-select'].find((s) => s.value === answers.stack);
+  if (stackConfig && stackConfig.installs) {
+    for (const installPath of stackConfig.installs) {
+      const sourcePath = path.join(SRC_DIR, installPath);
+      if (fs.existsSync(sourcePath)) {
+        // Copy agents
+        const agentsSrc = path.join(sourcePath, 'agents');
+        if (fs.existsSync(agentsSrc)) {
+          const agentsDest = path.join(CLAUDE_DIR, 'agents');
+          fs.copySync(agentsSrc, agentsDest, { overwrite: true });
+          copied.push(...collectFiles(agentsDest, '.claude/agents'));
+          console.log(chalk.gray(`  Copied ${answers.stack} agents`));
+        }
+        // Copy skills
+        const stackSkillsSrc = path.join(sourcePath, 'skills');
+        if (fs.existsSync(stackSkillsSrc)) {
+          fs.copySync(stackSkillsSrc, skillsDest, { overwrite: false });
+          copied.push(...collectFiles(skillsDest, '.claude/skills'));
+          console.log(chalk.gray(`  Copied ${answers.stack} skills`));
+        }
+      }
+    }
+  }
+
+  // 6. Copy integration files (Jira)
+  const ticketConfig = config.ticket_management['single-select'].find(
+    (t) => t.value === answers.ticket_management
+  );
+  if (ticketConfig && ticketConfig.installs) {
+    for (const installPath of ticketConfig.installs) {
+      const sourcePath = path.join(SRC_DIR, installPath);
+      if (fs.existsSync(sourcePath)) {
+        // Copy integration commands
+        const intCommandsSrc = path.join(sourcePath, 'commands');
+        if (fs.existsSync(intCommandsSrc)) {
+          fs.copySync(intCommandsSrc, commandsDest, { overwrite: true });
+          copied.push(...collectFiles(intCommandsSrc, '.claude/commands'));
+          console.log(chalk.gray('  Copied Jira commands'));
+        }
+        // Generate .mcp.json from template
+        const mcpTemplate = path.join(sourcePath, '.mcp.json.tpl');
+        if (fs.existsSync(mcpTemplate)) {
+          const tpl = fs.readFileSync(mcpTemplate, 'utf8');
+          const rendered = Mustache.render(tpl, answers);
+          fs.writeFileSync(path.join(PROJECT_DIR, '.mcp.json'), rendered, 'utf8');
+          copied.push('.mcp.json');
+          console.log(chalk.gray('  Generated .mcp.json'));
+        }
+      }
+    }
+  }
+
+  // 7. Generate files from Mustache templates
+  for (const fileConfig of config.files_to_generate) {
+    const templatePath = path.join(baseDir, fileConfig.template);
+    const outputPath = path.join(PROJECT_DIR, fileConfig.output);
+    if (fs.existsSync(templatePath)) {
+      const tpl = fs.readFileSync(templatePath, 'utf8');
+      const rendered = Mustache.render(tpl, answers);
+      fs.ensureDirSync(path.dirname(outputPath));
+      fs.writeFileSync(outputPath, rendered, 'utf8');
+      copied.push(fileConfig.output);
+      console.log(chalk.gray(`  Generated ${fileConfig.output}`));
+    }
+  }
+
+  // 8. Generate sensitive files (Jira credentials)
+  for (const fileConfig of config.sensitive_files) {
+    if (evaluateCondition(fileConfig.condition, answers)) {
+      const templatePath = path.join(baseDir, fileConfig.template);
+      const outputPath = path.join(PROJECT_DIR, fileConfig.output);
+      if (fs.existsSync(templatePath)) {
+        const tpl = fs.readFileSync(templatePath, 'utf8');
+        const rendered = Mustache.render(tpl, answers);
+        fs.ensureDirSync(path.dirname(outputPath));
+        fs.writeFileSync(outputPath, rendered, 'utf8');
+        copied.push(fileConfig.output);
+        console.log(chalk.gray(`  Generated ${fileConfig.output}`));
+      }
+      if (fileConfig.gitignore) {
+        addToGitignore(PROJECT_DIR, fileConfig.output);
+      }
+    }
+  }
+
+  // 9. Ensure .gitignore entries
+  const gitignorePath = path.join(PROJECT_DIR, '.gitignore');
+  let gitignoreContent = '';
+  if (fs.existsSync(gitignorePath)) {
+    gitignoreContent = fs.readFileSync(gitignorePath, 'utf8');
+  }
+  const defaultEntries = ['.claude/memory/', '.claude/settings.local.json'];
+  const toAdd = defaultEntries.filter((e) => !gitignoreContent.includes(e));
+  if (toAdd.length > 0) {
+    const section = '\n# Claude Code local state\n' + toAdd.join('\n') + '\n';
+    fs.writeFileSync(gitignorePath, gitignoreContent.trimEnd() + '\n' + section, 'utf8');
+  }
+
+  // 10. Write manifest
+  const manifest = {
+    version: pkg.version,
+    stack: answers.stack,
+    ticket_management: answers.ticket_management,
+    project_name: answers.project_name,
+    installedAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    files: [...new Set(copied)],
+  };
+  writeManifest(manifest);
+
+  // 11. Post-install message
+  const postMessage =
+    answers.ticket_management === 'jira'
+      ? config.post_install_message_jira
+      : config.post_install_message_local;
+  console.log(interpolate(postMessage, answers));
+}
+
+// ─── Update Logic ───────────────────────────────────────────────────
+
+function runUpdate() {
+  console.log(chalk.cyan.bold('\n  CAD Workflow - Update\n'));
+
+  const manifest = readManifest();
+  if (!manifest) {
+    console.log(chalk.red('  CAD is not installed. Run `cad-workflow install` first.\n'));
+    return;
+  }
+
+  console.log(chalk.gray(`  Current version: ${manifest.version}`));
+  console.log(chalk.gray(`  Package version: ${pkg.version}\n`));
+
+  const copied = [];
+  const stack = manifest.stack || 'mobile';
+
+  // Re-copy base commands
+  const baseDir = path.join(SRC_DIR, 'base');
+  const commandsDest = path.join(CLAUDE_DIR, 'commands');
+  const commandsSrc = path.join(baseDir, 'commands');
+  if (fs.existsSync(commandsSrc)) {
+    fs.copySync(commandsSrc, commandsDest, { overwrite: true });
+    copied.push(...collectFiles(commandsDest, '.claude/commands'));
+  }
+
+  // Re-copy base skills
+  const skillsDest = path.join(CLAUDE_DIR, 'skills');
+  const skillsSrc = path.join(baseDir, 'skills');
+  if (fs.existsSync(skillsSrc)) {
+    fs.copySync(skillsSrc, skillsDest, { overwrite: true });
+    copied.push(...collectFiles(skillsDest, '.claude/skills'));
+  }
+
+  // Re-copy stack agents and skills
+  const config = loadConfig();
+  const stackConfig = config.stack['single-select'].find((s) => s.value === stack);
+  if (stackConfig && stackConfig.installs) {
+    for (const installPath of stackConfig.installs) {
+      const sourcePath = path.join(SRC_DIR, installPath);
+      if (fs.existsSync(sourcePath)) {
+        const agentsSrc = path.join(sourcePath, 'agents');
+        if (fs.existsSync(agentsSrc)) {
+          fs.copySync(agentsSrc, path.join(CLAUDE_DIR, 'agents'), { overwrite: true });
+          copied.push(...collectFiles(path.join(CLAUDE_DIR, 'agents'), '.claude/agents'));
+        }
+        const stackSkillsSrc = path.join(sourcePath, 'skills');
+        if (fs.existsSync(stackSkillsSrc)) {
+          fs.copySync(stackSkillsSrc, skillsDest, { overwrite: true });
+        }
+      }
+    }
+  }
+
+  // Re-copy integration commands if Jira
+  if (manifest.ticket_management === 'jira') {
+    const jiraCommandsSrc = path.join(SRC_DIR, 'integrations', 'jira', 'commands');
+    if (fs.existsSync(jiraCommandsSrc)) {
+      fs.copySync(jiraCommandsSrc, commandsDest, { overwrite: true });
+    }
+  }
+
+  console.log(chalk.gray('  Updated agents, commands, skills...'));
+
+  // Update manifest
+  manifest.version = pkg.version;
+  manifest.updatedAt = new Date().toISOString();
+  manifest.files = [...new Set(copied)];
+  writeManifest(manifest);
+
+  console.log(chalk.green.bold('\n  Update complete!\n'));
+  console.log(chalk.gray(`  ${copied.length} files updated`));
+  console.log(
+    chalk.yellow('  Note: CLAUDE.md, config, and docs/ were preserved.\n')
+  );
+}
+
+// ─── Status Logic ───────────────────────────────────────────────────
+
+async function runStatus() {
+  console.log(chalk.cyan.bold('\n  CAD Workflow - Status\n'));
+
+  const manifest = readManifest();
+  if (!manifest) {
+    console.log(chalk.red('  CAD is not installed.\n'));
+    console.log(chalk.gray('  Run: npx cad-workflow install\n'));
+    return;
+  }
+
+  console.log(chalk.white(`  Installed version: ${chalk.green(manifest.version)}`));
+  console.log(chalk.white(`  Stack:             ${chalk.cyan(manifest.stack || 'unknown')}`));
+  console.log(chalk.white(`  Tickets:           ${chalk.cyan(manifest.ticket_management || 'unknown')}`));
+  console.log(chalk.white(`  Installed at:      ${chalk.gray(manifest.installedAt)}`));
+  console.log(chalk.white(`  Last updated:      ${chalk.gray(manifest.updatedAt)}`));
+  console.log(chalk.white(`  Files tracked:     ${chalk.gray(manifest.files.length)}`));
+
+  // Check for updates via npm
+  console.log(chalk.gray('\n  Checking for updates...'));
+  try {
+    const { execSync } = require('child_process');
+    const latest = execSync('npm view cad-workflow version 2>/dev/null', {
+      encoding: 'utf8',
+    }).trim();
+
+    if (latest && latest !== manifest.version) {
+      console.log(chalk.yellow(`\n  Update available: ${manifest.version} -> ${latest}`));
+      console.log(chalk.gray('  Run: npx cad-workflow@latest update\n'));
+    } else if (latest) {
+      console.log(chalk.green('  You are up to date!\n'));
+    } else {
+      console.log(chalk.gray('  Package not published yet.\n'));
+    }
+  } catch {
+    console.log(chalk.gray('  Could not check for updates (package not published yet).\n'));
+  }
+}
+
+// ─── CLI Router ─────────────────────────────────────────────────────
+
+async function main() {
+  const command = process.argv[2];
+
+  switch (command) {
+    case 'install':
+      await runInstall();
+      break;
+    case 'update':
+      runUpdate();
+      break;
+    case 'status':
+      await runStatus();
+      break;
+    case '--version':
+    case '-v':
+      console.log(pkg.version);
+      break;
+    case '--help':
+    case '-h':
+    case undefined:
+      console.log(`
+  ${chalk.cyan.bold('cad-workflow')} v${pkg.version}
+  ${chalk.gray('Clean Agentic Dev - Workflow IA avec Clean Architecture et TDD')}
+
+  ${chalk.white('Usage:')}
+    npx cad-workflow ${chalk.cyan('<command>')}
+
+  ${chalk.white('Commands:')}
+    ${chalk.cyan('install')}    Install CAD workflow into the current project
+    ${chalk.cyan('update')}     Update CAD workflow files (preserves CLAUDE.md, config, docs)
+    ${chalk.cyan('status')}     Show installed CAD version and check for updates
+
+  ${chalk.white('Options:')}
+    ${chalk.cyan('-v, --version')}  Show version
+    ${chalk.cyan('-h, --help')}     Show help
+`);
+      break;
+    default:
+      console.log(chalk.red(`\n  Unknown command: ${command}`));
+      console.log(chalk.gray('  Run `cad-workflow --help` for available commands.\n'));
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  if (err === '') {
+    // User cancelled prompt (Ctrl+C)
+    console.log(chalk.yellow('\n  Installation cancelled.\n'));
+    process.exit(0);
+  }
+  console.error(chalk.red(`\n  Error: ${err.message}\n`));
+  process.exit(1);
+});

package/bin/wrapper.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+/**
+ * npx entry point - preserves the user's working directory.
+ *
+ * When running via npx, __dirname points to a temp cache directory
+ * (contains `_npx` or `.npm`). In that case we spawn a child process
+ * with the correct cwd so that the CLI operates in the user's project.
+ */
+
+const path = require('path');
+
+const isNpx =
+  __dirname.includes('_npx') ||
+  __dirname.includes('.npm') ||
+  __dirname.includes('npx');
+
+if (isNpx) {
+  const { spawn } = require('child_process');
+  const child = spawn(
+    process.execPath,
+    [path.join(__dirname, 'cli.js'), ...process.argv.slice(2)],
+    {
+      cwd: process.cwd(),
+      stdio: 'inherit',
+      env: { ...process.env, CAD_CWD: process.cwd() },
+    }
+  );
+  child.on('exit', (code) => process.exit(code || 0));
+} else {
+  require('./cli.js');
+}