@reposkein/mcp 0.3.0 → 0.5.0

package/dist/serve/tokens.js

@@ -0,0 +1,108 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { readConfigString } from "../store/teamConfig.js";
+/** Minimum secret length we will accept. Short enough not to be annoying,
+ *  long enough that a token typed by hand isn't guessable in an afternoon. */
+const MIN_TOKEN_LENGTH = 16;
+/** Parses a token list: `name:token[:write]` entries separated by commas,
+ *  whitespace, or newlines.
+ *
+ *  Chosen over JSON because it has to survive being pasted into a shell
+ *  export, a systemd `Environment=` line, and a TOML string without escaping.
+ *  Anything unparseable is DROPPED with a reason rather than silently
+ *  becoming a valid credential — a malformed entry must never widen access.
+ *  Capability is opt-in: only the literal third field `write` grants it. */
+export function parseServeTokens(spec) {
+    const tokens = [];
+    const errors = [];
+    const seenNames = new Set();
+    const seenSecrets = new Set();
+    for (const rawEntry of spec.split(/[,\s]+/)) {
+        const entry = rawEntry.trim();
+        if (entry === "")
+            continue;
+        const parts = entry.split(":");
+        if (parts.length < 2 || parts.length > 3) {
+            errors.push(`ignored a token entry: expected "name:token" or "name:token:write"`);
+            continue;
+        }
+        const [name, token, cap] = parts;
+        if (!/^[A-Za-z0-9._-]{1,40}$/.test(name)) {
+            errors.push(`ignored a token entry: name must be 1-40 chars of [A-Za-z0-9._-] (got ${JSON.stringify(name)})`);
+            continue;
+        }
+        if (token.length < MIN_TOKEN_LENGTH) {
+            errors.push(`ignored token "${name}": secret shorter than ${MIN_TOKEN_LENGTH} characters`);
+            continue;
+        }
+        if (cap !== undefined && cap !== "write") {
+            errors.push(`ignored token "${name}": third field must be "write" (got ${JSON.stringify(cap)})`);
+            continue;
+        }
+        if (seenNames.has(name)) {
+            errors.push(`ignored a duplicate token name: "${name}"`);
+            continue;
+        }
+        if (seenSecrets.has(token)) {
+            errors.push(`ignored token "${name}": its secret is already used by another name`);
+            continue;
+        }
+        seenNames.add(name);
+        seenSecrets.add(token);
+        tokens.push({ name, token, write: cap === "write" });
+    }
+    return { tokens, errors };
+}
+/** Resolves the token list for `serve`: `REPOSKEIN_SERVE_TOKENS` wins over
+ *  `[serve] tokens` in `.reposkein/config.toml`.
+ *
+ *  Env-over-config because the config file is COMMITTED — an operator who
+ *  puts real secrets there has leaked them to everyone with repo access, so
+ *  the documented path is the env var and config is the convenience for a
+ *  private deployment. Only one source is consulted (no union): merging them
+ *  would make "why does this old token still work?" unanswerable. */
+export function loadServeTokens(repoPath, env = process.env) {
+    const fromEnv = env.REPOSKEIN_SERVE_TOKENS?.trim();
+    if (fromEnv)
+        return { ...parseServeTokens(fromEnv), source: "env" };
+    const fromConfig = readConfigString(repoPath, "serve", "tokens");
+    if (fromConfig && fromConfig.trim()) {
+        return { ...parseServeTokens(fromConfig), source: "config" };
+    }
+    return { tokens: [], errors: [], source: "none" };
+}
+/** Extracts the credential from an `Authorization: Bearer <token>` header.
+ *  Returns null for a missing, non-Bearer, or empty-value header. */
+export function bearerFromAuthHeader(header) {
+    const value = Array.isArray(header) ? header[0] : header;
+    if (!value)
+        return null;
+    const m = /^Bearer[ \t]+(.+)$/i.exec(value.trim());
+    if (!m)
+        return null;
+    const token = m[1].trim();
+    return token === "" ? null : token;
+}
+/** Length-independent constant-time comparison: both sides are hashed to a
+ *  fixed 32 bytes first, so `timingSafeEqual` never sees mismatched lengths
+ *  (it throws on those, and the throw itself would leak the length). */
+function secretEquals(a, b) {
+    const ha = createHash("sha256").update(a, "utf8").digest();
+    const hb = createHash("sha256").update(b, "utf8").digest();
+    return timingSafeEqual(ha, hb);
+}
+/** Finds the token a presented credential matches, or null.
+ *
+ *  Scans the WHOLE list with no early exit so the response time doesn't
+ *  reveal which position matched (or how many tokens the operator
+ *  configured). */
+export function matchServeToken(tokens, presented) {
+    if (presented === null)
+        return null;
+    let hit = null;
+    for (const t of tokens) {
+        if (secretEquals(t.token, presented))
+            hit = t;
+    }
+    return hit;
+}
+//# sourceMappingURL=tokens.js.map

