@onpeek/nuvio 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 wiktorekdev
+Copyright (c) 2026 onpeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+<div align="center">
+
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/nuvio-wordmark-dark.png" />
+    <source media="(prefers-color-scheme: light)" srcset="assets/nuvio-wordmark-light.png" />
+    <img src="assets/nuvio-wordmark-light.png" alt="Nuvio CLI" width="400" />
+  </picture>
+
+  <p>
+    <strong>Manage your Nuvio account from a terminal or coding agent.</strong><br />
+    Profiles · Addons · Plugins · Settings · Collections · Library · Providers · Trackers
+  </p>
+
+  <p>
+    <a href="https://github.com/onpeek/nuvio/actions/workflows/ci.yml"><img src="https://github.com/onpeek/nuvio/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+    <img src="https://img.shields.io/badge/node-%3E%3D20-339933?style=flat&logo=node.js&logoColor=white" alt="Node.js 20 or newer" />
+    <a href="LICENSE"><img src="https://img.shields.io/github/license/onpeek/nuvio?style=flat&color=6366f1" alt="MIT license" /></a>
+  </p>
+
+  <p><em>Unofficial community project. Not affiliated with or endorsed by Nuvio.</em></p>
+
+</div>
+
+---
+
+## Features
+
+- 64 commands, discovered on demand with <code>nuvio commands</code> and <code>nuvio help</code>
+- Manage profiles, addons, plugins, settings, collections, library, watch history, providers, and trackers
+- Preview changes, keep snapshots, and undo reversible writes
+- Confirm irreversible operations with a short-lived token
+- Save large results to a file instead of filling agent context
+- Requires Node.js 20 or newer.
+
+## Install
+
+```bash
+git clone https://github.com/onpeek/nuvio.git
+cd nuvio
+npm ci
+npm run build
+npm link
+npx skills add onpeek/nuvio --skill nuvio
+```
+
+Set <code>NUVIO_EMAIL</code> and <code>NUVIO_PASSWORD</code>, or set
+<code>NUVIO_REFRESH_TOKEN</code>. The CLI stores its session locally. Use
+<code>NUVIO_BACKEND_URL</code> for a self-hosted backend.
+
+## Use
+
+```bash
+nuvio commands profile
+nuvio help update-settings
+nuvio list-profiles
+nuvio list-addons --profile-id 1
+```
+
+Pass simple values as flags. For arrays, objects, PINs, or provider keys, use
+<code>--input FILE</code> or <code>--input -</code> with JSON. Keep credentials
+and secrets out of shell arguments.
+
+Preview a change, then apply it:
+
+```bash
+nuvio update-settings --input settings-edit.json --dry-run
+nuvio update-settings --input settings-edit.json
+nuvio undo --snapshot-id SNAPSHOT_ID
+```
+
+Normal stdout is capped at 12,000 bytes. Use <code>--output FILE</code> to save
+a full result. See [SECURITY.md](SECURITY.md) for local data and confirmation details.
+
+## Development
+
+```bash
+npm ci
+npm run typecheck
+npm run lint
+npm test
+```
+
+[MIT](LICENSE)

package/dist/cli/confirmation.js

@@ -0,0 +1,45 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const TTL_MS = 5 * 60_000;
+function fingerprint(command, args) {
+    const clean = Object.fromEntries(Object.entries(args)
+        .filter(([key]) => !['confirmation_token', 'confirm', 'dry_run'].includes(key))
+        .sort(([a], [b]) => a.localeCompare(b)));
+    return createHash('sha256')
+        .update(JSON.stringify({ command, args: clean }))
+        .digest('hex');
+}
+function pendingPath(cfg, token) {
+    const id = createHash('sha256').update(token).digest('hex');
+    return join(dirname(cfg.sessionFile), 'confirm-' + id + '.json');
+}
+export function prepareConfirmation(cfg, command, args) {
+    const token = randomBytes(24).toString('base64url');
+    const expires = Date.now() + TTL_MS;
+    const file = pendingPath(cfg, token);
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    writeFileSync(file, JSON.stringify({
+        command,
+        fingerprint: fingerprint(command, args),
+        expires_at: expires,
+    }), { flag: 'wx', mode: 0o600 });
+    return { confirmation_token: token, expires_at: new Date(expires).toISOString() };
+}
+export function verifyConfirmation(cfg, command, args, token) {
+    if (typeof token !== 'string' || token.length < 20)
+        throw new Error('Missing confirmation token. Run the command once without it to preview.');
+    const file = pendingPath(cfg, token);
+    let pending;
+    try {
+        pending = JSON.parse(readFileSync(file, 'utf8'));
+        unlinkSync(file);
+    }
+    catch {
+        throw new Error('Confirmation token not found or already used. Preview the command again.');
+    }
+    if (pending.command !== command || pending.fingerprint !== fingerprint(command, args))
+        throw new Error('Confirmation token does not match the command arguments.');
+    if (pending.expires_at <= Date.now())
+        throw new Error('Confirmation token expired. Preview the command again.');
+}

