@massu/core 0.1.1 → 0.4.0

package/src/commands/doctor.ts

@@ -9,15 +9,20 @@
  * 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
+ * 5. Knowledge DB exists (.massu/memory.db)
+ * 6. Memory directory exists (~/.claude/projects/.../memory/)
+ * 7. Shell hooks wired in settings.local.json
+ * 8. better-sqlite3 native module loads
+ * 9. Node.js version >= 18
+ * 10. Git repository detected
  */
 
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, readdirSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { parse as parseYaml } from 'yaml';
+import { getConfig, getResolvedPaths } from '../config.ts';
+import { getCurrentTier, getLicenseInfo, daysUntilExpiry } from '../license.ts';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -73,7 +78,7 @@ function checkConfig(projectRoot: string): CheckResult {
 }
 
 function checkMcpServer(projectRoot: string): CheckResult {
-  const mcpPath = resolve(projectRoot, '.mcp.json');
+  const mcpPath = getResolvedPaths().mcpJsonPath;
   if (!existsSync(mcpPath)) {
     return { name: 'MCP Server', status: 'fail', detail: '.mcp.json not found. Run: npx massu init' };
   }
@@ -91,7 +96,7 @@ function checkMcpServer(projectRoot: string): CheckResult {
 }
 
 function checkHooksConfig(projectRoot: string): CheckResult {
-  const settingsPath = resolve(projectRoot, '.claude/settings.local.json');
+  const settingsPath = getResolvedPaths().settingsLocalPath;
   if (!existsSync(settingsPath)) {
     return { name: 'Hooks Config', status: 'fail', detail: '.claude/settings.local.json not found. Run: npx massu init' };
   }
@@ -194,6 +199,180 @@ async function checkGitRepo(projectRoot: string): Promise<CheckResult> {
   }
 }
 
+function checkKnowledgeDb(projectRoot: string): CheckResult {
+  // Knowledge DB is the memory DB
+  const knowledgeDbPath = getResolvedPaths().memoryDbPath;
+  if (!existsSync(knowledgeDbPath)) {
+    return {
+      name: 'Knowledge DB',
+      status: 'warn',
+      detail: '.massu/memory.db not found (will auto-create on first session)',
+    };
+  }
+  return { name: 'Knowledge DB', status: 'pass', detail: '.massu/memory.db exists' };
+}
+
+function checkMemoryDir(_projectRoot: string): CheckResult {
+  // Memory dir: ~/.claude/projects/-<encoded-root>/memory/ (resolved via config)
+  const memoryDir = getResolvedPaths().memoryDir;
+  if (!existsSync(memoryDir)) {
+    return {
+      name: 'Memory Directory',
+      status: 'warn',
+      detail: 'Memory directory not found. Run: npx massu init',
+    };
+  }
+  return { name: 'Memory Directory', status: 'pass', detail: `Memory directory exists` };
+}
+
+function checkShellHooksWired(_projectRoot: string): CheckResult {
+  // Verify that .claude/settings.local.json has hooks configured (shell hooks are wired)
+  const settingsPath = getResolvedPaths().settingsLocalPath;
+  if (!existsSync(settingsPath)) {
+    return {
+      name: 'Shell Hooks',
+      status: 'fail',
+      detail: 'settings.local.json not found. Run: npx massu install-hooks',
+    };
+  }
+
+  try {
+    const content = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    const hooks = content.hooks ?? {};
+    const hasSessionStart = Array.isArray(hooks.SessionStart) && hooks.SessionStart.length > 0;
+    const hasPreToolUse = Array.isArray(hooks.PreToolUse) && hooks.PreToolUse.length > 0;
+    if (!hasSessionStart && !hasPreToolUse) {
+      return {
+        name: 'Shell Hooks',
+        status: 'fail',
+        detail: 'No lifecycle hooks wired. Run: npx massu install-hooks',
+      };
+    }
+    return { name: 'Shell Hooks', status: 'pass', detail: 'Lifecycle hooks wired in settings.local.json' };
+  } catch (err) {
+    return {
+      name: 'Shell Hooks',
+      status: 'fail',
+      detail: `settings.local.json parse error: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+async function checkLicenseStatus(): Promise<CheckResult> {
+  try {
+    const tier = await getCurrentTier();
+    const info = await getLicenseInfo();
+
+    if (tier === 'free' && !info.validUntil) {
+      return { name: 'License', status: 'pass', detail: 'Free (no API key configured)' };
+    }
+
+    const days = await daysUntilExpiry();
+    if (days >= 0 && info.validUntil) {
+      return {
+        name: 'License',
+        status: 'pass',
+        detail: `${tier.charAt(0).toUpperCase() + tier.slice(1)} (valid until ${info.validUntil})`,
+      };
+    }
+
+    return {
+      name: 'License',
+      status: 'pass',
+      detail: `${tier.charAt(0).toUpperCase() + tier.slice(1)} (valid)`,
+    };
+  } catch (err) {
+    return {
+      name: 'License',
+      status: 'warn',
+      detail: `Could not check license: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+function checkPythonHealth(projectRoot: string): CheckResult | null {
+  const config = getConfig();
+  if (!config.python?.root) return null;
+
+  const pythonRoot = resolve(projectRoot, config.python.root);
+  if (!existsSync(pythonRoot)) {
+    return {
+      name: 'Python',
+      status: 'fail',
+      detail: `Python root directory not found: ${config.python.root}`,
+    };
+  }
+
+  // Count .py files recursively (shallow scan for performance)
+  let pyFileCount = 0;
+  let routeCount = 0;
+  let modelCount = 0;
+  const initPyMissing: string[] = [];
+
+  function scanDir(dir: string, depth: number): void {
+    if (depth > 5) return;
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const excludeDirs = config.python?.exclude_dirs || ['__pycache__', '.venv', 'venv', '.mypy_cache', '.pytest_cache'];
+          if (!excludeDirs.includes(entry.name)) {
+            const subdir = resolve(dir, entry.name);
+            // Check for __init__.py in package directories
+            if (depth <= 2 && !existsSync(resolve(subdir, '__init__.py'))) {
+              // Only flag directories that contain .py files
+              try {
+                const subEntries = readdirSync(subdir);
+                if (subEntries.some(f => f.endsWith('.py') && f !== '__init__.py')) {
+                  initPyMissing.push(entry.name);
+                }
+              } catch { /* skip */ }
+            }
+            scanDir(subdir, depth + 1);
+          }
+        } else if (entry.name.endsWith('.py')) {
+          pyFileCount++;
+          // Rough heuristic for routes and models
+          if (entry.name === 'routes.py' || entry.name === 'router.py' || entry.name === 'endpoints.py') {
+            routeCount++;
+          }
+          if (entry.name === 'models.py' || entry.name === 'model.py' || entry.name === 'schemas.py') {
+            modelCount++;
+          }
+        }
+      }
+    } catch { /* skip unreadable dirs */ }
+  }
+
+  scanDir(pythonRoot, 0);
+
+  if (pyFileCount === 0) {
+    return {
+      name: 'Python',
+      status: 'warn',
+      detail: `Python root ${config.python.root} exists but no .py files found`,
+    };
+  }
+
+  const parts: string[] = [`${pyFileCount} .py files`];
+  if (routeCount > 0) parts.push(`${routeCount} route files`);
+  if (modelCount > 0) parts.push(`${modelCount} model files`);
+  if (initPyMissing.length > 0) {
+    parts.push(`missing __init__.py: ${initPyMissing.slice(0, 3).join(', ')}${initPyMissing.length > 3 ? '...' : ''}`);
+    return {
+      name: 'Python',
+      status: 'warn',
+      detail: parts.join(', '),
+    };
+  }
+
+  return {
+    name: 'Python',
+    status: 'pass',
+    detail: parts.join(', '),
+  };
+}
+
 // ============================================================
 // Main Doctor Flow
 // ============================================================
@@ -211,11 +390,19 @@ export async function runDoctor(): Promise<void> {
     checkMcpServer(projectRoot),
     checkHooksConfig(projectRoot),
     checkHookFiles(projectRoot),
+    checkKnowledgeDb(projectRoot),
+    checkMemoryDir(projectRoot),
+    checkShellHooksWired(projectRoot),
     await checkNativeModules(),
     checkNodeVersion(),
     await checkGitRepo(projectRoot),
+    await checkLicenseStatus(),
   ];
 
+  // Add Python health check if configured
+  const pythonCheck = checkPythonHealth(projectRoot);
+  if (pythonCheck) checks.push(pythonCheck);
+
   let passed = 0;
   let failed = 0;
   let warned = 0;

package/src/commands/init.ts

@@ -8,16 +8,21 @@
  * 2. Generates massu.config.yaml (or preserves existing)
  * 3. Registers MCP server in .mcp.json (creates or merges)
  * 4. Installs all 11 hooks in .claude/settings.local.json
- * 5. Prints success summary
+ * 5. Installs slash commands into .claude/commands/
+ * 6. Initializes memory directory
+ * 7. Prints success summary
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
 import { resolve, basename, dirname } from 'path';
 import { fileURLToPath } from 'url';
+import { homedir } from 'os';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 import { stringify as yamlStringify } from 'yaml';
+import { getConfig } from '../config.ts';
+import { installCommands } from './install-commands.ts';
 
 // ============================================================
 // Types
@@ -91,6 +96,135 @@ export function detectFramework(projectRoot: string): FrameworkDetection {
   return result;
 }
 
+// ============================================================
+// Python Project Detection
+// ============================================================
+
+interface PythonDetection {
+  detected: boolean;
+  root: string;
+  hasFastapi: boolean;
+  hasSqlalchemy: boolean;
+  hasAlembic: boolean;
+  alembicDir: string | null;
+}
+
+export function detectPython(projectRoot: string): PythonDetection {
+  const result: PythonDetection = {
+    detected: false,
+    root: '',
+    hasFastapi: false,
+    hasSqlalchemy: false,
+    hasAlembic: false,
+    alembicDir: null,
+  };
+
+  // Check for Python project markers
+  const markers = ['pyproject.toml', 'setup.py', 'requirements.txt', 'Pipfile'];
+  const hasMarker = markers.some(m => existsSync(resolve(projectRoot, m)));
+  if (!hasMarker) return result;
+
+  result.detected = true;
+
+  // Scan dependencies for FastAPI and SQLAlchemy
+  const depFiles = [
+    { file: 'pyproject.toml', parser: parsePyprojectDeps },
+    { file: 'requirements.txt', parser: parseRequirementsDeps },
+    { file: 'setup.py', parser: parseSetupPyDeps },
+    { file: 'Pipfile', parser: parsePipfileDeps },
+  ];
+
+  for (const { file, parser } of depFiles) {
+    const filePath = resolve(projectRoot, file);
+    if (existsSync(filePath)) {
+      try {
+        const content = readFileSync(filePath, 'utf-8');
+        const deps = parser(content);
+        if (deps.includes('fastapi')) result.hasFastapi = true;
+        if (deps.includes('sqlalchemy')) result.hasSqlalchemy = true;
+      } catch {
+        // Best effort
+      }
+    }
+  }
+
+  // Check for Alembic
+  if (existsSync(resolve(projectRoot, 'alembic.ini'))) {
+    result.hasAlembic = true;
+    // Try to find the alembic versions directory
+    if (existsSync(resolve(projectRoot, 'alembic'))) {
+      result.alembicDir = 'alembic';
+    }
+  } else if (existsSync(resolve(projectRoot, 'alembic'))) {
+    result.hasAlembic = true;
+    result.alembicDir = 'alembic';
+  }
+
+  // Auto-detect Python source root
+  const candidateRoots = ['app', 'src', 'backend', 'api'];
+  for (const candidate of candidateRoots) {
+    const candidatePath = resolve(projectRoot, candidate);
+    if (existsSync(candidatePath) && existsSync(resolve(candidatePath, '__init__.py'))) {
+      result.root = candidate;
+      break;
+    }
+    // Also check for .py files directly (some projects use app/ without __init__.py)
+    if (existsSync(candidatePath)) {
+      try {
+        const files = readdirSync(candidatePath);
+        if (files.some(f => f.endsWith('.py'))) {
+          result.root = candidate;
+          break;
+        }
+      } catch {
+        // Best effort
+      }
+    }
+  }
+
+  // Fallback: use '.' if no candidate root found
+  if (!result.root) {
+    result.root = '.';
+  }
+
+  return result;
+}
+
+function parsePyprojectDeps(content: string): string[] {
+  const deps: string[] = [];
+  const lower = content.toLowerCase();
+  if (lower.includes('fastapi')) deps.push('fastapi');
+  if (lower.includes('sqlalchemy')) deps.push('sqlalchemy');
+  return deps;
+}
+
+function parseRequirementsDeps(content: string): string[] {
+  const deps: string[] = [];
+  const lower = content.toLowerCase();
+  for (const line of lower.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('fastapi')) deps.push('fastapi');
+    if (trimmed.startsWith('sqlalchemy')) deps.push('sqlalchemy');
+  }
+  return deps;
+}
+
+function parseSetupPyDeps(content: string): string[] {
+  const deps: string[] = [];
+  const lower = content.toLowerCase();
+  if (lower.includes('fastapi')) deps.push('fastapi');
+  if (lower.includes('sqlalchemy')) deps.push('sqlalchemy');
+  return deps;
+}
+
+function parsePipfileDeps(content: string): string[] {
+  const deps: string[] = [];
+  const lower = content.toLowerCase();
+  if (lower.includes('fastapi')) deps.push('fastapi');
+  if (lower.includes('sqlalchemy')) deps.push('sqlalchemy');
+  return deps;
+}
+
 // ============================================================
 // Config File Generation
 // ============================================================
