@exagone313/dsh-podman 0.2.0-rc.2

package/dist/tool-params.js

@@ -0,0 +1,494 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+const containerParam = {
+    type: "string",
+    description: 'Logical container name; use "default" for the default workspace container.',
+};
+const imageIdParam = { type: "string", description: "Image short name." };
+const packageListParam = {
+    type: "array",
+    items: { type: "string" },
+    description: "Package names to install.",
+};
+const mountModeParam = {
+    type: "string",
+    enum: ["read_only", "read_write"],
+    description: "Read mode of the mount. Defaults to read_only, except for tmpfs mounts, which are always read_write.",
+};
+const mountKindParam = {
+    type: "string",
+    enum: ["project", "tmpfs", "volume", "secret"],
+    description: "Kind of mount: a project bind, a tmpfs, a named volume, or a named secret.",
+};
+// A project mount names a path under the projects root, so it may include
+// subdirectories: `team` mounts the project, `team/src` a directory inside it.
+const projectPathDescription = 'Project path under the projects root to mount, e.g. "team" or "team/src".';
+const projectMountItemParam = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        project: { type: "string", description: projectPathDescription },
+        mode: mountModeParam,
+        destination: {
+            type: "string",
+            description: "Destination path inside the container (volume, tmpfs, and secret mounts only; project mounts always mount at their project root).",
+        },
+        kind: mountKindParam,
+        volume: { type: "string", description: "Volume name to mount." },
+        secret: { type: "string", description: "Secret name to mount as a file." },
+    },
+    required: [],
+};
+const mountsParam = {
+    type: "array",
+    items: projectMountItemParam,
+    description: "Optional mounts to apply: a project bind, a tmpfs, a named volume, or a secret.",
+};
+export const envParam = {
+    type: "object",
+    additionalProperties: { type: "string" },
+    description: "Environment variables.",
+};
+// The complete PATH-addition list, shared by the tools that set it outright.
+const pathsParam = {
+    type: "array",
+    items: {
+        type: "string",
+        description: "Absolute directory to prepend to the container's PATH (no ':', NUL, or newline).",
+    },
+    description: "Complete ordered list of PATH additions, highest priority first. Replaces the current list; an empty list clears it.",
+};
+// The optional process identity a tool may request, shared by the tools that
+// can run a process as another user.
+const uidParam = {
+    type: "integer",
+    minimum: 0,
+    description: "Run the process as this uid (defaults to the container user).",
+};
+const gidParam = {
+    type: "integer",
+    minimum: 0,
+    description: "Run the process as this gid. Defaults to the uid when uid is set.",
+};
+const groupsParam = {
+    type: "array",
+    items: { type: "integer", minimum: 0 },
+    description: "Supplementary group ids; replaces the process's whole supplementary set.",
+};
+const descriptionParam = {
+    type: "string",
+    description: "Clear, concise description of what this command does in active voice, 5-10 words.",
+};
+const timeoutMsParam = {
+    type: "number",
+    description: "Timeout in milliseconds; the command is killed when it expires.",
+};
+export const imageListParameters = {
+    type: "object",
+    properties: {},
+    required: [],
+};
+export const imageGetParameters = {
+    type: "object",
+    properties: { imageId: imageIdParam },
+    required: ["imageId"],
+};
+export const imageBuildParameters = {
+    type: "object",
+    properties: {
+        imageId: imageIdParam,
+        parent: {
+            type: "string",
+            description: "Short name of the parent image (a base like archlinux/ubuntu/alpine, or an existing custom image).",
+        },
+        packages: packageListParam,
+    },
+    required: ["imageId", "parent", "packages"],
+};
+export const imageRebuildParameters = {
+    type: "object",
+    properties: { imageId: imageIdParam },
+    required: ["imageId"],
+};
+export const imageRebuildAllParameters = {
+    type: "object",
+    properties: {},
+    required: [],
+};
+export const imageRemoveParameters = {
+    type: "object",
+    properties: { imageId: imageIdParam },
+    required: ["imageId"],
+};
+export const containerListParameters = {
+    type: "object",
+    properties: {},
+    required: [],
+};
+export const containerStartParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        image: {
+            type: "string",
+            description: "Image short name (base or custom).",
+        },
+        mounts: mountsParam,
+        env: envParam,
+        secretEnv: { type: "object", additionalProperties: { type: "string" }, description: "Secret environment variables (env var name to secret short name)." },
+        paths: pathsParam,
+    },
+    required: ["container"],
+};
+export const containerRecreateParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        image: {
+            type: "string",
+            description: "Image ID to recreate the container with; defaults to the container's current image.",
+        },
+        mounts: mountsParam,
+        env: envParam,
+        secretEnv: { type: "object", additionalProperties: { type: "string" }, description: "Secret environment variables (env var name to secret short name)." },
+        paths: pathsParam,
+    },
+    required: ["container"],
+};
+export const containerMountListParameters = {
+    type: "object",
+    properties: { container: containerParam },
+    required: ["container"],
+};
+export const containerMountAddParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        kind: mountKindParam,
+        project: { type: "string", description: projectPathDescription },
+        destination: {
+            type: "string",
+            description: "Destination path inside the container (volume, tmpfs, and secret mounts only; project mounts always mount at their project root).",
+        },
+        mode: mountModeParam,
+        volume: { type: "string", description: "Named volume to mount." },
+        secret: { type: "string", description: "Named secret to mount." },
+    },
+    required: ["container"],
+};
+export const containerMountRemoveParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        kind: {
+            type: "string",
+            enum: ["project", "tmpfs", "volume", "secret"],
+            description: "Kind of mount to remove; inferred from secret or volume when omitted, otherwise project. Pass tmpfs explicitly: it has no name to infer from.",
+        },
+        project: {
+            type: "string",
+            description: "Project path of the project mount to remove.",
+        },
+        volume: {
+            type: "string",
+            description: "Named volume to remove; identifies the mount, so pass destination as well when the volume is mounted more than once.",
+        },
+        secret: {
+            type: "string",
+            description: "Named secret the removed mount must use; identifies the mount, so pass destination as well when the secret is mounted more than once.",
+        },
+        destination: {
+            type: "string",
+            description: "Destination path inside the container. Required for tmpfs; for a volume or secret it identifies the mount (and disambiguates one mounted more than once); not applicable to project mounts.",
+        },
+    },
+    required: ["container"],
+};
+export const containerMountUpdateParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        kind: {
+            type: "string",
+            enum: ["project", "volume"],
+            description: "Kind of mount to update; inferred from volume when omitted, otherwise project. Only project and volume mounts carry a mode.",
+        },
+        project: {
+            type: "string",
+            description: "Project path of the project mount to update.",
+        },
+        volume: {
+            type: "string",
+            description: "Named volume to update; identifies the mount, so pass destination as well when the volume is mounted more than once.",
+        },
+        destination: {
+            type: "string",
+            description: "Destination path inside the container; for a volume it identifies the mount (and disambiguates one mounted more than once); not applicable to project mounts.",
+        },
+        mode: mountModeParam,
+    },
+    required: ["container", "mode"],
+};
+export const containerPathSetParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        paths: pathsParam,
+    },
+    required: ["container", "paths"],
+};
+export const containerPathAddParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        path: {
+            type: "string",
+            description: "Absolute directory to prepend to the container's PATH (no ':', NUL, or newline). An existing entry is moved to the front.",
+        },
+    },
+    required: ["container", "path"],
+};
+export const containerPathRemoveParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        path: {
+            type: "string",
+            description: "PATH addition to remove. A directory that is only part of the container's default PATH cannot be removed.",
+        },
+    },
+    required: ["container", "path"],
+};
+export const containerRemoveParameters = {
+    type: "object",
+    properties: { container: containerParam },
+    required: ["container"],
+};
+export const volumeListParameters = {
+    type: "object",
+    properties: {},
+    required: [],
+};
+export const volumeCreateParameters = {
+    type: "object",
+    properties: { name: { type: "string", description: "Volume name to create." } },
+    required: ["name"],
+};
+export const volumeRemoveParameters = {
+    type: "object",
+    properties: { name: { type: "string", description: "Volume name to remove." } },
+    required: ["name"],
+};
+export const secretListParameters = {
+    type: "object",
+    properties: {},
+    required: [],
+};
+export const secretCreateParameters = {
+    type: "object",
+    properties: {
+        name: { type: "string", description: "Secret name to create." },
+        length: {
+            type: "integer",
+            minimum: 1,
+            description: "Length of the generated random value (default 32).",
+        },
+        charset: {
+            type: "string",
+            enum: ["alphanumeric", "hex", "base64url"],
+            description: "Character set for the generated random value.",
+        },
+    },
+    required: ["name"],
+};
+export const secretRemoveParameters = {
+    type: "object",
+    properties: { name: { type: "string", description: "Secret name to remove." } },
+    required: ["name"],
+};
+export const containerSecretAddParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        env: { type: "string", description: "Environment variable name." },
+        secret: { type: "string", description: "Named secret to inject." },
+    },
+    required: ["container", "env", "secret"],
+};
+export const containerSecretRemoveParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        env: { type: "string", description: "Environment variable name." },
+    },
+    required: ["container", "env"],
+};
+export const containerBashParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        command: { type: "string", description: "The shell command to execute." },
+        description: descriptionParam,
+        workdir: { type: "string", description: "Working directory." },
+        timeoutMs: timeoutMsParam,
+        env: envParam,
+        uid: uidParam,
+        gid: gidParam,
+        groups: groupsParam,
+    },
+    required: ["container", "command", "description"],
+};
+export const containerExecParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        argv: {
+            type: "array",
+            items: { type: "string" },
+            description: "The program and arguments to execute.",
+        },
+        description: descriptionParam,
+        workdir: { type: "string", description: "Working directory." },
+        timeoutMs: timeoutMsParam,
+        env: envParam,
+        uid: uidParam,
+        gid: gidParam,
+        groups: groupsParam,
+    },
+    required: ["container", "argv", "description"],
+};
+export const containerReadParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        file_path: {
+            type: "string",
+            description: "Path to read, resolved against the session working directory.",
+        },
+        offset: {
+            type: "integer",
+            minimum: 1,
+            description: "1-based first line to return. Defaults to 1.",
+        },
+        limit: {
+            type: "integer",
+            minimum: 1,
+            description: "Maximum number of lines to return. Defaults to 2000.",
+        },
+    },
+    required: ["container", "file_path"],
+};
+export const containerWriteParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        file_path: {
+            type: "string",
+            description: "Path to write, resolved against the session working directory.",
+        },
+        content: { type: "string", description: "Content to write." },
+    },
+    required: ["container", "file_path", "content"],
+};
+export const containerEditParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        file_path: {
+            type: "string",
+            description: "Path to edit, resolved against the session working directory.",
+        },
+        old_string: { type: "string", description: "Literal text to replace." },
+        new_string: { type: "string", description: "Replacement text." },
+        replace_all: {
+            type: "boolean",
+            description: "Replace every occurrence. Defaults to false; when false, old_string must appear exactly once.",
+        },
+    },
+    required: ["container", "file_path", "old_string", "new_string"],
+};
+export const containerGlobParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        pattern: { type: "string", description: "File pattern." },
+        path: {
+            type: "string",
+            description: "Directory to search in. Defaults to the session working directory.",
+        },
+    },
+    required: ["container", "pattern"],
+};
+export const containerGrepParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        pattern: { type: "string", description: "Regex to search for." },
+        path: {
+            type: "string",
+            description: "File or directory to search. Defaults to the session working directory.",
+        },
+        include: {
+            type: "string",
+            description: 'One glob filter for which files to search (e.g. "*.ts").',
+        },
+    },
+    required: ["container", "pattern"],
+};
+export const daemonStartParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        name: { type: "string", description: "Daemon name." },
+        argv: {
+            type: "array",
+            items: { type: "string" },
+            description: "Command to run as a daemon.",
+        },
+        cwd: { type: "string", description: "Working directory." },
+        env: envParam,
+        uid: uidParam,
+        gid: gidParam,
+        groups: groupsParam,
+        inheritEnv: {
+            type: "boolean",
+            description: "Inherit the container's environment (default true). When false the daemon receives only PATH and HOME plus env, so container and secret environment variables are not visible.",
+        },
+    },
+    required: ["container", "name", "argv"],
+};
+export const daemonListParameters = {
+    type: "object",
+    properties: { container: containerParam },
+    required: ["container"],
+};
+export const daemonStopParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        name: { type: "string", description: "Daemon name to stop." },
+        signal: { type: "string", description: 'Signal to send (e.g. "SIGTERM").' },
+    },
+    required: ["container", "name"],
+};
+export const daemonRestartParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        name: { type: "string", description: "Daemon name to restart." },
+    },
+    required: ["container", "name"],
+};
+export const daemonLogsParameters = {
+    type: "object",
+    properties: {
+        container: containerParam,
+        name: { type: "string", description: "Daemon name to read logs for." },
+        tailBytes: {
+            type: "integer",
+            description: "Maximum trailing bytes to retain per stream.",
+        },
+    },
+    required: ["container", "name"],
+};

