@switchbot/openapi-cli 2.7.2 → 3.1.0

package/dist/credentials/prime.js

@@ -0,0 +1,52 @@
+/**
+ * Credential priming cache.
+ *
+ * `loadConfig()` runs synchronously, but every OS keychain backend is
+ * async (subprocess-based). We bridge the two by priming credentials
+ * once per command, early in the `preAction` hook, and keeping the
+ * result in a tiny in-process cache keyed by profile name.
+ *
+ * After priming, sync callers can consult `getPrimedCredentials()` to
+ * pick up keychain-stored token/secret without any await.
+ *
+ * This module intentionally swallows errors — a flaky keychain
+ * probe must never block the CLI from running. When the probe fails
+ * we behave as "nothing primed" and the existing file path is used.
+ */
+import { selectCredentialStore } from './keychain.js';
+let cache = null;
+/**
+ * Look up the given profile in the active credential store and cache
+ * the result. Safe to call multiple times — subsequent calls with the
+ * same profile short-circuit against the cache. Swallows all errors.
+ */
+export async function primeCredentials(profile) {
+    if (cache?.profile === profile)
+        return;
+    try {
+        const store = await selectCredentialStore();
+        const creds = await store.get(profile);
+        cache = { profile, creds };
+    }
+    catch {
+        cache = { profile, creds: null };
+    }
+}
+/**
+ * Sync accessor for code paths that cannot be made async. Returns
+ * null when the cache is empty or keyed against a different profile,
+ * so existing file-based fallback stays the authoritative source.
+ */
+export function getPrimedCredentials(profile) {
+    if (!cache)
+        return null;
+    if (cache.profile !== profile)
+        return null;
+    return cache.creds;
+}
+/**
+ * Test helper. Not used by production code.
+ */
+export function __resetPrimedCredentials() {
+    cache = null;
+}

package/dist/devices/catalog.js

@@ -10,9 +10,6 @@
  *   - CommandSpec.safetyTier: explicit action safety classification. See
  *     SafetyTier for the 5-tier enum. Built-in entries set this on the
  *     destructive tier; other tiers are derived (see deriveSafetyTier).
- *   - CommandSpec.destructive (deprecated, v3.0 removal): legacy boolean
- *     that maps to safetyTier === 'destructive'. Still accepted in
- *     ~/.switchbot/catalog.json overlays and derived into safetyTier.
  *   - DeviceCatalogEntry.role: functional grouping for filter/search
  *     ("all lighting", "all security"). Does not affect API behavior.
  *   - DeviceCatalogEntry.readOnly: the device has no control commands; it
