bambu-printer-mcp 1.1.93 → 1.1.95
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +6 -3
- package/dist/3mf_parser.js +3 -2
- package/dist/cad/contracts.d.ts +10 -0
- package/dist/cad/contracts.js +41 -1
- package/dist/cad-engine.d.ts +5 -0
- package/dist/cad-engine.js +74 -3
- package/dist/counterpart/diagnostics.d.ts +163 -0
- package/dist/counterpart/diagnostics.js +816 -0
- package/dist/counterpart/flight-tools.d.ts +2 -2
- package/dist/counterpart/info.js +1 -0
- package/dist/counterpart/make-3mf.d.ts +10 -0
- package/dist/counterpart/make-3mf.js +472 -65
- package/dist/counterpart/model-plates.d.ts +8 -1
- package/dist/counterpart/model-plates.js +9 -4
- package/dist/counterpart/plate-filaments.d.ts +19 -0
- package/dist/counterpart/plate-filaments.js +72 -10
- package/dist/counterpart/remote.js +1 -0
- package/dist/counterpart/schemas.d.ts +8 -2
- package/dist/counterpart/schemas.js +1 -0
- package/dist/index.js +100 -2
- package/dist/tool-annotations.js +1 -0
- package/package.json +2 -2
- package/src/3mf_parser.ts +3 -2
- package/src/cad/contracts.ts +46 -1
- package/src/cad/examples/desk_clamp_hook.py +32 -0
- package/src/cad/examples/desk_edge_cable_holder.py +24 -0
- package/src/cad/examples/phone_stand.py +26 -0
- package/src/cad/geometry.py +52 -2
- package/src/cad/project3mf.py +426 -0
- package/src/cad/purpose.py +492 -0
- package/src/cad/worker.py +17 -2
- package/src/cad-engine.ts +73 -3
- package/src/counterpart/diagnostics.ts +775 -0
- package/src/counterpart/info.ts +1 -0
- package/src/counterpart/make-3mf.ts +446 -61
- package/src/counterpart/model-plates.ts +17 -5
- package/src/counterpart/plate-filaments.ts +75 -7
- package/src/counterpart/remote.ts +1 -0
- package/src/counterpart/schemas.ts +3 -0
- package/src/index.ts +83 -2
- package/src/tool-annotations.ts +1 -0
package/README.md
CHANGED
|
@@ -1069,7 +1069,7 @@ Dry-run the AMS match without uploading or starting a print. The tool reads `Met
|
|
|
1069
1069
|
|
|
1070
1070
|
#### list_3mf_plates
|
|
1071
1071
|
|
|
1072
|
-
List a designer's 3MF plates as Bambu Studio shows them when the file is opened, before slicing. A downloaded kit's six plates are six plates here too. For each plate it gives `index` (from 0, so `slice_stl`'s `slice_plate` is `index + 1`), `name`, the `objects` on it, and `sliced` (whether the file already holds its G-code). It also gives `plate_count` and the file's `title`, `designer` and `licence` when they're set. A plain 3MF with no plate metadata is one plate. `include_thumbnails` adds each plate's own preview from the file. Read-only.
|
|
1072
|
+
List a designer's 3MF plates as Bambu Studio shows them when the file is opened, before slicing. A downloaded kit's six plates are six plates here too. For each plate it gives `index` (from 0, so `slice_stl`'s `slice_plate` is `index + 1`), `name`, the `objects` on it, and `sliced` (whether the file already holds its G-code). To draw each plate from the open 3MF standard alone, `build_items` lists the root `3D/3dmodel.model` build items on it (0-based, in build order), and `parts` lists each model part of its objects once: `object_id` (the mesh object), `path` when that mesh is in another model part (`p:path`, e.g. `/3D/Objects/object_1.model`), `build_object_id` (the root object a build item places), `name`, `filament` (1-based, the project filament it prints in) and `painted: true` when slicer painting recolours some of its facets. Negative parts, modifiers and support blockers are not listed. It also gives `plate_count` and the file's `title`, `designer` and `licence` when they're set. A plain 3MF with no plate metadata is one plate. `include_thumbnails` adds each plate's own preview from the file. Read-only.
|
|
1073
1073
|
|
|
1074
1074
|
```json
|
|
1075
1075
|
{
|
|
@@ -1133,8 +1133,9 @@ If the project does not match those assumptions, the tool fails fast with a stru
|
|
|
1133
1133
|
|
|
1134
1134
|
[Counterpart](https://github.com/DMontgomery40/scan-to-make) (Scan to Make) reads printers through a small contract that this server and [mcp-3D-printer-server](https://github.com/DMontgomery40/mcp-3D-printer-server) share. Each tool declares an `outputSchema` and returns `structuredContent`, plus the same JSON as text for older clients. An error is returned as text only, because MCP clients check `structuredContent` against the schema even on errors. Other tools return an error's details in `structuredContent` (`status`, `retryable`, `suggestion`, `message`). When the printer refuses a print, the error also carries a stable `code`: `printer-command-rejected`, `printer-not-ready`, or `printer-upload-failed` when the file didn't reach the printer and no print command was sent, so a client can act on the code rather than the wording. A `print_3mf` call made with a progress token reports its LAN upload as MCP progress: `progress` is bytes sent, `total` the file's bytes, and `_meta["counterpart/stage"]` is `"upload"`, at most once per whole percent. `counterpart_printer_info` reports `capabilities.slicing` (`supports`, `copies`, `orient`), so a client can offer those choices without knowing the slicer. `counterpart_printer_info` and `counterpart_print_progress` take the usual optional `host`, `bambu_serial`, `bambu_token` and `bambu_model` (default `BAMBU_MODEL`) arguments.
|
|
1135
1135
|
|
|
1136
|
-
- **`counterpart_printer_info`** returns `{contract, server: {name, version}, printer: {kind: "bambu", model, displayName, serial, host}, capabilities}`. `displayName` is the model with its maker ("Bambu Lab P1S"), to show as given; it and `model` are absent when the model is unknown. `capabilities` lists progress, layers, the camera transport (`bambu-tcp` for A1/P1, `rtsp` for X1, P2S, H2 and X2D, `none` without a model), `cameraStream: true` for supported camera models, `filaments: "ams"`, pause, resume, cancel, `print3mf` and `gcode` (false on X2D). It sends nothing to the printer and never returns the access code.
|
|
1136
|
+
- **`counterpart_printer_info`** returns `{contract, server: {name, version}, printer: {kind: "bambu", model, displayName, serial, host}, capabilities}`. `displayName` is the model with its maker ("Bambu Lab P1S"), to show as given; it and `model` are absent when the model is unknown. `capabilities` lists progress, layers, the camera transport (`bambu-tcp` for A1/P1, `rtsp` for X1, P2S, H2 and X2D, `none` without a model), `cameraStream: true` for supported camera models, `diagnostics: true` (this server has `counterpart_diagnostics`), `filaments: "ams"`, pause, resume, cancel, `print3mf` and `gcode` (false on X2D). It sends nothing to the printer and never returns the access code.
|
|
1137
1137
|
- **`counterpart_self_check`** returns `{contract, server: {name, version}, ok, checks: [{name, ok, version?, message?}]}`: one check that the running server is its installed package's version, one per runtime dependency in `package.json` (it resolves from this install and loads, and the installed version meets an exact pin, `^` or `~` range), and `bambu-node patch`: every hunk of the bundled patch is in the installed bambu-node (a read-only reverse dry run, as postinstall checks), and it reads an H2D version report in memory as only the patched module can. Run it after an update; `ok` is false when any check fails. It sends nothing to the printer.
|
|
1138
|
+
- **`counterpart_diagnostics`** returns this server's own diagnostics for a bug report, `{package, version, files: [{name, content, truncated}], notes}`, for a client to add to its own export without knowing any log path. `files` are relative paths with UTF-8 text: `server.json` (package, version, Node.js, platform), `printers.json` (the configured printer's id, host, serial, model, connection route and whether an access code is set; firmware is not read), `settings.json` (this server's `BAMBU_*`, `SLICER_*`, `CAD_*` and similar settings), `slicer.json` (slicer type, path, profiles and the version its macOS bundle or AppImage name gives; the slicer is never run), `cad.json` (CAD runtime status), `tool-errors.log` (recent failed calls: tool and error, never arguments), `server-stderr.log` (this run's stderr, including MQTT and connection messages). The Bambu network plug-in and native helper logs are left out: other programs write them, and they can hold secrets this server cannot recognise. Optional `printer` (a serial or host) limits `printers.json` to that printer; optional `max_bytes` (default 4,194,304, at most 8,388,608) bounds the names, contents and notes together, keeping each file's newest lines. Redaction fails closed: the configured secrets and secret arguments go wherever they appear, also URL-encoded, JSON-escaped or base64; logged objects are redacted by key, and an object whose field names a secret loses its other values; settings show values only for known non-secret settings (any other only as `[set]`); and any log line that names a secret, in any spelling or encoding, is withheld whole as `[line withheld: may contain a secret]` with the lines that continue it, keeping its time and level. Serial numbers, error codes, firmware versions and whether a secret is set stay. A secret this server never held, on a line that names no secret, is the one thing it cannot recognise. A missing log is a note, never an error. It sends nothing to the printer.
|
|
1138
1139
|
- **`package.json` `counterpart`**: `{contract: "counterpart/1", notes, autoUpdate}`, readable with `npm view bambu-printer-mcp counterpart` before a client downloads a version. `notes` is one sentence about that release; `autoUpdate: false` asks clients not to install it automatically.
|
|
1139
1140
|
- **`counterpart_print_route`** reads or changes how prints and Stop/Pause/Resume reach the printer: `{route, mode, type, choices, savedTo}`, where `route` is `lan` (the local network, in the configured `BAMBU_DEFAULT_CONNECTION_MODE`) or `cloud` (Bambu Cloud through the [FULU bridge](docs/FULU.md)). Pass `route` to change it; the next print and control use it at once, and it is written to the `.env` in the server's working directory when one exists (`savedTo`, otherwise `null`). It is not part of the shared contract: it has no `outputSchema`, and mcp-3D-printer-server has no Bambu Cloud route.
|
|
1140
1141
|
- **`counterpart_print_progress`** returns `{contract, observedAt, state, job?, temps?, activeFilament?, problems}` from the printer's MQTT reports, which this server keeps while it is connected. A held session is answered from that cache without any printer traffic, and `observedAt` is when the printer sent the report. The server asks the printer for a full report only to fill an empty cache, and at most once every five minutes after the printer has been quiet that long. A printer that sends no report within 8 seconds is `offline`.
|
|
@@ -1325,9 +1326,11 @@ Read the `cad_design` prompt first. Supply `script` or a saved `script_path`, `o
|
|
|
1325
1326
|
|
|
1326
1327
|
Explicit `inputs: [{"name": "scan", "path": "/allowed/scan.stl"}]` snapshots the files a script may read as `INPUTS["scan"]`. For a mesh-only edit, use `mode: "mesh"` and return `trimesh.Trimesh`: it exports and validates STL plus renders, with `step: null` and a clear reason. For captured meshes, the injected `load_scan` helper takes explicit source units and an up-axis, converts coordinates to millimetres/Z-up, and grounds the mesh without fitting its size. Cleanup choices and labels belong to the caller’s rules; the MCP supplies execution, mesh libraries, checks and renders.
|
|
1327
1328
|
|
|
1329
|
+
For a multi-colour result, `build()` returns `project_3mf()`: a new project of named parts with filaments and plates, or (with `project_3mf("kit")` on a declared input 3MF, in `mode: "mesh"`) an edit that adds, replaces, renames or recolours parts and keeps the designer's print settings, painting, plates and other files byte for byte. The run writes `<name>.3mf` with the same writer as `counterpart_make_3mf` and returns `three_mf` and `three_mf_project` (each plate's parts and filaments, read back from the file). See [docs/CAD.md](docs/CAD.md#multi-colour-3mf-projects).
|
|
1330
|
+
|
|
1328
1331
|
`cad_status` and `cad_setup` expose `storage.expected_download_bytes`, `expected_installed_bytes` and cached measured `installed_bytes`; the first two are fresh-install budget estimates, not remaining transfer sizes. Setup failures carry `structuredContent.code`, `message`, `suggestion` and `retryable`, so clients do not parse wording.
|
|
1329
1332
|
|
|
1330
|
-
Runs wait for the environment's execution slot up to their own total timeout and return `queue_wait_ms`. Mark the selected result with `final: true`: each run's script-protected `cad-result.json` keeps the flag, full validation and artifact paths for recovery after restart. Check `status`, `valid` and the checks as well as `final`.
|
|
1333
|
+
Runs wait for the environment's execution slot up to their own total timeout and return `queue_wait_ms`. Mark the selected result with `final: true`: each run's script-protected `cad-result.json` keeps the flag, full validation and artifact paths for recovery after restart. Check `status`, `valid` and the checks as well as `final`. A solid design also declares `PURPOSE` (what it is for, what it holds, what carries the load, where its user is) and `use()` (itself as used, with the held object and the surface it meets); the run returns `purpose`, with each requirement evaluated on that assembly and the loads at each mount computed from it, and `ready`. `final: true` is recorded only when the design is ready; otherwise `final_refused` says why. Mesh mode and 3MF projects keep the earlier rule. Pass `role: "check"` for a fit-check part or reference export: every receipt records `role` (`"design"` when absent), a check run is never final, and every valid run that is not final carries `draft_reasons` saying why. See [docs/CAD.md](docs/CAD.md#purpose-and-the-design-as-used).
|
|
1331
1334
|
|
|
1332
1335
|
Unchanged declared inputs reuse immutable content-hash bundles, with `snapshot_bytes_added` and `snapshot_bytes_reused` in the result. Keep the referenced `.cad-inputs` bundles with saved designs. Previews now use depth cues and feature edges to reveal windows and recesses without a heavy renderer.
|
|
1333
1336
|
|
package/dist/3mf_parser.js
CHANGED
|
@@ -4,6 +4,7 @@ import * as fs from 'fs/promises';
|
|
|
4
4
|
import { AsyncLocalStorage } from 'node:async_hooks';
|
|
5
5
|
import { createHash, randomUUID } from 'node:crypto';
|
|
6
6
|
import * as path from 'node:path';
|
|
7
|
+
import { readSafe3mfArchive } from './safety/archive.js';
|
|
7
8
|
// Parses Bambu Studio's JSON config data
|
|
8
9
|
function parseBambuJSONConfig(jsonData) {
|
|
9
10
|
const config = {};
|
|
@@ -462,8 +463,8 @@ export async function analyze3MFAmsRequirements(filePath, plateIndex = 0) {
|
|
|
462
463
|
* is never a slice_info object.
|
|
463
464
|
*/
|
|
464
465
|
export async function analyze3MFPlateObjects(filePath, plateIndex = 0) {
|
|
465
|
-
|
|
466
|
-
const zip = await
|
|
466
|
+
// Bounded, with colliding or inconsistent entry names refused, as the other 3MF reads here.
|
|
467
|
+
const { zip } = await readSafe3mfArchive(filePath);
|
|
467
468
|
const plateNumber = plateIndex + 1;
|
|
468
469
|
const sliceInfo = zip.file('Metadata/slice_info.config');
|
|
469
470
|
if (!sliceInfo) {
|
package/dist/cad/contracts.d.ts
CHANGED
|
@@ -23,6 +23,7 @@ export declare const CAD_TOOLS: ({
|
|
|
23
23
|
parameters?: undefined;
|
|
24
24
|
output_dir?: undefined;
|
|
25
25
|
name?: undefined;
|
|
26
|
+
role?: undefined;
|
|
26
27
|
final?: undefined;
|
|
27
28
|
timeout_ms?: undefined;
|
|
28
29
|
model?: undefined;
|
|
@@ -106,6 +107,7 @@ export declare const CAD_TOOLS: ({
|
|
|
106
107
|
parameters?: undefined;
|
|
107
108
|
output_dir?: undefined;
|
|
108
109
|
name?: undefined;
|
|
110
|
+
role?: undefined;
|
|
109
111
|
final?: undefined;
|
|
110
112
|
timeout_ms?: undefined;
|
|
111
113
|
model?: undefined;
|
|
@@ -224,6 +226,12 @@ export declare const CAD_TOOLS: ({
|
|
|
224
226
|
maxLength: number;
|
|
225
227
|
description: string;
|
|
226
228
|
};
|
|
229
|
+
role: {
|
|
230
|
+
type: string;
|
|
231
|
+
enum: string[];
|
|
232
|
+
default: string;
|
|
233
|
+
description: string;
|
|
234
|
+
};
|
|
227
235
|
final: {
|
|
228
236
|
type: string;
|
|
229
237
|
default: boolean;
|
|
@@ -317,6 +325,7 @@ export declare const CAD_TOOLS: ({
|
|
|
317
325
|
script_path?: undefined;
|
|
318
326
|
parameters?: undefined;
|
|
319
327
|
output_dir?: undefined;
|
|
328
|
+
role?: undefined;
|
|
320
329
|
final?: undefined;
|
|
321
330
|
timeout_ms?: undefined;
|
|
322
331
|
model?: undefined;
|
|
@@ -439,6 +448,7 @@ export declare const CAD_TOOLS: ({
|
|
|
439
448
|
parameters?: undefined;
|
|
440
449
|
output_dir?: undefined;
|
|
441
450
|
name?: undefined;
|
|
451
|
+
role?: undefined;
|
|
442
452
|
final?: undefined;
|
|
443
453
|
};
|
|
444
454
|
required: string[];
|
package/dist/cad/contracts.js
CHANGED
|
@@ -103,7 +103,7 @@ export const CAD_TOOLS = [
|
|
|
103
103
|
},
|
|
104
104
|
{
|
|
105
105
|
name: "cad_run",
|
|
106
|
-
description: "Build parametric CAD headlessly in OS confinement. Read cad_design first: declare literal P = {...} and build() returning a build123d Shape. Supply script OR script_path; parameters overrides saved named values in one call before derived dimensions. Calls wait for the environment’s exclusive execution slot up to their own deadline and report queue_wait_ms. Each call creates a private immutable subfolder under allowed output_dir, never overwriting previous artifacts. The saved .py and .parameters.json are the recovery checkpoint even after cancellation. Returns independently measured geometry, STL/STEP, six orthographic renders, a perspective view and a contact sheet (with next: read the perspective view before the next change), the closest approach between every pair of solids (bodies), problems, what was checked and not checked,
|
|
106
|
+
description: "Build parametric CAD headlessly in OS confinement. Read cad_design first: declare literal P = {...} and build() returning a build123d Shape. Supply script OR script_path; parameters overrides saved named values in one call before derived dimensions. Calls wait for the environment’s exclusive execution slot up to their own deadline and report queue_wait_ms. Each call creates a private immutable subfolder under allowed output_dir, never overwriting previous artifacts. The saved .py and .parameters.json are the recovery checkpoint even after cancellation. Returns independently measured geometry, STL/STEP, six orthographic renders, a perspective view and a contact sheet (with next: read the perspective view before the next change), the closest approach between every pair of solids (bodies), problems, what was checked and not checked, printed: whatever the script wrote with print(), capped at 4000 characters, so a design can report a number it computed, and, in solid mode, purpose and ready: the script's PURPOSE compiled into requirements and evaluated on its use() assembly (held objects, mounts, loads computed from the geometry, facing the user). valid means only that the exported geometry is sound; final: true is recorded only when the design is ready (final_refused says why not).",
|
|
107
107
|
inputSchema: {
|
|
108
108
|
type: "object",
|
|
109
109
|
properties: {
|
|
@@ -147,6 +147,12 @@ export const CAD_TOOLS = [
|
|
|
147
147
|
maxLength: 64,
|
|
148
148
|
description: "Plain file stem for STL, STEP, Python and parameter artifacts.",
|
|
149
149
|
},
|
|
150
|
+
role: {
|
|
151
|
+
type: "string",
|
|
152
|
+
enum: ["design", "check"],
|
|
153
|
+
default: "design",
|
|
154
|
+
description: 'What this run is: "design" (the default) for the design itself, or "check" for a fit check part, a reference export or any other run that must never become the model. A check run is never selected as final, evaluates no PURPOSE, and its receipt says role: "check".',
|
|
155
|
+
},
|
|
150
156
|
final: {
|
|
151
157
|
type: "boolean",
|
|
152
158
|
default: false,
|
|
@@ -209,6 +215,38 @@ export const CAD_TOOLS = [
|
|
|
209
215
|
type: "string",
|
|
210
216
|
description: "The script's own print() output from this run, capped at 4000 characters (build.log keeps the rest). The script's words, not a measurement by the engine.",
|
|
211
217
|
},
|
|
218
|
+
ready: {
|
|
219
|
+
type: "boolean",
|
|
220
|
+
description: "Solid mode: the design's PURPOSE is declared and every requirement it compiles to passed on use(). final: true is recorded only when ready. Absent for mesh mode and 3MF projects.",
|
|
221
|
+
},
|
|
222
|
+
purpose: {
|
|
223
|
+
type: "object",
|
|
224
|
+
description: "Solid mode: what PURPOSE says the part is for (for, modelled_on), the product classes its words put it in, each requirement compiled from it with status pass, fail or not_modelled and what it says (held objects sit on the part, each mount touches its world surface, the exposed face of a held screen turns to the user's eye, tape stress and resting stability under the computed loads), the loads at the mounts (gravity, jolts, a hand's press), and blocked: what keeps it from ready.",
|
|
225
|
+
},
|
|
226
|
+
final_requested: { type: "boolean" },
|
|
227
|
+
role: {
|
|
228
|
+
type: "string",
|
|
229
|
+
enum: ["design", "check"],
|
|
230
|
+
description: 'The run\'s role as cad_run was given it: "design", or "check" for a check part or reference export that is never the model. Every receipt carries it.',
|
|
231
|
+
},
|
|
232
|
+
draft_reasons: {
|
|
233
|
+
type: "array",
|
|
234
|
+
items: { type: "string" },
|
|
235
|
+
description: "On every valid run that is not final: why not, in plain sentences (the designer did not mark it final; it is not ready, then what blocks it; or it is a check part, not the design). A client that keeps such a run as a draft shows these.",
|
|
236
|
+
},
|
|
237
|
+
final_refused: {
|
|
238
|
+
type: "array",
|
|
239
|
+
items: { type: "string" },
|
|
240
|
+
description: "Why final: true was not recorded, each as the step that fixes it (for example: model the dash as world:dash in use() so the tape mount can be checked). next quotes the first ones; the run is not the model until a run with final: true is ready.",
|
|
241
|
+
},
|
|
242
|
+
three_mf: {
|
|
243
|
+
type: "string",
|
|
244
|
+
description: "When build() returned project_3mf(): the written 3MF project, ready for slice_stl.",
|
|
245
|
+
},
|
|
246
|
+
three_mf_project: {
|
|
247
|
+
type: "object",
|
|
248
|
+
description: "When build() returned project_3mf(): base (the edited input alias, or null for a new project), changes, and the written file read back as list_3mf_plates reads it (plates with build_items, parts and filaments; project_filaments).",
|
|
249
|
+
},
|
|
212
250
|
seconds: { type: "number" },
|
|
213
251
|
}, [
|
|
214
252
|
"valid",
|
|
@@ -339,6 +377,7 @@ export const CAD_DESIGN_PROMPT = {
|
|
|
339
377
|
description: "MCP-owned rules for headless build123d designs and one-call parameter revisions.",
|
|
340
378
|
text: `Use code-CAD for dimensioned functional designs and parameter edits. Build in millimetres with build123d 0.13.0; the MCP owns the Python environment, execution, export, validation and rendering. Check cad_status and use cad_setup with install: true when needed. No Blender, Fusion, network or printer access is available to your script.
|
|
341
379
|
A new design starts from the product, in this order. First, name two or three products a person would buy for this request (search when you are not sure what is sold) and say which one the design follows. Second, choose from the cookbook by purpose: the list below says what each example is for (cad_examples with no name returns it with each one's pattern and product). Read the example whose use is nearest the request, with cad_examples and its name, before deciding anything else, and adapt its form and pattern, never its sizes. Third, and only then, choose the mechanism (a clamp, screw, spring, hinge or snap) and read a second example for it if you need one. A mechanism chosen before the product gives a bracket with the mechanism bolted on.
|
|
380
|
+
Then state the purpose as data, before any geometry: a literal PURPOSE = {...} beside P (cad_run reads it from the source; parameters cannot change it). "for": what it is for in the person's words (who uses it, where, doing what); "modelled_on": the bought product; "holds": [{"body": name, "mass_g": grams}] for what it carries; "mounts": [{"body": name, "by": "tape", "rests", "screw", "clamp", "hook" or "other"}] for each surface that takes the load; "user": [x, y, z], the eye of the person who uses it, in mm in the use() frame, when it shows them something; optional "jolt_g", "press_n", "reach_mm", "material" and "faces": {"body": name, "within_deg": 25}. Its words add requirements whatever you list: a holder, hook, stand, dock, mount, rack, bracket, cradle or organizer must name what it holds and what it mounts to; anything in a vehicle takes jolts of at least 1.5 g in every direction; a phone, tablet or screen it holds must face the user's eye within 25 degrees. Then define use() beside build(): return Compound(children=[...]) of the part as it is used, Z up and gravity along -Z, with each held object at its real size and pose labelled "held:<body>" and each surface it meets as a solid slab where it really is (a dash face at its real angle, a desk's underside, a wall) labelled "world:<body>", all touching the part where they really touch. cad_run computes the loads at each mount from that geometry (gravity on the part and what it holds, the jolts, a hand pressing the held object), checks tape against 3M VHB's published stresses and that a resting part neither tips, lifts nor slides, checks that a held screen faces the user, draws renders.use (from the user's eye when given) and reports it all in purpose. final: true is recorded only when ready is true; until then the result lists final_refused. A run that is not the design itself (a part exported only for cad_check_fit, a reference, a diagnostic) is a check: pass role: "check" to every cad_run that is not the design itself, so it is never mistaken for the model (it is never final and evaluates no PURPOSE). Every valid run that is not final carries draft_reasons, saying why. When a requirement fails, change the design the way the bought products solve it (a joint that aims it, a broader pad, a wider or heavier base), never the purpose.
|
|
342
381
|
The cookbook, by what each example is for:
|
|
343
382
|
${cadExampleLines()}
|
|
344
383
|
Form first: build the product's shape, not a profile pushed up. Before any geometry, write the concept as the script's opening docstring, the way every cookbook example does: what it is, then "Modelled on:" the bought product you named, its mechanism, the load path, the print orientation and why. A script whose header names no product was designed from the mechanism. build123d has loft (through sections of different shape), sweep (a section along a path or a Helix), revolve, fillet, chamfer, offset and shell as well as extrude; use the one the product's surface calls for: lofted where a hand closes round it, revolved where it turns, swept where it runs like a bent rod or a thread, filleted where two surfaces meet under load. Extrude a flat profile only for something that really is a plate or a lever, or for a print-in-place mechanism or spring that must lie in the layers, and say that reason in the result. Choose the print orientation after the form: split a part, turn it or accept a modest support before flattening its design.
|
|
@@ -349,6 +388,7 @@ Captured mesh preparation: load_scan(name, source_units="m" or "mm", up_axis="x"
|
|
|
349
388
|
Fit reference workflow: return load_scan("scan", source_units="m", up_axis="y") from build() in mode: "mesh" to export an unchanged, prepared reference STL for cad_check_fit. Declare every linked OBJ/MTL/texture asset. If you crop, simplify, fill, or otherwise alter this reference, report exactly what you excluded/changed and that the fit check proves only that reduced reference in the stated pose. A fit check against a scan is information; it must never resize or override an interface specified by measured dimensions. Keep those measured interfaces and report the discrepancy.
|
|
350
389
|
Result selection and edits: set final: true only on the result you select. cad-result.json in each immediate run folder is protected from script writes and retains final, completed_at, lineage_id (source hash), full checks and artifact paths; clients can discover the latest completed final record after restart without rebuilding. Final is a selection marker, not a replacement for valid/checks. Queued calls may expire with cad-queue-timeout before dispatch; do not automatically replay. Unchanged declared files reuse a read-only content-addressed bundle under output_dir/.cad-inputs, preserving filenames and restricting reads to that bundle. Keep this shared cache with the saved runs.
|
|
351
390
|
Mesh cleanup workflow: return a trimesh.Trimesh in mode: "mesh". Load the prepared mesh, fit needed geometry with NumPy/SciPy, rebuild regular sections/features with build123d or manifold3d CrossSection/extrusion/revolve, and combine meshes with manifold3d booleans. scikit-image supplies marching cubes for voxel/SDF work; Shapely supplies planar operations; Pillow supplies image/texture reads. Keep numeric choices in P and regenerate from declared inputs. Validate closure, winding, manifold status, dimensions and all six views using cad_run. What to regularise, infer, preserve or label comes from the caller's cleanup rules, not this engine prompt.
|
|
391
|
+
Multi-colour 3MF projects: build() may return project_3mf() instead of a shape. A new project: p = project_3mf(); p.add_part(shape, name="Lid", filament=2, object="Box", plate=1) for each part (parts that share object= are one object, printed as one piece; plates from 1), in solid mode with build123d shapes (the checks fuse each object's parts) or mode: "mesh" with trimesh parts. Editing a designer's 3MF: declare it as an input and p = project_3mf("kit") in mode: "mesh"; p.objects lists its objects (name, id, plate; p.object(id or unique name)) and their parts (name, id, filament, painted, mesh: a trimesh in the object's frame); p.add_part(shape, name=..., filament=..., object="Body") adds a part in that object's frame, p.replace_part(part, mesh) swaps a part's mesh (its painting goes with the old mesh) and p.set_part(part, name=..., filament=...) renames or recolours one; everything else in the file (print settings, painting, plates, other parts) is kept. cad_run writes <name>.3mf beside the STL and returns three_mf and three_mf_project (each plate's parts and filaments, read back from the file); slice it with slice_stl, never by rebuilding it from the STL.
|
|
352
392
|
Captured scan touch-up: t = scan_touchup(load_scan("scan", source_units="m", up_axis="y", ground=False), colour="colour", normal="normal", edge_mm=0.4) takes a textured capture (declare its OBJ, MTL and colour and normal map PNGs as inputs; pass the map aliases). It removes loose pieces and spikes, closes holes and refines to edge_mm without shrinking the body. t.regions() prints the colour regions (id, colour, area, size, flatness; 0 is the body) to build.log and saves regions.png in the run folder: read both, then name regions by id in the same scan and edge_mm. t.flatten(ids, shape="plane" or "curved"), t.bead(id, diameter_mm, proud_mm), t.cord(id, diameter_mm, proud_mm) (a cord follows its region's own curve) and t.seat(height_mm) record steps; return t.mesh(relief_gain=1.0), which adds the normal map's measured relief, applies the steps with manifold3d and prints its changes. Keep relief_gain at 1: a larger gain amplifies the map's noise, not stitches. When the caller's rules call for a textile's relief the scan missed (fabric, knit, crochet the photos show raised), t.texture_relief(height_mm, regions=None) raises its stitch pattern from the colour texture on the textile only (never flattened, beaded or corded regions); about 0.6 to 1.0 mm peak to peak prints visibly. It is off unless called: never for hard objects, printed graphics or labels.
|
|
353
393
|
The result includes paths, millimetre bounds/size, mesh and STEP volumes, solid count, watertight/manifold/winding/STEP checks, bodies (closest approach between solids, contact with the print plate at Z = 0, labelled bodies that are not one solid), problems, checked and not_checked, six orthographic renders (front, back, left, right, top, bottom), a perspective view from the front right and above, and a contact sheet with the perspective view large beside the six. Fix every entry in problems before selecting a result; an empty problems list proves nothing listed in not_checked. After every cad_run, Read its perspective view (renders.perspective, as the result's next says) before the next cad_run or any other change: a run you have not looked at tells you nothing about the form. Judge the form from the perspective view first: would a person recognise the product and want it? Then inspect all six; revise visible defects. Before the final run, list what the views show is wrong against the bought product you named (for a scan, the object in its photos), and fix each one or report it. To get a number out of a design (a spring force, a strain, a clearance you derived), print() it in the script: the result returns it as printed, with no need to make a run fail. A valid mesh or nominal parameter does not prove the requested dimension: measure the actual exported interfaces. Use cad_check_fit on a model and reference STL with an explicit rigid transform; report raw-scan interference and minimum gap. Calipers are authoritative but disagreement with a scan is unresolved measurement evidence, not permission to silently rescale it. Check assembly/insertion paths and actual articulated poses, not sums of local joint limits or reference points alone. Printing, clearance under load, supports and motion need separate evidence.
|
|
354
394
|
Fit, flexure and thread parameters: put each interface's nominal size, its source (measured, published, or assumed), the print correction, and the design fit in P as separate named values, so a fit report revises one number without resending the script. Model every dimension you claim: a parameter the geometry never uses (a wallet or case width that no cut or wall reads) is a defect; use it or remove it. Shape flexures so their bending lies in the layer plane of the exported print orientation, with the stroke, preload, and hard-stop gap as P values; build the stopped pose as well as the rest pose when checking. Model printed threads as explicit coarse geometry with the same pitch on both sides and clearance as a radial P offset; never scale a screw to clear its hole.
|
package/dist/cad-engine.d.ts
CHANGED
|
@@ -64,5 +64,10 @@ export declare class CadEngine {
|
|
|
64
64
|
private requireSupportedStorage;
|
|
65
65
|
private inputFile;
|
|
66
66
|
run(args: CadArguments, signal?: AbortSignal): Promise<Record<string, unknown>>;
|
|
67
|
+
/**
|
|
68
|
+
* When build() returned project_3mf(), write <name>.3mf from the sandbox's manifest and part STLs (this trusted
|
|
69
|
+
* process writes it; the sandbox only meshed the parts) and read it back as list_3mf_plates does.
|
|
70
|
+
*/
|
|
71
|
+
private project3mf;
|
|
67
72
|
checkFit(args: CadArguments, signal?: AbortSignal): Promise<Record<string, unknown>>;
|
|
68
73
|
}
|
package/dist/cad-engine.js
CHANGED
|
@@ -6,6 +6,8 @@ import { createHash, randomUUID } from "node:crypto";
|
|
|
6
6
|
import { createRequire } from "node:module";
|
|
7
7
|
import { performance } from "node:perf_hooks";
|
|
8
8
|
import { CadRefusal, cadFailure } from "./cad/refusal.js";
|
|
9
|
+
import { writeCadProject3mf } from "./counterpart/make-3mf.js";
|
|
10
|
+
import { listModelPlates } from "./counterpart/model-plates.js";
|
|
9
11
|
import { withCadLock } from "./cad/serial.js";
|
|
10
12
|
import { measureEnvironment, snapshotInputs, storageInfo, } from "./cad/storage.js";
|
|
11
13
|
import { cadSandbox, defaultCadSystem } from "./cad/process.js";
|
|
@@ -365,6 +367,8 @@ export class CadEngine {
|
|
|
365
367
|
"worker.py",
|
|
366
368
|
"geometry.py",
|
|
367
369
|
"scan_touchup.py",
|
|
370
|
+
"project3mf.py",
|
|
371
|
+
"purpose.py",
|
|
368
372
|
"process.ts",
|
|
369
373
|
"storage.ts",
|
|
370
374
|
"serial.ts",
|
|
@@ -433,12 +437,18 @@ export class CadEngine {
|
|
|
433
437
|
"inputs",
|
|
434
438
|
"mode",
|
|
435
439
|
"final",
|
|
440
|
+
"role",
|
|
436
441
|
]);
|
|
437
442
|
const root = await this.allowedDirectory(args.output_dir);
|
|
438
443
|
const name = plainName(args.name);
|
|
439
444
|
const timeout = milliseconds(args.timeout_ms), deadline = started + timeout;
|
|
440
445
|
if (args.final !== undefined && typeof args.final !== "boolean")
|
|
441
446
|
throw new Error("final must be a boolean.");
|
|
447
|
+
// What the run is for, on every receipt: the design itself, or a check part or reference export that must
|
|
448
|
+
// never become the person's model (scan-to-make #790 keeps the last valid run as a draft). Absent is design.
|
|
449
|
+
if (args.role !== undefined && args.role !== "design" && args.role !== "check")
|
|
450
|
+
throw new Error('role must be "design" or "check".');
|
|
451
|
+
const role = args.role === "check" ? "check" : "design";
|
|
442
452
|
if (root.split(path.sep).includes(".cad-inputs"))
|
|
443
453
|
throw new Error("output_dir cannot be inside the reserved CAD input cache.");
|
|
444
454
|
const remaining = () => {
|
|
@@ -529,9 +539,12 @@ export class CadEngine {
|
|
|
529
539
|
}
|
|
530
540
|
}
|
|
531
541
|
await fs.writeFile(parameters, JSON.stringify({ ...previous, ...overrides }), { mode: 0o600 });
|
|
542
|
+
// Not final until the engine has found it ready: an interrupted run never reads as selected.
|
|
532
543
|
await atomicJson(resultManifest, {
|
|
533
544
|
status: "pending",
|
|
534
|
-
final:
|
|
545
|
+
final: false,
|
|
546
|
+
...(args.final === true ? { final_requested: true } : {}),
|
|
547
|
+
role,
|
|
535
548
|
lineage_id: lineage,
|
|
536
549
|
});
|
|
537
550
|
try {
|
|
@@ -551,6 +564,7 @@ export class CadEngine {
|
|
|
551
564
|
script,
|
|
552
565
|
parameters,
|
|
553
566
|
mode,
|
|
567
|
+
role,
|
|
554
568
|
inputs: snapshots,
|
|
555
569
|
};
|
|
556
570
|
await fs.writeFile(request, JSON.stringify(base), { mode: 0o600 });
|
|
@@ -588,14 +602,41 @@ export class CadEngine {
|
|
|
588
602
|
}
|
|
589
603
|
const checked = JSON.parse((await this.confined("inspect", request, job, protectedFiles, remaining(), signal, readableInputs)).stdout);
|
|
590
604
|
const printed = built.stdout.trim();
|
|
605
|
+
const project = await this.project3mf(job, name, snapshots);
|
|
606
|
+
// final is the designer's selection, and it no longer stands on its own word (scan-to-make #608): a solid
|
|
607
|
+
// design is selected only when the engine found it ready, its purpose evaluated on the design as used.
|
|
608
|
+
const blocked = Array.isArray(checked.purpose?.blocked) ? checked.purpose.blocked : [];
|
|
609
|
+
const refused = args.final === true && role === "check"
|
|
610
|
+
? ['A check run is never the design: run the design itself with role "design" to mark it final.']
|
|
611
|
+
: args.final === true && checked.ready === false
|
|
612
|
+
? (Array.isArray(checked.purpose?.blocked) && checked.purpose.blocked.length ? checked.purpose.blocked : ["the engine did not find this design ready"])
|
|
613
|
+
: undefined;
|
|
591
614
|
const result = {
|
|
592
615
|
...checked,
|
|
616
|
+
...project,
|
|
593
617
|
// Beside the image paths, where the next step is decided.
|
|
594
|
-
next:
|
|
618
|
+
next: refused
|
|
619
|
+
? `Not selected as final, so it is not yet the model. To make it final: ${refused.slice(0, 3).join(" ")}${refused.length > 3 ? ` (and ${refused.length - 3} more in final_refused)` : ""} Then run again with final: true. Read renders.perspective and renders.use first.`
|
|
620
|
+
: "Read renders.perspective before the next cad_run or any other change: say what it shows is wrong against what you are making (the bought product you named, or the object in the photos), then fix that." +
|
|
621
|
+
(checked.purpose && checked.ready === false && Array.isArray(checked.purpose.blocked)
|
|
622
|
+
? ` Not ready yet, so final: true would be refused. To make it ready: ${checked.purpose.blocked.slice(0, 3).join(" ")}`
|
|
623
|
+
: ""),
|
|
595
624
|
// The script's own print() output: its words, not a measurement by this engine.
|
|
596
625
|
...(printed ? { printed: printed.length > 4000 ? printed.slice(0, 4000) + "\n[cut at 4000 characters; build.log has the rest]" : printed } : {}),
|
|
597
626
|
status: "completed",
|
|
598
|
-
final: args.final === true,
|
|
627
|
+
final: args.final === true && !refused,
|
|
628
|
+
...(refused ? { final_requested: true, final_refused: refused } : {}),
|
|
629
|
+
role,
|
|
630
|
+
// Why a valid run is not the final model, in plain sentences, for a client that keeps it as a draft.
|
|
631
|
+
...(checked.valid === true && !(args.final === true && !refused)
|
|
632
|
+
? {
|
|
633
|
+
draft_reasons: role === "check"
|
|
634
|
+
? ["This is a check part or reference export, not the design."]
|
|
635
|
+
: args.final === true
|
|
636
|
+
? ["It isn't ready, so the engine didn't mark it final.", ...refused]
|
|
637
|
+
: ["The designer didn't mark this run final.", ...(checked.ready === false ? blocked : [])],
|
|
638
|
+
}
|
|
639
|
+
: {}),
|
|
599
640
|
completed_at: new Date().toISOString(),
|
|
600
641
|
lineage_id: lineage,
|
|
601
642
|
result_manifest: resultManifest,
|
|
@@ -624,6 +665,7 @@ export class CadEngine {
|
|
|
624
665
|
status: "failed",
|
|
625
666
|
final: false,
|
|
626
667
|
final_requested: args.final === true,
|
|
668
|
+
role,
|
|
627
669
|
lineage_id: lineage,
|
|
628
670
|
message: e instanceof Error ? e.message : String(e),
|
|
629
671
|
script,
|
|
@@ -636,6 +678,35 @@ export class CadEngine {
|
|
|
636
678
|
}
|
|
637
679
|
}, "run", signal, deadline);
|
|
638
680
|
}
|
|
681
|
+
/**
|
|
682
|
+
* When build() returned project_3mf(), write <name>.3mf from the sandbox's manifest and part STLs (this trusted
|
|
683
|
+
* process writes it; the sandbox only meshed the parts) and read it back as list_3mf_plates does.
|
|
684
|
+
*/
|
|
685
|
+
async project3mf(job, name, inputs) {
|
|
686
|
+
const manifestPath = path.join(job, `${name}.project.json`);
|
|
687
|
+
const st = await fs.lstat(manifestPath).catch(() => undefined);
|
|
688
|
+
if (!st)
|
|
689
|
+
return {};
|
|
690
|
+
if (!st.isFile() || st.size > 1024 * 1024)
|
|
691
|
+
throw new Error("The design's 3MF project manifest is unsafe or too large.");
|
|
692
|
+
const partsDir = path.join(job, `${name}.parts`);
|
|
693
|
+
const dir = await fs.lstat(partsDir).catch(() => undefined);
|
|
694
|
+
if (!dir?.isDirectory())
|
|
695
|
+
throw new Error("The design's 3MF project parts are missing.");
|
|
696
|
+
const out = path.join(job, `${name}.3mf`);
|
|
697
|
+
const written = await writeCadProject3mf(JSON.parse(await fs.readFile(manifestPath, "utf8")), partsDir, inputs, out);
|
|
698
|
+
const listed = await listModelPlates(out);
|
|
699
|
+
return {
|
|
700
|
+
three_mf: out,
|
|
701
|
+
three_mf_project: {
|
|
702
|
+
base: written.base,
|
|
703
|
+
changes: written.changed,
|
|
704
|
+
plate_count: listed.plate_count,
|
|
705
|
+
plates: listed.plates.map(plate => ({ index: plate.index, name: plate.name, build_items: plate.build_items, parts: plate.parts, filaments: plate.filaments })),
|
|
706
|
+
project_filaments: listed.project_filaments,
|
|
707
|
+
},
|
|
708
|
+
};
|
|
709
|
+
}
|
|
639
710
|
async checkFit(args, signal) {
|
|
640
711
|
only(args, [
|
|
641
712
|
"model",
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
export declare const DIAGNOSTICS_DEFAULT_BYTES = 4194304;
|
|
2
|
+
export declare const DIAGNOSTICS_MAX_BYTES = 8388608;
|
|
3
|
+
export type DiagnosticsFile = {
|
|
4
|
+
name: string;
|
|
5
|
+
content: string;
|
|
6
|
+
truncated: boolean;
|
|
7
|
+
};
|
|
8
|
+
export type DiagnosticsResult = {
|
|
9
|
+
package: string;
|
|
10
|
+
version: string;
|
|
11
|
+
files: DiagnosticsFile[];
|
|
12
|
+
notes: string[];
|
|
13
|
+
};
|
|
14
|
+
/** A file on disk, whose tail goes in, or text the server composes. `missing` is the note when the file is absent. */
|
|
15
|
+
export type DiagnosticsSource = {
|
|
16
|
+
name: string;
|
|
17
|
+
file: string;
|
|
18
|
+
missing?: string;
|
|
19
|
+
} | {
|
|
20
|
+
name: string;
|
|
21
|
+
text: string;
|
|
22
|
+
};
|
|
23
|
+
export declare const DIAGNOSTICS_INPUT_PROPERTIES: {
|
|
24
|
+
printer: {
|
|
25
|
+
type: string;
|
|
26
|
+
description: string;
|
|
27
|
+
};
|
|
28
|
+
max_bytes: {
|
|
29
|
+
type: string;
|
|
30
|
+
minimum: number;
|
|
31
|
+
maximum: number;
|
|
32
|
+
description: string;
|
|
33
|
+
};
|
|
34
|
+
};
|
|
35
|
+
export declare const DIAGNOSTICS_OUTPUT_SCHEMA: {
|
|
36
|
+
type: "object";
|
|
37
|
+
properties: {
|
|
38
|
+
package: {
|
|
39
|
+
type: string;
|
|
40
|
+
description: string;
|
|
41
|
+
};
|
|
42
|
+
version: {
|
|
43
|
+
type: string;
|
|
44
|
+
description: string;
|
|
45
|
+
};
|
|
46
|
+
files: {
|
|
47
|
+
type: string;
|
|
48
|
+
items: {
|
|
49
|
+
type: string;
|
|
50
|
+
properties: {
|
|
51
|
+
name: {
|
|
52
|
+
type: string;
|
|
53
|
+
description: string;
|
|
54
|
+
};
|
|
55
|
+
content: {
|
|
56
|
+
type: string;
|
|
57
|
+
description: string;
|
|
58
|
+
};
|
|
59
|
+
truncated: {
|
|
60
|
+
type: string;
|
|
61
|
+
description: string;
|
|
62
|
+
};
|
|
63
|
+
};
|
|
64
|
+
required: string[];
|
|
65
|
+
};
|
|
66
|
+
};
|
|
67
|
+
notes: {
|
|
68
|
+
type: string;
|
|
69
|
+
items: {
|
|
70
|
+
type: string;
|
|
71
|
+
};
|
|
72
|
+
description: string;
|
|
73
|
+
};
|
|
74
|
+
};
|
|
75
|
+
required: string[];
|
|
76
|
+
};
|
|
77
|
+
/** The max_bytes a call asks for, checked. */
|
|
78
|
+
export declare function diagnosticsBudget(value: unknown): number;
|
|
79
|
+
/**
|
|
80
|
+
* Keeps what this server writes through console.error and console.warn (its stderr diagnostics: MQTT, connection,
|
|
81
|
+
* bridge and slicer messages) in memory as well. Writing to stderr is unchanged. Idempotent.
|
|
82
|
+
*/
|
|
83
|
+
export declare function captureServerLog(): void;
|
|
84
|
+
/** Records a failed tool call: its name and error, not its arguments. */
|
|
85
|
+
export declare function recordToolError(tool: string, error: unknown): void;
|
|
86
|
+
/** Remembers the values of a tool call's secret-named arguments (access codes, API keys, tokens) for redaction. */
|
|
87
|
+
export declare function rememberSecretArguments(args: unknown): void;
|
|
88
|
+
export declare const serverLogText: () => string;
|
|
89
|
+
export declare const toolErrorsText: () => string;
|
|
90
|
+
/** For tests: forgets what was recorded. */
|
|
91
|
+
export declare function resetDiagnosticsMemory(): void;
|
|
92
|
+
/** Text with \\uXXXX, \\xXX and %XX escapes read, so "\\x70assword" and "pass%77ord" are seen as "password". */
|
|
93
|
+
export declare function decodeEscapes(text: string): string;
|
|
94
|
+
export declare function isSecretName(name: string): boolean;
|
|
95
|
+
/** The values of this environment's secret-named variables. */
|
|
96
|
+
export declare function environmentSecrets(env?: NodeJS.ProcessEnv): string[];
|
|
97
|
+
/** text with every known secret (configured, in this environment, or seen in tool arguments) removed in each encoded form. */
|
|
98
|
+
export declare function removeKnownSecrets(text: string, secrets?: Iterable<string>): string;
|
|
99
|
+
export declare const WITHHELD = "[line withheld: may contain a secret]";
|
|
100
|
+
/** The canonical phrases of REASONS, in order: all a withheld marker may name. */
|
|
101
|
+
export declare const WITHHELD_REASONS: string[];
|
|
102
|
+
/** The withheld marker for these lines: WITHHELD, naming the REASONS they mention ("claude auth login" over "auth login"). */
|
|
103
|
+
export declare function withheldMarker(lines: string): string;
|
|
104
|
+
/** Whether a line may carry a secret: a secret word anywhere in it, in any spelling or encoding. */
|
|
105
|
+
export declare function suspectLine(line: string): boolean;
|
|
106
|
+
/**
|
|
107
|
+
* Free text with each suspect line withheld whole, with the lines that continue it; its time and level stay. A suspect
|
|
108
|
+
* line that is only a name and a safe value stays, but what continues it is withheld all the same.
|
|
109
|
+
*/
|
|
110
|
+
export declare function withholdSuspectLines(text: string): string;
|
|
111
|
+
/**
|
|
112
|
+
* text with every secret this module can recognise replaced, failing closed: known secret values in every encoded
|
|
113
|
+
* form; then the named patterns (values of secret-named keys, cookies, authorization headers, URL credentials,
|
|
114
|
+
* emails, JWTs, bare tokens, PEM blocks, other people's home folders); then every line that still names a secret
|
|
115
|
+
* withheld whole. Serial numbers, hosts, error codes and lowercase hashes stay.
|
|
116
|
+
*/
|
|
117
|
+
export declare function redactText(text: string, secrets?: Iterable<string>): string;
|
|
118
|
+
/** The pattern rules alone (redactText without withholding lines): what each named form becomes. */
|
|
119
|
+
export declare function redactPatterns(text: string, secrets?: Iterable<string>): string;
|
|
120
|
+
/**
|
|
121
|
+
* A logged or composed value with its secrets removed, by its structure: a secret-named key's value goes (a bare
|
|
122
|
+
* measure such as tokenCount stays); an object where any field names a secret ({"name":"BAMBU_ACCESS_CODE", …})
|
|
123
|
+
* loses its other scalars; a string holding JSON is read and walked; any other string is redacted as text, one
|
|
124
|
+
* value per line, so a string that names a secret is withheld.
|
|
125
|
+
*/
|
|
126
|
+
export declare function redactValue(value: unknown, secrets?: Iterable<string>, depth?: number): unknown;
|
|
127
|
+
/** A JSON file's text with its values redacted by structure (it stays valid JSON); other text as free text. */
|
|
128
|
+
export declare function redactJsonText(text: string, secrets?: Iterable<string>): string;
|
|
129
|
+
/** The last `bytes` of text, starting at a whole line where one starts inside it. */
|
|
130
|
+
export declare function tailText(text: string, bytes: number): {
|
|
131
|
+
text: string;
|
|
132
|
+
cut: boolean;
|
|
133
|
+
};
|
|
134
|
+
/**
|
|
135
|
+
* The bundle from sources, in their order: each file's tail, redacted. Small sources go in whole; the rest share what
|
|
136
|
+
* is left equally, keeping their newest lines. Names, contents and notes together stay within maxBytes.
|
|
137
|
+
*/
|
|
138
|
+
export declare function buildDiagnostics(options: {
|
|
139
|
+
package: string;
|
|
140
|
+
version: string;
|
|
141
|
+
sources: DiagnosticsSource[];
|
|
142
|
+
notes?: string[];
|
|
143
|
+
fixedNotes?: string[];
|
|
144
|
+
maxBytes?: number;
|
|
145
|
+
secrets?: string[];
|
|
146
|
+
}): DiagnosticsResult;
|
|
147
|
+
/**
|
|
148
|
+
* Settings whose values are known not to be secret (paths, hosts, ports, modes, models, timeouts). Any other setting
|
|
149
|
+
* shows only whether it is set: commands and their arguments, URLs and anything else can carry a credential.
|
|
150
|
+
*/
|
|
151
|
+
export declare const SAFE_SETTINGS: Set<string>;
|
|
152
|
+
/** The environment settings whose names match, sorted: a known non-secret one with its value, any other only "[set]" (or ""). */
|
|
153
|
+
export declare function settingsSnapshot(names: RegExp, env?: NodeJS.ProcessEnv): Record<string, string>;
|
|
154
|
+
/** The text of a JSON value for a bundle file. */
|
|
155
|
+
export declare const jsonText: (value: unknown) => string;
|
|
156
|
+
/** The newest `count` *.log files directly in each folder, newest first; absent folders are skipped. */
|
|
157
|
+
export declare function newestLogs(folders: string[], count: number, exclude?: string[]): string[];
|
|
158
|
+
/**
|
|
159
|
+
* The version of the app an executable belongs to, read without running it: a macOS bundle's Info.plist
|
|
160
|
+
* (CFBundleShortVersionString, else CFBundleVersion), else a version in the file's own name (AppImage). Undefined
|
|
161
|
+
* when neither says.
|
|
162
|
+
*/
|
|
163
|
+
export declare function appVersion(executable: string | undefined): string | undefined;
|