@askjo/pi-reflect 1.0.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@askjo/pi-reflect",
+  "version": "1.0.0",
+  "description": "Self-improving behavioral files for pi coding agents. Analyzes session transcripts for correction patterns and makes surgical edits to prevent recurrence.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "coding-agent",
+    "self-improvement",
+    "agents-md",
+    "behavioral-rules",
+    "reflection"
+  ],
+  "license": "MIT",
+  "author": "Pradeep Elankumaran <pradeepe@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jo-inc/pi-reflect.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jo-inc/pi-reflect/issues"
+  },
+  "homepage": "https://github.com/jo-inc/pi-reflect#readme",
+  "type": "module",
+  "scripts": {
+    "test": "node --import tsx --test tests/*.test.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/jo-inc/pi-reflect/main/logo.png"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-ai": "*"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/tests/apply-edits.test.ts

@@ -0,0 +1,348 @@
+import { describe, it } from "node:test";
+import * as assert from "node:assert/strict";
+import { applyEdits, type AnalysisEdit } from "../extensions/reflect.js";
+import { SAMPLE_AGENTS_MD } from "./helpers.js";
+
+describe("applyEdits", () => {
+	// --- strengthen ---
+
+	it("applies a basic strengthen edit", () => {
+		const content = "- **Rule one**: Do the thing.\n- **Rule two**: Do another thing.";
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			old_text: "- **Rule one**: Do the thing.",
+			new_text: "- **Rule one** (CRITICAL): Do the thing immediately and without hesitation.",
+		}];
+		const { result, applied, skipped } = applyEdits(content, edits);
+		assert.equal(applied, 1);
+		assert.equal(skipped.length, 0);
+		assert.ok(result.includes("(CRITICAL): Do the thing immediately"));
+		assert.ok(!result.includes("Do the thing."));
+		assert.ok(result.includes("- **Rule two**: Do another thing."));
+	});
+
+	it("skips strengthen when old_text not found", () => {
+		const content = "- **Rule one**: Do the thing.";
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			old_text: "- **Rule one**: Do something completely different.",
+			new_text: "- **Rule one**: Replacement.",
+		}];
+		const { result, applied, skipped } = applyEdits(content, edits);
+		assert.equal(applied, 0);
+		assert.equal(skipped.length, 1);
+		assert.ok(skipped[0].includes("Could not find"));
+		assert.equal(result, content);
+	});
+
+	it("skips strengthen when old_text appears multiple times (ambiguous)", () => {
+		const content = "- Do the thing.\n- Do the thing.";
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			old_text: "- Do the thing.",
+			new_text: "- Do the thing better.",
+		}];
+		const { result, applied, skipped } = applyEdits(content, edits);
+		assert.equal(applied, 0);
+		assert.equal(skipped.length, 1);
+		assert.ok(skipped[0].includes("Ambiguous"));
+		assert.equal(result, content);
+	});
+
+	it("detects duplication in replacement text", () => {
+		// old_text is >50 chars, and new_text contains the first 50 chars twice
+		const oldText = "- **ALWAYS read existing code before writing any code**. The #1 source of rework is acting before understanding.";
+		const newText = oldText + " " + oldText; // obvious duplication
+		const content = `# Rules\n${oldText}\n- Other rule.`;
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			old_text: oldText,
+			new_text: newText,
+		}];
+		const { applied, skipped } = applyEdits(content, edits);
+		assert.equal(applied, 0);
+		assert.equal(skipped.length, 1);
+		assert.ok(skipped[0].includes("Duplication"));
+	});
+
+	it("allows strengthen when old_text < 50 chars (skips duplication check)", () => {
+		const content = "- Short rule here.\n- Another rule.";
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			old_text: "- Short rule here.",
+			new_text: "- Short rule here, but stronger.",
+		}];
+		const { applied, skipped } = applyEdits(content, edits);
+		assert.equal(applied, 1);
+		assert.equal(skipped.length, 0);
+	});
+
+	it("applies strengthen on the realistic AGENTS.md fixture", () => {
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			old_text: '- **Execute first, explain minimally**: Do the work, then say what you did in 1-2 sentences.',
+			new_text: '- **Execute first, explain minimally**: Do the work, then say what you did in 1-2 sentences. Skip "Let me explain..." and "Here\'s what I\'ll do..." intros — just do it.',
+		}];
+		const { result, applied } = applyEdits(SAMPLE_AGENTS_MD, edits);
+		assert.equal(applied, 1);
+		assert.ok(result.includes('Skip "Let me explain..."'));
+		// Original rule is replaced, not duplicated
+		const count = (result.match(/Execute first, explain minimally/g) || []).length;
+		assert.equal(count, 1);
+	});
+
+	// --- add ---
+
+	it("applies a basic add edit", () => {
+		const content = "- Rule A.\n- Rule B.";
+		const edits: AnalysisEdit[] = [{
+			type: "add",
+			after_text: "- Rule A.",
+			new_text: "- Rule A-prime: A new rule inserted after A.",
+		}];
+		const { result, applied, skipped } = applyEdits(content, edits);
+		assert.equal(applied, 1);
+		assert.equal(skipped.length, 0);
+		const lines = result.split("\n");
+		assert.equal(lines[0], "- Rule A.");
+		assert.equal(lines[1], "- Rule A-prime: A new rule inserted after A.");
+		assert.equal(lines[2], "- Rule B.");
+	});
+
+	it("skips add when after_text not found", () => {
+		const content = "- Rule A.\n- Rule B.";
+		const edits: AnalysisEdit[] = [{
+			type: "add",
+			after_text: "- Nonexistent rule.",
+			new_text: "- New rule.",
+		}];
+		const { applied, skipped } = applyEdits(content, edits);
+		assert.equal(applied, 0);
+		assert.ok(skipped[0].includes("Could not find insertion point"));
+	});
+
+	it("skips add when after_text is ambiguous", () => {
+		const content = "- Same rule.\n- Other stuff.\n- Same rule.";
+		const edits: AnalysisEdit[] = [{
+			type: "add",
+			after_text: "- Same rule.",
+			new_text: "- New rule.",
+		}];
+		const { applied, skipped } = applyEdits(content, edits);
+		assert.equal(applied, 0);
+		assert.ok(skipped[0].includes("Ambiguous"));
+	});
+
+	it("skips add when new_text already exists in file (dedup)", () => {
+		const content = "- Rule A.\n- Rule B.\n- Already here.";
+		const edits: AnalysisEdit[] = [{
+			type: "add",
+			after_text: "- Rule A.",
+			new_text: "- Already here.",
+		}];
+		const { applied, skipped } = applyEdits(content, edits);
+		assert.equal(applied, 0);
+		assert.ok(skipped[0].includes("already exists"));
+	});
+
+	it("dedup check trims whitespace before comparing", () => {
+		const content = "- Rule A.\n- Rule B.\n- Already here.";
+		const edits: AnalysisEdit[] = [{
+			type: "add",
+			after_text: "- Rule A.",
+			new_text: "  - Already here.  ",
+		}];
+		const { applied, skipped } = applyEdits(content, edits);
+		assert.equal(applied, 0);
+		assert.ok(skipped[0].includes("already exists"));
+	});
+
+	it("adds to realistic AGENTS.md fixture", () => {
+		const edits: AnalysisEdit[] = [{
+			type: "add",
+			after_text: "- **Keep code DRY**: NEVER duplicate logic.",
+			new_text: '- **Check recent git commits when debugging**: ALWAYS run `git log --oneline -10` before diagnosing issues.',
+		}];
+		const { result, applied } = applyEdits(SAMPLE_AGENTS_MD, edits);
+		assert.equal(applied, 1);
+		assert.ok(result.includes("Check recent git commits"));
+		// Verify it's after the DRY rule
+		const dryIdx = result.indexOf("Keep code DRY");
+		const newIdx = result.indexOf("Check recent git commits");
+		assert.ok(newIdx > dryIdx);
+	});
+
+	// --- multiple edits ---
+
+	it("applies multiple edits in sequence", () => {
+		const edits: AnalysisEdit[] = [
+			{
+				type: "strengthen",
+				old_text: "- **Keep code DRY**: NEVER duplicate logic.",
+				new_text: "- **Keep code DRY (CRITICAL)**: NEVER duplicate logic. If two call sites need different behavior, add parameters.",
+			},
+			{
+				type: "add",
+				after_text: "- **NEVER push to main/master**: Pushing to main triggers production deployment.",
+				new_text: "- **Never deploy without explicit instruction**: Commit changes and report ready — user decides when to push.",
+			},
+		];
+		const { result, applied, skipped } = applyEdits(SAMPLE_AGENTS_MD, edits);
+		assert.equal(applied, 2);
+		assert.equal(skipped.length, 0);
+		assert.ok(result.includes("Keep code DRY (CRITICAL)"));
+		assert.ok(result.includes("Never deploy without explicit instruction"));
+	});
+
+	it("later edits see results of earlier edits (sequential application)", () => {
+		const content = "- Rule A: original.\n- Rule B: original.";
+		const edits: AnalysisEdit[] = [
+			{
+				type: "strengthen",
+				old_text: "- Rule A: original.",
+				new_text: "- Rule A: modified.",
+			},
+			{
+				type: "add",
+				after_text: "- Rule A: modified.",
+				new_text: "- Rule A-bis: added after modified A.",
+			},
+		];
+		const { result, applied } = applyEdits(content, edits);
+		assert.equal(applied, 2);
+		assert.ok(result.includes("Rule A: modified."));
+		assert.ok(result.includes("Rule A-bis: added after modified A."));
+	});
+
+	it("partial success: some edits apply, some skip", () => {
+		const content = "- Real rule.\n- Other rule.";
+		const edits: AnalysisEdit[] = [
+			{
+				type: "strengthen",
+				old_text: "- Real rule.",
+				new_text: "- Real rule, now stronger.",
+			},
+			{
+				type: "strengthen",
+				old_text: "- Ghost rule that does not exist.",
+				new_text: "- This should not apply.",
+			},
+		];
+		const { result, applied, skipped } = applyEdits(content, edits);
+		assert.equal(applied, 1);
+		assert.equal(skipped.length, 1);
+		assert.ok(result.includes("now stronger"));
+		assert.ok(!result.includes("should not apply"));
+	});
+
+	// --- invalid edits ---
+
+	it("skips edit with missing type", () => {
+		const content = "- Rule.";
+		const edits = [{ new_text: "- Replacement." }] as any;
+		const { applied, skipped } = applyEdits(content, edits);
+		assert.equal(applied, 0);
+		assert.ok(skipped[0].includes("Invalid edit"));
+	});
+
+	it("skips strengthen with null old_text", () => {
+		const content = "- Rule.";
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			old_text: null,
+			new_text: "- Replacement.",
+		}];
+		const { applied, skipped } = applyEdits(content, edits);
+		assert.equal(applied, 0);
+		assert.equal(skipped.length, 1);
+	});
+
+	it("skips add with null after_text", () => {
+		const content = "- Rule.";
+		const edits: AnalysisEdit[] = [{
+			type: "add",
+			after_text: null,
+			new_text: "- New rule.",
+		}];
+		const { applied, skipped } = applyEdits(content, edits);
+		assert.equal(applied, 0);
+		assert.equal(skipped.length, 1);
+	});
+
+	it("skips add with empty new_text", () => {
+		const content = "- Rule.";
+		const edits: AnalysisEdit[] = [{
+			type: "add",
+			after_text: "- Rule.",
+			new_text: "",
+		}];
+		const { applied, skipped } = applyEdits(content, edits);
+		assert.equal(applied, 0);
+		assert.equal(skipped.length, 1);
+	});
+
+	// --- edge cases ---
+
+	it("handles empty edits array", () => {
+		const content = "- Rule.";
+		const { result, applied, skipped } = applyEdits(content, []);
+		assert.equal(applied, 0);
+		assert.equal(skipped.length, 0);
+		assert.equal(result, content);
+	});
+
+	it("handles empty content", () => {
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			old_text: "- Rule.",
+			new_text: "- Better rule.",
+		}];
+		const { applied, skipped } = applyEdits("", edits);
+		assert.equal(applied, 0);
+		assert.equal(skipped.length, 1);
+	});
+
+	it("preserves content before and after the edit region exactly", () => {
+		const before = "# Header\n\nSome preamble text.\n\n";
+		const target = "- **Target rule**: Original wording.";
+		const after = "\n\n## Footer\n\nClosing text.";
+		const content = before + target + after;
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			old_text: target,
+			new_text: "- **Target rule**: Improved wording.",
+		}];
+		const { result, applied } = applyEdits(content, edits);
+		assert.equal(applied, 1);
+		assert.ok(result.startsWith(before));
+		assert.ok(result.endsWith(after));
+		assert.ok(result.includes("Improved wording."));
+	});
+
+	it("handles regex special characters in old_text for duplication check", () => {
+		// old_text contains chars that are regex-special: ( ) . * + ?
+		const oldText = "- **Rule (important)**: Use regex.* patterns? Yes, absolutely. Use $HOME and [brackets].";
+		const content = `# Rules\n${oldText}\n- Other.`;
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			old_text: oldText,
+			new_text: "- **Rule (important, CRITICAL)**: Use regex.* patterns? Yes, absolutely. Use $HOME and [brackets]. Always.",
+		}];
+		const { applied, skipped } = applyEdits(content, edits);
+		assert.equal(applied, 1);
+		assert.equal(skipped.length, 0);
+	});
+
+	it("handles multiline old_text in strengthen", () => {
+		const content = "- **Rule**: Line one.\n  Continuation line.\n- Next rule.";
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			old_text: "- **Rule**: Line one.\n  Continuation line.",
+			new_text: "- **Rule**: Line one, improved.\n  Continuation line, also improved.",
+		}];
+		const { result, applied } = applyEdits(content, edits);
+		assert.equal(applied, 1);
+		assert.ok(result.includes("Line one, improved."));
+		assert.ok(result.includes("Continuation line, also improved."));
+	});
+});

