@nseng-ai/plans 0.1.1

package/src/plan-persistence.ts

@@ -0,0 +1,149 @@
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+
+import type { CommandExecApi } from "@nseng-ai/foundation/exec";
+import { RealGitGateway } from "@nseng-ai/capability-kit/git";
+import type { GitGateway } from "@nseng-ai/capability-kit/git";
+import { isPathInside, optionalEntry } from "@nseng-ai/foundation/primitives";
+import { createRealPlanStoreGateway, type PlanStoreGateway } from "./plan-store-gateway.ts";
+
+export { isPathInside } from "@nseng-ai/foundation/primitives";
+
+export const MIN_PLAN_SLUG_WORDS = 3;
+export const MAX_PLAN_SLUG_WORDS = 7;
+
+const GENERIC_SLUG_WORDS = new Set([
+	"plan",
+	"task",
+	"tasks",
+	"work",
+	"implementation",
+	"implement",
+	"changes",
+	"change",
+	"update",
+	"updates",
+]);
+
+export function validatePlanSlug(slug: string): string | undefined {
+	const normalized = slug.trim();
+	if (normalized.length === 0) {
+		return "Slug is required.";
+	}
+
+	if (normalized.toLowerCase().endsWith(".md")) {
+		return "Pass the slug without the .md suffix.";
+	}
+
+	if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(normalized)) {
+		return "Slug must be lowercase kebab-case using only a-z, 0-9, and single hyphens.";
+	}
+
+	if (/^(?:19|20)\d{2}-\d{1,2}-\d{1,2}$/.test(normalized)) {
+		return "Slug must not be a date.";
+	}
+
+	const tokens = normalized.split("-");
+	if (tokens.length < MIN_PLAN_SLUG_WORDS) {
+		return `Slug must contain at least ${MIN_PLAN_SLUG_WORDS} words.`;
+	}
+	if (tokens.length > MAX_PLAN_SLUG_WORDS) {
+		return `Slug must contain at most ${MAX_PLAN_SLUG_WORDS} words.`;
+	}
+
+	if (tokens.some((token) => /^(?:19|20)\d{2}$/.test(token))) {
+		return "Slug must not contain date-like year tokens.";
+	}
+
+	if (tokens.every((token) => GENERIC_SLUG_WORDS.has(token))) {
+		return "Slug must include at least one specific, non-generic word.";
+	}
+
+	return undefined;
+}
+
+export function normalizePlanFilePath(rawPath: string): string {
+	const trimmed = rawPath.trim();
+	const withoutAt = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
+	if (withoutAt === "~") {
+		return homedir();
+	}
+	if (withoutAt.startsWith("~/")) {
+		return join(homedir(), withoutAt.slice(2));
+	}
+	return withoutAt;
+}
+
+export interface ResolvePlanSourceFileOptions {
+	cwd: string;
+	rawFilePath: string;
+	signal?: AbortSignal;
+	git?: GitGateway;
+	planStoreGateway?: PlanStoreGateway;
+}
+
+export interface ResolveGitRepoRootOptions {
+	cwd: string;
+	signal?: AbortSignal;
+	git?: GitGateway;
+}
+
+export async function resolvePlanSourceFile(
+	pi: CommandExecApi,
+	options: ResolvePlanSourceFileOptions,
+): Promise<string> {
+	const git = options.git ?? new RealGitGateway(pi);
+	const planStoreGateway = options.planStoreGateway ?? createRealPlanStoreGateway();
+	const normalizedPath = normalizePlanFilePath(options.rawFilePath);
+	if (!isAbsolute(normalizedPath)) {
+		throw new Error(
+			`Plan file path must be absolute or home-relative; got ${displayNonEmpty(normalizedPath)}.`,
+		);
+	}
+
+	const fileStat = await planStoreGateway.statPath(normalizedPath);
+	if (fileStat === undefined) {
+		throw new Error(`Plan file does not exist or is not accessible: ${normalizedPath}`);
+	}
+	if (fileStat.type !== "file") {
+		throw new Error(`Plan file must be a regular file: ${normalizedPath}`);
+	}
+
+	const realFilePath = await planStoreGateway.realpathOrResolve(normalizedPath);
+	const repoRoot = await resolveGitRepoRoot(pi, {
+		cwd: options.cwd,
+		git,
+		...optionalEntry("signal", options.signal),
+	});
+	if (repoRoot !== undefined) {
+		const realRepoRoot = await planStoreGateway.realpathOrResolve(repoRoot);
+		if (isPathInside(realRepoRoot, realFilePath)) {
+			throw new Error(
+				`Plan file must be outside the repository; got ${realFilePath} inside ${realRepoRoot}.`,
+			);
+		}
+	}
+
+	return realFilePath;
+}
+
+export async function resolveGitRepoRoot(
+	pi: CommandExecApi,
+	options: ResolveGitRepoRootOptions,
+): Promise<string | undefined> {
+	const git = options.git ?? new RealGitGateway(pi);
+	const root = await git.optionalRepoRoot({ cwd: options.cwd, signal: options.signal });
+	return root.type === "found" ? resolve(root.value) : undefined;
+}
+
+export function normalizeSummary(summary: string | undefined): string | undefined {
+	if (summary === undefined) {
+		return undefined;
+	}
+	const trimmed = summary.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function displayNonEmpty(value: string): string {
+	return value.length > 0 ? value : "(empty)";
+}

package/src/plan-store-gateway.ts

@@ -0,0 +1,104 @@
+import { open, readFile, readdir, realpath, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import { ensurePrivateParentDirectory } from "@nseng-ai/capability-kit/xdg";
+
+export interface PlanStoreGateway {
+	listDirectory(path: string): Promise<PlanStoreDirectoryRead>;
+	statPath(path: string): Promise<PlanStorePathStat | undefined>;
+	readTextFile(path: string): Promise<string>;
+	writeTextFileExclusive(path: string, content: string): Promise<void>;
+	realpathOrResolve(path: string): Promise<string>;
+}
+
+export type PlanStoreDirectoryRead =
+	| { type: "present"; entries: readonly PlanStoreDirectoryEntry[] }
+	| { type: "missing" };
+
+export interface PlanStoreDirectoryEntry {
+	name: string;
+	type: PlanStorePathType;
+}
+
+export interface PlanStorePathStat {
+	type: PlanStorePathType;
+	mtimeMs: number;
+}
+
+export type PlanStorePathType = "file" | "directory" | "other";
+
+export class RealPlanStoreGateway implements PlanStoreGateway {
+	async listDirectory(path: string): Promise<PlanStoreDirectoryRead> {
+		try {
+			const entries = await readdir(path, { withFileTypes: true });
+			return {
+				type: "present",
+				entries: entries.map((entry) => ({ name: entry.name, type: direntType(entry) })),
+			};
+		} catch (error) {
+			if (isNodeError(error) && error.code === "ENOENT") return { type: "missing" };
+			throw error;
+		}
+	}
+
+	async statPath(path: string): Promise<PlanStorePathStat | undefined> {
+		try {
+			const pathStat = await stat(path);
+			return { type: statsType(pathStat), mtimeMs: pathStat.mtimeMs };
+		} catch (error) {
+			if (isNodeError(error) && error.code === "ENOENT") return undefined;
+			throw error;
+		}
+	}
+
+	async readTextFile(path: string): Promise<string> {
+		return await readFile(path, "utf8");
+	}
+
+	async writeTextFileExclusive(path: string, content: string): Promise<void> {
+		await ensurePrivateParentDirectory(path);
+		let file: Awaited<ReturnType<typeof open>> | undefined;
+		try {
+			file = await open(path, "wx");
+			await file.writeFile(content, "utf8");
+		} catch (error) {
+			if (isNodeError(error) && error.code === "EEXIST") {
+				throw new Error(
+					`Saved plan file already exists in the local plan store; refusing to overwrite.\nPath: ${path}`,
+				);
+			}
+			throw error;
+		} finally {
+			await file?.close();
+		}
+	}
+
+	async realpathOrResolve(path: string): Promise<string> {
+		try {
+			return await realpath(path);
+		} catch {
+			// Missing paths still need stable containment comparisons at the domain layer.
+			return resolve(path);
+		}
+	}
+}
+
+export function createRealPlanStoreGateway(): PlanStoreGateway {
+	return new RealPlanStoreGateway();
+}
+
+function direntType(entry: { isFile(): boolean; isDirectory(): boolean }): PlanStorePathType {
+	if (entry.isFile()) return "file";
+	if (entry.isDirectory()) return "directory";
+	return "other";
+}
+
+function statsType(pathStat: { isFile(): boolean; isDirectory(): boolean }): PlanStorePathType {
+	if (pathStat.isFile()) return "file";
+	if (pathStat.isDirectory()) return "directory";
+	return "other";
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return typeof error === "object" && error !== null && "code" in error;
+}

package/src/saved-plan-content-slug.ts

@@ -0,0 +1,31 @@
+import type { CommandExecApi } from "@nseng-ai/foundation/exec";
+import {
+	buildContentSlugPrompt,
+	deriveContentSlug,
+	type ContentSlugDerivationVariant,
+	type ContentSlugEvidence,
+} from "./content-slug-derivation.ts";
+
+export type SavedPlanContentSlugEvidence = ContentSlugEvidence;
+
+const SAVED_PLAN_CONTENT_SLUG_VARIANT: ContentSlugDerivationVariant = {
+	slugKind: "saved-plan filename slug",
+	promptIntroLines: [
+		"Generate the saved-plan filename slug for the Markdown implementation plan content below.",
+		"Use only the final plan content. Do not use the current branch, repository name, request text, filename, or path.",
+	],
+	invalidSlugMessage: "Pi slug model output normalized to an invalid saved-plan filename slug.",
+	failureHeader: "Failed to derive saved-plan filename slug from plan content.",
+	noFallbackLine: "No assistant-generated slug or deterministic fallback was attempted.",
+};
+
+export async function deriveSavedPlanContentSlug(
+	pi: CommandExecApi,
+	input: { content: string; cwd: string; signal?: AbortSignal },
+): Promise<SavedPlanContentSlugEvidence> {
+	return deriveContentSlug(pi, input, SAVED_PLAN_CONTENT_SLUG_VARIANT);
+}
+
+export function buildSavedPlanContentSlugPrompt(content: string): string {
+	return buildContentSlugPrompt(content, SAVED_PLAN_CONTENT_SLUG_VARIANT);
+}