@exagone313/dsh-podman 0.2.0-rc.4 → 0.2.0

package/dist/terminal-sessions.js

@@ -0,0 +1,252 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+// Live and retained Podman terminals. One guest pty per (session, tab), kept
+// alive while the browser is away and replayed from a headless emulator screen
+// on reattach, so reloading the page does not lose the shell or its scrollback.
+import { openGuestTerminal } from "./guest-terminal.js";
+import { requireShell } from "./terminal-shells.js";
+import { randomUUID } from "node:crypto";
+import { createRequire } from "node:module";
+// Both xterm packages are CommonJS: a default ESM import of their named exports
+// fails under Node's interop rules, so they are required with their own types.
+const require = createRequire(import.meta.url);
+const { Terminal } = require("@xterm/headless");
+const { SerializeAddon } = require("@xterm/addon-serialize");
+// The harness's own browser terminals keep an idle shell for this long.
+export const TERMINAL_RETENTION_MS = 7_200_000;
+const DEFAULT_SCROLLBACK = 1000;
+const REAP_INTERVAL_MS = 60_000;
+export class TerminalSessions {
+    options;
+    entries = new Map();
+    byId = new Map();
+    scrollback;
+    retentionMs;
+    sweep;
+    constructor(options) {
+        this.options = options;
+        this.scrollback = options.scrollback ?? DEFAULT_SCROLLBACK;
+        this.retentionMs = options.retentionMs ?? TERMINAL_RETENTION_MS;
+        this.sweep = setInterval(() => this.reap(), REAP_INTERVAL_MS);
+        this.sweep.unref?.();
+    }
+    /**
+     * Validate a request and make sure its terminal exists.
+     * @param options - session/tab identity, target container and shell, dimensions.
+     * @returns the terminal identity and, when reattaching, its serialized screen.
+     */
+    async prepare(options) {
+        const key = `${options.sessionId}\n${options.tabId}`;
+        if (options.reopen === true)
+            this.drop(key);
+        const existing = this.entries.get(key);
+        if (existing !== undefined) {
+            existing.lastUsed = Date.now();
+            return {
+                terminalId: existing.terminalId,
+                workspace: existing.workspace,
+                container: existing.container,
+                shell: existing.shell,
+                title: existing.title,
+                attached: true,
+                snapshot: existing.serializer.serialize(),
+            };
+        }
+        const binding = options.container === "" || options.container === "default"
+            ? await this.options.resolver.resolveForPath(options.cwd, options.cwd, options.signal)
+            : await this.options.resolver.containerBinding(options.cwd, options.container, options.signal);
+        const shell = await requireShell(binding, options.cwd, options.shell, options.signal);
+        const terminal = openGuestTerminal(binding, {
+            argv: [shell.path, "-i"],
+            cwd: options.cwd,
+            cols: options.cols,
+            rows: options.rows,
+            terminalType: "xterm-256color",
+        });
+        const screen = new Terminal({
+            cols: options.cols,
+            rows: options.rows,
+            scrollback: this.scrollback,
+            allowProposedApi: true,
+        });
+        const serializer = new SerializeAddon();
+        screen.loadAddon(serializer);
+        const entry = {
+            key,
+            terminalId: randomUUID(),
+            sessionId: options.sessionId,
+            tabId: options.tabId,
+            workspace: options.workspace,
+            container: options.container,
+            shell: shell.path,
+            title: shell.name,
+            terminal,
+            screen,
+            serializer,
+            lastUsed: Date.now(),
+            listener: undefined,
+        };
+        terminal.onOutput((chunk) => {
+            entry.screen.write(chunk);
+            entry.listener?.({
+                type: "data",
+                data: Buffer.from(chunk).toString("base64"),
+            });
+        });
+        void terminal.done.then((outcome) => {
+            entry.exit = outcome;
+            entry.listener?.({
+                type: "exit",
+                exitCode: outcome.exitCode,
+                signal: outcome.signal,
+            });
+        }, (error) => {
+            entry.failure = error instanceof Error ? error.message : String(error);
+            entry.listener?.({ type: "error", message: entry.failure });
+        });
+        try {
+            // Surface a startup failure before publishing the entry.
+            await terminal.started;
+        }
+        catch (error) {
+            void terminal.terminate();
+            throw error;
+        }
+        this.entries.set(key, entry);
+        this.byId.set(entry.terminalId, entry);
+        return {
+            terminalId: entry.terminalId,
+            workspace: entry.workspace,
+            container: entry.container,
+            shell: entry.shell,
+            title: entry.title,
+            attached: false,
+        };
+    }
+    /**
+     * Attach one browser stream as the terminal's input owner.
+     * @param terminalId - a prepared terminal.
+     * @param write - frame sink for this attachment.
+     * @param signal - the request lifetime; aborting detaches without closing.
+     * @param snapshot - serialized screen to replay before live output.
+     * @returns a detach function, idempotent and safe after the entry is gone.
+     */
+    listen(terminalId, write, signal, snapshot) {
+        const entry = this.byId.get(terminalId);
+        if (entry === undefined)
+            return () => { };
+        // A newer attachment takes over: the previous one is told it is detached.
+        entry.listener?.({ type: "detached" });
+        entry.listener = write;
+        entry.lastUsed = Date.now();
+        write({
+            type: "ready",
+            terminalId,
+            workspace: entry.workspace,
+            container: entry.container,
+            shell: entry.shell,
+            title: entry.title,
+            attached: snapshot !== undefined,
+        });
+        if (snapshot !== undefined)
+            write({ type: "snapshot", screen: snapshot });
+        if (entry.exit !== undefined) {
+            write({
+                type: "exit",
+                exitCode: entry.exit.exitCode,
+                signal: entry.exit.signal,
+            });
+        }
+        else if (entry.failure !== undefined) {
+            write({ type: "error", message: entry.failure });
+        }
+        const detach = () => {
+            if (entry.listener === write)
+                entry.listener = undefined;
+        };
+        signal.addEventListener("abort", detach, { once: true });
+        return detach;
+    }
+    /**
+     * Apply one control request.
+     * @param control - input, resize, rename, or close.
+     * @returns whether the terminal was found.
+     */
+    control(control) {
+        const entry = this.byId.get(control.terminalId);
+        if (entry === undefined)
+            return false;
+        entry.lastUsed = Date.now();
+        switch (control.kind) {
+            case "input": {
+                if (!entry.terminal.exited()) {
+                    entry.terminal.write(Buffer.from(control.data, "base64"));
+                }
+                return true;
+            }
+            case "resize": {
+                if (!entry.terminal.exited()) {
+                    entry.terminal.resize(control.cols, control.rows);
+                    entry.screen.resize(control.cols, control.rows);
+                }
+                return true;
+            }
+            case "rename": {
+                entry.title = control.title;
+                entry.listener?.({ type: "title", title: control.title });
+                return true;
+            }
+            case "close": {
+                this.drop(entry.key);
+                void entry.terminal.terminate();
+                return true;
+            }
+        }
+    }
+    /**
+     * List the terminals one session still holds.
+     * @param sessionId - the owning session.
+     * @returns retained terminal metadata, oldest first.
+     */
+    retained(sessionId) {
+        return [...this.entries.values()]
+            .filter((entry) => entry.sessionId === sessionId)
+            .map((entry) => ({
+            tabId: entry.tabId,
+            terminalId: entry.terminalId,
+            title: entry.title,
+            workspace: entry.workspace,
+            container: entry.container,
+            shell: entry.shell,
+        }));
+    }
+    /** Close every terminal and stop the retention sweep. */
+    dispose() {
+        clearInterval(this.sweep);
+        for (const entry of [...this.entries.values()]) {
+            this.entries.delete(entry.key);
+            this.byId.delete(entry.terminalId);
+            void entry.terminal.terminate();
+        }
+    }
+    // drop removes one entry from both indexes without terminating it; the caller
+    // owns termination so a replace never races the old shell's teardown.
+    drop(key) {
+        const entry = this.entries.get(key);
+        if (entry === undefined)
+            return;
+        this.entries.delete(key);
+        this.byId.delete(entry.terminalId);
+    }
+    // reap closes terminals no browser has attached for the retention window.
+    reap() {
+        const cutoff = Date.now() - this.retentionMs;
+        for (const entry of [...this.entries.values()]) {
+            if (entry.listener === undefined && entry.lastUsed < cutoff) {
+                this.drop(entry.key);
+                void entry.terminal.terminate();
+            }
+        }
+    }
+}

