@young1lin/dsh-ui-gitworkbench 0.1.0

package/src/style-store.ts

@@ -0,0 +1,144 @@
+/**
+ * Per-project and global drawer styling: a background image and custom CSS.
+ *
+ * These live on the host rather than in the browser for two reasons. A project
+ * setting belongs to the project, so it must survive a different browser or a
+ * cleared origin; and a background image is far larger than a localStorage
+ * origin quota is willing to hold.
+ *
+ * The file is a durable boundary: everything read back is validated here, and
+ * anything unrecognized is dropped rather than propagated. The image in
+ * particular is interpolated into a CSS `url()` by the client, so it is held to
+ * a base64 `data:` URL with no character that could close the function and
+ * continue the stylesheet.
+ */
+import { join } from 'node:path'
+
+/** One scope's styling. Absent fields are impossible: every entry is complete. */
+export interface StyleEntry {
+  /** Custom CSS injected into the page verbatim; empty for none. */
+  readonly css: string
+  /** Background image as a base64 `data:` URL; empty for none. */
+  readonly image: string
+  /** Background blur radius in px. */
+  readonly blur: number
+  /** How much of the palette's own surface colour covers the image, in percent. */
+  readonly veil: number
+}
+
+export interface StyleFile {
+  readonly v: 1
+  readonly global: StyleEntry
+  /** Keyed by repository root, forward-slashed. */
+  readonly projects: Record<string, StyleEntry>
+}
+
+/** No image, no CSS, and the defaults the sliders open on. */
+export const DEFAULT_STYLE: StyleEntry = { css: '', image: '', blur: 18, veil: 78 }
+
+/** Largest accepted image data URL. A 2560px JPEG lands far below this; the cap
+ *  exists so a hand-edited file cannot make every drawer open drag megabytes. */
+export const STYLE_IMAGE_MAX = 3_000_000
+
+/** Largest accepted custom stylesheet. */
+export const STYLE_CSS_MAX = 200_000
+
+/** Largest accepted blur radius, in px. */
+export const STYLE_BLUR_MAX = 60
+
+/**
+ * Images this plugin will render.
+ *
+ * Deliberately narrow: the client interpolates the value into `url("…")`, and a
+ * base64 alphabet cannot contain a quote, a parenthesis, a backslash or a
+ * semicolon, so a stored value can never close the function and append rules of
+ * its own. It is also exactly what a canvas `toDataURL` produces, so nothing a
+ * user can select through the picker is rejected.
+ */
+const IMAGE_PATTERN = /^data:image\/(?:png|jpeg|webp|gif|avif);base64,[A-Za-z0-9+/]+={0,2}$/
+
+/**
+ * @param home - the user's home directory.
+ * @returns the style file's path, forward-slashed.
+ */
+export function stylePath(home: string): string {
+  return join(home, '.dsh', 'gitworkbench-style.json').replace(/\\/g, '/')
+}
+
+/**
+ * @param value - a number from a file or an RPC argument.
+ * @param min - lower bound.
+ * @param max - upper bound.
+ * @param fallback - used when the value is not a finite number.
+ * @returns the value clamped into range.
+ */
+function clampNumber(value: unknown, min: number, max: number, fallback: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback
+  return Math.min(Math.max(value, min), max)
+}
+
+/**
+ * Narrow an arbitrary value to a complete, in-range style entry.
+ * @param value - parsed JSON or an RPC argument.
+ * @returns a valid entry; every rejected field falls back to its default.
+ */
+export function sanitizeEntry(value: unknown): StyleEntry {
+  if (typeof value !== 'object' || value === null) return DEFAULT_STYLE
+  const record = value as Record<string, unknown>
+  const css = typeof record['css'] === 'string' && record['css'].length <= STYLE_CSS_MAX ? record['css'] : ''
+  const raw = record['image']
+  const image = typeof raw === 'string' && raw.length <= STYLE_IMAGE_MAX && IMAGE_PATTERN.test(raw) ? raw : ''
+  return {
+    css,
+    image,
+    blur: clampNumber(record['blur'], 0, STYLE_BLUR_MAX, DEFAULT_STYLE.blur),
+    veil: clampNumber(record['veil'], 0, 100, DEFAULT_STYLE.veil),
+  }
+}
+
+/**
+ * @returns a style file with nothing configured.
+ */
+export function emptyStyleFile(): StyleFile {
+  return { v: 1, global: DEFAULT_STYLE, projects: {} }
+}
+
+/**
+ * @param entry - a style entry.
+ * @returns whether it configures anything at all; an entry that does not is not
+ *   worth storing, and storing it would shadow the global scope with nothing.
+ */
+export function isBlankEntry(entry: StyleEntry): boolean {
+  return entry.css.length === 0 && entry.image.length === 0
+}
+
+/**
+ * Parse the style file, dropping anything malformed.
+ * @param raw - the file's text.
+ * @returns a valid style file; a corrupt one reads as empty rather than failing.
+ */
+export function parseStyle(raw: string): StyleFile {
+  try {
+    const parsed = JSON.parse(raw) as { v?: unknown; global?: unknown; projects?: unknown }
+    if (parsed?.v !== 1) return emptyStyleFile()
+    const projects: Record<string, StyleEntry> = {}
+    if (typeof parsed.projects === 'object' && parsed.projects !== null) {
+      for (const [root, entry] of Object.entries(parsed.projects as Record<string, unknown>)) {
+        if (root.length > 0) projects[root] = sanitizeEntry(entry)
+      }
+    }
+    return { v: 1, global: sanitizeEntry(parsed.global), projects }
+  } catch {
+    // A half-written or hand-edited file must not take the drawer down with it.
+    return emptyStyleFile()
+  }
+}
+
+/**
+ * @param readText - reads a file's text.
+ * @param path - the style file's path.
+ * @returns the stored styles, or an empty file when absent or unreadable.
+ */
+export async function loadStyle(readText: (path: string) => Promise<string>, path: string): Promise<StyleFile> {
+  try { return parseStyle(await readText(path)) } catch { return emptyStyleFile() }
+}

