@gitkraken/compose-tools 0.1.0

package/dist/git/utils/patch-builder.js

@@ -0,0 +1,2 @@
+function e(e){if(e.length===0)return``;let t=new Map;for(let n of e){let e=n.diffHeader,r=t.get(e);r||(r=[],t.set(e,r)),r.push(n)}let n=``;for(let[e,r]of t){let t=r.find(e=>e.isBinary);if(t?.binaryPatchData){let r=t.binaryPatchData.endsWith(`
+`)?t.binaryPatchData:`${t.binaryPatchData}\n`;n+=`${e}\n${r}`;continue}n+=`${e}\n`;let i=r.filter(e=>e.hunkHeader&&e.content&&!e.isRename);for(let e of i)n+=`${e.hunkHeader}\n${e.content}\n`}return n}export{e as buildPatchForCommit};

package/dist/git/utils/temp-index.d.ts

@@ -0,0 +1,6 @@
+import { ComposeGitPort } from "../../ports/git.js";
+
+//#region src/git/utils/temp-index.d.ts
+declare function withUntrackedInTempIndex<T>(git: ComposeGitPort, fn: (indexEnv: Record<string, string>) => Promise<T>, signal?: AbortSignal): Promise<T>;
+//#endregion
+export { withUntrackedInTempIndex };

package/dist/git/utils/temp-index.js

@@ -0,0 +1 @@
+import{ComposeGitPortMissingOpError as e}from"../../ports/git.js";import{gitDir as t,listUntracked as n,stageAll as r}from"../port-dispatch.js";import{randomUUID as i}from"node:crypto";import*as a from"node:fs";import*as o from"node:os";import*as s from"node:path";async function c(e,t,c){let u=await l(e,c),d=s.join(o.tmpdir(),`compose-tmp-idx-${i()}`);try{a.copyFileSync(u,d);let i={GIT_INDEX_FILE:d},o=await n(e,{signal:c});return o.length>0&&await r(e,{intentToAdd:!0,paths:o,indexEnv:i,signal:c}),await t(i)}finally{try{a.unlinkSync(d)}catch{}}}async function l(n,r){let i=await t(n,{signal:r});if(!i)throw new e(`gitDir`,`The temp-index helper needs to resolve the real .git/index path. Provide 'gitDir' (or 'exec').`);return s.join(i,`index`)}export{c as withUntrackedInTempIndex};

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { PhaseDetail, ProgressEvent, TokenUsage } from "./ai/types.js";
+import { AIError, AIErrorCode } from "./errors/ai.js";
+import { GitError, GitErrorCode } from "./errors/git.js";
+import { TaskInputError } from "./errors/task.js";
+import { WorkflowError, WorkflowErrorCode, WorkflowInputError } from "./errors/workflow.js";
+import { ApplyPatchOptions, CheckoutOptions, CleanOptions, CommitTreeOptions, ComposeGitOps, ComposeGitPort, ComposeGitPortMissingOpError, DeleteBranchOptions, DiffTreeOptions, ForEachRefOptions, GitCommitIdentity, IndexScopedOptions, LogOptions, OpOptions, SigningConfig, StageAllOptions, StashPushOptions, UpdateRefOptions } from "./ports/git.js";
+import { BranchGroup, BranchOrdering, BranchPartition, CommitDetail, CommitSuggestion, ComposeHunk, ComposeTaskName, PromptOverride } from "./tasks/types.js";
+import { ConventionDescriptor } from "./git/utils/conventions.js";
+import { AfterModelCallInfo, BeforeModelCallInfo, BeforePromptInfo, OnAfterModelCall, OnBeforeModelCall, OnBeforePrompt, estimatedCharactersPerToken } from "./tasks/ai-loop.js";
+import { AnalysisResult, AnalyzeInput, AnalyzeOutput, Concern, ConcernDependency, HunkAnnotation, HunkOrderingConstraint } from "./tasks/analyze/types.js";
+import { GroupInput, GroupOutput, GroupingResult, GroupingStrategy } from "./tasks/group/types.js";
+import { OrderInput, OrderOutput, OrderingResult } from "./tasks/order/types.js";
+import { QuickComposeInput, QuickComposeOutput, QuickComposeResult } from "./tasks/quick-compose/types.js";
+import { ComposeSession } from "./tasks/session.js";
+import { PartitionInput, PartitionOutput, PartitionResult, PartitionStrategy } from "./tasks/partition/types.js";
+import { ComposeContext, ComposeSource, ComposeTarget } from "./workflows/types.js";
+import { ComposeBranchPlan } from "./git/apply-target.js";
+import { analyze } from "./tasks/analyze/analyze.js";
+import { ComposeGroupInput, ComposeGroupOutput } from "./tasks/compose-group/types.js";
+import { composeGroup } from "./tasks/compose-group/compose-group.js";
+import { group } from "./tasks/group/group.js";
+import { order } from "./tasks/order/order.js";
+import { partition } from "./tasks/partition/partition.js";
+import { quickCompose } from "./tasks/quick-compose/quick-compose.js";
+import { ApplyComposePlanInput, ApplyComposePlanResult, ComposeApplyPlan, ComposeDepth, ComposeInput, ComposePlan, ComposePlanInput, ComposePlanResult, ComposeProgressEvent, ComposeResult, ComposeStrategy, applyComposePlan, compose, composePlan, defaultPhaseMessages } from "./workflows/compose.js";
+import { SplitInput, SplitPlan, SplitProgressEvent, SplitResult, split } from "./workflows/split.js";
+import { UndoComposeInput, ValidateUndoComposeInput, listUndoIds, undoCompose, validateUndoCompose } from "./workflows/undo.js";
+export { AIError, type AIErrorCode, type AfterModelCallInfo, type AnalysisResult, type AnalyzeInput, type AnalyzeOutput, type ApplyComposePlanInput, type ApplyComposePlanResult, type ApplyPatchOptions, type BeforeModelCallInfo, type BeforePromptInfo, type BranchGroup, type BranchOrdering, type BranchPartition, type CheckoutOptions, type CleanOptions, type CommitDetail, type CommitSuggestion, type CommitTreeOptions, type ComposeApplyPlan, type ComposeBranchPlan, type ComposeContext, type ComposeDepth, type ComposeGitOps, type ComposeGitPort, ComposeGitPortMissingOpError, type ComposeGroupInput, type ComposeGroupOutput, type ComposeHunk, type ComposeInput, type ComposePlan, type ComposePlanInput, type ComposePlanResult, type ComposeProgressEvent, type ComposeResult, type ComposeSession, type ComposeSource, type ComposeStrategy, type ComposeTarget, type ComposeTaskName, type Concern, type ConcernDependency, type ConventionDescriptor, type DeleteBranchOptions, type DiffTreeOptions, type ForEachRefOptions, type GitCommitIdentity, GitError, type GitErrorCode, type GroupInput, type GroupOutput, type GroupingResult, type GroupingStrategy, type HunkAnnotation, type HunkOrderingConstraint, type IndexScopedOptions, type LogOptions, type OnAfterModelCall, type OnBeforeModelCall, type OnBeforePrompt, type OpOptions, type OrderInput, type OrderOutput, type OrderingResult, type PartitionInput, type PartitionOutput, type PartitionResult, type PartitionStrategy, type PhaseDetail, type ProgressEvent, type PromptOverride, type QuickComposeInput, type QuickComposeOutput, type QuickComposeResult, type SigningConfig, type SplitInput, type SplitPlan, type SplitProgressEvent, type SplitResult, type StageAllOptions, type StashPushOptions, TaskInputError, type TokenUsage, type UndoComposeInput, type UpdateRefOptions, type ValidateUndoComposeInput, WorkflowError, type WorkflowErrorCode, WorkflowInputError, analyze, applyComposePlan, compose, composeGroup, composePlan, defaultPhaseMessages, estimatedCharactersPerToken, group, listUndoIds, order, partition, quickCompose, split, undoCompose, validateUndoCompose };