package/dist/terminal-shells.d.ts

@@ -0,0 +1,22 @@
+import { type TerminalShellView } from "./client/terminal-protocol.js";
+import { type WorkspaceBinding } from "./workspace-binding.js";
+export declare const SHELL_CANDIDATES: readonly ["zsh", "bash", "fish", "pwsh", "powershell", "nu", "ksh", "mksh", "dash", "ash", "sh"];
+/**
+ * Discover the shells one container really provides.
+ * @param binding - guest connection for the target container.
+ * @param cwd - an absolute path already mounted in that container.
+ * @param signal - cancellation of the probe.
+ * @returns each shell's requested name and resolved absolute path, most capable first.
+ */
+export declare function discoverShells(binding: WorkspaceBinding, cwd: string, signal?: AbortSignal): Promise<TerminalShellView[]>;
+/**
+ * Require one shell to still exist in the container, so a client cannot ask for
+ * an arbitrary executable and a shell that vanished since the picker loaded is
+ * refused instead of spawned.
+ * @param binding - guest connection for the target container.
+ * @param cwd - an absolute path already mounted in that container.
+ * @param path - the absolute shell path the client selected.
+ * @param signal - cancellation of the probe.
+ * @returns the verified shell.
+ */
+export declare function requireShell(binding: WorkspaceBinding, cwd: string, path: string, signal?: AbortSignal): Promise<TerminalShellView>;

