@shawnstack/quickforge 1.7.7 → 1.7.8

package/server/routes/storage.mjs

@@ -1,12 +1,82 @@
 import { sendJson, readJsonBody, decodeSegment } from '../utils/response.mjs'
-import { readStore, writeStore, atomicUpdate, getComparable, getStoreRevision, readSessionStoreScoped, readSessionValue, writeSessionValue, deleteSessionValue, ensureStorage, dataDir, configDir, storageDir, cacheDir, logsDir } from '../storage.mjs'
+import { readStore, writeStore, atomicUpdate, getComparable, getStoreRevision, readSessionStoreScoped, readSessionValue, writeSessionValueWithMetadata, deleteSessionWithMetadata, applySessionBatch, ensureStorage, dataDir, configDir, storageDir, cacheDir, logsDir } from '../storage.mjs'
 import { AUTO_ARCHIVE_SETTINGS_KEY, archiveInactiveSessions, normalizeAutoArchiveSettings } from '../auto-archive.mjs'
 import { directorySize } from '../utils/workspace.mjs'
 import { isAuthenticatedAppClient } from '../access-policy.mjs'
+import { getSessionIndexDiagnostics, markSessionIndexQueryFailure, querySessionIndexPage } from '../session-index-service.mjs'
+import { isSessionStateMaintenanceActive } from '../session-state-cutover.mjs'
 
 const metadataIndexCache = new Map()
 const MAX_METADATA_INDEX_CACHE_ENTRIES = 50
 const METADATA_INDEX_CACHE_TTL_MS = 1000
