import { basename, delimiter, dirname, extname, isAbsolute, join, normalize, parse, relative, resolve, sep, toNamespacedPath } from 'node:path';
import type { ParsedPath } from 'node:path';
/**
 * Returns the path to the `actions` directory. The `actions` directory
 * contains the core Stacks' actions.
 *
 * @param path - The relative path to the file or directory.
 * @returns The absolute path to the file or directory.
 * @example
 * ```ts
 * import { actionsPath } from '@stacksjs/path'
 *
 * console.log(actionsPath('path/to/action.ts')) // Outputs the absolute path to 'path/to/action.ts' within the `actions` directory
 * ```
 */
export declare function actionsPath(path?: string): string;
export declare function relativeActionsPath(path?: string): string;
export declare function userActionsPath(path?: string, options?: { relative: true }): string;
export declare function builtUserActionsPath(path?: string, options?: { relative: boolean }): string;
export declare function userComponentsPath(path?: string): string;
export declare function userViewsPath(path?: string): string;
export declare function userFunctionsPath(path?: string): string;
/**
 * Pick where a user lib folder (`components` / `functions`) lives
 * (stacksjs/stacks#929). A root-level `<project>/components` (or
 * `/functions`) folder wins when it exists; otherwise the conventional
 * `resources/<name>`. Lets apps keep these at the project root without
 * losing the `resources/`-nested default.
 *
 * Pure + injectable `exists` so the selection is unit-testable without
 * touching the real filesystem.
 */
export declare function resolveUserLibBase(rootDir: string, resourcesDir: string, exists?: (p: string) => boolean): string;
/**
 * Returns the path to the user-defined `Jobs` directory.
 *
 * @param path - The relative path to the file or directory within the `Jobs` directory.
 * @returns The absolute path to the specified file or directory within the user-defined `Jobs` directory.
 * @example
 * ```ts
 * import { userJobsPath } from '@stacksjs/path'
 *
 * console.log(userJobsPath('MyJob.ts')) // Outputs the absolute path to 'MyJob.ts' within the user-defined `Jobs` directory.
 * ```
 */
export declare function userJobsPath(path?: string): string;
/**
 * Returns the path to the user-defined `Controllers` directory.
 *
 * @param path - The relative path to the file or directory within the `Controllers` directory.
 * @returns The absolute path to the specified file or directory within the user-defined `Controllers` directory.
 */
export declare function userControllersPath(path?: string): string;
/**
 * Returns the path to the user-defined `Listeners` directory.
 *
 * @param path - The relative path to the file or directory within the `Listeners` directory.
 * @returns The absolute path to the specified file or directory within the user-defined `Listeners` directory.
 * @example
 * ```ts
 * import { userListenersPath } from '@stacksjs/path'
 *
 * console.log(userListenersPath('MyListener.ts')) // Outputs the absolute path to 'MyListener.ts' within the user-defined `Listeners` directory.
 * ```
 */
export declare function userListenersPath(path?: string): string;
/**
 * Returns the path to the user-defined `Middleware` directory.
 *
 * @param path - The relative path to the file or directory within the Middleware directory.
 * @returns The absolute path to the specified file or directory within the user-defined Middleware directory.
 * @example
 * ```ts
 * import { userMiddlewarePath } from '@stacksjs/path'
 *
 * console.log(userMiddlewarePath('MyMiddleware.ts')) // Outputs the absolute path to 'MyMiddleware.ts' within the user-defined Middleware directory.
 * ```
 */
export declare function userMiddlewarePath(path?: string): string;
/**
 * Returns the path to the user-defined `Models` directory.
 *
 * @param path - The relative path to the file or directory within the `Models` directory.
 * @returns The absolute path to the specified file or directory within the user-defined `Models` directory.
 * @example
 * ```ts
 * import { userModelsPath } from '@stacksjs/path'
 *
 * console.log(userModelsPath('MyModel.ts')) // Outputs the absolute path to 'MyModel.ts' within the user-defined `Models` directory.
 * ```
 */
export declare function userModelsPath(path?: string): string;
/**
 * Returns the path to the user-defined `Notifications` directory.
 *
 * @param path - The relative path to the file or directory within the `Notifications` directory.
 * @returns The absolute path to the specified file or directory within the user-defined `Notifications` directory.
 * @example
 * ```ts
 * import { userNotificationsPath } from '@stacksjs/path'
 *
 * console.log(userNotificationsPath('MyNotification.ts')) // Outputs the absolute path to 'MyNotification.ts' within the user-defined `Notifications` directory.
 * ```
 */
export declare function userNotificationsPath(path?: string): string;
/**
 * Returns the path to the user-defined `Mail` directory.
 *
 * Mailable classes live here, one file per email type. The companion
 * stx template lives in `resources/emails/<kebab-name>.stx` and is
 * resolved by `@stacksjs/email`'s template loader at send time.
 *
 * @param path - The relative path to the file or directory within the `Mail` directory.
 * @returns The absolute path to the specified file or directory within the user-defined `Mail` directory.
 * @example
 * ```ts
 * import { userMailPath } from '@stacksjs/path'
 *
 * console.log(userMailPath('Welcome.ts')) // Outputs the absolute path to 'Welcome.ts' within the user-defined `Mail` directory.
 * ```
 */
export declare function userMailPath(path?: string): string;
/**
 * Returns the path to the user-defined `resources/emails` directory
 * where stx email templates live. The make:mail scaffolder writes a
 * companion stx file alongside each Mailable class.
 */
export declare function userEmailsPath(path?: string): string;
export declare function userDatabasePath(path?: string): string;
export declare function userMigrationsPath(path?: string): string;
/**
 * Returns the path to the user-defined `Events.ts` file.
 *
 * @returns The absolute path to the `Events.ts` file within the user-defined directory.
 * @example
 * ```ts
 * import { userEventsPath } from '@stacksjs/path'
 *
 * console.log(userEventsPath()) // Outputs the absolute path to 'Events.ts' within the user-defined directory.
 * ```
 */
