project-knowledge 1.0.0 → 1.0.1

package/README.md

@@ -60,9 +60,8 @@ Requirements:
 - Git on `PATH`
 - (Optional) [Claude Code CLI](https://docs.claude.com/en/docs/claude-code)
   if you want the Claude adapter (the `mock-agent` adapter works without it)
-- Currently Windows-oriented: the server references Windows paths for the
-  PowerShell commit-doc generator and the safe runner. macOS/Linux work for
-  the dashboard and AI flows but the Git-doc generator needs porting.
+- Windows has the most complete hook/scheduled-task flow. The dashboard,
+  registry, AI profiles, and knowledge-store APIs use install-relative paths.
 
 ## Quick start
 
@@ -71,6 +70,7 @@ Global install:
 ```bash
 npm install -g project-knowledge
 project-knowledge            # starts server on http://localhost:7777
+project-knowledge start --port 9000
 ```
 
 Or run from source:
@@ -88,11 +88,28 @@ Then open <http://localhost:7777>. Override the port with
 ### First-time setup
 
 1. Open the dashboard → **Projects** → register a project (path + slug).
-2. Edit `ai-profiles.json` to pick the AI profile you want (start with
-   `mock-agent` to see the flow without an LLM).
+On first run, v1.0.1 creates missing runtime JSON files automatically. If
+`projects.json` or `ai-profiles.json` is empty or invalid, the server recovers
+with a safe default; invalid JSON is backed up as `*.invalid-<timestamp>.bak`.
+
+2. Open **Settings** / **AI profiles** to add MiniMax / GLM / GPT /
+   Anthropic-compatible models. The npm package ships with a safe mock profile
+   and no API keys.
 3. Run **Scan** → **Initial analysis** → review drafts → **Apply drafts**.
 4. (Optional) **Install hook** so future commits trigger an analysis job.
 
+### Upgrading from v1.0.0
+
+v1.0.0 did not publish a `bin` command, so a global install could complete
+without creating the `project-knowledge` executable. Reinstall v1.0.1:
+
+```bash
+npm uninstall -g project-knowledge
+npm install -g project-knowledge@latest
+project-knowledge --version
+project-knowledge
+```
+
 ## Architecture
 
 ```

package/_site/_test/package-startup-test.js

@@ -0,0 +1,108 @@
+// Run: node _site/_test/package-startup-test.js
+const fs = require('fs');
+const path = require('path');
+const { spawn, spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const BIN = path.join(ROOT, 'bin', 'project-knowledge.js');
+const PROJECTS_JSON = path.join(ROOT, 'projects.json');
+const PORT = process.env.KB_PACKAGE_TEST_PORT || '7825';
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+
+function assert(cond, msg) { if (!cond) throw new Error(msg); }
+
+function backup(file) {
+  return fs.existsSync(file) ? fs.readFileSync(file, 'utf-8') : null;
+}
+
+function restore(file, content) {
+  if (content == null) fs.rmSync(file, { force: true });
+  else fs.writeFileSync(file, content, 'utf-8');
+}
+
+async function waitForServer() {
+  const deadline = Date.now() + 15000;
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${BASE_URL}/api/state`);
+      if (res.ok) return res.json();
+      lastError = new Error(`HTTP ${res.status}`);
+    } catch (e) { lastError = e; }
+    await new Promise(resolve => setTimeout(resolve, 250));
+  }
+  throw lastError || new Error('server did not start');
+}
+
+async function stop(child) {
+  if (!child || child.killed) return;
+  child.kill('SIGTERM');
+  await new Promise(resolve => setTimeout(resolve, 250));
+  if (!child.killed) child.kill('SIGKILL');
+}
+
+async function withServer(fn) {
+  const child = spawn(process.execPath, [BIN, 'start', '--port', PORT, '--host', '127.0.0.1'], {
+    cwd: ROOT,
+    env: { ...process.env },
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+  });
+  let output = '';
+  child.stdout.on('data', d => { output += d.toString(); });
+  child.stderr.on('data', d => { output += d.toString(); });
+  try {
+    const state = await waitForServer();
+    await fn(state, output);
+  } finally {
+    await stop(child);
+  }
+}
+
+(async () => {
+  const originalProjects = backup(PROJECTS_JSON);
+  const originalInvalidBackups = new Set(
+    fs.readdirSync(ROOT).filter(name => name.startsWith('projects.json.invalid-') && name.endsWith('.bak'))
+  );
+
+  try {
+    const version = spawnSync(process.execPath, [BIN, '--version'], { cwd: ROOT, encoding: 'utf-8' });
+    assert(version.status === 0, '--version should exit successfully');
+    assert(version.stdout.trim() === require(path.join(ROOT, 'package.json')).version, '--version should match package version');
+
+    fs.rmSync(PROJECTS_JSON, { force: true });
+    await withServer(async (state) => {
+      assert(state && state.projects && typeof state.projects === 'object', 'missing projects.json should still return projects object');
+      assert(fs.existsSync(PROJECTS_JSON), 'missing projects.json should be created on first API read');
+      assert(fs.readFileSync(PROJECTS_JSON, 'utf-8').trim() === '{}', 'missing projects.json should initialize to {}');
+    });
+
+    fs.writeFileSync(PROJECTS_JSON, '', 'utf-8');
+    await withServer(async (state) => {
+      assert(state && state.projects && typeof state.projects === 'object', 'empty projects.json should still return projects object');
+      assert(fs.readFileSync(PROJECTS_JSON, 'utf-8').trim() === '{}', 'empty projects.json should be normalized to {}');
+    });
+
+    fs.writeFileSync(PROJECTS_JSON, '{', 'utf-8');
+    await withServer(async (state) => {
+      assert(state && state.projects && typeof state.projects === 'object', 'invalid projects.json should still return projects object');
+      assert(fs.readFileSync(PROJECTS_JSON, 'utf-8').trim() === '{}', 'invalid projects.json should be replaced with {}');
+      const newBackups = fs.readdirSync(ROOT)
+        .filter(name => name.startsWith('projects.json.invalid-') && name.endsWith('.bak'))
+        .filter(name => !originalInvalidBackups.has(name));
+      assert(newBackups.length >= 1, 'invalid projects.json should be backed up before recovery');
+    });
+
+    console.log('package-startup-test PASS');
+  } finally {
+    restore(PROJECTS_JSON, originalProjects);
+    for (const name of fs.readdirSync(ROOT)) {
+      if (name.startsWith('projects.json.invalid-') && name.endsWith('.bak') && !originalInvalidBackups.has(name)) {
+        fs.rmSync(path.join(ROOT, name), { force: true });
+      }
+    }
+  }
+})().catch(err => {
+  console.error(err && err.stack || err);
+  process.exit(1);
+});

