Skip to content

Commit cc5ce93

Browse files
mayoalexanderclaude
andcommitted
feat(integrations): iris integrations health and test <type>
IH-08, the CLI half of the Integration Health epic (bloq #503 list anomalyco#2315). Closes the reporting ask in #182476. iris integrations health what the last sweep found iris integrations health --probe probe every connection now iris integrations test gmail probe one connector now Both read the verdicts the server-side sweep writes, so the CLI and /p/integrations cannot disagree about whether something works. One definition of "working", computed in one place. A second client-side opinion is how list-connected ended up printing [unverified] next to connections that executed their functions fine (#182861). FOUR STATES, KEPT APART: ✓ working a probe ran and passed ✗ failing a probe ran and was refused — with the reason ? never checked nothing has ever probed this ∅ n/a runs in-process; there is no remote thing to check "never checked" is deliberately neither the pass marker nor the fail marker. It is an absence, and drawing it as either is a claim we cannot support — the same distinction list-connected already makes between "we asked and were refused" and "we could not ask". `status` says 'active' for a connection nobody has ever contacted, so any renderer reading status alone shows a green nobody earned. The summary prints every state including the zeroes, so "0 failing" is a measured zero rather than something inferred from an absence of red lines, and a fleet where nothing was ever checked reads as exactly that instead of as healthy. --json emits {error, connections: null} on a failed lookup rather than an empty list. An agent parsing [] states it as fact; that is what told a client her live Gmail was not connected, and the retry it prompted created the dead connection it had described. A 404 'not_connected' renders as "you have not connected this" with a connect hint, never as a failure — different answer, different fix. Verified end-to-end, not just compiled: served the fl-api branch locally, seeded one connection per state, and confirmed all four render distinctly from the real payload. 14 unit tests cover the formatting (bun test). tsc --noEmit reports no errors in these files; the one pre-existing error in src/session/llm.ts is untouched by this change. NOT pushed. This repo has only a pre-push hook, no pre-commit one, so the --no-verify on the commit skipped nothing — noted because the message previously implied otherwise. The pre-push guard has not been run against this branch yet. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01A2ZSEpG7FUdNk8ZpU9YFrR
1 parent a9b192b commit cc5ce93

3 files changed

Lines changed: 395 additions & 0 deletions

File tree

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
import { describe, expect, test } from "bun:test"
2+
import { describeAge, markerFor, formatRow, formatSummary } from "./integration-health"
3+
4+
/**
5+
* IH-08 — the CLI half of integration health (epic bloq #503 list #2315, closes #182476).
6+
*
7+
* These tests are about ONE thing: that the four states stay four. The bug being locked out is
8+
* not a wrong boolean, it is a collapse — "never checked" rendered as working (a green nobody
9+
* earned) or as failing (an alarm nobody deserved). `status` says 'active' for a connection
10+
* that has never been contacted, so any renderer reading status alone gets this wrong.
11+
*/
12+
13+
const row = (over: Record<string, unknown> = {}) =>
14+
({
15+
id: 1,
16+
type: "gmail",
17+
status: "active",
18+
state: "working",
19+
last_tested: new Date().toISOString(),
20+
last_error: null,
21+
...over,
22+
}) as any
23+
24+
describe("describeAge", () => {
25+
test("null is 'never', not a date and not zero", () => {
26+
// The tempting bug is coalescing a missing timestamp to `now` so the column looks populated.
27+
// That renders a connection nobody ever probed as "checked 0s ago".
28+
expect(describeAge(null)).toBe("never")
29+
})
30+
31+
test("an unparseable timestamp is 'unknown', not 'never'", () => {
32+
// "we have no timestamp" and "the timestamp is garbage" are different problems, and only
33+
// the first is a normal state.
34+
expect(describeAge("not-a-date")).toBe("unknown")
35+
})
36+
37+
test("it scales through seconds, minutes, hours and days", () => {
38+
const now = Date.parse("2026-09-04T12:00:00Z")
39+
const at = (ms: number) => describeAge(new Date(now - ms).toISOString(), now)
40+
41+
expect(at(30_000)).toBe("30s ago")
42+
expect(at(4 * 60_000)).toBe("4m ago")
43+
expect(at(3 * 3600_000)).toBe("3h ago")
44+
expect(at(2 * 86_400_000)).toBe("2d ago")
45+
})
46+
47+
test("a future timestamp does not render as a negative age", () => {
48+
const now = Date.parse("2026-09-04T12:00:00Z")
49+
expect(describeAge(new Date(now + 60_000).toISOString(), now)).toBe("0s ago")
50+
})
51+
})
52+
53+
describe("markerFor", () => {
54+
test("never_checked is neither the pass marker nor the fail marker", () => {
55+
// The whole epic in one assertion. An absence of evidence must not borrow either verdict.
56+
const unchecked = markerFor("never_checked")
57+
expect(unchecked).not.toBe(markerFor("working"))
58+
expect(unchecked).not.toBe(markerFor("failing"))
59+
})
60+
61+
test("not_applicable is distinct from never_checked", () => {
62+
// "there is nothing to check" and "nobody has checked" are different facts about a
63+
// connector, and only the second one is something we owe the user an action on.
64+
expect(markerFor("not_applicable")).not.toBe(markerFor("never_checked"))
65+
})
66+
67+
test("failing is distinct from working", () => {
68+
expect(markerFor("failing")).not.toBe(markerFor("working"))
69+
})
70+
})
71+
72+
describe("formatRow", () => {
73+
test("a failing row prints the reason, because 'failed' alone is unactionable", () => {
74+
const line = formatRow(row({ state: "failing", last_error: "token rejected (401)" }))
75+
expect(line).toContain("token rejected (401)")
76+
})
77+
78+
test("a failing row with no recorded reason says so rather than printing nothing", () => {
79+
const line = formatRow(row({ state: "failing", last_error: null }))
80+
expect(line).toContain("no reason recorded")
81+
})
82+
83+
test("a never-checked row says 'never checked' and claims no age", () => {
84+
const line = formatRow(row({ state: "never_checked", last_tested: null }))
85+
expect(line).toContain("never checked")
86+
expect(line).not.toContain("ago")
87+
})
88+
89+
test("a not-applicable row explains itself instead of showing a stale age", () => {
90+
const line = formatRow(row({ state: "not_applicable", last_tested: null }))
91+
expect(line).toContain("nothing to check")
92+
})
93+
94+
test("the account is shown, so two accounts of one type are told apart", () => {
95+
const line = formatRow(row({ account: "[email protected]" }))
96+
expect(line).toContain("[email protected]")
97+
})
98+
})
99+
100+
describe("formatSummary", () => {
101+
test("it counts every state, including the zeroes", () => {
102+
// "0 failing" must be a MEASURED zero on screen, not something the reader infers from an
103+
// absence of red lines — and a fleet where nothing was ever checked must not read as clean.
104+
const s = formatSummary([
105+
row({ state: "working" }),
106+
row({ state: "failing" }),
107+
row({ state: "never_checked" }),
108+
])
109+
110+
expect(s).toContain("1 working")
111+
expect(s).toContain("1 failing")
112+
expect(s).toContain("1 never checked")
113+
expect(s).toContain("0 n/a")
114+
})
115+
116+
test("an all-unchecked fleet does not summarise as healthy", () => {
117+
const s = formatSummary([row({ state: "never_checked" }), row({ state: "never_checked" })])
118+
expect(s).toContain("0 working")
119+
expect(s).toContain("2 never checked")
120+
})
121+
})
Lines changed: 271 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
import { cmd } from "./cmd"
2+
import * as prompts from "./clack"
3+
import { UI } from "../ui"
4+
import { irisFetch, requireAuth, dim, bold, success, highlight, writeJson } from "./iris-api"
5+
6+
/**
7+
* `iris integrations health` / `iris integrations test <type>` — IH-08, epic bloq #503 list #2315.
8+
* Closes the reporting half of #182476.
9+
*
10+
* THE POINT IS THAT THE CLI AND THE PAGE CANNOT DISAGREE. Both read the verdicts written by the
11+
* server-side sweep, so there is one definition of "working" and one place it is computed. A
12+
* second, client-side opinion is how `list-connected` ended up printing [unverified] next to
13+
* connections that executed their functions fine (#182861).
14+
*
15+
* FOUR STATES, KEPT APART ON PURPOSE:
16+
*
17+
* working a probe ran and passed
18+
* failing a probe ran and was refused — there is a reason, and we print it
19+
* never checked nothing has ever probed this. NOT the same as working, and not a failure
20+
* n/a the connector runs in-process; there is no remote thing to check
21+
*
22+
* Collapsing "never checked" into either colour is the bug this whole epic exists to remove:
23+
* `status` says 'active' for a connection nobody has ever contacted, so anything reading status
24+
* alone reports a green that was never earned.
25+
*/
26+
27+
type HealthState = "working" | "failing" | "never_checked" | "not_applicable"
28+
29+
interface HealthRow {
30+
id: number
31+
type: string
32+
name?: string | null
33+
auth_mode?: string | null
34+
account?: string | null
35+
status: string
36+
state: HealthState
37+
last_tested: string | null
38+
last_error: string | null
39+
probe_state?: string
40+
probe_error?: string | null
41+
}
42+
43+
/** "4m ago" / "3d ago" — or the honest word when nothing has ever checked. */
44+
export function describeAge(iso: string | null, now: number = Date.now()): string {
45+
if (!iso) return "never"
46+
const then = Date.parse(iso)
47+
if (Number.isNaN(then)) return "unknown"
48+
49+
const secs = Math.max(0, Math.round((now - then) / 1000))
50+
if (secs < 60) return `${secs}s ago`
51+
if (secs < 3600) return `${Math.round(secs / 60)}m ago`
52+
if (secs < 86400) return `${Math.round(secs / 3600)}h ago`
53+
return `${Math.round(secs / 86400)}d ago`
54+
}
55+
56+
/**
57+
* The marker for a state.
58+
*
59+
* `never_checked` is deliberately NOT a red ✗ and NOT a green ✓. It is an absence, and drawing
60+
* it as either is a claim we cannot support — the same distinction `list-connected` already
61+
* makes between "we asked and were refused" and "we could not ask".
62+
*/
63+
export function markerFor(state: HealthState): string {
64+
switch (state) {
65+
case "working":
66+
return success("✓")
67+
case "failing":
68+
return "✗"
69+
case "not_applicable":
70+
return dim("∅")
71+
default:
72+
return dim("?")
73+
}
74+
}
75+
76+
/** One printable line per connection. Exported so the formatting is testable without a network. */
77+
export function formatRow(row: HealthRow, now: number = Date.now()): string {
78+
const label = row.account ? `${row.type} ${dim(`(${row.account})`)}` : row.type
79+
const age = describeAge(row.last_tested, now)
80+
81+
const tail =
82+
row.state === "not_applicable"
83+
? dim("runs in-process — nothing to check")
84+
: row.state === "never_checked"
85+
? dim("never checked")
86+
: row.state === "failing"
87+
? `${dim(`checked ${age}`)} — ${row.last_error ?? "no reason recorded"}`
88+
: dim(`checked ${age}`)
89+
90+
return ` ${markerFor(row.state)} ${bold(label)} ${tail}`
91+
}
92+
93+
/**
94+
* The summary line.
95+
*
96+
* Reports every state including the empty ones, so "0 failing" is visible as a measured zero
97+
* rather than inferred from the absence of red lines — and so a run where NOTHING was ever
98+
* checked reads as exactly that instead of as a clean bill of health.
99+
*/
100+
export function formatSummary(rows: HealthRow[]): string {
101+
const n = (s: HealthState) => rows.filter((r) => r.state === s).length
102+
return `${n("working")} working · ${n("failing")} failing · ${n("never_checked")} never checked · ${n(
103+
"not_applicable",
104+
)} n/a`
105+
}
106+
107+
async function fetchHealth(probe: boolean): Promise<{ rows: HealthRow[] | null; failure: string | null }> {
108+
try {
109+
const res = await irisFetch(`/api/v1/integrations/health${probe ? "?probe=1" : ""}`)
110+
if (!res.ok) {
111+
return { rows: null, failure: `the health API returned HTTP ${res.status}` }
112+
}
113+
const body = (await res.json()) as { data?: HealthRow[] }
114+
return { rows: body?.data ?? [], failure: null }
115+
} catch (e) {
116+
return { rows: null, failure: e instanceof Error ? e.message : String(e) }
117+
}
118+
}
119+
120+
export const IntegrationsHealthCommand = cmd({
121+
command: "health",
122+
describe: "show when each integration was last tested, and whether it is working",
123+
builder: (y) =>
124+
y
125+
.option("probe", {
126+
type: "boolean",
127+
describe: "probe every connection NOW instead of reading the last sweep's verdicts",
128+
})
129+
.option("json", { type: "boolean" }),
130+
async handler(args) {
131+
UI.empty()
132+
prompts.intro("◈ Integration Health")
133+
if (!(await requireAuth())) {
134+
prompts.outro("Done")
135+
return
136+
}
137+
138+
const sp = prompts.spinner()
139+
sp.start(args.probe ? "Probing every connection…" : "Reading the last verdicts…")
140+
const { rows, failure } = await fetchHealth(Boolean(args.probe))
141+
sp.stop(failure ? "Failed" : "Done", failure ? 1 : 0)
142+
143+
if (args.json) {
144+
// A lookup that FAILED and a user with NO integrations are different answers, and an
145+
// agent parsing `[]` will state the second one as fact. Emit the error rather than an
146+
// empty list it cannot tell apart. (Same failure that told a client her live Gmail was
147+
// not connected, and whose retry then created the dead connection it described.)
148+
await writeJson(failure ? { error: failure, connections: null } : rows)
149+
prompts.outro("Done")
150+
return
151+
}
152+
153+
if (failure) {
154+
prompts.log.error(`Could not read integration health — ${failure}`)
155+
prompts.log.info(dim("This is NOT the same as everything being broken; the lookup did not complete."))
156+
prompts.outro("Done")
157+
return
158+
}
159+
160+
if (!rows || rows.length === 0) {
161+
prompts.log.warn("No integrations connected.")
162+
prompts.outro(dim("iris integrations list-available"))
163+
return
164+
}
165+
166+
const now = Date.now()
167+
for (const row of rows) console.log(formatRow(row, now))
168+
169+
console.log("")
170+
console.log(` ${formatSummary(rows)}`)
171+
172+
const failing = rows.filter((r) => r.state === "failing")
173+
const unchecked = rows.filter((r) => r.state === "never_checked")
174+
175+
if (failing.length) {
176+
console.log("")
177+
for (const f of failing) {
178+
console.log(` ${dim("Reconnect:")} ${highlight(`iris connect ${f.type}`)}`)
179+
}
180+
}
181+
182+
if (unchecked.length && !args.probe) {
183+
console.log("")
184+
console.log(` ${dim(`${unchecked.length} never checked — probe now with:`)} ${highlight("iris integrations health --probe")}`)
185+
}
186+
187+
prompts.outro("Done")
188+
},
189+
})
190+
191+
export const IntegrationsTestCommand = cmd({
192+
command: "test <type>",
193+
describe: "probe one integration right now and report whether it works",
194+
builder: (y) =>
195+
y.positional("type", { type: "string", describe: "integration slug, e.g. gmail" }).option("json", {
196+
type: "boolean",
197+
}),
198+
async handler(args) {
199+
const type = String(args.type ?? "").toLowerCase()
200+
201+
UI.empty()
202+
prompts.intro(`◈ Test ${type}`)
203+
if (!(await requireAuth())) {
204+
prompts.outro("Done")
205+
return
206+
}
207+
208+
const sp = prompts.spinner()
209+
sp.start(`Probing ${type}…`)
210+
211+
let rows: HealthRow[] | null = null
212+
let failure: string | null = null
213+
let notConnected = false
214+
215+
try {
216+
const res = await irisFetch(`/api/v1/integrations/health/${encodeURIComponent(type)}`, { method: "POST" })
217+
const body = (await res.json().catch(() => null)) as { data?: HealthRow[]; code?: string; error?: string } | null
218+
219+
if (res.status === 404 && body?.code === "not_connected") {
220+
notConnected = true
221+
} else if (!res.ok) {
222+
failure = body?.error ?? `the health API returned HTTP ${res.status}`
223+
} else {
224+
rows = body?.data ?? []
225+
}
226+
} catch (e) {
227+
failure = e instanceof Error ? e.message : String(e)
228+
}
229+
230+
sp.stop(failure || notConnected ? "Done" : "Done", failure ? 1 : 0)
231+
232+
if (args.json) {
233+
await writeJson(
234+
notConnected
235+
? { error: `no ${type} connection on this account`, code: "not_connected", connections: null }
236+
: failure
237+
? { error: failure, connections: null }
238+
: rows,
239+
)
240+
prompts.outro("Done")
241+
return
242+
}
243+
244+
// "You have not connected this" is a different answer from "it is broken", and the fix for
245+
// each is different. Never render the first as a failure.
246+
if (notConnected) {
247+
prompts.log.warn(`No ${type} connection on this account.`)
248+
console.log(` ${dim("Connect it:")} ${highlight(`iris connect ${type}`)}`)
249+
prompts.outro("Done")
250+
return
251+
}
252+
253+
if (failure) {
254+
prompts.log.error(`Could not probe ${type} — ${failure}`)
255+
prompts.log.info(dim("The probe did not complete. That says nothing about the integration."))
256+
prompts.outro("Done")
257+
return
258+
}
259+
260+
const now = Date.now()
261+
for (const row of rows ?? []) console.log(formatRow(row, now))
262+
263+
if ((rows ?? []).some((r) => r.state === "failing")) {
264+
console.log("")
265+
console.log(` ${dim("Reconnect:")} ${highlight(`iris connect ${type}`)}`)
266+
process.exitCode = 1
267+
}
268+
269+
prompts.outro("Done")
270+
},
271+
})

0 commit comments

Comments
 (0)