@nseng-ai/branch-context 0.1.1

package/src/core/session-artifact.ts

@@ -0,0 +1,114 @@
+import { z } from "zod";
+
+import { isRecord } from "@nseng-ai/foundation/primitives";
+
+import { BRANCH_CREATION_METHODS, type BranchContextEvidence } from "./branch-context-creation.ts";
+import { BRANCH_CONTEXT_NAMESPACE } from "./constants.ts";
+
+export const BRANCH_CONTEXT_OUTPUT_MESSAGE_TYPE = "branch-context-output";
+
+export type BranchContextOutputDetails =
+	| { status: "usage" }
+	| { status: "dry-run"; targetBranch: string; key: string }
+	| { status: "success"; evidence: BranchContextEvidence }
+	| { status: "loaded-plan" }
+	| { status: "reuse" }
+	| { status: "failure"; error: string }
+	| { status: "cancelled" };
+
+export interface BranchContextOutputMessage {
+	customType: typeof BRANCH_CONTEXT_OUTPUT_MESSAGE_TYPE;
+	content: string;
+	display: true;
+	details: BranchContextOutputDetails;
+}
+
+const nonEmptyEvidenceStringSchema = z.string().min(1);
+
+const branchContextEvidenceSchema = z.object({
+	slug: nonEmptyEvidenceStringSchema,
+	branch: nonEmptyEvidenceStringSchema,
+	branchCreation: z.enum(BRANCH_CREATION_METHODS),
+	startPoint: nonEmptyEvidenceStringSchema,
+	namespace: nonEmptyEvidenceStringSchema,
+	key: nonEmptyEvidenceStringSchema,
+	refName: nonEmptyEvidenceStringSchema,
+	commit: nonEmptyEvidenceStringSchema,
+	sourceFile: nonEmptyEvidenceStringSchema,
+	summary: z.string().optional(),
+});
+
+const successfulBranchContextOutputDetailsSchema = z.object({
+	status: z.literal("success"),
+	evidence: branchContextEvidenceSchema,
+});
+
+export function buildBranchContextOutputMessage(
+	content: string,
+	details: BranchContextOutputDetails,
+): BranchContextOutputMessage {
+	return {
+		customType: BRANCH_CONTEXT_OUTPUT_MESSAGE_TYPE,
+		content,
+		display: true,
+		details,
+	};
+}
+
+export function extractBranchContextEvidence(details: unknown): BranchContextEvidence | undefined {
+	const result = successfulBranchContextOutputDetailsSchema.safeParse(details);
+	if (!result.success) {
+		return undefined;
+	}
+
+	return toBranchContextEvidence(result.data.evidence);
+}
+
+function toBranchContextEvidence(
+	data: z.infer<typeof branchContextEvidenceSchema>,
+): BranchContextEvidence {
+	const { summary, ...evidence } = data;
+	return { ...evidence, ...(summary === undefined ? {} : { summary }) };
+}
+
+export function extractBranchContextEvidenceFromSessionEntry(
+	entry: unknown,
+): BranchContextEvidence | undefined {
+	const message = extractMessageFromEntry(entry);
+	if (
+		message === undefined ||
+		customTypeFromMessage(message) !== BRANCH_CONTEXT_OUTPUT_MESSAGE_TYPE
+	) {
+		return undefined;
+	}
+	return extractBranchContextEvidence(message.details);
+}
+
+export function findLatestBranchContextEvidence(
+	entries: readonly unknown[],
+): BranchContextEvidence | undefined {
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		const evidence = extractBranchContextEvidenceFromSessionEntry(entries[index]);
+		if (evidence !== undefined && evidence.namespace === BRANCH_CONTEXT_NAMESPACE) {
+			return evidence;
+		}
+	}
+	return undefined;
+}
+
+function extractMessageFromEntry(entry: unknown): Record<string, unknown> | undefined {
+	if (!isRecord(entry)) {
+		return undefined;
+	}
+	if (isRecord(entry.message)) {
+		return entry.message;
+	}
+	if (typeof entry.customType === "string" || entry.content !== undefined) {
+		return entry;
+	}
+	return undefined;
+}
+
+function customTypeFromMessage(message: Record<string, unknown>): string | undefined {
+	return typeof message.customType === "string" ? message.customType : undefined;
+}

