@onion-ai/cli 1.0.0-beta.1

package/src/commands/install.js

@@ -0,0 +1,261 @@
+import { readdirSync, readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import {
+  CLAUDE_HOME, ONION_HOME, ONION_MANIFEST,
+  ONION_COMMANDS, ONION_AGENTS, CLAUDE_SKILLS,
+  CLAUDE_MD, FRAMEWORK_SOURCE
+} from '../utils/paths.js';
+import { ensureDir, copyDir, readFile, writeFile, exists, countFiles, removeDir } from '../utils/fs.js';
+import * as log from '../utils/log.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Markers we add to CLAUDE.md to load Onion */
+const CLAUDE_MD_MARKER_START = '# === Onion Framework (auto-managed — do not edit) ===';
+const CLAUDE_MD_MARKER_END = '# === End Onion Framework ===';
+
+const CLAUDE_MD_BLOCK = `${CLAUDE_MD_MARKER_START}
+# Onion Framework - AI-powered development workflow system
+# Installed by @onion-ai/cli — https://github.com/onion-ai/cli
+#
+# Commands: Use /onion:* to access all framework commands
+# Agents: Use @onion-* to access all framework agents
+# Docs: ~/.claude/onion/docs/ for reference documentation
+#
+# To update: npx @onion-ai/cli update
+# To remove: npx @onion-ai/cli uninstall
+
+@onion/CLAUDE.md
+${CLAUDE_MD_MARKER_END}`;
+
+export async function install(opts = {}) {
+  const { force = false, dryRun = false } = opts;
+
+  log.header('Onion Framework Installer');
+
+  // 1. Check prerequisites
+  log.step('Checking prerequisites...');
+
+  if (!exists(CLAUDE_HOME)) {
+    log.error(`Claude Code config not found at ${CLAUDE_HOME}`);
+    log.info('Install Claude Code first: https://claude.ai/claude-code');
+    process.exit(1);
+  }
+  log.success('Claude Code detected');
+
+  // Check for existing installation
+  if (exists(ONION_HOME) && !force) {
+    const manifest = readManifest();
+    if (manifest) {
+      log.warn(`Onion Framework v${manifest.version} is already installed`);
+      log.info('Use --force to overwrite or run: onion update');
+      process.exit(1);
+    }
+  }
+
+  // Check framework source exists
+  if (!exists(FRAMEWORK_SOURCE)) {
+    log.error('Framework files not found in package. This is a bug.');
+    log.info('Please report: https://github.com/onion-ai/cli/issues');
+    process.exit(1);
+  }
+
+  if (dryRun) {
+    log.header('Dry run — no changes will be made');
+  }
+
+  // 2. Count what we're installing
+  const commandCount = countFiles(join(FRAMEWORK_SOURCE, 'commands'));
+  const agentCount = countFiles(join(FRAMEWORK_SOURCE, 'agents'));
+  const skillCount = countSkillDirs(join(FRAMEWORK_SOURCE, 'skills'));
+  const docCount = countFiles(join(FRAMEWORK_SOURCE, 'docs'));
+
+  log.info(`Found: ${commandCount} commands, ${agentCount} agents, ${skillCount} skills, ${docCount} docs`);
+
+  if (dryRun) {
+    log.blank();
+    log.step(`Would create: ${ONION_HOME}`);
+    log.step(`Would create: ${ONION_COMMANDS} (commands with onion: prefix)`);
+    log.step(`Would create: ${ONION_AGENTS} (agents)`);
+    log.step(`Would install skills to: ${CLAUDE_SKILLS}`);
+    log.step(`Would patch: ${CLAUDE_MD}`);
+    log.blank();
+    log.success('Dry run complete. Run without --dry-run to install.');
+    return;
+  }
+
+  // 3. Clean existing installation if --force
+  if (force) {
+    log.step('Removing existing installation...');
+    removeDir(ONION_HOME);
+    removeDir(ONION_COMMANDS);
+    removeDir(ONION_AGENTS);
+    removeOnionSkills(CLAUDE_SKILLS);
+  }
+
+  // 4. Install framework home (docs, utils, rules, CLAUDE.md)
+  log.step('Installing framework core...');
+  ensureDir(ONION_HOME);
+
+  const coreDirs = ['docs', 'utils', 'rules'];
+  for (const dir of coreDirs) {
+    const src = join(FRAMEWORK_SOURCE, dir);
+    if (exists(src)) {
+      copyDir(src, join(ONION_HOME, dir));
+    }
+  }
+
+  // Copy Onion CLAUDE.md entry point
+  const onionClaudeMd = join(FRAMEWORK_SOURCE, 'CLAUDE.md');
+  if (existsSync(onionClaudeMd)) {
+    const content = readFileSync(onionClaudeMd, 'utf-8');
+    writeFile(join(ONION_HOME, 'CLAUDE.md'), content);
+  }
+  log.success('Installed framework core (docs, utils, rules)');
+
+  // 5. Install commands → ~/.claude/commands/onion/
+  log.step('Installing commands (onion: prefix)...');
+  const cmdSrc = join(FRAMEWORK_SOURCE, 'commands');
+  if (exists(cmdSrc)) {
+    copyDir(cmdSrc, ONION_COMMANDS);
+    log.success(`Installed ${commandCount} commands → /onion:*`);
+  }
+
+  // 6. Install agents → ~/.claude/agents/onion/
+  log.step('Installing agents...');
+  const agentSrc = join(FRAMEWORK_SOURCE, 'agents');
+  if (exists(agentSrc)) {
+    copyDir(agentSrc, ONION_AGENTS);
+    log.success(`Installed ${agentCount} agents`);
+  }
+
+  // 7. Install skills → ~/.claude/skills/onion-<name>/
+  log.step('Installing skills...');
+  const skillSrc = join(FRAMEWORK_SOURCE, 'skills');
+  if (exists(skillSrc)) {
+    installSkills(skillSrc, CLAUDE_SKILLS);
+    log.success(`Installed ${skillCount} skills`);
+  }
+
+  // 8. Patch CLAUDE.md
+  log.step('Configuring Claude Code integration...');
+  patchClaudeMd();
+  log.success('Updated ~/.claude/CLAUDE.md');
+
+  // 9. Write manifest
+  const manifest = {
+    version: getPackageVersion(),
+    installedAt: new Date().toISOString(),
+    components: {
+      commands: commandCount,
+      agents: agentCount,
+      skills: skillCount,
+      docs: docCount
+    },
+    paths: {
+      home: ONION_HOME,
+      commands: ONION_COMMANDS,
+      agents: ONION_AGENTS,
+      skills: CLAUDE_SKILLS
+    }
+  };
+  writeFile(ONION_MANIFEST, JSON.stringify(manifest, null, 2));
+
+  // 10. Summary
+  log.blank();
+  log.header('Installation complete!');
+  log.info('Available commands in Claude Code:');
+  log.step('/onion                       — Intelligent entry point');
+  log.step('/onion:product:task          — Create structured tasks');
+  log.step('/onion:engineer:start        — Start feature development');
+  log.step('/onion:engineer:work         — Continue active feature');
+  log.step('/onion:git:feature:start     — Start GitFlow feature branch');
+  log.blank();
+  log.info('Run "onion doctor" to verify installation');
+  log.info('Run "onion list" to see all components');
+  log.blank();
+}
+
+/**
+ * Install skills with onion- prefix into Claude's skills directory.
+ */
+function installSkills(srcDir, destDir) {
+  ensureDir(destDir);
+  const entries = readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      copyDir(join(srcDir, entry.name), join(destDir, `onion-${entry.name}`));
+    }
+  }
+}
+
+/**
+ * Remove only onion-prefixed skills from Claude's skills directory.
+ */
+function removeOnionSkills(skillsDir) {
+  if (!existsSync(skillsDir)) return;
+  const entries = readdirSync(skillsDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && entry.name.startsWith('onion-')) {
+      removeDir(join(skillsDir, entry.name));
+    }
+  }
+}
+
+/**
+ * Count skill directories.
+ */
+function countSkillDirs(dir) {
+  if (!existsSync(dir)) return 0;
+  return readdirSync(dir, { withFileTypes: true })
+    .filter(e => e.isDirectory())
+    .length;
+}
+
+/**
+ * Patch CLAUDE.md to include Onion framework reference.
+ * Non-destructive — preserves existing content.
+ */
+function patchClaudeMd() {
+  let content = readFile(CLAUDE_MD) || '';
+
+  // Remove any existing Onion block
+  const startIdx = content.indexOf(CLAUDE_MD_MARKER_START);
+  const endIdx = content.indexOf(CLAUDE_MD_MARKER_END);
+  if (startIdx !== -1 && endIdx !== -1) {
+    content = content.substring(0, startIdx).trimEnd() +
+      '\n' +
+      content.substring(endIdx + CLAUDE_MD_MARKER_END.length);
+  }
+
+  // Append Onion block at the end
+  content = content.trimEnd() + '\n\n' + CLAUDE_MD_BLOCK + '\n';
+
+  writeFile(CLAUDE_MD, content);
+}
+
+/**
+ * Read the installation manifest.
+ */
+function readManifest() {
+  const content = readFile(ONION_MANIFEST);
+  if (!content) return null;
+  try {
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the package version.
+ */
+function getPackageVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf-8'));
+    return pkg.version;
+  } catch {
+    return 'unknown';
+  }
+}