package/_site/lib/job-orchestrator.js

@@ -35,7 +35,8 @@ const { spawn } = require('child_process');
 const { scanProject, applyScanResult } = require('./scanner');
 const { runInitialAnalysis, runCommitAnalysis } = require('./analysis-orchestrator');
 
-const LEGACY_SCRIPT = 'D:\\SanQian.Xu\\project-knowledge-base\\scripts\\gen-commit-doc.ps1';
+const APP_ROOT = path.resolve(__dirname, '..', '..');
+const LEGACY_SCRIPT = path.join(APP_ROOT, 'scripts', 'gen-commit-doc.ps1');
 
 const KNOWN_MODES = new Set(['legacy', 'scan', 'analyze-initial', 'analyze-commits', 'safe']);
 
@@ -90,7 +91,7 @@ function projectList(projects, slug) {
 }
 
 function legacyDefaultProjectKbPath(slug) {
-  return path.join('D:\\SanQian.Xu\\project-knowledge-base', 'projects', slug);
+  return path.join(APP_ROOT, 'projects', slug);
 }
 
 async function runScan(projects, slug, job) {

package/_site/server.js

@@ -29,11 +29,12 @@ const SITE_ROOT = __dirname;
 const PORT = parseInt(process.env.KB_SITE_PORT || '7777', 10);
 const HOST = process.env.KB_SITE_HOST || '127.0.0.1';
 const TASK_NAME = 'KB-GitCommits-Daily';
-const SCRIPT = 'D:\\SanQian.Xu\\project-knowledge-base\\scripts\\gen-commit-doc.ps1';
-const SAFE_RUNNER = 'D:\\SanQian.Xu\\project-knowledge-base\\_site\\scripts\\safe-runner.js';
+const SCRIPT = path.join(KB_ROOT, 'scripts', 'gen-commit-doc.ps1');
+const SAFE_RUNNER = path.join(SITE_ROOT, 'scripts', 'safe-runner.js');
 const PROJECT_SCHEMA_VERSION = 'v3';
 const DEFAULT_AI_PROFILE_ID = 'mock-agent';
 const DEFAULT_KNOWLEDGE_LANGUAGE = 'zh-CN';
+const PROJECTS_PATH = path.join(KB_ROOT, 'projects.json');
 const AI_PROFILES_PATH = path.join(KB_ROOT, 'ai-profiles.json');
 const JOBS_LOG_PATH = path.join(KB_ROOT, '.jobs-log.json');
 const KNOWLEDGE_STORE_PATH = path.join(KB_ROOT, 'knowledge-store.json');
@@ -46,7 +47,7 @@ const runningJobs = new Map();
 // Read a fresh copy of projects.json (re-loaded on every dispatch so that
 // background jobs see the latest registry state).
 function readProjectsForJob() {
-  return JSON.parse(fs.readFileSync(path.join(KB_ROOT, 'projects.json'), 'utf-8'));
+  return readProjects({ persistMigrations: true });
 }
 
 // ---- helpers ----
@@ -77,9 +78,43 @@ function readJson(p) {
 }
 
 function writeJson(p, obj) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
   fs.writeFileSync(p, JSON.stringify(obj, null, 2) + '\n', 'utf-8');
 }
 
