memorylink 1.0.0

package/src/cli.ts

@@ -0,0 +1,1259 @@
+#!/usr/bin/env node
+/**
+ * MemoryLink CLI
+ * Universal memory layer for AI coding assistants
+ * 
+ * Cross-AI sharing • Audit trails • Learning tracking • File protection
+ */
+
+import { Command } from 'commander';
+import { execSync } from 'child_process';
+import {
+  initCommand,
+  protectCommand,
+  unprotectCommand,
+  listProtectedCommand,
+  memoryCommand,
+  listMemoryCommand,
+  clearMemoryCommand,
+  changeCommand,
+  listChangesCommand,
+  clearChangesCommand,
+  learnCommand,
+  listLearningsCommand,
+  clearLearningsCommand,
+  watchCommand,
+  statusCommand,
+  doctorCommand,
+  getContextCommand,
+  exportContextCommand,
+  hooksInstallCommand,
+  hooksUninstallCommand,
+  hooksStatusCommand,
+  configureCommand,
+  quickConfigureCommand,
+  injectCommand,
+  quickInjectCommand,
+  setupCursorCommand,
+  setupClaudeCommand,
+  setupChatGPTCommand,
+  setupCopilotCommand,
+  setupAllCommand,
+  quickstartCommand,
+  migrateCommand,
+  searchCommand,
+  syncCommand,
+  autoLogInstallCommand,
+  autoLogUninstallCommand,
+  autoLogStatusCommand,
+  autoLogCommitCommand,
+  snippetCommand,
+  syncRulesCommand,
+  roadmapCommand,
+  validateCommand,
+  templateListCommand,
+  templateShowCommand,
+  templateCreateCommand,
+  templateDeleteCommand,
+} from './commands/index.js';
+import { 
+  checkpointCreateCommand, 
+  checkpointListCommand, 
+  checkpointDiffCommand,
+  checkpointRestoreCommand,
+} from './commands/checkpoint.js';
+import {
+  lockAcquireCommand,
+  lockReleaseCommand,
+  lockStatusCommand,
+  lockRenewCommand,
+} from './commands/lock.js';
+import { statsCommand } from './commands/stats.js';
+import { scopesListCommand } from './commands/scopes.js';
+import { telemetryTestCommand } from './commands/telemetry-test.js';
+import { DEFAULT_THRESHOLDS } from './config/thresholds.js';
+import { startMCPServer } from './server/mcp-server.js';
+import type { LearningStatus } from './types.js';
+
+const program = new Command();
+
+function validateEnvironment(thisCommand: Command) {
+  const cmdName = thisCommand.name();
+  // Skip global checks for purely informational commands
+  const skip = new Set(['help', 'server']);
+  if (skip.has(cmdName)) {
+    return;
+  }
+
+  // Basic Node.js version check
+  const nodeVersion = process.versions.node.split('.')[0];
+  const nodeMajor = parseInt(nodeVersion, 10);
+  if (Number.isFinite(nodeMajor) && nodeMajor < 16) {
+    console.error('\x1b[31m✗\x1b[0m Node.js 16 or higher is required to run MemoryLink.');
+    console.error(`Detected Node.js version: ${process.version}`);
+    console.error('Please upgrade Node.js from https://nodejs.org/');
+    process.exit(1);
+  }
+
+  // Git availability check – many commands rely on Git for hooks and sync
+  try {
+    execSync('git --version', { stdio: 'ignore' });
+  } catch {
+    console.error('\x1b[31m✗\x1b[0m Git is required for MemoryLink to manage hooks and share memory via your repo.');
+    console.error('Please install Git from https://git-scm.com/downloads and try again.');
+    process.exit(1);
+  }
+}
+
+// ASCII art logo
+const LOGO = `
+\x1b[36m╔══════════════════════════════════════════════════════════╗
+║                                                          ║
+║   🧠 MemoryLink v1.0.0                                   ║
+║   Universal memory layer for AI coding assistants        ║
+║                                                          ║
+╚══════════════════════════════════════════════════════════╝\x1b[0m
+`;
+
+program
+  .name('memorylink')
+  .description('Universal memory layer for AI coding assistants')
+  .version('1.0.0')
+  .option('-v, --verbose', 'Enable verbose output')
+  .hook('preAction', (thisCommand) => {
+    const opts = thisCommand.opts();
+    if (opts.verbose) {
+      console.log('\x1b[90m[verbose mode enabled]\x1b[0m');
+    }
+    // Basic environment validation for most commands
+    validateEnvironment(thisCommand);
+  });
+
+// ============================================
+// INIT COMMAND
+// ============================================
+program
+  .command('init')
+  .description('Initialize MemoryLink in current directory')
+  .action(async () => {
+    const opts = program.opts();
+    await initCommand({ verbose: opts.verbose });
+  });
+
+// ============================================
+// QUICKSTART COMMAND (Recommended by Qwen - reduces friction)
+// ============================================
+program
+  .command('quickstart')
+  .description('One-command setup: init + protect + hooks + AI config')
+  .option('-t, --tool <tool>', 'Primary AI tool (cursor, claude, chatgpt, copilot)', 'cursor')
+  .option('--skip-hooks', 'Skip Git hooks installation')
+  .action(async (cmdOpts: { tool?: string; skipHooks?: boolean }) => {
+    const opts = program.opts();
+    await quickstartCommand({ 
+      verbose: opts.verbose, 
+      tool: cmdOpts.tool,
+      skipHooks: cmdOpts.skipHooks,
+    });
+  });
+
+// ============================================
+// PROTECT COMMANDS
+// ============================================
+program
+  .command('protect <file>')
+  .description('Add a file to the protected list')
+  .option('-r, --reason <reason>', 'Reason for protection')
+  .action(async (file: string, cmdOpts: { reason?: string }) => {
+    const opts = program.opts();
+    await protectCommand(file, { verbose: opts.verbose, ...cmdOpts });
+  });
+
+program
+  .command('unprotect <file>')
+  .description('Remove a file from the protected list')
+  .action(async (file: string) => {
+    const opts = program.opts();
+    await unprotectCommand(file, { verbose: opts.verbose });
+  });
+
+program
+  .command('protected')
+  .description('List all protected files')
+  .action(async () => {
+    const opts = program.opts();
+    await listProtectedCommand({ verbose: opts.verbose });
+  });
+
+// ============================================
+// ROADMAP
+// ============================================
+program
+  .command('roadmap')
+  .description('Show launch roadmap and build thresholds (Tree-sitter, dashboard, VS Code)')
+  .action(async () => {
+    await roadmapCommand();
+  });
+
+// ============================================
+// VALIDATE COMMAND (v1.3 - Week 5: Memory Quality Validation)
+// ============================================
+program
+  .command('validate')
+  .description('Validate memory quality and generate quality report')
+  .option('--fix', 'Show fix suggestions (not yet implemented)')
+  .action(async (cmdOpts: { fix?: boolean }) => {
+    const opts = program.opts();
+    await validateCommand({ verbose: opts.verbose, fix: cmdOpts.fix || false });
+  });
+
+// ============================================
+// TEMPLATE COMMANDS (v1.3 - Week 6: Enhanced Auto-Capture)
+// ============================================
+const templateCmd = program
+  .command('template')
+  .description('Template management commands');
+
+templateCmd
+  .command('list')
+  .alias('ls')
+  .description('List all available templates')
+  .action(async () => {
+    const opts = program.opts();
+    await templateListCommand({ verbose: opts.verbose });
+  });
+
+templateCmd
+  .command('show <name>')
+  .alias('get')
+  .description('Show template details')
+  .action(async (name: string) => {
+    const opts = program.opts();
+    await templateShowCommand(name, { verbose: opts.verbose });
+  });
+
+templateCmd
+  .command('create <name>')
+  .description('Create a custom template')
+  .option('--description <desc>', 'Template description')
+  .option('--type <type>', 'Template type: memory or learning', 'memory')
+  .option('--fields <json>', 'Template fields as JSON string')
+  .action(async (name: string, cmdOpts: { description?: string; type?: string; fields?: string }) => {
+    const opts = program.opts();
+    await templateCreateCommand(name, {
+      verbose: opts.verbose,
+      description: cmdOpts.description,
+      type: cmdOpts.type as 'memory' | 'learning',
+      fields: cmdOpts.fields,
+    });
+  });
+
+templateCmd
+  .command('delete <name>')
+  .alias('rm')
+  .description('Delete a custom template')
+  .action(async (name: string) => {
+    const opts = program.opts();
+    await templateDeleteCommand(name, { verbose: opts.verbose });
+  });
+
+// ============================================
+// EXPORT COMMAND
+// ============================================
+program
+  .command('export')
+  .description('Export context to file or stdout')
+  .option('-o, --output <file>', 'Output file (defaults to stdout)')
+  .option('-f, --format <format>', 'Format: json or jsonl', 'json')
+  .option('-l, --limit <n>', 'Optional cap per section', '0')
+  .action(async (cmdOpts: { output?: string; format?: string; limit?: string }) => {
+    const opts = program.opts();
+    const limit = cmdOpts.limit ? parseInt(cmdOpts.limit, 10) : undefined;
+    await exportContextCommand(cmdOpts.output, { verbose: opts.verbose, format: cmdOpts.format as any, limit: limit === 0 ? undefined : limit });
+  });
+
+// ============================================
+// MEMORY COMMANDS
+// ============================================
+program
+  .command('memory <message>')
+  .description('Add an entry to the shared memory log (v1.5 Phase 2: add --scope for project scoping)')
+  .option('-t, --tags <tags>', 'Comma-separated tags')
+  .option('--type <type>', 'Entry type: note, decision, doc_ref, context, rule', 'note')
+  .option('-f, --force', 'Bypass secret detection (use with caution)')
+  .option('--scope <scope>', 'v1.5 Phase 2: Project scope (e.g., "frontend", "backend", "auth-module")')
+  .action(async (message: string, cmdOpts: { tags?: string; type?: string; force?: boolean; scope?: string }) => {
+    const opts = program.opts();
+    await memoryCommand(message, { 
+      verbose: opts.verbose, 
+      tags: cmdOpts.tags,
+      type: cmdOpts.type as any,
+      force: cmdOpts.force,
+      scope: cmdOpts.scope,
+    });
+  });
+
+program
+  .command('memories')
+  .description('List memory entries')
+  .option('-l, --limit <n>', 'Number of entries to show', '20')
+  .option('--tag <tag>', 'Filter by tag')
+  .option('--since <duration>', 'Filter by time (e.g., 7d, 2w, 1m)')
+  .option('--json', 'Output as JSON')
+  .action(async (cmdOpts: { limit?: string; tag?: string; since?: string; json?: boolean }) => {
+    const opts = program.opts();
+    await listMemoryCommand({ 
+      verbose: opts.verbose, 
+      limit: parseInt(cmdOpts.limit || '20', 10),
+      tag: cmdOpts.tag,
+      since: cmdOpts.since,
+      json: cmdOpts.json,
+    });
+  });
+
+// ============================================
+// SNIPPET COMMAND (Code Snippet Data Type)
+// ============================================
+program
+  .command('snippet <description>')
+  .description('Add a code snippet to memory')
+  .option('--code <code>', 'Code content (or use --file)')
+  .option('--file <path>', 'Read code from file')
+  .option('--lines <range>', 'Line range (e.g., "42" or "42-50")')
+  .option('--language <lang>', 'Programming language')
+  .option('--context <text>', 'Why this snippet is important')
+  .option('-t, --tags <tags>', 'Comma-separated tags')
+  .option('-f, --force', 'Bypass secret detection (use with caution)')
+  .action(async (description: string, cmdOpts: { code?: string; file?: string; lines?: string; language?: string; context?: string; tags?: string; force?: boolean }) => {
+    const opts = program.opts();
+    await snippetCommand(description, {
+      verbose: opts.verbose,
+      code: cmdOpts.code,
+      file: cmdOpts.file,
+      lines: cmdOpts.lines,
+      language: cmdOpts.language,
+      context: cmdOpts.context,
+      tags: cmdOpts.tags,
+      force: cmdOpts.force,
+    });
+  });
+
+// ============================================
+// CHANGE COMMANDS
+// ============================================
+program
+  .command('change <file> <reason>')
+  .description('Log a file change to the audit trail')
+  .option('-a, --agent <agent>', 'AI agent that made the change', 'user')
+  .option('--action <action>', 'Action type: created, edited, deleted, renamed', 'edited')
+  .option('-f, --force', 'Bypass secret detection (use with caution)')
+  .option('--justification <text>', 'Detailed justification for the change')
+  .option('--reviewed-by <name>', 'Person who reviewed the change')
+  .option('--tested <status>', 'Testing status/notes (e.g., "Yes - 42 tests pass")')
+  .option('--impact <description>', 'Human-readable impact description')
+  .action(async (file: string, reason: string, cmdOpts: { 
+    agent?: string; 
+    action?: string; 
+    force?: boolean;
+    justification?: string;
+    reviewedBy?: string;
+    tested?: string;
+    impact?: string;
+  }) => {
+    const opts = program.opts();
+    await changeCommand(file, reason, { 
+      verbose: opts.verbose, 
+      agent: cmdOpts.agent,
+      action: cmdOpts.action as any,
+      force: cmdOpts.force,
+      justification: cmdOpts.justification,
+      reviewedBy: cmdOpts.reviewedBy,
+      tested: cmdOpts.tested,
+      impact: cmdOpts.impact,
+    });
+  });
+
+program
+  .command('changes')
+  .description('List change entries')
+  .option('-l, --limit <n>', 'Number of entries to show', '20')
+  .option('--file <file>', 'Filter by file')
+  .option('--since <duration>', 'Filter by time (e.g., 7d, 2w, 1m)')
+  .option('--json', 'Output as JSON')
+  .action(async (cmdOpts: { limit?: string; file?: string; since?: string; json?: boolean }) => {
+    const opts = program.opts();
+    await listChangesCommand({ 
+      verbose: opts.verbose, 
+      limit: parseInt(cmdOpts.limit || '20', 10),
+      file: cmdOpts.file,
+      since: cmdOpts.since,
+      json: cmdOpts.json,
+    });
+  });
+
+// ============================================
+// LEARN COMMANDS
+// ============================================
+program
+  .command('learn <problem> <solution>')
+  .description('Track a solution attempt')
+  .requiredOption('-s, --status <status>', 'SUCCESS or FAILED')
+  .option('-t, --tags <tags>', 'Comma-separated tags')
+  .option('-r, --reason <reason>', 'Why it succeeded/failed')
+  .option('-f, --force', 'Bypass secret detection (use with caution)')
+  .action(async (problem: string, solution: string, cmdOpts: { status: string; tags?: string; reason?: string; force?: boolean }) => {
+    const opts = program.opts();
+    const status = cmdOpts.status.toUpperCase() as LearningStatus;
+    if (status !== 'SUCCESS' && status !== 'FAILED') {
+      console.error('\x1b[31m✗\x1b[0m Status must be SUCCESS or FAILED');
+      process.exit(1);
+    }
+    await learnCommand(problem, solution, { 
+      verbose: opts.verbose, 
+      status,
+      tags: cmdOpts.tags,
+      reason: cmdOpts.reason,
+      force: cmdOpts.force,
+    });
+  });
+
+program
+  .command('learnings')
+  .description('List learnings')
+  .option('-l, --limit <n>', 'Number of entries to show', '20')
+  .option('-s, --status <status>', 'Filter by SUCCESS or FAILED')
+  .option('--tag <tag>', 'Filter by tag')
+  .option('--since <duration>', 'Filter by time (e.g., 7d, 2w, 1m)')
+  .option('--json', 'Output as JSON')
+  .action(async (cmdOpts: { limit?: string; status?: string; tag?: string; since?: string; json?: boolean }) => {
+    const opts = program.opts();
+    await listLearningsCommand({ 
+      verbose: opts.verbose, 
+      limit: parseInt(cmdOpts.limit || '20', 10),
+      status: cmdOpts.status?.toUpperCase() as LearningStatus | undefined,
+      tag: cmdOpts.tag,
+      since: cmdOpts.since,
+      json: cmdOpts.json,
+    });
+  });
+
+// ============================================
+// WATCH COMMAND
+// ============================================
+program
+  .command('watch')
+  .description('Start file watcher for real-time protection and auto-logging')
+  .option('-i, --ignore <patterns...>', 'Additional patterns to ignore')
+  .option('--no-auto-log', 'Disable auto-logging to memory.log (default: enabled)')
+  .action(async (cmdOpts: { ignore?: string[]; autoLog?: boolean }) => {
+    const opts = program.opts();
+    await watchCommand({ 
+      verbose: opts.verbose, 
+      ignore: cmdOpts.ignore,
+      autoLog: cmdOpts.autoLog !== false // Default to true
+    });
+  });
+
+// ============================================
+// DETECT COMMAND
+// ============================================
+program
+  .command('detect')
+  .description('Auto-detect AI tools configured in the project')
+  .action(async () => {
+    const opts = program.opts();
+    const { detectCommand } = await import('./commands/detect.js');
+    await detectCommand({ verbose: opts.verbose });
+  });
+
+// ============================================
+// WATCH-PREFERENCES COMMAND
+// ============================================
+program
+  .command('watch-preferences')
+  .description('Watch for preference/rule changes and auto-reload AI tool configs')
+  .action(async () => {
+    const opts = program.opts();
+    const { watchPreferencesCommand } = await import('./commands/watch-preferences.js');
+    await watchPreferencesCommand({ verbose: opts.verbose });
+  });
+
+// ============================================
+// STATUS COMMAND
+// ============================================
+program
+  .command('status')
+  .description('Show MemoryLink status')
+  .action(async () => {
+    const opts = program.opts();
+    await statusCommand({ verbose: opts.verbose });
+  });
+
+// ============================================
+// DOCTOR COMMAND (includes secret scanning - All 7 AIs require)
+// ============================================
+program
+  .command('doctor')
+  .description('Run health checks, diagnostics, and security scanning (v1.4: add --preflight or --postflight for Buddy-Check)')
+  .option('--scan-secrets', 'Scan for potential secrets in logs (default: true)')
+  .option('--auto-fix', 'Show auto-fix suggestions for issues')
+  .option('--preflight', 'v1.4: Run preflight check before AI operations')
+  .option('--postflight', 'v1.4: Run postflight check after AI operations')
+  .option('--changed', 'v1.4: Only check changed files (for postflight)')
+  .option('--fix', 'v1.4: Auto-fix memory records (for postflight)')
+  .option('--json', 'v1.4: Output as JSON')
+  .option('--for <agent>', 'v1.4: Agent/user ID for preflight')
+  .option('--pr <number>', 'v1.4: PR number for preflight')
+  .option('--branch <branch>', 'v1.4: Branch name for preflight')
+  .action(async (cmdOpts: { 
+    scanSecrets?: boolean; 
+    autoFix?: boolean;
+    preflight?: boolean;
+    postflight?: boolean;
+    changed?: boolean;
+    fix?: boolean;
+    json?: boolean;
+    for?: string;
+    pr?: string;
+    branch?: string;
+  }) => {
+    const opts = program.opts();
+    await doctorCommand({ 
+      verbose: opts.verbose, 
+      scanSecrets: cmdOpts.scanSecrets !== false,
+      autoFix: cmdOpts.autoFix || false,
+      preflight: cmdOpts.preflight || false,
+      postflight: cmdOpts.postflight || false,
+      changed: cmdOpts.changed || false,
+      fix: cmdOpts.fix || false,
+      json: cmdOpts.json || false,
+      for: cmdOpts.for,
+      pr: cmdOpts.pr,
+      branch: cmdOpts.branch,
+    });
+  });
+
+// ============================================
+// CONFIGURE COMMAND
+// ============================================
+program
+  .command('configure')
+  .description('Interactive setup wizard')
+  .option('-q, --quick', 'Quick config with defaults')
+  .option('--ai-tools <tools>', 'AI tools (comma-separated)')
+  .option('--project-type <type>', 'Project type (node, react, python, general)')
+  .action(async (cmdOpts: { quick?: boolean; aiTools?: string; projectType?: string }) => {
+    const opts = program.opts();
+    if (cmdOpts.quick) {
+      await quickConfigureCommand({ 
+        verbose: opts.verbose, 
+        aiTools: cmdOpts.aiTools,
+        projectType: cmdOpts.projectType,
+      });
+    } else {
+      await configureCommand({ verbose: opts.verbose });
+    }
+  });
+
+// ============================================
+// GET-CONTEXT COMMAND
+// ============================================
+program
+  .command('get-context [tagOrFile]')
+  .description('Get filtered context for AI (v1.5 Phase 1: --smart, Phase 2: --scope)')
+  .option('-l, --limit <n>', 'Limit entries per section', '50')
+  .option('--since <date>', 'Filter by date (ISO format or relative: 7d, 2w, 1m)')
+  .option('--tag <tag>', 'Filter by tag')
+  .option('--smart', 'v1.5 Phase 1: Smart filtering with ranking (trust, recency, relevance)')
+  .option('--task <description>', 'v1.5 Phase 1: Task description for smart filtering')
+  .option('--scope <scope>', 'v1.5 Phase 2: Filter by project scope (e.g., "frontend", "backend")')
+  .action(async (tagOrFile: string | undefined, cmdOpts: { limit?: string; since?: string; tag?: string; smart?: boolean; task?: string; scope?: string }) => {
+    const opts = program.opts();
+    await getContextCommand(tagOrFile, { 
+      verbose: opts.verbose, 
+      limit: parseInt(cmdOpts.limit || '50', 10),
+      since: cmdOpts.since,
+      tag: cmdOpts.tag,
+      smart: cmdOpts.smart,
+      task: cmdOpts.task,
+      scope: cmdOpts.scope,
+    });
+  });
+
+// ============================================
+// INJECT COMMAND (1-click clipboard copy)
+// ============================================
+program
+  .command('inject')
+  .description('Copy context to clipboard for easy pasting (with OS notifications)')
+  .option('-l, --limit <n>', 'Limit entries', '20')
+  .option('--since <date>', 'Filter by date (7d, 2w, etc.)')
+  .option('--tag <tag>', 'Filter by tag')
+  .option('--type <type>', 'Filter by memory type')
+  .option('-r, --raw', 'Raw format without markdown')
+  .option('-q, --quick', 'Quick inject (minimal context)')
+  .option('--no-notify', 'Disable OS notifications')
+  .option('--auto', 'Auto mode: copy and exit silently')
+  .action(async (cmdOpts: { limit?: string; since?: string; tag?: string; type?: string; raw?: boolean; quick?: boolean; notify?: boolean; auto?: boolean }) => {
+    const opts = program.opts();
+    if (cmdOpts.quick) {
+      await quickInjectCommand({ verbose: opts.verbose, notify: cmdOpts.notify !== false });
+    } else {
+      await injectCommand({ 
+        verbose: opts.verbose, 
+        limit: parseInt(cmdOpts.limit || '20', 10),
+        since: cmdOpts.since,
+        tag: cmdOpts.tag,
+        type: cmdOpts.type as any,
+        raw: cmdOpts.raw,
+        notify: cmdOpts.notify !== false,
+        auto: cmdOpts.auto,
+      });
+    }
+  });
+
+// ============================================
+// SETUP COMMANDS (AI-specific)
+// ============================================
+const setup = program
+  .command('setup')
+  .description('Setup MemoryLink for specific AI tools');
+
+setup
+  .command('cursor')
+  .description('Create .cursorrules for Cursor AI')
+  .action(async () => {
+    const opts = program.opts();
+    await setupCursorCommand({ verbose: opts.verbose });
+  });
+
+setup
+  .command('claude')
+  .description('Create CLAUDE_INSTRUCTIONS.md')
+  .action(async () => {
+    const opts = program.opts();
+    await setupClaudeCommand({ verbose: opts.verbose });
+  });
+
+setup
+  .command('chatgpt')
+  .description('Create CHATGPT_INSTRUCTIONS.md')
+  .action(async () => {
+    const opts = program.opts();
+    await setupChatGPTCommand({ verbose: opts.verbose });
+  });
+
+setup
+  .command('copilot')
+  .description('Create .github/copilot-instructions.md')
+  .action(async () => {
+    const opts = program.opts();
+    await setupCopilotCommand({ verbose: opts.verbose });
+  });
+
+setup
+  .command('all')
+  .description('Setup for all AI tools')
+  .action(async () => {
+    const opts = program.opts();
+    await setupAllCommand({ verbose: opts.verbose });
+  });
+
+// ============================================
+// MCP SERVER COMMAND
+// ============================================
+program
+  .command('server')
+  .description('Start MCP server for Claude Desktop and Cursor integration')
+  .option('--stdio', 'Use stdio transport (default for Claude Desktop)', true)
+  .action(async () => {
+    await startMCPServer();
+  });
+
+// ============================================
+// MIGRATE COMMAND (v1.0 - Convert legacy text format to JSONL)
+// ============================================
+program
+  .command('migrate')
+  .description('Migrate logs to newer format (v1.0 or v1.4)')
+  .option('--to <version>', 'Target version: 1.0 or 1.4 (default: 1.0)', '1.0')
+  .option('--no-backup', 'Skip creating backup files')
+  .option('--dry-run', 'Preview migration without making changes')
+  .action(async (cmdOpts: { to?: string; backup?: boolean; dryRun?: boolean }) => {
+    const opts = program.opts();
+    await migrateCommand({ 
+      verbose: opts.verbose,
+      to: cmdOpts.to || '1.0',
+      backup: cmdOpts.backup !== false,
+      dryRun: cmdOpts.dryRun,
+    });
+  });
+
+// ============================================
+// INDEX COMMAND (v1.1 - Build vector index for semantic search)
+// ============================================
+program
+  .command('index')
+  .description('Build vector index for semantic search')
+  .option('--vector', 'Build vector index using embeddings')
+  .option('--local', 'Use local embeddings (offline, requires @xenova/transformers)')
+  .option('--rebuild', 'Rebuild existing index')
+  .action(async (cmdOpts: { vector?: boolean; local?: boolean; rebuild?: boolean }) => {
+    const opts = program.opts();
+    const { indexCommand } = await import('./commands/index-vector.js');
+    await indexCommand({
+      verbose: opts.verbose,
+      vector: cmdOpts.vector,
+      local: cmdOpts.local,
+      rebuild: cmdOpts.rebuild,
+    });
+  });
+
+// ============================================
+// SUGGEST-TAGS COMMAND (v1.1 - Tag Intelligence)
+// ============================================
+program
+  .command('suggest-tags <content>')
+  .description('Intelligently suggest tags based on content and existing tags')
+  .action(async (content: string) => {
+    const opts = program.opts();
+    const { suggestTagsCommand } = await import('./commands/suggest-tags.js');
+    await suggestTagsCommand(content, { verbose: opts.verbose });
+  });
+
+// ============================================
+// RESOLVE COMMAND (v1.1 - Conflict Resolution Helper)
+// ============================================
+program
+  .command('resolve')
+  .description('Detect and resolve Git merge conflicts in JSONL files')
+  .option('--file <file>', 'Resolve conflicts in specific file')
+  .option('--strategy <strategy>', 'Resolution strategy: ours, theirs, both, merge (default: merge)', 'merge')
+  .option('--interactive', 'Interactive conflict resolution (not implemented yet)')
+  .option('--list', 'List conflicts without resolving')
+  .action(async (cmdOpts: { file?: string; strategy?: string; interactive?: boolean; list?: boolean }) => {
+    const opts = program.opts();
+    const { resolveCommand } = await import('./commands/resolve.js');
+    await resolveCommand({
+      verbose: opts.verbose,
+      file: cmdOpts.file,
+      strategy: cmdOpts.strategy as 'ours' | 'theirs' | 'both' | 'merge',
+      interactive: cmdOpts.interactive,
+      list: cmdOpts.list,
+    });
+  });
+
+// ============================================
+// SEARCH COMMAND (v1.0 - Unified search across all logs)
+// ============================================
+program
+  .command('search <keyword>')
+  .description('Search across all logs by keyword (use --semantic for TF-IDF or --vector for embeddings)')
+  .option('--tag <tag>', 'Filter by tag')
+  .option('--since <duration>', 'Filter by time (e.g., 7d, 2w, 1m)')
+  .option('-l, --limit <n>', 'Maximum results to show', '50')
+  .option('-t, --type <type>', 'Log type: memory, learning, change, or all', 'all')
+  .option('--semantic', 'Use semantic search (TF-IDF + similarity) instead of keyword matching')
+  .option('--vector', 'Use vector search (embeddings) - requires index (memorylink index --vector)')
+  .option('--threshold <number>', 'Semantic similarity threshold (0-1, default 0.1 for semantic, 0.5 for vector)', parseFloat)
+  .option('--json', 'Output as JSON')
+  .action(async (keyword: string, cmdOpts: { tag?: string; since?: string; limit?: string; type?: string; semantic?: boolean; vector?: boolean; threshold?: number; json?: boolean }) => {
+    const opts = program.opts();
+    await searchCommand(keyword, {
+      verbose: opts.verbose,
+      tag: cmdOpts.tag,
+      since: cmdOpts.since,
+      limit: parseInt(cmdOpts.limit || '50', 10),
+      type: cmdOpts.type,
+      semantic: cmdOpts.semantic,
+      vector: cmdOpts.vector,
+      threshold: cmdOpts.threshold,
+      json: cmdOpts.json,
+    });
+  });
+
+// ============================================
+// SYNC COMMAND (Git sync for team collaboration)
+// ============================================
+program
+  .command('sync')
+  .description('Auto-stage, commit, and push .memorylink/ files to Git')
+  .option('--no-push', 'Commit without pushing to remote')
+  .option('--check', 'Check sync status (conflicts, behind/ahead)')
+  .option('-m, --message <message>', 'Custom commit message')
+  .option('--force', 'Force push (use with caution)')
+  .option('--batch', 'Enable batch commits (group multiple changes into one commit)')
+  .option('--batch-size <n>', 'Commit after N changes (default: 10)', parseInt)
+  .option('--batch-timeout <seconds>', 'Commit after N seconds (default: 300 = 5min)', parseInt)
+  .option('--force-commit', 'Force commit immediately (clear batch state)')
+  .action(async (cmdOpts: { noPush?: boolean; check?: boolean; message?: string; force?: boolean; batch?: boolean; batchSize?: number; batchTimeout?: number; forceCommit?: boolean }) => {
+    const opts = program.opts();
+    await syncCommand({
+      verbose: opts.verbose,
+      noPush: cmdOpts.noPush,
+      check: cmdOpts.check,
+      message: cmdOpts.message,
+      force: cmdOpts.force,
+      batch: cmdOpts.batch,
+      batchSize: cmdOpts.batchSize,
+      batchTimeout: cmdOpts.batchTimeout,
+      forceCommit: cmdOpts.forceCommit,
+    });
+  });
+
+// ============================================
+// CLEAR COMMAND
+// ============================================
+program
+  .command('clear <log>')
+  .description('Clear a specific log (memory, changes, learnings)')
+  .action(async (log: string) => {
+    const opts = program.opts();
+    switch (log.toLowerCase()) {
+      case 'memory':
+        await clearMemoryCommand({ verbose: opts.verbose });
+        break;
+      case 'changes':
+        await clearChangesCommand({ verbose: opts.verbose });
+        break;
+      case 'learnings':
+        await clearLearningsCommand({ verbose: opts.verbose });
+        break;
+      default:
+        console.error('\x1b[31m✗\x1b[0m Unknown log type. Use: memory, changes, or learnings');
+        process.exit(1);
+    }
+  });
+
+// ============================================
+// HOOKS COMMANDS
+// ============================================
+const hooks = program
+  .command('hooks')
+  .description('Manage Git hooks');
+
+hooks
+  .command('install')
+  .description('Install Git pre-commit hook for protection')
+  .action(async () => {
+    const opts = program.opts();
+    await hooksInstallCommand({ verbose: opts.verbose });
+  });
+
+hooks
+  .command('uninstall')
+  .description('Remove Git pre-commit hook')
+  .action(async () => {
+    const opts = program.opts();
+    await hooksUninstallCommand({ verbose: opts.verbose });
+  });
+
+hooks
+  .command('status')
+  .description('Show Git hooks status')
+  .action(async () => {
+    const opts = program.opts();
+    await hooksStatusCommand({ verbose: opts.verbose });
+  });
+
+// ============================================
+// AUTO-LOG COMMANDS (Auto-logging via Git hooks)
+// ============================================
+const autoLog = program
+  .command('auto-log')
+  .description('Auto-logging: Automatically log changes via Git hooks');
+
+autoLog
+  .command('install')
+  .description('Install Git post-commit hook for auto-logging')
+  .action(async () => {
+    const opts = program.opts();
+    await autoLogInstallCommand({ verbose: opts.verbose });
+  });
+
+autoLog
+  .command('uninstall')
+  .description('Remove Git post-commit hook for auto-logging')
+  .action(async () => {
+    const opts = program.opts();
+    await autoLogUninstallCommand({ verbose: opts.verbose });
+  });
+
+autoLog
+  .command('status')
+  .description('Show auto-logging hook status')
+  .action(async () => {
+    const opts = program.opts();
+    await autoLogStatusCommand({ verbose: opts.verbose });
+  });
+
+autoLog
+  .command('commit <commit> <message> <files>')
+  .description('Process commit and log changes (called from hook)')
+  .action(async (commit: string, message: string, files: string) => {
+    const opts = program.opts();
+    await autoLogCommitCommand({
+      verbose: opts.verbose,
+      commit,
+      message,
+      files,
+    });
+  });
+
+// ============================================
+// ARCHIVE COMMAND
+// ============================================
+program
+  .command('archive')
+  .description('Archive or expire old entries based on TTL or date filters')
+  .option('--before <date>', 'Archive entries before this date (ISO or relative like "30d", "6m")')
+  .option('--ttl <duration>', 'Time-to-live (e.g., "90d", "1y")')
+  .option('--dry-run', 'Show what would be archived without actually archiving')
+  .option('--status <status>', 'Status to set archived entries to (DEPRECATED or DELETED)', 'DEPRECATED')
+  .action(async (options: any) => {
+    const opts = program.opts();
+    const { archiveCommand } = await import('./commands/archive.js');
+    await archiveCommand({
+      verbose: opts.verbose,
+      before: options.before,
+      ttl: options.ttl,
+      dryRun: options.dryRun,
+      status: options.status,
+    });
+  });
+
+// ============================================
+// CONSOLIDATE COMMAND
+// ============================================
+program
+  .command('consolidate')
+  .description('Merge duplicate or similar memory entries')
+  .option('--threshold <number>', 'Similarity threshold (0-1, default 0.8)', parseFloat)
+  .option('--dry-run', 'Show what would be consolidated without actually doing it')
+  .option('--auto-merge', 'Automatically merge without confirmation')
+  .action(async (options: any) => {
+    const opts = program.opts();
+    const { consolidateCommand } = await import('./commands/consolidate.js');
+    await consolidateCommand({
+      verbose: opts.verbose,
+      threshold: options.threshold,
+      dryRun: options.dryRun,
+      autoMerge: options.autoMerge,
+    });
+  });
+
+// ============================================
+// SYNC-RULES COMMAND (P0: Memory Usage Fix)
+// ============================================
+program
+  .command('sync-rules')
+  .description('Generate .memorylink/rules.md from memory.log (type=rule|preference, status=ACTIVE)')
+  .action(async () => {
+    const opts = program.opts();
+    await syncRulesCommand({ verbose: opts.verbose });
+  });
+
+// ============================================
+// AUTO-CONTEXT COMMAND (DeepSeek's Path C)
+// ============================================
+const autoContext = program
+  .command('auto-context')
+  .description('Enable/disable automatic context injection for AI tools');
+
+autoContext
+  .command('enable')
+  .description('Enable auto-context mode (auto-sync rules on memory changes)')
+  .action(async () => {
+    const opts = program.opts();
+    const { autoContextEnableCommand } = await import('./commands/auto-context.js');
+    await autoContextEnableCommand({ verbose: opts.verbose });
+  });
+
+autoContext
+  .command('disable')
+  .description('Disable auto-context mode')
+  .action(async () => {
+    const opts = program.opts();
+    const { autoContextDisableCommand } = await import('./commands/auto-context.js');
+    await autoContextDisableCommand({ verbose: opts.verbose });
+  });
+
+autoContext
+  .command('status')
+  .description('Check auto-context mode status')
+  .action(async () => {
+    const opts = program.opts();
+    const { autoContextStatusCommand } = await import('./commands/auto-context.js');
+    await autoContextStatusCommand({ verbose: opts.verbose });
+  });
+
+// ============================================
+// GRAPH COMMAND (v1.2 - Code Structure Memory)
+// ============================================
+const graphCommand = program
+  .command('graph')
+  .description('Code structure memory commands');
+
+graphCommand
+  .command('build')
+  .description('Build code dependency graph')
+  .option('--rebuild', 'Force rebuild even if graph exists')
+  .option('--silent', 'Suppress output')
+  .action(async (cmdOpts: { rebuild?: boolean; silent?: boolean }) => {
+    const opts = program.opts();
+    const { graphBuildCommand } = await import('./commands/graph.js');
+    await graphBuildCommand({
+      verbose: opts.verbose,
+      rebuild: cmdOpts.rebuild,
+      silent: cmdOpts.silent,
+    });
+  });
+
+program
+  .command('graph-query <file>')
+  .description('Query file dependencies and structure')
+  .option('--visual', 'Show visual tree output')
+  .action(async (file: string, cmdOpts: { visual?: boolean }) => {
+    const opts = program.opts();
+    const { graphQueryCommand } = await import('./commands/graph.js');
+    await graphQueryCommand(file, { verbose: opts.verbose, visual: cmdOpts.visual });
+  });
+
+// ============================================
+// IMPACT COMMAND (v1.2 - Change Impact Analysis)
+// ============================================
+program
+  .command('impact <file>')
+  .description('Analyze change impact for a file')
+  .option('--change <description>', 'Description of proposed change')
+  .option('--rebuild', 'Rebuild graph before analysis')
+  .action(async (file: string, cmdOpts: { change?: string; rebuild?: boolean }) => {
+    const opts = program.opts();
+    const { impactCommand } = await import('./commands/impact.js');
+    await impactCommand(file, {
+      verbose: opts.verbose,
+      change: cmdOpts.change,
+      rebuild: cmdOpts.rebuild,
+    });
+  });
+
+// ============================================
+// PATTERNS COMMAND (v1.3 - Team Pattern Detection)
+// ============================================
+const patternsCommand = program
+  .command('patterns')
+  .description('Team pattern detection commands');
+
+patternsCommand
+  .command('detect')
+  .description('Detect team coding patterns from learnings')
+  .action(async () => {
+    const opts = program.opts();
+    const { patternsDetectCommand } = await import('./commands/patterns.js');
+    await patternsDetectCommand({ verbose: opts.verbose });
+  });
+
+program
+  .command('patterns-suggest <context>')
+  .description('Suggest team patterns for a given context')
+  .action(async (context: string) => {
+    const opts = program.opts();
+    const { patternsSuggestCommand } = await import('./commands/patterns.js');
+    await patternsSuggestCommand(context, { verbose: opts.verbose });
+  });
+
+// ============================================
+// CHECKPOINT COMMANDS (v1.5)
+// ============================================
+program
+  .command('checkpoint')
+  .description('Create, list, compare, or restore memory checkpoints (v1.5)')
+  .argument('[action]', 'Action: create, list, diff, or restore (default: list)', 'list')
+  .argument('[checkpoint1]', 'First checkpoint for diff, or checkpoint name for restore')
+  .argument('[checkpoint2]', 'Second checkpoint for diff')
+  .option('--name <name>', 'Checkpoint name (for create)')
+  .option('--message <message>', 'Checkpoint message (for create)')
+  .action(async (action: string, checkpoint1?: string, checkpoint2?: string, cmdOpts?: { name?: string; message?: string }) => {
+    const opts = program.opts();
+    const { error } = await import('./utils.js');
+    if (action === 'create') {
+      await checkpointCreateCommand({ 
+        verbose: opts.verbose,
+        name: cmdOpts?.name,
+        message: cmdOpts?.message,
+      });
+    } else if (action === 'list') {
+      await checkpointListCommand({ verbose: opts.verbose });
+    } else if (action === 'diff') {
+      if (!checkpoint1 || !checkpoint2) {
+        error('Both checkpoint names required for diff');
+        process.exit(1);
+      }
+      await checkpointDiffCommand(checkpoint1, checkpoint2, { verbose: opts.verbose });
+    } else if (action === 'restore') {
+      if (!checkpoint1) {
+        error('Checkpoint name required for restore');
+        process.exit(1);
+      }
+      await checkpointRestoreCommand(checkpoint1, { verbose: opts.verbose });
+    } else {
+      error(`Unknown action: ${action}. Use: create, list, diff, or restore`);
+      process.exit(1);
+    }
+  });
+
+// ============================================
+// LOCK COMMANDS (v1.5)
+// ============================================
+program
+  .command('lock')
+  .description('Agent locking commands (v1.5)')
+  .argument('[action]', 'Action: acquire, release, renew, or status (default: status)', 'status')
+  .option('--agent <id>', 'Agent ID (for acquire)')
+  .option('--files <files>', 'Comma-separated list of files (for acquire)')
+  .option('--timeout <minutes>', 'Lock timeout in minutes (default: 30)', '30')
+  .action(async (action: string, cmdOpts?: { agent?: string; files?: string; timeout?: string }) => {
+    const opts = program.opts();
+    const { error } = await import('./utils.js');
+    const timeout = cmdOpts?.timeout ? parseInt(cmdOpts.timeout, 10) : undefined;
+    if (action === 'acquire') {
+      await lockAcquireCommand({ 
+        verbose: opts.verbose,
+        agent: cmdOpts?.agent,
+        files: cmdOpts?.files,
+        timeout,
+      });
+    } else if (action === 'release') {
+      await lockReleaseCommand({ verbose: opts.verbose });
+    } else if (action === 'renew') {
+      await lockRenewCommand({ 
+        verbose: opts.verbose,
+        timeout,
+      });
+    } else if (action === 'status') {
+      await lockStatusCommand({ verbose: opts.verbose });
+    } else {
+      error(`Unknown action: ${action}. Use: acquire, release, renew, or status`);
+      process.exit(1);
+    }
+  });
+
+// ============================================
+// SCOPES COMMAND (v1.5 Phase 2 Enhancement)
+// ============================================
+program
+  .command('scopes')
+  .description('List and manage project scopes (v1.5 Phase 2)')
+  .argument('[action]', 'Action: list (default: list)', 'list')
+  .action(async (action: string) => {
+    const opts = program.opts();
+    if (action === 'list') {
+      await scopesListCommand({ verbose: opts.verbose });
+    } else {
+      const { error } = await import('./utils.js');
+      error(`Unknown action: ${action}. Use: list`);
+      process.exit(1);
+    }
+  });
+
+// ============================================
+// STATS COMMAND (v1.5 Phase 2)
+// ============================================
+program
+  .command('stats')
+  .description('Enhanced observability: statistics and analytics (v1.5 Phase 2)')
+  .option('--since <duration>', 'Filter by time: 7d, 2w, 1m')
+  .option('--format <format>', 'Output format: default, json, csv, markdown', 'default')
+  .option('--no-recommendations', 'Skip recommendations in output (v1.5.1)')
+  .action(async (cmdOpts?: { since?: string; format?: string; noRecommendations?: boolean }) => {
+    const opts = program.opts();
+    await statsCommand({
+      verbose: opts.verbose,
+      since: cmdOpts?.since,
+      format: cmdOpts?.format as any,
+      noRecommendations: cmdOpts?.noRecommendations || false,
+    });
+  });
+
+// ============================================
+// TELEMETRY TEST COMMAND (v1.6 - Internal/Debug Only)
+// ============================================
+program
+  .command('telemetry-test')
+  .description('INTERNAL: Trigger a test telemetry event (v1.6+)')
+  .option('--outcome <outcome>', 'Outcome: success or error', 'success')
+  .option('--error-kind <kind>', 'Error kind if outcome is error', 'TEST_ERROR')
+  .action(async (cmdOpts: { outcome: 'success' | 'error'; errorKind: string }) => {
+    const opts = program.opts();
+    await telemetryTestCommand({ verbose: opts.verbose });
+  });
+
+// Hide the telemetry-test command from the main help output
+// This is a workaround as Commander.js doesn't have a direct 'hidden' option for commands
+const telemetryTestCommandObj = program.commands.find(cmd => cmd.name() === 'telemetry-test');
+if (telemetryTestCommandObj) {
+  telemetryTestCommandObj.helpOption(false); // Hide help option for this command
+  // Further hiding might involve custom help output or not adding it to program.commands directly
+  // For now, this makes it less discoverable.
+}
+
+// ============================================
+// HELP COMMAND (enhanced)
+// ============================================
+program
+  .command('help')
+  .description('Show help with examples')
+  .action(() => {
+    console.log(LOGO);
+    console.log('\x1b[1mQuick Start:\x1b[0m');
+    console.log('  memorylink init                          # Initialize in project');
+    console.log('  memorylink protect src/config.ts         # Protect a file');
+    console.log('  memorylink memory "Uses React 18"        # Add context');
+    console.log('  memorylink watch                         # Start watcher');
+    console.log('');
+    console.log('\x1b[1mCore Commands:\x1b[0m');
+    console.log('  init                  Initialize .memorylink/ directory');
+    console.log('  protect <file>        Add file to protected list');
+    console.log('  unprotect <file>      Remove file from protected list');
+    console.log('  protected             List protected files');
+    console.log('  memory <message>      Add to shared memory');
+    console.log('  memories              List memory entries');
+    console.log('  change <file> <why>   Log a file change');
+    console.log('  changes               List change audit trail');
+    console.log('  learn <prob> <sol>    Track solution (--status SUCCESS|FAILED)');
+    console.log('  learnings             List learnings');
+    console.log('  watch                 Start real-time watcher');
+    console.log('  status                Show current state');
+    console.log('  doctor                Health check');
+    console.log('  get-context [tag]     Get filtered context for AI');
+    console.log('  search <keyword>      Search across all logs');
+    console.log('  export [file]         Export all data');
+    console.log('  clear <log>           Clear a log file');
+    console.log('  hooks install         Install Git protection hook');
+    console.log('  migrate               Convert legacy logs to JSONL (v1.0)');
+    console.log('');
+    console.log('\x1b[1mExamples:\x1b[0m');
+    console.log('  memorylink memory "Auth uses JWT tokens" --tags auth,security');
+    console.log('  memorylink learn "API timeout" "Increased to 30s" --status SUCCESS');
+    console.log('  memorylink get-context auth');
+    console.log('  memorylink change src/api.ts "Fixed auth bug" --agent cursor');
+    console.log('');
+    console.log('\x1b[1mFor AI Assistants:\x1b[0m');
+    console.log('  Read .memorylink/protected.txt before editing any file');
+    console.log('  Read .memorylink/memory.log for project context');
+    console.log('  Check .memorylink/learnings.log for past solutions');
+    console.log('  Log your changes to .memorylink/changes.log');
+    console.log('');
+    console.log('\x1b[36mDocs: https://github.com/memorylink/memorylink\x1b[0m');
+    console.log('');
+  });
+
+// Default action (no command)
+program.action(() => {
+  console.log(LOGO);
+  program.help();
+});
+
+// Parse and run
+program.parse(process.argv);
+