Settings
Rules on this page 20
| ID | Level | Rule |
|---|---|---|
| The Settings window | ||
| SET-01 | MUST | The Settings window opens from a palette command, bound to Ctrl+, (Cmd+, on macOS) in the
CUA keymap.
|
| 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.
|
| Adding a setting touches five places | ||
| SET-06 | MUST | Every setting has a palette command that flips the field or prompts for its value.
|
| Config folder and schema | ||
| 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.
|
| 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.
|
| SET-12 | MUST | Export configuration writes a timestamped .zip of the config folder; Import restores from
one.
|
| Secrets stay out of files | ||
| 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.
|
| 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.
|
| SET-15 | MUST | A repository URL with a password or token in it is refused, with the fix
(Settings Sync). A problem report’s redaction is DIAG-06.
|
| 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.
|
| Settings Sync (Git / GitHub) | ||
| 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.
|
The Settings window
Section titled “The Settings window”- 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.jsonandcua.mac.jsonbind it. - Reference: Editora
view.settings, bound inkeymaps/cua.jsonandcua.mac.json(and in the VS Code and Sublime keymaps; IntelliJ’s usesC-M-s).
- Check (code): a registered command opens Settings, and
- 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.
- Check (by hand): open Settings; the search field sits above the sidebar and the page.
- Reference: Editora
ui/SettingsWindow.java,ui/SettingsSidebarNav.java,ui/SettingsIcons.java.
- 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.
- Check (test): a unit test ranks a title hit above a keyword hit and a whole word above part of one.
- Reference: Editora
ui/SettingsSearch.java,SettingsSearchTest.
- 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.
- Check (code): no Save or Apply button in the window; text fields commit through
commitOnEnterOrBlur. - Reference: Editora
SettingsWindow.commitOnEnterOrBlur;SettingsSyncPage’s branch field marks an invalid branch.
- Check (code): no Save or Apply button in the window; text fields commit through
- SET-05 SHOULD A change made in one window reaches every other open window.
- Check (test): an FX test changes a setting in one window and finds it applied in the other.
- Reference: Editora: every window holds the same
config/SharedConfig.java, which announces each change (onSettingsChanged);CrossWindowSettingsFxTest.

Before adding a setting
Section titled “Before adding a setting”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.
Adding a setting touches five places
Section titled “Adding a setting touches five places”- Model field, default and accessors, with a schema bump and migration.
- Control, built once, writing the field and applying it.
- Row on its page with search keywords.
- Load line that sets the control from the model, safe to run at any time.
- 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.
Config folder and schema
Section titled “Config folder and schema”- SET-07 MUST Config lives in
~/.<app>, unless<APP>_CONFIG_DIRor a command-line flag (CLI-02) names another folder.- Check (code): one resolver picks the folder, in the order
--config-dir, the environment variable, the default. - Reference: Editora
AppandConfigManager.configDirFor,ConfigDirTest.
- Check (code): one resolver picks the folder, in the order
- SET-08 SHOULD
settings.jsonholds preferences,workspace-state.jsonsession state, and other stores their own JSON files.- Check (code): the config folder’s file names are constants in the config package.
- Reference: Editora
config/ConfigManager.java,config/WorkspaceState.java.
- SET-09 MUST Every versioned file has a
SCHEMA_VERSIONand av → v+1migration step. A purely additive field uses an identity step.- Check (code): each store declares
SCHEMA_VERSION, and the migrations have one step per version. - Reference: Editora
config/migration/ConfigMigrations.java,ConfigSchema.java,ConfigMigrationsTest.
- Check (code): each store declares
- SET-10 MUST A file newer than the running build is backed up to
<name>.v<n>.bakand defaults load.- Why: an older build never clobbers a newer config.
- Check (test): a test loads a too-new
settings.jsonand 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\uXXXXescape in a.propertiesfile). - Reference: Editora
config/migration/ConfigMigrations.java(keepCorrupt),ConfigLoadProblemsTest(outOfRangeNumbersAreClampedOnLoad,anUnparseableFileIsReportedWithItsBackup); Terminaconfig/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
.zipof the config folder; Import restores from one.- Check (test): tests over the zip’s name and contents, and an import that replaces only the ticked parts.
- Reference: Editora
config/ConfigExporter.java,config/ConfigImport.java,ConfigExporterTest,ConfigImportTest.
Secrets stay out of files
Section titled “Secrets stay out of files”- 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:Settingskeeps 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 repository URL with a password or token in it is refused, with the fix
(Settings Sync). A problem report’s redaction is DIAG-06.
- Check (by hand): paste
https://user:token@host/repo.gitas the sync repository. - Reference: Editora
ui/SettingsSyncPage.java(settings.sync.repo.credentials),sync/SyncEngine.java(hasCredentials, checked again at sync time).
- Check (by hand): paste
- 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 (
tlsTrustAllinconfig/Config.java). Editora doesn’t yet: Require registry signature for plugins is a Settings checkbox and theplugins.toggleRequireSignaturecommand.
Settings Sync (Git / GitHub)
Section titled “Settings Sync (Git / GitHub)”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
ghCLI. The account that can read the repo is pinned per clone, so machines with two GitHub accounts work.- Check (test): a test remembers the first account that can read the repository and uses it without asking again.
- Reference: Editora
sync/SyncAccount.java,SyncAccountTest,ui/SettingsSyncPage.java.
- SET-19 SHOULD Sync runs automatically (on change and at start) and on demand. Machine-local keys (window
size, paths) never sync.
- Check (code): one pure class decides which keys or files travel, and machine-local ones are not among them.
- Reference: Editora
ui/SettingsSync.java(after startup, after a local change, on an interval, andsync.now),sync/SyncCategory.java; Torrentasync/SyncKeys.java.
- SET-20 SHOULD On a same-entry conflict this machine wins, and a backup is taken before any sync that
replaces local files.
- Check (test): a merge test where both sides changed one entry keeps this machine’s.
- Reference: Editora
sync/SyncMerge.java,SyncMergeTest.
- SET-21 SHOULD Sync status shows as a pill in Settings and as echo messages; failures go to the Message Log.
- Check (by hand): point Sync at a repository that does not exist and read the pill and the log.
- Reference: Editora
ui/SettingsSyncPage.java,SyncStatus.



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