dev/setup.ts

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().

Declarations
#

21 declarations

view source

create_database
#

dev/setup.ts view source

(deps: CommandDeps, db_name: string, options?: CreateDatabaseOptions | undefined): Promise<CommandResult>

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.

deps

command execution capability

type CommandDeps

db_name

database name to create

type string

options?

logger

type CreateDatabaseOptions | undefined
optional

returns

Promise<CommandResult>

the command result

CreateDatabaseOptions
#

default_setup_logger
#

generate_random_key
#

dev/setup.ts view source

(deps: CommandDeps): Promise<string>

Generate a random base64 key using openssl.

deps

command execution capability

type CommandDeps

returns

Promise<string>

a random 32-byte base64-encoded key

throws

  • Error - if `openssl rand` fails or is unavailable

parse_db_name
#

dev/setup.ts view source

(url: string): string | null

Extract the database name from a PostgreSQL URL.

url

type string

returns

string | null

the database name, or null if the URL is invalid or has no path

read_env_var
#

dev/setup.ts view source

(deps: Pick<FsReadDeps, "stat" | "read_text_file">, env_path: string, name: string): Promise<string | undefined>

Read a single env var from a dotenv-style file.

deps

file read capability

type Pick<FsReadDeps, "stat" | "read_text_file">

env_path

path to the .env file

type string

name

the variable name to read

type string

returns

Promise<string | undefined>

the value, or undefined if the file or variable doesn't exist

reset_bootstrap_token
#

dev/setup.ts view source

(deps: FsReadDeps & FsWriteDeps & FsRemoveDeps & CommandDeps & EnvDeps, app_name: string, options?: SetupBootstrapTokenOptions | undefined): Promise<...>

Remove an existing bootstrap token and create a new one.

deps

file, command, env, and remove capabilities

type FsReadDeps & FsWriteDeps & FsRemoveDeps & CommandDeps & EnvDeps

app_name

application name

type string

options?

state_dir override, permissions, logger

type SetupBootstrapTokenOptions | undefined
optional

returns

Promise<SetupTokenResult>

result from creating the new token

reset_database
#

dev/setup.ts view source

(deps: CommandDeps & FsReadDeps & FsRemoveDeps, database_url: string, options?: ResetDatabaseOptions | undefined): Promise<...>

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.

deps

command and file capabilities

type CommandDeps & FsReadDeps & FsRemoveDeps

database_url

the DATABASE_URL value

type string

options?

pglite_data_dir, logger

type ResetDatabaseOptions | undefined
optional

returns

Promise<ResetDbResult>

result describing what happened

ResetDatabaseOptions
#

ResetDbResult
#

dev/setup.ts view source

ResetDbResult

Result of reset_database.

reset

Whether the database was actually reset.

type boolean

skipped

Whether the operation was skipped (e.g. pglite with no data dir).

type boolean

db_type

What type of database was detected.

type 'postgres' | 'pglite' | 'none'

seed_dev_account
#

dev/setup.ts view source

(deps: SeedDevAccountDeps, input: SeedDevAccountInput, options?: { log?: SetupLogger | undefined; } | undefined): Promise<...>

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.

deps

type SeedDevAccountDeps

input

type SeedDevAccountInput

options?

type { log?: SetupLogger | undefined; } | undefined
optional

returns

Promise<SeedDevAccountResult>

throws

  • Error - if an existing account is found without an associated actor row

SeedDevAccountDeps
#

SeedDevAccountInput
#

dev/setup.ts view source

SeedDevAccountInput

username

Account username. Policy is bypassed — any non-empty string is accepted.

type string

password

Account password. Policy is bypassed — any non-empty string is accepted.

type string

roles

Roles to grant via role_grant (idempotent).

type ReadonlyArray<string>

SeedDevAccountResult
#

dev/setup.ts view source

SeedDevAccountResult

Result of seed_dev_account.

account_id

type string

actor_id

type string

created

True if a new account was created; false if one already existed.

type boolean

setup_bootstrap_token
#

dev/setup.ts view source

(deps: FsReadDeps & FsWriteDeps & CommandDeps & EnvDeps, app_name: string, options?: SetupBootstrapTokenOptions | undefined): Promise<...>

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.

deps

file, command, and env capabilities

type FsReadDeps & FsWriteDeps & CommandDeps & EnvDeps

app_name

application name (used for default state directory)

type string

options?

state_dir override, permissions, logger

type SetupBootstrapTokenOptions | undefined
optional

returns

Promise<SetupTokenResult>

result indicating whether a token was created

setup_env_file
#

dev/setup.ts view source

(deps: FsReadDeps & FsWriteDeps & CommandDeps, env_path: string, example_path: string, options?: SetupEnvOptions | undefined): Promise<...>

Create an env file from its example template, auto-generating SECRET_COOKIE_KEYS.

If the file already exists, backfills any empty values that have generators. Idempotent — safe to re-run.

deps

file read, write, and command capabilities

type FsReadDeps & FsWriteDeps & CommandDeps

env_path

path for the env file (e.g. .env.development)

type string

example_path

path to the example template

type string

options?

extra replacements, permissions, logger

type SetupEnvOptions | undefined
optional

returns

Promise<SetupEnvResult>

result indicating whether the file was created or updated

SetupBootstrapTokenOptions
#

dev/setup.ts view source

SetupBootstrapTokenOptions

state_dir

State directory override. Defaults to ~/.{app_name}.

type string

set_permissions

Optional callback to set file/directory permissions.

type (path: string, mode: number) => Promise<void>

log

type SetupLogger

SetupEnvOptions
#

dev/setup.ts view source

SetupEnvOptions

Options for setup_env_file.

replacements

Extra env var replacements beyond the default SECRET_COOKIE_KEYS.

Keys are env var names, values are async generators. Replaces ^KEY=$ (empty value) patterns in the env file.

type Record<string, () => Promise<string>>

set_permissions

Optional callback to set file permissions (e.g. Deno.chmod).

type (path: string, mode: number) => Promise<void>

log

type SetupLogger

SetupEnvResult
#

dev/setup.ts view source

SetupEnvResult

Result of setup_env_file.

created

Whether a new file was created (vs updating existing).

type boolean

updated

Whether any values were generated/replaced.

type boolean

path

The env file path.

type string

SetupLogger
#

dev/setup.ts view source

SetupLogger

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.

ok

type (msg: string) => void

skip

type (msg: string) => void

error

type (msg: string) => void

SetupTokenResult
#

Depends on
#