@gitkraken/compose-tools 0.1.0

package/dist/tasks/types.d.ts

@@ -0,0 +1,101 @@
+//#region src/tasks/types.d.ts
+interface ComposeHunk {
+  index: number;
+  fileName: string;
+  diffHeader: string;
+  hunkHeader: string;
+  content: string;
+  additions: number;
+  deletions: number;
+  source: 'staged' | 'unstaged' | 'untracked' | 'branch';
+  sourceCommitSha?: string;
+  isRename?: boolean;
+  originalFileName?: string;
+  isBinary?: boolean;
+  /** Full binary patch block (base85-encoded). Excluded from AI context, used only by patch builder. */
+  binaryPatchData?: string;
+  /**
+   * Original author of this hunk (e.g. when the hunk came from a branch source
+   * and the commit carrying it was authored by someone specific). The apply
+   * phase aggregates per-commit hunks through an attribution strategy to choose
+   * the commit's primary author and Co-authored-by trailers.
+   *
+   * `date` is the commit's author date when known — used by consumers for UI
+   * display and, for the commit created by the apply path, as `GIT_AUTHOR_DATE`.
+   */
+  author?: {
+    name: string;
+    email: string;
+    date?: Date;
+  };
+  /**
+   * Additional authors attached to this hunk (for merge commits or the AI's
+   * attribution hints). Combined with `author` from all hunks in a commit to
+   * produce the final Co-authored-by trailer list.
+   */
+  coAuthors?: {
+    name: string;
+    email: string;
+    date?: Date;
+  }[];
+}
+interface CommitSuggestion {
+  id: string;
+  message: string;
+  explanation: string;
+  hunkIndices: number[];
+}
+interface CommitDetail {
+  sha: string;
+  message: string;
+  diff: string;
+  filesChanged: string[];
+}
+interface BranchGroup {
+  id: string;
+  name: string;
+  title: string;
+  description: string;
+  commits: CommitSuggestion[];
+}
+interface BranchOrdering {
+  branchId: string;
+  orderedCommitIds: string[];
+}
+interface BranchPartition {
+  branchName: string;
+  title: string;
+  description: string;
+  commitIds: string[];
+}
+/**
+ * Identifier for each AI task the library can run. Matches the `taskName`
+ * value passed to `runAiLoop` and the phase label surfaced on {@link
+ * import('../ai/types.js').PhaseDetail}.
+ */
+type ComposeTaskName = 'analyze' | 'group' | 'compose-group' | 'order' | 'partition' | 'quick-compose';
+/**
+ * Per-task prompt override. Every field is optional; undefined fields fall
+ * back to the library's built-in prompt.
+ *
+ * - `system`: replaces the task's system prompt entirely. The caller is
+ *   responsible for preserving any library-required constraints (output
+ *   format, validation schemas, etc.) the built-in prompt encodes — the
+ *   library's validators still run against whatever the model produces.
+ * - `userPrefix`: prepended to the task's user prompt, separated by a
+ *   blank line. Use for context the AI should see before the task body.
+ * - `userSuffix`: appended to the task's user prompt, separated by a
+ *   blank line. Use for late-binding instructions or reminders.
+ */
+interface PromptOverride {
+  system?: string;
+  userPrefix?: string;
+  userSuffix?: string;
+}
+/**
+ * Helper that applies a {@link PromptOverride} to a built user prompt.
+ * Returns the original prompt when no override exists.
+ */
+declare function applyUserPromptOverride(prompt: string, override?: PromptOverride): string;
+//#endregion
+export { BranchGroup, BranchOrdering, BranchPartition, CommitDetail, CommitSuggestion, ComposeHunk, ComposeTaskName, PromptOverride, applyUserPromptOverride };

package/dist/tasks/types.js

@@ -0,0 +1,3 @@
+function e(e,t){if(!t?.userPrefix&&!t?.userSuffix)return e;let n=[];return t.userPrefix&&n.push(t.userPrefix),n.push(e),t.userSuffix&&n.push(t.userSuffix),n.join(`
+
+`)}export{e as applyUserPromptOverride};

package/dist/workflows/compose.d.ts

