@vantageos/mcp-boilerplate 0.2.3 → 0.3.0

package/README.md

@@ -9,8 +9,8 @@ stateless Streamable HTTP from one server definition, its **own OAuth 2.1
 authorization server** (a Clerk person picks an organisation), an MCP Apps UI
 and FR/EN messages. No custom REST route ever stands in front of a tool call.
 
-It ships three small example tools (`ping`, `list_items`, `render_items_ui`)
-that exercise every layer. Replace them with yours; the wiring stays.
+It ships two small example tools (`ping`, `list_items`) that exercise every
+layer; `list_items` also carries the MCP Apps widget. Replace them with yours; the wiring stays.
 
 ## Structure
 
@@ -18,16 +18,24 @@ that exercise every layer. Replace them with yours; the wiring stays.
 src/
   mcpServerFactory.ts   # single MCP server definition, shared by both transports
   version.ts            # server name + version, derived from package.json
+  serverManifest.ts     # fail-closed loader of mcp-server.json (the server manifest)
+  toolRecord.ts         # typed tool record: authority, verb, table, mechanism, pagination, cost
+  pagination.ts         # cursor pagination applied by the tool (default, finite max, invalid_cursor)
+  buildIdentity.ts      # build identity derived from the served tree
   stdio.ts              # serveStdio(factory): both protocol eras over stdio
   http.ts               # Node http.Server adapter around the Hono app
   httpApp.ts            # createMcpHandler(factory) on /mcp + the OAuth gate
   auth.ts               # resource-server wiring (@vantageos/cloud-identity)
   config.ts             # env-derived AuthMode + external-issuer AuthConfig
   tenancy.ts            # verified JWT -> tenant; rows filtered by stored orgId
+  lake/                 # read-only data-lake reader: interface + in-memory default, Convex adapter
+    reader.ts  convex.ts
   oauth/                # own authorization server (cloud-identity decides)
     authorizationServer.ts  settings.ts  clerk.ts  tokenIssuer.ts
     clientRegistry.ts       codeStore.ts picker.ts
   ui/                   # MCP Apps widget + ui:// resource
+mcp-server.json         # the server manifest: capabilities, transport, version, feature switches
+.github/workflows/release.yml   # npm publish --provenance + registry proof (Actions is disabled fleet-wide)
 skills/connect-mcp-server/SKILL.md   # onboarding skill (English)
 scripts/
   plugin-manifest.source.json  # the ONE source of every packaging manifest
@@ -73,12 +81,33 @@ server version is read from `package.json`.
 
 ## Tool records
 
