@clipboard-health/groundcrew 4.0.3 → 4.2.0

package/dist/lib/tmuxAdapter.js

@@ -0,0 +1,156 @@
+/**
+ * tmux Workspace backend. Workspaces live as windows inside one dedicated
+ * `groundcrew` tmux session; the window name is the ticket id. tmux can't
+ * paint status pills, so `open` silently drops `spec.status`. This is the
+ * Linux/WSL path where cmux is unavailable.
+ */
+import { isSignalAborted, runWorkspaceCommand, } from "./workspaceAdapter.js";
+import { errorMessage, log, readEnvironmentVariable } from "./util.js";
+const TMUX_SESSION = "groundcrew";
+// `tmux new-session -d -s …` always creates one initial window. Without
+// `-n`, that window is named after the running shell (e.g. "0" / "zsh") and
+// would surface from `list()` as a phantom workspace. We name it with this
+// sentinel and filter it out — it stays around as a placeholder so the
+// session doesn't collapse when the last ticket window closes.
+const TMUX_IDLE_WINDOW = "_groundcrew_idle";
+export const tmuxAdapter = {
+    async open(spec, signal) {
+        await ensureTmuxSession(signal);
+        const target = tmuxTarget(spec.name);
+        const keepDeadWindowsEnv = readEnvironmentVariable("GROUNDCREW_KEEP_DEAD_WINDOWS");
+        const keepDeadWindows = keepDeadWindowsEnv !== undefined && keepDeadWindowsEnv.length > 0;
+        await runWorkspaceCommand("tmux", [
+            "new-window",
+            "-d",
+            "-t",
+            TMUX_SESSION,
+            "-n",
+            spec.name,
+            "-c",
+            spec.cwd,
+            spec.command,
+            ";",
+            "set-window-option",
+            "-t",
+            target,
+            "remain-on-exit",
+            keepDeadWindows ? "on" : "off",
+            ";",
+            "set-window-option",
+            "-t",
+            target,
+            "allow-rename",
+            "off",
+        ], signal);
+        // tmux can't paint status pills; spec.status is silently dropped.
+    },
+    async list(signal) {
+        const probe = await probeTmuxList("#{window_name}\t#{pane_dead}", signal);
+        if (probe.status === "missing") {
+            return [];
+        }
+        if (probe.status === "failed") {
+            log(`tmux list-windows failed: ${probe.reason}`);
+            // oxlint-disable-next-line unicorn/no-useless-undefined -- undefined marks the workspace backend as unavailable.
+            return undefined;
+        }
+        return parseTmuxWindows(probe.output);
+    },
+    async close(name, signal) {
+        try {
+            await runWorkspaceCommand("tmux", ["kill-window", "-t", tmuxTarget(name)], signal);
+            return { kind: "closed" };
+        }
+        catch (error) {
+            if (isSignalAborted(signal)) {
+                throw error;
+            }
+            if (isTmuxNotFoundError(error)) {
+                return { kind: "missing" };
+            }
+            throw error;
+        }
+    },
+    accessHint(name) {
+        return { kind: "attachCommand", command: `tmux attach -t ${tmuxTarget(name)}` };
+    },
+};
+function tmuxTarget(name) {
+    return `${TMUX_SESSION}:${name}`;
+}
+function isTmuxNotFoundError(error) {
+    // runCommand surfaces the child's stderr in error.message, so the "no
+    // server" / "missing session" / "can't find window" signatures are visible
+    // without a separate stderr probe.
+    const message = errorMessage(error);
+    return (message.includes("no server running") ||
+        message.includes("can't find session") ||
+        message.includes("can't find window"));
+}
+async function probeTmuxList(format, signal) {
+    try {
+        return {
+            status: "ok",
+            output: await runWorkspaceCommand("tmux", ["list-windows", "-t", TMUX_SESSION, "-F", format], signal),
+        };
+    }
+    catch (error) {
+        if (isSignalAborted(signal)) {
+            throw error;
+        }
+        if (isTmuxNotFoundError(error)) {
+            return { status: "missing" };
+        }
+        return { status: "failed", reason: errorMessage(error) };
+    }
+}
+async function ensureTmuxSession(signal) {
+    try {
+        await runWorkspaceCommand("tmux", ["has-session", "-t", TMUX_SESSION], signal);
+        return;
+    }
+    catch (error) {
+        if (isSignalAborted(signal)) {
+            throw error;
+        }
+        /* session missing or server down; create it */
+    }
+    try {
+        await runWorkspaceCommand("tmux", ["new-session", "-d", "-s", TMUX_SESSION, "-n", TMUX_IDLE_WINDOW], signal);
+    }
+    catch (error) {
+        if (isSignalAborted(signal)) {
+            throw error;
+        }
+        try {
+            await runWorkspaceCommand("tmux", ["has-session", "-t", TMUX_SESSION], signal);
+        }
+        catch {
+            throw error;
+        }
+    }
+}
+function parseTmuxWindows(output) {
+    const items = [];
+    for (const line of output.split("\n")) {
+        if (line.length === 0) {
+            continue;
+        }
+        const [name, deadFlag] = line.split("\t");
+        /* v8 ignore next 3 @preserve -- split on a non-empty string always yields a non-empty first element */
+        if (name === undefined || name.length === 0) {
+            continue;
+        }
+        if (name === TMUX_IDLE_WINDOW) {
+            continue;
+        }
+        // pane_dead != 0 means the command exited and the window is a zombie
+        // (only happens when remain-on-exit is on; defense in depth in case a
+        // user-globally-set value beats our per-window override).
+        if (deadFlag !== undefined && deadFlag !== "0") {
+            continue;
+        }
+        items.push({ name });
+    }
+    return items;
+}

