@hotmeshio/long-tail 0.26.0 → 0.28.0

package/build/modules/machines.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * The running machine surface, for settings and the machines API. Set by
+ * start() when the config declares lines; absent otherwise, so a deployment
+ * without machines serves no lines and no Lines view.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerMachineSurface = registerMachineSurface;
+exports.getMachineSurface = getMachineSurface;
+let surface = null;
+function registerMachineSurface(next) {
+    surface = next;
+}
+function getMachineSurface() {
+    return surface;
+}

package/build/routes/index.js

@@ -40,6 +40,7 @@ const nats_credentials_1 = __importDefault(require("./nats-credentials"));
 const scan_codes_1 = __importDefault(require("./scan-codes"));
 const domain_1 = __importDefault(require("./domain"));
 const announcements_1 = __importDefault(require("./announcements"));
+const machines_1 = __importDefault(require("./machines"));
 const router = (0, http_1.Router)();
 // Public routes (no auth required — they handle their own auth)
 router.use('/auth', auth_2.default);
@@ -80,6 +81,7 @@ router.use('/topics', topics_1.default);
 router.use('/scan-codes', scan_codes_1.default);
 router.use('/domain', domain_1.default);
 router.use('/announcements', announcements_1.default);
+router.use('/machines', machines_1.default);
 const overview_1 = __importDefault(require("./overview"));
 router.use('/overview', overview_1.default);
 const diagnostics_1 = __importDefault(require("./diagnostics"));

package/build/routes/machines.d.ts

@@ -0,0 +1,2 @@
+declare const router: import("express-serve-static-core").Router;
+export default router;

package/build/routes/machines.js

