@shardflux/cli 0.1.0

package/dist/args.js

@@ -0,0 +1,390 @@
+/**
+ * Command table and argument parsing for `shard` (node:util parseArgs, no
+ * dependencies). Pure: no SDK, no I/O, so it is unit-tested directly.
+ *
+ *   shard [global options] <command> [options] [arguments]
+ *
+ * `workspaces` may be written `ws`; `operations` may be written `ops`; the
+ * `files` and `operations` groups are also reachable under `workspaces`
+ * (`shard workspaces files read ...` == `shard files read ...`).
+ */
+import { parseArgs } from 'node:util';
+import { UsageError } from "./errors.js";
+export const CLI_VERSION = '0.1.0';
+export const GLOBAL_OPTIONS = {
+    'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
+    json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
+    'agent-label': { type: 'string', value: '<label>', description: 'Attribution label for workspace tool tokens (default $SHARDFLUX_AGENT_LABEL, else "cli").' },
+    help: { type: 'boolean', short: 'h', description: 'Show help.' },
+    version: { type: 'boolean', short: 'V', description: 'Print the version.' },
+};
+const CAPS = {
+    'cpu-millis': { type: 'string', value: '<n>', description: 'CPU cap in millicores.' },
+    'memory-mib': { type: 'string', value: '<n>', description: 'Memory cap in MiB.' },
+    'disk-gib': { type: 'string', value: '<n>', description: 'Disk cap in GiB.' },
+};
+const WAIT = {
+    wait: { type: 'boolean', description: 'Wait until the operation finishes.' },
+    timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (e.g. 90s, 5m; default 5m). The operation continues server side.' },
+};
+const REF = { name: 'id|key', required: true };
+export const COMMANDS = [
+    {
+        path: ['login'],
+        summary: 'Verify SHARDFLUX_API_KEY and show its organization, project and tool permissions',
+        description: 'shard never stores the key: it is read from SHARDFLUX_API_KEY on every run.',
+        positionals: [],
+        options: {},
+    },
+    { path: ['whoami'], summary: 'Show the principal behind SHARDFLUX_API_KEY', positionals: [], options: {} },
+    { path: ['version'], summary: 'Print the CLI and SDK versions', positionals: [], options: {} },
+    {
+        path: ['usage'],
+        summary: 'Show the organization usage summary for the current period',
+        positionals: [],
+        options: { org: { type: 'string', value: '<organization-id>', description: 'Organization (default: the API key’s organization).' } },
+    },
+    {
+        path: ['workspaces', 'open'],
+        summary: 'Open a workspace by key (create on first use, reconnect or resume afterwards)',
+        description: 'Waits until the workspace is ready unless --no-wait. Reopening never resets an existing workspace.',
+        positionals: [{ name: 'key', required: true }],
+        options: {
+            template: { type: 'string', value: '<slug>', description: 'Template slug (required), e.g. python-node-browser.' },
+            ...CAPS,
+            wait: { type: 'boolean', description: 'Wait until ready (default; --no-wait returns at once).' },
+            timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m). The start continues server side.' },
+        },
+        examples: ['shard workspaces open acme/demo --template python-node-browser', 'shard ws open acme/demo --template python-node-browser --no-wait --json'],
+    },
+    {
+        path: ['workspaces', 'list'],
+        summary: 'List the project’s workspaces',
+        positionals: [],
+        options: {
+            state: { type: 'string', value: '<state>', description: 'Observed state filter (running, suspended, creating, ...).' },
+            prefix: { type: 'string', value: '<key-prefix>', description: 'Only keys starting with this prefix.' },
+            'include-deleted': { type: 'boolean', description: 'Include deleted workspaces (tombstones).' },
+            all: { type: 'boolean', description: 'Fetch every page.' },
+            limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 50).' },
+            cursor: { type: 'string', value: '<cursor>', description: 'Continue from a previous page.' },
+        },
+    },
+    { path: ['workspaces', 'get'], summary: 'Show one workspace', positionals: [REF], options: {} },
+    {
+        path: ['workspaces', 'exec'],
+        summary: 'Run a command in a workspace; streams its output and exits with its exit code',
+        description: 'Runs argv directly (no shell; use `-- bash -lc "..."` for shell syntax). Output is streamed as it arrives and resumes from byte offsets after dropped connections; Ctrl-C stops waiting and cancels the command.',
+        positionals: [REF, { name: 'command', required: true, variadic: true }],
+        options: {
+            cwd: { type: 'string', value: '<dir>', description: 'Working directory (absolute).' },
+            env: { type: 'string', multiple: true, value: '<K=V>', description: 'Environment variable (repeatable).' },
+            timeout: { type: 'string', value: '<duration>', description: 'Kill the command after this long (exit code 124).' },
+            stdin: { type: 'string', value: '<file|->', description: 'Send this file (or - for standard input) to the command’s stdin (max 1 MiB).' },
+        },
+        examples: ['shard ws exec acme/demo -- python3 -V', 'shard ws exec acme/demo --cwd /home/user/app --env CI=1 -- bash -lc "npm test"'],
+    },
+    { path: ['workspaces', 'suspend'], summary: 'Suspend a running workspace (durable checkpoint)', positionals: [REF], options: { ...WAIT } },
+    { path: ['workspaces', 'resume'], summary: 'Resume a suspended workspace', positionals: [REF], options: { ...WAIT } },
+    {
+        path: ['workspaces', 'fork'],
+        summary: 'Fork a workspace into a new key',
+        positionals: [REF, { name: 'new-key', required: true }],
+        options: { ...CAPS, ...WAIT },
+    },
+    {
+        path: ['workspaces', 'delete'],
+        summary: 'Delete a workspace (tool access ends now; storage is cleaned up asynchronously)',
+        positionals: [REF],
+        options: { yes: { type: 'boolean', description: 'Required: confirm the deletion.' }, ...WAIT },
+    },
+    { path: ['workspaces', 'sessions'], summary: 'List the attributed agent sessions (tool-token principals and labels) of a workspace', positionals: [REF], options: {} },
+    {
+        path: ['files', 'read'],
+        summary: 'Print (or save) a file from a workspace',
+        positionals: [REF, { name: 'path', required: true }],
+        options: { out: { type: 'string', value: '<file>', description: 'Write to this local file instead of stdout.' } },
+    },
+    {
+        path: ['files', 'write'],
+        summary: 'Write a file in a workspace (atomic; durable once acknowledged)',
+        positionals: [REF, { name: 'path', required: true }],
+        options: {
+            from: { type: 'string', value: '<file|->', description: 'Local file to upload, or - for standard input (default -).' },
+            append: { type: 'boolean', description: 'Append instead of replacing.' },
+            parents: { type: 'boolean', description: 'Create missing parent directories (default; --no-parents to refuse).' },
+        },
+    },
+    {
+        path: ['files', 'ls'],
+        summary: 'List a directory in a workspace',
+        positionals: [REF, { name: 'path', required: true }],
+        options: { limit: { type: 'string', value: '<n>', description: 'Maximum entries (default 1000).' } },
+    },
+    {
+        path: ['operations', 'list'],
+        summary: 'List a workspace’s operations, newest first',
+        positionals: [REF],
+        options: {
+            state: { type: 'string', value: '<state>', description: 'queued, capacity_pending, running, succeeded, failed or canceled.' },
+            kind: { type: 'string', value: '<kind>', description: 'open, suspend, resume, fork, snapshot, delete, ...' },
+            limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 50).' },
+        },
+    },
+    { path: ['operations', 'get'], summary: 'Show one operation', positionals: [{ name: 'operation-id', required: true }], options: {} },
+    {
+        path: ['operations', 'wait'],
+        summary: 'Wait for an operation to finish (exit 0 succeeded, 6 failed/canceled, 5 timeout)',
+        positionals: [{ name: 'operation-id', required: true }],
+        options: { timeout: { type: 'string', value: '<duration>', description: 'Give up after this long (default 5m).' } },
+    },
+];
+const GROUPS = {
+    workspaces: 'Open, inspect and manage workspaces',
+    files: 'Read, write and list files in a workspace',
+    operations: 'Inspect and wait for lifecycle operations',
+};
+const ALIASES = { ws: 'workspaces', workspace: 'workspaces', ops: 'operations', operation: 'operations', file: 'files' };
+/** Canonical command words: aliases resolved, `workspaces files|operations` folded to the top-level group. */
+export function normalizeWords(words) {
+    const w = words.map((x) => ALIASES[x] ?? x);
+    if (w[0] === 'workspaces' && (w[1] === 'files' || w[1] === 'operations'))
+        return w.slice(1);
+    return w;
+}
+const key = (path) => path.join(' ');
+const BY_PATH = new Map(COMMANDS.map((c) => [key(c.path), c]));
+function isPrefix(words) {
+    const n = normalizeWords(words);
+    if (n.length === 0)
+        return true;
+    return COMMANDS.some((c) => n.length <= c.path.length && n.every((x, i) => c.path[i] === x));
+}
+export function findCommand(words) {
+    return BY_PATH.get(key(normalizeWords(words)));
+}
+// ---- values --------------------------------------------------------------------------------
+const DURATION = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/;
+const MAX_DURATION_MS = 7 * 24 * 3600 * 1000;
+/** "90s", "5m", "1.5h", "250ms"; a bare number is seconds. */
+export function parseDuration(text, option = 'duration') {
+    const m = DURATION.exec(text.trim());
+    if (!m)
+        throw new UsageError(`--${option} must be a duration like 30s, 5m, 1h or 500ms (got "${text}")`);
+    const n = Number(m[1]);
+    const mult = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 }[(m[2] ?? 's')];
+    const ms = Math.round(n * mult);
+    if (ms <= 0)
+        throw new UsageError(`--${option} must be greater than zero`);
+    if (ms > MAX_DURATION_MS)
+        throw new UsageError(`--${option} must be at most 7 days`);
+    return ms;
+}
+export function parsePositiveInt(text, option, max = Number.MAX_SAFE_INTEGER) {
+    if (!/^\d+$/.test(text.trim()))
+        throw new UsageError(`--${option} must be a positive integer (got "${text}")`);
+    const n = Number(text);
+    if (n < 1 || n > max)
+        throw new UsageError(`--${option} must be between 1 and ${max}`);
+    return n;
+}
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** ["A=1", "B=x=y"] -> { A: "1", B: "x=y" }. */
+export function parseEnvPairs(pairs) {
+    const out = {};
+    for (const p of pairs) {
+        const eq = p.indexOf('=');
+        const name = eq < 0 ? p : p.slice(0, eq);
+        if (eq < 0 || !ENV_NAME.test(name))
+            throw new UsageError(`--env expects NAME=value with a valid variable name (got "${p}")`);
+        out[name] = p.slice(eq + 1);
+    }
+    return out;
+}
+export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+/** Validates the API base URL: https, or http only to a loopback address (the key is a bearer credential). */
+export function resolveApiUrl(flag, env) {
+    const raw = (flag ?? env ?? '').trim() || 'https://api.shardflux.dev';
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new UsageError(`API URL is not a valid URL: "${raw}"`);
+    }
+    if (u.protocol !== 'https:' && !(u.protocol === 'http:' && (LOOPBACK.has(u.hostname) || u.hostname.endsWith('.localhost')))) {
+        throw new UsageError(`API URL must use https (plain http is allowed only for localhost): "${raw}"`);
+    }
+    if (u.username || u.password || u.search || u.hash)
+        throw new UsageError('API URL must not contain credentials, a query or a fragment');
+    return u.toString().replace(/\/+$/, '');
+}
+const FORBIDDEN_KEY_FLAG = /^--?(api-?key|apikey|key|token|secret)(=.*)?$/i;
+const GLOBAL_VALUE_FLAGS = new Set(['--api-url', '--agent-label']);
+function toParseArgsOptions(opts) {
+    const out = {};
+    for (const [name, o] of Object.entries(opts))
+        out[name] = { type: o.type, ...(o.short ? { short: o.short } : {}), ...(o.multiple ? { multiple: true } : {}) };
+    return out;
+}
+/**
+ * Parses argv (without node/script). Throws UsageError for anything invalid;
+ * returns help text for --help, bare groups and a bare `shard`.
+ */
+export function parseCommandLine(argv) {
+    const terminator = argv.indexOf('--');
+    const head = terminator < 0 ? argv : argv.slice(0, terminator);
+    for (const a of head) {
+        if (FORBIDDEN_KEY_FLAG.test(a)) {
+            throw new UsageError('shard reads the API key only from the SHARDFLUX_API_KEY environment variable; never pass it on the command line (shell history and process listings would expose it)');
+        }
+    }
+    // Pick the command words (the leading non-option words that form a known command path).
+    const words = [];
+    const rest = [];
+    let sawPositional = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--') {
+            rest.push(...argv.slice(i));
+            break;
+        }
+        if (a.startsWith('-') && a !== '-') {
+            rest.push(a);
+            if (GLOBAL_VALUE_FLAGS.has(a) && i + 1 < argv.length)
+                rest.push(argv[(i += 1)]);
+            continue;
+        }
+        if (!sawPositional && !findCommand(words) && isPrefix([...words, a])) {
+            words.push(a);
+            continue;
+        }
+        sawPositional = true;
+        rest.push(a);
+    }
+    const wantsHelp = head.includes('--help') || head.includes('-h');
+    const command = findCommand(words);
+    if (!command) {
+        if (words.length === 0) {
+            if (head.includes('--version') || head.includes('-V'))
+                return { kind: 'version' };
+            const stray = rest.find((r) => !r.startsWith('-'));
+            if (stray !== undefined)
+                throw new UsageError(`unknown command "${stray}"`);
+            if (rest.length > 0 && !wantsHelp) {
+                const unknown = rest.find((r) => !(r in { '--json': 1, '--help': 1, '-h': 1 }));
+                if (unknown !== undefined)
+                    throw new UsageError(`unknown option "${unknown}"`);
+            }
+            return { kind: 'help', text: topHelp() };
+        }
+        const group = normalizeWords(words)[0];
+        const stray = rest.find((r) => !r.startsWith('-'));
+        if (stray !== undefined)
+            throw new UsageError(`unknown command "${[...normalizeWords(words), stray].join(' ')}"`);
+        return { kind: 'help', text: groupHelp(group) };
+    }
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: rest,
+            options: toParseArgsOptions({ ...GLOBAL_OPTIONS, ...command.options }),
+            allowPositionals: true,
+            allowNegative: true,
+            strict: true,
+        });
+    }
+    catch (err) {
+        throw new UsageError(err instanceof Error ? err.message : String(err));
+    }
+    const values = parsed.values;
+    if (values.help === true)
+        return { kind: 'help', text: commandHelp(command) };
+    if (values.version === true)
+        return { kind: 'version' };
+    const positionals = parsed.positionals;
+    const specs = command.positionals;
+    const variadic = specs.at(-1)?.variadic === true;
+    const required = specs.filter((s) => s.required && !s.variadic).length;
+    if (positionals.length < required || (variadic && positionals.length < specs.length)) {
+        const missing = specs[Math.min(positionals.length, specs.length - 1)];
+        throw new UsageError(`missing <${missing.name}> for "shard ${command.path.join(' ')}"`);
+    }
+    if (!variadic && positionals.length > specs.length) {
+        throw new UsageError(`unexpected argument "${positionals[specs.length]}" for "shard ${command.path.join(' ')}"`);
+    }
+    return {
+        kind: 'run',
+        command,
+        values,
+        positionals,
+        global: {
+            apiUrl: typeof values['api-url'] === 'string' ? values['api-url'] : undefined,
+            json: values.json === true,
+            agentLabel: typeof values['agent-label'] === 'string' ? values['agent-label'] : undefined,
+        },
+    };
+}
+// ---- help ----------------------------------------------------------------------------------
+function optionLines(opts) {
+    const rows = Object.entries(opts).map(([name, o]) => [`${o.short ? `-${o.short}, ` : '    '}--${name}${o.value ? ` ${o.value}` : ''}`, o.description]);
+    const w = Math.max(0, ...rows.map((r) => r[0].length));
+    return rows.map(([l, d]) => `  ${l.padEnd(w)}  ${d}`);
+}
+export function usageLine(c) {
+    const pos = c.positionals.map((p) => (p.variadic ? `-- <${p.name}> [args...]` : p.required ? `<${p.name}>` : `[${p.name}]`));
+    const opts = Object.keys(c.options).length > 0 ? ' [options]' : '';
+    return `shard ${c.path.join(' ')}${opts}${pos.length ? ` ${pos.join(' ')}` : ''}`;
+}
+export function commandHelp(c) {
+    const lines = [`Usage: ${usageLine(c)}`, '', c.summary + '.'];
+    if (c.description)
+        lines.push('', c.description);
+    if (Object.keys(c.options).length > 0)
+        lines.push('', 'Options:', ...optionLines(c.options));
+    lines.push('', 'Global options:', ...optionLines(GLOBAL_OPTIONS));
+    if (c.examples?.length)
+        lines.push('', 'Examples:', ...c.examples.map((e) => `  ${e}`));
+    return lines.join('\n') + '\n';
+}
+export function groupHelp(group) {
+    const cmds = COMMANDS.filter((c) => c.path[0] === group);
+    const w = Math.max(...cmds.map((c) => usageLine(c).length));
+    return [`Usage: shard ${group} <command> [options]`, '', `${GROUPS[group] ?? ''}.`, '', 'Commands:', ...cmds.map((c) => `  ${usageLine(c).padEnd(w)}  ${c.summary}`), ...(group === 'workspaces' ? ['', 'Also: shard workspaces files <read|write|ls> ... and shard workspaces operations <list|get|wait> ...'] : []), '', `Run "shard ${group} <command> --help" for details.`].join('\n') + '\n';
+}
+export const EXIT_CODE_HELP = [
+    '  0    success',
+    '  1    error (API refusal such as conflict or quota, network, protocol)',
+    '  2    usage error (bad arguments, or input the API rejected as invalid)',
+    '  3    not found (workspace, operation or route)',
+    '  4    authentication/authorization (missing, malformed, revoked or insufficient key)',
+    '  5    timeout (waiting gave up; the operation continues server side)',
+    '  6    operation failed or canceled',
+    '  130  interrupted (Ctrl-C)',
+    '  exec: the command’s own exit code (124 if it timed out, 128+N if killed by signal N)',
+];
+export function topHelp() {
+    const w = Math.max(...COMMANDS.map((c) => usageLine(c).length));
+    return [
+        `shard ${CLI_VERSION} — the Shardflux command line (built on @shardflux/sdk)`,
+        '',
+        'Usage: shard [global options] <command> [options] [arguments]',
+        '',
+        'Commands:',
+        ...COMMANDS.map((c) => `  ${usageLine(c).padEnd(w)}  ${c.summary}`),
+        '',
+        'Aliases: ws = workspaces, ops = operations; "shard workspaces files|operations ..." also works.',
+        '',
+        'Global options:',
+        ...optionLines(GLOBAL_OPTIONS),
+        '',
+        'Environment:',
+        '  SHARDFLUX_API_KEY      project API key (sfk_...), required; never pass it as an argument',
+        '  SHARDFLUX_API_URL      API base URL (default https://api.shardflux.dev)',
+        '  SHARDFLUX_AGENT_LABEL  attribution label for tool tokens (default cli)',
+        '',
+        'Exit codes:',
+        ...EXIT_CODE_HELP,
+    ].join('\n') + '\n';
+}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * `shard` executable. Ctrl-C aborts in-flight waits/streams cleanly (exit
+ * 130); a second Ctrl-C exits at once. Output is flushed before exiting
+ * (stdout/stderr pipes are asynchronous on macOS).
+ */
+import { run } from "./main.js";
+const controller = new AbortController();
+let interrupts = 0;
+process.on('SIGINT', () => {
+    interrupts += 1;
+    if (interrupts > 1)
+        process.exit(130);
+    controller.abort(new Error('interrupted'));
+});
+const flush = (stream) => new Promise((resolve) => stream.write('', () => resolve()));
+const code = await run(process.argv.slice(2), { stdout: process.stdout, stderr: process.stderr, stdin: process.stdin, env: process.env }, { signal: controller.signal });
+await Promise.all([flush(process.stdout), flush(process.stderr)]);
+process.exit(code);

package/dist/commands.d.ts

@@ -0,0 +1,27 @@
+import type { RunResult, Shardflux, Workspace } from '@shardflux/sdk';
+import type { Values } from './args.js';
+export interface Writer {
+    write(chunk: string | Uint8Array): boolean;
+}
+export interface Io {
+    stdout: Writer;
+    stderr: Writer;
+    stdin: AsyncIterable<Buffer | string> & {
+        isTTY?: boolean;
+    };
+    env: Record<string, string | undefined>;
+}
+export interface Ctx {
+    io: Io;
+    json: boolean;
+    apiUrl: string;
+    agentLabel: string;
+    signal: AbortSignal;
+    cloud(): Shardflux;
+}
+export type Handler = (ctx: Ctx, values: Values, positionals: string[]) => Promise<number>;
+/** `<id|key>`: a UUID is tried as an id first; anything else (or an unknown UUID) as an exact workspace key. */
+export declare function resolveWorkspace(ctx: Ctx, ref: string): Promise<Workspace>;
+/** The exit code `shard exec` returns for a finished command. */
+export declare function execExitCode(r: Pick<RunResult, 'exitCode' | 'termSignal' | 'timedOut'>): number;
+export declare const HANDLERS: Record<string, Handler>;