@dsh-cove/dsh-web-all 0.0.0-stage → 0.4.3

package/src/core/ssh/protocol.ts

@@ -0,0 +1,212 @@
+/**
+ * Wire contract between the host half (routes.ts) and the browser half
+ * (client/api.ts). Pure types only — imported by both halves, bundled into
+ * each, no runtime identity to share.
+ */
+
+/** Authentication flavors a host entry may carry. */
+export type SshAuthKind = 'key' | 'password' | 'agent'
+
+/** Canonical OpenSSH SHA256 fingerprint (32 bytes, unpadded base64). */
+export function isHostKeyFingerprint(value: unknown): value is string {
+  return typeof value === 'string' && /^SHA256:[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]$/.test(value)
+}
+
+/** One stored host entry (the $DSH_HOME/dsh-ssh.json store shape). */
+export interface SshHostEntry {
+  /** Stable, user-chosen identifier used by every operation. */
+  alias: string
+  /** Hostname or IP of the target. */
+  host: string
+  /** Explicit, out-of-band verified SHA256 pin; otherwise use ~/.ssh/known_hosts. */
+  hostKeyFingerprint?: string
+  /** SSH port (default 22). */
+  port: number
+  /** Login user. */
+  user: string
+  /** Authentication. */
+  auth: {
+    kind: SshAuthKind
+    /** Absolute path to the private key for 'key' auth. */
+    keyPath?: string
+    /** Passphrase for an encrypted key. */
+    passphrase?: string
+    /** Password for 'password' auth. */
+    password?: string
+    /**
+     * ssh-agent endpoint for 'agent' auth. A socket path, the special value
+     * 'pageant' (PuTTY Pageant on Windows), or undefined for auto-detect
+     * (SSH_AUTH_SOCK, then Pageant on Windows).
+     */
+    agentPath?: string
+  }
+  /** Jump chain: local aliases connected through in order (ProxyJump). */
+  proxyJump: string[]
+  /** Free-form note. */
+  description?: string
+  /** Deployment environment label (development / production / ...). */
+  environment?: string
+  /** Free-form tags. */
+  tags: string[]
+  /** Physical location note. */
+  location?: string
+  createdAt: number
+  updatedAt: number
+}
+
+/** Public (secret-free) projection of an entry, safe for the browser/agent. */
+export interface SshHostSummary {
+  alias: string
+  host: string
+  /** Explicit, out-of-band verified SHA256 pin; otherwise use ~/.ssh/known_hosts. */
+  hostKeyFingerprint?: string
+  port: number
+  user: string
+  auth: SshAuthKind
+  /** Whether the key path exists on the host machine (key auth only). */
+  keyReady: boolean
+  proxyJump: string[]
+  description?: string
+  environment?: string
+  tags: string[]
+  location?: string
+  createdAt: number
+  updatedAt: number
+}
+
+/** Result of one non-interactive command execution. */
+export interface ExecResult {
+  success: boolean
+  /** Remote exit code, or null when the channel died without one. */
+  exitCode: number | null
+  timedOut: boolean
+  stdout: string
+  stderr: string
+  /** Wall-clock duration of the round trip in ms. */
+  durationMs: number
+  /** Connection error message when the command never ran. */
+  error?: string
+}
+
+/** One server entry in a cluster run. */
+export interface ClusterResult {
+  alias: string
+  ok: boolean
+  exitCode?: number | null
+  timedOut?: boolean
+  stdout?: string
+  stderr?: string
+  durationMs?: number
+  error?: string
+}
+
+/** SFTP transfer progress frame (upload stream). */
+export interface TransferProgress {
+  phase: 'connecting' | 'transferring' | 'done' | 'error'
+  file: string
+  transferred: number
+  total: number
+  percent: number
+  speedBps?: number
+  error?: string
+}
+
+/** One active local port-forward tunnel. */
+export interface TunnelInfo {
+  id: string
+  alias: string
+  localPort: number
+  remoteHost: string
+  remotePort: number
+  state: 'forwarding' | 'connecting' | 'failed'
+  error?: string
+  startedAt: number
+}
+
+/** One directory listing entry (remote file browser). */
+export interface RemoteDirEntry {
+  name: string
+  type: 'dir' | 'file' | 'other'
+  size: number
+  mtimeMs: number
+  mode?: number
+}
+
+/** Test-connection outcome. */
+export interface TestResult {
+  ok: boolean
+  latencyMs?: number
+  error?: string
+}
+
+/** Host edit payload (create/update); 'alias' comes from the URL for updates. */
+export interface HostPayload {
+  alias?: string
+  host: string
+  /** Explicit SHA256 pin; PATCH null clears it and returns to known_hosts. */
+  hostKeyFingerprint?: string | null
+  port?: number
+  user: string
+  /**
+   * Authentication. Required on create; on update an omitted auth keeps the
+   * stored secrets (the browser never receives them back).
+   */
+  auth?: SshHostEntry['auth']
+  proxyJump?: string[]
+  description?: string
+  environment?: string
+  tags?: string[]
+  location?: string
+}
+
+/** Import outcome from ~/.ssh/config. */
+export interface ImportResult {
+  parsed: number
+  added: number
+  skipped: number
+  /** Aliases that failed to map (wildcard patterns, missing HostName, ...). */
+  skippedNames: string[]
+}
+
+/** JSON error body used by every route. */
+export interface ApiErrorBody {
+  error: string
+}
+
+/** WebSocket terminal protocol frames (host -> client and client -> host). */
+export type TerminalServerFrame =
+  | { type: 'ready'; alias: string }
+  | { type: 'output'; data: string }
+  | { type: 'exit'; code: number | null; error?: string }
+  | {
+      type: 'auth_prompt'
+      name: string
+      instructions: string
+      prompts: Array<{ prompt: string; echo: boolean }>
+    }
+
+export type TerminalClientFrame =
+  | { type: 'input'; data: string }
+  | { type: 'resize'; cols: number; rows: number }
+  | { type: 'auth_response'; responses: string[] }
+
+/** Route paths the client calls (shared literals). */
+export const SSH_API_BASE = '/api/dsh-ssh' as const
+
+export const SSH_API = {
+  hosts: SSH_API_BASE + '/hosts',
+  importSshConfig: SSH_API_BASE + '/hosts/import-ssh-config',
+  test: SSH_API_BASE + '/test',
+  exec: SSH_API_BASE + '/exec',
+  cluster: SSH_API_BASE + '/cluster',
+  upload: SSH_API_BASE + '/upload',
+  download: SSH_API_BASE + '/download',
+  ls: SSH_API_BASE + '/ls',
+  tunnel: SSH_API_BASE + '/tunnel',
+  terminal: SSH_API_BASE + '/terminal',
+} as const
+
+/** NDJSON transfer stream line shapes (upload). */
+export type TransferStreamLine =
+  | { type: 'progress'; progress: TransferProgress }
+  | { type: 'result'; ok: boolean; transferredBytes?: number; error?: string }

