The browser workspace for Synthetos CNC controllers: configure the board, draw and check wiring, flash vetted firmware, and send G-code to run real jobs, from desktop Chrome or Edge over Web Serial, tied to a Synthetos account.
Status: Phase 0 (foundations). Nothing in this repository can open a serial port or move a machine. Packages are filled in task by task; so far
protocolhas inbound framing and classification (P0-07) and the dialect data, read-only capability probe, capability classifier and reviewed supported-version list (P0-08), andschemahas the board definition schema and board selection (P0-08) and, from the vendored TinyG HIL tables, the per-dialect status tables and settings schemas, the read allowlists, the forbidden writes, the edge-next settings overlay,validateand the write-plan gate (P0-09);safetyhas the job sanitiser with long-move splitting, the allow-matrix, the overrun bound and the host-gate rule (P0-10);testkithas the virtual clock, the edge-next and 440.21 firmware models, fault plans,MockSerialPortandReplayTransport(P0-11, dev only);machinehas theTransportinterface,GuardedTransportand the open policy, with no Web Serial transport yet (P0-12); the bundle scan refuses test-kit code,transport=handling, URL schemes and Web Serial in the build (P0-13); andmachine.workerruns under Playwright through a test-only fake-serial build (P0-14). The repository, gates, CI workflow, Worker, pages and E2E job (P0-01 to P0-06) are in place locally. The findings of the independent Phase 0 review have fix commits with regressions; the sanitiser, firmware-model and probe fixes are independently re-verified, and the gate and deploy fixes are awaiting re-verification. P0-15 (first deploy and therun-v0.1.0tag) is not done: there is no GitHub remote or Cloudflare deployment yet, and the owner decisions D39 and D40 are still to be carried into the gates. The owner's steps are on the ops pages (docs/ops/): the account (account.md), branch protection (branch-protection.md), the public staging host (access.md), the Worker (worker.md) and firmware sources (firmware-sources.md).
This software is not an emergency stop. Any machine it drives must have a hardwired, latching E-stop that removes motor and spindle power in hardware. Read the safety contract before connecting a machine: it is
SAFETY.mdin this repository, and is the/safety/page of the app.
Contributor rule: keep modules small and focused. See modularity limits and the ratchet before changing source.
| Path | Role |
|---|---|
packages/protocol |
Framing, inbound classification, dialect data, capability probe and classifier, reviewed supported-version list |
packages/safety |
Allow-matrix, sanitiser, preflight, jog plan, flash gate, fault policy, overrun bound, warning strings |
packages/machine |
Transport interface, MachineSession (the single writer), flow engines, streamer, watchdog, stop sequences |
packages/schema |
Units, generated settings schemas and status tables, read allowlists and forbidden writes (keyed by DialectId), the edge-next overlay, board definitions; MachineProfile v2 and the fact engine later |
packages/gcode |
G-code parser and dialect-aware interpreter and analyser |
packages/flasher |
Firmware manifest, HEX validation, xboot client |
packages/wiring |
Board data, components, rules engine, renderers |
packages/provenance |
Device-local trust anchor and authorship decisions (pure) |
packages/contracts |
API types and valibot schemas shared by the web app and the Worker |
packages/library |
Tool, material, stock, fixture and store-product records: schemas and validation, external link sanitising, versioning and forking, built-in seed data (docs/design/MACHINING_ASSISTANT.md §2-§4) |
packages/advisor |
Feeds and speeds: the deterministic rules model, achievable-feed estimate, live chipload estimator, the override envelope, and the AdvisorEngine seam with RulesEngine and MockAiEngine (§5, §6) |
packages/testkit |
Dev only. Firmware models and fakes for tests; never in a production bundle |
apps/web |
The workspace UI (Preact, Vite multi-page app) |
apps/cli |
Bench tooling (Node) |
workers/run |
The Cloudflare Worker serving the app, /api/* and /auth/*, and the single source of the security headers (src/headers.ts) |
firmware |
Local simulator images and legacy release fixtures; live releases come from GitHub through the Worker (docs/ops/firmware-sources.md) |
vendor |
firmware-pins.json: the firmware commits every protocol citation is pinned to (PIN-1); tinyg-hil-tables/: the TinyG token and status tables generated by the HIL harness (den.json edge-next, d440.json 440.21, d449.json stock edge-0.97 for the read-only dialect), the single source of the generated schema tables (pnpm gen:schema; see its README) |
test-fixtures |
Captured controller output used by tests: forum-json/ (lines quoted in the archived forum, with source URLs) and en-hil/ (TinyG edge-next HIL harness transcripts) |
tools/gates |
Dev only. The repository's lint rules, the licence gate, the gate acceptance tests, and the deploy tools (preflight, asset retention, smoke test) |
tools/e2e |
Dev only. Playwright against wrangler dev, serving the local build (pnpm e2e) or the attested artifact (pnpm e2e:artifact, the CI e2e job): exact headers, CSP enforcement, Trusted Types, and the origin guard on every test, plus the third-party canary. fake-serial/ is the test-only replacement for the machine worker's transport seam, and *.fake-serial.ts specs run against that build (pnpm e2e:fake-serial, P0-14) |
protocol,safety,machine,schema,flasherandprovenancehave no runtime npm dependencies and never import network APIs,contractsor the cloud client.libraryandadvisor(the machining assistant,docs/design/MACHINING_ASSISTANT.md§9) have no runtime npm dependencies, use no network API, are deterministic (noMath.random, no clock) and never reachmachine,protocol,safety,contracts, the cloud client or any app.- The cloud client (
apps/web/src/cloud) imports onlycontractsandprovenance, so nevermachine,protocolorsafety, and the safety path never imports it. workers/runimports onlycontracts. The server holds no machine logic.- No production entry may import
testkit. - Packages are layered (RUN_PLAN §5.3):
protocolimports no other workspace package;safetyimportsprotocol;schemaimportsprotocolandsafety;machineimportsprotocol,safety,schemaand theflasherentry;flasherimportsprotocol;gcode,wiringandprovenanceimportsafetyandprotocol;contractsimports no workspace package;testkitimportsprotocolandflasher. No import cycle anywhere inpackages/.libraryimports onlyschema's JSON Schema validator;advisorimportslibraryand that validator. Runtime workspace edges aredependencies(workspace:*), so the production build graph (--filter-prod) never includes the test kit. - Panels act only through typed intents checked by
safety.allowed; no code outsideMachineSessionwrites to the port, and nothing is loaded at runtime.
These rules are enforced by the gates below (P0-02, P0-03, P0-13).
| Gate | Command | What it enforces |
|---|---|---|
| Boundaries | pnpm deps |
.dependency-cruiser.cjs: the package layering above (layer-* rules) and no-circular; no npm (direct or transitive) and no Node built-ins in the safety path; no contracts or cloud client in the safety path; the cloud client imports only its own modules, contracts and provenance, and no chain of imports from it reaches machine, flasher, schema, gcode, wiring, testkit or any other web-app module (protocol and safety only through provenance); workers/run imports only contracts; library and advisor have no npm or Node built-in and reach no machine-path package, contracts, app or Worker (assistant-*); no entry reaches testkit; nothing imports from outside the repository; every import resolves. Then tools/gates/src/source/cli.ts parses every runtime source file and refuses what dependency-cruiser cannot see: a computed or reflective capability lookup (capability-lookup) and an import() with a computed specifier (dynamic-import) |
| Lint | pnpm lint |
eslint.config.js with the repository's own rules in tools/gates/src/eslint/: no eval/new Function; no HTML sinks (innerHTML, outerHTML, insertAdjacentHTML, dangerouslySetInnerHTML) outside apps/web/src/security/tt.ts; no abort in machine; no Math.random in safety and protocol, and no Math.random, Date.now or performance.now in library and advisor; no network identifiers in protocol, safety, machine, flasher, provenance, schema, library and advisor; in runtime source, navigator only as a static read of a reviewed data property, window aliases only with static keys, no Reflect (run/no-capability-lookup; the test kit is exempt) and no import() with a computed specifier (run/no-dynamic-import); no navigator.serial, requestPort or getPorts anywhere except packages/machine/src/webSerialTransport.ts, which may read navigator.serial statically and nothing more (P1-00; its tests are not exempt); no WARNING —, DANGER — or NOTICE — strings outside packages/safety/src/strings.ts. Inline eslint-disable comments are ignored (noInlineConfig), so a rule can be relaxed only in eslint.config.js |
| Licences | pnpm licence |
Production dependencies: MIT, ISC, BSD-2-Clause, BSD-3-Clause, Apache-2.0 or OFL-1.1. Dev dependencies may also be MPL-2.0, or carry a reviewed exception in tools/gates/src/licence/exceptions.ts. GPL and AGPL dependencies are never allowed (run itself is AGPL-3.0-or-later; see Licence) |
| CI policy | pnpm ci-policy |
Workflows: only the deploy jobs touch secrets or the Cloudflare token; deploy jobs run only on a push to main behind protected environments; actions pinned by SHA; no pull_request_target; no ${{ }} in scripts. CODEOWNERS covers every SAFETY §8 path. The PR template carries the SAFETY §8 checklist verbatim |
| Bundle scan | pnpm scan (after a build) |
No origin literal, //host, javascript: URL or network identifier in apps/web/dist outside the cloud-client chunks (assets/cloud/, decided by content in apps/web/build/chunks.ts); the static-assets _headers file present and identical to what workers/run/src/headers.ts renders. Anywhere in the bundle (P0-13, T-S40): no test-kit marker, MockSerialPort, transport= query handling, URL scheme other than relative, data: and blob:, or Web Serial (navigator.serial, requestPort, getPorts); in code, no computed or reflective capability lookup and no import() with a computed specifier; see docs/ops/ci.md |
| Reproducible build | pnpm repro |
Clones HEAD twice, installs only the build toolchain, builds both and fails unless they are byte-identical, then scans |
pnpm gates runs lint, boundaries, licences and the CI policy. tools/gates/test/acceptance.test.ts proves
each gate fails on a violation: it copies the working tree, introduces one
violation, runs the real gate command and checks which rule caught it.
A change to .dependency-cruiser.cjs, eslint.config.js, tools/gates/,
.github/ or apps/web/build/ changes the safety boundary and needs
safety-path review (.github/CODEOWNERS).
.github/workflows/ci.yml runs these jobs:
verify, secret-free;build, secret-free: the minimal build toolchain, two clean builds that must match byte for byte, and the bundle scan;e2e;e2e-fake-serial: the fake-serial test build, checked against the artifact, then its own Playwright suite (docs/testing/fake-serial.md);attest, which signs build provenance;deploy-staginganddeploy-production, which run onmainonly, behind protected environments, and deploy only the attested artifact, then run the post-deploy smoke test.
The Worker, its headers, the public staging host (OD-40) and the locked-down Cloudflare account (D39): docs/ops/worker.md, docs/ops/access.md, docs/ops/account.md.
Pull requests that touch safety paths must carry the SAFETY §8 checklist and
a recorded independent review bound to the head commit (safety-review,
D40: no approvals while there is a single maintainer, two once a second one
joins; docs/safety/reviews/README.md).
See docs/ops/ci.md for how it works, and docs/ops/branch-protection.md
for the GitHub settings the owner must enable. SAFETY.md is the in-repo
copy of the safety case.
Requirements: Node.js 22.18 or later (it runs the TypeScript gate and
bench scripts directly, with type stripping), and pnpm via Corepack (the exact
version is pinned in package.json packageManager).
corepack enable # or prefix commands with `corepack`
pnpm install --frozen-lockfile --ignore-scripts
pnpm -r typecheck
pnpm gates # lint, dependency-cruiser, licences
pnpm -r test
pnpm --filter web buildpnpm check runs typecheck, the gates, tests, the build and the bundle scan
in that order, then the fake-serial test build and its diff against the
production build, then the localhost bench build and its check (bench scan,
and "only the build-channel chunk differs"; P1-00). pnpm e2e builds and runs the Playwright suite against
wrangler dev (RUN_SCREENSHOTS=1 also writes the review screenshots to
docs/design/screenshots/p0-05/). pnpm e2e:artifact does what the CI
e2e job does: it assembles and verifies an artifact, runs the suite against
wrangler dev serving it, and runs the third-party canary (docs/ops/ci.md).
pnpm e2e:fake-serial builds the production and fake-serial builds, checks
that they differ only in the transport seam chunk, and runs the fake-serial
suite, in which machine.worker opens a mock port (docs/testing/fake-serial.md).
pnpm e2e:staging runs the staging headers suite (wrangler dev --env staging, serial=(self)). The localhost bench build for a real TinyG
(pnpm build:bench, pnpm bench:serve, never deployed) is described in
docs/bench/README.md.
Pages and theme (P0-05): every page (index.html, safety/, privacy/,
404.html) is prerendered at build time from the Preact components in
apps/web/src/shell/ and apps/web/src/pages/, so the safety bar and its W1
warning are in the HTML before any script runs. Every W and C string comes
from packages/safety/src/strings.ts, tested byte for byte against
SAFETY.md §5–§6 (T-S32). The bundle's version chip uses the commit SHA
(git rev-parse HEAD, or RUN_BUILD_SHA). Theme tokens, the token drift
check (pnpm tokens:drift --site <synthetos.com clone>), the contrast table
(pnpm gen:contrast) and the icons (pnpm gen:icons) are described in
docs/design/tokens.md.
Its nested pnpm calls need pnpm on PATH (corepack enable).
Protocol (P0-07): packages/protocol turns serial bytes into typed events.
createInboundDecoder() frames lines (CR/LF tolerant, UTF-8 safe, XON/XOFF
removed into FlowSignal events, 4 KB line cap) and classifies each one as
Response, StatusReport, QueueReport, RxReport, Exception,
Banner, Ack, Text or Garbled, with a relaxed-JSON parser that has depth and size caps
and never throws. Anything ambiguous is Garbled, never guessed. Its tests
run with coverage, and frame.ts, classify.ts, json.ts and inbound.ts
must stay at 100% branch coverage (packages/protocol/vitest.config.ts).
Safety (P0-10): packages/safety decides what may be sent and when.
sanitizeJob(lines, dialect, options) applies SAFETY §4.7 step by step and
returns the exact SentLine[] the streamer will write (LF-terminated, host
N numbers, barrier and holdback marks, long moves split under the
queued-motion ceiling) plus a report; a blocked report must never be armed.
allowed(snapshot, intent) is the declarative allow-matrix (SAFETY §4.1):
the stop class is allowed in every state with the port open, and in Phase 0
every motion, write and connect intent is denied with "Not available in this
release". overrunBound(queue) gives the distance bound and the time
estimate of SAFETY §4.3, and effectiveHostGates applies only tightening
host-gate changes until C19 (T-S69). The package is held to 100% coverage
(pnpm --filter @synthetos/safety test) and a 90% Stryker mutation score
(pnpm --filter @synthetos/safety mutation). Design notes and the places
where the code had to interpret the design: docs/safety/sanitiser.md.
Dependency hygiene: versions are pinned exactly (save-exact), install
scripts never run (ignore-scripts), and pnpm refuses versions published
less than seven days ago (minimumReleaseAge).
GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See
LICENSE and NOTICE. Anyone who modifies run and distributes it, or serves
it to users over a network, must offer those users the corresponding source
under the same licence (owner decision OD-7, docs/ops/owner-decisions.md).
The production dependency policy is unchanged: dependencies must be permissive (MIT, ISC, BSD-2-Clause, BSD-3-Clause, Apache-2.0 or OFL-1.1). Permissive licences are compatible with AGPL-3.0, so they can be combined with run and distributed under its terms. GPL and AGPL dependencies stay disallowed by the licence gate; that rule governs what run depends on, not run's own licence.
Controller firmware (TinyG, g2core) is GPL-2.0 and lives in its own
repositories. Tables generated from TinyG source and the TinyG logo files are
listed with their provenance in THIRD_PARTY_NOTICES.md.