dsh-bash-terminal-ts 0.4.0 → 0.4.2

package/lib/index.d.ts

@@ -1,201 +0,0 @@
-import type { BashTerminalContext, ExecAgent, JobsRegistry, JsonSchemaNode, ResolvedPaths, SandboxFacts, SandboxPolicy, ShellId, ToolRunContext } from "./dsh-types.js";
-/** Stable Cordis plugin name. */
-export declare const name = "bash-terminal";
-/** Services required before the tool can register. */
-export declare const inject: string[];
-/** The terminal backends this tool exposes, in catalog order. */
-export declare const SHELLS: readonly ["powershell", "gitbash", "msys2", "wsl"];
-/** The backend used when the caller does not name one. */
-export declare const DEFAULT_SHELL: ShellId;
-/** Settings namespace backing the user-chosen default terminal. */
-export declare const SETTINGS_NAMESPACE = "bash-terminal";
-/** Static shape of the runtime configuration schema. */
-export interface ConfigValues {
-    defaultShell: string;
-    timeoutMs: number;
-    maxTimeoutMs: number;
-    pwshPath: string;
-    gitBashPath: string;
-    msys2Path: string;
-    wslPath: string;
-}
-/** Runtime configuration schema. */
-export declare const Config: import("./dsh.js").SchemasterySchema;
-declare function candidateExists(candidate: string): boolean;
-/** Well-known PowerShell install locations plus PATH entries, newest first. */
-export declare function candidatePwshPaths(env?: NodeJS.ProcessEnv): string[];
-/**
- * Git for Windows locations, then PATH bash.exe entries EXCLUDING the
- * System32 launcher (c:\\windows\\system32\\bash.exe is the WSL
- * forwarder, not a Git Bash shell).
- */
-export declare function candidateGitBashPaths(env?: NodeJS.ProcessEnv): string[];
-/**
- * MSYS2 locations, in preference order: the real `bash.exe` under usr\bin first,
- * then bin\bash.exe, and `msys2.exe` dead last.
- *
- * msys2.exe is NOT a usable backend for piped execution: it is the console-
- * allocating Cygwin launcher, so a spawn with piped stdio returns exit 0 with
- * zero bytes on both stdout and stderr (measured on MSYS2 with bash 5.3.15).
- * Keeping it in the list only as a last-resort fallback preserves the path the
- * config docs reference, but a working bash.exe always wins.
- *
- * MSYS2 uses the same Cygwin/MSYS2 runtime as Git Bash, so it cannot run under
- * the DSH Windows ACL restricted-token sandbox.
- */
-export declare function candidateMsys2Paths(env?: NodeJS.ProcessEnv): string[];
-export declare function defaultWslPath(env?: NodeJS.ProcessEnv): string;
-/** Executable paths, possibly undefined when a backend is not installed. */
-export type { ResolvedPaths };
-type PathConfig = Partial<Pick<ConfigValues, "pwshPath" | "gitBashPath" | "msys2Path" | "wslPath">>;
-export declare function resolveAllPaths(config?: PathConfig, env?: NodeJS.ProcessEnv): ResolvedPaths;
-export declare function buildArgv(shell: string, command: string, paths: ResolvedPaths, distro?: string): Array<string | undefined>;
-/**
- * Merge the DSH_* environment over the process environment. For WSL, only
- * variables explicitly listed in WSLENV cross the boundary, so every DSH_* key is
- * appended to it (WSLENV is a `:` separated VAR[/flag] list).
- *
- * WSLENV usually already exists for reasons unrelated to us -- Windows Terminal
- * exports e.g. `WT_SESSION:WT_PROFILE_ID:` -- so the list is layered rather than
- * rebuilt, or those entries would be silently dropped from every WSL call.
- * Callers that spawn through a seam which replaces the parent environment
- * wholesale (the PTY path) must pass the inherited value explicitly.
- *
- * @param inheritedWslenv - the WSLENV the child would otherwise inherit.
- */
-export declare function buildEnv(shell: string, dshEnv?: Record<string, string>, inheritedWslenv?: string | undefined): Record<string, string | undefined>;
-export interface SpawnResolution {
-    command: string;
-    workdir: string;
-    timeoutMs: number;
-    stdoutMaxBytes: number;
-    stdin?: string;
-}
-declare function spawnSpec(resolved: SpawnResolution, argv: string[], env: Record<string, string | undefined>, signal: AbortSignal): {
-    readonly argv: string[];
-    readonly cwd: string;
-    readonly stdio: {
-        readonly stdin: "ignore" | {
-            data: string;
-        };
-        readonly stdout: {
-            maxBytes: number;
-            spill: {
-                maxBytes: number;
-            };
-        };
-        readonly stderr: {
-            maxBytes: number;
-            spill: {
-                maxBytes: number;
-            };
-        };
-    };
-    readonly graceMs: 3000;
-    readonly signal: AbortSignal;
-    readonly env: Record<string, string | undefined>;
-};
-interface StreamOutput {
-    text: string;
-    truncated: boolean;
-    spillPath?: string;
-}
-export interface ForegroundOutcome {
-    exitCode: number | null;
-    signal: string | null;
-    timedOut: boolean;
-    aborted: boolean;
-    timeoutMs: number;
-    stdout: StreamOutput;
-    stderr: StreamOutput;
-}
-declare function runForeground(ctx: BashTerminalContext, argv: string[], resolved: SpawnResolution, env: Record<string, string | undefined>, signal: AbortSignal, timeoutMs: number): Promise<ForegroundOutcome>;
-export interface ProcessRead {
-    delta: string;
-    lossy: boolean;
-    stdoutSpillPath?: string;
-    stderrSpillPath?: string;
-}
-interface BackgroundProc {
-    status: "running" | "killed" | "completed";
-    exitCode: number | null;
-    signal: string | null;
-    done: Promise<void>;
-    readOutput(): ProcessRead;
-    kill(): boolean;
-}
-declare function startBackground(ctx: BashTerminalContext, argv: string[], resolved: SpawnResolution, env: Record<string, string | undefined>, signal: AbortSignal): BackgroundProc;
-declare function processOutcome(proc: BackgroundProc): {
-    status: string;
-    detail: string;
-};
-export interface RenderedResult {
-    stdout: StreamOutput;
-    stderr: StreamOutput;
-    exitCode: number | null;
-    signal: string | null;
-    timedOut: boolean;
-    timeoutMs: number;
-}
-export declare function renderResult(result: RenderedResult): string;
-/** Model-facing lead sentence for each backend. The user's default terminal is
- * stated up front so the model never has to guess which syntax applies. */
-export declare const SHELL_DESCRIPTIONS: Record<ShellId, string>;
-/**
- * Render the model-facing tool description for one backend. The backend is
- * whatever the user chose in Settings -> General -> Default terminal; the
- * description names it explicitly so the model writes the right syntax.
- * @param backgroundEnabled - advertise `run_in_background` controls.
- * @param shell - active backend; unknown values fall back to the default.
- */
-export declare function toolDescription(backgroundEnabled: boolean, shell?: string): string;
-/** The shell tool's arguments after runtime validation. */
-export type ValidatedShellArgs = {
-    command: string;
-    description: string;
-    timeoutMs?: number;
-    distro?: string;
-    sandbox_permissions?: string;
-    justification?: string;
-    workdir?: string;
-    run_in_background?: boolean;
-    stdin?: string;
-};
-export declare function validateArgs(args: Record<string, unknown>): ValidatedShellArgs;
-declare function resolveWorkdir(modelWorkdir: string | undefined, exec: ToolRunContext): string | undefined;
-export interface ForegroundResult {
-    kind: "foreground";
-    exitCode: number | null;
-    signal: string | null;
-    timedOut: boolean;
-    aborted: boolean;
-    timeoutMs: number;
-    stdout: StreamOutput;
-    stderr: StreamOutput;
-    sandbox?: SandboxFacts;
-}
-export interface BackgroundResult {
-    kind: "background";
-    jobId: string;
-}
-export type ShellToolResult = ForegroundResult | BackgroundResult;
-export declare function apply(ctx: BashTerminalContext, config?: Partial<ConfigValues>): void;
-export declare const internals: {
-    candidateExists: typeof candidateExists;
-    resolveAllPaths: typeof resolveAllPaths;
-    resolveWorkdir: typeof resolveWorkdir;
-    renderResult: typeof renderResult;
-    processOutcome: typeof processOutcome;
-    startBackground: typeof startBackground;
-    runForeground: typeof runForeground;
-    spawnSpec: typeof spawnSpec;
-    buildEnv: typeof buildEnv;
-    buildArgv: typeof buildArgv;
-    validateArgs: typeof validateArgs;
-    toolDescription: typeof toolDescription;
-    SHELL_DESCRIPTIONS: Record<ShellId, string>;
-    DEFAULT_TIMEOUT_MS: number;
-    MAX_TIMEOUT_MS: number;
-    DEFAULT_MAX_OUTPUT_BYTES: number;
-};
-export type { ExecAgent, JobsRegistry, JsonSchemaNode, SandboxFacts, SandboxPolicy, ShellId, ToolRunContext };