package/src/ns/command.ts

@@ -0,0 +1,33 @@
+import {
+	createNsDomainCommand,
+	type NsDomainCommandOptions,
+} from "@nseng-ai/capability-kit/ns-command";
+import { optionalEntry } from "@nseng-ai/foundation/primitives";
+import type { NsCommand, NsCommandSchema, NsExtensionApi } from "@nseng-ai/ns/kernel/sdk";
+
+import {
+	createRealBranchContextCliContext,
+	type BranchContextCliContext,
+} from "../core/operations.ts";
+
+type BranchContextNsCommandOptions<S extends NsCommandSchema, T> = Omit<
+	NsDomainCommandOptions<S, T, BranchContextCliContext>,
+	"createContext"
+>;
+
+export function branchContextCommand<S extends NsCommandSchema, T>(
+	options: BranchContextNsCommandOptions<S, T>,
+): NsCommand<S, T> {
+	return createNsDomainCommand({
+		...options,
+		createContext: createBranchContextExtensionContext,
+	});
+}
+
+function createBranchContextExtensionContext(ctx: NsExtensionApi): BranchContextCliContext {
+	return createRealBranchContextCliContext({
+		cwd: ctx.cwd,
+		env: ctx.env,
+		...optionalEntry("stderr", ctx.stderr),
+	});
+}

package/src/ns/commands/attach.ts

@@ -0,0 +1,19 @@
+import { defineExtension } from "@nseng-ai/ns/kernel/sdk";
+
+import { branchContextCommand } from "../command.ts";
+import { attachRequestSchema, attachResultSchema, handleAttach } from "../../core/operations.ts";
+
+export const branchContextAttachNsCommand = branchContextCommand({
+	name: "attach",
+	summary: "Attach a saved plan or file as branch context.",
+	description:
+		"Attach a saved plan or arbitrary file to the current or selected branch context namespace.",
+	schema: attachRequestSchema,
+	resultSchema: attachResultSchema,
+	positionals: { key: { position: 0 } },
+	handler: handleAttach,
+});
+
+export default defineExtension({
+	commands: [branchContextAttachNsCommand],
+});

package/src/ns/commands/check.ts

@@ -0,0 +1,18 @@
+import { defineExtension } from "@nseng-ai/ns/kernel/sdk";
+
+import { branchContextCommand } from "../command.ts";
+import { checkResultSchema, handleCheck, keyRequestSchema } from "../../core/operations.ts";
+
+export const branchContextCheckNsCommand = branchContextCommand({
+	name: "check",
+	summary: "Check a branch-context entry.",
+	description: "Check whether a branch-context entry exists on the current or selected branch.",
+	schema: keyRequestSchema,
+	resultSchema: checkResultSchema,
+	positionals: { key: { position: 0 } },
+	handler: handleCheck,
+});
+
+export default defineExtension({
+	commands: [branchContextCheckNsCommand],
+});

package/src/ns/commands/delete.ts

@@ -0,0 +1,18 @@
+import { defineExtension } from "@nseng-ai/ns/kernel/sdk";
+
+import { branchContextCommand } from "../command.ts";
+import { deleteResultSchema, handleDelete, keyRequestSchema } from "../../core/operations.ts";
+
+export const branchContextDeleteNsCommand = branchContextCommand({
+	name: "delete",
+	summary: "Delete a branch-context entry.",
+	description: "Delete a branch-context entry from the current or selected branch.",
+	schema: keyRequestSchema,
+	resultSchema: deleteResultSchema,
+	positionals: { key: { position: 0 } },
+	handler: handleDelete,
+});
+
+export default defineExtension({
+	commands: [branchContextDeleteNsCommand],
+});

