@hiveai/cli 0.2.7 → 0.2.9

package/README.md

@@ -0,0 +1,406 @@
+# @hiveai/cli
+
+> **hAIve** — team-first persistent memory layer for AI coding agents.
+
+Stop re-explaining your project to every AI session. hAIve stores your team's conventions, architectural decisions, gotchas, and discovered patterns as version-controlled Markdown files. Every AI tool on your team reads the same shared knowledge automatically — via the MCP server, bridge files (CLAUDE.md, .cursorrules, Copilot instructions), or the CLI directly.
+
+---
+
+## Install
+
+```bash
+npm install -g @hiveai/cli
+```
+
+This installs the `haive` command globally.
+
+> **MCP server**: also install `@hiveai/mcp` to expose memories to Claude Code, Cursor, Copilot, and any MCP-compatible AI client.
+> **Semantic search** (optional): install `@hiveai/embeddings` for local embedding-based search (no data leaves your machine).
+
+---
+
+## Quick start
+
+```bash
+# 1. Initialize hAIve in your project
+cd my-project
+haive init
+
+# 2. Start the MCP server (in Claude Code / Cursor MCP config)
+haive mcp --root /absolute/path/to/my-project
+
+# 3. Add a team memory
+haive memory add \
+  --type gotcha \
+  --slug "open-in-view-false" \
+  --scope team \
+  --paths src/main/resources/application.properties \
+  --body "spring.jpa.open-in-view=false is intentional — do not re-enable."
+
+# 4. Browse memories
+haive memory list --scope team
+
+# 5. Get a briefing before a task
+haive briefing --task "add a payment endpoint" --scope team
+
+# 6. Sync after a git pull
+haive sync
+```
+
+---
+
+## Commands
+
+### `haive init`
+
+Initialize the `.ai/` structure in a project and generate bridge files for your AI tools.
+
+```bash
+haive init                    # Creates .ai/, CLAUDE.md, .cursorrules, copilot-instructions.md
+haive init --no-bridges       # Skip bridge file generation
+haive init --with-ci          # Also write .github/workflows/haive-sync.yml
+haive init --dir /other/path  # Initialize in a specific directory
+```
+
+**What it creates:**
+
+```
+your-project/
+├── .ai/
+│   ├── project-context.md        # Shared project overview (fill via bootstrap_project MCP prompt)
+│   ├── modules/                  # Per-component context files
+│   └── memories/
+│       ├── personal/             # Private to one developer
+│       ├── team/                 # Shared with the whole team (git-committed)
+│       └── module/<name>/        # Scoped to a specific module/component
+├── CLAUDE.md                     # Bridge for Claude Code (auto-generated)
+├── .cursorrules                  # Bridge for Cursor (auto-generated)
+└── .github/
+    └── copilot-instructions.md   # Bridge for GitHub Copilot (auto-generated)
+```
+
+Bridge files include mandatory rules that tell agents to call `post_task` and `mem_tried` before closing a session, so knowledge is captured automatically.
+
+---
+
+### `haive mcp`
+
+Start the hAIve MCP server over stdio. Point your AI client at this binary.
+
+```bash
+haive mcp                           # Auto-detect project root
+haive mcp --root /path/to/project   # Explicit project root
+```
+
+**Claude Code** (`~/.claude.json`):
+```json
+{
+  "mcpServers": {
+    "haive": {
+      "command": "haive-mcp",
+      "args": ["--root", "/absolute/path/to/your/project"]
+    }
+  }
+}
+```
+
+**Cursor** (`~/.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "haive": {
+      "command": "haive-mcp",
+      "args": ["--root", "/absolute/path/to/your/project"]
+    }
+  }
+}
+```
+
+**VS Code**:
+```bash
+code --add-mcp '{"name":"haive","command":"haive-mcp","args":["--root","/path/to/project"]}'
+```
+
+---
+
+### `haive memory`
+
+Manage individual memory entries.
+
+#### `haive memory add`
+
+```bash
+haive memory add \
+  --type <type> \          # convention | decision | gotcha | architecture | glossary | attempt
+  --slug <slug> \          # Short identifier used in the filename
+  --scope team \           # personal (default) | team | module
+  --title "My title" \     # Optional heading (auto-added to body)
+  --tags "auth,jwt" \      # Comma-separated tags
+  --domain payments \      # Business domain for relevance scoring
+  --paths src/auth.ts \    # Anchor to files (enables staleness detection)
+  --symbols JwtFilter \    # Anchor to symbols/functions
+  --body "The knowledge."  # Memory content (Markdown)
+
+# Read body from a file (useful for long memories):
+haive memory add --type architecture --slug "payment-flow" \
+  --body-file docs/payment-architecture.md
+```
+
+**Memory types:**
+
+| Type | When to use |
+|---|---|
+| `convention` | How things are done here: naming, patterns, workflow |
+| `decision` | A choice that was made and WHY (tradeoffs, constraints) |
+| `gotcha` | Non-obvious behavior, traps, things that surprise newcomers |
+| `architecture` | Structural overview of a system or module |
+| `glossary` | Domain terms and their meaning in this project |
+| `attempt` | Failed approach — prevents the same mistake next session |
+
+#### `haive memory list`
+
+```bash
+haive memory list                        # All memories
+haive memory list --scope team           # Team memories only
+haive memory list --status validated     # Only validated
+haive memory list --type gotcha          # Gotchas only
+haive memory list --tags auth,jwt        # By tags (AND match)
+haive memory list --module payments      # Module-scoped memories
+```
+
+#### `haive memory query`
+
+Full-text search across id, tags, and body.
+
+```bash
+haive memory query "flyway migration"         # AND search across all tokens
+haive memory query "payment mobile wave"      # Falls back to OR if no AND match
+haive memory query "jwt" --scope team --limit 5
+```
+
+#### `haive memory show`
+
+Print the full body, frontmatter, and usage stats of a memory.
+
+```bash
+haive memory show 2025-01-15-gotcha-flyway-strict
+```
+
+#### `haive memory update`
+
+Update a memory's body, tags, or anchor without changing its id or history.
+
+```bash
+haive memory update <id> --body "Updated content."
+haive memory update <id> --tags "auth,jwt,security"
+haive memory update <id> --paths src/auth.ts,src/jwt.ts
+```
+
+#### `haive memory verify`
+
+Check anchor freshness — detect stale memories when anchored files or symbols have moved.
+
+```bash
+haive memory verify           # Check all memories
+haive memory verify --id <id> # Check a specific one
+haive memory verify --update  # Write stale/validated status back to disk
+```
+
+When a file is missing, hAIve searches the project for files with the same basename and suggests possible renames.
+
+#### `haive memory approve` / `promote` / `reject`
+
+Control the memory lifecycle: `draft → proposed → validated` or `rejected`.
+
+```bash
+haive memory approve <id>       # Mark as validated
+haive memory approve --all      # Bulk-approve all proposed/draft
+haive memory promote <id>       # Promote personal → team (status: proposed)
+haive memory reject <id> --reason "Outdated after refactor"
+```
+
+#### `haive memory tried`
+
+Record a failed approach — the most valuable type of negative knowledge.
+
+```bash
+haive memory tried \
+  --what "importing gray-matter with ESM dynamic import" \
+  --why-failed "gray-matter doesn't export a default; named import required" \
+  --instead "import matter from 'gray-matter'" \
+  --scope team \
+  --paths src/parser.ts
+```
+
+Auto-validated (no approval cycle needed). Surfaced first in `get_briefing` so agents see it before making the same mistake.
+
+#### `haive memory import`
+
+Import documentation (README, ADR, wiki page) as memories via the `import_docs` MCP prompt.
+
+```bash
+haive memory import --from docs/architecture.md --scope team
+```
+
+Prints the MCP `import_docs` invocation to run in your AI client.
+
+#### `haive memory for-files`
+
+Show memories relevant to specific files you're about to edit.
+
+```bash
+haive memory for-files src/payments/PaymentService.java src/payments/PaymentController.java
+```
+
+#### `haive memory stats` / `hot` / `pending`
+
+```bash
+haive memory stats     # Usage stats and confidence levels for all memories
+haive memory hot       # Most-read unvalidated memories (good promotion candidates)
+haive memory pending   # Proposed memories awaiting review
+```
+
+---
+
+### `haive briefing`
+
+Print the full project briefing — project context + relevant memories — in one shot. Use before starting a task.
+
+```bash
+haive briefing                                      # Full briefing, team scope
+haive briefing --task "add a Stripe payment"        # Filter by task relevance
+haive briefing --files src/payments/PaymentService.java  # Filter by files
+haive briefing --scope all                          # Include personal memories
+haive briefing --include-stale                      # Include stale memories
+haive briefing --max-memories 15                    # Show more memories
+```
+
+---
+
+### `haive sync`
+
+Refresh memory state after a `git pull` or merge.
+
+```bash
+haive sync                          # Verify anchors + auto-promote eligible memories
+haive sync --since main             # Report memories changed since main
+haive sync --inject-bridge          # Inject top memories into CLAUDE.md
+haive sync --embed                  # Rebuild embeddings index after sync
+haive sync --quiet                  # Minimal output (for git hooks)
+```
+
+**What sync does:**
+1. Checks every anchored memory: does the file/symbol still exist? → marks `stale` if not
+2. Re-validates previously stale memories that are now fresh again
+3. Auto-promotes `proposed` memories that have been read enough times
+4. Reports a decay warning for memories not read in >90 days
+5. Optionally injects the top validated memories into your CLAUDE.md
+
+---
+
+### `haive install-hooks`
+
+Install git hooks so `haive sync` runs automatically after every pull/merge.
+
+```bash
+haive install-hooks         # Install post-merge and post-rewrite hooks
+haive install-hooks --dir /path/to/project
+```
+
+---
+
+### `haive embeddings`
+
+Manage the local semantic search index (requires `@hiveai/embeddings` to be installed).
+
+```bash
+haive embeddings index          # Build or refresh the embeddings index
+haive embeddings status         # Show index stats (count, last updated, model)
+haive embeddings query "how do we handle retries on payment failures"
+```
+
+The model (`bge-small-en-v1.5`, ~110MB) is downloaded on first use and cached locally. **No data leaves your machine.**
+
+---
+
+### `haive index`
+
+Build code navigation indexes.
+
+```bash
+haive index code        # Build .ai/code-map.json (file → exports + 1-line descriptions)
+```
+
+The code map lets AI agents find where a function lives without grepping — dramatically reducing tool calls at the start of a task.
+
+---
+
+### `haive tui`
+
+Interactive terminal dashboard to browse, filter, and manage memories.
+
+```bash
+haive tui               # Open the TUI (q to quit, arrow keys to navigate)
+haive tui --dir /path/to/project
+```
+
+---
+
+## Memory lifecycle
+
+```
+haive memory add        → status: draft
+haive memory promote    → status: proposed  (personal → team)
+haive memory approve    → status: validated
+haive sync              → status: stale     (if anchor broken)
+haive memory reject     → status: rejected
+```
+
+Validated team memories are loaded into every `get_briefing` call and injected into bridge files.
+
+---
+
+## Multi-component projects
+
+For projects with frontend + backend (or microservices), create one module context per component:
+
+```bash
+# After haive init, create module context files:
+mkdir -p .ai/modules/backend .ai/modules/frontend
+
+cat > .ai/modules/backend/context.md << 'EOF'
+# Module: backend
+- Spring Boot, Java 17, PostgreSQL
+- Always filter by tenantId in every query
+- Never modify existing Flyway migrations
+EOF
+
+cat > .ai/modules/frontend/context.md << 'EOF'
+# Module: frontend
+- React 19, TypeScript, TanStack Query
+- All API calls go through hooks in features/<domain>/api/
+- Env vars must be prefixed with VITE_
+EOF
+```
+
+`get_briefing` auto-loads the relevant module context based on the files the agent is editing.
+
+---
+
+## Semantic search (optional)
+
+Install `@hiveai/embeddings` for similarity-based memory retrieval:
+
+```bash
+npm install -g @hiveai/embeddings
+haive embeddings index          # First run downloads the model (~110MB)
+haive embeddings query "payment retry logic"
+```
+
+From MCP: set `semantic: true` on `mem_search` or `get_briefing`.
+
+---
+
+## License
+
+MIT

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command26 } from "commander";
+import { Command as Command27 } from "commander";
 
 // src/commands/briefing.ts
 import { existsSync } from "fs";
