IF Commons GitHub

arcactl init and its two models

0047Active

0047-arcactl-init · owner if · domain data

Requirements

FR-001checkpassing

The workstation model MUST say, from a platform and an environment and without touching a file, where a person's files are on Linux, macOS and Windows: .pgpass, pg_service.conf and psqlrc by libpq's rules (its own variables PGPASSFILE, PGSERVICEFILE and PSQLRC first), the directories of arcactl's settings, cache and state, the file of psql that arcactl owns, and the profile files of bash, zsh, fish, PowerShell, nushell and sh; and MUST say that the home directory is not known where it is not.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-workstation.test.ts: the files of a person are found by each platform's own rules and by libpq's own variables where it has them, without touching a file, and a missing home is said

Proved by: data/suite/arcactl-workstation.test.ts

Written in: data/sql/cli/workstation.ts

Tests: passed: suite/arcactl-workstation.test.ts the files of a person are found by each platform's own rules and by libpq's own variables

Cited by: Data, sql/cli/workstation

FR-002checkpassing

A managed block MUST be the only way arcactl changes a file that a person also edits: putting a block in twice MUST be the same as once; it MUST replace itself where it is there and leave everything outside its markers as it was, and keep the file's line ending; taking it out MUST leave the file as it was; and a file whose markers make no sense (one missing, out of order, or the block twice) MUST be an error value and MUST NOT be changed.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-workstation.test.ts: a managed block is put in once however often it is asked, replaces itself, leaves everything outside its markers as it was, keeps the line ending, comes out leaving the file as it was, and a file whose markers make no sense is an error and is not changed

Proved by: data/suite/arcactl-workstation.test.ts

Written in: data/sql/cli/blocks.ts

Tests: passed: suite/arcactl-workstation.test.ts a managed block is put in once however often it is asked, replaces itself, leaves everythi

Cited by: Data, sql/cli/blocks, sql/cli/libpq

FR-003checkpassing

A change of a file MUST be planned as a value (what the file is, what it would be, the difference) before it is made; making it MUST write a temporary file and rename it over, keep the file's mode (a new file the mode asked for, 0600 for a password file) and keep a copy of the first version, write through a symbolic link and keep the link, write nothing where there is nothing to change, and refuse a directory.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-workstation.test.ts: a change of a file is planned before it is made, is made whole by rename with the file's mode kept and a copy of the first version, writes nothing where there is nothing to change, goes through a symbolic link, and refuses a directory

Proved by: data/suite/arcactl-workstation.test.ts

Written in: data/sql/cli/files.ts

Tests: passed: suite/arcactl-workstation.test.ts a change of a file is planned before it is made, is made whole by rename with the file's m

Cited by: Data, sql/cli/files, sql/cli/libpq

FR-004checkpassing

The server model MUST be chosen by an option (--non-interactive, --interactive) or ARCA_MODE first, then by the environment (CI and the variables of the common CI systems), and only where none says, by whether there is a terminal; a server MUST write no file of a home directory and ask no question.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-workstation.test.ts: the server model is chosen by what is said (an option, ARCA_MODE), then by the environment (CI, no terminal), and only a person at a terminal gets the workstation, where files are written and questions asked

Proved by: data/suite/arcactl-workstation.test.ts

Written in: data/sql/cli/server.ts

Tests: passed: suite/arcactl-workstation.test.ts the server model is chosen by what is said (an option, ARCA_MODE), then by the environment

Cited by: Data, sql/cli/main, sql/cli/server

FR-005checkpassing

A server run MUST be given its secrets (the connection URL, the seal key, the unlock secret) as a variable or as the file a <NAME>_FILE variable names, MUST refuse both at once and a file that cannot be read, MUST NOT take a line ending at the end of a file as part of a secret, and MUST NOT print a password it was given either way.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-workstation.test.ts: a server run gets its secrets from a variable or from the file a NAME_FILE names, never both, without a trailing line ending, and a URL given so is used and never printed

Proved by: data/suite/arcactl-workstation.test.ts

Written in: data/sql/cli/server.ts

