pi-harness-runtime 1.1.445 → 1.1.447

package/packages/skills/src/sync-source.ts

@@ -0,0 +1,114 @@
+/**
+ * The skill sync: where the skills come from, and which script performs it.
+ *
+ * The source tree is installation data, not a constant of the product: the
+ * package must not guess a path on the operator's machine, and it must not
+ * print one either. The operator names the directory with an environment
+ * variable, and every message the package prints uses that name.
+ *
+ * The script is the other half and it belongs to the package, so it is
+ * found relative to the module - it works wherever the package was
+ * installed.
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * The environment variable that names the directory the operator wants to
+ * sync skills FROM.
+ */
+export const SKILLS_SOURCE_ENV = "PI_HARNESS_SKILLS_SOURCE";
+
+/**
+ * Expand a leading `~` to the home directory.
+ *
+ * A shell expands `~`, a program does not, and the operator writes the
+ * value the way they would write it on a command line.
+ */
+export function expandHome(path: string): string {
+	if (path === "~") return homedir();
+	if (path.startsWith("~/")) return join(homedir(), path.slice(2));
+	return path;
+}
+
+/**
+ * The directory the operator configured as the skill source, if any.
+ */
+export function getSkillsSource(): string | undefined {
+	const raw = process.env[SKILLS_SOURCE_ENV]?.trim();
+	if (!raw) return undefined;
+	return expandHome(raw);
+}
+
+/**
+ * The source the operator asked for on the command line, if any.
+ *
+ * The `--from` argument wins over the environment variable, because the
+ * argument is the more specific statement.
+ */
+export function getSkillsSourceFromArgs(args: string[]): string | undefined {
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+		if (arg === "--from" || arg === "-f") return args[i + 1];
+		if (arg.startsWith("--from=")) return expandHome(arg.slice("--from=".length));
+	}
+	return getSkillsSource();
+}
+
+/**
+ * The path of the sync script that ships with this package.
+ *
+ * The script lives in `scripts/` at the package root, and this module
+ * lives in `packages/skills/src/` (or in `packages/skills/dist/` when the
+ * package is compiled), so the script is three levels up. Finding it
+ * relative to the module works wherever the package was installed - the
+ * source of the skills is the operator's business, the script is ours.
+ *
+ * An installation without the script is a real state: the caller reports
+ * it instead of spawning a path that does not exist.
+ */
+export function syncSkillsScriptPath(
+	moduleUrl: string = import.meta.url,
+): string | undefined {
+	const path = fileURLToPath(
+		new URL("../../../scripts/sync-skills.ts", moduleUrl),
+	);
+	return existsSync(path) ? path : undefined;
+}
+
+/**
+ * The hint that tells the operator how to sync skills, when it applies.
+ *
+ * The hint applies when the harness skills directory exists but is empty
+ * and the configured source directory holds skills. It returns undefined
+ * when there is nothing to suggest.
+ */
+export function skillsSyncHint(): string | undefined {
+	try {
+		const harnessDir = join(homedir(), ".pi-harness-runtime", "skills");
+		if (!existsSync(harnessDir)) return undefined;
+
+		const entries = readdirSync(harnessDir).filter((n: string) => n !== "harness-runtime");
+		if (entries.length > 0) return undefined; // Has user skills, nothing to suggest
+
+		const source = getSkillsSource();
+		if (!source) return undefined;
+		if (!existsSync(source)) return undefined;
+
+		const skillEntries = readdirSync(source).filter((n: string) =>
+			existsSync(join(source, n, "SKILL.md")),
+		);
+		if (skillEntries.length === 0) return undefined;
+
+		return (
+			`[pi-harness] ${skillEntries.length} skill(s) found in ${source}. ` +
+			`Sync them: bun scripts/sync-skills.ts --from ${source}`
+		);
+	} catch {
+		// Non-fatal — ignore errors
+		return undefined;
+	}
+}

package/packages/todo-bd-sync/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moocoding/todo-bd-sync",
-  "version": "1.1.445",
+  "version": "1.1.447",
   "description": "Two-way sync between rpiv-todo overlay and bd issue tracker",
   "type": "module",
   "main": "src/index.ts",

