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

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

@@ -0,0 +1,60 @@
+/** Page kind `openTab` names; unique among the tab types in force. */
+export declare const PODMAN_TERMINAL_KIND = "podman-terminal";
+/** Implementation id the body, title and guide card register under. */
+export declare const PODMAN_TERMINAL_TAB_ID = "@exagone313/dsh-podman";
+declare module "@deepseek-ai/dsh-client-ui-sidebar-right/client" {
+    interface SidebarRightTabParamsMap {
+        "podman-terminal": PodmanTerminalParams;
+    }
+}
+/** Navigation parameters of one Podman terminal page. */
+export interface PodmanTerminalParams {
+    /** `""`/`"default"` for the default container, or a named one. */
+    readonly container?: string;
+    /** Absolute shell path returned by the shells route. */
+    readonly shell?: string;
+}
+export declare const PODMAN_TERMINAL_SHORTCUT_DEFAULTS: {
+    "desktop:macos": {
+        code: string;
+        modifiers: "control"[];
+    };
+    "desktop:windows": {
+        code: string;
+        modifiers: "control"[];
+    };
+    "desktop:linux": {
+        code: string;
+        modifiers: "control"[];
+    };
+    "web:macos": {
+        code: string;
+        modifiers: "control"[];
+    };
+    "web:windows": {
+        code: string;
+        modifiers: "control"[];
+    };
+};
+export declare const PODMAN_TERMINAL_SHORTCUT_FALLBACK_DEFAULTS: {
+    "desktop:macos": {
+        code: string;
+        modifiers: ("control" | "shift")[];
+    };
+    "desktop:windows": {
+        code: string;
+        modifiers: ("control" | "shift")[];
+    };
+    "desktop:linux": {
+        code: string;
+        modifiers: ("control" | "shift")[];
+    };
+    "web:macos": {
+        code: string;
+        modifiers: ("meta" | "shift")[];
+    };
+    "web:windows": {
+        code: string;
+        modifiers: ("control" | "shift")[];
+    };
+};

package/dist/client/terminal-tab.js

@@ -0,0 +1,35 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+/** Page kind `openTab` names; unique among the tab types in force. */
+export const PODMAN_TERMINAL_KIND = "podman-terminal";
+/** Implementation id the body, title and guide card register under. */
+export const PODMAN_TERMINAL_TAB_ID = "@exagone313/dsh-podman";
+// Keyboard profiles for opening a Podman terminal. The shortcuts registry
+// validates every declared default and THROWS on one it does not admit, inside
+// apply(), which fails the whole client entry and the web boot — so these
+// profiles are load-bearing, not cosmetic:
+// - Linux Web admits only Ctrl+/, Ctrl+Shift+, and Ctrl+Shift+. (the browser and
+//   system reservation rules), so no `web:linux` default can exist.
+// - macOS Web admits Ctrl+` and Meta+Shift+`, but not Ctrl+Shift+`; Windows Web
+//   admits both Ctrl+` and Ctrl+Shift+`.
+// - Desktop accepts Ctrl+` on every platform.
+//
+// The preferred binding is the built-in terminal's own Ctrl+`; this plugin's
+// bundle patch disables that client UI, which is what frees it.
+export const PODMAN_TERMINAL_SHORTCUT_DEFAULTS = {
+    "desktop:macos": { code: "Backquote", modifiers: ["control"] },
+    "desktop:windows": { code: "Backquote", modifiers: ["control"] },
+    "desktop:linux": { code: "Backquote", modifiers: ["control"] },
+    "web:macos": { code: "Backquote", modifiers: ["control"] },
+    "web:windows": { code: "Backquote", modifiers: ["control"] },
+};
+// Registered when the preferred binding is refused — the built-in terminal UI
+// is enabled again and still owns Ctrl+`, or another command claimed it.
+export const PODMAN_TERMINAL_SHORTCUT_FALLBACK_DEFAULTS = {
+    "desktop:macos": { code: "Backquote", modifiers: ["control", "shift"] },
+    "desktop:windows": { code: "Backquote", modifiers: ["control", "shift"] },
+    "desktop:linux": { code: "Backquote", modifiers: ["control", "shift"] },
+    "web:macos": { code: "Backquote", modifiers: ["meta", "shift"] },
+    "web:windows": { code: "Backquote", modifiers: ["control", "shift"] },
+};

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

