@nseng-ai/plans 0.1.1

package/package.json

@@ -0,0 +1,29 @@
+{
+	"name": "@nseng-ai/plans",
+	"version": "0.1.1",
+	"type": "module",
+	"files": [
+		"src"
+	],
+	"engines": {
+		"node": ">=24.12.0",
+		"pnpm": ">=11.8.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"bin": {
+		"enriched-plan": "src/cli.ts"
+	},
+	"exports": {
+		".": "./src/index.ts",
+		"./api": "./src/api.ts",
+		"./testing": "./src/testing.ts"
+	},
+	"dependencies": {
+		"@nseng-ai/capability-kit": "0.1.1",
+		"@nseng-ai/clinkr": "0.1.1",
+		"@nseng-ai/foundation": "0.1.1",
+		"zod": "^4.4.3"
+	}
+}

package/src/api.ts

@@ -0,0 +1,25 @@
+export {
+	NoSavedPlanAvailableError,
+	buildRepoPlanStoreKey,
+	encodeBranchForPlanPath,
+	formatSavedPlanFileEvidence,
+	normalizeRepoOriginUrl,
+	resolvePlanStoreDirectory,
+	writeSavedPlanFile,
+	type PlanStoreDirectoryEvidence,
+	type RepoIdentitySource,
+	type SavedPlanFileEvidence,
+} from "./saved-plan-file.ts";
+export {
+	buildSavedPlanContentSlugPrompt,
+	deriveSavedPlanContentSlug,
+	type SavedPlanContentSlugEvidence,
+} from "./saved-plan-content-slug.ts";
+export {
+	WRITE_SAVED_PLAN_FILE_TOOL_NAME,
+	findLatestSessionSavedPlanFile,
+	resolveSelectedSavedPlanFile,
+	type SelectedSavedPlanFile,
+	type ValidateSessionSavedPlanCandidateOptions,
+	type ValidatedSessionSavedPlan,
+} from "./saved-plan-selection.ts";

package/src/cli.ts

