@fonlan/dsh-quick-commands 0.1.0

package/lib/types/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @fonlan/dsh-quick-commands host half: per-workspace quick commands.
+ *
+ * Registers the `quick-commands` settings namespace (workspaceId → command
+ * sets + popup anchor), owns the subprocess runner that executes commands with
+ * a fixed workspace cwd, and serves the fenced JSON API the client calls for
+ * config CRUD and live command output.
+ *
+ * Remote workspaces: when the workspace path is a @dsh-ssh/dsh-ssh placeholder
+ * directory and the `sshPool` service is present, commands stream over SSH on
+ * the remote host (same tail/offset semantics as local runs). The SSH backend
+ * is resolved lazily per run, so plugin load order is irrelevant and the
+ * absence of dsh-ssh degrades cleanly to local-only behaviour.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "@fonlan/dsh-quick-commands";
+export declare const inject: string[];
+/** No plugin-level config; all configuration lives in the settings namespace. */
+export declare function apply(ctx: Context): void;

package/lib/types/server/remote.d.ts

@@ -0,0 +1,117 @@
+/** Remote host id + remote working directory decoded from a placeholder path. */
+export interface RemoteWorkspaceRef {
+    hostId: string;
+    /** Remote absolute path of the workspace root. */
+    remotePath: string;
+}
+export declare function remoteRoot(env?: NodeJS.ProcessEnv): string;
+/**
+ * Local absolute path → { hostId, remotePath } when it is a dsh-ssh
+ * placeholder (`<root>/<hostId>/<encoded>`), otherwise null. A coincidentally
+ * matching real directory is never misdetected: the encoded segment must
+ * round-trip to an absolute POSIX path.
+ */
+export declare function localPathToRemoteRef(localPath: string, env?: NodeJS.ProcessEnv): RemoteWorkspaceRef | null;
+/**
+ * Map a session cwd (which may be inside the placeholder workspace, e.g. a
+ * subdirectory of the workspace root) onto the remote filesystem. Only paths
+ * strictly inside the placeholder are re-anchored; anything else falls back to
+ * the workspace's remote root.
+ */
+export declare function resolveRemoteCwd(sessionCwd: string, workspaceLocalPath: string, remotePath: string): string;
+/** Streaming chunk the remote exec yields before the final exit-code item. */
+export interface RemoteExecChunk {
+    stream: 'stdout' | 'stderr';
+    chunk: Buffer;
+}
+/** The terminal item yielded by execStream: remote channel exit code. */
+export interface RemoteExecExit {
+    exitCode: number;
+}
+export type RemoteExecEvent = RemoteExecChunk | RemoteExecExit;
+/** SshConn minimal surface (see dsh-ssh ssh-core SshConn). */
+export interface SshConnLike {
+    execStream(cmd: string, opts?: {
+        cwd?: string;
+        timeoutMs?: number;
+    }): AsyncGenerator<RemoteExecEvent>;
+    exec(cmd: string, opts?: {
+        cwd?: string;
+        timeoutMs?: number;
+    }): Promise<{
+        code: number;
+        signal: string | null;
+        stdout: string;
+        stderr: string;
+    }>;
+}
+/** SshPool minimal surface (see dsh-ssh ssh-core SshPool). */
+export interface SshPoolLike {
+    acquire(cfg: {
+        id: string;
+        [key: string]: unknown;
+    }): Promise<SshConnLike>;
+    release(): void;
+}
+/** Error carrying a SSH-stage tag (mirrors dsh-ssh SshError.stage). */
+export interface SshStageError {
+    stage?: string;
+    message?: string;
+}
+/**
+ * Read one host's connection config from the `dsh-ssh-hosts` settings
+ * namespace (id → HostConfig dict, as written by the @dsh-ssh/dsh-ssh
+ * settings page). Returns `{ ...host, id }` for pool.acquire, or undefined
+ * when the host is not configured. `get` is the settings.get(ns) reader.
+ */
+export declare function readHostConfig(get: (ns: string) => unknown, hostId: string): {
+    id: string;
+    [key: string]: unknown;
+} | undefined;
+/**
+ * One remote execution stream. Consumes conn.execStream in the background,
+ * appends decoded chunks into the caller-provided tail buffers, and records the
+ * terminal outcome.
+ *
+ * The command runs on the remote shell that sshd spawns for the channel (that
+ * shell is the session/process-group leader; `$$` is its pid AND its pgid). The
+ * leader pid is probed by prefixing `echo <marker> $$ >&2` to the command, so
+ * `kill` can terminate the WHOLE process group (`kill -TERM -- -<pid>`), which
+ * `pkill -f` alone cannot do for a child like `sleep 30` whose cmdline does not
+ * match the original command text. The probe line is filtered out of the stderr
+ * stream the user sees (a short buffer handles chunk-cut lines).
+ */
+export declare class RemoteStreamExecutor {
+    private readonly conn;
+    private readonly pool;
+    private cmd;
+    private cwd;
+    private started;
+    /** Remote process-group leader pid (parse the marker line; null until seen). */
+    private leaderPid;
+    /** Raw stderr head buffer for the (possibly chunk-cut) marker line. */
+    private markerBuf;
+    constructor(conn: SshConnLike, pool: SshPoolLike);
+    /**
+     * Start consuming the remote stream, settling the returned promise when the
+     * stream ends. `onData` sees decoded text chunks, `onExit` the terminal
+     * outcome (called exactly once, also on connection failure).
+     */
+    start(cmd: string, cwd: string, onData: (stream: 'stdout' | 'stderr', text: string) => void, onExit: (exit: {
+        exitCode: number | null;
+        signal: string | null;
+        error?: string;
+    }) => void): Promise<void>;
+    /** Route stderr text, swallowing the (possibly split) marker line. */
+    private emitStderr;
+    /** The probed group-leader pid, if the marker line has been seen. */
+    get pid(): number | null;
+    /**
+     * Terminate the remote command's whole process group (best-effort). With the
+     * probed leader pid this is a true group kill (covers children like sleep);
+     * before the probe arrives (or when it never does) it falls back to a
+     * `pkill -f` on the exact `cd <cwd> && <cmd>` channel command line. The
+     * original stream then closes; the caller records signal 'TERM'.
+     */
+    kill(): Promise<void>;
+}

