@nseng-ai/branch-context 0.1.1

package/src/core/cli.ts

@@ -0,0 +1,98 @@
+import { ClinkrGroup } from "@nseng-ai/clinkr";
+import { defineCli } from "@nseng-ai/foundation/cli-runtime";
+import { optionalEntry } from "@nseng-ai/foundation/primitives";
+
+import {
+	attachRequestSchema,
+	createRealBranchContextCliContext,
+	createRequestSchema,
+	handleAttach,
+	handleCheck,
+	handleCreate,
+	handleDelete,
+	handleList,
+	handleLoad,
+	keyRequestSchema,
+	listRequestSchema,
+	loadRequestSchema,
+	type BranchContextCliContext,
+	type CliDeps,
+} from "./operations.ts";
+
+const entry = defineCli<BranchContextCliContext, CliDeps, undefined>({
+	metaUrl: import.meta.url,
+	runtime: "typescript",
+	description: "Branch context operations.",
+	prepareRun: ({ deps, cwd }) => {
+		const context =
+			deps.context === undefined
+				? createRealBranchContextCliContext({
+						cwd,
+						...optionalEntry("planStoreRoot", deps.planStoreRoot),
+					})
+				: {
+						context: deps.context,
+						cwd,
+						...optionalEntry("planStoreRoot", deps.planStoreRoot),
+					};
+		return { type: "run", context, buildState: undefined };
+	},
+	configureCli: ({ root }) => {
+		const execGroup = new ClinkrGroup<BranchContextCliContext>({
+			name: "exec",
+			description: "Run hidden deterministic branch-context operations for agents.",
+			isHidden: true,
+		});
+		execGroup.command({
+			name: "from-plan",
+			description: "Create a branch context from a saved plan.",
+			schema: createRequestSchema,
+			handler: handleCreate,
+		});
+		execGroup.command({
+			name: "load",
+			description: "Load a branch-context entry and render the implementation prompt.",
+			schema: loadRequestSchema,
+			positionals: { key: { position: 0 } },
+			handler: handleLoad,
+		});
+		execGroup.command({
+			name: "attach",
+			description: "Attach a saved plan or file as branch context.",
+			schema: attachRequestSchema,
+			positionals: { key: { position: 0 } },
+			handler: handleAttach,
+		});
+		execGroup.command({
+			name: "list",
+			description: "List branch-context entries.",
+			schema: listRequestSchema,
+			handler: handleList,
+		});
+		execGroup.command({
+			name: "check",
+			description: "Check whether a branch-context entry exists.",
+			schema: keyRequestSchema,
+			positionals: { key: { position: 0 } },
+			handler: handleCheck,
+		});
+		execGroup.command({
+			name: "delete",
+			description: "Delete a branch-context entry.",
+			schema: keyRequestSchema,
+			positionals: { key: { position: 0 } },
+			handler: handleDelete,
+		});
+		root.group(execGroup);
+	},
+});
+
+export const VERSION = entry.version;
+
+export function buildCli(): ClinkrGroup<BranchContextCliContext> {
+	return entry.buildCli(undefined);
+}
+
+export async function runCli(args: readonly string[], deps: CliDeps = {}): Promise<number> {
+	return await entry.run(args, deps);
+}

package/src/core/constants.ts

@@ -0,0 +1,19 @@
+import { buildPlanFileName, validatePlanSlug } from "@nseng-ai/plans";
+
+export const BRANCH_CONTEXT_NAMESPACE = "branch-context";
+export const UNSUPPORTED_ATTACHED_PLAN_KEY = "plan.md";
+
+export function buildBranchContextPlanKey(slug: string): string {
+	const slugError = validatePlanSlug(slug);
+	if (slugError !== undefined) {
+		throw new Error(`Invalid branch context slug: ${slugError}`);
+	}
+	return buildPlanFileName(slug);
+}
+
+export function isSupportedBranchContextPlanKey(key: string): boolean {
+	if (key === UNSUPPORTED_ATTACHED_PLAN_KEY) return false;
+	if (!key.endsWith(".md")) return false;
+	const slug = key.slice(0, -".md".length);
+	return validatePlanSlug(slug) === undefined;
+}

