dsh-better-sidebar 0.10.0

package/src/client/browser.ts

@@ -0,0 +1,119 @@
+/**
+ * Pure URL policy for the built-in browser tab: normalize user input into
+ * an http(s) URL, and refuse destinations that would be dangerous to embed
+ * in the sidebar iframe. Kept dependency-free so it is unit-testable.
+ *
+ * The iframe sandbox (opaque origin, no allow-same-origin / top-navigation)
+ * is the primary security boundary; this module is the address-bar gate on
+ * top of it: only http/https may be navigated, and loopback addresses are
+ * refused so a browsed page cannot probe local services by user action.
+ * The GUI's OWN origin is explicitly ALLOWED — the user may open the GUI
+ * itself in the sidebar (debugging, mirroring); the sandbox still renders
+ * it in an opaque origin with no same-origin privileges, exactly like any
+ * other site.
+ */
+
+/** Why a navigation attempt was refused. */
+export type BrowserBlockReason = 'scheme' | 'loopback'
+
+/** Result of normalizing one address-bar input. */
+export type BrowserNavigateResult =
+  | { kind: 'ok'; url: string }
+  | { kind: 'blocked'; reason: BrowserBlockReason }
+  | { kind: 'invalid' }
+
+/** One browser.probe wire result (host fetch of the target's headers). */
+export interface BrowserProbeResult {
+  reachable: boolean
+  /** The final (post-redirect) URL; present when reachable. */
+  url?: string
+  status?: number
+  xFrameOptions?: string
+  /** The CSP frame-ancestors source list; present when the directive exists. */
+  frameAncestors?: string[]
+}
+
+/** Embeddability verdict of one probe. */
+export type Embeddability = 'embeddable' | 'blocked' | 'unknown'
+
+/**
+ * Decide whether a site can render inside the sidebar iframe. The signals
+ * are exactly the ones the BROWSER enforces when it refuses an iframe load:
+ * X-Frame-Options DENY/SAMEORIGIN, or a frame-ancestors directive that does
+ * not allow `*` ('self' here means the SITE's own origin — never ours, so
+ * it also blocks the sidebar). A site we could not reach yields 'unknown'
+ * and the plain iframe stays.
+ */
+export function embeddabilityOf(probe: BrowserProbeResult): Embeddability {
+  if (probe.reachable !== true) return 'unknown'
+  const xfo = probe.xFrameOptions?.trim().toUpperCase()
+  if (xfo === 'DENY' || xfo === 'SAMEORIGIN') return 'blocked'
+  if (probe.frameAncestors !== undefined && !probe.frameAncestors.some(source => source === '*')) return 'blocked'
+  return 'embeddable'
+}
+
+/** A loopback hostname (localhost, IPv6 ::1, 127.0.0.0/8, 0.0.0.0). */
+export function isLoopbackHostname(hostname: string): boolean {
+  const host = hostname.replace(/^\[|\]$/g, '').toLowerCase()
+  if (host === 'localhost' || host === '::1' || host === '0.0.0.0') return true
+  const parts = host.split('.')
+  return parts.length === 4
+    && parts[0] === '127'
+    && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+}
+
+/**
+ * Normalize one address-bar input against the navigation policy.
+ * @param input - raw user text.
+ * @param selfOrigin - the GUI's own origin (window.location.origin). The GUI
+ * itself may be browsed in the sidebar (the sandbox keeps it opaque), so it
+ * is let through BEFORE the loopback check — its host is normally loopback.
+ */
+/** Schemes that must never reach the iframe, even without `//` (javascript:,
+ *  data:, file:, ...). Host:port lookalikes (example.com:8080) are NOT here —
+ *  they parse as hosts below. */
+const FORBIDDEN_SCHEMES = new Set([
+  'javascript', 'data', 'file', 'about', 'vbscript', 'blob',
+  'mailto', 'tel', 'ftp', 'ftps', 'ws', 'wss', 'sftp', 'ssh',
+  'chrome', 'chrome-extension', 'moz-extension', 'edge', 'opera', 'resource', 'view-source',
+])
+
+export function normalizeBrowserUrl(input: string, selfOrigin: string): BrowserNavigateResult {
+  const trimmed = input.trim()
+  if (trimmed === '') return { kind: 'invalid' }
+  // Distinguish an explicit scheme from a bare host:port. "example.com:8080"
+  // would match a naive scheme regex (dots are legal in schemes), so a
+  // scheme prefix is only honored when it is http(s) or a known-forbidden
+  // scheme; anything else is treated as a host and gets https://.
+  const schemeMatch = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(trimmed)
+  let withScheme: string
+  if (schemeMatch === null) {
+    withScheme = `https://${trimmed}`
+  } else {
+    const scheme = schemeMatch[1]!.toLowerCase()
+    if (scheme === 'http' || scheme === 'https') withScheme = trimmed
+    else if (FORBIDDEN_SCHEMES.has(scheme)) return { kind: 'blocked', reason: 'scheme' }
+    else withScheme = `https://${trimmed}`
+  }
+  let url: URL
+  try {
+    url = new URL(withScheme)
+  } catch {
+    return { kind: 'invalid' }
+  }
+  // The protocol backstop: any URL that still parses to a non-http(s)
+  // scheme (e.g. ftp://, ws:// — which carry `//` and skip the list) is
+  // refused here.
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return { kind: 'blocked', reason: 'scheme' }
+  // The GUI's own origin is ALLOWED (the user may browse the GUI itself in
+  // the sidebar; the sandbox renders it in an opaque origin like any other
+  // site). It must be checked before the loopback gate because its host is
+  // normally loopback.
+  try {
+    if (url.origin === new URL(selfOrigin).origin) return { kind: 'ok', url: url.href }
+  } catch {
+    // Unparsable selfOrigin (never in practice): fall through to the loopback gate.
+  }
+  if (isLoopbackHostname(url.hostname)) return { kind: 'blocked', reason: 'loopback' }
+  return { kind: 'ok', url: url.href }
+}

