@platless/axom-cli 0.1.0

package/dist/workstation/protocol/common.js

@@ -0,0 +1,136 @@
+export function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export const isString = (value) => typeof value === 'string';
+export const isBoolean = (value) => typeof value === 'boolean';
+export const isNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+export const isNullableString = (value) => value === null || typeof value === 'string';
+export const isStringArray = (value) => Array.isArray(value) && value.every(isString);
+export const isNullableStringArray = (value) => value === null || isStringArray(value);
+export const isStringRecord = (value) => isObject(value) && Object.values(value).every(isString);
+export function hasRequired(object, fields) {
+    return Object.entries(fields).every(([name, guard]) => Object.hasOwn(object, name) && guard(object[name]));
+}
+export function hasOptional(object, fields) {
+    return Object.entries(fields).every(([name, guard]) => !Object.hasOwn(object, name) || guard(object[name]));
+}
+/** Accepts `true` and nothing else — see {@link BridgeInfo.supportsSteering}. */
+export const isTrueOnly = (value) => value === true;
+export const isNullableBoolean = (value) => value === null || typeof value === 'boolean';
+export function isAuthMethodInfo(value) {
+    return isObject(value)
+        && hasRequired(value, { id: isString, name: isString })
+        && hasOptional(value, { type: isNullableString, description: isNullableString, args: isNullableStringArray });
+}
+export const isNullableAuthMethodInfoArray = (value) => value === null || (Array.isArray(value) && value.every(isAuthMethodInfo));
+export function isBridgeInfo(value) {
+    return isObject(value)
+        && hasRequired(value, { type: isString })
+        && hasOptional(value, {
+            available: isBoolean,
+            version: isNullableString,
+            displayName: isNullableString,
+            description: isNullableString,
+            // Optional for the same reason as the auth fields: absent is "nobody looked". No build
+            // produces these anymore (see `BridgeInfo`'s doc comment), but a guard that rejected them
+            // would turn a frame from an older peer into a decode failure.
+            cliCommand: isNullableString,
+            cliInstalled: isNullableBoolean,
+            adapterInstalled: isNullableBoolean,
+            // Unlike the "unknown vs no" fields above, `null` is a genuine answer here — see
+            // `BridgeInfo.adapterVersion`'s doc comment — so this accepts it the same as any other
+            // nullable string field.
+            adapterVersion: isNullableString,
+            registryVersion: isString,
+            // `true` and nothing else, like `recommended`/`supportsSteering`: see `BridgeInfo.unsupportedPlatform`.
+            unsupportedPlatform: isTrueOnly,
+            // Present only alongside `unsupportedPlatform: true`, but that pairing is a producer-side
+            // convention (see `acpAgents.ts`'s `roster`), not something this guard enforces -- a plain
+            // string is all a peer sending it without the flag is asked to satisfy.
+            platformTriple: isString,
+            // `true` and nothing else, like `supportsSteering`: see `BridgeInfo.recommended`.
+            recommended: isTrueOnly,
+            defaultName: isNullableString,
+            defaultLabel: isNullableString,
+            // Optional on purpose: see BridgeInfo's doc comment — absent is "unknown", and a guard that
+            // demanded these would turn "we have not connected to this agent yet" into a decode failure.
+            authMethods: isNullableAuthMethodInfoArray,
+            authenticated: isNullableBoolean,
+            // `true` and nothing else: like `agent_verified.authenticated`, this field has no `false`.
+            // A peer that sent one would be publishing "we looked and it cannot steer" through a key
+            // whose absence already says exactly that, so refusing it keeps one spelling per fact.
+            supportsSteering: isTrueOnly,
+        });
+}
+export function isBridgeInfoArray(value) {
+    return Array.isArray(value) && value.every(isBridgeInfo);
+}
+/**
+ * The roster entries a peer will actually be able to read, with the rest dropped loudly.
+ *
+ * Takes `unknown[]`, not `BridgeInfo[]`, because that is what it is: the argument's static type is
+ * a claim made by whoever assembled it out of another process's output, and this function exists
+ * precisely for the case where that claim is false.
+ *
+ * Every frame that carries a roster carries it as **optional cargo** — `management_hello`,
+ * `agent_hello`, `external_agents_scan_result` — while the frame itself is load-bearing. A peer
+ * that cannot decode one of those does not lose the roster; it loses the channel. The server's
+ * hello path in particular closes the socket with nothing said (`WorkstationGateway.kt`), so a
+ * single unreadable entry cost a workstation its connection *permanently*: the client rebuilt the
+ * same roster and re-sent it every 30 seconds forever. Degrading the way `agentHeartbeat` degrades
+ * its inventory — drop the cargo, keep the frame — is what bounds that damage to the agent that
+ * caused it.
+ *
+ * The roster's contents come from third-party agent processes over a pipe (see
+ * `toAuthMethodSnapshot` in `acpClient.ts` for how one gets in), so "our types say it is fine" is
+ * not evidence. Round-tripping through JSON before the check, and returning the *parsed* entries,
+ * is what makes the subject here identical to what the peer reads: `JSON.stringify` erases an
+ * `undefined` value, so a field can satisfy every `typeof` test in this process and still arrive
+ * missing. Same reasoning as `outboundAgentFrameRejection`'s round trip.
+ */
+export function bridgesForWire(bridges, frame) {
+    const { kept, dropped } = partitionWireSafeBridges(bridges);
+    if (dropped.length > 0) {
+        console.error(`[wire] ${frame} omits ${dropped.length} unreadable roster ` +
+            `entr${dropped.length === 1 ? 'y' : 'ies'} (${dropped.join(', ')}): ` +
+            'the agent advertised something this wire cannot carry');
+    }
+    return kept;
+}
+function partitionWireSafeBridges(bridges) {
+    let parsed;
+    try {
+        parsed = JSON.parse(JSON.stringify(bridges));
+    }
+    catch (error) {
+        // A roster that cannot be serialized at all still must not cost the channel.
+        return { kept: [], dropped: [`<unserializable roster: ${error instanceof Error ? error.message : String(error)}>`] };
+    }
+    if (!Array.isArray(parsed))
+        return { kept: [], dropped: ['<roster was not an array>'] };
+    const kept = [];
+    const dropped = [];
+    for (const entry of parsed) {
+        if (isBridgeInfo(entry))
+            kept.push(entry);
+        // Named by `type` where there is one: that is the registry agent id, which is what whoever
+        // reads the log has to go and look at. `typeof` rather than `isString` because `ValueGuard`'s
+        // annotation erases the type predicate and would leave `entry.type` as `unknown`.
+        else
+            dropped.push(isObject(entry) && typeof entry.type === 'string' ? entry.type : '<unnamed>');
+    }
+    return { kept, dropped };
+}
+export function decodeChannelFrame(text, discriminators, isValid) {
+    const value = JSON.parse(text);
+    if (!isObject(value)) {
+        throw new TypeError('Channel frame must be a JSON object');
+    }
+    const discriminator = value.t;
+    if (typeof discriminator !== 'string' || !discriminators.has(discriminator)) {
+        throw new TypeError(`Unexpected channel frame discriminator: ${String(discriminator)}`);
+    }
+    if (!isValid(value))
+        throw new TypeError(`Invalid channel frame shape: ${discriminator}`);
+    return value;
+}