package/dist/lib/workspaceAdapter.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared contract for Workspace backends. A Workspace is the host-side
+ * terminal session that runs an agent for one ticket; `Workspace.name` is
+ * the ticket id callers key on. The cmux and tmux adapters implement this
+ * interface in their own files (`cmuxAdapter.ts`, `tmuxAdapter.ts`);
+ * `workspaces.ts` resolves and fronts them. This is internal cleanup, not a
+ * plugin contract — nothing here is a published extension point.
+ */
+export type WorkspaceKind = "cmux" | "tmux";
+export interface Workspace {
+    /** Ticket id; the join key callers use. */
+    name: string;
+}
+export interface WorkspaceStatus {
+    text: string;
+    color?: string;
+    icon?: string;
+}
+export interface WorkspaceAccessHint {
+    kind: "attachCommand";
+    command: string;
+}
+export interface OpenSpec {
+    /** Ticket id; becomes the workspace's name. */
+    name: string;
+    /** Working directory the workspace runs in. */
+    cwd: string;
+    /** Shell string the workspace executes (host setup + agent exec). */
+    command: string;
+    /** Optional status painting. Adapters that can't paint silently drop it. */
+    status?: WorkspaceStatus;
+}
+/**
+ * `unavailable` is "we don't know" — never treat it as "empty," or callers
+ * would close every live workspace by deduction.
+ */
+export type WorkspaceProbe = {
+    kind: "ok";
+    names: Set<string>;
+} | {
+    kind: "unavailable";
+    error?: unknown;
+};
+export type WorkspaceInterruptResult = {
+    kind: "interrupted";
+} | {
+    kind: "missing";
+} | {
+    kind: "unavailable";
+    error?: unknown;
+};
+export type WorkspaceCloseResult = {
+    kind: "closed";
+} | {
+    kind: "missing";
+} | {
+    kind: "unavailable";
+    error?: unknown;
+};
+export interface Adapter {
+    open(spec: OpenSpec, signal?: AbortSignal): Promise<void>;
+    /**
+     * Live workspaces only. Returns:
+     * - `Workspace[]` when the adapter probe succeeded (may be empty).
+     * - `undefined` when the adapter binary failed in a way that doesn't
+     *   distinguish "no live workspaces" from "couldn't ask".
+     */
+    list(signal?: AbortSignal): Promise<Workspace[] | undefined>;
+    /** Closes the workspace or confirms it is not present. */
+    close(name: string, signal?: AbortSignal): Promise<WorkspaceCloseResult>;
+    /**
+     * User-facing way to reach the workspace, or `undefined` when the backend
+     * has no concise external hint.
+     */
+    accessHint(name: string): WorkspaceAccessHint | undefined;
+}
+export declare function runWorkspaceCommand(command: string, arguments_: readonly string[], signal?: AbortSignal): Promise<string>;
+export declare function isSignalAborted(signal?: AbortSignal): boolean;
+//# sourceMappingURL=workspaceAdapter.d.ts.map

