index.d.ts

/* auto-generated by NAPI-RS */
/* eslint-disable */
/**
 * Main APVM instance for building WordPress plugins.
 *
 * Create an instance using `Apvm.create()` or `Apvm.createWithTokenResolution()`,
 * then call the `build()` method (or the convenience methods `buildFromPr()`,
 * `buildFromBranch()`, `buildFromTag()`, `buildFromCommit()`) to produce
 * plugin artifacts.
 *
 * The instance is safe to use concurrently — you can fire multiple `build()`
 * calls in parallel and they will run independently on the tokio runtime.
 *
 * # TypeScript
 *
 * ```typescript
 * import { Apvm } from 'apvm-napi';
 *
 * // Minimal — no config needed, uses temp dir for builds
 * const apvm = await Apvm.create({});
 *
 * // Create with explicit builds dir and token
 * const apvm = await Apvm.create({
 *   buildsDir: '/var/lib/apvm/builds',
 *   githubToken: 'ghp_xxxxxxxxxxxx',
 * });
 *
 * // Or with automatic token resolution (tries env vars, gh CLI, etc.)
 * const apvm = await Apvm.createWithTokenResolution({});
 *
 * // Build WP Rocket from a PR
 * const output = await apvm.build({
 *   project: 'wp-rocket',
 *   gitRef: 'pr:456',
 *   outputDir: '/tmp/output',
 *   onProgress: (err, event) => {
 *     if (err || !event) return;
 *     console.log(event.type, event.message);
 *   },
 * });
 * ```
 */
