@henryqw/pi-config-store

Give extension authors one safe home for Pi extension files. A bad user config never stops an extension and is never silent: the store reports each problem and uses safe defaults, or it disables the extension when a default is not safe. End users do not install this package directly in Pi.

Install

npm install @henryqw/pi-config-store

Use your extension package's package manager. Do not run pi install for this library. Requires @earendil-works/pi-coding-agent 1.1.0 or later in the 1.x series.

Use

Declare each top-level key in a field table. Give each optional field a default. Mark a key as required when no safe default exists.

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { createConfigStore, field, parsers, registerConfigReporting, required } from "@henryqw/pi-config-store";

export default function (pi: ExtensionAPI) {
  const store = createConfigStore({
    extensionId: "my-extension",
    fields: {
      token: required(parsers.string({ trim: true })),
      split: field(parsers.oneOf(["right", "down"] as const), "right"),
      directory: field(parsers.absolutePath(), "/var/my-extension", { onInvalid: "disable" }),
      overrides: field(parsers.record(parsers.boolean(), { key: parsers.absolutePath() }), {}),
    },
  });
  const reporter = registerConfigReporting(pi, [store]);

  pi.registerCommand("my-command", {
    handler: async (_args, ctx) => {
      const loaded = store.loadSync();
      reporter.report(ctx, store, loaded);
      if (loaded.status === "disabled") return;
      // Use loaded.value.
    },
  });
}

registerConfigReporting shows launch problems. Call reporter.report after each lazy read, so that new problems also show once.

Load rules

A near-miss key is equal to the declared key except for letter case, or it has a small edit distance from the declared key. The limit is one edit (insert, delete, replace, or swap of two adjacent characters) for each three characters of the declared key, and a maximum of two edits. Thus, a declared key of one or two characters matches only a different letter case. The rule applies to each field table, also in parsers.object, but not to the keys of parsers.record or entries.

loadSync() does not throw for file content or I/O problems, and it never writes.

When the config is disabled, disable the extension's features. Keep config repair commands available, so that the user can fix the file.

Launch reporting

On each session_start, registerConfigReporting(pi, stores) loads each store. It shows one notification for each file that has issues:

When ctx.hasUI is false, the reporter writes the same text to stderr. Each issue shows one time in each session. The reporter identifies an issue by its file path, kind, key, and message. All reporters in the Pi process share this record, also the reporters of other extensions. Thus, when two extensions report the same file, each issue shows one time. A new session_start event starts a new record.

API

Field parsers

Write other rules as a FieldParser. Write cross-field rules in check.

By default, helpers use Pi's getAgentDir(). Pass agentDir to use another agent directory. Path helpers return paths without filesystem side effects.

For custom files that are not hand-edited JSON, such as generated state, use extensionConfigDir and the bounded text helpers. The text helpers do not parse data, handle missing files, or lock access. The owning extension controls their format, schema, recovery, and lock policy.

Only the owning extension writes its config home. Consumers use the owner's API or namespaced Pi events. They do not read or write another extension's files directly.

State and storage

• The config home is getAgentDir()/config/<extension-id>/.
• The default JSON file is getAgentDir()/config/<extension-id>/config.json. Use fileName for another hand-edited JSON file in the same home, such as presets.json.
• A missing file without required fields gives { status: "ok", source: "missing", value, issues: [] } with the defaults. The store does not create a file.

save, update, and remove are asynchronous. Every mutation uses a lock. Writes use a same-directory temporary file and atomic rename.

Limits and recovery

An extension ID must be one lowercase path component. A fileName must be one JSON file name. The helpers and store reject other values.

JSON reads and writes have a 64 KiB limit. UTF-8 decoding is strict.

Reads never change a file. A malformed or invalid file stays unchanged until the user edits it or an explicit write replaces it.

store.update(mutator) refuses a file that has any issue or a disabled config. It throws an error that gives the path and the issues, and it does not change the file. store.save(value) is an explicit full replacement. It validates value with the load rules and throws on any issue. It replaces a malformed file. Parsers of a store that writes must accept their own output.

A direct text read requires maxBytes to be a positive safe integer. It consumes at most maxBytes + 1 bytes and rejects a larger file. Invalid UTF-8 throws, and missing-file errors pass through unchanged.

A direct text write creates or restricts its parent directory to mode 0700 where supported. It writes a same-directory temporary file at mode 0600, flushes it, then renames it. Failures before rename clean the temporary file. A successful rename is committed, so later cancellation does not turn success into an error.

Repository default: most extension owners can assume one active config writer. Under that assumption, reload the extension after a manual or external edit before its next write. A stale in-memory full replacement is outside the supported workflow.

store.save(value) locks and replaces the whole config. The lock serializes writes, but does not merge fields from stale values. Use store.update(mutator) when an extension supports multiple processes, sessions, or writers, or to keep concurrent field changes. It reads the latest config under the store lock.

To repair a file that has issues from a value that the user confirmed earlier, use store.replaceIfUnchanged(snapshot, value). snapshot must be a loadSync() result of a store for the same file; another object throws a TypeError. Under the lock, the store reads the file again and compares all its bytes with the bytes that snapshot read. A missing file matches only a missing file. If the file changed, the method throws Config at <path> changed since it was read; nothing was written. Read it again and retry. and does not change the file.

A load reads at most 64 KiB + 1 byte, and it does not open a FIFO in a way that blocks. Thus, a snapshot of a file that is larger than 64 KiB, unreadable, or not a regular file cannot prove the file contents. For such a snapshot, the method throws Config at <path> was not read completely (<reason>), so it cannot be replaced safely; nothing was written. Fix, shrink, or remove the file, then retry. and does not change the file.