@shawnstack/quickforge 1.0.0 → 1.2.0

package/server/system-prompt.mjs

@@ -0,0 +1,67 @@
+export const BASE_SYSTEM_PROMPT = `You are a pragmatic coding assistant.
+
+For project tasks:
+- Inspect the workspace before changing files.
+- Make minimal, focused changes.
+- Prefer dedicated workspace tools for reading, editing, and searching files.
+- If dedicated tools are unavailable or insufficient, use the shell/command tool.
+- Use Python through the shell for reliable scripting, data processing, or file transformations.
+- Stay within the current workspace unless the user explicitly asks otherwise.
+- Verify changes with relevant tests, build, lint, or targeted checks.
+- If no suitable tool is available, say so clearly.`
+
+function escapeXml(value) {
+  return String(value ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+function formatSkillCatalogItem(skill) {
+  const details = [
+    `    <name>${escapeXml(skill.name)}</name>`,
+    `    <description>${escapeXml(skill.description)}</description>`,
+  ]
+
+  if (skill.compatibility) details.push(`    <compatibility>${escapeXml(skill.compatibility)}</compatibility>`)
+  if (skill.allowedTools) details.push(`    <allowed_tools>${escapeXml(skill.allowedTools)}</allowed_tools>`)
+
+  return `  <skill>\n${details.join('\n')}\n  </skill>`
+}
+
+function appendSkillsCatalog(parts, skills) {
+  if (!Array.isArray(skills) || skills.length === 0) return
+
+  const skillParts = skills.map(formatSkillCatalogItem)
+  parts.push(`
+<available_skills>
+The following Agent Skills provide specialized instructions for specific tasks. Use progressive disclosure: this catalog is available now, but full skill instructions are loaded only when needed.
+
+When the user's task matches a skill description, call activate_skill with that skill's name before proceeding. If a loaded skill references bundled files under scripts/, references/, or assets/, call read_skill_resource with the skill name and the relative path. Do not assume resources are already loaded.
+
+${skillParts.join('\n')}
+</available_skills>`)
+}
+
+export function composeSystemPrompt(instructions = {}) {
+  const parts = [BASE_SYSTEM_PROMPT]
+
+  if (instructions.global) {
+    parts.push(`\n<user_instructions>\n${instructions.global}\n</user_instructions>`)
+  }
+
+  if (instructions.project) {
+    parts.push(`\n<project_instructions>\n${instructions.project}\n</project_instructions>`)
+  }
+
+  const skills = Array.isArray(instructions.skills)
+    ? instructions.skills
+    : [
+        ...(Array.isArray(instructions.globalSkills) ? instructions.globalSkills : []),
+        ...(Array.isArray(instructions.projectSkills) ? instructions.projectSkills : []),
+      ]
+
+  appendSkillsCatalog(parts, skills)
+
+  return parts.join('\n')
+}

package/server/tools/definitions.mjs

@@ -0,0 +1,120 @@
+import { Type } from 'typebox'
+import { loadSelectedGlobalSkills, loadSelectedProjectSkills, mergeSkills } from '../skills.mjs'
+
+// ---------------------------------------------------------------------------
+// Canonical workspace tool definitions.
+// These are the single source of truth for tool metadata (name, label,
+// description, parameters). Both the server agent-manager (which wraps them
+// with execute handlers) and the GET /api/tools endpoint (which returns them
+// as JSON) import from here.
+//
+// When adding a new tool, add its definition here. The agent-manager connects
+// it to a handler, and the frontend can fetch definitions from /api/tools.
+// ---------------------------------------------------------------------------
+
+export const workspaceTools = [
+  {
+    name: 'get_project_info',
+    label: 'Project info',
+    description: 'Get the project directory bound to this chat.',
+    parameters: Type.Object({}),
+  },
+  {
+    name: 'list_dir',
+    label: 'List directory',
+    description: 'List files and folders inside the project bound to this chat. Paths are relative to that project root.',
+    parameters: Type.Object({
+      path: Type.Optional(Type.String({ description: 'Directory path relative to the workspace root. Defaults to .', default: '.' })),
+    }),
+  },
+  {
+    name: 'read_file',
+    label: 'Read file',
+    description: 'Read a UTF-8 text file inside the project bound to this chat. Use offset and limit for large files.',
+    parameters: Type.Object({
+      path: Type.String({ description: 'File path relative to the workspace root.' }),
+      offset: Type.Optional(Type.Number({ description: '1-based line offset.', default: 1 })),
+      limit: Type.Optional(Type.Number({ description: 'Maximum number of lines to return.', default: 200 })),
+    }),
+  },
+  {
+    name: 'grep_files',
+    label: 'Search files',
+    description: 'Search text in the project files bound to this chat. Returns matching file paths and line numbers.',
+    parameters: Type.Object({
+      query: Type.String({ description: 'Plain text or regular expression to search for.' }),
+      path: Type.Optional(Type.String({ description: 'Directory path relative to the workspace root. Defaults to .', default: '.' })),
+      regex: Type.Optional(Type.Boolean({ description: 'Treat query as a regular expression.', default: false })),
+      caseSensitive: Type.Optional(Type.Boolean({ description: 'Use case-sensitive matching.', default: false })),
+      limit: Type.Optional(Type.Number({ description: 'Maximum matches to return.', default: 200 })),
+    }),
+  },
+  {
+    name: 'write_file',
+    label: 'Write file',
+    description: 'Create or overwrite a UTF-8 text file inside the project bound to this chat.',
+    parameters: Type.Object({
+      path: Type.String({ description: 'File path relative to the workspace root.' }),
+      content: Type.String({ description: 'Complete file content to write.' }),
+    }),
+    executionMode: 'sequential',
+  },
+  {
+    name: 'edit_file',
+    label: 'Edit file',
+    description: 'Edit a text file in the project bound to this chat by replacing exact text. oldText must match exactly once.',
+    parameters: Type.Object({
+      path: Type.String({ description: 'File path relative to the workspace root.' }),
+      oldText: Type.String({ description: 'Exact existing text to replace. Must be unique in the file.' }),
+      newText: Type.String({ description: 'Replacement text.' }),
+    }),
+    executionMode: 'sequential',
+  },
+  {
+    name: 'run_command',
+    label: 'Run command',
+    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.' }),
+      timeoutSeconds: Type.Optional(Type.Number({ description: 'Timeout in seconds. Defaults to 60.', default: 60 })),
+    }),
+    executionMode: 'sequential',
+  },
+]
+
+function activeSkillSchema(skills) {
+  const names = skills.map((skill) => skill.name).filter(Boolean)
+  return names.length ? Type.String({ enum: names }) : Type.String()
+}
+
+export async function createSkillTools(config = {}) {
+  const globalSkills = await loadSelectedGlobalSkills(config.globalSkillNames)
+  const projectSkills = config.workspaceRoot
+    ? await loadSelectedProjectSkills(config.projectSkillNames, config.workspaceRoot)
+    : []
+  const skills = mergeSkills(globalSkills, projectSkills)
+  if (skills.length === 0) return []
+
+  const skillNameSchema = activeSkillSchema(skills)
+  return [
+    {
+      name: 'activate_skill',
+      label: 'Activate skill',
+      description: 'Load the full instructions for an enabled Agent Skill when the current task matches its description.',
+      parameters: Type.Object({
+        name: skillNameSchema,
+      }),
+    },
+    {
+      name: 'read_skill_resource',
+      label: 'Read skill resource',
+      description: 'Read a text resource bundled with an activated Agent Skill. Paths are relative to that skill directory.',
+      parameters: Type.Object({
+        skill: skillNameSchema,
+        path: Type.String({ description: 'Relative path inside the skill directory, for example references/REFERENCE.md or scripts/helper.py.' }),
+        offset: Type.Optional(Type.Number({ description: '1-based line offset.', default: 1 })),
+        limit: Type.Optional(Type.Number({ description: 'Maximum number of lines to return.', default: 200 })),
+      }),
+    },
+  ]
+}

