dsh-llm-fallbacks 0.4.3 → 0.5.0

package/scripts/repair-fallbacks-switch-logs.ts

@@ -1,374 +0,0 @@
-/**
- * repair-fallbacks-switch-logs.ts — repair session logs poisoned by the old
- * plugin's durable `fallbacks/switch` events.
- *
- * Background: until Task 1 of `fallbacks-session-event-stop-write`, the
- * plugin wrote durable `fallbacks/switch` session events. Host persistence
- * (`assertEventsSupported`) refuses to load any session log whose event type
- * is outside its baked catalog unless the event carries `ignorable: true`.
- * `Session.append` cannot write `ignorable`, and runtime registration proved
- * ineffective (module-instance mismatch). Session logs written while the old
- * plugin was active therefore fail to load after a dsh restart. This script
- * marks those events `ignorable: true` so the read path accepts them again.
- *
- * Session log format (`~/.dsh/sessions/<namespace>/<session-id>/session.jsonl.zstd`):
- *   - concatenated-zstd-frame container: **first frame MUST decode to
- *     exactly one header line** (rc.7 `assertZstdHeaderFrame`:
- *     `indexOf(10) === length-1`). Subsequent frames hold events.
- *   - `node:zlib.zstdDecompress` only decodes the FIRST frame, so this
- *     script shells out to the `zstd` CLI (`zstd -d -c` decodes every
- *     concatenated frame). Re-encoding MUST emit frame-1 = header only
- *     + a following frame for the rest — a single-frame rewrite of the
- *     whole log fails host boot (`first frame is not exactly one header line`).
- *
- * IMPORTANT: stop dsh before running with `--apply`. The script replaces a
- * session log via read → transform → atomic rename; a live dsh that appends
- * a new zstd frame between the read and the rename would have that frame
- * lost (read-modify-write race). Report / `--dry-run` runs are safe any
- * time — they never write files.
- *
- * Usage (from the repo root, via tsx — the package.json
- * `repair:fallbacks-switch-logs` script):
- *   pnpm repair:fallbacks-switch-logs -- --dry-run
- *   pnpm repair:fallbacks-switch-logs -- --apply --backup
- *   pnpm repair:fallbacks-switch-logs -- --root /tmp/repair-fixture --dry-run
- *
- * Flags:
- *   --root <dir>   session root to walk (default: ~/.dsh/sessions)
- *   --dry-run      report only — never write files
- *   --backup       required with --apply: copy the original to <file>.bak
- *                  before replacing (apply is refused without it)
- *   --apply        actually replace repaired files; requires --backup and a
- *                  stopped dsh; without it (or with --dry-run) the run only
- *                  reports would-change
- *
- * Safe by construction: a file is only replaced after its re-encoded form
- * passes `zstd -t`, has a one-line first frame, and carries the original
- * file's permission bits; a file that fails to decompress or re-encode is
- * reported and skipped (never corrupted); the replace is an atomic rename
- * of a temp file in the same directory. Report/dry-run mode performs no
- * filesystem writes at all.
- */
-import { execFileSync } from 'node:child_process'
-import {
-  chmodSync,
-  copyFileSync,
-  existsSync,
-  readdirSync,
-  renameSync,
-  rmSync,
-  statSync,
-  writeFileSync,
-} from 'node:fs'
-import { homedir } from 'node:os'
-import { basename, dirname, join } from 'node:path'
-import { pathToFileURL } from 'node:url'
-
-/** Decoded plaintext cap for one session log (512 MB; logs can be large). */
-const MAX_BUFFER = 512 * 1024 * 1024
-
-/** A line matched only when the PARSED type is exactly `fallbacks/switch`. */
-const SWITCH_TYPE = 'fallbacks/switch'
-
-export interface MarkFallbacksSwitchIgnorableResult {
-  lines: string[]
-  changed: number
-}
-
-/**
- * Pure transform: mark `fallbacks/switch` events without an `ignorable` field
- * as `ignorable: true`.
- *
- * - `type === 'session'` header lines are skipped untouched;
- * - every other line (non-switch events, malformed JSON, empty lines, switch
- *   events that already carry `ignorable`) passes through byte-identical;
- * - switch events are re-serialized with `ignorable` appended (insertion
- *   order — the read path only reads `event.ignorable`, so field position is
- *   irrelevant); `seq`/`time`/`data` are preserved verbatim;
- * - `changed` counts only lines that were modified.
- *
- * Matching is on the parsed `type` field, never on the raw string — the
- * substring `fallbacks/switch` legitimately appears inside user/message data
- * and must not be treated as an event.
- */
-export function markFallbacksSwitchIgnorable(lines: string[]): MarkFallbacksSwitchIgnorableResult {
-  const out = new Array<string>(lines.length)
-  let changed = 0
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]
-    if (line === '') {
-      out[i] = line
-      continue
-    }
-    let parsed: unknown
-    try {
-      parsed = JSON.parse(line)
-    } catch {
-      // Malformed JSON — pass through untouched, never corrupt.
-      out[i] = line
-      continue
-    }
-    if (parsed === null || typeof parsed !== 'object') {
-      out[i] = line
-      continue
-    }
-    const event = parsed as Record<string, unknown>
-    if (event.type === 'session') {
-      out[i] = line
-      continue
-    }
-    if (
-      event.type === SWITCH_TYPE &&
-      !Object.prototype.hasOwnProperty.call(event, 'ignorable')
-    ) {
-      out[i] = JSON.stringify({ ...event, ignorable: true })
-      changed++
-      continue
-    }
-    out[i] = line
-  }
-  return { lines: out, changed }
-}
-
-/* ------------------------------------------------------------------ */
-/* CLI                                                                */
-/* ------------------------------------------------------------------ */
-
-interface CliOptions {
-  root: string
-  dryRun: boolean
-  backup: boolean
-  apply: boolean
-}
-
-function usage(): string {
-  return `usage: tsx scripts/repair-fallbacks-switch-logs.ts [--root DIR] [--dry-run] [--backup] [--apply]
-
-  --root DIR    session root to walk (default: ~/.dsh/sessions)
-  --dry-run     report only — never write files
-  --backup      required with --apply: copy the original to <file>.bak before
-                replacing
-  --apply       actually replace repaired files (requires --backup; stop dsh
-                before applying)`
-}
-
-function expandHome(p: string): string {
-  if (p === '~') return homedir()
-  return p.startsWith('~/') ? join(homedir(), p.slice(2)) : p
-}
-
-export function parseArgs(argv: string[]): CliOptions {
-  let root = join(homedir(), '.dsh', 'sessions')
-  let dryRun = false
-  let backup = false
-  let apply = false
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i]
-    // pnpm run <script> -- <args> forwards the separator `--`; skip it.
-    if (arg === '--') continue
-    switch (arg) {
-      case '--root':
-        i++
-        if (i >= argv.length) throw new Error(`${usage()}\n\n--root requires a directory argument`)
-        root = expandHome(argv[i])
-        break
-      case '--dry-run':
-        dryRun = true
-        break
-      case '--backup':
-        backup = true
-        break
-      case '--apply':
-        apply = true
-        break
-      default:
-        throw new Error(`${usage()}\n\nunknown argument: ${arg}`)
-    }
-  }
-  if (apply && !backup) {
-    throw new Error(
-      `${usage()}\n\n--apply requires --backup: real modification must keep a .bak copy of every replaced session log (run with --dry-run first to review)`,
-    )
-  }
-  return { root, dryRun, backup, apply }
-}
-
-/** Resolve the zstd CLI binary; throw a clear error when it is missing. */
-function resolveZstd(): string {
-  try {
-    const resolved = execFileSync('which', ['zstd'], { encoding: 'utf8' }).trim()
-    if (resolved) return resolved
-  } catch {
-    // fall through to the direct check below
-  }
-  try {
-    execFileSync('zstd', ['--version'], { stdio: 'ignore' })
-    return 'zstd'
-  } catch {
-    throw new Error(
-      'zstd CLI not found on PATH. Install it (e.g. `brew install zstd`) and retry.',
-    )
-  }
-}
-
-/** Recursively find every `<namespace>/<session-id>/session.jsonl.zstd` under root. */
-function findSessionLogs(root: string): string[] {
-  const found: string[] = []
-  const walk = (dir: string): void => {
-    const entries = readdirSync(dir, { withFileTypes: true })
-    for (const entry of entries) {
-      const full = join(dir, entry.name)
-      if (entry.isDirectory()) {
-        walk(full)
-      } else if (entry.isFile() && entry.name === 'session.jsonl.zstd') {
-        found.push(full)
-      }
-    }
-  }
-  walk(root)
-  return found.sort()
-}
-
-type FileOutcome =
-  | { action: 'unchanged'; changed: 0 }
-  | { action: 'would-change'; changed: number }
-  | { action: 'changed'; changed: number }
-  | { action: 'error'; changed: number; error: string }
-
-/**
- * Encode repaired plaintext as concatenated zstd frames that rc.7 will
- * accept: frame 1 = header line + `\n` only; frame 2 = remaining lines.
- */
-export function encodeRepairedSessionLog(zstd: string, lines: string[]): Buffer {
-  const header = lines[0] ?? ''
-  const headerPlain = header.endsWith('\n') ? header : `${header}\n`
-  const zstdOut = { input: headerPlain, maxBuffer: MAX_BUFFER }
-  const frame1 = execFileSync(zstd, ['-c'], zstdOut)
-  const rest = lines.slice(1)
-  if (rest.length === 0 || (rest.length === 1 && rest[0] === '')) return frame1
-  const restPlain = rest.join('\n')
-  const frame2 = execFileSync(zstd, ['-c'], {
-    input: restPlain.endsWith('\n') ? restPlain : `${restPlain}\n`,
-    maxBuffer: MAX_BUFFER,
-  })
-  return Buffer.concat([frame1, frame2])
-}
-
-/**
- * Decompress all frames of one log, transform it, and (only when actually
- * applying) atomically replace it with a two-frame re-encode (header frame
- * + events frame) that passed `zstd -t` and carries the original file's
- * permission bits. Report/dry-run returns would-change WITHOUT touching the
- * filesystem.
- */
-export function processFile(zstd: string, file: string, opts: CliOptions): FileOutcome {
-  let plain: string
-  try {
-    plain = execFileSync(zstd, ['-d', '-c', file], { encoding: 'utf8', maxBuffer: MAX_BUFFER })
-  } catch (err) {
-    return {
-      action: 'error',
-      changed: 0,
-      error: `zstd -d -c failed: ${err instanceof Error ? err.message : String(err)}`,
-    }
-  }
-
-  const { lines, changed } = markFallbacksSwitchIgnorable(plain.split('\n'))
-  if (changed === 0) return { action: 'unchanged', changed: 0 }
-
-  // Report / dry-run: nothing to write — return would-change right after the
-  // transform (parseArgs refuses `--apply` without `--backup`, so any run
-  // reaching here without `write` is a report-only invocation).
-  const write = opts.apply && !opts.dryRun
-  if (!write) return { action: 'would-change', changed }
-
-  // Apply: temp files live next to the target so the final rename is atomic
-  // (same filesystem) and the walker never mistakes them for session logs.
-  const dir = dirname(file)
-  const tmpZstd = join(dir, `.${basename(file)}.${process.pid}.zstd.tmp`)
-  const mode = statSync(file).mode & 0o7777
-  try {
-    writeFileSync(tmpZstd, encodeRepairedSessionLog(zstd, lines))
-    execFileSync(zstd, ['-t', tmpZstd], { stdio: 'ignore' })
-    copyFileSync(file, `${file}.bak`)
-    chmodSync(tmpZstd, mode)
-    renameSync(tmpZstd, file)
-  } catch (err) {
-    return {
-      action: 'error',
-      changed,
-      error: `re-encode/validate failed: ${err instanceof Error ? err.message : String(err)}`,
-    }
-  } finally {
-    rmSync(tmpZstd, { force: true })
-  }
-  return { action: 'changed', changed }
-}
-
-export function main(): void {
-  const opts = parseArgs(process.argv.slice(2))
-  const zstd = resolveZstd()
-  if (!existsSync(opts.root)) {
-    console.error(`repair-fallbacks-switch-logs: root directory not found: ${opts.root}`)
-    process.exit(1)
-  }
-
-  const files = findSessionLogs(opts.root)
-  if (!files.length) {
-    console.log(`repair-fallbacks-switch-logs: no session.jsonl.zstd files under ${opts.root}`)
-    return
-  }
-
-  const mode = opts.dryRun ? 'dry-run' : opts.apply ? 'apply' : 'report'
-  console.log(`root: ${opts.root}`)
-  console.log(`mode: ${mode}${opts.backup ? ' (backup .bak before replace)' : ''}`)
-  console.log(`zstd: ${zstd}`)
-  console.log(`files: ${files.length}`)
-
-  let totalFiles = 0
-  let totalEvents = 0
-  let skipped = 0
-  let errors = 0
-  for (const file of files) {
-    const outcome = processFile(zstd, file, opts)
-    switch (outcome.action) {
-      case 'unchanged':
-        skipped++
-        console.log(`  unchanged    ${file}`)
-        break
-      case 'would-change':
-        totalFiles++
-        totalEvents += outcome.changed
-        console.log(`  would-change ${outcome.changed}  ${file}`)
-        break
-      case 'changed':
-        totalFiles++
-        totalEvents += outcome.changed
-        console.log(`  changed      ${outcome.changed}  ${file}`)
-        break
-      case 'error':
-        errors++
-        console.error(`  error        ${file}: ${outcome.error}`)
-        break
-    }
-  }
-
-  console.log(
-    `\nsummary: ${totalFiles} file(s), ${totalEvents} fallbacks/switch event(s) ` +
-      `${mode === 'dry-run' || mode === 'report' ? 'to be marked' : 'marked'}, ` +
-      `${skipped} unchanged skipped, ${errors} error(s)`,
-  )
-  if (errors) process.exitCode = 1
-}
-
-// Run only when executed directly (tsx scripts/repair-fallbacks-switch-logs.ts)
-// — importing the module (unit tests) must not start the CLI.
-const entry = process.argv[1] ? pathToFileURL(process.argv[1]).href : ''
-if (import.meta.url === entry) {
-  try {
-    main()
-  } catch (err) {
-    console.error(`\nrepair-fallbacks-switch-logs failed: ${err instanceof Error ? err.message : err}`)
-    process.exit(1)
-  }
-}