Archive/device plane

README.md

@@ -14,6 +14,7 @@
 - 🧠 **Native MCP server** — an owner-gated Model Context Protocol endpoint with a Claude connector for AI clients (off by default).
 - 👥 **Multi-user** — owner / admin / member roles, email invites, and social sign-in (Google, GitHub).
 - 📝 **Audit log** — every privileged action recorded and paginated in the UI.
+- 🔧 **Write, build and flash from the browser** — a code editor, serial monitor and Web Serial flasher in one page; the [nodrix agent](https://github.com/decoded-cipher/nodrix-agent) compiles on your machine, and the same build ships over the air.
 
 ## Quick start
 
@@ -36,12 +37,30 @@
      -H "Authorization: Bearer $NODRIX_TOKEN"
    ```
 
+## Flashing hardware from the browser
+
+The Code page pairs an editor with a serial monitor and flashes over Web Serial, so a board goes from sketch to running without leaving the browser. Compiling is the one part a browser cannot do — the ESP32 sysroot alone is over 150 MB — so it runs on your own machine via the agent.
+
+```bash
+curl -fsSL -o nodrix-agent \
+  https://github.com/decoded-cipher/nodrix-agent/releases/latest/download/nodrix-agent-macos-arm64
+chmod +x nodrix-agent
+arduino-cli core install esp32:esp32
+
+NODRIX_INSTANCE=https://<your-worker> NODRIX_TOKEN=<admin token> ./nodrix-agent
+```
+
+Other platforms are on the [agent releases](https://github.com/decoded-cipher/nodrix-agent/releases/latest). The agent dials out to your instance, so there is no port to open and no certificate to install; it never touches the serial port, which the browser owns. Flashing needs Chrome, Edge or Opera on desktop, or Chrome on Android — Safari and Firefox have no Web Serial.
+
+Keep a build and it becomes a firmware version you can send to any device over the air.
+
 ## Architecture
 
 - **Worker** ([worker/](worker/)) — a single Hono app. Durable Objects for Project, Dashboard, Scheduler, and the MCP agent; one Workflow for provisioning; D1 (metadata), R2 (telemetry history), KV (read cache + JWKS).
 - **Web** ([web/](web/)) — Vue 3 + Tailwind + Reka UI admin panel and drag-and-drop dashboard builder, built and served as Worker static assets.
 - **Shared** ([shared/](shared/)) — framework-agnostic Web Component widgets, the integration catalog, and automation blocks, consumed by both web and worker so there is a single source of truth.
 - **Deploy** ([deploy/](deploy/)) — the small config carrier behind the one-click Deploy to Cloudflare.
+- **Agent** ([nodrix-agent](https://github.com/decoded-cipher/nodrix-agent)) — an optional CLI on your own machine that runs `arduino-cli` for browser builds. Separate repo, separate release.
 
 ```
 worker/   Cloudflare Worker — API, Durable Objects, Workflow

deploy/wrangler.toml

@@ -1,7 +1,8 @@
-# nodrix deploy carrier. The Deploy to Cloudflare button clones only this
-# subdir; the build command pulls the real source from upstream over it. Don't
-# edit by hand — manage the deployment from the Cloudflare dashboard. Keep the
-# bindings in sync with the repo-root wrangler.toml.
+# nodrix deploy carrier. The Deploy to Cloudflare button clones only this subdir;
+# the build command pulls the real source from upstream over it and rebuilds the
+# deployment's wrangler.toml from this file, keeping only its Worker name,
+# account, routes, resource IDs and vars. Everything else here reaches every
+# existing deployment on its next build — keep it in sync with the root config.
 name = "nodrix"
 main = "worker/src/index.ts"
 compatibility_date = "2025-05-01"

scripts/build-from-upstream.sh

@@ -9,9 +9,11 @@
 # source of truth — meaning code changes in upstream never reach them. With
 # this script, every deploy:
 #
-#   1. Preserves the user's wrangler.toml (which has their resource IDs,
-#      filled by the Deploy button on day 1 and never changed since).
-#   2. Replaces every other file with the upstream source's contents.
+#   1. Replaces every file with the upstream source's contents.
+#   2. Rebuilds wrangler.toml from upstream's carrier template, keeping only the
+#      deployment's identity (Worker name, account, routes, resource IDs, vars).
+#      Keeping the whole file instead froze the topology at day 1, so a binding
+#      or flag added upstream never reached anyone who had already deployed.
 #   3. Runs upstream's build pipeline.
 #
 # Result: the user's clone is functionally a config carrier. Code = upstream.
@@ -31,6 +33,7 @@ UPSTREAM_REPO="${NODRIX_UPSTREAM_REPO:-decoded-cipher/nodrix}"
 DEPLOY_CHANNEL="${NODRIX_DEPLOY_CHANNEL:-release}"
 UPSTREAM_DIR="/tmp/nodrix-upstream"
 WRANGLER_BACKUP="/tmp/nodrix-wrangler.toml"
+WRANGLER_MERGED="/tmp/nodrix-wrangler.merged.toml"
 
 if [ -z "${WORKERS_CI_COMMIT_SHA:-}" ]; then
   echo "[build-from-upstream] not in Workers Builds CI — running local build chain"
@@ -43,7 +46,7 @@ fi
 
 echo "[build-from-upstream] CI build — pulling upstream ${UPSTREAM_REPO} (${DEPLOY_CHANNEL} channel)"
 
-# 1. Preserve user's wrangler.toml.
+# 1. Save the deployment's wrangler.toml; step 4 merges it back.
 if [ ! -f wrangler.toml ]; then
   echo "[build-from-upstream] no wrangler.toml in cwd — refusing to proceed" >&2
   exit 1
@@ -114,8 +117,17 @@ for dir in web worker scripts; do
     done
 done
 
-# 4. Restore user's wrangler.toml in case upstream had its own (which it does).
-cp "${WRANGLER_BACKUP}" wrangler.toml
+# 4. Rebuild wrangler.toml. This script comes from master but the clone is the
+#    release tag, so a release predating the merge script falls back instead of
+#    failing.
+if [ -f scripts/merge-wrangler.ts ] && [ -f ./deploy/wrangler.toml ]; then
+  echo "[build-from-upstream] merging deployment identity into upstream wrangler.toml"
+  bun scripts/merge-wrangler.ts "${WRANGLER_BACKUP}" ./deploy/wrangler.toml > "${WRANGLER_MERGED}"
+  mv "${WRANGLER_MERGED}" wrangler.toml
+else
+  echo "[build-from-upstream] upstream has no merge script — keeping wrangler.toml as-is"
+  cp "${WRANGLER_BACKUP}" wrangler.toml
+fi
 
 # 4b. Drop the nested deploy/ that the overlay just brought in. The clone root
 #     IS the deploy carrier; upstream's own deploy/ dir is dead weight here and

scripts/merge-wrangler.test.ts

@@ -0,0 +1,116 @@
+// Getting this wrong on a live deployment points it at resources it doesn't own,
+// or renames the Worker. Run with `bun test scripts/merge-wrangler.test.ts`.
+
+import { test, expect } from 'bun:test';
+import { mergeWrangler } from './merge-wrangler';
+
+// Renamed, on a custom domain, tracking a fork, and predating three template changes.
+const DEPLOYMENT = `name = "home-iot"
+main = "worker/src/index.ts"
+compatibility_date = "2025-05-01"
+compatibility_flags = ["nodejs_compat"]
+account_id = "acc_123"
+routes = [
+  { pattern = "iot.example.com", custom_domain = true }
+]
+
+[[d1_databases]]
+binding = "DB"
+database_name = "home-iot-db"
+database_id = "aaaa-bbbb-cccc"
+
+[[kv_namespaces]]
+binding = "KV"
+id = "kv_deadbeef"
+
+[[r2_buckets]]
+binding = "R2"
+bucket_name = "home-iot-telemetry"
+
+[vars]
+NODRIX_UPSTREAM_REPO = "someone/nodrix-fork"
+`;
+
+const TEMPLATE = `name = "nodrix"
+main = "worker/src/index.ts"
+compatibility_date = "2026-01-15"
+compatibility_flags = ["nodejs_compat"]
+
+[build]
+command = "curl -fsSL https://example.invalid/build.sh | bash"
+
+[[d1_databases]]
+binding = "DB"
+database_name = "nodrix"
+database_id = "PLACEHOLDER_FILLED_BY_DEPLOY_OR_WRANGLER"
+migrations_dir = "worker/src/platform/db/migrations"
+
+[[kv_namespaces]]
+binding = "KV"
+id = "PLACEHOLDER_FILLED_BY_DEPLOY_OR_WRANGLER"
+
+[[r2_buckets]]
+binding = "R2"
+bucket_name = "nodrix-telemetry"
+
+[[durable_objects.bindings]]
+name = "PROJECT_DO"
+class_name = "ProjectDO"
+
+[[migrations]]
+tag = "v2"
+new_sqlite_classes = ["DeviceDO"]
+
+[vars]
+NODRIX_UPSTREAM_REPO = "decoded-cipher/nodrix"
+NODRIX_FEATURE_FLAG = "on"
+
+[triggers]
+crons = ["0 0 * * *"]
+`;
+
+const merged = mergeWrangler(DEPLOYMENT, TEMPLATE);
+
+test('keeps the deployment worker name', () => {
+  expect(merged).toContain('name = "home-iot"');
+  expect(merged).not.toContain('name = "nodrix"');
+});
+
+test('keeps resource ids the deployment owns', () => {
+  expect(merged).toContain('database_id = "aaaa-bbbb-cccc"');
+  expect(merged).toContain('database_name = "home-iot-db"');
+  expect(merged).toContain('id = "kv_deadbeef"');
+  expect(merged).toContain('bucket_name = "home-iot-telemetry"');
+  expect(merged).not.toContain('PLACEHOLDER');
+});
+
+test('keeps account and routes the template never declares', () => {
+  expect(merged).toContain('account_id = "acc_123"');
+  expect(merged).toContain('pattern = "iot.example.com"');
+});
+
+test('takes compatibility settings and build config from upstream', () => {
+  expect(merged).toContain('compatibility_date = "2026-01-15"');
+  expect(merged).toContain('https://example.invalid/build.sh');
+});
+
+test('takes new bindings, migrations and triggers from upstream', () => {
+  expect(merged).toContain('class_name = "ProjectDO"');
+  expect(merged).toContain('new_sqlite_classes = ["DeviceDO"]');
+  expect(merged).toContain('crons = ["0 0 * * *"]');
+  expect(merged).toContain('migrations_dir = "worker/src/platform/db/migrations"');
+});
+
+test('keeps an overridden var and adds one the deployment predates', () => {
+  expect(merged).toContain('NODRIX_UPSTREAM_REPO = "someone/nodrix-fork"');
+  expect(merged).toContain('NODRIX_FEATURE_FLAG = "on"');
+});
+
+test('is idempotent against its own output', () => {
+  expect(mergeWrangler(merged, TEMPLATE)).toBe(merged);
+});
+
+test('a fresh deployment carrying only placeholders is left as the template', () => {
+  const fresh = mergeWrangler(TEMPLATE, TEMPLATE);
+  expect(fresh).toBe(TEMPLATE);
+});

scripts/merge-wrangler.ts

@@ -0,0 +1,171 @@
+// Rebuilds a deployment's wrangler.toml: bindings, flags and build config from
+// upstream's carrier template, identity from the deployment's own file.
+//
+// Keeping the deployment's file verbatim froze its topology at whatever the
+// Deploy button wrote on day one; taking upstream's verbatim would rename the
+// Worker, creating a second one and orphaning the live one.
+
+import { readFileSync } from 'node:fs';
+
+const PRESERVED_TOP_KEYS = ['name', 'account_id', 'workers_dev', 'preview_urls', 'route', 'routes'];
+
+const PRESERVED_RESOURCE_KEYS: Record<string, string[]> = {
+  d1_databases: ['database_id', 'database_name'],
+  kv_namespaces: ['id'],
+  r2_buckets: ['bucket_name'],
+};
+
+type Section = { header: string; lines: string[] };
+
+function keyOf(line: string): string | null {
+  const m = /^\s*([A-Za-z_][A-Za-z0-9_.-]*)\s*=/.exec(line);
+  return m ? m[1]! : null;
+}
+
+// TOML arrays and inline tables can span lines; those join into one entry.
+function unclosed(text: string): boolean {
+  let depth = 0;
+  let quote = '';
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]!;
+    if (quote) {
+      if (c === '\\') i++;
+      else if (c === quote) quote = '';
+      continue;
+    }
+    if (c === '"' || c === "'") quote = c;
+    else if (c === '#') break;
+    else if (c === '[' || c === '{') depth++;
+    else if (c === ']' || c === '}') depth--;
+  }
+  return depth > 0;
+}
+
+function parse(text: string): Section[] {
+  const sections: Section[] = [{ header: '', lines: [] }];
+  const raw = text.split('\n');
+  for (let i = 0; i < raw.length; i++) {
+    let line = raw[i]!;
+    if (line.trim().startsWith('[')) {
+      sections.push({ header: line.trim(), lines: [] });
+      continue;
+    }
+    if (keyOf(line)) {
+      while (unclosed(line) && i + 1 < raw.length) line += '\n' + raw[++i]!;
+    }
+    sections[sections.length - 1]!.lines.push(line);
+  }
+  return sections;
+}
+
+function valueOf(line: string): string {
+  const eq = line.indexOf('=');
+  return line.slice(eq + 1).trim().replace(/\s*#.*$/, '').replace(/^["']|["']$/g, '');
+}
+
+function lookup(section: Section, key: string): string | undefined {
+  for (const l of section.lines) if (keyOf(l) === key) return l;
+  return undefined;
+}
+
+function arrayName(header: string): string | null {
+  const m = /^\[\[([A-Za-z0-9_.-]+)\]\]$/.exec(header);
+  return m ? m[1]! : null;
+}
+
+export function mergeWrangler(sourceText: string, templateText: string): string {
+  const source = parse(sourceText);
+  const template = parse(templateText);
+
+  const sourceTop = source[0]!;
+  const sourceResources = new Map<string, Section>();
+  let sourceVars: Section | undefined;
+  for (const s of source) {
+    const name = arrayName(s.header);
+    if (name && name in PRESERVED_RESOURCE_KEYS) {
+      const binding = lookup(s, 'binding');
+      if (binding) sourceResources.set(`${name}:${valueOf(binding)}`, s);
+    } else if (s.header === '[vars]') {
+      sourceVars = s;
+    }
+  }
+
+  const out: string[] = [];
+  const usedTopKeys = new Set<string>();
+
+  for (const s of template) {
+    if (s.header) out.push(s.header);
+
+    const name = arrayName(s.header);
+    const resourceKeys = name ? PRESERVED_RESOURCE_KEYS[name] : undefined;
+    let resource: Section | undefined;
+    if (resourceKeys) {
+      const binding = lookup(s, 'binding');
+      if (binding) {
+        resource = sourceResources.get(`${name}:${valueOf(binding)}`);
+        if (!resource) {
+          console.error(
+            `[merge-wrangler] ${name} binding ${valueOf(binding)} is new upstream — this deployment has no id for it`
+          );
+        }
+      }
+    }
+
+    for (const line of s.lines) {
+      const key = keyOf(line);
+      if (!key) {
+        out.push(line);
+        continue;
+      }
+      if (!s.header && PRESERVED_TOP_KEYS.includes(key)) {
+        const own = lookup(sourceTop, key);
+        usedTopKeys.add(key);
+        out.push(own ?? line);
+        continue;
+      }
+      if (resource && resourceKeys!.includes(key)) {
+        out.push(lookup(resource, key) ?? line);
+        continue;
+      }
+      if (s.header === '[vars]' && sourceVars) {
+        out.push(lookup(sourceVars, key) ?? line);
+        continue;
+      }
+      out.push(line);
+    }
+
+    // Custom domains and account ids the template never declares.
+    if (!s.header) {
+      const extra = PRESERVED_TOP_KEYS.filter((k) => !usedTopKeys.has(k) && lookup(sourceTop, k));
+      if (extra.length) {
+        let at = out.length;
+        while (at > 0 && !keyOf(out[at - 1]!)) at--;
+        out.splice(at, 0, ...extra.map((k) => lookup(sourceTop, k)!));
+      }
+    }
+    if (s.header === '[vars]' && sourceVars) {
+      const declared = new Set(s.lines.map(keyOf).filter(Boolean));
+      for (const line of sourceVars.lines) {
+        const k = keyOf(line);
+        if (k && !declared.has(k)) out.push(line);
+      }
+    }
+  }
+
+  if (sourceVars && !template.some((s) => s.header === '[vars]')) {
+    out.push('', '[vars]', ...sourceVars.lines.filter((l) => keyOf(l)));
+  }
+
+  return out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\n*$/, '\n');
+}
+
+if (import.meta.main) {
+  const [, , sourcePath, templatePath] = process.argv;
+  if (!sourcePath || !templatePath) {
+    console.error('usage: merge-wrangler.ts <deployment.toml> <upstream-template.toml>');
+    process.exit(1);
+  }
+  process.stdout.write(
+    mergeWrangler(readFileSync(sourcePath, 'utf8'), readFileSync(templatePath, 'utf8'))
+  );
+}