Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
import { describe, expect, it } from 'vitest'
import { GitHubIssuesClient } from './client'
const issue = (number: number, over: Record<string, unknown> = {}) => ({
id: 1_000 + number,
number,
title: `Issue ${number}`,
body: 'Body',
state: 'open',
state_reason: null,
html_url: `https://github.com/nodeterm/nodeterm/issues/${number}`,
url: `https://api.github.com/repos/nodeterm/nodeterm/issues/${number}`,
labels: [{ id: 1, name: 'bug', color: 'd73a4a' }],
assignees: [{ id: 2, login: 'octocat', avatar_url: 'https://avatars.githubusercontent.com/u/2?v=4' }],
created_at: '2026-08-01T10:00:00Z',
updated_at: '2026-08-09T10:00:00Z',
locked: false,
...over
})
function response(body: unknown, init: ResponseInit = {}): Response {
return new Response(JSON.stringify(body), {
status: 200,
headers: { 'content-type': 'application/json', ...init.headers },
...init
})
}
describe('GitHubIssuesClient', () => {
it('validates the authenticated user identity used for global coordination', async () => {
const client = new GitHubIssuesClient({
token: 'secret',
fetch: async () => response({ id: 123, login: 'octocat' })
})
expect(await client.checkAuthenticatedUser()).toEqual({
notModified: false, identity: { userId: '123', login: 'octocat' }
})
})
it('uses the fixed API host and required version headers', async () => {
const calls: Array<{ url: string; init: RequestInit }> = []
const client = new GitHubIssuesClient({
token: 'secret',
fetch: async (url, init) => {
calls.push({ url: String(url), init: init ?? {} })
return response([issue(1)])
}
})
await client.listIssues('nodeterm/nodeterm', { state: 'all', page: 1, perPage: 50 })
expect(calls[0].url).toBe('https://api.github.com/repos/nodeterm/nodeterm/issues?state=all&page=1&per_page=50')
expect(calls[0].init).toMatchObject({ redirect: 'manual' })
expect(new Headers(calls[0].init.headers).get('x-github-api-version')).toBe('2022-11-28')
expect(new Headers(calls[0].init.headers).get('authorization')).toBe('Bearer secret')
})
it('harvests pull requests alongside issues, marking only the pull requests', async () => {
const client = new GitHubIssuesClient({
token: 'secret',
fetch: async () => response([
issue(1, {
draft: true,
pull_request: { url: 'https://api.github.com/repos/nodeterm/nodeterm/pulls/1', merged_at: null }
}),
issue(2)
])
})
const page = await client.listIssues('nodeterm/nodeterm', { state: 'all', page: 1, perPage: 50 })
expect(page.items.map((item) => item.number)).toEqual([1, 2])
expect(page.items[0].pull).toEqual({ draft: true, mergedAt: null })
expect(page.items[1].pull).toBeUndefined()
})
it('reads a merged pull request from merged_at, which is what separates it from closed', async () => {
const client = new GitHubIssuesClient({
token: 'secret',
fetch: async () => response([
issue(3, {
state: 'closed',
pull_request: { url: 'x', merged_at: '2026-08-30T20:35:03Z' }
}),
issue(4, { state: 'closed', pull_request: { url: 'x', merged_at: null } })
])
})
const page = await client.listIssues('nodeterm/nodeterm', { state: 'all', page: 1, perPage: 50 })
expect(page.items[0].pull).toEqual({ draft: false, mergedAt: '2026-08-30T20:35:03Z' })
expect(page.items[1].pull).toEqual({ draft: false, mergedAt: null })
})
it('rejects a malformed pull request payload instead of downgrading it to an issue', async () => {
const client = new GitHubIssuesClient({
token: 'secret',
fetch: async () => response([issue(5, { pull_request: { url: 'x', merged_at: 'not-a-date' } })])
})
await expect(client.listIssues('nodeterm/nodeterm', { state: 'all', page: 1, perPage: 50 }))
.rejects.toMatchObject({ code: 'malformed-response' })
})
it('rejects a pull request returned by the single issue endpoint', async () => {
const client = new GitHubIssuesClient({
token: 'secret',
fetch: async () => response(issue(7, { pull_request: { url: 'x' } }))
})
await expect(client.getIssue('nodeterm/nodeterm', 7))
.rejects.toMatchObject({ code: 'invalid-request' })
})
it('distinguishes permissions from primary and secondary rate limits', async () => {
const forbidden = new GitHubIssuesClient({
token: 'secret', fetch: async () => response({ message: 'forbidden' }, { status: 403 })
})
await expect(forbidden.getIssue('nodeterm/nodeterm', 1))
.rejects.toMatchObject({ code: 'insufficient-permission', status: 403 })
const primary = new GitHubIssuesClient({
token: 'secret', fetch: async () => response({ message: 'rate limit' }, {
status: 403, headers: { 'x-ratelimit-remaining': '0', 'x-ratelimit-reset': '2000000000' }
})
})
await expect(primary.getIssue('nodeterm/nodeterm', 1))
.rejects.toMatchObject({ code: 'rate-limited', status: 403, retryAt: 2_000_000_000_000 })
const before = Date.now()
const secondary = new GitHubIssuesClient({
token: 'secret', fetch: async () => response({ message: 'slow down' }, { status: 429 })
})
await expect(secondary.getIssue('nodeterm/nodeterm', 1)).rejects.toMatchObject({
code: 'rate-limited', status: 429
})
try {
await secondary.getIssue('nodeterm/nodeterm', 1)
} catch (error) {
expect((error as { retryAt: number }).retryAt).toBeGreaterThanOrEqual(before + 2_000)
}
const documentedSecondary = new GitHubIssuesClient({
token: 'secret', fetch: async () => response({
message: 'You have exceeded a secondary rate limit. Please wait a few minutes before you try again.',
documentation_url: 'https://docs.github.com/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-secondary-rate-limits'
}, { status: 403, headers: { 'x-ratelimit-remaining': '42' } })
})
await expect(documentedSecondary.getIssue('nodeterm/nodeterm', 1)).rejects.toMatchObject({
code: 'rate-limited', status: 403
})
})
it('returns the next page and ETag without arbitrary headers', async () => {
const client = new GitHubIssuesClient({
token: 'secret',
fetch: async () => response([issue(1)], {
headers: {
etag: '"abc"',
link: '<https://api.github.com/repos/nodeterm/nodeterm/issues?page=2>; rel="next"',
'x-private-value': 'must-not-pass'
}
})
})
expect(await client.listIssues('nodeterm/nodeterm', { state: 'all', page: 1, perPage: 50 }))
.toMatchObject({ nextPage: 2, etag: '"abc"' })
})
it('rejects malformed and oversized responses', async () => {
const malformed = new GitHubIssuesClient({
token: 'secret',
fetch: async () => response([{ id: 1, title: 'missing fields' }])
})
await expect(malformed.listIssues('nodeterm/nodeterm', { state: 'all', page: 1, perPage: 50 }))
.rejects.toMatchObject({ code: 'malformed-response' })
const oversized = new GitHubIssuesClient({
token: 'secret',
maxResponseBytes: 32,
fetch: async () => response([issue(1)])
})
await expect(oversized.listIssues('nodeterm/nodeterm', { state: 'all', page: 1, perPage: 50 }))
.rejects.toMatchObject({ code: 'response-too-large' })
})
it('decodes a confirmed issue update and sends only supported fields', async () => {
let request: { url: string; init: RequestInit } | null = null
const client = new GitHubIssuesClient({
token: 'secret',
fetch: async (url, init) => {
request = { url: String(url), init: init ?? {} }
return response(issue(42, { state: 'closed', labels: [{ id: 4, name: 'status:done', color: '30d158' }] }))
}
})
const updated = await client.updateIssue('nodeterm/nodeterm', 42, {
state: 'closed',
labels: ['bug', 'status:done']
})
expect(updated).toMatchObject({ number: 42, state: 'closed' })
expect(request).not.toBeNull()
expect(JSON.parse(String((request as unknown as { init: RequestInit }).init.body)))
.toEqual({ state: 'closed', labels: ['bug', 'status:done'] })
})
describe('issuesHeartbeat', () => {
it('asks for the single most recently updated item, conditionally on the stored ETag', async () => {
const calls: Array<{ url: string; headers: Headers }> = []
const client = new GitHubIssuesClient({
token: 'secret',
fetch: async (url, init) => {
calls.push({ url: String(url), headers: new Headers(init?.headers) })
return new Response(null, { status: 304, headers: { etag: '"strong"' } })
}
})
expect(await client.issuesHeartbeat('nodeterm/nodeterm', 'W/"stored"'))
.toEqual({ notModified: true, etag: 'W/"stored"' })
// state=all + sort=updated covers issues AND pull requests: the same endpoint and the same
// `updated_at` the incremental `since` scan filters on, so the heartbeat can never miss a
// change that scan would have picked up.
expect(calls[0].url).toBe(
'https://api.github.com/repos/nodeterm/nodeterm/issues?state=all&sort=updated&direction=desc&per_page=1'
)
expect(calls[0].headers.get('if-none-match')).toBe('W/"stored"')
})
it('returns the fresh ETag of a changed repository without decoding the item', async () => {
const client = new GitHubIssuesClient({
token: 'secret',
fetch: async () => response([{ anything: 'the body is not the point' }], {
headers: { etag: 'W/"fresh"' }
})
})
expect(await client.issuesHeartbeat('nodeterm/nodeterm')).toEqual({
notModified: false, etag: 'W/"fresh"'
})
})
it('sends no condition when there is no stored ETag', async () => {
let headers: Headers | undefined
const client = new GitHubIssuesClient({
token: 'secret',
fetch: async (_url, init) => { headers = new Headers(init?.headers); return response([]) }
})
await client.issuesHeartbeat('nodeterm/nodeterm')
expect(headers?.has('if-none-match')).toBe(false)
})
})
describe('rate-limit observation', () => {
const rateHeaders = {
'x-ratelimit-limit': '5000',
'x-ratelimit-remaining': '4968',
'x-ratelimit-reset': '1790625711',
'x-ratelimit-resource': 'core'
}
const expected = { resource: 'core', limit: 5000, remaining: 4968, resetAt: 1_790_625_711_000 }
it.each([
['a 200', () => response([], { headers: rateHeaders }), 4968],
['a 304', () => new Response(null, { status: 304, headers: rateHeaders }), 4968],
['a 500', () => new Response('{}', { status: 500, headers: rateHeaders }), 4968],
['a rate-limited 403', () => new Response('{}', {
status: 403, headers: { ...rateHeaders, 'x-ratelimit-remaining': '0' }
}), 0]
] as const)('reports the budget carried by %s', async (_name, make, remaining) => {
const samples: unknown[] = []
const client = new GitHubIssuesClient({
token: 'secret',
fetch: async () => make(),
onRateLimit: (sample) => samples.push(sample)
})
await client.issuesHeartbeat('nodeterm/nodeterm', 'W/"x"').catch(() => undefined)
expect(samples).toEqual([{ ...expected, remaining }])
})
it('ignores absent or malformed rate headers instead of recording a zero budget', async () => {
const samples: unknown[] = []
for (const headers of [
{},
{ ...rateHeaders, 'x-ratelimit-remaining': 'lots' },
{ ...rateHeaders, 'x-ratelimit-remaining': '9000' },
{ ...rateHeaders, 'x-ratelimit-resource': 'core; evil' }
]) {
const client = new GitHubIssuesClient({
token: 'secret',
fetch: async () => response([], { headers }),
onRateLimit: (sample) => samples.push(sample)
})
await client.issuesHeartbeat('nodeterm/nodeterm')
}
expect(samples).toEqual([])
})
it('never lets a throwing observer break the request', async () => {
const client = new GitHubIssuesClient({
token: 'secret',
fetch: async () => response([], { headers: { ...rateHeaders, etag: 'W/"a"' } }),
onRateLimit: () => { throw new Error('observer bug') }
})
await expect(client.issuesHeartbeat('nodeterm/nodeterm')).resolves.toEqual({
notModified: false, etag: 'W/"a"'
})
})
})
describe('checkAuthenticatedUser', () => {
it('answers 304 for an unchanged identity when given its validator', async () => {
let sent: string | null = null
const client = new GitHubIssuesClient({
token: 'secret',
fetch: async (_url, init) => {
sent = new Headers(init?.headers).get('if-none-match')
return new Response(null, { status: 304 })
}
})
expect(await client.checkAuthenticatedUser('W/"me"')).toEqual({ notModified: true })
expect(sent).toBe('W/"me"')
})
it('returns the identity with its validator on a 200', async () => {
const client = new GitHubIssuesClient({
token: 'secret',
fetch: async () => response({ id: 7, login: 'octocat' }, { headers: { etag: 'W/"me"' } })
})
expect(await client.checkAuthenticatedUser()).toEqual({
notModified: false, identity: { userId: '7', login: 'octocat' }, etag: 'W/"me"'
})
})
it('still surfaces a 401 as a refusal', async () => {
const client = new GitHubIssuesClient({
token: 'secret',
fetch: async () => new Response('{}', { status: 401 })
})
await expect(client.checkAuthenticatedUser('W/"me"')).rejects.toMatchObject({
code: 'request-failed', status: 401
})
})
})
describe('close reason', () => {
const capture = () => {
const bodies: unknown[] = []
const client = new GitHubIssuesClient({
token: 'secret',
fetch: async (_url, init) => {
bodies.push(JSON.parse(String(init?.body)))
return response(issue(42, { state: 'closed', state_reason: 'not_planned' }))
}
})
return { client, bodies }
}
it('sends state_reason alongside the state change', async () => {
const { client, bodies } = capture()
await client.updateIssue('nodeterm/nodeterm', 42, { state: 'closed', stateReason: 'not_planned', labels: [] })
expect(bodies).toEqual([{ state: 'closed', state_reason: 'not_planned', labels: [] }])
})
it.each([
['a reason without a state change', { stateReason: 'completed', labels: [] }],
['a reason GitHub does not know', { state: 'closed', stateReason: 'wontfix', labels: [] }],
['a close reason on a reopen', { state: 'open', stateReason: 'not_planned', labels: [] }],
['reopened on a close', { state: 'closed', stateReason: 'reopened', labels: [] }]
])('refuses %s without sending anything', async (_name, input) => {
const { client, bodies } = capture()
await expect(client.updateIssue('nodeterm/nodeterm', 42, input as never))
.rejects.toMatchObject({ code: 'invalid-request' })
expect(bodies).toEqual([])
})
})
describe('state_reason values GitHub adds later', () => {
const list = (reason: unknown) => new GitHubIssuesClient({
token: 'secret',
fetch: async () => response([issue(1), issue(2, { state: 'closed', state_reason: reason })])
}).listIssues('nodeterm/nodeterm', { state: 'all', page: 1, perPage: 50 })
it('decodes a duplicate instead of failing the whole page', async () => {
// Measured 2026-09-29: one of cli/cli's last 100 closed issues carries it. Rejecting it made
// the scan fail as malformed, and that repository never synced at all.
const page = await list('duplicate')
expect(page.items.map((item) => item.stateReason)).toEqual([null, 'duplicate'])
})
it('reads a reason it does not know yet as no reason, keeping the rest of the page', async () => {
const page = await list('some_future_reason')
expect(page.items.map((item) => item.number)).toEqual([1, 2])
expect(page.items[1].stateReason).toBeNull()
})
it('still rejects a state_reason that is not a string at all', async () => {
await expect(list(7)).rejects.toMatchObject({ code: 'malformed-response' })
})
})
})