@gitkraken/compose-tools 0.1.0

package/dist/tasks/order/prompt.js

@@ -0,0 +1,45 @@
+import{orderingResultSchema as e}from"./schema.js";import{z as t}from"zod";const n=JSON.stringify(t.toJSONSchema(e),null,2);function r(){return`You are an advanced AI programming assistant tasked with determining the optimal order for commits within each branch. Your goal is to order commits so that:
+
+1. **Dependencies are respected** — if commit A introduces something that commit B relies on, A must come before B
+2. **Refactoring before features** — structural improvements and refactors should precede new functionality that builds on them
+3. **Infrastructure before consumers** — types, interfaces, and utilities should come before the code that uses them
+4. **Tests near their implementation** — test commits should follow closely after the code they test
+5. **Clean build at each step** — ideally, the codebase should be in a valid state after each commit
+
+You will receive one or more branches, each containing unordered commits. Order the commits within each branch independently.
+
+## Required Output Format
+
+Output the ordered commit IDs per branch as JSON inside a <output> tag matching this schema:
+
+\`\`\`json
+${n}
+\`\`\`
+
+Return only the <output> tag and no other text.`}function i(e){let{branches:t,hunks:n,instructions:r}=e,i=`Determine the optimal commit order within each branch:\n\n<branches>\n${JSON.stringify(t.map(e=>({id:e.id,name:e.name,commits:e.commits.map(e=>({id:e.id,message:e.message,explanation:e.explanation,hunkIndices:e.hunkIndices}))})))}\n</branches>`;if(n?.length){let e=JSON.stringify(n.map(e=>({index:e.index,fileName:e.fileName,hunkHeader:e.hunkHeader})));i+=`\n\nFor reference, here is the hunk index to file mapping:\n<hunk_map>\n${e}\n</hunk_map>`}return r&&(i+=`\n\nAdditional instructions:\n${r}`),i+=`
+
+Return the ordered commit IDs per branch. Return only the <output> tag and no other text.`,i}function a(e){let t=`Based on the branches and commits you created, determine the optimal order for the commits within each branch.
+
+Ordering principles:
+1. Dependencies first — if commit A introduces something commit B relies on, A must come before B
+2. Refactoring before features — structural improvements precede new functionality
+3. Infrastructure before consumers — types, interfaces, utilities before the code using them
+4. Tests near their implementation — test commits follow closely after the code they test
+5. Clean build at each step — the codebase should be valid after each commit
+
+IMPORTANT: Respect the ordering constraints you identified in your analysis. If a hunk provides something (defines a file, function, type, etc.) that another hunk consumes (imports, calls, references), the provider's commit must come before or be the same as the consumer's commit.`;return e.instructions&&(t+=`\n\nAdditional instructions:\n${e.instructions}`),t+=`
+
+Return the ordered commit IDs per branch as JSON inside <output> tags:
+<output>
+{
+  "branches": [
+    {
+      "branchId": "[branch id]",
+      "orderedCommitIds": ["[first]", "[second]"]
+    }
+  ],
+  "rationale": "[explanation]"
+}
+</output>
+
+Return only the <output> tag and no other text.`,t}export{a as buildOrderContinuationPrompt,r as buildOrderSystemPrompt,i as buildOrderUserPrompt};

