@automagik/genie 0.260202.1901 → 0.260203.135

package/plugin/scripts/smart-install.js

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+/**
+ * Smart Install Script for automagik-genie
+ *
+ * Ensures required dependencies are installed:
+ * - Bun runtime (auto-installs if missing)
+ * - tmux (guides user if missing - can't auto-install)
+ * - beads (auto-installs if missing via npm)
+ *
+ * Also handles:
+ * - Dependency installation when version changes
+ * - CLI symlink creation for agent access
+ * - Version marker management
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, symlinkSync, unlinkSync } from 'fs';
+import { execSync, spawnSync } from 'child_process';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const ROOT = process.env.CLAUDE_PLUGIN_ROOT || join(homedir(), '.claude', 'plugins', 'automagik-genie');
+const GENIE_DIR = join(homedir(), '.genie');
+const MARKER = join(GENIE_DIR, '.install-version');
+const BIN_DIR = join(homedir(), '.local', 'bin');
+const IS_WINDOWS = process.platform === 'win32';
+
+// Common installation paths (handles fresh installs before PATH reload)
+const BUN_COMMON_PATHS = IS_WINDOWS
+  ? [join(homedir(), '.bun', 'bin', 'bun.exe')]
+  : [join(homedir(), '.bun', 'bin', 'bun'), '/usr/local/bin/bun', '/opt/homebrew/bin/bun'];
+
+const BEADS_COMMON_PATHS = IS_WINDOWS
+  ? [join(homedir(), 'AppData', 'Roaming', 'npm', 'bd.cmd')]
+  : [join(homedir(), '.local', 'bin', 'bd'), '/usr/local/bin/bd', '/opt/homebrew/bin/bd'];
+
+/**
+ * Get the Bun executable path
+ */
+function getBunPath() {
+  // Try PATH first
+  try {
+    const result = spawnSync('bun', ['--version'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    if (result.status === 0) return 'bun';
+  } catch {
+    // Not in PATH
+  }
+  return BUN_COMMON_PATHS.find(existsSync) || null;
+}
+
+function isBunInstalled() {
+  return getBunPath() !== null;
+}
+
+function getBunVersion() {
+  const bunPath = getBunPath();
+  if (!bunPath) return null;
+  try {
+    const result = spawnSync(bunPath, ['--version'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    return result.status === 0 ? result.stdout.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Install Bun automatically
+ */
+function installBun() {
+  console.error('Installing Bun runtime...');
+  try {
+    if (IS_WINDOWS) {
+      execSync('powershell -c "irm bun.sh/install.ps1 | iex"', { stdio: 'inherit', shell: true });
+    } else {
+      execSync('curl -fsSL https://bun.sh/install | bash', { stdio: 'inherit', shell: true });
+    }
+    if (!isBunInstalled()) {
+      throw new Error('Bun installation completed but binary not found. Please restart your terminal.');
+    }
+    console.error(`Bun ${getBunVersion()} installed`);
+  } catch (error) {
+    console.error('Failed to install Bun. Please install manually:');
+    if (IS_WINDOWS) {
+      console.error('  winget install Oven-sh.Bun');
+    } else {
+      console.error('  curl -fsSL https://bun.sh/install | bash');
+    }
+    throw error;
+  }
+}
+
+/**
+ * Check if tmux is installed
+ */
+function isTmuxInstalled() {
+  try {
+    const result = spawnSync('tmux', ['-V'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get tmux version
+ */
+function getTmuxVersion() {
+  try {
+    const result = spawnSync('tmux', ['-V'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    return result.status === 0 ? result.stdout.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if beads (bd) is installed
+ */
+function getBeadsPath() {
+  try {
+    const result = spawnSync('bd', ['--version'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    if (result.status === 0) return 'bd';
+  } catch {
+    // Not in PATH
+  }
+  return BEADS_COMMON_PATHS.find(existsSync) || null;
+}
+
+function isBeadsInstalled() {
+  return getBeadsPath() !== null;
+}
+
+/**
+ * Install beads via npm
+ */
+function installBeads() {
+  console.error('Installing beads (bd)...');
+  try {
+    execSync('npm install -g @anthropic-ai/bd', { stdio: 'inherit', shell: true });
+    if (!isBeadsInstalled()) {
+      throw new Error('beads installation completed but bd not found.');
+    }
+    console.error('beads installed');
+  } catch (error) {
+    console.error('Failed to install beads. Please install manually:');
+    console.error('  npm install -g @anthropic-ai/bd');
+    throw error;
+  }
+}
+
+/**
+ * Check if dependencies need to be installed
+ */
+function needsInstall() {
+  if (!existsSync(join(ROOT, 'node_modules'))) return true;
+  if (!existsSync(join(ROOT, 'package.json'))) return false; // No package.json = no deps needed
+
+  try {
+    const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8'));
+    if (!existsSync(MARKER)) return true;
+    const marker = JSON.parse(readFileSync(MARKER, 'utf-8'));
+    return pkg.version !== marker.version || getBunVersion() !== marker.bun;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Install dependencies using Bun
+ */
+function installDeps() {
+  const bunPath = getBunPath();
+  if (!bunPath) {
+    throw new Error('Bun executable not found');
+  }
+
+  console.error('Installing dependencies...');
+
+  // Ensure .genie directory exists
+  if (!existsSync(GENIE_DIR)) {
+    mkdirSync(GENIE_DIR, { recursive: true });
+  }
+
+  const bunCmd = IS_WINDOWS && bunPath.includes(' ') ? `"${bunPath}"` : bunPath;
+  execSync(`${bunCmd} install`, { cwd: ROOT, stdio: 'inherit', shell: IS_WINDOWS });
+
+  // Write version marker
+  let version = 'unknown';
+  try {
+    const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8'));
+    version = pkg.version;
+  } catch {
+    // Ignore
+  }
+
+  writeFileSync(MARKER, JSON.stringify({
+    version,
+    bun: getBunVersion(),
+    tmux: getTmuxVersion(),
+    installedAt: new Date().toISOString()
+  }));
+}
+
+/**
+ * Create CLI symlinks for agent access
+ */
+function createCliSymlinks() {
+  // Ensure bin directory exists
+  if (!existsSync(BIN_DIR)) {
+    mkdirSync(BIN_DIR, { recursive: true });
+  }
+
+  const links = [
+    { name: 'genie', target: join(ROOT, 'scripts', 'genie.cjs') },
+    { name: 'term', target: join(ROOT, 'scripts', 'term.cjs') }
+  ];
+
+  for (const { name, target } of links) {
+    const linkPath = join(BIN_DIR, name);
+
+    // Skip if target doesn't exist
+    if (!existsSync(target)) {
+      continue;
+    }
+
+    // Remove existing symlink if it exists
+    try {
+      if (existsSync(linkPath)) {
+        unlinkSync(linkPath);
+      }
+    } catch {
+      // Ignore errors
+    }
+
+    // Create symlink
+    try {
+      symlinkSync(target, linkPath);
+      console.error(`Created symlink: ${linkPath} -> ${target}`);
+    } catch (error) {
+      console.error(`Warning: Could not create symlink for ${name}: ${error.message}`);
+    }
+  }
+}
+
+// Main execution
+try {
+  // 1. Check/install Bun
+  if (!isBunInstalled()) {
+    installBun();
+  }
+
+  // 2. Check tmux - REQUIRED, but can't auto-install
+  if (!isTmuxInstalled()) {
+    console.error('');
+    console.error('ERROR: tmux is required but not installed.');
+    console.error('');
+    console.error('Please install tmux manually:');
+    if (process.platform === 'darwin') {
+      console.error('  brew install tmux');
+    } else if (process.platform === 'linux') {
+      console.error('  sudo apt install tmux    # Debian/Ubuntu');
+      console.error('  sudo dnf install tmux    # Fedora/RHEL');
+      console.error('  sudo pacman -S tmux      # Arch');
+    } else if (IS_WINDOWS) {
+      console.error('  WSL is required for tmux on Windows');
+      console.error('  Inside WSL: sudo apt install tmux');
+    }
+    console.error('');
+    console.error('Then restart Claude Code.');
+    process.exit(2); // Exit code 2 = blocking error for Claude to process
+  }
+
+  // 3. Check/install beads
+  if (!isBeadsInstalled()) {
+    installBeads();
+  }
+
+  // 4. Install dependencies if needed
+  if (needsInstall()) {
+    installDeps();
+    console.error('Dependencies installed');
+  }
+
+  // 5. Create CLI symlinks
+  createCliSymlinks();
+
+} catch (e) {
+  console.error('Installation failed:', e.message);
+  process.exit(1);
+}

package/plugin/scripts/src/install-genie-cli.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+#
+# Install genie-cli globally via npm/bun
+# This script is included with the automagik-genie plugin
+#
+
+usage() {
+  cat <<'EOF'
+Usage:
+  install-genie-cli.sh [--global | --local]
+
+Installs genie-cli, the companion CLI for the automagik-genie plugin.
+
+Options:
+  --global    Install globally to ~/.local/bin (default)
+  --local     Install to current directory's node_modules
+
+The global install creates a symlink at ~/.local/bin/genie
+that points to the installed genie-cli binary.
+EOF
+}
+
+INSTALL_MODE="global"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --global)
+      INSTALL_MODE="global"; shift ;;
+    --local)
+      INSTALL_MODE="local"; shift ;;
+    -h|--help)
+      usage; exit 0 ;;
+    *)
+      echo "Unknown arg: $1" >&2
+      usage
+      exit 2
+      ;;
+  esac
+done
+
+# Determine plugin root (relative to this script)
+PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+GENIE_CLI_ROOT="$(cd "$PLUGIN_ROOT/.." && pwd)"
+
+echo "Installing genie-cli from: $GENIE_CLI_ROOT"
+
+# Check for package manager
+if command -v bun &>/dev/null; then
+  PKG_MGR="bun"
+elif command -v npm &>/dev/null; then
+  PKG_MGR="npm"
+else
+  echo "Error: Neither bun nor npm found. Install one first." >&2
+  exit 1
+fi
+
+echo "Using package manager: $PKG_MGR"
+
+if [[ "$INSTALL_MODE" == "global" ]]; then
+  # Global install approach: link from ~/.local/bin
+  mkdir -p ~/.local/bin
+
+  # Install dependencies in genie-cli directory
+  echo "Installing dependencies..."
+  cd "$GENIE_CLI_ROOT"
+  $PKG_MGR install
+
+  # Create symlink
+  GENIE_BIN="$GENIE_CLI_ROOT/src/cli.ts"
+  if [[ -f "$GENIE_BIN" ]]; then
+    # For bun, we can use the TypeScript directly
+    if [[ "$PKG_MGR" == "bun" ]]; then
+      # Create a wrapper script
+      cat > ~/.local/bin/genie <<EOF
+#!/usr/bin/env bash
+exec bun "$GENIE_BIN" "\$@"
+EOF
+      chmod +x ~/.local/bin/genie
+      echo "Created wrapper at ~/.local/bin/genie"
+    else
+      # For npm, need to build first
+      echo "Building genie-cli..."
+      $PKG_MGR run build 2>/dev/null || true
+      if [[ -f "$GENIE_CLI_ROOT/dist/cli.js" ]]; then
+        ln -sf "$GENIE_CLI_ROOT/dist/cli.js" ~/.local/bin/genie
+        chmod +x ~/.local/bin/genie
+        echo "Linked to ~/.local/bin/genie"
+      else
+        echo "Warning: Build failed, using TypeScript source with bun" >&2
+        cat > ~/.local/bin/genie <<EOF
+#!/usr/bin/env bash
+exec bun "$GENIE_BIN" "\$@"
+EOF
+        chmod +x ~/.local/bin/genie
+      fi
+    fi
+  else
+    echo "Error: genie-cli binary not found at $GENIE_BIN" >&2
+    exit 1
+  fi
+
+  echo ""
+  echo "genie-cli installed successfully!"
+  echo ""
+  echo "Make sure ~/.local/bin is in your PATH:"
+  echo "  export PATH=\"\$HOME/.local/bin:\$PATH\""
+  echo ""
+  echo "Then run: genie --help"
+
+else
+  # Local install
+  echo "Installing genie-cli locally..."
+  cd "$GENIE_CLI_ROOT"
+  $PKG_MGR install
+  echo ""
+  echo "genie-cli installed locally."
+  echo "Run with: $PKG_MGR run genie --help"
+fi

package/plugin/scripts/src/validate-completion.ts

@@ -0,0 +1,142 @@
+#!/usr/bin/env bun
+/**
+ * Validate forge completion before session ends.
+ * Used by Stop hook to check if all tasks are complete.
+ *
+ * Usage: bun validate-completion.ts --session <session-id>
+ *        bun validate-completion.ts --help
+ *
+ * This script is advisory-only (exits 0) but logs warnings if:
+ * - Active wish exists with incomplete tasks
+ * - Tasks are marked BLOCKED
+ */
+
+import { parseArgs } from "util";
+import { readdirSync, readFileSync, existsSync } from "fs";
+import { join } from "path";
+
+const { values } = parseArgs({
+  args: Bun.argv.slice(2),
+  options: {
+    session: { type: "string", short: "s" },
+    help: { type: "boolean", short: "h" },
+  },
+  strict: true,
+});
+
+if (values.help) {
+  console.log(`
+validate-completion.ts - Check forge completion status
+
+Usage:
+  bun validate-completion.ts --session <session-id>
+  bun validate-completion.ts --help
+
+Options:
+  -s, --session   Session ID (currently unused, for future integration)
+  -h, --help      Show this help message
+
+This script checks for incomplete work and logs warnings.
+It always exits 0 (advisory only).
+`);
+  process.exit(0);
+}
+
+interface WishStatus {
+  slug: string;
+  status: string;
+  incompleteTasks: number;
+  blockedTasks: number;
+  totalTasks: number;
+}
+
+function findWishes(baseDir: string): WishStatus[] {
+  const wishesDir = join(baseDir, ".genie", "wishes");
+  const results: WishStatus[] = [];
+
+  if (!existsSync(wishesDir)) {
+    return results;
+  }
+
+  try {
+    const slugs = readdirSync(wishesDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+
+    for (const slug of slugs) {
+      const wishFile = join(wishesDir, slug, "wish.md");
+      if (!existsSync(wishFile)) continue;
+
+      const content = readFileSync(wishFile, "utf-8");
+
+      // Extract status
+      const statusMatch = content.match(/^\*\*Status:\*\*\s*(\w+)/m);
+      const status = statusMatch ? statusMatch[1] : "UNKNOWN";
+
+      // Skip completed wishes
+      if (status === "DONE") continue;
+
+      // Count execution group tasks
+      const groupMatches = content.match(/^###\s+Group\s+[A-Z]:/gm) || [];
+      const totalTasks = groupMatches.length;
+
+      // Count unchecked acceptance criteria (rough proxy for incomplete tasks)
+      const uncheckedCriteria = (content.match(/^-\s+\[\s+\]/gm) || []).length;
+      const checkedCriteria = (content.match(/^-\s+\[x\]/gim) || []).length;
+
+      // Check for BLOCKED mentions
+      const blockedMentions = (content.match(/BLOCKED/gi) || []).length;
+
+      results.push({
+        slug,
+        status,
+        incompleteTasks: uncheckedCriteria > 0 ? Math.ceil(uncheckedCriteria / 3) : 0, // Rough estimate
+        blockedTasks: blockedMentions > 0 ? 1 : 0,
+        totalTasks,
+      });
+    }
+  } catch (error) {
+    // Silent failure - don't block session end
+  }
+
+  return results;
+}
+
+// Find wishes from current directory
+const cwd = process.cwd();
+const wishes = findWishes(cwd);
+
+// Filter to active wishes (IN_PROGRESS)
+const activeWishes = wishes.filter((w) => w.status === "IN_PROGRESS");
+
+if (activeWishes.length === 0) {
+  // No active wishes, nothing to report
+  process.exit(0);
+}
+
+// Log warnings for incomplete work
+let hasWarnings = false;
+
+for (const wish of activeWishes) {
+  if (wish.incompleteTasks > 0 || wish.blockedTasks > 0) {
+    hasWarnings = true;
+    console.log(`\n⚠ Active wish "${wish.slug}" has incomplete work:`);
+
+    if (wish.incompleteTasks > 0) {
+      console.log(`  - ~${wish.incompleteTasks} tasks with unchecked criteria`);
+    }
+
+    if (wish.blockedTasks > 0) {
+      console.log(`  - ${wish.blockedTasks} BLOCKED task(s) need attention`);
+    }
+
+    console.log(`  Run /forge to continue or /review to validate.`);
+  }
+}
+
+if (hasWarnings) {
+  console.log("");
+}
+
+// Always exit 0 (advisory only)
+process.exit(0);

package/plugin/scripts/src/validate-wish.ts

@@ -0,0 +1,137 @@
+#!/usr/bin/env bun
+/**
+ * Validate a wish document structure before writing.
+ * Used by PreToolUse hook to catch missing sections.
+ *
+ * Usage: bun validate-wish.ts --file <path-to-wish.md>
+ *        bun validate-wish.ts --help
+ */
+
+import { parseArgs } from "util";
+import { readFileSync, existsSync } from "fs";
+
+const { values } = parseArgs({
+  args: Bun.argv.slice(2),
+  options: {
+    file: { type: "string", short: "f" },
+    help: { type: "boolean", short: "h" },
+  },
+  strict: true,
+});
+
+if (values.help) {
+  console.log(`
+validate-wish.ts - Validate wish document structure
+
+Usage:
+  bun validate-wish.ts --file <path-to-wish.md>
+  bun validate-wish.ts --help
+
+Options:
+  -f, --file   Path to wish document to validate
+  -h, --help   Show this help message
+
+Exit codes:
+  0  Validation passed
+  1  Validation failed (missing required sections)
+  2  Invalid arguments or file not found
+`);
+  process.exit(0);
+}
+
+if (!values.file) {
+  console.error("Error: --file is required");
+  process.exit(2);
+}
+
+if (!existsSync(values.file)) {
+  // File doesn't exist yet (being created), skip validation
+  console.log("File not found, skipping validation (new file)");
+  process.exit(0);
+}
+
+const content = readFileSync(values.file, "utf-8");
+
+interface ValidationResult {
+  passed: boolean;
+  issues: string[];
+}
+
+function validateWish(content: string): ValidationResult {
+  const issues: string[] = [];
+
+  // Required sections
+  const requiredSections = [
+    { pattern: /^##\s+Summary/m, name: "## Summary" },
+    { pattern: /^##\s+Scope/m, name: "## Scope" },
+    { pattern: /^###\s+IN/m, name: "### IN (under Scope)" },
+    { pattern: /^###\s+OUT/m, name: "### OUT (under Scope)" },
+    { pattern: /^##\s+Success Criteria/m, name: "## Success Criteria" },
+    { pattern: /^##\s+Execution Groups/m, name: "## Execution Groups" },
+  ];
+
+  for (const { pattern, name } of requiredSections) {
+    if (!pattern.test(content)) {
+      issues.push(`Missing required section: ${name}`);
+    }
+  }
+
+  // Check for at least one execution group
+  const groupPattern = /^###\s+Group\s+[A-Z]:/m;
+  if (!groupPattern.test(content)) {
+    issues.push("Missing execution group (need at least one ### Group X: section)");
+  }
+
+  // Check for acceptance criteria in groups
+  const groups = content.match(/^###\s+Group\s+[A-Z]:.*/gm) || [];
+  if (groups.length > 0) {
+    // Check if Acceptance Criteria exists somewhere after Execution Groups
+    const execGroupsIndex = content.indexOf("## Execution Groups");
+    const afterExecGroups = content.slice(execGroupsIndex);
+
+    if (!afterExecGroups.includes("**Acceptance Criteria:**")) {
+      issues.push("Execution groups should have **Acceptance Criteria:** sections");
+    }
+
+    if (!afterExecGroups.includes("**Validation:**")) {
+      issues.push("Execution groups should have **Validation:** command sections");
+    }
+  }
+
+  // Check that OUT scope is not empty
+  const outMatch = content.match(/^###\s+OUT\s*\n([\s\S]*?)(?=^##|^###|\n---|\Z)/m);
+  if (outMatch) {
+    const outContent = outMatch[1].trim();
+    // Check if it only has placeholder text or is empty
+    if (!outContent || outContent === "-" || outContent.match(/^-\s*$/)) {
+      issues.push("OUT scope should not be empty - add explicit exclusions");
+    }
+  }
+
+  // Check for success criteria checkboxes
+  const successSection = content.match(/^##\s+Success Criteria\s*\n([\s\S]*?)(?=^##|\n---|\Z)/m);
+  if (successSection) {
+    const checkboxes = successSection[1].match(/^-\s+\[\s*\]/gm) || [];
+    if (checkboxes.length === 0) {
+      issues.push("Success Criteria should have checkbox items (- [ ])");
+    }
+  }
+
+  return {
+    passed: issues.length === 0,
+    issues,
+  };
+}
+
+const result = validateWish(content);
+
+if (result.passed) {
+  console.log("✓ Wish document validation passed");
+  process.exit(0);
+} else {
+  console.log("⚠ Wish document validation issues:");
+  for (const issue of result.issues) {
+    console.log(`  - ${issue}`);
+  }
+  process.exit(1);
+}