pi-harness-runtime 0.9.7 → 0.9.11

package/packages/cookie-sanitizer/src/sync.ts

@@ -0,0 +1,304 @@
+/**
+ * Sync orchestrator — the heart of the sanitizer.
+ *
+ * Pipeline (per run):
+ *   1. Enumerate files in the drop folder (one level + one sublevel).
+ *   2. Read each file. Detect format. Parse.
+ *   3. Concatenate cookies from all parsed files.
+ *   4. Infer provider from filename + cookies.
+ *   5. Normalize (dedupe, expire, domain-match).
+ *   6. Serialize to Netscape and write to the canonical cache (atomic).
+ *
+ * Returns a SyncResult. Never throws — returns structured errors in `result.errors`.
+ *
+ * Sec-001: Cookie VALUES never appear in any log line. Diagnostics
+ * use file basenames and 64-char previews with values redacted.
+ */
+
+import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import type { CanonicalCookie, SyncOptions, SyncResult } from "./types.js";
+import { buildDetectedFile, safePreview } from "./detect-format.js";
+import { parseNetscape, serializeNetscape } from "./parse-netscape.js";
+import { parseEditThisCookieJson } from "./parse-json.js";
+import { normalize } from "./normalize.js";
+import { inferProvider } from "./infer-provider.js";
+import { atomicWriteFileSync, defaultCachePathFor } from "./atomic-write.js";
+
+/** Max depth for the drop-folder walk (one-level + one subfolder). */
+const MAX_DEPTH = 2;
+/** Max size of a single input file we'll parse (5 MB). */
+const MAX_INPUT_BYTES = 5 * 1024 * 1024;
+/** Default drop-folder location. */
+export const DEFAULT_DROP_DIR = join(
+	process.env.HOME ?? "/tmp",
+	".pi-harness-runtime",
+	"cookies",
+);
+
+/**
+ * Enumerate readable files inside `dir`, up to MAX_DEPTH.
+ * Returns absolute paths. Skips dotfiles, editor temp files.
+ *
+ * `excludePath` (optional) — absolute path of a file to skip, e.g.
+ * the canonical cache file (so we never recursively read it).
+ */
+export function enumerateDropFiles(
+	dir: string,
+	excludePath?: string,
+): string[] {
+	if (!existsSync(dir)) return [];
+	let stat;
+	try {
+		stat = statSync(dir);
+	} catch {
+		return [];
+	}
+	if (!stat.isDirectory()) return [];
+
+	const result: string[] = [];
+
+	function walk(current: string, depth: number) {
+		if (depth > MAX_DEPTH) return;
+		let entries: string[];
+		try {
+			entries = readdirSync(current);
+		} catch {
+			return;
+		}
+		for (const name of entries) {
+			// Skip dotfiles, editor temp/swap.
+			if (name.startsWith(".")) continue;
+			if (name.endsWith("~") || name.endsWith(".swp")) continue;
+
+			const full = join(current, name);
+			if (excludePath && full === excludePath) continue;
+
+			let st;
+			try {
+				st = statSync(full);
+			} catch {
+				continue;
+			}
+
+			if (st.isFile()) {
+				result.push(full);
+			} else if (st.isDirectory() && depth < MAX_DEPTH) {
+				walk(full, depth + 1);
+			}
+		}
+	}
+
+	walk(dir, 0);
+	return result;
+}
+
+/**
+ * Read a single input file as text, capped at MAX_INPUT_BYTES.
+ * Returns null + a `reason` if the file can't be read.
+ */
+export function readInputFile(filePath: string): {
+	text: string;
+	reason?: string;
+} {
+	let stat;
+	try {
+		stat = statSync(filePath);
+	} catch {
+		return { text: "", reason: "file not accessible" };
+	}
+	if (!stat.isFile()) return { text: "", reason: "not a regular file" };
+	if (stat.size > MAX_INPUT_BYTES) {
+		return { text: "", reason: `file too large (${stat.size} bytes)` };
+	}
+	try {
+		return { text: readFileSync(filePath, "utf8") };
+	} catch (e) {
+		return {
+			text: "",
+			reason: `read failed: ${e instanceof Error ? e.message : String(e)}`,
+		};
+	}
+}
+
+/**
+ * Run the full sync pipeline.
+ *
+ * Options:
+ *   - dropDir      default: ~/.pi-harness-runtime/cookies/
+ *   - cachePath    default: ~/.config/<provider>-cookies.txt
+ *   - providerHint override inference (skips filename/domain checks)
+ *   - dryRun       skip the actual file write (still returns would-be result)
+ *
+ * Returns a SyncResult. Never throws.
+ */
+export function sync(opts: SyncOptions = {}): SyncResult {
+	const dropDir = opts.dropDir ?? DEFAULT_DROP_DIR;
+
+	const tmpResult: SyncResult = {
+		provider: null,
+		processedFiles: [],
+		skippedFiles: [],
+		totalCookies: 0,
+		cachePath: "",
+		sourceDir: dropDir,
+		wrote: false,
+		errors: [],
+	};
+
+	const files = enumerateDropFiles(dropDir, opts.cachePath);
+	if (files.length === 0) {
+		// Nothing to do — no error, just nothing. Caller decides whether
+		// to surface this to the user.
+		return tmpResult;
+	}
+
+	const allCookies: CanonicalCookie[] = [];
+	let firstBasename: string | undefined;
+
+	for (const filePath of files) {
+		const { text, reason } = readInputFile(filePath);
+		if (reason) {
+			const det = buildDetectedFile(filePath, "");
+			tmpResult.skippedFiles.push({ basename: det.basename, reason });
+			tmpResult.errors.push({ basename: det.basename, message: reason });
+			continue;
+		}
+
+		const det = buildDetectedFile(filePath, text);
+		if (det.format == null) {
+			const preview = safePreview(text);
+			tmpResult.skippedFiles.push({
+				basename: det.basename,
+				reason: `unrecognised format (preview: ${preview})`,
+			});
+			tmpResult.errors.push({
+				basename: det.basename,
+				message: "unrecognised format",
+			});
+			continue;
+		}
+
+		let cookies: CanonicalCookie[] = [];
+		if (det.format === "netscape") {
+			cookies = parseNetscape(text);
+		} else if (det.format === "edit-this-cookie-json") {
+			cookies = parseEditThisCookieJson(text);
+		}
+
+		if (cookies.length === 0) {
+			tmpResult.skippedFiles.push({
+				basename: det.basename,
+				reason: `${det.format} parsed but yielded 0 cookies`,
+			});
+			continue;
+		}
+
+		allCookies.push(...cookies);
+		tmpResult.processedFiles.push(det.basename);
+		if (!firstBasename) firstBasename = det.basename;
+	}
+
+	if (allCookies.length === 0) {
+		return tmpResult;
+	}
+
+	const provider = inferProvider(firstBasename, allCookies, opts.providerHint);
+	if (!provider) {
+		tmpResult.errors.push({
+			basename: firstBasename ?? "<unknown>",
+			message: "could not infer provider (no filename/domain match)",
+		});
+		return tmpResult;
+	}
+	tmpResult.provider = provider;
+
+	const cachePath = opts.cachePath ?? defaultCachePathFor(provider);
+	tmpResult.cachePath = cachePath;
+
+	const normalized = normalize(allCookies, provider);
+	tmpResult.totalCookies = normalized.length;
+
+	if (normalized.length === 0) {
+		// All cookies were filtered (expired / wrong domain).
+		tmpResult.errors.push({
+			basename: firstBasename ?? "<unknown>",
+			message: "all cookies filtered (expired or wrong-provider domain)",
+		});
+		return tmpResult;
+	}
+
+	if (opts.dryRun) {
+		tmpResult.wrote = false;
+		return tmpResult;
+	}
+
+	const serialized = serializeNetscape(normalized);
+	try {
+		atomicWriteFileSync(cachePath, serialized);
+		tmpResult.wrote = true;
+	} catch (e) {
+		tmpResult.errors.push({
+			basename: firstBasename ?? "<unknown>",
+			message: `atomic write failed: ${e instanceof Error ? e.message : String(e)}`,
+		});
+	}
+
+	return tmpResult;
+}
+
+/**
+ * Has-any-input check: true if the drop folder has anything readable.
+ * Cheap — does a single `readdirSync`; no parsing.
+ */
+export function hasAnyCookieSource(
+	dropDir: string = DEFAULT_DROP_DIR,
+): boolean {
+	return enumerateDropFiles(dropDir).length > 0;
+}
+
+/**
+ * Convenience: cache path for the dominant provider in the drop folder,
+ * or null if nothing's there. Used by `footer-status.ts` to ask "should
+ * the footer hint point at this provider?"
+ */
+export function inferCachePath(
+	dropDir: string = DEFAULT_DROP_DIR,
+): string | null {
+	const files = enumerateDropFiles(dropDir);
+	if (files.length === 0) return null;
+
+	let firstBasename: string | undefined;
+	const cookies: CanonicalCookie[] = [];
+
+	for (const fp of files) {
+		const { text } = readInputFile(fp);
+		if (!text) continue;
+		const det = buildDetectedFile(fp, text);
+		if (!det.format) continue;
+		if (det.format === "netscape") cookies.push(...parseNetscape(text));
+		else if (det.format === "edit-this-cookie-json")
+			cookies.push(...parseEditThisCookieJson(text));
+		if (!firstBasename) firstBasename = det.basename;
+	}
+
+	const provider = inferProvider(firstBasename, cookies);
+	if (!provider) return null;
+	return defaultCachePathFor(provider);
+}
+
+export {
+	inferProvider,
+	inferProviderFromFilename,
+	inferProviderFromCookies,
+} from "./infer-provider.js";
+export { defaultCachePathFor } from "./atomic-write.js";
+export type {
+	SyncOptions,
+	SyncResult,
+	CanonicalCookie,
+	ProviderId,
+	DetectedFile,
+	CookieFileFormat,
+	WatcherEvent,
+} from "./types.js";

