@paths.design/caws-cli 9.3.2 → 10.1.0

package/dist/templates/scripts/new_feature.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+# Create a new CAWS feature spec + optional worktree
+#
+# Usage:
+#   scripts/new_feature.sh FEAT-001 "Feature description"
+#   scripts/new_feature.sh FEAT-001 "Feature description" --worktree
+#
+# This script:
+#   1. Creates a feature spec in .caws/specs/<ID>.yaml
+#   2. Optionally creates a git worktree for isolated development
+
+set -euo pipefail
+
+if [ $# -lt 2 ]; then
+  echo "usage: scripts/new_feature.sh <SPEC-ID> <title> [--worktree]" >&2
+  echo "  example: scripts/new_feature.sh FEAT-001 'Add user authentication'" >&2
+  exit 1
+fi
+
+SPEC_ID="$1"
+TITLE="$2"
+USE_WORKTREE="${3:-}"
+
+# Validate spec ID format (PREFIX-NUMBER, e.g., FEAT-001, AUTH-042)
+if ! echo "$SPEC_ID" | grep -qE '^[A-Z]+-[0-9]+$'; then
+  echo "error: spec ID must be in format PREFIX-NUMBER (e.g., FEAT-001, AUTH-042)" >&2
+  exit 1
+fi
+
+SPEC_FILE=".caws/specs/${SPEC_ID}.yaml"
+
+# Check if spec already exists
+if [ -f "$SPEC_FILE" ]; then
+  echo "error: spec $SPEC_ID already exists at $SPEC_FILE" >&2
+  exit 1
+fi
+
+# Create spec directory if needed
+mkdir -p .caws/specs
+
+# Generate spec scaffold
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+cat > "$SPEC_FILE" << EOF
+id: ${SPEC_ID}
+type: feature
+title: "${TITLE}"
+status: draft
+risk_tier: 2
+mode: development
+created_at: "${TIMESTAMP}"
+updated_at: "${TIMESTAMP}"
+blast_radius:
+  modules: []
+  data_migration: false
+operational_rollback_slo: 5m
+scope:
+  in: []
+  out:
+    - docs/reference/v1/
+    - .caws/
+threats: []
+invariants: []
+acceptance: []
+acceptance_criteria: []
+milestones: []
+EOF
+
+echo "Created feature spec: $SPEC_FILE"
+
+# Optionally create worktree
+if [ "$USE_WORKTREE" = "--worktree" ]; then
+  BRANCH_NAME="feat/${SPEC_ID,,}"  # lowercase
+  WORKTREE_DIR=".caws/worktrees/${SPEC_ID,,}"
+
+  git worktree add "$WORKTREE_DIR" -b "$BRANCH_NAME"
+  echo "Created worktree: $WORKTREE_DIR (branch: $BRANCH_NAME)"
+  echo ""
+  echo "To start working:"
+  echo "  cd $WORKTREE_DIR"
+fi

package/dist/test-analysis.js

@@ -7,6 +7,7 @@
 const fs = require('fs-extra');
 const path = require('path');
 const yaml = require('js-yaml');
+const { resolveSpec } = require('./utils/spec-resolver');
 
 /**
  * Waiver Pattern Learning Engine
@@ -198,7 +199,7 @@ class WaiverPatternLearner {
   /**
    * Analyze budget overrun patterns
    */
-  analyzeBudgetOverruns(waivers, specs) {
+  analyzeBudgetOverruns(waivers, _specs) {
     const budgetWaivers = waivers.filter((w) => w.gates?.includes('budget_limit'));
 
     if (budgetWaivers.length === 0) {
@@ -266,7 +267,7 @@ class WaiverPatternLearner {
   /**
    * Identify risk factors from waiver patterns
    */
-  identifyRiskFactors(waivers, specs) {
+  identifyRiskFactors(waivers, _specs) {
     // Simple risk factor identification based on waiver frequency
     const riskFactors = [];
 
@@ -595,17 +596,17 @@ class BudgetPredictor {
 /**
  * Main Test Analysis CLI handler
  */
-async function testAnalysisCommand(subcommand, options = []) {
+async function testAnalysisCommand(subcommand, options = [], commandOptions = {}) {
   const chalk = (await import('chalk')).default;
 
   try {
     switch (subcommand) {
       case 'assess-budget':
-        return await handleAssessBudget(options);
+        return await handleAssessBudget(options, commandOptions);
       case 'analyze-patterns':
         return await handleAnalyzePatterns(options);
       case 'find-similar':
-        return await handleFindSimilar(options);
+        return await handleFindSimilar(options, commandOptions);
       default:
         console.log(chalk.red('Unknown test-analysis subcommand'));
         console.log('Available commands:');
@@ -619,28 +620,49 @@ async function testAnalysisCommand(subcommand, options = []) {
   }
 }
 
+/**
+ * Resolve the current spec for analysis commands.
+ * Supports explicit `--spec <path>` for compatibility, but prefers
+ * the suite-standard resolver and `--spec-id`.
+ * @param {string[]} optionArgs
+ * @param {Object} commandOptions
+ * @returns {Promise<{spec: Object, specPath: string}>}
+ */
+async function resolveAnalysisSpec(optionArgs = [], commandOptions = {}) {
+  let specFile = null;
+  if (Array.isArray(optionArgs) && optionArgs.includes('--spec')) {
+    const specIndex = optionArgs.indexOf('--spec');
+    if (specIndex + 1 < optionArgs.length) {
+      specFile = optionArgs[specIndex + 1];
+    }
+  }
+
+  const resolved = await resolveSpec({
+    specId: commandOptions.specId,
+    specFile,
+    warnLegacy: false,
+    interactive: false,
+  });
+
+  return {
+    spec: resolved.spec,
+    specPath: resolved.path,
+  };
+}
+
 /**
  * Handle budget assessment command
  */
-async function handleAssessBudget(options) {
+async function handleAssessBudget(options, commandOptions = {}) {
   const chalk = (await import('chalk')).default;
   const predictor = new BudgetPredictor();
 
-  // Load current spec
-  let specPath = '.caws/working-spec.yaml';
-  if (options.includes('--spec')) {
-    const specIndex = options.indexOf('--spec');
-    if (specIndex + 1 < options.length) {
-      specPath = options[specIndex + 1];
-    }
-  }
-
   try {
-    const specContent = fs.readFileSync(specPath, 'utf8');
-    const spec = yaml.load(specContent);
+    const { spec, specPath } = await resolveAnalysisSpec(options, commandOptions);
 
     console.log(chalk.cyan(`Budget Assessment for ${spec.id}`));
     console.log('==============================================');
+    console.log(chalk.gray(`Spec: ${path.relative(process.cwd(), specPath)}`));
 
     const result = predictor.assessBudget(spec);
 
@@ -681,7 +703,7 @@ async function handleAssessBudget(options) {
 /**
  * Handle pattern analysis command
  */
-async function handleAnalyzePatterns(options) {
+async function handleAnalyzePatterns(_options) {
   const chalk = (await import('chalk')).default;
   const learner = new WaiverPatternLearner();
 
@@ -727,25 +749,16 @@ async function handleAnalyzePatterns(options) {
 /**
  * Handle find similar projects command
  */
-async function handleFindSimilar(options) {
+async function handleFindSimilar(options, commandOptions = {}) {
   const chalk = (await import('chalk')).default;
   const matcher = new ProjectSimilarityMatcher();
 
-  // Load current spec
-  let specPath = '.caws/working-spec.yaml';
-  if (options.includes('--spec')) {
-    const specIndex = options.indexOf('--spec');
-    if (specIndex + 1 < options.length) {
-      specPath = options[specIndex + 1];
-    }
-  }
-
   try {
-    const specContent = fs.readFileSync(specPath, 'utf8');
-    const spec = yaml.load(specContent);
+    const { spec, specPath } = await resolveAnalysisSpec(options, commandOptions);
 
     console.log(chalk.cyan(`Finding projects similar to ${spec.id}`));
     console.log('==============================================');
+    console.log(chalk.gray(`Spec: ${path.relative(process.cwd(), specPath)}`));
 
     const similar = matcher.findSimilarProjects(spec);
 

package/dist/tool-loader.js

@@ -128,7 +128,7 @@ class ToolLoader extends EventEmitter {
       this.emit('tool:loaded', { id: toolId, metadata: tool.metadata });
 
       return tool;
-    }, `Tool loading failed: ${toolId}`);
+    }, 'Tool loading failed');
   }
 
   /**

package/dist/utils/agent-session.js

@@ -0,0 +1,202 @@
+/**
+ * Agent Session Identity
+ *
+ * Provides a unified way to identify the current agent session across
+ * Claude Code, Cursor, and other IDE agent environments.
+ *
+ * Sources checked (first match wins):
+ *   1. CLAUDE_SESSION_ID  — set by Claude Code automatically
+ *   2. .caws/agents.json  — written by Cursor session-log hook (conversation_id)
+ *   3. CURSOR_TRACE_ID    — set by Cursor (per-request, not stable, last resort)
+ *
+ * The agent registry (.caws/agents.json) also tracks active agents for
+ * multi-agent coordination. Entries expire after a configurable TTL.
+ *
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const AGENTS_REGISTRY = '.caws/agents.json';
+const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 minutes
+
+/**
+ * Get the current agent's session ID from the best available source.
+ * @param {string} [projectRoot] - Project root (for reading agent registry)
+ * @returns {string|null} Session ID or null if not in an agent context
+ */
+function getAgentSessionId(projectRoot) {
+  // 1. Claude Code — most reliable, set automatically
+  if (process.env.CLAUDE_SESSION_ID) {
+    return process.env.CLAUDE_SESSION_ID;
+  }
+
+  // 2. Agent registry — written by Cursor session-log hook
+  if (projectRoot) {
+    const registry = loadAgentRegistry(projectRoot);
+    const active = findActiveAgent(registry);
+    if (active) {
+      return active.sessionId;
+    }
+  }
+
+  // 3. Cursor trace ID — per-request, not stable, but better than nothing
+  if (process.env.CURSOR_TRACE_ID) {
+    return `cursor:${process.env.CURSOR_TRACE_ID}`;
+  }
+
+  return null;
+}
+
+/**
+ * Get the agent platform name.
+ * @returns {string} 'claude-code' | 'cursor' | 'unknown'
+ */
+function getAgentPlatform() {
+  if (process.env.CLAUDE_SESSION_ID) return 'claude-code';
+  if (process.env.CURSOR_TRACE_ID) return 'cursor';
+  return 'unknown';
+}
+
+/**
+ * Load the agent registry, pruning stale entries.
+ * @param {string} root - Project root
+ * @returns {object} Registry with { agents: { [sessionId]: entry } }
+ */
+function loadAgentRegistry(root) {
+  const registryPath = path.join(root, AGENTS_REGISTRY);
+  let registry = { version: 1, agents: {} };
+
+  if (fs.existsSync(registryPath)) {
+    try {
+      registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+    } catch {
+      // Corrupt file — start fresh
+      registry = { version: 1, agents: {} };
+    }
+  }
+
+  // Prune stale entries on every read
+  const now = Date.now();
+  let pruned = false;
+  for (const [id, entry] of Object.entries(registry.agents || {})) {
+    const ttl = entry.ttl || DEFAULT_TTL_MS;
+    const lastSeenTime = entry.lastSeen ? new Date(entry.lastSeen).getTime() : 0;
+    const lastSeen = isNaN(lastSeenTime) ? 0 : lastSeenTime;
+    if (now - lastSeen > ttl) {
+      delete registry.agents[id];
+      pruned = true;
+    }
+  }
+
+  if (pruned) {
+    saveAgentRegistry(root, registry);
+  }
+
+  return registry;
+}
+
+/**
+ * Save the agent registry atomically (write-then-rename).
+ * @param {string} root - Project root
+ * @param {object} registry - Registry object
+ */
+function saveAgentRegistry(root, registry) {
+  const registryPath = path.join(root, AGENTS_REGISTRY);
+  const dir = path.dirname(registryPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const tmpPath = registryPath + '.tmp.' + process.pid;
+  fs.writeFileSync(tmpPath, JSON.stringify(registry, null, 2));
+  fs.renameSync(tmpPath, registryPath);
+}
+
+/**
+ * Register or heartbeat an agent session.
+ * Called by session-log hooks to keep entries fresh.
+ * @param {string} root - Project root
+ * @param {object} agent - Agent info
+ * @param {string} agent.sessionId - Unique session/conversation ID
+ * @param {string} agent.platform - 'claude-code' | 'cursor' | 'unknown'
+ * @param {string} [agent.model] - Model name if known
+ * @param {string} [agent.specId] - Active spec ID if known
+ * @param {number} [agent.ttl] - Custom TTL in ms (default 30 min)
+ */
+function heartbeatAgent(root, agent) {
+  const registry = loadAgentRegistry(root);
+  const existing = registry.agents[agent.sessionId] || {};
+
+  registry.agents[agent.sessionId] = {
+    ...existing,
+    sessionId: agent.sessionId,
+    platform: agent.platform || existing.platform || 'unknown',
+    model: agent.model || existing.model || null,
+    specId: agent.specId || existing.specId || null,
+    ttl: agent.ttl || existing.ttl || DEFAULT_TTL_MS,
+    firstSeen: existing.firstSeen || new Date().toISOString(),
+    lastSeen: new Date().toISOString(),
+  };
+
+  saveAgentRegistry(root, registry);
+}
+
+/**
+ * Remove an agent session from the registry.
+ * Called on session stop.
+ * @param {string} root - Project root
+ * @param {string} sessionId - Session to remove
+ */
+function removeAgent(root, sessionId) {
+  const registry = loadAgentRegistry(root);
+  delete registry.agents[sessionId];
+  saveAgentRegistry(root, registry);
+}
+
+/**
+ * Find the most recently active agent for this terminal/process.
+ * Prefers agents that match the current environment.
+ * @param {object} registry - Loaded registry
+ * @returns {object|null} Agent entry or null
+ */
+function findActiveAgent(registry) {
+  const agents = Object.values(registry.agents || {});
+  if (agents.length === 0) return null;
+
+  // If we're in Cursor, prefer cursor agents
+  const isCursor = !!process.env.CURSOR_TRACE_ID;
+  const preferred = agents.filter(a => {
+    if (isCursor) return a.platform === 'cursor';
+    return a.platform === 'claude-code';
+  });
+
+  const pool = preferred.length > 0 ? preferred : agents;
+
+  // Return most recently seen
+  pool.sort((a, b) => new Date(b.lastSeen) - new Date(a.lastSeen));
+  return pool[0];
+}
+
+/**
+ * List all currently active (non-expired) agents.
+ * @param {string} root - Project root
+ * @returns {object[]} Array of agent entries
+ */
+function listActiveAgents(root) {
+  const registry = loadAgentRegistry(root);
+  return Object.values(registry.agents || {});
+}
+
+module.exports = {
+  getAgentSessionId,
+  getAgentPlatform,
+  loadAgentRegistry,
+  saveAgentRegistry,
+  heartbeatAgent,
+  removeAgent,
+  findActiveAgent,
+  listActiveAgents,
+  AGENTS_REGISTRY,
+  DEFAULT_TTL_MS,
+};

package/dist/utils/detection.js

@@ -33,11 +33,17 @@ function findPackageRoot(startDir = __dirname) {
  * @returns {Object} Setup information
  */
 function detectCAWSSetup(cwd = process.cwd()) {
-  // Skip logging for version/help commands
+  // Skip logging for version/help/quiet commands, or when CAWS_QUIET is set.
+  // Verbose detection output contributes to Claude Code context-window
+  // exhaustion when agents run many caws commands in a single session.
   const isQuietCommand =
     process.argv.includes('--version') ||
     process.argv.includes('-V') ||
-    process.argv.includes('--help');
+    process.argv.includes('--help') ||
+    process.argv.includes('--json') ||
+    process.argv.includes('--quiet') ||
+    process.argv.includes('-q') ||
+    process.env.CAWS_QUIET === '1';
 
   if (!isQuietCommand) {
     console.log(chalk.blue('Detecting CAWS setup...'));