@achasoft/dsh-advanced-sidebar 0.1.0

package/types/host/index.d.ts

@@ -0,0 +1,210 @@
+/**
+ * The advanced-sidebar plugin's node half: one Remote namespace serving every operation the browser
+ * structurally cannot perform, plus the `advanced-sidebar` settings section both halves address.
+ *
+ * What is here and what is not follows one rule — the Host owns only what a browser cannot do. The
+ * session list, the workspace list, the background-task list, archiving, and directory listing all
+ * already reach the Web Client through capabilities it holds, so this endpoint adds no second copy
+ * of any of them. It answers for git (a subprocess), panel terminals (a pseudo-terminal), file
+ * previews (a filesystem read), external applications (a launch), stopping a background task
+ * (an owner-fenced registry), and deletion (a durable artifact).
+ *
+ * Nothing here is model-facing: no tool, no prompt section, no session event. Every result is a
+ * discriminated value rather than a throw, because the RPC gateway erases a business exception's
+ * classification and each panel's next move depends on which class it was.
+ * @module @achasoft/dsh-advanced-sidebar/host
+ */
+import { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { AdvancedSidebarSettings, AdvancedSidebarView, DeleteSessionRequest, DeleteSessionResult, GitCommitMessageRequest, GitCommitMessageResult, GitCommitRequest, GitCommitResult, GitDiffRequest, GitDiffResult, GitPushRequest, GitPushResult, GitStageRequest, GitStageResult, GitStatusRequest, GitStatusResult, ListEntriesRequest, ListEntriesResult, OpenInRequest, OpenInResult, PreviewListRequest, PreviewListResult, PreviewLogsRequest, PreviewLogsResult, PreviewStartRequest, PreviewStartResult, PreviewStopRequest, PreviewStopResult, ReadFileRequest, ReadFileResult, TaskKillRequest, TaskKillResult, TaskOutputRequest, TaskOutputResult, TerminalAckResult, TerminalCloseRequest, TerminalOpenRequest, TerminalOpenResult, TerminalReadRequest, TerminalReadResult, TerminalSignalRequest, TerminalWriteRequest } from './types.ts';
+export type * from './types.ts';
+export { REVEAL_TARGET_ID } from './open-in.ts';
+/**
+ * The settings namespace both halves address; the browser card joins the plugin tab on it.
+ *
+ * Kebab-case, unlike the Remote namespace below: a settings namespace is a kebab-case grammar the
+ * Host validates, while a Remote namespace is read as `ctx.remote.advancedSidebar.…` and so must be
+ * an identifier.
+ */
+export declare const ADVANCED_SIDEBAR_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+/** Deployment configuration for the advanced sidebar; the `advanced-sidebar` section's own shape. */
+export type Config = AdvancedSidebarSettings;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        advancedSidebar: AdvancedSidebarService;
+    }
+}
+/** Host endpoint for the sidebar's advanced operations, and owner of the settings section. */
+export declare class AdvancedSidebarService extends TypertRemoteService {
+    /** Loader validation for every deployment-varying choice this plugin makes. */
+    static Config: z<Config>;
+    private source;
+    private readonly git;
+    private readonly terminals;
+    private readonly launcher;
+    private readonly files;
+    private readonly tasks;
+    private readonly deleter;
+    private readonly preview;
+    /**
+     * @param ctx - Host context; every capability this service uses is resolved optionally, so a
+     * deployment missing one still serves a view that explains which panel is dark and why.
+     * @param config - the composition-layer preferences, used as the section's base layer.
+     */
+    constructor(ctx: Context, config: Config);
+    /**
+     * Describe which operations this Host can serve, so the menu can disable an entry with a reason
+     * instead of offering one that fails when it is pressed.
+     * @param signal - gateway-supplied cancellation for the executable probes.
+     * @returns the capability view.
+     */
+    describe(signal: AbortSignal): Promise<AdvancedSidebarView>;
+    /**
+     * Read one workspace's git status.
+     * @param request - the workspace directory.
+     * @param signal - gateway-supplied cancellation for the caller's abandoned request.
+     * @returns the reading, or a classified failure.
+     */
+    gitStatus(request: GitStatusRequest, signal: AbortSignal): Promise<GitStatusResult>;
+    /**
+     * Read one path's patch.
+     * @param request - the path and which index to compare.
+     * @param signal - gateway-supplied cancellation for the caller's abandoned request.
+     * @returns the patch, or a classified failure.
+     */
+    gitDiff(request: GitDiffRequest, signal: AbortSignal): Promise<GitDiffResult>;
+    /**
+     * Stage paths into the index.
+     * @param request - the workspace and the repository-relative paths.
+     * @param signal - gateway-supplied cancellation for the caller's abandoned request.
+     * @returns the reading after the write, or a classified failure.
+     */
+    gitStage(request: GitStageRequest, signal: AbortSignal): Promise<GitStageResult>;
+    /**
+     * Take paths back out of the index, leaving the working tree alone.
+     * @param request - the workspace and the repository-relative paths.
+     * @param signal - gateway-supplied cancellation for the caller's abandoned request.
+     * @returns the reading after the write, or a classified failure.
+     */
+    gitUnstage(request: GitStageRequest, signal: AbortSignal): Promise<GitStageResult>;
+    /**
+     * Record the staged changes.
+     * @param request - the workspace, the message, and whether to amend.
+     * @param signal - gateway-supplied cancellation; hooks run under `gitCommitTimeoutMs`.
+     * @returns the new commit and the reading after it, or a classified failure.
+     */
+    gitCommit(request: GitCommitRequest, signal: AbortSignal): Promise<GitCommitResult>;
+    /**
+     * Send the current branch's commits to its remote.
+     * @param request - the workspace, and whether an unpublished branch may be published.
+     * @param signal - gateway-supplied cancellation; the network wait runs under `gitPushTimeoutMs`.
+     * @returns the push and the reading after it, or a classified failure.
+     */
+    gitPush(request: GitPushRequest, signal: AbortSignal): Promise<GitPushResult>;
+    /**
+     * Ask the deployment's own model to write a commit message for what is staged.
+     * @param request - the workspace, and whether the message is for an amend.
+     * @param signal - gateway-supplied cancellation for the readings and the model call.
+     * @returns the drafted message, or a classified failure.
+     */
+    gitCommitMessage(request: GitCommitMessageRequest, signal: AbortSignal): Promise<GitCommitMessageResult>;
+    /**
+     * Allocate a panel terminal.
+     * @param request - the workspace directory and the panel's measured geometry.
+     * @param signal - gateway-supplied cancellation of the allocation.
+     * @returns the handle, or a classified failure.
+     */
+    terminalOpen(request: TerminalOpenRequest, signal: AbortSignal): Promise<TerminalOpenResult>;
+    /**
+     * Read a panel terminal's output from a caller-owned offset.
+     * @param request - the handle and the offset already rendered.
+     * @returns the delta and the process state, or a classified failure.
+     */
+    terminalRead(request: TerminalReadRequest): Promise<TerminalReadResult>;
+    /**
+     * Send keystrokes to a panel terminal.
+     * @param request - the handle and the text to deliver verbatim.
+     * @returns settlement, or a classified failure.
+     */
+    terminalWrite(request: TerminalWriteRequest): Promise<TerminalAckResult>;
+    /**
+     * Deliver a signal to a panel terminal's foreground process group.
+     * @param request - the handle and the signal.
+     * @returns settlement, or a classified failure.
+     */
+    terminalSignal(request: TerminalSignalRequest): Promise<TerminalAckResult>;
+    /**
+     * Close a panel terminal.
+     * @param request - the handle.
+     * @returns settlement, or a classified failure.
+     */
+    terminalClose(request: TerminalCloseRequest): Promise<TerminalAckResult>;
+    /**
+     * List one directory level for the Files panel.
+     * @param request - the directory and the workspace it must stay inside.
+     * @param signal - gateway-supplied cancellation for the caller's abandoned request.
+     * @returns the level, or a classified failure.
+     */
+    listEntries(request: ListEntriesRequest, signal: AbortSignal): Promise<ListEntriesResult>;
+    /**
+     * List one workspace's preview launch configurations, each with its current state.
+     * @param request - the workspace to read.
+     * @param signal - gateway-supplied cancellation for the caller's abandoned request.
+     * @returns the list, or a classified failure.
+     */
+    previewList(request: PreviewListRequest, signal: AbortSignal): Promise<PreviewListResult>;
+    /**
+     * Start one preview configuration.
+     * @param request - the workspace and the configuration name.
+     * @param signal - gateway-supplied cancellation of the start.
+     * @returns the started row, or a classified failure.
+     */
+    previewStart(request: PreviewStartRequest, signal: AbortSignal): Promise<PreviewStartResult>;
+    /**
+     * Stop one running preview server.
+     * @param request - the handle.
+     * @returns settlement, or a classified failure.
+     */
+    previewStop(request: PreviewStopRequest): Promise<PreviewStopResult>;
+    /**
+     * Read one preview server's output from a caller-owned offset, with its state at read time.
+     * @param request - the handle and the offset already rendered.
+     * @returns the delta and the state, or a classified failure.
+     */
+    previewLogs(request: PreviewLogsRequest): Promise<PreviewLogsResult>;
+    /**
+     * Read one file for the Files panel preview.
+     * @param request - the file and the workspace it must stay inside.
+     * @param signal - gateway-supplied cancellation for the caller's abandoned request.
+     * @returns the preview, or a classified failure.
+     */
+    readFile(request: ReadFileRequest, signal: AbortSignal): Promise<ReadFileResult>;
+    /**
+     * Hand one path to an external application or to the operating system's file manager.
+     * @param request - the target and the path.
+     * @param signal - gateway-supplied cancellation for the launch.
+     * @returns settlement, or a classified failure.
+     */
+    openIn(request: OpenInRequest, signal: AbortSignal): Promise<OpenInResult>;
+    /**
+     * Stop one live background task.
+     * @param request - the owning session and the task id.
+     * @returns what the registry did, or a classified failure.
+     */
+    taskKill(request: TaskKillRequest): Promise<TaskKillResult>;
+    /**
+     * Read one settled background task's output.
+     * @param request - the owning session and the task id.
+     * @returns the accumulated output, or a classified failure.
+     */
+    taskOutput(request: TaskOutputRequest): Promise<TaskOutputResult>;
+    /**
+     * Delete one session: archive it, and remove its durable artifact when the mode and Host allow.
+     * @param request - the session to delete.
+     * @param signal - gateway-supplied cancellation for the persistence listing.
+     * @returns what was actually done, or a classified failure.
+     */
+    deleteSession(request: DeleteSessionRequest, signal: AbortSignal): Promise<DeleteSessionResult>;
+}
+export default AdvancedSidebarService;

