pi-crew 0.9.54 → 0.9.56

package/src/utils/git.ts

@@ -0,0 +1,260 @@
+import { createRequire } from "node:module";
+
+type HostedGitInfoResult = {
+	repo?: unknown;
+	domain?: string;
+	project?: string;
+	user?: string;
+	committish?: string;
+};
+
+type HostedGitInfoModule = {
+	fromUrl: (url: string) => HostedGitInfoResult | null;
+};
+
+/**
+ * Parsed git source information.
+ */
+export type GitSource = {
+	/**
+	 * Always "git" for git sources.
+	 */
+	type: "git";
+	/**
+	 * Clone URL.
+	 */
+	repo: string;
+	/**
+	 * Git host domain (for example, "github.com").
+	 */
+	host: string;
+	/**
+	 * Repository path (for example, "org/repo").
+	 */
+	path: string;
+	/**
+	 * Git ref (branch, tag, or commit) if specified.
+	 */
+	ref?: string;
+	/**
+	 * Whether the source includes a pinned ref.
+	 */
+	pinned: boolean;
+};
+
+function getHostedGitInfo(): HostedGitInfoModule | null {
+	const require = createRequire(import.meta.url);
+	try {
+		return require("hosted-git-info") as HostedGitInfoModule;
+	} catch {
+		return null;
+	}
+}
+
+const hostedGitInfo = getHostedGitInfo();
+
+function splitRef(url: string): { repo: string; ref?: string } {
+	const scpLikeMatch = url.match(/^git@([^:]+):(.+)$/);
+	if (scpLikeMatch) {
+		const pathWithMaybeRef = scpLikeMatch[2] ?? "";
+		const atRefIndex = pathWithMaybeRef.indexOf("@");
+		const hashRefIndex = pathWithMaybeRef.indexOf("#");
+		let refSeparator = -1;
+		if (atRefIndex >= 0 && hashRefIndex >= 0) {
+			refSeparator = Math.min(atRefIndex, hashRefIndex);
+		} else {
+			refSeparator = atRefIndex >= 0 ? atRefIndex : hashRefIndex;
+		}
+		if (refSeparator < 0) {
+			return { repo: url };
+		}
+
+		const repoPath = pathWithMaybeRef.slice(0, refSeparator);
+		const ref = pathWithMaybeRef.slice(refSeparator + 1);
+		if (!repoPath || !ref) {
+			return { repo: url };
+		}
+
+		return {
+			repo: `git@${scpLikeMatch[1] ?? ""}:${repoPath}`,
+			ref,
+		};
+	}
+
+	if (url.includes("://")) {
+		try {
+			const parsed = new URL(url);
+			const fragmentRef = parsed.hash.startsWith("#") ? parsed.hash.slice(1) : "";
+			parsed.hash = "";
+			const pathWithMaybeRef = parsed.pathname.replace(/^\/+/, "");
+			const atRefIndex = pathWithMaybeRef.indexOf("@");
+			if (atRefIndex >= 0) {
+				const repoPath = pathWithMaybeRef.slice(0, atRefIndex);
+				const ref = pathWithMaybeRef.slice(atRefIndex + 1);
+				if (!repoPath || !ref) {
+					return { repo: parsed.toString().replace(/\/$/, "") };
+				}
+				parsed.pathname = `/${repoPath}`;
+				return {
+					repo: parsed.toString().replace(/\/$/, ""),
+					ref,
+				};
+			}
+
+			if (fragmentRef) {
+				return {
+					repo: parsed.toString().replace(/\/$/, ""),
+					ref: fragmentRef,
+				};
+			}
+
+			return { repo: parsed.toString().replace(/\/$/, "") };
+		} catch {
+			return { repo: url };
+		}
+	}
+
+	const slashIndex = url.indexOf("/");
+	if (slashIndex < 0) {
+		return { repo: url };
+	}
+
+	const pathWithMaybeRef = url.slice(slashIndex + 1);
+	const atRefIndex = pathWithMaybeRef.indexOf("@");
+	const hashRefIndex = pathWithMaybeRef.indexOf("#");
+	let refSeparator = -1;
+	if (atRefIndex >= 0 && hashRefIndex >= 0) {
+		refSeparator = Math.min(atRefIndex, hashRefIndex);
+	} else {
+		refSeparator = atRefIndex >= 0 ? atRefIndex : hashRefIndex;
+	}
+	if (refSeparator < 0) {
+		return { repo: url };
+	}
+
+	const repoPath = pathWithMaybeRef.slice(0, refSeparator);
+	const ref = pathWithMaybeRef.slice(refSeparator + 1);
+	if (!repoPath || !ref) {
+		return { repo: url };
+	}
+
+	return {
+		repo: `${url.slice(0, slashIndex)}/${repoPath}`,
+		ref,
+	};
+}
+
+function parseGenericGitUrl(url: string): GitSource | null {
+	const { repo: repoWithoutRef, ref } = splitRef(url);
+	let repo = repoWithoutRef;
+	let host = "";
+	let path = "";
+
+	const scpLikeMatch = repoWithoutRef.match(/^git@([^:]+):(.+)$/);
+	if (scpLikeMatch) {
+		host = scpLikeMatch[1] ?? "";
+		path = scpLikeMatch[2] ?? "";
+	} else if (
+		repoWithoutRef.startsWith("https://") ||
+		repoWithoutRef.startsWith("http://") ||
+		repoWithoutRef.startsWith("ssh://") ||
+		repoWithoutRef.startsWith("git://")
+	) {
+		try {
+			const parsed = new URL(repoWithoutRef);
+			host = parsed.hostname;
+			path = parsed.pathname.replace(/^\/+/, "");
+		} catch {
+			return null;
+		}
+	} else {
+		const slashIndex = repoWithoutRef.indexOf("/");
+		if (slashIndex < 0) {
+			return null;
+		}
+
+		host = repoWithoutRef.slice(0, slashIndex);
+		path = repoWithoutRef.slice(slashIndex + 1);
+		if (!host.includes(".") && host !== "localhost") {
+			return null;
+		}
+
+		repo = `https://${repoWithoutRef}`;
+	}
+
+	const normalizedPath = path.replace(/\.git$/, "").replace(/^\/+/, "");
+	if (!host || !normalizedPath || normalizedPath.split("/").length < 2) {
+		return null;
+	}
+
+	return {
+		type: "git",
+		repo,
+		host,
+		path: normalizedPath,
+		ref,
+		pinned: Boolean(ref),
+	};
+}
+
+/**
+ * Parse git source into normalized source information.
+ */
+export function parseGitUrl(source: string): GitSource | null {
+	const trimmed = source.trim();
+	const hasGitPrefix = trimmed.startsWith("git:");
+	const normalizedSource = hasGitPrefix ? trimmed.slice(4).trim() : trimmed.replace(/^git\+/i, "");
+	const url = normalizedSource;
+
+	if (!hasGitPrefix && !/^(https?|ssh|git):\/\//i.test(url) && !/^git@[^:]+:/.test(url)) {
+		return null;
+	}
+
+	const split = splitRef(url);
+
+	const parseCandidate = (candidate: string): GitSource | null => {
+		if (!hostedGitInfo) {
+			return null;
+		}
+		const info = hostedGitInfo.fromUrl(candidate) as HostedGitInfoResult | null;
+		if (!info) return null;
+		if (split.ref && info.project?.includes("@")) {
+			return null;
+		}
+		return {
+			type: "git",
+			repo:
+				split.repo.startsWith("http://") ||
+				split.repo.startsWith("https://") ||
+				split.repo.startsWith("ssh://") ||
+				split.repo.startsWith("git://") ||
+				split.repo.startsWith("git@")
+					? split.repo
+					: `https://${split.repo}`,
+			host: info.domain ?? "",
+			path: `${info.user ?? ""}/${info.project ?? ""}`.replace(/\.git$/, ""),
+			ref: info.committish || split.ref || undefined,
+			pinned: Boolean(info.committish || split.ref),
+		};
+	};
+
+	const hostedCandidates = [split.ref ? `${split.repo}#${split.ref}` : undefined, url].filter((value): value is string => Boolean(value));
+	for (const candidate of hostedCandidates) {
+		const info = parseCandidate(candidate);
+		if (info) {
+			return info;
+		}
+	}
+
+	const httpsCandidates = [split.ref ? `https://${split.repo}#${split.ref}` : undefined, `https://${url}`].filter(
+		(value): value is string => Boolean(value),
+	);
+	for (const candidate of httpsCandidates) {
+		const info = parseCandidate(candidate);
+		if (info) {
+			return info;
+		}
+	}
+
+	return parseGenericGitUrl(url);
+}

