import { ExecutorContextInterface, LifecycleExecutor } from '@qlover/fe-corekit';
import { ScriptPluginProps, ScriptPlugin, ScriptSharedInterface, ScriptContextInterface, ScriptContext, TemplateEngine, RenderFn, ShellInterface } from '@qlover/scripts-context';
export { ScriptPlugin } from '@qlover/scripts-context';
import { CommitField } from 'gitlog';
import { LoggerInterface } from '@qlover/logger';
import { OptionValues } from 'commander';

/**
 * @module WorkspaceInterface
 * @description Core data model for a monorepo package in a release run
 *
 * Represents one publishable workspace discovered by the {@link Workspaces}
 * plugin and passed through {@link ChangesetVersion} and {@link Github}.
 *
 * Typical lifecycle fields:
 * - `version` / `newVersion` — before and after `changeset version`
 * - `lastTag` — git baseline for changelog generation
 * - `dependencyRelease` — internal dependent bumped only because a dependency changed
 */

interface WorkspaceInterface {
    /**
     * Package name from package.json
     */
    name: string;
    /**
     * Current version from package.json before bump
     */
    version: string;
    /**
     * Version after `changeset version`, read from package.json on disk.
     *
     * - Before bump: usually undefined
     * - After bump: latest version on disk; may equal `version` if unchanged
     */
    newVersion?: string;
    /**
     * The relative path of the workspace
     */
    path: string;
    /**
     * The absolute path of the workspace
     */
    root: string;
    /**
     * The package.json of the workspace
     */
    packageJson: PackageJson;
    /**
     * Release tag name after version bump (for example `pkg@1.0.1`).
     *
     * Set by ChangesetVersion.mergeWorkspaces only when `newVersion` differs
     * from `version`. Not available before `changeset version` completes.
     */
    tagName?: string;
    /**
     * Previous release tag used as the git changelog baseline
     */
    lastTag?: string;
    /**
     * The changelog of the workspace
     *
     */
    changelog?: string;
    /**
     * Whether this workspace is an internal dependent bumped only because a
     * dependency was released (not directly changed in git).
     *
     * Set by the Workspaces plugin when `includeDependencyReleases` is enabled.
     * Processing rules depend on `changesetVersion.ignoreNonUpdatedPackages`:
     *
     * - `false`: included in changelog template flow and version bump logs
     * - `true`: tracked for restore only; skipped in changelog generation
     *
     * @default false
     */
    dependencyRelease?: boolean;
    /**
     * Package name of the direct dependency that caused this `dependencyRelease`.
     *
     * Set by Workspaces when appending dependents. ChangesetVersion uses it after
     * `changeset version` to fill `dependencyReleaseTemplate` with the source's
     * real `newVersion`.
     */
    dependencyReleaseOf?: string;
}

/**
 * Base configuration for Git-related plugins
 *
 * Extends ScriptPluginProps with generic options.
 *
 * @example
 * ```typescript
 * const config: GitBaseProps = {
 *   timeout: 5000
 * };
 * ```
 */
interface GitBaseProps extends ScriptPluginProps {
    /**
     * Environment variable name for GitHub API token
     * @deprecated This property is GitHub-specific, use a subclass if needed.
     */
    tokenRef?: string;
    /**
     * Timeout for API requests in milliseconds (generic)
     */
    timeout?: number;
}

/**
 * @module ReleaseFormatter
 * @description Template-based formatting for release branches, commits, and PRs
 *
 * Centralizes string formatting for the GitHub release flow. Uses
 * {@link TemplateEngine} from `@qlover/scripts-context` with ES6-style
 * `${ path }` placeholders and variables from {@link BranchNameTplVars}.
 *
 * Responsibilities:
 * - **Branch/tag names**: `getReleaseBranch()` from `branchName` / `releaseTagName` templates
 * - **Commit message**: `getCommitMessage()` with optional `less` / `more` templates when
 *   workspace count exceeds 3
 * - **PR content**: `getPRTitle()` and `getPRBody()` with single- vs multi-workspace changelog
 *   formatting via `batchPRBody`
 *
 * Defaults are sourced from `releaseJson.github` in {@link defaults}.
 * {@link Github} constructs an instance and calls `setConfig()` in `onBefore`
 * with runtime context (`repoName`, `releaseId`, `env`, etc.).
 *
 * @example Branch name template variables
 * ```typescript
 * // Template: release/${repoName}-${releaseId}
 * // Variables: repoName, releaseId, timestamp, authorName, env, count, spaces
 * formatter.getReleaseBranch(workspaces);
 * ```
 *
 * @example Multi-workspace PR body
 * ```typescript
 * formatter.getPRBody(workspaces, releaseBranchResult, templateContext);
 * ```
 */

interface ReleaseFormatterConfig {
    /**
     * Repository name
     */
    repoName?: string;
    /**
     * Author name
     */
    authorName?: string;
    /**
     * Release environment
     */
    env?: string;
    /**
     * Unique ID for the current release run
     */
    releaseId?: string;
    /**
     * The branch name for batch release
     *
     * Template variables: see {@link BranchNameTplVars}
     *
     * @default `release/${repoName}-${releaseId}`
     */
    branchName?: string;
    /**
     * The tag name for batch release
     *
     * Template variables: see {@link BranchNameTplVars}
     *
     * @default `release-tag-${count}-patch-${releaseId}`
     */
    releaseTagName?: string;
    /**
     *
     * @default 'Release ${spaces}' */
    releaseName?: string;
    /**
     * Commit message template used when creating the release branch
     *
     * When configured as an object, supports `less` and `more` templates:
     * - `less`: used when workspace count is 3 or fewer
     * - `more`: used when workspace count exceeds 3
     *
     * Supports conventional commit structure: subject, body, and footer.
     *
     * **Object form is experimental.**
     *
     * @example Conventional commit layout
     * ```
     * <type>(<scope>): <subject>    <-- Header/Subject (required)
     *                               <-- blank line
     * <body>                        <-- detailed description (optional)
     *                               <-- blank line
     * <footer>                      <-- issue refs or BREAKING CHANGE (optional)
     * ```
     *
     * @example Full template string
     *
     * ```
     * \`\`\`
     * chore(release): bump ${worksapce[0].name} to v${worksapce[0].newVersion} and others
     *   -
     * \`\`\`
     * ```
     *
     * By default, lists all package names and versions in the commit message.
     *
     * @default `'chore(release): ${spaces}'`
     */
    commitMessage?: string | {
        less: string;
        more: string;
    };
    /**
     * Pull request title template (1–2 packages)
     *
     * @default {@link releaseJson.github.PRTitle}
     */
    PRTitle?: string;
    /**
     * Pull request title template when releasing more than 2 packages
     *
     * Falls back to {@link PRTitle} when unset.
     *
     * @default {@link releaseJson.github.PRTitleMany}
     */
    PRTitleMany?: string;
    /**
     * Pull request body template
     *
     * @default from release.json
     */
    PRBody?: string;
    /**
     * Template for each workspace section in the PR body
     *
     * Used for both single- and multi-workspace releases.
     * Supports `${changeTypeSection}` (Patch/Minor/Major Changes).
     *
     * @default from release.json
     */
    batchPRBody?: string;
    /**
     * Semver increment used to title changelog sections (patch | minor | major)
     * @default 'patch'
     */
    increment?: string;
}

/**
 * @module Github
 * @description GitHub changelog enrichment, release PR, and GitHub Release plugin
 *
 * Third plugin in the default release pipeline (after {@link Workspaces} and
 * {@link ChangesetVersion}). Extends {@link GitBase} for git operations and
 * delegates GitHub API calls to {@link GithubManager}.
 *
 * Pipeline phases:
 * - **onBefore**: validate GitHub token; seed {@link ReleaseFormatter} context
 * - **onExec**: enrich workspace changelogs with PR/commit links via {@link GithubChangelog}
 * - **onSuccess**:
 *   - `createPR` — create release branch, commit, push, and open PR (unless skipped)
 *   - `createRelease` — create a GitHub Release per workspace (tag + changelog body)
 *
 * Release branch flow (`createPR`):
 * 1. `ReleaseFormatter.getReleaseBranch()` — derive branch and tag names from templates
 * 2. Create branch from `sourceBranch`, commit version/changelog changes, push
 * 3. Open PR with formatted title/body and optional labels
 * 4. Auto-merge when `autoMergeReleasePr` is enabled
 *
 * GitHub Release flow (`createRelease`):
 * 1. Filter workspaces with `tagName`, skipping `dependencyRelease` and
 *    paths matched by {@link GithubProps.ignoreReleasePaths}
 * 2. Call {@link GithubManager.createRelease} with workspace changelog as notes
 *
 * @example Skip PR creation (local dry-run)
 * ```bash
 * fe-release --github.skip-create-release-pr --dry-run
 * ```
 *
 * @example Publish + GitHub Releases (ignore examples)
 * ```bash
 * fe-release --changesetVersion.mode publish \
 *   --github.mode createRelease \
 *   --github.ignore-release-paths examples
 * ```
 *
 * @example fe-config label and merge settings
 * ```json
 * {
 *   "release": {
 *     "github": {
 *       "autoMergeReleasePr": false,
 *       "label": { "name": "CI-Release" },
 *       "ignoreReleasePaths": ["examples"]
 *     }
 *   }
 * }
 * ```
 */

type GithubMode = 'createPR' | 'createRelease';
type GithubLabel = {
    /**
     * Hexadecimal color code for label appearance
     *
     * Color format: 6-character hex string without '#'
     * Used for visual distinction in GitHub interface
     * Supports standard web color codes
     *
     * @optional
     * @default `'1A7F37'`
     * @example Green color
     * ```typescript
     * color: '1A7F37'
     * ```
     *
     * @example Blue color
     * ```typescript
     * color: '0366D6'
     * ```
     */
    color?: string;
    /**
     * Descriptive text for label documentation
     *
     * Provides context about the label's purpose
     * Used in GitHub label management interface
     * Helps team members understand label usage
     *
     * @optional
     * @default `'Release PR'`
     * @example
     * ```typescript
     * description: 'Automated release pull request'
     * ```
     */
    description?: string;
    /**
     * Label name for identification and display
     *
     * Used as the primary identifier for the label
     * Displayed in GitHub PR interface
     * Should be descriptive and consistent
     *
     * @optional
     * @default `'CI-Release'`
     * @example
     * ```typescript
     * name: 'release'
     * ```
     */
    name?: string;
};
interface GithubProps extends ReleaseFormatterConfig, GitBaseProps {
    /**
     * Plugin work mode
     *
     * - `createPR`: enrich changelogs in `onExec`, then create release branch and PR in `onSuccess`
     * - `createRelease`: enrich changelogs in `onExec`, then create GitHub Releases in `onSuccess`
     *
     * @default `'createPR'`
     */
    mode?: GithubMode;
    /**
     * PR auto-merge strategy for release pull requests
     *
     * Core concept:
     * Defines the merge strategy used when automatically merging
     * release pull requests, affecting commit history and
     * repository structure.
     *
     * Merge strategies:
     * - merge: Creates merge commit with branch history
     * - squash: Combines all commits into single commit
     * - rebase: Replays commits on target branch
     *
     * Strategy considerations:
     * - merge: Preserves complete branch history
     * - squash: Creates clean, linear history
     * - rebase: Maintains chronological order
     * - Affects commit message and history structure
     * - Influences repository maintenance and debugging
     *
     * @optional
     * @default `'squash'`
     * @example Squash merge
     * ```typescript
     * const config: FeReleaseConfig = {
     *   autoMergeType: 'squash'
     * };
     * ```
     *
     * @example Preserve history
     * ```typescript
     * const config: FeReleaseConfig = {
     *   autoMergeType: 'merge'
     * };
     * ```
     */
    mergeType?: 'merge' | 'squash' | 'rebase';
    /**
     * Whether to skip this plugin
     * @default false
     */
    skip?: boolean;
    /** @default 'chore(tag): ${name} v${version}' */
    commitMessage?: string;
    /** @default [] */
    commitArgs?: string[];
    draft?: boolean;
    preRelease?: boolean;
    autoGenerate?: boolean;
    makeLatest?: boolean | 'true' | 'false' | 'legacy';
    releaseNotes?: string;
    discussionCategoryName?: string;
    /**
     * Whether to auto-merge the created release PR
     *
     * @default false
     */
    autoMergeReleasePr?: boolean;
    /** @default false */
    pushChangeLabels?: boolean;
    /**
     * Skip creating the GitHub release pull request.
     *
     * When enabled, the release branch is still created and pushed,
     * but no PR is opened via the GitHub API. Useful for local testing.
     *
     * CLI: `--github.skip-create-release-pr`
     * fe-config: `release.github.skipCreateReleasePR`
     *
     * @default false
     */
    skipCreateReleasePr?: boolean;
    /**
     * Workspace path prefixes to skip when creating GitHub Releases.
     *
     * Matched with segment-aware path containment (e.g. `examples` skips
     * `examples/react-seed`). Applies only in `createRelease` mode.
     *
     * CLI: `--github.ignore-release-paths`
     * fe-config: `release.github.ignoreReleasePaths`
     *
     * @default `[]`
     * @example
     * ```json
     * { "ignoreReleasePaths": ["examples", "apps/docs"] }
     * ```
     */
    ignoreReleasePaths?: string[];
    /**
     * Configuration for release pull request labels
     *
     * Core concept:
     * Defines the label configuration for release pull requests,
     * enabling automated categorization and visual identification
     * of release-related PRs.
     *
     * Label features:
     * - Automated label application
     * - Customizable label appearance
     * - Consistent release identification
     * - Integration with GitHub labeling system
     * - Support for custom label descriptions
     *
     * Label properties:
     * - name: Label identifier and display name
     * - color: Hexadecimal color code for visual distinction
     * - description: Label description for documentation
     *
     * @optional
     * @example Basic label configuration
     * ```typescript
     * const config: FeReleaseConfig = {
     *   label: {
     *     name: 'release',
     *     color: '1A7F37',
     *     description: 'Automated release PR'
     *   }
     * };
     * ```
     *
     * @example Custom label
     * ```typescript
     * const config: FeReleaseConfig = {
     *   label: {
     *     name: 'CI-Release',
     *     color: '0366D6',
     *     description: 'Release created by CI/CD'
     *   }
     * };
     * ```
     */
    label?: GithubLabel;
}