package/dist/cli/registry.js

@@ -0,0 +1,14 @@
+export class CommandRegistry {
+    commands = new Map();
+    register(command) {
+        if (this.commands.has(command.name))
+            throw new Error(`Duplicate command: ${command.name}`);
+        this.commands.set(command.name, command);
+    }
+    get(name) {
+        return this.commands.get(name);
+    }
+    list() {
+        return [...this.commands.values()];
+    }
+}

package/dist/commands/account.js

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { defineMutation, defineRead } from './helpers.js';
+import * as account from '../nuvio/ops/account.js';
+export function registerAccountCommands(registry, client, cfg) {
+    defineRead(registry, client, cfg, {
+        name: 'nuvio_whoami',
+        title: 'Get current account',
+        description: 'Return the signed-in Nuvio account and the backend URL.',
+        risk: 'read',
+        schema: {},
+        handler: async () => ({ backend_url: client.backendUrl, account: await account.getAccount(client) }),
+    });
+    defineRead(registry, client, cfg, {
+        name: 'nuvio_sync_overview',
+        title: 'Get data overview',
+        description: 'Summary counts of profiles, addons, plugins, library items, watch progress and history.',
+        risk: 'read',
+        schema: {},
+        handler: () => account.getSyncOverview(client),
+    });
+    defineRead(registry, client, cfg, {
+        name: 'nuvio_list_avatars',
+        title: 'List avatars',
+        description: 'List avatar catalog ids available for profile avatars.',
+        risk: 'read',
+        schema: {},
+        handler: () => account.listAvatars(client),
+    });
+    defineRead(registry, client, cfg, {
+        name: 'nuvio_health',
+        title: 'Backend health check',
+        description: 'Ping the Nuvio backend database.',
+        risk: 'read',
+        schema: {},
+        handler: () => account.health(client),
+    });
+    defineRead(registry, client, cfg, {
+        name: 'nuvio_export_backup',
+        title: 'Export account backup',
+        description: 'Export account data as a JSON backup (profiles, addons, plugins, library, progress, history, settings, ' +
+            'collections). Credentials and tokens are excluded server-side. With no scope this is a full backup; pass ' +
+            'scope/profile_ids/platforms to narrow it.',
+        risk: 'read',
+        schema: {
+            scope: z.array(z.string()).optional().describe('Sections to include (e.g. settings, addons)'),
+            profile_ids: z.array(z.number().int().min(1).max(6)).optional().describe('Only these profiles'),
+            platforms: z.array(z.string()).optional().describe('Only these setting platforms'),
+        },
+        handler: (args) => account.exportBackup(client, {
+            scope: args.scope,
+            profile_ids: args.profile_ids,
+            platforms: args.platforms,
+        }),
+    });
+    defineMutation(registry, client, cfg, {
+        name: 'nuvio_restore_backup',
+        title: 'Restore account backup',
+        description: 'Replace account data from a backup produced by nuvio_export_backup. Only available on self-hosted backends that expose sync_restore_account_backup. High risk: overwrites profiles/addons/library/settings.',
+        risk: 'destructive',
+        resource: { kind: 'profiles' },
+        reversible: false,
+        note: 'restore replaces wide account state; revert is not attempted',
+        schema: { backup: z.record(z.string(), z.unknown()).describe('Backup JSON from nuvio_export_backup') },
+        handler: (args, ctx) => account.restoreBackup(client, args.backup, ctx.apply),
+    });
+}

