toolroll 0.5.0

package/dist/repos.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Which repositories the operator has actually committed to.
+ *
+ * Discovery is total and costs nothing, so it stays the way you find things.
+ * Enrollment is the smaller, deliberate list: what gets reported by default,
+ * and later what may be written to. Keeping the two separate is what lets the
+ * first run need no configuration while the tenth run stays quiet.
+ *
+ * The file is plain JSON in a conventional location because someone will want
+ * to edit it by hand or check it into their dotfiles — which also means it is
+ * untrusted input and gets validated like any other.
+ */
+export declare const CONFIG_VERSION = 2;
+export type ProjectRegistry = {
+    repos: string[];
+    roots: string[];
+};
+export type LoadResult = {
+    repos: string[];
+} | {
+    error: string;
+};
+export type RegistryLoadResult = ProjectRegistry | {
+    error: string;
+};
+type RegistryUpdateFailure = {
+    ok: false;
+    reason: "locked" | "registry" | "abandoned";
+    message: string;
+};
+export declare function configPath(env: Record<string, string | undefined>, home: string): string;
+export declare function loadProjectRegistry(file: string): Promise<RegistryLoadResult>;
+/** Compatibility view for reports, CLI enrollment, and the MCP surface. */
+export declare function loadRepos(file: string): Promise<LoadResult>;
+export declare function saveRepos(file: string, repos: readonly string[]): Promise<void>;
+/**
+ * The ONE locked registry update (onboarding findings 9/17/19/25/29/30):
+ * every writer — CLI add/remove, the console, up's enrollment — goes
+ * through here. The lock is an exclusive-create file whose body carries
+ * {pid, token, at}; a LIVE owner's lock is never touched; stale recovery
+ * runs only after kill(pid, 0) proves the owner dead, serialized through
+ * a second exclusive reaper lock that re-reads the exact snapshot it
+ * observed before unlinking. The owner releases only while its hold is
+ * under 25s — past that it abandons WITHOUT unlinking and reports so; the
+ * deadline is checked BEFORE publication, so a committed rename is never
+ * reported as failed. Reads: only ENOENT means an empty registry —
+ * malformed JSON, wrong shape, EACCES, and I/O errors REFUSE.
+ */
+export declare function updateRepos(file: string, transform: (repos: string[]) => string[]): Promise<{
+    ok: true;
+    repos: string[];
+} | RegistryUpdateFailure>;
+/** Persist project roots through the same lock as repo enrollment. */
+export declare function updateProjectRoots(file: string, transform: (roots: string[]) => string[]): Promise<{
+    ok: true;
+    roots: string[];
+} | RegistryUpdateFailure>;
+/** Atomically update repositories and roots without either writer erasing the other. */
+export declare function updateProjectRegistry(file: string, transform: (registry: ProjectRegistry) => ProjectRegistry): Promise<{
+    ok: true;
+    registry: ProjectRegistry;
+} | RegistryUpdateFailure>;
+export declare function addRepos(existing: readonly string[], incoming: readonly string[]): string[];
+export declare function removeRepos(existing: readonly string[], targets: readonly string[]): string[];
+export {};

package/dist/repos.js

