@chatcode/cco-better-sidebar 0.18.0-alpha.0

package/lib/types/fs-operations.d.ts

@@ -0,0 +1,30 @@
+/** Inputs of one upload: the session scope plus the request body stream. */
+export interface WorkspaceUploadInput {
+    /** The session workspace root; target and directory must stay inside it. */
+    cwd: string;
+    /** Absolute upload directory chosen by the client (inside `cwd`). */
+    dir: string;
+    /** Relative path below `dir` (absolute paths, '.', '..' and empty segments refused). */
+    relativePath: string;
+    /** The request body stream (raw bytes). */
+    chunks: AsyncIterable<string | Uint8Array>;
+    /** Byte cap; an oversized upload is refused without touching the target. */
+    limit: number;
+    /** Whether workspace containment is enforced (the `workspaceFence` setting; on by default). */
+    fence?: boolean;
+}
+/**
+ * Stream `chunks` into `dir/relativePath` atomically: a uniquely named temp
+ * sibling receives the bytes, then is renamed over the target. The parent
+ * directory is created on demand (recursive), so folder uploads work before
+ * any level exists. The unique temp name keeps concurrent uploads to the same
+ * target independent (each writes and renames its own file; the last rename
+ * wins) and never blocks later uploads after a crashed process.
+ *
+ * @throws SidebarError with a wire code for containment, shape, and size
+ * failures; the temp file is always removed on failure.
+ */
+export declare function writeWorkspaceUpload(input: WorkspaceUploadInput): Promise<{
+    path: string;
+    size: number;
+}>;

package/lib/types/fs-search.d.ts

@@ -0,0 +1,24 @@
+/** One search: the relative paths of the matching entries (dirs included so
+ *  the client can hint where matches live) plus the truncation flag. */
+export interface FsSearchResult {
+    matches: string[];
+    truncated: boolean;
+}
+/** Search budgets (both injectable for tests). */
+export interface FsSearchOptions {
+    /** Row cap of the result list (default 200). */
+    maxMatches?: number;
+    /** Total entries visited before the walk gives up (default 100_000). */
+    maxVisited?: number;
+}
+/**
+ * Search `root` recursively for entries whose name contains `query`
+ * (case-insensitive).
+ * @param root - absolute search root.
+ * @param query - the name substring; empty matches nothing.
+ * @param opts - budget overrides (tests).
+ * @returns the matching paths RELATIVE to `root` ('/'-separated), sorted,
+ *  plus whether a budget cut the walk short. An unreadable level is skipped
+ *  (permission errors never fail the whole search).
+ */
+export declare function searchFiles(root: string, query: string, opts?: FsSearchOptions): Promise<FsSearchResult>;

package/lib/types/fs-tree.d.ts

@@ -0,0 +1,51 @@
+/** One explorer row. */
+export interface SidebarFsEntry {
+    name: string;
+    path: string;
+    isDir: boolean;
+    hidden: boolean;
+    /** Whether the row is a symlink; `isDir` then describes the link's target. */
+    isSymlink: boolean;
+    /** For symlinks: the target is missing or unreadable (stat failed). */
+    broken: boolean;
+}
+/** One listed level. */
+export interface SidebarFsListing {
+    path: string;
+    entries: SidebarFsEntry[];
+    truncated: boolean;
+}
+/** Directory-first, case-insensitive name ordering (VSCode explorer order). */
+export declare function compareEntries(a: SidebarFsEntry, b: SidebarFsEntry): number;
+/**
+ * List one directory level.
+ * @param path - absolute directory path.
+ * @param maxEntries - row bound of one level (extra rows flag `truncated`).
+ * @returns the sorted listing.
+ * @throws {SidebarError} fs-error when the level is unreadable or not a directory.
+ */
+export declare function listDirectory(path: string, maxEntries?: number): Promise<SidebarFsListing>;
+/** The root row label of a listing: the last path segment (or the full path at the filesystem root). */
+export declare function rootLabel(path: string): string;
+/** Parent of a path, or undefined at the filesystem root (the explorer's "up" target). */
+export declare function parentOf(path: string): string | undefined;
+/**
+ * Normalize a caller-supplied path to an absolute, resolved path or throw
+ * fs-error. `path.isAbsolute()` is the OS's own notion of absolute: POSIX
+ * roots (`/...`), Windows drive letters (`C:\...`) and — on win32 — UNC
+ * network shares (`\\server\share\...`); drive-relative forms (`C:foo`)
+ * stay rejected.
+ */
+export declare function requireAbsolute(path: string): string;
+/**
+ * Whether `target` lies under `base` (or equals it), tolerant of separator
+ * style and — on Windows, where the filesystem is case-insensitive — of
+ * letter case. The media route uses this instead of a raw `startsWith` so a
+ * case-mismatched or mixed-separator path can never be misclassified
+ * (e.g. `C:\Users\Me` vs `c:/users/me/file.png`).
+ * @param platform - filesystem semantics; injectable so both branches are
+ * unit-testable on any host.
+ */
+export declare function isWithin(base: string, target: string, platform?: NodeJS.Platform): boolean;
+/** Message text of an unknown thrown value. */
+export declare function messageOf(error: unknown): string;

