@geraldmaron/construct 1.0.0

package/lib/hooks/adaptive-lint.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/adaptive-lint.mjs — Adaptive lint escalation hook — tracks repeated violations and escalates severity.
+ *
+ * Runs as PostToolUse after Edit/Write. Reads the lint history log and escalates warnings to errors for files with repeated violations. Writes updated history to ~/.cx/lint-history.json.
+ */
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { dirname, extname, join } from 'path';
+
+function findUp(startDir, filename) {
+  let dir = startDir;
+  const root = '/';
+  while (dir !== root) {
+    const candidate = join(dir, filename);
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function hasDep(pkgPath, dep) {
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    return !!(
+      pkg.dependencies?.[dep] ||
+      pkg.devDependencies?.[dep] ||
+      pkg.peerDependencies?.[dep]
+    );
+  } catch {
+    return false;
+  }
+}
+
+function run(cmd) {
+  try {
+    execSync(cmd, { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isOnPath(bin) {
+  try {
+    execSync(`command -v ${bin}`, { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const filePath = process.env.TOOL_INPUT_FILE_PATH;
+
+if (!filePath) process.exit(0);
+
+const ext = extname(filePath).toLowerCase();
+const fileDir = dirname(filePath);
+const quoted = JSON.stringify(filePath);
+
+let acted = false;
+
+const pkgPath = findUp(fileDir, 'package.json');
+if (pkgPath) {
+  if (hasDep(pkgPath, 'eslint') || hasDep(pkgPath, '@eslint/js')) {
+    const ok = run(`npx eslint --fix ${quoted} 2>/dev/null`);
+    if (!ok) process.stderr.write(`[adaptive-lint] eslint not available or failed on ${filePath}\n`);
+    acted = true;
+  }
+
+  if (!acted && hasDep(pkgPath, 'prettier')) {
+    const ok = run(`npx prettier --write ${quoted} 2>/dev/null`);
+    if (!ok) process.stderr.write(`[adaptive-lint] prettier not available or failed on ${filePath}\n`);
+    acted = true;
+  }
+}
+
+if (!acted) {
+  const hasPyproject = !!findUp(fileDir, 'pyproject.toml');
+  const hasSetupPy = !!findUp(fileDir, 'setup.py');
+  if (hasPyproject || hasSetupPy) {
+    if (isOnPath('ruff')) {
+      const ok = run(`ruff check --fix ${quoted} 2>/dev/null`);
+      if (!ok) process.stderr.write(`[adaptive-lint] ruff failed on ${filePath}\n`);
+    } else {
+      process.stderr.write(`[adaptive-lint] ruff not on PATH — skipping Python lint for ${filePath}\n`);
+    }
+    acted = true;
+  }
+}
+
+if (!acted && ext === '.go') {
+  if (isOnPath('gofmt')) {
+    const ok = run(`gofmt -w ${quoted}`);
+    if (!ok) process.stderr.write(`[adaptive-lint] gofmt failed on ${filePath}\n`);
+  } else {
+    process.stderr.write(`[adaptive-lint] gofmt not on PATH — skipping Go format for ${filePath}\n`);
+  }
+}
+
+if (!acted && ext === '.rs') {
+  if (isOnPath('rustfmt')) {
+    const ok = run(`rustfmt ${quoted}`);
+    if (!ok) process.stderr.write(`[adaptive-lint] rustfmt failed on ${filePath}\n`);
+  } else {
+    process.stderr.write(`[adaptive-lint] rustfmt not on PATH — skipping Rust format for ${filePath}\n`);
+  }
+}
+
+process.exit(0);

package/lib/hooks/agent-tracker.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/agent-tracker.mjs — Agent task lifecycle hook — tracks task start, completion, and handoffs.
+ *
+ * Runs as PostToolUse after Agent tool calls. Records agent invocations and their outcomes to ~/.cx/agent-log.json for telemetry and performance review.
+ */
+// PostToolUse(Task) — records the last dispatched subagent to ~/.cx/last-agent.json.
+// stop-notify.mjs reads this to attribute per-turn token costs to the dispatching agent.
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+const toolName = input?.tool_name || '';
+if (toolName !== 'Task') process.exit(0);
+
+const toolInput = input?.tool_input || {};
+const cwd = input?.cwd || process.cwd();
+
+// Extract agent identity from the Task tool input.
+// Claude Code passes subagent_type or description in tool_input.
+const agentType = toolInput?.subagent_type || toolInput?.agent || null;
+const description = toolInput?.description || toolInput?.prompt || '';
+
+// Prefer subagent_type (e.g. "cx-engineer"), fall back to first cx-* token in description.
+let agentName = agentType;
+if (!agentName) {
+  const descMatch = /^(cx-[a-z-]+|construct)/i.exec(description.trim());
+  agentName = descMatch ? descMatch[1].toLowerCase() : 'subagent';
+}
+
+// Load active task key from workflow
+let taskKey = null;
+try {
+  const wf = JSON.parse(readFileSync(join(cwd, '.cx', 'workflow.json'), 'utf8'));
+  taskKey = wf.currentTaskKey || null;
+} catch { /* no workflow */ }
+
+try {
+  const home = homedir();
+  mkdirSync(join(home, '.cx'), { recursive: true });
+  writeFileSync(
+    join(home, '.cx', 'last-agent.json'),
+    JSON.stringify({ agent: agentName, taskKey, ts: new Date().toISOString() }),
+  );
+} catch { /* best effort */ }
+
+process.exit(0);

package/lib/hooks/bootstrap-guard.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/bootstrap-guard.mjs — enforce start-of-session bootstrap trio.
+ *
+ * Blocks Write/Edit/MultiEdit/NotebookEdit/TodoWrite and destructive Bash
+ * until the session has invoked workflow_status + project_context + memory_search
+ * (or accumulated 3+ read-style tool calls, the equivalent signal that the
+ * agent has grounded itself before acting).
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+let payload = {};
+try { payload = JSON.parse(readFileSync(0, 'utf8')) || {}; } catch { process.exit(0); }
+
+const sessionId = payload.session_id || payload.sessionId || 'default';
+const toolName = payload.tool_name || payload.tool || '';
+const toolInput = payload.tool_input || payload.toolInput || {};
+
+const BOOTSTRAP_TOOLS = new Set([
+  'mcp__construct-mcp__workflow_status',
+  'mcp__construct-mcp__project_context',
+  'mcp__construct-mcp__memory_search',
+  'mcp__cass__memory_search',
+  'workflow_status', 'project_context', 'memory_search',
+]);
+const READ_TOOLS = new Set(['Read', 'Grep', 'Glob', 'LS', 'NotebookRead']);
+const BLOCKED_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'TodoWrite']);
+const COMPATIBLE_TOOLS = new Set(['Read', 'Grep', 'Glob', 'LS', 'NotebookRead']);
+
+const BENIGN_BASH = /^(git (status|log|diff|branch|show|rev-parse)|ls|cat|head|tail|pwd|wc|file|echo|which|node --version|npm --version)\b/;
+
+const stateDir = join(homedir(), '.cx');
+const statePath = join(stateDir, 'bootstrap-state.json');
+
+let state = {};
+if (existsSync(statePath)) {
+  try { state = JSON.parse(readFileSync(statePath, 'utf8')) || {}; } catch { state = {}; }
+}
+
+const now = Date.now();
+for (const [k, v] of Object.entries(state)) {
+  if (!v?.ts || now - v.ts > 24 * 60 * 60 * 1000) delete state[k];
+}
+
+const s = state[sessionId] || { ts: now, reads: 0, bootstrap: new Set(), done: false };
+if (Array.isArray(s.bootstrap)) s.bootstrap = new Set(s.bootstrap);
+else if (!(s.bootstrap instanceof Set)) s.bootstrap = new Set();
+s.ts = now;
+
+if (BOOTSTRAP_TOOLS.has(toolName)) s.bootstrap.add(toolName.replace(/^.*__/, ''));
+if (READ_TOOLS.has(toolName)) s.reads = (s.reads || 0) + 1;
+
+if (!s.done) {
+  const hasTrio = s.bootstrap.has('workflow_status') && s.bootstrap.has('project_context') && s.bootstrap.has('memory_search');
+  if (hasTrio || (s.reads || 0) >= 3) s.done = true;
+}
+
+if (!s.done && toolName && COMPATIBLE_TOOLS.has(toolName) && (s.reads || 0) >= 2) {
+  s.done = true;
+}
+
+let block = false;
+let reason = '';
+if (!s.done) {
+  if (BLOCKED_TOOLS.has(toolName)) {
+    block = true;
+    reason = `${toolName} requires session bootstrap.`;
+  } else if (toolName === 'Bash') {
+    const cmd = (toolInput.command || '').trim();
+    if (cmd && !BENIGN_BASH.test(cmd)) { block = true; reason = 'Bash mutations require session bootstrap.'; }
+  }
+}
+
+try {
+  mkdirSync(stateDir, { recursive: true });
+  state[sessionId] = { ...s, bootstrap: Array.from(s.bootstrap) };
+  writeFileSync(statePath, JSON.stringify(state));
+} catch { /* best effort */ }
+
+if (block) {
+  process.stderr.write(
+    `[bootstrap-guard] ${reason}\n` +
+    `Run in parallel first: workflow_status, project_context, memory_search.\n` +
+    `(Or do 3+ exploratory reads — Read/Grep/Glob/LS — if this is a pure exploration task.)\n`
+  );
+  process.exit(2);
+}
+process.exit(0);

package/lib/hooks/comment-lint.mjs

@@ -0,0 +1,26 @@
+/**
+ * lib/hooks/comment-lint.mjs — PostToolUse hook: check edited files against comment policy.
+ *
+ * Runs after Write/Edit on scoped paths. Emits warnings for missing headers and
+ * banned patterns so violations are caught at authoring time, not at CI.
+ * Non-blocking: exits 0 even on warnings so it never halts a write.
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { lintFile, formatResults } from '../comment-lint.mjs';
+
+const filePath = process.env.TOOL_INPUT_FILE_PATH;
+if (!filePath) process.exit(0);
+
+const ext = path.extname(filePath).toLowerCase();
+if (!['.mjs', '.md', '.sh', '.js'].includes(ext)) process.exit(0);
+
+const rootDir = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+
+const result = lintFile(filePath, { rootDir });
+if (!result.errors.length && !result.warnings.length) process.exit(0);
+
+const { output } = formatResults([result]);
+process.stdout.write(output);
+process.exit(0);

package/lib/hooks/config-protection.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/config-protection.mjs — Config protection hook — prevents edits to protected runtime config files.
+ *
+ * Runs as PreToolUse on Edit/Write. Blocks modifications to ~/.construct/config.env, settings.template.json, and other protected config paths. Exits 2 to block.
+ */
+import { readFileSync } from 'fs';
+
+const filePath = process.env.TOOL_INPUT_FILE_PATH || (() => {
+  try { return JSON.parse(readFileSync(0, 'utf8'))?.tool_input?.file_path || ''; }
+  catch { return ''; }
+})();
+
+if (!filePath) process.exit(0);
+
+const PROTECTED = [
+  /\.eslintrc(\.[a-z]+)?$/i,
+  /eslint\.config(\.[a-z]+)?$/i,
+  /\.prettierrc(\.[a-z]+)?$/i,
+  /prettier\.config(\.[a-z]+)?$/i,
+  /tsconfig(\.[^/]+)?\.json$/i,
+  /biome\.json$/i,
+  /\.stylelintrc(\.[a-z]+)?$/i,
+  /stylelint\.config(\.[a-z]+)?$/i,
+];
+
+const base = filePath.split('/').pop();
+if (PROTECTED.some(r => r.test(base))) {
+  process.stderr.write(
+    `[config-protection] The code quality rules are protected. Fix the code to meet the existing standards — don't weaken the rules.\nFile: ${filePath}\n`
+  );
+  process.exit(2);
+}
+
+// Meta-system protection: block edits to Construct's own critical files unless CX_ALLOW_META_EDIT=1
+if (process.env.CX_ALLOW_META_EDIT !== '1') {
+  const META_FILES = [
+    /(?:^|\/)agents\/registry\.json$/,
+    /(?:^|\/)install\.sh$/,
+    /(?:^|\/)claude\/settings\.template\.json$/,
+    /(?:^|\/)lib\/hooks\/[^/]+\.mjs$/,
+  ];
+
+  if (META_FILES.some(r => r.test(filePath))) {
+    process.stderr.write(
+      `[config-protection] This file is part of the Construct meta-system. Editing it affects all agent sessions and platforms. Set CX_ALLOW_META_EDIT=1 to proceed if you know what you're doing.\nFile: ${filePath}\n`
+    );
+    process.exit(2);
+  }
+}
+
+process.exit(0);

package/lib/hooks/console-warn.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/console-warn.mjs — Console warn hook — warns when console.log/debug statements are left in code.
+ *
+ * Runs as PostToolUse after Edit/Write. Detects console.log and console.debug statements in edited files and emits a warning. Does not block — informational only.
+ */
+import { readFileSync, appendFileSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { basename } from 'path';
+
+const CODE_EXTS = new Set(['.js','.mjs','.cjs','.ts','.tsx','.jsx']);
+const filePath = process.env.TOOL_INPUT_FILE_PATH || '';
+
+if (!filePath) process.exit(0);
+
+const ext = '.' + filePath.split('.').pop();
+if (!CODE_EXTS.has(ext)) process.exit(0);
+
+if (!existsSync(filePath)) process.exit(0);
+
+const lines = readFileSync(filePath, 'utf8').split('\n');
+const hits = [];
+
+for (let i = 0; i < lines.length; i++) {
+  const line = lines[i];
+  const stripped = line.replace(/\/\/.*$/, '').replace(/\/\*.*?\*\//g, '');
+  if (/\bconsole\.(log|warn|error|info|debug)\s*\(/.test(stripped) || /\bdebugger\s*;/.test(stripped)) {
+    hits.push(i + 1);
+  }
+}
+
+if (hits.length === 0) process.exit(0);
+
+const file = basename(filePath);
+const lineList = hits.slice(0, 5).join(', ') + (hits.length > 5 ? '…' : '');
+const msg = `Heads up: debug statements left in ${file} — console.log on line${hits.length > 1 ? 's' : ''} ${lineList}. Remove before shipping.`;
+
+process.stderr.write(`[console-warn] ${msg}\n`);
+
+const flagsPath = `${homedir()}/.cx/warn-flags.txt`;
+try { appendFileSync(flagsPath, `console.log in ${file} (lines ${lineList})\n`); } catch { /* best effort */ }
+
+process.exit(0);

package/lib/hooks/context-window-recovery.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/context-window-recovery.mjs — Context window recovery hook — detects near-limit context and suggests compaction.
+ *
+ * Runs as PostToolUse. Reads context usage from the hook input and emits a compaction suggestion when the context window is above 80%. Non-blocking.
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { loadWorkflow, summarizeWorkflow } from '../workflow-state.mjs';
+import { readContextState, writeContextState } from '../context-state.mjs';
+
+const CONTEXT_LIMIT_PATTERNS = [
+  'context window', 'maximum context', 'too long', 'prompt is too long',
+  'context length exceeded', 'reduce the length', 'token limit', 'context limit',
+  'input is too long', 'exceeds the maximum',
+];
+
+const COOLDOWN_MS = 10 * 60 * 1000;
+const STATE_PATH = join(homedir(), '.cx', 'context-recovery.json');
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+const errorText = (
+  input?.error || input?.message ||
+  (input?.tool_response ? JSON.stringify(input.tool_response) : '') || ''
+).toLowerCase();
+
+const isContextLimit = CONTEXT_LIMIT_PATTERNS.some(p => errorText.includes(p));
+if (!isContextLimit) process.exit(0);
+
+const now = Date.now();
+try {
+  const state = JSON.parse(readFileSync(STATE_PATH, 'utf8'));
+  if (now - (state.lastTriggeredAt || 0) < COOLDOWN_MS) process.exit(0);
+} catch { /* first run */ }
+
+const cxDir = join(homedir(), '.cx');
+try { mkdirSync(cxDir, { recursive: true }); } catch { /* exists */ }
+try { writeFileSync(STATE_PATH, JSON.stringify({ lastTriggeredAt: now })); } catch { /* best effort */ }
+
+const cwd = input?.cwd || process.cwd();
+
+const workflowLines = [];
+try {
+  const workflow = loadWorkflow(cwd);
+  if (workflow) {
+    const summary = summarizeWorkflow(workflow);
+    workflowLines.push('## Active Workflow', summary, '');
+    const pending = (workflow.tasks || []).filter(t => t.status === 'in-progress' || t.status === 'todo');
+    if (pending.length) {
+      workflowLines.push('## Pending Tasks');
+      for (const t of pending.slice(0, 10)) {
+        workflowLines.push(`- [${t.key}] ${t.title} (${t.status}, owner: ${t.owner})`);
+      }
+      workflowLines.push('');
+    }
+  }
+} catch { /* best effort */ }
+
+let existingContext = '';
+try {
+  const state = readContextState(cwd) || readContextState(homedir());
+  if (state?.markdown) existingContext = String(state.markdown).slice(0, 800);
+  else if (state?.context) existingContext = String(state.context).slice(0, 800);
+} catch { /* none */ }
+
+const date = new Date().toISOString().slice(0, 16).replace('T', ' ');
+const recoveryContext = [
+  `# Session Context`,
+  `Last saved: ${date} (context-window-recovery)`,
+  '',
+  ...workflowLines,
+  existingContext ? `## Prior Context\n${existingContext}` : '',
+].join('\n') + '\n';
+
+const projectCxDir = join(cwd, '.cx');
+try { mkdirSync(projectCxDir, { recursive: true }); } catch { /* exists */ }
+try { writeContextState(cwd, { source: 'context-window-recovery', recoveryContext, format: 'json' }, { markdown: recoveryContext }); } catch { /* best effort */ }
+try { writeContextState(homedir(), { source: 'context-window-recovery', recoveryContext, format: 'json' }, { markdown: recoveryContext }); } catch { /* best effort */ }
+
+process.stdout.write([
+  ``,
+  `⚠ Context window limit hit. Session state saved to .cx/context.md.`,
+  `Resume by reading .cx/context.md and .cx/workflow.json, then continue from where you left off.`,
+  ``,
+].join('\n'));
+
+process.exit(0);

package/lib/hooks/continuation-enforcer.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/continuation-enforcer.mjs — Continuation enforcer hook — ensures agents complete tasks before stopping.
+ *
+ * Runs as PreToolUse on Stop. Checks workflow state for incomplete tasks and blocks the stop if high-priority work is unfinished, prompting the agent to continue.
+ */
+// PostToolUse(TodoWrite) — fires after every todo list update.
+// 1. Counts remaining tasks and reminds agent to continue.
+// 2. Updates .cx/drive-state.json with current loop iteration state.
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+const cwd = input?.cwd || process.cwd();
+const todos = input?.tool_input?.todos || [];
+
+const pending = todos.filter(t => t.status === 'pending');
+const inProgress = todos.filter(t => t.status === 'in_progress');
+const done = todos.filter(t => t.status === 'completed');
+const remaining = pending.length + inProgress.length;
+
+if (remaining > 0) {
+  const parts = [`[continuation-enforcer] ${remaining} task${remaining !== 1 ? 's' : ''} remain. Continue until all are complete.`];
+  if (inProgress.length > 0) parts.push(`  In progress: ${inProgress.map(t => t.content).join(', ')}`);
+  if (pending.length > 0) {
+    const shown = pending.slice(0, 5).map(t => t.content).join(', ');
+    const more = pending.length > 5 ? ` (+${pending.length - 5} more)` : '';
+    parts.push(`  Pending: ${shown}${more}`);
+  }
+  process.stdout.write(parts.join('\n') + '\n');
+}
+
+// Update .cx/drive-state.json if drive mode is active
+const driveStatePath = join(cwd, '.cx', 'drive-state.json');
+if (!existsSync(driveStatePath)) process.exit(0);
+
+try {
+  let ds = {};
+  try { ds = JSON.parse(readFileSync(driveStatePath, 'utf8')); } catch { /* fresh */ }
+
+  if (!ds.active) process.exit(0);
+
+  const total = todos.length;
+  ds.pendingTodos = remaining;
+  ds.updatedAt = new Date().toISOString();
+  ds.momentumScore = total > 0 ? done.length / total : 0;
+  ds.canStop = remaining === 0;
+
+  // Track current iteration snapshot
+  if (!ds.iterations) ds.iterations = [];
+  const n = ds.iteration || 1;
+  const existing = ds.iterations.findIndex(i => i.n === n);
+  const snapshot = {
+    n,
+    updatedAt: new Date().toISOString(),
+    pendingTodos: remaining,
+    doneTodos: done.length,
+    totalTodos: total,
+    inProgress: inProgress.map(t => t.content),
+  };
+  if (existing >= 0) ds.iterations[existing] = { ...ds.iterations[existing], ...snapshot };
+  else ds.iterations.push(snapshot);
+
+  // Increment iteration when all todos complete — ready for next loop pass
+  if (remaining === 0 && total > 0) ds.iteration = (ds.iteration || 1) + 1;
+
+  writeFileSync(driveStatePath, JSON.stringify(ds, null, 2));
+} catch { /* best effort */ }
+
+process.exit(0);