@tpsdev-ai/flair 0.21.0 → 0.22.1

package/dist/deploy.js

@@ -8,7 +8,6 @@ import { createRequire } from "node:module";
 export const REQUIRED_PACKAGE_FILES = [
     "dist",
     "schemas",
-    "ui",
     "config.yaml",
 ];
 // harper's own deploy CLI defaults to a 120s peer-replication timeout that's
@@ -39,9 +38,9 @@ export function validateOptions(opts) {
     const hasBasic = !!(opts.fabricUser && opts.fabricPassword);
     const hasBearer = !!opts.fabricToken;
     if (!hasBasic && !hasBearer) {
-        errors.push("credentials required: pass --fabric-user + --fabric-password " +
-            "(or FABRIC_USER / FABRIC_PASSWORD env), or --fabric-token " +
-            "(FABRIC_TOKEN env)");
+        errors.push("credentials required: set FABRIC_USER + FABRIC_PASSWORD env (safest), or pass " +
+            "--fabric-user + --fabric-password-file <path>, or --fabric-token (FABRIC_TOKEN env); " +
+            "inline --fabric-user/--fabric-password also work but leak to shell history");
     }
     return errors;
 }

package/dist/fleet-presence.js

@@ -0,0 +1,98 @@
+// ─── Doctor: fleet presence / instance staleness (flair#639) ────────────────────
+//
+// `flair doctor` diagnosed a single instance only. Auto-presence (flair#608)
+// gives every agent a heartbeat, and each heartbeat now carries the SERVING
+// instance's own flair + harper version (resources/Presence.ts,
+// buildPresenceRecord()) — so the /Presence roster doubles as an org-level
+// fleet-version report, IF something reads it that way. This module is that
+// reading: pure classification over an already-fetched roster, no network,
+// no crypto, so it's fast and fully unit-testable in isolation — same split
+// as doctor-client.ts (pure logic here; the network fetch + Ed25519 signing
+// stay in src/cli.ts alongside authFetch/buildEd25519Auth, which they reuse).
+//
+// Deliberately NOT npm-latest aware: comparing against the newest version
+// PUBLISHED is version-nudge's job (src/version-check.ts, flair#587/#594).
+// This is comparing instances against EACH OTHER — "is anyone behind the
+// rest of the fleet" — which stays meaningful even fully offline, and is the
+// question flair#639 actually asks: an org-level answer without probing
+// every host by hand.
+//
+// Semver comparison reuses fabric-upgrade.ts's parseSemverCore/semverGte
+// (major.minor.patch only, pre-release/build suffixes ignored) — the one
+// semver implementation in this codebase; duplicating it here would risk the
+// two drifting on an edge case.
+import { parseSemverCore, semverGte } from "./fabric-upgrade.js";
+/** True only for a non-empty, parseable semver string — the one predicate every
+ *  function below needs, so it lives in exactly one place. */
+function hasParsableVersion(v) {
+    return typeof v === "string" && parseSemverCore(v) !== null;
+}
+/**
+ * Newest flairVersion seen across the roster. Entries with no (or an
+ * unparseable) version are excluded from the computation — an unversioned
+ * record can't be compared, so it can't set the bar. Returns null when NO
+ * entry in the roster reports a parseable version (nothing to compare
+ * against — e.g. a fleet that's entirely pre-flair#639, or a roster with a
+ * single unversioned instance).
+ */
+export function newestVersionSeen(rows) {
+    let newest = null;
+    for (const row of rows) {
+        if (!hasParsableVersion(row.flairVersion))
+            continue;
+        if (newest === null || semverGte(row.flairVersion, newest))
+            newest = row.flairVersion;
+    }
+    return newest;
+}
+/**
+ * Flag each roster row as stale relative to the newest flairVersion seen
+ * ACROSS THE WHOLE ROSTER (never against npm-latest — see module doc). A row
+ * is stale when:
+ *   - the roster has SOME newest version to compare against (newest !== null)
+ *     AND
+ *   - this row has no parseable version of its own (an older, pre-flair#639
+ *     instance — the loudest possible skew signal), OR its version is older
+ *     than the newest seen.
+ *
+ * A single-instance roster, or a roster where every instance reports the
+ * IDENTICAL version, has nothing to compare against → newest equals every
+ * row's own version (or is null) → nothing is flagged stale. A roster where
+ * NO instance has ever reported a version (newest === null) similarly flags
+ * nothing — there's no fleet-relative signal yet, only an org-wide gap this
+ * function can't see (that's what the "pass --agent to reveal versions" /
+ * "no versions reported yet" doctor messaging is for, not staleness).
+ */
+export function markStale(rows) {
+    const newest = newestVersionSeen(rows);
+    return rows.map((row) => {
+        const stale = newest !== null && (!hasParsableVersion(row.flairVersion) || !semverGte(row.flairVersion, newest));
+        return { ...row, stale, newestVersion: newest };
+    });
+}
+/**
+ * Sort oldest-version-first so problems top the listing (flair#639's stated
+ * requirement). Rows with no parseable version sort FIRST — an unversioned
+ * instance is the biggest unknown in the fleet, not a middling one, and
+ * markStale() always flags it stale whenever the roster has any signal at
+ * all, so surfacing it first keeps the "problems on top" contract even when
+ * mixed with real-but-old versions. Ties (equal versions) preserve roster
+ * order (stable sort).
+ */
+export function sortOldestVersionFirst(rows) {
+    return [...rows].sort((a, b) => {
+        const pa = hasParsableVersion(a.flairVersion) ? parseSemverCore(a.flairVersion) : null;
+        const pb = hasParsableVersion(b.flairVersion) ? parseSemverCore(b.flairVersion) : null;
+        if (!pa && !pb)
+            return 0;
+        if (!pa)
+            return -1;
+        if (!pb)
+            return 1;
+        for (let i = 0; i < 3; i++) {
+            if (pa[i] !== pb[i])
+                return pa[i] - pb[i];
+        }
+        return 0;
+    });
+}

