notex-companion 0.1.0

package/dist/mcp.d.ts

@@ -0,0 +1 @@
+export declare function startMcpStub(): void;

package/dist/net.d.ts

@@ -0,0 +1,14 @@
+export type FetchHandler = (req: Request) => Promise<Response>;
+export type MinimalServer = {
+    readonly hostname: string;
+    readonly port: number;
+    stop(closeActiveConnections?: boolean): void;
+};
+export type StartServerOptions = {
+    hostname: string;
+    port: number;
+    fetch: FetchHandler;
+};
+export type Runtime = "bun" | "node";
+export declare function detectRuntime(): Runtime;
+export declare function startServer(opts: StartServerOptions, runtime?: Runtime): MinimalServer;

package/dist/ops.d.ts

@@ -0,0 +1,75 @@
+import type { GraphIndex } from "./graph.js";
+import { type GraphEdge, type GraphNode, type OpResponse } from "./types.js";
+/** Also the version /v1/ping reports (companion-api.md §4.1) — the two must never drift apart. */
+export declare const API_VERSION = "0.1.0";
+export type StatusResult = {
+    apiVersion: string;
+    capabilities: string[];
+    limits: {
+        maxNodes: number;
+        maxDepth: number;
+    };
+};
+export declare function status(index: GraphIndex): OpResponse<StatusResult>;
+export type SearchRequest = {
+    q: string;
+    limit?: number;
+};
+export type SearchResult = {
+    results: Array<GraphNode & {
+        score: number;
+    }>;
+};
+export declare function search(index: GraphIndex, req: SearchRequest): OpResponse<SearchResult>;
+export type QueryRequest = {
+    question: string;
+    terms?: string[];
+    depth?: number;
+    maxNodes?: number;
+    seeds?: number;
+    include?: Array<"subgraph" | "context" | "footer">;
+};
+export type QueryResult = {
+    subgraph: {
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+        seeds: string[];
+    };
+    context?: {
+        markdown: string;
+        sources: Array<{
+            file: string;
+            location: string;
+        }>;
+    };
+    /** See companion-api.md §4.8 / notex-mcp-server.md §5 — same buildFooter as the write paths. */
+    footer?: string;
+    /** Set when no seed cleared the seed-score floor — an exact label or label-token match. */
+    lowConfidence?: {
+        topScore: number;
+    };
+};
+export declare function query(index: GraphIndex, req: QueryRequest): OpResponse<QueryResult>;
+export type PathRequest = {
+    from: string;
+    to: string;
+    maxDepth?: number;
+};
+export type PathResult = {
+    found: boolean;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+};
+/** Fully deterministic, undirected, no scoring (companion-api.md §4.5) — plain BFS. */
+export declare function path(index: GraphIndex, req: PathRequest): OpResponse<PathResult>;
+export type NodeRequest = {
+    id: string;
+};
+export type NodeResult = {
+    node: GraphNode;
+    neighbours: Array<{
+        node: GraphNode;
+        edge: GraphEdge;
+    }>;
+};
+export declare function node(index: GraphIndex, req: NodeRequest): OpResponse<NodeResult>;

package/dist/pairing.d.ts

@@ -0,0 +1,6 @@
+/** Loads the persisted token, or generates and persists a new one. `rotate: true` always regenerates. */
+export declare function loadOrCreateToken(checkoutPath: string, opts?: {
+    rotate?: boolean;
+}): string;
+/** The single pasteable line printed at startup (companion-api.md §3.2). */
+export declare function pairingLine(baseUrl: string, token: string): string;

package/dist/scoring.d.ts

@@ -0,0 +1,17 @@
+/** camelCase / snake_case / path segments → discrete lowercase tokens. */
+export declare function shatter(text: string): string[];
+export declare function terms(question: string): string[];
+export type ScoreIndexEntry = {
+    id: string;
+    labelTokens: Set<string>;
+    pathTokens: Set<string>;
+    labelLower: string;
+};
+export type ScoredNode = {
+    id: string;
+    score: number;
+    /** Cleared the seed-score floor: at least one term matched a whole label or a whole label token. */
+    exact: boolean;
+};
+/** label tokens weigh full; path tokens weigh less — a path match is weaker evidence. */
+export declare function scoreNodes(index: ScoreIndexEntry[], queryTerms: string[]): ScoredNode[];

package/dist/serve.d.ts