package/src/client/builtins/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Built-in registration: the plugin registers its own tab pages and file
+ * previewers through the same {@link BetterSidebarService} external plugins
+ * use — eating its own dogfood. The descriptors live next to their feature
+ * modules (tabs.tsx / viewers.tsx); this module only aggregates them and
+ * owns the disposer lifecycle (cordis auto-invokes it on fiber disposal,
+ * HMR-safe).
+ */
+import type { Context } from '../../context-types.ts'
+import type { BetterSidebarService } from '../service.ts'
+import { builtinTabs } from './tabs.tsx'
+import { builtinViewers } from './viewers.tsx'
+
+/**
+ * Register all built-in tabs and viewers with the service. Returns a
+ * disposer that unregisters everything (cordis auto-invokes it on fiber
+ * disposal). The `ctx` is threaded into tab descriptors that need it
+ * (EditorHost reads `ctx.betterSidebar` for file-viewer matching).
+ */
+export function registerBuiltins(ctx: Context, service: BetterSidebarService): () => void {
+  const disposers: (() => void)[] = []
+  for (const tab of builtinTabs(ctx)) {
+    disposers.push(service.registerTab(tab))
+  }
+  for (const viewer of builtinViewers()) {
+    disposers.push(service.registerFileViewer(viewer))
+  }
+  return () => {
+    for (const d of disposers) {
+      try { d() } catch { /* already disposed */ }
+    }
+  }
+}

package/src/client/builtins/tabs.tsx

