@f5-sales-demo/xcsh 19.51.2

package/src/commit/agentic/fallback.ts

@@ -0,0 +1,96 @@
+import * as path from "node:path";
+import type { CommitType, ConventionalAnalysis, NumstatEntry } from "../../commit/types";
+import type { CommitProposal } from "./state";
+
+const TEST_PATTERNS = ["/test/", "/tests/", "/__tests__/", "_test.", ".test.", ".spec.", "_spec."];
+const DOC_EXTENSIONS = new Set([".md", ".txt", ".rst", ".adoc"]);
+const CONFIG_EXTENSIONS = new Set([".json", ".yaml", ".yml", ".toml", ".xml", ".ini", ".cfg"]);
+const STYLE_EXTENSIONS = new Set([".css", ".scss", ".less", ".sass"]);
+
+function inferTypeFromFiles(numstat: NumstatEntry[]): CommitType {
+	if (numstat.length === 0) return "chore";
+
+	let hasTests = false;
+	let hasDocs = false;
+	let hasConfig = false;
+	let hasStyle = false;
+	let hasSource = false;
+
+	for (const entry of numstat) {
+		const lowerPath = entry.path.toLowerCase();
+		const ext = getExtension(entry.path);
+
+		if (TEST_PATTERNS.some(pattern => lowerPath.includes(pattern))) {
+			hasTests = true;
+		} else if (DOC_EXTENSIONS.has(ext)) {
+			hasDocs = true;
+		} else if (CONFIG_EXTENSIONS.has(ext)) {
+			hasConfig = true;
+		} else if (STYLE_EXTENSIONS.has(ext)) {
+			hasStyle = true;
+		} else {
+			hasSource = true;
+		}
+	}
+
+	if (hasTests && !hasSource && !hasDocs) return "test";
+	if (hasDocs && !hasSource && !hasTests) return "docs";
+	if (hasStyle && !hasSource && !hasTests) return "style";
+	if (hasConfig && !hasSource && !hasTests && !hasDocs) return "chore";
+	return "refactor";
+}
+
+function getExtension(filePath: string): string {
+	const name = path.basename(filePath);
+	const dotIndex = name.lastIndexOf(".");
+	return dotIndex >= 0 ? name.slice(dotIndex).toLowerCase() : "";
+}
+
+export function generateFallbackAnalysis(numstat: NumstatEntry[]): ConventionalAnalysis {
+	const type = inferTypeFromFiles(numstat);
+	const details = numstat.slice(0, 3).map(e => ({
+		text: `Updated ${path.basename(e.path)}`,
+		userVisible: false,
+	}));
+
+	return {
+		type,
+		scope: null,
+		details,
+		issueRefs: [],
+	};
+}
+
+export function generateFallbackSummary(type: CommitType, numstat: NumstatEntry[]): string {
+	const verbMap: Record<string, string> = {
+		test: "updated tests for",
+		docs: "updated documentation for",
+		refactor: "refactored",
+		style: "formatted",
+		chore: "updated",
+		feat: "updated",
+		fix: "updated",
+		perf: "updated",
+		build: "updated",
+		ci: "updated",
+		revert: "reverted changes in",
+	};
+	const verb = verbMap[type] ?? "updated";
+	const file = path.basename(numstat[0]?.path ?? "files");
+
+	if (numstat.length === 1) {
+		return `${verb} ${file}`;
+	}
+	return `${verb} ${file} and ${numstat.length - 1} other${numstat.length === 2 ? "" : "s"}`;
+}
+
+export function generateFallbackProposal(numstat: NumstatEntry[]): CommitProposal {
+	const analysis = generateFallbackAnalysis(numstat);
+	const summary = generateFallbackSummary(analysis.type, numstat);
+
+	return {
+		analysis,
+		summary,
+		warnings: ["Commit generated using fallback due to agent failure"],
+	};
+}

package/src/commit/agentic/index.ts

