@sanqianx/project-knowledge 4.6.1

package/_site/scripts/folder-picker.ps1

@@ -0,0 +1,156 @@
+# folder-picker.ps1 — modern folder picker for project-knowledge import dialog.
+# Uses the Vista+ IFileOpenDialog COM API (the same dialog VS Code / modern
+# Windows apps show) with the default initial folder set to "This PC".
+#
+# Reads title from $args[0]. Prints the selected absolute path to stdout, or
+# prints nothing if the user cancelled. Exits 0 in both cases.
+#
+# STA apartment + -WindowStyle Hidden is required by the caller; this script
+# assumes the host process has set those flags.
+
+param([string]$Title = 'Select folder')
+
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+
+$src = @'
+using System;
+using System.ComponentModel;
+using System.Linq;
+using System.Runtime.InteropServices;
+
+[Flags]
+public enum FOS : uint {
+  PICKFOLDERS     = 0x00000020,
+  FORCEFILESYSTEM = 0x00000040,
+  NOCHANGEDIR     = 0x00000008
+}
+
+[ComImport, Guid("d57c7288-d4ad-4768-be02-9d969532d960"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+public interface IFileOpenDialog {
+  [PreserveSig] int Show(IntPtr hwndOwner);
+  [PreserveSig] int SetFileTypes(uint cFileTypes, IntPtr rgFilterSpec);
+  [PreserveSig] int SetFileTypeIndex(uint iFileType);
+  [PreserveSig] int GetFileTypeIndex(out uint piFileType);
+  [PreserveSig] int Advise(IntPtr pfde, out uint pdwCookie);
+  [PreserveSig] int Unadvise(uint dwCookie);
+  [PreserveSig] int SetOptions(FOS fos);
+  [PreserveSig] int GetOptions(out FOS pfos);
+  [PreserveSig] int SetDefaultFolder(IntPtr psi);
+  [PreserveSig] int SetFolder(IntPtr psi);
+  [PreserveSig] int GetFolder(out IntPtr ppsi);
+  [PreserveSig] int GetCurrentSelection(out IntPtr ppsi);
+  [PreserveSig] int SetFileName([MarshalAs(UnmanagedType.LPWStr)] string pszName);
+  [PreserveSig] int GetFileName([MarshalAs(UnmanagedType.LPWStr)] out string pszName);
+  [PreserveSig] int SetTitle([MarshalAs(UnmanagedType.LPWStr)] string pszTitle);
+  [PreserveSig] int SetOkButtonLabel([MarshalAs(UnmanagedType.LPWStr)] string pszText);
+  [PreserveSig] int SetFileNameLabel([MarshalAs(UnmanagedType.LPWStr)] string pszLabel);
+  [PreserveSig] int GetResult(out IntPtr ppsi);
+  [PreserveSig] int AddPlace(IntPtr psi, int fdap);
+  [PreserveSig] int SetDefaultExtension([MarshalAs(UnmanagedType.LPWStr)] string pszDefaultExtension);
+  [PreserveSig] int Close(int hr);
+  [PreserveSig] int SetClientGuid(ref Guid guid);
+  [PreserveSig] int ClearClientData();
+  [PreserveSig] int SetFilter(IntPtr pFilter);
+  [PreserveSig] int GetResults(out IntPtr ppenum);
+  [PreserveSig] int GetSelectedItems(out IntPtr ppsai);
+}
+
+public static class Shell32 {
+  [DllImport("shell32.dll", CharSet = CharSet.Unicode, ExactSpelling = true, PreserveSig = true)]
+  public static extern int SHCreateItemFromParsingName(
+    [MarshalAs(UnmanagedType.LPWStr)] string pszPath,
+    IntPtr pbc,
+    [MarshalAs(UnmanagedType.LPStruct)] Guid riid,
+    out IntPtr ppv);
+
+  [DllImport("ole32.dll", PreserveSig = true)]
+  public static extern int CoCreateInstance(
+    ref Guid rclsid, IntPtr pUnkOuter, uint dwClsContext, ref Guid riid, out IntPtr ppv);
+}
+
+public static class User32 {
+  [DllImport("user32.dll")]
+  public static extern IntPtr GetForegroundWindow();
+}
+
+public static class FolderPicker {
+  public static string Pick(string title) {
+    Guid clsid = new Guid("DC1C5A9C-E88A-4DDE-A5A1-60F82A20AEF7");
+    Guid iid   = new Guid("d57c7288-d4ad-4768-be02-9d969532d960");
+    IntPtr pIfod = IntPtr.Zero;
+    IntPtr pItem = IntPtr.Zero;
+    IntPtr pResult = IntPtr.Zero;
+
+    try {
+      int hr = Shell32.CoCreateInstance(ref clsid, IntPtr.Zero, 0x1, ref iid, out pIfod);
+      if (hr != 0) throw new Win32Exception(hr);
+
+      IFileOpenDialog dialog = (IFileOpenDialog)Marshal.GetTypedObjectForIUnknown(pIfod, typeof(IFileOpenDialog));
+
+      FOS opts = FOS.PICKFOLDERS | FOS.FORCEFILESYSTEM | FOS.NOCHANGEDIR;
+      hr = dialog.SetOptions(opts);
+      if (hr != 0) throw new Win32Exception(hr);
+
+      // On Win11 with system ANSI codepage set (e.g. 936 GBK) the Fluent
+// title-bar chrome can garble CJK even though the dialog stores the title
+// correctly in Unicode (taskbar preview is correct via the Unicode path).
+// Use an ASCII title to keep the chrome legible; the import button's
+// surrounding UI (Chinese) tells the user what the picker is for.
+string safeTitle = title.All(c => c < 128) ? title : "Select Project Folder";
+hr = dialog.SetTitle(safeTitle);
+if (hr != 0) throw new Win32Exception(hr);
+
+      // Initial folder = This PC (FOLDERID_ComputerFolder)
+      Guid iidShellItem = new Guid("43826d1e-e718-42ee-bc55-a1e261c37bfe");
+      hr = Shell32.SHCreateItemFromParsingName(
+        "::{20D04FE0-3AEA-1069-A2D8-08002B30309D}",
+        IntPtr.Zero, iidShellItem, out pItem);
+      if (hr != 0) throw new Win32Exception(hr);
+      hr = dialog.SetFolder(pItem);
+      if (hr != 0) throw new Win32Exception(hr);
+
+      // Pass the current foreground window as owner so the dialog is parented
+      // to it (positioned on top, modal to it). Without an owner, the dialog
+      // has no z-order anchor and on Windows 11 ends up hidden behind the
+      // browser window that initiated the call.
+      IntPtr owner = User32.GetForegroundWindow();
+      hr = dialog.Show(owner);
+      // 0 = OK, 0x800704C7 = ERROR_CANCELLED, others = error
+      if (hr != 0) return null;
+
+      hr = dialog.GetResult(out pResult);
+      if (hr != 0 || pResult == IntPtr.Zero) return null;
+
+      // IShellItem vtable index 5 = GetDisplayName(SIGDN, LPWSTR*)
+      IntPtr vtable = Marshal.ReadIntPtr(pResult);
+      IntPtr getDisplayNameFn = Marshal.ReadIntPtr(vtable, 5 * IntPtr.Size);
+      GetDisplayNameDelegate del = (GetDisplayNameDelegate)Marshal.GetDelegateForFunctionPointer(
+        getDisplayNameFn, typeof(GetDisplayNameDelegate));
+
+      IntPtr strPtr = IntPtr.Zero;
+      int ghr = del(pResult, 0x80058000u, out strPtr);  // SIGDN_FILESYSPATH
+      if (ghr != 0 || strPtr == IntPtr.Zero) return null;
+
+      string path = Marshal.PtrToStringUni(strPtr);
+      Marshal.FreeCoTaskMem(strPtr);
+      return path;
+    } finally {
+      if (pResult != IntPtr.Zero) Marshal.Release(pResult);
+      if (pItem != IntPtr.Zero) Marshal.Release(pItem);
+      if (pIfod != IntPtr.Zero) Marshal.Release(pIfod);
+    }
+  }
+
+  [UnmanagedFunctionPointer(CallingConvention.StdCall)]
+  private delegate int GetDisplayNameDelegate(IntPtr pThis, uint sigdn, out IntPtr ppszName);
+}
+'@
+
+Add-Type -TypeDefinition $src -Language CSharp | Out-Null
+
+$path = [FolderPicker]::Pick($Title)
+if ($null -ne $path -and $path.Length -gt 0) {
+  Write-Output $path
+}
+exit 0

package/_site/scripts/hook-trigger.js

@@ -0,0 +1,156 @@
+const http = require('http');
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { getDataDir } = require('../lib/data-dir');
+const { readLiveEndpoint } = require('../lib/runtime-endpoint');
+const { StorageLayout } = require('../lib/storage-layout');
+const { Logger } = require('../lib/structured-logger');
+const { BridgeAdapter } = require('../lib/bridge-adapter');
+
+let bridgeIdentityModule = null;
+try {
+  const bridgePackage = require('@sanqianx/ai-coding-event-bridge');
+  if (bridgePackage && typeof bridgePackage.buildRepoIdentityV1 === 'function') bridgeIdentityModule = bridgePackage;
+} catch (_) {
+  bridgeIdentityModule = null;
+}
+
+const args = process.argv.slice(2);
+function arg(name, fallback = '') {
+  const index = args.indexOf(name);
+  return index >= 0 ? (args[index + 1] || fallback) : fallback;
+}
+
+const projectId = arg('--project-id', '');
+const repoRoot = arg('--repo-root', arg('--repo', ''));
+const fallbackHost = arg('--host', '127.0.0.1');
+const fallbackPort = Number(arg('--port', process.env.KB_SITE_PORT || '5757'));
+const dataDir = getDataDir();
+const layout = new StorageLayout({ dataDir });
+const logger = new Logger({
+  layout,
+  settingsProvider: () => ({ levels: ['trace', 'debug', 'info', 'warn', 'error', 'fatal'] }),
+  context: { component: 'git-hook', projectId },
+});
+const bridge = new BridgeAdapter({ dataDir, modulePath: arg('--bridge-module', '') });
+const timeoutMs = 2000;
+
+function git(gitArgs, fallback = '') {
+  if (!repoRoot) return fallback;
+  try {
+    return execFileSync('git', ['-C', repoRoot, ...gitArgs], {
+      encoding: 'utf8', windowsHide: true, timeout: timeoutMs,
+      stdio: ['ignore', 'pipe', 'ignore'], env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    }).trim();
+  } catch { return fallback; }
+}
+
+function target() {
+  const endpoint = readLiveEndpoint(dataDir);
+  return endpoint ? { host: endpoint.host, port: endpoint.port } : { host: fallbackHost, port: fallbackPort };
+}
+
+function post(body) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const endpoint = target();
+    const request = http.request({
+      host: endpoint.host,
+      port: endpoint.port,
+      method: 'POST',
+      path: '/api/hooks/post-commit',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+      timeout: timeoutMs,
+    }, response => {
+      response.resume();
+      response.on('end', () => resolve(response.statusCode || 0));
+    });
+    request.on('error', reject);
+    request.on('timeout', () => request.destroy(new Error('hook notification timeout')));
+    request.end(payload);
+  });
+}
+
+(async () => {
+  try {
+    if (!projectId || !repoRoot) {
+      await logger.warn('hook.notification.skipped', 'Hook payload is missing project identity or repository root.', { phase: 'validate' });
+      return;
+    }
+    const payload = {
+      schema: 'hook-event/v2',
+      projectId,
+      repoRoot,
+      head: git(['rev-parse', 'HEAD']),
+      branch: git(['branch', '--show-current']),
+    };
+    const operationId = arg('--operation-id', `op-${crypto.randomUUID()}`);
+    // Canonical repo-identity/v1 from the authoritative Git working tree.
+    // The old { commonDir }-only shape must never reach the Bridge again.
+    let repoIdentity = null;
+    if (bridgeIdentityModule) {
+      const toplevel = git(['rev-parse', '--show-toplevel']);
+      if (toplevel) {
+        let workspaceRoot = path.resolve(toplevel);
+        try { workspaceRoot = fs.realpathSync.native(workspaceRoot) || workspaceRoot; } catch { workspaceRoot = path.resolve(toplevel); }
+        const commonDir = git(['rev-parse', '--path-format=absolute', '--git-common-dir']);
+        const remoteRaw = git(['config', '--get', 'remote.origin.url']);
+        repoIdentity = bridgeIdentityModule.buildRepoIdentityV1({
+          workspaceRoot,
+          commonDir: commonDir ? path.resolve(commonDir) : null,
+          remote: remoteRaw ? bridgeIdentityModule.normalizeGitUrl(remoteRaw) : null,
+        });
+      }
+    }
+    const boundaryResult = await bridge.appendCommitBoundary({
+      projectId,
+      repoIdentity,
+      commitSha: payload.head,
+      parentShas: git(['show', '-s', '--format=%P', 'HEAD']).split(/\s+/).filter(Boolean),
+      branch: payload.branch || null,
+      committedAt: git(['show', '-s', '--format=%cI', 'HEAD']) || new Date().toISOString(),
+      operationId,
+    });
+    payload.operationId = operationId;
+    payload.boundary = boundaryResult;
+    if (boundaryResult.status === 'captured') {
+      await logger.debug('hook.boundary.captured', 'Commit conversation boundary was durably captured.', {
+        operationId,
+        phase: 'boundary',
+        commitSha: payload.head,
+        context: {
+          bridgeCursorAtCommit: boundaryResult.boundary.bridgeCursorAtCommit,
+          openTurnCount: boundaryResult.boundary.openTurnIdsAtCommit.length,
+        },
+      });
+    } else {
+      await logger.warn('hook.boundary.unavailable', 'Commit conversation boundary could not be captured.', {
+        operationId,
+        phase: 'boundary',
+        commitSha: payload.head,
+        context: { gapId: boundaryResult.gap && boundaryResult.gap.gapId, reason: boundaryResult.gap && boundaryResult.gap.reason },
+      });
+    }
+    try {
+      const status = await post(payload);
+      if (status < 200 || status >= 300) {
+        await logger.warn('hook.notification.failed', 'Knowledge service rejected the Hook notification.', { phase: 'notify', context: { status } });
+      } else {
+        await logger.debug('hook.notification.completed', 'Hook notification delivered.', { phase: 'notify' });
+      }
+    } catch (error) {
+      await logger.warn('hook.notification.degraded', 'Knowledge service is unavailable; this commit was not submitted for knowledge analysis.', { phase: 'notify', error });
+    }
+  } catch (error) {
+    await logger.error('hook.script.failed', 'Hook trigger failed.', { phase: 'runtime', error });
+  } finally {
+    await logger.close();
+  }
+})().then(() => process.exit(0), async error => {
+  try { await logger.error('hook.script.failed', 'Hook trigger failed unexpectedly.', { error }); await logger.close(); } catch {
+    // Hook execution must always exit zero even when logging is unavailable.
+  }
+  process.exit(0);
+});

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

