@sanqianx/project-knowledge 4.7.0 → 5.0.0

package/_site/scripts/install-module-candidates.js

@@ -0,0 +1,69 @@
+'use strict';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { createRequire } = require('node:module');
+const { spawnSync } = require('node:child_process');
+const AtomicFile = require('../lib/atomic-file');
+const { verifyInstalled, safeRelative } = require('./pack-module-candidates');
+const root = path.resolve(__dirname, '../..');
+const npmCli = process.env.npm_execpath || path.join(path.dirname(process.execPath), 'node_modules/npm/bin/npm-cli.js');
+function run(args, cwd) {
+  const result = spawnSync(process.execPath, [npmCli, ...args], { cwd, windowsHide: true, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+  if (result.status !== 0) throw new Error(`npm ${args[0]} failed (${result.status})`);
+  return result.stdout;
+}
+function contentAddressedArtifact(packedCore) {
+  const sha256 = crypto.createHash('sha256').update(fs.readFileSync(packedCore)).digest('hex');
+  const file = packedCore.replace(/\.tgz$/, `-${sha256}.tgz`);
+  if (file === packedCore) throw new Error('Candidate must be a tarball');
+  fs.copyFileSync(packedCore, file);
+  return { file, sha256 };
+}
+function main() {
+  const manifestFile = path.resolve(process.argv[2]);
+  const manifest = JSON.parse(fs.readFileSync(manifestFile));
+  if (manifest.schema !== 'project-knowledge/module-candidates/v1') throw new Error('Invalid candidate manifest');
+  const artifactRoot = path.dirname(manifestFile);
+  const dependencies = {};
+  for (const module of Object.values(manifest.modules)) {
+    if (!safeRelative(module.tarball) || !module.tarball.endsWith('.tgz')) throw new Error('Unsafe artifact path');
+    const file = path.join(artifactRoot, module.tarball);
+    if (fs.lstatSync(file).isSymbolicLink() || crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') !== module.sha256) throw new Error('Module artifact drift');
+    dependencies[module.installName] = `file:${file}`;
+  }
+  const candidate = JSON.parse(run(['pack', '--ignore-scripts', '--json', '--pack-destination', artifactRoot], root))[0];
+  const packedCore = path.join(artifactRoot, candidate.filename);
+  // Same-version local tarballs are cached by npm. Address each candidate by
+  // content so an update cannot silently keep an older runtime or UI.
+  const { sha256: shellSha256, file: shellArtifact } = contentAddressedArtifact(packedCore);
+  dependencies['@sanqianx/project-knowledge'] = `file:${shellArtifact}`;
+  const updateAt = process.argv.indexOf('--update');
+  const installedRoot = updateAt < 0 ? fs.mkdtempSync(path.join(os.tmpdir(), 'kb-installed-product-')) : path.resolve(process.argv[updateAt + 1]);
+  if (path.dirname(installedRoot) !== path.resolve(os.tmpdir()) || !path.basename(installedRoot).startsWith('kb-installed-product-') || fs.lstatSync(installedRoot).isSymbolicLink()) throw new Error('Only this task’s isolated installation can be updated');
+  if (updateAt >= 0 && JSON.parse(fs.readFileSync(path.join(installedRoot, 'installation-acceptance.json'))).installedRoot !== installedRoot) throw new Error('Installed fixture identity mismatch');
+  AtomicFile.writeJsonAtomic(path.join(installedRoot, 'package.json'), { name: 'kb-local-acceptance', version: '0.0.0', private: true, dependencies });
+  process.stdout.write(`Installing isolated product at ${installedRoot}\n`);
+  run(['install', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund'], installedRoot);
+  verifyInstalled(manifest, installedRoot);
+  const core = path.join(installedRoot, 'node_modules/@sanqianx/project-knowledge');
+  const resolver = createRequire(path.join(core, 'package.json'));
+  for (const module of Object.values(manifest.modules)) {
+    const actual = resolver.resolve(`${module.installName}/package.json`);
+    if (actual !== path.join(installedRoot, 'node_modules', module.installName, 'package.json')) throw new Error(`A nested stale module shadows the tested candidate: ${module.installName}`);
+  }
+  const verify = spawnSync(process.execPath, [path.join(core, '_site/scripts/verify-module-runtime.js'), '--working-tree'], { cwd: installedRoot, windowsHide: true, encoding: 'utf8' });
+  if (verify.status !== 0) throw new Error('Packaged engine integrity failed');
+  require('./verify-product-runtime').verifyProductRuntime(core);
+  for (const relative of ['vendor-manifest.json', 'module-runtime-manifest.json']) {
+    if (!fs.readFileSync(path.join(core, relative)).equals(fs.readFileSync(path.join(root, relative)))) throw new Error(`Installed candidate is stale: ${relative}`);
+  }
+  const report = { schema: 'project-knowledge/installed-candidates/v1', mode: 'local npm candidate installation, not remote release', installedRoot, core, artifactManifest: manifestFile, shellVersion: candidate.version, shellSha256, shellArtifact, modules: Object.fromEntries(Object.entries(manifest.modules).map(([key, module]) => [key, { version: module.version, sha256: module.sha256 }])), integrityPassed: true, testedAt: new Date().toISOString() };
+  AtomicFile.writeJsonAtomic(path.join(installedRoot, 'installation-acceptance.json'), report);
+  process.stdout.write(`INSTALLED_PRODUCT ${path.join(installedRoot, 'installation-acceptance.json')}\n`);
+}
+if (require.main === module) {
+  try { main(); } catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }
+}
+module.exports = { contentAddressedArtifact };

package/_site/scripts/pack-module-candidates.js

@@ -0,0 +1,72 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+const AtomicFile = require('../lib/atomic-file');
+const hash = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+const root = path.resolve(__dirname, '../..');
+const npmCli = process.env.npm_execpath || path.join(path.dirname(process.execPath), 'node_modules/npm/bin/npm-cli.js');
+const definitions = {
+  terminal: { option: '--terminal-source', name: '@sanqianx/claude-ai-workbench', installName: 'claude-ai-workbench', required: ['apps/agent-terminal/app.js', 'apps/agent-terminal/app.css', 'packages/server/lib/knowledge-context.js'] },
+  vectorHub: { option: '--vector-source', name: '@sanqianx/vector-hub', installName: '@sanqianx/vector-hub', required: ['dist/cjs/bin.js', 'dist/cjs/server/manager.js', 'ui/index.html'] },
+  eventBridge: { option: '--bridge-source', name: '@sanqianx/ai-coding-event-bridge-console', installName: '@sanqianx/ai-coding-event-bridge-console', required: ['src/server.js', 'src/bridge/core/consumer-registry.js', 'console/index.html'] },
+};
+function run(command, args, cwd) {
+  const result = spawnSync(command, args, { cwd, windowsHide: true, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+  if (result.status !== 0) throw new Error(`${path.basename(command)} failed (${result.status}): ${result.error?.message || result.stderr}`);
+  return result.stdout;
+}
+function safeRelative(file) { return typeof file === 'string' && !path.isAbsolute(file) && !/[\\\x00-\x1f]/.test(file) && !file.split('/').some(p => p === '..' || p === '.'); }
+function verifyInstalled(manifest, installedRoot) {
+  for (const [key, module] of Object.entries(manifest.modules)) {
+    const directory = path.join(installedRoot, 'node_modules', module.installName);
+    const pkg = JSON.parse(fs.readFileSync(path.join(directory, 'package.json')));
+    if (pkg.name !== module.name || pkg.version !== module.version) throw new Error(`Installed module identity mismatch: ${key}`);
+    for (const [relative, expected] of Object.entries(module.files)) {
+      if (!safeRelative(relative)) throw new Error('Unsafe module manifest path');
+      const file = path.join(directory, relative);
+      if (fs.lstatSync(file).isSymbolicLink() || hash(fs.readFileSync(file)) !== expected) throw new Error(`Installed module is stale or altered: ${key}/${relative}`);
+    }
+  }
+}
+function pack(sources) {
+  const output = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-module-candidates-'));
+  const manifest = { schema: 'project-knowledge/module-candidates/v1', createdAt: new Date().toISOString(), modules: {} };
+  for (const [key, definition] of Object.entries(definitions)) {
+    const source = path.resolve(sources[key]);
+    const pkg = JSON.parse(fs.readFileSync(path.join(source, 'package.json')));
+    if (pkg.name !== definition.name) throw new Error(`Unexpected source identity: ${key}`);
+    const expectedVersion = JSON.parse(fs.readFileSync(path.join(root, 'package.json'))).dependencies[definition.installName];
+    if (expectedVersion !== pkg.version && expectedVersion !== `npm:${pkg.name}@${pkg.version}`) throw new Error(`Source version is not pinned by the shell: ${key}`);
+    const result = JSON.parse(run(process.execPath, [npmCli, 'pack', '--ignore-scripts', '--json', '--pack-destination', output], source))[0];
+    const files = {};
+    for (const entry of result.files) {
+      if (!safeRelative(entry.path)) throw new Error('Unsafe npm package path');
+      const file = path.join(source, entry.path);
+      if (fs.lstatSync(file).isSymbolicLink()) throw new Error(`Symlink in module package: ${key}/${entry.path}`);
+      files[entry.path] = hash(fs.readFileSync(file));
+    }
+    if (definition.required.some(file => !files[file])) throw new Error(`Incomplete module runtime: ${key}`);
+    manifest.modules[key] = { name: pkg.name, installName: definition.installName, version: pkg.version, tarball: result.filename, sha256: hash(fs.readFileSync(path.join(output, result.filename))), files };
+    process.stdout.write(`Packed ${key} ${pkg.version}: ${result.files.length} files\n`);
+  }
+  const manifestPath = path.join(output, 'module-candidates.json'); AtomicFile.writeJsonAtomic(manifestPath, manifest);
+  const productFiles = Object.fromEntries(['ui/index.html', 'ui/product.js', 'ui/product.css'].map(file => [file, hash(fs.readFileSync(path.join(root, file)))]));
+  AtomicFile.writeJsonAtomic(path.join(root, 'module-runtime-manifest.json'), { schema: 'project-knowledge/module-content/v1', productFiles, modules: Object.fromEntries(Object.entries(manifest.modules).map(([key, module]) => [key, { name: module.name, installName: module.installName, version: module.version, files: module.files }])) });
+  process.stdout.write(`MODULE_CANDIDATES ${manifestPath}\n`);
+  return manifestPath;
+}
+if (require.main === module) {
+  try {
+    const at = process.argv.indexOf('--verify-installed');
+    if (at >= 0) { const manifest = JSON.parse(fs.readFileSync(process.argv[at + 1])); verifyInstalled(manifest, path.resolve(process.argv[at + 2])); process.stdout.write('Installed module bytes verified against candidate artifacts.\n'); }
+    else {
+      const sources = {};
+      for (const [key, d] of Object.entries(definitions)) { const i = process.argv.indexOf(d.option); if (i < 0 || !process.argv[i + 1]) throw new Error(`Explicit source required: ${d.option}`); sources[key] = process.argv[i + 1]; }
+      pack(sources);
+    }
+  } catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }
+}
+module.exports = { verifyInstalled, safeRelative };

package/_site/scripts/sync-release-version.js

@@ -62,9 +62,9 @@ function releaseVersionTargets(rootDir, version) {
       update(value) {
         const args = value && value.mcpServers && value.mcpServers['project-knowledge'] && value.mcpServers['project-knowledge'].args;
         if (!Array.isArray(args)) throw new Error('project-knowledge MCP server has no args array');
-        const index = args.findIndex(arg => /^project-knowledge@/.test(String(arg)));
+        const index = args.findIndex(arg => /^(?:@sanqianx\/)?project-knowledge@/.test(String(arg)));
         if (index < 0) throw new Error('project-knowledge MCP server has no pinned package argument');
-        args[index] = `project-knowledge@${version}`;
+        args[index] = `@sanqianx/project-knowledge@${version}`;
       },
     },
   ].map(target => ({ ...target, path: path.join(rootDir, target.file) }));

package/_site/scripts/vendor-modules.js

@@ -0,0 +1,47 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const AtomicFile = require('../lib/atomic-file');
+
+const root = path.resolve(__dirname, '../..');
+const destination = path.join(root, '_modules', 'knowledge-engine');
+const manifestFile = path.join(root, 'vendor-manifest.json');
+const hash = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+function sources(source) {
+  const files = ['package.json', 'README.md', 'ui/index.html', 'ui/app.js', 'ui/app.css'];
+  function walk(directory) {
+    for (const entry of fs.readdirSync(path.join(source, directory), { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) throw new Error('Symlinks are not accepted in a vendored runtime');
+      const relative = `${directory}/${entry.name}`;
+      if (entry.isDirectory()) walk(relative); else if (entry.isFile()) files.push(relative);
+    }
+  }
+  walk('src'); return files.sort();
+}
+function vendor(source) {
+  source = path.resolve(source);
+  const pkg = JSON.parse(fs.readFileSync(path.join(source, 'package.json')));
+  if (pkg.name !== '@sanqianx/ai-coding-knowledge-engine' || Object.keys(pkg.dependencies || {}).length || Object.keys(pkg.devDependencies || {}).length) throw new Error('The engine must remain a dependency-free runtime');
+  const previous = fs.existsSync(manifestFile) ? JSON.parse(fs.readFileSync(manifestFile)) : { schema: 'project-knowledge/vendor-runtime/v1', modules: {} };
+  const priorFiles = previous.modules['knowledge-engine']?.files || {};
+  const files = {};
+  for (const relative of sources(source)) {
+    const sourceFile = path.join(source, relative), target = path.join(destination, relative);
+    if (fs.lstatSync(sourceFile).isSymbolicLink() || fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink()) throw new Error('Unsafe runtime path');
+    const bytes = fs.readFileSync(sourceFile), digest = hash(bytes);
+    if (fs.existsSync(target)) {
+      const current = hash(fs.readFileSync(target));
+      if (current !== digest && current !== priorFiles[relative]) throw new Error(`Preserving unrecognized local runtime change: ${relative}`);
+    }
+    AtomicFile.writeFileAtomic(target, bytes); files[relative] = digest;
+  }
+  // No broad cleanup: obsolete files remain visible to the verifier until an
+  // explicit reviewed cleanup. Untracked/user changes are never overwritten.
+  previous.modules['knowledge-engine'] = { name: pkg.name, version: pkg.version, root: '_modules/knowledge-engine', files };
+  AtomicFile.writeJsonAtomic(manifestFile, previous);
+  process.stdout.write(`Vendored knowledge-engine ${pkg.version}: ${Object.keys(files).length} runtime files\n`);
+}
+const option = process.argv.indexOf('--engine-source');
+if (option < 0 || !process.argv[option + 1]) { process.stderr.write('Usage: vendor-modules --engine-source <explicit checkout path>\n'); process.exitCode = 1; }
+else vendor(process.argv[option + 1]);

package/_site/scripts/verify-module-runtime.js

@@ -0,0 +1,45 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+const root = path.resolve(__dirname, '../..');
+const workingTree = process.argv.includes('--working-tree');
+function verify() {
+  const manifest = JSON.parse(fs.readFileSync(path.join(root, 'vendor-manifest.json'), 'utf8'));
+  if (manifest.schema !== 'project-knowledge/vendor-runtime/v1') throw new Error('Invalid runtime manifest');
+  const engine = manifest.modules['knowledge-engine'];
+  if (!engine || engine.root !== '_modules/knowledge-engine') throw new Error('Missing engine runtime');
+  const packageInfo = JSON.parse(fs.readFileSync(path.join(root, 'package.json')));
+  for (const dependency of ['claude-ai-workbench', '@sanqianx/vector-hub', '@sanqianx/ai-coding-event-bridge-console']) {
+    if (!/^\d+\.\d+\.\d+$/.test(packageInfo.dependencies[dependency] || '') && !/^npm:@sanqianx\/claude-ai-workbench@\d+\.\d+\.\d+$/.test(packageInfo.dependencies[dependency] || '')) throw new Error(`Module dependency must be pinned: ${dependency}`);
+  }
+  const required = ['package.json', 'src/bin.js', 'src/server.js', 'src/coordinator.js', 'src/analysis-worker.js', 'ui/index.html', 'ui/app.js', 'ui/app.css'];
+  if (required.some(file => !engine.files[file])) throw new Error('Incomplete runtime manifest');
+  const hasGit = fs.existsSync(path.join(root, '.git'));
+  function checkTree(directory, prefix = '') {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const relative = prefix + entry.name;
+      if (entry.isSymbolicLink()) throw new Error(`Unsafe runtime path: ${relative}`);
+      if (entry.isDirectory()) checkTree(path.join(directory, entry.name), relative + '/');
+      else if (!Object.hasOwn(engine.files, relative)) throw new Error(`Unreviewed runtime file: ${relative}`);
+    }
+  }
+  checkTree(path.join(root, engine.root));
+  for (const [relative, expected] of Object.entries(engine.files)) {
+    if (relative.includes('..') || path.isAbsolute(relative)) throw new Error('Unsafe manifest path');
+    const file = path.join(root, engine.root, relative);
+    if (fs.lstatSync(file).isSymbolicLink()) throw new Error('Unsafe vendored symlink');
+    if (crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') !== expected) throw new Error(`Runtime drift: ${relative}`);
+    if (relative.endsWith('.js')) { const syntax = spawnSync(process.execPath, ['--check', file], { windowsHide: true, encoding: 'utf8' }); if (syntax.status !== 0) throw new Error(`Runtime syntax error: ${relative}`); }
+    if (hasGit && !workingTree) {
+      const indexed = spawnSync('git', ['show', `:${engine.root}/${relative}`], { cwd: root, windowsHide: true });
+      if (indexed.status !== 0) throw new Error(`Release blocked: runtime file is not Git tracked: ${relative}`);
+      if (crypto.createHash('sha256').update(indexed.stdout).digest('hex') !== expected) throw new Error(`Release blocked: Git runtime bytes differ from manifest: ${relative}`);
+    }
+  }
+  const enginePackage = JSON.parse(fs.readFileSync(path.join(root, engine.root, 'package.json')));
+  if (enginePackage.version !== engine.version || Object.keys(enginePackage.dependencies || {}).length || Object.keys(enginePackage.devDependencies || {}).length) throw new Error('Engine version/dependency contract failed');
+  process.stdout.write(workingTree ? 'Runtime content verified; uncommitted working tree is not release approval.\n' : 'Vendored runtime release gate passed.\n');
+}
+try { verify(); } catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }

package/_site/scripts/verify-product-runtime.js

@@ -0,0 +1,34 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { createRequire } = require('node:module');
+const { safeRelative } = require('./pack-module-candidates');
+function verifyProductRuntime(coreRoot, resolveFrom = path.join(coreRoot, 'package.json')) {
+  const manifest = JSON.parse(fs.readFileSync(path.join(coreRoot, 'module-runtime-manifest.json')));
+  if (manifest.schema !== 'project-knowledge/module-content/v1' || Object.keys(manifest.modules).length !== 3) throw new Error('Incomplete module content manifest');
+  const resolve = createRequire(resolveFrom);
+  for (const [relative, expected] of Object.entries(manifest.productFiles || {})) {
+    if (!safeRelative(relative) || crypto.createHash('sha256').update(fs.readFileSync(path.join(coreRoot, relative))).digest('hex') !== expected) throw new Error(`Product UI content mismatch: ${relative}`);
+  }
+  const modules = {};
+  for (const [key, module] of Object.entries(manifest.modules)) {
+    const pkgFile = resolve.resolve(`${module.installName}/package.json`);
+    const directory = path.dirname(pkgFile);
+    const pkg = JSON.parse(fs.readFileSync(pkgFile));
+    if (pkg.name !== module.name || pkg.version !== module.version) throw new Error(`Module version mismatch: ${key}`);
+    for (const [relative, expected] of Object.entries(module.files)) {
+      if (!safeRelative(relative) || !/^[a-f0-9]{64}$/.test(expected)) throw new Error('Unsafe module content manifest');
+      const file = path.join(directory, relative);
+      if (fs.lstatSync(file).isSymbolicLink() || crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') !== expected) throw new Error(`Module content mismatch: ${key}/${relative}. Install the tested candidate before packaging.`);
+    }
+    modules[key] = { directory, version: pkg.version };
+  }
+  for (const file of ['ui/index.html', 'ui/product.js', 'ui/product.css', '_modules/knowledge-engine/src/bin.js', '_modules/knowledge-engine/src/coordinator.js']) if (!fs.existsSync(path.join(coreRoot, file))) throw new Error(`Product runtime missing: ${file}`);
+  return modules;
+}
+if (require.main === module) {
+  try { verifyProductRuntime(path.resolve(process.argv[2] || path.join(__dirname, '../..'))); process.stdout.write('All product module versions and contents verified.\n'); }
+  catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }
+}
+module.exports = { verifyProductRuntime };