@phpsandbox/sdk 0.1.1 → 0.1.4

package/dist/runtime-telemetry.js

@@ -0,0 +1,111 @@
+export class RuntimeTelemetry {
+    constructor(okra) {
+        this.okra = okra;
+        this.references = new Map();
+        this.synchronization = Promise.resolve();
+        if (okra.runtimeTransport === 'realtime') {
+            okra.onDidConnect(() => {
+                if (this.references.size > 0) {
+                    void this.synchronize();
+                }
+            });
+        }
+    }
+    async acquire(feature) {
+        this.references.set(feature, (this.references.get(feature) ?? 0) + 1);
+        try {
+            await this.synchronize();
+        }
+        catch (error) {
+            this.removeReference(feature);
+            throw error;
+        }
+        let released = false;
+        return async () => {
+            if (released) {
+                return;
+            }
+            released = true;
+            this.removeReference(feature);
+            await this.synchronize();
+        };
+    }
+    removeReference(feature) {
+        const references = this.references.get(feature) ?? 0;
+        if (references <= 1) {
+            this.references.delete(feature);
+        }
+        else {
+            this.references.set(feature, references - 1);
+        }
+    }
+    synchronize() {
+        this.synchronization = this.synchronization.catch(() => { }).then(async () => {
+            const features = Array.from(this.references.keys());
+            if (features.length === 0) {
+                await this.okra.invoke('container.stop-telemetry');
+            }
+            else {
+                await this.okra.invoke('container.stream-telemetry', { features });
+            }
+        });
+        return this.synchronization;
+    }
+}
+export function watchRuntimeTelemetry(okra, telemetry, feature, event, transform, options = {}) {
+    let subscription = null;
+    let release = null;
+    let closed = false;
+    let abort = null;
+    const stop = async () => {
+        if (closed) {
+            return;
+        }
+        closed = true;
+        subscription?.dispose();
+        subscription = null;
+        if (abort && options.signal) {
+            options.signal.removeEventListener('abort', abort);
+        }
+        abort = null;
+        await release?.();
+        release = null;
+    };
+    return new ReadableStream({
+        start(controller) {
+            subscription = okra.listen(event, (data) => {
+                if (!closed) {
+                    controller.enqueue(transform(data));
+                }
+            });
+            if (options.signal) {
+                abort = () => {
+                    void stop().finally(() => controller.error(options.signal?.reason ?? new Error('Aborted')));
+                };
+                if (options.signal.aborted) {
+                    abort();
+                    return;
+                }
+                options.signal.addEventListener('abort', abort, { once: true });
+            }
+            void telemetry.acquire(feature).then(async (releaseTelemetry) => {
+                if (closed) {
+                    await releaseTelemetry();
+                    return;
+                }
+                release = releaseTelemetry;
+            }).catch((error) => {
+                if (!closed) {
+                    closed = true;
+                    subscription?.dispose();
+                    if (abort && options.signal) {
+                        options.signal.removeEventListener('abort', abort);
+                    }
+                    abort = null;
+                    controller.error(error);
+                }
+            });
+        },
+        cancel: stop,
+    });
+}

package/dist/schemas/publications.d.ts