export declare class Apvm {
  /**
   * Create a new APVM instance with the given configuration.
   *
   * Uses the provided GitHub token directly (if any). For automatic token
   * resolution from environment variables and `gh` CLI, use
   * `createWithTokenResolution()` instead.
   *
   * This method is async because the underlying HTTP client (octocrab)
   * requires a Tokio runtime during initialization.
   *
   * # Arguments
   *
   * * `config` - Configuration options. All fields are optional:
   *   - `buildsDir` — where artifacts are stored (uses temp dir if omitted)
   *   - `githubToken` — GitHub PAT for private repos
   *
   * # Throws
   *
   * - If the GitHub client cannot be initialized (e.g., invalid token format)
   *
   * # TypeScript
   *
   * ```typescript
   * // Minimal — uses a temp directory for builds
   * const apvm = await Apvm.create({});
   *
   * // With explicit config
   * const apvm = await Apvm.create({
   *   buildsDir: '/var/lib/apvm/builds',
   *   githubToken: 'ghp_xxxxxxxxxxxx',
   * });
   * ```
   */
  static create(config?: ApvmConfig | undefined | null): Promise<Apvm>
  /**
   * Create a new APVM instance with automatic GitHub token resolution.
   *
   * Tries to find a GitHub token from multiple sources (in order):
   *
   * 1. The `githubToken` field in the config (if provided)
   * 2. `GITHUB_TOKEN` environment variable
   * 3. `GH_TOKEN` environment variable
   * 4. `gh auth token` command (gh CLI >= 2.17.0)
   * 5. gh CLI config file (`~/.config/gh/hosts.yml`)
   *
   * This method is async because it may need to execute `gh auth token`
   * as a subprocess.
   *
   * # Arguments
   *
   * * `config` - Configuration options. All fields are optional:
   *   - `buildsDir` — where artifacts are stored (uses temp dir if omitted)
   *   - `githubToken` — if set, skips resolution and uses this token
   *
   * # Throws
   *
   * - If the GitHub client cannot be initialized
   *
   * # TypeScript
   *
   * ```typescript
   * // Minimal — resolves token automatically, uses temp builds dir
   * const apvm = await Apvm.createWithTokenResolution({});
   *
   * // With explicit builds dir
   * const apvm = await Apvm.createWithTokenResolution({
   *   buildsDir: '/var/lib/apvm/builds',
   * });
   *
   * console.log('Has token:', apvm.hasToken());
   * ```
   */
  static createWithTokenResolution(config?: ApvmConfig | undefined | null): Promise<Apvm>
  /**
   * Check if a GitHub token is available.
   *
   * Returns `true` if a token was found (either from config or resolved
   * from environment). A token is required for building from private
   * repositories (e.g., BackWPup).
   *
   * # TypeScript
   *
   * ```typescript
   * if (!apvm.hasToken()) {
   *   console.warn('No GitHub token — private repos will fail');
   * }
   * ```
   */
  hasToken(): boolean
  /**
   * Get a human-readable description of where the token came from.
   *
   * Returns `null` if no token is available.
   *
   * Possible values: `"config file"`, `"GITHUB_TOKEN"`, `"GH_TOKEN"`,
   * `"gh auth token"`, `"gh config"`.
   *
   * # TypeScript
   *
   * ```typescript
   * const source = apvm.tokenSource();
   * if (source) {
   *   console.log(`Token from: ${source}`);
   * }
   * ```
   */
  tokenSource(): string | null
  /**
   * List all registered project names.
   *
   * Returns the names of projects that can be built (e.g., `["backwpup", "wp-rocket"]`).
   *
   * # TypeScript
   *
   * ```typescript
   * const projects = apvm.listProjects();
   * // => ['backwpup', 'wp-rocket']
   * ```
   */
  listProjects(): Array<string>
  /**
   * Build a project from any git reference.
   *
   * This is the primary build method. It accepts a flexible `gitRef` string
   * that supports automatic detection of the reference type, or explicit
   * prefixes for disambiguation.
   *
   * The build runs asynchronously on the tokio runtime and returns a
   * Promise that resolves with the complete build output.
   *
   * # Arguments
   *
   * * `options` - Build configuration (project, gitRef, outputDir, etc.)
   * * `on_progress` - Optional callback for receiving build progress events.
   *   Called with Node.js error-first callback shape:
   *   `(err, event) => void`, where `event` is a [`JsBuildEvent`].
   *
   * # Throws
   *
   * - `InvalidArg` if the project is not found
   * - `InvalidArg` if a private repo has no token
   * - `GenericFailure` for git, build, or I/O errors
   *
   * # TypeScript
   *
   * ```typescript
   * // Minimal (WP Rocket from a PR)
   * const output = await apvm.build({
   *   project: 'wp-rocket',
   *   gitRef: 'pr:456',
   *   outputDir: '/tmp/output',
   * });
   *
   * // Full (BackWPup with version, variants, and progress)
   * const output = await apvm.build(
   *   {
   *     project: 'backwpup',
   *     gitRef: 'pr:123',
   *     version: '5.1.0',
   *     variants: ['pro'],
   *     outputDir: '/tmp/output',
   *   },
   *   (err, event) => {
   *     if (err || !event) return;
   *     if (event.type === 'phase_started') {
   *       console.log(`[${event.phase}] ${event.message}`);
   *     }
   *   },
   * );
   * ```
   */
  build(options: BuildOptions, onProgress?: (err: Error | null, event: JsBuildEvent) => void): Promise<JsBuildOutput>
  /**
   * Build a project from a pull request number.
   *
   * Convenience method equivalent to `build({ gitRef: 'pr:{prNumber}', ... })`.
   *
   * # Arguments
   *
   * * `project` - Project name (`"backwpup"` or `"wp-rocket"`)
   * * `pr_number` - Pull request number
   * * `output_dir` - Directory for build artifacts
   * * `version` - Optional version (required for BackWPup)
   * * `variants` - Optional variant filter
   * * `on_progress` - Optional progress callback
   *
   * # TypeScript
   *
   * ```typescript
   * const output = await apvm.buildFromPr(
   *   'wp-rocket', 456, '/tmp/output',
   *   undefined, undefined,
   *   (err, event) => {
   *     if (err || !event) return;
   *     console.log(event.type);
   *   },
   * );
   * ```
   */
  buildFromPr(project: string, prNumber: number, outputDir: string, version?: string, variants?: string[], onProgress?: (err: Error | null, event: JsBuildEvent) => void): Promise<JsBuildOutput>
  /**
   * Build a project from a branch name.
   *
   * Convenience method equivalent to `build({ gitRef: 'branch:{branch}', ... })`.
   *
   * # Arguments
   *
   * * `project` - Project name (`"backwpup"` or `"wp-rocket"`)
   * * `branch` - Branch name (e.g., `"develop"`, `"feature/my-feature"`)
   * * `output_dir` - Directory for build artifacts
   * * `version` - Optional version (required for BackWPup)
   * * `variants` - Optional variant filter
   * * `on_progress` - Optional progress callback
   *
   * # TypeScript
   *
   * ```typescript
   * const output = await apvm.buildFromBranch(
   *   'wp-rocket', 'develop', '/tmp/output',
   * );
   * ```
   */
  buildFromBranch(project: string, branch: string, outputDir: string, version?: string, variants?: string[], onProgress?: (err: Error | null, event: JsBuildEvent) => void): Promise<JsBuildOutput>
  /**
   * Build a project from a tag.
   *
   * Convenience method equivalent to `build({ gitRef: 'tag:{tag}', ... })`.
   *
   * # Arguments
   *
   * * `project` - Project name (`"backwpup"` or `"wp-rocket"`)
   * * `tag` - Tag name (e.g., `"v1.0.0"`, `"3.17.4"`)
   * * `output_dir` - Directory for build artifacts
   * * `version` - Optional version (required for BackWPup)
   * * `variants` - Optional variant filter
   * * `on_progress` - Optional progress callback
   *
   * # TypeScript
   *
   * ```typescript
   * const output = await apvm.buildFromTag(
   *   'wp-rocket', 'v3.17.4', '/tmp/output',
   * );
   * ```
   */
  buildFromTag(project: string, tag: string, outputDir: string, version?: string, variants?: string[], onProgress?: (err: Error | null, event: JsBuildEvent) => void): Promise<JsBuildOutput>
  /**
   * Build a project from a specific commit SHA.
   *
   * Convenience method equivalent to `build({ gitRef: 'commit:{commit}', ... })`.
   *
   * # Arguments
   *
   * * `project` - Project name (`"backwpup"` or `"wp-rocket"`)
   * * `commit` - Commit SHA (minimum 7 characters)
   * * `output_dir` - Directory for build artifacts
   * * `version` - Optional version (required for BackWPup)
   * * `variants` - Optional variant filter
   * * `on_progress` - Optional progress callback
   *
   * # TypeScript
   *
   * ```typescript
   * const output = await apvm.buildFromCommit(
   *   'wp-rocket', 'a1b2c3d', '/tmp/output',
   * );
   * ```
   */
  buildFromCommit(project: string, commit: string, outputDir: string, version?: string, variants?: string[], onProgress?: (err: Error | null, event: JsBuildEvent) => void): Promise<JsBuildOutput>
}