package/dist/terminal-shells.js

@@ -0,0 +1,99 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+// Shell discovery inside one container. The candidate list carries names only:
+// where a shell lives is answered by the container's own PATH (including the
+// deployment's PATH additions), /etc/shells, and $SHELL, so a shell installed
+// anywhere the container can see it is found without hardcoded locations.
+import { fsError, runExec } from "./guest-rpc.js";
+// Names looked up on the container's PATH, ordered most capable first so the
+// picker offers — and preselects — the best shell the container has. The first
+// five mirror the harness's own candidate order; the minimal POSIX shells come
+// last, with `sh` final because /bin/sh is usually a symlink to one of them.
+export const SHELL_CANDIDATES = [
+    "zsh",
+    "bash",
+    "fish",
+    "pwsh",
+    "powershell",
+    "nu",
+    "ksh",
+    "mksh",
+    "dash",
+    "ash",
+    "sh",
+];
+// POSIX `command -v`, not bash's `type -P`: the probe must not require a shell
+// it is still looking for, and it runs under /bin/sh in every image we build.
+const PROBE_SCRIPT = [
+    'for name in "$@"; do',
+    '  path=$(command -v -- "$name" 2>/dev/null) || continue',
+    '  case $path in /*) [ -x "$path" ] && printf "%s\\t%s\\n" "$name" "$path" ;; esac',
+    "done",
+    'for candidate in "$SHELL"; do',
+    '  case $candidate in /*) [ -x "$candidate" ] && printf "%s\\t%s\\n" "${candidate##*/}" "$candidate" ;; esac',
+    "done",
+    "if [ -f /etc/shells ]; then",
+    "  while IFS= read -r candidate; do",
+    '    case $candidate in ""|\#*) continue ;; esac',
+    '    case $candidate in /*) [ -x "$candidate" ] && printf "%s\\t%s\\n" "${candidate##*/}" "$candidate" ;; esac',
+    "  done < /etc/shells",
+    "fi",
+].join("\n");
+const PROBE_TIMEOUT_MS = 10_000;
+const PROBE_MAX_BYTES = 64 * 1024;
+// One ordered list drives both the probe and the result order, so the two can
+// never disagree.
+const SHELL_RANK = new Map(SHELL_CANDIDATES.map((name, index) => [name, index]));
+function rank(name) {
+    return SHELL_RANK.get(name) ?? SHELL_CANDIDATES.length;
+}
+/**
+ * Discover the shells one container really provides.
+ * @param binding - guest connection for the target container.
+ * @param cwd - an absolute path already mounted in that container.
+ * @param signal - cancellation of the probe.
+ * @returns each shell's requested name and resolved absolute path, most capable first.
+ */
+export async function discoverShells(binding, cwd, signal) {
+    const result = await runExec(binding, ["/bin/sh", "-c", PROBE_SCRIPT, "sh", ...SHELL_CANDIDATES], cwd, undefined, PROBE_TIMEOUT_MS, undefined, { signal, maxBytes: PROBE_MAX_BYTES });
+    // The probe prints PATH hits first, then $SHELL and /etc/shells, so keeping
+    // the first path per candidate name prefers the PATH answer and drops both
+    // symlinked duplicates (/bin/sh vs /usr/bin/sh) and anything /etc/shells
+    // lists that is not one of our candidate names (rbash, git-shell, …).
+    const candidates = new Set(SHELL_CANDIDATES);
+    const byName = new Map();
+    for (const line of result.stdout.split("\n")) {
+        const [rawName, rawPath] = line.split("\t");
+        const name = (rawName ?? "").trim();
+        const path = (rawPath ?? "").trim();
+        if (name === "" || !path.startsWith("/"))
+            continue;
+        if (!candidates.has(name))
+            continue;
+        if (!byName.has(name))
+            byName.set(name, path);
+    }
+    return [...byName]
+        .map(([name, path]) => ({ name, path }))
+        .sort((left, right) => rank(left.name) - rank(right.name) ||
+        left.name.localeCompare(right.name));
+}
+/**
+ * Require one shell to still exist in the container, so a client cannot ask for
+ * an arbitrary executable and a shell that vanished since the picker loaded is
+ * refused instead of spawned.
+ * @param binding - guest connection for the target container.
+ * @param cwd - an absolute path already mounted in that container.
+ * @param path - the absolute shell path the client selected.
+ * @param signal - cancellation of the probe.
+ * @returns the verified shell.
+ */
+export async function requireShell(binding, cwd, path, signal) {
+    const shells = await discoverShells(binding, cwd, signal);
+    const match = shells.find((shell) => shell.path === path);
+    if (match === undefined) {
+        throw fsError("FS_IO_ERROR", `shell ${JSON.stringify(path)} is not available in this container`);
+    }
+    return match;
+}

