@molecule/api-code-sandbox-docker 1.0.2 → 1.1.0

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,KAAK,EAcV,eAAe,EAMhB,MAAM,4BAA4B,CAAA;AAoBnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AA6J9C;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAQ9D;AAkCD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,EAAE;IACJ,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IACjC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IACrC,GAAG,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAA;CAC1D,GACA,OAAO,CAAC,CAAC,CAAC,CA2BZ;AAyxCD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,eAAe,CAErE"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,KAAK,EAcV,eAAe,EAOhB,MAAM,4BAA4B,CAAA;AAoBnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AA6J9C;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAQ9D;AAkCD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,EAAE;IACJ,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IACjC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IACrC,GAAG,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAA;CAC1D,GACA,OAAO,CAAC,CAAC,CAAC,CA2BZ;AA21CD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,eAAe,CAErE"}

package/dist/provider.js

@@ -508,6 +508,15 @@ class DockerSandboxProvider {
             labels[`${this.labelPrefix}.volumeName`] = config.volumeName;
             hostConfig.Binds = [`${config.volumeName}:/workspace`];
         }
+        // What the container does when its main process exits. Docker's default is
+        // `no`, matching this provider's historical behaviour: a sandbox whose
+        // process exits stays stopped for the caller to inspect. A caller running
+        // something long-lived (a production instance) asks for `always`/`on-failure`
+        // so the workload comes back after a crash or a daemon restart without a
+        // control plane in the loop.
+        if (config.restartPolicy && config.restartPolicy !== 'no') {
+            hostConfig.RestartPolicy = { Name: config.restartPolicy };
+        }
         const body = {
             Image: image,
             Env: env,
@@ -515,6 +524,13 @@ class DockerSandboxProvider {
             HostConfig: hostConfig,
             ExposedPorts: Object.fromEntries(publishPorts.map((port) => [`${port}/tcp`, {}])),
         };
+        // The caller's own main process, replacing the image's CMD. Without it a
+        // container that Docker restarts comes back running the image's idle command
+        // and serving nothing, while `status` still reports it as running — which it
+        // is, and empty. `Cmd` (not `Entrypoint`) so the image's entrypoint — tini,
+        // enabled above via `Init` — still wraps it and reaps its children.
+        if (config.command?.length)
+            body.Cmd = [...config.command];
         // Retry a transient create timeout (daemon momentarily overwhelmed under
         // concurrent boots) instead of failing the whole sandbox boot. The onRetry
         // guard adopts a container a timed-out create may have already made — keyed on
@@ -823,17 +839,32 @@ class DockerSandboxProvider {
                 // (e.g. a per-sandbox subdomain `sb-{port}.preview.localhost:{port}`).
                 return provider.previewUrlTemplate.replace(/\{port\}/g, String(port ?? 5173));
             },
+            /**
+             * Spawn a long-running process with streaming I/O, optionally on a PTY.
+             *
+             * `opts.pty` asks Docker for `Tty: true`, which gives the process a real
+             * controlling terminal: Ctrl-C (`0x03`) becomes SIGINT for the foreground
+             * job and the width can be renegotiated through `handle.resize()`. A TTY
+             * exec stream is NOT multiplexed, so the frame parser is bypassed and
+             * everything (stderr included, as on a real terminal) arrives on stdout.
+             *
+             * @param command - The command to run.
+             * @param opts - Working directory, env, and optional PTY size.
+             * @returns A handle with streaming I/O, stdin, kill, and (on a PTY) resize.
+             */
             async spawn(command, opts) {
+                const tty = Boolean(opts?.pty);
                 const execCreate = (await provider.dockerApi(`/containers/${containerId}/exec`, 'POST', {
                     Cmd: ['sh', '-c', command],
                     AttachStdin: true,
                     AttachStdout: true,
                     AttachStderr: true,
-                    Tty: false,
+                    Tty: tty,
+                    ...(opts?.pty ? { ConsoleSize: [opts.pty.rows, opts.pty.cols] } : {}),
                     WorkingDir: opts?.cwd ?? '/workspace',
                     Env: opts?.env ? Object.entries(opts.env).map(([k, v]) => `${k}=${v}`) : undefined,
                 }));
-                const socket = await provider.dockerExecUpgrade(execCreate.Id);
+                const socket = await provider.dockerExecUpgrade(execCreate.Id, tty);
                 const parser = new DockerMuxParser();
                 let closeCb = null;
                 // Kill idle spawn sockets after 10 minutes to prevent descriptor leaks
@@ -841,7 +872,17 @@ class DockerSandboxProvider {
                 socket.on('timeout', () => {
                     socket.destroy();
                 });
+                // A TTY exec stream carries raw terminal bytes — there are no 8-byte
+                // frame headers to strip, and feeding them to the mux parser would read
+                // the first byte of the shell's output as a stream descriptor.
+                const ttyListeners = [];
                 socket.on('data', (chunk) => {
+                    if (tty) {
+                        const text = chunk.toString('utf8');
+                        for (const cb of ttyListeners)
+                            cb(text);
+                        return;
+                    }
                     try {
                         parser.feed(chunk);
                     }
@@ -867,10 +908,16 @@ class DockerSandboxProvider {
                             socket.write(data);
                     },
                     onStdout(cb) {
-                        parser.onStdout(cb);
+                        if (tty)
+                            ttyListeners.push(cb);
+                        else
+                            parser.onStdout(cb);
                     },
                     onStderr(cb) {
-                        parser.onStderr(cb);
+                        // On a TTY both streams share one descriptor, so nothing arrives
+                        // here — registering is harmless and keeps the handle uniform.
+                        if (!tty)
+                            parser.onStderr(cb);
                     },
                     onClose(cb) {
                         closeCb = cb;
@@ -879,6 +926,22 @@ class DockerSandboxProvider {
                         if (!socket.destroyed)
                             socket.destroy();
                     },
+                    ...(tty
+                        ? {
+                            resize(size) {
+                                void provider
+                                    .dockerApi(`/exec/${execCreate.Id}/resize?h=${Math.max(1, Math.floor(size.rows))}&w=${Math.max(1, Math.floor(size.cols))}`, 'POST')
+                                    .catch((error) => {
+                                    // Best-effort: a resize races the exec exiting, and a
+                                    // failed one only leaves the remote width stale — never a
+                                    // reason to tear down a live session.
+                                    logger.debug('Spawn resize failed', {
+                                        error: error instanceof Error ? error.message : error,
+                                    });
+                                });
+                            },
+                        }
+                        : {}),
                 };
             },
             async hibernate() {
@@ -1311,11 +1374,14 @@ class DockerSandboxProvider {
      * bidirectional socket. Docker hijacks the connection (101 Switching Protocols)
      * when stdin is attached, giving us a raw TCP socket for streaming I/O.
      * @param execId - The exec instance ID from the create step.
+     * @param tty - Whether the exec was created with a TTY; the start call must
+     *   agree, or Docker streams multiplexed frames to a terminal expecting raw
+     *   bytes.
      * @returns The raw socket for stdin writes and multiplexed stdout/stderr reads.
      */
-    dockerExecUpgrade(execId) {
+    dockerExecUpgrade(execId, tty = false) {
         return new Promise((resolve, reject) => {
-            const body = JSON.stringify({ Detach: false, Tty: false });
+            const body = JSON.stringify({ Detach: false, Tty: tty });
             const req = http.request({
                 ...this.endpoint,
                 path: `/v1.44/exec/${execId}/start`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-code-sandbox-docker",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Docker-based code sandbox container provider",
   "type": "module",
   "main": "dist/index.js",
@@ -30,14 +30,14 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "@molecule/api-bond": "1.0.1",
-    "@molecule/api-code-sandbox": "1.0.2",
+    "@molecule/api-code-sandbox": "1.2.0",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
     "vitest": "4.1.10"
   },
   "peerDependencies": {
     "@molecule/api-bond": "^1.0.1",
-    "@molecule/api-code-sandbox": "^1.0.1",
+    "@molecule/api-code-sandbox": "^1.2.0",
     "@molecule/api-i18n": "^1.0.1"
   },
   "peerDependenciesMeta": {