/**
 * Configuration options for creating an APVM instance.
 *
 * This is a plain JavaScript object (not a class) that you pass
 * to [`Apvm.create()`] or [`Apvm.createWithTokenResolution()`].
 *
 * All fields are optional — when `buildsDir` is omitted, a temporary
 * directory is created automatically.
 *
 * # TypeScript
 *
 * ```typescript
 * // Minimal — temp builds dir, no token
 * const apvm = Apvm.create({});
 *
 * // With explicit builds directory
 * const apvm = Apvm.create({ buildsDir: '/var/lib/apvm/builds' });
 *
 * // Full configuration
 * const config: ApvmConfig = {
 *   buildsDir: '/var/lib/apvm/builds',
 *   githubToken: 'ghp_xxxxxxxxxxxx',
 * };
 * ```
 */
export interface ApvmConfig {
  /**
   * Directory where built artifacts will be stored.
   *
   * When omitted (`null` or `undefined`), a temporary directory is created
   * automatically under the system temp path (e.g., `/tmp/apvm-<pid>-<hex>/builds`).
   * This is ideal for one-off builds where persistent storage is not needed.
   *
   * When provided, must be an absolute path to an existing (or creatable) directory.
   */
  buildsDir?: string
  /**
   * GitHub Personal Access Token for API requests.
   *
   * Required for private repositories (e.g., BackWPup).
   * Optional for public repositories (e.g., WP Rocket), but recommended
   * for higher API rate limits (5000 vs 60 requests/hour).
   *
   * The token needs the `repo` scope for private repositories.
   */
  githubToken?: string
}

