@phpsandbox/sdk 0.0.68 → 0.1.2

package/dist/shell.js

@@ -1,108 +1,136 @@
 import { nanoid } from 'nanoid';
-function resolveExecInput(command, argsOrOpts = [], opts) {
+function resolveRunInput(command, argsOrOpts = [], opts) {
     const args = Array.isArray(argsOrOpts) ? argsOrOpts : [];
     const resolvedOpts = Array.isArray(argsOrOpts) ? opts : argsOrOpts;
     return {
         command: Array.isArray(command) ? command : args.length > 0 ? [command, ...args] : command,
-        opts: resolvedOpts,
+        opts: { tty: false, ...resolvedOpts },
     };
 }
 export class CommandError extends Error {
-    constructor(output, exitCode) {
-        super(output);
-        this.output = output;
-        this.exitCode = exitCode;
+    constructor(result) {
+        super(result.output);
+        this.result = result;
     }
 }
-class Result {
-    constructor(output, exitCode) {
+export class ProcessResult {
+    constructor(output, stdout, stderr, exitCode) {
         this.output = output;
+        this.stdout = stdout;
+        this.stderr = stderr;
         this.exitCode = exitCode;
     }
     throw() {
         if (this.exitCode !== 0) {
-            throw new CommandError(this.output, this.exitCode);
+            throw new CommandError(this);
         }
         return this;
     }
 }
-export default class Shell {
-    constructor(okra) {
-        this.okra = okra;
+export class ProcessReadable {
+    constructor() {
+        this.controller = null;
+        this.closed = false;
+        this.stream = new ReadableStream({
+            start: (controller) => {
+                this.controller = controller;
+            },
+            cancel: () => {
+                this.closed = true;
+                this.controller = null;
+            },
+        });
     }
-    onOutput(id, handler) {
-        return this.okra.listen(`shell.output.${id}`, handler);
+    enqueue(value) {
+        if (!this.closed) {
+            this.controller?.enqueue(value);
+        }
     }
-    listen(event, handler) {
-        return this.okra.listen(event, handler);
+    close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.controller?.close();
+        this.controller = null;
     }
-    async exec(command, argsOrOpts = [], opts) {
-        const input = resolveExecInput(command, argsOrOpts, opts);
-        const { abortSignal, ...payloadOpts } = input.opts ?? {};
-        const result = await this.okra.invoke('shell.exec', {
-            command: input.command,
-            opts: Object.keys(payloadOpts).length > 0 ? payloadOpts : undefined,
-        }, { abortSignal });
-        return new Result(result.output, result.exitCode);
+    fail(error) {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.controller?.error(error);
+        this.controller = null;
     }
-    execStream(command, argsOrOpts = [], opts) {
-        const input = resolveExecInput(command, argsOrOpts, opts);
-        const id = input.opts?.id || nanoid();
-        const disposables = new Set();
-        let controller = null;
-        let closed = false;
-        const dispose = () => {
-            for (const disposable of disposables) {
-                disposable.dispose();
-            }
-            disposables.clear();
-        };
-        const close = () => {
-            if (closed) {
-                return;
-            }
-            closed = true;
-            dispose();
-            if (controller) {
-                try {
-                    controller.close();
-                }
-                catch {
-                    // Ignore close errors after cancellation.
+}
+export class ShellProcess {
+    constructor(id, okra, command, opts) {
+        this.id = id;
+        this.okra = okra;
+        const output = new ProcessReadable();
+        const stdout = new ProcessReadable();
+        const stderr = new ProcessReadable();
+        this.output = output.stream;
+        this.stdout = stdout.stream;
+        this.stderr = stderr.stream;
+        this.stdin = new WritableStream({
+            write: async (chunk) => {
+                const input = typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk);
+                const written = await this.okra.invoke('shell.input', { id: this.id, input });
+                if (!written) {
+                    throw new Error(`Process ${this.id} is not accepting input`);
                 }
+            },
+        });
+        const encoder = new TextEncoder();
+        let subscription = this.okra.listen(`shell.output.${this.id}`, (event) => {
+            const data = encoder.encode(event.output);
+            const source = event.source ?? 'output';
+            output.enqueue({ source, data });
+            if (source === 'stderr') {
+                stderr.enqueue(data);
+            }
+            else {
+                stdout.enqueue(data);
             }
+        });
+        const finish = () => {
+            subscription?.dispose();
+            subscription = null;
+            output.close();
+            stdout.close();
+            stderr.close();
         };
         const fail = (error) => {
-            if (closed) {
-                return;
-            }
-            closed = true;
-            dispose();
-            if (controller) {
-                controller.error(error);
-            }
+            subscription?.dispose();
+            subscription = null;
+            output.fail(error);
+            stdout.fail(error);
+            stderr.fail(error);
         };
-        const output = new ReadableStream({
-            start: (_controller) => {
-                controller = _controller;
-                disposables.add(this.listen(`shell.output.${id}`, (data) => {
-                    controller?.enqueue(data.output);
-                }));
-            },
-            cancel: () => {
-                closed = true;
-                dispose();
-            },
-        });
-        const result = this.exec(input.command, { ...input.opts, id })
-            .then((response) => {
-            close();
-            return response;
-        })
-            .catch((error) => {
+        const { abortSignal, ...payloadOpts } = opts;
+        this.completion = this.okra.invoke('shell.exec', { command, opts: { ...payloadOpts, id: this.id } }, { abortSignal }).then((result) => {
+            finish();
+            return new ProcessResult(result.output, result.stdout, result.stderr, result.exitCode);
+        }).catch((error) => {
             fail(error);
             throw error;
         });
-        return { output, result };
+    }
+    wait() {
+        return this.completion;
+    }
+    async kill() {
+        await this.okra.invoke('shell.kill', { id: this.id });
+    }
+}
+export default class Shell {
+    constructor(okra) {
+        this.okra = okra;
+    }
+    run(command, argsOrOpts = [], opts) {
+        const input = resolveRunInput(command, argsOrOpts, opts);
+        const id = input.opts?.id ?? nanoid();
+        return new ShellProcess(id, this.okra, input.command, { ...input.opts, id });
     }
 }

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 {
@@ -49,7 +49,6 @@ export interface TerminalActions {
         input: string;
     }>;
     'terminal.list': Action<{}, Task[]>;
-    'terminal.start': Action;
     'terminal.create': Action<TerminalCreateInput, Task>;
     'terminal.spawn': Action<TerminalSpawnInput, Task>;
     'terminal.attach': Action<{
@@ -66,8 +65,8 @@ export interface TerminalActions {
     }, boolean>;
 }
 export interface SandboxProcess {
-    exit: Promise<number>;
-    input: WritableStream<string>;
+    wait(): Promise<number>;
+    input: WritableStream<string | Uint8Array>;
     output: ReadableStream<string>;
     kill(): Promise<boolean>;
     resize(dimensions: {
@@ -88,22 +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[]>;
-    start(): Promise<void>;
-    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,33 +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');
     }
-    start() {
-        return this.okra.invoke('terminal.start');
-    }
-    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);
@@ -51,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;
@@ -98,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) {
@@ -106,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();
@@ -127,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);
                 }));
             },
@@ -136,8 +116,8 @@ export default class Terminal {
                 disposeInput();
             },
         });
-        const exit = new Promise((resolve) => {
-            disposables.add(this.listen(`terminal.close.${id}`, (data) => {
+        const completion = new Promise((resolve) => {
+            disposables.add(this.okra.listen(`terminal.close.${id}`, (data) => {
                 if (controller) {
                     try {
                         controller.close();
@@ -165,7 +145,7 @@ export default class Terminal {
         }
         return {
             process: {
-                exit,
+                wait: () => completion,
                 input,
                 output,
                 kill,

package/docs/api-summary.md

@@ -23,45 +23,55 @@ Connection lifecycle methods, streaming actions, and event subscriptions require
 
 - `create(template, input?, init = true)`
 - `get(id)`
-- `open(id)`
 - `fork(id, input?)`
-- `delete(id)`
+- `destroy(id)`
 - `openFromData(data)`
 - `mail.status(id)`, `mail.enable(id)`, `mail.disable(id)`, `mail.list(id, options?)`, `mail.get(id, hash)`, `mail.delete(id, hash)`
 
 ## `NotebookInstance`
 
 - Lifecycle: `ready()`, `connected()`, `whenConnected()`, `reconnect()`, `dispose()`
-- Notebook actions: `fork(input?)`, `delete()`, `stop()`, `restart()`, `ping()`, `update()`
+- Notebook actions: `fork(input?)`, `destroy()`, `stop()`, `restart()`, `ping()`, `update()`
+- 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
 
-- `exec(command)` returning `{ output, exitCode }` plus `throw()` helper
+- `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`)
 
@@ -114,19 +124,17 @@ Connection lifecycle methods, streaming actions, and event subscriptions require
 - `stop()`, `eval(code, args?, replOpts?)`, `write(input)`, `resize(cols, rows)`
 - Events: `listen()`, `onOutput()`
 
-### Laravel (`notebook.laravel`)
-
-- Wrapper exists in the SDK, but the current runtime action set does not expose Laravel maintenance actions.
-
 ### Auth (`notebook.auth`)
 
 - `login(runtimeUrl)` using a fresh ticket-bearing runtime URL
-- `logout()`
 
-### Log (`notebook.log`)
+## Publications
 
-- `stream(handler)`
-- `listen(event, handler)`
+- `notebook.publish({ slug, provider, protection?, feedback?, metadata? })`
+- `notebook.publication()` returns the current publication or `null`
+- `client.publications.get(id)`, `destroy(id)`, `events(id)`, `logs(id)`, and `buildLogs(id, buildId)`
+- 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.
 
 ## Common Errors
 
@@ -137,6 +145,6 @@ Connection lifecycle methods, streaming actions, and event subscriptions require
 
 ## Notes for Consumers
 
-- `open()` and `get()` do not auto-initialize; call `await notebook.ready()`.
+- `get()` does not auto-initialize; call `await notebook.ready()`.
 - `create()` and `fork()` initialize by default.
 - Always call `notebook.dispose()` when finished.

package/docs/cdn-usage.md

@@ -15,10 +15,10 @@ Do not hardcode long-lived private API tokens in public frontend code. Use short
   import { PHPSandbox } from 'https://unpkg.com/@phpsandbox/sdk@0.0.51/dist/browser/phpsandbox-sdk.esm.min.js';
 
   const client = new PHPSandbox('your-short-lived-token');
-  const notebook = await client.notebook.open('your-notebook-id');
+  const notebook = await client.notebook.get('your-notebook-id');
   await notebook.ready();
 
-  const result = await notebook.shell.exec('php -v');
+  const result = await notebook.exec('php -v', { tty: false });
   result.throw();
   console.log(result.output);
 </script>
@@ -43,9 +43,9 @@ Do not hardcode long-lived private API tokens in public frontend code. Use short
 <script>
   const client = new PHPSandbox.PHPSandbox('your-short-lived-token');
 
-  client.notebook.open('your-notebook-id').then(async (notebook) => {
+  client.notebook.get('your-notebook-id').then(async (notebook) => {
     await notebook.ready();
-    const result = await notebook.shell.exec('php -v');
+    const result = await notebook.exec('php -v', { tty: false });
     console.log(result.output);
     notebook.dispose();
   });

package/docs/getting-started.md

@@ -35,8 +35,8 @@ const persistent = await client.notebook.create('laravel', {
   persistent: true,
 });
 
-// open()/get() need ready()
-const existing = await client.notebook.open('notebook-id');
+// get() needs ready()
+const existing = await client.notebook.get('notebook-id');
 await existing.ready();
 
 const fork = await existing.fork();
@@ -48,18 +48,18 @@ API notebook creates and forks are ephemeral by default. Use `persistent: true`
 ## 3. Write and Read Files
 
 ```ts
-await notebook.file.write('hello.php', '<?php echo "Hello";');
+await notebook.files.write('hello.php', '<?php echo "Hello";');
 
-const data = await notebook.file.readFile('hello.php');
+const data = await notebook.files.read('hello.php');
 const text = new TextDecoder().decode(data);
 
 console.log(text);
 ```
 
-If you need binary-safe writes, use `writeFile`:
+The same `write()` method accepts text, bytes, readable streams, and async iterables:
 
 ```ts
-await notebook.file.writeFile('binary.dat', new Uint8Array([1, 2, 3]), {
+await notebook.files.write('binary.dat', new Uint8Array([1, 2, 3]), {
   create: true,
   overwrite: true,
   unlock: false,
@@ -72,7 +72,7 @@ await notebook.file.writeFile('binary.dat', new Uint8Array([1, 2, 3]), {
 ### Terminal (stream output)
 
 ```ts
-const task = await notebook.terminal.spawn('php', ['hello.php']);
+const task = await notebook.terminals.create({ command: 'php', args: ['hello.php'] });
 const reader = task.output.getReader();
 
 try {
@@ -85,29 +85,29 @@ try {
   reader.releaseLock();
 }
 
-const exitCode = await task.exit;
+const exitCode = await task.wait();
 console.log(`\nExit code: ${exitCode}`);
 ```
 
 ### Shell (single command result)
 
 ```ts
-const result = await notebook.shell.exec('php -v');
+const result = await notebook.exec('php -v', { tty: false });
 result.throw();
-console.log(result.output);
+console.log(result.stdout);
 ```
 
 ## 5. Search and Watch Files
 
 ```ts
-const matches = await notebook.file.find('*.php', {
+const matches = await notebook.files.find('*.php', {
   includes: ['app/**'],
   excludes: ['vendor/**'],
 });
 
 console.log(matches.map((m) => m.path));
 
-const watcher = notebook.file.watch(
+const watcher = notebook.files.watch(
   '/app',
   {
     recursive: true,
@@ -125,8 +125,8 @@ watcher.dispose();
 ## 6. Use Composer and Git
 
 ```ts
-await notebook.composer.install({ noInteraction: true });
-await notebook.composer.require({ packages: ['monolog/monolog'] });
+(await notebook.composer.install().wait()).throw();
+(await notebook.composer.require({ packages: ['monolog/monolog'] }).wait()).throw();
 
 await notebook.git.checkpoint('Jane Doe <jane@example.com>', 'Initial checkpoint');
 ```
@@ -141,9 +141,9 @@ notebook.dispose();
 
 ## Common Pitfalls
 
-- `open()` / `get()` notebooks must call `await notebook.ready()` before tool calls.
-- `file.watch()` requires an `excludes` array.
-- `shell.exec()` does not throw by default; call `result.throw()` to fail on non-zero exit codes.
+- `get()` notebooks must call `await notebook.ready()` before tool calls.
+- `files.watch()` requires an `excludes` array.
+- Use `notebook.exec()` for one-shot commands; for streaming shell handles, await `process.wait()` and call `result.throw()` to fail on non-zero exit codes.
 
 ## Next Reading