@groundnuty/macf 0.2.38 → 0.2.39

package/dist/cli/commands/routing-doctor.d.ts

@@ -0,0 +1,183 @@
+import type { AgentInfo, HealthResponse } from '@groundnuty/macf-core';
+export type CallerPinStatus = 'pinned' | 'no-workflow' | 'error';
+/** One repo's caller-pin read. `pinned` ones participate in the consistency verdict. */
+export interface CallerPinResult {
+    readonly repo: string;
+    readonly pin: string | null;
+    readonly status: CallerPinStatus;
+    readonly error?: string;
+}
+/** One agent's entry in a repo's `.github/agent-config.json`. */
+export interface RoutingConfigEntry {
+    readonly app_name?: string;
+    readonly tmux_session?: string;
+}
+/** A repo's `.github/agent-config.json` (the router's per-label config). */
+export interface RoutingConfig {
+    readonly agents: Readonly<Record<string, RoutingConfigEntry>>;
+}
+/** Probe a single endpoint's `/health`; null on any failure. Injectable for tests. */
+export type RoutingProbeFn = (host: string, port: number) => Promise<HealthResponse | null>;
+/** Normalize a GitHub login for comparison: lowercase, strip `app/` + `[bot]`. */
+export declare function normalizeLogin(s: string): string;
+/**
+ * The expected fleet caller-pin: an explicit override, else the MODAL (most
+ * common) pin among the repos that ARE routing callers. `null` when no repo pins
+ * macf-actions (nothing to be consistent about).
+ */
+export declare function computeExpectedPin(pinned: readonly string[], override?: string): string | null;
+/**
+ * Self-skip correctness (#538 check b / #566). `app_name` must be the bot-LOGIN.
+ * When an authoritative `expectedBotLogin` is known (the running agent's own
+ * `github_app.bot_login`, macf#535), compare exactly (normalized). Otherwise fall
+ * back to the structural heuristic: the #566 bug is literally `app_name === <bare
+ * routing label>`, so flag that — anything else passes (we can't prove the exact
+ * bot-login without an authoritative actor source; stated in the legend).
+ */
+export declare function evaluateSelfSkip(label: string, appName: string | undefined, expectedBotLogin?: string): {
+    readonly ok: boolean;
+    readonly reason?: string;
+};
+/**
+ * Session-name drift (#? Stage-2 fallback). The CONVENTION check: `tmux_session`
+ * must equal `<project>@<label>`. This is a STATIC convention check — it proves the
+ * config follows the canonical naming, NOT that it matches the LIVE tmux session
+ * (a runtime fact this command can't see). Stated in the legend.
+ */
+export declare function evaluateSession(label: string, tmuxSession: string | undefined, project: string): {
+    readonly ok: boolean;
+    readonly expected: string;
+    readonly reason?: string;
+};
+/** Strict base64: only the base64 alphabet, padded to a multiple of 4. */
+export declare function isStrictBase64(s: string): boolean;
+/**
+ * CA material check (#563). `MACF_CA_CERT` is a readable VARIABLE; validate it is
+ * present AND parses — either as a PEM cert block whose body is strict base64, or
+ * as a base64-of-PEM blob that decodes to a cert. A present-but-malformed value
+ * (truncated / garbled base64) is the #563 class: present ≠ valid.
+ */
+export declare function evaluateCaCert(raw: string | null | undefined): {
+    readonly present: boolean;
+    readonly valid: boolean;
+    readonly reason?: string;
+};
+export type FreshnessState = 'fresh' | 'stale' | 'unreachable' | 'unknown' | 'unregistered';
+/**
+ * Classify a registry entry's freshness against the LIVE `/health`:
+ *  - `/health` answers + instance_id MATCHES   → `fresh`.
+ *  - `/health` answers + instance_id MISMATCH  → `stale` (registry points at an
+ *                                                older instance; a newer one answered).
+ *  - `/health` answers but reports no instance_id (older cs) → `unknown`.
+ *  - `/health` unreachable + heartbeat aged past TTL (DR-031) → `stale` (definitively
+ *                                                dead — ungraceful death).
+ *  - `/health` unreachable, heartbeat fresh/absent → `unreachable` (can't confirm;
+ *                                                NOT a verdict failure — liveness is
+ *                                                `fleet doctor`'s job, not the plane's).
+ */
+export declare function classifyFreshness(info: AgentInfo, health: HealthResponse | null, now: number, ttlMs: number): FreshnessState;
+export interface RepoPinRow {
+    readonly repo: string;
+    readonly pin: string | null;
+    readonly status: CallerPinStatus;
+    /** `true`/`false` for routing callers; `null` for non-callers (excluded from verdict). */
+    readonly consistent: boolean | null;
+}
+export interface AgentRow {
+    readonly label: string;
+    readonly appName: string | null;
+    readonly tmuxSession: string | null;
+    readonly routable: boolean;
+    readonly selfSkipOk: boolean;
+    readonly selfSkipReason?: string;
+    readonly sessionOk: boolean;
+    readonly sessionExpected: string;
+    readonly sessionReason?: string;
+    readonly freshness: FreshnessState;
+    readonly registryInstanceId?: string | null;
+    readonly healthInstanceId?: string | null;
+}
+export interface CaCheckResult {
+    readonly present: boolean;
+    readonly valid: boolean;
+    readonly reason?: string;
+}
+export interface RoutingDoctorReport {
+    readonly project: string;
+    readonly repoPins: readonly RepoPinRow[];
+    readonly expectedPin: string | null;
+    readonly hasRoutingConfig: boolean;
+    readonly agents: readonly AgentRow[];
+    readonly ca: CaCheckResult;
+}
+/** Injectable seam so tests drive the command fully offline. */
+export interface RoutingDoctorDeps {
+    readonly project: string;
+    /** The App install-set (DR-030 Q3 repo-set source). */
+    readonly listRepos: () => Promise<readonly string[]>;
+    /** Read a repo's macf-actions caller-pin from agent-router.yml. */
+    readonly readCallerPin: (repo: string) => Promise<CallerPinResult>;
+    /** The CURRENT project's routing config (`.github/agent-config.json`). */
+    readonly readRoutingConfig: () => Promise<RoutingConfig | null>;
+    /** Registry agents (for routability + freshness). */
+    readonly listRegistry: () => Promise<readonly {
+        readonly name: string;
+        readonly info: AgentInfo;
+    }[]>;
+    /** mTLS `/health` probe (freshness). */
+    readonly probe: RoutingProbeFn;
+    /** The `MACF_CA_CERT` variable's raw value. */
+    readonly readCaCert: () => Promise<string | null>;
+    /** Authoritative expected bot-logins by routing label (partial; heuristic fallback). */
+    readonly botLogins?: Readonly<Record<string, string>>;
+    /** Explicit expected caller-pin (else the modal pin). */
+    readonly expectedPin?: string;
+    /** Clock for the heartbeat-TTL staleness math (defaults to `Date.now()`). */
+    readonly now?: number;
+}
+/**
+ * Run all five checks. PURE w.r.t. the injected deps — tests pass fakes so nothing
+ * hits gh / the registry / the network.
+ */
+export declare function gatherRoutingDoctor(deps: RoutingDoctorDeps): Promise<RoutingDoctorReport>;
+export type RoutingVerdict = 'HEALTHY' | 'DEGRADED' | 'EMPTY';
+export declare function routingVerdict(report: RoutingDoctorReport): RoutingVerdict;
+/** `4 fleet repos (pins consistent); 3 agents (2 routing-OK); CA ✓; routing plane: HEALTHY`. */
+export declare function summaryLine(report: RoutingDoctorReport): string;
+/** ✓ consistent / ✗ divergent / `— n/a` (non-caller). */
+export declare function pinGlyph(consistent: boolean | null): string;
+/** Freshness → short glyph: fresh ✓, stale ✗, unreachable/unknown ?, unregistered —. */
+export declare function freshnessGlyph(s: FreshnessState): string;
+export declare function buildRepoRows(rows: readonly RepoPinRow[]): readonly (readonly string[])[];
+export declare function buildAgentRows(rows: readonly AgentRow[]): readonly (readonly string[])[];
+export declare function formatRepoTable(rows: readonly RepoPinRow[]): string;
+export declare function formatAgentTable(rows: readonly AgentRow[]): string;
+/**
+ * The honesty legend — these are STATIC GitHub-plane checks: they prove the
+ * routing PLUMBING is wired right, NOT that a message was delivered (that is
+ * `--e2e`, a later increment). Carried verbatim in the `--json` `disclaimer`.
+ */
+export declare const HONESTY_LEGEND: string;
+/**
+ * `schema_version` is the HARD version contract (DR-006 watchdog, devops #118):
+ * a consumer asserts `schema_version === <known>` and refuses an unknown value,
+ * so ANY breaking change (rename / removal / a same-name SEMANTIC shift) fails
+ * LOUD rather than silently misreading. BUMP on any breaking change; additive-
+ * optional fields do NOT bump it. Independent from fleet doctor's schema_version
+ * (a separate command, a separate contract).
+ */
+export declare const ROUTING_DOCTOR_JSON_SCHEMA_VERSION = 1;
+export declare function routingDoctorToJson(report: RoutingDoctorReport): unknown;
+export interface RunRoutingDoctorOptions {
+    readonly json?: boolean;
+    /** Explicit expected caller-pin (else the modal pin across the fleet). */
+    readonly expectedPin?: string;
+}
+/**
+ * `macf routing doctor` entry point. Returns the shell exit code — 1 when the
+ * routing plane is DEGRADED, 0 when HEALTHY or EMPTY (matching `fleet doctor` /
+ * `macf doctor` "non-zero on problem"). The `--json` body prints regardless; the
+ * watchdog reads `summary.verdict`. `deps` is injected by tests.
+ */
+export declare function runRoutingDoctor(projectDir: string, opts?: RunRoutingDoctorOptions, deps?: RoutingDoctorDeps): Promise<number>;
+//# sourceMappingURL=routing-doctor.d.ts.map

package/dist/cli/commands/routing-doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-doctor.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/routing-doctor.ts"],"names":[],"mappings":"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"}