@manfred-kunze-dev/iot-cli 3.4.0 → 3.5.0-dev.25

package/README.md

@@ -37,12 +37,12 @@ iot auth status
 
 The CLI supports multiple authentication methods (highest priority first):
 
-| Method | Example |
-|--------|---------|
-| CLI flags | `--api-key sk_... --base-url https://...` |
-| Environment variables | `IOT_API_KEY`, `IOT_BASE_URL` |
-| Local `.iot` file | JSON file in the current directory or any ancestor |
-| Config store | `~/.config/iot-cli/config.json` (set via `iot auth login`) |
+| Method                | Example                                                    |
+| --------------------- | ---------------------------------------------------------- |
+| CLI flags             | `--api-key sk_... --base-url https://...`                  |
+| Environment variables | `IOT_API_KEY`, `IOT_BASE_URL`                              |
+| Local `.iot` file     | JSON file in the current directory or any ancestor         |
+| Config store          | `~/.config/iot-cli/config.json` (set via `iot auth login`) |
 
 ```bash
 iot auth login     # Interactive setup
@@ -70,27 +70,60 @@ You can also switch contexts for a single invocation:
 iot --context staging auth status
 ```
 
+## Flashing devices
+
+`iot flash` provisions an SD card that **already carries a 2kw-os base image**
+(write that with Raspberry Pi Imager first). It mints a registration token,
+writes a validated `bootstrap.toml` onto the boot partition, and waits for the
+device to enrol.
+
+```bash
+# One-off, fully explicit
+iot flash --name "Werk2 Gateway" --target D:\ \
+  --ssh-key ~/.ssh/rpi_test.pub \
+  --wifi-ssid Plant-Primary --wifi-psk 'secret'
+
+# Fleet flashing: store the stable bits once, then only name each device
+iot flash profile set bench --ssh-key ~/.ssh/rpi_test.pub --wifi-mode store
+iot flash profile use bench
+iot flash --name "Bench Pi 3"
+
+# Customer site: profile holds the SSH key, WiFi is prompted and never stored
+iot flash profile set customer --ssh-key ~/.ssh/rpi_test.pub --wifi-mode prompt-always
+iot flash --profile customer --name "Acme Line 2"
+
+# CI / scripting
+iot flash --name ci-device --target /media/ci/boot --ssh-key ./key.pub \
+  --wifi-ssid CI --wifi-psk ci --non-interactive --no-wait --json
+```
+
+Values resolve as **flag → env → profile → prompt → error**. With
+`--non-interactive`, a missing value exits non-zero naming the flag instead of
+prompting.
+
+Not in scope: downloading or writing the OS image itself.
+
 ## Commands (foundation — v1)
 
-| Command | Description |
-|---------|-------------|
-| `auth` | Login, logout, and check auth status |
-| `config` | Get, set, and list global configuration values |
-| `context` | Manage CLI contexts for multiple environments |
-| `docs` | Browse API documentation from the terminal |
+| Command   | Description                                    |
+| --------- | ---------------------------------------------- |
+| `auth`    | Login, logout, and check auth status           |
+| `config`  | Get, set, and list global configuration values |
+| `context` | Manage CLI contexts for multiple environments  |
+| `docs`    | Browse API documentation from the terminal     |
 
 Resource commands (`devices`, `sensors`, `sites`, `readings`, `events`, …) ship in later releases.
 
 ### Global Options
 
-| Flag | Description |
-|------|-------------|
-| `--api-key <key>` | Override the API key |
-| `--base-url <url>` | Override the base URL |
-| `--context <name>` | Use a named context for this invocation without switching the active one |
-| `--json` | Output raw JSON instead of formatted tables |
-| `--no-color` | Disable colored output |
-| `--verbose` | Print resolved base URL, masked key, and request method+path on stderr before each call |
+| Flag               | Description                                                                             |
+| ------------------ | --------------------------------------------------------------------------------------- |
+| `--api-key <key>`  | Override the API key                                                                    |
+| `--base-url <url>` | Override the base URL                                                                   |
+| `--context <name>` | Use a named context for this invocation without switching the active one                |
+| `--json`           | Output raw JSON instead of formatted tables                                             |
+| `--no-color`       | Disable colored output                                                                  |
+| `--verbose`        | Print resolved base URL, masked key, and request method+path on stderr before each call |
 
 ## Output
 
