@phpsandbox/sdk 0.0.67 → 0.1.1

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;
+class OutputStream {
+    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 OutputStream();
+        const stdout = new OutputStream();
+        const stderr = new OutputStream();
+        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

@@ -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,7 +65,7 @@ export interface TerminalActions {
     }, boolean>;
 }
 export interface SandboxProcess {
-    exit: Promise<number>;
+    wait(): Promise<number>;
     input: WritableStream<string>;
     output: ReadableStream<string>;
     kill(): Promise<boolean>;
@@ -92,7 +91,6 @@ export default class Terminal {
     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>;

package/dist/terminal.js

@@ -9,9 +9,6 @@ export default class Terminal {
     list() {
         return this.okra.invoke('terminal.list');
     }
-    start() {
-        return this.okra.invoke('terminal.start');
-    }
     create(input) {
         return this.okra.invoke('terminal.create', input);
     }
@@ -136,7 +133,7 @@ export default class Terminal {
                 disposeInput();
             },
         });
-        const exit = new Promise((resolve) => {
+        const completion = new Promise((resolve) => {
             disposables.add(this.listen(`terminal.close.${id}`, (data) => {
                 if (controller) {
                     try {
@@ -165,7 +162,7 @@ export default class Terminal {
         }
         return {
             process: {
-                exit,
+                wait: () => completion,
                 input,
                 output,
                 kill,

package/docs/api-summary.md

@@ -23,16 +23,16 @@ 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: `run(command, args?, options?)` returning native `stdin`, `stdout`, `stderr`, ordered `output`, `exit`, and `kill()`
 - Events: `listen(event, handler)`, `onDidConnect(handler)`, `onDidDisconnect(handler)`, `onDidInitialize(handler)`
 - Raw call: `invoke(action, data?, options?)`
 
@@ -61,7 +61,7 @@ Connection lifecycle methods, streaming actions, and event subscriptions require
 
 ### Shell (`notebook.shell`)
 
-- `exec(command)` returning `{ output, exitCode }` plus `throw()` helper
+- `run(command, args?, options?)` returning the same process handle as `notebook.run()`
 
 ### Services (`notebook.services`)
 
@@ -114,14 +114,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()`
+
+## Publications
+
+- `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.
 
 ### Log (`notebook.log`)
 
@@ -137,6 +140,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.run('php -v', { tty: false }).exit;
   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.run('php -v', { tty: false }).exit;
     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();
@@ -92,9 +92,9 @@ console.log(`\nExit code: ${exitCode}`);
 ### Shell (single command result)
 
 ```ts
-const result = await notebook.shell.exec('php -v');
+const result = await notebook.run('php -v', { tty: false }).exit;
 result.throw();
-console.log(result.output);
+console.log(result.stdout);
 ```
 
 ## 5. Search and Watch Files
@@ -141,9 +141,9 @@ notebook.dispose();
 
 ## Common Pitfalls
 
-- `open()` / `get()` notebooks must call `await notebook.ready()` before tool calls.
+- `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.
+- Await `process.exit`, then call `result.throw()` to fail on non-zero exit codes.
 
 ## Next Reading
 

package/examples/README.md

@@ -6,20 +6,20 @@
 PHPSANDBOX_TOKEN=your-token npx tsx examples/basic.ts
 ```
 
-### Running Deployment Examples
+### Running Publication Examples
 
 Cloudflare Containers target:
 
 ```bash
 PHPSANDBOX_TOKEN=your-token PHPSANDBOX_NOTEBOOK_ID=notebook-id \
-  npx tsx examples/deploy-cloudflare-container.ts
+  npx tsx examples/publish-cloudflare-container.ts
 ```
 
 SSH agent target:
 
 ```bash
 PHPSANDBOX_TOKEN=your-token PHPSANDBOX_NOTEBOOK_ID=notebook-id \
-  npx tsx examples/deploy-ssh-agent.ts
+  npx tsx examples/publish-ssh-agent.ts
 ```
 
 Laravel Cloud target:
@@ -29,10 +29,10 @@ PHPSANDBOX_TOKEN=your-token PHPSANDBOX_NOTEBOOK_ID=notebook-id \
   PHPSANDBOX_LARAVEL_CLOUD_REPOSITORY=owner/repo \
   PHPSANDBOX_GITHUB_TOKEN=github-token \
   PHPSANDBOX_LARAVEL_CLOUD_API_KEY=lc-api-key \
-  npx tsx examples/deploy-laravel-cloud.ts
+  npx tsx examples/publish-laravel-cloud.ts
 ```
 
-Deployment examples accept `PHPSANDBOX_API_URL` and `PHPSANDBOX_DEPLOY_SLUG`. On the first run they create the notebook's deployment; later runs publish the existing deployment without changing slug or provider. The SSH example creates a server registration when `PHPSANDBOX_DEPLOY_SERVER_ID` is not set; on local `.test` APIs it also starts local Rook from `PHPSANDBOX_ROOK_DIR` or the sibling `rook` repo. The Laravel Cloud example syncs the notebook to `PHPSANDBOX_LARAVEL_CLOUD_REPOSITORY`, upserts `PHPSANDBOX_GITHUB_TOKEN` into `GITHUB_TOKEN`, and upserts `PHPSANDBOX_LARAVEL_CLOUD_API_KEY` into `LARAVEL_CLOUD_API_KEY` on first publish.
+Publication examples accept `PHPSANDBOX_API_URL` and `PHPSANDBOX_PUBLISH_SLUG`. On the first run they create the notebook's publication; later runs publish it again without changing slug or provider. The SSH example creates a server registration when `PHPSANDBOX_PUBLISH_SERVER_ID` is not set; on local `.test` APIs it also starts local Rook from `PHPSANDBOX_ROOK_DIR` or the sibling `rook` repo. The Laravel Cloud example syncs the notebook to `PHPSANDBOX_LARAVEL_CLOUD_REPOSITORY`, upserts `PHPSANDBOX_GITHUB_TOKEN` into `GITHUB_TOKEN`, and upserts `PHPSANDBOX_LARAVEL_CLOUD_API_KEY` into `LARAVEL_CLOUD_API_KEY` on first publish.
 
 ### Running The Laravel Load Test
 
@@ -105,7 +105,7 @@ Useful flags:
 - `--expect-provisioned=true` asserts the `notebook.ready()` initialization result reports provisioning work.
 - `--expect-provisioning-action=template` asserts the initialization result action.
 - `--reauthorization-url=wss://...?ticket=...` exercises `notebook.auth.login()` / `logout()` with a fresh ticket-bearing runtime URL.
-- `--mode=init` limits the scenario to notebook create, ready, and delete so you can isolate init capacity.
+- `--mode=init` limits the scenario to notebook create, ready, and destroy so you can isolate init capacity.
 - `--init-only` is shorthand for `--mode=init`.
 - `--stop-on-failure-level` stops after the first level that has at least one failing scenario.
 - `--local` switches the default API URL to `https://api.phpsandbox.test/v1` and defaults TLS to insecure unless you also pass `--ca-file` or `--no-insecure-tls`.
@@ -116,12 +116,12 @@ Useful flags:
 
 Default baseline coverage:
 
-- notebook lifecycle: create, ready, ping, delete
+- notebook lifecycle: create, ready, ping, destroy
 - secrets
 - container state and telemetry; optional restart with `--include-container-restart`
 - filesystem watch/write/read/search/find/tree/tail
 - optional preview fetch with `--include-preview`
-- shell exec and stream
+- shell process execution and streams
 - terminal spawn streaming
 - services with Redis logs
 - composer metadata and autoload dump
@@ -132,7 +132,6 @@ Intentionally excluded by default:
 
 - `beacon`, because it needs a browser iframe runtime
 - `auth`, because it needs a fresh ticket-bearing runtime URL
-- `laravel.maintenance.*`, because it is not part of the current okra websocket action set
 - `lsp`, because it is useful but more brittle than the rest of the headless baseline
 
 ### Running A Read-Only Existing Notebook Smoke Test

package/examples/basic.ts

@@ -21,4 +21,4 @@ console.log(decoder.decode(content));
 
 // Always close the notebook when done to clean up the connection.
 notebook.dispose();
-await notebook.delete();
+await notebook.destroy();

package/examples/git-merge-smoke.ts

@@ -41,7 +41,7 @@ async function main(): Promise<void> {
   let shouldDeleteFork = false;
 
   try {
-    base = await client.notebook.open(options.notebookId);
+    base = await client.notebook.get(options.notebookId);
     console.log(`Base notebook: ${base.data.id}`);
 
     await base.ready();
@@ -98,7 +98,7 @@ async function main(): Promise<void> {
   } finally {
     if (shouldDeleteFork && fork) {
       try {
-        await fork.delete();
+        await fork.destroy();
         console.log(`Deleted fork notebook: ${fork.data.id}`);
       } catch (error) {
         console.error(`Could not delete fork notebook ${fork.data.id}: ${formatError(error)}`);

package/examples/laravel-load-test.ts

@@ -478,7 +478,7 @@ async function runScenario(
 
         const data = {
           ...created.data,
-          runtimeUrl: resolveRuntimeUrl(created.data.runtimeUrl ?? created.data.okraUrl, options),
+          runtimeUrl: resolveRuntimeUrl(created.data.runtimeUrl, options),
         };
         created.dispose();
 
@@ -743,8 +743,8 @@ async function runScenario(
         recordSkippedStep(steps, 'filesystem.download', 'Enable with --include-download.');
       }
 
-      await runCheckedStep('shell.exec', async () => {
-        const result = await notebook!.shell.exec(['php', 'artisan', '--version']);
+      await runCheckedStep('shell.run', async () => {
+        const result = await notebook!.run(['php', 'artisan', '--version']).wait();
         result.throw();
         if (!result.output.toLowerCase().includes('laravel')) {
           throw new Error(`Unexpected artisan version output: ${trimDetail(result.output)}`);
@@ -754,21 +754,22 @@ async function runScenario(
       }, { skipIf: explainUnsupportedShell });
 
       await runCheckedStep(
-        'shell.exec-stream',
+        'shell.run-stream',
         async () => {
-          const execution = notebook!.shell.execStream(
-            ['php', 'artisan', 'route:list', `--path=${routeUrlPath}`]
+          const execution = notebook!.run(
+            ['php', 'artisan', 'route:list', `--path=${routeUrlPath}`],
+            { tty: false },
           );
 
           const [streamOutput, result] = await Promise.all([
-            readStreamToString(execution.output, options.streamTimeoutMs, options.maxStreamChars).catch((error) => {
+            readStreamToString(execution.stdout, options.streamTimeoutMs, options.maxStreamChars).catch((error) => {
               if (isStreamInactivityError(error)) {
                 return '';
               }
 
               throw error;
             }),
-            withTimeout(execution.result, options.stepTimeoutMs, 'waiting for shell.execStream() result'),
+            withTimeout(execution.wait(), options.stepTimeoutMs, 'waiting for process exit'),
           ]);
 
           result.throw();
@@ -792,7 +793,7 @@ async function runScenario(
 
           try {
             const outputPromise = readStreamToString(process.output, options.streamTimeoutMs, options.maxStreamChars);
-            const exitPromise = withTimeout(process.exit, options.stepTimeoutMs, 'waiting for terminal process to exit');
+            const exitPromise = withTimeout(process.wait(), options.stepTimeoutMs, 'waiting for terminal process to exit');
             const [output, exitCode] = await Promise.all([outputPromise, exitPromise]);
 
             if (exitCode !== 0) {
@@ -844,12 +845,6 @@ async function runScenario(
         { timeoutMs: options.stepTimeoutMs * 2 }
       );
 
-      recordSkippedStep(
-        steps,
-        'laravel.maintenance',
-        'Not part of the current okra websocket action set.'
-      );
-
       await runCheckedStep('composer.metadata', async () => {
         let composerLogChunks = 0;
         const composerLogs = notebook!.composer.stream((line) => {
@@ -950,7 +945,7 @@ async function runScenario(
       if (options.reauthorizationUrl) {
         await runCheckedStep('auth.login-logout', async () => {
           await notebook!.auth.login(options.reauthorizationUrl!);
-          await notebook!.auth.logout();
+          notebook!.dispose();
           return 'ok';
         });
       } else {
@@ -1020,7 +1015,7 @@ async function cleanupNotebook(notebook: NotebookInstance, steps: StepResult[]):
       const notebookId = notebook.data.id;
       await cleanupDeleteLimiter.run(async () => {
         try {
-          await retryWithBackoff(() => notebook.delete(), DELETE_RETRY_DELAYS_MS, shouldRetryApiRateLimitError);
+          await retryWithBackoff(() => notebook.destroy(), DELETE_RETRY_DELAYS_MS, shouldRetryApiRateLimitError);
         } catch (error) {
           if (formatError(error).includes('Notebook has been deleted')) {
             return;
@@ -1912,7 +1907,7 @@ function firstFulfilled<T>(promises: Array<Promise<T>>): Promise<T> {
 }
 
 async function readStreamToString(
-  stream: ReadableStream<string>,
+  stream: ReadableStream<string | Uint8Array>,
   timeoutMs: number,
   maxChars: number
 ): Promise<string> {
@@ -1926,7 +1921,7 @@ async function readStreamToString(
         break;
       }
 
-      output += chunk.value ?? '';
+      output += chunk.value instanceof Uint8Array ? new TextDecoder().decode(chunk.value) : (chunk.value ?? '');
     }
 
     return output;