package/dist/fleet-verify.js

@@ -0,0 +1,291 @@
+/**
+ * fleet-verify.ts — `flair fleet verify` (flair#636)
+ *
+ * Fabric deploys tolerate replication errors by design (origin-first, see
+ * src/deploy.ts's REPLICATION_FAILURE_RE / --ignore-replication-errors) —
+ * but nothing upstream of this module confirms a replicated node actually
+ * converged. Harper's own "Successfully deployed" means "origin took it."
+ * This sweeps the origin + every known peer and reports a per-node table
+ * instead of a single boolean, reusing src/probe.ts's `probeInstance`
+ * verbatim (flair#635/#641 — same shape, Fabric admin Basic auth swapped in
+ * for the injected `authedGet`, exactly per that module's own docstring).
+ *
+ * ── What "peer" means here — read before trusting a green sweep ──────────
+ * Harper Fabric's OWN cluster-replication peers (the physical nodes a
+ * component gets replicated to by `harper deploy`) are NOT enumerable
+ * through any operation in the OSS @harperfast/harper build this repo
+ * depends on. `cluster_status` — the operation that would answer "what
+ * nodes are in this cluster and are they in sync" — is explicitly called
+ * out as harper-pro-only in Harper's own source (node_modules/@harperfast/
+ * harper/components/mcp/tools/schemas/operationDescriptions.ts: "Out-of-core
+ * operations (e.g. harper-pro's cluster_status) cannot have entries here").
+ * There is no "list this cluster's replication nodes" call available to this
+ * CLI, on the origin or anywhere else — direct AND via-origin cluster
+ * topology discovery are both unavailable in this Harper tier.
+ *
+ * The only node registry this module CAN reach is Flair's OWN federation
+ * peer table (resources/Federation.ts's Peer records, via GET
+ * /FederationPeers) — a distinct, higher-level concept (cross-instance
+ * memory-sync pairing, hub-and-spoke) that happens to double as a fleet
+ * registry ONLY where an operator has ALSO paired each Fabric replica as a
+ * federation peer of the origin. A replica that was never paired is
+ * invisible to this sweep — `0 peers known` means "0 peers ON FILE", never
+ * "0 peers exist." renderFleetSweepTable() prints this caveat inline
+ * whenever the peer list comes back empty, so it can't be missed by reading
+ * a green summary line.
+ *
+ * Every peer that DOES carry a direct `endpoint` gets a REAL probe (health +
+ * authenticated version check, same Fabric admin Basic-auth credentials as
+ * the origin — a Fabric cluster shares one admin realm). A peer with no
+ * usable endpoint is reported "unverifiable" — never silently dropped, never
+ * printed green. See classifyNode()'s "method" field: "direct" (we actually
+ * hit it) vs "none" (we could not attempt a check at all, and say why).
+ */
+import { probeInstance } from "./probe.js";
+import * as render from "./render.js";
+// ─── Exit codes (documented in `flair fleet verify --help`) ─────────────────
+/** All nodes verified: healthy, authenticated, and version-matched. */
+export const FLEET_EXIT_OK = 0;
+/** Origin failed — unreachable, unauthenticated, or running the wrong version. Worst case: the cluster's entrypoint itself is broken. */
+export const FLEET_EXIT_ORIGIN_FAILED = 1;
+/** Origin is fine, but at least one reachable peer is running a DIFFERENT version — a mixed-version fleet (the #638 scenario). */
+export const FLEET_EXIT_PEER_SKEW = 2;
+/** Origin is fine, no version skew among reachable peers, but at least one peer could not be verified at all (unreachable, auth rejected, or no endpoint on file). */
+export const FLEET_EXIT_PEER_UNREACHABLE = 3;
+export const FLEET_EXIT_DESCRIPTIONS = {
+    [FLEET_EXIT_OK]: "all nodes verified: healthy, authenticated, version-matched",
+    [FLEET_EXIT_ORIGIN_FAILED]: "origin failed (unreachable, unauthenticated, or wrong version)",
+    [FLEET_EXIT_PEER_SKEW]: "origin OK, but a reachable peer is running a DIFFERENT version (skew)",
+    [FLEET_EXIT_PEER_UNREACHABLE]: "origin OK, no skew among reachable peers, but a peer could not be verified at all (unreachable, auth rejected, or no endpoint on file)",
+};
+/**
+ * Priority order when multiple problems exist at once: an origin failure
+ * always wins (nothing downstream matters if the entrypoint is broken), then
+ * skew (a real mixed-version fleet), then unreachable/unverifiable (we
+ * genuinely don't know that node's state).
+ */
+export function decideFleetExitCode(origin, peers) {
+    if (origin.status !== "ok")
+        return FLEET_EXIT_ORIGIN_FAILED;
+    if (peers.some((p) => p.status === "skew"))
+        return FLEET_EXIT_PEER_SKEW;
+    if (peers.some((p) => p.status !== "ok"))
+        return FLEET_EXIT_PEER_UNREACHABLE;
+    return FLEET_EXIT_OK;
+}
+// ─── Pure decision logic: ProbeResult → FleetNodeResult ─────────────────────
+/**
+ * Turn a probe attempt (or the absence of one) into a table row. Pure —
+ * no I/O. `expectVersion` is the baseline this node should be running;
+ * pass null when there is nothing to compare against (skew can't be
+ * evaluated, but health/auth still can).
+ */
+export function classifyNode(role, id, url, method, probe, expectVersion, unverifiableReason) {
+    if (method === "none" || probe === null) {
+        return {
+            id, role, url, method: "none",
+            healthy: null, authenticated: null, version: null, versionMatch: null,
+            status: "unverifiable",
+            detail: unverifiableReason ?? "no way to verify this node",
+        };
+    }
+    if (!probe.healthy) {
+        return {
+            id, role, url, method,
+            healthy: false, authenticated: null, version: null, versionMatch: null,
+            status: "unreachable",
+            detail: probe.error ?? `${url ?? id} did not answer /Health`,
+        };
+    }
+    if (probe.authenticated === false) {
+        return {
+            id, role, url, method,
+            healthy: true, authenticated: false, version: null, versionMatch: null,
+            status: "auth-failed",
+            detail: probe.error ?? "authenticated request rejected",
+        };
+    }
+    if (expectVersion !== null && probe.versionMatch === false) {
+        return {
+            id, role, url, method,
+            healthy: true, authenticated: probe.authenticated, version: probe.version, versionMatch: false,
+            status: "skew",
+            detail: probe.error ?? `version mismatch: expected ${expectVersion}, reports ${probe.version ?? "unknown"}`,
+        };
+    }
+    return {
+        id, role, url, method,
+        healthy: true, authenticated: probe.authenticated, version: probe.version, versionMatch: probe.versionMatch,
+        status: "ok",
+        detail: probe.version ? `healthy, running ${probe.version}` : "healthy",
+    };
+}
+// ─── Peer endpoint validation ────────────────────────────────────────────────
+/**
+ * A federation Peer record may have no `endpoint` at all (tunnel-paired —
+ * see src/cli.ts's existing `flair federation ping` handling of the same
+ * shape) or an endpoint that isn't a plain http(s) URL. Reject non-http(s)
+ * schemes rather than attempting to fetch them (same protocol allowlist as
+ * the existing federation-ping probe — Sherlock review on #314).
+ */
+export function validatePeerEndpoint(endpoint) {
+    if (!endpoint) {
+        return { error: "no endpoint on file (never federation-paired with a direct endpoint, or tunnel-paired)" };
+    }
+    let parsed;
+    try {
+        parsed = new URL(endpoint);
+    }
+    catch {
+        return { error: `invalid endpoint URL on file: ${endpoint}` };
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return { error: `unsupported endpoint protocol on file: ${parsed.protocol}` };
+    }
+    return { url: endpoint };
+}
+// ─── Fabric admin Basic-auth authedGet (injected into probeInstance) ────────
+/**
+ * Builds the authedGet probeInstance needs, using Fabric admin Basic auth —
+ * the exact credential shape src/deploy.ts and src/fabric-upgrade.ts already
+ * use for the whole cluster (FABRIC_USER/FABRIC_PASSWORD). Assumes a single
+ * Fabric cluster shares one admin realm across its nodes; a peer that
+ * rejects these credentials (a genuinely separate Harper instance with its
+ * own admin) surfaces as "auth-failed" — itself a real, informative finding,
+ * not a bug in this probe.
+ *
+ * NEVER logs the credential — only the Authorization header carries it, and
+ * probeInstance/callers only ever see/report the HTTP outcome.
+ */
+export function buildFabricAuthedGet(baseUrl, fabricUser, fabricPassword) {
+    const base = baseUrl.replace(/\/+$/, "");
+    const auth = Buffer.from(`${fabricUser}:${fabricPassword}`).toString("base64");
+    return async (path) => {
+        const res = await fetch(`${base}${path}`, {
+            headers: { Authorization: `Basic ${auth}` },
+            signal: AbortSignal.timeout(15_000),
+        });
+        const text = await res.text();
+        if (!res.ok)
+            throw new Error(text || `HTTP ${res.status}`);
+        return text ? JSON.parse(text) : {};
+    };
+}
+async function defaultFetchPeers(authedGet) {
+    const body = await authedGet("/FederationPeers");
+    return Array.isArray(body?.peers) ? body.peers : [];
+}
+function defaultDeps() {
+    return {
+        probe: probeInstance,
+        fetchPeers: defaultFetchPeers,
+        buildAuthedGet: buildFabricAuthedGet,
+    };
+}
+// ─── Orchestrator ───────────────────────────────────────────────────────────
+export async function sweepFleet(opts, injected) {
+    const deps = { ...defaultDeps(), ...injected };
+    const log = deps.log ?? (() => { });
+    const originAuthedGet = deps.buildAuthedGet(opts.target, opts.fabricUser, opts.fabricPassword);
+    log(`Probing origin ${opts.target} ...`);
+    const originProbe = await deps.probe(opts.target, {
+        expectVersion: opts.expectVersion,
+        timeoutMs: opts.timeoutMs,
+        authedGet: originAuthedGet,
+    });
+    const explicitExpect = opts.expectVersion ?? null;
+    const expectVersion = explicitExpect ?? originProbe.version ?? null;
+    const expectVersionSource = explicitExpect !== null ? "explicit" : expectVersion !== null ? "origin" : "none";
+    // Origin is classified against the EXPLICIT expectation only — when none was
+    // given, the origin itself defines the baseline and can't be "skewed"
+    // relative to its own reading.
+    const origin = classifyNode("origin", "origin", opts.target, "direct", originProbe, explicitExpect);
+    let peerRecords = [];
+    let peerEnumerationError = null;
+    try {
+        log("Enumerating federation peers ...");
+        peerRecords = await deps.fetchPeers(originAuthedGet);
+    }
+    catch (err) {
+        peerEnumerationError = err?.message ?? String(err);
+    }
+    // Revoked peers are intentionally decommissioned — reporting them
+    // unreachable would be noise, not signal.
+    const knownPeers = peerRecords.filter((p) => p.status !== "revoked");
+    const peers = [];
+    for (const p of knownPeers) {
+        const check = validatePeerEndpoint(p.endpoint);
+        if ("error" in check) {
+            peers.push(classifyNode("peer", p.id, p.endpoint ?? null, "none", null, expectVersion, check.error));
+            continue;
+        }
+        log(`Probing peer ${p.id} (${check.url}) ...`);
+        const peerAuthedGet = deps.buildAuthedGet(check.url, opts.fabricUser, opts.fabricPassword);
+        const peerProbe = await deps.probe(check.url, {
+            expectVersion: expectVersion ?? undefined,
+            timeoutMs: opts.timeoutMs,
+            authedGet: peerAuthedGet,
+        });
+        peers.push(classifyNode("peer", p.id, check.url, "direct", peerProbe, expectVersion));
+    }
+    if (peerEnumerationError) {
+        // A failure to even LIST peers means fleet coverage is unknown — never
+        // let that read as "0 peers, all clear."
+        peers.push({
+            id: "(peer enumeration)",
+            role: "peer",
+            url: null,
+            method: "none",
+            healthy: null, authenticated: null, version: null, versionMatch: null,
+            status: "unverifiable",
+            detail: `GET /FederationPeers on the origin failed: ${peerEnumerationError} — fleet coverage unknown, cannot confirm every peer was even considered`,
+        });
+    }
+    const exitCode = decideFleetExitCode(origin, peers);
+    return { target: opts.target, expectVersion, expectVersionSource, origin, peers, peerEnumerationError, exitCode };
+}
+// ─── Rendering ───────────────────────────────────────────────────────────────
+const STATUS_COLOR = {
+    ok: render.c.green,
+    skew: render.c.red,
+    unreachable: render.c.red,
+    "auth-failed": render.c.yellow,
+    unverifiable: render.c.yellow,
+};
+/**
+ * Per-node table + the caveats an operator needs to trust it. An "ok" row
+ * always means a REAL probe answered; anything else names exactly how it's
+ * wrong (see FleetNodeResult.detail) instead of a bare pass/fail.
+ */
+export function renderFleetSweepTable(result) {
+    const rows = [result.origin, ...result.peers];
+    const cols = [
+        { label: "node", key: "id" },
+        { label: "role", key: "role" },
+        { label: "method", key: "method", format: (v) => (v === "direct" ? "direct" : render.wrap(render.c.dim, "none")) },
+        {
+            label: "status",
+            key: "status",
+            format: (v) => render.wrap(STATUS_COLOR[v] ?? render.c.dim, String(v)),
+        },
+        { label: "version", key: "version", format: (v) => (v ? String(v) : render.wrap(render.c.dim, "—")) },
+        { label: "detail", key: "detail" },
+    ];
+    const lines = [render.table(cols, rows)];
+    if (result.peers.length === 0 || (result.peers.length === 1 && result.peerEnumerationError)) {
+        lines.push("");
+        lines.push(render.wrap(render.c.dim, "0 federation peers known to the origin. This does NOT mean the Fabric cluster has no other " +
+            "replication nodes — Harper's own cluster peers aren't visible to this tool (cluster_status is a " +
+            "harper-pro-only operation, unavailable in the OSS build this CLI ships). It means no other node is " +
+            "paired as a Flair federation peer of this origin. If this cluster has replicas, pair them " +
+            "(`flair federation pair`) so fleet verify can actually see them."));
+    }
+    const expectLine = result.expectVersionSource === "explicit"
+        ? `compared against --expect-version ${result.expectVersion}`
+        : result.expectVersionSource === "origin"
+            ? `compared against the origin's own reported version (${result.expectVersion}) — no --expect-version given`
+            : "no version baseline available (origin unreachable/unauthenticated and no --expect-version given) — skew could not be checked";
+    lines.push("");
+    lines.push(render.wrap(render.c.dim, expectLine));
+    return lines.join("\n");
+}