export declare function userEventsPath(): string;
/**
 * Returns the path to the `ai` directory. The AI directory
 * contains the core Stacks' AI logic which currently
 * is a wrapper of the OpenAI API.
 *
 * @param path - relative path to the file or directory
 * @returns string - absolute path to the file or directory
 *
 * @example
 * ```ts
 * import { aiPath } from '@stacksjs/path'
 *
 * console.log(aiPath('src/drivers/example.ts')) // Outputs the absolute path to 'openai.ts' within the AI directory
 * ```
 */
export declare function aiPath(path?: string): string;
/**
 * Returns the path to the `assets` directory within the `resources` directory.
 *
 * @param path - The relative path to the file or directory within the `assets` directory.
 * @returns The absolute path to the specified file or directory within the `assets` directory.
 * @example
 * ```ts
 * import { assetsPath } from '@stacksjs/path'
 *
 * console.log(assetsPath('images/logo.png')) // Outputs the absolute path to 'images/logo.png' within the `assets` directory.
 * ```
 */
export declare function assetsPath(path?: string): string;
/**
 * Returns the path to the `alias` directory within the core directory.
 *
 * @returns The absolute path to the `alias` directory.
 * @example
 * ```ts
 * import { aliasPath } from '@stacksjs/path'
 *
 * console.log(aliasPath()) // Outputs the absolute path to the `alias` directory.
 * ```
 */
export declare function aliasPath(): string;
/**
 * Returns the path to the `buddy` directory, optionally relative to the current working directory.
 *
 * @param path - The relative path to the file or directory within the buddy directory.
 * @param options - Optional. An object containing configuration settings.
 * @param options.relative - If true, returns the path relative to the current working directory.
 * @returns The absolute or relative path to the specified file or directory within the buddy  * @returns The absolute or relative path to the specified file or directory within the buddy directory.
 * @example
 * ```ts
 * import { buddyPath } from '@stacksjs/path'
 *
 * console.log(buddyPath('config/buddy.json')) // Outputs the absolute path to 'config/buddy.json' within the buddy directory.
 * console.log(buddyPath('config/buddy.json', { relative: true })) // Outputs the relative path to 'config/buddy.json' within the buddy directory.
 * ```
 */
export declare function buddyPath(path?: string, options?: { relative?: boolean }): string;
/**
 * Returns the path to the `runtime` directory within the framework directory.
 *
 * @param path - The relative path to the file or directory within the runtime directory.
 * @returns The absolute path to the specified file or directory within the runtime directory.
 * @example
 * ```ts
 * import { runtimePath } from '@stacksjs/path'
 *
 * console.log(runtimePath('runtime-config.json')) // Outputs the absolute path to 'runtime-config.json' within the runtime directory.
 * ```
 */
export declare function runtimePath(path?: string): string;
/**
 * Returns the path to the `analytics` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the `analytics` directory.
 * @returns The absolute path to the specified file or directory within the `analytics` directory.
 * @example
 * ```ts
 * import { analyticsPath } from '@stacksjs/path'
 *
 * console.log(analyticsPath('data/report.csv')) // Outputs the absolute path to 'data/report.csv' within the `analytics` directory.
 * ```
 */
export declare function analyticsPath(path?: string): string;
/**
 * Returns the path to the `arrays` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the `arrays` directory.
 * @returns The absolute path to the specified file or directory within the `arrays` directory.
 * @example
 * ```ts
 * import { arraysPath } from '@stacksjs/path'
 *
 * console.log(arraysPath('list.txt')) // Outputs the absolute path to 'list.txt' within the `arrays` directory.
 * ```
 */
export declare function arraysPath(path?: string): string;
/**
 * Returns the path to the `app` directory, optionally relative to the project directory.
 *
 * @param path - The relative path to the file or directory within the app directory.
 * @returns The absolute path to the specified file or directory within the app directory.
 * @example
 * ```ts
 * import { appPath } from '@stacksjs/path'
 *
 * console.log(appPath('Actions/DummyAction.ts')) // Outputs the absolute path to 'Actions/DummyAction.ts' within the app directory.
 * ```
 */
export declare function appPath(path?: string, options?: { relative?: boolean, cwd?: string }): string;
/**
 * Returns the path to the defaults `app` directory within the framework directory.
 * This is where default Actions, Controllers, etc. are stored.
 *
 * @param path - The relative path to the file or directory within the defaults app directory.
 * @returns The absolute path to the specified file or directory within the defaults app directory.
 */
export declare function defaultsAppPath(path?: string): string;
/**
 * Returns the path to the defaults `resources` directory within the framework directory.
 * This is where default views, components, layouts, etc. are stored.
 *
 * @param path - The relative path to the file or directory within the defaults resources directory.
 * @returns The absolute path to the specified file or directory within the defaults resources directory.
 */
export declare function defaultsResourcesPath(path?: string): string;
/**
 * Returns the path to the `auth` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the auth directory.
 * @returns The absolute path to the specified file or directory within the auth directory.
 * @example
 * ```ts
 * import { authPath } from '@stacksjs/path'
 *
 * console.log(authPath('login.ts')) // Outputs the absolute path to 'login.ts' within the auth directory.
 * ```
 */
export declare function authPath(path?: string): string;
/**
 * Returns the path to the `auth` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the auth directory.
 * @returns The absolute path to the specified file or directory within the auth directory.
 * @example
 * ```ts
 * import { coreApiPath } from '@stacksjs/path'
 *
 * console.log(coreApiPath('login.ts')) // Outputs the absolute path to 'login.ts' within the auth directory.
 * ```
 */
