pi-para 0.5.5 → 0.6.0

package/CHANGELOG.md

@@ -2,7 +2,29 @@
 
 ## Unreleased
 
+## [0.6.0] — 2026-07-14
+
+### Breaking
+- Node.js >= 22 is now required (`engines.node`), matching the embedded qmd-engine SDK. Installers reject Node 20/21.
+
 ### Changed
+- Upgraded `qmd-engine` to ^2.5.0 — `node-llama-cpp` is now an optional peer dependency upstream, so API-provider installs no longer pull the native llama.cpp toolchain.
+- Upgraded `better-sqlite3` to ^12.8.0 (prebuilt binaries for current Node majors, including Node 25 on Windows).
+- Wiki context is injected as a named `<system-reminder name="pi-para-wiki-context">` block with explicit wiki operating rules (search first, verify stale claims, persist decisions, prefer wiki_edit, no secrets).
+
+### Performance
+- `wiki_write` inline overhead cut from ~2.3s to ~0.6s on 500+ page wikis: single-pass parallel `rebuildIndex`, readdir-only slug scan for auto-linking, and QMD reindex deferred to the debounced background maintenance queue (same as `wiki_edit`).
+- `wiki_query` self-heals stale search state: on zero results it refreshes the QMD filesystem index once and retries before reporting no matches.
+
+### Fixed (Windows)
+- `scripts/install.ps1` requires Node >= 22, invokes `npx.cmd` explicitly (bare `npx` resolves to npx.ps1 and is blocked under restricted execution policies), and propagates `$LASTEXITCODE`.
+- `scripts/install.sh` minimum Node raised to 22.
+- Build/clean npm scripts are cross-platform (Node-based asset copy instead of POSIX `mkdir -p`/`cp`/`rm -rf`).
+- Fresh-install smoke test works on Windows (`fileURLToPath` for paths; sets both `HOME` and `USERPROFILE`).
+- `pi-para doctor` no longer emits a false secrets-permission warning on Windows/NTFS.
+- CI now includes a `windows-latest` job (typecheck, build, fresh-install smoke).
+
+### Changed (docs/infra)
 - Primary setup/runtime documentation now targets the no-daemon in-process scheduler architecture.
 - Added cross-platform install wrappers in `scripts/install.sh` and `scripts/install.ps1`.
 - Deprecated legacy daemon setup artifacts: `setup.sh` now delegates to the current setup flow, and `pi-para-daemon.service` / `DAEMON-PLAN.md` are marked legacy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-para",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "description": "PARA Knowledge Base Extension for pi — persistent, LLM-curated personal wiki",
   "type": "module",
   "main": "./dist/index.js",
@@ -144,8 +144,8 @@
     "skills"
   ],
   "scripts": {
-    "clean": "rm -rf dist",
-    "build": "tsc -p tsconfig.json && mkdir -p dist/webui/client/dist && cp src/webui/client/dist/index.html dist/webui/client/dist/index.html && mkdir -p dist/gepa/optimized && cp -r src/gepa/optimized/*.txt dist/gepa/optimized/ 2>/dev/null || true",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "tsc -p tsconfig.json && node scripts/build-assets.mjs",
     "check": "tsc --noEmit",
     "test": "vitest --run",
     "test:coverage": "vitest --run --coverage",
@@ -155,10 +155,13 @@
   },
   "dependencies": {
     "@types/better-sqlite3": "^7.6.13",
-    "better-sqlite3": "^11.9.1",
-    "qmd-engine": "^2.3.3",
+    "better-sqlite3": "^12.11.1",
+    "qmd-engine": "^2.5.0",
     "yaml": "^2.8.2"
   },
+  "engines": {
+    "node": ">=22.0.0"
+  },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "^0.80.2",
     "@earendil-works/pi-ai": "^0.80.2",

package/scripts/build-assets.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/* v8 ignore start */
+// Cross-platform post-tsc asset copy (replaces POSIX mkdir -p/cp in npm build).
+import { cp, mkdir, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join, resolve, dirname } from "node:path";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+// 1. Web UI client bundle
+const webuiSrc = join(root, "src", "webui", "client", "dist", "index.html");
+const webuiDestDir = join(root, "dist", "webui", "client", "dist");
+await mkdir(webuiDestDir, { recursive: true });
+if (existsSync(webuiSrc)) {
+  await cp(webuiSrc, join(webuiDestDir, "index.html"));
+}
+
+// 2. GEPA optimized prompt text files (optional)
+const gepaSrcDir = join(root, "src", "gepa", "optimized");
+const gepaDestDir = join(root, "dist", "gepa", "optimized");
+await mkdir(gepaDestDir, { recursive: true });
+if (existsSync(gepaSrcDir)) {
+  for (const entry of await readdir(gepaSrcDir)) {
+    if (entry.endsWith(".txt")) {
+      await cp(join(gepaSrcDir, entry), join(gepaDestDir, entry));
+    }
+  }
+}