@@ -0,0 +1,430 @@
+#!/usr/bin/env node
+
+import { resolve } from "node:path";
+
+import { ClinkrGroup, failure, negative, ok, usageError, type ClinkrExit } from "@nseng-ai/clinkr";
+import {
+	defineCli,
+	readStdin,
+	runOperationCommand,
+	type CliEntrypointDeps,
+} from "@nseng-ai/foundation/cli-runtime";
+import { formatErrorMessage } from "@nseng-ai/foundation/primitives";
+import { NodeCommandExecApi } from "@nseng-ai/foundation/exec";
+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 { z } from "zod";
+
+import {
+	normalizePlanFilePath,
+	resolvePlanSourceFile,
+	validatePlanSlug,
+} from "./plan-persistence.ts";
+import { createRealPlanStoreGateway, type PlanStoreGateway } from "./plan-store-gateway.ts";
+import {
+	buildPlanStoreOptions,
+	findLatestSavedPlanFile,
+	formatSavedPlanFileEvidence,
+	NoSavedPlanAvailableError,
+	listSavedPlans,
+	writeSavedPlanFile,
+	type LatestSavedPlanFileEvidence,
+	type PlanStoreOptions,
+	type SavedPlanFileEvidence,
+	type SavedPlanListItem,
+} from "./saved-plan-file.ts";
+
+type PlansOperation = "list" | "save" | "resolve";
+
+const listRequestSchema = z.object({
+	planStoreRoot: z
+		.string()
+		.optional()
+		.describe("Plan store root directory (relative paths resolve against cwd)."),
+});
+
+const saveRequestSchema = z.object({
+	slug: z.string().describe("Saved plan slug."),
+	summary: z.string().optional().describe("Optional saved-plan summary."),
+	stdin: z.boolean().optional().describe("Read plan content from stdin."),
+	contentFile: z.string().optional().describe("Read plan content from this file path."),
+});
+
+const resolveRequestSchema = z.object({
+	path: z.string().optional().describe("Absolute, @-prefixed, or home-relative plan file path."),
+});
+
+type ListRequest = z.infer<typeof listRequestSchema>;
+type SaveRequest = z.infer<typeof saveRequestSchema>;
+type ResolveRequest = z.infer<typeof resolveRequestSchema>;
+
+interface ExplicitResolvePlanEvidence {
+	source: "explicit";
+	filePath: string;
+}
+
+type LatestResolvePlanEvidence = LatestSavedPlanFileEvidence & { source: "latest" };
+
+type ResolvePlanEvidence = ExplicitResolvePlanEvidence | LatestResolvePlanEvidence;
+
+type SavedPlanListData = ReturnType<typeof savedPlanListJson>;
+type SavedPlanFileData = ReturnType<typeof savedPlanFileJson>;
+interface NoSavedPlanData {
+	code: NoSavedPlanAvailableError["reason"];
+	directoryPath: string;
+}
+
+type ResolvePlanData = ReturnType<typeof resolvePlanJson> | NoSavedPlanData;
+
+export interface CliDeps extends Pick<CliEntrypointDeps, "cwd" | "stdout" | "stderr"> {
+	commands?: CommandExecApi;
+	git?: GitGateway;
+	stdin?: () => Promise<string>;
+	planStoreRoot?: string;
+	planStoreGateway?: PlanStoreGateway;
+}
+
+export interface PlansCliContext {
+	commands: CommandExecApi;
+	git: GitGateway;
+	cwd: string;
+	stdin: () => Promise<string>;
+	planStoreRoot?: string;
+	planStoreGateway: PlanStoreGateway;
+}
+
+const entry = defineCli<PlansCliContext, CliDeps, undefined>({
+	metaUrl: import.meta.url,
+	runtime: "typescript",
+	description: "Enriched-plan operations. An enriched plan is any plan saved into ns.",
+	prepareRun: ({ deps, cwd }) => {
+		const commands = deps.commands ?? new NodeCommandExecApi();
+		const context: PlansCliContext = {
+			commands,
+			git: deps.git ?? new RealGitGateway(commands),
+			cwd,
+			stdin: deps.stdin ?? readStdin,
+			planStoreGateway: deps.planStoreGateway ?? createRealPlanStoreGateway(),
+			...(deps.planStoreRoot === undefined ? {} : { planStoreRoot: deps.planStoreRoot }),
+		};
+		return { type: "run", context, buildState: undefined };
+	},
+	configureCli: ({ root }) => {
+		root.command({
+			name: "list",
+			description: "List saved plans for the current repository across all branch keys.",
+			schema: listRequestSchema,
+			handler: handleList,
+			renderHuman: formatSavedPlanListData,
+		});
+
+		const execGroup = new ClinkrGroup<PlansCliContext>({
+			name: "exec",
+			description: "Run hidden deterministic saved-plan operations for agents.",
+			isHidden: true,
+		});
+		execGroup.command({
+			name: "save",
+			description: "Save a source-branch plan file in the local store.",
+			schema: saveRequestSchema,
+			handler: handleSave,
+		});
+		execGroup.command({
+			name: "resolve",
+			description: "Resolve an explicit or latest source-branch plan file.",
+			schema: resolveRequestSchema,
+			positionals: { path: { position: 0 } },
+			handler: handleResolve,
+			renderHuman: renderResolvePlanData,
+		});
+		root.group(execGroup);
+	},
+});
+
+export const VERSION = entry.version;
+
+export function buildCli(): ClinkrGroup<PlansCliContext> {
+	return entry.buildCli(undefined);
+}
+
+export async function runCli(args: readonly string[], deps: CliDeps = {}): Promise<number> {
+	return await entry.run(args, deps);
+}
+
+async function handleList(
+	ctx: PlansCliContext,
+	request: ListRequest,
+): Promise<ClinkrExit<SavedPlanListData>> {
+	return await runOperationCommand({
+		operation: "list",
+		action: async () => {
+			const cliPlanStoreRoot =
+				request.planStoreRoot === undefined
+					? undefined
+					: normalizeRootPath(request.planStoreRoot, ctx.cwd);
+			const planStoreRoot = cliPlanStoreRoot ?? ctx.planStoreRoot;
+			const plans = await listSavedPlans(ctx.commands, planStoreOptions(ctx, planStoreRoot));
+			return ok(savedPlanListJson(plans));
+		},
+		failureFromError: plansFailureFromError,
+	});
+}
+
+async function handleSave(
+	ctx: PlansCliContext,
+	request: SaveRequest,
+): Promise<ClinkrExit<SavedPlanFileData>> {
+	return await runOperationCommand({
+		operation: "save",
+		action: async () => {
+			const slugError = validatePlanSlug(request.slug);
+			if (slugError !== undefined) {
+				return usageError(`Invalid saved plan slug: ${slugError}`, {
+					code: "invalid-slug",
+					argument: "slug",
+					reason: slugError,
+				});
+			}
+			if (Boolean(request.stdin) === (request.contentFile !== undefined)) {
+				return usageError("Pass exactly one of --stdin or --content-file <path>.", {
+					code: "invalid-save-input",
+					requiredExactlyOneOf: ["--stdin", "--content-file"],
+				});
+			}
+
+			const contentFile = request.contentFile;
+			let content: string;
+			if (request.stdin === true) {
+				content = await ctx.stdin();
+			} else {
+				if (contentFile === undefined) {
+					throw new Error("Save input validation invariant failed.");
+				}
+				content = await ctx.planStoreGateway.readTextFile(normalizePlanFilePath(contentFile));
+			}
+			const evidence = await writeSavedPlanFile(
+				ctx.commands,
+				{
+					slug: request.slug,
+					content,
+					...(request.summary === undefined ? {} : { summary: request.summary }),
+				},
+				planStoreOptions(ctx),
+			);
+			return ok(savedPlanFileJson(evidence), { human: formatSavedPlanFileEvidence(evidence) });
+		},
+		failureFromError: plansFailureFromError,
+	});
+}
+
+async function handleResolve(
+	ctx: PlansCliContext,
+	request: ResolveRequest,
+): Promise<ClinkrExit<ResolvePlanData>> {
+	return await runOperationCommand<PlansOperation, ResolvePlanData>({
+		operation: "resolve",
+		action: async () => {
+			try {
+				return ok(resolvePlanJson(await resolvePlanEvidence(request, ctx)));
+			} catch (error) {
+				if (error instanceof NoSavedPlanAvailableError) {
+					return negative(error.message, {
+						data: { code: error.reason, directoryPath: error.directoryPath },
+					});
+				}
+				throw error;
+			}
+		},
+		failureFromError: plansFailureFromError,
+	});
+}
+
+function plansFailureFromError(operation: PlansOperation, error: unknown): ClinkrExit<never> {
+	return failure(plansErrorType(operation), formatErrorMessage(error), {
+		code: "unexpected-error",
+	});
+}
+
+function planStoreOptions(
+	ctx: PlansCliContext,
+	planStoreRoot: string | undefined = ctx.planStoreRoot,
+): PlanStoreOptions {
+	return buildPlanStoreOptions({
+		cwd: ctx.cwd,
+		git: ctx.git,
+		planStoreGateway: ctx.planStoreGateway,
+		planStoreRoot,
+	});
+}
+
+function plansErrorType(operation: PlansOperation): string {
+	switch (operation) {
+		case "list":
+			return "saved-plan-list-failed";
+		case "save":
+			return "saved-plan-write-failed";
+		case "resolve":
+			return "saved-plan-resolution-failed";
+	}
+}
+
+function normalizeRootPath(rawPath: string, cwd: string): string {
+	const normalized = normalizePlanFilePath(rawPath);
+	return resolve(cwd, normalized);
+}
+
+async function resolvePlanEvidence(
+	args: ResolveRequest,
+	ctx: PlansCliContext,
+): Promise<ResolvePlanEvidence> {
+	if (args.path !== undefined) {
+		const filePath = await resolvePlanSourceFile(ctx.commands, {
+			cwd: ctx.cwd,
+			rawFilePath: args.path,
+			git: ctx.git,
+			planStoreGateway: ctx.planStoreGateway,
+		});
+		return { source: "explicit", filePath };
+	}
+	const latest = await findLatestSavedPlanFile(ctx.commands, planStoreOptions(ctx));
+	return { source: "latest", ...latest };
+}
+
+function formatSavedPlanListData(data: SavedPlanListData): string {
+	if (data.plans.length === 0) {
+		return "No saved plans found for the current repository.";
+	}
+
+	const lines = ["Saved plans:"];
+	for (const plan of data.plans) {
+		lines.push(
+			[
+				`- ${plan.slug}`,
+				`  Branch key: ${plan.branchKey}`,
+				`  Modified: ${new Date(plan.modifiedTimeMs).toISOString()}`,
+				`  Path: ${plan.path}`,
+			].join("\n"),
+		);
+	}
+	return lines.join("\n");
+}
+
+function renderResolvePlanData(data: ResolvePlanData): string {
+	if (!("source" in data)) {
+		return `No saved plan available: ${data.code}\nDirectory: ${data.directoryPath}`;
+	}
+	if (data.source === "explicit") {
+		return [`Resolved explicit plan file.`, `Path: ${data.filePath}`].join("\n");
+	}
+	return [
+		"Resolved latest saved plan file in local plan store.",
+		`Path: ${data.filePath}`,
+		`Repo key: ${data.repoKey}`,
+		`Repo root: ${data.repoRoot}`,
+		`Repo identity source: ${data.repoIdentitySource}`,
+		`Source branch: ${data.sourceBranch}`,
+		`Branch path segment: ${data.branchKey}`,
+		`Slug: ${data.slug}`,
+		`Modified time ms: ${data.modifiedTimeMs}`,
+	].join("\n");
+}
+
+function savedPlanListJson(plans: readonly SavedPlanListItem[]): {
+	plans: ReturnType<typeof savedPlanListItemJson>[];
+} {
+	return { plans: plans.map(savedPlanListItemJson) };
+}
+
+function savedPlanListItemJson(plan: SavedPlanListItem): {
+	slug: string;
+	branchKey: string;
+	modifiedTimeMs: number;
+	path: string;
+	fileName: string;
+	repo: {
+		root: string;
+		key: string;
+		identitySource: string;
+		planStorePath: string;
+	};
+} {
+	return {
+		slug: plan.slug,
+		branchKey: plan.branchKey,
+		modifiedTimeMs: plan.modifiedTimeMs,
+		path: plan.filePath,
+		fileName: plan.fileName,
+		repo: {
+			root: plan.repoRoot,
+			key: plan.repoKey,
+			identitySource: plan.repoIdentitySource,
+			planStorePath: plan.repoDirectoryPath,
+		},
+	};
+}
+
+function savedPlanFileJson(evidence: SavedPlanFileEvidence): {
+	slug: string;
+	filePath: string;
+	repoRoot: string;
+	repoKey: string;
+	repoIdentitySource: SavedPlanFileEvidence["repoIdentitySource"];
+	sourceBranch: string;
+	branchKey: string;
+	summary?: string;
+} {
+	return {
+		slug: evidence.slug,
+		filePath: evidence.filePath,
+		repoRoot: evidence.repoRoot,
+		repoKey: evidence.repoKey,
+		repoIdentitySource: evidence.repoIdentitySource,
+		sourceBranch: evidence.sourceBranch,
+		branchKey: evidence.branchKey,
+		...(evidence.summary === undefined ? {} : { summary: evidence.summary }),
+	};
+}
+
+function resolvePlanJson(evidence: ResolvePlanEvidence):
+	| {
+			source: "explicit";
+			filePath: string;
+	  }
+	| {
+			source: "latest";
+			filePath: string;
+			slug: string;
+			fileName: string;
+			modifiedTimeMs: number;
+			repoRoot: string;
+			repoKey: string;
+			repoIdentitySource: LatestSavedPlanFileEvidence["repoIdentitySource"];
+			sourceBranch: string;
+			branchKey: string;
+			directoryPath: string;
+	  } {
+	switch (evidence.source) {
+		case "explicit":
+			return {
+				source: evidence.source,
+				filePath: evidence.filePath,
+			};
+		case "latest":
+			return {
+				source: evidence.source,
+				filePath: evidence.filePath,
+				slug: evidence.slug,
+				fileName: evidence.fileName,
+				modifiedTimeMs: evidence.modifiedTimeMs,
+				repoRoot: evidence.repoRoot,
+				repoKey: evidence.repoKey,
+				repoIdentitySource: evidence.repoIdentitySource,
+				sourceBranch: evidence.sourceBranch,
+				branchKey: evidence.branchKey,
+				directoryPath: evidence.directoryPath,
+			};
+	}
+}
+
+await entry.runIfMain({ isImportMetaMain: import.meta.main });