package/packages/cookie-sanitizer/src/types.ts

@@ -0,0 +1,101 @@
+/**
+ * Cookie sanitizer types.
+ *
+ * The data model is intentionally simple and explicit. Cookies flow in
+ * from one of two input formats (Netscape, EditThisCookie JSON), are
+ * normalised here into a canonical record, and written out as a single
+ * standard Netscape file by the writer.
+ *
+ * Cookie values are NEVER logged anywhere. They live in memory only
+ * for the duration of one parse → normalize → write cycle.
+ */
+
+/** Provider identifier — inferred from filename or dominant cookie domain. */
+export type ProviderId =
+	| "minimax"
+	| "anthropic"
+	| "openai"
+	| "glm"
+	| "openrouter"
+	| string;
+
+/** Input file format. */
+export type CookieFileFormat = "netscape" | "edit-this-cookie-json";
+
+/** A single cookie in canonical (post-normalize) form. */
+export interface CanonicalCookie {
+	/** Provider this cookie belongs to. Set during infer-provider pass. */
+	provider?: ProviderId;
+	/** Cookie name (e.g. "_token", "_ga"). Must be non-empty after normalization. */
+	name: string;
+	/** Cookie value. NEVER logged. */
+	value: string;
+	/** Cookie domain (e.g. ".minimax.io", "platform.minimax.io"). */
+	domain: string;
+	/** URL path this cookie applies to (default "/"). */
+	path: string;
+	/** Expires at — Unix seconds since epoch. NaN or undefined = session cookie. */
+	expires?: number;
+	/** Whether this is a Secure-only cookie (HTTPS-only). */
+	secure: boolean;
+	/** Whether this cookie is HTTP-only (no JS access). */
+	httpOnly: boolean;
+}
+
+/** Result of detecting a single file's format. */
+export interface DetectedFile {
+	/** Absolute path (or relative, in tests). */
+	path: string;
+	/** Filename only (no directory). Used for log lines — never the full path contents. */
+	basename: string;
+	/** Detected format. */
+	format: CookieFileFormat | null;
+	/** Raw text content (truncated to first 4096 chars for safety in debug logs). */
+	text: string;
+	/** Parse error if format is null. Null error means format is unknown. */
+	error?: string;
+}
+
+/** Sync result for the whole drop folder. */
+export interface SyncResult {
+	/** Provider that was inferred. Null if inference failed. */
+	provider: ProviderId | null;
+	/** Files considered (readable, recognized format). */
+	processedFiles: string[];
+	/** Files skipped (unreadable, unknown format). */
+	skippedFiles: Array<{ basename: string; reason: string }>;
+	/** Total cookies after dedupe across all files. */
+	totalCookies: number;
+	/** Path the canonical cache was written to (relative or absolute). */
+	cachePath: string;
+	/** Source path the cookies came from. */
+	sourceDir: string;
+	/** True if the cache was actually written (no-op if no new data). */
+	wrote: boolean;
+	/** Errors during sync (per-file, never value-bearing). */
+	errors: Array<{ basename: string; message: string }>;
+}
+
+/** Sync options. */
+export interface SyncOptions {
+	/** Override the default drop-folder location. */
+	dropDir?: string;
+	/** Override the default canonical cache location. */
+	cachePath?: string;
+	/** Provider hint (skips filename/domain inference). */
+	providerHint?: ProviderId;
+	/** Skip writing the cache file even if normalization produced cookies. */
+	dryRun?: boolean;
+}
+
+/** Watcher events emitted by the live watcher. */
+export type WatcherEvent =
+	| {
+			kind: "sync-ok";
+			provider: ProviderId;
+			cachePath: string;
+			cookies: number;
+	  }
+	| { kind: "sync-skip"; reason: string }
+	| { kind: "sync-error"; message: string }
+	| { kind: "watcher-error"; message: string };

