feat(3ds): deploy the console binary over the dev connection

AGENTS.md

@@ -58,8 +58,9 @@ documentation or tests. New validation runs stay in ignored artifact folders.
 ```sh
 bun run check                        # typecheck + all four shells' unit and sim tests
 bun run push --host <console-ip>     # rebuild the guest, hot-push it (~20 s)
+bun run deploy --host <console-ip>   # rebuild the .3dsx, install it over the wire, restart into it
 bun run shot --host <console-ip>     # a screenshot of both screens
-bun run 3ds                          # the full .3dsx — needed for a reflash
+bun run 3ds                          # the full .3dsx in dist/3ds
 bun run film                         # re-record media/ from the tapes
 bun run goldens                      # byte-compare the pinned frames
 ```
@@ -90,10 +91,13 @@ bun run check:desktop          # or check:3ds / check:ipod
 Run these commands from the repository root. Each shell also has its own
 package.json; desktop artifacts land in `shells/desktop/dist/`.
 
-`shells/3ds/src/` changes are hot pushes. A change under `vendor/pocketjs/hosts/3ds` is
-native: rebuild the `.3dsx`, copy it to the SD card, relaunch. **ftpd cannot
-run while Pocket Runtime does** — one homebrew at a time — so pairing happens
-with ftpd up and pushing happens with the shell up.
+`shells/3ds/src/` changes are hot pushes, and an accepted push persists on
+the card for this app. A change under `vendor/pocketjs/hosts/3ds` is native:
+`bun run deploy` writes the new `.3dsx` to `sdmc:/3ds/` through the running
+shell and restarts into it, and the restarted `.3dsx` boots the guest it
+embeds. **ftpd is needed once, to pair** (ftpd and Pocket Runtime are both
+homebrew, and one runs at a time); a Runtime that predates `deploy` takes one
+`bun run deploy --ftp --host <ip>` with ftpd open.
 
 ## What the tapes are for
 

README.md

@@ -77,6 +77,7 @@ to list its commands, including captures, benchmarks and the text companion.
 bun run guest                    # bundle the 3DS guest for the simulator
 bun run 3ds                      # full console binary in dist/3ds
 bun run push --host <console-ip>  # rebuild and hot-push the 3DS guest
+bun run deploy --host <console-ip> # install the .3dsx over the wire and restart into it
 bun run shot --host <console-ip>  # capture both console screens
 bun run film                     # regenerate shells/3ds/media from tapes
 bun run goldens                  # compare pinned 3DS frames

package.json

@@ -17,6 +17,7 @@
     "guest": "bun run --cwd shells/3ds guest",
     "pair": "bun run --cwd shells/3ds pair",
     "push": "bun run --cwd shells/3ds push",
+    "deploy": "bun run --cwd shells/3ds deploy",
     "probe": "bun run --cwd shells/3ds probe",
     "shot": "bun run --cwd shells/3ds shot",
     "film": "bun run --cwd shells/3ds film",

shells/3ds/README.md

@@ -188,13 +188,18 @@ To iterate without reflashing, pair once while the console is running ftpd,
 then hot-push the guest package — the app keeps running:
 
 ```sh
-bun run pair --host 192.168.1.20   # once, with ftpd open on the console
-bun run push --host 192.168.1.20   # rebuild + push, about 20 s
-bun run shot --host 192.168.1.20   # a screenshot of both screens
+bun run pair --host 192.168.1.20    # once, with ftpd open on the console
+bun run push --host 192.168.1.20    # rebuild + push, about 20 s
+bun run deploy --host 192.168.1.20  # new .3dsx over the wire, then restart into it
+bun run shot --host 192.168.1.20    # a screenshot of both screens
 ```
 
-A change under `vendor/pocketjs/hosts/3ds` is native and needs `bun run 3ds`
-and a reflash; everything in `src/` is a hot push.
+Everything in `src/` is a hot push, and an accepted push is what the shell
+boots next time. A change under `vendor/pocketjs/hosts/3ds` is native:
+`bun run deploy` builds the `.3dsx`, the running shell writes it to
+`/3ds/pocketshell-main.3dsx`, and the console restarts into it through
+Luma3DS's `hb:ldr` loader, running the guest the new file embeds. ftpd is
+not part of either loop after pairing.
 
 ## Checks
 

shells/3ds/package.json

@@ -10,6 +10,7 @@
     "guest": "bun scripts/guest.ts",
     "pair": "bun scripts/pair.ts",
     "push": "bun scripts/push.ts",
+    "deploy": "bun scripts/deploy.ts",
     "probe": "bun scripts/probe.ts",
     "shot": "bun scripts/shot.ts",
     "film": "bun scripts/film.ts",

shells/3ds/scripts/deploy.ts

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// bun run deploy [--host <ip>] [--no-launch] — build the console binary and
+// install it over the Pocket Runtime dev wire at sdmc:/3ds/pocketshell-main.3dsx,
+// then restart into it. The running shell receives the file, so ftpd is not
+// involved; a Runtime older than this needs one copy through ftpd first:
+// bun run deploy --ftp --host <ip>, with ftpd open.
+
+import { resolve } from "node:path";
+import { $ } from "bun";
+import { passThrough, plantDeviceKeys } from "../../../scripts/run.ts";
+import { DIST_3DS, ROOT, VENDOR } from "./paths.ts";
+
+await plantDeviceKeys();
+await passThrough($`bun ${resolve(import.meta.dir, "3ds.ts")}`.cwd(ROOT));
+await passThrough(
+  $`bun ${VENDOR}/tools/3ds-dev.ts install --file ${DIST_3DS}/pocketshell-main.3dsx ${process.argv.slice(2)}`
+    .cwd(ROOT),
+);

shells/3ds/scripts/push.ts

@@ -2,7 +2,7 @@
 // bun run push [--host <ip>] — rebuild the guest package and hot-push it to a
 // paired console over the Pocket Runtime dev wire, without touching the native
 // binary. This is the loop for app changes; a change under
-// vendor/pocketjs/hosts/3ds needs `bun run 3ds` and a reflash.
+// vendor/pocketjs/hosts/3ds is a native one, for `bun run deploy`.
 
 import { resolve } from "node:path";
 import { $ } from "bun";