+const SESSION_QUERY_INDEXES = new Set(['createdAt', 'lastModified', 'pinnedAt'])
+const shadowGenerationByShape = new Map()
+let shadowSampler = () => Math.random() < 0.01
+
+export function configureSessionIndexQueryShadow({ sample } = {}) {
+  if (sample !== undefined && typeof sample !== 'function') throw new TypeError('sample must be a function')
+  shadowSampler = sample ?? (() => Math.random() < 0.01)
+  shadowGenerationByShape.clear()
+}
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return value.map(canonicalJson)
+  if (!value || typeof value !== 'object') return value
+  return Object.fromEntries(Object.keys(value).sort().filter((key) => value[key] !== undefined).map((key) => [key, canonicalJson(value[key])]))
+}
+
+function sameShadowPage(sqlPage, jsonValues, limit, offset) {
+  const expected = jsonValues.slice(offset, offset + limit)
+  if (sqlPage.total !== jsonValues.length || sqlPage.values.length !== expected.length) return false
+  return JSON.stringify(sqlPage.values.map(canonicalJson)) === JSON.stringify(expected.map(canonicalJson))
+}
+
+function parseSqlPagination(limitParam, offsetParam) {
+  if (!limitParam || !/^[1-9]\d*$/.test(limitParam)) return null
+  if (offsetParam !== null && !/^(?:0|[1-9]\d*)$/.test(offsetParam)) return null
+  const limit = Number(limitParam)
+  const offset = offsetParam === null ? 0 : Number(offsetParam)
+  if (!Number.isSafeInteger(limit) || !Number.isSafeInteger(offset)) return null
+  return { limit, offset }
+}
+
+function sqlSessionQueryOptions({ store, indexName, directionParam, scope, projectId, archived, pinned, limitParam, offsetParam }) {
+  if (store !== 'sessions-metadata' || !SESSION_QUERY_INDEXES.has(indexName)) return null
+  if (directionParam !== null && directionParam !== 'asc' && directionParam !== 'desc') return null
+  if (archived !== null && archived !== 'only' && archived !== 'include') return null
+  if (pinned !== null && pinned !== 'only') return null
+  const pagination = parseSqlPagination(limitParam, offsetParam)
+  if (!pagination) return null
+
+  let scopeMode = 'all'
+  if (scope === 'global' && !projectId) scopeMode = 'global'
+  else if (scope === 'project' && typeof projectId === 'string' && projectId.length > 0) scopeMode = 'project'
+  else if ((scope === 'projects' || scope === 'project-all') && !projectId) scopeMode = 'projects'
+  else if (scope !== null || projectId !== null) return null
+
+  return {
+    ...pagination,
+    scopeMode,
+    projectId: scopeMode === 'project' ? projectId : null,
+    archive: archived === 'only' ? 'only' : archived === 'include' ? 'include' : 'exclude',
+    pinnedOnly: pinned === 'only',
+    sort: indexName,
+    direction: directionParam === 'desc' ? 'desc' : 'asc',
+  }
+}
+
+function shadowShape(options) {
+  return JSON.stringify({
+    scopeMode: options.scopeMode,
+    hasProjectId: options.scopeMode === 'project',
+    archive: options.archive,
+    pinnedOnly: options.pinnedOnly,
+    sort: options.sort,
+    direction: options.direction,
+    limit: options.limit,
+    offset: options.offset,
+  })
+}
 
 function metadataIndexCacheKey({ scope, projectId, indexName, direction, archived, pinned }) {
   return JSON.stringify({ scope: scope || '', projectId: projectId || '', indexName, direction, archived: archived || '', pinned: pinned || '' })
@@ -125,6 +195,41 @@ export async function handleStorageApi(req, res, url, context = { isLocalRequest
 
   const store = decodeSegment(parts[2])
 
+  // Session batch transaction endpoint: one request commits a set/delete mix
+  // across `sessions` and `sessions-metadata` as a single SQLite transaction
+  // (authoritative). expectedStateVersion is optional per operation.
+  if (req.method === 'POST' && parts.length === 3 && store === 'batch') {
+    if (isSessionStateMaintenanceActive()) {
+      const error = new Error('Session storage maintenance is in progress')
+      error.statusCode = 423
+      error.errorCode = 'SESSION_STORAGE_MAINTENANCE'
+      throw error
+    }
+    const body = await readJsonBody(req)
+    const operations = body?.operations
+    if (!Array.isArray(operations) || operations.length === 0) {
+      const error = new Error('Session batch operations are required')
+      error.statusCode = 400
+      throw error
+    }
+    try {
+      const result = await applySessionBatch(operations)
+      sendJson(res, 200, { ok: true, saved: result?.saved ?? 0, deleted: result?.deleted ?? 0 })
+    } catch (error) {
+      if (['SESSION_STATE_CONFLICT', 'SESSION_STATE_DUPLICATE_ID', 'SESSION_STATE_REQUIRED', 'SESSION_FULL_DELETE_REQUIRED'].includes(error?.errorCode)) {
+        error.statusCode = 409
+        throw error
+      }
+      if (error instanceof TypeError) {
+        const mapped = new Error(error.message)
+        mapped.statusCode = 400
+        throw mapped
+      }
+      throw error
+    }
+    return
+  }
+
   if (req.method === 'GET' && parts[3] === 'keys') {
     const prefix = url.searchParams.get('prefix') || ''
     const data = await readStore(store)
@@ -135,7 +240,8 @@ export async function handleStorageApi(req, res, url, context = { isLocalRequest
 
   if (req.method === 'GET' && parts[3] === 'index') {
     const indexName = decodeSegment(parts[4])
-    const direction = url.searchParams.get('direction') === 'desc' ? 'desc' : 'asc'
+    const directionParam = url.searchParams.get('direction')
+    const direction = directionParam === 'desc' ? 'desc' : 'asc'
     const scope = url.searchParams.get('scope')
     const projectId = url.searchParams.get('projectId')
     const limitParam = url.searchParams.get('limit')
@@ -145,6 +251,32 @@ export async function handleStorageApi(req, res, url, context = { isLocalRequest
 
     await ensureStorage()
 
+    const sqlOptions = sqlSessionQueryOptions({
+      store, indexName, directionParam, scope, projectId, archived, pinned, limitParam, offsetParam,
+    })
+    if (sqlOptions) {
+      const sqlResult = await querySessionIndexPage(sqlOptions)
+      if (sqlResult.ok) {
+        const diagnostics = getSessionIndexDiagnostics()
+        const shape = shadowShape(sqlOptions)
+        const lastGeneration = shadowGenerationByShape.get(shape)
+        const forced = lastGeneration !== diagnostics.rebuildGeneration
+        if (!forced && !shadowSampler({ shape, generation: diagnostics.rebuildGeneration })) {
+          sendJson(res, 200, { values: sqlResult.page.values, total: sqlResult.page.total })
+          return
+        }
+        const jsonValues = await readIndexedValues(store, indexName, direction, scope, projectId, archived, pinned)
+        shadowGenerationByShape.set(shape, diagnostics.rebuildGeneration)
+        if (sameShadowPage(sqlResult.page, jsonValues, sqlOptions.limit, sqlOptions.offset)) {
+          sendJson(res, 200, { values: sqlResult.page.values, total: sqlResult.page.total })
+          return
+        }
+        markSessionIndexQueryFailure('shadow_mismatch')
+        sendJson(res, 200, { values: jsonValues.slice(sqlOptions.offset, sqlOptions.offset + sqlOptions.limit), total: jsonValues.length })
+        return
+      }
+    }
+
     const values = await readIndexedValues(store, indexName, direction, scope, projectId, archived, pinned)
 
     const total = values.length
@@ -194,7 +326,9 @@ export async function handleStorageApi(req, res, url, context = { isLocalRequest
     if (req.method === 'PUT') {
       const body = await readJsonBody(req)
       if (store === 'sessions') {
-        await writeSessionValue(key, body?.value)
+        // Single-session PUT writes the body and derives/merges metadata so it
+        // never leaves a body orphaned (one SQLite transaction when authoritative).
+        await writeSessionValueWithMetadata(key, body?.value)
         sendJson(res, 200, { ok: true })
         return
       }
@@ -212,11 +346,7 @@ export async function handleStorageApi(req, res, url, context = { isLocalRequest
 
     if (req.method === 'DELETE') {
       if (store === 'sessions') {
-        await deleteSessionValue(key)
-        await atomicUpdate('sessions-metadata', (data) => {
-          delete data[key]
-          return data
-        })
+        await deleteSessionWithMetadata(key)
         sendJson(res, 200, { ok: true })
         return
       }

package/server/routes/workspace.mjs

@@ -25,6 +25,11 @@ const MAX_GIT_LINE_COUNT_TOTAL_BYTES = 10 * 1024 * 1024
 const GIT_LINE_COUNT_CONCURRENCY = 6
 const PREVIEW_ALLOWED_EXTENSIONS = new Set(['.html', '.htm', '.css', '.js', '.mjs', '.json', '.svg', '.png', '.jpg', '.jpeg', '.webp', '.gif', '.ico', '.txt', '.md'])
 const MAX_TREE_NODES = 50000
+const DEFAULT_CHILDREN_LIMIT = 200
+const MAX_CHILDREN_LIMIT = 500
+const DEFAULT_SEARCH_LIMIT = 100
+const MAX_SEARCH_LIMIT = 200
+const MAX_SEARCH_VISITED_ENTRIES = 50000
 const SKIP_DIRS = new Set(['.git', 'node_modules'])
 
 const extensionLanguageMap = new Map([
@@ -701,7 +706,9 @@ async function readGitFile(workspaceRoot, ref, relativePath) {
   return result.code === 0 ? result.stdout.toString('utf8') : ''
 }
 
-async function readWorkspaceTextFile(context, relativePath) {
+// 安全校验 + stat（不读内容）：普通读取与 meta 轻量探测共用，保证两条路径
+// 的 400/413/ENOENT 错误语义完全一致。
+async function statWorkspaceTextFile(context, relativePath) {
   const file = resolveWorkspacePath(relativePath, context)
   await assertSafeWorkspacePath(file, context, { allowSensitive: true })
   const stat = await fs.stat(file)
@@ -715,8 +722,13 @@ async function readWorkspaceTextFile(context, relativePath) {
     error.statusCode = 413
     throw error
   }
-  const buffer = await fs.readFile(file)
-  return { content: buffer.toString('utf8'), size: stat.size, path: toWorkspaceRelative(file, context) }
+  return { file, size: stat.size, mtimeMs: stat.mtimeMs, path: toWorkspaceRelative(file, context) }
+}
+
+async function readWorkspaceTextFile(context, relativePath) {
+  const info = await statWorkspaceTextFile(context, relativePath)
+  const buffer = await fs.readFile(info.file)
+  return { content: buffer.toString('utf8'), size: info.size, mtimeMs: info.mtimeMs, path: info.path }
 }
 
 async function buildTreeForDirectory(dir, context, counter, validateWorkspacePath) {
@@ -765,6 +777,202 @@ async function handleWorkspaceTree(req, res, url) {
   sendJson(res, 200, { root: context.project.name, tree })
 }
 
+function parseBoundedLimit(rawValue, defaultValue, maxValue) {
+  if (rawValue === null || rawValue === '') return defaultValue
+  const value = Number(rawValue)
+  if (!Number.isInteger(value) || value < 1) {
+    const error = new Error('limit must be a positive integer')
+    error.statusCode = 400
+    throw error
+  }
+  return Math.min(value, maxValue)
+}
+
+function encodeWorkspaceCursor(offset) {
+  return Buffer.from(String(offset), 'utf8').toString('base64url')
+}
+
+function decodeWorkspaceCursor(rawCursor) {
+  if (!rawCursor) return 0
+  let decoded
+  try {
+    decoded = Buffer.from(rawCursor, 'base64url').toString('utf8')
+  } catch {
+    const error = new Error('cursor is invalid')
+    error.statusCode = 400
+    throw error
+  }
+  if (!/^\d+$/.test(decoded)) {
+    const error = new Error('cursor is invalid')
+    error.statusCode = 400
+    throw error
+  }
+  const value = Number(decoded)
+  if (!Number.isSafeInteger(value) || value < 0) {
+    const error = new Error('cursor is invalid')
+    error.statusCode = 400
+    throw error
+  }
+  return value
+}
+
+export function compareWorkspaceEntries(left, right) {
+  if (left.type !== right.type) return left.type === 'directory' ? -1 : 1
+  return left.name.localeCompare(right.name, undefined, { sensitivity: 'base' })
+    || left.name.localeCompare(right.name, undefined, { sensitivity: 'variant' })
+    || (left.path < right.path ? -1 : left.path > right.path ? 1 : 0)
+}
+
+async function workspaceEntryFromDirent(dir, entry, context, validateWorkspacePath) {
+  if (entry.isDirectory() && SKIP_DIRS.has(entry.name)) return null
+  const fullPath = path.join(dir, entry.name)
+  const relativePath = toWorkspaceRelative(fullPath, context)
+  if (entry.isDirectory()) return { name: entry.name, path: relativePath, type: 'directory' }
+  if (entry.isFile()) return { name: entry.name, path: relativePath, type: 'file' }
+  if (!entry.isSymbolicLink()) return null
+
+  try {
+    await validateWorkspacePath(fullPath, { allowSensitive: true })
+    const stat = await fs.stat(fullPath)
+    if (stat.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) return null
+      return { name: entry.name, path: relativePath, type: 'directory' }
+    }
+    if (stat.isFile()) return { name: entry.name, path: relativePath, type: 'file' }
+  } catch {
+    // External, broken, or inaccessible symbolic links are omitted.
+  }
+  return null
+}
+
+async function readWorkspaceDirectory(context, relativePath) {
+  const requestedPath = relativePath?.trim() || '.'
+  const directory = resolveWorkspacePath(requestedPath, context)
+  const validateWorkspacePath = await createWorkspacePathValidator(context)
+  await validateWorkspacePath(directory, { allowSensitive: true })
+  const stat = await fs.stat(directory)
+  if (!stat.isDirectory()) {
+    const error = new Error('Path is not a directory')
+    error.statusCode = 400
+    throw error
+  }
+  return { directory, requestedPath: toWorkspaceRelative(directory, context), validateWorkspacePath }
+}
+
+export async function listWorkspaceChildren(context, relativePath = '.', options = {}) {
+  const limit = parseBoundedLimit(options.limit ?? null, DEFAULT_CHILDREN_LIMIT, MAX_CHILDREN_LIMIT)
+  const offset = decodeWorkspaceCursor(options.cursor || '')
+  const { directory, requestedPath, validateWorkspacePath } = await readWorkspaceDirectory(context, relativePath)
+  const dirents = await fs.readdir(directory, { withFileTypes: true })
+  const entries = []
+  for (const dirent of dirents) {
+    const entry = await workspaceEntryFromDirent(directory, dirent, context, validateWorkspacePath)
+    if (entry) entries.push(entry)
+  }
+  entries.sort(compareWorkspaceEntries)
+  if (offset > entries.length) {
+    const error = new Error('cursor is out of range')
+    error.statusCode = 400
+    throw error
+  }
+  const page = entries.slice(offset, offset + limit)
+  const nextOffset = offset + page.length
+  return {
+    root: context.project.name,
+    path: requestedPath,
+    entries: page,
+    nextCursor: nextOffset < entries.length ? encodeWorkspaceCursor(nextOffset) : null,
+    truncated: nextOffset < entries.length,
+  }
+}
+
+async function handleWorkspaceChildren(req, res, url) {
+  const context = await projectContextFromUrl(url)
+  sendJson(res, 200, await listWorkspaceChildren(context, url.searchParams.get('path') || '.', {
+    limit: url.searchParams.get('limit'),
+    cursor: url.searchParams.get('cursor') || '',
+  }))
+}
+
+export async function readValidatedWorkspaceSearchDirectory(directory, validateWorkspacePath, visitedDirectories, io = {}) {
+  const realpath = io.realpath || fs.realpath
+  const readdir = io.readdir || fs.readdir
+  await validateWorkspacePath(directory, { allowSensitive: true })
+  const directoryReal = await realpath(directory)
+  const directoryKey = process.platform === 'win32' ? directoryReal.toLocaleLowerCase() : directoryReal
+  if (visitedDirectories.has(directoryKey)) return null
+  visitedDirectories.add(directoryKey)
+  const dirents = await readdir(directory, { withFileTypes: true })
+  return { directoryReal, dirents }
+}
+
+export async function searchWorkspace(context, rawQuery, options = {}) {
+  const query = typeof rawQuery === 'string' ? rawQuery.trim() : ''
+  if (query.length < 2) {
+    const error = new Error('query must contain at least 2 characters')
+    error.statusCode = 400
+    throw error
+  }
+  const limit = parseBoundedLimit(options.limit ?? null, DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT)
+  const validateWorkspacePath = await createWorkspacePathValidator(context)
+  await validateWorkspacePath(context.workspaceRoot, { allowSensitive: true })
+  const normalizedQuery = query.toLocaleLowerCase()
+  const results = []
+  const pending = [context.workspaceRoot]
+  const visitedDirectories = new Set()
+  let visited = 0
+  let traversalTruncated = false
+  let hasAdditionalMatch = false
+
+  while (pending.length > 0 && !traversalTruncated && !hasAdditionalMatch) {
+    const directory = pending.pop()
+    let validated
+    try {
+      validated = await readValidatedWorkspaceSearchDirectory(directory, validateWorkspacePath, visitedDirectories)
+    } catch {
+      continue
+    }
+    if (!validated) continue
+    const { dirents } = validated
+    dirents.sort((left, right) => left.name.localeCompare(right.name, undefined, { sensitivity: 'base' })
+      || left.name.localeCompare(right.name, undefined, { sensitivity: 'variant' })
+      || (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))
+    const childDirectories = []
+    for (const dirent of dirents) {
+      if (visited >= MAX_SEARCH_VISITED_ENTRIES) {
+        traversalTruncated = true
+        break
+      }
+      visited += 1
+      const entry = await workspaceEntryFromDirent(directory, dirent, context, validateWorkspacePath)
+      if (!entry) continue
+      if (entry.path.toLocaleLowerCase().includes(normalizedQuery) || entry.name.toLocaleLowerCase().includes(normalizedQuery)) {
+        results.push(entry)
+        if (results.length > limit) {
+          hasAdditionalMatch = true
+          break
+        }
+      }
+      if (entry.type === 'directory') childDirectories.push(path.join(directory, dirent.name))
+    }
+    for (let index = childDirectories.length - 1; index >= 0; index -= 1) pending.push(childDirectories[index])
+  }
+
+  results.sort(compareWorkspaceEntries)
+  return {
+    root: context.project.name,
+    query,
+    entries: results.slice(0, limit),
+    truncated: traversalTruncated || hasAdditionalMatch,
+  }}
+
+async function handleWorkspaceSearch(req, res, url) {
+  const context = await projectContextFromUrl(url)
+  sendJson(res, 200, await searchWorkspace(context, url.searchParams.get('query') || '', {
+    limit: url.searchParams.get('limit'),
+  }))
+}
+
 async function handleWorkspaceFile(req, res, url) {
   const context = await projectContextFromUrl(url)
   const relativePath = url.searchParams.get('path') || ''
@@ -773,6 +981,19 @@ async function handleWorkspaceFile(req, res, url) {
     error.statusCode = 400
     throw error
   }
+  // meta=1：轻量元信息探测（与 preview 路由的 `__quickforge_check=1` 探测风格一致）。
+  // 走同一安全校验与 stat，但绝不读取文件内容，供客户端校验本地文件缓存快照。
+  if (url.searchParams.get('meta') === '1') {
+    const info = await statWorkspaceTextFile(context, relativePath)
+    sendJson(res, 200, {
+      path: info.path,
+      size: info.size,
+      mtimeMs: info.mtimeMs,
+      language: languageFromPath(info.path),
+      readonly: true,
+    })
+    return
+  }
   const file = await readWorkspaceTextFile(context, relativePath)
   sendJson(res, 200, {
     ...file,
@@ -840,6 +1061,21 @@ export async function inspectWorkspacePreviewFile(context, relativePath) {
   }
 }
 
+// ETag 源=stat（零额外 IO）：mtimeMs+size 足以标识本地文件版本
+export function buildPreviewEtag(stat) {
+  return `"${stat.mtimeMs}-${stat.size}"`
+}
+
+// If-None-Match 支持精确值、`*` 与逗号分隔列表（每项 trim 后比较）
+function ifNoneMatchSatisfied(headerValue, etag) {
+  return String(headerValue)
+    .split(',')
+    .some((candidate) => {
+      const value = candidate.trim()
+      return value === etag || value === '*'
+    })
+}
+
 async function handleWorkspacePreview(req, res, url) {
   let relativePath = ''
   try {
@@ -858,19 +1094,36 @@ async function handleWorkspacePreview(req, res, url) {
 
     const context = await projectContextFromId(projectId)
     const preview = await inspectWorkspacePreviewFile(context, relativePath)
+    const etag = buildPreviewEtag(preview.stat)
     if (url.searchParams.get('__quickforge_check') === '1') {
       sendJson(res, 200, {
         ok: true,
         path: relativePath,
         size: preview.stat.size,
+        mtimeMs: preview.stat.mtimeMs,
         contentType: preview.contentType,
       })
       return
     }
 
+    const ifNoneMatch = req.headers?.['if-none-match']
+    if (typeof ifNoneMatch === 'string' && ifNoneMatchSatisfied(ifNoneMatch, etag)) {
+      // 304=未变化零传输：命中协商缓存，不读文件体直接结束
+      res.writeHead(304, {
+        etag,
+        'cache-control': 'private, no-cache',
+        'x-content-type-options': 'nosniff',
+      })
+      res.end()
+      return
+    }
+
+    // no-cache=每次协商：浏览器每次回源校验，文件变化立即生效
     res.writeHead(200, {
       'content-type': preview.contentType,
-      'cache-control': 'no-store',
+      'content-length': String(preview.stat.size),
+      'cache-control': 'private, no-cache',
+      etag,
       'x-content-type-options': 'nosniff',
     })
     const buffer = await fs.readFile(preview.file)
@@ -1153,6 +1406,14 @@ export async function handleWorkspaceApi(req, res, url, requestContext = {}) {
     await handleWorkspaceTree(req, res, url)
     return
   }
+  if (req.method === 'GET' && url.pathname === '/api/workspace/children') {
+    await handleWorkspaceChildren(req, res, url)
+    return
+  }
+  if (req.method === 'GET' && url.pathname === '/api/workspace/search') {
+    await handleWorkspaceSearch(req, res, url)
+    return
+  }
   if (req.method === 'GET' && url.pathname === '/api/workspace/file') {
     await handleWorkspaceFile(req, res, url)
     return