@@ -0,0 +1,220 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const http_1 = require("../lib/http");
+const escalationsApi = __importStar(require("../api/escalations"));
+const auth_1 = require("../modules/auth");
+const machines_1 = require("../modules/machines");
+const commands_1 = require("../services/machines/commands");
+const registry_1 = require("../services/machines/registry");
+const registry_sync_1 = require("../services/machines/registry-sync");
+const line_index_1 = require("../services/machines/line-index");
+const topics_1 = require("../lib/machines/protocol/topics");
+const router = (0, http_1.Router)();
+/**
+ * The machine surface for the dashboard's Lines view. Reads and the dry run
+ * take the ops tier (superadmin, admin type, or engineer); declaring and
+ * retiring a line takes an administrator. A command is a row parked on the
+ * machine's role as the caller, so that role's write access decides, exactly
+ * as it does for any row created through the API.
+ */
+const NO_LINES = 'no machine lines are declared';
+const NOT_LEADING = 'this replica is not leading the line';
+function lineOf(req) {
+    const surface = (0, machines_1.getMachineSurface)();
+    const siteId = String(req.params.siteId);
+    const lineId = String(req.params.lineId);
+    const line = surface?.findLine(siteId, lineId);
+    return { surface, siteId, lineId, line };
+}
+const SORTS = new Set(['attention', 'site', 'updated']);
+/** The longest search a person types; anything past it is cut, never an error. */
+const QUERY_MAX_CHARS = 200;
+function queryString(v) {
+    return typeof v === 'string' && v.trim() ? v.trim().slice(0, QUERY_MAX_CHARS) : undefined;
+}
+/** The line a path names, when both tokens could name a line at all. */
+function pathLine(req) {
+    const siteId = req.params.siteId;
+    const lineId = req.params.lineId;
+    return (0, topics_1.isTopicLevel)(siteId) && (0, topics_1.isTopicLevel)(lineId) ? { siteId, lineId } : null;
+}
+function queryBoolean(v) {
+    return v === 'true' ? true : v === 'false' ? false : undefined;
+}
+function queryInt(v) {
+    const n = typeof v === 'string' ? Number(v) : NaN;
+    return Number.isFinite(n) ? n : undefined;
+}
+router.get('/lines', auth_1.requireRoleManager, async (req, res) => {
+    const surface = (0, machines_1.getMachineSurface)();
+    if (!surface) {
+        res.status(404).json({ error: NO_LINES });
+        return;
+    }
+    const sort = queryString(req.query.sort);
+    if (sort && !SORTS.has(sort)) {
+        res.status(400).json({ error: `sort must be one of ${[...SORTS].join(', ')}` });
+        return;
+    }
+    const query = {
+        q: queryString(req.query.q), site: queryString(req.query.site), attention: queryBoolean(req.query.attention),
+        sort: sort, limit: queryInt(req.query.limit), offset: queryInt(req.query.offset),
+    };
+    const [page, sites] = await Promise.all([(0, registry_1.listLines)(query), (0, registry_1.listSites)()]);
+    const body = {
+        lines: page.lines.map((record) => (0, line_index_1.toLineIndexRow)(surface, record)),
+        total: page.total, sites, limit: page.limit, offset: page.offset,
+    };
+    res.status(200).json(body);
+});
+router.put('/lines/:siteId/:lineId', auth_1.requireAdmin, async (req, res) => {
+    const surface = (0, machines_1.getMachineSurface)();
+    if (!surface) {
+        res.status(404).json({ error: NO_LINES });
+        return;
+    }
+    const named = pathLine(req);
+    if (!named) {
+        res.status(400).json({ error: 'siteId and lineId must be topic levels' });
+        return;
+    }
+    const { siteId, lineId } = named;
+    const definition = req.body?.definition;
+    if (!definition || typeof definition !== 'object' || Array.isArray(definition)) {
+        res.status(400).json({ error: 'definition is required' });
+        return;
+    }
+    if (definition.siteId !== siteId || definition.lineId !== lineId) {
+        res.status(400).json({ error: `definition must be for ${siteId}/${lineId}` });
+        return;
+    }
+    const version = req.body?.version;
+    if (version !== undefined && !(Number.isInteger(version) && version >= 1)) {
+        res.status(400).json({ error: 'version must be a whole number of at least 1' });
+        return;
+    }
+    try {
+        const record = await (0, registry_sync_1.declareLine)(surface, definition, version);
+        const stored = (await (0, registry_1.getLineWithHealth)(siteId, lineId)) ?? { ...record, health: (0, line_index_1.emptyLineHealth)(record.definition.machines.length) };
+        res.status(200).json({ line: (0, line_index_1.toLineIndexRow)(surface, stored) });
+    }
+    catch (err) {
+        if (err instanceof registry_1.LineVersionConflict) {
+            res.status(409).json({ error: err.message });
+            return;
+        }
+        res.status(400).json({ error: err instanceof Error ? err.message : String(err) });
+    }
+});
+router.delete('/lines/:siteId/:lineId', auth_1.requireAdmin, async (req, res) => {
+    const surface = (0, machines_1.getMachineSurface)();
+    if (!surface) {
+        res.status(404).json({ error: NO_LINES });
+        return;
+    }
+    const named = pathLine(req);
+    if (!named) {
+        res.status(404).json({ error: 'no such line' });
+        return;
+    }
+    const { siteId, lineId } = named;
+    const record = await (0, registry_sync_1.retireLine)(surface, siteId, lineId);
+    if (!record) {
+        res.status(404).json({ error: `no line ${siteId}/${lineId}` });
+        return;
+    }
+    res.status(204).end();
+});
+router.get('/lines/:siteId/:lineId', auth_1.requireRoleManager, (req, res) => {
+    const { surface, siteId, lineId, line } = lineOf(req);
+    if (!surface || !line) {
+        res.status(404).json({ error: surface ? `no line ${siteId}/${lineId}` : NO_LINES });
+        return;
+    }
+    const body = {
+        ...(surface.describeLine(siteId, lineId) ?? { siteId, lineId, leading: false }),
+        summary: (0, line_index_1.lineSummaryOf)(surface, siteId, lineId, line),
+    };
+    res.status(200).json(body);
+});
+router.post('/lines/:siteId/:lineId/inspect', auth_1.requireRoleManager, (req, res) => {
+    const { surface, siteId, lineId, line } = lineOf(req);
+    if (!surface || !line) {
+        res.status(404).json({ error: surface ? `no line ${siteId}/${lineId}` : NO_LINES });
+        return;
+    }
+    const topic = req.body?.topic;
+    if (typeof topic !== 'string' || !topic) {
+        res.status(400).json({ error: 'topic is required' });
+        return;
+    }
+    const result = surface.inspect(siteId, lineId, { topic, payload: (0, line_index_1.wirePayloadOf)(req.body?.payload), retained: req.body?.retained === true });
+    if (!result) {
+        res.status(409).json({ error: NOT_LEADING });
+        return;
+    }
+    res.status(200).json(result);
+});
+router.post('/lines/:siteId/:lineId/machines/:machineId/commands', async (req, res) => {
+    const { surface, siteId, lineId, line } = lineOf(req);
+    if (!surface || !line) {
+        res.status(404).json({ error: surface ? `no line ${siteId}/${lineId}` : NO_LINES });
+        return;
+    }
+    const machineId = String(req.params.machineId);
+    if (!line.machines.some((m) => m.machineId === machineId)) {
+        res.status(404).json({ error: `no machine ${machineId} on ${siteId}/${lineId}` });
+        return;
+    }
+    const op = req.body?.op;
+    const ops = surface.commandOps(siteId, lineId);
+    if (typeof op !== 'string' || !ops.includes(op)) {
+        res.status(400).json({ error: `op must be one of ${ops.join(', ')}` });
+        return;
+    }
+    const args = req.body?.args;
+    if (args !== undefined && (!args || typeof args !== 'object' || Array.isArray(args))) {
+        res.status(400).json({ error: 'args must be an object' });
+        return;
+    }
+    const result = await escalationsApi.createEscalation((0, commands_1.commandRow)((0, commands_1.commandTarget)(line, machineId), op, args ?? {}), req.auth);
+    if (result.status !== 201) {
+        res.status(result.status).json({ error: result.error });
+        return;
+    }
+    res.status(201).json({ rowId: result.data.id });
+});
+exports.default = router;

