@bdsqqq/pi 0.0.1

package/dist/core/file-tracker.js

@@ -0,0 +1,439 @@
+import { createRequire } from "node:module";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+//#region packages/core/file-tracker/index.ts
+/**
+* file change tracker — persists before/after content to disk for undo_edit.
+*
+* each edit writes a JSON file to
+* ~/.pi/file-changes/{sessionId}/{toolCallId}.json containing
+* the full before/after content and a unified diff.
+*
+* branch awareness comes from the conversation tree, not from
+* this module. tool call IDs live in assistant messages — when
+* the user navigates branches, only tool calls on the active
+* branch are visible. the undo_edit tool filters by active
+* tool call IDs before consulting the disk.
+*/
+const getFileChangesDir = () => globalThis.__PI_FILE_CHANGES_DIR__ ?? path.join(os.homedir(), ".pi", "file-changes");
+function sessionDir(sessionId) {
+	return path.join(getFileChangesDir(), sessionId);
+}
+function changePath(sessionId, toolCallId, changeId) {
+	return path.join(sessionDir(sessionId), `${toolCallId}.${changeId}`);
+}
+/** ensure the session's file-changes directory exists. */
+function ensureDir(sessionId) {
+	const dir = sessionDir(sessionId);
+	if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+/**
+* record a file change to disk. call after performing the edit.
+* the toolCallId comes from the execute() function's first argument.
+* returns the change ID (UUID) for the written record.
+*
+* one tool call can produce multiple changes (e.g., Task sub-agent
+* creating several files). each gets a unique UUID, stored as
+* {toolCallId}.{uuid}.
+*/
+function saveChange(sessionId, toolCallId, change) {
+	ensureDir(sessionId);
+	const id = crypto.randomUUID();
+	const record = {
+		...change,
+		id,
+		reverted: false
+	};
+	fs.writeFileSync(changePath(sessionId, toolCallId, id), JSON.stringify(record, null, 2), "utf-8");
+	return id;
+}
+/**
+* load all change records for a tool call. one tool call can produce
+* multiple changes (different files), each with its own UUID.
+*/
+function loadChanges(sessionId, toolCallId) {
+	const dir = sessionDir(sessionId);
+	if (!fs.existsSync(dir)) return [];
+	const prefix = `${toolCallId}.`;
+	try {
+		return fs.readdirSync(dir).filter((f) => f.startsWith(prefix)).map((f) => {
+			try {
+				return JSON.parse(fs.readFileSync(path.join(dir, f), "utf-8"));
+			} catch {
+				return null;
+			}
+		}).filter((c) => c !== null);
+	} catch {
+		return [];
+	}
+}
+/**
+* mark a specific change as reverted and restore the file.
+* returns the change record, or null if not found / already reverted.
+*/
+function revertChange(sessionId, toolCallId, changeId) {
+	const p = changePath(sessionId, toolCallId, changeId);
+	if (!fs.existsSync(p)) return null;
+	let change;
+	try {
+		change = JSON.parse(fs.readFileSync(p, "utf-8"));
+	} catch {
+		return null;
+	}
+	if (change.reverted) return null;
+	const filePath = change.uri.replace(/^file:\/\//, "");
+	fs.writeFileSync(filePath, change.before, "utf-8");
+	change.reverted = true;
+	fs.writeFileSync(p, JSON.stringify(change, null, 2), "utf-8");
+	return change;
+}
+/**
+* find the most recent non-reverted change for a file path,
+* filtered to only the given tool call IDs (branch awareness).
+*
+* the caller gets activeToolCallIds by scanning the current
+* session branch for edit_file/create_file tool calls.
+*/
+function findLatestChange(sessionId, filePath, activeToolCallIds) {
+	const uri = `file://${path.resolve(filePath)}`;
+	for (let i = activeToolCallIds.length - 1; i >= 0; i--) {
+		const toolCallId = activeToolCallIds[i];
+		if (!toolCallId) continue;
+		const match = loadChanges(sessionId, toolCallId).filter((c) => !c.reverted && c.uri === uri).sort((a, b) => b.timestamp - a.timestamp)[0];
+		if (match) return {
+			toolCallId,
+			change: match
+		};
+	}
+	return null;
+}
+/**
+* graceful require for the `diff` package — falls back to a naive
+* line-by-line diff when the package isn't resolvable (same pattern
+* as cheerio in html-to-md.ts).
+*/
+let createPatchFn = null;
+try {
+	createPatchFn = createRequire(import.meta.url)("diff").createPatch;
+} catch {}
+/**
+* generate a unified diff between two strings.
+*
+* uses the `diff` npm package (Myers algorithm) when available for
+* proper hunk-based output with context lines. context=3 matches
+* git's default, producing gaps between distant changes that show()
+* can elide in collapsed display.
+*
+* falls back to a naive line-by-line comparison when `diff` isn't
+* installed (produces correct but less optimal output — every line
+* is either +, -, or context with no hunk headers).
+*/
+function simpleDiff(filePath, before, after) {
+	if (createPatchFn) {
+		const lines = createPatchFn(path.basename(filePath), before, after, "original", "modified", { context: 3 }).split("\n");
+		const startIdx = lines.findIndex((l) => l.startsWith("---"));
+		return (startIdx > 0 ? lines.slice(startIdx) : lines).join("\n");
+	}
+	const beforeLines = before.split("\n");
+	const afterLines = after.split("\n");
+	const lines = [`--- ${path.basename(filePath)}\toriginal`, `+++ ${path.basename(filePath)}\tmodified`];
+	let i = 0;
+	let j = 0;
+	while (i < beforeLines.length || j < afterLines.length) if (i < beforeLines.length && j < afterLines.length && beforeLines[i] === afterLines[j]) {
+		lines.push(` ${beforeLines[i]}`);
+		i++;
+		j++;
+	} else if (i < beforeLines.length && (j >= afterLines.length || beforeLines[i] !== afterLines[j])) {
+		lines.push(`-${beforeLines[i]}`);
+		i++;
+	} else {
+		lines.push(`+${afterLines[j]}`);
+		j++;
+	}
+	return lines.join("\n");
+}
+if (import.meta.vitest) {
+	const { describe, it, expect, beforeEach, afterEach } = import.meta.vitest;
+	let tmpDir;
+	let sessionId;
+	beforeEach(() => {
+		tmpDir = path.join(os.tmpdir(), `pi-file-tracker-test-${Date.now()}`);
+		fs.mkdirSync(tmpDir, { recursive: true });
+		sessionId = `test-session-${Date.now()}`;
+		globalThis.__PI_FILE_CHANGES_DIR__ = tmpDir;
+	});
+	afterEach(() => {
+		try {
+			fs.rmSync(tmpDir, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+	});
+	describe("simpleDiff", () => {
+		it("generates unified diff for added lines", () => {
+			const diff = simpleDiff("test.txt", "line1\nline2", "line1\nline2\nline3");
+			expect(diff).toContain("--- test.txt");
+			expect(diff).toContain("+++ test.txt");
+			expect(diff).toContain("+line3");
+		});
+		it("generates unified diff for removed lines", () => {
+			const diff = simpleDiff("test.txt", "line1\nline2\nline3", "line1\nline3");
+			expect(diff).toContain("-line2");
+			expect(diff).not.toContain("+line2");
+		});
+		it("generates unified diff for changed lines", () => {
+			const diff = simpleDiff("file.txt", "old content", "new content");
+			expect(diff).toContain("-old content");
+			expect(diff).toContain("+new content");
+		});
+		it("handles identical content (no changes)", () => {
+			const content = "same\nlines\nhere";
+			const diff = simpleDiff("same.txt", content, content);
+			expect(diff).toContain("--- same.txt");
+			expect(diff).toContain("+++ same.txt");
+			const lines = diff.split("\n");
+			const changedLines = lines.filter((l) => l.startsWith("-") && !l.startsWith("---"));
+			const addedLines = lines.filter((l) => l.startsWith("+") && !l.startsWith("+++"));
+			expect(changedLines).toHaveLength(0);
+			expect(addedLines).toHaveLength(0);
+		});
+		it("handles empty before content", () => {
+			expect(simpleDiff("new.txt", "", "new file content")).toContain("+new file content");
+		});
+		it("handles empty after content", () => {
+			expect(simpleDiff("del.txt", "deleted content", "")).toContain("-deleted content");
+		});
+		it("includes file basename in diff header", () => {
+			const diff = simpleDiff("/path/to/some/file.ts", "a", "b");
+			expect(diff).toContain("--- file.ts");
+			expect(diff).toContain("+++ file.ts");
+		});
+	});
+	describe("saveChange and loadChanges", () => {
+		it("saves a change record to disk and loads it back", () => {
+			const toolCallId = "tc-123";
+			const filePath = path.join(tmpDir, "test-file.txt");
+			const content = "file content here";
+			const changeId = saveChange(sessionId, toolCallId, {
+				uri: `file://${filePath}`,
+				before: "",
+				after: content,
+				diff: simpleDiff(filePath, "", content),
+				isNewFile: true,
+				timestamp: Date.now()
+			});
+			expect(changeId).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+			const changes = loadChanges(sessionId, toolCallId);
+			expect(changes).toHaveLength(1);
+			expect(changes[0].id).toBe(changeId);
+			expect(changes[0].uri).toBe(`file://${filePath}`);
+			expect(changes[0].before).toBe("");
+			expect(changes[0].after).toBe(content);
+			expect(changes[0].isNewFile).toBe(true);
+			expect(changes[0].reverted).toBe(false);
+		});
+		it("supports multiple changes per tool call", () => {
+			const toolCallId = "tc-multi";
+			const file1 = path.join(tmpDir, "file1.txt");
+			const file2 = path.join(tmpDir, "file2.txt");
+			const id1 = saveChange(sessionId, toolCallId, {
+				uri: `file://${file1}`,
+				before: "",
+				after: "content1",
+				diff: "",
+				isNewFile: true,
+				timestamp: Date.now()
+			});
+			const id2 = saveChange(sessionId, toolCallId, {
+				uri: `file://${file2}`,
+				before: "",
+				after: "content2",
+				diff: "",
+				isNewFile: true,
+				timestamp: Date.now()
+			});
+			expect(id1).not.toBe(id2);
+			const changes = loadChanges(sessionId, toolCallId);
+			expect(changes).toHaveLength(2);
+			const uris = changes.map((c) => c.uri);
+			expect(uris).toContain(`file://${file1}`);
+			expect(uris).toContain(`file://${file2}`);
+		});
+		it("returns empty array when no changes exist", () => {
+			expect(loadChanges(sessionId, "nonexistent-toolcall")).toEqual([]);
+		});
+		it("persists changes across calls (real disk)", () => {
+			const toolCallId = "tc-persist";
+			const filePath = path.join(tmpDir, "persist.txt");
+			saveChange(sessionId, toolCallId, {
+				uri: `file://${filePath}`,
+				before: "old",
+				after: "new",
+				diff: simpleDiff(filePath, "old", "new"),
+				isNewFile: false,
+				timestamp: Date.now()
+			});
+			const changes = loadChanges(sessionId, toolCallId);
+			expect(changes).toHaveLength(1);
+			expect(changes[0].before).toBe("old");
+			expect(changes[0].after).toBe("new");
+		});
+	});
+	describe("revertChange", () => {
+		it("restores file to before state and marks reverted", () => {
+			const toolCallId = "tc-revert";
+			const filePath = path.join(tmpDir, "to-revert.txt");
+			fs.writeFileSync(filePath, "original content", "utf-8");
+			const changeId = saveChange(sessionId, toolCallId, {
+				uri: `file://${filePath}`,
+				before: "original content",
+				after: "modified content",
+				diff: "",
+				isNewFile: false,
+				timestamp: Date.now()
+			});
+			fs.writeFileSync(filePath, "modified content", "utf-8");
+			expect(fs.readFileSync(filePath, "utf-8")).toBe("modified content");
+			const result = revertChange(sessionId, toolCallId, changeId);
+			expect(result).not.toBeNull();
+			expect(result?.reverted).toBe(true);
+			expect(fs.readFileSync(filePath, "utf-8")).toBe("original content");
+			expect(loadChanges(sessionId, toolCallId)[0].reverted).toBe(true);
+		});
+		it("returns null for nonexistent change", () => {
+			expect(revertChange(sessionId, "tc-xxx", "nonexistent-id")).toBeNull();
+		});
+		it("returns null for already reverted change", () => {
+			const toolCallId = "tc-revert-twice";
+			const filePath = path.join(tmpDir, "revert-once.txt");
+			fs.writeFileSync(filePath, "before", "utf-8");
+			const changeId = saveChange(sessionId, toolCallId, {
+				uri: `file://${filePath}`,
+				before: "before",
+				after: "after",
+				diff: "",
+				isNewFile: false,
+				timestamp: Date.now()
+			});
+			expect(revertChange(sessionId, toolCallId, changeId)).not.toBeNull();
+			expect(revertChange(sessionId, toolCallId, changeId)).toBeNull();
+		});
+		it("works for newly created files (isNewFile: true)", () => {
+			const toolCallId = "tc-newfile";
+			const filePath = path.join(tmpDir, "brand-new.txt");
+			const changeId = saveChange(sessionId, toolCallId, {
+				uri: `file://${filePath}`,
+				before: "",
+				after: "new file content",
+				diff: "",
+				isNewFile: true,
+				timestamp: Date.now()
+			});
+			fs.writeFileSync(filePath, "new file content", "utf-8");
+			expect(revertChange(sessionId, toolCallId, changeId)).not.toBeNull();
+			expect(fs.readFileSync(filePath, "utf-8")).toBe("");
+		});
+	});
+	describe("findLatestChange", () => {
+		it("finds the most recent change for a file", () => {
+			const tc1 = "tc-first";
+			const tc2 = "tc-second";
+			const filePath = path.join(tmpDir, "chain.txt");
+			saveChange(sessionId, tc1, {
+				uri: `file://${filePath}`,
+				before: "v1",
+				after: "v2",
+				diff: "",
+				isNewFile: false,
+				timestamp: Date.now() - 2e3
+			});
+			saveChange(sessionId, tc2, {
+				uri: `file://${filePath}`,
+				before: "v2",
+				after: "v3",
+				diff: "",
+				isNewFile: false,
+				timestamp: Date.now() - 1e3
+			});
+			const result = findLatestChange(sessionId, filePath, [tc1, tc2]);
+			expect(result).not.toBeNull();
+			expect(result?.change.before).toBe("v2");
+			expect(result?.change.after).toBe("v3");
+			expect(result?.toolCallId).toBe(tc2);
+		});
+		it("skips reverted changes", () => {
+			const tc1 = "tc-revert-skip";
+			const filePath = path.join(tmpDir, "skip-reverted.txt");
+			const changeId = saveChange(sessionId, tc1, {
+				uri: `file://${filePath}`,
+				before: "old",
+				after: "new",
+				diff: "",
+				isNewFile: false,
+				timestamp: Date.now()
+			});
+			const change = {
+				...loadChanges(sessionId, tc1)[0],
+				reverted: true
+			};
+			const changeFilePath = path.join(tmpDir, sessionId, `${tc1}.${changeId}`);
+			fs.writeFileSync(changeFilePath, JSON.stringify(change, null, 2), "utf-8");
+			expect(findLatestChange(sessionId, filePath, [tc1])).toBeNull();
+		});
+		it("respects branch order (activeToolCallIds order)", () => {
+			const tc1 = "tc-branch-1";
+			const tc2 = "tc-branch-2";
+			const filePath = path.join(tmpDir, "branch-order.txt");
+			saveChange(sessionId, tc1, {
+				uri: `file://${filePath}`,
+				before: "a",
+				after: "b",
+				diff: "",
+				isNewFile: false,
+				timestamp: Date.now() - 1e3
+			});
+			saveChange(sessionId, tc2, {
+				uri: `file://${filePath}`,
+				before: "c",
+				after: "d",
+				diff: "",
+				isNewFile: false,
+				timestamp: Date.now()
+			});
+			expect(findLatestChange(sessionId, filePath, [tc1, tc2])?.change.after).toBe("d");
+			expect(findLatestChange(sessionId, filePath, [tc1])?.change.after).toBe("b");
+		});
+		it("returns null when file has no changes", () => {
+			expect(findLatestChange(sessionId, "/nonexistent/file.txt", ["tc-x"])).toBeNull();
+		});
+		it("handles multiple changes to different files in same tool call", () => {
+			const tc = "tc-multi-file";
+			const file1 = path.join(tmpDir, "multi1.txt");
+			const file2 = path.join(tmpDir, "multi2.txt");
+			saveChange(sessionId, tc, {
+				uri: `file://${file1}`,
+				before: "",
+				after: "f1",
+				diff: "",
+				isNewFile: true,
+				timestamp: Date.now() - 1e3
+			});
+			saveChange(sessionId, tc, {
+				uri: `file://${file2}`,
+				before: "",
+				after: "f2",
+				diff: "",
+				isNewFile: true,
+				timestamp: Date.now()
+			});
+			const result1 = findLatestChange(sessionId, file1, [tc]);
+			const result2 = findLatestChange(sessionId, file2, [tc]);
+			expect(result1?.change.after).toBe("f1");
+			expect(result2?.change.after).toBe("f2");
+		});
+	});
+}
+//#endregion
+export { findLatestChange, loadChanges, revertChange, saveChange, simpleDiff };

package/dist/core/github-api.d.ts

@@ -0,0 +1,45 @@
+//#region packages/core/github-api/index.d.ts
+interface RepoRef {
+  owner: string;
+  repo: string;
+}
+/**
+* parse a repository URL or shorthand into owner/repo.
+* accepts:
+*   - https://github.com/owner/repo
+*   - github.com/owner/repo
+*   - owner/repo
+*/
+declare function parseRepoUrl(input: string): RepoRef;
+/** build the "owner/repo" string for gh api paths. */
+declare function repoSlug(ref: RepoRef): string;
+/**
+* call `gh api` and return parsed JSON.
+* throws on non-zero exit or JSON parse failure.
+*
+* params are appended as query string (GET-safe). gh api's `-f` flag
+* forces POST, which breaks search/list endpoints.
+*/
+declare function ghApi<T = any>(endpoint: string, opts?: {
+  method?: string;
+  params?: Record<string, string | number>;
+  rawOutput?: boolean;
+  accept?: string;
+}): T;
+/**
+* paginated gh api call. collects items across pages.
+* github REST APIs return arrays for list endpoints.
+*/
+declare function ghApiPaginated<T = any>(endpoint: string, opts?: {
+  params?: Record<string, string | number>;
+  limit?: number;
+  offset?: number;
+}): T[];
+/** decode base64 content from github contents API. */
+declare function decodeBase64Content(encoded: string): string;
+/** add line numbers to file content. */
+declare function addLineNumbers(content: string, startLine?: number): string;
+/** truncate string to max length with indicator. */
+declare function truncate(text: string, maxLen: number): string;
+//#endregion
+export { RepoRef, addLineNumbers, decodeBase64Content, ghApi, ghApiPaginated, parseRepoUrl, repoSlug, truncate };

package/dist/core/github-api.js

@@ -0,0 +1,101 @@
+import { spawnSync } from "node:child_process";
+//#region packages/core/github-api/index.ts
+/**
+* shared helpers for github tools.
+*
+* wraps `gh api` CLI calls. requires gh CLI authenticated
+* (GH_TOKEN or `gh auth login`). all tools parse repository
+* URLs in the format "https://github.com/owner/repo" or
+* shorthand "owner/repo".
+*/
+/**
+* parse a repository URL or shorthand into owner/repo.
+* accepts:
+*   - https://github.com/owner/repo
+*   - github.com/owner/repo
+*   - owner/repo
+*/
+function parseRepoUrl(input) {
+	const parts = input.replace(/^https?:\/\//, "").replace(/^github\.com\//, "").replace(/\.git$/, "").replace(/\/$/, "").split("/");
+	if (parts.length < 2) throw new Error(`invalid repository: "${input}" — expected "owner/repo" or full URL`);
+	return {
+		owner: parts[0],
+		repo: parts[1]
+	};
+}
+/** build the "owner/repo" string for gh api paths. */
+function repoSlug(ref) {
+	return `${ref.owner}/${ref.repo}`;
+}
+/**
+* call `gh api` and return parsed JSON.
+* throws on non-zero exit or JSON parse failure.
+*
+* params are appended as query string (GET-safe). gh api's `-f` flag
+* forces POST, which breaks search/list endpoints.
+*/
+function ghApi(endpoint, opts) {
+	let url = endpoint;
+	if (opts?.params) {
+		const qs = Object.entries(opts.params).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`).join("&");
+		url += (url.includes("?") ? "&" : "?") + qs;
+	}
+	const args = [
+		"gh",
+		"api",
+		url
+	];
+	if (opts?.method) args.push("--method", opts.method);
+	if (opts?.accept) args.push("-H", `Accept: ${opts.accept}`);
+	const result = spawnSync("gh", args.slice(1), {
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		encoding: "utf-8",
+		maxBuffer: 10 * 1024 * 1024
+	});
+	if (result.status !== 0) {
+		const stderr = result.stderr?.trim() || "unknown error";
+		throw new Error(`gh api ${endpoint} failed: ${stderr}`);
+	}
+	const stdout = result.stdout?.trim() || "";
+	if (opts?.rawOutput) return stdout;
+	try {
+		return JSON.parse(stdout);
+	} catch {
+		throw new Error(`gh api ${endpoint}: invalid JSON response`);
+	}
+}
+/**
+* paginated gh api call. collects items across pages.
+* github REST APIs return arrays for list endpoints.
+*/
+function ghApiPaginated(endpoint, opts) {
+	const limit = opts?.limit ?? 30;
+	const offset = opts?.offset ?? 0;
+	const perPage = Math.min(limit, 100);
+	const page = Math.floor(offset / perPage) + 1;
+	const result = ghApi(endpoint, { params: {
+		...opts?.params,
+		per_page: perPage,
+		page
+	} });
+	return Array.isArray(result) ? result.slice(0, limit) : [];
+}
+/** decode base64 content from github contents API. */
+function decodeBase64Content(encoded) {
+	return Buffer.from(encoded.replace(/\n/g, ""), "base64").toString("utf-8");
+}
+/** add line numbers to file content. */
+function addLineNumbers(content, startLine = 1) {
+	return content.split("\n").map((line, i) => `${startLine + i}: ${line}`).join("\n");
+}
+/** truncate string to max length with indicator. */
+function truncate(text, maxLen) {
+	if (text.length <= maxLen) return text;
+	return `${text.slice(0, maxLen)}\n... (truncated, ${text.length} total characters)`;
+}
+//#endregion
+export { addLineNumbers, decodeBase64Content, ghApi, ghApiPaginated, parseRepoUrl, repoSlug, truncate };

package/dist/core/html-to-md.d.ts

@@ -0,0 +1,5 @@
+//#region packages/core/html-to-md/index.d.ts
+declare function isHtml(text: string): boolean;
+declare function htmlToMarkdown(html: string): string | null;
+//#endregion
+export { htmlToMarkdown, isHtml };