dsh-code 1.3.0 → 1.5.0

package/src/runner/harness-gate.ts

@@ -0,0 +1,168 @@
+/**
+ * Load-time DeepSeek Harness version gate.
+ *
+ * The terminal driver is validated against exactly one Harness snapshot, and
+ * the host resolves every bare `@deepseek-ai/*` import the plugin makes
+ * against ITS OWN installed copies (the profile's `HostResolvedRootInclude`
+ * redirects bare names to the installed-host base). No install-time or
+ * load-time check exists anywhere on that path, so a user who updates `dsh`
+ * would otherwise run this build against unvetted upstream code silently.
+ *
+ * This gate mirrors how the host itself reads its identity: the running CLI
+ * entry (`process.argv[1]`) sits inside the `@deepseek-ai/dsh` package, whose
+ * manifest version is released in lockstep with the Harness packages bundled
+ * beside it. When the probe can identify the host it compares the running
+ * versions against the one this build declares and fails fast with an
+ * actionable message; when it cannot identify the host it stays silent rather
+ * than brick a supported embedding on a false positive.
+ *
+ * @module @deepseek-ai/dsh-code/runner/harness-gate
+ */
+
+import { realpathSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/** The one Harness release this build was validated against. */
+export const EXPECTED_HARNESS_VERSION = '0.1.5-rc.2'
+
+/** Host packages whose bundled copy the plugin binds to at runtime. */
+export const HARNESS_GATE_PACKAGES = [
+  '@deepseek-ai/dsh-agent',
+  '@deepseek-ai/dsh-session',
+] as const
+
+/** The installed-host CLI package that carries the Harness runtime. */
+const HOST_PACKAGE_NAME = '@deepseek-ai/dsh'
+
+/** Filesystem slice the probe needs; injectable so tests stay pure. */
+export interface HarnessFs {
+  /** Resolve a symlinked entry to its real path. */
+  realpathSync(path: string): string
+  /** Read and parse one package.json; undefined when absent or unreadable. */
+  readManifest(path: string): { name?: unknown; version?: unknown } | undefined
+}
+
+const defaultHarnessFs: HarnessFs = {
+  realpathSync: path => realpathSync(path),
+  readManifest: path => {
+    try {
+      return JSON.parse(readFileSync(path, 'utf8')) as { name?: unknown; version?: unknown }
+    } catch {
+      return undefined
+    }
+  },
+}
+
+/** What the probe learned about the running host. */
+export interface HarnessProbe {
+  /** Installed-host package root, when identified. */
+  readonly hostRoot?: string
+  /** Installed-host CLI version (`@deepseek-ai/dsh`). */
+  readonly hostVersion?: string
+  /** Version of each gate package bundled beside the host, when present. */
+  readonly packages: Readonly<Record<string, string | undefined>>
+}
+
+const UNKNOWN_PROBE: HarnessProbe = { packages: {} }
+
+/**
+ * Walk up from one directory to the nearest `@deepseek-ai/dsh` package root.
+ * @param start - directory of the running CLI entry (already realpath'd).
+ * @param fs - filesystem slice to walk with.
+ * @returns the host package root, or undefined when no ancestor matches.
+ */
+function findHostRoot(start: string, fs: HarnessFs): string | undefined {
+  let directory = start
+  for (;;) {
+    const manifest = fs.readManifest(join(directory, 'package.json'))
+    if (manifest !== undefined && manifest.name === HOST_PACKAGE_NAME) return directory
+    const parent = dirname(directory)
+    if (parent === directory) return undefined
+    directory = parent
+  }
+}
+
+/**
+ * Identify the running host and the Harness versions it provides.
+ * @param argv1 - `process.argv[1]`, the running CLI entry path.
+ * @param fs - filesystem slice; defaults to the real one.
+ * @returns the probe result; `packages` is empty when the host is unknown.
+ */
+export function probeRunningHarness(argv1: string | undefined, fs: HarnessFs = defaultHarnessFs): HarnessProbe {
+  if (argv1 === undefined || argv1 === '') return UNKNOWN_PROBE
+  let entry: string
+  try {
+    entry = fs.realpathSync(argv1)
+  } catch {
+    return UNKNOWN_PROBE
+  }
+  const hostRoot = findHostRoot(dirname(entry), fs)
+  if (hostRoot === undefined) return UNKNOWN_PROBE
+  const hostManifest = fs.readManifest(join(hostRoot, 'package.json'))
+  const hostVersion = typeof hostManifest?.version === 'string' ? hostManifest.version : undefined
+  const packages: Record<string, string | undefined> = {}
+  for (const name of HARNESS_GATE_PACKAGES) {
+    const manifest = fs.readManifest(join(hostRoot, 'node_modules', name, 'package.json'))
+    if (typeof manifest?.version === 'string') packages[name] = manifest.version
+  }
+  return { hostRoot, hostVersion, packages }
+}
+
+/** One host fact that disagrees with the version this build declares. */
+export interface HarnessMismatch {
+  /** What was compared: the host CLI or one bundled package. */
+  readonly source: string
+  /** The version this build was validated against. */
+  readonly expected: string
+  /** The version the running host actually provides. */
+  readonly provided: string
+}
+
+/**
+ * Compare one probe against the expected snapshot. Unknown facts never
+ * mismatch: the gate must stay silent when it cannot judge, not brick a
+ * supported embedding on missing evidence.
+ * @param expected - the Harness version this build declares.
+ * @param probe - the running host's identified versions.
+ * @returns every concrete disagreement, empty when compatible or unknown.
+ */
+export function harnessVersionMismatches(expected: string, probe: HarnessProbe): readonly HarnessMismatch[] {
+  const mismatches: HarnessMismatch[] = []
+  if (probe.hostVersion !== undefined && probe.hostVersion !== expected) {
+    mismatches.push({ source: `${HOST_PACKAGE_NAME} host`, expected, provided: probe.hostVersion })
+  }
+  for (const name of HARNESS_GATE_PACKAGES) {
+    const provided = probe.packages[name]
+    if (provided !== undefined && provided !== expected) {
+      mismatches.push({ source: name, expected, provided })
+    }
+  }
+  return mismatches
+}
+
+/**
+ * Render the gate failure the user sees on stderr.
+ * @param expected - the Harness version this build declares.
+ * @param mismatches - the disagreements to report.
+ * @param hostRoot - installed-host root, when identified, for the fix hint.
+ * @returns the multi-line diagnostic.
+ */
+export function harnessGateMessage(expected: string, mismatches: readonly HarnessMismatch[], hostRoot?: string): string {
+  const lines = [`dsh: this dsh-code build requires DeepSeek Harness ${expected}, but this dsh provides:`]
+  for (const mismatch of mismatches) lines.push(`dsh:   ${mismatch.source} ${mismatch.provided}`)
+  lines.push('dsh: update dsh-code to a release built for this dsh, or use a dsh matching ' + expected + '.')
+  if (hostRoot !== undefined) lines.push(`dsh: running host: ${hostRoot}`)
+  return lines.join('\n')
+}
+
+/**
+ * Refuse to run against an identified-but-incompatible host.
+ * @param expected - the Harness version this build declares.
+ * @param probe - the running host's identified versions.
+ * @throws an Error carrying the gate diagnostic when a version disagrees.
+ */
+export function requireHarnessVersion(expected: string, probe: HarnessProbe): void {
+  const mismatches = harnessVersionMismatches(expected, probe)
+  if (mismatches.length === 0) return
+  throw new Error(harnessGateMessage(expected, mismatches, probe.hostRoot))
+}

package/src/runner/input-history.ts

@@ -0,0 +1,77 @@
+/** Global input recall: the appended prompts and their durable JSONL file.
+ *
+ * One JSONL file under the DSH home. A missing file means an empty history and
+ * unreadable or corrupt content degrades to the valid lines it could parse,
+ * silently — recall is a convenience surface, never a gate.
+ *
+ * @module @deepseek-ai/dsh-code/input-history
+ */
+
+import { readFileSync } from 'node:fs'
+import { appendFile, mkdir } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import {
+  historyLine,
+  HISTORY_MAX_ENTRIES,
+  needsCompaction,
+  parseHistoryFile,
+  serializeHistoryList,
+} from '../session/history.ts'
+import { writeFileAtomically } from '../settings-file.ts'
+
+/** Live recall state plus its serialized durable writes. */
+export interface InputHistoryStore {
+  /** The recall list, newest last; read live by the composer. */
+  readonly entries: () => readonly string[]
+  /** Append one submitted line and persist it; '' is ignored. */
+  readonly record: (text: string) => void
+  /** Await the pending writes (the quit flush). */
+  readonly flush: () => Promise<void>
+}
+
+/**
+ * Load the recall history and return its live store.
+ *
+ * Serialized history writes: each submission appends one JSON line at the end
+ * of the file, so concurrent terminals add entries after each other instead of
+ * overwriting snapshots they read at their own boot. A multi-line draft still
+ * occupies one physical line (JSON escapes the newline), and a regular-length
+ * line reaches the disk as one positioned write; an oversized paste may
+ * interleave mid-line, which the next parse simply drops.
+ *
+ * @param path - absolute path of the JSONL recall file.
+ * @param onFailure - receives the write failure message for a bounded notice.
+ */
+export function createInputHistory(path: string, onFailure: (message: string) => void): InputHistoryStore {
+  let entries: readonly string[] = []
+  let chain: Promise<void> = Promise.resolve()
+  try {
+    const raw = readFileSync(path, 'utf8')
+    entries = parseHistoryFile(raw)
+    // Stale lines (adjacent duplicates, dropped garbage, an over-cap tail)
+    // accumulate in an append-only file; rewrite the canonical form once per
+    // boot. The rewrite rides the same chain, so it lands before any
+    // submission the user types next. An entry another terminal appends
+    // inside the read-to-rename window is dropped — a millisecond-scale gap
+    // at boot that recall tolerates by design.
+    if (needsCompaction(raw)) {
+      chain = chain.then(() => writeFileAtomically(path, serializeHistoryList(entries))).catch(() => {})
+    }
+  } catch {
+    entries = []
+  }
+  return {
+    entries: () => entries,
+    record: (text: string): void => {
+      if (text === '') return
+      entries = [...entries, text].slice(-HISTORY_MAX_ENTRIES)
+      chain = chain
+        .then(() => mkdir(dirname(path), { recursive: true }))
+        .then(() => appendFile(path, historyLine(text), 'utf8'))
+        .catch((error: unknown) => {
+          onFailure(error instanceof Error ? error.message : String(error))
+        })
+    },
+    flush: () => chain,
+  }
+}

package/src/runner/mode-cycle.ts

@@ -0,0 +1,49 @@
+/** Shift+Tab mode-cycle stations for the terminal runner.
+ *
+ * Pure decision over the preset table and the committed plan fold: the runner
+ * applies the returned station, so the whole cycle is testable without a
+ * session.
+ *
+ * @module @deepseek-ai/dsh-code/mode-cycle
+ */
+
+/** One Shift+Tab station decision for the mode cycle. */
+export type ModeCycleDecision =
+  | { readonly kind: 'permission'; readonly preset: string }
+  | { readonly kind: 'plan-on' }
+  | { readonly kind: 'plan-off'; readonly preset: string }
+
+/**
+ * Decide the next Shift+Tab station. The cycle keeps the preset table's
+ * own order (most restrictive first) and inserts ONE plan station between
+ * the most restrictive preset and the wrap target: with the shipped three
+ * presets the user sees workspace-write → danger-full-access → read-only
+ * → plan → workspace-write. Plan IS the most restrictive preset plus the
+ * plan prompt layer — entering it switches nothing (the cycle is already
+ * parked on read-only), and leaving it lands on the next preset after the
+ * most restrictive one. Without the /plan command the cycle is exactly the
+ * preset table.
+ *
+ * `planIntent` covers the committed fold's commit lag: upstream queues a
+ * plan switch during an open turn (and the command pipeline is async even
+ * idle), so the durable plan/mode event lands AFTER the press that chose
+ * it. While an intent from an earlier press is in flight it — not the
+ * stale committed fold — decides the station, so repeated presses advance
+ * the cycle instead of re-issuing the same plan transition (the stuck
+ * plan-on/plan-off toggle). Undefined falls back to the committed fold.
+ */
+export function planCycleDecision(input: {
+  readonly names: readonly string[]
+  readonly current: string
+  readonly inPlan: boolean
+  readonly planAvailable: boolean
+  readonly planIntent?: boolean
+}): ModeCycleDecision | undefined {
+  const names = input.names
+  if (names.length === 0) return undefined
+  const first = names[0]
+  if ((input.planIntent ?? input.inPlan) === true) return { kind: 'plan-off', preset: names[1] ?? first }
+  const at = names.indexOf(input.current)
+  if (at === 0 && input.planAvailable) return { kind: 'plan-on' }
+  return { kind: 'permission', preset: names[(at + 1) % names.length] ?? first }
+}

package/src/runner/preferences.ts

@@ -0,0 +1,67 @@
+/** User-level preference files under the DSH home.
+ *
+ * The statusline, theme, language, and animations customizations each live in
+ * one small JSON file. They share exactly two policies: a missing file is the
+ * default and stays silent while a corrupt one degrades to the default with a
+ * surfaced warning (a user-authored customization must never fail silently),
+ * and every save goes through the serialized crash-atomic writer.
+ *
+ * @module @deepseek-ai/dsh-code/preferences
+ */
+
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { readSettingsObject, type UserSettingsPersistence } from '../settings-file.ts'
+
+/** Absolute path of one preference file under the DSH home. */
+export function preferencePath(fileName: string): string {
+  return join(homedir(), '.dsh', 'dsh-code', fileName)
+}
+
+/** Outcome of reading one preference file. */
+export interface PreferenceRead<T> {
+  /** Parsed value; undefined when the file is missing or corrupt (keep the default). */
+  readonly value?: T
+  /** Corruption message to surface; undefined for a missing or clean file. */
+  readonly warning?: string
+}
+
+/**
+ * Read one field of a preference file. A missing file is silence — the default
+ * stands and nothing is reported — while unreadable JSON or a non-object
+ * document both warn and keep the default.
+ * @param path - absolute path of the preference file.
+ * @param field - the JSON field the file carries.
+ * @param parse - narrows the raw field to the usable value.
+ * @returns the parsed value and/or the warning to surface.
+ */
+export function readPreference<T>(path: string, field: string, parse: (raw: unknown) => T): PreferenceRead<T> {
+  try {
+    return { value: parse(readSettingsObject(path)[field]) }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return {}
+    return { warning: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+/**
+ * Persist one preference field through the serialized crash-atomic writer.
+ * A failed write is reported through `onFailure` instead of rejecting.
+ * @param persistence - the shared user-settings writer.
+ * @param path - absolute path of the preference file.
+ * @param field - the JSON field the file carries.
+ * @param value - the value to store under `field`.
+ * @param onFailure - receives the failure message for a bounded notice.
+ */
+export function savePreference(
+  persistence: UserSettingsPersistence,
+  path: string,
+  field: string,
+  value: unknown,
+  onFailure: (message: string) => void,
+): void {
+  void persistence.save(path, JSON.stringify({ [field]: value }, null, 2) + '\n')
+    .catch((error: unknown) => {
+      onFailure(error instanceof Error ? error.message : String(error))
+    })
+}

package/src/runner/quit.ts

@@ -0,0 +1,53 @@
+/** Ordered terminal quit cleanup.
+ *
+ * Pure sequencing: every step rejection is contained and the exit request is
+ * always reached exactly once, so a failing flush never strands the process.
+ *
+ * @module @deepseek-ai/dsh-code/quit
+ */
+
+/** One ordered step of the terminal quit cleanup. */
+export interface QuitCleanupStep {
+  /** Step label used in diagnostics and tests. */
+  readonly name: string
+  /** The step's async work; a rejection is contained by the sequence. */
+  readonly run: () => Promise<void>
+}
+
+/**
+ * Run the ordered quit cleanup, then request exit. Every step rejection is
+ * contained (reported through `onError`) so a failed flush or dispose never
+ * skips the remaining cleanup; the exit request is always reached exactly
+ * once.
+ * @param steps - the cleanup steps in dependency order (settle the visible
+ * session, await the final in-flight composition, await durable recall).
+ * @param exit - the terminal exit request (code 0).
+ * @param onError - optional failure sink; called once per failing step and
+ * itself contained, so a throwing sink cannot abort the sequence.
+ * @returns the names of the steps that started, in order (for tests).
+ */
+export async function runQuitSequence(
+  steps: readonly QuitCleanupStep[],
+  exit: (code: number) => void,
+  onError?: (name: string, error: unknown) => void,
+): Promise<readonly string[]> {
+  const started: string[] = []
+  for (const step of steps) {
+    started.push(step.name)
+    try {
+      await step.run()
+    } catch (error) {
+      try {
+        onError?.(step.name, error)
+      } catch {
+        // The failure sink must never abort the cleanup sequence.
+      }
+    }
+  }
+  try {
+    exit(0)
+  } catch {
+    // The exit request itself must not become an unhandled rejection.
+  }
+  return started
+}

package/src/runner/search-rows.ts

@@ -0,0 +1,55 @@
+/** Cross-session search rows for the /search panel.
+ *
+ * Owns the panel row shape and the pure mapping from a session-query hit, so
+ * the row contract does not live inside the panel component that renders it
+ * and the runner can build rows without importing the panel module.
+ *
+ * @module @deepseek-ai/dsh-code/search-rows
+ */
+
+import type { SessionHeader } from '@deepseek-ai/dsh-session'
+
+/** One cross-session full-text search hit mapped from the session-query engine. */
+export interface SearchRow {
+  /** Session id (Enter resumes it through the switch machinery). */
+  readonly id: string
+  /** Display label: session title or the short id form. */
+  readonly label: string
+  /** Secondary facts line (workspace · preset markers). */
+  readonly detail: string
+  /** Bounded plain-text excerpt around the strongest match. */
+  readonly snippet: string
+  /** Match timestamp (relative labels derive from it). */
+  readonly updatedAt: number
+  /** Whether the hit is a delegated subagent conversation (not resumable). */
+  readonly subagent: boolean
+  /** Whether Enter may switch into it. */
+  readonly resumable: boolean
+}
+
+/**
+ * Map one cross-session full-text hit onto the /search panel's row (pure).
+ * Labels fall back to the short id form — the engine's hit carries the
+ * strongest matching event, not the title observation.
+ */
+export function searchHitToRow(hit: {
+  header: SessionHeader
+  bestMatch: { snippet: string; time: number }
+}): SearchRow {
+  const subagent = hit.header.origin === 'subagent'
+  const cwd = hit.header.cwd ?? ''
+  // Session cwds may arrive in either separator style regardless of the
+  // observing host (a workspace synced from Windows), so split on both.
+  const workspace = cwd.split(/[\\/]/u).filter(part => part !== '').at(-1) ?? ''
+  const preset = hit.header.agentPreset ?? ''
+  const flat = hit.bestMatch.snippet.replace(/\s+/gu, ' ').trim()
+  return {
+    id: hit.header.id,
+    label: hit.header.id.slice(-12),
+    detail: [workspace, preset].filter(part => part !== '').join(' · '),
+    snippet: flat.length > 158 ? `${flat.slice(0, 157)}…` : flat,
+    updatedAt: hit.bestMatch.time,
+    subagent,
+    resumable: !subagent,
+  }
+}