Reorganize packages into a modular hierarchy

Move the 18 flat packages/<name> packages into role-grouped dirs: core/, llm/, bash/, session-persistence/, ui/, support/. Group dirs are pure containers; each package keeps its @deepseek-ai/dsh-* name. Collapse the per-package tsconfig paths maps (base + typecheck) into one @deepseek-ai/dsh-* wildcard with a candidate per group, and derive the publint list from the hierarchy. Update all depth-coupled globs/configs (workspace, tsdown, vitest, eslint, knip, tsconfig includes/refs, per-package tsconfigs, generators, doc-script scopes, type-equiv manifest) and the cross-package/script relative imports in tests. Fix doc-typecheck's workspacePaths() to parse tsconfig JSONC via the TypeScript API instead of a regex comment-strip, which corrupted the new wildcard `/*/` path candidates. WIP: doc cross-links and package/RFC docs still to update.
2026-06-20 22:55:20 +08:00
parent 906705e353
commit d02e9f1bd6
191 changed files with 822 additions and 624 deletions
@@ -0,0 +1,146 @@
+/**
+ * The bash executor seam (`ctx.bash`): an abstract service defining WHAT a
+ * bash backend does — run commands, manage background tasks — without saying
+ * HOW. Implementations subclass {@link BashExecutor} and register themselves
+ * as the `bash` service; `@deepseek-ai/dsh-bash-local` (local subprocesses)
+ * is the first. Future implementations swap in sandboxes, containers, or
+ * remote exec servers without touching the tool schemas that consume them
+ * (`@deepseek-ai/dsh-tool-bash`).
+ *
+ * The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the
+ * surveyed agents: pi hides execution behind a `BashOperations` interface
+ * (local shell / SSH / VM backends), Codex behind an exec-server protocol.
+ *
+ * @module @deepseek-ai/dsh-bash
+ */
+
+import { Context, Service } from 'cordis'
+import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskListener, BashTaskRead } from './types.ts'
+
+export type {
+  BashExecRequest,
+  BashExecSpec,
+  BashRunResult,
+  BashTask,
+  BashTaskListener,
+  BashTaskRead,
+  BashTaskStatus,
+  CollectedOutput,
+} from './types.ts'
+
+declare module 'cordis' {
+  interface Context {
+    bash: BashExecutor
+  }
+}
+
+/**
+ * Abstract bash execution service. Subclass, implement the abstract methods,
+ * and load the subclass as a plugin — it registers as `ctx.bash` (one
+ * implementation per context; loading a second throws, which is cordis'
+ * standard duplicate-service behavior).
+ *
+ * Semantics every implementation must honor:
+ * - {@link run} REJECTS only for infrastructure failures (unusable workdir,
+ *   missing shell, pre-aborted signal). Nonzero exits, timeout kills, and
+ *   abort kills RESOLVE with a descriptive {@link BashRunResult} — reporting
+ *   a failed command is the tool layer's job, not an exception.
+ * - {@link start} returns immediately; no timeout applies to background
+ *   tasks (callers stop them via {@link kill} or the spec's AbortSignal).
+ *   Completion must fire the {@link onTaskDone} listeners exactly once per
+ *   task, and must NOT fire after the service is disposed.
+ * - {@link readOutput} is incremental: consecutive reads never re-deliver
+ *   output. Implementations bound their buffers; reads that lost data flag
+ *   `lossy` and point at full-stream spill files when available.
+ * - Disposal kills every running task and awaits their exit (no orphan
+ *   processes survive `fiber.dispose()`).
+ */
+export abstract class BashExecutor extends Service {
+  private listeners = new Set<BashTaskListener>()
+  private listenersClosed = false
+
+  constructor(ctx: Context) {
+    super(ctx, 'bash')
+    ctx.effect(() => () => {
+      // Close the listener registry before subclass teardown so late task
+      // completions (e.g. from kills issued during dispose) stay silent.
+      this.listenersClosed = true
+      this.listeners.clear()
+    }, 'bash listener teardown')
+  }
+
+  /**
+   * Resolve a caller's {@link BashExecRequest} into a fully-specified
+   * {@link BashExecSpec}, applying this implementation's config defaults and
+   * caps (working directory, default/max timeout). Consumers (tool layer)
+   * call this, then pass the result to {@link run}/{@link start} — keeping
+   * defaulting in the implementation that owns the config while the seam type
+   * stays explicit (no hidden `?? default` inside run/start).
+   */
+  abstract resolve(request: BashExecRequest): BashExecSpec
+
+  /** Run a command in the foreground; resolves when it finishes. */
+  abstract run(spec: BashExecSpec): Promise<BashRunResult>
+
+  /** Start a background task and return its handle immediately. */
+  abstract start(spec: BashExecSpec): BashTask
+
+  /** Look up a background task by id. */
+  abstract get(id: string): BashTask | undefined
+
+  /**
+   * The opaque OWNER token recorded for a background task at {@link start}
+   * (from the {@link BashExecSpec}'s `owner`), or `undefined` for an unknown id
+   * OR a known-but-ownerless task. The executor stores and returns the token
+   * verbatim — it never interprets it; the access POLICY (who may read/kill a
+   * task) lives in the consumer (`@deepseek-ai/dsh-tool-bash`), which compares
+   * `ownerOf(id)` to the caller's token. Collapsing unknown-id and
+   * known-but-unowned into the same `undefined` is fine: the consumer's access
+   * gate treats `undefined` as "open", and a genuinely unknown id then fails
+   * loudly at the subsequent {@link readOutput}/{@link kill} ("unknown task").
+   * Storing ownership in the executor (disposed with ITS fiber) — not in the
+   * tool plugin — is what makes ownership survive a `tool-bash` HMR reload.
+   */
+  abstract ownerOf(id: string): string | undefined
+
+  /** All tracked background tasks (insertion order). */
+  abstract list(): BashTask[]
+
+  /** Read output produced since the previous read. Throws for unknown ids. */
+  abstract readOutput(id: string): BashTaskRead
+
+  /**
+   * Kill a running background task. Returns false when it had already
+   * finished (no-op). Throws for unknown ids.
+   */
+  abstract kill(id: string): boolean
+
+  /**
+   * Register a background-task completion listener (disposed with the
+   * calling fiber). Listeners never fire after this service is disposed.
+   */
+  onTaskDone(listener: BashTaskListener): () => void {
+    const dispose = this.ctx.effect(() => {
+      this.listeners.add(listener)
+      return () => this.listeners.delete(listener)
+    }, 'bash.onTaskDone()')
+    return () => void dispose()
+  }
+
+  /** For implementations: notify listeners that `task` completed. Listener
+   * exceptions are contained (logged) — one bad listener must not reject
+   * `BashTask.done` or starve the listeners after it. */
+  protected notifyTaskDone(task: BashTask): void {
+    if (this.listenersClosed) return
+    for (const listener of this.listeners) {
+      try {
+        listener(task)
+      } catch (error: unknown) {
+        // Listener bugs are reported, never propagated into task.done.
+        console.error('bash onTaskDone listener threw:', error)
+      }
+    }
+  }
+}
+
+export default BashExecutor