package/dist/terminal-tab.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/terminal-tab.test.js

@@ -0,0 +1,58 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import test from "node:test";
+import assert from "node:assert/strict";
+// Importing the client module here also typechecks it under the host program,
+// which has no DOM lib: it must stay environment-free data.
+import { PODMAN_TERMINAL_SHORTCUT_DEFAULTS, PODMAN_TERMINAL_SHORTCUT_FALLBACK_DEFAULTS, } from "./client/terminal-tab.js";
+// The harness's shortcuts registry rejects a declared default it does not admit
+// by THROWING from register(), which runs inside apply(): one bad profile fails
+// the client entry and the whole web boot. These assertions pin the profiles
+// that rule allows, so such a break is caught by pnpm test instead of in the UI.
+test("the Podman terminal shortcut prefers the built-in terminal's binding", () => {
+    const defaults = PODMAN_TERMINAL_SHORTCUT_DEFAULTS;
+    assert.deepEqual(Object.keys(defaults).sort(), [
+        "desktop:linux",
+        "desktop:macos",
+        "desktop:windows",
+        "web:macos",
+        "web:windows",
+    ]);
+    for (const value of Object.values(PODMAN_TERMINAL_SHORTCUT_DEFAULTS)) {
+        assert.deepEqual(value, { code: "Backquote", modifiers: ["control"] });
+    }
+    // Linux Web admits only Ctrl+/, Ctrl+Shift+, and Ctrl+Shift+.
+    assert.equal(defaults["web:linux"], undefined);
+});
+test("the fallback binding is distinct and equally admitted", () => {
+    const fallback = PODMAN_TERMINAL_SHORTCUT_FALLBACK_DEFAULTS;
+    assert.deepEqual(Object.keys(fallback).sort(), [
+        "desktop:linux",
+        "desktop:macos",
+        "desktop:windows",
+        "web:macos",
+        "web:windows",
+    ]);
+    // macOS Web admits Ctrl+` and Meta+Shift+`, never Ctrl+Shift+`.
+    assert.deepEqual(PODMAN_TERMINAL_SHORTCUT_FALLBACK_DEFAULTS["web:macos"], {
+        code: "Backquote",
+        modifiers: ["meta", "shift"],
+    });
+    for (const profile of [
+        "desktop:macos",
+        "desktop:windows",
+        "desktop:linux",
+        "web:windows",
+    ]) {
+        assert.deepEqual(PODMAN_TERMINAL_SHORTCUT_FALLBACK_DEFAULTS[profile], {
+            code: "Backquote",
+            modifiers: ["control", "shift"],
+        });
+    }
+    // The two bindings can never overlap, so the fallback cannot be the reason a
+    // re-enabled built-in terminal breaks the boot.
+    for (const profile of Object.keys(fallback)) {
+        assert.notDeepEqual(fallback[profile], PODMAN_TERMINAL_SHORTCUT_DEFAULTS[profile]);
+    }
+});