@@ -0,0 +1,277 @@
+/**
+ * Which repositories the operator has actually committed to.
+ *
+ * Discovery is total and costs nothing, so it stays the way you find things.
+ * Enrollment is the smaller, deliberate list: what gets reported by default,
+ * and later what may be written to. Keeping the two separate is what lets the
+ * first run need no configuration while the tenth run stays quiet.
+ *
+ * The file is plain JSON in a conventional location because someone will want
+ * to edit it by hand or check it into their dotfiles — which also means it is
+ * untrusted input and gets validated like any other.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { configBase, namedPath } from "./names.js";
+export const CONFIG_VERSION = 2;
+const FILE_NAME = "repos.json";
+export function configPath(env, home) {
+    // Rename continuity: an enrolled list under an older name keeps working
+    // until one exists under the new one.
+    return namedPath(configBase(env, home), [FILE_NAME]);
+}
+export async function loadProjectRegistry(file) {
+    let text;
+    try {
+        text = await readFile(file, "utf8");
+    }
+    catch (cause) {
+        // ONLY the missing file is the ordinary first-run state (round-3
+        // finding 6): a permission or I/O failure is an unreadable registry,
+        // never an empty one — the MCP gateway fails closed on it.
+        if (cause.code === "ENOENT")
+            return { repos: [], roots: [] };
+        return { error: `${file} could not be read (${String(cause.message)})` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { error: `${file} is not valid JSON — fix or delete it` };
+    }
+    const registry = readProjectRegistry(parsed);
+    if (registry === null) {
+        return { error: `${file} does not look like a Toolroll config — fix or delete it` };
+    }
+    return { repos: sortUnique(registry.repos), roots: sortUnique(registry.roots) };
+}
+/** Compatibility view for reports, CLI enrollment, and the MCP surface. */
+export async function loadRepos(file) {
+    const loaded = await loadProjectRegistry(file);
+    return "error" in loaded ? loaded : { repos: loaded.repos };
+}
+export async function saveRepos(file, repos) {
+    await mkdir(dirname(file), { recursive: true });
+    const config = { version: CONFIG_VERSION, repos: sortUnique(repos), roots: [] };
+    await writeFile(file, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+/**
+ * The ONE locked registry update (onboarding findings 9/17/19/25/29/30):
+ * every writer — CLI add/remove, the console, up's enrollment — goes
+ * through here. The lock is an exclusive-create file whose body carries
+ * {pid, token, at}; a LIVE owner's lock is never touched; stale recovery
+ * runs only after kill(pid, 0) proves the owner dead, serialized through
+ * a second exclusive reaper lock that re-reads the exact snapshot it
+ * observed before unlinking. The owner releases only while its hold is
+ * under 25s — past that it abandons WITHOUT unlinking and reports so; the
+ * deadline is checked BEFORE publication, so a committed rename is never
+ * reported as failed. Reads: only ENOENT means an empty registry —
+ * malformed JSON, wrong shape, EACCES, and I/O errors REFUSE.
+ */
+export async function updateRepos(file, transform) {
+    const updated = await updateProjectRegistry(file, current => ({
+        ...current,
+        repos: transform(current.repos),
+    }));
+    return updated.ok ? { ok: true, repos: updated.registry.repos } : updated;
+}
+/** Persist project roots through the same lock as repo enrollment. */
+export async function updateProjectRoots(file, transform) {
+    const updated = await updateProjectRegistry(file, current => ({
+        ...current,
+        roots: transform(current.roots),
+    }));
+    return updated.ok ? { ok: true, roots: updated.registry.roots } : updated;
+}
+/** Atomically update repositories and roots without either writer erasing the other. */
+export async function updateProjectRegistry(file, transform) {
+    const { openSync, closeSync, writeSync, readFileSync, unlinkSync, existsSync: exists, mkdirSync, renameSync } = await import("node:fs");
+    const { randomBytes } = await import("node:crypto");
+    mkdirSync(dirname(file), { recursive: true });
+    const lockPath = `${file}.lock`;
+    const reaperPath = `${file}.reaper.lock`;
+    const token = randomBytes(16).toString("hex");
+    const body = JSON.stringify({ pid: process.pid, token, at: Date.now() });
+    const sleep = (ms) => new Promise(done => setTimeout(done, ms));
+    const tryReap = () => {
+        // Recovery only for PROVEN-dead owners, serialized by the reaper lock,
+        // which re-reads the exact snapshot before unlinking (finding 29). An
+        // orphaned reaper lock is itself reaped by the same dead-pid rule.
+        let snapshot = null;
+        try {
+            snapshot = JSON.parse(readFileSync(lockPath, "utf8"));
+        }
+        catch {
+            return;
+        }
+        if (typeof snapshot?.pid !== "number")
+            return;
+        try {
+            process.kill(snapshot.pid, 0);
+            return; // alive: never touched
+        }
+        catch {
+            // ESRCH — dead; continue under the reaper lock
+        }
+        try {
+            const before = readFileSync(reaperPath, "utf8");
+            const parsed = JSON.parse(before);
+            if (typeof parsed?.pid === "number") {
+                try {
+                    process.kill(parsed.pid, 0);
+                    return; // a live reaper is working
+                }
+                catch {
+                    try {
+                        unlinkSync(reaperPath);
+                    }
+                    catch { /* raced */ }
+                }
+            }
+        }
+        catch {
+            // no reaper lock — proceed to claim it
+        }
+        let reaperFd;
+        try {
+            reaperFd = openSync(reaperPath, "wx");
+        }
+        catch {
+            return; // another reaper won
+        }
+        try {
+            writeSync(reaperFd, JSON.stringify({ pid: process.pid }));
+            // Re-read and require the EXACT observed snapshot + a repeated
+            // dead-pid proof before unlinking (finding 29).
+            const now = readFileSync(lockPath, "utf8");
+            const again = JSON.parse(now);
+            if (again?.pid === snapshot.pid && again?.token === snapshot.token) {
+                try {
+                    process.kill(snapshot.pid, 0);
+                }
+                catch {
+                    try {
+                        unlinkSync(lockPath);
+                    }
+                    catch { /* raced */ }
+                }
+            }
+        }
+        catch {
+            // lock vanished or changed — nothing to do
+        }
+        finally {
+            closeSync(reaperFd);
+            try {
+                unlinkSync(reaperPath);
+            }
+            catch { /* already gone */ }
+        }
+    };
+    let held = false;
+    const acquiredAt = () => Date.now() - start;
+    let start = 0;
+    for (let attempt = 0; attempt < 6 && !held; attempt += 1) {
+        try {
+            const fd = openSync(lockPath, "wx");
+            writeSync(fd, body);
+            closeSync(fd);
+            held = true;
+            start = Date.now();
+        }
+        catch {
+            tryReap();
+            await sleep(100);
+        }
+    }
+    if (!held)
+        return { ok: false, reason: "locked", message: `${file} is busy — another enrollment holds its lock; try again` };
+    try {
+        let current;
+        if (!exists(file)) {
+            current = { repos: [], roots: [] }; // ONLY the missing-file case is an empty registry
+        }
+        else {
+            let text;
+            try {
+                text = readFileSync(file, "utf8");
+            }
+            catch (error) {
+                return { ok: false, reason: "registry", message: `${file} could not be read (${String(error.message)}) — refusing to replace it` };
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                return { ok: false, reason: "registry", message: `${file} is not valid JSON — fix or delete it; refusing to replace it` };
+            }
+            const registry = readProjectRegistryStrict(parsed);
+            if (registry === null) {
+                return { ok: false, reason: "registry", message: `${file} does not look like a Toolroll config — refusing to replace it` };
+            }
+            current = registry;
+        }
+        const transformed = transform({ repos: [...current.repos], roots: [...current.roots] });
+        const next = { repos: sortUnique(transformed.repos), roots: sortUnique(transformed.roots) };
+        // Deadline BEFORE publication (finding 30): a rename past the hold
+        // window would commit while the lock may already be reaped.
+        if (acquiredAt() > 20_000) {
+            held = false; // abandon: no unlink, no publication
+            return { ok: false, reason: "abandoned", message: "the registry lock aged out before the update could publish — nothing changed; try again" };
+        }
+        const temp = `${file}.${process.pid}.${token.slice(0, 8)}.tmp`;
+        const fd = openSync(temp, "wx");
+        writeSync(fd, `${JSON.stringify({ version: CONFIG_VERSION, ...next }, null, 2)}
+`);
+        closeSync(fd);
+        renameSync(temp, file);
+        return { ok: true, registry: next };
+    }
+    finally {
+        if (held && acquiredAt() < 25_000) {
+            try {
+                unlinkSync(lockPath);
+            }
+            catch { /* reaped despite liveness rules */ }
+        }
+    }
+}
+/** Strict shape for the locked path (finding 36): non-string entries REFUSE. */
+function readProjectRegistryStrict(parsed) {
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const { repos, roots } = parsed;
+    if (!Array.isArray(repos))
+        return null;
+    if (!repos.every((repo) => typeof repo === "string"))
+        return null;
+    if (roots !== undefined && (!Array.isArray(roots) || !roots.every((root) => typeof root === "string")))
+        return null;
+    return { repos, roots: roots ?? [] };
+}
+export function addRepos(existing, incoming) {
+    return sortUnique([...existing, ...incoming]);
+}
+export function removeRepos(existing, targets) {
+    const unwanted = new Set(targets);
+    return existing.filter(repo => !unwanted.has(repo));
+}
+/** null when the shape is wrong; non-string entries are dropped, not trusted. */
+function readProjectRegistry(parsed) {
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const { repos, roots } = parsed;
+    if (!Array.isArray(repos))
+        return null;
+    if (roots !== undefined && !Array.isArray(roots))
+        return null;
+    return {
+        repos: repos.filter((repo) => typeof repo === "string"),
+        roots: (roots ?? []).filter((root) => typeof root === "string"),
+    };
+}
+function sortUnique(repos) {
+    return [...new Set(repos)].sort();
+}

package/dist/repository-context-ui.d.ts

@@ -0,0 +1,2 @@
+import type { RepositoryContext } from './repository-context.js';
+export declare function repositoryContextHtml(repo: string, query: string, result: RepositoryContext | null, csrf: string): string;

package/dist/repository-context-ui.js

@@ -0,0 +1,10 @@
+const escape = (value) => value.replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char]);
+export function repositoryContextHtml(repo, query, result, csrf) {
+    const root = `/settings/knowledge?repo=${encodeURIComponent(repo)}`;
+    return `<section class="knowledge repository-context"><h2>Relevant code</h2><form method="get" action="/settings/knowledge"><input type="hidden" name="repo" value="${escape(repo)}"><label>Find code<input name="q" value="${escape(query)}" maxlength="1000" placeholder="A feature, file or symbol"></label><button type="submit">Search</button></form>` +
+        (result === null ? '' : `<p class="meta">${result.index.engine === 'typescript-ast' ? 'Code relationships' : 'Source search'}${result.mode === 'impact' ? ' · possible change impact' : ''}</p>` +
+            (result.excerpts.length ? result.excerpts.map(one => `<details><summary>${escape(one.file)}:${one.line}${one.symbol ? ` · ${escape(one.symbol)}` : ''}</summary><p class="meta">${escape(one.reason)}</p><pre>${escape(one.text)}</pre><a href="${root}&mode=impact&q=${encodeURIComponent(one.file)}">What this may affect</a></details>`).join('') : '<p>No matching source was found in this bounded search.</p>') +
+            (result.relationships.length ? `<details><summary>Related files</summary><ul>${result.relationships.map(one => `<li>${escape(one.from)} → ${escape(one.to)} · ${escape(one.kind)}</li>`).join('')}</ul></details>` : '') +
+            `<details><summary>Context details</summary><p>${escape(result.index.status)}${result.checkout ? ` · checkout ${escape(result.checkout.head.slice(0, 8))}` : ''}</p>${result.warnings.map(one => `<p>${escape(one)}</p>`).join('')}</details>`) +
+        (csrf ? `<details><summary>Refresh code index</summary><form method="post" action="/settings/knowledge/refresh"><input type="hidden" name="csrf" value="${escape(csrf)}"><input type="hidden" name="repo" value="${escape(repo)}"><p>Builds a local map of TypeScript and JavaScript imports. Uses no model.</p><button type="submit">Refresh index</button></form></details>` : '') + `</section>`;
+}