/**
 * @module ChangeLog
 * @description Core interfaces for changelog generation
 *
 * This module provides the core interfaces and types for generating
 * changelogs from Git commit history. It includes types for commit
 * parsing, formatting, and changelog generation.
 *
 * Core Components:
 * - Commit data structures
 * - Changelog formatting
 * - Git log options
 * - Changelog generation
 *
 * @example Basic usage
 * ```typescript
 * class MyChangeLog implements ChangeLogInterface {
 *   async getCommits(options?: GitChangelogOptions): Promise<CommitValue[]> {
 *     // Implementation
 *   }
 * }
 *
 * class MyFormatter implements ChangelogFormatter {
 *   format(commits: CommitValue[]): string[] {
 *     // Implementation
 *   }
 * }
 * ```
 */

/**
 * Base commit type mapping Git commit fields
 *
 * Maps all available Git commit fields to optional string values.
 * Uses the CommitField type from gitlog package to ensure type safety.
 *
 * Available fields include:
 * - hash: Full commit hash
 * - abbrevHash: Abbreviated commit hash
 * - subject: Commit message subject
 * - authorName: Author's name
 * - authorDate: Author date
 * - And many more from gitlog.CommitField
 *
 * @example
 * ```typescript
 * const commit: BaseCommit = {
 *   hash: 'abc123def456',
 *   abbrevHash: 'abc123',
 *   subject: 'feat: new feature',
 *   authorName: 'John Doe',
 *   authorDate: '2023-01-01'
 * };
 * ```
 */
type BaseCommit = {
    [key in CommitField]: string | undefined;
};
/**
 * Configuration options for changelog generation
 *
 * Provides comprehensive options for controlling how changelogs
 * are generated from Git history, including commit range selection,
 * formatting, and filtering.
 *
 * @example Basic usage
 * ```typescript
 * const options: GitChangelogOptions = {
 *   from: 'v1.0.0',
 *   to: 'v2.0.0',
 *   directory: 'packages/my-pkg',
 *   noMerges: true
 * };
 * ```
 *
 * @example Custom formatting
 * ```typescript
 * const options: GitChangelogOptions = {
 *   types: [
 *     { type: 'feat', section: '### Features' },
 *     { type: 'fix', section: '### Bug Fixes' }
 *   ],
 *   formatTemplate: '* ${commitlint.message} ${prLink}',
 *   commitBody: true
 * };
 * ```
 */
interface GitChangelogOptions {
    /**
     * Starting tag or commit reference
     *
     * Defines the start point for collecting commits.
     * Can be a tag name, commit hash, or branch name.
     *
     * @example
     * ```typescript
     * from: 'v1.0.0'  // Start from v1.0.0 tag
     * from: 'abc123'  // Start from specific commit
     * ```
     */
    from?: string;
    /**
     * Ending tag or commit reference
     *
     * Defines the end point for collecting commits.
     * Can be a tag name, commit hash, or branch name.
     *
     * @example
     * ```typescript
     * to: 'v2.0.0'    // End at v2.0.0 tag
     * to: 'main'      // End at main branch
     * ```
     */
    to?: string;
    /**
     * Directory to collect commits from
     *
     * Limits commit collection to changes in specified directory.
     * Useful for monorepo package-specific changelogs.
     *
     * @example
     * ```typescript
     * directory: 'packages/my-pkg'  // Only changes in this directory
     * ```
     */
    directory?: string;
    /**
     * Git commit fields to include
     *
     * Specifies which Git commit fields to retrieve.
     * @default ["abbrevHash", "hash", "subject", "authorName", "authorDate"]
     *
     * @example
     * ```typescript
     * fields: ['hash', 'subject', 'authorName']
     * ```
     */
    fields?: CommitField[];
    /**
     * Whether to exclude merge commits
     *
     * When true, merge commits are filtered out from the changelog.
     * @default true
     *
     * @example
     * ```typescript
     * noMerges: true  // Exclude merge commits
     * noMerges: false // Include merge commits
     * ```
     */
    noMerges?: boolean;
    /**
     * Commit type configurations
     *
     * Defines how different commit types should be handled and
     * formatted in the changelog.
     *
     * @example
     * ```typescript
     * types: [
     *   { type: 'feat', section: '### Features' },
     *   { type: 'fix', section: '### Bug Fixes' },
     *   { type: 'chore', hidden: true }  // Skip chore commits
     * ]
     * ```
     */
    types?: {
        type: string;
        section?: string;
        hidden?: boolean;
    }[];
    /**
     * Template for formatting commit entries
     *
     * Supports variables from CommitValue properties and adds:
     * - ${scopeHeader}: Formatted scope
     * - ${commitLink}: Commit hash link
     * - ${prLink}: PR number link
     *
     * @default '\n- ${scopeHeader} ${commitlint.message} ${commitLink} ${prLink}'
     *
     * @example
     * ```typescript
     * formatTemplate: '* ${commitlint.message} (${commitLink})'
     * ```
     */
    formatTemplate?: string;
    /**
     * Whether to include commit message body
     *
     * When true, includes the full commit message body
     * in the changelog entry.
     *
     * @since 2.3.0
     * @default false
     *
     * @example
     * ```typescript
     * commitBody: true  // Include full commit message
     * ```
     */
    commitBody?: boolean;
    /**
     * Template for dependency release entries
     *
     * Used for formatting changelog entries related to dependency updates.
     * Supports variables:
     * - ${dep.name}: Dependency name
     * - ${dep.oldVersion}: Previous version
     * - ${dep.newVersion}: Updated version
     *
     * @since 5.0.0
     * @default '- Update dependency **${name}** from `${oldVersion}` to `${newVersion}`'
     *
     * @example
     * ```typescript
     * dependencyReleaseTemplate: '- Bump **${dep.name}** from `${dep.oldVersion}` to `${dep.newVersion}`'
     * ```
     */
    dependencyReleaseTemplate?: string;
}
/**
 * Raw commit message parsing result
 *
 * Represents a parsed conventional commit message with its
 * component parts.
 *
 * @example
 * ```typescript
 * const tuple: CommitTuple = {
 *   raw: 'feat(api): add new endpoint\n\nDetails here',
 *   type: 'feat',
 *   scope: 'api',
 *   message: 'add new endpoint',
 *   body: 'Details here'
 * };
 * ```
 */
interface CommitTuple {
    /** Original commit message */
    raw: string;
    /** Commit type (e.g., 'feat', 'fix') */
    type?: string;
    /** Commit scope (e.g., 'api', 'core') */
    scope?: string;
    /** Main commit message */
    message: string;
    /** Optional commit body */
    body?: string;
}
/**
 * Parsed conventional commit data
 *
 * Represents a commit message parsed according to the
 * conventional commit specification.
 *
 * Format: type(scope): message
 *
 * @example
 * ```typescript
 * const commit: Commitlint = {
 *   type: 'feat',
 *   scope: 'api',
 *   message: 'add new endpoint',
 *   body: 'Adds support for new API endpoint\n\nBREAKING CHANGE: API format changed'
 * };
 * ```
 */
interface Commitlint {
    /** Commit type (e.g., 'feat', 'fix') */
    type?: string;
    /** Commit scope (e.g., 'api', 'core') */
    scope?: string;
    /** Main commit message */
    message: string;
    /**
     * Commit message body with title removed
     * @since 2.3.0
     */
    body?: string;
}
/**
 * Complete commit information
 *
 * Combines Git commit data, parsed conventional commit info,
 * and PR metadata into a single value object.
 *
 * @example
 * ```typescript
 * const commit: CommitValue = {
 *   base: {
 *     hash: 'abc123',
 *     subject: 'feat(api): new endpoint (#123)'
 *   },
 *   commitlint: {
 *     type: 'feat',
 *     scope: 'api',
 *     message: 'new endpoint'
 *   },
 *   commits: [],
 *   prNumber: '123'
 * };
 * ```
 */
interface CommitValue {
    /** Raw Git commit information */
    base: BaseCommit;
    /** Parsed conventional commit data */
    commitlint: Commitlint;
    /** Sub-commits (for merge commits) */
    commits?: CommitValue[];
    /** Associated pull request number */
    prNumber?: string;
}
/**
 * Interface for changelog formatting
 *
 * Defines the contract for classes that format commit data
 * into changelog entries.
 *
 * @example
 * ```typescript
 * class MarkdownFormatter implements ChangelogFormatter {
 *   format(commits: CommitValue[]): string[] {
 *     return commits.map(commit =>
 *       `- ${commit.commitlint.message} (#${commit.prNumber})`
 *     );
 *   }
 * }
 * ```
 */
interface ChangelogFormatter {
    /**
     * Formats commits into changelog entries
     *
     * @param commits - Array of commits to format
     * @param options - Optional formatting options
     * @returns Array of formatted changelog lines
     */
    format<Opt extends GitChangelogOptions>(commits: unknown[], options?: Opt): string[];
}
/**
 * Interface for changelog generation
 *
 * Defines the contract for classes that generate changelogs
 * from Git history.
 *
 * @example
 * ```typescript
 * class GitChangelog implements ChangeLogInterface {
 *   async getCommits(options?: GitChangelogOptions): Promise<CommitValue[]> {
 *     // Get commits from Git and parse them
 *     const commits = await gitlog(options);
 *     return commits.map(commit => ({
 *       base: commit,
 *       commitlint: parseCommit(commit.subject),
 *       commits: []
 *     }));
 *   }
 * }
 * ```
 */
interface ChangeLogInterface {
    /**
     * Retrieves and parses Git commits
     *
     * @param options - Optional Git log options
     * @returns Promise resolving to array of parsed commits
     */
    getCommits(options?: GitChangelogOptions): Promise<CommitValue[]>;
}