Tests: passed: suite/arcactl-workstation.test.ts a server run gets its secrets from a variable or from the file a NAME_FILE names, never bo

Cited by: Data, sql/cli/server

FR-006checkpassing

arcactl shell MUST print one script, for bash, zsh, fish, PowerShell, nushell or sh, made from its input alone: the ARCA_* variables, PGSERVICE, and PGOPTIONS with the search path, each value quoted by the rules of its shell so that any text arrives as it is and nothing in it is run; PGOPTIONS MUST stay a person's own where they have set it; the script MUST hold no password and MUST be refused input that has one, or a name that is not safe; and the command MUST connect to nothing, write nothing, name the shell it is for, and give the same script each time.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-shell.test.ts: each shell's quoting makes any text one word: the known answers of the rules of POSIX shells, fish, PowerShell and nushell, and the real shells hand back what they are given, spaces, quotes, $, backticks and line endings included; suite/arcactl-shell.test.ts: the script sets the instance, the service and the search path, keeps the person's own PGOPTIONS, and is the same sourced twice; suite/arcactl-shell.test.ts: the script is valid for every shell it is made for, is the same each time, holds no password, and the command that prints it connects to nothing, names the shell it is for, and refuses input that would not be safe

Proved by: data/suite/arcactl-shell.test.ts

Written in: data/sql/cli/shell.ts

Tests: passed: suite/arcactl-shell.test.ts the script is valid for every shell it is made for, is the same each time, holds no passwo; passed: suite/arcactl-shell.test.ts each shell's quoting makes any text one word: the known answers of the rules of POSIX shel; passed: suite/arcactl-shell.test.ts the script sets the instance, the service and the search path, keeps the person's own PGOP

Open: issue data 00009: CI does not install the shells the arcactl shell tests run

Cited by: Data, sql/cli/shell

FR-007checkpassing

The script MUST define arca, arca-doctor, arca-psql, arca-use and arca-off (and arca-prompt where asked) that call arcactl or psql with their arguments as they are, and completions of the commands, their options and their values made from the one table of commands; sourcing it twice MUST be the same as once; arca-off MUST take away what the script set and its functions and MUST leave a person's own variables; and arca-use MUST switch the instance without carrying the label or the service of the last instance over.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-shell.test.ts: arca-off takes away what the script set and the functions, leaves the person's own variables, and a switch of instance (arca-use, by the real command) replaces what the last one set without carrying its label or service over; suite/arcactl-shell.test.ts: the functions call arcactl with their arguments as they are, and the completions offer the commands, their options and their values; suite/arcactl-shell.test.ts: the script is valid for every shell it is made for, is the same each time, holds no password, and the command that prints it connects to nothing, names the shell it is for, and refuses input that would not be safe

Proved by: data/suite/arcactl-shell.test.ts

Written in: data/sql/cli/shell.ts

Tests: passed: suite/arcactl-shell.test.ts the script is valid for every shell it is made for, is the same each time, holds no passwo; passed: suite/arcactl-shell.test.ts arca-off takes away what the script set and the functions, leaves the person's own variabl; passed: suite/arcactl-shell.test.ts the functions call arcactl with their arguments as they are, and the completions offer the

Cited by: Data, sql/cli/shell

FR-008checkpassing

The writer of .pgpass MUST write each credential as libpq reads it (a colon and a backslash escaped, a lone * a wildcard) inside a managed block of a file made 0600; MUST replace the password of a place that is there where it is, add a new place at the end, and take one out, without touching the credentials of other places or a line the person wrote; MUST say where a line of the person's own that matches comes before the block, since libpq reads the first that matches; MUST find a file whose mode libpq would ignore (the group or others can read it) and put it right; MUST refuse a password or field that .pgpass cannot hold, and MUST NOT print a password in an error.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-libpq.test.ts: `.pgpass` lines escape a colon and a backslash and read back, the file is made 0600, a password is replaced or taken out without touching the person's lines or the other credentials, a line of the person's own that libpq would read first is said, and a credential that cannot be held is refused; suite/arcactl-libpq.test.ts: the real libpq reads what is written to `.pgpass`: each password, whatever it holds, reaches a server that asks for one, a wildcard and an exact line match as libpq reads them, and a file the group can read is ignored until its mode is put right

