dsh-better-sidebar 0.10.0

package/lib/types/git.d.ts

@@ -0,0 +1,75 @@
+/** A parsed `git status --porcelain=v1 -z` entry. */
+export interface GitStatusEntry {
+    path: string;
+    /** Two-letter index/worktree status (X Y), e.g. 'M ', ' M', 'A ', '??'. */
+    xy: string;
+}
+/** The source-control panel snapshot. */
+export interface GitStatusResult {
+    isRepo: boolean;
+    branch?: string;
+    entries: GitStatusEntry[];
+}
+/** One `git log` row. */
+export interface GitLogEntry {
+    /** Short hash (7+ chars, display). */
+    hash: string;
+    /** Full 40-char hash (advanced operations: revert / cherry-pick). */
+    hashFull: string;
+    subject: string;
+    author: string;
+    /** ISO 8601 author date (`%ai`), e.g. `2024-01-01 10:00:00 +0800`. */
+    date: string;
+    /** Ref decorations (`%D` with --decorate=short), e.g. `HEAD -> main, origin/main`; '' when none. */
+    refs: string;
+}
+/** One git failure (stderr text as the message). */
+export declare class GitCommandError extends Error {
+    readonly code: string;
+    readonly command: string;
+    constructor(message: string, code: string | undefined, command: string);
+}
+/** Parse porcelain v1 -z output into entries (rename/copy pairs collapse to one row). */
+export declare function parsePorcelainZ(output: string): GitStatusEntry[];
+/** Parse `git log --pretty=format:%h%x1f%s%x1f%an%x1f%ai%x1f%H%x1f%D` rows. */
+export declare function parseLogLines(output: string): GitLogEntry[];
+/** Whether the directory is inside a git work tree (exit-0 `git rev-parse`). */
+export declare function isGitRepo(cwd: string): Promise<boolean>;
+/** The repository top level containing `cwd` (`git rev-parse --show-toplevel`). */
+export declare function repoRoot(cwd: string): Promise<string>;
+/** The current branch name (`git rev-parse --abbrev-ref HEAD`; 'HEAD' when detached). */
+export declare function currentBranch(cwd: string): Promise<string>;
+/** Working-tree status (untracked included). */
+export declare function status(cwd: string): Promise<GitStatusResult>;
+/** Diff text of the worktree (unstaged) or the index (staged). */
+export declare function diff(cwd: string, path: string | undefined, staged: boolean): Promise<string>;
+/** Stage paths (all when path is undefined). */
+export declare function stage(cwd: string, path: string | undefined): Promise<void>;
+/** Unstage paths (all when path is undefined). */
+export declare function unstage(cwd: string, path: string | undefined): Promise<void>;
+/** Commit the staged changes with a message (global identity untouched). */
+export declare function commit(cwd: string, message: string): Promise<void>;
+/** Branch names (current first). */
+export declare function branches(cwd: string): Promise<{
+    current: string;
+    names: string[];
+}>;
+/** Switch to an existing branch. */
+export declare function checkout(cwd: string, branch: string): Promise<void>;
+/** Recent commit history (newest first), lazily pageable via skip/count. */
+export declare function log(cwd: string, count?: number, skip?: number): Promise<GitLogEntry[]>;
+/**
+ * Content of a file at a revision (`git show <rev>:<path>`), or null when the
+ * revision has no such path (a new/untracked file has no HEAD side).
+ */
+export declare function show(cwd: string, rev: string, path: string): Promise<string | null>;
+/** Full patch text of one commit (`git show` with the commit header suppressed).
+ *  Merge commits show their diff against the first parent (`-m --first-parent`
+ *  is a no-op for regular commits), so a history click always has content. */
+export declare function commitDiff(cwd: string, hash: string): Promise<string>;
+/** Discard the worktree changes of one path (`git checkout -- <path>`; the index is untouched). */
+export declare function discard(cwd: string, path: string): Promise<void>;
+/** Revert one commit onto the current branch with an auto-generated message. */
+export declare function revert(cwd: string, hash: string): Promise<void>;
+/** Cherry-pick one commit onto the current branch. */
+export declare function cherryPick(cwd: string, hash: string): Promise<void>;

