@lessly/sdk-app 60.0.0 → 61.0.1

package/README.md

@@ -26,6 +26,28 @@ await sdk.organization.product.create({ name: 'Acme' });
 The available namespaces track the live catalog and grow as platform extensions migrate; check
 `package.json` `exports` (or `src/gen/manifest.gen.ts`) for what a given version exposes.
 
+### Operation identity on every method
+
+Every generated REST method is a callable that also carries its own catalog identity, typed as
+`((input: X) => Promise<Y>) & Operation`:
+
+```ts
+sdk.mail.domain.create.operationKey; // 'mail_domain_create' — the catalog tool name
+sdk.mail.domain.create.level;        // 'admin' — one of 'read' | 'write' | 'admin'
+```
+
+`level` comes verbatim from the platform catalog — the SDK transports it and never infers it from
+`readOnly` or the HTTP method. Read both off the method rather than rebuilding a tool name from the
+accessor path: a hyphenated resource (`sdk.tracking['event-names'].list`) joins several id
+segments, so the path is a lossy view of the name. The properties are own properties of the
+function, so they survive destructuring (`const { list } = sdk.organization.connectors`).
+
+`src/gen/manifest.gen.ts` additionally exports `operations`, the whole tool-name -> level table,
+for callers that need a level without holding a client.
+
+Streaming (`<tool>Connect`) factories carry neither field: a socket is neither a read nor a write,
+and the catalog declares no level for a ws-only tool.
+
 Errors are surfaced as a typed `LesslyApiError` (`status`, `code`, `body`). Mutating calls
 without the `lessly_csrf` cookie fail before the network with `status: 0` and
 `code: 'csrf_cookie_missing'` — no retry, no hidden refresh.
@@ -137,12 +159,41 @@ would otherwise outrank it and silently resolve the lookup against GAR — which
 early run read GAR's `0.1.x` line instead of the empty npmjs registry and skipped the `0.2.0`
 floor. This requires no change to the CLI's `--channel`/`--catalog-url`/`--baseline` contract.
 
+### Runtime changes: `runtime-bump.json`
+
+The catalog diff only classifies **generated** code. The hand-written runtime (`src/runtime`, plus
+`src/react` when present) is gated separately: the pipeline content-hashes those trees into
+`runtimeHash` and stores it in the snapshot, so a runtime-only change publishes on its own instead
+of waiting for an unrelated catalog change.
+
+A runtime change ships at least a **PATCH**. To publish it at a higher level, commit the marker at
+the repo root:
+
+```json
+{ "level": "minor" }
+```
+
+- `runtime-bump.json` — `{ "level": "none" | "patch" | "minor" | "major" }`; a missing file reads as
+  `none`. Any other value fails the run.
+- The marker applies **only while `runtimeHash` differs from the snapshot's**. The pipeline never
+  commits, so it is not reset after use — it simply goes inert once that publish is snapshotted and
+  the hashes match again. Set it in the same commit as the runtime change and leave it at that
+  value; set it back to `"none"` whenever you like.
+- The published level is the **highest** of: the catalog diff (only when the generated output
+  changed), the runtime level (`max(marker, patch)` when the runtime changed), and `patch` when the
+  shipped docs changed. A `major` catalog diff therefore outranks a `minor` marker, and vice versa.
+- A legacy snapshot with no `runtimeHash` publishes **one seeding PATCH** (when a runtime is
+  present) to record the hash, after which detection is fully hash-based — the same two-mode shape
+  as `docsHash`.
+
 ### Snapshot shape
 
-`out/new-snapshot.json` is now a wrapper, `{ catalog, docsHash }`, rather than a bare catalog —
+`out/new-snapshot.json` is now a wrapper, `{ catalog, docsHash, runtimeHash }`, rather than a bare
+catalog —
 `docsHash` is the content hash of the **shipped** guide (the `docs/*.md` + `docs/recipes` files,
 matching the `files` globs; internal `docs/superpowers/` is excluded), added so a docs-only change
-(no catalog diff) still triggers a PATCH publish. The file remains an **opaque blob** to Cloud
+(no catalog diff) still triggers a PATCH publish; `runtimeHash` covers `src/runtime` + `src/react`
+(see "Runtime changes" above). The file remains an **opaque blob** to Cloud
 Build: store it in GCS exactly as written and pass it back verbatim as `--baseline` on the next
 run. Older, bare-catalog baselines from before this change are still accepted: because such a
 baseline predates in-package docs, the first run against it publishes a **one-time migration