ai-first-cli 1.3.0 → 1.3.5

package/tests/cli-commands-batch3.test.ts

@@ -0,0 +1,1128 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from "vitest";
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { spawn, execSync } from "child_process";
+
+const PROJECT_ROOT = process.cwd();
+const CLI_PATH = path.join(PROJECT_ROOT, "dist/commands/ai-first.js");
+const EXPRESS_API_PATH = path.join(PROJECT_ROOT, "test-projects/express-api");
+
+/**
+ * Creates a temporary project directory with some source files
+ */
+function createTempProjectDir(files: Record<string, string>): string {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "cli-batch3-test-"));
+  for (const [filePath, content] of Object.entries(files)) {
+    const fullPath = path.join(tempDir, filePath);
+    const dir = path.dirname(fullPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(fullPath, content);
+  }
+  return tempDir;
+}
+
+/**
+ * Creates a git repository with some commits
+ */
+function createGitRepo(files: Record<string, string>): string {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "cli-git-test-"));
+  
+  // Initialize git repo
+  execSync("git init", { cwd: tempDir, stdio: "ignore" });
+  execSync("git config user.email 'test@test.com'", { cwd: tempDir, stdio: "ignore" });
+  execSync("git config user.name 'Test User'", { cwd: tempDir, stdio: "ignore" });
+  
+  // Create files
+  for (const [filePath, content] of Object.entries(files)) {
+    const fullPath = path.join(tempDir, filePath);
+    const dir = path.dirname(fullPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(fullPath, content);
+  }
+  
+  // Initial commit
+  execSync("git add .", { cwd: tempDir, stdio: "ignore" });
+  execSync("git commit -m 'Initial commit'", { cwd: tempDir, stdio: "ignore" });
+  
+  return tempDir;
+}
+
+/**
+ * Run a CLI command and return result
+ */
+async function runCLICommand(
+  command: string,
+  args: string[],
+  cwd: string = process.cwd()
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  return new Promise((resolve) => {
+    const child = spawn("node", [CLI_PATH, command, ...args], {
+      cwd,
+      stdio: "pipe",
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout?.on("data", (data) => {
+      stdout += data.toString();
+    });
+
+    child.stderr?.on("data", (data) => {
+      stderr += data.toString();
+    });
+
+    child.on("close", (code) => {
+      resolve({
+        stdout,
+        stderr,
+        exitCode: code ?? 0,
+      });
+    });
+
+    child.on("error", (err) => {
+      stderr += err.message;
+      resolve({ stdout, stderr, exitCode: 1 });
+    });
+
+    // Timeout after 60 seconds
+    setTimeout(() => {
+      child.kill();
+      resolve({ stdout, stderr, exitCode: 124 });
+    }, 60000);
+  });
+}
+
+/**
+ * Run init command first (needed for some tests)
+ */
+async function runInitCommand(
+  args: string[],
+  cwd: string = process.cwd()
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  return new Promise((resolve) => {
+    const child = spawn("node", [CLI_PATH, "init", ...args], {
+      cwd,
+      stdio: "pipe",
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout?.on("data", (data) => {
+      stdout += data.toString();
+    });
+
+    child.stderr?.on("data", (data) => {
+      stderr += data.toString();
+    });
+
+    child.on("close", (code) => {
+      resolve({
+        stdout,
+        stderr,
+        exitCode: code ?? 0,
+      });
+    });
+
+    child.on("error", (err) => {
+      stderr += err.message;
+      resolve({ stdout, stderr, exitCode: 1 });
+    });
+
+    // Timeout after 60 seconds
+    setTimeout(() => {
+      child.kill();
+      resolve({ stdout, stderr, exitCode: 124 });
+    }, 60000);
+  });
+}
+
+describe("CLI Commands Batch 3 - git, graph, update, help", () => {
+  const tempDirs: string[] = [];
+
+  beforeAll(() => {
+    // Ensure dist is built
+    if (!fs.existsSync(CLI_PATH)) {
+      throw new Error(
+        `CLI not found at ${CLI_PATH}. Run 'npm run build' first.`
+      );
+    }
+  });
+
+  afterAll(() => {
+    // Clean up all temp directories
+    for (const dir of tempDirs) {
+      try {
+        fs.rmSync(dir, { recursive: true, force: true });
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+  });
+
+  // =========================================================================
+  // GIT COMMAND TESTS
+  // =========================================================================
+
+  describe("Git Command", () => {
+    describe("Default Options", () => {
+      it("should analyze git activity on a git repository", async () => {
+        const gitRepo = createGitRepo({
+          "package.json": '{"name": "test-repo"}',
+          "src/index.js": "const x = 1;",
+          "src/app.js": "const app = {};",
+        });
+        tempDirs.push(gitRepo);
+
+        const result = await runCLICommand("git", [], gitRepo);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toContain("Analyzing git activity");
+        expect(result.stdout).toContain("Recent files:");
+      });
+
+      it("should generate git context files", async () => {
+        const gitRepo = createGitRepo({
+          "package.json": '{"name": "test-repo"}',
+          "README.md": "# Test",
+        });
+        tempDirs.push(gitRepo);
+
+        await runCLICommand("git", [], gitRepo);
+
+        // Check that git context files were created
+        const aiGitDir = path.join(gitRepo, "ai-context", "git");
+        expect(fs.existsSync(aiGitDir)).toBe(true);
+      });
+
+      it("should handle repository with no commits", async () => {
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "no-commits-"));
+        tempDirs.push(tempDir);
+        
+        // Initialize git but don't make any commits
+        execSync("git init", { cwd: tempDir, stdio: "ignore" });
+        fs.writeFileSync(path.join(tempDir, "README.md"), "# Test");
+
+        const result = await runCLICommand("git", [], tempDir);
+
+        // Should handle gracefully
+        expect(result).toBeDefined();
+      });
+    });
+
+    describe("--root Flag", () => {
+      it("should analyze git in specified directory with --root", async () => {
+        const gitRepo = createGitRepo({
+          "package.json": '{"name": "root-test"}',
+          "src/main.js": "const main = 1;",
+        });
+        tempDirs.push(gitRepo);
+
+        const result = await runCLICommand("git", ["--root", gitRepo]);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toContain("Analyzing git activity");
+      });
+
+      it("should handle --root with short flag -r", async () => {
+        const gitRepo = createGitRepo({
+          "package.json": '{"name": "short-flag-test"}',
+        });
+        tempDirs.push(gitRepo);
+
+        const result = await runCLICommand("git", ["-r", gitRepo]);
+
+        expect(result.exitCode).toBe(0);
+      });
+    });
+
+    describe("--limit Flag", () => {
+      it("should limit commits with --limit flag", async () => {
+        const gitRepo = createGitRepo({
+          "package.json": '{"name": "limit-test"}',
+        });
+        tempDirs.push(gitRepo);
+
+        // Make multiple commits
+        for (let i = 0; i < 5; i++) {
+          fs.writeFileSync(path.join(gitRepo, `file${i}.js`), `const x = ${i};`);
+          execSync("git add .", { cwd: gitRepo, stdio: "ignore" });
+          execSync(`git commit -m "Commit ${i}"`, { cwd: gitRepo, stdio: "ignore" });
+        }
+
+        const result = await runCLICommand("git", ["--limit", "3"], gitRepo);
+
+        expect(result.exitCode).toBe(0);
+      });
+
+      it("should handle --limit with short flag -n", async () => {
+        const gitRepo = createGitRepo({
+          "package.json": '{"name": "n-flag-test"}',
+        });
+        tempDirs.push(gitRepo);
+
+        const result = await runCLICommand("git", ["-n", "10"], gitRepo);
+
+        expect(result.exitCode).toBe(0);
+      });
+    });
+
+    describe("--activity Flag", () => {
+      it("should show commit activity details with --activity", async () => {
+        const gitRepo = createGitRepo({
+          "package.json": '{"name": "activity-test"}',
+          "src/index.js": "const x = 1;",
+        });
+        tempDirs.push(gitRepo);
+
+        const result = await runCLICommand("git", ["--activity"], gitRepo);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toMatch(/Commit activity|commits/);
+      });
+
+      it("should handle --activity with short flag -a", async () => {
+        const gitRepo = createGitRepo({
+          "package.json": '{"name": "a-flag-test"}',
+        });
+        tempDirs.push(gitRepo);
+
+        const result = await runCLICommand("git", ["-a"], gitRepo);
+
+        expect(result.exitCode).toBe(0);
+      });
+    });
+
+    describe("--json Flag", () => {
+      it("should output JSON with --json flag", async () => {
+        const gitRepo = createGitRepo({
+          "package.json": '{"name": "json-test"}',
+        });
+        tempDirs.push(gitRepo);
+
+        const result = await runCLICommand("git", ["--json"], gitRepo);
+
+        expect(result.exitCode).toBe(0);
+        
+        const combinedOutput = result.stdout + result.stderr;
+        const jsonMatch = combinedOutput.match(/\{[\s\S]*\}$/m);
+        expect(jsonMatch).not.toBeNull();
+        expect(() => JSON.parse(jsonMatch![0])).not.toThrow();
+      });
+    });
+
+    describe("--help Flag", () => {
+      it("should show help message with --help", async () => {
+        const gitRepo = createGitRepo({
+          "package.json": '{"name": "help-test"}',
+        });
+        tempDirs.push(gitRepo);
+
+        const result = await runCLICommand("git", ["--help"], gitRepo);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toContain("git - Analyze recent git activity");
+        expect(result.stdout).toContain("--root");
+        expect(result.stdout).toContain("--limit");
+        expect(result.stdout).toContain("--activity");
+      });
+    });
+
+    describe("Non-Git Repository", () => {
+      it("should error on non-git repository", async () => {
+        const nonGitDir = createTempProjectDir({
+          "package.json": '{"name": "non-git"}',
+        });
+        tempDirs.push(nonGitDir);
+
+        const result = await runCLICommand("git", [], nonGitDir);
+
+        expect(result.exitCode).toBe(1);
+        expect(result.stdout).toContain("Not a git repository");
+      });
+    });
+
+    describe("Error Handling", () => {
+      it("should handle corrupted git repository gracefully", async () => {
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "corrupt-git-"));
+        tempDirs.push(tempDir);
+        
+        // Create a fake .git directory that isn't a real repo
+        fs.mkdirSync(path.join(tempDir, ".git"), { recursive: true });
+        fs.writeFileSync(path.join(tempDir, "README.md"), "# Test");
+
+        const result = await runCLICommand("git", [], tempDir);
+
+        // Should either succeed with empty results or fail gracefully
+        expect(result).toBeDefined();
+      });
+
+      it("should handle git command not available", async () => {
+        // This test assumes git is available, but verifies graceful handling
+        const gitRepo = createGitRepo({
+          "package.json": '{"name": "git-missing-test"}',
+        });
+        tempDirs.push(gitRepo);
+
+        const result = await runCLICommand("git", [], gitRepo);
+
+        // Should work if git is available
+        expect(result).toBeDefined();
+      });
+    });
+  });
+
+  // =========================================================================
+  // GRAPH COMMAND TESTS
+  // =========================================================================
+
+  describe("Graph Command", () => {
+    describe("Default Options", () => {
+      it("should build knowledge graph on express-api project", async () => {
+        const result = await runCLICommand("graph", [], EXPRESS_API_PATH);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toMatch(/Building knowledge graph|Graph Statistics/);
+      });
+
+      it("should create graph directory with knowledge-graph.json", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "graph-test"}',
+          "src/index.js": "const x = 1;",
+          "src/app.js": "const app = {};",
+        });
+        tempDirs.push(testProject);
+
+        await runCLICommand("graph", [], testProject);
+
+        // Check that graph file was created
+        const graphDir = path.join(testProject, "ai-context", "graph");
+        expect(fs.existsSync(graphDir) || fs.existsSync(path.join(testProject, "ai-context"))).toBe(true);
+      });
+
+      it("should handle non-git repository", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "no-git"}',
+          "src/index.js": "const x = 1;",
+        });
+        tempDirs.push(testProject);
+
+        const result = await runCLICommand("graph", [], testProject);
+
+        // Should complete with warning but exit code 0
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toMatch(/Not a git repository|Building knowledge graph/);
+      });
+    });
+
+    describe("--root Flag", () => {
+      it("should build graph in specified directory with --root", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "graph-root"}',
+          "src/main.js": "const main = 1;",
+        });
+        tempDirs.push(testProject);
+
+        const result = await runCLICommand("graph", ["--root", testProject]);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toMatch(/Building knowledge graph|Graph Statistics/);
+      });
+
+      it("should handle --root with short flag -r", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "graph-r"}',
+        });
+        tempDirs.push(testProject);
+
+        const result = await runCLICommand("graph", ["-r", testProject]);
+
+        expect(result.exitCode).toBe(0);
+      });
+    });
+
+    describe("--stats Flag", () => {
+      it("should show graph statistics with --stats", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "stats-test"}',
+          "src/index.js": "const x = 1;",
+        });
+        tempDirs.push(testProject);
+
+        const result = await runCLICommand("graph", ["--stats"], testProject);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toMatch(/Graph Statistics|Nodes:|Edges:/);
+      });
+
+      it("should handle --stats with short flag -s", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "stats-short"}',
+        });
+        tempDirs.push(testProject);
+
+        const result = await runCLICommand("graph", ["-s"], testProject);
+
+        expect(result.exitCode).toBe(0);
+      });
+    });
+
+    describe("--json Flag", () => {
+      it("should output graph as JSON with --json", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "graph-json"}',
+          "src/index.js": "const x = 1;",
+        });
+        tempDirs.push(testProject);
+
+        const result = await runCLICommand("graph", ["--json", "--no-git"], testProject);
+
+        expect(result.exitCode).toBe(0);
+        
+        const combinedOutput = result.stdout + result.stderr;
+        const jsonMatch = combinedOutput.match(/\{[\s\S]*\}$/m);
+        expect(jsonMatch).not.toBeNull();
+        
+        const json = JSON.parse(jsonMatch![0]);
+        expect(json.nodes).toBeDefined();
+        expect(json.edges).toBeDefined();
+      });
+    });
+
+    describe("--no-git Flag", () => {
+      it("should skip git history with --no-git", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "no-git-flag"}',
+        });
+        tempDirs.push(testProject);
+
+        const result = await runCLICommand("graph", ["--no-git"], testProject);
+
+        expect(result.exitCode).toBe(0);
+      });
+    });
+
+    describe("--help Flag", () => {
+      it("should show help message with --help", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "graph-help"}',
+        });
+        tempDirs.push(testProject);
+
+        const result = await runCLICommand("graph", ["--help"], testProject);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toContain("graph - Generate repository knowledge graph");
+        expect(result.stdout).toContain("--root");
+        expect(result.stdout).toContain("--stats");
+        expect(result.stdout).toContain("--json");
+      });
+    });
+
+    describe("Edge Cases", () => {
+      it("should handle empty project", async () => {
+        const emptyProject = fs.mkdtempSync(path.join(os.tmpdir(), "empty-graph-"));
+        tempDirs.push(emptyProject);
+
+        const result = await runCLICommand("graph", [], emptyProject);
+
+        // Should complete without crashing
+        expect(result.exitCode).toBe(0);
+      });
+
+      it("should handle project with only hidden files", async () => {
+        const hiddenProject = createTempProjectDir({
+          ".gitignore": "node_modules",
+          ".env": "SECRET=123",
+        });
+        tempDirs.push(hiddenProject);
+
+        const result = await runCLICommand("graph", [], hiddenProject);
+
+        expect(result.exitCode).toBe(0);
+      });
+
+      it("should handle deeply nested project", async () => {
+        const deepDir = path.join(
+          os.tmpdir(),
+          "graph-deep",
+          "level1",
+          "level2",
+          "level3"
+        );
+        fs.mkdirSync(deepDir, { recursive: true });
+        tempDirs.push(deepDir);
+
+        fs.writeFileSync(path.join(deepDir, "package.json"), '{"name": "deep"}');
+        fs.mkdirSync(path.join(deepDir, "src"), { recursive: true });
+        fs.writeFileSync(path.join(deepDir, "src", "index.js"), "const x = 1;");
+
+        const result = await runCLICommand("graph", [], deepDir);
+
+        expect(result.exitCode).toBe(0);
+      });
+    });
+  });
+
+  // =========================================================================
+  // UPDATE COMMAND TESTS
+  // =========================================================================
+
+  describe("Update Command", () => {
+    describe("Default Options", () => {
+      it("should require ai-context to exist", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "update-test"}',
+          "src/index.js": "const x = 1;",
+        });
+        tempDirs.push(testProject);
+
+        const result = await runCLICommand("update", [], testProject);
+
+        expect(result.exitCode).toBe(1);
+        expect(result.stdout).toContain("AI context not found");
+      });
+
+      it("should run incremental update when ai-context exists", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "update-test"}',
+          "src/index.js": "const x = 1;",
+        });
+        tempDirs.push(testProject);
+
+        // First run init to create ai-context
+        await runInitCommand([], testProject);
+
+        // Then run update
+        const result = await runCLICommand("update", [], testProject);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toMatch(/Running incremental update|Changed files|Updated:/);
+      });
+
+      it("should detect changed files", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "changed-files-test"}',
+          "src/index.js": "const x = 1;",
+        });
+        tempDirs.push(testProject);
+
+        // First run init
+        await runInitCommand([], testProject);
+
+        // Make a change
+        fs.writeFileSync(path.join(testProject, "src", "index.js"), "const x = 2;");
+
+        const result = await runCLICommand("update", [], testProject);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toMatch(/Changed files:|modified/);
+      });
+    });
+
+    describe("--root Flag", () => {
+      it("should update in specified directory with --root", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "update-root"}',
+          "src/main.js": "const main = 1;",
+        });
+        tempDirs.push(testProject);
+
+        // First run init
+        await runInitCommand(["--root", testProject], testProject);
+
+        const result = await runCLICommand("update", ["--root", testProject], testProject);
+
+        expect(result.exitCode).toBe(0);
+      });
+
+      it("should handle --root with short flag -r", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "update-r"}',
+        });
+        tempDirs.push(testProject);
+
+        // First run init
+        await runInitCommand(["-r", testProject], testProject);
+
+        const result = await runCLICommand("update", ["-r", testProject], testProject);
+
+        expect(result.exitCode).toBe(0);
+      });
+    });
+
+    describe("--no-git Flag", () => {
+      it("should use filesystem timestamps instead of git with --no-git", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "no-git-update"}',
+          "src/index.js": "const x = 1;",
+        });
+        tempDirs.push(testProject);
+
+        // First run init
+        await runInitCommand([], testProject);
+
+        const result = await runCLICommand("update", ["--no-git"], testProject);
+
+        expect(result.exitCode).toBe(0);
+      });
+    });
+
+    describe("--json Flag", () => {
+      it("should output JSON with --json flag", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "update-json"}',
+          "src/index.js": "const x = 1;",
+        });
+        tempDirs.push(testProject);
+
+        // First run init
+        await runInitCommand([], testProject);
+
+        const result = await runCLICommand("update", ["--json"], testProject);
+
+        expect(result.exitCode).toBe(0);
+        // Extract JSON from output (may have status line before JSON)
+        const jsonStart = result.stdout.indexOf('{');
+        expect(jsonStart).toBeGreaterThan(-1);
+        const jsonString = result.stdout.substring(jsonStart);
+        const json = JSON.parse(jsonString);
+        expect(json.changedFiles).toBeDefined();
+      });
+    });
+
+    describe("--help Flag", () => {
+      it("should show help message with --help", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "update-help"}',
+        });
+        tempDirs.push(testProject);
+
+        const result = await runCLICommand("update", ["--help"], testProject);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toContain("update - Incrementally update repository context");
+        expect(result.stdout).toContain("--root");
+        expect(result.stdout).toContain("--no-git");
+        expect(result.stdout).toContain("--json");
+      });
+    });
+
+    describe("Error Handling", () => {
+      it("should handle missing ai-context gracefully", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "no-context"}',
+        });
+        tempDirs.push(testProject);
+
+        const result = await runCLICommand("update", [], testProject);
+
+        expect(result.exitCode).toBe(1);
+        expect(result.stdout).toContain("AI context not found");
+      });
+
+      it("should handle corrupted ai-context", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "corrupted-context"}',
+        });
+        tempDirs.push(testProject);
+
+        // Create ai-context but with invalid content
+        const aiDir = path.join(testProject, "ai-context");
+        fs.mkdirSync(aiDir, { recursive: true });
+        fs.writeFileSync(path.join(aiDir, "invalid.json"), "{ invalid json }");
+
+        const result = await runCLICommand("update", [], testProject);
+
+        // Should handle gracefully
+        expect(result).toBeDefined();
+      });
+    });
+
+    describe("Edge Cases", () => {
+      it("should handle project with deleted files", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "deleted-files"}',
+          "src/index.js": "const x = 1;",
+          "src/to-delete.js": "const y = 2;",
+        });
+        tempDirs.push(testProject);
+
+        // First run init
+        await runInitCommand([], testProject);
+
+        // Delete a file
+        fs.unlinkSync(path.join(testProject, "src", "to-delete.js"));
+
+        const result = await runCLICommand("update", [], testProject);
+
+        expect(result.exitCode).toBe(0);
+      });
+
+      it("should handle project with new files", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "new-files"}',
+          "src/index.js": "const x = 1;",
+        });
+        tempDirs.push(testProject);
+
+        // First run init
+        await runInitCommand([], testProject);
+
+        // Add new files
+        fs.mkdirSync(path.join(testProject, "src", "new"), { recursive: true });
+        fs.writeFileSync(path.join(testProject, "src", "new", "file.js"), "const z = 3;");
+
+        const result = await runCLICommand("update", [], testProject);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toMatch(/Changed files:|added/);
+      });
+
+      it("should handle multiple rapid updates", async () => {
+        const testProject = createTempProjectDir({
+          "package.json": '{"name": "rapid-updates"}',
+          "src/index.js": "const x = 1;",
+        });
+        tempDirs.push(testProject);
+
+        // First run init
+        await runInitCommand([], testProject);
+
+        // Run update multiple times
+        const result1 = await runCLICommand("update", [], testProject);
+        const result2 = await runCLICommand("update", [], testProject);
+
+        expect(result1.exitCode).toBe(0);
+        expect(result2.exitCode).toBe(0);
+      });
+    });
+  });
+
+  // =========================================================================
+  // HELP AND VERSION TESTS
+  // =========================================================================
+
+  describe("Help and Version Commands", () => {
+    describe("Global --help Flag", () => {
+      it("should handle --help as unknown command", async () => {
+        const result = await runCLICommand("--help", []);
+        // Global --help is treated as unknown command
+        expect(result.exitCode).toBe(1);
+        expect(result.stdout).toContain("Unknown command");
+      });
+
+      it("should show all available commands via init --help", async () => {
+        const result = await runCLICommand("init", ["--help"]);
+        // init --help shows a subset of commands
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toContain("init");
+        expect(result.stdout).toContain("index");
+        expect(result.stdout).toContain("doctor");
+        expect(result.stdout).toContain("explore");
+        expect(result.stdout).toContain("adapters");
+      });
+    });
+
+    describe("Init --help Flag", () => {
+      it("should show init command help", async () => {
+        const result = await runCLICommand("init", ["--help"]);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toMatch(/init|Usage:/);
+      });
+    });
+
+    describe("Index --help Flag", () => {
+      it("should show index command help", async () => {
+        const result = await runCLICommand("index", ["--help"]);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toContain("ai-first index");
+        expect(result.stdout).toContain("--root");
+        expect(result.stdout).toContain("--semantic");
+      });
+    });
+
+    describe("Context --help Flag", () => {
+      it("should show context command help", async () => {
+        const result = await runCLICommand("context", ["--help"]);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toContain("context");
+      });
+    });
+
+    describe("Summarize --help Flag", () => {
+      it("should show summarize command help", async () => {
+        const result = await runCLICommand("summarize", ["--help"]);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toContain("summarize");
+      });
+    });
+
+    describe("Query --help Flag", () => {
+      it("should show query help or require index", async () => {
+        // First try with --help (may require index to exist)
+        const result = await runCLICommand("query", ["--help"]);
+        // Query command requires an index to exist, so it may show error or help
+        expect(result).toBeDefined();
+      });
+    });
+
+    describe("Doctor --help Flag", () => {
+      it("should show doctor command help", async () => {
+        const result = await runCLICommand("doctor", ["--help"]);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toContain("doctor");
+      });
+    });
+
+    describe("Explore --help Flag", () => {
+      it("should show explore help or handle module name", async () => {
+        const result = await runCLICommand("explore", ["--help"]);
+        // Explore treats --help as a module name, so output varies
+        expect(result).toBeDefined();
+      });
+    });
+
+    describe("Map --help Flag", () => {
+      it("should show map command help", async () => {
+        const result = await runCLICommand("map", ["--help"]);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toContain("map");
+      });
+    });
+
+    describe("Adapters --help Flag", () => {
+      it("should show adapters command help", async () => {
+        const result = await runCLICommand("adapters", ["--help"]);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toContain("adapters");
+      });
+    });
+
+    describe("Watch --help Flag", () => {
+      it("should show watch command help", async () => {
+        const result = await runCLICommand("watch", ["--help"]);
+
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toContain("watch");
+      });
+    });
+
+    describe("Unknown Command", () => {
+      it("should show error for unknown command", async () => {
+        const result = await runCLICommand("unknown-command", []);
+
+        expect(result.exitCode).toBe(1);
+        expect(result.stdout).toContain("Unknown command");
+      });
+
+      it("should suggest using --help for unknown command", async () => {
+        const result = await runCLICommand("unknown-command", []);
+
+        expect(result.stdout).toMatch(/--help|help/);
+      });
+    });
+
+    describe("Version Display", () => {
+      it("should show version with --version flag if supported", async () => {
+        const result = await runCLICommand("--version", []);
+
+        // Version might be shown or it might show help
+        // Either is acceptable
+        expect(result).toBeDefined();
+      });
+
+      it("should show version with -v flag if supported", async () => {
+        const result = await runCLICommand("-v", []);
+
+        expect(result).toBeDefined();
+      });
+    });
+  });
+
+  // =========================================================================
+  // INTEGRATION TESTS
+  // =========================================================================
+
+  describe("Integration Tests", () => {
+    it("should run full workflow: init -> git -> graph -> update", async () => {
+      // Create a git repository for integration testing
+      const gitRepo = createGitRepo({
+        "package.json": '{"name": "integration-test"}',
+        "src/index.js": "const x = 1;",
+        "src/app.js": "const app = {};",
+        "src/routes.js": "const routes = [];",
+      });
+      tempDirs.push(gitRepo);
+
+      // Step 1: Init
+      const initResult = await runInitCommand([], gitRepo);
+      expect(initResult.exitCode).toBe(0);
+
+      // Step 2: Git
+      const gitResult = await runCLICommand("git", [], gitRepo);
+      expect(gitResult.exitCode).toBe(0);
+
+      // Step 3: Graph
+      const graphResult = await runCLICommand("graph", ["--stats"], gitRepo);
+      expect(graphResult.exitCode).toBe(0);
+
+      // Step 4: Update
+      const updateResult = await runCLICommand("update", [], gitRepo);
+      expect(updateResult.exitCode).toBe(0);
+    });
+
+    it("should handle multiple commands in sequence", async () => {
+      const testProject = createTempProjectDir({
+        "package.json": '{"name": "multi-command"}',
+        "src/index.js": "const x = 1;",
+        "src/app.js": "const app = {};",
+      });
+      tempDirs.push(testProject);
+
+      // Run init first
+      const initResult = await runInitCommand([], testProject);
+      expect(initResult.exitCode).toBe(0);
+
+      // Run graph
+      const graphResult = await runCLICommand("graph", [], testProject);
+      expect(graphResult.exitCode).toBe(0);
+
+      // Run update multiple times
+      const update1 = await runCLICommand("update", [], testProject);
+      expect(update1.exitCode).toBe(0);
+
+      // Modify file
+      fs.writeFileSync(path.join(testProject, "src", "index.js"), "const x = 2;");
+
+      const update2 = await runCLICommand("update", [], testProject);
+      expect(update2.exitCode).toBe(0);
+    });
+
+    it("should work with different project types", async () => {
+      // TypeScript project with git repo
+      const tsProject = createGitRepo({
+        "package.json": '{"name": "ts-project"}',
+        "tsconfig.json": '{"compilerOptions": {}}',
+        "src/index.ts": "export const main = (): void => {};",
+      });
+      tempDirs.push(tsProject);
+
+      await runInitCommand([], tsProject);
+      const tsGitResult = await runCLICommand("git", [], tsProject);
+      expect(tsGitResult.exitCode).toBe(0);
+
+      const tsGraphResult = await runCLICommand("graph", [], tsProject);
+      expect(tsGraphResult.exitCode).toBe(0);
+
+      // Python project with git repo
+      const pyProject = createGitRepo({
+        "main.py": "def main(): pass",
+        "requirements.txt": "flask==2.0.0",
+      });
+      tempDirs.push(pyProject);
+
+      await runInitCommand([], pyProject);
+      const pyGitResult = await runCLICommand("git", [], pyProject);
+      expect(pyGitResult.exitCode).toBe(0);
+    });
+
+    it("should handle concurrent command execution", async () => {
+      const projects = [
+        createTempProjectDir({ "package.json": '{"name": "concurrent1"}', "src/index.js": "const x = 1;" }),
+        createTempProjectDir({ "package.json": '{"name": "concurrent2"}', "src/index.js": "const y = 2;" }),
+        createTempProjectDir({ "package.json": '{"name": "concurrent3"}', "src/index.js": "const z = 3;" }),
+      ];
+      tempDirs.push(...projects);
+
+      // Run init on all projects
+      const initPromises = projects.map(p => runInitCommand([], p));
+      const initResults = await Promise.all(initPromises);
+      initResults.forEach(r => expect(r.exitCode).toBe(0));
+
+      // Run graph on all projects concurrently
+      const graphPromises = projects.map(p => runCLICommand("graph", [], p));
+      const graphResults = await Promise.all(graphPromises);
+      graphResults.forEach(r => expect(r.exitCode).toBe(0));
+    });
+  });
+
+  // =========================================================================
+  // VERIFICATION CHECKLIST TESTS
+  // =========================================================================
+
+  describe("Verification Checklist", () => {
+    it("should verify git command on express-api project", async () => {
+      // This project has a .git directory
+      const hasGit = fs.existsSync(path.join(EXPRESS_API_PATH, ".git"));
+      
+      if (hasGit) {
+        const result = await runCLICommand("git", [], EXPRESS_API_PATH);
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toContain("Recent files:");
+      } else {
+        // Skip if not a git repo
+        expect(true).toBe(true);
+      }
+    });
+
+    it("should verify graph command on express-api project", async () => {
+      const result = await runCLICommand("graph", [], EXPRESS_API_PATH);
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toMatch(/Building knowledge graph|Graph Statistics/);
+    });
+
+    it("should verify git command exists via git --help", async () => {
+      const testProject = createGitRepo({
+        "package.json": '{"name": "git-help-test"}',
+      });
+      tempDirs.push(testProject);
+
+      const result = await runCLICommand("git", ["--help"], testProject);
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain("git");
+    });
+
+    it("should verify graph command exists via graph --help", async () => {
+      const testProject = createTempProjectDir({
+        "package.json": '{"name": "graph-help-test"}',
+      });
+      tempDirs.push(testProject);
+
+      const result = await runCLICommand("graph", ["--help"], testProject);
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain("graph");
+    });
+
+    it("should verify update command exists via update --help", async () => {
+      const testProject = createTempProjectDir({
+        "package.json": '{"name": "update-help-test"}',
+      });
+      tempDirs.push(testProject);
+
+      const result = await runCLICommand("update", ["--help"], testProject);
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain("update");
+    });
+
+    it("should verify CLI basic functionality", async () => {
+      const result = await runCLICommand("--help", []);
+      // --help is treated as unknown command, exits with 1
+      expect(result.exitCode).toBe(1);
+      expect(result.stdout).toContain("Unknown command");
+    });
+  });
+});