package/lib/types/html-route.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Pure URL vocabulary of the /sidebar/html route (HTML previewer).
+ *
+ * Why path-encoded parameters instead of a query string: the previewed
+ * page resolves its relative assets (./style.css, img/x.png) against the
+ * document URL, and the WHATWG URL algorithm DROPS the query of a
+ * path-relative reference — `/sidebar/html?a=1&path=/a/b/` + `./style.css`
+ * would lose the session scope and the route would reject the asset.
+ * Encoding everything into the URL path keeps relative resolution inside
+ * the same route with every request self-contained:
+ *
+ *   /sidebar/html/<sessionId>/<absolute-path segments, encodeURIComponent'd>
+ *   /sidebar/html/S/Users/me/proj/index.html
+ *     + ./style.css → /sidebar/html/S/Users/me/proj/style.css
+ *   Windows: C:\Users\me\a.html → /sidebar/html/S/C%3A/Users/me/a.html
+ *
+ * This module is intentionally dependency-free (no node imports, no wire
+ * helpers) so the client bundle can import `encodeHtmlUrl` without tripping
+ * the build-time purity gate; the host converts decode failures into
+ * SidebarError responses at the route boundary.
+ */
+/** One decoded route reference. */
+export interface HtmlRouteRef {
+    sessionId: string;
+    /** Absolute file path (leading slash; Windows drives keep their colon). */
+    path: string;
+}
+/** Decode outcome: the reference, or a client-error description. */
+export type HtmlDecodeResult = {
+    ok: true;
+    ref: HtmlRouteRef;
+} | {
+    ok: false;
+    status: 400 | 404;
+    message: string;
+};
+/** The route prefix both encoders/decoders agree on. */
+export declare const HTML_ROUTE_PREFIX = "/sidebar/html/";
+/** Build the route URL for one absolute file path (client + tests). */
+export declare function encodeHtmlUrl(sessionId: string, path: string): string;
+/**
+ * Decode a route pathname into the session + absolute file path. Rejects
+ * a wrong prefix (404), an empty or double-slash path, malformed percent
+ * encoding, and a missing sessionId or file path (400). The caller still
+ * must bound the decoded path with requireAbsolute + isWithin(cwd) — a
+ * decoded `..` segment resolves outside the cwd and is refused there.
+ */
+export declare function decodeHtmlUrl(pathname: string): HtmlDecodeResult;

package/lib/types/index.d.ts

@@ -0,0 +1,39 @@
+import type { Context } from './context-types.ts';
+import { Config, type ResolvedSidebarConfig, type SidebarConfig } from './config.ts';
+export { Config };
+export type { SidebarConfig, ResolvedSidebarConfig };
+export type { Context } from './context-types.ts';
+export type { BetterSidebarService, TabDescriptor, TabComponentProps, FileViewerDescriptor, FileViewerProps, FileFetchStrategy, } from './client/service.ts';
+/** Plugin identity for cordis.yml rows. */
+export declare const name = "dsh-better-sidebar";
+/** Services required before mounting: the webserver routes, the session store, the loader's connection row, and the tool registry. */
+export declare const inject: string[];
+/** Content type served by /sidebar/file (binary-safe fallback for unknowns). */
+export declare function mediaTypeForPath(path: string): string;
+/**
+ * The live face of the side card settings namespace, bound to the settings
+ * service when it is mounted. The DSH settings RPC domain only serves
+ * allowlisted namespaces (api-proxy exposedNamespaces), so the client reads
+ * and writes THIS namespace through the plugin's own fenced /sidebar routes,
+ * which call the seam in-process — no configuration-client gate involved.
+ */
+export interface SidebarSettingsFace {
+    /** The current resolved value + revision (undefined while the settings service is absent). */
+    get(): {
+        value?: unknown;
+        revision?: number;
+    };
+    /** Merge a patch (revision-guarded) and return the fresh resolved view. */
+    update(patch: Record<string, unknown>, expectedRevision?: number): Promise<{
+        value?: unknown;
+        revision?: number;
+    }>;
+}
+/**
+ * Plugin body: mount the fenced routes and the pty lifecycle.
+ * @param ctx - host plugin context (webServer, sessions, loader).
+ * @param config - deployment-provided limits; the Loader validates against
+ * {@link Config} and fills defaults, direct callers get them from
+ * {@link resolveSidebarConfig}.
+ */
+export declare function apply(ctx: Context, config?: SidebarConfig): void;