-Every tool declares `title`, the four annotations as explicit booleans
-(`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), a typed
-input schema and a typed output schema (Zod 4), and returns `structuredContent`
-plus a text block with the same JSON. `tests/toolRecordComplete.test.ts` walks
-`tools/list` and fails on any gap. Annotations are untrusted hints for the
-client (mcp-standard C-15); never gate an action on them alone.
+Every tool declares `title`, a typed input schema and a typed output schema (Zod 4),
+and returns `structuredContent` plus a text block with the same JSON. Its
+`annotations` carry the typed record of `src/toolRecord.ts`, readable from
+`tools/list` without reading the source:
+
+| Key | Rule | Meaning |
+|---|---|---|
+| `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` | C-15 | the four behavioural booleans |
+| `authRead`, `authWrite` | C-8 | authority pair from `public` / `org-member` / `org-admin` / `fleet-internal` / `master`, distinct; resolved from the verified identity, never from an argument |
+| `verb`, `table` | C-9, C-12 | the operation (`list`, `get`, `create`, `pure`...) and the data it touches |
+| `searchMechanism` | C-10 | how a list/search is served (`indexed-range` here); `unindexed-scan` does not publish |
+| `paginationCursor`, `paginationDefault`, `paginationMax` | C-11 | cursor, default page size and a finite maximum, applied by `src/pagination.ts` |
+| `tokensEstimeContexte` | C-13 | estimated context cost; `CONTEXT_CEILING` bounds each tool and the sum |
+
+The sets are closed TypeScript unions: a value outside them does not compile, and a
+list tool cannot omit its mechanism or its pagination. Each tool's record is a plain
+object of literals so a static checker can read it. `list_items` pages
+its rows: `limit` (default 20, capped at 100) and an opaque
+`cursor`; a truncated page carries `nextCursor` and `exhausted: false`, the last page
+`exhausted: true`; an invalid or expired cursor is a tool
+input error: a result with `isError: true` and `structuredContent.error.code`
+`invalid_cursor` (message FR/EN), never a silent first page. The JSON-RPC `-32602`
+stays with the protocol list methods' cursor, which the SDK serves.
+
+`tests/toolRecordComplete.test.ts` and the C-8..C-13 suites walk `tools/list` and
+fail on any gap. Annotations are untrusted hints for the client (mcp-standard C-15);
+never gate an action on them alone.
 
 ## Authentication tiers
 
@@ -125,7 +154,15 @@ shared between instances) unless both durable adapters are injected or
 single-instance deployment. Behind a reverse proxy set `MCP_TRUSTED_PROXY_COUNT`
 to the number of trusted proxies (default `0`): the `/register` rate limit then
 keys on the proxy-appended `X-Forwarded-For` entry, never on the client-supplied
-first one; with `0` it keys on the socket address and ignores the header.
+first one; with `0` it keys on the socket address and ignores the header. The value is the
+number of proxy HOPS that append to `X-Forwarded-For`, not the number of products you run:
+Railway needs `2` (measured: its header carries the client, then the edge proxy). A count
+that is too LOW fails silently, because the limiter then keys on a proxy address shared by
+many clients. To measure it, send 21 registrations from one client and expect a `429` on
+the 21st. An IPv6 client is keyed on its /64 and ALSO counted against its /48: every /64 inside one
+/48 shares `MCP_REGISTER_LIMIT_PER_48_PER_MINUTE` registrations per minute (default `100`), so
+one /48, which holds 65536 /64s, cannot fill the client registry to its `503`. An invalid value
+stops the server at start.
 
 **Request limits and CORS**: An operator variable that is set but invalid (for example `MCP_MAX_BODY_BYTES=abc`) stops the server at startup with the variable's name and the expected form, never a silent default; unset or empty keeps the default. the Node entry reads at most `MCP_MAX_BODY_BYTES`
 (default 1 MiB) of a request body and answers `413` before any handler runs.
@@ -183,6 +220,10 @@ server you host, in this order:
    logs one warning at boot, in English and French, naming the Home URL requirement. It is a
    warning, never a refusal: it means "a remote sign-in will only work if the Home URL points
    at this server, or if you move to a production instance". It carries no key or secret.
+6. **The consent page.** The organisation picker uses the VantagePeers dashboard design: dark
+   by default, light when the person's system asks for it, one card per organisation with its
+   role. It loads no external asset, so it carries its own tokens. Set `AUTHORIZE_BRAND_NAME`
+   to show your product's name above the title; nothing is shown by default.
 
 ### Multi-tenancy
 
@@ -191,6 +232,209 @@ organisation (`isRowInTenant`); a token with no organisation gets an explicit
 tool refusal, never an unscoped view. Resolve the caller's tenant only from the
 verified token, never from a tool argument.
 
+### The verified person in a tool
+
+A tool can also need the PERSON behind the call (subject, role, admin standing), for example to
+filter rows per person. The person is resolved once per `/mcp` request by
+`@vantageos/cloud-identity`'s `resolveCallerFromClaims`, from the same verified claims as the
+tenant; the server never reads a claim itself. The package reads two stores you inject, and the
+admin roles are yours to name (required, non-empty, no default):
+
+```ts
+import { buildHttpApp } from "@vantageos/mcp-boilerplate";
+
+const app = buildHttpApp({
+  authMode: "oauth",
+  authorizationServer,
+  identity: {
+    orgLookups: { orgById: (orgId) => orgStore.get(orgId) },
+    principalLookups: {
+      personById: (personId, orgId) => people.get(orgId, personId),
+      organisationById: (orgId) => orgStore.row(orgId),
+      orgKindOf: (orgId) => orgStore.kind(orgId),
+    },
+    adminRoles: ["org:admin"],
+  },
+});
+```
+
+A tool declares that it needs the person by wrapping its handler with `withVerifiedPerson`
+(in `src/mcpServerFactory.ts`, where `deps` is the per-request context the tenant travels in):
+
+```ts
+server.registerTool("my_rows", config, withVerifiedPerson(deps, async (args, person) => {
+  // person: { subject, actorName, org, principal, role, isOrgAdmin }, frozen, as the package returned it
+  return structuredResult({ rows: rowsVisibleTo(person.subject) });
+}));
+```
+
+Unless the person resolved, the handler does not run: the call gets an MCP tool error with the
+stable code `person_unresolved` (`structuredContent.error.code`), a FR/EN message per
+`X-MCP-Locale`, and a `reason`: `identity_not_configured` (no `identity` injected),
+`no_verified_session` (public tier, and **stdio, which never has a person**: there is no bearer
+on that transport) or `refused` (the package refused; its `code` and `reason` are carried, never
+a claim value). A tool that does not wrap its handler runs exactly as before, with no person.
+
+## Calling an upstream API (OAuth 2 client_credentials)
+
+A server derived from this boilerplate that reads a third-party API with its own credentials
+uses `createClientCredentialsTokenSource` (`src/upstream/clientCredentials.ts`). Create it ONCE
+at module scope: the MCP server is rebuilt per request, and the token cache lives in the source.
+
+```ts
+const upstream = createClientCredentialsTokenSource(
+  clientCredentialsFromEnv({
+    clientIdVar: "UPSTREAM_CLIENT_ID",
+    clientSecretVar: "UPSTREAM_CLIENT_SECRET",
+    tokenUrlVar: "UPSTREAM_TOKEN_URL",
+  })
+);
+// in a tool handler:
+const res = await upstream.fetchWithToken("https://api.upstream.example/v1/things");
+```
+
+The variable names are yours to choose. The token is cached until `expires_in` minus a 60 s
+skew, concurrent callers share one token request, and a 401 triggers one token refetch and one
+retry, never more. Client authentication is `client_secret_basic` by default, or
+`client_secret_post`. A missing variable is named at start, its value never shown; a token
+endpoint failure is an `UpstreamTokenError` with the status and OAuth `error` code, never a
+credential or a token.
+
+### Reading every page of an offset-paginated endpoint
+
+`createPaginatedUpstreamClient` (`src/upstream/paginatedClient.ts`) reads an upstream endpoint
+paginated by offset and limit. The parameter names, where they travel (`query` or `jsonBody`)
+and the method are configuration. Create it once at module scope, beside the token source:
+
+```ts
+const things = createPaginatedUpstreamClient({
+  fetchImpl: upstream.fetchWithToken,
+  baseUrl: "https://api.upstream.example/v1/",
+  allowedOrigins: ["https://api.upstream.example"],
+  offsetParam: "offset",
+  limitParam: "limit",
+  placement: "jsonBody", // POST with offset and limit in the JSON body; "query" sends a GET
+  rowCeiling: 5000,
+  extractRows: (body) => (body as { data: unknown[] }).data,
+});
+const all = await things.readAll("things", { status: "active" }); // every page, or a refusal
+const page = await things.readPage("things", { status: "active" }, cursor); // one page per call
+```
+
+`allowedOrigins` and `rowCeiling` are required. A path resolving to another origin is refused before
+any network call, so the bearer token never leaves for a host a tool argument names, and redirects
+are refused rather than followed (`redirect: "error"`). `readAll` stops on the short page (or at the
+total, with `extractTotal`) and refuses a set above the ceiling with `row_ceiling_exceeded`, never a
+silently truncated one. `readPage` returns `{ rows, nextCursor?, exhausted }`; its cursor is bound
+to the path and params, and one replayed against another query or altered without recomputing its
+fingerprint is refused as `invalid_cursor`. The fingerprint is unkeyed: it detects misuse, not
+forgery; the offset carries no authority and a minted offset above the ceiling is refused before any
+request. An empty page before a declared total is refused as `inconsistent_page`, never
+re-requested. 429 and 503 are retried with exponential backoff (default 5 attempts, 500 ms base,
+30 s cap) and honour `Retry-After`; no other status is retried. Errors (`UpstreamPageError`) name the
+path and the status, never a token, a parameter value or the body. Keep `pageSize` (default 100)
+within the upstream's real maximum: a page silently capped below it reads as the last one unless the
+response declares a total.
+
+## Declaring your own configuration
+
+A derived server declares the environment variables it reads, once, and gets a typed, validated,
+frozen object at start (`src/declaredVariables.ts`):
+
+```ts
+import { defineVariables, describeVariables, loadVariables } from "@vantageos/mcp-boilerplate";
+
+export const declared = defineVariables({
+  apiBaseUrl: {
+    env: "UPSTREAM_API_BASE_URL",
+    type: "url",
+    description: { en: "Upstream API base URL", fr: "URL de base de l'API amont" },
+  },
+  readKey: {
+    env: "LAKE_READ_KEY",
+    type: "string",
+    secret: true,
+    description: { en: "Data lake read key", fr: "Clé de lecture du lac de données" },
+  },
+  pageSize: {
+    env: "UPSTREAM_PAGE_SIZE",
+    type: "integer",
+    min: 1,
+    max: 500,
+    required: false,
+    default: 100,
+    description: { en: "Rows per upstream page", fr: "Lignes par page amont" },
+  },
+  fieldMap: {
+    env: "FIELD_MAPPINGS",
+    type: "json",
+    description: { en: "Code-to-label mappings", fr: "Correspondances code-libellé" },
+  },
+});
+
+export const settings = loadVariables(declared); // settings.pageSize: number
+console.log(describeVariables(declared)); // the contract, for --help: no value, no default
+```
+
+The variable names are yours to choose. Types: `string`, `integer` (`min`/`max`), `boolean`
+(`"0"` or `"1"`), `url` (https, http on loopback only), `originList`, `enum` (`values`) and `json`
+(an object or an array). A variable is required unless it says `required: false`; a `default`
+needs `required: false`. Unset or empty is missing; a set but invalid value is refused, never
+replaced by the default. Every missing or invalid variable is reported together in ONE
+`ConfigurationError` (`problems: { key, env, reason, expected }[]`, message in English and
+French) that names the variables and never shows a value. The result is frozen and typed from
+the declaration: an undeclared key does not compile, and reading one at runtime throws.
+`JSON.stringify`, `String()` and `console.log` of the result never throw and show a `secret: true`
+value as `[secret]`; a secret is skipped by spread and `Object.entries`, and read by name only. A
+broken declaration (duplicate env name, unknown type or property, a default that does not validate)
+is refused when `defineVariables` runs. The boilerplate's own variables (`OAUTH_ENV`, the server
+knobs, `clientCredentialsFromEnv`) do not use the registry yet.
+
+## Reading the client's data lake
+
+A derived server reads its client's data lake (the single persisted source) through a READ-ONLY
+interface, `LakeReader` (`src/lake/reader.ts`): `listPage({ after?, limit, scope? })` returns
+`{ rows, exhausted }` in ascending key order, `get(key, scope?)` returns one row or `undefined`,
+and `keyOf(row)` names the stable key the cursor carries. There is no write method. `list_items`
+reads through the reader injected as `buildHttpApp({ lake })` (or `McpServerDeps.lake`); with none
+injected it reads the in-memory seed (`EXAMPLE_ITEMS_READER`), exactly as before. The caller's
+tenant travels INTO the read as `scope`, and every row that comes back is re-checked: a row of
+another tenant fails the call closed. `readPage` applies the tool's bounds and cursor to any reader
+and checks each page against the contract; a page it cannot read (not a list, more rows than
+asked, keys out of order or not after the cursor, a truncated page with no row, a row with no key)
+is a `LakeReadError`, which `list_items` answers as a tool error with the stable code
+`lake_unreadable` and the reason, never an empty or partial page.
+
+The Convex adapter ships at its own subpath; `convex` is an optional peer dependency, installed
+only by a server that imports it:
+
+```ts
+import { convexLakeReaderFromEnv } from "@vantageos/mcp-boilerplate/lake/convex";
+
+const lake = convexLakeReaderFromEnv(
+  process.env,
+  { urlVar: "LAKE_URL", tokenVar: "LAKE_READ_KEY" },
+  {
+    functions: { page: "lakeRead:listRows", get: "lakeRead:getRow" },
+    keyField: "rowKey",
+    tokenArg: "readKey", // omit to send the token through setAuth (Authorization: Bearer)
+  }
+);
+const app = buildHttpApp({ authMode: "oauth", authorizationServer, lake });
+```
+
+The variable names, the query function names and the key field are configuration: nothing in the
+package names a table or a function. The connection variables are declared with `defineVariables`
+(the URL as `url`: https, http on loopback only; the token as a `secret`), so a missing or invalid
+one is refused at start, by name, never by value. The adapter only ever calls
+`ConvexHttpClient.query`, never a mutation or an action. The page function receives
+`{ after?, limit, tenantId? }` and returns the rows whose key is after `after`, ascending, at most
+`limit` (the adapter asks for one row more than the page to tell a truncated page from the last
+one); the get function receives `{ key, tenantId? }` and returns the row or `null`. An optional
+`parseRow` (e.g. a Zod `parse`) types each row and refuses one it cannot read. A failing call is
+`read_failed`, and the client's message is not forwarded: no error carries the token, the URL or a
+row value.
+
 ## Server-side i18n (FR/EN)
 
 `src/i18n.ts` localizes MCP error/validation messages and the picker page: the
@@ -211,9 +455,10 @@ Hono app in-process with the SDK v2 `Client`; the stdio suite spawns the built
 
 ## Adding a tool
 
-Register it once in `src/mcpServerFactory.ts` with `title`, the four
-annotations, `inputSchema` and `outputSchema`, and return
-`structuredResult(...)`. It is then served on both transports and both
+Declare its record in `src/toolRecord.ts` (authority pair, verb, table, and for a
+list/search the mechanism and pagination), register it once in
+`src/mcpServerFactory.ts` with `title`, `annotations: YOUR_ANNOTATIONS`,
+`inputSchema` and `outputSchema`, and return `structuredResult(...)`. It is then served on both transports and both
 protocol eras. `tests/toolRecordComplete.test.ts` keeps it honest.
 
 ## Packaging & distribution
@@ -250,10 +495,56 @@ npm publish                 # prepublishOnly re-runs build + test + evals
 Publication is proven at the registry's `dist-tag`, never by the exit code of
 `npm publish`.
 
+The version lives in `package.json` AND in `mcp-server.json` (the server manifest,
+mcp-standard C-18). Bump both to the same value: `scripts/sync-plugin-version.mjs`
+reads the version from the manifest and refuses a `package.json` that disagrees,
+naming both. The manifest also declares the server's capabilities, which the factory
+serves, and the feature switches later releases read.
+
+## Pin and verify the published package
+
+Install from npm, the registry of record, and pin an EXACT version so an update never
+arrives unasked. `1.2.3` below is an example, not a published version: list the real
+ones and replace it with the version you audited.
+
+```bash
+npm view @vantageos/mcp-boilerplate versions --json     # the published versions
+npm install @vantageos/mcp-boilerplate@1.2.3             # pin an exact version
+```
+
+Roll back by pinning the previous version; no published version is ever removed.
+
+```bash
+npm install @vantageos/mcp-boilerplate@1.2.2             # rollback: the previous version
+```
+
+A second, independent channel carries the same tag: the GitHub release of
+`elpiarthera/vantage-mcp-boilerplate`. The package is published with
+`npm publish --provenance` by `.github/workflows/release.yml`; check the attestation
+with `npm audit signatures`.
+
+GitHub Actions is disabled across the ElPi Corp fleet, so a publication made without CI
+has no provenance attestation. The equivalent check is the checksum of the packed
+tarball, reproduced from a clean checkout of the tag and read back from the registry:
+
+```bash
+npm pack                                # prints the tarball name
+shasum mcp-boilerplate-1.2.3.tgz        # the checksum you reproduce (use the real name)
+curl -s -H 'Cache-Control: no-cache' https://registry.npmjs.org/@vantageos%2Fmcp-boilerplate/1.2.3 \
+  | node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).dist.shasum"
+```
+
+Equal sums: the registry serves what the source builds. A running server proves what
+it serves the same way: `GET /health` returns `{ status, version, buildId }` before any
+authentication. `buildId` is a hash of the files the process runs from, so it changes
+when they change, which `version` does not guarantee.
+
 ## MCP Apps UI layer
 
-`render_items_ui` renders `EXAMPLE_ITEMS` as an interactive widget
-(`io.modelcontextprotocol/ui`, spec 2026-01-26).
+`list_items` renders its page of `EXAMPLE_ITEMS` as an interactive widget
+(`io.modelcontextprotocol/ui`, spec 2026-01-26). One operation on one table is one
+tool (mcp-standard C-12), so the data tool itself carries the UI link; there is no
+separate render tool.
 
 - The tool links its `ui://` resource through the nested `_meta.ui.resourceUri`
   with explicit `visibility: ["model", "app"]`. The tool is registered with
