pi-para 0.5.2 → 0.6.0

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

@@ -0,0 +1,55 @@
+# pi-para — Interactive Setup (Windows)
+# Usage:
+#   irm https://raw.githubusercontent.com/picassio/pi-para/main/scripts/install.ps1 | iex
+
+Write-Host ""
+Write-Host "  🗂️  pi-para — Setup" -ForegroundColor Cyan
+Write-Host "  ──────────────────"
+Write-Host ""
+
+$package = "pi-para"
+$packageLatest = "$package@latest"
+# 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) from https://nodejs.org, then re-run." -ForegroundColor Yellow
+    exit 1
+}
+
+$parts = $nodeVer.Split('.')
+$major = [int]$parts[0]
+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
+}
+
+# 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
+exit $LASTEXITCODE

package/scripts/install.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# pi-para — Interactive Setup
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/picassio/pi-para/main/scripts/install.sh | bash
+
+PACKAGE="pi-para"
+# 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
+    return 1
+  fi
+
+  local version major minor
+  version=$(node -v 2>/dev/null | sed 's/^v//')
+  major=$(echo "$version" | cut -d. -f1)
+  minor=$(echo "$version" | cut -d. -f2)
+
+  if [ "${major:-0}" -lt "$MIN_NODE_MAJOR" ]; then
+    return 1
+  fi
+  if [ "$major" -eq "$MIN_NODE_MAJOR" ] && [ "${minor:-0}" -lt "$MIN_NODE_MINOR" ]; then
+    return 1
+  fi
+  return 0
+}
+
+main() {
+  echo ""
+  echo "  🗂️  pi-para — Setup"
+  echo "  ──────────────────"
+  echo ""
+
+  if check_node_version && command -v npx >/dev/null 2>&1; then
+    local node_version
+    node_version=$(node -v 2>/dev/null | sed 's/^v//')
+    echo "  → Using npx (Node $node_version)"
+    echo ""
+
+    # Always pin @latest so npx does a registry lookup instead of reusing an
+    # older cached package. Redirect stdin from /dev/tty when available so
+    # interactive prompts still work under curl | bash.
+    if [ -r /dev/tty ]; then
+      npx -y "$PACKAGE@latest" setup "$@" </dev/tty
+    else
+      npx -y "$PACKAGE@latest" setup "$@"
+    fi
+  else
+    echo "  ✗ Node $MIN_NODE_MAJOR.$MIN_NODE_MINOR+ with npx is required."
+    echo ""
+    echo "  Install Node from https://nodejs.org, then run:"
+    echo ""
+    echo "    npx $PACKAGE@latest setup"
+    echo ""
+    exit 1
+  fi
+}
+
+main "$@"

