@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/channel/manager.mjs

@@ -0,0 +1,504 @@
+/**
+ * Channel Manager
+ *
+ * Manages the distribution channel (stable vs edge) for AIWG.
+ * - Stable: Uses the npm-installed package
+ * - Edge: Uses a git clone of the main branch for bleeding-edge updates
+ *
+ * @module src/channel/manager
+ * @version 2024.12.0
+ */
+
+import fs from 'fs/promises';
+import { readFileSync, existsSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { execSync, spawn } from 'child_process';
+import os from 'os';
+
+/**
+ * Run a command with inherited stdio, applying a wall-clock timeout so a
+ * slow or hung git fetch cannot wedge the CLI for minutes. On timeout the
+ * child is SIGTERM'd and escalated to SIGKILL after 5s if it does not exit.
+ * Rejects with an Error carrying `.code = 'ETIMEDOUT'` on timeout or the
+ * original exit code otherwise.
+ *
+ * Replaces execSync() sites that had no timeout. Overridable via
+ * AIWG_GIT_TIMEOUT_MS (default 60s — fetch/pull on slow networks can take
+ * a while but must eventually terminate).
+ */
+async function runWithTimeout(cmd, args, options = {}) {
+  const timeoutMs = (() => {
+    const raw = process.env['AIWG_GIT_TIMEOUT_MS'];
+    const n = raw ? parseInt(raw, 10) : NaN;
+    return Number.isFinite(n) && n > 0 ? n : 60_000;
+  })();
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      stdio: 'inherit',
+      ...options,
+    });
+
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      try { child.kill('SIGTERM'); } catch { /* already exited */ }
+      const kill9 = setTimeout(() => {
+        try { child.kill('SIGKILL'); } catch { /* already exited */ }
+      }, 5_000);
+      kill9.unref?.();
+      settled = true;
+      const err = new Error(`\`${cmd} ${args.join(' ')}\` timed out after ${timeoutMs}ms`);
+      err.code = 'ETIMEDOUT';
+      reject(err);
+    }, timeoutMs);
+    timer.unref?.();
+
+    child.on('close', (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (code === 0) resolve();
+      else {
+        const err = new Error(`\`${cmd} ${args.join(' ')}\` exited with code ${code}`);
+        err.code = code ?? 1;
+        reject(err);
+      }
+    });
+
+    child.on('error', (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Configuration paths
+const CONFIG_DIR = path.join(os.homedir(), '.aiwg');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'channel.json');
+const EDGE_INSTALL_PATH = path.join(os.homedir(), '.local', 'share', 'ai-writing-guide');
+const REPO_URL = 'https://github.com/jmagly/aiwg.git';
+
+/**
+ * Default channel configuration
+ */
+const DEFAULT_CONFIG = {
+  channel: 'stable',
+  edgePath: EDGE_INSTALL_PATH,
+  lastUpdateCheck: null,
+  updateCheckInterval: 86400000, // 24 hours in ms
+};
+
+/**
+ * Get the package root directory.
+ *
+ * Walks up from this file's directory looking for the nearest package.json
+ * that names "aiwg". This works whether this module runs from its source
+ * location (`src/channel/manager.mjs`) or from its compiled-build copy
+ * (`dist/src/channel/manager.mjs`), both of which have package.json at
+ * the repo root.
+ *
+ * The walk is bounded to 10 levels as a safety cap.
+ *
+ * @returns {string} Path to package root
+ */
+export function getPackageRoot() {
+  let dir = __dirname;
+  for (let i = 0; i < 10; i++) {
+    const pkg = path.join(dir, 'package.json');
+    if (existsSync(pkg)) {
+      try {
+        const content = JSON.parse(readFileSync(pkg, 'utf8'));
+        if (content.name === 'aiwg') return dir;
+      } catch {
+        // keep walking
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // Fallback to the legacy hardcoded two-up resolution.
+  return path.resolve(__dirname, '..', '..');
+}
+
+/**
+ * Load channel configuration
+ * @returns {Promise<object>} Channel configuration
+ */
+export async function loadConfig() {
+  try {
+    const data = await fs.readFile(CONFIG_FILE, 'utf8');
+    return { ...DEFAULT_CONFIG, ...JSON.parse(data) };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+
+/**
+ * Save channel configuration
+ * @param {object} config - Configuration to save
+ */
+export async function saveConfig(config) {
+  await fs.mkdir(CONFIG_DIR, { recursive: true });
+  await fs.writeFile(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+/**
+ * Get the current channel
+ * @returns {Promise<string>} 'stable' or 'edge'
+ */
+export async function getChannel() {
+  const config = await loadConfig();
+  return config.channel;
+}
+
+/**
+ * Get the framework root path based on current channel
+ * @returns {Promise<string>} Path to framework root
+ */
+export async function getFrameworkRoot() {
+  const config = await loadConfig();
+
+  if (config.channel === 'edge') {
+    // Check if edge installation exists
+    try {
+      await fs.access(config.edgePath);
+      return config.edgePath;
+    } catch {
+      // Edge path doesn't exist, fall back to stable
+      console.warn('Edge installation not found, using stable channel');
+      return getPackageRoot();
+    }
+  }
+
+  return getPackageRoot();
+}
+
+/**
+ * Switch to edge (bleeding edge) channel
+ * Clones or updates the git repository for latest main branch
+ */
+export async function switchToEdge() {
+  const config = await loadConfig();
+
+  console.log('Switching to edge channel (bleeding edge from main branch)...');
+  console.log('');
+
+  // Check if edge installation exists
+  const edgeExists = await fs.access(config.edgePath).then(() => true).catch(() => false);
+
+  if (edgeExists) {
+    // Update existing installation
+    console.log(`Updating edge installation at ${config.edgePath}...`);
+    try {
+      await runWithTimeout('git', ['fetch', '--all'], { cwd: config.edgePath });
+      await runWithTimeout('git', ['checkout', 'main'], { cwd: config.edgePath });
+      await runWithTimeout('git', ['pull', '--ff-only'], { cwd: config.edgePath });
+      // Ensure sparse checkout excludes .aiwg/ on existing installs
+      try {
+        const sparseConfig = path.join(config.edgePath, '.git', 'info', 'sparse-checkout');
+        const hasSparse = await fs.access(sparseConfig).then(() => true).catch(() => false);
+        if (!hasSparse) {
+          execSync('git sparse-checkout init --cone', { cwd: config.edgePath, stdio: 'pipe' });
+          execSync('git sparse-checkout set --no-cone "/*" "!/.aiwg"', { cwd: config.edgePath, stdio: 'pipe' });
+        }
+      } catch {
+        // Sparse checkout is optional — older git may not support it
+      }
+      console.log('Edge installation updated successfully.');
+    } catch (error) {
+      console.error('Failed to update edge installation:', error.message);
+      console.log('Try removing the directory and running again:');
+      console.log(`  rm -rf ${config.edgePath}`);
+      console.log('  aiwg --use-main');
+      process.exit(1);
+    }
+  } else {
+    // Clone fresh
+    console.log(`Cloning repository to ${config.edgePath}...`);
+    await fs.mkdir(path.dirname(config.edgePath), { recursive: true });
+    try {
+      execSync(`git clone --branch main ${REPO_URL} "${config.edgePath}"`, { stdio: 'inherit' });
+      // Exclude dogfooding artifacts from edge clones — users want framework source only
+      try {
+        execSync('git sparse-checkout init --cone', { cwd: config.edgePath, stdio: 'pipe' });
+        execSync('git sparse-checkout set --no-cone "/*" "!/.aiwg"', { cwd: config.edgePath, stdio: 'pipe' });
+      } catch {
+        // Sparse checkout is optional — older git versions may not support it
+        console.log('Note: sparse checkout not available, .aiwg/ will be present in edge install.');
+      }
+      console.log('Edge installation created successfully.');
+    } catch (error) {
+      console.error('Failed to clone repository:', error.message);
+      process.exit(1);
+    }
+  }
+
+  // Update config
+  config.channel = 'edge';
+  await saveConfig(config);
+
+  console.log('');
+  console.log('Switched to edge channel.');
+  console.log('You are now using the latest code from the main branch.');
+  console.log('');
+  console.log('To update edge installation: aiwg -update');
+  console.log('To switch back to stable:   aiwg --use-stable');
+}
+
+/**
+ * Switch to dev mode (use local repo as both framework source and CLI)
+ *
+ * In dev mode, the CLI entry point delegates to the dev repo's facade,
+ * so all code (including `aiwg index`, `aiwg use`, etc.) runs from the
+ * local build rather than the npm-installed package.
+ *
+ * @param {string} devPath - Path to the local development repository
+ */
+export async function switchToDev(devPath) {
+  const config = await loadConfig();
+
+  const resolvedPath = path.resolve(devPath);
+
+  console.log('Switching to dev mode (local repository source)...');
+  console.log('');
+
+  // Verify the path looks like an AIWG repo
+  try {
+    await fs.access(path.join(resolvedPath, 'agentic', 'code', 'frameworks'));
+  } catch {
+    console.error(`Error: ${resolvedPath} does not appear to be an AIWG repository.`);
+    console.error('Expected to find agentic/code/frameworks/ directory.');
+    process.exit(1);
+  }
+
+  // Verify compiled router exists (dev-mode dispatch imports from dist/).
+  // Accept repos that have never been built by emitting a clear build hint
+  // rather than hard-failing here — the first `aiwg` invocation will re-check
+  // and print the same hint. This lets `aiwg --use-dev /path/to/fresh/clone`
+  // succeed followed by `npm run build`.
+  const distRouter = path.join(resolvedPath, 'dist', 'src', 'cli', 'router.js');
+  const distExists = await fs.access(distRouter).then(() => true).catch(() => false);
+
+  config.channel = 'edge';
+  config.edgePath = resolvedPath;
+  config.devMode = true;
+  await saveConfig(config);
+
+  console.log('Switched to dev mode.');
+  console.log(`Dev repo:    ${resolvedPath}`);
+  console.log(`Router:      ${distRouter}`);
+  if (!distExists) {
+    console.log('');
+    console.log('NOTE: dist/ is not built yet. Before running aiwg commands:');
+    console.log(`  (cd ${resolvedPath} && npm run build)`);
+  }
+  console.log('');
+  console.log('The aiwg command now runs the compiled router from your local repo.');
+  console.log('After making changes, run: npm run build');
+  console.log('');
+  console.log('Commands:');
+  console.log('  aiwg use all          Deploy from local source');
+  console.log('  aiwg version          Verify dev mode active');
+  console.log('  aiwg --use-stable     Switch back to npm package');
+}
+
+/**
+ * Switch to next (alpha/beta/RC) channel
+ * Installs the latest pre-release from the `next` dist-tag
+ */
+export async function switchToNext() {
+  const config = await loadConfig();
+
+  console.log('Switching to next channel (alpha/beta/RC — latest pre-release)...');
+  console.log('');
+
+  try {
+    execSync('npm install -g aiwg@next', { stdio: 'inherit' });
+  } catch (error) {
+    console.error('Failed to install aiwg@next:', error.message);
+    console.error('Check that npm is available and you have write access to the global prefix.');
+    process.exit(1);
+  }
+
+  config.channel = 'next';
+  config.devMode = false;
+  await saveConfig(config);
+
+  console.log('');
+  console.log('Switched to next channel.');
+  console.log('You are now running the latest alpha/beta/RC release.');
+  console.log('');
+  console.log('To see what version you installed: aiwg version');
+  console.log('To switch back to stable:          aiwg sync --channel latest');
+}
+
+/**
+ * Switch to nightly channel
+ * Installs the latest nightly snapshot from the `nightly` dist-tag
+ */
+export async function switchToNightly() {
+  const config = await loadConfig();
+
+  console.log('Switching to nightly channel (latest automated snapshot)...');
+  console.log('');
+
+  try {
+    execSync('npm install -g aiwg@nightly', { stdio: 'inherit' });
+  } catch (error) {
+    console.error('Failed to install aiwg@nightly:', error.message);
+    console.error('Check that npm is available and you have write access to the global prefix.');
+    process.exit(1);
+  }
+
+  config.channel = 'nightly';
+  config.devMode = false;
+  await saveConfig(config);
+
+  console.log('');
+  console.log('Switched to nightly channel.');
+  console.log('You are now running the latest automated nightly snapshot.');
+  console.log('');
+  console.log('To see what version you installed: aiwg version');
+  console.log('To switch back to stable:          aiwg sync --channel latest');
+}
+
+/**
+ * Switch to stable (npm) channel
+ */
+export async function switchToStable() {
+  const config = await loadConfig();
+
+  console.log('Switching to stable channel (npm package)...');
+  console.log('');
+
+  config.channel = 'stable';
+  config.devMode = false;
+  await saveConfig(config);
+
+  console.log('Switched to stable channel.');
+  console.log('You are now using the npm-installed package.');
+  console.log('');
+  console.log('To update: npm install -g aiwg@latest');
+  console.log('To switch to edge: aiwg --use-main');
+}
+
+/**
+ * Get version information based on current channel
+ * @returns {Promise<object>} Version info
+ */
+/**
+ * Normalize a package.json `repository` field (string or `{ url }`) into a clean
+ * `host/owner/repo` display form for version stamps — stripping the `git+`
+ * prefix, URL scheme, and `.git` suffix. Returns '' if none is declared.
+ *
+ * @param {string | { url?: string } | undefined} repository
+ * @returns {string}
+ */
+function normalizeRepoUrl(repository) {
+  const raw = typeof repository === 'string' ? repository : repository?.url || '';
+  return raw
+    .replace(/^git\+/, '')
+    .replace(/^git@([^:]+):/, '$1/')
+    .replace(/^[a-z]+:\/\//i, '')
+    .replace(/\.git$/, '')
+    .replace(/\/$/, '');
+}
+
+export async function getVersionInfo() {
+  const config = await loadConfig();
+  const packageRoot = getPackageRoot();
+
+  // Read package.json version
+  const packageJsonPath = path.join(packageRoot, 'package.json');
+  const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+
+  // Detect pre-release channel from version string when channel.json says 'stable'
+  // This handles the case where a user ran `npm install -g aiwg@next` directly —
+  // npm updates the binary but channel.json stays as 'stable'.
+  let channel = config.channel;
+  const version = packageJson.version;
+  if (!config.devMode && channel === 'stable') {
+    if (version.includes('-rc.')) {
+      channel = 'rc';
+    } else if (version.includes('-beta.')) {
+      channel = 'beta';
+    } else if (version.includes('-alpha.')) {
+      channel = 'alpha';
+    } else if (version.includes('-nightly.')) {
+      channel = 'nightly';
+    }
+  }
+
+  const info = {
+    version,
+    channel,
+    packageRoot,
+    devMode: config.devMode || false,
+    // Public-facing URLs — single source of truth is package.json, so user-visible
+    // stamps/links never hardcode the internal build origin. The published package
+    // declares the public repository/homepage/bugs; read them here rather than
+    // duplicating literals across the CLI.
+    repoUrl: normalizeRepoUrl(packageJson.repository),       // e.g. github.com/jmagly/aiwg
+    homepage: packageJson.homepage || '',                    // e.g. https://aiwg.io
+    issuesUrl: packageJson.bugs?.url || '',                  // e.g. https://github.com/jmagly/aiwg/issues
+  };
+
+  if (config.channel === 'edge') {
+    // Get git info for edge channel
+    try {
+      const gitHash = execSync('git rev-parse --short HEAD', {
+        cwd: config.edgePath,
+        encoding: 'utf8',
+      }).trim();
+      const gitBranch = execSync('git branch --show-current', {
+        cwd: config.edgePath,
+        encoding: 'utf8',
+      }).trim();
+      info.edgePath = config.edgePath;
+      info.gitHash = gitHash;
+      info.gitBranch = gitBranch;
+    } catch {
+      // Git info not available
+    }
+  }
+
+  return info;
+}
+
+/**
+ * Update the edge installation from git
+ */
+export async function updateEdge() {
+  const config = await loadConfig();
+
+  if (config.channel !== 'edge') {
+    console.log('Not in edge channel. Use npm install -g aiwg@latest for stable channel.');
+    return;
+  }
+
+  console.log('Updating edge installation...');
+
+  try {
+    await runWithTimeout('git', ['fetch', '--all'], { cwd: config.edgePath });
+    await runWithTimeout('git', ['pull', '--ff-only'], { cwd: config.edgePath });
+    console.log('');
+    console.log('Edge installation updated successfully.');
+  } catch (error) {
+    console.error('Update failed:', error.message);
+    console.log('');
+    console.log('If you have local changes, try:');
+    console.log(`  cd ${config.edgePath}`);
+    console.log('  git stash');
+    console.log('  git pull');
+    console.log('  git stash pop');
+    process.exit(1);
+  }
+}

package/dist/src/cli/agent-spawn.js

@@ -0,0 +1,178 @@
+/**
+ * Agent Spawn Utility
+ *
+ * Centralized utility for spawning agentic CLI tools across providers.
+ * Handles --dangerous, --provider, and --params passthrough flags uniformly
+ * across all commands that invoke an underlying agent system.
+ *
+ * Usage pattern:
+ *   const { opts, remaining } = parseAgentSpawnFlags(ctx.args);
+ *   const config = getProviderConfig(opts.provider);
+ *   const spawnArgs = buildAgentArgs(prompt, opts);
+ *   spawn(config.binary, spawnArgs, { stdio: 'inherit' });
+ */
+export const PROVIDER_CONFIGS = {
+    claude: {
+        binary: 'claude',
+        dangerousFlag: '--dangerously-skip-permissions',
+        name: 'Claude Code',
+    },
+    opencode: {
+        binary: 'opencode',
+        // OpenCode uses `opencode run "<prompt>"` for non-interactive execution.
+        // Dangerous mode flag not yet confirmed; omit rather than guess.
+        promptPrefix: ['run'],
+        dangerousFlag: null,
+        name: 'OpenCode',
+    },
+    codex: {
+        binary: 'codex',
+        // Codex supports --full-auto (no approval prompts) and --approval-mode full-auto
+        dangerousFlag: '--full-auto',
+        name: 'OpenAI Codex',
+    },
+    hermes: {
+        // Hermes is a model series (NousResearch), not a confirmed standalone CLI.
+        // Treat as IDE/runtime-integrated until a CLI is confirmed.
+        binary: null,
+        dangerousFlag: null,
+        name: 'Hermes',
+        guidanceMessage: 'Hermes does not have a confirmed standalone CLI.\n' +
+            'Run via Ollama (`ollama run hermes3`) or through your configured MCP sidecar.',
+    },
+    copilot: {
+        binary: null,
+        dangerousFlag: null,
+        name: 'GitHub Copilot',
+        guidanceMessage: 'GitHub Copilot is IDE-integrated and cannot be spawned from the CLI.\n' +
+            'Open your IDE, navigate to the Copilot chat panel, and run the skill manually.',
+    },
+    cursor: {
+        binary: null,
+        dangerousFlag: null,
+        name: 'Cursor',
+        guidanceMessage: 'Cursor is IDE-integrated and cannot be spawned from the CLI.\n' +
+            'For unrestricted AIWG tool access, use the MCP sidecar:\n' +
+            '  aiwg mcp install cursor && aiwg mcp serve\n' +
+            'See: docs/integrations/cursor-mcp-sidecar.md',
+    },
+    factory: {
+        binary: null,
+        dangerousFlag: null,
+        name: 'Factory AI',
+        guidanceMessage: 'Factory AI is cloud-based and cannot be spawned from the CLI.\n' +
+            'Use the Factory AI dashboard to dispatch the workflow.',
+    },
+    warp: {
+        binary: null,
+        dangerousFlag: null,
+        name: 'Warp Terminal',
+        guidanceMessage: 'Warp Terminal cannot be spawned programmatically.\n' +
+            'For unrestricted AIWG tool access, use the MCP sidecar:\n' +
+            '  aiwg mcp install warp && aiwg mcp serve\n' +
+            'See: docs/integrations/warp-mcp-sidecar.md',
+    },
+    windsurf: {
+        binary: null,
+        dangerousFlag: null,
+        name: 'Windsurf',
+        guidanceMessage: 'Windsurf is IDE-integrated and cannot be spawned from the CLI.\n' +
+            'For unrestricted AIWG tool access, use the MCP sidecar:\n' +
+            '  aiwg mcp install windsurf && aiwg mcp serve\n' +
+            'See: docs/integrations/windsurf-mcp-sidecar.md',
+    },
+};
+/**
+ * Extract --provider, --dangerous, and --params from an args array.
+ * Returns the parsed options and the remaining args with those flags removed.
+ *
+ * This is non-destructive — the original array is not modified.
+ */
+export function parseAgentSpawnFlags(args) {
+    const opts = {};
+    const remaining = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--provider' && i + 1 < args.length) {
+            opts.provider = args[++i];
+        }
+        else if (arg === '--dangerous') {
+            opts.dangerous = true;
+        }
+        else if (arg === '--params' && i + 1 < args.length) {
+            opts.params = args[++i];
+        }
+        else {
+            remaining.push(arg);
+        }
+    }
+    return { opts, remaining };
+}
+// ── Arg construction ──────────────────────────────────────────
+/**
+ * Build the final args array for spawning a provider binary.
+ *
+ * Order: [prompt, dangerous-flag?, ...raw-params]
+ */
+export function buildAgentArgs(prompt, opts) {
+    const config = getProviderConfig(opts.provider ?? 'claude');
+    const args = [];
+    // Dangerous flag must precede the prompt — it is a CLI flag to the binary,
+    // not content to pass to the agent. e.g. `claude --dangerously-skip-permissions "<prompt>"`
+    if (opts.dangerous && config.dangerousFlag) {
+        args.push(config.dangerousFlag);
+        // If provider has no dangerous flag, silently ignored —
+        // callers should warn via dangerousWarning().
+    }
+    // Some providers require a subcommand before the prompt (e.g. `opencode run "<prompt>"`)
+    args.push(...(config.promptPrefix ?? []));
+    // The prompt
+    args.push(prompt);
+    // User passthrough params — appended after the prompt verbatim
+    if (opts.params) {
+        args.push(...splitParams(opts.params));
+    }
+    return args;
+}
+/**
+ * Split a params string into individual args, respecting double/single quotes.
+ * "hello world" → ['hello world']
+ * --flag value  → ['--flag', 'value']
+ */
+export function splitParams(params) {
+    const result = [];
+    const re = /(?:[^\s"']+|"[^"]*"|'[^']*')+/g;
+    let match;
+    while ((match = re.exec(params)) !== null) {
+        // Strip surrounding quotes from individual tokens
+        result.push(match[0].replace(/^["']|["']$/g, ''));
+    }
+    return result;
+}
+// ── Provider helpers ──────────────────────────────────────────
+/** Get config for a provider, falling back to claude for unknown values. */
+export function getProviderConfig(provider) {
+    return PROVIDER_CONFIGS[provider] ?? PROVIDER_CONFIGS['claude'];
+}
+/** Returns true if the provider has a CLI binary that can be spawned. */
+export function isSpawnableProvider(provider) {
+    return getProviderConfig(provider).binary !== null;
+}
+/**
+ * Warn string if --dangerous was requested but the provider has no
+ * corresponding flag. Returns null if the combination is valid.
+ */
+export function dangerousWarning(provider) {
+    const config = getProviderConfig(provider);
+    if (!config.dangerousFlag) {
+        return `--dangerous is not supported for provider '${config.name}' and will be ignored.`;
+    }
+    return null;
+}
+/** List all spawnable provider names. */
+export function spawnableProviders() {
+    return Object.entries(PROVIDER_CONFIGS)
+        .filter(([, c]) => c.binary !== null)
+        .map(([k]) => k);
+}
+//# sourceMappingURL=agent-spawn.js.map