package/dist/lib/workspaceAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceAdapter.d.ts","sourceRoot":"","sources":["../../src/lib/workspaceAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5C,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE7C,MAAM,MAAM,wBAAwB,GAChC;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE7C,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE7C,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D;;;;;OAKG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,EAAE,GAAG,SAAS,CAAC,CAAC;IAC7D,0DAA0D;IAC1D,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACzE;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAAC;CAC3D;AAED,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAE7D"}

package/dist/lib/workspaceAdapter.js

@@ -0,0 +1,17 @@
+/**
+ * Shared contract for Workspace backends. A Workspace is the host-side
+ * terminal session that runs an agent for one ticket; `Workspace.name` is
+ * the ticket id callers key on. The cmux and tmux adapters implement this
+ * interface in their own files (`cmuxAdapter.ts`, `tmuxAdapter.ts`);
+ * `workspaces.ts` resolves and fronts them. This is internal cleanup, not a
+ * plugin contract — nothing here is a published extension point.
+ */
+import { runCommandAsync } from "./commandRunner.js";
+export async function runWorkspaceCommand(command, arguments_, signal) {
+    return signal === undefined
+        ? await runCommandAsync(command, arguments_)
+        : await runCommandAsync(command, arguments_, { signal });
+}
+export function isSignalAborted(signal) {
+    return signal?.aborted === true;
+}

package/dist/lib/workspaces.d.ts

@@ -1,62 +1,15 @@
 /**
- * Workspace adapter — opens/lists/closes the host-side terminal session
+ * Workspace facade — opens/lists/closes the host-side terminal session
  * that runs an agent for one ticket. `Workspace.name` is the ticket id;
- * callers key on it. Adapters do their own internal lookup when their
- * backend uses opaque refs.
+ * callers key on it. The cmux and tmux backends live in their own files
+ * (`cmuxAdapter.ts`, `tmuxAdapter.ts`) behind the shared `Adapter`
+ * interface in `workspaceAdapter.ts`; this module resolves which one to
+ * use, caches it per config, and exposes the `workspaces` API.
  */
 import type { ResolvedConfig, WorkspaceKindSetting } from "./config.ts";
 import { type HostCapabilities } from "./host.ts";
