Move docs/ package mirror into document-navigator plugin

Relocate the ~6k-file docs tree from the repo root into
plugins/document-navigator/docs/ so the plugin is self-contained and
portable. docs/superpowers/ (specs and plans) stays at the repo root.

Moved via cp+rm rather than git mv because directory rename() fails with
EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the
identical-content files at commit time.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-30 01:10:00 +01:00
parent fe3fedf42e
commit 9bf56a806b
6022 changed files with 12437 additions and 0 deletions

View File

@@ -0,0 +1,75 @@
# `options` — constructor option schema and defaults
<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose
This module owns the Zod schema and defaults for the scalar slice of
`createStdoutAuditSink({...})`'s input. Validation happens at the
boundary — a typo on `maxQueueMs` raises
`AUDIT_STDOUT.INVALID_OPTIONS` rather than silently being ignored.
The schema is `.strict()` so unknown keys are rejected (same rationale
as the `AuditRecord` schema).
The non-scalar slots — writer, clock, timers, logger, instruments,
hmacKey — bypass Zod and are checked structurally by the sink itself
at construction. Mixing the two validation styles keeps the typed
surface narrow while still rejecting obvious typos.
## Features
- Strict Zod schema for scalar option keys.
- Defaults: `maxQueueMs = 100`, `warnThrottleMs = 60_000`,
`sinkLabel = "stdout"`.
- Resolver wraps any `ZodError` as `AUDIT_STDOUT.INVALID_OPTIONS`.
- Constants exported so callers can reference them when computing
test throughput budgets.
## Usage: Basic
```ts
import { resolveStdoutAuditScalarOptions } from "@suaveplan/api-audit-stdout/options";
const resolved = resolveStdoutAuditScalarOptions({ maxQueueMs: 250 });
// resolved.warnThrottleMs === 60_000 (default)
```
## Usage: Advanced
```ts
import {
DEFAULT_MAX_QUEUE_MS,
resolveStdoutAuditScalarOptions,
type StdoutAuditScalarOptions,
} from "@suaveplan/api-audit-stdout/options";
function tightenedForTests(): StdoutAuditScalarOptions {
return {
maxQueueMs: Math.max(1, DEFAULT_MAX_QUEUE_MS / 10),
warnThrottleMs: 1_000,
};
}
const resolved = resolveStdoutAuditScalarOptions(tightenedForTests());
```
## API Reference
- `stdoutAuditScalarOptionsSchema` — strict Zod object.
- `StdoutAuditScalarOptions` — inferred type.
- `ResolvedStdoutAuditScalarOptions` — defaults-applied shape.
- `resolveStdoutAuditScalarOptions(raw)` — boundary parser.
- `DEFAULT_MAX_QUEUE_MS`, `DEFAULT_WARN_THROTTLE_MS` — constants.
## Implementation Notes
`maxQueueMs` is bounded to positive integers because a value of 0
would mean "never queue" — that's a different semantics (synchronous
backpressure) and would need its own option. `warnThrottleMs`
governs the once-per-window log; tests use a `FakeClock` plus a
short throttle to exercise the throttle without sleeping. The
`sinkLabel` exists so a future spinoff (e.g. journald) can reuse
this module while still attaching a distinct `sink="…"` label to its
counters.