package/src/core/context.ts

@@ -0,0 +1,45 @@
+import { RealGitBrmemGateway, type BrmemGateway } from "@nseng-ai/brmem";
+import { NodeCommandExecApi } from "@nseng-ai/foundation/exec";
+import type { CommandExecApi, StdinCapableCommandExecApi } from "@nseng-ai/foundation/exec";
+import { RealGitGateway } from "@nseng-ai/capability-kit/git";
+import type { GitGateway } from "@nseng-ai/capability-kit/git";
+import {
+	RealGraphiteBranchGateway,
+	type GraphiteBranchGateway,
+} from "@nseng-ai/capability-kit/graphite/branch";
+
+export interface BranchContextContext {
+	commands: CommandExecApi;
+	git: GitGateway;
+	brmem: BrmemGateway;
+	graphite: GraphiteBranchGateway;
+}
+
+export interface BranchContextContextOptions {
+	cwd?: string;
+}
+
+export type BranchContextContextFactory<Args extends unknown[]> = (
+	...args: Args
+) => BranchContextContext;
+
+export function createBranchContextContext(
+	commands: StdinCapableCommandExecApi,
+	options: BranchContextContextOptions = {},
+): BranchContextContext {
+	const cwd = options.cwd ?? process.cwd();
+	const git = new RealGitGateway(commands);
+	const brmem = new RealGitBrmemGateway({ cwd, commands, git });
+	return {
+		commands,
+		git,
+		brmem,
+		graphite: new RealGraphiteBranchGateway(commands),
+	};
+}
+
+export function createRealBranchContextContext(
+	options: BranchContextContextOptions = {},
+): BranchContextContext {
+	return createBranchContextContext(new NodeCommandExecApi(), options);
+}

package/src/core/existing-branch-reuse.ts

