@nseng-ai/plans 0.1.1

package/src/saved-plan-selection.ts

@@ -0,0 +1,361 @@
+import { basename, isAbsolute } from "node:path";
+import { z } from "zod";
+
+import {
+	buildPlanFileName,
+	buildPlanStoreBranchDirectoryPath,
+	encodeBranchForPlanPath,
+	findLatestSavedPlanFile,
+	resolvePlanStoreDirectory,
+	type LatestSavedPlanFileEvidence,
+	type PlanStoreDirectoryEvidence,
+	type SavedPlanFileEvidence,
+	type PlanStoreOptions,
+} from "./saved-plan-file.ts";
+import { createRealPlanStoreGateway, type PlanStoreGateway } from "./plan-store-gateway.ts";
+import type { CommandExecApi } from "@nseng-ai/foundation/exec";
+import { isPathInside, normalizePlanFilePath, validatePlanSlug } from "./plan-persistence.ts";
+
+export const WRITE_SAVED_PLAN_FILE_TOOL_NAME = "write_saved_plan_file";
+
+export type ValidatedSessionSavedPlan = LatestSavedPlanFileEvidence & {
+	summary?: string;
+};
+
+export type SessionSavedPlanValidation =
+	| { type: "valid"; plan: ValidatedSessionSavedPlan }
+	| { type: "stale"; reason: string }
+	| { type: "unsafe"; message: string };
+
+export type LatestSessionSavedPlanResult =
+	| { type: "found"; plan: ValidatedSessionSavedPlan }
+	| { type: "not-found" }
+	| { type: "unsafe"; message: string };
+
+export type SelectedSavedPlanFile =
+	| {
+			type: "explicit";
+			filePath: string;
+			fileName: string;
+			savedPlanFileStem: string;
+	  }
+	| {
+			type: "session";
+			plan: ValidatedSessionSavedPlan;
+			savedPlanFileStem: string;
+	  }
+	| {
+			type: "latest";
+			plan: LatestSavedPlanFileEvidence;
+			savedPlanFileStem: string;
+	  };
+
+export interface ResolveSelectedSavedPlanFileOptions extends PlanStoreOptions {
+	explicitPath?: string;
+	sessionEntries?: readonly unknown[];
+	shouldFallbackToLatest?: boolean;
+	shouldAllowSessionSourceBranchMismatch?: boolean;
+}
+
+export interface ValidateSessionSavedPlanCandidateOptions {
+	shouldAllowSourceBranchMismatch?: boolean;
+	planStoreGateway?: PlanStoreGateway;
+}
+
+const repoIdentitySourceSchema = z.enum(["origin-url", "repo-root"]);
+
+const savedPlanFileEvidenceSchema = z.object({
+	slug: z.string(),
+	repoRoot: z.string(),
+	repoKey: z.string(),
+	repoIdentitySource: repoIdentitySourceSchema,
+	sourceBranch: z.string(),
+	branchKey: z.string(),
+	filePath: z.string(),
+	summary: z.string().optional(),
+});
+
+const savedPlanFileSessionEntrySchema = z.object({
+	type: z.literal("message"),
+	message: z
+		.object({
+			role: z.literal("toolResult"),
+			toolName: z.literal(WRITE_SAVED_PLAN_FILE_TOOL_NAME),
+			isError: z.unknown().optional(),
+			details: savedPlanFileEvidenceSchema,
+		})
+		.refine((message) => message.isError !== true),
+});
+
+export function extractSavedPlanFileEvidenceFromSessionEntry(
+	entry: unknown,
+): SavedPlanFileEvidence | undefined {
+	const result = savedPlanFileSessionEntrySchema.safeParse(entry);
+	if (!result.success) {
+		return undefined;
+	}
+
+	return toSavedPlanFileEvidence(result.data.message.details);
+}
+
+function toSavedPlanFileEvidence(
+	data: z.infer<typeof savedPlanFileEvidenceSchema>,
+): SavedPlanFileEvidence {
+	const { summary, ...evidence } = data;
+	return { ...evidence, ...(summary === undefined ? {} : { summary }) };
+}
+
+export async function validateSessionSavedPlanCandidate(
+	evidence: SavedPlanFileEvidence,
+	directory: PlanStoreDirectoryEvidence,
+	options: ValidateSessionSavedPlanCandidateOptions = {},
+): Promise<SessionSavedPlanValidation> {
+	if (!isAbsolute(evidence.filePath)) {
+		return unsafe(
+			`Session saved-plan evidence file path must be absolute: ${evidence.filePath || "(empty)"}`,
+		);
+	}
+	if (!evidence.filePath.endsWith(".md")) {
+		return unsafe(
+			`Session saved-plan evidence file path must use a .md filename: ${evidence.filePath}`,
+		);
+	}
+
+	const slugError = validatePlanSlug(evidence.slug);
+	if (slugError !== undefined) {
+		return unsafe(
+			`Session saved-plan evidence has an invalid slug ${JSON.stringify(evidence.slug)}: ${slugError}`,
+		);
+	}
+
+	const fileName = basename(evidence.filePath);
+	const expectedFileName = buildPlanFileName(evidence.slug);
+	if (fileName !== expectedFileName) {
+		return unsafe(
+			`Session saved-plan evidence basename must match slug: expected ${expectedFileName}, got ${fileName || "(empty)"}.`,
+		);
+	}
+
+	const planStoreGateway = options.planStoreGateway ?? createRealPlanStoreGateway();
+	const metadata = validateDirectoryMetadata(evidence, directory, options);
+	if (metadata.type === "invalid") {
+		return unsafe(metadata.message);
+	}
+
+	const expectedDirectoryPath = metadata.directoryPath;
+	if (!isPathInside(expectedDirectoryPath, evidence.filePath)) {
+		return unsafe(
+			[
+				formatOutsidePlanStoreDirectoryMessage(expectedDirectoryPath, directory.directoryPath),
+				`Plan store directory: ${expectedDirectoryPath}`,
+				`Saved plan path: ${evidence.filePath}`,
+			].join("\n"),
+		);
+	}
+
+	const fileStat = await planStoreGateway.statPath(evidence.filePath);
+	if (fileStat === undefined) {
+		return {
+			type: "stale",
+			reason: `Saved plan file no longer exists or is not accessible: ${evidence.filePath}`,
+		};
+	}
+	if (fileStat.type !== "file") {
+		return unsafe(`Session saved-plan evidence path is not a regular file: ${evidence.filePath}`);
+	}
+
+	const realDirectoryPath = await planStoreGateway.realpathOrResolve(expectedDirectoryPath);
+	const realFilePath = await planStoreGateway.realpathOrResolve(evidence.filePath);
+	if (!isPathInside(realDirectoryPath, realFilePath)) {
+		return unsafe(
+			[
+				"Session saved-plan evidence resolves outside the current local plan store directory.",
+				`Plan store directory: ${directory.directoryPath}`,
+				`Resolved plan store directory: ${realDirectoryPath}`,
+				`Saved plan path: ${evidence.filePath}`,
+				`Resolved saved plan path: ${realFilePath}`,
+			].join("\n"),
+		);
+	}
+
+	const plan: ValidatedSessionSavedPlan = {
+		...directory,
+		sourceBranch: evidence.sourceBranch,
+		branchKey: evidence.branchKey,
+		directoryPath: expectedDirectoryPath,
+		slug: evidence.slug,
+		filePath: evidence.filePath,
+		fileName,
+		modifiedTimeMs: fileStat.mtimeMs,
+		...(evidence.summary === undefined ? {} : { summary: evidence.summary }),
+	};
+	return { type: "valid", plan };
+}
+
+export async function findLatestSessionSavedPlanFile(
+	entries: readonly unknown[],
+	directory: PlanStoreDirectoryEvidence,
+	options: ValidateSessionSavedPlanCandidateOptions = {},
+): Promise<LatestSessionSavedPlanResult> {
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		const entry = entries[index];
+		const evidence = extractSavedPlanFileEvidenceFromSessionEntry(entry);
+		if (evidence === undefined) {
+			continue;
+		}
+
+		const validation = await validateSessionSavedPlanCandidate(evidence, directory, options);
+		switch (validation.type) {
+			case "valid":
+				return { type: "found", plan: validation.plan };
+			case "stale":
+				continue;
+			case "unsafe":
+				return validation;
+		}
+	}
+
+	return { type: "not-found" };
+}
+
+export async function resolveSelectedSavedPlanFile(
+	pi: CommandExecApi,
+	options: ResolveSelectedSavedPlanFileOptions,
+): Promise<SelectedSavedPlanFile> {
+	if (options.explicitPath !== undefined) {
+		const filePath = normalizePlanFilePath(options.explicitPath);
+		if (!isAbsolute(filePath)) {
+			throw new Error(
+				`Plan file path must be absolute or home-relative; got ${filePath || "(empty)"}.`,
+			);
+		}
+
+		const fileName = basename(filePath);
+		if (!fileName.endsWith(".md")) {
+			throw new Error(`Plan file must use a .md filename; got ${fileName || "(empty)"}.`);
+		}
+
+		return {
+			type: "explicit",
+			savedPlanFileStem: fileName.slice(0, -".md".length),
+			filePath,
+			fileName,
+		};
+	}
+
+	const sessionEntries = options.sessionEntries ?? [];
+	if (sessionEntries.length > 0) {
+		const directory = await resolvePlanStoreDirectory(pi, options);
+		const sessionResult = await findLatestSessionSavedPlanFile(sessionEntries, directory, {
+			shouldAllowSourceBranchMismatch: options.shouldAllowSessionSourceBranchMismatch ?? false,
+			...(options.planStoreGateway === undefined
+				? {}
+				: { planStoreGateway: options.planStoreGateway }),
+		});
+		switch (sessionResult.type) {
+			case "found":
+				return {
+					type: "session",
+					plan: sessionResult.plan,
+					savedPlanFileStem: sessionResult.plan.slug,
+				};
+			case "unsafe":
+				throw new Error(sessionResult.message);
+			case "not-found":
+				break;
+		}
+	}
+
+	if (options.shouldFallbackToLatest ?? false) {
+		const latest = await findLatestSavedPlanFile(pi, options);
+		return { type: "latest", plan: latest, savedPlanFileStem: latest.slug };
+	}
+
+	throw new Error("No usable saved plan was found in the current session branch.");
+}
+
+type DirectoryMetadataValidation =
+	| { type: "valid"; directoryPath: string }
+	| { type: "invalid"; message: string };
+
+function validateDirectoryMetadata(
+	evidence: SavedPlanFileEvidence,
+	directory: PlanStoreDirectoryEvidence,
+	options: ValidateSessionSavedPlanCandidateOptions,
+): DirectoryMetadataValidation {
+	const mismatches = validateRepoMetadata(evidence, directory);
+	if (mismatches.length > 0) {
+		return metadataInvalid(mismatches);
+	}
+
+	const expectedBranchKey = encodeBranchForPlanPath(evidence.sourceBranch);
+	if (evidence.branchKey !== expectedBranchKey) {
+		return metadataInvalid([
+			`branchKey: evidence ${evidence.branchKey}, expected ${expectedBranchKey} for sourceBranch ${evidence.sourceBranch}`,
+		]);
+	}
+
+	const branchMatchesCurrent =
+		evidence.sourceBranch === directory.sourceBranch && evidence.branchKey === directory.branchKey;
+	if (branchMatchesCurrent) {
+		return { type: "valid", directoryPath: directory.directoryPath };
+	}
+
+	if (!(options.shouldAllowSourceBranchMismatch ?? false)) {
+		return metadataInvalid([
+			`sourceBranch: evidence ${evidence.sourceBranch}, current ${directory.sourceBranch}`,
+			`branchKey: evidence ${evidence.branchKey}, current ${directory.branchKey}`,
+		]);
+	}
+
+	return {
+		type: "valid",
+		directoryPath: buildPlanStoreBranchDirectoryPath({
+			repoDirectoryPath: directory.repoDirectoryPath,
+			branchKey: evidence.branchKey,
+		}),
+	};
+}
+
+function validateRepoMetadata(
+	evidence: SavedPlanFileEvidence,
+	directory: PlanStoreDirectoryEvidence,
+): string[] {
+	const mismatches: string[] = [];
+	if (evidence.repoRoot !== directory.repoRoot) {
+		mismatches.push(`repoRoot: evidence ${evidence.repoRoot}, current ${directory.repoRoot}`);
+	}
+	if (evidence.repoKey !== directory.repoKey) {
+		mismatches.push(`repoKey: evidence ${evidence.repoKey}, current ${directory.repoKey}`);
+	}
+	if (evidence.repoIdentitySource !== directory.repoIdentitySource) {
+		mismatches.push(
+			`repoIdentitySource: evidence ${evidence.repoIdentitySource}, current ${directory.repoIdentitySource}`,
+		);
+	}
+	return mismatches;
+}
+
+function metadataInvalid(mismatches: readonly string[]): DirectoryMetadataValidation {
+	return {
+		type: "invalid",
+		message: [
+			"Latest saved plan belongs to a different repo or branch than the current checkout, or an incompatible source branch.",
+			...mismatches,
+		].join("\n"),
+	};
+}
+
+function formatOutsidePlanStoreDirectoryMessage(
+	expectedDirectoryPath: string,
+	currentDirectoryPath: string,
+): string {
+	if (expectedDirectoryPath === currentDirectoryPath) {
+		return "Session saved-plan evidence points outside the current local plan store directory.";
+	}
+	return "Session saved-plan evidence points outside the saved plan source-branch local plan store directory.";
+}
+
+function unsafe(message: string): SessionSavedPlanValidation {
+	return { type: "unsafe", message };
+}

