@hanhnd/agent-kit 1.0.42 → 1.0.44

package/README.md

@@ -27,6 +27,29 @@ Claude Code and Codex plugin manifests already use this package:
 }
 ```
 
+## API Token Scopes
+
+Integration tools call the Atlassian REST APIs with scoped API tokens. Create each token at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) ("Create API token with scopes") and grant the scopes below.
+
+| Token                  | Scopes                                                                                                                         |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `BITBUCKET_API_TOKEN`  | `read:pullrequest:bitbucket`, `write:pullrequest:bitbucket`, `read:repository:bitbucket`, `read:workspace:bitbucket`, `read:user:bitbucket` |
+| `JIRA_API_TOKEN`       | `read:jira-work`                                                                                                               |
+| `CONFLUENCE_API_TOKEN` | `read:page:confluence`                                                                                                         |
+
+Per tool:
+
+| Tool                            | Scopes                                                                                                                        |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `kit_get_bitbucket_pr`          | `read:pullrequest:bitbucket`; `read:repository:bitbucket` for the diff (the PR diff redirects to the repository diff)         |
+| `kit_get_bitbucket_pr_comments` | `read:pullrequest:bitbucket`                                                                                                  |
+| `kit_create_bitbucket_pr`       | `read:pullrequest:bitbucket`, `write:pullrequest:bitbucket`; `read:workspace:bitbucket` for reviewers given by name; `read:user:bitbucket` to skip the PR author |
+| `kit_find_bitbucket_reviewers`  | `read:workspace:bitbucket`; `read:user:bitbucket` to flag the PR author                                                       |
+| `kit_jira_get_ticket`           | `read:jira-work`                                                                                                              |
+| `kit_confluence_get_page`       | `read:page:confluence`                                                                                                        |
+
+A missing scope surfaces as a 401/403; the error message lists the scopes the tool needs.
+
 ## Development
 
 From the repository root:

package/dist/mcp/bitbucket.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mcp/bitbucket.test.js

@@ -0,0 +1,335 @@
+import * as assert from 'node:assert/strict';
+import { afterEach, describe, mock, test } from 'node:test';
+import { MAX_PAGES, handleCreateBitbucketPr, handleFindBitbucketReviewers, handleGetBitbucketPrComments, matchReviewers, normalizeName, resolveBitbucketPr, resolveBitbucketRepo, } from './integration.js';
+const API = 'https://api.bitbucket.org/2.0';
+const PR_URL = 'https://bitbucket.org/acme/web-app/pull-requests/42';
+process.env.BITBUCKET_USER_EMAIL = 'dev@acme.test';
+process.env.BITBUCKET_API_TOKEN = 'bb-token';
+process.env.BITBUCKET_DEFAULT_WORKSPACE = 'acme';
+/** Replace the global fetch for one test with a queue of responses; `afterEach` restores it. */
+function stubFetch(responses) {
+    const calls = [];
+    mock.method(globalThis, 'fetch', async (input, init) => {
+        calls.push({
+            url: String(input),
+            method: init?.method ?? 'GET',
+            body: init?.body ? JSON.parse(String(init.body)) : undefined,
+        });
+        const next = responses[Math.min(calls.length - 1, responses.length - 1)];
+        return new Response(typeof next.body === 'string' ? next.body : JSON.stringify(next.body), {
+            status: next.status,
+            headers: { 'content-type': 'application/json' },
+        });
+    });
+    return calls;
+}
+afterEach(() => mock.restoreAll());
+describe('resolveBitbucketPr / resolveBitbucketRepo', () => {
+    test('B1: PR URL resolves to workspace, repo and id', () => {
+        assert.deepEqual(resolveBitbucketPr(PR_URL), { ok: true, ws: 'acme', repo: 'web-app', prId: 42 });
+    });
+    test('B2: numeric PR id uses the default workspace', () => {
+        assert.deepEqual(resolveBitbucketPr('7', undefined, 'api'), { ok: true, ws: 'acme', repo: 'api', prId: 7 });
+    });
+    test('B3: numeric PR id without repoSlug is rejected', () => {
+        assert.equal(resolveBitbucketPr('7').ok, false);
+    });
+    test('B4: repo accepts URL, workspace/repo pair, clone URL and bare slug', () => {
+        const expected = { ok: true, ws: 'acme', repo: 'web-app' };
+        assert.deepEqual(resolveBitbucketRepo('https://bitbucket.org/acme/web-app/src/main/'), expected);
+        assert.deepEqual(resolveBitbucketRepo('acme/web-app'), expected);
+        assert.deepEqual(resolveBitbucketRepo('git@bitbucket.org:acme/web-app.git'), expected);
+        assert.deepEqual(resolveBitbucketRepo('web-app'), expected);
+        assert.deepEqual(resolveBitbucketRepo('web-app', 'other'), { ok: true, ws: 'other', repo: 'web-app' });
+    });
+    test('B5: slugs with URL-breaking characters are rejected', () => {
+        assert.equal(resolveBitbucketRepo('acme/web app').ok, false);
+        assert.equal(resolveBitbucketRepo('../evil').ok, false);
+    });
+});
+const SELF_UUID = '{11111111-1111-1111-1111-111111111111}';
+const MEMBERS = [
+    { uuid: '{aaaaaaaa-0000-0000-0000-000000000001}', display_name: 'Trần Văn Điền', nickname: 'dientv' },
+    { uuid: '{aaaaaaaa-0000-0000-0000-000000000002}', display_name: 'Nguyễn Tiến Dũng', nickname: 'dungnt' },
+    { uuid: '{aaaaaaaa-0000-0000-0000-000000000003}', display_name: 'Lê Dũng', nickname: 'dungle' },
+    { uuid: SELF_UUID, display_name: 'Ngô Hạnh', nickname: 'hanhnd' },
+];
+const member = (i) => ({
+    uuid: MEMBERS[i].uuid,
+    displayName: MEMBERS[i].display_name,
+    nickname: MEMBERS[i].nickname,
+});
+/** Route requests by URL (lookups run concurrently, so order is not stable); unrouted → 500. */
+function stubRoutes(route) {
+    const calls = [];
+    mock.method(globalThis, 'fetch', async (input, init) => {
+        const url = String(input);
+        const method = init?.method ?? 'GET';
+        calls.push({ url, method, body: init?.body ? JSON.parse(String(init.body)) : undefined });
+        const res = route(url, method) ?? { status: 500, body: `unrouted ${method} ${url}` };
+        return new Response(typeof res.body === 'string' ? res.body : JSON.stringify(res.body), {
+            status: res.status,
+            headers: { 'content-type': 'application/json' },
+        });
+    });
+    return calls;
+}
+/** Workspace members split over two pages, the current user, and a 201 for PR creation. */
+function bitbucketRoutes(overrides = () => undefined) {
+    return (url, method) => {
+        const hit = overrides(url, method);
+        if (hit)
+            return hit;
+        if (url === `${API}/workspaces/acme/members?pagelen=100`) {
+            return {
+                status: 200,
+                body: { values: MEMBERS.slice(0, 2).map((user) => ({ user })), next: `${API}/workspaces/acme/members?page=2` },
+            };
+        }
+        if (url === `${API}/workspaces/acme/members?page=2`) {
+            return { status: 200, body: { values: MEMBERS.slice(2).map((user) => ({ user })) } };
+        }
+        if (url === `${API}/user`)
+            return { status: 200, body: { uuid: SELF_UUID } };
+        if (method === 'POST')
+            return { status: 201, body: created };
+        return undefined;
+    };
+}
+const created = {
+    id: 101,
+    title: 'Add login',
+    state: 'OPEN',
+    draft: true,
+    source: { branch: { name: 'feature/login' } },
+    destination: { branch: { name: 'develop' } },
+    reviewers: [{ display_name: 'Bob' }],
+    links: { html: { href: 'https://bitbucket.org/acme/web-app/pull-requests/101' } },
+};
+const postOf = (calls) => calls.find((c) => c.method === 'POST');
+describe('matchReviewers / normalizeName', () => {
+    const members = MEMBERS.map((_, i) => member(i));
+    test('N1: normalizeName strips Vietnamese diacritics including đ', () => {
+        assert.equal(normalizeName('  Trần Văn Điền '), 'tran van dien');
+    });
+    test('N2: a single word matches a whole word of the display name, accent-insensitive', () => {
+        const r = matchReviewers(['Dien'], members);
+        assert.deepEqual(r.resolved, [{ query: 'Dien', member: member(0) }]);
+    });
+    test('N3: a word shared by several members is ambiguous, never guessed', () => {
+        const r = matchReviewers(['Dung'], members);
+        assert.equal(r.resolved.length, 0);
+        assert.deepEqual(r.ambiguous[0].candidates.map((c) => c.uuid), [member(1).uuid, member(2).uuid]);
+    });
+    test('N4: full name, nickname and multi-word queries disambiguate', () => {
+        const r = matchReviewers(['nguyen tien dung', 'dungle', 'Le Dung'], members);
+        assert.deepEqual(r.resolved.map((x) => x.member.uuid), [member(1).uuid, member(2).uuid, member(2).uuid]);
+    });
+    test('N5: partial words do not match', () => {
+        assert.deepEqual(matchReviewers(['Die'], members).unmatched, ['Die']);
+    });
+});
+describe('handleCreateBitbucketPr', () => {
+    test('C1: POSTs the documented body and renders id + URL', async () => {
+        const calls = stubRoutes(bitbucketRoutes());
+        const text = (await handleCreateBitbucketPr({
+            repository: 'acme/web-app',
+            title: ' Add login ',
+            sourceBranch: 'feature/login',
+            destinationBranch: 'develop',
+            description: 'Body',
+            closeSourceBranch: true,
+            draft: true,
+            reviewers: ['504c3b62-8120-4f0c-a7bc-87800b9d6f70'],
+        })).content[0].text;
+        const post = postOf(calls);
+        assert.ok(post);
+        assert.equal(post.url, `${API}/repositories/acme/web-app/pullrequests`);
+        assert.deepEqual(post.body, {
+            title: 'Add login',
+            source: { branch: { name: 'feature/login' } },
+            destination: { branch: { name: 'develop' } },
+            description: 'Body',
+            close_source_branch: true,
+            draft: true,
+            reviewers: [{ uuid: '{504c3b62-8120-4f0c-a7bc-87800b9d6f70}' }],
+        });
+        assert.ok(!calls.some((c) => c.url.includes('/members')), 'UUID-only reviewers need no member lookup');
+        assert.match(text, /Created PR #101: Add login/);
+        assert.match(text, /pull-requests\/101/);
+        assert.match(text, /feature\/login → develop/);
+        assert.match(text, /\(draft\)/);
+        assert.match(text, /Reviewers:\*\* Bob/);
+    });
+    test('C2: omits destination so Bitbucket defaults to the main branch; no lookups without reviewers', async () => {
+        const calls = stubRoutes(bitbucketRoutes());
+        await handleCreateBitbucketPr({ repository: 'web-app', title: 'T', sourceBranch: 'feat' });
+        assert.equal(calls.length, 1);
+        assert.deepEqual(postOf(calls)?.body, { title: 'T', source: { branch: { name: 'feat' } } });
+    });
+    test('C3: names resolve across member pages, dedupe, and drop the PR author', async () => {
+        const calls = stubRoutes(bitbucketRoutes());
+        const text = (await handleCreateBitbucketPr({
+            repository: 'acme/web-app',
+            title: 'T',
+            sourceBranch: 'f',
+            reviewers: ['Dien', 'dientv', 'Le Dung', 'Hanh'],
+        })).content[0].text;
+        assert.deepEqual(postOf(calls)?.body, {
+            title: 'T',
+            source: { branch: { name: 'f' } },
+            reviewers: [{ uuid: member(0).uuid }, { uuid: member(2).uuid }],
+        });
+        assert.match(text, /PR author\) were named as a reviewer — skipped/);
+    });
+    test('C4: ambiguous or unknown names abort before any PR is created', async () => {
+        const calls = stubRoutes(bitbucketRoutes());
+        const text = (await handleCreateBitbucketPr({
+            repository: 'acme/web-app',
+            title: 'T',
+            sourceBranch: 'f',
+            reviewers: ['Dung', 'Zed'],
+        })).content[0].text;
+        assert.equal(postOf(calls), undefined);
+        assert.match(text, /PR not created/);
+        assert.match(text, /"Dung" matches 2 members/);
+        assert.match(text, /Nguyễn Tiến Dũng \(@dungnt\)/);
+        assert.match(text, /"Zed" matches no workspace member/);
+    });
+    test('C5: a 403 on the member list names the missing scope', async () => {
+        stubRoutes(bitbucketRoutes((url) => (url.includes('/members') ? { status: 403, body: {} } : undefined)));
+        const text = (await handleCreateBitbucketPr({ repository: 'acme/web-app', title: 'T', sourceBranch: 'f', reviewers: ['Dien'] })).content[0].text;
+        assert.match(text, /read:workspace:bitbucket/);
+    });
+    test('C5b: the member-list scope hint is not repeated by the generic scope hint', async () => {
+        stubRoutes(bitbucketRoutes((url) => (url.includes('/members') ? { status: 403, body: {} } : undefined)));
+        const text = (await handleCreateBitbucketPr({ repository: 'acme/web-app', title: 'T', sourceBranch: 'f', reviewers: ['Dien'] })).content[0].text;
+        assert.doesNotMatch(text, /Check the API token has these scopes/);
+    });
+    test('C6: without read:user scope the author is not filtered, but creation proceeds', async () => {
+        const calls = stubRoutes(bitbucketRoutes((url) => (url.endsWith('/user') ? { status: 403, body: {} } : undefined)));
+        await handleCreateBitbucketPr({ repository: 'acme/web-app', title: 'T', sourceBranch: 'f', reviewers: ['Dien'] });
+        assert.deepEqual((postOf(calls)?.body).reviewers, [{ uuid: member(0).uuid }]);
+    });
+    test('C7: 400 surfaces the Bitbucket error message', async () => {
+        stubRoutes(() => ({
+            status: 400,
+            body: { type: 'error', error: { message: 'There are no changes to be pulled' } },
+        }));
+        const text = (await handleCreateBitbucketPr({ repository: 'acme/web-app', title: 'T', sourceBranch: 'f' }))
+            .content[0].text;
+        assert.match(text, /API error 400: There are no changes to be pulled/);
+    });
+});
+describe('handleFindBitbucketReviewers', () => {
+    test('F1: reports matched, skipped-self, ambiguous and unknown names', async () => {
+        stubRoutes(bitbucketRoutes());
+        const text = (await handleFindBitbucketReviewers({ names: ['Dien', 'Hanh', 'Dung', 'Zed'] })).content[0].text;
+        assert.match(text, /## Reviewer lookup \(acme\)/);
+        assert.match(text, /✅ Trần Văn Điền \(@dientv\) \{aaaaaaaa-0000-0000-0000-000000000001\}/);
+        assert.match(text, /PR author\) were named — skipped/);
+        assert.match(text, /"Dung" matches 2 members/);
+        assert.match(text, /"Zed" matches no workspace member/);
+    });
+    test('F2: an invalid workspace slug is rejected before any request', async () => {
+        const calls = stubRoutes(bitbucketRoutes());
+        const text = (await handleFindBitbucketReviewers({ names: ['Dien'], workspace: '../x' })).content[0].text;
+        assert.equal(calls.length, 0);
+        assert.match(text, /Invalid workspace slug/);
+    });
+});
+function comment(id, extra = {}) {
+    return {
+        id,
+        created_on: '2026-10-01T10:00:00Z',
+        content: { raw: `body ${id}` },
+        user: { display_name: `user${id}` },
+        deleted: false,
+        ...extra,
+    };
+}
+describe('handleGetBitbucketPrComments', () => {
+    test('M1: follows next links and threads general + inline comments', async () => {
+        const calls = stubFetch([
+            {
+                status: 200,
+                body: {
+                    values: [comment(1), comment(2, { inline: { path: 'src/a.ts', to: 12 } })],
+                    next: `${API}/repositories/acme/web-app/pullrequests/42/comments?pagelen=100&page=2`,
+                },
+            },
+            {
+                status: 200,
+                body: {
+                    values: [
+                        comment(3, { parent: { id: 2 }, inline: { path: 'src/a.ts', to: 12 } }),
+                        comment(4, {
+                            inline: { path: 'src/b.ts', from: 5 },
+                            resolution: { type: 'comment_resolution', user: { display_name: 'Ann' } },
+                        }),
+                    ],
+                },
+            },
+        ]);
+        const text = (await handleGetBitbucketPrComments({ input: PR_URL })).content[0].text;
+        assert.equal(calls.length, 2);
+        assert.equal(calls[0].url, `${API}/repositories/acme/web-app/pullrequests/42/comments?pagelen=100`);
+        assert.match(text, /4 comments in 3 threads · 2 open · 1 resolved/);
+        assert.match(text, /### General\n- \*\*#1 · user1 · 2026-10-01 · 🟡 open\*\*\n  > body 1/);
+        assert.match(text, /#### `src\/a.ts`\n- \*\*#2 · user2 · 2026-10-01 · line 12 · 🟡 open\*\*/);
+        assert.match(text, /  ↳ \*\*#3 · user3 · 2026-10-01\*\*\n    > body 3/);
+        assert.match(text, /#4 · user4 · 2026-10-01 · old line 5 · ✅ resolved by Ann/);
+    });
+    test('M2: includeResolved=false hides resolved threads', async () => {
+        stubFetch([
+            {
+                status: 200,
+                body: { values: [comment(1), comment(2, { resolution: { type: 'comment_resolution' } })] },
+            },
+        ]);
+        const text = (await handleGetBitbucketPrComments({ input: PR_URL, includeResolved: false })).content[0].text;
+        assert.match(text, /#1 /);
+        assert.doesNotMatch(text, /#2 /);
+    });
+    test('M3: deleted comments are hidden unless they carry replies', async () => {
+        stubFetch([
+            {
+                status: 200,
+                body: {
+                    values: [comment(1, { deleted: true }), comment(2, { deleted: true }), comment(3, { parent: { id: 2 } })],
+                },
+            },
+        ]);
+        const text = (await handleGetBitbucketPrComments({ input: PR_URL })).content[0].text;
+        assert.doesNotMatch(text, /#1 /);
+        assert.match(text, /#2 [^\n]*\n  > _\(deleted\)_/);
+        assert.match(text, /↳ \*\*#3 /);
+    });
+    test('M4: a next link to another host is never followed', async () => {
+        const calls = stubFetch([{ status: 200, body: { values: [comment(1)], next: 'https://evil.example/steal' } }]);
+        await handleGetBitbucketPrComments({ input: PR_URL });
+        assert.equal(calls.length, 1);
+    });
+    test('M5: stops at the page cap and says so', async () => {
+        const calls = stubFetch([
+            {
+                status: 200,
+                body: { values: [comment(1)], next: `${API}/repositories/acme/web-app/pullrequests/42/comments?page=n` },
+            },
+        ]);
+        const text = (await handleGetBitbucketPrComments({ input: PR_URL })).content[0].text;
+        assert.equal(calls.length, MAX_PAGES);
+        assert.match(text, /Stopped after 20 pages/);
+    });
+    test('M7: a 403 appends the scopes the tool needs', async () => {
+        stubFetch([{ status: 403, body: {} }]);
+        const text = (await handleGetBitbucketPrComments({ input: PR_URL })).content[0].text;
+        assert.match(text, /Access denied \(403\)/);
+        assert.match(text, /Check the API token has these scopes: read:pullrequest:bitbucket\./);
+    });
+    test('M6: 404 maps to a not-found message', async () => {
+        stubFetch([{ status: 404, body: { type: 'error', error: { message: 'nope' } } }]);
+        const text = (await handleGetBitbucketPrComments({ input: PR_URL })).content[0].text;
+        assert.match(text, /Not found/);
+    });
+});

package/dist/mcp/confluence.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mcp/confluence.test.js

@@ -0,0 +1,258 @@
+import * as assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import { afterEach, describe, mock, test } from 'node:test';
+import { LARGE_PAYLOAD_THRESHOLD, handleConfluenceGetPage, resolveConfluencePageId } from './integration.js';
+const PAGE_ID = '123456789';
+const PAGE_URL = `https://acme.atlassian.net/wiki/spaces/ENG/pages/${PAGE_ID}/Some+Page+Title`;
+const BLOG_URL = 'https://acme.atlassian.net/wiki/spaces/ENG/blog/2026/01/15/987654321/Post+Title';
+const TINY_URL = 'https://acme.atlassian.net/wiki/x/AbCdEf';
+// Credentials resolve through process.env first, which is enough for these tests: every
+// case here supplies credentials rather than asserting their absence.
+process.env.ATLASSIAN_CLOUD_ID = 'cloud-a';
+process.env.ATLASSIAN_USER_EMAIL = 'dev@acme.test';
+process.env.CONFLUENCE_API_TOKEN = 'confluence-token';
+/** Replace the global fetch for one test; `afterEach` restores it. */
+function stubFetch(status, body) {
+    const calls = [];
+    const authHeaders = [];
+    mock.method(globalThis, 'fetch', async (input, init) => {
+        calls.push(String(input));
+        authHeaders.push(String(init?.headers?.Authorization ?? ''));
+        return new Response(typeof body === 'string' ? body : JSON.stringify(body), {
+            status,
+            headers: { 'content-type': 'application/json' },
+        });
+    });
+    return { calls, authHeaders };
+}
+const spilledFiles = [];
+afterEach(() => {
+    mock.restoreAll();
+    while (spilledFiles.length > 0) {
+        const file = spilledFiles.pop();
+        if (file)
+            fs.rmSync(file, { force: true });
+    }
+});
+/** Decode the `email:token` pair a Basic auth header carries. */
+function decodeBasicAuth(header) {
+    return Buffer.from(header.replace('Basic ', ''), 'base64').toString('utf8');
+}
+function pageFixture(overrides = {}) {
+    return {
+        id: PAGE_ID,
+        title: 'Design Notes',
+        status: 'current',
+        spaceId: '98765',
+        version: { number: 7, createdAt: '2026-07-01T10:00:00.000Z' },
+        body: { storage: { value: '<p>Hello <strong>world</strong></p>' } },
+        labels: { results: [{ name: 'design' }, { name: 'api' }] },
+        _links: { base: 'https://acme.atlassian.net/wiki', webui: `/spaces/ENG/pages/${PAGE_ID}/Design+Notes` },
+        ...overrides,
+    };
+}
+async function textFor(input) {
+    return (await handleConfluenceGetPage({ input })).content[0].text;
+}
+async function successText(page) {
+    stubFetch(200, page);
+    return textFor(PAGE_URL);
+}
+describe('resolveConfluencePageId (BC2, BC5, BC6, BC7)', () => {
+    test('H1: full page URL with a title segment resolves to the numeric id', () => {
+        assert.deepEqual(resolveConfluencePageId(PAGE_URL), { kind: 'id', pageId: PAGE_ID });
+    });
+    test('H2: page URL with a query string and fragment but no title segment resolves', () => {
+        const url = `https://acme.atlassian.net/wiki/spaces/ENG/pages/${PAGE_ID}?focusedCommentId=99#anchor`;
+        assert.deepEqual(resolveConfluencePageId(url), { kind: 'id', pageId: PAGE_ID });
+    });
+    test('H3: legacy viewpage.action form resolves from the pageId query parameter', () => {
+        const url = `https://acme.atlassian.net/pages/viewpage.action?pageId=${PAGE_ID}`;
+        assert.deepEqual(resolveConfluencePageId(url), { kind: 'id', pageId: PAGE_ID });
+    });
+    test('H4: bare numeric id resolves', () => {
+        assert.deepEqual(resolveConfluencePageId(PAGE_ID), { kind: 'id', pageId: PAGE_ID });
+    });
+    test('H8: blog URL is classified as blog, never as an id from its date segments', () => {
+        const resolution = resolveConfluencePageId(BLOG_URL);
+        assert.equal(resolution.kind, 'blog');
+        assert.notEqual(resolution.kind, 'id');
+        const serialised = JSON.stringify(resolution);
+        assert.ok(!serialised.includes('2026'), 'a date segment must never become a page id');
+        assert.ok(!serialised.includes('987654321'), 'a blog post id must never become a page id');
+    });
+});
+describe('handleConfluenceGetPage — pre-network error paths (BC5, BC6, BC7, BC8)', () => {
+    test('H5: tiny link errors before any network call and asks for the full page URL', async () => {
+        assert.deepEqual(resolveConfluencePageId(TINY_URL), { kind: 'tiny' });
+        const { calls } = stubFetch(200, pageFixture());
+        const text = await textFor(TINY_URL);
+        assert.equal(calls.length, 0, 'MUST NOT call fetch for a tiny link');
+        assert.match(text, /tiny link/i);
+        assert.match(text, /full page URL/i);
+    });
+    test('H6: blog URL errors before any network call', async () => {
+        const { calls } = stubFetch(200, pageFixture());
+        const text = await textFor(BLOG_URL);
+        assert.equal(calls.length, 0, 'MUST NOT call fetch for a blog URL');
+        assert.match(text, /blog posts are not supported/i);
+    });
+    test('H7: unrecognised input errors before any network call and lists accepted forms', async () => {
+        assert.deepEqual(resolveConfluencePageId('not a confluence link at all'), { kind: 'unknown' });
+        const { calls } = stubFetch(200, pageFixture());
+        const text = await textFor('not a confluence link at all');
+        assert.equal(calls.length, 0, 'MUST NOT call fetch for unrecognised input');
+        assert.match(text, /Accepted input forms/);
+        assert.match(text, /viewpage\.action\?pageId=/);
+        assert.match(text, /numeric page ID/);
+    });
+});
+describe('handleConfluenceGetPage — happy path output (BC3)', () => {
+    test('H13: renders the full brief in exactly one request', async () => {
+        const { calls, authHeaders } = stubFetch(200, pageFixture());
+        const text = await textFor(PAGE_URL);
+        assert.equal(calls.length, 1, 'exactly one HTTP request — no space or user lookup');
+        assert.ok(calls[0].includes('/ex/confluence/cloud-a/'), `must use the shared cloud id, got: ${calls[0]}`);
+        assert.equal(decodeBasicAuth(authHeaders[0]), 'dev@acme.test:confluence-token', 'Confluence must authenticate with the shared email and its own token, not the Jira token');
+        assert.ok(calls[0].includes('body-format=storage'), `got: ${calls[0]}`);
+        assert.ok(calls[0].includes('include-labels=true'), `got: ${calls[0]}`);
+        assert.ok(calls[0].includes('include-version=true'), `got: ${calls[0]}`);
+        assert.match(text, /Design Notes/);
+        assert.match(text, /\*\*Status:\*\* current/);
+        assert.match(text, /\*\*Space:\*\* ENG/);
+        assert.match(text, /\*\*Version:\*\* 7/);
+        assert.match(text, /\*\*Last updated:\*\* 2026-07-01T10:00:00\.000Z/);
+        assert.match(text, new RegExp(`\\*\\*URL:\\*\\* https://acme\\.atlassian\\.net/wiki/spaces/ENG/pages/${PAGE_ID}/Design\\+Notes`));
+        assert.match(text, /### Content\nHello \*\*world\*\*/);
+        assert.match(text, /### Labels\ndesign, api/);
+    });
+    test('H14: space line is omitted, never guessed, when webui has no /spaces/<KEY>/', async () => {
+        const text = await successText(pageFixture({ _links: { base: 'https://acme.atlassian.net/wiki', webui: '/foo/bar' } }));
+        assert.ok(!text.includes('**Space:**'), `space line must be omitted, got: ${text}`);
+        assert.ok(!text.includes('98765'), 'spaceId must never be presented as a space key');
+        assert.match(text, /\*\*URL:\*\* https:\/\/acme\.atlassian\.net\/wiki\/foo\/bar/);
+    });
+});
+describe('handleConfluenceGetPage — distinct HTTP and schema errors (BC9)', () => {
+    async function errorText(status, body = { message: 'nope' }) {
+        stubFetch(status, body);
+        return textFor(PAGE_URL);
+    }
+    test('H15: 401 identifies an auth failure', async () => {
+        const text = await errorText(401);
+        assert.match(text, /401/);
+        assert.match(text, /Auth failed/i);
+        assert.ok(!/Not found/i.test(text), '401 must be distinct from the 404 message');
+    });
+    test('H16: 403 mentions permission or restriction and is distinct from 404', async () => {
+        const text = await errorText(403);
+        assert.match(text, /403/);
+        assert.match(text, /permission|restricted/i);
+        assert.ok(!/Not found/i.test(text), '403 must be distinct from the 404 message');
+    });
+    test('H17: 404 identifies not-found and is distinct from 403', async () => {
+        const text = await errorText(404);
+        assert.match(text, /Not found/i);
+        assert.ok(!text.includes('403'), '404 must be distinct from the 403 message');
+    });
+    test('H18: other non-OK statuses include the status code', async () => {
+        const text = await errorText(500);
+        assert.match(text, /500/);
+        assert.ok(!/Auth failed/i.test(text), '500 must be distinct from 401');
+        assert.ok(!/Not found/i.test(text), '500 must be distinct from 404');
+        assert.ok(!/permission|restricted/i.test(text), '500 must be distinct from 403');
+    });
+    test('H19: a 200 missing title is reported as an invalid response format', async () => {
+        const { title: _title, ...withoutTitle } = pageFixture();
+        const text = await successText(withoutTitle);
+        assert.match(text, /Invalid Confluence response format/);
+        assert.ok(!text.includes('### Content'), 'a schema failure must not be presented as partial success');
+    });
+});
+describe('handleConfluenceGetPage — empty and unconvertible bodies (BC10)', () => {
+    const EXPECTED_URL = `https://acme.atlassian.net/wiki/spaces/ENG/pages/${PAGE_ID}/Design+Notes`;
+    function assertEmptyWarning(text, status) {
+        assert.match(text, /⚠️ Confluence returned no readable body/);
+        assert.ok(text.includes(`status: ${status}`), `warning must name the page status, got: ${text}`);
+        assert.ok(text.includes(EXPECTED_URL), `warning must include the absolute URL, got: ${text}`);
+        assert.ok(!/### Content\n\s*\n/.test(text), 'MUST NOT emit an empty Content section as if it were success');
+    }
+    test('H20: body: {} (the documented Atlassian defect) warns explicitly', async () => {
+        assertEmptyWarning(await successText(pageFixture({ body: {} })), 'current');
+    });
+    test('H21: an empty storage value warns explicitly', async () => {
+        assertEmptyWarning(await successText(pageFixture({ body: { storage: { value: '' } } })), 'current');
+    });
+    test('H22: a body that converts to whitespace only warns explicitly', async () => {
+        assertEmptyWarning(await successText(pageFixture({ body: { storage: { value: '<p>&nbsp;</p>' } } })), 'current');
+    });
+    test('H23: a trashed page names its status in the warning', async () => {
+        const text = await successText(pageFixture({ status: 'trashed', body: {} }));
+        assertEmptyWarning(text, 'trashed');
+        assert.match(text, /\*\*Status:\*\* trashed/);
+    });
+});
+describe('handleConfluenceGetPage — oversize bodies spill to a temp file (BC11)', () => {
+    const HUGE_TEXT = 'x'.repeat(LARGE_PAYLOAD_THRESHOLD + 10);
+    test('H24: the body is written to /tmp and referenced, not inlined', async () => {
+        stubFetch(200, pageFixture({ body: { storage: { value: `<p>${HUGE_TEXT}</p>` } } }));
+        const text = await textFor(PAGE_URL);
+        const spilledPath = text.match(new RegExp(`/tmp/kit-confluence-${PAGE_ID}-\\d+\\.md`))?.[0];
+        assert.ok(spilledPath, `output must reference a temp path, got: ${text.slice(0, 300)}`);
+        spilledFiles.push(spilledPath);
+        assert.ok(fs.existsSync(spilledPath), 'the temp file must actually be written');
+        assert.ok(fs.readFileSync(spilledPath, 'utf8').includes(HUGE_TEXT), 'the temp file must hold the markdown');
+        assert.ok(!text.includes(HUGE_TEXT), 'MUST NOT inline the body once it has been spilled');
+    });
+});
+describe('handleConfluenceGetPage — secret redaction and labels (BC19, BC20)', () => {
+    test('H26: a pasted AWS key in the page body is redacted', async () => {
+        const secret = 'AKIAABCDEFGHIJKLMNOP';
+        const text = await successText(pageFixture({ body: { storage: { value: `<p>key ${secret} here</p>` } } }));
+        assert.match(text, /\[REDACTED\]/);
+        assert.ok(!text.includes(secret), 'the raw token MUST NOT reach the agent context');
+    });
+    test('H27: absent labels render None', async () => {
+        const { labels: _labels, ...withoutLabels } = pageFixture();
+        assert.match(await successText(withoutLabels), /### Labels\nNone/);
+    });
+    test('H28: an empty labels result renders None', async () => {
+        assert.match(await successText(pageFixture({ labels: { results: [] } })), /### Labels\nNone/);
+    });
+    test('H29: multiple labels render comma-joined', async () => {
+        assert.match(await successText(pageFixture()), /### Labels\ndesign, api/);
+    });
+});
+describe('handleConfluenceGetPage — never rejects (H30)', () => {
+    test('H30: every error and success scenario resolves to a valid mcpText envelope', async () => {
+        const scenarios = [
+            { label: 'tiny link', input: TINY_URL, status: 200, body: pageFixture() },
+            { label: 'blog URL', input: BLOG_URL, status: 200, body: pageFixture() },
+            { label: 'unrecognised', input: 'nonsense', status: 200, body: pageFixture() },
+            ...[401, 403, 404, 500].map((status) => ({
+                label: `HTTP ${status}`,
+                input: PAGE_URL,
+                status,
+                body: { message: 'nope' },
+            })),
+            { label: 'schema mismatch', input: PAGE_URL, status: 200, body: { id: PAGE_ID } },
+            { label: 'empty body', input: PAGE_URL, status: 200, body: pageFixture({ body: {} }) },
+            {
+                label: 'malformed body markup',
+                input: PAGE_URL,
+                status: 200,
+                body: pageFixture({ body: { storage: { value: '<p><strong>oops</p><![CDATA[' } } }),
+            },
+            { label: 'happy path', input: PAGE_URL, status: 200, body: pageFixture() },
+        ];
+        for (const scenario of scenarios) {
+            stubFetch(scenario.status, scenario.body);
+            const result = await handleConfluenceGetPage({ input: scenario.input });
+            assert.equal(result.content.length, 1, `${scenario.label}: expected one content entry`);
+            assert.equal(result.content[0].type, 'text', `${scenario.label}: expected a text envelope`);
+            assert.equal(typeof result.content[0].text, 'string', `${scenario.label}: expected string text`);
+            assert.ok(result.content[0].text.length > 0, `${scenario.label}: expected a non-empty message`);
+            mock.restoreAll();
+        }
+    });
+});