Proved by: data/suite/arcactl-libpq.test.ts

Written in: data/sql/cli/libpq.ts

Tests: passed: suite/arcactl-libpq.test.ts `.pgpass` lines escape a colon and a backslash and read back, the file is made 0600, a pas; passed: suite/arcactl-libpq.test.ts the real libpq reads what is written to `.pgpass`: each password, whatever it holds, reach

Cited by: Data, sql/cli/libpq

FR-009checkpassing

The writer of pg_service.conf MUST write the instances it is given as the services of a managed block (host, port, dbname, user, sslmode, and the search path as options), read them back, refuse an instance that is not valid and a service the person defined outside the block (libpq reads the first, so the one written would be ignored), and take the block out where it is given none.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-libpq.test.ts: the service file holds the instances in a block, reads them back, refuses a service the person already defined outside it and what is not valid, and the real psql connects by the service, by PGSERVICE as the shell sets it

Proved by: data/suite/arcactl-libpq.test.ts

Written in: data/sql/cli/libpq.ts

Tests: passed: suite/arcactl-libpq.test.ts the service file holds the instances in a block, reads them back, refuses a service the pe

FR-010checkpassing

The writer of psqlrc MUST write a file of its own (the prompt naming the instance, display settings, and the helper queries :tables, :invariants, :guard and :audit) that makes no output at start, and a managed block in the person's psqlrc that includes it by an absolute path with forward slashes; and an undo MUST take every block and credential of these writers out and leave the person's own lines as they were.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-libpq.test.ts: the psqlrc is a block that includes the file arcactl owns, which is quiet at start, names the instance, and gives the helper queries that work on a real database; and undoing takes away what was put in and leaves the person's own

Proved by: data/suite/arcactl-libpq.test.ts

Written in: data/sql/cli/libpq.ts

Tests: passed: suite/arcactl-libpq.test.ts the psqlrc is a block that includes the file arcactl owns, which is quiet at start, names

Cited by: Data, sql/cli/libpq

FR-011checkpassing

Discovery MUST find the instances a person can reach from the connection they gave (its password dropped), libpq's environment, the services of pg_service.conf, the hosts .pgpass has passwords for, what arcactl remembers (its state file, which holds no password), and, where asked, PostgreSQL on this machine; MUST make one of a place heard of twice, naming it by its service; MUST NOT take a wildcard host or a service with no host; and MUST find the arca.config.ts files in an Ergonex workspace (ERGONEX_HOME), leaving out node_modules, .git, .worktrees and dist.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-init.test.ts: discovery finds the instances from the connection given, libpq's environment, the service file, the hosts `.pgpass` has passwords for, what arcactl knows and (where asked) this machine, makes one of the same place, names it by its service, never takes a wildcard host, drops the password of a URL, and finds the arca.config.ts of an Ergonex workspace; suite/arcactl-init.test.ts: the state is written in a stable order, so that the same state is the same text, and a state file that is not one is said

Proved by: data/suite/arcactl-init.test.ts

Written in: data/sql/cli/discover.ts, data/sql/cli/init.ts, data/sql/cli/state.ts

Tests: passed: suite/arcactl-init.test.ts discovery finds the instances from the connection given, libpq's environment, the service ; passed: suite/arcactl-init.test.ts the state is written in a stable order, so that the same state is the same text, and a sta

Cited by: Data, sql/cli/discover, sql/cli/init, sql/cli/state

FR-012checkpassing

Looking at an instance MUST read and change nothing, and MUST say whether it is reached, as whom, what that role could do to it (read, migrate, or migrate and guard, from its being a superuser and its right to create in the schema or the database) and which arca models its tables hold in full; a password MUST go only to the host it is written for (never by a wildcard line) and MUST NOT be in anything said of a failure.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-init.test.ts: looking at an instance reads and changes nothing: it says whether it is reached, as whom, what that role could do (read, migrate, migrate and guard) and which arca models it has, and says why it is not reached without the password; suite/arcactl-init.test.ts: init with nothing given shows the instances found with what each could do, a password goes only to the host it is written for, and init sets up the shell and the psql files with no instance at all