package/dist/serve/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/serve/tokens.ts"],"names":[],"mappings":"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"}

package/dist/serve/watch.d.ts

@@ -0,0 +1,73 @@
+/** What one watch tick did. `unchanged` is the overwhelmingly common case and
+ *  costs exactly one `git rev-parse` — the whole point of comparing against
+ *  the indexed-at marker rather than re-indexing on a timer. `locked` means
+ *  another indexer run (a write-capable tool call, or the previous tick) owns
+ *  the index lock; the tick is skipped, not queued. */
+export type WatchOutcome = "unchanged" | "reindexed" | "failed" | "no-head" | "locked";
+export interface ReindexResult {
+    ok: boolean;
+    nodes?: number;
+    edges?: number;
+    error?: string;
+}
+export interface WatchDeps {
+    /** Current git HEAD of the served checkout, or null (not a repo / no HEAD). */
+    headSha: () => string | null;
+    /** The SHA the graph was last built from (`.reposkein/local/indexed-at`). */
+    indexedSha: () => string | null;
+    /** Rebuild the graph. MUST also refresh the indexed-at marker on success. */
+    reindex: () => Promise<ReindexResult>;
+    /** Where the one-line-per-reindex summary goes. MUST NOT be stdout in stdio
+     *  mode; `serve` has no stdio transport, but stderr stays the convention. */
+    log: (message: string) => void;
+    /** Whether an indexer run is already in progress or queued. Injectable so
+     *  the skip path is testable without spawning anything. */
+    indexBusy: () => boolean;
+}
+/** Reads HEAD of `repoPath`, or null. Never throws. */
+export declare function gitHeadSha(repoPath: string): string | null;
+/** One watch tick.
+ *
+ *  Idempotence is structural, not statistical: the decision to do work is
+ *  `HEAD !== indexed-at`, and the marker is written from HEAD by the index
+ *  step itself. So a tick against an unchanged checkout does nothing at all
+ *  (no indexer spawn, no log line), and a tick after `git pull` does exactly
+ *  one re-index — including across a server restart, because the marker is on
+ *  disk. If HEAD moves again DURING an index, the marker records the SHA that
+ *  was current when the index finished and the next tick converges.
+ *
+ *  Reusing REP-16's marker (rather than an in-memory "last seen" SHA) is what
+ *  keeps `doctor --ci`'s `graph_stale` check agreeing with the watcher: both
+ *  read the same file. */
+export declare function watchTick(deps: WatchDeps): Promise<WatchOutcome>;
+/** The default `reindex`: the same indexer invocation `reposkein-mcp index`
+ *  uses, followed by the indexed-at marker write. */
+export declare function makeDefaultReindex(repoPath: string, repoId: string): () => Promise<ReindexResult>;
+export interface HeadWatcherOptions {
+    intervalMs: number;
+    log?: (message: string) => void;
+    /** Called after a successful re-index — `serve` uses it to rebuild the
+     *  `/api/*` handler, whose node/edge counts and git metadata are computed
+     *  once per handler. */
+    onReindexed?: () => void;
+    /** Test seam: replaces the git + indexer plumbing wholesale. */
+    deps?: Partial<WatchDeps>;
+}
+export interface HeadWatcher {
+    /** Runs one tick now (awaitable — used by the startup catch-up and tests). */
+    tick: () => Promise<WatchOutcome>;
+    stop: () => void;
+}
+/** Polls `git rev-parse HEAD` on an interval and re-indexes when it moves.
+ *
+ *  A poll, not a filesystem watcher: the indexer's determinism guarantee is
+ *  defined against committed state, and an fs watcher would fire on every
+ *  editor save — re-indexing mid-edit, repeatedly, for a graph nobody asked
+ *  for yet. A poll also covers the case that actually matters for a shared
+ *  server (someone ran `git fetch && git reset --hard` in the checkout, or a
+ *  deploy hook did) without requiring a hook to be installed at all.
+ *
+ *  `intervalMs <= 0` disables polling entirely; `tick()` still works, so an
+ *  operator can drive re-indexing from their own post-receive hook by
+ *  restarting or by running `reposkein-mcp index`. */
+export declare function startHeadWatcher(repoPath: string, repoId: string, opts: HeadWatcherOptions): HeadWatcher;

