# Extension settings contract Every repository extension that reads configuration declares it through its own committed `src/pi-ext-settings.ts` and remains usable when installed without the rest of `pi-ext`. `scripts/codegen/templates/pi-ext-settings.ts` generates these local copies through `mise run //:codegen` for the extensions listed in the `pi-ext-settings` target of `scripts/codegen/targets.json`. Root and extension `check` tasks compare generated files byte-for-byte, and the template's own tests live in `scripts/codegen/pi-ext-settings.test.ts`. Debug selection is separate and follows the [debug contract](DEBUG.md). ## Declarations A `SettingDeclaration` names a `key`, a `parse` function, a `default`, an optional `flag`, and an optional `env` variable. For example: ```ts import { parseBooleanSetting, registerSettingFlag, resolveSetting, type SettingDeclaration, } from "./src/pi-ext-settings.ts"; const ENABLE_SETTING: SettingDeclaration = { key: "nushell.enable", parse: parseBooleanSetting, default: false, flag: { name: "nushell", type: "boolean", description: "Enable Nushell tools at startup" }, env: "PI_NUSHELL_ENABLE", }; registerSettingFlag(pi, ENABLE_SETTING); // at extension load const setting = resolveSetting(pi, ctx, ENABLE_SETTING); // at session_start or first use ``` Keys start with the extension directory name and use camelCase leaves, such as `git-safe.cloneTimeoutMs`. An extension may declare its whole block, such as `pipi`, when one parser validates it as a unit. Renamed keys get no aliases; a stale key is invalid rather than silently ignored. ## Declarative choices and integer ranges Declarations may provide a human-readable `label` and `description`. `defineChoiceSetting` derives strict string validation from its `choices` list. `defineIntegerSetting` derives validation from inclusive `range.min` and `range.max`, with an optional positive integer `range.step` measured from `min`. Both helpers return ordinary `SettingDeclaration` objects, including their parser and public metadata. They reject invalid declaration bounds or defaults when the declaration is created. Integer settings accept numbers from settings files and numeric strings from flags or environment variables, never booleans or coercible objects. Choice and integer declarations may use an `undefined` default to preserve an unset configuration; it is not a value to write into JSON. Explicit null or invalid values remain errors rather than falling through to that default. ```ts import { defineChoiceSetting, defineIntegerSetting } from "./src/pi-ext-settings.ts"; const ENGINE = defineChoiceSetting({ key: "example.engine", label: "Engine", description: "Choose speed or quality.", choices: ["fast", "quality"] as const, default: "fast", }); const THREADS = defineIntegerSetting({ key: "example.threads", label: "Threads", range: { min: 1, max: 8 }, default: undefined, }); ``` The README generator reads this metadata statically, including imported choice arrays, numeric bounds and exported constants from the extension's generated settings helper, without executing extension code. Custom parsers remain available for open-ended strings or structured settings. Metadata adds neither a settings picker nor persistence APIs and does not change storage or source precedence. ## Resolution Each declaration resolves independently in this order: flag, env, trusted project `.pi/settings.json`, user `~/.pi/agent/settings.json`, default. Pass the real `ctx.isProjectTrusted()`; untrusted project settings are never read. Settings needed before any session exists, such as keyboard shortcuts, resolve at load with `process.cwd()` and trust `false`, so they come from env and user settings only. When project and user values are both plain objects, they deep-merge with project winning per key; arrays and scalars replace. Resolve once per session or operation, not on hot paths. ## Sources Flags suit startup toggles only. Pi flags are boolean or string, and a boolean flag can only turn behavior on. `registerSettingFlag` registers a flag without a default so an omitted flag defers to lower sources; never call `pi.registerFlag` or `pi.getFlag` directly. Environment variables keep established names, including third-party ones such as `FIREFOX_BIN`. New variables are `PI__`, uppercasing the slug and replacing hyphens with underscores. An empty environment value counts as set. Negated variables such as `PI_MOCKUP_NO_OPEN` invert the boolean parser for the env source only. Credentials and tokens stay in environment variables or Pi's credential store and never become settings. ## Validation Settings files accept JSON types only; numeric and boolean strings are accepted only from flags and env. Use `parseBooleanSetting` and `parseNumberSetting`, then add range checks; timer and subprocess timeouts are capped at `MAX_TIMER_MS`. A parser returns `undefined` or throws an `Error` to reject a value; thrown messages appear in the reported error. An invalid value never falls through to a lower source. Report it once through `ctx.ui.notify` with warning severity and use the built-in default, or fail the operation when the setting is a safety limit. Never write diagnostics to stdout. ## Tests and documentation Each participating extension keeps `__tests__/settings.test.ts` covering the default, each declared source, trusted project over user, ignored untrusted project, and invalid values without fallthrough. Tests assert observable behavior where practical and use the repository-owned fixture `test/fixture/create-pi-session.ts` with its sandboxed home; emit `session_shutdown` before disposing a session. Each extension README documents its keys, env variables, flags, defaults, valid ranges, trust, and invalid-value behavior. ## Enforcement `scripts/extensions.ts` rejects direct `getGlobalSettings`, `getProjectSettings`, `registerFlag`, and `getFlag` calls outside generated `src/pi-ext-*.ts` files. `SettingsManager.create` remains allowed for building child agent sessions.