package/packages/cookie-sanitizer/src/watcher.ts

@@ -0,0 +1,180 @@
+/**
+ * Live cookie-folder watcher.
+ *
+ * Wraps chokidar v5 with the project-specific options:
+ *  - `atomic: 100`           — EditThisCookie / browser exporters use atomic write
+ *  - `awaitWriteFinish`      — wait for size to settle before triggering
+ *  - `ignoreInitial: true`   — startup is handled by sync.ts separately
+ *  - `depth: 2`              — one level + one subfolder
+ *  - editor temp ignored
+ *
+ * Sec-001: Cookie values are NEVER logged. Diagnostics use only
+ * basenames, file paths, and event kinds.
+ */
+
+import chokidar, { type FSWatcher } from "chokidar";
+import { join } from "node:path";
+import { sync, type SyncOptions } from "./sync.js";
+import type { WatcherEvent } from "./types.js";
+
+/** Public watcher config. */
+export interface CookieWatcherConfig {
+	/** Folder to watch. Default: ~/.pi-harness-runtime/cookies/ */
+	dropDir: string;
+	/** Sync options passed through to the sync orchestrator. */
+	syncOptions?: SyncOptions;
+	/** Event sink. Required. */
+	onEvent: (event: WatcherEvent) => void;
+	/** Override the debounce window (ms). Default 250. */
+	debounceMs?: number;
+	/** Optional logger (defaults to console). */
+	logger?: (msg: string) => void;
+}
+
+const DEFAULT_DEBOUNCE_MS = 250;
+
+/** Wraps a chokidar watcher for the drop folder. */
+export class CookieWatcher {
+	private watcher: FSWatcher | null = null;
+	private debounceMs: number;
+	private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+	private log: (msg: string) => void;
+	private cfg: CookieWatcherConfig;
+	private running = false;
+
+	constructor(config: CookieWatcherConfig) {
+		this.cfg = config;
+		this.debounceMs = config.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+		this.log = config.logger ?? ((m) => console.log(`[cookie-sanitizer] ${m}`));
+	}
+
+	/** Start watching. Idempotent — calling twice is a no-op. */
+	start(): void {
+		if (this.running) return;
+		this.running = true;
+
+		this.watcher = chokidar.watch(this.cfg.dropDir, {
+			ignored: (targetPath: string) => {
+				const base = targetPath.split("/").pop() ?? "";
+				if (base.startsWith(".")) return true;
+				if (base.endsWith("~") || base.endsWith(".swp")) return true;
+				if (base.endsWith(".tmp")) return true;
+				// Exclude the canonical cache file (if specified) so the
+				// sanitizer's own write doesn't trigger a re-sync.
+				if (
+					this.cfg.syncOptions?.cachePath &&
+					targetPath === this.cfg.syncOptions.cachePath
+				) {
+					return true;
+				}
+				return false;
+			},
+			ignoreInitial: true,
+			persistent: true,
+			depth: 2,
+			atomic: 100,
+			awaitWriteFinish: {
+				stabilityThreshold: 200,
+				pollInterval: 50,
+			},
+		});
+
+		this.watcher.on("add", () => this.schedule());
+		this.watcher.on("change", () => this.schedule());
+		this.watcher.on("unlink", () => this.schedule());
+		this.watcher.on("error", (err: unknown) => {
+			this.log(
+				`watcher error: ${err instanceof Error ? err.message : String(err)}`,
+			);
+			this.cfg.onEvent({
+				kind: "watcher-error",
+				message: err instanceof Error ? err.message : String(err),
+			});
+		});
+
+		this.log(`watching ${this.cfg.dropDir}`);
+	}
+
+	/** Stop watching. Idempotent. */
+	async stop(): Promise<void> {
+		if (!this.running) return;
+		this.running = false;
+		if (this.debounceTimer) {
+			clearTimeout(this.debounceTimer);
+			this.debounceTimer = null;
+		}
+		if (this.watcher) {
+			await this.watcher.close();
+			this.watcher = null;
+		}
+		this.log("stopped");
+	}
+
+	/** Trigger a sync immediately (bypass debounce). */
+	triggerNow(): void {
+		if (this.debounceTimer) {
+			clearTimeout(this.debounceTimer);
+			this.debounceTimer = null;
+		}
+		this.runSync();
+	}
+
+	private schedule(): void {
+		if (this.debounceTimer) clearTimeout(this.debounceTimer);
+		this.debounceTimer = setTimeout(() => {
+			this.debounceTimer = null;
+			this.runSync();
+		}, this.debounceMs);
+	}
+
+	private runSync(): void {
+		try {
+			const result = sync(this.cfg.syncOptions ?? {});
+			if (result.errors.length > 0) {
+				for (const err of result.errors) {
+					this.cfg.onEvent({
+						kind: "sync-error",
+						message: `${err.basename}: ${err.message}`,
+					});
+				}
+			}
+			if (result.provider && result.wrote) {
+				this.cfg.onEvent({
+					kind: "sync-ok",
+					provider: result.provider,
+					cachePath: result.cachePath,
+					cookies: result.totalCookies,
+				});
+			} else if (
+				result.processedFiles.length === 0 &&
+				result.provider === null
+			) {
+				this.cfg.onEvent({
+					kind: "sync-skip",
+					reason: "no usable cookies found",
+				});
+			}
+		} catch (e) {
+			this.cfg.onEvent({
+				kind: "sync-error",
+				message: e instanceof Error ? e.message : String(e),
+			});
+		}
+	}
+}
+
+/** Factory: a watcher that writes to a default no-op logger. */
+export function createWatcher(
+	dropDir: string,
+	syncOptions: SyncOptions,
+	onEvent: (event: WatcherEvent) => void,
+): CookieWatcher {
+	return new CookieWatcher({ dropDir, syncOptions, onEvent });
+}
+
+/** Compute a sensible dropDir for a given HOME override (test seam). */
+export function defaultDropDir(
+	home: string = process.env.HOME ?? "/tmp",
+): string {
+	return join(home, ".pi-harness-runtime", "cookies");
+}

