@onpeek/nuvio 1.0.0

package/dist/commands/undo.js

@@ -0,0 +1,165 @@
+import { z } from 'zod';
+import { NuvioError } from '../nuvio/errors.js';
+import { maskDeep } from '../mask.js';
+import { defineLocalMutation, defineRead } from './helpers.js';
+import { capture, captureComposite, describe, findLastChange, findLastUndo, getSnapshot, listSnapshots, pruneSnapshots, readResource, restore, snapshotResources, } from '../nuvio/snapshots.js';
+async function captureBefore(client, cfg, tool, snapshot) {
+    if (cfg.disableSnapshots)
+        return;
+    const entries = [];
+    for (const entry of snapshotResources(snapshot)) {
+        entries.push({
+            resource: entry.resource,
+            before: await readResource(client, entry.resource),
+            // Preserve the scope so a redo can target exactly the same records.
+            scope: entry.scope,
+        });
+    }
+    if (entries.length === 0)
+        return;
+    if (entries.length === 1) {
+        capture(cfg, client, {
+            tool,
+            resource: entries[0].resource,
+            before: entries[0].before,
+            scope: entries[0].scope,
+            reversible: true,
+            note: `state before ${tool === 'nuvio_undo' ? 'undoing' : 'redoing'} ${snapshot.id}`,
+        });
+    }
+    else {
+        captureComposite(cfg, client, {
+            tool,
+            entries,
+            reversible: true,
+            note: `state before ${tool === 'nuvio_undo' ? 'undoing' : 'redoing'} ${snapshot.id}`,
+        });
+    }
+}
+function formatReport(report) {
+    return report.outcomes
+        .map((o) => {
+        const where = `${o.resource}${o.profile_id !== undefined ? ` profile ${o.profile_id}` : ''}${o.platform ? `/${o.platform}` : ''}`;
+        return `${o.ok ? '✓' : '✗'} ${where}: ${o.message}`;
+    })
+        .join('\n');
+}
+export function registerUndoCommands(registry, client, cfg) {
+    defineRead(registry, client, cfg, {
+        name: 'nuvio_list_undo',
+        title: 'List available undos',
+        description: 'List recent automatically-captured snapshots. Each can be reverted with nuvio_undo.',
+        risk: 'read',
+        schema: { limit: z.number().int().min(1).max(200).default(25) },
+        handler: (args) => {
+            const snapshots = listSnapshots(cfg, args.limit);
+            if (snapshots.length === 0)
+                return 'No snapshots recorded yet.';
+            return snapshots.map(describe).join('\n');
+        },
+    });
+    defineRead(registry, client, cfg, {
+        name: 'nuvio_inspect_snapshot',
+        title: 'Inspect a snapshot',
+        description: 'Show the captured previous state of a snapshot (secrets masked).',
+        risk: 'read',
+        annotations: { readOnlyHint: true },
+        schema: { snapshot_id: z.string() },
+        handler: (args) => {
+            const snapshot = getSnapshot(cfg, args.snapshot_id);
+            if (!snapshot)
+                throw new NuvioError(`Snapshot ${args.snapshot_id} not found.`);
+            return {
+                id: snapshot.id,
+                ts: snapshot.ts,
+                tool: snapshot.tool,
+                composite: snapshot.composite ?? false,
+                resources: snapshotResources(snapshot).map((e) => ({
+                    resource: e.resource,
+                    scope: e.scope === undefined ? undefined : maskDeep(e.scope),
+                    before: maskDeep(e.before),
+                })),
+                reversible: snapshot.reversible,
+                sensitive: snapshot.sensitive,
+                note: snapshot.note,
+            };
+        },
+    });
+    defineRead(registry, client, cfg, {
+        name: 'nuvio_undo',
+        title: 'Undo a change',
+        description: 'Revert a previous change using its snapshot (single or composite). Defaults to the most recent change. ' +
+            'Snapshots the current state first, so an undo can itself be undone.',
+        risk: 'write',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+        schema: {
+            snapshot_id: z
+                .string()
+                .optional()
+                .describe('Snapshot id from nuvio_list_undo. Omit to undo the most recent change.'),
+        },
+        handler: async (args) => {
+            const target = args.snapshot_id ? getSnapshot(cfg, args.snapshot_id) : findLastChange(cfg);
+            if (!target) {
+                throw new NuvioError(args.snapshot_id ? `Snapshot ${args.snapshot_id} not found.` : 'There is nothing to undo.');
+            }
+            if (!target.reversible) {
+                throw new NuvioError(`Snapshot ${target.id} (${target.tool}) is not reversible${target.note ? ` — ${target.note}` : ''}.`);
+            }
+            await captureBefore(client, cfg, 'nuvio_undo', target);
+            const report = await restore(client, cfg, target);
+            const suffix = cfg.disableSnapshots
+                ? ' Snapshots are disabled, so this undo cannot itself be undone.'
+                : '';
+            const failed = report.outcomes.filter((o) => !o.ok).length;
+            return (`${report.ok ? 'Reverted' : `Partially reverted (${failed} failed)`} snapshot ${target.id} (${target.tool}).` +
+                `\n${formatReport(report)}${suffix}`);
+        },
+    });
+    defineRead(registry, client, cfg, {
+        name: 'nuvio_redo',
+        title: 'Redo an undone change',
+        description: 'Re-apply the change that the most recent nuvio_undo reverted. Snapshots current state first.',
+        risk: 'write',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+        schema: {},
+        handler: async () => {
+            const target = findLastUndo(cfg);
+            if (!target)
+                throw new NuvioError('There is nothing to redo.');
+            await captureBefore(client, cfg, 'nuvio_redo', target);
+            const report = await restore(client, cfg, target);
+            const suffix = cfg.disableSnapshots ? ' Snapshot writing is disabled; this redo was not recorded.' : '';
+            const failed = report.outcomes.filter((o) => !o.ok).length;
+            return (`${report.ok ? 'Re-applied' : `Partially re-applied (${failed} failed)`} snapshot ${target.id}.` +
+                `\n${formatReport(report)}${suffix}`);
+        },
+    });
+    defineLocalMutation(registry, client, cfg, {
+        name: 'nuvio_prune_snapshots',
+        title: 'Prune snapshots',
+        description: 'Delete old snapshot files according to retention limits (age, count, total size). Local-only; defaults to dry_run.',
+        risk: 'destructive',
+        schema: {
+            older_than_days: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe('Delete snapshots older than N days (0 disables).'),
+            keep_last: z.number().int().min(0).optional().describe('Always keep the newest N snapshots.'),
+            max_total_bytes: z.number().int().min(0).optional().describe('Keep total snapshot bytes under this.'),
+        },
+        handler: async (args, ctx) => {
+            const result = pruneSnapshots(cfg, {
+                olderThanDays: args.older_than_days,
+                keepLast: args.keep_last,
+                maxCount: 0,
+                maxTotalBytes: args.max_total_bytes,
+                dryRun: !ctx.apply,
+            });
+            const diff = result.removed.map((r) => `- ${r.id} (${r.reason}, ${r.bytes} bytes)`);
+            return { changed: result.removed.length > 0, applied: ctx.apply, diff };
+        },
+    });
+}