package/lib/types/invariant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Package-owned invariant companion for `dsh-better-sidebar`.
+ * @module dsh-better-sidebar/invariant
+ */
+import type { Context } from './context-types.ts';
+/** Cordis companion plugin name. */
+export declare const name = "dsh-better-sidebar-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;

package/lib/types/jobs-routes.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Background-job routes of the /sidebar JSON API ('jobs.output' /
+ * 'jobs.kill'). The job LIST needs no route: it arrives through the
+ * harness's `session/jobs` push mirror (`jobsBySession` in the sessions
+ * list feed). The routes:
+ *
+ * - 'jobs.output' — REPLAYS the output the MODEL has read so far for one
+ *   job. The source is the owner session's own event log: `tool/call` rows
+ *   of `job_output` name the job via `arguments.job_id`, and the paired
+ *   `tool/result` rows carry the finalized content the model received.
+ *   Because the session store's in-memory log can lag the live append feed
+ *   after a host restart (the store session stays frozen at its
+ *   rehydration boundary), the plugin ALSO mirrors job_output events from
+ *   the live `session/event` feed and merges both sources (deduped by seq).
+ *   This touches NO DSH source: the model's `job_output` cursor is never
+ *   consumed, and the pane stays empty until the agent reads the job.
+ * - 'jobs.kill' — the registry's stock `kill` (a pristine DSH API),
+ *   fenced by the owning session via the live agent caller. Absent registry
+ *   → 503, mirroring the settings routes' optional-service downgrade.
+ */
+import type { Context } from './context-types.ts';
+/** The two background-job routes of the sidebar API. */
+export interface SidebarJobsRoutes {
+    /** The output the model has read so far for one job (event replay, capped). */
+    output(payload: unknown): {
+        text: string;
+        truncated: boolean;
+        read: boolean;
+    };
+    /** Request cancellation of one job (live jobs flip to stopping). */
+    kill(payload: unknown): {
+        ok: true;
+        outcome: 'requested' | 'already-finished';
+    };
+}
+/**
+ * Build the jobs routes bound to the plugin context. `output` merges the
+ * owner session's own event log with the live job_output mirror; `kill`
+ * reads the jobs/agents services lazily and degrades to a 503 when the
+ * deployment lacks the registry.
+ * @param ctx - host plugin context.
+ * @param outputLimit - response cap for one output replay in bytes; longer
+ *   texts are sliced and flagged `truncated` (mirrors the fs.read cap).
+ */
+export declare function buildJobsApi(ctx: Context, outputLimit: number): SidebarJobsRoutes;