@@ -0,0 +1,371 @@
+import { PhaseDetail, ProgressEvent, TokenUsage } from "../ai/types.js";
+import { ComposeGitPort, SigningConfig } from "../ports/git.js";
+import { BranchPartition, CommitSuggestion, ComposeHunk, ComposeTaskName, PromptOverride } from "../tasks/types.js";
+import { ConventionDescriptor } from "../git/utils/conventions.js";
+import { OnAfterModelCall, OnBeforeModelCall, OnBeforePrompt } from "../tasks/ai-loop.js";
+import { AnalysisResult } from "../tasks/analyze/types.js";
+import { GroupingResult, GroupingStrategy } from "../tasks/group/types.js";
+import { OrderingResult } from "../tasks/order/types.js";
+import { ComposeSession } from "../tasks/session.js";
+import { PartitionStrategy } from "../tasks/partition/types.js";
+import { ComposeContext, ComposeSource, ComposeTarget } from "./types.js";
+import { SafetySnapshot } from "../git/types.js";
+import { ComposeBranchPlan } from "../git/apply-target.js";
+import { AiModelPort, UndoId } from "@gitkraken/shared-tools";
+
+//#region src/workflows/compose.d.ts
+/**
+ * Pure-planning input — runs the AI pipeline and returns a {@link ComposePlan}
+ * without mutating the repository. Same shape as {@link ComposeInput} minus
+ * `applyPlan` and `onBeforeApply`.
+ */
+interface ComposePlanInput {
+  git: ComposeGitPort;
+  model: AiModelPort;
+  source?: ComposeSource;
+  target?: ComposeTarget;
+  context?: ComposeContext;
+  instructions?: string;
+  conventions?: ConventionDescriptor;
+  conventionAuthor?: string;
+  strategy?: ComposeStrategy;
+  depth?: ComposeDepth;
+  maxRetries?: number;
+  onProgress?: (event: ComposeProgressEvent) => void;
+  signal?: AbortSignal;
+  onBeforeModelCall?: OnBeforeModelCall;
+  onAfterModelCall?: OnAfterModelCall;
+  onBeforePrompt?: OnBeforePrompt;
+  /** See {@link ComposeInput.hunkFilter}. */
+  hunkFilter?: ComposeInput['hunkFilter'];
+  /** See {@link ComposeInput.session}. */
+  session?: ComposeSession;
+  /** See {@link ComposeInput.promptOverrides}. */
+  promptOverrides?: ComposeInput['promptOverrides'];
+}
+/** Result of {@link composePlan}. Contains everything needed to later call {@link applyComposePlan}. */
+interface ComposePlanResult {
+  plan: ComposePlan;
+  snapshot: SafetySnapshot;
+  source: ComposeResult['source'];
+  session: ComposeSession;
+  usage: TokenUsage;
+  phases: PhaseDetail[];
+  /** See {@link ComposeResult.feedbackTargetCallId}. */
+  feedbackTargetCallId?: string;
+  /** See {@link ComposeResult.hunksFilteredCount}. */
+  hunksFilteredCount?: number;
+}
+/** Pure-apply input — takes a previously computed plan and writes it to the repository. */
+interface ApplyComposePlanInput {
+  git: ComposeGitPort;
+  applyPlan: ComposeApplyPlan;
+  source?: ComposeSource;
+  target?: ComposeTarget;
+  onProgress?: (event: ComposeProgressEvent) => void;
+  signal?: AbortSignal;
+  /** GPG signing config for produced commits. See {@link ComposeInput.signing}. */
+  signing?: SigningConfig;
+  /** How to pick the primary author for each commit. See {@link ComposeInput.authorAttribution}. */
+  authorAttribution?: ComposeInput['authorAttribution'];
+}
+/** Result of {@link applyComposePlan}. */
+interface ApplyComposePlanResult {
+  commitShas?: Record<string, string>;
+  partitions?: BranchPartition[];
+  partitionGroups?: BranchPartition[][];
+  phases: PhaseDetail[];
+  undoId?: UndoId;
+}
+/** Controls how many AI pipeline steps run and how deeply each reasons. */
+type ComposeDepth = 'quick' | 'balanced' | 'deep';
+interface ComposeStrategy {
+  /** Controls branch splitting and commit granularity in the group step. */
+  grouping?: GroupingStrategy;
+  /** Controls how aggressively branches are subdivided into stacks in the partition step. */
+  partition?: PartitionStrategy;
+}
+/**
+ * A serializable bundle of everything needed to apply a previously computed plan.
+ *
+ * The `snapshot` field is a content-hash safety check — it ensures the working directory
+ * still matches what the plan was computed against. Distinct from the `preState` returned
+ * by {@link compose}, which is a state snapshot used to roll back the operation.
+ */
+interface ComposeApplyPlan {
+  plan: ComposePlan;
+  source: ComposeSource;
+  snapshot: SafetySnapshot;
+  target?: ComposeTarget;
+}
+interface ComposeInput {
+  git: ComposeGitPort;
+  /** AI model — required unless `applyPlan` is provided. */
+  model?: AiModelPort;
+  /** Apply a previously computed plan without re-running AI phases. When set, `model` is not needed. */
+  applyPlan?: ComposeApplyPlan;
+  source?: ComposeSource;
+  target?: ComposeTarget;
+  context?: ComposeContext;
+  instructions?: string;
+  conventions?: ConventionDescriptor;
+  conventionAuthor?: string;
+  /** Controls AI aggressiveness for splitting branches, commits, and partitions. */
+  strategy?: ComposeStrategy;
+  /** Controls AI pipeline depth. 'quick' = single AI call. 'balanced' = 2-3 calls (default). 'deep' = 4+ calls with full analysis. */
+  depth?: ComposeDepth;
+  maxRetries?: number;
+  onProgress?: (event: ComposeProgressEvent) => void;
+  onBeforeApply?: (plan: ComposePlan) => Promise<boolean>;
+  /**
+   * Optional cancellation signal. Forwarded to every AI call and every git operation.
+   * On abort, the workflow throws `WorkflowError('CANCELLED')`.
+   */
+  signal?: AbortSignal;
+  /**
+   * Called immediately before each model.generate invocation. Use for progress UI,
+   * telemetry, or correlation. The library doesn't interpret the result.
+   */
+  onBeforeModelCall?: OnBeforeModelCall;
+  /** Called after each model.generate invocation, on both success and error. */
+  onAfterModelCall?: OnAfterModelCall;
+  /**
+   * Gating hook called immediately before each model.generate call. Returning
+   * `false` aborts the workflow with `WorkflowError('CANCELLED')`. Use for
+   * large-prompt confirmations, cost warnings, org policy checks, etc.
+   */
+  onBeforePrompt?: OnBeforePrompt;
+  /**
+   * Called after source collection and before the AI pipeline runs. The
+   * returned hunks become the set the AI sees (and the set whose indices
+   * are referenced by the resulting plan). Use for AIIgnore globs, org
+   * policy filters, or any consumer-side hunk-level policy.
+   *
+   * The difference between the returned array's length and the input's is
+   * surfaced as {@link ComposeResult.hunksFilteredCount}. If the filter
+   * removes every hunk, the workflow throws `GitError('NO_CHANGES')` just
+   * like an empty collection.
+   *
+   * The filter MUST NOT mutate hunks in place or invent new indices — it
+   * can only drop entries. Remaining hunks keep their original `index`
+   * values so the plan still references the authoritative collection.
+   */
+  hunkFilter?: (hunks: ComposeHunk[]) => Promise<ComposeHunk[]> | ComposeHunk[];
+  /**
+   * Per-task prompt overrides, keyed by {@link ComposeTaskName}. Consumers with
+   * existing prompt template services (server-driven templates, provider-specific
+   * templates, org-tuned wording) use this to replace the library's default
+   * system prompt or decorate the user prompt without forking the task code.
+   *
+   * The library still runs the same validators against the model response, so a
+   * replacement `system` prompt has to preserve the output contract the task
+   * expects (JSON shape inside `<output>` tags, hunk index constraints, etc.).
+   */
+  promptOverrides?: Partial<Record<ComposeTaskName, PromptOverride>>;
+  /**
+   * Resume a prior workflow instead of running every AI phase from scratch.
+   *
+   * When provided, each AI task checks its own entry in `completedSteps`. If
+   * present, the task returns that cached result instead of invoking the
+   * model. Unblocks recovery paths (e.g. user declined a ToS confirmation
+   * between `analyze` and `group` — retry with the same session, analyze is
+   * skipped, group runs fresh) and supports CLI / MCP consumers that want to
+   * build plans incrementally.
+   *
+   * Each task checks only its own entry in `completedSteps`; entries belonging
+   * to steps the current depth doesn't run are ignored. A resumed task
+   * contributes no usage and no callIds — telemetry for that phase reflects
+   * the original run, not this one.
+   */
+  session?: ComposeSession;
+  /**
+   * GPG signing config for commits produced by the apply phase. Typically
+   * derived from `git config commit.gpgsign` + `user.signingkey`. When
+   * `enabled` is true, the library passes `-S` to `commit-tree` and sets
+   * `GIT_GPG_PROGRAM` env when `gpgProgram` is provided.
+   */
+  signing?: SigningConfig;
+  /**
+   * How to pick the primary author for each commit when its hunks come from
+   * multiple original authors (recompose / commit-range sources).
+   *
+   * - `'plurality'` (default): the author who owns the most hunks in the
+   *   commit wins; all other distinct authors become `Co-authored-by:` trailers.
+   * - `'first-hunk'`: use the first hunk's author; all other distinct authors
+   *   become `Co-authored-by:` trailers.
+   * - function: fully custom — consumer inspects the hunks and returns the
+   *   primary identity (or `undefined` to use the commit creator's identity).
+   *   Co-authors are still derived from the union of hunk authors minus the
+   *   returned primary.
+   *
+   * Ignored when no hunks have `author` set (e.g. workdir source).
+   */
+  authorAttribution?: 'plurality' | 'first-hunk' | ((hunks: ComposeHunk[]) => {
+    name: string;
+    email: string;
+  } | undefined);
+}
+interface ComposePlan {
+  analysis?: AnalysisResult;
+  grouping: GroupingResult;
+  ordering: OrderingResult;
+  branches: ComposeBranchPlan[];
+  allOrderedCommits: CommitSuggestion[];
+}
+/**
+ * Discriminated union of phase events emitted during compose/split/apply.
+ *
+ * Every event carries:
+ * - `message`: a default user-friendly label (e.g. "Analyzing changes…").
+ *   Consumers can use it directly or map to localized copy.
+ * - `weight`: a relative duration estimate. Useful for building a progress
+ *   bar where phases have different costs. Weights sum to roughly 100 across
+ *   a typical run; individual numbers are approximate and may be tuned over
+ *   library releases. Treat as a hint, not a promise.
+ * - `detail`/`event`: phase-specific extra info (git state, AI attempt, etc.).
+ */
+type ComposeProgressEvent = {
+  phase: 'collecting';
+  message: string;
+  weight: number;
+  detail?: string;
+} | {
+  phase: 'composing';
+  message: string;
+  weight: number;
+  event: ProgressEvent;
+} | {
+  phase: 'compose-grouping';
+  message: string;
+  weight: number;
+  event: ProgressEvent;
+} | {
+  phase: 'analyzing';
+  message: string;
+  weight: number;
+  event: ProgressEvent;
+} | {
+  phase: 'grouping';
+  message: string;
+  weight: number;
+  event: ProgressEvent;
+} | {
+  phase: 'ordering';
+  message: string;
+  weight: number;
+  event: ProgressEvent;
+} | {
+  phase: 'partitioning';
+  message: string;
+  weight: number;
+  branch: string;
+  event: ProgressEvent;
+} | {
+  phase: 'verifying';
+  message: string;
+  weight: number;
+  detail?: string;
+} | {
+  phase: 'applying';
+  message: string;
+  weight: number;
+  detail?: string;
+};
+/** Default messages and weights per phase. Exposed so consumers can override for localization. */
+declare const defaultPhaseMessages: Record<ComposeProgressEvent['phase'], {
+  message: string;
+  weight: number;
+}>;
+interface ComposeResult {
+  plan: ComposePlan;
+  /**
+   * Content-hash snapshot from the collection phase.
+   *
+   * Pass this back via {@link ComposeApplyPlan.snapshot} to apply the plan later — the
+   * apply path verifies the working directory still matches before re-running. Distinct
+   * from {@link undoId}, which is for rolling back.
+   */
+  snapshot: SafetySnapshot;
+  partitions?: BranchPartition[];
+  /** Partitions grouped by independent stack. Each inner array is one stack (root first, tip last). */
+  partitionGroups?: BranchPartition[][];
+  session: ComposeSession;
+  usage: TokenUsage;
+  phases: PhaseDetail[];
+  source: {
+    type: 'workdir' | 'branch';
+    hunks: ComposeHunk[];
+    commitMessages?: string[];
+    branchName?: string;
+    baseBranch?: string;
+  };
+  /**
+   * Size of the input the AI operated on. Useful for consumers building
+   * telemetry events — no need to recount hunks and lines from the source.
+   */
+  diffStats: {
+    fileCount: number;
+    hunkCount: number;
+    addedLines: number;
+    removedLines: number;
+  };
+  commitShas?: Record<string, string>;
+  /**
+   * Identifier for undoing this operation.
+   *
+   * Pass to {@link undoCompose} to reverse all git mutations this compose performed.
+   * Only set when changes were actually applied (not set when the user rejected
+   * the plan via `onBeforeApply`).
+   */
+  undoId?: UndoId;
+  /**
+   * Call ID of the "decision" model response for this workflow — the last
+   * validated response across all AI phases. Consumers that surface user
+   * feedback (thumbs up/down) stamp this ID on the feedback event so it maps
+   * back to a specific prompt/response. Undefined when no AI phases ran
+   * (e.g. {@link applyComposePlan} without prior {@link composePlan}).
+   */
+  feedbackTargetCallId?: string;
+  /**
+   * Number of hunks the consumer's `hunkFilter` removed before AI saw them.
+   * Undefined when no filter ran.
+   */
+  hunksFilteredCount?: number;
+}
+/**
+ * Compose code changes into a clean set of commits and branches.
+ *
+ * Three pipelines depending on `depth`:
+ * - `quick` — single AI call, output order trusted (good for squashed diffs)
+ * - `balanced` (default) — compose-group + order, optional analysis included in the prompt
+ * - `deep` — separate analyze, group, order, partition steps with rich reasoning
+ *
+ * Returns a {@link ComposeResult} with an `undoId` — pass it to {@link undoCompose}
+ * to reverse all git mutations. The undo manifest is persisted in the git object
+ * database and survives process restarts.
+ *
+ * Caller is responsible for the `model` lifecycle. If `applyPlan` is provided, the AI
+ * phases are skipped and the previously computed plan is re-applied; the workdir
+ * snapshot in the plan is verified before applying.
+ */
+declare function compose(input: ComposeInput): Promise<ComposeResult>;
+/**
+ * Run the AI pipeline without mutating the repository.
+ *
+ * Returns a plan + snapshot that can be reviewed, edited, and later handed to
+ * {@link applyComposePlan}. This is the two-phase entry point — ideal for
+ * consumers whose UX lets the user edit the plan before committing.
+ *
+ * For single-shot "plan and apply in one go", use {@link compose} directly.
+ */
+declare function composePlan(input: ComposePlanInput): Promise<ComposePlanResult>;
+/**
+ * Apply a previously computed plan (from {@link composePlan}) to the repository.
+ *
+ * Verifies the snapshot against the current workdir before applying — if the
+ * subsets the plan touches have drifted, throws `WorkflowError('SAFETY_CHECK_FAILED')`.
+ * On success, returns an `undoId` that {@link undoCompose} can reverse.
+ */
+declare function applyComposePlan(input: ApplyComposePlanInput): Promise<ApplyComposePlanResult>;
+//#endregion
+export { ApplyComposePlanInput, ApplyComposePlanResult, ComposeApplyPlan, type ComposeBranchPlan, type ComposeContext, ComposeDepth, ComposeInput, ComposePlan, ComposePlanInput, ComposePlanResult, ComposeProgressEvent, ComposeResult, type ComposeSource, ComposeStrategy, type ComposeTarget, applyComposePlan, compose, composePlan, defaultPhaseMessages };