/**
 * Options for a build operation.
 *
 * Pass this object to any `Apvm.build*()` method to configure the build.
 *
 * # Required Fields
 *
 * - `project` — Project name (`"backwpup"` or `"wp-rocket"`)
 * - `outputDir` — Directory where artifacts will be placed
 *
 * # TypeScript
 *
 * ```typescript
 * // Minimal (WP Rocket, version auto-detected)
 * await apvm.build({
 *   project: 'wp-rocket',
 *   gitRef: 'pr:456',
 *   outputDir: '/tmp/output',
 * });
 *
 * // Full options (BackWPup, version required)
 * await apvm.build({
 *   project: 'backwpup',
 *   gitRef: 'pr:123',
 *   version: '5.1.0',
 *   variants: ['pro', 'free'],
 *   outputDir: '/tmp/output',
 *   onProgress: (event) => console.log(event),
 * });
 * ```
 */
export interface BuildOptions {
  /**
   * The project to build.
   *
   * Must be a registered project name: `"backwpup"` or `"wp-rocket"`.
   */
  project: string
  /**
   * Git reference to build from.
   *
   * Supports automatic detection or explicit prefixes:
   * - `"123"` → PR #123 (or branch if PR doesn't exist)
   * - `"pr:123"` → Force PR interpretation
   * - `"branch:develop"` → Force branch interpretation
   * - `"tag:v1.0.0"` → Force tag interpretation
   * - `"commit:a1b2c3d"` → Force commit interpretation
   * - `"develop"` → Branch name
   * - `"v1.0.0"` → Tag (if exists) or branch
   */
  gitRef: string
  /**
   * Version to build.
   *
   * - **BackWPup**: Required (e.g., `"5.1.0"`)
   * - **WP Rocket**: Optional, auto-detected from source code if omitted
   */
  version?: string
  /**
   * Specific variants to build.
   *
   * When `null` or omitted, all variants are built.
   *
   * - **BackWPup**: Supports `["pro", "free"]`
   * - **WP Rocket**: Has no variants (this field is ignored)
   */
  variants?: Array<string>
  /**
   * Directory where build artifacts will be placed.
   *
   * Must be an absolute path. The directory will be created if it
   * doesn't exist.
   */
  outputDir: string
}

/**
 * A build progress event.
 *
 * Events use a discriminated union pattern — check the `type` field to
 * determine the event variant, then access the corresponding fields.
 *
 * # Event Types
 *
 * | `type`             | Fields Available                              |
 * |--------------------|-----------------------------------------------|
 * | `phase_started`    | `phase`, `message`                            |
 * | `phase_completed`  | `phase`                                       |
 * | `step_started`     | `step`                                        |
 * | `step_completed`   | `step`                                        |
 * | `command_output`   | `stream`, `line`                              |
 * | `warning`          | `message`                                     |
 * | `build_succeeded`  | `artifacts` (list of file paths)              |
 * | `build_failed`     | `reason`                                      |
 *
 * # TypeScript
 *
 * ```typescript
 * apvm.build({
 *   project: 'wp-rocket',
 *   gitRef: 'pr:456',
 *   outputDir: '/tmp',
 *   onProgress: (event) => {
 *     switch (event.type) {
 *       case 'phase_started':
 *         console.log(`[${event.phase}] ${event.message}`);
 *         break;
 *       case 'step_started':
 *         console.log(`  Running: ${event.step?.label}`);
 *         break;
 *       case 'command_output':
 *         if (verbose) console.log(`    [${event.stream}] ${event.line}`);
 *         break;
 *       case 'build_succeeded':
 *         console.log(`Done! ${event.artifacts?.length} artifacts`);
 *         break;
 *       case 'build_failed':
 *         console.error(`FAILED: ${event.reason}`);
 *         break;
 *     }
 *   },
 * });
 * ```
 */
