pi-crew 0.9.53 → 0.9.55

package/src/utils/ndjson.ts

@@ -0,0 +1,115 @@
+/**
+ * ndjson.ts — Canonical broker NDJSON framing primitives (encoder + decoder
+ *              + typed errors). Newline-delimited JSON, one frame per `\\n`.
+ *
+ * Moved out of the parallel-work stub `src/runtime/crew-broker-deps.ts`.
+ * The public surface (MAX_BROKER_FRAME_BYTES, BrokerError, BrokerErrorCode,
+ * encodeBrokerFrame, NdjsonDecoder) is preserved verbatim so importers
+ * can be updated with a single import-path change.
+ *
+ * No internal dependencies on other src/ modules — only Node built-ins.
+ */
+
+/** Maximum encoded NDJSON frame size in UTF-8 bytes, INCLUDING the trailing `\n`. */
+export const MAX_BROKER_FRAME_BYTES = 256 * 1024;
+
+// ============================================================================
+// BrokerError — typed protocol errors
+// ============================================================================
+
+export type BrokerErrorCode = "oversize-frame" | "auth" | "protocol" | "timeout" | "close" | "not-implemented" | "rate-limit";
+
+export class BrokerError extends Error {
+	readonly code: BrokerErrorCode;
+	constructor(code: BrokerErrorCode, message: string) {
+		super(message);
+		this.name = "BrokerError";
+		this.code = code;
+	}
+}
+
+// ============================================================================
+// NDJSON encoder
+// ============================================================================
+
+/**
+ * Encode a value as a single NDJSON frame (one JSON object terminated by `\n`).
+ * Rejects values whose encoded byte length exceeds MAX_BROKER_FRAME_BYTES BEFORE
+ * returning. Throws BrokerError("oversize-frame") for over-size payloads.
+ */
+export function encodeBrokerFrame(value: unknown): Buffer {
+	// Stringify with replacer to drop undefined/function values (matches JSON.stringify semantics).
+	const json = JSON.stringify(value);
+	if (json === undefined) {
+		// Cannot encode (e.g. circular) — surface a typed protocol error.
+		throw new BrokerError("protocol", "encodeBrokerFrame: value is not JSON-serializable");
+	}
+	const enc = Buffer.from(json, "utf8");
+	// +1 for the trailing '\n'.
+	if (enc.length + 1 > MAX_BROKER_FRAME_BYTES) {
+		throw new BrokerError("oversize-frame", `frame exceeds ${MAX_BROKER_FRAME_BYTES} bytes (got ${enc.length + 1})`);
+	}
+	const out = Buffer.allocUnsafe(enc.length + 1);
+	enc.copy(out);
+	out[enc.length] = 0x0a; // '\n'
+	return out;
+}
+
+// ============================================================================
+// NDJSON decoder
+// ============================================================================
+
+/** Cap the partial-frame accumulator to 2 * MAX_BROKER_FRAME_BYTES. Beyond that
+ *  we surface oversize-frame and let the caller close. The 2x headroom is
+ *  enough to assemble one full frame from chunks of any size. */
+const MAX_DECODER_BUFFER = 2 * MAX_BROKER_FRAME_BYTES;
+
+export class NdjsonDecoder {
+	private buffer: Buffer = Buffer.alloc(0);
+
+	/**
+	 * Push a chunk; return the array of complete parsed values (each was
+	 * followed by a `\n` in the stream). May return zero items (no full
+	 * frame yet), one item, or many items. Malformed JSON throws
+	 * BrokerError("protocol"); over-size accumulated buffer throws
+	 * BrokerError("oversize-frame"). Callers must catch and close the socket.
+	 */
+	push(chunk: Buffer): unknown[] {
+		if (chunk.length === 0) return [];
+		this.buffer = this.buffer.length === 0 ? chunk : Buffer.concat([this.buffer, chunk]);
+		if (this.buffer.length > MAX_DECODER_BUFFER) {
+			throw new BrokerError("oversize-frame", `decoder buffer exceeded ${MAX_DECODER_BUFFER} bytes`);
+		}
+		const out: unknown[] = [];
+		let idx = this.buffer.indexOf(0x0a);
+		while (idx !== -1) {
+			const line = this.buffer.subarray(0, idx);
+			// Empty lines are skipped (lenient — mirrors herdr/NDJSON practice).
+			if (line.length > 0) {
+				// Reject an oversize LINE before parse.
+				if (line.length > MAX_BROKER_FRAME_BYTES) {
+					throw new BrokerError("oversize-frame", `line exceeds ${MAX_BROKER_FRAME_BYTES} bytes (got ${line.length})`);
+				}
+				try {
+					out.push(JSON.parse(line.toString("utf8")));
+				} catch (cause) {
+					throw new BrokerError("protocol", `ndjson: malformed JSON: ${(cause as Error).message}`);
+				}
+			}
+			// Advance past the consumed line + newline.
+			this.buffer = this.buffer.subarray(idx + 1);
+			idx = this.buffer.indexOf(0x0a);
+		}
+		return out;
+	}
+
+	reset(): void {
+		this.buffer = Buffer.alloc(0);
+	}
+}
+
+// ============================================================================
+// External re-exports
+// ============================================================================
+// Re-exported here for callers that import all broker primitives from ndjson.ts.
+export { newBrokerToken } from "../runtime/crew-broker-tokens.ts";

