@wrongstack/tools 0.250.0 → 0.256.0

package/dist/document.js

@@ -28,6 +28,7 @@ var documentTool = {
   permission: "auto",
   mutating: false,
   timeoutMs: 3e4,
+  capabilities: ["fs.read"],
   inputSchema: {
     type: "object",
     properties: {

package/dist/document.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/_util.ts","../src/document.ts"],"names":["stat"],"mappings":"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","file":"document.js","sourcesContent":["import * as fsp from 'node:fs/promises';\nimport * as path from 'node:path';\nimport * as Core from '@wrongstack/core';\nimport type { Context } from '@wrongstack/core';\n/** Detected package manager for a project directory. */\nexport type PackageManager = 'pnpm' | 'yarn' | 'npm';\n\n/**\n * Detect the project's package manager by inspecting lockfiles in `cwd`.\n * Order: pnpm → yarn → npm (default). Missing or unreadable directories fall\n * back to `npm` rather than throwing, so a `safeResolve`-checked cwd that\n * happens to be empty never aborts the tool.\n */\nexport async function detectPackageManager(cwd: string): Promise<PackageManager> {\n  const { stat } = await import('node:fs/promises');\n  try {\n    await stat(`${cwd}/pnpm-lock.yaml`);\n    return 'pnpm';\n  } catch {\n    /* not pnpm */\n  }\n  try {\n    await stat(`${cwd}/yarn.lock`);\n    return 'yarn';\n  } catch {\n    /* not yarn */\n  }\n  return 'npm';\n}\n\nexport function resolvePath(input: string, ctx: Context): string {\n  return path.isAbsolute(input) ? path.normalize(input) : path.resolve(ctx.workingDir ?? ctx.cwd, input);\n}\n\nexport function ensureInsideRoot(absPath: string, ctx: Context): string {\n  const root = path.resolve(ctx.projectRoot);\n  const target = path.resolve(absPath);\n  const rel = path.relative(root, target);\n  if (rel.startsWith('..') || path.isAbsolute(rel)) {\n    throw new Error(`Path \"${absPath}\" is outside project root \"${root}\"`);\n  }\n  return target;\n}\n\nexport function safeResolve(input: string, ctx: Context): string {\n  return ensureInsideRoot(resolvePath(input, ctx), ctx);\n}\n\n/**\n * Defense against in-root→out-of-root symlink escape (CWE-59). `safeResolve`\n * only does a syntactic `../` check, so a symlink that lives *inside* the\n * project root but points outside still passes it. This resolves the path\n * through `fs.realpath` and re-verifies containment against the realpath of\n * the project root (comparing like-for-like, since the root itself may be a\n * symlink — macOS `/var`→`/private/var`, Windows 8.3 short names). For a path\n * that does not exist yet (e.g. a `write` to a new file) the nearest existing\n * ancestor directory is checked instead. Throws if the real target escapes.\n *\n * Mirrors the per-file guard already used in `replace.ts`/`grep.ts`; applied\n * to single-file `read`/`edit`/`write` it throws (rather than skips) because\n * the caller named exactly one file.\n */\nexport async function assertRealInsideRoot(absPath: string, ctx: Context): Promise<void> {\n  const realRoot = await fsp.realpath(ctx.projectRoot).catch(() => path.resolve(ctx.projectRoot));\n  let probe = absPath;\n  for (;;) {\n    let real: string;\n    try {\n      real = await fsp.realpath(probe);\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {\n        const parent = path.dirname(probe);\n        if (parent === probe) return; // reached fs root without escaping\n        probe = parent;\n        continue;\n      }\n      throw err;\n    }\n    const rel = path.relative(realRoot, real);\n    if (rel.startsWith('..') || path.isAbsolute(rel)) {\n      throw new Error(\n        `Path \"${absPath}\" resolves through a symlink outside project root \"${realRoot}\"`,\n      );\n    }\n    return;\n  }\n}\n\n/** `safeResolve` + symlink realpath containment check. Async. */\nexport async function safeResolveReal(input: string, ctx: Context): Promise<string> {\n  const abs = safeResolve(input, ctx);\n  await assertRealInsideRoot(abs, ctx);\n  return abs;\n}\n\nexport function truncateMiddle(s: string, max: number): string {\n  if (Buffer.byteLength(s, 'utf8') <= max) return s;\n  const half = Math.floor(max / 2);\n  return (\n    s.slice(0, half) +\n    `\\n…[truncated ${Buffer.byteLength(s, 'utf8') - max} bytes from middle]…\\n` +\n    s.slice(-half)\n  );\n}\n\nexport function isBinaryBuffer(buf: Buffer): boolean {\n  const len = Math.min(buf.length, 8192);\n  for (let i = 0; i < len; i++) {\n    if (buf[i] === 0) return true;\n  }\n  return false;\n}\n\n// ─── Command-output normalization (token-saving) ────────────────────────────\n//\n// Raw process output is full of tokens the model gains nothing from: ANSI\n// escapes, carriage-return progress spam, runs of identical warning lines, and\n// huge tails of build noise. These helpers strip that noise before the output\n// reaches the LLM. They are scoped to COMMAND tools (bash/git/exec and the\n// _spawn-stream consumers) — never applied to structured/code outputs.\n\n/** Unified byte cap for all command tool output fed to the model. */\nexport const COMMAND_OUTPUT_MAX_BYTES = 32_768;\n\n/** Runs of >= this many identical consecutive lines are collapsed. */\nconst REPEAT_RUN_THRESHOLD = 3;\n\n/**\n * Collapse carriage-return overwrites the way a terminal would: `\\r\\n` becomes\n * `\\n`, and a bare `\\r` (progress redraw) keeps only the text after the LAST\n * `\\r` on its physical line. Without this, a single progress bar that redraws\n * 200 times explodes into 200 lines.\n */\nexport function collapseCarriageReturns(text: string): string {\n  const lf = text.replace(/\\r\\n/g, '\\n');\n  if (!lf.includes('\\r')) return lf;\n  return lf\n    .split('\\n')\n    .map((line) => (line.includes('\\r') ? line.slice(line.lastIndexOf('\\r') + 1) : line))\n    .join('\\n');\n}\n\n/**\n * Collapse a run of `minRun`+ identical consecutive lines into the line once\n * plus a marker. Consecutive-only — it never reorders or dedups non-adjacent\n * lines, so diffs/source stay intact.\n */\nexport function collapseConsecutiveDuplicates(text: string, minRun = REPEAT_RUN_THRESHOLD): string {\n  const lines = text.split('\\n');\n  const out: string[] = [];\n  let i = 0;\n  while (i < lines.length) {\n    let j = i + 1;\n    while (j < lines.length && lines[j] === lines[i]) j++;\n    const run = j - i;\n    if (run >= minRun) {\n      out.push(lines[i]!, `… ⟨repeated ${run}×⟩`);\n    } else {\n      for (let k = i; k < j; k++) out.push(lines[k]!);\n    }\n    i = j;\n  }\n  return out.join('\\n');\n}\n\n/** Largest prefix of `s` whose UTF-8 byte length is <= `maxBytes`. */\nfunction takeHeadBytes(s: string, maxBytes: number): string {\n  if (maxBytes <= 0) return '';\n  if (Buffer.byteLength(s, 'utf8') <= maxBytes) return s;\n  let lo = 0;\n  let hi = s.length;\n  while (lo < hi) {\n    const mid = Math.ceil((lo + hi) / 2);\n    if (Buffer.byteLength(s.slice(0, mid), 'utf8') <= maxBytes) lo = mid;\n    else hi = mid - 1;\n  }\n  return s.slice(0, lo);\n}\n\n/** Largest suffix of `s` whose UTF-8 byte length is <= `maxBytes`. */\nfunction takeTailBytes(s: string, maxBytes: number): string {\n  if (maxBytes <= 0) return '';\n  if (Buffer.byteLength(s, 'utf8') <= maxBytes) return s;\n  let lo = 0;\n  let hi = s.length;\n  while (lo < hi) {\n    const mid = Math.ceil((lo + hi) / 2);\n    if (Buffer.byteLength(s.slice(s.length - mid), 'utf8') <= maxBytes) lo = mid;\n    else hi = mid - 1;\n  }\n  return s.slice(s.length - lo);\n}\n\n/**\n * Truncate to `maxBytes` keeping BOTH ends — the head (what ran / early context)\n * and the tail (errors and summaries usually land last), biased ~45/55 toward\n * the tail. The result never exceeds `maxBytes`.\n */\nexport function truncateHeadTail(s: string, maxBytes: number): string {\n  const total = Buffer.byteLength(s, 'utf8');\n  if (total <= maxBytes) return s;\n  // Reserve a fixed allowance for the marker so the final string can't exceed\n  // the cap even though the dropped-byte count's digit width varies.\n  const MARKER_RESERVE = 64;\n  const avail = Math.max(0, maxBytes - MARKER_RESERVE);\n  const headBudget = Math.floor(avail * 0.45);\n  const head = takeHeadBytes(s, headBudget);\n  const tail = takeTailBytes(s, avail - Buffer.byteLength(head, 'utf8'));\n  const kept = Buffer.byteLength(head, 'utf8') + Buffer.byteLength(tail, 'utf8');\n  return `${head}\\n…[truncated ${total - kept} bytes]…\\n${tail}`;\n}\n\n/**\n * Full token-saving pipeline for command tool output: strip ANSI → collapse\n * carriage-return progress → trim trailing whitespace → collapse identical\n * consecutive lines → squeeze blank-line runs → head+tail truncate to the cap.\n */\nexport function normalizeCommandOutput(\n  raw: string,\n  opts: { maxBytes?: number | undefined } = {},\n): string {\n  if (!raw) return raw;\n  let text = Core.stripAnsi(raw);\n  text = collapseCarriageReturns(text);\n  text = text.replace(/[ \\t]+$/gm, ''); // trailing whitespace per line\n  text = collapseConsecutiveDuplicates(text);\n  text = text.replace(/\\n{3,}/g, '\\n\\n'); // >=2 blank lines → 1\n  return truncateHeadTail(text, opts.maxBytes ?? COMMAND_OUTPUT_MAX_BYTES);\n}\n","import * as fs from 'node:fs/promises';\nimport type { Tool } from '@wrongstack/core';\nimport { safeResolve } from './_util.js';\n\ninterface DocumentInput {\n  target: 'file' | 'function' | 'class' | 'type' | 'all';\n  path?: string | undefined;\n  files?: string | string[] | undefined;\n  style?: 'jsdoc' | 'tsdoc' | 'block' | undefined;\n  overwrite?: boolean | undefined;\n  cwd?: string | undefined;\n}\n\ninterface DocumentedItem {\n  path: string;\n  name: string;\n  signature: string;\n  docstring: string;\n  status: 'documented' | 'skipped' | 'error';\n  error?: string | undefined;\n}\n\ninterface DocumentOutput {\n  files_processed: number;\n  items_documented: number;\n  results: DocumentedItem[];\n  style: string;\n}\n\nexport const documentTool: Tool<DocumentInput, DocumentOutput> = {\n  name: 'document',\n  category: 'Project',\n  description:\n    'Preview documentation comments (JSDoc/TSDoc style) that would be generated for code symbols. ' +\n    'Returns a list of candidates with status `skipped` — the tool is currently a read-only preview and does NOT write to files.',\n  usageHint:\n    'USE FOR IMPROVING CODE DOCUMENTATION:\\n\\n' +\n    '- Good for adding missing docs to public APIs or complex functions.\\n' +\n    '- Currently this is a PREVIEW-ONLY tool: it does not modify files.\\n' +\n    '- Use the output to decide which symbols to document manually, or pass the candidates to `edit` / `patch`.\\n' +\n    '- `overwrite`, `style`, and `target` parameters are accepted for future expansion but are ignored today.\\n' +\n    'Always review the proposed documentation before applying it — the model can hallucinate details.',\n  permission: 'auto',\n  mutating: false,\n  timeoutMs: 30_000,\n  inputSchema: {\n    type: 'object',\n    properties: {\n      target: {\n        type: 'string',\n        enum: ['file', 'function', 'class', 'type', 'all'],\n        description: 'What to document',\n      },\n      path: {\n        type: 'string',\n        description: 'Specific file path to document',\n      },\n      files: {\n        type: 'string',\n        description: 'File(s) to process: single path, comma-separated list, or glob',\n      },\n      style: {\n        type: 'string',\n        enum: ['jsdoc', 'tsdoc', 'block'],\n        description: 'Documentation style (default: jsdoc)',\n      },\n      overwrite: {\n        type: 'boolean',\n        description: 'Overwrite existing docstrings (default: false)',\n      },\n      cwd: { type: 'string', description: 'Working directory (default: cwd)' },\n    },\n  },\n  async execute(input, ctx) {\n    const cwd = input.cwd ? safeResolve(input.cwd, ctx) : ctx.cwd;\n    const style = input.style ?? 'jsdoc';\n    const results: DocumentedItem[] = [];\n    let filesProcessed = 0;\n    let itemsDocumented = 0;\n\n    const fileList = input.files\n      ? await resolveFiles(Array.isArray(input.files) ? input.files.join(',') : input.files, cwd)\n      : input.path\n        ? [safeResolve(input.path, ctx)]\n        : [];\n\n    for (const absPath of fileList) {\n      try {\n        const content = await fs.readFile(absPath, 'utf8');\n        filesProcessed++;\n        const processed = processFile(\n          content,\n          absPath,\n          style,\n          input.overwrite ?? false,\n          input.target ?? 'all',\n        );\n        results.push(...processed);\n        itemsDocumented += processed.filter((r) => r.status === 'documented').length;\n      } catch (e) {\n        results.push({\n          path: absPath,\n          name: absPath.split('/').pop() ?? absPath,\n          signature: '',\n          docstring: '',\n          status: 'error',\n          error: e instanceof Error ? e.message : String(e),\n        });\n      }\n    }\n\n    return {\n      files_processed: filesProcessed,\n      items_documented: itemsDocumented,\n      results,\n      style,\n    };\n  },\n};\n\nasync function resolveFiles(filesInput: string, cwd: string): Promise<string[]> {\n  const files = Array.isArray(filesInput) ? filesInput : filesInput.split(',');\n  const resolved: string[] = [];\n\n  for (const f of files) {\n    const absPath = f.trim().startsWith('/') ? f.trim() : `${cwd}/${f.trim()}`;\n    try {\n      const stat = await fs.stat(absPath);\n      if (stat.isFile()) resolved.push(absPath);\n    } catch {\n      // skip\n    }\n  }\n\n  return resolved;\n}\n\nfunction processFile(\n  content: string,\n  absPath: string,\n  _style: string,\n  _overwrite: boolean,\n  target: string,\n): DocumentedItem[] {\n  const results: DocumentedItem[] = [];\n  const functionRegex = /(?:async\\s+)?function\\s+(\\w+)\\s*\\(([^)]*)\\)/g;\n  const arrowRegex = /(?:const|let|var)\\s+(\\w+)\\s*=\\s*(?:async\\s+)?\\(([^)]*)\\)\\s*=>/g;\n  const classRegex = /class\\s+(\\w+)/g;\n  const typeRegex = /(?:type|interface)\\s+(\\w+)\\s*[=<]/g;\n\n  const allMatches: { name: string; sig: string; type: string; line: number }[] = [];\n\n  if (target === 'all' || target === 'function') {\n    for (const m of content.matchAll(functionRegex)) {\n      if (!m[1]) continue;\n      allMatches.push({\n        name: m[1],\n        sig: m[2] ?? '',\n        type: 'function',\n        line: content.slice(0, m.index).split('\\n').length,\n      });\n    }\n    for (const m of content.matchAll(arrowRegex)) {\n      if (!m[1]) continue;\n      allMatches.push({\n        name: m[1],\n        sig: m[2] ?? '',\n        type: 'arrow',\n        line: content.slice(0, m.index).split('\\n').length,\n      });\n    }\n  }\n\n  if (target === 'all' || target === 'class') {\n    for (const m of content.matchAll(classRegex)) {\n      if (!m[1]) continue;\n      allMatches.push({\n        name: m[1],\n        sig: '',\n        type: 'class',\n        line: content.slice(0, m.index).split('\\n').length,\n      });\n    }\n  }\n\n  if (target === 'all' || target === 'type') {\n    for (const m of content.matchAll(typeRegex)) {\n      if (!m[1]) continue;\n      allMatches.push({\n        name: m[1],\n        sig: m[0] ?? '',\n        type: 'type',\n        line: content.slice(0, m.index).split('\\n').length,\n      });\n    }\n  }\n\n  for (const m of allMatches) {\n    results.push({\n      path: absPath,\n      name: m.name,\n      signature: m.sig,\n      docstring: `/** ${m.name} - documented at line ${m.line} */`,\n      status: 'skipped',\n    });\n  }\n\n  return results;\n}\n"]}
+{"version":3,"sources":["../src/_util.ts","../src/document.ts"],"names":["stat"],"mappings":"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","file":"document.js","sourcesContent":["import * as fsp from 'node:fs/promises';\nimport * as path from 'node:path';\nimport * as Core from '@wrongstack/core';\nimport type { Context } from '@wrongstack/core';\n/** Detected package manager for a project directory. */\nexport type PackageManager = 'pnpm' | 'yarn' | 'npm';\n\n/**\n * Detect the project's package manager by inspecting lockfiles in `cwd`.\n * Order: pnpm → yarn → npm (default). Missing or unreadable directories fall\n * back to `npm` rather than throwing, so a `safeResolve`-checked cwd that\n * happens to be empty never aborts the tool.\n */\nexport async function detectPackageManager(cwd: string): Promise<PackageManager> {\n  const { stat } = await import('node:fs/promises');\n  try {\n    await stat(`${cwd}/pnpm-lock.yaml`);\n    return 'pnpm';\n  } catch {\n    /* not pnpm */\n  }\n  try {\n    await stat(`${cwd}/yarn.lock`);\n    return 'yarn';\n  } catch {\n    /* not yarn */\n  }\n  return 'npm';\n}\n\nexport function resolvePath(input: string, ctx: Context): string {\n  return path.isAbsolute(input) ? path.normalize(input) : path.resolve(ctx.workingDir ?? ctx.cwd, input);\n}\n\nexport function ensureInsideRoot(absPath: string, ctx: Context): string {\n  const root = path.resolve(ctx.projectRoot);\n  const target = path.resolve(absPath);\n  const rel = path.relative(root, target);\n  if (rel.startsWith('..') || path.isAbsolute(rel)) {\n    throw new Error(`Path \"${absPath}\" is outside project root \"${root}\"`);\n  }\n  return target;\n}\n\nexport function safeResolve(input: string, ctx: Context): string {\n  return ensureInsideRoot(resolvePath(input, ctx), ctx);\n}\n\n/**\n * Defense against in-root→out-of-root symlink escape (CWE-59). `safeResolve`\n * only does a syntactic `../` check, so a symlink that lives *inside* the\n * project root but points outside still passes it. This resolves the path\n * through `fs.realpath` and re-verifies containment against the realpath of\n * the project root (comparing like-for-like, since the root itself may be a\n * symlink — macOS `/var`→`/private/var`, Windows 8.3 short names). For a path\n * that does not exist yet (e.g. a `write` to a new file) the nearest existing\n * ancestor directory is checked instead. Throws if the real target escapes.\n *\n * Mirrors the per-file guard already used in `replace.ts`/`grep.ts`; applied\n * to single-file `read`/`edit`/`write` it throws (rather than skips) because\n * the caller named exactly one file.\n */\nexport async function assertRealInsideRoot(absPath: string, ctx: Context): Promise<void> {\n  const realRoot = await fsp.realpath(ctx.projectRoot).catch(() => path.resolve(ctx.projectRoot));\n  let probe = absPath;\n  for (;;) {\n    let real: string;\n    try {\n      real = await fsp.realpath(probe);\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {\n        const parent = path.dirname(probe);\n        if (parent === probe) return; // reached fs root without escaping\n        probe = parent;\n        continue;\n      }\n      throw err;\n    }\n    const rel = path.relative(realRoot, real);\n    if (rel.startsWith('..') || path.isAbsolute(rel)) {\n      throw new Error(\n        `Path \"${absPath}\" resolves through a symlink outside project root \"${realRoot}\"`,\n      );\n    }\n    return;\n  }\n}\n\n/** `safeResolve` + symlink realpath containment check. Async. */\nexport async function safeResolveReal(input: string, ctx: Context): Promise<string> {\n  const abs = safeResolve(input, ctx);\n  await assertRealInsideRoot(abs, ctx);\n  return abs;\n}\n\nexport function truncateMiddle(s: string, max: number): string {\n  if (Buffer.byteLength(s, 'utf8') <= max) return s;\n  const half = Math.floor(max / 2);\n  return (\n    s.slice(0, half) +\n    `\\n…[truncated ${Buffer.byteLength(s, 'utf8') - max} bytes from middle]…\\n` +\n    s.slice(-half)\n  );\n}\n\nexport function isBinaryBuffer(buf: Buffer): boolean {\n  const len = Math.min(buf.length, 8192);\n  for (let i = 0; i < len; i++) {\n    if (buf[i] === 0) return true;\n  }\n  return false;\n}\n\n// ─── Command-output normalization (token-saving) ────────────────────────────\n//\n// Raw process output is full of tokens the model gains nothing from: ANSI\n// escapes, carriage-return progress spam, runs of identical warning lines, and\n// huge tails of build noise. These helpers strip that noise before the output\n// reaches the LLM. They are scoped to COMMAND tools (bash/git/exec and the\n// _spawn-stream consumers) — never applied to structured/code outputs.\n\n/** Unified byte cap for all command tool output fed to the model. */\nexport const COMMAND_OUTPUT_MAX_BYTES = 32_768;\n\n/** Runs of >= this many identical consecutive lines are collapsed. */\nconst REPEAT_RUN_THRESHOLD = 3;\n\n/**\n * Collapse carriage-return overwrites the way a terminal would: `\\r\\n` becomes\n * `\\n`, and a bare `\\r` (progress redraw) keeps only the text after the LAST\n * `\\r` on its physical line. Without this, a single progress bar that redraws\n * 200 times explodes into 200 lines.\n */\nexport function collapseCarriageReturns(text: string): string {\n  const lf = text.replace(/\\r\\n/g, '\\n');\n  if (!lf.includes('\\r')) return lf;\n  return lf\n    .split('\\n')\n    .map((line) => (line.includes('\\r') ? line.slice(line.lastIndexOf('\\r') + 1) : line))\n    .join('\\n');\n}\n\n/**\n * Collapse a run of `minRun`+ identical consecutive lines into the line once\n * plus a marker. Consecutive-only — it never reorders or dedups non-adjacent\n * lines, so diffs/source stay intact.\n */\nexport function collapseConsecutiveDuplicates(text: string, minRun = REPEAT_RUN_THRESHOLD): string {\n  const lines = text.split('\\n');\n  const out: string[] = [];\n  let i = 0;\n  while (i < lines.length) {\n    let j = i + 1;\n    while (j < lines.length && lines[j] === lines[i]) j++;\n    const run = j - i;\n    if (run >= minRun) {\n      out.push(lines[i]!, `… ⟨repeated ${run}×⟩`);\n    } else {\n      for (let k = i; k < j; k++) out.push(lines[k]!);\n    }\n    i = j;\n  }\n  return out.join('\\n');\n}\n\n/** Largest prefix of `s` whose UTF-8 byte length is <= `maxBytes`. */\nfunction takeHeadBytes(s: string, maxBytes: number): string {\n  if (maxBytes <= 0) return '';\n  if (Buffer.byteLength(s, 'utf8') <= maxBytes) return s;\n  let lo = 0;\n  let hi = s.length;\n  while (lo < hi) {\n    const mid = Math.ceil((lo + hi) / 2);\n    if (Buffer.byteLength(s.slice(0, mid), 'utf8') <= maxBytes) lo = mid;\n    else hi = mid - 1;\n  }\n  return s.slice(0, lo);\n}\n\n/** Largest suffix of `s` whose UTF-8 byte length is <= `maxBytes`. */\nfunction takeTailBytes(s: string, maxBytes: number): string {\n  if (maxBytes <= 0) return '';\n  if (Buffer.byteLength(s, 'utf8') <= maxBytes) return s;\n  let lo = 0;\n  let hi = s.length;\n  while (lo < hi) {\n    const mid = Math.ceil((lo + hi) / 2);\n    if (Buffer.byteLength(s.slice(s.length - mid), 'utf8') <= maxBytes) lo = mid;\n    else hi = mid - 1;\n  }\n  return s.slice(s.length - lo);\n}\n\n/**\n * Truncate to `maxBytes` keeping BOTH ends — the head (what ran / early context)\n * and the tail (errors and summaries usually land last), biased ~45/55 toward\n * the tail. The result never exceeds `maxBytes`.\n */\nexport function truncateHeadTail(s: string, maxBytes: number): string {\n  const total = Buffer.byteLength(s, 'utf8');\n  if (total <= maxBytes) return s;\n  // Reserve a fixed allowance for the marker so the final string can't exceed\n  // the cap even though the dropped-byte count's digit width varies.\n  const MARKER_RESERVE = 64;\n  const avail = Math.max(0, maxBytes - MARKER_RESERVE);\n  const headBudget = Math.floor(avail * 0.45);\n  const head = takeHeadBytes(s, headBudget);\n  const tail = takeTailBytes(s, avail - Buffer.byteLength(head, 'utf8'));\n  const kept = Buffer.byteLength(head, 'utf8') + Buffer.byteLength(tail, 'utf8');\n  return `${head}\\n…[truncated ${total - kept} bytes]…\\n${tail}`;\n}\n\n/**\n * Full token-saving pipeline for command tool output: strip ANSI → collapse\n * carriage-return progress → trim trailing whitespace → collapse identical\n * consecutive lines → squeeze blank-line runs → head+tail truncate to the cap.\n */\nexport function normalizeCommandOutput(\n  raw: string,\n  opts: { maxBytes?: number | undefined } = {},\n): string {\n  if (!raw) return raw;\n  let text = Core.stripAnsi(raw);\n  text = collapseCarriageReturns(text);\n  text = text.replace(/[ \\t]+$/gm, ''); // trailing whitespace per line\n  text = collapseConsecutiveDuplicates(text);\n  text = text.replace(/\\n{3,}/g, '\\n\\n'); // >=2 blank lines → 1\n  return truncateHeadTail(text, opts.maxBytes ?? COMMAND_OUTPUT_MAX_BYTES);\n}\n","import * as fs from 'node:fs/promises';\nimport type { Tool } from '@wrongstack/core';\nimport { safeResolve } from './_util.js';\n\ninterface DocumentInput {\n  target: 'file' | 'function' | 'class' | 'type' | 'all';\n  path?: string | undefined;\n  files?: string | string[] | undefined;\n  style?: 'jsdoc' | 'tsdoc' | 'block' | undefined;\n  overwrite?: boolean | undefined;\n  cwd?: string | undefined;\n}\n\ninterface DocumentedItem {\n  path: string;\n  name: string;\n  signature: string;\n  docstring: string;\n  status: 'documented' | 'skipped' | 'error';\n  error?: string | undefined;\n}\n\ninterface DocumentOutput {\n  files_processed: number;\n  items_documented: number;\n  results: DocumentedItem[];\n  style: string;\n}\n\nexport const documentTool: Tool<DocumentInput, DocumentOutput> = {\n  name: 'document',\n  category: 'Project',\n  description:\n    'Preview documentation comments (JSDoc/TSDoc style) that would be generated for code symbols. ' +\n    'Returns a list of candidates with status `skipped` — the tool is currently a read-only preview and does NOT write to files.',\n  usageHint:\n    'USE FOR IMPROVING CODE DOCUMENTATION:\\n\\n' +\n    '- Good for adding missing docs to public APIs or complex functions.\\n' +\n    '- Currently this is a PREVIEW-ONLY tool: it does not modify files.\\n' +\n    '- Use the output to decide which symbols to document manually, or pass the candidates to `edit` / `patch`.\\n' +\n    '- `overwrite`, `style`, and `target` parameters are accepted for future expansion but are ignored today.\\n' +\n    'Always review the proposed documentation before applying it — the model can hallucinate details.',\n  permission: 'auto',\n  mutating: false,\n  timeoutMs: 30_000,\n  capabilities: ['fs.read'],\n  inputSchema: {\n    type: 'object',\n    properties: {\n      target: {\n        type: 'string',\n        enum: ['file', 'function', 'class', 'type', 'all'],\n        description: 'What to document',\n      },\n      path: {\n        type: 'string',\n        description: 'Specific file path to document',\n      },\n      files: {\n        type: 'string',\n        description: 'File(s) to process: single path, comma-separated list, or glob',\n      },\n      style: {\n        type: 'string',\n        enum: ['jsdoc', 'tsdoc', 'block'],\n        description: 'Documentation style (default: jsdoc)',\n      },\n      overwrite: {\n        type: 'boolean',\n        description: 'Overwrite existing docstrings (default: false)',\n      },\n      cwd: { type: 'string', description: 'Working directory (default: cwd)' },\n    },\n  },\n  async execute(input, ctx) {\n    const cwd = input.cwd ? safeResolve(input.cwd, ctx) : ctx.cwd;\n    const style = input.style ?? 'jsdoc';\n    const results: DocumentedItem[] = [];\n    let filesProcessed = 0;\n    let itemsDocumented = 0;\n\n    const fileList = input.files\n      ? await resolveFiles(Array.isArray(input.files) ? input.files.join(',') : input.files, cwd)\n      : input.path\n        ? [safeResolve(input.path, ctx)]\n        : [];\n\n    for (const absPath of fileList) {\n      try {\n        const content = await fs.readFile(absPath, 'utf8');\n        filesProcessed++;\n        const processed = processFile(\n          content,\n          absPath,\n          style,\n          input.overwrite ?? false,\n          input.target ?? 'all',\n        );\n        results.push(...processed);\n        itemsDocumented += processed.filter((r) => r.status === 'documented').length;\n      } catch (e) {\n        results.push({\n          path: absPath,\n          name: absPath.split('/').pop() ?? absPath,\n          signature: '',\n          docstring: '',\n          status: 'error',\n          error: e instanceof Error ? e.message : String(e),\n        });\n      }\n    }\n\n    return {\n      files_processed: filesProcessed,\n      items_documented: itemsDocumented,\n      results,\n      style,\n    };\n  },\n};\n\nasync function resolveFiles(filesInput: string, cwd: string): Promise<string[]> {\n  const files = Array.isArray(filesInput) ? filesInput : filesInput.split(',');\n  const resolved: string[] = [];\n\n  for (const f of files) {\n    const absPath = f.trim().startsWith('/') ? f.trim() : `${cwd}/${f.trim()}`;\n    try {\n      const stat = await fs.stat(absPath);\n      if (stat.isFile()) resolved.push(absPath);\n    } catch {\n      // skip\n    }\n  }\n\n  return resolved;\n}\n\nfunction processFile(\n  content: string,\n  absPath: string,\n  _style: string,\n  _overwrite: boolean,\n  target: string,\n): DocumentedItem[] {\n  const results: DocumentedItem[] = [];\n  const functionRegex = /(?:async\\s+)?function\\s+(\\w+)\\s*\\(([^)]*)\\)/g;\n  const arrowRegex = /(?:const|let|var)\\s+(\\w+)\\s*=\\s*(?:async\\s+)?\\(([^)]*)\\)\\s*=>/g;\n  const classRegex = /class\\s+(\\w+)/g;\n  const typeRegex = /(?:type|interface)\\s+(\\w+)\\s*[=<]/g;\n\n  const allMatches: { name: string; sig: string; type: string; line: number }[] = [];\n\n  if (target === 'all' || target === 'function') {\n    for (const m of content.matchAll(functionRegex)) {\n      if (!m[1]) continue;\n      allMatches.push({\n        name: m[1],\n        sig: m[2] ?? '',\n        type: 'function',\n        line: content.slice(0, m.index).split('\\n').length,\n      });\n    }\n    for (const m of content.matchAll(arrowRegex)) {\n      if (!m[1]) continue;\n      allMatches.push({\n        name: m[1],\n        sig: m[2] ?? '',\n        type: 'arrow',\n        line: content.slice(0, m.index).split('\\n').length,\n      });\n    }\n  }\n\n  if (target === 'all' || target === 'class') {\n    for (const m of content.matchAll(classRegex)) {\n      if (!m[1]) continue;\n      allMatches.push({\n        name: m[1],\n        sig: '',\n        type: 'class',\n        line: content.slice(0, m.index).split('\\n').length,\n      });\n    }\n  }\n\n  if (target === 'all' || target === 'type') {\n    for (const m of content.matchAll(typeRegex)) {\n      if (!m[1]) continue;\n      allMatches.push({\n        name: m[1],\n        sig: m[0] ?? '',\n        type: 'type',\n        line: content.slice(0, m.index).split('\\n').length,\n      });\n    }\n  }\n\n  for (const m of allMatches) {\n    results.push({\n      path: absPath,\n      name: m.name,\n      signature: m.sig,\n      docstring: `/** ${m.name} - documented at line ${m.line} */`,\n      status: 'skipped',\n    });\n  }\n\n  return results;\n}\n"]}

package/dist/exec.js

@@ -1,11 +1,114 @@
 import { spawn } from 'node:child_process';
 import * as path from 'node:path';
 import * as Core from '@wrongstack/core';
-import { buildChildEnv, expectDefined } from '@wrongstack/core';
-import * as os from 'node:os';
+import { buildChildEnv, expectDefined, wstackGlobalRoot } from '@wrongstack/core';
 import * as fs from 'node:fs';
+import { mkdirSync, createWriteStream } from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import * as os from 'node:os';
 
 // src/exec.ts
+var SPOOL_RETENTION_MS = 7 * 24 * 60 * 60 * 1e3;
+var SPOOL_WRITE_HWM_BYTES = 4 * 1024 * 1024;
+var sweepStarted = false;
+function toolOutputDir() {
+  return path.join(wstackGlobalRoot(), "tool-output");
+}
+function sweepOldSpoolFiles(dir) {
+  if (sweepStarted) return;
+  sweepStarted = true;
+  void (async () => {
+    try {
+      const now = Date.now();
+      for (const name of await fsp.readdir(dir)) {
+        if (!name.endsWith(".log")) continue;
+        const p = path.join(dir, name);
+        try {
+          const st = await fsp.stat(p);
+          if (now - st.mtimeMs > SPOOL_RETENTION_MS) await fsp.unlink(p);
+        } catch {
+        }
+      }
+    } catch {
+    }
+  })();
+}
+function spoolNote(info) {
+  const dropped = info.droppedBytes > 0 ? `, ~${info.droppedBytes} bytes dropped under backpressure` : "";
+  return `
+[output truncated \u2014 full ${info.bytes} bytes at ${info.path}${dropped}; read/grep that file selectively instead of re-running with more output]`;
+}
+function createOutputSpool(opts) {
+  const threshold = opts.thresholdBytes;
+  const safeTool = opts.tool.replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 40) || "tool";
+  let head = "";
+  let headBytes = 0;
+  let totalBytes = 0;
+  let droppedBytes = 0;
+  let stream = null;
+  let filePath = null;
+  let failed = false;
+  let finalized = false;
+  const open = () => {
+    if (stream || failed) return;
+    try {
+      const dir = toolOutputDir();
+      mkdirSync(dir, { recursive: true });
+      sweepOldSpoolFiles(dir);
+      const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+      const rand = Math.random().toString(36).slice(2, 6);
+      filePath = path.join(dir, `${stamp}-${safeTool}-${rand}.log`);
+      stream = createWriteStream(filePath, { flags: "w", encoding: "utf8" });
+      stream.on("error", () => {
+        failed = true;
+        stream = null;
+        filePath = null;
+      });
+      stream.write(head);
+    } catch {
+      failed = true;
+      stream = null;
+      filePath = null;
+    }
+  };
+  return {
+    write(text) {
+      if (finalized || !text) return;
+      totalBytes += Buffer.byteLength(text, "utf8");
+      if (!stream && !failed) {
+        if (headBytes + text.length <= threshold) {
+          head += text;
+          headBytes += text.length;
+          return;
+        }
+        head += text;
+        open();
+        head = "";
+        return;
+      }
+      if (stream) {
+        if (stream.writableLength > SPOOL_WRITE_HWM_BYTES) {
+          droppedBytes += Buffer.byteLength(text, "utf8");
+          return;
+        }
+        stream.write(text);
+      }
+    },
+    finalize() {
+      if (finalized) {
+        return filePath ? { path: filePath, bytes: totalBytes, droppedBytes } : null;
+      }
+      finalized = true;
+      head = "";
+      if (!stream || !filePath) return null;
+      try {
+        stream.end();
+      } catch {
+      }
+      return { path: filePath, bytes: totalBytes, droppedBytes };
+    }
+  };
+}
 var COMMAND_OUTPUT_MAX_BYTES = 32768;
 var REPEAT_RUN_THRESHOLD = 3;
 function collapseCarriageReturns(text) {
@@ -686,6 +789,7 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
     let stderr = "";
     let killed = false;
     const startedAt = Date.now();
+    const spool = createOutputSpool({ tool: `exec-${cmd}`, thresholdBytes: MAX_OUTPUT });
     const resolved = resolveWin32Command(cmd);
     const isWin = process.platform === "win32";
     const needsShell = isWin && (resolved.endsWith(".cmd") || resolved.endsWith(".bat"));
@@ -718,10 +822,14 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
       else signal.addEventListener("abort", onAbort, { once: true });
     }
     child.stdout?.on("data", (chunk) => {
-      if (stdout.length < MAX_OUTPUT) stdout += chunk.toString();
+      const text = chunk.toString();
+      if (stdout.length < MAX_OUTPUT) stdout += text;
+      spool.write(text);
     });
     child.stderr?.on("data", (chunk) => {
-      if (stderr.length < MAX_OUTPUT) stderr += chunk.toString();
+      const text = chunk.toString();
+      if (stderr.length < MAX_OUTPUT) stderr += text;
+      spool.write(text);
     });
     child.on("close", (code) => {
       clearTimeout(timer);
@@ -730,10 +838,11 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
       const durationMs = Date.now() - startedAt;
       const exitCode = killed ? 124 : code ?? 1;
       registry.afterCall(durationMs, exitCode !== 0);
+      const spooled = spool.finalize();
       resolve2({
         command: cmd,
         args,
-        stdout: normalizeCommandOutput(stdout),
+        stdout: normalizeCommandOutput(stdout) + (spooled ? spoolNote(spooled) : ""),
         stderr: normalizeCommandOutput(stderr),
         exitCode,
         truncated: Buffer.byteLength(stdout, "utf8") > COMMAND_OUTPUT_MAX_BYTES || Buffer.byteLength(stderr, "utf8") > COMMAND_OUTPUT_MAX_BYTES,
@@ -745,6 +854,7 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
       if (isWin) signal.removeEventListener("abort", onAbort);
       if (typeof pid === "number") registry.unregister(pid);
       registry.afterCall(Date.now() - startedAt, true);
+      spool.finalize();
       resolve2({
         command: cmd,
         args,