package/types/host/open-in.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The Open in submenu's Host half: reveal a path in the operating system's file manager, and launch
+ * a configured external application on it.
+ *
+ * The harness's own `host.openPath` hands a path to its default application, which is the right
+ * verb for a directory and the wrong one for a file — a person asking to see a file in Finder does
+ * not want it opened in whatever edits `.ts`. This module keeps that distinction: a directory is
+ * opened, a file is selected in its folder.
+ * @module @achasoft/dsh-advanced-sidebar/host/open-in
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AdvancedSidebarSettings, OpenInRequest, OpenInResult, OpenInTargetView } from './types.ts';
+/** Id of the built-in file-manager target; no configured editor may claim it. */
+export declare const REVEAL_TARGET_ID = "reveal";
+/**
+ * Launches external applications for the Open in submenu. One instance serves every request and
+ * caches each target's resolved executable.
+ */
+export declare class OpenInLauncher {
+    private readonly ctx;
+    private readonly source;
+    private readonly resolved;
+    /**
+     * @param ctx - Host context carrying the subprocess and filesystem capabilities.
+     * @param source - reads the current settings section; called per request so an edited target list
+     * reaches the next menu with no registration to rebuild.
+     */
+    constructor(ctx: Context, source: () => AdvancedSidebarSettings);
+    /**
+     * List every target in menu order with its availability.
+     *
+     * Unavailable targets are listed rather than hidden: a person who configured an editor and does
+     * not see it cannot tell a typo in `command` from a menu that simply has no such feature.
+     * @param signal - cancellation for the executable lookups.
+     * @returns the targets, file manager first.
+     */
+    describe(signal?: AbortSignal): Promise<readonly OpenInTargetView[]>;
+    /**
+     * Hand one path to a target.
+     * @param request - which target, and which absolute path.
+     * @param signal - cancellation for the launch.
+     * @returns settlement, or a classified failure.
+     */
+    open(request: OpenInRequest, signal?: AbortSignal): Promise<OpenInResult>;
+    /**
+     * Show a path in the operating system's file manager.
+     * @param target - the canonical path.
+     * @param directory - whether the path is a directory (opened) or a file (selected).
+     * @param signal - cancellation for the launch.
+     * @returns settlement, or a classified failure.
+     */
+    private reveal;
+    /**
+     * The platform's file-manager invocation.
+     * @param platform - the Host platform.
+     * @param target - the canonical path; omitted while only the executable name is needed.
+     * @param directory - whether the path is a directory.
+     * @returns the argv and whether a non-zero exit is normal for it.
+     */
+    private revealCommand;
+    /**
+     * Run one launcher and classify its outcome.
+     * @param argv - resolved executable and arguments.
+     * @param signal - cancellation for the launch.
+     * @param tolerateExit - accept a non-zero exit as success (Windows Explorer).
+     * @returns settlement, or a classified failure.
+     */
+    private launch;
+    /**
+     * Resolve a file path that is not a directory.
+     * @param path - the browser-supplied path.
+     * @param signal - cancellation for the resolution.
+     * @returns the canonical path, or undefined when nothing is there.
+     */
+    private resolveFile;
+    /**
+     * Whether one command resolves, without reporting why it does not.
+     * @param command - executable name or path.
+     * @param signal - cancellation for the lookup.
+     * @returns true when the command resolves.
+     */
+    private available;
+    /**
+     * Resolve one command once and remember the answer, negative answers included.
+     * @param command - executable name or path.
+     * @param signal - cancellation for the lookup.
+     * @returns the executable path, or undefined when the command is absent.
+     * @throws {CommandUnavailableError} when no subprocess capability is mounted.
+     */
+    private locate;
+    /** Drop every cached lookup, so an edited target list or a newly installed editor is re-probed. */
+    forget(): void;
+}