package/dist/index.js

@@ -0,0 +1 @@
+import{WorkflowError as e,WorkflowInputError as t}from"./errors/workflow.js";import{AIError as n}from"./errors/ai.js";import{GitError as r}from"./errors/git.js";import{TaskInputError as i}from"./errors/task.js";import{ComposeGitPortMissingOpError as a}from"./ports/git.js";import{estimatedCharactersPerToken as o}from"./tasks/ai-loop.js";import{analyze as s}from"./tasks/analyze/analyze.js";import{composeGroup as c}from"./tasks/compose-group/compose-group.js";import{group as l}from"./tasks/group/group.js";import{order as u}from"./tasks/order/order.js";import{partition as d}from"./tasks/partition/partition.js";import{quickCompose as f}from"./tasks/quick-compose/quick-compose.js";import{applyComposePlan as p,compose as m,composePlan as h,defaultPhaseMessages as g}from"./workflows/compose.js";import{split as _}from"./workflows/split.js";import{listUndoIds as v,undoCompose as y,validateUndoCompose as b}from"./workflows/undo.js";export{n as AIError,a as ComposeGitPortMissingOpError,r as GitError,i as TaskInputError,e as WorkflowError,t as WorkflowInputError,s as analyze,p as applyComposePlan,m as compose,c as composeGroup,h as composePlan,g as defaultPhaseMessages,o as estimatedCharactersPerToken,l as group,v as listUndoIds,u as order,d as partition,f as quickCompose,_ as split,y as undoCompose,b as validateUndoCompose};

package/dist/ports/git.d.ts