@@ -629,25 +626,22 @@ export function findCatalogEntry(query) {
  *
  * The inference order is:
  *   1. Explicit `spec.safetyTier`.
- *   2. Legacy `spec.destructive: true` → `'destructive'` (overlay compat).
- *   3. IR context (customize command OR entry.category === 'ir')
+ *   2. IR context (customize command OR entry.category === 'ir')
  *      → `'ir-fire-forget'`.
- *   4. Default → `'mutation'`.
+ *   3. Default → `'mutation'`.
  */
 export function deriveSafetyTier(spec, entry) {
     if (spec.safetyTier)
         return spec.safetyTier;
-    if (spec.destructive)
-        return 'destructive';
     if (spec.commandType === 'customize')
         return 'ir-fire-forget';
     if (entry?.category === 'ir')
         return 'ir-fire-forget';
     return 'mutation';
 }
-/** Read the safety reason for a command, with fallback to the legacy field. */
+/** Read the safety reason for a command. */
 export function getCommandSafetyReason(spec) {
-    return spec.safetyReason ?? spec.destructiveReason ?? null;
+    return spec.safetyReason ?? null;
 }
 /**
  * Pick up to 3 non-destructive, idempotent commands an agent can safely invoke

package/dist/index.js

@@ -23,6 +23,17 @@ import { registerHistoryCommand } from './commands/history.js';
 import { registerPlanCommand } from './commands/plan.js';
 import { registerCapabilitiesCommand } from './commands/capabilities.js';
 import { registerAgentBootstrapCommand } from './commands/agent-bootstrap.js';
+import { registerPolicyCommand } from './commands/policy.js';
+import { registerRulesCommand } from './commands/rules.js';
+import { registerAuthCommand } from './commands/auth.js';
+import { registerInstallCommand } from './commands/install.js';
+import { registerUninstallCommand } from './commands/uninstall.js';
+import { registerStatusSyncCommand } from './commands/status-sync.js';
+import { registerHealthCommand } from './commands/health.js';
+import { registerUpgradeCheckCommand } from './commands/upgrade-check.js';
+import { registerDaemonCommand } from './commands/daemon.js';
+import { primeCredentials } from './credentials/prime.js';
+import { getActiveProfile } from './lib/request-context.js';
 const require = createRequire(import.meta.url);
 const { version: pkgVersion } = require('../package.json');
 // Early initialization: check for --no-color flag or NO_COLOR env var and disable chalk.
@@ -41,7 +52,8 @@ if (isJsonMode()) {
 const TOP_LEVEL_COMMANDS = [
     'config', 'devices', 'scenes', 'webhook', 'completion', 'mcp',
     'quota', 'catalog', 'cache', 'events', 'doctor', 'schema',
-    'history', 'plan', 'capabilities', 'agent-bootstrap',
+    'history', 'plan', 'capabilities', 'agent-bootstrap', 'install', 'uninstall', 'status-sync',
+    'health', 'upgrade-check', 'daemon',
 ];
 const cacheModeArg = (value) => {
     if (value.startsWith('-')) {
@@ -94,6 +106,22 @@ registerHistoryCommand(program);
 registerPlanCommand(program);
 registerCapabilitiesCommand(program);
 registerAgentBootstrapCommand(program);
+registerPolicyCommand(program);
+registerRulesCommand(program);
+registerAuthCommand(program);
+registerInstallCommand(program);
+registerUninstallCommand(program);
+registerStatusSyncCommand(program);
+registerHealthCommand(program);
+registerUpgradeCheckCommand(program);
+registerDaemonCommand(program);
+// Prime keychain-stored credentials before any command runs. This is a
+// best-effort probe: failures are silently swallowed inside primeCredentials,
+// so the existing file-based path remains the safety net. We probe once per
+// invocation (even for --help and --version, which is harmless).
+program.hook('preAction', async () => {
+    await primeCredentials(getActiveProfile() ?? 'default');
+});
 program.addHelpText('after', `
 Credentials:
   Provide SwitchBot API v1.1 credentials via either:
@@ -122,6 +150,7 @@ Examples:
   $ switchbot devices command <deviceId> turnOn --dry-run
   $ switchbot scenes execute <sceneId> --verbose
   $ switchbot webhook setup https://your.host/hook
+  $ switchbot status-sync start --openclaw-model home-agent
 
 Discovery:
   Don't know a device ID / what it supports?

package/dist/install/default-steps.js

@@ -0,0 +1,257 @@
+/**
+ * Default install steps used by `switchbot install` (Phase 3B in-repo).
+ *
+ * Each factory returns an `InstallStep<InstallContext>` whose `execute`
+ * and `undo` both operate on the shared context. Steps are intentionally
+ * small — each one either mutates one system (keychain / filesystem /
+ * symlink) or captures input, never a mix. The orchestrator composes
+ * them in `src/commands/install.ts`.
+ *
+ * The step runner (`src/install/steps.ts`) handles rollback on failure;
+ * these factories just make sure every `execute` records what it needs
+ * into the context so the matching `undo` can unwind it.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { scaffoldPolicyFile, PolicyFileExistsError, } from '../commands/policy.js';
+import { promptTokenAndSecret, readCredentialsFile } from '../commands/config.js';
+import { selectCredentialStore } from '../credentials/keychain.js';
+// ---------------------------------------------------------------------------
+// Step 1: capture credentials (memory only — no side effects until step 2)
+// ---------------------------------------------------------------------------
+export function stepPromptCredentials() {
+    return {
+        name: 'prompt-credentials',
+        description: 'Collect SwitchBot token + secret (interactive unless --token-file)',
+        async execute(ctx) {
+            if (ctx.credentials)
+                return; // already provided via API consumer
+            if (ctx.tokenFile) {
+                const creds = readCredentialsFile(ctx.tokenFile);
+                ctx.credentials = creds;
+                return;
+            }
+            if (ctx.nonInteractive) {
+                throw new Error('no --token-file and stdin is not a TTY; pass --token-file <path> to install non-interactively');
+            }
+            ctx.credentials = await promptTokenAndSecret();
+        },
+        undo() {
+            // No disk state created; clearing memory is enough.
+            // The calling process will exit shortly after rollback, but null
+            // the field for defence-in-depth.
+            return;
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Step 2: write credentials to keychain (or file fallback)
+// ---------------------------------------------------------------------------
+export function stepWriteKeychain() {
+    return {
+        name: 'write-keychain',
+        description: 'Store credentials in the OS keychain (falls back to ~/.switchbot/config.json)',
+        async execute(ctx) {
+            if (!ctx.credentials) {
+                throw new Error('internal: credentials missing at write-keychain; prompt step must run first');
+            }
+            const store = await selectCredentialStore();
+            const previous = await store.get(ctx.profile);
+            ctx.previousCredentials = previous;
+            await store.set(ctx.profile, ctx.credentials);
+            ctx.credentialStore = store;
+            ctx.credentialsWereStored = true;
+        },
+        async undo(ctx) {
+            if (!ctx.credentialsWereStored || !ctx.credentialStore)
+                return;
+            try {
+                if (ctx.previousCredentials) {
+                    await ctx.credentialStore.set(ctx.profile, ctx.previousCredentials);
+                }
+                else {
+                    await ctx.credentialStore.delete(ctx.profile);
+                }
+            }
+            finally {
+                ctx.credentialsWereStored = false;
+                ctx.previousCredentials = undefined;
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Step 3: scaffold policy.yaml if missing (skip if present, don't clobber)
+// ---------------------------------------------------------------------------
+export function stepScaffoldPolicy() {
+    return {
+        name: 'scaffold-policy',
+        description: 'Create a starter policy.yaml (only if none exists)',
+        execute(ctx) {
+            try {
+                const result = scaffoldPolicyFile(ctx.policyPath, { skipExisting: true });
+                ctx.policyScaffoldResult = result;
+            }
+            catch (err) {
+                if (err instanceof PolicyFileExistsError) {
+                    // skipExisting is true → this branch is unreachable, but be
+                    // defensive against future changes.
+                    return;
+                }
+                throw err;
+            }
+        },
+        undo(ctx) {
+            const r = ctx.policyScaffoldResult;
+            if (!r || r.skipped)
+                return;
+            // Only remove the file if WE created it (skipped === false means
+            // we wrote fresh content to a path that did not exist before).
+            try {
+                fs.unlinkSync(r.policyPath);
+            }
+            catch {
+                // best-effort; do not fail rollback on cleanup
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Step 4: install skill into the agent's skills directory
+// ---------------------------------------------------------------------------
+/**
+ * Compute the on-disk location where an agent expects to find this skill.
+ * Only `claude-code` has an automation path today; others are informational
+ * (the installer will print a recipe instead of creating anything).
+ */
+export function skillLinkPathFor(agent, home = os.homedir()) {
+    if (agent === 'claude-code') {
+        return path.join(home, '.claude', 'skills', 'switchbot');
+    }
+    return null;
+}
+export function stepSymlinkSkill(opts = {}) {
+    return {
+        name: 'symlink-skill',
+        description: 'Link the skill into ~/.claude/skills/switchbot (Claude Code)',
+        execute(ctx) {
+            if (ctx.agent === 'none')
+                return;
+            if (!ctx.skillPath) {
+                // Informational path: print the recipe, do not fail. Undo can
+                // safely no-op in this branch.
+                ctx.skillRecipePrinted = true;
+                return;
+            }
+            const target = path.resolve(ctx.skillPath);
+            if (!fs.existsSync(target)) {
+                throw new Error(`--skill-path does not exist: ${target}`);
+            }
+            const stat = fs.statSync(target);
+            if (!stat.isDirectory()) {
+                throw new Error(`--skill-path is not a directory: ${target}`);
+            }
+            const linkPath = skillLinkPathFor(ctx.agent);
+            if (!linkPath) {
+                // Non-automating agent: print a recipe instead of creating state.
+                ctx.skillRecipePrinted = true;
+                return;
+            }
+            // A2: require a SKILL.md only when we are about to create a link.
+            // Non-automating agents (cursor/copilot) print a recipe and return
+            // above, so they are never blocked by this check.
+            if (!opts.force && !fs.existsSync(path.join(target, 'SKILL.md'))) {
+                throw new Error(`${target} does not look like a skill (no SKILL.md at the root). ` +
+                    'Pass --force if you really mean to link this directory.');
+            }
+            if (fs.existsSync(linkPath)) {
+                const st = fs.lstatSync(linkPath);
+                if (st.isSymbolicLink()) {
+                    // A3: tolerate an existing link only when it points at the same
+                    // target; otherwise the user is likely trying to repoint and we
+                    // should not silently pretend success. --force replaces it.
+                    let existingTarget = null;
+                    try {
+                        existingTarget = path.resolve(path.dirname(linkPath), fs.readlinkSync(linkPath));
+                    }
+                    catch {
+                        existingTarget = null;
+                    }
+                    if (existingTarget === target) {
+                        ctx.skillLinkPath = linkPath;
+                        ctx.skillLinkCreated = false;
+                        return;
+                    }
+                    if (!opts.force) {
+                        throw new Error(`${linkPath} already links to ${existingTarget ?? '(unreadable)'}; ` +
+                            'pass --force to replace it, or run `switchbot uninstall` first.');
+                    }
+                    fs.unlinkSync(linkPath);
+                }
+                else {
+                    throw new Error(`${linkPath} exists and is not a symlink; refusing to clobber (move it aside and re-run)`);
+                }
+            }
+            fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+            // Windows: regular symlinks require admin or Developer Mode. A
+            // directory junction works for any user and is transparent to
+            // most tools. Unix: plain symlink.
+            const linkType = process.platform === 'win32' ? 'junction' : 'dir';
+            fs.symlinkSync(target, linkPath, linkType);
+            ctx.skillLinkPath = linkPath;
+            ctx.skillLinkCreated = true;
+        },
+        undo(ctx) {
+            if (!ctx.skillLinkCreated || !ctx.skillLinkPath)
+                return;
+            try {
+                fs.unlinkSync(ctx.skillLinkPath);
+            }
+            catch {
+                // best-effort
+            }
+        },
+    };
+}
+function defaultDoctorSpawner(cliPath, profile) {
+    const args = profile === 'default' ? [cliPath, 'doctor', '--json'] : [cliPath, '--profile', profile, 'doctor', '--json'];
+    const r = spawnSync(process.execPath, args, { encoding: 'utf-8' });
+    return {
+        ok: r.status === 0,
+        exitCode: r.status,
+        stdout: r.stdout ?? '',
+        stderr: r.stderr ?? '',
+    };
+}
+export function stepDoctorVerify(opts = { cliPath: '' }) {
+    const spawner = opts.spawner ?? defaultDoctorSpawner;
+    const cliPath = opts.cliPath;
+    return {
+        name: 'doctor-verify',
+        description: 'Verify the install with switchbot doctor --json',
+        execute(ctx) {
+            if (!cliPath) {
+                // Fail closed: without a known CLI path we cannot spawn doctor.
+                // Mark not-ok but still succeed (no rollback).
+                ctx.doctorOk = false;
+                ctx.doctorReport = { skipped: true, reason: 'no cliPath provided' };
+                return;
+            }
+            const r = spawner(cliPath, ctx.profile);
+            ctx.doctorOk = r.ok;
+            try {
+                ctx.doctorReport = r.stdout ? JSON.parse(r.stdout) : { exitCode: r.exitCode, stderr: r.stderr };
+            }
+            catch {
+                ctx.doctorReport = { exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr };
+            }
+            // NOTE: never throw here. Doctor failure is reported; rollback is
+            // opt-in by the user via `switchbot uninstall`.
+        },
+        undo() {
+            return;
+        },
+    };
+}

package/dist/install/preflight.js

@@ -0,0 +1,212 @@
+/**
+ * Install-orchestrator pre-flight (Phase 3A · F5).
+ *
+ * Pure library — no CLI entry. Consumers (e.g. a future
+ * `openclaw plugins install` command) call `runPreflight()` and decide
+ * whether to proceed based on the returned result. Nothing here mutates
+ * user state: every check is read-only.
+ *
+ * The check list mirrors `docs/design/phase3-install.md` step 1 minus
+ * the bits that require external services (npm registry / SwitchBot API
+ * reachability are left for the installer itself to probe when it has
+ * a plan to retry, since they are the flakiest of the lot).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { resolvePolicyPath, loadPolicyFile, PolicyFileNotFoundError } from '../policy/load.js';
+import { validateLoadedPolicy } from '../policy/validate.js';
+import { selectCredentialStore } from '../credentials/keychain.js';
+function parseMajor(version) {
+    const m = /^v?(\d+)\./.exec(version);
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    return Number.isFinite(n) ? n : null;
+}
+function checkNodeVersion(opts) {
+    const required = opts.minNodeMajor ?? 18;
+    const version = opts.nodeVersion ?? process.version;
+    const major = parseMajor(version);
+    if (major === null) {
+        return {
+            name: 'node',
+            status: 'fail',
+            message: `unrecognised Node.js version string: ${version}`,
+            hint: 'reinstall Node.js from https://nodejs.org',
+        };
+    }
+    if (major < required) {
+        return {
+            name: 'node',
+            status: 'fail',
+            message: `Node.js ${version} < required v${required}`,
+            hint: `upgrade Node.js to v${required} or later`,
+        };
+    }
+    return { name: 'node', status: 'ok', message: `Node.js ${version}` };
+}
+function checkPolicy() {
+    const policyPath = resolvePolicyPath();
+    try {
+        const loaded = loadPolicyFile(policyPath);
+        const result = validateLoadedPolicy(loaded);
+        if (result.valid) {
+            return {
+                name: 'policy',
+                status: 'ok',
+                message: `policy at ${policyPath} validates (v${result.schemaVersion ?? '?'})`,
+            };
+        }
+        return {
+            name: 'policy',
+            status: 'warn',
+            message: `policy at ${policyPath} has ${result.errors.length} validation error(s)`,
+            hint: 'run "switchbot policy validate" to see details before installing',
+        };
+    }
+    catch (err) {
+        if (err instanceof PolicyFileNotFoundError) {
+            return {
+                name: 'policy',
+                status: 'ok',
+                message: `no policy at ${policyPath} (installer will scaffold one)`,
+            };
+        }
+        return {
+            name: 'policy',
+            status: 'warn',
+            message: `policy at ${policyPath} is unreadable: ${err instanceof Error ? err.message : String(err)}`,
+            hint: 'move the file aside, then re-run — the installer will scaffold a fresh copy',
+        };
+    }
+}
+async function checkKeychain() {
+    try {
+        const store = await selectCredentialStore();
+        const desc = store.describe();
+        if (desc.writable) {
+            return {
+                name: 'keychain',
+                status: 'ok',
+                message: `credential backend: ${desc.backend}`,
+            };
+        }
+        return {
+            name: 'keychain',
+            status: 'warn',
+            message: `credential backend ${desc.backend} is not writable — will fall back to file`,
+            hint: desc.notes ?? 'install the OS keychain helper to get native credential storage',
+        };
+    }
+    catch (err) {
+        return {
+            name: 'keychain',
+            status: 'warn',
+            message: `keychain probe failed: ${err instanceof Error ? err.message : String(err)}`,
+            hint: 'the installer will fall back to the file backend',
+        };
+    }
+}
+function checkHomeDirWritable() {
+    const home = os.homedir();
+    const switchbotDir = path.join(home, '.switchbot');
+    try {
+        const homeStat = fs.statSync(home);
+        if (!homeStat.isDirectory()) {
+            return {
+                name: 'home',
+                status: 'fail',
+                message: `home path is not a directory: ${home}`,
+                hint: 'check your HOME/USERPROFILE environment configuration',
+            };
+        }
+        if (fs.existsSync(switchbotDir)) {
+            const sbStat = fs.statSync(switchbotDir);
+            if (!sbStat.isDirectory()) {
+                return {
+                    name: 'home',
+                    status: 'fail',
+                    message: `${switchbotDir} exists but is not a directory`,
+                    hint: 'move the file aside and re-run install',
+                };
+            }
+            fs.accessSync(switchbotDir, fs.constants.W_OK);
+            return { name: 'home', status: 'ok', message: `writable: ${switchbotDir}` };
+        }
+        fs.accessSync(home, fs.constants.W_OK);
+        return { name: 'home', status: 'ok', message: `writable: ${home}` };
+    }
+    catch (err) {
+        return {
+            name: 'home',
+            status: 'fail',
+            message: `cannot write under ${home}: ${err instanceof Error ? err.message : String(err)}`,
+            hint: 'check ownership and permissions on your home directory',
+        };
+    }
+}
+function nearestExistingPath(target) {
+    let cur = target;
+    while (true) {
+        if (fs.existsSync(cur))
+            return cur;
+        const parent = path.dirname(cur);
+        if (parent === cur)
+            return null;
+        cur = parent;
+    }
+}
+function checkAgentSkillDirWritable(opts) {
+    const shouldCheck = opts.agent === 'claude-code' && (opts.expectSkillLink ?? true);
+    if (!shouldCheck)
+        return null;
+    const home = os.homedir();
+    const target = path.join(home, '.claude', 'skills');
+    try {
+        const existing = nearestExistingPath(target);
+        if (!existing) {
+            return {
+                name: 'agent-skills-dir',
+                status: 'fail',
+                message: `cannot resolve an existing parent for ${target}`,
+                hint: 'check your home directory path and permissions',
+            };
+        }
+        const stat = fs.statSync(existing);
+        if (!stat.isDirectory()) {
+            return {
+                name: 'agent-skills-dir',
+                status: 'fail',
+                message: `path component is not a directory: ${existing}`,
+                hint: 'move the blocking file aside and re-run install',
+            };
+        }
+        fs.accessSync(existing, fs.constants.W_OK);
+        return { name: 'agent-skills-dir', status: 'ok', message: `writable: ${target}` };
+    }
+    catch (err) {
+        return {
+            name: 'agent-skills-dir',
+            status: 'fail',
+            message: `cannot write to ${target}: ${err instanceof Error ? err.message : String(err)}`,
+            hint: 'open Claude Code once (it will create ~/.claude) or create the directory manually',
+        };
+    }
+}
+/**
+ * Run every pre-flight check and return a combined result. Safe to
+ * call multiple times; no state is cached.
+ */
+export async function runPreflight(options = {}) {
+    const checks = [];
+    checks.push(checkNodeVersion(options));
+    checks.push(checkPolicy());
+    checks.push(await checkKeychain());
+    checks.push(checkHomeDirWritable());
+    const agentCheck = checkAgentSkillDirWritable(options);
+    if (agentCheck)
+        checks.push(agentCheck);
+    const ok = checks.every((c) => c.status !== 'fail');
+    return { checks, ok };
+}

package/dist/install/steps.js

@@ -0,0 +1,67 @@
+/**
+ * Install-orchestrator step runner (Phase 3A · F5).
+ *
+ * Each step has a deterministic `execute` and a matching `undo`. The
+ * runner executes steps in order; on any failure it walks the
+ * already-completed steps in reverse and invokes their `undo`. If an
+ * `undo` itself fails, the error is captured and surfaced — the
+ * runner does NOT abort the rollback. The caller gets a full report
+ * and can decide how to surface partial cleanup failures.
+ *
+ * The module is intentionally agnostic of what steps do; consumers
+ * (future `openclaw plugins install`) plug in concrete steps like
+ * "npm i -g the CLI" or "write the credential to the keychain".
+ */
+/**
+ * Run the given steps in order. On the first failure, the runner
+ * walks already-executed steps in reverse and invokes each step's
+ * undo. Returns a report describing every step's fate.
+ */
+export async function runInstall(steps, options = {}) {
+    const ctx = (options.context ?? {});
+    const outcomes = [];
+    const executed = [];
+    let failedAt;
+    for (const step of steps) {
+        try {
+            await step.execute(ctx);
+            outcomes.push({ step: step.name, status: 'succeeded' });
+            executed.push(step);
+        }
+        catch (err) {
+            outcomes.push({
+                step: step.name,
+                status: 'failed',
+                error: err instanceof Error ? err.message : String(err),
+            });
+            failedAt = step.name;
+            break;
+        }
+        if (options.stopAfter === step.name)
+            break;
+    }
+    if (failedAt !== undefined) {
+        // Roll back completed steps in reverse. Undo failures are captured
+        // but do not abort further rollback attempts — the goal is to
+        // leave as little residue as possible.
+        for (let i = executed.length - 1; i >= 0; i--) {
+            const step = executed[i];
+            try {
+                await step.undo(ctx);
+                outcomes.push({ step: step.name, status: 'rolled-back' });
+            }
+            catch (err) {
+                outcomes.push({
+                    step: step.name,
+                    status: 'rollback-failed',
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+    return {
+        ok: failedAt === undefined,
+        outcomes,
+        ...(failedAt !== undefined ? { failedAt } : {}),
+    };
+}