@onesi/genesis-cli 0.0.1-stage → 0.2.0

package/dist/hives-marketplace.js

@@ -0,0 +1,29 @@
+import { Option } from 'commander';
+import { readFunctionJson } from './function-input.js';
+function number(value) { if (value === undefined)
+    return undefined; if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)))
+    throw new Error('Invalid page option.'); return Number(value); }
+/** Environment values belong in a bounded private JSON file, never command-line options. */
+export function registerHivesMarketplace(hives, deps) {
+    const m = hives.command('marketplace').description('Existing Hives packages, publication and persisted installations');
+    const output = (data) => deps.emit(data, () => JSON.stringify(data, null, 2));
+    const read = deps.readRequest ?? readFunctionJson;
+    const api = async () => (await deps.client()).hives.marketplace;
+    m.command('list <project_id>').option('--query <value>').option('--category <value>').option('--free-only').option('--verified-only')
+        .addOption(new Option('--sort <field>').choices(['name', 'installs', 'stars', 'created', 'updated']))
+        .addOption(new Option('--order <direction>').choices(['asc', 'desc'])).option('--page <number>').option('--page-size <number>')
+        .action(async (project, o) => output(await (await api()).list(project, { q: o.query, category: o.category, free_only: o.freeOnly, verified_only: o.verifiedOnly, sort: o.sort, order: o.order, page: number(o.page), page_size: number(o.pageSize) })));
+    m.command('get <project_id> <slug>').option('--version <semver>').action(async (project, slug, o) => output(await (await api()).get(project, slug, { version: o.version })));
+    m.command('versions <project_id> <slug>').option('--page <number>').option('--page-size <number>').action(async (project, slug, o) => output(await (await api()).versions(project, slug, { page: number(o.page), page_size: number(o.pageSize) })));
+    for (const action of ['categories', 'featured'])
+        m.command(`${action} <project_id>`).action(async (project) => output(await (await api())[action](project)));
+    m.command('publish <project_id>').requiredOption('--request-file <path>', 'JSON publication with an owned uploaded module_hash and immutable version')
+        .action(async (project, o) => output(await (await api()).publish(project, await read(o.requestFile, 512 * 1024))));
+    for (const action of ['install', 'update'])
+        m.command(`${action} <project_id> <slug>`).requiredOption('--request-file <path>', 'JSON version and env_overrides; use {} for defaults')
+            .action(async (project, slug, o) => output(await (await api())[action](project, slug, await read(o.requestFile, 512 * 1024))));
+    m.command('installed <project_id>').option('--page <number>').option('--page-size <number>').action(async (project, o) => output(await (await api()).installed(project, { page: number(o.page), page_size: number(o.pageSize) })));
+    m.command('installation <project_id> <installation_id>').action(async (project, id) => output(await (await api()).getInstallation(project, id)));
+    for (const action of ['reconcile', 'uninstall'])
+        m.command(`${action} <project_id> <installation_id>`).action(async (project, id) => output(await (await api())[action](project, id)));
+}

package/dist/hives-node-transport.d.ts

@@ -0,0 +1,6 @@
+import { type GenesisOptions } from '@onesi/genesis';
+export declare function closeHivesNodeTransport(): Promise<void>;
+export declare function hivesOperationBudget(id: string): number;
+/** Hives leaf transport. Caller fetch overrides stay authoritative; only native
+ * global fetch gets our Agent. Every operation retains an overall body deadline. */
+export declare function createHivesNodeTransport(opts: GenesisOptions, callerSignal?: AbortSignal): typeof fetch;

package/dist/hives-node-transport.js