package/server/tools/index.mjs

@@ -1,10 +1,36 @@
 import { promises as fs } from 'node:fs'
 import path from 'node:path'
 import { spawn } from 'node:child_process'
-import { resolveWorkspacePath, toWorkspaceRelative, assertSafeWorkspacePath, truncateText, splitLines, shouldSkipSearchDir, shouldSearchFile, isSensitiveWorkspacePath } from '../utils/workspace.mjs'
+import { resolveWorkspacePath, toWorkspaceRelative, assertSafeWorkspacePath, truncateText, splitLines, walkFiles } from '../utils/workspace.mjs'
 import { readProjectConfig, getActiveProject } from '../project-config.mjs'
+import {
+  formatSkillActivation,
+  loadSelectedGlobalSkills,
+  loadSelectedProjectSkills,
+  mergeSkills,
+  readSkillResource,
+} from '../skills.mjs'
 import { getWorkspaceRoot, getToolWorkspaceRoot } from '../utils/workspace.mjs'
 
+// --- get_project_info ---
+export async function toolGetProjectInfo(_params, context) {
+  const config = context?.project ? null : await readProjectConfig()
+  const project = context?.project || getActiveProject(config)
+  const workspaceRoot = context?.workspaceRoot || project?.path || getWorkspaceRoot()
+
+  if (!project) {
+    return {
+      content: 'No active project is configured.',
+      details: { project: null, workspaceRoot },
+    }
+  }
+
+  return {
+    content: [`Project: ${project.name}`, `Path: ${workspaceRoot}`, `ID: ${project.id}`].join('\n'),
+    details: { project, workspaceRoot },
+  }
+}
+
 // --- list_dir ---
 export async function toolListDir(params, context) {
   const dir = resolveWorkspacePath(params?.path || '.', context)
@@ -54,6 +80,31 @@ export async function toolReadFile(params, context) {
 }
 
 // --- grep_files ---
+
+/**
+ * Process items with bounded concurrency.  Returns results in input order.
+ * @template T, R
+ * @param {T[]} items
+ * @param {(item: T, index: number) => Promise<R>} fn
+ * @param {number} concurrency
+ * @returns {Promise<R[]>}
+ */
+async function poolMap(items, fn, concurrency = 20) {
+  const results = new Array(items.length)
+  let cursor = 0
+
+  async function worker() {
+    while (cursor < items.length) {
+      const index = cursor++
+      results[index] = await fn(items[index], index)
+    }
+  }
+
+  const workers = Array.from({ length: Math.min(concurrency, items.length) }, () => worker())
+  await Promise.all(workers)
+  return results
+}
+
 export async function toolGrepFiles(params, context) {
   const root = resolveWorkspacePath(params?.path || '.', context)
   assertSafeWorkspacePath(root, context)
@@ -67,24 +118,62 @@ export async function toolGrepFiles(params, context) {
 
   const limit = Math.min(1000, Math.max(1, Number(params?.limit || 200)))
   const flags = params?.caseSensitive ? 'g' : 'gi'
-  const matcher = params?.regex
-    ? new RegExp(query, flags)
-    : new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), flags)
+  let matcher
+  try {
+    matcher = params?.regex
+      ? new RegExp(query, flags)
+      : new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), flags)
+  } catch {
+    const error = new Error('Invalid regular expression')
+    error.statusCode = 400
+    throw error
+  }
 
   const files = await walkFiles(root, [], context)
   const matches = []
 
