@solarisdk/core 0.4.2 → 0.4.4

package/dist/desktop.d.ts

@@ -41,6 +41,11 @@ export declare class Desktop extends SessionHandle {
         doubleClick: (x: number, y: number, opts?: ClickOptions) => Promise<void>;
         down: (x: number, y: number, button?: MouseButton) => Promise<void>;
         up: (x: number, y: number, button?: MouseButton) => Promise<void>;
+        /**
+         * Scroll the wheel with the pointer at (x, y). `direction` defaults to "down", `amount` (wheel clicks, 1-50)
+         * to 3. The guest takes the wheel delta in the `y` field and does not move the pointer, so the pointer is moved
+         * first and (x, y) is never passed as the delta (it used to be: scroll(x, 500) fired 500 clicks, 20-30 s).
+         */
         scroll: (x: number, y: number, opts?: ScrollOptions) => Promise<void>;
         drag: (from: {
             x: number;

package/dist/desktop.js

@@ -1,4 +1,5 @@
 import { SessionHandle } from "./handle.js";
+import { SolariError } from "./errors.js";
 import { base64ToBytes } from "./transport.js";
 function buttonToCode(button) {
     if (button === undefined)
@@ -46,11 +47,19 @@ export class Desktop extends SessionHandle {
             stream: opts.stream,
         });
     }
-    execStream(cmd, onChunk, opts = {}) {
-        return this.rpcStream("exec", { cmd, args: opts.args ?? [], cwd: opts.cwd, timeoutMs: opts.timeoutMs, stream: true }, (c) => {
+    async execStream(cmd, onChunk, opts = {}) {
+        const decoders = { stdout: new TextDecoder(), stderr: new TextDecoder() };
+        const result = await this.rpcStream("exec", { cmd, args: opts.args ?? [], cwd: opts.cwd, timeoutMs: opts.timeoutMs, stream: true }, (c) => {
             const bytes = c.data ? base64ToBytes(c.data) : new Uint8Array();
-            onChunk({ stream: c.stream, text: new TextDecoder().decode(bytes), bytes });
+            const dec = decoders[c.stream] ?? decoders.stdout;
+            onChunk({ stream: c.stream, text: dec.decode(bytes, { stream: true }), bytes });
         });
+        for (const stream of ["stdout", "stderr"]) {
+            const rest = decoders[stream].decode();
+            if (rest)
+                onChunk({ stream, text: rest, bytes: new Uint8Array() });
+        }
+        return result;
     }
     fs = {
         read: (path) => this.files.read(path),
@@ -71,7 +80,23 @@ export class Desktop extends SessionHandle {
         }).then(() => undefined),
         down: (x, y, button = "left") => this.mouseCall(x, y, "down", button),
         up: (x, y, button = "left") => this.mouseCall(x, y, "up", button),
-        scroll: (x, y, opts = {}) => this.mouseCall(x, y, "scroll", opts.button, opts.humanize),
+        scroll: async (x, y, opts = {}) => {
+            const amount = opts.amount ?? 3;
+            if (!Number.isInteger(amount) || amount < 1 || amount > 50) {
+                throw new SolariError("scroll amount must be a whole number of wheel clicks from 1 to 50");
+            }
+            const direction = opts.direction ?? "down";
+            if (direction !== "up" && direction !== "down") {
+                throw new SolariError('scroll direction must be "up" or "down"');
+            }
+            await this.mouseCall(x, y, "move", undefined, opts.humanize);
+            await this.guiCall("input.mouse", {
+                x,
+                y: direction === "up" ? amount : -amount,
+                action: "scroll",
+                button: buttonToCode(opts.button),
+            });
+        },
         drag: (from, to, button = "left") => this.guiCall("input.drag", { from, to, button: buttonToCode(button) }).then(() => undefined),
     };
     mouseCall(x, y, action, button, humanize) {
@@ -126,7 +151,18 @@ export class Desktop extends SessionHandle {
     process = {
         list: async () => {
             const r = await this.guiCall("process.list", {});
-            return r.processes;
+            return (r.processes ?? []).map((p) => {
+                const info = {
+                    pid: Number(p.pid),
+                    name: String(p.name ?? p.comm ?? ""),
+                };
+                const cmd = p.cmd ?? p.cmdline;
+                if (typeof cmd === "string")
+                    info.cmd = cmd;
+                if (typeof p.state === "string")
+                    info.state = p.state;
+                return info;
+            });
         },
         kill: (pid) => this.guiCall("process.kill", { pid }).then(() => undefined),
         start: async (cmd, opts = {}) => {

package/dist/handle.d.ts

@@ -56,14 +56,30 @@ export interface SessionConfig extends ControlChannelConfig {
 }
 /** The longest `timeoutMs` the gateway accepts for a command (600 000 ms), and the default for `commands.run`. */
 export declare const DEFAULT_COMMAND_TIMEOUT_MS = 600000;
+/**
+ * The session `id` is no longer running (killed or paused, through any handle or by id), so the exit reminder must not
+ * name it. Tracking is by id, not by handle: two handles to one session, or a `client.kill(id)` with no handle at all,
+ * all clear the same entry.
+ */
+export declare function markSessionReleased(id: string): void;
+/** The lines the exit reminder prints: one per distinct session id, however many handles track it. */
+export declare function exitReminderMessages(): string[];
+/** Ids the exit reminder would name right now (for tests). */
+export declare function unreleasedSessionIds(): string[];
 /** Cap on PTY output held before the first onData() subscriber (bytes, total). */
 export declare const PTY_EARLY_BUFFER_MAX: number;
+export interface SessionHandle {
+    /** `await using sbx = await client.create(...)` releases the machine (`kill()`) when the scope ends. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
 export declare class SessionHandle {
     /** The session id (sandboxId / sessionId). */
     readonly id: string;
     readonly controlUrl: string;
     readonly expiresAt: string;
     protected readonly channel: ControlChannel;
+    /** Set once the gateway has refused a command stream because this sandbox is `shared`. */
+    private sharedContext;
     protected readonly hooks: SessionHooks;
     /** Set by {@link kill} so {@link close} doesn't warn about a machine we
      *  have just released. */
@@ -166,10 +182,11 @@ export declare class SessionHandle {
     }>;
     readonly volumes: {
         /**
-         * Mount a volume into the guest at `path`. Thin pass-through to the guest
-         * `volume.mount` RPC; the gateway volume routes may be a 501 stub today.
+         * Not available at runtime. A volume is mounted when the sandbox is created (or resumed): the guest cannot fetch the
+         * storage credentials itself, and the gateway has no runtime-mount route, so the old pass-through to the guest
+         * `volume.mount` RPC always failed with "bucket is required". Pass `volumes: [{ volumeId, path }]` at create.
          */
-        mount: (volId: string, path: string) => Promise<void>;
+        mount: (_volId: string, _path: string) => Promise<void>;
     };
     readonly git: {
         /** Clone `url` into `opts.path` (or git's default dir) under `opts.cwd`. */
@@ -198,10 +215,19 @@ export declare class SessionHandle {
     };
     /** Run `git <args>` in the guest via the command RPC (no shell). */
     private runGit;
-    /** Run `git <args>`; throw with the stderr on a non-zero exit. */
+    /** Run `git <args>`; throw with the stderr on a non-zero exit. A password passed in `secret` is masked in the message. */
     private mustGit;
-    /** Splice basic-auth creds into an https remote URL (for private remotes). */
-    private authUrl;
+    /**
+     * Credentials for ONE git command, for a private http(s) remote at `remoteUrl`. They go to the guest as environment
+     * variables of that command and git reads them back through an inline credential helper, so they are never in the
+     * clone URL (and so not in `.git/config`, a snapshot or a template), never in argv (`/proc/<pid>/cmdline`), and never
+     * in a config file: the `-c` options last for this command only and the helper script holds no secret.
+     *
+     * The helper is bound to the remote's origin (`credential.<scheme>://<host>.helper`), so git never hands the password
+     * to another host: a redirect to a different host, or a downgrade to http, gets nothing. Returns undefined when
+     * there are no credentials, or the remote is not http(s) (ssh remotes do not use them).
+     */
+    private gitAuth;
     private gitClone;
     private gitStatus;
     private gitAdd;

package/dist/handle.js

@@ -6,6 +6,18 @@ export const DEFAULT_COMMAND_TIMEOUT_MS = 600_000;
 const unreleased = new Map();
 const MAX_TRACKED_UNRELEASED = 1000;
 let exitHookInstalled = false;
+export function markSessionReleased(id) {
+    for (const [token, tracked] of unreleased)
+        if (tracked === id)
+            unreleased.delete(token);
+}
+export function exitReminderMessages() {
+    return [...new Set(unreleased.values())].map((id) => `[solari] this process is exiting but session ${shortId(id)} is still running and will bill until its ` +
+        `idle timeout. Call kill() to release it (or declare it with \`await using\`).`);
+}
+export function unreleasedSessionIds() {
+    return [...unreleased.values()];
+}
 function trackUnreleased(token, id) {
     unreleased.set(token, id);
     if (unreleased.size > MAX_TRACKED_UNRELEASED)
@@ -14,20 +26,30 @@ function trackUnreleased(token, id) {
         return;
     exitHookInstalled = true;
     process.on("exit", () => {
-        for (const id of unreleased.values()) {
-            console.warn(`[solari] this process is exiting but session ${shortId(id)} is still running and will bill until its ` +
-                `idle timeout. Call kill() to release it (or declare it with \`await using\`).`);
-        }
+        for (const line of exitReminderMessages())
+            console.warn(line);
         unreleased.clear();
     });
 }
 const MIN_REST_TIMEOUT_MS = 1000;
 export const PTY_EARLY_BUFFER_MAX = 1024 * 1024;
+const GIT_CREDENTIAL_HELPER = '!f() { test "$1" = get && printf "username=%s\\npassword=%s\\n" "$SOLARI_GIT_USERNAME" "$SOLARI_GIT_PASSWORD"; }; f';
+function gitSubcommand(args) {
+    let i = 0;
+    while (args[i] === "-c")
+        i += 2;
+    return args[i] ?? "";
+}
+function rejectOptionLike(what, v) {
+    if (v.startsWith("-"))
+        throw new Error(`git ${what} must not start with "-": ${JSON.stringify(v)}`);
+}
 export class SessionHandle {
     id;
     controlUrl;
     expiresAt;
     channel;
+    sharedContext = false;
     hooks;
     killed = false;
     releaseToken = {};
@@ -58,7 +80,8 @@ export class SessionHandle {
         return this.channel.reconnect();
     }
     close(opts = {}) {
-        unreleased.delete(this.releaseToken);
+        if (!opts.quiet)
+            unreleased.delete(this.releaseToken);
         if (!this.killed && !opts.quiet && typeof console !== "undefined") {
             console.warn(`[solari] close() on session ${shortId(this.id)} closed the local channel only — ` +
                 `the remote machine is still running and will bill until its idle ` +
@@ -120,17 +143,26 @@ export class SessionHandle {
                     opts.onStderr?.(c.data);
             });
         }
-        this.channel.onFrame("cmd.data", cmdId, (f) => {
-            const stream = f.stream ?? "stdout";
-            const data = f.base64 ? new TextDecoder().decode(base64ToBytes(f.base64)) : "";
-            const chunk = { stream, data };
+        const decoders = { stdout: new TextDecoder(), stderr: new TextDecoder() };
+        const emit = (chunk) => {
             if (dataCbs.length === 0)
                 buffered.push(chunk);
             else
                 for (const cb of dataCbs)
                     cb(chunk);
+        };
+        this.channel.onFrame("cmd.data", cmdId, (f) => {
+            const stream = f.stream ?? "stdout";
+            const dec = decoders[stream] ?? decoders.stdout;
+            const data = f.base64 ? dec.decode(base64ToBytes(f.base64), { stream: true }) : "";
+            emit({ stream, data });
         });
         this.channel.onFrame("cmd.exit", cmdId, (f) => {
+            for (const stream of ["stdout", "stderr"]) {
+                const rest = decoders[stream].decode();
+                if (rest)
+                    emit({ stream, data: rest });
+            }
             this.channel.offFrame("cmd.data", cmdId);
             this.channel.offFrame("cmd.exit", cmdId);
             this.channel.offStreamClose(cmdId);
@@ -172,23 +204,21 @@ export class SessionHandle {
         if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs < 0) {
             throw new SolariError(`Solari: timeoutMs must be a non-negative number of milliseconds, got ${String(timeoutMs)}`);
         }
-        if (this.hooks.exec &&
+        const restEligible = !!this.hooks.exec &&
             !opts.background &&
             !opts.onStdout &&
             !opts.onStderr &&
             !opts.env &&
             !opts.user &&
             timeoutMs >= MIN_REST_TIMEOUT_MS &&
-            timeoutMs <= DEFAULT_COMMAND_TIMEOUT_MS &&
-            !this.channel.connected) {
+            timeoutMs <= DEFAULT_COMMAND_TIMEOUT_MS;
+        const viaRest = async () => {
+            const r = await this.hooks.exec(this.id, { cmd, args: opts.args, cwd: opts.cwd, timeoutMs });
+            return { ...r, timedOut: r.timedOut === true };
+        };
+        if (restEligible && (!this.channel.connected || this.sharedContext)) {
             try {
-                const r = await this.hooks.exec(this.id, {
-                    cmd,
-                    args: opts.args,
-                    cwd: opts.cwd,
-                    timeoutMs,
-                });
-                return { ...r, timedOut: r.timedOut === true };
+                return await viaRest();
             }
             catch (err) {
                 if (!isRouteUnavailable(err))
@@ -196,7 +226,24 @@ export class SessionHandle {
             }
         }
         const acc = { stdout: "", stderr: "" };
-        const handle = await this.startCommand(cmd, { ...opts, timeoutMs: undefined }, acc);
+        let handle;
+        try {
+            handle = await this.startCommand(cmd, { ...opts, timeoutMs: undefined }, acc);
+        }
+        catch (err) {
+            if (!isSharedRefusal(err))
+                throw err;
+            this.sharedContext = true;
+            if (restEligible) {
+                try {
+                    return await viaRest();
+                }
+                catch (e) {
+                    throw normalizeExecError(e, timeoutMs);
+                }
+            }
+            throw err;
+        }
         if (opts.background) {
             return { exitCode: 0, stdout: "", stderr: "", timedOut: false };
         }
@@ -363,9 +410,7 @@ export class SessionHandle {
         return this.hooks.uploadUrl(this.id, path);
     }
     volumes = {
-        mount: (volId, path) => this.channel
-            .call("volume.mount", { volumeId: volId, path })
-            .then(() => undefined),
+        mount: (_volId, _path) => Promise.reject(new SolariError("volumes.mount() is not supported on a running sandbox: pass volumes: [{ volumeId, path }] when you create it")),
     };
     git = {
         clone: (url, opts = {}) => this.gitClone(url, opts),
@@ -378,42 +423,61 @@ export class SessionHandle {
         branches: (cwd) => this.gitBranches(cwd),
         log: (opts = {}) => this.gitLog(opts),
     };
-    async runGit(args, cwd) {
-        return this.runCommand("git", { args, ...(cwd ? { cwd } : {}) });
+    async runGit(args, cwd, env) {
+        return this.runCommand("git", { args, ...(cwd ? { cwd } : {}), ...(env ? { env } : {}) });
     }
-    async mustGit(args, cwd) {
-        const r = await this.runGit(args, cwd);
+    async mustGit(args, cwd, env, secret) {
+        const r = await this.runGit(args, cwd, env);
         if (r.exitCode !== 0) {
-            const detail = (r.stderr || r.stdout || "").trim();
-            throw new Error(`git ${args[0]} failed (exit ${r.exitCode}): ${detail}`);
+            let detail = (r.stderr || r.stdout || "").trim();
+            if (secret)
+                detail = detail.split(secret).join("***");
+            throw new Error(`git ${gitSubcommand(args)} failed (exit ${r.exitCode}): ${detail}`);
         }
         return r.stdout;
     }
-    authUrl(url, username, password) {
+    gitAuth(remoteUrl, username, password) {
         if (!username && !password)
-            return url;
+            return undefined;
+        for (const v of [username, password]) {
+            if (v !== undefined && /[\r\n\0]/.test(v))
+                throw new Error("git credentials must not contain line breaks or NUL");
+        }
+        let origin;
         try {
-            const u = new URL(url);
-            if (username)
-                u.username = encodeURIComponent(username);
-            if (password)
-                u.password = encodeURIComponent(password);
-            return u.toString();
+            const u = new URL(remoteUrl);
+            if (u.protocol !== "https:" && u.protocol !== "http:")
+                return undefined;
+            origin = `${u.protocol}//${u.host}`;
         }
         catch {
-            return url;
+            return undefined;
         }
+        if (/[=\s]/.test(origin))
+            return undefined;
+        return {
+            cfg: [
+                "-c", "credential.helper=",
+                "-c", `credential.${origin}.helper=${GIT_CREDENTIAL_HELPER}`,
+            ],
+            env: {
+                GIT_TERMINAL_PROMPT: "0",
+                SOLARI_GIT_USERNAME: username ?? "",
+                SOLARI_GIT_PASSWORD: password ?? "",
+            },
+        };
     }
     async gitClone(url, opts) {
-        const args = ["clone"];
+        const auth = this.gitAuth(url, opts.username, opts.password);
+        const args = [...(auth?.cfg ?? []), "clone"];
         if (opts.depth && opts.depth > 0)
             args.push("--depth", String(opts.depth));
         if (opts.branch)
             args.push("--branch", opts.branch);
-        args.push(this.authUrl(url, opts.username, opts.password));
+        args.push("--", url);
         if (opts.path)
             args.push(opts.path);
-        await this.mustGit(args, opts.cwd);
+        await this.mustGit(args, opts.cwd, auth?.env, opts.password);
     }
     async gitStatus(cwd) {
         const out = await this.mustGit(["status", "--porcelain=v1", "--branch"], cwd);
@@ -488,25 +552,25 @@ export class SessionHandle {
     }
     async gitPushPull(op, opts) {
         const remote = opts.remote || "origin";
-        const cfg = [];
+        rejectOptionLike("remote", remote);
+        if (opts.branch)
+            rejectOptionLike("branch", opts.branch);
+        let auth;
         if (opts.username || opts.password) {
-            const plain = (await this.runGit(["remote", "get-url", remote], opts.cwd)).stdout.trim();
-            if (plain) {
-                const authed = this.authUrl(plain, opts.username, opts.password);
-                if (authed !== plain)
-                    cfg.push("-c", `url.${authed}.insteadOf=${plain}`);
-            }
+            const plain = (await this.mustGit(["remote", "get-url", "--", remote], opts.cwd)).trim();
+            auth = this.gitAuth(plain, opts.username, opts.password);
         }
-        const args = [...cfg, op, remote];
+        const args = [...(auth?.cfg ?? []), op, "--", remote];
         if (opts.branch)
             args.push(opts.branch);
-        await this.mustGit(args, opts.cwd);
+        await this.mustGit(args, opts.cwd, auth?.env, opts.password);
     }
     async gitCheckout(ref, opts) {
+        rejectOptionLike("ref", ref);
         const args = ["checkout"];
         if (opts.create)
             args.push("-b");
-        args.push(ref);
+        args.push(ref, "--");
         await this.mustGit(args, opts.cwd);
     }
     async gitBranches(cwd) {
@@ -569,6 +633,7 @@ export class SessionHandle {
             throw new Error("pause requires a client-created handle");
         }
         await this.hooks.pause(this.id);
+        markSessionReleased(this.id);
         this.close({ quiet: true });
     }
     async resume() {
@@ -576,6 +641,7 @@ export class SessionHandle {
             throw new Error("resume requires a client-created handle");
         }
         const r = await this.hooks.resume(this.id);
+        trackUnreleased(this.releaseToken, this.id);
         this.channel.setControlUrl(r.controlUrl);
         await this.channel.reconnect();
     }
@@ -618,6 +684,7 @@ export class SessionHandle {
         if (this.hooks.kill)
             await this.hooks.kill(this.id);
         this.killed = true;
+        markSessionReleased(this.id);
         this.close();
     }
 }
@@ -652,6 +719,11 @@ function explainShellCommandFailure(cmd, err) {
     }
     return new Error(msg + hint);
 }
+function isSharedRefusal(err) {
+    if (err instanceof ActionError && err.code === "NotAvailableOnSharedIsolation")
+        return true;
+    return err instanceof Error && /NotAvailableOnSharedIsolation|not available on a shared/.test(err.message);
+}
 function isRouteUnavailable(err) {
     return (err instanceof GatewayError &&
         (err.status === 404 || err.status === 405 || err.status === 501));

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { DEFAULT_COMMAND_TIMEOUT_MS, SessionHandle } from "./handle.js";
+export { DEFAULT_COMMAND_TIMEOUT_MS, SessionHandle, markSessionReleased, unreleasedSessionIds, exitReminderMessages } from "./handle.js";
 export { shortId } from "./ids.js";
 export { formatIdlePolicy } from "./idle-policy.js";
 export type { SessionConfig, SessionHooks } from "./handle.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { DEFAULT_COMMAND_TIMEOUT_MS, SessionHandle } from "./handle.js";
+export { DEFAULT_COMMAND_TIMEOUT_MS, SessionHandle, markSessionReleased, unreleasedSessionIds, exitReminderMessages } from "./handle.js";
 export { shortId } from "./ids.js";
 export { formatIdlePolicy } from "./idle-policy.js";
 export { Desktop } from "./desktop.js";

package/dist/types.d.ts

@@ -632,6 +632,10 @@ export interface MouseResult {
 export interface ScrollOptions {
     button?: MouseButton;
     humanize?: boolean;
+    /** Which way the wheel turns. Default "down". */
+    direction?: "up" | "down";
+    /** Wheel clicks, a whole number from 1 to 50. Default 3. */
+    amount?: number;
 }
 export interface ClickOptions {
     button?: MouseButton;
@@ -686,8 +690,12 @@ export interface ProcessListParams {
 }
 export interface ProcessInfo {
     pid: number;
+    /** The process name (the guest agent's `comm`). */
     name: string;
+    /** The full command line (the guest agent's `cmdline`). */
     cmd?: string;
+    /** Process state letter as the kernel reports it (`R`, `S`, `Z`, ...). */
+    state?: string;
 }
 export interface ProcessListResult {
     processes: ProcessInfo[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solarisdk/core",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Shared runtime for the Solari SDK \u2014 transport, session handles, images, templates, and types used by @solarisdk/desktop and @solarisdk/sandbox.",
   "type": "module",
   "main": "./dist/index.js",