package/lib/types/prefs-shared.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Shared "Side card" preference vocabulary (types + constants), consumed by
+ * BOTH halves: the host registers the schemastery schema over these values
+ * (config.ts) and the client reads/writes them through the settings RPC
+ * (client/prefs.ts, client/SideCardSection.tsx). Kept free of schemastery so
+ * the browser bundle never pulls the schema runtime in.
+ */
+/** The user-settings namespace holding the side card preferences. */
+export declare const SIDEBAR_PREFS_NS = "dsh-better-sidebar";
+/** User-facing side card preferences (new-conversation defaults). */
+export interface SidebarPrefs {
+    /** Whether a brand-new conversation opens the side card by default. */
+    openByDefault: boolean;
+    /** Default panel width as a percent of the window width (20–60). */
+    defaultWidthPercent: number;
+    /**
+     * Whether the sidebar auto-activates (opens the panel) and expands the
+     * Subagent page when the current conversation spawns a new subagent.
+     */
+    autoOpenSubagent: boolean;
+    /**
+     * Whether the sidebar auto-activates (opens the panel) and expands the
+     * Jobs page when a NEW background job appears for the current
+     * conversation (any new job id, not just the first one).
+     */
+    autoOpenJobs: boolean;
+    /**
+     * Whether the model-facing agent terminal tools (terminal_create / list /
+     * send / read / wait_for / resize / signal / close) are injected into the
+     * model's toolset. Off by default: the feature stays dormant until the
+     * user explicitly enables it in the side card settings.
+     */
+    agentTerminalTools: boolean;
+    /**
+     * Whether expanding the bottom panel for the FIRST time in a session tries
+     * to open a fresh terminal tab there (the terminal quota/type still gates
+     * the attempt). On by default; the switch lives under the terminal tab's
+     * row in the Side card settings.
+     */
+    bottomPanelAutoTerminal: boolean;
+    /**
+     * Whether chat-side file opens (tool-row path links, the produced-files
+     * row, prose file mentions — every path that funnels through the client
+     * runtime's `ctx.workspaces.openPath`) open in the sidebar editor instead
+     * of the Host OS's default application. On by default; the editor tab's
+     * own enable switch gates it too (both must be on for the takeover).
+     */
+    interceptOpenPath: boolean;
+    /**
+     * Whether the HTML previewer drops its sandboxed iframe. Sandbox ON (the
+     * default) renders previewed HTML in an opaque-origin iframe that cannot
+     * touch the GUI; turning it OFF runs the previewed page with the GUI's
+     * own origin — full read/write access to session files and internal
+     * APIs. Only for trusted local content; the setting copy warns.
+     */
+    htmlViewerNoSandbox: boolean;
+    /**
+     * Whether a newly opened HTML preview starts UNSANDBOXED (the per-surface
+     * temporary unlock pre-applied). Off by default: previews open sandboxed
+     * and the status row offers the one-tap unlock; when on, previews open
+     * in the red unsandboxed state and the status row offers a one-tap
+     * restore for the current file.
+     */
+    htmlViewerDefaultUnsafe: boolean;
+    /**
+     * Whether the browser tab drops its sandboxed iframe. Sandbox ON (the
+     * default) keeps browsed sites in an opaque origin with no GUI access;
+     * turning it OFF runs any visited site with the GUI's own origin — it
+     * can read session data and act as the logged-in GUI. Only for trusted
+     * sites; the setting copy warns.
+     */
+    browserNoSandbox: boolean;
+    /**
+     * Whether clicking an http(s) EXTERNAL link in the GUI (chat messages,
+     * tool rows, prose mentions) opens the sidebar browser instead of a new
+     * browser tab. On by default; gated on the browser tab's own enable
+     * switch (both must be on for the takeover). Ctrl/Cmd+click always
+     * bypasses the takeover.
+     */
+    browserInterceptLinks: boolean;
+    /**
+     * Per-tab enable switches, keyed by tab descriptor id (`'explorer'`,
+     * `'my-plugin:db'`). An ABSENT key means enabled — only an explicit
+     * `false` disables a tab type (hidden from the + menu, `openTab` refuses,
+     * and derived flows like subagent auto-open / agent-terminal tabs stop).
+     * Already-open tabs of a disabled type keep rendering (closing one
+     * prevents reopening), matching the "existing conversations keep their
+     * own layouts" rule.
+     */
+    tabsEnabled: Record<string, boolean>;
+    /**
+     * Per-viewer enable switches, keyed by file viewer descriptor id
+     * (`'image'`, `'my-plugin:csv'`). An ABSENT key means enabled; a disabled
+     * viewer is skipped by `matchFileViewer` so files fall through to the
+     * next matching viewer (or the download button when none match).
+     */
+    viewersEnabled: Record<string, boolean>;
+}
+/** Range contract of {@link SidebarPrefs.defaultWidthPercent}. */
+export declare const WIDTH_PERCENT_MIN = 20;
+export declare const WIDTH_PERCENT_MAX = 60;
+export declare const WIDTH_PERCENT_DEFAULT = 30;
+/** Fallback prefs used whenever the settings document is unreachable or malformed. */
+export declare const SIDEBAR_PREFS_DEFAULTS: SidebarPrefs;
+/** Clamp one width percent into the contract range (shared by schema and client reads). */
+export declare function clampWidthPercent(value: number): number;