@@ -0,0 +1,354 @@
+import * as path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { $env, getProjectDir, isEnoent, prompt } from "@f5xc-salesdemos/pi-utils";
+import { applyChangelogProposals } from "../../commit/changelog";
+import { detectChangelogBoundaries } from "../../commit/changelog/detect";
+import { parseUnreleasedSection } from "../../commit/changelog/parse";
+import { formatCommitMessage } from "../../commit/message";
+import { resolvePrimaryModel, resolveSmolModel } from "../../commit/model-selection";
+import type { CommitCommandArgs, ConventionalAnalysis } from "../../commit/types";
+import { ModelRegistry } from "../../config/model-registry";
+import { Settings } from "../../config/settings";
+import { discoverAuthStorage, discoverContextFiles } from "../../sdk";
+import * as git from "../../utils/git";
+import { type ExistingChangelogEntries, runCommitAgentSession } from "./agent";
+import { generateFallbackProposal } from "./fallback";
+import splitConfirmPrompt from "./prompts/split-confirm.md" with { type: "text" };
+import type { CommitAgentState, CommitProposal, HunkSelector, SplitCommitPlan } from "./state";
+import { computeDependencyOrder } from "./topo-sort";
+import { detectTrivialChange } from "./trivial";
+
+interface CommitExecutionContext {
+	cwd: string;
+	dryRun: boolean;
+	push: boolean;
+}
+
+export async function runAgenticCommit(args: CommitCommandArgs): Promise<void> {
+	const cwd = getProjectDir();
+	const [settings, authStorage] = await Promise.all([Settings.init({ cwd }), discoverAuthStorage()]);
+
+	process.stdout.write("● Resolving model...\n");
+	const modelRegistry = new ModelRegistry(authStorage);
+	await modelRegistry.refresh();
+	const stagedFilesPromise = (async () => {
+		let stagedFiles = await git.diff.changedFiles(cwd, { cached: true });
+		if (stagedFiles.length === 0) {
+			process.stdout.write("No staged changes detected, staging all changes...\n");
+			await git.stage.files(cwd);
+			stagedFiles = await git.diff.changedFiles(cwd, { cached: true });
+		}
+		return stagedFiles;
+	})();
+
+	const primaryModelPromise = resolvePrimaryModel(args.model, settings, modelRegistry);
+	const [primaryModelResult, stagedFiles] = await Promise.all([primaryModelPromise, stagedFilesPromise]);
+	const { model: primaryModel, apiKey: primaryApiKey } = primaryModelResult;
+	process.stdout.write(`  └─ ${primaryModel.name}\n`);
+
+	const { model: agentModel, thinkingLevel: agentThinkingLevel } = await resolveSmolModel(
+		settings,
+		modelRegistry,
+		primaryModel,
+		primaryApiKey,
+	);
+
+	if (stagedFiles.length === 0) {
+		process.stderr.write("No changes to commit.\n");
+		return;
+	}
+
+	if (!args.noChangelog) {
+		process.stdout.write("● Detecting changelog targets...\n");
+	}
+	const [changelogBoundaries, contextFiles, numstat, diff] = await Promise.all([
+		args.noChangelog ? [] : detectChangelogBoundaries(cwd, stagedFiles),
+		discoverContextFiles(cwd),
+		git.diff.numstat(cwd, { cached: true }),
+		git.diff(cwd, { cached: true }),
+	]);
+	const changelogTargets = changelogBoundaries.map(boundary => boundary.changelogPath);
+	if (!args.noChangelog) {
+		if (changelogTargets.length > 0) {
+			for (const path of changelogTargets) {
+				process.stdout.write(`  └─ ${path}\n`);
+			}
+		} else {
+			process.stdout.write("  └─ (none found)\n");
+		}
+	}
+
+	process.stdout.write("● Discovering context files...\n");
+	const agentsMdFiles = contextFiles.filter(file => file.path.endsWith("XCSH.md"));
+	if (agentsMdFiles.length > 0) {
+		for (const file of agentsMdFiles) {
+			process.stdout.write(`  └─ ${file.path}\n`);
+		}
+	} else {
+		process.stdout.write("  └─ (none found)\n");
+	}
+	const forceFallback = $env.PI_COMMIT_TEST_FALLBACK?.toLowerCase() === "true";
+	if (forceFallback) {
+		process.stdout.write("● Forcing fallback commit generation...\n");
+		const fallbackProposal = generateFallbackProposal(numstat);
+		await runSingleCommit(fallbackProposal, { cwd, dryRun: args.dryRun, push: args.push });
+		return;
+	}
+
+	const trivialChange = detectTrivialChange(diff);
+	if (trivialChange) {
+		process.stdout.write(`● Detected trivial change: ${trivialChange.summary}\n`);
+		const trivialProposal: CommitProposal = {
+			analysis: {
+				type: trivialChange.type,
+				scope: null,
+				details: [],
+				issueRefs: [],
+			},
+			summary: trivialChange.summary,
+			warnings: [],
+		};
+		await runSingleCommit(trivialProposal, { cwd, dryRun: args.dryRun, push: args.push });
+		return;
+	}
+
+	let existingChangelogEntries: ExistingChangelogEntries[] | undefined;
+	if (!args.noChangelog && changelogTargets.length > 0) {
+		existingChangelogEntries = await loadExistingChangelogEntries(changelogTargets);
+		if (existingChangelogEntries.length === 0) {
+			existingChangelogEntries = undefined;
+		}
+	}
+
+	process.stdout.write("● Starting commit agent...\n");
+	let commitState: CommitAgentState;
+	let usedFallback = false;
+
+	try {
+		commitState = await runCommitAgentSession({
+			cwd,
+			model: agentModel,
+			thinkingLevel: agentThinkingLevel,
+			settings,
+			modelRegistry,
+			authStorage,
+			userContext: args.context,
+			contextFiles,
+			changelogTargets,
+			requireChangelog: !args.noChangelog && changelogTargets.length > 0,
+			diffText: diff,
+			existingChangelogEntries,
+		});
+	} catch (error) {
+		const errorMessage = error instanceof Error ? error.message : String(error);
+		process.stderr.write(`Agent error: ${errorMessage}\n`);
+		if (error instanceof Error && error.stack && $env.DEBUG) {
+			process.stderr.write(`${error.stack}\n`);
+		}
+		process.stdout.write("● Using fallback commit generation...\n");
+		commitState = { proposal: generateFallbackProposal(numstat) };
+		usedFallback = true;
+	}
+
+	if (!usedFallback && !commitState.proposal && !commitState.splitProposal) {
+		if ($env.PI_COMMIT_NO_FALLBACK?.toLowerCase() !== "true") {
+			process.stdout.write("● Agent did not provide proposal, using fallback...\n");
+			commitState.proposal = generateFallbackProposal(numstat);
+			usedFallback = true;
+		}
+	}
+
+	let updatedChangelogFiles: string[] = [];
+	if (!args.noChangelog && changelogTargets.length > 0 && !usedFallback) {
+		if (!commitState.changelogProposal) {
+			process.stderr.write("Commit agent did not provide changelog entries.\n");
+			return;
+		}
+		process.stdout.write("● Applying changelog entries...\n");
+		const updated = await applyChangelogProposals({
+			cwd,
+			proposals: commitState.changelogProposal.entries,
+			dryRun: args.dryRun,
+			onProgress: message => {
+				process.stdout.write(`  ├─ ${message}\n`);
+			},
+		});
+		updatedChangelogFiles = updated.map(filePath => path.relative(cwd, filePath));
+		if (updated.length > 0) {
+			for (const filePath of updated) {
+				process.stdout.write(`  └─ ${filePath}\n`);
+			}
+		} else {
+			process.stdout.write("  └─ (no changes)\n");
+		}
+	}
+
+	if (commitState.proposal) {
+		await runSingleCommit(commitState.proposal, { cwd, dryRun: args.dryRun, push: args.push });
+		return;
+	}
+
+	if (commitState.splitProposal) {
+		await runSplitCommit(commitState.splitProposal, {
+			cwd,
+			dryRun: args.dryRun,
+			push: args.push,
+			additionalFiles: updatedChangelogFiles,
+		});
+		return;
+	}
+
+	process.stderr.write("Commit agent did not provide a proposal.\n");
+}
+
+async function runSingleCommit(proposal: CommitProposal, ctx: CommitExecutionContext): Promise<void> {
+	if (proposal.warnings.length > 0) {
+		process.stdout.write(formatWarnings(proposal.warnings));
+	}
+	const commitMessage = formatCommitMessage(proposal.analysis, proposal.summary);
+	if (ctx.dryRun) {
+		process.stdout.write("\nGenerated commit message:\n");
+		process.stdout.write(`${commitMessage}\n`);
+		return;
+	}
+	await git.commit(ctx.cwd, commitMessage);
+	process.stdout.write("Commit created.\n");
+	if (ctx.push) {
+		await git.push(ctx.cwd);
+		process.stdout.write("Pushed to remote.\n");
+	}
+}
+
+async function runSplitCommit(
+	plan: SplitCommitPlan,
+	ctx: CommitExecutionContext & { additionalFiles?: string[] },
+): Promise<void> {
+	if (plan.warnings.length > 0) {
+		process.stdout.write(formatWarnings(plan.warnings));
+	}
+	if (ctx.additionalFiles && ctx.additionalFiles.length > 0) {
+		appendFilesToLastCommit(plan, ctx.additionalFiles);
+	}
+	const stagedFiles = await git.diff.changedFiles(ctx.cwd, { cached: true });
+	const plannedFiles = new Set(plan.commits.flatMap(commit => commit.changes.map(change => change.path)));
+	const missingFiles = stagedFiles.filter(file => !plannedFiles.has(file));
+	if (missingFiles.length > 0) {
+		process.stderr.write(`Split commit plan missing staged files: ${missingFiles.join(", ")}\n`);
+		return;
+	}
+
+	if (ctx.dryRun) {
+		process.stdout.write("\nSplit commit plan (dry run):\n");
+		for (const [index, commit] of plan.commits.entries()) {
+			const analysis: ConventionalAnalysis = {
+				type: commit.type,
+				scope: commit.scope,
+				details: commit.details,
+				issueRefs: commit.issueRefs,
+			};
+			const message = formatCommitMessage(analysis, commit.summary);
+			process.stdout.write(`Commit ${index + 1}:\n${message}\n`);
+			const changeSummary = commit.changes
+				.map(change => formatFileChangeSummary(change.path, change.hunks))
+				.join(", ");
+			process.stdout.write(`Changes: ${changeSummary}\n`);
+		}
+		return;
+	}
+
+	if (!(await confirmSplitCommitPlan(plan))) {
+		process.stdout.write("Split commit aborted by user.\n");
+		return;
+	}
+
+	const order = computeDependencyOrder(plan.commits);
+	if ("error" in order) {
+		throw new Error(order.error);
+	}
+
+	await git.stage.reset(ctx.cwd);
+	for (const commitIndex of order) {
+		const commit = plan.commits[commitIndex];
+		await git.stage.hunks(ctx.cwd, commit.changes);
+		const analysis: ConventionalAnalysis = {
+			type: commit.type,
+			scope: commit.scope,
+			details: commit.details,
+			issueRefs: commit.issueRefs,
+		};
+		const message = formatCommitMessage(analysis, commit.summary);
+		await git.commit(ctx.cwd, message);
+		await git.stage.reset(ctx.cwd);
+	}
+	process.stdout.write("Split commits created.\n");
+	if (ctx.push) {
+		await git.push(ctx.cwd);
+		process.stdout.write("Pushed to remote.\n");
+	}
+}
+
+function appendFilesToLastCommit(plan: SplitCommitPlan, files: string[]): void {
+	if (plan.commits.length === 0) return;
+	const planned = new Set(plan.commits.flatMap(commit => commit.changes.map(change => change.path)));
+	const targetCommit = plan.commits[plan.commits.length - 1];
+	for (const file of files) {
+		if (planned.has(file)) continue;
+		targetCommit.changes.push({ path: file, hunks: { type: "all" } });
+		planned.add(file);
+	}
+}
+
+async function confirmSplitCommitPlan(plan: SplitCommitPlan): Promise<boolean> {
+	if (!process.stdin.isTTY || !process.stdout.isTTY) {
+		return true;
+	}
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	try {
+		const splitConfirmQuestion = prompt.render(splitConfirmPrompt, { count: plan.commits.length });
+		const answer = await rl.question(splitConfirmQuestion);
+		return ["y", "yes"].includes(answer.trim().toLowerCase());
+	} finally {
+		rl.close();
+	}
+}
+
+function formatWarnings(warnings: string[]): string {
+	return `Warnings:\n${warnings.map(warning => `- ${warning}`).join("\n")}\n`;
+}
+
+function formatFileChangeSummary(path: string, hunks: HunkSelector): string {
+	if (hunks.type === "all") {
+		return `${path} (all)`;
+	}
+	if (hunks.type === "indices") {
+		return `${path} (hunks ${hunks.indices.join(", ")})`;
+	}
+	return `${path} (lines ${hunks.start}-${hunks.end})`;
+}
+
+async function loadExistingChangelogEntries(paths: string[]): Promise<ExistingChangelogEntries[]> {
+	const entries = await Promise.all(
+		paths.map(async path => {
+			let content: string;
+			try {
+				content = await Bun.file(path).text();
+			} catch (err) {
+				if (isEnoent(err)) return null;
+				throw err;
+			}
+			try {
+				const unreleased = parseUnreleasedSection(content);
+				const sections = Object.entries(unreleased.entries)
+					.filter(([, items]) => items.length > 0)
+					.map(([name, items]) => ({ name, items }));
+				if (sections.length > 0) {
+					return { path, sections };
+				}
+			} catch {
+				return null;
+			}
+			return null;
+		}),
+	);
+	return entries.filter((entry): entry is ExistingChangelogEntries => entry !== null);
+}

