@hotmeshio/long-tail 0.25.4 → 0.27.0

package/build/lib/messaging/nats/render-conf.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Long Tail's NATS server, rendered. Accounts keep traffic apart:
+ *
+ * - LT: Long Tail itself. It owns the durable streams and imports each edge's
+ *   subjects, which its streams can then keep.
+ * - one edge account per line: the site broker's bridge logs in here (MQTT
+ *   only) and may publish its line's subjects and nothing else. The account
+ *   exports exactly those subjects, so nothing of Long Tail's is reachable.
+ * - SYS: the server's own monitoring.
+ *
+ * NATS configuration accepts JSON, so accounts are written as JSON.
+ */
+export interface NatsPermissions {
+    publish?: string[] | {
+        allow?: string[];
+        deny?: string[];
+    };
+    subscribe?: string[] | {
+        allow?: string[];
+        deny?: string[];
+    };
+}
+export interface NatsUser {
+    user: string;
+    password?: string;
+    permissions?: NatsPermissions;
+    allowed_connection_types?: string[];
+}
+/** A line's edge: who logs in for it, and the subjects it may publish (e.g. `line.v1.site-1.line-1.>`). */
+export interface EdgeAccount {
+    name: string;
+    subjects: string;
+    users: NatsUser[];
+}
+export interface NatsConfOptions {
+    serverName: string;
+    port?: number;
+    httpPort?: number;
+    jetstream?: {
+        storeDir: string;
+    };
+    /** WebSocket listener for browsers; `noAuthUser` maps a connection without credentials to that LT user. */
+    websocket?: {
+        port: number;
+        noTls?: boolean;
+        noAuthUser?: string;
+    };
+    /** MQTT listener for edge bridges; with `tls`, certificates map to users by their subject. */
+    mqtt?: {
+        port: number;
+        tls?: {
+            certFile: string;
+            keyFile: string;
+            caFile: string;
+        };
+    };
+    lt: {
+        users: NatsUser[];
+    };
+    edges: EdgeAccount[];
+    system?: {
+        user: string;
+        password: string;
+    };
+}
+export declare const LT_ACCOUNT = "LT";
+export declare const SYS_ACCOUNT = "SYS";
+export declare function renderNatsConf(opts: NatsConfOptions): string;

package/build/lib/messaging/nats/render-conf.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Long Tail's NATS server, rendered. Accounts keep traffic apart:
+ *
+ * - LT: Long Tail itself. It owns the durable streams and imports each edge's
+ *   subjects, which its streams can then keep.
+ * - one edge account per line: the site broker's bridge logs in here (MQTT
+ *   only) and may publish its line's subjects and nothing else. The account
+ *   exports exactly those subjects, so nothing of Long Tail's is reachable.
+ * - SYS: the server's own monitoring.
+ *
+ * NATS configuration accepts JSON, so accounts are written as JSON.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYS_ACCOUNT = exports.LT_ACCOUNT = void 0;
+exports.renderNatsConf = renderNatsConf;
+exports.LT_ACCOUNT = 'LT';
+exports.SYS_ACCOUNT = 'SYS';
+function accounts(opts) {
+    const out = {
+        [exports.LT_ACCOUNT]: {
+            jetstream: opts.jetstream ? 'enabled' : 'disabled',
+            users: opts.lt.users,
+            imports: opts.edges.map((e) => ({ stream: { account: e.name, subject: e.subjects } })),
+        },
+    };
+    for (const edge of opts.edges) {
+        // The edge account has JetStream because NATS keeps MQTT session state there.
+        out[edge.name] = { jetstream: opts.jetstream ? 'enabled' : 'disabled', users: edge.users, exports: [{ stream: edge.subjects }] };
+    }
+    if (opts.system)
+        out[exports.SYS_ACCOUNT] = { users: [opts.system] };
+    return out;
+}
+function renderNatsConf(opts) {
+    const lines = [
+        '# Rendered by Long Tail (lib/messaging/nats/render-conf.ts). Do not edit by hand.',
+        `server_name: ${JSON.stringify(opts.serverName)}`,
+        `port: ${opts.port ?? 4222}`,
+        `http: ${opts.httpPort ?? 8222}`,
+    ];
+    if (opts.jetstream)
+        lines.push(`jetstream { store_dir: ${JSON.stringify(opts.jetstream.storeDir)} }`);
+    if (opts.websocket) {
+        const ws = opts.websocket;
+        lines.push(`websocket { port: ${ws.port}${ws.noTls ? ', no_tls: true, same_origin: false' : ''}${ws.noAuthUser ? `, no_auth_user: ${JSON.stringify(ws.noAuthUser)}` : ''} }`);
+    }
+    if (opts.mqtt) {
+        const tls = opts.mqtt.tls;
+        lines.push(tls
+            ? `mqtt { port: ${opts.mqtt.port}, tls { cert_file: ${JSON.stringify(tls.certFile)}, key_file: ${JSON.stringify(tls.keyFile)}, ca_file: ${JSON.stringify(tls.caFile)}, verify_and_map: true, timeout: 5 } }`
+            : `mqtt { port: ${opts.mqtt.port} }`);
+    }
+    lines.push(`accounts: ${JSON.stringify(accounts(opts), null, 2)}`);
+    if (opts.system)
+        lines.push(`system_account: ${exports.SYS_ACCOUNT}`);
+    return `${lines.join('\n')}\n`;
+}