package/lib/types/pty-manager.d.ts

@@ -0,0 +1,76 @@
+import * as nodePty from 'node-pty';
+/**
+ * Restore the executable bit pnpm strips from node-pty's prebuilt
+ * spawn-helper (the macOS helper that forks and sets up the pty). Without it
+ * every spawn fails with `posix_spawnp failed`. Idempotent; mirrors
+ * @deepseek-ai/dsh-terminal-bash's ensure-spawn-helper postinstall, run at
+ * plugin activation so link-installed deployments get the fix too.
+ */
+export declare function ensureSpawnHelper(): void;
+/** One live terminal. */
+export interface SidebarPty {
+    /** `${sessionId}:${tabId}` registry key. */
+    key: string;
+    sessionId: string;
+    tabId: string;
+    /** The working directory the process was SPAWNED with (a reconnect that
+     *  resolves a different authoritative cwd respawns instead of reusing —
+     *  the page-load hydrate race can attach the real cwd after the first
+     *  connect, and a shell in the wrong directory must not linger). */
+    cwd: string;
+    pty: nodePty.IPty;
+    /** Output accumulated since spawn (bounded; head dropped when over the limit). */
+    transcript: string;
+    /** Whether the top-level process exited (transcript stays replayable). */
+    exited: boolean;
+    exitCode?: number | null;
+}
+/**
+ * The terminal registry. `maxPerSession` bounds concurrent processes per
+ * conversation (the client caps tabs at the same number).
+ */
+export declare class PtyManager {
+    private readonly shell;
+    private readonly maxPerSession;
+    private readonly sessions;
+    private readonly pendingCloses;
+    constructor(shell: string, maxPerSession: number);
+    /** All live terminal keys of one session. */
+    keysOf(sessionId: string): string[];
+    /**
+     * Open (or reuse) the terminal for a session/tab key. A handle whose
+     * process already exited is replaced with a fresh spawn (reconnecting a
+     * dead terminal must yield a live shell, not an input sink), and so is a
+     * live handle whose spawn cwd differs from the now-authoritative one (the
+     * first connect of a page load can arrive before the session hydrates, so
+     * it fell back to the process cwd — reconnecting with the real cwd must
+     * restart the shell in the right directory). Reopening also cancels any
+     * pending scheduled close (a reconnect within the grace window keeps the
+     * process alive).
+     * @param sessionId - conversation id.
+     * @param tabId - client tab id.
+     * @param cwd - initial working directory (the session's cwd).
+     * @param cols - initial terminal width.
+     * @param rows - initial terminal height.
+     * @returns the live handle.
+     * @throws {SidebarError} pty-error when the per-session cap is reached.
+     */
+    open(sessionId: string, tabId: string, cwd: string, cols: number, rows: number): SidebarPty;
+    /**
+     * Schedule the terminal's destruction after `delayMs`. A tab close sends
+     * delay 0 (release the quota immediately); a bare socket drop (refresh,
+     * crash) uses the grace period so a quick reconnect keeps the process.
+     * `open()` cancels any pending close.
+     */
+    scheduleClose(key: string, delayMs: number): void;
+    /** Cancel a pending scheduled close (the terminal is being reopened). */
+    cancelClose(key: string): void;
+    /** Resolve a live handle by key, or undefined. */
+    get(key: string): SidebarPty | undefined;
+    /** Close a terminal and drop its state (the owning tab was closed). */
+    close(key: string): void;
+    /** Close every terminal (plugin teardown). */
+    disposeAll(): void;
+}
+/** The interactive shell for this platform (empty SHELL falls back). */
+export declare function defaultShell(): string;

package/lib/types/tools.d.ts