package/src/commands/list.js

@@ -0,0 +1,152 @@
+import { readdirSync, existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import {
+  ONION_COMMANDS, ONION_AGENTS, CLAUDE_SKILLS, ONION_HOME
+} from '../utils/paths.js';
+import { exists, readFile } from '../utils/fs.js';
+import * as log from '../utils/log.js';
+
+export async function list(opts = {}) {
+  const showAll = !opts.commands && !opts.agents && !opts.skills;
+
+  const manifest = readManifest();
+  if (!manifest) {
+    log.error('Onion Framework is not installed');
+    log.info('Run: npx @onion-ai/cli install');
+    process.exit(1);
+  }
+
+  log.header(`Onion Framework v${manifest.version}`);
+
+  if (showAll || opts.commands) {
+    listCommands();
+  }
+
+  if (showAll || opts.agents) {
+    listAgents();
+  }
+
+  if (showAll || opts.skills) {
+    listSkills();
+  }
+
+  log.blank();
+}
+
+function listCommands() {
+  log.step('Commands (/onion:*):');
+  if (!exists(ONION_COMMANDS)) {
+    log.warn('  No commands directory found');
+    return;
+  }
+
+  const commands = collectCommands(ONION_COMMANDS, '');
+  for (const cmd of commands.sort()) {
+    console.log(`    /onion:${cmd}`);
+  }
+  console.log(`    (${commands.length} total)`);
+  log.blank();
+}
+
+function listAgents() {
+  log.step('Agents:');
+  if (!exists(ONION_AGENTS)) {
+    log.warn('  No agents directory found');
+    return;
+  }
+
+  const agents = collectAgents(ONION_AGENTS);
+  for (const agent of agents.sort()) {
+    console.log(`    @${agent}`);
+  }
+  console.log(`    (${agents.length} total)`);
+  log.blank();
+}
+
+function listSkills() {
+  log.step('Skills:');
+  if (!existsSync(CLAUDE_SKILLS)) {
+    log.warn('  No skills directory found');
+    return;
+  }
+
+  const entries = readdirSync(CLAUDE_SKILLS, { withFileTypes: true });
+  const skills = entries
+    .filter(e => e.isDirectory() && e.name.startsWith('onion-'))
+    .map(e => e.name);
+
+  for (const skill of skills.sort()) {
+    console.log(`    ${skill}`);
+  }
+  console.log(`    (${skills.length} total)`);
+  log.blank();
+}
+
+/**
+ * Recursively collect command paths from directory structure.
+ * Maps directory/file.md → "directory:file"
+ */
+function collectCommands(dir, prefix) {
+  const results = [];
+  const entries = readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const newPrefix = prefix ? `${prefix}:${entry.name}` : entry.name;
+      results.push(...collectCommands(join(dir, entry.name), newPrefix));
+    } else if (entry.name.endsWith('.md')) {
+      const name = entry.name.replace('.md', '');
+      const cmdPath = prefix ? `${prefix}:${name}` : name;
+      results.push(cmdPath);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Recursively collect agent names from directory structure.
+ */
+function collectAgents(dir) {
+  const results = [];
+  const entries = readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      results.push(...collectAgents(join(dir, entry.name)));
+    } else if (entry.name.endsWith('.md')) {
+      // Try to read the agent name from frontmatter
+      const name = extractFrontmatterName(join(dir, entry.name)) ||
+        entry.name.replace('.md', '');
+      results.push(name);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Extract the 'name' field from YAML frontmatter.
+ */
+function extractFrontmatterName(filePath) {
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!fmMatch) return null;
+    const nameMatch = fmMatch[1].match(/^name:\s*(.+)$/m);
+    if (!nameMatch) return null;
+    return nameMatch[1].trim().replace(/['"]/g, '');
+  } catch {
+    return null;
+  }
+}
+
+function readManifest() {
+  const content = readFile(join(ONION_HOME, 'manifest.json'));
+  if (!content) return null;
+  try {
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}

package/src/commands/uninstall.js

@@ -0,0 +1,90 @@
+import { readdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import {
+  ONION_HOME, ONION_MANIFEST, ONION_COMMANDS, ONION_AGENTS,
+  CLAUDE_SKILLS, CLAUDE_MD
+} from '../utils/paths.js';
+import { readFile, writeFile, removeDir, exists } from '../utils/fs.js';
+import * as log from '../utils/log.js';
+
+const CLAUDE_MD_MARKER_START = '# === Onion Framework (auto-managed — do not edit) ===';
+const CLAUDE_MD_MARKER_END = '# === End Onion Framework ===';
+
+export async function uninstall(opts = {}) {
+  log.header('Onion Framework Uninstaller');
+
+  if (!exists(ONION_HOME) && !exists(ONION_COMMANDS)) {
+    log.warn('Onion Framework is not installed');
+    return;
+  }
+
+  // 1. Remove commands
+  log.step('Removing commands...');
+  if (exists(ONION_COMMANDS)) {
+    removeDir(ONION_COMMANDS);
+    log.success('Removed commands from ~/.claude/commands/onion/');
+  }
+
+  // 2. Remove agents
+  log.step('Removing agents...');
+  if (exists(ONION_AGENTS)) {
+    removeDir(ONION_AGENTS);
+    log.success('Removed agents from ~/.claude/agents/onion/');
+  }
+
+  // 3. Remove onion-prefixed skills
+  log.step('Removing skills...');
+  if (existsSync(CLAUDE_SKILLS)) {
+    const entries = readdirSync(CLAUDE_SKILLS, { withFileTypes: true });
+    let removed = 0;
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name.startsWith('onion-')) {
+        removeDir(join(CLAUDE_SKILLS, entry.name));
+        removed++;
+      }
+    }
+    if (removed > 0) {
+      log.success(`Removed ${removed} skills from ~/.claude/skills/`);
+    }
+  }
+
+  // 4. Remove framework home
+  log.step('Removing framework core...');
+  if (exists(ONION_HOME)) {
+    removeDir(ONION_HOME);
+    log.success('Removed ~/.claude/onion/');
+  }
+
+  // 5. Unpatch CLAUDE.md
+  log.step('Restoring Claude Code configuration...');
+  unpatchClaudeMd();
+  log.success('Restored ~/.claude/CLAUDE.md');
+
+  log.blank();
+  log.header('Uninstall complete');
+  log.info('The Onion Framework has been removed.');
+  log.info('Your Claude Code configuration is intact.');
+  log.blank();
+}
+
+/**
+ * Remove the Onion block from CLAUDE.md.
+ */
+function unpatchClaudeMd() {
+  let content = readFile(CLAUDE_MD);
+  if (!content) return;
+
+  const startIdx = content.indexOf(CLAUDE_MD_MARKER_START);
+  const endIdx = content.indexOf(CLAUDE_MD_MARKER_END);
+
+  if (startIdx === -1 || endIdx === -1) return;
+
+  content = content.substring(0, startIdx).trimEnd() +
+    '\n' +
+    content.substring(endIdx + CLAUDE_MD_MARKER_END.length).trimStart();
+
+  // Clean up excess blank lines
+  content = content.replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+
+  writeFile(CLAUDE_MD, content);
+}

package/src/commands/update.js

@@ -0,0 +1,26 @@
+import { readFile } from '../utils/fs.js';
+import { ONION_MANIFEST } from '../utils/paths.js';
+import * as log from '../utils/log.js';
+
+export async function update() {
+  log.header('Onion Framework Update');
+
+  // Read current manifest
+  const manifestContent = readFile(ONION_MANIFEST);
+  if (!manifestContent) {
+    log.error('Onion Framework is not installed');
+    log.info('Run: npx @onion-ai/cli install');
+    process.exit(1);
+  }
+
+  const manifest = JSON.parse(manifestContent);
+  log.info(`Current version: ${manifest.version}`);
+
+  // Re-run install with --force
+  log.step('Reinstalling framework...');
+  const { install } = await import('./install.js');
+  await install({ force: true });
+
+  log.blank();
+  log.success('Update complete');
+}

package/src/utils/fs.js

@@ -0,0 +1,89 @@
+import { existsSync, mkdirSync, cpSync, rmSync, readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { join, relative } from 'path';
+
+/**
+ * Ensure a directory exists, creating it recursively if needed.
+ */
+export function ensureDir(dir) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Copy a directory recursively.
+ */
+export function copyDir(src, dest) {
+  ensureDir(dest);
+  cpSync(src, dest, { recursive: true });
+}
+
+/**
+ * Remove a directory recursively.
+ */
+export function removeDir(dir) {
+  if (existsSync(dir)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Read a file as UTF-8 string. Returns null if not found.
+ */
+export function readFile(filePath) {
+  if (!existsSync(filePath)) return null;
+  return readFileSync(filePath, 'utf-8');
+}
+
+/**
+ * Write a string to a file, creating parent directories if needed.
+ */
+export function writeFile(filePath, content) {
+  const dir = filePath.substring(0, filePath.lastIndexOf('/'));
+  ensureDir(dir);
+  writeFileSync(filePath, content, 'utf-8');
+}
+
+/**
+ * Check if a path exists.
+ */
+export function exists(p) {
+  return existsSync(p);
+}
+
+/**
+ * Count files in a directory recursively.
+ */
+export function countFiles(dir, ext = '.md') {
+  if (!existsSync(dir)) return 0;
+  let count = 0;
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      count += countFiles(fullPath, ext);
+    } else if (entry.name.endsWith(ext)) {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * List all files in a directory recursively.
+ */
+export function listFiles(dir, ext = null) {
+  const results = [];
+  if (!existsSync(dir)) return results;
+
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...listFiles(fullPath, ext));
+    } else if (!ext || entry.name.endsWith(ext)) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}

package/src/utils/log.js

@@ -0,0 +1,35 @@
+const RESET = '\x1b[0m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const CYAN = '\x1b[36m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+
+export function success(msg) {
+  console.log(`${GREEN}  ✓${RESET} ${msg}`);
+}
+
+export function warn(msg) {
+  console.log(`${YELLOW}  ⚠${RESET} ${msg}`);
+}
+
+export function error(msg) {
+  console.log(`${RED}  ✗${RESET} ${msg}`);
+}
+
+export function info(msg) {
+  console.log(`${CYAN}  ℹ${RESET} ${msg}`);
+}
+
+export function step(msg) {
+  console.log(`${DIM}  →${RESET} ${msg}`);
+}
+
+export function header(msg) {
+  console.log(`\n${BOLD}${msg}${RESET}\n`);
+}
+
+export function blank() {
+  console.log('');
+}

package/src/utils/paths.js

@@ -0,0 +1,32 @@
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Root of the npm package (where package.json lives) */
+export const PACKAGE_ROOT = join(__dirname, '..', '..');
+
+/** The framework files shipped with the package */
+export const FRAMEWORK_SOURCE = join(PACKAGE_ROOT, 'framework');
+
+/** Claude Code global config directory */
+export const CLAUDE_HOME = join(homedir(), '.claude');
+
+/** Where Onion framework gets installed */
+export const ONION_HOME = join(CLAUDE_HOME, 'onion');
+
+/** Standard Claude Code discovery paths */
+export const CLAUDE_COMMANDS = join(CLAUDE_HOME, 'commands');
+export const CLAUDE_AGENTS = join(CLAUDE_HOME, 'agents');
+export const CLAUDE_SKILLS = join(CLAUDE_HOME, 'skills');
+
+/** Onion-namespaced paths within Claude's discovery directories */
+export const ONION_COMMANDS = join(CLAUDE_COMMANDS, 'onion');
+export const ONION_AGENTS = join(CLAUDE_AGENTS, 'onion');
+
+/** Claude Code main config file */
+export const CLAUDE_MD = join(CLAUDE_HOME, 'CLAUDE.md');
+
+/** Onion manifest (tracks what was installed) */
+export const ONION_MANIFEST = join(ONION_HOME, 'manifest.json');