@osdlc/tiered-dirs 0.0.1-stage → 0.3.0

package/README.md

@@ -1,5 +1,423 @@
 # @osdlc/tiered-dirs
 
-This name is reserved. The first real release will be published from
-[osdlc/osdlc](https://github.com/osdlc/osdlc) by its release workflow.
-This placeholder (0.0.1-stage) contains no code.
+Machine-local directories for every product a vendor ships, on Linux, macOS
+and Windows.
+
+## The problem
+
+A program that keeps state on disk needs a directory for it, and the right one
+differs by operating system and by kind of state. A vendor that ships several
+programs also has to decide which state they share and which they keep apart.
+And a test suite must never write into the developer's real home directory.
+
+`@osdlc/tiered-dirs` answers all three. A caller names a directory on two axes:
+
+- **tier**: who shares the state. `vendor()` is `<vendor>`, shared by
+  everything the vendor ships. `suite(key)` is `<vendor>.<key>`, shared by the
+  programs of one suite. `standalone(tool)` is the bare `<tool>`, for a general
+  tool that is not part of the vendor's suite.
+- **home**: how long the state must last. `durable`, `config`, `cache`,
+  `state`, `logs` or `runtime`.
+
+`scratch()` sits outside both axes: the platform temp directory.
+
+A **convention** picks the per-OS table the homes come from: `native` (the
+default) or `xdg`. They differ on macOS only.
+
+It is for a vendor with more than one program, or one program with tests that
+must not touch the real home. It computes paths only: it creates, reads and
+deletes nothing on disk. It has no dependencies. The
+[Rust crate `tiered-dirs`](https://crates.io/crates/tiered-dirs) is its twin
+and gives the same relative paths.
+
+## When not to use it
+
+- One program with one config file. `env-paths` or `xdg-app-paths` is enough.
+- You want the app framework's own directories, for example Tauri's. Use the
+  framework's.
+- You need the directories created. This package does not create them.
+
+## How it compares
+
+| Package | What it gives |
+|---|---|
+| [env-paths](https://github.com/sindresorhus/env-paths) | One tool's data, config, cache, log and temp directories per OS. |
+| [xdg-basedir](https://github.com/sindresorhus/xdg-basedir) | The XDG variables and their defaults, with no app name. |
+| [xdg-app-paths](https://github.com/rivy/js.xdg-app-paths) | One tool's XDG directories, with a legacy fallback. |
+| [os-paths](https://github.com/rivy/js.os-paths) | The OS home, temp and XDG directories. |
+| [appdirsjs](https://github.com/codingjerk/appdirs-js) | One tool's cache, config and data directories. |
+
+They give per-app or XDG directories for one tool. None of them has shared
+vendor and suite tiers, separate state and runtime homes that are never the
+cache, one override variable per root, a scratch root for tests, or a Rust
+twin held to the same paths.
+
+## Install
+
+```sh
+npm install @osdlc/tiered-dirs
+```
+
+## Quick start
+
+```ts
+import { TieredDirs, envVars } from '@osdlc/tiered-dirs'
+
+const dirs = TieredDirs.fromEnv('com.example', envVars('EXAMPLE'), {
+  platform: 'linux',
+  env: { HOME: '/home/ada' },
+})
+
+dirs.vendor().config().path
+// /home/ada/.config/com.example
+
+dirs.suite('notes').cache().scoped('vaults', 'v7').app('search').path
+// /home/ada/.cache/com.example.notes/vaults/v7/search
+```
+
+A real program leaves out `platform` and `env`; they are there so the paths
+above do not depend on the machine. `examples/usage.test.ts` runs every export
+of this package.
+
+## Tiers
+
+| tier | segment | shared by |
+|---|---|---|
+| vendor | `<vendor>` | every product line the vendor ships |
+| suite | `<vendor>.<suiteKey>` | the products that share user data |
+| standalone | `<tool>` | one general tool, shipped outside the suite |
+
+The vendor is the one segment the caller fixes up front. The suite segment is
+composed from it. `suiteKey` is a caller-supplied constant, not derived from a
+bundle identifier. `Tier.kind` reports which method produced a tier (`vendor`,
+`suite` or `standalone`).
+
+`Tier` and `Dir` are exported as types only. Their constructors are not part
+of the package, so a value always comes from a checked method:
+`TieredDirs.vendor()`, `suite()`, `standalone()` and `scratch()`, `Tier.home()`
+and the home methods, and `Dir.scoped()` and `Dir.app()`.
+
+The product tier, one product's own directory keyed by bundle identifier, is
+not here. An app framework usually resolves it, and this package takes no
+framework dependency. `TieredDirs.isVendorBundleId(bundleId)` lets a layer
+above check that a product's bundle id sits under the vendor.
+`isVendorBundleId(vendor, bundleId)` is the same check for a caller with no
+`TieredDirs`. Both are a bare prefix test, as in the Rust twin.
+
+Tiers are distinct addresses and there is no merge. `vendor().durable()`,
+`suite(k).durable()` and `standalone(t).durable()` are different locations.
+This package never reads two and merges them. A given piece of state lives at
+exactly one tier and the caller names the tier it means.
+
+### A general tool supplies its own root
+
+The vendor and suite tiers govern a suite: products that share one owner. A
+general tool the vendor ships into other people's repositories is not in that
+suite, and `suite('tool')` would write the vendor's namespace onto a stranger's
+machine.
+
+`standalone(tool)` is the tier for that tool. Its segment is the bare tool
+name, with no vendor composition. Its config directory is `~/.config/<tool>` on
+Linux, and on macOS under `xdg`. Under `native` on macOS it is
+`~/Library/Application Support/<tool>`.
+
+```ts
+import { TieredDirs, envVars } from '@osdlc/tiered-dirs'
+
+const cli = TieredDirs.fromEnv('com.example', envVars('TOOL'), {
+  convention: 'xdg',
+  platform: 'darwin',
+  env: { HOME: '/Users/ada' },
+})
+cli.standalone('tool').config().path
+// /Users/ada/.config/tool
+```
+
+## Homes
+
+| home | Linux (both) | macOS, `native` | macOS, `xdg` | Windows (both) |
+|---|---|---|---|---|
+| durable | `$XDG_DATA_HOME`, `~/.local/share` | `~/Library/Application Support` | `$XDG_DATA_HOME`, `~/.local/share` | `%APPDATA%` |
+| config | `$XDG_CONFIG_HOME`, `~/.config` | `~/Library/Application Support` | `$XDG_CONFIG_HOME`, `~/.config` | `%APPDATA%` |
+| cache | `$XDG_CACHE_HOME`, `~/.cache` | `~/Library/Caches` | `$XDG_CACHE_HOME`, `~/.cache` | `%LOCALAPPDATA%` |
+| state | `$XDG_STATE_HOME`, `~/.local/state` | `~/Library/Application Support` | `$XDG_STATE_HOME`, `~/.local/state` | `%LOCALAPPDATA%\state` |
+| logs | `$XDG_STATE_HOME`, `~/.local/state` | `~/Library/Logs` | `$XDG_STATE_HOME`, `~/.local/state` | `<durable>/logs` |
+| runtime | `$XDG_RUNTIME_DIR`, `<durable>/run` | `<durable>/run` | `$XDG_RUNTIME_DIR`, `<durable>/run` | `<durable>/run` |
+
+`logs` and `state` never fall back to `cache`, because the OS purges cache. On
+Windows `state` is `%LOCALAPPDATA%\state`: under the same root as each tier's
+cache folder and beside it, never the same folder. `state`, `logs` and `run`
+are reserved segment names, in any case, so no tier can land on another home's
+root: `standalone('state')` throws `TieredDirsError`. `runtime` sits under
+`durable` for the same reason: the OS may purge cache while the process a
+pidfile describes is still alive. Under XDG, logs and state share one
+directory, so keep their file names apart. A relative `XDG_*` value is
+ignored, as the XDG spec says, and `~` is not expanded. On Windows, `xdg`
+means `native`.
+
+## Choosing a convention
+
+- A CLI or developer tool uses `xdg`. Its users look for `~/.config/<tool>` and
+  keep it in their dotfiles.
+- A GUI app uses `native`. macOS users and tools expect
+  `~/Library/Application Support`.
+- A file that two programs read is resolved in one place, by the program that
+  owns it, under that program's convention.
+
+Pass `{ convention: 'xdg' }` to `systemBaseDirs` or `TieredDirs.fromEnv`.
+`<P>_CONVENTION=native` or `xdg` overrides the caller's choice; any other value
+throws `TieredDirsError`. The value is trimmed, then must match exactly, in
+lower case. `parseConvention(value)` parses a convention from anywhere else,
+such as a flag: exactly `native` or `xdg`, untrimmed, like the Rust twin's
+`FromStr`. `xdgBaseDirs(home, env)` builds the XDG table under any home, on
+any host.
+
+## Overrides and scratch roots
+
+Every base directory can be moved by environment variable, so a test or harness
+can run a whole app inside one scratch root. The caller picks the names:
+`envVars('EXAMPLE')` reads `EXAMPLE_ROOT`, `EXAMPLE_<HOME>_DIR`,
+`EXAMPLE_SCRATCH_DIR`, `EXAMPLE_REQUIRE_OVERRIDE` and `EXAMPLE_CONVENTION`.
+`overrideVars(vars)` lists the ones that move a directory, and
+`isOverridden(vars, env)` says whether any of them is set to a non-empty value
+(`env` defaults to `process.env`). Per base directory,
+the first answer wins:
+
+| order | source | effect |
+|---|---|---|
+| 1 | `<P>_<HOME>_DIR` | moves one: `<P>_DURABLE_DIR`, `<P>_CONFIG_DIR`, `<P>_CACHE_DIR`, `<P>_STATE_DIR`, `<P>_LOGS_DIR`, `<P>_RUNTIME_DIR`, `<P>_SCRATCH_DIR` |
+| 2 | `<P>_ROOT` | the rooted layout: `<root>/durable`, `<root>/config`, `<root>/cache`, `<root>/state`, `<root>/logs`, `<root>/scratch`, runtime at `<root>/durable/run` |
+| 3 | the OS default | the table above, for `<P>_CONVENTION` when set, else `opts.convention`, else `native` |
+
+Runtime follows durable: when `<P>_RUNTIME_DIR` is unset but durable is moved by
+step 1 or 2, runtime is `<durable>/run`. An empty variable counts as unset; a
+relative one is an error. `opts.overrides` on `systemBaseDirs` sits ahead of all
+three. `rootedBaseDirs(root)` builds the layout of step 2 directly.
+
+### Tests never resolve a real home
+
+When neither `env` nor `home` is injected, `systemBaseDirs` applies two rules
+first:
+
+- In a test runner process where `<P>_ROOT` is unset and `HOME` is not moved,
+  `<P>_ROOT` reads as `<tmp>/tiered-dirs-test-<pid>-<start ms>`. "HOME moved"
+  means `HOME` differs from the passwd home. The Rust twin has no such
+  condition. It is kept so a test that points `HOME` at a fixture keeps its
+  paths. `{ testRoot: false }` turns the test-root default off explicitly. A CI
+  job that sets `HOME` itself, such as a GitHub Actions container job
+  (`HOME=/github/home`, passwd home `/root`), therefore gets no test-root
+  default: set `<P>_ROOT` there. A test runner
+  process is one with a test file as its entry point that runs with
+  `NODE_ENV=test`, `NODE_TEST_CONTEXT` (set by `node --test`) or under Bun.
+  A Vitest worker is detected too. A test that points `HOME` at a fixture
+  keeps it. A child process a test spawns gets no default, because its entry
+  point is neither a test file nor a Vitest worker.
+- With `<P>_REQUIRE_OVERRIDE` set, a root that would fall back to the per-OS
+  table throws a `TieredDirsError` naming the fix.
+
+`testRoot()` returns that root, cached per module instance (per test file under
+Vitest's default isolation), in a test runner process, and
+`undefined` elsewhere. A layer that reads its own variables, such as a
+product tier, uses it to apply the same default. Pass `{ testRoot: false }`
+to `systemBaseDirs` or `TieredDirs.fromEnv` to skip the first rule only.
+`<P>_ROOT` and `<P>_REQUIRE_OVERRIDE` still apply.
+
+## Scratch
+
+`scratch()` returns the platform temp directory: `$TMPDIR` or `/tmp`, and
+`%TEMP%` / `%TMP%` on Windows. It adds nothing to the platform answer, so "no
+direct OS path call outside this package" can be checked with a search.
+
+Scratch is not a `Home` and not a tier. It holds state that does not outlive a
+single call. The `runtime` home holds state that does and describes a live
+process: a pidfile, a socket, a lock.
+
+## Injectable roots
+
+Nothing below `systemBaseDirs` reads the environment. A `TieredDirs` resolves
+its roots once, at construction, and every path after that is pure string work.
+A server that cannot read the environment hands in roots from its own config:
+
+```ts
+import { TieredDirs, type BaseDirs } from '@osdlc/tiered-dirs'
+
+const bases: BaseDirs = {
+  durable: '/srv/data',
+  config: '/srv/config',
+  cache: '/srv/cache',
+  state: '/srv/state',
+  logs: '/srv/logs',
+  runtime: '/srv/run',
+  scratch: '/srv/tmp',
+}
+const dirs = new TieredDirs('com.example', bases)
+dirs.vendor().cache().path
+// /srv/cache/com.example
+```
+
+Every `BaseDirs` field is `readonly`. To change a root, build a new object, for
+example `{ ...bases, cache: '/srv/other' }`.
+
+Tests use the same seam to assert exact paths without touching a real home
+directory.
+
+## Failure
+
+Every base directory can fail to resolve; headless CI and sandboxes do not
+always have a home. `systemBaseDirs` and `TieredDirs.fromEnv` throw
+`TieredDirsError` rather than assert, and `overrides` rescues an environment
+with no home at all. `vendor`, `suiteKey`, `tool`, `kind`, `key` and `app` are
+each checked as a single path segment: non-empty, no separator, no `..`,
+matching `/^[a-z0-9][a-z0-9._-]*$/i`, and not `state`, `logs` or `run`.
+`isValidSegment(key)` is that rule. An invalid one throws `TieredDirsError`.
+
+`TieredDirsError.code` says which failure it is, one code per variant of the
+Rust twin's `Error`. Its type is `TieredDirsErrorCode`:
+
+| code | when |
+|---|---|
+| `MISSING_BASE_DIR` | a root needs a home directory and none can be found |
+| `RELATIVE_OVERRIDE` | an override variable holds a relative path |
+| `OVERRIDE_REQUIRED` | `<P>_REQUIRE_OVERRIDE` is set and a root would fall back to the per-OS table |
+| `INVALID_CONVENTION` | `<P>_CONVENTION` or `parseConvention` got a value other than `native` or `xdg` |
+| `INVALID_KEY` | a segment fails `isValidSegment` |
+
+The message gives the details, such as the variable or the key.
+
+## API
+
+```typescript
+function envVars(prefix: string): EnvVars
+function overrideVars(vars: EnvVars): readonly string[]
+function isOverridden(vars: EnvVars, env?: Record<string, string | undefined>): boolean
+interface EnvVars {
+  root: string
+  dirs: Record<keyof BaseDirs, string>
+  requireOverride: string
+  convention: string
+}
+
+function isValidSegment(key: string): boolean
+
+type Home = 'durable' | 'config' | 'cache' | 'state' | 'logs' | 'runtime'
+const HOMES: readonly Home[]
+type Convention = 'native' | 'xdg'
+const CONVENTIONS: readonly Convention[]
+function parseConvention(value: string): Convention
+type TierKind = 'vendor' | 'suite' | 'standalone'
+const TIER_KINDS: readonly TierKind[]
+interface BaseDirs {
+  readonly durable: string
+  readonly config: string
+  readonly cache: string
+  readonly state: string
+  readonly logs: string
+  readonly runtime: string
+  readonly scratch: string
+}
+interface ResolveOptions {
+  platform?: string
+  convention?: Convention
+  env?: Record<string, string | undefined>
+  home?: string
+  overrides?: Partial<BaseDirs>
+  testRoot?: boolean // default true
+}
+function systemBaseDirs(vars: EnvVars, opts?: ResolveOptions): BaseDirs
+function testRoot(): string | undefined
+function rootedBaseDirs(root: string): BaseDirs
+function xdgBaseDirs(home: string, env: Record<string, string | undefined>): BaseDirs
+
+class TieredDirs {
+  constructor(vendor: string, bases: BaseDirs)
+  static fromEnv(vendor: string, vars: EnvVars, opts?: ResolveOptions): TieredDirs
+  readonly vendorName: string
+  readonly bases: Readonly<BaseDirs>
+  vendor(): Tier
+  suite(suiteKey: string): Tier
+  standalone(tool: string): Tier
+  scratch(): Dir
+  isVendorBundleId(bundleId: string): boolean
+}
+function isVendorBundleId(vendor: string, bundleId: string): boolean
+
+// Tier and Dir are exported as types only. Get one from the methods above.
+class Tier {
+  readonly segment: string
+  readonly kind: TierKind
+  durable(): Dir
+  config(): Dir
+  cache(): Dir
+  state(): Dir
+  logs(): Dir
+  runtime(): Dir
+  home(home: Home): Dir
+}
+
+class Dir {
+  readonly base: string
+  readonly segments: readonly string[]
+  get path(): string // absolute, host separator
+  get relative(): string // below the base, always "/"-separated
+  scoped(kind: string, key: string): Dir
+  app(app: string): Dir
+}
+
+type TieredDirsErrorCode =
+  | 'MISSING_BASE_DIR'
+  | 'RELATIVE_OVERRIDE'
+  | 'OVERRIDE_REQUIRED'
+  | 'INVALID_CONVENTION'
+  | 'INVALID_KEY'
+class TieredDirsError extends Error {
+  readonly code: TieredDirsErrorCode
+}
+```
+
+## Parity
+
+This package is the twin of the Rust `tiered-dirs` crate.
+`packages/rust/tiered-dirs/tests/fixtures/parity.json` in the repository is
+the contract between them: a table of (tier, home, scope, app) to expected
+relative path, a `scratch_cases` list for the scratch root, `env_cases` for the
+override order, `convention_cases` for the XDG layout under a stub home and
+`rejected_conventions`. Both suites read that one file with base directories
+stubbed: `rootedBaseDirs('/stub')` here, `BaseDirs::rooted("/stub")` there.
+Neither twin may add a path shape the other lacks.
+
+## Stability
+
+Every export is stable in 0.x, and its TSDoc says so: `TieredDirs`,
+`TieredDirsError`, `envVars`, `overrideVars`, `isOverridden`,
+`systemBaseDirs`, `testRoot`, `rootedBaseDirs`, `xdgBaseDirs`,
+`parseConvention`, `isValidSegment`, `isVendorBundleId`, `HOMES`,
+`CONVENTIONS`, `TIER_KINDS` and the types `Tier`, `Dir`, `BaseDirs`, `EnvVars`, `Home`,
+`Convention`, `TierKind`, `ResolveOptions` and `TieredDirsErrorCode`. A
+breaking change to one of them ships only in a new 0.x minor release, with a
+CHANGELOG entry that starts with `Breaking:`.
+
+Some of them may grow in a minor release, as their Rust twins are
+`#[non_exhaustive]`: `TierKind` and `Convention` may gain a member,
+`TieredDirsErrorCode` a code, and `EnvVars` a name. A `switch` over one of the
+unions needs a `default` arm. Build `EnvVars` with `envVars()`, not by hand,
+so a new name is filled in. `Home` is exhaustive on purpose: a new home
+changes every caller's layout, so adding one is a breaking release.
+
+## Runtimes and platforms
+
+Node.js 22 or later, ESM only. The built package is tested on Node.js 22 and
+24, on Linux and macOS. The code uses `node:os` and `node:path` only. The path
+tables above cover Windows, and the tests check all three tables by injecting
+the platform. The tests compare paths without depending on the separator, but
+they do not run on a Windows host in CI yet. Bun is not tested, though the
+test-root rule recognises it.
+
+## Security
+
+The package builds path strings. It runs no commands, writes no files and
+creates no temporary files. Every caller-supplied segment is checked, and an
+override variable must be an absolute path. See [SECURITY.md](./SECURITY.md).
+
+## License
+
+`MIT OR Apache-2.0`, at your option.

package/SECURITY.md

@@ -0,0 +1,23 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please report vulnerabilities privately. Do not open a public issue.
+
+Use GitHub private vulnerability reporting on the repository: open the
+[Security tab](https://github.com/osdlc/osdlc/security) and choose
+"Report a vulnerability".
+
+Include the version, a short description, and steps to reproduce. A minimal
+code sample helps.
+
+## Supported versions
+
+Only the latest release gets security fixes. While the version is 0.x, that
+is the latest minor release. Upgrade to it.
+
+## What to expect
+
+This is a small project. We aim to reply within a week. We will tell you
+whether we accept the report and keep you updated until a fix is released.
+We will credit you in the release notes if you want that.