@@ -291,9 +291,49 @@ var BRIDGE_BODY = `<!-- hAIve bridge file \u2014 do not edit by hand. -->
 
 See \`.ai/project-context.md\` for the full project context.
 Memories live under \`.ai/memories/\` (personal/team/module).
+
+## hAIve \u2014 mandatory rules for AI agents
+- **Before** marking a task as done ("Done", "Finished", "C'est fait"), call the MCP prompt \`post_task\`.
+- **Immediately** when an approach fails (wrong API, wrong pattern, wrong assumption), call \`mem_tried\` \u2014 do not wait until the end of the session.
+- When starting a new task, call \`get_briefing\` with the task description to load relevant memories and avoid repeating past mistakes.
+`;
+var CI_WORKFLOW = `name: haive-sync
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    paths:
+      - '.ai/**'
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install hAIve CLI
+        run: npm install -g @haive/cli
+
+      - name: Sync memories (verify anchors + auto-promote)
+        run: haive sync --quiet
+
+      - name: Commit updated memories (if any)
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .ai/
+          git diff --cached --quiet || git commit -m "chore: haive sync [skip ci]"
+          git push
 `;
 function registerInit(program2) {
-  program2.command("init").description("Initialize a hAIve project (.ai/ structure + bridge files)").option("-d, --dir <dir>", "project root", process.cwd()).option("--no-bridges", "do not generate CLAUDE.md / .cursorrules / copilot-instructions.md").action(async (opts) => {
+  program2.command("init").description("Initialize a hAIve project (.ai/ structure + bridge files)").option("-d, --dir <dir>", "project root", process.cwd()).option("--no-bridges", "do not generate CLAUDE.md / .cursorrules / copilot-instructions.md").option("--with-ci", "write a GitHub Actions workflow (.github/workflows/haive-sync.yml)").action(async (opts) => {
     const root = path3.resolve(opts.dir);
     const paths = resolveHaivePaths4(root);
     if (existsSync3(paths.haiveDir)) {
@@ -312,6 +352,16 @@ function registerInit(program2) {
       await writeBridge(root, ".cursorrules");
       await writeBridge(root, path3.join(".github", "copilot-instructions.md"));
     }
+    if (opts.withCi) {
+      const ciPath = path3.join(root, ".github", "workflows", "haive-sync.yml");
+      if (existsSync3(ciPath)) {
+        ui.info("CI workflow already exists \u2014 skipped");
+      } else {
+        await mkdir(path3.dirname(ciPath), { recursive: true });
+        await writeFile(ciPath, CI_WORKFLOW, "utf8");
+        ui.success(`Created ${path3.relative(root, ciPath)}`);
+      }
+    }
     ui.success(`hAIve initialized at ${root}`);
     ui.info("Next: " + ui.bold("haive memory add --type convention --slug <name>"));
   });
@@ -429,6 +479,7 @@ import {
   findProjectRoot as findProjectRoot8,
   getUsage,
   isAutoPromoteEligible,
+  isDecaying,
   loadMemoriesFromDir as loadMemoriesFromDir2,
   loadUsageIndex,
   resolveHaivePaths as resolveHaivePaths5,
@@ -444,7 +495,7 @@ function registerSync(program2) {
   ).option("--no-verify", "skip the anchor verification step").option("--no-promote", "skip the auto-promotion step").option(
     "--inject-bridge",
     "inject top validated memories into CLAUDE.md (or --bridge-file) between <!-- haive:memories-start/end --> markers"
-  ).option("--bridge-file <path>", "bridge file to inject into (default: CLAUDE.md)").option("--bridge-max-memories <n>", "max memories to inject into bridge file", "5").action(async (opts) => {
+  ).option("--bridge-file <path>", "bridge file to inject into (default: CLAUDE.md)").option("--bridge-max-memories <n>", "max memories to inject into bridge file", "5").option("--embed", "rebuild embeddings index after sync (requires @haive/embeddings)").action(async (opts) => {
     const root = findProjectRoot8(opts.dir);
     const paths = resolveHaivePaths5(root);
     if (!existsSync6(paths.memoriesDir)) {
@@ -555,6 +606,33 @@ function registerSync(program2) {
         for (const f of sinceReport.removed) log(`  - ${f}`);
       }
     }
+    if (!opts.quiet) {
+      const allForDecay = await loadMemoriesFromDir2(paths.memoriesDir);
+      const usageForDecay = await loadUsageIndex(paths);
+      const decaying = allForDecay.filter(({ memory: memory2 }) => {
+        const fm = memory2.frontmatter;
+        if (fm.status === "rejected" || fm.status === "deprecated" || fm.status === "stale") return false;
+        const u = getUsage(usageForDecay, fm.id);
+        return isDecaying(u, fm.created_at);
+      });
+      if (decaying.length > 0) {
+        log(ui.yellow(`
+\u26A0  ${decaying.length} memor${decaying.length === 1 ? "y" : "ies"} not read in >90 days (consider reviewing or deprecating):`));
+        for (const { memory: memory2 } of decaying) {
+          log(ui.dim(`   ${memory2.frontmatter.id}`));
+        }
+      }
+    }
+    if (opts.embed) {
+      try {
+        const emb = await import("@hiveai/embeddings");
+        log(ui.dim("embed: rebuilding index\u2026"));
+        const report = await emb.rebuildIndex(paths);
+        log(ui.dim(`embed: index rebuilt (${report.added} added, ${report.updated} updated, ${report.removed} removed)`));
+      } catch {
+        ui.warn("--embed: @hiveai/embeddings not available or index build failed. Run `haive embeddings index` manually.");
+      }
+    }
   });
 }
 async function injectBridge(bridgeFile, memoriesDir, maxMemories, root, quiet) {
@@ -1698,6 +1776,9 @@ function registerMemoryVerify(memory2) {
         console.log(`${ui.bold("STALE")}  ${mem.frontmatter.id}`);
         console.log(`       ${ui.dim(rel)}`);
         console.log(`       ${result.reason}`);
+        if (result.possibleRenames.length > 0) {
+          console.log(`       ${ui.yellow("Possible renames:")} ${result.possibleRenames.join(", ")}`);
+        }
       } else {
         freshCount++;
         console.log(`${ui.dim("fresh")}  ${mem.frontmatter.id}`);
@@ -1751,9 +1832,60 @@ function applyVerification(mem, result) {
   };
 }
 
+// src/commands/memory-import.ts
+import { readFile as readFile7 } from "fs/promises";
+import { existsSync as existsSync24 } from "fs";
+import "commander";
+import {
+  findProjectRoot as findProjectRoot26,
+  resolveHaivePaths as resolveHaivePaths23
+} from "@hiveai/core";
+function registerMemoryImport(memory2) {
+  memory2.command("import").description(
+    "Parse a Markdown file and suggest memories via the import_docs MCP prompt (prints a ready-to-use prompt invocation)"
+  ).requiredOption("--from <file>", "Markdown/text file to import from").option("--scope <scope>", "personal | team (default: team)", "team").option("-d, --dir <dir>", "project root").action(async (opts) => {
+    const root = findProjectRoot26(opts.dir);
+    const paths = resolveHaivePaths23(root);
+    if (!existsSync24(paths.haiveDir)) {
+      ui.error(`No .ai/ found at ${root}. Run \`haive init\` first.`);
+      process.exitCode = 1;
+      return;
+    }
+    if (!existsSync24(opts.from)) {
+      ui.error(`File not found: ${opts.from}`);
+      process.exitCode = 1;
+      return;
+    }
+    const content = await readFile7(opts.from, "utf8");
+    const scope = opts.scope ?? "team";
+    ui.info(`Preparing import from: ${opts.from}  (scope=${scope})`);
+    ui.info(`Content length: ${content.length} chars`);
+    console.log();
+    console.log(ui.bold("To import via MCP, invoke the `import_docs` prompt with:"));
+    console.log();
+    console.log(
+      ui.dim(
+        JSON.stringify(
+          {
+            content: content.slice(0, 200) + (content.length > 200 ? "\u2026" : ""),
+            source: opts.from,
+            scope
+          },
+          null,
+          2
+        )
+      )
+    );
+    console.log();
+    ui.info(
+      'Or use your AI client to call: import_docs({ content: <file contents>, source: "' + opts.from + '", scope: "' + scope + '" })'
+    );
+  });
+}
+
 // src/index.ts
-var program = new Command26();
-program.name("haive").description("hAIve \u2014 team-first persistent memory layer for AI coding agents").version("0.2.7");
+var program = new Command27();
+program.name("haive").description("hAIve \u2014 team-first persistent memory layer for AI coding agents").version("0.2.9");
 registerInit(program);
 registerMcp(program);
 registerBriefing(program);
@@ -1780,6 +1912,7 @@ registerMemoryApprove(memory);
 registerMemoryUpdate(memory);
 registerMemoryHot(memory);
 registerMemoryTried(memory);
+registerMemoryImport(memory);
 program.parseAsync(process.argv).catch((err) => {
   if (isZodError(err)) {
     for (const issue of err.issues) {