package/lib/types/server/rpc.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { QuickCommandsSettingsFace } from './settings.js';
+import type { QuickRunner } from './runner.js';
+export declare function registerApiRoutes(ctx: Context, runner: QuickRunner, settings: QuickCommandsSettingsFace): () => void;

package/lib/types/server/runner.d.ts

@@ -0,0 +1,114 @@
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+import type { QuickCommandsSettings } from '../shared/contract.js';
+import { type SshPoolLike } from './remote.js';
+/** Optional SSH backend (duck-typed over the @dsh-ssh/dsh-ssh plugin). */
+export interface RemoteBackend {
+    pool: SshPoolLike;
+    /** Resolve one hostId to its connection config (settings `dsh-ssh-hosts`). */
+    resolveHost: (hostId: string) => {
+        id: string;
+        [key: string]: unknown;
+    } | undefined;
+}
+/** Lazily-resolved SSH backend: resolved per run, so load order is irrelevant. */
+export type RemoteBackendResolver = () => RemoteBackend | undefined;
+/** A snapshot reader over one run's captured output (delta + offsets). */
+export interface RunPollResult {
+    kind: 'poll';
+    status: 'running' | 'exited';
+    exitCode: number | null;
+    signal: string | null;
+    stdoutEnd: number;
+    stderrEnd: number;
+    stdoutDelta: string;
+    stderrDelta: string;
+    stdoutLossy: boolean;
+    stderrLossy: boolean;
+}
+/** The runner's exported operations. */
+export interface QuickRunner {
+    /**
+     * Start one command for a workspace (serial: rejects when one is live).
+     * Async: a remote run acquires its SSH connection before returning.
+     */
+    start(input: {
+        workspaceId: string;
+        workspacePath: string;
+        workspaceTitle: string;
+        commandName: string;
+        command: string;
+        sessionCwd: string;
+        popupAnchor: QuickCommandsSettings['popupAnchor'];
+    }): Promise<{
+        ok: true;
+        runId: string;
+        remoteHost?: string;
+        resolvedCommand: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    /** Read output deltas since the caller's offsets. */
+    poll(runId: string, stdoutFrom: number, stderrFrom: number): RunPollResult | null;
+    /** Terminate the live process tree (idempotent). */
+    kill(runId: string): 'ok' | 'not-found' | 'already-exited';
+    /** List live runs for the workspace (for reattach / run list). */
+    forWorkspace(workspaceId: string): Array<{
+        runId: string;
+        commandName: string;
+        startedAt: number;
+        status: 'running' | 'exited';
+    }>;
+}
+/** Substitute supported placeholders in the command string. */
+export declare function resolvePlaceholders(command: string, vars: {
+    workspace: string;
+    cwd: string;
+    title: string;
+}): string;
+/** Pick the shell executable for the current platform. */
+export declare function shellCmd(): string;
+/** Pick the `-c` inclusive switch for the current platform. */
+export declare function shellFlag(): '-c';
+interface SubprocessServiceLike {
+    spawn(spec: SubprocessSpawnSpec): SubprocessHandle;
+}
+export declare class QuickCommandRunner implements QuickRunner {
+    private readonly subprocess;
+    private readonly resolveRemote?;
+    private readonly runs;
+    private readonly liveByWorkspace;
+    constructor(subprocess: SubprocessServiceLike, resolveRemote?: RemoteBackendResolver | undefined);
+    /** Resolve the remote reference lazily so SSH availability is re-checked per run. */
+    private resolveRemoteBackend;
+    start(input: {
+        workspaceId: string;
+        workspacePath: string;
+        workspaceTitle: string;
+        commandName: string;
+        command: string;
+        sessionCwd: string;
+        popupAnchor: QuickCommandsSettings['popupAnchor'];
+    }): Promise<{
+        ok: true;
+        runId: string;
+        remoteHost?: string;
+        resolvedCommand: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    private startLocal;
+    private startRemote;
+    poll(runId: string, stdoutFrom: number, stderrFrom: number): RunPollResult | null;
+    kill(runId: string): 'ok' | 'not-found' | 'already-exited';
+    forWorkspace(workspaceId: string): Array<{
+        runId: string;
+        commandName: string;
+        startedAt: number;
+        status: 'running' | 'exited';
+    }>;
+    /** Every live run id (terminal and running) for fiber cleanup. */
+    listAll(): string[];
+}
+export {};

package/lib/types/server/settings.d.ts

@@ -0,0 +1,24 @@
+/**
+ * User-facing plugin settings (per-workspace command sets + popup anchor),
+ * persisted through the settings service namespace `quick-commands`.
+ * The DSH settings service requires a lowercase kebab-case namespace
+ * (/^[a-z][a-z0-9-]*$/), so the scoped package name cannot be used here.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { QuickCommandsSettings, QuickCommandEntry, QuickPopupSize } from '../shared/contract.js';
+export declare const QUICK_COMMANDS_NS: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+export declare const QuickCommandsSettingsSchema: z<QuickCommandsSettings>;
+/** Settings service face for the quick-commands engine. */
+export interface QuickCommandsSettingsFace {
+    get(): QuickCommandsSettings;
+    /** Read the command set bound to one workspace id. */
+    commandsOf(workspaceId: string): QuickCommandEntry[];
+    /** Replace the whole command set for one workspace id (instant-save). */
+    setCommands(workspaceId: string, commands: QuickCommandEntry[]): Promise<void>;
+    /** Set the popup anchor preference. */
+    setAnchor(anchor: QuickCommandsSettings['popupAnchor']): Promise<void>;
+    /** Persist the output popup size (drag-resize). */
+    setPopupSize(size: QuickPopupSize): Promise<void>;
+}
+export declare function registerSettings(ctx: Context): QuickCommandsSettingsFace;

package/lib/types/shared/contract.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared wire contracts for @fonlan/dsh-quick-commands.
+ *
+ * Browser-safe: no host-only imports live here. The client bundle imports
+ * these shapes (type-only + runtime constants), so anything that must cross
+ * the fenced JSON API keeps its plain-Object shape here.
+ */
+/** One configured quick command inside a workspace. */
+export interface QuickCommandEntry {
+    /** Human-facing command name (unique within the workspace). */
+    name: string;
+    /** Shell command line, executed through bash -c / pwsh -c. */
+    command: string;
+}
+/** Config slice bound to one workspace (keyed by workspaceId). */
+export interface WorkspaceCommands {
+    /** DSH workspace registry id this command set belongs to. */
+    workspaceId: string;
+    /** Ordered command entries. */
+    commands: QuickCommandEntry[];
+}
+/** Output popup dimensions in CSS pixels (user drag-resize state). */
+export interface QuickPopupSize {
+    width: number;
+    height: number;
+}
+/** Full user-facing plugin settings document (settings namespace value). */
+export interface QuickCommandsSettings {
+    /** Command sets; a workspace may be absent (no commands configured). */
+    workspaces: WorkspaceCommands[];
+    /** Output popup anchor preference: fixed bottom-right or anchored at the button. */
+    popupAnchor: 'corner' | 'button';
+    /** Output popup size; absent until the user drags the resize handle (then per-anchor defaults apply). */
+    popupSize?: QuickPopupSize;
+}
+/** Placeholder substitution values resolved for one execution. */
+export interface QuickRunPlaceholders {
+    /** Workspace root path (also the execution cwd). */
+    workspace: string;
+    /** Session actual cwd (may be a subdirectory of the workspace). */
+    cwd: string;
+    /** Workspace display title. */
+    title: string;
+}
+/** One live run view returned by `run.start`. */
+export interface QuickRunView {
+    runId: string;
+    workspaceId: string;
+    commandName: string;
+    /** Command line after placeholder substitution (display only). */
+    resolvedCommand: string;
+    /** Non-empty when the command executes over SSH on a remote workspace host. */
+    remoteHost?: string;
+    status: 'running' | 'exited';
+    exitCode: number | null;
+    signal: string | null;
+    startedAt: number;
+    /** Total stdout bytes captured so far (offset currency). */
+    stdoutEnd: number;
+    /** Total stderr bytes captured so far (offset currency). */
+    stderrEnd: number;
+    /** stdout tail appended since `stdoutFrom` (whole tail when lossy). */
+    stdoutDelta: string;
+    /** stderr tail appended since `stderrFrom` (whole tail when lossy). */
+    stderrDelta: string;
+    /** True when the in-memory tail lost its head for this stream. */
+    stdoutLossy: boolean;
+    stderrLossy: boolean;
+}
+/** API response envelope (mirrors task-kanban's fenced fetch wrapper). */
+export interface ApiEnvelope<T> {
+    ok: boolean;
+    value?: T;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/** Settings card view: command sets plus the workspace roster for display. */
+export interface QuickRosterEntry {
+    workspaceId: string;
+    path: string;
+    title: string;
+    /** SSH host id when the workspace runs remotely through dsh-ssh (else absent). */
+    remoteHost?: string;
+    commands: QuickCommandEntry[];
+}

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "@fonlan/dsh-quick-commands",
+  "version": "0.1.0",
+  "description": "DSH web plugin: per-workspace quick commands. Configure named shell commands per DSH workspace, run one from the session header with live stdout/stderr in a floating popup.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fonlan/dsh-quick-commands.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fonlan/dsh-quick-commands/issues"
+  },
+  "homepage": "https://github.com/fonlan/dsh-quick-commands",
+  "keywords": [
+    "dsh",
+    "quick-commands",
+    "plugin",
+    "workspace",
+    "commands"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml",
+    "README.md",
+    "README.en.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf lib && tsc -p tsconfig.build.json && tsdown",
+    "build:client": "tsdown",
+    "prepare": "npm run build",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.client.json",
+    "bundle": "tsdown",
+    "watch": "tsdown --watch",
+    "release:patch": "npm version patch && git push && git push --tags",
+    "release:minor": "npm version minor && git push && git push --tags",
+    "release:major": "npm version major && git push && git push --tags"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-primitives",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-settings-plugins"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-workspace": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.1-rc.2",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^5.9.0",
+    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-workspace": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.1-rc.2"
+  },
+  "packageManager": "pnpm@11.21.0"
+}

package/src/client/api.ts

@@ -0,0 +1,76 @@
+/**
+ * Browser client for the plugin's fenced JSON API
+ * (/plugins/@fonlan/dsh-quick-commands/api/<method>). Same-origin fetch with
+ * the task-kanban envelope shape: { ok, value } | { ok:false, error }.
+ */
+import type {
+  ApiEnvelope,
+  QuickCommandsSettings,
+  QuickPopupSize,
+  QuickRosterEntry,
+  QuickRunView,
+} from '../shared/contract'
+
+export class QuickCommandsApiError extends Error {
+  constructor(readonly code: string, message: string) {
+    super(message)
+  }
+}
+
+async function call<T>(method: string, payload: Record<string, unknown> = {}): Promise<T> {
+  let response: Response
+  try {
+    response = await fetch(`/plugins/@fonlan/dsh-quick-commands/api/${method}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+  } catch (error) {
+    throw new QuickCommandsApiError('network', error instanceof Error ? error.message : String(error))
+  }
+  const parsed = (await response.json().catch(() => null)) as ApiEnvelope<T> | null
+  if (!response.ok || parsed === null || parsed.ok !== true || parsed.value === undefined) {
+    throw new QuickCommandsApiError(
+      (parsed?.error?.code as string | undefined) ?? 'http',
+      parsed?.error?.message ?? `HTTP ${response.status}`,
+    )
+  }
+  return parsed.value as T
+}
+
+/** Current session cwd of a session row (SessionSummary carries cwd). */
+export interface SessionRow {
+  id: string
+  cwd?: string
+}
+
+/** One delta read result (mirrors the host RunPollResult). */
+export interface RunPoll {
+  status: 'running' | 'exited'
+  exitCode: number | null
+  signal: string | null
+  stdoutEnd: number
+  stderrEnd: number
+  stdoutDelta: string
+  stderrDelta: string
+  stdoutLossy: boolean
+  stderrLossy: boolean
+}
+
+export const quickApi = {
+  settingsGet: () => call<QuickCommandsSettings>('settings.get'),
+  settingsSetCommands: (workspaceId: string, commands: Array<{ name: string; command: string }>) =>
+    call<QuickCommandsSettings>('settings.setCommands', { workspaceId, commands }),
+  settingsSetAnchor: (anchor: QuickCommandsSettings['popupAnchor']) =>
+    call<QuickCommandsSettings>('settings.setAnchor', { anchor }),
+  settingsSetPopupSize: (size: QuickPopupSize) =>
+    call<QuickCommandsSettings>('settings.setPopupSize', { width: size.width, height: size.height }),
+  workspacesList: () => call<QuickRosterEntry[]>('workspaces.list'),
+  runStart: (workspaceId: string, commandName: string, sessionCwd: string) =>
+    call<QuickRunView>('run.start', { workspaceId, commandName, sessionCwd }),
+  runPoll: (runId: string, stdoutFrom: number, stderrFrom: number) =>
+    call<RunPoll>('run.poll', { runId, stdoutFrom, stderrFrom }),
+  runKill: (runId: string) => call<{ killed: boolean }>('run.kill', { runId }),
+  runList: (workspaceId: string) =>
+    call<Array<{ runId: string; commandName: string; startedAt: number; status: 'running' | 'exited' }>>('run.list', { workspaceId }),
+}