package/types/host/paths.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Path resolution and containment for every endpoint that takes a path from the browser.
+ *
+ * A browser-supplied path is untrusted input at a process boundary, so each one is resolved through
+ * `ctx.fs` and proved to sit inside the workspace it claims to belong to before any command, read,
+ * or launch sees it. `..` and symlinks are handled by the filesystem's own canonicalization rather
+ * than by string arithmetic here.
+ * @module @achasoft/dsh-advanced-sidebar/host/paths
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { FsTarget } from '@deepseek-ai/dsh-fs';
+/** A resolved, contained path plus the canonical spelling a subprocess can open. */
+export interface ResolvedPath {
+    /** The canonical target. */
+    readonly target: FsTarget;
+    /** Absolute path in the filesystem backend's execution world. */
+    readonly processPath: string;
+}
+/** Why a path could not be accepted. */
+export type PathRejection = 
+/** No filesystem capability is mounted. */
+{
+    readonly code: 'no-filesystem';
+    readonly message: string;
+}
+/** The path does not exist, or escaped the workspace it was asked about. */
+ | {
+    readonly code: 'path-denied';
+    readonly message: string;
+};
+/** Either a usable path or the reason it was refused. */
+export type PathOutcome = {
+    readonly ok: true;
+    readonly value: ResolvedPath;
+} | {
+    readonly ok: false;
+    readonly rejection: PathRejection;
+};
+/**
+ * Resolve one absolute directory as a workspace root.
+ * @param ctx - Host context carrying the optional filesystem capability.
+ * @param path - absolute directory path supplied by the browser.
+ * @param signal - cancellation for the backend round-trip.
+ * @returns the canonical directory, or the reason it was refused.
+ */
+export declare function resolveWorkspace(ctx: Context, path: string, signal?: AbortSignal): Promise<PathOutcome>;
+/**
+ * Resolve one path and prove it sits inside an already-resolved workspace.
+ * @param ctx - Host context carrying the optional filesystem capability.
+ * @param workspace - the canonical workspace directory the path must stay within.
+ * @param path - absolute path supplied by the browser.
+ * @param signal - cancellation for the backend round-trip.
+ * @returns the canonical path, or the reason it was refused.
+ */
+export declare function resolveInside(ctx: Context, workspace: ResolvedPath, path: string, signal?: AbortSignal): Promise<PathOutcome>;