@@ -0,0 +1,199 @@
+import { GitPort } from "@gitkraken/shared-tools";
+
+//#region src/ports/git.d.ts
+/**
+ * Compose-specific git port — accepts either high-level ops, raw `exec`, or both.
+ *
+ * The library's internal call sites go through dispatchers in `../git/port-dispatch.js`
+ * that prefer the high-level op when provided, fall back to `exec` otherwise, and
+ * throw `ComposeGitPortMissingOpError` when neither is available for the current flow.
+ *
+ * Consumers have three reasonable shapes:
+ * - CLI consumer: provide only `exec` — every op is routed through it.
+ * - libgit2 consumer: provide every op used by their flow, skip `exec`.
+ * - Hybrid: provide `exec` plus targeted high-level overrides (e.g. signing-aware
+ *   `commitTree`) that the library prefers over the default CLI route.
+ *
+ * `exec` is optional at the type level, but required at runtime if any flow calls an
+ * op the consumer didn't provide — the dispatcher throws with a clear message.
+ */
+interface ComposeGitOps {
+  /** Resolve a ref to its SHA. Covers `rev-parse HEAD`, `rev-parse <branch>`, `rev-parse <sha>`. */
+  revParse?: (ref: string, opts?: OpOptions) => Promise<string>;
+  /** Resolve and verify a ref exists. Returns SHA on success, `null` on not-found. Covers `rev-parse --verify`. */
+  revParseVerify?: (ref: string, opts?: OpOptions) => Promise<string | null>;
+  /** Absolute path to the `.git` dir for this repo. Covers `rev-parse --absolute-git-dir`. */
+  gitDir?: (opts?: OpOptions) => Promise<string>;
+  /** Name of the branch HEAD points at, or `null` if HEAD is detached. Covers `rev-parse --abbrev-ref HEAD` / `symbolic-ref`. */
+  currentBranch?: (opts?: OpOptions) => Promise<string | null>;
+  /** Best common ancestor between two refs. Covers `merge-base a b`. */
+  mergeBase?: (a: string, b: string, opts?: OpOptions) => Promise<string>;
+  /** Tree-to-tree unified diff. Covers `diff --binary from to` and `diff --name-only from to`. */
+  diffTree?: (from: string, to: string, opts?: DiffTreeOptions) => Promise<string>;
+  /** Commit log with custom format. Covers various `git log --format=... <range>` / `-1 <sha>` uses. */
+  log?: (opts: LogOptions) => Promise<string>;
+  /** Ref enumeration. Covers `for-each-ref`. */
+  forEachRef?: (opts: ForEachRefOptions) => Promise<string>;
+  /** Write the current (or temp) index to a tree object. Covers `write-tree`. */
+  writeTree?: (opts?: IndexScopedOptions) => Promise<string>;
+  /** Load a tree's contents into the current (or temp) index. Covers `read-tree <sha>`. */
+  readTree?: (sha: string, opts?: IndexScopedOptions) => Promise<void>;
+  /** Stage files to the current (or temp) index. Covers `add -u`, `add -A`, `add -N -- paths`, `add <paths>`. */
+  stageAll?: (opts?: StageAllOptions) => Promise<void>;
+  /** Porcelain status. Covers `status --porcelain`. */
+  statusPorcelain?: (opts?: OpOptions) => Promise<string>;
+  /** Untracked file paths relative to repo root. Covers `ls-files --others --exclude-standard`. */
+  listUntracked?: (opts?: OpOptions) => Promise<string[]>;
+  /** Read a file's contents at a given ref. Covers `show ref:path`. */
+  showFile?: (ref: string, path: string, opts?: OpOptions) => Promise<string>;
+  /** Read a git config value. Returns `null` when unset. Covers `config <key>`. */
+  getConfig?: (key: string, opts?: OpOptions) => Promise<string | null>;
+  /** Create a commit object from a tree and parents. Covers `commit-tree tree -p parent -m message`. */
+  commitTree?: (tree: string, parents: string[], message: string, opts?: CommitTreeOptions) => Promise<string>;
+  /** Apply a unified diff patch to the current (or temp) index. Covers `apply --cached --allow-binary-replacement`. */
+  applyPatchToIndex?: (patch: string, opts?: ApplyPatchOptions) => Promise<void>;
+  /** 3-way merge producing a tree SHA. Covers `merge-tree --write-tree a b`. */
+  mergeTree?: (a: string, b: string, opts?: OpOptions) => Promise<string>;
+  /** Create a branch at `startPoint`. Covers `branch name start`. */
+  createBranch?: (name: string, startPoint: string, opts?: OpOptions) => Promise<void>;
+  /** Delete a branch. `force: true` maps to `-D`. Covers `branch -D` and `branch -d`. */
+  deleteBranch?: (name: string, opts?: DeleteBranchOptions) => Promise<void>;
+  /** Set a ref to a SHA atomically. `previousSha` allows CAS. Covers `update-ref <ref> <sha>` / `update-ref -d`. */
+  updateRef?: (ref: string, sha: string, opts?: UpdateRefOptions) => Promise<void>;
+  /** Switch to a ref. `createBranch: true` → new branch. `detach: true` → detached HEAD. Covers `checkout <ref>`, `checkout -b`, `checkout --detach`. */
+  checkout?: (ref: string, opts?: CheckoutOptions) => Promise<void>;
+  /** Reset HEAD (and optionally index/worktree) to a ref. Covers `reset [--soft/--mixed/--hard] sha`. */
+  reset?: (ref: string, mode: 'soft' | 'mixed' | 'hard', opts?: OpOptions) => Promise<void>;
+  /** Remove untracked files/dirs from workdir. Covers `clean -fd`. */
+  cleanWorkdir?: (opts?: CleanOptions) => Promise<void>;
+  /** Discard unstaged workdir changes. Covers `checkout -- .` or `checkout -- paths`. */
+  discardWorkdirChanges?: (paths?: string[], opts?: OpOptions) => Promise<void>;
+  /** Push current workdir state to stash. Covers `stash push --include-untracked -m msg`. */
+  stashPush?: (opts?: StashPushOptions) => Promise<void>;
+  /** Pop the top stash entry. Covers `stash pop`. */
+  stashPop?: (opts?: OpOptions) => Promise<void>;
+  /**
+   * Apply an existing commit onto the current HEAD, producing a new commit.
+   * Covers `git cherry-pick <sha>`. Throws when conflicts make the pick fail —
+   * callers should wrap and surface that as a `GitError('CHERRY_PICK_CONFLICT')`.
+   *
+   * A libgit2-backed implementation can perform a 3-way merge in memory and
+   * create the resulting commit directly, without touching the working tree.
+   */
+  cherryPick?: (sha: string, opts?: OpOptions) => Promise<void>;
+  /** Abort an in-progress cherry-pick. Covers `git cherry-pick --abort`. */
+  cherryPickAbort?: (opts?: OpOptions) => Promise<void>;
+}
+/** Options passed to every op — all ops can be cancelled via signal. */
+interface OpOptions {
+  signal?: AbortSignal;
+}
+interface DiffTreeOptions extends OpOptions {
+  /** Include binary hunks as base85. Default true. */
+  binary?: boolean;
+  /** Return file list instead of patch content. */
+  nameOnly?: boolean;
+}
+interface LogOptions extends OpOptions {
+  format: string;
+  range?: string;
+  sha?: string;
+  limit?: number;
+  noMerges?: boolean;
+  reverse?: boolean;
+  author?: string;
+}
+interface ForEachRefOptions extends OpOptions {
+  format: string;
+  prefix?: string;
+  sort?: string;
+  limit?: number;
+}
+/**
+ * Index-scoped options.
+ *
+ * `indexEnv` is the env vars the library produces when it wants an op to run
+ * against a scratch index rather than the real one — typically
+ * `{ GIT_INDEX_FILE: <tmp path> }`. CLI consumers route these env vars to the
+ * child process. libgit2 consumers can treat `indexEnv.GIT_INDEX_FILE` as an
+ * opaque key to look up their in-memory index object.
+ */
+interface IndexScopedOptions extends OpOptions {
+  indexEnv?: Record<string, string>;
+}
+interface StageAllOptions extends IndexScopedOptions {
+  /** Stage only tracked modifications (`add -u`). Mutually exclusive with `intentToAdd`. */
+  trackedOnly?: boolean;
+  /** Add with intent-to-add (`add -N`). */
+  intentToAdd?: boolean;
+  /** Stage specific paths. When omitted, stages all (`add -A`). */
+  paths?: string[];
+}
+interface GitCommitIdentity {
+  name: string;
+  email: string;
+  date?: Date;
+}
+interface SigningConfig {
+  enabled: boolean;
+  /**
+   * The signing key to pass to `commit-tree -S<key>`. Accepts any value git
+   * would — GPG key ID, SSH key path, etc. — matching the `user.signingkey`
+   * git config semantics.
+   */
+  signingKey?: string;
+  gpgProgram?: string;
+}
+interface CommitTreeOptions extends OpOptions {
+  /** When set, sets `GIT_AUTHOR_*` env on the commit. */
+  author?: GitCommitIdentity;
+  /** When enabled, the op signs the commit (consumer responsibility to honor). */
+  signing?: SigningConfig;
+}
+interface ApplyPatchOptions extends IndexScopedOptions {
+  /** Allow binary hunks in the patch. Default true. */
+  allowBinaryReplacement?: boolean;
+}
+interface DeleteBranchOptions extends OpOptions {
+  force?: boolean;
+}
+interface UpdateRefOptions extends OpOptions {
+  /** When set, only update if the current SHA matches. */
+  previousSha?: string;
+  /** When true, deletes the ref instead. */
+  remove?: boolean;
+}
+interface CheckoutOptions extends OpOptions {
+  /** When true, `ref` is a new branch name to create. Requires `startPoint` for non-HEAD starts. */
+  createBranch?: boolean;
+  /** Start point for a new branch created via `createBranch`. Ignored otherwise. */
+  startPoint?: string;
+  /** Detach HEAD at the target. */
+  detach?: boolean;
+}
+interface CleanOptions extends OpOptions {
+  force?: boolean;
+  directories?: boolean;
+}
+interface StashPushOptions extends OpOptions {
+  message?: string;
+  includeUntracked?: boolean;
+}
+/**
+ * The full port shape the library accepts. Exec is optional — if absent,
+ * every flow must be fully served by high-level ops.
+ */
+type ComposeGitPort = ComposeGitOps & {
+  exec?: GitPort['exec'];
+};
+/**
+ * Thrown when the library needs a git op the consumer didn't provide, and
+ * `exec` isn't available as a fallback.
+ */
+declare class ComposeGitPortMissingOpError extends Error {
+  readonly op: string;
+  readonly hint: string;
+  constructor(op: string, hint?: string);
+}
+//#endregion
+export { ApplyPatchOptions, CheckoutOptions, CleanOptions, CommitTreeOptions, ComposeGitOps, ComposeGitPort, ComposeGitPortMissingOpError, DeleteBranchOptions, DiffTreeOptions, ForEachRefOptions, GitCommitIdentity, IndexScopedOptions, LogOptions, OpOptions, SigningConfig, StageAllOptions, StashPushOptions, UpdateRefOptions };

