Skip to content

Latest commit

 

History

History
186 lines (167 loc) · 37.2 KB

features.md

File metadata and controls

186 lines (167 loc) · 37.2 KB

Features

Every user-visible capability of github.com/ubgo/appdir, read from the code, with the guide section that explains it and the example that runs it. An example is linked only when its code calls the feature's API (checked by searching the example's Go files for the identifier, variable or file the feature is about). A dash with a reason means the feature cannot run here (Windows only, root only, two disks, a property); a plain dash means no example calls it yet. For the order to read the guides in, see the learning path.

Start

Feature Package Guide Example
New(app, opts...) resolves every home and path in one call and creates nothing appdir First use: resolve with New quickstart
App name must match ^[a-z0-9][a-z0-9._-]*$, else ErrInvalidOption appdir First use: pick an app name quickstart
Reads never create: New, Path, Paths only stat folders and read home.jsonc and pointer keys appdir First use: resolve with New quickstart
Path(kind) returns a kind's path in its effective home appdir First use: Path and PathIn quickstart
PathIn(kind, scope) returns a kind's path in one named home (global or project) appdir First use: Path and PathIn quickstart, prod-db-guard
Ensure(kind) creates a kind's folder (or a file kind's parent) on first use and returns the path appdir First use: Ensure quickstart
InitProject(dir) creates .<app>/ with home.jsonc: the only way a project home is made appdir Init: InitProject project-init
InitProject refuses to turn the global home into a project home appdir Init: refuse the global home project-init
InitHome(path, scope) creates a home anywhere (<app> init --home X, pointer targets) appdir Init: InitHome project-init, pointers
InitHome on a folder holding another app's home.jsonc fails with ErrNotHome; on this app's home it is a no-op; a home.jsonc that does not parse is ErrBadHomeFile and stays untouched appdir Init: InitHome project-init
home.jsonc (app, layout, scope) is written atomically: temp file, fsync, rename, Windows retry appdir Init: InitProject project-init
InitProject(dir) with a relative dir resolves it against the working folder New used (WithWorkDir), not the process's current folder appdir Init: relative folder and broken home.jsonc project-init
InitProject and InitHome refuse a home whose home.jsonc exists but cannot be parsed; they never overwrite it appdir Init: relative folder and broken home.jsonc project-init
With WithoutKind(KindHome), init creates only the home folder and writes no home.jsonc; a home: pointer target is then recognised by its name .<app> appdir Kinds: drop the home file custom-layout
App() returns the app name appdir First use: resolve with New quickstart, demo
New validates the whole option set: an empty env prefix, an unknown mode or lookup, a layout version or socket length below 1, a nil seam, an empty profile list, a release or dev profile not in the list, a run-file or legacy folder name that is not one plain path segment are each ErrInvalidOption appdir Errors: ErrInvalidOption, Options reference doctor

Homes