/**
 * @module ChangesetVersion
 * @description Changelog generation and changeset version/publish plugin
 *
 * Second plugin in the default release pipeline (after {@link Workspaces},
 * before {@link Github}). Bridges git-based changelog formatting with the
 * Changesets CLI for monorepo version bumps.
 *
 * Pipeline phases:
 * - **onBefore**: validate `.changeset` directory; configure npm auth when mode includes publish
 *   (`NPM_TOKEN` for token auth, or skip when Trusted Publishing / OIDC is detected)
 * - **onExec**: generate per-workspace git changelogs (skips `dependencyRelease`
 *   when `ignoreNonUpdatedPackages` is enabled)
 * - **onSuccess**: run version and/or publish flow based on `mode`
 *
 * Publish flow (`mode: 'publish'` or second half of `'both'`):
 * 1. Run `changeset publish` (npm publish + local `git tag` for public packages)
 * 2. Sync workspaces from disk so `tagName` is set from the release version
 * 3. Create local tags for `private` packages (changesets skips tagging them)
 * 4. Push `workspace.tagName` refs that exist locally to `origin`
 *
 * Version flow (`mode: 'version'` or first half of `'both'`):
 * 1. Write `.changeset/*.md` files for directly changed packages only
 * 2. Run `changeset version` (optionally with `changelog: false` when `onlyVersion`)
 * 3. Optionally `git restore` dependency-release paths when `ignoreNonUpdatedPackages`
 * 4. Sync workspace `newVersion` / `tagName` from disk via `mergeWorkspaces`
 *
 * @example Version-only release
 * ```typescript
 * // fe-config.json
 * {
 *   "release": {
 *     "changesetVersion": {
 *       "mode": "version",
 *       "increment": "patch"
 *     }
 *   }
 * }
 * ```
 *
 * @example Ignore internal dependent bumps
 * ```bash
 * fe-release --changesetVersion.ignore-non-updated-packages
 * ```
 *
 * @see {@link ChangesetVersionProps.ignoreNonUpdatedPackages} for dependency-release behavior
 */

type ChangesetVersionMode = 'version' | 'publish' | 'both';
interface ChangesetVersionProps extends GitChangelogOptions, ScriptPluginProps {
    /**
     * Work mode
     *
     * - `version`: generate git changelog, write changeset files, run `changeset version`
     * - `publish`: run `changeset publish`
     * - `both`: run `version` flow first, then `publish`
     *
     * @default 'version'
     */
    mode?: ChangesetVersionMode;
    /**
     * Version increment type for generated changeset files
     * @default 'patch'
     */
    increment?: string;
    /**
     * Whether to skip this plugin
     * @default false
     */
    skip?: boolean;
    /**
     * Whether to skip generating changeset files (version mode only)
     * @default false
     */
    skipChangeset?: boolean;
    /**
     * Root directory of the changeset config
     * @default '.changeset'
     */
    changesetRoot?: string;
    /**
     * When true, only bump package.json versions via changesets;
     * do not write changelog content into CHANGELOG.md
     * @default false
     */
    onlyVersion?: boolean;
    /**
     * Control how internal dependency bump side-effects are handled during release.
     *
     * ## Background
     *
     * When a source package changes, `changeset version` may also bump its internal
     * dependents (for example, `fe-scripts` depends on `scripts-context`).
     * Dependents are tracked as `dependencyRelease` workspaces
     * (see `workspaces.includeDependencyReleases`).
     *
     * ## `false` (default) — keep dependent bumps
     *
     * 1. **Workspaces**: append dependents and set `dependencyRelease: true`
     * 2. **Changelog**: generate git changelog for changed packages; dependents use
     *    `dependencyReleaseTemplate` changelog
     * 3. **Changeset files**: only created for directly changed packages
     * 4. **`changeset version`**: bumps changed packages and dependents on disk
     * 5. **Result**: `Updated workspaces` includes `(DEP)` entries; dependents may
     *    be published together
     *
     * ## `true` — ignore dependent bumps (restore after version)
     *
     * 1. **Workspaces**: append dependents for restore targeting (`lastTag` is still resolved)
     * 2. **Changelog / changeset**: skip processing for `dependencyRelease` workspaces
     * 3. **`changeset version`**: runs as usual (changesets may still touch dependents)
     * 4. **Restore**: `git restore` all `dependencyRelease` workspace paths
     * 5. **Result**: only directly changed packages remain bumped; they are the only
     *    workspaces left for GitHub PR title/body/`release-tag-${count}-*` naming
     *
     * @see {@link shouldProcessWorkspace} for the per-workspace processing gate
     *
     * CLI: `--changesetVersion.ignore-non-updated-packages`
     * Alias: `--changelog.ignore-non-updated-packages`
     *
     * @default false
     */
    ignoreNonUpdatedPackages?: boolean;
    /**
     * Use npm Trusted Publishing (OIDC) instead of `NPM_TOKEN`.
     *
     * When enabled (or when GitHub Actions OIDC env is detected), publish skips
     * writing `_authToken` to npm config so the CLI can exchange OIDC credentials.
     *
     * CLI: `--changesetVersion.use-trusted-publishing`
     *
     * @default false
     */
    useTrustedPublishing?: boolean;
}
/**
 * Manages changelog generation, changeset file creation, and Changesets CLI execution.
 *
 * Coordinates with {@link Workspaces} for workspace discovery and
 * `dependencyRelease` tagging. Downstream {@link Github} consumes enriched
 * changelogs and bumped versions produced here.
 */
declare class ChangesetVersion extends ScriptPlugin<ReleaseContext, ChangesetVersionProps> {
    constructor(context: ReleaseContext, props?: ChangesetVersionProps);
    get changesetRoot(): string;
    get changesetConfigPath(): string;
    protected get mode(): ChangesetVersionMode;
    protected get ignoreNonUpdatedPackages(): boolean;
    protected get useTrustedPublishing(): boolean;
    /**
     * True when publish should use npm Trusted Publishing (OIDC) instead of NPM_TOKEN.
     */
    protected isTrustedPublishingEnv(): boolean;
    protected shouldProcessWorkspace(workspace: WorkspaceInterface): boolean;
    protected getProcessableWorkspaces(workspaces: WorkspaceInterface[]): WorkspaceInterface[];
    onBefore(): Promise<void>;
    /**
     * Configure npm auth before changeset publish.
     *
     * Uses Trusted Publishing (OIDC) when detected; otherwise requires `NPM_TOKEN`.
     * Version-only runs (release PR) do not need npm auth.
     */
    protected validateNpmToken(): Promise<void>;
    onExec(_context: ReleaseContext): Promise<void>;
    protected printWorksapces(): void;
    onSuccess(): Promise<void>;
    protected logDryRun(message: string): void;
    protected runVersionFlow(): Promise<void>;
    protected runChangesetPublish(): Promise<void>;
    /**
     * Collect tag names that should be pushed after `changeset publish`.
     *
     * Includes public packages (tagged by changesets) and private packages
     * (tagged by {@link ensurePrivateReleaseTags}). Skips dependency-release
     * workspaces.
     */
    protected collectPushableReleaseTags(workspaces: WorkspaceInterface[]): string[];
    /**
     * List local git tag names (short refs under `refs/tags/`).
     */
    protected listLocalTags(): Promise<Set<string>>;
    /**
     * Create local git tags for private packages after `changeset publish`.
     *
     * Changesets skips npm publish and tagging for `private: true` packages.
     * Release still needs those tags as changelog baselines, so create them here.
     */
    protected ensurePrivateReleaseTags(workspaces: WorkspaceInterface[]): Promise<void>;
    /**
     * Push release tags from synced workspaces' `tagName` fields.
     *
     * After {@link syncWorkspaces} and {@link ensurePrivateReleaseTags}, push
     * tags that exist as local refs. Missing public-package tags are skipped
     * (changeset may have skipped publish); they are not invented here.
     */
    protected pushWorkspaceReleaseTags(workspaces: WorkspaceInterface[]): Promise<void>;
    protected syncWorkspaces(workspaces: WorkspaceInterface[]): void;
    /**
     * Rebuild `dependencyRelease` changelogs after source packages have `newVersion`.
     *
     * Workspaces appends dependents before `changeset version`, so the template can
     * only use a provisional version. Once mergeWorkspaces reads bumped versions
     * from disk, rewrite each dependent changelog with the real source bump.
     */
    protected refreshDependencyReleaseChangelogs(workspaces: WorkspaceInterface[]): WorkspaceInterface[];
    mergeWorkspaces(workspaces: WorkspaceInterface[]): WorkspaceInterface[];
    protected runChangesetVersion(onlyVersion?: boolean): Promise<void>;
    restoreIgnorePackages(): Promise<void>;
    generateChangelog(workspace: WorkspaceInterface): Promise<WorkspaceInterface>;
    protected getChangelogWithGit(tagName: string, dir: string): Promise<string[]>;
    protected generateTagName(workspace: WorkspaceInterface): string;
    getIncrement(): string;
    /**
     * Labels that can override semver increment.
     *
     * Prefer explicit `workspaces.changeLabels`, then fall back to the PR labels
     * from `GITHUB_EVENT_PATH` when running in GitHub Actions after a PR merge.
     */
    protected getIncrementLabels(): string[];
    protected readGithubEventLabelNames(): string[];
    generateChangesetFile(workspace: WorkspaceInterface): Promise<void>;
}

/**
 * @module ReleaseLabel
 * @description Release label management and file change detection
 *
 * This module provides utilities for managing release labels and detecting
 * which packages have changed based on file paths. It supports custom
 * comparison logic and label formatting.
 *
 * Core Features:
 * - File change detection
 * - Package path matching
 * - Label generation
 * - Custom comparison logic
 *
 * @example Basic usage
 * ```typescript
 * const label = new ReleaseLabel({
 *   changePackagesLabel: 'changed:${name}',
 *   packagesDirectories: ['packages/a', 'packages/b']
 * });
 *
 * // Find changed packages
 * const changed = label.pick(['packages/a/src/index.ts']);
 * // ['packages/a']
 *
 * // Generate labels
 * const labels = label.toChangeLabels(changed);
 * // ['changed:packages/a']
 * ```
 *
 * @example Custom comparison
 * ```typescript
 * const label = new ReleaseLabel({
 *   changePackagesLabel: 'changed:${name}',
 *   packagesDirectories: ['packages/a'],
 *   compare: (file, pkg) => file.includes(pkg)
 * });
 *
 * const changed = label.pick(['src/packages/a/index.ts']);
 * // ['packages/a']
 * ```
 */
/**
 * Function type for custom file path comparison
 *
 * Used to determine if a changed file belongs to a package.
 * Default implementation checks if the file path starts with
 * the package path.
 *
 * @param changedFilePath - Path of the changed file
 * @param packagePath - Path of the package to check against
 * @returns True if the file belongs to the package
 */
type ReleaseLabelCompare = (changedFilePath: string, packagePath: string) => boolean;
interface ReleaseLabelOptions {
    /**
     * The change packages label
     */
    changePackagesLabel: string;
    /**
     * The packages directories
     */
    packagesDirectories: string[];
    compare?: ReleaseLabelCompare;
}
/**
 * Core class for managing release labels and change detection
 *
 * Provides utilities for detecting changed packages and generating
 * appropriate labels. Supports custom comparison logic and label
 * formatting.
 *
 * Features:
 * - File change detection
 * - Package path matching
 * - Label generation
 * - Custom comparison logic
 *
 * @example Basic usage
 * ```typescript
 * const label = new ReleaseLabel({
 *   changePackagesLabel: 'changed:${name}',
 *   packagesDirectories: ['packages/a', 'packages/b']
 * });
 *
 * // Find changed packages
 * const changed = label.pick(['packages/a/src/index.ts']);
 *
 * // Generate labels
 * const labels = label.toChangeLabels(changed);
 * ```
 *
 * @example Custom comparison
 * ```typescript
 * const label = new ReleaseLabel({
 *   changePackagesLabel: 'changed:${name}',
 *   packagesDirectories: ['packages/a'],
 *   compare: (file, pkg) => file.includes(pkg)
 * });
 *
 * const changed = label.pick(['src/packages/a/index.ts']);
 * ```
 */