package/dist/tool-schemas.d.ts

@@ -0,0 +1,2 @@
+export * from "./tool-params.js";
+export * from "./tool-defs.js";

package/dist/tool-schemas.js

@@ -0,0 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+export * from "./tool-params.js";
+export * from "./tool-defs.js";

package/dist/tool-views.d.ts

@@ -0,0 +1,2 @@
+export declare function toolCallView(name: string, args: any): unknown;
+export declare function toolResultView(name: string, _args: any, result: any): unknown;

package/dist/tool-views.js

@@ -0,0 +1,56 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import { TOOL_UI } from "./tool-schemas.js";
+// The command tools render as terminal cards; every other tool gets a generic
+// card with its UI title. Views are recomputed on each delivery and never
+// persisted (see the harness tool-presentation contract).
+export function toolCallView(name, args) {
+    if (name === "container_bash" || name === "container_exec") {
+        const command = name === "container_bash"
+            ? String(args?.command ?? "")
+            : Array.isArray(args?.argv)
+                ? args.argv.map((item) => String(item)).join(" ")
+                : "";
+        return {
+            card: "terminal",
+            title: command,
+            ...(typeof args?.description === "string" && args.description !== ""
+                ? { description: args.description }
+                : {}),
+        };
+    }
+    const ui = TOOL_UI[name];
+    if (ui === undefined)
+        return undefined;
+    return { card: "generic", title: ui.title, kind: ui.kind };
+}
+export function toolResultView(name, _args, result) {
+    if (result?.isError)
+        return undefined;
+    if (name !== "container_bash" && name !== "container_exec")
+        return undefined;
+    const text = (result?.content ?? [])
+        .filter((block) => block?.type === "text")
+        .map((block) => block.text)
+        .join("");
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (data === null || typeof data !== "object")
+        return undefined;
+    const output = [data.stdout, data.stderr]
+        .filter((value) => typeof value === "string" && value !== "")
+        .join("");
+    return {
+        card: "terminal",
+        output,
+        ...(data.signal
+            ? { signal: String(data.signal) }
+            : { exitCode: Number(data.exitCode ?? 0) }),
+    };
+}