@@ -277,7 +568,7 @@ one self-contained HTML file (an in-repo inlining plugin in `vite.config.ts`,
 `dist/ui-bundle/widget.html`) by `npm run build:ui`, on a path that never
 collides with tsc's `dist/ui/`.
 
-**Identity layer**: `@vantageos/cloud-identity` (^0.19.0) is the only identity
+**Identity layer**: `@vantageos/cloud-identity` (^0.20.2) is the only identity
 package. Its resource-server entry point (`verifyMcpAccessToken`,
 `buildProtectedResourceMetadata`) verifies the Bearer token on `/mcp`; `jose` is
 kept only to mint the authorization server's access tokens. An unreachable key set

package/dist/buildIdentity.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Build identity DERIVED from the served tree (mcp-standard C-25, S-7).
+ *
+ * `version` is a declared value: it changes only when someone remembers to change it, so its
+ * equality between source and server proves nothing about the code actually running. A build
+ * identity is computed from the files the process was started from, so it changes when they
+ * change. It is exposed beside `version`, before authentication, on `/health` (httpApp.ts) and
+ * in the server identity of `server/discover` / `initialize` (mcpServerFactory.ts), so a
+ * deployment is proven by what the server RETURNS, never by what the deploy command printed.
+ *
+ * The identity is the first 16 hex characters of a SHA-256 over every file under the directory
+ * this module runs from (`dist/` when built, `src/` under the test runner): relative path and
+ * content, in path order, so mtimes and directory order never matter and a rename counts.
+ * It reveals nothing about the infrastructure (S-7 anti-rule: the version and nothing else).
+ */
+/** The identity of the tree rooted at `dir`. Refuses a tree with no file: nothing was built. */
+export declare function computeBuildIdentity(dir: string): string;
+/** The identity of the tree THIS process runs from, computed once. */
+export declare function getBuildIdentity(): string;