package/types/host/porcelain.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Pure parser for `git status --porcelain=v2 --branch -z`.
+ *
+ * Kept apart from the command runner so the format — which is the only part of the git integration
+ * with edge cases worth testing (renames carry two paths, `-z` terminates every line including the
+ * headers, and a path may contain any byte but NUL) — is exercised without a subprocess.
+ * @module @achasoft/dsh-advanced-sidebar/host/porcelain
+ */
+import type { GitFileChange } from './types.ts';
+/** Branch facts from the `# branch.*` headers, all optional because an unborn branch has none. */
+export interface PorcelainBranch {
+    /** Value of `# branch.head`, unless it is the literal `(detached)`. */
+    branch?: string;
+    /** Value of `# branch.upstream`. */
+    upstream?: string;
+    /** First figure of `# branch.ab`. */
+    ahead: number;
+    /** Second figure of `# branch.ab`, as a positive count. */
+    behind: number;
+    /** True when `# branch.head` is `(detached)`. */
+    detached: boolean;
+}
+/** Everything one status reading yields, before the caller groups or truncates it. */
+export interface PorcelainStatus {
+    /** Branch position. */
+    branch: PorcelainBranch;
+    /** Every changed path in git's own order. */
+    changes: GitFileChange[];
+}
+/**
+ * Parse one complete `--porcelain=v2 --branch -z` payload.
+ *
+ * Unknown record types are skipped rather than rejected: git adds record kinds over time, and a
+ * reading that lists every change it understood is more useful than one that refuses the whole
+ * repository because a future git emitted a line this parser has not met.
+ * @param payload - git's stdout, verbatim.
+ * @returns the branch facts and every parsed change.
+ */
+export declare function parsePorcelainV2(payload: string): PorcelainStatus;
+/**
+ * Whether a change belongs in the staged group — its index state differs from HEAD.
+ * @param change - one parsed change.
+ * @returns true when a commit right now would record something for this path.
+ */
+export declare function isStaged(change: GitFileChange): boolean;
+/**
+ * Whether a change belongs in the unstaged group — its working tree differs from the index.
+ * @param change - one parsed change.
+ * @returns true when the path has edits no commit would record yet.
+ */
+export declare function isUnstaged(change: GitFileChange): boolean;

