chati-dev 4.2.2 → 4.3.0

package/src/orchestrator/doctor.js

@@ -0,0 +1,270 @@
+/**
+ * @fileoverview /chati doctor — silent boot-time self-diagnostic.
+ *
+ * Runs a battery of fast (< 200ms) filesystem + version checks every time
+ * /chati boots. Pass-silent, fail-loud: the intent is that the user never
+ * sees doctor output when everything is fine; they see a specific,
+ * actionable message ONLY when something is off.
+ *
+ * Six checks, two severities:
+ *
+ *   id         severity  description
+ *   ---------  --------  -----------
+ *   license    BLOCK     ~/.chati-dev/license.yaml status != VALID (fail-open if missing)
+ *   scaffold   BLOCK     projectDir/.chati.dev/ directory exists
+ *   session    BLOCK     .chati/session.yaml parses cleanly (or is absent)
+ *   hooks      WARN      .claude/settings.json has expected hook registrations
+ *   model      WARN      session.active_model is populated (hook fills on first fire)
+ *   node       BLOCK     process version >= 22
+ *
+ * BLOCK failures short-circuit boot with a fix instruction. WARN failures
+ * surface as non-blocking notices.
+ *
+ * Each check is a PURE FUNCTION on (options) — takes everything it needs
+ * as args (no global state). runDoctor composes them and aggregates the
+ * verdict.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { readLicenseStatus } from '../license/wait.js';
+
+export const SEVERITY = Object.freeze({
+  BLOCK: 'BLOCK',
+  WARN:  'WARN',
+});
+
+/**
+ * @typedef {object} CheckResult
+ * @property {string} id
+ * @property {'BLOCK'|'WARN'} severity
+ * @property {'pass'|'fail'} status
+ * @property {string} message
+ * @property {string} [fix]          Suggested fix when status=fail.
+ */
+
+// ---------------------------------------------------------------------------
+// Individual checks — pure functions.
+// ---------------------------------------------------------------------------
+
+/**
+ * License status. Fail-open: missing file = pass (matches license-guard.js).
+ * @param {{ home?: string }} opts
+ * @returns {CheckResult}
+ */
+export function checkLicense({ home = process.env.HOME || '' } = {}) {
+  // F-A5-003: delegate to the canonical reader in license/wait.js so the
+  // doctor and the runtime-block path share a single source of truth. If
+  // the YAML shape changes, both fail/pass the same way.
+  const result = readLicenseStatus(home);
+  if (!result.present) {
+    return { id: 'license', severity: SEVERITY.BLOCK, status: 'pass', message: 'No license file (demo mode allowed — fail-open).' };
+  }
+  if (result.error) {
+    return {
+      id:       'license',
+      severity: SEVERITY.BLOCK,
+      status:   'fail',
+      message:  `Cannot read license file: ${result.error}`,
+      fix:      'Restore ~/.chati-dev/license.yaml or run: npx chati-dev activate --key=YOUR-KEY',
+    };
+  }
+  const status = result.status || 'UNKNOWN';
+  if (status === 'VALID') {
+    return { id: 'license', severity: SEVERITY.BLOCK, status: 'pass', message: 'License: VALID.' };
+  }
+  return {
+    id:       'license',
+    severity: SEVERITY.BLOCK,
+    status:   'fail',
+    message:  `License status: ${status}`,
+    fix:      'Paste in another terminal: npx chati-dev activate --key=YOUR-KEY',
+  };
+}
+
+/**
+ * Scaffold presence in the project. Required — without it, hooks and
+ * agent files are unreachable.
+ * @param {{ projectDir: string }} opts
+ * @returns {CheckResult}
+ */
+export function checkScaffold({ projectDir }) {
+  const scaffoldDir = join(projectDir, '.chati.dev');
+  if (existsSync(scaffoldDir)) {
+    return { id: 'scaffold', severity: SEVERITY.BLOCK, status: 'pass', message: '.chati.dev/ scaffold present.' };
+  }
+  return {
+    id:       'scaffold',
+    severity: SEVERITY.BLOCK,
+    status:   'fail',
+    message:  '.chati.dev/ scaffold directory not found in project root.',
+    fix:      'Run: npx chati-dev init (from the project root)',
+  };
+}
+
+/**
+ * Session file integrity. Absence is fine (pre-init state). Presence
+ * with parse error is a BLOCK — we cannot route agent messages.
+ * @param {{ projectDir: string }} opts
+ * @returns {CheckResult}
+ */
+export function checkSession({ projectDir }) {
+  const sessionPath = join(projectDir, '.chati', 'session.yaml');
+  if (!existsSync(sessionPath)) {
+    return {
+      id: 'session', severity: SEVERITY.BLOCK, status: 'pass',
+      message: 'Session not yet initialized (pre-init or fresh project).',
+    };
+  }
+  try {
+    const raw = readFileSync(sessionPath, 'utf-8');
+    // Minimal integrity: must contain at least one YAML-ish `key:` line and
+    // no obviously malformed constructs.
+    const hasKey = /^\s*\w+:/m.test(raw);
+    const hasBadStructure = /\[\s*\w+:\s*/.test(raw); // `[key:` is not valid YAML shorthand
+    if (!hasKey || hasBadStructure) {
+      return {
+        id:       'session',
+        severity: SEVERITY.BLOCK,
+        status:   'fail',
+        message:  'session.yaml is present but appears corrupted.',
+        fix:      'Inspect .chati/session.yaml manually, or re-run: npx chati-dev init',
+      };
+    }
+    return { id: 'session', severity: SEVERITY.BLOCK, status: 'pass', message: 'session.yaml parses cleanly.' };
+  } catch (err) {
+    return {
+      id:       'session',
+      severity: SEVERITY.BLOCK,
+      status:   'fail',
+      message:  `Cannot read session.yaml: ${err.message}`,
+      fix:      'Check filesystem permissions on .chati/session.yaml',
+    };
+  }
+}
+
+/**
+ * Hook drift detection. Looks for a representative sample of expected
+ * hooks in .claude/settings.json. Missing = WARN (hook system is
+ * advisory; system still works).
+ * @param {{ projectDir: string }} opts
+ * @returns {CheckResult}
+ */
+export function checkHooks({ projectDir }) {
+  const settingsPath = join(projectDir, '.claude', 'settings.json');
+  if (!existsSync(settingsPath)) {
+    return {
+      id: 'hooks', severity: SEVERITY.WARN, status: 'pass',
+      message: '.claude/settings.json not found — skipping hook drift check.',
+    };
+  }
+  try {
+    const raw = readFileSync(settingsPath, 'utf-8');
+    const settings = JSON.parse(raw);
+    const hookConfigs = settings && settings.hooks ? settings.hooks : {};
+    const expected = ['prism-engine.js', 'license-guard.js'];
+    const flat = JSON.stringify(hookConfigs);
+    const missing = expected.filter(h => !flat.includes(h));
+    if (missing.length === 0) {
+      return { id: 'hooks', severity: SEVERITY.WARN, status: 'pass', message: 'Expected hooks registered.' };
+    }
+    return {
+      id:       'hooks',
+      severity: SEVERITY.WARN,
+      status:   'fail',
+      message:  `Missing hook registrations: ${missing.join(', ')}`,
+      fix:      'Re-run installer to refresh .claude/settings.json: npx chati-dev init (is idempotent)',
+    };
+  } catch (err) {
+    return {
+      id:       'hooks',
+      severity: SEVERITY.WARN,
+      status:   'fail',
+      message:  `Cannot parse .claude/settings.json: ${err.message}`,
+    };
+  }
+}
+
+/**
+ * Active model detection. Populated by /chati boot or by prism-engine
+ * on first fire. Absent = WARN — context bracket will still compute via
+ * provider default, just less precise.
+ * @param {{ projectDir: string }} opts
+ * @returns {CheckResult}
+ */
+export function checkModel({ projectDir }) {
+  const sessionPath = join(projectDir, '.chati', 'session.yaml');
+  if (!existsSync(sessionPath)) {
+    return {
+      id: 'model', severity: SEVERITY.WARN, status: 'pass',
+      message: 'Session not yet initialized — model detection deferred.',
+    };
+  }
+  try {
+    const raw = readFileSync(sessionPath, 'utf-8');
+    const match = raw.match(/^\s*active_model:\s*(.+)$/m);
+    const value = match ? match[1].trim().replace(/^["']|["']$/g, '') : '';
+    if (!value || value === 'null' || value === '~' || value === '') {
+      return {
+        id:       'model',
+        severity: SEVERITY.WARN,
+        status:   'fail',
+        message:  'active_model not set — hook will populate on next prompt.',
+      };
+    }
+    return { id: 'model', severity: SEVERITY.WARN, status: 'pass', message: `active_model: ${value}` };
+  } catch {
+    return {
+      id: 'model', severity: SEVERITY.WARN, status: 'pass',
+      message: 'Cannot read active_model; deferring to hook.',
+    };
+  }
+}
+
+/**
+ * Node version gate. Framework assumes Node 22+ for modern ESM, fetch,
+ * globbing. Earlier versions break test runs and hook spawns.
+ * @param {{ versionString?: string }} opts
+ * @returns {CheckResult}
+ */
+export function checkNode({ versionString = process.version } = {}) {
+  const match = versionString.match(/^v?(\d+)/);
+  const major = match ? parseInt(match[1], 10) : 0;
+  if (major >= 22) {
+    return { id: 'node', severity: SEVERITY.BLOCK, status: 'pass', message: `Node ${versionString} OK.` };
+  }
+  return {
+    id:       'node',
+    severity: SEVERITY.BLOCK,
+    status:   'fail',
+    message:  `Node ${versionString} is below the required v22.`,
+    fix:      'Install Node 22+: https://nodejs.org/en/download',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// runDoctor — aggregate all six checks.
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{ projectDir: string, home?: string }} opts
+ * @returns {{
+ *   ok:       boolean,
+ *   checks:   CheckResult[],
+ *   blockers: CheckResult[],
+ *   warnings: CheckResult[]
+ * }}
+ */
+export function runDoctor(opts) {
+  const checks = [
+    checkLicense({ home: opts.home }),
+    checkScaffold({ projectDir: opts.projectDir }),
+    checkSession({ projectDir: opts.projectDir }),
+    checkHooks({ projectDir: opts.projectDir }),
+    checkModel({ projectDir: opts.projectDir }),
+    checkNode(),
+  ];
+  const blockers = checks.filter(c => c.status === 'fail' && c.severity === SEVERITY.BLOCK);
+  const warnings = checks.filter(c => c.status === 'fail' && c.severity === SEVERITY.WARN);
+  return { ok: blockers.length === 0, checks, blockers, warnings };
+}

package/src/orchestrator/handoff-engine.js

@@ -12,6 +12,7 @@ import { updateClaudeMd } from '../memory/magic-docs.js';
 import { generateContextFiles } from '../config/context-file-generator.js';
 import { existsSync, readdirSync } from 'fs';
 import { join } from 'path';
+import { resolveFrameworkDir } from '../utils/framework-dir.js';
 
 /**
  * Execute a full agent-to-agent handoff.
@@ -151,11 +152,11 @@ export function validateHandoffPreconditions(params, projectDir = '.') {
   // Deterministic artifact checks for UX agent handoffs
   const agent = params.fromTask?.agent || params.fromTask?.id?.split('-')[0] || '';
   if (agent === 'ux') {
-    const brandbookPath = join(projectDir, 'chati.dev', 'artifacts', '4-UX', 'brandbook.html');
+    const brandbookPath = join(projectDir, resolveFrameworkDir(projectDir), 'artifacts', '4-UX', 'brandbook.html');
     if (!existsSync(brandbookPath)) {
       issues.push('brandbook.html is missing — UX handoff requires the visual brandbook file on disk');
     }
-    const discoveryLogPath = join(projectDir, 'chati.dev', 'artifacts', '4-UX', 'component-discovery-log.md');
+    const discoveryLogPath = join(projectDir, resolveFrameworkDir(projectDir), 'artifacts', '4-UX', 'component-discovery-log.md');
     if (!existsSync(discoveryLogPath)) {
       issues.push('component-discovery-log.md is missing — UX handoff requires component discovery documentation');
     }
@@ -225,7 +226,7 @@ export function loadHandoffContext(projectDir, fromAgent) {
  * @returns {object[]} Array of handoff summaries
  */
 export function getHandoffHistory(projectDir) {
-  const handoffsDir = join(projectDir, 'chati.dev', 'artifacts', 'handoffs');
+  const handoffsDir = join(projectDir, resolveFrameworkDir(projectDir), 'artifacts', 'handoffs');
 
   if (!existsSync(handoffsDir)) {
     return [];

package/src/orchestrator/index.js

@@ -60,6 +60,8 @@ export {
   updateSession,
   recordModeTransition,
   recordAgentCompletion,
+  parseHandoffDecisionTrail,
+  parseHandoffScaffoldSignals,
   getSessionSummary,
   validateSession,
   claimSession,