package/src/types/dsh-client-shim.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Ambient shims for the CLIENT half, so `tsc` can check it WITHOUT
+ * `@deepseek-ai/dsh-client-runtime` and `@deepseek-ai/dsh-client-ui-slots`
+ * installed — they are peer dependencies resolved from the web profile's module
+ * farm at runtime, and this repository never installs them.
+ *
+ * WHAT THIS IS FOR: catching mistakes in THIS plugin's own code — a stale
+ * identifier after a refactor, a prop that no longer exists, a missing field, a
+ * type that does not line up. Before it existed the client half was never
+ * typechecked at all: `tsconfig.json` includes only the host entry, and tsdown
+ * builds with `dts: false` while rolldown does no checking.
+ *
+ * WHAT THIS IS NOT: a copy of the harness's types. Everything at the dsh
+ * boundary below is deliberately loose, so it can confirm a call is shaped
+ * roughly right but never that it matches the real signature. The authority is
+ * the harness monorepo, and a green check here does NOT prove this plugin still
+ * fits the host it mounts into — only running it does. Widen a declaration when
+ * it blocks correct code; never narrow one to encode a guess.
+ */
+
+declare module '*.module.css' {
+  /** CSS-module class map; the build inlines the stylesheet and exports this. */
+  const classes: Record<string, string>
+  export default classes
+}
+
+/** Host frozen table supplies this at runtime; only `createPortal` is used here. */
+declare module 'react-dom' {
+  import type { ReactNode } from 'react'
+  export function createPortal(children: ReactNode, container: Element | DocumentFragment): ReactNode
+}
+
+/** Bare specifier imported for load ordering only; it contributes no types here. */
+declare module '@deepseek-ai/dsh-client-runtime' {}
+
+declare module '@deepseek-ai/dsh-client-runtime/client' {
+  /** One slot contribution, as `ctx.slots.register` accepts it. */
+  export interface SlotRegistration {
+    /** Slot to contribute to. */
+    readonly name: string
+    /** Identity of this contribution within the slot. */
+    readonly id: string
+    /** Sort key among the slot's entries. */
+    readonly order?: number
+    /**
+     * Locale namespace. Declaring it makes the framework synthesize the `t` prop;
+     * this plugin's namespace is outside dsh's typed map, so the component
+     * declares `t` itself rather than receiving a checked type here.
+     */
+    readonly locale?: string
+    /** Business callbacks handed to the component as props. */
+    readonly inject?: () => Record<string, unknown>
+  }
+
+  /** The client-side plugin context an `apply` receives. */
+  export interface ClientContext {
+    /**
+     * Register a contribution as a disposable effect.
+     * @param apply - performs the registration and returns its disposer.
+     * @param label - diagnostic name for the effect.
+     * @returns a disposer for the effect itself.
+     */
+    effect(apply: () => (() => void) | void, label?: string): () => void
+    slots: {
+      /**
+       * Run `apply` once the named slot exists.
+       * @param name - slot being contributed to.
+       * @param apply - performs the registration.
+       */
+      inject(name: string, apply: () => void): void
+      /**
+       * Contribute one component to a slot.
+       * @param registration - slot, identity, ordering, locale and injected props.
+       * @param component - the component rendered for this entry.
+       * @returns the disposer.
+       */
+      register(registration: SlotRegistration, component: unknown): () => void
+    }
+  }
+}
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  /**
+   * Props every slot component receives from the runtime.
+   *
+   * The real type is keyed on the slot name; this approximation carries only the
+   * members this plugin reads, which is what lets its own usage be checked.
+   */
+  export interface PropsRuntime<N extends string = string> {
+    /** Session this header belongs to. */
+    readonly sessionId: string
+    /**
+     * Subscribe to a slice of the sessions store. The store's type lives in the
+     * harness, so the selector's parameter is annotated at each call site.
+     * @param selector - picks the slice to subscribe to.
+     * @returns the selected slice.
+     */
+    readonly useSessions: <T>(selector: (state: never) => T) => T
+  }
+}