package/packages/cookie-sanitizer/test/infer.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Provider inference tests.
+ *
+ * Three inference passes:
+ *   1. filename hint
+ *   2. dominant domain (>= 80%)
+ *   3. null
+ *
+ * The `hint` parameter overrides all of the above.
+ */
+
+import { describe, it, expect } from "bun:test";
+import {
+	inferProvider,
+	inferProviderFromFilename,
+	inferProviderFromCookies,
+	knownProviders,
+} from "../src/infer-provider.js";
+import type { CanonicalCookie } from "../src/types.js";
+
+function cookie(domain: string, name = "n"): CanonicalCookie {
+	return {
+		name,
+		value: "v",
+		domain,
+		path: "/",
+		secure: false,
+		httpOnly: false,
+	};
+}
+
+describe("inferProviderFromFilename", () => {
+	it("matches known providers by name fragment", () => {
+		expect(inferProviderFromFilename("minimax-cookies.txt")).toBe("minimax");
+		expect(inferProviderFromFilename("anthropic-session.json")).toBe(
+			"anthropic",
+		);
+		expect(inferProviderFromFilename("openai-tokens.json")).toBe("openai");
+		expect(inferProviderFromFilename("glm-export.json")).toBe("glm");
+	});
+
+	it("returns null for unknown names", () => {
+		expect(inferProviderFromFilename("random-export.json")).toBe(null);
+		expect(inferProviderFromFilename("")).toBe(null);
+	});
+});
+
+describe("inferProviderFromCookies", () => {
+	it("returns provider when ≥ 80% of cookies match one domain", () => {
+		const cookies = [
+			cookie(".minimax.io"),
+			cookie("platform.minimax.io"),
+			cookie(".minimax.io"),
+			cookie(".minimax.io"),
+			cookie(".other.com", "x"),
+		];
+		// 4/5 = 80% → matches minimax
+		expect(inferProviderFromCookies(cookies)).toBe("minimax");
+	});
+
+	it("returns null when no single provider dominates", () => {
+		const cookies = [
+			cookie(".minimax.io", "a"),
+			cookie(".anthropic.com", "b"),
+			cookie(".openai.com", "c"),
+		];
+		expect(inferProviderFromCookies(cookies)).toBe(null);
+	});
+
+	it("returns null for empty input", () => {
+		expect(inferProviderFromCookies([])).toBe(null);
+	});
+});
+
+describe("inferProvider (combined)", () => {
+	it("explicit hint wins over everything", () => {
+		const cookies = [cookie(".minimax.io")];
+		expect(inferProvider("anthropic.json", cookies, "openai")).toBe("openai");
+	});
+
+	it("filename hint wins over domain inference", () => {
+		const cookies = [cookie(".openai.com")];
+		expect(inferProvider("minimax-2026.json", cookies)).toBe("minimax");
+	});
+
+	it("falls through to domain inference when no filename match", () => {
+		const cookies = [
+			cookie(".anthropic.com"),
+			cookie(".anthropic.com"),
+			cookie(".anthropic.com"),
+			cookie(".anthropic.com"),
+		];
+		expect(inferProvider("random.txt", cookies)).toBe("anthropic");
+	});
+
+	it("returns null when nothing matches", () => {
+		expect(inferProvider("random.txt", [cookie(".other.com")])).toBe(null);
+	});
+});
+
+describe("knownProviders", () => {
+	it("returns at least the bundled providers", () => {
+		const providers = knownProviders();
+		expect(providers).toContain("minimax");
+		expect(providers).toContain("anthropic");
+		expect(providers).toContain("openai");
+		expect(providers).toContain("glm");
+		expect(providers).toContain("openrouter");
+	});
+});