@switchbot/openapi-cli 2.7.2 → 3.1.0

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/daemon-state.js

@@ -0,0 +1,46 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+function getStateDir() {
+    return path.join(os.homedir(), '.switchbot');
+}
+function getDaemonPidFile() {
+    return path.join(getStateDir(), 'daemon.pid');
+}
+function getDaemonLogFile() {
+    return path.join(getStateDir(), 'daemon.log');
+}
+function getDaemonStateFile() {
+    return path.join(getStateDir(), 'daemon.state.json');
+}
+function getHealthzPidFile() {
+    return path.join(getStateDir(), 'healthz.pid');
+}
+export const DAEMON_PID_FILE = getDaemonPidFile();
+export const DAEMON_LOG_FILE = getDaemonLogFile();
+export const DAEMON_STATE_FILE = getDaemonStateFile();
+export const HEALTHZ_PID_FILE = getHealthzPidFile();
+function ensureStateDir() {
+    fs.mkdirSync(getStateDir(), { recursive: true, mode: 0o700 });
+}
+export function writeDaemonState(state) {
+    ensureStateDir();
+    fs.writeFileSync(getDaemonStateFile(), JSON.stringify(state, null, 2), { mode: 0o600 });
+}
+export function readDaemonState() {
+    try {
+        const raw = fs.readFileSync(getDaemonStateFile(), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function removeDaemonState() {
+    try {
+        fs.unlinkSync(getDaemonStateFile());
+    }
+    catch {
+        // best effort
+    }
+}

package/dist/lib/destructive-mode.js

@@ -0,0 +1,12 @@
+import { getActiveProfile } from './request-context.js';
+const DIRECT_DESTRUCTIVE_PROFILES = new Set(['dev', 'development']);
+export function allowsDirectDestructiveExecution(profile = getActiveProfile()) {
+    if (process.env.SWITCHBOT_ALLOW_DIRECT_DESTRUCTIVE === '1')
+        return true;
+    if (!profile)
+        return false;
+    return DIRECT_DESTRUCTIVE_PROFILES.has(profile.toLowerCase());
+}
+export function destructiveExecutionHint() {
+    return "Use 'switchbot plan save <file>' -> 'switchbot plan review <planId>' -> 'switchbot plan approve <planId>' -> 'switchbot plan execute <planId>' instead.";
+}

package/dist/lib/devices.js

@@ -101,6 +101,7 @@ export async function executeCommand(deviceId, cmd, parameter, commandType, clie
         parameter,
         commandType,
         dryRun: isDryRun(),
+        ...(options?.planId ? { planId: options.planId } : {}),
     };
     // Wrap in idempotency cache if key is provided
     const execute = async () => {
@@ -272,7 +273,6 @@ export async function describeDevice(deviceId, options = {}, client) {
                 return {
                     ...c,
                     safetyTier: tier,
-                    destructive: tier === 'destructive',
                     ...(reason ? { safetyReason: reason } : {}),
                 };
             }),

package/dist/lib/plan-store.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+export const PLANS_DIR = path.join(os.homedir(), '.switchbot', 'plans');
+function ensurePlansDir() {
+    fs.mkdirSync(PLANS_DIR, { recursive: true, mode: 0o700 });
+}
+function planPath(planId) {
+    return path.join(PLANS_DIR, `${planId}.json`);
+}
+const UUID_V4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function assertValidPlanId(planId) {
+    if (!UUID_V4_RE.test(planId)) {
+        throw new Error(`invalid planId: ${planId}`);
+    }
+}
+export function savePlanRecord(plan) {
+    ensurePlansDir();
+    const record = {
+        planId: randomUUID(),
+        createdAt: new Date().toISOString(),
+        status: 'pending',
+        plan,
+    };
+    fs.writeFileSync(planPath(record.planId), JSON.stringify(record, null, 2), { mode: 0o600 });
+    return record;
+}
+export function loadPlanRecord(planId) {
+    assertValidPlanId(planId);
+    try {
+        const raw = fs.readFileSync(planPath(planId), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function updatePlanRecord(planId, updates) {
+    assertValidPlanId(planId);
+    const record = loadPlanRecord(planId);
+    if (!record)
+        throw new Error(`Plan ${planId} not found in ${PLANS_DIR}`);
+    const updated = { ...record, ...updates };
+    fs.writeFileSync(planPath(planId), JSON.stringify(updated, null, 2), { mode: 0o600 });
+    return updated;
+}
+export function listPlanRecords() {
+    try {
+        if (!fs.existsSync(PLANS_DIR))
+            return [];
+        return fs
+            .readdirSync(PLANS_DIR)
+            .filter((f) => f.endsWith('.json'))
+            .flatMap((f) => {
+            try {
+                return [JSON.parse(fs.readFileSync(path.join(PLANS_DIR, f), 'utf-8'))];
+            }
+            catch {
+                return [];
+            }
+        })
+            .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    }
+    catch {
+        return [];
+    }
+}

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 };
+}

package/dist/policy/diff.js

@@ -0,0 +1,91 @@
+export const MAX_POLICY_DIFF_CHANGES = 200;
+function isPlainObject(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+function collectPolicyDiff(left, right, at, out, limit) {
+    if (out.length >= limit)
+        return;
+    if (Array.isArray(left) && Array.isArray(right)) {
+        const maxLen = Math.max(left.length, right.length);
+        for (let i = 0; i < maxLen; i++) {
+            if (out.length >= limit)
+                return;
+            const path = `${at}[${i}]`;
+            if (i >= left.length) {
+                out.push({ path, kind: 'added', after: right[i] });
+            }
+            else if (i >= right.length) {
+                out.push({ path, kind: 'removed', before: left[i] });
+            }
+            else {
+                collectPolicyDiff(left[i], right[i], path, out, limit);
+            }
+        }
+        return;
+    }
+    if (isPlainObject(left) && isPlainObject(right)) {
+        const keys = new Set([...Object.keys(left), ...Object.keys(right)]);
+        for (const key of [...keys].sort()) {
+            if (out.length >= limit)
+                return;
+            const path = at === '$' ? `$.${key}` : `${at}.${key}`;
+            const leftHas = Object.prototype.hasOwnProperty.call(left, key);
+            const rightHas = Object.prototype.hasOwnProperty.call(right, key);
+            if (!leftHas && rightHas) {
+                out.push({ path, kind: 'added', after: right[key] });
+            }
+            else if (leftHas && !rightHas) {
+                out.push({ path, kind: 'removed', before: left[key] });
+            }
+            else {
+                collectPolicyDiff(left[key], right[key], path, out, limit);
+            }
+        }
+        return;
+    }
+    if (!Object.is(left, right)) {
+        out.push({ path: at, kind: 'changed', before: left, after: right });
+    }
+}
+function buildLineDiff(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');
+}
+export function diffPolicyValues(leftDoc, rightDoc, leftSource, rightSource, maxChanges = MAX_POLICY_DIFF_CHANGES) {
+    const changes = [];
+    collectPolicyDiff(leftDoc, rightDoc, '$', changes, maxChanges);
+    const equal = changes.length === 0;
+    return {
+        equal,
+        changeCount: changes.length,
+        truncated: changes.length >= maxChanges,
+        stats: {
+            added: changes.filter((c) => c.kind === 'added').length,
+            removed: changes.filter((c) => c.kind === 'removed').length,
+            changed: changes.filter((c) => c.kind === 'changed').length,
+        },
+        changes,
+        diff: buildLineDiff(leftSource, rightSource),
+    };
+}

package/dist/policy/examples/policy.example.yaml

@@ -0,0 +1,99 @@
+# ============================================================================
+#  SwitchBot policy — example
+# ============================================================================
+#  Copy this file to your user config directory and edit it:
+#
+#    mkdir -p ~/.switchbot
+#    cp policy.example.yaml ~/.switchbot/policy.yaml
+#
+#  Every section is OPTIONAL. If a field isn't set, the CLI/agent layer falls back to
+#  a safe default (documented next to each field).
+#
+#  Agents read this file before every session. They never write to it
+#  without showing you the diff and asking first.
+# ============================================================================
+
+# Schema version. Do not remove this line — the skill uses it to detect
+# breaking changes and migrate your file when a newer schema ships.
+version: "0.2"
+
+# ----------------------------------------------------------------------------
+# aliases  —  friendly names the agent can resolve to real devices
+# ----------------------------------------------------------------------------
+# The #1 reason to have a policy file. Without aliases, the agent has to
+# guess which device you mean when you say "the bedroom light", and it can
+# guess wrong if two devices have similar names.
+#
+# Get each deviceId from:
+#   switchbot devices list --format=tsv
+#
+# The format is:  "what the user says": "<deviceId>"
+# Quote the key if it contains spaces or non-ASCII characters.
+aliases:
+  # "living room light": "01-202407090924-26354212"
+  # "bedroom AC":        "02-202502111234-85411230"
+  # "front door lock":   "03-202501201700-99887766"
+  # "kitchen plug":      "04-202503081500-55443322"
+
+# ----------------------------------------------------------------------------
+# confirmations  —  which actions require explicit user approval
+# ----------------------------------------------------------------------------
+# The skill already refuses destructive actions (locks, deletions) by
+# default. Use this section to adjust the defaults for your account.
+#
+# always_confirm: extra actions that need confirmation even though they
+#                 wouldn't by default (e.g. you never want the agent to
+#                 turn on the AC without asking).
+# never_confirm:  actions that normally confirm but you trust (NEVER add
+#                 destructive actions here — the skill will reject that).
+confirmations:
+  always_confirm:
+    # - "setTargetTemperature"
+    # - "setThermostatMode"
+
+  never_confirm:
+    # - "turnOn"
+    # - "turnOff"
+
+# ----------------------------------------------------------------------------
+# quiet_hours  —  during these hours, every mutation requires confirmation
+# ----------------------------------------------------------------------------
+# Times are 24-hour, local system time. If omitted, no quiet hours apply.
+quiet_hours:
+  # start: "22:00"
+  # end:   "08:00"
+
+# ----------------------------------------------------------------------------
+# audit  —  where to log every action the agent takes
+# ----------------------------------------------------------------------------
+# The skill ALWAYS logs mutations and destructive actions. This section
+# controls where the log goes and how long it's kept.
+audit:
+  # Path for the audit log. "~" is expanded. JSON Lines format.
+  log_path: "~/.switchbot/audit.log"
+
+  # How long to keep log lines. "never" disables rotation. Accepts units:
+  # d (days), w (weeks), m (months). Default: "90d".
+  retention: "90d"
+
+# ----------------------------------------------------------------------------
+# automation  —  Phase 4 (rule engine). Leave `enabled: false` for now.
+# ----------------------------------------------------------------------------
+# The rule engine ships in Phase 4. This section is reserved so the schema
+# validates today; if you set `enabled: true` before Phase 4 lands, the
+# skill will warn you and ignore it.
+automation:
+  enabled: false
+  # rules: []
+
+# ----------------------------------------------------------------------------
+# cli  —  optional CLI-level overrides
+# ----------------------------------------------------------------------------
+cli:
+  # Which profile to use if you have multiple SwitchBot accounts. The CLI
+  # supports `switchbot --profile <name>`. Default: "default".
+  profile: "default"
+
+  # Device cache TTL. The skill refreshes the cache when it's older than
+  # this. Defaults to the CLI's own default (typically 5 minutes).
+  # cache_ttl: "5m"

package/dist/policy/format.js

@@ -0,0 +1,57 @@
+import chalk, { Chalk } from 'chalk';
+const noColorChalk = new Chalk({ level: 0 });
+function colorize(enabled) {
+    return enabled ? chalk : noColorChalk;
+}
+function snippet(source, line, col, length, c) {
+    const lines = source.split(/\r?\n/);
+    if (line < 1 || line > lines.length)
+        return '';
+    const lineText = lines[line - 1];
+    const gutter = `  ${line} | `;
+    const pad = ' '.repeat(gutter.length);
+    const caretStart = Math.max(0, col - 1);
+    const caretLen = Math.max(1, length);
+    const caret = `${' '.repeat(caretStart)}${c.red('^'.repeat(caretLen))}`;
+    return `${c.dim(gutter)}${lineText}\n${c.dim(pad)}${caret}`;
+}
+function estimateTokenLength(source, line, col) {
+    const lines = source.split(/\r?\n/);
+    if (line < 1 || line > lines.length)
+        return 1;
+    const lineText = lines[line - 1];
+    const start = Math.max(0, col - 1);
+    if (start >= lineText.length)
+        return 1;
+    const rest = lineText.slice(start);
+    const quoted = rest.match(/^(['"]).*?\1/);
+    if (quoted)
+        return quoted[0].length;
+    const token = rest.match(/^[^\s,\[\]{}]+/);
+    return token ? token[0].length : 1;
+}
+function formatError(err, policyPath, source, opts) {
+    const c = colorize(opts.color ?? true);
+    const loc = err.line !== undefined && err.col !== undefined ? `${err.line}:${err.col}` : '(unknown)';
+    const header = `${c.cyan(policyPath)}:${c.yellow(loc)}`;
+    const body = [`${c.red.bold('error')}: ${err.message}`];
+    if (err.line !== undefined && err.col !== undefined && !opts.noSnippet) {
+        const len = estimateTokenLength(source, err.line, err.col);
+        const snip = snippet(source, err.line, err.col, len, c);
+        if (snip)
+            body.unshift(snip);
+    }
+    if (err.hint)
+        body.push(`${c.green.bold('hint')}:  ${err.hint}`);
+    return [header, ...body].join('\n');
+}
+export function formatValidationResult(result, source, opts = {}) {
+    const c = colorize(opts.color ?? true);
+    if (result.valid) {
+        return `${c.green.bold('✓')} ${result.policyPath} is valid (schema v${result.schemaVersion})`;
+    }
+    const blocks = result.errors.map((e) => formatError(e, result.policyPath, source, opts));
+    const count = result.errors.length;
+    const footer = `${c.red.bold(`✗ ${count} ${count === 1 ? 'error' : 'errors'}`)} in ${result.policyPath} (schema v${result.schemaVersion})`;
+    return [...blocks, '', footer].join('\n\n').replace(/\n{3,}/g, '\n\n');
+}

package/dist/policy/load.js

@@ -0,0 +1,61 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { parseDocument, LineCounter } from 'yaml';
+export const DEFAULT_POLICY_PATH = join(homedir(), '.config', 'openclaw', 'switchbot', 'policy.yaml');
+export function resolvePolicyPath(options = {}) {
+    const { flag, env = process.env } = options;
+    if (flag && flag.trim().length > 0)
+        return resolve(flag);
+    const fromEnv = env.SWITCHBOT_POLICY_PATH;
+    if (fromEnv && fromEnv.trim().length > 0)
+        return resolve(fromEnv);
+    return DEFAULT_POLICY_PATH;
+}
+export class PolicyFileNotFoundError extends Error {
+    policyPath;
+    constructor(policyPath) {
+        super(`policy file not found: ${policyPath}`);
+        this.policyPath = policyPath;
+        this.name = 'PolicyFileNotFoundError';
+    }
+}
+export class PolicyYamlParseError extends Error {
+    policyPath;
+    yamlErrors;
+    constructor(message, policyPath, yamlErrors) {
+        super(message);
+        this.policyPath = policyPath;
+        this.yamlErrors = yamlErrors;
+        this.name = 'PolicyYamlParseError';
+    }
+}
+export function loadPolicyFile(policyPath) {
+    let source;
+    try {
+        source = readFileSync(policyPath, 'utf-8');
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'ENOENT')
+            throw new PolicyFileNotFoundError(policyPath);
+        throw err;
+    }
+    const lineCounter = new LineCounter();
+    const doc = parseDocument(source, { lineCounter, keepSourceTokens: true });
+    if (doc.errors.length > 0) {
+        const yamlErrors = doc.errors.map((e) => {
+            const pos = e.pos?.[0];
+            const loc = pos !== undefined ? lineCounter.linePos(pos) : undefined;
+            return { line: loc?.line, col: loc?.col, message: e.message };
+        });
+        throw new PolicyYamlParseError(doc.errors[0].message, policyPath, yamlErrors);
+    }
+    return {
+        path: policyPath,
+        source,
+        doc,
+        lineCounter,
+        data: doc.toJS({ maxAliasCount: 100 }),
+    };
+}

package/dist/policy/migrate.js

@@ -0,0 +1,67 @@
+import { isMap, isScalar, parseDocument, LineCounter } from 'yaml';
+import { validateLoadedPolicy } from './validate.js';
+export class PolicyMigrationError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'PolicyMigrationError';
+    }
+}
+const MIGRATION_CHAIN = [];
+function bumpVersionScalar(doc, target) {
+    if (!isMap(doc.contents)) {
+        throw new PolicyMigrationError('policy root must be a YAML mapping (got null or an array)', 'invalid-shape');
+    }
+    const pair = doc.contents.items.find((p) => isScalar(p.key) && p.key.value === 'version');
+    if (!pair || !isScalar(pair.value)) {
+        throw new PolicyMigrationError('policy has no `version` scalar to migrate; add `version: "0.2"` (or `"0.1"`) and retry', 'no-version-field');
+    }
+    pair.value.value = target;
+}
+function findPlan(from, to) {
+    const chain = [];
+    let cur = from;
+    while (cur !== to) {
+        const step = MIGRATION_CHAIN.find((p) => p.fromVersion === cur);
+        if (!step) {
+            throw new PolicyMigrationError(`no migration path from v${from} to v${to} (missing step at v${cur})`, 'no-path');
+        }
+        chain.push(step);
+        cur = step.toVersion;
+    }
+    return chain;
+}
+export function planMigration(loaded, from, to) {
+    if (from === to) {
+        const precheck = validateLoadedPolicy(loaded);
+        return { changed: false, fromVersion: from, toVersion: to, nextSource: loaded.source, precheck };
+    }
+    const plan = findPlan(from, to);
+    // Round-trip through source instead of Document.clone(): keeps comments +
+    // anchors intact, works across yaml library versions, and leaves the
+    // caller's `loaded.doc` untouched.
+    const nextLineCounter = new LineCounter();
+    const clone = parseDocument(loaded.source, {
+        lineCounter: nextLineCounter,
+        keepSourceTokens: true,
+    });
+    for (const step of plan)
+        step.migrate(clone);
+    const nextSource = String(clone);
+    // Re-parse after serialization so `doc` and `source` stay in sync for the
+    // validator's line/col mapping.
+    const reLineCounter = new LineCounter();
+    const reDoc = parseDocument(nextSource, {
+        lineCounter: reLineCounter,
+        keepSourceTokens: true,
+    });
+    const precheck = validateLoadedPolicy({
+        path: loaded.path,
+        source: nextSource,
+        doc: reDoc,
+        lineCounter: reLineCounter,
+        data: reDoc.toJS({ maxAliasCount: 100 }),
+    });
+    return { changed: true, fromVersion: from, toVersion: to, nextSource, precheck };
+}