package/dist/terminal-targets.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/terminal-targets.test.js

@@ -0,0 +1,43 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import test from "node:test";
+import assert from "node:assert/strict";
+import { containerOptions, shellName, validContainer, validShell, } from "./client/terminal-targets.js";
+function row(containerName, workspaceSlug) {
+    return { containerName, workspaceSlug };
+}
+test("terminal container options are logical names only", () => {
+    const containers = [
+        row("default", "alpha"),
+        row("dev", "alpha"),
+        row("db", "beta"),
+        // A podman name is never a valid target: the API rejects it.
+        row("dsh-podman-alpha-default", "alpha"),
+    ];
+    assert.deepEqual(containerOptions(containers, "alpha"), ["dev"]);
+    assert.deepEqual(containerOptions(containers, "beta"), ["db"]);
+    assert.deepEqual(containerOptions(containers, "missing"), []);
+    assert.deepEqual(containerOptions(containers, undefined), []);
+});
+test("remembered targets are reused only while they are still offered", () => {
+    // Containers: the default answer is the workspace's own default.
+    assert.equal(validContainer(undefined, ["dev"]), "");
+    assert.equal(validContainer("", ["dev"]), "");
+    assert.equal(validContainer("dev", ["dev"]), "dev");
+    assert.equal(validContainer("gone", ["dev"]), "");
+    // Shells: a recreated container may no longer offer the remembered path.
+    const shells = [{ name: "bash", path: "/usr/bin/bash" }];
+    assert.equal(validShell(undefined, shells), undefined);
+    assert.equal(validShell("", shells), undefined);
+    assert.equal(validShell("/usr/bin/bash", shells), "/usr/bin/bash");
+    assert.equal(validShell("/bin/zsh", shells), undefined);
+});
+test("a shell path is named by its basename", () => {
+    assert.equal(shellName("/usr/bin/bash"), "bash");
+    assert.equal(shellName("/bin/sh"), "sh");
+    assert.equal(shellName("pwsh"), "pwsh");
+    assert.equal(shellName("/opt/tools/bin/"), undefined);
+    assert.equal(shellName(""), undefined);
+    assert.equal(shellName(undefined), undefined);
+});