package/dist/commands/addons.js

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+import { fetchJsonFromPublicUrl } from '../nuvio/safe-fetch.js';
+import { defineMutation, defineRead } from './helpers.js';
+import { addonAddShape, addonRemoveShape, addonReorderShape, addonUpdateShape, assertTarget, profile, } from '../nuvio/schemas.js';
+import * as addons from '../nuvio/ops/addons.js';
+export function registerAddonCommands(registry, client, cfg) {
+    const originId = cfg.originClientId;
+    defineRead(registry, client, cfg, {
+        name: 'nuvio_list_addons',
+        title: 'List addons',
+        description: 'List the addons installed on a profile (url, name, enabled, sort_order).',
+        risk: 'read',
+        schema: { profile_id: profile },
+        handler: (args) => addons.listAddons(client, args.profile_id),
+    });
+    defineRead(registry, client, cfg, {
+        name: 'nuvio_inspect_addon',
+        title: 'Inspect an addon manifest',
+        description: 'Fetch and summarise a Stremio/Nuvio addon manifest (name, version, resources, catalog types) before installing.',
+        risk: 'read',
+        schema: { url: z.url() },
+        handler: async (args) => {
+            const manifest = (await fetchJsonFromPublicUrl(args.url));
+            return {
+                id: manifest.id,
+                name: manifest.name,
+                version: manifest.version,
+                description: manifest.description,
+                types: manifest.types,
+                resources: manifest.resources,
+                catalogs: Array.isArray(manifest.catalogs)
+                    ? manifest.catalogs.map((c) => ({
+                        type: c.type,
+                        id: c.id,
+                        name: c.name,
+                    }))
+                    : [],
+            };
+        },
+    });
+    defineMutation(registry, client, cfg, {
+        name: 'nuvio_add_addon',
+        title: 'Install an addon',
+        description: 'Install an addon on a profile by manifest URL. The current addon list is read and preserved; only the new addon is appended.',
+        risk: 'write',
+        resource: (args) => ({ kind: 'addons', profile_id: args.profile_id }),
+        schema: addonAddShape,
+        handler: (args, ctx) => addons.addAddon(client, args.profile_id, args, originId, ctx.apply),
+    });
+    defineMutation(registry, client, cfg, {
+        name: 'nuvio_update_addon',
+        title: 'Update an addon',
+        description: 'Change an addon name, enabled flag or sort order. Identify it by url or table id.',
+        risk: 'write',
+        resource: (args) => ({ kind: 'addons', profile_id: args.profile_id }),
+        schema: addonUpdateShape,
+        handler: (args, ctx) => {
+            assertTarget('nuvio_update_addon', args);
+            const { profile_id, url, id, ...changes } = args;
+            return addons.updateAddon(client, profile_id, { url, id }, changes, originId, ctx.apply);
+        },
+    });
+    defineMutation(registry, client, cfg, {
+        name: 'nuvio_reorder_addons',
+        title: 'Reorder addons',
+        description: "Set the display order of a profile's addons. Provide every installed addon URL exactly once, in the desired order.",
+        risk: 'write',
+        resource: (args) => ({ kind: 'addons', profile_id: args.profile_id }),
+        schema: addonReorderShape,
+        handler: (args, ctx) => addons.reorderAddons(client, args.profile_id, args.ordered_urls, originId, ctx.apply),
+    });
+    defineMutation(registry, client, cfg, {
+        name: 'nuvio_remove_addon',
+        title: 'Remove an addon',
+        description: 'Uninstall one addon from a profile.',
+        risk: 'destructive',
+        resource: (args) => ({ kind: 'addons', profile_id: args.profile_id }),
+        schema: addonRemoveShape,
+        handler: (args, ctx) => {
+            assertTarget('nuvio_remove_addon', args);
+            return addons.removeAddon(client, args.profile_id, { url: args.url, id: args.id }, originId, ctx.apply);
+        },
+    });
+}

