@magnetoagents/cli 0.1.0

package/dist/cli.js

@@ -0,0 +1,671 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createClient, MagnetoApiError, normalizeApiBase } from './client.js';
+import { resolveApiKey, writeCredentials } from './credentials.js';
+import { ACCOUNT_SPEC, COMPUTERS_SPEC, FILES_SPEC, InvalidOutputFormatError, parseOutputFlag, RUN_GET_SPEC, RUNS_SPEC, SKILLS_SPEC, TEMPLATES_SPEC, UPTIME_SPEC, formatOutput, resolveOutputFormat, } from './format.js';
+import { openUrl as defaultOpenUrl } from './open-url.js';
+import { readPackageVersion } from './package-version.js';
+/** Thrown by injected `io.exit` in tests so action `catch` blocks do not remap the code to 1. */
+export class CliExitError extends Error {
+    exitCode;
+    constructor(exitCode) {
+        super(`exit ${exitCode}`);
+        this.name = 'CliExitError';
+        this.exitCode = exitCode;
+    }
+}
+const GATEWAY_WARNING = 'Warning: this URL is a 60-second credential. Do not write it to shell history or logs.';
+function resolveIo(io) {
+    return {
+        fetchImpl: io?.fetchImpl,
+        stdout: io?.stdout ?? process.stdout,
+        stderr: io?.stderr ?? process.stderr,
+        exit: io?.exit ?? ((code) => process.exit(code)),
+        openUrl: io?.openUrl ?? defaultOpenUrl,
+        env: io?.env ?? process.env,
+    };
+}
+export function handleError(err, io) {
+    if (err instanceof CliExitError) {
+        throw err;
+    }
+    const { stderr, exit } = resolveIo(io);
+    if (err instanceof MagnetoApiError) {
+        const bits = [`error: ${err.detail} (HTTP ${err.status})`];
+        if (err.requestId)
+            bits.push(`request-id: ${err.requestId}`);
+        if (err.retryAfter)
+            bits.push(`Retry-After: ${err.retryAfter}`);
+        stderr.write(`${bits.join(' · ')}\n`);
+        return exit(err.status === 401 || err.status === 403 ? 2 : 1);
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    stderr.write(`${message}\n`);
+    return exit(1);
+}
+function addOutputOption(cmd, io) {
+    return cmd.option('--output <fmt>', 'table | json | quiet', (raw) => {
+        try {
+            return parseOutputFlag(raw);
+        }
+        catch (err) {
+            if (err instanceof InvalidOutputFormatError) {
+                io.stderr.write(`${err.message}\n`);
+                io.exit(1);
+            }
+            throw err;
+        }
+    });
+}
+function formatAccountHuman(data) {
+    const workspace = (data.workspace ?? {});
+    const subscription = data.subscription;
+    const usage = (data.usage ?? {});
+    const key = (data.key ?? {});
+    const rate = (data.rate_limit ?? {});
+    const wsName = workspace.name?.trim() ? workspace.name : '—';
+    const wsId = workspace.id ?? '';
+    let planLine;
+    if (subscription == null) {
+        planLine = '(unavailable)';
+    }
+    else if (!subscription.plans || subscription.plans.length === 0) {
+        planLine = '(none)';
+    }
+    else {
+        planLine = subscription.plans
+            .map((p) => `${p.plan ?? '?'} (${p.status ?? '?'})`)
+            .join(', ');
+    }
+    const cu = formatUsageBlob(usage.cu);
+    const llm = formatUsageBlob(usage.llm);
+    const reqToday = usage.requests_today == null ? 'n/a' : String(usage.requests_today);
+    const scopes = Array.isArray(key.scopes) ? key.scopes.join(', ') : '';
+    const expires = key.expires_at ? key.expires_at : 'never';
+    const label = (s) => s.padEnd(12);
+    return [
+        `${label('Workspace')}${wsName} (${wsId})`,
+        `${label('Plan')}${planLine}`,
+        `${label('Usage')}CU ${cu} · LLM ${llm} · requests today ${reqToday}`,
+        `${label('Key')}${key.prefix ?? ''}  scopes: ${scopes}  expires: ${expires}`,
+        `${label('Rate limit')}${rate.limit ?? '?'} / ${rate.window_s ?? '?'}s`,
+        '',
+    ].join('\n');
+}
+function formatUsageBlob(value) {
+    if (value == null)
+        return 'n/a';
+    if (typeof value === 'number' || typeof value === 'string')
+        return String(value);
+    if (typeof value === 'object') {
+        const o = value;
+        if (o.total_cost_usd != null)
+            return `$${o.total_cost_usd}`;
+        if (o.cost_usd != null)
+            return `$${o.cost_usd}`;
+    }
+    return JSON.stringify(value);
+}
+export function buildProgram(io) {
+    const resolved = resolveIo(io);
+    const { stdout, stderr, exit, env, openUrl } = resolved;
+    function requireClient() {
+        const apiKey = resolveApiKey(env);
+        if (!apiKey) {
+            stderr.write('No API key. Run `magneto login <key>` or set MAGNETO_API_KEY. Mint keys in the dashboard.\n');
+            return exit(1);
+        }
+        const timeoutRaw = env.MAGNETO_TIMEOUT_MS;
+        const parsedTimeout = timeoutRaw != null ? Number(timeoutRaw) : NaN;
+        return createClient({
+            apiKey,
+            baseUrl: env.MAGNETO_API_BASE ?? env.MAGNETO_BASE_URL,
+            fetchImpl: resolved.fetchImpl,
+            ...(Number.isFinite(parsedTimeout) && parsedTimeout > 0 ? { timeoutMs: parsedTimeout } : {}),
+        });
+    }
+    function printJson(data) {
+        stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    }
+    function fail(err) {
+        if (err instanceof CliExitError)
+            throw err;
+        handleError(err, resolved);
+    }
+    function writeFormatted(data, explicit, spec) {
+        let format;
+        try {
+            format = resolveOutputFormat({ explicit, isTty: Boolean(stdout.isTTY) });
+        }
+        catch (err) {
+            if (err instanceof InvalidOutputFormatError) {
+                stderr.write(`${err.message}\n`);
+                exit(1);
+            }
+            throw err;
+        }
+        stdout.write(formatOutput(data, format, spec));
+    }
+    const program = new Command();
+    program
+        .name('magneto')
+        .description('Magneto CLI — public /api/v1 with sk_live_* keys')
+        .version(readPackageVersion());
+    program.exitOverride((err) => {
+        exit(typeof err.exitCode === 'number' ? err.exitCode : 1);
+    });
+    program.configureOutput({
+        writeOut: (s) => {
+            stdout.write(s);
+        },
+        writeErr: (s) => {
+            stderr.write(s);
+        },
+    });
+    program
+        .command('login')
+        .description('Save an sk_live_* key to ~/.magneto/credentials.json (mode 0600)')
+        .argument('<key>', 'Workspace API key (sk_live_…)')
+        .action((key) => {
+        if (!key.startsWith('sk_live_')) {
+            stderr.write('Key must start with sk_live_\n');
+            exit(1);
+        }
+        const credPath = writeCredentials(key);
+        stdout.write(`Credentials written to ${credPath} (mode 0600)\n`);
+        stdout.write(`API base: ${normalizeApiBase(env.MAGNETO_API_BASE)}\n`);
+    });
+    const computers = program.command('computers').description('Manage computers');
+    addOutputOption(computers
+        .command('list')
+        .description('List computers for the key minting user'), resolved).action(async (opts) => {
+        try {
+            const client = requireClient();
+            writeFormatted(await client.listComputers(), opts.output, COMPUTERS_SPEC);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    computers
+        .command('create')
+        .description('Create a computer (workspace forced from key)')
+        .option('--name <name>', 'Display name')
+        .option('--flavor <flavor>', 'agent | desktop', 'agent')
+        .option('--template-id <id>', 'Agent template id', (v) => Number(v))
+        .option('--vcpu <n>', 'Desktop vCPU', (v) => Number(v))
+        .option('--ram-gb <n>', 'Desktop RAM GB', (v) => Number(v))
+        .option('--disk-gb <n>', 'Desktop disk GB', (v) => Number(v))
+        .action(async (opts) => {
+        try {
+            const client = requireClient();
+            const body = {};
+            if (opts.name)
+                body.name = opts.name;
+            if (opts.flavor)
+                body.flavor = opts.flavor;
+            if (opts.templateId != null && !Number.isNaN(opts.templateId)) {
+                body.template_id = opts.templateId;
+            }
+            if (opts.vcpu != null && !Number.isNaN(opts.vcpu))
+                body.vcpu = opts.vcpu;
+            if (opts.ramGb != null && !Number.isNaN(opts.ramGb))
+                body.ram_gb = opts.ramGb;
+            if (opts.diskGb != null && !Number.isNaN(opts.diskGb))
+                body.disk_gb = opts.diskGb;
+            printJson(await client.createComputer(body));
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    addOutputOption(computers.command('get').description('Get a computer').argument('<id>', 'Computer id'), resolved).action(async (id, opts) => {
+        try {
+            const client = requireClient();
+            writeFormatted(await client.getComputer(id), opts.output, COMPUTERS_SPEC);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    computers
+        .command('start')
+        .description('Start a stopped computer')
+        .argument('<id>', 'Computer id')
+        .action(async (id) => {
+        try {
+            const client = requireClient();
+            printJson(await client.startComputer(id));
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    computers
+        .command('restart')
+        .description('Restart a computer')
+        .argument('<id>', 'Computer id')
+        .action(async (id) => {
+        try {
+            const client = requireClient();
+            printJson(await client.restartComputer(id));
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    computers
+        .command('stop')
+        .description('Stop a computer')
+        .argument('<id>', 'Computer id')
+        .action(async (id) => {
+        try {
+            const client = requireClient();
+            printJson(await client.stopComputer(id));
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    computers
+        .command('resize')
+        .description('Resize a desktop computer (all three flags required)')
+        .argument('<id>', 'Computer id')
+        .requiredOption('--vcpu <n>', 'Desktop vCPU', (v) => Number(v))
+        .requiredOption('--ram-gb <n>', 'Desktop RAM GB', (v) => Number(v))
+        .requiredOption('--disk-gb <n>', 'Desktop disk GB', (v) => Number(v))
+        .action(async (id, opts) => {
+        try {
+            if ([opts.vcpu, opts.ramGb, opts.diskGb].some((n) => Number.isNaN(n))) {
+                stderr.write('--vcpu, --ram-gb, and --disk-gb must be numbers\n');
+                exit(1);
+            }
+            const client = requireClient();
+            printJson(await client.resizeComputer(id, {
+                vcpu: opts.vcpu,
+                ram_gb: opts.ramGb,
+                disk_gb: opts.diskGb,
+            }));
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    computers
+        .command('delete')
+        .description('Irreversible deprovision. --confirm must equal the computer name (forwarded as ?confirm=). No prompt.')
+        .argument('<id>', 'Computer id')
+        .requiredOption('--confirm <name>', 'Computer name (must match)')
+        .action(async (id, opts) => {
+        try {
+            const client = requireClient();
+            const result = await client.deleteComputer(id, opts.confirm);
+            if (result === undefined) {
+                stdout.write('ok\n');
+            }
+            else {
+                printJson(result);
+            }
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    addOutputOption(computers
+        .command('uptime')
+        .description('Uptime for a computer')
+        .argument('<id>', 'Computer id')
+        .option('--window-seconds <n>', 'Lookback window in seconds', (v) => Number(v)), resolved).action(async (id, opts) => {
+        try {
+            const client = requireClient();
+            const windowSeconds = opts.windowSeconds != null && !Number.isNaN(opts.windowSeconds)
+                ? opts.windowSeconds
+                : undefined;
+            writeFormatted(await client.getComputerUptime(id, windowSeconds), opts.output, UPTIME_SPEC);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    program
+        .command('gateway')
+        .description('Mint a 60-second signed desktop/terminal URL. The URL is a credential — do not write it to shell history or logs.')
+        .argument('<id>', 'Computer id')
+        .requiredOption('--target <target>', 'desktop | terminal')
+        .option('--open', 'Open the URL in the default browser')
+        .action(async (id, opts) => {
+        try {
+            const target = opts.target;
+            if (target !== 'desktop' && target !== 'terminal') {
+                stderr.write('--target must be desktop or terminal\n');
+                return exit(1);
+            }
+            const client = requireClient();
+            const result = await client.mintGatewayUrl(id, target);
+            stdout.write(`${result.url}\n`);
+            stderr.write(`${GATEWAY_WARNING}\n`);
+            if (opts.open)
+                await openUrl(result.url);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    program
+        .command('run')
+        .description('Run a computer-use instruction (desktop only; streams to stdout)')
+        .argument('<instruction>', 'Natural-language instruction')
+        .requiredOption('--computer <id>', 'Desktop computer id')
+        .option('--model <model>', 'Model id (default server-side)')
+        .option('--max-steps <n>', 'Max CU steps', (v) => Number(v))
+        .action(async (instruction, opts) => {
+        try {
+            const client = requireClient();
+            await client.runComputerUse(opts.computer, {
+                instruction,
+                ...(opts.model ? { model: opts.model } : {}),
+                ...(opts.maxSteps != null && !Number.isNaN(opts.maxSteps)
+                    ? { max_steps: opts.maxSteps }
+                    : {}),
+            }, (chunk) => {
+                stdout.write(chunk);
+            });
+            if (stdout.isTTY)
+                stdout.write('\n');
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    const runs = program.command('runs').description('Computer-use runs');
+    addOutputOption(runs
+        .command('list')
+        .description('List runs for a computer')
+        .requiredOption('--computer <id>', 'Computer id')
+        .option('--limit <n>', 'Page size', (v) => Number(v))
+        .option('--offset <n>', 'Page offset', (v) => Number(v)), resolved).action(async (opts) => {
+        try {
+            const client = requireClient();
+            const page = {};
+            if (opts.limit != null && !Number.isNaN(opts.limit))
+                page.limit = opts.limit;
+            if (opts.offset != null && !Number.isNaN(opts.offset))
+                page.offset = opts.offset;
+            writeFormatted(await client.listRuns(opts.computer, page), opts.output, RUNS_SPEC);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    addOutputOption(runs
+        .command('get')
+        .description('Get a run (table/quiet hide events; json includes them)')
+        .argument('<run_id>', 'Run id')
+        .requiredOption('--computer <id>', 'Computer id'), resolved).action(async (runId, opts) => {
+        try {
+            const client = requireClient();
+            writeFormatted(await client.getRun(opts.computer, runId), opts.output, RUN_GET_SPEC);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    runs
+        .command('export')
+        .description('Export a run replay (bytes to -o or stdout). Timeout exempt.')
+        .argument('<run_id>', 'Run id')
+        .requiredOption('--computer <id>', 'Computer id')
+        .option('-o, --output-file <file>', 'Write bytes to this path')
+        .action(async (runId, opts) => {
+        try {
+            const client = requireClient();
+            const res = await client.exportRun(opts.computer, runId);
+            const buf = Buffer.from(await res.arrayBuffer());
+            if (opts.outputFile) {
+                fs.mkdirSync(path.dirname(opts.outputFile), { recursive: true });
+                fs.writeFileSync(opts.outputFile, buf);
+            }
+            else {
+                stdout.write(buf);
+            }
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    runs
+        .command('stop')
+        .description('Stop a computer-use run')
+        .argument('<run_id>', 'Run id')
+        .requiredOption('--computer <id>', 'Computer id')
+        .action(async (runId, opts) => {
+        try {
+            const client = requireClient();
+            printJson(await client.stopRun(opts.computer, runId));
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    program
+        .command('bash')
+        .description('Run a shell command on a computer. Requires key scope `exec` (not in the default set). ' +
+        'On HTTP 200 the process exit code is the remote exit_code (not 1/2). ' +
+        'HTTP 401/403 still exit 2; other HTTP errors still exit 1. ' +
+        'Quote commands with spaces: magneto bash <id> -- "cmd with spaces".')
+        .argument('<id>', 'Computer id')
+        .argument('[command]', 'Remote command (use -- before commands that start with -)')
+        .option('--timeout <seconds>', 'Remote timeout in seconds (server clamps 1–300)', (v) => Number(v))
+        .action(async (id, command, opts) => {
+        try {
+            if (!command) {
+                stderr.write('command is required (e.g. magneto bash <id> -- "echo ok")\n');
+                return exit(1);
+            }
+            const timeout = opts.timeout != null && !Number.isNaN(opts.timeout) ? opts.timeout : 60;
+            const client = requireClient();
+            const result = await client.bash(id, { command, timeout });
+            stdout.write(result.output ?? '');
+            if (result.timed_out)
+                stderr.write('timed out\n');
+            if (result.truncated)
+                stderr.write('output truncated\n');
+            exit((result.exit_code ?? 0) & 255);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    const files = program.command('files').description('Account files');
+    addOutputOption(files.command('list').description('List uploaded files'), resolved).action(async (opts) => {
+        try {
+            const client = requireClient();
+            writeFormatted(await client.listFiles(), opts.output, FILES_SPEC);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    files
+        .command('upload')
+        .description('Upload a local file (multipart field `file`, 10 MiB server limit)')
+        .argument('<path>', 'Local file path')
+        .action(async (filePath) => {
+        try {
+            if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+                stderr.write(`file not found: ${filePath}\n`);
+                exit(1);
+            }
+            const stat = fs.statSync(filePath);
+            if (stat.size === 0) {
+                stderr.write('file is empty\n');
+                exit(1);
+            }
+            if (stat.size > 10 * 1024 * 1024) {
+                stderr.write('warning: file exceeds 10 MiB; server will reject it\n');
+            }
+            const client = requireClient();
+            printJson(await client.uploadFile(filePath));
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    files
+        .command('download')
+        .description('Download a file via its signed URL (URL is never printed)')
+        .argument('<id>', 'File id')
+        .option('-o, --output <dir>', 'Destination file or directory (trailing / = directory)')
+        .action(async (id, opts) => {
+        try {
+            const client = requireClient();
+            const info = await client.getFileDownloadUrl(id);
+            const filename = typeof info.filename === 'string' && info.filename ? info.filename : id;
+            let dest;
+            if (opts.output) {
+                const asDir = opts.output.endsWith('/') ||
+                    opts.output.endsWith(path.sep) ||
+                    (fs.existsSync(opts.output) && fs.statSync(opts.output).isDirectory());
+                dest = asDir ? path.join(opts.output, filename) : opts.output;
+            }
+            else {
+                dest = path.join('.', filename);
+            }
+            await client.downloadSignedUrl(info.url, dest);
+            stderr.write(`${dest}\n`);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    const templates = program.command('templates').description('Agent template catalog');
+    addOutputOption(templates
+        .command('list')
+        .description('List templates')
+        .option('--skip <n>', 'Offset', (v) => Number(v), 0)
+        .option('--limit <n>', 'Page size', (v) => Number(v), 100), resolved).action(async (opts) => {
+        try {
+            const client = requireClient();
+            const skip = opts.skip != null && !Number.isNaN(opts.skip) ? opts.skip : 0;
+            const limit = opts.limit != null && !Number.isNaN(opts.limit) ? opts.limit : 100;
+            writeFormatted(await client.listTemplates({ skip, limit }), opts.output, TEMPLATES_SPEC);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    const skills = program.command('skills').description('Skill install helpers');
+    skills
+        .command('install')
+        .description('Install a marketplace skill onto a computer')
+        .argument('<skill_id>', 'Numeric skill id', (v) => Number(v))
+        .requiredOption('--computer <id>', 'Computer id')
+        .action(async (skillId, opts) => {
+        try {
+            if (typeof skillId !== 'number' || Number.isNaN(skillId)) {
+                stderr.write('skill_id must be a number\n');
+                exit(1);
+            }
+            const client = requireClient();
+            printJson(await client.installSkill(opts.computer, skillId));
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    addOutputOption(skills
+        .command('search')
+        .description('List marketplace skills. Optional [query] filters the fetched page client-side (name + description); v1 has no ?q=.')
+        .argument('[query]', 'Client-side substring filter')
+        .option('--skip <n>', 'Offset', (v) => Number(v), 0)
+        .option('--limit <n>', 'Page size', (v) => Number(v), 100), resolved).action(async (query, opts) => {
+        try {
+            const client = requireClient();
+            const skip = opts.skip != null && !Number.isNaN(opts.skip) ? opts.skip : 0;
+            const limit = opts.limit != null && !Number.isNaN(opts.limit) ? opts.limit : 100;
+            const rows = (await client.listSkills({ skip, limit }));
+            const filtered = query && query.trim()
+                ? rows.filter((row) => {
+                    const q = query.toLowerCase();
+                    const name = String(row.name ?? '').toLowerCase();
+                    const desc = String(row.description ?? '').toLowerCase();
+                    return name.includes(q) || desc.includes(q);
+                })
+                : rows;
+            writeFormatted(filtered, opts.output, SKILLS_SPEC);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    skills
+        .command('uninstall')
+        .description('Uninstall a marketplace skill from a computer (204 → silent)')
+        .argument('<skill_id>', 'Skill id')
+        .requiredOption('--computer <id>', 'Computer id')
+        .action(async (skillId, opts) => {
+        try {
+            const client = requireClient();
+            await client.uninstallSkill(opts.computer, skillId);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    addOutputOption(program
+        .command('account')
+        .description('Workspace plan, usage, key scopes, and rate limit'), resolved).action(async (opts) => {
+        try {
+            const client = requireClient();
+            const data = (await client.getAccount());
+            const warnings = data.warnings;
+            if (Array.isArray(warnings)) {
+                for (const w of warnings)
+                    stderr.write(`${String(w)}\n`);
+            }
+            let format;
+            try {
+                format = resolveOutputFormat({ explicit: opts.output, isTty: Boolean(stdout.isTTY) });
+            }
+            catch (err) {
+                if (err instanceof InvalidOutputFormatError) {
+                    stderr.write(`${err.message}\n`);
+                    exit(1);
+                }
+                throw err;
+            }
+            if (format === 'json') {
+                stdout.write(formatOutput(data, 'json', ACCOUNT_SPEC));
+            }
+            else if (format === 'quiet') {
+                stdout.write(formatOutput(data, 'quiet', ACCOUNT_SPEC));
+            }
+            else {
+                stdout.write(formatAccountHuman(data));
+            }
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    return program;
+}
+function isEntrypoint() {
+    const invoked = process.argv[1];
+    if (!invoked)
+        return false;
+    try {
+        return path.resolve(invoked) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntrypoint()) {
+    buildProgram()
+        .parseAsync(process.argv)
+        .catch((err) => handleError(err));
+}