crewhaus 0.1.8 → 0.2.1

package/dist/loadtest.js

@@ -0,0 +1,196 @@
+/**
+ * Item 68 — `crewhaus loadtest <spec>`: drive a daemon-shape harness (managed
+ * gateway / channel-bot / batch) under concurrent load and measure throughput,
+ * p50/p95/p99 latency, error rate, and cost/req — with a `--gate` mode that
+ * fails (exit 1) when p95 latency or error rate exceed declared thresholds (a
+ * pre-deploy gate).
+ *
+ * Load is driven through an INJECTED `LoadDriver` — one async call per request
+ * that returns a `RequestOutcome`. That seam makes the runner deterministic +
+ * credential-free in tests (a stub driver returns canned latencies), while the
+ * CLI wires a real driver: the managed gateway's in-process `handle()` behind a
+ * stub/echo model, or the batch queue's consumer. No live server or provider
+ * key is needed for the runner itself.
+ *
+ * Everything here is side-effect-free (the CLI entry file constructs the driver
+ * + writes the report). The aggregation is pure: same outcomes → same report.
+ */
+/** Thrown on bad flags / driver misuse. The CLI routes it through `die()`. */
+export class LoadtestError extends Error {
+    name = "LoadtestError";
+}
+const DEFAULT_CONCURRENCY = 10;
+const DEFAULT_REQUESTS = 100;
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    // Nearest-rank on a pre-sorted array.
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1));
+    return sorted[idx];
+}
+/**
+ * Run a concurrent load test against the injected driver. Dispatches up to
+ * `concurrency` requests in flight until the request budget (or duration) is
+ * exhausted, then drains. Deterministic given a deterministic driver + clock.
+ */
+export async function runLoadtest(driver, config = {}) {
+    const concurrency = Math.max(1, config.concurrency ?? DEFAULT_CONCURRENCY);
+    const maxRequests = config.requests ?? DEFAULT_REQUESTS;
+    if (maxRequests < 1)
+        throw new LoadtestError("requests must be ≥ 1");
+    const now = config.now ?? (() => performance.now());
+    const sleep = config.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const durationMs = config.durationMs;
+    const rps = config.rps;
+    const outcomes = [];
+    let dispatched = 0;
+    const startedAt = now();
+    const shouldStop = () => {
+        if (dispatched >= maxRequests)
+            return true;
+        if (durationMs !== undefined && now() - startedAt >= durationMs)
+            return true;
+        return false;
+    };
+    // Open-loop pacing: the interval between dispatches for the target rps.
+    const dispatchIntervalMs = rps !== undefined && rps > 0 ? 1000 / rps : 0;
+    async function worker() {
+        while (!shouldStop()) {
+            const idx = dispatched;
+            dispatched += 1;
+            if (dispatchIntervalMs > 0) {
+                // Pace dispatch toward the target rps. Each of the `concurrency` workers
+                // waits `concurrency / rps` seconds between its own dispatches, so the
+                // aggregate dispatch rate across all workers approximates `rps`.
+                await sleep(dispatchIntervalMs * concurrency);
+            }
+            let outcome;
+            try {
+                outcome = await driver(idx);
+            }
+            catch (err) {
+                outcome = {
+                    ok: false,
+                    latencyMs: 0,
+                    errorKind: err instanceof Error ? err.name || "threw" : "threw",
+                };
+            }
+            outcomes.push(outcome);
+        }
+    }
+    const workers = [];
+    for (let i = 0; i < concurrency; i++)
+        workers.push(worker());
+    await Promise.all(workers);
+    const wallClockMs = Math.max(0, now() - startedAt);
+    return aggregateLoadtest(outcomes, {
+        wallClockMs,
+        ...(config.pricePerMInput !== undefined ? { pricePerMInput: config.pricePerMInput } : {}),
+        ...(config.pricePerMOutput !== undefined ? { pricePerMOutput: config.pricePerMOutput } : {}),
+    });
+}
+/**
+ * Aggregate raw outcomes into a report. Pure — exported so tests can assert on
+ * percentile math without driving a run, and so the CLI can re-aggregate a
+ * persisted outcome set.
+ */
+export function aggregateLoadtest(outcomes, opts) {
+    const requests = outcomes.length;
+    const succeeded = outcomes.filter((o) => o.ok).length;
+    const failed = requests - succeeded;
+    // Latency percentiles over SUCCESSFUL requests (a failed 429 at 1ms would
+    // otherwise flatter the tail).
+    const latencies = outcomes
+        .filter((o) => o.ok)
+        .map((o) => o.latencyMs)
+        .sort((a, b) => a - b);
+    const sumLatency = latencies.reduce((acc, l) => acc + l, 0);
+    const tokens = outcomes.reduce((acc, o) => ({
+        input: acc.input + (o.tokens?.input ?? 0),
+        output: acc.output + (o.tokens?.output ?? 0),
+    }), { input: 0, output: 0 });
+    const errorKinds = {};
+    for (const o of outcomes) {
+        if (!o.ok) {
+            const kind = o.errorKind ?? "error";
+            errorKinds[kind] = (errorKinds[kind] ?? 0) + 1;
+        }
+    }
+    const priceIn = opts.pricePerMInput ?? 0;
+    const priceOut = opts.pricePerMOutput ?? 0;
+    const totalCostUsd = (tokens.input / 1_000_000) * priceIn + (tokens.output / 1_000_000) * priceOut;
+    return {
+        requests,
+        succeeded,
+        failed,
+        errorRate: requests === 0 ? 0 : failed / requests,
+        wallClockMs: opts.wallClockMs,
+        throughputRps: opts.wallClockMs > 0 ? (requests / opts.wallClockMs) * 1000 : 0,
+        latency: {
+            p50: percentile(latencies, 50),
+            p95: percentile(latencies, 95),
+            p99: percentile(latencies, 99),
+            min: latencies[0] ?? 0,
+            max: latencies[latencies.length - 1] ?? 0,
+            mean: latencies.length === 0 ? 0 : sumLatency / latencies.length,
+        },
+        tokens,
+        costPerReqUsd: requests === 0 ? 0 : totalCostUsd / requests,
+        totalCostUsd,
+        errorKinds,
+    };
+}
+/** Evaluate a report against gate thresholds. Empty thresholds → always passes. */
+export function evaluateGate(report, thresholds) {
+    const breaches = [];
+    if (thresholds.maxP95LatencyMs !== undefined && report.latency.p95 > thresholds.maxP95LatencyMs) {
+        breaches.push(`p95 latency ${report.latency.p95.toFixed(1)}ms > ${thresholds.maxP95LatencyMs}ms`);
+    }
+    if (thresholds.maxErrorRate !== undefined && report.errorRate > thresholds.maxErrorRate) {
+        breaches.push(`error rate ${(report.errorRate * 100).toFixed(1)}% > ${(thresholds.maxErrorRate * 100).toFixed(1)}%`);
+    }
+    return { passed: breaches.length === 0, breaches };
+}
+function fmtUsd(n) {
+    return `$${n.toFixed(6)}`;
+}
+/** Render a plain-text loadtest report. */
+export function renderLoadtestText(report, verdict) {
+    const lines = [];
+    lines.push("loadtest:");
+    lines.push(`  requests:    ${report.requests} (${report.succeeded} ok / ${report.failed} failed, ${(report.errorRate * 100).toFixed(1)}% error rate)`);
+    lines.push(`  throughput:  ${report.throughputRps.toFixed(1)} req/s over ${report.wallClockMs.toFixed(0)}ms`);
+    lines.push(`  latency:     p50 ${report.latency.p50.toFixed(1)}ms · p95 ${report.latency.p95.toFixed(1)}ms · p99 ${report.latency.p99.toFixed(1)}ms (min ${report.latency.min.toFixed(1)} / max ${report.latency.max.toFixed(1)})`);
+    lines.push(`  tokens:      ${report.tokens.input} in / ${report.tokens.output} out; cost/req ${fmtUsd(report.costPerReqUsd)}; total ${fmtUsd(report.totalCostUsd)}`);
+    const kinds = Object.entries(report.errorKinds);
+    if (kinds.length > 0) {
+        lines.push(`  errors:      ${kinds.map(([k, v]) => `${k}×${v}`).join(", ")}`);
+    }
+    if (verdict !== undefined) {
+        lines.push(verdict.passed ? "  gate:        PASS" : "  gate:        FAIL");
+        for (const b of verdict.breaches)
+            lines.push(`    ! ${b}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Render an HTML loadtest report (self-contained). */
+export function renderLoadtestHtml(report, verdict) {
+    const gateRow = verdict === undefined
+        ? ""
+        : `<tr><th>Gate</th><td>${verdict.passed ? "PASS" : `FAIL — ${verdict.breaches.map((b) => b.replace(/</g, "&lt;")).join("; ")}`}</td></tr>`;
+    return `<!doctype html>
+<html><head><meta charset="utf-8"><title>Loadtest report</title>
+<style>body{font:14px system-ui,sans-serif;margin:2rem}table{border-collapse:collapse}th,td{border:1px solid #ddd;padding:.4rem .7rem;text-align:left}th{background:#f5f5f5}</style>
+</head><body>
+<h1>Loadtest report</h1>
+<table>
+<tr><th>Requests</th><td>${report.requests} (${report.succeeded} ok / ${report.failed} failed)</td></tr>
+<tr><th>Error rate</th><td>${(report.errorRate * 100).toFixed(1)}%</td></tr>
+<tr><th>Throughput</th><td>${report.throughputRps.toFixed(1)} req/s</td></tr>
+<tr><th>Latency p50 / p95 / p99</th><td>${report.latency.p50.toFixed(1)} / ${report.latency.p95.toFixed(1)} / ${report.latency.p99.toFixed(1)} ms</td></tr>
+<tr><th>Cost / req</th><td>${fmtUsd(report.costPerReqUsd)}</td></tr>
+${gateRow}
+</table>
+</body></html>
+`;
+}

package/dist/marketplace-cli.d.ts

@@ -0,0 +1,110 @@
+import type { ModuleRegistrySource, PluginMetadata } from "@crewhaus/module-marketplace-client";
+import type { PluginRegistryEntry } from "@crewhaus/plugin-registry";
+import type { PluginManifest } from "@crewhaus/plugin-sdk";
+/** Thrown for operational failures (no registry configured, bad ref, driver
+ *  failure). The CLI routes the message through `die()`; tests assert on
+ *  `.message`. */
+export declare class MarketplaceCliError extends Error {
+    readonly name = "MarketplaceCliError";
+}
+/** Where installed plugins live (mirrors §41 trustedRoots). */
+export declare function defaultPluginsDir(): string;
+/** The plugin-registry install-record file. */
+export declare function defaultPluginRegistryPath(): string;
+/** Where `templates use` writes the fetched template. Defaults to the cwd
+ *  (a template is scaffolded into the working directory). */
+export declare function defaultTemplateWorkspaceDir(): string;
+export type RegistryRefKind = {
+    readonly kind: "local";
+    readonly dir: string;
+} | {
+    readonly kind: "http";
+    readonly baseUrl: string;
+};
+/**
+ * Resolve a registry ref string into a backend descriptor. `http(s)://…` →
+ * HTTP; anything else is a filesystem path (a leading `file:` is stripped).
+ * `undefined` (nothing configured) throws so a read verb fails loudly instead
+ * of silently hitting nothing.
+ */
+export declare function resolveRegistryRef(ref: string | undefined, kindLabel: string): RegistryRefKind;
+/**
+ * A `ModuleRegistrySource` over an HTTP JSON index. The catalog is
+ * `GET <baseUrl>` returning `{ plugins: PluginMetadata[] }`; a manifest is
+ * `GET <baseUrl>/<name>.json` (optionally `<name>@<version>.json`). `fetch`
+ * is injected so tests drive it without a network.
+ */
+export declare function createHttpModuleRegistrySource(opts: {
+    readonly id: string;
+    readonly baseUrl: string;
+    readonly fetchImpl?: typeof fetch;
+}): ModuleRegistrySource;
+/**
+ * A LOCAL `ModuleRegistrySource` over a directory of plugin manifest JSONs
+ * (`<name>.json`). Mirrors template-registry's `LocalRegistrySource`; used
+ * for `--registry <dir>` and by tests. Reads go through injected fs seams so
+ * this stays unit-testable.
+ */
+export declare function createLocalModuleRegistrySource(opts: {
+    readonly dir: string;
+    readonly readdirImpl: (dir: string) => ReadonlyArray<string>;
+    readonly readFileImpl: (path: string) => string;
+    readonly existsImpl: (path: string) => boolean;
+}): ModuleRegistrySource;
+/** Project a full manifest down to the search metadata shape. */
+export declare function toMetadata(m: PluginManifest): PluginMetadata;
+/** Compare two `major.minor.patch` cores; pre-release/build ignored (matches
+ *  module-marketplace-client's own `compareSemver`). */
+export declare function compareSemverCore(a: string, b: string): number;
+export type OutdatedRow = {
+    readonly name: string;
+    readonly installed: string;
+    readonly latest?: string;
+    /** "outdated" | "current" | "unknown" (not in the remote registry). */
+    readonly status: "outdated" | "current" | "unknown";
+};
+/**
+ * Compute the freshness report: for each installed plugin, its installed
+ * version vs the remote latest. `unknown` when the plugin is not in the
+ * remote catalog (a private/local install). Pure over the two lists.
+ */
+export declare function computeOutdated(installed: ReadonlyArray<{
+    readonly name: string;
+    readonly version: string;
+}>, remote: ReadonlyArray<PluginMetadata>): OutdatedRow[];
+/** The installed (name, version) pairs from plugin-registry entries. */
+export declare function installedVersions(entries: ReadonlyArray<PluginRegistryEntry>): Array<{
+    name: string;
+    version: string;
+}>;
+export declare function formatPluginList(rows: ReadonlyArray<PluginMetadata>): ReadonlyArray<string>;
+export declare function formatOutdated(rows: ReadonlyArray<OutdatedRow>): ReadonlyArray<string>;
+/** The minimal PublishDraft fields the publish loop needs (structurally
+ *  satisfied by BOTH marketplace clients' PublishDraft shapes). */
+export type PublishDraftLike = {
+    readonly prTitle: string;
+    readonly prBody: string;
+    /** repo-relative path the manifest is written to on the branch. */
+    readonly manifestRelPath: string;
+    /** the manifest bytes to write. */
+    readonly manifestContents: string;
+    readonly name: string;
+    readonly version: string;
+};
+/** The write-and-open plan the driver executes for a publish. */
+export type PublishPrPlan = {
+    readonly branch: string;
+    readonly title: string;
+    readonly body: string;
+    readonly files: Readonly<Record<string, string>>;
+    readonly commitMessage: string;
+};
+/** Assemble the publish PR plan from a draft. Pure. */
+export declare function buildPublishPrPlan(draft: PublishDraftLike, now: Date): PublishPrPlan;
+/** Driver seam: execute a `PublishPrPlan` (branch → write → commit → push →
+ *  `gh pr create`). CLI wires git/gh; tests inject a stub. NEVER auto-merges. */
+export type PublishPrDriver = (plan: PublishPrPlan) => Promise<{
+    readonly prNumber?: number;
+    readonly url: string;
+    readonly branch: string;
+}>;

package/dist/marketplace-cli.js

@@ -0,0 +1,250 @@
+/**
+ * Item 60 — the marketplace CLI: `crewhaus plugins {list,search,install,
+ * uninstall,publish,outdated}` and `crewhaus templates {list,search,use}`.
+ * These verbs were the explicitly-deferred CLI surface on top of the §42
+ * `module-marketplace-client` / §40 `template-marketplace-client` (their
+ * docstrings name "the CLI follow-up" as the secondary consumer); this
+ * closes them, plus the publish loop and a dependency-freshness watch.
+ *
+ * Factored out of the entry file `index.ts` (which runs a top-level argv
+ * switch and so cannot be imported by a test without executing the CLI).
+ * Side-effect-free on import, mirroring `datasets.ts` / `retention.ts`:
+ *   - the registry-source construction + the marketplace clients are the only
+ *     I/O, and they route network through an injectable `fetch` seam so
+ *     `list`/`search`/`install`/`outdated` are tested against a seeded LOCAL
+ *     registry or a mocked HTTP source with no real network;
+ *   - the `outdated` comparison and the report formatters are pure;
+ *   - the publish loop drives `gh` behind an injected driver seam.
+ *
+ * REGISTRY RESOLUTION — a `--registry <ref>` flag, else
+ * `CREWHAUS_PLUGIN_REGISTRY` / `CREWHAUS_TEMPLATE_REGISTRY`, selects the
+ * backend:
+ *   - a filesystem path (or `file:<path>`) → a LOCAL source (a directory of
+ *     manifest JSONs — the same on-disk shape the registries write);
+ *   - an `http(s)://` URL → an HTTP source (a `{plugins:[]}` / `{templates:[]}`
+ *     JSON index at `<url>` + per-name manifests at `<url>/<name>.json`).
+ * With nothing configured, the read verbs report "no registry configured"
+ * rather than reaching for a hardcoded endpoint.
+ *
+ * SIGNING — install respects `plugin-registry`'s fail-closed verification:
+ * when trust anchors are configured (via `--trust-anchor` / env), an unsigned
+ * or badly-signed plugin is refused; `--allow-unsigned` is the explicit dev
+ * opt-out. Templates carry their own `verifyingRegistry` wrapper (out of scope
+ * here — install fetches the manifest verbatim).
+ */
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+/** Thrown for operational failures (no registry configured, bad ref, driver
+ *  failure). The CLI routes the message through `die()`; tests assert on
+ *  `.message`. */
+export class MarketplaceCliError extends Error {
+    name = "MarketplaceCliError";
+}
+// ---------------------------------------------------------------------------
+// default locations
+// ---------------------------------------------------------------------------
+/** Where installed plugins live (mirrors §41 trustedRoots). */
+export function defaultPluginsDir() {
+    return join(homedir(), ".crewhaus", "plugins");
+}
+/** The plugin-registry install-record file. */
+export function defaultPluginRegistryPath() {
+    return join(homedir(), ".crewhaus", "plugin-registry.json");
+}
+/** Where `templates use` writes the fetched template. Defaults to the cwd
+ *  (a template is scaffolded into the working directory). */
+export function defaultTemplateWorkspaceDir() {
+    return process.cwd();
+}
+/**
+ * Resolve a registry ref string into a backend descriptor. `http(s)://…` →
+ * HTTP; anything else is a filesystem path (a leading `file:` is stripped).
+ * `undefined` (nothing configured) throws so a read verb fails loudly instead
+ * of silently hitting nothing.
+ */
+export function resolveRegistryRef(ref, kindLabel) {
+    if (ref === undefined || ref === "") {
+        throw new MarketplaceCliError(`no ${kindLabel} registry configured — pass --registry <dir|url> or set the CREWHAUS_${kindLabel.toUpperCase()}_REGISTRY env var (a directory of manifest JSONs, or an http(s):// index URL)`);
+    }
+    if (/^https?:\/\//.test(ref))
+        return { kind: "http", baseUrl: ref.replace(/\/$/, "") };
+    const path = ref.startsWith("file:") ? ref.slice("file:".length) : ref;
+    return { kind: "local", dir: isAbsolute(path) ? path : resolve(process.cwd(), path) };
+}
+// ---------------------------------------------------------------------------
+// HTTP-backed ModuleRegistrySource (plugins)
+// ---------------------------------------------------------------------------
+/**
+ * A `ModuleRegistrySource` over an HTTP JSON index. The catalog is
+ * `GET <baseUrl>` returning `{ plugins: PluginMetadata[] }`; a manifest is
+ * `GET <baseUrl>/<name>.json` (optionally `<name>@<version>.json`). `fetch`
+ * is injected so tests drive it without a network.
+ */
+export function createHttpModuleRegistrySource(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const base = opts.baseUrl.replace(/\/$/, "");
+    return {
+        id: opts.id,
+        async listPlugins() {
+            const res = await fetchImpl(base);
+            if (!res.ok) {
+                throw new MarketplaceCliError(`plugin registry list ${res.status}: ${(await res.text()).slice(0, 256)}`);
+            }
+            const data = (await res.json());
+            if (!Array.isArray(data?.plugins)) {
+                throw new MarketplaceCliError("plugin registry list payload missing plugins[]");
+            }
+            return data.plugins;
+        },
+        async getManifest(name, version) {
+            const suffix = version !== undefined ? `${name}@${version}` : name;
+            const res = await fetchImpl(`${base}/${suffix}.json`);
+            if (!res.ok) {
+                throw new MarketplaceCliError(`plugin registry fetch "${suffix}" ${res.status}: ${(await res.text()).slice(0, 256)}`);
+            }
+            return (await res.json());
+        },
+    };
+}
+/**
+ * A LOCAL `ModuleRegistrySource` over a directory of plugin manifest JSONs
+ * (`<name>.json`). Mirrors template-registry's `LocalRegistrySource`; used
+ * for `--registry <dir>` and by tests. Reads go through injected fs seams so
+ * this stays unit-testable.
+ */
+export function createLocalModuleRegistrySource(opts) {
+    const manifestPath = (name, version) => join(opts.dir, `${version !== undefined ? `${name}@${version}` : name}.json`);
+    return {
+        id: `local:${opts.dir}`,
+        async listPlugins() {
+            if (!opts.existsImpl(opts.dir))
+                return [];
+            const out = [];
+            for (const f of opts.readdirImpl(opts.dir)) {
+                if (!f.endsWith(".json") || f.includes("@"))
+                    continue;
+                try {
+                    const m = JSON.parse(opts.readFileImpl(join(opts.dir, f)));
+                    out.push(toMetadata(m));
+                }
+                catch {
+                    // skip malformed
+                }
+            }
+            return out.sort((a, b) => a.name.localeCompare(b.name));
+        },
+        async getManifest(name, version) {
+            const versioned = manifestPath(name, version);
+            const path = version !== undefined && opts.existsImpl(versioned) ? versioned : manifestPath(name);
+            if (!opts.existsImpl(path)) {
+                throw new MarketplaceCliError(`plugin "${name}" not found in ${opts.dir}`);
+            }
+            return JSON.parse(opts.readFileImpl(path));
+        },
+    };
+}
+/** Project a full manifest down to the search metadata shape. */
+export function toMetadata(m) {
+    const rec = m;
+    return {
+        name: m.name,
+        version: m.version,
+        ...(typeof rec["description"] === "string" ? { description: rec["description"] } : {}),
+        ...(typeof rec["author"] === "string" ? { author: rec["author"] } : {}),
+        ...(typeof rec["homepage"] === "string" ? { homepage: rec["homepage"] } : {}),
+        ...(typeof rec["license"] === "string" ? { license: rec["license"] } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// outdated (dependency-freshness watch)
+// ---------------------------------------------------------------------------
+/** Compare two `major.minor.patch` cores; pre-release/build ignored (matches
+ *  module-marketplace-client's own `compareSemver`). */
+export function compareSemverCore(a, b) {
+    const core = (v) => (v.split("-")[0] ?? "").split(".").map((n) => Number.parseInt(n, 10) || 0);
+    const aN = core(a);
+    const bN = core(b);
+    for (let i = 0; i < 3; i++) {
+        const ai = aN[i] ?? 0;
+        const bi = bN[i] ?? 0;
+        if (ai !== bi)
+            return ai - bi;
+    }
+    return 0;
+}
+/**
+ * Compute the freshness report: for each installed plugin, its installed
+ * version vs the remote latest. `unknown` when the plugin is not in the
+ * remote catalog (a private/local install). Pure over the two lists.
+ */
+export function computeOutdated(installed, remote) {
+    const latestByName = new Map();
+    for (const p of remote) {
+        const prev = latestByName.get(p.name);
+        if (prev === undefined || compareSemverCore(p.version, prev) > 0) {
+            latestByName.set(p.name, p.version);
+        }
+    }
+    const rows = [];
+    for (const inst of installed) {
+        const latest = latestByName.get(inst.name);
+        if (latest === undefined) {
+            rows.push({ name: inst.name, installed: inst.version, status: "unknown" });
+            continue;
+        }
+        const status = compareSemverCore(latest, inst.version) > 0 ? "outdated" : "current";
+        rows.push({ name: inst.name, installed: inst.version, latest, status });
+    }
+    return rows.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** The installed (name, version) pairs from plugin-registry entries. */
+export function installedVersions(entries) {
+    return entries.map((e) => ({
+        name: e.manifest.name,
+        version: e.pinnedVersion ?? e.manifest.version,
+    }));
+}
+// ---------------------------------------------------------------------------
+// formatters (pure)
+// ---------------------------------------------------------------------------
+export function formatPluginList(rows) {
+    if (rows.length === 0)
+        return ["no plugins in the registry"];
+    return rows.map((p) => `${p.name}@${p.version}${p.author !== undefined ? ` — ${p.author}` : ""}${p.description !== undefined ? `\n    ${p.description}` : ""}`);
+}
+export function formatOutdated(rows) {
+    if (rows.length === 0)
+        return ["no plugins installed"];
+    const lines = [];
+    let outdated = 0;
+    for (const r of rows) {
+        if (r.status === "outdated") {
+            outdated += 1;
+            lines.push(`⤴ ${r.name}: ${r.installed} → ${r.latest} (update available)`);
+        }
+        else if (r.status === "current") {
+            lines.push(`✓ ${r.name}: ${r.installed} (current)`);
+        }
+        else {
+            lines.push(`? ${r.name}: ${r.installed} (not in the configured registry)`);
+        }
+    }
+    lines.push("");
+    lines.push(outdated === 0
+        ? "summary: all installed plugins current"
+        : `summary: ${outdated} update(s) available`);
+    return lines;
+}
+/** Assemble the publish PR plan from a draft. Pure. */
+export function buildPublishPrPlan(draft, now) {
+    const slug = draft.name.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+    const stamp = now.toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    const branch = `publish/${slug || "plugin"}-${draft.version}-${stamp}`;
+    return {
+        branch,
+        title: draft.prTitle,
+        body: draft.prBody,
+        files: { [draft.manifestRelPath]: draft.manifestContents },
+        commitMessage: `publish(${draft.name}): ${draft.version}`,
+    };
+}

package/dist/mcp-doctor.d.ts

@@ -0,0 +1,121 @@
+/**
+ * F5 — sanitise an mcp_servers KEY into a single safe filename segment before it
+ * is joined onto `.crewhaus/mcp/` (the drift-snapshot write). The mcp_servers
+ * key schema is `z.string().min(1)` (NOT `safeName`), so a server named
+ * `../../evil` — or one carrying a slash / NUL — would let
+ * `join(mcpDir, `${name}.json`)` escape the directory. We `basename` to strip
+ * path components, then replace every character outside the conservative
+ * `[A-Za-z0-9._-]` set with `_` (the same class the eval-runner + graders use),
+ * and floor an empty / dot-only result to a stable placeholder. The result is
+ * always a bare filename that stays inside the snapshot dir.
+ */
+export declare function safeMcpFileName(name: string): string;
+/** One durable `mcp_stats` record's payload (what runtime-core persists). */
+export type McpStatsPayload = {
+    readonly server: string;
+    readonly toolName: string;
+    readonly durationMs: number;
+    readonly isError: boolean;
+};
+/** Per-server rolled-up health over the scored session window. */
+export type McpServerHealth = {
+    readonly server: string;
+    readonly calls: number;
+    readonly errors: number;
+    readonly errorRate: number;
+    /** p50 / p95 call latency, ms (nearest-rank). */
+    readonly p50Ms: number;
+    readonly p95Ms: number;
+    /** Longest run of CONSECUTIVE erroring calls — a reconnect-churn proxy, since
+     *  the mcp client's reconnect events are Logger-only (not durable). */
+    readonly maxErrorStreak: number;
+    /** True when the server is chronically failing (see {@link QUARANTINE_POLICY}). */
+    readonly chronic: boolean;
+};
+/** Thresholds a server must cross to be judged chronically failing → quarantine
+ *  candidate. Kept together so the report and the quarantine decision agree. */
+export declare const QUARANTINE_POLICY: {
+    /** Minimum calls before an error rate is trustworthy (cold-start guard). */
+    readonly minCalls: 5;
+    /** Error-rate ceiling; above it (with enough calls) the server is chronic. */
+    readonly errorRate: 0.5;
+    /** OR: this many consecutive errors is chronic regardless of overall rate
+     *  (a server that just went hard-down mid-session). */
+    readonly errorStreak: 4;
+};
+/** Nearest-rank percentile (0-based floor). Empty ⇒ 0. */
+export declare function percentile(values: ReadonlyArray<number>, p: number): number;
+/**
+ * Fold a flat stream of `mcp_stats` payloads (already read from session logs,
+ * oldest-first) into per-server health. The `maxErrorStreak` is computed over
+ * the input order, so callers should pass records in chronological order (the
+ * session-log reader yields insertion order — which is chronological).
+ */
+export declare function scoreMcpHealth(records: ReadonlyArray<McpStatsPayload>): McpServerHealth[];
+/** Chronic-failure verdict shared by scoring + quarantine decision. */
+export declare function isChronic(calls: number, errorRate: number, maxErrorStreak: number): boolean;
+/** A single tool as advertised by a server, for drift snapshotting. */
+export type McpToolSnapshot = {
+    readonly name: string;
+    /** Stable hash of the tool's JSON-schema (order-insensitive). */
+    readonly schemaHash: string;
+};
+/** The on-disk drift snapshot for one server (`.crewhaus/mcp/<server>.json`). */
+export type McpServerSnapshot = {
+    readonly version: 1;
+    readonly server: string;
+    readonly ts: string;
+    readonly tools: ReadonlyArray<McpToolSnapshot>;
+};
+/**
+ * Stable hash of a JSON-schema value: recursively sort object keys so
+ * `{a,b}` and `{b,a}` hash identically, then sha256 the canonical form. A
+ * server that reorders its schema keys between connects is NOT drift; a server
+ * that changes a field's type IS. Returns the first 16 hex chars (collision-
+ * safe enough for a per-tool change signal).
+ */
+export declare function schemaHash(schema: unknown): string;
+/** Build a fresh snapshot from a server's live `listTools` result. */
+export declare function buildSnapshot(server: string, tools: ReadonlyArray<{
+    readonly name: string;
+    readonly inputSchema: unknown;
+}>, ts: string): McpServerSnapshot;
+export type McpDrift = {
+    readonly added: ReadonlyArray<string>;
+    readonly removed: ReadonlyArray<string>;
+    /** Tools present in both but whose schema hash changed. */
+    readonly schemaChanged: ReadonlyArray<string>;
+};
+/** True when nothing changed. */
+export declare function driftIsEmpty(drift: McpDrift): boolean;
+/**
+ * Diff a previous snapshot against the current one. `previous` undefined (no
+ * snapshot on disk yet) ⇒ empty drift (the current becomes the new baseline;
+ * a first-ever connect is not "drift"). Added = in current not previous;
+ * removed = in previous not current; schemaChanged = in both, different hash.
+ */
+export declare function diffSnapshots(previous: McpServerSnapshot | undefined, current: McpServerSnapshot): McpDrift;
+export type QuarantineDecision = {
+    /** Servers whose tools should be WITHDRAWN (chronic + not already out). */
+    readonly quarantine: ReadonlyArray<string>;
+    /** Servers whose tools should be RESTORED (were out, now healthy). */
+    readonly restore: ReadonlyArray<string>;
+};
+/**
+ * Decide catalog mutations from the current health + the set of servers whose
+ * tools are ALREADY quarantined. A chronic server not yet quarantined →
+ * quarantine; a quarantined server that is no longer chronic (its recent
+ * window is healthy — e.g. a probe succeeded) → restore. A server absent from
+ * `health` entirely (no recent calls) is left as-is: no signal either way.
+ */
+export declare function decideQuarantine(health: ReadonlyArray<McpServerHealth>, alreadyQuarantined: ReadonlyArray<string>): QuarantineDecision;
+/**
+ * The synthetic notice injected in place of a quarantined server's tools so the
+ * model routes around them — mirrors loop-detection's warning injection. Kept
+ * here so the report and the runtime injection render the identical text.
+ */
+export declare function quarantineNotice(server: string, reason: string): string;
+/** Render the per-server health table lines for `crewhaus mcp doctor`. */
+export declare function formatHealthReport(health: ReadonlyArray<McpServerHealth>): string[];
+/** Render the drift lines for one server. Empty array when no drift. */
+export declare function formatDriftReport(server: string, drift: McpDrift): string[];