@contextos/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,1350 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command as Command14 } from "commander";
+
+// src/commands/init.ts
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import inquirer from "inquirer";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import { stringify } from "yaml";
+import {
+  detectProjectType
+} from "@contextos/core";
+var CONTEXTOS_DIR = ".contextos";
+var initCommand = new Command("init").description("Initialize ContextOS in the current directory").option("-t, --template <name>", "Use a community template").option("-y, --yes", "Skip interactive prompts").option("-f, --force", "Overwrite existing configuration").action(async (options) => {
+  const cwd = process.cwd();
+  const contextosPath = join(cwd, CONTEXTOS_DIR);
+  if (existsSync(contextosPath) && !options.force) {
+    console.log(chalk.yellow("\u26A0\uFE0F  ContextOS is already initialized in this directory."));
+    console.log(chalk.gray("   Use --force to reinitialize.\n"));
+    return;
+  }
+  console.log(chalk.blue.bold("\n\u{1F680} Initializing ContextOS...\n"));
+  const spinner = ora("Detecting project type...").start();
+  const detected = await detectProjectType(cwd);
+  spinner.succeed(`Detected: ${chalk.cyan(detected.language)}${detected.framework ? ` / ${chalk.cyan(detected.framework)}` : ""}`);
+  let projectName = cwd.split(/[\\/]/).pop() || "my-project";
+  let description = "";
+  if (!options.yes) {
+    const answers = await inquirer.prompt([
+      {
+        type: "input",
+        name: "projectName",
+        message: "Project name:",
+        default: projectName
+      },
+      {
+        type: "input",
+        name: "description",
+        message: "Project description (optional):"
+      },
+      {
+        type: "confirm",
+        name: "proceed",
+        message: "Create .contextos folder?",
+        default: true
+      }
+    ]);
+    if (!answers.proceed) {
+      console.log(chalk.yellow("\nInitialization cancelled."));
+      return;
+    }
+    projectName = answers.projectName;
+    description = answers.description;
+  }
+  const createSpinner = ora("Creating .contextos folder...").start();
+  try {
+    mkdirSync(contextosPath, { recursive: true });
+    mkdirSync(join(contextosPath, "db"), { recursive: true });
+    mkdirSync(join(contextosPath, "rules"), { recursive: true });
+    const contextYaml = {
+      version: "3.1",
+      project: {
+        name: projectName,
+        language: detected.language,
+        framework: detected.framework,
+        description: description || void 0
+      },
+      stack: {},
+      constraints: [
+        {
+          rule: "Follow project coding conventions",
+          severity: "warning"
+        }
+      ],
+      boundaries: [],
+      meta: {
+        last_indexed: (/* @__PURE__ */ new Date()).toISOString(),
+        index_version: "3.1"
+      }
+    };
+    writeFileSync(
+      join(contextosPath, "context.yaml"),
+      stringify(contextYaml, { indent: 2 }),
+      "utf-8"
+    );
+    const configYaml = {
+      indexing: {
+        watch_mode: true,
+        ignore_patterns: [
+          "**/*.test.ts",
+          "**/*.spec.ts",
+          "node_modules/**",
+          "dist/**",
+          ".git/**"
+        ],
+        file_size_limit: "1MB"
+      },
+      graph: {
+        max_depth: 2,
+        follow_types: ["import", "require", "export"],
+        include_types: true
+      },
+      embedding: {
+        strategy: "adaptive",
+        provider: "local",
+        model: "all-MiniLM-L6-v2",
+        chunk_size: 512,
+        overlap: 50
+      },
+      budgeting: {
+        strategy: "adaptive"
+      }
+    };
+    writeFileSync(
+      join(contextosPath, "config.yaml"),
+      stringify(configYaml, { indent: 2 }),
+      "utf-8"
+    );
+    const codingRules = `# Coding Rules
+
+## General Guidelines
+
+- Follow the established patterns in this codebase
+- Write clean, readable code
+- Add comments for complex logic
+
+## Architecture
+
+- Separate concerns appropriately
+- Use dependency injection where applicable
+
+## Testing
+
+- Write tests for new functionality
+- Maintain test coverage
+`;
+    writeFileSync(
+      join(contextosPath, "rules", "coding.md"),
+      codingRules,
+      "utf-8"
+    );
+    createSpinner.succeed("Created .contextos folder");
+    console.log(chalk.green.bold("\n\u2705 ContextOS initialized successfully!\n"));
+    console.log(chalk.gray("Created:"));
+    console.log(chalk.gray("  .contextos/context.yaml    - Project configuration"));
+    console.log(chalk.gray("  .contextos/config.yaml     - Tool settings"));
+    console.log(chalk.gray("  .contextos/rules/coding.md - Coding guidelines"));
+    console.log();
+    console.log(chalk.blue("Next steps:"));
+    console.log(chalk.white("  1. Edit .contextos/context.yaml to customize your project"));
+    console.log(chalk.white('  2. Run "ctx index" to build the initial index'));
+    console.log(chalk.white('  3. Run "ctx goal <description>" to build context\n'));
+  } catch (error) {
+    createSpinner.fail("Failed to create .contextos folder");
+    console.error(chalk.red("Error:"), error);
+    process.exit(1);
+  }
+});
+
+// src/commands/index.ts
+import { Command as Command2 } from "commander";
+import chalk2 from "chalk";
+import ora2 from "ora";
+import { getContextBuilder } from "@contextos/core";
+var indexCommand = new Command2("index").description("Index the project for context building").option("-w, --watch", "Watch mode for incremental updates").option("-f, --force", "Force full reindex").option("-s, --stats", "Show indexing statistics").action(async (options) => {
+  console.log(chalk2.blue.bold("\n\u{1F4CA} Indexing project...\n"));
+  const spinner = ora2("Initializing...").start();
+  try {
+    const builder = await getContextBuilder();
+    spinner.text = "Indexing files...";
+    const result = await builder.index(options.force);
+    spinner.succeed("Indexing complete");
+    console.log();
+    console.log(chalk2.gray("Results:"));
+    console.log(chalk2.white(`  \u{1F4C1} Files indexed: ${chalk2.cyan(result.filesIndexed)}`));
+    console.log(chalk2.white(`  \u{1F4DD} Chunks created: ${chalk2.cyan(result.chunksCreated)}`));
+    console.log(chalk2.white(`  \u23F1\uFE0F  Time: ${chalk2.cyan(result.timeMs + "ms")}`));
+    if (options.stats) {
+      const stats = builder.getStats();
+      if (stats) {
+        console.log();
+        console.log(chalk2.gray("Graph Statistics:"));
+        console.log(chalk2.white(`  Nodes: ${stats.graph.nodeCount}`));
+        console.log(chalk2.white(`  Edges: ${stats.graph.edgeCount}`));
+        console.log(chalk2.white(`  Avg imports: ${stats.graph.avgImports}`));
+        console.log();
+        console.log(chalk2.gray("Vector Statistics:"));
+        console.log(chalk2.white(`  Chunks: ${stats.vectors.chunkCount}`));
+        console.log(chalk2.white(`  Files: ${stats.vectors.fileCount}`));
+        console.log(chalk2.white(`  Embedded: ${stats.vectors.embeddedCount}`));
+      }
+    }
+    console.log();
+    console.log(chalk2.green('\u2705 Index ready. Run "ctx goal <description>" to build context.\n'));
+    if (options.watch) {
+      console.log(chalk2.blue("\u{1F440} Watching for file changes... (Ctrl+C to stop)\n"));
+      process.on("SIGINT", () => {
+        console.log(chalk2.yellow("\nWatch mode stopped."));
+        process.exit(0);
+      });
+    }
+  } catch (error) {
+    spinner.fail("Indexing failed");
+    if (error instanceof Error && error.message.includes("not initialized")) {
+      console.log(chalk2.yellow('\nRun "ctx init" first to initialize ContextOS.\n'));
+    } else {
+      console.error(chalk2.red("Error:"), error);
+    }
+    process.exit(1);
+  }
+});
+
+// src/commands/build.ts
+import { Command as Command3 } from "commander";
+import chalk3 from "chalk";
+import ora3 from "ora";
+import { getContextBuilder as getContextBuilder2 } from "@contextos/core";
+var buildCommand = new Command3("build").description("Build context (infers goal from git diff)").option("-m, --max-tokens <number>", "Maximum tokens for context", "32000").option("-f, --file <path>", "Target file for context").option("--no-rules", "Exclude coding rules from context").action(async (options) => {
+  console.log(chalk3.blue.bold("\n\u{1F528} Building context...\n"));
+  const spinner = ora3("Analyzing project...").start();
+  try {
+    const builder = await getContextBuilder2();
+    spinner.text = "Inferring goal from git diff...";
+    const result = await builder.build({
+      maxTokens: parseInt(options.maxTokens),
+      targetFile: options.file,
+      includeRules: options.rules
+    });
+    spinner.succeed("Context built");
+    console.log();
+    console.log(chalk3.gray("Goal: ") + chalk3.white(result.goal));
+    console.log();
+    console.log(chalk3.gray("Included Files:"));
+    for (const file of result.files.slice(0, 10)) {
+      const scoreStr = (file.score.final * 100).toFixed(0) + "%";
+      console.log(chalk3.white(`  \u{1F4C4} ${file.path} ${chalk3.gray(`(${scoreStr} - ${file.reason})`)}`));
+    }
+    if (result.files.length > 10) {
+      console.log(chalk3.gray(`  ... and ${result.files.length - 10} more files`));
+    }
+    console.log();
+    console.log(chalk3.gray("Statistics:"));
+    console.log(chalk3.white(`  \u{1F4CA} Token count: ${chalk3.cyan(result.tokenCount.toLocaleString())}`));
+    console.log(chalk3.white(`  \u{1F4B0} Token savings: ${chalk3.green(result.savings.percentage + "%")}`));
+    console.log(chalk3.white(`  \u23F1\uFE0F  Build time: ${chalk3.cyan(result.meta.buildTime + "ms")}`));
+    console.log();
+    console.log(chalk3.green('\u2705 Context ready. Run "ctx copy" to copy to clipboard.\n'));
+  } catch (error) {
+    spinner.fail("Build failed");
+    if (error instanceof Error && error.message.includes("not initialized")) {
+      console.log(chalk3.yellow('\nRun "ctx init" first to initialize ContextOS.\n'));
+    } else {
+      console.error(chalk3.red("Error:"), error);
+    }
+    process.exit(1);
+  }
+});
+
+// src/commands/goal.ts
+import { Command as Command4 } from "commander";
+import chalk4 from "chalk";
+import ora4 from "ora";
+import { getContextBuilder as getContextBuilder3 } from "@contextos/core";
+var goalCommand = new Command4("goal").description("Set explicit goal and build context").argument("<description>", "Goal description").option("-m, --max-tokens <number>", "Maximum tokens for context", "32000").option("-f, --file <path>", "Target file for context").option("--no-rules", "Exclude coding rules from context").option("-c, --copy", "Copy to clipboard after building").action(async (description, options) => {
+  console.log(chalk4.blue.bold("\n\u{1F3AF} Building context for goal...\n"));
+  console.log(chalk4.gray("Goal: ") + chalk4.white(description));
+  console.log();
+  const spinner = ora4("Analyzing relevance...").start();
+  try {
+    const builder = await getContextBuilder3();
+    spinner.text = "Ranking files...";
+    const result = await builder.build({
+      goal: description,
+      maxTokens: parseInt(options.maxTokens),
+      targetFile: options.file,
+      includeRules: options.rules
+    });
+    spinner.succeed("Context built");
+    console.log();
+    console.log(chalk4.gray("Top Relevant Files:"));
+    for (const file of result.files.slice(0, 8)) {
+      const scoreStr = (file.score.final * 100).toFixed(0) + "%";
+      console.log(chalk4.white(`  \u{1F4C4} ${file.path}`));
+      console.log(chalk4.gray(`     Score: ${scoreStr} | ${file.reason}`));
+    }
+    if (result.rules.length > 0) {
+      console.log();
+      console.log(chalk4.gray("Applied Rules:"));
+      for (const rule of result.rules.slice(0, 3)) {
+        const icon = rule.severity === "error" ? "\u{1F6AB}" : "\u26A0\uFE0F";
+        console.log(chalk4.white(`  ${icon} ${rule.rule}`));
+      }
+    }
+    console.log();
+    console.log(chalk4.gray("Summary:"));
+    console.log(chalk4.white(`  \u{1F4CA} Tokens: ${chalk4.cyan(result.tokenCount.toLocaleString())} / ${options.maxTokens}`));
+    console.log(chalk4.white(`  \u{1F4C1} Files: ${chalk4.cyan(result.files.length)} included`));
+    console.log(chalk4.white(`  \u{1F4B0} Savings: ${chalk4.green(result.savings.percentage + "%")} token reduction`));
+    if (options.copy) {
+      const { default: clipboardy } = await import("clipboardy");
+      const formatted = builder.formatForLLM(result);
+      await clipboardy.write(formatted);
+      console.log();
+      console.log(chalk4.green("\u{1F4CB} Copied to clipboard!"));
+    }
+    console.log();
+    if (!options.copy) {
+      console.log(chalk4.blue('Run "ctx copy" to copy to clipboard, or "ctx preview" for details.\n'));
+    }
+  } catch (error) {
+    spinner.fail("Goal building failed");
+    if (error instanceof Error && error.message.includes("not initialized")) {
+      console.log(chalk4.yellow('\nRun "ctx init" first to initialize ContextOS.\n'));
+    } else {
+      console.error(chalk4.red("Error:"), error);
+    }
+    process.exit(1);
+  }
+});
+
+// src/commands/preview.ts
+import { Command as Command5 } from "commander";
+import chalk5 from "chalk";
+import ora5 from "ora";
+import { getContextBuilder as getContextBuilder4 } from "@contextos/core";
+var previewCommand = new Command5("preview").description("Preview context without copying").option("-g, --goal <description>", "Override goal for preview").option("-m, --max-tokens <number>", "Maximum tokens", "32000").action(async (options) => {
+  console.log(chalk5.blue.bold("\n\u{1F441}\uFE0F  Context Preview\n"));
+  const spinner = ora5("Loading context...").start();
+  try {
+    const builder = await getContextBuilder4();
+    const result = await builder.build({
+      goal: options.goal,
+      maxTokens: parseInt(options.maxTokens)
+    });
+    spinner.stop();
+    console.log(chalk5.gray("\u250C" + "\u2500".repeat(68) + "\u2510"));
+    console.log(chalk5.gray("\u2502") + ` ${chalk5.white.bold("Context Summary")}`.padEnd(77) + chalk5.gray("\u2502"));
+    console.log(chalk5.gray("\u251C" + "\u2500".repeat(68) + "\u2524"));
+    const goalLine = ` Goal: ${result.goal}`;
+    console.log(chalk5.gray("\u2502") + chalk5.white(goalLine.substring(0, 68).padEnd(68)) + chalk5.gray("\u2502"));
+    console.log(chalk5.gray("\u251C" + "\u2500".repeat(68) + "\u2524"));
+    const tokenBudget = parseInt(options.maxTokens);
+    const usedPercent = Math.round(result.tokenCount / tokenBudget * 100);
+    const barLength = 40;
+    const filledLength = Math.round(usedPercent / 100 * barLength);
+    const bar = "\u2588".repeat(filledLength) + "\u2591".repeat(barLength - filledLength);
+    console.log(chalk5.gray("\u2502") + ` Tokens: ${result.tokenCount.toLocaleString()} / ${tokenBudget.toLocaleString()}`.padEnd(68) + chalk5.gray("\u2502"));
+    console.log(chalk5.gray("\u2502") + ` [${bar}] ${usedPercent}%`.padEnd(68) + chalk5.gray("\u2502"));
+    console.log(chalk5.gray("\u251C" + "\u2500".repeat(68) + "\u2524"));
+    console.log(chalk5.gray("\u2502") + chalk5.white.bold(" \u{1F4C1} Included Files (" + result.files.length + ")").padEnd(77) + chalk5.gray("\u2502"));
+    console.log(chalk5.gray("\u2502") + " ".repeat(68) + chalk5.gray("\u2502"));
+    for (const file of result.files.slice(0, 6)) {
+      const score = (file.score.final * 100).toFixed(0);
+      const line = `   ${file.path}`;
+      const scorePart = ` ${score}%`;
+      const paddedLine = line.substring(0, 58).padEnd(58) + chalk5.gray(scorePart);
+      console.log(chalk5.gray("\u2502") + paddedLine.padEnd(77) + chalk5.gray("\u2502"));
+    }
+    if (result.files.length > 6) {
+      console.log(chalk5.gray("\u2502") + chalk5.gray(`   ... and ${result.files.length - 6} more files`).padEnd(68) + chalk5.gray("\u2502"));
+    }
+    console.log(chalk5.gray("\u251C" + "\u2500".repeat(68) + "\u2524"));
+    if (result.rules.length > 0) {
+      console.log(chalk5.gray("\u2502") + chalk5.white.bold(" \u{1F4CB} Active Rules (" + result.rules.length + ")").padEnd(77) + chalk5.gray("\u2502"));
+      for (const rule of result.rules.slice(0, 3)) {
+        const icon = rule.severity === "error" ? "\u{1F6AB}" : "\u26A0\uFE0F";
+        const line = `   ${icon} ${rule.rule}`;
+        console.log(chalk5.gray("\u2502") + line.substring(0, 68).padEnd(68) + chalk5.gray("\u2502"));
+      }
+      console.log(chalk5.gray("\u251C" + "\u2500".repeat(68) + "\u2524"));
+    }
+    console.log(chalk5.gray("\u2502") + chalk5.green.bold(` \u{1F4B0} Token Savings: ${result.savings.percentage}%`).padEnd(77) + chalk5.gray("\u2502"));
+    console.log(chalk5.gray("\u2502") + chalk5.gray(`    Original: ${result.savings.original.toLocaleString()} \u2192 Optimized: ${result.savings.optimized.toLocaleString()}`).padEnd(68) + chalk5.gray("\u2502"));
+    console.log(chalk5.gray("\u2514" + "\u2500".repeat(68) + "\u2518"));
+    console.log();
+    console.log(chalk5.blue('Run "ctx copy" to copy this context to clipboard.\n'));
+  } catch (error) {
+    spinner.fail("Preview failed");
+    if (error instanceof Error && error.message.includes("not initialized")) {
+      console.log(chalk5.yellow('\nRun "ctx init" first to initialize ContextOS.\n'));
+    } else {
+      console.error(chalk5.red("Error:"), error);
+    }
+    process.exit(1);
+  }
+});
+
+// src/commands/copy.ts
+import { Command as Command6 } from "commander";
+import chalk6 from "chalk";
+import ora6 from "ora";
+import { getContextBuilder as getContextBuilder5 } from "@contextos/core";
+var copyCommand = new Command6("copy").description("Copy built context to clipboard").option("-g, --goal <description>", "Goal for context").option("-m, --max-tokens <number>", "Maximum tokens", "32000").option("-f, --format <type>", "Output format: markdown, json, plain", "markdown").action(async (options) => {
+  const spinner = ora6("Building context...").start();
+  try {
+    const builder = await getContextBuilder5();
+    const result = await builder.build({
+      goal: options.goal,
+      maxTokens: parseInt(options.maxTokens)
+    });
+    spinner.text = "Formatting...";
+    let output;
+    switch (options.format) {
+      case "json":
+        output = JSON.stringify({
+          goal: result.goal,
+          files: result.files.map((f) => ({
+            path: f.path,
+            score: f.score.final,
+            content: f.chunks.map((c) => c.content).join("\n")
+          })),
+          rules: result.rules,
+          tokenCount: result.tokenCount
+        }, null, 2);
+        break;
+      case "plain":
+        output = result.files.map((f) => `// ${f.path}
+${f.chunks.map((c) => c.content).join("\n")}`).join("\n\n");
+        break;
+      default:
+        output = builder.formatForLLM(result);
+    }
+    const { default: clipboardy } = await import("clipboardy");
+    await clipboardy.write(output);
+    spinner.succeed("Copied to clipboard");
+    console.log();
+    console.log(chalk6.gray("Context Details:"));
+    console.log(chalk6.white(`  \u{1F4CA} Tokens: ${chalk6.cyan(result.tokenCount.toLocaleString())}`));
+    console.log(chalk6.white(`  \u{1F4C1} Files: ${chalk6.cyan(result.files.length)}`));
+    console.log(chalk6.white(`  \u{1F4DD} Format: ${chalk6.cyan(options.format)}`));
+    console.log(chalk6.white(`  \u{1F4B0} Savings: ${chalk6.green(result.savings.percentage + "%")}`));
+    console.log();
+    console.log(chalk6.green.bold("\u{1F4CB} Context copied to clipboard!\n"));
+    console.log(chalk6.gray("Paste into your AI assistant to get contextual help.\n"));
+  } catch (error) {
+    spinner.fail("Copy failed");
+    if (error instanceof Error && error.message.includes("not initialized")) {
+      console.log(chalk6.yellow('\nRun "ctx init" first to initialize ContextOS.\n'));
+    } else {
+      console.error(chalk6.red("Error:"), error);
+    }
+    process.exit(1);
+  }
+});
+
+// src/commands/doctor.ts
+import { Command as Command7 } from "commander";
+import chalk7 from "chalk";
+import ora7 from "ora";
+import { detectDrift, isGeminiAvailable, createGeminiClient } from "@contextos/core";
+var doctorCommand = new Command7("doctor").description("Check for drift between context.yaml and code reality").option("--fix", "Attempt to auto-fix issues").option("--json", "Output as JSON for CI/CD").option("--ci", "Exit with code 1 if errors found").option("--explain", "Use Gemini to explain issues in detail").action(async (options) => {
+  if (!options.json) {
+    console.log(chalk7.blue.bold("\n\u{1FA7A} ContextOS Health Check\n"));
+  }
+  const spinner = options.json ? null : ora7("Analyzing project...").start();
+  const gemini = options.explain && isGeminiAvailable() ? createGeminiClient() : null;
+  try {
+    const report = await detectDrift();
+    if (spinner) spinner.stop();
+    if (options.json) {
+      console.log(JSON.stringify(report, null, 2));
+      if (options.ci && report.errors.length > 0) {
+        process.exit(1);
+      }
+      return;
+    }
+    console.log(chalk7.gray("\u2554" + "\u2550".repeat(68) + "\u2557"));
+    console.log(chalk7.gray("\u2551") + chalk7.white.bold(" \u{1FA7A} ContextOS Health Check").padEnd(77) + chalk7.gray("\u2551"));
+    console.log(chalk7.gray("\u2560" + "\u2550".repeat(68) + "\u2563"));
+    if (report.errors.length > 0) {
+      console.log(chalk7.gray("\u2551") + " ".repeat(68) + chalk7.gray("\u2551"));
+      console.log(chalk7.gray("\u2551") + chalk7.red.bold(` \u274C ERRORS (${report.errors.length})`).padEnd(77) + chalk7.gray("\u2551"));
+      console.log(chalk7.gray("\u2551") + " ".repeat(68) + chalk7.gray("\u2551"));
+      for (const error of report.errors) {
+        console.log(chalk7.gray("\u2551") + chalk7.red(` [ERROR] ${error.message}`).substring(0, 68).padEnd(68) + chalk7.gray("\u2551"));
+        console.log(chalk7.gray("\u2551") + chalk7.gray(`    Expected: "${error.expected}"`).substring(0, 68).padEnd(68) + chalk7.gray("\u2551"));
+        console.log(chalk7.gray("\u2551") + chalk7.gray(`    Actual: "${error.actual}"`).substring(0, 68).padEnd(68) + chalk7.gray("\u2551"));
+        if (error.location) {
+          console.log(chalk7.gray("\u2551") + chalk7.gray(`    Location: ${error.location.file}${error.location.line ? ":" + error.location.line : ""}`).substring(0, 68).padEnd(68) + chalk7.gray("\u2551"));
+        }
+        console.log(chalk7.gray("\u2551") + chalk7.yellow(`    \u{1F4A1} Fix: ${error.suggestion}`).substring(0, 68).padEnd(68) + chalk7.gray("\u2551"));
+        if (gemini) {
+          try {
+            const explanation = await gemini.explainDrift({
+              type: error.type,
+              expected: error.expected,
+              actual: error.actual,
+              location: error.location?.file
+            });
+            console.log(chalk7.gray("\u2551") + " ".repeat(68) + chalk7.gray("\u2551"));
+            console.log(chalk7.gray("\u2551") + chalk7.cyan("    \u{1F916} AI Explanation:").padEnd(68) + chalk7.gray("\u2551"));
+            const lines = explanation.split("\n").slice(0, 3);
+            for (const line of lines) {
+              console.log(chalk7.gray("\u2551") + chalk7.white(`    ${line}`).substring(0, 68).padEnd(68) + chalk7.gray("\u2551"));
+            }
+          } catch {
+          }
+        }
+        console.log(chalk7.gray("\u2551") + " ".repeat(68) + chalk7.gray("\u2551"));
+      }
+    }
+    if (report.warnings.length > 0) {
+      console.log(chalk7.gray("\u2551") + chalk7.yellow.bold(` \u26A0\uFE0F  WARNINGS (${report.warnings.length})`).padEnd(77) + chalk7.gray("\u2551"));
+      console.log(chalk7.gray("\u2551") + " ".repeat(68) + chalk7.gray("\u2551"));
+      for (const warning of report.warnings) {
+        console.log(chalk7.gray("\u2551") + chalk7.yellow(` [WARNING] ${warning.message}`).substring(0, 68).padEnd(68) + chalk7.gray("\u2551"));
+        console.log(chalk7.gray("\u2551") + chalk7.yellow(`    \u{1F4A1} ${warning.suggestion}`).substring(0, 68).padEnd(68) + chalk7.gray("\u2551"));
+        console.log(chalk7.gray("\u2551") + " ".repeat(68) + chalk7.gray("\u2551"));
+      }
+    }
+    console.log(chalk7.gray("\u2560" + "\u2550".repeat(68) + "\u2563"));
+    const statusIcon = report.errors.length > 0 ? "\u274C" : report.warnings.length > 0 ? "\u26A0\uFE0F" : "\u2705";
+    const statusText = report.errors.length > 0 ? "Issues found - action required" : report.warnings.length > 0 ? "Warnings detected" : "All checks passed";
+    console.log(chalk7.gray("\u2551") + ` ${statusIcon} ${statusText}`.padEnd(68) + chalk7.gray("\u2551"));
+    console.log(chalk7.gray("\u2551") + chalk7.green(` \u2705 ${report.passed} checks passed`).padEnd(77) + chalk7.gray("\u2551"));
+    if (report.errors.length > 0) {
+      console.log(chalk7.gray("\u2551") + chalk7.red(` \u274C ${report.errors.length} errors`).padEnd(77) + chalk7.gray("\u2551"));
+    }
+    if (report.warnings.length > 0) {
+      console.log(chalk7.gray("\u2551") + chalk7.yellow(` \u26A0\uFE0F  ${report.warnings.length} warnings`).padEnd(77) + chalk7.gray("\u2551"));
+    }
+    console.log(chalk7.gray("\u255A" + "\u2550".repeat(68) + "\u255D"));
+    console.log();
+    if (options.ci && report.errors.length > 0) {
+      process.exit(1);
+    }
+  } catch (error) {
+    if (spinner) spinner.fail("Health check failed");
+    if (error instanceof Error && error.message.includes("not initialized")) {
+      console.log(chalk7.yellow('\nRun "ctx init" first to initialize ContextOS.\n'));
+    } else {
+      console.error(chalk7.red("Error:"), error);
+    }
+    process.exit(1);
+  }
+});
+
+// src/commands/suggest-rules.ts
+import { Command as Command8 } from "commander";
+import chalk8 from "chalk";
+import ora8 from "ora";
+import { readFileSync, writeFileSync as writeFileSync2 } from "fs";
+import { join as join2 } from "path";
+import { glob } from "glob";
+import { parse, stringify as stringify2 } from "yaml";
+import {
+  isGeminiAvailable as isGeminiAvailable2,
+  createGeminiClient as createGeminiClient2,
+  loadConfig
+} from "@contextos/core";
+var suggestRulesCommand = new Command8("suggest-rules").description("Suggest coding constraints using Gemini AI analysis").option("-a, --apply", "Automatically apply suggested rules").option("-n, --count <number>", "Number of files to analyze", "5").action(async (options) => {
+  console.log(chalk8.blue.bold("\n\u{1F916} Gemini Constraint Suggester\n"));
+  if (!isGeminiAvailable2()) {
+    console.log(chalk8.yellow("\u26A0\uFE0F  Gemini API key not configured."));
+    console.log(chalk8.gray("   Set GEMINI_API_KEY environment variable to use this feature.\n"));
+    console.log(chalk8.white('   Example: export GEMINI_API_KEY="your-api-key"\n'));
+    return;
+  }
+  const spinner = ora8("Loading project configuration...").start();
+  try {
+    const config = loadConfig();
+    const gemini = createGeminiClient2();
+    if (!gemini) {
+      spinner.fail("Failed to create Gemini client");
+      return;
+    }
+    const existingRules = config.context.constraints?.map((c) => c.rule) || [];
+    spinner.text = "Finding sample code files...";
+    const extensions = ["*.ts", "*.js", "*.tsx", "*.jsx", "*.py"];
+    const patterns = extensions.map((e) => `**/${e}`);
+    let files = await glob(patterns, {
+      cwd: config.rootDir,
+      ignore: ["**/node_modules/**", "**/dist/**", "**/.git/**", "**/*.test.*", "**/*.spec.*"],
+      absolute: true
+    });
+    const maxFiles = parseInt(options.count) || 5;
+    files = files.slice(0, maxFiles);
+    if (files.length === 0) {
+      spinner.fail("No source files found to analyze");
+      return;
+    }
+    spinner.text = `Analyzing ${files.length} files with Gemini...`;
+    let sampleCode = "";
+    for (const file of files) {
+      try {
+        const content = readFileSync(file, "utf-8");
+        const relativePath = file.replace(config.rootDir, "");
+        sampleCode += `
+// File: ${relativePath}
+${content.slice(0, 500)}
+`;
+      } catch {
+      }
+    }
+    const suggestions = await gemini.suggestConstraints(sampleCode, existingRules);
+    spinner.succeed("Analysis complete");
+    if (suggestions.length === 0) {
+      console.log(chalk8.yellow("\n\u{1F4CB} No new constraint suggestions at this time."));
+      console.log(chalk8.gray("   Your existing rules seem comprehensive!\n"));
+      return;
+    }
+    console.log(chalk8.white.bold("\n\u{1F4CB} Suggested Constraints:\n"));
+    suggestions.forEach((suggestion, index) => {
+      const severityIcon = suggestion.severity === "error" ? "\u{1F6AB}" : suggestion.severity === "warning" ? "\u26A0\uFE0F" : "\u2139\uFE0F";
+      const severityColor = suggestion.severity === "error" ? chalk8.red : suggestion.severity === "warning" ? chalk8.yellow : chalk8.blue;
+      console.log(`${chalk8.gray(`${index + 1}.`)} ${severityIcon} ${chalk8.white.bold(suggestion.rule)}`);
+      console.log(`   ${chalk8.gray("Severity:")} ${severityColor(suggestion.severity)}`);
+      console.log(`   ${chalk8.gray("Reason:")} ${suggestion.reason}`);
+      console.log();
+    });
+    if (options.apply) {
+      const applySpinner = ora8("Applying suggestions to context.yaml...").start();
+      try {
+        const contextPath = join2(config.rootDir, ".contextos", "context.yaml");
+        const contextContent = readFileSync(contextPath, "utf-8");
+        const contextYaml = parse(contextContent);
+        if (!contextYaml.constraints) {
+          contextYaml.constraints = [];
+        }
+        for (const suggestion of suggestions) {
+          contextYaml.constraints.push({
+            rule: suggestion.rule,
+            severity: suggestion.severity
+          });
+        }
+        writeFileSync2(contextPath, stringify2(contextYaml, { indent: 2 }), "utf-8");
+        applySpinner.succeed(`Added ${suggestions.length} constraints to context.yaml`);
+      } catch (error) {
+        applySpinner.fail("Failed to apply suggestions");
+        console.error(chalk8.red("Error:"), error);
+      }
+    } else {
+      console.log(chalk8.blue("\u{1F4A1} Run with --apply to add these rules to your context.yaml\n"));
+    }
+  } catch (error) {
+    spinner.fail("Suggestion failed");
+    if (error instanceof Error && error.message.includes("not initialized")) {
+      console.log(chalk8.yellow('\nRun "ctx init" first to initialize ContextOS.\n'));
+    } else {
+      console.error(chalk8.red("Error:"), error);
+    }
+    process.exit(1);
+  }
+});
+
+// src/commands/config.ts
+import { Command as Command9 } from "commander";
+import chalk9 from "chalk";
+import inquirer2 from "inquirer";
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "fs";
+import { join as join3 } from "path";
+import { parse as parse2, stringify as stringify3 } from "yaml";
+import { loadConfig as loadConfig2 } from "@contextos/core";
+var configCommand = new Command9("config").description("View and modify configuration settings").argument("[key]", "Configuration key to view/set (e.g., indexing.watch_mode)").argument("[value]", "Value to set").option("-l, --list", "List all configuration values").option("-r, --reset", "Reset to default configuration").option("-e, --edit", "Open configuration in interactive editor").action(async (key, value, options) => {
+  try {
+    const config = loadConfig2();
+    const configPath = join3(config.rootDir, ".contextos", "config.yaml");
+    const configContent = readFileSync2(configPath, "utf-8");
+    const configYaml = parse2(configContent);
+    if (options.list || !key && !options.reset && !options.edit) {
+      console.log(chalk9.blue.bold("\n\u2699\uFE0F  ContextOS Configuration\n"));
+      console.log(chalk9.gray("Path:"), configPath);
+      console.log();
+      printConfig(configYaml);
+      return;
+    }
+    if (options.reset) {
+      const { confirm } = await inquirer2.prompt([{
+        type: "confirm",
+        name: "confirm",
+        message: "Reset configuration to defaults?",
+        default: false
+      }]);
+      if (confirm) {
+        const defaultConfig = {
+          indexing: {
+            watch_mode: true,
+            ignore_patterns: ["node_modules/**", "dist/**", ".git/**"],
+            file_size_limit: "1MB"
+          },
+          graph: {
+            max_depth: 2,
+            follow_types: ["import", "require", "export"],
+            include_types: true
+          },
+          embedding: {
+            strategy: "adaptive",
+            provider: "local",
+            model: "all-MiniLM-L6-v2",
+            chunk_size: 512,
+            overlap: 50
+          },
+          budgeting: {
+            strategy: "adaptive"
+          }
+        };
+        writeFileSync3(configPath, stringify3(defaultConfig, { indent: 2 }), "utf-8");
+        console.log(chalk9.green("\n\u2705 Configuration reset to defaults.\n"));
+      }
+      return;
+    }
+    if (options.edit) {
+      const answers = await inquirer2.prompt([
+        {
+          type: "confirm",
+          name: "watchMode",
+          message: "Enable watch mode (auto-indexing)?",
+          default: configYaml.indexing?.watch_mode ?? true
+        },
+        {
+          type: "number",
+          name: "maxDepth",
+          message: "Max dependency graph depth:",
+          default: configYaml.graph?.max_depth ?? 2
+        },
+        {
+          type: "list",
+          name: "embeddingStrategy",
+          message: "Embedding strategy:",
+          choices: ["adaptive", "full", "lazy"],
+          default: configYaml.embedding?.strategy ?? "adaptive"
+        },
+        {
+          type: "number",
+          name: "chunkSize",
+          message: "Chunk size (tokens):",
+          default: configYaml.embedding?.chunk_size ?? 512
+        },
+        {
+          type: "input",
+          name: "targetModel",
+          message: "Target LLM model:",
+          default: configYaml.budgeting?.target_model ?? "gpt-4-turbo"
+        }
+      ]);
+      configYaml.indexing = { ...configYaml.indexing, watch_mode: answers.watchMode };
+      configYaml.graph = { ...configYaml.graph, max_depth: answers.maxDepth };
+      configYaml.embedding = {
+        ...configYaml.embedding,
+        strategy: answers.embeddingStrategy,
+        chunk_size: answers.chunkSize
+      };
+      configYaml.budgeting = { ...configYaml.budgeting, target_model: answers.targetModel };
+      writeFileSync3(configPath, stringify3(configYaml, { indent: 2 }), "utf-8");
+      console.log(chalk9.green("\n\u2705 Configuration updated.\n"));
+      return;
+    }
+    if (key) {
+      const keys = key.split(".");
+      if (value !== void 0) {
+        setNestedValue(configYaml, keys, parseValue(value));
+        writeFileSync3(configPath, stringify3(configYaml, { indent: 2 }), "utf-8");
+        console.log(chalk9.green(`
+\u2705 Set ${key} = ${value}
+`));
+      } else {
+        const val = getNestedValue(configYaml, keys);
+        if (val !== void 0) {
+          console.log(`
+${chalk9.cyan(key)}: ${formatValue(val)}
+`);
+        } else {
+          console.log(chalk9.yellow(`
+\u26A0\uFE0F  Key '${key}' not found.
+`));
+        }
+      }
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("not initialized")) {
+      console.log(chalk9.yellow('\nRun "ctx init" first to initialize ContextOS.\n'));
+    } else {
+      console.error(chalk9.red("Error:"), error);
+    }
+    process.exit(1);
+  }
+});
+function printConfig(obj, prefix = "") {
+  for (const [key, value] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      console.log(chalk9.white.bold(`${fullKey}:`));
+      printConfig(value, fullKey);
+    } else {
+      console.log(`  ${chalk9.cyan(fullKey)}: ${formatValue(value)}`);
+    }
+  }
+}
+function formatValue(value) {
+  if (Array.isArray(value)) {
+    return chalk9.gray(`[${value.join(", ")}]`);
+  }
+  if (typeof value === "boolean") {
+    return value ? chalk9.green("true") : chalk9.red("false");
+  }
+  if (typeof value === "number") {
+    return chalk9.yellow(String(value));
+  }
+  return chalk9.white(String(value));
+}
+function getNestedValue(obj, keys) {
+  let current = obj;
+  for (const key of keys) {
+    if (current && typeof current === "object" && key in current) {
+      current = current[key];
+    } else {
+      return void 0;
+    }
+  }
+  return current;
+}
+function setNestedValue(obj, keys, value) {
+  let current = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (!(key in current) || typeof current[key] !== "object") {
+      current[key] = {};
+    }
+    current = current[key];
+  }
+  current[keys[keys.length - 1]] = value;
+}
+function parseValue(value) {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (!isNaN(Number(value))) return Number(value);
+  return value;
+}
+
+// src/commands/analyze.ts
+import { Command as Command10 } from "commander";
+import chalk10 from "chalk";
+import ora9 from "ora";
+import { readFileSync as readFileSync3, readdirSync } from "fs";
+import { join as join4, relative } from "path";
+import {
+  RLMEngine,
+  createGeminiClient as createGeminiClient3,
+  mergeFilesToContext
+} from "@contextos/core";
+function collectFiles(dir, extensions = [".ts", ".js", ".tsx", ".jsx", ".py", ".go", ".rs", ".java"], maxFiles = 100) {
+  const files = [];
+  function walk(currentDir) {
+    if (files.length >= maxFiles) return;
+    const entries = readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (files.length >= maxFiles) break;
+      const fullPath = join4(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (["node_modules", ".git", "dist", "build", ".next", "__pycache__", "venv"].includes(entry.name)) {
+          continue;
+        }
+        walk(fullPath);
+      } else if (entry.isFile()) {
+        const ext = entry.name.substring(entry.name.lastIndexOf("."));
+        if (extensions.includes(ext)) {
+          try {
+            const content = readFileSync3(fullPath, "utf-8");
+            files.push({
+              path: relative(dir, fullPath),
+              content
+            });
+          } catch {
+          }
+        }
+      }
+    }
+  }
+  walk(dir);
+  return files;
+}
+var analyzeCommand = new Command10("analyze").description("RLM-powered deep analysis of your codebase").argument("<goal>", 'Analysis goal or question (e.g., "Find all API endpoints")').option("-d, --depth <number>", "Maximum recursion depth for RLM", "3").option("-b, --budget <tokens>", "Token budget for analysis", "50000").option("-p, --path <path>", "Path to analyze (default: current directory)", ".").option("--max-files <number>", "Maximum files to include", "100").option("--verbose", "Show detailed execution trace").action(async (goal, options) => {
+  console.log(chalk10.blue.bold("\n\u{1F50D} RLM Analysis Engine\n"));
+  console.log(chalk10.gray("Goal: ") + chalk10.white(goal));
+  console.log();
+  const spinner = ora9("Collecting codebase files...").start();
+  try {
+    const files = collectFiles(options.path, void 0, parseInt(options.maxFiles));
+    spinner.text = `Found ${files.length} files. Building context...`;
+    if (files.length === 0) {
+      spinner.fail("No source files found");
+      console.log(chalk10.yellow("\nMake sure you are in a project directory with source code.\n"));
+      process.exit(1);
+    }
+    const context = mergeFilesToContext(files);
+    const contextSizeKB = (context.length / 1024).toFixed(1);
+    spinner.text = `Context: ${contextSizeKB}KB. Initializing RLM engine...`;
+    const engine = new RLMEngine({
+      maxDepth: parseInt(options.depth),
+      maxTokenBudget: parseInt(options.budget),
+      backend: "gemini",
+      verbose: options.verbose
+    });
+    const gemini = createGeminiClient3();
+    if (!gemini) {
+      spinner.fail("Gemini API key not configured");
+      console.log(chalk10.yellow("\nSet GEMINI_API_KEY environment variable to use RLM analysis.\n"));
+      process.exit(1);
+    }
+    engine.setModelAdapter({
+      name: "gemini",
+      maxContextTokens: 2e6,
+      async complete(request) {
+        try {
+          const response = await gemini.request(
+            request.userMessage,
+            request.systemPrompt
+          );
+          return {
+            content: response,
+            tokensUsed: {
+              prompt: Math.ceil(request.userMessage.length / 4),
+              completion: Math.ceil(response.length / 4),
+              total: Math.ceil((request.userMessage.length + response.length) / 4)
+            },
+            finishReason: "stop"
+          };
+        } catch (error) {
+          return {
+            content: "",
+            tokensUsed: { prompt: 0, completion: 0, total: 0 },
+            finishReason: "error",
+            error: error instanceof Error ? error.message : String(error)
+          };
+        }
+      },
+      async countTokens(text) {
+        return Math.ceil(text.length / 4);
+      }
+    });
+    spinner.text = "Executing RLM analysis...";
+    const startTime = Date.now();
+    const result = await engine.execute(goal, context);
+    const duration = ((Date.now() - startTime) / 1e3).toFixed(1);
+    spinner.succeed(`Analysis complete (${duration}s)`);
+    console.log();
+    console.log(chalk10.blue.bold("\u2500".repeat(60)));
+    console.log(chalk10.blue.bold("\u{1F4CA} Analysis Result"));
+    console.log(chalk10.blue.bold("\u2500".repeat(60)));
+    console.log();
+    console.log(result.answer);
+    console.log();
+    console.log(chalk10.blue.bold("\u2500".repeat(60)));
+    console.log();
+    console.log(chalk10.gray("Statistics:"));
+    console.log(chalk10.white(`  \u{1F522} Tokens used: ${chalk10.cyan(result.totalTokens.toLocaleString())}`));
+    console.log(chalk10.white(`  \u{1F3AF} Confidence: ${chalk10.cyan((result.confidence * 100).toFixed(0) + "%")}`));
+    console.log(chalk10.white(`  \u{1F4DD} Execution steps: ${chalk10.cyan(result.executionPath.length)}`));
+    if (result.truncated) {
+      console.log(chalk10.yellow(`  \u26A0\uFE0F  Truncated: ${result.truncationReason}`));
+    }
+    if (options.verbose && result.executionPath.length > 0) {
+      console.log();
+      console.log(chalk10.gray("Execution Trace:"));
+      for (const step of result.executionPath.slice(0, 10)) {
+        const icon = step.action === "code" ? "\u{1F4BB}" : step.action === "recurse" ? "\u{1F504}" : "\u2705";
+        console.log(chalk10.gray(`  ${icon} ${step.action}: ${step.input.slice(0, 60)}...`));
+      }
+      if (result.executionPath.length > 10) {
+        console.log(chalk10.gray(`  ... and ${result.executionPath.length - 10} more steps`));
+      }
+    }
+    console.log();
+  } catch (error) {
+    spinner.fail("Analysis failed");
+    console.error(chalk10.red("Error:"), error);
+    process.exit(1);
+  }
+});
+
+// src/commands/refactor.ts
+import { Command as Command11 } from "commander";
+import chalk11 from "chalk";
+import ora10 from "ora";
+import {
+  getContextBuilder as getContextBuilder7,
+  RLMEngine as RLMEngine2,
+  createGeminiClient as createGeminiClient4,
+  mergeFilesToContext as mergeFilesToContext2
+} from "@contextos/core";
+var refactorCommand = new Command11("refactor").description("RLM-powered safe refactoring with impact analysis").argument("<description>", 'Refactoring description (e.g., "Rename User to Account")').option("-f, --file <path>", "Target file to refactor").option("-d, --depth <number>", "Maximum analysis depth", "2").option("--dry-run", "Preview changes without applying").option("--no-backup", "Skip creating backup files").option("--force", "Apply changes without confirmation").action(async (description, options) => {
+  console.log(chalk11.blue.bold("\n\u{1F527} RLM Refactoring Engine\n"));
+  console.log(chalk11.gray("Description: ") + chalk11.white(description));
+  if (options.file) {
+    console.log(chalk11.gray("Target file: ") + chalk11.white(options.file));
+  }
+  console.log();
+  const spinner = ora10("Analyzing codebase...").start();
+  try {
+    const builder = await getContextBuilder7();
+    spinner.text = "Building context...";
+    const buildResult = await builder.build({
+      maxTokens: 5e4,
+      targetFile: options.file
+    });
+    const files = buildResult.files.map((f) => ({
+      path: f.path,
+      content: f.content || ""
+    }));
+    const context = mergeFilesToContext2(files);
+    spinner.text = "Initializing RLM engine...";
+    const engine = new RLMEngine2({
+      maxDepth: parseInt(options.depth),
+      maxTokenBudget: 3e4,
+      backend: "gemini"
+    });
+    const gemini = createGeminiClient4();
+    if (!gemini) {
+      spinner.fail("Gemini API key not configured");
+      console.log(chalk11.yellow("\nSet GEMINI_API_KEY environment variable.\n"));
+      process.exit(1);
+    }
+    engine.setModelAdapter({
+      name: "gemini",
+      maxContextTokens: 2e6,
+      async complete(request) {
+        try {
+          const response = await gemini.request(
+            request.userMessage,
+            request.systemPrompt
+          );
+          return {
+            content: response,
+            tokensUsed: {
+              prompt: Math.ceil(request.userMessage.length / 4),
+              completion: Math.ceil(response.length / 4),
+              total: Math.ceil((request.userMessage.length + response.length) / 4)
+            },
+            finishReason: "stop"
+          };
+        } catch (error) {
+          return {
+            content: "",
+            tokensUsed: { prompt: 0, completion: 0, total: 0 },
+            finishReason: "error",
+            error: error instanceof Error ? error.message : String(error)
+          };
+        }
+      },
+      async countTokens(text) {
+        return Math.ceil(text.length / 4);
+      }
+    });
+    spinner.text = "Analyzing refactoring impact...";
+    const analysisGoal = `
+Analyze the following refactoring request and provide a detailed impact analysis:
+
+REFACTORING REQUEST: ${description}
+${options.file ? `TARGET FILE: ${options.file}` : ""}
+
+Please analyze:
+1. Which files need to be modified
+2. What specific changes are needed in each file
+3. What are the potential risks
+4. What tests should be run after the refactoring
+
+Respond in JSON format:
+{
+    "description": "Summary of the refactoring",
+    "files": [
+        {
+            "path": "path/to/file.ts",
+            "action": "modify|create|delete",
+            "changes": "Description of changes",
+            "impact": "low|medium|high"
+        }
+    ],
+    "risks": ["Risk 1", "Risk 2"],
+    "testSuggestions": ["Test 1", "Test 2"]
+}
+            `.trim();
+    const result = await engine.execute(analysisGoal, context);
+    spinner.succeed("Impact analysis complete");
+    let plan;
+    try {
+      const jsonMatch = result.answer.match(/\{[\s\S]*\}/);
+      if (jsonMatch) {
+        plan = JSON.parse(jsonMatch[0]);
+      } else {
+        throw new Error("No JSON found in response");
+      }
+    } catch {
+      console.log();
+      console.log(chalk11.blue.bold("Analysis Result:"));
+      console.log(result.answer);
+      console.log();
+      process.exit(0);
+    }
+    console.log();
+    console.log(chalk11.blue.bold("\u2500".repeat(60)));
+    console.log(chalk11.blue.bold("\u{1F4CB} Refactoring Plan"));
+    console.log(chalk11.blue.bold("\u2500".repeat(60)));
+    console.log();
+    console.log(chalk11.white(plan.description));
+    console.log();
+    console.log(chalk11.blue.bold("Files to modify:"));
+    for (const file of plan.files) {
+      const impactColor = file.impact === "high" ? chalk11.red : file.impact === "medium" ? chalk11.yellow : chalk11.green;
+      const actionIcon = file.action === "create" ? "\u2795" : file.action === "delete" ? "\u{1F5D1}\uFE0F" : "\u{1F4DD}";
+      console.log(`  ${actionIcon} ${chalk11.white(file.path)} ${impactColor(`[${file.impact}]`)}`);
+      console.log(chalk11.gray(`     ${file.changes}`));
+    }
+    console.log();
+    if (plan.risks.length > 0) {
+      console.log(chalk11.yellow.bold("\u26A0\uFE0F  Potential Risks:"));
+      for (const risk of plan.risks) {
+        console.log(chalk11.yellow(`  \u2022 ${risk}`));
+      }
+      console.log();
+    }
+    if (plan.testSuggestions.length > 0) {
+      console.log(chalk11.cyan.bold("\u{1F9EA} Recommended Tests:"));
+      for (const test of plan.testSuggestions) {
+        console.log(chalk11.cyan(`  \u2022 ${test}`));
+      }
+      console.log();
+    }
+    if (options.dryRun) {
+      console.log(chalk11.gray("\u2500".repeat(60)));
+      console.log(chalk11.yellow("\n\u{1F4CB} Dry run mode - no changes applied.\n"));
+      console.log(chalk11.gray("Remove --dry-run flag to apply changes.\n"));
+      process.exit(0);
+    }
+    if (!options.force) {
+      console.log(chalk11.gray("\u2500".repeat(60)));
+      console.log(chalk11.yellow("\n\u26A0\uFE0F  This is a preview. Use --force to apply changes."));
+      console.log(chalk11.gray("Or use --dry-run for analysis-only mode.\n"));
+      process.exit(0);
+    }
+    console.log(chalk11.green("\n\u2705 Refactoring plan generated successfully.\n"));
+    console.log(chalk11.gray("Note: Automatic code modification coming in a future release."));
+    console.log(chalk11.gray("For now, use this analysis to manually apply the changes.\n"));
+  } catch (error) {
+    spinner.fail("Refactoring analysis failed");
+    if (error instanceof Error && error.message.includes("not initialized")) {
+      console.log(chalk11.yellow('\nRun "ctx init" first to initialize ContextOS.\n'));
+    } else {
+      console.error(chalk11.red("Error:"), error);
+    }
+    process.exit(1);
+  }
+});
+
+// src/commands/explain.ts
+import { Command as Command12 } from "commander";
+import chalk12 from "chalk";
+import ora11 from "ora";
+import { readFileSync as readFileSync4, existsSync as existsSync2, statSync as statSync2 } from "fs";
+import { join as join5, basename } from "path";
+import {
+  RLMEngine as RLMEngine3,
+  createGeminiClient as createGeminiClient5,
+  mergeFilesToContext as mergeFilesToContext3
+} from "@contextos/core";
+var explainCommand = new Command12("explain").description("Get AI-powered explanation of code").argument("<target>", "File path, function name, or module to explain").option("-d, --depth <number>", "Include dependencies up to depth", "1").option("-f, --format <format>", "Output format: text, markdown, json", "markdown").option("--no-examples", "Skip usage examples in explanation").option("--technical", "Include technical implementation details").action(async (target, options) => {
+  console.log(chalk12.blue.bold("\n\u{1F4DA} ContextOS Code Explainer\n"));
+  const spinner = ora11("Analyzing target...").start();
+  try {
+    let targetContent = "";
+    let targetPath = "";
+    let contextFiles = [];
+    const possiblePath = join5(process.cwd(), target);
+    if (existsSync2(possiblePath) && statSync2(possiblePath).isFile()) {
+      targetPath = target;
+      targetContent = readFileSync4(possiblePath, "utf-8");
+      contextFiles.push({ path: target, content: targetContent });
+      spinner.text = `Found file: ${target}`;
+    } else if (existsSync2(target) && statSync2(target).isFile()) {
+      targetPath = target;
+      targetContent = readFileSync4(target, "utf-8");
+      contextFiles.push({ path: basename(target), content: targetContent });
+      spinner.text = `Found file: ${target}`;
+    } else {
+      spinner.text = `Searching for "${target}"...`;
+      const searchDirs = ["src", "lib", "app", "."];
+      const _found = false;
+      for (const dir of searchDirs) {
+        const searchPath = join5(process.cwd(), dir);
+        if (!existsSync2(searchPath)) continue;
+        spinner.fail(`Symbol "${target}" not found as a file.`);
+        console.log(chalk12.yellow(`
+Tip: Provide a file path instead, e.g.:`));
+        console.log(chalk12.gray(`  ctx explain src/auth/service.ts`));
+        console.log(chalk12.gray(`  ctx explain ./utils/helpers.js`));
+        process.exit(1);
+      }
+    }
+    spinner.text = "Initializing RLM engine...";
+    const engine = new RLMEngine3({
+      maxDepth: parseInt(options.depth),
+      maxTokenBudget: 2e4,
+      backend: "gemini"
+    });
+    const gemini = createGeminiClient5();
+    if (!gemini) {
+      spinner.fail("Gemini API key not configured");
+      console.log(chalk12.yellow("\nSet GEMINI_API_KEY environment variable.\n"));
+      process.exit(1);
+    }
+    engine.setModelAdapter({
+      name: "gemini",
+      maxContextTokens: 2e6,
+      async complete(request) {
+        try {
+          const response = await gemini.request(
+            request.userMessage,
+            request.systemPrompt
+          );
+          return {
+            content: response,
+            tokensUsed: {
+              prompt: Math.ceil(request.userMessage.length / 4),
+              completion: Math.ceil(response.length / 4),
+              total: Math.ceil((request.userMessage.length + response.length) / 4)
+            },
+            finishReason: "stop"
+          };
+        } catch (error) {
+          return {
+            content: "",
+            tokensUsed: { prompt: 0, completion: 0, total: 0 },
+            finishReason: "error",
+            error: error instanceof Error ? error.message : String(error)
+          };
+        }
+      },
+      async countTokens(text) {
+        return Math.ceil(text.length / 4);
+      }
+    });
+    spinner.text = "Generating explanation...";
+    const technicalNote = options.technical ? "Include implementation details, algorithms used, and performance considerations." : "";
+    const examplesNote = options.examples ? "Include practical usage examples." : "";
+    const explainGoal = `
+Explain the following code in a clear, educational manner.
+
+FILE: ${targetPath}
+
+Please provide:
+1. **Overview**: What this code does at a high level
+2. **Key Components**: Main functions, classes, or exports
+3. **How It Works**: Step-by-step explanation of the logic
+4. **Dependencies**: What this code imports/relies on
+${examplesNote ? "5. **Usage Examples**: How to use this code" : ""}
+${technicalNote ? "6. **Technical Details**: Implementation specifics" : ""}
+
+Format the response in ${options.format === "json" ? "JSON" : "Markdown"}.
+            `.trim();
+    const context = mergeFilesToContext3(contextFiles);
+    const result = await engine.execute(explainGoal, context);
+    spinner.succeed("Explanation generated");
+    console.log();
+    console.log(chalk12.blue.bold("\u2500".repeat(60)));
+    console.log(chalk12.blue.bold(`\u{1F4D6} Explanation: ${targetPath}`));
+    console.log(chalk12.blue.bold("\u2500".repeat(60)));
+    console.log();
+    if (options.format === "json") {
+      try {
+        const jsonMatch = result.answer.match(/\{[\s\S]*\}/);
+        if (jsonMatch) {
+          console.log(JSON.stringify(JSON.parse(jsonMatch[0]), null, 2));
+        } else {
+          console.log(result.answer);
+        }
+      } catch {
+        console.log(result.answer);
+      }
+    } else {
+      console.log(result.answer);
+    }
+    console.log();
+    console.log(chalk12.blue.bold("\u2500".repeat(60)));
+    console.log(chalk12.gray(`Tokens used: ${result.totalTokens} | Confidence: ${(result.confidence * 100).toFixed(0)}%`));
+    console.log();
+  } catch (error) {
+    spinner.fail("Explanation failed");
+    console.error(chalk12.red("Error:"), error);
+    process.exit(1);
+  }
+});
+
+// src/commands/trace.ts
+import { Command as Command13 } from "commander";
+import chalk13 from "chalk";
+import ora12 from "ora";
+import {
+  getContextBuilder as getContextBuilder8
+} from "@contextos/core";
+var traceCommand = new Command13("trace").description("Trace function call chains and dependencies").argument("<symbol>", "Function or class name to trace").option("-d, --direction <dir>", "Trace direction: callers, callees, both", "both").option("--depth <number>", "Maximum trace depth", "3").option("--json", "Output as JSON").action(async (symbol, options) => {
+  console.log(chalk13.blue.bold("\n\u{1F517} Call Chain Tracer\n"));
+  console.log(chalk13.gray(`Tracing: ${symbol}`));
+  console.log(chalk13.gray(`Direction: ${options.direction}`));
+  console.log();
+  const spinner = ora12("Analyzing dependency graph...").start();
+  try {
+    const _builder = await getContextBuilder8();
+    spinner.text = "Building call chain...";
+    spinner.succeed("Trace complete");
+    console.log();
+    console.log(chalk13.blue.bold("\u2500".repeat(60)));
+    console.log(chalk13.blue.bold(`\u{1F4CA} Call Chain for: ${symbol}`));
+    console.log(chalk13.blue.bold("\u2500".repeat(60)));
+    console.log();
+    if (options.direction === "callers" || options.direction === "both") {
+      console.log(chalk13.green.bold("\u2B06\uFE0F  Called by (callers):"));
+      console.log(chalk13.gray("  \u2514\u2500\u2500 Use ctx analyze to find callers"));
+      console.log();
+    }
+    if (options.direction === "callees" || options.direction === "both") {
+      console.log(chalk13.yellow.bold("\u2B07\uFE0F  Calls (callees):"));
+      console.log(chalk13.gray("  \u2514\u2500\u2500 Use ctx analyze to find dependencies"));
+      console.log();
+    }
+    console.log(chalk13.blue.bold("\u2500".repeat(60)));
+    console.log();
+    console.log(chalk13.gray("Tip: For detailed analysis, use:"));
+    console.log(chalk13.cyan(`  ctx analyze "Find all functions that call ${symbol}"`));
+    console.log();
+  } catch (error) {
+    spinner.fail("Trace failed");
+    if (error instanceof Error && error.message.includes("not initialized")) {
+      console.log(chalk13.yellow('\nRun "ctx init" first to initialize ContextOS.\n'));
+    } else {
+      console.error(chalk13.red("Error:"), error);
+    }
+    process.exit(1);
+  }
+});
+
+// src/index.ts
+var program = new Command14();
+program.name("ctx").description("ContextOS - The Context Server Protocol for AI Coding").version("0.1.0").option("-v, --verbose", "Enable verbose output");
+program.addCommand(initCommand);
+program.addCommand(indexCommand);
+program.addCommand(buildCommand);
+program.addCommand(goalCommand);
+program.addCommand(previewCommand);
+program.addCommand(copyCommand);
+program.addCommand(doctorCommand);
+program.addCommand(configCommand);
+program.addCommand(suggestRulesCommand);
+program.addCommand(analyzeCommand);
+program.addCommand(refactorCommand);
+program.addCommand(explainCommand);
+program.addCommand(traceCommand);
+program.parse();