package/src/content-slug-derivation.ts

@@ -0,0 +1,127 @@
+import { type CommandExecApi, formatOutputSection } from "@nseng-ai/foundation/exec";
+import { deriveSlugWithModel, type SlugModelEvidence } from "@nseng-ai/capability-kit/model-slug";
+import { MAX_PLAN_SLUG_WORDS, MIN_PLAN_SLUG_WORDS, validatePlanSlug } from "./plan-persistence.ts";
+
+const MAX_ERROR_CHARS = 4_000;
+
+export const MAX_PLAN_CONTENT_CHARS = 32_000;
+
+export interface ContentSlugDerivationVariant {
+	slugKind: string;
+	promptIntroLines: readonly string[];
+	invalidSlugMessage: string;
+	failureHeader: string;
+	noFallbackLine: string;
+}
+
+export interface DeriveContentSlugInput {
+	content: string;
+	cwd: string;
+	signal?: AbortSignal;
+}
+
+export type ContentSlugEvidence = SlugModelEvidence;
+
+export async function deriveContentSlug(
+	pi: CommandExecApi,
+	input: DeriveContentSlugInput,
+	variant: ContentSlugDerivationVariant,
+): Promise<ContentSlugEvidence> {
+	const prompt = buildContentSlugPrompt(input.content, variant);
+	const result = await deriveSlugWithModel({
+		cwd: input.cwd,
+		prompt,
+		...(input.signal === undefined ? {} : { signal: input.signal }),
+		slugKind: variant.slugKind,
+		normalizeOutput: normalizePlanContentSlugOutput,
+		exec: (command, args, options) => pi.exec(command, args, options),
+	});
+	if (!result.ok) {
+		throw slugDerivationFailed(variant, result.failure.lines);
+	}
+
+	const { slug, rawOutput } = result.evidence;
+	const slugError = validatePlanSlug(slug);
+	if (slugError !== undefined) {
+		throw slugDerivationFailed(variant, [
+			variant.invalidSlugMessage,
+			`Normalized slug: ${slug}`,
+			`Reason: ${slugError}`,
+			formatOutputSection("stdout", rawOutput, { maxChars: MAX_ERROR_CHARS, maxLines: 80 }),
+		]);
+	}
+
+	return result.evidence;
+}
+
+export function buildContentSlugPrompt(
+	content: string,
+	variant: ContentSlugDerivationVariant,
+): string {
+	return [
+		...variant.promptIntroLines,
+		"Return exactly one slug and no prose.",
+		"Rules:",
+		"- Use lowercase ASCII kebab-case words separated by single hyphens.",
+		`- Use ${MIN_PLAN_SLUG_WORDS}–${MAX_PLAN_SLUG_WORDS} words.`,
+		"- Make the slug specific to the implementation described by the plan.",
+		"- Prefer concrete deliverables and nouns from the plan body.",
+		"- Do not use dates, random IDs, generic-only slugs, or the saved-plan filename.",
+		"",
+		"## Plan content",
+		truncatePlanContentForSlug(displayPlanContentForSlug(content)),
+	].join("\n");
+}
+
+function displayPlanContentForSlug(content: string): string {
+	const trimmed = content.trim();
+	return trimmed.length > 0 ? trimmed : "(empty plan content)";
+}
+
+export function normalizePlanContentSlugOutput(value: string): string | undefined {
+	const firstLine = firstNonEmptyModelOutputLine(value);
+	if (firstLine === undefined) {
+		return undefined;
+	}
+
+	const slug = firstLine
+		.toLowerCase()
+		.normalize("NFKD")
+		.replace(/[\u0300-\u036f]/g, "")
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-|-$/g, "");
+	const withoutPlanSuffix = slug.replace(/(?:-plan)+$/g, "").replace(/^-|-$/g, "");
+	if (withoutPlanSuffix.length === 0) {
+		return undefined;
+	}
+
+	const repaired = withoutPlanSuffix
+		.split("-")
+		.filter(Boolean)
+		.slice(0, MAX_PLAN_SLUG_WORDS)
+		.join("-");
+	return repaired.length > 0 ? repaired : undefined;
+}
+
+export function truncatePlanContentForSlug(content: string): string {
+	if (content.length <= MAX_PLAN_CONTENT_CHARS) {
+		return content;
+	}
+	return `${content.slice(0, MAX_PLAN_CONTENT_CHARS)}\n\n[Plan content truncated for slug generation]`;
+}
+
+function firstNonEmptyModelOutputLine(value: string): string | undefined {
+	return value
+		.replace(/```[\s\S]*?```/g, (match) => match.replace(/```[a-zA-Z]*\n?|```/g, ""))
+		.split("\n")
+		.map((line) => line.trim())
+		.find((line) => line.length > 0);
+}
+
+function slugDerivationFailed(
+	variant: ContentSlugDerivationVariant,
+	lines: readonly string[],
+): Error {
+	return new Error([variant.failureHeader, ...lines, variant.noFallbackLine].join("\n"));
+}