export declare function coreApiPath(path?: string): string;
/**
 * Returns the path to the build directory. The build directory
 * contains Stacks' build engine & its tooling integrations.
 *
 * @param path string - relative path to the file or directory
 * @returns string - absolute path to the file or directory
 * @example
 * ```ts
 * buildPath('functions.stx')
 * buildPath('components.ts')
 * ```
 */
export declare function buildPath(path?: string): string;
/**
 * Returns the path to the build engine directory.
 *
 * @param path - The relative path to the file or directory within the build engine directory.
 * @returns The absolute path to the specified file or directory within the build engine directory.
 */
export declare function buildEnginePath(path?: string): string;
/**
 * Returns the path to the `libs` directory within the framework directory.
 *
 * @param path - The relative path to the file or directory within the `libs` directory.
 * @returns The absolute path to the specified file or directory within the `libs` directory.
 */
export declare function libsPath(path?: string): string;
/**
 * Returns the path to the user `libs` directory within the root project directory.
 *
 * @param path - The relative path to the file or directory within the `libs` directory.
 * @returns The absolute path to the specified file or directory within the `libs` directory.
 */
export declare function userLibsPath(path?: 'components' | 'functions' | string): string;
/**
 * Returns the path to the `entries` directory within the `libs` directory.
 *
 * @param path - The relative path to the file or directory within the `entries` directory.
 * @returns The absolute path to the specified file or directory within the `entries` directory.
 */
export declare function libsEntriesPath(path?: string): string;
/**
 * Returns the path to the `cache` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the cache directory.
 * @returns The absolute path to the specified file or directory within the cache directory.
 */
export declare function cachePath(path?: string): string;
/**
 * Returns the path to the `chat` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the chat directory.
 * @returns The absolute path to the specified file or directory within the chat directory.
 */
export declare function chatPath(path?: string): string;
/**
 * Returns the path to the `charts` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the charts directory.
 * @returns The absolute path to the specified file or directory within the charts directory.
 */
export declare function chartsPath(path?: string): string;
/**
 * Returns the path to the `cli` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the cli directory.
 * @returns The absolute path to the specified file or directory within the cli directory.
 */
export declare function cliPath(path?: string): string;
/**
 * Returns the path to the `cloud` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the cloud directory.
 * @returns The absolute path to the specified file or directory within the cloud directory.
 */
export declare function cloudPath(path?: string): string;
/**
 * Returns the path to the `cloud` directory within the framework directory.
 *
 * @param path - The relative path to the file or directory within the framework cloud directory.
 * @returns The absolute path to the specified file or directory within the framework cloud directory.
 */
export declare function frameworkCloudPath(path?: string): string;
/**
 * Returns the path to the `collections` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the `collections` directory.
 * @returns The absolute path to the specified file or directory within the `collections` directory.
 */
export declare function collectionsPath(path?: string): string;
/**
 * Returns the path to the `Commands` directory within the app directory.
 *
 * @param path - The relative path to the file or directory within the `Commands` directory.
 * @returns The absolute path to the specified file or directory within the `Commands` directory.
 */
export declare function commandsPath(path?: string): string;
/**
 * Returns the path to the `components` directory within the `resources` directory.
 *
 * @param path - The relative path to the file or directory within the `components` directory.
 * @returns The absolute path to the specified file or directory within the `components` directory.
 */
export declare function componentsPath(path?: string): string;
/**
 * Returns the path to the `config` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the config directory.
 * @returns The absolute path to the specified file or directory within the config directory.
 */
export declare function configPath(path?: string): string;
/**
 * Returns the path to the `core` directory within the framework directory.
 *
 * @param path - The relative path to the file or directory within the core directory.
 * @returns The absolute path to the specified file or directory within the core directory.
 */
export declare function corePath(path?: string): string;
/**
 * Returns the absolute path to the `custom-elements.json` file within the core directory.
 *
 * @returns The absolute path to the `custom-elements.json` file.
 */
export declare function customElementsDataPath(): string;
/**
 * Returns the path to the `database` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the database directory.
 * @returns The absolute path to the specified file or directory within the database directory.
 */
export declare function databasePath(path?: string): string;
/**
 * Returns the path to the `datetime` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the datetime directory.
 * @returns The absolute path to the specified file or directory within the datetime directory.
 */
export declare function datetimePath(path?: string): string;
/**
 * Returns the path to the `development` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the development directory.
 * @returns The absolute path to the specified file or directory within the development directory.
 */
export declare function developmentPath(path?: string): string;
/**
 * Returns the path to the `desktop` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the desktop directory.
 * @returns The absolute path to the specified file or directory within the desktop directory.
 */
export declare function desktopPath(path?: string): string;
/**
 * Returns the path to the `docs` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the `docs` directory.
 * @returns The absolute path to the specified file or directory within the `docs` directory.
 */
export declare function docsPath(path?: string): string;
/**
 * Returns the path to the `domains` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the `domains` directory.
 * @returns The absolute path to the specified file or directory within the `domains` directory.
 */
export declare function dnsPath(path?: string): string;
/**
 * Returns the path to the `email` directory within the `notifications` directory.
 *
 * @param path - The relative path to the file or directory within the email directory.
 * @returns The absolute path to the specified file or directory within the email directory.
 */
export declare function emailPath(path?: string): string;
/**
 * Returns the path to the `enums` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the `enums` directory.
 * @returns The absolute path to the specified file or directory within the `enums` directory.
 */
export declare function enumsPath(path?: string): string;
/**
 * Returns the path to the `eslint-plugin` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the eslint-plugin directory.
 * @returns The absolute path to the specified file or directory within the eslint-plugin directory.
 */
