@schovest/pi-config

Shared JSON config I/O for the @schovest/pi-* packages — XDG-aware path resolution, loads that return {} instead of throwing, saves that report failure and chmod to 0600, and TypeBox-driven defaults. It is an internal utility of the rpiv-mono monorepo, published only so its sibling packages can depend on it: there is no CLI, and it registers nothing with Pi Agent.

Install

npm install @schovest/pi-config

ESM only. The package ships TypeScript source — exports and types both point at ./index.ts, with no compiled build — so you need a bundler or a TypeScript-aware runtime (tsx, Bun). Plain node cannot load it, and --experimental-strip-types refuses .ts files under node_modules.

Quick start

import { configPath, loadJsonConfig } from "@schovest/pi-config";

const path = configPath("rpiv-todo"); // ~/.config/rpiv-todo/config.json
const config = loadJsonConfig<{ theme?: string }>(path); // {} if the file is missing

What it provides

Eleven exports, all stateless — no singletons, no caches, no import-time side effects.

Export	What it does
configPath(name, file?)	Resolves <config dir>/<name>/<file>, defaulting to ~/.config/<name>/config.json. An absolute XDG_CONFIG_HOME (or ~/~/…) overrides the directory; anything else falls back.
loadJsonConfig(path)	Parses a JSON file. Returns {} for a missing file, a non-plain-object value, or malformed JSON (which also warns) — a hand-edited config cannot crash the caller.
loadJsonConfigWithLegacyFallback(name, file?)	Reads the XDG path; only when that file is absent does it read the pre-XDG ~/.config/<name>/<file>. Corruption is surfaced, never masked by the legacy file.
saveJsonConfig(path, data)	mkdir -p, writes pretty JSON with a trailing newline, then chmods 0600 (best effort). Returns true/false instead of throwing — guard your "Saved" message on it.
validateConfig(schema, value)	Strips unknown keys, layers schema defaults underneath, and returns {} on any failure.
validateGuidanceFields(fields)	Keeps promptSnippet only if it is a non-empty string, and promptGuidelines only if it is a non-empty array of non-empty strings. Everything else is dropped.
GuidanceFieldsSchema	TypeBox object for the two guidance fields, with additionalProperties: true so consumers can nest it in a larger config schema.
GuidanceFields	Type for the same shape: { promptSnippet?: string; promptGuidelines?: string[] }.
parseModelKey(key)	Splits provider/modelId, also accepting the legacy provider:modelId; slash wins when both are present. Returns undefined if there is no separator at index ≥ 1.
modelKey({ provider, id })	Emits the canonical provider/id. Paired with parseModelKey, persisted colon-form keys migrate on the next save.
readEnvVar(key, fallback?)	Returns the trimmed variable, or fallback when it is unset or empty after trimming.

XDG_CONFIG_HOME is the only variable this package reads, and it governs the rpiv-* config layer only — Pi's own ~/.pi/… paths are a separate concern.

Used by

Package	Uses
rpiv-pi	Path resolution, model-key codec, schema validation for model config
rpiv-advisor	Model-key codec, guidance fields, config load/save
rpiv-web-tools	Provider config load/save, guidance schema and validation
rpiv-telemetry (internal, never published)	Config load/save, schema validation, env-var reads
rpiv-voice	Config load/save
rpiv-i18n	Config load/save
rpiv-todo	Config load, guidance fields
rpiv-ask-user-question	Config load, guidance fields
rpiv-warp	Config load
rpiv-workflow	Path resolution

These are versioned in lockstep with this package.

License

MIT — see LICENSE.