declare class ReleaseLabel {
    private readonly options;
    /**
     * Creates a new ReleaseLabel instance
     *
     * @param options - Configuration options for label management
     *
     * @example
     * ```typescript
     * const label = new ReleaseLabel({
     *   // Label template with ${name} placeholder
     *   changePackagesLabel: 'changed:${name}',
     *
     *   // Package directories to monitor
     *   packagesDirectories: ['packages/a', 'packages/b'],
     *
     *   // Optional custom comparison logic
     *   compare: (file, pkg) => file.includes(pkg)
     * });
     * ```
     */
    constructor(options: ReleaseLabelOptions);
    /**
     * Compares a changed file path against a package path
     *
     * Uses custom comparison function if provided, otherwise
     * checks if the file path starts with the package path.
     *
     * @param changedFilePath - Path of the changed file
     * @param packagePath - Path of the package to check against
     * @returns True if the file belongs to the package
     *
     * @example
     * ```typescript
     * // Default comparison
     * label.compare('packages/a/src/index.ts', 'packages/a');
     * // true
     *
     * // Custom comparison
     * const label = new ReleaseLabel({
     *   ...options,
     *   compare: (file, pkg) => file.includes(pkg)
     * });
     * label.compare('src/packages/a/index.ts', 'packages/a');
     * // true
     * ```
     */
    compare(changedFilePath: string, packagePath: string): boolean;
    /**
     * Generates a change label for a single package
     *
     * Replaces ${name} placeholder in the label template with
     * the package path.
     *
     * @param packagePath - Path of the package
     * @param label - Optional custom label template
     * @returns Formatted change label
     *
     * @example
     * ```typescript
     * // Default label template
     * label.toChangeLabel('packages/a');
     * // 'changed:packages/a'
     *
     * // Custom label template
     * label.toChangeLabel('packages/a', 'modified:${name}');
     * // 'modified:packages/a'
     * ```
     */
    toChangeLabel(packagePath: string, label?: string): string;
    /**
     * Generates change labels for multiple packages
     *
     * Maps each package path to a formatted change label.
     *
     * @param packages - Array of package paths
     * @param label - Optional custom label template
     * @returns Array of formatted change labels
     *
     * @example
     * ```typescript
     * // Default label template
     * label.toChangeLabels(['packages/a', 'packages/b']);
     * // ['changed:packages/a', 'changed:packages/b']
     *
     * // Custom label template
     * label.toChangeLabels(
     *   ['packages/a', 'packages/b'],
     *   'modified:${name}'
     * );
     * // ['modified:packages/a', 'modified:packages/b']
     * ```
     */
    toChangeLabels(packages: string[], label?: string): string[];
    /**
     * Identifies packages affected by changed files
     *
     * Checks each changed file against package paths to determine
     * which packages have been modified.
     *
     * @param changedFiles - Array or Set of changed file paths
     * @param packages - Optional array of package paths to check
     * @returns Array of affected package paths
     *
     * @example
     * ```typescript
     * // Check against default packages
     * label.pick(['packages/a/src/index.ts']);
     * // ['packages/a']
     *
     * // Check specific packages
     * label.pick(
     *   ['packages/a/index.ts', 'packages/b/test.ts'],
     *   ['packages/a', 'packages/c']
     * );
     * // ['packages/a']
     *
     * // Using Set of files
     * label.pick(new Set(['packages/a/index.ts']));
     * // ['packages/a']
     * ```
     */
    pick(changedFiles: Array<string> | Set<string>, packages?: string[]): string[];
}

interface WorkspacesProps extends ScriptPluginProps {
    /**
     * Whether to skip checking the package.json file
     *
     * @default `false`
     */
    skipCheckPackage?: boolean;
    /**
     * The workspaces to publish
     * @private
     */
    workspaces?: WorkspaceInterface[];
    /**
     * The change labels
     *
     * from `changePackagesLabel`
     */
    changeLabels?: string[];
    /**
     * The changed paths
     * @private
     */
    changedPaths?: string[];
    /**
     * The packages
     * @private
     */
    packages?: string[];
    /**
     * All project packages mapping
     * @private
     */
    projectWorkspaces?: WorkspaceInterface[];
    /**
     * Template for generating release tag names after version bump
     *
     * Template variables support {@link WorkspaceInterface} properties.
     *
     * @default `'${name}@${version}'`
     */
    tagTemplate?: string;
    /**
     * Glob-style pattern for matching historical release tags
     *
     * @default `'${name}@*'`
     */
    tagMatch?: string;
    /**
     * Include internal dependents in the release workspace list.
     *
     * When enabled (default), packages that depend on a changed source are appended
     * with `dependencyRelease: true`. This list is used for:
     *
     * - changelog / version logging when `changesetVersion.ignoreNonUpdatedPackages`
     *   is `false`
     * - `git restore` targeting when `changesetVersion.ignoreNonUpdatedPackages`
     *   is `true`
     *
     * @default true
     */
    includeDependencyReleases?: boolean;
    /**
     * Directories containing packages for monorepo releases
     *
     * Core concept:
     * Specifies the directories that contain packages for
     * monorepo release management, enabling selective
     * package discovery and release coordination.
     *
     * Directory patterns:
     * - Supports glob patterns for flexible matching
     * - Enables selective package inclusion
     * - Supports nested directory structures
     * - Facilitates monorepo organization
     * - Enables workspace-specific configurations
     *
     * Use cases:
     * - Monorepo package discovery
     * - Selective package releases
     * - Workspace-specific configurations
     * - Multi-package coordination
     * - Dependency-aware releases
     *
     * @optional
     * @default `[]`
     * @example Basic package directories
     * ```typescript
     * const config: FeReleaseConfig = {
     *   packagesDirectories: ['packages/*']
     * };
     * ```
     *
     * @example Multiple package directories
     * ```typescript
     * const config: FeReleaseConfig = {
     *   packagesDirectories: ['packages/*', 'apps/*', 'libs/*']
     * };
     * ```
     */
    packagesDirectories?: string[];
    /**
     * Git ref used as the left side of `git diff <compareRef>...HEAD`
     * when detecting changed packages.
     *
     * Defaults to `origin/<sourceBranch>`, then falls back to the merged PR base
     * SHA from `GITHUB_EVENT_PATH` when running after a GitHub Actions PR merge
     * into the same branch (where `origin/<sourceBranch>...HEAD` is empty).
     *
     * @optional
     * @example `'abc1234'` or `'origin/master'`
     */
    compareRef?: string;
    /**
     * Template for package change labels in monorepos
     *
     * Core concept:
     * Defines the naming pattern for labels that identify
     * which packages have changed in monorepo releases,
     * enabling targeted review and deployment.
     *
     * Label usage:
     * - Applied to PRs when specific packages change
     * - Enables package-specific review processes
     * - Supports selective deployment strategies
     * - Improves monorepo change tracking
     * - Facilitates team collaboration and review
     *
     * Template variables:
     * - `${name}`: Package name for label identification
     *
     * @optional
     * @default `'changes:${name}'`
     * @example Basic change label
     * ```typescript
     * const config: FeReleaseConfig = {
     *   changePackagesLabel: 'changes:${name}'
     * };
     * ```
     *
     * @example Custom change label
     * ```typescript
     * const config: FeReleaseConfig = {
     *   changePackagesLabel: 'package:${name}'
     * };
     * ```
     */
    changePackagesLabel?: string;
}

/**
 * @module FeReleaseDefaults
 * @description Internal constants for fe-release
 *
 * User-facing default configuration lives in `release.json` and is
 * injected into {@link ReleaseContext} at construction time.
 */
/**
 * Default name for the release task context (fe-config.json key)
 */
declare const defaultReleaaseName = "release";
/**
 * Path to package manifest file
 */
declare const MANIFEST_PATH = "package.json";
/**
 * Template opening delimiter
 */
declare const TEMPLATE_OPEN = "{{";
declare const releaseJson: {
    readonly sourceBranch: "master";
    readonly releaseEnv: "development";
    readonly github: {
        readonly mode: "createPR";
        readonly mergeType: "squash";
        readonly autoMergeReleasePR: false;
        readonly pushChangeLabels: false;
        readonly skipCreateReleasePR: false;
        /** Used when releasing 1–2 packages */
        readonly PRTitle: "Release ${spaces}";
        /** Used when releasing more than 2 packages */
        readonly PRTitleMany: "Release ${count} packages: ${spaces}";
        readonly PRBody: "## Changelog\n\n${changelog}";
        /**
         * Per-workspace section in the PR body (single and multi package).
         * `${changeTypeSection}` is Patch/Minor/Major Changes from increment.
         */
        readonly batchPRBody: "\n### ${name}@${newVersion}\n\n#### ${changeTypeSection}\n\n${changelog}\n";
        readonly branchName: "release/${repoName}-${releaseId}";
        readonly releaseTagName: "release-tag-${count}-patch-${releaseId}";
        readonly commitMessage: "chore(release): ${spaces}";
        /** GitHub release title template (createRelease mode) */
        readonly releaseName: "${name}@${version}";
        /** Path prefixes skipped when creating GitHub releases */
        readonly ignoreReleasePaths: readonly string[];
        readonly label: {
            readonly name: "CI-Release";
            readonly color: "1A7F37";
            readonly description: "Automated release PR (merge to publish)";
        };
    };
    readonly changesetVersion: {
        readonly mode: "version";
        readonly increment: "patch";
        readonly changesetRoot: ".changeset";
        readonly ignoreNonUpdatedPackages: false;
        readonly dependencyReleaseTemplate: "- Update dependency **${name}** from `${oldVersion}` to `${newVersion}`";
        readonly formatTemplate: "\n- ${scopeHeader} ${commitlint.message} ${commitLink} ${prLink}";
        readonly types: readonly [{
            readonly type: "feat";
            readonly section: "#### ✨ Features";
            readonly hidden: false;
        }, {
            readonly type: "fix";
            readonly section: "#### 🐞 Bug Fixes";
            readonly hidden: false;
        }, {
            readonly type: "chore";
            readonly section: "#### 🔧 Chores";
            readonly hidden: true;
        }, {
            readonly type: "docs";
            readonly section: "#### 📝 Documentation";
            readonly hidden: false;
        }, {
            readonly type: "refactor";
            readonly section: "#### ♻️ Refactors";
            readonly hidden: false;
        }, {
            readonly type: "perf";
            readonly section: "#### 🚀 Performance";
            readonly hidden: false;
        }, {
            readonly type: "test";
            readonly section: "#### 🚨 Tests";
            readonly hidden: true;
        }, {
            readonly type: "style";
            readonly section: "#### 🎨 Styles";
            readonly hidden: true;
        }, {
            readonly type: "ci";
            readonly section: "#### 🔄 CI";
            readonly hidden: true;
        }, {
            readonly type: "build";
            readonly section: "#### 🚧 Build";
            readonly hidden: false;
        }, {
            readonly type: "revert";
            readonly section: "#### ⏪ Reverts";
            readonly hidden: true;
        }, {
            readonly type: "release";
            readonly section: "#### 🔖 Releases";
            readonly hidden: true;
        }];
    };
    readonly workspaces: {
        readonly tagTemplate: "${name}@${version}";
        readonly tagMatch: "${name}@*";
        readonly includeDependencyReleases: true;
    };
};

/**
 * @module FeReleaseTypes
 * @description Type definitions for the fe-release framework
 *
 * This module provides TypeScript type definitions for the fe-release framework,
 * including interfaces for release context, configuration, execution context,
 * and various utility types.
 *
 * Type Categories:
 * - Execution Context: Types for task execution and return values
 * - Configuration: Types for release and workspace configuration
 * - Plugin Types: Interfaces for GitHub PR and workspace plugins
 * - Utility Types: Helper types like DeepPartial and PackageJson
 *
 * Design Considerations:
 * - Type safety for plugin configuration
 * - Extensible context interfaces
 * - Backward compatibility support
 * - Clear deprecation markers
 * - Generic type constraints
 */

/**
 * Extended execution context for release tasks
 *
 * Adds release-specific return value handling to the base executor context.
 * Used to track and manage release task execution results.
 *
 * @example
 * ```typescript
 * const context: ExecutorReleaseContext = {
 *   returnValue: { githubToken: 'token123' },
 *   // ... other executor context properties
 * };
 * ```
 */
interface ExecutorReleaseContext extends ExecutorContextInterface<ReleaseContext> {
    returnValue: ReleaseReturnValue;
}
/**
 * Return value type for release tasks
 *
 * Defines the structure of data returned from release task execution.
 * Includes GitHub token and allows for additional custom properties.
 *
 * @example
 * ```typescript
 * const returnValue: ReleaseReturnValue = {
 *   githubToken: 'github_pat_123',
 *   customData: { version: '1.0.0' }
 * };
 * ```
 */
type ReleaseReturnValue = {
    githubToken?: string;
    [key: string]: unknown;
};
/**
 * Utility type for creating deep partial types
 *
 * Makes all properties in T optional recursively, useful for
 * partial configuration objects and type-safe updates.
 *
 * @example
 * ```typescript
 * interface Config {
 *   deep: {
 *     nested: {
 *       value: string;
 *     }
 *   }
 * }
 *
 * const partial: DeepPartial<Config> = {
 *   deep: {
 *     nested: {
 *       // All properties optional
 *     }
 *   }
 * };
 * ```
 */
