@sanqianx/project-knowledge 4.6.1

package/_site/lib/requirement-recorder.js

@@ -0,0 +1,278 @@
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const {
+  SCHEMAS,
+  FIELD_LIMITS,
+  DomainError,
+  createId,
+  validateProjectId,
+} = require('./contracts');
+const { StorageLayout } = require('./storage-layout');
+const { ProjectRegistryStore } = require('./project-registry-store');
+const { ProjectStore } = require('./project-store');
+const { ConversationStore } = require('./conversation-store');
+
+const REQUIREMENT_CLIENTS = Object.freeze(['claude', 'codex', 'opencode']);
+const CLIENT_ALIASES = Object.freeze({
+  'claude-code': 'claude',
+  claudecode: 'claude',
+  'codex-cli': 'codex',
+});
+
+function requiredMetadata(value, name, maxLength = 512) {
+  const normalized = String(value || '').trim();
+  if (!normalized || normalized.length > maxLength || /[\u0000-\u001f\u007f]/.test(normalized)) {
+    throw new DomainError('INVALID_ARGUMENT', `${name} must be a non-empty identifier no longer than ${maxLength} characters.`);
+  }
+  return normalized;
+}
+
+function optionalMetadata(value, name, maxLength = 512) {
+  if (value == null || value === '') return null;
+  return requiredMetadata(value, name, maxLength);
+}
+
+function normalizeClient(client) {
+  const raw = String(client || '').trim().toLowerCase();
+  const normalized = CLIENT_ALIASES[raw] || raw;
+  if (!REQUIREMENT_CLIENTS.includes(normalized)) {
+    throw new DomainError('INVALID_ARGUMENT', `client must be one of: ${REQUIREMENT_CLIENTS.join(', ')}.`);
+  }
+  return normalized;
+}
+
+function normalizeCommit(value, name = 'commit') {
+  if (value == null || value === '') return null;
+  const normalized = String(value).trim().toLowerCase();
+  if (!/^[0-9a-f]{7,64}$/.test(normalized)) {
+    throw new DomainError('INVALID_ARGUMENT', `${name} must be a Git object id.`);
+  }
+  return normalized;
+}
+
+function requirementHash(text) {
+  return `sha256:${crypto.createHash('sha256').update(text, 'utf8').digest('hex')}`;
+}
+
+// Canonical repo-identity/v1 builder from the Bridge package (synchronous
+// helpers only). Missing module degrades to null identity, never a guess.
+let bridgeIdentityModule = null;
+try {
+  const bridgeModule = require('@sanqianx/ai-coding-event-bridge');
+  if (bridgeModule && typeof bridgeModule.buildRepoIdentityV1 === 'function') bridgeIdentityModule = bridgeModule;
+} catch (_) {
+  bridgeIdentityModule = null;
+}
+
+class GitReader {
+  run(repoPath, args) {
+    return spawnSync('git', ['-C', path.resolve(repoPath), ...args], {
+      encoding: 'utf8',
+      windowsHide: true,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    });
+  }
+
+  resolveRoot(candidate) {
+    const resolved = path.resolve(candidate || process.cwd());
+    const gitCwd = fs.existsSync(resolved) && fs.statSync(resolved).isFile() ? path.dirname(resolved) : resolved;
+    const result = this.run(gitCwd, ['rev-parse', '--show-toplevel']);
+    const root = String(result.stdout || '').trim();
+    if (result.status !== 0 || !root) {
+      throw new DomainError('INVALID_ARGUMENT', 'repoPath must resolve to a Git worktree.');
+    }
+    return path.resolve(root);
+  }
+
+  currentContext(repoPath) {
+    try {
+      const headResult = this.run(repoPath, ['rev-parse', '--verify', 'HEAD']);
+      const head = headResult.status === 0 ? normalizeCommit(String(headResult.stdout || '').trim(), 'HEAD') : null;
+      const branchResult = this.run(repoPath, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+      const branch = branchResult.status === 0
+        ? optionalMetadata(String(branchResult.stdout || '').trim(), 'branch', 1024)
+        : null;
+      const topResult = this.run(repoPath, ['rev-parse', '--show-toplevel']);
+      const top = topResult.status === 0 && String(topResult.stdout || '').trim()
+        ? path.resolve(String(topResult.stdout).trim())
+        : null;
+      const commonResult = this.run(repoPath, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+      const commonDir = commonResult.status === 0 && String(commonResult.stdout || '').trim()
+        ? path.resolve(String(commonResult.stdout).trim())
+        : null;
+      let repoIdentity = null;
+      if (top && bridgeIdentityModule) {
+        let workspaceRoot = top;
+        try { workspaceRoot = fs.realpathSync.native(top) || top; } catch (_) { workspaceRoot = top; }
+        const remoteResult = this.run(repoPath, ['config', '--get', 'remote.origin.url']);
+        const remote = remoteResult.status === 0 && String(remoteResult.stdout || '').trim()
+          ? bridgeIdentityModule.normalizeGitUrl(String(remoteResult.stdout).trim())
+          : null;
+        repoIdentity = bridgeIdentityModule.buildRepoIdentityV1({ workspaceRoot, commonDir, remote });
+      }
+      return { headAtRecord: head, branch, repoIdentity };
+    } catch {
+      return { headAtRecord: null, branch: null, repoIdentity: null };
+    }
+  }
+
+  isAncestor(repoPath, ancestor, commit) {
+    const left = normalizeCommit(ancestor, 'ancestor');
+    const right = normalizeCommit(commit, 'commit');
+    if (!left || !right) return false;
+    return this.run(repoPath, ['merge-base', '--is-ancestor', left, right]).status === 0;
+  }
+}
+
+class ProjectRequirementResolver {
+  constructor(options = {}) {
+    this.layout = options.layout || new StorageLayout(options);
+    this.registryStore = options.registryStore || new ProjectRegistryStore({ layout: this.layout });
+    this.projectStore = options.projectStore || new ProjectStore({ layout: this.layout });
+    this.gitReader = options.gitReader || new GitReader();
+  }
+
+  resolve(input = {}) {
+    const explicitProjectId = input.projectId ? validateProjectId(input.projectId) : '';
+    const registry = this.registryStore.read({ allowMissing: true });
+    if (explicitProjectId) {
+      if (!registry.projects[explicitProjectId]) {
+        throw new DomainError('PROJECT_NOT_FOUND', 'The explicit projectId is not registered.', { status: 404 });
+      }
+      const config = this.projectStore.readConfig(explicitProjectId);
+      if (config.enabled === false) throw new DomainError('PROJECT_NOT_FOUND', 'The explicit project is disabled.', { status: 404 });
+      if (input.repoPath) {
+        const root = this.gitReader.resolveRoot(input.repoPath);
+        if (!this.layout.pathsEqual(root, config.repoPath)) {
+          throw new DomainError('PROJECT_NOT_FOUND', 'repoPath does not match the explicit projectId.', { status: 404 });
+        }
+      }
+      return { projectId: explicitProjectId, config };
+    }
+
+    const root = this.gitReader.resolveRoot(input.repoPath || process.cwd());
+    const matches = registry.projectOrder.filter(projectId => {
+      const config = this.projectStore.readConfig(projectId);
+      return config.enabled !== false && this.layout.pathsEqual(config.repoPath, root);
+    });
+    if (matches.length === 0) {
+      throw new DomainError('PROJECT_NOT_FOUND', 'No enabled project is registered for the current Git root.', { status: 404 });
+    }
+    if (matches.length > 1) {
+      throw new DomainError('PROJECT_AMBIGUOUS', 'Multiple projects are registered for the current Git root.', { status: 409 });
+    }
+    const projectId = matches[0];
+    return { projectId, config: this.projectStore.readConfig(projectId) };
+  }
+}
+
+class RequirementRecorder {
+  constructor(options = {}) {
+    this.layout = options.layout || new StorageLayout(options);
+    this.projectStore = options.projectStore || new ProjectStore({ layout: this.layout });
+    this.gitReader = options.gitReader || new GitReader();
+    this.resolver = options.resolver || new ProjectRequirementResolver({
+      layout: this.layout,
+      projectStore: this.projectStore,
+      registryStore: options.registryStore,
+      gitReader: this.gitReader,
+    });
+    this.logger = options.logger || null;
+    this.conversationStore = options.conversationStore || new ConversationStore({
+      layout: this.layout,
+      projectStore: this.projectStore,
+      logger: this.logger,
+    });
+    this.now = options.now || (() => new Date().toISOString());
+    this.createRequirementId = options.createRequirementId || (() => createId('req'));
+  }
+
+  async recordRequirement(input = {}) {
+    const operationId = input.operationId || createId('op');
+    try {
+      const text = typeof input.text === 'string'
+        ? input.text
+        : typeof input.requirement === 'string' ? input.requirement : '';
+      if (!text.trim()) throw new DomainError('INVALID_ARGUMENT', 'Requirement text must be non-empty.', { operationId });
+      if (text.length > FIELD_LIMITS.requirement) {
+        throw new DomainError('INVALID_ARGUMENT', `Requirement text exceeds ${FIELD_LIMITS.requirement} characters.`, { operationId });
+      }
+      const client = normalizeClient(input.client);
+      const sessionId = requiredMetadata(input.sessionId, 'sessionId');
+      const conversationId = optionalMetadata(input.conversationId, 'conversationId');
+      const explicitCommit = normalizeCommit(input.explicitCommit, 'explicitCommit');
+      const resolved = this.resolver.resolve(input);
+      const gitContext = this.gitReader.currentContext(resolved.config.repoPath);
+      const record = {
+        schema: SCHEMAS.requirement,
+        id: this.createRequirementId(),
+        ts: this.now(),
+        projectId: resolved.projectId,
+        client,
+        sessionId,
+        conversationId,
+        branch: gitContext.branch || null,
+        headAtRecord: gitContext.headAtRecord || null,
+        requirement: text,
+        requirementHash: requirementHash(text),
+        explicitCommit,
+      };
+      const source = client === 'claude' ? 'claude-code' : client;
+      const turnId = optionalMetadata(input.turnId, 'turnId') || `explicit-${record.id}`;
+      await this.conversationStore.appendEvent(resolved.projectId, {
+        eventId: `explicit-${record.id}`,
+        sequence: null,
+        source,
+        eventType: 'user_prompt',
+        role: 'user',
+        content: text,
+        sessionId,
+        turnId,
+        projectPath: resolved.config.repoPath,
+        repoIdentity: gitContext.repoIdentity,
+        branch: record.branch,
+        headAtCapture: record.headAtRecord,
+        capturedAt: record.ts,
+        rawEventType: 'explicit-requirement-adapter',
+        identityConfidence: explicitCommit ? 'explicit' : 'high',
+        captureStatus: 'explicit-supplement',
+        explicitCommitSha: explicitCommit,
+        legacyRequirementId: record.id,
+      });
+      if (this.logger && typeof this.logger.info === 'function') {
+        await this.logger.info('requirement.recorded', 'User requirement recorded.', {
+          operationId,
+          projectId: resolved.projectId,
+          requirementId: record.id,
+          client,
+          sessionId,
+          requirementHash: record.requirementHash,
+        });
+      }
+      return { ...record, turnId };
+    } catch (error) {
+      if (error instanceof DomainError) {
+        if (!error.operationId) error.operationId = operationId;
+        throw error;
+      }
+      throw new DomainError('INVALID_ARGUMENT', 'Requirement could not be recorded durably.', {
+        status: 500,
+        retryable: true,
+        operationId,
+        cause: error,
+      });
+    }
+  }
+}
+
+module.exports = {
+  REQUIREMENT_CLIENTS,
+  GitReader,
+  ProjectRequirementResolver,
+  RequirementRecorder,
+  normalizeClient,
+  normalizeCommit,
+  requirementHash,
+};

package/_site/lib/runtime-endpoint.js

@@ -0,0 +1,160 @@
+// Stable discovery record for the one local project-knowledge backend.
+//
+// Git hooks and the desktop shell must not bake in a port: the CLI can fall
+// back from 5757 when that port is occupied.  This small file lives in the
+// version-independent data directory and is replaced atomically whenever a
+// backend starts.
+
+const fs = require('fs');
+const path = require('path');
+
+const SCHEMA = 'project-knowledge/runtime-endpoint/v1';
+const FILENAME = 'runtime-endpoint.json';
+
+function endpointPath(dataDir) {
+  return path.join(path.resolve(dataDir), FILENAME);
+}
+
+function isLoopbackHost(host) {
+  const value = String(host || '').trim().toLowerCase();
+  return value === '127.0.0.1' || value === 'localhost' || value === '::1';
+}
+
+function normalizeEndpoint(value) {
+  if (!value || typeof value !== 'object') return null;
+  const pid = Number(value.pid);
+  const port = Number(value.port);
+  const host = String(value.host || '127.0.0.1').trim();
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return null;
+  // Runtime discovery is intentionally local-only. Never let a modified
+  // endpoint file make hooks send repository metadata to a remote host.
+  if (!isLoopbackHost(host)) return null;
+  return {
+    schema: SCHEMA,
+    pid,
+    host,
+    port,
+    mode: String(value.mode || 'cli'),
+    startedAt: String(value.startedAt || ''),
+  };
+}
+
+function readEndpoint(dataDir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(endpointPath(dataDir), 'utf-8'));
+    if (parsed.schema !== SCHEMA) return null;
+    return normalizeEndpoint(parsed);
+  } catch {
+    return null;
+  }
+}
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(Number(pid), 0);
+    return true;
+  } catch (error) {
+    // EPERM means the process exists but we lack permission to signal it
+    // (common on Windows when the daemon and this process run at different
+    // privilege levels). Treat that as alive — only ESRCH/ENOENT mean dead.
+    // Misjudging a live process as dead would delete a running backend's
+    // endpoint file (see readLiveEndpoint) and spawn a duplicate.
+    if (error && error.code === 'EPERM') return true;
+    return false;
+  }
+}
+
+function readLiveEndpoint(dataDir, { removeStale = true } = {}) {
+  const endpoint = readEndpoint(dataDir);
+  if (!endpoint) return null;
+  if (isProcessAlive(endpoint.pid)) return endpoint;
+  if (removeStale) clearEndpoint(dataDir, { pid: endpoint.pid });
+  return null;
+}
+
+function writeEndpoint(dataDir, value) {
+  const endpoint = normalizeEndpoint({
+    ...value,
+    startedAt: value && value.startedAt || new Date().toISOString(),
+  });
+  if (!endpoint) throw new Error('invalid runtime endpoint');
+  const target = endpointPath(dataDir);
+  const temp = `${target}.${process.pid}.tmp`;
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(temp, JSON.stringify(endpoint, null, 2) + '\n', 'utf-8');
+  try {
+    fs.renameSync(temp, target);
+  } catch (error) {
+    // Windows cannot always replace an existing file with renameSync.
+    try { fs.rmSync(target, { force: true }); } catch {
+      // The following rename is authoritative and reports endpoint replacement failure.
+    }
+    fs.renameSync(temp, target);
+  }
+  return endpoint;
+}
+
+function claimEndpoint(dataDir, value) {
+  const endpoint = normalizeEndpoint({
+    ...value,
+    startedAt: value && value.startedAt || new Date().toISOString(),
+  });
+  if (!endpoint) throw new Error('invalid runtime endpoint');
+  const target = endpointPath(dataDir);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      fs.writeFileSync(target, JSON.stringify(endpoint, null, 2) + '\n', {
+        encoding: 'utf-8',
+        flag: 'wx',
+      });
+      return { claimed: true, endpoint };
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') throw error;
+      const existing = readEndpoint(dataDir);
+      if (existing && isProcessAlive(existing.pid)) {
+        return { claimed: false, endpoint: existing };
+      }
+      // A just-created file can briefly be unreadable while another process
+      // writes it. Treat it as busy rather than deleting a concurrent claim.
+      try {
+        const ageMs = Date.now() - fs.statSync(target).mtimeMs;
+        if (!existing && ageMs < 2000) return { claimed: false, endpoint: null };
+      } catch {
+        // clearEndpoint performs the ownership-safe final check when stat is unavailable.
+      }
+      clearEndpoint(dataDir, existing ? { pid: existing.pid } : {});
+    }
+  }
+  return { claimed: false, endpoint: readLiveEndpoint(dataDir) };
+}
+
+function clearEndpoint(dataDir, { pid } = {}) {
+  const target = endpointPath(dataDir);
+  if (pid != null) {
+    const current = readEndpoint(dataDir);
+    if (current && current.pid !== Number(pid)) return false;
+  }
+  try {
+    fs.rmSync(target, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  SCHEMA,
+  FILENAME,
+  endpointPath,
+  isLoopbackHost,
+  normalizeEndpoint,
+  readEndpoint,
+  readLiveEndpoint,
+  writeEndpoint,
+  claimEndpoint,
+  clearEndpoint,
+  isProcessAlive,
+};