@achasoft/dsh-advanced-sidebar 0.1.0 → 0.3.0

package/types/host/preview-content.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Pure decisions the same-origin preview routes are built on: what a file is, what MIME type it
+ * gets, and whether a URL is one this plugin is willing to fetch or frame.
+ *
+ * Kept free of `ctx`, `node:http`, and the filesystem so every rule here is a table lookup a test
+ * can state in one line. The two rules that matter most — a proxy target must be loopback, and a
+ * framed document must be same-origin — are the whole difference between a helpful preview and an
+ * open proxy or a cross-origin hole, so they live in functions rather than in a request handler's
+ * middle.
+ * @module @achasoft/dsh-advanced-sidebar/host/preview-content
+ */
+import type { PreviewFileKind } from './types.ts';
+/**
+ * Absolute path of the workspace-file route; one route, parameterized by query.
+ *
+ * Declared here rather than in the module that registers it because the BROWSER half builds URLs
+ * from these strings too, and this module is the one both halves already share. Two literals that
+ * had to agree would eventually stop agreeing, and the symptom would be a frame that 404s only
+ * after a rename nobody thought was load-bearing.
+ */
+export declare const FILE_ROUTE = "/advanced-sidebar/preview-file";
+/** Absolute path of the loopback reverse proxy; subpaths are forwarded as-is. */
+export declare const PROXY_ROUTE = "/advanced-sidebar/preview-proxy";
+/** Absolute path of the scratchpad route: renders text the panel posts, with no file behind it. */
+export declare const SCRATCHPAD_ROUTE = "/advanced-sidebar/preview-scratchpad";
+/**
+ * The scratchpad route derived from the file route.
+ *
+ * The two differ only in their last segment, and a deployment that overrides one would have to
+ * override the other; deriving it is what makes that impossible to forget.
+ * @param fileRoute - the file route, `/…/preview-file`.
+ * @returns the scratchpad route.
+ */
+export declare function scratchRoute(fileRoute: string): string;
+/**
+ * The lower-case extension of a path, without its dot.
+ * @param path - a file path or a URL pathname.
+ * @returns the extension, or the empty string when there is none.
+ */
+export declare function extensionOf(path: string): string;
+/**
+ * The MIME type one path is served with.
+ * @param path - a file path or a URL pathname.
+ * @returns the type; `application/octet-stream` when the extension says nothing.
+ */
+export declare function contentTypeOf(path: string): string;
+/**
+ * Whether a MIME type is text that needs an explicit charset.
+ *
+ * `text/*` and the `+json`/`+xml` suffixes are the two families where a browser guessing a charset
+ * would be guessing right most of the time and wrong exactly when it matters — a UTF-8 source file
+ * rendered as latin-1.
+ * @param contentType - the type, without parameters.
+ * @returns true when the type should carry `; charset=utf-8`.
+ */
+export declare function isTextual(contentType: string): boolean;
+/**
+ * How the browser should present one path.
+ *
+ * `.html` is `iframe` rather than `text`: the frame is the point of the mode, and the same-origin
+ * route injects the base URL that makes its relative assets resolve. `.svg` is treated as an
+ * `iframe` too, because an SVG document is scriptable — handing it to an `<img>` would silently
+ * drop its scripts and hand it to the frame instead keeps one behaviour for "a document".
+ * @param path - a file path or a URL pathname.
+ * @param contentType - the type it is served with; defaults to the one {@link contentTypeOf} gives.
+ * @returns the preview kind.
+ */
+export declare function classifyFile(path: string, contentType?: string): PreviewFileKind;
+/**
+ * Reject anything that is not plain HTTP(S).
+ *
+ * A `file:` or `data:` URL handed to the proxy would read the Host's own disk, and a `javascript:`
+ * one would be an injection; none of them is something a preview of a dev server needs.
+ * @param value - the candidate URL.
+ * @returns the parsed URL, or the reason it was refused.
+ */
+export declare function parseHttpUrl(value: string): {
+    ok: true;
+    url: URL;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Whether a parsed URL points at this machine.
+ *
+ * The proxy exists so a loopback dev server can be framed same-origin. Without this check it would
+ * also fetch `http://10.0.0.5/admin` on the operator's behalf, from the operator's network position
+ * — an open proxy bolted to the GUI. Only literal loopback names and addresses pass: `localhost`,
+ * `127.0.0.0/8`, and `[::1]`.
+ *
+ * A hostname that merely *resolves* to loopback (a split-horizon DNS entry, a hostfile alias) is
+ * refused rather than probed. Deciding this by lookup would make the answer depend on the resolver
+ * at request time, and a DNS rebinding attack is exactly the case where the answer changes between
+ * the check and the fetch.
+ * @param url - a parsed URL.
+ * @returns true when the host is a loopback literal.
+ */
+export declare function isLoopbackHost(url: URL): boolean;
+/**
+ * Refuse a URL this plugin will not fetch.
+ * @param value - the candidate URL.
+ * @returns the parsed URL, or the reason it was refused.
+ */
+export declare function validateProxyTarget(value: string): {
+    ok: true;
+    url: URL;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Percent-encode a value for a query string, using the one encoder every runtime here has.
+ * @param value - the raw value.
+ * @returns the encoded value.
+ */
+export declare function encodeQuery(value: string): string;
+/**
+ * Build the same-origin URL one workspace file is framed from.
+ * @param fileRoute - the absolute file route path, no trailing slash.
+ * @param workspacePath - absolute Host workspace directory.
+ * @param filePath - absolute Host path inside it.
+ * @returns the path plus query string.
+ */
+export declare function fileUrl(fileRoute: string, workspacePath: string, filePath: string): string;
+/**
+ * Build the same-origin URL that proxies one absolute upstream URL.
+ * @param proxyRoute - the absolute proxy route path, no trailing slash.
+ * @param target - the loopback URL to fetch.
+ * @returns the path plus query string.
+ */
+export declare function proxyUrlFor(proxyRoute: string, target: string): string;
+/**
+ * Turn one absolute upstream URL into a same-origin frame URL when it is a loopback target.
+ *
+ * A cross-origin dev server is left exactly as it is: pointing the GUI's own proxy at a host it
+ * would refuse is not an improvement, and the panel says why the frame is opaque rather than
+ * silently refusing to show it.
+ * @param proxyRoute - the absolute proxy route path, no trailing slash.
+ * @param raw - the URL a person typed.
+ * @returns the frame URL, and whether it is same-origin with the GUI.
+ */
+export declare function frameUrlFor(proxyRoute: string, raw: string): {
+    src: string;
+    sameOrigin: boolean;
+};
+/**
+ * Insert a `<base>` element into an HTML document's head.
+ *
+ * String surgery rather than a parser on purpose: this runs on every HTML response, the document is
+ * untrusted, and the only structural fact needed — "where does the head begin" — is unambiguous in
+ * any HTML a browser will accept. The base goes immediately after the head's own opening tag, or
+ * immediately after `<html>` when there is no head, or at the very front when there is neither —
+ * which the parser then files into the implied head, where a base belongs.
+ *
+ * The global regex is what makes "no head" mean it: `indexOf('<head')` alone matches the substring
+ * inside `<header>`, and splicing a base into a `<header>` would leave the document resolving every
+ * relative URL against the wrong place.
+ * @param html - the document text, as bytes decoded by the caller.
+ * @param baseHref - the absolute same-origin prefix relative paths resolve against.
+ * @returns the document with the base element added.
+ */
+export declare function injectBase(html: string, baseHref: string): string;
+/**
+ * Whether a byte window looks like an HTML document that should get the base marker.
+ * @param contentType - the response's MIME type.
+ * @param bytes - the document's leading bytes.
+ * @returns true for an HTML response.
+ */
+export declare function isHtmlDocument(contentType: string, bytes: Uint8Array): boolean;
+/**
+ * Decode a byte window as UTF-8 for the base injection, preserving nothing it cannot decode.
+ *
+ * Non-fatal on purpose: an HTML file whose tail is cut mid-sequence is still a document worth
+ * rendering, and one replacement character is better than a 500.
+ * @param bytes - the window.
+ * @returns the decoded text.
+ */
+export declare function decodeText(bytes: Uint8Array): string;

package/types/host/preview-serve.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Same-origin preview serving: the Host routes that make a workspace file and a loopback dev server
+ * loadable *from the GUI's own origin*.
+ *
+ * This is the piece the whole agent-driven debugging story rests on. An `<iframe src="http://127.0.0.1:5173">`
+ * is cross-origin, and a cross-origin frame's `document` is unreachable — the panel cannot read its
+ * DOM, its console, or its box metrics, and neither can the model. Serving the same bytes from
+ * `/advanced-sidebar/preview-file?…` and proxying the dev server through
+ * `/advanced-sidebar/preview-proxy?url=…` makes the frame same-origin with the page that hosts it,
+ * so the panel's driver can inspect and drive it directly.
+ *
+ * Four deliberate refusals keep that power from becoming a hole in the GUI:
+ *
+ * 1. **Every route answers only the authenticated GUI.** Each HTTP route and the websocket upgrade
+ *    call the Host connection's `requestRejection` before anything else — the same gate `/api`, the
+ *    Typert websocket and the harness's own open-in-app routes use. It applies the Host/Origin fence
+ *    (a loopback or configured `trustedHosts` authority, no `Sec-Fetch-Site: cross-site`, an `Origin`
+ *    that matches the `Host` when present — which is what defeats DNS rebinding) and then verifies the
+ *    signed, authority-bound `dsh-auth-*` browser cookie. That cookie is `SameSite=Strict`, so the
+ *    panel's same-origin `<iframe src>`, its `fetch`, and the frame's own subresources all carry it,
+ *    while a page on any other site cannot. A Host whose connection exposes no such gate gets **no
+ *    routes at all**: these routes read files and relay to local ports, and an ungated copy of them is
+ *    a file server for every process and web page that can reach the port.
+ * 2. **The proxy only talks to loopback.** `validateProxyTarget` refuses every host that is not a
+ *    loopback literal, so this cannot fetch an intranet service from the operator's network
+ *    position. A URL that merely resolves to loopback is refused too — see that function. The GUI's
+ *    own `dsh-auth-*` cookie is removed from what is forwarded, so a dev server never receives a
+ *    credential for the harness, and cannot overwrite it either.
+ * 3. **A file is only ever read from inside a registered workspace.** The request names a workspace,
+ *    but that name is a claim: the file must also sit inside one of the workspaces the harness's own
+ *    `workspaceRegistry` holds, or it is refused. Without that, `?workspace=/` made the whole disk a
+ *    workspace. A Host with no registry serves no file.
+ * 4. **Containment is the filesystem's, not string arithmetic.** Every path goes through
+ *    `resolveWorkspace`/`resolveInside`, the same containment the Files panel uses, and a symlink
+ *    that escapes is caught by the filesystem's own canonicalization.
+ *
+ * Nothing here is cached. A dev server's own asset pipeline already handles its own caching; a
+ * workspace file is exactly the thing an operator edits and expects to see change, so the route
+ * answers `no-store` plus a weak validator and lets the panel decide when to reload.
+ * @module @achasoft/dsh-advanced-sidebar/host/preview-serve
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export { FILE_ROUTE, PROXY_ROUTE, SCRATCHPAD_ROUTE } from './preview-content.ts';
+import type { AdvancedSidebarSettings, PreviewFileInfoResult, PreviewSurfaceInfo } from './types.ts';
+/**
+ * Largest scratchpad document the Host will echo back.
+ *
+ * The scratchpad is a person typing HTML into a text area; a megabyte of it is a mistake or an
+ * attempt to make the Host hold memory, and neither is worth serving.
+ */
+export declare const SCRATCHPAD_MAX_BYTES: number;
+/**
+ * Serves workspace files and proxies loopback dev servers on the GUI's own origin.
+ *
+ * One instance is created by the service and disposed with it, which is what guarantees no route
+ * outlives the plugin: every registration returns a disposer, and `dispose()` runs them all.
+ */
+export declare class PreviewSurface {
+    private readonly ctx;
+    private readonly source;
+    /**
+     * The upstream URL each panel last pointed its frame at, keyed by its client id.
+     *
+     * Only a fallback: a proxied document's own URLs all carry their target explicitly, because the
+     * browser rewrites them from the injected `<base>`. What needs this map is a request the base
+     * cannot reach — a `fetch()` from inside the page to a relative path, or a link with no base of
+     * its own — and there is exactly one sensible target for those.
+     */
+    private readonly targets;
+    /** Every request currently in flight, so a dispose does not leave sockets open. */
+    private readonly live;
+    private closed;
+    /** Whether the routes are registered; see {@link RouteState}. */
+    private routes;
+    /**
+     * @param ctx - Host context carrying the optional filesystem capability.
+     * @param source - reads the current settings section; called per request.
+     */
+    constructor(ctx: Context, source: () => AdvancedSidebarSettings);
+    /**
+     * What this surface is, for `describe()`.
+     * @returns the route paths and whether the routes are actually mounted.
+     */
+    info(): PreviewSurfaceInfo;
+    /**
+     * The URL one workspace file is framed from, or undefined when this Host serves no routes.
+     * @param workspacePath - absolute Host workspace directory.
+     * @param filePath - absolute Host path inside it.
+     * @returns the same-origin path, query included.
+     */
+    fileUrl(workspacePath: string, filePath: string): string | undefined;
+    /**
+     * The same-origin URL that proxies one loopback URL.
+     * @param target - the loopback URL, already validated by the caller.
+     * @returns the same-origin path, query included.
+     */
+    proxyUrl(target: string): string;
+    /**
+     * Register every route with the mounted web server, each behind the connection's request gate.
+     *
+     * Registration goes through `ctx.inject(['connection', 'webServer'], …)` rather than a constructor
+     * read: a headless deployment composes neither, and the inject face simply never runs, leaving the
+     * rest of the plugin working. The connection is a hard requirement rather than an optional extra —
+     * it is the only thing that can tell the GUI's own browser from any other client of the port — so a
+     * connection without `requestRejection` mounts nothing and says so through {@link info}.
+     */
+    install(): void;
+    /** Forget every target and abort every in-flight request. Called from the plugin's teardown. */
+    dispose(): void;
+    /**
+     * Describe one workspace file for the panel, or refuse it.
+     * @param workspacePath - absolute Host workspace directory.
+     * @param path - absolute Host path, or a path relative to the workspace.
+     * @param signal - cancellation for the resolution and the metadata read.
+     * @returns the file's kind, size, frame URL, and change token.
+     */
+    info_(workspacePath: string | undefined, path: string, signal?: AbortSignal): Promise<PreviewFileInfoResult>;
+    /**
+     * Serve one workspace file as the frame's document or as one of its subresources.
+     * @param req - the incoming request.
+     * @param res - the response the handler owns.
+     */
+    private handleFile;
+    /**
+     * Serve text the panel posted, as an HTML document on this origin.
+     *
+     * The scratchpad renders as `text/html` rather than through `srcdoc` so that the frame's document
+     * has a real URL with this origin: `document.baseURI`, relative `fetch`, and `window.location` all
+     * then behave the way the page under test expects, and an agent's `eval` sees them.
+     * @param req - the incoming request.
+     * @param res - the response the handler owns.
+     */
+    private handleScratchpad;
+    /**
+     * Forward one request to a loopback upstream and stream the answer back.
+     * @param req - the incoming request.
+     * @param res - the response the handler owns.
+     */
+    private handleProxy;
+    /**
+     * Forward one upgraded connection to a loopback upstream.
+     *
+     * A dev server's live-reload socket is an optional convenience, not part of the inspection story:
+     * a websocket carries no DOM and no console, and a page whose socket never opens still renders and
+     * is still drivable. The tunnel is here because it is cheap — a raw `net` pipe with no protocol
+     * knowledge — but a server that negotiates on a path other than the route's own root is not
+     * tunnelled, because the web server's upgrade seat matches exact paths and claiming a wildcard
+     * would collide with the app's own sockets.
+     * @param req - the upgrade request.
+     * @param socket - the client socket the handler owns.
+     * @param head - bytes the parser already read past the request line.
+     */
+    private handleUpgrade;
+    /**
+     * One upstream request, with the response streamed straight through.
+     * @param req - the client request.
+     * @param res - the client response.
+     * @param upstreamUrl - the absolute loopback URL to fetch.
+     */
+    private forward;
+    /**
+     * Resolve a workspace and one path inside it.
+     * @param workspacePath - absolute Host workspace directory, absent to treat the path itself as one.
+     * @param path - absolute Host path, or a path relative to the workspace.
+     * @param signal - cancellation for the resolution.
+     * @returns the workspace, the contained target, and the path as it should be displayed.
+     */
+    private resolve;
+    /**
+     * Refuse a target that sits inside none of the harness's registered workspaces.
+     *
+     * The workspace a request names is only the root its relative paths hang from; it is not evidence
+     * that the directory is one the operator opened. `?workspace=/` would otherwise make the whole disk
+     * a workspace, so the canonical target is checked against the registry's own canonical paths — the
+     * list the sidebar shows, and nothing a request can add to. A subdirectory of a registered
+     * workspace passes, because the file is still inside what the operator opened.
+     *
+     * Each registered path is resolved through the same filesystem as the target, so a symlinked
+     * workspace compares as its real directory on both sides. A registered directory that no longer
+     * resolves (deleted, unmounted) simply contains nothing.
+     * @param target - the canonical target the request resolved to.
+     * @param path - the path as asked, for the refusal message.
+     * @param signal - cancellation for the resolutions.
+     * @returns the refusal, or undefined when a registered workspace contains the target.
+     */
+    private outsideRegisteredWorkspaces;
+    /**
+     * Describe one already-resolved file.
+     * @param workspace - the resolved workspace.
+     * @param target - the resolved target.
+     * @param display - the path to report back and to base the content type on.
+     * @param signal - cancellation for the metadata and token reads.
+     * @returns the description.
+     */
+    private describeFile;
+    /**
+     * A weak validator for one file: the backend's version, its size, and a digest of its head.
+     * @param target - the resolved target.
+     * @param version - the backend's opaque freshness token.
+     * @param size - the byte size; `undefined` asks for no probe read.
+     * @param reportedSize - the size the backend reported, which may be absent.
+     * @param signal - cancellation for the probe read.
+     * @returns the ETag body, quotes included.
+     */
+    private etag;
+    /**
+     * The target one subresource request should be forwarded to.
+     * @param req - the subresource request.
+     * @param suffix - the path below the proxy route, without a leading slash.
+     * @returns the validated target, or undefined when this Host holds none for the caller.
+     */
+    private fallbackTarget;
+    /**
+     * Record the target one panel is framing, so its subresources resolve.
+     * @param clientId - the panel's id.
+     * @param target - the upstream URL, or undefined when the panel stopped framing one.
+     */
+    rememberTarget(clientId: string, target: string | undefined): void;
+}
+/**
+ * A `Cookie` request header minus the harness's own browser-session cookie.
+ * @param header - the raw header; Node joins repeated `Cookie` headers into one string.
+ * @returns the remaining pairs, or undefined when nothing remains.
+ */
+export declare function withoutHostAuthCookies(header: string | readonly string[]): string | undefined;
+/** One byte range a request asked for. */
+interface Range {
+    /** First byte, inclusive. */
+    readonly start: number;
+    /** Last byte, inclusive. */
+    readonly end: number;
+}
+/**
+ * Parse one `Range` header against a known size.
+ *
+ * Only `bytes=` and only a single range are honoured: a multipart range costs a multipart encoder to
+ * serve, and the one caller that matters — a `<video>` scrubber — asks for one range at a time.
+ * @param header - the raw header value.
+ * @param size - the file's size in bytes.
+ * @returns the range, undefined for a full response, or `unsatisfiable`.
+ */
+export declare function parseRange(header: string | undefined, size: number): Range | undefined | 'unsatisfiable';

package/types/host/settings-section.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Attaching this plugin's settings section to the harness settings provider.
+ *
+ * Harness 0.1.1-rc.2 and earlier exported two free helpers from `@deepseek-ai/dsh-settings` for
+ * this, `installSettingsSection` and `settingsNamespace`. Current harnesses removed both: the same
+ * wiring is the provider's own `settings.installSection(owner, ns, schema, entry, hooks)`, reached
+ * through `ctx.inject(['settings'], …)`. Importing the old helpers by name fails to link on a
+ * current install, so the plugin carries these two small equivalents instead of depending on a
+ * compatibility shim that only exists on a development machine.
+ *
+ * Injecting `settings` rather than requiring it keeps the plugin loadable in a deployment that
+ * mounts no settings provider: the section simply never attaches, and the composition entry the
+ * plugin was configured with stays the source.
+ * @module @achasoft/dsh-advanced-sidebar/host/settings-section
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type z from '@deepseek-ai/schemastery';
+/** What a consumer hands the provider, as the installed harness defines it. */
+export interface SettingsSectionHooks<T> {
+    /**
+     * Receive the active configuration source: the resolved settings scope while one is attached,
+     * the composition entry otherwise.
+     * @param current - thunk returning the currently authoritative value.
+     */
+    setSource: (current: () => T) => void;
+    /** Re-judge anything derived from the source after an attach, a detach, or a committed change. */
+    onChange: () => void;
+    /**
+     * Reject a resolved section the plugin could not act on, for constraints its schema cannot express.
+     * @param value - the resolved section.
+     */
+    validate?: (value: T) => void;
+}
+/**
+ * Check a settings namespace against the provider's grammar, failing at load rather than at attach.
+ * @param value - the namespace.
+ * @returns the same namespace.
+ * @throws TypeError when it is not a lowercase hyphenated identifier.
+ */
+export declare function settingsNamespace<const N extends string>(value: N): N;
+/**
+ * Attach one settings section whenever a settings provider is present.
+ * @param ctx - the owning plugin context; its unload detaches the section.
+ * @param ns - the plugin's settings namespace.
+ * @param schema - schema resolving the section.
+ * @param entry - the composition entry, used as the base layer and as the fallback without a provider.
+ * @param hooks - source sink, change notification, and optional validation.
+ */
+export declare function installSettingsSection<T>(ctx: Context, ns: string, schema: z<T>, entry: T, hooks: SettingsSectionHooks<T>): void;