type DeepPartial<T> = {
    [P in keyof T]?: string extends keyof T[P] ? T[P] : T[P] extends object ? DeepPartial<T[P]> : T[P];
};
/**
 * Configuration interface for release process
 *
 * Extends shared script configuration with release-specific
 * settings for GitHub PR and workspace management.
 *
 * @example
 * ```typescript
 * const config: ReleaseConfig = {
 *   githubPR: {
 *     owner: 'org',
 *     repo: 'repo',
 *     base: 'main'
 *   },
 *   workspaces: {
 *     packages: ['packages/*']
 *   }
 * };
 * ```
 */
interface ReleaseConfig extends ScriptSharedInterface {
    changesetVersion?: ChangesetVersionProps;
    github?: GithubProps;
    workspaces?: WorkspacesProps;
    /** Repository name without owner */
    repoName?: string;
    /** Repository owner / org / namespace */
    authorName?: string;
    releaseEnv?: string;
    currentBranch?: string;
    releaseId?: string;
}
/**
 * Options interface for release context
 *
 * Extends script context interface with release-specific configuration.
 * Uses generic type parameter for custom configuration extensions.
 *
 * @example
 * ```typescript
 * interface CustomConfig extends ReleaseConfig {
 *   custom: {
 *     feature: boolean;
 *   }
 * }
 *
 * const options: ReleaseContextOptions<CustomConfig> = {
 *   custom: {
 *     feature: true
 *   }
 * };
 * ```
 */
interface ReleaseContextOptions$1<T extends ReleaseConfig = ReleaseConfig> extends ScriptContextInterface<T> {
}
/**
 * Configuration for a single execution step
 *
 * Defines a labeled, optionally enabled task with async execution.
 * Used for creating structured, trackable release steps.
 *
 * @example
 * ```typescript
 * const step: StepOption<string> = {
 *   label: 'Update version',
 *   enabled: true,
 *   task: async () => {
 *     // Version update logic
 *     return 'Version updated to 1.0.0';
 *   }
 * };
 * ```
 */
type StepOption<T> = {
    label: string;
    enabled?: boolean;
    task: () => Promise<T>;
};
/**
 * Type alias for package.json structure
 *
 * Represents the structure of a package.json file with flexible
 * key-value pairs. Used for package metadata handling.
 *
 * @example
 * ```typescript
 * const pkg: PackageJson = {
 *   name: 'my-package',
 *   version: '1.0.0',
 *   dependencies: {
 *     // ...
 *   }
 * };
 * ```
 */
type PackageJson = Record<string, unknown>;
/**
 * Context interface for template processing
 *
 * Combines release context options with workspace values and
 * adds template-specific properties. Includes deprecated fields
 * with migration guidance.
 *
 * @example
 * ```typescript
 * const context: TemplateContext = {
 *   publishPath: './dist',
 *   env: 'production',      // Deprecated
 *   branch: 'main',         // Deprecated
 *   // ... other properties from ReleaseContextOptions
 * };
 * ```
 */
interface TemplateContext extends ReleaseContextOptions$1, WorkspaceInterface {
    publishPath: string;
    /**
     * @deprecated  use `releaseEnv` from `shared`
     */
    env: string;
    /**
     * @deprecated  use `sourceBranch` from `shared`
     */
    branch: string;
}
interface ReleaseGlobalConfig {
    /**
     * The github PR of the project
     * @private
     */
    github?: GithubProps;
    /**
     * Changeset version/publish plugin options
     * @private
     */
    changesetVersion?: ChangesetVersionProps;
    /**
     * The workspaces of the project
     * @private
     */
    workspaces?: WorkspacesProps;
}
declare module '@qlover/scripts-context' {
    interface FeConfig {
        [defaultReleaaseName]?: ReleaseGlobalConfig;
    }
}

/**
 * @module PluginTuple
 * @description Type-safe plugin tuple creation and handling
 *
 * This module provides utilities for creating and handling tuples that
 * represent plugin configurations. It ensures type safety when working
 * with plugin constructors and their parameters.
 *
 * Core Features:
 * - Type-safe plugin class handling
 * - Constructor parameter inference
 * - Plugin tuple creation
 *
 * @example Basic usage
 * ```typescript
 * class MyPlugin extends ScriptPlugin {
 *   constructor(context: ScriptContext, config: { option: string }) {
 *     super(context);
 *   }
 * }
 *
 * const pluginTuple = tuple(MyPlugin, { option: 'value' });
 * // [MyPlugin, { option: 'value' }]
 * ```
 *
 * @example Plugin name string
 * ```typescript
 * const pluginTuple = tuple('MyPlugin', { option: 'value' });
 * // ['MyPlugin', { option: 'value' }]
 * ```
 */

/**
 * Plugin class constructor type
 *
 * Represents a constructor for a class that extends ScriptPlugin.
 * Supports generic constructor arguments.
 *
 * @template T - Array type for constructor arguments
 *
 * @example
 * ```typescript
 * class MyPlugin extends ScriptPlugin {
 *   constructor(context: ScriptContext, config: { option: string }) {
 *     super(context);
 *   }
 * }
 *
 * const PluginCtor: PluginClass = MyPlugin;
 * ```
 */
type PluginClass<T extends unknown[] = any[]> = new (...args: T) => ScriptPlugin<ScriptContext<any>, ScriptPluginProps>;
/**
 * Plugin constructor parameters type
 *
 * Extracts the constructor parameter types for a plugin class,
 * excluding the first parameter (context). Uses TypeScript's
 * conditional types and inference to extract parameter types.
 *
 * @template T - Plugin class type
 *
 * @example
 * ```typescript
 * class MyPlugin extends ScriptPlugin {
 *   constructor(
 *     context: ScriptContext,
 *     config: { option: string },
 *     extra: number
 *   ) {
 *     super(context);
 *   }
 * }
 *
 * // Type: [{ option: string }, number]
 * type Params = PluginConstructorParams<typeof MyPlugin>;
 * ```
 */
type PluginConstructorParams<T extends PluginClass> = T extends new (first: any, ...args: infer P) => unknown ? P : never;
/**
 * Plugin configuration tuple type
 *
 * Represents a tuple containing a plugin class (or name) and its
 * constructor arguments. Used for plugin registration and loading.
 *
 * @template T - Plugin class type
 *
 * @example
 * ```typescript
 * class MyPlugin extends ScriptPlugin {
 *   constructor(context: ScriptContext, config: { option: string }) {
 *     super(context);
 *   }
 * }
 *
 * // Type: [typeof MyPlugin, { option: string }]
 * type Tuple = PluginTuple<typeof MyPlugin>;
 *
 * // Type: [string, { option: string }]
 * type StringTuple = PluginTuple<'MyPlugin'>;
 * ```
 */
type PluginTuple<T extends PluginClass> = [
    T | string,
    ...PluginConstructorParams<T>
];
/**
 * Creates a type-safe plugin configuration tuple
 *
 * Helper function for creating tuples that represent plugin
 * configurations with proper type inference for constructor
 * arguments.
 *
 * @template T - Plugin class type
 * @param plugin - Plugin class or name
 * @param args - Plugin constructor arguments
 * @returns Plugin configuration tuple
 *
 * @example Class-based plugin
 * ```typescript
 * class MyPlugin extends ScriptPlugin {
 *   constructor(
 *     context: ScriptContext,
 *     config: { option: string },
 *     extra: number
 *   ) {
 *     super(context);
 *   }
 * }
 *
 * const config = tuple(MyPlugin, { option: 'value' }, 42);
 * // [MyPlugin, { option: 'value' }, 42]
 * ```
 *
 * @example String-based plugin
 * ```typescript
 * const config = tuple('MyPlugin', { option: 'value' });
 * // ['MyPlugin', { option: 'value' }]
 * ```
 */
declare function tuple<T extends PluginClass>(plugin: T | string, ...args: PluginConstructorParams<T>): PluginTuple<T>;

/**
 * @module ReleaseContext
 * @description Core context management for release operations
 *
 * This module provides the central context management for release operations,
 * handling configuration, environment variables, workspace management, and
 * package information. It extends the base ScriptContext with release-specific
 * functionality.
 *
 * Core Features:
 * - Environment variable management
 * - Workspace configuration
 * - Package.json access
 * - Template context generation
 * - Changeset CLI integration
 *
 * @example Basic usage
 * ```typescript
 * const context = new ReleaseContext('my-package', {
 *   rootPath: '/path/to/project',
 *   sourceBranch: 'main',
 *   releaseEnv: 'production'
 * });
 *
 * // Access package info
 * const version = context.getPkg('version');
 *
 * // Generate template context
 * const templateData = context.getTemplateContext();
 * ```
 *
 * @example Workspace management
 * ```typescript
 * // Set workspace configuration
 * context.setWorkspaces([{
 *   name: 'package-a',
 *   version: '1.0.0',
 *   path: 'packages/a'
 * }]);
 *
 * // Access workspace info
 * const currentWorkspace = context.workspace;
 * ```
 *
 * @example Changeset integration
 * ```typescript
 * // Run changeset commands
 * await context.runChangesetsCli('version', ['--snapshot', 'alpha']);
 * ```
 */

interface ReleaseContextOptions extends ScriptContextInterface<ReleaseContextConfig> {
}
interface ReleaseContextConfig extends ReleaseGlobalConfig, ScriptSharedInterface {
    /**
     * The environment of the project
     *
     * default:
     * - first, get from `FE_RELEASE_ENV`
     * - second, get from `NODE_ENV`
     * - `development`
     */
    releaseEnv?: string;
    /**
     * Plugins
     */
    plugins?: PluginTuple<PluginClass<unknown[]>>[];
    /**
     * The name of the repository
     */
    repoName?: string;
    /**
     * The name of the author
     */
    authorName?: string;
    /**
     * The current branch of the project
     */
    currentBranch?: string;
    /**
     * Unique identifier for the current release run
     *
     * @private
     */
    releaseId?: string;
}
/**
 * Core context class for release operations
 *
 * Manages release-specific configuration, environment variables,
 * workspace settings, and provides utilities for release operations.
 *
 * Features:
 * - Automatic environment detection
 * - Source branch management
 * - Workspace configuration
 * - Package.json access
 * - Template context generation
 * - Changeset CLI integration
 *
 * @example Basic initialization
 * ```typescript
 * const context = new ReleaseContext('my-package', {
 *   rootPath: '/path/to/project',
 *   sourceBranch: 'main'
 * });
 * ```
 *
 * @example Environment configuration
 * ```typescript
 * // With environment variables
 * process.env.FE_RELEASE_ENV = 'staging';
 * process.env.FE_RELEASE_BRANCH = 'develop';
 *
 * const context = new ReleaseContext('my-package', {});
 * // context.releaseEnv === 'staging'
 * // context.sourceBranch === 'develop'
 * ```
 */
