cloud-alm-mcp-server 0.0.0-stage → 0.1.0-beta.0

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to this package. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0-beta.0] - 2026-11-14
+
+### Fixed
+
+- `calm_create_task` takes no description when there is none (Cloud ALM
+  does not need one), names its priority codes, and its preview and card
+  say the type and priority ("Create a defect", "priority high").
+- The approval ask states when it expires and also travels in
+  `structuredContent`, for hosts that show the model only that.
+- `init` says when the key could write and how to turn writes on; for a
+  prerelease, its setup lines pin the version.
+
+### Changed
+
+- Seven task-shaped read tools replace the 21 endpoint mirrors:
+  `calm_overview`, `calm_find`, `calm_get`, `calm_trace`, `calm_gaps`,
+  `calm_analytics`, `calm_landscape`. They accept short display ids
+  (`3-17`, `8-1-2`), read a whole project in a few requests, answer in
+  compact text, and show the latest test results. The tool list costs about
+  1.8k tokens instead of 4.5k.
+
+### Added
+
+- Approval of writes (`CALM_APPROVAL=prefer|required|off`): every write is
+  a proposal the user approves in an approval card in the chat (MCP Apps)
+  or, in `prefer`, by saying yes in the chat (`calm_confirm`). The client's
+  confirm dialog is opt-in (`CALM_APPROVAL_DIALOG=on`), as some clients
+  decline it unseen. Approvals are single-use, expire after an hour (the
+  card then shows them as expired), and are bound to
+  the caller.
+- `doctor` checks scopes per tool, write mode, approval and the default project.
+
+- Write mode, off by default (`CALM_WRITE=on|dry-run`):
+  `calm_create_task`, `calm_create_test_case`, `calm_create_feature`,
+  `calm_create_document`, `calm_update`, `calm_delete`, `calm_comment`,
+  `calm_link` (link and unlink, also documents and requirements),
+  `calm_tag`. Duplicates refused; every write tool takes `dryRun` and
+  previews each change before → after; a 403 names the missing scope.
+- `CALM_TOOLS` (allow list) and `CALM_PROJECT` (default project).
+- Skills `cloud-alm-explore` and `cloud-alm-test-design`.
+- `cloud-alm-mcp-server init [file|-]`: checks a service key (shape, token,
+  `calm-api.*` scopes per area, one read), saves it mode 600 under the
+  user's config directory and prints configuration for Claude Code, Codex,
+  Claude Desktop and Cursor. `--force` replaces a saved key, `--skip-check`
+  saves without contacting SAP.
+- `cloud-alm-mcp-server doctor`: the same checks on an existing setup, plus
+  key file permissions and the Node version.
+- `--version` and `--help`.
+- `CALM_SERVICE_KEY` takes the key JSON itself as well as a path; without
+  it the stdio server uses the key saved by `init`.
+- Package ready for npm: `bin`, `files` (no tests, no source maps),
+  `exports`, `engines`, `prepublishOnly` (typecheck, test, build).
+- MIT licence.
+- CI on Node 22 and 24, with a check of the packed command; a release
+  workflow (tag `v*` → `npm publish --provenance`) that stays inert until
+  an `NPM_TOKEN` secret exists.
+
+## 0.1.0
+
+- First version: read-only Cloud ALM reader and MCP server, stdio mode
+  with a service key, streamable HTTP mode with a bearer per request.
+  Not published.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Didro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,376 @@
-# Temporary Holding Version
+# cloud-alm-mcp-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [Model Context Protocol](https://modelcontextprotocol.io) server that lets
+an agent (Claude, Codex, Cursor…) work with **SAP Cloud ALM**: projects,
+requirements, user stories, defects, features, documents, test cases and
+test plans, processes, landscape, cross-library, analytics and service
+status events.
+
+**Read-only by default.** The read tools are annotated `readOnlyHint` and
+the reader sends GET requests only, to `*.alm.cloud.sap` hosts only.
+Writing (create, change, link, tag, comment, delete) is opt-in
+with `CALM_WRITE` ([Modes and governance](#modes-and-governance)).
+
+> Status: beta (0.1.0-beta.0). MIT licence.
+
+## Quick start
+
+Requires Node 22 or later.
+
+1. Get a Cloud ALM API service key (below) and download its JSON.
+2. Check it and save it:
+
+   ```sh
+   npx -y cloud-alm-mcp-server init ~/Downloads/calm-read.json
+   ```
+
+   `init` gets a token to prove the key works, lists which areas of Cloud
+   ALM its scopes can read, makes one read, then saves the key readable
+   only by you (mode 600) in `~/.config/cloud-alm-mcp-server/` and prints
+   the configuration for Claude Code, Codex, Claude Desktop and Cursor.
+   Paste the JSON instead of naming a file: `init` alone reads stdin.
+   You can delete the downloaded copy afterwards.
+3. Add the server to your client with the printed line, e.g.
+
+   ```sh
+   claude mcp add cloud-alm --scope user -e CALM_SERVICE_KEY=$HOME/.config/cloud-alm-mcp-server/service-key.json -- npx -y cloud-alm-mcp-server
+   ```
+
+4. Any time later: `npx -y cloud-alm-mcp-server doctor` checks the key,
+   token, scopes, API and Node version.
+
+| Command | Does |
+| --- | --- |
+| `cloud-alm-mcp-server` | starts the stdio server (default) |
+| `cloud-alm-mcp-server http` | starts the streamable HTTP server |
+| `cloud-alm-mcp-server init [file\|-] [--force] [--skip-check]` | checks and saves a key, prints client config |
+| `cloud-alm-mcp-server doctor` | checks the setup |
+| `cloud-alm-mcp-server --version` / `--help` | |
+
+No command prints the key's secret or a token.
+
+> Beta. Until 0.1.0 is out, name the beta: `npx -y cloud-alm-mcp-server@beta`.
+> A packed build installs with `npm install -g ./cloud-alm-mcp-server-<version>.tgz`;
+> then use `cloud-alm-mcp-server` instead of `npx -y cloud-alm-mcp-server`.
+
+## Get a service key
+
+Cloud ALM's APIs take an OAuth token from a **service key** of the "SAP Cloud
+ALM API" service, created in the BTP subaccount where your Cloud ALM tenant
+lives. Nothing is deployed; the instance only registers an OAuth client.
+
+1. In the BTP cockpit, open the Cloud ALM subaccount → *Services* →
+   *Instances and Subscriptions* → *Create*.
+2. Service **SAP Cloud ALM API**, plan **standard**, runtime environment
+   **Other**. Name it, e.g. `calm-read`.
+3. Parameters: give the client the read scopes it needs (the default
+   template has none, which gives a token that can read nothing):
+
+   ```json
+   {
+     "xs-security": {
+       "xsappname": "calm-read",
+       "authorities": [
+         "$XSMASTERAPPNAME.calm-api.projects.read",
+         "$XSMASTERAPPNAME.calm-api.tasks.read",
+         "$XSMASTERAPPNAME.calm-api.features.read",
+         "$XSMASTERAPPNAME.calm-api.documents.read",
+         "$XSMASTERAPPNAME.calm-api.testcases.read",
+         "$XSMASTERAPPNAME.calm-api.testplans.read",
+         "$XSMASTERAPPNAME.calm-api.processmanagement.read",
+         "$XSMASTERAPPNAME.calm-api.processhierarchy.read",
+         "$XSMASTERAPPNAME.calm-api.landscape.read",
+         "$XSMASTERAPPNAME.calm-api.lib.read",
+         "$XSMASTERAPPNAME.calm-api.analytics.read",
+         "$XSMASTERAPPNAME.calm-api.analytics.providers.read",
+         "$XSMASTERAPPNAME.calm-api.bsm.read"
+       ]
+     }
+   }
+   ```
+
+   Add only what you will read. Analytics datasets also need their area's
+   scope (`calm-api.tasks.read` for `Tasks`, `…defects.read`,
+   `…requirements.read`, `…tests.read`, …), and operations datasets their
+   own (`…metrics.read`, `…jobs.read`, `…exm.read` …). Personal fields
+   (assignee names) need `calm-api.tasks.personal.read` and its siblings.
+4. Create a **service binding** (the key) on the instance and download its
+   JSON. Run `cloud-alm-mcp-server init <file>` on it: it saves a copy
+   readable only by you. Never put it in a repository.
+
+The key holds `uaa.url`, `uaa.clientid`, `uaa.clientsecret` and
+`endpoints.Api` (e.g. `https://eu20.alm.cloud.sap/api`, regional; the token
+selects your tenant). The token carries no user: calls run as a machine
+with access to the whole tenant. SAP cannot limit a key to one project.
+
+Changed the scopes? The token reflects them at once: rerun
+`cloud-alm-mcp-server doctor`. Rotated the key? `init --force <new file>`.
+
+## Tools
+
+Seven read tools, each answering a question in one call. Items are named by
+their short **display ids** (`3-17` task, `6-1` feature, `7-1` document,
+`8-1-2` test case, `8-3-1` test plan), which every tool accepts; GUIDs work
+too. Answers are compact text written for a model's context.
+
+| Tool | Answers |
+| --- | --- |
+| `calm_overview` | Start here: the project, its current phase, counts of requirements, user stories, defects, features, test cases and documents by status, latest test results, tags in use, gaps |
+| `calm_find` | Search or list items across types (tasks, features, documents, test cases, test plans, processes, library) by words in titles and tags (`a b \| c`), type, status, tag |
+| `calm_get` | Full content of 1–10 items at once: description, test steps and latest result, document text, feature transports, every link named |
+| `calm_trace` | An item's links both ways: requirement → user stories → features (status, transports), test cases (with results), documents, solution process |
+| `calm_gaps` | What is missing or failing: requirements and user stories without a test case, process or feature; failed test runs; features with untested tasks; test cases linked to nothing or not prepared |
+| `calm_analytics` | Analytics datasets (tasks, defects, test runs, jobs, exceptions, integration messages…), counted with `groupBy` |
+| `calm_landscape` | Systems and cloud services, and SAP service status events, open ones first |
+
+With write mode on (below), ten more:
+
+| Tool | Does |
+| --- | --- |
+| `calm_create_task` | Creates a requirement, user story (optionally under a requirement), defect or project task; refuses a duplicate title |
+| `calm_create_test_case` | Creates a manual test case with activities and steps, linked to the requirements or user stories it covers; refuses a duplicate title |
+| `calm_create_feature` | Creates a feature, optionally linked to the tasks it delivers; refuses a duplicate title |
+| `calm_create_document` | Creates a document (content, type, status, priority) linked to tasks; refuses a duplicate title |
+| `calm_update` | Changes 1–20 items with the same changes: tasks (title, description, status in plain words, priority, assignee, start and due date, timebox, obsolete), features (title, description, status, priority), manual test cases (title, prepared, priority, `addActivity` with steps). Sends only the fields that differ and answers before → after per field |
+| `calm_delete` | Deletes tasks (`soft: true` marks them obsolete instead, as SAP recommends), manual test cases (`force: true` also deletes their runs and results) and documents |
+| `calm_comment` | Adds a comment to a task |
+| `calm_link` | Links, or with `unlink: true` unlinks, a test case (tests), feature (delivers) or document (documents) to tasks, and user stories or project tasks to their requirement; skips links already in that state |
+| `calm_tag` | Adds or removes tags on tasks, keeping the others, and reports tags Cloud ALM silently dropped |
+
+Every write tool takes `dryRun: true` and then answers with a complete
+preview: item ids and titles, each field before → after, what gets created,
+linked or deleted. Display ids work everywhere. Statuses are plain words,
+mapped to Cloud ALM's codes per task type (`open`, `in progress`,
+`blocked`, `in review`, `done`, `not relevant` as the type has them;
+requirements also `to be approved`, `approved`, `in realization`,
+`approved for deployment`, `rejected`; defects also `retest`). A field that
+does not apply to an item is refused before anything is written. A 403
+names the scope the key lacks. Writes are never retried.
+
+What Cloud ALM's API itself does not allow (no scope changes it):
+
+- Features cannot be deleted, and their status moves only along Cloud
+  ALM's path (in specification ↔ not planned; in specification → in
+  realization → in testing → successfully tested, back to in realization;
+  once in realization, never back to in specification or not planned).
+  "Ready for production" cannot be set through the API, so "deployed" is
+  not reachable through it either.
+- A feature description holding images cannot be changed through the API.
+- A document's title, content, status, priority and type cannot change
+  after create; only its links can.
+- Test cases and features cannot be tagged; automated test cases are
+  read-only; a test case's project, scope and process cannot change.
+- No API records manual test execution (runs, step results, pass/fail).
+- A requirement's approval is final (it cannot go back to "to be approved"
+  or "rejected"), and an approved requirement cannot be deleted.
+- A task has one requirement: unlink it before linking another.
+- Every write is recorded as the key's technical user.
+
+Deleting test cases and documents needs extra scopes on the key
+(`testcases.delete`, `testcases.force-delete`, `documents.delete`).
+
+A read the key has no scope for is named in the answer ("not readable with
+this key"); the rest still answers. Errors are short text with a code
+(`unauthorized`, `forbidden`, `not_found`, `rate_limited`, `unavailable`,
+`bad_request`) and never carry a token.
+
+### Modes and governance
+
+| Variable | Effect |
+| --- | --- |
+| `CALM_WRITE` | `off` (default): read tools only. `dry-run`: write tools are offered but only preview. `on`: write tools write. The key also needs the write scopes. |
+| `CALM_TOOLS` | Comma-separated tool names to offer, e.g. `calm_overview,calm_find,calm_get`. Default: all (of the current mode). |
+| `CALM_APPROVAL` | With `CALM_WRITE=on`: `prefer` (default) has the user approve each write in the card or the chat, `required` in the card only, `off` writes at once. |
+| `CALM_APPROVAL_DIALOG` | `on` also asks in the client's confirm dialog (MCP elicitation), where it declares one. Off by default: only terminal clients show it reliably. |
+| `CALM_PROJECT` | Project GUID used when a call names none. Without it, a tenant with one project uses that one; with several, tools ask for `projectId`. |
+
+In HTTP mode the same variables apply to every request; the bearer token
+decides what Cloud ALM allows.
+
+### Approving writes
+
+With approval on, a write tool only proposes the change: it runs as a dry
+run and answers with the preview; nothing is sent to Cloud ALM until the
+user approves. Every answer carries the same proposal, whatever the client
+says it supports, and the user approves it in one of these ways:
+
+| Where | How | Clients (Nov 2026) |
+| --- | --- | --- |
+| the approval card | an MCP Apps card in the chat with Approve / Reject | Claude (web, Desktop chat), ChatGPT, VS Code, Goose |
+| the chat (`prefer` only) | the agent shows the preview and asks; on the user's yes it calls `calm_confirm` | every client |
+| the client's dialog (`CALM_APPROVAL_DIALOG=on`) | the client's own confirm dialog | Claude Code and Codex in a terminal |
+
+The card's button calls `calm_approve`, a tool visible to the card only,
+with a one-time token that travels in the result's `_meta`, never in the
+text the model reads. If the host drops `_meta` (some do, e.g. on reload),
+the card falls back to the id in `structuredContent`, which approves only
+in `prefer`. If the host does not pass the card's calls to the server
+(it does not declare `serverTools`; the Claude Code tab is one, see
+anthropics/claude-code#106708), the card shows the change without
+buttons and asks the user to reply yes in the chat; a failed call does
+the same. An approval is single-use, expires after 60
+minutes (the card then shows it as expired) and, over HTTP, must come with the same bearer token as the
+request that proposed it. `dryRun: true` previews without asking.
+
+Why the dialog is off by default: some clients declare a confirm dialog
+and answer "decline" without showing it (the Claude desktop app, for one),
+and some draw the card without declaring MCP Apps. With the dialog on, a
+declined or failed dialog keeps the proposal open for the card or chat.
+
+Scopes (`calm-api.` …): `projects.read`, `tasks.read`, `features.read`,
+`documents.read`, `testcases.read`, `testplans.read`,
+`processmanagement.read`, `landscape.read`, `lib.read`, `analytics.read`
+with `tests.read` (test results), `bsm.read`; for writing `tasks.write`,
+`testcases.write`, `features.write`, `documents.write` (task links of
+features and documents are written through the Tasks API), and to delete
+test cases and documents (or unlink a test case from a task)
+`testcases.delete`, `testcases.force-delete`, `documents.delete`.
+
+## Two ways to run it
+
+### stdio, with your own key (default)
+
+The server finds the key in `CALM_SERVICE_KEY`, either a file path or the
+JSON itself, else in the file `init` saved
+(`$XDG_CONFIG_HOME/cloud-alm-mcp-server/service-key.json`, by default under
+`~/.config`; `%APPDATA%\cloud-alm-mcp-server\` on Windows;
+`CALM_CONFIG_DIR` overrides the directory). It gets tokens by client
+credentials and keeps them in memory only.
+
+```sh
+npx -y cloud-alm-mcp-server                                    # the key saved by init
+CALM_SERVICE_KEY=~/keys/calm-read.json npx -y cloud-alm-mcp-server
+CALM_SERVICE_KEY="$SECRET_FROM_YOUR_VAULT" npx -y cloud-alm-mcp-server   # the JSON itself
+```
+
+### Streamable HTTP, a bearer token per request
+
+For hosting behind your own gateway: the server holds **no secret**. Each
+request carries `Authorization: Bearer <token>`, a Cloud ALM token the
+caller obtained. The API address comes from the `X-Calm-Api-Url` header,
+or `CALM_API_URL` when the header is absent; it must be an
+`https://…alm.cloud.sap` address, so a token is never sent anywhere else.
+
+```sh
+PORT=3333 CALM_API_URL=https://eu20.alm.cloud.sap/api npx -y cloud-alm-mcp-server http
+# MCP endpoint: http://127.0.0.1:3333/mcp  (HOST to bind elsewhere)
+```
+
+Stateless: one server per POST, JSON answers, no session. Requests without
+a bearer get 401; other methods 405. Put it behind TLS and your own
+authentication of callers: the bearer authorizes Cloud ALM, not the caller.
+
+## Use as a library
+
+The Cloud ALM client is exported too:
+
+```ts
+import { CloudAlm, serviceKeyGrants, formatTasks, createServer, createHttpHandler } from "cloud-alm-mcp-server";
+
+const calm = new CloudAlm(serviceKeyGrants(serviceKey));          // from a service key
+const calm2 = new CloudAlm(async () => myBroker.grant("cloud-alm")); // from your own token source
+console.log(formatTasks(await calm.listTasks({ type: "defect", limit: 20 })));
+```
+
+A grant is `{ accessToken, baseUrl, expiresAt? }`; a callback is called once
+per operation. The library never reads environment variables or files.
+
+## Cloud ALM quirks it hides
+
+- **Path casing differs per service**: REST services use lower case
+  (`projects`, `tasks`, `landscapeObjects`, `solutionProcesses`), OData
+  services capitalised entity sets (`Features`, `ManualTestCases`). The
+  wrong case answers 404. The library holds the right paths.
+- **Tasks need a project.** Cloud ALM answers 400 without `projectId`.
+  Without one, `listTasks` reads every project (up to 10) and merges.
+- **GUID filters go unquoted** in OData (`projectId eq 1234…`); a quoted
+  GUID answers 400 (`Edm.Guid` vs `Edm.String`). Ids are checked as GUIDs
+  before they go into a path or a filter.
+- **Paging differs**: OData services take `$top`/`$skip`/`$count`; tasks,
+  landscape and status events take `limit`/`offset`; process management
+  takes a literal `$top`/`$skip`. Every list here takes `{ limit, offset }`
+  (limit 1–200, default 50) and returns
+  `{ items, offset, limit, nextOffset, total }`. `nextOffset` is null on
+  the last page (one extra row is fetched to know). `total` is set when
+  Cloud ALM counts (OData).
+- **Errors come in four shapes** (`{message}`, `{error:{message}}`,
+  `[{message}]`, `{message,status}`); the library reads all of them.
+- **Analytics rows are aggregates**, one per combination of dimension
+  values, not records. Unknown or unfilterable dimensions in `filters` are
+  ignored by Cloud ALM. Some datasets refuse without a filter (428, e.g.
+  `ServiceLevels` needs a business service id).
+- **Links live with one side.** A task's test cases are found from Test
+  Management (`toTaskAssignments/any(a:a/taskId eq …)`), its features
+  from the task's feature assignments, its requirement from relation type
+  10 (`parentId` stays empty), its processes from
+  `tasks/solutionProcessAssignments`. A link the key has no scope for is
+  listed as not readable instead of failing the task. `calm_gaps`
+  counts direct links only: a requirement tested only through its user
+  stories counts as uncovered.
+
+## Errors
+
+Every failure is a `CloudAlmError` with a `code` and a short `reason`:
+
+| Code | When |
+| --- | --- |
+| `unauthorized` | no usable token, expired token, 401, key refused by the token endpoint |
+| `forbidden` | 403: the key lacks the scope for this call |
+| `not_found` | 404 (also a wrong path) |
+| `rate_limited` | 429 after two short retries (Cloud ALM allows about 500 requests per 5 s per tenant) |
+| `unavailable` | 5xx, network error, timeout (30 s per operation), non-JSON or oversized answer |
+| `bad_request` | 400, 422, 428, or an argument this library refused (bad id, limit, type) |
+
+A reason never carries the token, the secret or a raw response body; long
+opaque strings are redacted.
+
+## Safety
+
+The reader (`CloudAlm`) sends GET only, to the grant's `baseUrl` only,
+which must be `https://` on a `*.alm.cloud.sap` host (`hostPattern` option
+to change it for a test double). No redirects followed. At most 40 requests
+and 30 seconds per operation; answers above 8 MB are refused.
+
+The writer (`CloudAlmWriter`), used only in write mode, sends POST, PATCH
+or DELETE only to a fixed allow-list of (method, path) pairs: create and
+change tasks, features, documents and manual test cases (with their
+activities and steps), comments, tags, links, and the deletes the API
+offers. It never retries. A test case write carries its ETag (Cloud ALM
+answers 428 without one).
+
+## Develop
+
+Bun for development and tests, plain Node 22+ for the built package.
+
+```sh
+bun install
+bun run typecheck
+bun run test          # unit tests on hand-written fixtures, in-process MCP client over both modes, CLI with fakes
+bun run build         # dist/ for Node
+node dist/cli.js doctor
+CALM_SERVICE_KEY=~/keys/calm-read.json bun scripts/live-check.ts stdio   # against a real tenant
+CALM_SERVICE_KEY=~/keys/calm-read.json bun scripts/live-check.ts http
+```
+
+The live check calls every tool against a real tenant and prints per tool
+whether it answered and the size of the answer, never its text, the secret
+or a token. Test fixtures are invented values in the shapes a real tenant
+returns.
+
+Try the package as users get it:
+
+```sh
+npm pack --pack-destination /tmp
+cd "$(mktemp -d)" && npm init -y >/dev/null && npm i /tmp/cloud-alm-mcp-server-*.tgz
+npx --no-install cloud-alm-mcp-server doctor
+```
+
+CI runs typecheck, tests, build, a start-up check and the packed command on
+Node 22 and 24. Releases: bump `version` in `package.json`, add a
+`CHANGELOG.md` entry, tag `vX.Y.Z` and push the tag; the release workflow
+checks again and runs `npm publish --provenance`. It publishes nothing
+until the repository has an `NPM_TOKEN` secret.
+
+## Licence
+
+MIT: see [LICENSE](LICENSE). Use it, change it, ship it.

package/dist/approval.d.ts

@@ -0,0 +1,41 @@
+/** off: write at once; prefer: approve in the card or the chat; required: in the card (or an opted-in dialog) only. */
+export type ApprovalMode = "off" | "prefer" | "required";
+export declare const APPROVAL_MODES: ApprovalMode[];
+export declare const CARD_URI = "ui://cloud-alm/approve-v1.html";
+export declare const META_KEY = "cloud-alm/approval";
+/** Long enough for a user who answers a turn later; still single-use and bound to one change. */
+export declare const TTL_MS: number;
+/** A write waiting for the user. Holds the tool name and its arguments, not a client. */
+type Pending = {
+    tool: string;
+    /** Whether it may be taken without the card's nonce (mode prefer). */
+    allowChat: boolean;
+    args: Record<string, unknown>;
+    preview: string;
+    subject: string;
+    nonce: Buffer;
+    expiresAt: number;
+};
+/** Who may approve: the stdio user, or the holder of the same bearer token. */
+export declare const subjectOf: (token: string | undefined) => string;
+export type Proposal = {
+    id: string;
+    nonce: string;
+    expiresAt: number;
+};
+export declare function propose(entry: Omit<Pending, "nonce" | "expiresAt">, now?: number): Proposal;
+export declare class ApprovalError extends Error {
+}
+/**
+ * Take a pending write out (single use). With `nonce`, it must match: the
+ * card path. Without, only entries that allow the chat (mode prefer) may.
+ */
+export declare function take(id: string, subject: string, nonce: string | undefined, now?: number): Pending;
+/** Forget every pending write (tests). */
+export declare function clearPending(): void;
+/**
+ * The approval card. Shows the server's preview (never HTML from the
+ * model or the tenant: text only), and Approve / Reject.
+ */
+export declare function cardHtml(): string;
+export {};