chati-dev 4.2.1 → 4.3.0

package/framework/hooks/license-guard.js

@@ -3,229 +3,159 @@
  * License Guard Hook — UserPromptSubmit
  *
  * Validates license status before each user prompt turn.
- * Uses a 24h cache stored in ~/.chati-dev/license.yaml (global, all projects).
+ * Once activated, the license is trusted until explicitly revoked by the API.
  *
  * Behavior:
- * - No key configured  → allow (orchestrator handles inline activation)
- * - Cache VALID < 24h  → allow silently + session ping (once/day/project)
- * - Cache EXPIRED/INVALID < 24h → block with renewal message
- * - Cache stale (> 24h) → call API, refresh cache, then allow or block
- * - API unreachable    → fail open (allow), never block work
+ * - No license file        → block with activation instructions
+ * - Cache VALID            → allow silently (always trust cached VALID status)
+ * - Cache EXPIRED/INVALID  → block with renewal message
+ * - Cache stale (> 24h) + API reachable → refresh cache in background
+ * - API unreachable        → use cached status (no blocking on network issues)
+ *
+ * Rationale: users activate once at install time. After that, the hook should
+ * never block due to cache expiry or network issues. Only explicit server-side
+ * revocation (EXPIRED/INVALID status returned by API) blocks the user.
+ *
+ * Telemetry pings are owned by session-digest.js (PreCompact event), not here.
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
-import { join, basename } from 'path';
+import { join } from 'path';
 import { homedir } from 'os';
 
 const API_BASE = 'https://chati.dev/api';
-const TELEMETRY_ENDPOINT = 'https://chati.dev/api/telemetry';
-const CACHE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours — shorter window to catch expirations faster
-const PING_THROTTLE_MS = 5 * 60 * 1000; // 5 minutes
+const CACHE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
 
 const GLOBAL_DIR = join(homedir(), '.chati-dev');
 const LICENSE_PATH = join(GLOBAL_DIR, 'license.yaml');