Feature Package Guide Example
Global home is ~/.<app> (rule global); XDG variables are not read appdir Global and project homes: the global home quickstart
Global(), Project() and HasProject() give both homes at once, with Base, Data, Rule, Fallback, Note, Info appdir Global and project homes: inspect both quickstart
Walk-up finds the nearest .<app>/ from the working folder (rule project) appdir Lookup: the walk lookup
Walk-up stops at a repo root: an entry named .git, file, folder or symlink (a dangling link counts) appdir Lookup: the walk lookup
Walk-up checks $HOME itself, then stops; it also stops at the filesystem root appdir Lookup: the walk lookup
Walk-up stops at a change of disk (device id, Windows volume serial) appdir Lookup: the walk — (needs a second mount)
<APP>_CEILING_DIRS stops the walk (a walk that starts inside a ceiling stops there); relative entries are ignored with warning ceiling-relative (WarnCeilingRelative); entries that do not expand to an absolute path with ceiling-dropped (WarnCeilingDropped) appdir Lookup: ceilings lookup
The global home is never taken as a project home (compared with os.SameFile) appdir Lookup: the walk lookup
The walk follows the real path of the working folder; folders compare by identity, not by string appdir Lookup: the walk lookup
Nearest wins in a monorepo; a nested repo is a wall appdir Lookup: the walk lookup
WithLookup(HereOnly) looks only in the working folder appdir Lookup: HereOnly lookup
HereOnly still translates a linked worktree to its main checkout first, by design (SPEC 4.4 step 4) appdir Worktrees: pitfalls worktree
A linked git worktree uses the main checkout's .<app>/ (rule worktree), read from gitdir: and commondir, git never run appdir Worktrees: translate the working folder worktree
Main checkout without .<app>/: the worktree's own lookup runs, with warning worktree-main-missing when it finds a home (none when neither has one) appdir Worktrees: main checkout with no home worktree
A submodule is its own project; a worktree of a bare repo uses itself appdir Worktrees: cases that are not shared worktree
No project home: project kinds fail with ErrNoProject ("no ./ here; run ' init' or pass --home") appdir Lookup: no project home lookup, project-init
WithHome(path) (--home) is one home for every scope (rule flag) appdir Overrides: --home overrides
<APP>_HOME is one home for every scope (rule env-home) appdir Overrides: APP_HOME overrides
<APP>_<KIND>_DIR moves one non-anchored kind (rule env-kind); a file kind keeps its file name appdir Overrides: APP_KIND_DIR overrides
KindEnv(kind), EnvName(suffix) and EnvPrefix() give the variable names a tool should print appdir Overrides: print the variable names overrides
WithEnvPrefix(p) changes the env prefix (default: app upper-cased, - and . to _) appdir Overrides: print the variable names overrides
WithDirName(name) changes the home folder name (default .<app>); it must be one plain folder name, else ErrInvalidOption appdir Global and project homes: rename the home folder overrides
User paths expand ~, ~/… and ${VAR}; $VAR stays literal; ~user is refused; relative paths resolve against the working folder appdir Overrides: how user paths expand overrides
An unset or empty ${VAR} is ErrEnvVar naming the variable, never a path at / appdir Overrides: how user paths expand overrides
A broken --home or <APP>_HOME (an unset ${VAR}) fails every kind with its error, the cache included: no temp fallback and no code defaults appdir Overrides: report a broken override, Fallbacks: pitfalls overrides
Under --home or <APP>_HOME, a both kind is listed once by Paths(), labelled global appdir paths --json: print it doctor
A variable that is set but empty counts as unset appdir Overrides: how user paths expand overrides
No $HOME: global config kinds use code defaults (rule defaults), global data kinds fail with ErrNoHome appdir Fallbacks: no user home fallbacks
Disposable kinds with no $HOME use <tmp>/<Name(app)>-<uid>/ (rule temp, fallback) appdir Fallbacks: no user home fallbacks
Ensure on a disposable kind falls back to the temp folder when creating fails read-only or with a permission error appdir Fallbacks: read-only home fallbacks
WithTempFallback(false) turns both temp fallbacks off appdir Fallbacks: turn the temp fallback off fallbacks
The temp folder is created 0700 and refused when it is a symlink or owned by someone else (ErrUnsafeTemp) appdir Fallbacks: no user home fallbacks
Running as root in another user's home is refused (ErrRootOwned) unless WithAllowRoot(true) appdir Fallbacks: the root guard — (needs root)
A read-only home fails with the OS error, the path and a hint to set <APP>_HOME or <APP>_<KIND>_DIR appdir Fallbacks: read-only home fallbacks

Pointers

Feature Package Guide Example
home: pointer key moves the project home to another folder (rule pointer) appdir Pointer keys: relative home: pointers
db: pointer key moves only the database (rule pointer); backups/ stays appdir Pointer keys: db: pointers, prod-db-guard
Pointer keys are read from the marker's config.jsonc then config.local.jsonc; local wins per key appdir Pointer keys: before you start pointers
Absolute pointer refused in the committed file: only relative or ~/ (ErrPointerAbsolute) appdir Pointer keys: absolute paths in config.local.jsonc pointers
Relative pointers resolve against the folder holding the config file appdir Pointer keys: relative home: pointers
Missing home: target or missing db: folder fails with ErrPointerMissing appdir Pointer keys: relative home: pointers
home: target must hold this app's home.jsonc (ErrPointerNotHome); with WithoutKind(KindHome) it must be a folder named .<app> appdir Pointer keys: create the target pointers
Pointers go one hop only; the target's own keys are ignored with warning pointer-chain-ignored appdir Pointer keys: one hop pointers
A pointer error fails every kind that can live in the project: project-only kinds, project-else-global kinds (logs) and the project side of both kinds; nothing falls back to the marker or the global home, and only global kinds such as the cache keep working appdir Pointer keys: ConfigFiles under a broken pointer, pitfalls pointers
A pointer value that is not a string fails with ErrInvalidOption appdir Pointer keys: a value must be a string pointers
A local "home": "" does not clear a home: pointer in the committed file appdir Pointer keys: an empty local home: pointers
Dev profile: home: data goes to <target>/profiles/<profile>/, db: is ignored with warning pointer-ignored-for-profile appdir Pointer keys: the dev profile pointers