package/dist/repository-context.d.ts

@@ -0,0 +1,67 @@
+export type RepositoryContextRequest = {
+    repo: string;
+    query: string;
+    mode?: 'search' | 'impact';
+    audience?: 'lead' | 'crew';
+    /** Canonical admitted project when repo is a crew worktree. Must share its Git common directory. */
+    project?: string;
+    baseRevision?: string;
+    cacheRoot?: string;
+    refresh?: boolean;
+    maxBytes?: number;
+};
+export type RepositoryCheckout = {
+    repo: string;
+    gitDir: string;
+    head: string;
+    baseRevision: string;
+    sourceHash: string;
+    source: 'working-tree';
+};
+export type RepositoryRelationship = {
+    from: string;
+    to: string;
+    kind: 'imports' | 're-exports' | 'dynamic-import';
+    file: string;
+    line: number;
+    provenance: 'explicit';
+};
+export type RepositoryExcerpt = {
+    file: string;
+    line: number;
+    endLine: number;
+    sha256: string;
+    text: string;
+    reason: string;
+    symbol: string | null;
+};
+export type RepositoryContext = {
+    version: 1;
+    readOnly: boolean;
+    query: string;
+    mode: 'search' | 'impact';
+    asOf: string;
+    checkout: RepositoryCheckout | null;
+    index: {
+        engine: 'typescript-ast' | 'text-search';
+        status: 'ready' | 'missing' | 'stale' | 'unavailable';
+        generation: string | null;
+        extractor: string | null;
+    };
+    excerpts: RepositoryExcerpt[];
+    relationships: RepositoryRelationship[];
+    omissions: {
+        files: number;
+        excerpts: number;
+        relationships: number;
+        sourceBytes: number;
+    };
+    warnings: string[];
+};
+/** Synchronous, read-only capture for DB transaction and provider-admission callers.
+ * Call once and persist the returned selection; resume uses that capture, never fresh source. */
+export declare function repositoryContextRead(request: Omit<RepositoryContextRequest, 'refresh'>): RepositoryContext;
+/** Explicit refresh is the only cache-writing path. It never changes project/task records. */
+export declare function repositoryContext(request: RepositoryContextRequest): Promise<RepositoryContext>;
+/** Human/model context rendering; saved records remain the authority and retain this structured capture. */
+export declare function repositoryContextText(context: RepositoryContext): string;