package/types/host/preview.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Preview servers: the Host half of the Preview panel.
+ *
+ * A person looking at a running application needs three things the browser cannot do for itself —
+ * start the process, know when its port is actually accepting, and read what it printed. This
+ * module owns all three, plus the merge of where configurations come from.
+ *
+ * Configurations are read from the workspace's own `.claude/launch.json` first and from the
+ * `previews` settings rows second, and a name declared in both is taken from the file. That order
+ * is the point: a repository already carrying that file gets a working panel with nothing else to
+ * write, and it stays the authority on how to run itself when a deployment also configures a row.
+ *
+ * Readiness is a TCP connect to the configured port, retried until it accepts or the deadline
+ * passes. An HTTP probe would need a path, a method, and an opinion about which status codes count;
+ * a listening socket is the one fact every dev server agrees on.
+ * @module @achasoft/dsh-advanced-sidebar/host/preview
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AdvancedSidebarSettings, CapabilityState, PreviewLaunch, PreviewListRequest, PreviewListResult, PreviewLogsRequest, PreviewLogsResult, PreviewOrigin, PreviewStartRequest, PreviewStartResult, PreviewStopRequest, PreviewStopResult } from './types.ts';
+/** One configuration plus where it was read from. */
+interface Resolved {
+    /** The configuration. */
+    readonly launch: PreviewLaunch;
+    /** Which file it came from. */
+    readonly origin: PreviewOrigin;
+}
+/**
+ * Read one launch file's configurations.
+ *
+ * A malformed file is reported rather than thrown: the panel still lists the settings rows and says
+ * why the file was ignored, which is more useful than a Preview entry that refuses to open.
+ * @param text - the file's contents.
+ * @returns the configurations, or the reason the file was ignored.
+ */
+export declare function parseLaunchFile(text: string): {
+    launches: PreviewLaunch[];
+} | {
+    error: string;
+};
+/**
+ * Merge a workspace's launch file with the settings rows.
+ *
+ * The file wins a name collision: a repository stating how to run itself outranks a deployment-wide
+ * default that happens to use the same name.
+ * @param fromFile - configurations read from `.claude/launch.json`.
+ * @param fromSettings - configurations from the `previews` settings rows.
+ * @returns the merged list, file rows first.
+ */
+export declare function mergeLaunches(fromFile: readonly PreviewLaunch[], fromSettings: readonly PreviewLaunch[]): Resolved[];
+/**
+ * Owns every preview server in the process. One instance is created by the service and disposed
+ * with it, which is what guarantees no dev server outlives the plugin.
+ */
+export declare class PreviewServers {
+    private readonly ctx;
+    private readonly source;
+    private readonly records;
+    /**
+     * Configurations with a start already in flight, keyed `<workspace>\u0000<name>`.
+     *
+     * `start()` awaits a file read, a path resolution, and an executable lookup before it registers
+     * anything, so two starts of one row would both find no predecessor and both spawn — leaving a
+     * dev server on the port that no `serverId` any panel holds can ever stop.
+     */
+    private readonly starting;
+    private closing;
+    /**
+     * @param ctx - Host context carrying the subprocess and filesystem capabilities.
+     * @param source - reads the current settings section; called per request.
+     */
+    constructor(ctx: Context, source: () => AdvancedSidebarSettings);
+    /**
+     * Report whether a preview server can be started on this Host.
+     * @returns availability plus how many servers are already running.
+     */
+    describe(): CapabilityState & {
+        running: number;
+    };
+    /**
+     * List one workspace's configurations, each with its current state.
+     * @param request - the workspace to read.
+     * @param signal - cancellation for the file read.
+     * @returns the list, or a classified failure.
+     */
+    list(request: PreviewListRequest, signal?: AbortSignal): Promise<PreviewListResult>;
+    /**
+     * Start one configuration.
+     * @param request - the workspace and the configuration name.
+     * @param signal - cancellation of the start itself; a started server owns its later lifetime.
+     * @returns the started row, or a classified failure.
+     */
+    start(request: PreviewStartRequest, signal?: AbortSignal): Promise<PreviewStartResult>;
+    /**
+     * Start one validated configuration, holding its in-flight claim.
+     * @param workspace - the resolved workspace.
+     * @param launch - the configuration, already known to name a command.
+     * @param origin - which file it came from.
+     * @param signal - cancellation of the start.
+     * @returns the started row, or a classified failure.
+     */
+    private spawn;
+    /**
+     * Stop one server and forget it.
+     * @param request - the handle.
+     * @returns settlement, or a classified failure.
+     */
+    stop(request: PreviewStopRequest): Promise<PreviewStopResult>;
+    /**
+     * Read one server's output from a caller-owned offset, with its state at read time.
+     * @param request - the handle and the offset already rendered.
+     * @returns the delta and the state, or a classified failure.
+     */
+    logs(request: PreviewLogsRequest): PreviewLogsResult;
+    /**
+     * Terminate every server and refuse new ones. Called from the service's teardown effect.
+     * @returns after every process tree has exited.
+     */
+    disposeAll(): Promise<void>;
+    /**
+     * The `previews` settings rows, normalized into the shape the merge reads.
+     * @returns the configured launches.
+     */
+    private settingsLaunches;
+    /**
+     * Read and parse the workspace's launch file.
+     * @param workspace - the resolved workspace.
+     * @param signal - cancellation for the read.
+     * @returns the configurations, the file's path when it existed, and why it was ignored when it was.
+     */
+    private readLaunchFile;
+    /**
+     * Resolve the directory one configuration runs in, proving it stays inside the workspace.
+     * @param workspace - the resolved workspace.
+     * @param launch - the configuration.
+     * @param signal - cancellation for the resolution.
+     * @returns the directory, or the failure to return.
+     */
+    private launchDirectory;
+    /**
+     * Watch one process for its exit.
+     * @param record - the started server.
+     */
+    private watch;
+    /**
+     * Probe one server's port until it accepts or the deadline passes.
+     * @param record - the started server.
+     */
+    private awaitReady;
+    /**
+     * Move whatever the collected streams hold into the retained buffer.
+     *
+     * Both streams share one buffer and one offset, because the panel shows one log: a dev server
+     * prints its banner on one and its errors on the other, and two independently scrolling views of
+     * the same startup would be harder to read, not easier.
+     * @param record - the server to drain.
+     */
+    private drain;
+    /**
+     * Find a live record for one workspace and configuration name.
+     * @param workspace - canonical workspace path.
+     * @param name - configuration name.
+     * @returns the record, when one exists.
+     */
+    private find;
+    /**
+     * Stop one process tree without letting a cleanup fault escape.
+     * @param record - the server to stop.
+     * @returns after the tree has exited.
+     */
+    private terminate;
+    /**
+     * Project one configuration into its view, attaching a live record when one exists.
+     * @param resolved - the configuration and its origin.
+     * @param workspace - canonical workspace path.
+     * @returns the view.
+     */
+    private view;
+    /**
+     * Project one live record into its view.
+     * @param record - the server.
+     * @returns the view.
+     */
+    private viewOf;
+}
+export {};

