knodin 0.7.6 → 0.8.3

package/dist/src/mirror.js

@@ -0,0 +1,290 @@
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { mirrorEntryPath, mirrorSourcePath, mirrorStagingRoot, mirrorStatePath, readMirrorRegistry, writeMirrorRegistry, } from "./engine/state-paths.js";
+import { gitExecutable } from "./git-executable.js";
+import { repositoryIdentity } from "./repository-management.js";
+export class MirrorError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = "MirrorError";
+        this.kind = kind;
+    }
+}
+/** Marker dropped at a mirror's root so it cannot be mistaken for a checkout. */
+const MIRROR_README = `This directory is a knodin mirror: a read-only shallow clone of a remote
+repository, kept only so knodin can answer graph questions about it.
+
+This is not a working copy.
+Local edits here are DISCARDED on the next \`knodin remote refresh\`.
+Clone the repository yourself if you intend to change it.
+`;
+/**
+ * Strips credentials from a clone URL so nothing secret reaches the registry.
+ *
+ * The password always goes. The username goes only for HTTP(S), where it is
+ * routinely a token or half of a credential pair.
+ *
+ * For other schemes the username is structural, not secret: `ssh://git@host/x`
+ * means the SSH account, and clearing it yields `ssh://host/x`, which is not the
+ * same URL and cannot be used to re-add the mirror. The registry value is shown
+ * by `knodin remote list`, so a user copying it back would get a URL that does
+ * not work — the listing has to stay actionable, not merely safe.
+ */
+export function sanitizeCloneUrl(url) {
+    try {
+        const parsed = new URL(url);
+        parsed.password = "";
+        if (parsed.protocol === "http:" || parsed.protocol === "https:")
+            parsed.username = "";
+        return parsed.toString();
+    }
+    catch {
+        // scp-style (git@host:org/repo.git) carries no secret to strip.
+        return url;
+    }
+}
+/**
+ * Classifies a failed git invocation.
+ *
+ * GitHub and GitHub Enterprise deliberately answer 404 for a private repository
+ * the caller cannot see, so "missing" and "forbidden" are indistinguishable over
+ * the wire. They are therefore reported as one kind, and the message never
+ * claims the repository does not exist — that would turn an auth problem into a
+ * false statement about the remote.
+ */
+export function classifyGitFailure(stderr, signal) {
+    if (signal)
+        return "interrupted";
+    const text = stderr.toLowerCase();
+    if (/no space left on device|disk quota|write error|out of memory/.test(text))
+        return "disk";
+    if (/could not resolve host|network is unreachable|connection timed out|failed to connect|temporary failure in name resolution|operation timed out/.test(text))
+        return "network";
+    if (/repository not found|not found|does not exist|authentication failed|permission denied|access denied|could not read username|terminal prompts disabled|403|401/.test(text))
+        return "not-found-or-forbidden";
+    return "unknown";
+}
+/**
+ * Removes embedded credentials from text before it is shown or logged.
+ *
+ * Git is necessarily invoked with the *raw* clone URL, and it echoes that URL
+ * back in its own error text — `fatal: repository 'https://user:token@host/x'
+ * not found`. Everything we surface interpolates that stderr, so a token in the
+ * URL would land in terminal output, and from there into scrollback, CI logs and
+ * support bundles. Only the registry copy was being sanitized.
+ *
+ * Two passes: an exact substitution of the raw URL when we have it, and a
+ * generic `//user:secret@` scrub for anything git spells differently (trailing
+ * `.git/`, percent-encoding, a redirect target we never passed in).
+ *
+ * The username class also excludes `:`, which is what makes this linear. An
+ * earlier form used `[^/@\s]*:[^/@\s]*@` and I argued it was safe because
+ * neither class can span the `@` that terminates them — true, and beside the
+ * point: neither class excluded `:` either, so a run of colons could be split
+ * between them in as many ways as there were colons. Measured on `//` followed
+ * by `a:` repeated, with no `@` to succeed on: 3.7 / 18.8 / 65.9 / 226.8 ms at
+ * 4k / 8k / 16k / 32k chars — quadratic. Excluding `:` from the first class
+ * fixes the split at the first colon; flat at 0.03 ms across the same inputs.
+ *
+ * Third time today that a regex I reasoned was linear was not, so: the guard on
+ * the credential-scrubbing path is itself measured, not argued.
+ */
+const EMBEDDED_CREDENTIAL = /\/\/[^/@\s:]*:[^/@\s]*@/g;
+/**
+ * Username-only userinfo on HTTP(S), e.g. `https://<token>@host/x`.
+ *
+ * Raised in review on #59: the pair form above misses a token passed as the
+ * username alone, which is a normal way to authenticate over HTTPS, so the
+ * scrub would have left it intact unless it happened to match `rawUrl` exactly.
+ *
+ * Restricted to `http:`/`https:` on purpose, and it is the same distinction
+ * `sanitizeCloneUrl` makes: over SSH the username is structural (`ssh://git@…`
+ * names the account), so blanket-redacting `//user@` would mangle SSH URLs in
+ * error text while protecting nothing. A *password* is secret under any scheme
+ * and is still caught by the pair pattern.
+ *
+ * Linear: the class excludes `/`, `@`, `:` and whitespace, so it cannot span
+ * either the `@` that terminates it or the `//` that begins the next attempt.
+ * Verified by measurement rather than by that argument — see the spec.
+ */
+const HTTP_USERINFO = /(https?:\/\/)[^/@\s:]*@/gi;
+export function redactSecrets(text, rawUrl) {
+    let out = text;
+    if (rawUrl?.includes("@"))
+        out = out.split(rawUrl).join(sanitizeCloneUrl(rawUrl));
+    out = out.replace(HTTP_USERINFO, "$1***@");
+    return out.replace(EMBEDDED_CREDENTIAL, "//***:***@");
+}
+/** Human-facing message for a failure kind, naming the identity actually used. */
+function failureMessage(kind, url, stderr, rawUrl) {
+    const detail = redactSecrets(stderr, rawUrl).trim().split("\n").slice(-3).join(" ").slice(0, 400);
+    switch (kind) {
+        case "not-found-or-forbidden": {
+            // Git's own wording asserts non-existence ("repository ... does not
+            // exist", "Repository not found"), which is precisely the claim that
+            // cannot be supported: the server answers identically whether the
+            // repository is absent or merely invisible to these credentials.
+            // Passing that text through would launder a guess into a finding.
+            const neutral = detail
+                .replace(/does ?n[o']t exist/gi, "was not accessible")
+                .replace(/repository not found/gi, "repository not accessible");
+            return `knodin remote: ${url} was not found, or is not accessible with the credentials in use. Git reports both cases identically, so this is NOT evidence the repository is missing — retry with an account that has access (\`gh-as <account>\`) or an SSH remote. git reported: ${neutral}`;
+        }
+        case "network":
+            return `knodin remote: could not reach ${url}. ${detail}`;
+        case "disk":
+            return `knodin remote: ran out of disk while acquiring ${url}. ${detail}`;
+        case "interrupted":
+            return `knodin remote: acquiring ${url} was interrupted before it completed. ${detail}`;
+        default:
+            return `knodin remote: failed to acquire ${url}. ${detail}`;
+    }
+}
+/**
+ * Runs git, throwing a classified MirrorError on failure.
+ *
+ * `url` is the sanitized form used in messages. `rawUrl` is the credentialed
+ * form actually handed to git, supplied only so its secret can be scrubbed back
+ * out of git's own error text — never for display.
+ */
+function runGit(args, url, cwd, rawUrl) {
+    const result = childProcess.spawnSync(gitExecutable(), args, {
+        cwd,
+        encoding: "utf8",
+        env: {
+            ...process.env,
+            // Never block on an interactive credential prompt: a hang is worse than
+            // a clean, classified failure.
+            GIT_TERMINAL_PROMPT: "0",
+        },
+    });
+    if (result.error)
+        throw new MirrorError("unknown", `${redactSecrets(result.error.message, rawUrl)} (${url})`);
+    if (result.status !== 0) {
+        const kind = classifyGitFailure(result.stderr ?? "", result.signal);
+        throw new MirrorError(kind, failureMessage(kind, url, result.stderr ?? "", rawUrl));
+    }
+    return result.stdout ?? "";
+}
+/** Recursively removes a directory, ignoring absence. */
+function discard(target) {
+    fs.rmSync(target, { recursive: true, force: true });
+}
+/**
+ * Acquires a mirror of `url`.
+ *
+ * The clone lands in a staging directory and is renamed into place only once it
+ * has completed, so an interrupted acquisition can never leave a partial mirror
+ * that later reads as a complete one — the same failure shape as an empty graph
+ * that reads as "no results".
+ */
+export function addMirror(url) {
+    const sanitized = sanitizeCloneUrl(url);
+    const staging = path.join(mirrorStagingRoot(), `pending-${process.pid}`);
+    fs.mkdirSync(mirrorStagingRoot(), { recursive: true });
+    discard(staging);
+    try {
+        // The raw `url` goes to git because it may carry the credentials that make
+        // the clone work; `sanitized` is what any message may show, and passing the
+        // raw form as the last argument lets its secret be scrubbed from git's own
+        // error text rather than echoed back to the terminal.
+        runGit(["clone", "--depth", "1", "--single-branch", url, staging], sanitized, undefined, url);
+        // Git records the clone URL verbatim in `.git/config`, so a token embedded
+        // in `url` would persist on disk inside the mirror — in a directory whose
+        // path `knodin remote list` prints — and be reused implicitly by every
+        // later `refresh`. Sanitizing the registry copy while leaving the real
+        // secret in the clone's config would be sanitization in name only.
+        //
+        // The cost is deliberate: `refresh` can no longer authenticate from a
+        // token baked into the URL, and falls back to whatever git would use
+        // anyway — an SSH key or a credential helper. When that is not configured,
+        // refresh fails with the existing not-found-or-forbidden message, which
+        // already points at `gh-as` and SSH remotes. An honest auth failure is
+        // better than a credential quietly living in ~/.knodin.
+        if (sanitized !== url)
+            runGit(["remote", "set-url", "origin", sanitized], sanitized, staging);
+        const identity = repositoryIdentity(staging);
+        const entry = mirrorEntryPath(identity);
+        const source = mirrorSourcePath(identity);
+        const existing = readMirrorRegistry().mirrors.find((m) => m.identity === identity);
+        if (existing && fs.existsSync(source)) {
+            discard(staging);
+            return { record: existing, alreadyPresent: true };
+        }
+        const sha = runGit(["rev-parse", "HEAD"], sanitized, staging).trim();
+        fs.mkdirSync(entry, { recursive: true });
+        fs.mkdirSync(mirrorStatePath(identity), { recursive: true });
+        discard(source);
+        fs.renameSync(staging, source);
+        fs.writeFileSync(path.join(entry, "README"), MIRROR_README);
+        const record = {
+            identity,
+            url: sanitized,
+            path: source,
+            fetchedAt: new Date().toISOString(),
+            sha,
+            readOnly: true,
+        };
+        const registry = readMirrorRegistry();
+        writeMirrorRegistry({
+            version: 1,
+            mirrors: [...registry.mirrors.filter((m) => m.identity !== identity), record],
+        });
+        return { record, alreadyPresent: false };
+    }
+    finally {
+        discard(staging);
+    }
+}
+/**
+ * All registered mirrors, newest fetch first.
+ *
+ * Byte order, not `localeCompare`. `fetchedAt` is ISO 8601, which sorts
+ * correctly lexicographically, and locale collation can treat punctuation as
+ * variable-weight — so the `-`, `:` and `T` separators are not guaranteed to be
+ * compared the same way on every host. Same reasoning as `comparePaths`: this
+ * output should not depend on the machine it ran on.
+ */
+export function listMirrors() {
+    return [...readMirrorRegistry().mirrors].sort((left, right) => {
+        if (left.fetchedAt > right.fetchedAt)
+            return -1;
+        return left.fetchedAt < right.fetchedAt ? 1 : 0;
+    });
+}
+/** Removes a mirror's clone, its graph, and its registry entry. */
+export function removeMirror(identity) {
+    const registry = readMirrorRegistry();
+    if (!registry.mirrors.some((mirror) => mirror.identity === identity))
+        return false;
+    discard(mirrorEntryPath(identity));
+    writeMirrorRegistry({
+        version: 1,
+        mirrors: registry.mirrors.filter((m) => m.identity !== identity),
+    });
+    return true;
+}
+/**
+ * Fetches the mirror's branch again and hard-resets the clone onto it. The graph
+ * is left alone; callers re-index. Returns the record with its new sha.
+ */
+export function refreshMirror(identity) {
+    const registry = readMirrorRegistry();
+    const record = registry.mirrors.find((m) => m.identity === identity);
+    if (!record)
+        throw new MirrorError("unknown", `knodin remote: no mirror named ${identity}`);
+    const source = record.path;
+    if (!fs.existsSync(source))
+        throw new MirrorError("unknown", `knodin remote: mirror ${identity} is registered but its clone is missing; remove and re-add it`);
+    runGit(["fetch", "--depth", "1", "origin"], record.url, source);
+    runGit(["reset", "--hard", "FETCH_HEAD"], record.url, source);
+    const sha = runGit(["rev-parse", "HEAD"], record.url, source).trim();
+    const updated = { ...record, sha, fetchedAt: new Date().toISOString() };
+    writeMirrorRegistry({
+        version: 1,
+        mirrors: [...registry.mirrors.filter((m) => m.identity !== identity), updated],
+    });
+    return updated;
+}

package/dist/src/node-runtime.js

@@ -0,0 +1,157 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { compareBytesDescending } from "./compare.js";
+const MINIMUM_NODE_MAJOR = 24;
+function nodeMajor(version) {
+    const match = version?.trim().match(/^v?(\d+)(?:\.|$)/);
+    if (!match)
+        return undefined;
+    const major = Number(match[1]);
+    return Number.isSafeInteger(major) ? major : undefined;
+}
+function isSupported(version) {
+    return (nodeMajor(version) ?? 0) >= MINIMUM_NODE_MAJOR;
+}
+function sortVersionsDescending(left, right) {
+    const leftParts = left.replace(/^v/, "").split(".").map(Number);
+    const rightParts = right.replace(/^v/, "").split(".").map(Number);
+    for (let index = 0; index < Math.max(leftParts.length, rightParts.length); index += 1) {
+        const difference = (rightParts[index] ?? 0) - (leftParts[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    // Byte order: this tie-break decides which runtime the handoff selects, so it
+    // must not vary with the host locale. Descending, matching the numeric
+    // comparison above.
+    return compareBytesDescending(left, right);
+}
+function addPathCandidates(options, executableName, add) {
+    for (const directory of (options.env.PATH ?? "").split(options.pathApi.delimiter)) {
+        if (directory && options.pathApi.isAbsolute(directory))
+            add(options.pathApi.join(directory, executableName));
+    }
+}
+function defaultFnmRoot(options, appDataRoot) {
+    if (options.platform === "darwin")
+        return options.pathApi.join(options.homeDirectory, "Library", "Application Support", "fnm");
+    if (options.platform === "win32" && appDataRoot)
+        return options.pathApi.join(appDataRoot, "fnm");
+    return options.pathApi.join(options.homeDirectory, ".local", "share", "fnm");
+}
+function addPlatformCandidates(options, executableName, absoluteEnvRoot, add, addVersioned) {
+    if (options.platform === "darwin") {
+        add("/opt/homebrew/opt/node@24/bin/node");
+        add("/opt/homebrew/opt/node/bin/node");
+        add("/usr/local/opt/node@24/bin/node");
+        add("/usr/local/opt/node/bin/node");
+    }
+    if (options.platform === "win32") {
+        addVersioned(absoluteEnvRoot(options.env.NVM_HOME), []);
+        const programFilesRoot = absoluteEnvRoot(options.env.ProgramFiles);
+        add(programFilesRoot
+            ? options.pathApi.join(programFilesRoot, "nodejs", executableName)
+            : undefined);
+    }
+}
+function runtimeCandidates(options) {
+    const { env, homeDirectory, pathApi, platform } = options;
+    const executableName = platform === "win32" ? "node.exe" : "node";
+    const candidates = [];
+    const seen = new Set([options.currentExecutable]);
+    const add = (candidate) => {
+        if (!candidate || seen.has(candidate))
+            return;
+        seen.add(candidate);
+        candidates.push(candidate);
+    };
+    const addVersioned = (root, suffix) => {
+        if (!root || !pathApi.isAbsolute(root))
+            return;
+        for (const version of options.listDirectories(root).sort(sortVersionsDescending))
+            add(pathApi.join(root, version, ...suffix, executableName));
+    };
+    if (env.KNODIN_NODE_RUNTIME && !pathApi.isAbsolute(env.KNODIN_NODE_RUNTIME))
+        throw new Error("KNODIN_NODE_RUNTIME must be an absolute path to a Node.js executable.");
+    add(env.KNODIN_NODE_RUNTIME);
+    addPathCandidates(options, executableName, add);
+    const absoluteEnvRoot = (value) => value && pathApi.isAbsolute(value) ? value : undefined;
+    const miseRoot = absoluteEnvRoot(env.MISE_DATA_DIR) ?? pathApi.join(homeDirectory, ".local", "share", "mise");
+    const managerBinaryDirectory = platform === "win32" ? [] : ["bin"];
+    addVersioned(pathApi.join(miseRoot, "installs", "node"), managerBinaryDirectory);
+    addVersioned(pathApi.join(homeDirectory, ".mise", "installs", "node"), managerBinaryDirectory);
+    const nvmRoot = absoluteEnvRoot(env.NVM_DIR);
+    addVersioned(nvmRoot ? pathApi.join(nvmRoot, "versions", "node") : undefined, managerBinaryDirectory);
+    addVersioned(pathApi.join(homeDirectory, ".nvm", "versions", "node"), managerBinaryDirectory);
+    const appDataRoot = absoluteEnvRoot(env.APPDATA);
+    const fnmDefaultRoot = defaultFnmRoot(options, appDataRoot);
+    const fnmRoot = absoluteEnvRoot(env.FNM_DIR);
+    addVersioned(fnmRoot ? pathApi.join(fnmRoot, "node-versions") : undefined, platform === "win32" ? ["installation"] : ["installation", "bin"]);
+    addVersioned(pathApi.join(fnmDefaultRoot, "node-versions"), platform === "win32" ? ["installation"] : ["installation", "bin"]);
+    const asdfRoot = absoluteEnvRoot(env.ASDF_DATA_DIR) ?? pathApi.join(homeDirectory, ".asdf");
+    addVersioned(pathApi.join(asdfRoot, "installs", "nodejs"), managerBinaryDirectory);
+    const voltaRoot = absoluteEnvRoot(env.VOLTA_HOME) ?? pathApi.join(homeDirectory, ".volta");
+    addVersioned(pathApi.join(voltaRoot, "tools", "image", "node"), managerBinaryDirectory);
+    addPlatformCandidates(options, executableName, absoluteEnvRoot, add, addVersioned);
+    return candidates;
+}
+export function handoffToSupportedNodeRuntime(options) {
+    if (isSupported(options.currentVersion))
+        return { kind: "current" };
+    const explicitRuntime = options.env.KNODIN_NODE_RUNTIME;
+    if (explicitRuntime === options.currentExecutable)
+        throw new Error(`KNODIN_NODE_RUNTIME points to the active Node.js ${options.currentVersion} executable; Node.js 24 or newer is required.`);
+    for (const candidate of runtimeCandidates(options)) {
+        const version = options.probe(candidate);
+        if (!isSupported(version)) {
+            if (candidate === explicitRuntime) {
+                throw new Error(`KNODIN_NODE_RUNTIME points to ${candidate}, but it reports ${version ?? "no usable Node.js version"}; Node.js 24 or newer is required.`);
+            }
+            continue;
+        }
+        const result = options.spawn(candidate, options.launcherArguments, {
+            env: options.env,
+            stdio: "inherit",
+        });
+        if (result.error)
+            throw new Error(`Unable to launch Knodin with ${candidate}: ${result.error.message}`);
+        if (result.status === null && result.signal === null)
+            throw new Error(`Knodin's Node.js 24+ runtime at ${candidate} exited without a status.`);
+        return { kind: "relaunched", status: result.status, signal: result.signal };
+    }
+    throw new Error(`Knodin requires Node.js 24 or newer, but the active runtime is ${options.currentVersion}. Install Node.js 24+ with Homebrew or your version manager, or set KNODIN_NODE_RUNTIME=/absolute/path/to/node. Your project may remain pinned to Node.js 20.`);
+}
+function listDirectories(root) {
+    try {
+        return fs
+            .readdirSync(root, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+function probeNodeVersion(candidate) {
+    const result = spawnSync(candidate, ["-p", "process.versions.node"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 2_000,
+    });
+    return result.status === 0 ? result.stdout.trim() : undefined;
+}
+export function handoffCurrentProcessToSupportedNodeRuntime() {
+    return handoffToSupportedNodeRuntime({
+        currentExecutable: process.execPath,
+        currentVersion: process.versions.node,
+        env: process.env,
+        homeDirectory: os.homedir(),
+        platform: process.platform,
+        launcherArguments: process.argv.slice(1),
+        probe: probeNodeVersion,
+        spawn: (candidate, args, options) => spawnSync(candidate, args, options),
+        pathApi: path,
+        listDirectories,
+    });
+}