Proved by: data/suite/arcactl-init.test.ts

Written in: data/sql/cli/discover.ts, data/sql/cli/init.ts

Tests: passed: suite/arcactl-init.test.ts init with nothing given shows the instances found with what each could do, a password goes; passed: suite/arcactl-init.test.ts looking at an instance reads and changes nothing: it says whether it is reached, as whom,

Cited by: Data, sql/cli/discover

FR-013checkpassing

arcactl init MUST set up a workstation and no database: show every change it would make (the passwords of .pgpass not shown) and make them only where agreed (--yes, or a person's yes), write nothing on --dry-run or where it is declined or there is no one to ask, change nothing the second time, leave a person's own lines, a service of their own that it would use and what other tools wrote, take away with --undo only what it put in, refuse a server run, refuse an option, model, name, shell or password it cannot use before it writes anything, refuse a file whose markers are broken without changing any file, never put a password anywhere but .pgpass, and end by running the checks of the workstation.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-init.test.ts: init sets up the workstation and no database: the service, the password in .pgpass alone, the psql files and the shell profile, shown first and made only where agreed, the same again changes nothing, and the real psql and a real shell then reach the instance by what was written; suite/arcactl-init.test.ts: init asks a person what it needs and changes nothing they decline, leaves their own lines and the block of Ergonex where they are, uses a service they defined themselves, and undo takes away only what init put in; suite/arcactl-init.test.ts: init is for a workstation: a server run refuses it and writes nothing, an option, a model, a name or a shell that is not valid is refused before anything is written, a URL's password is not shown, and a file whose markers are broken is not changed; suite/arcactl-init.test.ts: init with nothing given shows the instances found with what each could do, a password goes only to the host it is written for, and init sets up the shell and the psql files with no instance at all

Proved by: data/suite/arcactl-init.test.ts

Written in: data/sql/cli/init.ts, data/sql/cli/profile.ts, data/sql/cli/prompt.ts

Tests: passed: suite/arcactl-init.test.ts init with nothing given shows the instances found with what each could do, a password goes; passed: suite/arcactl-init.test.ts init asks a person what it needs and changes nothing they decline, leaves their own lines ; passed: suite/arcactl-init.test.ts init is for a workstation: a server run refuses it and writes nothing, an option, a model,; passed: suite/arcactl-init.test.ts init sets up the workstation and no database: the service, the password in .pgpass alone,

Cited by: Data, sql/cli/profile, sql/cli/prompt

FR-014checkpassing

The script of arcactl shell for the default instance MUST be kept in a cache file of arcactl's, and a managed block arcactl:shell in the profile of each shell wanted MUST source it only where it is readable, so that a shell whose cache is gone starts without an error; the block MUST be a different block from Ergonex's, and both MUST be able to be in one profile.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-init.test.ts: init asks a person what it needs and changes nothing they decline, leaves their own lines and the block of Ergonex where they are, uses a service they defined themselves, and undo takes away only what init put in

Proved by: data/suite/arcactl-init.test.ts

Written in: data/sql/cli/init.ts

Tests: passed: suite/arcactl-init.test.ts init asks a person what it needs and changes nothing they decline, leaves their own lines

FR-015checkpassing

The checks of the workstation (ARCA-W001 to ARCA-W006: psql and its version, the password file and its mode, the default instance's service, the psql files, each profile's block and the cache it sources being the script as it would be made now, and the default instance being reached) MUST each say pass, warn, fail or that they could not be made, and what to do; arcactl doctor --scope workstation (and --scope all, with the checks of the database) MUST run them, and a server run MUST refuse them.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-init.test.ts: the workstation checks find what is wrong: psql missing or old, a password file libpq would ignore, a missing service, a stale or changed psql file, a profile whose block or cache is gone or out of date, and an instance that is not reached; and they run as doctor --scope workstation

Proved by: data/suite/arcactl-init.test.ts

Written in: data/sql/cli/init.ts, data/sql/cli/workstation-checks.ts

Tests: passed: suite/arcactl-init.test.ts the workstation checks find what is wrong: psql missing or old, a password file libpq woul

Cited by: Data, sql/cli/init, sql/cli/workstation-checks

Out of scope

  • arcactl ensure, which keeps a database and its migrations current: its own specification.
  • Looking for PostgreSQL by a Unix socket, in containers or in a cloud: only TCP, the places above and 127.0.0.1:5432 where asked.
  • Putting arcactl on the path or installing it: Ergonex's and the package manager's.
  • The password prompt: the writers are given a password and write it to .pgpass alone; where it comes from (a prompt without echo, standard input) is init's.
  • The helper file needs psql 15 or later (\\getenv); an older psql shows an error at start.
  • arca-scope (a sealed scope for the shell): it needs a command that makes the mark, and comes with it.
  • The completions of zsh, PowerShell and nushell are checked for syntax only (zsh needs a completion system loaded); fish's and bash's are run.
  • A real home directory in the tests: every file is in a temporary directory, and each platform's rules are tested as a function.

Edge cases

  • A person in an Ergonex workspace: ERGONEX_HOME is searched for arca.config.ts, and the profile holds Ergonex's block and ours, per FR-011 and FR-014. (Ergonex replaced IFWS, the earlier workspaces tool, which is retired.)
  • A service of the person's own with the instance's name: it is used and not written over, per FR-013.
  • A role that cannot create in the database or the schema: the instance is read only, per FR-012.
  • A shell whose cache file was removed: it starts, and doctor says the cache is missing, per FR-014 and FR-015.
  • A password with a colon, a backslash, a quote or a space: written escaped, and read back exactly by the real libpq, per FR-008.
  • A .pgpass of mode 0644: libpq says it has group or world access and ignores it; the writer puts the mode right, per FR-008.
  • A service the person already has, with the name of an instance: refused, and the file is not changed, per FR-009.
  • PGlite served over a socket ignores the options startup parameter, so the search path from options is seen in the file and not in a PGlite session, per FR-009.
  • A value with a quote, a $, a backtick or a line ending in a path: it arrives as it is, per FR-006.
  • A person who has their own PGOPTIONS: it is kept, and arca-off does not remove it, per FR-006 and FR-007.
  • sh (dash) has no function name with a dash: it gets arca_doctor and the rest with underscores, per FR-007.
  • A Windows user whose Documents folder is redirected (OneDrive): the PowerShell profile can be named by ARCACTL_PWSH_PROFILE, per FR-001.
  • A dotfile manager that links .zshrc into a repository: the link is kept and the file it leads to is written, per FR-003.
  • A file with an opening marker and no closing one: an error value, and the file is not changed, per FR-002.
  • A file that ends with no line ending: one is added when the block is put in, so taking the block out restores it up to that line ending, per FR-002.
  • CI=false: it is not a CI, per FR-004.
  • Both ARCA_DATABASE_URL and ARCA_DATABASE_URL_FILE: refused, per FR-005.

Assumptions

  • libpq ignores a password file that the group or others can read, so arcactl makes it 0600.
  • A secret in a file has no line ending of its own: the one an editor or echo adds is not part of it.

Open questions

OQ-1open question

Whether the server model should read the secrets of a secret manager (Vault, a cloud's) directly; now it reads a variable or a file, which a sidecar or the platform provides.

Key entities

  • Managed block - the lines between two marker lines that name arcactl and the block.
  • Change - a planned change of one file, before it is made.
  • Mode - workstation or server.

Success criteria

SC-001success criterion

Running arcactl setup twice on a machine leaves every file as it was after the first, and removing it leaves every file as it was before; and a pipeline runs the same commands with nothing asked and no file of a home directory written.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Data, sql/cli/blocks, sql/cli/discover, sql/cli/files, sql/cli/init, sql/cli/libpq, sql/cli/main, sql/cli/profile, sql/cli/prompt, sql/cli/server, sql/cli/shell, sql/cli/state, sql/cli/workstation-checks, sql/cli/workstation

Titles, headings, exports, tables, columns and requirements. Esc closes.