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

package/src/client/trust.ts

@@ -0,0 +1,187 @@
+/**
+ * 网关页面的宿主信任补丁（客户端半边）。
+ *
+ * 0.2 客户端用**页面来源**判断设置面归谁管：
+ *
+ *   const persistence = ctx.remote.$host.isLoopback ? "host" : "memory"
+ *   (dsh-client-ui-settings)
+ *
+ * 经家族网关打开的页面（http://dsh.mac/ 、http://<lan-ip>:3082）主机名不是回环地址，
+ * 于是客户端把整个设置面降级成进程内的内存态：设置 → 模型 显示
+ * “settings are unavailable in this browser”，账号页、配置文件入口同样失效。
+ * 而宿主半边其实早就把网关请求当回环处理（server-mode 代理重写为回环形状 + noBrowserAuth），
+ * 只有客户端还认为自己低人一等。
+ *
+ * 两份声明，互为兜底：
+ * 1. 宿主注入的 boot 脚本（server-mode SERVER_BOOT_SCRIPT）在非回环分支同步声明
+ *    `__DSH_TRANSPORT__.ownsHost = true`（官方 transport 钩子：“本页拥有 Host”）；
+ * 2. 本模块在客户端启动时兜底：只要**能证明**这页是家族网关发出来的
+ *    （浏览器可读的 dsh_gw 标记 cookie，拿不到时退化为一次 /api/gateway/session 探测），
+ *    就把 `ctx.connection.isLoopback` 置为 true 并让 `remote.$host` 的快照失效重建。
+ *    这样即使 shell HTML 被浏览器缓存、boot 脚本是旧的，设置面依然留在宿主上。
+ *
+ * 回环页面与非网关页面完全不受影响：前者本来 isLoopback 就是 true，后者拿不到标记也不会被改写。
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis'
+import {
+  HOST_ACCESS_MARKER_COOKIE,
+  HOST_ACCESS_MARKER_VALUE,
+  HOST_ACCESS_SESSION_PATH,
+} from '../core/remote-access/paths.ts'
+
+/** 宿主网关写的“来源标记”cookie 名（非密值，仅供客户端识别来源）。 */
+export const GATEWAY_MARKER_COOKIE = 'dsh_gw'
+
+/** 标记 cookie 的期望值。 */
+export const GATEWAY_MARKER_VALUE = '1'
+
+/**
+ * 远程访问域写的第二份来源标记（同样非密值）。反向代理直连拓扑
+ * （browser -> nginx -> 127.0.0.1:3080，没有家族网关）拿不到网关 cookie 与
+ * 网关 boot 脚本，由宿主在 `GET /api/dsh-access/session` 和 per-request boot
+ * 脚本响应上写入该标记。
+ */
+export { HOST_ACCESS_MARKER_COOKIE, HOST_ACCESS_MARKER_VALUE } from '../core/remote-access/paths.ts'
+
+/** 网关会话探测路径（server-mode 网关才有）。 */
+export const GATEWAY_SESSION_PATH = '/api/gateway/session'
+
+/** 远程访问域的准入探测路径；`owners === true` 表示本页可以拥有 Host。 */
+export const ACCESS_SESSION_PATH = HOST_ACCESS_SESSION_PATH
+
+/** 浏览器位置的最小面（便于单测注入）。 */
+export interface LocationLike {
+  hostname: string
+}
+
+/** 连接句柄的最小面（只读成员在运行时是普通可写属性）。 */
+export interface ConnectionTrustTarget {
+  isLoopback?: boolean
+}
+
+/** remote 服务的最小面：`$host` 是带缓存的 getter，缓存字段是 hostFacts。 */
+export interface RemoteTrustTarget {
+  hostFacts?: unknown
+  [key: string]: unknown
+}
+
+/** 宿主名是否属于回环（与 dsh-client-connection 的判定一致：localhost / ::1 / 127/8）。 */
+export function isLoopbackHostname(hostname: string): boolean {
+  if (hostname === 'localhost' || hostname === '::1' || hostname === '[::1]') return true
+  const parts = hostname.split('.')
+  return parts.length === 4 && parts[0] === '127' && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+}
+
+/** 从 document.cookie 里读某个标记（同步、无网络）。 */
+function hasMarker(cookie: string | undefined, name: string, value: string): boolean {
+  if (cookie === undefined || cookie === '') return false
+  return cookie.split(';').some(part => {
+    const eq = part.indexOf('=')
+    if (eq < 0) return false
+    return part.slice(0, eq).trim() === name && part.slice(eq + 1).trim() === value
+  })
+}
+
+/** 家族网关写的来源标记。 */
+export function hasGatewayMarker(cookie: string | undefined): boolean {
+  return hasMarker(cookie, GATEWAY_MARKER_COOKIE, GATEWAY_MARKER_VALUE)
+}
+
+/** 远程访问域写的来源标记（反向代理直连拓扑）。 */
+export function hasHostAccessMarker(cookie: string | undefined): boolean {
+  return hasMarker(cookie, HOST_ACCESS_MARKER_COOKIE, HOST_ACCESS_MARKER_VALUE)
+}
+
+/**
+ * 把“本页拥有 Host”落到运行时对象上：改 connection 的 isLoopback，并让 remote.$host 的
+ * 缓存快照失效（该 getter 下一次访问会用新的 connection 值重建）。
+ * @param targets - connection 与 remote 服务（任一缺失都安全跳过）。
+ * @returns 是否真的改写过 connection。
+ */
+export function applyGatewayHostOwnership(targets: {
+  connection?: ConnectionTrustTarget | undefined
+  remote?: RemoteTrustTarget | undefined
+  transport?: Record<string, unknown> | undefined
+}): boolean {
+  let changed = false
+  if (targets.transport !== undefined && targets.transport.ownsHost !== true) {
+    try {
+      targets.transport.ownsHost = true
+      changed = true
+    } catch { /* 冻结的 transport：跳过 */ }
+  }
+  const connection = targets.connection
+  if (connection !== undefined && connection.isLoopback !== true) {
+    try {
+      connection.isLoopback = true
+      changed = true
+    } catch { /* 冻结的句柄：跳过 */ }
+  }
+  const remote = targets.remote
+  if (remote !== undefined) {
+    try {
+      delete remote.hostFacts
+    } catch { /* 无视 */ }
+  }
+  return changed
+}
+
+/** 取一个可选服务（缺失或抛错都返回 undefined）。 */
+function optionalService<T>(ctx: ClientContext, name: string): T | undefined {
+  try {
+    return (ctx.get as unknown as (id: string, strict?: boolean) => unknown)(name, false) as T | undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 挂载信任补丁；返回 disposer。只对“非回环 + 能证明来自家族网关”的页面生效。
+ * @param ctx - client root context。
+ * @param locationLike - 可注入的位置（默认取 globalThis.location）。
+ * @param cookie - 可注入的 cookie 串（默认取 document.cookie）。
+ */
+export function mountGatewayTrust(
+  ctx: ClientContext,
+  locationLike: LocationLike | undefined = typeof location === 'undefined' ? undefined : location,
+  cookie: string | undefined = typeof document === 'undefined' ? undefined : document.cookie,
+  probe: ((path: string) => Promise<boolean>) | undefined = undefined,
+): () => void {
+  if (locationLike === undefined || isLoopbackHostname(locationLike.hostname)) return () => {}
+  const globalTransport = (globalThis as { __DSH_TRANSPORT__?: Record<string, unknown> }).__DSH_TRANSPORT__
+  const apply = (): boolean => applyGatewayHostOwnership({
+    connection: optionalService<ConnectionTrustTarget>(ctx, 'connection'),
+    remote: optionalService<RemoteTrustTarget>(ctx, 'remote'),
+    transport: globalTransport,
+  })
+  if (hasGatewayMarker(cookie) || hasHostAccessMarker(cookie)) {
+    apply()
+    return () => {}
+  }
+  if (globalTransport?.ownsHost === true) {
+    // boot 脚本已经声明过（壳是新的）：只需要把 remote 的快照失效掉，让 settings 读到 true。
+    apply()
+    return () => {}
+  }
+  // 老壳（HTML 被缓存、没有 boot 声明、也没有标记 cookie）：先探家族网关会话，
+  // 再退到远程访问域的准入探测（反向代理直连拓扑没有网关），任一确认即补。
+  let disposed = false
+  const sessionProbe = probe ?? defaultAdmissionProbe
+  void sessionProbe(GATEWAY_SESSION_PATH)
+    .then(admitted => admitted ? true : sessionProbe(ACCESS_SESSION_PATH))
+    .then(admitted => { if (!disposed && admitted) apply() })
+    .catch(() => { /* 网关与远程访问域都不可达：保持原状 */ })
+  return () => { disposed = true }
+}
+
+/**
+ * 默认探测：网关会话回答 `authenticated`，远程访问域回答 `owners`。
+ * @param path - 要探测的准入路径。
+ * @returns 该页是否可以拥有 Host。
+ */
+async function defaultAdmissionProbe(path: string): Promise<boolean> {
+  const response = await fetch(path, { credentials: 'same-origin', headers: { accept: 'application/json' } })
+  if (!response.ok) return false
+  const body = await response.json() as { authenticated?: unknown; owners?: unknown }
+  return path === GATEWAY_SESSION_PATH ? body.authenticated === true : body.owners === true
+}

package/src/client/ui-icons.ts

@@ -0,0 +1,35 @@
+/**
+ * 运行时安全的图标出口。
+ *
+ * DSH 0.2 的类型声明仍导出 *16/*14 图标，但实际运行时只提供 *Medium/*Regular
+ * 变体：直接引用会让 React 拿到 undefined 元素类型并在渲染时抛 #130
+ * （右侧栏 Git 页此前正是如此）。本模块按运行时名字优先解析，类型名字兜底，
+ * 两者都缺失时退化为不渲染任何图标的空组件。
+ */
+import * as primitives from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ComponentType } from 'react'
+
+/** 图标组件面（size/className 与官方 primitives 一致，其余属性透传）。 */
+export type UiIcon = ComponentType<{ size?: number; className?: string } & Record<string, unknown>>
+
+const table = primitives as unknown as Record<string, UiIcon | undefined>
+const EMPTY: UiIcon = () => null
+
+function icon(typed: string, runtime: string): UiIcon {
+  // 测试里的 module mock、或更早/更晚的 cohort 可能两个名字都没有：访问未知导出
+  // 在 vitest 的 mock 代理下会抛错，所以这里整体兜底为空组件。
+  try { return table[runtime] ?? table[typed] ?? EMPTY } catch { return EMPTY }
+}
+
+export const IconBranchOutline16 = icon('IconBranchOutline16', 'IconBranchOutlineMedium')
+export const IconCheckOutline14 = icon('IconCheckOutline14', 'IconCheckOutlineMedium')
+export const IconChevronDownOutline14 = icon('IconChevronDownOutline14', 'IconChevronDownOutlineMedium')
+export const IconCloseOutline16 = icon('IconCloseOutline16', 'IconCloseOutlineMedium')
+export const IconCodeOutline16 = icon('IconCodeOutline16', 'IconCodeOutlineMedium')
+export const IconCopyOutline16 = icon('IconCopyOutline16', 'IconCopyOutlineMedium')
+export const IconGlobeOutline16 = icon('IconGlobeOutline16', 'IconGlobeOutlineMedium')
+export const IconPlusOutline16 = icon('IconPlusOutline16', 'IconPlusOutlineMedium')
+export const IconRefreshOutline16 = icon('IconRefreshOutline16', 'IconRefreshOutlineMedium')
+export const IconSearchOutline16 = icon('IconSearchOutline16', 'IconSearchOutlineMedium')
+export const IconTrashOutline16 = icon('IconTrashOutline16', 'IconTrashOutlineMedium')
+export const IconWorkspaceTreeOutline16 = icon('IconWorkspaceTreeOutline16', 'IconWorkspaceTreeOutlineMedium')

package/src/core/git-graph/commands.ts

@@ -0,0 +1,107 @@
+/** Pure Git argv construction, branch-name validation, and failure classification. */
+import type { GitError } from './protocol.ts'
+
+export const topLevelArgv = (): string[] => ['rev-parse', '--show-toplevel']
+export const headBranchArgv = (): string[] => ['rev-parse', '--abbrev-ref', 'HEAD']
+export const headShortArgv = (): string[] => ['rev-parse', '--short', 'HEAD']
+export const statusPorcelainArgv = (): string[] => ['status', '--porcelain']
+export const unmergedArgv = (): string[] => ['diff', '--name-only', '--diff-filter=U']
+export const worktreeListArgv = (): string[] => ['worktree', 'list', '--porcelain']
+export const verifyRefArgv = (branch: string): string[] => ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`]
+export const checkRefFormatArgv = (branch: string): string[] => ['check-ref-format', '--branch', branch]
+export const switchArgv = (branch: string): string[] => ['switch', '--no-guess', '--', branch]
+export const createBranchArgv = (branch: string): string[] => ['switch', '--no-guess', '-c', branch]
+export const forEachRefArgv = (): string[] => ['for-each-ref', 'refs/heads', '--format=%(refname:short)%00%(HEAD)%00%(objectname)']
+export const diffArgv = (path?: string, staged = false): string[] => ['diff', ...(staged ? ['--cached'] : []), '--', ...(path ? [path] : [])]
+export const stageArgv = (path?: string): string[] => ['add', '--', ...(path ? [path] : ['.'])]
+export const unstageArgv = (path?: string): string[] => ['restore', '--staged', '--', ...(path ? [path] : ['.'])]
+export const commitArgv = (message: string): string[] => ['commit', '-m', message]
+export const graphLogArgv = (limit: number, skip = 0): string[] => [
+  'log', '--branches', '--tags', '--remotes', '--topo-order', '--parents',
+  '--format=%H%x00%P%x00%an%x00%at%x00%D%x00%s%x1e', '--max-count', String(limit), '--skip', String(skip),
+]
+export const commitDiffArgv = (oid: string): string[] => [
+  'show', '--format=fuller', '--stat', '--patch', '--no-ext-diff', '--no-color', '--find-renames', oid, '--',
+]
+export const verifyCommitArgv = (oid: string): string[] => ['cat-file', '-e', `${oid}^{commit}`]
+export const verifyTrackedPathArgv = (path: string): string[] => ['ls-files', '--error-unmatch', '--', path]
+export const discardFileArgv = (path: string): string[] => ['restore', '--source=HEAD', '--staged', '--worktree', '--', path]
+export const revertArgv = (oid: string): string[] => ['revert', '--no-edit', '--', oid]
+export const cherryPickArgv = (oid: string): string[] => ['cherry-pick', '--', oid]
+
+export const OPERATION_MARKERS = [
+  'MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'BISECT_LOG',
+  'rebase-merge', 'rebase-apply', 'sequencer',
+] as const
+export const gitPathArgv = (marker: string): string[] => ['rev-parse', '--git-path', marker]
+export const operationMarkersArgv = (): string[] => ['rev-parse', ...OPERATION_MARKERS.flatMap((marker) => ['--git-path', marker])]
+
+export function validateObjectId(value: string): string | null {
+  if (value === '') return 'empty'
+  if (value.startsWith('-')) return 'leading-dash'
+  if (!/^[0-9a-f]{7,64}$/i.test(value)) return 'not-hex-object-id'
+  return null
+}
+
+export function validateRepoRelativePath(value: string): string | null {
+  if (value === '') return 'empty'
+  if (value.includes('\0')) return 'nul-byte'
+  if (/^[\\/]/.test(value) || /^[a-z]:[\\/]/i.test(value)) return 'absolute-path'
+  const components = value.replace(/\\/g, '/').split('/')
+  if (components.some((part) => part === '' || part === '.' || part === '..')) return 'unsafe-component'
+  return null
+}
+
+export function validateBranchName(name: string): string | null {
+  if (name === '') return 'empty'
+  if (name === '@') return 'at-sign'
+  if (name.startsWith('-')) return 'leading-dash'
+  if (name.endsWith('.')) return 'trailing-dot'
+  if (name.endsWith('.lock')) return 'lock-suffix'
+  if (name.includes('..')) return 'double-dot'
+  if (name.includes('@{')) return 'at-brace'
+  if (name.includes('//')) return 'double-slash'
+  if (/[ ~^:?*[\\]/.test(name)) return 'forbidden-char'
+  for (const character of name) {
+    const code = character.codePointAt(0)
+    if (code !== undefined && (code < 0x20 || code === 0x7f)) return 'control-char'
+  }
+  for (const component of name.split('/')) {
+    if (component === '') return 'empty-component'
+    if (component.startsWith('.')) return 'dot-component'
+    if (component.endsWith('.lock')) return 'lock-suffix'
+  }
+  return name.length > 1000 ? 'too-long' : null
+}
+
+export function extractBlockedPaths(stderr: string, header: RegExp): { paths: string[]; moreFiles: number } {
+  const firstNewline = stderr.indexOf('\n', stderr.search(header))
+  if (firstNewline < 0) return { paths: [], moreFiles: 0 }
+  const paths: string[] = []
+  for (const line of stderr.slice(firstNewline + 1).split('\n')) {
+    if (!line.startsWith('\t')) break
+    const trimmed = line.trim()
+    if (trimmed === '') break
+    const quoted = /^"(.+)"$/.exec(trimmed)
+    paths.push((quoted?.[1] ?? trimmed).replace(/\\(.)/g, '$1'))
+  }
+  return { paths: paths.slice(0, 2), moreFiles: Math.max(0, paths.length - 2) }
+}
+
+export function classifySwitchFailure(stderr: string): GitError {
+  const first = stderr.trim().split('\n')[0] ?? ''
+  const patterns = [
+    { code: 'tracked-changes-would-be-overwritten' as const, header: /Your local changes to the following files would be overwritten by (?:checkout|merge)/ },
+    { code: 'untracked-changes-would-be-overwritten' as const, header: /The following untracked working tree files would be overwritten by checkout/ },
+  ]
+  for (const pattern of patterns) {
+    if (pattern.header.test(stderr)) return { code: pattern.code, message: first, ...extractBlockedPaths(stderr, pattern.header) }
+  }
+  if (/did not match any file\(s\) known to git|invalid reference|not a valid branch/.test(stderr)) {
+    return { code: 'target-branch-not-found', message: first }
+  }
+  if (/already used by worktree|is already checked out at/.test(stderr)) {
+    return { code: 'branch-in-other-worktree', message: first }
+  }
+  return { code: 'internal', message: first || 'git switch failed' }
+}

package/src/core/git-graph/protocol.ts

@@ -0,0 +1,238 @@
+/** Pure wire contract and parsers for the workspace Git surface. */
+export interface RepoStatus {
+  root: string
+  branch: string
+  head: string
+  dirtyFiles: number
+  untrackedFiles: number
+  conflicts: number
+  operationInProgress: boolean
+}
+
+export interface BranchRow { name: string; current: boolean }
+
+export interface BranchesView {
+  root: string
+  branch: string
+  branches: BranchRow[]
+  dirtyFiles: number
+  untrackedFiles: number
+  conflicts: number
+  operationInProgress: boolean
+}
+
+export type GitErrorCode =
+  | 'conflicts-present'
+  | 'operation-in-progress'
+  | 'branch-in-other-worktree'
+  | 'tracked-changes-would-be-overwritten'
+  | 'untracked-changes-would-be-overwritten'
+  | 'target-branch-not-found'
+  | 'invalid-branch-name'
+  | 'branch-already-exists'
+  | 'workspace-unknown'
+  | 'invalid-object-id'
+  | 'commit-not-found'
+  | 'invalid-file-path'
+  | 'file-not-tracked'
+  | 'dirty-worktree'
+  | 'nothing-to-apply'
+  | 'apply-conflict'
+  | 'internal'
+
+export interface GitError {
+  code: GitErrorCode
+  message: string
+  paths?: string[]
+  moreFiles?: number
+}
+
+export type SwitchResult =
+  | {
+    ok: true
+    branch: string
+    /**
+     * Whether the conversation now runs in the branch's new worktree. A lane is
+     * a DSH workspace, and the move is the platform's own workspace navigation
+     * (`uiWorkspace.openWorkspace`, the call behind the shell's picker): a build
+     * that cannot reach that service reports the worktree as ready and says
+     * where to pick it up rather than claiming the user is already in it.
+     */
+    opened: boolean
+  }
+  | { ok: false; error: GitError }
+
+export interface GraphCommit {
+  oid: string
+  parents: string[]
+  subject: string
+  author: string
+  authorTime: number
+  refs: string[]
+}
+
+export interface GraphView {
+  root: string
+  branch: string
+  commits: GraphCommit[]
+  hasMore: boolean
+  nextCursor?: string
+}
+
+export interface CommitDiffView {
+  root: string
+  oid: string
+  diff: string
+}
+
+export type GitMutationKind = 'discard' | 'revert' | 'cherry-pick'
+export interface GitMutationResult { changed: true; kind: GitMutationKind; head: string }
+export type GitMutationResponse = { ok: true; value: GitMutationResult } | { ok: false; error: GitError }
+
+export type GitEnvelope<T> = { ok: true; value: T } | { ok: false; error: GitError }
+
+export function parseBranches(stdout: string): BranchRow[] {
+  return stdout.split('\n').flatMap((line) => {
+    if (line === '') return []
+    const [name, marker, oid] = line.split('\0')
+    return name === undefined || marker === undefined || oid === undefined
+      ? []
+      : [{ name, current: marker === '*' }]
+  }).sort((left, right) => left.name.localeCompare(right.name))
+}
+
+export function parsePorcelain(stdout: string): Pick<RepoStatus, 'dirtyFiles' | 'untrackedFiles' | 'conflicts'> {
+  const result = { dirtyFiles: 0, untrackedFiles: 0, conflicts: 0 }
+  const conflicts = new Set(['DD', 'AU', 'UD', 'UA', 'DU', 'AA', 'UU'])
+  for (const line of stdout.split('\n')) {
+    if (line === '') continue
+    const code = line.slice(0, 2)
+    if (conflicts.has(code)) result.conflicts += 1
+    else if (code === '??') result.untrackedFiles += 1
+    else result.dirtyFiles += 1
+  }
+  return result
+}
+
+export function parseWorktreeBranches(stdout: string): string[] {
+  const found = new Set<string>()
+  for (const line of stdout.split('\n')) {
+    const prefix = 'branch refs/heads/'
+    if (line.startsWith(prefix)) {
+      const name = line.slice(prefix.length).trim()
+      if (name !== '') found.add(name)
+    }
+  }
+  return [...found]
+}
+
+export function parseDecoration(value: string): string[] {
+  return value === '' ? [] : value.split(', ').map((ref) => ref === 'HEAD' ? '' : ref.replace(/^HEAD -> /, '').replace(/^tag: /, '').trim()).filter(Boolean)
+}
+
+export function parseGraph(stdout: string): GraphCommit[] {
+  const commits: GraphCommit[] = []
+  for (const raw of stdout.split('\u001e')) {
+    const [oid, parents = '', author = '', authorTime = '0', refs = '', subject = ''] = raw.replace(/^\n/, '').split('\0')
+    if (!oid) continue
+    commits.push({
+      oid,
+      parents: parents === '' ? [] : parents.split(' '),
+      author,
+      authorTime: Number(authorTime),
+      refs: parseDecoration(refs),
+      subject,
+    })
+  }
+  return commits
+}
+
+export type LaneGlyph = 'node' | 'pass' | 'merge' | 'gap'
+export interface GraphRowLanes { columns: LaneGlyph[]; nodeColumn: number; merge: boolean }
+
+export function computeLanes(commits: readonly GraphCommit[]): GraphRowLanes[] {
+  const futureParents = new Set(commits.flatMap((commit) => commit.parents))
+  const pending: Array<string | null> = []
+  return commits.map((commit) => {
+    let nodeColumn = pending.indexOf(commit.oid)
+    if (nodeColumn < 0) {
+      pending.push(commit.oid)
+      nodeColumn = pending.length - 1
+    }
+    const columns = pending.map<LaneGlyph>((oid, column) => {
+      if (column === nodeColumn) return commit.parents.length > 1 ? 'merge' : 'node'
+      if (oid === null || oid === commit.oid) return 'gap'
+      return futureParents.has(oid) ? 'pass' : 'gap'
+    })
+    const parents = commit.parents.filter((parent) => futureParents.has(parent))
+    for (let i = 0; i < pending.length; i += 1) {
+      if (i !== nodeColumn && pending[i] === commit.oid) pending[i] = null
+    }
+    pending[nodeColumn] = parents[0] ?? null
+    for (const parent of parents.slice(1)) if (!pending.includes(parent)) pending.push(parent)
+    while (pending.at(-1) === null) pending.pop()
+    return { columns, nodeColumn, merge: commit.parents.length > 1 }
+  })
+}
+
+const ERROR_CODES = new Set<GitErrorCode>([
+  'conflicts-present', 'operation-in-progress', 'branch-in-other-worktree',
+  'tracked-changes-would-be-overwritten', 'untracked-changes-would-be-overwritten',
+  'target-branch-not-found', 'invalid-branch-name', 'branch-already-exists',
+  'workspace-unknown', 'invalid-object-id', 'commit-not-found', 'invalid-file-path',
+  'file-not-tracked', 'dirty-worktree', 'nothing-to-apply', 'apply-conflict', 'internal',
+])
+const record = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === 'object' && value !== null ? value as Record<string, unknown> : undefined
+
+export function isRepoStatus(value: unknown): value is RepoStatus {
+  const row = record(value)
+  return row !== undefined && typeof row.root === 'string' && typeof row.branch === 'string'
+    && typeof row.head === 'string' && typeof row.dirtyFiles === 'number'
+    && typeof row.untrackedFiles === 'number' && typeof row.conflicts === 'number'
+    && typeof row.operationInProgress === 'boolean'
+}
+
+export function isBranchesView(value: unknown): value is BranchesView {
+  const row = record(value)
+  return row !== undefined && typeof row.root === 'string' && typeof row.branch === 'string'
+    && Array.isArray(row.branches) && row.branches.every((item) => {
+      const branch = record(item)
+      return branch !== undefined && typeof branch.name === 'string' && typeof branch.current === 'boolean'
+    }) && typeof row.dirtyFiles === 'number' && typeof row.untrackedFiles === 'number'
+    && typeof row.conflicts === 'number' && typeof row.operationInProgress === 'boolean'
+}
+
+export function isGraphView(value: unknown): value is GraphView {
+  const row = record(value)
+  return row !== undefined && typeof row.root === 'string' && typeof row.branch === 'string'
+    && typeof row.hasMore === 'boolean' && (row.nextCursor === undefined || typeof row.nextCursor === 'string')
+    && Array.isArray(row.commits) && row.commits.every((item) => {
+      const commit = record(item)
+      return commit !== undefined && typeof commit.oid === 'string'
+        && Array.isArray(commit.parents) && commit.parents.every((parent) => typeof parent === 'string')
+        && typeof commit.subject === 'string' && typeof commit.author === 'string'
+        && typeof commit.authorTime === 'number' && Array.isArray(commit.refs)
+        && commit.refs.every((ref) => typeof ref === 'string')
+    })
+}
+
+export function isCommitDiffView(value: unknown): value is CommitDiffView {
+  const row = record(value)
+  return row !== undefined && typeof row.root === 'string' && typeof row.oid === 'string' && typeof row.diff === 'string'
+}
+
+export function isGitMutationResult(value: unknown): value is GitMutationResult {
+  const row = record(value)
+  return row !== undefined && row.changed === true
+    && (row.kind === 'discard' || row.kind === 'revert' || row.kind === 'cherry-pick')
+    && typeof row.head === 'string'
+}
+
+export function isGitError(value: unknown): value is GitError {
+  const error = record(value)
+  return error !== undefined && typeof error.code === 'string' && ERROR_CODES.has(error.code as GitErrorCode)
+    && typeof error.message === 'string'
+    && (error.paths === undefined || (Array.isArray(error.paths) && error.paths.every((path) => typeof path === 'string')))
+    && (error.moreFiles === undefined || typeof error.moreFiles === 'number')
+}

package/src/core/index.ts

@@ -0,0 +1,2 @@
+/** Shared pure contracts and helpers for the position-owned web-all entity. */
+export const WEB_ALL_RUNTIME_OWNER = 'web-all' as const

package/src/core/lark-inbox/gating.ts

@@ -0,0 +1,35 @@
+/** Pure inbound admission rules for Feishu/Lark events. */
+
+export interface GatingConfig {
+  requireMentionInGroup: boolean
+  allowedOpenIds: readonly string[]
+  dropAppMessages: boolean
+}
+
+export type GateVerdict =
+  | { accept: true }
+  | { accept: false; reason: 'app-message' | 'group-without-mention' | 'sender-not-allowed' }
+
+export interface GateInput {
+  chatType?: string
+  senderType?: string
+  senderOpenId?: string
+  mentionBot?: boolean
+}
+
+/** Apply the authoritative pre-merge gate order. */
+export function gateEvent(input: GateInput, config: GatingConfig): GateVerdict {
+  if (config.dropAppMessages && input.senderType === 'app') {
+    return { accept: false, reason: 'app-message' }
+  }
+  if (input.chatType === 'group' && config.requireMentionInGroup && !input.mentionBot) {
+    return { accept: false, reason: 'group-without-mention' }
+  }
+  if (config.allowedOpenIds.length > 0) {
+    const senderOpenId = input.senderOpenId
+    if (!senderOpenId || !config.allowedOpenIds.includes(senderOpenId)) {
+      return { accept: false, reason: 'sender-not-allowed' }
+    }
+  }
+  return { accept: true }
+}