@sanqianx/project-knowledge 5.0.24 → 5.0.25

package/_site/lib/ai-workspace.js

@@ -1,104 +1,104 @@
-const fs = require('fs');
-const path = require('path');
-const { getDataDir } = require('./data-dir');
-
-const APP_ROOT = getDataDir();
-const SITE_ROOT = path.resolve(__dirname, '..');
-const AI_ROOT = path.join(APP_ROOT, '_ai');
-const STANDARD_SUBDIRS = ['runs', 'context-packs', 'backups', 'claude-workbench'];
-
-function safeSlug(slug) {
-  return typeof slug === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(slug);
-}
-
-function projectAIPath(slug) {
-  if (!safeSlug(slug)) throw new Error(`invalid slug for AI workspace: ${slug}`);
-  return path.join(AI_ROOT, slug);
-}
-
-function ensureProjectAIPath(slug) {
-  const root = projectAIPath(slug);
-  for (const sub of STANDARD_SUBDIRS) {
-    fs.mkdirSync(path.join(root, sub), { recursive: true });
-  }
-  return root;
-}
-
-function legacyAIPath(kbPath) {
-  return path.join(kbPath, '_ai');
-}
-
-function copyDir(src, dest) {
-  fs.mkdirSync(dest, { recursive: true });
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    const from = path.join(src, entry.name);
-    const to = path.join(dest, entry.name);
-    if (entry.isDirectory()) copyDir(from, to);
-    else if (entry.isFile()) fs.copyFileSync(from, to);
-  }
-}
-
-function migrateAIWorkspace({ slug, kbPath, preserveOriginal = true }) {
-  const legacy = legacyAIPath(kbPath);
-  const target = ensureProjectAIPath(slug);
-  const result = {
-    ok: true,
-    slug,
-    legacyPath: legacy,
-    targetPath: target,
-    copied: false,
-    preservedOriginal: preserveOriginal,
-  };
-  if (!fs.existsSync(legacy)) return result;
-  copyDir(legacy, target);
-  result.copied = true;
-  if (!preserveOriginal) {
-    fs.rmSync(legacy, { recursive: true, force: true });
-    result.preservedOriginal = false;
-  }
-  return result;
-}
-
-function runPath(slug, runId) {
-  return path.join(projectAIPath(slug), 'runs', `${runId}.json`);
-}
-
-function contextPackDir(slug, runId) {
-  return path.join(projectAIPath(slug), 'context-packs', runId);
-}
-
-function findExistingRunPath({ slug, kbPath, runId }) {
-  const primary = path.join(projectAIPath(slug), 'runs', `${runId}.json`);
-  return primary;
-}
-
-function listProjectDirs(projectSlug = null, projects = null) {
-  if (projectSlug) return [projectAIPath(projectSlug)];
-  const dirs = [];
-  if (fs.existsSync(AI_ROOT)) {
-    for (const entry of fs.readdirSync(AI_ROOT, { withFileTypes: true })) {
-      if (entry.isDirectory() && safeSlug(entry.name)) dirs.push(path.join(AI_ROOT, entry.name));
-    }
-  }
-  if (projects) {
-    for (const [slug] of Object.entries(projects)) {
-      if (safeSlug(slug)) dirs.push(projectAIPath(slug));
-    }
-  }
-  return [...new Set(dirs.map(d => path.resolve(d)))];
-}
-
-module.exports = {
-  APP_ROOT,
-  SITE_ROOT,
-  AI_ROOT,
-  STANDARD_SUBDIRS,
-  projectAIPath,
-  ensureProjectAIPath,
-  legacyAIPath,
-  migrateAIWorkspace,
-  runPath,
-  contextPackDir,
-  findExistingRunPath,
-  listProjectDirs,
-};
+const fs = require('fs');
+const path = require('path');
+const { getDataDir } = require('./data-dir');
+
+const APP_ROOT = getDataDir();
+const SITE_ROOT = path.resolve(__dirname, '..');
+const AI_ROOT = path.join(APP_ROOT, '_ai');
+const STANDARD_SUBDIRS = ['runs', 'context-packs', 'backups', 'claude-workbench'];
+
+function safeSlug(slug) {
+  return typeof slug === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(slug);
+}
+
+function projectAIPath(slug) {
+  if (!safeSlug(slug)) throw new Error(`invalid slug for AI workspace: ${slug}`);
+  return path.join(AI_ROOT, slug);
+}
+
+function ensureProjectAIPath(slug) {
+  const root = projectAIPath(slug);
+  for (const sub of STANDARD_SUBDIRS) {
+    fs.mkdirSync(path.join(root, sub), { recursive: true });
+  }
+  return root;
+}
+
+function legacyAIPath(kbPath) {
+  return path.join(kbPath, '_ai');
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDir(from, to);
+    else if (entry.isFile()) fs.copyFileSync(from, to);
+  }
+}
+
+function migrateAIWorkspace({ slug, kbPath, preserveOriginal = true }) {
+  const legacy = legacyAIPath(kbPath);
+  const target = ensureProjectAIPath(slug);
+  const result = {
+    ok: true,
+    slug,
+    legacyPath: legacy,
+    targetPath: target,
+    copied: false,
+    preservedOriginal: preserveOriginal,
+  };
+  if (!fs.existsSync(legacy)) return result;
+  copyDir(legacy, target);
+  result.copied = true;
+  if (!preserveOriginal) {
+    fs.rmSync(legacy, { recursive: true, force: true });
+    result.preservedOriginal = false;
+  }
+  return result;
+}
+
+function runPath(slug, runId) {
+  return path.join(projectAIPath(slug), 'runs', `${runId}.json`);
+}
+
+function contextPackDir(slug, runId) {
+  return path.join(projectAIPath(slug), 'context-packs', runId);
+}
+
+function findExistingRunPath({ slug, kbPath, runId }) {
+  const primary = path.join(projectAIPath(slug), 'runs', `${runId}.json`);
+  return primary;
+}
+
+function listProjectDirs(projectSlug = null, projects = null) {
+  if (projectSlug) return [projectAIPath(projectSlug)];
+  const dirs = [];
+  if (fs.existsSync(AI_ROOT)) {
+    for (const entry of fs.readdirSync(AI_ROOT, { withFileTypes: true })) {
+      if (entry.isDirectory() && safeSlug(entry.name)) dirs.push(path.join(AI_ROOT, entry.name));
+    }
+  }
+  if (projects) {
+    for (const [slug] of Object.entries(projects)) {
+      if (safeSlug(slug)) dirs.push(projectAIPath(slug));
+    }
+  }
+  return [...new Set(dirs.map(d => path.resolve(d)))];
+}
+
+module.exports = {
+  APP_ROOT,
+  SITE_ROOT,
+  AI_ROOT,
+  STANDARD_SUBDIRS,
+  projectAIPath,
+  ensureProjectAIPath,
+  legacyAIPath,
+  migrateAIWorkspace,
+  runPath,
+  contextPackDir,
+  findExistingRunPath,
+  listProjectDirs,
+};