package/dist/ports/git.js

@@ -0,0 +1 @@
+var e=class extends Error{op;hint;constructor(e,t){super(`ComposeGitPort is missing op '${e}'. `+`Provide either '${e}' directly, or provide 'exec' as a fallback. ${t??``}`.trim()),this.name=`ComposeGitPortMissingOpError`,this.op=e,this.hint=t??``}};export{e as ComposeGitPortMissingOpError};

package/dist/tasks/ai-loop.d.ts

@@ -0,0 +1,99 @@
+import { AiSession } from "../ai/session.js";
+import { ProgressEvent, TokenUsage } from "../ai/types.js";
+import { AiModelPort } from "@gitkraken/shared-tools";
+
+//#region src/tasks/ai-loop.d.ts
+/**
+ * Observability hook: called immediately before each model.generate invocation.
+ *
+ * Consumers can use this for telemetry, progress UI, log emission, etc. The
+ * library doesn't interpret the result — the hook is purely informational.
+ */
+interface BeforeModelCallInfo {
+  /** Phase name (e.g. "analyze", "compose-group", "order", "partition"). */
+  phase: string;
+  attempt: number;
+  maxAttempts: number;
+  /** Stable UUID identifying this model.generate call. Pairs with the matching After event. */
+  callId: string;
+}
+interface AfterModelCallInfo {
+  phase: string;
+  attempt: number;
+  callId: string;
+  success: boolean;
+  durationMs: number;
+  usage?: TokenUsage;
+  error?: {
+    code: string;
+    message: string;
+  };
+  /** Identifier of the prompt template used for this call, when a consumer override supplied one. */
+  promptVersion?: string;
+}
+type OnBeforeModelCall = (info: BeforeModelCallInfo) => void;
+type OnAfterModelCall = (info: AfterModelCallInfo) => void;
+/**
+ * Gating hook fired immediately before each model.generate call.
+ *
+ * Returning `false` aborts the workflow; the library throws the resulting
+ * rejection as a `WorkflowError('CANCELLED')`. Intended for cost warnings,
+ * large-prompt confirmations, policy checks, and similar consumer-side UX.
+ *
+ * The library provides `tokenEstimate` as a rough `charCount / 2.8`
+ * approximation — reasonable for code-heavy prompts but not authoritative.
+ * Consumers can ignore it and estimate their own way.
+ */
+interface BeforePromptInfo {
+  phase: string;
+  attempt: number;
+  maxAttempts: number;
+  charCount: number;
+  messageCount: number;
+  tokenEstimate: number;
+}
+type OnBeforePrompt = (info: BeforePromptInfo) => Promise<boolean>;
+/** Character-to-token approximation for English/code prompts. */
+declare const estimatedCharactersPerToken = 2.8;
+interface AiLoopParams<T> {
+  model: AiModelPort;
+  systemPrompt?: string;
+  userPrompt: string;
+  session?: AiSession;
+  maxRetries?: number;
+  maxTokens?: number;
+  onProgress?: (event: ProgressEvent) => void;
+  validate: (responseText: string) => ValidationResult<T>;
+  taskName: string;
+  signal?: AbortSignal;
+  /** Phase label stamped on Before/After model-call hook events. */
+  phase?: string;
+  onBeforeModelCall?: OnBeforeModelCall;
+  onAfterModelCall?: OnAfterModelCall;
+  /**
+   * Gating hook. Called before each model.generate. If it returns `false`, the
+   * loop aborts with an AbortError (caught by the workflow and surfaced as a
+   * `WorkflowError('CANCELLED')`).
+   */
+  onBeforePrompt?: OnBeforePrompt;
+  promptVersion?: string;
+}
+interface ValidationResult<T> {
+  valid: boolean;
+  result?: T;
+  errors?: string[];
+  retryFeedback?: string;
+}
+interface AiLoopResult<T> {
+  result: T;
+  session: AiSession;
+  usage?: TokenUsage;
+  attempts: number;
+  durationMs: number;
+  /** Stable call IDs for each model.generate invocation this loop made, in order. */
+  callIds: string[];
+}
+declare function runAiLoop<T>(params: AiLoopParams<T>): Promise<AiLoopResult<T>>;
+declare function extractOutputTag(text: string): string | null;
+//#endregion
+export { AfterModelCallInfo, BeforeModelCallInfo, BeforePromptInfo, OnAfterModelCall, OnBeforeModelCall, OnBeforePrompt, ValidationResult, estimatedCharactersPerToken, extractOutputTag, runAiLoop };

