@shawnstack/quickforge 1.3.17 → 1.3.18

package/README.md

@@ -1,7 +1,7 @@
 # 速构 QuickForge
 
 <p align="center">
-  <img alt="Version" src="https://img.shields.io/badge/version-1.3.17-blue" />
+  <img alt="Version" src="https://img.shields.io/badge/version-1.3.18-blue" />
   <img alt="License" src="https://img.shields.io/badge/license-MIT-green" />
   <img alt="Node" src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" />
   <img alt="React" src="https://img.shields.io/badge/react-19-61DAFB?logo=react" />
@@ -65,7 +65,7 @@ QuickForge 的工具能力很直接，因此也需要谨慎使用：
 #### 从 npm 安装
 
 ```bash
-npm install -g @shawnstack/quickforge@1.3.17
+npm install -g @shawnstack/quickforge@1.3.18
 qf
 
 # CLI 工具
@@ -79,17 +79,17 @@ qf update
 当前版本的离线包：
 
 ```text
-package-offline/shawnstack-quickforge-1.3.17.tgz
+package-offline/shawnstack-quickforge-1.3.18.tgz
 ```
 
 在安装了 Node.js 20+ 和 npm 的机器上执行：
 
 ```bash
-npm install -g ./package-offline/shawnstack-quickforge-1.3.17.tgz
+npm install -g ./package-offline/shawnstack-quickforge-1.3.18.tgz
 qf
 ```
 
-该包由 `v1.3.17` 标签生成，包含离线安装所需的运行时依赖。
+该包由 `v1.3.18` 标签生成，包含离线安装所需的运行时依赖。
 
 ### 本地开发
 
@@ -228,7 +228,7 @@ QuickForge intentionally exposes powerful local capabilities, so the boundaries
 #### npm
 
 ```bash
-npm install -g @shawnstack/quickforge@1.3.17
+npm install -g @shawnstack/quickforge@1.3.18
 qf
 
 # CLI utilities
@@ -239,20 +239,20 @@ qf update
 
 #### Offline tarball
 
-The offline release package for `v1.3.17` is:
+The offline release package for `v1.3.18` is:
 
 ```text
-package-offline/shawnstack-quickforge-1.3.17.tgz
+package-offline/shawnstack-quickforge-1.3.18.tgz
 ```
 
 Install it on a machine with Node.js 20+ and npm:
 
 ```bash
-npm install -g ./package-offline/shawnstack-quickforge-1.3.17.tgz
+npm install -g ./package-offline/shawnstack-quickforge-1.3.18.tgz
 qf
 ```
 
-The package was generated from tag `v1.3.17` and includes bundled runtime dependencies for offline installation.
+The package was generated from tag `v1.3.18` and includes bundled runtime dependencies for offline installation.
 
 ### Local development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shawnstack/quickforge",
