@exagone313/dsh-podman 0.2.0-rc.2

package/dist/workspace-binding.js

@@ -0,0 +1,275 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import { guestClient, controlClient, grpc, unary, } from "./grpc/runtime-client.js";
+import { isAbsolute, join } from "node:path";
+export class WorkspaceResolver {
+    config;
+    registry;
+    bindings = new Map();
+    constructor(config, registry) {
+        this.config = config;
+        this.registry = registry;
+    }
+    setConfig(patch) {
+        Object.assign(this.config, patch);
+    }
+    getConfig() {
+        return this.config;
+    }
+    async resolve(cwd) {
+        const workspace = await this.workspaceForCwd(cwd);
+        const relativePath = String(workspace.path).replace(`${this.config.projectsRoot}/`, "");
+        const key = workspaceSlug(workspace.id);
+        const binding = await this.ready(key, relativePath);
+        // The default container always keeps its project mount, so the session
+        // directory is always mounted in it.
+        const session = defaultCwdOf(cwd);
+        return session === undefined ? binding : { ...binding, defaultCwd: session };
+    }
+    // Resolve the workspace binding for a filesystem path when the caller did not
+    // supply a session working directory. The 0.1.5 `fs.resolve` contract allows
+    // `{ signal }` alone, and the workspace that CONTAINS the path is the only
+    // sensible owner, so match it by longest canonical-path prefix. A path
+    // outside every workspace is not in any container's filesystem, so it is
+    // reported as missing rather than failing the caller.
+    async resolveForPath(path, cwd) {
+        if (typeof cwd === "string" && cwd !== "")
+            return this.resolve(cwd);
+        if (isAbsolute(path)) {
+            const workspace = this.containingWorkspace(path);
+            if (workspace !== undefined)
+                return this.resolve(String(workspace.path));
+            throw notFoundError(`no DH workspace contains path ${JSON.stringify(path)}`);
+        }
+        throw new Error(`cannot resolve a DH workspace for path ${JSON.stringify(path)}; pass a session working directory`);
+    }
+    containingWorkspace(path) {
+        const entries = this.registry?.list?.() ?? [];
+        let match;
+        for (const workspace of entries) {
+            const root = workspace?.path;
+            if (typeof root !== "string" || root === "")
+                continue;
+            if (path !== root && !path.startsWith(`${root}/`))
+                continue;
+            if (match === undefined || root.length > String(match.path).length) {
+                match = workspace;
+            }
+        }
+        return match;
+    }
+    async workspaceForCwd(cwd) {
+        if (typeof cwd !== "string" || cwd === "") {
+            throw new Error(`cannot resolve a DH workspace without a session working directory (got ${JSON.stringify(cwd)})`);
+        }
+        const workspace = await this.registry?.resolveByPath?.(cwd);
+        if (workspace === undefined) {
+            throw new Error(`no DH workspace owns session cwd ${JSON.stringify(cwd)}`);
+        }
+        return workspace;
+    }
+    resolveSlug(key) {
+        return this.ready(key, key);
+    }
+    async containerBinding(cwd, container) {
+        const workspace = await this.workspaceForCwd(cwd);
+        const slug = workspaceSlug(workspace.id);
+        const result = await this.control("listContainers", {});
+        const row = containerRowFor(result.containers ?? [], slug, container);
+        if (row === undefined) {
+            throw containerNotFound(container, slug);
+        }
+        const socket = row.agentSocketPath;
+        const binding = {
+            guest: guestClient(socket),
+            token: row.agentToken,
+            socket,
+        };
+        const session = defaultCwdOf(cwd);
+        if (session !== undefined &&
+            projectMountCovers(this.config.projectsRoot, row.mounts ?? [], session)) {
+            binding.defaultCwd = session;
+        }
+        await this.ensureReady(binding, slug, container);
+        return binding;
+    }
+    // ready resolves a workspace's default container and waits for its guest
+    // agent, recreating the container once when it is reported running but its
+    // agent never answers (a crashed agent or a lost socket).
+    async ready(key, projectName) {
+        let binding = await this.resolveBinding(key, projectName);
+        try {
+            await waitForReady(binding.guest, this.readyTimeoutMs());
+        }
+        catch {
+            this.bindings.delete(key);
+            binding = await this.resolveBinding(key, projectName);
+            try {
+                await waitForReady(binding.guest, this.readyTimeoutMs());
+            }
+            catch {
+                await this.recoverContainer(key, "default");
+                this.bindings.delete(key);
+                binding = await this.resolveBinding(key, projectName);
+                await waitForReady(binding.guest, this.readyTimeoutMs());
+            }
+        }
+        return binding;
+    }
+    readyTimeoutMs() {
+        const configured = Number(this.config.readyTimeoutMs);
+        return Number.isFinite(configured) && configured > 0 ? configured : 15000;
+    }
+    // ensureReady waits for one binding's guest agent and recovers the container
+    // once when the wait fails.
+    async ensureReady(binding, slug, container) {
+        try {
+            await waitForReady(binding.guest, this.readyTimeoutMs());
+            return;
+        }
+        catch {
+            // Recover below.
+        }
+        await this.recoverContainer(slug, container);
+        await waitForReady(binding.guest, this.readyTimeoutMs());
+    }
+    // recoverContainer best-effort recreates a container whose agent is
+    // unreachable. A failure here is not fatal: the caller's retry surfaces the
+    // real readiness failure.
+    async recoverContainer(slug, container) {
+        try {
+            await this.control("recreateContainer", {
+                workspaceSlug: slug,
+                container,
+            });
+        }
+        catch {
+            // Best-effort.
+        }
+    }
+    resolveBinding(key, projectName) {
+        let binding = this.bindings.get(key);
+        if (binding === undefined) {
+            binding = this.create(key, projectName).catch((error) => {
+                if (this.bindings.get(key) === binding)
+                    this.bindings.delete(key);
+                throw error;
+            });
+            this.bindings.set(key, binding);
+        }
+        return binding;
+    }
+    async create(slug, projectName) {
+        const control = controlClient(join(this.config.socketsRoot, "orchestrator.sock"));
+        const controlMetadata = metadata(this.config.controlToken);
+        let workspace;
+        try {
+            workspace = await unary(control, "describeWorkspace", {
+                workspaceSlug: slug,
+            }, controlMetadata);
+        }
+        catch (error) {
+            if (error.code !== grpc.status.NOT_FOUND)
+                throw error;
+            workspace = await unary(control, "createWorkspace", {
+                workspaceSlug: slug,
+                projectName,
+                imageId: this.config.defaultImage,
+                mounts: [{ projectName, mode: "MOUNT_MODE_READ_WRITE" }],
+            }, controlMetadata);
+        }
+        const socket = workspace.agentSocketPath;
+        return {
+            guest: guestClient(socket),
+            token: workspace.agentToken,
+            socket,
+        };
+    }
+    async control(method, request) {
+        return unary(controlClient(join(this.config.socketsRoot, "orchestrator.sock")), method, request, metadata(this.config.controlToken));
+    }
+}
+// notFoundError builds the harness's missing-path error (`FsErrorCode`
+// `'FS_NOT_FOUND'`). A path outside every workspace is not part of any
+// container's filesystem, so callers must see it as absent: agent-instructions'
+// project-root walk probes ancestors above the workspace and only continues
+// when this code comes back.
+function notFoundError(message) {
+    const error = new Error(message);
+    error.code = "FS_NOT_FOUND";
+    return error;
+}
+// containerNotFound is the one not-found shape every container tool reports.
+export function containerNotFound(container, slug) {
+    const error = new Error(slug === undefined
+        ? `container ${JSON.stringify(container)} not found`
+        : `container ${JSON.stringify(container)} not found in workspace ${JSON.stringify(slug)}`);
+    error.code = "NOT_FOUND";
+    return error;
+}
+// normalizeToolError gives every tool failure one shape: a message without
+// grpc's "<code> <NAME>: " prefix, and a string `code` (the grpc status name
+// when the error carried one) so callers can branch without parsing text.
+export function normalizeToolError(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    const message = raw.replace(/^\d+\s+[A-Z_]+:\s*/, "");
+    const code = error.code;
+    const name = typeof code === "number"
+        ? grpc.status[code]
+        : typeof code === "string"
+            ? code
+            : undefined;
+    const normalized = new Error(message);
+    if (name !== undefined)
+        normalized.code = name;
+    return normalized;
+}
+function waitForReady(agent, timeoutMs = 15000) {
+    return new Promise((resolve, reject) => {
+        agent.waitForReady(Date.now() + timeoutMs, (error) => error ? reject(error) : resolve());
+    });
+}
+// workspaceSlug validates the workspace id that names this workspace's pod
+// (dsh-podman-<slug>) and containers (dsh-podman-<slug>-<logical>). It must be
+// a UUID so a container name can never collide with a pod name.
+export function workspaceSlug(id) {
+    const value = String(id ?? "");
+    if (!UUID_PATTERN.test(value)) {
+        throw new Error(`invalid workspace id ${JSON.stringify(value)}: expected a UUID`);
+    }
+    return value.toLowerCase();
+}
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function containerRowFor(containers, slug, container) {
+    return containers.find((row) => row.workspaceSlug === slug && row.containerName === container);
+}
+export function metadata(token) {
+    const result = new grpc.Metadata();
+    if (token !== "") {
+        result.set("authorization", `bearer ${token}`);
+    }
+    return result;
+}
+// defaultCwdOf returns the session working directory as a usable container
+// path, or undefined when it is unset.
+function defaultCwdOf(cwd) {
+    return typeof cwd === "string" && cwd !== "" ? cwd : undefined;
+}
+// projectMountCovers reports whether a project mount of a container makes the
+// given container path reachable: the mount destination itself or a path below
+// it.
+function projectMountCovers(projectsRoot, mounts, path) {
+    return mounts.some((mount) => {
+        if (!isProjectMount(mount))
+            return false;
+        const destination = `${projectsRoot}/${mount.projectName}`;
+        return path === destination || path.startsWith(`${destination}/`);
+    });
+}
+// isProjectMount reports whether a proto mount is a project mount. An unset
+// kind is the project default.
+function isProjectMount(mount) {
+    const kind = mount?.kind;
+    return kind === undefined || kind === "" || kind === "MOUNT_KIND_PROJECT";
+}