@@ -0,0 +1,150 @@
+import { Agent } from 'undici';
+import { Genesis, operationTable } from '@onesi/genesis';
+// Node's native fetch accepts a compatible per-request dispatcher. Never change
+// the global dispatcher or the portable SDK: other products retain their transport.
+const agentOptions = { headersTimeout: 340_000, bodyTimeout: 340_000, connect: { timeout: 5_000 }, connections: 4, pipelining: 1 };
+let agent;
+const nativeAgent = () => agent ??= new Agent(agentOptions);
+export async function closeHivesNodeTransport() {
+    const current = agent;
+    agent = undefined;
+    await current?.destroy();
+}
+export function hivesOperationBudget(id) {
+    if (['hives_list_buckets', 'hives_create_bucket', 'hives_get_bucket', 'hives_delete_bucket', 'hives_list_objects', 'hives_upload_object', 'hives_upload_object_by_key', 'hives_delete_object', 'hives_delete_object_by_key', 'hives_download_object_by_key', 'hives_get_cors_config', 'hives_set_cors_config', 'hives_generate_presigned_url', 'hives_reconcile'].includes(id))
+        return 100_000;
+    if (id === 'hives_cancel_deployment' || id === 'hives_delete_deployment' || id === 'hives_stop_deployment')
+        return 330_000;
+    // A live SSE subscription is bounded by its caller's window or --follow limit (at most 300 s).
+    if (id === 'hives_stream_logs')
+        return 330_000;
+    if (['hives_create_deployment', 'hives_upload_deployment', 'hives_invoke_deployment', 'hives_invoke_function', 'hives_invoke_function_async'].includes(id))
+        return 40_000;
+    if (['hives_create_function', 'hives_update_function', 'hives_delete_function'].includes(id))
+        return 100_000;
+    return 20_000;
+}
+const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const templatePattern = (value) => new RegExp('^' + value.split(/(\{[^}]+\})/).map((part) => part.startsWith('{') ? '[^/]+' : escape(part)).join('') + '$');
+/** Hives leaf transport. Caller fetch overrides stay authoritative; only native
+ * global fetch gets our Agent. Every operation retains an overall body deadline. */
+export function createHivesNodeTransport(opts, callerSignal) {
+    const supplied = opts.fetch ?? globalThis.fetch;
+    const underlying = supplied.bind(globalThis);
+    const useNative = supplied === globalThis.fetch;
+    const resolver = new Genesis(opts);
+    const routes = Object.entries(operationTable)
+        .filter(([, op]) => op.service === 'hives' && !op.internal)
+        .flatMap(([id, op]) => {
+        const direct = resolver.routing === 'direct';
+        let base;
+        try {
+            base = new URL(direct ? (opts.upstreams?.hives ?? op.upstream.base) : resolver.baseUrl);
+        }
+        catch {
+            throw new Error('Invalid Hives service address.');
+        }
+        const path = direct ? op.upstream.path : op.path;
+        const prefix = base.pathname.replace(/\/+$/, '');
+        const paths = [path];
+        if (!direct && path.startsWith('/v1/hives/'))
+            paths.push(path.replace('/v1/hives/', '/hives/v1/'));
+        return paths.map((p) => ({ id, origin: base.origin, method: direct ? op.upstream.method : op.method, pattern: templatePattern(prefix + p) }));
+    });
+    return (async (input, init = {}) => {
+        let url;
+        try {
+            url = new URL(input instanceof Request ? input.url : String(input));
+        }
+        catch {
+            throw new Error('Invalid Hives request address.');
+        }
+        const method = (init.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
+        const route = routes.find((entry) => entry.origin === url.origin && entry.method === method && entry.pattern.test(url.pathname));
+        if (!route)
+            return underlying(input, init);
+        const controller = new AbortController();
+        let message = 'Hives transport failed. Refresh the resource and retry.';
+        const safeError = () => new Error(message);
+        const signals = [...new Set([callerSignal, init.signal, input instanceof Request ? input.signal : undefined].filter((signal) => !!signal))];
+        const canceled = () => {
+            message = 'Hives request canceled before completion. Refresh the resource before retrying.';
+            controller.abort();
+        };
+        for (const signal of signals)
+            signal.addEventListener('abort', canceled, { once: true });
+        const timer = setTimeout(() => {
+            message = 'Hives request deadline exceeded. Refresh the resource before retrying.';
+            controller.abort();
+        }, hivesOperationBudget(route.id));
+        timer.unref();
+        let abortReject = () => { };
+        let reader;
+        let bodyController;
+        const aborted = () => {
+            abortReject(safeError());
+            bodyController?.error(safeError());
+            void reader?.cancel().catch(() => { });
+            cleanup();
+        };
+        controller.signal.addEventListener('abort', aborted, { once: true });
+        const abortPromise = new Promise((_, reject) => { abortReject = reject; });
+        void abortPromise.catch(() => { });
+        const cleanup = () => {
+            clearTimeout(timer);
+            for (const signal of signals)
+                signal.removeEventListener('abort', canceled);
+            controller.signal.removeEventListener('abort', aborted);
+        };
+        if (signals.some((signal) => signal.aborted))
+            canceled();
+        try {
+            if (controller.signal.aborted)
+                throw safeError();
+            const requestInit = {
+                ...init, signal: controller.signal, cache: 'no-store',
+                redirect: init.redirect === 'manual' ? 'manual' : 'error',
+                ...(useNative ? { dispatcher: nativeAgent() } : {}),
+            };
+            const pending = underlying(input, requestInit);
+            // A caller transport may ignore AbortSignal. Reject on our budget anyway,
+            // and discard any late response rather than presenting an acknowledgement.
+            void pending.then((response) => { if (controller.signal.aborted)
+                void response.body?.cancel().catch(() => { }); }, () => { });
+            const response = await Promise.race([pending, abortPromise]);
+            if (controller.signal.aborted)
+                throw safeError();
+            if (!response.body) {
+                cleanup();
+                return response;
+            }
+            reader = response.body.getReader();
+            const body = new ReadableStream({
+                start(value) { bodyController = value; },
+                async pull(value) {
+                    try {
+                        const next = await reader.read();
+                        if (controller.signal.aborted)
+                            return;
+                        if (next.done) {
+                            cleanup();
+                            value.close();
+                        }
+                        else
+                            value.enqueue(next.value);
+                    }
+                    catch {
+                        cleanup();
+                        value.error(safeError());
+                    }
+                },
+                async cancel() { cleanup(); await reader.cancel().catch(() => { }); },
+            });
+            return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+        }
+        catch {
+            cleanup();
+            throw safeError();
+        }
+    });
+}

package/dist/hives-operations.d.ts

@@ -0,0 +1,10 @@
+import { Command } from 'commander';
+import type { Genesis } from '@onesi/genesis';
+type Deps = {
+    client: () => Promise<Genesis>;
+    emit: (data: unknown, pretty: () => string) => void;
+    readRequest?: (path: string, limit: number) => Promise<Record<string, unknown>>;
+    line?: (text: string) => void;
+};
+export declare function registerHivesOperations(hives: Command, deps: Deps): void;
+export {};

package/dist/hives-operations.js

@@ -0,0 +1,63 @@
+import { registerHivesResources } from './hives-resources.js';
+import { registerHivesPlatform } from './hives-platform.js';
+import { Option } from 'commander';
+import { readFunctionJson } from './function-input.js';
+function metricsOptions(command) {
+    return command.option('--start <time>', 'inclusive UTC timestamp').option('--end <time>', 'exclusive UTC timestamp')
+        .addOption(new Option('--resolution <value>', 'time bucket').choices(['minute', 'fiveminutes', 'fifteenminutes', 'hour', 'day']))
+        .addOption(new Option('--aggregation <value>', 'supported aggregation').choices(['sum', 'avg', 'min', 'max', 'count', 'p50', 'p90', 'p95', 'p99']));
+}
+const integer = (value, name, max) => {
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < 1 || Number(value) > max) {
+        throw new Error(`${name} must be an integer from 1 to ${max}.`);
+    }
+    return Number(value);
+};
+const paging = (command) => command.option('--page <number>').option('--per-page <number>');
+const pagination = (o) => ({ page: integer(o.page, '--page', 10000), per_page: integer(o.perPage, '--per-page', 100) });
+export function registerHivesOperations(hives, deps) {
+    registerHivesResources(hives, deps);
+    registerHivesPlatform(hives, { client: deps.client, emit: deps.emit, line: deps.line });
+    const output = (data) => deps.emit(data, () => JSON.stringify(data, null, 2));
+    const read = deps.readRequest ?? readFunctionJson;
+    const settings = hives.command('settings').description('Stored project preferences and actual engine capabilities');
+    settings.command('get <project_id>').action(async (project) => output(await (await deps.client()).hives.settings.get(project)));
+    settings.command('update <project_id>').requiredOption('--request-file <path>', 'JSON settings patch')
+        .action(async (project, o) => output(await (await deps.client()).hives.settings.update(project, await read(o.requestFile, 64 * 1024))));
+    const crons = hives.command('crons').description('Waggle schedules and persisted run outcomes');
+    paging(crons.command('list <project_id>')).action(async (project, o) => output(await (await deps.client()).hives.crons.list(project, pagination(o))));
+    crons.command('get <project_id> <cron_id>').action(async (project, cron) => output(await (await deps.client()).hives.crons.get(project, cron)));
+    crons.command('create <project_id>').requiredOption('--request-file <path>', 'JSON name, schedule, handler, timezone and enabled preference')
+        .action(async (project, o) => {
+        const body = await read(o.requestFile, 64 * 1024);
+        if (typeof body.name !== 'string' || typeof body.schedule !== 'string' || typeof body.handler !== 'string')
+            throw new Error('Cron JSON requires name, schedule and handler strings.');
+        output(await (await deps.client()).hives.crons.create(project, { ...body, name: body.name, schedule: body.schedule, handler: body.handler }));
+    });
+    crons.command('update <project_id> <cron_id>').requiredOption('--request-file <path>', 'JSON schedule patch')
+        .action(async (project, cron, o) => output(await (await deps.client()).hives.crons.update(project, cron, await read(o.requestFile, 64 * 1024))));
+    for (const action of ['delete', 'pause', 'resume', 'trigger']) {
+        crons.command(`${action} <project_id> <cron_id>`)
+            .description(action === 'trigger' ? 'Admit one run; inspect runs for completion. Does not retry.' : `${action} an owned schedule`)
+            .action(async (project, cron) => output(await (await deps.client()).hives.crons[action](project, cron)));
+    }
+    paging(crons.command('runs <project_id> <cron_id>')).addOption(new Option('--status <state>', 'persisted run status').choices(['pending', 'running', 'success', 'failed', 'timeout', 'cancelled']))
+        .option('--since <time>').option('--until <time>')
+        .action(async (project, cron, o) => output(await (await deps.client()).hives.crons.runs(project, cron, { ...pagination(o), status: o.status, since: o.since, until: o.until })));
+    const metrics = hives.command('metrics').description('Retained completed API observations; unavailable measurements remain null');
+    for (const kind of ['project', 'requests', 'latency', 'errors', 'resources']) {
+        metricsOptions(metrics.command(`${kind} <project_id>`))
+            .action(async (project, q) => output(await (await deps.client()).hives.metrics[kind](project, q)));
+    }
+    metrics.command('dashboard <project_id>').addOption(new Option('--period <value>').choices(['1h', '24h', '7d', '30d']))
+        .action(async (project, q) => output(await (await deps.client()).hives.metrics.dashboard(project, q)));
+    for (const kind of ['function', 'invocations']) {
+        metricsOptions(metrics.command(`${kind} <project_id> <function_id>`))
+            .action(async (project, id, q) => output(await (await deps.client()).hives.metrics[kind](project, id, q)));
+    }
+    metricsOptions(metrics.command('deployment <project_id> <deployment_id>'))
+        .action(async (project, id, q) => output(await (await deps.client()).hives.metrics.deployment(project, id, q)));
+    metrics.command('realtime <project_id>').action(async (project) => output(await (await deps.client()).hives.metrics.realtime(project)));
+}