package/build/scripts/bambu-boat.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Make the example's first print: a small 3DBenchy (by Creative Tools), sliced
+ * for the printer with OrcaSlicer, written to examples/workflows/bambu-printer/files/boat.gcode.3mf.
+ * Run it on the host, where OrcaSlicer is installed:
+ *
+ *   npm run bambu:boat
+ *
+ * 1. Download the model once into files/.
+ * 2. Scale it (BAMBU_BOAT_SCALE, 0.5 by default: about ten minutes on a P1S).
+ * 3. Slice it with the printer, process and filament presets. Each is an
+ *    OrcaSlicer system preset name or a path to a preset JSON, which may
+ *    inherit a system preset by name.
+ *
+ * Env: BAMBU_BOAT_PRINTER, BAMBU_BOAT_PROCESS, BAMBU_BOAT_FILAMENT, BAMBU_BOAT_SCALE,
+ * ORCA_SLICER (the OrcaSlicer executable) and ORCA_PROFILES (its BBL profiles directory).
+ */
+export {};

package/build/scripts/bambu-boat.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Make the example's first print: a small 3DBenchy (by Creative Tools), sliced
+ * for the printer with OrcaSlicer, written to examples/workflows/bambu-printer/files/boat.gcode.3mf.
+ * Run it on the host, where OrcaSlicer is installed:
+ *
+ *   npm run bambu:boat
+ *
+ * 1. Download the model once into files/.
+ * 2. Scale it (BAMBU_BOAT_SCALE, 0.5 by default: about ten minutes on a P1S).
+ * 3. Slice it with the printer, process and filament presets. Each is an
+ *    OrcaSlicer system preset name or a path to a preset JSON, which may
+ *    inherit a system preset by name.
+ *
+ * Env: BAMBU_BOAT_PRINTER, BAMBU_BOAT_PROCESS, BAMBU_BOAT_FILAMENT, BAMBU_BOAT_SCALE,
+ * ORCA_SLICER (the OrcaSlicer executable) and ORCA_PROFILES (its BBL profiles directory).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+try {
+    require('dotenv/config');
+}
+catch { /* dotenv optional */ }
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const env = process.env;
+const FILES = (0, path_1.resolve)('examples/workflows/bambu-printer/files');
+const MODEL_URL = 'https://raw.githubusercontent.com/CreativeTools/3DBenchy/master/Single-part/3DBenchy.stl';
+const ORCA = env.ORCA_SLICER || '/Applications/OrcaSlicer.app/Contents/MacOS/OrcaSlicer';
+const PROFILES = env.ORCA_PROFILES || '/Applications/OrcaSlicer.app/Contents/Resources/profiles/BBL';
+const PRESET = {
+    PRINTER: env.BAMBU_BOAT_PRINTER || 'Bambu Lab P1S 0.4 nozzle',
+    PROCESS: env.BAMBU_BOAT_PROCESS || '0.20mm Standard @BBL X1C',
+    FILAMENT: env.BAMBU_BOAT_FILAMENT || 'Bambu PLA Basic @BBL X1C',
+};
+const PRESET_DIR = { PRINTER: 'machine', PROCESS: 'process', FILAMENT: 'filament' };
+const STL_HEADER = 84;
+const STL_TRIANGLE = 50;
+const say = (msg) => console.log(`[${new Date().toISOString().slice(11, 19)}] ${msg}`);
+async function fetchModel() {
+    const path = (0, path_1.join)(FILES, '3DBenchy.stl');
+    if ((0, fs_1.existsSync)(path))
+        return path;
+    const res = await fetch(MODEL_URL);
+    if (!res.ok)
+        throw new Error(`GET ${MODEL_URL} -> ${res.status}`);
+    (0, fs_1.writeFileSync)(path, Buffer.from(await res.arrayBuffer()));
+    return path;
+}
+/** A binary STL with every vertex scaled about the origin; the slicer places it on the bed. */
+function scaleStl(stl, factor) {
+    const count = stl.readUInt32LE(STL_HEADER - 4);
+    if (stl.length !== STL_HEADER + count * STL_TRIANGLE)
+        throw new Error('the model is not a binary STL');
+    const out = Buffer.from(stl);
+    for (let t = 0; t < count; t++) {
+        const at = STL_HEADER + t * STL_TRIANGLE;
+        for (let v = 3; v < 12; v++)
+            out.writeFloatLE(stl.readFloatLE(at + v * 4) * factor, at + v * 4);
+    }
+    return out;
+}
+/** The system presets of one kind in ORCA_PROFILES, by name. */
+function systemPresets(kind) {
+    const dir = (0, path_1.join)(PROFILES, PRESET_DIR[kind]);
+    const byName = new Map();
+    for (const file of (0, fs_1.readdirSync)(dir).filter((f) => f.endsWith('.json'))) {
+        const preset = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(dir, file), 'utf8'));
+        if (preset.name)
+            byName.set(preset.name, preset);
+    }
+    return byName;
+}
+/**
+ * A preset by path or system preset name, with every setting it inherits
+ * written out: OrcaSlicer's command line reads only the keys in the file, so
+ * an inherited start, layer-change or end G-code would otherwise be lost.
+ */
+function fullPreset(kind, value) {
+    const system = systemPresets(kind);
+    const own = (0, fs_1.existsSync)(value) ? JSON.parse((0, fs_1.readFileSync)(value, 'utf8')) : system.get(value);
+    if (!own)
+        throw new Error(`no ${kind.toLowerCase()} preset ${value} (a path, or a name in ${PROFILES}/${PRESET_DIR[kind]})`);
+    const chain = [own];
+    for (let p = own; p.inherits;) {
+        p = system.get(p.inherits);
+        if (!p)
+            throw new Error(`${kind.toLowerCase()} preset ${value} inherits ${chain[chain.length - 1].inherits}, which is not in ${PROFILES}`);
+        chain.unshift(p);
+    }
+    return Object.assign({}, ...chain, { inherits: '' });
+}
+/** Write a full preset for the slicer; a process or filament is marked compatible with the printer, as OrcaSlicer requires. */
+function writePreset(dir, kind, preset, printerName) {
+    const path = (0, path_1.join)(dir, `${PRESET_DIR[kind]}.json`);
+    const compatibility = kind === 'PRINTER' ? {} : { from: 'User', compatible_printers: [printerName], compatible_printers_condition: '' };
+    (0, fs_1.writeFileSync)(path, JSON.stringify({ ...preset, ...compatibility }));
+    return path;
+}
+async function main() {
+    if (!(0, fs_1.existsSync)(ORCA))
+        throw new Error(`OrcaSlicer is not at ${ORCA}; install it or set ORCA_SLICER`);
+    (0, fs_1.mkdirSync)(FILES, { recursive: true });
+    const work = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), 'bambu-boat-'));
+    // 1. The model
+    const model = await fetchModel();
+    // 2. Scaled
+    const scale = Number(env.BAMBU_BOAT_SCALE || 0.5);
+    if (!(scale > 0))
+        throw new Error(`BAMBU_BOAT_SCALE="${env.BAMBU_BOAT_SCALE}" must be a number above 0`);
+    const scaled = (0, path_1.join)(work, 'boat.stl');
+    (0, fs_1.writeFileSync)(scaled, scaleStl((0, fs_1.readFileSync)(model), scale));
+    // 3. Sliced
+    const printerPreset = fullPreset('PRINTER', PRESET.PRINTER);
+    const printerName = printerPreset.name;
+    const printer = writePreset(work, 'PRINTER', printerPreset, printerName);
+    const process_ = writePreset(work, 'PROCESS', fullPreset('PROCESS', PRESET.PROCESS), printerName);
+    const filament = writePreset(work, 'FILAMENT', fullPreset('FILAMENT', PRESET.FILAMENT), printerName);
+    say(`slicing at ${scale}x for ${printerName}`);
+    (0, child_process_1.execFileSync)(ORCA, [
+        '--load-settings', `${printer};${process_}`, '--load-filaments', filament,
+        '--arrange', '1', '--slice', '0', '--outputdir', work, '--export-3mf', 'boat.gcode.3mf', scaled,
+    ], { stdio: 'inherit' });
+    const target = (0, path_1.join)(FILES, 'boat.gcode.3mf');
+    (0, fs_1.renameSync)((0, path_1.join)(work, 'boat.gcode.3mf'), target);
+    const gcode = (0, fs_1.readdirSync)(work).find((f) => f.endsWith('.gcode'));
+    const time = gcode ? (0, fs_1.readFileSync)((0, path_1.join)(work, gcode), 'utf8').slice(0, 2000).match(/total estimated time: ([^\n]+)/)?.[1] : undefined;
+    say(`${target}${time ? ` (about ${time})` : ''}`);
+}
+main().catch((err) => {
+    console.error(`failed: ${err.message}`);
+    process.exit(1);
+});