export interface JsBuildEvent {
  /**
   * Event type discriminator.
   *
   * One of: `"phase_started"`, `"phase_completed"`, `"step_started"`,
   * `"step_completed"`, `"command_output"`, `"warning"`,
   * `"build_succeeded"`, `"build_failed"`.
   */
  type: string
  /** Build phase (present for `phase_started` and `phase_completed` events). */
  phase?: JsBuildPhase
  /** Human-readable message (present for `phase_started` and `warning` events). */
  message?: string
  /** Build step details (present for `step_started` and `step_completed` events). */
  step?: JsBuildStep
  /** Output stream type (present for `command_output` events). */
  stream?: JsOutputStream
  /** Command output line (present for `command_output` events). */
  line?: string
  /** Artifact file paths (present for `build_succeeded` events). */
  artifacts?: Array<string>
  /** Failure reason (present for `build_failed` events). */
  reason?: string
}

/**
 * Complete output from a build operation.
 *
 * This is the main return type from all `Apvm.build*()` methods. It contains
 * the build artifacts, the resolved git reference, and all metadata needed
 * to identify and store the build.
 *
 * # TypeScript
 *
 * ```typescript
 * const output = await apvm.build({ project: 'wp-rocket', gitRef: 'pr:456', outputDir: '/tmp' });
 *
 * console.log(`Built: ${output.description}`);
 * console.log(`Version: ${output.result.version}`);
 * console.log(`Commit: ${output.commitShort}`);
 * console.log(`Artifacts: ${output.result.artifacts.length}`);
 *
 * for (const artifact of output.result.artifacts) {
 *   console.log(`  ${artifact.filename} (${artifact.size} bytes)`);
 * }
 * ```
 */
export interface JsBuildOutput {
  /** The build result containing artifacts and version info. */
  result: JsBuildResult
  /** The resolved git reference with full metadata. */
  resolvedRef: JsResolvedRef
  /** Full commit SHA of what was built. */
  commit: string
  /** Short commit SHA (7 characters). */
  commitShort: string
  /** Branch name that was checked out. */
  branch: string
  /**
   * Human-readable description of what was built.
   *
   * Example: `"PR #123 @ a1b2c3d"`, `"branch 'develop' @ e4f5g6h"`
   */
  description: string
}

/**
 * High-level phases of the build process.
 *
 * Each build goes through these phases in order. Use this to track
 * overall build progress in your UI.
 *
 * # TypeScript
 *
 * ```typescript
 * switch (event.phase) {
 *   case 'Clone': console.log('Cloning repository...'); break;
 *   case 'Build': console.log('Building plugin...'); break;
 *   case 'CollectArtifacts': console.log('Almost done...'); break;
 * }
 * ```
 */
export declare const enum JsBuildPhase {
  /** Cloning the git repository. */
  Clone = 'Clone',
  /** Checking out the target ref (branch, tag, PR, commit). */
  Checkout = 'Checkout',
  /** Verifying tool dependencies (npm, composer, etc.). */
  DependencyCheck = 'DependencyCheck',
  /** Running builder's pre-build hook. */
  PreBuild = 'PreBuild',
  /** Executing setup commands (dependency installation). */
  Setup = 'Setup',
  /** Running the main build commands. */
  Build = 'Build',
  /** Running builder's build hook. */
  BuildHook = 'BuildHook',
  /** Running builder's post-build hook. */
  PostBuild = 'PostBuild',
  /** Collecting and verifying build artifacts. */
  CollectArtifacts = 'CollectArtifacts'
}

/**
 * Result of a successful build operation.
 *
 * Contains all produced artifacts, the resolved version, and build context.
 */
