import { ChildProcess, SpawnOptions } from 'node:child_process';
import { CustomErrorBase } from '@backstage/errors';

/**
 * A function that takes a set of path fragments and resolves them into a
 * single complete path, relative to some root.
 *
 * @public
 */
type ResolveFunc = (...paths: string[]) => string;
/**
 * Resolved paths relative to the target project, based on `process.cwd()`.
 * Lazily initialized on first property access. Re-resolves automatically
 * when `process.cwd()` changes.
 *
 * @public
 */
type TargetPaths = {
    /** The target package directory. */
    dir: string;
    /** The target monorepo root directory. */
    rootDir: string;
    /** Resolve a path relative to the target package directory. */
    resolve: ResolveFunc;
    /** Resolve a path relative to the target repo root. */
    resolveRoot: ResolveFunc;
};
/**
 * Resolved paths relative to a specific package in the repository.
 *
 * @public
 */
type OwnPaths = {
    /** The package root directory. */
    dir: string;
    /** The monorepo root directory containing the package. */
    rootDir: string;
    /** Resolve a path relative to the package root. */
    resolve: ResolveFunc;
    /** Resolve a path relative to the monorepo root containing the package. */
    resolveRoot: ResolveFunc;
};
/**
 * Common paths and resolve functions used by the cli.
 * Currently assumes it is being executed within a monorepo.
 *
 * @public
 * @deprecated Use {@link targetPaths} and {@link findOwnPaths} instead.
 */
type Paths = {
    ownDir: string;
    ownRoot: string;
    targetDir: string;
    targetRoot: string;
    resolveOwn: ResolveFunc;
    resolveOwnRoot: ResolveFunc;
    resolveTarget: ResolveFunc;
    resolveTargetRoot: ResolveFunc;
};
/**
 * Lazily resolved paths relative to the target project. Import this directly
 * for cwd-based path resolution without needing `__dirname`.
 *
 * @public
 */
declare const targetPaths: TargetPaths;
/**
 * Find paths relative to the package that the calling code lives in.
 *
 * Results are cached per package root, and the package root lookup uses a
 * hierarchical directory cache so that multiple calls from different
 * subdirectories within the same package share work.
 *
 * @public
 */
declare function findOwnPaths(searchDir: string): OwnPaths;
/**
 * Find paths related to a package and its execution context.
 *
 * @public
 * @deprecated Use {@link targetPaths} for cwd-based paths and
 * {@link findOwnPaths} for package-relative paths instead.
 *
 * @example
 *
 * const paths = findPaths(__dirname)
 */
declare function findPaths(searchDir: string): Paths;
/**
 * The name of the backstage's config file
 *
 * @public
 */
declare const BACKSTAGE_JSON = "backstage.json";

/**
 * Checks if path is the same as or a child path of base.
 *
 * @public
 */
declare function isChildPath(base: string, path: string): boolean;

/**
 * This function can be called to setup undici and node-fetch Proxy agents.
 *
 * You can set GLOBAL_AGENT_HTTP(S)_PROXY to configure a proxy to be used in the
 * CLIs.
 *
 * You can also configure a custom namespace by setting
 * GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACE which will replace the default
 * "GLOBAL_AGENT_" env-var prefix.
 *
 * Make sure to call this function before any other imports.
 *
 * @public
 * @deprecated Use Node.js built-in proxy support by setting `NODE_USE_ENV_PROXY=1`
 * alongside your `HTTP_PROXY` / `HTTPS_PROXY` environment variables instead.
 * This function will be removed in a future release.
 * See {@link https://backstage.io/docs/tutorials/corporate-proxy/ | the corporate proxy guide} for details.
 */
declare function bootstrapEnvProxyAgents(): void;

/**
 * Callback function that can be used to receive stdout or stderr data from a child process.
 *
 * @public
 */
type RunOnOutput = (data: Buffer) => void;
/**
 * Options for running a child process with {@link run} or related functions.
 *
 * @public
 */
type RunOptions = Omit<SpawnOptions, 'env'> & {
    env?: Partial<NodeJS.ProcessEnv>;
    onStdout?: RunOnOutput;
    onStderr?: RunOnOutput;
    stdio?: SpawnOptions['stdio'];
};
/**
 * Child process handle returned by {@link run}.
 *
 * @public
 */
interface RunChildProcess extends ChildProcess {
    /**
     * Waits for the child process to exit.
     *
     * @remarks
     *
     * Resolves when the process exits successfully (exit code 0) or is terminated by a signal.
     * If the process exits with a non-zero exit code, the promise is rejected with an {@link ExitCodeError}.
     *
     * @returns A promise that resolves when the process exits successfully or is terminated by a signal, or rejects on error.
     */
    waitForExit(): Promise<void>;
}
/**
 * Runs a command and returns a child process handle.
 *
 * @public
 */
declare function run(args: string[], options?: RunOptions): RunChildProcess;
/**
 * Runs a command and returns the stdout.
 *
 * @remarks
 *
 * On error, both stdout and stderr are attached to the error object as properties.
 *
 * @public
 */
declare function runOutput(args: string[], options?: RunOptions): Promise<string>;
/**
 * Runs a command and returns true if it exits with code 0, false otherwise.
 *
 * @public
 */
declare function runCheck(args: string[]): Promise<boolean>;

/**
 * Error thrown when a child process exits with a non-zero code.
 * @public
 */
declare class ExitCodeError extends CustomErrorBase {
    /** The exit code of the child process. */
    readonly code: number;
    constructor(code: number, command?: string);
}

export { BACKSTAGE_JSON, ExitCodeError, bootstrapEnvProxyAgents, findOwnPaths, findPaths, isChildPath, run, runCheck, runOutput, targetPaths };
export type { OwnPaths, Paths, ResolveFunc, RunChildProcess, RunOnOutput, RunOptions, TargetPaths };