@@ -0,0 +1,33 @@
+import type { ContainerView } from "./card-protocol.js";
+import type { TerminalShellView } from "./terminal-protocol.js";
+/**
+ * The named containers selectable for one workspace, sorted.
+ *
+ * The empty value is not repeated here: the picker's own placeholder already
+ * means "the workspace's default container".
+ * @param containers - container rows from the card snapshot.
+ * @param workspaceSlug - the selected workspace's slug.
+ * @returns logical container names, excluding the default.
+ */
+export declare function containerOptions(containers: readonly ContainerView[], workspaceSlug: string | undefined): string[];
+/**
+ * The remembered container, but only while the workspace still offers it.
+ * @param remembered - the container name the card started last time.
+ * @param options - the workspace's selectable container names.
+ * @returns the remembered name, or `""` for the workspace's default container.
+ */
+export declare function validContainer(remembered: string | undefined, options: readonly string[]): string;
+/**
+ * The remembered shell, but only while the chosen container still offers it —
+ * the same container may have been recreated from another image.
+ * @param remembered - the absolute shell path the card started last time.
+ * @param shells - the shells the host discovered in the chosen container.
+ * @returns the remembered path, or `undefined` when it is gone.
+ */
+export declare function validShell(remembered: string | undefined, shells: readonly TerminalShellView[]): string | undefined;
+/**
+ * The program name of a shell path.
+ * @param path - an absolute shell path such as `/usr/bin/bash`, or absent.
+ * @returns the basename, or `undefined` when there is nothing to name.
+ */
+export declare function shellName(path: string | undefined): string | undefined;

package/dist/client/terminal-targets.js

