/**
 * Dev workflow helpers for setup, reset, and database management.
 *
 * Composable functions that consumer projects (tx, visiones, etc.) use in their
 * `scripts/dev_setup.ts`, `scripts/dev_reset.ts`, etc. All functions accept narrow
 * `*Deps` interfaces from `runtime/deps.ts` — pass a `RuntimeDeps` instance
 * created by `create_deno_runtime()`.
 *
 * @module
 */
import type { CommandDeps, CommandResult, EnvDeps, FsReadDeps, FsRemoveDeps, FsWriteDeps } from '../runtime/deps.js';
import type { QueryDeps } from '../db/query_deps.js';
/**
 * Optional logger for setup helpers.
 *
 * Functions that accept a logger use it for status messages.
 * When omitted, a default bracket-format logger writes to console.
 */
export interface SetupLogger {
    ok: (msg: string) => void;
    skip: (msg: string) => void;
    error: (msg: string) => void;
}
/** Default logger using bracket format. */
export declare const default_setup_logger: SetupLogger;
/** Result of `setup_env_file`. */
export interface SetupEnvResult {
    /** Whether a new file was created (vs updating existing). */
    created: boolean;
    /** Whether any values were generated/replaced. */
    updated: boolean;
    /** The env file path. */
    path: string;
}
/** Result of `setup_bootstrap_token`. */
export interface SetupTokenResult {
    /** Whether a new token was created (false if already existed). */
    created: boolean;
    /** The token file path. */
    token_path: string;
}
/** Result of `reset_database`. */
export interface ResetDbResult {
    /** Whether the database was actually reset. */
    reset: boolean;
    /** Whether the operation was skipped (e.g. pglite with no data dir). */
    skipped: boolean;
    /** What type of database was detected. */
    db_type: 'postgres' | 'pglite' | 'none';
}
/** Options for `setup_env_file`. */
export interface SetupEnvOptions {
    /**
     * Extra env var replacements beyond the default `SECRET_FUZ_COOKIE_KEYS`.
     *
     * Keys are env var names, values are async generators.
     * Replaces `^KEY=$` (empty value) patterns in the env file.
     */
    replacements?: Record<string, () => Promise<string>>;
    /** Optional callback to set file permissions (e.g. `Deno.chmod`). */
    set_permissions?: (path: string, mode: number) => Promise<void>;
    log?: SetupLogger;
}
/** Options for `setup_bootstrap_token`. */
export interface SetupBootstrapTokenOptions {
    /** State directory override. Defaults to `~/.{app_name}`. */
    state_dir?: string;
    /** Optional callback to set file/directory permissions. */
    set_permissions?: (path: string, mode: number) => Promise<void>;
    log?: SetupLogger;
}
/** Options for `create_database`. */
export interface CreateDatabaseOptions {
    log?: SetupLogger;
}
/** Options for `reset_database`. */
export interface ResetDatabaseOptions {
    /** Directory to remove for file-based pglite. */
    pglite_data_dir?: string;
    log?: SetupLogger;
}
/**
 * Extract the database name from a PostgreSQL URL.
 *
 * @returns the database name, or `null` if the URL is invalid or has no path
 */
export declare const parse_db_name: (url: string) => string | null;
/**
 * Generate a random base64 key using openssl.
 *
 * @param deps - command execution capability
 * @returns a random 32-byte base64-encoded key
 * @throws Error if `openssl rand` fails or is unavailable
 */
export declare const generate_random_key: (deps: CommandDeps) => Promise<string>;
/**
 * Read a single env var from a dotenv-style file.
 *
 * @param deps - file read capability
 * @param env_path - path to the .env file
 * @param name - the variable name to read
 * @returns the value, or `undefined` if the file or variable doesn't exist
 */
export declare const read_env_var: (deps: Pick<FsReadDeps, "stat" | "read_text_file">, env_path: string, name: string) => Promise<string | undefined>;
/**
 * Create an env file from its example template, auto-generating `SECRET_FUZ_COOKIE_KEYS`.
 *
 * If the file already exists, backfills any empty values that have generators.
 * Idempotent — safe to re-run.
 *
 * @param deps - file read, write, and command capabilities
 * @param env_path - path for the env file (e.g. `.env.development`)
 * @param example_path - path to the example template
 * @param options - extra replacements, permissions, logger
 * @returns result indicating whether the file was created or updated
 * @mutates filesystem - writes `env_path` (creating from `example_path` if missing) and optionally chmods to `0o600`
 */