package/dist/views.test.d.ts

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

package/dist/views.test.js

@@ -0,0 +1,23 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import test from "node:test";
+import assert from "node:assert/strict";
+import { SECRET_BEARING_CONTAINER } from "./test-support.js";
+import { publicContainer } from "./index.js";
+test("publicContainer rebuilds a safe object from an API row", () => {
+    const out = publicContainer(SECRET_BEARING_CONTAINER);
+    assert.deepEqual(Object.keys(out).sort(), [
+        "containerName",
+        "env",
+        "imageId",
+        "mounts",
+        "paths",
+        "secretEnv",
+        "status",
+    ]);
+    assert.deepEqual(out.mounts, [
+        { projectName: "team", mode: "read_write", kind: "project" },
+    ]);
+    assert.deepEqual(out.env, { PATH: "/bin", DB_PASSWORD: "hunter2" });
+});

package/dist/volumes.test.d.ts

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

package/dist/volumes.test.js

@@ -0,0 +1,40 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import test from "node:test";
+import assert from "node:assert/strict";
+import { VOLUME_TOOLS } from "./test-support.js";
+import { TOOLS, toolHandlers } from "./index.js";
+test("volume tools are registered with the expected schemas", () => {
+    for (const name of VOLUME_TOOLS) {
+        const tool = TOOLS.find((entry) => entry.name === name);
+        assert.ok(tool, `${name} registered`);
+        if (name === "volume_remove") {
+            assert.equal(tool.approval, true, "volume_remove must require approval");
+        }
+        else {
+            assert.notEqual(tool.approval, true, `${name} must not require approval`);
+        }
+        assert.equal(tool.parameters.type, "object", `${name} type`);
+        assert.equal(typeof tool.parameters.properties, "object");
+        assert.ok(Array.isArray(tool.parameters.required));
+    }
+    const listTool = TOOLS.find((entry) => entry.name === "volume_list");
+    assert.deepEqual(listTool.parameters.required, []);
+    const createTool = TOOLS.find((entry) => entry.name === "volume_create");
+    assert.deepEqual(createTool.parameters.required, ["name"]);
+    assert.equal(createTool.parameters.properties.name.type, "string");
+    const removeTool = TOOLS.find((entry) => entry.name === "volume_remove");
+    assert.deepEqual(removeTool.parameters.required, ["name"]);
+    assert.equal(removeTool.parameters.properties.name.type, "string");
+});
+test("volume_list and secret_list return name objects", async () => {
+    const volumeResolver = {
+        control: async () => ({ volumes: [{ name: "myvol" }] }),
+    };
+    assert.deepEqual(await toolHandlers.volume_list(volumeResolver, {}, {}), [{ name: "myvol" }]);
+    const secretResolver = {
+        control: async () => ({ secrets: [{ name: "dbpass" }] }),
+    };
+    assert.deepEqual(await toolHandlers.secret_list(secretResolver, {}, {}), [{ name: "dbpass" }]);
+});

