@phpsandbox/sdk 0.1.1 → 0.1.4

package/docs/getting-started.md

@@ -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,14 +85,14 @@ 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.run('php -v', { tty: false }).exit;
+const result = await notebook.exec('php -v', { tty: false });
 result.throw();
 console.log(result.stdout);
 ```
@@ -100,14 +100,14 @@ 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');
 ```
@@ -142,8 +142,8 @@ notebook.dispose();
 ## Common Pitfalls
 
 - `get()` notebooks must call `await notebook.ready()` before tool calls.
-- `file.watch()` requires an `excludes` array.
-- Await `process.exit`, then call `result.throw()` to fail on non-zero exit codes.
+- `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
 

package/examples/basic.ts

@@ -16,7 +16,7 @@ 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');
+const content = await notebook.files.read('routes/web.php');
 console.log(decoder.decode(content));
 
 // Always close the notebook when done to clean up the connection.

package/examples/git-merge-smoke.ts

@@ -54,10 +54,7 @@ async function main(): Promise<void> {
 
     await fork.ready();
     const editContent = buildEditContent(base.data.id, forkNotebookId, options);
-    const written = await fork.file.write(options.editPath, editContent);
-    if (!written) {
-      throw new Error(`fs.write returned false for ${options.editPath}.`);
-    }
+    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);

package/examples/laravel-load-test.ts

@@ -389,11 +389,10 @@ async function runScenario(
   let notebook: NotebookInstance | null = null;
   let previewUrl: string | undefined;
   let logsCaptured = 0;
-  let logListener: Disposable | null = null;
+  let logReader: ReadableStreamDefaultReader<import('../src/log.js').RuntimeLogEntry> | null = null;
   let initTrace: InitTrace | undefined;
   let readyResult: NotebookInitSuccessResult | undefined;
   let initTraceDisposables: Disposable[] = [];
-  let telemetryEnabled = false;
   let redisRunning = false;
 
   const routeSlug = id.toLowerCase();
@@ -560,12 +559,19 @@ async function runScenario(
     }
 
     if (options.mode !== 'init') {
-      logListener = notebook.log.stream((line) => {
-        if (line.trim().length > 0) {
-          logsCaptured += 1;
-          ui.updateScenarioLogs(id, logsCaptured);
+      logReader = notebook.logs.follow().getReader();
+      void (async () => {
+        while (logReader) {
+          const entry = await logReader.read();
+          if (entry.done) {
+            return;
+          }
+          if (entry.value.message.trim().length > 0) {
+            logsCaptured += 1;
+            ui.updateScenarioLogs(id, logsCaptured);
+          }
         }
-      });
+      })().catch(() => {});
 
       await runCheckedStep('notebook.ping', () => notebook!.ping(), { continueOnError: false });
 
@@ -599,8 +605,8 @@ async function runScenario(
       });
 
       await runCheckedStep('container.state', async () => {
-        const [state, ports] = await Promise.all([notebook!.container.state(), notebook!.container.openedPorts()]);
-        const portInfo = assertPortInfoList(ports, 'container.openedPorts');
+        const [state, ports] = await Promise.all([notebook!.container.state(), notebook!.ports.list()]);
+        const portInfo = assertPortInfoList(ports, 'ports.list');
         return `${state.state} (${describePorts(portInfo)})`;
       });
 
@@ -609,11 +615,11 @@ async function runScenario(
           'container.restart',
           async () => {
             await notebook!.container.start();
-            const [state, ports] = await Promise.all([notebook!.container.state(), notebook!.container.openedPorts()]);
+            const [state, ports] = await Promise.all([notebook!.container.state(), notebook!.ports.list()]);
             if (state.state !== 'running') {
               throw new Error(`Expected running container after restart, got ${state.state}`);
             }
-            return `${state.state} (${describePorts(assertPortInfoList(ports, 'container.openedPorts after restart'))})`;
+            return `${state.state} (${describePorts(assertPortInfoList(ports, 'ports.list after restart'))})`;
           },
           { timeoutMs: options.stepTimeoutMs * 3, continueOnError: false }
         );
@@ -626,29 +632,20 @@ async function runScenario(
         async () =>
           retryWithBackoff(
             async () => {
-              const statsPromise = waitForNextEvent<ContainerStats>(
-                (handler) => notebook!.container.listen('container.stats', handler),
-                options.telemetryTimeoutMs,
-                'container.stats'
-              );
-              void statsPromise.catch(() => undefined);
-              const portsPromise = waitForNextEvent<PortInfo[]>(
-                (handler) => notebook!.container.listen('container.ports', handler),
-                options.telemetryTimeoutMs,
-                'container.ports'
-              );
-              void portsPromise.catch(() => undefined);
-
-              await notebook!.container.enableTelemetry(new Set(['stats', 'ports']));
-              telemetryEnabled = true;
-
-              return await firstFulfilled([
-                statsPromise.then(
-                  (stats) =>
-                    `cpu=${stats.cpu.usage}/${stats.cpu.limit} memory=${stats.memory.usage}/${stats.memory.limit}`
-                ),
-                portsPromise.then((ports) => describePorts(assertPortInfoList(ports, 'container.ports'))),
-              ]);
+              const statsReader = notebook!.metrics.watch().getReader();
+              const portsReader = notebook!.ports.watch().getReader();
+              try {
+                const statsPromise = withTimeout(statsReader.read(), options.telemetryTimeoutMs, 'metrics.watch')
+                  .then(({ value }) => {
+                    if (!value) throw new Error('metrics.watch ended before a sample was received.');
+                    return `cpu=${value.cpu.usage}/${value.cpu.limit} memory=${value.memory.usage}/${value.memory.limit}`;
+                  });
+                const portsPromise = withTimeout(portsReader.read(), options.telemetryTimeoutMs, 'ports.watch')
+                  .then(({ value }) => describePorts(assertPortInfoList(value ?? [], 'ports.watch')));
+                return await firstFulfilled([statsPromise, portsPromise]);
+              } finally {
+                await Promise.all([statsReader.cancel(), portsReader.cancel()]);
+              }
             },
             TELEMETRY_RETRY_DELAYS_MS,
             shouldRetryTelemetryError
@@ -660,7 +657,7 @@ async function runScenario(
         'filesystem.watch-and-write',
         async () => {
           const changeSeen = createDeferred<FileChange>();
-          const watch = await notebook!.file.watch(
+          const watch = await notebook!.files.watch(
             'routes',
             { recursive: true, excludes: ['vendor/**', 'node_modules/**'] },
             (change) => {
@@ -671,12 +668,9 @@ async function runScenario(
           );
 
           try {
-            const current = textDecoder.decode(await notebook!.file.readFile(routePath));
+            const current = textDecoder.decode(await notebook!.files.read(routePath));
             const next = appendRouteDefinition(current, id, routeUrlPath);
-            const written = await notebook!.file.write(routePath, next);
-            if (!written) {
-              throw new Error(`fs.write returned false for ${routePath}.`);
-            }
+            await notebook!.files.write(routePath, next);
 
             const change = await withTimeout(
               changeSeen.promise,
@@ -692,14 +686,13 @@ async function runScenario(
       );
 
       await runCheckedStep('filesystem.inspect', async () => {
-        const [raw, info, stat, directory, tree, found, tail] = await Promise.all([
-          notebook!.file.readFile(routePath),
-          notebook!.file.info(routePath),
-          notebook!.file.stat(routePath),
-          notebook!.file.readDirectory('routes'),
-          notebook!.file.tree('routes'),
-          notebook!.file.find(routeFileName, { includes: ['routes/**'], maxResults: 10 }),
-          notebook!.file.tail(routePath, 20),
+        const [raw, stat, directory, tree, found, tail] = await Promise.all([
+          notebook!.files.read(routePath),
+          notebook!.files.stat(routePath),
+          notebook!.files.list('routes'),
+          notebook!.files.tree('routes'),
+          notebook!.files.find(routeFileName, { includes: ['routes/**'], maxResults: 10 }),
+          notebook!.files.tail(routePath, { lines: 20 }),
         ]);
 
         const text = textDecoder.decode(raw);
@@ -707,7 +700,7 @@ async function runScenario(
           throw new Error(`Expected ${routeUrlPath} in ${routePath}.`);
         }
 
-        const [, matches] = await notebook!.file.search(
+        const [, matches] = await notebook!.files.search(
           { pattern: routeUrlPath },
           { includes: [routePath], excludes: [], maxResults: 10 }
         );
@@ -716,12 +709,12 @@ async function runScenario(
           throw new Error(`file.search() did not find ${routeUrlPath}.`);
         }
 
-        const exists = await notebook!.file.exists(routePath);
+        const exists = await notebook!.files.exists(routePath);
         if (!exists) {
           throw new Error(`${routePath} does not exist after write.`);
         }
 
-        return `size=${stat.size} info=${info.language} dir=${directory.length} tree-lines=${tree.split('\n').length} find=${found.length} tail=${tail.length}`;
+        return `size=${stat.size} dir=${directory.length} tree-lines=${tree.split('\n').length} find=${found.length} tail=${tail.length}`;
       });
 
       if (options.includePreview) {
@@ -732,7 +725,10 @@ async function runScenario(
 
       if (options.includeDownload) {
         await runCheckedStep('filesystem.download', async () => {
-          const archive = await notebook!.file.download(undefined, ['vendor/**', 'node_modules/**'], [routePath, 'composer.json']);
+          const archive = await notebook!.files.download({
+            exclude: ['vendor/**', 'node_modules/**'],
+            include: [routePath, 'composer.json'],
+          });
           if (archive.size === 0) {
             throw new Error('file.download() returned an empty blob.');
           }
@@ -784,12 +780,12 @@ async function runScenario(
       );
 
       await runCheckedStep(
-        'terminal.spawn',
+        'terminals.create',
         async () => {
-          const process = await notebook!.terminal.spawn(
-            'php',
-            ['artisan', 'route:list', `--path=${routeUrlPath}`]
-          );
+          const process = await notebook!.terminals.create({
+            command: 'php',
+            args: ['artisan', 'route:list', `--path=${routeUrlPath}`],
+          });
 
           try {
             const outputPromise = readStreamToString(process.output, options.streamTimeoutMs, options.maxStreamChars);
@@ -797,7 +793,7 @@ async function runScenario(
             const [output, exitCode] = await Promise.all([outputPromise, exitPromise]);
 
             if (exitCode !== 0) {
-              throw new Error(`terminal.spawn() exited with ${exitCode}: ${trimDetail(output)}`);
+              throw new Error(`terminals.create() exited with ${exitCode}: ${trimDetail(output)}`);
             }
 
             if (!output.includes(routeUrlPath)) {
@@ -820,7 +816,7 @@ async function runScenario(
           redisRunning = started.running || started.state === 'running' || started.state === 'starting';
 
           const stream = notebook!.services.logs('redis', { follow: true, tail: 25 });
-          const reader = stream.output.getReader();
+          const reader = stream.getReader();
 
           try {
             const [snapshot, chunk] = await Promise.all([
@@ -837,7 +833,6 @@ async function runScenario(
           } finally {
             await reader.cancel().catch(() => undefined);
             reader.releaseLock();
-            await stream.stop().catch(() => false);
             await notebook!.services.stop('redis').catch(() => started);
             redisRunning = false;
           }
@@ -847,25 +842,20 @@ async function runScenario(
 
       await runCheckedStep('composer.metadata', async () => {
         let composerLogChunks = 0;
-        const composerLogs = notebook!.composer.stream((line) => {
-          if (line.trim().length > 0) {
+        const dump = notebook!.composer.dumpAutoload();
+        for await (const chunk of dump.output) {
+          if (chunk.data.byteLength > 0) {
             composerLogChunks += 1;
           }
-        });
-
-        try {
-          const [packages, dump] = await Promise.all([notebook!.composer.packages(), notebook!.composer.dumpAutoload()]);
-          if (!dump.success) {
-            throw new Error(dump.message || 'composer.dumpAutoload() failed.');
-          }
-          if (packages.length === 0) {
-            throw new Error('composer.packages() returned no packages.');
-          }
+        }
 
-          return `packages=${packages.length} composer-log-events=${composerLogChunks}`;
-        } finally {
-          composerLogs.dispose();
+        (await dump.wait()).throw();
+        const packages = await notebook!.composer.packages();
+        if (packages.length === 0) {
+          throw new Error('composer.packages() returned no packages.');
         }
+
+        return `packages=${packages.length} composer-log-events=${composerLogChunks}`;
       }, { timeoutMs: Math.max(options.stepTimeoutMs * 2, 120_000) });
 
       await runCheckedStep('git.checkpoint', async () => {
@@ -960,11 +950,8 @@ async function runScenario(
         await notebook.services.stop('redis').catch(() => undefined);
       }
 
-      if (telemetryEnabled) {
-        await notebook.container.stopTelemetry().catch(() => undefined);
-      }
-
-      logListener?.dispose();
+      await logReader?.cancel().catch(() => undefined);
+      logReader = null;
       for (const disposable of initTraceDisposables) {
         disposable.dispose();
       }

package/examples/notebook-readonly-smoke.ts

@@ -155,12 +155,12 @@ async function main(): Promise<void> {
     }, false);
 
     await recordStep(steps, 'container.opened-ports', options.stepTimeoutMs, async () => {
-      const ports = await notebook!.container.openedPorts();
-      return describePorts(assertPortInfoList(ports, 'container.openedPorts'));
+      const ports = await notebook!.ports.list();
+      return describePorts(assertPortInfoList(ports, 'ports.list'));
     }, false);
 
     const rootSnapshot = await recordStep(steps, 'filesystem.root', options.stepTimeoutMs, async () => {
-      const rootEntries = await notebook!.file.readDirectory('/');
+      const rootEntries = await notebook!.files.list('/');
 
       const preferred = ['composer.json', 'index.php', 'artisan'];
       const rootNames = new Set(rootEntries.map(([name]) => name));
@@ -174,7 +174,7 @@ async function main(): Promise<void> {
     const treePath = rootSnapshot.candidate === 'artisan' ? 'routes' : undefined;
     if (treePath) {
       await recordStep(steps, 'filesystem.tree', options.stepTimeoutMs, async () => {
-        const tree = await notebook!.file.tree(treePath);
+        const tree = await notebook!.files.tree(treePath);
         return `path=${treePath} bytes=${tree.length}`;
       }, false);
     } else {
@@ -183,8 +183,8 @@ async function main(): Promise<void> {
 
     const findSnapshot = await recordStep(steps, 'filesystem.find', options.stepTimeoutMs, async () => {
       const [composerFiles, indexFiles] = await Promise.all([
-        notebook!.file.find('composer.json', { maxResults: 10 }),
-        notebook!.file.find('index.php', { maxResults: 10 }),
+        notebook!.files.find('composer.json', { maxResults: 10 }),
+        notebook!.files.find('index.php', { maxResults: 10 }),
       ]);
       const candidate = [...composerFiles, ...indexFiles].find((file) => typeof file.path === 'string')?.path;
       return {
@@ -197,15 +197,13 @@ async function main(): Promise<void> {
 
     if (candidate) {
       await recordStep(steps, 'filesystem.read-candidate', options.stepTimeoutMs, async () => {
-        const [info, stat, content, tail] = await Promise.all([
-          notebook!.file.info(candidate),
-          notebook!.file.stat(candidate),
-          notebook!.file.readFile(candidate),
-          notebook!.file.tail(candidate, 10),
+        const [stat, content, tail] = await Promise.all([
+          notebook!.files.stat(candidate),
+          notebook!.files.read(candidate),
+          notebook!.files.tail(candidate, { lines: 10 }),
         ]);
 
-        const bytes = content instanceof Uint8Array ? content : new TextEncoder().encode(JSON.stringify(content));
-        return `path=${candidate} size=${stat.size} binary=${info.binary} sha256=${sha256(bytes)} tailBytes=${tail.length}`;
+        return `path=${candidate} size=${stat.size} sha256=${sha256(content)} tailBytes=${tail.length}`;
       }, false);
     } else {
       recordSkippedStep(steps, 'filesystem.read-candidate', 'No readable candidate file found.');
@@ -214,7 +212,10 @@ async function main(): Promise<void> {
     if (options.includeDownload) {
       if (candidate) {
         await recordStep(steps, 'filesystem.download', options.stepTimeoutMs, async () => {
-          const archive = await notebook!.file.download(undefined, ['vendor/**', 'node_modules/**'], [candidate]);
+          const archive = await notebook!.files.download({
+            exclude: ['vendor/**', 'node_modules/**'],
+            include: [candidate],
+          });
           if (archive.size === 0) {
             throw new Error('file.download() returned an empty blob.');
           }
@@ -228,7 +229,7 @@ async function main(): Promise<void> {
     }
 
     await recordStep(steps, 'filesystem.search', options.stepTimeoutMs, async () => {
-      const [hasMore, matches] = await notebook!.file.search({
+      const [hasMore, matches] = await notebook!.files.search({
         pattern: 'php',
         isRegExp: false,
         isCaseSensitive: false,
@@ -260,7 +261,7 @@ async function main(): Promise<void> {
       await runExecutionChecks(notebook, steps, options);
     } else {
       recordSkippedStep(steps, 'shell.run', 'Enable with --include-exec.');
-      recordSkippedStep(steps, 'terminal.spawn', 'Enable with --include-exec.');
+      recordSkippedStep(steps, 'terminals.create', 'Enable with --include-exec.');
       recordSkippedStep(steps, 'terminal.interactive', 'Enable with --include-exec.');
       recordSkippedStep(steps, 'terminal.osc', 'Enable with --include-exec.');
       recordSkippedStep(steps, 'repl.eval', 'Enable with --include-exec.');
@@ -332,26 +333,25 @@ async function runExecutionChecks(notebook: NotebookInstance, steps: StepArtifac
     return `exit=${result.exitCode}`;
   }, false);
 
-  await recordStep(steps, 'terminal.spawn', options.stepTimeoutMs, async () => {
-    const process = await notebook.terminal.spawn('php', ['-r', 'echo "sdk-smoke";'], { output: true });
+  await recordStep(steps, 'terminals.create', options.stepTimeoutMs, async () => {
+    const process = await notebook.terminals.create({ command: 'php', args: ['-r', 'echo "sdk-smoke";'] });
     const [exitCode, output] = await Promise.all([
       withTimeout(process.wait(), options.stepTimeoutMs, 'waiting for terminal process exit'),
       readStreamToString(process.output, options.streamTimeoutMs, options.maxStreamChars),
     ]);
 
     if (exitCode !== 0 || !output.includes('sdk-smoke')) {
-      throw new Error(`terminal.spawn failed: exit=${exitCode} output=${trimDetail(output)}`);
+      throw new Error(`terminals.create failed: exit=${exitCode} output=${trimDetail(output)}`);
     }
 
     return `exit=${exitCode}`;
   }, false);
 
   await recordStep(steps, 'terminal.interactive', options.stepTimeoutMs, async () => {
-    const process = await notebook.terminal.spawn(
-      'bash',
-      ['-lc', 'IFS= read -r line; printf "sdk-input:%s\\n" "$line"'],
-      { output: true }
-    );
+    const process = await notebook.terminals.create({
+      command: 'bash',
+      args: ['-lc', 'IFS= read -r line; printf "sdk-input:%s\\n" "$line"'],
+    });
 
     try {
       const writer = process.input.getWriter();
@@ -374,15 +374,12 @@ async function runExecutionChecks(notebook: NotebookInstance, steps: StepArtifac
   }, false);
 
   await recordStep(steps, 'terminal.osc', options.stepTimeoutMs, async () => {
-    const process = await notebook.terminal.spawn(
-      'bash',
-      ['-lc', 'printf "sdk-prompt$"'],
-      {
-        output: true,
-        osc: true,
-        terminal: { cols: 80, rows: 15 },
-      }
-    );
+    const process = await notebook.terminals.create({
+      command: 'bash',
+      args: ['-lc', 'printf "sdk-prompt$"'],
+      osc: true,
+      size: [80, 15],
+    });
 
     try {
       const [exitCode, output] = await Promise.all([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phpsandbox/sdk",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "A comprehensive TypeScript SDK for interacting with cloud-based PHP development environments",
   "main": "./dist/index.js",
   "module": "./dist/index.js",