@substrate-ai/core 0.19.54

package/dist/events/event-bus.d.ts

@@ -0,0 +1,55 @@
+/**
+ * TypedEventBus<E extends EventMap> — generic event bus interface and implementation.
+ *
+ * This interface is the stable contract for the event bus system.
+ * Packages parameterize it with their own event map types (e.g., TypedEventBus<SdlcEvents>).
+ */
+import type { EventMap, EventHandler } from './types.js';
+/**
+ * A type-safe event bus parameterized over an event map E.
+ *
+ * @example
+ * const bus: TypedEventBus<CoreEvents & SdlcEvents> = createEventBus()
+ * bus.on('orchestrator:story-complete', ({ storyKey }) => { ... })
+ */
+export interface TypedEventBus<E extends EventMap> {
+    /**
+     * Emit an event with a typed payload.
+     * All registered handlers for this event key are called synchronously.
+     */
+    emit<K extends keyof E>(event: K, payload: E[K]): void;
+    /**
+     * Register a handler for an event.
+     */
+    on<K extends keyof E>(event: K, handler: EventHandler<E[K]>): void;
+    /**
+     * Unregister a previously registered handler.
+     */
+    off<K extends keyof E>(event: K, handler: EventHandler<E[K]>): void;
+}
+/**
+ * Concrete implementation of TypedEventBus backed by Node.js EventEmitter.
+ *
+ * Dispatch is SYNCHRONOUS — all handlers run before emit() returns (per ADR-004).
+ * maxListeners is set to 100 to avoid spurious warnings in large systems.
+ *
+ * @example
+ * const bus = new TypedEventBusImpl<CoreEvents & SdlcEvents>()
+ * bus.on('orchestrator:story-complete', ({ storyKey }) => { ... })
+ * bus.emit('orchestrator:story-complete', { storyKey: '1-1', reviewCycles: 1 })
+ */
+export declare class TypedEventBusImpl<E extends EventMap> implements TypedEventBus<E> {
+    private readonly _emitter;
+    constructor();
+    emit<K extends keyof E>(event: K, payload: E[K]): void;
+    on<K extends keyof E>(event: K, handler: EventHandler<E[K]>): void;
+    off<K extends keyof E>(event: K, handler: EventHandler<E[K]>): void;
+}
+/**
+ * Create a new TypedEventBus instance parameterized over event map E.
+ *
+ * @example
+ * const bus = createEventBus<CoreEvents & SdlcEvents>()
+ */
+export declare function createEventBus<E extends EventMap>(): TypedEventBus<E>;
+//# sourceMappingURL=event-bus.d.ts.map

package/dist/events/event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/events/event-bus.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAExD;;;;;;GAMG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,QAAQ;IAC/C;;;OAGG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;IAEtD;;OAEG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;IAElE;;OAEG;IACH,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;CACpE;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,iBAAiB,CAAC,CAAC,SAAS,QAAQ,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IAC5E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;;IAQvC,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;IAItD,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;IAKlE,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;CAGpE;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,QAAQ,KAAK,aAAa,CAAC,CAAC,CAAC,CAErE"}

package/dist/events/event-bus.js

