@phpsandbox/sdk 0.1.13 → 0.1.14

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();
-}

package/examples/git-merge-smoke.ts

@@ -1,395 +0,0 @@
-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 '@phpsandbox/sdk';
-
-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 = PHPSandbox.realtime(options.token, options.apiUrl, {
-    ...transport,
-  });
-
-  let base: NotebookInstance | null = null;
-  let fork: NotebookInstance | null = null;
-  let shouldDeleteFork = false;
-
-  try {
-    base = await client.notebook.get(options.notebookId);
-    console.log(`Base notebook: ${base.data.id}`);
-
-    await base.ready();
-    await ensureBaseCheckpoint(base, options);
-
-    fork = await base.fork();
-    shouldDeleteFork = options.deleteFork;
-    const forkNotebookId = fork.data.id;
-    console.log(`Fork notebook: ${forkNotebookId}`);
-
-    await fork.ready();
-    const editContent = buildEditContent(base.data.id, forkNotebookId, options);
-    await fork.files.write(options.editPath, editContent);
-    console.log(`Edited fork file: ${options.editPath}`);
-
-    const forkCheckpoint = await fork.git.checkpoint(options.author, `Smoke edit in fork ${forkNotebookId}`, options.ref, false);
-    console.log(`Fork checkpoint: ${forkCheckpoint.ref}`);
-
-    console.log(`Diff source notebook: ${forkNotebookId}`);
-
-    const preview = await retry(
-      () =>
-        base!.git.diff({
-          notebookId: forkNotebookId,
-          token: options.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({
-      notebookId: forkNotebookId,
-      token: options.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.destroy();
-        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 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;
-});