dsh-health-readout

Declare where to read, what counts as healthy, and what each failure means — get one verdict.

A read-only dsh plugin. It composes readings that already exist (files, JSON endpoints, log tails) and returns a single verdict with per-reading detail. It never writes anything, never keeps state, and never becomes a source of truth.

{
  "readings": [{
    "id": "queue-depth",
    "title": "Queue depth is under the ceiling",
    "source":  { "kind": "json-field", "path": "status.json", "field": "queueDepth" },
    "healthy": { "op": "lt", "value": 8, "bad": "degraded" },
    "blind":   "A single sample: a queue that drains and refills between samples looks identical to a quiet one."
  }]
}

Three rules, built into the API

These are not style preferences. Each one is a bug we shipped somewhere before it became a rule, and here they are enforced by the type shapes and by tests rather than by good intentions:

1. "Cannot tell" is never zero. A source that cannot be read yields unknown — never ok, never 0, never false. unknown is always printed, and it moves the verdict on its own.
2. Every criterion must be able to fire. selftest: true feeds each declared criterion its own counter-example and reports any criterion that stayed green — a criterion nobody can falsify is decoration, and it is reported as such.
3. Every reading states its blind spot. blind is required. A reading whose limits are unstated reads like a reading whose limits do not exist.

Install

dsh plugin --profile <name> add dsh-health-readout      # npm
dsh plugin --profile <name> add ./dsh-health-readout-0.1.0.tgz
dsh plugin --profile <name> add <git-url>               # prebuilt: no build step, no postinstall

The package ships exactly the files that run (no build, no prepare script, no runtime dependencies), so a git install needs no build permission from the user.

Configure

Every value resolves in this order: the plugin row's config: block → environment variable → built-in default.

setting	config key	environment variable	default
where readings live	dataDir	DSH_HEALTH_READOUT_DATA_DIR	~/.dsh-health-readout
the declarations	specFile	DSH_HEALTH_READOUT_SPEC	readings.json (inside dataDir)
evaluate only some ids	only	DSH_HEALTH_READOUT_ONLY	all

The data directory is deliberately not a dsh platform directory. dsh may rebuild its own directories on upgrade; a user's readings must not be inside something that can be rebuilt out from under them. Point dataDir anywhere you control.

Relative paths inside the spec resolve against dataDir. ~ and ${dataDir} are expanded.

The spec

Copy examples/readings.example.json to <dataDir>/readings.json and edit it.

Source kinds

kind	reads	required fields
file-age-seconds	seconds since a file was written	path
file-size	bytes	path
file-exists	whether a path exists (false is knowledge, not ignorance)	path
json-field	a dotted path inside a JSON file	path, field
jsonl-last-field	a dotted path in the last parseable JSONL line (tail-read)	path, field, maxBytes?
text-count	regex matches in the last maxBytes of a file	path, pattern, maxBytes?, flags?
dir-count	files in a directory, optionally by suffix	path, suffix?
http-json-field	a dotted path in a JSON endpoint (always timed out)	url, field, timeoutMs?

Operators (healthy.op): lt lte gt gte eq neq between matches exists absent.

States (healthy.bad, default degraded), ordered by severity — the worst reading decides the verdict:

ok < notice < unknown < degraded < broken

unknown sits above notice on purpose: a readout that cannot see part of the world must not report a confident ok.

The tool

health_readout — one read-only call, two optional arguments:

• only — comma-separated reading ids to evaluate.
• selftest — also prove every declared criterion can go red.

The rendered output lists each reading with its value, its verdict, its reason and its blind spot, and prints the unreadable ones separately ("Could not read" is not "fine".).

Tests

node --test test/criteria.test.mjs test/sources.test.mjs test/spec.test.mjs test/readout.test.mjs

43 tests, no test framework and no fixtures on disk. The two arms worth knowing about: deleting a watched file must move the verdict to unknown (never leaving it at ok), and a deliberately unfalsifiable criterion (matches: ".*") must be reported as such by selftest.

Limitations (stated, not hidden)

• No cross-line folding. A reading is one value from one place. "How many records are still open" means folding several JSONL lines into a state, which is a query, not a reading. Point the spec at a file that already carries that number (a derived snapshot) and keep the fold in whatever produced it — this plugin composes readings, it does not become a query engine.
• No history. Every reading is one sample of the present. Trends need a recorder, and a recorder is a writer — out of scope for a readout.
• No changed-within operator. Comparing to a previous value requires state; see above.
• unknown is noisy by design. A missing file moves the verdict. That is the intended trade: silence about a blind spot is more expensive than a loud report about one.
• A spec may read any file the dsh process can read. That is the trust model: the user writes the spec, the user owns the paths.
• Host-only. No browser half, no settings UI; the verdict reaches the model as a tool result.

License

MIT.