export interface JsBuildResult {
  /** The artifacts produced by the build. */
  artifacts: Array<JsProducedArtifact>
  /** The directory where the build was performed. */
  buildDir: string
  /** The version that was built (e.g., `"5.1.0"`, `"3.17.4"`). */
  version: string
  /**
   * The variants that were built (empty array if no variants).
   *
   * Example: `["pro", "free"]` for BackWPup, `[]` for WP Rocket.
   */
  variantsBuilt: Array<string>
  /** Total size of all artifacts in bytes. */
  totalSize: number
  /** Number of artifacts produced. */
  artifactCount: number
}

/**
 * A single build step within a phase.
 *
 * Steps represent individual shell commands or operations. The `label`
 * is a human-readable description suitable for display, while `command`
 * contains the actual shell command (useful for debug/verbose logging).
 *
 * # TypeScript
 *
 * ```typescript
 * console.log(`Running: ${step.label}`);
 * // verbose mode:
 * console.log(`  $ ${step.command}`);
 * ```
 */
export interface JsBuildStep {
  /**
   * Human-readable description of what this step does.
   *
   * Example: `"Installing production dependencies"`
   */
  label: string
  /**
   * The actual shell command being executed.
   *
   * Example: `"composer install --no-dev --no-scripts"`
   */
  command: string
}

/**
 * Which output stream a command line came from.
 *
 * Used in `CommandOutput` events to distinguish between stdout and stderr.
 */
export declare const enum JsOutputStream {
  /** Standard output. */
  Stdout = 'Stdout',
  /** Standard error. */
  Stderr = 'Stderr'
}

/**
 * A single artifact produced by a build.
 *
 * Represents a built file (typically a zip archive) that can be stored
 * or distributed.
 *
 * # TypeScript
 *
 * ```typescript
 * for (const artifact of output.result.artifacts) {
 *   console.log(`${artifact.filename} (${artifact.size} bytes)`);
 *   if (artifact.variantId) {
 *     console.log(`  Variant: ${artifact.variantId}`);
 *   }
 * }
 * ```
 */
export interface JsProducedArtifact {
  /**
   * Variant ID this artifact belongs to.
   *
   * `null` for single-variant projects (e.g., WP Rocket).
   * Set to variant name for multi-variant projects (e.g., `"pro"`, `"free"`).
   */
  variantId?: string
  /** Full path to the artifact file on disk. */
  path: string
  /** Target filename (how it should be named in storage). */
  filename: string
  /**
   * File size in bytes.
   *
   * Note: Represented as a JavaScript `number`. Files larger than 2^53 bytes
   * (8 PB) would lose precision, which is not a practical concern.
   */
  size: number
}

/**
 * The type of git reference that was resolved.
 *
 * This uses a discriminated union pattern — check the `type` field
 * to determine the variant, then read `value` for the associated data.
 *
 * # TypeScript
 *
 * ```typescript
 * switch (source.type) {
 *   case 'pull_request': console.log(`PR #${source.value}`); break;
 *   case 'branch': console.log(`Branch: ${source.value}`); break;
 *   case 'tag': console.log(`Tag: ${source.value}`); break;
 *   case 'commit': console.log(`Commit: ${source.value}`); break;
 * }
 * ```
 */
export interface JsRefSource {
  /** The type of reference: `"pull_request"`, `"branch"`, `"tag"`, or `"commit"`. */
  type: string
  /**
   * The value associated with the reference type.
   *
   * - For `pull_request`: the PR number as a string (e.g., `"123"`)
   * - For `branch`: the branch name (e.g., `"develop"`)
   * - For `tag`: the tag name (e.g., `"v1.0.0"`)
   * - For `commit`: the commit SHA (e.g., `"a1b2c3d"`)
   */
  value: string
  /** A human-readable description (e.g., `"PR #123"`, `"branch 'develop'"`) */
  description: string
}

/**
 * A resolved git reference with full metadata.
 *
 * Returned as part of [`JsBuildOutput`] to describe exactly what was built.
 */
export interface JsResolvedRef {
  /** The original input from the user (e.g., `"pr:123"`, `"develop"`). */
  input: string
  /** The detected source type and value. */
  source: JsRefSource
  /** The git ref that was checked out (branch name, tag, or commit SHA). */
  gitRef: string
  /** Full commit SHA, if resolved. */
  commitSha?: string
}