syncstaff-mcp 0.2.3

package/dist/lib/client-config.js

@@ -0,0 +1,81 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+function configPath(root) {
+    return join(root, ".keel", "config.json");
+}
+function validate(value, path) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`invalid Keel client config at ${path}: expected an object`);
+    }
+    const candidate = value;
+    if (candidate.version !== 1) {
+        throw new Error(`invalid Keel client config at ${path}: unsupported version`);
+    }
+    for (const key of ["server", "project", "token", "vendor"]) {
+        if (typeof candidate[key] !== "string" || !candidate[key].trim()) {
+            throw new Error(`invalid Keel client config at ${path}: ${key} is required`);
+        }
+    }
+    let server;
+    try {
+        server = new URL(candidate.server);
+    }
+    catch {
+        throw new Error(`invalid Keel client config at ${path}: server must be an absolute URL`);
+    }
+    if (!["http:", "https:"].includes(server.protocol) || server.username || server.password) {
+        throw new Error(`invalid Keel client config at ${path}: server must be an HTTP(S) URL without credentials`);
+    }
+    if (server.search || server.hash) {
+        throw new Error(`invalid Keel client config at ${path}: server must not contain a query or fragment`);
+    }
+    if (!/^ch_[A-Za-z0-9_-]+$/.test(candidate.token)) {
+        throw new Error(`invalid Keel client config at ${path}: token has an unexpected format`);
+    }
+    return {
+        version: 1,
+        server: server.toString().replace(/\/+$/, ""),
+        project: candidate.project.trim(),
+        token: candidate.token.trim(),
+        vendor: candidate.vendor.trim(),
+    };
+}
+/** Load repo-local adapter credentials, or null before `keel login`. */
+export function loadClientConfig(root) {
+    const path = configPath(root);
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new Error(`invalid Keel client config at ${path}: file is not valid JSON`);
+    }
+    return validate(parsed, path);
+}
+/** Atomically save adapter credentials with owner-only permissions. */
+export function saveClientConfig(root, config) {
+    const path = configPath(root);
+    const validated = validate(config, path);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    chmodSync(dirname(path), 0o700);
+    const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        writeFileSync(temporary, `${JSON.stringify(validated, null, 2)}\n`, {
+            encoding: "utf8",
+            flag: "wx",
+            mode: 0o600,
+        });
+        renameSync(temporary, path);
+        // A pre-existing destination may have had weaker permissions. rename(2)
+        // replaces it with the mode-0600 temp file; chmod is belt and braces for
+        // platforms whose rename semantics differ.
+        chmodSync(path, 0o600);
+    }
+    finally {
+        if (existsSync(temporary))
+            unlinkSync(temporary);
+    }
+    return path;
+}

package/dist/lib/env-compat.js

