@playcraft/cli 0.0.59 → 0.1.0

package/dist/workspace-runtime/server/http.js

@@ -1,19 +1,26 @@
 import { readObservedFile, withObservedFile } from '../workspaces/revisions.js';
 import { registerWorkspace, revisionScope, workspaceRoot, WorkspaceContextError } from '../workspaces/registry.js';
 import { randomUUID } from 'node:crypto';
-import { workspaceRegistrationRequestSchema, HTTP_STATUS_BY_ERROR, assertLeaseFence, buildHandshakeDocument, capability, findUntrustedRuntimeFields, hashOperationPayload, instanceRebuildRequestSchema, operationAcceptRequestSchema, operationKindSchema, operationScopeKey, resolveIdempotentAccept, runtimeError, unavailableRuntimeCapabilities, } from '@playcraft/common/cloud-workspace/runtime';
+import { workspaceRegistrationRequestSchema, HTTP_STATUS_BY_ERROR, assertLeaseFence, buildHandshakeDocument, capability, findUntrustedRuntimeFields, hashOperationPayload, instanceRebuildRequestSchema, sourceAckSchema, operationAcceptRequestSchema, operationKindSchema, operationScopeKey, resolveIdempotentAccept, runtimeError, unavailableRuntimeCapabilities, } from '@playcraft/common/cloud-workspace/runtime';
 import { controlTokenMatches, extractControlToken } from './auth.js';
 import { canExecuteKind, executeOperation } from './dispatch.js';
 import { InvalidWorkspacePathError, listWorkspaceFiles, } from '../workspaces/files.js';
 import { materializeRemoteSnapshot } from '../workspaces/file-snapshot.js';
 import { GitWorkspaceError, readWorkspaceGitDiff, readWorkspaceGitGraph, readWorkspaceGitStatus, } from '../workspaces/git.js';
 import { readWorkspaceParameters } from '../workspaces/parameters.js';