package/dist/workspace-binding.test.d.ts

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

package/dist/workspace-binding.test.js

@@ -0,0 +1,337 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import test from "node:test";
+import assert from "node:assert/strict";
+import grpc from "@grpc/grpc-js";
+import loader from "@grpc/proto-loader";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { mkdirSync } from "node:fs";
+import { controlClient, guestClient } from "./grpc/runtime-client.js";
+import { workspaceSlug, metadata, WorkspaceResolver, containerRowFor, containerNotFound, normalizeToolError, } from "./workspace-binding.js";
+const SLUG = "2c573001-4171-4900-904b-12a5cc02737a";
+const SLUG_SUB = "3d684112-5282-4a11-a15c-23b6dd13848b";
+test("workspaceSlug accepts a UUID workspace id", () => {
+    assert.equal(workspaceSlug(SLUG), SLUG);
+    assert.equal(workspaceSlug(SLUG.toUpperCase()), SLUG);
+});
+test("workspaceSlug rejects anything that is not a UUID", () => {
+    const invalid = [
+        undefined,
+        null,
+        "",
+        "proj",
+        "team-app",
+        "a/b",
+        "..",
+        "a b",
+        `${SLUG}-x`,
+        SLUG.slice(0, -1),
+    ];
+    for (const value of invalid) {
+        assert.throws(() => workspaceSlug(value), /expected a UUID/, `expected ${JSON.stringify(value)} to be rejected`);
+    }
+});
+test("metadata carries the bearer token", () => {
+    const result = metadata("token-1");
+    assert.ok(result instanceof grpc.Metadata);
+    assert.equal(result.get("authorization")[0], "bearer token-1");
+});
+test("metadata omits the header when the token is empty", () => {
+    const result = metadata("");
+    assert.ok(result instanceof grpc.Metadata);
+    assert.equal(result.get("authorization").length, 0);
+});
+test("normalizeToolError strips the grpc prefix and names the code", () => {
+    const prefixed = Object.assign(new Error("5 NOT_FOUND: container not found"), { code: 5 });
+    const normalized = normalizeToolError(prefixed);
+    assert.equal(normalized.message, "container not found");
+    assert.equal(normalized.code, "NOT_FOUND");
+    const plain = normalizeToolError(new Error("boom"));
+    assert.equal(plain.message, "boom");
+    assert.equal(plain.code, undefined);
+    const named = Object.assign(new Error("bad input"), { code: "INVALID_ARGUMENT" });
+    assert.equal(normalizeToolError(named).code, "INVALID_ARGUMENT");
+});
+test("containerNotFound reports one stable shape", () => {
+    assert.equal(containerNotFound("db", "w1").message, 'container "db" not found in workspace "w1"');
+    assert.equal(containerNotFound("db").code, "NOT_FOUND");
+    assert.equal(containerNotFound("db").message, 'container "db" not found');
+});
+test("containerRowFor finds rows by workspace and name", () => {
+    const containers = [
+        { workspaceSlug: "team-app", containerName: "default", status: "running" },
+        { workspaceSlug: "team-app", containerName: "db", status: "stopped" },
+        { workspaceSlug: "other", containerName: "db", status: "running" },
+    ];
+    assert.deepEqual(containerRowFor(containers, "team-app", "db"), {
+        workspaceSlug: "team-app",
+        containerName: "db",
+        status: "stopped",
+    });
+    assert.deepEqual(containerRowFor(containers, "team-app", "default"), {
+        workspaceSlug: "team-app",
+        containerName: "default",
+        status: "running",
+    });
+    assert.equal(containerRowFor(containers, "team-app", "missing"), undefined);
+    assert.equal(containerRowFor([], "team-app", "default"), undefined);
+});
+test("control and guest proto files resolve next to the runtime", () => {
+    const control = controlClient("/tmp/dsh-proto-control.sock");
+    const guest = guestClient("/tmp/dsh-proto-guest.sock");
+    control.close();
+    guest.close();
+});
+async function startControlServer(containers = [], options = {}) {
+    const protoPath = resolve(dirname(fileURLToPath(import.meta.url)), "grpc/proto/dshctl/v1/control.proto");
+    const definition = loader.loadSync(protoPath, {
+        longs: String,
+        enums: String,
+        defaults: true,
+    });
+    const loaded = grpc.loadPackageDefinition(definition);
+    const server = new grpc.Server();
+    const received = [];
+    const createRequests = [];
+    const recreateRequests = [];
+    server.addService(loaded.dshctl.v1.OrchestratorControl.service, {
+        listWorkspaces: (call, callback) => {
+            received.push(call.metadata.get("authorization")[0]);
+            callback(null, { workspaces: [] });
+        },
+        describeWorkspace: (_call, callback) => {
+            callback({ code: grpc.status.NOT_FOUND, details: "workspace not found" });
+        },
+        listContainers: (_call, callback) => {
+            callback(null, { containers });
+        },
+        createWorkspace: (call, callback) => {
+            createRequests.push(call.request);
+            callback(null, {
+                workspaceSlug: call.request.workspaceSlug,
+                agentSocketPath: resolve(socketsRoot, "guest.sock"),
+                agentToken: "tok",
+            });
+        },
+        recreateContainer: (call, callback) => {
+            recreateRequests.push(call.request);
+            callback(null, { workspaceSlug: call.request.workspaceSlug });
+        },
+    });
+    const socketsRoot = resolve(tmpdir(), `dsh-control-test-${process.pid}-${Date.now()}-${Math.random()}`);
+    mkdirSync(socketsRoot, { recursive: true });
+    const socket = resolve(socketsRoot, "orchestrator.sock");
+    await new Promise((ok, fail) => server.bindAsync(`unix:${socket}`, grpc.ServerCredentials.createInsecure(), (error) => (error ? fail(error) : ok())));
+    // Also answer on the guest socket the fake createWorkspace hands back, so a
+    // resolved binding becomes ready immediately instead of waiting out the
+    // readiness deadline.
+    await new Promise((ok, fail) => server.bindAsync(`unix:${resolve(socketsRoot, "guest.sock")}`, grpc.ServerCredentials.createInsecure(), (error) => (error ? fail(error) : ok())));
+    // Point the fake container rows at the same guest socket, so a named
+    // container binding becomes ready immediately too.
+    if (options.rewriteContainerSocket !== false) {
+        for (const row of containers) {
+            row.agentSocketPath = resolve(socketsRoot, "guest.sock");
+        }
+    }
+    return {
+        socketsRoot,
+        received,
+        createRequests,
+        recreateRequests,
+        stop: () => server.forceShutdown(),
+    };
+}
+test("control calls carry the bearer token", async () => {
+    const { socketsRoot, received, stop } = await startControlServer();
+    try {
+        const resolver = new WorkspaceResolver({
+            socketsRoot,
+            defaultImage: "arch",
+            projectsRoot: "/projects",
+            controlToken: "tok-1",
+        }, undefined);
+        await resolver.control("listWorkspaces", {});
+        assert.equal(received[0], "bearer tok-1");
+    }
+    finally {
+        stop();
+    }
+});
+test("control calls omit the token when unset", async () => {
+    const { socketsRoot, received, stop } = await startControlServer();
+    try {
+        const resolver = new WorkspaceResolver({
+            socketsRoot,
+            defaultImage: "arch",
+            projectsRoot: "/projects",
+            controlToken: "",
+        }, undefined);
+        await resolver.control("listWorkspaces", {});
+        assert.equal(received[0], undefined);
+    }
+    finally {
+        stop();
+    }
+});
+test("the auto-created workspace mount stays read-write", async () => {
+    // Additional mounts default to read-only, but the workspace's own project
+    // directory must stay writable or the agent cannot edit the project.
+    const { socketsRoot, createRequests, stop } = await startControlServer();
+    try {
+        const resolver = new WorkspaceResolver({
+            socketsRoot,
+            defaultImage: "arch",
+            projectsRoot: "/projects",
+            controlToken: "",
+        }, { resolveByPath: () => ({ id: SLUG, path: "/projects/team" }) });
+        await resolver.resolve("/projects/team");
+        assert.equal(createRequests.length, 1);
+        assert.equal(createRequests[0].projectName, "team");
+        const mounts = createRequests[0].mounts;
+        assert.equal(mounts.length, 1);
+        assert.equal(mounts[0].projectName, "team");
+        assert.equal(mounts[0].mode, "MOUNT_MODE_READ_WRITE");
+    }
+    finally {
+        stop();
+    }
+});
+test("resolve exposes the session directory as the default cwd", async () => {
+    const { socketsRoot, stop } = await startControlServer();
+    try {
+        const resolver = new WorkspaceResolver({
+            socketsRoot,
+            defaultImage: "arch",
+            projectsRoot: "/projects",
+            controlToken: "",
+        }, { resolveByPath: () => ({ id: SLUG, path: "/projects/team" }) });
+        const binding = await resolver.resolve("/projects/team");
+        assert.equal(binding.defaultCwd, "/projects/team");
+    }
+    finally {
+        stop();
+    }
+});
+test("containerBinding exposes the session directory only when a project mount covers it", async () => {
+    const mounted = await startControlServer([{
+            workspaceSlug: SLUG,
+            containerName: "db",
+            agentSocketPath: "/run/x.sock",
+            agentToken: "tok",
+            mounts: [{ kind: "MOUNT_KIND_PROJECT", projectName: "team" }],
+        }]);
+    try {
+        const resolver = new WorkspaceResolver({
+            socketsRoot: mounted.socketsRoot,
+            defaultImage: "arch",
+            projectsRoot: "/projects",
+            controlToken: "",
+        }, { resolveByPath: () => ({ id: SLUG, path: "/projects/team" }) });
+        const binding = await resolver.containerBinding("/projects/team", "db");
+        assert.equal(binding.defaultCwd, "/projects/team");
+    }
+    finally {
+        mounted.stop();
+    }
+    const unmounted = await startControlServer([{
+            workspaceSlug: SLUG,
+            containerName: "db",
+            agentSocketPath: "/run/x.sock",
+            agentToken: "tok",
+            mounts: [{ kind: "MOUNT_KIND_VOLUME", volume: "data", destination: "/data" }],
+        }]);
+    try {
+        const resolver = new WorkspaceResolver({
+            socketsRoot: unmounted.socketsRoot,
+            defaultImage: "arch",
+            projectsRoot: "/projects",
+            controlToken: "",
+        }, { resolveByPath: () => ({ id: SLUG, path: "/projects/team" }) });
+        const binding = await resolver.containerBinding("/projects/team", "db");
+        assert.equal(binding.defaultCwd, undefined);
+    }
+    finally {
+        unmounted.stop();
+    }
+});
+test("containerBinding recreates a container whose agent never answers", async () => {
+    const control = await startControlServer([{
+            workspaceSlug: SLUG,
+            containerName: "db",
+            agentSocketPath: "/nonexistent/guest.sock",
+            agentToken: "tok",
+            mounts: [],
+        }], { rewriteContainerSocket: false });
+    try {
+        const resolver = new WorkspaceResolver({
+            socketsRoot: control.socketsRoot,
+            defaultImage: "arch",
+            projectsRoot: "/projects",
+            controlToken: "",
+            readyTimeoutMs: 50,
+        }, { resolveByPath: () => ({ id: SLUG, path: "/projects/team" }) });
+        await assert.rejects(() => resolver.containerBinding("/projects/team", "db"));
+        assert.equal(control.recreateRequests.length, 1);
+        assert.equal(control.recreateRequests[0].container, "db");
+    }
+    finally {
+        control.stop();
+    }
+});
+test("resolveForPath derives the workspace from an absolute path without a cwd", async () => {
+    const { socketsRoot, createRequests, stop } = await startControlServer();
+    try {
+        const resolver = new WorkspaceResolver({
+            socketsRoot,
+            defaultImage: "arch",
+            projectsRoot: "/projects",
+            controlToken: "",
+        }, {
+            list: () => [
+                { id: SLUG, path: "/projects/team" },
+                { id: SLUG_SUB, path: "/projects/team/sub" },
+            ],
+            resolveByPath: (path) => path === "/projects/team/sub"
+                ? { id: SLUG_SUB, path: "/projects/team/sub" }
+                : { id: SLUG, path: "/projects/team" },
+        });
+        const binding = await resolver.resolveForPath("/projects/team/sub/AGENTS.md", undefined);
+        assert.equal(binding.defaultCwd, "/projects/team/sub");
+        assert.equal(createRequests[0].projectName, "team/sub");
+    }
+    finally {
+        stop();
+    }
+});
+test("resolveForPath rejects paths it cannot map to a workspace", async () => {
+    const resolver = new WorkspaceResolver({
+        socketsRoot: "/run/dsh",
+        defaultImage: "arch",
+        projectsRoot: "/projects",
+        controlToken: "",
+    }, {
+        list: () => [{ id: SLUG, path: "/projects/team" }],
+        resolveByPath: () => undefined,
+    });
+    await assert.rejects(() => resolver.resolveForPath("README.md", undefined), /session working directory/);
+    // A path outside every workspace is not in any container's filesystem: it is
+    // reported with the harness's missing-path code so callers treat it as absent
+    // (agent-instructions walks ancestors above the workspace this way).
+    await assert.rejects(() => resolver.resolveForPath("/elsewhere/file", undefined), (error) => error instanceof Error && error.code === "FS_NOT_FOUND");
+});
+test("resolve rejects a missing cwd without stringifying it", async () => {
+    const resolver = new WorkspaceResolver({
+        socketsRoot: "/run/dsh",
+        defaultImage: "arch",
+        projectsRoot: "/projects",
+        controlToken: "",
+    }, {
+        resolveByPath: () => {
+            throw new Error("resolveByPath must not be called with a missing cwd");
+        },
+    });
+    await assert.rejects(() => resolver.resolve(undefined), /session working directory/);
+});