package/dist/serve/watch.js

@@ -0,0 +1,135 @@
+import { execFileSync } from "node:child_process";
+import { readIndexedAtSha, writeIndexedAtMarker } from "../store/indexedAt.js";
+import { ensureIndexerBinary } from "../indexer/fetchBinary.js";
+import { spawnIndexer, parseJsonStats } from "../indexer/runIndexer.js";
+import { isIndexLockHeld } from "../indexer/indexLock.js";
+/** Reads HEAD of `repoPath`, or null. Never throws. */
+export function gitHeadSha(repoPath) {
+    try {
+        const sha = execFileSync("git", ["-C", repoPath, "rev-parse", "HEAD"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return sha || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** One watch tick.
+ *
+ *  Idempotence is structural, not statistical: the decision to do work is
+ *  `HEAD !== indexed-at`, and the marker is written from HEAD by the index
+ *  step itself. So a tick against an unchanged checkout does nothing at all
+ *  (no indexer spawn, no log line), and a tick after `git pull` does exactly
+ *  one re-index — including across a server restart, because the marker is on
+ *  disk. If HEAD moves again DURING an index, the marker records the SHA that
+ *  was current when the index finished and the next tick converges.
+ *
+ *  Reusing REP-16's marker (rather than an in-memory "last seen" SHA) is what
+ *  keeps `doctor --ci`'s `graph_stale` check agreeing with the watcher: both
+ *  read the same file. */
+export async function watchTick(deps) {
+    const head = deps.headSha();
+    if (!head)
+        return "no-head";
+    if (head === deps.indexedSha())
+        return "unchanged";
+    // Someone else is indexing (a write tool call, or a still-running earlier
+    // tick). SKIP rather than queue: whatever they are building is being built
+    // from the same working tree, so by the time the lock frees, this tick's
+    // work is either done or the next tick will see it needs doing. Queueing
+    // here would fire a redundant full index behind every write tool call.
+    if (deps.indexBusy())
+        return "locked";
+    const started = Date.now();
+    const r = await deps.reindex();
+    const secs = ((Date.now() - started) / 1000).toFixed(1);
+    const short = head.slice(0, 12);
+    if (!r.ok) {
+        deps.log(`reposkein serve: reindex for HEAD ${short} FAILED after ${secs}s: ${r.error ?? "unknown error"} ` +
+            "(serving the previous graph; will retry on the next tick)");
+        return "failed";
+    }
+    deps.log(`reposkein serve: reindexed at HEAD ${short} in ${secs}s ` +
+        `(${r.nodes ?? "?"} nodes, ${r.edges ?? "?"} edges)`);
+    return "reindexed";
+}
+/** The default `reindex`: the same indexer invocation `reposkein-mcp index`
+ *  uses, followed by the indexed-at marker write. */
+export function makeDefaultReindex(repoPath, repoId) {
+    return async () => {
+        try {
+            const bin = await ensureIndexerBinary();
+            const r = await spawnIndexer(bin, ["index", "--json", "--repo-id", repoId, repoPath]);
+            if (r.code !== 0) {
+                return { ok: false, error: r.stderr.trim() || r.stdout.trim() || `exit ${r.code}` };
+            }
+            const stats = parseJsonStats(r.stdout);
+            writeIndexedAtMarker(repoPath);
+            return stats ? { ok: true, nodes: stats.nodes, edges: stats.edges } : { ok: true };
+        }
+        catch (e) {
+            return { ok: false, error: e instanceof Error ? e.message : String(e) };
+        }
+    };
+}
+/** Polls `git rev-parse HEAD` on an interval and re-indexes when it moves.
+ *
+ *  A poll, not a filesystem watcher: the indexer's determinism guarantee is
+ *  defined against committed state, and an fs watcher would fire on every
+ *  editor save — re-indexing mid-edit, repeatedly, for a graph nobody asked
+ *  for yet. A poll also covers the case that actually matters for a shared
+ *  server (someone ran `git fetch && git reset --hard` in the checkout, or a
+ *  deploy hook did) without requiring a hook to be installed at all.
+ *
+ *  `intervalMs <= 0` disables polling entirely; `tick()` still works, so an
+ *  operator can drive re-indexing from their own post-receive hook by
+ *  restarting or by running `reposkein-mcp index`. */
+export function startHeadWatcher(repoPath, repoId, opts) {
+    const log = opts.log ?? ((m) => void process.stderr.write(`${m}\n`));
+    const deps = {
+        headSha: opts.deps?.headSha ?? (() => gitHeadSha(repoPath)),
+        indexedSha: opts.deps?.indexedSha ?? (() => readIndexedAtSha(repoPath)),
+        reindex: opts.deps?.reindex ?? makeDefaultReindex(repoPath, repoId),
+        log: opts.deps?.log ?? log,
+        indexBusy: opts.deps?.indexBusy ?? isIndexLockHeld,
+    };
+    // Ticks never overlap: a slow index on a big repo must not stack up behind
+    // a fast interval, and two concurrent indexer runs on one checkout would
+    // race on the same output files.
+    let busy = false;
+    let stopped = false;
+    const tick = async () => {
+        if (stopped)
+            return "unchanged";
+        // A previous tick is still running (slow index on a big repo, fast
+        // interval). Same reasoning as the index-lock skip in `watchTick`.
+        if (busy)
+            return "locked";
+        busy = true;
+        try {
+            const outcome = await watchTick(deps);
+            if (outcome === "reindexed")
+                opts.onReindexed?.();
+            return outcome;
+        }
+        finally {
+            busy = false;
+        }
+    };
+    const timer = opts.intervalMs > 0
+        ? setInterval(() => {
+            void tick();
+        }, opts.intervalMs)
+        : null;
+    return {
+        tick,
+        stop: () => {
+            stopped = true;
+            if (timer)
+                clearInterval(timer);
+        },
+    };
+}
+//# sourceMappingURL=watch.js.map

package/dist/serve/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../../src/serve/watch.ts"],"names":[],"mappings":"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"}

package/dist/server/createMcpServer.d.ts

@@ -0,0 +1,129 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { GraphStore } from "../store/GraphStore.js";
+import type { RepoResolution } from "../store/resolveRepoPath.js";
+import { ensureGraph } from "../indexer/ensureGraph.js";
+/** Selects the store backend.
+ *  REPOSKEIN_STORE = "jsonl" | "neo4j" | "auto" (default "auto").
+ *  - auto: JSONL if <repoPath>/.reposkein/nodes.jsonl exists, else Neo4j if
+ *    NEO4J_PASSWORD is set, else Unconfigured.
+ *  - jsonl: JSONL if available, else Unconfigured.
+ *  - neo4j: Neo4j if configured, else Unconfigured.
+ *
+ *  `agent` names the writer for sidecar selection (one summaries file per
+ *  agent, see store/sidecar.ts); undefined keeps the REPOSKEIN_AGENT default. */
+export declare function buildStore(repoPath: string | undefined, repoId: string | undefined, agent?: string): GraphStore;
+/** Structured, actionable message for repo-scoped tool calls when no repo
+ *  resolved (see `resolveRepoPath`). Names the discovered candidates when
+ *  resolution failed due to workspace-mode ambiguity, and points at
+ *  `list_repos` / `select_repo` so the agent can pick one instead of
+ *  abandoning the tools. */
+export declare function repoRequiredMessage(resolution: RepoResolution): string;
+/** A repo resolved but has no committed `meta.json` (never indexed). */
+export declare function repoUnindexedMessage(repoPath: string): string;
+/** Whether a graph is available to READ at `repoPath` without building one.
+ *
+ *  Mirrors `buildStore`'s backend choice exactly (same env, same order), so
+ *  "we can serve reads" and "we picked a real store" can never disagree:
+ *  explicit neo4j mode trusts the DB, otherwise the committed-derived JSONL
+ *  decides, and `auto` falls back to Neo4j when a password is configured. */
+export declare function graphAvailable(repoPath: string, env?: NodeJS.ProcessEnv): boolean;
+/** A read-only connection resolved a repo whose derived graph isn't built.
+ *
+ *  Building it means spawning the indexer and writing `.reposkein/*.jsonl` —
+ *  a write, and the LAST write a read-only token could still trigger, since
+ *  `ensureGraph` used to run unconditionally on first touch of any repo. So a
+ *  read-only caller gets this instead: an explanation and the exact command
+ *  for whoever does hold write access, with nothing changed on disk. */
+export declare function readOnlyUnindexedMessage(repoPath: string): string;
+/** Exported for schema tests. */
+export declare const getContextProfileInputSchema: {
+    node_id: z.ZodOptional<z.ZodString>;
+    file_path: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    hops: z.ZodOptional<z.ZodNumber>;
+    federated: z.ZodOptional<z.ZodBoolean>;
+};
+/** Exported for schema tests. */
+export declare const recordDecisionInputSchema: {
+    title: z.ZodString;
+    context: z.ZodString;
+    decision: z.ZodString;
+    consequences: z.ZodOptional<z.ZodString>;
+    alternatives: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        proposed: "proposed";
+        accepted: "accepted";
+    }>>;
+    anchor_node_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    anchor_paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    supersedes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+};
+export declare const setDecisionStatusInputSchema: {
+    decision_id: z.ZodString;
+    status: z.ZodEnum<{
+        accepted: "accepted";
+        rejected: "rejected";
+        deprecated: "deprecated";
+    }>;
+};
+export declare const reaffirmDecisionInputSchema: {
+    decision_id: z.ZodString;
+};
+export declare const listDecisionsInputSchema: {
+    status: z.ZodOptional<z.ZodEnum<{
+        proposed: "proposed";
+        accepted: "accepted";
+        rejected: "rejected";
+        deprecated: "deprecated";
+        superseded: "superseded";
+    }>>;
+    anchor: z.ZodOptional<z.ZodString>;
+    q: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+};
+export declare const getDecisionInputSchema: {
+    decision_id: z.ZodString;
+};
+/** The tools that MUTATE the repo (sidecar prose, decision records, the
+ *  derived graph). Gated behind the `write` capability in `serve --http`
+ *  (REP-17); always available over stdio, where the caller already owns the
+ *  checkout.
+ *
+ *  `select_repo` is deliberately NOT here: it mutates only this connection's
+ *  own `RepoSession`, which since REP-17 is per-connection state, so a
+ *  read-only caller pointing itself at a different discovered repo affects
+ *  nobody else. */
+export declare const WRITE_TOOLS: readonly ["write_semantic_summary", "record_decision", "set_decision_status", "reaffirm_decision", "reindex_file", "init_cpg_skeleton"];
+export interface ToolCapabilities {
+    /** False = read-only connection: every WRITE_TOOLS call is refused. */
+    write: boolean;
+}
+export interface CreateMcpServerOptions {
+    /** Working directory repo discovery starts from. */
+    cwd: string;
+    /** REPOSKEIN_REPO_PATH, or undefined. */
+    envRepoPath: string | undefined;
+    /** Session-log id. Defaults to `resolveSessionId(process.env)` (the stdio
+     *  behaviour: one id per server process). */
+    sessionId?: string;
+    /** Writer identity recorded as `summary_by`/`decided_by` and used to pick
+     *  the per-agent sidecar file. Undefined keeps the historical
+     *  `REPOSKEIN_AGENT ?? "agent"` fallback inside the tools. */
+    identity?: string;
+    /** Defaults to `{ write: true }` — the stdio behaviour. */
+    capabilities?: ToolCapabilities;
+    /** Test seam for the first-touch graph build. Defaults to the real
+     *  `ensureGraph`. Injected in tests so the read-only build gate can be
+     *  asserted (called / not called) without spawning an indexer. */
+    ensureGraph?: typeof ensureGraph;
+}
+/** Builds ONE MCP server with its own session state.
+ *
+ *  Everything a caller can move — the active repo (`select_repo`), the
+ *  per-repoPath store/context cache, the tool-call logger — lives in this
+ *  closure, so two connections into the same process cannot see each other's
+ *  selection. That is what makes `serve --http` (REP-17) safe; over stdio
+ *  there is exactly one of these per process, which is byte-for-byte the
+ *  behaviour that existed before the extraction. */
+export declare function createMcpServer(opts: CreateMcpServerOptions): McpServer;