agentic-numerical-control 0.1.6 → 0.2.0

package/dist/server/cam.js

@@ -0,0 +1,592 @@
+// CAM: turning a 3D model into a G-code job with ANC's built-in Kiri:Moto
+// (engines/kiri, built into dist/engines/kiri). ANC owns only the settings
+// and the bookkeeping here; the toolpaths and G-code are Kiri:Moto's.
+//
+// Each generation runs in its own child process (the Kiri runner), which has
+// no link to CNCjs or the machine. A generated program is saved as an
+// ordinary job file in the jobs folder and is never loaded into CNCjs or run
+// by this code: the person reviews it in the viewer and loads it themselves.
+import { fork } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { STATE_DIR } from "./paths.js";
+import { JOBS_DIR, PRODUCT, ROOT, VERSION } from "./product.js";
+const ENGINE_DIR = path.join(ROOT, "dist", "engines", "kiri");
+const TOOLS_FILE = path.join(STATE_DIR, "tools.json");
+const CAM_JOBS_FILE = path.join(STATE_DIR, "cam-jobs.json");
+const MODEL_EXT = /\.stl$/i;
+/** A generation still running after this is stopped. */
+const GENERATE_TIMEOUT_MS = 10 * 60 * 1000;
+/** mm above the top of the stock for travel moves. */
+const SAFE_Z = 5;
+const INSPECT_TIMEOUT_MS = 60 * 1000;
+export function camEngine() {
+    try {
+        const m = JSON.parse(fs.readFileSync(path.join(ENGINE_DIR, "manifest.json"), "utf-8"));
+        return { name: m.upstream.name, version: m.upstream.version, commit: m.upstream.commit };
+    }
+    catch {
+        return null;
+    }
+}
+/** Starts the Kiri runner for one request. The process ends when the request does. */
+function runEngine(message, timeoutMs, onProgress) {
+    const manifest = path.join(ENGINE_DIR, "manifest.json");
+    if (!fs.existsSync(manifest))
+        throw new Error(`The built-in Kiri:Moto is missing (${ENGINE_DIR}). Run npm run build.`);
+    const entry = JSON.parse(fs.readFileSync(manifest, "utf-8")).entry;
+    // Only what Node needs: the CAM process gets nothing of ANC's own (tokens,
+    // the CNCjs address or secret).
+    const env = {};
+    for (const k of ["PATH", "Path", "SYSTEMROOT", "SystemRoot", "TEMP", "TMP", "TMPDIR", "HOME", "USERPROFILE", "LANG"]) {
+        if (process.env[k] !== undefined)
+            env[k] = process.env[k];
+    }
+    const child = fork(path.join(ENGINE_DIR, entry), [], {
+        cwd: path.dirname(path.join(ENGINE_DIR, entry)),
+        env,
+        // Plain Node: no loader or debugger flags from this process.
+        execArgv: [],
+        stdio: ["ignore", "pipe", "pipe", "ipc"],
+        windowsHide: true,
+    });
+    let log = "";
+    const keep = (d) => {
+        log = (log + d.toString()).slice(-4000);
+    };
+    child.stdout?.on("data", keep);
+    child.stderr?.on("data", keep);
+    const done = new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        const timer = setTimeout(() => {
+            child.kill();
+            finish(() => reject(new Error(`Kiri:Moto took longer than ${Math.round(timeoutMs / 60000)} minutes and was stopped.`)));
+        }, timeoutMs);
+        child.on("message", (m) => {
+            if (m?.type === "ready")
+                child.send(message);
+            else if (m?.type === "progress")
+                onProgress?.(Number(m.fraction) || 0, String(m.status ?? ""));
+            else if (m?.type === "result")
+                finish(() => resolve(m));
+            else if (m?.type === "error")
+                finish(() => reject(new Error(String(m.message))));
+        });
+        child.on("exit", (code, signal) => {
+            finish(() => reject(new Error(signal ? "Stopped." : `Kiri:Moto stopped unexpectedly (exit ${code}).${log ? ` Last output: ${log.trim().split("\n").slice(-3).join(" | ")}` : ""}`)));
+        });
+    });
+    return { child, done };
+}
+const stlCache = new Map();
+const TOP_CELLS = 72;
+/** Reads an STL (binary or text) for its size and a top view. Cached until the file changes. */
+function stlInfo(full) {
+    let stat;
+    try {
+        stat = fs.statSync(full);
+    }
+    catch {
+        return null;
+    }
+    const key = `${full}:${stat.size}:${stat.mtimeMs}`;
+    if (stlCache.has(key))
+        return stlCache.get(key);
+    let info = null;
+    try {
+        info = readStl(fs.readFileSync(full));
+    }
+    catch { }
+    stlCache.set(key, info);
+    return info;
+}
+function readStl(buf) {
+    let v;
+    const n = buf.length >= 84 ? buf.readUInt32LE(80) : -1;
+    if (n >= 0 && 84 + n * 50 === buf.length) {
+        v = new Float32Array(n * 9);
+        for (let i = 0; i < n; i++)
+            for (let j = 0; j < 9; j++)
+                v[i * 9 + j] = buf.readFloatLE(84 + i * 50 + 12 + j * 4);
+    }
+    else {
+        v = [];
+        for (const m of buf.toString("latin1").matchAll(/vertex\s+(\S+)\s+(\S+)\s+(\S+)/g))
+            v.push(Number(m[1]), Number(m[2]), Number(m[3]));
+    }
+    const tris = Math.floor(v.length / 9);
+    if (!tris)
+        return null;
+    const min = { x: Infinity, y: Infinity, z: Infinity };
+    const max = { x: -Infinity, y: -Infinity, z: -Infinity };
+    for (let i = 0; i < tris * 9; i += 3) {
+        min.x = Math.min(min.x, v[i]);
+        max.x = Math.max(max.x, v[i]);
+        min.y = Math.min(min.y, v[i + 1]);
+        max.y = Math.max(max.y, v[i + 1]);
+        min.z = Math.min(min.z, v[i + 2]);
+        max.z = Math.max(max.z, v[i + 2]);
+    }
+    if (![min.x, min.y, min.z, max.x, max.y, max.z].every(Number.isFinite))
+        return null;
+    // Highest point in each cell of a grid over the part, from the triangles' faces.
+    const sx = max.x - min.x || 1;
+    const sy = max.y - min.y || 1;
+    const cell = Math.max(sx, sy) / TOP_CELLS;
+    const w = Math.max(1, Math.ceil(sx / cell));
+    const h = Math.max(1, Math.ceil(sy / cell));
+    const top = new Float32Array(w * h).fill(-Infinity);
+    for (let t = 0; t < tris * 9; t += 9) {
+        const ax = (v[t] - min.x) / cell, ay = (v[t + 1] - min.y) / cell, az = v[t + 2];
+        const bx = (v[t + 3] - min.x) / cell, by = (v[t + 4] - min.y) / cell, bz = v[t + 5];
+        const cx = (v[t + 6] - min.x) / cell, cy = (v[t + 7] - min.y) / cell, cz = v[t + 8];
+        const d = (by - cy) * (ax - cx) + (cx - bx) * (ay - cy);
+        if (Math.abs(d) < 1e-12)
+            continue;
+        const i0 = Math.max(0, Math.floor(Math.min(ax, bx, cx))), i1 = Math.min(w - 1, Math.ceil(Math.max(ax, bx, cx)));
+        const j0 = Math.max(0, Math.floor(Math.min(ay, by, cy))), j1 = Math.min(h - 1, Math.ceil(Math.max(ay, by, cy)));
+        for (let j = j0; j <= j1; j++) {
+            for (let i = i0; i <= i1; i++) {
+                const px = i + 0.5, py = j + 0.5;
+                const l1 = ((by - cy) * (px - cx) + (cx - bx) * (py - cy)) / d;
+                const l2 = ((cy - ay) * (px - cx) + (ax - cx) * (py - cy)) / d;
+                const l3 = 1 - l1 - l2;
+                if (l1 < -1e-9 || l2 < -1e-9 || l3 < -1e-9)
+                    continue;
+                const z = l1 * az + l2 * bz + l3 * cz;
+                if (z > top[j * w + i])
+                    top[j * w + i] = z;
+            }
+        }
+    }
+    const sz = max.z - min.z || 1;
+    const rows = [];
+    for (let j = h - 1; j >= 0; j--) {
+        let row = "";
+        for (let i = 0; i < w; i++) {
+            const z = top[j * w + i];
+            row += z === -Infinity ? "." : String(Math.min(9, Math.floor(((z - min.z) / sz) * 10)));
+        }
+        rows.push(row);
+    }
+    return { triangles: tris, min, max, top: { w, h, rows } };
+}
+/** Jobs made from each model, from the records kept when they were generated. */
+function jobsByModel() {
+    const out = new Map();
+    let all = {};
+    try {
+        all = JSON.parse(fs.readFileSync(CAM_JOBS_FILE, "utf-8"));
+    }
+    catch { }
+    for (const [file, r] of Object.entries(all)) {
+        if (!r?.model?.file || !fs.existsSync(path.join(JOBS_DIR, file)))
+            continue;
+        const list = out.get(r.model.file) ?? [];
+        list.push({
+            file,
+            createdAt: r.createdAt,
+            units: r.model.units,
+            operations: Array.isArray(r.operations) ? r.operations.map((o) => o.type) : [],
+            tool: r.tools?.[0]?.name ?? null,
+            stock: r.stock ? { x: r.stock.x, y: r.stock.y, z: r.stock.z } : null,
+        });
+        out.set(r.model.file, list);
+    }
+    for (const list of out.values())
+        list.sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)));
+    return out;
+}
+/** STL files in the jobs folder, next to the G-code, with their size and the jobs made from them. */
+export function listModels(opts = {}) {
+    if (!fs.existsSync(JOBS_DIR))
+        return [];
+    const jobs = jobsByModel();
+    return fs
+        .readdirSync(JOBS_DIR, { withFileTypes: true })
+        .filter((e) => e.isFile() && MODEL_EXT.test(e.name))
+        .map((e) => {
+        const full = path.join(JOBS_DIR, e.name);
+        const stat = fs.statSync(full);
+        const info = stlInfo(full);
+        const made = jobs.get(e.name) ?? [];
+        const model = {
+            file: e.name,
+            bytes: stat.size,
+            modified: stat.mtime.toISOString(),
+            triangles: info?.triangles ?? null,
+            size: info ? { x: round(info.max.x - info.min.x), y: round(info.max.y - info.min.y), z: round(info.max.z - info.min.z) } : null,
+            units: made[0]?.units ?? null,
+            jobs: made.map(({ units: _, ...j }) => j),
+        };
+        if (opts.preview)
+            model.top = info?.top ?? null;
+        return model;
+    })
+        .sort((a, b) => a.file.localeCompare(b.file));
+}
+/** Resolves a model name to an STL file directly in the jobs folder; anything else is refused. */
+function modelPath(file) {
+    const resolved = path.resolve(JOBS_DIR, file);
+    if (path.dirname(resolved) !== JOBS_DIR || !MODEL_EXT.test(resolved) || !fs.existsSync(resolved)) {
+        throw new Error(`"${file}" is not an STL file in the ${PRODUCT.displayName} jobs folder (${JOBS_DIR}). anc_list_models lists them.`);
+    }
+    return resolved;
+}
+const round = (n, d = 3) => Math.round(n * 10 ** d) / 10 ** d;
+/**
+ * Size of a model. STL files carry no units, so both readings are given and
+ * the person has to say which is right before anything is generated.
+ */
+export async function inspectModel(file) {
+    const full = modelPath(file);
+    const r = await runEngine({ type: "inspect", model: full }, INSPECT_TIMEOUT_MS).done;
+    const s = r.size;
+    const mm = { x: round(s.x), y: round(s.y), z: round(s.z) };
+    const fromInches = { x: round(s.x * 25.4, 2), y: round(s.y * 25.4, 2), z: round(s.z * 25.4, 2) };
+    const largest = Math.max(s.x, s.y, s.z);
+    return {
+        file,
+        bytes: fs.statSync(full).size,
+        triangles: r.triangles,
+        size: s,
+        ifMillimetres: mm,
+        ifInches: fromInches,
+        unitsNote: "STL files don't record units. Ask the person whether this model is in millimetres or inches before generating" +
+            (largest < 20 ? "; it is small for millimetres, so it may be inches." : largest > 600 ? "; it is large for inches." : "."),
+        engine: `${r.engine} ${r.version}`,
+    };
+}
+export function listTools() {
+    try {
+        const tools = JSON.parse(fs.readFileSync(TOOLS_FILE, "utf-8"));
+        return Array.isArray(tools) ? tools : [];
+    }
+    catch {
+        return [];
+    }
+}
+function writeTools(tools) {
+    fs.mkdirSync(STATE_DIR, { recursive: true });
+    fs.writeFileSync(TOOLS_FILE, JSON.stringify(tools, null, 2));
+}
+export function saveTool(input) {
+    const tools = listTools();
+    if (!(input.diameter > 0 && input.diameter < 100))
+        throw new Error("Tool diameter must be between 0 and 100 mm.");
+    if (!(input.fluteLength > 0 && input.fluteLength < 300))
+        throw new Error("Flute length must be between 0 and 300 mm.");
+    if (input.type === "vbit" && !(input.angle && input.angle > 0 && input.angle < 180))
+        throw new Error("A V-bit needs its angle (degrees).");
+    const existing = input.id !== undefined ? tools.find((t) => t.id === input.id) : undefined;
+    if (input.id !== undefined && !existing)
+        throw new Error(`No tool with id ${input.id}.`);
+    const id = existing?.id ?? Math.max(0, ...tools.map((t) => t.id)) + 1;
+    const tool = {
+        id,
+        number: input.number ?? existing?.number ?? id,
+        name: input.name.trim() || `${input.diameter} mm ${input.type}`,
+        type: input.type,
+        diameter: input.diameter,
+        fluteLength: input.fluteLength,
+        shankDiameter: input.shankDiameter ?? existing?.shankDiameter ?? input.diameter,
+        angle: input.type === "vbit" ? (input.angle ?? null) : null,
+    };
+    writeTools([...tools.filter((t) => t.id !== id), tool].sort((a, b) => a.id - b.id));
+    return tool;
+}
+export function removeTool(id) {
+    const tools = listTools();
+    if (!tools.some((t) => t.id === id))
+        throw new Error(`No tool with id ${id}.`);
+    writeTools(tools.filter((t) => t.id !== id));
+}
+/** A tool as Kiri:Moto describes one (src/kiri/app/conf/defaults.js, template.tools). */
+function kiriTool(t) {
+    const type = { flat: "endmill", ball: "ballmill", vbit: "tapermill", drill: "drill" }[t.type];
+    return {
+        id: t.id,
+        number: t.number,
+        type,
+        name: t.name,
+        metric: true,
+        shaft_diam: t.shankDiameter,
+        shaft_len: 20,
+        flute_diam: t.diameter,
+        flute_len: t.fluteLength,
+        taper_tip: 0,
+        // Kiri's taper_angle is measured from the tool's axis: half the included angle.
+        ...(t.type === "vbit" ? { taper_angle: (t.angle ?? 90) / 2 } : {}),
+    };
+}
+/** Grbl's $130-$132 travel, $30 spindle and $110-$112 rates, when the controller reported them. */
+export function camMachine(settings) {
+    const n = (k) => {
+        const v = Number(settings?.[`$${k}`]);
+        return Number.isFinite(v) && v > 0 ? v : null;
+    };
+    const travel = n(130) && n(131) && n(132) ? { x: n(130), y: n(131), z: n(132) } : null;
+    return {
+        travel: travel ?? { x: 300, y: 300, z: 80 },
+        spindleMax: n(30) ?? 24000,
+        maxFeed: n(110) && n(111) && n(112) ? { xy: Math.min(n(110), n(111)), z: n(112) } : null,
+        source: travel ? "machine" : "assumed",
+    };
+}
+/**
+ * The G-code dialect for Grbl and grblHAL. Kiri's own Grbl profile has no
+ * spindle command and starts with M6, which Grbl refuses; this one turns the
+ * spindle on with M3, off with M5 at the end, and never sends M6.
+ */
+function grblDevice(machine) {
+    return {
+        mode: "CAM",
+        internal: 0,
+        deviceName: "Grbl (Agentic Numerical Control)",
+        bedWidth: machine.travel.x,
+        bedDepth: machine.travel.y,
+        maxHeight: machine.travel.z,
+        spindleMax: machine.spindleMax,
+        gcodePre: ["G21", "G90", "G17"],
+        gcodePost: ["M5", "M30"],
+        gcodeSpindle: ["M3 S{speed}"],
+        gcodeDwell: ["G4 P{time}"],
+        gcodeChange: ["M5", "M0"],
+        gcodeFExt: "nc",
+        gcodeSpace: true,
+        gcodeStrip: true,
+    };
+}
+/** ANC's names for an operation's settings, as the fields Kiri:Moto's operation takes. */
+function kiriOp(op) {
+    const common = { tool: op.tool, spindle: op.spindle, rate: op.feed };
+    switch (op.type) {
+        case "rough":
+            return {
+                type: "rough",
+                ...common,
+                down: op.stepDown,
+                step: op.stepOver,
+                plunge: op.plunge,
+                leave: op.leave ?? 0,
+                all: (op.area ?? "all") === "all",
+                inside: op.area === "inside",
+                direction: op.direction ?? "climb",
+            };
+        case "outline":
+            return {
+                type: "outline",
+                ...common,
+                down: op.stepDown,
+                plunge: op.plunge,
+                outside: (op.side ?? "outside") === "outside",
+                inside: op.side === "inside",
+                direction: op.direction ?? "climb",
+            };
+        case "contour":
+            return { type: "contour", ...common, step: op.stepOver, leave: op.leave ?? 0, axis: op.axis ?? "X" };
+    }
+}
+/** Refuses settings that can't be right; returns warnings for ones worth a second look. */
+function checkOperations(ops, tools, machine) {
+    const warnings = [];
+    if (!ops.length)
+        throw new Error("Give at least one operation.");
+    const used = new Set(ops.map((o) => o.tool));
+    if (used.size > 1) {
+        throw new Error("One tool per job for now: generate a separate job for each tool, so each tool change is done by hand between jobs.");
+    }
+    for (const [i, op] of ops.entries()) {
+        const label = `Operation ${i + 1} (${op.type})`;
+        const tool = tools.find((t) => t.id === op.tool);
+        if (!tool)
+            throw new Error(`${label}: no tool with id ${op.tool}. anc_save_tool adds one.`);
+        if (tool.type !== "flat" && tool.type !== "ball")
+            throw new Error(`${label}: ${op.type} needs a flat or ball end mill, not a ${tool.type}.`);
+        if (op.type !== "contour") {
+            if (!(op.stepDown && op.stepDown > 0))
+                throw new Error(`${label}: stepDown (mm per pass) is required.`);
+            if (!(op.plunge && op.plunge > 0))
+                throw new Error(`${label}: plunge (mm/min) is required.`);
+            if (op.stepDown > tool.fluteLength)
+                throw new Error(`${label}: stepDown ${op.stepDown} mm is more than the tool's ${tool.fluteLength} mm flute length.`);
+            if (op.stepDown > tool.diameter)
+                warnings.push(`${label}: stepDown ${op.stepDown} mm is more than the tool diameter (${tool.diameter} mm); that is a heavy cut for most hobby machines.`);
+        }
+        if (op.type !== "outline") {
+            if (!(op.stepOver && op.stepOver >= 0.05 && op.stepOver <= 1))
+                throw new Error(`${label}: stepOver must be a fraction of the tool diameter between 0.05 and 1.`);
+        }
+        if (!(op.feed > 0))
+            throw new Error(`${label}: feed (mm/min) is required.`);
+        if (!(op.spindle > 0))
+            throw new Error(`${label}: spindle speed (rpm) is required.`);
+        if (op.spindle > machine.spindleMax)
+            warnings.push(`${label}: spindle ${op.spindle} rpm is above the machine's maximum (${machine.spindleMax}).`);
+        if (machine.maxFeed && op.feed > machine.maxFeed.xy)
+            warnings.push(`${label}: feed ${op.feed} mm/min is above the machine's maximum rate (${machine.maxFeed.xy}).`);
+        if (machine.maxFeed && op.plunge && op.plunge > machine.maxFeed.z)
+            warnings.push(`${label}: plunge ${op.plunge} mm/min is above the machine's Z maximum (${machine.maxFeed.z}).`);
+    }
+    return warnings;
+}
+const camJobs = new Map();
+function publicJob(j) {
+    const { id, model, state, progress, status, startedAt, finishedAt, file, warnings, error, setup } = j;
+    return { id, model, state, progress: round(progress, 2), status, startedAt, finishedAt, file, warnings, error, setup };
+}
+function freeName(base) {
+    const clean = base.replace(/\.[^.]+$/, "").replace(/[^\w.\- ]+/g, "_").trim() || "job";
+    let name = `${clean}.nc`;
+    for (let i = 2; fs.existsSync(path.join(JOBS_DIR, name)); i++)
+        name = `${clean}-${i}.nc`;
+    return name;
+}
+function recordCamJob(file, meta) {
+    let all = {};
+    try {
+        all = JSON.parse(fs.readFileSync(CAM_JOBS_FILE, "utf-8"));
+    }
+    catch { }
+    all[file] = meta;
+    try {
+        fs.mkdirSync(STATE_DIR, { recursive: true });
+        fs.writeFileSync(CAM_JOBS_FILE, JSON.stringify(all, null, 2));
+    }
+    catch { }
+}
+/** How a generated job was made: model, units, stock, tools, operations and engine. */
+export function camJobInfo(file) {
+    try {
+        return JSON.parse(fs.readFileSync(CAM_JOBS_FILE, "utf-8"))[file] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Starts generating; returns at once with the job's id. */
+export async function startGenerate(req, machine) {
+    const modelFull = modelPath(req.model);
+    const engine = camEngine();
+    if (!engine)
+        throw new Error("The built-in Kiri:Moto is missing. Run npm run build.");
+    if (req.units !== "mm" && req.units !== "in")
+        throw new Error('units must be "mm" or "in"; ask the person which the model is in.');
+    const tools = listTools();
+    const warnings = checkOperations(req.operations, tools, machine);
+    const usedTools = tools.filter((t) => req.operations.some((o) => o.tool === t.id));
+    const size = (await inspectModel(req.model)).size;
+    const scale = req.units === "in" ? 25.4 : 1;
+    const part = { x: round(size.x * scale), y: round(size.y * scale), z: round(size.z * scale) };
+    const stock = req.stock ?? { x: round(part.x + 10), y: round(part.y + 10), z: part.z };
+    if (stock.x + 1e-3 < part.x || stock.y + 1e-3 < part.y || stock.z + 1e-3 < part.z) {
+        throw new Error(`The stock (${stock.x} x ${stock.y} x ${stock.z} mm) is smaller than the part (${part.x} x ${part.y} x ${part.z} mm).`);
+    }
+    if (stock.x > machine.travel.x || stock.y > machine.travel.y) {
+        warnings.push(`The stock (${stock.x} x ${stock.y} mm) is bigger than the machine's work area (${machine.travel.x} x ${machine.travel.y} mm${machine.source === "assumed" ? ", assumed: no machine has reported its travel" : ""}).`);
+    }
+    const origin = req.origin ?? "front-left";
+    const id = crypto.randomUUID().slice(0, 8);
+    const job = {
+        id,
+        model: req.model,
+        state: "running",
+        progress: 0,
+        status: "starting",
+        startedAt: new Date().toISOString(),
+        finishedAt: null,
+        file: null,
+        warnings,
+        error: null,
+        setup: null,
+    };
+    camJobs.set(id, job);
+    const runner = runEngine({
+        type: "generate",
+        job: {
+            model: modelFull,
+            units: req.units,
+            stock,
+            origin,
+            device: grblDevice(machine),
+            tools: usedTools.map(kiriTool),
+            // One tool, set up by hand before the job: no tool change at the start.
+            // Travel 5 mm above the stock rather than Kiri's 1 mm, to clear clamps
+            // and uneven stock.
+            process: { camToolInit: false, camZClearance: SAFE_Z, ops: req.operations.map(kiriOp) },
+        },
+    }, GENERATE_TIMEOUT_MS, (fraction, status) => {
+        job.progress = Math.max(job.progress, Math.min(1, fraction));
+        if (status)
+            job.status = status;
+    });
+    job.child = runner.child;
+    job.done = runner.done.then((r) => {
+        const file = freeName(req.name ?? req.model);
+        const t = usedTools[0];
+        const setup = `Zero X and Y at the ${origin === "center" ? "centre" : "front-left corner"} of the stock and Z on the top of the stock. ` +
+            `Stock ${stock.x} x ${stock.y} x ${stock.z} mm. Tool: ${t.name} (${t.diameter} mm ${t.type}).`;
+        const header = [
+            `; ${PRODUCT.displayName} ${VERSION}, toolpaths by ${engine.name} ${engine.version} (${engine.commit.slice(0, 12)})`,
+            `; Model: ${req.model} (${req.units}), part ${part.x} x ${part.y} x ${part.z} mm`,
+            `; ${setup}`,
+            `; Operations: ${req.operations.map((o) => o.type).join(", ")}`,
+            `; Travel moves at Z ${SAFE_Z}.` +
+                (r.info?.linksAsCuts ? ` ${r.info.linksAsCuts} linking moves inside the stock are feed moves (G1) instead of rapids.` : ""),
+            "; Check this program in the viewer before running it, and run an air cut first on a new setup.",
+        ];
+        fs.writeFileSync(path.join(JOBS_DIR, file), header.join("\n") + "\n" + String(r.gcode).replace(/\r\n/g, "\n").trimEnd() + "\n");
+        const modelHash = crypto.createHash("sha256").update(fs.readFileSync(modelFull)).digest("hex");
+        recordCamJob(file, {
+            createdAt: new Date().toISOString(),
+            model: { file: req.model, sha256: modelHash, units: req.units, part },
+            stock,
+            origin,
+            machine,
+            tools: usedTools,
+            operations: req.operations,
+            engine,
+            output: { safeZ: SAFE_Z, linksAsCuts: r.info?.linksAsCuts ?? 0 },
+            app: VERSION,
+        });
+        if (r.info?.alert)
+            job.warnings.push(`Kiri:Moto: ${r.info.alert}`);
+        Object.assign(job, { state: "done", progress: 1, status: "done", file, setup, finishedAt: new Date().toISOString() });
+        return publicJob(job);
+    }, (e) => {
+        if (job.state === "running")
+            Object.assign(job, { state: "failed", error: e.message, finishedAt: new Date().toISOString() });
+        return publicJob(job);
+    });
+    return publicJob(job);
+}
+/** Waits up to `ms` for a generation to finish, then reports where it is. */
+export async function waitForCamJob(id, ms) {
+    const job = camJobs.get(id);
+    if (!job)
+        throw new Error(`No CAM job ${id}.`);
+    if (job.done)
+        await Promise.race([job.done, new Promise((r) => setTimeout(r, ms))]);
+    return publicJob(job);
+}
+export function cancelCamJob(id) {
+    const job = camJobs.get(id);
+    if (!job)
+        throw new Error(`No CAM job ${id}.`);
+    if (job.state === "running") {
+        Object.assign(job, { state: "cancelled", status: "cancelled", finishedAt: new Date().toISOString() });
+        job.child?.kill();
+    }
+    return publicJob(job);
+}
+export function listCamJobs() {
+    return [...camJobs.values()].map(publicJob).slice(-20);
+}