@reposkein/mcp 0.2.7 → 0.4.0

package/dist/cli/doctorFreshness.js

@@ -0,0 +1,111 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readIndexedAtSha } from "../store/indexedAt.js";
+/** Marker `init --hooks` (the Rust indexer) writes into every hook it
+ *  installs — see indexer/crates/cli/src/main.rs `write_hook`. Doctor uses
+ *  the same marker to tell "RepoSkein installed this hook" from "the user
+ *  has their own pre-commit hook and never ran `reposkein-mcp init`". */
+const HOOK_MARKER = "# reposkein-managed";
+const warn = (id, label, ok, detail, fix) => ({
+    id,
+    label,
+    ok,
+    critical: false, // these checks degrade the workflow; they never block startup
+    detail,
+    fix: ok ? undefined : fix,
+});
+/** Non-critical by default: a repo can be perfectly usable without hooks
+ *  (an agent can always run `reposkein-mcp index` by hand). `doctor --ci`
+ *  promotes this id to a failing exit code — see CI_FAIL_IDS in doctor.ts. */
+export function hooksCheck(repoPath) {
+    const hookPath = join(repoPath, ".git", "hooks", "pre-commit");
+    if (!existsSync(hookPath)) {
+        return warn("hooks_installed", "git hooks installed", false, "no .git/hooks/pre-commit", "run `reposkein-mcp init` to install the pre-commit/post-merge hooks");
+    }
+    let content = "";
+    try {
+        content = readFileSync(hookPath, "utf8");
+    }
+    catch {
+        /* unreadable — treat like missing below */
+    }
+    const managed = content.includes(HOOK_MARKER);
+    return warn("hooks_installed", "git hooks installed", managed, managed
+        ? "pre-commit hook installed"
+        : ".git/hooks/pre-commit exists but was not installed by RepoSkein", managed ? undefined : "run `reposkein-mcp init` to install the pre-commit/post-merge hooks");
+}
+/** `git -C repoPath rev-parse HEAD`, or null on any failure (no git, not a
+ *  repo, no commits yet). */
+function currentHeadSha(repoPath) {
+    try {
+        const out = execFileSync("git", ["-C", repoPath, "rev-parse", "HEAD"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Content-based staleness: the committed graph is fresh iff the commit SHA
+ *  recorded the last time it was (re)built (`.reposkein/local/indexed-at` —
+ *  see mcp/src/store/indexedAt.ts) equals the current git HEAD. The marker
+ *  is kept current two ways: the installed git hooks maintain it on their
+ *  own (`post-commit` after every commit, `post-merge`/`post-checkout` —
+ *  which also re-index — after a merge/pull/branch switch), and
+ *  `reposkein-mcp index`/`init` write it directly. A mismatch therefore
+ *  means one of: the hooks were never installed (or were removed), or
+ *  nobody's indexed this repo at all yet.
+ *
+ *  Replaces an earlier mtime-based heuristic (mtime(nodes.jsonl) vs. the last
+ *  commit's timestamp) that turned out to be structurally blind after any
+ *  fresh checkout: `git clone`/`checkout` — or a CI cache restoring
+ *  `.reposkein/` from a prior run — stamps every file it writes with
+ *  "now", which is always ≥ any past commit's timestamp, so
+ *  `mtime < lastCommitMs` could never be true right when it mattered most.
+ *  A recorded SHA has no such blind spot: it's compared by value, not by
+ *  filesystem timestamp.
+ *
+ *  Deliberately a **plain SHA mismatch**, not a diff filtered to
+ *  indexed-language extensions: filtering would need to stay in sync with
+ *  `config.toml`'s `[languages] enabled` list and the indexer's own
+ *  extension→language table, which is one more thing to drift. The cost of
+ *  getting it wrong is asymmetric — a false "stale" just costs a redundant
+ *  `reposkein-mcp index` (cheap), while a false "fresh" is exactly the bug
+ *  being fixed — so the simpler, conservative rule wins here.
+ *
+ *  Two distinct failure shapes, both reported under the same check id:
+ *   - no recorded SHA at all → never indexed via a hook or the mcp-side path
+ *     (a fresh clone's local/ never carries over, since it's gitignored) —
+ *     FAIL.
+ *   - a recorded SHA that doesn't match HEAD → the hooks are missing (or
+ *     were bypassed, e.g. `git commit --no-verify`) and nobody's re-indexed
+ *     by hand either — FAIL.
+ *
+ *  Non-critical by default; `doctor --ci` promotes it (CI_FAIL_IDS in
+ *  doctor.ts). */
+export function graphStaleCheck(repoPath) {
+    const nodesFile = join(repoPath, ".reposkein", "nodes.jsonl");
+    if (!existsSync(nodesFile)) {
+        return warn("graph_stale", "graph freshness", false, "no .reposkein/nodes.jsonl (never indexed)", "run `reposkein-mcp index`");
+    }
+    const recordedSha = readIndexedAtSha(repoPath);
+    if (!recordedSha) {
+        return warn("graph_stale", "graph freshness", false, "nodes.jsonl exists but no recorded indexed-at commit (.reposkein/local/indexed-at) — " +
+            "the post-commit/post-merge/post-checkout hooks maintain this automatically, so its " +
+            "absence means the hooks aren't installed (or local/ never carried over a clone) and " +
+            "nobody's run `reposkein-mcp index`/`init` by hand either", "run `reposkein-mcp index`");
+    }
+    const headSha = currentHeadSha(repoPath);
+    if (headSha === null) {
+        return warn("graph_stale", "graph freshness", true, "no git HEAD to compare against (skipped)");
+    }
+    if (recordedSha === headSha) {
+        return warn("graph_stale", "graph freshness", true, `graph matches HEAD (${headSha.slice(0, 7)})`);
+    }
+    return warn("graph_stale", "graph freshness", false, `graph was indexed at ${recordedSha.slice(0, 7)}, but HEAD is now ${headSha.slice(0, 7)} — commits landed since ` +
+        "the last index without the marker advancing (hooks missing/bypassed, or the graph was never re-indexed)", "run `reposkein-mcp index`");
+}
+//# sourceMappingURL=doctorFreshness.js.map

package/dist/cli/doctorFreshness.js.map

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

package/dist/cli/doctorSummaries.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from "./doctor.js";
+export declare function summaryChecks(repoPath: string): Check[];

package/dist/cli/doctorSummaries.js

@@ -0,0 +1,95 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { countRecordedConflicts, isShardFileName, loadSummaryShards, summariesDir, } from "../store/summaryShards.js";
+/** Health of the committed authored summaries, `.reposkein/summaries/<xx>.jsonl`.
+ *
+ *  Every check is non-critical. Summaries are the one part of `.reposkein/`
+ *  nothing can regenerate, so the failure mode that matters is *silent* loss:
+ *  prose that exists on disk but will never be committed, or a merge that
+ *  dropped a record. Each check below names one way that happens.
+ *
+ *  Returns [] when the repo has no committed summaries and no legacy file —
+ *  a repo that has never had an agent write one has nothing to report. */
+const warn = (id, label, ok, detail, fix) => ({
+    id,
+    label,
+    ok,
+    critical: false,
+    detail,
+    fix: ok ? undefined : fix,
+});
+/** `git check-ignore -v <path>`, or null when the path is not ignored (or git
+ *  is unavailable / this is not a repo). The verbose form names the source:
+ *  `<file>:<line>:<pattern>\t<path>`. */
+function checkIgnoreSource(repoPath, relPath) {
+    try {
+        const out = execFileSync("git", ["-C", repoPath, "check-ignore", "-v", "--no-index", relPath], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const first = out.split("\n")[0]?.trim();
+        return first ? first.split("\t")[0] : null;
+    }
+    catch {
+        // exit 1 = not ignored; anything else = no git. Both mean "no finding".
+        return null;
+    }
+}
+export function summaryChecks(repoPath) {
+    const dir = summariesDir(repoPath);
+    let shardCount = 0;
+    try {
+        shardCount = readdirSync(dir).filter(isShardFileName).length;
+    }
+    catch {
+        shardCount = 0;
+    }
+    const legacyPresent = existsSync(join(repoPath, ".reposkein", "summaries.jsonl"));
+    if (shardCount === 0 && !legacyPresent)
+        return [];
+    const checks = [];
+    const loaded = loadSummaryShards(repoPath);
+    // 1) The pre-sharding single file is still there.
+    //
+    //    One committed summaries.jsonl is exactly the artifact that made every
+    //    branch conflict — the #35 lesson. It is read for one release so nothing
+    //    is stranded, but leaving it is a conflict waiting to happen.
+    checks.push(warn("summaries_unsplit", "summaries sharded", !legacyPresent, legacyPresent
+        ? `.reposkein/summaries.jsonl is still present (${loaded.summaries.size} record(s) readable); every branch that writes a summary will conflict on it`
+        : `${shardCount} shard(s), ${loaded.summaries.size} summar${loaded.summaries.size === 1 ? "y" : "ies"}`, "run `reposkein-indexer index .` — it folds the file into .reposkein/summaries/<xx>.jsonl and retires it; commit the result"));
+    // 2) A .gitignore pattern is masking the shards.
+    //
+    //    A repo-root rule like `.reposkein/*` (or a blanket `*.jsonl`) silently
+    //    keeps the shards out of every commit. Nothing errors — the summaries
+    //    simply never reach a teammate, and are lost with the machine.
+    const probe = shardCount > 0 ? firstShardRelPath(repoPath) : ".reposkein/summaries/00.jsonl";
+    const ignoredBy = checkIgnoreSource(repoPath, probe);
+    checks.push(warn("summaries_committable", "summary shards committable", ignoredBy === null, ignoredBy === null
+        ? "not git-ignored"
+        : `${probe} is ignored by ${ignoredBy} — authored summaries would never be committed`, "add a negation after that rule, e.g. `!**/.reposkein/summaries/`, then `git add .reposkein/summaries`"));
+    // 3) Damaged shard content: conflict markers or unparseable lines.
+    checks.push(warn("summaries_readable", "summary shards parse", loaded.warnings.length === 0, loaded.warnings.length === 0
+        ? `${loaded.summaries.size} record(s) read cleanly`
+        : loaded.warnings.join("; "), "run `reposkein-indexer index .` to rewrite the shards canonically, then commit them"));
+    // 4) Divergent records preserved from a merge. Not an error — the resolution
+    //    is deterministic — but a human should read the loser before it is
+    //    forgotten, because nothing can regenerate it.
+    const conflicts = countRecordedConflicts(repoPath);
+    checks.push(warn("summaries_conflicts", "summary merge conflicts", conflicts === 0, conflicts === 0
+        ? "none recorded"
+        : `${conflicts} record(s) lost a merge tiebreak and were preserved in .reposkein/local/conflicts.jsonl`, "read .reposkein/local/conflicts.jsonl; re-write any summary worth keeping, then delete the file"));
+    return checks;
+}
+function firstShardRelPath(repoPath) {
+    try {
+        const names = readdirSync(summariesDir(repoPath)).filter(isShardFileName).sort();
+        if (names[0])
+            return `.reposkein/summaries/${names[0]}`;
+    }
+    catch {
+        // fall through
+    }
+    return ".reposkein/summaries/00.jsonl";
+}
+//# sourceMappingURL=doctorSummaries.js.map

package/dist/cli/doctorSummaries.js.map

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

package/dist/cli/federatedDiscovery.d.ts

@@ -0,0 +1,16 @@
+export interface FederatedRepo {
+    /** repo_id from the nested repo's meta.json (or its directory name if the
+     *  meta.json is missing/unreadable). */
+    repoId: string;
+    /** Path of the nested repo root, relative to the scanned root (posix-style). */
+    rootPath: string;
+    /** Absolute path of the nested repo root. */
+    absPath: string;
+}
+/** Scans descendants of `repoPath` for nested repos (directories containing a
+ *  `.reposkein/` marker), excluding `repoPath` itself. Does not recurse past a
+ *  hit — a repo nested inside another nested repo is out of scope for a single
+ *  export pass. Bounded to `maxDepth` levels (default 6) so a pathological
+ *  tree can't cause an unbounded scan. Deterministic (sorted by rootPath).
+ *  Best-effort: unreadable directories are skipped, never thrown. */
+export declare function discoverFederatedRepos(repoPath: string, maxDepth?: number): FederatedRepo[];

package/dist/cli/federatedDiscovery.js

@@ -0,0 +1,75 @@
+import { readdirSync, existsSync, readFileSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+/** Directories never descended into while scanning for nested repos: build
+ *  output, VCS internals, other worktrees/tool state — mirrors the skip set
+ *  used by store/resolveRepoPath.ts's walk-down discovery. */
+const SKIP_DIR_NAMES = new Set([
+    "node_modules",
+    ".git",
+    "target",
+    "dist",
+    ".worktrees",
+    ".claude",
+]);
+/** Scans descendants of `repoPath` for nested repos (directories containing a
+ *  `.reposkein/` marker), excluding `repoPath` itself. Does not recurse past a
+ *  hit — a repo nested inside another nested repo is out of scope for a single
+ *  export pass. Bounded to `maxDepth` levels (default 6) so a pathological
+ *  tree can't cause an unbounded scan. Deterministic (sorted by rootPath).
+ *  Best-effort: unreadable directories are skipped, never thrown. */
+export function discoverFederatedRepos(repoPath, maxDepth = 6) {
+    const root = resolve(repoPath);
+    const hits = [];
+    function isReposkeinDir(dir) {
+        try {
+            return statSync(join(dir, ".reposkein")).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }
+    function recurse(dir, depth) {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable dir — skip, don't fail the export
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (SKIP_DIR_NAMES.has(entry.name))
+                continue;
+            if (entry.name === ".reposkein")
+                continue;
+            const full = join(dir, entry.name);
+            if (isReposkeinDir(full)) {
+                let repoId = entry.name;
+                const metaPath = join(full, ".reposkein", "meta.json");
+                if (existsSync(metaPath)) {
+                    try {
+                        const meta = JSON.parse(readFileSync(metaPath, "utf8"));
+                        if (typeof meta.repo_id === "string" && meta.repo_id)
+                            repoId = meta.repo_id;
+                    }
+                    catch {
+                        // fall back to the directory name
+                    }
+                }
+                hits.push({
+                    repoId,
+                    rootPath: relative(root, full).split("\\").join("/") || ".",
+                    absPath: full,
+                });
+                continue; // don't descend further into a hit
+            }
+            recurse(full, depth + 1);
+        }
+    }
+    recurse(root, 1);
+    return hits.sort((a, b) => (a.rootPath < b.rootPath ? -1 : a.rootPath > b.rootPath ? 1 : 0));
+}
+//# sourceMappingURL=federatedDiscovery.js.map

package/dist/cli/federatedDiscovery.js.map

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

package/dist/cli/init.d.ts

@@ -1,3 +1,4 @@
+import { type AgentId, type WriteAgentConfigsOptions } from "./agentAdapters.js";
 /** Where the navigation skill is installed for a repo (Claude project skills). */
 export declare function skillTargetPath(repoPath: string): string;
 /** The bundled SKILL.md inside the installed package (dist/SKILL.md). */
@@ -7,13 +8,75 @@ export declare function mcpConfigSnippet(repoPath: string): string;
 /** Idempotently add the per-machine MCP config files to the repo's .gitignore
  *  (creating it if absent), so `reposkein-mcp init` never leaves them tracked. */
 export declare function ensureLocalConfigGitignored(repoPath: string): void;
+/** True when `.reposkein/meta.json` is tracked by git — this clone joined a
+ *  repo that already has RepoSkein set up (someone else ran `init` and
+ *  committed it), rather than being the first machine to set it up (whose
+ *  meta.json exists on disk but isn't committed yet). Join mode skips
+ *  first-time scaffolding entirely and instead wires up the local agent(s)
+ *  automatically (REP-16 T5) — see `runInit`.
+ *
+ *  Falls back to plain existence when git itself is unavailable (no `git`
+ *  binary, or `repoPath` isn't a git repo yet) so `init` still behaves
+ *  sensibly outside a git repo rather than throwing. */
+export declare function detectJoinMode(repoPath: string): boolean;
+/** Where `init --ci` writes the Pages-publish workflow in the target repo. */
+export declare function ciWorkflowTargetPath(repoPath: string): string;
+/** Template written by `reposkein-mcp init --ci`: a thin caller of RepoSkein's
+ *  reusable publish workflow (see docs/HOSTING.md). Consumers get released
+ *  indexer binaries (no Rust toolchain) + a self-contained static export
+ *  published to GitHub Pages. Repo owners must still flip Settings → Pages →
+ *  "Build and deployment: GitHub Actions" once. */
+export declare function ciWorkflowTemplate(): string;
+/** `reposkein-mcp init --ci`: writes the Pages-publish workflow template into
+ *  the target repo's `.github/workflows/`. Non-destructive: skips (with a
+ *  message) if the file already exists, so a re-run never clobbers a repo
+ *  owner's edits. Returns whether it wrote the file. */
+export declare function writeCiWorkflow(repoPath: string): {
+    written: boolean;
+    path: string;
+};
 /** `reposkein-mcp index [path]`: (re)build the code graph at `repoPath` using the
  *  native indexer. The package-friendly way to index — the `reposkein-indexer`
- *  binary is fetched into the package (not on PATH), so end users run this. */
+ *  binary is fetched into the package (not on PATH), so end users run this.
+ *  On success, also records the current git HEAD to `.reposkein/local/indexed-at`
+ *  — `doctor --ci`'s `graph_stale` check reads it back (see doctorFreshness.ts).
+ *  The installed git hooks maintain the same marker themselves (`post-commit`
+ *  after every commit, `post-merge`/`post-checkout` — which also re-index —
+ *  after a merge/pull/branch switch; see the hook templates in
+ *  indexer/crates/cli/src/main.rs), so this mcp-side write is the "manual
+ *  index" case, not the only path that keeps the marker current. */
 export declare function runIndex(repoPath?: string): Promise<number>;
-/** `reposkein-mcp init [path] [--no-index]`: ensure the indexer, install git hooks,
- *  build the initial graph, install the navigation skill, and print the MCP config +
- *  next steps. Pass `index: false` to skip the initial index. */
-export declare function runInit(repoPath?: string, opts?: {
+export interface RunInitOptions {
     index?: boolean;
-}): Promise<number>;
+    ci?: boolean;
+    /** Explicit `--agents` override for join mode; detected when omitted. */
+    agents?: AgentId[];
+    /** `--dry-run`: plan agent config writes without touching disk. */
+    dryRun?: boolean;
+    /** Force join-mode on/off; auto-detected (committed .reposkein/meta.json)
+     *  when omitted — see `detectJoinMode`. */
+    join?: boolean;
+    /** Test-only injection point for the agent-adapter step (fake `exec`/`now`). */
+    agentWriteOpts?: Pick<WriteAgentConfigsOptions, "exec" | "now">;
+}
+/** `reposkein-mcp init [path] [--no-index] [--ci] [--agents <list>] [--dry-run]`:
+ *  ensure the indexer, install git hooks, build the initial graph, install
+ *  the navigation skill, then either (join mode) auto-write the local
+ *  agent(s) MCP config, or (first-time) print the config snippet to paste in
+ *  by hand. Pass `index: false` to skip the initial index; `ci: true` to
+ *  also write the GitHub Pages publish workflow (see docs/HOSTING.md).
+ *
+ *  Join mode (REP-16 T5): auto-detected when `.reposkein/meta.json` is
+ *  already committed (`detectJoinMode`) — i.e. someone cloned a repo that
+ *  already has RepoSkein set up. Skips nothing structural (hooks/index/skill
+ *  still run so a stale local checkout gets caught up) but additionally
+ *  writes `.mcp.json` / `opencode.json` / `.cursor/mcp.json` for whichever
+ *  agent(s) are detected present (or `opts.agents`), then prints a doctor
+ *  summary instead of a config snippet to copy by hand.
+ *
+ *  Unsupported platform (darwin-x64, win32-arm64, no REPOSKEIN_INDEXER_BIN):
+ *  prints cargo-install fallback instructions and CONTINUES instead of
+ *  crashing — hooks + the initial index are skipped (nothing to run them
+ *  with), but the skill, CI workflow, and (in join mode) agent config are
+ *  still written, and the function returns 0. */
+export declare function runInit(repoPath?: string, opts?: RunInitOptions): Promise<number>;