package/_site/lib/atomic-file.js

@@ -1,204 +1,204 @@
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-const { DomainError } = require('./contracts');
-
-const DEFAULT_LOCK_TIMEOUT_MS = 10_000;
-const DEFAULT_STALE_LOCK_MS = 120_000;
-
-function delay(ms) {
-  return new Promise(resolve => setTimeout(resolve, ms));
-}
-
-function isProcessAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return error && error.code === 'EPERM';
-  }
-}
-
-function readLockOwner(lockPath) {
-  try { return JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch { return null; }
-}
-
-function canBreakStaleLock(lockPath, staleMs) {
-  let stat;
-  try { stat = fs.statSync(lockPath); } catch { return false; }
-  const owner = readLockOwner(lockPath);
-  // A complete owner record lets us recover immediately after a process
-  // crash. The age threshold is only needed for an incomplete/unreadable
-  // file that another process may still be creating.
-  if (owner && Number.isInteger(Number(owner.pid))) return !isProcessAlive(Number(owner.pid));
-  return (Date.now() - stat.mtimeMs) >= staleMs;
-}
-
-async function acquireFileLock(lockPath, options = {}) {
-  const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : DEFAULT_LOCK_TIMEOUT_MS;
-  const staleMs = Number.isFinite(options.staleMs) ? options.staleMs : DEFAULT_STALE_LOCK_MS;
-  const retryMs = Number.isFinite(options.retryMs) ? options.retryMs : 25;
-  const started = Date.now();
-  const nonce = crypto.randomBytes(12).toString('hex');
-  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-  while (true) {
-    try {
-      const fd = fs.openSync(lockPath, 'wx', 0o600);
-      const owner = { pid: process.pid, startedAt: new Date().toISOString(), nonce };
-      fs.writeFileSync(fd, `${JSON.stringify(owner)}\n`, 'utf8');
-      fs.fsyncSync(fd);
-      fs.closeSync(fd);
-      return async function release() {
-        const current = readLockOwner(lockPath);
-        if (!current || current.nonce !== nonce) return;
-        try { fs.unlinkSync(lockPath); } catch (error) { if (!error || error.code !== 'ENOENT') throw error; }
-      };
-    } catch (error) {
-      if (!error || error.code !== 'EEXIST') throw error;
-      if (canBreakStaleLock(lockPath, staleMs)) {
-        try { fs.unlinkSync(lockPath); continue; } catch (unlinkError) {
-          // A competing process may recover the same stale lock first; retry through the normal wait path.
-        }
-      }
-      if ((Date.now() - started) >= timeoutMs) {
-        throw new DomainError('PROJECT_BUSY', 'Timed out waiting for a file lock.', {
-          status: 409,
-          retryable: true,
-          details: { lockCategory: path.basename(lockPath) },
-        });
-      }
-      await delay(retryMs);
-    }
-  }
-}
-
-async function withFileLock(lockPath, fn, options = {}) {
-  const release = await acquireFileLock(lockPath, options);
-  try { return await fn(); } finally { await release(); }
-}
-
-function syncDirectoryBestEffort(directory) {
-  let fd;
-  try {
-    fd = fs.openSync(directory, 'r');
-    fs.fsyncSync(fd);
-  } catch {
-    // Directory fsync is unsupported on some filesystems; the file replace is already durable.
-  } finally {
-    if (fd != null) try { fs.closeSync(fd); } catch {
-      // Closing a best-effort directory descriptor cannot invalidate the completed file replace.
-    }
-  }
-}
-
-function replaceWithRetry(tempPath, targetPath, options = {}) {
-  const retries = Number.isInteger(options.renameRetries) ? options.renameRetries : 8;
-  const waitBuffer = new Int32Array(new SharedArrayBuffer(4));
-  let lastError;
-  for (let attempt = 0; attempt <= retries; attempt += 1) {
-    try {
-      fs.renameSync(tempPath, targetPath);
-      return;
-    } catch (error) {
-      lastError = error;
-      if (!error || !['EPERM', 'EACCES', 'EBUSY', 'EEXIST'].includes(error.code) || attempt === retries) break;
-      Atomics.wait(waitBuffer, 0, 0, Math.min(250, 10 * (2 ** attempt)));
-    }
-  }
-  throw lastError;
-}
-
-function writeFileAtomic(filePath, content, options = {}) {
-  const directory = path.dirname(filePath);
-  fs.mkdirSync(directory, { recursive: true });
-  const tempPath = path.join(directory, `.${path.basename(filePath)}.${process.pid}.${Date.now()}.${crypto.randomBytes(6).toString('hex')}.tmp`);
-  let fd;
-  try {
-    fd = fs.openSync(tempPath, 'wx', options.mode || 0o600);
-    fs.writeFileSync(fd, content, options.encoding || 'utf8');
-    fs.fsyncSync(fd);
-    fs.closeSync(fd);
-    fd = null;
-    if (typeof options.beforeRename === 'function') options.beforeRename(tempPath, filePath);
-    replaceWithRetry(tempPath, filePath, options);
-    syncDirectoryBestEffort(directory);
-    return { path: filePath };
-  } catch (error) {
-    if (fd != null) try { fs.closeSync(fd); } catch {
-      // Preserve the original write error.
-    }
-    try { if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath); } catch {
-      // Preserve the original write error; stale temp files are never treated as live data.
-    }
-    throw error;
-  }
-}
-
-function writeJsonAtomic(filePath, value, options = {}) {
-  return writeFileAtomic(filePath, `${JSON.stringify(value, null, 2)}\n`, options);
-}
-
-function readJsonStrict(filePath, options = {}) {
-  let raw;
-  try { raw = fs.readFileSync(filePath, 'utf8'); }
-  catch (error) {
-    if (error && error.code === 'ENOENT' && options.allowMissing) return options.defaultValue;
-    throw error;
-  }
-  try {
-    const parsed = JSON.parse(raw);
-    if (typeof options.validate === 'function') options.validate(parsed);
-    return parsed;
-  } catch (error) {
-    if (error instanceof DomainError) throw error;
-    throw new DomainError('DATA_CORRUPT', 'A JSON data file is corrupt.', {
-      status: 500,
-      cause: error,
-      details: { category: options.category || 'json' },
-    });
-  }
-}
-
-async function appendJsonlLocked(filePath, value, options = {}) {
-  const lockPath = options.lockPath || `${filePath}.lock`;
-  return withFileLock(lockPath, async () => {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    const fd = fs.openSync(filePath, 'a', options.mode || 0o600);
-    try {
-      fs.writeFileSync(fd, `${JSON.stringify(value)}\n`, 'utf8');
-      fs.fsyncSync(fd);
-    } finally {
-      fs.closeSync(fd);
-    }
-    return value;
-  }, options);
-}
-
-function cleanupStaleTemps(directory, options = {}) {
-  if (!fs.existsSync(directory)) return [];
-  const olderThanMs = Number.isFinite(options.olderThanMs) ? options.olderThanMs : 24 * 60 * 60 * 1000;
-  const now = Date.now();
-  const removed = [];
-  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
-    if (!entry.isFile() || !/^\..+\.\d+\.\d+\.[a-f0-9]+\.tmp$/i.test(entry.name)) continue;
-    const absolute = path.join(directory, entry.name);
-    const stat = fs.statSync(absolute);
-    if ((now - stat.mtimeMs) < olderThanMs) continue;
-    fs.unlinkSync(absolute);
-    removed.push(absolute);
-  }
-  return removed;
-}
-
-module.exports = {
-  DEFAULT_LOCK_TIMEOUT_MS,
-  DEFAULT_STALE_LOCK_MS,
-  acquireFileLock,
-  withFileLock,
-  writeFileAtomic,
-  writeJsonAtomic,
-  readJsonStrict,
-  appendJsonlLocked,
-  cleanupStaleTemps,
-};
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { DomainError } = require('./contracts');
+
+const DEFAULT_LOCK_TIMEOUT_MS = 10_000;
+const DEFAULT_STALE_LOCK_MS = 120_000;
+
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error && error.code === 'EPERM';
+  }
+}
+
+function readLockOwner(lockPath) {
+  try { return JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch { return null; }
+}
+
+function canBreakStaleLock(lockPath, staleMs) {
+  let stat;
+  try { stat = fs.statSync(lockPath); } catch { return false; }
+  const owner = readLockOwner(lockPath);
+  // A complete owner record lets us recover immediately after a process
+  // crash. The age threshold is only needed for an incomplete/unreadable
+  // file that another process may still be creating.
+  if (owner && Number.isInteger(Number(owner.pid))) return !isProcessAlive(Number(owner.pid));
+  return (Date.now() - stat.mtimeMs) >= staleMs;
+}
+
+async function acquireFileLock(lockPath, options = {}) {
+  const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : DEFAULT_LOCK_TIMEOUT_MS;
+  const staleMs = Number.isFinite(options.staleMs) ? options.staleMs : DEFAULT_STALE_LOCK_MS;
+  const retryMs = Number.isFinite(options.retryMs) ? options.retryMs : 25;
+  const started = Date.now();
+  const nonce = crypto.randomBytes(12).toString('hex');
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  while (true) {
+    try {
+      const fd = fs.openSync(lockPath, 'wx', 0o600);
+      const owner = { pid: process.pid, startedAt: new Date().toISOString(), nonce };
+      fs.writeFileSync(fd, `${JSON.stringify(owner)}\n`, 'utf8');
+      fs.fsyncSync(fd);
+      fs.closeSync(fd);
+      return async function release() {
+        const current = readLockOwner(lockPath);
+        if (!current || current.nonce !== nonce) return;
+        try { fs.unlinkSync(lockPath); } catch (error) { if (!error || error.code !== 'ENOENT') throw error; }
+      };
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') throw error;
+      if (canBreakStaleLock(lockPath, staleMs)) {
+        try { fs.unlinkSync(lockPath); continue; } catch (unlinkError) {
+          // A competing process may recover the same stale lock first; retry through the normal wait path.
+        }
+      }
+      if ((Date.now() - started) >= timeoutMs) {
+        throw new DomainError('PROJECT_BUSY', 'Timed out waiting for a file lock.', {
+          status: 409,
+          retryable: true,
+          details: { lockCategory: path.basename(lockPath) },
+        });
+      }
+      await delay(retryMs);
+    }
+  }
+}
+
+async function withFileLock(lockPath, fn, options = {}) {
+  const release = await acquireFileLock(lockPath, options);
+  try { return await fn(); } finally { await release(); }
+}
+
+function syncDirectoryBestEffort(directory) {
+  let fd;
+  try {
+    fd = fs.openSync(directory, 'r');
+    fs.fsyncSync(fd);
+  } catch {
+    // Directory fsync is unsupported on some filesystems; the file replace is already durable.
+  } finally {
+    if (fd != null) try { fs.closeSync(fd); } catch {
+      // Closing a best-effort directory descriptor cannot invalidate the completed file replace.
+    }
+  }
+}
+
+function replaceWithRetry(tempPath, targetPath, options = {}) {
+  const retries = Number.isInteger(options.renameRetries) ? options.renameRetries : 8;
+  const waitBuffer = new Int32Array(new SharedArrayBuffer(4));
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    try {
+      fs.renameSync(tempPath, targetPath);
+      return;
+    } catch (error) {
+      lastError = error;
+      if (!error || !['EPERM', 'EACCES', 'EBUSY', 'EEXIST'].includes(error.code) || attempt === retries) break;
+      Atomics.wait(waitBuffer, 0, 0, Math.min(250, 10 * (2 ** attempt)));
+    }
+  }
+  throw lastError;
+}
+
+function writeFileAtomic(filePath, content, options = {}) {
+  const directory = path.dirname(filePath);
+  fs.mkdirSync(directory, { recursive: true });
+  const tempPath = path.join(directory, `.${path.basename(filePath)}.${process.pid}.${Date.now()}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  let fd;
+  try {
+    fd = fs.openSync(tempPath, 'wx', options.mode || 0o600);
+    fs.writeFileSync(fd, content, options.encoding || 'utf8');
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = null;
+    if (typeof options.beforeRename === 'function') options.beforeRename(tempPath, filePath);
+    replaceWithRetry(tempPath, filePath, options);
+    syncDirectoryBestEffort(directory);
+    return { path: filePath };
+  } catch (error) {
+    if (fd != null) try { fs.closeSync(fd); } catch {
+      // Preserve the original write error.
+    }
+    try { if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath); } catch {
+      // Preserve the original write error; stale temp files are never treated as live data.
+    }
+    throw error;
+  }
+}
+
+function writeJsonAtomic(filePath, value, options = {}) {
+  return writeFileAtomic(filePath, `${JSON.stringify(value, null, 2)}\n`, options);
+}
+
+function readJsonStrict(filePath, options = {}) {
+  let raw;
+  try { raw = fs.readFileSync(filePath, 'utf8'); }
+  catch (error) {
+    if (error && error.code === 'ENOENT' && options.allowMissing) return options.defaultValue;
+    throw error;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof options.validate === 'function') options.validate(parsed);
+    return parsed;
+  } catch (error) {
+    if (error instanceof DomainError) throw error;
+    throw new DomainError('DATA_CORRUPT', 'A JSON data file is corrupt.', {
+      status: 500,
+      cause: error,
+      details: { category: options.category || 'json' },
+    });
+  }
+}
+
+async function appendJsonlLocked(filePath, value, options = {}) {
+  const lockPath = options.lockPath || `${filePath}.lock`;
+  return withFileLock(lockPath, async () => {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const fd = fs.openSync(filePath, 'a', options.mode || 0o600);
+    try {
+      fs.writeFileSync(fd, `${JSON.stringify(value)}\n`, 'utf8');
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    return value;
+  }, options);
+}
+
+function cleanupStaleTemps(directory, options = {}) {
+  if (!fs.existsSync(directory)) return [];
+  const olderThanMs = Number.isFinite(options.olderThanMs) ? options.olderThanMs : 24 * 60 * 60 * 1000;
+  const now = Date.now();
+  const removed = [];
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (!entry.isFile() || !/^\..+\.\d+\.\d+\.[a-f0-9]+\.tmp$/i.test(entry.name)) continue;
+    const absolute = path.join(directory, entry.name);
+    const stat = fs.statSync(absolute);
+    if ((now - stat.mtimeMs) < olderThanMs) continue;
+    fs.unlinkSync(absolute);
+    removed.push(absolute);
+  }
+  return removed;
+}
+
+module.exports = {
+  DEFAULT_LOCK_TIMEOUT_MS,
+  DEFAULT_STALE_LOCK_MS,
+  acquireFileLock,
+  withFileLock,
+  writeFileAtomic,
+  writeJsonAtomic,
+  readJsonStrict,
+  appendJsonlLocked,
+  cleanupStaleTemps,
+};