@@ -0,0 +1,26 @@
+import { type GraphState } from "./http.js";
+import { type MinimalServer } from "./net.js";
+export type ServeOptions = {
+    /** Absolute path of the checkout to serve — where graphify-out/graph.json and .notex/ live. */
+    checkoutPath: string;
+    /**
+     * Fixed at 7717 by default (companion-api.md §3.1). Pass 0 for an OS-assigned port — but
+     * only under Bun (`bun test`, or any consumer running on the Bun runtime): the plain-Node
+     * fallback in net.ts binds synchronously and can't read back an OS-assigned port before
+     * returning, so it throws for `port: 0` rather than silently ignoring it.
+     */
+    port?: number;
+    /** Additional allowed origins beyond the dev default (companion-api.md §5). */
+    origins?: string[];
+    rotateToken?: boolean;
+    nodeEnv?: string;
+    /** Fires once the graph finishes loading (or fails to) — the CLI uses this for startup output. */
+    onGraphState?: (state: GraphState) => void;
+};
+export type ServeHandle = {
+    server: MinimalServer;
+    token: string;
+    baseUrl: string;
+    pairingLine: string;
+};
+export declare function serve(opts: ServeOptions): ServeHandle;

package/dist/traversal.d.ts

@@ -0,0 +1,16 @@
+import type { Truncated } from "./types.js";
+export type TraversalEdge = {
+    source: string;
+    target: string;
+    weight: number;
+};
+export type AdjacencyMap<E> = Map<string, Array<{
+    other: string;
+    edge: E;
+}>>;
+export type TraversalResult<E> = {
+    nodeIds: string[];
+    edges: E[];
+    truncated: Truncated | null;
+};
+export declare function traverse<E extends TraversalEdge>(adjacency: AdjacencyMap<E>, allEdges: E[], seedIds: string[], depth: number, maxNodes: number): TraversalResult<E>;

package/dist/types.d.ts

@@ -0,0 +1,68 @@
+/** Returned by `status` and echoed on every op response. */
+export type GraphStamp = {
+    builtAt: string;
+    graphHash: string;
+    nodeCount: number;
+    edgeCount: number;
+    communityCount: number;
+    checkoutPath: string;
+    headSha: string | null;
+    graphRoot: string;
+    rootPrefix: string;
+};
+export type GraphNode = {
+    id: string;
+    label: string;
+    sourceFile: string;
+    sourceLocation: string;
+    fileType: string;
+    community: {
+        id: number;
+        name: string;
+    } | null;
+};
+export type GraphEdge = {
+    source: string;
+    target: string;
+    relation: string;
+    weight: number;
+    confidence: string;
+    sourceFile: string;
+    sourceLocation: string;
+};
+export type Truncated = {
+    reason: "maxNodes" | "depth";
+    omittedCount: number;
+};
+export type Degraded = {
+    expansion: "none";
+};
+export type OpResponse<T> = {
+    graph: GraphStamp;
+    degraded?: Degraded;
+    truncated?: Truncated;
+} & T;
+export type ErrorResponse = {
+    error: {
+        code: string;
+        message: string;
+        detail?: unknown;
+    };
+};
+export declare const ERROR_CODES: {
+    readonly unauthorized: "unauthorized";
+    readonly notFound: "not_found";
+    readonly graphUnreadable: "graph_unreadable";
+    readonly invalidRequest: "invalid_request";
+    readonly graphLoading: "graph_loading";
+};
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+/**
+ * Thrown by ops for the error cases in companion-api.md §2.4. A transport binding
+ * (REST, MCP) maps `code` to its own status/error shape; this module stays transport-free.
+ */
+export declare class OpError extends Error {
+    readonly code: ErrorCode;
+    readonly detail?: unknown;
+    constructor(code: ErrorCode, message: string, detail?: unknown);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "notex-companion",
+  "version": "0.1.0",
+  "description": "Local retrieval companion for Notex — reads a checkout's graphify-out/graph.json and serves deterministic search/query/path/node lookups over loopback HTTP and (stub) MCP stdio. No LLM, no graph building, no network beyond 127.0.0.1.",
+  "keywords": ["notex", "graphify", "mcp", "code-graph"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bhirmbani/notex.git",
+    "directory": "packages/companion"
+  },
+  "homepage": "https://github.com/bhirmbani/notex/tree/main/packages/companion#readme",
+  "type": "module",
+  "bin": {
+    "notex-companion": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "README.md"],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "build": "rm -rf dist && bun run build:cli && bun run build:lib && bun run build:types && chmod +x dist/cli.js",
+    "build:cli": "bun build ./src/bin.ts --target=node --format=esm --outfile=dist/cli.js --banner=\"#!/usr/bin/env node\"",
+    "build:lib": "bun build ./src/index.ts --target=node --format=esm --outfile=dist/index.js",
+    "build:types": "tsc -p tsconfig.build.json && node scripts/fix-dts-extensions.mjs",
+    "prepublishOnly": "bun run typecheck && bun test && bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^5.9.3"
+  }
+}