@massu/core 0.1.0 → 0.1.2

package/src/cli.ts

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Massu CLI Entry Point
+ *
+ * Routes subcommands to handlers, falls through to MCP server mode
+ * when no subcommand is provided (backward compatible).
+ *
+ * Usage:
+ *   npx massu init            - Full project setup
+ *   npx massu doctor          - Health check
+ *   npx massu install-hooks   - Install hooks only
+ *   npx massu validate-config - Validate configuration
+ *   npx @massu/core           - MCP server mode (no args)
+ */
+
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const args = process.argv.slice(2);
+const subcommand = args[0];
+
+async function main(): Promise<void> {
+  switch (subcommand) {
+    case 'init': {
+      const { runInit } = await import('./commands/init.ts');
+      await runInit();
+      break;
+    }
+    case 'doctor': {
+      const { runDoctor } = await import('./commands/doctor.ts');
+      await runDoctor();
+      break;
+    }
+    case 'install-hooks': {
+      const { runInstallHooks } = await import('./commands/install-hooks.ts');
+      await runInstallHooks();
+      break;
+    }
+    case 'validate-config': {
+      const { runValidateConfig } = await import('./commands/doctor.ts');
+      await runValidateConfig();
+      break;
+    }
+    case '--help':
+    case '-h': {
+      printHelp();
+      break;
+    }
+    case '--version':
+    case '-v': {
+      printVersion();
+      break;
+    }
+    default: {
+      // No subcommand or unknown: fall through to MCP server mode
+      // This maintains backward compatibility with `npx @massu/core`
+      await import('./server.ts');
+    }
+  }
+}
+
+function printHelp(): void {
+  console.log(`
+Massu AI - Engineering Governance Platform
+
+Usage:
+  massu <command>
+
+Commands:
+  init              Set up Massu AI in your project (one command, full setup)
+  doctor            Check installation health
+  install-hooks     Install/update Claude Code hooks
+  validate-config   Validate massu.config.yaml
+
+Options:
+  --help, -h        Show this help message
+  --version, -v     Show version
+
+Getting started:
+  npx massu init    # Full setup in one command
+
+Documentation: https://massu.ai/docs
+`);
+}
+
+function printVersion(): void {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(__dirname, '../package.json'), 'utf-8'));
+    console.log(`massu v${pkg.version}`);
+  } catch {
+    console.log('massu v0.1.0');
+  }
+}
+
+main().catch((err) => {
+  console.error(`massu: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});

package/src/cloud-sync.ts

@@ -0,0 +1,190 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+import type Database from 'better-sqlite3';
+import { getConfig } from './config.ts';
+import {
+  enqueueSyncPayload,
+  dequeuePendingSync,
+  removePendingSync,
+  incrementRetryCount,
+} from './memory-db.ts';
+
+// ============================================================
+// Cloud Sync Module
+// Internal module — NOT an MCP tool. Called by session-end hook.
+// ============================================================
+
+export interface SyncPayload {
+  sessions?: Array<{
+    local_session_id: string;
+    project_name?: string;
+    summary?: string;
+    started_at?: string;
+    ended_at?: string;
+    turns?: number;
+    tokens_used?: number;
+    estimated_cost?: number;
+    tools_used?: string[];
+  }>;
+  observations?: Array<{
+    local_observation_id: string;
+    session_id?: string;
+    type: string;
+    content: string;
+    importance: number;
+    file_path?: string;
+  }>;
+  analytics?: Array<{
+    event_type: string;
+    event_data: Record<string, unknown>;
+  }>;
+  audit?: Array<{
+    action: string;
+    resource?: string;
+    details: Record<string, unknown>;
+  }>;
+}
+
+export interface SyncResult {
+  success: boolean;
+  synced: {
+    sessions: number;
+    observations: number;
+    analytics: number;
+    audit: number;
+  };
+  error?: string;
+}
+
+const MAX_RETRIES = 3;
+const RETRY_DELAYS = [1000, 2000, 4000]; // exponential backoff
+
+/**
+ * Sync data to the cloud endpoint.
+ * Respects config flags for selective sync.
+ * On failure after retries, enqueues payload for later retry.
+ */
+export async function syncToCloud(
+  db: Database.Database,
+  payload: SyncPayload
+): Promise<SyncResult> {
+  const config = getConfig();
+  const cloud = config.cloud;
+
+  // Check if cloud sync is enabled
+  if (!cloud?.enabled) {
+    return { success: true, synced: { sessions: 0, observations: 0, analytics: 0, audit: 0 } };
+  }
+
+  // Check API key
+  if (!cloud.apiKey) {
+    return { success: false, synced: { sessions: 0, observations: 0, analytics: 0, audit: 0 }, error: 'No API key configured' };
+  }
+
+  // Check endpoint
+  const endpoint = cloud.endpoint;
+  if (!endpoint) {
+    return { success: false, synced: { sessions: 0, observations: 0, analytics: 0, audit: 0 }, error: 'No sync endpoint configured' };
+  }
+
+  // Apply selective sync filters
+  const filteredPayload: SyncPayload = {};
+  if (cloud.sync?.memory !== false) {
+    filteredPayload.sessions = payload.sessions;
+    filteredPayload.observations = payload.observations;
+  }
+  if (cloud.sync?.analytics !== false) {
+    filteredPayload.analytics = payload.analytics;
+  }
+  if (cloud.sync?.audit !== false) {
+    filteredPayload.audit = payload.audit;
+  }
+
+  // Attempt sync with retry
+  let lastError = '';
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+    try {
+      const response = await fetch(endpoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${cloud.apiKey}`,
+        },
+        body: JSON.stringify(filteredPayload),
+      });
+
+      if (!response.ok) {
+        lastError = `HTTP ${response.status}: ${response.statusText}`;
+        if (response.status >= 400 && response.status < 500) {
+          // Client errors are not retryable
+          break;
+        }
+        // Server errors — retry
+        if (attempt < MAX_RETRIES - 1) {
+          await sleep(RETRY_DELAYS[attempt]);
+          continue;
+        }
+        break;
+      }
+
+      const result = await response.json() as { synced?: { sessions?: number; observations?: number; analytics?: number } };
+      return {
+        success: true,
+        synced: {
+          sessions: result.synced?.sessions ?? 0,
+          observations: result.synced?.observations ?? 0,
+          analytics: result.synced?.analytics ?? 0,
+          audit: 0,
+        },
+      };
+    } catch (err) {
+      lastError = err instanceof Error ? err.message : String(err);
+      if (attempt < MAX_RETRIES - 1) {
+        await sleep(RETRY_DELAYS[attempt]);
+        continue;
+      }
+    }
+  }
+
+  // All retries exhausted — enqueue for later
+  try {
+    enqueueSyncPayload(db, JSON.stringify(payload));
+  } catch (_e) {
+    // Best effort — don't crash if queue fails
+  }
+
+  return {
+    success: false,
+    synced: { sessions: 0, observations: 0, analytics: 0, audit: 0 },
+    error: lastError,
+  };
+}
+
+/**
+ * Drain the pending sync queue. Processes items oldest-first.
+ * Successfully synced items are removed; failed items get their retry count incremented.
+ */
+export async function drainSyncQueue(db: Database.Database): Promise<void> {
+  const config = getConfig();
+  if (!config.cloud?.enabled || !config.cloud?.apiKey) return;
+
+  const pending = dequeuePendingSync(db, 10);
+  for (const item of pending) {
+    try {
+      const payload = JSON.parse(item.payload) as SyncPayload;
+      const result = await syncToCloud(db, payload);
+      if (result.success) {
+        removePendingSync(db, item.id);
+      } else {
+        incrementRetryCount(db, item.id, result.error ?? 'Unknown error');
+      }
+    } catch (err) {
+      incrementRetryCount(db, item.id, err instanceof Error ? err.message : String(err));
+    }
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/src/commands/doctor.ts

@@ -0,0 +1,300 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * `massu doctor` — Installation health check.
+ *
+ * Verifies all components of a Massu AI installation are working:
+ * 1. massu.config.yaml exists and parses correctly
+ * 2. .mcp.json has massu entry
+ * 3. .claude/settings.local.json has hooks config
+ * 4. All 11 compiled hook files exist
+ * 5. better-sqlite3 native module loads
+ * 6. Node.js version >= 18
+ * 7. Git repository detected
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { parse as parseYaml } from 'yaml';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ============================================================
+// Types
+// ============================================================
+
+interface CheckResult {
+  name: string;
+  status: 'pass' | 'fail' | 'warn';
+  detail: string;
+}
+
+// ============================================================
+// Hook Files
+// ============================================================
+
+const EXPECTED_HOOKS = [
+  'session-start.js',
+  'session-end.js',
+  'post-tool-use.js',
+  'user-prompt.js',
+  'pre-compact.js',
+  'pre-delete-check.js',
+  'post-edit-context.js',
+  'security-gate.js',
+  'cost-tracker.js',
+  'quality-event.js',
+  'intent-suggester.js',
+];
+
+// ============================================================
+// Individual Checks
+// ============================================================
+
+function checkConfig(projectRoot: string): CheckResult {
+  const configPath = resolve(projectRoot, 'massu.config.yaml');
+  if (!existsSync(configPath)) {
+    return { name: 'Configuration', status: 'fail', detail: 'massu.config.yaml not found. Run: npx massu init' };
+  }
+
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    const parsed = parseYaml(content);
+    if (!parsed || typeof parsed !== 'object') {
+      return { name: 'Configuration', status: 'fail', detail: 'massu.config.yaml is empty or invalid YAML' };
+    }
+    return { name: 'Configuration', status: 'pass', detail: 'massu.config.yaml found and valid' };
+  } catch (err) {
+    return { name: 'Configuration', status: 'fail', detail: `massu.config.yaml parse error: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+
+function checkMcpServer(projectRoot: string): CheckResult {
+  const mcpPath = resolve(projectRoot, '.mcp.json');
+  if (!existsSync(mcpPath)) {
+    return { name: 'MCP Server', status: 'fail', detail: '.mcp.json not found. Run: npx massu init' };
+  }
+
+  try {
+    const content = JSON.parse(readFileSync(mcpPath, 'utf-8'));
+    const servers = content.mcpServers ?? {};
+    if (!servers.massu) {
+      return { name: 'MCP Server', status: 'fail', detail: 'massu not registered in .mcp.json. Run: npx massu init' };
+    }
+    return { name: 'MCP Server', status: 'pass', detail: 'Registered in .mcp.json' };
+  } catch (err) {
+    return { name: 'MCP Server', status: 'fail', detail: `.mcp.json parse error: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+
+function checkHooksConfig(projectRoot: string): CheckResult {
+  const settingsPath = resolve(projectRoot, '.claude/settings.local.json');
+  if (!existsSync(settingsPath)) {
+    return { name: 'Hooks Config', status: 'fail', detail: '.claude/settings.local.json not found. Run: npx massu init' };
+  }
+
+  try {
+    const content = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    if (!content.hooks) {
+      return { name: 'Hooks Config', status: 'fail', detail: 'No hooks configured. Run: npx massu install-hooks' };
+    }
+
+    // Count configured hooks
+    let hookCount = 0;
+    for (const groups of Object.values(content.hooks)) {
+      if (Array.isArray(groups)) {
+        for (const group of groups) {
+          const g = group as { hooks?: unknown[] };
+          if (Array.isArray(g.hooks)) {
+            hookCount += g.hooks.length;
+          }
+        }
+      }
+    }
+
+    if (hookCount === 0) {
+      return { name: 'Hooks Config', status: 'fail', detail: 'Hooks section exists but no hooks configured' };
+    }
+
+    return { name: 'Hooks Config', status: 'pass', detail: `${hookCount} hooks configured` };
+  } catch (err) {
+    return { name: 'Hooks Config', status: 'fail', detail: `settings.local.json parse error: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+
+function checkHookFiles(projectRoot: string): CheckResult {
+  // Check node_modules path first
+  const nodeModulesHooksDir = resolve(projectRoot, 'node_modules/@massu/core/dist/hooks');
+  let hooksDir = nodeModulesHooksDir;
+
+  if (!existsSync(nodeModulesHooksDir)) {
+    // Check relative to this file (development mode)
+    const devHooksDir = resolve(__dirname, '../../dist/hooks');
+    if (existsSync(devHooksDir)) {
+      hooksDir = devHooksDir;
+    } else {
+      return { name: 'Hook Files', status: 'fail', detail: 'Compiled hooks not found. Run: npm install @massu/core' };
+    }
+  }
+
+  const missing: string[] = [];
+  for (const hookFile of EXPECTED_HOOKS) {
+    if (!existsSync(resolve(hooksDir, hookFile))) {
+      missing.push(hookFile);
+    }
+  }
+
+  if (missing.length > 0) {
+    return { name: 'Hook Files', status: 'fail', detail: `Missing hooks: ${missing.join(', ')}` };
+  }
+
+  return { name: 'Hook Files', status: 'pass', detail: `${EXPECTED_HOOKS.length}/${EXPECTED_HOOKS.length} compiled hooks present` };
+}
+
+async function checkNativeModules(): Promise<CheckResult> {
+  try {
+    await import('better-sqlite3');
+    return { name: 'Native Modules', status: 'pass', detail: 'better-sqlite3 loads correctly' };
+  } catch (err) {
+    return { name: 'Native Modules', status: 'fail', detail: `better-sqlite3 failed: ${err instanceof Error ? err.message : String(err)}. Try: npm rebuild better-sqlite3` };
+  }
+}
+
+function checkNodeVersion(): CheckResult {
+  const version = process.versions.node;
+  const major = parseInt(version.split('.')[0], 10);
+
+  if (major >= 18) {
+    return { name: 'Node.js', status: 'pass', detail: `v${version} (>= 18 required)` };
+  }
+
+  return { name: 'Node.js', status: 'fail', detail: `v${version} — Node.js 18+ is required` };
+}
+
+async function checkGitRepo(projectRoot: string): Promise<CheckResult> {
+  const gitDir = resolve(projectRoot, '.git');
+  if (!existsSync(gitDir)) {
+    return { name: 'Git Repository', status: 'warn', detail: 'Not a git repository (optional but recommended)' };
+  }
+
+  try {
+    const { spawnSync } = await import('child_process');
+    const result = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      encoding: 'utf-8',
+      timeout: 5000,
+      cwd: projectRoot,
+    });
+    const branch = result.stdout?.trim() ?? 'unknown';
+    return { name: 'Git Repository', status: 'pass', detail: `Detected (branch: ${branch})` };
+  } catch {
+    return { name: 'Git Repository', status: 'pass', detail: 'Detected' };
+  }
+}
+
+// ============================================================
+// Main Doctor Flow
+// ============================================================
+
+export async function runDoctor(): Promise<void> {
+  const projectRoot = process.cwd();
+
+  console.log('');
+  console.log('Massu AI Health Check');
+  console.log('=====================');
+  console.log('');
+
+  const checks: CheckResult[] = [
+    checkConfig(projectRoot),
+    checkMcpServer(projectRoot),
+    checkHooksConfig(projectRoot),
+    checkHookFiles(projectRoot),
+    await checkNativeModules(),
+    checkNodeVersion(),
+    await checkGitRepo(projectRoot),
+  ];
+
+  let passed = 0;
+  let failed = 0;
+  let warned = 0;
+
+  for (const check of checks) {
+    const icon = check.status === 'pass' ? '\u2713' : check.status === 'warn' ? '!' : '\u2717';
+    const pad = check.name.padEnd(20);
+    console.log(`  ${icon} ${pad} ${check.detail}`);
+
+    if (check.status === 'pass') passed++;
+    else if (check.status === 'fail') failed++;
+    else warned++;
+  }
+
+  console.log('');
+
+  if (failed === 0) {
+    const total = passed + warned;
+    console.log(`Status: HEALTHY (${passed}/${total} checks passed${warned > 0 ? `, ${warned} warnings` : ''})`);
+  } else {
+    console.log(`Status: UNHEALTHY (${failed} check${failed > 1 ? 's' : ''} failed)`);
+    console.log('');
+    console.log('Fix issues above, then run: npx massu doctor');
+  }
+  console.log('');
+
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+// ============================================================
+// Validate Config Command
+// ============================================================
+
+export async function runValidateConfig(): Promise<void> {
+  const projectRoot = process.cwd();
+  const configPath = resolve(projectRoot, 'massu.config.yaml');
+
+  if (!existsSync(configPath)) {
+    console.error('Error: massu.config.yaml not found in current directory');
+    console.error('Run: npx massu init');
+    process.exit(1);
+    return;
+  }
+
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    const parsed = parseYaml(content);
+
+    if (!parsed || typeof parsed !== 'object') {
+      console.error('Error: massu.config.yaml is empty or not a valid YAML object');
+      process.exit(1);
+      return;
+    }
+
+    // Check required fields
+    const warnings: string[] = [];
+
+    if (!parsed.project?.name) {
+      warnings.push('Missing project.name (will default to "my-project")');
+    }
+    if (!parsed.toolPrefix) {
+      warnings.push('Missing toolPrefix (will default to "massu")');
+    }
+    if (!parsed.framework?.type) {
+      warnings.push('Missing framework.type (will default to "typescript")');
+    }
+
+    console.log('');
+    if (warnings.length === 0) {
+      console.log('massu.config.yaml is valid');
+    } else {
+      console.log('massu.config.yaml parsed successfully with warnings:');
+      for (const w of warnings) {
+        console.log(`  ! ${w}`);
+      }
+    }
+    console.log('');
+  } catch (err) {
+    console.error(`Error parsing massu.config.yaml: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}