@sanqianx/project-knowledge 4.6.1

package/_site/lib/settings-store.js

@@ -0,0 +1,113 @@
+const { SCHEMAS, DomainError, publicAiProfilesConfig } = require('./contracts');
+const AtomicFile = require('./atomic-file');
+const { StorageLayout } = require('./storage-layout');
+
+function defaultSettings() {
+  return {
+    schema: SCHEMAS.settings,
+    schemaVersion: 2,
+    knowledge: { rootPath: '' },
+    ai: { schema: 'ai-profiles/v1', profiles: [] },
+    embedding: {},
+    logging: {
+      levels: ['trace', 'debug', 'info', 'warn', 'error', 'fatal'],
+    },
+    promptOverrides: {},
+    integrations: {},
+    legacyExtensions: {},
+    updatedAt: '',
+  };
+}
+
+function mergeObjects(base, patch) {
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) return patch;
+  const output = { ...(base && typeof base === 'object' && !Array.isArray(base) ? base : {}) };
+  for (const [key, value] of Object.entries(patch)) {
+    output[key] = value && typeof value === 'object' && !Array.isArray(value)
+      ? mergeObjects(output[key], value)
+      : value;
+  }
+  return output;
+}
+
+function validateSettings(settings) {
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+    throw new DomainError('DATA_CORRUPT', 'Settings must be an object.', { status: 500 });
+  }
+  if (settings.schema !== SCHEMAS.settings || settings.schemaVersion !== 2) {
+    throw new DomainError('SCHEMA_UNSUPPORTED', 'Unsupported settings schema.', { status: 409 });
+  }
+  if (!settings.knowledge || typeof settings.knowledge.rootPath !== 'string') {
+    throw new DomainError('DATA_CORRUPT', 'Settings knowledge.rootPath is invalid.', { status: 500 });
+  }
+  const logging = settings.logging || {};
+  if (!Array.isArray(logging.levels) || !logging.levels.length || logging.levels.some(level => !['trace', 'debug', 'info', 'warn', 'error', 'fatal'].includes(level))) {
+    throw new DomainError('DATA_CORRUPT', 'Settings logging configuration is invalid.', { status: 500 });
+  }
+  return settings;
+}
+
+class SettingsStore {
+  constructor(options = {}) {
+    this.layout = options.layout || new StorageLayout(options);
+    this.atomic = options.atomic || AtomicFile;
+    this.filePath = options.filePath || this.layout.getSettingsPath();
+    this.lockPath = options.lockPath || this.layout.getRuntimePath('locks', 'settings.lock');
+  }
+
+  read(options = {}) {
+    if (options.allowMissing) {
+      return this.atomic.readJsonStrict(this.filePath, {
+        allowMissing: true,
+        defaultValue: defaultSettings(),
+        category: 'settings',
+        validate: validateSettings,
+      });
+    }
+    return this.atomic.readJsonStrict(this.filePath, { category: 'settings', validate: validateSettings });
+  }
+
+  async initialize(initial = {}) {
+    return this.atomic.withFileLock(this.lockPath, async () => {
+      let current;
+      try { current = this.read(); }
+      catch (error) {
+        if (!error || error.code !== 'ENOENT') throw error;
+      }
+      if (current) return current;
+      const next = validateSettings(mergeObjects(defaultSettings(), initial));
+      next.updatedAt = new Date().toISOString();
+      this.atomic.writeJsonAtomic(this.filePath, next);
+      return next;
+    });
+  }
+
+  async updatePatch(patch) {
+    return this.atomic.withFileLock(this.lockPath, async () => {
+      if (patch && patch.logging && typeof patch.logging === 'object') {
+        const unknown = Object.keys(patch.logging).find(key => key !== 'levels');
+        if (unknown) throw new DomainError('INVALID_ARGUMENT', `Logging setting is read-only or unsupported: ${unknown}.`, { details: { field: unknown } });
+      }
+      const current = this.read({ allowMissing: true });
+      const next = mergeObjects(current, patch || {});
+      next.schema = SCHEMAS.settings;
+      next.schemaVersion = 2;
+      next.updatedAt = new Date().toISOString();
+      validateSettings(next);
+      if (next.knowledge.rootPath) this.layout.validateKnowledgeRoot(next.knowledge.rootPath);
+      this.atomic.writeJsonAtomic(this.filePath, next);
+      return next;
+    });
+  }
+
+  readPublicView(options = {}) {
+    const settings = this.read(options);
+    return {
+      ...settings,
+      ai: publicAiProfilesConfig(settings.ai),
+      logging: { levels: [...settings.logging.levels] },
+    };
+  }
+}
+
+module.exports = { SettingsStore, defaultSettings, validateSettings, mergeObjects };

