@platless/axom-cli 0.3.13 → 0.6.36

package/dist/workstation/desktopControl/transport.js

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { DesktopProtocolError, parseDesktopJson } from './protocol.js';
+const sessionId = z.string().regex(/^[0-9a-f]{32}$/);
+const generation = z.number().int().min(1).max(Number.MAX_SAFE_INTEGER);
+const secret = z.string().regex(/^[A-Za-z0-9_-]{43}$/).refine(s => Buffer.from(s, 'base64url').toString('base64url') === s);
+const role = z.enum(['viewer_control', 'viewer_media', 'device_control', 'device_media']);
+const quic = z.strictObject({ port: z.number().int().min(1).max(65535), certificate: z.string().min(64).max(2048).refine(s => Buffer.from(s, 'base64').toString('base64') === s) });
+const schema = z.discriminatedUnion('type', [
+    z.strictObject({ type: z.literal('device_attach'), sessionId, grant: secret }),
+    z.strictObject({ type: z.literal('viewer_attach'), sessionId, nonce: secret }),
+    z.strictObject({ type: z.literal('attached'), sessionId, role, controlGeneration: generation, overviewToken: secret.optional(), audioToken: secret.optional() }),
+    z.strictObject({ type: z.literal('media_grant'), sessionId, controlGeneration: generation, grant: secret, quic: quic.optional() }),
+    z.strictObject({ type: z.literal('media_nonce'), sessionId, controlGeneration: generation, nonce: secret, quic: quic.optional() }),
+]);
+export function decodeDesktopTransport(source) {
+    try {
+        return schema.parse(parseDesktopJson(source, 4096));
+    }
+    catch {
+        throw new DesktopProtocolError('Invalid desktop transport exchange');
+    }
+}
+export function encodeDesktopTransport(message) {
+    const text = JSON.stringify(message);
+    decodeDesktopTransport(text);
+    return text;
+}

package/dist/workstation/desktopControl/wallpaper.js

@@ -0,0 +1,78 @@
+import { createHash } from 'node:crypto';
+import { wallpaperAssetSchema } from './lobby.js';
+export function decodeWallpaper(text) {
+    if (Buffer.byteLength(text) > 100_000)
+        throw new Error('wallpaper_unavailable');
+    const result = JSON.parse(text);
+    const asset = wallpaperAssetSchema.parse(result.asset);
+    if (typeof result.jpeg !== 'string' || result.jpeg.length > 87384)
+        throw new Error('wallpaper_unavailable');
+    const jpeg = Buffer.from(result.jpeg, 'base64');
+    if (jpeg.length < 4 || jpeg.length > 65536 || jpeg.toString('base64') !== result.jpeg || jpeg[0] !== 255 || jpeg[1] !== 216)
+        throw new Error('wallpaper_unavailable');
+    const version = createHash('sha256').update(JSON.stringify(asset)).update(jpeg).digest('hex');
+    return { asset: { ...asset, version }, jpeg };
+}
+export class XfceWallpaperReader {
+    execute;
+    constructor(execute) {
+        this.execute = execute;
+    }
+    async discover() {
+        const workspaceValue = await this.execute('xprop', ['-root', '_NET_CURRENT_DESKTOP']);
+        let workspace = /_NET_CURRENT_DESKTOP\(CARDINAL\)\s*=\s*(\d+)/.exec(workspaceValue)?.[1];
+        if (workspace == null || Number(workspace) > 1024)
+            throw new Error('wallpaper_unavailable');
+        const listed = await this.execute('xfconf-query', ['-c', 'xfce4-desktop', '-l']);
+        const read = (property) => this.execute('xfconf-query', ['-c', 'xfce4-desktop', '-p', property]);
+        if (listed.split(/\r?\n/).some(line => line.trim() === '/backdrop/single-workspace-mode') &&
+            (await read('/backdrop/single-workspace-mode')).trim() === 'true') {
+            workspace = (await read('/backdrop/single-workspace-number')).trim();
+            if (!/^\d{1,4}$/.test(workspace) || Number(workspace) > 1024)
+                throw new Error('wallpaper_unavailable');
+        }
+        const available = listed.split(/\r?\n/).map(line => line.trim());
+        const properties = available
+            .filter(line => new RegExp(`^/backdrop/screen0/monitor[^/]+/workspace${workspace}/last-image$`).test(line));
+        let selected = properties[0];
+        let defaultImage = false;
+        if (properties.length === 0) {
+            const version = await this.execute('xfdesktop', ['--version']);
+            const monitors = await this.execute('xrandr', ['--listactivemonitors']);
+            if (!/xfdesktop version 4\.20(?:\.\d+)?\b/.test(version) || !/^Monitors:\s*1\s*$/m.test(monitors))
+                throw new Error('wallpaper_unavailable');
+            const output = /^\s*0:\s+\S+\s+\S+\s+(\S+)\s*$/m.exec(monitors)?.[1];
+            if (!output || !/^[A-Za-z0-9_.:-]+$/.test(output))
+                throw new Error('wallpaper_unavailable');
+            selected = `/backdrop/screen0/monitor${output}/workspace${workspace}/last-image`;
+            defaultImage = true;
+        }
+        if (properties.length > 1)
+            throw new Error('wallpaper_unavailable');
+        const file = defaultImage ? '/usr/share/backgrounds/xfce/xfce-x.svg' : (await read(selected)).trim();
+        if (!file.startsWith('/') || file.length > 4096 || /[\r\n\0]/.test(file))
+            throw new Error('wallpaper_unavailable');
+        const prefix = selected.slice(0, -'last-image'.length);
+        const style = available.includes(`${prefix}image-style`) ? (await read(`${prefix}image-style`)).trim() : '5';
+        const placement = { '1': 'center', '2': 'tile', '3': 'stretch', '4': 'fit', '5': 'cover' }[style];
+        if (!placement)
+            throw new Error('wallpaper_unavailable');
+        let background = '#000000';
+        let fidelity = 'exact';
+        if (placement !== 'cover' && placement !== 'stretch') {
+            try {
+                if ((await read(`${prefix}color-style`)).trim() !== '0')
+                    throw new Error('unsupported_gradient');
+                const values = (await read(`${prefix}rgba1`)).split(/\r?\n/).map(line => line.trim())
+                    .filter(line => /^\d+(?:\.\d+)?$/.test(line)).map(Number);
+                if (values.length !== 4 || values.some(value => value < 0 || value > 1) || values[3] !== 1)
+                    throw new Error('unknown_fill');
+                background = '#' + values.slice(0, 3).map(value => Math.round(value * 255).toString(16).padStart(2, '0')).join('');
+            }
+            catch {
+                fidelity = 'approximate';
+            }
+        }
+        return { file, placement, background, fidelity };
+    }
+}