package/dist/hives-platform.d.ts

@@ -0,0 +1,13 @@
+import { Command } from 'commander';
+import type { Genesis } from '@onesi/genesis';
+type Deps = {
+    client: () => Promise<Genesis>;
+    emit: (data: unknown, pretty: () => string) => void;
+    /** Print one line as it arrives (live log streams). */
+    line?: (text: string) => void;
+    readText?: (path: string, limit: number) => Promise<Uint8Array>;
+    writeNew?: (path: string, bytes: Uint8Array) => Promise<void>;
+};
+/** Hives logs (query and live SSE), custom domains, regions, the Hives identity, Hives fleets and remote sessions/SFTP. */
+export declare function registerHivesPlatform(hives: Command, deps: Deps): void;
+export {};

package/dist/hives-platform.js

@@ -0,0 +1,133 @@
+import { readFile, stat, writeFile } from 'node:fs/promises';
+const SFTP_BYTES = 10 * 1024 * 1024;
+const MANIFEST_BYTES = 64 * 1024;
+function integer(value, name, min, max) {
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < min || Number(value) > max) {
+        throw new Error(`${name} must be an integer from ${min} to ${max}.`);
+    }
+    return Number(value);
+}
+async function readBounded(path, limit) {
+    const metadata = await stat(path);
+    if (!metadata.isFile() || metadata.size > limit)
+        throw new Error(`Choose a regular file of at most ${limit} bytes.`);
+    const bytes = await readFile(path);
+    if (bytes.byteLength > limit)
+        throw new Error(`File exceeds ${limit} bytes.`);
+    return Uint8Array.from(bytes);
+}
+/** Hives logs (query and live SSE), custom domains, regions, the Hives identity, Hives fleets and remote sessions/SFTP. */
+export function registerHivesPlatform(hives, deps) {
+    const output = (data) => deps.emit(data, () => JSON.stringify(data, null, 2));
+    const line = deps.line ?? ((text) => process.stdout.write(text + '\n'));
+    const read = deps.readText ?? readBounded;
+    const writeNew = deps.writeNew ?? ((path, bytes) => writeFile(path, bytes, { flag: 'wx', mode: 0o600 }));
+    const api = async () => (await deps.client()).hives;
+    const logs = hives.command('logs').description('Project logs: retained query and live Server-Sent Events');
+    logs.command('query <project_id>').option('--level <level>').option('--source <source>').option('--search <text>')
+        .option('--start <time>', 'inclusive UTC timestamp').option('--end <time>', 'exclusive UTC timestamp').option('--request-id <id>')
+        .option('--page <number>').option('--per-page <number>')
+        .action(async (project, o) => output(await (await api()).logs.query(project, { level: o.level, source: o.source, search: o.search, start: o.start, end: o.end, request_id: o.requestId,
+        page: integer(o.page, '--page', 1, 10000), per_page: integer(o.perPage, '--per-page', 1, 100) })));
+    logs.command('stream <project_id>').description('Live events. Bounded by --max-events and --seconds; --follow prints each event as it arrives')
+        .option('--level <level>').option('--source <source>').option('--heartbeat', 'ask the server for heartbeat events')
+        .option('--max-events <number>', 'stop after this many events (1-10000; default 100, unlimited with --follow)')
+        .option('--seconds <number>', 'stop after this many seconds (1-300; default 10, or 300 with --follow)')
+        .option('--follow', 'print one JSON event per line as it arrives')
+        .action(async (project, o) => {
+        const q = { level: o.level, source: o.source, ...(o.heartbeat ? { heartbeat: true } : {}) };
+        const maxEvents = integer(o.maxEvents, '--max-events', 1, 10000);
+        const seconds = integer(o.seconds, '--seconds', 1, 300) ?? (o.follow ? 300 : 10);
+        const client = await api();
+        if (!o.follow) {
+            output(await client.logs.window(project, q, { maxEvents: maxEvents ?? 100, seconds }));
+            return;
+        }
+        const stop = new AbortController();
+        const timer = setTimeout(() => stop.abort(), seconds * 1000);
+        let count = 0;
+        try {
+            for await (const event of client.logs.stream(project, q, { signal: stop.signal })) {
+                line(JSON.stringify(event));
+                count++;
+                if (maxEvents !== undefined && count >= maxEvents)
+                    break;
+            }
+        }
+        catch (error) {
+            // Reaching --seconds closes the connection; that is the bounded end, not a failure.
+            if (!stop.signal.aborted)
+                throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    });
+    const domains = hives.command('domains').description('Custom domains for a project: add, DNS verification and certificate provisioning');
+    domains.command('list <project_id>').option('--page <number>').option('--per-page <number>')
+        .action(async (project, o) => output(await (await api()).domains.list(project, { page: integer(o.page, '--page', 1, 10000), per_page: integer(o.perPage, '--per-page', 1, 100) })));
+    domains.command('add <project_id> <domain>').action(async (project, domain) => output(await (await api()).domains.add(project, { domain })));
+    domains.command('verify <project_id> <domain_id>').description('Check the DNS verification record now')
+        .action(async (project, id) => output(await (await api()).domains.verify(project, id)));
+    domains.command('provision-ssl <project_id> <domain_id>').description('Request a certificate for a verified domain')
+        .action(async (project, id) => output(await (await api()).domains.provisionSsl(project, id)));
+    hives.command('regions').description('Regions Hives can place projects in').command('list')
+        .action(async () => output(await (await api()).regions.list()));
+    hives.command('auth').description('The identity Hives sees for this credential').command('me')
+        .action(async () => output(await (await api()).auth.me()));
+    const fleets = hives.command('fleets').description('Hives fleets deployed from a map-fleet.toml manifest');
+    fleets.command('list').action(async () => output(await (await api()).fleets.list()));
+    fleets.command('deploy').requiredOption('--manifest-file <path>', 'map-fleet.toml manifest (at most 64 KiB)')
+        .action(async (o) => {
+        const manifestToml = new TextDecoder('utf-8', { fatal: true }).decode(await read(o.manifestFile, MANIFEST_BYTES));
+        output(await (await api()).fleets.deploy({ manifestToml }));
+    });
+    fleets.command('status <fleet_id>').action(async (id) => output(await (await api()).fleets.status(id)));
+    fleets.command('teardown <fleet_id>').action(async (id) => {
+        const result = await (await api()).fleets.teardown(id);
+        output(result ?? { torn_down: id });
+    });
+    const remote = hives.command('remote').description('Remote SSH, terminal and debug sessions, and SFTP, for a project target');
+    const sessions = remote.command('sessions').description('Open remote sessions');
+    sessions.command('list <project_id>').option('--type <session_type>', 'ssh, terminal or debug').option('--target <target_id>')
+        .action(async (project, o) => output(await (await api()).remote.sessions.list(project, { session_type: o.type, target_id: o.target })));
+    sessions.command('close <project_id> <session_id>').action(async (project, id) => output(await (await api()).remote.sessions.close(project, id)));
+    remote.command('ssh <project_id> <target_id>').requiredOption('--public-key-file <path>', 'your SSH public key (never a private key)')
+        .option('--ttl-secs <seconds>', 'session lifetime (60-86400; default 3600)')
+        .action(async (project, target, o) => {
+        const public_key = new TextDecoder('utf-8', { fatal: true }).decode(await read(o.publicKeyFile, 16 * 1024)).trim();
+        if (/PRIVATE KEY/.test(public_key) || !/^(ssh-|ecdsa-|sk-)/.test(public_key))
+            throw new Error('Provide an OpenSSH public key file (for example ~/.ssh/id_ed25519.pub).');
+        output(await (await api()).remote.ssh(project, { target_id: target, public_key, ttl_secs: integer(o.ttlSecs, '--ttl-secs', 60, 86400) }));
+    });
+    remote.command('terminal <project_id> <target_id>').option('--shell <path>').option('--cols <number>').option('--rows <number>')
+        .action(async (project, target, o) => output(await (await api()).remote.terminal(project, { target_id: target, shell: o.shell, cols: integer(o.cols, '--cols', 1, 1000), rows: integer(o.rows, '--rows', 1, 1000) })));
+    remote.command('debug <project_id> <target_id>').option('--protocol <protocol>', 'dap or chrome-devtools')
+        .action(async (project, target, o) => output(await (await api()).remote.debug(project, { target_id: target, protocol: o.protocol })));
+    const sftp = remote.command('sftp').description('Files on a remote target');
+    sftp.command('ls <project_id> <target_id>').option('--path <path>')
+        .action(async (project, target, o) => output(await (await api()).remote.sftp.list(project, target, { path: o.path })));
+    sftp.command('read <project_id> <target_id> <path>').option('--output-file <path>', 'write the decoded content_base64 to a new private file')
+        .action(async (project, target, path, o) => {
+        const result = await (await api()).remote.sftp.read(project, target, path);
+        if (!o.outputFile) {
+            output(result);
+            return;
+        }
+        const encoded = result?.content_base64;
+        if (typeof encoded !== 'string' || encoded.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded))
+            throw new Error('Hives returned no valid content_base64 for this file.');
+        const decoded = Buffer.from(encoded, 'base64');
+        if (decoded.toString('base64') !== encoded)
+            throw new Error('Hives returned no valid content_base64 for this file.');
+        const bytes = Uint8Array.from(decoded);
+        await writeNew(o.outputFile, bytes);
+        output({ saved: true, bytes: bytes.byteLength });
+    });
+    sftp.command('write <project_id> <target_id> <path>').requiredOption('--file <local_path>', 'local file to upload (at most 10 MiB)')
+        .action(async (project, target, path, o) => output(await (await api()).remote.sftp.write(project, target, { path, content_base64: Buffer.from(await read(o.file, SFTP_BYTES)).toString('base64') })));
+    sftp.command('delete <project_id> <target_id> <path>')
+        .action(async (project, target, path) => output(await (await api()).remote.sftp.delete(project, target, { path })));
+}