export declare function eslintPluginPath(path?: string): string;
/**
 * Returns the path to the `error-handling` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the error-handling directory.
 * @returns The absolute path to the specified file or directory within the error-handling directory.
 */
export declare function errorHandlingPath(path?: string): string;
/**
 * Returns the path to the `events` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the `events` directory.
 * @returns The absolute path to the specified file or directory within the `events` directory.
 */
export declare function eventsPath(path?: string): string;
/** Returns the path to the feature-flags core package. */
export declare function featureFlagsPath(path?: string): string;
/**
 * Returns the path to the `env` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the env directory.
 * @returns The absolute path to the specified file or directory within the env directory.
 */
export declare function coreEnvPath(path?: string): string;
/**
 * Returns the path to the `examples` directory within the framework directory, filtered by type.
 *
 * @param type - The type of examples to filter by ('web-components').
 * @returns The absolute path to the specified type of examples within the `examples` directory.
 */
export declare function examplesPath(type?: 'web-components'): string;
/**
 * Returns the path to the `faker` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the faker directory.
 * @returns The absolute path to the specified file or directory within the faker directory.
 */
export declare function fakerPath(path?: string): string;
/**
 * Returns the path to the framework directory, optionally relative to the current working directory.
 *
 * @param path - The relative path to the file or directory within the framework directory.
 * @param options - Optional. An object containing configuration settings.
 * @param options.relative - If true, returns the path relative to the current working directory.
 * @param options.cwd - Specifies a custom working directory.
 * @returns The absolute or relative path to the specified file or directory within the framework directory.
 */
export declare function frameworkPath(path?: string, options?: { relative?: boolean, cwd?: string }): string;
/**
 * Returns the path to the `frontend` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the health directory.
 * @returns The absolute path to the specified file or directory within the health directory.
 */
export declare function browserPath(path?: string): string;
/**
 * Returns the path to the `health` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the health directory.
 * @returns The absolute path to the specified file or directory within the health directory.
 */
export declare function healthPath(path?: string): string;
/**
 * Returns the path to the `functions` directory within the `resources` directory.
 *
 * @param path - The relative path to the file or directory within the `functions` directory.
 * @returns The absolute path to the specified file or directory within the `functions` directory.
 */
export declare function functionsPath(path?: string): string;
/**
 * Returns the path to the `git` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the git directory.
 * @returns The absolute path to the specified file or directory within the git directory.
 */
export declare function gitPath(path?: string): string;
/**
 * Returns the path to the `lang` directory, optionally relative to the project directory.
 *
 * @param path - The relative path to the file or directory within the lang directory.
 * @returns The absolute path to the specified file or directory within the lang directory.
 */
export declare function langPath(path?: string): string;
/**
 * Returns the path to the `layouts` directory within the `resources` directory, optionally relative to the current working directory.
 *
 * @param path - The relative path to the file or directory within the `layouts` directory.
 * @param options - Optional. An object containing configuration settings.
 * @param options.relative - If true, returns the path relative to the current working directory.
 * @param options.defaults - If true, returns the path to the `defaults/layouts` directory.
 * @returns The absolute or relative path to the specified file or directory within the `layouts` directory.
 */
export declare function layoutsPath(path?: string, options?: { relative?: boolean, defaults?: boolean }): string;
export declare function libraryEntryPath(type: LibraryType): string;
/**
 * Returns the path to the `lint` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the lint directory.
 * @returns The absolute path to the specified file or directory within the lint directory.
 */
export declare function lintPath(path?: string): string;
/**
 * Returns the path to the `listeners` directory within the app directory.
 *
 * @param path - The relative path to the file or directory within the `listeners` directory.
 * @returns The absolute path to the specified file or directory within the `listeners` directory.
 */
export declare function listenersPath(path?: string): string;
/**
 * Returns the path to the `jobs` directory within the app directory.
 *
 * @param path - The relative path to the file or directory within the `jobs` directory.
 * @returns The absolute path to the specified file or directory within the `jobs` directory.
 */
export declare function jobsPath(path?: string): string;
/**
 * Returns the path to the `logging` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the logging directory.
 * @returns The absolute path to the specified file or directory within the logging directory.
 */
export declare function loggingPath(path?: string): string;
/**
 * Returns the path to the `logs` directory within the project storage directory.
 *
 * @param path - The relative path to the file or directory within the `logs` directory.
 * @returns The absolute path to the specified file or directory within the `logs` directory.
 */
export declare function logsPath(path?: string): string;
/**
 * Returns the path to the `models` directory within the app directory.
 *
 * @param path - The relative path to the file or directory within the `models` directory.
 * @returns The absolute path to the specified file or directory within the `models` directory.
 */
export declare function modelsPath(path?: string): string;
/**
 * Returns the path to the `modules` directory within the `resources` directory.
 *
 * @param path - The relative path to the file or directory within the `modules` directory.
 * @returns The absolute path to the specified file or directory within the `modules` directory.
 */
export declare function modulesPath(path?: string): string;
/**
 * Returns the path to the `notifications` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the `notifications` directory.
 * @returns The absolute path to the specified file or directory within the `notifications` directory.
 */
export declare function notificationsPath(path?: string): string;
/**
 * Returns the path to the `newsletter` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the `newsletter` directory.
 * @returns The absolute path to the specified file or directory within the `newsletter` directory.
 */
export declare function newsletterPath(path?: string): string;
/**
 * Returns the path to the `orm` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the orm directory.
 * @returns The absolute path to the specified file or directory within the orm directory.
 */
export declare function ormPath(path?: string): string;
/**
 * Returns the path to the `objects` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the `objects` directory.
 * @returns The absolute path to the specified file or directory within the `objects` directory.
 */