-  for (const file of files) {
-    if (matches.length >= limit) break
-    const stat = await fs.stat(file)
-    if (stat.size > 1024 * 1024) continue
-
-    const text = await fs.readFile(file, 'utf8').catch(() => '')
-    const lines = splitLines(text)
-    for (let index = 0; index < lines.length && matches.length < limit; index++) {
-      matcher.lastIndex = 0
-      if (matcher.test(lines[index])) {
-        matches.push(`${toWorkspaceRelative(file, context)}:${index + 1}: ${lines[index]}`)
+  // Stat and filter files in parallel, then grep in parallel batches
+  const candidateResults = await poolMap(files, async (file) => {
+    try {
+      const stat = await fs.stat(file)
+      if (stat.size > 1024 * 1024) return { file, skip: true }
+      return { file, skip: false }
+    } catch {
+      return { file, skip: true }
+    }
+  })
+
+  const candidates = candidateResults.filter((r) => !r.skip).map((r) => r.file)
+
+  // Grep with bounded concurrency — short-circuit when limit reached
+  let matchCount = 0
+  for (let batchStart = 0; batchStart < candidates.length && matchCount < limit; batchStart += 20) {
+    const batch = candidates.slice(batchStart, batchStart + 20)
+    const batchMatches = await Promise.all(
+      batch.map(async (file) => {
+        if (matchCount >= limit) return []
+        try {
+          const text = await fs.readFile(file, 'utf8')
+          const lines = splitLines(text)
+          const fileMatches = []
+          for (let index = 0; index < lines.length && (matchCount + fileMatches.length) < limit; index++) {
+            matcher.lastIndex = 0
+            if (matcher.test(lines[index])) {
+              fileMatches.push(`${toWorkspaceRelative(file, context)}:${index + 1}: ${lines[index]}`)
+            }
+          }
+          return fileMatches
+        } catch {
+          return []
+        }
+      }),
+    )
+    for (const fm of batchMatches) {
+      if (matchCount >= limit) break
+      for (const m of fm) {
+        if (matchCount >= limit) break
+        matches.push(m)
+        matchCount++
       }
     }
   }
@@ -144,6 +233,59 @@ export async function toolEditFile(params, context) {
   }
 }
 
+// --- run_command ---
+function activeSkillsForContext(context) {
+  return mergeSkills(context?.globalSkills, context?.projectSkills)
+}
+
+function activeSkillByName(context, name) {
+  const skillName = String(name || '')
+  return activeSkillsForContext(context).find((skill) => skill.name === skillName)
+}
+
+export async function loadSkillToolContext(config = {}) {
+  const globalSkills = await loadSelectedGlobalSkills(config.globalSkillNames)
+  const projectSkills = config.workspaceRoot
+    ? await loadSelectedProjectSkills(config.projectSkillNames, config.workspaceRoot)
+    : []
+  return { globalSkills, projectSkills }
+}
+
+// --- activate_skill ---
+export async function toolActivateSkill(params, context) {
+  const skill = activeSkillByName(context, params?.name)
+  if (!skill) {
+    const error = new Error(`Unknown or disabled skill: ${params?.name || ''}`)
+    error.statusCode = 404
+    throw error
+  }
+
+  return {
+    content: truncateText(await formatSkillActivation(skill)),
+    details: {
+      skill: skill.name,
+      source: skill.source,
+      directory: skill.rootDir,
+    },
+  }
+}
+
+// --- read_skill_resource ---
+export async function toolReadSkillResource(params, context) {
+  const skill = activeSkillByName(context, params?.skill)
+  if (!skill) {
+    const error = new Error(`Unknown or disabled skill: ${params?.skill || ''}`)
+    error.statusCode = 404
+    throw error
+  }
+
+  const result = await readSkillResource(skill, params?.path, params)
+  return {
+    content: truncateText(result.content),
+    details: result.details,
+  }
+}
+
 // --- run_command ---
 export async function toolRunCommand(params, context) {
   const command = String(params?.command || '')
@@ -191,40 +333,17 @@ export async function toolRunCommand(params, context) {
       ].join('\n')
       resolve({ content: truncateText(content), details: { command, project: context?.project, cwd: getToolWorkspaceRoot(context), code, signal, timedOut } })
     })
+    child.on('error', (err) => {
+      clearTimeout(timer)
+      resolve({
+        isError: true,
+        content: truncateText(`Error running command: ${err.message}`),
+        details: { command, project: context?.project, error: err.message },
+      })
+    })
   })
 }
 