+function backupInvalidJson(filePath, raw) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = `${filePath}.invalid-${stamp}.bak`;
+  try {
+    fs.writeFileSync(backupPath, raw, 'utf-8');
+  } catch {}
+  return backupPath;
+}
+
+function readJsonOrDefault(filePath, defaultValue, options = {}) {
+  const { persistDefault = true, backupInvalid = true } = options;
+  let raw = '';
+  try {
+    raw = fs.readFileSync(filePath, 'utf-8');
+  } catch (error) {
+    if (error && error.code !== 'ENOENT') throw error;
+    if (persistDefault) writeJson(filePath, defaultValue);
+    return defaultValue;
+  }
+  if (!raw.trim()) {
+    if (persistDefault) writeJson(filePath, defaultValue);
+    return defaultValue;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    const backupPath = backupInvalid ? backupInvalidJson(filePath, raw) : '';
+    if (persistDefault) writeJson(filePath, defaultValue);
+    console.warn(`[project-knowledge] Recovered invalid JSON at ${filePath}${backupPath ? `; backup: ${backupPath}` : ''}`);
+    return defaultValue;
+  }
+}
+
 function isSafeSlug(s) { return typeof s === 'string' && /^[a-z0-9][a-z0-9-]{0,40}$/.test(s); }
 
 function normalizeKnowledgeLanguage(value) {
@@ -118,9 +153,8 @@ function isLegacyKbPath(value) {
 }
 
 // ---- AI profiles (TASK-005) ----
-function readAiProfiles() {
-  if (!fs.existsSync(AI_PROFILES_PATH)) {
-    return { schema: 'ai-profiles/v1', defaultProfileId: DEFAULT_AI_PROFILE_ID, profiles: listAdapters().map(a => ({
+function defaultAiProfilesConfig() {
+  return { schema: 'ai-profiles/v1', defaultProfileId: DEFAULT_AI_PROFILE_ID, profiles: listAdapters().map(a => ({
       id: a.id,
       name: a.name,
       description: a.description,
@@ -136,8 +170,13 @@ function readAiProfiles() {
         timeoutMs: 300000,
       } : {}),
     })) };
-  }
-  return JSON.parse(fs.readFileSync(AI_PROFILES_PATH, 'utf-8'));
+}
+
+function readAiProfiles() {
+  return readJsonOrDefault(AI_PROFILES_PATH, defaultAiProfilesConfig(), {
+    persistDefault: true,
+    backupInvalid: true,
+  });
 }
 
 function writeAiProfiles(cfg) {
@@ -242,11 +281,13 @@ function normalizeProjects(rawProjects) {
 }
 
 function readProjects(options = {}) {
-  const projectsPath = path.join(KB_ROOT, 'projects.json');
-  const rawProjects = readJson(projectsPath);
+  const rawProjects = readJsonOrDefault(PROJECTS_PATH, {}, {
+    persistDefault: true,
+    backupInvalid: true,
+  });
   const result = normalizeProjects(rawProjects);
   if (options.persistMigrations && result.changed) {
-    writeJson(projectsPath, result.projects);
+    writeJson(PROJECTS_PATH, result.projects);
   }
   return result.projects;
 }

package/ai-profiles.json

@@ -1,20 +1,28 @@
 {
   "schema": "ai-profiles/v1",
-  "defaultProfileId": "minimax-m3",
+  "defaultProfileId": "mock-agent",
   "profiles": [
     {
-      "id": "minimax-m3",
-      "name": "MiniMax M3",
+      "id": "mock-agent",
+      "name": "Mock Agent",
+      "description": "Local deterministic adapter for smoke tests and first-run verification.",
       "enabled": true,
+      "implementation": "mock-agent"
+    },
+    {
+      "id": "claude-code-agent",
+      "name": "Claude Code Agent",
+      "description": "Runs Claude Code or an Anthropic-compatible endpoint with the configured model.",
+      "enabled": false,
       "implementation": "claude-code-agent",
-      "baseUrl": "https://api.minimaxi.com/anthropic",
-      "apiKey": "sk-cp-q4xMs0h5OQ-gCHnKi6P_9I8IkBVLUuWvs0v1J0t7CH7m8hgq6jvshtPsjQ3X00Ula-_M7jRQYKWvsKyZT3BECNgWRx9CcWAIY_aMyaJ5XAtf87uS_s1XaXU",
-      "apiKeyEnv": "",
-      "model": "MiniMax-M3",
+      "baseUrl": "https://api.anthropic.com",
+      "apiKey": "",
+      "apiKeyEnv": "ANTHROPIC_AUTH_TOKEN",
+      "model": "claude-haiku-4-5",
       "version": "2023-06-01",
-      "temperature": 0,
+      "temperature": 0.2,
       "maxTokens": 4096,
-      "timeoutMs": 3000000
+      "timeoutMs": 300000
     }
   ]
 }

package/bin/project-knowledge.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const pkg = require('../package.json');
+
+function printHelp() {
+  console.log(`project-knowledge ${pkg.version}
+
+Usage:
+  project-knowledge [start] [--host 127.0.0.1] [--port 7777]
+  project-knowledge --version
+  project-knowledge --help
+
+Starts the local Project Knowledge dashboard.`);
+}
+
+function takeFlag(args, longName, shortName) {
+  const index = args.findIndex(item => item === longName || item === shortName);
+  if (index === -1) return '';
+  const value = args[index + 1] || '';
+  args.splice(index, value ? 2 : 1);
+  return value;
+}
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+  printHelp();
+  process.exit(0);
+}
+if (args.includes('--version') || args.includes('-v')) {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+let command = 'start';
+if (args[0] && !args[0].startsWith('-')) {
+  command = args.shift();
+}
+
+if (command !== 'start' && command !== 'serve') {
+  console.error(`Unknown command: ${command}`);
+  printHelp();
+  process.exit(1);
+}
+
+const port = takeFlag(args, '--port', '-p');
+const host = takeFlag(args, '--host', '-H');
+if (port) process.env.KB_SITE_PORT = port;
+if (host) process.env.KB_SITE_HOST = host;
+
+require(path.join(__dirname, '..', '_site', 'server.js'));

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "project-knowledge",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Knowledge base manager with Git integration, AI-driven analysis, and bilingual (zh-CN/en-US) knowledge output",
   "main": "_site/server.js",
   "scripts": {
     "start": "node _site/server.js",
     "test": "node _site/_test/run-all-tests.js"
   },
+  "bin": {
+    "project-knowledge": "bin/project-knowledge.js"
+  },
   "engines": {
     "node": ">=18"
   },
@@ -20,6 +23,7 @@
     "_site/_test/fixtures/",
     "_site/start.bat",
     "_site/stop.bat",
+    "bin/",
     "templates/",
     "scripts/",
     "ai-profiles.json",

package/scripts/gen-commit-doc.ps1

@@ -5,7 +5,7 @@
 param(
     [Parameter(Mandatory = $true)]
     [string] $ProjectSlug,
-    [string] $KbRoot = "D:\SanQian.Xu\project-knowledge-base",
+    [string] $KbRoot = (Split-Path -Parent $PSScriptRoot),
     [int] $MaxCommits = 0
 )
 

package/scripts/list-features.ps1

@@ -7,7 +7,7 @@ param(
     [string] $ProjectSlug,
     [ValidateSet("time", "count")]
     [string] $SortBy = "time",
-    [string] $KbRoot = "D:\SanQian.Xu\project-knowledge-base"
+    [string] $KbRoot = (Split-Path -Parent $PSScriptRoot)
 )
 
 $commitsDir = Join-Path $KbRoot "projects\$ProjectSlug\commits"

package/scripts/register-scheduled-task.bat

@@ -1,5 +1,7 @@
 @echo off
-schtasks /create /tn KB-GitCommits-Daily /tr "powershell -ExecutionPolicy Bypass -File D:\SanQian.Xu\project-knowledge-base\scripts\gen-commit-doc.ps1 -ProjectSlug ALL" /sc daily /st 08:00 /f
+@echo off
+set "KB_ROOT=%~dp0.."
+schtasks /create /tn KB-GitCommits-Daily /tr "powershell -ExecutionPolicy Bypass -File \"%KB_ROOT%\scripts\gen-commit-doc.ps1\" -ProjectSlug ALL" /sc daily /st 08:00 /f
 echo Done.
 schtasks /query /tn KB-GitCommits-Daily
 pause