package/dist/hives-resources.d.ts

@@ -0,0 +1,9 @@
+import { Command } from 'commander';
+import type { Genesis } from '@onesi/genesis';
+type Deps = {
+    client: () => Promise<Genesis>;
+    emit: (data: unknown, pretty: () => string) => void;
+    readRequest?: (path: string, limit: number) => Promise<Record<string, unknown>>;
+};
+export declare function registerHivesResources(hives: Command, deps: Deps): void;
+export {};

package/dist/hives-resources.js

@@ -0,0 +1,94 @@
+import { registerHivesMarketplace } from './hives-marketplace.js';
+import { createReadStream } from 'node:fs';
+import { stat, writeFile } from 'node:fs/promises';
+import { readFunctionJson } from './function-input.js';
+async function bytes(path) {
+    const metadata = await stat(path);
+    if (!metadata.isFile() || metadata.size > 10 * 1024 * 1024)
+        throw new Error('Choose a regular file of at most 10 MiB.');
+    const stream = createReadStream(path);
+    const chunks = [];
+    let total = 0;
+    try {
+        for await (const chunk of stream) {
+            const value = Buffer.from(chunk);
+            total += value.byteLength;
+            if (total > 10 * 1024 * 1024)
+                throw new Error('Object file exceeds 10 MiB.');
+            chunks.push(value);
+        }
+    }
+    finally {
+        stream.destroy();
+    }
+    return Uint8Array.from(Buffer.concat(chunks, total));
+}
+function number(value, min, max) { if (value === undefined)
+    return undefined; if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < min || Number(value) > max)
+    throw new Error('Invalid bounded numeric option.'); return Number(value); }
+export function registerHivesResources(hives, deps) {
+    registerHivesMarketplace(hives, deps);
+    const output = (data) => deps.emit(data, () => JSON.stringify(data, null, 2));
+    const read = deps.readRequest ?? readFunctionJson;
+    const cells = hives.command('cells').description('Owned GCS buckets and objects; uncertain mutations require readback/reconciliation');
+    cells.command('list <project_id>').option('--page <number>').option('--per-page <number>').action(async (project, o) => output(await (await deps.client()).hives.cells.list(project, { page: number(o.page, 1, 10000), per_page: number(o.perPage, 1, 100) })));
+    cells.command('get <project_id> <bucket_id>').action(async (project, id) => output(await (await deps.client()).hives.cells.get(project, id)));
+    cells.command('create <project_id>').requiredOption('--request-file <path>', 'JSON name, region, visibility and CORS').action(async (project, o) => output(await (await deps.client()).hives.cells.create(project, await read(o.requestFile, 512 * 1024))));
+    for (const action of ['remove', 'reconcile'])
+        cells.command(`${action} <project_id> <bucket_id>`).action(async (project, id) => output(await (await deps.client()).hives.cells[action](project, id)));
+    const cors = cells.command('cors');
+    cors.command('get <project_id> <bucket_id>').action(async (project, id) => output(await (await deps.client()).hives.cells.cors.get(project, id)));
+    cors.command('set <project_id> <bucket_id>').requiredOption('--request-file <path>', 'JSON object with rules array').action(async (project, id, o) => { const body = await read(o.requestFile, 512 * 1024); if (!Array.isArray(body.rules))
+        throw new Error('CORS JSON requires rules.'); output(await (await deps.client()).hives.cells.cors.set(project, id, body.rules)); });
+    const objects = cells.command('objects');
+    objects.command('list <project_id> <bucket_id>').option('--prefix <value>').option('--delimiter <value>').option('--continuation-token <value>').option('--max-keys <number>').action(async (project, id, o) => output(await (await deps.client()).hives.cells.objects.list(project, id, { prefix: o.prefix, delimiter: o.delimiter, continuation_token: o.continuationToken, max_keys: number(o.maxKeys, 1, 1000) })));
+    for (const action of ['put', 'put-flat'])
+        objects.command(`${action} <project_id> <bucket_id> <key>`).requiredOption('--file <path>', 'Exact binary bytes up to 10 MiB').option('--content-type <value>').action(async (project, id, key, o) => { const client = await deps.client(); output(await client.hives.cells.objects[action === 'put' ? 'put' : 'putFlat'](project, id, key, await bytes(o.file), { content_type: o.contentType })); });
+    for (const action of ['remove', 'remove-flat'])
+        objects.command(`${action} <project_id> <bucket_id> <key>`).action(async (project, id, key) => { await (await deps.client()).hives.cells.objects[action === 'remove' ? 'remove' : 'removeFlat'](project, id, key); output({ acknowledged: true }); });
+    objects.command('download <project_id> <bucket_id> <key>').requiredOption('--output-file <path>', 'Create a new file; existing files are never overwritten').action(async (project, id, key, o) => { const response = await (await deps.client()).hives.cells.objects.download(project, id, key); const data = new Uint8Array(await response.arrayBuffer()); await writeFile(o.outputFile, data, { flag: 'wx', mode: 0o600 }); output({ saved: true, bytes: data.byteLength }); });
+    cells.command('presign <project_id> <bucket_id>').requiredOption('--request-file <path>', 'Explicit GET/PUT capability request; PUT requires exact content_length').action(async (project, id, o) => output(await (await deps.client()).hives.cells.presign(project, id, await read(o.requestFile, 64 * 1024))));
+    const queues = hives.command('queues').description('Buzz durable messages and possessed temporary delivery receipts');
+    const consumer = queues.command('consumer').description('Persisted standard-queue function binding; inspect state after an unknown mutation outcome');
+    for (const action of ['get', 'remove'])
+        consumer.command(`${action} <project_id> <queue_id>`).action(async (project, id) => output(await (await deps.client()).hives.queues.consumer[action](project, id)));
+    consumer.command('configure <project_id> <queue_id>').requiredOption('--request-file <path>', 'Exact existing queue delivery settings and owned active function').action(async (project, id, o) => output(await (await deps.client()).hives.queues.consumer.configure(project, id, await read(o.requestFile, 4096))));
+    for (const action of ['list'])
+        queues.command(`${action} <project_id>`).action(async (project) => output(await (await deps.client()).hives.queues[action](project)));
+    for (const action of ['get', 'stats', 'consumers', 'pause', 'resume', 'purge', 'remove', 'dead-letter-stats', 'purge-dead-letters']) {
+        const names = { 'dead-letter-stats': 'deadLetterStats', 'purge-dead-letters': 'purgeDeadLetters' };
+        queues.command(`${action} <project_id> <queue_id>`).action(async (project, id) => { const client = await deps.client(); const method = action in names ? names[action] : action; output(await client.hives.queues[method](project, id)); });
+    }
+    queues.command('create <project_id>').requiredOption('--request-file <path>', 'Queue name, standard/dead_letter/fifo type and optional delivery settings').action(async (project, o) => output(await (await deps.client()).hives.queues.create(project, await read(o.requestFile, 512 * 1024))));
+    queues.command('configure <project_id> <queue_id>').requiredOption('--request-file <path>').action(async (project, id, o) => output(await (await deps.client()).hives.queues.configure(project, id, await read(o.requestFile, 512 * 1024))));
+    queues.command('send <project_id> <queue_id>').requiredOption('--request-file <path>', 'Exactly body or body_base64; decoded body 256 KiB. FIFO retains its separate message_group_id and deduplication_id contract').option('--idempotency-key <key>', 'Persist the original key for a funded standard-queue send; never change it after uncertainty').action(async (project, id, o) => output(await (await deps.client()).hives.queues.send(project, id, await read(o.requestFile, 512 * 1024), { idempotencyKey: o.idempotencyKey })));
+    queues.command('operations').description('Read original queue operation status without sending another message').command('get <project_id> <queue_id> <operation_id>').action(async (project, id, operation) => output(await (await deps.client()).hives.queues.operations.get(project, id, operation)));
+    queues.command('receive <project_id> <queue_id>').option('--max-messages <number>').option('--wait-seconds <number>').action(async (project, id, o) => output(await (await deps.client()).hives.queues.receive(project, id, { maxMessages: number(o.maxMessages, 1, 10), waitSeconds: number(o.waitSeconds, 0, 10) })));
+    for (const action of ['ack', 'nack'])
+        queues.command(`${action} <project_id> <queue_id> <message_id>`).requiredOption('--receipt-file <path>', 'JSON receiptHandle; not a credential/header/query').action(async (project, id, message, o) => { const body = await read(o.receiptFile, 4096); if (typeof body.receiptHandle !== 'string')
+            throw new Error('Receipt JSON requires receiptHandle.'); output(await (await deps.client()).hives.queues[action](project, id, message, body.receiptHandle)); });
+    queues.command('dead-letters <project_id> <queue_id>').option('--limit <number>').option('--offset <number>').action(async (project, id, o) => output(await (await deps.client()).hives.queues.deadLetters(project, id, { limit: number(o.limit, 1, 10), offset: number(o.offset, 0, 8192) })));
+    for (const action of ['replay', 'delete-dead-letter'])
+        queues.command(`${action} <project_id> <queue_id> <message_id>`).action(async (project, id, message) => output(await (await deps.client()).hives.queues[action === 'replay' ? 'replay' : 'deleteDeadLetter'](project, id, message)));
+    const topics = hives.command('topics').description('Owned Buzz topics; publication persists deliveries, never retries an unknown outcome');
+    topics.command('list <project_id>').action(async (project) => output(await (await deps.client()).hives.topics.list(project)));
+    for (const action of ['get', 'remove'])
+        topics.command(`${action} <project_id> <topic_id>`).action(async (project, id) => output(await (await deps.client()).hives.topics[action](project, id)));
+    topics.command('create <project_id>').requiredOption('--request-file <path>', 'JSON topic name').action(async (project, o) => output(await (await deps.client()).hives.topics.create(project, await read(o.requestFile, 4096))));
+    topics.command('publish <project_id> <topic_id>').requiredOption('--request-file <path>', 'Exactly body or body_base64 plus optional string attributes; no automatic retry').action(async (project, id, o) => output(await (await deps.client()).hives.topics.publish(project, id, await read(o.requestFile, 512 * 1024))));
+    const subscriptions = topics.command('subscriptions').description('Same-project standard queue destinations; removing a subscription retains queued messages');
+    subscriptions.command('list <project_id> <topic_id>').action(async (project, id) => output(await (await deps.client()).hives.topics.subscriptions.list(project, id)));
+    subscriptions.command('add <project_id> <topic_id> <queue_id>').action(async (project, id, queue) => output(await (await deps.client()).hives.topics.subscriptions.add(project, id, queue)));
+    subscriptions.command('remove <project_id> <topic_id> <subscription_id>').action(async (project, id, subscription) => output(await (await deps.client()).hives.topics.subscriptions.remove(project, id, subscription)));
+    const volumes = hives.command('volumes').description('Persistent local storage; refresh saved state after an uncertain acknowledgement');
+    volumes.command('list <project_id>').option('--page <number>').option('--per-page <number>').action(async (project, o) => output(await (await deps.client()).hives.volumes.list(project, { page: number(o.page, 1, 10000), per_page: number(o.perPage, 1, 100) })));
+    for (const action of ['get', 'unmount', 'remove'])
+        volumes.command(`${action} <project_id> <volume_id>`).action(async (project, id) => output(await (await deps.client()).hives.volumes[action](project, id)));
+    volumes.command('create <project_id>').requiredOption('--request-file <path>', 'JSON name and size_mib (32–1024); local read_write_once only').action(async (project, o) => output(await (await deps.client()).hives.volumes.create(project, await read(o.requestFile, 4096))));
+    volumes.command('mount <project_id> <volume_id>').requiredOption('--request-file <path>', 'JSON target_id, mount_path and explicit read_only; preserve these values when reconnecting').action(async (project, id, o) => output(await (await deps.client()).hives.volumes.mount(project, id, await read(o.requestFile, 4096))));
+    const runtime = hives.command('runtimes').description('Compiled serving implementation metadata; not available capacity');
+    runtime.command('list').action(async () => output(await (await deps.client()).hives.runtimes.list()));
+    runtime.command('project <project_id>').action(async (project) => output(await (await deps.client()).hives.runtimes.project(project)));
+    runtime.command('get <name>').action(async (name) => output(await (await deps.client()).hives.runtimes.get(name)));
+    runtime.command('select').requiredOption('--wasi <value>').requiredOption('--runner <value>').requiredOption('--artifact <value>').action(async (input) => output(await (await deps.client()).hives.runtimes.select(input)));
+}