-// --- get_project_info ---
-export async function toolGetProjectInfo(_params, context) {
-  if (context?.project) {
-    return {
-      content: `Project: ${context.project.name}\nRoot: ${context.project.path}`,
-      details: { project: context.project, workspaceRoot: context.workspaceRoot },
-    }
-  }
-
-  const config = await readProjectConfig()
-  const project = getActiveProject(config)
-  return {
-    content: `Active project: ${project.name}\nRoot: ${project.path}`,
-    details: { project, workspaceRoot: getWorkspaceRoot() },
-  }
-}
-
-// Helper for grep
-async function walkFiles(root, files = [], context) {
-  const entries = await fs.readdir(root, { withFileTypes: true })
-  for (const entry of entries) {
-    const fullPath = path.join(root, entry.name)
-    if (entry.isDirectory()) {
-      if (!shouldSkipSearchDir(entry.name)) await walkFiles(fullPath, files, context)
-    } else if (entry.isFile() && shouldSearchFile(entry.name) && !isSensitiveWorkspacePath(fullPath, context)) {
-      files.push(fullPath)
-    }
-  }
-  return files
-}
-
 export const toolHandlers = {
   get_project_info: toolGetProjectInfo,
   list_dir: toolListDir,
@@ -233,4 +352,6 @@ export const toolHandlers = {
   write_file: toolWriteFile,
   edit_file: toolEditFile,
   run_command: toolRunCommand,
+  activate_skill: toolActivateSkill,
+  read_skill_resource: toolReadSkillResource,
 }

package/server/utils/logger.mjs

@@ -0,0 +1,34 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { logsDir } from '../storage.mjs'
+
+function timestamp() {
+  return new Date().toISOString()
+}
+
+function logFile() {
+  const date = new Date().toISOString().slice(0, 10)
+  return path.join(logsDir, `server-${date}.log`)
+}
+
+function formatArgs(args) {
+  return args.map((a) =>
+    typeof a === 'string' ? a : a instanceof Error ? a.stack : JSON.stringify(a),
+  ).join(' ')
+}
+
+function writeLog(level, ...args) {
+  const line = `${timestamp()} [${level}] ${formatArgs(args)}\n`
+  process.stderr.write(line)
+  try {
+    fs.appendFileSync(logFile(), line)
+  } catch {
+    // ignore write errors
+  }
+}
+
+export const logger = {
+  info: (...args) => writeLog('INFO', ...args),
+  warn: (...args) => writeLog('WARN', ...args),
+  error: (...args) => writeLog('ERROR', ...args),
+}

package/server/utils/network.mjs

@@ -0,0 +1,38 @@
+import os from 'node:os'
+
+export function isPrivateIpv4(hostname) {
+  if (!/^\d{1,3}(?:\.\d{1,3}){3}$/.test(hostname || '')) return false
+  const parts = hostname.split('.').map((part) => Number(part))
+  if (parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return false
+  const [a, b] = parts
+  return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168)
+}
+
+export function isLoopbackAddress(address) {
+  if (!address) return false
+  const normalized = address.replace(/^::ffff:/, '')
+  return normalized === '127.0.0.1' || normalized === '::1' || normalized === 'localhost'
+}
+
+export function getLanIpv4Addresses() {
+  const result = []
+  const seen = new Set()
+  const interfaces = os.networkInterfaces()
+
+  for (const entries of Object.values(interfaces)) {
+    for (const entry of entries || []) {
+      if (entry.family !== 'IPv4' || entry.internal) continue
+      if (!isPrivateIpv4(entry.address)) continue
+      if (seen.has(entry.address)) continue
+      seen.add(entry.address)
+      result.push(entry.address)
+    }
+  }
+
+  return result
+}
+
+export function getLanUrls(port, protocol = 'http') {
+  const safePort = Number(port)
+  return getLanIpv4Addresses().map((address) => `${protocol}://${address}${safePort ? `:${safePort}` : ''}`)
+}

package/server/utils/platform.mjs

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process'
+import { promises as fs } from 'node:fs'
 import path from 'node:path'
 import os from 'node:os'
 
@@ -121,8 +122,37 @@ try {
   throw error
 }
 
+export async function openPathInFileManager(targetPath) {
+  const resolved = path.resolve(String(targetPath || ''))
+  const stat = await fs.stat(resolved).catch(() => null)
+  if (!stat || !stat.isDirectory()) {
+    const error = new Error(`Directory does not exist: ${resolved}`)
+    error.statusCode = 400
+    throw error
+  }
+
+  const command = process.platform === 'win32' ? 'explorer.exe' : process.platform === 'darwin' ? 'open' : 'xdg-open'
+  const args = [resolved]
+  await new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: false,
+      shell: false,
+    })
+    child.once('error', (error) => {
+      error.statusCode = 500
+      reject(error)
+    })
+    child.once('spawn', () => {
+      child.unref()
+      resolve()
+    })
+  })
+}
+
 export function openBrowser(url) {
-  if (process.env.QUICKFORGE_NO_OPEN === '1' || process.env.FASTCODE_NO_OPEN === '1') return
+  if (process.env.QUICKFORGE_NO_OPEN === '1') return
 
   const command = process.platform === 'win32' ? 'cmd' : process.platform === 'darwin' ? 'open' : 'xdg-open'
   const args = process.platform === 'win32' ? ['/c', 'start', '""', url] : [url]

package/server/utils/response.mjs

@@ -1,4 +1,4 @@
-const DEFAULT_MAX_BODY_BYTES = Number(process.env.QUICKFORGE_MAX_BODY_BYTES || process.env.FASTCODE_MAX_BODY_BYTES || 50 * 1024 * 1024)
+const DEFAULT_MAX_BODY_BYTES = Number(process.env.QUICKFORGE_MAX_BODY_BYTES || 50 * 1024 * 1024)
 
 export function sendJson(res, status, value) {
   const body = JSON.stringify(value)
@@ -27,7 +27,14 @@ export async function readJsonBody(req, maxBodyBytes = DEFAULT_MAX_BODY_BYTES) {
     chunks.push(chunk)
   }
   const text = Buffer.concat(chunks).toString('utf8')
-  return text ? JSON.parse(text) : null
+  if (!text) return null
+  try {
+    return JSON.parse(text.trimStart())
+  } catch {
+    const error = new Error('Invalid JSON request body')
+    error.statusCode = 400
+    throw error
+  }
 }
 
 export function decodeSegment(value) {