package/scripts/install.ps1

@@ -9,36 +9,47 @@ Write-Host ""
 
 $package = "pi-para"
 $packageLatest = "$package@latest"
-$minMajor = 20
-$minMinor = 12
-
-if (-not (Get-Command npx -ErrorAction SilentlyContinue)) {
-    Write-Host "  ✗ npx not found." -ForegroundColor Red
-    Write-Host ""
-    Write-Host "  Install Node.js (>= $minMajor.$minMinor) from https://nodejs.org, then re-run." -ForegroundColor Yellow
-    Write-Host ""
-    exit 1
-}
+# qmd-engine (embedded search SDK) requires Node >= 22.
+$minMajor = 22
 
 $nodeVer = (node -v 2>$null) -replace '^v',''
 if (-not $nodeVer) {
     Write-Host "  ✗ Node.js not found on PATH." -ForegroundColor Red
-    Write-Host "  Install Node.js (>= $minMajor.$minMinor) from https://nodejs.org, then re-run." -ForegroundColor Yellow
+    Write-Host "  Install Node.js (>= $minMajor) from https://nodejs.org, then re-run." -ForegroundColor Yellow
     exit 1
 }
 
 $parts = $nodeVer.Split('.')
 $major = [int]$parts[0]
-$minor = [int]$parts[1]
-if ($major -lt $minMajor -or ($major -eq $minMajor -and $minor -lt $minMinor)) {
-    Write-Host "  ✗ Node.js $nodeVer is too old (requires >= $minMajor.$minMinor)" -ForegroundColor Red
+if ($major -lt $minMajor) {
+    Write-Host "  ✗ Node.js $nodeVer is too old (pi-para requires Node >= $minMajor)" -ForegroundColor Red
     Write-Host "  Upgrade Node.js: https://nodejs.org" -ForegroundColor Yellow
     exit 1
 }
 
-Write-Host "  → Using npx (Node $nodeVer)" -ForegroundColor Gray
+# Resolve npx.cmd explicitly. Bare `npx` resolves to npx.ps1, which fails
+# under restricted PowerShell execution policies.
+$npx = $null
+$npxCmd = Get-Command npx.cmd -ErrorAction SilentlyContinue
+if ($npxCmd) {
+    $npx = $npxCmd.Source
+} else {
+    $nodeCmd = Get-Command node -ErrorAction SilentlyContinue
+    if ($nodeCmd) {
+        $candidate = Join-Path (Split-Path $nodeCmd.Source) "npx.cmd"
+        if (Test-Path $candidate) { $npx = $candidate }
+    }
+}
+if (-not $npx) {
+    Write-Host "  ✗ npx.cmd not found." -ForegroundColor Red
+    Write-Host "  Install Node.js (>= $minMajor) from https://nodejs.org, then re-run." -ForegroundColor Yellow
+    exit 1
+}
+
+Write-Host "  → Using $npx (Node $nodeVer)" -ForegroundColor Gray
 Write-Host ""
 
 # Always pin @latest so npx does a registry lookup instead of reusing an older
 # cached package.
-& npx -y $packageLatest setup @args
+& $npx -y $packageLatest setup @args
+exit $LASTEXITCODE

package/scripts/install.sh

@@ -6,8 +6,9 @@ set -euo pipefail
 #   curl -fsSL https://raw.githubusercontent.com/picassio/pi-para/main/scripts/install.sh | bash
 
 PACKAGE="pi-para"
-MIN_NODE_MAJOR=20
-MIN_NODE_MINOR=12
+# qmd-engine (embedded search SDK) requires Node >= 22.
+MIN_NODE_MAJOR=22
+MIN_NODE_MINOR=0
 
 check_node_version() {
   if ! command -v node >/dev/null 2>&1; then

package/scripts/smoke-install.mjs

@@ -3,12 +3,13 @@
 import { mkdtemp, rm, access } from "node:fs/promises";
 import { constants } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
 const execFileAsync = promisify(execFile);
-const root = resolve(new URL("..", import.meta.url).pathname);
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const cli = join(root, "dist", "cli.js");
 
 async function main() {
@@ -17,7 +18,8 @@ async function main() {
   });
 
   const home = await mkdtemp(join(tmpdir(), "pi-para-smoke-"));
-  const env = { ...process.env, HOME: home };
+  // os.homedir() reads HOME on POSIX and USERPROFILE on Windows — set both.
+  const env = { ...process.env, HOME: home, USERPROFILE: home };
 
   try {
     await run([cli, "setup", "--yes", "--local", root], env);

package/src/doctor.ts

@@ -101,6 +101,11 @@ async function checkSecrets(secretsPath: string): Promise<DoctorCheck> {
   try {
     const store = await readSecretStore(secretsPath);
     if (!existsSync(secretsPath)) return { name: "secrets", status: "ok", message: "no local pi-para secrets configured" };
+    // POSIX mode bits are meaningless on Windows/NTFS — stat reports 666 and
+    // chmod is a no-op, so a permissions warning there is a false positive.
+    if (process.platform === "win32") {
+      return { name: "secrets", status: "ok", message: `${Object.keys(store.secrets).length} local secret(s) (POSIX permission check skipped on Windows)` };
+    }
     const mode = statSync(secretsPath).mode & 0o777;
     if (mode & 0o077) {
       return { name: "secrets", status: "warn", message: `${secretsPath} permissions are too open (${mode.toString(8)})`, fixable: true };

package/dist/atomic-write.d.ts

@@ -1,2 +0,0 @@
-export declare function atomicWriteFile(path: string, content: string, mode?: number): Promise<void>;
-//# sourceMappingURL=atomic-write.d.ts.map

package/dist/atomic-write.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAKA,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWjG"}

package/dist/atomic-write.js

@@ -1,18 +0,0 @@
-import { closeSync, fsyncSync, openSync, renameSync, writeFileSync } from "node:fs";
-import { mkdir } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { randomUUID } from "node:crypto";
-export async function atomicWriteFile(path, content, mode) {
-    await mkdir(dirname(path), { recursive: true });
-    const tempPath = join(dirname(path), `.${randomUUID()}.tmp`);
-    const fd = openSync(tempPath, "w", mode);
-    try {
-        writeFileSync(fd, content, "utf-8");
-        fsyncSync(fd);
-    }
-    finally {
-        closeSync(fd);
-    }
-    renameSync(tempPath, path);
-}
-//# sourceMappingURL=atomic-write.js.map

package/dist/atomic-write.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"atomic-write.js","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACpF,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY,EAAE,OAAe,EAAE,IAAa;IAChF,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,UAAU,EAAE,MAAM,CAAC,CAAC;IAC7D,MAAM,EAAE,GAAG,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IACzC,IAAI,CAAC;QACH,aAAa,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACpC,SAAS,CAAC,EAAE,CAAC,CAAC;IAChB,CAAC;YAAS,CAAC;QACT,SAAS,CAAC,EAAE,CAAC,CAAC;IAChB,CAAC;IACD,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AAC7B,CAAC"}

package/dist/capture.d.ts

@@ -1,34 +0,0 @@
-/**
- * Session knowledge capture — extracts insights from sessions into the wiki.
- *
- * Two modes:
- * - Auto-capture on session_shutdown (standalone Agent with wiki tools)
- * - Explicit capture via /wiki-capture command (standalone Agent)
- *
- * Both are fully automatic — no user confirmation prompts.
- */
-import type { Model } from "@earendil-works/pi-ai";
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
-import type { QMDStore } from "qmd-engine";
-import type { ProjectScope } from "./scope.js";
-import type { PageRef } from "./wiki.js";
-import type { SessionDigest } from "./raw.js";
-export interface CaptureResult {
-    pagesCreated: PageRef[];
-    pagesUpdated: PageRef[];
-    skipped: boolean;
-    reason?: string;
-    digestEntry?: SessionDigest;
-}
-/**
- * Called automatically on session_shutdown.
- * Spins up a standalone Agent with wiki tools, aborts after timeoutMs.
- */
-export declare function autoCapture(wikiDir: string, store: QMDStore, messages: AgentMessage[], scope: ProjectScope, sessionFile: string, model: Model<any>, modelRegistry: ModelRegistry, timeoutMs?: number, alreadyCaptured?: string[]): Promise<CaptureResult>;
-/**
- * Called when user explicitly requests capture mid-session via /wiki-capture.
- * Spins up a standalone Agent with wiki tools.
- */
-export declare function explicitCapture(wikiDir: string, store: QMDStore, topic: string | undefined, messages: AgentMessage[], scope: ProjectScope, sessionFile: string, model: Model<any>, modelRegistry: ModelRegistry, alreadyCaptured?: string[]): Promise<CaptureResult>;
-//# sourceMappingURL=capture.d.ts.map

package/dist/capture.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../src/capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAEnD,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,+BAA+B,CAAC;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,WAAW,CAAC;AAGvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAO9C,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,OAAO,EAAE,CAAC;IACxB,YAAY,EAAE,OAAO,EAAE,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,aAAa,CAAC;CAC7B;AAqMD;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,QAAQ,EACf,QAAQ,EAAE,YAAY,EAAE,EACxB,KAAK,EAAE,YAAY,EACnB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EACjB,aAAa,EAAE,aAAa,EAC5B,SAAS,CAAC,EAAE,MAAM,EAClB,eAAe,CAAC,EAAE,MAAM,EAAE,GACzB,OAAO,CAAC,aAAa,CAAC,CAkJxB;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,QAAQ,EAAE,YAAY,EAAE,EACxB,KAAK,EAAE,YAAY,EACnB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EACjB,aAAa,EAAE,aAAa,EAC5B,eAAe,CAAC,EAAE,MAAM,EAAE,GACzB,OAAO,CAAC,aAAa,CAAC,CAqHxB"}