mcp-3d-printer-server 1.2.5 → 1.2.11

package/dist/printers/creality.d.ts

@@ -1,10 +1,19 @@
-import { PrinterImplementation } from "../types.js";
-export declare class CrealityImplementation extends PrinterImplementation {
+import { GenericPrinterImplementation, type GenericPrinterState } from "./generic-base.js";
+/**
+ * Note: this adapter's /api/device, /api/storage and /api/job routes are not a
+ * documented Creality API. Readiness fails closed unless the response carries
+ * a recognized idle state; remote starts are refused because no download
+ * route is verified.
+ */
+export declare class CrealityImplementation extends GenericPrinterImplementation {
+    protected readonly printerLabel = "Creality";
+    protected readPrinterState(host: string, port: string, apiKey: string): Promise<GenericPrinterState>;
     getStatus(host: string, port: string, apiKey: string): Promise<any>;
     getFiles(host: string, port: string, apiKey: string): Promise<any>;
     getFile(host: string, port: string, apiKey: string, filename: string): Promise<any>;
-    uploadFile(host: string, port: string, apiKey: string, filePath: string, filename: string, print: boolean): Promise<any>;
-    startJob(host: string, port: string, apiKey: string, filename: string): Promise<any>;
-    cancelJob(host: string, port: string, apiKey: string): Promise<any>;
-    setTemperature(host: string, port: string, apiKey: string, component: string, temperature: number): Promise<any>;
+    protected uploadSucceeded(data: any): boolean;
+    protected rawUploadFile(host: string, port: string, apiKey: string, filePath: string, filename: string, print: boolean): Promise<any>;
+    protected rawStartJob(host: string, port: string, apiKey: string, filename: string): Promise<any>;
+    protected rawCancelJob(host: string, port: string, apiKey: string): Promise<any>;
+    protected rawSetTemperature(host: string, port: string, apiKey: string, component: string, temperature: number): Promise<any>;
 }

package/dist/printers/creality.js

@@ -1,7 +1,39 @@
-import { PrinterImplementation } from "../types.js";
+import { GenericPrinterImplementation } from "./generic-base.js";
 import fs from "fs";
 import FormData from "form-data";
-export class CrealityImplementation extends PrinterImplementation {
+const IDLE_STATES = new Set(["idle", "ready", "standby", "operational"]);
+const FINISHED_STATES = new Set(["complete", "completed", "finished", "finish", "cancelled", "canceled", "stopped"]);
+/**
+ * Note: this adapter's /api/device, /api/storage and /api/job routes are not a
+ * documented Creality API. Readiness fails closed unless the response carries
+ * a recognized idle state; remote starts are refused because no download
+ * route is verified.
+ */
+export class CrealityImplementation extends GenericPrinterImplementation {
+    constructor() {
+        super(...arguments);
+        this.printerLabel = "Creality";
+    }
+    async readPrinterState(host, port, apiKey) {
+        let data;
+        try {
+            data = (await this.apiClient.get(`http://${host}:${port}/api/device/status`, { headers: { "Authorization": `Bearer ${apiKey}` } })).data;
+        }
+        catch (error) {
+            throw new Error(`Cannot read Creality printer state; nothing was sent: ${error.message}`);
+        }
+        const candidates = [data?.state, data?.status, data?.printStatus, data?.print_state, data?.data?.state, data?.data?.status];
+        const raw = candidates.find((value) => typeof value === "string" && value.trim());
+        if (typeof raw !== "string") {
+            throw new Error("Creality did not report a recognizable printer state; cannot verify the printer is idle.");
+        }
+        const state = raw.trim().toLowerCase();
+        if (IDLE_STATES.has(state))
+            return { state, ready: true };
+        if (FINISHED_STATES.has(state))
+            return { state, ready: true, finishedJob: JSON.stringify([state]) };
+        return { state, ready: false, reason: `state is ${state}` };
+    }
     async getStatus(host, port, apiKey) {
         const url = `http://${host}:${port}/api/device/status`;
         const response = await this.apiClient.get(url, {
@@ -29,7 +61,10 @@ export class CrealityImplementation extends PrinterImplementation {
         });
         return response.data;
     }
-    async uploadFile(host, port, apiKey, filePath, filename, print) {
+    uploadSucceeded(data) {
+        return !!data?.success;
+    }
+    async rawUploadFile(host, port, apiKey, filePath, filename, print) {
         const url = `http://${host}:${port}/api/storage/upload`;
         const formData = new FormData();
         formData.append("file", fs.createReadStream(filePath));
@@ -40,12 +75,10 @@ export class CrealityImplementation extends PrinterImplementation {
                 ...formData.getHeaders()
             }
         });
-        if (print && response.data.success) {
-            await this.startJob(host, port, apiKey, filename);
-        }
+        // Printing is started by the shared gate only after a fresh state recheck.
         return response.data;
     }
-    async startJob(host, port, apiKey, filename) {
+    async rawStartJob(host, port, apiKey, filename) {
         const url = `http://${host}:${port}/api/job/start`;
         const response = await this.apiClient.post(url, {
             filename: filename
@@ -57,7 +90,7 @@ export class CrealityImplementation extends PrinterImplementation {
         });
         return response.data;
     }
-    async cancelJob(host, port, apiKey) {
+    async rawCancelJob(host, port, apiKey) {
         const url = `http://${host}:${port}/api/job/cancel`;
         const response = await this.apiClient.post(url, {}, {
             headers: {
@@ -67,7 +100,7 @@ export class CrealityImplementation extends PrinterImplementation {
         });
         return response.data;
     }
-    async setTemperature(host, port, apiKey, component, temperature) {
+    async rawSetTemperature(host, port, apiKey, component, temperature) {
         const url = `http://${host}:${port}/api/printer/temperature`;
         let data = {};
         if (component === "bed") {

package/dist/printers/duet.d.ts

@@ -1,10 +1,15 @@
-import { PrinterImplementation } from "../types.js";
-export declare class DuetImplementation extends PrinterImplementation {
+import { GenericPrinterImplementation, type GenericPrinterState } from "./generic-base.js";
+export declare class DuetImplementation extends GenericPrinterImplementation {
+    protected readonly printerLabel = "Duet";
+    private code;
     getStatus(host: string, port: string, apiKey: string): Promise<any>;
     getFiles(host: string, port: string, apiKey: string): Promise<any>;
     getFile(host: string, port: string, apiKey: string, filename: string): Promise<any>;
-    uploadFile(host: string, port: string, apiKey: string, filePath: string, filename: string, print: boolean): Promise<any>;
-    startJob(host: string, port: string, apiKey: string, filename: string): Promise<any>;
-    cancelJob(host: string, port: string, apiKey: string): Promise<any>;
-    setTemperature(host: string, port: string, apiKey: string, component: string, temperature: number): Promise<any>;
+    /** Object model state.status: only "idle" can start a job or heat. */
+    protected readPrinterState(host: string, port: string, apiKey: string): Promise<GenericPrinterState>;
+    protected downloadRemoteFile(host: string, port: string, apiKey: string, filename: string, destination: string): Promise<void>;
+    protected rawUploadFile(host: string, port: string, apiKey: string, filePath: string, filename: string, print: boolean): Promise<any>;
+    protected rawStartJob(host: string, port: string, apiKey: string, filename: string): Promise<any>;
+    protected rawCancelJob(host: string, port: string, apiKey: string): Promise<any>;
+    protected rawSetTemperature(host: string, port: string, apiKey: string, component: string, temperature: number): Promise<any>;
 }

package/dist/printers/duet.js

@@ -1,14 +1,38 @@
-import { PrinterImplementation } from "../types.js";
 import fs from "fs";
-import FormData from "form-data";
-export class DuetImplementation extends PrinterImplementation {
+import { GenericPrinterImplementation } from "./generic-base.js";
+/**
+ * Duet Software Framework (DuetWebServer) REST routes, verified against
+ * DuetSoftwareFramework src/DuetWebServer/Controllers/MachineController.cs:
+ * GET status, POST code (raw text body), GET/PUT file/{*filename},
+ * GET directory/{*directory}. Standalone RepRapFirmware rr_* routes are not
+ * supported by this adapter.
+ */
+function duetPath(filename) {
+    const name = filename.trim();
+    if (/^\d+:\//.test(name))
+        return name;
+    if (name.startsWith("/"))
+        return `0:${name}`;
+    return `0:/gcodes/${name}`;
+}
+export class DuetImplementation extends GenericPrinterImplementation {
+    constructor() {
+        super(...arguments);
+        this.printerLabel = "Duet";
+    }
+    async code(host, port, code) {
+        const response = await this.apiClient.post(`http://${host}:${port}/machine/code`, code, {
+            headers: { "Content-Type": "text/plain" },
+        });
+        return response.data;
+    }
     async getStatus(host, port, apiKey) {
         const url = `http://${host}:${port}/machine/status`;
         const response = await this.apiClient.get(url);
         return response.data;
     }
     async getFiles(host, port, apiKey) {
-        const url = `http://${host}:${port}/machine/file-list`;
+        const url = `http://${host}:${port}/machine/directory/${encodeURIComponent("0:/gcodes")}`;
         const response = await this.apiClient.get(url);
         return response.data;
     }
@@ -17,37 +41,39 @@ export class DuetImplementation extends PrinterImplementation {
         const response = await this.apiClient.get(url);
         return response.data;
     }
-    async uploadFile(host, port, apiKey, filePath, filename, print) {
-        const url = `http://${host}:${port}/machine/file-upload`;
-        const formData = new FormData();
-        formData.append("file", fs.createReadStream(filePath));
-        formData.append("filename", filename);
-        const response = await this.apiClient.post(url, formData, {
-            headers: {
-                ...formData.getHeaders()
-            }
-        });
-        if (print && response.data.err === 0) {
-            await this.startJob(host, port, apiKey, filename);
+    /** Object model state.status: only "idle" can start a job or heat. */
+    async readPrinterState(host, port, apiKey) {
+        let data;
+        try {
+            data = (await this.apiClient.get(`http://${host}:${port}/machine/status`)).data;
         }
-        return response.data;
+        catch (error) {
+            throw new Error(`Cannot read Duet object model state; nothing was sent: ${error.message}`);
+        }
+        const status = data?.state?.status ?? data?.result?.state?.status;
+        if (typeof status !== "string" || !status) {
+            throw new Error("Duet did not report state.status; cannot verify the printer is idle.");
+        }
+        return { state: status, ready: status === "idle", reason: status === "idle" ? undefined : `state.status is ${status}` };
     }
-    async startJob(host, port, apiKey, filename) {
-        const url = `http://${host}:${port}/machine/code`;
-        const response = await this.apiClient.post(url, {
-            code: `M32 "${filename}"`
-        });
-        return response.data;
+    async downloadRemoteFile(host, port, apiKey, filename, destination) {
+        await this.downloadToFile(`http://${host}:${port}/machine/file/${encodeURIComponent(duetPath(filename))}`, {}, destination);
     }
-    async cancelJob(host, port, apiKey) {
-        const url = `http://${host}:${port}/machine/code`;
-        const response = await this.apiClient.post(url, {
-            code: "M0"
+    async rawUploadFile(host, port, apiKey, filePath, filename, print) {
+        const url = `http://${host}:${port}/machine/file/${encodeURIComponent(duetPath(filename))}`;
+        const response = await this.apiClient.put(url, fs.createReadStream(filePath), {
+            headers: { "Content-Type": "application/octet-stream", "Content-Length": String((await fs.promises.stat(filePath)).size) },
         });
-        return response.data;
+        // Printing is started by the shared gate only after a fresh state recheck.
+        return response.data ?? { uploaded: true };
     }
-    async setTemperature(host, port, apiKey, component, temperature) {
-        const url = `http://${host}:${port}/machine/code`;
+    async rawStartJob(host, port, apiKey, filename) {
+        return this.code(host, port, `M32 "${duetPath(filename)}"`);
+    }
+    async rawCancelJob(host, port, apiKey) {
+        return this.code(host, port, "M0");
+    }
+    async rawSetTemperature(host, port, apiKey, component, temperature) {
         let gcode;
         if (component === "bed") {
             gcode = `M140 S${temperature}`;
@@ -58,9 +84,6 @@ export class DuetImplementation extends PrinterImplementation {
         else {
             throw new Error(`Unsupported component: ${component}`);
         }
-        const response = await this.apiClient.post(url, {
-            code: gcode
-        });
-        return response.data;
+        return this.code(host, port, gcode);
     }
 }

package/dist/printers/generic-base.d.ts

@@ -0,0 +1,69 @@
+import type { AxiosInstance } from "axios";
+import { PrinterImplementation } from "../types.js";
+import { type ConfirmHardware } from "../safety/confirmation.js";
+import { type PrintSafetyOptions } from "../safety/expected-peaks.js";
+import { type Heater } from "../safety/gcode-thermal.js";
+/** Normalized adapter state used by the print and heating preflight. */
+export interface GenericPrinterState {
+    /** Adapter-reported state text. */
+    state: string;
+    /** Idle enough to start a job or heat: not printing, paused, busy, errored or offline. */
+    ready: boolean;
+    /** Why the printer is not ready. */
+    reason?: string;
+    /** Set when the printer explicitly reports a finished or cancelled job that may still be on the bed. */
+    finishedJob?: string;
+}
+export interface HeaterComponent {
+    heater: Heater;
+    /** Component name passed to the adapter's raw transport. */
+    raw: string;
+}
+/** Download timeout for remote-start inspection; the shared client times out at 10 s. */
+export declare const REMOTE_DOWNLOAD_TIMEOUT_MS = 120000;
+/**
+ * Shared print and heating gate for non-Bambu adapters. Public mutations
+ * validate every input before connecting, inspect the exact bytes that are
+ * uploaded, check fresh adapter state, ask a human (MCP elicitation), recheck
+ * state and only then dispatch. Heater-off and cancel are never gated.
+ */
+export declare abstract class GenericPrinterImplementation extends PrinterImplementation {
+    private readonly confirm?;
+    protected abstract readonly printerLabel: string;
+    /** True when rawUploadFile(print=true) starts the uploaded bytes atomically. */
+    protected readonly uploadStartsPrint: boolean;
+    constructor(apiClient: AxiosInstance, confirm?: ConfirmHardware | undefined);
+    protected abstract rawUploadFile(host: string, port: string, apiKey: string, filePath: string, filename: string, print: boolean): Promise<any>;
+    protected abstract rawStartJob(host: string, port: string, apiKey: string, filename: string): Promise<any>;
+    protected abstract rawCancelJob(host: string, port: string, apiKey: string): Promise<any>;
+    protected abstract rawSetTemperature(host: string, port: string, apiKey: string, component: string, temperature: number): Promise<any>;
+    /** Throw when the state cannot be read; never guess. */
+    protected abstract readPrinterState(host: string, port: string, apiKey: string): Promise<GenericPrinterState>;
+    /**
+     * Download a printer-side file for inspection. Adapters without a verified
+     * download route leave this undefined and remote starts are refused.
+     */
+    protected downloadRemoteFile?(host: string, port: string, apiKey: string, filename: string, destination: string): Promise<void>;
+    /** Adapter-specific upload acknowledgement for the upload-then-start route. */
+    protected uploadSucceeded(_data: unknown): boolean;
+    /** Adapter-specific acknowledgement that an atomic upload-and-print started. */
+    protected uploadStartedPrint(_data: unknown): boolean;
+    /** Map caller component names to a heater and the raw adapter name. */
+    protected heaterComponent(component: string): HeaterComponent | undefined;
+    private operationKey;
+    cancelJob(host: string, port: string, apiKey: string): Promise<any>;
+    setTemperature(host: string, port: string, apiKey: string, component: string, temperature: unknown, options?: PrintSafetyOptions): Promise<any>;
+    uploadFile(host: string, port: string, apiKey: string, filePath: string, filename: string, print: boolean, options?: PrintSafetyOptions): Promise<any>;
+    startJob(host: string, port: string, apiKey: string, filename: string, options?: PrintSafetyOptions): Promise<any>;
+    /** Download with a bounded size and its own timeout. */
+    protected downloadToFile(url: string, headers: Record<string, string>, destination: string): Promise<void>;
+    private validateOffline;
+    /** The started name must be the uploaded name: no directories. */
+    private printableRemoteName;
+    /** A private read-only copy named like the remote file; multipart adapters use its basename. */
+    private withNamedSnapshot;
+    private assertReady;
+    private assertBedClearance;
+    private printChecked;
+    private printPrompt;
+}

package/dist/printers/generic-base.js

@@ -0,0 +1,209 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { PrinterImplementation } from "../types.js";
+import { cancelPendingPrinterOperations, withPrinterOperation } from "../safety/artifact.js";
+import { MAX_PRINT_FILE_BYTES } from "../safety/archive.js";
+import { requireHumanConfirmation } from "../safety/confirmation.js";
+import { assertExpectedPeaks, validateExpectedPeaks } from "../safety/expected-peaks.js";
+import { assertInspectableGcodeName, finiteTemperature, genericCeilings, inspectGcodeFile, validateGenericTemperature, } from "../safety/gcode-thermal.js";
+/** Download timeout for remote-start inspection; the shared client times out at 10 s. */
+export const REMOTE_DOWNLOAD_TIMEOUT_MS = 120000;
+/**
+ * Shared print and heating gate for non-Bambu adapters. Public mutations
+ * validate every input before connecting, inspect the exact bytes that are
+ * uploaded, check fresh adapter state, ask a human (MCP elicitation), recheck
+ * state and only then dispatch. Heater-off and cancel are never gated.
+ */
+export class GenericPrinterImplementation extends PrinterImplementation {
+    constructor(apiClient, confirm) {
+        super(apiClient);
+        this.confirm = confirm;
+        /** True when rawUploadFile(print=true) starts the uploaded bytes atomically. */
+        this.uploadStartsPrint = false;
+    }
+    /** Adapter-specific upload acknowledgement for the upload-then-start route. */
+    uploadSucceeded(_data) {
+        return true;
+    }
+    /** Adapter-specific acknowledgement that an atomic upload-and-print started. */
+    uploadStartedPrint(_data) {
+        return true;
+    }
+    /** Map caller component names to a heater and the raw adapter name. */
+    heaterComponent(component) {
+        const normalized = component.trim().toLowerCase();
+        if (normalized === "bed")
+            return { heater: "bed", raw: "bed" };
+        if (["extruder", "nozzle", "tool", "tool0"].includes(normalized))
+            return { heater: "nozzle", raw: "extruder" };
+        return undefined;
+    }
+    operationKey(host, port) {
+        return `${this.printerLabel}:${host}:${port}`;
+    }
+    async cancelJob(host, port, apiKey) {
+        cancelPendingPrinterOperations(host, this.operationKey(host, port));
+        return this.rawCancelJob(host, port, apiKey);
+    }
+    async setTemperature(host, port, apiKey, component, temperature, options = {}) {
+        const target = this.heaterComponent(String(component));
+        if (!target)
+            throw new Error(`Unsupported component: ${component}`);
+        const value = finiteTemperature(temperature);
+        const key = this.operationKey(host, port);
+        if (value === 0) {
+            // Heater-off is never gated and cancels pending checked operations.
+            cancelPendingPrinterOperations(host, key);
+            return this.rawSetTemperature(host, port, apiKey, target.raw, 0);
+        }
+        const material = options.material?.trim();
+        validateGenericTemperature(target.heater, value, material ? [material] : undefined);
+        return withPrinterOperation(host, key, async (assertActive) => {
+            this.assertReady(await this.readPrinterState(host, port, apiKey), "heat");
+            await requireHumanConfirmation(this.confirm, `Heat ${target.heater} on ${this.printerLabel} (${host}:${port}) to ${value}°C?` +
+                (material && target.heater === "nozzle" ? ` Declared material: ${material}. Confirm the loaded filament matches.` : ""), "generic");
+            assertActive();
+            this.assertReady(await this.readPrinterState(host, port, apiKey), "heat");
+            assertActive();
+            return this.rawSetTemperature(host, port, apiKey, target.raw, value);
+        });
+    }
+    async uploadFile(host, port, apiKey, filePath, filename, print, options = {}) {
+        if (!print)
+            return this.rawUploadFile(host, port, apiKey, filePath, filename, false);
+        const remoteName = this.printableRemoteName(filename);
+        this.validateOffline(options);
+        return withPrinterOperation(host, this.operationKey(host, port), (assertActive) => this.withNamedSnapshot(filePath, remoteName, (snapshot) => this.printChecked(host, port, apiKey, snapshot, remoteName, options, assertActive)));
+    }
+    async startJob(host, port, apiKey, filename, options = {}) {
+        this.validateOffline(options);
+        if (!this.downloadRemoteFile) {
+            throw new Error(`Print safety: start_print cannot inspect files already stored on ${this.printerLabel}; this adapter has no verified download route. ` +
+                "Uninspected remote jobs are refused. Use upload_gcode with print=true and the local G-code so the exact bytes are inspected.");
+        }
+        assertInspectableGcodeName(filename);
+        const checkedName = `checked-${randomUUID()}-${path.posix.basename(filename.replace(/\\/g, "/"))}`;
+        return withPrinterOperation(host, this.operationKey(host, port), async (assertActive) => {
+            const directory = await fs.mkdtemp(path.join(os.tmpdir(), "printer-remote-check-"));
+            const downloaded = path.join(directory, "download");
+            try {
+                await this.downloadRemoteFile(host, port, apiKey, filename, downloaded);
+                // Start a uniquely named copy of the inspected download; the original
+                // remote name could change between inspection and start.
+                return await this.withNamedSnapshot(downloaded, checkedName, (snapshot) => this.printChecked(host, port, apiKey, snapshot, checkedName, options, assertActive));
+            }
+            finally {
+                await fs.rm(directory, { recursive: true, force: true });
+            }
+        });
+    }
+    /** Download with a bounded size and its own timeout. */
+    async downloadToFile(url, headers, destination) {
+        const response = await this.apiClient.get(url, {
+            headers,
+            responseType: "arraybuffer",
+            timeout: REMOTE_DOWNLOAD_TIMEOUT_MS,
+            maxContentLength: MAX_PRINT_FILE_BYTES,
+            maxBodyLength: MAX_PRINT_FILE_BYTES,
+        });
+        const bytes = Buffer.from(response.data);
+        if (!bytes.length || bytes.length > MAX_PRINT_FILE_BYTES) {
+            throw new Error("Remote print file is empty or exceeds the 256 MiB inspection limit.");
+        }
+        await fs.writeFile(destination, bytes);
+    }
+    validateOffline(options) {
+        validateExpectedPeaks(options.expectedPeaks);
+        genericCeilings();
+    }
+    /** The started name must be the uploaded name: no directories. */
+    printableRemoteName(filename) {
+        const name = String(filename);
+        if (!name || name !== path.posix.basename(name) || name.includes("\\") || name === "." || name === ".." || /[\r\n\0]/.test(name)) {
+            throw new Error("Print safety: printing after upload needs a plain filename without directories, so the started file is exactly the uploaded file.");
+        }
+        assertInspectableGcodeName(name);
+        return name;
+    }
+    /** A private read-only copy named like the remote file; multipart adapters use its basename. */
+    async withNamedSnapshot(source, name, operation) {
+        const directory = await fs.mkdtemp(path.join(os.tmpdir(), "printer-print-"));
+        const snapshot = path.join(directory, name);
+        try {
+            await fs.copyFile(source, snapshot);
+            await fs.chmod(snapshot, 0o400);
+            return await operation(snapshot);
+        }
+        finally {
+            await fs.rm(directory, { recursive: true, force: true });
+        }
+    }
+    assertReady(state, action) {
+        if (!state.ready) {
+            throw new Error(`Print safety: ${this.printerLabel} reports '${state.state}'${state.reason ? ` (${state.reason})` : ""}; ` +
+                `it is not safely idle, so the ${action === "print" ? "print was not started" : "heater was not changed"}.`);
+        }
+    }
+    assertBedClearance(state, confirmedFinishedJob) {
+        if (state.finishedJob !== undefined && state.finishedJob !== confirmedFinishedJob) {
+            throw new Error("Print safety: the printer reports a newly finished job. Confirm its part and debris were removed before retrying.");
+        }
+    }
+    async printChecked(host, port, apiKey, snapshot, remoteName, options, assertActive) {
+        const inspection = await inspectGcodeFile(snapshot, { material: options.material });
+        assertExpectedPeaks(options.expectedPeaks, { nozzle: inspection.peaks.nozzle, bed: inspection.peaks.bed });
+        const initial = await this.readPrinterState(host, port, apiKey);
+        this.assertReady(initial, "print");
+        await requireHumanConfirmation(this.confirm, this.printPrompt(host, port, remoteName, inspection, initial), "generic", initial.finishedJob !== undefined);
+        assertActive();
+        const confirmed = await this.readPrinterState(host, port, apiKey);
+        this.assertReady(confirmed, "print");
+        this.assertBedClearance(confirmed, initial.finishedJob);
+        assertActive();
+        const summary = {
+            status: "success",
+            printRequested: true,
+            remotePath: remoteName,
+            sha256: inspection.sha256,
+            materials: inspection.materials,
+            peakTemperatures: inspection.peaks,
+        };
+        if (this.uploadStartsPrint) {
+            const response = await this.rawUploadFile(host, port, apiKey, snapshot, remoteName, true);
+            // A stop sent while the upload was in flight reached the printer before
+            // this upload started the job, so stop again: the cancellation must win.
+            try {
+                assertActive();
+            }
+            catch {
+                await this.rawCancelJob(host, port, apiKey).catch(() => undefined);
+                throw new Error(`A stop request arrived while ${remoteName} was uploading; the print it started was stopped again. Check the printer before retrying.`);
+            }
+            if (!this.uploadStartedPrint(response)) {
+                throw new Error(`${this.printerLabel} stored ${remoteName} but reports that it did not start printing it.`);
+            }
+            return { ...summary, response };
+        }
+        const upload = await this.rawUploadFile(host, port, apiKey, snapshot, remoteName, false);
+        if (!this.uploadSucceeded(upload)) {
+            throw new Error(`${this.printerLabel} did not confirm the upload of ${remoteName}; the print was not started.`);
+        }
+        // Uploads can be long. Recheck state before the start command.
+        const dispatch = await this.readPrinterState(host, port, apiKey);
+        this.assertReady(dispatch, "print");
+        this.assertBedClearance(dispatch, initial.finishedJob);
+        assertActive();
+        const response = await this.rawStartJob(host, port, apiKey, remoteName);
+        return { ...summary, upload, response };
+    }
+    printPrompt(host, port, remoteName, inspection, state) {
+        const materials = inspection.materials.length ? inspection.materials.join(", ") : "none declared (no positive nozzle target)";
+        return (`Start a checked print of ${remoteName} on ${this.printerLabel} (${host}:${port})? ` +
+            `Materials: ${materials} (${inspection.materialSource}). Peak targets: nozzle ${inspection.peaks.nozzle}°C, bed ${inspection.peaks.bed}°C, chamber ${inspection.peaks.chamber}°C ` +
+            `(server ceilings ${inspection.ceilings.nozzle}/${inspection.ceilings.bed}/${inspection.ceilings.chamber}°C). File SHA-256: ${inspection.sha256}. ` +
+            "Confirm the loaded filament matches and that the build plate is clear." +
+            (state.finishedJob !== undefined ? ` The printer reports '${state.state}': remove the previous part and debris before confirming.` : ""));
+    }
+}

package/dist/printers/klipper.d.ts

@@ -1,10 +1,21 @@
-import { PrinterImplementation } from "../types.js";
-export declare class KlipperImplementation extends PrinterImplementation {
+import { GenericPrinterImplementation, type GenericPrinterState } from "./generic-base.js";
+export declare class KlipperImplementation extends GenericPrinterImplementation {
+    protected readonly printerLabel = "Klipper/Moonraker";
+    protected authHeaders(apiKey: string): Record<string, unknown>;
     getStatus(host: string, port: string, apiKey: string): Promise<any>;
     getFiles(host: string, port: string, apiKey: string): Promise<any>;
     getFile(host: string, port: string, apiKey: string, filename: string): Promise<any>;
-    uploadFile(host: string, port: string, apiKey: string, filePath: string, filename: string, print: boolean): Promise<any>;
-    startJob(host: string, port: string, apiKey: string, filename: string): Promise<any>;
-    cancelJob(host: string, port: string, apiKey: string): Promise<any>;
-    setTemperature(host: string, port: string, apiKey: string, component: string, temperature: number): Promise<any>;
+    /**
+     * Moonraker object query: webhooks.state must be "ready" (not startup,
+     * shutdown or error) and print_stats.state standby/complete/cancelled.
+     * complete/cancelled can leave a part on the bed, so they need a human.
+     */
+    protected readPrinterState(host: string, port: string, apiKey: string): Promise<GenericPrinterState>;
+    protected downloadRemoteFile(host: string, port: string, apiKey: string, filename: string, destination: string): Promise<void>;
+    /** Current Moonraker returns {result:{item}}; older releases returned result "success". */
+    protected uploadSucceeded(data: any): boolean;
+    protected rawUploadFile(host: string, port: string, apiKey: string, filePath: string, filename: string, print: boolean): Promise<any>;
+    protected rawStartJob(host: string, port: string, apiKey: string, filename: string): Promise<any>;
+    protected rawCancelJob(host: string, port: string, apiKey: string): Promise<any>;
+    protected rawSetTemperature(host: string, port: string, apiKey: string, component: string, temperature: number): Promise<any>;
 }