@@ -104,7 +238,7 @@ export function generateConfig(projectRoot: string, framework: FrameworkDetectio
 
   const projectName = basename(projectRoot);
 
-  const config = {
+  const config: Record<string, unknown> = {
     project: {
       name: projectName,
       root: 'auto',
@@ -129,6 +263,21 @@ export function generateConfig(projectRoot: string, framework: FrameworkDetectio
     ],
   };
 
+  // Detect and add Python configuration
+  const python = detectPython(projectRoot);
+  if (python.detected) {
+    const pythonConfig: Record<string, unknown> = {
+      root: python.root,
+      exclude_dirs: ['__pycache__', '.venv', 'venv', '.mypy_cache', '.pytest_cache'],
+    };
+    if (python.hasFastapi) pythonConfig.framework = 'fastapi';
+    if (python.hasSqlalchemy) pythonConfig.orm = 'sqlalchemy';
+    if (python.hasAlembic && python.alembicDir) {
+      pythonConfig.alembic_dir = python.alembicDir;
+    }
+    config.python = pythonConfig;
+  }
+
   const yamlContent = `# Massu AI Configuration
 # Generated by: npx massu init
 # Documentation: https://massu.ai/docs/getting-started/configuration
@@ -281,7 +430,8 @@ export function buildHooksConfig(hooksDir: string): HooksConfig {
 }
 
 export function installHooks(projectRoot: string): { installed: boolean; count: number } {
-  const claudeDir = resolve(projectRoot, '.claude');
+  const claudeDirName = getConfig().conventions?.claudeDirName ?? '.claude';
+  const claudeDir = resolve(projectRoot, claudeDirName);
   const settingsPath = resolve(claudeDir, 'settings.local.json');
 
   // Ensure .claude directory exists
@@ -321,6 +471,51 @@ export function installHooks(projectRoot: string): { installed: boolean; count:
   return { installed: true, count: hookCount };
 }
 
+// ============================================================
+// Memory Directory Initialization
+// ============================================================
+
+/**
+ * Initialize the memory directory and create an initial MEMORY.md if absent.
+ * The memory directory lives in ~/.claude/projects/<encoded-root>/memory/
+ * matching the path used by memory-db.ts / knowledge-tools.ts.
+ */
+export function initMemoryDir(projectRoot: string): { created: boolean; memoryMdCreated: boolean } {
+  // Encode the project root the same way as getResolvedPaths() in config.ts
+  const encodedRoot = '-' + projectRoot.replace(/\//g, '-');
+  const memoryDir = resolve(homedir(), `.claude/projects/${encodedRoot}/memory`);
+
+  let created = false;
+  if (!existsSync(memoryDir)) {
+    mkdirSync(memoryDir, { recursive: true });
+    created = true;
+  }
+
+  const memoryMdPath = resolve(memoryDir, 'MEMORY.md');
+  let memoryMdCreated = false;
+  if (!existsSync(memoryMdPath)) {
+    const projectName = basename(projectRoot);
+    const memoryContent = `# ${projectName} - Massu Memory
+
+## Key Learnings
+<!-- Important patterns and conventions discovered during development -->
+
+## Common Gotchas
+<!-- Non-obvious issues and how to avoid them -->
+
+## Corrections
+<!-- Wrong behaviors that were corrected and how to prevent them -->
+
+## File Index
+<!-- Significant files and directories -->
+`;
+    writeFileSync(memoryMdPath, memoryContent, 'utf-8');
+    memoryMdCreated = true;
+  }
+
+  return { created, memoryMdCreated };
+}
+
 // ============================================================
 // Main Init Flow
 // ============================================================
@@ -343,6 +538,16 @@ export async function runInit(): Promise<void> {
   const detected = frameworkParts.length > 0 ? frameworkParts.join(', ') : 'JavaScript';
   console.log(`  Detected: ${detected}`);
 
+  // Step 1b: Detect Python
+  const python = detectPython(projectRoot);
+  if (python.detected) {
+    const pyParts: string[] = ['Python'];
+    if (python.hasFastapi) pyParts.push('FastAPI');
+    if (python.hasSqlalchemy) pyParts.push('SQLAlchemy');
+    if (python.hasAlembic) pyParts.push('Alembic');
+    console.log(`  Detected: ${pyParts.join(', ')} (root: ${python.root})`);
+  }
+
   // Step 2: Create config
   const configCreated = generateConfig(projectRoot, framework);
   if (configCreated) {
@@ -363,7 +568,27 @@ export async function runInit(): Promise<void> {
   const { count: hooksCount } = installHooks(projectRoot);
   console.log(`  Installed ${hooksCount} hooks in .claude/settings.local.json`);
 
-  // Step 5: Databases info
+  // Step 5: Install slash commands
+  const cmdResult = installCommands(projectRoot);
+  const cmdTotal = cmdResult.installed + cmdResult.updated + cmdResult.skipped;
+  if (cmdResult.installed > 0 || cmdResult.updated > 0) {
+    console.log(`  Installed ${cmdTotal} slash commands (${cmdResult.installed} new, ${cmdResult.updated} updated)`);
+  } else {
+    console.log(`  ${cmdTotal} slash commands already up to date`);
+  }
+
+  // Step 6: Initialize memory directory
+  const { created: memDirCreated, memoryMdCreated } = initMemoryDir(projectRoot);
+  if (memDirCreated) {
+    console.log('  Created memory directory (~/.claude/projects/.../memory/)');
+  } else {
+    console.log('  Memory directory already exists');
+  }
+  if (memoryMdCreated) {
+    console.log('  Created initial MEMORY.md');
+  }
+
+  // Step 7: Databases info
   console.log('  Databases will auto-create on first session');
 
   // Summary

package/src/commands/install-commands.ts

@@ -0,0 +1,137 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * `massu install-commands` — Install massu slash commands into a project.
+ *
+ * Copies all massu command .md files from the package's commands/ directory
+ * into the project's .claude/commands/ directory. Existing massu commands
+ * are updated; non-massu commands are preserved.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { getConfig } from '../config.ts';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ============================================================
+// Command Installation
+// ============================================================
+
+/**
+ * Resolve the path to the bundled commands directory.
+ * Handles both npm-installed and local development scenarios.
+ */
+export function resolveCommandsDir(): string | null {
+  const cwd = process.cwd();
+
+  // 1. npm-installed: node_modules/@massu/core/commands
+  const nodeModulesPath = resolve(cwd, 'node_modules/@massu/core/commands');
+  if (existsSync(nodeModulesPath)) {
+    return nodeModulesPath;
+  }
+
+  // 2. Relative to compiled dist/cli.js → ../commands
+  const distRelPath = resolve(__dirname, '../commands');
+  if (existsSync(distRelPath)) {
+    return distRelPath;
+  }
+
+  // 3. Relative to source src/commands/ → ../../commands
+  const srcRelPath = resolve(__dirname, '../../commands');
+  if (existsSync(srcRelPath)) {
+    return srcRelPath;
+  }
+
+  return null;
+}
+
+export interface InstallCommandsResult {
+  installed: number;
+  updated: number;
+  skipped: number;
+  commandsDir: string;
+}
+
+export function installCommands(projectRoot: string): InstallCommandsResult {
+  const claudeDirName = getConfig().conventions?.claudeDirName ?? '.claude';
+  const targetDir = resolve(projectRoot, claudeDirName, 'commands');
+
+  // Ensure .claude/commands directory exists
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true });
+  }
+
+  // Find source commands
+  const sourceDir = resolveCommandsDir();
+  if (!sourceDir) {
+    console.error('  ERROR: Could not find massu commands directory.');
+    console.error('  Try reinstalling: npm install @massu/core');
+    return { installed: 0, updated: 0, skipped: 0, commandsDir: targetDir };
+  }
+
+  // Read all command files from source
+  const sourceFiles = readdirSync(sourceDir).filter(f => f.endsWith('.md'));
+
+  let installed = 0;
+  let updated = 0;
+  let skipped = 0;
+
+  for (const file of sourceFiles) {
+    const sourcePath = resolve(sourceDir, file);
+    const targetPath = resolve(targetDir, file);
+    const sourceContent = readFileSync(sourcePath, 'utf-8');
+
+    if (existsSync(targetPath)) {
+      const existingContent = readFileSync(targetPath, 'utf-8');
+      if (existingContent === sourceContent) {
+        skipped++;
+        continue;
+      }
+      // Update existing command
+      writeFileSync(targetPath, sourceContent, 'utf-8');
+      updated++;
+    } else {
+      // Install new command
+      writeFileSync(targetPath, sourceContent, 'utf-8');
+      installed++;
+    }
+  }
+
+  return { installed, updated, skipped, commandsDir: targetDir };
+}
+
+// ============================================================
+// Standalone CLI Runner
+// ============================================================
+
+export async function runInstallCommands(): Promise<void> {
+  const projectRoot = process.cwd();
+
+  console.log('');
+  console.log('Massu AI - Install Slash Commands');
+  console.log('==================================');
+  console.log('');
+
+  const result = installCommands(projectRoot);
+
+  if (result.installed > 0) {
+    console.log(`  Installed ${result.installed} new commands`);
+  }
+  if (result.updated > 0) {
+    console.log(`  Updated ${result.updated} existing commands`);
+  }
+  if (result.skipped > 0) {
+    console.log(`  ${result.skipped} commands already up to date`);
+  }
+
+  const total = result.installed + result.updated + result.skipped;
+  console.log('');
+  console.log(`  ${total} slash commands available in ${result.commandsDir}`);
+  console.log('');
+  console.log('  Restart your Claude Code session to use them.');
+  console.log('');
+}