@@ -0,0 +1,28 @@
+import type { Context } from './context-types.ts';
+import { AgentPtyRegistry } from './agent-pty.ts';
+/**
+ * Bound a string to a byte limit, marking truncation. Truncation never
+ * splits a multi-byte UTF-8 sequence: when the byte cap lands inside one,
+ * the walk-back retreats to the sequence's leading byte so the retained
+ * prefix decodes cleanly (a split would decode to U+FFFD).
+ * @internal exported for the unit tests, like {@link snapshotOf}.
+ */
+export declare function boundBytes(text: string, maxBytes: number): {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * Register the eight terminal tools against the host tool registry. The
+ * `resolveCwd` callback threads the live session cwd (authoritative from the
+ * session store, falling back to the process cwd) so a freshly-created
+ * terminal lands in the right directory without the model passing it.
+ * Every uuid-keyed tool first asserts the terminal belongs to the calling
+ * session (`registry.assertOwned`), so one agent can never reach another
+ * session's terminals.
+ * @param ctx - host plugin context (carries the tools service).
+ * @param registry - the agent-owned terminal registry.
+ * @param resolveCwd - live cwd resolver for one session id.
+ * @returns a disposer that unregisters all eight tools (the caller gates
+ * registration on the side-card setting and calls this to turn them off).
+ */
+export declare function registerTools(ctx: Context, registry: AgentPtyRegistry, resolveCwd: (sessionId: string) => string): () => void;

package/lib/types/trust-fence.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Browser-trust fence for the sidebar routes, behaviorally identical to the
+ * /api gateway's fence in @deepseek-ai/dsh-client-connection
+ * (src/api-request-trust.ts + src/loopback-hostname.ts, BSD-3-Clause,
+ * copied here because the package does not export these helpers and the
+ * plugin must not depend on its internals). Host-header loopback or a
+ * configured trusted authority passes; cross-site browser markers refuse.
+ * This is a DNS-rebinding / cross-site defense, not authentication.
+ */
+import type { IncomingHttpHeaders } from 'node:http';
+/** The request facts the fence reads (structural subset of IncomingMessage). */
+interface ApiTrustRequest {
+    headers: IncomingHttpHeaders;
+}
+/** Whether a normalized URL hostname names the local loopback authority. */
+export declare function isLoopbackHostname(hostname: string): boolean;
+/**
+ * Decide whether one sidebar request may reach the plugin routes.
+ * @param request - node HTTP request facts (headers).
+ * @param trustedHosts - non-loopback authorities this deployment serves.
+ * @returns true when the Host is ours (loopback or trusted) and browser markers are same-origin.
+ */
+export declare function isTrustedApiRequest(request: ApiTrustRequest, trustedHosts: readonly string[]): boolean;
+export {};

package/lib/types/wire.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Wire helpers for the /sidebar JSON API: bounded body reading, response
+ * writing, and the shared error envelope. Every API method returns
+ * `{ok: true, value}` on success and `{ok: false, error: {code, message}}`
+ * (HTTP 4xx/5xx matching the code) on failure.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Machine-readable error codes of the sidebar API. */
+export type SidebarErrorCode = 'bad-request' | 'not-found' | 'forbidden' | 'method-error' | 'fs-error' | 'git-error' | 'pty-error' | 'job-error' | 'settings-rejected' | 'settings-conflict' | 'internal';
+/** One API failure with its wire code and HTTP status. */
+export declare class SidebarError extends Error {
+    readonly code: SidebarErrorCode;
+    readonly status: number;
+    constructor(code: SidebarErrorCode, message: string, status?: number);
+}
+/** Success envelope of one API method. */
+export interface SidebarOk<T> {
+    ok: true;
+    value: T;
+}
+/** Failure envelope of one API method. */
+export interface SidebarErr {
+    ok: false;
+    error: {
+        code: SidebarErrorCode;
+        message: string;
+    };
+}
+/** Read and parse the JSON request body (bounded; malformed → bad-request). */
+export declare function readJsonBody(req: IncomingMessage): Promise<unknown>;
+/** Write a JSON response with the given status. */
+export declare function writeJson(res: ServerResponse, status: number, body: unknown): void;
+/** Write the success envelope. */
+export declare function writeOk(res: ServerResponse, value: unknown): void;
+/** Write the failure envelope for any thrown value (unknown → internal 500). */
+export declare function writeError(res: ServerResponse, error: unknown): void;
+/** Narrow an unknown payload value to a string, else throw bad-request. */
+export declare function requireString(payload: unknown, key: string): string;