cc4pm 1.8.0

package/scripts/hooks/session-end.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+/**
+ * Stop Hook (Session End) - Persist learnings during active sessions
+ *
+ * Cross-platform (Windows, macOS, Linux)
+ *
+ * Runs on Stop events (after each response). Extracts a meaningful summary
+ * from the session transcript (via stdin JSON transcript_path) and updates a
+ * session file for cross-session continuity.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const {
+  getSessionsDir,
+  getDateString,
+  getTimeString,
+  getSessionIdShort,
+  getProjectName,
+  ensureDir,
+  readFile,
+  writeFile,
+  runCommand,
+  log
+} = require('../lib/utils');
+
+const SUMMARY_START_MARKER = '<!-- ECC:SUMMARY:START -->';
+const SUMMARY_END_MARKER = '<!-- ECC:SUMMARY:END -->';
+const SESSION_SEPARATOR = '\n---\n';
+
+/**
+ * Extract a meaningful summary from the session transcript.
+ * Reads the JSONL transcript and pulls out key information:
+ * - User messages (tasks requested)
+ * - Tools used
+ * - Files modified
+ */
+function extractSessionSummary(transcriptPath) {
+  const content = readFile(transcriptPath);
+  if (!content) return null;
+
+  const lines = content.split('\n').filter(Boolean);
+  const userMessages = [];
+  const toolsUsed = new Set();
+  const filesModified = new Set();
+  let parseErrors = 0;
+
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+
+      // Collect user messages (first 200 chars each)
+      if (entry.type === 'user' || entry.role === 'user' || entry.message?.role === 'user') {
+        // Support both direct content and nested message.content (Claude Code JSONL format)
+        const rawContent = entry.message?.content ?? entry.content;
+        const text = typeof rawContent === 'string'
+          ? rawContent
+          : Array.isArray(rawContent)
+            ? rawContent.map(c => (c && c.text) || '').join(' ')
+            : '';
+        if (text.trim()) {
+          userMessages.push(text.trim().slice(0, 200));
+        }
+      }
+
+      // Collect tool names and modified files (direct tool_use entries)
+      if (entry.type === 'tool_use' || entry.tool_name) {
+        const toolName = entry.tool_name || entry.name || '';
+        if (toolName) toolsUsed.add(toolName);
+
+        const filePath = entry.tool_input?.file_path || entry.input?.file_path || '';
+        if (filePath && (toolName === 'Edit' || toolName === 'Write')) {
+          filesModified.add(filePath);
+        }
+      }
+
+      // Extract tool uses from assistant message content blocks (Claude Code JSONL format)
+      if (entry.type === 'assistant' && Array.isArray(entry.message?.content)) {
+        for (const block of entry.message.content) {
+          if (block.type === 'tool_use') {
+            const toolName = block.name || '';
+            if (toolName) toolsUsed.add(toolName);
+
+            const filePath = block.input?.file_path || '';
+            if (filePath && (toolName === 'Edit' || toolName === 'Write')) {
+              filesModified.add(filePath);
+            }
+          }
+        }
+      }
+    } catch {
+      parseErrors++;
+    }
+  }
+
+  if (parseErrors > 0) {
+    log(`[SessionEnd] Skipped ${parseErrors}/${lines.length} unparseable transcript lines`);
+  }
+
+  if (userMessages.length === 0) return null;
+
+  return {
+    userMessages: userMessages.slice(-10), // Last 10 user messages
+    toolsUsed: Array.from(toolsUsed).slice(0, 20),
+    filesModified: Array.from(filesModified).slice(0, 30),
+    totalMessages: userMessages.length
+  };
+}
+
+// Read hook input from stdin (Claude Code provides transcript_path via stdin JSON)
+const MAX_STDIN = 1024 * 1024;
+let stdinData = '';
+process.stdin.setEncoding('utf8');
+
+process.stdin.on('data', chunk => {
+  if (stdinData.length < MAX_STDIN) {
+    const remaining = MAX_STDIN - stdinData.length;
+    stdinData += chunk.substring(0, remaining);
+  }
+});
+
+process.stdin.on('end', () => {
+  runMain();
+});
+
+function runMain() {
+  main().catch(err => {
+    console.error('[SessionEnd] Error:', err.message);
+    process.exit(0);
+  });
+}
+
+function getSessionMetadata() {
+  const branchResult = runCommand('git rev-parse --abbrev-ref HEAD');
+
+  return {
+    project: getProjectName() || 'unknown',
+    branch: branchResult.success ? branchResult.output : 'unknown',
+    worktree: process.cwd()
+  };
+}
+
+function extractHeaderField(header, label) {
+  const match = header.match(new RegExp(`\\*\\*${escapeRegExp(label)}:\\*\\*\\s*(.+)$`, 'm'));
+  return match ? match[1].trim() : null;
+}
+
+function buildSessionHeader(today, currentTime, metadata, existingContent = '') {
+  const headingMatch = existingContent.match(/^#\s+.+$/m);
+  const heading = headingMatch ? headingMatch[0] : `# Session: ${today}`;
+  const date = extractHeaderField(existingContent, 'Date') || today;
+  const started = extractHeaderField(existingContent, 'Started') || currentTime;
+
+  return [
+    heading,
+    `**Date:** ${date}`,
+    `**Started:** ${started}`,
+    `**Last Updated:** ${currentTime}`,
+    `**Project:** ${metadata.project}`,
+    `**Branch:** ${metadata.branch}`,
+    `**Worktree:** ${metadata.worktree}`,
+    ''
+  ].join('\n');
+}
+
+function mergeSessionHeader(content, today, currentTime, metadata) {
+  const separatorIndex = content.indexOf(SESSION_SEPARATOR);
+  if (separatorIndex === -1) {
+    return null;
+  }
+
+  const existingHeader = content.slice(0, separatorIndex);
+  const body = content.slice(separatorIndex + SESSION_SEPARATOR.length);
+  const nextHeader = buildSessionHeader(today, currentTime, metadata, existingHeader);
+  return `${nextHeader}${SESSION_SEPARATOR}${body}`;
+}
+
+async function main() {
+  // Parse stdin JSON to get transcript_path
+  let transcriptPath = null;
+  try {
+    const input = JSON.parse(stdinData);
+    transcriptPath = input.transcript_path;
+  } catch {
+    // Fallback: try env var for backwards compatibility
+    transcriptPath = process.env.CLAUDE_TRANSCRIPT_PATH;
+  }
+
+  const sessionsDir = getSessionsDir();
+  const today = getDateString();
+  const shortId = getSessionIdShort();
+  const sessionFile = path.join(sessionsDir, `${today}-${shortId}-session.tmp`);
+  const sessionMetadata = getSessionMetadata();
+
+  ensureDir(sessionsDir);
+
+  const currentTime = getTimeString();
+
+  // Try to extract summary from transcript
+  let summary = null;
+
+  if (transcriptPath) {
+    if (fs.existsSync(transcriptPath)) {
+      summary = extractSessionSummary(transcriptPath);
+    } else {
+      log(`[SessionEnd] Transcript not found: ${transcriptPath}`);
+    }
+  }
+
+  if (fs.existsSync(sessionFile)) {
+    const existing = readFile(sessionFile);
+    let updatedContent = existing;
+
+    if (existing) {
+      const merged = mergeSessionHeader(existing, today, currentTime, sessionMetadata);
+      if (merged) {
+        updatedContent = merged;
+      } else {
+        log(`[SessionEnd] Failed to normalize header in ${sessionFile}`);
+      }
+    }
+
+    // If we have a new summary, update only the generated summary block.
+    // This keeps repeated Stop invocations idempotent and preserves
+    // user-authored sections in the same session file.
+    if (summary && updatedContent) {
+      const summaryBlock = buildSummaryBlock(summary);
+
+      if (updatedContent.includes(SUMMARY_START_MARKER) && updatedContent.includes(SUMMARY_END_MARKER)) {
+        updatedContent = updatedContent.replace(
+          new RegExp(`${escapeRegExp(SUMMARY_START_MARKER)}[\\s\\S]*?${escapeRegExp(SUMMARY_END_MARKER)}`),
+          summaryBlock
+        );
+      } else {
+        // Migration path for files created before summary markers existed.
+        updatedContent = updatedContent.replace(
+          /## (?:Session Summary|Current State)[\s\S]*?$/,
+          `${summaryBlock}\n\n### Notes for Next Session\n-\n\n### Context to Load\n\`\`\`\n[relevant files]\n\`\`\`\n`
+        );
+      }
+    }
+
+    if (updatedContent) {
+      writeFile(sessionFile, updatedContent);
+    }
+
+    log(`[SessionEnd] Updated session file: ${sessionFile}`);
+  } else {
+    // Create new session file
+    const summarySection = summary
+      ? `${buildSummaryBlock(summary)}\n\n### Notes for Next Session\n-\n\n### Context to Load\n\`\`\`\n[relevant files]\n\`\`\``
+      : `## Current State\n\n[Session context goes here]\n\n### Completed\n- [ ]\n\n### In Progress\n- [ ]\n\n### Notes for Next Session\n-\n\n### Context to Load\n\`\`\`\n[relevant files]\n\`\`\``;
+
+    const template = `${buildSessionHeader(today, currentTime, sessionMetadata)}${SESSION_SEPARATOR}${summarySection}
+`;
+
+    writeFile(sessionFile, template);
+    log(`[SessionEnd] Created session file: ${sessionFile}`);
+  }
+
+  process.exit(0);
+}
+
+function buildSummarySection(summary) {
+  let section = '## Session Summary\n\n';
+
+  // Tasks (from user messages — collapse newlines and escape backticks to prevent markdown breaks)
+  section += '### Tasks\n';
+  for (const msg of summary.userMessages) {
+    section += `- ${msg.replace(/\n/g, ' ').replace(/`/g, '\\`')}\n`;
+  }
+  section += '\n';
+
+  // Files modified
+  if (summary.filesModified.length > 0) {
+    section += '### Files Modified\n';
+    for (const f of summary.filesModified) {
+      section += `- ${f}\n`;
+    }
+    section += '\n';
+  }
+
+  // Tools used
+  if (summary.toolsUsed.length > 0) {
+    section += `### Tools Used\n${summary.toolsUsed.join(', ')}\n\n`;
+  }
+
+  section += `### Stats\n- Total user messages: ${summary.totalMessages}\n`;
+
+  return section;
+}
+
+function buildSummaryBlock(summary) {
+  return `${SUMMARY_START_MARKER}\n${buildSummarySection(summary).trim()}\n${SUMMARY_END_MARKER}`;
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/scripts/hooks/session-start.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * SessionStart Hook - Load previous context on new session
+ *
+ * Cross-platform (Windows, macOS, Linux)
+ *
+ * Runs when a new Claude session starts. Loads the most recent session
+ * summary into Claude's context via stdout, and reports available
+ * sessions and learned skills.
+ */
+
+const {
+  getSessionsDir,
+  getLearnedSkillsDir,
+  findFiles,
+  ensureDir,
+  readFile,
+  log,
+  output
+} = require('../lib/utils');
+const { getPackageManager, getSelectionPrompt } = require('../lib/package-manager');
+const { listAliases } = require('../lib/session-aliases');
+const { detectProjectType } = require('../lib/project-detect');
+
+async function main() {
+  const sessionsDir = getSessionsDir();
+  const learnedDir = getLearnedSkillsDir();
+
+  // Ensure directories exist
+  ensureDir(sessionsDir);
+  ensureDir(learnedDir);
+
+  // Check for recent session files (last 7 days)
+  const recentSessions = findFiles(sessionsDir, '*-session.tmp', { maxAge: 7 });
+
+  if (recentSessions.length > 0) {
+    const latest = recentSessions[0];
+    log(`[SessionStart] Found ${recentSessions.length} recent session(s)`);
+    log(`[SessionStart] Latest: ${latest.path}`);
+
+    // Read and inject the latest session content into Claude's context
+    const content = readFile(latest.path);
+    if (content && !content.includes('[Session context goes here]')) {
+      // Only inject if the session has actual content (not the blank template)
+      output(`Previous session summary:\n${content}`);
+    }
+  }
+
+  // Check for learned skills
+  const learnedSkills = findFiles(learnedDir, '*.md');
+
+  if (learnedSkills.length > 0) {
+    log(`[SessionStart] ${learnedSkills.length} learned skill(s) available in ${learnedDir}`);
+  }
+
+  // Check for available session aliases
+  const aliases = listAliases({ limit: 5 });
+
+  if (aliases.length > 0) {
+    const aliasNames = aliases.map(a => a.name).join(', ');
+    log(`[SessionStart] ${aliases.length} session alias(es) available: ${aliasNames}`);
+    log(`[SessionStart] Use /sessions load <alias> to continue a previous session`);
+  }
+
+  // Detect and report package manager
+  const pm = getPackageManager();
+  log(`[SessionStart] Package manager: ${pm.name} (${pm.source})`);
+
+  // If no explicit package manager config was found, show selection prompt
+  if (pm.source === 'default') {
+    log('[SessionStart] No package manager preference found.');
+    log(getSelectionPrompt());
+  }
+
+  // Detect project type and frameworks (#293)
+  const projectInfo = detectProjectType();
+  if (projectInfo.languages.length > 0 || projectInfo.frameworks.length > 0) {
+    const parts = [];
+    if (projectInfo.languages.length > 0) {
+      parts.push(`languages: ${projectInfo.languages.join(', ')}`);
+    }
+    if (projectInfo.frameworks.length > 0) {
+      parts.push(`frameworks: ${projectInfo.frameworks.join(', ')}`);
+    }
+    log(`[SessionStart] Project detected — ${parts.join('; ')}`);
+    output(`Project type: ${JSON.stringify(projectInfo)}`);
+  } else {
+    log('[SessionStart] No specific project type detected');
+  }
+
+  process.exit(0);
+}
+
+main().catch(err => {
+  console.error('[SessionStart] Error:', err.message);
+  process.exit(0); // Don't block on errors
+});

package/scripts/hooks/suggest-compact.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * Strategic Compact Suggester
+ *
+ * Cross-platform (Windows, macOS, Linux)
+ *
+ * Runs on PreToolUse or periodically to suggest manual compaction at logical intervals
+ *
+ * Why manual over auto-compact:
+ * - Auto-compact happens at arbitrary points, often mid-task
+ * - Strategic compacting preserves context through logical phases
+ * - Compact after exploration, before execution
+ * - Compact after completing a milestone, before starting next
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  getTempDir,
+  writeFile,
+  log
+} = require('../lib/utils');
+
+async function main() {
+  // Track tool call count (increment in a temp file)
+  // Use a session-specific counter file based on session ID from environment
+  // or parent PID as fallback
+  const sessionId = (process.env.CLAUDE_SESSION_ID || 'default').replace(/[^a-zA-Z0-9_-]/g, '') || 'default';
+  const counterFile = path.join(getTempDir(), `claude-tool-count-${sessionId}`);
+  const rawThreshold = parseInt(process.env.COMPACT_THRESHOLD || '50', 10);
+  const threshold = Number.isFinite(rawThreshold) && rawThreshold > 0 && rawThreshold <= 10000
+    ? rawThreshold
+    : 50;
+
+  let count = 1;
+
+  // Read existing count or start at 1
+  // Use fd-based read+write to reduce (but not eliminate) race window
+  // between concurrent hook invocations
+  try {
+    const fd = fs.openSync(counterFile, 'a+');
+    try {
+      const buf = Buffer.alloc(64);
+      const bytesRead = fs.readSync(fd, buf, 0, 64, 0);
+      if (bytesRead > 0) {
+        const parsed = parseInt(buf.toString('utf8', 0, bytesRead).trim(), 10);
+        // Clamp to reasonable range — corrupted files could contain huge values
+        // that pass Number.isFinite() (e.g., parseInt('9'.repeat(30)) => 1e+29)
+        count = (Number.isFinite(parsed) && parsed > 0 && parsed <= 1000000)
+          ? parsed + 1
+          : 1;
+      }
+      // Truncate and write new value
+      fs.ftruncateSync(fd, 0);
+      fs.writeSync(fd, String(count), 0);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    // Fallback: just use writeFile if fd operations fail
+    writeFile(counterFile, String(count));
+  }
+
+  // Suggest compact after threshold tool calls
+  if (count === threshold) {
+    log(`[StrategicCompact] ${threshold} tool calls reached - consider /compact if transitioning phases`);
+  }
+
+  // Suggest at regular intervals after threshold (every 25 calls from threshold)
+  if (count > threshold && (count - threshold) % 25 === 0) {
+    log(`[StrategicCompact] ${count} tool calls - good checkpoint for /compact if context is stale`);
+  }
+
+  process.exit(0);
+}
+
+main().catch(err => {
+  console.error('[StrategicCompact] Error:', err.message);
+  process.exit(0);
+});

package/scripts/install-apply.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+/**
+ * Refactored cc4pm installer runtime.
+ *
+ * Keeps the legacy language-based install entrypoint intact while moving
+ * target-specific mutation logic into testable Node code.
+ */
+
+const {
+  SUPPORTED_INSTALL_TARGETS,
+  listAvailableLanguages,
+} = require('./lib/install-executor');
+const {
+  LEGACY_INSTALL_TARGETS,
+  normalizeInstallRequest,
+  parseInstallArgs,
+} = require('./lib/install/request');
+const { loadInstallConfig } = require('./lib/install/config');
+const { applyInstallPlan } = require('./lib/install/apply');
+const { createInstallPlanFromRequest } = require('./lib/install/runtime');
+
+function showHelp(exitCode = 0) {
+  const languages = listAvailableLanguages();
+
+  console.log(`
+Usage: install.sh [--target <${LEGACY_INSTALL_TARGETS.join('|')}>] [--dry-run] [--json] <language> [<language> ...]
+       install.sh [--target <${SUPPORTED_INSTALL_TARGETS.join('|')}>] [--dry-run] [--json] --profile <name> [--with <component>]... [--without <component>]...
+       install.sh [--target <${SUPPORTED_INSTALL_TARGETS.join('|')}>] [--dry-run] [--json] --modules <id,id,...> [--with <component>]... [--without <component>]...
+       install.sh [--dry-run] [--json] --config <path>
+
+Targets:
+  claude       (default) - Install rules to ~/.claude/rules/
+  cursor       - Install rules, hooks, and bundled Cursor configs to ./.cursor/
+  antigravity  - Install rules, workflows, skills, and agents to ./.agent/
+
+Options:
+  --profile <name>    Resolve and install a manifest profile
+  --modules <ids>     Resolve and install explicit module IDs
+  --with <component>  Include a user-facing install component
+  --without <component>
+                      Exclude a user-facing install component
+  --config <path>     Load install intent from ecc-install.json
+  --dry-run    Show the install plan without copying files
+  --json       Emit machine-readable plan/result JSON
+  --help       Show this help text
+
+Available languages:
+${languages.map(language => `  - ${language}`).join('\n')}
+`);
+
+  process.exit(exitCode);
+}
+
+function printHumanPlan(plan, dryRun) {
+  console.log(`${dryRun ? 'Dry-run install plan' : 'Applying install plan'}:\n`);
+  console.log(`Mode: ${plan.mode}`);
+  console.log(`Target: ${plan.target}`);
+  console.log(`Adapter: ${plan.adapter.id}`);
+  console.log(`Install root: ${plan.installRoot}`);
+  console.log(`Install-state: ${plan.installStatePath}`);
+  if (plan.mode === 'legacy') {
+    console.log(`Languages: ${plan.languages.join(', ')}`);
+  } else {
+    console.log(`Profile: ${plan.profileId || '(custom modules)'}`);
+    console.log(`Included components: ${plan.includedComponentIds.join(', ') || '(none)'}`);
+    console.log(`Excluded components: ${plan.excludedComponentIds.join(', ') || '(none)'}`);
+    console.log(`Requested modules: ${plan.requestedModuleIds.join(', ') || '(none)'}`);
+    console.log(`Selected modules: ${plan.selectedModuleIds.join(', ') || '(none)'}`);
+    if (plan.skippedModuleIds.length > 0) {
+      console.log(`Skipped modules: ${plan.skippedModuleIds.join(', ')}`);
+    }
+    if (plan.excludedModuleIds.length > 0) {
+      console.log(`Excluded modules: ${plan.excludedModuleIds.join(', ')}`);
+    }
+  }
+  console.log(`Operations: ${plan.operations.length}`);
+
+  if (plan.warnings.length > 0) {
+    console.log('\nWarnings:');
+    for (const warning of plan.warnings) {
+      console.log(`- ${warning}`);
+    }
+  }
+
+  console.log('\nPlanned file operations:');
+  for (const operation of plan.operations) {
+    console.log(`- ${operation.sourceRelativePath} -> ${operation.destinationPath}`);
+  }
+
+  if (!dryRun) {
+    console.log(`\nDone. Install-state written to ${plan.installStatePath}`);
+  }
+}
+
+function main() {
+  try {
+    const options = parseInstallArgs(process.argv);
+
+    if (options.help) {
+      showHelp(0);
+    }
+
+    const config = options.configPath
+      ? loadInstallConfig(options.configPath, { cwd: process.cwd() })
+      : null;
+    const request = normalizeInstallRequest({
+      ...options,
+      config,
+    });
+    const plan = createInstallPlanFromRequest(request, {
+      projectRoot: process.cwd(),
+      homeDir: process.env.HOME,
+      claudeRulesDir: process.env.CLAUDE_RULES_DIR || null,
+    });
+
+    if (options.dryRun) {
+      if (options.json) {
+        console.log(JSON.stringify({ dryRun: true, plan }, null, 2));
+      } else {
+        printHumanPlan(plan, true);
+      }
+      return;
+    }
+
+    const result = applyInstallPlan(plan);
+    if (options.json) {
+      console.log(JSON.stringify({ dryRun: false, result }, null, 2));
+    } else {
+      printHumanPlan(result, false);
+    }
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();