Layout

Feature Package Guide Example
Standard kinds: home, config, config-local, gitignore, shared, db, backups, cache, run, logs (constants KindHome … KindLogs) appdir Kinds: read the layout in effect, before you start custom-layout
WithMode(ModeGlobal) makes data kinds global; the default ModeProject fails safe; Mode() reports it appdir Kinds: pick the mode, choosing: mode and scopes custom-layout, fallbacks, daemon-paths
Scopes global, project, project-else-global, both (ScopeGlobal, ScopeProject, ScopeProjectElseGlobal, ScopeBoth); logs is project-else-global in project mode appdir Kinds: pick the mode custom-layout
WithKind(name, …) adds a kind: starts as a folder, ignored by git, in the data scope, with its own <APP>_<KIND>_DIR appdir Kinds: declare the layout custom-layout
WithKind on an existing kind changes it in place (rename = new path, keeps git rule and scope) appdir Kinds: declare the layout custom-layout
WithoutKind(name) drops a kind from paths, the gitignore block and Ensure appdir Kinds: declare the layout custom-layout
Kind options Folder, File, Commit, Scoped, Disposable, Anchored appdir Kinds: declare the layout custom-layout
Kind option Ignore() turns a committed kind back to ignored appdir Kinds: flip a git rule custom-layout
Kind names and paths are validated (relative, slash-separated, no ..), else ErrInvalidOption appdir Kinds: invalid names and paths custom-layout
Kinds() returns the layout in effect, in stable order, as KindSpec (Name, Path, Type TypeFile/TypeFolder, Git GitCommit/GitIgnore, Scope, Disposable, Anchored) appdir Kinds: read the layout in effect custom-layout, doctor
GitignoreBlock() builds the marker block: *, then re-includes of committed kinds, parents first appdir Gitignore: see the block custom-layout, doctor
WithGitCommit adds committed patterns; WithGitIgnore wins over every commit rule, even a pattern equal to a generated re-include line appdir Gitignore: see the block custom-layout
WriteGitignore() replaces only the text between # <app>:begin / # <app>:end; broken markers are ErrGitignoreMarkers appdir Gitignore: write it, broken markers custom-layout
The .gitignore block is written only inside a git work tree (InitProject does it too) appdir Gitignore: write it, before you start project-init
Folders are created 0700 and files 0600; existing permissions are left alone appdir Files and permissions: private folders custom-layout
WithPerm(dir, file) changes the modes Ensure creates with appdir Files and permissions: WithPerm and the cache tag custom-layout
Windows: a protected ACL for the current user and SYSTEM only appdir Files and permissions: platform extras — (Windows only)
Disposable folders get CACHEDIR.TAG appdir Files and permissions: private folders custom-layout
WithCacheTag(false) turns the cache tag and the platform no-index markers off appdir Files and permissions: WithPerm and the cache tag custom-layout
macOS .metadata_never_index and Time Machine exclusion; Windows not-content-indexed attribute appdir Files and permissions: platform extras — (macOS and Windows only)
A home may be a symlink; Ensure of a file kind refuses a link whose real path is outside its home, or a broken link (ErrSymlinkEscape) appdir Files and permissions: the symlink rule custom-layout
VerifyFile(path) applies the symlink rule to a file the tool did not get from Ensure; inside is decided by whole path segments (a folder named ..x is inside) appdir Files and permissions: VerifyFile custom-layout
A home whose home.jsonc layout is newer than WithLayoutVersion refuses writes (ErrLayoutTooNew) appdir Files and permissions: the layout version guard custom-layout, doctor
A kind that is not in the layout (never declared, or dropped by WithoutKind) is ErrUnknownKind from Path, PathIn and Ensure appdir Errors: ErrUnknownKind, Kinds: ask for a kind that is gone doctor, custom-layout