-  "version": "1.3.17",
+  "version": "1.3.18",
   "description": "AI chat application with YOLO-mode local workspace tools. React + Vite + Tailwind CSS frontend, local Node.js storage server.",
   "keywords": [
     "ai",

package/server/tools/definitions.mjs

@@ -68,6 +68,8 @@ export const workspaceTools = [
     description: 'Run a shell command in the project bound to this chat. Use this for lint, build, tests, git status, and diagnostics.',
     parameters: Type.Object({
       command: Type.String({ description: 'Command to execute in the workspace.' }),
+      timeoutMs: Type.Optional(Type.Number({ description: 'Command timeout in milliseconds. Defaults to 30 minutes and is clamped to the supported range.', default: 1800000 })),
+      description: Type.Optional(Type.String({ description: 'Short explanation of why this command is being run.' })),
     }),
     executionMode: 'sequential',
   },

package/server/tools/index.mjs

@@ -1,8 +1,9 @@
-import { promises as fs } from 'node:fs'
+import { createWriteStream, promises as fs } from 'node:fs'
 import path from 'node:path'
 import { spawn } from 'node:child_process'
 import { createRequire } from 'node:module'
 import { resolveWorkspacePath, toWorkspaceRelative, assertSafeWorkspacePath, truncateText, splitLines, walkFiles } from '../utils/workspace.mjs'
+import { logsDir } from '../storage.mjs'
 import { createTextDiff } from '../utils/text-diff.mjs'
 import {
   formatSkillActivation,
@@ -476,63 +477,63 @@ export async function toolWriteFile(params, context) {
   }
 }
 
-// --- edit_file ---
-function countOccurrences(text, needle) {
-  if (!needle) return 0
-  let count = 0
-  let index = 0
-  while ((index = text.indexOf(needle, index)) !== -1) {
-    count++
-    index += needle.length
-  }
-  return count
-}
-
-function detectLineEnding(text) {
-  return text.includes('\r\n') ? '\r\n' : '\n'
-}
-
-function normalizeLineEndings(text) {
-  return text.replaceAll('\r\n', '\n').replaceAll('\r', '\n')
-}
-
-function convertToLineEnding(text, ending) {
-  const normalized = normalizeLineEndings(text)
-  return ending === '\r\n' ? normalized.replaceAll('\n', '\r\n') : normalized
-}
-
-export async function toolEditFile(params, context) {
-  const file = resolveWorkspacePath(params?.path, context)
-  await assertSafeWorkspacePath(file, context)
-
-  const rawOldText = String(params?.oldText ?? '')
-  const rawNewText = String(params?.newText ?? '')
-  const text = await fs.readFile(file, 'utf8')
-  const lineEnding = detectLineEnding(text)
-  const oldText = convertToLineEnding(rawOldText, lineEnding)
-  const newText = convertToLineEnding(rawNewText, lineEnding)
-  const count = countOccurrences(text, oldText)
-
-  if (count !== 1) {
-    const rawCount = oldText === rawOldText ? count : countOccurrences(text, rawOldText)
-    const suffix = rawCount !== count ? ` after normalizing line endings; raw match count was ${rawCount}` : ''
-    const error = new Error(`oldText must match exactly once; found ${count} matches${suffix}`)
-    error.statusCode = 400
-    throw error
-  }
-
-  const nextText = text.replace(oldText, newText)
-  const relativePath = toWorkspaceRelative(file, context)
-  const diff = createTextDiff(text, nextText, relativePath)
-
-  await fs.writeFile(file, nextText, 'utf8')
-
-  return {
-    content: `Edited ${relativePath} (+${diff.addedLines} -${diff.removedLines})`,
-    details: { path: relativePath, project: context?.project, replaced: count, diff },
-  }
-}
-
+// --- edit_file ---
+function countOccurrences(text, needle) {
+  if (!needle) return 0
+  let count = 0
+  let index = 0
+  while ((index = text.indexOf(needle, index)) !== -1) {
+    count++
+    index += needle.length
+  }
+  return count
+}
+
+function detectLineEnding(text) {
+  return text.includes('\r\n') ? '\r\n' : '\n'
+}
+
+function normalizeLineEndings(text) {
+  return text.replaceAll('\r\n', '\n').replaceAll('\r', '\n')
+}
+
+function convertToLineEnding(text, ending) {
+  const normalized = normalizeLineEndings(text)
+  return ending === '\r\n' ? normalized.replaceAll('\n', '\r\n') : normalized
+}
+
+export async function toolEditFile(params, context) {
+  const file = resolveWorkspacePath(params?.path, context)
+  await assertSafeWorkspacePath(file, context)
+
+  const rawOldText = String(params?.oldText ?? '')
+  const rawNewText = String(params?.newText ?? '')
+  const text = await fs.readFile(file, 'utf8')
+  const lineEnding = detectLineEnding(text)
+  const oldText = convertToLineEnding(rawOldText, lineEnding)
+  const newText = convertToLineEnding(rawNewText, lineEnding)
+  const count = countOccurrences(text, oldText)
+
+  if (count !== 1) {
+    const rawCount = oldText === rawOldText ? count : countOccurrences(text, rawOldText)
+    const suffix = rawCount !== count ? ` after normalizing line endings; raw match count was ${rawCount}` : ''
+    const error = new Error(`oldText must match exactly once; found ${count} matches${suffix}`)
+    error.statusCode = 400
+    throw error
+  }
+
+  const nextText = text.replace(oldText, newText)
+  const relativePath = toWorkspaceRelative(file, context)
+  const diff = createTextDiff(text, nextText, relativePath)
+
+  await fs.writeFile(file, nextText, 'utf8')
+
+  return {
+    content: `Edited ${relativePath} (+${diff.addedLines} -${diff.removedLines})`,
+    details: { path: relativePath, project: context?.project, replaced: count, diff },
+  }
+}
+
 // --- run_command ---
 function activeSkillsForContext(context) {
   return mergeSkills(context?.globalSkills, context?.projectSkills)
@@ -587,6 +588,29 @@ export async function toolReadSkillResource(params, context) {
 }
 
 // --- run_command ---
+const DEFAULT_RUN_COMMAND_TIMEOUT_MS = 30 * 60 * 1000
+const MIN_RUN_COMMAND_TIMEOUT_MS = 1000
+const MAX_RUN_COMMAND_TIMEOUT_MS = 30 * 60 * 1000
+const COMMAND_TAIL_LINES = 100
+
+function formatDurationMs(durationMs = 0) {
+  const totalSeconds = Math.max(0, Math.floor(durationMs / 1000))
+  const minutes = Math.floor(totalSeconds / 60)
+  const seconds = totalSeconds % 60
+  if (minutes > 0) return `${minutes}m ${seconds}s (${durationMs}ms)`
+  return `${seconds}s (${durationMs}ms)`
+}
+
+function tailText(current, chunk, maxLines = COMMAND_TAIL_LINES) {
+  const lines = (current + chunk).split(/\r?\n/)
+  if (lines.length <= maxLines) return lines.join('\n')
+  return lines.slice(lines.length - maxLines).join('\n')
+}
+
+function tailLabel(name, truncated) {
+  return truncated ? `${name} (last ${COMMAND_TAIL_LINES} lines):` : `${name}:`
+}
+
 function commandStatus(meta = {}) {
   if (meta.running) return 'Status: running'
   const flags = [
@@ -598,16 +622,46 @@ function commandStatus(meta = {}) {
 }
 
 function formatCommandOutput(command, stdout, stderr, meta = {}) {
-  return [
+  const lines = [
     `Command: ${command}`,
-    commandStatus(meta),
-    '',
-    'STDOUT:',
-    stdout || '(empty)',
+  ]
+  if (meta.description) lines.push(`Description: ${meta.description}`)
+  lines.push(commandStatus(meta))
+  if (typeof meta.durationMs === 'number') lines.push(`Duration: ${formatDurationMs(meta.durationMs)}`)
+  if (typeof meta.timeoutMs === 'number') lines.push(`Timeout: ${formatDurationMs(meta.timeoutMs)}`)
+  if (meta.cwd) lines.push(`CWD: ${meta.cwd}`)
+  if (meta.outputFile) lines.push(`Full output: ${meta.outputFile}`)
+  if (meta.outputTruncated) lines.push(`Output mode: showing the last ${COMMAND_TAIL_LINES} lines; full output is saved to the log file.`)
+  if (meta.logError) lines.push(`Log warning: ${meta.logError}`)
+  lines.push('', tailLabel('STDOUT', meta.stdoutTruncated), stdout || '(empty)', '', tailLabel('STDERR', meta.stderrTruncated), stderr || '(empty)')
+  return lines.join('\n')
+}
+
+function safeLogFilePart(value, fallback) {
+  const text = String(value || '').replace(/[^a-zA-Z0-9_.-]/g, '_').slice(0, 80)
+  return text || fallback
+}
+
+async function createCommandLogStream(command, { cwd, description, toolCallId } = {}) {
+  const dir = path.join(logsDir, 'commands')
+  await fs.mkdir(dir, { recursive: true })
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
+  const fileName = `${timestamp}_${safeLogFilePart(toolCallId, 'command')}.log`
+  const outputFile = path.join(dir, fileName)
+  const stream = createWriteStream(outputFile, { flags: 'wx' })
+  stream.write([
+    `Command: ${command}`,
+    description ? `Description: ${description}` : null,
+    `CWD: ${cwd}`,
+    `Started at: ${new Date().toISOString()}`,
     '',
-    'STDERR:',
-    stderr || '(empty)',
-  ].join('\n')
+  ].filter(Boolean).join('\n'))
+  return { stream, outputFile }
+}
+
+function writeCommandLog(stream, source, chunk) {
+  stream.write(`\n[${source} ${new Date().toISOString()}]\n`)
+  stream.write(chunk)
 }
 
 function killProcessTree(child, signal = 'SIGTERM') {
@@ -641,8 +695,6 @@ export function abortRunningCommand(toolCallId) {
   return true
 }
 
-const RUN_COMMAND_TIMEOUT_MS = 30 * 60 * 1000
-
 export async function toolRunCommand(params, context, runtime = {}) {
   const command = String(params?.command || '')
   if (!command.trim()) {
@@ -651,12 +703,34 @@ export async function toolRunCommand(params, context, runtime = {}) {
     throw error
   }
 
-  const timeoutMs = RUN_COMMAND_TIMEOUT_MS
+  const description = String(params?.description || '').trim().slice(0, 500)
+  const timeoutMs = clampNumber(params?.timeoutMs, DEFAULT_RUN_COMMAND_TIMEOUT_MS, MIN_RUN_COMMAND_TIMEOUT_MS, MAX_RUN_COMMAND_TIMEOUT_MS)
   const cwd = getToolWorkspaceRoot(context)
+  const startedAt = Date.now()
 
   if (runtime.signal?.aborted) {
-    const content = formatCommandOutput(command, '', 'Command aborted before start.', { aborted: true })
-    return { content: truncateText(content), details: { command, project: context?.project, cwd, aborted: true } }
+    const content = formatCommandOutput(command, '', 'Command aborted before start.', {
+      aborted: true,
+      cwd,
+      description,
+      timeoutMs,
+      durationMs: 0,
+    })
+    return { content: truncateText(content), details: { command, description, project: context?.project, cwd, timeoutMs, durationMs: 0, aborted: true } }
+  }
+
+  let logStream = null
+  let outputFile = null
+  let logError = null
+  try {
+    const log = await createCommandLogStream(command, { cwd, description, toolCallId: runtime.toolCallId })
+    logStream = log.stream
+    outputFile = log.outputFile
+    logStream.on('error', (error) => {
+      logError = error?.message || 'Failed to write command log.'
+    })
+  } catch (error) {
+    logError = error?.message || 'Failed to create command log.'
   }
 
   return new Promise((resolve) => {
@@ -670,6 +744,8 @@ export async function toolRunCommand(params, context, runtime = {}) {
 
     let stdout = ''
     let stderr = ''
+    let stdoutTruncated = false
+    let stderrTruncated = false
     let timedOut = false
     let aborted = false
     let settled = false
@@ -685,21 +761,65 @@ export async function toolRunCommand(params, context, runtime = {}) {
       runtime.signal?.removeEventListener?.('abort', onAbort)
     }
 
+    const commonDetails = (extra = {}) => {
+      const now = Date.now()
+      return {
+        command,
+        description,
+        project: context?.project,
+        cwd,
+        timeoutMs,
+        outputFile,
+        stdout,
+        stderr,
+        stdoutTruncated,
+        stderrTruncated,
+        outputTruncated: stdoutTruncated || stderrTruncated,
+        durationMs: now - startedAt,
+        toolCallId: runtime.toolCallId,
+        logError,
+        ...extra,
+      }
+    }
+
+    const resolveAfterLogClose = (result) => {
+      if (!logStream) {
+        resolve(result)
+        return
+      }
+      const details = result.details || {}
+      logStream.write([
+        '',
+        '',
+        `[quickforge ${new Date().toISOString()}]`,
+        `Exit code: ${details.code ?? 'unknown'}${details.signal ? `, signal: ${details.signal}` : ''}`,
+        `Duration: ${formatDurationMs(details.durationMs)}`,
+        `Timed out: ${Boolean(details.timedOut)}`,
+        `Aborted: ${Boolean(details.aborted)}`,
+        'Command finished.',
+        '',
+      ].join('\n'))
+      logStream.end(() => resolve(result))
+    }
+
     const finish = ({ code = null, signal = null, error = null } = {}) => {
       if (settled) return
       flushUpdate()
       settled = true
       cleanup()
+      const durationMs = Date.now() - startedAt
       if (error) {
-        resolve({
+        const details = commonDetails({ error: error.message, aborted, timedOut, durationMs })
+        resolveAfterLogClose({
           isError: true,
-          content: truncateText(`Error running command: ${error.message}`),
-          details: { command, project: context?.project, cwd, error: error.message, aborted, timedOut },
+          content: truncateText(formatCommandOutput(command, stdout, `Error running command: ${error.message}\n${stderr}`.trim(), details)),
+          details,
         })
         return
       }
-      const content = formatCommandOutput(command, stdout, stderr, { code, signal, timedOut, aborted })
-      resolve({ content: truncateText(content), details: { command, project: context?.project, cwd, code, signal, timedOut, aborted } })
+      const details = commonDetails({ code, signal, timedOut, aborted, durationMs })
+      const content = formatCommandOutput(command, stdout, stderr, details)
+      resolveAfterLogClose({ content: truncateText(content), details })
     }
 
     const stopChild = (reason) => {
@@ -718,15 +838,16 @@ export async function toolRunCommand(params, context, runtime = {}) {
       finish({ signal: 'SIGTERM' })
     }
 
-    const runningDetails = () => ({ command, project: context?.project, cwd, running: true, stdout, stderr, toolCallId: runtime.toolCallId })
+    const runningDetails = () => commonDetails({ running: true })
 
     const emitUpdate = () => {
       updateTimer = null
       if (settled || !updatePending) return
       updatePending = false
+      const details = runningDetails()
       runtime.onUpdate?.({
-        content: [{ type: 'text', text: truncateText(formatCommandOutput(command, stdout, stderr, { running: true })) }],
-        details: runningDetails(),
+        content: [{ type: 'text', text: truncateText(formatCommandOutput(command, stdout, stderr, details)) }],
+        details,
       })
     }
     const flushUpdate = () => {
@@ -736,9 +857,10 @@ export async function toolRunCommand(params, context, runtime = {}) {
       }
       if (!updatePending) return
       updatePending = false
+      const details = runningDetails()
       runtime.onUpdate?.({
-        content: [{ type: 'text', text: truncateText(formatCommandOutput(command, stdout, stderr, { running: true })) }],
-        details: runningDetails(),
+        content: [{ type: 'text', text: truncateText(formatCommandOutput(command, stdout, stderr, details)) }],
+        details,
       })
     }
     const scheduleUpdate = () => {
@@ -755,12 +877,18 @@ export async function toolRunCommand(params, context, runtime = {}) {
 
     child.stdout.on('data', (chunk) => {
       if (settled) return
-      stdout = truncateText(stdout + chunk.toString())
+      const text = chunk.toString()
+      stdoutTruncated = stdoutTruncated || (stdout + text).split(/\r?\n/).length > COMMAND_TAIL_LINES
+      stdout = tailText(stdout, text)
+      if (logStream && !logError) writeCommandLog(logStream, 'stdout', text)
       scheduleUpdate()
     })
     child.stderr.on('data', (chunk) => {
       if (settled) return
-      stderr = truncateText(stderr + chunk.toString())
+      const text = chunk.toString()
+      stderrTruncated = stderrTruncated || (stderr + text).split(/\r?\n/).length > COMMAND_TAIL_LINES
+      stderr = tailText(stderr, text)
+      if (logStream && !logError) writeCommandLog(logStream, 'stderr', text)
       scheduleUpdate()
     })
     child.on('close', (code, signal) => {