+import { desktopHost, desktopRoute } from './desktop-host.js';
+import { terminalHost } from './terminal-host.js';
 export async function handleRuntimeRequest(state, request, response) {
     const url = new URL(request.url ?? '/', 'http://127.0.0.1');
-    if (!controlTokenMatches(state.config.controlToken, extractControlToken(request.headers))) {
+    const access = authorizeRuntime(state, request);
+    if (!access) {
         writeError(response, runtimeError('unauthenticated', 'control_token_required'));
         return;
     }
+    if (access === 'read' && !readSourcePath(request.method ?? 'GET', url.pathname)) {
+        writeJson(response, 403, { error: 'source_read_only' });
+        return;
+    }
     try {
         if (request.method === 'GET' && url.pathname === '/runtime/health') {
             writeJson(response, 200, { status: 'ok', handshake: handshake(state) });
@@ -28,6 +35,7 @@ export async function handleRuntimeRequest(state, request, response) {
                 generation,
                 runtimeEpoch: state.runtimeEpoch,
                 instanceToken: state.instanceToken,
+                sourceReadToken: state.journal.sourceReadToken(),
                 workspaceMode: state.config.workspaceMode,
                 executionGroup: {
                     replaced: state.journal.executionGroup().replaced,
@@ -80,11 +88,8 @@ export async function handleRuntimeRequest(state, request, response) {
             });
             return;
         }
-        if (request.method === 'GET' && url.pathname === '/runtime/events') {
-            const after = Number(url.searchParams.get('after') ?? '0');
-            writeJson(response, 200, {
-                events: state.journal.listEvents(Number.isInteger(after) ? after : 0),
-            });
+        if (url.pathname === '/runtime/events' || url.pathname.startsWith('/runtime/events/')) {
+            await handleSourceEvents(state, request, response, url);
             return;
         }
         if (request.method === 'GET' && url.pathname === '/runtime/files') {
@@ -143,6 +148,10 @@ export async function handleRuntimeRequest(state, request, response) {
             await handleTerminalIdentity(state, request, response, url.pathname.slice('/runtime/terminals/'.length));
             return;
         }
+        if (desktopRoute(url.pathname)) {
+            await desktopHost(state).handleHttp(request, response, url);
+            return;
+        }
         if (request.method === 'GET' && url.pathname === '/runtime/operations') {
             const kind = operationKindSchema.safeParse(url.searchParams.get('kind'));
             const clientRequestId = url.searchParams.get('clientRequestId');
@@ -219,9 +228,10 @@ function handshake(state) {
                 : capability('terminal', true);
         }
         if (item.name === 'desktop') {
-            return destroyed
-                ? capability('desktop', false, 'runtime_destroyed')
-                : capability('desktop', false, 'display_not_started');
+            if (destroyed)
+                return capability('desktop', false, 'runtime_destroyed');
+            const status = desktopHost(state).snapshot().status;
+            return status === 'ready' ? capability('desktop', true) : capability('desktop', false, status);
         }
         if (item.name === 'parameters') {
             return destroyed
@@ -502,7 +512,7 @@ async function handleTerminalIdentity(state, request, response, remainder) {
             writeError(response, runtimeError('capability_unavailable', 'terminal_destroyed'));
             return;
         }
-        writeError(response, runtimeError('capability_unavailable', 'pty_not_started'));
+        writeError(response, runtimeError('capability_unavailable', 'websocket_required'));
         return;
     }
     if (request.method === 'GET' && !action) {
@@ -517,6 +527,7 @@ async function handleTerminalIdentity(state, request, response, remainder) {
                 status: 'destroyed',
                 destroyedAt: new Date().toISOString(),
             });
+        terminalHost(state).revoke(destroyed.terminalId, 'terminal_destroyed');
         writeJson(response, 200, { terminalId: destroyed.terminalId, status: destroyed.status });
         return;
     }
@@ -554,6 +565,180 @@ function writeJson(response, status, body) {
     });
     response.end(payload);
 }
+function authorizeRuntime(state, request) {
+    const presented = extractControlToken(request.headers);
+    if (controlTokenMatches(state.config.controlToken, presented))
+        return 'control';
+    const dedicated = headerValue(request.headers['x-playcraft-source-read-token']);
+    const candidate = dedicated || presented;
+    if (candidate && controlTokenMatches(state.journal.sourceReadToken(), candidate))
+        return 'read';
+    return null;
+}
+function readSourcePath(method, pathname) {
+    if (method === 'GET' && pathname === '/runtime/events')
+        return true;
+    if (method === 'POST' && pathname === '/runtime/events/replay-pins')
+        return true;
+    if (method === 'DELETE' && pathname.startsWith('/runtime/events/replay-pins/'))
+        return true;
+    return false;
+}
+async function handleSourceEvents(state, request, response, url) {
+    if (request.method === 'POST' && url.pathname === '/runtime/events/replay-pins') {
+        const pin = await state.journal.createReplayPin({
+            runtimeId: state.config.runtimeId,
+            generation: state.config.generation,
+            runtimeEpoch: state.runtimeEpoch,
+            ttlMs: Number(asRecord(await readJson(request)).ttlMs) || undefined,
+        });
+        writeJson(response, 201, pin);
+        return;
+    }
+    if (request.method === 'DELETE' && url.pathname.startsWith('/runtime/events/replay-pins/')) {
+        await state.journal.deleteReplayPin(decodeURIComponent(url.pathname.slice('/runtime/events/replay-pins/'.length)));
+        writeJson(response, 200, { deleted: true });
+        return;
+    }
+    if (request.method === 'POST' && url.pathname === '/runtime/events/ack') {
+        const parsed = sourceAckSchema.safeParse(await readJson(request));
+        if (!parsed.success) {
+            writeJson(response, 400, { error: 'invalid_source_ack' });
+            return;
+        }
+        try {
+            await state.journal.acknowledgeSource(parsed.data);
+        }
+        catch (error) {
+            writeJson(response, 409, { code: error instanceof Error ? error.message : 'ack_rejected' });
+            return;
+        }
+        writeJson(response, 200, { ok: true, acceptedLeaseFence: state.journal.acceptedLeaseFence() });
+        return;
+    }
+    if (request.method === 'GET' && url.pathname === '/runtime/events') {
+        const after = Number(url.searchParams.get('after') ?? '0');
+        const safeAfter = Number.isInteger(after) && after >= 0 ? after : 0;
+        const epochQuery = url.searchParams.get('runtimeEpoch');
+        const runtimeEpoch = epochQuery === null ? state.runtimeEpoch : Number(epochQuery);
+        const query = {
+            runtimeId: state.config.runtimeId,
+            generation: state.config.generation,
+            runtimeEpoch: Number.isInteger(runtimeEpoch) ? runtimeEpoch : state.runtimeEpoch,
+            after: safeAfter,
+        };
+        if (String(request.headers.accept ?? '').includes('text/event-stream')) {
+            writeSourceStream(state, request, response, query);
+            return;
+        }
+        if (epochQuery === null) {
+            const events = state.journal.listEvents(safeAfter);
+            const page = state.journal.readSourcePage({ ...query, limit: 1 });
+            writeJson(response, 200, {
+                events,
+                retainedFrom: page.ok ? page.retainedFrom : page.retainedFrom,
+                highWater: page.ok ? page.highWater : page.highWater,
+                nextAfter: events.at(-1)?.source.sourceSequence ?? safeAfter,
+                runtimeId: query.runtimeId,
+                generation: query.generation,
+                runtimeEpoch: query.runtimeEpoch,
+            });
+            return;
+        }
+        const page = state.journal.readSourcePage(query);
+        if (!page.ok) {
+            writeJson(response, 409, {
+                code: page.code,
+                retainedFrom: page.retainedFrom,
+                highWater: page.highWater,
+                coveredThrough: page.coveredThrough,
+            });
+            return;
+        }
+        writeJson(response, 200, {
+            events: page.events,
+            retainedFrom: page.retainedFrom,
+            highWater: page.highWater,
+            nextAfter: page.nextAfter,
+            runtimeId: page.runtimeId,
+            generation: page.generation,
+            runtimeEpoch: page.runtimeEpoch,
+        });
+        return;
+    }
+    writeJson(response, 404, { error: 'not_found' });
+}
+function writeSourceStream(state, request, response, query) {
+    let cursor = query.after;
+    const buffered = [];
+    const matches = (event) => event.source.runtimeId === query.runtimeId &&
+        event.source.generation === query.generation &&
+        event.source.runtimeEpoch === query.runtimeEpoch &&
+        event.source.sourceSequence > cursor;
+    const unsubscribe = state.journal.onSourceEvent((event) => {
+        if (matches(event))
+            buffered.push(event);
+    });
+    const page = state.journal.readSourcePage({ ...query, limit: 500 });
+    response.writeHead(200, {
+        'content-type': 'text/event-stream; charset=utf-8',
+        'cache-control': 'no-cache, no-transform',
+        connection: 'keep-alive',
+        'x-accel-buffering': 'no',
+    });
+    const writeEvent = (name, data) => {
+        response.write(`event: ${name}\ndata: ${JSON.stringify(data)}\n\n`);
+    };
+    if (!page.ok) {
+        writeEvent('source.gap', {
+            code: page.code,
+            retainedFrom: page.retainedFrom,
+            highWater: page.highWater,
+            coveredThrough: page.coveredThrough,
+        });
+        response.end();
+        unsubscribe();
+        return;
+    }
+    writeEvent('source.ready', {
+        runtimeId: page.runtimeId,
+        generation: page.generation,
+        runtimeEpoch: page.runtimeEpoch,
+        retainedFrom: page.retainedFrom,
+        highWater: page.highWater,
+        nextAfter: page.nextAfter,
+    });
+    for (const event of page.events) {
+        writeEvent('source', event);
+        cursor = event.source.sourceSequence;
+    }
+    for (const event of buffered) {
+        if (!matches(event))
+            continue;
+        writeEvent('source', event);
+        cursor = event.source.sourceSequence;
+    }
+    unsubscribe();
+    const follow = state.journal.onSourceEvent((event) => {
+        if (!matches(event))
+            return;
+        writeEvent('source', event);
+        cursor = event.source.sourceSequence;
+    });
+    const heartbeat = setInterval(() => {
+        response.write(`: ping\n\n`);
+    }, 10_000);
+    heartbeat.unref?.();
+    const stop = () => {
+        clearInterval(heartbeat);
+        follow();
+    };
+    request.on('close', stop);
+    response.on('close', stop);
+}
+function headerValue(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
 function asRecord(value) {
     return value && typeof value === 'object' && !Array.isArray(value)
         ? value

package/dist/workspace-runtime/server/terminal-host.js

@@ -0,0 +1,243 @@
+import { createRequire } from 'node:module';
+import { randomUUID } from 'node:crypto';
+import { lstat } from 'node:fs/promises';
+import { WebSocketServer } from 'ws';
+import { appendTerminalOutput, createTerminalOutputLog, decodeTerminalBytes, runtimeError, terminalClientFrameSchema, terminalOutputSince, } from '@playcraft/common/cloud-workspace/runtime';
+import { resolveWorkspaceFile } from '../workspaces/files.js';
+import { workspaceRoot } from '../workspaces/registry.js';
+import { controlTokenMatches, extractControlToken } from './auth.js';
+const require = createRequire(import.meta.url);
+const pty = require('node-pty');
+const commands = new WeakMap();
+const hosts = new WeakMap();
+export function setTerminalCommand(state, command) {
+    commands.set(state, command);
+}
+export function terminalHost(state) {
+    let host = hosts.get(state);
+    if (!host) {
+        host = new TerminalHost(state);
+        hosts.set(state, host);
+    }
+    return host;
+}
+export function disposeTerminalHost(state) {
+    hosts.get(state)?.dispose();
+    hosts.delete(state);
+}
+export class TerminalHost {
+    state;
+    sessions = new Map();
+    sockets = new WebSocketServer({ noServer: true });
+    constructor(state) {
+        this.state = state;
+    }
+    async handleUpgrade(request, socket, head) {
+        const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+        const match = /^\/runtime\/terminals\/([^/]+)\/connect$/.exec(url.pathname);
+        if (!match || !controlTokenMatches(this.state.config.controlToken, extractControlToken(request.headers))) {
+            rejectUpgrade(socket, 401, runtimeError('unauthenticated', 'control_token_required'));
+            return;
+        }
+        if (this.state.journal.destroyed()) {
+            rejectUpgrade(socket, 409, runtimeError('capability_unavailable', 'runtime_destroyed'));
+            return;
+        }
+        const terminalId = decodeURIComponent(match[1]);
+        const terminal = this.state.journal.getTerminal(terminalId);
+        if (!terminal) {
+            rejectUpgrade(socket, 404, { error: 'terminal_not_found' });
+            return;
+        }
+        if (terminal.status === 'destroyed') {
+            rejectUpgrade(socket, 409, runtimeError('capability_unavailable', 'terminal_destroyed'));
+            return;
+        }
+        let session = this.sessions.get(terminal.terminalId);
+        if (!session) {
+            try {
+                session = this.spawn(terminal, await terminalDirectory(this.state, terminal));
+            }
+            catch {
+                rejectUpgrade(socket, 409, runtimeError('capability_unavailable', 'pty_unavailable'));
+                return;
+            }
+        }
+        const active = session;
+        this.sockets.handleUpgrade(request, socket, head, (ws) => this.attach(active, ws));
+    }
+    revoke(terminalId, reason) {
+        const session = this.sessions.get(terminalId);
+        if (!session)
+            return;
+        this.sessions.delete(terminalId);
+        const frame = { type: 'revoked', reason };
+        for (const listener of session.listeners)
+            listener(frame);
+        session.listeners.clear();
+        try {
+            session.pty.kill();
+        }
+        catch {
+            /* the process may already have exited */
+        }
+    }
+    dispose() {
+        for (const terminalId of [...this.sessions.keys()])
+            this.revoke(terminalId, 'runtime_destroyed');
+        this.sockets.close();
+    }
+    spawn(terminal, cwd) {
+        const command = commands.get(this.state) ?? defaultShell();
+        const session = {
+            streamId: randomUUID(),
+            log: createTerminalOutputLog(),
+            listeners: new Set(),
+            pty: pty.spawn(command.file, command.args, {
+                name: 'xterm-256color',
+                cols: 80,
+                rows: 24,
+                cwd,
+                env: shellEnv(command.file, cwd),
+            }),
+        };
+        session.pty.onData((data) => publish(session, data));
+        session.pty.onExit(({ exitCode, signal }) => {
+            session.exited = {
+                code: exitCode,
+                ...(signal === undefined ? {} : { signal: String(signal) }),
+            };
+            const frame = {
+                type: 'exit',
+                streamId: session.streamId,
+                code: exitCode,
+                ...(session.exited.signal ? { signal: session.exited.signal } : {}),
+            };
+            for (const listener of session.listeners)
+                listener(frame);
+        });
+        this.sessions.set(terminal.terminalId, session);
+        return session;
+    }
+    attach(session, ws) {
+        let open = true;
+        let resumed = false;
+        let cursor = 0;
+        const send = (frame) => {
+            if (open && ws.readyState === ws.OPEN)
+                ws.send(JSON.stringify(frame));
+        };
+        const listener = (frame) => {
+            if (!resumed)
+                return;
+            if (frame.type === 'output') {
+                const end = frame.offset + decodeTerminalBytes(frame.data).length;
+                if (end <= cursor)
+                    return;
+                cursor = Math.max(cursor, end);
+            }
+            send(frame);
+        };
+        session.listeners.add(listener);
+        ws.on('message', (raw) => {
+            let body;
+            try {
+                body = JSON.parse(String(raw));
+            }
+            catch {
+                return;
+            }
+            const parsed = terminalClientFrameSchema.safeParse(body);
+            if (!parsed.success || session.exited && parsed.data.type !== 'resume')
+                return;
+            const frame = parsed.data;
+            if (frame.type === 'resume') {
+                if (frame.streamId && frame.streamId !== session.streamId) {
+                    send({ type: 'reset', streamId: session.streamId, offset: session.log.end });
+                    cursor = session.log.end;
+                    resumed = true;
+                    if (session.exited)
+                        send(exitFrame(session));
+                    return;
+                }
+                const since = terminalOutputSince(session.log, frame.offset);
+                if (since.gap)
+                    send({ type: 'gap', streamId: session.streamId, offset: since.offset });
+                for (const item of since.frames) {
+                    send({ type: 'output', streamId: session.streamId, offset: item.offset, data: item.data });
+                }
+                cursor = session.log.end;
+                resumed = true;
+                if (session.exited)
+                    send(exitFrame(session));
+                return;
+            }
+            if (!resumed)
+                return;
+            if (frame.type === 'resize') {
+                session.pty.resize(frame.cols, frame.rows);
+                return;
+            }
+            session.pty.write(Buffer.from(decodeTerminalBytes(frame.data)).toString('utf8'));
+        });
+        const detach = () => {
+            open = false;
+            session.listeners.delete(listener);
+        };
+        ws.on('close', detach);
+        ws.on('error', detach);
+    }
+}
+function publish(session, text) {
+    const before = session.log.end;
+    session.log = appendTerminalOutput(session.log, text);
+    const since = terminalOutputSince(session.log, before);
+    for (const item of since.frames) {
+        const frame = {
+            type: 'output',
+            streamId: session.streamId,
+            offset: item.offset,
+            data: item.data,
+        };
+        for (const listener of session.listeners)
+            listener(frame);
+    }
+}
+function exitFrame(session) {
+    return {
+        type: 'exit',
+        streamId: session.streamId,
+        code: session.exited?.code ?? null,
+        ...(session.exited?.signal ? { signal: session.exited.signal } : {}),
+    };
+}
+async function terminalDirectory(state, terminal) {
+    const root = await workspaceRoot(state, terminal.workspaceId);
+    if (!terminal.cwd)
+        return root;
+    const resolved = await resolveWorkspaceFile(root, terminal.cwd);
+    const stat = await lstat(resolved);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('pty_unavailable');
+    return resolved;
+}
+function defaultShell() {
+    const shell = process.env.SHELL;
+    const file = shell && shell.startsWith('/') ? shell : '/bin/sh';
+    return { file, args: ['-i'] };
+}
+function shellEnv(file, cwd) {
+    return {
+        PATH: process.env.PATH ?? '/usr/bin:/bin',
+        HOME: process.env.HOME ?? cwd,
+        TERM: 'xterm-256color',
+        LANG: process.env.LANG ?? 'C.UTF-8',
+        SHELL: file,
+    };
+}
+function rejectUpgrade(socket, status, body) {
+    const payload = JSON.stringify(body);
+    const title = status === 401 ? 'Unauthorized' : status === 404 ? 'Not Found' : 'Conflict';
+    socket.write(`HTTP/1.1 ${status} ${title}\r\ncontent-type: application/json; charset=utf-8\r\ncontent-length: ${Buffer.byteLength(payload)}\r\nconnection: close\r\n\r\n${payload}`);
+    socket.destroy();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.0.59",
+  "version": "0.1.0",
   "private": false,
   "type": "module",
   "engines": {
@@ -48,8 +48,9 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "^0.0.59",
-    "@playcraft/common": "^0.0.59",
+    "@playcraft/build": "^0.1.0",
+    "@playcraft/common": "^0.1.0",
+    "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.6",
@@ -65,6 +66,7 @@
     "json5": "^2.2.3",
     "latest-version": "^7.0.0",
     "music-metadata": "^11.12.3",
+    "node-pty": "1.0.0",
     "ora": "^8.2.0",
     "picocolors": "^1.1.1",
     "sharp": "^0.34.5",
@@ -82,6 +84,7 @@
     "@types/sharp": "^0.32.0",
     "@types/update-notifier": "^6.0.8",
     "@types/ws": "^8.18.1",
+    "esbuild": "^0.28.1",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
   }