package/types/host/run.d.ts

@@ -0,0 +1,72 @@
+/**
+ * One-shot command execution over `ctx.subprocess`, shared by the git reader and the Open in
+ * launcher.
+ *
+ * The subprocess seam applies no defaults, so every disposition, bound, and grace period is stated
+ * here from this plugin's own settings — which is also what keeps the two callers' behavior
+ * configurable from cordis.yml rather than from constants buried in a runner.
+ * @module @achasoft/dsh-advanced-sidebar/host/run
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Everything one invocation needs; nothing is defaulted. */
+export interface CommandSpec {
+    /** Executable and arguments; `argv[0]` is a resolved executable path. */
+    readonly argv: readonly string[];
+    /** Working directory. */
+    readonly cwd: string;
+    /** Wall-clock bound; exceeding it terminates the process tree. */
+    readonly timeoutMs: number;
+    /** In-memory cap per stream, in bytes; overflow keeps the tail. */
+    readonly maxBytes: number;
+    /** TERM-to-KILL grace for the termination escalation. */
+    readonly graceMs: number;
+    /** Explicit environment entries layered over the provider's scrubbed base. */
+    readonly env?: Record<string, string>;
+}
+/** Exit facts and collected output of one finished command. */
+export interface CommandOutcome {
+    /** Exit code; null when the process died from a signal. */
+    readonly exitCode: number | null;
+    /** Terminating signal; null on a normal exit. */
+    readonly signal: string | null;
+    /** Collected stdout. */
+    readonly stdout: string;
+    /** Collected stderr. */
+    readonly stderr: string;
+    /** True when the command was stopped by {@link CommandSpec.timeoutMs}. */
+    readonly timedOut: boolean;
+    /** True when the caller's own signal aborted the command. */
+    readonly aborted: boolean;
+    /**
+     * True when stdout exceeded {@link CommandSpec.maxBytes} and only its TAIL was retained.
+     *
+     * Reported rather than swallowed because it changes what the text means: a caller that then takes
+     * the head of this string is showing the middle of the real output, and would label it complete.
+     */
+    readonly stdoutLossy: boolean;
+}
+/** No filesystem/subprocess capability, or a spawn that never produced a process. */
+export declare class CommandUnavailableError extends Error {
+    /**
+     * @param message - operator diagnostic naming what was missing.
+     */
+    constructor(message: string);
+}
+/**
+ * Resolve one executable, returning undefined rather than throwing when it is absent.
+ * @param ctx - Host context carrying the optional subprocess capability.
+ * @param command - executable name or absolute path.
+ * @param signal - cancellation for the lookup.
+ * @returns the canonical executable path, or undefined when it does not resolve.
+ * @throws {CommandUnavailableError} when no subprocess capability is mounted.
+ */
+export declare function resolveCommand(ctx: Context, command: string, signal?: AbortSignal): Promise<string | undefined>;
+/**
+ * Run one command to completion under a timeout.
+ * @param ctx - Host context carrying the optional subprocess capability.
+ * @param spec - the fully specified invocation.
+ * @param signal - the caller's cancellation, distinguished from the timeout in the outcome.
+ * @returns exit facts and collected output.
+ * @throws {CommandUnavailableError} when no subprocess capability is mounted.
+ */
+export declare function runCommand(ctx: Context, spec: CommandSpec, signal?: AbortSignal): Promise<CommandOutcome>;