package/build/lib/messaging/nats/streams.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Durable streams on JetStream. A spec becomes a file-backed stream or an
+ * explicit-ack durable consumer; ensuring either is safe on every boot, and an
+ * existing consumer keeps its position while its subjects follow the spec.
+ */
+import { type ConsumerConfig, type JetStreamClient, type JetStreamManager, type StreamConfig } from 'nats';
+import type { ConsumerSpec, Delivery, LTConsumeOptions, LTStreamMessage, LTStreams, LTSubscription, StreamSpec, Subject } from '../../../types/messaging';
+export declare function streamConfig(spec: StreamSpec): Partial<StreamConfig>;
+export declare function consumerConfig(spec: ConsumerSpec): Partial<ConsumerConfig>;
+/** Create the stream, or update an existing one to the spec. */
+export declare function ensureStream(jsm: JetStreamManager, spec: StreamSpec): Promise<void>;
+/** Create the consumer, or move an existing one to the spec's subjects without losing its place. */
+export declare function ensureConsumer(jsm: JetStreamManager, stream: string, spec: ConsumerSpec): Promise<void>;
+export declare function payloadOf(m: {
+    data: Uint8Array;
+}): string;
+export declare class NatsStreams implements LTStreams {
+    private readonly jsm;
+    private readonly js;
+    constructor(jsm: JetStreamManager, js: JetStreamClient);
+    ensureStream(spec: StreamSpec): Promise<void>;
+    ensureConsumer(stream: string, spec: ConsumerSpec): Promise<void>;
+    append(subject: Subject, payload: string): Promise<void>;
+    /** One message at a time: the next is not taken until the handler settles this one. */
+    consume(stream: string, consumer: string, handler: (m: LTStreamMessage) => Promise<Delivery>, opts?: LTConsumeOptions): Promise<LTSubscription>;
+}

package/build/lib/messaging/nats/streams.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Durable streams on JetStream. A spec becomes a file-backed stream or an
+ * explicit-ack durable consumer; ensuring either is safe on every boot, and an
+ * existing consumer keeps its position while its subjects follow the spec.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NatsStreams = void 0;
+exports.streamConfig = streamConfig;
+exports.consumerConfig = consumerConfig;
+exports.ensureStream = ensureStream;
+exports.ensureConsumer = ensureConsumer;
+exports.payloadOf = payloadOf;
+const nats_1 = require("nats");
+const constants_1 = require("../constants");
+const DEFAULT_ACK_WAIT_MS = 30_000;
+const DEFAULT_NAK_DELAY_MS = 1_000;
+function streamConfig(spec) {
+    return { name: spec.name, subjects: spec.subjects, max_age: (0, nats_1.nanos)(spec.maxAgeMs), storage: nats_1.StorageType.File };
+}
+function consumerConfig(spec) {
+    return {
+        durable_name: spec.name,
+        ack_policy: nats_1.AckPolicy.Explicit,
+        deliver_policy: (spec.startAt ?? constants_1.START_AT.NEW) === constants_1.START_AT.ALL ? nats_1.DeliverPolicy.All : nats_1.DeliverPolicy.New,
+        ack_wait: (0, nats_1.nanos)(spec.ackWaitMs ?? DEFAULT_ACK_WAIT_MS),
+        filter_subjects: spec.filterSubjects,
+    };
+}
+/** Create the stream, or update an existing one to the spec. */
+async function ensureStream(jsm, spec) {
+    const config = streamConfig(spec);
+    try {
+        await jsm.streams.info(spec.name);
+    }
+    catch (err) {
+        if (!/stream not found/i.test(err?.message ?? ''))
+            throw err;
+        await jsm.streams.add(config);
+        return;
+    }
+    await jsm.streams.update(spec.name, config);
+}
+/** Create the consumer, or move an existing one to the spec's subjects without losing its place. */
+async function ensureConsumer(jsm, stream, spec) {
+    let existing;
+    try {
+        existing = await jsm.consumers.info(stream, spec.name);
+    }
+    catch (err) {
+        if (!/consumer not found/i.test(err?.message ?? ''))
+            throw err;
+        await jsm.consumers.add(stream, consumerConfig(spec));
+        return;
+    }
+    const want = [...spec.filterSubjects].sort();
+    const have = [...(existing.config.filter_subjects ?? [])].sort();
+    if (want.join('|') !== have.join('|'))
+        await jsm.consumers.update(stream, spec.name, { filter_subjects: spec.filterSubjects });
+}
+function payloadOf(m) {
+    return Buffer.from(m.data).toString('utf8');
+}
+class NatsStreams {
+    constructor(jsm, js) {
+        this.jsm = jsm;
+        this.js = js;
+    }
+    ensureStream(spec) {
+        return ensureStream(this.jsm, spec);
+    }
+    ensureConsumer(stream, spec) {
+        return ensureConsumer(this.jsm, stream, spec);
+    }
+    async append(subject, payload) {
+        await this.js.publish(subject, payload);
+    }
+    /** One message at a time: the next is not taken until the handler settles this one. */
+    async consume(stream, consumer, handler, opts = {}) {
+        const nakDelayMs = opts.nakDelayMs ?? DEFAULT_NAK_DELAY_MS;
+        const messages = await (await this.js.consumers.get(stream, consumer)).consume();
+        void (async () => {
+            for await (const m of messages) {
+                const delivery = await handler({ subject: m.subject, payload: payloadOf(m), deliveries: m.info.deliveryCount })
+                    .catch(() => constants_1.DELIVERY.NAK);
+                if (delivery === constants_1.DELIVERY.ACK)
+                    m.ack();
+                else if (delivery === constants_1.DELIVERY.NAK)
+                    m.nak(nakDelayMs);
+                else
+                    m.term();
+            }
+        })();
+        return { close: async () => { await messages.close(); } };
+    }
+}
+exports.NatsStreams = NatsStreams;