package/dist/config.js

@@ -0,0 +1,60 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const OFFICIAL_PUBLISHABLE_KEY = 'sb_publishable_1Clq8rlTVACkdcZuqr6_AD__xUUC_EN';
+function loadEnvFiles() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // Only package-relative .env files: never the current working directory.
+    const candidates = [resolve(here, '..', '.env'), resolve(here, '..', '..', '.env')];
+    const load = process.loadEnvFile;
+    if (typeof load !== 'function')
+        return;
+    for (const file of candidates) {
+        if (!existsSync(file))
+            continue;
+        try {
+            load(file);
+        }
+        catch {
+            /* ignore malformed env files */
+        }
+    }
+}
+function bool(value, fallback) {
+    if (value === undefined || value === '')
+        return fallback;
+    return ['1', 'true', 'yes', 'on'].includes(value.trim().toLowerCase());
+}
+function int(value, fallback) {
+    const parsed = Number.parseInt(value ?? '', 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+/** Like `int`, but `0` is a valid value (used where 0 means "disabled"). */
+function nonNegativeInt(value, fallback) {
+    const parsed = Number.parseInt(value ?? '', 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+export function loadConfig() {
+    loadEnvFiles();
+    const dataDir = process.env.NUVIO_DATA_DIR?.trim() ||
+        (process.env.XDG_DATA_HOME
+            ? join(process.env.XDG_DATA_HOME, 'nuvio')
+            : join(homedir(), '.local', 'share', 'nuvio'));
+    return {
+        backendUrl: (process.env.NUVIO_BACKEND_URL ?? 'https://api.nuvio.tv').replace(/\/+$/, ''),
+        publishableKey: process.env.NUVIO_PUBLISHABLE_KEY?.trim() || OFFICIAL_PUBLISHABLE_KEY,
+        email: process.env.NUVIO_EMAIL?.trim() || undefined,
+        password: process.env.NUVIO_PASSWORD || undefined,
+        refreshToken: process.env.NUVIO_REFRESH_TOKEN?.trim() || undefined,
+        originClientId: process.env.NUVIO_ORIGIN_CLIENT_ID?.trim() || 'nuvio-cli',
+        sessionFile: process.env.NUVIO_SESSION_FILE?.trim() || join(dataDir, 'session.json'),
+        auditFile: process.env.NUVIO_AUDIT_FILE?.trim() || join(dataDir, 'audit.jsonl'),
+        snapshotDir: process.env.NUVIO_SNAPSHOT_DIR?.trim() || join(dataDir, 'snapshots'),
+        backendTimeoutMs: int(process.env.NUVIO_BACKEND_TIMEOUT_MS, 30_000),
+        disableSnapshots: bool(process.env.NUVIO_DISABLE_SNAPSHOTS, false),
+        snapshotMaxAgeDays: nonNegativeInt(process.env.NUVIO_SNAPSHOT_MAX_AGE_DAYS, 30),
+        snapshotMaxCount: nonNegativeInt(process.env.NUVIO_SNAPSHOT_MAX_COUNT, 250),
+        snapshotMaxTotalBytes: nonNegativeInt(process.env.NUVIO_SNAPSHOT_MAX_TOTAL_BYTES, 50 * 1024 * 1024),
+    };
+}

package/dist/index.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+import { closeSync, openSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { ZodError, z } from 'zod';
+import { loadConfig } from './config.js';
+import { AuthManager } from './nuvio/auth.js';
+import { NuvioClient } from './nuvio/client.js';
+import { CommandRegistry } from './cli/registry.js';
+import { registerAllCommands } from './commands/index.js';
+import { isPlanSupported } from './nuvio/ops/plan.js';
+import { VERSION } from './version.js';
+const MAX_STDOUT_BYTES = 12_000;
+function displayName(name) {
+    return name.replace(/^nuvio_/, '').replaceAll('_', '-');
+}
+function commandName(name) {
+    return 'nuvio_' + name.replaceAll('-', '_');
+}
+function fail(message, details) {
+    process.stderr.write(JSON.stringify({ error: message, ...(details === undefined ? {} : { details }) }) + '\n');
+    process.exit(1);
+}
+function parseValue(text, type) {
+    if (type === 'string')
+        return text;
+    if (type === 'integer' || type === 'number')
+        return Number(text);
+    if (type === 'boolean')
+        return text === 'true' ? true : text === 'false' ? false : text;
+    if (type === 'array' || type === 'object' || text.startsWith('{') || text.startsWith('[')) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}
+function parseFlags(argv, command) {
+    const args = {};
+    const properties = z.toJSONSchema(command.schema).properties ?? {};
+    let output;
+    let input;
+    let apply = false;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (!token.startsWith('--'))
+            fail('Unexpected positional argument: ' + token);
+        const equal = token.indexOf('=');
+        const flag = (equal >= 0 ? token.slice(2, equal) : token.slice(2)).replaceAll('-', '_');
+        if (flag === 'apply') {
+            apply = true;
+            continue;
+        }
+        if (flag === 'confirm' || flag === 'dry_run') {
+            args[flag] = equal >= 0 ? parseValue(token.slice(equal + 1), 'boolean') : true;
+            continue;
+        }
+        const value = equal >= 0 ? token.slice(equal + 1) : argv[++i];
+        if (value === undefined)
+            fail('Missing value for --' + flag.replaceAll('_', '-'));
+        if (flag === 'input')
+            input = value;
+        else if (flag === 'output')
+            output = value;
+        else
+            args[flag] = parseValue(value, properties[flag]?.type);
+    }
+    if (input) {
+        const raw = input === '-' ? readFileSync(0, 'utf8') : readFileSync(input, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || Array.isArray(parsed) || typeof parsed !== 'object')
+            fail('Input must be a JSON object');
+        return { args: { ...parsed, ...args }, output, apply };
+    }
+    return { args, output, apply };
+}
+function help(command) {
+    const json = z.toJSONSchema(command.schema);
+    return {
+        command: 'nuvio ' + displayName(command.name),
+        title: command.title,
+        description: command.description,
+        risk: command.risk,
+        parameters: json.properties ?? {},
+        required: json.required ?? [],
+        input: 'Use flags for simple values or --input FILE / --input - for a JSON object.',
+        output: 'JSON on stdout. Use --output FILE for large results.',
+    };
+}
+function print(data, output) {
+    const json = JSON.stringify(data);
+    if (output) {
+        writeFileSync(output.fd, json + '\n');
+        process.stdout.write(JSON.stringify({ saved_to: output.path, bytes: Buffer.byteLength(json) }) + '\n');
+        return;
+    }
+    if (Buffer.byteLength(json) > MAX_STDOUT_BYTES) {
+        const result = data && typeof data === 'object' && !Array.isArray(data) ? data : {};
+        process.stdout.write(JSON.stringify({
+            truncated: true,
+            bytes: Buffer.byteLength(json),
+            status: result.status,
+            snapshot_id: result.snapshot_id,
+            hint: 'Repeat a read with --output FILE for the full result.',
+        }) + '\n');
+        return;
+    }
+    process.stdout.write(json + '\n');
+}
+async function main() {
+    const [verb, ...rest] = process.argv.slice(2);
+    if (verb === '--version' || verb === 'version') {
+        print({ version: VERSION });
+        return;
+    }
+    const cfg = loadConfig();
+    const auth = new AuthManager({
+        backendUrl: cfg.backendUrl,
+        publishableKey: cfg.publishableKey,
+        email: cfg.email,
+        password: cfg.password,
+        refreshToken: cfg.refreshToken,
+        sessionFile: cfg.sessionFile,
+        timeoutMs: Math.min(cfg.backendTimeoutMs, 15_000),
+    });
+    const client = new NuvioClient(cfg, auth);
+    const registry = new CommandRegistry();
+    registerAllCommands(registry, client, cfg);
+    if (!verb || verb === 'help' || verb === '--help') {
+        const selected = rest[0] && registry.get(commandName(rest[0]));
+        print(selected
+            ? help(selected)
+            : {
+                usage: 'nuvio <command> [--flags] | nuvio help <command> | nuvio commands [search] | nuvio plan-operations',
+                examples: [
+                    'nuvio list-profiles',
+                    'nuvio list-addons --profile-id 1',
+                    'nuvio help update-settings',
+                ],
+                commands: 'Run nuvio commands <search> to discover commands by name or description.',
+            });
+        return;
+    }
+    if (verb === 'commands') {
+        const query = rest.join(' ').toLowerCase();
+        print(registry
+            .list()
+            .filter((c) => (c.name + ' ' + c.title + ' ' + c.description).toLowerCase().includes(query))
+            .map((c) => ({ command: displayName(c.name), title: c.title, risk: c.risk })));
+        return;
+    }
+    if (verb === 'plan-operations') {
+        print(registry
+            .list()
+            .filter((c) => isPlanSupported(c.name))
+            .map((c) => displayName(c.name)));
+        return;
+    }
+    const command = registry.get(commandName(verb));
+    if (!command)
+        fail('Unknown command. Run nuvio commands <search> to find one.');
+    if (rest.includes('--help')) {
+        print(help(command));
+        return;
+    }
+    const { args, output, apply } = parseFlags(rest, command);
+    if (apply) {
+        if (command.name !== 'nuvio_apply_plan')
+            fail('--apply is only valid for apply-plan');
+        args.dry_run = false;
+    }
+    let parsed;
+    try {
+        parsed = command.schema.strict().parse(args);
+    }
+    catch (error) {
+        if (error instanceof ZodError)
+            fail('Invalid command arguments', error.issues);
+        throw error;
+    }
+    const fd = output ? openSync(output, 'wx', 0o600) : undefined;
+    let completed = false;
+    try {
+        print(await command.run(parsed), output && fd !== undefined ? { path: output, fd } : undefined);
+        completed = true;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+        if (!completed && output)
+            unlinkSync(output);
+    }
+}
+main().catch((error) => fail(error instanceof Error ? error.message : String(error)));

package/dist/mask.js

@@ -0,0 +1,33 @@
+const SECRET_KEY = /(password|passwd|secret|token|api[_-]?key|credential|authorization)/i;
+/** Exact keys that are secret but not matched by SECRET_KEY (e.g. PIN). */
+const SECRET_KEYS = new Set(['pin', 'current_pin', 'new_pin', 'old_pin', 'pincode', 'passcode']);
+const NOT_SECRET = new Set(['origin_client_id']);
+function shouldMask(key) {
+    const lower = key.toLowerCase();
+    if (NOT_SECRET.has(lower))
+        return false;
+    if (SECRET_KEYS.has(lower))
+        return true;
+    return SECRET_KEY.test(lower);
+}
+/** Mask a single secret, keeping a short suffix so operators can still tell values apart. */
+export function maskSecret(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return '****';
+    if (value.length <= 4)
+        return '****';
+    return `****${value.slice(-4)}`;
+}
+/** Recursively mask values under sensitive keys. Used before any output or log. */
+export function maskDeep(value) {
+    if (Array.isArray(value))
+        return value.map(maskDeep);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [key, val] of Object.entries(value)) {
+            out[key] = shouldMask(key) ? maskSecret(val) : maskDeep(val);
+        }
+        return out;
+    }
+    return value;
+}

package/dist/nuvio/auth.js

@@ -0,0 +1,123 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { NuvioError, errorFromResponse } from './errors.js';
+const REFRESH_SKEW_SECONDS = 60;
+/**
+ * Owns the Nuvio session: signs in, persists the refresh token, and transparently
+ * refreshes the short-lived access token.
+ */
+export class AuthManager {
+    cfg;
+    session;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.session = { backendUrl: cfg.backendUrl };
+        this.load();
+    }
+    load() {
+        if (!existsSync(this.cfg.sessionFile))
+            return;
+        try {
+            const parsed = JSON.parse(readFileSync(this.cfg.sessionFile, 'utf8'));
+            if (parsed.backendUrl !== this.cfg.backendUrl)
+                return; // session belongs to a different backend
+            this.session = parsed;
+        }
+        catch {
+            /* ignore corrupt session file */
+        }
+    }
+    persist() {
+        const target = this.cfg.sessionFile;
+        const tmp = `${target}.tmp`;
+        try {
+            mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+            writeFileSync(tmp, JSON.stringify(this.session, null, 2), { mode: 0o600 });
+            renameSync(tmp, target);
+        }
+        catch {
+            /* session persistence is best-effort; the in-memory session still works */
+        }
+    }
+    get userId() {
+        return this.session.userId;
+    }
+    get email() {
+        return this.session.email ?? this.cfg.email;
+    }
+    clear() {
+        this.session = { backendUrl: this.cfg.backendUrl };
+        this.persist();
+    }
+    capture(token) {
+        this.session.accessToken = token.access_token;
+        if (token.refresh_token)
+            this.session.refreshToken = token.refresh_token;
+        const expiresAt = token.expires_at ?? (token.expires_in ? Math.floor(Date.now() / 1000) + token.expires_in : undefined);
+        this.session.expiresAt = expiresAt;
+        if (token.user?.id)
+            this.session.userId = token.user.id;
+        if (token.user?.email)
+            this.session.email = token.user.email;
+        this.persist();
+    }
+    async postToken(query, body) {
+        const res = await fetch(`${this.cfg.backendUrl}/auth/v1/token?grant_type=${query}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                apikey: this.cfg.publishableKey,
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(this.cfg.timeoutMs ?? 15_000),
+        });
+        const json = await res.json().catch(() => null);
+        if (!res.ok)
+            throw errorFromResponse(res.status, json);
+        return json;
+    }
+    async signInWithPassword() {
+        if (!this.cfg.email || !this.cfg.password) {
+            throw new NuvioError('No session available and NUVIO_EMAIL / NUVIO_PASSWORD (or NUVIO_REFRESH_TOKEN) are not set.');
+        }
+        const token = await this.postToken('password', {
+            email: this.cfg.email,
+            password: this.cfg.password,
+        });
+        this.capture(token);
+    }
+    async refresh() {
+        const refreshToken = this.session.refreshToken ?? this.cfg.refreshToken;
+        if (!refreshToken)
+            throw new NuvioError('Session expired and no refresh token is available.');
+        const token = await this.postToken('refresh_token', { refresh_token: refreshToken });
+        this.capture(token);
+    }
+    /** Force a refresh (used after a 401 from the API). */
+    async forceRefresh() {
+        await this.refresh();
+    }
+    /** Returns a valid bearer token, signing in or refreshing as needed. */
+    async getAccessToken() {
+        const now = Math.floor(Date.now() / 1000);
+        const token = this.session.accessToken;
+        const expiring = !this.session.expiresAt || this.session.expiresAt - REFRESH_SKEW_SECONDS <= now;
+        if (token && !expiring)
+            return token;
+        if (this.session.refreshToken || this.cfg.refreshToken) {
+            try {
+                await this.refresh();
+            }
+            catch (error) {
+                // A rotated/expired refresh token falls back to password auth if we have it.
+                if (!this.cfg.email || !this.cfg.password)
+                    throw error;
+                await this.signInWithPassword();
+            }
+        }
+        else {
+            await this.signInWithPassword();
+        }
+        return this.session.accessToken;
+    }
+}

package/dist/nuvio/call-context.js

@@ -0,0 +1,20 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const storage = new AsyncLocalStorage();
+export function withCallCache(fn) {
+    return storage.run({ cache: new Map() }, fn);
+}
+/** Memoize a read for the duration of the current call. Falls back to a plain call with no scope. */
+export function callCache(key, loader) {
+    const store = storage.getStore();
+    if (!store)
+        return loader();
+    const existing = store.cache.get(key);
+    if (existing)
+        return existing;
+    const pending = loader().catch((error) => {
+        store.cache.delete(key);
+        throw error;
+    });
+    store.cache.set(key, pending);
+    return pending;
+}