export declare function objectsPath(path?: string): string;
/**
 * Returns the default path to the onboarding views within the project directory, or a specified path.
 *
 * @param path - The relative path to the file or directory within the project directory. Defaults to 'views/dashboard/onboarding'.
 * @returns The absolute path to the specified file or directory within the project directory.
 */
export declare function onboardingPath(path?: string): string;
/**
 * Returns the path to the `package.json` file of a specified library type within the framework directory.
 *
 * @param type - The type of the library ('web-components', or 'functions') for which to return the package.json path.
 * @returns The absolute path to the specified package.json file within the framework directory.
 */
export declare function packageJsonPath(type: LibraryType): string;
/**
 * Returns the path to the `views` directory within the `resources` directory.
 *
 * @param path - The relative path to the file or directory within the `views` directory.
 * @returns The absolute path to the specified file or directory within the `views` directory.
 */
export declare function viewsPath(path?: string): string;
/**
 * Returns the path to the `path` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the path directory.
 * @returns The absolute path to the specified file or directory within the path directory.
 */
export declare function pathPath(path?: string): string;
/**
 * Returns the path to the `payments` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the `payments` directory.
 * @returns The absolute path to the specified file or directory within the `payments` directory.
 */
export declare function paymentsPath(path?: string): string;
/**
 * Returns the project path, resolving from the current working directory and moving up until the storage directory is no longer part of the path.
 *
 * @param filePath - The relative path to append to the project path. Defaults to an empty string.
 * @returns The absolute path to the specified file or directory within the project directory.
 */
export declare function projectPath(filePath?: string, options?: { relative: boolean }): string;
/**
 * Finds and returns the absolute path of a specified project by name.
 *
 * @param project - The name of the project to find.
 * @returns The absolute path to the specified project.
 * @throws Error if the project with the specified name cannot be found.
 */
export declare function findProjectPath(project: string): Promise<string>;
/**
 * Returns the path to the `config` directory within the project directory.
 *
 * @param path - The relative path to the file or directory within the config directory.
 * @returns The absolute path to the specified file or directory within the config directory.
 */
export declare function projectConfigPath(path?: string): string;
/**
 * Returns the path to the `storage` directory within the project directory.
 *
 * @param path - The relative path to the file or directory within the storage directory.
 * @returns The absolute path to the specified file or directory within the storage directory.
 */
export declare function storagePath(path?: string): string;
/**
 * Returns the path to the `public` directory within the project directory.
 *
 * @param path - The relative path to the file or directory within the public directory.
 * @returns The absolute path to the specified file or directory within the public directory.
 */
export declare function publicPath(path?: string): string;
/** Where `buddy upgrade` reads the managed scaffold from. */
export declare function defaultsPackagePath(projectRoot?: string): string;
/** Version of the installed `@stacksjs/defaults`, or null when absent. */
export declare function installedDefaultsVersion(projectRoot?: string): string | null;
/**
 * Compare the vendored framework defaults against the installed package.
 *
 * `storage/framework/defaults` is the copy that executes, and `buddy upgrade`
 * is the only thing that writes it. Bump `stacks` in package.json and run
 * `bun install`, which is how anyone moves a dependency, and the package
 * advances while the vendored tree stays put.
 *
 * Cheap by construction: two manifest reads and one marker read, so callers on
 * a boot path can consult it freely.
 */
export declare function inspectDefaultsProvenance(projectRoot?: string): DefaultsSkew;
/**
 * Returns the path to the `push` directory within the `notifications` directory.
 *
 * @param path - The relative path to the file or directory within the push directory.
 * @returns The absolute path to the specified file or directory within the push directory.
 */
export declare function pushPath(path?: string): string;
/**
 * Returns the path to the `query-builder` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the query-builder directory.
 * @returns The absolute path to the specified file or directory within the query-builder directory.
 */
export declare function queryBuilderPath(path?: string): string;
/**
 * Returns the path to the `queue` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the queue directory.
 * @returns The absolute path to the specified file or directory within the queue directory.
 */
export declare function queuePath(path?: string): string;
/**
 * Returns the path to the `realtime` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the realtime directory.
 * @returns The absolute path to the specified file or directory within the realtime directory.
 */
export declare function realtimePath(path?: string): string;
/**
 * Returns the path to the `resources` directory within the project storage directory, with an option for relative paths.
 *
 * @param path - The relative path to the file or directory within the `resources` directory.
 * @param options - Optional. An object containing configuration settings.
 * @param options.relative - If true, returns the path relative to the current working directory.
 * @returns The absolute or relative path to the specified file or directory within the `resources` directory.
 */
export declare function resourcesPath(path?: string, options?: { relative?: boolean }): string;
/**
 * Returns the path to the `repl` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the repl directory.
 * @returns The absolute path to the specified file or directory within the repl directory.
 */
export declare function replPath(path?: string): string;
/**
 * Returns the path to the `router` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the router directory.
 * @returns The absolute path to the specified file or directory within the router directory.
 */
export declare function routerPath(path?: string): string;
/**
 * Returns the path to the `routes` directory within the `resources` directory, with an option for relative paths.
 *
 * @param path - The relative path to the file or directory within the `routes` directory.
 * @param options - Optional. An object containing configuration settings.
 * @param options.relative - If true, returns the path relative to the current working directory.
 * @returns The absolute or relative path to the specified file or directory within the `routes` directory.
 */
export declare function routesPath(path?: string, options?: { relative?: boolean }): string;
/**
 * Returns the path to the `search-engine` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the search-engine directory.
 * @returns The absolute path to the specified file or directory within the search-engine directory.
 */
export declare function searchEnginePath(path?: string): string;
/**
 * Returns the path to the `settings` directory within the project directory, defaulting to the views/dashboard/settings directory.
 *
 * @param path - The relative path to the file or directory within the `settings` directory.
 * @returns The absolute path to the specified file or directory within the `settings` directory.
 */