@@ -0,0 +1,66 @@
+/**
+ * KEEL_* ⇄ CHARTER_* environment aliasing.
+ *
+ * The service is renamed Charter → Keel. Twenty-six environment variables
+ * carry the old prefix, and they are read from ~30 files, three agent hook
+ * configs, two MCP configs, a CI workflow, and a systemd unit on a host this
+ * repo does not control. Renaming all of that in one commit means every one
+ * of those has to land simultaneously, and anything that restarts in between
+ * comes up misconfigured.
+ *
+ * That is not a hypothetical here. `src/mcp/index.ts` was switched to KEEL_*
+ * before the configs that feed it were, so the adapter would have thrown
+ * "KEEL_PROJECT env var is required" on the first tool call after any agent
+ * restarted — while `dist/` still held a pre-rename build, so the breakage was
+ * invisible until the next `npm run build`. A test run would have armed it.
+ *
+ * So instead: alias both directions, once, at process start. Every variable
+ * answers to both names, the running fleet keeps working on CHARTER_*, new
+ * code can read KEEL_*, and the configs migrate one at a time instead of all
+ * at once. This module is the reason the rename does not need a window.
+ *
+ * Remove it only when nothing sets CHARTER_* anywhere — including the VPS
+ * systemd unit and every developer's shell profile, which is the part nobody
+ * remembers.
+ */
+const PREFIXES = ["SYNCSTAFF_", "NAIB_", "KEEL_", "CHARTER_"];
+/**
+ * Mirror SYNCSTAFF_x ⇄ NAIB_x ⇄ KEEL_x ⇄ CHARTER_x across all naming eras.
+ *
+ * An explicitly set value always wins: if multiple names are present with
+ * different values, neither is overwritten.
+ *
+ * Idempotent, so entry points may call it more than once.
+ */
+export function aliasEnv(env = process.env) {
+    for (const [key, value] of Object.entries(env)) {
+        if (value === undefined)
+            continue;
+        for (const sourcePrefix of PREFIXES) {
+            if (key.startsWith(sourcePrefix)) {
+                const suffix = key.slice(sourcePrefix.length);
+                for (const targetPrefix of PREFIXES) {
+                    if (targetPrefix !== sourcePrefix) {
+                        const renamed = targetPrefix + suffix;
+                        if (env[renamed] === undefined)
+                            env[renamed] = value;
+                    }
+                }
+                break;
+            }
+        }
+    }
+}
+/**
+ * Read a variable by its suffix under NAIB_, KEEL_, or CHARTER_ prefix (newest first).
+ */
+export function naibEnv(suffix) {
+    return process.env["SYNCSTAFF_" + suffix] ?? process.env["NAIB_" + suffix] ?? process.env["KEEL_" + suffix] ?? process.env["CHARTER_" + suffix];
+}
+export const keelEnv = naibEnv;
+// Aliasing on import is deliberate. Several modules read process.env at module
+// scope (`const SERVER = process.env.KEEL_URL ?? …`), which runs before any
+// entry point's first statement. A function an entry point must remember to
+// call would therefore be called too late, and the failure would be a silent
+// fallback to a default rather than an error.
+aliasEnv();

package/dist/lib/ids.js

@@ -0,0 +1,24 @@
+import { randomBytes } from "node:crypto";
+const B32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"; // Crockford base32
+function encodeTime(ms) {
+    let out = "";
+    for (let i = 9; i >= 0; i--) {
+        out = B32[ms % 32] + out;
+        ms = Math.floor(ms / 32);
+    }
+    return out;
+}
+function encodeRandom(len) {
+    const bytes = randomBytes(len);
+    let out = "";
+    for (let i = 0; i < len; i++)
+        out += B32[bytes[i] % 32];
+    return out;
+}
+export function ulid(prefix) {
+    const id = encodeTime(Date.now()) + encodeRandom(16);
+    return prefix ? `${prefix}_${id}` : id;
+}
+export function now() {
+    return new Date().toISOString();
+}

package/dist/lib/index/aliases.js

