@falling-ts/dsh-force-compact 0.2.0

package/src/core/crashnet.js

@@ -0,0 +1,215 @@
+/**
+ * Universal crash net for every exported method entry in the plugin.
+ *
+ * Two layers:
+ * 1. **Entry wrappers** — every exported function routed through
+ *    {@link guardFn} gets its ENTIRE body (the topmost level of the call
+ *    tree) covered: on throw, a detailed diagnostic — function name, the exact
+ *    throw site (`file:line:column`), the deepest plugin frame, the nearest
+ *    NON-plugin frame (usually the vendored caller that actually faulted),
+ *    and the full call stack — is appended to the plugin's durable log file.
+ * 2. **Process-wide net** ({@link installCrashNet}) — `uncaughtException` +
+ *    `unhandledRejection` handlers (installed at most once per process) that
+ *    classify whatever escapes every entry point the same way.
+ *
+ * Output goes straight to the durable debug log (same destination convention
+ * as `core/log.js`: `~/.dsh/logs/dsh-force-compact.log`), bypassing
+ * `ctx.logger` entirely so a crash remains reconstructable even before the
+ * logger is wired or after a process death. Every emission site is itself
+ * self-defensive: a logger failure can never disturb a business path.
+ *
+ * @module @falling-ts/dsh-force-compact/crashnet
+ */
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+/** Expand a leading `~` using the process user home (Windows: USERPROFILE). */
+function expandTilde(value) {
+  if (typeof value !== 'string') return value
+  const trimmed = value.trim()
+  if (trimmed !== '~' && !trimmed.startsWith('~/') && !trimmed.startsWith('~\\')) return value
+  const rest = trimmed === '~' ? '' : trimmed.slice(2)
+  const home = process.env.USERPROFILE || process.env.HOME || (os.homedir && os.homedir())
+  if (home === undefined || home === null || typeof home !== 'string' || home.length === 0) return value
+  return path.join(home, rest)
+}
+
+/** Durable crash-log path — identical convention to `core/log.js`. */
+function crashLogPath() {
+  try {
+    return expandTilde('~/.dsh/logs/dsh-force-compact.log')
+  } catch {
+    return ''
+  }
+}
+
+/** Append one line to the durable crash log. Never throws. */
+function appendDiag(line) {
+  try {
+    const p = crashLogPath()
+    if (p === '') return
+    fs.mkdirSync(path.dirname(p), { recursive: true })
+    fs.appendFileSync(p, line + '\n', 'utf8')
+  } catch (_diagnosticFailure) {
+    // A diagnostic sink must never break a business path.
+  }
+}
+
+/** True when a stack-frame line points inside this plugin package. */
+function isPluginFrame(frame) {
+  return typeof frame === 'string' && frame.indexOf('dsh-force-compact') >= 0
+}
+
+/** Extract a human-readable `file:line:col` from one stack-frame line. */
+function frameLocation(frame) {
+  if (typeof frame !== 'string') return String(frame)
+  const match = /\(?([^(\n]*?)(?:(\d+))?(?:(\d+))?(\))?$/g.exec(frame.trim())
+  if (match === null) return frame.trim()
+  const file = (match[1] || '').trim()
+  const line = match[2]
+  const col = match[3]
+  if (file === '' && line === undefined) return frame.trim()
+  if (line === undefined) return file
+  return `${file}:${line}${col === undefined ? '' : ':' + col}`
+}
+
+/**
+ * Split a stack string into plugin-side and non-plugin frames.
+ * @param {string} stackStack the raw `Error.stack` text.
+ * @returns {{ pluginFrames: string[], foreignFrames: string[] }}
+ */
+function partitionFrames(stackStack) {
+  const pluginFrames = []
+  const foreignFrames = []
+  if (typeof stackStack !== 'string') return { pluginFrames, foreignFrames }
+  for (const raw of stackStack.split('\n')) {
+    const trimmed = raw.trim()
+    if (trimmed.length === 0) continue
+    if (/(^|\()dsh-force-compact/.test(trimmed)) pluginFrames.push(trimmed)
+    else if (/^at /.test(trimmed)) foreignFrames.push(trimmed)
+  }
+  return { pluginFrames, foreignFrames }
+}
+
+/**
+ * Render the multi-line crash diagnostic for one thrown value.
+ * @param {string} label stable display name of the wrapping entry.
+ * @param {unknown} error the thrown value.
+ * @param {string} site the exact `file:line:col` where the throw originated,
+ *   or the sentinel marker when unavailable.
+ * @returns {string[]} formatted lines ready for the durable log.
+ */
+export function renderCrash(label, error, site) {
+  const isErrorLike = error instanceof Error
+  const message = isErrorLike ? (error.message ?? '(no message)') : (typeof error === 'string' ? error : (function stringifySafe(v) { try { return JSON.stringify(v) } catch { return String(v) } })(error))
+  const stackString = (isErrorLike && typeof error.stack === 'string' && error.stack.length > 0) ? error.stack : ''
+  const { pluginFrames, foreignFrames } = partitionFrames(stackString)
+  const lines = []
+  lines.push(`[force-compact][CRASHNET] ENTRY FAILURE — ${label}`)
+  lines.push(`  message: ${message}`)
+  lines.push(`  thrownAt: ${typeof site === 'string' && site.length > 0 ? site : '(not captured)'}`)
+  if (pluginFrames.length > 0) lines.push(`  deepest-plugin-frame: ${frameLocation(pluginFrames[pluginFrames.length - 1])}`)
+  if (foreignFrames.length > 0) lines.push(`  nearest-non-plugin-frame: ${frameLocation(foreignFrames[foreignFrames.length - 1])}`)
+  const stackLines = stackString.length > 0 ? stackString.split('\n') : []
+  lines.push(`  ---- call stack (up to 40 frames) ----`)
+  for (const raw of stackLines.slice(0, 40)) lines.push(`  ${raw}`)
+  if (stackLines.length > 40) lines.push(`  …(${stackLines.length - 40} more frames elided)`)
+  if (stackLines.length === 0) lines.push(`  (no stack captured — the thrown value carried no .stack)`)
+  lines.push(`  ------------------------------------------`)
+  return lines
+}
+
+/**
+ * Capture the EXACT call site of the current expression: the innermost frame
+ * of a freshly minted `Error().stack`. Called from the wrapper's catch block
+ * it names `file:line:col` of the statement that threw.
+ * @returns {string} the call-site coordinate, or a sentinel on failure.
+ */
+function captureSite() {
+  try {
+    const raw = new Error('crashnet-site-marker').stack
+    if (typeof raw !== 'string' || raw.length === 0) return '(no stack available)'
+    const lines = raw.split('\n')
+    const idx = lines.findIndex(l => l.indexOf('crashnet-site-marker') >= 0)
+    if (idx < 0) return '(marker frame not found)'
+    return frameLocation(lines[idx])
+  } catch {
+    return '(site capture failed)'
+  }
+}
+
+/**
+ * Wrap a method entry with the universal crash net.
+ *
+ * Semantics:
+ * - **Success path**: synchronous bodies resolve synchronously; asynchronous
+ *   (promise-returning) bodies keep their promise shape. Callers observe
+ *   exactly what they observe today.
+ * - **Failure path**: the wrapper appends the full diagnostic to the durable
+ *   log AND rethrows/propagates the ORIGINAL error (or promise rejection).
+ *   Existing `try/catch` blocks in callers keep receiving it — this layer adds
+ *   observability, it changes no control flow.
+ *
+ * @template {(...args:any)=>any} F
+ * @param {string} label stable display name of the wrapped entry.
+ * @param {F} fn the body to cover.
+ * @returns {F} the covered body.
+ */
+export function guardFn(label, fn) {
+  const wrapped = (...args) => {
+    try {
+      const result = fn(...args)
+      if (result !== null && typeof result === 'object' && typeof result.catch === 'function') {
+        // Async entry: attach a rejection observer that LOGS but PRESERVES the
+        // rejection (downstream catches still fire). The `.catch` chain returns
+        // a new promise; callers awaiting it see the identical outcome.
+        result.catch((error) => {
+          for (const line of renderCrash(`${label} (async)`, error, captureSite())) appendDiag(line)
+        })
+        return result
+      }
+      return result
+    } catch (error) {
+      for (const line of renderCrash(label, error, captureSite())) appendDiag(line)
+      throw error
+    }
+  }
+  try { Object.defineProperty(wrapped, 'name', { value: label, configurable: true }) } catch { /* cosmetic */ }
+  return wrapped
+}
+
+/** Guarded installation flag — at most one set of process handlers. */
+let installed = false
+
+/**
+ * Install the process-wide crash net (idempotent).
+ *
+ * Attaches one `uncaughtException` handler and one `unhandledRejection`
+ * handler that emit a full diagnostic for anything escaping every wrapped
+ * entry (native callbacks, microtask roots, timer callbacks). The exception
+ * handler KEEPS THE PROCESS ALIVE (Node's default terminates on
+ * `uncaughtException`), so the diagnostic line lands before any later
+ * supervisor decision. If a different subsystem installs its own handler
+ * earlier, ours still fires — multiple handlers compose.
+ */
+export function installCrashNet() {
+  if (installed) return
+  installed = true
+  process.on('uncaughtException', (error) => {
+    for (const line of renderCrash('UNCAUGHT EXCEPTION (process-wide net)', error, captureSite())) appendDiag(line)
+  })
+  process.on('unhandledRejection', (reason) => {
+    for (const line of renderCrash('UNHANDLED REJECTION (process-wide net)', reason, captureSite())) appendDiag(line)
+  })
+}
+
+/** Public accessor: append one line to the durable crash log. */
+export function appendCrashLine(line) { appendDiag(line) }
+
+/** Public accessor: capture the current call-site coordinates. */
+export function captureThrowSite() { return captureSite() }
+
+/** Public accessor: the resolved crash-log path. */
+export function getCrashLogPath() { return crashLogPath() }

package/src/core/log.js

@@ -0,0 +1,346 @@
+/**
+ * dsh-force-compact debug log sink.
+ *
+ * Installs a `ctx.logger` exporter that routes **this plugin's own** log lines
+ * (those whose first argument is tagged `[force-compact]`) to a file — by
+ * default `~/.dsh/logs/dsh-force-compact.log` (under the shared user `$DSH_HOME`,
+ * kept out of any single checkout) — whenever debug logging is enabled by the
+ * `falling-ts-force-compact` settings (`debug`, a boolean that defaults to
+ * `true`). This makes the plugin's otherwise-invisible `warn` / `debug`
+ * diagnostics land somewhere durable, closing the loop where the stock
+ * logger's in-memory-only default sink + `INFO` floor meant those lines went
+ * nowhere.
+ *
+ * Installation is deferred to {@linkcode ensureDebugLogger}, invoked lazily from
+ * the guarded listeners. File I/O goes through **Node's native `node:fs`**
+ * (dynamically imported), not the product `fs` service — the latter is fenced
+ * by the sandbox policy to the session workspace and refuses an absolute path
+ * such as `~/.dsh/logs` (which is deliberately kept OUT of any workspace). A
+ * diagnostic side-channel to the user home is therefore best served straight
+ * from Node, independent of the instance's sandbox mode.
+ *
+ * Design notes (kept deliberately minimal, per this plugin's conventions):
+ * - No `timer` and no long-lived in-memory queue: each captured line performs
+ *   a single fire-and-forget read-append of the file. Occasional loss or
+ *   interleaving under concurrent flushes is acceptable for a diagnostic sink
+ *   and never affects a request path.
+ * - The exporter registers with `levels: { default: DEBUG }` so the host's
+ *   default `INFO` floor no longer drops `warn` / `debug`.
+ * - Appends are capped (~{@linkcode MAX_LOG_CHARS}) keeping the tail, so the
+ *   file cannot grow unbounded.
+ * - Every failure is swallowed: a diagnostic sink must never break business
+ *   paths.
+ *
+ * @module @falling-ts/dsh-force-compact/debug-log
+ */
+
+import { readSettings, DEFAULTS, NS } from './settings.js'
+
+/** Marker identifying this plugin's own log lines (matches every `ctx.logger.*('[force-compact] …')` call site). */
+const MARKER = '[force-compact]'
+
+/**
+ * Expand a leading `~` prefix to the absolute OS user home, so `fs.resolve`
+ * (which treats `~` as a literal path segment) receives an absolute path.
+ *
+ * Reuses the harness's own `expandHomePath` (from the resolvable
+ * `@deepseek-ai/dsh-home-paths` workspace package, whose `homedir()` honors
+ * `USERPROFILE` on Windows) when importable; otherwise falls back to a local
+ * expansion driven by whichever user-home environment variable is readable
+ * (`USERPROFILE` on Windows, `HOME` elsewhere) without requiring Node globals
+ * to be injected. Returns the input unchanged when no supported `~` prefix is
+ * present or no home can be determined.
+ *
+ * @param {string} path
+ * @returns {Promise<string>}
+ */
+async function expandHome(path) {
+  if (typeof path !== 'string') return path
+  const trimmed = path.trim()
+  if (trimmed !== '~' && !trimmed.startsWith('~/') && !trimmed.startsWith('~\\')) return path
+  const rest = trimmed === '~' ? '' : trimmed.slice(2)
+  try {
+    const mod = await import('@deepseek-ai/dsh-home-paths')
+    const fn = mod.expandHomePath
+    if (typeof fn === 'function') return fn(trimmed)
+  } catch {
+    // Fall through to the local expansion below.
+  }
+  // Last resort: read the user home from the environment via a dynamically
+  // imported `node:os` (reachable from the plugin's loader base), and expand
+  // manually if that works too. When none is available, return the input as-is
+  // so the caller still attempts a best-effort write rather than throwing.
+  const home = await readUserHome()
+  if (home === null) return path
+  const sep = home.includes('\\') ? '\\' : '/'
+  return home + (rest === '' ? '' : sep + rest.replace(/\\/g, sep))
+}
+
+/**
+ * Best-effort OS user home without relying on injected globals: prefer an
+ * explicitly-readable home (via dynamically imported `node:os`), else `null`.
+ *
+ * @returns {Promise<string|null>}
+ */
+async function readUserHome() {
+  try {
+    const mod = await import('node:os')
+    const fn = mod && mod.homedir
+    if (typeof fn === 'function') {
+      const h = fn.call(mod)
+      if (typeof h === 'string' && h.length > 0) return h
+    }
+  } catch {
+    // `node:os` unreachable; leave it to the caller.
+  }
+  return null
+}
+
+/** Cap the on-disk log size (characters), keeping the most recent lines. */
+const MAX_LOG_CHARS = 1000000
+
+/**
+ * Install the debug-log sink for this plugin, **at most once**, called lazily
+ * from the guarded listeners.
+ *
+ * Idempotency: a process-local latch (`debugState`) settles the outcome. On a
+ * committed install `installed` becomes `true` and every subsequent call is a
+ * cheap early return (no settings read). While a prior attempt has not settled
+ * (`attempted` false) a later listener re-enters. The first successful install
+ * wins and binds the exporter to its fiber, where it is disposed automatically
+ * when the plugin stops, updates, or is removed.
+ *
+ * Reads the `falling-ts-force-compact` settings live (`debug`, default `true`,
+ * and `logFile`, default `~/.dsh/logs/dsh-force-compact.log`), expands a
+ * leading `~` to the absolute OS home, and registers a `ctx.logger` exporter
+ * that routes only this plugin's own `[force-compact]` lines to the file via
+ * native `node:fs` (sandbox-independent). Swallows all failures: a diagnostic
+ * sink must never break business paths.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @returns {Promise<void>}
+ */
+export async function ensureDebugLogger(ctx) {
+  if (debugState.installed) return
+  if (debugState.attempted) return
+  debugState.attempted = true
+
+  // SAFETY ENVELOPE: a diagnostic-sink installer must NEVER break a business
+  // path. Wrap the whole install so any anomaly (a throwing
+  // `ctx.logger.exporter`, a rejecting settings read, a bad path) marks the
+  // sink as settled-installed and moves on silently rather than propagating.
+  try {
+    await __ensureDebugLoggerBody(ctx)
+  } catch {
+    debugState.installed = true
+  }
+}
+
+async function __ensureDebugLoggerBody(ctx) {
+  const resolved = (await readSettings(ctx)) ?? { ...DEFAULTS }
+  // Centralize the `debug` gate at the EXPORT boundary: the exporter decides,
+  // per line, whether to persist — reading the live `debug` setting at install
+  // time (and, on the fast path, trusting the cached flag). A `debug === false`
+  // deployment therefore installs nothing and writes nothing: no self-noticing
+  // line, no settings round-trip per emitted line.
+  if (resolved.debug !== true) {
+    debugState.installed = true
+    return
+  }
+  if (!resolved.logFile) {
+    ctx.logger.warn('[force-compact] debug logging enabled but no log file path configured — nothing will be written')
+    debugState.installed = true
+    return
+  }
+
+  const filePath = await expandHome(resolved.logFile)
+  if (!filePath) {
+    ctx.logger.warn('[force-compact] debug logging enabled but no log file path could be resolved — nothing will be written')
+    debugState.installed = true
+    return
+  }
+
+  // Take a SINGLE synchronous snapshot of the `debug` setting on the very first
+  // exported line (cheap `getSync`/`get`, cached forever-after). This makes the
+  // export-boundary gate race-free: `debug === false` deployments persist
+  // NOTHING even for the first line, because the snapshot resolves synchronously
+  // rather than deferring to a background read. Thereafter the cached boolean
+  // drives the gate at zero per-line cost; a mid-process `debug` flip takes
+  // effect on the next exporter reinstall.
+  let debugGate
+  const exporter = {
+    colors: false,
+    levels: { default: 3 },
+    export: (message) => {
+      // Final persistence gate lives HERE (the export boundary): a line is
+      // written iff it carries the plugin marker AND the `debug` setting is on.
+      if (!shouldInclude(message)) return
+      if (debugGate === undefined) debugGate = syncDebugSettingSnapshot(ctx)
+      if (!debugGate) return
+      void writeLine(filePath, renderLine(message))
+    },
+  }
+
+  // Bound to the current fiber; removed on stop/update/undefine.
+  ctx.logger.exporter(exporter)
+  debugState.installed = true
+  // Logged AFTER the exporter is installed so this notice lands in the file too.
+  ctx.logger.info(
+    `[force-compact] debug logging enabled — writing [force-compact] lines to ${filePath}`,
+  )
+}
+
+/**
+ * Process-local install state for the debug sink: `installed` permanently stops
+ * further attempts after a settled outcome; `attempted` prevents re-entering the
+ * settings read once a decision has begun (without committing the exporter yet).
+ * Module scope, never exported; reset naturally on a fresh process.
+ */
+const debugState = { attempted: false, installed: false }
+
+/**
+ * Synchronously snapshot the live `debug` setting exactly once (module-level
+ * cache), resolving either through the `settings` service's synchronous read
+ * (`getSync`) or its ordinary read (returned synchronously when backed by a
+ * local store). Returns a settled boolean (never throws): missing values fall
+ * back to the composition default. Settling here at the FIRST exported line
+ * keeps the steady-state `export()` path free of any settings round-trip; a
+ * mid-process `debug` flip takes effect on the next exporter reinstall.
+ */
+let cachedDebug
+function syncDebugSettingSnapshot(ctx) {
+  if (cachedDebug !== undefined) return cachedDebug
+  try {
+    const raw = ctx.get?.('settings')
+    let v
+    if (raw != null && typeof raw.getSync === 'function') {
+      v = raw.getSync(NS)?.debug
+    } else if (typeof raw?.get === 'function') {
+      v = raw.get(NS)?.debug
+    }
+    return v !== undefined ? v === true : DEFAULTS.debug
+  } catch {
+    return DEFAULTS.debug
+  }
+}
+
+/**
+ * Keep only this plugin's own lines: the first `args` element is the log
+ * template string and must carry the `[force-compact]` marker.
+ *
+ * @param {any} message structured log record
+ * @returns {boolean}
+ */
+function shouldInclude(message) {
+  if (message === null || typeof message !== 'object') return false
+  const args = message.args
+  if (!Array.isArray(args) || args.length === 0) return false
+  const first = args[0]
+  return typeof first === 'string' && first.indexOf(MARKER) !== -1
+}
+
+/**
+ * Render one message to a single prefixed line: ISO timestamp, severity tag,
+ * then the formatted arguments. Errors contribute their stack (or message);
+ * objects are compacted to JSON; everything else is stringified. Only the
+ * shallow `args` are touched — the live record itself is never cloned or
+ * recursively enumerated.
+ *
+ * @param {any} message
+ * @returns {string}
+ */
+function renderLine(message) {
+  // Tolerate a malformed `message`: a non-date `ts` (undefined/null/nonsense
+  // string) would otherwise make `new Date(...).toISOString()` throw on the
+  // `Invalid Date` value. Degrade to an epoch-zero timestamp so the line still
+  // renders — a diagnostic line dropping on a weird record is unacceptable.
+  let ts
+  try {
+    ts = Number.isFinite(+new Date(message.ts).getTime()) ? new Date(message.ts).toISOString() : new Date(0).toISOString()
+  } catch {
+    ts = new Date(0).toISOString()
+  }
+  const type = String(message && message.type !== undefined ? message.type : 'info').toUpperCase()
+  return `${ts} [${type}] ${formatArgs(Array.isArray(message && message.args) ? message.args : [])}`
+}
+
+/**
+ * Format the shallow argument list into a printable string.
+ *
+ * @param {any[]} args
+ * @returns {string}
+ */
+function formatArgs(args) {
+  const parts = []
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg instanceof Error) parts.push(arg.stack || arg.message)
+    else if (typeof arg === 'object' && arg !== null) {
+      try {
+        parts.push(JSON.stringify(arg))
+      } catch {
+        parts.push(String(arg))
+      }
+    } else {
+      parts.push(String(arg))
+    }
+  }
+  return parts.join(' ')
+}
+
+/**
+ * Lazily import Node's native filesystem promises, cached after the first load.
+ * Native `node:fs` is intentionally chosen over the product `fs` service because
+ * the latter is fenced by the sandbox policy to the session workspace and
+ * refuses an absolute user-home path; the native module writes the absolute
+ * target directly, independent of sandbox mode. Returns `null` if the import
+ * ever fails (extremely unlikely for a builtin), letting callers degrade.
+ *
+ * @returns {Promise<Object|null>}
+ */
+let nativeFsPromises
+async function getNodeFs() {
+  if (nativeFsPromises !== undefined) return nativeFsPromises
+  try {
+    nativeFsPromises = await import('node:fs/promises')
+  } catch {
+    nativeFsPromises = null
+  }
+  return nativeFsPromises
+}
+
+/**
+ * Append one line to the debug log using native Node `fs`. Creates the parent
+ * directory if needed, appends, and truncates to {@linkcode MAX_LOG_CHARS}
+ * keeping the tail. Fire-and-forget; swallows all errors so a diagnostic sink
+ * can never disturb a business path.
+ *
+ * @param {string} path absolute target path
+ * @param {string} line rendered line WITHOUT a trailing newline
+ */
+async function writeLine(path, line) {
+  try {
+    const fsp = await getNodeFs()
+    if (fsp === null) return
+    const { dirname } = await import('node:path')
+    // Ensure the containing directory exists (recursive, no-op if present).
+    await fsp.mkdir(dirname(path), { recursive: true })
+    await fsp.appendFile(path, line + '\n')
+    // Tail-cap: if the file grew past the budget, keep only the last
+    // MAX_LOG_CHARS characters so it cannot grow unbounded.
+    const stat = await fsp.stat(path).catch(() => null)
+    if (stat !== null && stat.size > MAX_LOG_CHARS) {
+      const handle = await fsp.open(path, 'r+')
+      try {
+        const buffer = Buffer.alloc(MAX_LOG_CHARS)
+        const { bytesRead } = await handle.readFile(buffer, 0, MAX_LOG_CHARS, stat.size - MAX_LOG_CHARS)
+        await handle.writeFile(Buffer.from(buffer.subarray(0, bytesRead)), 0, bytesRead, 0)
+        await handle.truncate(bytesRead)
+      } finally {
+        await handle.close()
+      }
+    }
+  } catch {
+    // Diagnostic sink must never break the requesting path.
+  }
+}