@phpsandbox/sdk 0.0.51 → 0.0.52

package/examples/README.md

@@ -0,0 +1,206 @@
+## Examples
+
+### Running Basic Example
+
+```bash
+PHPSANDBOX_TOKEN=your-token npx tsx examples/basic.ts
+```
+
+### 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.
+- `--okra-origin=ws://127.0.0.1:9511` preserves the SDK-issued websocket path/auth but routes okra traffic to another host.
+- `--include-container-restart` adds a mutable `container.start()` 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.
+- `--auth-payload=...` exercises `notebook.auth.login()` / `logout()`.
+- `--mode=init` limits the scenario to notebook create, ready, and delete 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, delete
+- 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
+- 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 real connection payload
+- `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
+
+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 okra host:
+
+```bash
+PHPSANDBOX_TOKEN=your-token npx tsx examples/notebook-readonly-smoke.ts \
+  --notebook-id=gypjc \
+  --okra-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.
+
+### Okra Operator Loop
+
+For repeatable prod investigations, use the operator CLI:
+
+```bash
+npx tsx tools/okra-loop.ts run --label=init-64-96 -- --levels=64,80,96 --waves=2 --mode=init
+```
+
+If you omit the load-test level flags entirely, the operator loop defaults to a conservative staircase:
+
+```bash
+npx tsx tools/okra-loop.ts run --label=quick-probe
+```
+
+That default probe uses `--levels=1,2,4,8,12,16,24,32,48,64,80,96` and enables `--stop-on-failure-level` so you get the first failing boundary quickly.
+
+This will:
+
+- run the Laravel load test and save `load-test.json`, stdout, and stderr into `artifacts/okra-loop/<timestamp>-<label>/`
+- capture before/after snapshots from `okra-main`, `okra-helfer`, and `okra-helfer-prime`
+- sample remote load/memory/supervisor state during the run
+- write `analysis.json` plus a `report.md` with hotspot heuristics and next actions
+
+Useful operator flags:
+
+- `--hosts=none` disables SSH collection, which is useful for local API runs.
+- `--deploy-hosts=workers` deploys the local okra checkout to `okra-helfer` and `okra-helfer-prime` before the run.
+- `--artifact-root=...` changes where run artifacts are stored.
+- `--sample-interval-ms=15000` adjusts the SSH sampling interval.
+
+Deploy only:
+
+```bash
+npx tsx tools/okra-loop.ts deploy --deploy-hosts=workers
+```

package/examples/basic.ts

@@ -0,0 +1,24 @@
+import { PHPSandbox } from '../src/index.js';
+
+const token = process.env.PHPSANDBOX_TOKEN;
+if (!token) {
+  throw new Error('Missing PHPSANDBOX_TOKEN');
+}
+
+const psb = new PHPSandbox(token);
+const notebook = await psb.notebook.create('laravel');
+
+console.log('====== Ping the notebook ======');
+console.log('Response:', await notebook.ping());
+console.log('====== Notebook is ready ======');
+
+console.log('\n');
+
+console.log('====== Read routes/web.php in the notebook ======');
+const decoder = new TextDecoder();
+const content = await notebook.file.readFile('routes/web.php');
+console.log(decoder.decode(content));
+
+// Always close the notebook when done to clean up the connection.
+notebook.dispose();
+await notebook.delete();

package/examples/get.ts

@@ -0,0 +1,21 @@
+import { Client } from '../src/index.js';
+
+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 = new Client(token, apiUrl);
+const notebook = await client.notebook.get(notebookId);
+
+try {
+  console.log(await notebook.mail.status());
+} finally {
+  notebook.dispose();
+}

package/examples/git-merge-smoke.ts