@@ -64,12 +64,12 @@ export declare const PublicationProtectionModeSchema: z.ZodEnum<{
     password: "password";
 }>;
 export declare const PublicationLogStreamSchema: z.ZodEnum<{
-    build: "build";
     runtime: "runtime";
+    build: "build";
 }>;
 export declare const PublishStreamLogStreamSchema: z.ZodEnum<{
-    build: "build";
     runtime: "runtime";
+    build: "build";
     publish: "publish";
 }>;
 export declare const PublicationEventDataSchema: z.ZodObject<{
@@ -82,8 +82,8 @@ export declare const PublicationEventDataSchema: z.ZodObject<{
 export declare const PublicationLogChunkDataSchema: z.ZodObject<{
     sequence: z.ZodNumber;
     stream: z.ZodEnum<{
-        build: "build";
         runtime: "runtime";
+        build: "build";
     }>;
     content: z.ZodString;
     createdAt: z.ZodNullable<z.ZodString>;
@@ -99,8 +99,8 @@ export declare const PublishStreamPhaseSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const PublishStreamLogSchema: z.ZodObject<{
     stream: z.ZodEnum<{
-        build: "build";
         runtime: "runtime";
+        build: "build";
         publish: "publish";
     }>;
     content: z.ZodString;
@@ -135,8 +135,8 @@ export declare const PublishStreamPhaseEventSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const PublishStreamLogEventSchema: z.ZodObject<{
     stream: z.ZodEnum<{
-        build: "build";
         runtime: "runtime";
+        build: "build";
         publish: "publish";
     }>;
     content: z.ZodString;
@@ -172,8 +172,8 @@ export declare const PublishStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodObj
     type: z.ZodLiteral<"phase">;
 }, z.core.$strict>, z.ZodObject<{
     stream: z.ZodEnum<{
-        build: "build";
         runtime: "runtime";
+        build: "build";
         publish: "publish";
     }>;
     content: z.ZodString;
@@ -223,8 +223,8 @@ export declare const PublishStreamSseLogEventSchema: z.ZodObject<{
     event: z.ZodLiteral<"log">;
     data: z.ZodObject<{
         stream: z.ZodEnum<{
-            build: "build";
             runtime: "runtime";
+            build: "build";
             publish: "publish";
         }>;
         content: z.ZodString;
@@ -293,8 +293,8 @@ export declare const PublishStreamSseEventSchema: z.ZodPipe<z.ZodDiscriminatedUn
     event: z.ZodLiteral<"log">;
     data: z.ZodObject<{
         stream: z.ZodEnum<{
-            build: "build";
             runtime: "runtime";
+            build: "build";
             publish: "publish";
         }>;
         content: z.ZodString;
@@ -350,7 +350,7 @@ export declare const PublishStreamSseEventSchema: z.ZodPipe<z.ZodDiscriminatedUn
     status?: "running" | "failed" | "completed";
     data?: Record<string, unknown>;
 } | {
-    stream: "build" | "runtime" | "publish";
+    stream: "runtime" | "build" | "publish";
     content: string;
     type: "log";
 } | {
@@ -370,7 +370,7 @@ export declare const PublishStreamSseEventSchema: z.ZodPipe<z.ZodDiscriminatedUn
 } | {
     event: "log";
     data: {
-        stream: "build" | "runtime" | "publish";
+        stream: "runtime" | "build" | "publish";
         content: string;
     };
 } | {

package/dist/services.d.ts

@@ -1,4 +1,4 @@
-import { Action, Disposable, NotebookInstance } from './index.js';
+import { Action, NotebookInstance } from './index.js';
 export type NotebookServiceKind = 'app' | 'web' | 'cache' | 'task';
 export type NotebookServiceSource = 'built_in' | 'setup_task';
 export type NotebookServiceState = 'running' | 'starting' | 'stopping' | 'backoff' | 'exited' | 'fatal' | 'stopped' | 'unknown';
@@ -64,20 +64,13 @@ export interface ServiceLogOptions {
     tail?: number;
     follow?: false;
 }
-export interface ServiceLogStream {
-    id: string;
-    output: ReadableStream<string>;
-    stop(): Promise<boolean>;
-}
 export default class Services {
     protected okra: NotebookInstance;
     constructor(okra: NotebookInstance);
     list(): Promise<NotebookServiceStatus[]>;
     run(name: NotebookServiceName, command?: NotebookServiceCommand): Promise<NotebookServiceStatus>;
     stop(name: NotebookServiceName): Promise<NotebookServiceStatus>;
-    onLog(id: string, handler: (data: ServiceEvents['service.log']) => void): Disposable;
-    listen<T extends keyof ServiceEvents>(event: T, handler: (data: ServiceEvents[T]) => void): Disposable;
-    logs(name: NotebookServiceName, options: ServiceLogStreamOptions): ServiceLogStream;
+    logs(name: NotebookServiceName, options: ServiceLogStreamOptions): ReadableStream<string>;
     logs(name: NotebookServiceName, options?: ServiceLogOptions): Promise<string>;
     private followLogs;
 }

package/dist/services.js

@@ -18,12 +18,6 @@ export default class Services {
     stop(name) {
         return this.okra.invoke('service.stop', { name });
     }
-    onLog(id, handler) {
-        return this.okra.listen(`service.log.${id}`, handler);
-    }
-    listen(event, handler) {
-        return this.okra.listen(event, handler);
-    }
     logs(name, options = {}) {
         if (options.follow) {
             return this.followLogs(name, options);
@@ -80,10 +74,10 @@ export default class Services {
             close();
             return this.okra.invoke('service.stop-logs', { id });
         });
-        const output = new ReadableStream({
+        return new ReadableStream({
             start: (_controller) => {
                 controller = _controller;
-                disposables.add(this.onLog(id, (data) => {
+                disposables.add(this.okra.listen(`service.log.${id}`, (data) => {
                     controller?.enqueue(data.output);
                 }));
                 void this.okra
@@ -98,9 +92,8 @@ export default class Services {
                 });
             },
             cancel: () => {
-                void stop();
+                return stop().then(() => undefined);
             },
         });
-        return { id, output, stop };
     }
 }

package/dist/shell.d.ts

@@ -49,6 +49,15 @@ export declare class ProcessResult implements ProcessResultData {
     constructor(output: string, stdout: string, stderr: string, exitCode: number);
     throw(): this;
 }
+export declare class ProcessReadable<T> {
+    readonly stream: ReadableStream<T>;
+    private controller;
+    private closed;
+    constructor();
+    enqueue(value: T): void;
+    close(): void;
+    fail(error: unknown): void;
+}
 export declare class ShellProcess {
     readonly id: string;
     private readonly okra;

package/dist/shell.js

@@ -27,7 +27,7 @@ export class ProcessResult {
         return this;
     }
 }
-class OutputStream {
+export class ProcessReadable {
     constructor() {
         this.controller = null;
         this.closed = false;
@@ -67,9 +67,9 @@ export class ShellProcess {
     constructor(id, okra, command, opts) {
         this.id = id;
         this.okra = okra;
-        const output = new OutputStream();
-        const stdout = new OutputStream();
-        const stderr = new OutputStream();
+        const output = new ProcessReadable();
+        const stdout = new ProcessReadable();
+        const stderr = new ProcessReadable();
         this.output = output.stream;
         this.stdout = stdout.stream;
         this.stderr = stderr.stream;

package/dist/terminal.d.ts

@@ -1,4 +1,4 @@
-import { Action, Disposable, NotebookInstance } from './index.js';
+import { Action, NotebookInstance } from './index.js';
 export interface Task {
     id: string;
     command: string | string[];
@@ -14,7 +14,7 @@ export interface TerminalCreateInput {
     kind: string;
     size: [number, number];
     command?: string | string[];
-    env?: Record<string, string>;
+    env?: Record<string, string | number | boolean>;
     cwd?: string;
 }
 export interface TerminalSpawnInput {
@@ -66,7 +66,7 @@ export interface TerminalActions {
 }
 export interface SandboxProcess {
     wait(): Promise<number>;
-    input: WritableStream<string>;
+    input: WritableStream<string | Uint8Array>;
     output: ReadableStream<string>;
     kill(): Promise<boolean>;
     resize(dimensions: {
@@ -87,21 +87,27 @@ export interface SpawnOptions {
     tty?: boolean;
     abortSignal?: AbortSignal;
 }
-export default class Terminal {
+export interface TerminalOptions {
+    command?: string | string[];
+    args?: string[];
+    kind?: string;
+    size?: [number, number];
+    cwd?: string;
+    env?: Record<string, string | number | boolean>;
+    id?: string;
+    osc?: boolean;
+    tty?: boolean;
+    abortSignal?: AbortSignal;
+}
+export default class Terminals {
     protected okra: NotebookInstance;
     constructor(okra: NotebookInstance);
     list(): Promise<Task[]>;
-    create(input: TerminalCreateInput): Promise<Task>;
-    onStarted(handler: (t: Task) => void): Disposable;
-    resize(id: string, size: [number, number]): Promise<boolean>;
-    onOutput(id: string, handler: (data: TerminalEvents['terminal.output']) => void): Disposable;
-    input(id: string, input: string): Promise<boolean>;
-    listen<T extends keyof TerminalEvents>(event: T, handler: (data: TerminalEvents[T]) => void): Disposable;
+    create(options?: TerminalOptions): Promise<SandboxProcess & Task>;
     attach(id: string, opts?: {
         replayHistory?: boolean;
         abortSignal?: AbortSignal;
     }): Promise<(SandboxProcess & Task) | false>;
-    spawn(command: string, args: string[], opts?: SpawnOptions): Promise<SandboxProcess & Task>;
     private processHandle;
 }
 export {};

package/dist/terminal.js

@@ -2,30 +2,34 @@ import { nanoid } from 'nanoid';
 import { once } from './utils/promise.js';
 const TERMINAL_INPUT_FLUSH_DELAY_MS = 8;
 const terminalInputFlushPattern = /[\x00-\x1f\x7f]/;
-export default class Terminal {
+export default class Terminals {
     constructor(okra) {
         this.okra = okra;
     }
     list() {
         return this.okra.invoke('terminal.list');
     }
-    create(input) {
-        return this.okra.invoke('terminal.create', input);
-    }
-    onStarted(handler) {
-        return this.okra.listen('terminal.started', handler);
-    }
-    resize(id, size) {
-        return this.okra.invoke('terminal.resize', { id, width: size[0], height: size[1] });
-    }
-    onOutput(id, handler) {
-        return this.okra.listen(`terminal.output.${id}`, handler);
-    }
-    input(id, input) {
-        return Promise.resolve(this.okra.send('terminal.input', { id, input }));
-    }
-    listen(event, handler) {
-        return this.okra.listen(event, handler);
+    async create(options = {}) {
+        const id = options.id ?? nanoid();
+        const handle = this.processHandle(id, options.abortSignal);
+        const command = typeof options.command === 'string' && options.args?.length
+            ? [options.command, ...options.args]
+            : options.command;
+        const { abortSignal, args: _args, ...input } = options;
+        try {
+            const task = await this.okra.invoke('terminal.create', {
+                ...input,
+                id,
+                kind: options.kind ?? 'bash',
+                size: options.size ?? [80, 24],
+                command,
+            }, { abortSignal });
+            return { ...handle.process, ...task };
+        }
+        catch (error) {
+            handle.dispose();
+            throw error;
+        }
     }
     async attach(id, opts) {
         const handle = this.processHandle(id, opts?.abortSignal);
@@ -48,28 +52,6 @@ export default class Terminal {
             throw error;
         }
     }
-    async spawn(command, args, opts) {
-        const id = opts?.id || nanoid();
-        const handle = this.processHandle(id, opts?.abortSignal);
-        const { abortSignal, ...otherOpts } = opts ?? {};
-        try {
-            const result = await this.okra.invoke('terminal.spawn', {
-                command: [command, ...args],
-                opts: {
-                    id,
-                    ...otherOpts,
-                },
-            }, { abortSignal });
-            return {
-                ...handle.process,
-                ...result,
-            };
-        }
-        catch (error) {
-            handle.dispose();
-            throw error;
-        }
-    }
     processHandle(id, abortSignal) {
         const disposables = new Set();
         let abortHandler;
@@ -95,7 +77,7 @@ export default class Terminal {
             }
             const input = pendingInput;
             pendingInput = '';
-            void this.input(id, input);
+            void this.okra.send('terminal.input', { id, input });
         };
         const scheduleInputFlush = () => {
             if (inputFlushTimer) {
@@ -103,7 +85,8 @@ export default class Terminal {
             }
             inputFlushTimer = setTimeout(flushInput, TERMINAL_INPUT_FLUSH_DELAY_MS);
         };
-        const queueInput = (chunk) => {
+        const queueInput = (value) => {
+            const chunk = typeof value === 'string' ? value : new TextDecoder().decode(value);
             pendingInput += chunk;
             if (terminalInputFlushPattern.test(chunk)) {
                 flushInput();
@@ -124,7 +107,7 @@ export default class Terminal {
         const output = new ReadableStream({
             start: (_controller) => {
                 controller = _controller;
-                disposables.add(this.listen(`terminal.output.${id}`, (data) => {
+                disposables.add(this.okra.listen(`terminal.output.${id}`, (data) => {
                     controller?.enqueue(data.output);
                 }));
             },
@@ -134,7 +117,7 @@ export default class Terminal {
             },
         });
         const completion = new Promise((resolve) => {
-            disposables.add(this.listen(`terminal.close.${id}`, (data) => {
+            disposables.add(this.okra.listen(`terminal.close.${id}`, (data) => {
                 if (controller) {
                     try {
                         controller.close();

package/docs/api-summary.md

@@ -32,36 +32,46 @@ Connection lifecycle methods, streaming actions, and event subscriptions require
 
 - Lifecycle: `ready()`, `connected()`, `whenConnected()`, `reconnect()`, `dispose()`
 - Notebook actions: `fork(input?)`, `destroy()`, `stop()`, `restart()`, `ping()`, `update()`
-- Processes: `run(command, args?, options?)` returning native `stdin`, `stdout`, `stderr`, ordered `output`, `exit`, and `kill()`
+- Processes: `exec(command, args?, options?)`, or `run(command, args?, options?)` returning native `stdin`, `stdout`, `stderr`, ordered `output`, `wait()`, and `kill()`
 - Events: `listen(event, handler)`, `onDidConnect(handler)`, `onDidDisconnect(handler)`, `onDidInitialize(handler)`
 - Raw call: `invoke(action, data?, options?)`
 
 ## Services
 
-### Filesystem (`notebook.file`)
+### Filesystem (`notebook.files`)
 
-- File data: `info()`, `readFile()`, `write()`, `writeFile()`, `tail()`, `stat()`, `exists()`
-- File management: `move()`, `rename()`, `copy()`, `remove()`, `delete()`
-- Directory: `mkdir()`, `createDirectory()`, `readDirectory()`, `tree()`
+- File data: `read()`, `readText()`, `readStream()`, `write()`, `tail()`, `stat()`, `exists()`
+- File management: `move()`, `copy()`, `remove()`
+- Directory: `createDirectory()`, `list()`, `tree()`
 - Search: `find()`, `search()`
-- Streaming/monitoring: `watch()`, `download()`
+- Streaming/monitoring: `readStream()`, `watch()`, `download()`
+- `tail()` is an eager last-lines snapshot; it does not follow future appends.
 
-### Terminal (`notebook.terminal`)
+### Terminal (`notebook.terminals`)
 
-- Terminal control: `list()`, `create()`, `attach()`, `resize()`, `input()`
-- Process API: `spawn(command, args, opts?)`, `attach(id, opts?)`
-- Events: `listen()`, `onStarted()`, `onOutput(id, handler)`
+- `list()` returns terminal metadata
+- `create(options?)` returns a terminal handle
+- `attach(id, options?)` returns a terminal handle
+- Handles expose `input`, `output`, `wait()`, `resize()`, and `kill()`
 
 ### Container (`notebook.container`)
 
 - Lifecycle: `start()`, `stop()`, `state()`
-- Ports: `openedPorts()`, `onPort(handler)`
 - Runtime config: `setPhp(version)`
-- Telemetry: `enableTelemetry(features)`, `stopTelemetry()`, `listen(event, handler)`
 
-### Shell (`notebook.shell`)
+### Runtime observability
 
-- `run(command, args?, options?)` returning the same process handle as `notebook.run()`
+- `notebook.logs.follow({ signal? })` returns `ReadableStream<RuntimeLogEntry>`
+- `notebook.ports.list()` returns the current preview ports
+- `notebook.ports.watch({ signal? })` returns `ReadableStream<PortInfo[]>`
+- `notebook.metrics.current()` returns the current CPU, memory, and disk sample
+- `notebook.metrics.watch({ signal? })` returns `ReadableStream<ContainerStats>`
+
+### Processes
+
+- `notebook.run(command, args?, options?)` returns a streaming process handle
+- `notebook.exec(command, args?, options?)` returns a buffered `ProcessResult` for one-shot commands
+- Process handles expose `output`, `stdout`, `stderr`, `stdin`, `wait()`, and `kill()`
 
 ### Services (`notebook.services`)
 
@@ -70,13 +80,13 @@ Connection lifecycle methods, streaming actions, and event subscriptions require
 - `run(name, command?)`
 - `stop(name)`
 - `logs(name, { tail? })`
-- `logs(name, { follow: true, tail?, id? })` returning `{ id, output, stop() }`
-- Events: `listen()`, `onLog(id, handler)`
+- `logs(name, { follow: true, tail?, id? })` returning `ReadableStream<string>`; cancel the stream to stop following
 
 ### Composer (`notebook.composer`)
 
-- Core: `invoke(command, args?, options?)`
-- Helpers: `install()`, `update()`, `require()`, `remove()`, `dumpAutoload()`, `packages()`, `stream(handler)`
+- Core: `run(command, args?, options?)`
+- Helpers: `install()`, `update()`, `require()`, `remove()`, `dumpAutoload()`, `packages()`
+- Command handles expose `output`, `stdout`, `stderr`, `wait()`, and `kill()`
 
 ### Git (`notebook.git`)
 
@@ -126,11 +136,6 @@ Connection lifecycle methods, streaming actions, and event subscriptions require
 - A publish run exposes `events()` as an `AsyncIterable`, `result()`, and `publication()`.
 - Built-in provider names are `cloudflare-containers`, `ssh-server`, and `laravel-cloud`. Provider maps support TypeScript declaration merging.
 
-### Log (`notebook.log`)
-
-- `stream(handler)`
-- `listen(event, handler)`
-
 ## Common Errors
 
 - `ApiError` for HTTP API failures

package/docs/cdn-usage.md

@@ -18,7 +18,7 @@ Do not hardcode long-lived private API tokens in public frontend code. Use short
   const notebook = await client.notebook.get('your-notebook-id');
   await notebook.ready();
 
-  const result = await notebook.run('php -v', { tty: false }).exit;
+  const result = await notebook.exec('php -v', { tty: false });
   result.throw();
   console.log(result.output);
 </script>
@@ -45,7 +45,7 @@ Do not hardcode long-lived private API tokens in public frontend code. Use short
 
   client.notebook.get('your-notebook-id').then(async (notebook) => {
     await notebook.ready();
-    const result = await notebook.run('php -v', { tty: false }).exit;
+    const result = await notebook.exec('php -v', { tty: false });
     console.log(result.output);
     notebook.dispose();
   });