package/dist/workspace-binding.d.ts

@@ -0,0 +1,40 @@
+import { grpc } from "./grpc/runtime-client.js";
+export interface WorkspaceBinding {
+    guest: grpc.Client;
+    token: string;
+    socket: string;
+    defaultCwd?: string;
+}
+export interface BindingConfig {
+    socketsRoot: string;
+    defaultImage: string;
+    projectsRoot: string;
+    controlToken: string;
+    readyTimeoutMs?: number;
+}
+export declare class WorkspaceResolver {
+    private readonly config;
+    private readonly registry;
+    private readonly bindings;
+    constructor(config: BindingConfig, registry: any);
+    setConfig(patch: Partial<BindingConfig>): void;
+    getConfig(): Readonly<BindingConfig>;
+    resolve(cwd: unknown): Promise<WorkspaceBinding>;
+    resolveForPath(path: string, cwd: unknown): Promise<WorkspaceBinding>;
+    private containingWorkspace;
+    private workspaceForCwd;
+    resolveSlug(key: string): Promise<WorkspaceBinding>;
+    containerBinding(cwd: unknown, container: string): Promise<WorkspaceBinding>;
+    private ready;
+    private readyTimeoutMs;
+    private ensureReady;
+    private recoverContainer;
+    private resolveBinding;
+    private create;
+    control<T>(method: string, request: unknown): Promise<T>;
+}
+export declare function containerNotFound(container: string, slug?: string): Error;
+export declare function normalizeToolError(error: unknown): Error;
+export declare function workspaceSlug(id: unknown): string;
+export declare function containerRowFor(containers: any[], slug: string, container: string): any | undefined;
+export declare function metadata(token: string): grpc.Metadata;