-export type WorkspaceKind = "cmux" | "tmux";
-export interface Workspace {
-    /** Ticket id; the join key callers use. */
-    name: string;
-}
-export interface WorkspaceStatus {
-    text: string;
-    color?: string;
-    icon?: string;
-}
-export interface WorkspaceAccessHint {
-    kind: "attachCommand";
-    command: string;
-}
-export interface OpenSpec {
-    /** Ticket id; becomes the workspace's name. */
-    name: string;
-    /** Working directory the workspace runs in. */
-    cwd: string;
-    /** Shell string the workspace executes (host setup + agent exec). */
-    command: string;
-    /** Optional status painting. Adapters that can't paint silently drop it. */
-    status?: WorkspaceStatus;
-}
-/**
- * `unavailable` is "we don't know" — never treat it as "empty," or callers
- * would close every live workspace by deduction.
- */
-export type WorkspaceProbe = {
-    kind: "ok";
-    names: Set<string>;
-} | {
-    kind: "unavailable";
-    error?: unknown;
-};
-export type WorkspaceInterruptResult = {
-    kind: "interrupted";
-} | {
-    kind: "missing";
-} | {
-    kind: "unavailable";
-    error?: unknown;
-};
-export type WorkspaceCloseResult = {
-    kind: "closed";
-} | {
-    kind: "missing";
-} | {
-    kind: "unavailable";
-    error?: unknown;
-};
+import { type OpenSpec, type WorkspaceAccessHint, type WorkspaceCloseResult, type WorkspaceInterruptResult, type WorkspaceKind, type WorkspaceProbe } from "./workspaceAdapter.ts";
+export type { OpenSpec, Workspace, WorkspaceAccessHint, WorkspaceCloseResult, WorkspaceInterruptResult, WorkspaceKind, WorkspaceProbe, WorkspaceStatus, } from "./workspaceAdapter.ts";
 export interface WorkspaceResolution {
     requested: WorkspaceKindSetting;
     resolved: WorkspaceKind;
@@ -77,5 +30,4 @@ export declare const workspaces: {
     interrupt: typeof interruptWorkspace;
     accessHint(config: ResolvedConfig, name: string, signal?: AbortSignal): Promise<WorkspaceAccessHint | undefined>;
 };
-export {};
 //# sourceMappingURL=workspaces.d.ts.map

package/dist/lib/workspaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspaces.d.ts","sourceRoot":"","sources":["../../src/lib/workspaces.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAI1E,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5C,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE7C,MAAM,MAAM,wBAAwB,GAChC;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE7C,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAwU7C,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,oBAAoB,CAAC;IAChC,QAAQ,EAAE,aAAa,CAAC;IACxB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,gBAAgB;IACxB,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,gBAAgB,GAAG,mBAAmB,CAUtF;AAgOD,iBAAe,eAAe,CAC5B,MAAM,EAAE,cAAc,EACtB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CAezB;AAED,iBAAe,kBAAkB,CAC/B,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,wBAAwB,CAAC,CAenC;AAED,eAAO,MAAM,UAAU;IACf,IAAI,SAAS,cAAc,QAAQ,QAAQ,WAAW,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvF,KAAK;IACC,KAAK,SACD,cAAc,QAChB,MAAM,WACH,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC;IAIhC,SAAS;IACH,UAAU,SACN,cAAc,QAChB,MAAM,WACH,WAAW,GACnB,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;CAI5C,CAAC"}
+{"version":3,"file":"workspaces.d.ts","sourceRoot":"","sources":["../../src/lib/workspaces.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE1E,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,aAAa,EAClB,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,QAAQ,EACR,SAAS,EACT,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,aAAa,EACb,cAAc,EACd,eAAe,GAChB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,oBAAoB,CAAC;IAChC,QAAQ,EAAE,aAAa,CAAC;IACxB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,gBAAgB;IACxB,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,gBAAgB,GAAG,mBAAmB,CAUtF;AAsDD,iBAAe,eAAe,CAC5B,MAAM,EAAE,cAAc,EACtB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CAezB;AAED,iBAAe,kBAAkB,CAC/B,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,wBAAwB,CAAC,CAenC;AAED,eAAO,MAAM,UAAU;IACf,IAAI,SAAS,cAAc,QAAQ,QAAQ,WAAW,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvF,KAAK;IACC,KAAK,SACD,cAAc,QAChB,MAAM,WACH,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC;IAIhC,SAAS;IACH,UAAU,SACN,cAAc,QAChB,MAAM,WACH,WAAW,GACnB,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;CAI5C,CAAC"}