knodin 0.8.7 → 0.9.0

package/dist/src/manager-update.js

@@ -0,0 +1,455 @@
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const UPDATE_JOURNAL_STATES = [
+    "planned",
+    "manager-applying",
+    "candidate-installed-unverified",
+    "candidate-verifying",
+    "candidate-verified",
+    "rollback-required",
+    "rollback-applying",
+    "rollback-installed-unverified",
+    "rollback-verifying",
+    "rollback-verified",
+    "terminal-unhealthy",
+];
+const MAX_STATE_BYTES = 1024 * 1024;
+const MAX_CHANNEL_BYTES = 4 * 1024 * 1024;
+const CHANNEL_TIMEOUT_MS = 10_000;
+function stateRoot(stateHome) {
+    const root = stateHome ?? process.env.XDG_STATE_HOME ?? path.join(os.homedir(), ".local", "state");
+    return path.join(root, "knodin", "updates");
+}
+export function managerUpdateStatePath(stateHome) {
+    return path.join(stateRoot(stateHome), "state.json");
+}
+export function updateJournalPath(stateHome) {
+    return path.join(stateRoot(stateHome), "journal.json");
+}
+function boundedJson(file) {
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_STATE_BYTES)
+            return null;
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function fsyncDirectory(directory) {
+    try {
+        const descriptor = fs.openSync(directory, "r");
+        try {
+            fs.fsyncSync(descriptor);
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+    }
+    catch {
+        // Windows cannot fsync directories. The file itself is still fsynced.
+    }
+}
+function atomicWrite(file, value) {
+    const directory = path.dirname(file);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const temporary = path.join(directory, `.${path.basename(file)}.${process.pid}.${randomUUID()}`);
+    const descriptor = fs.openSync(temporary, "wx", 0o600);
+    try {
+        fs.writeFileSync(descriptor, `${JSON.stringify(value)}\n`, "utf8");
+        fs.fsyncSync(descriptor);
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+    fs.renameSync(temporary, file);
+    fsyncDirectory(directory);
+}
+export function readManagerUpdateState(stateHome) {
+    const value = boundedJson(managerUpdateStatePath(stateHome));
+    if (value?.schemaVersion === 1 && typeof value.autoEnabled === "boolean")
+        return value;
+    return { schemaVersion: 1, autoEnabled: false, platformAutoEligible: false };
+}
+export function writeManagerUpdateState(state, stateHome) {
+    atomicWrite(managerUpdateStatePath(stateHome), state);
+}
+export function readUpdateJournal(stateHome) {
+    const value = boundedJson(updateJournalPath(stateHome));
+    if (!value || value.schemaVersion !== 1 || !UPDATE_JOURNAL_STATES.includes(value.state))
+        return null;
+    return value;
+}
+export function writeUpdateJournal(journal, stateHome) {
+    atomicWrite(updateJournalPath(stateHome), journal);
+}
+export function transitionUpdateJournal(journal, state, changes = {}, stateHome) {
+    const next = { ...journal, ...changes, state, updatedAt: new Date().toISOString() };
+    writeUpdateJournal(next, stateHome);
+    return next;
+}
+function processStartToken(pid = process.pid) {
+    try {
+        if (process.platform === "win32") {
+            return execFileSync("powershell.exe", ["-NoProfile", "-Command", `(Get-Process -Id ${pid}).StartTime.ToUniversalTime().Ticks`], { encoding: "utf8", timeout: 2_000 }).trim();
+        }
+        return execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+            encoding: "utf8",
+            timeout: 2_000,
+        }).trim();
+    }
+    catch {
+        return "unavailable";
+    }
+}
+export function createUpdateJournal(input) {
+    const now = new Date().toISOString();
+    return {
+        schemaVersion: 1,
+        id: randomUUID(),
+        state: "planned",
+        previousVersion: input.previousVersion,
+        targetVersion: input.targetVersion,
+        manager: input.manager,
+        previousExecutable: input.manager.executable,
+        fixtureVersion: input.fixtureVersion,
+        pid: process.pid,
+        processStartToken: processStartToken(),
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+function realIdentity(candidate) {
+    try {
+        const stat = fs.lstatSync(candidate);
+        if (!stat.isFile() && !stat.isSymbolicLink())
+            return null;
+        return { path: path.resolve(candidate), realpath: fs.realpathSync(candidate) };
+    }
+    catch {
+        return null;
+    }
+}
+function pathExecutables(env) {
+    const found = [];
+    const stale = [];
+    const names = process.platform === "win32" ? ["knodin.cmd", "knodin.exe", "knodin"] : ["knodin"];
+    for (const directory of (env.PATH ?? "").split(path.delimiter).filter(Boolean)) {
+        for (const name of names) {
+            const candidate = path.join(directory, name);
+            try {
+                const stat = fs.lstatSync(candidate);
+                if (stat.isSymbolicLink()) {
+                    try {
+                        fs.realpathSync(candidate);
+                    }
+                    catch {
+                        stale.push(path.resolve(candidate));
+                        continue;
+                    }
+                }
+                const identity = realIdentity(candidate);
+                if (identity && !found.some((entry) => entry.realpath === identity.realpath))
+                    found.push(identity);
+            }
+            catch {
+                // PATH entries are untrusted hints; absence is ordinary.
+            }
+        }
+    }
+    return { found, stale };
+}
+function methodFromEvidence(chain, env) {
+    const text = chain.join("\n").toLowerCase();
+    if (text.includes("/cellar/") || text.includes("/homebrew/") || env.HOMEBREW_PREFIX)
+        return "homebrew";
+    if (text.includes("/.local/share/mise/") || env.MISE_DATA_DIR || env.MISE_ENV)
+        return "mise";
+    if (text.includes("/.volta/") || env.VOLTA_HOME)
+        return "volta";
+    if (text.includes("/.nvm/") || env.NVM_BIN || env.NVM_DIR)
+        return "nvm";
+    if (text.includes("/fnm") || env.FNM_DIR || env.FNM_MULTISHELL_PATH)
+        return "fnm";
+    if (text.includes("/.asdf/") || env.ASDF_DIR || env.ASDF_DATA_DIR)
+        return "asdf";
+    if (text.includes("node_modules/knodin") || text.includes("/npm/"))
+        return "npm";
+    return "unknown";
+}
+export function resolveManagerOwnership(options = {}) {
+    const env = options.env ?? process.env;
+    const executablePath = options.executablePath ?? options.runtimeCommand?.[0] ?? process.argv[1] ?? process.execPath;
+    const executable = realIdentity(executablePath) ?? {
+        path: path.resolve(executablePath),
+        realpath: path.resolve(executablePath),
+    };
+    const chain = [executable.path, executable.realpath, ...(options.runtimeCommand ?? [])];
+    const packageMarker = `${path.sep}node_modules${path.sep}knodin${path.sep}`;
+    const markerIndex = executable.realpath.lastIndexOf(packageMarker);
+    const packageRoot = markerIndex >= 0
+        ? executable.realpath.slice(0, markerIndex + packageMarker.length - 1)
+        : undefined;
+    const receipts = [];
+    if (packageRoot && fs.existsSync(path.join(packageRoot, "package.json")))
+        receipts.push(path.join(packageRoot, "package.json"));
+    const paths = pathExecutables(env);
+    const method = methodFromEvidence([...chain, ...receipts], env);
+    const duplicates = paths.found.filter((entry) => entry.realpath !== executable.realpath);
+    const pathShadowing = paths.found.length > 0 && paths.found[0]?.realpath !== executable.realpath;
+    const ambiguous = duplicates.length > 0 || paths.stale.length > 0 || pathShadowing;
+    const evidence = [
+        `active executable: ${executable.path}`,
+        `resolved executable: ${executable.realpath}`,
+        ...(packageRoot ? [`package root: ${packageRoot}`] : []),
+        ...receipts.map((receipt) => `manager receipt: ${receipt}`),
+        ...duplicates.map((entry) => `competing executable: ${entry.path} -> ${entry.realpath}`),
+        ...paths.stale.map((entry) => `stale PATH link: ${entry}`),
+    ];
+    return {
+        method,
+        status: ambiguous ? "ambiguous" : method === "unknown" ? "unknown" : "owned",
+        executable,
+        packageRoot,
+        receipts,
+        chain,
+        duplicates,
+        staleLinks: paths.stale,
+        pathShadowing,
+        evidence,
+    };
+}
+export function setManualPin(version, stateHome) {
+    if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version))
+        throw new Error("pin requires a semantic version");
+    const state = readManagerUpdateState(stateHome);
+    const next = {
+        ...state,
+        pin: { kind: "manual", version, createdAt: new Date().toISOString() },
+    };
+    writeManagerUpdateState(next, stateHome);
+    return next;
+}
+export function setAutomaticRollbackPin(restoredVersion, failedVersion, stateHome) {
+    const state = readManagerUpdateState(stateHome);
+    const next = {
+        ...state,
+        pin: {
+            kind: "automatic-rollback",
+            version: restoredVersion,
+            failedVersion,
+            createdAt: new Date().toISOString(),
+        },
+    };
+    writeManagerUpdateState(next, stateHome);
+    return next;
+}
+export function unpinUpdate(stateHome) {
+    const { pin: _pin, ...state } = readManagerUpdateState(stateHome);
+    const next = { ...state, schemaVersion: 1 };
+    writeManagerUpdateState(next, stateHome);
+    return next;
+}
+export function acknowledgeUpdateFailure(stateHome) {
+    const state = readManagerUpdateState(stateHome);
+    if (state.pin?.kind !== "automatic-rollback" || !state.pin.failedVersion)
+        return state;
+    const next = {
+        ...state,
+        pin: { ...state.pin, acknowledgedFailedVersion: state.pin.failedVersion },
+    };
+    writeManagerUpdateState(next, stateHome);
+    return next;
+}
+export function updateAttention(state) {
+    const pin = state.pin;
+    if (pin?.kind !== "automatic-rollback" || !pin.failedVersion)
+        return null;
+    if (pin.newerAvailableVersion && pin.newerAvailableVersion !== pin.failedVersion) {
+        return `Knodin remains pinned to ${pin.version} after ${pin.failedVersion} failed verification.\n${pin.newerAvailableVersion} is now available; review the release and run \`knodin update unpin\` when ready.`;
+    }
+    if (pin.acknowledgedFailedVersion === pin.failedVersion)
+        return null;
+    return `Knodin remains pinned to ${pin.version} after ${pin.failedVersion} failed verification. Run \`knodin update acknowledge\` to suppress this notice or \`knodin update unpin\` when ready.`;
+}
+function parseVersion(version) {
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/.exec(version);
+    if (!match)
+        return null;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease: version.includes("-"),
+    };
+}
+function compareVersion(left, right) {
+    const a = parseVersion(left);
+    const b = parseVersion(right);
+    if (!a || !b)
+        return left < right ? -1 : left === right ? 0 : 1;
+    return (a.major - b.major ||
+        a.minor - b.minor ||
+        a.patch - b.patch ||
+        Number(b.prerelease) - Number(a.prerelease));
+}
+async function boundedChannelJson(url, options) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "https:" || parsed.username || parsed.password)
+        throw new Error("owner channel must use credential-free HTTPS");
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? CHANNEL_TIMEOUT_MS);
+    try {
+        let bytes;
+        if (options.fetchBytes)
+            bytes = await options.fetchBytes(url, controller.signal, MAX_CHANNEL_BYTES);
+        else {
+            const response = await fetch(url, {
+                signal: controller.signal,
+                redirect: "error",
+                headers: { accept: "application/json" },
+            });
+            if (!response.ok)
+                throw new Error(`owner channel returned HTTP ${response.status}`);
+            const declared = Number(response.headers.get("content-length"));
+            if (Number.isFinite(declared) && declared > MAX_CHANNEL_BYTES)
+                throw new Error("owner channel metadata exceeds its byte limit");
+            bytes = new Uint8Array(await response.arrayBuffer());
+        }
+        if (bytes.byteLength > MAX_CHANNEL_BYTES)
+            throw new Error("owner channel metadata exceeds its byte limit");
+        return JSON.parse(Buffer.from(bytes).toString("utf8"));
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function npmReleases(value) {
+    const versions = value.versions;
+    const times = value.time;
+    if (!versions || !times)
+        throw new Error("npm metadata is incomplete");
+    return Object.entries(versions)
+        .filter(([version]) => parseVersion(version))
+        .map(([version, manifest]) => {
+        const policy = manifest.knodin;
+        return {
+            version,
+            publishedAt: times[version] ?? "",
+            yanked: manifest.deprecated === true || typeof manifest.deprecated === "string",
+            breaking: policy?.compatibility === "non-breaking"
+                ? false
+                : policy?.compatibility === "breaking"
+                    ? true
+                    : null,
+            channel: "npm",
+        };
+    })
+        .sort((left, right) => compareVersion(right.version, left.version));
+}
+function homebrewReleases(value) {
+    const versions = value.versions;
+    if (!Array.isArray(versions))
+        throw new Error("Homebrew version metadata is incomplete");
+    return versions
+        .filter((entry) => Boolean(entry && typeof entry === "object"))
+        .filter((entry) => typeof entry.version === "string" && parseVersion(entry.version))
+        .map((entry) => ({
+        version: String(entry.version),
+        publishedAt: typeof entry.publishedAt === "string" ? entry.publishedAt : "",
+        yanked: entry.yanked === true,
+        breaking: entry.compatibility === "non-breaking"
+            ? false
+            : entry.compatibility === "breaking"
+                ? true
+                : null,
+        channel: "homebrew",
+    }))
+        .sort((left, right) => compareVersion(right.version, left.version));
+}
+export async function queryOwnerAvailability(options) {
+    const owner = options.owner ?? resolveManagerOwnership();
+    if (owner.status === "ambiguous")
+        return {
+            status: "owner-ambiguous",
+            owner,
+            installedVersion: options.installedVersion,
+            releases: [],
+            autoEligible: false,
+            reason: "multiple, stale, or shadowing installations require manual cleanup",
+            networkUsed: false,
+        };
+    if (owner.status === "unknown")
+        return {
+            status: "owner-unknown",
+            owner,
+            installedVersion: options.installedVersion,
+            releases: [],
+            autoEligible: false,
+            reason: "the active executable owner could not be proven",
+            networkUsed: false,
+        };
+    try {
+        const homebrew = owner.method === "homebrew";
+        const url = homebrew
+            ? "https://raw.githubusercontent.com/knodin/knodin/main/versions.json"
+            : "https://registry.npmjs.org/knodin";
+        const metadata = await boundedChannelJson(url, options);
+        const releases = homebrew ? homebrewReleases(metadata) : npmReleases(metadata);
+        const latest = releases.find((release) => !release.yanked);
+        if (!latest)
+            throw new Error("owner channel has no retained release");
+        const current = parseVersion(options.installedVersion);
+        const candidate = parseVersion(latest.version);
+        const ageHours = ((options.now ?? new Date()).getTime() - Date.parse(latest.publishedAt)) / 3_600_000;
+        const autoEligible = Boolean(current &&
+            candidate &&
+            !candidate.prerelease &&
+            candidate.major === current.major &&
+            candidate.minor === current.minor &&
+            candidate.patch > current.patch &&
+            latest.breaking === false &&
+            Number.isFinite(ageHours) &&
+            ageHours >= 24);
+        return {
+            status: compareVersion(latest.version, options.installedVersion) > 0 ? "available" : "up-to-date",
+            owner,
+            installedVersion: options.installedVersion,
+            latestVersion: latest.version,
+            releases,
+            autoEligible,
+            reason: autoEligible
+                ? undefined
+                : "only explicitly non-breaking patch releases at least 24 hours old are automatic",
+            networkUsed: true,
+        };
+    }
+    catch (error) {
+        return {
+            status: "unavailable",
+            owner,
+            installedVersion: options.installedVersion,
+            releases: [],
+            autoEligible: false,
+            reason: error instanceof Error ? error.message : String(error),
+            networkUsed: true,
+        };
+    }
+}
+export function managerInstallArgv(method, version) {
+    if (!parseVersion(version))
+        throw new Error("manager installation requires a semantic version");
+    if (method === "homebrew")
+        return ["brew", "install", `knodin/homebrew-tap/knodin@${version}`];
+    if (method === "volta")
+        return ["volta", "install", `knodin@${version}`];
+    if (method === "mise")
+        return ["mise", "use", "--global", `npm:knodin@${version}`];
+    if (["npm", "nvm", "fnm", "asdf"].includes(method))
+        return ["npm", "install", "--global", `knodin@${version}`];
+    return null;
+}