package/dist/iam-directory.d.ts

@@ -0,0 +1,15 @@
+import type { Command } from 'commander';
+import type { Genesis } from '@onesi/genesis';
+type Dependencies = {
+    client: () => Promise<Genesis>;
+    orgId: (client: Genesis) => Promise<string>;
+    emit: (data: unknown, pretty: () => string) => void;
+};
+/**
+ * `genesis projects` and `genesis workspaces`: the IAM organization directory of the org you are
+ * signed in to (or --org). IAM accepts only a One account login; API keys get IAM_HUMAN_SESSION_REQUIRED.
+ * Writes need iam:write and owner/admin authority in the organization. The gateway binds the organization
+ * context (Auth organization-context exchange) itself; this CLI sends one request and changes no session or context.
+ */
+export declare function registerIamDirectory(program: Command, dependencies: Dependencies): void;
+export {};

package/dist/iam-directory.js

@@ -0,0 +1,71 @@
+import { randomUUID } from 'node:crypto';
+import { table } from './output.js';
+const KEY = ['--idempotency-key <key>', 'Reuse the key from an uncertain earlier attempt to replay it; otherwise a new one is minted'];
+const rows = (r) => (r?.items ?? []);
+/**
+ * `genesis projects` and `genesis workspaces`: the IAM organization directory of the org you are
+ * signed in to (or --org). IAM accepts only a One account login; API keys get IAM_HUMAN_SESSION_REQUIRED.
+ * Writes need iam:write and owner/admin authority in the organization. The gateway binds the organization
+ * context (Auth organization-context exchange) itself; this CLI sends one request and changes no session or context.
+ */
+export function registerIamDirectory(program, dependencies) {
+    const { client, orgId, emit } = dependencies;
+    const scope = async () => { const gen = await client(); return { gen, org: await orgId(gen) }; };
+    const projects = program.command('projects').description('Projects in your organization (One account login; writes need owner or admin)');
+    projects.command('list', { isDefault: true }).action(async () => {
+        const { gen, org } = await scope();
+        const r = await gen.projects.list(org);
+        emit(r, () => table(rows(r), ['id', 'name', 'slug']));
+    });
+    projects.command('get <project_id>').action(async (id) => {
+        const { gen, org } = await scope();
+        const r = await gen.projects.get(org, id);
+        emit(r, () => table([r], ['id', 'name', 'slug', 'organization_id']));
+    });
+    projects.command('create <name>').description('Create a project').requiredOption('--slug <slug>', 'unique within the organization').option(...KEY)
+        .action(async (name, o) => {
+        const { gen, org } = await scope();
+        const r = await gen.projects.create(org, { name, slug: o.slug }, o.idempotencyKey ?? randomUUID());
+        emit(r, () => table([r], ['id', 'name', 'slug']));
+    });
+    projects.command('rename <project_id> <name>').description('Rename a project').option('--slug <slug>', 'also change the slug')
+        .action(async (id, name, o) => {
+        const { gen, org } = await scope();
+        const r = await gen.projects.update(org, id, { name, ...(o.slug ? { slug: o.slug } : {}) });
+        emit(r, () => table([r], ['id', 'name', 'slug']));
+    });
+    projects.command('delete <project_id>').description('Permanently delete a project (refused while workspaces, fleets or grants use it)')
+        .action(async (id) => {
+        const { gen, org } = await scope();
+        await gen.projects.delete(org, id);
+        emit({ deleted: id }, () => `Deleted project ${id}.`);
+    });
+    const workspaces = program.command('workspaces').description('Workspaces in your organization (One account login; writes need owner or admin)');
+    workspaces.command('list', { isDefault: true }).action(async () => {
+        const { gen, org } = await scope();
+        const r = await gen.workspaces.list(org);
+        emit(r, () => table(rows(r), ['id', 'name', 'projectId']));
+    });
+    workspaces.command('get <workspace_id>').action(async (id) => {
+        const { gen, org } = await scope();
+        const r = await gen.workspaces.get(org, id);
+        emit(r, () => table([r], ['id', 'name', 'projectId', 'organizationId']));
+    });
+    workspaces.command('create <name>').description('Create a workspace').option('--project <project_id>', 'the project it belongs to').option(...KEY)
+        .action(async (name, o) => {
+        const { gen, org } = await scope();
+        const r = await gen.workspaces.create(org, { name, ...(o.project ? { project_id: o.project } : {}) }, o.idempotencyKey ?? randomUUID());
+        emit(r, () => table([r], ['id', 'name', 'projectId']));
+    });
+    workspaces.command('rename <workspace_id> <name>').description('Rename a workspace').action(async (id, name) => {
+        const { gen, org } = await scope();
+        const r = await gen.workspaces.rename(org, id, name);
+        emit(r, () => table([r], ['id', 'name', 'projectId']));
+    });
+    workspaces.command('delete <workspace_id>').description('Permanently delete a workspace (refused while fleets or grants use it)')
+        .action(async (id) => {
+        const { gen, org } = await scope();
+        await gen.workspaces.delete(org, id);
+        emit({ deleted: id }, () => `Deleted workspace ${id}.`);
+    });
+}