@switchbot/openapi-cli 2.6.4 → 3.0.0

package/dist/api/client.js

@@ -87,6 +87,15 @@ export function createClient() {
             }
             throw new DryRunSignal(method, url);
         }
+        // P8: record the quota attempt BEFORE the request is dispatched so
+        // failures (timeouts / DNS errors / 5xx / aborted) also count. Only
+        // pre-flight refusals (daily-cap, --dry-run) above skip recording
+        // since they never touch the network. Retries re-enter this
+        // interceptor and record again, which matches the SwitchBot API
+        // billing model (every dispatched HTTP request consumes quota).
+        if (quotaEnabled) {
+            recordRequest(method, url);
+        }
         return config;
     });
     // Handle API-level errors (HTTP 200 but statusCode !== 100)
@@ -94,11 +103,6 @@ export function createClient() {
         if (verbose) {
             process.stderr.write(chalk.grey(`[verbose] ${response.status} ${response.statusText}\n`));
         }
-        if (quotaEnabled && response.config) {
-            const method = (response.config.method ?? 'get').toUpperCase();
-            const url = `${response.config.baseURL ?? ''}${response.config.url ?? ''}`;
-            recordRequest(method, url);
-        }
         const data = response.data;
         if (data.statusCode !== undefined && data.statusCode !== 100) {
             const msg = API_ERROR_MESSAGES[data.statusCode] ??
@@ -161,13 +165,10 @@ export function createClient() {
                     return sleep(delay).then(() => client.request(config));
                 }
             }
-            // Record exhausted/non-retryable HTTP responses too — they count
-            // against the daily quota.
-            if (quotaEnabled && error.response && config) {
-                const method = (config.method ?? 'get').toUpperCase();
-                const url = `${config.baseURL ?? ''}${config.url ?? ''}`;
-                recordRequest(method, url);
-            }
+            // P8: quota already recorded in the request interceptor before
+            // dispatch — no extra bookkeeping needed here on the error path.
+            // Timeouts, DNS failures, 5xx, and exhausted retries all counted
+            // when the attempt was first made.
             if (status === 401) {
                 throw new ApiError('Authentication failed: invalid token or daily 10,000-request quota exceeded', 401, {
                     transient: false,

package/dist/commands/agent-bootstrap.js

@@ -1,19 +1,24 @@
 import { printJson } from '../utils/output.js';
 import { loadCache } from '../devices/cache.js';
-import { getEffectiveCatalog } from '../devices/catalog.js';
+import { getEffectiveCatalog, deriveSafetyTier, CATALOG_SCHEMA_VERSION, } from '../devices/catalog.js';
 import { readProfileMeta } from '../config.js';
 import { todayUsage, DAILY_QUOTA } from '../utils/quota.js';
 import { ALL_STRATEGIES } from '../utils/name-resolver.js';
+import { IDENTITY } from './identity.js';
+import { resolvePolicyPath, loadPolicyFile, PolicyFileNotFoundError, PolicyYamlParseError, } from '../policy/load.js';
+import { validateLoadedPolicy } from '../policy/validate.js';
+import { selectCredentialStore } from '../credentials/keychain.js';
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 const { version: pkgVersion } = require('../../package.json');
-const IDENTITY = {
-    product: 'SwitchBot',
-    domain: 'IoT smart home device control',
-    vendor: 'Wonderlabs, Inc.',
-    apiVersion: 'v1.1',
-    authMethod: 'HMAC-SHA256 token+secret',
-};
+/**
+ * Schema version of the agent-bootstrap payload. Must stay in lockstep
+ * with the catalog schema — bootstrap consumers (AI agents) reason about
+ * catalog-derived fields (safetyTier, destructive flag), so a drift
+ * between the two would silently break their assumptions. `doctor`
+ * fails the `catalog-schema` check when these differ.
+ */
+export const AGENT_BOOTSTRAP_SCHEMA_VERSION = CATALOG_SCHEMA_VERSION;
 const SAFETY_TIERS = {
     read: 'No state mutation; safe to call freely.',
     action: 'Mutates device/cloud state but reversible (turnOn, setColor).',
@@ -26,7 +31,47 @@ const QUICK_REFERENCE = {
     observability: ['doctor --json', 'quota status', 'cache status', 'events mqtt-tail'],
     history: ['history range <id> --since 7d', 'history stats <id>'],
     meta: ['devices meta set <id> --alias <name>', 'devices meta list', 'devices meta get <id>'],
+    policy: ['policy validate', 'policy new', 'policy migrate'],
+    auth: ['auth keychain describe', 'auth keychain migrate', 'auth keychain get'],
 };
+function readPolicyStatus() {
+    // Lightweight read — used by the bootstrap payload so agents know whether
+    // a policy file exists and is healthy without shelling out to
+    // `switchbot policy validate`. Parallel to `checkPolicy` in doctor but
+    // returns a more compact shape (no first-error drill-down; agents who
+    // want that run the dedicated command).
+    const policyPath = resolvePolicyPath();
+    try {
+        const loaded = loadPolicyFile(policyPath);
+        const result = validateLoadedPolicy(loaded);
+        return {
+            present: true,
+            valid: result.valid,
+            path: policyPath,
+            schemaVersion: result.schemaVersion,
+            errorCount: result.valid ? 0 : result.errors.length,
+        };
+    }
+    catch (err) {
+        if (err instanceof PolicyFileNotFoundError) {
+            return { present: false, valid: null, path: policyPath };
+        }
+        if (err instanceof PolicyYamlParseError) {
+            return { present: true, valid: false, path: policyPath, errorCount: 1 };
+        }
+        return { present: false, valid: null, path: policyPath };
+    }
+}
+async function readCredentialsBackend() {
+    try {
+        const store = await selectCredentialStore();
+        const desc = store.describe();
+        return { name: store.name, label: desc.backend, writable: desc.writable };
+    }
+    catch {
+        return { name: 'file', label: 'File (~/.switchbot/config.json)', writable: true };
+    }
+}
 export function registerAgentBootstrapCommand(program) {
     program
         .command('agent-bootstrap')
@@ -47,12 +92,13 @@ Examples:
   $ switchbot agent-bootstrap | jq '.devices | length'
   $ switchbot agent-bootstrap --compact | jq '.quickReference'
 `)
-        .action((opts) => {
+        .action(async (opts) => {
         const compact = Boolean(opts.compact);
         const cache = loadCache();
         const catalog = getEffectiveCatalog();
         const usage = todayUsage();
         const meta = readProfileMeta(undefined);
+        const credentialsBackend = await readCredentialsBackend();
         const cachedDevices = cache
             ? Object.entries(cache.devices).map(([id, d]) => ({
                 deviceId: id,
@@ -83,17 +129,20 @@ Examples:
                 category: e.category,
                 role: e.role ?? null,
                 readOnly: e.readOnly ?? false,
-                commands: e.commands.map((c) => ({
-                    command: c.command,
-                    parameter: c.parameter,
-                    destructive: Boolean(c.destructive),
-                    idempotent: Boolean(c.idempotent),
-                })),
+                commands: e.commands.map((c) => {
+                    const tier = deriveSafetyTier(c, e);
+                    return {
+                        command: c.command,
+                        parameter: c.parameter,
+                        safetyTier: tier,
+                        idempotent: Boolean(c.idempotent),
+                    };
+                }),
                 statusFields: e.statusFields ?? [],
             };
         });
         const payload = {
-            schemaVersion: '1.0',
+            schemaVersion: AGENT_BOOTSTRAP_SCHEMA_VERSION,
             generatedAt: new Date().toISOString(),
             cliVersion: pkgVersion,
             identity: IDENTITY,
@@ -114,6 +163,8 @@ Examples:
                 remaining: usage.remaining,
                 dailyLimit: DAILY_QUOTA,
             },
+            policyStatus: readPolicyStatus(),
+            credentialsBackend,
             devices: cachedDevices,
             catalog: {
                 scope: cachedDevices.length > 0 ? 'used' : 'all',

package/dist/commands/auth.js

@@ -0,0 +1,354 @@
+/**
+ * `switchbot auth` command group (v2.9 preview, part of Phase 3A).
+ *
+ * Surfaces the credential store abstraction added in F1/F2 so users
+ * can introspect, write to, delete from, and migrate into the OS
+ * keychain without editing `~/.switchbot/config.json` by hand.
+ *
+ * All subcommands honour the active `--profile <name>` flag so a user
+ * who runs multiple accounts keeps the keychain entries cleanly
+ * partitioned.
+ *
+ * No credential material is ever printed in plain text. `get` emits
+ * a masked summary only; `set` reads via a TTY prompt (echo-off) or a
+ * file passed via `--stdin-file <path>`. `migrate` never touches the
+ * keychain unless the backend reports `writable: true`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import readline from 'node:readline';
+import { exitWithError, isJsonMode, printJson } from '../utils/output.js';
+import { stringArg } from '../utils/arg-parsers.js';
+import { getActiveProfile } from '../lib/request-context.js';
+import { selectCredentialStore, } from '../credentials/keychain.js';
+function activeProfile() {
+    return getActiveProfile() ?? 'default';
+}
+function maskValue(value) {
+    if (value.length === 0)
+        return '';
+    if (value.length <= 4)
+        return '*'.repeat(value.length);
+    const head = value.slice(0, 2);
+    const tail = value.slice(-2);
+    return `${head}${'*'.repeat(Math.max(4, value.length - 4))}${tail}`;
+}
+async function promptSecret(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+    return new Promise((resolve) => {
+        process.stderr.write(question);
+        const stdin = process.stdin;
+        let answer = '';
+        const onData = (chunk) => {
+            const s = chunk.toString('utf-8');
+            for (const ch of s) {
+                if (ch === '\r' || ch === '\n') {
+                    stdin.removeListener('data', onData);
+                    if (stdin.setRawMode)
+                        stdin.setRawMode(false);
+                    stdin.pause();
+                    process.stderr.write('\n');
+                    rl.close();
+                    resolve(answer);
+                    return;
+                }
+                if (ch === '\u0003') {
+                    process.exit(130);
+                }
+                if (ch === '\u007f' || ch === '\b') {
+                    answer = answer.slice(0, -1);
+                    continue;
+                }
+                answer += ch;
+            }
+        };
+        if (stdin.setRawMode)
+            stdin.setRawMode(true);
+        stdin.resume();
+        stdin.on('data', onData);
+    });
+}
+function readStdinFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        exitWithError({
+            code: 2,
+            kind: 'usage',
+            message: `--stdin-file: file not found: ${filePath}`,
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch (err) {
+        exitWithError({
+            code: 2,
+            kind: 'usage',
+            message: `--stdin-file: invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
+        });
+    }
+    if (!parsed ||
+        typeof parsed !== 'object' ||
+        typeof parsed.token !== 'string' ||
+        typeof parsed.secret !== 'string') {
+        exitWithError({
+            code: 2,
+            kind: 'usage',
+            message: '--stdin-file must contain a JSON object with "token" and "secret" strings.',
+        });
+    }
+    const { token, secret } = parsed;
+    if (!token || !secret) {
+        exitWithError({
+            code: 2,
+            kind: 'usage',
+            message: '--stdin-file: token and secret must be non-empty.',
+        });
+    }
+    return { token, secret };
+}
+function cleanupMigratedSourceFile(sourceFile, parsed) {
+    const next = { ...parsed };
+    delete next.token;
+    delete next.secret;
+    if (Object.keys(next).length === 0) {
+        fs.unlinkSync(sourceFile);
+        return 'deleted';
+    }
+    fs.writeFileSync(sourceFile, JSON.stringify(next, null, 2), { mode: 0o600 });
+    return 'scrubbed';
+}
+export function registerAuthCommand(program) {
+    const auth = program
+        .command('auth')
+        .description('Manage SwitchBot credentials in the OS keychain (preview)');
+    const keychain = auth
+        .command('keychain')
+        .description('OS keychain backend (describe/get/set/delete/migrate)');
+    keychain
+        .command('describe')
+        .description('Show which credential backend is active on this machine')
+        .action(async () => {
+        const store = await selectCredentialStore();
+        const desc = store.describe();
+        if (isJsonMode()) {
+            printJson(desc);
+            return;
+        }
+        console.log(`backend : ${desc.backend}`);
+        console.log(`tag     : ${desc.tag}`);
+        console.log(`writable: ${desc.writable ? 'yes' : 'no'}`);
+        if (desc.notes)
+            console.log(`notes   : ${desc.notes}`);
+    });
+    keychain
+        .command('get')
+        .description('Check whether the active profile has credentials (masked output)')
+        .action(async () => {
+        const profile = activeProfile();
+        const store = await selectCredentialStore();
+        const creds = await store.get(profile);
+        if (!creds) {
+            if (isJsonMode()) {
+                printJson({ profile, backend: store.name, present: false });
+                return;
+            }
+            console.log(`No credentials found for profile "${profile}" in backend "${store.name}".`);
+            process.exit(1);
+        }
+        if (isJsonMode()) {
+            printJson({
+                profile,
+                backend: store.name,
+                present: true,
+                token: { length: creds.token.length, masked: maskValue(creds.token) },
+                secret: { length: creds.secret.length, masked: maskValue(creds.secret) },
+            });
+            return;
+        }
+        console.log(`profile : ${profile}`);
+        console.log(`backend : ${store.name}`);
+        console.log(`token   : ${maskValue(creds.token)} (${creds.token.length} chars)`);
+        console.log(`secret  : ${maskValue(creds.secret)} (${creds.secret.length} chars)`);
+    });
+    keychain
+        .command('set')
+        .description('Write token and secret to the keychain for the active profile')
+        .option('--stdin-file <path>', 'Read {"token","secret"} JSON from file (for non-TTY environments)', stringArg('--stdin-file'))
+        .action(async (options) => {
+        const profile = activeProfile();
+        const store = await selectCredentialStore();
+        if (!store.describe().writable) {
+            exitWithError({
+                code: 1,
+                kind: 'runtime',
+                message: `backend "${store.name}" is not writable on this machine`,
+                hint: 'Install the OS keychain helper or use ~/.switchbot/config.json directly.',
+            });
+        }
+        let bundle;
+        if (options.stdinFile) {
+            bundle = readStdinFile(options.stdinFile);
+        }
+        else if (process.stdin.isTTY) {
+            const token = (await promptSecret('Token : ')).trim();
+            const secret = (await promptSecret('Secret: ')).trim();
+            if (!token || !secret) {
+                exitWithError({
+                    code: 2,
+                    kind: 'usage',
+                    message: 'Both token and secret are required.',
+                });
+            }
+            bundle = { token, secret };
+        }
+        else {
+            exitWithError({
+                code: 2,
+                kind: 'usage',
+                message: 'Non-TTY input requires --stdin-file <path>.',
+            });
+        }
+        try {
+            await store.set(profile, bundle);
+        }
+        catch (err) {
+            exitWithError({
+                code: 1,
+                kind: 'runtime',
+                message: `keychain write failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        if (isJsonMode()) {
+            printJson({ profile, backend: store.name, written: true });
+            return;
+        }
+        console.log(`Stored credentials for profile "${profile}" in backend "${store.name}".`);
+    });
+    keychain
+        .command('delete')
+        .description('Remove credentials for the active profile from the keychain')
+        .option('--yes', 'Skip the interactive confirmation prompt')
+        .action(async (options) => {
+        const profile = activeProfile();
+        const store = await selectCredentialStore();
+        if (!options.yes && process.stdin.isTTY) {
+            const reply = (await promptSecret(`Delete credentials for profile "${profile}" from backend "${store.name}"? type DELETE to confirm: `)).trim();
+            if (reply !== 'DELETE') {
+                if (isJsonMode()) {
+                    printJson({ profile, backend: store.name, deleted: false, reason: 'cancelled' });
+                    return;
+                }
+                console.log('Aborted.');
+                process.exit(0);
+            }
+        }
+        try {
+            await store.delete(profile);
+        }
+        catch (err) {
+            exitWithError({
+                code: 1,
+                kind: 'runtime',
+                message: `keychain delete failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        if (isJsonMode()) {
+            printJson({ profile, backend: store.name, deleted: true });
+            return;
+        }
+        console.log(`Deleted credentials for profile "${profile}" in backend "${store.name}".`);
+    });
+    keychain
+        .command('migrate')
+        .description('Copy credentials from ~/.switchbot/config.json (or --profile) into the keychain')
+        .option('--delete-file', 'Remove the source credential file when possible; otherwise scrub token/secret and keep metadata')
+        .action(async (options) => {
+        const profile = activeProfile();
+        const store = await selectCredentialStore();
+        if (!store.describe().writable) {
+            exitWithError({
+                code: 1,
+                kind: 'runtime',
+                message: `backend "${store.name}" is not writable on this machine`,
+            });
+        }
+        const sourceFile = profile === 'default'
+            ? path.join(os.homedir(), '.switchbot', 'config.json')
+            : path.join(os.homedir(), '.switchbot', 'profiles', `${profile}.json`);
+        if (!fs.existsSync(sourceFile)) {
+            exitWithError({
+                code: 2,
+                kind: 'usage',
+                message: `source file not found: ${sourceFile}`,
+                hint: 'Run "switchbot config set-token" first or use "switchbot auth keychain set" directly.',
+            });
+        }
+        let parsed;
+        try {
+            const raw = JSON.parse(fs.readFileSync(sourceFile, 'utf-8'));
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+                throw new Error('expected a JSON object');
+            }
+            parsed = raw;
+        }
+        catch (err) {
+            exitWithError({
+                code: 1,
+                kind: 'runtime',
+                message: `failed to parse ${sourceFile}: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        const token = typeof parsed.token === 'string' ? parsed.token : '';
+        const secret = typeof parsed.secret === 'string' ? parsed.secret : '';
+        if (!token || !secret) {
+            exitWithError({
+                code: 1,
+                kind: 'runtime',
+                message: `source file missing token or secret: ${sourceFile}`,
+            });
+        }
+        try {
+            await store.set(profile, { token, secret });
+        }
+        catch (err) {
+            exitWithError({
+                code: 1,
+                kind: 'runtime',
+                message: `keychain write failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        let cleanup = 'kept';
+        if (options.deleteFile) {
+            try {
+                cleanup = cleanupMigratedSourceFile(sourceFile, parsed);
+            }
+            catch (err) {
+                // Non-fatal: migration succeeded, we just couldn't clean up.
+                console.error(`warning: could not remove ${sourceFile}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        if (isJsonMode()) {
+            printJson({
+                profile,
+                backend: store.name,
+                migrated: true,
+                sourceFile,
+                sourceDeleted: cleanup === 'deleted',
+                sourceScrubbed: cleanup === 'scrubbed',
+            });
+            return;
+        }
+        console.log(`Migrated profile "${profile}" to backend "${store.name}".`);
+        const cleanupNote = cleanup === 'deleted'
+            ? ' (deleted)'
+            : cleanup === 'scrubbed'
+                ? ' (credentials removed; metadata kept)'
+                : '';
+        console.log(`source: ${sourceFile}${cleanupNote}`);
+        if (!options.deleteFile) {
+            console.log('Source file kept — pass --delete-file on the next run to remove it.');
+        }
+    });
+}

package/dist/commands/batch.js

@@ -1,5 +1,5 @@
 import { intArg, enumArg, stringArg } from '../utils/arg-parsers.js';
-import { printJson, isJsonMode, handleError, buildErrorPayload, UsageError, emitJsonError, exitWithError } from '../utils/output.js';
+import { printJson, isJsonMode, handleError, buildErrorPayload, UsageError, exitWithError } from '../utils/output.js';
 import { fetchDeviceList, executeCommand, isDestructiveCommand, buildHubLocationMap, } from '../lib/devices.js';
 import { createClient } from '../api/client.js';
 import { parseFilter, applyFilter, FilterSyntaxError } from '../utils/filter.js';
@@ -96,7 +96,8 @@ export function registerBatchCommand(devices) {
         .option('--concurrency <n>', 'Max parallel in-flight requests (default 5)', intArg('--concurrency', { min: 1 }), '5')
         .option('--max-concurrent <n>', 'Alias for --concurrency; takes priority when set', intArg('--max-concurrent', { min: 1 }))
         .option('--stagger <ms>', 'Fixed delay between task starts in ms (default 0 = random 20-60ms jitter)', intArg('--stagger', { min: 0 }), '0')
-        .option('--plan', 'With --dry-run: emit a plan JSON document instead of executing anything')
+        .option('--plan', '[DEPRECATED, use --emit-plan] With --dry-run: emit a plan JSON document instead of executing anything')
+        .option('--emit-plan', 'With --dry-run: emit a plan JSON document instead of executing anything')
         .option('--yes', 'Allow destructive commands (Smart Lock unlock, garage open, ...)')
         .option('--type <commandType>', '"command" (default) or "customize" for user-defined IR buttons', enumArg('--type', COMMAND_TYPES), 'command')
         .option('--stdin', 'Read deviceIds from stdin, one per line (same as trailing "-")')
@@ -127,8 +128,9 @@ Concurrency & pacing:
   --stagger <ms>         Fixed delay between task starts; default 0 uses random 20-60ms jitter.
 
 Planning:
-  --dry-run --plan       Print the plan JSON without executing anything. Useful
+  --dry-run --emit-plan  Print the plan JSON without executing anything. Useful
                          for agents that want to show the user what will run.
+                         (--plan is the deprecated alias, removed in v3.0.)
 
 Safety:
   Destructive commands (Smart Lock unlock, Garage Door Opener turnOn/turnOff,
@@ -146,6 +148,17 @@ Examples:
         // Trailing "-" sentinel selects stdin mode.
         const extra = commandObj.args ?? [];
         const readStdin = Boolean(options.stdin) || extra.includes('-');
+        // P12: --plan is deprecated in favor of --emit-plan. Reject both
+        // together (conflicting) and warn when only the old flag is used.
+        if (options.plan && options.emitPlan) {
+            handleError(new UsageError('Use --emit-plan; --plan is deprecated and cannot be combined with --emit-plan.'));
+            return;
+        }
+        if (options.plan && !options.emitPlan) {
+            // Warning goes to stderr so it cannot corrupt --json output on stdout.
+            console.error('[WARN] --plan is deprecated; use --emit-plan. Will be removed in v3.0.');
+        }
+        const emitPlan = Boolean(options.emitPlan || options.plan);
         // Accept --idempotency-key as alias; reject when both forms are supplied.
         if (options.idempotencyKey !== undefined && options.idempotencyKeyPrefix !== undefined) {
             handleError(new UsageError('Use either --idempotency-key or --idempotency-key-prefix, not both.'));
@@ -216,22 +229,14 @@ Examples:
             }
         }
         if (blockedForDestructive.length > 0 && !options.yes) {
-            if (isJsonMode()) {
-                const deviceIds = blockedForDestructive.map((b) => b.deviceId);
-                emitJsonError({
-                    code: 2,
-                    kind: 'guard',
-                    message: `Destructive command "${cmd}" requires --yes to run on ${blockedForDestructive.length} device(s).`,
-                    hint: 'Re-issue the call with --yes to proceed.',
-                    context: { command: cmd, deviceIds },
-                });
-            }
-            else {
-                console.error(`Refusing to run destructive command "${cmd}" on ${blockedForDestructive.length} device(s) without --yes:`);
-                for (const b of blockedForDestructive)
-                    console.error(`  ${b.deviceId}`);
-            }
-            process.exit(2);
+            const deviceIds = blockedForDestructive.map((b) => b.deviceId);
+            exitWithError({
+                code: 2,
+                kind: 'guard',
+                message: `Refusing to run destructive command "${cmd}" on ${blockedForDestructive.length} device(s) without --yes: ${deviceIds.join(', ')}`,
+                hint: 'Re-issue the call with --yes to proceed.',
+                context: { command: cmd, deviceIds },
+            });
         }
         // parameter may be a JSON object string; mirror the single-command action.
         let parsedParam = parameter ?? 'default';
@@ -247,8 +252,8 @@ Examples:
         const concurrency = Math.max(1, Number.parseInt(maxConcurrentRaw, 10) || DEFAULT_CONCURRENCY);
         const staggerMs = Math.max(0, Number.parseInt(options.stagger, 10) || 0);
         const dryRun = isDryRun();
-        // --dry-run --plan: emit a plan document and return without executing.
-        if (dryRun && options.plan) {
+        // --dry-run --emit-plan (or legacy --plan): emit a plan document and return without executing.
+        if (dryRun && emitPlan) {
             const steps = resolved.ids.map((id) => ({
                 deviceId: id,
                 command: cmd,