package/dist/terminal-titles.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/terminal-titles.test.js

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import test from "node:test";
+import assert from "node:assert/strict";
+import { forgetTerminalTitle, publishTerminalTitle, subscribeTerminalTitles, terminalTitle, } from "./client/terminal-titles.js";
+test("published terminal titles are readable, notifying and forgettable", () => {
+    let notifications = 0;
+    const unsubscribe = subscribeTerminalTitles(() => {
+        notifications += 1;
+    });
+    assert.equal(terminalTitle("s1:t1"), undefined);
+    publishTerminalTitle("s1:t1", "bash");
+    assert.equal(terminalTitle("s1:t1"), "bash");
+    assert.equal(notifications, 1);
+    // Re-publishing the same name is a no-op; another terminal is independent.
+    publishTerminalTitle("s1:t1", "bash");
+    publishTerminalTitle("s1:t1", "");
+    assert.equal(notifications, 1);
+    publishTerminalTitle("s1:t2", "sh");
+    assert.equal(terminalTitle("s1:t2"), "sh");
+    assert.equal(notifications, 2);
+    // The same tab id in another session never bleeds through.
+    publishTerminalTitle("s2:t1", "zsh");
+    assert.equal(terminalTitle("s1:t1"), "bash");
+    assert.equal(terminalTitle("s2:t1"), "zsh");
+    forgetTerminalTitle("s1:t1");
+    assert.equal(terminalTitle("s1:t1"), undefined);
+    assert.equal(notifications, 4);
+    // Forgetting an unknown key changes nothing.
+    forgetTerminalTitle("s1:t1");
+    assert.equal(notifications, 4);
+    unsubscribe();
+    publishTerminalTitle("s1:t2", "fish");
+    assert.equal(notifications, 4);
+});

package/dist/test-support.d.ts

@@ -2,6 +2,13 @@ import { EventEmitter } from "node:events";
 export declare const WORKSPACE_ID = "2c573001-4171-4900-904b-12a5cc02737a";
 export declare class FakeTerminalCall extends EventEmitter {
     readonly stdinChunks: Buffer[];
+    readonly resizes: Array<{
+        rows: number;
+        cols: number;
+    }>;
+    start: any;
+    closed: boolean;
+    ended: boolean;
     write(message: any): void;
     end(): void;
     cancel(): void;
@@ -283,6 +290,24 @@ export declare function editGuest(stat: Record<string, unknown>, content?: Buffe
     token: string;
 };
 export declare function editProvider(binding: unknown): import("./fs-provider.js").FilesystemProvider;
+export declare class FakeExecStream extends EventEmitter {
+    private readonly starts;
+    private readonly options;
+    paused: number;
+    resumed: number;
+    cancelled: boolean;
+    constructor(starts: Array<Record<string, any>>, options: {
+        emitExit?: boolean;
+        exit?: Record<string, unknown>;
+        stdout?: string;
+    });
+    write(message: any): boolean;
+    end(): void;
+    pause(): void;
+    resume(): void;
+    cancel(): void;
+    emitData(message: Record<string, unknown>): void;
+}
 export declare function spawnGuest(options?: {
     emitExit?: boolean;
     exit?: Record<string, unknown>;
@@ -294,14 +319,19 @@ export declare function spawnGuest(options?: {
     }[];
     starts: Record<string, any>[];
     deletes: Record<string, unknown>[];
+    streams: FakeExecStream[];
+    guest: {
+        exec: () => FakeExecStream;
+        signal: (request: {
+            processId: string;
+            signal: string;
+        }, _metadata: unknown, callback: Function) => void;
+        delete: (request: Record<string, unknown>, _metadata: unknown, callback: Function) => void;
+    };
     resolver: {
         resolve: () => Promise<{
             guest: {
-                exec: () => {
-                    on(event: string, handler: Function): void;
-                    write(message: any): void;
-                    end(): void;
-                };
+                exec: () => FakeExecStream;
                 signal: (request: {
                     processId: string;
                     signal: string;