@lzehrung/codegraph 2.1.2 → 2.2.1

package/docs/mcp.md

@@ -12,7 +12,21 @@ Stdio is the default transport and is the best fit when the MCP client launches
 codegraph mcp serve --root . --stdio
 ```
 
-Streamable HTTP is useful when multiple IDE, terminal, or agent instances should share one repo-local server:
+For one reusable repo-local HTTP server, use the lifecycle wrapper:
+
+```bash
+codegraph server start --root /path/to/repo --warmup
+codegraph server status --root /path/to/repo --json
+codegraph server stop --root /path/to/repo
+```
+
+`server start` serializes lifecycle changes, launches `mcp serve`, waits for a same-root process and startup identity proved by a challenged `/health` response, then records the process at `.codegraph/server.json`. It defaults to `127.0.0.1:7331`; use `--host` explicitly for a non-loopback bind, `--replace` only to restart a live server for the same root, and `--startup-timeout-ms <1-86400000>` when a warmup needs more than the 15-second default.
+
+`server start --json` emits `status: "started"`, the registry fields, and `update`. `server status` retries challenged HTTP health checks and reports a verification remedy instead of removing metadata for an unreachable or identity-mismatched server. `server stop` removes only confirmed stale metadata or signals a Codegraph process whose proven health identity matches the registry.
+
+The v2 registry contains process metadata and a non-secret credential ID; the secret stays in the per-user Codegraph state directory, outside the project and separate from package files and compiler cache data. A live v1 registry is never signaled, so stop its old process manually before a new start.
+
+Use `mcp serve` directly when another process manager owns the server:
 
 ```bash
 codegraph mcp serve --root /path/to/repo --port 7331 --warmup
@@ -47,7 +61,7 @@ HTTP enforces Host and Origin policies. A missing `Origin` is accepted for non-b
 
 ## Runtime identity and updates
 
-The MCP initialize response advertises the codegraph package version captured when the server starts. The server checks its captured package metadata path at most once every 30 seconds during tool calls; a changed or temporarily unavailable installation produces a deduplicated stderr warning but does not fail the request or terminate the server.
+The MCP initialize response advertises the codegraph package version captured when the server starts. MCP tool calls share one cached checker that reads captured package metadata at most once every 30 seconds and emits a deduplicated stderr warning when the installation changes or is unavailable. The health endpoint uses its own cached silent checker, so a health call and a tool call can each read package metadata in the same interval without failing the request or terminating the server.
 
 On Windows, installed-package servers map the verified native addon from `%LOCALAPPDATA%\codegraph\native-cache\v1`, not from npm's package directory. An old server may therefore remain healthy after npm installs a new release, but it must be restarted to use the new JavaScript runtime and cache identity.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lzehrung/codegraph",
-  "version": "2.1.2",
+  "version": "2.2.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -82,7 +82,7 @@
   "license": "MIT",
   "description": "Multi-language repository map for agents and humans: MCP tools, dependency graphs, symbol indexes, impact review, and bounded source evidence.",
   "dependencies": {
-    "@lzehrung/codegraph-core": "2.1.2",
+    "@lzehrung/codegraph-core": "2.2.1",
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "fast-glob": "^3.3.3",
@@ -99,6 +99,6 @@
     "@emnapi/runtime": "1.11.3"
   },
   "optionalDependencies": {
-    "@lzehrung/codegraph-native": "^1.9.2"
+    "@lzehrung/codegraph-native": "^1.11.1"
   }
 }

package/dist/languages/definitions/loadLanguage.d.ts

@@ -1,2 +0,0 @@
-export { loadTreeSitterLanguage, loadTypeScriptGrammars } from "../../parserBackend.js";
-//# sourceMappingURL=loadLanguage.d.ts.map