package/dist/workflows/compose.js

@@ -0,0 +1,2 @@
+import{WorkflowError as e,WorkflowInputError as t}from"../errors/workflow.js";import{throwIfCancelled as n}from"../cancellation.js";import{GitError as r}from"../errors/git.js";import{addUsage as i,emptyUsage as a}from"../ai/types.js";import{analyze as o}from"../tasks/analyze/analyze.js";import{composeGroup as s}from"../tasks/compose-group/compose-group.js";import{group as c}from"../tasks/group/group.js";import{order as l}from"../tasks/order/order.js";import{partition as u}from"../tasks/partition/partition.js";import{applyPatchToIndex as d,diffTree as f,forEachRef as p,readTree as m,revParse as h,writeTree as g}from"../git/port-dispatch.js";import{buildPatchForCommit as _}from"../git/utils/patch-builder.js";import{sha256 as v}from"../git/utils/crypto.js";import{collectFromSource as y}from"../git/diff-collector.js";import{verifySnapshot as b}from"../git/safety.js";import{applyToTarget as x}from"../git/apply-target.js";import{requireExec as S}from"../git/require-exec.js";import{extractConventions as C}from"../git/utils/conventions.js";import{randomUUID as w}from"node:crypto";import{unlinkSync as T}from"node:fs";import{tmpdir as E}from"node:os";import{join as D}from"node:path";import{UndoStore as O,capturePreOperationState as k,generateUndoId as A}from"@gitkraken/shared-tools";const j={collecting:{message:`Collecting changes…`,weight:5},composing:{message:`Composing commits…`,weight:40},"compose-grouping":{message:`Grouping changes into commits…`,weight:40},analyzing:{message:`Analyzing changes…`,weight:20},grouping:{message:`Grouping changes into commits…`,weight:25},ordering:{message:`Ordering commits…`,weight:15},partitioning:{message:`Subdividing branches…`,weight:20},verifying:{message:`Verifying…`,weight:5},applying:{message:`Applying to repository…`,weight:10}};async function M(i){if(!i.applyPlan&&!i.model)throw new t(`Either 'model' or 'applyPlan' must be provided`);if(i.applyPlan)return B(i);let{git:a,model:o,source:s={type:`workdir`},onProgress:c,onBeforeApply:l,signal:u}=i;n(u);let d=o,f=i.depth??`balanced`,p=i.target??G(s);q(s,p);let m=[];c?.({phase:`collecting`,...j.collecting});let h=Date.now(),g=await y(a,s,{signal:u});if(m.push({name:`collecting`,durationMs:Date.now()-h,attempts:1}),g.hunks.length===0)throw new r(`NO_CHANGES`,K(s));let{hunks:_,filteredCount:v}=await U(g.hunks,i.hunkFilter);if(_.length===0)throw new r(`NO_CHANGES`,K(s));let w=v!==void 0&&v>0?await W(a,g.snapshot,_,u):g.snapshot,T=await N(f,{hunks:_,collection:g,conventions:i.conventions??await C({git:a,author:i.conventionAuthor,signal:u}),existingBranchNames:await Y(a,u),groupMode:p.type===`auto`?`branches`:`commits`,target:p,model:d,instructions:i.instructions,context:i.context,strategy:i.strategy,maxRetries:i.maxRetries,onProgress:c,signal:u,onBeforeModelCall:i.onBeforeModelCall,onAfterModelCall:i.onAfterModelCall,onBeforePrompt:i.onBeforePrompt,session:i.session,promptOverrides:i.promptOverrides}),E={analysis:T.analysis,grouping:T.grouping,ordering:T.ordering,branches:T.branchPlans,allOrderedCommits:T.allOrderedCommits};if(m.push(...T.phases),l&&!await l(E))return{plan:E,snapshot:w,session:T.session,usage:T.usage,phases:m,source:{type:s.type===`branch`?`branch`:`workdir`,hunks:_,commitMessages:g.commitMessages,branchName:g.branchName,baseBranch:g.baseBranch},diffStats:V(_),feedbackTargetCallId:H(m),hunksFilteredCount:v};let D=await k(S(a,`capturing pre-operation state`),{signal:u});c?.({phase:`verifying`,...j.verifying});let O=Date.now(),A=await b(a,g.snapshot,{includeUnstaged:s.type===`workdir`&&!s.stagedOnly,includeUntracked:g.untrackedIncluded,signal:u});if(!A.valid)throw new e(`SAFETY_CHECK_FAILED`,`Safety check failed: ${A.error}`);m.push({name:`verifying`,durationMs:Date.now()-O,attempts:1}),c?.({phase:`applying`,...j.applying});let M=Date.now(),P=await x({git:a,target:p,branchPlans:T.branchPlans,allOrderedCommits:T.allOrderedCommits,hunks:g.hunks,snapshot:w,collection:g,signal:u,signing:i.signing,authorAttribution:i.authorAttribution});m.push({name:`applying`,durationMs:Date.now()-M,attempts:1});let F=await X(a,D,P.mutations,p,s,u);return{plan:E,snapshot:w,partitions:P.partitions,partitionGroups:P.partitionGroups,session:T.session,usage:T.usage,phases:m,source:{type:s.type===`branch`?`branch`:`workdir`,hunks:_,commitMessages:g.commitMessages,branchName:g.branchName,baseBranch:g.baseBranch},diffStats:V(_),commitShas:P.commitShas,undoId:F,feedbackTargetCallId:H(m),hunksFilteredCount:v}}function N(e,t){switch(e){case`quick`:return P(t);case`balanced`:return F(t);case`deep`:return L(t)}}async function P(e){return I(e,{lightweight:!0,skipOrder:!0})}async function F(e){return I(e,{includeAnalysis:!0})}async function I(e,t){let{hunks:r,collection:o,conventions:c,existingBranchNames:d,groupMode:f,target:p,model:m,instructions:h,context:g,strategy:_,maxRetries:v,onProgress:y,signal:b,onBeforeModelCall:x,onAfterModelCall:S,onBeforePrompt:C}=e;n(b);let w=a(),T=[],E=await s({hunks:r,commitMessages:o.commitMessages,commitOrder:o.commitOrder,branchName:o.branchName,baseBranch:o.baseBranch,issueUrl:g?.issueUrl,pullRequestUrl:g?.pullRequestUrl,instructions:h,conventions:c,mode:f,strategy:_?.grouping,existingBranchNames:f===`branches`?d:void 0,includeAnalysis:t.includeAnalysis,lightweight:t.lightweight,condensed:t.condensed,model:m,session:e.session,maxRetries:v,onProgress:e=>y?.({phase:`compose-grouping`,...j[`compose-grouping`],event:e}),signal:b,onBeforeModelCall:x,onAfterModelCall:S,onBeforePrompt:C,promptOverride:e.promptOverrides?.[`compose-group`]});E.usage&&i(w,E.usage),T.push({name:`compose-grouping`,durationMs:E.durationMs,attempts:E.attempts,usage:E.usage,callIds:E.callIds});let D=E.session,O,k;if(t.skipOrder)O=E.result.branches.map(e=>({branchGroup:e,orderedCommitIds:e.commits.map(e=>e.id)})),k={branches:O.map(e=>({branchId:e.branchGroup.id,orderedCommitIds:e.orderedCommitIds})),rationale:``};else{let t=await l({branches:E.result.branches,hunks:r,instructions:h,model:m,session:E.session,maxRetries:v,onProgress:e=>y?.({phase:`ordering`,...j.ordering,event:e}),signal:b,onBeforeModelCall:x,onAfterModelCall:S,onBeforePrompt:C,promptOverride:e.promptOverrides?.order});t.usage&&i(w,t.usage),T.push({name:`ordering`,durationMs:t.durationMs,attempts:t.attempts,usage:t.usage,callIds:t.callIds}),D=t.session,k=t.result,O=E.result.branches.map(e=>({branchGroup:e,orderedCommitIds:k.branches.find(t=>t.branchId===e.id)?.orderedCommitIds??e.commits.map(e=>e.id)}))}if(p.type===`auto`){let t=new Set(d);for(let e of E.result.branches)e.name&&t.add(e.name);for(let n of O){let r=await u({commits:J(n.branchGroup,n.orderedCommitIds),orderedCommitIds:n.orderedCommitIds,sourceBranchName:n.branchGroup.name,instructions:h,conventions:c,strategy:_?.partition,existingBranchNames:t,model:m,maxRetries:v,onProgress:e=>y?.({phase:`partitioning`,...j.partitioning,branch:n.branchGroup.name,event:e}),signal:b,onBeforeModelCall:x,onAfterModelCall:S,onBeforePrompt:C,promptOverride:e.promptOverrides?.partition});r.usage&&i(w,r.usage),T.push({name:`partitioning:${n.branchGroup.name}`,durationMs:r.durationMs,attempts:r.attempts,usage:r.usage,callIds:r.callIds}),n.partitioning=r.result,D=r.session;for(let e of r.result.partitions)t.add(e.branchName)}}let A=O.flatMap(e=>J(e.branchGroup,e.orderedCommitIds));return{analysis:void 0,grouping:E.result,ordering:k,branchPlans:O,allOrderedCommits:A,session:D,usage:w,phases:T}}async function L(e){let{hunks:t,collection:r,conventions:s,existingBranchNames:d,groupMode:f,target:p,model:m,instructions:h,context:g,strategy:_,maxRetries:v,onProgress:y,signal:b,onBeforeModelCall:x,onAfterModelCall:S,onBeforePrompt:C}=e;n(b);let w=a(),T=[],E=await o({hunks:t,commitMessages:r.commitMessages,commitOrder:r.commitOrder,branchName:r.branchName,baseBranch:r.baseBranch,issueUrl:g?.issueUrl,pullRequestUrl:g?.pullRequestUrl,instructions:h,model:m,session:e.session,maxRetries:v,onProgress:e=>y?.({phase:`analyzing`,...j.analyzing,event:e}),signal:b,onBeforeModelCall:x,onAfterModelCall:S,onBeforePrompt:C,promptOverride:e.promptOverrides?.analyze});E.usage&&i(w,E.usage),T.push({name:`analyzing`,durationMs:E.durationMs,attempts:E.attempts,usage:E.usage,callIds:E.callIds});let D=await c({hunks:t,commitMessages:r.commitMessages,instructions:h,conventions:s,mode:f,strategy:_?.grouping,existingBranchNames:f===`branches`?d:void 0,model:m,session:E.session,maxRetries:v,onProgress:e=>y?.({phase:`grouping`,...j.grouping,event:e}),signal:b,onBeforeModelCall:x,onAfterModelCall:S,onBeforePrompt:C,promptOverride:e.promptOverrides?.group});D.usage&&i(w,D.usage),T.push({name:`grouping`,durationMs:D.durationMs,attempts:D.attempts,usage:D.usage,callIds:D.callIds});let O=await l({branches:D.result.branches,hunks:t,instructions:h,model:m,session:D.session,maxRetries:v,onProgress:e=>y?.({phase:`ordering`,...j.ordering,event:e}),signal:b,onBeforeModelCall:x,onAfterModelCall:S,onBeforePrompt:C,promptOverride:e.promptOverrides?.order});O.usage&&i(w,O.usage),T.push({name:`ordering`,durationMs:O.durationMs,attempts:O.attempts,usage:O.usage,callIds:O.callIds});let k=D.result.branches.map(e=>({branchGroup:e,orderedCommitIds:O.result.branches.find(t=>t.branchId===e.id)?.orderedCommitIds??e.commits.map(e=>e.id)})),A=O.session;if(p.type===`auto`){let t=new Set(d);for(let e of D.result.branches)e.name&&t.add(e.name);for(let n of k){let r=await u({commits:J(n.branchGroup,n.orderedCommitIds),orderedCommitIds:n.orderedCommitIds,sourceBranchName:n.branchGroup.name,instructions:h,conventions:s,strategy:_?.partition,existingBranchNames:t,model:m,maxRetries:v,onProgress:e=>y?.({phase:`partitioning`,...j.partitioning,branch:n.branchGroup.name,event:e}),signal:b,onBeforeModelCall:x,onAfterModelCall:S,onBeforePrompt:C,promptOverride:e.promptOverrides?.partition});r.usage&&i(w,r.usage),T.push({name:`partitioning:${n.branchGroup.name}`,durationMs:r.durationMs,attempts:r.attempts,usage:r.usage,callIds:r.callIds}),n.partitioning=r.result,A=r.session;for(let e of r.result.partitions)t.add(e.branchName)}}let M=k.flatMap(e=>J(e.branchGroup,e.orderedCommitIds));return{analysis:E.result,grouping:D.result,ordering:O.result,branchPlans:k,allOrderedCommits:M,session:A,usage:w,phases:T}}async function R(e){let t=await M({...e,onBeforeApply:async()=>!1});return{plan:t.plan,snapshot:t.snapshot,source:t.source,session:t.session,usage:t.usage,phases:t.phases,feedbackTargetCallId:t.feedbackTargetCallId,hunksFilteredCount:t.hunksFilteredCount}}async function z(e){let t=await M({git:e.git,applyPlan:e.applyPlan,source:e.source,target:e.target,onProgress:e.onProgress,signal:e.signal,signing:e.signing,authorAttribution:e.authorAttribution});return{commitShas:t.commitShas,partitions:t.partitions,partitionGroups:t.partitionGroups,phases:t.phases,undoId:t.undoId}}async function B(t){let{git:i,applyPlan:o,onProgress:s,signal:c}=t;n(c);let{plan:l,snapshot:u,source:d}=o,f=t.source??d,p=t.target??o?.target??G(f);q(f,p);let m=await k(S(i,`capturing pre-operation state`),{signal:c}),h=[];s?.({phase:`collecting`,...j.collecting});let g=Date.now(),_=await y(i,f,{signal:c});if(h.push({name:`collecting`,durationMs:Date.now()-g,attempts:1}),_.hunks.length===0)throw new r(`NO_CHANGES`,K(f));if(_.snapshot.diffHash!==u.diffHash)throw new e(`SAFETY_CHECK_FAILED`,`Working directory has changed since the plan was created. Re-run compose to generate a new plan.`);s?.({phase:`verifying`,...j.verifying});let v=Date.now(),C=await b(i,_.snapshot,{includeUnstaged:f.type===`workdir`&&!f.stagedOnly,includeUntracked:_.untrackedIncluded,signal:c});if(!C.valid)throw new e(`SAFETY_CHECK_FAILED`,`Safety check failed: ${C.error}`);h.push({name:`verifying`,durationMs:Date.now()-v,attempts:1}),s?.({phase:`applying`,...j.applying});let w=Date.now(),T=await x({git:i,target:p,branchPlans:l.branches,allOrderedCommits:l.allOrderedCommits,hunks:_.hunks,snapshot:_.snapshot,collection:_,signal:c,signing:t.signing,authorAttribution:t.authorAttribution});h.push({name:`applying`,durationMs:Date.now()-w,attempts:1});let E=await X(i,m,T.mutations,p,f,c);return{plan:l,snapshot:_.snapshot,partitions:T.partitions,partitionGroups:T.partitionGroups,session:{messages:[],systemPrompt:``,completedSteps:{}},usage:a(),phases:h,source:{type:f.type===`branch`?`branch`:`workdir`,hunks:_.hunks,commitMessages:_.commitMessages,branchName:_.branchName,baseBranch:_.baseBranch},diffStats:V(_.hunks),commitShas:T.commitShas,undoId:E}}function V(e){let t=new Set,n=0,r=0;for(let i of e)t.add(i.fileName),n+=i.additions,r+=i.deletions;return{fileCount:t.size,hunkCount:e.length,addedLines:n,removedLines:r}}function H(e){for(let t=e.length-1;t>=0;t--){let n=e[t].callIds;if(n&&n.length>0)return n[n.length-1]}}async function U(e,t){if(!t)return{hunks:e,filteredCount:void 0};let n=await t(e);return{hunks:n,filteredCount:e.length-n.length}}async function W(e,t,n,r){let i=D(E(),`compose-filtered-idx-${w()}`),a={GIT_INDEX_FILE:i};try{await m(e,t.headSha,{indexEnv:a,signal:r});let i=_(n);i.length>0&&await d(e,i,{indexEnv:a,signal:r});let o=await g(e,{indexEnv:a,signal:r}),s=await f(e,t.headSha,o,{signal:r});return{...t,diffHash:v(s)}}finally{try{T(i)}catch{}}}function G(e){return e.type===`branch`?{type:`branch-replace`}:e.type===`commit-range`?{type:`rewrite-range`,branch:e.branch,rangeFrom:e.from,rangeTo:e.to}:{type:`head`}}function K(e){switch(e.type){case`workdir`:return`No changes found in working directory`;case`branch`:return`No changes found on branch '${e.name}'`;case`commit-range`:return`No changes found in range '${e.from}..${e.to}' on branch '${e.branch}'`}}function q(e,n){if(n.type===`branch-replace`&&e.type!==`branch`)throw new t(`target 'branch-replace' requires source type 'branch'`);if(n.type===`rewrite-range`&&e.type!==`commit-range`&&e.type!==`branch`)throw new t(`target 'rewrite-range' requires source type 'commit-range' or 'branch'`)}function J(t,n){return n.map(n=>{let r=t.commits.find(e=>e.id===n);if(!r)throw new e(`INTERNAL`,`Commit ${n} not found in branch '${t.id}'`);return r})}async function Y(e,t){let n=(await p(e,{format:`%(refname:short)`,prefix:`refs/heads/`,signal:t})).trim().split(`
+`).filter(Boolean);return new Set(n)}async function X(e,t,n,r,i,a){let o=A(),s=n.createdBranches.length||1,c=`compose: ${s} branch${s===1?``:`es`} from ${i.type}`,l=[...n.movedBranches];if(r.type===`head`&&t.headBranch){let n=await h(e,`HEAD`,{signal:a});n!==t.headSha&&l.push({name:t.headBranch,previousSha:t.headSha,newSha:n})}let u={version:1,id:o,createdAt:new Date().toISOString(),description:c,previousHead:{sha:t.headSha,branch:t.headBranch},workdirClean:t.workdirClean,workdirBackupSha:t.workdirBackupSha,createdBranches:n.createdBranches,deletedBranches:n.deletedBranches,movedBranches:l};return await new O(S(e,`undo manifest persistence`)).save(u,{signal:a}),o}export{z as applyComposePlan,M as compose,R as composePlan,j as defaultPhaseMessages};

