@phpsandbox/sdk 0.1.13 → 0.1.15

package/docs/getting-started.md

@@ -1,169 +0,0 @@
-# Getting Started with PHPSandbox SDK
-
-This guide walks through the fastest path from install to a working notebook.
-
-## Prerequisites
-
-- Node.js 18+
-- A PHPSandbox account with an active subscription and available notebook capacity
-- SDK access enabled and an API key created in **API keys**
-
-## Install
-
-```bash
-npm install @phpsandbox/sdk
-```
-
-Copy the API key when shown and store it in `PHPSANDBOX_TOKEN` in your server environment or secret store. Keys are shown once and grant notebook read and write access; never include them in frontend bundles or commit them. If **API keys** is unavailable, request SDK access first.
-
-For a complete runnable example, save the [root quick start](../README.md#quick-start) as `quickstart.mjs` and run `node quickstart.mjs`. The snippets below explain individual operations.
-
-## 1. Create a Client
-
-```ts
-import { PHPSandbox } from '@phpsandbox/sdk';
-
-const token = process.env.PHPSANDBOX_TOKEN;
-if (!token) throw new Error('Missing PHPSANDBOX_TOKEN');
-
-const client = PHPSandbox.realtime(token);
-```
-
-## 2. Create or Open a Notebook
-
-```ts
-const notebook = await client.notebook.create('standard');
-
-const persistent = await client.notebook.create('laravel', {
-  title: 'Persistent Laravel',
-  persistent: true,
-});
-
-const existing = await client.notebook.get('notebook-id');
-
-const fork = await existing.fork();
-const persistentFork = await existing.fork({ persistent: true });
-```
-
-API notebook creates and forks are ephemeral by default. Use `persistent: true` only when your account is allowed to create persistent notebooks.
-
-## 3. Write and Read Files
-
-```ts
-await notebook.files.write('hello.php', '<?php echo "Hello";');
-
-const data = await notebook.files.read('hello.php');
-const text = new TextDecoder().decode(data);
-
-console.log(text);
-```
-
-The same `write()` method accepts text, bytes, readable streams, and async iterables:
-
-```ts
-await notebook.files.write('binary.dat', new Uint8Array([1, 2, 3]), {
-  create: true,
-  overwrite: true,
-  unlock: false,
-  atomic: false,
-});
-```
-
-## 4. Run Commands
-
-### Terminal (stream output)
-
-```ts
-const task = await notebook.terminals.create({ command: 'php', args: ['hello.php'] });
-const reader = task.output.getReader();
-
-while (true) {
-  const { done, value } = await reader.read();
-  if (done) break;
-  process.stdout.write(value);
-}
-reader.releaseLock();
-
-const exitCode = await task.wait();
-console.log(`\nExit code: ${exitCode}`);
-```
-
-### Shell (single command result)
-
-```ts
-const result = await notebook.exec('php -v', { tty: false });
-if (result.exitCode !== 0) throw new Error(result.stderr || result.output);
-console.log(result.stdout);
-```
-
-## 5. Search and Watch Files
-
-```ts
-const matches = await notebook.files.find('*.php', {
-  includes: ['app/**'],
-  excludes: ['vendor/**'],
-});
-
-console.log(matches.map((match) => match.path));
-
-const watcher = await notebook.files.watch(
-  '/app',
-  {
-    recursive: true,
-    excludes: ['vendor/**', 'node_modules/**'],
-  },
-  (change) => {
-    console.log(change.type, change.path);
-  }
-);
-
-// later
-watcher.dispose();
-```
-
-## 6. Use Composer and Git
-
-```ts
-const installResult = await notebook.composer.run('install').wait();
-if (installResult.exitCode !== 0) throw new Error(installResult.stderr || installResult.output);
-
-const requireResult = await notebook.composer.run('require', { packages: ['monolog/monolog'] }).wait();
-if (requireResult.exitCode !== 0) throw new Error(requireResult.stderr || requireResult.output);
-
-await notebook.git.checkpoint('Jane Doe <jane@example.com>', 'Initial checkpoint');
-```
-
-## 7. Clean Up
-
-Use a `finally` block to dispose every connection, including forks and notebooks opened with `get()`. `dispose()` only closes local resources. For temporary automation, delete the remote notebook as well:
-
-```ts
-try {
-  await notebook.destroy();
-} finally {
-  notebook.dispose();
-}
-```
-
-Omit `destroy()` only when you intend to keep the notebook. Stopping a notebook does not delete it. Ephemeral notebooks are eventually pruned according to `notebook.data.policy`; do not rely on that as immediate cleanup.
-
-## Common Pitfalls
-
-- Runtime actions wait for readiness. Call `ready()` only when you need its provisioning metadata.
-- `files.watch()` requires an `excludes` array.
-- Command results include `exitCode`; decide explicitly whether a non-zero exit should fail your workflow.
-
-## Troubleshooting
-
-- `401`: check that the API key is set and has not been revoked.
-- `403`: check permissions, account subscription, notebook capacity, and persistence entitlement.
-- `404`: the notebook is missing or inaccessible to your account.
-- `422`: use `RemoteError.isValidation(error)` to inspect field errors; `standard` is the plain PHP template ID.
-- `429`: respect `error.response.headers.get('Retry-After')` and reduce concurrency. Avoid blind retries of resource creation or publication.
-- A process stays alive after the script finishes: ensure all notebook instances are disposed in `finally`.
-
-## Next Reading
-
-- API overview: [API overview](api-summary.md)
-- CDN/browser usage: [Browser usage](cdn-usage.md)
-- Root quick start: [Root quick start](../README.md)

package/examples/README.md

@@ -1,203 +0,0 @@
-## Examples
-
-Examples import the published `@phpsandbox/sdk` package. From a source checkout, run `npm ci && npm run build` first. Set `PHPSANDBOX_TOKEN` using your environment or secret store. The basic example creates and deletes one temporary notebook; publication examples can change deployments and provider resources.
-
-### Running Basic Example
-
-```bash
-PHPSANDBOX_TOKEN=your-token npx tsx examples/basic.ts
-```
-
-### Running Publication Examples
-
-Cloudflare Containers target:
-
-```bash
-PHPSANDBOX_TOKEN=your-token PHPSANDBOX_NOTEBOOK_ID=notebook-id \
-  npx tsx examples/publish-cloudflare-container.ts
-```
-
-SSH agent target:
-
-```bash
-PHPSANDBOX_TOKEN=your-token PHPSANDBOX_NOTEBOOK_ID=notebook-id \
-  npx tsx examples/publish-ssh-agent.ts
-```
-
-Laravel Cloud target:
-
-```bash
-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/publish-laravel-cloud.ts
-```
-
-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 links or refreshes the GitHub and Laravel Cloud integrations, attaches each provider to the sandbox, synchronizes the notebook to `PHPSANDBOX_LARAVEL_CLOUD_REPOSITORY`, and publishes through the attached Laravel Cloud integration.
-
-### Running The Laravel Load Test
-
-When stdout is a TTY, the load test renders a live dashboard with current stage, active scenarios, and rolling results. When output is redirected or piped, it falls back to plain logs.
-
-Baseline one sandbox:
-
-```bash
-PHPSANDBOX_TOKEN=your-token npx tsx examples/laravel-load-test.ts --levels=1
-```
-
-Init-only baseline one sandbox:
-
-```bash
-PHPSANDBOX_TOKEN=your-token npx tsx examples/laravel-load-test.ts --levels=1 --mode=init
-```
-
-Creation/provisioning parity baseline for a fresh Laravel notebook:
-
-```bash
-PHPSANDBOX_TOKEN=your-token npx tsx examples/laravel-load-test.ts \
-  --local \
-  --levels=1 \
-  --mode=init \
-  --require-init-messages="Preparing your workspace...|Setting up your project...|Opening your workspace..." \
-  --expect-provisioned=true \
-  --expect-provisioning-action=template \
-  --json-file=/tmp/phpsandbox-create-init.json
-```
-
-Ramp concurrency over multiple levels:
-
-```bash
-PHPSANDBOX_TOKEN=your-token npx tsx examples/laravel-load-test.ts --levels=1,2,4,8 --waves=3
-```
-
-Or generate levels from a max concurrency:
-
-```bash
-PHPSANDBOX_TOKEN=your-token npx tsx examples/laravel-load-test.ts --max-concurrency=10 --step=2 --waves=2
-```
-
-Local API with a self-signed certificate:
-
-```bash
-PHPSANDBOX_TOKEN=your-token npx tsx examples/laravel-load-test.ts \
-  --local \
-  --levels=1
-```
-
-Local API with a trusted CA file:
-
-```bash
-PHPSANDBOX_TOKEN=your-token npx tsx examples/laravel-load-test.ts \
-  --api-url=https://api.phpsandbox.test/v1 \
-  --ca-file=/path/to/rootCA.pem \
-  --levels=1
-```
-
-Useful flags:
-
-- `--no-cleanup` keeps every notebook after the run.
-- `--keep-failed` keeps failed notebooks for inspection. By default, failures are deleted too.
-- `--runtime-origin=ws://127.0.0.1:9511` preserves the SDK-issued websocket path/auth but routes runtime traffic to another host.
-- `--include-container-restart` adds a runtime restart check on the fresh notebook.
-- `--include-download` adds `file.download()` to the baseline.
-- `--include-preview` fetches the initialized preview URL in init mode, or the route written by the scenario in full mode.
-- `--include-lsp` adds an LSP initialize handshake to the baseline.
-- `--require-init-messages="Preparing...|Setting up...|Opening..."` asserts frontend-visible init messages were received in order.
-- `--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 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`.
-- `--json` prints a machine-readable summary after the text report.
-- `--json-file=/path/to/run.json` writes a machine-readable artifact for later analysis.
-- `--insecure-tls` disables certificate verification for local HTTPS/WSS testing.
-- `--ca-file=/path/to/rootCA.pem` trusts a custom CA for local HTTPS/WSS testing.
-
-Default baseline coverage:
-
-- 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 process execution and streams
-- terminal spawn streaming
-- services with Redis logs
-- composer metadata and autoload dump
-- git checkpoint/log
-- REPL eval
-
-Intentionally excluded by default:
-
-- `beacon`, because it needs a browser iframe runtime
-- `auth`, because it needs a fresh ticket-bearing runtime URL
-- `lsp`, because it is useful but more brittle than the rest of the headless baseline
-
-### Running A Read-Only Existing Notebook Smoke Test
-
-Use this when you want to compare an existing notebook, such as `gypjc`, without writing to it:
-
-```bash
-PHPSANDBOX_TOKEN=your-token npx tsx examples/notebook-readonly-smoke.ts \
-  --notebook-id=gypjc \
-  --json-file=/tmp/gypjc-smoke.json
-```
-
-Local API with a self-signed certificate:
-
-```bash
-PHPSANDBOX_TOKEN=your-token npx tsx examples/notebook-readonly-smoke.ts \
-  --local \
-  --notebook-id=gypjc
-```
-
-To preserve the SDK-issued notebook auth/path but route the websocket to a different runtime host:
-
-```bash
-PHPSANDBOX_TOKEN=your-token npx tsx examples/notebook-readonly-smoke.ts \
-  --notebook-id=gypjc \
-  --runtime-origin=ws://127.0.0.1:9501
-```
-
-Default smoke coverage:
-
-- notebook get, ready, and ping
-- container state and opened ports
-- filesystem directory/tree/find/read/search
-- read-only git status/log, service list, and composer packages where supported
-
-Optional flags:
-
-- `--include-exec` adds shell, terminal spawn, terminal stdin/stdout, terminal OSC, and REPL execution checks.
-- `--include-download` adds a read-only `file.download()` check for a known file.
-- `--include-preview` fetches the initialized preview URL.
-
-### Running A Git Merge Smoke Test
-
-Use this to fork a base notebook, edit the fork, checkpoint the fork, and preview the diff from the base notebook:
-
-```bash
-PHPSANDBOX_TOKEN=your-token npx tsx examples/git-merge-smoke.ts \
-  --local \
-  --notebook-id=10ywr \
-  --allow-checkpoint
-```
-
-Pass `--apply` only when you want the merge to mutate the base notebook disk:
-
-```bash
-PHPSANDBOX_TOKEN=your-token npx tsx examples/git-merge-smoke.ts \
-  --local \
-  --notebook-id=10ywr \
-  --allow-checkpoint \
-  --apply
-```
-
-By default the created fork is kept for inspection. Pass `--delete-fork` when you want the script to delete it after the run.
-
-### Repository-only operator tools
-
-The `tools/okra-loop.ts` operator utility requires the source checkout and maintainer infrastructure access. It is not included in the published package and is not part of consumer onboarding.

package/examples/basic.ts

@@ -1,15 +0,0 @@
-import { PHPSandbox } from '@phpsandbox/sdk';
-
-const token = process.env.PHPSANDBOX_TOKEN;
-if (!token) throw new Error('Missing PHPSANDBOX_TOKEN');
-
-const client = PHPSandbox.realtime(token);
-const notebook = await client.notebook.create('standard');
-
-await notebook.files.write('hello.php', '<?php echo "Hello from PHPSandbox";');
-const result = await notebook.exec('php', ['hello.php']);
-if (result.exitCode !== 0) throw new Error(result.stderr || result.output);
-console.log(result.stdout.trim());
-
-await notebook.destroy();
-notebook.dispose();

package/examples/get.ts

@@ -1,22 +0,0 @@
-import { PHPSandbox } from '@phpsandbox/sdk';
-
-const token = process.env.PHPSANDBOX_TOKEN;
-if (!token) {
-  throw new Error('Missing PHPSANDBOX_TOKEN');
-}
-
-const notebookId = process.env.PHPSANDBOX_NOTEBOOK_ID;
-if (!notebookId) {
-  throw new Error('Missing PHPSANDBOX_NOTEBOOK_ID');
-}
-
-const apiUrl = process.env.PHPSANDBOX_API_URL ?? 'https://api.phpsandbox.io/v1';
-const client = PHPSandbox.realtime(token, apiUrl);
-const notebook = await client.notebook.get(notebookId);
-
-try {
-  console.log('notebook:', notebook.data.id, notebook.data.title ?? '');
-  console.log(await notebook.mail.status());
-} finally {
-  notebook.dispose();
-}