package/_site/lib/storage-layout.js

@@ -0,0 +1,162 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const dataDirModule = require('./data-dir');
+const { DomainError, validateProjectId } = require('./contracts');
+
+function stripTrailingSeparators(value) {
+  const parsed = path.parse(value);
+  let result = value;
+  while (result.length > parsed.root.length && /[\\/]$/.test(result)) result = result.slice(0, -1);
+  return result;
+}
+
+class StorageLayout {
+  constructor(options = {}) {
+    this.dataDir = path.resolve(options.dataDir || dataDirModule.getDataDir());
+    this.platform = options.platform || process.platform;
+  }
+
+  getDataDir() { return this.dataDir; }
+  getSettingsPath() { return path.join(this.dataDir, 'settings.json'); }
+  getProjectRegistryPath() { return path.join(this.dataDir, 'projects.json'); }
+  getMigrationStatePath() { return path.join(this.dataDir, 'runtime', 'migration-state.json'); }
+  getMigrationCompletionPath() { return path.join(this.dataDir, 'runtime', 'layout-v2.completed.json'); }
+
+  getProjectMetadataDir(projectId) {
+    return path.join(this.dataDir, 'projects', validateProjectId(projectId));
+  }
+
+  getProjectConfigPath(projectId) { return path.join(this.getProjectMetadataDir(projectId), 'config.json'); }
+  getProjectStatePath(projectId) { return path.join(this.getProjectMetadataDir(projectId), 'state.json'); }
+  getProjectRequirementsPath(projectId) { return path.join(this.getProjectMetadataDir(projectId), 'requirements.jsonl'); }
+  getProjectConversationEventsPath(projectId) { return path.join(this.getProjectMetadataDir(projectId), 'conversation-events.jsonl'); }
+  getProjectCommitBoundariesDir(projectId) { return path.join(this.getProjectMetadataDir(projectId), 'commit-boundaries'); }
+  getProjectCommitConversationsDir(projectId) { return path.join(this.getProjectMetadataDir(projectId), 'commit-conversations'); }
+  validateCommitSha(commitSha) {
+    const value = String(commitSha || '').trim().toLowerCase();
+    if (!/^[a-f0-9]{7,64}$/.test(value)) throw new DomainError('INVALID_ARGUMENT', 'Invalid commit SHA.');
+    return value;
+  }
+  getProjectCommitBoundaryPath(projectId, commitSha) {
+    return path.join(this.getProjectCommitBoundariesDir(projectId), `${this.validateCommitSha(commitSha)}.json`);
+  }
+  getProjectCommitConversationPath(projectId, commitSha) {
+    return path.join(this.getProjectCommitConversationsDir(projectId), `${this.validateCommitSha(commitSha)}.json`);
+  }
+  getProjectLockPath(projectId) { return path.join(this.getProjectMetadataDir(projectId), '.project.lock'); }
+  getRegistryLockPath() { return path.join(this.dataDir, 'runtime', 'locks', 'projects.lock'); }
+
+  getIndexPath() { return path.join(this.dataDir, 'index', 'knowledge.lancedb'); }
+  getCachePath(...segments) { return path.join(this.dataDir, 'cache', ...segments); }
+  getRuntimePath(...segments) { return path.join(this.dataDir, 'runtime', ...segments); }
+  getRecoveryPath(...segments) { return path.join(this.dataDir, 'recovery', ...segments); }
+
+  getLogPath(scope = 'app', projectId = '') {
+    if (scope === 'system') return path.join(this.dataDir, 'logs', 'system');
+    // app/hooks are read-only compatibility locations for pre-v13 logs.
+    if (scope === 'app') return path.join(this.dataDir, 'logs', 'app');
+    if (scope === 'hooks') return path.join(this.dataDir, 'logs', 'hooks');
+    if (scope === 'project' || scope === 'projects') {
+      return path.join(this.dataDir, 'logs', 'projects', validateProjectId(projectId));
+    }
+    throw new DomainError('INVALID_ARGUMENT', `Unknown log scope: ${scope}.`);
+  }
+
+  getKnowledgeRootPath(settings) {
+    const root = settings && settings.knowledge && settings.knowledge.rootPath;
+    if (!root || typeof root !== 'string') {
+      throw new DomainError('INVALID_ARGUMENT', 'Knowledge root is not configured.', { status: 409 });
+    }
+    return path.resolve(root);
+  }
+
+  resolveNewProjectKnowledgePath(storageName, settings) {
+    const safe = String(storageName || '').trim();
+    if (!safe || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(safe)) {
+      throw new DomainError('INVALID_ARGUMENT', 'Invalid storageName.');
+    }
+    return path.join(this.getKnowledgeRootPath(settings), safe);
+  }
+
+  getProjectKnowledgePath(config) {
+    if (!config || typeof config.knowledgePath !== 'string' || !config.knowledgePath.trim()) {
+      throw new DomainError('DATA_CORRUPT', 'Project knowledgePath is missing.', { status: 500 });
+    }
+    return path.resolve(config.knowledgePath);
+  }
+
+  normalizeForComparison(value) {
+    if (!value || typeof value !== 'string') return '';
+    const normalized = stripTrailingSeparators(path.resolve(value));
+    return this.platform === 'win32' ? normalized.toLowerCase() : normalized;
+  }
+
+  pathsEqual(left, right) {
+    const a = this.normalizeForComparison(left);
+    const b = this.normalizeForComparison(right);
+    return Boolean(a && b && a === b);
+  }
+
+  isPathInside(root, target, options = {}) {
+    if (!root || !target) return false;
+    const resolve = options.realpath === false ? path.resolve : value => this.realpathWithMissingLeaf(value);
+    let rootPath;
+    let targetPath;
+    try {
+      rootPath = resolve(root);
+      targetPath = resolve(target);
+    } catch {
+      return false;
+    }
+    const rel = path.relative(rootPath, targetPath);
+    if (rel === '') return options.allowRoot !== false;
+    return !rel.startsWith('..') && !path.isAbsolute(rel);
+  }
+
+  realpathWithMissingLeaf(value) {
+    let current = path.resolve(value);
+    const suffix = [];
+    while (!fs.existsSync(current)) {
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      suffix.unshift(path.basename(current));
+      current = parent;
+    }
+    const real = fs.realpathSync.native ? fs.realpathSync.native(current) : fs.realpathSync(current);
+    return path.join(real, ...suffix);
+  }
+
+  validateKnowledgeRoot(rootPath) {
+    const absolute = path.resolve(String(rootPath || '').trim());
+    if (!rootPath) throw new DomainError('INVALID_ARGUMENT', 'Knowledge root is required.');
+    let created = false;
+    if (!fs.existsSync(absolute)) {
+      fs.mkdirSync(absolute, { recursive: true });
+      created = true;
+    }
+    if (!fs.statSync(absolute).isDirectory()) {
+      throw new DomainError('INVALID_ARGUMENT', 'Knowledge root must be a directory.');
+    }
+    const probe = path.join(absolute, `.project-knowledge-write-probe-${process.pid}-${crypto.randomBytes(6).toString('hex')}`);
+    try {
+      const fd = fs.openSync(probe, 'wx', 0o600);
+      fs.fsyncSync(fd);
+      fs.closeSync(fd);
+      fs.unlinkSync(probe);
+    } catch (error) {
+      try { if (fs.existsSync(probe)) fs.unlinkSync(probe); } catch {
+        // Preserve the writability error; a uniquely named failed probe is never runtime data.
+      }
+      throw new DomainError('INVALID_ARGUMENT', 'Knowledge root is not writable.', { status: 400, cause: error });
+    }
+    return { ok: true, rootPath: absolute, created };
+  }
+}
+
+function createStorageLayout(options) {
+  return new StorageLayout(options);
+}
+
+module.exports = { StorageLayout, createStorageLayout };