package/tests/command-source.test.ts

@@ -0,0 +1,54 @@
+import { describe, it } from "node:test";
+import * as assert from "node:assert/strict";
+import { collectTranscriptsFromCommand } from "../extensions/reflect.js";
+
+describe("collectTranscriptsFromCommand", () => {
+	it("executes a command and returns its output", async () => {
+		const result = await collectTranscriptsFromCommand("echo 'hello world'", 1, 1024 * 1024);
+		assert.ok(result.transcripts.includes("hello world"));
+		assert.equal(result.sessionCount, 1); // no ### Session: headers, defaults to 1
+		assert.equal(result.includedCount, 1);
+	});
+
+	it("interpolates {lookbackDays} in command", async () => {
+		const result = await collectTranscriptsFromCommand("echo 'days={lookbackDays}'", 7, 1024 * 1024);
+		assert.ok(result.transcripts.includes("days=7"));
+	});
+
+	it("interpolates multiple {lookbackDays} occurrences", async () => {
+		const result = await collectTranscriptsFromCommand("echo '{lookbackDays} and {lookbackDays}'", 3, 1024 * 1024);
+		assert.ok(result.transcripts.includes("3 and 3"));
+	});
+
+	it("counts ### Session: headers for session count", async () => {
+		const multiSession = "echo '### Session: one\\n### Session: two\\n### Session: three'";
+		const result = await collectTranscriptsFromCommand(multiSession, 1, 1024 * 1024);
+		assert.equal(result.sessionCount, 3);
+	});
+
+	it("truncates output exceeding maxBytes", async () => {
+		// maxBytes=500, maxBuffer=1000. Command outputs 800 bytes (> maxBytes but < maxBuffer).
+		// Output should succeed but get truncated to 500 + truncation message.
+		const result = await collectTranscriptsFromCommand(
+			"printf '%0800d' 0",
+			1,
+			500,
+		);
+		assert.ok(result.transcripts.length > 500, `Expected > 500 bytes, got ${result.transcripts.length}`);
+		assert.ok(result.transcripts.length < 800, `Expected < 800 bytes (trimmed), got ${result.transcripts.length}`);
+		assert.ok(result.transcripts.includes("[...truncated"));
+	});
+
+	it("returns empty on command failure", async () => {
+		const result = await collectTranscriptsFromCommand("false", 1, 1024);
+		assert.equal(result.transcripts, "");
+		assert.equal(result.sessionCount, 0);
+		assert.equal(result.includedCount, 0);
+	});
+
+	it("returns empty on nonexistent command", async () => {
+		const result = await collectTranscriptsFromCommand("nonexistent_command_xyz_123", 1, 1024);
+		assert.equal(result.transcripts, "");
+		assert.equal(result.sessionCount, 0);
+	});
+});

