@rockhopper-co/mcp-server 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -4,7 +4,140 @@ All notable changes to this project are documented here. Follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.5.0] — 2026-05-12
+## [Unreleased]
+
+### Fixed
+- **`get_cell_history`, `resolve_comment`, and `rename_file` no longer
+  render `undefined` for every field (KI-096).** Diagnosis revealed the
+  formatters were correct — the backend was returning the wrong shape
+  on all three endpoints. Backend PR
+  [#478](https://github.com/Rockhopper-Co/backend/pull/478) fixed the
+  shapes; this PR adopts them:
+  - `getCellHistory` passes `?format=mcp` to opt into the backend's
+    normalized projection (`{versionId, value, changedBy, changedAt}`).
+    Default `format` preserves the raw-CTE shape the frontend cell-
+    history popover consumes — we never call that path.
+  - `resolveComment` + `updateEnrolledFile` continue to call the same
+    URLs but now receive the updated `FileChat` / `EnrolledFile` entity
+    (was TypeORM `UpdateResult`).
+  - `CellHistoryEntry.versionId` retyped `number` → `string` (was a
+    contributing root cause of the `Version undefined` symptom — the
+    backend's semver string never coerced to the declared numeric type).
+- **`api-client.ts`: zod-parse opt-in for response validation
+  (KI-096).** `request<T>(path, init?, responseSchema?)` now accepts an
+  optional zod schema; when supplied, the response is parsed with
+  `safeParse` and any drift throws a useful diagnostic
+  (`Rockhopper API response failed schema check at <path>: <field> —
+  <message>`) instead of silently rendering `undefined` in formatters.
+  Three call sites opt in: `getCellHistory`, `resolveComment`,
+  `updateEnrolledFile`. Other methods stay unchanged; a sweep ticket
+  can migrate them later. New `src/zod-schemas.ts` module holds the
+  per-entity schemas.
+
+### Added
+- **`search_files` `matchIn` parameter.** Optional enum (`name` |
+  `comments` | `versions` | `all`); defaults to `name` for back-compat.
+  Broadens search past file-name substring into comment text
+  (`FileChat.message`) and version descriptions (`FileVersion.description`).
+  Backed by [backend PR #472](https://github.com/Rockhopper-Co/backend/pull/472)
+  / ENG-1383; behavior available once that merges. Closes KI-080.
+- **OAuth device-grant flow (RFC 8628) as default auth.** First launch
+  with no `ROCKHOPPER_TOKEN` env var now prints a verification code +
+  URL to stderr, polls the backend's `/auth/device/{code,token}`
+  endpoints, and persists the resulting bearer token in the OS keychain
+  (Keychain on macOS, Credential Manager on Windows, libsecret on
+  Linux). Subsequent launches reuse the stored token silently. Tokens
+  default to a 60-minute lifetime; on expiry the next launch silently
+  re-runs the flow. `ROCKHOPPER_TOKEN` still takes precedence when set
+  — PAT path preserved for headless / CI scenarios. Backed by
+  [backend PR #473](https://github.com/Rockhopper-Co/backend/pull/473)
+  / ENG-1384. Closes KI-081 / ENG-1444.
+- **`get_unattributed_changes` cursor pagination + cap/summary (KI-097).**
+  File-wide mode now uses the dedicated paginated backend route
+  (`GET /unattributed-changes/paginated/:fileMsId`, added by
+  [backend PR #475](https://github.com/Rockhopper-Co/backend/pull/475) /
+  KI-102) instead of the legacy unpaginated route. The MCP tool gains an
+  optional `cursor` input for round-tripping the backend's cursor.
+  Responses are now capped at 200 displayed rows with a summary line
+  ("Showing X of Y change(s) on this page (Z total across the file)" +
+  top-sheets breakdown) and a pagination hint when more pages or hidden
+  rows are available. Audit measured one file at 12.5 MB / 28k rows on
+  the old route — context-blowing for AI clients; now bounded under
+  the 25k-token MCP limit. Sheet-filter mode (`sheetName` set) is
+  unchanged — it stays unpaginated since sheet size inherently bounds
+  it. Closes KI-097.
+
+### Changed
+- `ROCKHOPPER_TOKEN` is now **optional** (was required). Unset → OAuth.
+  Set → PAT auth path.
+- **`ApiClient.getUnattributedChanges` refactored into two methods**
+  (KI-097): `getUnattributedChangesBySheet(fileMsId, sheetName)` for
+  the sheet-filtered legacy route, and
+  `getUnattributedChangesPaginated(fileMsId, cursor?)` for the new
+  cursor-paginated route. The old combined method is removed. External
+  consumers of `ApiClient` (e.g. `mcp-gateway`) only use `createServer`
+  + `ApiClient` as types, not these methods directly, so the rename has
+  zero blast radius outside this repo.
+
+### Dependencies
+- **`keytar`** (new runtime dep) — OS-native keychain wrapper. Linux
+  requires `libsecret` installed; otherwise the OAuth path errors with
+  a clear remediation message and you must fall back to PAT.
+
+### Changed (breaking)
+- **`update_file_description` renamed to `rename_file`.** The tool always
+  performed a rename (its `name` input wires to backend
+  `PATCH /enrolled-files/:fileMsId`); the old name described non-existent
+  "description" semantics. Customers using the npm-installed local server
+  should update any tool-name allowlists or prompts referencing
+  `update_file_description`. Closes KI-100 / ENG-1439.
+
+### Fixed
+- **`cancel_review` now actually cancels PENDING reviews.** The
+  pre-flight status check at `tools/write-reviews.ts` compared against
+  the lowercase string `'pending'`, but the backend's
+  `ReviewRequestStatus` enum is uppercase (`PENDING`/`APPROVED`/
+  `CANCELLED`). The check always failed → `api.cancelReview()` was never
+  invoked → every cancel returned "cannot be cancelled — status is
+  'PENDING'". Now uses a defensive `.toUpperCase()` comparison so the
+  fix survives future backend casing flips. Closes KI-099 / ENG-1438.
+
+### Internal
+- Test fixtures in `src/__tests__/unit/test-helpers.ts` and
+  `src/__tests__/e2e/fixtures/rockhopper-api-fixtures.ts` updated to use
+  the real backend's uppercase `ReviewRequestStatus` enum values. Prior
+  fixtures used lowercase, which masked KI-099 by being bug-symmetric
+  with the broken code.
+
+### Fixed (bundled — same casing-bug class as KI-099)
+- **`file-overview` prompt no longer mis-classifies APPROVED + CANCELLED
+  reviews as pending.** `prompts/index.ts:180` filtered with lowercase
+  `r.status !== 'approved' && r.status !== 'rejected'`, but
+  `ReviewRequestStatus` is uppercase and contains no `'rejected'` value
+  (`PENDING`/`APPROVED`/`CANCELLED` only). Result: all non-pending
+  reviews were silently counted as pending in the prompt output. Now
+  filters with positive intent — `r.status?.toUpperCase() === 'PENDING'`.
+  Sibling fix to KI-099; same casing-bug class but in a different
+  surface (prompt vs. tool).
+
+### Tooling
+- **`npm run lint` now works.** The `lint` script referenced
+  `eslint src/` but `eslint` was missing from `devDependencies`, so any
+  fresh install silently produced `sh: eslint: command not found`. Added
+  `@eslint/js`, `eslint`, `globals`, and `typescript-eslint` as devDeps
+  and shipped a flat-config `eslint.config.js` that mirrors the
+  `mcp-gateway` repo's setup. Test files relax
+  `@typescript-eslint/no-explicit-any` (mock-stub casts) while production
+  code keeps the rule on. Lint is clean across `src/`.
+
+## [0.6.0] — 2026-05-13
+
+> Released to npm as `0.6.0`. The release branch was prepared with
+> `package.json` at `0.5.0` (set in [PR #37](https://github.com/Rockhopper-Co/mcp-server/pull/37)),
+> but the `release:minor` script ran on top of that and produced `0.6.0`
+> via `npm version minor`. No code differs between the `0.5.0` manifest
+> and the `0.6.0` published artifact — the bump is purely a version-string
+> change. Content below is what shipped.
 
 ### Changed
 - **`resources/list` no longer enumerates per-file instances.** The 4

package/README.md

@@ -6,17 +6,41 @@ MCP (Model Context Protocol) server for Rockhopper. Lets AI tools like Claude, C
 
 - Node.js 18+
 - A Rockhopper account with at least one enrolled file
-- A Personal Access Token (PAT) from Rockhopper
+- (Optional) A Personal Access Token — only required for headless / CI / scripted setups
 
-## Setup
+## Authentication
 
-### 1. Create a Personal Access Token
+The server supports two auth modes. **OAuth (recommended)** is the default — no token to copy and paste. **PAT** stays available for headless scenarios.
 
-In the Rockhopper web app, go to **Settings > Personal Access Tokens** and create a new token. Choose `read-only` scope for read access or `read-write` if you also want to add comments/reviews.
+### OAuth (recommended)
 
-Copy the token — it's shown only once.
+On first launch, the server prints a short verification code to stderr and a URL to visit. Sign in once in your browser — the resulting bearer token is stored in your OS keychain (Keychain on macOS, Credential Manager on Windows, libsecret on Linux). Subsequent launches pick the token up silently.
 
-### 2. Install
+Nothing to configure — just launch the server with no `ROCKHOPPER_TOKEN` set:
+
+```bash
+npx @rockhopper-co/mcp-server
+```
+
+You'll see (on stderr):
+
+```
+Rockhopper — sign in to authorize this MCP client.
+Open: https://app.rockhopper.co/device?user_code=ABCD2345
+(or visit https://app.rockhopper.co/device and enter code: ABCD2345)
+```
+
+Tokens default to a 60-minute lifetime. When yours expires, the next launch silently re-runs the device flow.
+
+> **Linux**: requires `libsecret` to be installed (`apt-get install libsecret-1-dev` on Debian/Ubuntu, `dnf install libsecret` on Fedora). If unavailable, fall back to the PAT path below.
+
+### Personal Access Token (headless / CI)
+
+For non-interactive setups, generate a PAT in the Rockhopper web app under **Settings > Personal Access Tokens** (`read-only` or `read-write` scope) and set it as `ROCKHOPPER_TOKEN`. PATs take precedence over OAuth — if `ROCKHOPPER_TOKEN` is set, the device-grant flow is skipped.
+
+## Setup
+
+### 1. Install
 
 ```bash
 npm install -g @rockhopper-co/mcp-server
@@ -28,7 +52,7 @@ Or run directly with npx:
 npx @rockhopper-co/mcp-server
 ```
 
-### 3. Configure your AI tool
+### 2. Configure your AI tool
 
 #### Claude Desktop / Claude Code
 
@@ -41,7 +65,6 @@ Add to your MCP config (`~/.claude/mcp.json` or Claude Desktop settings):
       "command": "npx",
       "args": ["-y", "@rockhopper-co/mcp-server"],
       "env": {
-        "ROCKHOPPER_TOKEN": "rh_pat_your_token_here",
         "ROCKHOPPER_API_URL": "https://api.rockhopper.co"
       }
     }
@@ -49,6 +72,8 @@ Add to your MCP config (`~/.claude/mcp.json` or Claude Desktop settings):
 }
 ```
 
+Leave `ROCKHOPPER_TOKEN` out to use OAuth (recommended). Set it if you want PAT auth instead.
+
 #### Cursor
 
 Add to `.cursor/mcp.json` in your project:
@@ -60,7 +85,6 @@ Add to `.cursor/mcp.json` in your project:
       "command": "npx",
       "args": ["-y", "@rockhopper-co/mcp-server"],
       "env": {
-        "ROCKHOPPER_TOKEN": "rh_pat_your_token_here",
         "ROCKHOPPER_API_URL": "https://api.rockhopper.co"
       }
     }
@@ -72,7 +96,7 @@ Add to `.cursor/mcp.json` in your project:
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `ROCKHOPPER_TOKEN` | Yes | — | Personal Access Token (starts with `rh_pat_`) |
+| `ROCKHOPPER_TOKEN` | No | — | Personal Access Token (starts with `rh_pat_`). When unset, OAuth device-grant flow runs on first launch. |
 | `ROCKHOPPER_API_URL` | No | `https://api.rockhopper.co` | Rockhopper API base URL |
 
 ## Postman

package/dist/api-client.d.ts

@@ -1,4 +1,4 @@
-import type { CellHistoryEntry, EnrolledFile, FileChat, FileVersion, ReviewActivity, ReviewRequest, Team, UnattributedChange, UserSummary } from './types.js';
+import type { CellHistoryEntry, EnrolledFile, FileChat, FileVersion, PaginatedUnattributedResponse, ReviewActivity, ReviewRequest, Team, UnattributedChange, UserSummary } from './types.js';
 export interface ApiClientConfig {
     baseUrl: string;
     token: string;
@@ -7,15 +7,32 @@ export declare class ApiClient {
     private readonly baseUrl;
     private readonly token;
     constructor(config: ApiClientConfig);
+    /**
+     * KI-096: optional `responseSchema` validates the response shape with
+     * zod. When supplied, drift between backend's actual response and the
+     * mcp-server's declared type fails LOUDLY with a `ZodError` (wrapped
+     * here in an Error with the path that drifted) instead of silently
+     * rendering `undefined` in tool formatters. Opt-in per call site so
+     * existing methods stay untouched until a sweep migrates them.
+     */
     private request;
     getMe(): Promise<UserSummary>;
     getTeam(teamId: number): Promise<Team>;
     listEnrolledFiles(params?: {
         search?: string;
+        matchIn?: 'name' | 'comments' | 'versions' | 'all';
     }): Promise<EnrolledFile[]>;
     getEnrolledFile(fileMsId: string): Promise<EnrolledFile>;
     getFileVersions(fileMsId: string): Promise<FileVersion[]>;
     getFileVersion(versionInternalId: number): Promise<FileVersion>;
+    /**
+     * KI-096: passes `?format=mcp` to opt into the backend's normalized
+     * projection `{versionId, value, changedBy, changedAt}` (added by
+     * backend PR #478). Default `format` (omitted) returns the raw CTE
+     * row shape the frontend cell-history popover consumes — we never
+     * call that path. Zod-parses the response so future drift between
+     * backend and mcp-server contracts fails loudly.
+     */
     getCellHistory(fileMsId: string, sheetName: string, cellAddress: string): Promise<CellHistoryEntry[]>;
     getFileComments(fileMsId: string): Promise<FileChat[]>;
     getComment(chatId: number): Promise<FileChat>;
@@ -29,6 +46,14 @@ export declare class ApiClient {
         message: string;
         versionInternalId: number;
     }): Promise<FileChat>;
+    /**
+     * KI-096: zod-parses the response. Backend PR #478 fixed
+     * `PATCH /file-chat/:chatId` to return the updated entity (was
+     * UpdateResult) AND to persist `resolved` (was silently dropped).
+     * The schema check pins both fixes — if either regresses, the parse
+     * fails with a clear message instead of the formatter rendering
+     * `Comment undefined marked as resolved.`
+     */
     resolveComment(chatId: number): Promise<FileChat>;
     getReviewsForVersion(versionId: number): Promise<ReviewRequest[]>;
     getReviewsForLatestVersion(fileMsId: string): Promise<ReviewRequest[]>;
@@ -43,10 +68,28 @@ export declare class ApiClient {
     approveReview(reviewId: number, body: {
         notes?: string;
     }): Promise<ReviewRequest>;
-    getUnattributedChanges(fileMsId: string, params?: {
-        sheetName?: string;
-        status?: string;
-    }): Promise<UnattributedChange[]>;
+    /**
+     * Sheet-filtered unattributed changes. Returns ALL rows for the given
+     * sheet on the file (no pagination — sheet filter inherently bounds
+     * result size). Use this when the caller already knows which sheet to
+     * inspect; use {@link getUnattributedChangesPaginated} for the file-wide
+     * view.
+     */
+    getUnattributedChangesBySheet(fileMsId: string, sheetName: string): Promise<UnattributedChange[]>;
+    /**
+     * Cursor-paginated file-wide unattributed changes (KI-097).
+     *
+     * Hits the non-shadowable `GET /unattributed-changes/paginated/:fileMsId`
+     * route added by backend PR #475 (KI-102). The legacy `:fileMsId/v2`
+     * route is shadowed by `:fileMsId/:sheetName` route ordering and returns
+     * an empty array; do not call it from here.
+     *
+     * Pass `cursor` returned by a previous call to fetch the next page.
+     * Snapshot TTL is 30 minutes — older cursors cause the backend to return
+     * HTTP 410 GONE with `{ resyncRequired: { code: 'SNAPSHOT_EXPIRED' } }`,
+     * which surfaces here as a thrown RockhopperApiError.
+     */
+    getUnattributedChangesPaginated(fileMsId: string, cursor?: string): Promise<PaginatedUnattributedResponse>;
     createVersion(body: {
         enrolledFileMsId: string;
         version: {
@@ -60,6 +103,14 @@ export declare class ApiClient {
         description: string;
     }): Promise<FileVersion>;
     cancelReview(reviewId: number): Promise<ReviewRequest>;
+    /**
+     * KI-096: zod-parses the response. Backend PR #478 fixed
+     * `PATCH /enrolled-files/:fileMsId` to return the updated entity
+     * (was UpdateResult typed as Promise<any>). The schema check pins
+     * the entity contract — if it regresses, the parse fails with a
+     * clear message instead of `rename_file` rendering
+     * `File renamed to 'undefined' (id: undefined).`
+     */
     updateEnrolledFile(fileMsId: string, body: {
         name?: string;
     }): Promise<EnrolledFile>;

package/dist/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}

package/dist/api-client.js

@@ -1,3 +1,4 @@
+import { CellHistoryEntryArraySchema, EnrolledFileSchema, FileChatSchema, } from './zod-schemas.js';
 export class ApiClient {
     baseUrl;
     token;
@@ -5,7 +6,15 @@ export class ApiClient {
         this.baseUrl = config.baseUrl.replace(/\/+$/, '');
         this.token = config.token;
     }
-    async request(path, init) {
+    /**
+     * KI-096: optional `responseSchema` validates the response shape with
+     * zod. When supplied, drift between backend's actual response and the
+     * mcp-server's declared type fails LOUDLY with a `ZodError` (wrapped
+     * here in an Error with the path that drifted) instead of silently
+     * rendering `undefined` in tool formatters. Opt-in per call site so
+     * existing methods stay untouched until a sweep migrates them.
+     */
+    async request(path, init, responseSchema) {
         const url = `${this.baseUrl}${path}`;
         const response = await fetch(url, {
             ...init,
@@ -19,7 +28,21 @@ export class ApiClient {
             const body = await response.text().catch(() => '');
             throw new Error(`Rockhopper API ${response.status}: ${response.statusText} — ${body}`);
         }
-        return response.json();
+        const json = await response.json();
+        if (responseSchema) {
+            const parsed = responseSchema.safeParse(json);
+            if (!parsed.success) {
+                // Surface a useful diagnostic — the formatter would otherwise show
+                // `undefined`, hiding the contract break. Include the path of the
+                // first issue so the cause is obvious from the error message.
+                const first = parsed.error.issues[0];
+                throw new Error(`Rockhopper API response failed schema check at ${path}: ` +
+                    `${first?.path.join('.') || '<root>'} — ${first?.message} ` +
+                    `(${parsed.error.issues.length} issue(s) total)`);
+            }
+            return parsed.data;
+        }
+        return json;
     }
     // --- Users ---
     async getMe() {
@@ -34,6 +57,8 @@ export class ApiClient {
         const query = new URLSearchParams();
         if (params?.search)
             query.set('search', params.search);
+        if (params?.matchIn)
+            query.set('matchIn', params.matchIn);
         const qs = query.toString();
         return this.request(`/enrolled-files${qs ? `?${qs}` : ''}`);
     }
@@ -47,9 +72,21 @@ export class ApiClient {
     async getFileVersion(versionInternalId) {
         return this.request(`/file-versions/file/version/${versionInternalId}`);
     }
+    /**
+     * KI-096: passes `?format=mcp` to opt into the backend's normalized
+     * projection `{versionId, value, changedBy, changedAt}` (added by
+     * backend PR #478). Default `format` (omitted) returns the raw CTE
+     * row shape the frontend cell-history popover consumes — we never
+     * call that path. Zod-parses the response so future drift between
+     * backend and mcp-server contracts fails loudly.
+     */
     async getCellHistory(fileMsId, sheetName, cellAddress) {
-        const query = new URLSearchParams({ cell: cellAddress, sheetName });
-        return this.request(`/file-versions/file/${fileMsId}/cell-history?${query}`);
+        const query = new URLSearchParams({
+            cell: cellAddress,
+            sheetName,
+            format: 'mcp',
+        });
+        return this.request(`/file-versions/file/${fileMsId}/cell-history?${query}`, undefined, CellHistoryEntryArraySchema);
     }
     // --- File Chat (Comments) ---
     async getFileComments(fileMsId) {
@@ -70,11 +107,19 @@ export class ApiClient {
             body: JSON.stringify(body),
         });
     }
+    /**
+     * KI-096: zod-parses the response. Backend PR #478 fixed
+     * `PATCH /file-chat/:chatId` to return the updated entity (was
+     * UpdateResult) AND to persist `resolved` (was silently dropped).
+     * The schema check pins both fixes — if either regresses, the parse
+     * fails with a clear message instead of the formatter rendering
+     * `Comment undefined marked as resolved.`
+     */
     async resolveComment(chatId) {
         return this.request(`/file-chat/${chatId}`, {
             method: 'PATCH',
             body: JSON.stringify({ resolved: true }),
-        });
+        }, FileChatSchema);
     }
     // --- Reviews ---
     async getReviewsForVersion(versionId) {
@@ -102,11 +147,33 @@ export class ApiClient {
         });
     }
     // --- Unattributed Changes ---
-    async getUnattributedChanges(fileMsId, params) {
-        let path = `/unattributed-changes/${fileMsId}`;
-        if (params?.sheetName) {
-            path += `/${params.sheetName}`;
-        }
+    /**
+     * Sheet-filtered unattributed changes. Returns ALL rows for the given
+     * sheet on the file (no pagination — sheet filter inherently bounds
+     * result size). Use this when the caller already knows which sheet to
+     * inspect; use {@link getUnattributedChangesPaginated} for the file-wide
+     * view.
+     */
+    async getUnattributedChangesBySheet(fileMsId, sheetName) {
+        const path = `/unattributed-changes/${fileMsId}/${encodeURIComponent(sheetName)}`;
+        return this.request(path);
+    }
+    /**
+     * Cursor-paginated file-wide unattributed changes (KI-097).
+     *
+     * Hits the non-shadowable `GET /unattributed-changes/paginated/:fileMsId`
+     * route added by backend PR #475 (KI-102). The legacy `:fileMsId/v2`
+     * route is shadowed by `:fileMsId/:sheetName` route ordering and returns
+     * an empty array; do not call it from here.
+     *
+     * Pass `cursor` returned by a previous call to fetch the next page.
+     * Snapshot TTL is 30 minutes — older cursors cause the backend to return
+     * HTTP 410 GONE with `{ resyncRequired: { code: 'SNAPSHOT_EXPIRED' } }`,
+     * which surfaces here as a thrown RockhopperApiError.
+     */
+    async getUnattributedChangesPaginated(fileMsId, cursor) {
+        const qs = cursor ? `?cursor=${encodeURIComponent(cursor)}` : '';
+        const path = `/unattributed-changes/paginated/${fileMsId}${qs}`;
         return this.request(path);
     }
     // --- Version lifecycle ---
@@ -130,11 +197,19 @@ export class ApiClient {
         });
     }
     // --- File metadata update ---
+    /**
+     * KI-096: zod-parses the response. Backend PR #478 fixed
+     * `PATCH /enrolled-files/:fileMsId` to return the updated entity
+     * (was UpdateResult typed as Promise<any>). The schema check pins
+     * the entity contract — if it regresses, the parse fails with a
+     * clear message instead of `rename_file` rendering
+     * `File renamed to 'undefined' (id: undefined).`
+     */
     async updateEnrolledFile(fileMsId, body) {
         return this.request(`/enrolled-files/${fileMsId}`, {
             method: 'PATCH',
             body: JSON.stringify(body),
-        });
+        }, EnrolledFileSchema);
     }
 }
 //# sourceMappingURL=api-client.js.map

package/dist/api-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAiBA,MAAM,OAAO,SAAS;IACH,OAAO,CAAS;IAChB,KAAK,CAAS;IAE/B,YAAY,MAAuB;QACjC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC5B,CAAC;IAEO,KAAK,CAAC,OAAO,CAAI,IAAY,EAAE,IAAkB;QACvD,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,GAAG,IAAI;YACP,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,IAAI,CAAC,KAAK,EAAE;gBACrC,cAAc,EAAE,kBAAkB;gBAClC,GAAG,IAAI,EAAE,OAAO;aACjB;SACF,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YACnD,MAAM,IAAI,KAAK,CACb,kBAAkB,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,UAAU,MAAM,IAAI,EAAE,CACtE,CAAC;QACJ,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,EAAgB,CAAC;IACvC,CAAC;IAED,gBAAgB;IAEhB,KAAK,CAAC,KAAK;QACT,OAAO,IAAI,CAAC,OAAO,CAAc,WAAW,CAAC,CAAC;IAChD,CAAC;IAED,gBAAgB;IAEhB,KAAK,CAAC,OAAO,CAAC,MAAc;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAO,UAAU,MAAM,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,yBAAyB;IAEzB,KAAK,CAAC,iBAAiB,CAAC,MAEvB;QACC,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;QACpC,IAAI,MAAM,EAAE,MAAM;YAAE,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACvD,MAAM,EAAE,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC,OAAO,CACjB,kBAAkB,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CACvC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,QAAgB;QACpC,OAAO,IAAI,CAAC,OAAO,CAAe,mBAAmB,QAAQ,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,wBAAwB;IAExB,KAAK,CAAC,eAAe,CAAC,QAAgB;QACpC,OAAO,IAAI,CAAC,OAAO,CAAgB,uBAAuB,QAAQ,EAAE,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,iBAAyB;QAC5C,OAAO,IAAI,CAAC,OAAO,CACjB,+BAA+B,iBAAiB,EAAE,CACnD,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,cAAc,CAClB,QAAgB,EAChB,SAAiB,EACjB,WAAmB;QAEnB,MAAM,KAAK,GAAG,IAAI,eAAe,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC,CAAC;QACpE,OAAO,IAAI,CAAC,OAAO,CACjB,uBAAuB,QAAQ,iBAAiB,KAAK,EAAE,CACxD,CAAC;IACJ,CAAC;IAED,+BAA+B;IAE/B,KAAK,CAAC,eAAe,CAAC,QAAgB;QACpC,OAAO,IAAI,CAAC,OAAO,CAAa,cAAc,QAAQ,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,MAAc;QAC7B,OAAO,IAAI,CAAC,OAAO,CAAW,qBAAqB,MAAM,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,IAKnB;QACC,OAAO,IAAI,CAAC,OAAO,CAAW,YAAY,EAAE;YAC1C,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,cAAc,CAClB,MAAc,EACd,IAAoD;QAEpD,OAAO,IAAI,CAAC,OAAO,CAAW,cAAc,MAAM,UAAU,EAAE;YAC5D,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,MAAc;QACjC,OAAO,IAAI,CAAC,OAAO,CAAW,cAAc,MAAM,EAAE,EAAE;YACpD,MAAM,EAAE,OAAO;YACf,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;SACzC,CAAC,CAAC;IACL,CAAC;IAED,kBAAkB;IAElB,KAAK,CAAC,oBAAoB,CACxB,SAAiB;QAEjB,OAAO,IAAI,CAAC,OAAO,CACjB,qBAAqB,SAAS,WAAW,CAC1C,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,0BAA0B,CAC9B,QAAgB;QAEhB,OAAO,IAAI,CAAC,OAAO,CACjB,kBAAkB,QAAQ,0BAA0B,CACrD,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,QAAgB;QAC9B,OAAO,IAAI,CAAC,OAAO,CAAgB,qBAAqB,QAAQ,EAAE,CAAC,CAAC;IACtE,CAAC;IAED,KAAK,CAAC,mBAAmB,CACvB,QAAgB;QAEhB,OAAO,IAAI,CAAC,OAAO,CACjB,qBAAqB,QAAQ,aAAa,CAC3C,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,mBAAmB,CAAC,IAKzB;QACC,OAAO,IAAI,CAAC,OAAO,CAAgB,mBAAmB,EAAE;YACtD,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,aAAa,CACjB,QAAgB,EAChB,IAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CACjB,qBAAqB,QAAQ,UAAU,EACvC;YACE,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CACF,CAAC;IACJ,CAAC;IAED,+BAA+B;IAE/B,KAAK,CAAC,sBAAsB,CAC1B,QAAgB,EAChB,MAAgD;QAEhD,IAAI,IAAI,GAAG,yBAAyB,QAAQ,EAAE,CAAC;QAC/C,IAAI,MAAM,EAAE,SAAS,EAAE,CAAC;YACtB,IAAI,IAAI,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QACjC,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAuB,IAAI,CAAC,CAAC;IAClD,CAAC;IAED,4BAA4B;IAE5B,KAAK,CAAC,aAAa,CAAC,IAQnB;QACC,OAAO,IAAI,CAAC,OAAO,CAAc,gBAAgB,EAAE;YACjD,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,cAAc,CAClB,QAAgB,EAChB,IAA6B;QAE7B,OAAO,IAAI,CAAC,OAAO,CACjB,oCAAoC,QAAQ,EAAE,EAC9C;YACE,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CACF,CAAC;IACJ,CAAC;IAED,2BAA2B;IAE3B,KAAK,CAAC,YAAY,CAAC,QAAgB;QACjC,OAAO,IAAI,CAAC,OAAO,CAAgB,qBAAqB,QAAQ,EAAE,EAAE;YAClE,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;SAC9C,CAAC,CAAC;IACL,CAAC;IAED,+BAA+B;IAE/B,KAAK,CAAC,kBAAkB,CACtB,QAAgB,EAChB,IAAuB;QAEvB,OAAO,IAAI,CAAC,OAAO,CAAe,mBAAmB,QAAQ,EAAE,EAAE;YAC/D,MAAM,EAAE,OAAO;YACf,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}

package/dist/auth/device-grant-client.d.ts

@@ -0,0 +1,80 @@
+/**
+ * ENG-1444 / KI-081 — RFC 8628 device-grant client.
+ *
+ * Talks to the backend's `POST /auth/device/{code,token}` endpoints
+ * (introduced in ENG-1384 PR 1, `Rockhopper-Co/backend#473`). Used by
+ * the mcp-server CLI when no PAT env var is set and no OAuth bundle
+ * is stored in the OS keychain.
+ *
+ * Surfaces a single entrypoint, `runDeviceGrantFlow`, that:
+ *
+ *   1. Calls `/auth/device/code` to get a (deviceCode, userCode) pair.
+ *   2. Emits the user-facing `userCode` + verification URI to stderr
+ *      (LLM clients pick this up via stdout's stderr passthrough).
+ *   3. Polls `/auth/device/token` at the server-specified interval,
+ *      respecting RFC 8628 § 3.5 `slow_down` (bumps interval +5s) and
+ *      `authorization_pending` (continues polling).
+ *   4. Resolves with the access-token bundle on success, rejects on
+ *      `access_denied` / `expired_token` / network failure.
+ *
+ * No external HTTP dependency — uses globalThis.fetch (Node 18+).
+ * `fetchImpl` + `sleep` + `onUserCode` are injectable for tests.
+ */
+export interface DeviceCodeResponse {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    expiresIn: number;
+    interval: number;
+}
+export interface DeviceTokenSuccess {
+    accessToken: string;
+    tokenType: 'Bearer';
+    expiresIn: number;
+    refreshToken?: string;
+}
+export interface DeviceGrantFlowOptions {
+    baseUrl: string;
+    clientId: string;
+    /** Override for tests. Defaults to globalThis.fetch. */
+    fetchImpl?: typeof fetch;
+    /** Override for tests. Defaults to setTimeout-based sleep. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Called once with the user code + verification URI. Defaults to stderr. */
+    onUserCode?: (info: {
+        userCode: string;
+        verificationUri: string;
+        verificationUriComplete: string;
+    }) => void;
+}
+export declare class DeviceGrantError extends Error {
+    readonly code: 'access_denied' | 'expired_token' | 'network_error' | 'unknown';
+    constructor(code: 'access_denied' | 'expired_token' | 'network_error' | 'unknown', message: string);
+}
+/**
+ * Issue a fresh device code + user code pair.
+ */
+export declare function requestDeviceCode(opts: Pick<DeviceGrantFlowOptions, 'baseUrl' | 'clientId' | 'fetchImpl'>): Promise<DeviceCodeResponse>;
+/**
+ * Internal: one polling round-trip. Returns the token bundle on
+ * success, or a sentinel describing why the server isn't ready yet.
+ */
+export declare function pollOnce(opts: Pick<DeviceGrantFlowOptions, 'baseUrl' | 'clientId' | 'fetchImpl'>, deviceCode: string): Promise<{
+    kind: 'success';
+    bundle: DeviceTokenSuccess;
+} | {
+    kind: 'pending';
+} | {
+    kind: 'slow_down';
+}>;
+/**
+ * Full flow — request code, print to stderr, poll until success or
+ * fatal error. Returns the access-token bundle on success.
+ *
+ * `interval` (seconds, server-supplied) becomes the poll cadence.
+ * `slow_down` responses bump the interval by RFC's recommended +5s.
+ * Total wall time is bounded by the server-supplied `expiresIn`.
+ */
+export declare function runDeviceGrantFlow(opts: DeviceGrantFlowOptions): Promise<DeviceTokenSuccess>;
+//# sourceMappingURL=device-grant-client.d.ts.map

package/dist/auth/device-grant-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-grant-client.d.ts","sourceRoot":"","sources":["../../src/auth/device-grant-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,uBAAuB,EAAE,MAAM,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,QAAQ,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,6EAA6E;IAC7E,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,EAAE,MAAM,CAAC;QACxB,uBAAuB,EAAE,MAAM,CAAC;KACjC,KAAK,IAAI,CAAC;CACZ;AAED,qBAAa,gBAAiB,SAAQ,KAAK;aAEvB,IAAI,EAChB,eAAe,GACf,eAAe,GACf,eAAe,GACf,SAAS;gBAJG,IAAI,EAChB,eAAe,GACf,eAAe,GACf,eAAe,GACf,SAAS,EACb,OAAO,EAAE,MAAM;CAKlB;AAkBD;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,CAAC,sBAAsB,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC,GACvE,OAAO,CAAC,kBAAkB,CAAC,CAuB7B;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,IAAI,CAAC,sBAAsB,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC,EACxE,UAAU,EAAE,MAAM,GACjB,OAAO,CACN;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,CACxB,CAsDA;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAgC7B"}