package/dist/commands/collections.js

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+import { defineMutation, defineRead } from './helpers.js';
+import * as collections from '../nuvio/ops/collections.js';
+const sourceSchema = z.object({
+    addonId: z.string(),
+    type: z.string(),
+    catalogId: z.string(),
+});
+const folderSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    coverImageUrl: z.string().optional(),
+    coverEmoji: z.string().optional(),
+    tileShape: z.enum(['POSTER', 'LANDSCAPE', 'SQUARE']).optional(),
+    hideTitle: z.boolean().optional(),
+    catalogSources: z.array(sourceSchema).optional(),
+});
+const collectionSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    backdropImageUrl: z.string().optional(),
+    pinToTop: z.boolean().optional(),
+    viewMode: z.enum(['TABBED_GRID', 'ROWS', 'FOLLOW_LAYOUT']).optional(),
+    showAllTab: z.boolean().optional(),
+    folders: z.array(folderSchema).optional(),
+});
+const normalizeFolder = (folder) => ({ ...folder, catalogSources: folder.catalogSources ?? [] });
+const normalizeCollection = (collection) => ({
+    ...collection,
+    folders: (collection.folders ?? []).map(normalizeFolder),
+});
+export function registerCollectionCommands(registry, client, cfg) {
+    const originId = cfg.originClientId;
+    const profile = z.number().int().min(1).max(6).default(1);
+    const resource = (args) => ({ kind: 'collections', profile_id: args.profile_id });
+    defineRead(registry, client, cfg, {
+        name: 'nuvio_list_collections',
+        title: 'List collections',
+        description: "List a profile's custom collections (titles, view mode, folders, catalog sources).",
+        risk: 'read',
+        schema: { profile_id: profile },
+        handler: (args) => collections.getCollections(client, args.profile_id),
+    });
+    defineMutation(registry, client, cfg, {
+        name: 'nuvio_create_collection',
+        title: 'Create a collection',
+        description: 'Add a new collection to a profile.',
+        risk: 'write',
+        resource,
+        schema: { profile_id: profile, collection: collectionSchema },
+        handler: (args, ctx) => collections.createCollection(client, args.profile_id, normalizeCollection(args.collection), originId, ctx.apply),
+    });
+    defineMutation(registry, client, cfg, {
+        name: 'nuvio_update_collection',
+        title: 'Update a collection',
+        description: "Edit a collection's title, view mode, pin state or replace its folder list.",
+        risk: 'write',
+        resource,
+        schema: {
+            profile_id: profile,
+            collection_id: z.string(),
+            changes: collectionSchema.omit({ id: true }).partial(),
+        },
+        handler: (args, ctx) => {
+            const { folders, ...rest } = args.changes;
+            const changes = folders ? { ...rest, folders: folders.map(normalizeFolder) } : rest;
+            return collections.updateCollection(client, args.profile_id, args.collection_id, changes, originId, ctx.apply);
+        },
+    });
+    defineMutation(registry, client, cfg, {
+        name: 'nuvio_delete_collection',
+        title: 'Delete a collection',
+        description: 'Remove a collection from a profile.',
+        risk: 'destructive',
+        resource,
+        schema: { profile_id: profile, collection_id: z.string() },
+        handler: (args, ctx) => collections.deleteCollection(client, args.profile_id, args.collection_id, originId, ctx.apply),
+    });
+    defineMutation(registry, client, cfg, {
+        name: 'nuvio_add_collection_folder',
+        title: 'Add a folder to a collection',
+        description: 'Append a folder (with catalog sources) to an existing collection.',
+        risk: 'write',
+        resource,
+        schema: { profile_id: profile, collection_id: z.string(), folder: folderSchema },
+        handler: (args, ctx) => collections.addFolder(client, args.profile_id, args.collection_id, normalizeFolder(args.folder), originId, ctx.apply),
+    });
+    defineMutation(registry, client, cfg, {
+        name: 'nuvio_update_collection_folder',
+        title: 'Update a collection folder',
+        description: "Edit a folder's title, cover, tile shape or catalog sources.",
+        risk: 'write',
+        resource,
+        schema: {
+            profile_id: profile,
+            collection_id: z.string(),
+            folder_id: z.string(),
+            changes: folderSchema.omit({ id: true }).partial(),
+        },
+        handler: (args, ctx) => collections.updateFolder(client, args.profile_id, args.collection_id, args.folder_id, args.changes, originId, ctx.apply),
+    });
+    defineMutation(registry, client, cfg, {
+        name: 'nuvio_remove_collection_folder',
+        title: 'Remove a collection folder',
+        description: 'Remove a folder from a collection.',
+        risk: 'destructive',
+        resource,
+        schema: { profile_id: profile, collection_id: z.string(), folder_id: z.string() },
+        handler: (args, ctx) => collections.removeFolder(client, args.profile_id, args.collection_id, args.folder_id, originId, ctx.apply),
+    });
+    defineMutation(registry, client, cfg, {
+        name: 'nuvio_reorder_collections',
+        title: 'Reorder collections',
+        description: 'Set collection order. Provide every collection id exactly once, in the desired order.',
+        risk: 'write',
+        resource,
+        schema: { profile_id: profile, ordered_ids: z.array(z.string()).min(1) },
+        handler: (args, ctx) => collections.reorderCollections(client, args.profile_id, args.ordered_ids, originId, ctx.apply),
+    });
+    defineMutation(registry, client, cfg, {
+        name: 'nuvio_duplicate_collection',
+        title: 'Duplicate a collection',
+        description: 'Copy a collection (including folders and catalog sources) under a new id, placed right after the source.',
+        risk: 'write',
+        resource,
+        schema: {
+            profile_id: profile,
+            collection_id: z.string(),
+            new_id: z.string(),
+            new_title: z.string().optional(),
+        },
+        handler: (args, ctx) => collections.duplicateCollection(client, args.profile_id, args.collection_id, args.new_id, args.new_title, originId, ctx.apply),
+    });
+    defineMutation(registry, client, cfg, {
+        name: 'nuvio_reorder_collection_folders',
+        title: 'Reorder folders in a collection',
+        description: 'Set folder order. Provide every folder id in the collection exactly once, in the desired order.',
+        risk: 'write',
+        resource,
+        schema: {
+            profile_id: profile,
+            collection_id: z.string(),
+            ordered_folder_ids: z.array(z.string()).min(1),
+        },
+        handler: (args, ctx) => collections.reorderCollectionFolders(client, args.profile_id, args.collection_id, args.ordered_folder_ids, originId, ctx.apply),
+    });
+}

