@nseng-ai/branch-context 0.1.1

package/src/pi/gt/upstack-impl-launch.ts

@@ -0,0 +1,154 @@
+import { type BranchContextEvidence } from "@nseng-ai/branch-context/api";
+import { formatImplBranchContextCommand } from "../surfaces.ts";
+import type { ExecResult } from "@nseng-ai/foundation/command";
+import { setRuntimeStatus } from "@nseng-ai/pi/runtime/status";
+import type { ExtensionAPI, NewSessionOptions, NewSessionResult } from "../host-types.ts";
+
+export type BranchContextGtUpstackImplHost = Pick<ExtensionAPI, "exec">;
+
+export type BranchContextGtUpstackImplNewSessionOptions = NewSessionOptions;
+export type BranchContextGtUpstackImplNewSessionResult = NewSessionResult;
+
+interface LaunchStatusUi {
+	setStatus?(key: string, value: string | undefined): void;
+}
+
+export interface BranchContextGtUpstackImplContext {
+	cwd: string;
+	hasUI: boolean;
+	ui: LaunchStatusUi;
+	sessionManager?: {
+		getSessionFile?(): string | undefined;
+	};
+	newSession(
+		options?: BranchContextGtUpstackImplNewSessionOptions,
+	): Promise<BranchContextGtUpstackImplNewSessionResult>;
+}
+
+export interface BranchContextGtUpstackImplLaunchOptions {
+	host: BranchContextGtUpstackImplHost;
+	ctx: BranchContextGtUpstackImplContext;
+	statusKey: string;
+	target: Pick<BranchContextEvidence, "branch" | "key">;
+	signal?: AbortSignal;
+}
+
+export type BranchContextGtUpstackImplLaunchPhase = "checkout" | "new-session";
+
+export type BranchContextGtUpstackImplLaunchResult =
+	| { type: "launched"; branch: string; key: string; parentSession?: string }
+	| { type: "cancelled"; branch: string; key: string; parentSession?: string }
+	| {
+			type: "failed";
+			branch: string;
+			key: string;
+			phase: BranchContextGtUpstackImplLaunchPhase;
+			message: string;
+			parentSession?: string;
+	  };
+
+const CHECKOUT_TIMEOUT_MS = 30_000;
+
+export async function runBranchContextGtUpstackImplLaunch(
+	options: BranchContextGtUpstackImplLaunchOptions,
+): Promise<BranchContextGtUpstackImplLaunchResult> {
+	const { branch, key } = options.target;
+	let isReplacementSessionActive = false;
+	let phase: BranchContextGtUpstackImplLaunchPhase = "checkout";
+	let parentSession: string | undefined;
+
+	try {
+		setRuntimeStatus(options.ctx, options.statusKey, "checking out branch context…");
+		const checkout = await checkoutBranchContext({
+			host: options.host,
+			cwd: options.ctx.cwd,
+			targetBranch: branch,
+			signal: options.signal,
+		});
+		if (checkout.type === "failed") {
+			return { type: "failed", branch, key, phase: "checkout", message: checkout.message };
+		}
+
+		phase = "new-session";
+		setRuntimeStatus(options.ctx, options.statusKey, "starting implementation session…");
+		parentSession = options.ctx.sessionManager?.getSessionFile?.();
+		const parentSessionPart = parentSession === undefined ? {} : { parentSession };
+		const newSessionOptions: BranchContextGtUpstackImplNewSessionOptions = {
+			withSession: async (newCtx) => {
+				isReplacementSessionActive = true;
+				await newCtx.sendUserMessage(formatImplBranchContextCommand(key));
+			},
+		};
+		if (parentSession !== undefined) {
+			newSessionOptions.parentSession = parentSession;
+		}
+
+		const result = await options.ctx.newSession(newSessionOptions);
+		if (result.cancelled) {
+			return { type: "cancelled", branch, key, ...parentSessionPart };
+		}
+
+		return { type: "launched", branch, key, ...parentSessionPart };
+	} catch (error) {
+		if (isReplacementSessionActive) {
+			throw error;
+		}
+		return {
+			type: "failed",
+			branch,
+			key,
+			phase,
+			message: error instanceof Error ? error.message : String(error),
+			...(parentSession === undefined ? {} : { parentSession }),
+		};
+	} finally {
+		if (!isReplacementSessionActive) {
+			setRuntimeStatus(options.ctx, options.statusKey, undefined);
+		}
+	}
+}
+
+export function formatBranchContextGtUpstackImplFollowUpFlow(
+	targetBranch: string,
+	key: string,
+): string {
+	return [`git checkout ${targetBranch}`, "/new", formatImplBranchContextCommand(key)].join("\n");
+}
+
+type CheckoutResult = { type: "ok" } | { type: "failed"; message: string };
+
+interface CheckoutBranchContextOptions {
+	host: BranchContextGtUpstackImplHost;
+	cwd: string;
+	targetBranch: string;
+	signal: AbortSignal | undefined;
+}
+
+async function checkoutBranchContext(
+	options: CheckoutBranchContextOptions,
+): Promise<CheckoutResult> {
+	const result = await options.host.exec("git", ["checkout", options.targetBranch], {
+		cwd: options.cwd,
+		timeout: CHECKOUT_TIMEOUT_MS,
+		...(options.signal === undefined ? {} : { signal: options.signal }),
+	});
+	if (result.code === 0) {
+		return { type: "ok" };
+	}
+
+	const output = formatCheckoutFailureOutput(result);
+	return {
+		type: "failed",
+		message: `git checkout ${options.targetBranch} failed with exit code ${result.code}: ${output}`,
+	};
+}
+
+function formatCheckoutFailureOutput(result: ExecResult): string {
+	if (result.stderr.length > 0) {
+		return result.stderr;
+	}
+	if (result.stdout.length > 0) {
+		return result.stdout;
+	}
+	return "(no output)";
+}