package/dist/workstation/exec/attach.js

@@ -0,0 +1,126 @@
+import { ExecWireText } from './shaping.js';
+/** Spec §4.3: `exec_output` waits while the socket holds more than the high mark, until it drains below the low mark. */
+export const EXEC_WINDOW_HIGH_BYTES = 1024 * 1024;
+export const EXEC_WINDOW_LOW_BYTES = 256 * 1024;
+const WINDOW_POLL_MS = 20;
+/** Records per `exec.read` page (the keeper also caps a page at 1.5 MiB). */
+const PAGE_RECORDS = 1024;
+/** Re-read cadence when nothing new arrived and no progress was signalled. */
+const IDLE_POLL_MS = 500;
+const RETRY_MS = 1000;
+/** The v5 `exec_exit` of an ended durable exec (`exitFrame` is the today-shaped frame, exec/policy.ts `durableExitFrame`). */
+export function wireExitFrame(exitFrame, outcome, gapBytes) {
+    const signal = outcome.state === 'exited' ? outcome.exit.signal : null;
+    return { ...exitFrame, cancelled: outcome.cancelled, ...(signal ? { signal } : {}), ...(gapBytes > 0 ? { gaps: gapBytes } : {}) };
+}
+const sleep = (ms, signal) => new Promise((resolve) => {
+    if (signal.aborted) {
+        resolve();
+        return;
+    }
+    const done = () => { clearTimeout(timer); signal.removeEventListener('abort', done); resolve(); };
+    const timer = setTimeout(done, ms);
+    signal.addEventListener('abort', done, { once: true });
+});
+/** Resolves once the socket has room for more output: at once below the high mark, else when it drained below the low mark. */
+export async function waitForWindow(bufferedAmount, signal, pollMs = WINDOW_POLL_MS) {
+    if (bufferedAmount() <= EXEC_WINDOW_HIGH_BYTES)
+        return;
+    while (!signal.aborted && bufferedAmount() > EXEC_WINDOW_LOW_BYTES)
+        await sleep(pollMs, signal);
+}
+/**
+ * Streams `exec` to `channel`: reads its records from keeper-terminal from the commit point on (decoding silently up to
+ * `fromOffset`), sends one `exec_output` per chunk at or after `fromOffset`, honouring the socket window, then the final
+ * `exec_status` and `exec_exit` once the exec ended. A non-streaming exec sends only the final two. `stop()` ends it silently
+ * (the channel closed, or a newer attach replaced it); the exec itself is untouched.
+ */
+export class ExecAttachment {
+    exec;
+    channel;
+    options;
+    abort = new AbortController();
+    done;
+    constructor(exec, channel, options) {
+        this.exec = exec;
+        this.channel = channel;
+        this.options = options;
+        this.done = this.run().catch((error) => { this.options.log?.(`exec ${options.id}: attachment failed: ${error instanceof Error ? error.message : String(error)}`); });
+    }
+    stop() { this.abort.abort(); }
+    get stopped() { return this.abort.signal.aborted; }
+    async run() {
+        const { exec } = this;
+        if (exec.wire?.streaming !== false)
+            await this.stream();
+        if (this.stopped)
+            return;
+        const outcome = await Promise.race([exec.outcome, new Promise((resolve) => this.abort.signal.addEventListener('abort', () => resolve(null), { once: true }))]);
+        if (outcome === null || this.stopped)
+            return;
+        const id = this.options.id;
+        this.channel.send({ t: 'exec_status', id, state: 'exited', headOffset: exec.finalHead, committedOffset: exec.committedOffset });
+        this.channel.send(this.options.exitFrame(outcome));
+    }
+    /** Waits for more records: a progress signal from the exec's own follower, a stop, or the idle poll. */
+    wait(ms) {
+        return new Promise((resolve) => {
+            const unsubscribe = this.exec.onProgress(() => { unsubscribe(); resolve(); });
+            void sleep(ms, this.abort.signal).then(() => { unsubscribe(); resolve(); });
+        });
+    }
+    async stream() {
+        const { exec, channel } = this;
+        const { id, fromOffset } = this.options;
+        const text = new ExecWireText();
+        let cursor = exec.commitFloor + 1;
+        const hold = exec.hold(cursor);
+        try {
+            while (!this.stopped) {
+                const exitAt = exec.exitRecordOffset;
+                if (exitAt !== undefined && cursor > exitAt)
+                    return;
+                let page;
+                try {
+                    page = await exec.read(cursor, PAGE_RECORDS);
+                }
+                catch (error) {
+                    if (exec.finished)
+                        return; // deleted, reclaimed or unreachable: the outcome says so
+                    this.options.log?.(`exec ${id}: read failed: ${error instanceof Error ? error.message : String(error)}`);
+                    await this.wait(RETRY_MS);
+                    continue;
+                }
+                if (this.stopped)
+                    return;
+                if (page.records.length === 0) {
+                    if (exec.finished)
+                        return;
+                    await this.wait(this.options.idleMs ?? IDLE_POLL_MS);
+                    continue;
+                }
+                for (const record of page.records) {
+                    if (record.o < cursor)
+                        continue;
+                    cursor = record.o + 1;
+                    hold.at = cursor;
+                    if (record.k === 'exit')
+                        return;
+                    if (record.k !== 'out' && record.k !== 'err')
+                        continue;
+                    const stream = record.k === 'out' ? 'stdout' : 'stderr';
+                    const chunk = text.push(stream, record.so, Buffer.from(record.b, 'base64'));
+                    if (!chunk || record.o < fromOffset)
+                        continue;
+                    await waitForWindow(() => channel.bufferedAmount(), this.abort.signal);
+                    if (this.stopped)
+                        return;
+                    channel.send({ t: 'exec_output', id, stream, chunk, offset: record.o, recvAtMs: record.t });
+                }
+            }
+        }
+        finally {
+            exec.unhold(hold);
+        }
+    }
+}

