dsh-code 1.0.2 → 1.0.3

package/src/editor-keys.ts

@@ -0,0 +1,371 @@
+/**
+ * VS Code-family terminal keybinding repair. VS Code hands Ctrl+R to the
+ * workbench (Open Recent) even while an integrated terminal owns focus, so
+ * the reasoning-fold key never reaches the TUI. Workspace-scoped keybindings
+ * do not exist, so the fix is one user-level keybindings.json rule that
+ * forwards the raw Ctrl byte via sendSequence under terminalFocus. This
+ * module detects the hosting editor variant, resolves its user
+ * keybindings.json, and merges the rule idempotently; pure merge/detect
+ * helpers are separated from the fs orchestration so both stay testable.
+ * @module @deepseek-ai/dsh-code/editor-keys
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+
+/** Integrated-terminal editor variants this module can repair. */
+export type EditorTerminalFamily = 'vscode' | 'cursor' | 'vscodium' | 'windsurf'
+
+/** Install directory names per family ('vscode' covers stable and Insiders). */
+const FAMILY_DIRS: Record<EditorTerminalFamily, readonly string[]> = {
+  vscode: ['Code', 'Code - Insiders'],
+  cursor: ['Cursor'],
+  vscodium: ['VSCodium'],
+  windsurf: ['Windsurf'],
+}
+
+/**
+ * Detect the editor hosting this integrated terminal.
+ * @param env - process environment (TERM_PROGRAM decides; case/whitespace tolerant).
+ * @returns the family, or undefined outside VS Code-family terminals.
+ */
+export function detectEditorTerminalFamily(env: NodeJS.ProcessEnv = process.env): EditorTerminalFamily | undefined {
+  const program = env.TERM_PROGRAM?.trim().toLowerCase()
+  if (program === 'vscode' || program === 'cursor' || program === 'vscodium' || program === 'windsurf') return program
+  return undefined
+}
+
+/**
+ * Whether the pty is hosted away from the editor UI (ssh/container/tunnel).
+ * Keybindings live on the client machine, so a remote session must never
+ * write them server-side.
+ */
+export function isRemoteTerminalEnv(env: NodeJS.ProcessEnv = process.env): boolean {
+  return (env.VSCODE_IPC_HOOK_CLI ?? '').trim() !== ''
+}
+
+/** Filesystem anchors used to resolve editor config paths (injectable for tests). */
+export interface EditorPathContext {
+  /** User home directory. */
+  homedir: string
+  /** %APPDATA% on Windows; only read for win32 resolution. */
+  appdata?: string
+  /** Node platform qualifier. */
+  platform: NodeJS.Platform
+}
+
+/**
+ * Resolve the user keybindings.json candidates for one family, most likely
+ * install first. Only paths that exist on disk are repaired.
+ */
+export function editorKeybindingCandidates(family: EditorTerminalFamily, context: EditorPathContext): readonly string[] {
+  return FAMILY_DIRS[family].map(dir => {
+    if (context.platform === 'win32') {
+      return join(context.appdata ?? join(context.homedir, 'AppData', 'Roaming'), dir, 'User', 'keybindings.json')
+    }
+    if (context.platform === 'darwin') {
+      return join(context.homedir, 'Library', 'Application Support', dir, 'User', 'keybindings.json')
+    }
+    return join(context.homedir, '.config', dir, 'User', 'keybindings.json')
+  })
+}
+
+/** The one workbench rule that hands Ctrl+R to the focused terminal. */
+export const CTRL_R_PASSTHROUGH_RULE = {
+  key: 'ctrl+r',
+  command: 'workbench.action.terminal.sendSequence',
+  args: { text: '\u0012' },
+  when: 'terminalFocus',
+} as const
+
+/** Serialized rule block (4-space indent, the editors' default style). */
+const RULE_BLOCK = [
+  '    {',
+  '        "key": "ctrl+r",',
+  '        "command": "workbench.action.terminal.sendSequence",',
+  '        "args": { "text": "\\u0012" },',
+  '        "when": "terminalFocus"',
+  '    }',
+].join('\n')
+
+/** Fresh-file template carrying the editors' standard header comment. */
+const KEYBINDINGS_TEMPLATE = '// Place your key bindings in this file to override the defaults\n[\n' + RULE_BLOCK + '\n]\n'
+
+/** Whether one parsed keybindings entry already forwards Ctrl+R to the terminal. */
+function isCtrlRPassthroughEntry(entry: unknown): boolean {
+  if (typeof entry !== 'object' || entry === null) return false
+  const record = entry as Record<string, unknown>
+  if (record.command !== CTRL_R_PASSTHROUGH_RULE.command) return false
+  if (typeof record.key !== 'string' || record.key.trim().toLowerCase() !== CTRL_R_PASSTHROUGH_RULE.key) return false
+  const args = record.args
+  if (typeof args !== 'object' || args === null) return false
+  const text = (args as Record<string, unknown>).text
+  if (typeof text !== 'string' || !text.includes('\u0012')) return false
+  return typeof record.when === 'string' && /\bterminalFocus\b/u.test(record.when)
+}
+
+/**
+ * Remove // and block comments from one JSONC document. Double-quoted strings
+ * survive untouched, so comment markers inside string values are preserved.
+ */
+export function stripJsoncComments(text: string): string {
+  let out = ''
+  let index = 0
+  let inString = false
+  while (index < text.length) {
+    const char = text[index]!
+    if (inString) {
+      out += char
+      if (char === '\\' && index + 1 < text.length) {
+        out += text[index + 1]!
+        index += 2
+        continue
+      }
+      if (char === '"') inString = false
+      index += 1
+      continue
+    }
+    if (char === '"') {
+      inString = true
+      out += char
+      index += 1
+      continue
+    }
+    if (char === '/' && text[index + 1] === '/') {
+      while (index < text.length && text[index] !== '\n') index += 1
+      continue
+    }
+    if (char === '/' && text[index + 1] === '*') {
+      index += 2
+      while (index < text.length && !(text[index] === '*' && text[index + 1] === '/')) {
+        if (text[index] === '\n') out += '\n'
+        index += 1
+      }
+      index += 2
+      continue
+    }
+    out += char
+    index += 1
+  }
+  return out
+}
+
+/** Drop commas directly before a closing bracket (string-aware). */
+function removeTrailingCommas(text: string): string {
+  let out = ''
+  let index = 0
+  let inString = false
+  while (index < text.length) {
+    const char = text[index]!
+    if (inString) {
+      out += char
+      if (char === '\\' && index + 1 < text.length) {
+        out += text[index + 1]!
+        index += 2
+        continue
+      }
+      if (char === '"') inString = false
+      index += 1
+      continue
+    }
+    if (char === '"') {
+      inString = true
+      out += char
+      index += 1
+      continue
+    }
+    if (char === ',') {
+      let peek = index + 1
+      while (peek < text.length && (text[peek] === ' ' || text[peek] === '\t' || text[peek] === '\n' || text[peek] === '\r')) peek += 1
+      const next = text[peek]
+      if (next === '}' || next === ']') {
+        index += 1
+        continue
+      }
+    }
+    out += char
+    index += 1
+  }
+  return out
+}
+
+/** Parse one JSONC document; trailing commas are tolerated. */
+export function parseJsonc(text: string): unknown {
+  return JSON.parse(removeTrailingCommas(stripJsoncComments(text)))
+}
+
+/** Raw index of the top-level rule array's opening bracket, or -1 when absent. */
+function rawOpenBracketIndex(text: string): number {
+  let index = 0
+  let inString = false
+  while (index < text.length) {
+    const char = text[index]!
+    if (inString) {
+      if (char === '\\') {
+        index += 2
+        continue
+      }
+      if (char === '"') inString = false
+      index += 1
+      continue
+    }
+    if (char === '"') {
+      inString = true
+      index += 1
+      continue
+    }
+    if (char === '/' && text[index + 1] === '/') {
+      while (index < text.length && text[index] !== '\n') index += 1
+      continue
+    }
+    if (char === '/' && text[index + 1] === '*') {
+      index += 2
+      while (index < text.length && !(text[index] === '*' && text[index + 1] === '/')) index += 1
+      index += 2
+      continue
+    }
+    if (char === '[') return index
+    index += 1
+  }
+  return -1
+}
+
+/** Outcome of merging the passthrough rule into one keybindings document. */
+export type KeybindingsMerge =
+  | { readonly status: 'present' }
+  | { readonly status: 'updated'; readonly text: string }
+  | { readonly status: 'created'; readonly text: string }
+
+/**
+ * Merge the Ctrl+R passthrough into one keybindings.json document. The raw
+ * text is preserved verbatim (comments included); the rule is inserted right
+ * after the array opener so it cannot be shadowed by later conflicting user
+ * rules. Missing files resolve to a fresh template.
+ * @throws when the document does not carry a rule array.
+ */
+export function mergeCtrlRPassthrough(raw: string | undefined): KeybindingsMerge {
+  if (raw === undefined) return { status: 'created', text: KEYBINDINGS_TEMPLATE }
+  const parsed = parseJsonc(raw)
+  if (!Array.isArray(parsed)) throw new Error('keybindings.json does not contain a rule array')
+  if (parsed.some(isCtrlRPassthroughEntry)) return { status: 'present' }
+  const open = rawOpenBracketIndex(raw)
+  if (open === -1) throw new Error('keybindings.json does not contain a rule array')
+  const insert = parsed.length > 0 ? '\n' + RULE_BLOCK + ',' : '\n' + RULE_BLOCK
+  return { status: 'updated', text: raw.slice(0, open + 1) + insert + raw.slice(open + 1) }
+}
+
+/** User-level marker file content: the startup hint fires at most once per install. */
+export interface EditorKeysFlag {
+  hintShownAt?: string
+}
+
+/** Parse one flag file snapshot; missing or corrupt content degrades to unshown. */
+export function parseEditorKeysFlag(raw: string | undefined): EditorKeysFlag {
+  if (raw === undefined) return {}
+  try {
+    const parsed: unknown = JSON.parse(raw)
+    if (typeof parsed !== 'object' || parsed === null) return {}
+    const shown = (parsed as Record<string, unknown>).hintShownAt
+    return typeof shown === 'string' ? { hintShownAt: shown } : {}
+  } catch {
+    return {}
+  }
+}
+
+/** Persist the shown marker; best-effort, the hint is cosmetic and never a gate. */
+export async function markEditorKeysHintShown(path: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, JSON.stringify({ hintShownAt: new Date().toISOString() }, null, 2) + '\n', 'utf8')
+}
+
+/** Inputs shared by the apply and startup-hint flows. */
+export interface EditorKeysEnv {
+  /** Process environment (TERM_PROGRAM / VSCODE_IPC_HOOK_CLI). */
+  env: NodeJS.ProcessEnv
+  /** Filesystem anchors for editor config resolution. */
+  paths: EditorPathContext
+  /** Absolute path of the one-shot hint marker under the DSH home. */
+  flagPath: string
+}
+
+/** Read one file if it exists; undefined otherwise (ENOENT and unreadable both). */
+async function readIfPresent(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Apply the Ctrl+R passthrough to every local keybindings.json of the hosting
+ * editor and mark the startup hint shown. Existing files get a .dsh-bak
+ * backup before the first write.
+ * @returns a one-line user-facing summary.
+ * @throws with an actionable message when the environment cannot be repaired.
+ */
+export async function applyCtrlRPassthrough({ env, paths, flagPath }: EditorKeysEnv): Promise<string> {
+  const family = detectEditorTerminalFamily(env)
+  if (family === undefined) {
+    throw new Error(
+      'not a VS Code-family terminal (TERM_PROGRAM=' + (env.TERM_PROGRAM?.trim() || 'unset') + '); add the ctrl+r rule to keybindings.json manually',
+    )
+  }
+  if (isRemoteTerminalEnv(env)) {
+    throw new Error('remote terminal detected; apply the keybindings rule on the local machine instead')
+  }
+  const candidates = editorKeybindingCandidates(family, paths)
+  const targets: string[] = []
+  for (const candidate of candidates) {
+    if (await readIfPresent(candidate) !== undefined) targets.push(candidate)
+  }
+  if (targets.length === 0) targets.push(candidates[0]!)
+  const updated: string[] = []
+  const present: string[] = []
+  for (const target of targets) {
+    const raw = await readIfPresent(target)
+    const merge = mergeCtrlRPassthrough(raw)
+    if (merge.status === 'present') {
+      present.push(target)
+      continue
+    }
+    await mkdir(dirname(target), { recursive: true })
+    if (raw !== undefined) await writeFile(target + '.dsh-bak', raw, 'utf8')
+    await writeFile(target, merge.text, 'utf8')
+    updated.push(target)
+  }
+  await markEditorKeysHintShown(flagPath).catch(() => {})
+  const label = (target: string): string => basename(dirname(dirname(target)))
+  if (updated.length === 0) {
+    return 'ctrl+r passthrough already configured in ' + present.map(label).join(', ')
+  }
+  return 'ctrl+r passthrough written to ' + updated.map(label).join(', ') + ' — effective immediately'
+}
+
+/**
+ * Resolve the one-shot startup hint for VS Code-family terminals. Fires at
+ * most once per install (flag file), never when the passthrough rule is
+ * already present, and never in remote ptys where the repair cannot run.
+ * @returns the hint line, or undefined to stay silent.
+ */
+export async function resolveEditorKeysStartupHint({ env, paths, flagPath }: EditorKeysEnv): Promise<string | undefined> {
+  const flag = parseEditorKeysFlag(await readIfPresent(flagPath))
+  if (flag.hintShownAt !== undefined) return undefined
+  const family = detectEditorTerminalFamily(env)
+  if (family === undefined || isRemoteTerminalEnv(env)) return undefined
+  for (const candidate of editorKeybindingCandidates(family, paths)) {
+    const raw = await readIfPresent(candidate)
+    if (raw === undefined) continue
+    try {
+      const parsed: unknown = parseJsonc(raw)
+      if (Array.isArray(parsed) && parsed.some(isCtrlRPassthroughEntry)) {
+        await markEditorKeysHintShown(flagPath).catch(() => {})
+        return undefined
+      }
+    } catch {
+      // An unparseable config still deserves the hint; apply reports the error.
+    }
+  }
+  await markEditorKeysHintShown(flagPath).catch(() => {})
+  return 'run /vscode-keys to pass ctrl+r through this editor (alt+r works meanwhile)'
+}

package/src/git-workflow.ts

@@ -44,9 +44,9 @@ export function parseGitDiffSpec(argument: string): GitDiffSpec {
   return { label: `changes since ${value}`, args: ['diff', '--no-ext-diff', '--unified=3', value, '--'] }
 }
 
-function executeGit(cwd: string, args: readonly string[]): Promise<string> {
+function executeGit(cwd: string, args: readonly string[], signal?: AbortSignal): Promise<string> {
   return new Promise((resolve, reject) => {
-    execFile('git', [...args], { cwd, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, windowsHide: true }, (error, stdout, stderr) => {
+    execFile('git', [...args], { cwd, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, windowsHide: true, signal }, (error, stdout, stderr) => {
       if (error !== null) {
         reject(new Error(stderr.trim() || error.message))
         return
@@ -56,17 +56,21 @@ function executeGit(cwd: string, args: readonly string[]): Promise<string> {
   })
 }
 
-/** Load one complete textual diff without invoking external diff drivers. */
-export async function loadGitDiff(cwd: string, argument: string): Promise<GitDiffView> {
+/**
+ * Load one complete textual diff without invoking external diff drivers.
+ * @param signal - aborted by the caller on session switches/quit, killing the
+ * git subprocess instead of letting a stale repository's diff land later.
+ */
+export async function loadGitDiff(cwd: string, argument: string, signal?: AbortSignal): Promise<GitDiffView> {
   const spec = parseGitDiffSpec(argument)
   try {
-    const text = await executeGit(cwd, spec.args)
+    const text = await executeGit(cwd, spec.args, signal)
     return { title: `git diff - ${spec.label}`, files: parseGitDiffFiles(text) }
   } catch (error: unknown) {
     // An unborn repository has no HEAD. Preserve useful unstaged output for
     // the default form while still surfacing all other Git failures.
     if (argument.trim() !== '') throw error
-    const text = await executeGit(cwd, ['diff', '--no-ext-diff', '--unified=3', '--'])
+    const text = await executeGit(cwd, ['diff', '--no-ext-diff', '--unified=3', '--'], signal)
     return { title: 'git diff - working tree', files: parseGitDiffFiles(text) }
   }
 }