package/dist/workstation/protocol/computer.js

@@ -0,0 +1,31 @@
+import { decodeChannelFrame, hasOptional, hasRequired, isBoolean, isNumber, isString, isStringArray, isStringRecord } from './common.js';
+const DISCRIMINATORS = new Set([
+    'computer_hello', 'computer_ready', 'heartbeat', 'heartbeat_ack',
+    'exec_request', 'exec_output', 'exec_exit', 'exec_cancel',
+]);
+function isComputerFrame(value) {
+    switch (value.t) {
+        case 'computer_hello': return hasRequired(value, { ticket: isString });
+        case 'computer_ready': return hasRequired(value, { generation: isString, wireVersion: isNumber });
+        case 'heartbeat': return hasRequired(value, { seq: isNumber, sentAtEpochMs: isNumber });
+        case 'heartbeat_ack': return hasRequired(value, { seq: isNumber });
+        case 'exec_request': return hasRequired(value, {
+            id: isString, command: isString, shell: isString, cwd: isString, env: isStringRecord,
+            pathPrepend: isStringArray, streaming: isBoolean,
+        }) && hasOptional(value, { timeoutSeconds: isNullableNumber });
+        case 'exec_output': return hasRequired(value, { id: isString, stream: isString, chunk: isString });
+        case 'exec_exit': return hasRequired(value, {
+            id: isString, exitCode: isNullableNumber, stdout: isString, stderr: isString,
+            timedOut: isBoolean, truncated: isBoolean,
+        });
+        case 'exec_cancel': return hasRequired(value, { id: isString });
+        default: return false;
+    }
+}
+function isNullableNumber(value) { return value === null || isNumber(value); }
+export function encodeComputerFrame(frame) {
+    return JSON.stringify(frame);
+}
+export function decodeComputerFrame(text) {
+    return decodeChannelFrame(text, DISCRIMINATORS, isComputerFrame);
+}