package/dist/tasks/ai-loop.js

@@ -0,0 +1,2 @@
+import{WorkflowError as e}from"../errors/workflow.js";import{AIError as t}from"../errors/ai.js";import{TaskInputError as n}from"../errors/task.js";import{appendAssistantMessage as r,appendUserMessage as i,createAiSession as a}from"../ai/session.js";import{addUsage as o}from"../ai/types.js";import{randomUUID as s}from"node:crypto";const c=2.8;async function l(o){let{model:c,userPrompt:l,maxRetries:f=3,maxTokens:p=16384,onProgress:m,validate:h,taskName:g,signal:_,phase:v=g,onBeforeModelCall:y,onAfterModelCall:b,promptVersion:x}=o;if(!o.session&&!o.systemPrompt)throw new n(`${g}: either 'session' or 'systemPrompt' must be provided`);let S=Date.now(),C;o.session?C=i(o.session,l):(C=a(o.systemPrompt),C=i(C,l));let w,T=[],E=f+1,D=[];for(let t=0;t<=f;t++){_?.throwIfAborted();let n=t+1;if(m?.({type:`attempt_start`,attempt:n,maxAttempts:E}),o.onBeforePrompt){let t=(C.systemPrompt?.length??0)+C.messages.reduce((e,t)=>e+t.content.length,0);if(!await o.onBeforePrompt({phase:v,attempt:n,maxAttempts:E,charCount:t,messageCount:C.messages.length,tokenEstimate:Math.ceil(t/2.8)}))throw new e(`CANCELLED`,`Prompt gate declined by consumer (onBeforePrompt returned false)`)}let a=s();D.push(a);let l=Date.now();y?.({phase:v,attempt:n,maxAttempts:E,callId:a});let g;try{g=await c.generate({system:C.systemPrompt,messages:[...C.messages],maxTokens:p,temperature:0,signal:_})}catch(t){let r=t instanceof Error?t.message:String(t);throw b?.({phase:v,attempt:n,callId:a,success:!1,durationMs:Date.now()-l,error:{code:t?.code??`UNKNOWN`,message:r},promptVersion:x}),u(t)||_?.aborted?new e(`CANCELLED`,r,{cause:t}):t}b?.({phase:v,attempt:n,callId:a,success:!0,durationMs:Date.now()-l,usage:g.usage,promptVersion:x}),w=d(w,g.usage);let O=h(g.text);if(O.valid&&O.result!==void 0)return C=r(C,g.text),{result:O.result,session:C,usage:w,attempts:n,durationMs:Date.now()-S,callIds:D};T=O.errors??[`Unknown validation error`],m?.({type:`validation_failed`,attempt:n,maxAttempts:E,errors:T}),t<f&&O.retryFeedback&&(C=r(C,g.text),C=i(C,O.retryFeedback))}throw new t(`VALIDATION_EXHAUSTED`,`Failed to get valid ${g} after ${E} attempts. Last errors:\n${T.join(`
+`)}`)}function u(e){return e instanceof Error&&(e.name===`AbortError`||e.name===`DOMException`)}function d(e,t){if(!e)return t;if(!t)return e;let n={...e};return o(n,t),n}function f(e){let t=e.match(/<output>([\s\S]*?)(?:<\/output>|$)/)?.[1]?.trim()??null;return t?t.match(/^```(?:\w*)\n?([\s\S]*?)```$/)?.[1]?.trim()??t:null}export{c as estimatedCharactersPerToken,f as extractOutputTag,l as runAiLoop};

