toolroll 0.9.92 → 0.9.94

package/dist/remote-destination.js

@@ -0,0 +1,217 @@
+/**
+ * Where a read of a recorded remote really connects, worked out and pinned before git runs (docs/plans/code-map.md §1).
+ * remote-main.ts's URL rules look at a host's spelling; a name can still resolve to this machine. Here the name is
+ * resolved once, every address is checked, and git is told to use exactly the checked address. Routing is decided from
+ * the same environment git gets. Anything that can't be decided or pinned refuses with a reason: there is no fallback to
+ * an unpinned read.
+ */
+import { lookup as dnsLookup } from "node:dns/promises";
+import { isIP } from "node:net";
+export const lookupAll = async (host) => (await dnsLookup(host, { all: true, verbatim: true })).map(one => one.address);
+const UNDECIDED = "Toolroll can't tell how this connection would be routed";
+const NOT_ALLOWED = "its address isn't one Toolroll connects to";
+/** The eight 16-bit groups of an IPv6 address; null when it isn't one. */
+function hextets(address) {
+    let text = address.toLowerCase().replace(/%.*$/, "");
+    const dotted = /(\d+\.\d+\.\d+\.\d+)$/.exec(text);
+    if (dotted !== null) {
+        const parts = dotted[1].split(".").map(Number);
+        if (parts.some(part => part > 255))
+            return null;
+        text = `${text.slice(0, dotted.index)}${((parts[0] << 8) | parts[1]).toString(16)}:${((parts[2] << 8) | parts[3]).toString(16)}`;
+    }
+    const halves = text.split("::");
+    if (halves.length > 2)
+        return null;
+    const left = halves[0] === "" ? [] : halves[0].split(":");
+    const right = halves.length === 1 || halves[1] === "" ? [] : halves[1].split(":");
+    const gap = 8 - left.length - right.length;
+    if (halves.length === 1 ? gap !== 0 : gap < 1)
+        return null;
+    const groups = [...left, ...Array(halves.length === 1 ? 0 : gap).fill("0"), ...right].map(one => parseInt(one, 16));
+    return groups.length === 8 && groups.every(one => Number.isInteger(one) && one >= 0 && one <= 0xffff) ? groups : null;
+}
+const refusedV4 = (address) => {
+    const [a, b] = address.split(".").map(Number);
+    return a === 127 || a === 0 || (a === 169 && b === 254);
+};
+const v4Of = (high, low) => `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`;
+/** Whether an address is loopback, unspecified, link-local, or an IPv4-mapped or NAT64 form of these. */
+export function addressRefused(address) {
+    const family = isIP(address);
+    if (family === 4)
+        return refusedV4(address);
+    if (family !== 6)
+        return true;
+    const g = hextets(address);
+    if (g === null)
+        return true;
+    const top = g.slice(0, 5).every(one => one === 0);
+    if (top && g[5] === 0 && g[6] === 0 && (g[7] === 0 || g[7] === 1))
+        return true; // :: and ::1
+    if ((g[0] & 0xffc0) === 0xfe80)
+        return true; // fe80::/10
+    if (top && g[5] === 0xffff)
+        return refusedV4(v4Of(g[6], g[7])); // ::ffff:a.b.c.d
+    if (top && g[5] === 0)
+        return refusedV4(v4Of(g[6], g[7])); // ::a.b.c.d (deprecated compatible form)
+    if (g[0] === 0x64 && g[1] === 0xff9b && g.slice(2, 6).every(one => one === 0))
+        return refusedV4(v4Of(g[6], g[7])); // 64:ff9b::/96
+    return false;
+}
+/** The host, effective port and scheme a recorded URL connects to; null when it can't be read. The caller has already
+ * passed remoteUrlProblem. Node's URL parser normalizes every spelling of a literal host. */
+export function destinationOf(url) {
+    const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):\/\//.exec(url)?.[1]?.toLowerCase();
+    let host, port;
+    if (scheme === "https" || scheme === "ssh") {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            return null;
+        }
+        host = parsed.hostname.replace(/^\[(.*)\]$/, "$1");
+        port = parsed.port === "" ? (scheme === "https" ? 443 : 22) : Number(parsed.port);
+        return validDestination(scheme, host, port);
+    }
+    if (scheme !== undefined)
+        return null;
+    const colon = url.indexOf(":");
+    if (colon <= 0)
+        return null;
+    host = url.slice(0, colon).replace(/^.*@/, "");
+    return validDestination("ssh", host, 22);
+}
+function validDestination(scheme, host, port) {
+    const literal = isIP(host) !== 0;
+    if (!literal && !/^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?\.?$/.test(host))
+        return null;
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return null;
+    return { scheme, host, port, literal };
+}
+async function checkedAddress(host, literal, lookup) {
+    if (literal)
+        return addressRefused(host) ? { ok: false, why: NOT_ALLOWED } : { ok: true, address: host };
+    let found;
+    try {
+        found = await lookup(host);
+    }
+    catch {
+        return { ok: false, why: "its host name couldn't be resolved" };
+    }
+    if (found.length === 0)
+        return { ok: false, why: "its host name couldn't be resolved" };
+    // Every address, not just the first: a name that also answers with this machine isn't connected to.
+    if (found.some(addressRefused))
+        return { ok: false, why: NOT_ALLOWED };
+    return { ok: true, address: found[0] };
+}
+const curlPin = (host, port, address) => ["-c", `http.curloptResolve=${host}:${port}:${isIP(address) === 6 ? `[${address}]` : address}`];
+/** One NO_PROXY entry against a host, as curl compares them; "unknown" for anything Toolroll won't second-guess. */
+function noProxyMatch(entry, host) {
+    const raw = entry.replace(/^\[(.*)\]$/, "$1");
+    if (raw === "*")
+        return true;
+    const hostIp = isIP(host);
+    const cidr = /^(.+)\/(\d+)$/.exec(raw);
+    if (cidr !== null) {
+        if (isIP(cidr[1]) === 0)
+            return "unknown";
+        if (hostIp === 0)
+            return false;
+        if (hostIp !== isIP(cidr[1]))
+            return false;
+        const bits = Number(cidr[2]);
+        if (hostIp === 4) {
+            if (bits > 32)
+                return "unknown";
+            const value = (ip) => ip.split(".").reduce((n, part) => n * 256 + Number(part), 0);
+            const size = 2 ** (32 - bits);
+            return Math.floor(value(host) / size) === Math.floor(value(cidr[1]) / size);
+        }
+        return "unknown";
+    }
+    if (isIP(raw) !== 0)
+        return hostIp !== 0 && (hextets(raw)?.join() ?? raw) === (hextets(host)?.join() ?? host);
+    if (/[^A-Za-z0-9.-]/.test(raw))
+        return "unknown";
+    if (hostIp !== 0)
+        return false;
+    const name = raw.replace(/^\.+/, "").replace(/\.+$/, "").toLowerCase();
+    const wanted = host.replace(/\.+$/, "").toLowerCase();
+    return name !== "" && (wanted === name || wanted.endsWith(`.${name}`));
+}
+/** Whether curl would skip the proxy for this host; "unknown" when an entry can't be decided. */
+export function noProxyApplies(noProxy, host) {
+    let unknown = false;
+    for (const entry of noProxy.split(/[,\s]+/).filter(Boolean)) {
+        const hit = noProxyMatch(entry, host);
+        if (hit === true)
+            return true;
+        if (hit === "unknown")
+            unknown = true;
+    }
+    return unknown ? "unknown" : false;
+}
+const envOf = (env, lower, upper) => {
+    const low = env[lower];
+    return low !== undefined && low !== "" ? low : env[upper] ?? "";
+};
+/** The proxy curl would use from `https_proxy`/`HTTPS_PROXY`: http or https schemes only (a SOCKS proxy resolves names
+ * on its side, in ways this can't see). */
+function proxyOf(value) {
+    const text = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(value) ? value : `http://${value}`;
+    let parsed;
+    try {
+        parsed = new URL(text);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        return null;
+    const host = parsed.hostname.replace(/^\[(.*)\]$/, "$1");
+    const port = parsed.port === "" ? (parsed.protocol === "https:" ? 443 : 1080) : Number(parsed.port);
+    const literal = isIP(host) !== 0;
+    if (host === "" || (!literal && !/^[A-Za-z0-9.-]+$/.test(host)))
+        return null;
+    return { host, port, literal };
+}
+/**
+ * Decide the route and pin it. `env` is what git will see (the names remote-main.ts's ENV_ALLOWLIST passes). ssh never
+ * uses a proxy. Through a proxy, the proxy's own address is checked and pinned; the operator's proxy then chooses the
+ * final destination, and the caller says so.
+ */
+export async function pinDestination(url, env, lookup = lookupAll) {
+    const target = destinationOf(url);
+    if (target === null)
+        return { ok: false, why: UNDECIDED };
+    if (target.scheme === "ssh") {
+        const checked = await checkedAddress(target.host, target.literal, lookup);
+        if (!checked.ok)
+            return checked;
+        return { ok: true, pin: { gitArgs: [], proxy: null, env: { GIT_SSH_COMMAND: `ssh -o BatchMode=yes -o ProxyCommand=none -o ProxyJump=none -o HostName=${checked.address} -o Port=${target.port} -o HostKeyAlias=${target.host} -o CheckHostIP=no` } } };
+    }
+    const proxyValue = envOf(env, "https_proxy", "HTTPS_PROXY");
+    if (proxyValue !== "") {
+        const skip = noProxyApplies(envOf(env, "no_proxy", "NO_PROXY"), target.host);
+        if (skip === "unknown")
+            return { ok: false, why: UNDECIDED };
+        if (!skip) {
+            const proxy = proxyOf(proxyValue);
+            if (proxy === null)
+                return { ok: false, why: UNDECIDED };
+            const checked = await checkedAddress(proxy.host, proxy.literal, lookup);
+            if (!checked.ok)
+                return { ok: false, why: `your proxy's ${checked.why.replace(/^its /, "")}` };
+            return { ok: true, pin: { gitArgs: curlPin(proxy.host, proxy.port, checked.address), env: {}, proxy: proxy.host } };
+        }
+    }
+    const checked = await checkedAddress(target.host, target.literal, lookup);
+    if (!checked.ok)
+        return checked;
+    return { ok: true, pin: { gitArgs: curlPin(target.host, target.port, checked.address), env: {}, proxy: null } };
+}

package/dist/remote-main.d.ts

@@ -1,4 +1,6 @@
 import { type ExecResult } from "./exec.js";
+import type { BoundedOptions, BoundedResult, BoundedRunner } from "./bounded-spawn.js";
+import type { Pin } from "./remote-destination.js";
 import type { Store } from "./store.js";
 import type { Runner } from "./worktree.js";
 /** What the private directory's git may see of this process's environment: nothing that names a repository, an
@@ -40,7 +42,13 @@ export type RemoteMainRead = {
 } | {
     ok: false;
     why: string;
+    reason?: "moved";
 };
+/** What every reader of a remote main shows when its address redirects. The target is remote-supplied text: it is never
+ * shown, stored or followed, and the new remote is never adopted automatically. */
+export declare const REMOTE_MOVED = "The repository moved: its address now redirects. Update the project's remote in Toolroll (Settings \u2192 Projects), then try again.";
+/** git's words for a refused redirect (http.followRedirects=false), read for the status code alone. */
+export declare function redirected(stderr: string): boolean;
 /**
  * One pass's reads of recorded remotes. Every `read` fetches again (the pre-teardown re-check is never older than
  * the teardown); a project's private directory lasts until `close`, so a fetch after the first only brings what
@@ -61,3 +69,43 @@ export declare class RemoteMains {
     read(repo: string): Promise<RemoteMainRead>;
     close(): void;
 }
+export declare const MAP_FETCH_LIMITS: {
+    readonly timeoutMs: 120000;
+    readonly memoryBytes: number;
+    readonly diskBytes: number;
+    readonly fileBytes: number;
+    readonly maxStderr: number;
+};
+export type MapGitOptions = {
+    helper?: string;
+    extra?: readonly string[];
+};
+/** Git in a private directory under the map's rules: the same hardening as `RemoteMains`, plus the pin. */
+export declare function mapGitArgs(dir: string, pin: Pin, args: readonly string[], options?: MapGitOptions): string[];
+/** The environment for it: exactly the allowed names, the fixed settings, and the pin's. */
+export declare function mapGitEnv(pin: Pin, from?: Readonly<Record<string, string | undefined>>): Record<string, string>;
+export declare function initPrivateDir(dir: string, bounded: BoundedRunner): Promise<BoundedResult>;
+export type MapPeek = {
+    ok: true;
+    commit: string | null;
+} | {
+    ok: false;
+    why: string;
+    reason?: "moved";
+};
+/** The commit the recorded remote's main is at, without fetching: null when the remote has no `main`. */
+export declare function peekMain(url: string, dir: string, pin: Pin, bounded: BoundedRunner, helper?: string): Promise<MapPeek>;
+/** A depth-1 private folder is clean when it holds only what the fetch made: a `shallow` file naming exactly the fetched
+ * commit, and no grafts or alternates. */
+export declare function shallowClean(dir: string, commit: string): boolean;
+export type MapFetch = {
+    ok: true;
+    commit: string;
+    enforced: "system" | "checked";
+} | {
+    ok: false;
+    why: string;
+    reason?: "moved";
+};
+/** Fetch main at depth 1 into `dir`, under the map's limits. `onStart` records the spawn for crash cleanup. */
+export declare function readShallowMain(url: string, dir: string, pin: Pin, bounded: BoundedRunner, onStart?: BoundedOptions["onStart"], helper?: string): Promise<MapFetch>;

package/dist/remote-main.js

@@ -13,7 +13,7 @@
  * Every doubt fails closed: no recorded remote, a URL that isn't allowed, a failed fetch or a remote without main all
  * read as "not proven", and the task stays for a person.
  */
-import { mkdirSync, mkdtempSync, rmSync, existsSync } from "node:fs";
+import { lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, existsSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { run } from "./exec.js";
 /** The ref a fetched remote main is kept under, inside the private directory only. */
@@ -35,7 +35,9 @@ export const CREDENTIAL_HELPER = process.platform === "darwin" ? "osxkeychain" :
 function hardened(helper, file = "never") {
     return ["-c", "core.hooksPath=/dev/null", "-c", "protocol.allow=never", "-c", "protocol.https.allow=always", "-c", "protocol.ssh.allow=always",
         "-c", `protocol.file.allow=${file}`, "-c", "protocol.ext.allow=never", "-c", "credential.helper=", ...(helper === "" ? [] : ["-c", `credential.helper=${helper}`]),
-        "-c", "gc.auto=0", "-c", "maintenance.auto=false", "-c", "fetch.recurseSubmodules=false", "-c", "core.fsmonitor=false"];
+        "-c", "gc.auto=0", "-c", "maintenance.auto=false", "-c", "fetch.recurseSubmodules=false", "-c", "core.fsmonitor=false",
+        // Never to an address the recorded URL doesn't name: a moved repository is a person's choice to record (MOVED).
+        "-c", "http.followRedirects=false"];
 }
 /**
  * A URL Toolroll may fetch remote main from: https or ssh (either form). Local paths, file URLs and loopback hosts
@@ -96,6 +98,14 @@ export function remoteUrlProblem(url) {
     const parsed = parseRemoteUrl(url);
     return "why" in parsed ? parsed.why : null;
 }
+/** What every reader of a remote main shows when its address redirects. The target is remote-supplied text: it is never
+ * shown, stored or followed, and the new remote is never adopted automatically. */
+export const REMOTE_MOVED = "The repository moved: its address now redirects. Update the project's remote in Toolroll (Settings → Projects), then try again.";
+/** git's words for a refused redirect (http.followRedirects=false), read for the status code alone. */
+export function redirected(stderr) {
+    return /returned error: 30[12378]\b/.test(stderr);
+}
+const UNREAD = "Toolroll couldn't read the project's remote main";
 /**
  * One pass's reads of recorded remotes. Every `read` fetches again (the pre-teardown re-check is never older than
  * the teardown); a project's private directory lasts until `close`, so a fetch after the first only brings what
@@ -145,14 +155,16 @@ export class RemoteMains {
             return { ok: false, why: problem };
         const dir = await this.dirFor(repo);
         if (dir === null)
-            return { ok: false, why: "Toolroll couldn't read the project's remote main" };
+            return { ok: false, why: UNREAD };
         const fetched = await this.exec(dir, ["fetch", "--quiet", "--no-tags", "--no-write-fetch-head", "--", url, `+refs/heads/main:${REMOTE_MAIN}`]);
+        if (fetched.code !== 0 && redirected(fetched.stderr))
+            return { ok: false, why: REMOTE_MOVED, reason: "moved" };
         if (fetched.code !== 0 || !this.clean(dir))
-            return { ok: false, why: "Toolroll couldn't read the project's remote main" };
+            return { ok: false, why: UNREAD };
         const resolved = await this.exec(dir, ["rev-parse", "--verify", "--quiet", `${REMOTE_MAIN}^{commit}`]);
         const main = resolved.stdout.trim();
         if (resolved.code !== 0 || !SHA.test(main))
-            return { ok: false, why: "Toolroll couldn't read the project's remote main" };
+            return { ok: false, why: UNREAD };
         const git = args => this.exec(dir, args);
         const bring = async (from, head) => {
             if (!SHA.test(head))
@@ -177,3 +189,70 @@ export class RemoteMains {
         this.dirs.clear();
     }
 }
+// ---- the code map's own read: pinned, depth 1, bounded (docs/plans/code-map.md §1) ---------------------------------
+const MAP_MAIN = "refs/toolroll/map-main";
+/** What keeps git's own memory down. index-pack still materializes delta bases, so these reduce; they don't bound. */
+const LOW_MEMORY = ["-c", "pack.threads=1", "-c", "core.deltaBaseCacheLimit=32m", "-c", "core.bigFileThreshold=1m"];
+export const MAP_FETCH_LIMITS = { timeoutMs: 120_000, memoryBytes: 1024 ** 3, diskBytes: 1024 ** 3, fileBytes: 512 * 1024 ** 2, maxStderr: 64 * 1024 };
+/** Git in a private directory under the map's rules: the same hardening as `RemoteMains`, plus the pin. */
+export function mapGitArgs(dir, pin, args, options = {}) {
+    return ["--git-dir", dir, ...hardened(options.helper ?? CREDENTIAL_HELPER), ...pin.gitArgs, ...(options.extra ?? []), ...args];
+}
+/** The environment for it: exactly the allowed names, the fixed settings, and the pin's. */
+export function mapGitEnv(pin, from = process.env) {
+    const env = {};
+    for (const name of ENV_ALLOWLIST) {
+        const value = from[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    return { ...env, ...ENV, ...pin.env };
+}
+export function initPrivateDir(dir, bounded) {
+    return bounded("git", ["init", "--quiet", "--bare", "--template=", dir], { cwd: dir, env: mapGitEnv({ gitArgs: [], env: {}, proxy: null }), timeoutMs: 30_000, maxStdout: 4096, maxStderr: 4096, label: "code-map-init" });
+}
+/** The commit the recorded remote's main is at, without fetching: null when the remote has no `main`. */
+export async function peekMain(url, dir, pin, bounded, helper) {
+    const ran = await bounded("git", mapGitArgs(dir, pin, ["ls-remote", "--", url, "refs/heads/main"], helper === undefined ? {} : { helper }), { cwd: dir, env: mapGitEnv(pin), timeoutMs: 30_000, maxStdout: 64 * 1024, maxStderr: MAP_FETCH_LIMITS.maxStderr, label: "code-map-peek" });
+    if (ran.code !== 0 && redirected(ran.stderr))
+        return { ok: false, why: REMOTE_MOVED, reason: "moved" };
+    if (ran.code !== 0 || ran.killed !== null)
+        return { ok: false, why: UNREAD };
+    const line = ran.stdout.toString("utf8").split("\n").find(one => one.endsWith("\trefs/heads/main"));
+    if (line === undefined)
+        return ran.stdout.length === 0 ? { ok: true, commit: null } : { ok: false, why: UNREAD };
+    const commit = line.slice(0, line.indexOf("\t"));
+    return SHA.test(commit) ? { ok: true, commit } : { ok: false, why: UNREAD };
+}
+/** A depth-1 private folder is clean when it holds only what the fetch made: a `shallow` file naming exactly the fetched
+ * commit, and no grafts or alternates. */
+export function shallowClean(dir, commit) {
+    if ([join("info", "grafts"), join("objects", "info", "alternates"), join("objects", "info", "http-alternates")].some(name => existsSync(join(dir, name))))
+        return false;
+    try {
+        const held = lstatSync(join(dir, "shallow"));
+        if (!held.isFile() || held.size > 128)
+            return false;
+        return readFileSync(join(dir, "shallow"), "utf8").trim() === commit;
+    }
+    catch (error) {
+        // A history of one commit needs no shallow boundary, and git writes none.
+        return error.code === "ENOENT";
+    }
+}
+/** Fetch main at depth 1 into `dir`, under the map's limits. `onStart` records the spawn for crash cleanup. */
+export async function readShallowMain(url, dir, pin, bounded, onStart, helper) {
+    const fetched = await bounded("git", mapGitArgs(dir, pin, ["fetch", "--quiet", "--depth=1", "--no-tags", "--no-write-fetch-head", "--", url, `+refs/heads/main:${MAP_MAIN}`], { extra: LOW_MEMORY, ...(helper === undefined ? {} : { helper }) }), { cwd: dir, env: mapGitEnv(pin), timeoutMs: MAP_FETCH_LIMITS.timeoutMs, maxStdout: 4096, maxStderr: MAP_FETCH_LIMITS.maxStderr, memoryBytes: MAP_FETCH_LIMITS.memoryBytes,
+        diskBytes: MAP_FETCH_LIMITS.diskBytes, fileBytes: MAP_FETCH_LIMITS.fileBytes, folder: dir, label: "code-map-fetch", ...(onStart === undefined ? {} : { onStart }) });
+    if (fetched.code !== 0 && redirected(fetched.stderr))
+        return { ok: false, why: REMOTE_MOVED, reason: "moved" };
+    if (fetched.killed !== null)
+        return { ok: false, why: `the fetch went past its ${fetched.killed} limit` };
+    if (fetched.code !== 0)
+        return { ok: false, why: UNREAD };
+    const resolved = await bounded("git", mapGitArgs(dir, pin, ["rev-parse", "--verify", "--quiet", `${MAP_MAIN}^{commit}`]), { cwd: dir, env: mapGitEnv(pin), timeoutMs: 30_000, maxStdout: 4096, maxStderr: 4096, label: "code-map-rev" });
+    const commit = resolved.stdout.toString("utf8").trim();
+    if (resolved.code !== 0 || !SHA.test(commit) || !shallowClean(dir, commit))
+        return { ok: false, why: UNREAD };
+    return { ok: true, commit, enforced: fetched.enforced };
+}

package/dist/repository-context.d.ts

@@ -3,7 +3,8 @@ export type RepositoryContextRequest = {
     query: string;
     mode?: 'search' | 'impact';
     audience?: 'lead' | 'crew';
-    /** Canonical admitted project when repo is a crew worktree. Must share its Git common directory. */
+    /** The admitted project from Toolroll's records: repo itself, or the project a crew worktree belongs to. Every read is
+     * bound to its git folder. */
     project?: string;
     baseRevision?: string;
     cacheRoot?: string;
@@ -16,7 +17,7 @@ export type RepositoryCheckout = {
     head: string;
     baseRevision: string;
     sourceHash: string;
-    source: 'working-tree';
+    source: 'working-tree' | 'base-commit';
 };
 export type RepositoryRelationship = {
     from: string;