package/dist/workstation/protocol/management.js

@@ -0,0 +1,116 @@
+import { decodeChannelFrame, hasOptional, hasRequired, isBoolean, isBridgeInfoArray, isNullableString, isNumber, isObject, isString, } from './common.js';
+export const MANAGEMENT_WIRE_MIN_VERSION = 1;
+/** Adds the `DRAINING` value to ClientUpdatePhase. */
+export const MANAGEMENT_WIRE_DRAINING_VERSION = 3;
+/** Adds optional workstation load and storage-pool metrics to heartbeats. */
+export const MANAGEMENT_WIRE_METRICS_VERSION = 4;
+/** Adds normalized CPU load and OS memory-pressure metrics. */
+export const MANAGEMENT_WIRE_PRESSURE_VERSION = 5;
+/** Replaces normalized CPU load with raw 1/5/15-minute load averages and CPU capacity. */
+export const MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION = 6;
+export const MANAGEMENT_WIRE_VERSION = MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION;
+const DISCRIMINATORS = new Set([
+    'management_hello', 'management_ready', 'heartbeat', 'heartbeat_ack',
+    'channel_ticket_request', 'channel_ticket', 'client_update', 'client_update_status',
+    'external_agents_scan', 'external_agents_scan_result',
+]);
+const CHANNEL_KINDS = new Set(['MANAGEMENT', 'COMPUTER', 'AGENT']);
+const CHANNEL_STATES = new Set(['DISCONNECTED', 'CONNECTING', 'CONNECTED', 'RECONNECTING']);
+function isChannelKind(value) { return typeof value === 'string' && CHANNEL_KINDS.has(value); }
+function isChannelState(value) { return typeof value === 'string' && CHANNEL_STATES.has(value); }
+function isNullable(guard) {
+    return (value) => value === null || guard(value);
+}
+function isProtocolRange(value) {
+    return isObject(value) && hasRequired(value, { min: isNumber, max: isNumber });
+}
+function isProtocolRangeMap(value, complete) {
+    if (!isObject(value))
+        return false;
+    if (complete && ![...CHANNEL_KINDS].every((kind) => Object.hasOwn(value, kind)))
+        return false;
+    return Object.entries(value).every(([kind, range]) => CHANNEL_KINDS.has(kind) && isProtocolRange(range));
+}
+function isSelectedProtocolMap(value) {
+    return isObject(value)
+        && [...CHANNEL_KINDS].every((kind) => Object.hasOwn(value, kind))
+        && Object.entries(value).every(([kind, version]) => CHANNEL_KINDS.has(kind) && isNumber(version));
+}
+function isRelease(value) {
+    return isObject(value) && hasRequired(value, { version: isString, url: isString, size: isNumber, sha512: isString });
+}
+const UPDATE_PHASES = new Set([
+    'REQUESTED', 'DRAINING', 'BUSY', 'DOWNLOADING', 'VERIFYING', 'INSTALLING', 'RESTARTING',
+    'SUCCEEDED', 'FAILED', 'ROLLED_BACK', 'UPDATE_IN_PROGRESS',
+]);
+function isUpdateStatus(value) {
+    return isObject(value) && hasRequired(value, { phase: (phase) => typeof phase === 'string' && UPDATE_PHASES.has(phase) })
+        && hasOptional(value, {
+            commandId: isString, version: isString, releaseSha512: isString, force: isBoolean,
+            activeShellTasks: isNumber, activeAgentTasks: isNumber, error: isString,
+        });
+}
+function isOsInfo(value) {
+    return isObject(value) && hasRequired(value, { name: isString, version: isString, arch: isString })
+        && hasOptional(value, { hostname: isNullableString });
+}
+function isStoragePoolMetrics(value) {
+    return isObject(value) && hasRequired(value, {
+        id: isString,
+        label: isString,
+        workspaces: (workspaces) => Array.isArray(workspaces) && workspaces.every(isString),
+        totalBytes: isNumber,
+        availableBytes: isNumber,
+    });
+}
+function isWorkstationMetrics(value) {
+    return isObject(value) && hasRequired(value, {
+        cpuUtilization: isNullable(isNumber),
+        memoryTotalBytes: isNumber,
+        memoryAvailableBytes: isNumber,
+        storagePools: (pools) => Array.isArray(pools) && pools.every(isStoragePoolMetrics),
+    }) && hasOptional(value, {
+        cpuLoadNormalized: isNullable(isNumber),
+        cpuLoad1: isNullable(isNumber),
+        cpuLoad5: isNullable(isNumber),
+        cpuLoad15: isNullable(isNumber),
+        cpuLogicalCount: isNullable(isNumber),
+        memoryPressure: isNullable(isNumber),
+    });
+}
+function isManagementFrame(value) {
+    switch (value.t) {
+        case 'management_hello': return hasRequired(value, {
+            workstationId: isString, workstation: isString, clientNonce: isString, clientVersion: isString,
+            protocols: (protocols) => isProtocolRangeMap(protocols, true),
+            clientPackage: isString,
+        }) && hasOptional(value, { bridges: isBridgeInfoArray });
+        case 'management_ready': return hasRequired(value, {
+            serverNonce: isString, generation: isString, protocols: isSelectedProtocolMap,
+        }) && hasOptional(value, { release: isNullable(isRelease) });
+        case 'heartbeat': return hasRequired(value, {
+            seq: isNumber, sentAtEpochMs: isNumber, clientVersion: isString,
+            channels: (channels) => isObject(channels) && Object.entries(channels).every(([kind, state]) => CHANNEL_KINDS.has(kind) && isChannelState(state)),
+            activeShellTasks: isNumber, activeAgentTasks: isNumber,
+        }) && hasOptional(value, {
+            protocols: (protocols) => isProtocolRangeMap(protocols, false),
+            os: isNullable(isOsInfo),
+            update: isNullable(isUpdateStatus),
+            metrics: isNullable(isWorkstationMetrics),
+        });
+        case 'heartbeat_ack': return hasRequired(value, { seq: isNumber });
+        case 'channel_ticket_request': return hasRequired(value, { channel: isChannelKind });
+        case 'channel_ticket': return hasRequired(value, { channel: isChannelKind, ticket: isString, expiresAtEpochMs: isNumber });
+        case 'client_update': return hasRequired(value, { commandId: isString, release: isRelease, force: isBoolean });
+        case 'client_update_status': return hasRequired(value, { status: isUpdateStatus });
+        case 'external_agents_scan': return hasRequired(value, { commandId: isString });
+        case 'external_agents_scan_result': return hasRequired(value, { commandId: isString, bridges: isBridgeInfoArray });
+        default: return false;
+    }
+}
+export function encodeManagementFrame(frame) {
+    return JSON.stringify(frame);
+}
+export function decodeManagementFrame(text) {
+    return decodeChannelFrame(text, DISCRIMINATORS, isManagementFrame);
+}