package/scripts/smoke-install.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/* v8 ignore start */
+import { mkdtemp, rm, access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { tmpdir } from "node:os";
+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(dirname(fileURLToPath(import.meta.url)), "..");
+const cli = join(root, "dist", "cli.js");
+
+async function main() {
+  await access(cli, constants.R_OK).catch(() => {
+    throw new Error("dist/cli.js not found. Run npm run build before smoke-install.");
+  });
+
+  const home = await mkdtemp(join(tmpdir(), "pi-para-smoke-"));
+  // 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);
+
+    const status = JSON.parse((await run([cli, "status", "--json"], env)).stdout);
+    assert(status.configPath?.startsWith(home), "status configPath should use smoke HOME");
+    assert(status.wikiDir?.startsWith(home), "status wikiDir should use smoke HOME");
+    assert(typeof status.pages?.total === "number", "status pages.total should be numeric");
+    assert(typeof status.scheduler?.queued === "number", "status scheduler.queued should be numeric");
+
+    const doctor = JSON.parse((await run([cli, "doctor", "--json"], env)).stdout);
+    assert(doctor.ok === true, "doctor should pass in smoke HOME");
+
+    console.log("pi-para smoke install passed");
+    console.log(`  HOME: ${home}`);
+    console.log(`  Config: ${status.configPath}`);
+    console.log(`  Wiki: ${status.wikiDir}`);
+  } finally {
+    if (!process.env.PI_PARA_KEEP_SMOKE_HOME) {
+      await rm(home, { recursive: true, force: true });
+    }
+  }
+}
+
+async function run(args, env) {
+  const [file, ...rest] = args;
+  return execFileAsync(process.execPath, [file, ...rest], {
+    cwd: root,
+    env,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/skills/para/SKILL.md

@@ -45,7 +45,7 @@ Write to the wiki immediately when you:
 - Learn how a system actually works (vs. how you assumed)
 - Establish a convention or pattern others should follow
 
-Use `wiki_write(mode: 'edit')` for surgical updates to existing pages. Use `wiki_write(mode: 'append')` to add new sections. Don't defer — context and reasoning degrade with time.
+Use `wiki_edit` for surgical updates to existing pages. Use `wiki_write(mode: 'append')` to add new sections and `wiki_write(mode: 'replace')` only for intentional full-page rewrites. Don't defer — context and reasoning degrade with time.
 
 ## 4. When Debugging — Search First
 

package/skills/setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup
-description: Set up pi-para PARA knowledge base extension. Installs qmd search engine, configures providers, starts background capture daemon. Use when user asks to install, set up, or configure pi-para wiki.
+description: Set up pi-para PARA knowledge base extension. Configures no-daemon scheduler runtime, embedded QMD SDK, provider profiles, and diagnostics. Use when user asks to install, set up, or configure pi-para wiki.
 ---
 
 # pi-para Setup

package/src/atomic-write.ts

@@ -0,0 +1,17 @@
+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: string, content: string, mode?: number): Promise<void> {
+  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);
+}

package/src/capture.ts

@@ -8,10 +8,10 @@
  * Both are fully automatic — no user confirmation prompts.
  */
 
-import type { Model } from "@mariozechner/pi-ai";
-import { Agent } from "@mariozechner/pi-agent-core";
-import type { AgentMessage, AgentEvent } from "@mariozechner/pi-agent-core";
-import type { ModelRegistry } from "@mariozechner/pi-coding-agent";
+import type { Model } from "@earendil-works/pi-ai";
+import { Agent } from "@earendil-works/pi-agent-core";
+import type { AgentMessage, AgentEvent } 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";

package/src/cli-legacy.ts

@@ -0,0 +1,43 @@
+export const LEGACY_DAEMON_COMMANDS = new Set([
+  "start",
+  "stop",
+  "legacy-status",
+  "process",
+  "process-recent",
+  "retry-failed",
+  "history",
+]);
+
+export function isLegacyDaemonCommand(command: string | undefined): boolean {
+  return command !== undefined && LEGACY_DAEMON_COMMANDS.has(command);
+}
+
+export function formatLegacyDaemonWarning(command: string): string {
+  const replacement = replacementForLegacyCommand(command);
+  return [
+    `[pi-para] Warning: '${command}' is a deprecated legacy daemon command.`,
+    "pi-para now uses an in-process scheduler while Pi is open; no system daemon is required.",
+    replacement ? `Use ${replacement} for the current workflow.` : "Use 'pi-para tasks' or '/wiki-scheduler status' for the current workflow.",
+  ].join("\n");
+}
+
+function replacementForLegacyCommand(command: string): string | null {
+  switch (command) {
+    case "start":
+      return "'pi-para setup' and restart Pi";
+    case "stop":
+      return "'/wiki-scheduler status' or close/restart Pi sessions";
+    case "legacy-status":
+      return "'pi-para tasks' or '/wiki-scheduler status'";
+    case "process":
+      return "'pi-para capture-recent --hours N' or '/wiki-capture'";
+    case "process-recent":
+      return "'pi-para capture-recent --hours N'";
+    case "retry-failed":
+      return "'pi-para tasks retry'";
+    case "history":
+      return "'pi-para tasks history'";
+    default:
+      return null;
+  }
+}

package/src/cli.ts

@@ -1,15 +1,8 @@
 #!/usr/bin/env node
 /**
- * CLI for pi-para-daemon.
+ * CLI for pi-para.
  *
- * Usage:
- *   pi-para-daemon start [--foreground]
- *   pi-para-daemon stop
- *   pi-para-daemon status
- *   pi-para-daemon process <session_file>
- *   pi-para-daemon process-recent [--hours N]
- *   pi-para-daemon retry-failed
- *   pi-para-daemon history [--scope NAME]
+ * The old pi-para-daemon commands remain as deprecated compatibility aliases.
  */
 
 import { join } from "node:path";
@@ -19,6 +12,7 @@ import { existsSync, readdirSync, statSync } from "node:fs";
 import { Daemon } from "./daemon.js";
 import { StateDB } from "./state.js";
 import { RegistryWatcher } from "./watcher.js";
+import { formatLegacyDaemonWarning, isLegacyDaemonCommand } from "./cli-legacy.js";
 
 // -- Model setup -------------------------------------------------------------
 // Use MiniMax via the same config as qmd-engine
@@ -26,7 +20,7 @@ import { RegistryWatcher } from "./watcher.js";
 async function createModel(modelArg?: string) {
   const { parse } = await import("yaml");
   const { readFileSync } = await import("node:fs");
-  const { getModel, getProviders, getEnvApiKey } = await import("@mariozechner/pi-ai");
+  const { getModel, getProviders, getEnvApiKey } = await import("@earendil-works/pi-ai/compat");
 
   // 0. Try config.json daemonModel
   if (!modelArg) {
@@ -53,7 +47,7 @@ async function createModel(modelArg?: string) {
         // Resolve API key: try AuthStorage first (OAuth), then env vars
         let authStore: any = null;
         try {
-          const { AuthStorage } = await import("@mariozechner/pi-coding-agent");
+          const { AuthStorage } = await import("@earendil-works/pi-coding-agent");
           authStore = AuthStorage.create();
         } catch {}
         const getApiKey = async (p: string) => {
@@ -71,9 +65,9 @@ async function createModel(modelArg?: string) {
 
   // 2. Try pi's auth storage (auth.json) — supports OAuth (Anthropic, GitHub Copilot, etc.)
   try {
-    const { AuthStorage } = await import("@mariozechner/pi-coding-agent");
+    const { AuthStorage } = await import("@earendil-works/pi-coding-agent");
     const authStorage = AuthStorage.create();
-    const { getModels } = await import("@mariozechner/pi-ai");
+    const { getModels } = await import("@earendil-works/pi-ai/compat");
 
     // Check providers in preference order: anthropic first (best quality)
     const preferredProviders = ["anthropic", "openai", "openrouter", "google-antigravity", "github-copilot"];
@@ -103,7 +97,7 @@ async function createModel(modelArg?: string) {
   for (const provider of providers) {
     const key = getEnvApiKey(provider);
     if (key) {
-      const { getModels } = await import("@mariozechner/pi-ai");
+      const { getModels } = await import("@earendil-works/pi-ai/compat");
       const models = getModels(provider as any);
       const sorted = [...models].sort((a, b) => (b.contextWindow ?? 0) - (a.contextWindow ?? 0));
       const picked = sorted.find(m => !m.reasoning) ?? sorted[0];
@@ -150,7 +144,102 @@ async function main() {
   const command = args[0];
   const wikiDir = join(homedir(), ".pi", "wiki");
 
+  if (isLegacyDaemonCommand(command)) {
+    console.warn(formatLegacyDaemonWarning(command));
+    console.warn("");
+  }
+
   switch (command) {
+    case "setup": {
+      const dryRun = args.includes("--dry-run");
+      const localIdx = args.indexOf("--local");
+      const localPath = localIdx >= 0 ? args[localIdx + 1] : undefined;
+      const { runSetup, formatSetupResult } = await import("./setup.js");
+      const result = await runSetup({ yes: args.includes("--yes"), dryRun, localPath });
+      console.log(formatSetupResult(result));
+      break;
+    }
+
+    case "doctor": {
+      const json = args.includes("--json");
+      const { runDoctor, formatDoctorResult } = await import("./doctor.js");
+      const result = await runDoctor({
+        fix: args.includes("--fix"),
+        testCaptureModel: args.includes("--test-capture-model"),
+      });
+      console.log(json ? JSON.stringify(result, null, 2) : formatDoctorResult(result));
+      break;
+    }
+
+    case "tasks": {
+      const sub = args[1] ?? "list";
+      const {
+        listSchedulerTasks,
+        retryFailedSchedulerTasks,
+        getSchedulerTask,
+        listSchedulerHistory,
+        formatQueueItems,
+        formatQueueItem,
+        formatSchedulerHistory,
+      } = await import("./scheduler/controls.js");
+      if (sub === "retry") {
+        const taskIdx = args.indexOf("--task");
+        const taskName = taskIdx >= 0 ? args[taskIdx + 1] : undefined;
+        const count = retryFailedSchedulerTasks(wikiDir, { taskName });
+        console.log(`Requeued ${count} failed task${count === 1 ? "" : "s"}.`);
+      } else if (sub === "show") {
+        const id = parseInt(args[2] ?? "", 10);
+        if (!Number.isFinite(id)) { console.error("Usage: pi-para tasks show <id>"); process.exit(1); }
+        console.log(formatQueueItem(getSchedulerTask(wikiDir, id)));
+      } else if (sub === "history") {
+        const taskIdx = args.indexOf("--task");
+        const limitIdx = args.indexOf("--limit");
+        const taskName = taskIdx >= 0 ? args[taskIdx + 1] : undefined;
+        const limit = limitIdx >= 0 ? parseInt(args[limitIdx + 1] ?? "20", 10) : 20;
+        console.log(formatSchedulerHistory(listSchedulerHistory(wikiDir, { taskName, limit })));
+      } else {
+        const statusIdx = args.indexOf("--status");
+        const status = statusIdx >= 0 ? args[statusIdx + 1] as any : undefined;
+        console.log(formatQueueItems(listSchedulerTasks(wikiDir, { status })));
+      }
+      break;
+    }
+
+    case "capture-recent": {
+      const hoursIdx = args.indexOf("--hours");
+      const hours = hoursIdx >= 0 ? parseInt(args[hoursIdx + 1] ?? "24") : 24;
+      const { queueCaptureRecent, formatQueueCaptureRecentResult } = await import("./scheduler/controls.js");
+      const result = await queueCaptureRecent({ wikiDir, hours });
+      console.log(formatQueueCaptureRecentResult(result));
+      console.log("Queued captures run when a Pi session with pi-para is open.");
+      break;
+    }
+
+    case "providers": {
+      const sub = args[1] ?? "list";
+      const { readSecretStore, setSecret, removeSecret, redactCredential } = await import("./credentials.js");
+      if (sub === "set-secret") {
+        const name = args[2];
+        const value = args[3];
+        if (!name || !value) { console.error("Usage: pi-para providers set-secret <name> <value>"); process.exit(1); }
+        await setSecret(name, value);
+        console.log(`Stored secret:${name}`);
+      } else if (sub === "remove-secret") {
+        const name = args[2];
+        if (!name) { console.error("Usage: pi-para providers remove-secret <name>"); process.exit(1); }
+        await removeSecret(name);
+        console.log(`Removed secret:${name}`);
+      } else {
+        const secrets = await readSecretStore();
+        const names = Object.keys(secrets.secrets);
+        console.log("pi-para providers");
+        console.log("  Credential policy: Pi AuthStorage preferred; pi-para secrets fallback; env vars not used by setup.");
+        if (names.length === 0) console.log("  No pi-para local secrets configured.");
+        for (const name of names) console.log(`  secret:${name} = ${redactCredential(secrets.secrets[name])}`);
+      }
+      break;
+    }
+
     case "start": {
       const modelIdx = args.indexOf("--model");
       const modelArg = modelIdx >= 0 ? args[modelIdx + 1] : undefined;
@@ -210,6 +299,14 @@ async function main() {
     }
 
     case "status": {
+      const json = args.includes("--json");
+      const { getPiParaStatus, formatPiParaStatus } = await import("./status.js");
+      const result = await getPiParaStatus();
+      console.log(json ? JSON.stringify(result, null, 2) : formatPiParaStatus(result));
+      break;
+    }
+
+    case "legacy-status": {
       const state = new StateDB(wikiDir);
       const pid = state.getState("daemon_pid");
       const startedAt = state.getState("daemon_started_at");
@@ -358,7 +455,7 @@ async function main() {
           break;
         }
         default:
-          console.log(`pi-para-daemon gepa — GEPA prompt optimizer (DSPy GEPA via uv)
+          console.log(`pi-para gepa — GEPA prompt optimizer (DSPy GEPA via uv)
 
 Subcommands:
   optimize   Run DSPy GEPA optimization
@@ -387,25 +484,33 @@ Config (persistent defaults in ~/.pi/wiki/config.json):
     }
 
     default:
-      console.log(`pi-para-daemon — background knowledge capture
+      console.log(`pi-para — PARA wiki extension CLI
+
+Primary commands:
+  setup              Configure pi-para for this machine (--yes, --dry-run, --local PATH)
+  doctor             Validate install/config/wiki/QMD health (--fix, --json, --test-capture-model)
+  tasks              Show scheduler queue (--status queued|running|done|failed)
+  tasks show <id>    Show one queued/running/done/failed task payload
+  tasks history      Show scheduler history [--task NAME] [--limit N]
+  tasks retry        Requeue failed scheduler tasks [--task NAME]
+  status             Show config/wiki/scheduler status (--json)
+  capture-recent     Queue recent completed sessions for capture (--hours N)
+  providers          List credential refs and local secrets
+  providers set-secret <name> <value>
+  providers remove-secret <name>
+  gepa <subcommand>  GEPA prompt optimizer (optimize, list, targets, compare)
 
-Commands:
-  start              Start the daemon (foreground)
-  stop               Stop the running daemon
-  status             Show daemon status and recent history
+Legacy compatibility commands:
+  start              Deprecated daemon foreground mode
+  stop               Deprecated daemon stop
+  legacy-status      Legacy daemon status and recent history
   process <file>     Process a single session file
   process-recent     Process unprocessed sessions (--hours N, default 24)
   retry-failed       Retry all failed sessions
   history            Show processing history (--scope NAME to filter)
-  gepa <subcommand>  GEPA prompt optimizer (optimize, list, targets, compare)
-
-Options:
-  --model <provider/id>  Use specific model (e.g. anthropic/claude-sonnet-4)
 
-Model resolution order:
-  1. --model flag
-  2. Pi's model registry (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.)
-  3. ~/.config/qmd/index.yml chat provider (MiniMax, OpenRouter, etc.)`);
+Credential policy:
+  Use Pi AuthStorage or ~/.pi/para/secrets.json. Setup does not use env vars for API keys.`);
       break;
   }
 }