package/src/types/dsh-shim.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Ambient shims so `tsc` can transpile the host half WITHOUT the @deepseek-ai
+ * packages installed locally — they resolve from the web profile's module farm
+ * at runtime. Types here are intentionally loose (strict is off); they exist
+ * only to let the decorator transform and emit. The real types live in the
+ * harness monorepo and govern behaviour once loaded in-profile.
+ */
+
+declare module '@deepseek-ai/cordis' {
+  export interface Context {
+    tools: {
+      /** ToolRuntime.register — returns the dispose callback; loose here, see file header. */
+      register(definition: unknown): () => void
+    }
+    /**
+     * SystemPrompt registry. Only `context()` is mirrored — the dynamic
+     * per-assembly contribution, whose `text` provider is SYNCHRONOUS (see the
+     * real `PromptContext` in packages/core/system-prompt/src/index.ts). The
+     * `agent` field on the assemble context is merged in by `dsh-agent`.
+     */
+    systemPrompt: {
+      context(input: {
+        name: string
+        order: number
+        text: (context: { agent?: { session: { id: string } } }) => string
+      }): () => void
+    }
+    /** Mount a child scope once the named services are available; loose here, see file header. */
+    inject(services: readonly string[], apply: (scope: Context) => void): void
+    subprocess: {
+      spawn(spec: {
+        argv: readonly string[]
+        cwd: string
+        stdio: { stdin: unknown; stdout: 'pipe'; stderr: 'pipe' }
+        graceMs: number
+        signal?: AbortSignal
+        /** Merged onto the implementation's scrubbed base environment. */
+        env?: Record<string, string> | undefined
+      }): {
+        stdout: import('node:stream').Readable | undefined
+        stderr: import('node:stream').Readable | undefined
+        done: Promise<{ exitCode: number | null; signal: string | null }>
+      }
+    }
+  }
+  export class Service<T = never> {
+    constructor(ctx: Context, name: string)
+    readonly ctx: Context
+  }
+}
+
+declare module '@deepseek-ai/dsh-typert-protocol' {
+  import type { Service, Context } from '@deepseek-ai/cordis'
+  type Stage3MethodDecorator = (value: Function, context: ClassMethodDecoratorContext) => void
+  export class TypertRemoteService<T = never> extends Service<T> {
+    protected constructor(ctx: Context, serviceKey: string, options?: { namespace?: string })
+    readonly typertRemote: unknown
+  }
+  export function Remote(): Stage3MethodDecorator
+  export function Remote(exportName: string): Stage3MethodDecorator
+}
+
+declare module '@deepseek-ai/dsh-tools' {
+  /**
+   * Loose mirror of the real ToolRunContext (packages/core/tools/src/index.ts):
+   * only the agent → session → header.cwd path the worktree tools read. The
+   * real type carries far more (signal, deferContext, events, ...); the shim
+   * keeps tsc happy while the runtime object provides these fields.
+   */
+  export interface ToolRunContext {
+    agent?: { id: string; session: { id: string; header: { cwd?: string } } }
+    /** Turn-scoped cancellation the executor always supplies; forward it to every subprocess. */
+    signal: AbortSignal
+  }
+  /** Identity-typed defineTool — it only wraps the definition object at runtime. */
+  export function defineTool(tool: Record<string, unknown>): unknown
+}

