@shawnstack/quickforge 1.3.24 → 1.3.26

package/server/custom-commands.mjs

@@ -1,6 +1,8 @@
 import { promises as fs } from 'node:fs'
 import path from 'node:path'
+import { getEnabledPluginCommandSources } from './plugins/registry.mjs'
 
+const commandsRelativeDirs = ['.claude/commands', '.opencode/commands', '.ai/commands']
 const commandsRelativeDir = '.ai/commands'
 const commandNamePattern = /^(?!.*--)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/
 
@@ -23,10 +25,9 @@ function configuredCommandDirectories(workspaceRoot, commandDir) {
 }
 
 function commandDirectories(workspaceRoot, commandDir) {
-  const defaultDir = commandDirectory(workspaceRoot)
-  if (!defaultDir) return []
+  if (!workspaceRoot) return []
 
-  const dirs = [defaultDir]
+  const dirs = commandsRelativeDirs.map((dir) => path.join(path.resolve(workspaceRoot), dir))
   for (const configuredDir of configuredCommandDirectories(workspaceRoot, commandDir)) {
     if (!dirs.some((dir) => path.resolve(dir) === path.resolve(configuredDir))) {
       dirs.push(configuredDir)
@@ -102,7 +103,7 @@ function firstOptionalBoolean(...values) {
   return undefined
 }
 
-function commandFromFile(file, text) {
+function commandFromFile(file, text, options = {}) {
   const parsed = parseFrontmatter(text)
   if (!parsed.body) return null
 
@@ -127,7 +128,9 @@ function commandFromFile(file, text) {
     ),
     body: parsed.body,
     filePath: file,
-    relativePath: path.relative(path.dirname(path.dirname(file)), file).replace(/\\/g, '/'),
+    relativePath: options.relativePath || path.relative(path.dirname(path.dirname(file)), file).replace(/\\/g, '/'),
+    source: options.source,
+    pluginName: options.pluginName,
   }
 }
 
@@ -159,7 +162,7 @@ export function textFromUserMessage(message) {
     .join('\n')
 }
 
-async function listCommandsFromDirectory(dir) {
+async function listCommandsFromDirectory(dir, options = {}) {
   let entries
   try {
     entries = await fs.readdir(dir, { withFileTypes: true })
@@ -173,7 +176,14 @@ async function listCommandsFromDirectory(dir) {
     if (!entry.isFile() || !entry.name.toLowerCase().endsWith('.md')) continue
     const file = path.join(dir, entry.name)
     try {
-      const command = commandFromFile(file, await fs.readFile(file, 'utf8'))
+      const relativePath = options.relativeRoot
+        ? `${options.relativeRoot}/${entry.name}`.replace(/\\/g, '/')
+        : undefined
+      const command = commandFromFile(file, await fs.readFile(file, 'utf8'), {
+        source: options.source,
+        pluginName: options.pluginName,
+        relativePath,
+      })
       if (command) commands.push(command)
     } catch (error) {
       console.warn(`Failed to load custom command ${file}:`, error.message || error)
@@ -183,9 +193,49 @@ async function listCommandsFromDirectory(dir) {
   return commands
 }
 
+async function listCommandsFromFile(file, options = {}) {
+  if (!file.toLowerCase().endsWith('.md')) return []
+  try {
+    const command = commandFromFile(file, await fs.readFile(file, 'utf8'), options)
+    return command ? [command] : []
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR' || error?.code === 'EACCES' || error?.code === 'EPERM') return []
+    console.warn(`Failed to load custom command ${file}:`, error.message || error)
+    return []
+  }
+}
+
+async function listCommandsFromPluginSource(source) {
+  const stat = await fs.stat(source.path).catch(() => null)
+  if (!stat) return []
+  const options = {
+    source: source.source,
+    pluginName: source.pluginName,
+    relativePath: source.relativePath,
+    relativeRoot: source.relativePath,
+  }
+  if (stat.isFile()) return listCommandsFromFile(source.path, options)
+  if (stat.isDirectory()) return listCommandsFromDirectory(source.path, options)
+  return []
+}
+
+async function listPluginCommands(workspaceRoot) {
+  if (!workspaceRoot) return []
+  const sources = await getEnabledPluginCommandSources({ workspaceRoot })
+  const commands = []
+  for (const source of sources) {
+    commands.push(...await listCommandsFromPluginSource(source))
+  }
+  return commands
+}
+
 export async function listProjectCommands(workspaceRoot, commandDir) {
   const byName = new Map()
 
+  for (const command of (await listPluginCommands(workspaceRoot)).sort((a, b) => a.name.localeCompare(b.name))) {
+    byName.set(command.name, command)
+  }
+
   for (const dir of commandDirectories(workspaceRoot, commandDir)) {
     const commands = await listCommandsFromDirectory(dir)
     for (const command of commands.sort((a, b) => a.name.localeCompare(b.name))) {
@@ -254,6 +304,9 @@ export function parseInternalCommandInvocation(message) {
   const planMatch = text.match(/^\/plan(?:\s+([\s\S]*))?$/i)
   if (planMatch) return { type: 'plan', args: (planMatch[1] || '').trim() }
 
+  const reviewMatch = text.match(/^\/review(?:\s+([\s\S]*))?$/i)
+  if (reviewMatch) return { type: 'review', args: (reviewMatch[1] || '').trim() }
+
   const compactMatch = text.match(/^\/compact(?:\s+([\s\S]*))?$/i)
   if (compactMatch) return { type: 'compact', args: (compactMatch[1] || '').trim() }
 
@@ -278,6 +331,11 @@ export async function handleInternalCommand(invocation, workspaceRoot, commandDi
     return { plan: true, args: invocation.args }
   }
 
+  if (invocation.type === 'review') {
+    if (!workspaceRoot) return 'Review requires an active project chat.'
+    return { review: true, args: invocation.args || '' }
+  }
+
   if (invocation.type === 'clear') {
     return { clear: true }
   }
@@ -319,7 +377,7 @@ function formatCommandList(commands) {
       '/command new review',
       '```',
       '',
-      'Or add Markdown files under `.ai/commands/`, for example `.ai/commands/review.md`.',
+      'Or add Markdown files under `.claude/commands/`, `.opencode/commands/`, or `.ai/commands/`, for example `.ai/commands/review.md`.',
     ].join('\n')
   }
 
@@ -335,7 +393,7 @@ function formatCommandList(commands) {
     '',
     ...rows,
     '',
-    'Command files live in `.ai/commands/*.md`. Use `$ARGUMENTS` inside a command file to insert invocation arguments.',
+    'Command files live in `.claude/commands/*.md`, `.opencode/commands/*.md`, `.ai/commands/*.md`, or configured directories. Use `$ARGUMENTS` inside a command file to insert invocation arguments.',
   ].join('\n')
 }
 

package/server/index.mjs

@@ -24,6 +24,7 @@ import { handleSharesApi } from './routes/shares.mjs'
 import { handleSharedConversationApi } from './routes/shared-conversation.mjs'
 import { handleLanAccessApi, renderLanUnlockPage } from './routes/lan-access.mjs'
 import { handleMcpApi } from './routes/mcp.mjs'
+import { handlePluginsApi } from './routes/plugins.mjs'
 import { handleWorkspaceApi, handleGitApi } from './routes/workspace.mjs'
 import { handleTerminalApi, handleTerminalUpgrade } from './routes/terminal.mjs'
 import { serveStatic } from './routes/static.mjs'
@@ -227,6 +228,12 @@ async function handleApi(req, res, url) {
     return
   }
 
+  // Plugins
+  if (pathname === '/api/plugins' || pathname.startsWith('/api/plugins/')) {
+    await handlePluginsApi(req, res, url)
+    return
+  }
+
   // Project routes
   if (pathname === '/api/project' || pathname.startsWith('/api/project/')) {
     await handleProjectApi(req, res, url)

package/server/message-converters.mjs

@@ -0,0 +1,79 @@
+/**
+ * LLM message format converters.
+ *
+ * Pure functions that transform AgentMessage[] to LLM-compatible Message[]
+ * and extract text content from messages. No module-level state.
+ */
+
+/**
+ * Strip the `details` property from a message object.
+ * Returns a shallow copy so the original message is not mutated.
+ */
+export function omitDetailsForLlm(message) {
+  if (!message || typeof message !== 'object' || message.details === undefined) return message
+  const copy = { ...message }
+  delete copy.details
+  return copy
+}
+
+/**
+ * Convert AgentMessage[] to LLM-compatible Message[].
+ * Handles "user-with-attachments" → "user" with multi-modal content blocks.
+ * Without this the default pi-agent-core convertToLlm silently drops
+ * user-with-attachments messages, so the LLM never sees attachments.
+ */
+export function serverConvertToLlm(messages) {
+  return messages
+    .filter(m => m.role !== 'artifact')
+    .map(m => {
+      if (m.role === 'user-with-attachments') {
+        const textContent = typeof m.content === 'string'
+          ? [{ type: 'text', text: m.content }]
+          : [...m.content]
+        if (Array.isArray(m.attachments)) {
+          for (const att of m.attachments) {
+            if (att.type === 'image' && att.content) {
+              textContent.push({ type: 'image', data: att.content, mimeType: att.mimeType })
+            } else if (att.type === 'document' && att.extractedText) {
+              textContent.push({ type: 'text', text: `\n\n[Document: ${att.fileName}]\n${att.extractedText}` })
+            }
+          }
+        }
+        return omitDetailsForLlm({ ...m, role: 'user', content: textContent })
+      }
+      if (m.role === 'user' || m.role === 'assistant' || m.role === 'toolResult') return omitDetailsForLlm(m)
+      return null
+    })
+    .filter(Boolean)
+}
+
+/**
+ * Extract plain text content from a message object.
+ * Handles string content and ContentBlock[] arrays.
+ */
+export function messageText(message) {
+  const content = message?.content
+  if (typeof content === 'string') return content
+  if (Array.isArray(content)) {
+    return content
+      .filter((block) => block?.type === 'text')
+      .map((block) => block.text ?? '')
+      .join('\n')
+      .trim()
+  }
+  return ''
+}
+
+/**
+ * Find the last assistant message with non-empty text content.
+ * Returns the text string, or '' if no assistant text is found.
+ */
+export function lastAssistantText(messages) {
+  for (let index = messages.length - 1; index >= 0; index--) {
+    const message = messages[index]
+    if (message?.role !== 'assistant') continue
+    const text = messageText(message)
+    if (text) return text
+  }
+  return ''
+}

package/server/plugins/loader.mjs

@@ -0,0 +1,56 @@
+import { pathToFileURL } from 'node:url'
+
+function isPlainObject(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value))
+}
+
+function contentToText(result) {
+  if (typeof result === 'string') return result
+  if (Array.isArray(result?.content)) {
+    return result.content.map((item) => {
+      if (typeof item === 'string') return item
+      if (item?.type === 'text') return item.text || ''
+      return JSON.stringify(item)
+    }).join('\n')
+  }
+  if (Object.prototype.hasOwnProperty.call(result || {}, 'content')) return String(result.content ?? '')
+  return JSON.stringify(result ?? null, null, 2)
+}
+
+export async function loadPlugin(manifest, context = {}) {
+  const mainPath = new URL(manifest.main, pathToFileURL(`${manifest.dir}/`))
+  const moduleUrl = `${mainPath.href}?quickforgePluginReload=${Date.now()}`
+  const module = await import(moduleUrl)
+  const factory = module.createPlugin || module.default
+  if (typeof factory !== 'function') {
+    throw new Error(`Plugin ${manifest.name} must export createPlugin(context) or a default factory function.`)
+  }
+
+  const plugin = await factory({
+    ...context,
+    plugin: {
+      name: manifest.name,
+      displayName: manifest.displayName,
+      version: manifest.version,
+      dir: manifest.dir,
+    },
+  })
+
+  if (!isPlainObject(plugin)) {
+    throw new Error(`Plugin ${manifest.name} factory must return an object.`)
+  }
+
+  const tools = isPlainObject(plugin.tools) ? plugin.tools : {}
+  return {
+    async callTool(toolName, params = {}, toolContext = {}) {
+      const handler = tools[toolName]
+      if (typeof handler !== 'function') throw new Error(`Plugin ${manifest.name} did not provide handler for tool ${toolName}.`)
+      const result = await handler(params || {}, toolContext)
+      return {
+        content: contentToText(result),
+        details: isPlainObject(result?.details) ? result.details : undefined,
+        isError: Boolean(result?.isError),
+      }
+    },
+  }
+}

package/server/plugins/manifest.mjs

@@ -0,0 +1,174 @@
+import path from 'node:path'
+
+export const PLUGIN_API_VERSION = 1
+
+const pluginNamePattern = /^[a-z0-9][a-z0-9_-]{0,63}$/
+const toolNamePattern = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/
+
+function isPlainObject(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value))
+}
+
+function asString(value, fallback = '') {
+  return typeof value === 'string' ? value.trim() : fallback
+}
+
+function normalizeStringArray(value) {
+  if (!Array.isArray(value)) return []
+  const result = []
+  const seen = new Set()
+  for (const item of value) {
+    const text = asString(item)
+    if (!text || seen.has(text)) continue
+    seen.add(text)
+    result.push(text)
+  }
+  return result
+}
+
+function addPermission(result, seen, value) {
+  const text = asString(value)
+  if (!text || seen.has(text)) return
+  seen.add(text)
+  result.push(text)
+}
+
+function normalizePermissions(value) {
+  if (Array.isArray(value)) return normalizeStringArray(value)
+  if (!isPlainObject(value)) return []
+
+  const result = []
+  const seen = new Set()
+  for (const [key, item] of Object.entries(value)) {
+    if (!key) continue
+    if (Array.isArray(item)) {
+      for (const permission of item) addPermission(result, seen, `${key}:${permission}`)
+    } else if (isPlainObject(item)) {
+      addPermission(result, seen, `${key}:${JSON.stringify(item)}`)
+    } else {
+      addPermission(result, seen, `${key}:${item}`)
+    }
+  }
+  return result
+}
+
+function normalizeSchema(value) {
+  return isPlainObject(value) ? value : { type: 'object', properties: {} }
+}
+
+function isPathInside(root, target) {
+  const relative = path.relative(root, target)
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))
+}
+
+function normalizeRelativePath(value, fieldName, pluginName, pluginDir) {
+  const rawPath = asString(value).replace(/\\/g, '/')
+  if (!rawPath) throw new Error(`Plugin ${pluginName} ${fieldName} contribution path is required.`)
+  if (rawPath.includes('\0')) throw new Error(`Plugin ${pluginName} ${fieldName} contribution path contains invalid characters.`)
+  if (path.isAbsolute(rawPath)) throw new Error(`Plugin ${pluginName} ${fieldName} contribution path must be relative: ${rawPath}`)
+
+  const resolvedPath = path.resolve(pluginDir, rawPath)
+  if (!isPathInside(pluginDir, resolvedPath)) {
+    throw new Error(`Plugin ${pluginName} ${fieldName} contribution path is outside the plugin directory: ${rawPath}`)
+  }
+
+  return {
+    path: rawPath.replace(/^\.\//, ''),
+    resolvedPath,
+  }
+}
+
+function normalizePathContributions(value, fieldName, pluginName, pluginDir) {
+  const entries = typeof value === 'string' ? [value] : Array.isArray(value) ? value : isPlainObject(value) ? [value] : []
+  const result = []
+  const seen = new Set()
+
+  for (const entry of entries) {
+    const rawPath = typeof entry === 'string'
+      ? entry
+      : isPlainObject(entry)
+        ? entry.path || entry.dir || entry.file
+        : ''
+    const normalized = normalizeRelativePath(rawPath, fieldName, pluginName, pluginDir)
+    const key = normalized.path.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    result.push(normalized)
+  }
+
+  return result
+}
+
+function normalizeTool(tool, pluginName) {
+  if (!isPlainObject(tool)) throw new Error(`Plugin ${pluginName} tool entry must be an object.`)
+  const name = asString(tool.name)
+  if (!toolNamePattern.test(name)) {
+    throw new Error(`Plugin ${pluginName} has invalid tool name: ${name || '(empty)'}. Use letters, numbers, underscore, or hyphen.`)
+  }
+  return {
+    name,
+    label: asString(tool.label || tool.title, name),
+    description: asString(tool.description, name),
+    parameters: normalizeSchema(tool.parameters || tool.inputSchema),
+    executionMode: asString(tool.executionMode) || undefined,
+  }
+}
+
+export function quickForgePluginToolName(pluginName, toolName) {
+  return `plugin__${pluginName}__${toolName.replace(/[^A-Za-z0-9_-]/g, '_')}`
+}
+
+export function parseQuickForgePluginToolName(value) {
+  const name = String(value || '')
+  if (!name.startsWith('plugin__')) return null
+  const rest = name.slice('plugin__'.length)
+  const index = rest.indexOf('__')
+  if (index <= 0 || index >= rest.length - 2) return null
+  return {
+    pluginName: rest.slice(0, index),
+    toolName: rest.slice(index + 2),
+  }
+}
+
+export function isPluginToolName(name) {
+  return Boolean(parseQuickForgePluginToolName(name))
+}
+
+export function normalizePluginManifest(raw, pluginDir) {
+  if (!isPlainObject(raw)) throw new Error('plugin.json must contain an object.')
+
+  const name = asString(raw.name)
+  if (!pluginNamePattern.test(name)) {
+    throw new Error(`Invalid plugin name: ${name || '(empty)'}. Use lowercase letters, numbers, underscore, or hyphen.`)
+  }
+
+  const apiVersion = Number(raw.apiVersion || PLUGIN_API_VERSION)
+  if (apiVersion !== PLUGIN_API_VERSION) {
+    throw new Error(`Unsupported plugin apiVersion ${apiVersion}. Current QuickForge plugin API is ${PLUGIN_API_VERSION}.`)
+  }
+
+  const contributes = isPlainObject(raw.contributes) ? raw.contributes : {}
+  const tools = Array.isArray(contributes.tools)
+    ? contributes.tools.map((tool) => normalizeTool(tool, name))
+    : []
+
+  return {
+    name,
+    displayName: asString(raw.displayName || raw.title, name),
+    version: asString(raw.version, '0.0.0'),
+    description: asString(raw.description),
+    apiVersion,
+    quickforgeVersion: asString(raw.quickforgeVersion),
+    enabledByDefault: raw.enabledByDefault === true,
+    main: asString(raw.main, 'index.mjs'),
+    permissions: normalizePermissions(raw.permissions),
+    contributes: {
+      tools,
+      skills: normalizePathContributions(contributes.skills, 'skills', name, pluginDir),
+      commands: normalizePathContributions(contributes.commands, 'commands', name, pluginDir),
+      settings: isPlainObject(contributes.settings) ? contributes.settings : null,
+    },
+    dir: pluginDir,
+    manifestPath: path.join(pluginDir, 'plugin.json'),
+  }
+}