package/build/scripts/bambu-print.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Print one file on a Bambu printer through Long Tail, and follow its rows.
+ * Run it where the printer is reachable, e.g. in the Long Tail container:
+ *
+ *   docker compose exec long-tail npm run bambu:print -- [examples/workflows/bambu-printer/files/part.gcode.3mf] [station]
+ *
+ * Without a file it prints the example's boat, a half-size 3DBenchy for a P1S with a 0.8 nozzle and TPU;
+ * `npm run bambu:boat` slices one for another printer or filament.
+ *
+ * 1. Put the file on the printer (it prints only files on its own storage) and hash it: the unit's artifact.
+ * 2. Start the unit route: one print step at the station, then a person unloads.
+ * 3. Print the route's rows and their lifecycle items as they change, until the
+ *    route ends. The unload row is resolved by a person on the dashboard.
+ *
+ * Env: LT_USERNAME and LT_PASSWORD (a Long Tail login that may invoke the route), BASE_URL
+ * (http://localhost:3000), BAMBU_SITE_DIR (deploy/bambu-site), and the printers in .env.
+ */
+export {};

package/build/scripts/bambu-print.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * Print one file on a Bambu printer through Long Tail, and follow its rows.
+ * Run it where the printer is reachable, e.g. in the Long Tail container:
+ *
+ *   docker compose exec long-tail npm run bambu:print -- [examples/workflows/bambu-printer/files/part.gcode.3mf] [station]
+ *
+ * Without a file it prints the example's boat, a half-size 3DBenchy for a P1S with a 0.8 nozzle and TPU;
+ * `npm run bambu:boat` slices one for another printer or filament.
+ *
+ * 1. Put the file on the printer (it prints only files on its own storage) and hash it: the unit's artifact.
+ * 2. Start the unit route: one print step at the station, then a person unloads.
+ * 3. Print the route's rows and their lifecycle items as they change, until the
+ *    route ends. The unload row is resolved by a person on the dashboard.
+ *
+ * Env: LT_USERNAME and LT_PASSWORD (a Long Tail login that may invoke the route), BASE_URL
+ * (http://localhost:3000), BAMBU_SITE_DIR (deploy/bambu-site), and the printers in .env.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+try {
+    require('dotenv/config');
+}
+catch { /* dotenv optional */ }
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const env_1 = require("../examples/workflows/bambu-printer/env");
+const files_1 = require("../examples/workflows/bambu-printer/files");
+const route_1 = require("../examples/workflows/machine-line/workflows/route");
+const env = process.env;
+const BASE_URL = env.BASE_URL || 'http://localhost:3000';
+const SITE_DIR = env.BAMBU_SITE_DIR || 'deploy/bambu-site';
+const WATCH_MS = 3_000;
+const BOAT = 'examples/workflows/bambu-printer/boat/p1s-0.8-tpu.gcode.3mf';
+const ts = () => new Date().toISOString().slice(11, 19);
+const say = (msg) => console.log(`[${ts()}] ${msg}`);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+let token = '';
+async function api(method, path, body) {
+    const res = await fetch(`${BASE_URL}/api${path}`, {
+        method,
+        headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok)
+        throw new Error(`${method} ${path} -> ${res.status}: ${JSON.stringify(data)}`);
+    return data;
+}
+/** The route's rows, and the items each holds, printed as they change; the route's result once it ends. */
+async function follow(orderRef, workflowId) {
+    const shown = new Map();
+    for (;;) {
+        try {
+            const result = await look(orderRef, workflowId, shown);
+            if (result)
+                return result;
+        }
+        catch (err) {
+            // A restart or a database blip is not the route ending: keep following.
+            say(`(could not read the route: ${err.message}; trying again)`);
+        }
+        await sleep(WATCH_MS);
+    }
+}
+async function look(orderRef, workflowId, shown) {
+    const facets = encodeURIComponent(JSON.stringify({ orderRef }));
+    const { escalations } = await api('GET', `/escalations?facets=${facets}&limit=20&sort_by=created_at&order=asc`);
+    for (const row of escalations) {
+        const { items = [] } = await api('GET', `/escalations/${row.id}/items`);
+        const view = `${row.type}/${row.role} ${row.status}${row.assigned_to ? ' claimed' : ''} [${items.map((i) => i.itemKey).join(', ')}]`;
+        if (shown.get(row.id) !== view)
+            say(`${row.id.slice(0, 8)} ${view}`);
+        shown.set(row.id, view);
+    }
+    const resp = await api('GET', `/workflows/${workflowId}/result`).catch(() => null);
+    return resp?.result?.data?.status ? resp.result.data : null;
+}
+async function main() {
+    const [file = BOAT, stationArg] = process.argv.slice(2);
+    if (!(0, fs_1.existsSync)(file))
+        throw new Error(`${file} is missing; usage: npm run bambu:print -- [path/to/part.gcode.3mf] [station]`);
+    const line = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(SITE_DIR, 'line.json'), 'utf8'));
+    const station = stationArg || line.machines[0].machineId;
+    const printer = (0, env_1.printersFromEnv)().find((p) => p.station === station);
+    if (!printer || !line.machines.some((m) => m.machineId === station))
+        throw new Error(`${station} is not an enabled printer on the line in ${SITE_DIR}/line.json`);
+    // 1. The artifact, on the printer
+    const routeKey = `P${Date.now().toString(36)}`;
+    const sha256 = (0, crypto_1.createHash)('sha256').update((0, fs_1.readFileSync)(file)).digest('hex');
+    say(`copying ${(0, path_1.basename)(file)} to ${station} (a minute or two for a few MB)`);
+    const url = await (0, files_1.stageFile)(printer, file, `${routeKey}.gcode.3mf`);
+    say(`${url} (sha256 ${sha256.slice(0, 12)}…)`);
+    // 2. The route
+    const { LT_USERNAME: username, LT_PASSWORD: password } = env;
+    if (!username || !password)
+        throw new Error('set LT_USERNAME and LT_PASSWORD in .env');
+    token = (await api('POST', '/auth/login', { username, password })).token;
+    const input = {
+        siteId: line.siteId, lineId: line.lineId, routeKey, orderRef: `ORD-${routeKey}`,
+        units: [{ unitId: `U-${routeKey}`, carrierId: `PLATE-${routeKey}` }],
+        steps: [{ machineId: station, process: env_1.PRINT_PROCESS, recipe: { ...env_1.PRINT_RECIPE } }],
+        artifact: { url, sha256 }, exitRole: env_1.BAMBU_ROLES.UNLOAD, handoffTimeout: env.BAMBU_HANDOFF_TIMEOUT || '6h',
+    };
+    const workflowId = `bambu-${routeKey}`;
+    await api('POST', `/workflows/${route_1.UNIT_ROUTE_WORKFLOW}/invoke`, { data: input, metadata: { source: 'bambu-print' }, workflowId });
+    say(`started ${workflowId} on ${station}; unload the part on the dashboard (${env_1.BAMBU_ROLES.UNLOAD}) when it finishes`);
+    // 3. Follow it
+    say(`route ended: ${JSON.stringify(await follow(input.orderRef, workflowId))}`);
+}
+main().catch((err) => {
+    console.error(`[${ts()}] failed: ${err.message}`);
+    process.exit(1);
+});

