@sanqianx/project-knowledge 4.6.1

package/_site/lib/context-pack-builder.js

@@ -0,0 +1,299 @@
+// Context Pack Builder (TASK-006)
+// Collects Git diff / stats, project goal, related module/change docs,
+// package/config files, neighbouring source, and tests into a machine-readable
+// context pack written to _site/_ai/<slug>/context-packs/<run-id>/.
+//
+// Path safety: every path is normalized and verified to live inside the project root
+// before it is added to the pack. Outside-the-project paths are rejected.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execGit } = require('./git-runner');
+const aiWorkspace = require('./ai-workspace');
+
+const MAX_FILE_BYTES = 200 * 1024;     // Skip files larger than 200 KB
+const MAX_EXCERPT_BYTES = 8 * 1024;    // Excerpt limited to 8 KB
+const BINARY_DETECT_BYTES = 4096;      // Read up to 4 KB to detect binary
+
+const PACKAGE_CONFIG_FILES = [
+  'package.json', 'package-lock.json', 'pnpm-workspace.yaml', 'pnpm-lock.yaml',
+  'tsconfig.json', 'tsconfig.base.json', 'pyproject.toml', 'setup.py', 'requirements.txt',
+  'Cargo.toml', 'Cargo.lock', 'go.mod', 'go.sum', 'pom.xml', 'build.gradle',
+  '.eslintrc.json', '.eslintrc.js', '.prettierrc.json',
+];
+
+function shortHash(input) {
+  return crypto.createHash('sha1').update(input).digest('hex').slice(0, 12);
+}
+
+function isSafePath(projectRoot, target) {
+  const resolved = path.resolve(projectRoot, target);
+  const root = path.resolve(projectRoot);
+  // Use a separator-aware check so 'proj-other' does not pass 'proj' as parent.
+  return resolved === root || resolved.startsWith(root + path.sep) || resolved.startsWith(root + '/');
+}
+
+function isBinaryBuffer(buf) {
+  const limit = Math.min(BINARY_DETECT_BYTES, buf.length);
+  for (let i = 0; i < limit; i++) {
+    if (buf[i] === 0) return true;
+  }
+  return false;
+}
+
+function readSafeExcerpt(absPath) {
+  let stat;
+  try { stat = fs.statSync(absPath); } catch { return null; }
+  if (!stat.isFile()) return null;
+  if (stat.size > MAX_FILE_BYTES) {
+    return { excerpt: null, size: stat.size, binary: false, skipped: 'too-large' };
+  }
+  let buf;
+  try { buf = fs.readFileSync(absPath); } catch { return null; }
+  if (isBinaryBuffer(buf)) {
+    return { excerpt: null, size: stat.size, binary: true, skipped: 'binary' };
+  }
+  const text = buf.toString('utf-8');
+  if (text.length > MAX_EXCERPT_BYTES) {
+    return { excerpt: text.slice(0, MAX_EXCERPT_BYTES) + '\n...[truncated]', size: stat.size, binary: false, truncated: true };
+  }
+  return { excerpt: text, size: stat.size, binary: false, truncated: false };
+}
+
+function getNeighborPaths(projectRoot, changedFiles) {
+  const neighbors = new Set();
+  for (const file of changedFiles) {
+    if (!file) continue;
+    const dir = path.dirname(file);
+    if (!dir || dir === '.') continue;
+    try {
+      const entries = fs.readdirSync(path.join(projectRoot, dir), { withFileTypes: true });
+      for (const e of entries) {
+        if (!e.isFile()) continue;
+        if (e.name.startsWith('.')) continue;
+        const rel = path.posix.join(dir, e.name).replace(/\\/g, '/');
+        if (changedFiles.includes(rel)) continue;
+        neighbors.add(rel);
+      }
+    } catch {
+      // Neighbor discovery is optional evidence; unreadable directories are omitted from the manifest.
+    }
+  }
+  return [...neighbors];
+}
+
+function getTestPaths(projectRoot, changedFiles) {
+  const tests = new Set();
+  const isTestName = (name) => /\.(test|spec)\.[a-z]+$/i.test(name) || /^test[s]?[\/\\]/i.test(name) || /__tests__[\/\\]/i.test(name);
+  // Tests in the same directory tree, and direct "test" / "tests" siblings
+  for (const file of changedFiles) {
+    if (!file) continue;
+    const dir = path.dirname(file);
+    // Same-dir tests
+    try {
+      const entries = fs.readdirSync(path.join(projectRoot, dir), { withFileTypes: true });
+      for (const e of entries) {
+        if (!e.isFile()) continue;
+        if (isTestName(e.name)) {
+          tests.add(path.posix.join(dir, e.name).replace(/\\/g, '/'));
+        }
+      }
+    } catch {
+      // Test discovery is best-effort and records only readable sibling files.
+    }
+    // Direct test/ folder sibling
+    for (const candidate of ['tests', 'test', '__tests__']) {
+      const testDir = path.join(projectRoot, dir, candidate);
+      if (!fs.existsSync(testDir)) continue;
+      try {
+        const entries = fs.readdirSync(testDir, { withFileTypes: true });
+        for (const e of entries) {
+          if (!e.isFile()) continue;
+          if (isTestName(e.name)) {
+            tests.add(path.posix.join(dir, candidate, e.name).replace(/\\/g, '/'));
+          }
+        }
+      } catch {
+        // An unreadable optional test directory contributes no context-pack entry.
+      }
+    }
+  }
+  return [...tests];
+}
+
+function findRelatedDocs(projectRoot, changedFiles) {
+  // Map files to existing module/change docs by lightweight body/path match.
+  const out = new Set();
+  const dirs = [path.join(projectRoot, 'modules'), path.join(projectRoot, 'changes')];
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) continue;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (!e.isFile() || !e.name.endsWith('.md')) continue;
+      const full = path.join(dir, e.name);
+      let text;
+      try { text = fs.readFileSync(full, 'utf-8'); } catch { continue; }
+      const rel = path.posix.join(path.basename(dir), e.name).replace(/\\/g, '/');
+      // Heuristic: if any changed file path is mentioned in the doc body, treat as related.
+      for (const f of changedFiles) {
+        if (f && text.includes(f)) { out.add(rel); break; }
+      }
+    }
+  }
+  return [...out];
+}
+
+async function buildContextPack({ project, runId, trigger, commits = [], options = {} }) {
+  if (!project || !project.slug) throw new Error('project required');
+  const slug = project.slug;
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(slug)) throw new Error('invalid project id');
+  if (runId && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(runId)) throw new Error('invalid context pack run id');
+  if (!project.kbPath) throw new Error('project.kbPath is required');
+  const projectRoot = path.resolve(project.kbPath);
+  if (!isSafePath(projectRoot, '')) throw new Error('unsafe project root');
+
+  const gitPath = project.gitPath || project.localPath;
+  if (!gitPath) throw new Error('project has no git/local path');
+  const sourceRoot = path.resolve(gitPath); // source files live in the git repo, not the KB
+
+  const maxFiles = Number.isInteger(options.maxFiles) && options.maxFiles > 0 ? Math.min(options.maxFiles, 500) : 80;
+  const entries = [];
+  const seenAbs = new Set();
+  const safeSeen = (rel) => entries.find(e => e.path === rel);
+
+  function addEntry(rel, kind, reason) {
+    if (entries.length >= maxFiles) return;
+    // Decide which root to read from: KB files are anchored at projectRoot,
+    // source files are anchored at sourceRoot.
+    const isKbKind = ['goal', 'analysis', 'module-doc', 'change-doc'].includes(kind);
+    const root = isKbKind ? projectRoot : sourceRoot;
+    if (!isSafePath(root, rel)) return; // path traversal guard
+    if (safeSeen(rel)) return;
+    const abs = path.join(root, rel);
+    if (seenAbs.has(abs)) return;
+    if (!fs.existsSync(abs)) return;
+    let stat;
+    try { stat = fs.statSync(abs); } catch { return; }
+    if (!stat.isFile()) return;
+    const data = readSafeExcerpt(abs);
+    if (!data) return;
+    entries.push({
+      path: rel.replace(/\\/g, '/'),
+      kind,
+      reason,
+      size: data.size,
+      binary: data.binary,
+      truncated: !!data.truncated,
+      skipped: data.skipped || null,
+      excerpt: data.excerpt,
+    });
+    seenAbs.add(abs);
+  }
+
+  // 1. project goal (highest-priority context)
+  if (fs.existsSync(path.join(projectRoot, 'GOAL.md'))) {
+    addEntry('GOAL.md', 'goal', 'highest-priority human-controlled truth');
+  }
+
+  // 2. architecture / project analysis
+  if (fs.existsSync(path.join(projectRoot, 'ARCHITECTURE.md'))) {
+    addEntry('ARCHITECTURE.md', 'analysis', 'current architecture and project description');
+  }
+
+  let changedFiles = [];
+  let range = null;
+  let diffStat = null;
+
+  if (trigger === 'commits' && commits.length > 0) {
+    // 3a. Collect every file touched by any of the commits (use git show --name-only).
+    // This is safer than `diff first^..last` because the first commit has no parent.
+    const seen = new Set();
+    for (const c of commits) {
+      const r = await execGit(gitPath, ['show', '--name-only', '--format=', c.hash]);
+      if (r.ok) {
+        for (const line of (r.stdout || '').split('\n')) {
+          const f = line.trim();
+          if (f) seen.add(f);
+        }
+      }
+    }
+    changedFiles = [...seen];
+    range = `${commits[0].hash.slice(0, 7)}..${commits[commits.length - 1].hash.slice(0, 7)} (${commits.length} commit${commits.length === 1 ? '' : 's'})`;
+    // shortstat across the union of commits
+    const stat = await execGit(gitPath, ['diff', '--shortstat', `${commits[0].hash}^`, commits[commits.length - 1].hash]);
+    if (stat.ok) diffStat = (stat.stdout || '').trim();
+  } else {
+    // initial: enumerate tracked files (top N by size is overkill — just take first maxFiles)
+    const ls = await execGit(gitPath, ['ls-files']);
+    if (ls.ok) {
+      changedFiles = (ls.stdout || '').split('\n').map(s => s.trim()).filter(Boolean);
+    }
+    range = 'all-tracked-files';
+  }
+
+  // 3b. Changed files (as evidence)
+  for (const f of changedFiles) addEntry(f, 'git-changed', trigger === 'commits' ? `changed in ${range}` : 'tracked file');
+
+  // 4. Package / config files (look in source root)
+  for (const f of PACKAGE_CONFIG_FILES) {
+    if (fs.existsSync(path.join(sourceRoot, f))) addEntry(f, 'package-config', 'package or build configuration');
+  }
+
+  // 5. Neighbouring source files (in source root)
+  for (const f of getNeighborPaths(sourceRoot, changedFiles)) {
+    addEntry(f, 'neighbor', 'sibling of a changed file');
+  }
+
+  // 6. Tests near changed files (in source root)
+  for (const f of getTestPaths(sourceRoot, changedFiles)) {
+    addEntry(f, 'test-nearby', 'test for a changed file');
+  }
+
+  // 7. Related module / change docs (look in KB root)
+  for (const f of findRelatedDocs(projectRoot, changedFiles)) {
+    const kind = f.startsWith('changes/') ? 'change-doc' : 'module-doc';
+    addEntry(f, kind, 'mentions a changed file');
+  }
+
+  const pack = {
+    schema: 'context-pack/v1',
+    runId: runId || shortHash(`${slug}:${Date.now()}:${Math.random()}`),
+    project: slug,
+    createdAt: new Date().toISOString(),
+    trigger: trigger || 'initial',
+    gitPath,
+    kbPath: projectRoot,
+    sourceBranch: project.currentBranch || null,
+    sourceDefaultBranch: project.defaultBranch || null,
+    sourceRemote: project.remoteUrl || null,
+    range,
+    diffStat,
+    commitCount: commits.length,
+    commits: commits.map(c => ({ hash: c.hash, short: c.short, subject: c.subject, date: c.date, author: c.author })),
+    entries,
+    limits: {
+      maxFiles,
+      maxFileBytes: MAX_FILE_BYTES,
+      maxExcerptBytes: MAX_EXCERPT_BYTES,
+    },
+  };
+
+  // 8. Write to disk
+  const outDir = options.outputDir
+    ? path.resolve(options.outputDir, pack.runId)
+    : aiWorkspace.contextPackDir(slug, pack.runId);
+  fs.mkdirSync(outDir, { recursive: true });
+  fs.writeFileSync(path.join(outDir, 'context-pack.json'), JSON.stringify(pack, null, 2), 'utf-8');
+
+  return pack;
+}
+
+module.exports = {
+  buildContextPack,
+  isSafePath,
+  PACKAGE_CONFIG_FILES,
+  MAX_FILE_BYTES,
+  MAX_EXCERPT_BYTES,
+};