package/src/commit/agentic/prompts/analyze-file.md

@@ -0,0 +1,22 @@
+Analyze file at {{file}}.
+
+Goal:
+{{#if goal}}
+{{goal}}
+{{else}}
+Summarize purpose and commit-relevant changes.
+{{/if}}
+
+Return concise JSON object with:
+- summary: one-sentence description of file's role
+- highlights: 2-5 bullet points about notable behaviors or changes
+- risks: edge cases or risks worth noting (empty array if none)
+
+{{#if related_files}}
+## Other Files in This Change
+{{related_files}}
+
+Consider how file's changes relate to above files.
+{{/if}}
+
+Call submit_result tool with JSON payload.

package/src/commit/agentic/prompts/session-user.md

@@ -0,0 +1,25 @@
+Generate conventional commit proposal for current staged changes.
+
+{{#if user_context}}
+User context:
+{{user_context}}
+{{/if}}
+
+{{#if changelog_targets}}
+Changelog targets (must call propose_changelog for these files):
+{{changelog_targets}}
+{{/if}}
+
+{{#if existing_changelog_entries}}
+## Existing Unreleased Changelog Entries
+May include entries from list in propose_changelog `deletions` field for removal.
+{{#each existing_changelog_entries}}
+### {{path}}
+{{#each sections}}
+{{name}}:
+{{#list items prefix="- " join="\n"}}{{this}}{{/list}}
+{{/each}}
+{{/each}}
+{{/if}}
+
+Use git_* tools to inspect changes. Call analyze_files for deeper per-file summaries. Finish with propose_commit or split_commit.

package/src/commit/agentic/prompts/split-confirm.md

@@ -0,0 +1 @@
+Split commit plan has {{count}} commits. Proceed? (y/N):

package/src/commit/agentic/prompts/system.md

@@ -0,0 +1,38 @@
+You are xcsh commit workflow's conventional commit expert.
+
+Your job: decide needed git info, gather via tools, then call exactly one:
+- propose_commit (single commit)
+- split_commit (multiple commits when changes are unrelated)
+
+Workflow rules:
+1. Always call git_overview first.
+2. Keep tool calls minimal: prefer 1-2 git_file_diff calls for key files (hard limit 2).
+3. Use git_hunk only for large diffs.
+4. Use recent_commits only if you need style context.
+5. Use analyze_files only when diffs too large or unclear.
+6. Do not use read.
+
+Commit requirements:
+- Summary line: past-tense verb, ≤ 72 chars, no trailing period.
+- Avoid filler words: comprehensive, various, several, improved, enhanced, better.
+- Avoid meta phrases: "this commit", "this change", "updated code", "modified files".
+- Scope: lowercase, max two segments; only letters, digits, hyphens, underscores.
+- Detail lines optional (0-6). Each sentence ending in period, ≤ 120 chars.
+
+Conventional commit types:
+{{types_description}}
+
+Tool guidance:
+- git_overview: staged files, stat summary, numstat, scope candidates
+- git_file_diff: diff for specific files
+- git_hunk: specific hunks for large diffs
+- recent_commits: recent commit subjects + style stats
+- analyze_files: spawn quick_task subagents in parallel for analysis
+- propose_changelog: provide changelog entries for each changelog target
+- propose_commit: submit final commit proposal and run validation
+- split_commit: propose multiple commit groups (no overlapping files; all staged files covered)
+
+## Changelog Requirements
+
+If changelog targets provided, you **MUST** call `propose_changelog` before finishing.
+If you propose split commit plan, include changelog target files in relevant commit changes.

package/src/commit/agentic/state.ts

@@ -0,0 +1,60 @@
+import type { CommitType, ConventionalAnalysis, ConventionalDetail, NumstatEntry } from "../../commit/types";
+
+export interface GitOverviewSnapshot {
+	files: string[];
+	stat: string;
+	numstat: NumstatEntry[];
+	scopeCandidates: string;
+	isWideScope: boolean;
+	untrackedFiles?: string[];
+	excludedFiles?: string[];
+}
+
+export interface CommitProposal {
+	analysis: ConventionalAnalysis;
+	summary: string;
+	warnings: string[];
+}
+
+export type HunkSelector =
+	| { type: "all" }
+	| { type: "indices"; indices: number[] }
+	| { type: "lines"; start: number; end: number };
+
+export interface FileChange {
+	path: string;
+	hunks: HunkSelector;
+}
+
+export interface SplitCommitGroup {
+	changes: FileChange[];
+	type: CommitType;
+	scope: string | null;
+	summary: string;
+	details: ConventionalDetail[];
+	issueRefs: string[];
+	rationale?: string;
+	dependencies: number[];
+}
+
+export interface SplitCommitPlan {
+	commits: SplitCommitGroup[];
+	warnings: string[];
+}
+
+export interface ChangelogProposal {
+	entries: Array<{
+		path: string;
+		entries: Record<string, string[]>;
+		deletions?: Record<string, string[]>;
+	}>;
+}
+
+export interface CommitAgentState {
+	overview?: GitOverviewSnapshot;
+	proposal?: CommitProposal;
+	splitProposal?: SplitCommitPlan;
+	changelogProposal?: ChangelogProposal;
+	diffCache?: Map<string, string>;
+	diffText?: string;
+}