package/packages/token-estimation/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/token-estimation",
-  "version": "1.1.445",
+  "version": "1.1.447",
   "description": "pi-harness-runtime — token-estimation",
   "type": "module",
   "main": "./dist/index.js",

package/packages/tooling-preference/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/tooling-preference",
-  "version": "1.1.445",
+  "version": "1.1.447",
   "description": "pi-harness-runtime — JS/TS tooling preference (Biome vs ESLint/Prettier) proposal",
   "type": "module",
   "main": "./dist/index.js",

package/packages/trajectory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/trajectory",
-  "version": "1.1.445",
+  "version": "1.1.447",
   "description": "Trajectory capture for the write-review loop — persists cycle records for learning",
   "type": "module",
   "main": "./dist/src/index.js",

package/packages/tui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/tui",
-  "version": "1.1.445",
+  "version": "1.1.447",
   "description": "pi-harness-runtime — tui",
   "type": "module",
   "main": "./dist/index.js",

package/packages/two-phase-review/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/two-phase-review",
-  "version": "1.1.445",
+  "version": "1.1.447",
   "description": "pi-harness-runtime — two-phase implementation and review workflow (queue review signals, gate the phase, scope the diff)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/types/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/types",
-  "version": "1.1.445",
+  "version": "1.1.447",
   "description": "Shared TypeScript types for pi-harness-runtime packages",
   "type": "module",
   "main": "./dist/index.js",

package/packages/webmcp-tester/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/webmcp-tester",
-  "version": "1.1.445",
+  "version": "1.1.447",
   "description": "WebMCP-powered E2E testing for pi-harness - natural language test scenarios",
   "type": "module",
   "main": "./dist/index.js",

package/packages/wiki/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/wiki",
-  "version": "1.1.445",
+  "version": "1.1.447",
   "description": "LLM Wiki integration for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/write-review/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moocoding/write-review",
-  "version": "1.1.445",
+  "version": "1.1.447",
   "description": "Two-agent write-review loop with blackboard coordination",
   "type": "module",
   "main": "src/index.ts",

package/scripts/copy-plugins.js

