@paths.design/caws-cli 8.2.1 → 8.3.0

package/dist/session/session-manager.js

@@ -0,0 +1,548 @@
+/**
+ * @fileoverview CAWS Session Capsule Manager
+ * Manages session lifecycle and capsule persistence for multi-agent coordination.
+ * Each session produces a structured capsule that captures baseline state on entry
+ * and work summary + verification evidence on exit.
+ * @author @darianrosebrook
+ */
+
+const { execFileSync } = require('child_process');
+const fs = require('fs-extra');
+const path = require('path');
+const crypto = require('crypto');
+
+const SESSIONS_DIR = '.caws/sessions';
+const REGISTRY_FILE = '.caws/sessions.json';
+const CAPSULE_SCHEMA_VERSION = 'caws.capsule.v1';
+
+/**
+ * Get the git repository root
+ * @returns {string} Absolute path to repo root
+ */
+function getRepoRoot() {
+  return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+    encoding: 'utf8',
+  }).trim();
+}
+
+/**
+ * Get current HEAD revision (short hash)
+ * @param {string} cwd - Working directory
+ * @returns {string}
+ */
+function getHeadRev(cwd) {
+  try {
+    return execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
+      encoding: 'utf8',
+      cwd,
+    }).trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Get current branch name
+ * @param {string} cwd - Working directory
+ * @returns {string}
+ */
+function getCurrentBranch(cwd) {
+  try {
+    return execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      encoding: 'utf8',
+      cwd,
+    }).trim();
+  } catch {
+    return 'detached';
+  }
+}
+
+/**
+ * Get dirty files in working tree
+ * @param {string} cwd - Working directory
+ * @returns {{ paths: string[], dirty: boolean }}
+ */
+function getWorkspaceFingerprint(cwd) {
+  try {
+    const output = execFileSync('git', ['status', '--porcelain'], {
+      encoding: 'utf8',
+      cwd,
+    });
+    const paths = output
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => line.substring(3).trim());
+    return { paths_touched: paths, dirty: paths.length > 0 };
+  } catch {
+    return { paths_touched: [], dirty: false };
+  }
+}
+
+/**
+ * Get project name from working spec or directory
+ * @param {string} root - Repository root
+ * @returns {string}
+ */
+function getProjectName(root) {
+  try {
+    const yaml = require('js-yaml');
+    const specPath = path.join(root, '.caws/working-spec.yaml');
+    if (fs.existsSync(specPath)) {
+      const spec = yaml.load(fs.readFileSync(specPath, 'utf8'));
+      return spec.title || spec.id || path.basename(root);
+    }
+  } catch {
+    // Fall through
+  }
+  return path.basename(root);
+}
+
+/**
+ * Get skein ID from working spec
+ * @param {string} root - Repository root
+ * @returns {string}
+ */
+function getSkeinId(root) {
+  try {
+    const yaml = require('js-yaml');
+    const specPath = path.join(root, '.caws/working-spec.yaml');
+    if (fs.existsSync(specPath)) {
+      const spec = yaml.load(fs.readFileSync(specPath, 'utf8'));
+      return spec.id || 'unknown';
+    }
+  } catch {
+    // Fall through
+  }
+  return 'unknown';
+}
+
+/**
+ * Load the session registry
+ * @param {string} root - Repository root
+ * @returns {Object} Registry object
+ */
+function loadRegistry(root) {
+  const registryPath = path.join(root, REGISTRY_FILE);
+  try {
+    if (fs.existsSync(registryPath)) {
+      return JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+    }
+  } catch {
+    // Corrupted registry, start fresh
+  }
+  return { version: 1, sessions: {} };
+}
+
+/**
+ * Save the session registry
+ * @param {string} root - Repository root
+ * @param {Object} registry - Registry object
+ */
+function saveRegistry(root, registry) {
+  const registryPath = path.join(root, REGISTRY_FILE);
+  fs.ensureDirSync(path.dirname(registryPath));
+  fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2));
+}
+
+/**
+ * Generate a deterministic session ID
+ * @returns {string}
+ */
+function generateSessionId() {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const suffix = crypto.randomBytes(4).toString('hex');
+  return `${timestamp}__${suffix}`;
+}
+
+/**
+ * Start a new session, creating the initial capsule with baseline state
+ * @param {Object} options - Session options
+ * @param {string} [options.role] - Agent role (worker, integrator, qa)
+ * @param {string} [options.specId] - Associated feature spec ID
+ * @param {string[]} [options.allowedGlobs] - Allowed file patterns
+ * @param {string[]} [options.forbiddenGlobs] - Forbidden file patterns
+ * @param {string} [options.intent] - What this session intends to accomplish
+ * @returns {Object} Created capsule
+ */
+function startSession(options = {}) {
+  const root = getRepoRoot();
+  const registry = loadRegistry(root);
+  const sessionId = generateSessionId();
+
+  const {
+    role = 'worker',
+    specId,
+    allowedGlobs = [],
+    forbiddenGlobs = [],
+    intent = '',
+  } = options;
+
+  // Build scope from spec if available and no explicit globs provided
+  let scope = {
+    allowed_globs: allowedGlobs,
+    forbidden_globs: forbiddenGlobs,
+  };
+
+  if (specId && allowedGlobs.length === 0) {
+    try {
+      const yaml = require('js-yaml');
+      const specPath = path.join(root, `.caws/specs/${specId}.yaml`);
+      if (fs.existsSync(specPath)) {
+        const spec = yaml.load(fs.readFileSync(specPath, 'utf8'));
+        if (spec.scope) {
+          scope.allowed_globs = spec.scope.in || [];
+          scope.forbidden_globs = spec.scope.out || [];
+        }
+      }
+    } catch {
+      // Non-fatal: scope stays as provided
+    }
+  }
+
+  const capsule = {
+    schema: CAPSULE_SCHEMA_VERSION,
+    project: getProjectName(root),
+    skein_id: getSkeinId(root),
+    session_id: sessionId,
+    role,
+    spec_id: specId || null,
+    scope,
+    base_state: {
+      head_rev: getHeadRev(root),
+      branch: getCurrentBranch(root),
+      workspace_fingerprint: getWorkspaceFingerprint(root),
+    },
+    started_at: new Date().toISOString(),
+    ended_at: null,
+    work_summary: {
+      intent: intent || '',
+      paths_touched: [],
+      artifacts_written: [],
+      commits: [],
+    },
+    verification: {
+      tests_run: [],
+      determinism_checks: [],
+    },
+    known_issues: [],
+    handoff: {
+      next_actions: [],
+      risk_notes: [],
+    },
+  };
+
+  // Persist capsule
+  const sessionsDir = path.join(root, SESSIONS_DIR);
+  fs.ensureDirSync(sessionsDir);
+  const capsulePath = path.join(sessionsDir, `${sessionId}.json`);
+  fs.writeFileSync(capsulePath, JSON.stringify(capsule, null, 2));
+
+  // Update registry
+  registry.sessions[sessionId] = {
+    path: `${sessionId}.json`,
+    role,
+    spec_id: specId || null,
+    status: 'active',
+    started_at: capsule.started_at,
+    ended_at: null,
+    head_rev: capsule.base_state.head_rev,
+    branch: capsule.base_state.branch,
+  };
+  saveRegistry(root, registry);
+
+  return capsule;
+}
+
+/**
+ * Add a checkpoint to the current (most recent active) session
+ * @param {Object} data - Checkpoint data
+ * @param {string} [data.sessionId] - Specific session ID (uses latest active if omitted)
+ * @param {string[]} [data.pathsTouched] - Files changed
+ * @param {string[]} [data.artifactsWritten] - Generated artifacts
+ * @param {Object[]} [data.testsRun] - Test results { name, status, evidence }
+ * @param {Object[]} [data.determinismChecks] - Determinism checks { name, status, total }
+ * @param {Object[]} [data.knownIssues] - Issues discovered { type, description }
+ * @param {string} [data.intent] - Updated intent description
+ * @returns {Object} Updated capsule
+ */
+function checkpointSession(data = {}) {
+  const root = getRepoRoot();
+  const registry = loadRegistry(root);
+
+  // Find session
+  const sessionId = data.sessionId || findActiveSession(registry);
+  if (!sessionId) {
+    throw new Error('No active session found. Start one with: caws session start');
+  }
+
+  const capsulePath = path.join(root, SESSIONS_DIR, `${sessionId}.json`);
+  if (!fs.existsSync(capsulePath)) {
+    throw new Error(`Session capsule not found: ${sessionId}`);
+  }
+
+  const capsule = JSON.parse(fs.readFileSync(capsulePath, 'utf8'));
+
+  // Merge checkpoint data
+  if (data.intent) {
+    capsule.work_summary.intent = data.intent;
+  }
+  if (data.pathsTouched) {
+    const existing = new Set(capsule.work_summary.paths_touched);
+    for (const p of data.pathsTouched) existing.add(p);
+    capsule.work_summary.paths_touched = [...existing];
+  }
+  if (data.artifactsWritten) {
+    const existing = new Set(capsule.work_summary.artifacts_written);
+    for (const a of data.artifactsWritten) existing.add(a);
+    capsule.work_summary.artifacts_written = [...existing];
+  }
+  if (data.testsRun) {
+    capsule.verification.tests_run.push(...data.testsRun);
+  }
+  if (data.determinismChecks) {
+    capsule.verification.determinism_checks.push(...data.determinismChecks);
+  }
+  if (data.knownIssues) {
+    capsule.known_issues.push(...data.knownIssues);
+  }
+
+  // Record current commit as a checkpoint
+  const currentRev = getHeadRev(root);
+  if (currentRev !== capsule.base_state.head_rev) {
+    capsule.work_summary.commits.push({
+      rev: currentRev,
+      checkpoint_at: new Date().toISOString(),
+    });
+  }
+
+  // Write updated capsule
+  fs.writeFileSync(capsulePath, JSON.stringify(capsule, null, 2));
+
+  return capsule;
+}
+
+/**
+ * End a session, finalizing the capsule with handoff information
+ * @param {Object} data - End session data
+ * @param {string} [data.sessionId] - Specific session ID (uses latest active if omitted)
+ * @param {string[]} [data.nextActions] - What the next session should do
+ * @param {string[]} [data.riskNotes] - Risk notes for handoff
+ * @returns {Object} Finalized capsule
+ */
+function endSession(data = {}) {
+  const root = getRepoRoot();
+  const registry = loadRegistry(root);
+
+  const sessionId = data.sessionId || findActiveSession(registry);
+  if (!sessionId) {
+    throw new Error('No active session found.');
+  }
+
+  const capsulePath = path.join(root, SESSIONS_DIR, `${sessionId}.json`);
+  if (!fs.existsSync(capsulePath)) {
+    throw new Error(`Session capsule not found: ${sessionId}`);
+  }
+
+  const capsule = JSON.parse(fs.readFileSync(capsulePath, 'utf8'));
+
+  // Finalize
+  capsule.ended_at = new Date().toISOString();
+
+  // Capture final workspace state
+  const fingerprint = getWorkspaceFingerprint(root);
+  capsule.work_summary.paths_touched = [
+    ...new Set([...capsule.work_summary.paths_touched, ...fingerprint.paths_touched]),
+  ];
+
+  // Record final commit
+  const finalRev = getHeadRev(root);
+  if (
+    finalRev !== capsule.base_state.head_rev &&
+    !capsule.work_summary.commits.some((c) => c.rev === finalRev)
+  ) {
+    capsule.work_summary.commits.push({
+      rev: finalRev,
+      checkpoint_at: new Date().toISOString(),
+    });
+  }
+
+  // Handoff
+  if (data.nextActions) {
+    capsule.handoff.next_actions = data.nextActions;
+  }
+  if (data.riskNotes) {
+    capsule.handoff.risk_notes = data.riskNotes;
+  }
+
+  // Flag if dirty
+  if (fingerprint.dirty) {
+    capsule.known_issues.push({
+      type: 'warning',
+      description: `Session ended with ${fingerprint.paths_touched.length} uncommitted file(s).`,
+    });
+  }
+
+  // Write finalized capsule
+  fs.writeFileSync(capsulePath, JSON.stringify(capsule, null, 2));
+
+  // Update registry
+  registry.sessions[sessionId].status = 'completed';
+  registry.sessions[sessionId].ended_at = capsule.ended_at;
+  saveRegistry(root, registry);
+
+  return capsule;
+}
+
+/**
+ * List all sessions
+ * @param {Object} [options] - List options
+ * @param {string} [options.status] - Filter by status (active, completed)
+ * @param {number} [options.limit] - Max entries to return
+ * @returns {Object[]} Session entries
+ */
+function listSessions(options = {}) {
+  const root = getRepoRoot();
+  const registry = loadRegistry(root);
+
+  let entries = Object.entries(registry.sessions).map(([id, meta]) => ({
+    id,
+    ...meta,
+  }));
+
+  if (options.status) {
+    entries = entries.filter((e) => e.status === options.status);
+  }
+
+  // Sort by started_at descending (most recent first)
+  entries.sort((a, b) => new Date(b.started_at) - new Date(a.started_at));
+
+  if (options.limit) {
+    entries = entries.slice(0, options.limit);
+  }
+
+  return entries;
+}
+
+/**
+ * Show a specific session's full capsule
+ * @param {string} sessionId - Session ID (or "latest" for most recent)
+ * @returns {Object} Full capsule
+ */
+function showSession(sessionId) {
+  const root = getRepoRoot();
+
+  if (sessionId === 'latest') {
+    const registry = loadRegistry(root);
+    const active = findActiveSession(registry);
+    if (active) {
+      sessionId = active;
+    } else {
+      // Find most recent completed
+      const entries = Object.entries(registry.sessions).sort(
+        (a, b) => new Date(b[1].started_at) - new Date(a[1].started_at)
+      );
+      if (entries.length === 0) throw new Error('No sessions found.');
+      sessionId = entries[0][0];
+    }
+  }
+
+  const capsulePath = path.join(root, SESSIONS_DIR, `${sessionId}.json`);
+  if (!fs.existsSync(capsulePath)) {
+    throw new Error(`Session capsule not found: ${sessionId}`);
+  }
+
+  return JSON.parse(fs.readFileSync(capsulePath, 'utf8'));
+}
+
+/**
+ * Briefing output for session start hooks - returns structured text
+ * @returns {string} Briefing text
+ */
+function getBriefing() {
+  const root = getRepoRoot();
+  const registry = loadRegistry(root);
+
+  const lines = [];
+  lines.push('--- CAWS Session Briefing ---');
+
+  // Git baseline
+  const headRev = getHeadRev(root);
+  const branch = getCurrentBranch(root);
+  const fingerprint = getWorkspaceFingerprint(root);
+  lines.push(`Git: ${branch} @ ${headRev} (${fingerprint.paths_touched.length} dirty files)`);
+
+  if (fingerprint.dirty) {
+    lines.push('WARNING: Working tree has uncommitted changes from a prior session.');
+  }
+
+  // Active sessions
+  const activeSessions = Object.entries(registry.sessions)
+    .filter(([, meta]) => meta.status === 'active')
+    .map(([id, meta]) => ({ id, ...meta }));
+
+  if (activeSessions.length > 0) {
+    lines.push(`Active sessions: ${activeSessions.length}`);
+    for (const s of activeSessions) {
+      lines.push(`  - ${s.id} (${s.role}, spec: ${s.spec_id || 'none'})`);
+    }
+  }
+
+  // Last completed session handoff
+  const completedSessions = Object.entries(registry.sessions)
+    .filter(([, meta]) => meta.status === 'completed')
+    .sort((a, b) => new Date(b[1].ended_at) - new Date(a[1].ended_at));
+
+  if (completedSessions.length > 0) {
+    const [lastId] = completedSessions[0];
+    try {
+      const capsule = showSession(lastId);
+      if (capsule.handoff.next_actions.length > 0) {
+        lines.push('Handoff from prior session:');
+        for (const action of capsule.handoff.next_actions) {
+          lines.push(`  - ${action}`);
+        }
+      }
+      if (capsule.known_issues.length > 0) {
+        lines.push('Known issues from prior session:');
+        for (const issue of capsule.known_issues) {
+          lines.push(`  - [${issue.type}] ${issue.description}`);
+        }
+      }
+    } catch {
+      // Non-fatal
+    }
+  }
+
+  lines.push('---');
+  lines.push("Run 'caws session start' to begin a tracked session.");
+  lines.push('--- End CAWS Briefing ---');
+
+  return lines.join('\n');
+}
+
+/**
+ * Find the most recent active session
+ * @param {Object} registry - Session registry
+ * @returns {string|null} Session ID or null
+ */
+function findActiveSession(registry) {
+  const active = Object.entries(registry.sessions)
+    .filter(([, meta]) => meta.status === 'active')
+    .sort((a, b) => new Date(b[1].started_at) - new Date(a[1].started_at));
+
+  return active.length > 0 ? active[0][0] : null;
+}
+
+module.exports = {
+  startSession,
+  checkpointSession,
+  endSession,
+  listSessions,
+  showSession,
+  getBriefing,
+  loadRegistry,
+  getRepoRoot,
+  SESSIONS_DIR,
+  REGISTRY_FILE,
+  CAPSULE_SCHEMA_VERSION,
+};