package/build/services/machines/commands.d.ts

@@ -1,11 +1,11 @@
 /**
  * Commands as rows. A host asks a machine to start, stop, pause, resume,
- * change over or cancel a job by parking a machine-command row on the machine's role, from a
- * workflow step or through the API, the same way it asks a person for
+ * change over, cancel a job, report a snapshot, or do anything its codec
+ * declares (`rowOps`), by parking a machine-command row on the machine's role,
+ * from a workflow step or through the API, the same way it asks a person for
  * anything. The gateway sends the command and resolves the row with the
  * machine's reply (CommandResolution), so the step reads the outcome as data.
  */
-import type { Op } from '../../lib/machines/protocol';
 import { type LineDef } from '../../lib/machines/line';
 import { type CommandFacets } from './contracts';
 /** Where a command goes: the machine and the role its rows land on. */
@@ -17,10 +17,10 @@ export interface CommandTarget {
 }
 export declare function commandTarget(line: LineDef, machineId: string): CommandTarget;
 /** The row that asks a machine for `op`: pass it to conditional(), or create it through the API. */
-export declare function commandRow(target: CommandTarget, op: Op, args?: Record<string, unknown>): {
+export declare function commandRow(target: CommandTarget, op: string, args?: Record<string, unknown>): {
     role: string;
     type: "machine-command";
-    subtype: Op;
+    subtype: string;
     description: string;
     priority: number;
     metadata: Record<string, unknown>;

package/build/services/machines/commands.js

@@ -1,8 +1,9 @@
 "use strict";
 /**
  * Commands as rows. A host asks a machine to start, stop, pause, resume,
- * change over or cancel a job by parking a machine-command row on the machine's role, from a
- * workflow step or through the API, the same way it asks a person for
+ * change over, cancel a job, report a snapshot, or do anything its codec
+ * declares (`rowOps`), by parking a machine-command row on the machine's role,
+ * from a workflow step or through the API, the same way it asks a person for
  * anything. The gateway sends the command and resolves the row with the
  * machine's reply (CommandResolution), so the step reads the outcome as data.
  */

package/build/services/machines/config.d.ts

@@ -29,7 +29,6 @@ export interface MachineLineConfig {
     mqtt?: MqttEndpoint;
     replyTimeoutMs: number;
     dispatchAttempts: number;
-    handoffTimeout: string;
     offlineDebounceMs: number;
     /** A connected machine silent this long gets a quiet row; 0 turns the check off. */
     quietMs: number;
@@ -37,7 +36,15 @@ export interface MachineLineConfig {
     dispatchTtlMs: number;
     /** How long confirmed message ids gather before a receipt goes out. */
     receiptDelayMs: number;
+    /** Note each job's start, progress steps and pauses on the row that holds it (lifecycle.ts). */
+    lifecycle: boolean;
+    /** With lifecycle notes, progress is noted each time it crosses this many percent; 0 notes none. */
+    progressStep: number;
+    /** Telemetry messages are published as wire events too; off by default, since they are read live and many. */
+    wireTelemetry: boolean;
     ltBaseUrl: string;
 }
 type Env = Record<string, string | undefined>;
+/** The generic line protocol's topic root when MACHINE_TOPIC_ROOT is unset. */
+export declare const DEFAULT_TOPIC_ROOT = "line/v1";
 export declare function loadMachineLineConfig(env?: Env): MachineLineConfig;