Skip to content
Pauta4.5.0

Settings

Rules on this page 20
IDLevelRule
The Settings window
SET-01MUST
The Settings window opens from a palette command, bound to Ctrl+, (Cmd+, on macOS) in the CUA keymap.
SET-02MUST
The window has a sidebar of pages with icons on the left, the page on the right, and a search field on top.
SET-03MUST
Search finds a row by its title, description, visible text, its card or section heading, its page name and English keywords. Title hits rank above description hits; whole words above word starts. The page with the best match opens, and every non-matching row, heading and card is hidden.
SET-04MUST
Settings apply live, with no Save button. Text fields commit on Enter or focus loss; invalid values are marked and never committed.
SET-05SHOULD
A change made in one window reaches every other open window.
Adding a setting touches five places
SET-06MUST
Every setting has a palette command that flips the field or prompts for its value.
Config folder and schema
SET-07MUST
Config lives in ~/.<app>, unless <APP>_CONFIG_DIR or a command-line flag (CLI-02) names another folder.
SET-08SHOULD
settings.json holds preferences, workspace-state.json session state, and other stores their own JSON files.
SET-09MUST
Every versioned file has a SCHEMA_VERSION and a v → v+1 migration step. A purely additive field uses an identity step.
SET-10MUST
A file newer than the running build is backed up to <name>.v<n>.bak and defaults load.
SET-11MUST
Never trust a config file. Clamp every value to its valid range when it is read, not only when it is written; an unknown value falls back to its default; a file that cannot be decoded is kept as a backup (Editora names it <name>.corrupt.bak) and defaults load. A bad file never stops the app from starting.
SET-12MUST
Export configuration writes a timestamped .zip of the config folder; Import restores from one.
Secrets stay out of files
SET-13MUST
No secret goes in a config file. API keys and tokens go to the operating system’s keychain: macOS Keychain, Windows Credential Manager, the Secret Service on Linux. Calls may block on a prompt, so they run off the FX thread.
SET-14MUST
A credential the app can ask for again lives in memory for the session only and is never written. Work that needs it waits until the user has signed in this session; do not “fix” that by storing the password.
SET-15MUST
A secret in the wrong place is refused. A repository URL with a password or token in it is refused, with the fix (Settings Sync); a problem report redacts tokens, credentials, e-mail addresses, user names and home paths before anyone sees it (Diagnostics).
SET-16MUST
An option that weakens security has no UI: it exists only as a key in the config file, so nobody turns it on by clicking.
Settings Sync (Git / GitHub)
SET-18SHOULD
Setup is by pasting a repo URL, or Create on GitHub through the gh CLI. The account that can read the repo is pinned per clone, so machines with two GitHub accounts work.
SET-19SHOULD
Sync runs automatically (on change and at start) and on demand. Machine-local keys (window size, paths) never sync.
SET-20SHOULD
On a same-entry conflict this machine wins, and a backup is taken before any sync that replaces local files.
SET-21SHOULD
Sync status shows as a pill in Settings and as echo messages; failures go to the Message Log.
  • SET-01 MUST The Settings window opens from a palette command, bound to Ctrl+, (Cmd+, on macOS) in the CUA keymap.
    • Check (code): a registered command opens Settings, and cua.json and cua.mac.json bind it.
    • Reference: Editora view.settings, bound in keymaps/cua.json and cua.mac.json (and in the VS Code and Sublime keymaps; IntelliJ’s uses C-M-s).
  • SET-02 MUST The window has a sidebar of pages with icons on the left, the page on the right, and a search field on top.
  • SET-03 MUST Search finds a row by its title, description, visible text, its card or section heading, its page name and English keywords. Title hits rank above description hits; whole words above word starts. The page with the best match opens, and every non-matching row, heading and card is hidden.
  • SET-04 MUST Settings apply live, with no Save button. Text fields commit on Enter or focus loss; invalid values are marked and never committed.
  • SET-05 SHOULD A change made in one window reaches every other open window.
Editora's Settings window searching for sync, with the Sync page open
Typing sync in Settings: pages without a match gray out and the best page opens.