@@ -11,7 +11,7 @@
 
 import { mkdirSync, existsSync, readdirSync, cpSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -57,4 +57,14 @@ function main() {
   console.log("[copy-plugins] Done!");
 }
 
-main();
+/**
+ * The program runs only when the file is the entry point.
+ *
+ * The script is published in the npm package and is the postinstall hook,
+ * so a consumer may import it. An import must not copy files into the
+ * home directory of the machine that imported it.
+ */
+const entry = process.argv[1];
+if (entry && pathToFileURL(entry).href === import.meta.url) {
+  main();
+}

package/scripts/sync-skills.ts

@@ -11,8 +11,9 @@
  */
 
 import { existsSync, mkdirSync, readdirSync, statSync, copyFileSync, rmSync } from "node:fs";
-import { join, basename, dirname } from "node:path";
+import { join, basename } from "node:path";
 import { homedir } from "node:os";
+import { pathToFileURL } from "node:url";
 
 // Default paths
 const DEFAULT_TARGET = join(homedir(), ".pi-harness-runtime", "skills");
@@ -270,6 +271,20 @@ function syncSkills(options: SyncOptions): void {
   console.log(`  3. List skills: /skill list`);
 }
 
-// Main
-const options = parseArgs();
-syncSkills(options);
+/**
+ * The program runs only when the file is the entry point.
+ *
+ * The script is published in the npm package, so a consumer may import it.
+ * An import must not sync skills, and it must not end the importing
+ * process - the same rule the harness programs and the command modules
+ * follow.
+ */
+function main(): void {
+  const options = parseArgs();
+  syncSkills(options);
+}
+
+const entry = process.argv[1];
+if (entry && pathToFileURL(entry).href === import.meta.url) {
+  main();
+}

package/scripts/sync-to-qdrant.ts

@@ -13,6 +13,7 @@
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { pathToFileURL } from "node:url";
 import { QdrantClient } from "@qdrant/js-client-rest";
 // The runtime and this script must write into the SAME collection with the
 // SAME vectors: a collection holds vectors of exactly one size, and a vector
@@ -343,10 +344,19 @@ async function search(query: string): Promise<void> {
 // Main
 // =============================================================================
 
-const args = process.argv.slice(2);
+/**
+ * The program runs only when the file is the entry point.
+ *
+ * The script is published in the npm package, so a consumer may import it.
+ * An import must not talk to Qdrant, and it must not end the importing
+ * process - the same rule the harness programs and the command modules
+ * follow.
+ */
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
 
-if (args.includes("--help")) {
-  console.log(`
+  if (args.includes("--help")) {
+    console.log(`
 Sync Skills to Qdrant (Sanitized)
 ──────────────────────────────────
 Upload skills to Qdrant for team sharing.
@@ -373,28 +383,34 @@ Environment:
 Or create file:
   ~/.pi-harness-runtime/keys/qdrant-api-key.txt
 `);
-  process.exit(0);
-}
+    process.exit(0);
+  }
 
-if (args.includes("--list")) {
-  await listSkills();
-  process.exit(0);
-}
+  if (args.includes("--list")) {
+    await listSkills();
+    process.exit(0);
+  }
 
-const searchIdx = args.indexOf("--search");
-if (searchIdx !== -1 && args[searchIdx + 1]) {
-  await search(args[searchIdx + 1]);
-  process.exit(0);
-}
+  const searchIdx = args.indexOf("--search");
+  if (searchIdx !== -1 && args[searchIdx + 1]) {
+    await search(args[searchIdx + 1]);
+    process.exit(0);
+  }
 
-const fromIdx = args.indexOf("--from");
-if (fromIdx === -1 || !args[fromIdx + 1]) {
-  console.error("Error: --from <directory> is required");
-  console.error("Use --help for usage information.");
-  process.exit(1);
-}
+  const fromIdx = args.indexOf("--from");
+  if (fromIdx === -1 || !args[fromIdx + 1]) {
+    console.error("Error: --from <directory> is required");
+    console.error("Use --help for usage information.");
+    process.exit(1);
+  }
 
-const sourceDir = args[fromIdx + 1];
-const clear = args.includes("--clear");
+  const sourceDir = args[fromIdx + 1];
+  const clear = args.includes("--clear");
 
-await syncToQdrant(sourceDir, clear);
+  await syncToQdrant(sourceDir, clear);
+}
+
+const entry = process.argv[1];
+if (entry && pathToFileURL(entry).href === import.meta.url) {
+  await main();
+}

package/CLAUDE.md

@@ -1,77 +0,0 @@
-# Project Instructions for AI Agents
-
-This file provides instructions and context for AI coding agents working on this project.
-
-<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
-## Beads Issue Tracker
-
-This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
-
-### Quick Reference
-
-```bash
-bd ready              # Find available work
-bd show <id>          # View issue details
-bd update <id> --claim  # Claim work
-bd close <id>         # Complete work
-```
-
-### Rules
-
-- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
-- Run `bd prime` for detailed command reference and session close protocol
-- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
-
-## Session Completion
-
-**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
-
-**MANDATORY WORKFLOW:**
-
-1. **File issues for remaining work** - Create issues for anything that needs follow-up
-2. **Run quality gates** (if code changed) - Tests, linters, builds
-3. **Update issue status** - Close finished work, update in-progress items
-4. **PUSH TO REMOTE** - This is MANDATORY:
-   ```bash
-   git pull --rebase
-   bd dolt push
-   git push
-   git status  # MUST show "up to date with origin"
-   ```
-5. **Clean up** - Clear stashes, prune remote branches
-6. **Verify** - All changes committed AND pushed
-7. **Hand off** - Provide context for next session
-
-**CRITICAL RULES:**
-- Work is NOT complete until `git push` succeeds
-- NEVER stop before pushing - that leaves work stranded locally
-- NEVER say "ready to push when you are" - YOU must push
-- If push fails, resolve and retry until it succeeds
-<!-- END BEADS INTEGRATION -->
-
-
-## Build & Test
-
-_Add your build and test commands here_
-
-```bash
-# Example:
-# npm install
-# npm test
-```
-
-## Architecture Overview
-
-_Add a brief overview of your project architecture_
-
-## Conventions & Patterns
-
-### Git Workflow
-
-After running `git status`, **ALWAYS** run `git add --all` before asking about committing. Never assume changes are staged.
-
-```bash
-git status  # inspect changes
-git add --all  # stage everything
-git commit    # then proceed
-```

package/TODO-todo-bd-sync.md

@@ -1,124 +0,0 @@
-# TODO: Complete todo-bd-sync Implementation
-
-## Status: Phase 1 & 2 Complete
-
-### What was implemented
-
-1. **Package structure** (`packages/todo-bd-sync/`)
-   - ✅ `src/types.ts` - Type definitions for TodoTask, BdIssue, IdMappingRegistry
-   - ✅ `src/detector.ts` - Dependency detection (rpiv-todo, bd CLI)
-   - ✅ `src/sync.ts` - Two-way sync logic (todo ↔ bd)
-   - ✅ `src/index.ts` - Main API with TodoBdSync class
-   - ✅ `src/extension.ts` - pi-coding-agent extension entry
-   - ✅ `src/todo-reminder.ts` - Auto-reminder for continuing todos
-   - ✅ `package.json` - Package manifest
-
-2. **Integration into main extension**
-   - ✅ Added import and lazy initialization to `index.ts`
-
-3. **Documentation**
-   - ✅ `docs/todo-bd-sync.md` - Full documentation with auto-reminder feature
-   - ✅ `README.md` - Added section and commands
-
----
-
-## New: Auto-Reminder Feature (Phase 2)
-
-### Problem Fixed
-
-- **Bug**: LLM completes tasks but stays silent about remaining todos
-- **User had to manually ask**: "continue with todos" or "wrap up"
-
-### Solution
-
-The `todo-reminder.ts` module injects reminders when todos remain:
-
-**Prerequisite**: Tasks must be created with `bd create` (not via `/todo` command).
-
-```typescript
-// After agent completes a task:
-// Checks bd for remaining todos
-// Injects message:
-"Remaining todos detected:
-[bd-a1b2] Review PR (pending)
-
-Please continue with the next pending task or ask the user which to prioritize."
-```
-
-### How It Works
-
-1. Hooks into `agent_end` and `tool_execution_end`
-2. Calls `bd ready --json` to check remaining todos
-3. If pending tasks exist, sends reminder via `pi.sendUserMessage()`
-4. 5-second cooldown to prevent spam
-
----
-
-## Remaining Tasks
-
-### P1: Test Basic Integration
-
-```bash
-# Restart pi and test
-pi
-
-# Check if todo-bd-sync is enabled
-/bd-todo-status
-```
-
-### P2: Test Auto-Reminder
-
-1. Create a multi-step task via bd:
-
-   ```bash
-   bd create "Build API" -p 2
-   bd create "Add tests" --parent <parent-id>
-   bd create "Deploy" --parent <parent-id>
-   ```
-
-2. Ask LLM to work on it:
-
-   ```
-   Build the API and manage tasks with bd
-   ```
-
-3. After completing a task, verify reminder is injected:
-   - Should see message about remaining todos
-   - LLM should offer to continue
-
-### P3: Tune Reminder Behavior
-
-- Adjust cooldown (currently 5 seconds)
-- Customize reminder message template
-- Test with various task counts
-
----
-
-## Files Summary
-
-| File | Purpose |
-|------|---------|
-| `src/types.ts` | Type definitions |
-| `src/detector.ts` | Check dependencies |
-| `src/sync.ts` | bd CLI integration |
-| `src/todo-reminder.ts` | **NEW: Auto-reminder injection** |
-| `src/index.ts` | Main API |
-| `src/extension.ts` | Extension entry |
-
----
-
-## Testing Plan
-
-1. **Basic sync**: Create bd issue → verify sync
-2. **Auto-reminder**: Multi-step task → verify reminder appears
-3. **Integration**: Full workflow test
-
----
-
-## Notes
-
-- The implementation uses lazy imports to avoid breaking if dependencies are missing
-- bd CLI must be installed for full functionality
-- rpiv-todo is optional (fallback mode available)
-- Auto-reminder does NOT modify the overlay (it works fine)
-- Only injects context to prompt LLM to continue