package/dist/tasks/analyze/analyze.d.ts

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

package/dist/tasks/analyze/analyze.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{buildAnalyzeSystemPrompt as r,buildAnalyzeUserPrompt as i}from"./prompt.js";import{validateAnalyzeResponse as a}from"./validator.js";async function o(o){let s=o.hunks;if(!s||s.length===0)throw new e(`No hunks provided: supply 'hunks'`);if(o.session?.completedSteps.analyze)return{result:o.session.completedSteps.analyze,session:o.session,attempts:0,durationMs:0,callIds:[]};let c=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),l=s.length,u=await t({model:o.model,systemPrompt:o.session?void 0:o.promptOverride?.system??r(),userPrompt:c,session:o.session,maxRetries:o.maxRetries,onProgress:o.onProgress,signal:o.signal,onBeforeModelCall:o.onBeforeModelCall,onAfterModelCall:o.onAfterModelCall,onBeforePrompt:o.onBeforePrompt,validate:e=>a(e,l),taskName:`analyze`}),d=o.session?.completedSteps??{},f={...u.session,completedSteps:{...d,analyze:u.result}};return{result:u.result,session:f,usage:u.usage,attempts:u.attempts,durationMs:u.durationMs,callIds:u.callIds}}export{o as analyze};

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

@@ -0,0 +1,16 @@
+import { ComposeHunk } from "../types.js";
+
+//#region src/tasks/analyze/prompt.d.ts
+declare function buildAnalyzeSystemPrompt(): string;
+declare function buildAnalyzeUserPrompt(params: {
+  hunks: ComposeHunk[];
+  commitMessages?: string[];
+  commitOrder?: string[];
+  branchName?: string;
+  baseBranch?: string;
+  issueUrl?: string;
+  pullRequestUrl?: string;
+  instructions?: string;
+}): string;
+//#endregion
+export { buildAnalyzeSystemPrompt, buildAnalyzeUserPrompt };

package/dist/tasks/analyze/prompt.js

@@ -0,0 +1,34 @@
+import{analysisResultSchema 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 code analysis assistant. Your task is to deeply analyze a set of code changes (provided as diff hunks) and produce a structured understanding of what the changes accomplish, what concerns they address, and how hunks relate to each other.
+
+Your analysis must produce:
+1. **Title** — a short, PR-style title for the changes (under 72 characters, imperative mood, e.g. "Add user authentication and session management"). This should capture the essence of what the changes accomplish.
+2. **Concerns** — distinct themes, features, or purposes within the changes. Each concern should represent a logically independent unit of work.
+3. **Dependencies** — relationships between concerns where one depends on or builds upon another.
+4. **Hunk annotations** — for each hunk, which concern it belongs to and what role it plays.
+5. **Ordering constraints** — pairs of hunks where one provides something (defines a file, function, type, config entry, etc.) that the other consumes (imports, calls, references, uses). The provider hunk must appear in the same commit as or an earlier commit than the consumer hunk. This does NOT mean they must be in different commits — they can absolutely be in the same commit if that makes sense. It simply means the consumer cannot appear in a commit that precedes the provider's commit.
+
+Look for these patterns:
+- A hunk adds a script/file, another hunk references that file path in configuration, package.json, or imports
+- A hunk defines a function, class, or type, another hunk imports or calls it
+- A hunk creates a module, another hunk adds it to an index/barrel export
+- A hunk adds a dependency, another hunk uses that dependency
+
+Rules:
+- Every hunk must be annotated with exactly one concern
+- Concerns should be named clearly and concisely
+- Dependencies should capture real code-level relationships, not just thematic similarity
+- Ordering constraints should capture concrete provider/consumer relationships between specific hunks, not vague thematic ordering
+- Your summary should be actionable — someone reading it should understand the full scope of changes
+
+## Required Output Format
+
+Output your analysis 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=`Analyze the following code changes:\n\n<hunks>\n${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}:{}})))}\n</hunks>`,u=[];if(i&&u.push(`Branch: ${i}`),a&&u.push(`Base branch: ${a}`),o&&u.push(`Issue: ${o}`),s&&u.push(`Pull request: ${s}`),u.length>0&&(l+=`\n\n<context>\n${u.join(`
+`)}\n</context>`),n?.length){let e=n.map((e,t)=>({index:t,sha:r?.[t],message:e}));l+=`\n\n<commit_messages>\n${JSON.stringify(e)}\n</commit_messages>`}return c&&(l+=`\n\nCarefully follow these additional instructions, but do not deviate from the output structure:\n${c}`),l+=`
+
+Now analyze the changes and return your structured analysis. Return only the <output> tag and no other text.`,l}export{r as buildAnalyzeSystemPrompt,i as buildAnalyzeUserPrompt};

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