@@ -0,0 +1,158 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function writeJson(filePath, value) {
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function packageVersion(rootDir) {
+  const version = String(readJson(path.join(rootDir, 'package.json')).version || '').trim();
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version)) {
+    throw new Error(`package.json must contain a SemVer version, received: ${version || '(empty)'}`);
+  }
+  return version;
+}
+
+function releaseVersionTargets(rootDir, version) {
+  return [
+    {
+      file: 'package-lock.json',
+      update(value) {
+        value.version = version;
+        if (!value.packages || !value.packages['']) throw new Error('package-lock.json has no root package entry');
+        value.packages[''].version = version;
+      },
+    },
+    {
+      file: 'desktop/package.json',
+      update(value) { value.version = version; },
+    },
+    {
+      file: 'desktop/package-lock.json',
+      update(value) {
+        value.version = version;
+        if (!value.packages || !value.packages['']) throw new Error('desktop/package-lock.json has no root package entry');
+        value.packages[''].version = version;
+      },
+    },
+    {
+      file: 'plugins/project-knowledge/.claude-plugin/plugin.json',
+      update(value) { value.version = version; },
+    },
+    {
+      file: 'plugins/project-knowledge/.codex-plugin/plugin.json',
+      update(value) { value.version = version; },
+    },
+    {
+      file: '.claude-plugin/marketplace.json',
+      update(value) {
+        if (!Array.isArray(value.plugins) || !value.plugins[0]) throw new Error('Claude marketplace has no project plugin');
+        value.plugins[0].version = version;
+      },
+    },
+    {
+      file: 'plugins/project-knowledge/.mcp.json',
+      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)));
+        if (index < 0) throw new Error('project-knowledge MCP server has no pinned package argument');
+        args[index] = `project-knowledge@${version}`;
+      },
+    },
+  ].map(target => ({ ...target, path: path.join(rootDir, target.file) }));
+}
+
+function inspectReleaseVersion(rootDir) {
+  const version = packageVersion(rootDir);
+  const drift = [];
+  for (const target of releaseVersionTargets(rootDir, version)) {
+    const before = fs.readFileSync(target.path, 'utf8');
+    const value = JSON.parse(before);
+    target.update(value);
+    const after = `${JSON.stringify(value, null, 2)}\n`;
+    if (before.replace(/\r\n/g, '\n') !== after) drift.push(target.file);
+  }
+  return { version, drift };
+}
+
+function syncReleaseVersion(rootDir) {
+  const version = packageVersion(rootDir);
+  const changed = [];
+  for (const target of releaseVersionTargets(rootDir, version)) {
+    const before = fs.readFileSync(target.path, 'utf8');
+    const value = JSON.parse(before);
+    target.update(value);
+    const after = `${JSON.stringify(value, null, 2)}\n`;
+    if (before.replace(/\r\n/g, '\n') === after) continue;
+    writeJson(target.path, value);
+    changed.push(target.file);
+  }
+  return { version, changed };
+}
+
+function stageReleaseVersionFiles(rootDir, files) {
+  if (!files.length) return;
+  const result = spawnSync('git', ['-C', rootDir, 'add', '--', ...files], {
+    encoding: 'utf8',
+    windowsHide: true,
+  });
+  if (result.status !== 0) {
+    throw new Error(`failed to stage synchronized release files: ${(result.stderr || result.stdout || '').trim()}`);
+  }
+}
+
+function parseArgs(argv) {
+  let rootDir = path.resolve(__dirname, '..', '..');
+  let check = false;
+  let tag = null;
+  let stage = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--check') check = true;
+    else if (arg === '--stage') stage = true;
+    else if (arg === '--root') rootDir = path.resolve(argv[++index] || '');
+    else if (arg === '--tag') tag = String(argv[++index] || '').trim();
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+  return { rootDir, check, tag, stage };
+}
+
+function main(argv = process.argv.slice(2)) {
+  const { rootDir, check, tag, stage } = parseArgs(argv);
+  if (check) {
+    const result = inspectReleaseVersion(rootDir);
+    if (result.drift.length) {
+      throw new Error(`Release version ${result.version} is out of sync: ${result.drift.join(', ')}`);
+    }
+    if (tag && tag !== `v${result.version}`) {
+      throw new Error(`Release tag ${tag} must match package version v${result.version}`);
+    }
+    console.log(`release version ${result.version} is synchronized`);
+    return result;
+  }
+  const result = syncReleaseVersion(rootDir);
+  if (stage) stageReleaseVersionFiles(rootDir, result.changed);
+  console.log(result.changed.length
+    ? `${stage ? 'synchronized and staged' : 'synchronized'} release version ${result.version}: ${result.changed.join(', ')}`
+    : `release version ${result.version} is already synchronized`);
+  return result;
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`release version synchronization failed: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = { inspectReleaseVersion, main, releaseVersionTargets, stageReleaseVersionFiles, syncReleaseVersion };

package/_site/server.js

@@ -0,0 +1,12 @@
+// Project Knowledge v2 HTTP entry point.
+const { startServer, installProcessHandlers } = require('./lib/server-app');
+
+const instancePromise = startServer();
+installProcessHandlers(instancePromise);
+
+instancePromise.then(instance => {
+  process.stdout.write(`Project Knowledge listening on http://${instance.host}:${instance.port}\n`);
+}).catch(error => {
+  process.stderr.write(`[project-knowledge] startup failed: ${String(error && error.message || error)}\n`);
+  process.exitCode = 1;
+});