package/dist/languages/definitions/loadLanguage.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"loadLanguage.d.ts","sourceRoot":"","sources":["../../../src/languages/definitions/loadLanguage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/languages/definitions/loadLanguage.js

@@ -1,2 +0,0 @@
-export { loadTreeSitterLanguage, loadTypeScriptGrammars } from "../../parserBackend.js";
-//# sourceMappingURL=loadLanguage.js.map

package/dist/languages/definitions/loadLanguage.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"loadLanguage.js","sourceRoot":"","sources":["../../../src/languages/definitions/loadLanguage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/parserBackend.d.ts

@@ -1,57 +0,0 @@
-export interface SyntaxPoint {
-    row: number;
-    column: number;
-}
-export interface ParserSyntaxNode {
-    readonly id?: number;
-    type: string;
-    text: string;
-    startIndex: number;
-    endIndex: number;
-    startPosition: SyntaxPoint;
-    endPosition: SyntaxPoint;
-    parent: ParserSyntaxNode | null;
-    namedChildren: ParserSyntaxNode[];
-    previousSibling?: ParserSyntaxNode | null;
-    previousNamedSibling?: ParserSyntaxNode | null;
-    child(index: number): ParserSyntaxNode | null;
-    childForFieldName(fieldName: string): ParserSyntaxNode | null;
-}
-export interface ParserSyntaxTree {
-    rootNode: ParserSyntaxNode & {
-        descendantForIndex(startIndex: number, endIndex: number): ParserSyntaxNode;
-        descendantForPosition(start: SyntaxPoint, end: SyntaxPoint): ParserSyntaxNode;
-    };
-    walk(): unknown;
-}
-export interface ParserLanguage {
-    readonly name?: string;
-}
-export interface QueryPoint {
-    row: number;
-    column: number;
-    index: number;
-}
-export interface QueryCapture {
-    name: string;
-    text: string;
-    nodeType: string;
-    start: QueryPoint;
-    end: QueryPoint;
-}
-export interface QueryMatch {
-    patternIndex: number;
-    captures: QueryCapture[];
-}
-export declare function __resetParserBackendModuleForTests(): void;
-export declare function isNonNativeParserAvailable(): boolean;
-export declare function isNonNativeParserUnavailableError(error: unknown): boolean;
-export declare function loadTreeSitterLanguage(packageName: string): ParserLanguage;
-export declare function loadTypeScriptGrammars(): {
-    typescript: ParserLanguage;
-    tsx: ParserLanguage;
-};
-export declare function parseWithLanguage(_source: string, _language: ParserLanguage): ParserSyntaxTree;
-export declare function isParserSyntaxTree(tree: unknown): tree is ParserSyntaxTree;
-export declare function executeQueryAsNativeMatches(_source: string, _language: ParserLanguage, _queryText: string, _tree?: ParserSyntaxTree): QueryMatch[];
-//# sourceMappingURL=parserBackend.d.ts.map

package/dist/parserBackend.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"parserBackend.d.ts","sourceRoot":"","sources":["../src/parserBackend.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,WAAW,CAAC;IAC3B,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAChC,aAAa,EAAE,gBAAgB,EAAE,CAAC;IAClC,eAAe,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC1C,oBAAoB,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC/C,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAC9C,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;CAC/D;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,gBAAgB,GAAG;QAC3B,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAAC;QAC3E,qBAAqB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,GAAG,gBAAgB,CAAC;KAC/E,CAAC;IACF,IAAI,IAAI,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,UAAU,CAAC;IAClB,GAAG,EAAE,UAAU,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AASD,wBAAgB,kCAAkC,IAAI,IAAI,CAEzD;AAED,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAED,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEzE;AAED,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CAE1E;AAED,wBAAgB,sBAAsB,IAAI;IACxC,UAAU,EAAE,cAAc,CAAC;IAC3B,GAAG,EAAE,cAAc,CAAC;CACrB,CAKA;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,GAAG,gBAAgB,CAE9F;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,gBAAgB,CAE1E;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,cAAc,EACzB,UAAU,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,gBAAgB,GACvB,UAAU,EAAE,CAEd"}

package/dist/parserBackend.js

@@ -1,33 +0,0 @@
-const NON_NATIVE_PARSER_UNAVAILABLE_PREFIX = "Non-native Tree-sitter parser is unavailable";
-const NON_NATIVE_PARSER_UNAVAILABLE_SUFFIX = "native parser is the only grammar backend";
-function createUnavailableError(feature) {
-    return new Error(`${NON_NATIVE_PARSER_UNAVAILABLE_PREFIX} for ${feature}; ${NON_NATIVE_PARSER_UNAVAILABLE_SUFFIX}`);
-}
-export function __resetParserBackendModuleForTests() {
-    // Kept for tests that reset parser backends between cases.
-}
-export function isNonNativeParserAvailable() {
-    return false;
-}
-export function isNonNativeParserUnavailableError(error) {
-    return error instanceof Error && error.message.includes(NON_NATIVE_PARSER_UNAVAILABLE_PREFIX);
-}
-export function loadTreeSitterLanguage(packageName) {
-    return { name: packageName };
-}
-export function loadTypeScriptGrammars() {
-    return {
-        typescript: { name: "tree-sitter-typescript/typescript" },
-        tsx: { name: "tree-sitter-typescript/tsx" },
-    };
-}
-export function parseWithLanguage(_source, _language) {
-    throw createUnavailableError("syntax-tree parsing");
-}
-export function isParserSyntaxTree(tree) {
-    return typeof tree === "object" && tree !== null && "rootNode" in tree && "walk" in tree;
-}
-export function executeQueryAsNativeMatches(_source, _language, _queryText, _tree) {
-    throw createUnavailableError("query execution");
-}
-//# sourceMappingURL=parserBackend.js.map

package/dist/parserBackend.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"parserBackend.js","sourceRoot":"","sources":["../src/parserBackend.ts"],"names":[],"mappings":"AAoDA,MAAM,oCAAoC,GAAG,8CAA8C,CAAC;AAC5F,MAAM,oCAAoC,GAAG,2CAA2C,CAAC;AAEzF,SAAS,sBAAsB,CAAC,OAAe;IAC7C,OAAO,IAAI,KAAK,CAAC,GAAG,oCAAoC,QAAQ,OAAO,KAAK,oCAAoC,EAAE,CAAC,CAAC;AACtH,CAAC;AAED,MAAM,UAAU,kCAAkC;IAChD,2DAA2D;AAC7D,CAAC;AAED,MAAM,UAAU,0BAA0B;IACxC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,iCAAiC,CAAC,KAAc;IAC9D,OAAO,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,oCAAoC,CAAC,CAAC;AAChG,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,WAAmB;IACxD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,sBAAsB;IAIpC,OAAO;QACL,UAAU,EAAE,EAAE,IAAI,EAAE,mCAAmC,EAAE;QACzD,GAAG,EAAE,EAAE,IAAI,EAAE,4BAA4B,EAAE;KAC5C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,SAAyB;IAC1E,MAAM,sBAAsB,CAAC,qBAAqB,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAa;IAC9C,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,UAAU,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,CAAC;AAC3F,CAAC;AAED,MAAM,UAAU,2BAA2B,CACzC,OAAe,EACf,SAAyB,EACzB,UAAkB,EAClB,KAAwB;IAExB,MAAM,sBAAsB,CAAC,iBAAiB,CAAC,CAAC;AAClD,CAAC"}