@@ -0,0 +1,38 @@
+import { z } from "zod";
+
+//#region src/tasks/analyze/schema.d.ts
+declare const analysisResultSchema: z.ZodObject<{
+  title: z.ZodString;
+  summary: z.ZodString;
+  concerns: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    hunkIndices: z.ZodArray<z.ZodNumber>;
+  }, z.core.$strip>>;
+  dependencies: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    reason: z.ZodString;
+  }, z.core.$strip>>>;
+  hunkAnnotations: z.ZodArray<z.ZodObject<{
+    hunkIndex: z.ZodNumber;
+    concernId: z.ZodString;
+    purpose: z.ZodString;
+  }, z.core.$strip>>;
+  orderingConstraints: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    provider: z.ZodNumber;
+    consumer: z.ZodNumber;
+    kind: z.ZodEnum<{
+      "file-reference": "file-reference";
+      import: "import";
+      "function-call": "function-call";
+      "type-reference": "type-reference";
+      "config-reference": "config-reference";
+      other: "other";
+    }>;
+    reason: z.ZodString;
+  }, z.core.$strip>>>;
+}, z.core.$strip>;
+//#endregion
+export { analysisResultSchema };

package/dist/tasks/analyze/schema.js

@@ -0,0 +1 @@
+import{z as e}from"zod";const t=e.enum([`file-reference`,`import`,`function-call`,`type-reference`,`config-reference`,`other`]),n=e.object({title:e.string().min(1).max(72).describe(`Short PR-style title for the changes (under 72 chars, imperative mood, e.g. 'Add user authentication and session management')`),summary:e.string().min(1).describe(`High-level summary of all changes`),concerns:e.array(e.object({id:e.string().describe(`Unique concern ID (e.g. c1, c2)`),name:e.string().describe(`Short concern name`),description:e.string().describe(`What this concern accomplishes`),hunkIndices:e.array(e.number()).describe(`Indices of hunks belonging to this concern`)})).min(1).describe(`Distinct themes, features, or purposes within the changes`),dependencies:e.array(e.object({from:e.string().describe(`Concern ID`),to:e.string().describe(`Concern ID that 'from' depends on`),reason:e.string().describe(`Why the dependency exists`)})).default([]).describe(`Relationships between concerns`),hunkAnnotations:e.array(e.object({hunkIndex:e.number().describe(`Index of the hunk`),concernId:e.string().describe(`Concern this hunk belongs to`),purpose:e.string().describe(`What this hunk does in context of its concern`)})).describe(`Per-hunk concern assignment and purpose`),orderingConstraints:e.array(e.object({provider:e.number().describe(`Hunk index that defines/creates something`),consumer:e.number().describe(`Hunk index that references/uses it`),kind:t.describe(`Type of provider/consumer relationship`),reason:e.string().describe(`Brief explanation of the relationship`)})).default([]).describe(`Provider/consumer ordering between hunks`)});export{n as analysisResultSchema};

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