package/tests/config-and-history.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { makeTempDir, cleanup } from "./helpers.js";
+
+/**
+ * Config and history tests.
+ *
+ * loadConfig/saveConfig/loadHistory/saveHistory read from module-level constants
+ * (CONFIG_FILE, HISTORY_FILE). We can't easily redirect those without env var overrides.
+ * Instead, we test the serialization/deserialization logic by writing temp files
+ * and verifying the JSON structure matches what the functions expect.
+ */
+
+describe("config serialization", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = makeTempDir();
+	});
+
+	afterEach(() => {
+		cleanup(tmpDir);
+	});
+
+	it("config round-trips through JSON correctly", () => {
+		const config = {
+			targets: [
+				{
+					path: "/path/to/AGENTS.md",
+					schedule: "daily",
+					model: "anthropic/claude-sonnet-4-5",
+					lookbackDays: 1,
+					maxSessionBytes: 614400,
+					backupDir: "~/.pi/agent/reflect-backups",
+					transcriptSource: { type: "pi-sessions" },
+				},
+			],
+		};
+		const fp = path.join(tmpDir, "config.json");
+		fs.writeFileSync(fp, JSON.stringify(config, null, 2));
+		const parsed = JSON.parse(fs.readFileSync(fp, "utf-8"));
+		assert.deepEqual(parsed, config);
+	});
+
+	it("config with command transcript source round-trips", () => {
+		const config = {
+			targets: [
+				{
+					path: "/path/to/SOUL.md",
+					schedule: "daily",
+					model: "anthropic/claude-sonnet-4-5",
+					lookbackDays: 7,
+					maxSessionBytes: 614400,
+					backupDir: "~/.pi/agent/reflect-backups",
+					transcriptSource: {
+						type: "command",
+						command: "python extract.py {lookbackDays}",
+					},
+				},
+			],
+		};
+		const fp = path.join(tmpDir, "config.json");
+		fs.writeFileSync(fp, JSON.stringify(config, null, 2));
+		const parsed = JSON.parse(fs.readFileSync(fp, "utf-8"));
+		assert.equal(parsed.targets[0].transcriptSource.type, "command");
+		assert.equal(parsed.targets[0].transcriptSource.command, "python extract.py {lookbackDays}");
+	});
+
+	it("partial config gets defaults merged", () => {
+		// Simulate what loadConfig does: merge with DEFAULT_TARGET
+		const DEFAULT_TARGET = {
+			path: "",
+			schedule: "daily",
+			model: "anthropic/claude-sonnet-4-5",
+			lookbackDays: 1,
+			maxSessionBytes: 600 * 1024,
+			backupDir: "default-backup",
+			transcriptSource: { type: "pi-sessions" },
+		};
+		const partial = { path: "/my/file.md" };
+		const merged = { ...DEFAULT_TARGET, ...partial };
+		assert.equal(merged.path, "/my/file.md");
+		assert.equal(merged.model, "anthropic/claude-sonnet-4-5");
+		assert.equal(merged.lookbackDays, 1);
+		assert.equal(merged.transcriptSource.type, "pi-sessions");
+	});
+
+	it("target-level overrides take precedence over defaults", () => {
+		const DEFAULT_TARGET = {
+			path: "",
+			schedule: "daily" as const,
+			model: "anthropic/claude-sonnet-4-5",
+			lookbackDays: 1,
+			maxSessionBytes: 600 * 1024,
+			backupDir: "default-backup",
+			transcriptSource: { type: "pi-sessions" as const },
+		};
+		const override = {
+			path: "/my/file.md",
+			model: "google/gemini-2.5-pro",
+			lookbackDays: 7,
+		};
+		const merged = { ...DEFAULT_TARGET, ...override };
+		assert.equal(merged.model, "google/gemini-2.5-pro");
+		assert.equal(merged.lookbackDays, 7);
+		assert.equal(merged.schedule, "daily"); // kept default
+	});
+});
+
+describe("history serialization", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = makeTempDir();
+	});
+
+	afterEach(() => {
+		cleanup(tmpDir);
+	});
+
+	it("history round-trips through JSON", () => {
+		const runs = [
+			{
+				timestamp: "2026-02-12T20:22:25.000Z",
+				targetPath: "/path/to/AGENTS.md",
+				sessionsAnalyzed: 48,
+				correctionsFound: 135,
+				editsApplied: 7,
+				summary: "7 edits applied.",
+				diffLines: 20,
+			},
+		];
+		const fp = path.join(tmpDir, "history.json");
+		fs.writeFileSync(fp, JSON.stringify(runs, null, 2));
+		const parsed = JSON.parse(fs.readFileSync(fp, "utf-8"));
+		assert.deepEqual(parsed, runs);
+	});
+
+	it("history is trimmed to last 100 runs", () => {
+		const runs = Array.from({ length: 150 }, (_, i) => ({
+			timestamp: `2026-01-${String(i).padStart(3, "0")}`,
+			targetPath: "/path/to/AGENTS.md",
+			sessionsAnalyzed: 10,
+			correctionsFound: 5,
+			editsApplied: 2,
+			summary: `Run ${i}`,
+			diffLines: 3,
+		}));
+		const trimmed = runs.slice(-100);
+		assert.equal(trimmed.length, 100);
+		assert.equal(trimmed[0].summary, "Run 50");
+		assert.equal(trimmed[99].summary, "Run 149");
+	});
+
+	it("empty history returns empty array from JSON parse", () => {
+		const fp = path.join(tmpDir, "history.json");
+		fs.writeFileSync(fp, "[]");
+		const parsed = JSON.parse(fs.readFileSync(fp, "utf-8"));
+		assert.deepEqual(parsed, []);
+	});
+
+	it("malformed history file returns fallback empty array", () => {
+		const fp = path.join(tmpDir, "history.json");
+		fs.writeFileSync(fp, "not json");
+		let result: any[];
+		try {
+			result = JSON.parse(fs.readFileSync(fp, "utf-8"));
+		} catch {
+			result = [];
+		}
+		assert.deepEqual(result, []);
+	});
+});