package/_site/start.bat

@@ -0,0 +1,26 @@
+@echo off
+setlocal
+
+REM KB Management Site launcher — double-click to start
+set KB_SITE=%~dp0
+set PORT=5757
+
+REM Check if already running
+netstat -ano | findstr ":%PORT% " | findstr "LISTENING" >nul 2>&1
+if %ERRORLEVEL%==0 (
+  echo [kb-site] Already running on port %PORT%. Opening browser...
+  start "" "http://localhost:%PORT%/"
+  goto :eof
+)
+
+echo [kb-site] Starting server on port %PORT%...
+start "KB-Site" /min cmd /c "cd /d "%KB_SITE%" && node server.js"
+timeout /t 2 /nobreak >nul
+
+REM Open browser
+start "" "http://localhost:%PORT%/"
+
+echo.
+echo [kb-site] Server started. To stop: close the "KB-Site" window, or run stop.bat
+echo.
+pause

package/_site/stop.bat

@@ -0,0 +1,11 @@
+@echo off
+setlocal
+set PORT=5757
+
+echo [kb-site] Stopping server on port %PORT%...
+for /f "tokens=5" %%P in ('netstat -ano ^| findstr ":%PORT% " ^| findstr "LISTENING"') do (
+  taskkill /F /PID %%P >nul 2>&1
+  echo [kb-site] Killed PID %%P
+)
+echo Done.
+pause