package/dist/test-analysis.js

@@ -607,7 +607,7 @@ async function testAnalysisCommand(subcommand, options = []) {
       case 'find-similar':
         return await handleFindSimilar(options);
       default:
-        console.log(chalk.red('❌ Unknown test-analysis subcommand'));
+        console.log(chalk.red('Unknown test-analysis subcommand'));
         console.log('Available commands:');
         console.log('  assess-budget    - Analyze budget needs for current spec');
         console.log('  analyze-patterns - Show waiver pattern analysis');
@@ -615,7 +615,7 @@ async function testAnalysisCommand(subcommand, options = []) {
         return;
     }
   } catch (error) {
-    console.error(chalk.red('❌ Test analysis failed:'), error.message);
+    console.error(chalk.red('Test analysis failed:'), error.message);
   }
 }
 
@@ -639,8 +639,8 @@ async function handleAssessBudget(options) {
     const specContent = fs.readFileSync(specPath, 'utf8');
     const spec = yaml.load(specContent);
 
-    console.log(chalk.cyan(`📊 Budget Assessment for ${spec.id}`));
-    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log(chalk.cyan(`Budget Assessment for ${spec.id}`));
+    console.log('==============================================');
 
     const result = predictor.assessBudget(spec);
 
@@ -650,14 +650,14 @@ async function handleAssessBudget(options) {
         `Historical Analysis: ${assessment.similar_projects_analyzed} similar projects analyzed`
       );
       console.log(
-        `🎯 Recommended Budget: ${assessment.recommended_budget.files} files, ${assessment.recommended_budget.loc} LOC (+${assessment.buffer_applied.files_percent}% buffer)`
+        `Recommended Budget: ${assessment.recommended_budget.files} files, ${assessment.recommended_budget.loc} LOC (+${assessment.buffer_applied.files_percent}% buffer)`
       );
-      console.log(`💡 Rationale: ${assessment.rationale.join('; ')}`);
+      console.log(`Rationale: ${assessment.rationale.join('; ')}`);
 
       if (assessment.risk_factors.length > 0) {
         console.log(
           chalk.yellow(
-            `⚠️ Risk Factors: ${assessment.risk_factors.map((f) => f.description).join('; ')}`
+            `Risk Factors: ${assessment.risk_factors.map((f) => f.description).join('; ')}`
           )
         );
       }
@@ -666,15 +666,15 @@ async function handleAssessBudget(options) {
         assessment.confidence > 0.8 ? 'High' : assessment.confidence > 0.6 ? 'Medium' : 'Low';
       console.log(
         chalk.green(
-          `✅ Confidence: ${confidenceLevel} (${Math.round(assessment.confidence * 100)}%)`
+          `Confidence: ${confidenceLevel} (${Math.round(assessment.confidence * 100)}%)`
         )
       );
     } else {
-      console.log(chalk.yellow(`⚠️ ${result.message}`));
-      console.log('💡 Consider using default tier-based budgeting for now');
+      console.log(chalk.yellow(`${result.message}`));
+      console.log('Consider using default tier-based budgeting for now');
     }
   } catch (error) {
-    console.error(chalk.red('❌ Failed to load spec:'), error.message);
+    console.error(chalk.red('Failed to load spec:'), error.message);
   }
 }
 
