@colbymchenry/codegraph 1.0.0 → 1.0.1

package/README.md

@@ -4,6 +4,8 @@
 
 ## 🎉 1.0 Released!
 
+Already installed? Run `codegraph upgrade` to update in place.
+
 Follow [@getcodegraph](https://x.com/getcodegraph) on X for updates.
 
 ### Supercharge Claude Code, Cursor, Codex, OpenCode, Hermes Agent, Gemini, Antigravity, and Kiro with Semantic Code Intelligence
@@ -53,7 +55,8 @@ curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install
 irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
 ```
 
-Already have Node? Use npm instead (works on any version):
+<details>
+<summary><b>Already have Node? Use npm instead (works on any version)</b></summary>
 
 ```bash
 npm i -g @colbymchenry/codegraph
@@ -63,6 +66,8 @@ npm i -g @colbymchenry/codegraph
 
 <sub>**Upgrade any time** with `codegraph 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 upgrade <version>` to pin one.</sub>
 
+</details>
+
 ### 2. Wire up your agent(s)
 
 In a **new terminal**, run the installer to connect CodeGraph to the agents you use:
@@ -77,10 +82,10 @@ codegraph install
 
 ```bash
 cd your-project
-codegraph init -i
+codegraph init
 ```
 
-<sub>`codegraph init` just creates the local `.codegraph/` index directory; adding `-i` (`--index`) also builds the initial graph in the same step. Without `-i`, run `codegraph index` afterwards to populate it.</sub>
+<sub>`codegraph init` creates the local `.codegraph/` directory and builds the full graph in the same step — one command, done.</sub>
 
 <div align="center">
 
@@ -88,6 +93,10 @@ codegraph init -i
 
 </div>
 
+### 4. No more syncing!
+
+Auto-sync is enabled by default. CodeGraph watches the project and updates the graph on every file change — while your agent edits code, or you add, modify, or delete files. **The index is never stale, and there is nothing to re-run.**
+
 ### Uninstall
 
 Changed your mind? One command removes CodeGraph from every agent it configured:
@@ -359,10 +368,10 @@ Restart your agent (Claude Code / Cursor / Codex CLI / opencode / Hermes Agent /
 
 ```bash
 cd your-project
-codegraph init -i
+codegraph init
 ```
 
-Builds the per-project knowledge graph index. A single global `codegraph install` works in every project you open — no need to re-run the installer per project.
+Builds the per-project knowledge graph index, which then auto-syncs on every file change. A single global `codegraph 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/` directory exists.
 
@@ -467,6 +476,7 @@ codegraph uninit [path]           # Remove CodeGraph from a project (--force to
 codegraph index [path]            # Full index (--force to re-index, --quiet for less output)
 codegraph sync [path]             # Incremental update
 codegraph status [path]           # Show statistics
+codegraph unlock [path]           # Remove a stale lock file that's blocking indexing
 codegraph query <search>          # Search symbols (--kind, --limit, --json)
 codegraph explore <query>         # Relevant symbols' source + call paths in one shot (same output as the codegraph_explore MCP tool)
 codegraph node <symbol|file>      # One symbol's source + callers, or read a file with line numbers (same output as codegraph_node)
@@ -475,8 +485,11 @@ codegraph callers <symbol>        # Find what calls a function/method (--limit,
 codegraph callees <symbol>        # Find what a function/method calls (--limit, --json)
 codegraph impact <symbol>         # Analyze what code is affected by changing a symbol (--depth, --json)
 codegraph affected [files...]     # Find test files affected by changes (see below)
-codegraph serve --mcp             # Start MCP server
+codegraph daemon                  # Manage background daemons — pick one to stop (alias: daemons)
+codegraph telemetry [on|off]      # Show or change anonymous usage telemetry
 codegraph upgrade [version]       # Update to the latest release (--check, --force)
+codegraph version                 # Print the installed version (also -v, --version)
+codegraph help [command]          # Show help, optionally for one command
 ```
 
 ### `codegraph affected`
@@ -709,7 +722,7 @@ Framework routing is validated the same way, on a canonical app per framework: E
 - **You're on an old (pre-0.9) install.** Reinstall to get the bundled runtime — `curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh` (macOS/Linux), `irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex` (Windows), or `npm i -g @colbymchenry/codegraph@latest`.
 - **`codegraph 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** — Ensure the project is initialized/indexed, verify the path in your MCP config, and check that `codegraph serve --mcp` works from the command line.
+**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 status`) and that the path in your MCP config is correct. If it still won't connect, re-run `codegraph install` to rewrite the config.
 
 **Missing symbols** — The MCP server auto-syncs on save (wait a couple seconds). Run `codegraph 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`).
 

package/dist/bin/fatal-handler.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Render an uncaught value for the last-resort log WITHOUT triggering stack
+ * formatting. Pure and total — never throws, never touches `.stack`.
+ */
+export declare function describeFatal(value: unknown): string;
+/** Injectable seams so the wiring is testable without registering real handlers. */
+export interface FatalHandlerDeps {
+    /** Event target to attach to. Defaults to `process`. */
+    target?: NodeJS.EventEmitter;
+    /** How to terminate. Defaults to `process.exit`. */
+    exit?: (code: number) => void;
+    /** How to emit the bounded line. Defaults to a synchronous fd-2 write. */
+    write?: (line: string) => void;
+}
+/**
+ * Install the uncaught-exception / unhandled-rejection handlers. Both log a
+ * bounded line and then exit non-zero (Node's default fatal semantics).
+ */
+export declare function installFatalHandlers(deps?: FatalHandlerDeps): void;
+//# sourceMappingURL=fatal-handler.d.ts.map

package/dist/directory.d.ts

@@ -57,6 +57,21 @@ export declare function isInitialized(projectRoot: string): boolean;
  * @param startPath - Directory to start searching from
  * @returns The project root containing .codegraph/, or null if not found
  */
+/**
+ * Reason a directory is unsafe to use as an index ROOT, or null when it's fine.
+ *
+ * Indexing your home directory or a filesystem root drags in caches, `Library`,
+ * every other project, etc. — a multi-GB index, constant file-watcher churn, and
+ * (pre-1.0 on macOS) a file-descriptor blowup that exhausted `kern.maxfiles` and
+ * took unrelated apps / the whole machine down (#845). The classic trigger:
+ * running the installer or `codegraph init` from `$HOME`, which auto-indexes the
+ * current directory. These are never intended project roots, so the installer
+ * and `init`/`index` refuse them (overridable with `--force`).
+ *
+ * Pure-ish (reads only `os.homedir()` + realpath) so it's easy to unit-test.
+ * The returned string is a human phrase that slots into "… looks like {reason}".
+ */
+export declare function unsafeIndexRootReason(projectRoot: string): string | null;
 export declare function findNearestCodeGraphRoot(startPath: string): string | null;
 /**
  * Create the .codegraph directory structure

package/dist/mcp/daemon-manager.d.ts

@@ -0,0 +1,42 @@
+import type { DaemonRecord, StopResult } from './daemon-registry';
+/** Sentinel option values (not real roots, so they can't collide with a project path). */
+export declare const STOP_ALL = "__stop_all__";
+export declare const CANCEL = "__cancel__";
+export interface PickItem {
+    value: string;
+    label: string;
+    hint?: string;
+}
+/** Compact uptime: `45s`, `12m`, `3h 5m`. */
+export declare function formatUptime(ms: number): string;
+/**
+ * Build the ordered, UI-ready option list: the current project's daemon first
+ * (so it's the auto-selected default), the rest newest-first, then "Stop all"
+ * (only when there's more than one) and "Cancel".
+ */
+export declare function buildPickItems(daemons: DaemonRecord[], cwdRoot: string | null, now: number): PickItem[];
+export interface PickerDeps {
+    list: () => DaemonRecord[];
+    stop: (root: string) => Promise<StopResult>;
+    stopAll: () => Promise<StopResult[]>;
+    /** Realpath'd root of the current project's daemon, or null. */
+    cwdRoot: string | null;
+    now: () => number;
+    /** Render the picker; returns the chosen value or a cancel sentinel. */
+    select: (opts: {
+        message: string;
+        options: PickItem[];
+        initialValue: string;
+    }) => Promise<unknown>;
+    isCancel: (v: unknown) => boolean;
+    /** Per-action note (e.g. "Stopped daemon …"). */
+    note: (msg: string) => void;
+    /** Final line + teardown (clack outro). */
+    done: (msg: string) => void;
+}
+/**
+ * Pick a daemon → stop it → re-prompt with what's left, until the user cancels
+ * (Esc / Ctrl-C / "Cancel"), picks "Stop all", or nothing remains.
+ */
+export declare function runDaemonPicker(deps: PickerDeps): Promise<void>;
+//# sourceMappingURL=daemon-manager.d.ts.map

package/dist/mcp/daemon-registry.d.ts

@@ -0,0 +1,47 @@
+export interface DaemonRecord {
+    /** Realpath'd project root the daemon serves. */
+    root: string;
+    pid: number;
+    version: string;
+    socketPath: string;
+    /** Epoch ms when the daemon bound its socket. */
+    startedAt: number;
+}
+/**
+ * `~/.codegraph/daemons` — GLOBAL, keyed off the home install dir. (The
+ * `CODEGRAPH_DIR` env var only renames the per-project index dir, not this.)
+ */
+export declare function getRegistryDir(): string;
+/**
+ * Is `pid` a live process? `kill(pid, 0)` sends no signal — it just probes:
+ * ESRCH ⇒ dead, EPERM ⇒ alive but not ours (still alive). Same liveness check
+ * the PPID watchdog (#277) and daemon lock arbitration use.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/** Best-effort: record this daemon so `list`/`stop --all` can find it. */
+export declare function registerDaemon(rec: DaemonRecord): void;
+/** Best-effort: drop this daemon's record on graceful shutdown. */
+export declare function deregisterDaemon(root: string): void;
+/**
+ * All registered daemons whose process is still alive, newest first. Dead/garbage
+ * records are deleted as a side effect (self-healing) unless `prune` is false.
+ */
+export declare function listDaemons(opts?: {
+    prune?: boolean;
+}): DaemonRecord[];
+export interface StopResult {
+    root: string;
+    pid: number | null;
+    /** 'term' graceful, 'kill' force, 'not-running' stale lock, 'no-daemon' none found. */
+    outcome: 'term' | 'kill' | 'not-running' | 'no-daemon';
+}
+/**
+ * Stop the daemon serving `root`: SIGTERM, wait, then SIGKILL if it won't go,
+ * then sweep its artifacts. `root` must be realpath'd (match how the daemon
+ * keys its socket/lockfile). Resolves the pid from the authoritative lockfile,
+ * falling back to the registry.
+ */
+export declare function stopDaemonAt(root: string): Promise<StopResult>;
+/** Stop every registered, live daemon. */
+export declare function stopAllDaemons(): Promise<StopResult[]>;
+//# sourceMappingURL=daemon-registry.d.ts.map

package/dist/mcp/index.d.ts

@@ -50,6 +50,7 @@ export declare class MCPServer {
     private engine;
     private daemon;
     private ppidWatchdog;
+    private livenessWatchdog;
     private originalPpid;
     private hostPpid;
     private stopped;

package/dist/mcp/liveness-watchdog.d.ts

@@ -0,0 +1,18 @@
+/** Default: 60s — ~300× shorter than the 5h #850 wedge, far longer than any real main-thread block. */
+export declare const DEFAULT_WATCHDOG_TIMEOUT_MS = 60000;
+/** Parse the timeout env, falling back to the default for missing/invalid values. */
+export declare function parseWatchdogTimeoutMs(raw: string | undefined, fallback?: number): number;
+/** Derive a heartbeat cadence that emits several beats inside the timeout window. */
+export declare function deriveCheckIntervalMs(timeoutMs: number): number;
+export interface WatchdogHandle {
+    /** Stop heartbeating and shut the watchdog child down. Idempotent. */
+    stop(): void;
+}
+/**
+ * Install the main-thread liveness watchdog for a long-lived process. Returns a
+ * handle to stop it, or `null` when disabled or when the child can't be spawned
+ * (degraded, never throws — a missing watchdog must never keep a process from
+ * starting).
+ */
+export declare function installMainThreadWatchdog(): WatchdogHandle | null;
+//# sourceMappingURL=liveness-watchdog.d.ts.map

package/package.json

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