package/src/pi/host-types.ts

@@ -0,0 +1,135 @@
+import type { Component } from "@earendil-works/pi-tui";
+import type {
+	BranchContextContextFactory,
+	BranchCreationMethod,
+	createBranchContextFromFile,
+	loadBranchContextPlan,
+} from "@nseng-ai/branch-context/api";
+import type { ExecOptions, ExecResult } from "@nseng-ai/foundation/command";
+import type {
+	SessionReplacementContext,
+	SessionReplacementOptions,
+	SessionReplacementResult,
+} from "@nseng-ai/pi/sessions/replacement";
+import type { resolveSelectedSavedPlanFile, writeSavedPlanFile } from "@nseng-ai/plans/api";
+import type { SendMessageOptions } from "@nseng-ai/pi/shared/message-delivery";
+
+export type NotifyLevel = "info" | "warning" | "error";
+
+export interface TextContent {
+	type: "text";
+	text: string;
+}
+
+export type CustomMessageContent = string | TextContent[];
+
+export interface CustomMessage {
+	customType: string;
+	content: CustomMessageContent;
+	display: boolean;
+	details?: unknown;
+}
+
+export interface ToolResult {
+	content: TextContent[];
+	details?: unknown;
+}
+
+export type ToolUpdateHandler = (update: Partial<ToolResult>) => void;
+
+export type SessionHistoryEntry = unknown;
+
+export interface SessionManagerLike {
+	getBranch?(): SessionHistoryEntry[];
+	getEntries?(): SessionHistoryEntry[];
+	getSessionFile?(): string | undefined;
+}
+
+export type NewSessionResult = SessionReplacementResult;
+
+export interface ReplacedSessionContext extends CommandContext, SessionReplacementContext {
+	sendMessage(message: CustomMessage, options?: SendMessageOptions): Promise<void> | void;
+	sendUserMessage(content: string): Promise<void> | void;
+}
+
+export type NewSessionOptions = SessionReplacementOptions<
+	ReplacedSessionContext,
+	SessionManagerLike
+>;
+
+export interface BranchContextOperations {
+	loadBranchContextPlan: typeof loadBranchContextPlan;
+	createBranchContextFromFile: typeof createBranchContextFromFile;
+	writeSavedPlanFile: typeof writeSavedPlanFile;
+	resolveSelectedSavedPlanFile: typeof resolveSelectedSavedPlanFile;
+}
+
+export interface BranchContextExtensionOptions {
+	branchContextDefaultCreation?: BranchCreationMethod;
+	branchContextPrefix?: string;
+	planStoreRoot?: string;
+	branchContextOperations?: BranchContextOperations;
+	createBranchContextContext?: BranchContextContextFactory<[pi: ExtensionAPI, cwd: string]>;
+}
+
+export interface ToolContext {
+	cwd: string;
+	hasUI?: boolean;
+	ui?: {
+		setStatus?(key: string, value: string | undefined): void;
+	};
+}
+
+export interface ToolRenderResultOptions {
+	isPartial: boolean;
+}
+
+export interface ToolDefinition {
+	name: string;
+	label?: string;
+	description: string;
+	promptSnippet?: string;
+	promptGuidelines?: string[];
+	parameters: Record<string, unknown>;
+	execute(
+		toolCallId: string,
+		params: unknown,
+		signal: AbortSignal | undefined,
+		onUpdate: ToolUpdateHandler | undefined,
+		ctx: ToolContext,
+	): Promise<ToolResult> | ToolResult;
+	renderCall?(args: unknown, theme: unknown, context: unknown): Component;
+	renderResult?(
+		result: ToolResult,
+		options: ToolRenderResultOptions,
+		theme: unknown,
+		context: unknown,
+	): Component;
+}
+
+export interface CommandContext {
+	cwd: string;
+	hasUI: boolean;
+	ui: {
+		notify(message: string, level?: NotifyLevel): void;
+		setStatus(key: string, value: string | undefined): void;
+		confirm?(title: string, message?: string): Promise<boolean>;
+	};
+	waitForIdle(): Promise<void>;
+	newSession(options?: NewSessionOptions): Promise<NewSessionResult>;
+	sessionManager?: SessionManagerLike;
+}
+
+export interface ExtensionAPI {
+	registerCommand(
+		name: string,
+		options: {
+			description?: string;
+			handler(args: string, ctx: CommandContext): Promise<void> | void;
+		},
+	): void;
+	registerTool(definition: ToolDefinition): void;
+	exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+	sendMessage?(message: CustomMessage, options?: SendMessageOptions): void;
+	sendUserMessage(content: string): void;
+}

