@denisvieiradev/gitwise-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,840 @@
+import { L as LLMProvider, P as ProviderConfig, M as ModelTier } from './types-DnMpR1qf.js';
+export { a as LLMChatRequest, b as LLMChatResponse, c as ModelConfig } from './types-DnMpR1qf.js';
+
+declare const EXIT_CODES: Readonly<Record<string, number>>;
+interface GitwiseErrorArgs {
+    code: string;
+    message: string;
+    exitCode?: number;
+    cause?: unknown;
+    details?: Record<string, unknown>;
+}
+declare class GitwiseError extends Error {
+    readonly code: string;
+    readonly exitCode: number;
+    readonly cause?: unknown;
+    readonly details?: Record<string, unknown>;
+    constructor(args: GitwiseErrorArgs);
+    toJSON(): {
+        name: string;
+        code: string;
+        exitCode: number;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+}
+declare function wrapError(err: unknown): GitwiseError;
+
+declare function setVerbose(enabled: boolean): void;
+declare function isVerbose(): boolean;
+declare function info(message: string, context?: Record<string, unknown>): void;
+declare function error(message: string, context?: Record<string, unknown>): void;
+declare function warn(message: string, context?: Record<string, unknown>): void;
+declare function debug(message: string, context?: Record<string, unknown>): void;
+
+declare function fileExists(filePath: string): Promise<boolean>;
+declare function readJSON<T>(filePath: string): Promise<T>;
+declare function writeJSON<T>(filePath: string, data: T): Promise<void>;
+declare function ensureDir(dirPath: string): Promise<void>;
+
+declare function getBranch(cwd: string): Promise<string>;
+declare function createBranch(cwd: string, branchName: string, startPoint?: string): Promise<void>;
+declare function checkout(cwd: string, branchName: string): Promise<void>;
+declare function checkoutForce(cwd: string, branchName: string): Promise<void>;
+declare function resetHard(cwd: string, ref: string): Promise<void>;
+declare function getDiff(cwd: string, base?: string): Promise<string>;
+declare function getStagedDiff(cwd: string): Promise<string>;
+declare function getLog(cwd: string, range?: string, maxCount?: number): Promise<string>;
+declare function add(cwd: string, files: string[]): Promise<void>;
+/**
+ * Write the current index to a tree object and return its SHA. Captures the
+ * fully-staged state so individual paths can later be re-staged from it via
+ * the index alone, without ever reading the working tree.
+ */
+declare function writeTree(cwd: string): Promise<string>;
+/**
+ * Stage the given paths into the index from a tree object, without touching
+ * the working tree. Unlike `git add`, this never reads the worktree, so a path
+ * that no longer matches a worktree file — a staged-then-deleted file, a staged
+ * deletion, or a planned path that was never staged — is handled by the index
+ * (added, removed, or no-op'd) instead of aborting with
+ * "pathspec did not match any files". No-ops when `files` is empty.
+ */
+declare function stagePathsFromTree(cwd: string, tree: string, files: string[]): Promise<void>;
+declare function commit$1(cwd: string, message: string): Promise<string>;
+declare function status(cwd: string): Promise<string>;
+declare function push(cwd: string, remote: string, branch: string): Promise<void>;
+declare function fetch(cwd: string, remote: string): Promise<void>;
+declare function getChangedFiles(cwd: string): Promise<string[]>;
+interface ChangedFile {
+    file: string;
+    indexStatus: string;
+    workTreeStatus: string;
+}
+declare function parseStatus(cwd: string): Promise<ChangedFile[]>;
+declare function getStagedFiles(cwd: string): Promise<ChangedFile[]>;
+declare function resetStaged(cwd: string): Promise<void>;
+declare function getStagedFilesList(cwd: string): Promise<string[]>;
+declare function getUnstagedFiles(cwd: string): Promise<ChangedFile[]>;
+declare function getLatestTag(cwd: string): Promise<string | null>;
+declare function createTag(cwd: string, tag: string, message: string, options?: {
+    signed?: boolean;
+}): Promise<void>;
+declare function tagExists(cwd: string, tag: string): Promise<boolean>;
+declare function pushWithTags(cwd: string, remote: string, branch: string): Promise<void>;
+declare function mergeNoFf(cwd: string, source: string): Promise<void>;
+declare function branchExists(cwd: string, branch: string): Promise<boolean>;
+declare function headSha(cwd: string): Promise<string>;
+declare function resetSoft(cwd: string, ref: string): Promise<void>;
+declare function stashPushNamed(cwd: string, message: string): Promise<void>;
+declare function stashList(cwd: string): Promise<string>;
+declare function stashApplyNamed(cwd: string, stashName: string): Promise<void>;
+declare function stashPopNamed(cwd: string, stashName: string): Promise<void>;
+declare function stashDropNamed(cwd: string, stashName: string): Promise<void>;
+/**
+ * Force-remove all untracked files and directories from the working tree.
+ * Used before stash pop in compensate paths to avoid "would be overwritten"
+ * conflicts from files that were left untracked after reset --hard.
+ */
+declare function cleanForced(cwd: string): Promise<void>;
+/**
+ * Read a file's contents at `HEAD` via `git show HEAD:<path>`. Returns `null`
+ * when the path does not exist in the HEAD tree (so callers can distinguish
+ * "missing in HEAD" from "exists but empty"). Bypasses the helper `run()` to
+ * preserve trailing newlines, which the working-tree validators compare
+ * byte-for-byte.
+ */
+declare function showFileAtHead(cwd: string, path: string): Promise<string | null>;
+declare function deleteBranch(cwd: string, branch: string, force?: boolean): Promise<void>;
+/**
+ * Is `branch` fully reachable from `target`? Resolves to true when every commit
+ * on `branch` is already in `target` (i.e., the merge would be a no-op). Used
+ * by abortRelease to refuse deleting a release branch that still has commits
+ * not present in main/develop.
+ */
+declare function isBranchMerged(cwd: string, branch: string, target: string): Promise<boolean>;
+/**
+ * Detect the base branch of the repository (main or master).
+ * Returns 'main' if both exist, falls back to 'master', throws if neither exists.
+ */
+declare function detectBaseBranch(cwd: string): Promise<string>;
+interface ApplyCommitParams {
+    message: string;
+    files: string[];
+    cwd: string;
+}
+/**
+ * Stage the given files and create a commit.
+ * Throws a typed error on hook failure or other git errors.
+ */
+declare function applyCommit(params: ApplyCommitParams): Promise<void>;
+
+type git_ApplyCommitParams = ApplyCommitParams;
+type git_ChangedFile = ChangedFile;
+declare const git_add: typeof add;
+declare const git_applyCommit: typeof applyCommit;
+declare const git_branchExists: typeof branchExists;
+declare const git_checkout: typeof checkout;
+declare const git_checkoutForce: typeof checkoutForce;
+declare const git_cleanForced: typeof cleanForced;
+declare const git_createBranch: typeof createBranch;
+declare const git_createTag: typeof createTag;
+declare const git_deleteBranch: typeof deleteBranch;
+declare const git_detectBaseBranch: typeof detectBaseBranch;
+declare const git_fetch: typeof fetch;
+declare const git_getBranch: typeof getBranch;
+declare const git_getChangedFiles: typeof getChangedFiles;
+declare const git_getDiff: typeof getDiff;
+declare const git_getLatestTag: typeof getLatestTag;
+declare const git_getLog: typeof getLog;
+declare const git_getStagedDiff: typeof getStagedDiff;
+declare const git_getStagedFiles: typeof getStagedFiles;
+declare const git_getStagedFilesList: typeof getStagedFilesList;
+declare const git_getUnstagedFiles: typeof getUnstagedFiles;
+declare const git_headSha: typeof headSha;
+declare const git_isBranchMerged: typeof isBranchMerged;
+declare const git_mergeNoFf: typeof mergeNoFf;
+declare const git_parseStatus: typeof parseStatus;
+declare const git_push: typeof push;
+declare const git_pushWithTags: typeof pushWithTags;
+declare const git_resetHard: typeof resetHard;
+declare const git_resetSoft: typeof resetSoft;
+declare const git_resetStaged: typeof resetStaged;
+declare const git_showFileAtHead: typeof showFileAtHead;
+declare const git_stagePathsFromTree: typeof stagePathsFromTree;
+declare const git_stashApplyNamed: typeof stashApplyNamed;
+declare const git_stashDropNamed: typeof stashDropNamed;
+declare const git_stashList: typeof stashList;
+declare const git_stashPopNamed: typeof stashPopNamed;
+declare const git_stashPushNamed: typeof stashPushNamed;
+declare const git_status: typeof status;
+declare const git_tagExists: typeof tagExists;
+declare const git_writeTree: typeof writeTree;
+declare namespace git {
+  export { type git_ApplyCommitParams as ApplyCommitParams, type git_ChangedFile as ChangedFile, git_add as add, git_applyCommit as applyCommit, git_branchExists as branchExists, git_checkout as checkout, git_checkoutForce as checkoutForce, git_cleanForced as cleanForced, commit$1 as commit, git_createBranch as createBranch, git_createTag as createTag, git_deleteBranch as deleteBranch, git_detectBaseBranch as detectBaseBranch, git_fetch as fetch, git_getBranch as getBranch, git_getChangedFiles as getChangedFiles, git_getDiff as getDiff, git_getLatestTag as getLatestTag, git_getLog as getLog, git_getStagedDiff as getStagedDiff, git_getStagedFiles as getStagedFiles, git_getStagedFilesList as getStagedFilesList, git_getUnstagedFiles as getUnstagedFiles, git_headSha as headSha, git_isBranchMerged as isBranchMerged, git_mergeNoFf as mergeNoFf, git_parseStatus as parseStatus, git_push as push, git_pushWithTags as pushWithTags, git_resetHard as resetHard, git_resetSoft as resetSoft, git_resetStaged as resetStaged, git_showFileAtHead as showFileAtHead, git_stagePathsFromTree as stagePathsFromTree, git_stashApplyNamed as stashApplyNamed, git_stashDropNamed as stashDropNamed, git_stashList as stashList, git_stashPopNamed as stashPopNamed, git_stashPushNamed as stashPushNamed, git_status as status, git_tagExists as tagExists, git_writeTree as writeTree };
+}
+
+interface CreatePRParams {
+    title: string;
+    body: string;
+    base?: string;
+    cwd: string;
+    draft?: boolean;
+}
+interface PRResult {
+    url: string;
+}
+declare function isGhAvailable(): Promise<boolean>;
+declare function getGhVersion(): Promise<string | null>;
+declare function createPR(params: CreatePRParams): Promise<PRResult>;
+interface UpdatePRParams {
+    prNumber: string | number;
+    title?: string;
+    body?: string;
+    cwd: string;
+}
+declare function updatePR(params: UpdatePRParams): Promise<PRResult>;
+declare function getPrUrl(prNumber: string | number, cwd: string): Promise<string>;
+interface CreateReleaseParams {
+    tag: string;
+    title: string;
+    body: string;
+    cwd: string;
+}
+declare function createGitHubRelease(params: CreateReleaseParams): Promise<PRResult>;
+declare const openPr: typeof createPR;
+
+type github_CreatePRParams = CreatePRParams;
+type github_CreateReleaseParams = CreateReleaseParams;
+type github_PRResult = PRResult;
+type github_UpdatePRParams = UpdatePRParams;
+declare const github_createGitHubRelease: typeof createGitHubRelease;
+declare const github_createPR: typeof createPR;
+declare const github_getGhVersion: typeof getGhVersion;
+declare const github_getPrUrl: typeof getPrUrl;
+declare const github_isGhAvailable: typeof isGhAvailable;
+declare const github_openPr: typeof openPr;
+declare const github_updatePR: typeof updatePR;
+declare namespace github {
+  export { type github_CreatePRParams as CreatePRParams, type github_CreateReleaseParams as CreateReleaseParams, type github_PRResult as PRResult, type github_UpdatePRParams as UpdatePRParams, github_createGitHubRelease as createGitHubRelease, github_createPR as createPR, github_getGhVersion as getGhVersion, github_getPrUrl as getPrUrl, github_isGhAvailable as isGhAvailable, github_openPr as openPr, github_updatePR as updatePR };
+}
+
+declare function loadEnv(projectRoot: string): Promise<void>;
+declare function writeEnvVar(projectRoot: string, key: string, value: string): Promise<void>;
+declare function readEnvVar(projectRoot: string, key: string): Promise<string | undefined>;
+/**
+ * Read a key from process.env, with optional fallback to the project .env file.
+ */
+declare function read(key: string, projectRoot?: string): Promise<string | undefined>;
+
+declare const env_loadEnv: typeof loadEnv;
+declare const env_read: typeof read;
+declare const env_readEnvVar: typeof readEnvVar;
+declare const env_writeEnvVar: typeof writeEnvVar;
+declare namespace env {
+  export { env_loadEnv as loadEnv, env_read as read, env_readEnvVar as readEnvVar, env_writeEnvVar as writeEnvVar };
+}
+
+interface Step<T> {
+    name: string;
+    apply: () => Promise<T>;
+    compensate: (result: T) => Promise<void>;
+}
+interface Logger {
+    warn(message: string, context?: Record<string, unknown>): void;
+}
+interface RollbackFailure {
+    step: string;
+    error: unknown;
+}
+interface RollbackResult {
+    partial: boolean;
+    failures: RollbackFailure[];
+}
+declare class Transaction {
+    private readonly applied;
+    run<T>(step: Step<T>): Promise<T>;
+    get size(): number;
+    rollback(reason: GitwiseError, logger: Logger): Promise<RollbackResult>;
+}
+
+declare const STALE_LOCK_MS: number;
+interface LockPayload {
+    pid: number;
+    host: string;
+    command: string;
+    acquiredAt: string;
+}
+interface AcquireRepoLockOptions {
+    command?: string;
+    staleMs?: number;
+    isProcessAlive?: (pid: number) => boolean;
+    now?: () => Date;
+    /**
+     * Test seam: invoked once, awaited, immediately after a stale lock is
+     * unlinked and immediately before the re-acquire attempt. Lets tests
+     * deterministically simulate another process re-creating the lock inside
+     * the reclaim window (the `EEXIST` on `attempt >= 1` → REPO_LOCKED path).
+     * Unset in production (no-op).
+     */
+    onReclaim?: () => void | Promise<void>;
+}
+declare function acquireRepoLock(repoPath: string, options?: AcquireRepoLockOptions): Promise<() => Promise<void>>;
+
+declare function resolveClaudeBinary(customPath?: string): string | null;
+
+/**
+ * Release-lifecycle strategy abstraction. Narrow on purpose (per ADR-002):
+ * it covers branch creation, merge targets, and the develop-branch requirement
+ * — nothing else from the broader FlowStrategy design lives here yet.
+ */
+type ReleaseStrategyName = "github-flow" | "gitflow";
+interface ReleaseStrategy {
+    readonly name: ReleaseStrategyName;
+    /** Optional release branch to create during prepare; null = no branch. */
+    releaseBranchFor(version: string): string | null;
+    /** Branches to merge the release into during finish, in order. */
+    mergeTargets(mainBranch: string, developBranch?: string): string[];
+    /** True if a develop branch must exist for this strategy to run. */
+    requiresDevelop(): boolean;
+}
+declare function createReleaseStrategy(name: ReleaseStrategyName): ReleaseStrategy;
+
+type Language = "en" | "pt-br" | "es" | "fr" | "de" | "zh" | "ja" | "ko";
+type CommitConvention = "conventional" | "gitmoji" | "angular" | "kernel" | "custom";
+interface ModelConfig {
+    fast: string;
+    balanced: string;
+    powerful: string;
+}
+/** Persisted in ~/.gitwise/config.json */
+interface UserConfig {
+    provider: "api" | "claude-code";
+    claudeCliPath?: string;
+    models: ModelConfig;
+    language: Language;
+    defaultBaseBranch?: string;
+    commitConvention: CommitConvention;
+}
+/** Loaded from <cwd>/.gitwise.json — all fields are optional */
+interface RepoConfig {
+    models?: Partial<ModelConfig>;
+    language?: Language;
+    defaultBaseBranch?: string;
+    commitConvention?: CommitConvention;
+    templatesPath?: string;
+    /** When true, applyRelease() propagates the new version to all packages/* */
+    workspacePropagation?: boolean;
+    /** Release lifecycle strategy. Unset = "github-flow" at the consumer level. */
+    releaseStrategy?: ReleaseStrategyName;
+    /** Develop branch name for gitflow; consumers default to "develop" when unset. */
+    developBranch?: string;
+}
+/** The merged result of UserConfig + RepoConfig overrides */
+interface MergedConfig extends UserConfig {
+    templatesPath?: string;
+    releaseStrategy?: ReleaseStrategyName;
+    developBranch?: string;
+}
+declare const DEFAULT_USER_CONFIG: UserConfig;
+
+interface GetMergedConfigOptions {
+    cwd: string;
+    homeDir?: string;
+}
+/**
+ * Load and merge config:
+ *   1. Start from defaults
+ *   2. Layer user config (~/.gitwise/config.json)
+ *   3. Layer repo config (<cwd>/.gitwise.json)
+ *
+ * Note: the API key is NOT included in the returned config.
+ */
+declare function getMergedConfig(options: GetMergedConfigOptions): Promise<MergedConfig>;
+/**
+ * Read the Anthropic API key from process.env first, then ~/.gitwise/.env.
+ * Returns undefined if not found anywhere.
+ */
+declare function getApiKey(homeDir?: string): Promise<string | undefined>;
+
+declare function readUserConfig(homeDir?: string): Promise<UserConfig>;
+declare function writeUserConfig(partial: Partial<UserConfig>, homeDir?: string): Promise<void>;
+/**
+ * Write ANTHROPIC_API_KEY to ~/.gitwise/.env with file mode 0600.
+ * Keys MUST NOT be written to config.json.
+ *
+ * Note: writeEnvVar(root, key, val) writes to root/.gitwise/.env.
+ * We pass homeDir (default: os.homedir()) so the file lands at ~/.gitwise/.env.
+ */
+declare function writeApiKey(value: string, homeDir?: string): Promise<void>;
+
+declare function readRepoConfig(cwd: string): Promise<RepoConfig | null>;
+
+interface LoadTemplateOptions {
+    /** Override the user-global templates directory (default: ~/.gitwise/templates). */
+    templatesPath?: string;
+    /** Repo root for repo-level override lookup (default: process.cwd()). */
+    repoRoot?: string;
+}
+/**
+ * Load a template by name, applying 3-level precedence:
+ *   1. <repoRoot>/.gitwise/templates/<name>.md  (highest priority)
+ *   2. templatesPath (default: ~/.gitwise/templates/<name>.md)
+ *   3. packages/core/templates/<name>.md         (bundled fallback)
+ *
+ * Returns the raw template string (not interpolated).
+ * Throws TEMPLATE_NOT_FOUND if no file found at any level.
+ */
+declare function loadTemplate(name: string, options?: LoadTemplateOptions): Promise<string>;
+/**
+ * Load and interpolate a template in one call.
+ */
+declare function loadAndInterpolate(name: string, ctx: Record<string, string>, options?: LoadTemplateOptions): Promise<string>;
+
+/**
+ * Replace {{var}} placeholders in a template string with values from ctx.
+ * Unknown placeholders are left untouched.
+ */
+declare function interpolate(template: string, ctx: Record<string, string>): string;
+
+interface CommitEntry {
+    message: string;
+    description?: string;
+    files: string[];
+}
+interface CommitPlan {
+    kind: "single" | "split";
+    commits: CommitEntry[];
+    tokens: {
+        input: number;
+        output: number;
+    };
+}
+type SplitMode = "auto" | "never" | "always";
+interface CommitOptions {
+    cwd: string;
+    provider: LLMProvider;
+    prompt?: string;
+    split?: SplitMode;
+    push?: boolean;
+    commitConvention?: string;
+    templatesPath?: string;
+    repoRoot?: string;
+    feedbackHint?: string;
+    generateAlternatives?: boolean;
+}
+interface CommitAlternatives {
+    kind: "alternatives";
+    options: string[];
+    tokens: {
+        input: number;
+        output: number;
+    };
+}
+interface ApplyCommitPlanOptions {
+    push?: boolean;
+    remote?: string;
+}
+interface LLMSingleResponse {
+    type: "single";
+    message: string;
+}
+interface LLMPlanResponse {
+    type: "plan";
+    commits: Array<{
+        message: string;
+        description?: string;
+        files: string[];
+    }>;
+}
+type LLMCommitResponse = LLMSingleResponse | LLMPlanResponse;
+declare function parseCommitResponse(raw: string): LLMCommitResponse;
+declare function commit(opts: CommitOptions): Promise<CommitPlan | CommitAlternatives>;
+interface CommitStepResult {
+    priorSha: string;
+    newSha: string;
+}
+/**
+ * Transaction step that saves a named git stash as a backup of the pre-split
+ * working tree, then immediately re-applies the stash so the normal flow can
+ * continue with the same staged state.  The predictable stash name
+ * (`gitwise/split-<ISO8601>`) lets `docs/recovery.md` guide manual recovery
+ * when the compensate fires.
+ *
+ * compensate: resets the index and working tree to HEAD (no-data-loss because
+ * the stash is still present), then pops the named stash to restore the exact
+ * pre-split state.
+ */
+declare function takeNamedStashStep(cwd: string, stashName: string): Step<void>;
+/**
+ * Transaction step that stages the given group's files and creates one commit.
+ *
+ * Staging goes through `stagedTree` — a tree object captured from the fully
+ * staged index before the split unstaged everything — via the index alone
+ * (`git reset <tree> -- <paths>`). This never reads the working tree, so a
+ * planned path that no longer matches a worktree file (a staged-then-deleted
+ * file, a staged deletion, or a path the plan named but that was never staged)
+ * is handled by the index instead of aborting the whole commit with
+ * "pathspec did not match any files". A group whose paths contribute nothing
+ * to the index (e.g. all phantom paths) is skipped rather than failing on an
+ * empty commit.
+ *
+ * apply  — records the prior HEAD SHA (for compensate) and the new HEAD SHA
+ *           (as evidence of the created commit) in the result. When the group
+ *           stages nothing, `newSha === priorSha` and no commit is made.
+ * compensate — runs `git reset --soft <priorSha>` to undo only this commit
+ *              while preserving the staged delta for potential retry.
+ */
+declare function applyOneCommitStep(entry: CommitEntry, cwd: string, stagedTree: string): Step<CommitStepResult>;
+declare function applyCommitPlan(plan: CommitPlan, opts: ApplyCommitPlanOptions & {
+    cwd: string;
+}): Promise<void>;
+
+interface ReviewFinding {
+    file?: string;
+    line?: string;
+    description: string;
+    suggestion?: string;
+}
+interface ReviewResult {
+    critical: ReviewFinding[];
+    suggestions: ReviewFinding[];
+    nitpicks: ReviewFinding[];
+    markdown: string;
+    tokens: {
+        input: number;
+        output: number;
+    };
+}
+interface ReviewOptions {
+    cwd: string;
+    provider: LLMProvider;
+    baseBranch?: string;
+    prompt?: string;
+    tier?: "fast" | "balanced" | "powerful";
+    templatesPath?: string;
+    repoRoot?: string;
+}
+declare function review(opts: ReviewOptions): Promise<ReviewResult>;
+
+interface PrDraft {
+    title: string;
+    body: string;
+    existingPrNumber?: number;
+    tokens: {
+        input: number;
+        output: number;
+    };
+}
+interface PrOptions {
+    cwd: string;
+    provider: LLMProvider;
+    baseBranch?: string;
+    prompt?: string;
+    templatesPath?: string;
+    repoRoot?: string;
+}
+interface ApplyPrOptions {
+    cwd: string;
+    draft?: boolean;
+    baseBranch?: string;
+}
+interface ApplyPrResult {
+    url: string;
+}
+declare function pr(opts: PrOptions): Promise<PrDraft>;
+declare function applyPr(draft: PrDraft, opts: ApplyPrOptions): Promise<ApplyPrResult>;
+
+/**
+ * On-disk handoff between `gw release prepare` and `gw release finish`.
+ * Lifecycle and validation rules are defined in ADR-003 — written last in
+ * prepare, deleted first in finish; never edit by hand.
+ */
+interface PersistedReleasePlan {
+    schema: 1;
+    strategy: ReleaseStrategyName;
+    currentVersion: string;
+    newVersion: string;
+    suggestedBump: BumpType;
+    changelog: string;
+    notes: string;
+    commits: string;
+    preparedAt: string;
+    baseCommit: string;
+    targetBranch: string;
+    releaseBranchCreated: boolean;
+    tokens: {
+        input: number;
+        output: number;
+    };
+}
+declare function saveReleasePlan(cwd: string, plan: PersistedReleasePlan): Promise<void>;
+declare function loadReleasePlan(cwd: string): Promise<PersistedReleasePlan | null>;
+declare function deleteReleasePlan(cwd: string): Promise<void>;
+/**
+ * Ensure `entry` is covered by the repo's `.gitignore`. Coverage is detected
+ * by an exact-match line OR a wildcard for the entry's directory (`dir/` or
+ * `dir/*`). When appending, prints a one-line notice and preserves the file's
+ * existing trailing-newline behavior.
+ */
+declare function ensureGitignored(cwd: string, entry: string): Promise<void>;
+
+type BumpType = "major" | "minor" | "patch";
+interface ReleasePlan {
+    suggestedBump: BumpType;
+    newVersion: string;
+    currentVersion: string;
+    changelog: string;
+    notes: string;
+    commits: string;
+    tokens: {
+        input: number;
+        output: number;
+    };
+}
+interface ReleaseOptions {
+    cwd: string;
+    provider: LLMProvider;
+    bump?: BumpType;
+    language?: string;
+    templatesPath?: string;
+    repoRoot?: string;
+    workspacePropagation?: boolean;
+}
+interface ApplyReleaseOptions {
+    cwd: string;
+    tagAndPush?: boolean;
+    createGhRelease?: boolean;
+    workspacePropagation?: boolean;
+    /** Forwarded to finishRelease. Default true. Set false only for testing. */
+    signTags?: boolean;
+}
+declare function bumpVersion(current: string, type: BumpType): string;
+/**
+ * Heuristic bump from commit log strings.
+ * BREAKING CHANGE / ! marker → major
+ * feat: → minor
+ * fix:/chore:/etc → patch
+ */
+declare function heuristicBump(commits: string): BumpType;
+/**
+ * @deprecated Prefer the explicit two-phase lifecycle ({@link prepareRelease}
+ * → caller-supplied confirm → {@link finishRelease}) or the unified
+ * {@link runReleaseInProcess} helper. Kept exported so the legacy skill script
+ * and any external callers using `release()` + `applyRelease()` keep working;
+ * a future task may collapse it into `prepareRelease`.
+ */
+declare function release(opts: ReleaseOptions): Promise<ReleasePlan>;
+interface PrepareReleaseOptions extends ReleaseOptions {
+    /** Strategy override; if omitted, resolved from RepoConfig (default "github-flow"). */
+    strategy?: ReleaseStrategyName;
+    /** Develop branch name override; if omitted, resolved from RepoConfig (default "develop"). */
+    developBranch?: string;
+}
+/**
+ * Run the planning half of the two-phase release lifecycle (ADR-001).
+ *
+ * Resolves the active strategy, validates preconditions (clean tree, develop
+ * exists for gitflow, no pre-existing release branch), runs the LLM planner
+ * via {@link release}, then drives every side-effectful step inside a single
+ * {@link Transaction} under a `.gitwise/.lock`. On any failure the
+ * transaction rolls back in LIFO order: plan file unlinked, release commit
+ * reset (gitflow), `.gitignore` reverted, CHANGELOG.md reverted, workspace
+ * + root manifests reverted, notes file unlinked, release branch deleted.
+ * Compensate failures surface as a `ROLLBACK_PARTIAL` log warning emitted by
+ * the transaction itself; the original cause is always rethrown unchanged.
+ *
+ * ADR-004 §Decision item 1: the release plan file is written LAST so its
+ * presence on disk is a contract that every preceding step succeeded.
+ */
+declare function prepareRelease(opts: PrepareReleaseOptions): Promise<PersistedReleasePlan>;
+/**
+ * @deprecated Prefer the explicit two-phase lifecycle ({@link prepareRelease}
+ * → caller-supplied confirm → {@link finishRelease}) or the unified
+ * {@link runReleaseInProcess} helper.
+ *
+ * Apply an in-memory {@link ReleasePlan} to the repository. Kept exported as
+ * a thin adapter so the legacy skill script and any external callers that
+ * still pair `release()` with `applyRelease()` keep working. Internally this
+ * builds a {@link PersistedReleasePlan} from the in-memory plan, writes it
+ * (and the user-editable notes file) to disk so {@link finishRelease} can
+ * consume it, and then delegates the mutation pipeline to
+ * {@link finishRelease}. Both phases now travel through the same code path.
+ *
+ * Preflight: throws `WORKING_TREE_DIRTY` if the working tree has uncommitted
+ * changes, and (when `tagAndPush` is enabled) `TAG_EXISTS` if the target
+ * `v<newVersion>` ref already exists. Both checks run before any file or git
+ * mutation so a failed run leaves the repo untouched.
+ */
+declare function applyRelease(plan: ReleasePlan, opts: ApplyReleaseOptions): Promise<void>;
+interface FinishReleaseOptions {
+    cwd: string;
+    /** Tag locally and push (with `--follow-tags`); default true. */
+    tagAndPush?: boolean;
+    /** Invoke `gh release create` after the tag is pushed; default true. */
+    createGhRelease?: boolean;
+    /** Delete the local release branch after gitflow merges; default true. Ignored for github-flow. */
+    deleteReleaseBranch?: boolean;
+    /**
+     * Propagate the new root version into every workspace package's
+     * `package.json` (and sibling `plugin.json`) before the github-flow release
+     * commit, then stage exactly those manifests alongside the root files so
+     * they all land in the same commit. Workspace layout is read from
+     * `package.json.workspaces` (array or yarn-style `{ packages: [...] }`);
+     * falls back to `packages/*` when the field is missing. Default false.
+     * Ignored for gitflow because prepare already committed manifests on the
+     * release branch.
+     */
+    workspacePropagation?: boolean;
+    /**
+     * Sign the release tag with the local GPG key (`git tag -s`). Default true.
+     * Set to false only for testing or environments without a GPG key — a
+     * warning is emitted to stderr when signing is skipped.
+     */
+    signTags?: boolean;
+}
+/**
+ * Consume a persisted release plan and finalize the release (ADR-001 / ADR-003).
+ *
+ * Lifecycle: load plan → validate against live repo state → reload notes from
+ * `.gitwise/release-<version>.md` → on github-flow, bump `package.json` and
+ * prepend the CHANGELOG entry then commit on the current branch → delete the
+ * plan file (BEFORE any irreversible operation — merges, tags, pushes — so a
+ * downstream failure cannot trigger a second `finish`; on gitflow this is
+ * effectively the same as deleting first because the github-flow block is
+ * skipped) → merge `plan.targetBranch` into every `strategy.mergeTargets`
+ * entry that isn't `targetBranch` itself → annotate the tag with the reloaded
+ * notes, push with `--follow-tags`, and on gitflow also push the develop
+ * branch → optionally create the GitHub release (graceful: failure logs but
+ * does not roll back) → on gitflow, delete the now fully-merged release
+ * branch unless `deleteReleaseBranch === false`.
+ *
+ * Throws typed errors before mutating anything: `NO_RELEASE_PLAN`,
+ * `STALE_PLAN_TAG_EXISTS`, `STALE_PLAN_BRANCH_MISMATCH`, `WORKING_TREE_DIRTY`,
+ * `STRATEGY_DEVELOP_MISSING`, plus `INVALID_PLAN_SCHEMA` / `INVALID_PLAN_JSON`
+ * surfaced by `loadReleasePlan`. On the github-flow path, a pre-commit hook
+ * failure during step 5's release commit surfaces as `COMMIT_HOOK_FAILURE`
+ * with the plan file STILL on disk — recover by resolving the hook issue
+ * and running `git reset --hard HEAD` to clear the partial manifest/CHANGELOG
+ * writes before re-running `gw release finish`, or run `gw release abort` to
+ * discard the in-flight release. Once the plan file is deleted at step 6, a
+ * failed strategy merge (typically gitflow's develop merge when develop has
+ * advanced) surfaces as `FINISH_MERGE_CONFLICT` — the repo is left mid-merge
+ * for manual recovery (`git merge --continue` then tag + push by hand) since
+ * the plan can no longer be re-run.
+ */
+declare function finishRelease(opts: FinishReleaseOptions): Promise<void>;
+interface AbortReleaseOptions {
+    cwd: string;
+    /** When true, also delete the release branch (gitflow only). Default false. */
+    deleteBranch?: boolean;
+}
+/**
+ * Discard an in-flight release (ADR-001 / ADR-003).
+ *
+ * Loads the persisted plan and removes it from disk. When `deleteBranch` is
+ * true AND prepare created a release branch, verifies that branch is fully
+ * merged into every strategy merge target (main, and develop for gitflow)
+ * BEFORE deleting the plan. If the branch still has unmerged commits, throws
+ * `RELEASE_BRANCH_UNMERGED` and leaves both the plan file and the branch in
+ * place so the user can recover. Notes (`.gitwise/release-<v>.md`) are never
+ * touched — the user may still want them.
+ */
+declare function abortRelease(opts: AbortReleaseOptions): Promise<void>;
+interface RunReleaseInProcessOptions extends PrepareReleaseOptions {
+    /**
+     * Resolved with the persisted plan after `prepareRelease` writes it. Return
+     * `false` (or have the promise reject with `p.isCancel`-style cancellation)
+     * to abort: the helper calls {@link abortRelease} which removes the plan
+     * file (and any gitflow release branch when `confirmAbortDeletesBranch` is
+     * true). The on-disk notes file is always preserved.
+     */
+    confirm: (plan: PersistedReleasePlan) => Promise<boolean> | boolean;
+    /** Forwarded to {@link finishRelease} when `confirm` returns true. */
+    finishOptions?: Omit<FinishReleaseOptions, "cwd">;
+    /**
+     * When `confirm` returns false on a gitflow plan, also delete the release
+     * branch that prepare created. Default false. Ignored for github-flow.
+     *
+     * Pass a callback to decide after the plan exists — useful for CLIs that
+     * want to ask "Also delete the release branch?" only when a gitflow
+     * release branch was actually created. The callback runs inside the abort
+     * paths (post-confirm-false and confirm-threw); errors thrown from it are
+     * treated as "do not delete" so the abort itself still completes.
+     */
+    confirmAbortDeletesBranch?: boolean | ((plan: PersistedReleasePlan) => Promise<boolean> | boolean);
+}
+/**
+ * Drive the two-phase release lifecycle inside a single process against the
+ * same plan written to and read from `.gitwise/release-plan.json`.
+ *
+ * Runs {@link prepareRelease}, awaits the caller-supplied `confirm` callback
+ * (which receives the persisted plan), and either calls {@link finishRelease}
+ * (confirm true) or {@link abortRelease} (confirm false / throws). On
+ * confirmed completion the plan file is deleted by `finishRelease`; on abort
+ * it is removed by `abortRelease`. The on-disk notes file
+ * (`.gitwise/release-<version>.md`) is preserved either way.
+ *
+ * This is the unified path used by both the legacy `applyRelease` adapter
+ * (auto-confirms) and the upcoming `gw release` CLI root action (task_09).
+ * Decoupling the prompt into a `confirm` callback keeps core free of CLI UI
+ * dependencies (e.g. `@clack/prompts`).
+ *
+ * Returns the persisted plan when the release was applied, or `null` if the
+ * caller declined via `confirm`.
+ */
+declare function runReleaseInProcess(opts: RunReleaseInProcessOptions): Promise<PersistedReleasePlan | null>;
+/**
+ * Step factory for atomically bumping the `version` field of a single
+ * manifest (package.json or sibling plugin.json) under a {@link Transaction}.
+ *
+ * `apply` reads the manifest's prior bytes (Buffer, not parsed JSON, so any
+ * trailing newline or formatting in the on-disk file is preserved verbatim
+ * for rollback), rewrites the `version` field in place via `writeJSON`, and
+ * returns the captured prior bytes as the step result. `compensate` writes
+ * those bytes back, restoring the file byte-for-byte regardless of what the
+ * apply path produced. Steps are intended to run sequentially so ordering is
+ * deterministic per ADR-004.
+ */
+declare function writeWorkspaceVersionStep(manifestPath: string, newVersion: string): Step<Buffer>;
+/**
+ * Propagate `version` into every workspace manifest under a {@link Transaction}
+ * so that a write failure on `packages[N]/package.json` reliably restores the
+ * bytes of every previously-written manifest (ADR-004 §Decision item 2).
+ *
+ * Acquires `.gitwise/.lock` for the duration of the flow and releases it in a
+ * `finally` block so a concurrent gitwise invocation fails fast with
+ * `REPO_LOCKED`. Writes are sequential (not concurrent) to keep ordering
+ * deterministic. On any apply failure, runs `Transaction.rollback` BEFORE
+ * propagating the error so callers always see the original cause; a partial
+ * rollback (compensate itself fails) surfaces as a single `ROLLBACK_PARTIAL`
+ * warning emitted by `Transaction.rollback`.
+ *
+ * Returns the cwd-relative paths of every manifest the function actually
+ * modified so the caller can stage exactly those files (never a directory
+ * sweep, which would also pick up unrelated untracked work).
+ */
+declare function propagateVersionToWorkspaces(cwd: string, version: string): Promise<string[]>;
+/**
+ * Detect whether `cwd` is the root of an npm/pnpm/yarn workspaces monorepo
+ * (or otherwise uses a `packages/*` layout with at least one nested
+ * `package.json`). Single source of truth for the CLI and the skills runner
+ * when auto-defaulting `workspacePropagation` per ADR-005.
+ *
+ * Returns `true` exactly when {@link propagateVersionToWorkspaces} would have
+ * at least one manifest to rewrite — i.e. some workspace pattern in the root
+ * `package.json` (array form, yarn-object `{ packages: [...] }` form, or the
+ * `packages/*` fallback) resolves to a directory containing a `package.json`.
+ */
+declare function detectWorkspaceRoot(cwd: string): Promise<boolean>;
+
+declare function createProvider(config: ProviderConfig): LLMProvider;
+
+declare const COMMAND_TIER_MAP: Record<string, ModelTier>;
+declare function resolveModelTier(command: string): ModelTier;
+declare const SUPPORTED_COMMANDS: (keyof typeof COMMAND_TIER_MAP)[];
+
+declare const version: string;
+declare const __placeholder__: unique symbol;
+
+export { type AbortReleaseOptions, type AcquireRepoLockOptions, type ApplyCommitParams, type ApplyCommitPlanOptions, type ApplyPrOptions, type ApplyPrResult, type ApplyReleaseOptions, type BumpType, type ChangedFile, type CommitAlternatives, type CommitConvention, type CommitEntry, type CommitOptions, type CommitPlan, type CommitStepResult, type ModelConfig as ConfigModelConfig, type CreatePRParams, type CreateReleaseParams, DEFAULT_USER_CONFIG, EXIT_CODES, type FinishReleaseOptions, GitwiseError, type GitwiseErrorArgs, LLMProvider, type Language, type LoadTemplateOptions, type LockPayload, type Logger, type MergedConfig, ModelTier, type PRResult, type PersistedReleasePlan, type PrDraft, type PrOptions, type PrepareReleaseOptions, ProviderConfig, type ReleaseOptions, type ReleasePlan, type ReleaseStrategy, type ReleaseStrategyName, type RepoConfig, type ReviewFinding, type ReviewOptions, type ReviewResult, type RollbackFailure, type RollbackResult, type RunReleaseInProcessOptions, STALE_LOCK_MS, SUPPORTED_COMMANDS, type SplitMode, type Step, Transaction, type UpdatePRParams, type UserConfig, __placeholder__, abortRelease, acquireRepoLock, applyCommitPlan, applyOneCommitStep, applyPr, applyRelease, bumpVersion, commit, createProvider, createReleaseStrategy, debug, deleteReleasePlan, detectWorkspaceRoot, ensureDir, ensureGitignored, env, error, fileExists, finishRelease, getApiKey, getMergedConfig, git, github, heuristicBump, info, interpolate, isVerbose, loadAndInterpolate, loadReleasePlan, loadTemplate, parseCommitResponse, pr, prepareRelease, propagateVersionToWorkspaces, readJSON, readRepoConfig, readUserConfig, release, resolveClaudeBinary, resolveModelTier, review, runReleaseInProcess, saveReleasePlan, setVerbose, stashList, takeNamedStashStep, version, warn, wrapError, writeApiKey, writeJSON, writeUserConfig, writeWorkspaceVersionStep };