package/dist/buildIdentity.js

@@ -0,0 +1,62 @@
+/**
+ * Build identity DERIVED from the served tree (mcp-standard C-25, S-7).
+ *
+ * `version` is a declared value: it changes only when someone remembers to change it, so its
+ * equality between source and server proves nothing about the code actually running. A build
+ * identity is computed from the files the process was started from, so it changes when they
+ * change. It is exposed beside `version`, before authentication, on `/health` (httpApp.ts) and
+ * in the server identity of `server/discover` / `initialize` (mcpServerFactory.ts), so a
+ * deployment is proven by what the server RETURNS, never by what the deploy command printed.
+ *
+ * The identity is the first 16 hex characters of a SHA-256 over every file under the directory
+ * this module runs from (`dist/` when built, `src/` under the test runner): relative path and
+ * content, in path order, so mtimes and directory order never matter and a rename counts.
+ * It reveals nothing about the infrastructure (S-7 anti-rule: the version and nothing else).
+ */
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tBoth } from "./i18n.js";
+/** Every file under `dir` as a posix-relative path, sorted. Throws, naming `dir`, if unreadable. */
+function listFiles(dir, prefix = "") {
+    let entries;
+    try {
+        entries = readdirSync(join(dir, prefix), { withFileTypes: true });
+    }
+    catch (error) {
+        throw new Error(tBoth("buildIdentity.unreadable", {
+            dir,
+            reason: error instanceof Error ? error.message : String(error),
+        }));
+    }
+    const files = [];
+    for (const entry of entries) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+            files.push(...listFiles(dir, rel));
+        else if (entry.isFile())
+            files.push(rel);
+    }
+    return files.sort();
+}
+/** The identity of the tree rooted at `dir`. Refuses a tree with no file: nothing was built. */
+export function computeBuildIdentity(dir) {
+    const files = listFiles(dir);
+    if (files.length === 0)
+        throw new Error(tBoth("buildIdentity.empty", { dir }));
+    const hash = createHash("sha256");
+    for (const rel of files) {
+        const content = createHash("sha256")
+            .update(readFileSync(join(dir, rel)))
+            .digest("hex");
+        hash.update(`${rel}\0${content}\n`);
+    }
+    return hash.digest("hex").slice(0, 16);
+}
+let processIdentity;
+/** The identity of the tree THIS process runs from, computed once. */
+export function getBuildIdentity() {
+    processIdentity ??= computeBuildIdentity(dirname(fileURLToPath(import.meta.url)));
+    return processIdentity;
+}