package/src/index.ts

@@ -0,0 +1,72 @@
+export { buildCli, runCli, type CliDeps, type PlansCliContext } from "./cli.ts";
+export {
+	buildContentSlugPrompt,
+	deriveContentSlug,
+	MAX_PLAN_CONTENT_CHARS,
+	normalizePlanContentSlugOutput,
+	truncatePlanContentForSlug,
+	type ContentSlugDerivationVariant,
+	type ContentSlugEvidence,
+	type DeriveContentSlugInput,
+} from "./content-slug-derivation.ts";
+export {
+	createRealPlanStoreGateway,
+	RealPlanStoreGateway,
+	type PlanStoreDirectoryEntry,
+	type PlanStoreDirectoryRead,
+	type PlanStoreGateway,
+	type PlanStorePathStat,
+	type PlanStorePathType,
+} from "./plan-store-gateway.ts";
+export {
+	isPathInside,
+	normalizePlanFilePath,
+	normalizeSummary,
+	resolveGitRepoRoot,
+	resolvePlanSourceFile,
+	validatePlanSlug,
+} from "./plan-persistence.ts";
+export {
+	NoSavedPlanAvailableError,
+	buildPlanStoreOptions,
+	buildPlanFileName,
+	buildPlanStoreBranchDirectoryPath,
+	buildRepoPlanStoreKey,
+	defaultPlanStoreRoot,
+	encodeBranchForPlanPath,
+	findLatestSavedPlanFile,
+	formatSavedPlanFileEvidence,
+	listSavedPlans,
+	normalizeRepoOriginUrl,
+	resolvePlanStoreDirectory,
+	resolvePlanStoreRepoDirectory,
+	sanitizePlanPathSegment,
+	writeSavedPlanFile,
+	type LatestSavedPlanFileEvidence,
+	type NoSavedPlanAvailableReason,
+	type PlanStoreDirectoryEvidence,
+	type PlanStoreOptions,
+	type PlanStoreRepoEvidence,
+	type RepoIdentitySource,
+	type SavedPlanFileEvidence,
+	type SavedPlanFileParams,
+	type SavedPlanListItem,
+} from "./saved-plan-file.ts";
+export {
+	buildSavedPlanContentSlugPrompt,
+	deriveSavedPlanContentSlug,
+	type SavedPlanContentSlugEvidence,
+} from "./saved-plan-content-slug.ts";
+export {
+	WRITE_SAVED_PLAN_FILE_TOOL_NAME,
+	extractSavedPlanFileEvidenceFromSessionEntry,
+	findLatestSessionSavedPlanFile,
+	resolveSelectedSavedPlanFile,
+	validateSessionSavedPlanCandidate,
+	type LatestSessionSavedPlanResult,
+	type ResolveSelectedSavedPlanFileOptions,
+	type SelectedSavedPlanFile,
+	type SessionSavedPlanValidation,
+	type ValidateSessionSavedPlanCandidateOptions,
+	type ValidatedSessionSavedPlan,
+} from "./saved-plan-selection.ts";