package/src/worktree.ts

@@ -0,0 +1,142 @@
+// src/worktree.ts — Task 1 delivers only the binding storage; later tasks append.
+import { join } from 'node:path'
+import { saveJsonAtomic } from './atomic-json.js'
+
+export interface WorktreeBinding {
+  readonly repoRoot: string
+  readonly worktreePath: string
+  readonly name: string
+  readonly enteredAt: string
+  /**
+   * Commit the worktree's branch started from. Optional on purpose: bindings
+   * written before this field existed stay valid, and a reuse path can fail to
+   * recover a historical branch point. A consumer without it falls back to
+   * diffing against the worktree's own HEAD.
+   */
+  readonly baseCommit?: string
+}
+
+export interface BindingsFile { readonly v: 1; readonly bindings: Record<string, WorktreeBinding> }
+
+const BINDINGS_FIELDS = ['repoRoot', 'worktreePath', 'name', 'enteredAt'] as const
+
+function emptyFile(): BindingsFile { return { v: 1, bindings: {} } }
+
+function isBinding(value: unknown): value is WorktreeBinding {
+  if (typeof value !== 'object' || value === null) return false
+  const record = value as Record<string, unknown>
+  if (!BINDINGS_FIELDS.every(field => typeof record[field] === 'string' && (record[field] as string).length > 0)) return false
+  // Absent is normal; present-but-malformed is corruption, and dropping the
+  // whole record beats trusting half of it.
+  const base = record['baseCommit']
+  return base === undefined || (typeof base === 'string' && base.length > 0)
+}
+
+export function bindingsPath(home: string): string {
+  return join(home, '.dsh', 'gitworkbench-worktree-bindings.json').replace(/\\/g, '/')
+}
+
+export function parseBindings(raw: string): BindingsFile {
+  try {
+    const parsed = JSON.parse(raw) as { v?: unknown; bindings?: unknown }
+    if (parsed?.v !== 1 || typeof parsed.bindings !== 'object' || parsed.bindings === null) return emptyFile()
+    const out = emptyFile()
+    for (const [sessionId, value] of Object.entries(parsed.bindings as Record<string, unknown>)) {
+      if (sessionId.length > 0 && isBinding(value)) out.bindings[sessionId] = value
+    }
+    return out
+  } catch {
+    return emptyFile()
+  }
+}
+
+export async function loadBindings(readText: (path: string) => Promise<string>, path: string): Promise<BindingsFile> {
+  try { return parseBindings(await readText(path)) } catch { return emptyFile() }
+}
+
+export async function saveBindings(
+  ensureDir: (dir: string) => Promise<void>,
+  writeText: (path: string, text: string) => Promise<void>,
+  rename: (from: string, to: string) => Promise<void>,
+  path: string,
+  file: BindingsFile,
+): Promise<void> {
+  await saveJsonAtomic(ensureDir, writeText, rename, path, file)
+}
+
+// ---- Task 3: RPC return shapes (all JSON-safe; success writes no error key) ----
+
+export interface WorktreeOpResult {
+  readonly ok: boolean
+  /** Present on success. */
+  readonly worktreePath?: string
+  /** Present on success of enter/exit. */
+  readonly branch?: string
+  /** Operational guidance for the model, present when meaningful. */
+  readonly hint?: string
+  /** Present on failure only. */
+  readonly error?: string
+}
+
+// ---- Task 2: worktree name/branch/path derivation + porcelain parsing ----
+
+const NAME_PATTERN = /^[A-Za-z0-9._-]{1,40}$/
+
+export interface WorktreeEntry { readonly path: string; readonly head: string; readonly branch: string }
+
+export function sanitizeName(raw: string | undefined, rng: () => string): string {
+  if (raw !== undefined && NAME_PATTERN.test(raw) && raw !== '.' && raw !== '..') return raw
+  return `wt-${rng()}`
+}
+
+export function branchFor(name: string): string { return `wt/${name}` }
+
+/** Longest ref name accepted — well past any real branch, short of a payload. */
+const REF_MAX_LENGTH = 200
+/** The character set git allows in a branch or tag name. */
+const REF_CHARS = /^[A-Za-z0-9._/-]+$/
+
+/**
+ * Decide whether a ref name from an untrusted caller may be passed to git.
+ *
+ * A ref arrives from the browser as free text and becomes a POSITIONAL argument,
+ * so three things are rejected before it gets there: a leading `-`, which git
+ * would read as an option rather than a ref; `..`, which is range syntax and
+ * would silently change what a comparison covers; and any character outside the
+ * set git accepts in a ref name.
+ * @param ref - candidate ref name.
+ * @returns true when the value is safe to pass to git as a ref.
+ */
+export function isRefName(ref: string): boolean {
+  return typeof ref === 'string'
+    && ref.length > 0 && ref.length <= REF_MAX_LENGTH
+    && !ref.startsWith('-')
+    && !ref.includes('..')
+    && REF_CHARS.test(ref)
+}
+
+export function worktreeDir(repoRoot: string, name: string): string {
+  return `${repoRoot.replace(/\/+$/, '')}/.agents/worktrees/${name}`
+}
+
+export function parseWorktreeList(porcelain: string): WorktreeEntry[] {
+  const out: WorktreeEntry[] = []
+  let path = ''
+  let head = ''
+  let branch = ''
+  const flush = (): void => {
+    if (path.length > 0 && head.length > 0 && branch.length > 0) {
+      out.push({ path, head, branch })
+    }
+    path = ''; head = ''; branch = ''
+  }
+  for (const line of porcelain.split('\n')) {
+    if (line.length === 0) { flush(); continue }
+    if (line.startsWith('worktree ')) path = line.slice('worktree '.length)
+    else if (line.startsWith('HEAD ')) head = line.slice('HEAD '.length)
+    else if (line.startsWith('branch refs/heads/')) branch = line.slice('branch refs/heads/'.length)
+    else if (line === 'detached') { path = ''; head = ''; branch = '' }
+  }
+  flush()
+  return out
+}