@@ -685,8 +685,8 @@ async function handleAnalyzePatterns(options) {
   const chalk = (await import('chalk')).default;
   const learner = new WaiverPatternLearner();
 
-  console.log(chalk.cyan('🔍 Analyzing Waiver Patterns'));
-  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log(chalk.cyan('Analyzing Waiver Patterns'));
+  console.log('==============================================');
 
   const result = learner.analyzePatterns();
 
@@ -696,7 +696,7 @@ async function handleAnalyzePatterns(options) {
     console.log(`Total waivers analyzed: ${patterns.total_waivers}`);
 
     if (patterns.budget_overruns) {
-      console.log('\n💰 Budget Overrun Patterns:');
+      console.log('\nBudget Overrun Patterns:');
       console.log(
         `  Average overrun: ${patterns.budget_overruns.average_overrun_files} files, ${patterns.budget_overruns.average_overrun_loc} LOC`
       );
@@ -712,7 +712,7 @@ async function handleAnalyzePatterns(options) {
     }
 
     if (patterns.common_reasons.length > 0) {
-      console.log('\n📋 Most Common Waiver Reasons:');
+      console.log('\nMost Common Waiver Reasons:');
       patterns.common_reasons.slice(0, 5).forEach((reason) => {
         console.log(
           `  ${reason.reason}: ${reason.count} times (${Math.round(reason.frequency * 100)}%)`
@@ -720,7 +720,7 @@ async function handleAnalyzePatterns(options) {
       });
     }
   } else {
-    console.log(chalk.yellow(`⚠️ ${result.message}`));
+    console.log(chalk.yellow(`${result.message}`));
   }
 }
 
@@ -744,8 +744,8 @@ async function handleFindSimilar(options) {
     const specContent = fs.readFileSync(specPath, 'utf8');
     const spec = yaml.load(specContent);
 
-    console.log(chalk.cyan(`🔍 Finding projects similar to ${spec.id}`));
-    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log(chalk.cyan(`Finding projects similar to ${spec.id}`));
+    console.log('==============================================');
 
     const similar = matcher.findSimilarProjects(spec);
 
@@ -758,10 +758,10 @@ async function handleFindSimilar(options) {
         );
       });
     } else {
-      console.log(chalk.yellow('⚠️ No similar projects found'));
+      console.log(chalk.yellow('No similar projects found'));
     }
   } catch (error) {
-    console.error(chalk.red('❌ Failed to load spec:'), error.message);
+    console.error(chalk.red('Failed to load spec:'), error.message);
   }
 }