@@ -0,0 +1,244 @@
+/**
+ * Path aliases: the mappings that make a bare specifier internal.
+ *
+ * `import { BoardItemEditor } from "@/components/board/BoardItemEditor"` is not
+ * a package. It is a local file, renamed by a `paths` entry in tsconfig.json.
+ * A resolver that does not read that config classifies it as external, and
+ * every internal edge in the application disappears.
+ *
+ * That was true of this repository until now. web/tsconfig.json declares
+ * `"@/*": ["./src/*"]`, six files import through it, and the graph saw none of
+ * those edges. The real-repo tests passed only because they were scoped to
+ * keel/src, which uses relative imports throughout — the blind spot was hiding
+ * behind the choice of test corpus, which is the most comfortable place for a
+ * blind spot to hide.
+ *
+ * Three decisions here are deliberate, and each is a place where the obvious
+ * implementation is worse:
+ *
+ * SCOPE. A monorepo has several tsconfigs. web/tsconfig.json's aliases apply
+ * to web/, not to keel/. Applying every alias everywhere would invent edges
+ * across package boundaries — the same class of error as matching a name in an
+ * unrelated language. Each mapping records the directory it governs, and the
+ * nearest governing config wins.
+ *
+ * AMBIGUITY IS NOT A CHOICE. A `paths` entry may list several targets, and
+ * TypeScript tries them in order. Picking the first that exists would usually
+ * be right and would occasionally invent an edge to a file the compiler would
+ * never have chosen. When more than one candidate exists on disk, this reports
+ * the specifier as ambiguous and names both, rather than guessing.
+ *
+ * THE CONFIG IS PART OF THE INDEX IDENTITY. Two checkouts with identical
+ * source but different `paths` produce different graphs. If the fingerprint
+ * ignored the alias map, those two would claim to be the same index and a
+ * blast radius computed on one would be quietly wrong on the other. So
+ * `aliasSignature()` folds into the fingerprint alongside the parser version,
+ * for the same reason.
+ */
+/** POSIX join that tolerates empty segments and normalises "." and "..". */
+function joinPath(...parts) {
+    const segments = [];
+    for (const part of parts.join("/").split("/")) {
+        if (!part || part === ".")
+            continue;
+        if (part === "..") {
+            if (segments.length > 0)
+                segments.pop();
+            continue;
+        }
+        segments.push(part);
+    }
+    return segments.join("/");
+}
+const dirOf = (path) => {
+    const slash = path.lastIndexOf("/");
+    return slash === -1 ? "" : path.slice(0, slash);
+};
+/**
+ * JSON with comments and trailing commas — tsconfig.json is JSONC, and
+ * JSON.parse rejects both. Deliberately small: this strips line and block
+ * comments outside strings and removes trailing commas. A config exotic enough
+ * to defeat it yields no aliases, which degrades to today's behaviour rather
+ * than to a wrong one.
+ */
+function parseJsonc(text) {
+    let out = "";
+    let inString = false;
+    let quote = "";
+    for (let i = 0; i < text.length; i += 1) {
+        const char = text[i];
+        const next = text[i + 1];
+        if (inString) {
+            out += char;
+            if (char === "\\") {
+                out += next ?? "";
+                i += 1;
+            }
+            else if (char === quote) {
+                inString = false;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            inString = true;
+            quote = char;
+            out += char;
+            continue;
+        }
+        if (char === "/" && next === "/") {
+            while (i < text.length && text[i] !== "\n")
+                i += 1;
+            out += "\n";
+            continue;
+        }
+        if (char === "/" && next === "*") {
+            i += 2;
+            while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
+                i += 1;
+            i += 1;
+            continue;
+        }
+        out += char;
+    }
+    out = out.replace(/,(\s*[}\]])/g, "$1");
+    try {
+        return JSON.parse(out);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Collect every alias rule declared by config files in the indexed set.
+ *
+ * Only files already discovered are read — the index never reaches outside
+ * what it was given, which keeps this consistent with the parser's rule about
+ * ambient authority.
+ */
+export function discoverAliases(files, options) {
+    const rules = [];
+    const configs = files.filter((path) => path.endsWith("tsconfig.json") || path.endsWith("jsconfig.json") || path.endsWith("package.json"));
+    for (const configPath of [...configs].sort()) {
+        const scope = dirOf(configPath);
+        let parsed;
+        try {
+            parsed = parseJsonc(options.readFile(configPath));
+        }
+        catch {
+            continue; // unreadable config: no aliases, not a failure
+        }
+        if (!parsed || typeof parsed !== "object")
+            continue;
+        if (configPath.endsWith("package.json")) {
+            rules.push(...packageImports(parsed, scope, configPath));
+            continue;
+        }
+        rules.push(...tsconfigPaths(parsed, scope, configPath, files, options, 0));
+    }
+    // Longest prefix first so "@/components/" beats "@/", and the more specific
+    // mapping is the one that applies — matching how TypeScript itself picks.
+    return rules.sort((a, b) => b.prefix.length - a.prefix.length || (a.scope < b.scope ? -1 : a.scope > b.scope ? 1 : 0));
+}
+function tsconfigPaths(config, scope, source, files, options, depth) {
+    const rules = [];
+    const compilerOptions = (config.compilerOptions ?? {});
+    // `extends` first, so a local `paths` can override an inherited one by
+    // being appended later and winning the longest-prefix sort on equal length.
+    const extendsRef = config.extends;
+    if (typeof extendsRef === "string" && depth < (options.maxExtends ?? 5)) {
+        const target = extendsRef.startsWith(".")
+            ? joinPath(scope, extendsRef.endsWith(".json") ? extendsRef : `${extendsRef}.json`)
+            : null;
+        if (target && files.includes(target)) {
+            try {
+                const parent = parseJsonc(options.readFile(target));
+                if (parent && typeof parent === "object") {
+                    rules.push(...tsconfigPaths(parent, dirOf(target), target, files, options, depth + 1));
+                }
+            }
+            catch {
+                /* an unreadable parent contributes nothing */
+            }
+        }
+    }
+    const paths = compilerOptions.paths;
+    if (!paths || typeof paths !== "object")
+        return rules;
+    // baseUrl is relative to the config that declares it; targets are relative
+    // to baseUrl. Omitting baseUrl means targets are relative to the config.
+    const baseUrl = typeof compilerOptions.baseUrl === "string" ? compilerOptions.baseUrl : ".";
+    const base = joinPath(scope, baseUrl);
+    for (const [pattern, rawTargets] of Object.entries(paths)) {
+        if (!Array.isArray(rawTargets))
+            continue;
+        const wildcard = pattern.endsWith("*");
+        const prefix = wildcard ? pattern.slice(0, -1) : pattern;
+        const targets = rawTargets
+            .filter((t) => typeof t === "string")
+            .map((t) => joinPath(base, wildcard ? t.replace(/\*$/, "") : t));
+        if (targets.length === 0)
+            continue;
+        rules.push({ scope, prefix, wildcard, targets, source });
+    }
+    return rules;
+}
+/**
+ * Node's own alias mechanism: package.json "imports", where keys begin with
+ * "#". Supported because it is the standard-track answer to the same problem
+ * and costs a dozen lines once the tsconfig machinery exists.
+ */
+function packageImports(config, scope, source) {
+    const imports = config.imports;
+    if (!imports || typeof imports !== "object")
+        return [];
+    const rules = [];
+    for (const [pattern, rawTarget] of Object.entries(imports)) {
+        if (!pattern.startsWith("#"))
+            continue;
+        // A conditional object ({"node": "./a.js", "default": "./b.js"}) has no
+        // single answer without knowing the runtime condition. Take every leaf as
+        // a candidate; if more than one exists on disk the resolver calls it
+        // ambiguous, which is the truthful outcome.
+        const targets = collectStringLeaves(rawTarget).map((t) => joinPath(scope, t.replace(/\*$/, "")));
+        if (targets.length === 0)
+            continue;
+        const wildcard = pattern.endsWith("*");
+        rules.push({
+            scope,
+            prefix: wildcard ? pattern.slice(0, -1) : pattern,
+            wildcard,
+            targets,
+            source,
+        });
+    }
+    return rules;
+}
+function collectStringLeaves(value, depth = 0) {
+    if (typeof value === "string")
+        return [value];
+    if (depth > 4 || !value || typeof value !== "object")
+        return [];
+    return Object.values(value).flatMap((v) => collectStringLeaves(v, depth + 1));
+}
+/** Does this rule govern the file doing the importing? */
+export function ruleGoverns(rule, fromPath) {
+    if (rule.scope === "")
+        return true;
+    return fromPath === rule.scope || fromPath.startsWith(`${rule.scope}/`);
+}
+/**
+ * The alias configuration's contribution to the index fingerprint.
+ *
+ * Same argument as the parser version. Identical source with a different
+ * `paths` block produces a different graph, so the two indexes must not claim
+ * to be the same one. Sorted, because the order rules were discovered in is a
+ * property of the walk rather than of the repository.
+ */
+export function aliasSignature(aliases) {
+    if (aliases.length === 0)
+        return "none";
+    return aliases
+        .map((rule) => `${rule.scope}|${rule.prefix}${rule.wildcard ? "*" : ""}=>${rule.targets.join(",")}`)
+        .sort()
+        .join(";");
+}

package/dist/lib/index/call-sites.js

@@ -0,0 +1,178 @@
+/**
+ * Call-site resolution for blast radius, backed by the local graph.
+ *
+ * This is the bridge between the graph subsystem and the coordination
+ * protocol, and it exists to retire one specific line of code:
+ *
+ *   const callRe = new RegExp(`\\b${escapeRe(lastSeg)}\\s*\\(`);
+ *
+ * That is `grep-v1`, in lib/blast.ts. It finds a symbol's final dotted
+ * segment followed by an open paren, anywhere in any TS/JS/Python file,
+ * skipping only lines that look like declarations. It has no idea what a
+ * comment is.
+ *
+ * On 13 August it was asked for the call sites of a TypeScript method named
+ * `check` and returned 38, sixteen of them in an unrelated Python package.
+ * The worst was:
+ *
+ *   # side of the ORPHAN check (but NOT FTS, which only indexes
+ *
+ * A word, a space, an open paren, inside a comment. The count tripped a width
+ * threshold, the intent escalated, and an agent stopped for a human decision
+ * that existed only because a regex cannot tell prose from code. There is a
+ * test in local-call-sites.test.ts holding that exact line.
+ *
+ * What replaces it resolves a call only when the name is bound in the calling
+ * file — defined there or imported there — and the target actually exports it.
+ * A comment cannot satisfy that, and neither can a same-named function in a
+ * package nobody imports.
+ *
+ * Two rules about honesty, because a quieter analyzer that is quietly wrong
+ * would be worse than the loud one it replaces:
+ *
+ *   The analyzer is always named in the report. A consumer must never have to
+ *   guess whether a result came from the graph or from grep.
+ *
+ *   Where the graph cannot see — a language with no backend, a repository
+ *   where typescript is not installed — this returns null and the caller falls
+ *   back to grep rather than reporting an empty, confident answer. Silence
+ *   from a blind analyzer is the one output worse than noise.
+ */
+import { buildFileIndex } from "./file-index.js";
+import { buildDependencyGraph } from "./graph.js";
+import { buildSymbolTable, resolveCallEdges, resolveReferenceEdges, } from "./symbols.js";
+/**
+ * Build a call-site index over a checkout, or return null if the graph cannot
+ * see it.
+ *
+ * Null is a real answer and the caller must respect it: no parser backend
+ * means no graph, and pretending otherwise would report "no call sites" for a
+ * repository nobody analysed.
+ *
+ * The index is built once and queried many times, because
+ * attachClientCallSiteReports asks about several symbols per intent and
+ * rebuilding per symbol would make the graph slower than the regex it
+ * replaces.
+ */
+export function buildGraphCallSiteIndex(repoPath, loadParsers, options = {}) {
+    const registry = loadParsers();
+    if (!registry)
+        return null;
+    let index;
+    let calls;
+    let references;
+    try {
+        index = buildFileIndex(repoPath, registry, { exclude: options.exclude });
+        const graph = buildDependencyGraph(index);
+        void graph; // built for its side of the pipeline; edges come from calls below
+        const table = buildSymbolTable(index);
+        calls = resolveCallEdges(index, table);
+        // One table, one resolver, two views of it. Building references from a
+        // second symbol table would let the two surfaces drift apart, which is the
+        // defect R12.0 names rather than a detail of how they are wired.
+        references = resolveReferenceEdges(index, table);
+    }
+    catch {
+        // A graph that failed to build is not a graph that found nothing.
+        return null;
+    }
+    // Nothing was parsed at all — a repository of Markdown, or a backend that
+    // matched no extension. Same reasoning as null above.
+    if (index.coverage.parsed + index.coverage.partial === 0)
+        return null;
+    /**
+     * Which files EXPORT each name.
+     *
+     * Both maps below are keyed by name alone, because a caller asking for a
+     * blast radius has a name and nothing else. That is the right key for the
+     * question and the wrong key for the answer: two unrelated symbols may share
+     * a spelling, and the resolver — correctly — binds each reference to
+     * whichever one is in scope where it appears. Keying the *result* by name
+     * then pools them back together, undoing the resolution that just happened.
+     *
+     * What that looked like here: `now`, exported by lib/ids.ts, collected the
+     * two reads of a `const now` local to lib/slack.ts; `keelEnv`, exported by
+     * lib/env-compat.ts, collected five calls to a same-named local in a script
+     * that does not import it. Both were labelled "confirmed" — the label that
+     * tells a human these are the trustworthy ones. Across this repository 268
+     * sites were wrong this way, and they are what has kept the real-code
+     * precision test red since 17 August.
+     *
+     * The rule that removes them: a name declared in an intent is an EXPORTED
+     * name — `interfaces_touched` is a list of exports — so a reference the
+     * resolver bound to a file-local definition belongs to a different symbol
+     * that merely reads the same. When some file exports the name, only
+     * references resolving to one of those files are part of its radius.
+     *
+     * When nothing exports the name, every binding is kept: that is a purely
+     * local symbol, and a caller asking about one wants exactly those sites.
+     */
+    const exportersOf = new Map();
+    for (const file of index.files) {
+        for (const exported of file.result.exports) {
+            const owners = exportersOf.get(exported.name);
+            if (owners)
+                owners.add(file.path);
+            else
+                exportersOf.set(exported.name, new Set([file.path]));
+        }
+    }
+    /** Does this edge bind to the name's exported symbol, or to a namesake? */
+    const bindsToTheExportedSymbol = (symbol, to) => {
+        const owners = exportersOf.get(symbol);
+        return owners === undefined || owners.size === 0 || owners.has(to);
+    };
+    const bySymbol = new Map();
+    for (const edge of calls.edges) {
+        if (!bindsToTheExportedSymbol(edge.symbol, edge.to))
+            continue;
+        const list = bySymbol.get(edge.symbol);
+        const site = {
+            path: edge.from,
+            line: edge.line ?? 0,
+            symbol: edge.symbol,
+            // The calling function, not a line of source. A blast radius consumer
+            // needs to know WHERE in the file; it does not need the code, and
+            // shipping the code is what the privacy boundary exists to prevent.
+            context: edge.enclosing ? `${edge.enclosing}()` : "",
+        };
+        if (list)
+            list.push(site);
+        else
+            bySymbol.set(edge.symbol, [site]);
+    }
+    const referencesBySymbol = new Map();
+    for (const edge of references.edges) {
+        if (!bindsToTheExportedSymbol(edge.symbol, edge.to))
+            continue;
+        const site = {
+            path: edge.from,
+            line: edge.line ?? 0,
+            symbol: edge.symbol,
+            kind: edge.kind,
+            context: edge.enclosing ? `${edge.enclosing}()` : "",
+        };
+        const list = referencesBySymbol.get(edge.symbol);
+        if (list)
+            list.push(site);
+        else
+            referencesBySymbol.set(edge.symbol, [site]);
+    }
+    return {
+        sitesFor(symbol) {
+            // A declared interface may be written "Class.method"; the graph keys on
+            // the member name, which is the last segment.
+            const last = symbol.split(".").pop() ?? symbol;
+            return bySymbol.get(last) ?? [];
+        },
+        referencesFor(symbol) {
+            const last = symbol.split(".").pop() ?? symbol;
+            return referencesBySymbol.get(last) ?? [];
+        },
+        coverage: index.coverage,
+        blindSpots: index.blindSpots.length,
+        unresolvedCalls: calls.unresolved.length,
+        unresolvedReferences: references.unresolved.length,
+        analyzer: `keel-graph-v1(${registry.signature()})`,
+    };
+}