export declare function settingsPath(path?: string): string;
/**
 * Returns the path to the `scripts` directory within the framework directory.
 *
 * @param path - The relative path to the file or directory within the `scripts` directory.
 * @returns The absolute path to the specified file or directory within the `scripts` directory.
 */
export declare function scriptsPath(path?: string): string;
/**
 * Returns the path to the `scheduler` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the scheduler directory.
 * @returns The absolute path to the specified file or directory within the scheduler directory.
 */
export declare function schedulerPath(path?: string): string;
/**
 * Returns the path to the `skills` directory within the core directory.
 *
 * That is the `@stacksjs/skills` package. The skills it reads ship from
 * `storage/framework/defaults/ai/skills`, not from here.
 *
 * @param path - The relative path to the file or directory within the skills directory.
 * @returns The absolute path to the specified file or directory within the skills directory.
 */
export declare function skillsPath(path?: string): string;
/**
 * Returns the path to the `slug` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the slug directory.
 * @returns The absolute path to the specified file or directory within the slug directory.
 */
export declare function slugPath(path?: string): string;
/**
 * Returns the path to the `sms` directory within the `notifications` directory.
 *
 * @param path - The relative path to the file or directory within the `sms` directory.
 * @returns The absolute path to the specified file or directory within the `sms` directory.
 */
export declare function smsPath(path?: string): string;
/**
 * Returns the path to the `storage` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the storage directory.
 * @returns The absolute path to the specified file or directory within the storage directory.
 */
export declare function coreStoragePath(path?: string): string;
/**
 * Returns the path to the `stores` directory within the `resources` directory.
 *
 * @param path - The relative path to the file or directory within the `stores` directory.
 * @returns The absolute path to the specified file or directory within the `stores` directory.
 */
export declare function storesPath(path?: string): string;
/**
 * Returns the path to the `security` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the security directory.
 * @returns The absolute path to the specified file or directory within the security directory.
 */
export declare function securityPath(path?: string): string;
/**
 * Returns the path to the `server` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the server directory.
 * @returns The absolute path to the specified file or directory within the server directory.
 */
export declare function serverPath(path?: string): string;
export declare function userServerPath(path?: string): string;
/**
 * Returns the path to the `serverless` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the `serverless` directory.
 * @returns The absolute path to the specified file or directory within the `serverless` directory.
 */
export declare function serverlessPath(path?: string): string;
/**
 * Returns the path to the specified directory or file within the framework's `src` directory.
 *
 * @param path - The relative path to the file or directory within the framework's `src` directory.
 * @returns The absolute path to the specified file or directory within the framework's `src` directory.
 */
export declare function stacksPath(path?: string): string;
export declare function stacksLockPath(): string;
export declare function stacksBackupPath(stackName?: string): string;
/**
 * Returns the path to the `shell` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the shell directory.
 * @returns The absolute path to the specified file or directory within the shell directory.
 */
export declare function shellPath(path?: string): string;
/**
 * Returns the path to the `strings` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the `strings` directory.
 * @returns The absolute path to the specified file or directory within the `strings` directory.
 */
export declare function stringsPath(path?: string): string;
/**
 * Returns the path to the `testing` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the testing directory.
 * @returns The absolute path to the specified file or directory within the testing directory.
 */
export declare function testingPath(path?: string): string;
/**
 * Returns the path to the `tinker` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the tinker directory.
 * @returns The absolute path to the specified file or directory within the tinker directory.
 */
export declare function tinkerPath(path?: string): string;
/**
 * Returns the path to the `tests` directory within the framework directory.
 *
 * @param path - The relative path to the file or directory within the `tests` directory.
 * @returns The absolute path to the specified file or directory within the `tests` directory.
 */
export declare function testsPath(path?: string): string;
/**
 * Returns the path to the `types` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the `types` directory.
 * @returns The absolute path to the specified file or directory within the `types` directory.
 */
export declare function typesPath(path?: string): string;
/**
 * Returns the path to the `ui` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the ui directory.
 * @returns The absolute path to the specified file or directory within the ui directory.
 */
export declare function uiPath(path?: string, options?: { relative?: boolean }): string;
/**
 * Returns the path to the `utils` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the `utils` directory.
 * @returns The absolute path to the specified file or directory within the `utils` directory.
 */
export declare function utilsPath(path?: string): string;
/**
 * Returns the path to the `validation` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the validation directory.
 * @returns The absolute path to the specified file or directory within the validation directory.
 */
export declare function validationPath(path?: string): string;
/**
 * Returns the path to the framework's runtime scratch directory.
 *
 * This is where the framework keeps short-lived, machine-local state that is
 * neither source nor build output: the `buddy migrate` lockfile, the marker a
 * migration subprocess writes back to the CLI, temporary bundles, and similar.
 * Nothing in here is committed, and deleting the whole directory is always safe.
 *
 * It used to live at `./.stacks` in the project root. Everything runtime-owned
 * now sits under `storage/` so the root only holds files you author.
 *
 * @param path - The relative path to the file or directory within the runtime directory.
 * @returns The absolute path to the specified file or directory.
 * @example
 * ```ts
 * import { frameworkRuntimePath } from '@stacksjs/path'
 *
 * console.log(frameworkRuntimePath('migrations.lock'))
 * ```
 */
export declare function frameworkRuntimePath(path?: string): string;
/**
 * Returns the path to stx's build cache and generated route manifest.
 *
 * stx writes its compiled-template cache, Crosswind CSS cache, client-script
 * bundles and `routes.ts` manifest here. It used to be `./.stx` in the project
 * root; stx now takes the location from its own `stateDir` config option, which
 * `config/ui.ts` sets to this directory and {@link runtimeDirectoryEnv} exports
 * as `STX_DIR` for every process the project starts.
 *
 * @param path - The relative path to the file or directory within the stx cache.
 * @returns The absolute path to the specified file or directory.
 */