package/src/utils/paths.ts

@@ -0,0 +1,227 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function packageRoot(): string {
+	// Phase 5 H2 follow-up: this function is called from both src/ paths
+	// (e.g. src/utils/paths.ts) AND from dist/index.mjs after bundling.
+	// The original 2-level walk only worked for src/ paths:
+	//   src/utils/paths.ts → src/utils/ → src/ → packageRoot
+	// For dist/index.mjs we need only 1 level:
+	//   dist/index.mjs → dist/ → packageRoot
+	// Heuristic: walk up from `import.meta.url`'s directory until we find
+	// a directory that contains `package.json` with our package name. This
+	// is robust to either entrypoint and to future relocation (e.g., a
+	// monorepo layout under `packages/pi-crew/dist/index.mjs` would walk
+	// 2 levels from dist).
+	let dir = path.dirname(fileURLToPath(import.meta.url));
+	for (let i = 0; i < 6; i++) {
+		const candidate = path.join(dir, "package.json");
+		if (fs.existsSync(candidate)) {
+			try {
+				const pkg = JSON.parse(fs.readFileSync(candidate, "utf-8")) as { name?: string };
+				if (pkg.name === "pi-crew") {
+					return dir;
+				}
+			} catch {
+				// Unreadable or invalid JSON — keep walking.
+			}
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	// Fallback: 2-level walk (matches original src/ semantics). Bundles
+	// that don't ship a package.json (very unusual) will get a wrong path
+	// here, but that's a build-pipeline bug we want to surface, not hide.
+	return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+}
+
+export function userPiRoot(): string {
+	// F4: a misconfigured PI_TEAMS_HOME can be the literal string "undefined"
+	// (e.g. PI_TEAMS_HOME=$UNSET_VAR in a shell), which would build paths like
+	// "undefined/.pi/agent" relative to cwd and silently create a junk "undefined/"
+	// tree. Treat the literal "undefined" (and empty) as unset and fall back to
+	// os.homedir().
+	const rawHome = (process.env.PI_TEAMS_HOME ?? process.env.PI_CREW_HOME)?.trim();
+	const home = rawHome && rawHome !== "undefined" ? rawHome : os.homedir();
+	const resolved = path.join(home, ".pi", "agent");
+
+	// Reject symlinks to prevent confusion attacks where PI_TEAMS_HOME points to
+	// an attacker-controlled target via a user-owned symlink.
+	// We use lstatSync (does NOT follow) to detect symlinks before they are resolved.
+	// ENOENT is acceptable — the directory may not exist yet (caller will create it).
+	let isSymlink = false;
+	try {
+		const lstats = fs.lstatSync(resolved);
+		isSymlink = lstats.isSymbolicLink();
+	} catch (err: unknown) {
+		if (err instanceof Error && "code" in err && err.code !== "ENOENT") throw err;
+		// Path doesn't exist yet — caller will create it. Skip further validation.
+		return resolved;
+	}
+	if (isSymlink) {
+		throw new Error(
+			`userPiRoot: PI_TEAMS_HOME path "${resolved}" is a symlink. ` +
+				"Symlinks are not supported for PI_TEAMS_HOME to prevent confusion attacks. " +
+				"Set PI_TEAMS_HOME to a direct path owned by the current user.",
+		);
+	}
+
+	// Validate that the resolved path is owned by the current user
+	// to ensure security assumptions about file permissions (0o600/0o700) hold.
+	// Skip check if the directory does not exist yet.
+	try {
+		const stats = fs.statSync(resolved);
+		if (stats.uid !== os.userInfo().uid) {
+			throw new Error(
+				`userPiRoot: PI_TEAMS_HOME path "${resolved}" is not owned by the current user (uid=${os.userInfo().uid}, found uid=${stats.uid}). ` +
+					"This violates security assumptions about file permissions. Set PI_TEAMS_HOME to a path owned by the current user, or unset it to use the default.",
+			);
+		}
+	} catch (err: unknown) {
+		if (err instanceof Error && "code" in err && err.code !== "ENOENT") {
+			throw err;
+		}
+		// ENOENT from statSync means the directory was deleted between lstat and stat
+		// (race condition). This is acceptable — caller will handle.
+	}
+
+	return resolved;
+}
+
+const PROJECT_DIR_MARKERS = [".git", ".pi", ".crew", ".hg", ".svn", ".factory", ".omc"];
+const PROJECT_FILE_MARKERS = [
+	"package.json",
+	"pyproject.toml",
+	"Cargo.toml",
+	"go.mod",
+	"pom.xml",
+	"composer.json",
+	"build.gradle",
+	"build.gradle.kts",
+];
+
+// 2.10 — cache findRepoRoot results so repeated lookups during render ticks
+// (loadConfig, state-store helpers, powerbar, snapshot-cache, ...) skip the
+// 14 existsSync calls per ancestor level. TTL is short enough that a freshly
+// `git init`-ed marker is picked up within ~30s without forcing manual
+// invalidation in interactive sessions.
+const PROJECT_ROOT_CACHE_TTL_MS = 30_000;
+const PROJECT_ROOT_CACHE_MAX_ENTRIES = 32;
+interface ProjectRootCacheEntry {
+	repoRoot: string | undefined;
+	cachedAt: number;
+}
+const projectRootCache = new Map<string, ProjectRootCacheEntry>();
+
+function evictOldestProjectRoot(): void {
+	const oldest = projectRootCache.keys().next().value;
+	if (oldest !== undefined) projectRootCache.delete(oldest);
+}
+
+/** Drop all cached findRepoRoot results. Call from cleanupRuntime / tests. */
+export function clearProjectRootCache(): void {
+	projectRootCache.clear();
+}
+
+function hasProjectMarker(dir: string): boolean {
+	for (const marker of PROJECT_DIR_MARKERS) {
+		if (fs.existsSync(path.join(dir, marker))) return true;
+	}
+	for (const file of PROJECT_FILE_MARKERS) {
+		if (fs.existsSync(path.join(dir, file))) return true;
+	}
+	return false;
+}
+
+/** On Windows, resolve a path to its canonical long-name form.
+ *  Uses realpathSync.native to get the \\?\ long-name path, then strips
+ *  the prefix for path.relative compatibility. */
+function canonicalizePath(p: string): string {
+	try {
+		const r = fs.realpathSync.native(p);
+		return r.startsWith("\\\\?\\") ? r.slice(4) : r;
+	} catch {
+		try {
+			return fs.realpathSync(p);
+		} catch {
+			return p;
+		}
+	}
+}
+
+export function findRepoRoot(cwd: string): string | undefined {
+	// Resolve symlinks before walking to prevent malicious symlinks from bypassing
+	// home/temp boundary checks. If the path doesn't exist (e.g., caller passed
+	// a non-existent CWD like /tmp/no-such-dir), fall back to the lexical path
+	// and let computeRepoRoot handle the rest. ENOENT here is common for
+	// newly-created test directories and shouldn't propagate as a crash.
+	let startKey: string;
+	try {
+		startKey = fs.realpathSync(cwd);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			startKey = path.resolve(cwd);
+		} else {
+			throw error;
+		}
+	}
+	const cached = projectRootCache.get(startKey);
+	if (cached && Date.now() - cached.cachedAt < PROJECT_ROOT_CACHE_TTL_MS) {
+		// Re-insert to refresh LRU position.
+		projectRootCache.delete(startKey);
+		projectRootCache.set(startKey, cached);
+		return cached.repoRoot;
+	}
+	const result = computeRepoRoot(startKey);
+	projectRootCache.set(startKey, { repoRoot: result, cachedAt: Date.now() });
+	while (projectRootCache.size > PROJECT_ROOT_CACHE_MAX_ENTRIES) evictOldestProjectRoot();
+	return result;
+}
+
+function computeRepoRoot(start: string): string | undefined {
+	let current = start;
+	const root = path.parse(current).root;
+	const home = path.resolve(os.homedir());
+	const tempRoot = path.resolve(os.tmpdir());
+	while (current !== root) {
+		// Stop walking before checking markers at home or temp root
+		if (current === home || current === tempRoot) return undefined;
+		if (hasProjectMarker(current)) return current;
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	if (current === home || current === tempRoot) return undefined;
+	if (hasProjectMarker(root)) return root;
+	return undefined;
+}
+
+export function projectPiRoot(cwd: string): string {
+	const repoRoot = findRepoRoot(cwd) ?? cwd;
+	const piDir = path.join(repoRoot, ".pi");
+	// Use realpathSync to resolve any symlinks before returning to prevent
+	// config from being read from unexpected locations.
+	if (fs.existsSync(piDir)) return fs.realpathSync(piDir);
+	return piDir;
+}
+
+export function projectCrewRoot(cwd: string): string {
+	const repoRoot = findRepoRoot(cwd) ?? cwd;
+	const crewDir = path.join(repoRoot, ".crew");
+	// Keep an existing .crew/ stable even when .pi/ exists for project config.
+	// Use canonicalizePath to get long-name form on Windows, matching
+	// what worktree operations and resolveRealContainedPath expect.
+	if (fs.existsSync(crewDir)) return canonicalizePath(crewDir);
+	// Legacy reuse: if .pi/ already exists for the project, namespace under .pi/teams/
+	// to avoid creating a parallel .crew/ alongside an existing pi project layout.
+	const piDir = path.join(repoRoot, ".pi");
+	if (fs.existsSync(piDir)) return path.join(canonicalizePath(piDir), "teams");
+	return crewDir;
+}
+
+export function userCrewRoot(): string {
+	return path.join(userPiRoot(), "extensions", "pi-crew");
+}

package/src/utils/project-detector.ts

@@ -0,0 +1,160 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/**
+ * Information about a detected project.
+ */
+export interface ProjectInfo {
+	projectId: string;
+	projectName: string;
+}
+
+/**
+ * Create a SHA256 hash of a string, returning the first 16 characters.
+ */
+function hashPath(input: string): string {
+	return createHash("sha256").update(input).digest("hex").slice(0, 16);
+}
+
+/**
+ * Extract the repository name from a git remote URL.
+ * Handles formats like:
+ *   - https://github.com/user/repo.git
+ *   - https://github.com/user/repo
+ *   - git@github.com:user/repo.git
+ *   - ssh://git@github.com/user/repo.git
+ */
+function extractRepoName(remoteUrl: string): string | null {
+	// Remove .git suffix
+	const withoutGit = remoteUrl.replace(/\.git$/, "");
+
+	// Handle SSH format: git@github.com:user/repo
+	const sshMatch = withoutGit.match(/^git@[^:]+:(.+)$/);
+	if (sshMatch) {
+		const parts = sshMatch[1].split("/");
+		return parts[parts.length - 1] ?? null;
+	}
+
+	// Handle HTTPS/HTTP/SSH URL format
+	try {
+		const url = new URL(withoutGit);
+		const pathParts = url.pathname.split("/").filter(Boolean);
+		return pathParts[pathParts.length - 1] ?? null;
+	} catch {
+		// Not a valid URL, try to extract from path-like string
+		const parts = withoutGit.split("/").filter(Boolean);
+		return parts[parts.length - 1] ?? null;
+	}
+}
+
+/**
+ * Try to get the repository name from git remote origin.
+ */
+function tryGitRemote(cwd: string): string | null {
+	try {
+		const remoteUrl = execFileSync("git", ["remote", "get-url", "origin"], {
+			cwd,
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "ignore"],
+		}).trim();
+
+		if (!remoteUrl) return null;
+
+		const repoName = extractRepoName(remoteUrl);
+		if (!repoName) return null;
+
+		// Verify it's a valid directory name (no path traversal attempts)
+		if (repoName.includes("..") || repoName.includes("/")) return null;
+
+		return repoName;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Try to get the directory name from git toplevel.
+ */
+function tryGitToplevel(cwd: string): string | null {
+	try {
+		const toplevel = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+			cwd,
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "ignore"],
+		}).trim();
+
+		if (!toplevel || !fs.existsSync(toplevel)) return null;
+
+		const dirName = path.basename(toplevel);
+		// Verify it's a valid directory name
+		if (!dirName || dirName.includes("..") || dirName.includes("/")) return null;
+
+		return dirName;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Detect project information from a working directory.
+ * Uses a hierarchy of detection methods, falling through on failure.
+ *
+ * Detection hierarchy (first successful wins):
+ * 1. CLAUDE_PROJECT_DIR env var → hash the path, use dir name as name
+ * 2. git remote get-url origin → extract repo name from URL
+ * 3. git rev-parse --show-toplevel → use dir name
+ * 4. Fallback: hash(cwd) for projectId, path.basename(cwd) for name
+ */
+export function detectProjectId(cwd: string): ProjectInfo {
+	// Normalize the cwd path
+	const normalizedCwd = path.resolve(cwd);
+
+	// Method 1: Check CLAUDE_PROJECT_DIR env var
+	const claudeProjectDir = process.env.CLAUDE_PROJECT_DIR;
+	if (claudeProjectDir?.trim()) {
+		const resolvedPath = path.resolve(claudeProjectDir.trim());
+		const projectName = path.basename(resolvedPath);
+		const projectId = hashPath(resolvedPath);
+		return { projectId, projectName };
+	}
+
+	// Method 2: Try git remote origin
+	const repoName = tryGitRemote(normalizedCwd);
+	if (repoName) {
+		const projectId = hashPath(normalizedCwd);
+		return { projectId, projectName: repoName };
+	}
+
+	// Method 3: Try git toplevel
+	const toplevelName = tryGitToplevel(normalizedCwd);
+	if (toplevelName) {
+		const projectId = hashPath(normalizedCwd);
+		return { projectId, projectName: toplevelName };
+	}
+
+	// Method 4: Fallback - hash the cwd and use basename
+	const projectId = hashPath(normalizedCwd);
+	const projectName = path.basename(normalizedCwd) || "unknown";
+	return { projectId, projectName };
+}
+
+/**
+ * Get the storage directory for a specific project's instincts.
+ * @param projectId - The project identifier (from detectProjectId)
+ * @param crewRoot - The crew root directory (e.g., from projectCrewRoot)
+ * @returns The path to the project's storage directory
+ */
+export function getProjectStorageDir(projectId: string, crewRoot: string): string {
+	return path.join(crewRoot, "instincts", "projects", projectId);
+}
+
+/**
+ * Get the global storage directory for instincts.
+ * @param crewRoot - The crew root directory
+ * @returns The path to the global storage directory
+ */
+export function getGlobalStorageDir(crewRoot: string): string {
+	return path.join(crewRoot, "instincts", "global");
+}