package/_site/lib/contracts.js

@@ -0,0 +1,279 @@
+const crypto = require('crypto');
+
+const SCHEMAS = Object.freeze({
+  settings: 'settings/v2',
+  projectRegistry: 'project-registry/v2',
+  projectConfig: 'project-config/v2',
+  projectState: 'project-state/v2',
+  requirement: 'requirement/v1',
+  aiCodingEvent: 'ai-coding-event/v1',
+  gitCommitBoundary: 'git-commit-boundary/v1',
+  commitConversationSnapshot: 'commit-conversation-snapshot/v1',
+  commitClaim: 'commit-claim/v1',
+  promotionJournal: 'promotion-journal/v1',
+  migrationJournal: 'migration-journal/v1',
+  log: 'log/v2',
+  hookEvent: 'hook-event/v2',
+});
+
+const SCHEMA_VERSIONS = Object.freeze({
+  settings: 2,
+  projectRegistry: 2,
+  projectConfig: 2,
+  projectState: 2,
+  hookManaged: 2,
+  layoutMigration: 'layout-v2',
+});
+
+const TRIGGERS = Object.freeze(['git-hook']);
+const TRIGGER_SET = new Set(TRIGGERS);
+const LOG_LEVELS = Object.freeze(['trace', 'debug', 'info', 'warn', 'error', 'fatal']);
+const LOG_LEVEL_SET = new Set(LOG_LEVELS);
+const ANALYSIS_PHASES = Object.freeze([
+  'idle',
+  'scanning',
+  'claim.created',
+  'requirement.bound',
+  'evidence.prepared',
+  'ai.running',
+  'output.validated',
+  'promotion.prepared',
+  'markdown.promoted',
+  'state.advanced',
+  'index.queued',
+  'index.applied',
+  'history-diverged',
+  'failed',
+]);
+
+const ERROR_CODES = Object.freeze([
+  'INVALID_ARGUMENT',
+  'INVALID_TRIGGER',
+  'SCHEMA_UNSUPPORTED',
+  'DATA_CORRUPT',
+  'IMMUTABLE_FIELD',
+  'PROJECT_BUSY',
+  'PROJECT_NOT_FOUND',
+  'PROJECT_AMBIGUOUS',
+  'HOOK_CONFLICT',
+  'HOOK_INVALID',
+  'HISTORY_DIVERGED',
+  'MIGRATION_SOURCE_CHANGED',
+  'MIGRATION_TARGET_CONFLICT',
+  'MIGRATION_FAILED',
+  'PATH_OUTSIDE_ROOT',
+  'AUTH_REQUIRED',
+  'ORIGIN_FORBIDDEN',
+  'LOGGER_UNAVAILABLE',
+  'LOG_CURSOR_EXPIRED',
+  'EVIDENCE_INTEGRITY_FAILED',
+  'AI_PROFILE_REQUIRED',
+]);
+
+const IMMUTABLE_PROJECT_FIELDS = Object.freeze([
+  'schema',
+  'schemaVersion',
+  'projectId',
+  'storageName',
+  'createdAt',
+  'knowledgePath',
+]);
+const MUTABLE_PROJECT_FIELDS = Object.freeze([
+  'displayName',
+  'enabled',
+  'aiProfileId',
+  'knowledgeLanguage',
+  'relatedProjectIds',
+]);
+
+const REDACTED_VALUE = '[REDACTED]';
+const REDACTION_KEY_PATTERN = /(?:api[-_]?key|auth(?:orization|token)?|access[-_]?token|refresh[-_]?token|bearer|password|passwd|secret|client[-_]?secret|private[-_]?key|cookie|set-cookie)/i;
+const FIELD_LIMITS = Object.freeze({
+  message: 4096,
+  stack: 16384,
+  path: 4096,
+  contextString: 8192,
+  requirement: 131072,
+});
+
+class DomainError extends Error {
+  constructor(code, message, options = {}) {
+    super(String(message || code || 'Domain error'), options.cause ? { cause: options.cause } : undefined);
+    this.name = 'DomainError';
+    this.code = ERROR_CODES.includes(code) ? code : 'INVALID_ARGUMENT';
+    this.status = Number.isInteger(options.status) ? options.status : 400;
+    this.retryable = options.retryable === true;
+    this.operationId = options.operationId || '';
+    this.details = sanitizePublicDetails(options.details);
+  }
+}
+
+function createId(prefix) {
+  const base = typeof crypto.randomUUID === 'function'
+    ? crypto.randomUUID().replace(/-/g, '')
+    : crypto.randomBytes(16).toString('hex');
+  return `${prefix}-${base}`;
+}
+
+function assertSchema(actual, expected, category = 'data') {
+  if (actual !== expected) {
+    throw new DomainError('SCHEMA_UNSUPPORTED', `Unsupported ${category} schema.`, {
+      status: 409,
+      details: { category, expected, actual: String(actual || '') },
+    });
+  }
+  return true;
+}
+
+function validateTrigger(trigger) {
+  if (!TRIGGER_SET.has(trigger)) {
+    throw new DomainError('INVALID_TRIGGER', 'Trigger must be git-hook.', {
+      details: { trigger: String(trigger || '') },
+    });
+  }
+  return trigger;
+}
+
+function validateLogLevel(level) {
+  if (!LOG_LEVEL_SET.has(level)) {
+    throw new DomainError('INVALID_ARGUMENT', 'Invalid log level.', {
+      details: { level: String(level || '') },
+    });
+  }
+  return level;
+}
+
+function validateProjectId(projectId) {
+  const value = String(projectId || '');
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{2,127}$/.test(value)) {
+    throw new DomainError('INVALID_ARGUMENT', 'Invalid projectId.');
+  }
+  return value;
+}
+
+function validateStateTransition(from, to) {
+  if (!ANALYSIS_PHASES.includes(from) || !ANALYSIS_PHASES.includes(to)) {
+    throw new DomainError('INVALID_ARGUMENT', 'Unknown analysis phase.', { details: { from, to } });
+  }
+  if (from === to) return true;
+  const allowed = {
+    idle: ['scanning', 'index.queued', 'failed'],
+    scanning: ['claim.created', 'idle', 'history-diverged', 'failed'],
+    'claim.created': ['requirement.bound', 'failed'],
+    'requirement.bound': ['evidence.prepared', 'failed'],
+    'evidence.prepared': ['ai.running', 'failed'],
+    'ai.running': ['output.validated', 'failed'],
+    'output.validated': ['promotion.prepared', 'failed'],
+    'promotion.prepared': ['markdown.promoted', 'failed'],
+    'markdown.promoted': ['state.advanced', 'failed'],
+    'state.advanced': ['index.queued', 'scanning', 'idle', 'failed'],
+    'index.queued': ['index.applied', 'failed'],
+    'index.applied': ['idle', 'scanning'],
+    'history-diverged': ['scanning', 'idle'],
+    failed: ['scanning', 'ai.running', 'promotion.prepared', 'index.queued', 'idle'],
+  };
+  if (!(allowed[from] || []).includes(to)) {
+    throw new DomainError('INVALID_ARGUMENT', `Invalid analysis transition: ${from} -> ${to}.`, {
+      details: { from, to },
+    });
+  }
+  return true;
+}
+
+function sanitizePublicDetails(value, seen = new WeakSet()) {
+  if (value == null || typeof value === 'boolean' || typeof value === 'number') return value;
+  if (typeof value === 'string') return value.slice(0, FIELD_LIMITS.contextString);
+  if (value instanceof Error) return { name: value.name, code: value.code || '', message: String(value.message || '').slice(0, FIELD_LIMITS.message) };
+  if (typeof value !== 'object') return String(value).slice(0, FIELD_LIMITS.contextString);
+  if (seen.has(value)) return '[Circular]';
+  seen.add(value);
+  if (Array.isArray(value)) return value.slice(0, 100).map(item => sanitizePublicDetails(item, seen));
+  const out = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (REDACTION_KEY_PATTERN.test(key) || /stack/i.test(key) || /prompt|diff|header/i.test(key)) {
+      continue;
+    } else {
+      out[key] = sanitizePublicDetails(child, seen);
+    }
+  }
+  return out;
+}
+
+function serializeErrorEnvelope(error, operationId = '') {
+  const source = error instanceof DomainError
+    ? error
+    : new DomainError('INVALID_ARGUMENT', 'The operation failed.', { status: 500, operationId });
+  return {
+    ok: false,
+    error: {
+      code: source.code,
+      message: source.message,
+      operationId: source.operationId || operationId || '',
+      retryable: source.retryable === true,
+      details: sanitizePublicDetails(source.details || {}),
+    },
+  };
+}
+
+function publicAiProfileView(profile) {
+  const source = profile && typeof profile === 'object' ? profile : {};
+  const secret = source.apiKey || source.authToken || source.anthropicAuthToken || '';
+  const publicView = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (REDACTION_KEY_PATTERN.test(key)) continue;
+    publicView[key] = value;
+  }
+  publicView.hasApiKey = Boolean(secret);
+  publicView.apiKeyMasked = secret ? `****${String(secret).slice(-4)}` : '';
+  return publicView;
+}
+
+function publicAiProfilesConfig(config) {
+  const source = config && typeof config === 'object' ? config : {};
+  return {
+    ...source,
+    profiles: Array.isArray(source.profiles) ? source.profiles.map(publicAiProfileView) : [],
+  };
+}
+
+function assertMutableProjectPatch(patch, options = {}) {
+  const allowKnowledgePath = options.allowKnowledgePath === true;
+  const allowRepoPath = options.allowRepoPath === true;
+  for (const key of Object.keys(patch && typeof patch === 'object' ? patch : {})) {
+    if (IMMUTABLE_PROJECT_FIELDS.includes(key) && !(allowKnowledgePath && key === 'knowledgePath')) {
+      throw new DomainError('IMMUTABLE_FIELD', `Project field is immutable: ${key}.`, { status: 409, details: { field: key } });
+    }
+    if (!MUTABLE_PROJECT_FIELDS.includes(key)
+      && !(allowKnowledgePath && key === 'knowledgePath')
+      && !(allowRepoPath && key === 'repoPath')) {
+      throw new DomainError('INVALID_ARGUMENT', `Unknown project field: ${key}.`, { details: { field: key } });
+    }
+  }
+  return true;
+}
+
+module.exports = {
+  SCHEMAS,
+  SCHEMA_VERSIONS,
+  TRIGGERS,
+  LOG_LEVELS,
+  ANALYSIS_PHASES,
+  ERROR_CODES,
+  IMMUTABLE_PROJECT_FIELDS,
+  MUTABLE_PROJECT_FIELDS,
+  REDACTED_VALUE,
+  REDACTION_KEY_PATTERN,
+  FIELD_LIMITS,
+  DomainError,
+  createId,
+  assertSchema,
+  validateTrigger,
+  validateLogLevel,
+  validateProjectId,
+  validateStateTransition,
+  sanitizePublicDetails,
+  serializeErrorEnvelope,
+  publicAiProfileView,
+  publicAiProfilesConfig,
+  assertMutableProjectPatch,
+};