package/dist/workstation/register.js

@@ -0,0 +1,42 @@
+import { UsageError } from '../config.js';
+import { clientDir, loadClientConfig, saveClientConfig, writeKeys } from './config.js';
+import { osInfo } from './osinfo.js';
+export async function registerWorkstation(server, clientName, token, ws) {
+    const dir = clientDir();
+    const existing = await loadClientConfig(dir).catch(() => undefined);
+    const body = {
+        name: clientName,
+        ...(existing?.server === server ? { workstationId: existing.workstationId } : {}),
+        os: osInfo(),
+        defaultWorkspace: { name: ws.name, cwd: ws.cwd, shell: ws.shell },
+    };
+    let res;
+    try {
+        res = await fetch(new URL('/workstation/register', server), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        throw new Error(`Failed to reach ${server}/workstation/register: ${err instanceof Error ? err.message : err}`);
+    }
+    if (!res.ok) {
+        // A workstation with this name is already registered for this account — most commonly because
+        // this same machine registered before an axom-cli upgrade and no longer has a local config at
+        // the new config-directory path (see the client's move from ~/.axom-workstation to
+        // ~/.axom/workstation). Rebinding the existing row silently would hand this machine's identity
+        // to whichever caller re-registers next, so the server refuses instead of upserting.
+        if (res.status === 409) {
+            throw new UsageError(`A workstation named '${clientName}' is already registered for this account. This is expected `
+                + `when the same machine re-registers after an axom-cli upgrade. Delete it under Settings → `
+                + 'Workstations, then run `axom workstation start` again.');
+        }
+        throw new Error(`Registration failed: ${res.status} ${await res.text()}`);
+    }
+    const data = (await res.json());
+    if (!data.workstationId)
+        throw new Error('Registration response missing workstationId');
+    await saveClientConfig(dir, { server, workstationId: data.workstationId, workspaces: [{ name: ws.name, cwd: ws.cwd }] });
+    await writeKeys(dir, data.clientKey, data.serverPub);
+}