package/lib/terminal.d.ts

@@ -1,87 +0,0 @@
-import type { BashTerminalContext, ResolvedPaths, TerminalHandle } from "./dsh-types.js";
-declare const TERMINAL_SIGNALS: readonly ["SIGINT", "SIGTERM", "SIGKILL", "SIGTSTP", "SIGHUP"];
-export type TerminalSignal = (typeof TERMINAL_SIGNALS)[number];
-interface TerminalBufferRead {
-    delta: string;
-    nextOffset: number;
-}
-interface TerminalBuffer {
-    append(chunk: string): void;
-    readFrom(offset: number): TerminalBufferRead;
-    snapshot(): string;
-}
-/** Interactive-shell argv (no -c: the terminal itself is the session). */
-export declare function terminalArgv(shell: string, paths: ResolvedPaths, distro?: string): Array<string | undefined>;
-interface TerminalSession {
-    id: string;
-    handle: TerminalHandle;
-    buffer: TerminalBuffer;
-    shell: string;
-    distro?: string;
-    closed: boolean;
-}
-export interface TerminalOpenOptions {
-    argv: string[];
-    shell: string;
-    cwd: string;
-    env: Record<string, string | undefined>;
-    rows: number;
-    cols: number;
-    distro?: string;
-    initial?: string;
-}
-export interface TerminalRegistry {
-    open(options: TerminalOpenOptions): Promise<TerminalSession>;
-    get(id: string): TerminalSession;
-    send(id: string, input: string): Promise<TerminalBufferRead>;
-    read(id: string): TerminalBufferRead;
-    signal(id: string, sig: string): Promise<TerminalBufferRead>;
-    close(id: string): Promise<boolean>;
-}
-/**
- * Terminal-session registry owned by the plugin fiber: opens PTYs through
- * the official seam, forwards output into a capped buffer, and tears every
- * session down on plugin disposal.
- */
-export declare function createTerminalRegistry(ctx: BashTerminalContext): TerminalRegistry;
-/** The terminal tool's arguments after runtime validation (discriminated by action). */
-export type ValidatedTerminalArgs = {
-    action: "open";
-    sessionId?: string;
-    command?: string;
-    distro?: string;
-    workdir?: string;
-} | {
-    action: "send";
-    sessionId: string;
-    input: string;
-} | {
-    action: "read";
-    sessionId: string;
-} | {
-    action: "signal";
-    sessionId: string;
-    signal: TerminalSignal;
-} | {
-    action: "close";
-    sessionId: string;
-};
-export declare function validateArgs(args: Record<string, unknown>): asserts args is ValidatedTerminalArgs;
-export interface TerminalOpenResult {
-    kind: "open";
-    sessionId: string;
-    pid: number;
-    shell: string;
-    output: string;
-}
-export interface TerminalSessionResult {
-    kind: "session";
-    output: string;
-}
-export interface TerminalClosedResult {
-    kind: "closed";
-    sessionId: string;
-}
-export type TerminalToolResult = TerminalOpenResult | TerminalSessionResult | TerminalClosedResult;
-export declare function terminalTool(ctx: BashTerminalContext, registry: TerminalRegistry, paths: ResolvedPaths, defaultShell: () => string): import("./dsh-types.js").ToolDefinition;
-export {};