package/dist/commands/helpers.js

@@ -0,0 +1,186 @@
+import { appendFileSync, mkdirSync, renameSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { z } from 'zod';
+import { prepareConfirmation, verifyConfirmation } from '../cli/confirmation.js';
+import { withCallCache } from '../nuvio/call-context.js';
+import { capture, captureComposite, readResource, removeSnapshot, restoreResource, } from '../nuvio/snapshots.js';
+import { applyPlan } from '../nuvio/ops/plan.js';
+import { maskDeep } from '../mask.js';
+const AUDIT_MAX_BYTES = 5 * 1024 * 1024;
+function audit(cfg, entry) {
+    try {
+        mkdirSync(dirname(cfg.auditFile), { recursive: true, mode: 0o700 });
+        try {
+            if (statSync(cfg.auditFile).size > AUDIT_MAX_BYTES)
+                renameSync(cfg.auditFile, cfg.auditFile + '.1');
+        }
+        catch {
+            /* first write */
+        }
+        appendFileSync(cfg.auditFile, JSON.stringify({ ts: new Date().toISOString(), ...maskDeep(entry) }) +
+            '\n', { mode: 0o600 });
+    }
+    catch {
+        /* best effort */
+    }
+}
+function ctx(client, cfg, apply, dryRun, before) {
+    return { client, config: cfg, apply, dryRun, before, read: (ref) => readResource(client, ref) };
+}
+export function defineRead(registry, client, cfg, spec) {
+    registry.register({
+        name: spec.name,
+        title: spec.title,
+        description: spec.description,
+        risk: spec.risk,
+        schema: z.object(spec.schema),
+        run: async (raw) => withCallCache(async () => maskDeep(await spec.handler(raw, ctx(client, cfg, true, false)))),
+    });
+}
+export function defineMutation(registry, client, cfg, spec) {
+    const reversible = spec.reversible ?? true;
+    const schema = z.object({
+        ...spec.schema,
+        dry_run: z.boolean().optional(),
+        ...(!reversible
+            ? { confirmation_token: z.string().optional() }
+            : spec.risk === 'destructive'
+                ? { confirm: z.boolean().optional() }
+                : {}),
+    });
+    registry.register({
+        name: spec.name,
+        title: spec.title,
+        description: spec.description,
+        risk: spec.risk,
+        schema,
+        run: async (raw) => withCallCache(async () => {
+            const args = raw;
+            const dryRun = raw.dry_run === true;
+            const apply = !dryRun &&
+                (reversible
+                    ? spec.risk !== 'destructive' || raw.confirm === true
+                    : typeof raw.confirmation_token === 'string');
+            if (apply && !reversible)
+                verifyConfirmation(cfg, spec.name, raw, raw.confirmation_token);
+            const resource = typeof spec.resource === 'function' ? spec.resource(args) : spec.resource;
+            let before;
+            let snapshot;
+            if (apply && reversible && !cfg.disableSnapshots) {
+                before = await readResource(client, resource);
+                snapshot = capture(cfg, client, {
+                    tool: spec.name,
+                    resource,
+                    before,
+                    reversible: true,
+                    note: spec.note,
+                    scope: spec.scope?.(args),
+                });
+            }
+            let result;
+            try {
+                result = await spec.handler(args, ctx(client, cfg, apply, dryRun, before));
+            }
+            catch (error) {
+                if (snapshot)
+                    removeSnapshot(cfg, snapshot.id);
+                throw error;
+            }
+            if (snapshot && !(result.applied && result.changed))
+                removeSnapshot(cfg, snapshot.id);
+            if (result.applied && result.changed)
+                audit(cfg, { command: spec.name, resource, args, diff: result.diff, snapshot: snapshot?.id });
+            const confirmation = !reversible && !apply && !dryRun && result.changed
+                ? prepareConfirmation(cfg, spec.name, raw)
+                : undefined;
+            return {
+                status: !result.changed ? 'unchanged' : result.applied ? 'applied' : 'preview',
+                changed: result.changed,
+                diff: maskDeep(result.diff),
+                ...(snapshot && result.applied && result.changed ? { snapshot_id: snapshot.id } : {}),
+                ...(confirmation
+                    ? {
+                        warning: 'Irreversible. Run again with --confirmation-token TOKEN and the same arguments to apply.',
+                        ...confirmation,
+                    }
+                    : {}),
+                ...(spec.risk === 'destructive' && !apply && !dryRun
+                    ? { hint: 'Run again with --confirm to apply.' }
+                    : {}),
+            };
+        }),
+    });
+}
+export function defineLocalMutation(registry, client, cfg, spec) {
+    registry.register({
+        name: spec.name,
+        title: spec.title,
+        description: spec.description,
+        risk: spec.risk,
+        schema: z.object({ ...spec.schema, dry_run: z.boolean().optional(), confirm: z.boolean().optional() }),
+        run: async (raw) => {
+            const apply = raw.confirm === true && raw.dry_run !== true;
+            const result = await spec.handler(raw, ctx(client, cfg, apply, !apply));
+            if (result.applied && result.changed)
+                audit(cfg, { command: spec.name, args: raw, diff: result.diff });
+            return {
+                status: !result.changed ? 'unchanged' : result.applied ? 'applied' : 'preview',
+                changed: result.changed,
+                diff: maskDeep(result.diff),
+            };
+        },
+    });
+}
+export function definePlanMutation(registry, client, cfg) {
+    registry.register({
+        name: 'nuvio_apply_plan',
+        title: 'Apply a plan of operations',
+        description: 'Apply supported operations together with a composite snapshot and rollback. Preview by default.',
+        risk: 'write',
+        schema: z.object({
+            operations: z
+                .array(z.object({ tool: z.string().min(1), args: z.record(z.string(), z.unknown()).default({}) }))
+                .min(1),
+            dry_run: z.boolean().optional().default(true),
+        }),
+        run: async (raw) => withCallCache(async () => {
+            const operations = raw.operations.map((op) => ({
+                ...op,
+                tool: 'nuvio_' + op.tool.replaceAll('-', '_'),
+            }));
+            const result = await applyPlan(operations, raw.dry_run !== false, {
+                client,
+                originId: cfg.originClientId,
+                snapshotsDisabled: cfg.disableSnapshots,
+                captureComposite: (entries) => cfg.disableSnapshots
+                    ? undefined
+                    : captureComposite(cfg, client, {
+                        tool: 'nuvio_apply_plan',
+                        entries,
+                        reversible: true,
+                        note: 'composite snapshot for a plan',
+                    }).id,
+                restoreEntry: async (entry) => {
+                    await restoreResource(client, cfg, entry, {
+                        id: 'nuvio_apply_plan',
+                        tool: 'nuvio_apply_plan',
+                        reversible: true,
+                    });
+                },
+            });
+            if (['applied', 'rolled_back', 'partially_applied'].includes(result.status))
+                audit(cfg, { command: 'nuvio_apply_plan', operations, result });
+            return maskDeep({
+                ...result,
+                operations: result.operations.map((op) => ({
+                    ...op,
+                    tool: op.tool.replace(/^nuvio_/, '').replaceAll('_', '-'),
+                })),
+                failed_operation: result.failed_operation && {
+                    ...result.failed_operation,
+                    tool: result.failed_operation.tool.replace(/^nuvio_/, '').replaceAll('_', '-'),
+                },
+            });
+        }),
+    });
+}