package/lib/types/git.d.ts

@@ -0,0 +1,124 @@
+/** 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[];
+    /** True when the working tree had more rows than `GIT_STATUS_LIMIT`; the
+     *  panel shows a truncation notice instead of freezing on a huge untracked
+     *  set (issue #369). */
+    truncated?: boolean;
+    /** Selected repository root, or the discovered roots when the cwd is a container. */
+    root?: string;
+    repositories?: string[];
+}
+/** One linked checkout returned by `git worktree list --porcelain`. */
+export interface GitWorktree {
+    /** Absolute checkout root. */
+    path: string;
+    /** Branch name without `refs/heads/`, or `HEAD` when detached. */
+    branch: string;
+    /** Whether this checkout contains the session cwd. */
+    current: boolean;
+    /** Number of staged + unstaged status rows (a file changed on both sides counts once). */
+    changes: number;
+}
+/** 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[];
+/** One raw porcelain worktree record. Prunable checkouts are retained by
+ * Git's administrative metadata after their directory disappears and must not
+ * become selectable command targets. Locked checkouts remain usable. */
+export interface GitWorktreeRecord {
+    path: string;
+    branch: string;
+    locked: boolean;
+    prunable: boolean;
+}
+/** Parse `git worktree list --porcelain` records. Production requests use
+ * `-z` so even newlines and non-ASCII bytes in checkout paths stay lossless;
+ * newline framing remains accepted for small fixtures and older Git output. */
+export declare function parseWorktreeList(output: string): GitWorktreeRecord[];
+/** 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`).
+ *  Probe timeout is short: a cwd on a stalled mount must not hold the panel
+ *  hostage for the full command budget (issue #369). */
+export declare function isGitRepo(cwd: string): Promise<boolean>;
+/** Discover the current repository or direct child repositories. Results are
+ *  cached per cwd and concurrent callers share one in-flight scan, so opening
+ *  the panel (three parallel git.* requests) costs a single discovery pass. */
+export declare function repoRoots(cwd: string): Promise<string[]>;
+/** Resolve the selected repository, defaulting to the first discovered root. */
+export declare function repoRoot(cwd: string, selected?: 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). `--untracked-files=all` lists
+ * the contents of new directories as individual entries, while preserving
+ * repository discovery and explicit repository selection for workspace roots.
+ */
+export declare function status(cwd: string, selected?: string): Promise<GitStatusResult>;
+/** All linked checkouts of the repository containing `cwd`, enriched with a
+ * live change count. The current checkout is first so a single-worktree repo
+ * preserves the old UI ordering. */
+export declare function worktrees(cwd: string): Promise<GitWorktree[]>;
+/** Resolve an optional client-selected linked checkout. A caller may never use
+ * this seam to point Git operations at an unrelated repository: the target
+ * must occur in the authoritative session repository's worktree list. */
+export declare function resolveWorktree(cwd: string, requested?: string): Promise<string>;
+/** Diff text of the worktree (unstaged) or the index (staged). */
+export declare function diff(cwd: string, path: string | undefined, staged: boolean, selected?: string): Promise<string>;
+/** Stage paths (all when path is undefined). */
+export declare function stage(cwd: string, path: string | undefined, selected?: string): Promise<void>;
+/** Unstage paths (all when path is undefined). */
+export declare function unstage(cwd: string, path: string | undefined, selected?: string): Promise<void>;
+/** Commit the staged changes with a message (global identity untouched). */
+export declare function commit(cwd: string, message: string, selected?: string): Promise<void>;
+/** Branch names (current first). */
+export declare function branches(cwd: string, selected?: string): Promise<{
+    current: string;
+    names: string[];
+}>;
+/** Switch to an existing branch. */
+export declare function checkout(cwd: string, branch: string, selected?: string): Promise<void>;
+/** Recent commit history (newest first), lazily pageable via skip/count. */
+export declare function log(cwd: string, count?: number, skip?: number, selected?: string): 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, selected?: 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, selected?: 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, selected?: string): Promise<void>;
+/** Revert one commit onto the current branch with an auto-generated message. */
+export declare function revert(cwd: string, hash: string, selected?: string): Promise<void>;
+/** Cherry-pick one commit onto the current branch. */
+export declare function cherryPick(cwd: string, hash: string, selected?: string): Promise<void>;

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

