@synap-core/cli 1.11.0 → 1.13.0

package/dist/commands/doctor.d.ts

@@ -8,14 +8,144 @@
  *   (b) the key authenticates against that pod.
  *   (c) the configured workspace (and project) actually exist on THIS pod —
  *       via `GET /orient`, which is the pod's own answer to "what's valid here".
- *   (d) prints the active lens (pod, workspace, project) so the user sees
+ *   (d) the Intelligence Service is reachable — the dependency that capture,
+ *       import and all AI structuring run through. Without it doctor once
+ *       printed "All checks passed" while every import was 502-ing.
+ *   (e) the connection broker answers — and when it does not, WHY: broker
+ *       kind, relay credential presence + expiry, control-plane issuer trust
+ *       and the owner's identity link, with the one fix for that reason.
+ *   (f) prints the active lens (pod, workspace, project) so the user sees
  *       exactly where they're pointed.
  *
- * Degrades gracefully on older pods (missing /orient, no release/status route)
- * — a check that can't run says so and moves on, it never throws.
+ * Degrades gracefully on older pods (missing /orient, no dependency probe) — a
+ * check that can't run says so and moves on, it never throws. Crucially, a
+ * check that could not run reports "could not determine" and is NOT green: an
+ * unknown is not a pass. Only a PROVEN failure sets a non-zero exit code.
  */
+/** A saved pod address the Control Plane says has moved. */
+export interface PodMove {
+    from: string;
+    to: string;
+    /** The saved profile holding `from`, when there is one. */
+    profileName?: string;
+}
+/**
+ * Why a pod host did not answer, when the reason is a move. Null when it is not
+ * one (or nothing suggests it), so the caller keeps its generic message. Asks
+ * the Control Plane only on a signal: a redirect to another host, or a hosted
+ * address that stopped answering.
+ */
+export declare function diagnosePodMove(podUrl: string, health: {
+    moved?: boolean;
+}, activeName: string): Promise<{
+    check: CheckResult;
+    move?: PodMove;
+} | null>;
 interface DoctorOpts {
     json?: boolean;
+    /** Every check with its details, ids and addresses. */
+    verbose?: boolean;
+    /** Perform the one right action per key problem, then verify with a real MCP initialize. */
+    fix?: boolean;
+    /** Probe this pod URL instead of the configured one (works with no pod configured). */
+    podUrl?: string;
+}
+interface CheckResult {
+    name: string;
+    /** true ONLY when the check verified something good. */
+    ok: boolean;
+    /**
+     * true when the check could not run at all — an unknown, not a pass and not
+     * a proven failure. It still suppresses "All checks passed" (that green line
+     * over an undetermined dependency is the exact lie this file is fixing), but
+     * it does NOT set a failing exit code, because nothing was proven broken.
+     */
+    unknown?: boolean;
+    detail: string;
+    fix?: string;
 }
+/**
+ * What the pod's dependency probe says about the Intelligence Service.
+ *
+ * Mirrors the pod's own three states rather than flattening them to a boolean
+ * (`packages/api/src/routers/hub-protocol/rest/health-dependencies.ts`):
+ *   • `up`         — state "reachable".
+ *   • `down`       — state "unreachable": the pod KNOWS the IS URL, the probe failed.
+ *   • `unresolved` — the pod could not even work out WHICH IS to call. Still a
+ *     real failure (a capture hits the same resolution), but a different fault
+ *     with a different fix, so it is never reported as "unreachable".
+ *   • `unknown`    — the CLI could not read an answer at all. NOT a pass.
+ */
+export type IsHealthVerdict = {
+    state: "up" | "down" | "unresolved" | "unknown";
+    detail: string;
+};
+export declare function readIntelligenceHealth(payload: unknown): IsHealthVerdict;
+/**
+ * Turn an IS verdict into a check row. Names the CONSEQUENCE, not just the
+ * dependency: the incident this fixes had a green doctor while every capture /
+ * import was 502-ing, so "IS unreachable" alone does not tell the user that the
+ * command they are about to run cannot work.
+ */
+export declare function intelligenceCheck(verdict: IsHealthVerdict): CheckResult;
 export declare function doctor(opts?: DoctorOpts): Promise<void>;
+/**
+ * What `GET /api/hub/connectors/providers` says about the broker.
+ * `not-configured` is the route's own 503 ("Nango not configured"); every other
+ * failure to read is `unknown`, never a pass.
+ */
+export type BrokerProvidersRead = {
+    state: "ok";
+} | {
+    state: "not-configured";
+} | {
+    state: "error";
+    reason: string;
+    message?: string;
+} | {
+    state: "unknown";
+    detail: string;
+};
+/**
+ * `GET /api/hub/connectors/broker-diagnostics` (synap-backend
+ * `connectors/broker-trust-diagnostics.ts`). Non-secret by contract.
+ */
+export interface BrokerTrustReport {
+    cpIssuer: {
+        present: boolean;
+        status: string | null;
+        hasSourceConfigWrite: boolean;
+    };
+    ownerIdentityLink: {
+        present: boolean;
+    };
+    /** `resolvable` is absent on a pod that predates it. */
+    relayCredential: {
+        present: boolean;
+        resolvable?: boolean;
+        validUntil: string | null;
+    };
+    broker: {
+        kind: string;
+        reason: string | null;
+    };
+}
+export type BrokerDiagnosticsRead = {
+    state: "read";
+    report: BrokerTrustReport;
+} | {
+    state: "unknown";
+    detail: string;
+};
+export declare function readProvidersEnvelope(payload: unknown): BrokerProvidersRead;
+export declare function readBrokerDiagnostics(payload: unknown): BrokerDiagnosticsRead;
+/** The one fix for a broker fault, sharpened by the trust diagnostics when readable. */
+export declare function brokerFixHint(reason: string, diagnostics: BrokerDiagnosticsRead, message?: string): string;
+export declare function brokerCheck(providers: BrokerProvidersRead, diagnostics: BrokerDiagnosticsRead): CheckResult;
+/**
+ * Default output never shows internal addresses, ids or raw timestamps — they
+ * are noise to a person and stay one `-v` away. A parenthetical that only
+ * carried an id ("(checked as workspace <uuid>)") goes entirely.
+ */
+export declare function forDisplay(text: string, verbose?: boolean): string;
 export {};