@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/hooks/readme-age-check.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * readme-age-check.mjs — Stop hook (async)
+ *
+ * On session end, scans tracked READMEs whose last commit is older than 90
+ * days and emits `readme.stale` for cx-docs-keeper. Rate-limited via
+ * ~/.cx/readme-age-state.json so the same README isn't reported more than
+ * once per week.
+ *
+ * @p95ms 1500
+ * @maxBlockingScope none (async, non-blocking)
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { emitRoleEvent } from '../roles/hook-emit.mjs';
+
+const STATE_PATH = join(homedir(), '.cx', 'readme-age-state.json');
+const STALE_DAYS = 90;
+const SUPPRESS_DAYS = 7;
+
+const cwd = process.cwd();
+
+function listReadmes() {
+  try {
+    const out = execSync(
+      "git ls-files | grep -E '(^|/)README\\.md$' | head -50",
+      { cwd, timeout: 2000, shell: '/bin/sh' }
+    ).toString();
+    return out.split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function lastCommitTs(file) {
+  try {
+    const out = execSync(`git log -1 --format=%at -- "${file}"`, { cwd, timeout: 2000 }).toString().trim();
+    return parseInt(out, 10) * 1000;
+  } catch {
+    return 0;
+  }
+}
+
+function loadState() {
+  try { return JSON.parse(readFileSync(STATE_PATH, 'utf8')); } catch { return {}; }
+}
+function saveState(state) {
+  try { writeFileSync(STATE_PATH, JSON.stringify(state)); } catch { /* best effort */ }
+}
+
+const readmes = listReadmes();
+if (readmes.length === 0) process.exit(0);
+
+const state = loadState();
+const now = Date.now();
+const staleThreshold = now - STALE_DAYS * 24 * 60 * 60 * 1000;
+const suppressUntil = now - SUPPRESS_DAYS * 24 * 60 * 60 * 1000;
+
+for (const file of readmes) {
+  const ts = lastCommitTs(file);
+  if (!ts || ts >= staleThreshold) continue;
+  const prev = state[file] || 0;
+  if (prev > suppressUntil) continue;
+  emitRoleEvent({
+    type: 'readme.stale',
+    summary: `${file} last updated ${Math.round((now - ts) / (24 * 60 * 60 * 1000))} days ago`,
+    hookInput: { cwd },
+    context: { file, lastCommitTs: ts },
+  });
+  state[file] = now;
+}
+
+saveState(state);
+process.exit(0);

package/lib/hooks/registry-sync.mjs

@@ -3,21 +3,28 @@
  * lib/hooks/registry-sync.mjs — Registry sync hook — reminds to run construct sync after registry changes.
  *
  * Runs as PostToolUse after edits to agents/registry.json. Checks if the file was modified and emits a reminder to run construct sync to regenerate platform adapters.
+ *
+ * @p95ms 12000
+ * @maxBlockingScope none (PostToolUse, non-blocking)
  */
 import { execSync } from 'child_process';
+import path from 'node:path';
+import { logHookFailure } from './_lib/log.mjs';
+import { constructDir } from '../paths.mjs';
 
 const filePath = process.env.TOOL_INPUT_FILE_PATH || '';
-if (!filePath.endsWith('/agents/registry.json')) process.exit(0);
+if (!filePath.endsWith(path.join('agents', 'registry.json')) && !filePath.endsWith('/agents/registry.json')) process.exit(0);
 
-const toolkitDir = process.env.CX_TOOLKIT_DIR || `${process.env.HOME}/.construct`;
+const toolkitDir = constructDir();
 try {
-  execSync('node sync-agents.mjs', {
+  execSync('node scripts/sync-agents.mjs', {
     cwd: toolkitDir,
     stdio: 'pipe',
     env: { ...process.env, CX_TOOLKIT_DIR: toolkitDir },
     timeout: 12_000,
   });
-} catch (e) {
-  process.stderr.write(`[registry-sync] Sync failed: ${e.message}\n`);
+} catch (err) {
+  logHookFailure({ hook: 'registry-sync', err, phase: 'execute', input: { toolkitDir } });
+  process.stderr.write(`[registry-sync] Sync failed: ${err.message}\n`);
 }
 process.exit(0);

package/lib/hooks/scan-secrets.mjs

@@ -3,9 +3,13 @@
  * lib/hooks/scan-secrets.mjs — Scan secrets hook — detects potential secrets in files before they are committed.
  *
  * Runs as PostToolUse after Edit/Write. Scans the modified file content against known secret patterns (API keys, tokens, passwords) and blocks (exit 2) on matches.
+ *
+ * @p95ms 30
+ * @maxBlockingScope PostToolUse
  */
 import { readFileSync } from 'fs';
 import { extname } from 'path';
+import { logHookFailure } from './_lib/log.mjs';
 
 const SCAN_EXTENSIONS = new Set([
   '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
@@ -23,15 +27,42 @@ const PLACEHOLDER_PATTERNS = [
   /__[A-Z_]+__/,
 ];
 
+// Patterns are matched per-line so multiple findings in one file are
+// surfaced together. Capture group 1 is included in the JSONL log if
+// present; otherwise the full match is used.
 const SECRET_PATTERNS = [
   { name: 'Anthropic API key', pattern: /ANTHROPIC_API_KEY\s*=\s*(sk-ant-[a-zA-Z0-9\-_]{20,})/i },
+  { name: 'Anthropic admin key', pattern: /(sk-ant-admin-[a-zA-Z0-9\-_]{20,})/ },
   { name: 'OpenAI API key', pattern: /OPENAI_API_KEY\s*=\s*(sk-[a-zA-Z0-9]{40,})/i },
+  { name: 'OpenAI project key', pattern: /(sk-proj-[a-zA-Z0-9_\-]{40,})/ },
+  { name: 'OpenAI organization key', pattern: /(sk-svcacct-[a-zA-Z0-9_\-]{40,})/ },
   { name: 'OpenRouter key', pattern: /(sk-or-v1-[a-zA-Z0-9]{40,})/ },
   { name: 'AWS access key', pattern: /(AKIA[0-9A-Z]{16})/ },
-  { name: 'Private key (PEM)', pattern: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/ },
-  { name: 'GitHub personal access token', pattern: /(ghp_[a-zA-Z0-9]{36})/ },
+  { name: 'AWS secret access key', pattern: /aws[_\-]?secret[_\-]?access[_\-]?key\s*[:=]\s*['"]?([A-Za-z0-9\/\+=]{40})/i },
+  { name: 'AWS session token', pattern: /(ASIA[0-9A-Z]{16})/ },
+  { name: 'GCP service account JSON key', pattern: /"private_key"\s*:\s*"-----BEGIN PRIVATE KEY-----/ },
+  { name: 'GCP API key', pattern: /(AIza[0-9A-Za-z\-_]{35})/ },
+  { name: 'Azure storage account key', pattern: /AccountKey\s*=\s*([A-Za-z0-9\+\/=]{88})/ },
+  { name: 'Private key (PEM)', pattern: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/ },
+  { name: 'SSH private key', pattern: /-----BEGIN OPENSSH PRIVATE KEY-----/ },
+  { name: 'GitHub personal access token (classic)', pattern: /(ghp_[a-zA-Z0-9]{36})/ },
+  { name: 'GitHub fine-grained PAT', pattern: /(github_pat_[A-Z0-9]{22}_[A-Za-z0-9]{59})/ },
   { name: 'GitHub Actions token', pattern: /(ghs_[a-zA-Z0-9]{36})/ },
-  { name: 'Database URL with credentials', pattern: /DATABASE_URL\s*=\s*(postgresql:\/\/[^@]+:[^@]+@)/i },
+  { name: 'GitHub OAuth token', pattern: /(gho_[a-zA-Z0-9]{36})/ },
+  { name: 'GitHub user-to-server token', pattern: /(ghu_[a-zA-Z0-9]{36})/ },
+  { name: 'GitHub server-to-server token', pattern: /(ghr_[a-zA-Z0-9]{36})/ },
+  { name: 'Slack bot token', pattern: /(xoxb-[0-9]{10,}-[0-9]{10,}-[a-zA-Z0-9]{24,})/ },
+  { name: 'Slack user token', pattern: /(xoxp-[0-9]{10,}-[0-9]{10,}-[0-9]{10,}-[a-z0-9]{32,})/ },
+  { name: 'Slack webhook URL', pattern: /(https:\/\/hooks\.slack\.com\/services\/T[A-Z0-9]+\/B[A-Z0-9]+\/[A-Za-z0-9]{24})/ },
+  { name: 'Stripe live secret', pattern: /(sk_live_[A-Za-z0-9]{20,})/ },
+  { name: 'Stripe restricted key', pattern: /(rk_live_[A-Za-z0-9]{20,})/ },
+  { name: 'Twilio account SID', pattern: /(AC[a-f0-9]{32})/ },
+  { name: 'Twilio auth token', pattern: /TWILIO_AUTH_TOKEN\s*=\s*([a-f0-9]{32})/i },
+  { name: 'SendGrid API key', pattern: /(SG\.[a-zA-Z0-9_\-]{22}\.[a-zA-Z0-9_\-]{43})/ },
+  { name: 'Mailgun API key', pattern: /(key-[a-z0-9]{32})/ },
+  { name: 'JWT (signed)', pattern: /(eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_\-]{10,})/ },
+  { name: 'Database URL with credentials', pattern: /(?:DATABASE|POSTGRES|MYSQL|MONGODB)_URL\s*=\s*([a-z]+:\/\/[^:\s]+:[^@\s]+@)/i },
+  { name: 'Generic API key (env-style)', pattern: /(?:^|\s)([A-Z][A-Z0-9_]*(?:API|SECRET|TOKEN|PASSWORD|PRIVATE)_KEY)\s*=\s*['"]?([A-Za-z0-9_\-+/=]{30,})['"]?/, captureGroup: 2 },
 ];
 
 function isPlaceholder(value) {
@@ -48,7 +79,8 @@ if (!SCAN_EXTENSIONS.has(ext)) process.exit(0);
 let content;
 try {
   content = readFileSync(filePath, 'utf8');
-} catch {
+} catch (err) {
+  logHookFailure({ hook: 'scan-secrets', err, phase: 'read', input: { filePath } });
   process.exit(0);
 }
 
@@ -57,12 +89,12 @@ const findings = [];
 
 for (let i = 0; i < lines.length; i++) {
   const line = lines[i];
-  for (const { name, pattern } of SECRET_PATTERNS) {
+  for (const { name, pattern, captureGroup } of SECRET_PATTERNS) {
     const match = pattern.exec(line);
     if (!match) continue;
-    const captured = match[1] ?? match[0];
+    const captured = match[captureGroup ?? 1] ?? match[0];
     if (isPlaceholder(captured)) continue;
-    findings.push({ name, line: i + 1, value: captured.slice(0, 20) + '...' });
+    findings.push({ name, line: i + 1, value: String(captured).slice(0, 20) + '...' });
   }
 }
 
@@ -73,4 +105,15 @@ for (const { name, line, value } of findings) {
   process.stderr.write(`  Line ${line}: ${name} — matched value starts with: ${value}\n`);
 }
 process.stderr.write('Remove or rotate the secret before writing this file.\n');
+
+try {
+  const { emitRoleEvent } = await import('../roles/hook-emit.mjs');
+  emitRoleEvent({
+    type: 'secrets.detected',
+    summary: `Secret(s) detected in ${filePath}: ${findings.map((f) => f.name).join(', ')}`,
+    hookInput: {},
+    context: { filePath, findings },
+  });
+} catch { /* best effort */ }
+
 process.exit(2);

package/lib/hooks/session-optimize.mjs

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/session-optimize.mjs — Session end optimization hook — triggers agent optimization for low-performers.
+ *
+ * Runs as a Stop hook at session end. Checks recent performance reviews for agents with avgScore < 0.7
+ * and invokes `construct optimize <agent>` to generate and apply improvement patches.
+ *
+ * @p95ms 300
+ * @maxBlockingScope Stop (non-blocking, async)
+ */
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { spawnSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONSTRUCT_BIN = join(__dirname, '..', '..', 'bin', 'construct');
+
+const OPTIMIZATION_THRESHOLD = 0.7;     // Score below this triggers optimization
+const MIN_TRACES_PER_AGENT = 3;          // Minimum traces needed for optimization
+const OPTIMIZATION_DAYS = 7;            // Look back 7 days for performance data
+const OPTIMIZATION_LOG_DIR = join(homedir(), '.cx', 'optimization-logs');
+
+// Ensure optimization log directory exists
+mkdirSync(OPTIMIZATION_LOG_DIR, { recursive: true });
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+// Only run for Construct sessions
+const cwd = input?.cwd || process.cwd();
+const projectName = cwd.split('/').pop() || 'project';
+
+// Skip if this is not a Construct project or in global mode
+if (projectName !== 'construct' && !existsSync(join(cwd, '.cx'))) {
+  process.exit(0);
+}
+
+// Reviews older than this trigger an auto-refresh on the next session-stop.
+// Six hours keeps optimization signal current without re-running review on
+// every short session. Operators can still run `construct review` manually.
+const REVIEW_REFRESH_MS = 6 * 60 * 60 * 1000;
+
+function maybeRefreshReviews() {
+  const reviewsDir = join(homedir(), '.cx', 'performance-reviews');
+  let needsRefresh = false;
+  try {
+    if (!existsSync(reviewsDir)) {
+      needsRefresh = true;
+    } else {
+      const files = spawnSync('find', [reviewsDir, '-name', '*.json', '-type', 'f'], {
+        encoding: 'utf8', timeout: 5000,
+      }).stdout.trim().split('\n').filter(Boolean);
+      if (files.length === 0) {
+        needsRefresh = true;
+      } else {
+        const newestMs = files.reduce((acc, f) => {
+          try {
+            const m = Number(spawnSync('stat', ['-f', '%m', f], { encoding: 'utf8' }).stdout.trim());
+            return Number.isFinite(m) ? Math.max(acc, m * 1000) : acc;
+          } catch { return acc; }
+        }, 0);
+        if (Date.now() - newestMs > REVIEW_REFRESH_MS) needsRefresh = true;
+      }
+    }
+  } catch { /* tolerate fs errors silently — refresh is best-effort */ }
+
+  if (!needsRefresh) return;
+
+  // Refresh detached so the Stop hook does not block on telemetry latency.
+  try {
+    spawnSync(process.execPath, [CONSTRUCT_BIN, 'review', '--quiet'], {
+      stdio: 'ignore',
+      timeout: 60_000,
+      detached: true,
+    });
+  } catch { /* refresh is best-effort; manual `construct review` is always available */ }
+}
+
+// Read the most recent performance review
+function getLatestPerformanceReview() {
+  const reviewsDir = join(homedir(), '.cx', 'performance-reviews');
+  if (!existsSync(reviewsDir)) return null;
+
+  try {
+    const files = spawnSync('find', [reviewsDir, '-name', '*.json', '-type', 'f'], {
+      encoding: 'utf8',
+      timeout: 5000
+    }).stdout.trim().split('\n').filter(Boolean);
+
+    if (files.length === 0) return null;
+    
+    // Sort by modification time, newest first
+    files.sort((a, b) => {
+      try {
+        const statA = spawnSync('stat', ['-f', '%m', a], { encoding: 'utf8' }).stdout.trim();
+        const statB = spawnSync('stat', ['-f', '%m', b], { encoding: 'utf8' }).stdout.trim();
+        return parseInt(statB) - parseInt(statA);
+      } catch {
+        return 0;
+      }
+    });
+    
+    const latestFile = files[0];
+    const content = readFileSync(latestFile, 'utf8');
+    return JSON.parse(content);
+  } catch (error) {
+    console.error(`Error reading performance reviews: ${error.message}`);
+    return null;
+  }
+}
+
+// Check if agent needs optimization
+function needsOptimization(agentStats) {
+  return (
+    agentStats.scoredInvocations >= MIN_TRACES_PER_AGENT &&
+    agentStats.avgScore < OPTIMIZATION_THRESHOLD &&
+    agentStats.lowScoreTraces.length > 0
+  );
+}
+
+// Run optimization for a specific agent
+function optimizeAgent(agentName) {
+  console.log(`🔧 Optimizing ${agentName} (score < ${OPTIMIZATION_THRESHOLD})`);
+  
+  const logFile = join(OPTIMIZATION_LOG_DIR, `${new Date().toISOString().split('T')[0]}-${agentName}.log`);
+  const startTime = Date.now();
+  
+  try {
+    // Run construct optimize with auto-apply (no --dry-run)
+    const result = spawnSync(CONSTRUCT_BIN, ['optimize', agentName, `--days=${OPTIMIZATION_DAYS}`], {
+      cwd,
+      encoding: 'utf8',
+      timeout: 300000, // 5 minutes timeout for optimization
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    
+    const duration = Date.now() - startTime;
+    
+    // Log the optimization attempt
+    const logEntry = {
+      timestamp: new Date().toISOString(),
+      agent: agentName,
+      durationMs: duration,
+      success: result.status === 0,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      exitCode: result.status,
+      signal: result.signal
+    };
+    
+    writeFileSync(logFile, JSON.stringify(logEntry, null, 2) + '\n');
+    
+    if (result.status === 0) {
+      console.log(`✅ Optimization for ${agentName} completed in ${duration}ms`);
+      
+      // Record observation about the optimization
+      recordOptimizationObservation(agentName, true, duration);
+    } else {
+      console.log(`❌ Optimization for ${agentName} failed with code ${result.status}`);
+      console.log(`Stderr: ${result.stderr.slice(0, 500)}...`);
+      
+      // Record observation about the failure
+      recordOptimizationObservation(agentName, false, duration, result.stderr);
+    }
+    
+    return result.status === 0;
+  } catch (error) {
+    console.error(`❌ Optimization for ${agentName} threw error: ${error.message}`);
+    
+    const logEntry = {
+      timestamp: new Date().toISOString(),
+      agent: agentName,
+      durationMs: Date.now() - startTime,
+      success: false,
+      error: error.message,
+      stack: error.stack
+    };
+    
+    writeFileSync(logFile, JSON.stringify(logEntry, null, 2) + '\n');
+    return false;
+  }
+}
+
+// Record optimization observation for learning
+function recordOptimizationObservation(agentName, success, durationMs, error = null) {
+  const observation = {
+    role: 'construct',
+    category: success ? 'pattern' : 'anti-pattern',
+    summary: success 
+      ? `Auto-optimized ${agentName} in ${durationMs}ms`
+      : `Auto-optimization failed for ${agentName}: ${error?.slice(0, 200) || 'unknown error'}`,
+    content: success
+      ? `Automatic optimization triggered for ${agentName} after performance review showed avgScore < ${OPTIMIZATION_THRESHOLD}. Optimization completed successfully in ${durationMs}ms.`
+      : `Automatic optimization failed for ${agentName}. Error: ${error || 'Unknown'}. System should notify maintainer.`,
+    tags: ['auto-optimization', 'performance-review', agentName],
+    confidence: 0.9
+  };
+  
+  try {
+    // Use existing observation recording if available
+    const observationFile = join(homedir(), '.cx', 'observations', `${Date.now()}-${agentName}-optimization.json`);
+    mkdirSync(dirname(observationFile), { recursive: true });
+    writeFileSync(observationFile, JSON.stringify(observation, null, 2) + '\n');
+  } catch (error) {
+    // Non-critical - observation recording failed
+    console.error(`Failed to record optimization observation: ${error.message}`);
+  }
+}
+
+// Main optimization logic
+function main() {
+  // If the most recent review is missing or stale (>6h), kick off a refresh
+  // detached so the Stop hook returns promptly. The refresh runs on the next
+  // session's Stop if it's still in flight; nothing here blocks user work.
+  maybeRefreshReviews();
+
+  const review = getLatestPerformanceReview();
+  if (!review || !review.agentStats || review.agentStats.length === 0) {
+    console.log('📊 No performance review data found. Run `construct review` first.');
+    process.exit(0);
+  }
+  
+  console.log(`📊 Checking ${review.agentStats.length} agents from performance review ${review.generated}`);
+  
+  const agentsNeedingOptimization = review.agentStats.filter(needsOptimization);
+  
+  if (agentsNeedingOptimization.length === 0) {
+    console.log(`✅ All ${review.agentStats.length} agents have scores >= ${OPTIMIZATION_THRESHOLD} or insufficient data`);
+    process.exit(0);
+  }
+  
+  console.log(`🔧 Found ${agentsNeedingOptimization.length} agents needing optimization:`);
+  agentsNeedingOptimization.forEach(agent => {
+    console.log(`  • ${agent.name}: avgScore=${agent.avgScore}, invocations=${agent.invocations}`);
+  });
+  
+  // Run optimization for each agent (serial for now)
+  let optimizedCount = 0;
+  let failedCount = 0;
+  
+  for (const agent of agentsNeedingOptimization) {
+    const success = optimizeAgent(agent.name);
+    if (success) {
+      optimizedCount++;
+    } else {
+      failedCount++;
+    }
+    
+    // Small delay between optimizations to avoid rate limits
+    if (agentsNeedingOptimization.length > 1) {
+      spawnSync('sleep', ['10'], { encoding: 'utf8' });
+    }
+  }
+  
+  // Summary
+  console.log(`\n📈 Optimization Summary:`);
+  console.log(`  • Agents checked: ${review.agentStats.length}`);
+  console.log(`  • Needing optimization: ${agentsNeedingOptimization.length}`);
+  console.log(`  • Successfully optimized: ${optimizedCount}`);
+  console.log(`  • Failed: ${failedCount}`);
+  
+  if (optimizedCount > 0) {
+    console.log(`\n💡 Optimized agents will be evaluated in the next performance review.`);
+    console.log(`   Run \`construct review\` after next session to see improvements.`);
+  }
+  
+  // Log summary to file
+  const summary = {
+    timestamp: new Date().toISOString(),
+    project: projectName,
+    reviewDate: review.generated,
+    agentsChecked: review.agentStats.length,
+    agentsNeedingOptimization: agentsNeedingOptimization.length,
+    optimizedCount,
+    failedCount,
+    agents: agentsNeedingOptimization.map(a => ({
+      name: a.name,
+      avgScore: a.avgScore,
+      invocations: a.invocations,
+      optimized: optimizeAgent.includes ? 'yes' : 'no'
+    }))
+  };
+  
+  const summaryFile = join(OPTIMIZATION_LOG_DIR, `${new Date().toISOString().split('T')[0]}-summary.json`);
+  writeFileSync(summaryFile, JSON.stringify(summary, null, 2) + '\n');
+}
+
+// Run main logic
+try {
+  main();
+} catch (error) {
+  console.error(`❌ Session optimization hook crashed: ${error.message}`);
+  console.error(error.stack);
+  
+  // Log the crash
+  const crashLog = join(OPTIMIZATION_LOG_DIR, 'crashes', `${Date.now()}-crash.json`);
+  mkdirSync(dirname(crashLog), { recursive: true });
+  writeFileSync(crashLog, JSON.stringify({
+    timestamp: new Date().toISOString(),
+    error: error.message,
+    stack: error.stack,
+    cwd,
+    projectName
+  }, null, 2) + '\n');
+  
+  process.exit(1);
+}
+
+process.exit(0);