@@ -0,0 +1,211 @@
+/**
+ * The 7 built-in tab descriptors: the plugin registers its own pages
+ * (explorer / git / terminal / browser / subagent / editor / diff) through
+ * the same {@link BetterSidebarService} external plugins use — eating its
+ * own dogfood. The terminal descriptor owns its quota (`TERMINAL_LIMIT`)
+ * and mints `terminal:<n>` ids through `createTab`; the browser mints
+ * `browser:<n>` the same way (no quota).
+ */
+import { IconBranchOutline16, IconCodeOutline16, IconFolderOpen16, IconThinkOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { Context } from '../../context-types.ts'
+import { allLeaves, isAgentTabId, type SidebarState } from '../state.ts'
+import { t } from '../locales.ts'
+import { openSidebarFile } from '../intercept.tsx'
+import { ExplorerView } from '../ExplorerView.tsx'
+import { EditorHost } from '../EditorHost.tsx'
+import { lazyChunkComponent } from '../lazy-chunk.tsx'
+import { GitView } from '../GitView.tsx'
+import { DiffTab } from '../DiffTab.tsx'
+import { SubagentView } from '../SubagentView.tsx'
+import { BrowserView } from '../BrowserView.tsx'
+import { IconTerminalOutline16, IconDiffOutline16, IconGlobeOutline16 } from '../icons.tsx'
+import type { ComponentType } from 'react'
+import type { SessionScope } from '../api.ts'
+import type { SidebarStore } from '../state.ts'
+import type { TabDescriptor } from '../service.ts'
+
+/**
+ * Lazy wrapper over the terminal view: xterm (and its stylesheet) is fetched
+ * only when a terminal tab is first opened (see chunk-loader.ts). The
+ * wrapper keeps the descriptor contract `(props) => ReactNode` — Sidebar
+ * calls it as a plain function.
+ *
+ * TerminalView's props are { scope, tabId, store } — `tabId` is NOT part of
+ * TabComponentProps (it carries `tab: SidebarTab` instead), so the
+ * descriptor maps it explicitly; a bare pass-through would leave tabId
+ * undefined and TerminalView's isAgentTabId(tabId) would crash on
+ * `undefined.startsWith` (regression-pinned in tests/lazy-chunk.spec.tsx).
+ */
+const LazyTerminal = lazyChunkComponent<TerminalViewProps>(
+  'terminal',
+  (mod) => mod.TerminalView as ComponentType<TerminalViewProps> | undefined,
+)
+
+/** The terminal view's props (mirror of TerminalView's own signature). */
+interface TerminalViewProps {
+  scope: SessionScope
+  tabId: string
+  store: SidebarStore
+}
+
+/** How many UI-owned terminals may be open at once (agent-owned ones are uncapped). */
+export const TERMINAL_LIMIT = 3
+
+/** Count UI-owned terminals (agent:` tabs excluded — they are the model's). */
+function uiTerminalCount(state: SidebarState): number {
+  return allLeaves(state.splits)
+    .flatMap(leaf => leaf.tabs)
+    .filter(tab => tab.type === 'terminal' && !isAgentTabId(tab.id)).length
+}
+
+/** The 7 built-in tab descriptors. */
+export function builtinTabs(ctx: Context): readonly TabDescriptor[] {
+  return [
+    {
+      id: 'editor',
+      title: () => t('editor'),
+      icon: (size: number) => <IconCodeOutline16 size={size} />,
+      order: -1,
+      hidden: true,
+      dedupeKey: (tab) => tab.path,
+      component: ({ ctx, store, scope, tab }) => (
+        <EditorHost ctx={ctx} store={store} scope={scope} path={tab.path ?? ''} title={tab.title} />
+      ),
+    },
+    {
+      id: 'explorer',
+      title: () => t('explorer'),
+      icon: (size: number) => <IconFolderOpen16 size={size} />,
+      order: 10,
+      single: true,
+      component: ({ ctx, store, scope, expanded, onToggleDir, onReferenceFile }) => (
+        <ExplorerView
+          sessionId={scope.sessionId}
+          cwd={scope.cwd}
+          expanded={expanded ?? []}
+          onToggle={onToggleDir ?? (() => { /* no-op */ })}
+          onOpenFile={(path) => { openSidebarFile(ctx, store, scope.sessionId, path) }}
+          onReferenceFile={onReferenceFile ?? (() => { /* no-op */ })}
+        />
+      ),
+    },
+    {
+      id: 'git',
+      title: () => t('git'),
+      icon: (size: number) => <IconBranchOutline16 size={size} />,
+      order: 20,
+      single: true,
+      component: ({ ctx, store, scope, onOpenDiff }) => (
+        <GitView
+          scope={scope}
+          onOpenFile={(path) => { openSidebarFile(ctx, store, scope.sessionId, path) }}
+          onOpenDiff={onOpenDiff ?? (() => { /* no-op */ })}
+        />
+      ),
+    },
+    {
+      id: 'subagent',
+      title: () => t('subagent'),
+      icon: (size: number) => <IconThinkOutline16 size={size} />,
+      order: 30,
+      single: true,
+      // Declarative settings: the auto-open switches render under this row in
+      // the Side card settings page (the Jobs page's own related settings).
+      settings: {
+        toggles: [{
+          key: 'autoOpenSubagent',
+          title: () => t('settingsSubagentTitle'),
+          desc: () => t('settingsSubagentDesc'),
+        }, {
+          key: 'autoOpenJobs',
+          title: () => t('settingsJobsTitle'),
+          desc: () => t('settingsJobsDesc'),
+        }],
+      },
+      component: ({ ctx, scope, visible, onSubagentJump }) => (
+        <SubagentView
+          sessionId={scope.sessionId}
+          ctx={ctx}
+          active={visible}
+          onOpenChild={(address) => { onSubagentJump?.(address.childSessionId) }}
+        />
+      ),
+    },
+    {
+      id: 'terminal',
+      title: () => t('terminal'),
+      icon: (size: number) => <IconTerminalOutline16 size={size} />,
+      order: 40,
+      available: (_ctx, _scope, state) => uiTerminalCount(state) < TERMINAL_LIMIT,
+      // Declarative settings: the model-facing terminal tools switch and the
+      // bottom-panel first-expansion auto-terminal switch render under this
+      // row in the Side card settings page (the Terminal page's own related
+      // settings; the host gates the toolset on the tools one independently).
+      settings: {
+        toggles: [{
+          key: 'agentTerminalTools',
+          title: () => t('settingsToolsTitle'),
+          desc: () => t('settingsToolsDesc'),
+        }, {
+          key: 'bottomPanelAutoTerminal',
+          title: () => t('settingsBottomTerminalTitle'),
+          desc: () => t('settingsBottomTerminalDesc'),
+        }],
+      },
+      createTab: (state) => {
+        const count = uiTerminalCount(state)
+        if (count >= TERMINAL_LIMIT) return null
+        return {
+          tab: {
+            id: `terminal:${state.nextTerminal}`,
+            type: 'terminal',
+            title: `${t('terminal')} ${state.nextTerminal}`,
+          },
+          patch: { nextTerminal: state.nextTerminal + 1 },
+        }
+      },
+      component: ({ tab, scope, store }) => <LazyTerminal scope={scope} store={store} tabId={tab.id} />,
+    },
+    {
+      id: 'browser',
+      title: () => t('browser'),
+      icon: (size: number) => <IconGlobeOutline16 size={size} />,
+      order: 50,
+      // Declarative settings: the sandbox escape hatch and the link
+      // takeover render under this tab's row in the Side card settings
+      // page (the sandbox one is warned on).
+      settings: {
+        toggles: [{
+          key: 'browserNoSandbox',
+          title: () => t('settingsBrowserSandboxTitle'),
+          desc: () => t('settingsBrowserSandboxDesc'),
+        }, {
+          key: 'browserInterceptLinks',
+          title: () => t('settingsBrowserLinksTitle'),
+          desc: () => t('settingsBrowserLinksDesc'),
+        }],
+      },
+      createTab: (state) => ({
+        tab: {
+          id: `browser:${state.nextBrowser}`,
+          type: 'browser',
+          title: t('browser'),
+        },
+        patch: { nextBrowser: state.nextBrowser + 1 },
+      }),
+      component: (props) => <BrowserView {...props} />,
+    },
+    {
+      id: 'diff',
+      title: () => t('git'),
+      icon: (size: number) => <IconDiffOutline16 size={size} />,
+      order: -1,
+      hidden: true,
+      dedupeKey: (tab) => tab.id,
+      component: ({ scope, tab }) => (
+        tab.diff === undefined ? null
+          : <DiffTab sessionId={scope.sessionId} cwd={scope.cwd} diff={tab.diff} />
+      ),
+    },
+  ]
+}

package/src/client/builtins/viewers.tsx

@@ -0,0 +1,151 @@
+/**
+ * The 9 built-in file viewer descriptors: every preview surface is a
+ * registered viewer (image / pdf / docx / xlsx / pptx / markdown / html /
+ * code / binary-download), exactly like external plugins register theirs.
+ * The `binary-download` viewer sniffs NUL bytes via `detect` for unknown
+ * binaries and serves doc/xls/ppt by extension; `code` is the catch-all
+ * (`exts: []`, lowest priority) that claims any file no other viewer did.
+ *
+ * The heavy viewers (docx/xlsx/pptx and the CodeMirror-backed
+ * markdown/html/code) render through {@link lazyChunkComponent} wrappers —
+ * their libraries are fetched only when such a file is first opened (see
+ * chunk-loader.ts). The descriptor metadata (id/exts/priority/detect) is
+ * identical either way, so matching semantics and external-plugin
+ * overrides are unaffected; the `component` wrapper keeps the descriptor
+ * contract `(props) => ReactNode`.
+ *
+ * Every viewer carries the declarative settings-surface fields — `title`
+ * and `icon` — so the Side card settings page can render the enable/disable
+ * inventory without hardcoding (eating our own dogfood).
+ */
+import { IconCodeOutline16, IconDownloadOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
+import { lazyChunkComponent } from '../lazy-chunk.tsx'
+import { PdfView } from '../PdfView.tsx'
+import { BinaryDownload } from '../binary-download.tsx'
+import {
+  IconImageOutline16,
+  IconMarkdownOutline16,
+  IconPdfOutline16,
+  IconDocxOutline16,
+  IconXlsxOutline16,
+  IconPptxOutline16,
+  IconHtmlOutline16,
+} from '../icons.tsx'
+import type { ComponentType } from 'react'
+import type { FileViewerDescriptor, FileViewerProps } from '../service.ts'
+import { t } from '../locales.ts'
+import css from '../sidebar.module.css'
+
+/**
+ * Lazy wrappers over the chunk-resident viewer components. The `pick`
+ * functions are module-level (stable identity — the wrapper effect depends
+ * on them); the cast bridges the chunk exports record to the descriptor
+ * prop shape (the views read only their own subset of FileViewerProps).
+ */
+const LazyDocx = lazyChunkComponent<FileViewerProps>('docx', (mod) => mod.DocxView as ComponentType<FileViewerProps> | undefined)
+const LazyXlsx = lazyChunkComponent<FileViewerProps>('xlsx', (mod) => mod.XlsxView as ComponentType<FileViewerProps> | undefined)
+const LazyPptx = lazyChunkComponent<FileViewerProps>('pptx', (mod) => mod.PptxView as ComponentType<FileViewerProps> | undefined)
+const LazyTextEditor = lazyChunkComponent<FileViewerProps>('editor', (mod) => mod.TextEditor as ComponentType<FileViewerProps> | undefined)
+
+/** The 9 built-in file viewer descriptors. */
+export function builtinViewers(): readonly FileViewerDescriptor[] {
+  return [
+    {
+      id: 'image',
+      title: () => t('viewerImage'),
+      icon: (size: number) => <IconImageOutline16 size={size} />,
+      exts: ['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg', 'bmp', 'ico', 'avif'],
+      fetchStrategy: 'mediaUrl',
+      component: ({ mediaUrl: url, title }) => (
+        <div className={css.editorImageWrap}>
+          <img className={css.editorImage} src={url} alt={title} />
+        </div>
+      ),
+    },
+    {
+      id: 'pdf',
+      title: () => t('viewerPdf'),
+      icon: (size: number) => <IconPdfOutline16 size={size} />,
+      exts: ['pdf'],
+      fetchStrategy: 'mediaUrl',
+      component: ({ scope, path, title }) => (
+        <PdfView scope={scope} path={path} title={title} />
+      ),
+    },
+    {
+      id: 'docx',
+      title: () => t('viewerDocx'),
+      icon: (size: number) => <IconDocxOutline16 size={size} />,
+      exts: ['docx'],
+      fetchStrategy: 'mediaUrl',
+      component: (props) => <LazyDocx {...props} />,
+    },
+    {
+      id: 'xlsx',
+      title: () => t('viewerXlsx'),
+      icon: (size: number) => <IconXlsxOutline16 size={size} />,
+      exts: ['xlsx'],
+      fetchStrategy: 'mediaUrl',
+      component: (props) => <LazyXlsx {...props} />,
+    },
+    {
+      id: 'pptx',
+      title: () => t('viewerPptx'),
+      icon: (size: number) => <IconPptxOutline16 size={size} />,
+      exts: ['pptx'],
+      fetchStrategy: 'mediaUrl',
+      component: (props) => <LazyPptx {...props} />,
+    },
+    {
+      id: 'markdown',
+      title: () => t('viewerMarkdown'),
+      icon: (size: number) => <IconMarkdownOutline16 size={size} />,
+      exts: ['md', 'markdown'],
+      fetchStrategy: 'fsRead',
+      component: (props) => <LazyTextEditor {...props} />,
+    },
+    {
+      id: 'html',
+      title: () => t('viewerHtml'),
+      icon: (size: number) => <IconHtmlOutline16 size={size} />,
+      exts: ['html', 'htm'],
+      fetchStrategy: 'fsRead',
+      // Declarative settings: the sandbox escape hatch and the default-unsafe
+      // start state render under this viewer's row in the Side card settings
+      // page (both warned on).
+      settings: {
+        toggles: [{
+          key: 'htmlViewerNoSandbox',
+          title: () => t('settingsHtmlSandboxTitle'),
+          desc: () => t('settingsHtmlSandboxDesc'),
+        }, {
+          key: 'htmlViewerDefaultUnsafe',
+          title: () => t('settingsHtmlDefaultUnsafeTitle'),
+          desc: () => t('settingsHtmlDefaultUnsafeDesc'),
+        }],
+      },
+      component: (props) => <LazyTextEditor {...props} />,
+    },
+    {
+      id: 'code',
+      title: () => t('viewerCode'),
+      icon: (size: number) => <IconCodeOutline16 size={size} />,
+      exts: [],
+      priority: -100,
+      fetchStrategy: 'fsRead',
+      component: (props) => <LazyTextEditor {...props} />,
+    },
+    {
+      id: 'binary-download',
+      title: () => t('viewerBinary'),
+      icon: (size: number) => <IconDownloadOutline16 size={size} />,
+      exts: ['doc', 'xls', 'ppt'],
+      priority: -50,
+      fetchStrategy: 'binary-download',
+      // NUL probe: a file whose head bytes contain a NUL is binary — claimed
+      // before the catch-all code viewer on the head re-match.
+      detect: (_path, head) => head.includes(0),
+      component: ({ scope, path }) => <BinaryDownload scope={scope} path={path} />,
+    },
+  ]
+}