@@ -0,0 +1,415 @@
+import fs from 'node:fs/promises';
+import https from 'node:https';
+import axios from 'axios';
+import NodeWebSocket from 'ws';
+import { PHPSandbox, type GitDiffPreview, type GitMergeResult, type NotebookInstance } from '../src/index.js';
+
+const DEFAULT_API_URL = 'https://api.phpsandbox.io/v1';
+const DEFAULT_LOCAL_API_URL = 'https://api.phpsandbox.test/v1';
+
+interface ParsedArgs {
+  get(key: string): string | boolean | undefined;
+}
+
+interface Options {
+  token: string;
+  notebookId: string;
+  apiUrl: string;
+  ref: string;
+  author: string;
+  message: string;
+  editPath: string;
+  editContent?: string;
+  local: boolean;
+  apply: boolean;
+  deleteFork: boolean;
+  allowCheckpoint: boolean;
+  insecureTls: boolean;
+  caFile?: string;
+}
+
+async function main(): Promise<void> {
+  const options = parseOptions(process.argv.slice(2));
+  const transport = await createNodeTransport(options);
+  const client = new PHPSandbox(options.token, options.apiUrl, {
+    startClosed: true,
+    ...transport,
+  });
+
+  let base: NotebookInstance | null = null;
+  let fork: NotebookInstance | null = null;
+  let shouldDeleteFork = false;
+
+  try {
+    base = await client.notebook.open(options.notebookId);
+    console.log(`Base notebook: ${base.data.id}`);
+
+    await base.ready();
+    await ensureBaseCheckpoint(base, options);
+
+    fork = await base.fork();
+    shouldDeleteFork = options.deleteFork;
+    console.log(`Fork notebook: ${fork.data.id}`);
+
+    await fork.ready();
+    const editContent = buildEditContent(base.data.id, fork.data.id, options);
+    const written = await fork.file.write(options.editPath, editContent);
+    if (!written) {
+      throw new Error(`fs.write returned false for ${options.editPath}.`);
+    }
+    console.log(`Edited fork file: ${options.editPath}`);
+
+    const forkCheckpoint = await fork.git.checkpoint(options.author, `Smoke edit in fork ${fork.data.id}`, options.ref, false);
+    console.log(`Fork checkpoint: ${forkCheckpoint.ref}`);
+
+    const forkCredentials = await fork.git.credentials();
+    console.log(`Diff source: ${redactUrl(forkCredentials.url)}`);
+
+    const preview = await retry(
+      () =>
+        base!.git.diff({
+          url: forkCredentials.url,
+          token: forkCredentials.token,
+          ref: options.ref,
+        }),
+      5,
+      1_000
+    );
+    printPreview(preview);
+
+    if (!options.apply) {
+      console.log('Merge skipped. Pass --apply to mutate the base notebook.');
+      return;
+    }
+
+    const merge = await base.git.merge({
+      url: forkCredentials.url,
+      token: forkCredentials.token,
+      ref: options.ref,
+      expectedBaseRef: preview.baseRef,
+      author: options.author,
+      message: options.message,
+    });
+    printMerge(merge);
+
+    if (merge.status === 'conflict') {
+      shouldDeleteFork = false;
+    }
+  } finally {
+    if (shouldDeleteFork && fork) {
+      try {
+        await fork.delete();
+        console.log(`Deleted fork notebook: ${fork.data.id}`);
+      } catch (error) {
+        console.error(`Could not delete fork notebook ${fork.data.id}: ${formatError(error)}`);
+      }
+    }
+
+    fork?.dispose();
+    base?.dispose();
+  }
+}
+
+async function ensureBaseCheckpoint(base: NotebookInstance, options: Options): Promise<void> {
+  const status = await base.git.status();
+  console.log(`Base Git: initialized=${status.initialized} clean=${status.clean} branch=${status.branch || '-'} ref=${status.ref || '-'}`);
+
+  if (status.initialized && status.clean) {
+    return;
+  }
+
+  if (!options.allowCheckpoint) {
+    const reason = status.initialized
+      ? 'Base notebook has uncommitted changes.'
+      : 'Base notebook Git repository is not initialized.';
+    throw new Error(`${reason} Re-run with --allow-checkpoint to create a base checkpoint before forking.`);
+  }
+
+  const checkpoint = await base.git.checkpoint(
+    options.author,
+    status.initialized ? 'Base checkpoint before fork merge smoke' : 'Initialize base Git history for fork merge smoke',
+    options.ref,
+    !status.initialized
+  );
+  console.log(`Base checkpoint: ${checkpoint.ref}`);
+}
+
+function buildEditContent(baseId: string, forkId: string, options: Options): string {
+  if (options.editContent !== undefined) {
+    return options.editContent;
+  }
+
+  return [
+    'PHPSandbox Git merge smoke',
+    `base=${baseId}`,
+    `fork=${forkId}`,
+    `createdAt=${new Date().toISOString()}`,
+    '',
+  ].join('\n');
+}
+
+function printPreview(preview: GitDiffPreview): void {
+  console.log(`Diff: status=${preview.status} base=${preview.baseRef || '-'} target=${preview.targetRef || '-'}`);
+  if (preview.status === 'unrelated') {
+    console.log(preview.message ?? 'Base and source do not share Git history.');
+    return;
+  }
+
+  console.log(`Changed files: ${preview.files.length}`);
+  for (const file of preview.files.slice(0, 20)) {
+    const oldPath = file.oldPath ? `${file.oldPath} -> ` : '';
+    console.log(`- ${file.status} ${oldPath}${file.path}`);
+  }
+  if (preview.files.length > 20) {
+    console.log(`- ... ${preview.files.length - 20} more`);
+  }
+}
+
+function printMerge(merge: GitMergeResult): void {
+  console.log(`Merge: status=${merge.status}`);
+  if ('message' in merge && merge.message) {
+    console.log(merge.message);
+  }
+
+  if (merge.status === 'conflict') {
+    for (const conflict of merge.conflicts) {
+      console.log(`- ${conflict.status} ${conflict.file} (${conflict.type})`);
+    }
+    return;
+  }
+
+  if ('ref' in merge && merge.ref) {
+    console.log(`Result ref: ${merge.ref}`);
+  }
+}
+
+function parseOptions(argv: string[]): Options {
+  const args = parseArgs(argv);
+
+  if (booleanArg(args, 'help') === true) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const token = stringArg(args, 'token') ?? process.env.PHPSANDBOX_TOKEN;
+  if (!token) {
+    throw new Error('Missing PHPSANDBOX_TOKEN. Pass it via the environment or --token.');
+  }
+
+  const local = booleanArg(args, 'local') ?? false;
+  const notebookId = stringArg(args, 'notebook-id') ?? '10ywr';
+  const caFile = stringArg(args, 'ca-file');
+
+  return {
+    token,
+    notebookId,
+    apiUrl: stringArg(args, 'api-url') ?? process.env.PHPSANDBOX_API_URL ?? (local ? DEFAULT_LOCAL_API_URL : DEFAULT_API_URL),
+    ref: stringArg(args, 'ref') ?? 'main',
+    author: stringArg(args, 'author') ?? 'PHPSandbox <hi@phpsandbox.io>',
+    message: stringArg(args, 'message') ?? `Merge fork into ${notebookId}`,
+    editPath: stringArg(args, 'edit-path') ?? 'phpsandbox-git-merge-smoke.txt',
+    editContent: stringArg(args, 'edit-content'),
+    local,
+    apply: booleanArg(args, 'apply') ?? false,
+    deleteFork: booleanArg(args, 'delete-fork') ?? false,
+    allowCheckpoint: booleanArg(args, 'allow-checkpoint') ?? false,
+    insecureTls: booleanArg(args, 'insecure-tls') ?? (local && !caFile),
+    caFile,
+  };
+}
+
+async function createNodeTransport(options: Options): Promise<{
+  fetch?: typeof globalThis.fetch;
+  webSocket?: typeof NodeWebSocket;
+}> {
+  if (!options.insecureTls && !options.caFile) {
+    return {};
+  }
+
+  if (!options.apiUrl.startsWith('https://')) {
+    return {};
+  }
+
+  const ca = options.caFile ? await fs.readFile(options.caFile, 'utf8') : undefined;
+  const agentOptions = {
+    ca,
+    rejectUnauthorized: !options.insecureTls,
+  };
+  const httpsAgent = new https.Agent(agentOptions);
+
+  class ConfiguredWebSocket extends NodeWebSocket {
+    public constructor(address: string | URL, protocols?: string | string[]) {
+      super(address, protocols, agentOptions);
+    }
+  }
+
+  const fetch: typeof globalThis.fetch = async (input, init) => {
+    const request = input instanceof Request ? input : new Request(input, init);
+    const headers: Record<string, string> = {};
+    request.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+    const body =
+      request.method === 'GET' || request.method === 'HEAD'
+        ? undefined
+        : Buffer.from(await request.arrayBuffer());
+
+    const response = await axios.request<ArrayBuffer>({
+      url: request.url,
+      method: request.method as any,
+      headers,
+      data: body,
+      responseType: 'arraybuffer',
+      validateStatus: () => true,
+      httpsAgent,
+    });
+
+    const responseHeaders = new Headers();
+    for (const [key, value] of Object.entries(response.headers)) {
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          responseHeaders.append(key, String(item));
+        }
+      } else if (value !== undefined) {
+        responseHeaders.set(key, String(value));
+      }
+    }
+
+    return new Response(response.data, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: responseHeaders,
+    });
+  };
+
+  return { fetch, webSocket: ConfiguredWebSocket as typeof NodeWebSocket };
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const values = new Map<string, string | boolean>();
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const current = argv[index];
+    if (!current.startsWith('--')) {
+      continue;
+    }
+
+    if (current.startsWith('--no-')) {
+      values.set(current.slice(5), false);
+      continue;
+    }
+
+    const assignment = current.match(/^--([^=]+)=(.*)$/);
+    if (assignment) {
+      values.set(assignment[1], assignment[2]);
+      continue;
+    }
+
+    const key = current.slice(2);
+    const next = argv[index + 1];
+    if (next && !next.startsWith('--')) {
+      values.set(key, next);
+      index += 1;
+      continue;
+    }
+
+    values.set(key, true);
+  }
+
+  return {
+    get(key: string) {
+      return values.get(key);
+    },
+  };
+}
+
+function stringArg(args: ParsedArgs, key: string): string | undefined {
+  const value = args.get(key);
+  return typeof value === 'string' && value !== '' ? value : undefined;
+}
+
+function booleanArg(args: ParsedArgs, key: string): boolean | undefined {
+  const value = args.get(key);
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  if (value === undefined) {
+    return undefined;
+  }
+  if (value === 'true' || value === '1') {
+    return true;
+  }
+  if (value === 'false' || value === '0') {
+    return false;
+  }
+  throw new Error(`Invalid --${key}: ${value}`);
+}
+
+async function retry<T>(callback: () => Promise<T>, attempts: number, delayMs: number): Promise<T> {
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      return await callback();
+    } catch (error) {
+      lastError = error;
+      if (attempt === attempts) {
+        break;
+      }
+
+      console.log(`Retrying after transient Git source lookup failure (${attempt}/${attempts}): ${formatError(error)}`);
+      await sleep(delayMs);
+    }
+  }
+
+  throw lastError;
+}
+
+function sleep(delayMs: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function redactUrl(value: string): string {
+  try {
+    const url = new URL(value);
+    if (url.username || url.password) {
+      url.username = 'redacted';
+      url.password = 'redacted';
+    }
+    if (url.search) {
+      url.search = '?redacted=1';
+    }
+    return url.toString();
+  } catch {
+    return '<invalid-url>';
+  }
+}
+
+function printHelp(): void {
+  console.log(`
+Usage:
+  PHPSANDBOX_TOKEN=... npx tsx examples/git-merge-smoke.ts --local --notebook-id=10ywr
+
+Options:
+  --notebook-id=<id>       Base notebook to open. Defaults to 10ywr.
+  --ref=<ref>              Source Git ref. Defaults to main.
+  --edit-path=<path>       File to write in the fork. Defaults to phpsandbox-git-merge-smoke.txt.
+  --edit-content=<text>    Exact content to write into edit-path.
+  --apply                  Apply merge into the base notebook after diffing.
+  --delete-fork            Delete the created fork after the smoke run.
+  --allow-checkpoint       Create a base checkpoint before forking if needed.
+  --local                  Use the local API host.
+  --api-url=<url>          API URL. Defaults to ${DEFAULT_API_URL}, or ${DEFAULT_LOCAL_API_URL} with --local.
+  --insecure-tls           Disable TLS verification for local HTTPS/WSS.
+  --ca-file=<path>         Trust a custom CA for local HTTPS/WSS.
+`);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+});