package/src/pi/index.ts

@@ -0,0 +1,16 @@
+export {
+	CREATE_BRANCH_CONTEXT_COMMAND_NAME,
+	GT_UPSTACK_IMPL_COMMAND_NAME,
+	WRITE_GRILLED_PLAN_COMMAND_NAME,
+	WRITE_PLAN_COMMAND_NAME,
+	branchContextExtensionParity,
+	default,
+} from "./extension.ts";
+export {
+	BRANCH_CONTEXT_FROM_PLAN_COMMAND_NAME,
+	BRANCH_CONTEXT_UPSTACK_IMPL_FROM_PLAN_COMMAND_NAME,
+	IMPL_BRANCH_CONTEXT_COMMAND_NAME,
+	IMPL_CURRENT_SAVED_PLAN_COMMAND_NAME,
+	formatImplBranchContextCommand,
+} from "./surfaces.ts";
+export type { BranchContextExtensionOptions, ExtensionAPI } from "./extension.ts";

package/src/pi/options.ts

@@ -0,0 +1,32 @@
+import {
+	createBranchContextFromFile,
+	loadBranchContextPlan,
+	type BranchCreationMethod,
+} from "@nseng-ai/branch-context/api";
+import { resolveSelectedSavedPlanFile, writeSavedPlanFile } from "@nseng-ai/plans/api";
+import type { BranchContextExtensionOptions, BranchContextOperations } from "./host-types.ts";
+
+const realBranchContextOperations: BranchContextOperations = {
+	loadBranchContextPlan,
+	createBranchContextFromFile,
+	writeSavedPlanFile,
+	resolveSelectedSavedPlanFile,
+};
+
+export function resolveBranchContextOperations(
+	options: BranchContextExtensionOptions,
+): BranchContextOperations {
+	return options.branchContextOperations ?? realBranchContextOperations;
+}
+
+export function resolveBranchContextDefaultCreation(
+	options: BranchContextExtensionOptions,
+): BranchCreationMethod {
+	return options.branchContextDefaultCreation ?? "plain-git";
+}
+
+export function resolvePlanStoreRootOption(
+	options: BranchContextExtensionOptions,
+): string | undefined {
+	return options.planStoreRoot;
+}