package/dist/workflows/split.d.ts

@@ -0,0 +1,80 @@
+import { PhaseDetail, ProgressEvent, TokenUsage } from "../ai/types.js";
+import { ComposeGitPort } from "../ports/git.js";
+import { BranchPartition, CommitDetail, ComposeHunk } from "../tasks/types.js";
+import { OnAfterModelCall, OnBeforeModelCall, OnBeforePrompt } from "../tasks/ai-loop.js";
+import { AnalysisResult } from "../tasks/analyze/types.js";
+import { ComposeSession } from "../tasks/session.js";
+import { PartitionResult } from "../tasks/partition/types.js";
+import { AiModelPort, UndoId } from "@gitkraken/shared-tools";
+
+//#region src/workflows/split.d.ts
+interface SplitInput {
+  git: ComposeGitPort;
+  model: AiModelPort;
+  branchName: string;
+  baseBranch?: string;
+  instructions?: string;
+  maxRetries?: number;
+  onProgress?: (event: SplitProgressEvent) => void;
+  onBeforeApply?: (plan: SplitPlan) => Promise<boolean>;
+  /**
+   * Optional cancellation signal. Forwarded to every AI call and every git operation.
+   * On abort, the workflow throws `WorkflowError('CANCELLED')`.
+   */
+  signal?: AbortSignal;
+  onBeforeModelCall?: OnBeforeModelCall;
+  onAfterModelCall?: OnAfterModelCall;
+  onBeforePrompt?: OnBeforePrompt;
+}
+interface SplitPlan {
+  analysis: AnalysisResult;
+  partitioning: PartitionResult;
+  commits: CommitDetail[];
+}
+type SplitProgressEvent = {
+  phase: 'collecting';
+  detail?: string;
+} | {
+  phase: 'analyzing';
+  event: ProgressEvent;
+} | {
+  phase: 'partitioning';
+  event: ProgressEvent;
+} | {
+  phase: 'applying';
+  detail?: string;
+};
+interface SplitResult {
+  plan: SplitPlan;
+  partitions: BranchPartition[];
+  session: ComposeSession;
+  usage: TokenUsage;
+  phases: PhaseDetail[];
+  source: {
+    type: 'branch';
+    hunks: ComposeHunk[];
+    commitMessages: string[];
+    branchName: string;
+    baseBranch: string;
+  };
+  /**
+   * Identifier for undoing this operation.
+   *
+   * Pass to {@link undoCompose} to reverse all git mutations this split performed.
+   * Only set when branches were actually created (not set when the user rejected
+   * the plan via `onBeforeApply` or there were too few partitions).
+   */
+  undoId?: UndoId;
+}
+/**
+ * Split a multi-commit branch into a stack of smaller branches.
+ *
+ * Analyzes the branch's diff, partitions commits into independent branches, and
+ * (when there's more than one partition) creates the new branches as a stack rooted
+ * at `baseBranch`. The original branch is deleted and replaced by the partition branches.
+ *
+ * Returns an `undoId` — pass to `undoCompose` from this package to reverse the split.
+ */
+declare function split(input: SplitInput): Promise<SplitResult>;
+//#endregion
+export { SplitInput, SplitPlan, SplitProgressEvent, SplitResult, split };