package/src/client.tsx

@@ -1,161 +0,0 @@
-// dsh-bash-terminal-ts client plugin: a "Default terminal" preference row in the
-// Web UI General settings. The user picks powershell / gitbash / msys2 / wsl;
-// the host shell tool obeys that choice (the model cannot change it).
-//
-// The option list below must stay in lockstep with SHELLS in ./index.ts: every
-// id gets an <option> here and a `shell.<id>` entry in both dictionaries. The
-// shipped bundle cannot import the host module (it pulls node: builtins), so
-// test/client.ts asserts the bundle covers every host shell id instead.
-
-import { defineStore } from "@deepseek-ai/dsh-client-store";
-
-const SETTINGS_NS = "settings.bash-terminal";
-const SETTINGS_NAMESPACE = "bash-terminal";
-
-const zh: Record<string, string> = {
-  "shell.title": "默认终端",
-  "shell.description": "shell 工具执行命令时使用的终端（由你决定，AI 无法更改）",
-  "shell.powershell": "PowerShell",
-  "shell.gitbash": "Git Bash",
-  "shell.msys2": "MSYS2",
-  "shell.wsl": "WSL"
-};
-const en: Record<string, string> = {
-  "shell.title": "Default terminal",
-  "shell.description": "Terminal used by the shell tool (you control this; the AI cannot change it)",
-  "shell.powershell": "PowerShell",
-  "shell.gitbash": "Git Bash",
-  "shell.msys2": "MSYS2",
-  "shell.wsl": "WSL"
-};
-
-export const inject = ["slots", "locale", "settingsScope"];
-
-/** Row state snapshot served through the settings store. */
-interface RowState {
-  shell: string;
-  revision: number;
-  writable: boolean;
-}
-
-interface ShellPreferenceRowProps {
-  t: (key: string) => string;
-  useStore: <S>(selector: (state: RowState) => S) => S;
-  setShell: (id: string) => void;
-}
-
-function ShellPreferenceRow({ t, useStore, setShell }: ShellPreferenceRowProps) {
-  const shell = useStore((s) => s.shell);
-  const writable = useStore((s) => s.writable);
-  return (
-    <div
-      style={{
-        display: "flex",
-        alignItems: "center",
-        justifyContent: "space-between",
-        gap: 16,
-        padding: "12px 0"
-      }}
-    >
-      <div style={{ minWidth: 0 }}>
-        <div style={{ fontSize: 14, fontWeight: 500, lineHeight: "22px", color: "var(--dsw-alias-label-primary, inherit)" }}>
-          {t("shell.title")}
-        </div>
-        <div style={{ fontSize: 12, lineHeight: "18px", opacity: 0.65 }}>{t("shell.description")}</div>
-      </div>
-      <select
-        value={shell}
-        disabled={!writable}
-        onChange={(e) => setShell(e.target.value)}
-        style={{
-          fontSize: 14,
-          padding: "6px 10px",
-          borderRadius: 8,
-          border: "1px solid var(--dsw-alias-line-strong, #ccc)",
-          background: "var(--dsw-alias-bg-layer-2, #fff)",
-          color: "var(--dsw-alias-label-primary, inherit)",
-          outline: "none",
-          cursor: writable ? "pointer" : "not-allowed",
-          maxWidth: 180
-        }}
-      >
-        <option value="powershell">{t("shell.powershell")}</option>
-        <option value="gitbash">{t("shell.gitbash")}</option>
-        <option value="msys2">{t("shell.msys2")}</option>
-        <option value="wsl">{t("shell.wsl")}</option>
-      </select>
-    </div>
-  );
-}
-
-interface SettingsSnapshot {
-  status: string;
-  value?: { defaultShell?: string };
-  revision: number;
-  writable: boolean;
-}
-
-interface SettingsScopeBinding {
-  getSnapshot(): SettingsSnapshot;
-  subscribe(fn: () => void): () => void;
-  set(field: string, value: string): void;
-  unset(): void;
-}
-
-interface ClientContext {
-  effect(fn: () => unknown, name?: string): unknown;
-  locale: { register(ns: string, dicts: Record<string, Record<string, string>>): unknown };
-  settingsScope: { bind(options: { namespace: string }): SettingsScopeBinding };
-  slots: {
-    inject(slot: string, fn: () => unknown, name?: string): void;
-    register(options: Record<string, unknown>, Component: unknown): Record<string, unknown>;
-  };
-}
-
-interface RowStoreActions {
-  sync(shell?: string, revision?: number, writable?: boolean): void;
-}
-
-export function apply(ctx: ClientContext): void {
-  ctx.effect(() => ctx.locale.register(SETTINGS_NS, { zh, en }), "bash-terminal: settings dictionaries");
-  const scope = ctx.settingsScope.bind({ namespace: SETTINGS_NAMESPACE });
-  const store = defineStore<RowState, { sync: (draft: RowState, shell?: string, revision?: number, writable?: boolean) => void }>({
-    init: (): RowState => ({ shell: "powershell", revision: -1, writable: false }),
-    actions: {
-      sync: (d, shell, revision, writable) => {
-        if (revision !== undefined && revision <= d.revision) return;
-        if (shell !== undefined) d.shell = shell;
-        if (revision !== undefined) d.revision = revision;
-        if (writable !== undefined) d.writable = writable;
-      }
-    }
-  });
-  // defineStore() yields a { spec, create } factory; slots.register creates
-  // the live store, so we bind the actions in the inject callback and push
-  // the initial snapshot there too (mirrors the theme row pattern).
-  let bound: RowStoreActions | undefined;
-  const push = (snap: SettingsSnapshot): void => {
-    bound?.sync(snap.value?.defaultShell, snap.revision, snap.writable);
-  };
-  ctx.slots.inject(
-    "settings.general.item",
-    () =>
-      ctx.slots.register(
-        {
-          name: "settings.general.item",
-          id: "bash-terminal-shell",
-          order: 20,
-          store,
-          locale: SETTINGS_NS,
-          inject: (actions: unknown) => {
-            bound = actions as RowStoreActions;
-            push(scope.getSnapshot());
-            return { setShell: (value: string) => void scope.set("defaultShell", value) };
-          }
-        },
-        ShellPreferenceRow
-      ),
-    "bash-terminal: settings row"
-  );
-  ctx.effect(() => scope.subscribe(() => push(scope.getSnapshot())), "bash-terminal: settings watch");
-}