package/src/pi/surfaces.ts

@@ -0,0 +1,11 @@
+export const BRANCH_CONTEXT_FROM_PLAN_COMMAND_NAME = "ns:branch-context:from-plan";
+export const BRANCH_CONTEXT_UPSTACK_IMPL_FROM_PLAN_COMMAND_NAME =
+	"ns:branch-context:upstack-impl-from-plan";
+export const IMPL_BRANCH_CONTEXT_COMMAND_NAME = "ns:branch-context:impl-attached-plan";
+export const WRITE_PLAN_COMMAND_NAME = "ns:plan:save";
+export const WRITE_GRILLED_PLAN_COMMAND_NAME = "ns:plan:grill-and-save";
+export const IMPL_CURRENT_SAVED_PLAN_COMMAND_NAME = "ns:plan:impl-current";
+
+export function formatImplBranchContextCommand(key: string): string {
+	return `/${IMPL_BRANCH_CONTEXT_COMMAND_NAME} ${key}`;
+}

package/src/testing/index.ts

@@ -0,0 +1,258 @@
+import {
+	FakeBrmemGateway,
+	type BrmemGateway,
+	type BrmemOptionalResult,
+	type BrmemResult,
+	type CopyEntriesResult,
+	type DeleteEntryResult,
+	type EntryContent,
+	type EntryDiagnostic,
+	type FakeBrmemGatewayOptions,
+	type FakeEntrySeed,
+	type GitRemoteConfig,
+	type ListedEntry,
+	type ListedSnapshot,
+	type PutEntryResult,
+} from "@nseng-ai/brmem";
+
+import { BRANCH_CONTEXT_NAMESPACE } from "../core/constants.ts";
+
+export interface InMemoryAttachedPlanState {
+	branch: string;
+	key: string;
+	content?: string;
+	refName?: string;
+	commit?: string;
+	sourceFile?: string;
+}
+
+export interface InMemoryBrmemGatewayState {
+	currentBranch?: FakeBrmemGatewayOptions["currentBranch"];
+	entries?: readonly InMemoryAttachedPlanState[];
+	presenceFailure?: { code: string; message: string };
+	attachFailure?: { code: string; message: string };
+	listFailure?: { code: string; message: string };
+	getFailure?: { code: string; message: string };
+	deleteFailure?: { code: string; message: string };
+}
+
+export interface BrmemAttachmentCall {
+	branch: string;
+	key: string;
+}
+
+export interface BrmemListCall {
+	branch?: string;
+}
+
+export interface BrmemPutCall {
+	namespace: string;
+	branch: string;
+	key: string;
+	content: string;
+}
+
+interface StoredAttachedPlan {
+	branch: string;
+	key: string;
+	content: string;
+	refName: string;
+	commit: string;
+	sourceFile: string;
+}
+
+export class InMemoryBranchMemoryGateway implements BrmemGateway {
+	private readonly fake: FakeBrmemGateway;
+	private readonly entries = new Map<string, StoredAttachedPlan>();
+	readonly checkEntryCalls: BrmemAttachmentCall[] = [];
+	readonly putEntryCalls: BrmemPutCall[] = [];
+	readonly listEntriesCalls: BrmemListCall[] = [];
+	readonly getEntryCalls: BrmemAttachmentCall[] = [];
+	readonly deleteEntryCalls: BrmemAttachmentCall[] = [];
+
+	constructor(state: InMemoryBrmemGatewayState = {}) {
+		for (const entry of state.entries ?? [])
+			this.entries.set(entryKey(entry.branch, entry.key), normalizeEntry(entry));
+		this.fake = new FakeBrmemGateway({
+			...(state.currentBranch === undefined ? {} : { currentBranch: state.currentBranch }),
+			entries: (state.entries ?? []).map(toFakeEntry),
+			operationErrors: {
+				...(state.presenceFailure === undefined ? {} : { check: state.presenceFailure }),
+				...(state.attachFailure === undefined ? {} : { put: state.attachFailure }),
+				...(state.listFailure === undefined ? {} : { list: state.listFailure }),
+				...(state.getFailure === undefined ? {} : { get: state.getFailure }),
+				...(state.deleteFailure === undefined ? {} : { delete: state.deleteFailure }),
+			},
+		});
+	}
+
+	get attachmentPresenceCalls(): readonly BrmemAttachmentCall[] {
+		return this.checkEntryCalls.map((call) => ({ ...call }));
+	}
+
+	get attachPlanCalls(): readonly BrmemPutCall[] {
+		return this.putEntryCalls.map((call) => ({ ...call }));
+	}
+
+	get listAttachedPlansCalls(): readonly BrmemListCall[] {
+		return this.listEntriesCalls.map((call) => ({ ...call }));
+	}
+
+	get getAttachedPlanCalls(): readonly BrmemAttachmentCall[] {
+		return this.getEntryCalls.map((call) => ({ ...call }));
+	}
+
+	get attachedPlans(): readonly InMemoryAttachedPlanState[] {
+		return [...this.entries.values()].map((entry) => ({ ...entry }));
+	}
+
+	async currentBranch(): Promise<BrmemResult<string>> {
+		return await this.fake.currentBranch();
+	}
+
+	async listEntries(options: {
+		namespace: string;
+		key?: string;
+		branch?: string;
+	}): Promise<BrmemResult<readonly ListedEntry[]>> {
+		this.listEntriesCalls.push(options.branch === undefined ? {} : { branch: options.branch });
+		return await this.fake.listEntries(options);
+	}
+
+	async listAllEntries(options: {
+		key?: string;
+		branch?: string;
+	}): Promise<BrmemResult<readonly ListedEntry[]>> {
+		return await this.fake.listAllEntries(options);
+	}
+
+	async getEntry(options: {
+		namespace: string;
+		key: string;
+		branch: string;
+		at?: string;
+	}): Promise<BrmemOptionalResult<EntryContent>> {
+		this.getEntryCalls.push({ branch: options.branch, key: options.key });
+		return await this.fake.getEntry(options);
+	}
+
+	async checkEntry(options: {
+		namespace: string;
+		key: string;
+		branch: string;
+		at?: string;
+	}): Promise<BrmemOptionalResult<EntryDiagnostic>> {
+		this.checkEntryCalls.push({ branch: options.branch, key: options.key });
+		return await this.fake.checkEntry(options);
+	}
+
+	async putEntry(options: BrmemPutCall): Promise<BrmemResult<PutEntryResult>> {
+		this.putEntryCalls.push({ ...options });
+		const result = await this.fake.putEntry(options);
+		this.recordEntryWriteResult(options, result);
+		return result;
+	}
+
+	async createEntry(options: BrmemPutCall): Promise<BrmemResult<PutEntryResult>> {
+		this.putEntryCalls.push({ ...options });
+		const result = await this.fake.createEntry(options);
+		this.recordEntryWriteResult(options, result);
+		return result;
+	}
+
+	private recordEntryWriteResult(options: BrmemPutCall, result: BrmemResult<PutEntryResult>): void {
+		if (result.type !== "ok" || options.namespace !== BRANCH_CONTEXT_NAMESPACE) return;
+		this.entries.set(entryKey(options.branch, options.key), {
+			branch: options.branch,
+			key: options.key,
+			content: options.content,
+			refName: result.value.entry.entryLocator,
+			commit: result.value.commitSha,
+			sourceFile: "",
+		});
+	}
+
+	async deleteEntry(options: {
+		namespace: string;
+		key: string;
+		branch: string;
+	}): Promise<BrmemResult<DeleteEntryResult>> {
+		this.deleteEntryCalls.push({ branch: options.branch, key: options.key });
+		const result = await this.fake.deleteEntry(options);
+		if (result.type === "ok" && options.namespace === BRANCH_CONTEXT_NAMESPACE) {
+			this.entries.delete(entryKey(options.branch, options.key));
+		}
+		return result;
+	}
+
+	async copyEntries(options: {
+		namespace: string;
+		fromBranch: string;
+		toBranch: string;
+		shouldOverwrite: boolean;
+		keyGlob?: string;
+	}): Promise<BrmemResult<CopyEntriesResult>> {
+		return await this.fake.copyEntries(options);
+	}
+
+	async listSnapshots(options: {
+		namespace?: string;
+	}): Promise<BrmemResult<readonly ListedSnapshot[]>> {
+		return await this.fake.listSnapshots(options);
+	}
+
+	async listLocalBranches(): Promise<BrmemResult<ReadonlySet<string>>> {
+		return await this.fake.listLocalBranches();
+	}
+
+	async localBranchPresence(options: {
+		branch: string;
+	}): Promise<BrmemResult<"present" | "absent">> {
+		return await this.fake.localBranchPresence(options);
+	}
+
+	async deleteSnapshot(options: { namespace: string; branch: string }): Promise<BrmemResult<void>> {
+		return await this.fake.deleteSnapshot(options);
+	}
+
+	async getRemoteConfig(remote: string): Promise<BrmemOptionalResult<GitRemoteConfig>> {
+		return await this.fake.getRemoteConfig(remote);
+	}
+
+	async addRemoteRefspecs(
+		remote: string,
+		push: readonly string[],
+		fetch: readonly string[],
+	): Promise<BrmemResult<void>> {
+		return await this.fake.addRemoteRefspecs(remote, push, fetch);
+	}
+}
+
+function toFakeEntry(entry: InMemoryAttachedPlanState): FakeEntrySeed {
+	return {
+		namespace: BRANCH_CONTEXT_NAMESPACE,
+		branch: entry.branch,
+		key: entry.key,
+		content: entry.content ?? "",
+		...(entry.commit === undefined ? {} : { headSha: entry.commit }),
+	};
+}
+
+function normalizeEntry(entry: InMemoryAttachedPlanState): StoredAttachedPlan {
+	return {
+		branch: entry.branch,
+		key: entry.key,
+		content: entry.content ?? "",
+		refName: entry.refName ?? defaultRefName(entry.branch, entry.key),
+		commit: entry.commit ?? "abc123",
+		sourceFile: entry.sourceFile ?? `/tmp/${entry.key}`,
+	};
+}
+
+function defaultRefName(branch: string, key: string): string {
+	return `refs/brmem/ns/${BRANCH_CONTEXT_NAMESPACE}/${branch.replaceAll("/", "---")}:${key}`;
+}
+
+function entryKey(branch: string, key: string): string {
+	return `${branch}\0${key}`;
+}