Config files

Feature Package Guide Example
ConfigFiles() lists config files in read order: global, project marker, home: target; later wins per key appdir Config files: list and merge config-files, doctor
Each ConfigFile says its home, whether it is local, and whether it is committed (inside a git work tree) appdir Config files: list and merge config-files
Dev profile reads the shared project config, then its own profiles/<profile>/config.local.jsonc last (ConfigFile.Profile) appdir Config files: the dev profile's own file config-files
With a home: pointer the target's two files are read after the marker's appdir Config files: with a home: pointer config-files
Missing files are still listed; --home lists one home's two files; no $HOME drops the global files appdir Config files: --home and no $HOME config-files
With a broken pointer, ConfigFiles() still lists the marker's own two files so doctor can name the bad key appdir Pointer keys: ConfigFiles under a broken pointer pointers
A config kind dropped with WithoutKind is left out of ConfigFiles() appdir Config files: drop a config kind config-files
WithConfigReader replaces the JSONC reader used for home.jsonc and pointer keys appdir Config files: replace the reader config-files
Built-in JSONC reader: // and /* */ comments, trailing commas, strings handled; a top-level null and a backslash before a raw newline are errors appdir/internal/jsonclite Config files: replace the reader pointers, config-files

Profiles

Feature Package Guide Example
Profile order: WithProfile (--profile), then <APP>_PROFILE, then the build; Profile() reports it appdir Profiles: let appdir pick, choosing: profiles profiles
<APP>_PROFILE limits: a dev build ignores prod unless <APP>_ALLOW_PROD=1, a release build ignores others (warning profile-env-ignored) appdir Profiles: let appdir pick profiles
An unknown profile from flag or env is ErrUnknownProfile, never a fallback appdir Profiles: let appdir pick profiles, daemon-paths
Custom profiles: WithProfiles, WithReleaseProfile, WithDevProfile (defaults ProfileProd, ProfileDev) appdir Profiles: add your own profiles
WithRelease(bool) states release or dev from the tool's -ldflags -X variable appdir Release detection: flag or build info profiles
Without the flag, a release is a clean tagged build with no vcs.revision (only go install module@vX) appdir Release detection: flag or build info profiles, testing-setup
IsRelease() and ReleaseReason() say what was decided and why appdir Release detection: report the decision profiles, doctor
A non-release profile uses ~/.<app>-<profile> and .<app>/profiles/<profile>/ for data; anchored files stay shared appdir Profiles: where each profile keeps its files profiles
Name(base) and NameWith(base, sep) add the profile suffix to labels appdir Names: Name and NameWith profiles
Banner() gives the one stderr line for a non-release profile appdir Names: print the banner profiles
CheckDB(path) prod-db guard: a dev build refuses the prod database (ErrProdDB) appdir Prod-db guard: check before you open prod-db-guard
CheckDB returns AccessReadWrite, or with <APP>_ALLOW_PROD=1 on the prod db AccessReadOnly (DBAccess.String(): read-write, read-only) appdir Prod-db guard: prod and dev databases prod-db-guard
CheckDB follows a release-profile db: pointer in the prod view appdir Prod-db guard: follow a db: pointer prod-db-guard
CheckDB resolves a relative path against WithWorkDir, runs VerifyFile, ignores every <APP>_* variable in the prod view, and catches the prod db before the prod home exists appdir Prod-db guard: relative path, no folders yet prod-db-guard
Env-leak filter: in a non-release profile, <APP>_HOME or <APP>_<KIND>_DIR inside the prod home is ignored (warning env-points-to-prod) appdir Child processes: the env-leak filter profiles, prod-db-guard
ChildEnv(environ) sets <APP>_PROFILE for child processes appdir Child processes: pass the profile profiles
CleanEnv(environ, prefix) drops every <PREFIX>_* variable appdir Child processes: pass the profile profiles
ForProfile(p) resolves another profile's paths without opening its files appdir Child processes: pass the profile profiles
Warnings() returns what the tool should print once appdir paths --json: doctor, warning codes doctor, lookup, pointers

