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

package/dist/lib/flash/boot-partition.js

@@ -0,0 +1,128 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { renderBootstrapToml, parseBootstrapToml, } from "./bootstrap.js";
+export const BOOTSTRAP_FILENAME = "bootstrap.toml";
+/**
+ * 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 function inspectBootPartition(mountPath) {
+    const reasons = [];
+    if (!existsSync(mountPath)) {
+        return {
+            looksLikeRpiBoot: false,
+            hasStaleBootstrap: false,
+            reasons: [`${mountPath} does not exist or is not mounted.`],
+        };
+    }
+    let entries = [];
+    try {
+        entries = readdirSync(mountPath);
+    }
+    catch (err) {
+        return {
+            looksLikeRpiBoot: false,
+            hasStaleBootstrap: false,
+            reasons: [`${mountPath} is not readable: ${err.message}`],
+        };
+    }
+    const lower = entries.map((e) => e.toLowerCase());
+    if (!lower.includes("config.txt"))
+        reasons.push("config.txt is missing.");
+    if (!lower.includes("cmdline.txt"))
+        reasons.push("cmdline.txt is missing.");
+    if (!lower.some((e) => e.endsWith(".dtb")))
+        reasons.push("no .dtb files found.");
+    return {
+        looksLikeRpiBoot: reasons.length === 0,
+        hasStaleBootstrap: lower.includes(BOOTSTRAP_FILENAME),
+        reasons,
+    };
+}
+/**
+ * Enumerate plausible boot partitions across platforms. Windows drive letters,
+ * macOS /Volumes, Linux /media and /run/media.
+ */
+export function detectBootPartitions() {
+    const candidates = [];
+    if (process.platform === "win32") {
+        for (let c = "D".charCodeAt(0); c <= "Z".charCodeAt(0); c++) {
+            candidates.push(`${String.fromCharCode(c)}:\\`);
+        }
+    }
+    else {
+        const roots = ["/Volumes", "/media", "/run/media"];
+        for (const root of roots) {
+            if (!existsSync(root))
+                continue;
+            for (const entry of safeReaddir(root)) {
+                const path = join(root, entry);
+                candidates.push(path);
+                // /media/<user>/<label> nesting
+                for (const nested of safeReaddir(path)) {
+                    candidates.push(join(path, nested));
+                }
+            }
+        }
+    }
+    return candidates.filter((p) => inspectBootPartition(p).looksLikeRpiBoot);
+}
+function safeReaddir(path) {
+    try {
+        return readdirSync(path);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 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 function writeBootstrapFile(mountPath, input) {
+    const target = join(mountPath, BOOTSTRAP_FILENAME);
+    const content = renderBootstrapToml(input);
+    // Explicit utf-8, no BOM. Node never adds one; this is belt-and-braces
+    // against a future refactor reaching for utf16 or a BOM-writing helper.
+    writeFileSync(target, content, { encoding: "utf-8" });
+    const raw = readFileSync(target);
+    if (raw.subarray(0, 3).toString("hex") === "efbbbf") {
+        throw new Error(`${target} was written with a BOM; the gateway cannot parse it.`);
+    }
+    const roundTripped = parseBootstrapToml(raw.toString("utf-8"));
+    assertRoundTrip(input, roundTripped, target);
+    return target;
+}
+function assertRoundTrip(expected, actual, target) {
+    const mismatch = (field) => {
+        throw new Error(`${target} did not round-trip correctly (${field} differs). ` +
+            "The card may be faulty or full — do not boot this device.");
+    };
+    if (actual.token !== expected.token)
+        mismatch("provision.token");
+    if (actual.hostname !== expected.hostname)
+        mismatch("device.hostname");
+    if (actual.profileId !== expected.profileId)
+        mismatch("device.profile_id");
+    if (actual.wifiCountry !== expected.wifiCountry)
+        mismatch("wifi.country");
+    if (actual.sshAuthorizedKey !== expected.sshAuthorizedKey)
+        mismatch("ssh.authorized_key");
+    if (actual.provisionUrl !== expected.provisionUrl)
+        mismatch("backend.provision_url");
+    if (actual.brokerUri !== expected.brokerUri)
+        mismatch("backend.broker_uri");
+    if (actual.wifiNetworks.length !== expected.wifiNetworks.length)
+        mismatch("wifi.networks");
+    expected.wifiNetworks.forEach((net, i) => {
+        const got = actual.wifiNetworks[i];
+        if (got.ssid !== net.ssid)
+            mismatch(`wifi.networks[${i}].ssid`);
+        if (got.psk !== net.psk)
+            mismatch(`wifi.networks[${i}].psk`);
+    });
+}
+//# sourceMappingURL=boot-partition.js.map

package/dist/lib/flash/bootstrap.d.ts

@@ -0,0 +1,35 @@
+export interface WifiNetwork {
+    ssid: string;
+    /** Omitted entirely for an open network. */
+    psk?: string;
+}
+export interface BootstrapInput {
+    hostname?: string;
+    profileId?: string;
+    token: string;
+    wifiCountry: string;
+    /** Priority order — first entry is preferred. */
+    wifiNetworks: WifiNetwork[];
+    sshAuthorizedKey: string;
+    provisionUrl?: string;
+    brokerUri?: string;
+}
+/**
+ * Render bootstrap.toml matching the gateway's parser at
+ * embedded/products/gateway-rpi/src/mkd_gateway/bootstrap.py.
+ *
+ * Always UTF-8 with no BOM — the Pi's tomllib rejects a BOM.
+ */
+export declare function renderBootstrapToml(input: BootstrapInput): string;
+/**
+ * Parse bootstrap.toml back into the input shape. Used to prove a written
+ * file round-trips — byte-comparing our own output against itself would
+ * not catch an escaping bug.
+ */
+export declare function parseBootstrapToml(text: string): BootstrapInput;
+/**
+ * Render a hostname from a pattern. Hostnames must be unique per device,
+ * so patterns are expected to reference the device id.
+ */
+export declare function renderHostname(pattern: string, deviceId: string): string;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/lib/flash/bootstrap.js

@@ -0,0 +1,105 @@
+import { parse as parseToml } from "smol-toml";
+/** RFC-1123 label rules, which is what hostnamectl will accept. */
+const HOSTNAME_RE = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/;
+/**
+ * Serialize a TOML basic string. We escape rather than rely on literal
+ * strings because PSKs routinely contain quotes and backslashes.
+ */
+function tomlString(value) {
+    const escaped = value
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r")
+        .replace(/\t/g, "\\t");
+    return `"${escaped}"`;
+}
+/**
+ * Render bootstrap.toml matching the gateway's parser at
+ * embedded/products/gateway-rpi/src/mkd_gateway/bootstrap.py.
+ *
+ * Always UTF-8 with no BOM — the Pi's tomllib rejects a BOM.
+ */
+export function renderBootstrapToml(input) {
+    if (input.wifiNetworks.length === 0) {
+        throw new Error("At least one WiFi network is required.");
+    }
+    const lines = [];
+    lines.push("# Generated by `iot flash`. Consumed and deleted on first boot.");
+    lines.push("");
+    if (input.hostname || input.profileId) {
+        lines.push("[device]");
+        if (input.hostname)
+            lines.push(`hostname = ${tomlString(input.hostname)}`);
+        if (input.profileId)
+            lines.push(`profile_id = ${tomlString(input.profileId)}`);
+        lines.push("");
+    }
+    lines.push("[provision]");
+    lines.push(`token = ${tomlString(input.token)}`);
+    lines.push("");
+    lines.push("[wifi]");
+    lines.push(`country = ${tomlString(input.wifiCountry)}`);
+    lines.push("");
+    for (const net of input.wifiNetworks) {
+        lines.push("[[wifi.networks]]");
+        lines.push(`ssid = ${tomlString(net.ssid)}`);
+        if (net.psk !== undefined)
+            lines.push(`psk = ${tomlString(net.psk)}`);
+        lines.push("");
+    }
+    lines.push("[ssh]");
+    lines.push(`authorized_key = ${tomlString(input.sshAuthorizedKey)}`);
+    lines.push("");
+    if (input.provisionUrl || input.brokerUri) {
+        lines.push("[backend]");
+        if (input.provisionUrl)
+            lines.push(`provision_url = ${tomlString(input.provisionUrl)}`);
+        if (input.brokerUri)
+            lines.push(`broker_uri = ${tomlString(input.brokerUri)}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Parse bootstrap.toml back into the input shape. Used to prove a written
+ * file round-trips — byte-comparing our own output against itself would
+ * not catch an escaping bug.
+ */
+export function parseBootstrapToml(text) {
+    const raw = parseToml(text);
+    const rawNets = raw.wifi?.networks;
+    const networks = Array.isArray(rawNets)
+        ? rawNets
+            .filter((n) => typeof n?.ssid === "string")
+            .map((n) => (n.psk === undefined ? { ssid: n.ssid } : { ssid: n.ssid, psk: n.psk }))
+        : raw.wifi?.ssid
+            ? [raw.wifi.psk === undefined ? { ssid: raw.wifi.ssid } : { ssid: raw.wifi.ssid, psk: raw.wifi.psk }]
+            : [];
+    return {
+        hostname: raw.device?.hostname,
+        profileId: raw.device?.profile_id,
+        token: raw.provision?.token ?? "",
+        wifiCountry: raw.wifi?.country ?? "",
+        wifiNetworks: networks,
+        sshAuthorizedKey: raw.ssh?.authorized_key ?? "",
+        provisionUrl: raw.backend?.provision_url,
+        brokerUri: raw.backend?.broker_uri,
+    };
+}
+/**
+ * Render a hostname from a pattern. Hostnames must be unique per device,
+ * so patterns are expected to reference the device id.
+ */
+export function renderHostname(pattern, deviceId) {
+    const short = deviceId.split("-")[0] ?? deviceId;
+    const out = pattern
+        .replace(/\{deviceIdShort\}/g, short)
+        .replace(/\{deviceId\}/g, deviceId);
+    if (!HOSTNAME_RE.test(out)) {
+        throw new Error(`Pattern "${pattern}" produced "${out}", which is not a valid hostname ` +
+            "(letters, digits and hyphens only; must start and end alphanumeric).");
+    }
+    return out;
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/lib/flash/platform.d.ts

@@ -0,0 +1,23 @@
+import type { IotClient } from "../client.js";
+export interface MintResult {
+    token: string;
+    deviceId: string;
+    deviceName: string;
+    provisionEndpoint: string;
+    expiresAt: string;
+}
+export interface EnrolmentResult {
+    online: boolean;
+    status: string;
+    lastSeenAt: string | null;
+    timedOut: boolean;
+}
+export declare function mintRegistrationToken(client: IotClient, deviceName: string): Promise<MintResult>;
+export declare function waitForEnrolment(client: IotClient, deviceId: string, opts: {
+    timeoutMs: number;
+    intervalMs: number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    onPoll?: (status: string) => void;
+}): Promise<EnrolmentResult>;
+//# sourceMappingURL=platform.d.ts.map

package/dist/lib/flash/platform.js

@@ -0,0 +1,75 @@
+import { ApiError, CLIError, EXIT } from "../errors.js";
+/**
+ * A device that has never checked in has no lastSeenAt. Treat "has a
+ * lastSeenAt at all" as the enrolment signal — a freshly booted device
+ * reporting in is exactly the success criterion, and this avoids
+ * hard-coding a status vocabulary the platform may extend.
+ */
+function isOnline(status, lastSeenAt) {
+    if (!lastSeenAt)
+        return false;
+    return status !== "PENDING";
+}
+export async function mintRegistrationToken(client, deviceName) {
+    let data;
+    // The client middleware THROWS ApiError on non-2xx, so the 404 case must be
+    // caught, not read off a returned `error` field.
+    try {
+        const res = await client.POST("/v1/devices/registration/tokens", {
+            body: { deviceName },
+        });
+        data = res.data;
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404) {
+            throw new CLIError("The registration endpoint returned 404. API keys are organization-scoped " +
+                "under row-level security, so a key belonging to a different organization " +
+                "looks identical to a missing endpoint.", EXIT.NOT_FOUND, 'Check `iot context current` and that the key belongs to the target organization.');
+        }
+        throw err;
+    }
+    if (!data) {
+        throw new CLIError("The platform returned an empty registration response.");
+    }
+    const result = data;
+    if (!result.token || result.token.split(".").length !== 3) {
+        throw new CLIError("The platform returned a malformed registration token.");
+    }
+    return result;
+}
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function waitForEnrolment(client, deviceId, opts) {
+    const sleep = opts.sleep ?? defaultSleep;
+    const now = opts.now ?? (() => Date.now());
+    const started = now();
+    let status = "UNKNOWN";
+    let lastSeenAt = null;
+    while (now() - started < opts.timeoutMs) {
+        try {
+            const { data } = await client.GET("/v1/devices/{id}", {
+                params: { path: { id: deviceId } },
+            });
+            if (data) {
+                const d = data;
+                status = d.status ?? "UNKNOWN";
+                lastSeenAt = d.lastSeenAt ?? null;
+                opts.onPoll?.(status);
+                if (isOnline(status, lastSeenAt)) {
+                    return { online: true, status, lastSeenAt, timedOut: false };
+                }
+            }
+        }
+        catch (err) {
+            // The card is already written by the time we poll, so a transient blip
+            // must not abort the wait. Bad credentials, however, will never recover
+            // and would otherwise burn the full timeout in silence.
+            if (err instanceof ApiError && (err.status === 401 || err.status === 403)) {
+                throw err;
+            }
+            status = "UNREACHABLE";
+        }
+        await sleep(opts.intervalMs);
+    }
+    return { online: false, status, lastSeenAt, timedOut: true };
+}
+//# sourceMappingURL=platform.js.map

package/dist/lib/flash/profile.d.ts

@@ -0,0 +1,23 @@
+import type { WifiNetwork } from "./bootstrap.js";
+export declare const DEFAULT_COUNTRY = "DE";
+export declare const DEFAULT_HOSTNAME_PATTERN = "gw-{deviceIdShort}";
+export interface FlashProfile {
+    sshKeyPath?: string;
+    country: string;
+    hostnamePattern: string;
+    /**
+     * `prompt-always` means a customer's WiFi credentials are used for one
+     * flash and never written to disk.
+     */
+    wifiMode: "store" | "prompt-always";
+    wifiNetworks?: WifiNetwork[];
+    context?: string;
+    profileId?: string;
+}
+export declare function getAllFlashProfiles(): Record<string, FlashProfile>;
+export declare function getFlashProfile(name: string): FlashProfile | undefined;
+export declare function setFlashProfile(name: string, profile: FlashProfile): void;
+export declare function deleteFlashProfile(name: string): void;
+export declare function getActiveFlashProfileName(): string | undefined;
+export declare function setActiveFlashProfile(name: string): void;
+//# sourceMappingURL=profile.d.ts.map

package/dist/lib/flash/profile.js

@@ -0,0 +1,45 @@
+import { store } from "../config.js";
+export const DEFAULT_COUNTRY = "DE";
+export const DEFAULT_HOSTNAME_PATTERN = "gw-{deviceIdShort}";
+const PROFILES_KEY = "flashProfiles";
+const ACTIVE_KEY = "activeFlashProfile";
+export function getAllFlashProfiles() {
+    return (store.get(PROFILES_KEY) ?? {});
+}
+export function getFlashProfile(name) {
+    return getAllFlashProfiles()[name];
+}
+export function setFlashProfile(name, profile) {
+    const profiles = getAllFlashProfiles();
+    // Enforce the privacy promise at the storage boundary rather than trusting
+    // every call site to strip credentials first.
+    const toStore = profile.wifiMode === "prompt-always"
+        ? { ...profile, wifiNetworks: undefined }
+        : profile;
+    profiles[name] = toStore;
+    store.set(PROFILES_KEY, profiles);
+}
+export function deleteFlashProfile(name) {
+    const profiles = getAllFlashProfiles();
+    if (!profiles[name]) {
+        throw new Error(`Flash profile "${name}" does not exist.`);
+    }
+    delete profiles[name];
+    store.set(PROFILES_KEY, profiles);
+    if (getActiveFlashProfileName() === name) {
+        // conf's `set` rejects `undefined` ("Use `delete()` to clear values") —
+        // `delete()` is the correct way to unset a key.
+        store.delete(ACTIVE_KEY);
+    }
+}
+export function getActiveFlashProfileName() {
+    return store.get(ACTIVE_KEY);
+}
+export function setActiveFlashProfile(name) {
+    if (!getFlashProfile(name)) {
+        const available = Object.keys(getAllFlashProfiles()).join(", ") || "(none)";
+        throw new Error(`Flash profile "${name}" does not exist. Available profiles: ${available}`);
+    }
+    store.set(ACTIVE_KEY, name);
+}
+//# sourceMappingURL=profile.js.map

package/dist/lib/flash/resolve.d.ts

@@ -0,0 +1,45 @@
+import type { WifiNetwork } from "./bootstrap.js";
+export interface FlashFlags {
+    name?: string;
+    target?: string;
+    wifiSsid?: string[];
+    wifiPsk?: string[];
+    country?: string;
+    sshKey?: string;
+    hostname?: string;
+    profile?: string;
+    profileId?: string;
+    nonInteractive?: boolean;
+}
+export interface ResolveDeps {
+    promptText: (question: string, opts?: {
+        default?: string;
+    }) => Promise<string>;
+    promptSecret: (question: string) => Promise<string>;
+    isInteractive?: () => boolean;
+}
+export interface ResolvedFlashInputs {
+    deviceName: string;
+    wifiNetworks: WifiNetwork[];
+    country: string;
+    sshAuthorizedKey: string;
+    hostnamePattern: string;
+    hostnameOverride?: string;
+    profileId?: string;
+}
+/**
+ * Resolve every field with priority:
+ *   flag > env > profile > interactive prompt > error
+ *
+ * Prompting happens only when stdin is a TTY and --non-interactive is absent,
+ * so CI fails fast with a named flag instead of hanging on a prompt.
+ */
+export declare function resolveFlashInputs(flags: FlashFlags, deps: ResolveDeps): Promise<ResolvedFlashInputs>;
+/**
+ * --wifi-ssid and --wifi-psk are repeatable and positionally paired, so
+ * `--wifi-ssid A --wifi-psk a --wifi-ssid B --wifi-psk b` yields A/a then B/b.
+ * A network with no matching psk is treated as open. Shared with
+ * `flash profile set`, which pairs the same two flags into stored networks.
+ */
+export declare function pairWifiNetworks(ssids: string[], psks: string[]): WifiNetwork[];
+//# sourceMappingURL=resolve.d.ts.map

package/dist/lib/flash/resolve.js

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync } from "node:fs";
+import { getFlashProfile, getActiveFlashProfileName, DEFAULT_COUNTRY, DEFAULT_HOSTNAME_PATTERN, } from "./profile.js";
+function required(value, flag, interactive) {
+    if (value)
+        return value;
+    throw new Error(interactive
+        ? `Missing required value; pass ${flag}.`
+        : `Missing required value in non-interactive mode; pass ${flag}.`);
+}
+/**
+ * Resolve every field with priority:
+ *   flag > env > profile > interactive prompt > error
+ *
+ * Prompting happens only when stdin is a TTY and --non-interactive is absent,
+ * so CI fails fast with a named flag instead of hanging on a prompt.
+ */
+export async function resolveFlashInputs(flags, deps) {
+    const isTty = deps.isInteractive
+        ? deps.isInteractive()
+        : process.stdin.isTTY === true;
+    const interactive = !flags.nonInteractive && isTty;
+    const profileName = flags.profile ?? getActiveFlashProfileName();
+    const profile = profileName
+        ? getFlashProfile(profileName)
+        : undefined;
+    if (flags.profile && !profile) {
+        throw new Error(`Flash profile "${flags.profile}" does not exist.`);
+    }
+    // --- device name ---
+    let deviceName = flags.name ?? process.env.IOT_FLASH_DEVICE_NAME;
+    if (!deviceName && interactive) {
+        deviceName = await deps.promptText("Device name");
+    }
+    deviceName = required(deviceName, "--name", interactive);
+    // --- country ---
+    const country = flags.country ??
+        process.env.IOT_FLASH_COUNTRY ??
+        profile?.country ??
+        DEFAULT_COUNTRY;
+    // --- ssh key ---
+    let sshKeyPath = flags.sshKey ?? process.env.IOT_FLASH_SSH_KEY ?? profile?.sshKeyPath;
+    if (!sshKeyPath && interactive) {
+        sshKeyPath = await deps.promptText("Path to operator SSH public key");
+    }
+    sshKeyPath = required(sshKeyPath, "--ssh-key", interactive);
+    if (!existsSync(sshKeyPath)) {
+        throw new Error(`SSH public key not found: ${sshKeyPath}`);
+    }
+    const sshAuthorizedKey = readFileSync(sshKeyPath, "utf-8").trim();
+    if (!sshAuthorizedKey.startsWith("ssh-")) {
+        throw new Error(`${sshKeyPath} does not look like an SSH public key ` +
+            '(expected it to start with "ssh-"). Did you point at the private key?');
+    }
+    // --- wifi ---
+    let wifiNetworks = pairWifiFlags(flags);
+    if (wifiNetworks.length === 0 && profile?.wifiMode === "store") {
+        wifiNetworks = profile.wifiNetworks ?? [];
+    }
+    if (wifiNetworks.length === 0) {
+        if (!interactive) {
+            throw new Error("No WiFi network configured. Pass --wifi-ssid and --wifi-psk " +
+                "(repeat both, in priority order), or store them in a flash profile.");
+        }
+        const ssid = await deps.promptText("WiFi SSID");
+        if (!ssid)
+            throw new Error("A WiFi SSID is required.");
+        const psk = await deps.promptSecret("WiFi passphrase (blank for an open network)");
+        wifiNetworks = [psk ? { ssid, psk } : { ssid }];
+    }
+    return {
+        deviceName,
+        wifiNetworks,
+        country,
+        sshAuthorizedKey,
+        hostnamePattern: profile?.hostnamePattern ?? DEFAULT_HOSTNAME_PATTERN,
+        hostnameOverride: flags.hostname,
+        profileId: flags.profileId ?? profile?.profileId,
+    };
+}
+/**
+ * --wifi-ssid and --wifi-psk are repeatable and positionally paired, so
+ * `--wifi-ssid A --wifi-psk a --wifi-ssid B --wifi-psk b` yields A/a then B/b.
+ * A network with no matching psk is treated as open. Shared with
+ * `flash profile set`, which pairs the same two flags into stored networks.
+ */
+export function pairWifiNetworks(ssids, psks) {
+    return ssids.map((ssid, i) => {
+        const psk = psks[i];
+        return psk ? { ssid, psk } : { ssid };
+    });
+}
+function pairWifiFlags(flags) {
+    return pairWifiNetworks(flags.wifiSsid ?? [], flags.wifiPsk ?? []);
+}
+//# sourceMappingURL=resolve.js.map

package/dist/lib/prompt.d.ts

@@ -0,0 +1,13 @@
+/** Prompts always render on stderr so stdout stays machine-readable. */
+export declare function promptText(question: string, opts?: {
+    default?: string;
+}): Promise<string>;
+/** Hidden input for secrets (WiFi PSKs, API keys). */
+export declare function promptSecret(question: string): Promise<string>;
+/**
+ * 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.
+ */
+export declare function promptHidden(rl: import("node:readline/promises").Interface, prompt: string): Promise<string>;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/lib/prompt.js

@@ -0,0 +1,54 @@
+import { createInterface } from "node:readline/promises";
+/** Prompts always render on stderr so stdout stays machine-readable. */
+export async function promptText(question, opts = {}) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const suffix = opts.default ? ` [${opts.default}]` : "";
+        const answer = (await rl.question(`${question}${suffix}: `)).trim();
+        return answer || opts.default || "";
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Hidden input for secrets (WiFi PSKs, API keys). */
+export async function promptSecret(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return (await promptHidden(rl, `${question}: `)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * 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.
+ */
+export 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=prompt.js.map