@@ -98,17 +131,17 @@ Stdout carries the command's data payload (table, JSON, created resource ID). Ev
 
 Exit codes:
 
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | Generic error |
-| 2 | Not authenticated (401) |
-| 3 | Forbidden (403) |
-| 4 | Not found (404) |
-| 5 | Conflict (409) |
-| 6 | Validation error (422) |
-| 7 | Server error (5xx) |
-| 8 | Network error |
+| Code | Meaning                 |
+| ---- | ----------------------- |
+| 0    | Success                 |
+| 1    | Generic error           |
+| 2    | Not authenticated (401) |
+| 3    | Forbidden (403)         |
+| 4    | Not found (404)         |
+| 5    | Conflict (409)          |
+| 6    | Validation error (422)  |
+| 7    | Server error (5xx)      |
+| 8    | Network error           |
 
 ## Development
 
@@ -129,8 +162,8 @@ npm run typecheck
 npm test
 
 # Regenerate typed client from a running dev backend
-SPRING_PROFILES_ACTIVE=spec ./mvnw.cmd -pl backend spring-boot:run   # in backend/
-npm run generate                                                       # in cli/
+SPRING_PROFILES_ACTIVE=spec ./mvnw.cmd spring-boot:run   # run from backend/
+npm run generate                                           # run from cli/
 ```
 
 See [`docs/superpowers/specs/2026-05-25-iot-cli-foundation-design.md`](../docs/superpowers/specs/2026-05-25-iot-cli-foundation-design.md) for the full design.

package/dist/commands/auth.js

@@ -1,8 +1,9 @@
 import { Command } from "commander";
 import { createInterface } from "node:readline/promises";
+import { promptHidden } from "../lib/prompt.js";
 import { DEFAULT_BASE_URL, getActiveContextName, getActiveContext, getContextCount, setContext, setActiveContext, deleteContext, isJsonOutput, resolveConfig, } from "../lib/config.js";
 import { getClient } from "../lib/client.js";
-import { printJson, printKeyValue, printSuccess, maskKey } from "../lib/output.js";
+import { printJson, printKeyValue, printSuccess, maskKey, } from "../lib/output.js";
 import { handleError } from "../lib/errors.js";
 export function makeAuthCommand() {
     const cmd = new Command("auth").description("Manage authentication");
@@ -17,7 +18,10 @@ export function makeAuthCommand() {
             const contextName = getActiveContextName();
             const currentCtx = getActiveContext();
             if (!apiKey || !baseUrl) {
-                const rl = createInterface({ input: process.stdin, output: process.stderr });
+                const rl = createInterface({
+                    input: process.stdin,
+                    output: process.stderr,
+                });
                 try {
                     if (!baseUrl) {
                         const defaultUrl = currentCtx?.baseUrl ?? DEFAULT_BASE_URL;
@@ -40,7 +44,9 @@ export function makeAuthCommand() {
             // Validate by probing /v1/devices/summary so the user knows the
             // creds work before they exit the prompt.
             const { client } = getClient(command);
-            const { data, error } = await client.GET("/v1/devices/summary");
+            const { data, error } = await client.GET("/v1/devices/summary", {
+                params: { query: { pageable: {} } },
+            });
             if (error) {
                 throw new Error("Saved credentials, but the validation probe failed. " +
                     "Double-check the API key and base URL with `iot auth status`.");
@@ -50,7 +56,7 @@ export function makeAuthCommand() {
                     success: true,
                     context: contextName,
                     baseUrl,
-                    devices: data?.total ?? null,
+                    devices: data?.totalElements ?? null,
                 });
             }
             else {
@@ -87,11 +93,13 @@ export function makeAuthCommand() {
             const contextName = getActiveContextName();
             try {
                 const { client } = getClient(command);
-                const { data, error } = await client.GET("/v1/devices/summary");
+                const { data, error } = await client.GET("/v1/devices/summary", {
+                    params: { query: { pageable: {} } },
+                });
                 if (error) {
                     throw error;
                 }
-                const devices = data?.total ?? 0;
+                const devices = data?.totalElements ?? 0;
                 if (json) {
                     printJson({
                         authenticated: true,
@@ -153,7 +161,10 @@ export function makeAuthCommand() {
                 // Last context — keep the entry, just blank the key. This matches
                 // the spec: "logout clears the active context's apiKey, keeps baseUrl
                 // so re-login is one prompt."
-                setContext(contextName, { apiKey: "", baseUrl: ctx?.baseUrl ?? DEFAULT_BASE_URL });
+                setContext(contextName, {
+                    apiKey: "",
+                    baseUrl: ctx?.baseUrl ?? DEFAULT_BASE_URL,
+                });
             }
             else {
                 deleteContext(contextName);
@@ -171,34 +182,4 @@ export function makeAuthCommand() {
     });
     return cmd;
 }
-/**
- * Tiny hidden-input helper for API keys. readline.question doesn't natively
- * support hiding input on Windows/POSIX consistently, so we mute the muxed
- * output stream while the user types.
- */
-function promptHidden(rl, prompt) {
-    return new Promise((resolveAnswer, rejectAnswer) => {
-        const mutableStdout = rl.output;
-        const original = mutableStdout.write.bind(mutableStdout);
-        let muted = false;
-        mutableStdout.write = ((chunk, enc, cb) => {
-            if (muted && typeof chunk === "string") {
-                return original("", enc, cb);
-            }
-            return original(chunk, enc, cb);
-        });
-        process.stderr.write(prompt);
-        muted = true;
-        rl.question("")
-            .then((answer) => {
-            mutableStdout.write = original;
-            process.stderr.write("\n");
-            resolveAnswer(answer);
-        })
-            .catch((err) => {
-            mutableStdout.write = original;
-            rejectAnswer(err);
-        });
-    });
-}
 //# sourceMappingURL=auth.js.map

package/dist/commands/flash-profile.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function makeFlashProfileCommand(): Command;
+//# sourceMappingURL=flash-profile.d.ts.map

package/dist/commands/flash-profile.js

@@ -0,0 +1,180 @@
+import { Command } from "commander";
+import { isJsonOutput } from "../lib/config.js";
+import { printJson, printTable, printSuccess, printKeyValue, } from "../lib/output.js";
+import { handleError } from "../lib/errors.js";
+import { getAllFlashProfiles, getFlashProfile, setFlashProfile, deleteFlashProfile, getActiveFlashProfileName, setActiveFlashProfile, DEFAULT_COUNTRY, DEFAULT_HOSTNAME_PATTERN, } from "../lib/flash/profile.js";
+import { pairWifiNetworks } from "../lib/flash/resolve.js";
+function collect(value, previous = []) {
+    return [...previous, value];
+}
+/**
+ * WiFi PSKs are a secret and must never reach stdout. Every JSON-emitting
+ * path (list, show) funnels through here rather than trusting each call
+ * site to strip credentials individually.
+ */
+function redactProfile(p) {
+    return {
+        ...p,
+        wifiNetworks: p.wifiNetworks?.map((n) => ({
+            ssid: n.ssid,
+            psk: n.psk ? "***" : undefined,
+        })),
+    };
+}
+export function makeFlashProfileCommand() {
+    const cmd = new Command("profile").description("Manage reusable flash profiles");
+    cmd
+        .command("list")
+        .description("List flash profiles")
+        .action((_opts, command) => {
+        try {
+            const profiles = getAllFlashProfiles();
+            const active = getActiveFlashProfileName();
+            if (isJsonOutput(command)) {
+                const redacted = Object.fromEntries(Object.entries(profiles).map(([name, p]) => [
+                    name,
+                    redactProfile(p),
+                ]));
+                printJson({ active, profiles: redacted });
+                return;
+            }
+            const rows = Object.entries(profiles).map(([name, p]) => ({
+                active: name === active ? "*" : "",
+                name,
+                country: p.country,
+                wifiMode: p.wifiMode,
+                networks: String(p.wifiNetworks?.length ?? 0),
+            }));
+            if (rows.length === 0) {
+                process.stderr.write('No flash profiles. Create one with "iot flash profile set <name>".\n');
+                return;
+            }
+            printTable(rows, [
+                { key: "active", header: "" },
+                { key: "name", header: "NAME" },
+                { key: "country", header: "COUNTRY" },
+                { key: "wifiMode", header: "WIFI MODE" },
+                { key: "networks", header: "NETWORKS" },
+            ]);
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    cmd
+        .command("show <name>")
+        .description("Show one profile (WiFi passphrases are not printed)")
+        .action((name, _opts, command) => {
+        try {
+            const p = getFlashProfile(name);
+            if (!p)
+                throw new Error(`Flash profile "${name}" does not exist.`);
+            const safe = redactProfile(p);
+            if (isJsonOutput(command)) {
+                printJson(safe);
+                return;
+            }
+            printKeyValue({
+                Country: p.country,
+                "Hostname Pattern": p.hostnamePattern,
+                "WiFi Mode": p.wifiMode,
+                Networks: (p.wifiNetworks ?? []).map((n) => n.ssid).join(", ") || "(none)",
+                "SSH Key": p.sshKeyPath ?? "(unset)",
+            });
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    cmd
+        .command("set <name>")
+        .description("Create or update a flash profile")
+        .option("--ssh-key <path>", "Operator SSH public key path")
+        .option("--country <cc>", "WiFi regulatory domain")
+        .option("--hostname-pattern <pattern>", "Hostname pattern")
+        .option("--wifi-mode <mode>", "store | prompt-always")
+        .option("--wifi-ssid <ssid>", "WiFi SSID to store (repeatable, priority order)", collect)
+        .option("--wifi-psk <psk>", "WiFi passphrase (repeatable, pairs with --wifi-ssid)", collect)
+        .option("--profile-id <uuid>", "DeviceProfile applied at provision")
+        .action((name, opts, command) => {
+        try {
+            const existing = getFlashProfile(name);
+            // Only replace stored networks when the user actually passed
+            // --wifi-ssid; otherwise leave whatever is already on the profile
+            // alone (same merge pattern as sshKeyPath/profileId below).
+            const wifiFromFlags = pairWifiNetworks(opts.wifiSsid ?? [], opts.wifiPsk ?? []);
+            // An omitted --wifi-mode is no longer a hard "prompt-always"
+            // default (that silently discarded --wifi-ssid/--wifi-psk with a
+            // success message — #373 Case A). Passing --wifi-ssid with no
+            // explicit mode now infers "store"; otherwise an existing
+            // profile's stored mode is preserved so an unrelated partial
+            // update (e.g. --ssh-key alone) can't clobber it back to the
+            // default and wipe stored networks (#373 Case B).
+            const effectiveMode = opts.wifiMode ??
+                (wifiFromFlags.length > 0 ? "store" : existing?.wifiMode) ??
+                "prompt-always";
+            if (effectiveMode !== "store" && effectiveMode !== "prompt-always") {
+                throw new Error('--wifi-mode must be "store" or "prompt-always".');
+            }
+            if (wifiFromFlags.length > 0 && effectiveMode === "prompt-always") {
+                throw new Error("--wifi-ssid/--wifi-psk require --wifi-mode store (prompt-always never stores WiFi).");
+            }
+            setFlashProfile(name, {
+                ...existing,
+                sshKeyPath: opts.sshKey ?? existing?.sshKeyPath,
+                country: opts.country ?? existing?.country ?? DEFAULT_COUNTRY,
+                hostnamePattern: opts.hostnamePattern ??
+                    existing?.hostnamePattern ??
+                    DEFAULT_HOSTNAME_PATTERN,
+                wifiMode: effectiveMode,
+                wifiNetworks: wifiFromFlags.length > 0 ? wifiFromFlags : existing?.wifiNetworks,
+                profileId: opts.profileId ?? existing?.profileId,
+            });
+            if (isJsonOutput(command)) {
+                printJson({ success: true, name });
+            }
+            else {
+                printSuccess(`Saved flash profile "${name}".`, "stderr");
+            }
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    cmd
+        .command("use <name>")
+        .description("Set the default flash profile")
+        .action((name, _opts, command) => {
+        try {
+            setActiveFlashProfile(name);
+            if (isJsonOutput(command)) {
+                printJson({ success: true, active: name });
+            }
+            else {
+                printSuccess(`Using flash profile "${name}".`, "stderr");
+            }
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    cmd
+        .command("delete <name>")
+        .description("Delete a flash profile")
+        .action((name, _opts, command) => {
+        try {
+            deleteFlashProfile(name);
+            if (isJsonOutput(command)) {
+                printJson({ success: true, deleted: name });
+            }
+            else {
+                printSuccess(`Deleted flash profile "${name}".`, "stderr");
+            }
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=flash-profile.js.map

package/dist/commands/flash.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function makeFlashCommand(): Command;
+//# sourceMappingURL=flash.d.ts.map

package/dist/commands/flash.js

@@ -0,0 +1,176 @@
+import { Command } from "commander";
+import { getClient } from "../lib/client.js";
+import { isJsonOutput } from "../lib/config.js";
+import { printJson, printKeyValue, printSuccess } from "../lib/output.js";
+import { handleError } from "../lib/errors.js";
+import { promptText, promptSecret } from "../lib/prompt.js";
+import { resolveFlashInputs } from "../lib/flash/resolve.js";
+import { inspectBootPartition, detectBootPartitions, writeBootstrapFile, } from "../lib/flash/boot-partition.js";
+import { renderHostname } from "../lib/flash/bootstrap.js";
+import { mintRegistrationToken, waitForEnrolment, } from "../lib/flash/platform.js";
+import { makeFlashProfileCommand } from "./flash-profile.js";
+function collect(value, previous = []) {
+    return [...previous, value];
+}
+export function makeFlashCommand() {
+    const cmd = new Command("flash").description("Provision an SD card that already carries a 2kw-os base image");
+    // The one-off flow (`iot flash --name ... --wifi-ssid ...`) lives on this
+    // hidden default subcommand rather than directly on `cmd`. `cmd` also hosts
+    // `profile`, whose `set` action needs its OWN --wifi-ssid/--ssh-key/etc to
+    // populate a stored profile (see flash-profile.ts). Commander resolves a
+    // repeated flag name by whichever ANCESTOR in the parse chain declares it
+    // first, regardless of `enablePositionalOptions`/`passThroughOptions` — so
+    // if these options lived on `cmd` itself, `iot flash profile set bench
+    // --wifi-ssid ...` would have `cmd` silently swallow `--wifi-ssid` before
+    // `profile set` ever saw it, discarding the value the user typed. Keeping
+    // the options off `cmd` and on this sibling-of-`profile` child instead
+    // avoids the collision entirely.
+    const run = new Command("run")
+        .description("Provision an SD card that already carries a 2kw-os base image")
+        .option("--name <deviceName>", "Device name to register")
+        .option("--target <mount>", "SD boot partition mount point (auto-detected if omitted)")
+        .option("--wifi-ssid <ssid>", "WiFi SSID (repeatable, priority order)", collect)
+        .option("--wifi-psk <psk>", "WiFi passphrase (repeatable, pairs with --wifi-ssid)", collect)
+        .option("--country <cc>", "WiFi regulatory domain")
+        .option("--ssh-key <path>", "Operator SSH public key")
+        .option("--hostname <name>", "Override the hostname pattern")
+        .option("--profile <name>", "Flash profile to use")
+        .option("--profile-id <uuid>", "DeviceProfile to apply at provision")
+        .option("--no-wait", "Exit after writing instead of waiting for enrolment")
+        .option("--timeout <sec>", "Enrolment wait timeout in seconds", "300")
+        .option("--non-interactive", "Never prompt; error on a missing value")
+        .option("--force", "Write even if the target looks wrong or already prepared")
+        .action(async (opts, command) => {
+        try {
+            const json = isJsonOutput(command);
+            const flags = opts;
+            // 1. Resolve inputs.
+            const resolved = await resolveFlashInputs(flags, {
+                promptText,
+                promptSecret,
+            });
+            // 1b. A bad --timeout is only relevant when we'll actually wait
+            // (--no-wait leaves it unused), but when we will, validate it here —
+            // before minting a token or writing the card — so a typo never
+            // leaves an orphaned pending device registration and a written SD
+            // card behind a validation error.
+            let timeoutSeconds = 0;
+            if (flags.wait) {
+                timeoutSeconds = Number(flags.timeout);
+                if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) {
+                    throw new Error("--timeout must be a positive number of seconds.");
+                }
+            }
+            // 2. Locate and check the card.
+            const target = flags.target ?? autoDetectTarget();
+            const check = inspectBootPartition(target);
+            if (!check.looksLikeRpiBoot && !flags.force) {
+                throw new Error(`${target} does not look like a Raspberry Pi boot partition:\n  ` +
+                    check.reasons.join("\n  ") +
+                    "\nRefusing to write. Pass --force to override.");
+            }
+            if (check.hasStaleBootstrap && !flags.force) {
+                throw new Error(`${target} already contains a bootstrap.toml, so this card may already ` +
+                    "be prepared. Refusing to overwrite. Pass --force to replace it.\n" +
+                    "Note: a device that has already enrolled IGNORES a new token and keeps " +
+                    "its existing identity, so re-flashing it leaves an unused pending device " +
+                    "registered on the platform. WiFi, SSH and hostname changes still apply.");
+            }
+            // 3. Mint.
+            const { client, config } = getClient(command);
+            const mint = await mintRegistrationToken(client, resolved.deviceName);
+            const hostname = resolved.hostnameOverride ??
+                renderHostname(resolved.hostnamePattern, mint.deviceId);
+            // 4. Write. provision_url is carried from the mint response so a card
+            //    flashed against staging cannot silently enrol into production.
+            const written = writeBootstrapFile(target, {
+                hostname,
+                profileId: resolved.profileId,
+                token: mint.token,
+                wifiCountry: resolved.country,
+                wifiNetworks: resolved.wifiNetworks,
+                sshAuthorizedKey: resolved.sshAuthorizedKey,
+                provisionUrl: mint.provisionEndpoint,
+            });
+            if (!json) {
+                printSuccess(`Wrote ${written}`, "stderr");
+                process.stderr.write(`Token expires ${mint.expiresAt} — boot the device before then.\n` +
+                    "Safely eject the card, insert it, and power the device on.\n");
+            }
+            // 5. Verify.
+            if (!flags.wait) {
+                emit(json, {
+                    deviceId: mint.deviceId,
+                    deviceName: mint.deviceName,
+                    hostname,
+                    written,
+                    status: "not_checked",
+                });
+                return;
+            }
+            if (!json)
+                process.stderr.write("Waiting for the device to enrol...\n");
+            const timeoutMs = timeoutSeconds * 1000;
+            const result = await waitForEnrolment(client, mint.deviceId, {
+                timeoutMs,
+                intervalMs: 5000,
+            });
+            if (!result.online) {
+                const dashboard = `${config.baseUrl.replace(/\/api\/?$/, "")}/devices/${mint.deviceId}`;
+                throw new Error(`Device has not enrolled within ${flags.timeout}s (last status: ${result.status}). ` +
+                    `The card is written and the token is valid until ${mint.expiresAt}. ` +
+                    `Check ${dashboard}`);
+            }
+            emit(json, {
+                deviceId: mint.deviceId,
+                deviceName: mint.deviceName,
+                hostname,
+                written,
+                status: result.status,
+                lastSeenAt: result.lastSeenAt,
+            });
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    cmd.addCommand(run, { isDefault: true, hidden: true });
+    cmd.addCommand(makeFlashProfileCommand());
+    // `run` is hidden (it's reached by default, not by name), so its options
+    // would otherwise be invisible to `iot flash --help`. Append them instead
+    // of duplicating the flag list as static text, so the two can't drift.
+    cmd.addHelpText("after", () => {
+        const help = run.helpInformation();
+        const i = help.indexOf("Options:");
+        if (i < 0)
+            return "";
+        const optionsBlock = help.slice(i);
+        return `\nRun without a subcommand for the one-off flow:\n  iot flash [options]\n\n${optionsBlock}`;
+    });
+    return cmd;
+}
+function autoDetectTarget() {
+    const found = detectBootPartitions();
+    if (found.length === 1)
+        return found[0];
+    if (found.length === 0) {
+        throw new Error("No Raspberry Pi boot partition found. Insert the flashed SD card, " +
+            "or point at it explicitly with --target.");
+    }
+    throw new Error(`Multiple boot partitions found (${found.join(", ")}). ` +
+        "Pick one with --target.");
+}
+/** Secrets are deliberately absent from every emitted field. */
+function emit(json, payload) {
+    if (json) {
+        printJson(payload);
+        return;
+    }
+    printKeyValue({
+        "Device ID": String(payload.deviceId),
+        "Device Name": String(payload.deviceName),
+        Hostname: String(payload.hostname),
+        Status: String(payload.status),
+    });
+}
+//# sourceMappingURL=flash.js.map

package/dist/index.js

@@ -5,6 +5,7 @@ import { makeAuthCommand } from "./commands/auth.js";
 import { makeContextCommand } from "./commands/context.js";
 import { makeConfigCommand } from "./commands/config.js";
 import { makeDocsCommand } from "./commands/docs.js";
+import { makeFlashCommand } from "./commands/flash.js";
 import { checkForUpdates } from "./lib/update-notifier.js";
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
@@ -24,6 +25,7 @@ program.addCommand(makeAuthCommand());
 program.addCommand(makeContextCommand());
 program.addCommand(makeConfigCommand());
 program.addCommand(makeDocsCommand());
+program.addCommand(makeFlashCommand());
 const json = process.argv.includes("--json");
 const updater = checkForUpdates(pkg.version, { json });
 program

package/dist/lib/flash/boot-partition.d.ts

@@ -0,0 +1,26 @@
+import { type BootstrapInput } from "./bootstrap.js";
+export declare const BOOTSTRAP_FILENAME = "bootstrap.toml";
+export interface BootPartitionCheck {
+    looksLikeRpiBoot: boolean;
+    hasStaleBootstrap: boolean;
+    reasons: string[];
+}
+/**
+ * Decide whether a mount point looks like a Raspberry Pi FAT boot partition.
+ * This is the guard that stops us writing onto the wrong volume.
+ */
+export declare function inspectBootPartition(mountPath: string): BootPartitionCheck;
+/**
+ * Enumerate plausible boot partitions across platforms. Windows drive letters,
+ * macOS /Volumes, Linux /media and /run/media.
+ */
+export declare function detectBootPartitions(): string[];
+/**
+ * Render, write, then read back and re-parse. A write is never reported as
+ * successful on the strength of the write call alone — re-parsing is what
+ * proves a PSK full of shell-hostile characters survived intact.
+ *
+ * Returns the path written.
+ */
+export declare function writeBootstrapFile(mountPath: string, input: BootstrapInput): string;
+//# sourceMappingURL=boot-partition.d.ts.map