agentic-numerical-control 0.0.0-stage → 0.1.0

package/dist/server/product.js

@@ -0,0 +1,21 @@
+// Product identity and install locations, from product.json at the package
+// root. Renaming the product is a change to that file only.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/** Package root: one level above server/ (dev) or dist/server/'s parent's parent (built). */
+export const ROOT = (() => {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    while (!fs.existsSync(path.join(dir, "product.json"))) {
+        const up = path.dirname(dir);
+        if (up === dir)
+            throw new Error("product.json not found above " + fileURLToPath(import.meta.url));
+        dir = up;
+    }
+    return dir;
+})();
+export const PRODUCT = JSON.parse(fs.readFileSync(path.join(ROOT, "product.json"), "utf-8"));
+export const VERSION = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf-8")).version;
+/** Folder the user drops G-code into; Claude can open any job in it. */
+export const JOBS_DIR = path.resolve(process.env.ANC_JOBS_DIR ?? path.join(os.homedir(), "Documents", PRODUCT.displayName));

package/dist/server/relay.js

@@ -0,0 +1,147 @@
+// Keeps this PC linked to a Agentic Numerical Control cloud account. The PC dials out to the
+// cloud over a WebSocket; MCP requests from Claude arrive on it and are
+// answered by the local MCP endpoint. Nothing listens on the network.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import WebSocket from "ws";
+import { STATE_DIR } from "./paths.js";
+export const DEVICE_FILE = path.join(STATE_DIR, "device.json");
+const PING_MS = 25_000;
+const MAX_BACKOFF_MS = 30_000;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export function readLink() {
+    try {
+        return JSON.parse(fs.readFileSync(DEVICE_FILE, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function postJson(url, body) {
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    const json = (await res.json().catch(() => ({})));
+    if (!res.ok)
+        throw new Error(json.error ?? `${res.status} ${res.statusText}`);
+    return json;
+}
+/** Device-code pairing: show a code, wait for the person to approve it online. */
+export async function pair(cloudUrl) {
+    for (;;) {
+        const link = await pairOnce(cloudUrl);
+        if (link)
+            return link;
+        console.log("  That code expired; here is a new one.");
+    }
+}
+async function pairOnce(cloudUrl) {
+    const name = `${os.hostname()} (Agentic Numerical Control)`;
+    const start = await postJson(`${cloudUrl}/api/device/start`, { name });
+    console.log("");
+    console.log("  Link this PC to your Agentic Numerical Control account:");
+    console.log(`    1. Open ${start.verificationUri}`);
+    console.log(`    2. Sign in and check the code is ${start.userCode}`);
+    console.log("");
+    const deadline = Date.now() + start.expiresIn * 1000;
+    while (Date.now() < deadline) {
+        await sleep(start.interval * 1000);
+        let poll;
+        try {
+            poll = await postJson(`${cloudUrl}/api/device/poll`, { deviceCode: start.deviceCode });
+        }
+        catch (e) {
+            console.error(`[anc] Pairing: ${e.message}`);
+            return null;
+        }
+        if (poll.status === "approved") {
+            const link = { cloudUrl, deviceToken: poll.deviceToken, name };
+            fs.mkdirSync(STATE_DIR, { recursive: true });
+            fs.writeFileSync(DEVICE_FILE, JSON.stringify(link, null, 2), { mode: 0o600 });
+            console.log("  Linked. Agentic Numerical Control is now available in Claude.\n");
+            return link;
+        }
+    }
+    return null;
+}
+/**
+ * Runs the relay forever: pairs if needed, then keeps the WebSocket open and
+ * forwards each request to `localMcpUrl`.
+ */
+export async function runRelay(cloudUrlArg, localMcpUrl) {
+    let link = readLink();
+    const cloudUrl = (cloudUrlArg ?? link?.cloudUrl ?? process.env.ANC_CLOUD_URL)?.replace(/\/+$/, "");
+    if (!cloudUrl)
+        throw new Error("Pass the Agentic Numerical Control cloud address, e.g. --relay https://agentic-numerical-control.example.workers.dev");
+    if (!link || link.cloudUrl !== cloudUrl)
+        link = await pair(cloudUrl);
+    let backoff = 1000;
+    for (;;) {
+        const result = await connectOnce(link, localMcpUrl, () => {
+            backoff = 1000;
+        });
+        if (result === "unlinked") {
+            console.error("[anc] This PC is no longer linked. Pairing again.");
+            fs.rmSync(DEVICE_FILE, { force: true });
+            link = await pair(cloudUrl);
+            continue;
+        }
+        await sleep(backoff);
+        backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+    }
+}
+function connectOnce(link, localMcpUrl, onOpen) {
+    return new Promise((resolve) => {
+        const wsUrl = link.cloudUrl.replace(/^http/, "ws") + "/agent";
+        const ws = new WebSocket(wsUrl, { headers: { authorization: `Bearer ${link.deviceToken}` } });
+        let ping;
+        ws.on("unexpected-response", (_req, res) => {
+            resolve(res.statusCode === 401 ? "unlinked" : "closed");
+            ws.terminate();
+        });
+        ws.on("open", () => {
+            onOpen();
+            console.error(`[anc] Connected to ${link.cloudUrl}`);
+            ping = setInterval(() => ws.readyState === WebSocket.OPEN && ws.send("ping"), PING_MS);
+        });
+        ws.on("message", async (data) => {
+            const text = data.toString();
+            if (text === "pong")
+                return;
+            const req = JSON.parse(text);
+            if (req.type !== "request")
+                return;
+            try {
+                const res = await fetch(localMcpUrl, {
+                    method: req.method,
+                    headers: req.headers,
+                    body: req.method === "GET" || req.method === "HEAD" ? undefined : req.body,
+                });
+                const headers = {};
+                res.headers.forEach((value, key) => {
+                    if (key === "content-type" || key.startsWith("mcp-"))
+                        headers[key] = value;
+                });
+                ws.send(JSON.stringify({ type: "response", id: req.id, status: res.status, headers, body: await res.text() }));
+            }
+            catch (e) {
+                ws.send(JSON.stringify({
+                    type: "response",
+                    id: req.id,
+                    status: 502,
+                    headers: { "content-type": "text/plain" },
+                    body: `Agentic Numerical Control on the PC could not handle the request: ${e.message}`,
+                }));
+            }
+        });
+        ws.on("close", () => {
+            clearInterval(ping);
+            console.error("[anc] Disconnected from the cloud; reconnecting.");
+            resolve("closed");
+        });
+        ws.on("error", (e) => console.error(`[anc] Cloud connection error: ${e.message}`));
+    });
+}

package/dist/server/server.js

@@ -0,0 +1,263 @@
+import { RESOURCE_MIME_TYPE, registerAppResource, registerAppTool, } from "@modelcontextprotocol/ext-apps/server";
+import { McpServer, } from "@modelcontextprotocol/server";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { currentJob, jobSummary, jobsDir, listJobFiles, loadJobFile, loadJobFromCncjs, loadJobText, parsedLineAt, } from "./jobs.js";
+import { ROOT, VERSION } from "./product.js";
+import { CNCJS_URL, cncjs } from "./cncjs.js";
+// The viewer follows whatever program CNCjs has loaded, including files
+// loaded from the CNCjs interface itself.
+cncjs.onGcodeLoad((name, gcode) => loadJobFromCncjs(name, gcode));
+const VIEWER_HTML = path.join(ROOT, "dist", "viewer.html");
+const VIEWER_URI = "ui://anc/viewer.html";
+// Base64 grows by 4/3: 384 KiB of binary is ~512 KiB per tool result, which
+// keeps each relayed message under the cloud WebSocket's 1 MiB limit.
+const CHUNK_BYTES = 384 * 1024;
+const MAX_LINES_PER_CALL = 500;
+function json(value) {
+    // The viewer reads the text block, not structuredContent: Claude Desktop has
+    // been reported to strip structuredContent for local servers.
+    return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}
+function fail(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+export function createServer() {
+    const server = new McpServer({ name: "agentic-numerical-control", version: VERSION });
+    registerAppTool(server, "anc_show_job", {
+        title: "Show CNC job",
+        description: "Open the Agentic Numerical Control 3D toolpath viewer for a G-code job. Pass `file` (a name from anc_list_jobs) or `gcode` text. " +
+            "With neither, re-opens the job already shown. Preview only: this never loads anything into CNCjs or moves the machine.",
+        inputSchema: z.object({
+            file: z.string().optional().describe("G-code file name in the Agentic Numerical Control jobs folder"),
+            gcode: z.string().optional().describe("G-code program text to preview"),
+            name: z.string().optional().describe("Display name when passing gcode text"),
+        }),
+        _meta: { ui: { resourceUri: VIEWER_URI } },
+    }, async ({ file, gcode, name }) => {
+        try {
+            const job = file
+                ? await loadJobFile(file)
+                : gcode
+                    ? loadJobText(name ?? "Untitled job", gcode)
+                    : currentJob();
+            if (!job) {
+                return fail("No job is loaded yet. Pass `file` or `gcode`; anc_list_jobs lists the files.");
+            }
+            return json({ job: jobSummary(job) });
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool("anc_list_jobs", {
+        title: "List CNC job files",
+        description: "List G-code files in the Agentic Numerical Control jobs folder that anc_show_job can open.",
+        inputSchema: z.object({}),
+    }, async () => {
+        try {
+            return json({ folder: jobsDir(), files: await listJobFiles() });
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    // ---- App-only tools: the viewer polls these directly, without a model turn.
+    registerAppTool(server, "anc_snapshot", {
+        title: "Viewer snapshot",
+        description: "Current job identity and machine link state for the Agentic Numerical Control viewer.",
+        inputSchema: z.object({}),
+        _meta: { ui: { visibility: ["app"] } },
+    }, async () => {
+        // Connect lazily; a failure is reported in machine.state, not thrown.
+        await cncjs.ensure().catch(() => { });
+        const job = currentJob();
+        const machine = cncjs.snapshot();
+        // Progress counts lines CNCjs has had acknowledged ("received"), not
+        // physical completion: the planner may still be executing them.
+        const tracking = job && machine.sender && machine.loadedFile === job.name;
+        return json({
+            job: job ? jobSummary(job) : null,
+            machine,
+            progress: tracking
+                ? {
+                    line: parsedLineAt(job, machine.sender.received),
+                    sent: machine.sender.sent,
+                    received: machine.sender.received,
+                    total: machine.sender.total,
+                    // CNCjs refreshes elapsedTime only when it sends a line; derive it
+                    // from startTime so it keeps counting while the planner is full.
+                    elapsedMs: machine.sender.startTime
+                        ? (machine.sender.finishTime || Date.now()) - machine.sender.startTime
+                        : 0,
+                }
+                : null,
+            cncjsUrl: CNCJS_URL,
+            serverTime: new Date().toISOString(),
+        });
+    });
+    registerAppTool(server, "anc_get_toolpath", {
+        title: "Get toolpath chunk",
+        description: "Packed toolpath geometry for the current job, base64 in chunks.",
+        inputSchema: z.object({
+            revision: z.number().int(),
+            chunk: z.number().int().min(0),
+        }),
+        _meta: { ui: { visibility: ["app"] } },
+    }, async ({ revision, chunk }) => {
+        const job = currentJob();
+        if (!job || job.revision !== revision) {
+            return fail(`Job revision ${revision} is no longer current.`);
+        }
+        const chunkCount = Math.max(1, Math.ceil(job.packed.byteLength / CHUNK_BYTES));
+        if (chunk >= chunkCount)
+            return fail(`Chunk ${chunk} out of range (${chunkCount}).`);
+        const slice = job.packed.subarray(chunk * CHUNK_BYTES, (chunk + 1) * CHUNK_BYTES);
+        return json({
+            revision,
+            chunk,
+            chunkCount,
+            totalBytes: job.packed.byteLength,
+            segmentCount: job.toolpath.motions.length,
+            lineCount: job.toolpath.lineEnds.length,
+            data: slice.toString("base64"),
+        });
+    });
+    registerAppTool(server, "anc_get_lines", {
+        title: "Get program lines",
+        description: "A window of G-code program lines for the current job.",
+        inputSchema: z.object({
+            revision: z.number().int(),
+            start: z.number().int().min(0),
+            count: z.number().int().min(1).max(MAX_LINES_PER_CALL),
+        }),
+        _meta: { ui: { visibility: ["app"] } },
+    }, async ({ revision, start, count }) => {
+        const job = currentJob();
+        if (!job || job.revision !== revision) {
+            return fail(`Job revision ${revision} is no longer current.`);
+        }
+        return json({ revision, start, lines: job.toolpath.lines.slice(start, start + count) });
+    });
+    // ---- Machine link and run control (shared by Claude and the viewer).
+    server.registerTool("anc_list_ports", {
+        title: "List machine ports",
+        description: "List serial ports CNCjs can see, to find the CNC controller.",
+        inputSchema: z.object({}),
+    }, async () => {
+        try {
+            return json({ ports: await cncjs.listPorts(), machine: cncjs.snapshot() });
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool("anc_connect_machine", {
+        title: "Connect machine",
+        description: "Open the CNC controller's serial port in CNCjs. This connects to the real machine; only call it when the user asks to connect.",
+        inputSchema: z.object({
+            port: z.string().describe("Serial port, e.g. COM3"),
+            baudrate: z.number().int().default(115200),
+            controller: z.enum(["Grbl", "Marlin", "Smoothie", "TinyG", "g2core"]).default("Grbl"),
+        }),
+    }, async ({ port, baudrate, controller }) => {
+        try {
+            await cncjs.openPort(port, baudrate, controller);
+            return json({ machine: cncjs.snapshot() });
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool("anc_disconnect_machine", {
+        title: "Disconnect machine",
+        description: "Close the machine's serial port in CNCjs.",
+        inputSchema: z.object({}),
+    }, async () => {
+        try {
+            await cncjs.closePort();
+            return json({ machine: cncjs.snapshot() });
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    registerAppTool(server, "anc_send_to_cncjs", {
+        title: "Load job into CNCjs",
+        description: "Load the job shown in Agentic Numerical Control into CNCjs's sender so it is ready to run. Does not start it.",
+        inputSchema: z.object({}),
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async () => {
+        const job = currentJob();
+        if (!job)
+            return fail("No job is shown in Agentic Numerical Control.");
+        try {
+            const busy = cncjs.snapshot().workflow;
+            if (busy !== "idle")
+                return fail(`CNCjs is ${busy}; stop the current job first.`);
+            await cncjs.load(job.name, job.gcode);
+            return json({ loaded: job.name, machine: cncjs.snapshot() });
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    registerAppTool(server, "anc_job_control", {
+        title: "Control CNC job",
+        description: "Start, pause, resume or stop the job loaded in CNCjs, or send feed hold, cycle start, unlock ($X), home ($H) or soft reset. " +
+            "This moves the real machine: only start or resume when the user explicitly asks. " +
+            "Soft reset is not an emergency stop; the physical E-stop is.",
+        inputSchema: z.object({
+            action: z.enum(["start", "pause", "resume", "stop", "feedhold", "cyclestart", "unlock", "home", "reset"]),
+        }),
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async ({ action }) => {
+        try {
+            const m = cncjs.snapshot();
+            if (action === "start") {
+                const job = currentJob();
+                if (m.link !== "live")
+                    return fail(`Not starting: machine status is not live (${m.state}).`);
+                if (m.activeState !== "Idle")
+                    return fail(`Not starting: machine is ${m.activeState}, not Idle.`);
+                if (m.workflow !== "idle")
+                    return fail(`Not starting: CNCjs workflow is ${m.workflow}.`);
+                if (!m.loadedFile)
+                    return fail("Not starting: no program is loaded in CNCjs.");
+                if (job && job.name !== m.loadedFile) {
+                    return fail(`Not starting: CNCjs has "${m.loadedFile}" loaded but Agentic Numerical Control is showing "${job.name}".`);
+                }
+            }
+            const command = {
+                start: "gcode:start",
+                pause: "gcode:pause",
+                resume: "gcode:resume",
+                stop: "gcode:stop",
+                feedhold: "feedhold",
+                cyclestart: "cyclestart",
+                unlock: "unlock",
+                home: "homing",
+                reset: "reset",
+            }[action];
+            if (action === "stop")
+                await cncjs.command(command, { force: true });
+            else
+                await cncjs.command(command);
+            return json({ sent: action, machine: cncjs.snapshot() });
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    registerAppResource(server, VIEWER_URI, VIEWER_URI, { mimeType: RESOURCE_MIME_TYPE, description: "Agentic Numerical Control toolpath viewer" }, async () => ({
+        contents: [
+            {
+                uri: VIEWER_URI,
+                mimeType: RESOURCE_MIME_TYPE,
+                text: await fs.readFile(VIEWER_HTML, "utf-8"),
+            },
+        ],
+    }));
+    return server;
+}

package/dist/server/toolpath.js

@@ -0,0 +1,123 @@
+// Turns G-code text into a flat segment list the viewer can draw directly.
+// Parsing runs here, in Node, because gcode-toolpath depends on Node's
+// fs/stream/events and cannot be bundled into the sandboxed app iframe.
+import Toolpath from "gcode-toolpath";
+export const MOTION_RAPID = 0;
+export const MOTION_FEED = 1;
+export const MOTION_ARC = 2;
+const ARC_DIVISIONS = 30;
+export function buildToolpath(gcode) {
+    const positions = [];
+    const motions = [];
+    const lineEnds = [];
+    const lines = [];
+    const feedRates = new Set();
+    const spindleSpeeds = new Set();
+    let units = "mm";
+    let cutLength = 0;
+    let rapidLength = 0;
+    const min = { x: Infinity, y: Infinity, z: Infinity };
+    const max = { x: -Infinity, y: -Infinity, z: -Infinity };
+    const push = (a, b, motion) => {
+        positions.push(a.x, a.y, a.z, b.x, b.y, b.z);
+        motions.push(motion);
+        for (const p of [a, b]) {
+            if (p.x < min.x)
+                min.x = p.x;
+            if (p.y < min.y)
+                min.y = p.y;
+            if (p.z < min.z)
+                min.z = p.z;
+            if (p.x > max.x)
+                max.x = p.x;
+            if (p.y > max.y)
+                max.y = p.y;
+            if (p.z > max.z)
+                max.z = p.z;
+        }
+        const len = Math.hypot(b.x - a.x, b.y - a.y, b.z - a.z);
+        if (motion === MOTION_RAPID)
+            rapidLength += len;
+        else
+            cutLength += len;
+    };
+    const toolpath = new Toolpath({
+        addLine: (modal, v1, v2) => {
+            push(v1, v2, modal.motion === "G0" ? MOTION_RAPID : MOTION_FEED);
+        },
+        // Same tessellation as CNCjs's GCodeVisualizer: 30 divisions, with the
+        // helical axis interpolated linearly across the arc.
+        addArcCurve: (modal, v1, v2, v0) => {
+            const clockwise = modal.motion === "G2";
+            const radius = Math.hypot(v1.x - v0.x, v1.y - v0.y);
+            let start = Math.atan2(v1.y - v0.y, v1.x - v0.x);
+            let end = Math.atan2(v2.y - v0.y, v2.x - v0.x);
+            if (start === end)
+                end += 2 * Math.PI;
+            // Normalise the sweep so it runs in the commanded direction.
+            let sweep = end - start;
+            if (clockwise && sweep > 0)
+                sweep -= 2 * Math.PI;
+            if (!clockwise && sweep < 0)
+                sweep += 2 * Math.PI;
+            let prev = null;
+            for (let i = 0; i <= ARC_DIVISIONS; i++) {
+                const t = i / ARC_DIVISIONS;
+                const a = start + sweep * t;
+                const px = v0.x + radius * Math.cos(a);
+                const py = v0.y + radius * Math.sin(a);
+                const pz = v1.z + (v2.z - v1.z) * t;
+                let p;
+                if (modal.plane === "G18")
+                    p = { x: py, y: pz, z: px };
+                else if (modal.plane === "G19")
+                    p = { x: pz, y: px, z: py };
+                else
+                    p = { x: px, y: py, z: pz };
+                if (prev)
+                    push(prev, p, MOTION_ARC);
+                prev = p;
+            }
+        },
+    });
+    toolpath.loadFromStringSync(gcode, (line) => {
+        for (const [letter, value] of line.words ?? []) {
+            if (letter === "F")
+                feedRates.add(value);
+            if (letter === "S")
+                spindleSpeeds.add(value);
+            if (letter === "G" && value === 20)
+                units = "inch";
+            if (letter === "G" && value === 21)
+                units = "mm";
+        }
+        lineEnds.push(motions.length);
+        lines.push(line.line);
+    });
+    return {
+        positions: Float32Array.from(positions),
+        motions: Uint8Array.from(motions),
+        lineEnds: Uint32Array.from(lineEnds),
+        lines,
+        bounds: motions.length ? { min, max } : null,
+        cutLength,
+        rapidLength,
+        feedRates: [...feedRates].sort((a, b) => a - b),
+        spindleSpeeds: [...spindleSpeeds].sort((a, b) => a - b),
+        units,
+    };
+}
+/**
+ * Packs the typed arrays into one buffer: positions, then lineEnds, then
+ * motions, so every view stays aligned without padding.
+ */
+export function packToolpath(tp) {
+    const total = tp.positions.byteLength + tp.lineEnds.byteLength + tp.motions.byteLength;
+    const buf = Buffer.alloc(total);
+    let offset = 0;
+    for (const arr of [tp.positions, tp.lineEnds, tp.motions]) {
+        Buffer.from(arr.buffer, arr.byteOffset, arr.byteLength).copy(buf, offset);
+        offset += arr.byteLength;
+    }
+    return buf;
+}

package/dist/server/update.js

@@ -0,0 +1,69 @@
+// Self-update for installed copies: on start, if npm has a newer version,
+// install it into the same place with the same Node, then relaunch.
+// Development checkouts (a .git folder at the root) never self-update.
+import { execFileSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { PRODUCT, ROOT, VERSION } from "./product.js";
+function newer(a, b) {
+    const pa = a.split(/[.-]/).map(Number);
+    const pb = b.split(/[.-]/).map(Number);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] ?? 0) !== (pb[i] ?? 0))
+            return (pa[i] ?? 0) > (pb[i] ?? 0);
+    }
+    return false;
+}
+/** The npm prefix this copy was installed into: .../node_modules/<name> -> ... */
+function installPrefix() {
+    const parts = ROOT.split(path.sep);
+    const i = parts.lastIndexOf("node_modules");
+    if (i < 0)
+        return null;
+    let prefix = parts.slice(0, i).join(path.sep);
+    if (process.platform !== "win32" && path.basename(prefix) === "lib")
+        prefix = path.dirname(prefix);
+    return prefix;
+}
+/** npm that ships with the Node running us. */
+function npmCli() {
+    const bin = path.dirname(process.execPath);
+    return process.platform === "win32"
+        ? path.join(bin, "node_modules", "npm", "bin", "npm-cli.js")
+        : path.join(bin, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js");
+}
+/** Returns true if a newer version was installed and started in our place. */
+export async function updateIfAvailable() {
+    if (fs.existsSync(path.join(ROOT, ".git")))
+        return false;
+    const prefix = installPrefix();
+    const npm = npmCli();
+    if (!prefix || !fs.existsSync(npm))
+        return false;
+    let latest;
+    try {
+        const res = await fetch(`https://registry.npmjs.org/${PRODUCT.name}/latest`, { signal: AbortSignal.timeout(5000) });
+        if (!res.ok)
+            return false;
+        latest = (await res.json()).version;
+    }
+    catch {
+        console.error(`[update] Could not reach npm to check for updates; staying on ${VERSION}.`);
+        return false;
+    }
+    if (!newer(latest, VERSION))
+        return false;
+    console.error(`[update] Updating ${VERSION} -> ${latest}`);
+    try {
+        execFileSync(process.execPath, [npm, "install", "-g", "--prefix", prefix, `${PRODUCT.name}@${latest}`], {
+            stdio: "inherit",
+        });
+    }
+    catch (e) {
+        console.error(`[update] Update failed (${e.message}); staying on ${VERSION}.`);
+        return false;
+    }
+    // The package was replaced in place; run the new copy with the same arguments.
+    spawn(process.execPath, process.argv.slice(1), { detached: true, stdio: "ignore", windowsHide: true }).unref();
+    return true;
+}