declare class ReleaseContext extends ScriptContext<ReleaseContextConfig> {
    protected templateEngine: TemplateEngine;
    protected compileMap: Map<string, RenderFn>;
    /**
     * Creates a new ReleaseContext instance
     *
     * Initializes the context with provided options and sets up
     * default values for required configuration:
     * - rootPath: Defaults to current working directory
     * - sourceBranch: Uses environment variables or default
     * - releaseEnv: Uses environment variables or 'development'
     *
     * Environment Variable Priority:
     * - sourceBranch: FE_RELEASE_BRANCH > FE_RELEASE_SOURCE_BRANCH > release.json
     * - releaseEnv: FE_RELEASE_ENV > NODE_ENV > 'development'
     *
     * @param name - Unique identifier for this release context
     * @param options - Configuration options
     *
     * @example
     * ```typescript
     * const context = new ReleaseContext('web-app', {
     *   rootPath: '/projects/web-app',
     *   sourceBranch: 'main',
     *   releaseEnv: 'production'
     * });
     * ```
     */
    constructor(name: string, options: Partial<ReleaseContextOptions>);
    /**
     * Gets the root path of the project
     *
     * @returns Absolute path to project root
     *
     * @example
     * ```typescript
     * const root = context.rootPath;
     * // '/path/to/project'
     * ```
     */
    get rootPath(): string;
    /**
     * Gets the source branch for the release
     *
     * @returns Branch name to use as source
     *
     * @example
     * ```typescript
     * const branch = context.sourceBranch;
     * // 'main' or custom branch name
     * ```
     */
    get sourceBranch(): string;
    /**
     * Gets the release environment
     *
     * @returns Environment name (e.g., 'development', 'production')
     *
     * @example
     * ```typescript
     * const env = context.releaseEnv;
     * // 'development' or custom environment
     * ```
     */
    get releaseEnv(): string;
    /**
     * Gets the unique identifier for the current release run
     */
    get releaseId(): string;
    /**
     * Gets all configured workspaces
     *
     * @returns Array of workspace configurations or undefined
     *
     * @example
     * ```typescript
     * const allWorkspaces = context.workspaces;
     * // [{ name: 'pkg-a', version: '1.0.0', ... }]
     * ```
     */
    get workspaces(): WorkspaceInterface[] | undefined;
    /**
     * Sets the workspace configurations
     *
     * Updates the workspace list while preserving other workspace settings
     *
     * @param workspaces - Array of workspace configurations
     *
     * @example
     * ```typescript
     * context.setWorkspaces([{
     *   name: 'pkg-a',
     *   version: '1.0.0',
     *   path: 'packages/a',
     *   lastTag: 'pkg-aV1.0.0'
     * }]);
     * ```
     */
    setWorkspaces(workspaces: WorkspaceInterface[]): void;
    /**
     * @deprecated use `getParameters` or use `context.parameters`(type safe)
     * @param key
     * @param defaultValue
     */
    getOptions<T = unknown>(key?: keyof ReleaseContextConfig | (keyof ReleaseContextConfig)[], defaultValue?: T): T;
    /**
     * Generates template context for string interpolation
     *
     * Combines context options, workspace data, and specific paths
     * for use in template processing. Includes deprecated fields
     * for backward compatibility.
     *
     * @returns Combined template context
     *
     * @example
     * ```typescript
     * const context = releaseContext.getTemplateContext();
     * // {
     * //   publishPath: 'packages/my-pkg',
     * //   env: 'production',        // deprecated
     * //   branch: 'main',          // deprecated
     * //   releaseEnv: 'production', // use this instead
     * //   sourceBranch: 'main',    // use this instead
     * //   ...other options
     * // }
     * ```
     */
    getTemplateContext(): TemplateContext;
    /**
     * Executes changeset CLI commands
     *
     * Automatically detects and uses appropriate package manager
     * (pnpm or npx) to run changeset commands.
     *
     * @param name - Changeset command name
     * @param args - Optional command arguments
     * @returns Command output
     *
     * @example Version bump
     * ```typescript
     * // Bump version with snapshot
     * await context.runChangesetsCli('version', ['--snapshot', 'alpha']);
     *
     * // Create new changeset
     * await context.runChangesetsCli('add');
     *
     * // Status check
     * await context.runChangesetsCli('status');
     * ```
     */
    runChangesetsCli(name: string, args?: string[]): Promise<string>;
    /**
     * Gets the workspaces of the project
     *
     * If no workspaces are found, throws an error.
     *
     * @throws Error if no workspaces are found
     * @returns The workspaces of the project
     *
     * @example
     * ```typescript
     * const workspaces = context.requireWorkspaces();
     * // [{ name: 'pkg-a', version: '1.0.0', ... }]
     * ```
     */
    requireWorkspaces(): WorkspaceInterface[];
    /**
     * Format a template with the given data
     *
     * The template will be compiled only once and cached for future use.
     *
     * @param template - The template to format
     * @param data - The data to format the template with
     * @returns The formatted template
     */
    format(template: string, data: Record<string, any>): string;
    getTemplateEngine(): TemplateEngine;
}

/**
 * @module ReleaseTask
 * @description Task orchestration for release process
 *
 * This module provides the core task orchestration for the release process,
 * managing plugin loading, execution order, and context handling. It serves
 * as the main entry point for executing release operations.
 *
 * Core Features:
 * - Plugin management and execution
 * - Release context initialization
 * - Task execution control
 * - Environment-based control
 *
 * Default Plugins:
 * - Workspaces: Monorepo workspace management
 * - Changelog: Version and changelog management
 * - GithubPR: Pull request creation and management
 *
 * @example Basic usage
 * ```typescript
 * // Initialize and execute
 * const task = new ReleaseTask({
 *   rootPath: '/path/to/project',
 *   sourceBranch: 'main'
 * });
 *
 * await task.exec();
 * ```
 *
 * @example Custom plugins
 * ```typescript
 * import { tuple } from '@qlover/fe-release';
 *
 * // Add custom plugin
 * class CustomPlugin extends ScriptPlugin {
 *   async onExec() {
 *     // Custom release logic
 *   }
 * }
 *
 * const task = new ReleaseTask({}, new LifecycleExecutor<ReleaseContext>(), [
 *   tuple(CustomPlugin, { option: 'value' })
 * ]);
 *
 * await task.exec();
 * ```
 *
 * @example Environment control
 * ```typescript
 * // Skip release
 * process.env.FE_RELEASE = 'false';
 *
 * const task = new ReleaseTask();
 * try {
 *   await task.exec();
 * } catch (e) {
 *   // Handle "Skip Release" error
 * }
 * ```
 */

/**
 * Core task class for managing release operations
 *
 * Handles plugin orchestration, task execution, and context management
 * for the release process. Supports both built-in and custom plugins.
 *
 * Features:
 * - Plugin lifecycle management
 * - Task execution control
 * - Context initialization and access
 * - Environment-based control
 *
 * @example Basic initialization
 * ```typescript
 * const task = new ReleaseTask({
 *   rootPath: '/path/to/project'
 * });
 * ```
 *
 * @example Custom executor
 * ```typescript
 * const executor = new LifecycleExecutor<ReleaseContext>({
 *   onError: (err) => console.error('Release failed:', err)
 * });
 *
 * const task = new ReleaseTask({}, executor);
 * ```
 *
 * @example Custom plugins
 * ```typescript
 * const task = new ReleaseTask(
 *   {}, // options
 *   new LifecycleExecutor<ReleaseContext>(),
 *   [
 *     tuple(CustomPlugin, { config: 'value' }),
 *     ...innerTuples // include default plugins
 *   ]
 * );
 * ```
 */
declare class ReleaseTask {
    protected executor: LifecycleExecutor<ReleaseContext>;
    protected defaultTuples: PluginTuple<PluginClass>[];
    /**
     * Release context instance
     * @protected
     */
    protected context: ReleaseContext;
    /**
     * Creates a new ReleaseTask instance
     *
     * Initializes the release context and sets up plugin configuration.
     * Supports custom executors and plugin configurations.
     *
     * @param options - Release context configuration
     * @param executor - Custom async executor (optional)
     * @param defaultTuples - Plugin configuration tuples (optional)
     *
     * @example
     * ```typescript
     * // Basic initialization
     * const task = new ReleaseTask({
     *   rootPath: '/path/to/project',
     *   sourceBranch: 'main'
     * });
     *
     * // With custom executor and plugins
     * const task = new ReleaseTask(
     *   { rootPath: '/path/to/project' },
     *   new LifecycleExecutor<ReleaseContext>(),
     *   [tuple(CustomPlugin, { option: 'value' })]
     * );
     * ```
     */
    constructor(options?: Partial<ReleaseContextOptions>, executor?: LifecycleExecutor<ReleaseContext>, defaultTuples?: PluginTuple<PluginClass>[]);
    /**
     * Gets the current release context
     *
     * @returns Release context instance
     *
     * @example
     * ```typescript
     * const task = new ReleaseTask();
     * const context = task.getContext();
     *
     * console.log(context.releaseEnv);
     * console.log(context.sourceBranch);
     * ```
     */
    getContext(): ReleaseContext;
    /**
     * Loads and configures plugins for the release task
     *
     * Combines default and external plugins, initializes them with
     * the current context, and configures special cases like the
     * Workspaces plugin.
     *
     * Plugin Loading Process:
     * 1. Merge default and external plugins
     * 2. Initialize plugins with context
     * 3. Configure special plugins
     * 4. Add plugins to executor
     *
     * @param externalTuples - Additional plugin configurations
     * @returns Array of initialized plugins
     *
     * @example Basic usage
     * ```typescript
     * const task = new ReleaseTask();
     * const plugins = await task.usePlugins();
     * ```
     *
     * @example Custom plugins
     * ```typescript
     * const task = new ReleaseTask();
     * const plugins = await task.usePlugins([
     *   tuple(CustomPlugin, { option: 'value' })
     * ]);
     * ```
     */
    usePlugins(externalTuples?: PluginTuple<PluginClass>[]): Promise<ScriptPlugin<ScriptContext<any>, ScriptPluginProps>[]>;
    /**
     * Executes the release task
     *
     * Internal method that runs the task through the executor.
     * Preserves the context through the execution chain.
     *
     * @returns Execution result
     * @internal
     */
    run(): Promise<unknown>;
    /**
     * Main entry point for executing the release task
     *
     * Checks environment conditions, loads plugins, and executes
     * the release process. Supports additional plugin configuration
     * at execution time.
     *
     * Environment Control:
     * - Checks FE_RELEASE environment variable
     * - Skips release if FE_RELEASE=false
     *
     * @param externalTuples - Additional plugin configurations
     * @returns Execution result
     * @throws Error if release is skipped via environment variable
     *
     * @example Basic execution
     * ```typescript
     * const task = new ReleaseTask();
     * await task.exec();
     * ```
     *
     * @example With additional plugins
     * ```typescript
     * const task = new ReleaseTask();
     * await task.exec([
     *   tuple(CustomPlugin, { option: 'value' })
     * ]);
     * ```
     *
     * @example Environment control
     * ```typescript
     * // Skip release
     * process.env.FE_RELEASE = 'false';
     *
     * const task = new ReleaseTask();
     * try {
     *   await task.exec();
     * } catch (e) {
     *   if (e.message === 'Skip Release') {
     *     console.log('Release skipped via environment variable');
     *   }
     * }
     * ```
     */
    exec(externalTuples?: PluginTuple<PluginClass>[]): Promise<unknown>;
}

/**
 * @module GitChangelog
 * @description Git-based changelog generation and commit parsing
 *
 * This module provides functionality for generating changelogs from Git
 * history, parsing commit messages according to conventional commit format,
 * and managing commit metadata.
 *
 * Core Features:
 * - Git log retrieval
 * - Conventional commit parsing
 * - Changelog generation
 * - Tag resolution
 * - PR number extraction
 *
 * @example Basic usage
 * ```typescript
 * const changelog = new GitChangelog({
 *   shell,
 *   logger,
 *   directory: 'packages/my-pkg'
 * });
 *
 * // Get commits between tags
 * const commits = await changelog.getCommits({
 *   from: 'v1.0.0',
 *   to: 'v2.0.0'
 * });
 * ```
 *
 * @example Commit parsing
 * ```typescript
 * const changelog = new GitChangelog({ shell, logger });
 *
 * // Parse conventional commit
 * const commit = changelog.parseCommitlint(
 *   'feat(api): add new endpoint',
 *   'Detailed description\n\nBREAKING CHANGE: API format changed'
 * );
 * // {
 * //   type: 'feat',
 * //   scope: 'api',
 * //   message: 'add new endpoint',
 * //   body: '  Detailed description\n\n  BREAKING CHANGE: API format changed'
 * // }
 * ```
 */

/**
 * Complete list of available Git commit fields
 *
 * These fields can be used when retrieving commit information
 * to specify which data should be included in the output.
 *
 * @example
 * ```typescript
 * const commits = await changelog.getGitLog({
 *   fields: CHANGELOG_ALL_FIELDS
 * });
 * ```
 */
declare const CHANGELOG_ALL_FIELDS: CommitField[];
interface GitChangelogProps extends GitChangelogOptions {
    shell: ShellInterface;
    logger: LoggerInterface;
}
/**
 * Core class for Git-based changelog generation
 *
 * Provides functionality for retrieving and parsing Git commit history,
 * generating changelogs, and managing commit metadata. Implements the
 * ChangeLogInterface for standardized changelog generation.
 *
 * Features:
 * - Git log retrieval with flexible options
 * - Conventional commit parsing
 * - Tag resolution and validation
 * - PR number extraction
 * - Commit body formatting
 *
 * @example Basic usage
 * ```typescript
 * const changelog = new GitChangelog({
 *   shell,
 *   logger,
 *   directory: 'packages/my-pkg'
 * });
 *
 * // Get commits with parsed metadata
 * const commits = await changelog.getCommits({
 *   from: 'v1.0.0',
 *   to: 'v2.0.0',
 *   noMerges: true
 * });
 * ```
 *
 * @example Custom commit parsing
 * ```typescript
 * const changelog = new GitChangelog({ shell, logger });
 *
 * // Create commit value from hash and message
 * const commit = changelog.toCommitValue(
 *   'abc1234',
 *   'feat(api): new endpoint (#123)'
 * );
 * // {
 * //   base: { hash: 'abc1234', ... },
 * //   commitlint: { type: 'feat', scope: 'api', ... },
 * //   prNumber: '123'
 * // }
 * ```
 */