@@ -0,0 +1,69 @@
+import { ProgressEvent, TokenUsage } from "../../ai/types.js";
+import { 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/analyze/types.d.ts
+interface AnalyzeInput {
+  hunks?: ComposeHunk[];
+  commitMessages?: string[];
+  commitOrder?: string[];
+  branchName?: string;
+  baseBranch?: string;
+  issueUrl?: string;
+  pullRequestUrl?: string;
+  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 Concern {
+  id: string;
+  name: string;
+  description: string;
+  hunkIndices: number[];
+}
+interface ConcernDependency {
+  from: string;
+  to: string;
+  reason: string;
+}
+interface HunkAnnotation {
+  hunkIndex: number;
+  concernId: string;
+  purpose: string;
+}
+interface HunkOrderingConstraint {
+  /** Hunk that provides/defines/creates something */
+  provider: number;
+  /** Hunk that consumes/references/uses it */
+  consumer: number;
+  kind: 'file-reference' | 'import' | 'function-call' | 'type-reference' | 'config-reference' | 'other';
+  reason: string;
+}
+interface AnalysisResult {
+  title: string;
+  summary: string;
+  concerns: Concern[];
+  dependencies: ConcernDependency[];
+  hunkAnnotations: HunkAnnotation[];
+  orderingConstraints: HunkOrderingConstraint[];
+}
+interface AnalyzeOutput {
+  result: AnalysisResult;
+  session: ComposeSession;
+  usage?: TokenUsage;
+  attempts: number;
+  durationMs: number;
+  callIds: string[];
+}
+//#endregion
+export { AnalysisResult, AnalyzeInput, AnalyzeOutput, Concern, ConcernDependency, HunkAnnotation, HunkOrderingConstraint };

package/dist/tasks/analyze/types.js

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

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

@@ -0,0 +1,7 @@
+import { ValidationResult } from "../ai-loop.js";
+import { AnalysisResult } from "./types.js";
+
+//#region src/tasks/analyze/validator.d.ts
+declare function validateAnalyzeResponse(responseText: string, totalHunks: number): ValidationResult<AnalysisResult>;
+//#endregion
+export { validateAnalyzeResponse };

package/dist/tasks/analyze/validator.js

@@ -0,0 +1,13 @@
+import{extractOutputTag as e}from"../ai-loop.js";import{analysisResultSchema 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());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());let l=c.data,u=new Set(l.hunkAnnotations.map(e=>e.hunkIndex)),d=[...new Set(Array.from({length:a},(e,t)=>t))].filter(e=>!u.has(e));return d.length>0?r([`Missing annotations for hunks: ${d.join(`, `)}`],`Your response is missing annotations for some hunks. Every hunk must be annotated.\n\nMissing: ${d.join(`, `)}\n\nPlease provide a corrected response.`):{valid:!0,result:{title:l.title,summary:l.summary,concerns:l.concerns,dependencies:l.dependencies,hunkAnnotations:l.hunkAnnotations,orderingConstraints:l.orderingConstraints}}}catch{return r([`Failed to parse response as valid JSON`],i())}}function r(e,t){return{valid:!1,errors:e,retryFeedback:t}}function i(){return`Your response has an invalid structure. Please return JSON inside <output> tags with this structure:
+<output>
+{
+  "title": "Short PR-style title (under 72 chars)",
+  "summary": "...",
+  "concerns": [{ "id": "c1", "name": "...", "description": "...", "hunkIndices": [0, 1] }],
+  "dependencies": [{ "from": "c1", "to": "c2", "reason": "..." }],
+  "hunkAnnotations": [{ "hunkIndex": 0, "concernId": "c1", "purpose": "..." }],
+  "orderingConstraints": [{ "provider": 0, "consumer": 1, "kind": "import", "reason": "..." }]
+}
+</output>
+
+Return only the <output> tag and no other text.`}export{n as validateAnalyzeResponse};

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

@@ -0,0 +1,15 @@
+import { GroupOutput } from "../group/types.js";
+import { ComposeGroupInput } from "./types.js";
+
+//#region src/tasks/compose-group/compose-group.d.ts
+/**
+ * Balanced-mode task that combines analysis reasoning with grouping.
+ *
+ * The AI internally analyzes concerns, dependencies, and ordering constraints
+ * before producing a GroupingResult. The output uses the same schema and
+ * validator as the standard group task, but the prompt instructs deeper
+ * reasoning than a standalone group call.
+ */
+declare function composeGroup(input: ComposeGroupInput): Promise<GroupOutput>;
+//#endregion
+export { composeGroup };

package/dist/tasks/compose-group/compose-group.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{validateGroupResponse as r}from"../group/validator.js";import{buildComposeGroupSystemPrompt as i,buildComposeGroupUserPrompt as a}from"./prompt.js";async function o(o){let s=o.hunks,c=o.mode??`branches`;if(!s||s.length===0)throw new e(`No hunks provided for compose-group`);if(o.session?.completedSteps.composeGroup)return{result:o.session.completedSteps.composeGroup,session:o.session,attempts:0,durationMs:0,callIds:[]};let l=o.promptOverride?.system??i(o.conventions,c,o.strategy,o.includeAnalysis,o.lightweight),u=n(a({hunks:s,commitMessages:o.commitMessages,commitOrder:o.commitOrder,branchName:o.branchName,baseBranch:o.baseBranch,issueUrl:o.issueUrl,pullRequestUrl:o.pullRequestUrl,instructions:o.instructions,condensed:o.condensed}),o.promptOverride),d=await t({model:o.model,systemPrompt:l,userPrompt:u,maxRetries:o.maxRetries,onProgress:o.onProgress,signal:o.signal,onBeforeModelCall:o.onBeforeModelCall,onAfterModelCall:o.onAfterModelCall,onBeforePrompt:o.onBeforePrompt,validate:e=>r(e,s.length,c,o.existingBranchNames),taskName:`compose-group`}),f=o.session?.completedSteps??{},p={...d.session,completedSteps:{...f,composeGroup:d.result}};return{result:d.result,session:p,usage:d.usage,attempts:d.attempts,durationMs:d.durationMs,callIds:d.callIds}}export{o as composeGroup};

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

@@ -0,0 +1,26 @@
+import { ComposeHunk } from "../types.js";
+import { ConventionDescriptor } from "../../git/utils/conventions.js";
+import { GroupingStrategy } from "../group/types.js";
+
+//#region src/tasks/compose-group/prompt.d.ts
+/**
+ * System prompt for balanced-mode compose-group.
+ *
+ * Combines analysis reasoning (identify concerns, dependencies, ordering)
+ * with grouping instructions. The AI reasons about codependencies internally
+ * but only outputs GroupingResult — no separate AnalysisResult.
+ */
+declare function buildComposeGroupSystemPrompt(conventions?: ConventionDescriptor, mode?: 'commits' | 'branches', strategy?: GroupingStrategy, includeAnalysis?: boolean, lightweight?: boolean): string;
+declare function buildComposeGroupUserPrompt(params: {
+  hunks: ComposeHunk[];
+  commitMessages?: string[];
+  commitOrder?: string[];
+  branchName?: string;
+  baseBranch?: string;
+  issueUrl?: string;
+  pullRequestUrl?: string;
+  instructions?: string;
+  condensed?: boolean;
+}): string;
+//#endregion
+export { buildComposeGroupSystemPrompt, buildComposeGroupUserPrompt };