A setting is a question the user has to answer. When the question has one right answer, choose it, make it the behavior, and say why in the code and the docs; do not ship a knob for it. Modula’s test: would a car radio have it? A preset button, yes; a “decimation stages” spinner, no. So Modula has no gain, bandwidth or squelch control: each has one right value for a listener, and the app supplies it. Add a setting when people really differ (a keymap, a theme, a language), not when the developer could not decide.

  1. Model field, default and accessors, with a schema bump and migration.
  2. Control, built once, writing the field and applying it.
  3. Row on its page with search keywords.
  4. Load line that sets the control from the model, safe to run at any time.
  5. Palette command that flips or prompts the same field, plus strings in every catalog.
  • SET-06 MUST Every setting has a palette command that flips the field or prompts for its value.
    • Check (by hand): for each row in Settings, find a palette command that changes it.
    • Reference: Editora’s view.toggle… and picker commands (ui/WindowCommandRegistrar.java). Editora does not have one for every setting yet: terminalNotifications, for one, is only a Settings row.
  • SET-07 MUST Config lives in ~/.<app>, unless <APP>_CONFIG_DIR or a command-line flag (CLI-02) names another folder.
  • SET-08 SHOULD settings.json holds preferences, workspace-state.json session state, and other stores their own JSON files.
  • SET-09 MUST Every versioned file has a SCHEMA_VERSION and a v → v+1 migration step. A purely additive field uses an identity step.
  • SET-10 MUST A file newer than the running build is backed up to <name>.v<n>.bak and defaults load.
    • Why: an older build never clobbers a newer config.
    • Check (test): a test loads a too-new settings.json and finds the backup and the defaults.
    • Reference: Editora ConfigVersioningTest (tooNewSettingsAreBackedUpAndDefaultsLoaded).
  • SET-11 MUST Never trust a config file. Clamp every value to its valid range when it is read, not only when it is written; an unknown value falls back to its default; a file that cannot be decoded is kept as a backup (Editora names it <name>.corrupt.bak) and defaults load. A bad file never stops the app from starting.
    • Why: config is plain JSON (or properties) and people edit it by hand. A hand-edited two-million-line scrollback must not exhaust memory at the next launch (Termina).
    • Check (test): a test loads out-of-range numbers and an unparseable file, including one that makes the parser throw something other than an IOException (a malformed \uXXXX escape in a .properties file).
    • Reference: Editora config/migration/ConfigMigrations.java (keepCorrupt), ConfigLoadProblemsTest (outOfRangeNumbersAreClampedOnLoad, anUnparseableFileIsReportedWithItsBackup); Termina config/Settings.java, SettingsTest (aMalformedEscapeNoLongerStopsTheAppStarting). Torrenta, Modula, Mirada and nux keep no backup, and in Torrenta and nux a malformed escape stops the app from starting.
  • SET-12 MUST Export configuration writes a timestamped .zip of the config folder; Import restores from one.
  • SET-13 MUST No secret goes in a config file. API keys and tokens go to the operating system’s keychain: macOS Keychain, Windows Credential Manager, the Secret Service on Linux. Calls may block on a prompt, so they run off the FX thread.
    • Check (code): no key or token field in the settings model; reads and writes go through the secret store.
    • Reference: Editora secrets/SecretStore.java, config/ApiKeyVault.java. Editora doesn’t yet: Settings keeps the AI keys as a fallback for when no keychain answers, and saving a key from Settings writes the keychain on the FX thread. Torrenta keeps its proxy password, Torznab key and remote-profile passwords in plain text.
  • SET-14 MUST A credential the app can ask for again lives in memory for the session only and is never written. Work that needs it waits until the user has signed in this session; do not “fix” that by storing the password.
    • Check (code): the credential is a field of a runtime object, absent from every config class.
    • Reference: nux’s UPS login (app/CommandRunner.java).
  • SET-15 MUST A secret in the wrong place is refused. A repository URL with a password or token in it is refused, with the fix (Settings Sync); a problem report redacts tokens, credentials, e-mail addresses, user names and home paths before anyone sees it (Diagnostics).
  • SET-16 MUST An option that weakens security has no UI: it exists only as a key in the config file, so nobody turns it on by clicking.
    • Check (code): no Settings row or command writes such a key.
    • Reference: nux’s trust-all TLS (tlsTrustAll in config/Config.java). Editora doesn’t yet: Require registry signature for plugins is a Settings checkbox and the plugins.toggleRequireSignature command.

An app with user data worth carrying between computers offers sync, on its own Settings page (SYNC-01), into a Git repository the user owns (SYNC-02). The rules below are how it behaves.

  • SET-18 SHOULD Setup is by pasting a repo URL, or Create on GitHub through the gh CLI. The account that can read the repo is pinned per clone, so machines with two GitHub accounts work.
  • SET-19 SHOULD Sync runs automatically (on change and at start) and on demand. Machine-local keys (window size, paths) never sync.
  • SET-20 SHOULD On a same-entry conflict this machine wins, and a backup is taken before any sync that replaces local files.
  • SET-21 SHOULD Sync status shows as a pill in Settings and as echo messages; failures go to the Message Log.
Editora's Sync settings page
Editora's Sync page: repository, branch, Create on GitHub… and what to sync.
Torrenta's Sync settings page
Torrenta's Sync page.
Termina's Sync settings page
Termina's Sync page.

Pauta 4.5.0 · · Changelog · This page in the latest edition