@@ -0,0 +1,230 @@
+import type { CommandExecApi } from "@nseng-ai/foundation/exec";
+import type { BrmemGateway } from "@nseng-ai/brmem";
+import { selectAttachedPlanKey } from "./attached-plan.ts";
+import { checkBranchContextEntryPresence, listBranchContextPlans } from "./branch-memory.ts";
+import type { BranchContextContext } from "./context.ts";
+import { BRANCH_CONTEXT_NAMESPACE } from "./constants.ts";
+import { extractBranchContextEvidenceFromSessionEntry } from "./session-artifact.ts";
+
+export type ExistingBranchContextReuseSource =
+	| "explicit-branch"
+	| "session-output"
+	| "current-branch";
+
+export interface ExistingBranchContextReuse {
+	branch: string;
+	key: string;
+	source: ExistingBranchContextReuseSource;
+}
+
+export interface ExistingBranchContextCandidate {
+	branch: string;
+	source: ExistingBranchContextReuseSource;
+	requestedKey?: string;
+}
+
+export interface ResolveExistingBranchContextReuseParams {
+	explicitBranch?: string;
+	sessionEntries?: readonly unknown[];
+}
+
+export interface ResolveExistingBranchContextReuseOptions {
+	cwd: string;
+	context: BranchContextContext;
+	signal?: AbortSignal;
+}
+
+type ReuseVerificationFailure =
+	| { type: "candidate"; candidate: ExistingBranchContextCandidate; message: string }
+	| { type: "current-branch-resolution"; message: string };
+
+type CandidateVerification =
+	| { type: "verified"; reuse: ExistingBranchContextReuse }
+	| { type: "failure"; message: string };
+
+export async function resolveExistingBranchContextReuse(
+	_pi: CommandExecApi,
+	params: ResolveExistingBranchContextReuseParams,
+	options: ResolveExistingBranchContextReuseOptions,
+): Promise<ExistingBranchContextReuse> {
+	const brmem = options.context.brmem;
+	const failures: ReuseVerificationFailure[] = [];
+
+	const explicitBranch = params.explicitBranch;
+	if (explicitBranch !== undefined) {
+		const candidate: ExistingBranchContextCandidate = {
+			branch: explicitBranch,
+			source: "explicit-branch",
+		};
+		const result = await verifyCandidate(brmem, candidate);
+		if (result.type === "verified") {
+			return result.reuse;
+		}
+		throw buildNoReusableBranchError([{ type: "candidate", candidate, message: result.message }]);
+	}
+
+	const sessionCandidates = collectSessionCandidates(params.sessionEntries ?? []);
+	if (sessionCandidates.length > 1) {
+		throw new Error(
+			[
+				"Multiple existing branch-context candidates were found in this session.",
+				"Rerun with `--branch <target-branch>` to choose explicitly.",
+				"",
+				"Candidates:",
+				...sessionCandidates.map(formatCandidateListItem),
+			].join("\n"),
+		);
+	}
+
+	const sessionCandidate = sessionCandidates[0];
+	if (sessionCandidate !== undefined) {
+		const result = await verifyCandidate(brmem, sessionCandidate);
+		if (result.type === "verified") {
+			return result.reuse;
+		}
+		failures.push({ type: "candidate", candidate: sessionCandidate, message: result.message });
+	}
+
+	const branch = await options.context.git.currentBranch({
+		cwd: options.cwd,
+		signal: options.signal,
+	});
+	if (branch.type === "branch") {
+		const candidate: ExistingBranchContextCandidate = {
+			branch: branch.branch,
+			source: "current-branch",
+		};
+		const result = await verifyCandidate(brmem, candidate);
+		if (result.type === "verified") {
+			return result.reuse;
+		}
+		failures.push({ type: "candidate", candidate, message: result.message });
+	} else if (branch.type === "detached") {
+		failures.push({ type: "current-branch-resolution", message: "Current HEAD is detached." });
+	} else {
+		failures.push({ type: "current-branch-resolution", message: branch.error.message });
+	}
+
+	throw buildNoReusableBranchError(failures);
+}
+
+async function verifyCandidate(
+	brmem: BrmemGateway,
+	candidate: ExistingBranchContextCandidate,
+): Promise<CandidateVerification> {
+	if (candidate.requestedKey !== undefined) {
+		let key: string;
+		try {
+			key = selectAttachedPlanKey({
+				branch: candidate.branch,
+				requestedKey: candidate.requestedKey,
+				entries: [
+					{
+						branch: candidate.branch,
+						key: candidate.requestedKey,
+						namespace: BRANCH_CONTEXT_NAMESPACE,
+						refName: "",
+					},
+				],
+			});
+		} catch (error) {
+			return { type: "failure", message: error instanceof Error ? error.message : String(error) };
+		}
+		const presence = await checkBranchContextEntryPresence(brmem, {
+			branch: candidate.branch,
+			key,
+		});
+		if (presence.type === "present") {
+			return {
+				type: "verified",
+				reuse: { branch: candidate.branch, key, source: candidate.source },
+			};
+		}
+		if (presence.type === "absent") {
+			return { type: "failure", message: `Branch-context key \`${key}\` is absent.` };
+		}
+		return { type: "failure", message: presence.error.message };
+	}
+
+	const list = await listBranchContextPlans(brmem, { branch: candidate.branch });
+	if (!list.ok) {
+		return { type: "failure", message: list.error.message };
+	}
+	try {
+		const key = selectAttachedPlanKey({ branch: candidate.branch, entries: list.value });
+		return { type: "verified", reuse: { branch: candidate.branch, key, source: candidate.source } };
+	} catch (error) {
+		return { type: "failure", message: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+function collectSessionCandidates(entries: readonly unknown[]): ExistingBranchContextCandidate[] {
+	const candidates: ExistingBranchContextCandidate[] = [];
+	for (const entry of entries) {
+		const evidence = extractBranchContextEvidenceFromSessionEntry(entry);
+		if (evidence === undefined || evidence.namespace !== BRANCH_CONTEXT_NAMESPACE) {
+			continue;
+		}
+		const candidate = {
+			branch: evidence.branch,
+			requestedKey: evidence.key,
+			source: "session-output",
+		} as const;
+		if (
+			!candidates.some(
+				(existing) =>
+					existing.branch === candidate.branch && existing.requestedKey === candidate.requestedKey,
+			)
+		) {
+			candidates.push(candidate);
+		}
+	}
+	return candidates;
+}
+
+function buildNoReusableBranchError(failures: readonly ReuseVerificationFailure[]): Error {
+	return new Error(
+		[
+			"No existing branch context with an attached plan could be reused.",
+			"",
+			"Verification failures:",
+			...failures.map(formatVerificationFailureListItem),
+		].join("\n"),
+	);
+}
+
+export function formatExistingBranchContextReuse(reuse: ExistingBranchContextReuse): string {
+	return [
+		"Existing branch context with attached plan:",
+		`Branch: ${reuse.branch}`,
+		`Branch Memory namespace: ${BRANCH_CONTEXT_NAMESPACE}`,
+		`Branch Memory key: ${reuse.key}`,
+		`Reuse source: ${formatExistingReuseSource(reuse.source)}`,
+	].join("\n");
+}
+
+function formatExistingReuseSource(source: ExistingBranchContextReuseSource): string {
+	switch (source) {
+		case "explicit-branch":
+			return "explicit --branch";
+		case "session-output":
+			return "current session branch-context output";
+		case "current-branch":
+			return "current branch";
+	}
+}
+
+function formatCandidateListItem(candidate: ExistingBranchContextCandidate): string {
+	const keyPart =
+		candidate.requestedKey === undefined
+			? "attached key: auto-select"
+			: `attached key: ${candidate.requestedKey}`;
+	return `- ${candidate.branch} (${keyPart}; source: ${formatExistingReuseSource(candidate.source)})`;
+}
+
+function formatVerificationFailureListItem(failure: ReuseVerificationFailure): string {
+	if (failure.type === "candidate") {
+		return `${formatCandidateListItem(failure.candidate)}\n  ${failure.message}`;
+	}
+	return `- could not resolve current branch:\n  ${failure.message}`;
+}

package/src/core/index.ts

@@ -0,0 +1,47 @@
+export {
+	createBranchContextContext,
+	createRealBranchContextContext,
+	type BranchContextContext,
+	type BranchContextContextFactory,
+	type BranchContextContextOptions,
+} from "./context.ts";
+export {
+	BRANCH_CONTEXT_NAMESPACE,
+	buildBranchContextPlanKey,
+	buildBranchContextCreateOperation,
+	createBranchContextFromFile,
+	deriveTargetBranch,
+	formatBranchContextCreateFailure,
+	formatBranchContextCreatePreview,
+	formatBranchContextEvidence,
+	describeBranchContextGraphiteCreationSteps,
+	resolveBranchContextCreatePreviewContext,
+	type BranchContextCreateOperation,
+	type BranchContextEvidence,
+	type BranchCreationMethod,
+} from "./branch-context-creation.ts";
+export {
+	buildImplBranchContextPrompt,
+	formatLoadedAttachedPlanEvidence,
+	loadBranchContextPlan,
+	type LoadedAttachedPlan,
+} from "./attached-plan.ts";
+export {
+	BRANCH_CONTEXT_OUTPUT_MESSAGE_TYPE,
+	buildBranchContextOutputMessage,
+	extractBranchContextEvidence,
+	extractBranchContextEvidenceFromSessionEntry,
+	findLatestBranchContextEvidence,
+	type BranchContextOutputDetails,
+	type BranchContextOutputMessage,
+} from "./session-artifact.ts";
+export {
+	formatExistingBranchContextReuse,
+	resolveExistingBranchContextReuse,
+	type ExistingBranchContextReuse,
+} from "./existing-branch-reuse.ts";
+export {
+	buildPlanContentSlugPrompt,
+	derivePlanContentSlug,
+	type PlanContentSlugEvidence,
+} from "./plan-content-slug.ts";