package/build/lib/messaging/subjects.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Subject filters. Subjects are dot-separated tokens; in a filter `*` matches
+ * exactly one token and `>` matches one or more trailing tokens.
+ */
+import type { Subject } from '../../types/messaging';
+export declare function subjectMatches(filter: Subject, subject: Subject): boolean;
+/** Whether `subject` is a valid concrete subject: nonempty tokens, no wildcards or whitespace. */
+export declare function isSubject(subject: string): boolean;

package/build/lib/messaging/subjects.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Subject filters. Subjects are dot-separated tokens; in a filter `*` matches
+ * exactly one token and `>` matches one or more trailing tokens.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.subjectMatches = subjectMatches;
+exports.isSubject = isSubject;
+function subjectMatches(filter, subject) {
+    const f = filter.split('.');
+    const s = subject.split('.');
+    for (let i = 0; i < f.length; i++) {
+        if (f[i] === '>')
+            return i === f.length - 1 && s.length > i;
+        if (i >= s.length)
+            return false;
+        if (f[i] !== '*' && f[i] !== s[i])
+            return false;
+    }
+    return f.length === s.length;
+}
+/** Whether `subject` is a valid concrete subject: nonempty tokens, no wildcards or whitespace. */
+function isSubject(subject) {
+    return !!subject && subject.split('.').every((t) => !!t && !/[\s*>]/.test(t));
+}

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/scripts/machine-line.d.ts

@@ -0,0 +1,33 @@
+/**
+ * machine-line: drive the machine line example end to end.
+ *
+ * Starts unit routes on the factory line and plays the people: at every
+ * station people work (and at the inspector, where every route ends) a
+ * person takes the units off the station before and receives them; a
+ * technician clears alarms; an operator decides each failed handoff. The
+ * machines and the gateway do the rest over MQTT. MIX sets the share of
+ * routes minted from the automated manifest; the rest run the manual one,
+ * through the same workflow. Rows are watched on Long Tail's NATS.
+ *
+ * Usage (after `docker compose -f docker-compose.yml -f docker-compose.nats.yml -f docker-compose.machines.yml up -d --build`):
+ *   npm run machine:line
+ *   MIX=50 UNITS=8 npm run machine:line          # half automated, half manual, same factory
+ *   UNITS=8 BATCH=2 npm run machine:line
+ *   FAULT=jam npm run machine:line               # first route jams leaving FAULT_AT; operator retries
+ *   FAULT=reject DECIDE=scrap npm run machine:line
+ *
+ * Env vars:
+ *   BASE_URL      Long Tail API (default http://localhost:3000)
+ *   SIM_URL       mock line drill server (default http://localhost:8090)
+ *   NATS_URL      Long Tail NATS (default nats://localhost:4222), NATS_TOKEN (default dev_api_secret)
+ *   UNITS         units to run (default 6); BATCH units per route (default 2)
+ *   MIX           percent of routes on the automated manifest (default 100); the rest run manual
+ *   MACHINE_LINE_CONFIG, MACHINE_MANIFESTS   line and manifests (default the factory line and route-manifests.json)
+ *   FAULT         jam | incomplete | carrier_mismatch | unreadable | stall | reject | hold | estop | offline
+ *   FAULT_AT      machine the fault happens at (default the first machine)
+ *   DECIDE        operator decision on a failed handoff: retry | manual | scrap (default retry;
+ *                 manual where the row does not offer retry)
+ *   OFFLINE_S     how long FAULT=offline keeps the machine away (default 25)
+ *   HANDOFF_TIMEOUT  per-handoff timeout (default 5m); TIMEOUT_S whole run (default 300)
+ */
+export {};