@switchbot/openapi-cli 2.7.2 → 3.0.0

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 } : {}),
+    };
+}

package/dist/lib/command-keywords.js

@@ -0,0 +1,17 @@
+export const COMMAND_KEYWORDS = [
+    { pattern: /\boff\b|\bturn.?off\b|\bstop\b/i, command: 'turnOff' },
+    { pattern: /\bon\b|\bturn.?on\b|\bstart\b/i, command: 'turnOn' },
+    { pattern: /\bpress\b|\bclick\b|\btap\b/i, command: 'press' },
+    { pattern: /\block\b/i, command: 'lock' },
+    { pattern: /\bunlock\b/i, command: 'unlock' },
+    { pattern: /\bopen\b|\braise\b|\bup\b/i, command: 'open' },
+    { pattern: /\bclose\b|\blower\b|\bdown\b/i, command: 'close' },
+    { pattern: /\bpause\b/i, command: 'pause' },
+];
+export function inferCommandFromIntent(intent) {
+    for (const k of COMMAND_KEYWORDS) {
+        if (k.pattern.test(intent))
+            return k.command;
+    }
+    return undefined;
+}

package/dist/lib/devices.js

@@ -272,7 +272,6 @@ export async function describeDevice(deviceId, options = {}, client) {
                 return {
                     ...c,
                     safetyTier: tier,
-                    destructive: tier === 'destructive',
                     ...(reason ? { safetyReason: reason } : {}),
                 };
             }),

package/dist/policy/add-rule.js

@@ -0,0 +1,124 @@
+import { parseDocument, isMap, isSeq, isScalar, LineCounter } from 'yaml';
+import { parse as yamlParse } from 'yaml';
+import { loadPolicyFile } from './load.js';
+import { validateLoadedPolicy } from './validate.js';
+import fs from 'node:fs';
+export class AddRuleError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'AddRuleError';
+    }
+}
+function buildDiff(before, after) {
+    const beforeLines = before.split('\n');
+    const afterLines = after.split('\n');
+    const lines = ['--- before', '+++ after'];
+    let i = 0;
+    let j = 0;
+    while (i < beforeLines.length || j < afterLines.length) {
+        const b = beforeLines[i];
+        const a = afterLines[j];
+        if (i < beforeLines.length && j < afterLines.length && b === a) {
+            lines.push(` ${b}`);
+            i++;
+            j++;
+        }
+        else if (j < afterLines.length && (i >= beforeLines.length || b !== a)) {
+            lines.push(`+${a}`);
+            j++;
+        }
+        else {
+            lines.push(`-${b}`);
+            i++;
+        }
+    }
+    return lines.join('\n');
+}
+function isNullNode(node) {
+    return isScalar(node) && node.value === null;
+}
+export function addRuleToPolicySource(opts) {
+    const loaded = loadPolicyFile(opts.policyPath);
+    const beforeSource = loaded.source;
+    // Parse the incoming rule
+    let ruleObj;
+    try {
+        ruleObj = yamlParse(opts.ruleYaml);
+    }
+    catch (err) {
+        throw new AddRuleError(`Could not parse rule YAML: ${err.message}`, 'invalid-rule-yaml');
+    }
+    if (!ruleObj || typeof ruleObj !== 'object' || Array.isArray(ruleObj)) {
+        throw new AddRuleError('Rule YAML must be a single mapping object', 'invalid-rule-shape');
+    }
+    const ruleName = ruleObj['name'];
+    if (typeof ruleName !== 'string' || !ruleName) {
+        throw new AddRuleError('Rule must have a non-empty "name" field', 'missing-rule-name');
+    }
+    // Clone the document using source round-trip (preserves comments)
+    const clone = parseDocument(beforeSource, { keepSourceTokens: true });
+    if (!isMap(clone.contents)) {
+        throw new AddRuleError('Policy root must be a YAML mapping', 'invalid-policy-shape');
+    }
+    // Ensure automation block exists
+    let automationNode = clone.contents.get('automation', true);
+    if (!automationNode || isNullNode(automationNode)) {
+        clone.setIn(['automation'], clone.createNode({ enabled: false, rules: [] }));
+        automationNode = clone.contents.get('automation', true);
+    }
+    // Ensure automation.rules exists and is a sequence
+    const rulesNode = clone.getIn(['automation', 'rules'], true);
+    if (!rulesNode || isNullNode(rulesNode)) {
+        clone.setIn(['automation', 'rules'], clone.createNode([]));
+    }
+    else if (!isSeq(rulesNode)) {
+        throw new AddRuleError('automation.rules exists but is not a sequence; cannot append', 'invalid-rules-shape');
+    }
+    // Duplicate name check — use JS conversion for simplicity
+    const policyJs = clone.toJS({ maxAliasCount: 100 });
+    const existingRulesJs = policyJs['automation']?.['rules'];
+    const existingRulesArr = Array.isArray(existingRulesJs) ? existingRulesJs : [];
+    const duplicateIdx = existingRulesArr.findIndex((r) => r?.['name'] === ruleName);
+    if (duplicateIdx !== -1 && !opts.force) {
+        throw new AddRuleError(`Rule named "${ruleName}" already exists. Use --force to overwrite.`, 'duplicate-rule-name');
+    }
+    if (duplicateIdx !== -1 && opts.force) {
+        const rulesSeq = clone.getIn(['automation', 'rules'], true);
+        rulesSeq.items.splice(duplicateIdx, 1);
+    }
+    // Enable automation if requested
+    if (opts.enableAutomation) {
+        clone.setIn(['automation', 'enabled'], true);
+    }
+    // Append the rule
+    const ruleNode = clone.createNode(ruleObj);
+    const rulesSeq = clone.getIn(['automation', 'rules'], true);
+    rulesSeq.items.push(ruleNode);
+    const nextSource = String(clone);
+    // Validate the resulting policy
+    const reLC = new LineCounter();
+    const reDoc = parseDocument(nextSource, { lineCounter: reLC, keepSourceTokens: true });
+    const validation = validateLoadedPolicy({
+        path: opts.policyPath,
+        source: nextSource,
+        doc: reDoc,
+        lineCounter: reLC,
+        data: reDoc.toJS({ maxAliasCount: 100 }),
+    });
+    if (!validation.valid) {
+        const msgs = validation.errors.map((e) => `  line ${e.line}: ${e.message}`).join('\n');
+        throw new AddRuleError(`Policy would be invalid after adding the rule:\n${msgs}`, 'validation-failed');
+    }
+    const diff = buildDiff(beforeSource, nextSource);
+    return { ruleName, diff, nextSource };
+}
+export function addRuleToPolicyFile(opts) {
+    const result = addRuleToPolicySource(opts);
+    if (!opts.dryRun) {
+        fs.writeFileSync(opts.policyPath, result.nextSource, 'utf8');
+        return { ...result, written: true };
+    }
+    return { ...result, written: false };
+}