package/src/ns/commands/from-plan.ts

@@ -0,0 +1,21 @@
+import { defineExtension } from "@nseng-ai/ns/kernel/sdk";
+
+import { branchContextCommand } from "../command.ts";
+import {
+	branchContextResultSchema,
+	createRequestSchema,
+	handleCreate,
+} from "../../core/operations.ts";
+
+export const branchContextFromPlanNsCommand = branchContextCommand({
+	name: "from-plan",
+	summary: "Create branch context from a saved plan.",
+	description: "Create a branch context entry from a saved plan file for agent implementation.",
+	schema: createRequestSchema,
+	resultSchema: branchContextResultSchema,
+	handler: handleCreate,
+});
+
+export default defineExtension({
+	commands: [branchContextFromPlanNsCommand],
+});

package/src/ns/commands/list.ts

@@ -0,0 +1,17 @@
+import { defineExtension } from "@nseng-ai/ns/kernel/sdk";
+
+import { branchContextCommand } from "../command.ts";
+import { handleList, listRequestSchema, listResultSchema } from "../../core/operations.ts";
+
+export const branchContextListNsCommand = branchContextCommand({
+	name: "list",
+	summary: "List branch-context entries.",
+	description: "List branch-context entries attached to the current or selected branch.",
+	schema: listRequestSchema,
+	resultSchema: listResultSchema,
+	handler: handleList,
+});
+
+export default defineExtension({
+	commands: [branchContextListNsCommand],
+});

package/src/ns/commands/load.ts

@@ -0,0 +1,19 @@
+import { defineExtension } from "@nseng-ai/ns/kernel/sdk";
+
+import { branchContextCommand } from "../command.ts";
+import { handleLoad, loadPlanResultSchema, loadRequestSchema } from "../../core/operations.ts";
+
+export const branchContextLoadNsCommand = branchContextCommand({
+	name: "load",
+	summary: "Load an attached branch-context plan.",
+	description:
+		"Load a branch-context entry and render the implementation prompt for agent invocation.",
+	schema: loadRequestSchema,
+	resultSchema: loadPlanResultSchema,
+	positionals: { key: { position: 0 } },
+	handler: handleLoad,
+});
+
+export default defineExtension({
+	commands: [branchContextLoadNsCommand],
+});

package/src/ns/repo-local-ns-extension.ts

@@ -0,0 +1,32 @@
+import {
+	defineRepoLocalNsExtensionDescriptor,
+	repoLocalNsCommandDescriptor,
+} from "@nseng-ai/ns/kernel/sdk";
+
+import { branchContextAttachNsCommand } from "./commands/attach.ts";
+import { branchContextCheckNsCommand } from "./commands/check.ts";
+import { branchContextDeleteNsCommand } from "./commands/delete.ts";
+import { branchContextFromPlanNsCommand } from "./commands/from-plan.ts";
+import { branchContextListNsCommand } from "./commands/list.ts";
+import { branchContextLoadNsCommand } from "./commands/load.ts";
+
+const BRANCH_CONTEXT_COMMANDS = [
+	branchContextFromPlanNsCommand,
+	branchContextLoadNsCommand,
+	branchContextAttachNsCommand,
+	branchContextListNsCommand,
+	branchContextCheckNsCommand,
+	branchContextDeleteNsCommand,
+] as const;
+
+export const branchContextRepoLocalNsExtension = defineRepoLocalNsExtensionDescriptor({
+	group: "branch-context",
+	description: "Create and load branch-scoped implementation context.",
+	commands: BRANCH_CONTEXT_COMMANDS.map((command) =>
+		repoLocalNsCommandDescriptor({
+			command,
+			manifestPath: ["exec", command.name],
+			packageExportPrefix: "@nseng-ai/branch-context/ns/commands",
+		}),
+	),
+});