package/dist/workstation/exec/command.js

@@ -0,0 +1,40 @@
+// What the daemon decides about one `exec_request` before anything runs (spec §4.2 "daemon (policy)" column; analysis E §6.3–6.4):
+// the exact argv, the complete environment and the absolute deadline. Shared by the durable (keeper-terminal) path and the
+// in-process fallback, so both run the same command line in the same environment.
+import path from 'node:path';
+/**
+ * `[shell, '-lc', command]`, element by element what the daemon has always spawned (`spawn(req.shell, ['-lc', req.command])`):
+ * a login, non-interactive shell of the user's choice reading the command string exactly. Never wrapped (`sh -c`, `; echo $?`, …):
+ * any wrapping would go through the user's shell dialect (zsh EQUALS, fish quoting).
+ */
+export function execArgv(req) {
+    return [req.shell, '-lc', req.command];
+}
+/** The daemon's credential for its own server: never visible to a command (commands/workstation.ts drops it already; again here). */
+export const ACCESS_TOKEN_ENV = 'AXOM_ACCESS_TOKEN';
+/**
+ * The complete environment of the command: the daemon's environment without the access token, then the request's `env`, then
+ * `pathPrepend` in front of PATH (exactly as the daemon always did). keeper-terminal gets this whole map and never falls back to its
+ * own environment (under a systemd transient unit that would be the user manager's, frozen at the keeper's start).
+ */
+export function execEnvironment(daemonEnv, req) {
+    const env = {};
+    for (const [name, value] of Object.entries(daemonEnv))
+        if (value !== undefined && name !== ACCESS_TOKEN_ENV)
+            env[name] = value;
+    Object.assign(env, req.env);
+    if (req.pathPrepend.length > 0)
+        env.PATH = [...req.pathPrepend, env.PATH ?? ''].filter(Boolean).join(path.delimiter);
+    return env;
+}
+/**
+ * The absolute deadline, from `timeoutSeconds` and the DAEMON's clock at the moment it first received the request (never the
+ * server's clock). No timeout (absent, null, 0 or negative: today's rule) means no deadline.
+ */
+export function execDeadline(req, receivedAtMs) {
+    return req.timeoutSeconds && req.timeoutSeconds > 0 ? receivedAtMs + req.timeoutSeconds * 1000 : undefined;
+}
+/** keeper-terminal wants an absolute cwd; a relative one resolves against the daemon's cwd, as `spawn` always resolved it. */
+export function execCwd(req) {
+    return path.resolve(req.cwd || '.');
+}