export declare function stxPath(path?: string): string;
/**
 * Returns the path to the local cloud state directory.
 *
 * ts-cloud persists per-environment driver state, cached templates, and the
 * management dashboard's credentials here. These are machine-local secrets and
 * caches, never committed. It used to be `./.ts-cloud` in the project root;
 * ts-cloud now takes the location from its own `stateDir` config option, which
 * `config/cloud.ts` sets to this directory and {@link runtimeDirectoryEnv}
 * exports as `TS_CLOUD_STATE_DIR` for every process the project starts.
 *
 * Not to be confused with {@link cloudPath}, which points at the committed
 * `cloud/` infrastructure-as-code directory.
 *
 * @param path - The relative path to the file or directory within the cloud state directory.
 * @returns The absolute path to the specified file or directory.
 */
export declare function cloudStatePath(path?: string): string;
/**
 * The environment stx and ts-cloud need in order to find their state.
 *
 * Both take the directory from their own config (`config/ui.ts` sets stx's
 * `stateDir`, `config/cloud.ts` sets ts-cloud's), but a config is only read
 * once something loads it, and both libraries reach for their state from module
 * scope and from helpers that never see a config object. Their documented
 * override is an environment variable, which is also what carries the answer
 * into every process a command spawns. Absolute, so a code path resolving
 * against a subdirectory still lands in the same place.
 */
export declare function runtimeDirectoryEnv(): Record<string, string>;
/**
 * Applies {@link runtimeDirectoryEnv} to `process.env`.
 *
 * An explicitly set value wins: someone who exports `STX_DIR` before running a
 * command means it.
 */
export declare function applyRuntimeDirectoryEnv(): void;
/**
 * Recursively merges `from` into `to`, keeping whatever is already at `to`.
 *
 * The recursion matters: a shallow "rename each top-level entry unless it
 * exists" pass would delete an entire subtree just because a sibling file
 * inside it happened to be present at the destination. Directories present on
 * both sides are merged entry by entry; only files that already exist at the
 * destination are dropped from the source.
 */
export declare function mergeDirectoryInto(from: string, to: string): void;
/**
 * Creates the framework's runtime directories under `storage/` and clears the
 * legacy root-level entries.
 *
 * For each relocated directory this:
 *
 *  1. creates the target under `storage/` if it does not exist yet,
 *  2. recursively merges a pre-existing real directory in the project root into
 *     it (anything already at the target wins, so re-running is safe),
 *  3. removes what is left in the root - including the symlink earlier versions
 *     put there, now that stx and ts-cloud are configured to read the target
 *     directly.
 *
 * A symlink pointing anywhere other than the target is left alone: it is not
 * ours to remove (an old checkout's `.stacks` may still be the core-source
 * shortcut that `buddy generate:core-symlink` now writes to `.framework`).
 *
 * Every step is best-effort - this must never throw or block a command.
 *
 * @returns What is now in place for each relocated directory.
 */
export declare function ensureRuntimeDirectories(): RuntimeDirectoryState[];
/**
 * Returns the path to the `validation` directory within the core directory.
 *
 * @param path - The relative path to the file or directory within the validation directory.
 * @returns The absolute path to the specified file or directory within the validation directory.
 */
export declare function socialsPath(path?: string): string;
/**
 * Returns the path to the home directory, optionally appending a given path.
 *
 * @param path - The relative path to append to the home directory path.
 * @returns The absolute path to the specified file or directory within the home directory.
 */
export declare function homeDir(path?: string): string;
/**
 * Provenance stamp written next to the synced tree. `buddy upgrade` is the only
 * thing that writes `storage/framework/defaults`, so this is the only record of
 * which release the tree came from.
 */
export declare const DEFAULTS_SYNC_MARKER: '.stacks-sync.json';
export declare const path: Path;
export declare interface DefaultsSyncMarker {
  version: string
  syncedAt: string
}
export declare interface DefaultsSkew {
  status: DefaultsProvenance
  installed: string | null
  vendored: string | null
  syncedAt: string | null
}
/**
 * The outcome of relocating one runtime directory.
 *
 * `cleared` says whether the old root-level entry is gone. It stays false only
 * when something we should not touch is sitting there - a symlink someone else
 * created, or an entry we could not remove.
 */