package/src/utils/guards.ts

@@ -0,0 +1,107 @@
+/**
+ * Centralized type guard library for pi-crew.
+ *
+ * Inspired by @ayulab/runtime-core — all unknown-to-narrowed checks
+ * go through these helpers instead of inline typeof/instanceof.
+ */
+
+// ── Primitive guards ──────────────────────────────────────────────────
+
+/** Narrow `unknown` to `Record<string, unknown>`. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Narrow `unknown` to `string`. */
+export function isString(value: unknown): value is string {
+	return typeof value === "string";
+}
+
+/** Narrow `unknown` to a non-empty string. */
+export function isNonEmptyString(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0;
+}
+
+/** Narrow `unknown` to `number` (excludes NaN). */
+export function isNumber(value: unknown): value is number {
+	return typeof value === "number" && !Number.isNaN(value);
+}
+
+/** Narrow `unknown` to `boolean`. */
+export function isBoolean(value: unknown): value is boolean {
+	return typeof value === "boolean";
+}
+
+/** Narrow `unknown` to `readonly string[]`. */
+export function isStringArray(value: unknown): value is readonly string[] {
+	return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+
+/**
+ * Higher-order guard: build a guard that checks every element of an array.
+ *
+ * @example
+ * const isNumberArray = isArrayOf(isNumber);
+ */
+export function isArrayOf<T>(guard: (item: unknown) => item is T): (value: unknown) => value is readonly T[] {
+	return (value: unknown): value is readonly T[] => Array.isArray(value) && value.every(guard);
+}
+
+// ── Record field extractors ───────────────────────────────────────────
+
+/** Extract a string field from a record, returning `undefined` if absent. */
+export function getStringField(value: unknown, key: string): string | undefined {
+	if (!isRecord(value)) return undefined;
+	const field = value[key];
+	return typeof field === "string" ? field : undefined;
+}
+
+/** Extract a number field from a record, returning `undefined` if absent. */
+export function getNumberField(value: unknown, key: string): number | undefined {
+	if (!isRecord(value)) return undefined;
+	const field = value[key];
+	return typeof field === "number" && !Number.isNaN(field) ? field : undefined;
+}
+
+/** Extract a boolean field from a record, returning `undefined` if absent. */
+export function getBooleanField(value: unknown, key: string): boolean | undefined {
+	if (!isRecord(value)) return undefined;
+	const field = value[key];
+	return typeof field === "boolean" ? field : undefined;
+}
+
+/** Extract a nested record field from a record, returning `undefined` if absent. */
+export function getRecordField(value: unknown, key: string): Record<string, unknown> | undefined {
+	if (!isRecord(value)) return undefined;
+	const field = value[key];
+	return isRecord(field) ? field : undefined;
+}
+
+/** Extract an array field from a record, returning `undefined` if absent. */
+export function getArrayField(value: unknown, key: string): unknown[] | undefined {
+	if (!isRecord(value)) return undefined;
+	const field = value[key];
+	return Array.isArray(field) ? field : undefined;
+}
+
+// ── Error helpers ─────────────────────────────────────────────────────
+
+/**
+ * Extract a human-readable message from an unknown error value.
+ *
+ * Prefer this over manual `instanceof Error` checks to keep error
+ * handling uniform across the codebase.
+ */
+export function errorMessage(err: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}
+
+// ── Utility types ─────────────────────────────────────────────────────
+
+/** A non-empty readonly array type. */
+export type NonEmptyReadonlyArray<T> = readonly [T, ...T[]];
+
+/** Narrow a readonly array to a non-empty readonly array. */
+export function hasItems<T>(items: readonly T[]): items is NonEmptyReadonlyArray<T> {
+	return items.length > 0;
+}

package/src/utils/ids.ts

@@ -0,0 +1,24 @@
+import { randomBytes } from "node:crypto";
+import { generateTaskName } from "./task-name-generator.ts";
+
+export function createRunId(prefix = "team"): string {
+	const stamp = new Date()
+		.toISOString()
+		.replace(/[-:.TZ]/g, "")
+		.slice(0, 14);
+	const suffix = randomBytes(8).toString("hex");
+	return `${prefix}_${stamp}_${suffix}`;
+}
+
+export function createTaskId(stepId: string, index: number): string {
+	const normalized =
+		stepId
+			.toLowerCase()
+			.replace(/[^a-z0-9-]+/g, "-")
+			.replace(/^-+|-+$/g, "") || "task";
+	return `${String(index + 1).padStart(2, "0")}_${normalized}`;
+}
+
+export function createDisplayName(): string {
+	return generateTaskName();
+}

package/src/utils/incremental-reader.ts

@@ -0,0 +1,220 @@
+import * as fs from "node:fs";
+
+export interface IncrementalReadState {
+	byteOffset: number;
+	lineCount: number;
+}
+
+export interface IncrementalReadResult {
+	lines: string[];
+	state: IncrementalReadState;
+	eof: boolean;
+}
+
+const CHUNK_SIZE = 64 * 1024;
+
+/**
+ * Read the last `tailBytes` bytes of a file and parse it as JSONL,
+ * returning each successfully-parsed item in file order. If the file is
+ * shorter than `tailBytes`, the entire file is read from offset 0.
+ *
+ * Returns:
+ *   - items: parsed JSONL items (T may be any deserializable type)
+ *   - fileSize: total file size in bytes
+ *   - bytesRead: number of bytes actually read (≤ min(fileSize, tailBytes))
+ *   - truncated: true when `bytesRead < fileSize` (a prefix was dropped)
+ *
+ * The function bounds the read to `tailBytes`, so CPU is O(tail bytes)
+ * regardless of how large the file grows. Used by the event-log tail
+ * read path (FIND-05) to avoid the O(total events) cost of the legacy
+ * `readFileSync`+`split("\n")`+`JSON.parse` approach.
+ */
+export function readJsonlTail<T>(
+	filePath: string,
+	tailBytes: number,
+): {
+	items: T[];
+	fileSize: number;
+	bytesRead: number;
+	truncated: boolean;
+} {
+	const limit = Math.max(0, Math.floor(tailBytes));
+	let stat: fs.Stats;
+	try {
+		stat = fs.statSync(filePath);
+	} catch {
+		return { items: [], fileSize: 0, bytesRead: 0, truncated: false };
+	}
+	const fileSize = stat.size;
+	if (fileSize === 0 || limit === 0) {
+		return { items: [], fileSize, bytesRead: 0, truncated: false };
+	}
+
+	const startOffset = Math.max(0, fileSize - limit);
+	const bytesToRead = fileSize - startOffset;
+	const truncated = startOffset > 0;
+
+	let fd: number | undefined;
+	try {
+		// FIND-05 follow-up: O_NOFOLLOW refuses symlinks (defense-in-depth,
+		// consistent with atomicWriteFile / resolveRealContainedPath). The
+		// eventsPath is validated inside stateRoot, but this guards against a
+		// symlinked file appearing after validation. O_NOFOLLOW on a symlink
+		// yields ELOOP, which the catch below treats like ENOENT (return empty).
+		fd = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+	} catch {
+		return { items: [], fileSize, bytesRead: 0, truncated: false };
+	}
+	try {
+		const buf = Buffer.alloc(bytesToRead);
+		let totalRead = 0;
+		while (totalRead < bytesToRead) {
+			const chunkSize = Math.min(CHUNK_SIZE, bytesToRead - totalRead);
+			const bytesRead = fs.readSync(fd, buf, totalRead, chunkSize, startOffset + totalRead);
+			if (bytesRead === 0) break;
+			totalRead += bytesRead;
+		}
+
+		// Decode the slice we actually read; the buffer may be partially
+		// filled on short reads. We use totalRead (not bytesToRead) so the
+		// JSONL split lands on actual data, not a zero-padded tail.
+		const content = buf.toString("utf-8", 0, totalRead);
+
+		// If we truncated the file, the first decoded line may be a
+		// half-line from the cut. Drop it — we can't trust the JSON.
+		// Use a single indexOf("\n") to find the first newline; if there
+		// is none, the whole tail is one partial line and we drop it.
+		let body = content;
+		if (truncated) {
+			const firstNewline = body.indexOf("\n");
+			if (firstNewline < 0) {
+				// No newline at all in the tail → the entire tail is one
+				// partial line. Return no items; the caller should fall
+				// back to a wider tail or full read.
+				return { items: [], fileSize, bytesRead: totalRead, truncated: true };
+			}
+			body = body.slice(firstNewline + 1);
+		}
+
+		const items: T[] = [];
+		for (const line of body.split("\n")) {
+			const trimmed = line.trim();
+			if (!trimmed) continue;
+			try {
+				items.push(JSON.parse(trimmed) as T);
+			} catch {
+				// Skip malformed lines (mirrors readJsonlSince's behavior).
+			}
+		}
+		return { items, fileSize, bytesRead: totalRead, truncated };
+	} finally {
+		if (fd !== undefined) {
+			try {
+				fs.closeSync(fd);
+			} catch {
+				/* ignore */
+			}
+		}
+	}
+}
+
+/**
+ * Read new lines from a text file since last known byte offset.
+ * Uses fs.openSync + fs.readSync for efficient incremental reading.
+ */
+export function readLinesSince(filePath: string, state: IncrementalReadState): IncrementalReadResult {
+	let fd: number | undefined;
+	try {
+		fd = fs.openSync(filePath, "r");
+	} catch {
+		return {
+			lines: [],
+			state: { byteOffset: state.byteOffset, lineCount: state.lineCount },
+			eof: true,
+		};
+	}
+
+	try {
+		const stat = fs.fstatSync(fd);
+		const fileSize = stat.size;
+
+		if (fileSize <= state.byteOffset) {
+			return {
+				lines: [],
+				state: { byteOffset: fileSize, lineCount: state.lineCount },
+				eof: true,
+			};
+		}
+
+		const bytesToRead = fileSize - state.byteOffset;
+		const buf = Buffer.alloc(bytesToRead);
+		let totalRead = 0;
+
+		while (totalRead < bytesToRead) {
+			const chunkSize = Math.min(CHUNK_SIZE, bytesToRead - totalRead);
+			const bytesRead = fs.readSync(fd, buf, totalRead, chunkSize, state.byteOffset + totalRead);
+			if (bytesRead === 0) break;
+			totalRead += bytesRead;
+		}
+
+		const content = buf.toString("utf-8", 0, totalRead);
+		const lines: string[] = [];
+		let lineCount = state.lineCount;
+		let committedOffset = state.byteOffset;
+
+		let searchFrom = 0;
+		let newlineIdx: number;
+
+		while ((newlineIdx = content.indexOf("\n", searchFrom)) !== -1) {
+			const lineText = content.slice(searchFrom, newlineIdx);
+			committedOffset = state.byteOffset + newlineIdx + 1;
+			searchFrom = newlineIdx + 1;
+			if (lineText.length > 0) {
+				lines.push(lineText);
+				lineCount++;
+			}
+		}
+
+		const eof = committedOffset >= fileSize;
+
+		return {
+			lines,
+			state: { byteOffset: committedOffset, lineCount },
+			eof,
+		};
+	} finally {
+		if (fd !== undefined) {
+			try {
+				fs.closeSync(fd);
+			} catch {
+				/* ignore */
+			}
+		}
+	}
+}
+
+/**
+ * Read parsed JSON objects from a JSONL file since last known byte offset.
+ * Skips malformed lines.
+ */
+export function readJsonlSince<T>(
+	filePath: string,
+	state: IncrementalReadState,
+): { items: T[]; state: IncrementalReadState; eof: boolean } {
+	const result = readLinesSince(filePath, state);
+	const items: T[] = [];
+
+	for (const line of result.lines) {
+		try {
+			items.push(JSON.parse(line) as T);
+		} catch {
+			// Skip malformed lines
+		}
+	}
+
+	return {
+		items,
+		state: result.state,
+		eof: result.eof,
+	};
+}

package/src/utils/internal-error.ts

@@ -0,0 +1,10 @@
+export function logInternalError(scope: string, error: unknown, details?: string, severity?: "error" | "warn" | "debug"): void {
+	// "error" and "warn" always emit; "debug" (default) is gated behind PI_TEAMS_DEBUG
+	if (!severity || severity === "debug") {
+		if (!process.env.PI_TEAMS_DEBUG) return;
+	}
+	const message =
+		error instanceof Error ? error.message : typeof error === "object" && error !== null ? JSON.stringify(error) : String(error);
+	const suffix = details ? `: ${details}` : "";
+	console.error(`[pi-crew:${scope}] ${message}${suffix}`);
+}

package/src/utils/names.ts

@@ -0,0 +1,36 @@
+export function sanitizeName(name: string): string {
+	const result = name
+		.toLowerCase()
+		.trim()
+		.replace(/\s+/g, "-")
+		.replace(/[^a-z0-9-]/g, "")
+		.replace(/-+/g, "-")
+		.replace(/^-+|-+$/g, "");
+	return result || "unnamed";
+}
+
+export function requireString(value: unknown, label: string): { value?: string; error?: string } {
+	if (typeof value !== "string" || !value.trim()) return { error: `${label} must be a non-empty string.` };
+	return { value: value.trim() };
+}
+
+export function parseConfigObject(config: unknown): {
+	value?: Record<string, unknown>;
+	error?: string;
+} {
+	let parsed = config;
+	if (typeof parsed === "string") {
+		try {
+			parsed = JSON.parse(parsed) as unknown;
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return { error: `config must be valid JSON: ${message}` };
+		}
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { error: "config must be an object." };
+	return { value: parsed as Record<string, unknown> };
+}
+
+export function hasOwn(obj: Record<string, unknown>, key: string): boolean {
+	return Object.hasOwn(obj, key);
+}