package/dist/workflows/split.js

@@ -0,0 +1,3 @@
+import{throwIfCancelled as e}from"../cancellation.js";import{GitError as t}from"../errors/git.js";import{addUsage as n,emptyUsage as r}from"../ai/types.js";import{analyze as i}from"../tasks/analyze/analyze.js";import{partition as a}from"../tasks/partition/partition.js";import{forEachRef as o}from"../git/port-dispatch.js";import{createStackedBranches as s}from"../git/apply-branches.js";import{parseUnifiedDiff as c}from"../git/utils/hunk-parser.js";import{collectCommitsForSplit as l}from"../git/diff-collector.js";import{requireExec as u}from"../git/require-exec.js";import{defaultPhaseMessages as d}from"./compose.js";import{UndoStore as f,capturePreOperationState as p,generateUndoId as m}from"@gitkraken/shared-tools";async function h(o){let{git:f,model:m,branchName:h,baseBranch:v=`main`,instructions:y,maxRetries:b,onProgress:x,onBeforeApply:S,signal:C,onBeforeModelCall:w,onAfterModelCall:T,onBeforePrompt:E}=o;e(C);let D=r(),O=[];x?.({phase:`collecting`,...d.collecting});let k=Date.now(),{commits:A,branchSha:j}=await l(f,h,v,C);if(O.push({name:`collecting`,durationMs:Date.now()-k,attempts:1}),A.length===0)throw new t(`NO_CHANGES`,`No commits found between '${v}' and '${h}'`);if(A.length<2)throw new t(`NO_CHANGES`,`Too few commits to split. A branch needs at least 2 commits.`);let M=c(A.map(e=>e.diff).join(`
+`),`branch`),N=A.map(e=>({id:e.sha,message:e.message,explanation:``,hunkIndices:[]})),P=await i({hunks:M,commitMessages:A.map(e=>e.message),commitOrder:A.map(e=>e.sha),branchName:h,baseBranch:v,instructions:y,model:m,maxRetries:b,onProgress:e=>x?.({phase:`analyzing`,...d.analyzing,event:e}),signal:C,onBeforeModelCall:w,onAfterModelCall:T,onBeforePrompt:E});P.usage&&n(D,P.usage),O.push({name:`analyzing`,durationMs:P.durationMs,attempts:P.attempts,usage:P.usage,callIds:P.callIds});let F=await a({commits:N,orderedCommitIds:A.map(e=>e.sha),sourceBranchName:h,baseBranch:v,instructions:y,existingBranchNames:await g(f,C),model:m,session:P.session,maxRetries:b,onProgress:e=>x?.({phase:`partitioning`,...d.partitioning,event:e}),signal:C,onBeforeModelCall:w,onAfterModelCall:T,onBeforePrompt:E});F.usage&&n(D,F.usage),O.push({name:`partitioning`,durationMs:F.durationMs,attempts:F.attempts,usage:F.usage,callIds:F.callIds});let I={type:`branch`,hunks:M,commitMessages:A.map(e=>e.message),branchName:h,baseBranch:v},L={analysis:P.result,partitioning:F.result,commits:A};if(F.result.partitions.length<=1||S&&!await S(L))return{plan:L,partitions:F.result.partitions,session:F.session,usage:D,phases:O,source:I};let R=await p(u(f,`capturing pre-operation state`),{signal:C});x?.({phase:`applying`,...d.applying});let z=Date.now();await s({git:f,partitions:F.result.partitions,originalBranchName:h,originalBranchSha:j,signal:C}),O.push({name:`applying`,durationMs:Date.now()-z,attempts:1});let B=await _(f,R,F.result.partitions,h,j,C);return{plan:L,partitions:F.result.partitions,session:F.session,usage:D,phases:O,source:I,undoId:B}}async function g(e,t){let n=(await o(e,{format:`%(refname:short)`,prefix:`refs/heads/`,signal:t})).trim().split(`
+`).filter(Boolean);return new Set(n)}async function _(e,t,n,r,i,a){let o=m(),s=n.map(e=>{let t=e.commitIds[e.commitIds.length-1];return{name:e.branchName,sha:t}}),c={version:1,id:o,createdAt:new Date().toISOString(),description:`split: ${n.length} branches from '${r}'`,previousHead:{sha:t.headSha,branch:t.headBranch},workdirClean:t.workdirClean,workdirBackupSha:t.workdirBackupSha,createdBranches:s,deletedBranches:[{name:r,sha:i}],movedBranches:[]};return await new f(u(e,`undo manifest persistence`)).save(c,{signal:a}),o}export{h as split};

