@aroman22/codegraph-vba 1.17.2 → 2.1.0

package/README.md

@@ -57,14 +57,14 @@ See [fork capabilities and lineage](docs/fork-capabilities.md) for the delivered
 
 **Why fork?** To add VBA / Access language support that does not exist upstream, so agents can navigate Microsoft Access projects managed by Dysflow the same way they navigate TypeScript or Python today. See the [VBA / Access + Dysflow integration](#vba--access--dysflow-integration) section below for the feature spec, the pattern table, and the hard invariants.
 
-**The fork is published to npm as `@aroman22/codegraph-vba`.** The upstream package `@colbymchenry/codegraph` does **not** have VBA / Access support — install `@aroman22/codegraph-vba` to get it:
+**The fork ships through [GitHub Releases](https://github.com/ardelperal/codegraph-vba/releases).** The upstream package `@colbymchenry/codegraph` does **not** have VBA / Access support — install this fork to get it:
 
 ```bash
-# Option A — install from npm (easiest; gets you the codegraph-vba CLI on PATH):
-npm i -g @aroman22/codegraph-vba
-# or with pnpm:
-pnpm add -g codegraph-vba
-# or the one-line OS installer (no Node required) — see Get Started below.
+# Option A — one-line installer from GitHub Releases (no Node, no npm):
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/ardelperal/codegraph-vba/main/install.sh | sh
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/ardelperal/codegraph-vba/main/install.ps1 | iex
 ```
 
 ```bash
@@ -98,17 +98,15 @@ curl -fsSL https://raw.githubusercontent.com/ardelperal/codegraph-vba/main/insta
 irm https://raw.githubusercontent.com/ardelperal/codegraph-vba/main/install.ps1 | iex
 ```
 
-<details>
-<summary><b>Already have Node? Use npm instead (works on any version)</b></summary>
-
-```bash
-npm i -g @aroman22/codegraph-vba
-```
-
 <sub>CodeGraph bundles its own runtime — nothing to compile, no native build, works the same everywhere. The installer puts `codegraph-vba` on your PATH but **doesn't change your current shell** — open a new terminal before the next step so the command resolves.</sub>
 
 <sub>**Upgrade any time** with `codegraph-vba upgrade` — it detects how you installed (bundle, npm, or npx) and updates in place. Add `--check` to see if an update is available, or `codegraph-vba upgrade <version>` to pin one.</sub>
 
+<details>
+<summary><b>npm (legacy)</b></summary>
+
+The npm package `@aroman22/codegraph-vba` is published only on a best-effort basis and can lag behind GitHub Releases. Prefer the installer above; if you already installed through npm, re-run the installer to switch.
+
 </details>
 
 ### 2. Wire up your agent(s)
@@ -119,7 +117,7 @@ In a **new terminal**, run the installer to connect CodeGraph to the agents you
 codegraph-vba install
 ```
 
-<sub>Detects and auto-configures Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro — wiring the CodeGraph MCP server into each. **This is the step that connects CodeGraph to your agent;** installing the CLI in step 1 does not do it on its own. It only wires up your agent — it does **not** index any code; building each project's graph is the separate `codegraph-vba init` in step 3. (Shortcut: `npx codegraph-vba` downloads and runs this in one go.)</sub>
+<sub>Detects and auto-configures Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro — wiring the CodeGraph MCP server into each. **This is the step that connects CodeGraph to your agent;** installing the CLI in step 1 does not do it on its own. It only wires up your agent — it does **not** index any code; building each project's graph is the separate `codegraph-vba init` in step 3.</sub>
 
 ### 3. Initialize each project
 
@@ -128,7 +126,7 @@ cd your-project
 codegraph-vba init
 ```
 
-<sub>`codegraph-vba init` creates the local `.codegraph-vba/` directory and builds the full graph in the same step — one command, done.</sub>
+<sub>`codegraph-vba init` creates the local `.codegraph/` directory and builds the full graph in the same step — one command, done.</sub>
 
 <div align="center">
 
@@ -148,7 +146,7 @@ Changed your mind? One command removes CodeGraph from every agent it configured:
 codegraph-vba uninstall
 ```
 
-<sub>Reverses the installer — strips CodeGraph's MCP server config, instructions, and permissions from each configured agent. Your project indexes (`.codegraph-vba/`) are left untouched; remove those per-project with `codegraph-vba uninit`. Use `--target` to remove from specific agents, or `--yes` to run non-interactively.</sub>
+<sub>Reverses the installer — strips CodeGraph's MCP server config, instructions, and permissions from each configured agent. Your project indexes (`.codegraph/`) are left untouched; remove those per-project with `codegraph-vba uninit`. Use `--target` to remove from specific agents, or `--yes` to run non-interactively.</sub>
 
 ---
 
@@ -552,8 +550,10 @@ payload as JSON.
 
 ### 1. Run the Installer
 
+Install the CLI (see [Get Started](#get-started)), then run:
+
 ```bash
-npx codegraph-vba
+codegraph-vba install
 ```
 
 The installer will:
@@ -595,14 +595,15 @@ codegraph-vba init
 
 Builds the per-project knowledge graph index, which then auto-syncs on every file change. A single global `codegraph-vba install` works in every project you open — no need to re-run the installer per project.
 
-That's it — your agent will use CodeGraph tools automatically when a `.codegraph-vba/` directory exists.
+That's it — your agent will use CodeGraph tools automatically when a `.codegraph/` directory exists.
 
 <details>
 <summary><strong>Manual Setup (Alternative)</strong></summary>
 
-**Install globally:**
+**Install the CLI:**
 ```bash
-npm i -g @aroman22/codegraph-vba
+curl -fsSL https://raw.githubusercontent.com/ardelperal/codegraph-vba/main/install.sh | sh   # macOS / Linux
+irm https://raw.githubusercontent.com/ardelperal/codegraph-vba/main/install.ps1 | iex        # Windows
 ```
 
 **Add to `~/.claude.json`:**
@@ -641,7 +642,7 @@ CodeGraph's MCP server delivers its usage guidance to your agent **automatically
 - **Answer structural questions directly with CodeGraph** — it *is* the pre-built index, so a grep/read loop just repeats work it already did. Treat the returned source as already read.
 - **Reach for `codegraph_explore` for almost anything** — "how does X work", a flow/"how does X reach Y", or surveying an area. One call returns the relevant symbols' verbatim source grouped by file, the call paths between them (dynamic-dispatch hops included), and a blast-radius summary. Name a file or symbol in the query to read its current line-numbered source.
 - **Trust the results — don't re-verify with grep**, and check the staleness banner after edits.
-- Works **per project**: query any project that has a `.codegraph-vba/` index by passing `projectPath` — so a monorepo where only some services are indexed, or a second repo, works in one session. A path with no index returns clean guidance to use built-in tools; indexing stays your decision.
+- Works **per project**: query any project that has a `.codegraph/` index by passing `projectPath` — so a monorepo where only some services are indexed, or a second repo, works in one session. A path with no index returns clean guidance to use built-in tools; indexing stays your decision.
 
 The exact text is `src/mcp/server-instructions.ts` — the single source of truth for the main agent. Because subagents and non-MCP harnesses never see the MCP guidance, the installer also writes a short marker-fenced section into the agent's instructions file pointing at the `codegraph-vba explore` CLI equivalent.
 
@@ -674,7 +675,7 @@ The exact text is `src/mcp/server-instructions.ts` — the single source of trut
 
 1. **Extraction** — [tree-sitter](https://tree-sitter.github.io/) parses source code into ASTs. Language-specific queries extract nodes (functions, classes, methods) and edges (calls, imports, extends, implements).
 
-2. **Storage** — Everything goes into a local SQLite database (`.codegraph-vba/codegraph.db`) with FTS5 full-text search.
+2. **Storage** — Everything goes into a local SQLite database (`.codegraph/codegraph.db`) with FTS5 full-text search.
 
 3. **Resolution** — After extraction, references are resolved: function calls → definitions, imports → source files, class inheritance, and framework-specific patterns.
 
@@ -750,7 +751,7 @@ When running as an MCP server, CodeGraph exposes a **single tool** — `codegrap
 
 The other tools (`codegraph_node`, `codegraph_search`, `codegraph_callers`, `codegraph_callees`, `codegraph_impact`, `codegraph_files`, `codegraph_status`, and the Access-specific `codegraph_behavior_evidence`) stay fully functional but **unlisted by default** — everything they return already arrives inline on `codegraph_explore` (its blast-radius section, the relationship map, a symbol's body as its callee list). Re-enable any of them for the MCP surface with the `CODEGRAPH_MCP_TOOLS` environment variable (e.g. `CODEGRAPH_MCP_TOOLS=explore,node,search,callers`), or use their CLI equivalents (`codegraph-vba node` / `query` / `callers` / `callees` / `impact` / `files` / `status`).
 
-Even when the server's own root has no `.codegraph-vba/` index, the tools stay available: pass `projectPath` to query any indexed project — a sub-service in a monorepo, or a second repo — in the same session. A path that has no index returns clean guidance to use built-in tools instead, so nothing fails loudly, and indexing stays your decision.
+Even when the server's own root has no `.codegraph/` index, the tools stay available: pass `projectPath` to query any indexed project — a sub-service in a monorepo, or a second repo — in the same session. A path that has no index returns clean guidance to use built-in tools instead, so nothing fails loudly, and indexing stays your decision.
 
 ---
 
@@ -883,9 +884,9 @@ compile) for all three desktop OSes, on both Intel/AMD (x64) and ARM (arm64):
 
 | Platform | Architectures | Install |
 |----------|---------------|---------|
-| Windows | x64, arm64 | PowerShell installer or npm |
-| macOS | x64, arm64 | shell installer or npm |
-| Linux | x64, arm64 | shell installer or npm |
+| Windows | x64, arm64 | PowerShell installer |
+| macOS | x64, arm64 | shell installer |
+| Linux | x64, arm64 | shell installer |
 
 See [Get Started](#get-started) for the one-line install commands.
 
@@ -972,8 +973,8 @@ Framework routing is validated the same way, on a canonical app per framework: E
 
 **MCP hits `database is locked`** — current builds shouldn't: CodeGraph bundles its own Node runtime and uses Node's built-in `node:sqlite` in WAL mode, where concurrent reads never block on a writer. If you still see it:
 
-- **You're on an old (pre-0.9) install.** Reinstall to get the bundled runtime — `curl -fsSL https://raw.githubusercontent.com/ardelperal/codegraph-vba/main/install.sh | sh` (macOS/Linux), `irm https://raw.githubusercontent.com/ardelperal/codegraph-vba/main/install.ps1 | iex` (Windows), or `npm i -g @aroman22/codegraph-vba@latest`.
-- **`codegraph-vba status` shows `Journal:` other than `wal`** — WAL couldn't be enabled on this filesystem (common on network shares and WSL2 `/mnt`), so reads can block on writes. Move the project (with its `.codegraph-vba/` folder) onto a local disk.
+- **You're on an old (pre-0.9) install.** Reinstall to get the bundled runtime — `curl -fsSL https://raw.githubusercontent.com/ardelperal/codegraph-vba/main/install.sh | sh` (macOS/Linux), `irm https://raw.githubusercontent.com/ardelperal/codegraph-vba/main/install.ps1 | iex` (Windows).
+- **`codegraph-vba status` shows `Journal:` other than `wal`** — WAL couldn't be enabled on this filesystem (common on network shares and WSL2 `/mnt`), so reads can block on writes. Move the project (with its `.codegraph/` folder) onto a local disk.
 
 **MCP server not connecting** — Your agent starts the server itself, so you don't launch it by hand. Make sure the project is initialized and indexed (`codegraph-vba status`) and that the path in your MCP config is correct. If it still won't connect, re-run `codegraph-vba install` to rewrite the config.
 
@@ -981,7 +982,7 @@ Framework routing is validated the same way, on a canonical app per framework: E
 
 **Missing symbols** — The MCP server auto-syncs on save (wait a couple seconds). Run `codegraph-vba sync` manually if needed. Check that the file's language is supported and isn't inside a `.gitignore`d or default-excluded directory (e.g. `node_modules`, `dist`).
 
-**Sharing one checkout between Windows and WSL** — Don't point both at the same `.codegraph-vba/`: the background-server lock and the SQLite index are tied to the OS that wrote them, and SQLite locking across the WSL2/Windows filesystem boundary is unreliable. Give each side its own index in the same tree by setting `CODEGRAPH_DIR` to a distinct name on one of them — e.g. `CODEGRAPH_DIR=.codegraph-win` on Windows, leaving WSL on the default `.codegraph-vba`. CodeGraph skips any sibling `.codegraph-*` directory when indexing and watching, so the two never trip over each other.
+**Sharing one checkout between Windows and WSL** — Don't point both at the same `.codegraph/`: the background-server lock and the SQLite index are tied to the OS that wrote them, and SQLite locking across the WSL2/Windows filesystem boundary is unreliable. Give each side its own index in the same tree by setting `CODEGRAPH_DIR` to a distinct name on one of them — e.g. `CODEGRAPH_DIR=.codegraph-win` on Windows, leaving WSL on the default `.codegraph`. CodeGraph skips any sibling `.codegraph-*` directory when indexing and watching, so the two never trip over each other.
 
 ## Star History
 

package/dist/directory.d.ts

@@ -36,7 +36,9 @@ export declare const CODEGRAPH_DIR: string;
  * default `.codegraph`, the active `CODEGRAPH_DIR` override, and any
  * `.codegraph-*` sibling. File-watching and the indexer skip ALL of these, so
  * when two environments share one working tree (Windows + WSL, issue #636)
- * neither indexes or watches the other's index directory.
+ * neither indexes or watches the other's index directory. The prefix match
+ * also covers the legacy `.codegraph-vba/` directory older releases of this
+ * fork wrote, so a stale one left in a consumer repo is never indexed.
  */
 export declare function isCodeGraphDataDir(name: string): boolean;
 /**

package/dist/upgrade/index.d.ts

@@ -26,6 +26,13 @@
 export declare const REPO = "ardelperal/codegraph-vba";
 export declare const NPM_PACKAGE = "@aroman22/codegraph-vba";
 export declare const INSTALL_SH_URL = "https://raw.githubusercontent.com/ardelperal/codegraph-vba/main/install.sh";
+export declare const INSTALL_PS1_URL = "https://raw.githubusercontent.com/ardelperal/codegraph-vba/main/install.ps1";
+/**
+ * The one-line shell command that installs the CLI from GitHub Releases on
+ * this platform (issue #326 — no npm). Used both to run the install and in
+ * user-facing hints, so the two can never disagree.
+ */
+export declare function cliInstallCommand(platform: NodeJS.Platform): string;
 export type InstallMethod = {
     kind: 'bundle';
     os: 'unix' | 'windows';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aroman22/codegraph-vba",
-  "version": "1.17.2",
+  "version": "2.1.0",
   "description": "Local-first code intelligence for AI agents (MCP). Self-contained — bundles its own runtime.",
   "bin": {
     "codegraph-vba": "npm-shim.js"
@@ -15,12 +15,12 @@
     "./package.json": "./package.json"
   },
   "optionalDependencies": {
-    "@aroman22/codegraph-vba-darwin-arm64": "1.17.2",
-    "@aroman22/codegraph-vba-darwin-x64": "1.17.2",
-    "@aroman22/codegraph-vba-linux-arm64": "1.17.2",
-    "@aroman22/codegraph-vba-linux-x64": "1.17.2",
-    "@aroman22/codegraph-vba-win32-arm64": "1.17.2",
-    "@aroman22/codegraph-vba-win32-x64": "1.17.2"
+    "@aroman22/codegraph-vba-darwin-arm64": "2.1.0",
+    "@aroman22/codegraph-vba-darwin-x64": "2.1.0",
+    "@aroman22/codegraph-vba-linux-arm64": "2.1.0",
+    "@aroman22/codegraph-vba-linux-x64": "2.1.0",
+    "@aroman22/codegraph-vba-win32-arm64": "2.1.0",
+    "@aroman22/codegraph-vba-win32-x64": "2.1.0"
   },
   "files": [
     "npm-shim.js",