@switchbot/openapi-cli 2.6.4 → 3.0.0

package/dist/commands/capabilities.js

@@ -1,7 +1,27 @@
-import { getEffectiveCatalog } from '../devices/catalog.js';
+import { getEffectiveCatalog, deriveSafetyTier, deriveStatusQueries, } from '../devices/catalog.js';
+import { RESOURCE_CATALOG } from '../devices/resources.js';
 import { loadCache } from '../devices/cache.js';
 import { printJson } from '../utils/output.js';
 import { enumArg, stringArg } from '../utils/arg-parsers.js';
+import { IDENTITY } from './identity.js';
+/** Collect the distinct catalog safety tiers actually used across the given entries. Sorted. */
+function collectSafetyTiersInUse(entries) {
+    const seen = new Set();
+    for (const e of entries) {
+        for (const c of e.commands) {
+            seen.add(deriveSafetyTier(c, e));
+        }
+        // P11: statusQueries contribute the 'read' tier.
+        if (deriveStatusQueries(e).length > 0) {
+            seen.add('read');
+        }
+    }
+    return [...seen].sort();
+}
+/** P11: total number of read-only queries exposed across the catalog. */
+function countStatusQueries(entries) {
+    return entries.reduce((n, e) => n + deriveStatusQueries(e).length, 0);
+}
 const AGENT_GUIDE = {
     safetyTiers: {
         read: 'No state mutation; safe to call freely — does not consume quota unless noted.',
@@ -68,23 +88,6 @@ const COMMAND_META = {
 function metaFor(command) {
     return COMMAND_META[command] ?? null;
 }
-const IDENTITY = {
-    product: 'SwitchBot',
-    domain: 'IoT smart home device control',
-    vendor: 'Wonderlabs, Inc.',
-    apiVersion: 'v1.1',
-    apiDocs: 'https://github.com/OpenWonderLabs/SwitchBotAPI',
-    deviceCategories: {
-        physical: 'Wi-Fi/BLE devices controllable via Cloud API (Hub required for BLE-only)',
-        ir: 'IR remote devices learned by a SwitchBot Hub (TV, AC, etc.)',
-    },
-    constraints: {
-        quotaPerDay: 10000,
-        bleRequiresHub: true,
-        authMethod: 'HMAC-SHA256 token+secret',
-    },
-    agentGuide: 'docs/agent-guide.md',
-};
 const MCP_TOOLS = [
     'list_devices',
     'get_device_status',
@@ -147,7 +150,7 @@ export function registerCapabilitiesCommand(program) {
     const SURFACES = ['cli', 'mcp', 'plan', 'mqtt', 'all'];
     program
         .command('capabilities')
-        .description('Print a machine-readable manifest of CLI capabilities (for agent bootstrap)')
+        .description('Print a machine-readable manifest of SwitchBot CLI capabilities (for AI agent bootstrap)')
         .option('--minimal', 'Omit per-subcommand flag details to reduce output size (alias of --compact)')
         .option('--compact', 'Emit a compact summary: identity + leaf command list with safety metadata only')
         .option('--used', 'Restrict the catalog summary to device types present in the local cache. Mirrors `schema export --used`.')
@@ -249,9 +252,12 @@ export function registerCapabilitiesCommand(program) {
             catalog: {
                 typeCount: catalog.length,
                 roles,
-                destructiveCommandCount: catalog.reduce((n, e) => n + e.commands.filter((c) => c.destructive).length, 0),
+                destructiveCommandCount: catalog.reduce((n, e) => n + e.commands.filter((c) => deriveSafetyTier(c, e) === 'destructive').length, 0),
+                safetyTiersInUse: collectSafetyTiersInUse(catalog),
                 readOnlyTypeCount: catalog.filter((e) => e.readOnly).length,
+                readOnlyQueryCount: countStatusQueries(catalog),
             },
+            resources: RESOURCE_CATALOG,
         };
         if (!compact)
             payload.generatedAt = new Date().toISOString();
@@ -273,8 +279,10 @@ export function registerCapabilitiesCommand(program) {
                 payload.catalog = {
                     typeCount: filteredCatalog.length,
                     roles: [...new Set(filteredCatalog.map((e) => e.role ?? 'other'))].sort(),
-                    destructiveCommandCount: filteredCatalog.reduce((n, e) => n + e.commands.filter((c) => c.destructive).length, 0),
+                    destructiveCommandCount: filteredCatalog.reduce((n, e) => n + e.commands.filter((c) => deriveSafetyTier(c, e) === 'destructive').length, 0),
+                    safetyTiersInUse: collectSafetyTiersInUse(filteredCatalog),
                     readOnlyTypeCount: filteredCatalog.filter((e) => e.readOnly).length,
+                    readOnlyQueryCount: countStatusQueries(filteredCatalog),
                 };
                 payload.usedFilter = { applied: true, typesInCache: [...seen].sort() };
             }

package/dist/commands/catalog.js

@@ -1,12 +1,12 @@
 import { enumArg } from '../utils/arg-parsers.js';
 import { printTable, printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
 import { resolveFormat, resolveFields, renderRows } from '../utils/format.js';
-import { DEVICE_CATALOG, findCatalogEntry, getCatalogOverlayPath, getEffectiveCatalog, loadCatalogOverlay, resetCatalogOverlayCache, } from '../devices/catalog.js';
+import { DEVICE_CATALOG, findCatalogEntry, getCatalogOverlayPath, getEffectiveCatalog, loadCatalogOverlay, resetCatalogOverlayCache, deriveSafetyTier, } from '../devices/catalog.js';
 export function registerCatalogCommand(program) {
     const SOURCES = ['built-in', 'overlay', 'effective'];
     const catalog = program
         .command('catalog')
-        .description('Inspect the built-in device catalog and any local overlay')
+        .description('Inspect the SwitchBot device catalog (supported device types + any local overlay)')
         .addHelpText('after', `
 This CLI ships with a static catalog of known SwitchBot device types and
 their commands (see 'switchbot devices types'). You can extend or override
@@ -341,10 +341,11 @@ function renderEntry(entry) {
     else {
         console.log('\nCommands:');
         const rows = entry.commands.map((c) => {
+            const tier = deriveSafetyTier(c, entry);
             const flags = [];
             if (c.commandType === 'customize')
                 flags.push('customize');
-            if (c.destructive)
+            if (tier === 'destructive')
                 flags.push('!destructive');
             const label = flags.length > 0 ? `${c.command}  [${flags.join(', ')}]` : c.command;
             return [label, c.parameter, c.description];

package/dist/commands/config.js

@@ -4,7 +4,7 @@ import { execFileSync } from 'node:child_process';
 import { stringArg } from '../utils/arg-parsers.js';
 import { intArg } from '../utils/arg-parsers.js';
 import { saveConfig, showConfig, getConfigSummary, listProfiles, readProfileMeta } from '../config.js';
-import { isJsonMode, printJson, emitJsonError } from '../utils/output.js';
+import { isJsonMode, printJson, exitWithError } from '../utils/output.js';
 import chalk from 'chalk';
 function parseEnvFile(file) {
     const out = {};
@@ -89,6 +89,36 @@ async function promptSecret(question) {
         void mutableStdout;
     });
 }
+/**
+ * Interactive echo-off prompt for token + secret. Used by both
+ * `switchbot config set-token` and the install orchestrator. Throws if
+ * stdin is not a TTY.
+ */
+export async function promptTokenAndSecret() {
+    if (!process.stdin.isTTY) {
+        throw new Error('interactive prompt requires a TTY');
+    }
+    const token = (await promptSecret('Token: ')).trim();
+    const secret = (await promptSecret('Secret: ')).trim();
+    if (!token || !secret) {
+        throw new Error('token and secret are both required');
+    }
+    return { token, secret };
+}
+/**
+ * Read a two-line credential file (line 1 = token, line 2 = secret)
+ * and unlink it on success. The installer's `--token-file` escape
+ * hatch uses this; keeps credentials off the command line and shell
+ * history for CI-style installs.
+ */
+export function readCredentialsFile(filePath) {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const lines = raw.split(/\r?\n/).filter((l) => l.length > 0);
+    if (lines.length < 2) {
+        throw new Error(`credential file ${filePath} must contain two lines: token, then secret`);
+    }
+    return { token: lines[0].trim(), secret: lines[1].trim() };
+}
 export function registerConfigCommand(program) {
     const config = program
         .command('config')
@@ -145,14 +175,11 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
         }
         if (options.fromEnvFile) {
             if (!fs.existsSync(options.fromEnvFile)) {
-                const msg = `--from-env-file: file not found: ${options.fromEnvFile}`;
-                if (isJsonMode()) {
-                    emitJsonError({ code: 2, kind: 'usage', message: msg });
-                }
-                else {
-                    console.error(msg);
-                }
-                process.exit(2);
+                exitWithError({
+                    code: 2,
+                    kind: 'usage',
+                    message: `--from-env-file: file not found: ${options.fromEnvFile}`,
+                });
             }
             const parsed = parseEnvFile(options.fromEnvFile);
             token = token ?? parsed.token;
@@ -160,37 +187,33 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
         }
         if (options.fromOp) {
             if (!options.opSecret) {
-                const msg = '--from-op requires --op-secret <ref> for the secret reference.';
-                if (isJsonMode()) {
-                    emitJsonError({ code: 2, kind: 'usage', message: msg });
-                }
-                else {
-                    console.error(msg);
-                }
-                process.exit(2);
+                exitWithError({
+                    code: 2,
+                    kind: 'usage',
+                    message: '--from-op requires --op-secret <ref> for the secret reference.',
+                });
             }
             try {
                 token = readFromOp(options.fromOp);
                 secret = readFromOp(options.opSecret);
             }
             catch (err) {
-                const msg = `1Password CLI read failed: ${err instanceof Error ? err.message : String(err)}`;
-                if (isJsonMode()) {
-                    emitJsonError({ code: 1, kind: 'runtime', message: msg, hint: 'Ensure the "op" CLI is installed and authenticated (op signin).' });
-                }
-                else {
-                    console.error(msg);
-                    console.error('Ensure the "op" CLI is installed and authenticated (op signin).');
-                }
-                process.exit(1);
+                exitWithError({
+                    code: 1,
+                    kind: 'runtime',
+                    message: `1Password CLI read failed: ${err instanceof Error ? err.message : String(err)}`,
+                    hint: 'Ensure the "op" CLI is installed and authenticated (op signin).',
+                });
             }
         }
         // No credentials yet and stdin is a TTY → interactive prompt (safest path).
         if ((!token || !secret) && !options.fromEnvFile && !options.fromOp && process.stdin.isTTY) {
             if (isJsonMode()) {
-                const msg = 'Interactive mode cannot run under --json. Provide token/secret via --from-env-file, --from-op, or positional args.';
-                emitJsonError({ code: 2, kind: 'usage', message: msg });
-                process.exit(2);
+                exitWithError({
+                    code: 2,
+                    kind: 'usage',
+                    message: 'Interactive mode cannot run under --json. Provide token/secret via --from-env-file, --from-op, or positional args.',
+                });
             }
             try {
                 if (!token)
@@ -204,14 +227,11 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
             }
         }
         if (!token || !secret) {
-            const msg = 'Missing token/secret. Run interactively, or use --from-env-file / --from-op, or pass positional arguments (discouraged).';
-            if (isJsonMode()) {
-                emitJsonError({ code: 2, kind: 'usage', message: msg });
-            }
-            else {
-                console.error(msg);
-            }
-            process.exit(2);
+            exitWithError({
+                code: 2,
+                kind: 'usage',
+                message: 'Missing token/secret. Run interactively, or use --from-env-file / --from-op, or pass positional arguments (discouraged).',
+            });
         }
         saveConfig(token, secret, {
             label: options.label,

package/dist/commands/devices.js

@@ -1,7 +1,7 @@
 import { enumArg, stringArg } from '../utils/arg-parsers.js';
-import { printTable, printKeyValue, printJson, isJsonMode, handleError, UsageError, StructuredUsageError, emitJsonError, exitWithError } from '../utils/output.js';
+import { printTable, printKeyValue, printJson, isJsonMode, handleError, UsageError, StructuredUsageError, exitWithError } from '../utils/output.js';
 import { resolveFormat, resolveFields, renderRows } from '../utils/format.js';
-import { findCatalogEntry, getEffectiveCatalog } from '../devices/catalog.js';
+import { findCatalogEntry, getEffectiveCatalog, deriveSafetyTier, getCommandSafetyReason, } from '../devices/catalog.js';
 import { getCachedDevice, loadCache } from '../devices/cache.js';
 import { loadDeviceMeta } from '../devices/device-meta.js';
 import { resolveDeviceId, ALL_STRATEGIES } from '../utils/name-resolver.js';
@@ -15,7 +15,7 @@ import { registerExpandCommand } from './expand.js';
 import { registerDevicesMetaCommand } from './device-meta.js';
 import { isDryRun } from '../utils/flags.js';
 import { DryRunSignal } from '../api/client.js';
-import { resolveField, listSupportedFieldInputs } from '../schema/field-aliases.js';
+import { resolveField, resolveFieldList, listSupportedFieldInputs } from '../schema/field-aliases.js';
 const EXPAND_HINTS = {
     'Air Conditioner': { command: 'setAll', flags: '--temp 26 --mode cool --fan low --power on' },
     'Curtain': { command: 'setPosition', flags: '--position 50 --mode silent' },
@@ -88,7 +88,7 @@ Examples:
 `)
         .option('--wide', 'Show all columns (controlType, family, roomID, room, hub, cloud)')
         .option('--show-hidden', 'Include devices hidden via "devices meta set --hide"')
-        .option('--filter <expr>', 'Filter devices: comma-separated clauses. Each clause is "key=value" (substring; exact for category), "key!=value" (negated substring), "key~value" (explicit substring), or "key=/regex/" (case-insensitive regex). Supported keys: deviceId/id, deviceName/name, deviceType/type, controlType, roomName/room, category.', stringArg('--filter'))
+        .option('--filter <expr>', 'Filter devices: comma-separated clauses. Each clause is "key=value" (substring; exact for category), "key!=value" (negated substring), "key~value" (explicit substring), or "key=/regex/" (case-insensitive regex). Supported keys: deviceId/id, deviceName/name, deviceType/type, controlType, roomName/room, category, familyName/family, hubDeviceId/hub, roomID/roomid, enableCloudService/cloud, alias.', stringArg('--filter'))
         .action(async (options) => {
         try {
             const body = await fetchDeviceList();
@@ -98,8 +98,11 @@ Examples:
             const hubLocation = buildHubLocationMap(deviceList);
             // Parse --filter into a list of clauses. Shared grammar across
             // `devices list`, `devices batch`, and `events tail` / `mqtt-tail`.
-            const LIST_KEYS = ['deviceId', 'type', 'name', 'category', 'room', 'controlType'];
-            const LIST_FILTER_CANONICAL = ['deviceId', 'deviceName', 'deviceType', 'controlType', 'roomName', 'category'];
+            const LIST_KEYS = ['deviceId', 'type', 'name', 'category', 'room', 'controlType',
+                'family', 'hub', 'roomID', 'cloud', 'alias'];
+            const LIST_FILTER_CANONICAL = ['deviceId', 'deviceName', 'deviceType', 'controlType',
+                'roomName', 'category', 'familyName', 'hubDeviceId', 'roomID',
+                'enableCloudService', 'alias'];
             const LIST_FILTER_TO_RUNTIME = {
                 deviceId: 'deviceId',
                 deviceName: 'name',
@@ -107,6 +110,11 @@ Examples:
                 controlType: 'controlType',
                 roomName: 'room',
                 category: 'category',
+                familyName: 'family',
+                hubDeviceId: 'hub',
+                roomID: 'roomID',
+                enableCloudService: 'cloud',
+                alias: 'alias',
             };
             let listClauses = null;
             if (options.filter) {
@@ -137,10 +145,10 @@ Examples:
             };
             if (fmt === 'json' && process.argv.includes('--json')) {
                 if (listClauses) {
-                    const filteredDeviceList = deviceList.filter((d) => matchesFilter({ deviceId: d.deviceId, type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '', controlType: d.controlType || '' }));
+                    const filteredDeviceList = deviceList.filter((d) => matchesFilter({ deviceId: d.deviceId, type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '', controlType: d.controlType || '', family: d.familyName || '', hub: d.hubDeviceId || '', roomID: d.roomID || '', cloud: String(d.enableCloudService), alias: deviceMeta.devices[d.deviceId]?.alias || '' }));
                     const filteredIrList = infraredRemoteList.filter((d) => {
                         const inherited = hubLocation.get(d.hubDeviceId);
-                        return matchesFilter({ deviceId: d.deviceId, type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '', controlType: d.controlType || '' });
+                        return matchesFilter({ deviceId: d.deviceId, type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '', controlType: d.controlType || '', family: inherited?.family || '', hub: d.hubDeviceId || '', roomID: inherited?.roomID || '', cloud: '', alias: deviceMeta.devices[d.deviceId]?.alias || '' });
                     });
                     printJson({ ok: true, deviceList: filteredDeviceList, infraredRemoteList: filteredIrList });
                 }
@@ -157,7 +165,7 @@ Examples:
             for (const d of deviceList) {
                 if (!options.showHidden && deviceMeta.devices[d.deviceId]?.hidden)
                     continue;
-                if (!matchesFilter({ deviceId: d.deviceId, type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '', controlType: d.controlType || '' }))
+                if (!matchesFilter({ deviceId: d.deviceId, type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '', controlType: d.controlType || '', family: d.familyName || '', hub: d.hubDeviceId || '', roomID: d.roomID || '', cloud: String(d.enableCloudService), alias: deviceMeta.devices[d.deviceId]?.alias || '' }))
                     continue;
                 rows.push([
                     d.deviceId,
@@ -177,7 +185,7 @@ Examples:
                 if (!options.showHidden && deviceMeta.devices[d.deviceId]?.hidden)
                     continue;
                 const inherited = hubLocation.get(d.hubDeviceId);
-                if (!matchesFilter({ deviceId: d.deviceId, type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '', controlType: d.controlType || '' }))
+                if (!matchesFilter({ deviceId: d.deviceId, type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '', controlType: d.controlType || '', family: inherited?.family || '', hub: d.hubDeviceId || '', roomID: inherited?.roomID || '', cloud: '', alias: deviceMeta.devices[d.deviceId]?.alias || '' }))
                     continue;
                 rows.push([
                     d.deviceId,
@@ -280,7 +288,7 @@ Examples:
                     }
                 }
                 else {
-                    const fields = resolveFields();
+                    const rawFields = resolveFields();
                     for (const entry of batch) {
                         const { deviceId, ok, error, _fetchedAt: ts, ...status } = entry;
                         console.log(`\n─── ${String(deviceId)} ───`);
@@ -288,9 +296,13 @@ Examples:
                             console.error(`  error: ${String(error)}`);
                         }
                         else {
+                            const statusMap = status;
+                            const fields = rawFields
+                                ? resolveFieldList(rawFields, Object.keys(statusMap))
+                                : undefined;
                             const displayStatus = fields
-                                ? Object.fromEntries(fields.map((f) => [f, status[f] ?? null]))
-                                : status;
+                                ? Object.fromEntries(fields.map((f) => [f, statusMap[f] ?? null]))
+                                : statusMap;
                             printKeyValue(displayStatus);
                             console.error(`  fetched at ${String(ts)}`);
                         }
@@ -315,7 +327,10 @@ Examples:
                 const statusWithTs = { ...body, _fetchedAt: fetchedAt };
                 const allHeaders = Object.keys(statusWithTs);
                 const allRows = [Object.values(statusWithTs)];
-                const fields = resolveFields();
+                const rawFields = resolveFields();
+                const fields = rawFields
+                    ? resolveFieldList(rawFields, allHeaders)
+                    : undefined;
                 renderRows(allHeaders, allRows, fmt, fields);
                 return;
             }
@@ -453,26 +468,22 @@ Examples:
             const validation = validateCommand(deviceId, cmd, parameter, options.type);
             if (!validation.ok) {
                 const err = validation.error;
-                if (isJsonMode()) {
-                    const obj = { code: 2, kind: 'usage', message: err.message };
-                    if (err.hint)
-                        obj.hint = err.hint;
-                    obj.context = { validationKind: err.kind };
-                    emitJsonError(obj);
-                }
-                else {
-                    console.error(`Error: ${err.message}`);
-                    if (err.hint)
-                        console.error(err.hint);
-                    if (err.kind === 'unknown-command') {
-                        const cached = getCachedDevice(deviceId);
-                        if (cached) {
-                            console.error(`Run 'switchbot devices commands ${JSON.stringify(cached.type)}' for parameter formats and descriptions.`);
-                            console.error(`(If the catalog is out of date, run 'switchbot devices list' to refresh the local cache, or pass --type customize for custom IR buttons.)`);
-                        }
+                let hint = err.hint;
+                if (err.kind === 'unknown-command') {
+                    const cached = getCachedDevice(deviceId);
+                    if (cached) {
+                        const extra = `Run 'switchbot devices commands ${JSON.stringify(cached.type)}' for parameter formats and descriptions.\n` +
+                            `(If the catalog is out of date, run 'switchbot devices list' to refresh the local cache, or pass --type customize for custom IR buttons.)`;
+                        hint = hint ? `${hint}\n${extra}` : extra;
                     }
                 }
-                process.exit(2);
+                exitWithError({
+                    code: 2,
+                    kind: 'usage',
+                    message: err.message,
+                    hint,
+                    context: { validationKind: err.kind },
+                });
             }
             // Case-only mismatch: emit a warning and continue with the canonical name.
             if (validation.caseNormalizedFrom && validation.normalized) {
@@ -507,7 +518,7 @@ Examples:
                     hint: reason
                         ? `Re-run with --yes to confirm. Reason: ${reason}`
                         : 'Re-run with --yes to confirm, or --dry-run to preview without sending.',
-                    context: { command: cmd, deviceType: typeLabel, deviceId, ...(reason ? { destructiveReason: reason } : {}) },
+                    context: { command: cmd, deviceType: typeLabel, deviceId, ...(reason ? { safetyReason: reason, destructiveReason: reason } : {}) },
                 });
             }
             // Warn when --yes is given but the command is not destructive (no-op flag)
@@ -645,7 +656,7 @@ Examples:
             const joinedMatch = findCatalogEntry(joined);
             if (joinedMatch && !Array.isArray(joinedMatch)) {
                 if (isJsonMode()) {
-                    printJson(joinedMatch);
+                    printJson(normalizeCatalogForJson(joinedMatch));
                 }
                 else {
                     renderCatalogEntry(joinedMatch);
@@ -664,7 +675,7 @@ Examples:
                 }
                 if (individualMatches.length === typeParts.length) {
                     if (isJsonMode()) {
-                        printJson(individualMatches);
+                        printJson(individualMatches.map(normalizeCatalogForJson));
                     }
                     else {
                         individualMatches.forEach((entry, i) => {
@@ -824,6 +835,20 @@ Examples:
     // switchbot devices meta set/get/list/clear
     registerDevicesMetaCommand(devices);
 }
+function normalizeCatalogForJson(entry) {
+    return {
+        ...entry,
+        commands: entry.commands.map((c) => {
+            const tier = deriveSafetyTier(c, entry);
+            const reason = getCommandSafetyReason(c);
+            return {
+                ...c,
+                safetyTier: tier,
+                ...(reason ? { safetyReason: reason } : {}),
+            };
+        }),
+    };
+}
 function renderCatalogEntry(entry) {
     console.log(`Type:     ${entry.type}`);
     console.log(`Category: ${entry.category === 'ir' ? 'IR remote' : 'Physical device'}`);
@@ -841,10 +866,11 @@ function renderCatalogEntry(entry) {
         console.log('\nCommands:');
         const hasExamples = entry.commands.some((c) => c.exampleParams && c.exampleParams.length > 0);
         const rows = entry.commands.map((c) => {
+            const tier = deriveSafetyTier(c, entry);
             const flags = [];
             if (c.commandType === 'customize')
                 flags.push('customize');
-            if (c.destructive)
+            if (tier === 'destructive')
                 flags.push('!destructive');
             const label = flags.length > 0 ? `${c.command}  [${flags.join(', ')}]` : c.command;
             const base = [label, c.parameter, c.description];
@@ -854,7 +880,7 @@ function renderCatalogEntry(entry) {
             ? ['command', 'parameter', 'description', 'example']
             : ['command', 'parameter', 'description'];
         printTable(tableHeaders, rows);
-        const hasDestructive = entry.commands.some((c) => c.destructive);
+        const hasDestructive = entry.commands.some((c) => deriveSafetyTier(c, entry) === 'destructive');
         if (hasDestructive) {
             console.log('\n[!destructive] commands have hard-to-reverse real-world effects — confirm before issuing.');
         }