package/dist/workflows/types.d.ts

@@ -0,0 +1,63 @@
+//#region src/workflows/types.d.ts
+/**
+ * Where compose pulls changes from.
+ *
+ * - `workdir`: collect from the working directory. Set `stagedOnly` to ignore unstaged changes,
+ *   `noUntracked` to ignore untracked files.
+ * - `branch`: collect the diff between `name` and `mergeTarget` (defaults to the upstream/base branch).
+ * - `commit-range`: collect from a contiguous range of commits on a branch, with per-hunk author
+ *   info derived from the owning commits. Used by "recompose this commit" / "recompose selected
+ *   commits" flows. `from` is exclusive (parent of first commit), `to` is inclusive. For a
+ *   single-commit recompose: `from = parent(commitSha)`, `to = commitSha`.
+ */
+type ComposeSource = {
+  type: 'workdir';
+  stagedOnly?: boolean;
+  noUntracked?: boolean;
+} | {
+  type: 'branch';
+  name: string;
+  mergeTarget?: string;
+} | {
+  type: 'commit-range';
+  branch: string;
+  from: string;
+  to: string;
+};
+/**
+ * Where compose writes the result.
+ *
+ * - `head`: commit onto the current branch.
+ * - `branch`: create or replace a single named branch.
+ * - `branch-replace`: replace the source branch (only valid when source is `branch`).
+ * - `auto`: create one branch per grouped concern, optionally subdividing into stacks.
+ * - `rewrite-range`: rewrite a contiguous commit range on `branch`, preserving commits
+ *   before `rangeFrom` (always) and commits after `rangeTo` (by cherry-pick when
+ *   `preserveSuffix`). Used with `source: 'commit-range'` for mid-branch recompose.
+ */
+type ComposeTarget = {
+  type: 'head';
+} | {
+  type: 'branch';
+  name: string;
+  preserveOriginal?: boolean;
+} | {
+  type: 'branch-replace';
+} | {
+  type: 'auto';
+  preserveOriginal?: boolean;
+} | {
+  type: 'rewrite-range';
+  branch: string;
+  rangeFrom: string;
+  rangeTo: string; /** Commits before `rangeFrom` always stay; this flag is reserved for future semantics. Default true. */
+  preservePrefix?: boolean; /** When true (default), cherry-pick `rangeTo..branch-tip` onto the new range tip. */
+  preserveSuffix?: boolean;
+};
+/** Optional context passed through to AI prompts (issue/PR URLs surface in commit messages). */
+interface ComposeContext {
+  issueUrl?: string;
+  pullRequestUrl?: string;
+}
+//#endregion
+export { ComposeContext, ComposeSource, ComposeTarget };

package/dist/workflows/types.js

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