@@ -0,0 +1,65 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+/**
+ * The named containers selectable for one workspace, sorted.
+ *
+ * The empty value is not repeated here: the picker's own placeholder already
+ * means "the workspace's default container".
+ * @param containers - container rows from the card snapshot.
+ * @param workspaceSlug - the selected workspace's slug.
+ * @returns logical container names, excluding the default.
+ */
+export function containerOptions(containers, workspaceSlug) {
+    if (workspaceSlug === undefined || workspaceSlug === "")
+        return [];
+    const names = new Set();
+    for (const container of containers) {
+        if (container.workspaceSlug !== workspaceSlug)
+            continue;
+        if (container.containerName === "" || container.containerName === "default") {
+            continue;
+        }
+        // A podman name is an internal identifier the API rejects; never offer one.
+        if (container.containerName.startsWith("dsh-podman-"))
+            continue;
+        names.add(container.containerName);
+    }
+    return [...names].sort((left, right) => left.localeCompare(right));
+}
+/**
+ * The remembered container, but only while the workspace still offers it.
+ * @param remembered - the container name the card started last time.
+ * @param options - the workspace's selectable container names.
+ * @returns the remembered name, or `""` for the workspace's default container.
+ */
+export function validContainer(remembered, options) {
+    if (remembered === undefined || remembered === "")
+        return "";
+    return options.includes(remembered) ? remembered : "";
+}
+/**
+ * The remembered shell, but only while the chosen container still offers it —
+ * the same container may have been recreated from another image.
+ * @param remembered - the absolute shell path the card started last time.
+ * @param shells - the shells the host discovered in the chosen container.
+ * @returns the remembered path, or `undefined` when it is gone.
+ */
+export function validShell(remembered, shells) {
+    if (remembered === undefined || remembered === "")
+        return undefined;
+    return shells.some((shell) => shell.path === remembered)
+        ? remembered
+        : undefined;
+}
+/**
+ * The program name of a shell path.
+ * @param path - an absolute shell path such as `/usr/bin/bash`, or absent.
+ * @returns the basename, or `undefined` when there is nothing to name.
+ */
+export function shellName(path) {
+    if (path === undefined || path === "")
+        return undefined;
+    const name = path.slice(path.lastIndexOf("/") + 1);
+    return name === "" ? undefined : name;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Publish the name the host reported for one terminal.
+ * @param key - `${sessionId}:${tabId}`, the same composite the host retains by.
+ * @param title - the running shell's name.
+ */
+export declare function publishTerminalTitle(key: string, title: string): void;
+/**
+ * Drop one terminal's title when its body goes away.
+ * @param key - the same composite {@link publishTerminalTitle} used.
+ */
+export declare function forgetTerminalTitle(key: string): void;
+/**
+ * Read the published title.
+ * @param key - the same composite {@link publishTerminalTitle} used.
+ * @returns the name, or `undefined` while nothing has been published.
+ */
+export declare function terminalTitle(key: string): string | undefined;
+/**
+ * Subscribe to title changes.
+ * @param listener - called after every publish or forget.
+ * @returns the unsubscriber.
+ */
+export declare function subscribeTerminalTitles(listener: () => void): () => void;

package/dist/client/terminal-titles.js

@@ -0,0 +1,52 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+// Live tab titles for the Podman terminal, the browser-side peer of the built-in
+// terminal's live name: the host names the running shell in the open stream's
+// `ready` (and `title`) frames, the tab body publishes it here, and the tab chip
+// renders it. The store is module-level and DOM-free so it can be unit-tested
+// from the host program.
+const titles = new Map();
+const listeners = new Set();
+function emit() {
+    for (const listener of listeners)
+        listener();
+}
+/**
+ * Publish the name the host reported for one terminal.
+ * @param key - `${sessionId}:${tabId}`, the same composite the host retains by.
+ * @param title - the running shell's name.
+ */
+export function publishTerminalTitle(key, title) {
+    if (title === "" || titles.get(key) === title)
+        return;
+    titles.set(key, title);
+    emit();
+}
+/**
+ * Drop one terminal's title when its body goes away.
+ * @param key - the same composite {@link publishTerminalTitle} used.
+ */
+export function forgetTerminalTitle(key) {
+    if (titles.delete(key))
+        emit();
+}
+/**
+ * Read the published title.
+ * @param key - the same composite {@link publishTerminalTitle} used.
+ * @returns the name, or `undefined` while nothing has been published.
+ */
+export function terminalTitle(key) {
+    return titles.get(key);
+}
+/**
+ * Subscribe to title changes.
+ * @param listener - called after every publish or forget.
+ * @returns the unsubscriber.
+ */
+export function subscribeTerminalTitles(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}

package/dist/client/terminal-transport.d.ts

@@ -0,0 +1,63 @@
+import { type TerminalControl, type TerminalFrame, type TerminalOpenQuery, type TerminalRetainedView, type TerminalShellView, type TerminalTargetView } from "./terminal-protocol.js";
+export type TerminalStreamQuery = TerminalOpenQuery & {
+    readonly reopen?: boolean;
+};
+/**
+ * Open or reattach one terminal and deliver every frame to `onFrame`.
+ *
+ * The route answers one JSON frame per line (`application/x-ndjson`), so the
+ * body is decoded incrementally and split on newlines; a partial trailing line
+ * is flushed once the stream ends. Aborting `signal` rejects the returned
+ * promise with an `AbortError`, which callers treat as a closed stream rather
+ * than a failure.
+ * @param query - session, tab, target shell and initial geometry.
+ * @param onFrame - per-frame callback, in arrival order.
+ * @param signal - lifetime of this attachment.
+ */
+export declare function openTerminalStream(query: TerminalStreamQuery, onFrame: (frame: TerminalFrame) => void, signal: AbortSignal): Promise<void>;
+/**
+ * Send one control request (input, resize, rename or close).
+ * @param control - the control to apply.
+ * @throws when the host refuses it: an unknown terminal, or a malformed body.
+ */
+export declare function sendTerminalControl(control: TerminalControl): Promise<void>;
+/**
+ * List the shells a container really provides, `sh`/`bash` first.
+ * @param workspace - the workspace project name, or `""` for the session cwd.
+ * @param container - `""`/`"default"` for the default container, or a named one.
+ * @param sessionId - owning session, used by the host when `workspace` is empty.
+ * @param signal - cancellation of the probe.
+ * @returns the verified shells, in host order.
+ */
+export declare function fetchTerminalShells(workspace: string, container: string, sessionId: string, signal?: AbortSignal): Promise<TerminalShellView[]>;
+/**
+ * The workspace the host resolved for one session.
+ *
+ * A Session belongs to exactly one workspace, whose side panes — and terminals —
+ * are its own, so the browser never asks for a workspace: the host answers from
+ * the session itself and reports when it cannot place it.
+ * @param sessionId - owning session.
+ * @param signal - cancellation of the read.
+ * @returns the resolved workspace and its harness workspace slug.
+ * @throws when the host cannot determine the session's workspace.
+ */
+export declare function fetchTerminalTarget(sessionId: string, signal?: AbortSignal): Promise<TerminalTargetView>;
+/**
+ * List the terminals this session still has retained on the host.
+ * @param sessionId - owning session.
+ * @returns the retained terminals, oldest first.
+ */
+export declare function fetchRetainedTerminals(sessionId: string): Promise<TerminalRetainedView[]>;
+/**
+ * Encode bytes for the wire. Control frames carry binary keyboard input, so the
+ * conversion is byte-exact and never goes through a UTF-8 string round trip.
+ * @param bytes - raw bytes.
+ * @returns standard base64.
+ */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/**
+ * Decode wire bytes into a `Uint8Array` xterm can write unchanged.
+ * @param data - standard base64.
+ * @returns the decoded bytes.
+ */
+export declare function base64ToBytes(data: string): Uint8Array;

package/dist/client/terminal-transport.js

@@ -0,0 +1,207 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+// The terminal tab's browser half of the host routes. Everything travels over
+// same-origin `fetch` on the harness API channel, which carries the browser
+// session the harness issued for it; no service is injected here so the module
+// stays testable and usable from any component.
+import { TERMINAL_PATH, TERMINAL_RETAINED_PATH, TERMINAL_SHELLS_PATH, TERMINAL_TARGET_PATH, } from "./terminal-protocol.js";
+async function failure(response) {
+    try {
+        const body = (await response.json());
+        if (typeof body.error === "string" && body.error !== "") {
+            return new Error(body.error);
+        }
+    }
+    catch {
+        // A non-JSON body falls through to the status text.
+    }
+    return new Error(`terminal request failed (${response.status})`);
+}
+function endpoint(path) {
+    return new URL(path, globalThis.location.origin);
+}
+function trimmed(value) {
+    return typeof value === "string" ? value : "";
+}
+/**
+ * Open or reattach one terminal and deliver every frame to `onFrame`.
+ *
+ * The route answers one JSON frame per line (`application/x-ndjson`), so the
+ * body is decoded incrementally and split on newlines; a partial trailing line
+ * is flushed once the stream ends. Aborting `signal` rejects the returned
+ * promise with an `AbortError`, which callers treat as a closed stream rather
+ * than a failure.
+ * @param query - session, tab, target shell and initial geometry.
+ * @param onFrame - per-frame callback, in arrival order.
+ * @param signal - lifetime of this attachment.
+ */
+export async function openTerminalStream(query, onFrame, signal) {
+    const url = endpoint(TERMINAL_PATH);
+    url.searchParams.set("sessionId", query.sessionId);
+    url.searchParams.set("tabId", query.tabId);
+    url.searchParams.set("workspace", query.workspace);
+    url.searchParams.set("container", query.container);
+    url.searchParams.set("shell", query.shell);
+    url.searchParams.set("cols", String(query.cols));
+    url.searchParams.set("rows", String(query.rows));
+    if (query.reopen === true)
+        url.searchParams.set("reopen", "1");
+    const response = await fetch(url, {
+        headers: { accept: "application/x-ndjson" },
+        signal,
+    });
+    if (!response.ok)
+        throw await failure(response);
+    if (response.body === null)
+        throw new Error("terminal stream has no body");
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffered = "";
+    const emit = (line) => {
+        const text = line.trim();
+        if (text === "")
+            return;
+        onFrame(JSON.parse(text));
+    };
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffered += decoder.decode(value, { stream: true });
+        let newline = buffered.indexOf("\n");
+        while (newline !== -1) {
+            emit(buffered.slice(0, newline));
+            buffered = buffered.slice(newline + 1);
+            newline = buffered.indexOf("\n");
+        }
+    }
+    // A multi-byte character split across the last chunk survives this flush.
+    buffered += decoder.decode();
+    if (buffered !== "")
+        emit(buffered);
+}
+/**
+ * Send one control request (input, resize, rename or close).
+ * @param control - the control to apply.
+ * @throws when the host refuses it: an unknown terminal, or a malformed body.
+ */
+export async function sendTerminalControl(control) {
+    const response = await fetch(endpoint(TERMINAL_PATH), {
+        method: "POST",
+        headers: {
+            accept: "application/json",
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(control),
+    });
+    if (!response.ok)
+        throw await failure(response);
+}
+/**
+ * List the shells a container really provides, `sh`/`bash` first.
+ * @param workspace - the workspace project name, or `""` for the session cwd.
+ * @param container - `""`/`"default"` for the default container, or a named one.
+ * @param sessionId - owning session, used by the host when `workspace` is empty.
+ * @param signal - cancellation of the probe.
+ * @returns the verified shells, in host order.
+ */
+export async function fetchTerminalShells(workspace, container, sessionId, signal) {
+    const url = endpoint(TERMINAL_SHELLS_PATH);
+    url.searchParams.set("workspace", workspace);
+    url.searchParams.set("container", container);
+    url.searchParams.set("sessionId", sessionId);
+    const response = await fetch(url, {
+        headers: { accept: "application/json" },
+        signal,
+    });
+    if (!response.ok)
+        throw await failure(response);
+    const body = (await response.json());
+    if (!Array.isArray(body.shells))
+        return [];
+    return body.shells.map((shell) => ({
+        name: trimmed(shell.name),
+        path: trimmed(shell.path),
+    }));
+}
+/**
+ * The workspace the host resolved for one session.
+ *
+ * A Session belongs to exactly one workspace, whose side panes — and terminals —
+ * are its own, so the browser never asks for a workspace: the host answers from
+ * the session itself and reports when it cannot place it.
+ * @param sessionId - owning session.
+ * @param signal - cancellation of the read.
+ * @returns the resolved workspace and its harness workspace slug.
+ * @throws when the host cannot determine the session's workspace.
+ */
+export async function fetchTerminalTarget(sessionId, signal) {
+    const url = endpoint(TERMINAL_TARGET_PATH);
+    url.searchParams.set("sessionId", sessionId);
+    const response = await fetch(url, {
+        headers: { accept: "application/json" },
+        signal,
+    });
+    if (!response.ok)
+        throw await failure(response);
+    const body = (await response.json());
+    return {
+        workspace: trimmed(body.workspace),
+        workspaceSlug: trimmed(body.workspaceSlug),
+    };
+}
+/**
+ * List the terminals this session still has retained on the host.
+ * @param sessionId - owning session.
+ * @returns the retained terminals, oldest first.
+ */
+export async function fetchRetainedTerminals(sessionId) {
+    const url = endpoint(TERMINAL_RETAINED_PATH);
+    url.searchParams.set("sessionId", sessionId);
+    const response = await fetch(url, {
+        headers: { accept: "application/json" },
+    });
+    if (!response.ok)
+        throw await failure(response);
+    const body = (await response.json());
+    if (!Array.isArray(body.terminals))
+        return [];
+    return body.terminals.map((terminal) => {
+        const view = terminal;
+        return {
+            tabId: trimmed(view.tabId),
+            terminalId: trimmed(view.terminalId),
+            title: trimmed(view.title),
+            workspace: trimmed(view.workspace),
+            container: trimmed(view.container),
+            shell: trimmed(view.shell),
+        };
+    });
+}
+/**
+ * Encode bytes for the wire. Control frames carry binary keyboard input, so the
+ * conversion is byte-exact and never goes through a UTF-8 string round trip.
+ * @param bytes - raw bytes.
+ * @returns standard base64.
+ */
+export function bytesToBase64(bytes) {
+    let binary = "";
+    for (let index = 0; index < bytes.length; index++) {
+        binary += String.fromCharCode(bytes[index]);
+    }
+    return btoa(binary);
+}
+/**
+ * Decode wire bytes into a `Uint8Array` xterm can write unchanged.
+ * @param data - standard base64.
+ * @returns the decoded bytes.
+ */
+export function base64ToBytes(data) {
+    const binary = atob(data);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index++) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+}