Runtime

Feature Package Guide Example
RunPath(file) gives run/lock, run/daemon.lock, run/<app>.pid, run/discovery.json, run/<app>.sock, run/socket (RunLock … RunSocketFile); WithRunFile renames one to one plain file name appdir Run files: get the run files daemon-paths
Socket() returns run/<app>.sock when the path is short enough appdir Run files: socket and its folder daemon-paths
Socket fallback over WithSocketMaxLen (100): $XDG_RUNTIME_DIR/<name>/ on Linux, else /tmp/<name>-<uid>/, <hash>.sock, path written to run/socket appdir Run files: the fallback for long paths daemon-paths
Windows: always a named pipe \\.\pipe\<name>-<user>-<hash> appdir Run files: the fallback for long paths — (Windows only)
EnsureSocketDir() creates run/ on every OS, plus the fallback folder 0700 with owner and symlink checks when the socket falls back appdir Run files: socket and its folder daemon-paths
DaemonProfile(): WithDaemonProfile (--daemon-profile), then <APP>_DAEMON_PROFILE, then the own profile appdir Run files: the daemon of another profile daemon-paths
DaemonDiscovery() gives the daemon profile's discovery file appdir Run files: the daemon of another profile daemon-paths
MoveLegacy(ctx) moves an old global home named by WithLegacyHome(LegacyHome{Dir, DaemonLocks}) on first run; same disk is one rename, then MOVED.txt (status moved, MoveDone) appdir Legacy move: move on the first run legacy-move
MoveLegacy outcomes: none, already, both-exist, skipped (MoveNone, MoveAlready, MoveBothExist, MoveSkipped; non-release profile, or home set by --home/<APP>_HOME) appdir Legacy move: cases that do not move legacy-move
MoveLegacy cross-disk copy: verify file count and bytes plus WithLegacyVerify, keep the old folder as .moved-<date> appdir Legacy move: moving across disks — (needs two disks)
MoveLegacy takes a lock and probes old daemon locks without creating files (ErrBusy) appdir/internal/flock Legacy move: wait for the old daemon legacy-move
MoveLegacy crash safety: a partial copy is redone, a finished copy is completed, a move stopped after the old folder was renamed is finished on the next run appdir Legacy move: moving across disks — (needs two disks)

Testing

Feature Package Guide Example
ForTest(t, app) points HOME, <APP>_HOME, XDG, TMPDIR and the agent config folder variables into a temp root and unsets every other <APP>_* variable and the leaking GIT_* variables appdir Testing: isolate the process with ForTest testing-setup
In a test binary, New panics on any path outside the test root, the socket fallback folder included; WithTestGuard(false) turns it off appdir Testing: the guard testing-setup
Seams WithEnv, WithHomeDir, WithWorkDir, WithBuildInfo replace every outside input appdir Testing: seams testing-setup

Reference

Feature Package Guide Example
Paths() lists every kind (both homes for both kinds) for paths --json and doctor appdir paths --json: print it, First use: Paths doctor, quickstart
Paths() never fails: a kind whose home is unusable carries the message in Entry.Error and the failing rule in Rule appdir paths --json: print it doctor
Every path records its Rule: flag, env-home, env-kind, project, worktree, pointer, global, temp, defaults (RuleFlag … RuleDefaults) appdir paths --json: print it, rules quickstart, overrides
JSON tags on Home, Entry, ConfigFile, Socket, Warning, MoveResult appdir paths --json: result types doctor
Warning codes: profile-env-ignored, env-points-to-prod, pointer-chain-ignored, pointer-ignored-for-profile, ceiling-relative, ceiling-dropped, worktree-main-missing (WarnProfileEnvIgnored … WarnWorktreeMainMissing) appdir paths --json: warning codes doctor
Sentinel errors checked with errors.Is, each wrapped in a full sentence; exit codes stay the tool's job appdir Errors: suggested exit codes doctor
Every default is an option (the full option table) appdir Options reference — (reference table)
Dirs is immutable and safe for concurrent use; no package-level mutable state appdir Options: Dirs is immutable — (a property, not a call)
Standard library only; macOS, Linux and Windows appdir Platforms: platform table — (a property, not a call)