package/dist/tasks/order/schema.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+
+//#region src/tasks/order/schema.d.ts
+declare const orderingResultSchema: z.ZodObject<{
+  branches: z.ZodArray<z.ZodObject<{
+    branchId: z.ZodString;
+    orderedCommitIds: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>>;
+  rationale: z.ZodString;
+}, z.core.$strip>;
+//#endregion
+export { orderingResultSchema };

package/dist/tasks/order/schema.js

@@ -0,0 +1 @@
+import{z as e}from"zod";const t=e.object({branchId:e.string().describe(`ID of the branch being ordered`),orderedCommitIds:e.array(e.string()).describe(`Commit IDs in optimal order`)}),n=e.object({branches:e.array(t).describe(`Ordered commits per branch`),rationale:e.string().describe(`Explanation of ordering decisions`)});export{n as orderingResultSchema};

package/dist/tasks/order/types.d.ts

@@ -0,0 +1,36 @@
+import { ProgressEvent, TokenUsage } from "../../ai/types.js";
+import { BranchGroup, BranchOrdering, ComposeHunk, PromptOverride } from "../types.js";
+import { OnAfterModelCall, OnBeforeModelCall, OnBeforePrompt } from "../ai-loop.js";
+import { ComposeSession } from "../session.js";
+import { AiModelPort } from "@gitkraken/shared-tools";
+
+//#region src/tasks/order/types.d.ts
+interface OrderInput {
+  branches?: BranchGroup[];
+  hunks?: ComposeHunk[];
+  instructions?: string;
+  model: AiModelPort;
+  session?: ComposeSession;
+  maxRetries?: number;
+  onProgress?: (event: ProgressEvent) => void;
+  signal?: AbortSignal;
+  onBeforeModelCall?: OnBeforeModelCall;
+  onAfterModelCall?: OnAfterModelCall;
+  onBeforePrompt?: OnBeforePrompt;
+  /** Optional prompt override. When set, replaces or decorates the built-in prompts. */
+  promptOverride?: PromptOverride;
+}
+interface OrderingResult {
+  branches: BranchOrdering[];
+  rationale: string;
+}
+interface OrderOutput {
+  result: OrderingResult;
+  session: ComposeSession;
+  usage?: TokenUsage;
+  attempts: number;
+  durationMs: number;
+  callIds: string[];
+}
+//#endregion
+export { OrderInput, OrderOutput, OrderingResult };

package/dist/tasks/order/types.js

@@ -0,0 +1 @@
+export{};

package/dist/tasks/order/validator.d.ts

@@ -0,0 +1,11 @@
+import { ValidationResult } from "../ai-loop.js";
+import { OrderingResult } from "./types.js";
+
+//#region src/tasks/order/validator.d.ts
+interface KnownBranch {
+  branchId: string;
+  commitIds: string[];
+}
+declare function validateOrderResponse(responseText: string, knownBranches: KnownBranch[]): ValidationResult<OrderingResult>;
+//#endregion
+export { validateOrderResponse };

package/dist/tasks/order/validator.js

@@ -0,0 +1,12 @@
+import{extractOutputTag as e}from"../ai-loop.js";import{orderingResultSchema as t}from"./schema.js";function n(n,a){try{let o=e(n);if(!o)return r([`No <output> tag found in response`],i(a));let s=JSON.parse(o),c=t.safeParse(s);if(!c.success)return r(c.error.issues.map(e=>`${e.path.join(`.`)}: ${e.message}`),i(a));let l=c.data,u=[],d=new Set;for(let e of l.branches){d.add(e.branchId);let t=a.find(t=>t.branchId===e.branchId);if(!t)return r([`Unknown branch ID: '${e.branchId}'`],`Branch ID '${e.branchId}' doesn't match any known branch.\n\nKnown branches: ${a.map(e=>e.branchId).join(`, `)}`);let n=new Set(t.commitIds),i=new Set,o=[],s=[];for(let t of e.orderedCommitIds)i.has(t)&&o.push(t),n.has(t)||s.push(t),i.add(t);if(o.length>0)return r([`Branch '${e.branchId}': duplicate commit IDs: ${o.join(`, `)}`],`Branch '${e.branchId}' has duplicate commits. Each must appear exactly once.\n\nDuplicates: ${o.join(`, `)}`);if(s.length>0)return r([`Branch '${e.branchId}': unknown commit IDs: ${s.join(`, `)}`],`Branch '${e.branchId}' references unknown commits.\n\nUnknown: ${s.join(`, `)}\nValid: ${t.commitIds.join(`, `)}`);let c=t.commitIds.filter(e=>!i.has(e));if(c.length>0)return r([`Branch '${e.branchId}': missing commit IDs: ${c.join(`, `)}`],`Branch '${e.branchId}' is missing some commits.\n\nMissing: ${c.join(`, `)}`);u.push({branchId:e.branchId,orderedCommitIds:e.orderedCommitIds})}let f=a.filter(e=>!d.has(e.branchId));return f.length>0?r([`Missing branches: ${f.map(e=>e.branchId).join(`, `)}`],`Some branches are not included in the ordering.\n\nMissing: ${f.map(e=>e.branchId).join(`, `)}`):{valid:!0,result:{branches:u,rationale:l.rationale}}}catch{return r([`Failed to parse response as valid JSON`],i(a))}}function r(e,t){return{valid:!1,errors:e,retryFeedback:t}}function i(e){return`Your response has an invalid structure. Return JSON inside <output> tags:
+<output>
+{
+  "branches": [
+${e.map(e=>`    { "branchId": "${e.branchId}", "orderedCommitIds": ${JSON.stringify(e.commitIds)} }`).join(`,
+`)}
+  ],
+  "rationale": "[explanation]"
+}
+</output>
+
+All branches must be present with all their commits ordered. Return only the <output> tag and no other text.`}export{n as validateOrderResponse};

package/dist/tasks/partition/partition.d.ts

@@ -0,0 +1,6 @@
+import { PartitionInput, PartitionOutput } from "./types.js";
+
+//#region src/tasks/partition/partition.d.ts
+declare function partition(input: PartitionInput): Promise<PartitionOutput>;
+//#endregion
+export { partition };

package/dist/tasks/partition/partition.js

@@ -0,0 +1 @@
+import{TaskInputError as e}from"../../errors/task.js";import{runAiLoop as t}from"../ai-loop.js";import{applyUserPromptOverride as n}from"../types.js";import{buildPartitionContinuationPrompt as r,buildPartitionSystemPrompt as i,buildPartitionUserPrompt as a}from"./prompt.js";import{validatePartitionResponse as o}from"./validator.js";async function s(s){let c=s.commits,l=s.orderedCommitIds??c?.map(e=>e.id)??[];if(l.length===0)throw new e(`No commits provided: supply 'commits' or 'orderedCommitIds'`);if(s.session?.completedSteps.partition)return{result:s.session.completedSteps.partition,session:s.session,attempts:0,durationMs:0,callIds:[]};let u=n(s.session?r(s):a({commits:c,orderedCommitIds:l,sourceBranchName:s.sourceBranchName,baseBranch:s.baseBranch,instructions:s.instructions}),s.promptOverride),d=await t({model:s.model,systemPrompt:s.session?void 0:s.promptOverride?.system??i(s.conventions,s.strategy),userPrompt:u,session:s.session,maxRetries:s.maxRetries,onProgress:s.onProgress,signal:s.signal,onBeforeModelCall:s.onBeforeModelCall,onAfterModelCall:s.onAfterModelCall,onBeforePrompt:s.onBeforePrompt,validate:e=>o(e,l,s.existingBranchNames),taskName:`partition`}),f=s.session?.completedSteps??{},p={...d.session,completedSteps:{...f,partition:d.result}};return{result:d.result,session:p,usage:d.usage,attempts:d.attempts,durationMs:d.durationMs,callIds:d.callIds}}export{s as partition};

package/dist/tasks/partition/prompt.d.ts

@@ -0,0 +1,16 @@
+import { CommitSuggestion } from "../types.js";
+import { ConventionDescriptor } from "../../git/utils/conventions.js";
+import { PartitionInput, PartitionStrategy } from "./types.js";
+
+//#region src/tasks/partition/prompt.d.ts
+declare function buildPartitionSystemPrompt(conventions?: ConventionDescriptor, strategy?: PartitionStrategy): string;
+declare function buildPartitionUserPrompt(params: {
+  commits: CommitSuggestion[];
+  orderedCommitIds: string[];
+  sourceBranchName?: string;
+  baseBranch?: string;
+  instructions?: string;
+}): string;
+declare function buildPartitionContinuationPrompt(input: PartitionInput): string;
+//#endregion
+export { buildPartitionContinuationPrompt, buildPartitionSystemPrompt, buildPartitionUserPrompt };

package/dist/tasks/partition/prompt.js

@@ -0,0 +1,61 @@
+import{partitionResultSchema as e}from"./schema.js";import{z as t}from"zod";const n=JSON.stringify(t.toJSONSchema(e),null,2);function r(e,t){let r=e?.branches&&e.branches.format!==`unknown`?`For each sub-branch, name it following the repository's branch naming conventions.\n\n${e.promptFragment}`:`For each sub-branch, provide a branch name derived from the source branch name (e.g., "feature/part-1-description").`;return`You are an advanced AI programming assistant tasked with determining whether an ordered list of commits on a single branch should be subdivided into stacked branches for a pull request workflow.
+
+Your goal is to examine the commits and decide whether they form one cohesive unit or whether there are natural subdivision points that would benefit from stacked PRs.
+
+Rules:
+1. Each sub-branch is a CONTIGUOUS range of commits from the ordered list
+2. Each sub-branch represents an independently reviewable and mergeable unit
+3. Earlier sub-branches can be merged first — later ones build on them
+4. A single sub-branch (no subdivision) is a perfectly valid and common outcome
+5. A single-commit sub-branch is valid if that commit is independently mergeable
+
+${i(t?.splitting)}
+
+${r}
+- A short PR-style title (under 72 characters, imperative mood)
+- A description of what the sub-branch accomplishes
+- The commit IDs it contains (in order)
+
+## Required Output Format
+
+Output your partition as JSON inside a <output> tag matching this schema:
+
+\`\`\`json
+${n}
+\`\`\`
+
+Return only the <output> tag and no other text.`}function i(e){let t=`Consider merge-order preference: even if sub-groups compile independently, keep them together if merging one without the other would be incomplete or confusing to reviewers.`;return e===`conservative`?`Keep commits as a single branch unless the sub-groups address completely different concerns with no merge-order preference between them.
+${t}
+Changes addressing the same pattern across different files should stay together. When in doubt, do not partition.`:e===`aggressive`?`Subdivide whenever there is a clear concern boundary between contiguous groups of commits. Each sub-group should be as focused as possible.
+${t}
+Prefer more partitions over fewer. Each stacked PR should tell one focused story.`:`Only partition when the sub-groups are independently reviewable AND independently mergeable, and a reviewer would genuinely benefit from seeing them as separate PRs.
+
+Do NOT partition just because commits are distinct. A branch with a refactor commit followed by a feature commit that uses the refactor is a perfectly coherent single PR.
+
+Changes addressing the same pattern across different files should stay together. For example, applying a similar fix to multiple functions belongs in one branch, not split across multiple stacked PRs.
+
+${t}`}function a(e){let{commits:t,orderedCommitIds:n,sourceBranchName:r,baseBranch:i,instructions:a}=e,o=n.map(e=>{let n=t.find(t=>t.id===e);return n?{id:n.id,message:n.message,explanation:n.explanation}:{id:e,message:`unknown`,explanation:``}}),s=`Determine whether these ordered commits should be subdivided into stacked branches:\n\n<commits>\n${JSON.stringify(o)}\n</commits>`,c=[];return r&&c.push(`Source branch: ${r}`),i&&c.push(`Base branch: ${i}`),c.length>0&&(s+=`\n\n<context>\n${c.join(`
+`)}\n</context>`),a&&(s+=`\n\nAdditional instructions:\n${a}`),s+=`
+
+Return the partition. Return only the <output> tag and no other text.`,s}function o(e){let t=s(e.strategy);return e.sourceBranchName&&(t+=`\n\nSource branch: ${e.sourceBranchName}`),e.baseBranch&&(t+=`\nBase branch: ${e.baseBranch}`),e.conventions?.promptFragment&&(t+=`\n\n${e.conventions.promptFragment}`),e.instructions&&(t+=`\n\nAdditional instructions:\n${e.instructions}`),t+=`
+
+Return the partition as JSON inside <output> tags:
+<output>
+{
+  "partitions": [
+    { "branchName": "[name]", "title": "[short PR title]", "description": "[what it does]", "commitIds": ["[id1]", "[id2]"] }
+  ],
+  "rationale": "[explanation]"
+}
+</output>
+
+Return only the <output> tag and no other text.`,t}function s(e){let t=e?.splitting??`balanced`,n=`Based on the ordered commits for this branch, determine whether they should be subdivided into stacked sub-branches. Each sub-branch must be a contiguous range of commits.`,r=`Consider merge-order preference: even if sub-groups compile independently, keep them together if merging one without the other would be incomplete or confusing.`;return t===`conservative`?`${n}
+
+Keep as a single branch unless sub-groups address completely different concerns with no merge-order preference. ${r}
+When in doubt, do not partition.`:t===`aggressive`?`${n}
+
+Subdivide whenever there is a clear concern boundary. Each stacked PR should tell one focused story. Prefer more partitions over fewer. ${r}`:`${n}
+
+Only subdivide when the sub-groups are independently reviewable AND independently mergeable, and a reviewer would genuinely benefit from separate PRs. Do NOT partition just because commits are distinct — a refactor followed by a feature using it is a coherent single PR.
+
+${r}`}export{o as buildPartitionContinuationPrompt,r as buildPartitionSystemPrompt,a as buildPartitionUserPrompt};

package/dist/tasks/partition/schema.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+//#region src/tasks/partition/schema.d.ts
+declare const partitionResultSchema: z.ZodObject<{
+  partitions: z.ZodArray<z.ZodObject<{
+    branchName: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+    commitIds: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>>;
+  rationale: z.ZodString;
+}, z.core.$strip>;
+//#endregion
+export { partitionResultSchema };

package/dist/tasks/partition/schema.js

@@ -0,0 +1 @@
+import{z as e}from"zod";const t=e.object({branchName:e.string().min(1).describe(`Valid git branch name`),title:e.string().describe(`Short PR-style title for this sub-branch (under 72 chars, imperative mood, e.g. 'Refactor authentication middleware')`),description:e.string().describe(`What this sub-branch accomplishes`),commitIds:e.array(e.string()).min(1).describe(`Commit IDs in this partition (contiguous range)`)}),n=e.object({partitions:e.array(t).min(1).describe(`Contiguous partitions of commits into stacked branches`),rationale:e.string().describe(`Explanation of why this partition was chosen`)});export{n as partitionResultSchema};

package/dist/tasks/partition/types.d.ts

@@ -0,0 +1,53 @@
+import { ProgressEvent, TokenUsage } from "../../ai/types.js";
+import { BranchPartition, CommitSuggestion, PromptOverride } from "../types.js";
+import { ConventionDescriptor } from "../../git/utils/conventions.js";
+import { OnAfterModelCall, OnBeforeModelCall, OnBeforePrompt } from "../ai-loop.js";
+import { ComposeSession } from "../session.js";
+import { AiModelPort } from "@gitkraken/shared-tools";
+
+//#region src/tasks/partition/types.d.ts
+interface PartitionStrategy {
+  /**
+   * How aggressively to subdivide a branch into stacked sub-branches.
+   * - "conservative": keep as single branch unless sub-groups are truly independent PRs
+   * - "balanced": subdivide when concerns are distinct and independently reviewable (default)
+   * - "aggressive": maximize subdivision; any concern boundary becomes a stack point
+   */
+  splitting?: 'conservative' | 'balanced' | 'aggressive';
+}
+interface PartitionInput {
+  commits?: CommitSuggestion[];
+  orderedCommitIds?: string[];
+  sourceBranchName?: string;
+  baseBranch?: string;
+  instructions?: string;
+  conventions?: ConventionDescriptor;
+  /** Controls how aggressively the AI subdivides into stacked branches. */
+  strategy?: PartitionStrategy;
+  /** Branch names that already exist (or are claimed by earlier phases) — used to detect collisions during validation. */
+  existingBranchNames?: Set<string>;
+  model: AiModelPort;
+  session?: ComposeSession;
+  maxRetries?: number;
+  onProgress?: (event: ProgressEvent) => void;
+  signal?: AbortSignal;
+  onBeforeModelCall?: OnBeforeModelCall;
+  onAfterModelCall?: OnAfterModelCall;
+  onBeforePrompt?: OnBeforePrompt;
+  /** Optional prompt override. When set, replaces or decorates the built-in prompts. */
+  promptOverride?: PromptOverride;
+}
+interface PartitionResult {
+  partitions: BranchPartition[];
+  rationale: string;
+}
+interface PartitionOutput {
+  result: PartitionResult;
+  session: ComposeSession;
+  usage?: TokenUsage;
+  attempts: number;
+  durationMs: number;
+  callIds: string[];
+}
+//#endregion
+export { PartitionInput, PartitionOutput, PartitionResult, PartitionStrategy };

package/dist/tasks/partition/types.js

@@ -0,0 +1 @@
+export{};

package/dist/tasks/partition/validator.d.ts

@@ -0,0 +1,7 @@
+import { ValidationResult } from "../ai-loop.js";
+import { PartitionResult } from "./types.js";
+
+//#region src/tasks/partition/validator.d.ts
+declare function validatePartitionResponse(responseText: string, knownIds: string[], existingBranchNames?: Set<string>): ValidationResult<PartitionResult>;
+//#endregion
+export { validatePartitionResponse };

package/dist/tasks/partition/validator.js

@@ -0,0 +1,11 @@
+import{extractOutputTag as e}from"../ai-loop.js";import{partitionResultSchema as t}from"./schema.js";function n(n,s,c){try{let l=e(n);if(!l)return a([`No <output> tag found in response`],o());let u=JSON.parse(l),d=t.safeParse(u);if(!d.success)return a(d.error.issues.map(e=>`${e.path.join(`.`)}: ${e.message}`),o());let f=d.data,p=[],m=[],h=new Set;for(let e=0;e<f.partitions.length;e++){let t=f.partitions[e];if(!i(t.branchName))return a([`Partition ${e}: '${t.branchName}' is not a valid git branch name`],`The branch name '${t.branchName}' is invalid. Git branch names cannot contain spaces, '..', '~', '^', ':', '\\', or end with '.lock'. Please provide a valid name.`);if(h.has(t.branchName))return a([`Duplicate partition branch name: '${t.branchName}'`],`Multiple partitions use the branch name '${t.branchName}'. Each partition must have a unique branch name. Please rename one of them.`);if(h.add(t.branchName),c?.has(t.branchName))return a([`Branch name '${t.branchName}' already exists in the repository`],`The branch name '${t.branchName}' already exists in the repository. Please choose a different name for partition ${e}.`);for(let e of t.commitIds)m.push(e);p.push({branchName:t.branchName,title:t.title,description:t.description,commitIds:t.commitIds})}let g=new Set,_=[];for(let e of m)g.has(e)&&_.push(e),g.add(e);if(_.length>0)return a([`Duplicate commit IDs: ${_.join(`, `)}`],`Some commits appear in multiple partitions. Each must be in exactly one.\n\nDuplicates: ${_.join(`, `)}`);let v=new Set(s),y=s.filter(e=>!g.has(e)),b=m.filter(e=>!v.has(e));return y.length>0?a([`Missing commits: ${y.join(`, `)}`],`Some commits are not assigned to any partition.\n\nMissing: ${y.join(`, `)}`):b.length>0?a([`Unknown commits: ${b.join(`, `)}`],`Some commit IDs don't match any known commit.\n\nUnknown: ${b.join(`, `)}`):r(p,s)?{valid:!0,result:{partitions:p,rationale:f.rationale}}:a([`Partitions are not contiguous`],`Each partition must contain a contiguous range of commits in the provided order. Please regroup into contiguous ranges.`)}catch{return a([`Failed to parse response as valid JSON`],o())}}function r(e,t){let n=new Map(t.map((e,t)=>[e,t])),r=0;for(let t of e)for(let e of t.commitIds){let t=n.get(e);if(t===void 0||t!==r)return!1;r++}return r===t.length}function i(e){return e.startsWith(`-`)||e.startsWith(`.`)||e.endsWith(`.lock`)||e.endsWith(`.`)||e.endsWith(`/`)||e.includes(`..`)||e.includes(`~`)||e.includes(`^`)||e.includes(`:`)||e.includes(`\\`)||e.includes(` `)||e.includes(`?`)||e.includes(`*`)||e.includes(`[`)||e.includes(`@{`)?!1:e.length>0}function a(e,t){return{valid:!1,errors:e,retryFeedback:t}}function o(){return`Your response has an invalid structure. Return JSON inside <output> tags:
+<output>
+{
+  "partitions": [
+    { "branchName": "[name]", "title": "[short PR title]", "description": "[what it does]", "commitIds": ["[id1]", "[id2]"] }
+  ],
+  "rationale": "[explanation]"
+}
+</output>
+
+Return only the <output> tag and no other text.`}export{n as validatePartitionResponse};

package/dist/tasks/quick-compose/prompt.d.ts

@@ -0,0 +1,18 @@
+import { ComposeHunk } from "../types.js";
+import { ConventionDescriptor } from "../../git/utils/conventions.js";
+import { GroupingStrategy } from "../group/types.js";
+
+//#region src/tasks/quick-compose/prompt.d.ts
+declare function buildQuickComposeSystemPrompt(conventions?: ConventionDescriptor, mode?: 'commits' | 'branches', strategy?: GroupingStrategy, includePartitions?: boolean): string;
+declare function buildQuickComposeUserPrompt(params: {
+  hunks: ComposeHunk[];
+  commitMessages?: string[];
+  commitOrder?: string[];
+  branchName?: string;
+  baseBranch?: string;
+  issueUrl?: string;
+  pullRequestUrl?: string;
+  instructions?: string;
+}): string;
+//#endregion
+export { buildQuickComposeSystemPrompt, buildQuickComposeUserPrompt };

package/dist/tasks/quick-compose/prompt.js

@@ -0,0 +1,47 @@
+import{quickComposeResultSchema as e}from"./schema.js";import{z as t}from"zod";const n=JSON.stringify(t.toJSONSchema(e),null,2);function r(e,t=`branches`,r,i=!1){let c=e?.promptFragment?`Write commit messages following the repository's conventions:\n\n${e.promptFragment}`:`Write commit messages:
+- First line: concise summary, 50 chars max, third-person singular present tense ("Fixes", "Adds", "Improves")
+   - Then a blank line followed by details focusing on "why" not "what"`,l=a(r?.commitGranularity),u=t===`branches`?o(r?.branchSplitting,e):``,d=i?s():``;return`You are a fast AI code organizer. Given a set of code diff hunks, organize them into well-structured commits${t===`branches`?` and branches`:``} in a single pass.
+
+## Your task
+
+1. **Group** hunks into logical, atomic commits. Each hunk goes in exactly one commit.
+2. **Order** commits within each branch so dependencies flow correctly. If commit A defines something commit B uses, A comes first. Rename hunks (isRename=true) must come before any hunks referencing the new file path.
+3. Write a short commit message and explanation for each commit.
+${t===`branches`?`4. Assign commits to branches — each branch is a cohesive unit of work for one PR.`:`4. Place all commits in a single branch with id "default", name "", title "", description "".`}
+${i?`5. If a branch should be split into stacked sub-branches for review, provide partitions.`:``}
+
+## Commit style
+${c}
+${l}
+${u}
+${d}
+
+## Rules
+- Every hunk must be assigned to exactly one commit
+- Every commit must contain at least one hunk — no empty commits
+- orderedCommitIds must list every commit ID in the branch in the order they should be applied
+- Keep it practical — focus on clean grouping over deep dependency analysis
+
+## Required Output Format
+
+Output as JSON inside a <output> tag matching this schema:
+
+\`\`\`json
+${n}
+\`\`\`
+
+Return only the <output> tag and no other text.`}function i(e){let{hunks:t,commitMessages:n,commitOrder:r,branchName:i,baseBranch:a,issueUrl:o,pullRequestUrl:s,instructions:c}=e,l=`Organize these code hunks into commits:
+
+<hunks>
+${JSON.stringify(t.map(e=>({index:e.index,fileName:e.fileName,hunkHeader:e.hunkHeader,content:e.content,...e.isBinary?{isBinary:!0}:{},...e.isRename?{isRename:!0}:{},...e.originalFileName?{originalFileName:e.originalFileName}:{}})))}
+</hunks>`,u=[];return i&&u.push(`Branch: ${i}`),a&&u.push(`Base: ${a}`),o&&u.push(`Issue: ${o}`),s&&u.push(`PR: ${s}`),u.length>0&&(l+=`\n\nContext:\n${u.join(`
+`)}`),n?.length&&(l+=`\n\nOriginal commit messages (match their style):\n<commit_messages>\n${JSON.stringify(n)}\n</commit_messages>`),r?.length&&(l+=`\n\nOriginal commit order:\n${JSON.stringify(r)}`),c&&(l+=`\n\nAdditional instructions:\n${c}`),l+=`
+
+Return only the <output> tag and no other text.`,l}function a(e){return e===`consolidated`?`
+Prefer fewer, larger commits. Combine related changes into a single commit.`:e===`granular`?`
+Prefer more, smaller commits. Each distinct change gets its own commit.`:``}function o(e,t){let n=`\n## Branch guidelines\n- Each branch has a descriptive name, a short PR title (under 72 chars), and at least one commit.\n- ${t?.promptFragment?`Follow the repository's branch naming conventions.`:`Give each branch a descriptive name.`}`;return e===`conservative`?`${n}\n- Default to a single branch. Only split when concerns are completely unrelated.`:e===`aggressive`?`${n}\n- Create separate branches for each distinct concern. Maximize focus per PR.`:`${n}\n- Split when concerns are genuinely independent. Keep together when they form a coherent story.`}function s(){return`
+## Partition guidelines (stacked sub-branches)
+- If a branch has multiple distinct concerns, split it into partitions for stacked review.
+- Each partition is a contiguous range of commits from orderedCommitIds.
+- Each partition gets a unique, valid git branch name.
+- Single partition (no split) is a valid outcome.`}export{r as buildQuickComposeSystemPrompt,i as buildQuickComposeUserPrompt};

package/dist/tasks/quick-compose/quick-compose.d.ts

@@ -0,0 +1,6 @@
+import { QuickComposeInput, QuickComposeOutput } from "./types.js";
+
+//#region src/tasks/quick-compose/quick-compose.d.ts
+declare function quickCompose(input: QuickComposeInput): Promise<QuickComposeOutput>;
+//#endregion
+export { quickCompose };

package/dist/tasks/quick-compose/quick-compose.js

@@ -0,0 +1 @@
+import{TaskInputError as e}from"../../errors/task.js";import{runAiLoop as t}from"../ai-loop.js";import{applyUserPromptOverride as n}from"../types.js";import{buildQuickComposeSystemPrompt as r,buildQuickComposeUserPrompt as i}from"./prompt.js";import{validateQuickComposeResponse as a}from"./validator.js";async function o(o){let s=o.hunks,c=o.mode??`branches`,l=o.includePartitions??!1;if(!s||s.length===0)throw new e(`No hunks provided for quick compose`);if(o.session?.completedSteps.quickCompose)return{result:o.session.completedSteps.quickCompose,session:o.session,attempts:0,durationMs:0,callIds:[]};let u=o.promptOverride?.system??r(o.conventions,c,o.strategy,l),d=n(i({hunks:s,commitMessages:o.commitMessages,commitOrder:o.commitOrder,branchName:o.branchName,baseBranch:o.baseBranch,issueUrl:o.issueUrl,pullRequestUrl:o.pullRequestUrl,instructions:o.instructions}),o.promptOverride),f=await t({model:o.model,systemPrompt:u,userPrompt:d,maxRetries:o.maxRetries,onProgress:o.onProgress,signal:o.signal,onBeforeModelCall:o.onBeforeModelCall,onAfterModelCall:o.onAfterModelCall,onBeforePrompt:o.onBeforePrompt,validate:e=>a(e,s.length,c,l,o.existingBranchNames),taskName:`quick-compose`}),p=o.session?.completedSteps??{},m={...f.session,completedSteps:{...p,quickCompose:f.result}};return{result:f.result,session:m,usage:f.usage,attempts:f.attempts,durationMs:f.durationMs,callIds:f.callIds}}export{o as quickCompose};

package/dist/tasks/quick-compose/schema.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+
+//#region src/tasks/quick-compose/schema.d.ts
+declare const quickComposeResultSchema: z.ZodObject<{
+  branches: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+    commits: z.ZodArray<z.ZodObject<{
+      id: z.ZodString;
+      message: z.ZodString;
+      explanation: z.ZodString;
+      hunks: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strip>>;
+    orderedCommitIds: z.ZodArray<z.ZodString>;
+    partitions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      branchName: z.ZodString;
+      title: z.ZodString;
+      description: z.ZodString;
+      commitIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+  }, z.core.$strip>>;
+  rationale: z.ZodString;
+}, z.core.$strip>;
+//#endregion
+export { quickComposeResultSchema };

package/dist/tasks/quick-compose/schema.js

@@ -0,0 +1 @@
+import{z as e}from"zod";const t=e.object({id:e.string().describe(`Unique commit ID (e.g. commit-1)`),message:e.string().describe(`Commit message`),explanation:e.string().describe(`Detailed explanation of the commit`),hunks:e.array(e.number().int().describe(`Hunk index`)).describe(`Hunk indices included in this commit`)}),n=e.object({branchName:e.string().min(1).describe(`Git branch name for this partition`),title:e.string().describe(`Short PR-style title`),description:e.string().describe(`What this partition accomplishes`),commitIds:e.array(e.string()).min(1).describe(`Ordered commit IDs in this partition`)}),r=e.object({id:e.string().min(1).describe(`Unique branch ID`),name:e.string().describe(`Branch name (empty string for commits-only mode)`),title:e.string().describe(`Short PR-style title (under 72 chars, imperative mood)`),description:e.string().describe(`What this branch accomplishes`),commits:e.array(t).min(1).describe(`Commits in this branch`),orderedCommitIds:e.array(e.string()).min(1).describe(`Commit IDs in optimal order`),partitions:e.array(n).optional().describe(`Stacked sub-branches (only for multi-branch mode)`)}),i=e.object({branches:e.array(r).min(1).describe(`Branches with grouped, ordered commits`),rationale:e.string().describe(`Brief explanation of the grouping and ordering rationale`)});export{i as quickComposeResultSchema};

package/dist/tasks/quick-compose/types.d.ts

@@ -0,0 +1,63 @@
+import { ProgressEvent, TokenUsage } from "../../ai/types.js";
+import { BranchPartition, CommitSuggestion, ComposeHunk, PromptOverride } from "../types.js";
+import { ConventionDescriptor } from "../../git/utils/conventions.js";
+import { OnAfterModelCall, OnBeforeModelCall, OnBeforePrompt } from "../ai-loop.js";
+import { GroupingStrategy } from "../group/types.js";
+import { ComposeSession } from "../session.js";
+import { AiModelPort } from "@gitkraken/shared-tools";
+
+//#region src/tasks/quick-compose/types.d.ts
+interface QuickComposeInput {
+  hunks: ComposeHunk[];
+  commitMessages?: string[];
+  commitOrder?: string[];
+  branchName?: string;
+  baseBranch?: string;
+  issueUrl?: string;
+  pullRequestUrl?: string;
+  instructions?: string;
+  conventions?: ConventionDescriptor;
+  /** "commits" = flat commit list (no branch naming). "branches" = AI decides branches. */
+  mode?: 'commits' | 'branches';
+  /** Whether to include partition info in the output (for auto target). */
+  includePartitions?: boolean;
+  /** Controls how aggressively the AI splits branches and commits. */
+  strategy?: GroupingStrategy;
+  /** Branch names that already exist — used to detect collisions during validation. */
+  existingBranchNames?: Set<string>;
+  model: AiModelPort;
+  /** Prior session to resume from. When `completedSteps.quickCompose` is present, skip the AI call. */
+  session?: ComposeSession;
+  maxRetries?: number;
+  onProgress?: (event: ProgressEvent) => void;
+  signal?: AbortSignal;
+  onBeforeModelCall?: OnBeforeModelCall;
+  onAfterModelCall?: OnAfterModelCall;
+  onBeforePrompt?: OnBeforePrompt;
+  /** Optional prompt override. When set, replaces or decorates the built-in prompts. */
+  promptOverride?: PromptOverride;
+}
+/** Raw combined result from the quick-compose AI output — one branch entry with embedded ordering+partitions. */
+interface QuickComposeBranch {
+  id: string;
+  name: string;
+  title: string;
+  description: string;
+  commits: CommitSuggestion[];
+  orderedCommitIds: string[];
+  partitions?: BranchPartition[];
+}
+interface QuickComposeResult {
+  branches: QuickComposeBranch[];
+  rationale: string;
+}
+interface QuickComposeOutput {
+  result: QuickComposeResult;
+  session: ComposeSession;
+  usage?: TokenUsage;
+  attempts: number;
+  durationMs: number;
+  callIds: string[];
+}
+//#endregion
+export { QuickComposeBranch, QuickComposeInput, QuickComposeOutput, QuickComposeResult };

package/dist/tasks/quick-compose/types.js

@@ -0,0 +1 @@
+export{};

package/dist/tasks/quick-compose/validator.d.ts

@@ -0,0 +1,7 @@
+import { ValidationResult } from "../ai-loop.js";
+import { QuickComposeResult } from "./types.js";
+
+//#region src/tasks/quick-compose/validator.d.ts
+declare function validateQuickComposeResponse(responseText: string, totalHunks: number, mode?: 'commits' | 'branches', includePartitions?: boolean, existingBranchNames?: Set<string>): ValidationResult<QuickComposeResult>;
+//#endregion
+export { validateQuickComposeResponse };

package/dist/tasks/quick-compose/validator.js

@@ -0,0 +1,25 @@
+import{extractOutputTag as e}from"../ai-loop.js";import{quickComposeResultSchema as t}from"./schema.js";function n(n,s,c=`branches`,l=!1,u){try{let d=e(n);if(!d)return a([`No <output> tag found in response`],o(c,l));let f=JSON.parse(d),p=t.safeParse(f);if(!p.success)return a(p.error.issues.map(e=>`${e.path.join(`.`)}: ${e.message}`),o(c,l));let m=p.data,h=new Set,g=new Set,_=new Set,v=[],y=new Set,b=[],x=[],S=[];for(let e of m.branches){if(h.has(e.id))return a([`Duplicate branch ID: '${e.id}'`],o(c,l));if(h.add(e.id),c===`branches`&&e.name.length===0)return a([`Branch '${e.id}': missing or empty 'name'`],o(c,l));if(c===`branches`&&e.name.length>0){if(g.has(e.name))return a([`Duplicate branch name: '${e.name}'`],`Multiple branches use the name '${e.name}'. Each branch must have a unique name. Please rename one of them.`);if(g.add(e.name),u?.has(e.name))return a([`Branch name '${e.name}' already exists in the repository`],`The branch name '${e.name}' already exists in the repository. Please choose a different name for branch '${e.id}'.`)}let t=[],n=new Set;for(let r of e.commits){y.has(r.id)&&b.push(r.id),y.add(r.id),n.add(r.id);let e=[];for(let t of r.hunks)_.has(t)&&v.push(t),_.add(t),e.push(t);e.length===0&&x.push(r.id),t.push({id:r.id,message:r.message,explanation:r.explanation,hunkIndices:e})}let s=new Set(e.orderedCommitIds);if(s.size!==e.orderedCommitIds.length)return a([`Branch '${e.id}': orderedCommitIds contains duplicates`],`The orderedCommitIds list for branch '${e.id}' contains duplicates. Each commit ID must appear exactly once.`);let d=[...n].filter(e=>!s.has(e)),f=e.orderedCommitIds.filter(e=>!n.has(e));if(d.length>0)return a([`Branch '${e.id}': orderedCommitIds is missing commits: ${d.join(`, `)}`],`The orderedCommitIds for branch '${e.id}' must include every commit. Missing: ${d.join(`, `)}`);if(f.length>0)return a([`Branch '${e.id}': orderedCommitIds references unknown commits: ${f.join(`, `)}`],`The orderedCommitIds for branch '${e.id}' references commits that don't exist. Unknown: ${f.join(`, `)}`);let p=e.partitions?[...e.partitions]:void 0;if(p){let t=new Set,n=[];for(let r=0;r<p.length;r++){let o=p[r];if(!i(o.branchName))return a([`Branch '${e.id}', partition ${r}: '${o.branchName}' is not a valid git branch name`],`The branch name '${o.branchName}' is invalid. Git branch names cannot contain spaces, '..', '~', '^', ':', '\\', or end with '.lock'. Please provide a valid name.`);if(t.has(o.branchName))return a([`Branch '${e.id}': duplicate partition name '${o.branchName}'`],`Multiple partitions use the branch name '${o.branchName}'. Each must be unique.`);if(t.add(o.branchName),u?.has(o.branchName))return a([`Partition branch name '${o.branchName}' already exists in the repository`],`The branch name '${o.branchName}' already exists in the repository. Please choose a different name.`);for(let e of o.commitIds)n.push(e)}let o=new Set(n),c=e.orderedCommitIds.filter(e=>!o.has(e)),l=n.filter(e=>!s.has(e));if(c.length>0)return a([`Branch '${e.id}': partition is missing commits: ${c.join(`, `)}`],`All commits must be assigned to a partition. Missing: ${c.join(`, `)}`);if(l.length>0)return a([`Branch '${e.id}': partition references unknown commits: ${l.join(`, `)}`],`Partition references unknown commits: ${l.join(`, `)}`);if(!r(p,e.orderedCommitIds))return a([`Branch '${e.id}': partitions are not contiguous`],`Each partition must contain a contiguous range of commits in the ordered list. Please regroup into contiguous ranges.`)}S.push({id:e.id,name:e.name,title:e.title,description:e.description,commits:t,orderedCommitIds:e.orderedCommitIds,partitions:p})}if(b.length>0)return a([`Duplicate commit IDs: ${b.join(`, `)}`],`Some commit IDs appear multiple times. Each must be unique.\n\nDuplicates: ${b.join(`, `)}`);if(x.length>0)return a([`Empty commits (no hunks assigned): ${x.join(`, `)}`],`Every commit must contain at least one hunk. These commits have an empty \`hunks\` array: ${x.join(`, `)}.
+
+Either assign at least one hunk to each of these commits, or remove them entirely. If a commit's purpose is already covered by another commit, remove the duplicate. If a commit is supposed to cover specific hunks, assign those hunk indices to it. Every hunk index still needs to appear in exactly one commit.`);if(v.length>0)return a([`Duplicate hunks: ${v.join(`, `)}`],`Some hunks appear in multiple commits. Each hunk can only be used once.\n\nDuplicate hunks: ${v.join(`, `)}`);let C=new Set(Array.from({length:s},(e,t)=>t)),w=[...C].filter(e=>!_.has(e)),T=[..._].filter(e=>!C.has(e));return w.length>0?a([`Missing hunks: ${w.join(`, `)}`],`Some hunks are not assigned to any commit. All hunks must be included.\n\nMissing: ${w.join(`, `)}`):T.length>0?a([`Extra hunks: ${T.join(`, `)}`],`Some hunks in your response don't exist in the input.\n\nExtra: ${T.join(`, `)}`):{valid:!0,result:{branches:S,rationale:m.rationale}}}catch{return a([`Failed to parse response as valid JSON`],o(c,l))}}function r(e,t){let n=new Map(t.map((e,t)=>[e,t])),r=0;for(let t of e)for(let e of t.commitIds){let t=n.get(e);if(t===void 0||t!==r)return!1;r++}return r===t.length}function i(e){return e.startsWith(`-`)||e.startsWith(`.`)||e.endsWith(`.lock`)||e.endsWith(`.`)||e.endsWith(`/`)||e.includes(`..`)||e.includes(`~`)||e.includes(`^`)||e.includes(`:`)||e.includes(`\\`)||e.includes(` `)||e.includes(`?`)||e.includes(`*`)||e.includes(`[`)||e.includes(`@{`)?!1:e.length>0}function a(e,t){return{valid:!1,errors:e,retryFeedback:t}}function o(e,t){return`Your response has an invalid structure. Please return JSON inside <output> tags:
+<output>
+{
+  "branches": [
+    {
+      "id": ${e===`commits`?`"default"`:`"[branch id]"`},
+      "name": ${e===`commits`?`""`:`"[branch name]"`},
+      "title": ${e===`commits`?`""`:`"[short PR title]"`},
+      "description": ${e===`commits`?`""`:`"[branch description]"`},
+      "commits": [
+        { "id": "[commit id]", "message": "[message]", "explanation": "[explanation]", "hunks": [0, 1, 2] }
+      ],
+      "orderedCommitIds": ["[commit-id-1]", "[commit-id-2]"]${t?`,
+      "partitions": [
+        { "branchName": "[name]", "title": "[title]", "description": "[desc]", "commitIds": ["[id1]", "[id2]"] }
+      ]`:``}
+    }
+  ],
+  "rationale": "[explanation]"
+}
+</output>
+
+Return only the <output> tag and no other text.`}export{n as validateQuickComposeResponse};

package/dist/tasks/session.d.ts

@@ -0,0 +1,22 @@
+import { AiSession } from "../ai/session.js";
+import { AnalysisResult } from "./analyze/types.js";
+import { GroupingResult } from "./group/types.js";
+import { OrderingResult } from "./order/types.js";
+import { QuickComposeResult } from "./quick-compose/types.js";
+import { PartitionResult } from "./partition/types.js";
+
+//#region src/tasks/session.d.ts
+interface ComposeSession extends AiSession {
+  completedSteps: {
+    analyze?: AnalysisResult;
+    group?: GroupingResult;
+    composeGroup?: GroupingResult;
+    quickCompose?: QuickComposeResult;
+    order?: OrderingResult;
+    partition?: PartitionResult;
+  };
+}
+declare function createComposeSession(systemPrompt: string): ComposeSession;
+declare function withCompletedStep<K extends keyof ComposeSession['completedSteps']>(aiSession: AiSession, incomingSteps: ComposeSession['completedSteps'], key: K, value: NonNullable<ComposeSession['completedSteps'][K]>): ComposeSession;
+//#endregion
+export { ComposeSession, createComposeSession, withCompletedStep };

package/dist/tasks/session.js

@@ -0,0 +1 @@
+function e(e){return{messages:[],systemPrompt:e,completedSteps:{}}}function t(e,t,n,r){return{...e,completedSteps:{...t,[n]:r}}}export{e as createComposeSession,t as withCompletedStep};