-const PINGS_PATH = join(GLOBAL_DIR, 'pings.yaml');
-
-async function main() {
-  let input = '';
-  for await (const chunk of process.stdin) input += chunk;
-
-  try {
-    // Read global license file — REQUIRED for operation
-    if (!existsSync(LICENSE_PATH)) {
-      block('No license found. Run: npx chati-dev activate --key=YOUR-KEY\nGet a license at https://chati.dev/pricing');
-      return;
-    }
-
-    const licenseRaw = readFileSync(LICENSE_PATH, 'utf-8');
-    const licenseKey = readYamlField(licenseRaw, 'key');
-
-    if (!licenseKey || licenseKey === 'null') {
-      block('No license key configured. Run: npx chati-dev activate --key=YOUR-KEY\nGet a license at https://chati.dev/pricing');
-      return;
-    }
 
-    // Check cache validity
-    const status = readYamlField(licenseRaw, 'status');
-    const checkedAt = readYamlField(licenseRaw, 'checked_at');
-    const age = checkedAt ? Date.now() - new Date(checkedAt).getTime() : Infinity;
-
-    if (age < CACHE_TTL_MS) {
-      if (status === 'VALID') {
-        await allowWithPing(licenseKey);
-        return;
-      }
-      if (status === 'EXPIRED' || status === 'INVALID') {
-        block(buildMessage(status, readYamlField(licenseRaw, 'reason')));
-        return;
-      }
-    }
-
-    // Cache stale — call API
-    try {
-      const machineId = await computeMachineId();
-      const res = await fetch(
-        `${API_BASE}/license/validate?key=${encodeURIComponent(licenseKey)}&machine_id=${encodeURIComponent(machineId)}`,
-        { signal: AbortSignal.timeout(5000) }
-      );
-      const data = await res.json();
+/**
+ * Pure license validation function — provider-agnostic.
+ * Returns a verdict object that hook wrappers can translate to their
+ * provider's blocking schema (Claude UserPromptSubmit, Gemini BeforeModel,
+ * Codex UserPromptSubmit).
+ *
+ * @returns {Promise<{valid: boolean, reason?: string, status?: string}>}
+ */
+export async function checkLicense() {
+  // Read global license file — REQUIRED for operation
+  if (!existsSync(LICENSE_PATH)) {
+    return { valid: false, reason: 'No license found. Run: npx chati-dev activate --key=YOUR-KEY\nGet a license at https://chati.dev/pricing', status: 'MISSING' };
+  }
 
-      // Persist updated status (keep existing key)
-      const existing = parseYaml(licenseRaw);
-      const updated = {
-        ...existing,
-        status: data.status,
-        plan: data.plan ?? '',
-        days_remaining: data.days_remaining ?? '',
-        expires_at: data.expires_at ?? '',
-        reason: data.reason ?? '',
-        checked_at: new Date().toISOString(),
-      };
-      mkdirSync(GLOBAL_DIR, { recursive: true });
-      writeFileSync(LICENSE_PATH, dumpYaml(updated));
+  const licenseRaw = readFileSync(LICENSE_PATH, 'utf-8');
+  const licenseKey = readYamlField(licenseRaw, 'key');
 
-      if (data.status === 'VALID') {
-        await allowWithPing(licenseKey);
-        return;
-      }
-      block(buildMessage(data.status, data.reason));
-    } catch {
-      // API unreachable — check if we have a recent VALID cache to fall back on
-      // If cache is less than 24h old AND was VALID, allow (grace period for network issues)
-      // Otherwise block — we cannot verify the license
-      if (age < 24 * 60 * 60 * 1000 && status === 'VALID') {
-        allow(); // grace: last check was recent and valid, allow despite network issue
-      } else {
-        block('Unable to verify license (network issue). If this persists, check your connection.\nRun: npx chati-dev activate --key=YOUR-KEY');
-      }
-    }
-  } catch { /* expected: stdin parse may fail — fail open */
-    allow();
+  if (!licenseKey || licenseKey === 'null') {
+    return { valid: false, reason: 'No license key configured. Run: npx chati-dev activate --key=YOUR-KEY\nGet a license at https://chati.dev/pricing', status: 'MISSING' };
   }
-}
 
-// ---------------------------------------------------------------------------
-// Session Ping (5-min throttle with phase-change detection)
-// ---------------------------------------------------------------------------
+  const status = readYamlField(licenseRaw, 'status');
+  const checkedAt = readYamlField(licenseRaw, 'checked_at');
+  const age = checkedAt ? Date.now() - new Date(checkedAt).getTime() : Infinity;
 
-async function allowWithPing(licenseKey) {
-  const projectPath = process.cwd();
-  const projectName = basename(projectPath) || 'unknown';
-  const session = readSessionContext();
+  // EXPLICIT REVOCATION — block immediately
+  // Server explicitly said this license is no longer valid.
+  if (status === 'EXPIRED' || status === 'INVALID' || status === 'REVOKED') {
+    return { valid: false, reason: buildMessage(status, readYamlField(licenseRaw, 'reason')), status };
+  }
 
-  if (shouldPing(projectPath, session)) {
-    recordPing(projectPath, session); // sync — prevents duplicate pings even if fetch fails
-    const pingPromise = sendSessionPing(licenseKey, projectName, session);
-    allow();
-    await pingPromise; // keep process alive until ping completes (max 3s)
-  } else {
-    allow();
+  // Fresh cache (< CACHE_TTL_MS) — trust without API call
+  if (status === 'VALID' && age < CACHE_TTL_MS) {
+    return { valid: true, status: 'VALID' };
   }
-}
 
-/**
- * Reads .chati/session.yaml from cwd to extract pipeline phase, agent, and project type.
- * Returns {} on any error (fail silently — this is optional enrichment).
- */
-function readSessionContext() {
+  // Stale cache — try background refresh.
+  // CRITICAL: cached VALID is trusted indefinitely. API call only updates the
+  // cache or detects revocation. Network failures NEVER block the user.
   try {
-    const sessionPath = join(process.cwd(), '.chati', 'session.yaml');
-    if (!existsSync(sessionPath)) return {};
-    const raw = readFileSync(sessionPath, 'utf-8');
-
-    // project.state → pipeline_phase
-    const stateMatch = raw.match(/^\s+state:\s*(.+)$/m);
-    const pipeline_phase = stateMatch ? stateMatch[1].trim().replace(/^["']|["']$/g, '') : null;
-
-    // current_agent (top-level)
-    const agentMatch = raw.match(/^current_agent:\s*(.+)$/m);
-    const current_agent = agentMatch ? agentMatch[1].trim().replace(/^["']|["']$/g, '') : null;
-
-    // project.type → project_type
-    const typeMatch = raw.match(/^\s+type:\s*(.+)$/m);
-    const project_type = typeMatch ? typeMatch[1].trim().replace(/^["']|["']$/g, '') : null;
-
-    return { pipeline_phase, current_agent, project_type };
-  } catch { return {}; }
+    const machineId = await computeMachineId();
+    const res = await fetch(
+      `${API_BASE}/license/validate?key=${encodeURIComponent(licenseKey)}&machine_id=${encodeURIComponent(machineId)}`,
+      { signal: AbortSignal.timeout(5000) }
+    );
+    const data = await res.json();
+
+    // Persist updated status (keep existing key)
+    const existing = parseYaml(licenseRaw);
+    const updated = {
+      ...existing,
+      status: data.status,
+      plan: data.plan ?? '',
+      days_remaining: data.days_remaining ?? '',
+      expires_at: data.expires_at ?? '',
+      reason: data.reason ?? '',
+      checked_at: new Date().toISOString(),
+    };
+    mkdirSync(GLOBAL_DIR, { recursive: true });
+    writeFileSync(LICENSE_PATH, dumpYaml(updated));
+
+    if (data.status === 'VALID') return { valid: true, status: 'VALID' };
+    return { valid: false, reason: buildMessage(data.status, data.reason), status: data.status };
+  } catch {
+    // API unreachable — trust the last known status indefinitely.
+    // The user activated once; we never block due to network issues.
+    if (status === 'VALID') {
+      return { valid: true, status: 'VALID', graced: true };
+    }
+    // Status is unknown/null and API is unreachable — only now we ask user to retry.
+    return { valid: false, reason: 'License status unknown and unable to reach validation server. Try again when online.\nRun: npx chati-dev activate --key=YOUR-KEY', status: 'NETWORK_ERROR' };
+  }
 }
 
-/**
- * Pings.yaml format: '/path/to/project': '2026-03-22T21:00:00.000Z|discover|greenfield-wu'
- * Ping if: (1) no entry, (2) >5 min ago, OR (3) phase/agent changed
- */
-function shouldPing(projectPath, session = {}) {
-  try {
-    if (!existsSync(PINGS_PATH)) return true;
-    const content = readFileSync(PINGS_PATH, 'utf-8');
-    const escaped = projectPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const match = content.match(new RegExp(`^${escaped}:\\s*'?([^'\\n]+)'?$`, 'm'));
-    if (!match) return true;
-
-    const [timestamp, lastPhase, lastAgent] = match[1].trim().split('|');
-    const age = Date.now() - new Date(timestamp).getTime();
-    if (age > PING_THROTTLE_MS) return true;
+async function main() {
+  let input = '';
+  for await (const chunk of process.stdin) input += chunk;
 
-    // Phase or agent changed → ping immediately
-    if (session.pipeline_phase && session.pipeline_phase !== lastPhase) return true;
-    if (session.current_agent && session.current_agent !== lastAgent) return true;
+  // Detect hook event from stdin to output the correct schema.
+  // PreToolUse needs hookSpecificOutput.permissionDecision.
+  // UserPromptSubmit needs exit 2 + stderr (silent block).
+  let event = null;
+  try {
+    const parsed = JSON.parse(input);
+    event = parsed.hook_event_name || null;
+  } catch { /* expected: may not be JSON */ }
 
-    return false;
-  } catch { return false; } // fail closed — don't add latency on parse error
-}
+  const isPreToolUse = event === 'PreToolUse';
 
-function recordPing(projectPath, session = {}) {
   try {
-    mkdirSync(GLOBAL_DIR, { recursive: true });
-    const timestamp = new Date().toISOString();
-    const phase = session.pipeline_phase ?? '';
-    const agent = session.current_agent ?? '';
-    const value = `${timestamp}|${phase}|${agent}`;
-
-    let content = existsSync(PINGS_PATH) ? readFileSync(PINGS_PATH, 'utf-8') : '';
-    const escaped = projectPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    if (new RegExp(`^${escaped}:`, 'm').test(content)) {
-      content = content.replace(new RegExp(`^(${escaped}:).*$`, 'm'), `$1 '${value}'`);
+    const result = await checkLicense();
+    if (result.valid) {
+      process.stdout.write(isPreToolUse
+        ? JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow' } })
+        : '{}');
     } else {
-      content += `${projectPath}: '${value}'\n`;
+      if (isPreToolUse) {
+        process.stdout.write(JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: result.reason,
+          },
+        }));
+      } else {
+        process.stderr.write(result.reason);
+        process.exit(2);
+      }
     }
-    writeFileSync(PINGS_PATH, content);
-  } catch {} // fail silently
-}
-
-async function sendSessionPing(licenseKey, projectName, session = {}) {
-  try {
-    const properties = {};
-    if (session.pipeline_phase) properties.pipeline_phase = session.pipeline_phase;
-    if (session.current_agent) properties.current_agent = session.current_agent;
-    if (session.project_type) properties.project_type = session.project_type;
-
-    await fetch(TELEMETRY_ENDPOINT, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        license_key: licenseKey,
-        project_name: projectName,
-        events: [{
-          type: 'session_active',
-          timestamp: new Date().toISOString(),
-          properties,
-        }],
-      }),
-      signal: AbortSignal.timeout(3000),
-    });
-  } catch {} // fire-and-forget, always fail silently
+  } catch { /* fail open */
+    process.stdout.write(isPreToolUse
+      ? JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow' } })
+      : '{}');
+  }
 }
 
 // ---------------------------------------------------------------------------
-// Decision helpers
+// Decision helpers (used only for non-hook Bash invocations via checkLicense)
 // ---------------------------------------------------------------------------
 
-function allow() {
-  process.stdout.write(JSON.stringify({ decision: 'allow' }));
-}
-
 function block(reason) {
-  process.stdout.write(JSON.stringify({ decision: 'block', reason }));
+  // v4.2.2 → v4.2.3 hotfix test: try exit code 2 + stderr instead of
+  // {decision:block} JSON. The JSON form was silently consumed as context
+  // injection in production. Per docs (variant 2), exit 2 + stderr is the
+  // canonical UserPromptSubmit block mechanism.
+  process.stderr.write(reason);
+  process.exit(2);
 }
 
 function buildMessage(status, reason) {
@@ -274,7 +204,16 @@ async function computeMachineId() {
   return createHash('sha256').update(raw).digest('hex').substring(0, 16);
 }
 
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }

package/framework/hooks/mode-governance.js

@@ -15,8 +15,8 @@ import { join, relative, isAbsolute } from 'path';
 
 const MODE_SCOPES = {
   planning: {
-    allowed: ['chati.dev/', '.chati/', 'chati.dev/artifacts/'],
-    description: 'Planning mode: write only to chati.dev/ and .chati/',
+    allowed: ['chati.dev/', '.chati.dev/', '.chati/', 'artifacts/', 'CLAUDE.local.md', 'CLAUDE.md', '.claude/'],
+    description: 'Planning mode: write only to framework dir, .chati/, artifacts/, and Claude config files',
   },
   build: {
     allowed: ['*'],
@@ -41,12 +41,25 @@ const STATE_TO_GOVERNANCE_MODE = {
 
 function getCurrentMode(projectDir) {
   const sessionPath = join(projectDir, '.chati', 'session.yaml');
-  if (!existsSync(sessionPath)) return 'planning'; // Default to most restrictive
+  // No session = no enforcement yet (orchestrator will set mode on first run).
+  // Defaulting to planning here would deadlock fresh installs (planning blocks
+  // session.yaml writes, so the orchestrator could never bootstrap).
+  if (!existsSync(sessionPath)) return 'build';
 
   const raw = readFileSync(sessionPath, 'utf-8');
-  const match = raw.match(/^\s*mode:\s*(.+)$/m);
-  const state = match ? match[1].trim().replace(/^["']|["']$/g, '') : 'discover';
-  return STATE_TO_GOVERNANCE_MODE[state] || 'planning';
+  // Prefer explicit mode field; fall back to project.state mapping.
+  const modeMatch = raw.match(/^\s*mode:\s*(.+)$/m);
+  if (modeMatch) {
+    const mode = modeMatch[1].trim().replace(/^["']|["']$/g, '');
+    if (MODE_SCOPES[mode]) return mode;
+  }
+  const stateMatch = raw.match(/^\s+state:\s*(.+)$/m);
+  if (stateMatch) {
+    const state = stateMatch[1].trim().replace(/^["']|["']$/g, '');
+    return STATE_TO_GOVERNANCE_MODE[state] || 'build';
+  }
+  // Session exists but no mode/state field — be permissive.
+  return 'build';
 }
 
 function isPathAllowed(filePath, projectDir, mode) {
@@ -74,31 +87,70 @@ async function main() {
     const filePath = toolInput.file_path || toolInput.path || '';
 
     if (!filePath) {
-      process.stdout.write(JSON.stringify({ decision: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
+      return;
+    }
+
+    // Block direct edits to session.yaml — it must be managed by CLI only.
+    // CLI uses fs.writeFileSync (not intercepted by hooks), so this only blocks
+    // Claude's Edit/Write tool calls, which is exactly what we want.
+    const rel = isAbsolute(filePath) ? relative(projectDir, filePath) : filePath;
+    if (rel === join('.chati', 'session.yaml') || rel === '.chati/session.yaml') {
+      process.stdout.write(JSON.stringify(denyOutput(
+        '[Article XV] session.yaml is managed by the CLI. Use the router: node chati.dev/orchestrator/chati-router.js advance --agent {name} --score {score}'
+      )));
       return;
     }
 
     const mode = getCurrentMode(projectDir);
 
     if (isPathAllowed(filePath, projectDir, mode)) {
-      process.stdout.write(JSON.stringify({ decision: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
     } else {
       const scope = MODE_SCOPES[mode];
-      process.stdout.write(JSON.stringify({
-        decision: 'block',
-        reason: `[Article XI] ${scope.description}. Cannot write to "${filePath}" in ${mode} mode.`,
-      }));
+      process.stdout.write(JSON.stringify(denyOutput(
+        `[Article XI] ${scope.description}. Cannot write to "${filePath}" in ${mode} mode.`
+      )));
     }
   } catch (err) {
     process.stderr.write(`[chati-hook-error] mode-governance: ${err?.message || 'unknown'}\n`);
-    process.stdout.write(JSON.stringify({ decision: 'block', reason: 'Hook error — fail-closed for safety' }));
+    // Hook errors are fail-OPEN: a broken hook should not block the user.
+    // Security-critical denials are handled by explicit logic above.
+    process.stdout.write(JSON.stringify(allowOutput()));
   }
 }
 
+function allowOutput() {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+    },
+  };
+}
+
+function denyOutput(reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
 export { getCurrentMode, isPathAllowed, MODE_SCOPES, STATE_TO_GOVERNANCE_MODE };
 
-// Only run main when executed directly (not imported by tests)
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }

package/framework/hooks/model-governance.js

@@ -38,6 +38,7 @@ const AGENT_MODELS = {
   tasks: { provider: 'claude', model: 'sonnet', tier: 'sonnet' },
   'qa-planning': { provider: 'claude', model: 'opus', tier: 'opus' },
   'qa-implementation': { provider: 'claude', model: 'opus', tier: 'opus' },
+  'qa-visual': { provider: 'claude', model: 'opus', tier: 'opus' },
   dev: { provider: 'claude', model: 'opus', tier: 'opus' },
   devops: { provider: 'claude', model: 'sonnet', tier: 'sonnet' },
 };
@@ -80,24 +81,34 @@ async function main() {
       const assignment = AGENT_MODELS[agent];
       const expected = assignment.model || assignment;
       const provider = assignment.provider || 'claude';
-      // Advisory note — appended to context
+      // Advisory context injection via canonical UserPromptSubmit schema.
       process.stdout.write(JSON.stringify({
-        result: 'allow',
-        prefix: `<!-- [Article XVI] Agent "${agent}" assigned model: ${expected} (provider: ${provider}) -->`,
+        hookSpecificOutput: {
+          hookEventName: 'UserPromptSubmit',
+          additionalContext: `[Article XVI] Agent "${agent}" assigned model: ${expected} (provider: ${provider})`,
+        },
       }));
     } else {
-      process.stdout.write(JSON.stringify({ result: 'allow' }));
+      process.stdout.write('{}');
     }
   } catch (err) {
     process.stderr.write(`[chati] model-governance: ${err.message}\n`);
-    process.stdout.write(JSON.stringify({ result: 'allow' }));
+    process.stdout.write('{}');
   }
 }
 
 export { AGENT_MODELS, UPGRADE_CONDITIONS, getCurrentAgent };
 
-// Only run main when executed directly (not imported by tests)
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }

package/framework/hooks/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}