declare class GitChangelog implements ChangeLogInterface {
    protected options: GitChangelogProps;
    /**
     * Creates a new GitChangelog instance
     *
     * @param options - Configuration options including shell and logger
     *
     * @example
     * ```typescript
     * const changelog = new GitChangelog({
     *   shell: new Shell(),
     *   logger: new Logger(),
     *   directory: 'packages/my-pkg',
     *   noMerges: true
     * });
     * ```
     */
    constructor(options: GitChangelogProps);
    /**
     * Retrieves Git commit history with specified options
     *
     * Fetches commit information between specified tags or commits,
     * with support for filtering and field selection.
     *
     * @param options - Configuration options for Git log retrieval
     * @returns Array of commit objects with requested fields
     *
     * @example Basic usage
     * ```typescript
     * const commits = await changelog.getGitLog({
     *   from: 'v1.0.0',
     *   to: 'v2.0.0',
     *   directory: 'packages/my-pkg',
     *   noMerges: true
     * });
     * ```
     *
     * @example Custom fields
     * ```typescript
     * const commits = await changelog.getGitLog({
     *   fields: ['hash', 'subject', 'authorName'],
     *   directory: 'src'
     * });
     * ```
     */
    getGitLog(options?: GitChangelogOptions): Promise<BaseCommit[]>;
    /**
     * Retrieves and parses Git commits with metadata
     *
     * Gets commit history and enhances it with parsed conventional
     * commit information and PR metadata.
     *
     * @override
     * @param options - Configuration options for Git log retrieval
     * @returns Array of enhanced commit objects with parsed metadata
     *
     * @example Basic usage
     * ```typescript
     * const commits = await changelog.getCommits({
     *   from: 'v1.0.0',
     *   to: 'v2.0.0'
     * });
     * // [
     * //   {
     * //     base: { hash: '...', subject: '...' },
     * //     commitlint: { type: 'feat', scope: 'api', ... },
     * //     commits: []
     * //   }
     * // ]
     * ```
     *
     * @example Filtered commits
     * ```typescript
     * const commits = await changelog.getCommits({
     *   directory: 'packages/my-pkg',
     *   noMerges: true
     * });
     * ```
     */
    getCommits(options?: GitChangelogOptions): Promise<CommitValue[]>;
    /**
     * Creates a base commit object from message and optional data
     *
     * Utility method to create a standardized commit object with
     * basic metadata. Used internally for commit value creation.
     *
     * @param message - Commit message
     * @param target - Optional additional commit data
     * @returns Base commit object
     * @protected
     *
     * @example
     * ```typescript
     * const commit = changelog.createBaseCommit(
     *   'feat: new feature',
     *   {
     *     hash: 'abc123',
     *     authorName: 'John Doe'
     *   }
     * );
     * ```
     */
    protected createBaseCommit(message: string, target?: Partial<BaseCommit>): BaseCommit;
    /**
     * Indents each line of a text block
     *
     * Adds specified number of spaces to the start of each line
     * in a multi-line string. Used for formatting commit body text.
     *
     * @since 2.3.2
     * @param body - Text to indent
     * @param size - Number of spaces to add (default: 2)
     * @returns Indented text
     *
     * @example
     * ```typescript
     * const text = changelog.tabify(
     *   'Line 1\nLine 2\nLine 3',
     *   4
     * );
     * // '    Line 1\n    Line 2\n    Line 3'
     * ```
     */
    tabify(body: string, size?: number): string;
    /**
     * Parses a commit message into conventional commit format
     *
     * Extracts type, scope, message, and body from a commit message
     * following the conventional commit specification.
     *
     * Format: type(scope): message
     *
     * @param subject - Commit subject line
     * @param rawBody - Full commit message body
     * @returns Parsed conventional commit data
     *
     * @example Basic commit
     * ```typescript
     * const commit = changelog.parseCommitlint(
     *   'feat(api): add new endpoint'
     * );
     * // {
     * //   type: 'feat',
     * //   scope: 'api',
     * //   message: 'add new endpoint'
     * // }
     * ```
     *
     * @example With body
     * ```typescript
     * const commit = changelog.parseCommitlint(
     *   'fix(core): memory leak',
     *   'Fixed memory leak in core module\n\nBREAKING CHANGE: API changed'
     * );
     * // {
     * //   type: 'fix',
     * //   scope: 'core',
     * //   message: 'memory leak',
     * //   body: '  Fixed memory leak in core module\n\n  BREAKING CHANGE: API changed'
     * // }
     * ```
     */
    parseCommitlint(subject: string, rawBody?: string): Commitlint;
    /**
     * Creates a complete commit value object from hash and message
     *
     * Combines commit hash, parsed conventional commit data, and
     * PR information into a single commit value object.
     *
     * @param hash - Commit hash
     * @param message - Full commit message
     * @returns Complete commit value object
     *
     * @example Basic commit
     * ```typescript
     * const commit = changelog.toCommitValue(
     *   'abc123',
     *   'feat(api): new endpoint'
     * );
     * // {
     * //   base: {
     * //     hash: 'abc123',
     * //     abbrevHash: 'abc123',
     * //     subject: 'feat(api): new endpoint'
     * //   },
     * //   commitlint: {
     * //     type: 'feat',
     * //     scope: 'api',
     * //     message: 'new endpoint'
     * //   },
     * //   commits: []
     * // }
     * ```
     *
     * @example PR commit
     * ```typescript
     * const commit = changelog.toCommitValue(
     *   'def456',
     *   'fix(core): memory leak (#123)'
     * );
     * // {
     * //   base: { hash: 'def456', ... },
     * //   commitlint: { type: 'fix', ... },
     * //   commits: [],
     * //   prNumber: '123'
     * // }
     * ```
     */
    toCommitValue(hash: string, message: string): CommitValue;
    /**
     * Resolves a Git tag or reference to a valid commit reference
     *
     * Attempts to resolve a tag name to a valid Git reference.
     * Falls back to root commit or HEAD if tag doesn't exist.
     *
     * @param tag - Tag name to resolve
     * @param fallback - Fallback value ('root' or 'HEAD')
     * @returns Resolved Git reference
     * @protected
     *
     * @example Basic tag resolution
     * ```typescript
     * const ref = await changelog.resolveTag('v1.0.0');
     * // 'v1.0.0' if tag exists
     * // 'HEAD' if tag doesn't exist
     * ```
     *
     * @example Root commit fallback
     * ```typescript
     * const ref = await changelog.resolveTag(
     *   'non-existent-tag',
     *   'root'
     * );
     * // First commit hash if tag doesn't exist
     * ```
     */
    protected resolveTag(tag?: string, fallback?: string): Promise<string>;
}

/**
 * @module GitChangelogFormatter
 * @description Formats Git commits into readable changelog entries
 *
 * This module provides functionality for formatting Git commits into
 * a structured changelog format, with support for conventional commits,
 * PR links, and custom templates.
 *
 * Core Features:
 * - Conventional commit formatting
 * - PR and commit linking
 * - Type-based grouping
 * - Custom templates
 * - Markdown formatting
 *
 * @example Basic usage
 * ```typescript
 * const formatter = new GitChangelogFormatter({
 *   shell,
 *   repoUrl: 'https://github.com/org/repo',
 *   types: [
 *     { type: 'feat', section: '### Features' },
 *     { type: 'fix', section: '### Bug Fixes' }
 *   ]
 * });
 *
 * const changelog = formatter.format(commits);
 * // ### Features
 * // - **api:** new endpoint ([abc123](https://github.com/org/repo/commit/abc123)) (#123)
 * //
 * // ### Bug Fixes
 * // - **core:** fix memory leak ([def456](https://github.com/org/repo/commit/def456))
 * ```
 *
 * @example Custom template
 * ```typescript
 * const formatter = new GitChangelogFormatter({
 *   shell,
 *   formatTemplate: '* ${commitlint.message} ${prLink}',
 *   types: [{ type: 'feat', section: '## New' }]
 * });
 *
 * const changelog = formatter.format(commits);
 * // ## New
 * // * add user authentication (#124)
 * ```
 */

/**
 * Configuration options for changelog formatting
 *
 * Extends GitChangelogOptions with repository URL support
 * for generating links to commits and pull requests.
 */
interface Options extends GitChangelogOptions {
    /**
     * Repository URL for generating links
     *
     * @example 'https://github.com/org/repo'
     */
    repoUrl?: string;
}
/**
 * Core class for formatting Git commits into changelog entries
 *
 * Implements ChangelogFormatter interface to provide standardized
 * changelog generation with support for:
 * - Conventional commit formatting
 * - Type-based grouping
 * - PR and commit linking
 * - Custom templates
 * - Markdown formatting
 *
 * @example Basic usage
 * ```typescript
 * const formatter = new GitChangelogFormatter({
 *   shell,
 *   repoUrl: 'https://github.com/org/repo',
 *   types: [
 *     { type: 'feat', section: '### Features' },
 *     { type: 'fix', section: '### Bug Fixes' }
 *   ]
 * });
 *
 * const changelog = formatter.format(commits);
 * ```
 *
 * @example Custom formatting
 * ```typescript
 * const formatter = new GitChangelogFormatter({
 *   shell,
 *   formatTemplate: '* ${commitlint.message}',
 *   types: [{ type: 'feat', section: '## New' }],
 *   commitBody: true // Include commit body
 * });
 * ```
 */
declare class GitChangelogFormatter implements ChangelogFormatter {
    protected options: Options & {
        shell: ShellInterface;
    };
    protected templateEngine: TemplateEngine;
    /**
     * Creates a new GitChangelogFormatter instance
     *
     * @param options - Configuration options including shell interface
     *
     * @example
     * ```typescript
     * const formatter = new GitChangelogFormatter({
     *   shell: new Shell(),
     *   repoUrl: 'https://github.com/org/repo',
     *   types: [
     *     { type: 'feat', section: '### Features' }
     *   ],
     *   formatTemplate: '- ${commitlint.message}'
     * });
     * ```
     */
    constructor(options: Options & {
        shell: ShellInterface;
    });
    /**
     * Formats an array of commits into changelog entries
     *
     * Groups commits by type and formats them according to the
     * configured template and options. Supports commit body
     * inclusion and type-based sections.
     *
     * @override
     * @param commits - Array of commit values to format
     * @param options - Optional formatting options
     * @returns Array of formatted changelog lines
     *
     * @example Basic formatting
     * ```typescript
     * const changelog = formatter.format([
     *   {
     *     base: { hash: 'abc123' },
     *     commitlint: {
     *       type: 'feat',
     *       scope: 'api',
     *       message: 'new endpoint'
     *     }
     *   }
     * ]);
     * // [
     * //   '### Features',
     * //   '- **api:** new endpoint ([abc123](...))'
     * // ]
     * ```
     *
     * @example With commit body
     * ```typescript
     * const changelog = formatter.format(
     *   [{
     *     commitlint: {
     *       type: 'fix',
     *       message: 'memory leak',
     *       body: 'Fixed memory allocation\nAdded cleanup'
     *     }
     *   }],
     *   { commitBody: true }
     * );
     * // [
     * //   '### Bug Fixes',
     * //   '- memory leak',
     * //   '  Fixed memory allocation',
     * //   '  Added cleanup'
     * // ]
     * ```
     */
    format(commits: CommitValue[], options?: Options): string[];
    /**
     * Formats a single commit into a changelog entry
     *
     * Applies the configured template to a commit, including
     * scope formatting, PR links, and commit hash links.
     *
     * @param commit - Commit value to format
     * @param options - Optional formatting options
     * @returns Formatted changelog entry
     *
     * @example Basic formatting
     * ```typescript
     * const entry = formatter.formatCommit({
     *   base: { hash: 'abc123' },
     *   commitlint: {
     *     type: 'feat',
     *     scope: 'api',
     *     message: 'new endpoint'
     *   }
     * });
     * // '- **api:** new endpoint ([abc123](...))'
     * ```
     *
     * @example With PR number
     * ```typescript
     * const entry = formatter.formatCommit({
     *   base: { hash: 'def456' },
     *   commitlint: {
     *     message: 'fix bug'
     *   },
     *   prNumber: '123'
     * });
     * // '- fix bug ([def456](...)) (#123)'
     * ```
     */
    formatCommit(commit: CommitValue, options?: Options): string;
    /**
     * Formats a target string as a Markdown link
     *
     * Creates a Markdown-formatted link with optional URL.
     * If no URL is provided, formats as a plain reference.
     *
     * @param target - Text to display
     * @param url - Optional URL for the link
     * @returns Formatted Markdown link
     *
     * @example With URL
     * ```typescript
     * const link = formatter.foramtLink('abc123', 'https://github.com/org/repo/commit/abc123');
     * // '([abc123](https://github.com/org/repo/commit/abc123))'
     * ```
     *
     * @example Without URL
     * ```typescript
     * const link = formatter.foramtLink('abc123');
     * // '(abc123)'
     * ```
     */
    foramtLink(target: string, url?: string): string;
    /**
     * Formats a commit hash as a Markdown link
     *
     * @deprecated Use foramtLink instead
     * @param target - Commit hash to display
     * @param url - Optional URL to the commit
     * @returns Formatted Markdown link
     *
     * @example
     * ```typescript
     * const link = formatter.formatCommitLink(
     *   'abc123',
     *   'https://github.com/org/repo/commit/abc123'
     * );
     * // '([abc123](https://github.com/org/repo/commit/abc123))'
     * ```
     */
    formatCommitLink(target: string, url?: string): string;
    /**
     * Formats a commit scope in Markdown
     *
     * Wraps the scope in bold syntax and adds a colon.
     *
     * @param scope - Scope to format
     * @returns Formatted scope in Markdown
     *
     * @example
     * ```typescript
     * const scope = formatter.formatScope('api');
     * // '**api:**'
     * ```
     */
    formatScope(scope: string): string;
}