@@ -0,0 +1,52 @@
+/**
+ * TypedEventBus<E extends EventMap> — generic event bus interface and implementation.
+ *
+ * This interface is the stable contract for the event bus system.
+ * Packages parameterize it with their own event map types (e.g., TypedEventBus<SdlcEvents>).
+ */
+import { EventEmitter } from 'node:events';
+// ---------------------------------------------------------------------------
+// TypedEventBusImpl
+// ---------------------------------------------------------------------------
+/**
+ * Concrete implementation of TypedEventBus backed by Node.js EventEmitter.
+ *
+ * Dispatch is SYNCHRONOUS — all handlers run before emit() returns (per ADR-004).
+ * maxListeners is set to 100 to avoid spurious warnings in large systems.
+ *
+ * @example
+ * const bus = new TypedEventBusImpl<CoreEvents & SdlcEvents>()
+ * bus.on('orchestrator:story-complete', ({ storyKey }) => { ... })
+ * bus.emit('orchestrator:story-complete', { storyKey: '1-1', reviewCycles: 1 })
+ */
+export class TypedEventBusImpl {
+    _emitter;
+    constructor() {
+        this._emitter = new EventEmitter();
+        // Raise limit to avoid spurious warnings in large systems with many subscribers
+        this._emitter.setMaxListeners(100);
+    }
+    emit(event, payload) {
+        this._emitter.emit(event, payload);
+    }
+    on(event, handler) {
+        // EventEmitter passes arguments as rest params; cast to satisfy TypeScript
+        this._emitter.on(event, handler);
+    }
+    off(event, handler) {
+        this._emitter.off(event, handler);
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory function
+// ---------------------------------------------------------------------------
+/**
+ * Create a new TypedEventBus instance parameterized over event map E.
+ *
+ * @example
+ * const bus = createEventBus<CoreEvents & SdlcEvents>()
+ */
+export function createEventBus() {
+    return new TypedEventBusImpl();
+}
+//# sourceMappingURL=event-bus.js.map

package/dist/events/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../src/events/event-bus.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AA4B1C,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,OAAO,iBAAiB;IACX,QAAQ,CAAc;IAEvC;QACE,IAAI,CAAC,QAAQ,GAAG,IAAI,YAAY,EAAE,CAAA;QAClC,gFAAgF;QAChF,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,GAAG,CAAC,CAAA;IACpC,CAAC;IAED,IAAI,CAAoB,KAAQ,EAAE,OAAa;QAC7C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAe,EAAE,OAAO,CAAC,CAAA;IAC9C,CAAC;IAED,EAAE,CAAoB,KAAQ,EAAE,OAA2B;QACzD,2EAA2E;QAC3E,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAe,EAAE,OAAiC,CAAC,CAAA;IACtE,CAAC;IAED,GAAG,CAAoB,KAAQ,EAAE,OAA2B;QAC1D,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAe,EAAE,OAAiC,CAAC,CAAA;IACvE,CAAC;CACF;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,IAAI,iBAAiB,EAAK,CAAA;AACnC,CAAC"}

package/dist/events/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @substrate-ai/core events barrel export.
+ * Re-exports all event-related types for package consumers.
+ */
+export type { EventMap, EventHandler } from './types.js';
+export type { TypedEventBus } from './event-bus.js';
+export { TypedEventBusImpl, createEventBus } from './event-bus.js';
+export type { CoreEvents, EventTaskResult, EventTaskError, } from './core-events.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/events/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACxD,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACnD,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAClE,YAAY,EACV,UAAU,EAGV,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAA"}

package/dist/events/index.js

@@ -0,0 +1,6 @@
+/**
+ * @substrate-ai/core events barrel export.
+ * Re-exports all event-related types for package consumers.
+ */
+export { TypedEventBusImpl, createEventBus } from './event-bus.js';
+//# sourceMappingURL=index.js.map

package/dist/events/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/events/types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Base event type primitives for the TypedEventBus system.
+ *
+ * These types are the foundation of the event bus contract.
+ * All event maps must satisfy EventMap; all handlers must satisfy EventHandler<T>.
+ */
+/**
+ * Base constraint for event maps.
+ * Each key is an event name (string), and the value is the payload type.
+ *
+ * Using `object` (not `Record<string, unknown>`) so that TypeScript interfaces
+ * with named properties (without index signatures) satisfy the constraint.
+ * TypeScript interfaces extend `object` but may not extend `Record<string, unknown>`
+ * unless they have an explicit index signature.
+ */
+export type EventMap = object;
+/**
+ * A typed event handler function for payload type T.
+ */
+export type EventHandler<T> = (payload: T) => void;
+//# sourceMappingURL=types.d.ts.map

package/dist/events/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/events/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;GAQG;AAEH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAA;AAE7B;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAA"}

package/dist/events/types.js

@@ -0,0 +1,8 @@
+/**
+ * Base event type primitives for the TypedEventBus system.
+ *
+ * These types are the foundation of the event bus contract.
+ * All event maps must satisfy EventMap; all handlers must satisfy EventHandler<T>.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/events/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/events/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/git/git-manager.d.ts

@@ -0,0 +1,31 @@
+/**
+ * GitManager — interface and stub for git worktree management.
+ *
+ * The full implementation will be provided by a later story.
+ * This stub subscribes to worktree events and satisfies the IBaseService
+ * lifecycle contract.
+ *
+ * Event subscriptions (Architecture Section 19):
+ *  - Listens to worktree:created, worktree:merged, worktree:conflict, worktree:removed events
+ */
+import type { IBaseService } from '../types.js';
+import type { TypedEventBus } from '../events/index.js';
+import type { CoreEvents } from '../events/index.js';
+import type { ILogger } from '../dispatch/types.js';
+export interface GitManager extends IBaseService {
+}
+export declare class GitManagerImpl implements GitManager {
+    private readonly _eventBus;
+    private readonly _logger;
+    readonly repoRoot: string | undefined;
+    constructor(eventBus: TypedEventBus<CoreEvents>, repoRoot?: string, logger?: ILogger);
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export interface GitManagerOptions {
+    eventBus: TypedEventBus<CoreEvents>;
+    repoRoot?: string;
+    logger?: ILogger;
+}
+export declare function createGitManager(options: GitManagerOptions): GitManager;
+//# sourceMappingURL=git-manager.d.ts.map

package/dist/git/git-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-manager.d.ts","sourceRoot":"","sources":["../../src/git/git-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAMnD,MAAM,WAAW,UAAW,SAAQ,YAAY;CAE/C;AAMD,qBAAa,cAAe,YAAW,UAAU;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;gBAEzB,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO;IAM9E,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB3B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGhC;AAMD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,CAAA;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAEvE"}

package/dist/git/git-manager.js

@@ -0,0 +1,46 @@
+/**
+ * GitManager — interface and stub for git worktree management.
+ *
+ * The full implementation will be provided by a later story.
+ * This stub subscribes to worktree events and satisfies the IBaseService
+ * lifecycle contract.
+ *
+ * Event subscriptions (Architecture Section 19):
+ *  - Listens to worktree:created, worktree:merged, worktree:conflict, worktree:removed events
+ */
+// ---------------------------------------------------------------------------
+// GitManagerImpl (stub)
+// ---------------------------------------------------------------------------
+export class GitManagerImpl {
+    _eventBus;
+    _logger;
+    repoRoot;
+    constructor(eventBus, repoRoot, logger) {
+        this._eventBus = eventBus;
+        this.repoRoot = repoRoot;
+        this._logger = logger ?? console;
+    }
+    async initialize() {
+        this._logger.info({ repoRoot: this.repoRoot }, 'GitManager.initialize() — stub');
+        // Subscribe to worktree lifecycle events
+        this._eventBus.on('worktree:created', ({ taskId, worktreePath, branchName }) => {
+            this._logger.debug({ taskId, worktreePath, branchName }, 'worktree:created');
+        });
+        this._eventBus.on('worktree:merged', ({ taskId, branch }) => {
+            this._logger.debug({ taskId, branch }, 'worktree:merged');
+        });
+        this._eventBus.on('worktree:conflict', ({ taskId, conflictingFiles }) => {
+            this._logger.warn({ taskId, conflictingFiles }, 'worktree:conflict');
+        });
+        this._eventBus.on('worktree:removed', ({ taskId, branchName }) => {
+            this._logger.debug({ taskId, branchName }, 'worktree:removed');
+        });
+    }
+    async shutdown() {
+        this._logger.info('GitManager.shutdown() — stub');
+    }
+}
+export function createGitManager(options) {
+    return new GitManagerImpl(options.eventBus, options.repoRoot, options.logger);
+}
+//# sourceMappingURL=git-manager.js.map

package/dist/git/git-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-manager.js","sourceRoot":"","sources":["../../src/git/git-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAeH,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E,MAAM,OAAO,cAAc;IACR,SAAS,CAA2B;IACpC,OAAO,CAAS;IACxB,QAAQ,CAAoB;IAErC,YAAY,QAAmC,EAAE,QAAiB,EAAE,MAAgB;QAClF,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAA;QACzB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,OAAO,GAAG,MAAM,IAAI,OAAO,CAAA;IAClC,CAAC;IAED,KAAK,CAAC,UAAU;QACd,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE,gCAAgC,CAAC,CAAA;QAEhF,yCAAyC;QACzC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,kBAAkB,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,EAAE,EAAE;YAC7E,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,EAAE,kBAAkB,CAAC,CAAA;QAC9E,CAAC,CAAC,CAAA;QAEF,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,iBAAiB,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE;YAC1D,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,iBAAiB,CAAC,CAAA;QAC3D,CAAC,CAAC,CAAA;QAEF,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,EAAE,MAAM,EAAE,gBAAgB,EAAE,EAAE,EAAE;YACtE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,gBAAgB,EAAE,EAAE,mBAAmB,CAAC,CAAA;QACtE,CAAC,CAAC,CAAA;QAEF,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,kBAAkB,EAAE,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,EAAE;YAC/D,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,kBAAkB,CAAC,CAAA;QAChE,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAA;IACnD,CAAC;CACF;AAYD,MAAM,UAAU,gBAAgB,CAAC,OAA0B;IACzD,OAAO,IAAI,cAAc,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;AAC/E,CAAC"}

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

@@ -0,0 +1,166 @@
+/**
+ * git-utils.ts — Low-level git command helpers.
+ *
+ * All git commands are executed via child_process.spawn (not simple-git),
+ * as specified in ADR-007 (Git Worktree Management).
+ *
+ * Functions:
+ *  - spawnGit: Execute git with given args, returns stdout/stderr/code
+ *  - getGitVersion: Returns version string like "2.42.0"
+ *  - parseGitVersion: Parses version string into { major, minor, patch }
+ *  - isGitVersionSupported: Checks if version >= 2.20.0
+ *  - verifyGitVersion: Throws if git not installed or < 2.20
+ *  - createWorktree: Creates a worktree + branch
+ *  - removeWorktree: Removes a worktree directory
+ *  - removeBranch: Deletes a branch with git branch -D
+ *  - getOrphanedWorktrees: Scans .substrate-worktrees/ and returns paths
+ *  - simulateMerge: Runs git merge --no-commit --no-ff to detect conflicts
+ *  - abortMerge: Runs git merge --abort to clean up a simulated merge
+ *  - getConflictingFiles: Returns list of files with conflicts using git diff --name-only --diff-filter=U
+ *  - performMerge: Runs git merge --no-ff to execute actual merge
+ *  - getMergedFiles: Returns list of files changed in a merge using git diff --name-only
+ */
+export interface SpawnOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface GitSpawnResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+export interface GitVersion {
+    major: number;
+    minor: number;
+    patch: number;
+}
+/**
+ * Spawn a git subprocess with the given args.
+ *
+ * @param args    - Arguments to pass to git (e.g., ['worktree', 'add', ...])
+ * @param options - Optional spawn options (cwd, env)
+ * @returns       - Object with stdout, stderr, and exit code
+ */
+export declare function spawnGit(args: string[], options?: SpawnOptions): Promise<GitSpawnResult>;
+/**
+ * Get the installed git version string.
+ *
+ * @returns Version string like "2.42.0"
+ * @throws  Error if git is not installed or version cannot be parsed
+ */
+export declare function getGitVersion(): Promise<string>;
+/**
+ * Parse a git version string into major/minor/patch components.
+ *
+ * @param versionString - Version string like "2.42.0" or "2.20"
+ * @returns             - Parsed version components
+ */
+export declare function parseGitVersion(versionString: string): GitVersion;
+/**
+ * Check if the given git version string is >= 2.20.0.
+ *
+ * @param version - Version string like "2.42.0"
+ * @returns       - true if version >= 2.20.0
+ */
+export declare function isGitVersionSupported(version: string): boolean;
+/**
+ * Verify that git is installed and version >= 2.20.
+ *
+ * @throws Error with clear message if git is not installed or too old
+ */
+export declare function verifyGitVersion(): Promise<void>;
+/**
+ * Create a git worktree and its associated branch.
+ *
+ * Uses a single `git worktree add {worktreePath} -b {branchName} {baseBranch}`
+ * command to create the worktree with a new branch in one step.
+ *
+ * @param projectRoot - Absolute path to the git repository root
+ * @param taskId      - Task identifier (used in path derivation)
+ * @param branchName  - Branch name to create (e.g., "substrate/task-abc123")
+ * @param baseBranch  - Branch to base the worktree on (e.g., "main")
+ * @returns           - Object with the worktreePath
+ * @throws            - Error if git command fails
+ */
+export declare function createWorktree(projectRoot: string, taskId: string, branchName: string, baseBranch: string): Promise<{
+    worktreePath: string;
+}>;
+/**
+ * Remove a git worktree by path.
+ *
+ * Uses `git worktree remove --force` to handle unclean worktrees.
+ *
+ * @param worktreePath - Absolute path to the worktree directory
+ * @param projectRoot  - Absolute path to the git repository root
+ * @throws             - Error if git command fails
+ */
+export declare function removeWorktree(worktreePath: string, projectRoot?: string): Promise<void>;
+/**
+ * Delete a git branch using `git branch -D`.
+ *
+ * @param branchName  - Branch name to delete (e.g., "substrate/task-abc123")
+ * @param projectRoot - Absolute path to the git repository root
+ * @returns           - true if branch was successfully deleted, false otherwise
+ */
+export declare function removeBranch(branchName: string, projectRoot?: string): Promise<boolean>;
+/**
+ * Scan the worktrees base directory and return paths of all found worktree directories.
+ *
+ * @param projectRoot   - Absolute path to the git repository root
+ * @param baseDirectory - Relative directory name for worktrees (default: '.substrate-worktrees')
+ * @returns             - Array of absolute worktree directory paths
+ */
+export declare function getOrphanedWorktrees(projectRoot: string, baseDirectory?: string): Promise<string[]>;
+/**
+ * Simulate a merge using git merge --no-commit --no-ff without committing.
+ *
+ * This runs in the target branch's working directory (the project root or
+ * worktree path). The simulation must be aborted after checking conflicts
+ * via abortMerge().
+ *
+ * @param branchName  - The source branch to simulate merging
+ * @param cwd         - Working directory (must be on the target branch)
+ * @returns           - true if merge would be clean, false if there are conflicts
+ */
+export declare function simulateMerge(branchName: string, cwd: string): Promise<boolean>;
+/**
+ * Abort a merge in progress using git merge --abort.
+ *
+ * Should be called after simulateMerge() to clean up the merge state,
+ * regardless of whether conflicts were found.
+ *
+ * @param cwd - Working directory (same as used for simulateMerge)
+ */
+export declare function abortMerge(cwd: string): Promise<void>;
+/**
+ * Get a list of files with conflicts during a merge.
+ *
+ * Must be called while a merge is in progress (after simulateMerge() and
+ * before abortMerge()).
+ *
+ * @param cwd - Working directory of the repository
+ * @returns   - Array of conflicting file paths
+ */
+export declare function getConflictingFiles(cwd: string): Promise<string[]>;
+/**
+ * Perform an actual merge using git merge --no-ff.
+ *
+ * Should only be called after detectConflicts() confirms there are no conflicts.
+ * Creates a merge commit even if fast-forward is possible (--no-ff ensures history).
+ *
+ * @param branchName  - The source branch to merge
+ * @param cwd         - Working directory (must be on the target branch)
+ * @returns           - true if merge succeeded, false otherwise
+ */
+export declare function performMerge(branchName: string, cwd: string): Promise<boolean>;
+/**
+ * Get a list of files changed in the most recent merge.
+ *
+ * Uses git diff --name-only HEAD~1..HEAD to find files in the merge commit.
+ * Falls back to empty array if commit history is insufficient.
+ *
+ * @param cwd - Working directory of the repository
+ * @returns   - Array of file paths that were merged
+ */
+export declare function getMergedFiles(cwd: string): Promise<string[]>;
+//# sourceMappingURL=git-utils.d.ts.map

package/dist/git/git-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-utils.d.ts","sourceRoot":"","sources":["../../src/git/git-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAUH,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAUD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CA2BxF;AAMD;;;;;GAKG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAcrD;AAMD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,UAAU,CAOjE;AAMD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAK9D;AAMD;;;;GAIG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAmBtD;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBnC;AAMD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAY9F;AAMD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAY7F;AAMD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,SAAyB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAsBzH;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAarF;AAMD;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE3D;AAMD;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAexE;AAMD;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAWpF;AAMD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA0BnE"}