@arthai/agents 1.0.0

package/bin/cli.js

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+// bin/cli.js — npx @arthai/agents CLI
+// Thin wrapper: parses args, installs compiled plugins or shells out to install.sh
+
+'use strict';
+
+const { execSync, spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const TOOLKIT_DIR = path.resolve(__dirname, '..');
+const BUNDLES_DIR = path.join(TOOLKIT_DIR, 'bundles');
+const PLUGINS_DIR = path.join(TOOLKIT_DIR, 'dist', 'plugins');
+const INSTALL_SH = path.join(TOOLKIT_DIR, 'install.sh');
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+switch (command) {
+  case 'install':
+    handleInstall(args.slice(1));
+    break;
+  case 'list':
+    handleList();
+    break;
+  case 'info':
+    handleInfo(args[1]);
+    break;
+  case 'legacy':
+    handleLegacy(args.slice(1));
+    break;
+  case undefined:
+  case '--help':
+  case '-h':
+    printUsage();
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    printUsage();
+    process.exit(1);
+}
+
+// ── install ───────────────────────────────────────────────────────────────────
+
+function handleInstall(rawArgs) {
+  if (rawArgs.length === 0) {
+    console.error('Usage: arthai install <bundle> [bundle...] [target-path]');
+    process.exit(1);
+  }
+
+  const bundleNames = [];
+  let targetDir = process.cwd();
+
+  for (const arg of rawArgs) {
+    if (arg.startsWith('-')) {
+      console.error(`Unknown flag: ${arg}`);
+      process.exit(1);
+    }
+    // Last arg is target path if it looks like a path (contains / or starts with . or ~)
+    const looksLikePath = arg.includes(path.sep) || arg.startsWith('.') || arg.startsWith('~') || arg.startsWith('/');
+    if (looksLikePath && rawArgs.indexOf(arg) === rawArgs.length - 1) {
+      targetDir = path.resolve(arg.replace(/^~/, process.env.HOME || '~'));
+    } else {
+      bundleNames.push(arg);
+    }
+  }
+
+  if (bundleNames.length === 0) {
+    console.error('No bundle names specified.');
+    process.exit(1);
+  }
+
+  // Validate bundle name format (prevent path traversal)
+  for (const name of bundleNames) {
+    assertValidBundleName(name);
+  }
+
+  // Validate bundle names are known
+  const allBundles = listBundles();
+  const unknownBundles = bundleNames.filter(n => !allBundles.has(n));
+  if (unknownBundles.length > 0) {
+    console.error(`Unknown bundle(s): ${unknownBundles.join(', ')}`);
+    console.error(`Available: ${[...allBundles.keys()].join(', ')}`);
+    process.exit(1);
+  }
+
+  // Resolve dependencies (topological order)
+  const resolved = resolveDependencies(bundleNames);
+  console.log(`Installing: ${resolved.join(' → ')}`);
+
+  // Ensure target dir exists
+  if (!fs.existsSync(targetDir)) {
+    console.error(`Target directory does not exist: ${targetDir}`);
+    process.exit(1);
+  }
+
+  const pluginsTargetDir = path.join(targetDir, '.claude', 'plugins');
+
+  for (const name of resolved) {
+    // Defense-in-depth: verify the resolved path stays inside PLUGINS_DIR
+    const pluginDir = path.resolve(PLUGINS_DIR, name);
+    if (!pluginDir.startsWith(path.resolve(PLUGINS_DIR) + path.sep)) {
+      console.error(`Security: plugin path for "${name}" escapes dist/plugins/. Aborting.`);
+      process.exit(1);
+    }
+    if (!fs.existsSync(pluginDir)) {
+      console.error(`Plugin '${name}' not found in dist/plugins/. Run compiler.sh first.`);
+      process.exit(1);
+    }
+    copyPlugin(pluginDir, pluginsTargetDir, name);
+    console.log(`  Installed: ${name} → ${path.join(pluginsTargetDir, name)}`);
+  }
+
+  console.log(`\nDone. ${resolved.length} plugin(s) installed to ${pluginsTargetDir}`);
+}
+
+// ── list ──────────────────────────────────────────────────────────────────────
+
+function handleList() {
+  const bundles = listBundles();
+  if (bundles.size === 0) {
+    console.log('No bundles found.');
+    return;
+  }
+
+  console.log('Available bundles:\n');
+  for (const [name, meta] of bundles) {
+    const compiled = fs.existsSync(path.join(PLUGINS_DIR, name)) ? '(compiled)' : '(not compiled)';
+    const deps = meta.dependencies && meta.dependencies.length > 0
+      ? `  deps: [${meta.dependencies.join(', ')}]`
+      : '';
+    console.log(`  ${name.padEnd(12)}  ${meta.description}${deps}`);
+    if (compiled.includes('compiled')) {
+      // Only mention if not compiled — to keep output clean
+    }
+  }
+
+  const compiledCount = [...bundles.keys()].filter(n => fs.existsSync(path.join(PLUGINS_DIR, n))).length;
+  console.log(`\n${bundles.size} bundles total, ${compiledCount} compiled`);
+}
+
+// ── info ──────────────────────────────────────────────────────────────────────
+
+function handleInfo(bundleName) {
+  if (!bundleName) {
+    console.error('Usage: arthai info <bundle>');
+    process.exit(1);
+  }
+
+  const bundleFile = path.join(BUNDLES_DIR, `${bundleName}.json`);
+  if (!fs.existsSync(bundleFile)) {
+    console.error(`Bundle not found: ${bundleName}`);
+    process.exit(1);
+  }
+
+  const meta = JSON.parse(fs.readFileSync(bundleFile, 'utf8'));
+  const compiled = fs.existsSync(path.join(PLUGINS_DIR, bundleName));
+
+  console.log(`Bundle: ${meta.name}`);
+  console.log(`Description: ${meta.description}`);
+  console.log(`Version: ${meta.version || readVersion()}`);
+  console.log(`Compiled: ${compiled ? 'yes' : 'no (run compiler.sh first)'}`);
+
+  if (meta.include_all) {
+    console.log('Contents: ALL (reads portable.manifest)');
+  } else {
+    if (meta.agents && meta.agents.length > 0) {
+      console.log(`Agents (${meta.agents.length}): ${meta.agents.map(a => path.basename(a, '.md')).join(', ')}`);
+    }
+    if (meta.skills && meta.skills.length > 0) {
+      console.log(`Skills (${meta.skills.length}): ${meta.skills.map(s => path.basename(s)).join(', ')}`);
+    }
+    if (meta.hooks && meta.hooks.length > 0) {
+      console.log(`Hooks (${meta.hooks.length}): ${meta.hooks.join(', ')}`);
+    }
+    if (meta.dependencies && meta.dependencies.length > 0) {
+      console.log(`Dependencies: ${meta.dependencies.join(', ')}`);
+    }
+  }
+}
+
+// ── legacy ────────────────────────────────────────────────────────────────────
+
+function handleLegacy(legacyArgs) {
+  if (!fs.existsSync(INSTALL_SH)) {
+    console.error(`install.sh not found at ${INSTALL_SH}`);
+    process.exit(1);
+  }
+
+  const result = spawnSync('bash', [INSTALL_SH, ...legacyArgs], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+
+  if (result.error) {
+    console.error(`Failed to run install.sh: ${result.error.message}`);
+    process.exit(1);
+  }
+  process.exit(result.status || 0);
+}
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+// Validate bundle names: only lowercase alphanumeric and hyphens, max 64 chars.
+// Prevents path traversal via names like "../../etc/passwd".
+function isValidBundleName(name) {
+  return typeof name === 'string' && /^[a-z0-9-]{1,64}$/.test(name);
+}
+
+function assertValidBundleName(name) {
+  if (!isValidBundleName(name)) {
+    console.error(`Invalid bundle name: "${name}". Bundle names must be lowercase alphanumeric with hyphens only.`);
+    process.exit(1);
+  }
+}
+
+function listBundles() {
+  const bundles = new Map();
+  if (!fs.existsSync(BUNDLES_DIR)) return bundles;
+
+  for (const file of fs.readdirSync(BUNDLES_DIR).filter(f => f.endsWith('.json')).sort()) {
+    try {
+      const meta = JSON.parse(fs.readFileSync(path.join(BUNDLES_DIR, file), 'utf8'));
+      bundles.set(meta.name, meta);
+    } catch (e) {
+      // Skip malformed bundle files
+    }
+  }
+  return bundles;
+}
+
+function resolveDependencies(names) {
+  const bundles = listBundles();
+  const resolved = [];
+  const visited = new Set();
+
+  function visit(name) {
+    if (visited.has(name)) return;
+    visited.add(name);
+    const meta = bundles.get(name);
+    if (meta && Array.isArray(meta.dependencies)) {
+      for (const dep of meta.dependencies) {
+        // Validate dependency names from bundle JSON to prevent path traversal
+        if (!isValidBundleName(dep)) {
+          console.error(`Bundle "${name}" has invalid dependency name: "${dep}". Aborting.`);
+          process.exit(1);
+        }
+        visit(dep);
+      }
+    }
+    resolved.push(name);
+  }
+
+  for (const name of names) {
+    visit(name);
+  }
+  return resolved;
+}
+
+function copyPlugin(sourceDir, targetPluginsDir, name) {
+  const dest = path.join(targetPluginsDir, name);
+
+  // Remove existing
+  if (fs.existsSync(dest)) {
+    fs.rmSync(dest, { recursive: true });
+  }
+  fs.mkdirSync(dest, { recursive: true });
+
+  // Recursive copy
+  copyDirRecursive(sourceDir, dest);
+}
+
+function copyDirRecursive(src, dest) {
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function readVersion() {
+  const versionFile = path.join(TOOLKIT_DIR, 'VERSION');
+  if (fs.existsSync(versionFile)) {
+    return fs.readFileSync(versionFile, 'utf8').trim();
+  }
+  return '0.0.0';
+}
+
+function printUsage() {
+  const version = readVersion();
+  console.log(`arthai v${version} — AI-powered development toolkit for Claude Code
+
+Usage:
+  arthai install <bundle> [bundle...] [path]   Install bundle(s) into a project
+  arthai list                                   List available bundles
+  arthai info <bundle>                          Show bundle details
+  arthai legacy [args...]                       Run install.sh directly
+
+Bundles:
+  forge     Full dev workflow (plan, build, test, ship)
+  spark     Project setup and onboarding
+  scalpel   Surgical bug fixing
+  sentinel  Operations and reliability
+  prism     Deep QA and testing
+  canvas    Design-driven development
+  compass   Product strategy
+  counsel   AI consulting toolkit
+  shield    Safety guardrails
+  cruise    Autopilot mode (requires forge+scalpel+sentinel)
+  prime     Everything
+
+Examples:
+  npx @arthai/agents install forge ./my-project
+  npx @arthai/agents install prime .
+  npx @arthai/agents legacy --setup .
+`);
+}

package/bundles/canvas.json

@@ -0,0 +1,16 @@
+{
+  "name": "canvas",
+  "description": "Design-driven development — adversarial design critique + frontend",
+  "version": "1.0.0",
+  "agents": [
+    "agents/design-studio-think.md",
+    "agents/design-studio-create.md",
+    "agents/design-studio-critique.md",
+    "agents/frontend.md"
+  ],
+  "skills": [
+    "skills/planning"
+  ],
+  "hooks": [],
+  "dependencies": []
+}

package/bundles/compass.json

@@ -0,0 +1,16 @@
+{
+  "name": "compass",
+  "description": "Product strategy — PM, GTM, user research, content strategy",
+  "version": "1.0.0",
+  "agents": [
+    "agents/product-manager.md",
+    "agents/gtm-expert.md",
+    "agents/user-researcher.md",
+    "agents/content-strategist.md"
+  ],
+  "skills": [
+    "skills/planning"
+  ],
+  "hooks": [],
+  "dependencies": []
+}

package/bundles/counsel.json

@@ -0,0 +1,31 @@
+{
+  "name": "counsel",
+  "description": "AI consulting toolkit — client discovery, proposals, deliverables",
+  "version": "1.0.0",
+  "agents": [
+    "agents/ai-consultant.md",
+    "agents/competitive-analyst.md",
+    "agents/meeting-prep.md",
+    "agents/stakeholder-reporter.md"
+  ],
+  "skills": [
+    "skills/consulting",
+    "skills/client-discovery",
+    "skills/engagement-tracker",
+    "skills/opportunity-map",
+    "skills/pitch-generator",
+    "skills/roi-calculator",
+    "skills/solution-architect",
+    "skills/deliverable-builder",
+    "skills/market-research",
+    "skills/welcome",
+    "skills/wizard",
+    "skills/share",
+    "skills/templates"
+  ],
+  "hooks": [
+    "ensure-client-dir",
+    "check-deliverable"
+  ],
+  "dependencies": []
+}

package/bundles/cruise.json

@@ -0,0 +1,11 @@
+{
+  "name": "cruise",
+  "description": "Autopilot mode — autonomous task execution (requires forge+scalpel+sentinel)",
+  "version": "1.0.0",
+  "agents": [],
+  "skills": [
+    "skills/autopilot"
+  ],
+  "hooks": [],
+  "dependencies": ["forge", "scalpel", "sentinel"]
+}

package/bundles/forge.json

@@ -0,0 +1,26 @@
+{
+  "name": "forge",
+  "description": "Full development workflow — plan, build, test, ship",
+  "version": "1.0.0",
+  "agents": [
+    "agents/architect.md",
+    "agents/product-manager.md",
+    "agents/python-backend.md",
+    "agents/frontend.md",
+    "agents/qa.md",
+    "agents/code-reviewer.md"
+  ],
+  "skills": [
+    "skills/planning",
+    "skills/implement",
+    "skills/qa",
+    "skills/pr",
+    "skills/precheck",
+    "skills/review-pr"
+  ],
+  "hooks": [
+    "triage-router",
+    "post-test-summary"
+  ],
+  "dependencies": []
+}

package/bundles/prime.json

@@ -0,0 +1,10 @@
+{
+  "name": "prime",
+  "description": "Everything — all agents, skills, and hooks in one plugin",
+  "version": "1.0.0",
+  "include_all": true,
+  "agents": [],
+  "skills": [],
+  "hooks": [],
+  "dependencies": []
+}

package/bundles/prism.json

@@ -0,0 +1,23 @@
+{
+  "name": "prism",
+  "description": "Deep QA — multi-agent testing, baseline tracking, incident analysis",
+  "version": "1.0.0",
+  "agents": [
+    "agents/qa.md",
+    "agents/qa-e2e.md",
+    "agents/qa-domain.md",
+    "agents/qa-challenger.md",
+    "agents/qa-baseline-updater.md",
+    "agents/qa-test-promoter.md"
+  ],
+  "skills": [
+    "skills/qa",
+    "skills/qa-learn",
+    "skills/qa-incident"
+  ],
+  "hooks": [
+    "post-test-summary",
+    "post-diff-test-compare"
+  ],
+  "dependencies": []
+}

package/bundles/scalpel.json

@@ -0,0 +1,17 @@
+{
+  "name": "scalpel",
+  "description": "Surgical bug fixing — targeted fixes, CI repair, issue triage",
+  "version": "1.0.0",
+  "agents": [
+    "agents/code-reviewer.md"
+  ],
+  "skills": [
+    "skills/fix",
+    "skills/ci-fix",
+    "skills/issue"
+  ],
+  "hooks": [
+    "pre-edit-guard"
+  ],
+  "dependencies": []
+}

package/bundles/sentinel.json

@@ -0,0 +1,19 @@
+{
+  "name": "sentinel",
+  "description": "Operations and reliability — SRE, incidents, deploy monitoring",
+  "version": "1.0.0",
+  "agents": [
+    "agents/sre.md",
+    "agents/ops.md"
+  ],
+  "skills": [
+    "skills/sre",
+    "skills/incident",
+    "skills/restart"
+  ],
+  "hooks": [
+    "post-deploy-health",
+    "post-git-state"
+  ],
+  "dependencies": []
+}

package/bundles/shield.json

@@ -0,0 +1,14 @@
+{
+  "name": "shield",
+  "description": "Safety guardrails — bash guards, edit protection, session bootstrap",
+  "version": "1.0.0",
+  "agents": [],
+  "skills": [],
+  "hooks": [
+    "pre-bash-guard",
+    "pre-edit-guard",
+    "session-bootstrap",
+    "triage-router"
+  ],
+  "dependencies": []
+}

package/bundles/spark.json

@@ -0,0 +1,19 @@
+{
+  "name": "spark",
+  "description": "Project setup and onboarding — calibrate, scan, bootstrap",
+  "version": "1.0.0",
+  "agents": [
+    "agents/setup.md",
+    "agents/explore-light.md"
+  ],
+  "skills": [
+    "skills/onboard",
+    "skills/calibrate",
+    "skills/scan",
+    "skills/setup"
+  ],
+  "hooks": [
+    "session-bootstrap"
+  ],
+  "dependencies": []
+}