export declare const setup_env_file: (deps: FsReadDeps & FsWriteDeps & CommandDeps, env_path: string, example_path: string, options?: SetupEnvOptions) => Promise<SetupEnvResult>;
/**
 * Create a bootstrap token file if it doesn't exist.
 *
 * The token is a one-shot secret used to create the first admin account.
 * Stored at `~/.{app_name}/secret_bootstrap_token` by default.
 *
 * @param deps - file, command, and env capabilities
 * @param app_name - application name (used for default state directory)
 * @param options - state_dir override, permissions, logger
 * @returns result indicating whether a token was created
 * @mutates filesystem - creates state directory and writes the token file (optionally chmods to `0o700` / `0o600`)
 */
export declare const setup_bootstrap_token: (deps: FsReadDeps & FsWriteDeps & CommandDeps & EnvDeps, app_name: string, options?: SetupBootstrapTokenOptions) => Promise<SetupTokenResult>;
/**
 * Remove an existing bootstrap token and create a new one.
 *
 * @param deps - file, command, env, and remove capabilities
 * @param app_name - application name
 * @param options - state_dir override, permissions, logger
 * @returns result from creating the new token
 * @mutates filesystem - removes the existing token file (if any) then writes a fresh one
 */
export declare const reset_bootstrap_token: (deps: FsReadDeps & FsWriteDeps & FsRemoveDeps & CommandDeps & EnvDeps, app_name: string, options?: SetupBootstrapTokenOptions) => Promise<SetupTokenResult>;
/**
 * Create a PostgreSQL database if `createdb` is available.
 *
 * Does not throw — returns the underlying command result so callers can
 * decide how to react to a missing `createdb` or an "already exists" failure.
 *
 * @param deps - command execution capability
 * @param db_name - database name to create
 * @param options - logger
 * @returns the command result
 * @mutates external database - invokes `createdb` to create `db_name` when available
 */
export declare const create_database: (deps: CommandDeps, db_name: string, options?: CreateDatabaseOptions) => Promise<CommandResult>;
/**
 * Reset a database to a clean slate.
 *
 * For PostgreSQL: drops and recreates the database.
 * For pglite: removes the data directory if `pglite_data_dir` is provided.
 * For empty/missing URLs: skips.
 *
 * @param deps - command and file capabilities
 * @param database_url - the `DATABASE_URL` value
 * @param options - `pglite_data_dir`, logger
 * @returns result describing what happened
 * @mutates external database - drops and recreates the PostgreSQL database, or removes the PGlite data directory
 * @mutates filesystem - removes `options.pglite_data_dir` recursively for PGlite URLs
 */
export declare const reset_database: (deps: CommandDeps & FsReadDeps & FsRemoveDeps, database_url: string, options?: ResetDatabaseOptions) => Promise<ResetDbResult>;
/** Input to `seed_dev_account`. */
export interface SeedDevAccountInput {
    /** Account username. Policy is bypassed — any non-empty string is accepted. */
    username: string;
    /** Account password. Policy is bypassed — any non-empty string is accepted. */
    password: string;
    /** Roles to grant via role_grant (idempotent). */
    roles?: ReadonlyArray<string>;
}
/** Result of `seed_dev_account`. */
export interface SeedDevAccountResult {
    account_id: string;
    actor_id: string;
    /** True if a new account was created; false if one already existed. */
    created: boolean;
}
/** Dependencies for `seed_dev_account`. */
export interface SeedDevAccountDeps extends QueryDeps {
    /** Password hasher (e.g., `argon2_password_deps.hash_password`). */
    hash_password: (password: string) => Promise<string>;
}
/**
 * Seed a development test account, bypassing username/password policy.
 *
 * Idempotent by username — if an account with the given username already
 * exists, reuses it and only reconciles the requested role grants. Never
 * updates an existing password (rerun would silently rotate it).
 *
 * Intended for `scripts/dev_setup.ts` — do not call in production.
 *
 * @mutates database - inserts an account/actor pair when missing and grants any requested role role_grants
 * @throws Error if an existing account is found without an associated actor row
 */
export declare const seed_dev_account: (deps: SeedDevAccountDeps, input: SeedDevAccountInput, options?: {
    log?: SetupLogger;
}) => Promise<SeedDevAccountResult>;
//# sourceMappingURL=setup.d.ts.map