export declare interface RuntimeDirectoryState {
  legacy: string
  target: string
  cleared: boolean
}
export declare interface Path {
  actionsPath: (path?: string) => string
  userActionsPath: (path?: string) => string
  builtUserActionsPath: (path?: string, option?: { relative: boolean }) => string
  userComponentsPath: (path?: string) => string
  userViewsPath: (path?: string) => string
  userFunctionsPath: (path?: string) => string
  aiPath: (path?: string) => string
  assetsPath: (path?: string) => string
  relativeActionsPath: (path?: string) => string
  aliasPath: (path?: string) => string
  analyticsPath: (path?: string) => string
  arraysPath: (path?: string) => string
  appPath: (path?: string) => string
  defaultsAppPath: (path?: string) => string
  defaultsResourcesPath: (path?: string) => string
  authPath: (path?: string) => string
  coreApiPath: (path?: string) => string
  buddyPath: (path?: string) => string
  buildEnginePath: (path?: string) => string
  libsEntriesPath: (path?: string) => string
  buildPath: (path?: string) => string
  cachePath: (path?: string) => string
  chartsPath: (path?: string) => string
  chatPath: (path?: string) => string
  cliPath: (path?: string) => string
  cloudPath: (path?: string) => string
  cloudStatePath: (path?: string) => string
  frameworkCloudPath: (path?: string) => string
  frameworkRuntimePath: (path?: string) => string
  stxPath: (path?: string) => string
  ensureRuntimeDirectories: () => RuntimeDirectoryState[]
  runtimeDirectoryEnv: () => Record<string, string>
  applyRuntimeDirectoryEnv: () => void
  collectionsPath: (path?: string) => string
  commandsPath: (path?: string) => string
  componentsPath: (path?: string) => string
  configPath: (path?: string) => string
  projectConfigPath: (path?: string) => string
  corePath: (path?: string) => string
  customElementsDataPath: (path?: string) => string
  databasePath: (path?: string) => string
  datetimePath: (path?: string) => string
  developmentPath: (path?: string) => string
  desktopPath: (path?: string) => string
  docsPath: (path?: string) => string
  dnsPath: (path?: string) => string
  emailPath: (path?: string) => string
  enumsPath: (path?: string) => string
  eslintPluginPath: (path?: string) => string
  errorHandlingPath: (path?: string) => string
  eventsPath: (path?: string) => string
  featureFlagsPath: (path?: string) => string
  coreEnvPath: (path?: string) => string
  healthPath: (path?: string) => string
  examplesPath: (type?: 'web-components') => string
  fakerPath: (path?: string) => string
  frameworkPath: (path?: string) => string
  browserPath: (path?: string) => string
  storagePath: (path?: string) => string
  functionsPath: (path?: string) => string
  gitPath: (path?: string) => string
  langPath: (path?: string) => string
  layoutsPath: (path?: string, options?: { relative?: boolean }) => string
  libsPath: (path?: string) => string
  userLibsPath: (path?: string) => string
  libraryEntryPath: (type: LibraryType) => string
  lintPath: (path?: string) => string
  listenersPath: (path?: string) => string
  loggingPath: (path?: string) => string
  logsPath: (path?: string) => string
  jobsPath: (path?: string) => string
  modulesPath: (path?: string) => string
  ormPath: (path?: string) => string
  objectsPath: (path?: string) => string
  onboardingPath: (path?: string) => string
  notificationsPath: (path?: string) => string
  newsletterPath: (path?: string) => string
  packageJsonPath: (type: LibraryType) => string
  viewsPath: (path?: string) => string
  pathPath: (path?: string) => string
  paymentsPath: (path?: string) => string
  projectPath: (path?: string) => string
  findProjectPath: (project: string) => Promise<string>
  coreStoragePath: (path?: string) => string
  publicPath: (path?: string) => string
  defaultsPackagePath: (projectRoot?: string) => string
  installedDefaultsVersion: (projectRoot?: string) => string | null
  inspectDefaultsProvenance: (projectRoot?: string) => DefaultsSkew
  pushPath: (path?: string) => string
  queryBuilderPath: (path?: string) => string
  queuePath: (path?: string) => string
  realtimePath: (path?: string) => string
  resourcesPath: (path?: string) => string
  replPath: (path?: string) => string
  routerPath: (path?: string) => string
  routesPath: (path?: string) => string
  runtimePath: (path?: string) => string
  searchEnginePath: (path?: string) => string
  schedulerPath: (path?: string) => string
  settingsPath: (path?: string) => string
  smsPath: (path?: string) => string
  skillsPath: (path?: string) => string
  slugPath: (path?: string) => string
  scriptsPath: (path?: string) => string
  securityPath: (path?: string) => string
  serverPath: (path?: string) => string
  userServerPath: (path?: string) => string
  serverlessPath: (path?: string) => string
  stacksPath: (path?: string) => string
  stacksLockPath: () => string
  stacksBackupPath: (stackName?: string) => string
  stringsPath: (path?: string) => string
  shellPath: (path?: string) => string
  storesPath: (path?: string) => string
  socialsPath: (path?: string) => string
  testingPath: (path?: string) => string
  testsPath: (path?: string) => string
  tinkerPath: (path?: string) => string
  typesPath: (path?: string) => string
  uiPath: (path?: string, options?: { relative?: boolean }) => string
  userDatabasePath: (path?: string) => string
  userMigrationsPath: (path?: string) => string
  userEventsPath: (path?: string) => string
  userJobsPath: (path?: string) => string
  userControllersPath: (path?: string) => string
  userListenersPath: (path?: string) => string
  userMiddlewarePath: (path?: string) => string
  userModelsPath: (path?: string) => string
  userNotificationsPath: (path?: string) => string
  userMailPath: (path?: string) => string
  userEmailsPath: (path?: string) => string
  utilsPath: (path?: string) => string
  validationPath: (path?: string) => string
  homeDir: (path?: string) => string
  basename: (path: string) => string
  delimiter: () => ';' | ':'
  dirname: (path: string) => string
  extname: (path: string) => string
  isAbsolute: (path: string) => boolean
  join: (...paths: string[]) => string
  normalize: (path: string) => string
  relative: (from: string, to: string) => string
  resolve: (...paths: string[]) => string
  parse: (path: string) => ParsedPath
  sep: () => '/' | '\\'
  toNamespacedPath: (path: string) => string
}
/**
 * Returns the path to the library entry file, filtered by library type.
 *
 * @param type - The type of library ('web-components', or 'functions').
 * @returns The absolute path to the specified library entry file.
 */
export type LibraryType = 'web-components' | 'functions';
/**
 * - `not-applicable` — nothing to compare: no vendored tree, no installed
 *   package, or a framework checkout where the tree is the source rather than a
 *   copy of it.
 * - `unstamped` — the tree predates provenance stamping, so only a file
 *   comparison can say whether it is current.
 */
export type DefaultsProvenance = 'not-applicable' | 'current' | 'stale' | 'unstamped';
export { basename, delimiter, dirname, extname, isAbsolute, join, normalize, relative, resolve, sep, toNamespacedPath };