basemind-opencode 0.2.6 → 0.4.0-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basemind-opencode",
-  "version": "0.2.6",
+  "version": "0.4.0-rc.1",
   "description": "Full AI context layer over MCP — tree-sitter code-map, document RAG (PDF/Office/HTML/email + OCR + reranker), shared agent memory, on-demand web crawl, git history + blame + per-symbol diff. 300+ languages, 8 coding-agent harnesses, content-addressed Fjall + LanceDB.",
   "keywords": [
     "agent-context",

package/skills/basemind-cli/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: basemind-cli
+description: >-
+  Navigate codebases and manage caches via the basemind CLI — outlines, symbol search,
+  reference/caller lookups, git history, blame, and diffs. For headless scripting, CI, or when
+  driving the CLI more efficiently than interactive MCP calls. Shares the same index as the
+  MCP server.
+---
+
+# basemind CLI — the scriptable interface
+
+basemind has two equally-weighted surfaces: MCP (interactive tool calls) and CLI (scriptable commands).
+They share the same `.basemind/` index and are safe to run alongside each other. Reach for the CLI
+when you're scripting, batching queries, running in headless environments, or CI.
+
+## Capabilities
+
+- **Code map across 300+ languages** — tree-sitter outlines, symbol search, references, callers,
+  call graphs, implementations, dependents.
+- **Full-text + symbol search** — indexed regex over content and substring symbol lookup.
+- **Git intelligence** — history, blame, and structural diffs at symbol resolution, plus churn.
+- **Document RAG over 90+ file formats** — PDFs, Office, HTML, email, images (OCR) → semantic search.
+- **Shared memory** — per-repo, scope-keyed key-value + semantic memory across sessions.
+- **Web crawl** — scrape / follow-link crawl into the searchable document store.
+- **Cache management** — stats, garbage collection, selective and full clears.
+
+## When to reach for it
+
+- Running in headless environments or CI pipelines.
+- Batching multiple queries without interactive delays.
+- Integrating basemind into shell scripts or non-MCP tooling.
+- Controlling tool routing explicitly (no agent routing decisions).
+- Clearing caches destructively (only the CLI allows `--component all`).
+
+## Command routing (copy this into your mental model)
+
+| Question | Command | Notes |
+|---|---|---|
+| "Where is X defined?" | `basemind query symbol "X"` | Substring match, optional `--kind` filter. |
+| "What's the shape of file F?" | `basemind query outline path/F` | Add `--l2` for calls + docs. |
+| "What calls X?" (any name) | `basemind query references "X"` | Name match, no scope resolution. |
+| "What calls this specific definition?" | `basemind query callers path name [--kind]` | Specific definition lookup. |
+| "Trace the call graph?" | `basemind query call-graph "name" [--direction --max-depth]` | BFS over calls. |
+| "What implements / extends X?" | `basemind query implementations "X"` | Rust, Python, TS/TSX, JS. |
+| "What imports module M?" | `basemind query dependents "M"` | Reverse-lookup via imports. |
+| "What files are indexed?" | `basemind query list-files [--language --path-contains]` | Filter by language/path. |
+| "What changed recently?" | `basemind git recent-changes [--limit N]` | Recent commits with paths. |
+| "When did symbol X last change?" | `basemind git symbol-history path name` | Cross-commit structural hash. |
+| "Who wrote this line / symbol?" | `basemind git blame-file path` / `blame-symbol path name` | Per-line / per-symbol. |
+| "Where's the churn?" | `basemind git hot-files [--limit N]` | Churn-ranked files. |
+| "What's dirty in the working tree?" | `basemind git working-tree-status` | Staged/unstaged summary. |
+| "Diff a file between revs?" | `basemind git diff-file path old new` / `diff-outline path` | File / outline diffs. |
+| "What's indexed?" | `basemind query status` | File count, languages, cache dir. |
+| "What's HEAD / branch?" | `basemind query repo-info` | Branch, HEAD, origin. |
+| "Regex over file contents?" | `basemind query grep "pattern" [--language --path-contains]` | Full-text search. |
+| "Semantic search over docs?" | `basemind memory search-documents "query"` | Needs `documents` feature. |
+| "Recall something stored earlier?" | `basemind memory get "key"` / `list` / `search "q"` | KNN + exact match. |
+| "Remember this for future sessions?" | `basemind memory put "key" "value"` | Delete with `memory delete "key"`. |
+| "Cache size?" | `basemind cache stats` | On-disk size + orphan accounting. |
+| "Reclaim cache space?" | `basemind cache gc` | Reclaim orphaned blobs. Safe alongside serve. |
+| "Clear caches?" | `basemind cache clear --component blobs\|views\|all` | Destructive; use CLI not MCP. |
+| "Pull this URL into RAG?" | `basemind web scrape <url>` | Single page (requires `--features crawl`). |
+| "Ingest a docs site?" | `basemind web crawl <seed-url>` | Link-following crawl. |
+| "What URLs exist on this site?" | `basemind web map <url>` | Sitemap + link discovery. |
+| "Keep index fresh?" | `basemind watch [--no-serve]` | Live re-index. `--no-serve` = no MPC server. |
+| "Refresh the index after edits?" | `basemind scan` | Full or incremental scan. |
+| "Per-tool activity summary?" | `basemind telemetry` | Histogram + estimated tokens saved. |
+
+## Output format
+
+By default, all commands return **human-readable text**. For machine consumption, add the global `--json` flag:
+
+```bash
+basemind query symbol "parseQuery" --json
+```
+
+This returns the raw `JsonSchema`-derived response structure, same as MCP.
+
+## Setup (one-time per repo)
+
+```sh
+basemind scan
+```
+
+This walks the tree, parses with tree-sitter, and writes the content-addressed blob store +
+Fjall inverted index under `.basemind/`. A few seconds for small repos, ~22 s for an ~80k-file
+TypeScript monorepo.
+
+Re-run `basemind scan` after large changes, or run `basemind watch` to keep the index fresh.
+
+## Examples
+
+### Find where a symbol is defined
+
+```bash
+basemind query symbol "MapCache"
+```
+
+Output:
+
+```text
+src/mcp/mod.rs:79:1 MapCache (struct)
+src/mcp/mod.rs:88:1 MapCache (impl)
+```
+
+### Show a file's outline before opening it
+
+```bash
+basemind query outline src/mcp/tools.rs --l2
+```
+
+### Get all references to a function
+
+```bash
+basemind query references "process_file"
+```
+
+### Find all callers of a specific definition
+
+```bash
+basemind query callers src/scanner.rs "process_file" --json
+```
+
+### Show recent commits with changed files
+
+```bash
+basemind git recent-changes --limit 5
+```
+
+### Blame a symbol to see when its body last changed
+
+```bash
+basemind git blame-symbol src/scanner.rs "process_file"
+```
+
+### Manage cache space
+
+```bash
+basemind cache stats
+basemind cache gc          # reclaim orphaned blobs
+basemind cache clear --component blobs  # clear blobs only
+```
+
+## Notes
+
+- All paths are repository-relative with forward-slash separators.
+- The CLI opens the index read-only; safe to run alongside a live `basemind serve` process.
+- Lists are capped (`--limit`, default 100, max 1000).
+- Matching on symbol names is substring-based; `find_references("bar")` matches `Foo::bar()` and `bar()` alike.
+- Git tools require basemind to be running inside a git repository.
+- Intelligence tools (`search_documents`, `memory_*`) require basemind to be built with `--features full`
+  (or the individual `documents` / `memory` flags).
+- Memory is scoped by the normalized `origin` remote URL — clones of the same repo share memory;
+  unrelated repos do not see each other's entries.
+- Web ingestion tools (`web_scrape`, `web_crawl`, `web_map`) require `--features crawl`.