/**
 * @module PluginLoader
 * @description Dynamic plugin loading and instantiation
 *
 * This module provides utilities for dynamically loading and instantiating
 * plugins from various sources (ESM imports, file paths, package names).
 * It supports concurrent loading with limits and fallback mechanisms.
 *
 * Core Features:
 * - Dynamic ESM imports
 * - Fallback to CommonJS require
 * - Concurrent loading with limits
 * - Plugin instantiation with context
 *
 * @example Basic plugin loading
 * ```typescript
 * // Load plugin by name
 * const [name, Plugin] = await load('@scope/my-plugin');
 *
 * // Load and instantiate multiple plugins
 * const plugins = await loaderPluginsFromPluginTuples(
 *   context,
 *   [
 *     tuple(MyPlugin, { option: 'value' }),
 *     tuple('@scope/my-plugin', { option: 'value' })
 *   ]
 * );
 * ```
 *
 * @example Custom concurrency
 * ```typescript
 * // Load plugins with custom concurrency limit
 * const plugins = await loaderPluginsFromPluginTuples(
 *   context,
 *   pluginTuples,
 *   3 // Max 3 concurrent loads
 * );
 * ```
 */

/**
 * Dynamically loads a plugin module
 *
 * Attempts to load a plugin using multiple strategies:
 * 1. Direct ESM import
 * 2. Import from current working directory
 * 3. Fallback to CommonJS require.resolve
 *
 * @template T - Plugin module type
 * @param pluginName - Plugin name or path to load
 * @returns Promise resolving to [plugin name, plugin module]
 * @throws If plugin cannot be loaded by any method
 *
 * @example Package import
 * ```typescript
 * const [name, Plugin] = await load('@scope/my-plugin');
 * const instance = new Plugin(context);
 * ```
 *
 * @example Local file import
 * ```typescript
 * const [name, Plugin] = await load('./plugins/MyPlugin');
 * const instance = new Plugin(context);
 * ```
 *
 * @example Error handling
 * ```typescript
 * try {
 *   const [name, Plugin] = await load('non-existent');
 * } catch (error) {
 *   console.error('Failed to load plugin:', error);
 * }
 * ```
 */
declare function load<T>(pluginName: string): Promise<[string, T]>;
/**
 * Loads and instantiates multiple plugins concurrently
 *
 * Takes an array of plugin tuples and creates plugin instances
 * with the provided context. Supports both class-based and
 * string-based plugin specifications.
 *
 * Features:
 * - Concurrent loading with configurable limit
 * - Mixed plugin types (class/string)
 * - Automatic context injection
 * - Type-safe instantiation
 *
 * @template T - Plugin instance type
 * @param context - Release context for plugin initialization
 * @param pluginsTuples - Array of plugin configuration tuples
 * @param maxLimit - Maximum concurrent plugin loads (default: 5)
 * @returns Promise resolving to array of plugin instances
 *
 * @example Basic usage
 * ```typescript
 * const plugins = await loaderPluginsFromPluginTuples(
 *   context,
 *   [
 *     tuple(MyPlugin, { option: 'value' }),
 *     tuple('@scope/plugin', { option: 'value' })
 *   ]
 * );
 * ```
 *
 * @example Custom concurrency
 * ```typescript
 * const plugins = await loaderPluginsFromPluginTuples(
 *   context,
 *   pluginTuples,
 *   3  // Load max 3 plugins at once
 * );
 * ```
 *
 * @example Type-safe loading
 * ```typescript
 * interface MyPlugin extends ScriptPlugin {
 *   customMethod(): void;
 * }
 *
 * const plugins = await loaderPluginsFromPluginTuples<MyPlugin>(
 *   context,
 *   pluginTuples
 * );
 *
 * plugins.forEach(plugin => plugin.customMethod());
 * ```
 */
declare function loaderPluginsFromPluginTuples<T extends ScriptPlugin<ReleaseContext, ScriptPluginProps>>(context: ReleaseContext, pluginsTuples: PluginTuple<PluginClass>[], maxLimit?: number): Promise<T[]>;

/**
 * @module Factory
 * @description Type-safe factory function for class and function instantiation
 *
 * This module provides a flexible factory function that can handle both
 * class constructors and factory functions with proper type inference.
 *
 * Core Features:
 * - Type-safe instantiation
 * - Support for both classes and functions
 * - Argument type inference
 * - Runtime constructor detection
 *
 * @example Basic usage
 * ```typescript
 * // Class-based
 * class MyClass {
 *   constructor(name: string, value: number) {}
 * }
 *
 * const instance = factory(MyClass, 'test', 42);
 *
 * // Function-based
 * function createObject(config: { option: string }) {
 *   return { ...config };
 * }
 *
 * const object = factory(createObject, { option: 'value' });
 * ```
 */
/**
 * Combined type for class constructors and factory functions
 *
 * Represents either a class constructor or a factory function
 * with proper typing for arguments and return value.
 *
 * @template T - Return type
 * @template Args - Tuple type for arguments
 *
 * @example Class constructor
 * ```typescript
 * class MyClass {
 *   constructor(name: string) {}
 * }
 *
 * const ctor: ConstructorType<MyClass, [string]> = MyClass;
 * ```
 *
 * @example Factory function
 * ```typescript
 * interface Config {
 *   option: string;
 * }
 *
 * const factory: ConstructorType<Config, [string]> =
 *   (option: string) => ({ option });
 * ```
 */
type ConstructorType<T, Args extends unknown[]> = (new (...args: Args) => T) | ((...args: Args) => T);
/**
 * Creates instances from constructors or factory functions
 *
 * A flexible factory function that can handle both class constructors
 * and factory functions. It automatically detects the type at runtime
 * and uses the appropriate instantiation method.
 *
 * Features:
 * - Automatic constructor detection
 * - Type-safe argument passing
 * - Support for both classes and functions
 * - Generic type inference
 *
 * @template T - Return type
 * @template Args - Tuple type for arguments
 * @param Constructor - Class constructor or factory function
 * @param args - Arguments to pass to constructor/function
 * @returns Instance of type T
 *
 * @example Class instantiation
 * ```typescript
 * class Logger {
 *   constructor(name: string, level: string) {
 *     // Implementation
 *   }
 * }
 *
 * const logger = factory(Logger, 'main', 'debug');
 * ```
 *
 * @example Factory function
 * ```typescript
 * interface Config {
 *   name: string;
 *   options: Record<string, unknown>;
 * }
 *
 * function createConfig(name: string, options = {}): Config {
 *   return { name, options };
 * }
 *
 * const config = factory(createConfig, 'myConfig', { debug: true });
 * ```
 *
 * @example Generic types
 * ```typescript
 * class Container<T> {
 *   constructor(value: T) {
 *     // Implementation
 *   }
 * }
 *
 * const container = factory<Container<string>, [string]>(
 *   Container,
 *   'value'
 * );
 * ```
 */
declare function factory<T, Args extends unknown[]>(Constructor: ConstructorType<T, Args>, ...args: Args): T;

/**
 * @module CommanderArgs
 * @description Command-line argument processing utilities
 *
 * This module provides utilities for processing and transforming
 * command-line arguments from Commander.js into structured objects.
 * It supports dot notation for nested properties and common prefix
 * grouping.
 *
 * Core Features:
 * - Dot notation support
 * - Common prefix grouping
 * - Deep object creation
 * - Type-safe processing
 *
 * @example Basic usage
 * ```typescript
 * const args = {
 *   verbose: true,
 *   'config.port': 3000,
 *   'config.host': 'localhost'
 * };
 *
 * const processed = reduceOptions(args);
 * // {
 * //   verbose: true,
 * //   config: {
 * //     port: 3000,
 * //     host: 'localhost'
 * //   }
 * // }
 * ```
 *
 * @example With common prefix
 * ```typescript
 * const args = {
 *   verbose: true,
 *   port: 3000
 * };
 *
 * const processed = reduceOptions(args, 'options');
 * // {
 * //   options: {
 * //     verbose: true,
 * //     port: 3000
 * //   }
 * // }
 * ```
 */

/**
 * Processes Commander.js options into a structured object
 *
 * Takes raw options from Commander.js and transforms them into a
 * structured object, handling dot notation for nested properties
 * and optional common prefix grouping.
 *
 * Features:
 * - Dot notation parsing (e.g., 'config.port' → { config: { port: value } })
 * - Common prefix grouping (e.g., { port: 3000 } → { common: { port: 3000 } })
 * - Deep object creation with lodash/set
 * - Preserves value types
 *
 * @param opts - Raw options from Commander.js
 * @param commonKey - Optional prefix for non-nested properties
 * @returns Processed options object
 *
 * @example Basic dot notation
 * ```typescript
 * const args = {
 *   'server.port': 3000,
 *   'server.host': 'localhost',
 *   verbose: true
 * };
 *
 * const result = reduceOptions(args);
 * // {
 * //   server: {
 * //     port: 3000,
 * //     host: 'localhost'
 * //   },
 * //   verbose: true
 * // }
 * ```
 *
 * @example With common prefix
 * ```typescript
 * const args = {
 *   'config.debug': true,
 *   port: 3000,
 *   host: 'localhost'
 * };
 *
 * const result = reduceOptions(args, 'server');
 * // {
 * //   config: {
 * //     debug: true
 * //   },
 * //   server: {
 * //     port: 3000,
 * //     host: 'localhost'
 * //   }
 * // }
 * ```
 */
declare function reduceOptions(opts: OptionValues, commonKey?: string): OptionValues;

export { type BaseCommit, CHANGELOG_ALL_FIELDS, type ChangeLogInterface, type ChangelogFormatter, ChangesetVersion, type ChangesetVersionMode, type ChangesetVersionProps, type CommitTuple, type CommitValue, type Commitlint, type ConstructorType, type DeepPartial, type ExecutorReleaseContext, GitChangelog, GitChangelogFormatter, type GitChangelogOptions, type GitChangelogProps, MANIFEST_PATH, type Options, type PackageJson, type PluginClass, type PluginConstructorParams, type PluginTuple, type ReleaseConfig, ReleaseContext, type ReleaseContextOptions$1 as ReleaseContextOptions, type ReleaseGlobalConfig, ReleaseLabel, type ReleaseLabelCompare, type ReleaseLabelOptions, type ReleaseReturnValue, ReleaseTask, type StepOption, TEMPLATE_OPEN, type TemplateContext, type WorkspaceInterface, defaultReleaaseName, factory, load, loaderPluginsFromPluginTuples, reduceOptions, releaseJson, tuple };