@productbrain/cli 0.1.0-beta.14 → 0.1.0-beta.14010

package/dist/__tests__/rate-limit-resilience.test.js

@@ -0,0 +1,191 @@
+/**
+ * WP-579 — rate-limit resilience: touch throttle + backoff/retry (TEN-2923, TEN-2924).
+ * DEC-2108 (TASK-883): one back-off per command, honouring Retry-After, never one per sub-call.
+ *
+ * Mirrors the mock/module-mock conventions of envelope-contract.test.ts.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+// ─── Module mocks (must precede imports that trigger side effects) ────────────
+vi.mock('../lib/config.js', () => ({
+    getConfig: vi.fn(() => ({
+        apiKey: 'pb_sk_test',
+        siteUrl: 'https://example.convex.site',
+    })),
+}));
+vi.mock('../lib/adminConfig.js', () => ({
+    resolveAdminConfig: vi.fn(),
+}));
+let mockSession = { sessionId: 'session-1' };
+vi.mock('../lib/session.js', () => ({
+    readSession: vi.fn(() => mockSession),
+    writeSession: vi.fn(),
+    clearSession: vi.fn(),
+    addCapturedEntry: vi.fn(),
+}));
+vi.mock('../lib/spinner.js', () => ({
+    withSpinner: vi.fn((_label, fn) => fn()),
+}));
+vi.mock('../lib/update-check.js', () => ({
+    recordServerLatest: vi.fn(),
+}));
+// ─── Imports (after mocks) ────────────────────────────────────────────────────
+import { kernelCall, kernelCallWithSession, resetRateLimitBackoff, resetTouchThrottle } from '../lib/client.js';
+function successResponse(data = {}) {
+    return {
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        json: async () => ({ ok: true, data }),
+        headers: { get: () => null },
+    };
+}
+function rateLimitedResponse(retryAfterSeconds) {
+    return {
+        ok: false,
+        status: 429,
+        statusText: 'Too Many Requests',
+        json: async () => ({
+            ok: false,
+            code: 'rate-limited',
+            message: `Rate limit exceeded for this API key. Retry after ${retryAfterSeconds}s.`,
+            retryAfterSeconds,
+        }),
+        headers: { get: (name) => (name === 'Retry-After' ? String(retryAfterSeconds) : null) },
+    };
+}
+function validationFailedResponse() {
+    return {
+        ok: false,
+        status: 400,
+        statusText: 'Bad Request',
+        json: async () => ({ ok: false, code: 'VALIDATION_FAILED', message: 'Bad input' }),
+        headers: { get: () => null },
+    };
+}
+// Two describes below switch on fake timers. Restore real ones after every test so timer
+// state can't leak into a later test in this file (the throttle describe runs first today,
+// but that ordering is not a contract).
+afterEach(() => {
+    vi.useRealTimers();
+});
+describe('kernelCall — one back-off per command on 429 (DEC-2108, TEN-5073)', () => {
+    let stderr;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.useFakeTimers();
+        resetRateLimitBackoff();
+        stderr = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    });
+    afterEach(() => stderr.mockRestore());
+    it('waits the server-given seconds once, says so, then retries and succeeds', async () => {
+        let callCount = 0;
+        global.fetch = vi.fn(async () => {
+            callCount += 1;
+            return callCount === 1 ? rateLimitedResponse(7) : successResponse({ id: 'ENT-1' });
+        });
+        const resultPromise = kernelCall('chain.getEntry', {});
+        await vi.advanceTimersByTimeAsync(6_900);
+        expect(callCount).toBe(1); // still waiting: Retry-After is honoured, not guessed
+        await vi.advanceTimersByTimeAsync(400);
+        expect(await resultPromise).toEqual({ id: 'ENT-1' });
+        expect(callCount).toBe(2);
+        expect(stderr).toHaveBeenCalledWith('Rate limited: waiting 7s once, then retrying.\n');
+    });
+    it('a call still refused after the back-off fails with the kernel message, two attempts in all', async () => {
+        let callCount = 0;
+        global.fetch = vi.fn(async () => {
+            callCount += 1;
+            return rateLimitedResponse(1);
+        });
+        const resultPromise = kernelCall('chain.getEntry', {}).catch((err) => err);
+        await vi.advanceTimersByTimeAsync(20_000);
+        const err = await resultPromise;
+        expect(err.message).toBe('Rate limit exceeded for this API key. Retry after 1s.');
+        expect(callCount).toBe(2);
+    });
+    it('a later sub-call in the same command fails at once: no second back-off, no timer', async () => {
+        let callCount = 0;
+        global.fetch = vi.fn(async () => {
+            callCount += 1;
+            return callCount === 1 ? rateLimitedResponse(1) : callCount === 2 ? successResponse({}) : rateLimitedResponse(1);
+        });
+        const first = kernelCall('chain.listCollections', {});
+        await vi.advanceTimersByTimeAsync(1_500);
+        await first;
+        expect(callCount).toBe(2);
+        const err = await kernelCall('chain.createEntry', {}).catch((e) => e);
+        expect(err.message).toContain('Rate limit exceeded');
+        expect(callCount).toBe(3);
+        expect(vi.getTimerCount()).toBe(0);
+    });
+    it('never retries a non-rate-limited failure (e.g. VALIDATION_FAILED)', async () => {
+        let callCount = 0;
+        global.fetch = vi.fn(async () => {
+            callCount += 1;
+            return validationFailedResponse();
+        });
+        await expect(kernelCall('chain.createEntry', {})).rejects.toThrow('Bad input');
+        expect(callCount).toBe(1);
+    });
+    it('does not sit on a Retry-After over 60 s: surfaces it instead of sleeping', async () => {
+        let callCount = 0;
+        global.fetch = vi.fn(async () => {
+            callCount += 1;
+            return rateLimitedResponse(86_400);
+        });
+        const err = await kernelCall('chain.getEntry', {}).catch((e) => e);
+        expect(err.message).toContain('Rate limit exceeded');
+        expect(callCount).toBe(1);
+        expect(vi.getTimerCount()).toBe(0);
+    });
+});
+describe('kernelCallWithSession — background calls opt out of retry (TEN-2924)', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.useFakeTimers();
+        resetTouchThrottle();
+        resetRateLimitBackoff();
+        mockSession = { sessionId: 'session-1' };
+    });
+    it('never arms a retry timer when retryOnRateLimit is false', async () => {
+        let callCount = 0;
+        global.fetch = vi.fn(async () => {
+            callCount += 1;
+            return rateLimitedResponse(1);
+        });
+        const err = await kernelCallWithSession('chain.recordGroundingOutcome', {}, { retryOnRateLimit: false }).catch((e) => e);
+        expect(err).toBeInstanceOf(Error);
+        // One attempt, and crucially no pending timer left holding the event loop open.
+        expect(callCount).toBe(1);
+        expect(vi.getTimerCount()).toBe(0);
+    });
+    // Codex round 2 found capture.ts was not the only detached call site. Sweep of every
+    // kernelCall* whose promise is neither awaited nor returned: capture.ts (grounding),
+    // brief.ts (recordBriefRun), handshake.ts x2 (drift + collision TENs; handshake.ts is since
+    // deleted). All four then opted out. This pins the class rather than the instances — a detached call that keeps the
+    // retry arms timers that outlive the command's foreground work.
+    it('arms no timer for kernelCall either — the detached brief.ts shape', async () => {
+        let callCount = 0;
+        global.fetch = vi.fn(async () => {
+            callCount += 1;
+            return rateLimitedResponse(1);
+        });
+        const err = await kernelCall('chain.recordBriefRun', {}, { retryOnRateLimit: false }).catch((e) => e);
+        expect(err).toBeInstanceOf(Error);
+        expect(callCount).toBe(1);
+        expect(vi.getTimerCount()).toBe(0);
+    });
+    it('still retries by default when no options are passed', async () => {
+        // TASK-894: the session touch rides the write as a header, so every request here is the write.
+        let writeCalls = 0;
+        global.fetch = vi.fn(async () => {
+            writeCalls += 1;
+            return writeCalls === 1 ? rateLimitedResponse(1) : successResponse({ id: 'ENT-2' });
+        });
+        const resultPromise = kernelCallWithSession('chain.createEntry', {});
+        await vi.advanceTimersByTimeAsync(2000);
+        expect(await resultPromise).toEqual({ id: 'ENT-2' });
+        expect(writeCalls).toBe(2);
+    });
+});
+//# sourceMappingURL=rate-limit-resilience.test.js.map

package/dist/__tests__/rate-limit-resilience.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit-resilience.test.js","sourceRoot":"","sources":["../../src/__tests__/rate-limit-resilience.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/read-target-notice.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=read-target-notice.test.d.ts.map

package/dist/__tests__/read-target-notice.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-target-notice.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/read-target-notice.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/read-target-notice.test.js

@@ -0,0 +1,125 @@
+/**
+ * WP-714 S3 — read commands announce their effective tenant too.
+ * TEN-3398 (WP-711 follow-up) — the write path (`kernelCallWithSession`) announces too, closing
+ * the gap this file used to assert as intentional (see the last two tests below).
+ *
+ * Before WP-714 S3, `emitEffectiveTenantNotice` was called only from the 8 explicit write call
+ * sites (relate x2, restore, organisationWrite, promote, capture, session, update) — every
+ * plain read (`pb get`/`search`/`orient`/`context`/`brief`/`constellation`/...) went through
+ * `client.ts`'s `kernelCall` silently. Before TEN-3398, `kernelCallWithSession`
+ * itself never called the notice at all — a write command that was not one of those 8 explicit
+ * call sites (e.g. `chain.verifyEntry`/`rework.report`) was silent. This file exercises the REAL
+ * `kernelCall`/`kernelCallWithSession` implementations from client.ts —
+ * only their dependencies (config, session, sessionBinding, reportedProfile, fetch) are
+ * mocked — so removing the notice call from either path, or the once-per-process guard, turns
+ * one of these red. Mirrors the mocking shape of `client-binding-guard.test.ts` (WP-711/712),
+ * which proved the binding guard the same way.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+const assertSessionStillBoundMock = vi.fn();
+const readSessionMock = vi.fn();
+const readSessionBySessionIdMock = vi.fn();
+const getConfigMock = vi.fn();
+const resolveEffectiveProfileMock = vi.fn();
+vi.mock('../lib/config.js', () => ({
+    getConfig: (...args) => getConfigMock(...args),
+    resolveEffectiveProfile: (...args) => resolveEffectiveProfileMock(...args),
+}));
+vi.mock('../lib/session.js', () => ({
+    readSession: (...args) => readSessionMock(...args),
+    readSessionBySessionId: (...args) => readSessionBySessionIdMock(...args),
+}));
+vi.mock('../lib/sessionBinding.js', () => ({
+    assertSessionStillBound: (...args) => assertSessionStillBoundMock(...args),
+}));
+const effectiveState = { value: { profile: 'funcode', source: 'local' } };
+vi.mock('../lib/reportedProfile.js', () => ({
+    resolveReportedProfile: () => effectiveState.value,
+}));
+// `readLocalProjectConfig` is only reached via `resolveShadowedPin` (env-key/cwd-key/local-key
+// sources, none of which this file exercises) — kept inert so these tests isolate the read-path
+// wiring.
+vi.mock('../lib/projectConfig.js', () => ({ readLocalProjectConfig: () => null }));
+import { kernelCall, kernelCallWithSession } from '../lib/client.js';
+import { resetEffectiveTenantNoticeForTests } from '../lib/workspaceNotice.js';
+import { setOutputMode } from '../lib/runner.js';
+describe('read path announces the effective tenant (WP-714 S3)', () => {
+    let fetchSpy;
+    let stderr;
+    let stderrSpy;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        resetEffectiveTenantNoticeForTests();
+        assertSessionStillBoundMock.mockImplementation(() => { });
+        getConfigMock.mockReturnValue({ apiKey: 'pb_sk_test', siteUrl: 'https://test.convex.site' });
+        readSessionMock.mockReturnValue(null);
+        effectiveState.value = { profile: 'funcode', source: 'local' };
+        setOutputMode('pretty'); // deterministic: not gated by TTY auto-detection in a test runner.
+        fetchSpy = vi.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            headers: { get: () => null },
+            json: async () => ({ ok: true, data: { hello: 'world' } }),
+        });
+        vi.stubGlobal('fetch', fetchSpy);
+        stderr = [];
+        stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation((c) => { stderr.push(String(c)); return true; });
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        stderrSpy.mockRestore();
+        setOutputMode('auto');
+    });
+    it('doneWhen 1/6: kernelCall (the plain read path) announces the effective tenant — delete the call and this goes red', async () => {
+        await kernelCall('chain.getEntry', { entryId: 'X-1' });
+        expect(stderr.join('')).toBe('→ funcode\n');
+    });
+    it('doneWhen 4: a command making several kernel calls (like `pb orient`) emits exactly one notice', async () => {
+        await kernelCall('chain.getVocabulary', {});
+        await kernelCall('chain.getOrientView', { tier: 'standard' });
+        await kernelCall('agent.markOriented', { sessionId: 'sess-1' });
+        expect(fetchSpy).toHaveBeenCalledTimes(3); // three real kernel calls happened...
+        const lines = stderr.join('').split('\n').filter((l) => l.startsWith('→'));
+        expect(lines).toHaveLength(1); // ...but the notice printed exactly once.
+    });
+    // WP-721 (reverses WP-714 S3's doneWhen 5, which asserted the OPPOSITE): a `--json` read on an
+    // explicit (local) binding announces its tenant on stderr, identically to the pretty read.
+    // The suppressed form shipped live on `@productbrain/cli@0.1.0-beta.5421` as a ZERO-BYTE
+    // stderr for `pb get WP-711 --json` in a correctly pinned repo — no tenant signal at all for
+    // the CLI's primary consumer. This is the read-path half of the regression pin in
+    // workspaceNotice.test.ts; delete the fix and this goes red at `jsonStderr`.
+    it('WP-721: a --json read on an explicit (local) binding announces its tenant — same stderr as pretty', async () => {
+        setOutputMode('pretty');
+        await kernelCall('chain.getEntry', { entryId: 'X-1' });
+        const prettyStderr = stderr.join('');
+        resetEffectiveTenantNoticeForTests();
+        stderr.length = 0;
+        setOutputMode('json');
+        await kernelCall('chain.getEntry', { entryId: 'X-1' });
+        const jsonStderr = stderr.join('');
+        expect(prettyStderr).toBe('→ funcode\n');
+        expect(jsonStderr).toBe('→ funcode\n');
+        // The identity line is mode-independent now: the ONLY thing `--json` ever governed here was
+        // whether an agent could see which Chain its read hit.
+        expect(jsonStderr).toBe(prettyStderr);
+    });
+    // TEN-3398 (WP-711 follow-up): this used to assert the OPPOSITE — that kernelCallWithSession
+    // never announces, because "every write command already calls this explicitly" (a premise
+    // that was false: verify.ts, rework.ts, and 9 other write commands never called it at all —
+    // see the corrected doc comment on workspaceNotice.ts's emitEffectiveTenantNotice). The write
+    // path now shares the SAME notice call site as the read path.
+    it('DOES auto-announce from kernelCallWithSession too — the write path shares the read path\'s notice call site (TEN-3398)', async () => {
+        resolveEffectiveProfileMock.mockReturnValue({ profile: 'funcode', source: 'local' });
+        await kernelCallWithSession('chain.createEntry', { description: 'x' });
+        expect(stderr.join('')).toBe('→ funcode\n');
+    });
+    it('the 8 pre-existing explicit write call sites still print exactly once — kernelCallWithSession\'s own (later) attempt is a no-op under the once-per-process guard', async () => {
+        // Mirrors what capture.ts/relate.ts/etc. do: call the notice explicitly BEFORE the write.
+        const { emitEffectiveTenantNotice } = await import('../lib/workspaceNotice.js');
+        await emitEffectiveTenantNotice(); // the command's own explicit, earlier call
+        await kernelCallWithSession('chain.createEntry', { description: 'x' }); // its internal call
+        const lines = stderr.join('').split('\n').filter((l) => l.startsWith('→'));
+        expect(lines).toHaveLength(1);
+    });
+});
+//# sourceMappingURL=read-target-notice.test.js.map

package/dist/__tests__/read-target-notice.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-target-notice.test.js","sourceRoot":"","sources":["../../src/__tests__/read-target-notice.test.ts"],"names":[],"mappings":"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"}