package/src/core/subagent-model/badges.ts

@@ -0,0 +1,161 @@
+/**
+ * Subagent badge facts, resolved from the client sessions list snapshot.
+ *
+ * DSH 0.2 reshaped every fact this feature used: `sessions.list` no longer has
+ * `current` or `subagentsByParent`, and the `subagents/history` RPC is gone.
+ * The list rows carry the projections instead — the parent row's
+ * `projectionValues.subagentCatalog` names its direct children, and each child
+ * row's `projectionValues.modelSelection` holds the model and reasoning effort
+ * the child ran with (`{ lastUsed, next }`). So the badge needs no history
+ * fetch and never opens or retains a child session.
+ *
+ * Dependency-free: the position module passes the raw snapshot rows in.
+ */
+
+/** The `modelSelection` projection's shape (`{ provider, model, reasoningEffort? }`). */
+export interface SubagentModelChoice {
+  readonly provider?: unknown
+  readonly model?: unknown
+  readonly reasoningEffort?: unknown
+}
+
+/** One `projectionValues` bag as the client list carries it. */
+export interface SubagentProjectionValuesLike {
+  readonly subagentCatalog?: unknown
+  readonly modelSelection?: unknown
+}
+
+/** The subset of a session list row this resolver reads. */
+export interface SubagentListRowLike {
+  readonly id?: unknown
+  readonly parentId?: unknown
+  readonly origin?: unknown
+  readonly displayTitle?: unknown
+  readonly title?: unknown
+  readonly projectionValues?: SubagentProjectionValuesLike
+}
+
+/** The subset of the sessions list snapshot this resolver reads. */
+export interface SubagentListSnapshotLike {
+  readonly byId?: Readonly<Record<string, SubagentListRowLike>>
+  /** Parent-keyed projections; a fallback path for the catalog. */
+  readonly projectionsBySession?: Readonly<Record<string, { readonly values?: { readonly subagentCatalog?: unknown } }>>
+}
+
+/** One badge to render: the child identity, its matchable labels, and its text. */
+export interface SubagentBadgeFacts {
+  readonly childId: string
+  /** Labels/row titles that identify this child's rendered row. */
+  readonly labels: readonly string[]
+  /** `model` or `model · effort`; absent when the child recorded no selection. */
+  readonly modelText?: string
+}
+
+/** Resolved badges plus the conversation root they belong to. */
+export interface SubagentBadgeResolution {
+  readonly rootId?: string
+  readonly badges: readonly SubagentBadgeFacts[]
+}
+
+/**
+ * Walk upward to the first non-subagent session.
+ * @param rows - the list rows.
+ * @param sessionId - any listed session id.
+ * @returns the root conversation's id (the input when it is already a root).
+ */
+export function rootSessionId(
+  rows: Readonly<Record<string, SubagentListRowLike>>,
+  sessionId: string,
+): string {
+  const seen = new Set<string>()
+  let current = rows[sessionId]
+  while (current?.origin === 'subagent' && typeof current.parentId === 'string' && !seen.has(String(current.id))) {
+    seen.add(String(current.id))
+    current = rows[current.parentId]
+  }
+  return typeof current?.id === 'string' ? current.id : sessionId
+}
+
+/** `model` or `model · effort`, or undefined when the choice carries no model. */
+export function formatModelText(choice: unknown): string | undefined {
+  if (!isRecord(choice)) return undefined
+  const model = nonBlankString(choice.model)
+  if (model === undefined) return undefined
+  const effort = nonBlankString(choice.reasoningEffort)
+  return effort === undefined ? model : `${model} · ${effort}`
+}
+
+/**
+ * Resolve every badge for the conversation the operator is in.
+ * @param snapshot - the sessions list snapshot (`byId` + projections).
+ * @param sessionId - the main-view session id, when one is selected.
+ * @returns the root id and one entry per catalog child that has a model.
+ */
+export function resolveSubagentBadges(
+  snapshot: SubagentListSnapshotLike,
+  sessionId: string | undefined,
+): SubagentBadgeResolution {
+  const rows = snapshot.byId ?? {}
+  if (sessionId === undefined || sessionId === '') return { badges: [] }
+  const rootId = rootSessionId(rows, sessionId)
+  const catalog = readCatalog(snapshot, rows, rootId)
+  const badges: SubagentBadgeFacts[] = []
+  const seen = new Set<string>()
+  for (const entry of catalog) {
+    const childId = readChildId(entry)
+    if (childId === undefined || seen.has(childId)) continue
+    seen.add(childId)
+    const child = rows[childId]
+    badges.push({
+      childId,
+      labels: childLabels(entry, child),
+      ...(formatModelText(pickSelection(child?.projectionValues?.modelSelection)) === undefined
+        ? {}
+        : { modelText: formatModelText(pickSelection(child?.projectionValues?.modelSelection)) }),
+    })
+  }
+  return { rootId, badges }
+}
+
+/** The parent row's catalog first; the parent-keyed projection as fallback. */
+function readCatalog(
+  snapshot: SubagentListSnapshotLike,
+  rows: Readonly<Record<string, SubagentListRowLike>>,
+  rootId: string,
+): readonly unknown[] {
+  const fromRow = rows[rootId]?.projectionValues?.subagentCatalog
+  if (Array.isArray(fromRow)) return fromRow
+  const fromProjection = snapshot.projectionsBySession?.[rootId]?.values?.subagentCatalog
+  return Array.isArray(fromProjection) ? fromProjection : []
+}
+
+function readChildId(entry: unknown): string | undefined {
+  if (!isRecord(entry)) return undefined
+  return nonBlankString(entry.id)
+}
+
+/** Every label a rendered row may carry for this child. */
+function childLabels(entry: unknown, child: SubagentListRowLike | undefined): readonly string[] {
+  const candidates = [
+    isRecord(entry) ? nonBlankString(entry.label) : undefined,
+    nonBlankString(child?.displayTitle),
+    nonBlankString(child?.title),
+  ]
+  return [...new Set(candidates.filter((value): value is string => value !== undefined))]
+}
+
+/** The committed request header wins over the pending intent. */
+function pickSelection(selection: unknown): unknown {
+  if (!isRecord(selection)) return selection
+  return selection.lastUsed ?? selection.next
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function nonBlankString(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const trimmed = value.trim()
+  return trimmed === '' ? undefined : trimmed
+}

package/src/core/worktree/invariant.ts

@@ -0,0 +1,101 @@
+/**
+ * Public error type thrown by the host worktree manager. Errors are domain
+ * shaped (no leaking of git exit codes as raw integers) so the HTTP layer
+ * can map them to stable status codes without parsing message strings.
+ *
+ * The browser half imports this through the same `./invariant` export as
+ * the host half: both halves agree on the error vocabulary over the wire.
+ * @module @dsh-cove/dsh-client-ui-worktree/invariant
+ */
+
+export type WorktreeErrorCode =
+  /** The session cwd is not inside a git repository. */
+  | 'not-a-repository'
+  /** The session cwd does not match any registered workspace. */
+  | 'workspace-unknown'
+  /** The named worktree does not exist for the repository. */
+  | 'worktree-not-found'
+  /** A worktree with the same name already exists. */
+  | 'worktree-exists'
+  /** A running session would be broken by removing this worktree. */
+  | 'worktree-busy'
+  /** The branch name is invalid (empty, contains spaces, has a `..`, etc.). */
+  | 'invalid-branch'
+  /** A git subprocess returned a non-zero exit code. */
+  | 'git-failed'
+  /** The git push to the remote failed. */
+  | 'push-failed'
+  /** The repository has no `origin` remote to push to. */
+  | 'no-remote'
+  /** Cleanup refused because the branch is not merged into its base. */
+  | 'not-merged'
+  /** The remote host is not GitHub, so no compare URL or PR API applies. */
+  | 'unsupported-remote'
+  /** The manifest file is missing required fields or is corrupted. */
+  | 'manifest-corrupt'
+  /** The repo does not ignore `<repo>/.dsh/workspaces/`, so a lane directory
+   *  would show up as untracked in the main checkout. */
+  | 'worktree-not-ignored'
+  /** The host could not create the session bound to a new lane. */
+  | 'session-create-failed'
+  /** The session a lane would bind to is not live on the host. */
+  | 'session-unknown'
+  /** A bind named a lane the asking conversation is not running in. */
+  | 'lane-mismatch'
+
+/**
+ * Thrown by the worktree host service when a domain precondition fails.
+ * The message is human-readable English; the code is the stable contract.
+ */
+export class WorktreeError extends Error {
+  readonly code: WorktreeErrorCode
+  readonly details?: Record<string, unknown>
+
+  constructor(code: WorktreeErrorCode, message: string, details?: Record<string, unknown>) {
+    super(message)
+    this.name = 'WorktreeError'
+    this.code = code
+    if (details !== undefined) this.details = details
+  }
+}
+
+/**
+ * Stable, language-neutral branch-name predicate. Accepts the git ref
+ * subset that does not surprise users: letters, digits, dot, underscore,
+ * slash, dash; must not be empty, must not start with a dot or dash, must
+ * not contain `..`, must not end with `.lock`, and must be <= 100 chars.
+ */
+export function isValidBranchName(name: string): boolean {
+  if (typeof name !== 'string') return false
+  if (name.length === 0 || name.length > 100) return false
+  if (name === 'HEAD' || name === '@') return false
+  if (name.startsWith('.') || name.startsWith('-')) return false
+  if (name.endsWith('.lock') || name.endsWith('/') || name.endsWith('.')) return false
+  if (name.includes('..')) return false
+  if (name.includes('~') || name.includes('^') || name.includes(':')) return false
+  if (name.includes('\\') || name.includes(' ')) return false
+  if (!/^[A-Za-z0-9._/-]+$/.test(name)) return false
+  return true
+}
+
+/** Default error message for a code (browser copy mirrors these). */
+export function defaultMessage(code: WorktreeErrorCode): string {
+  switch (code) {
+    case 'not-a-repository': return 'The directory is not a git repository.'
+    case 'workspace-unknown': return 'The directory is not a registered workspace.'
+    case 'worktree-not-found': return 'No such worktree.'
+    case 'worktree-exists': return 'A worktree with that name already exists.'
+    case 'worktree-busy': return 'A running session is bound to that worktree; stop it first or use force.'
+    case 'invalid-branch': return 'That branch name is not valid for a git ref.'
+    case 'git-failed': return 'git exited with a non-zero status; see the server log for details.'
+    case 'push-failed': return 'The push to the remote failed; see the server log for details.'
+    case 'no-remote': return 'The repository has no "origin" remote; add one before creating a pull request.'
+    case 'not-merged': return 'The branch is not merged into its base; merge the pull request first or force the cleanup.'
+    case 'unsupported-remote': return 'The remote host is not GitHub; PR creation is only supported for GitHub remotes.'
+    case 'manifest-corrupt': return 'The worktree manifest is corrupted; remove it and reinitialize.'
+    case 'worktree-not-ignored': return 'The repository does not ignore the worktree root; add it to .gitignore before creating a lane.'
+    case 'session-create-failed': return 'The host could not start a session on the new lane; the lane was rolled back.'
+    case 'session-unknown': return 'The session does not exist on the host, so it cannot be bound to a lane.'
+    case 'lane-mismatch': return 'The session is not running in that lane directory, so it cannot be bound to it.'
+  }
+}

package/src/core/worktree/manifest.ts

@@ -0,0 +1,135 @@
+/**
+ * Manifest on-disk schema for `<repo>/.dsh/workspaces/manifest.json`. The
+ * manifest records every worktree we ever created so the sidebar can
+ * recover after the worktree directory is gone (orphan state) and so the
+ * workspace registry can re-bind surviving paths. Since v1 it also records
+ * PR metadata per worktree so the panel can show merged / not-merged state
+ * across restarts.
+ *
+ * Version history:
+ *  - v1: name/path/baseCommit/createdAt/detached per entry.
+ *  - v2: adds optional `baseBranch` (repo-level PR target) and per-entry
+ *    `prUrl` / `prNumber` / `remoteBranch` / `baseRef` / `updatedAt`.
+ *    The reader accepts both versions (v1 entries simply carry no PR
+ *    metadata) so an upgraded plugin never trips over an older manifest.
+ *    v2 also carries the optional session binding (`sessionId` /
+ *    `workspaceId`) and preset outcome used by session-bound lanes; these
+ *    are additive optional fields, so the on-disk version stays 2.
+ * @module @dsh-cove/dsh-client-ui-worktree/core
+ */
+
+import { MANIFEST_FILENAME, WORKSPACE_DIR } from './paths.ts'
+
+/** Persisted entry for one worktree. */
+export interface WorktreeManifestEntry {
+  /** Branch name (== worktree dir name under `.dsh/workspaces/`). */
+  name: string
+  /** Absolute path. */
+  path: string
+  /** Commit the worktree was created from. */
+  baseCommit: string
+  /** ISO 8601 timestamp. */
+  createdAt: string
+  /** True when the worktree was created without a branch (detached). */
+  detached: boolean
+  /** PR page URL once a PR was created through this plugin. */
+  prUrl?: string
+  /** GitHub PR number when created via the REST API. */
+  prNumber?: number
+  /** The remote the branch was pushed to (`origin`). */
+  remoteBranch?: string
+  /** Base branch the PR targets. */
+  baseRef?: string
+  /** ISO 8601 timestamp of the last PR-related mutation. */
+  updatedAt?: string
+  /** DSH session bound to this lane (session-bound lanes only). */
+  sessionId?: string
+  /** DSH workspace id registered for the lane path, when known. */
+  workspaceId?: string
+  /** Whether the required lane permission preset was applied to its session. */
+  permissionPresetApplied?: boolean
+}
+
+/** The full manifest file (current on-disk version). */
+export interface WorktreeManifest {
+  version: 2
+  repoPath: string
+  /** Repo-level PR target base branch; set on the first pr-create. */
+  baseBranch?: string
+  worktrees: WorktreeManifestEntry[]
+}
+
+/** A parsed manifest in the current (v2) shape; v1 input is normalized. */
+export type ParsedWorktreeManifest = WorktreeManifest
+
+/** Empty manifest for a fresh repo. */
+export function emptyManifest(repoPath: string): WorktreeManifest {
+  return { version: 2, repoPath, worktrees: [] }
+}
+
+/**
+ * Parse manifest text into the current v2 shape. v1 manifests (or v2 with
+ * missing optional fields) are normalized rather than rejected, so an
+ * upgraded plugin keeps working with an old manifest. Throws a plain
+ * `Error` on shapes that are not a manifest at all — the caller decides
+ * how to surface corruption.
+ */
+export function parseManifest(text: string): ParsedWorktreeManifest {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch (error) {
+    throw new Error(`worktree manifest is not valid JSON: ${String(error)}`)
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('worktree manifest must be a JSON object')
+  }
+  const record = parsed as Record<string, unknown>
+  const version = record['version']
+  if (version !== 1 && version !== 2) {
+    throw new Error(`unsupported worktree manifest version: ${JSON.stringify(version)}`)
+  }
+  if (typeof record['repoPath'] !== 'string') {
+    throw new Error('worktree manifest is missing repoPath')
+  }
+  if (!Array.isArray(record['worktrees'])) {
+    throw new Error('worktree manifest is missing the worktrees array')
+  }
+  const baseBranch = typeof record['baseBranch'] === 'string' ? record['baseBranch'] : undefined
+  const worktrees: WorktreeManifestEntry[] = (record['worktrees'] as unknown[]).map((entry) => {
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new Error('worktree manifest contains a malformed entry')
+    }
+    const e = entry as Record<string, unknown>
+    for (const field of ['name', 'path', 'baseCommit', 'createdAt'] as const) {
+      if (typeof e[field] !== 'string') throw new Error(`worktree manifest entry is missing '${field}'`)
+    }
+    if (typeof e['detached'] !== 'boolean') {
+      throw new Error('worktree manifest entry is missing detached')
+    }
+    const out: WorktreeManifestEntry = {
+      name: e['name'] as string,
+      path: e['path'] as string,
+      baseCommit: e['baseCommit'] as string,
+      createdAt: e['createdAt'] as string,
+      detached: e['detached'] as boolean,
+    }
+    if (typeof e['prUrl'] === 'string') out.prUrl = e['prUrl']
+    if (typeof e['prNumber'] === 'number') out.prNumber = e['prNumber']
+    if (typeof e['remoteBranch'] === 'string') out.remoteBranch = e['remoteBranch']
+    if (typeof e['baseRef'] === 'string') out.baseRef = e['baseRef']
+    if (typeof e['updatedAt'] === 'string') out.updatedAt = e['updatedAt']
+    if (typeof e['sessionId'] === 'string') out.sessionId = e['sessionId']
+    if (typeof e['workspaceId'] === 'string') out.workspaceId = e['workspaceId']
+    if (typeof e['permissionPresetApplied'] === 'boolean') {
+      out.permissionPresetApplied = e['permissionPresetApplied']
+    }
+    return out
+  })
+  return { version: 2, repoPath: record['repoPath'] as string, ...(baseBranch === undefined ? {} : { baseBranch }), worktrees }
+}
+
+/** Manifest path = `<repo>/.dsh/workspaces/manifest.json`. */
+export function manifestPath(repoPath: string): string {
+  return `${repoPath}/${WORKSPACE_DIR}/${MANIFEST_FILENAME}`
+}