package/src/testing.ts

@@ -0,0 +1,129 @@
+import { dirname, resolve } from "node:path";
+
+import type {
+	PlanStoreDirectoryEntry,
+	PlanStoreDirectoryRead,
+	PlanStoreGateway,
+	PlanStorePathStat,
+	PlanStorePathType,
+} from "./plan-store-gateway.ts";
+
+interface InMemoryNode {
+	type: PlanStorePathType;
+	content?: string;
+	mtimeMs: number;
+}
+
+export interface WriteInMemoryPlanStoreFileOptions {
+	mtimeMs?: number;
+}
+
+export class InMemoryPlanStoreGateway implements PlanStoreGateway {
+	private readonly nodes = new Map<string, InMemoryNode>();
+	private nextMtimeMs = 1;
+
+	constructor(paths: { directories?: readonly string[]; files?: Record<string, string> } = {}) {
+		for (const directory of paths.directories ?? []) this.mkdir(directory);
+		for (const [path, content] of Object.entries(paths.files ?? {})) this.writeFile(path, content);
+	}
+
+	async listDirectory(path: string): Promise<PlanStoreDirectoryRead> {
+		const normalizedPath = normalize(path);
+		const node = this.nodes.get(normalizedPath);
+		if (node === undefined) return { type: "missing" };
+		if (node.type !== "directory") return { type: "present", entries: [] };
+
+		const entries = new Map<string, PlanStoreDirectoryEntry>();
+		const prefix = normalizedPath === "/" ? "/" : `${normalizedPath}/`;
+		for (const [candidatePath, candidate] of this.nodes) {
+			if (candidatePath === normalizedPath || !candidatePath.startsWith(prefix)) continue;
+			const rest = candidatePath.slice(prefix.length);
+			if (rest.length === 0 || rest.includes("/")) continue;
+			entries.set(rest, { name: rest, type: candidate.type });
+		}
+		return {
+			type: "present",
+			entries: [...entries.values()].sort((a, b) => a.name.localeCompare(b.name)),
+		};
+	}
+
+	async statPath(path: string): Promise<PlanStorePathStat | undefined> {
+		const node = this.nodes.get(normalize(path));
+		if (node === undefined) return undefined;
+		return { type: node.type, mtimeMs: node.mtimeMs };
+	}
+
+	async readTextFile(path: string): Promise<string> {
+		const normalizedPath = normalize(path);
+		const node = this.nodes.get(normalizedPath);
+		if (node?.type !== "file" || node.content === undefined) {
+			throw new Error(`ENOENT: no such file or directory, open '${normalizedPath}'`);
+		}
+		return node.content;
+	}
+
+	async writeTextFileExclusive(path: string, content: string): Promise<void> {
+		const normalizedPath = normalize(path);
+		if (this.nodes.has(normalizedPath)) {
+			throw new Error(
+				`Saved plan file already exists in the local plan store; refusing to overwrite.\nPath: ${normalizedPath}`,
+			);
+		}
+		this.writeFile(normalizedPath, content);
+	}
+
+	async realpathOrResolve(path: string): Promise<string> {
+		return normalize(path);
+	}
+
+	mkdir(path: string, options: { mtimeMs?: number } = {}): void {
+		const normalizedPath = normalize(path);
+		this.ensureParentDirectories(normalizedPath);
+		this.nodes.set(normalizedPath, {
+			type: "directory",
+			mtimeMs: options.mtimeMs ?? this.nextMtime(),
+		});
+	}
+
+	writeFile(path: string, content: string, options: WriteInMemoryPlanStoreFileOptions = {}): void {
+		const normalizedPath = normalize(path);
+		this.ensureParentDirectories(normalizedPath);
+		this.nodes.set(normalizedPath, {
+			type: "file",
+			content,
+			mtimeMs: options.mtimeMs ?? this.nextMtime(),
+		});
+	}
+
+	readFile(path: string): string {
+		const normalizedPath = normalize(path);
+		const node = this.nodes.get(normalizedPath);
+		if (node?.type !== "file" || node.content === undefined) {
+			throw new Error(`In-memory plan store file does not exist: ${normalizedPath}`);
+		}
+		return node.content;
+	}
+
+	hasFile(path: string): boolean {
+		return this.nodes.get(normalize(path))?.type === "file";
+	}
+
+	private ensureParentDirectories(path: string): void {
+		const parent = normalize(dirname(path));
+		if (parent === path) return;
+		if (!this.nodes.has(parent)) {
+			this.ensureParentDirectories(parent);
+			this.nodes.set(parent, { type: "directory", mtimeMs: this.nextMtime() });
+		}
+	}
+
+	private nextMtime(): number {
+		const value = this.nextMtimeMs;
+		this.nextMtimeMs += 1;
+		return value;
+	}
+}
+
+function normalize(path: string): string {
+	return resolve("/", path);
+}