@@ -0,0 +1,59 @@
+/**
+ * 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
+ *   UNC (\\server\share\... or //server/share/...):
+ *     → /sidebar/html/S//server/share/proj/a.html  ('//' right after the
+ *       sessionId marks the UNC prefix; the WHATWG URL keeps '//' intact so
+ *       relative assets still resolve inside the same route)
+ *
+ * The decoder rebuilds the marker as a forward-slash `//server/share/...`
+ * path. That form is intentionally platform-neutral: `node:path` resolves it
+ * to `\\server\share\...` on win32 and `/server/share/...` on POSIX, so the
+ * host's existing requireAbsolute + isWithin fence needs no platform signal
+ * (a leading `//` is a legal POSIX absolute path, so no data is lost on
+ * either platform).
+ *
+ * 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 path, malformed percent encoding, and a
+ * missing sessionId or file path (400). The caller still must bound the
+ * decoded path with the workspace real-path guard — 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,47 @@
+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 web runtime's trusted hosts, 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;
+    };
+    /**
+     * Whether the dsh-web-ui family's aionui-panel has been selected as the
+     * right-panel provider (the `aionui-panel` settings namespace resolves
+     * `rightPanel: 'aionui-panel'`). While true the sidebar must not mount —
+     * the two right panels are mutually exclusive. False when the namespace is
+     * absent (no aionui installed) or the provider is anything else.
+     */
+    externalDisable(): boolean;
+    /** 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, webRuntime).
+ * @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/login-route.d.ts

@@ -0,0 +1,2 @@
+import type { Context, SidebarHttpRequest } from './context-types.ts';
+export declare function registerLoginRoute(ctx: Context, fence: (req: SidebarHttpRequest) => boolean): () => void;

package/lib/types/open-external.d.ts

@@ -0,0 +1,24 @@
+/** The two external open actions the route accepts. */
+export type OpenExternalAction = 'reveal' | 'url';
+/** One platform opener invocation (argv array — never a shell string). */
+export interface ExternalCommand {
+    command: string;
+    args: string[];
+}
+/** Reveal/select a path in the OS file manager. On Linux there is no common
+ *  select protocol — the containing directory is opened instead (KISS). */
+export declare function revealCommand(path: string, platform?: NodeJS.Platform): ExternalCommand;
+/** Hand a custom-scheme URL to the OS protocol handler. */
+export declare function urlCommand(url: string, platform?: NodeJS.Platform): ExternalCommand;
+/** Validate a URL-scheme open target: a parseable custom-scheme URL (never
+ *  http/https — those would only dump the URL into a browser tab). */
+export declare function validateExternalUrl(raw: string): string;
+/**
+ * Launch one external open action and return immediately (detached, no
+ * stdio). Spawn failures are reported through the child's 'error' event —
+ * by then the route already returned, so the event is swallowed (the OS
+ * dialog about a missing handler is the user-visible outcome either way).
+ */
+export declare function launchExternal(action: OpenExternalAction, value: string): {
+    started: true;
+};

package/lib/types/path-security.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Resolve an existing workspace path through symlinks and (unless disarmed)
+ * enforce containment.
+ *
+ * @param cwd - Session workspace directory.
+ * @param target - Client-supplied absolute path.
+ * @param fence - Whether containment is enforced (the settings-page
+ * `workspaceFence` switch). Even when false the paths are still resolved
+ * through symlinks so callers always receive the canonical target.
+ * @returns The canonical absolute path used for the filesystem operation.
+ */
+export declare function ensureWorkspacePath(cwd: string, target: string, fence?: boolean): Promise<string>;
+/**
+ * Validate a write destination, including destinations that do not exist yet.
+ * Existing targets are resolved to catch symlinks; missing targets are checked
+ * against the nearest existing ancestor before the caller creates or renames.
+ * The returned path is rebuilt from that canonical ancestor, so an existing
+ * symlink is never left in the path passed to the write operation.
+ *
+ * @param cwd - Session workspace directory.
+ * @param target - Client-supplied absolute destination path.
+ * @param fence - Whether containment is enforced (the settings-page
+ * `workspaceFence` switch). Resolution/canonicalization is identical either way.
+ * @returns A canonical path for an existing target or its nearest existing ancestor.
+ */
+export declare function ensureWorkspaceWritePath(cwd: string, target: string, fence?: boolean): Promise<string>;