@shoalrun/cli 0.1.0-alpha.11 → 0.1.0-alpha.13

package/agent-docs/content-delivery/api.md

@@ -0,0 +1,130 @@
+---
+id: reference.content-client
+title: Content client API
+summary: Look up the content client entry point, snapshot methods, limits,
+  results, and errors.
+type: reference
+area: publishing
+subarea: publishing-content-delivery
+canonical: /content-delivery/api
+---
+
+# Content client API
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Content delivery > Content client API
+
+**Updated: 2026-10-29.**
+
+Import the browser-safe delivery API from `@shoalrun/cli/content`. It reads exports and mounts trusted HTML without loading the compiler. Browser use requires HTTPS or localhost for Web Crypto.
+
+Available since `0.1.0-alpha.13`.
+
+## Open a source
+
+```ts
+openManifestContentSource(options): Promise<ContentSnapshot>
+```
+
+| Option                 | Meaning                                                      | Default        |
+| ---------------------- | ------------------------------------------------------------ | -------------- |
+| `manifestUrl`          | HTTP(S) manifest URL; relative URLs use the browser location | Required       |
+| `fetch`                | Application-provided fetch implementation                    | Global `fetch` |
+| `signal`               | Cancellation signal for opening the manifest                 | None           |
+| `limits.manifestBytes` | Maximum manifest response bytes                              | 5,000,000      |
+| `limits.resourceBytes` | Maximum representation response bytes                        | 8,000,000      |
+| `limits.resources`     | Maximum resources in a manifest                              | 10,000         |
+
+`manifestUrl` accepts a string or `URL`. Outside a browser, supply an absolute URL. URLs must omit credentials, query strings, and fragments; the manifest must sit within its declared `publicBase`.
+
+Limits must be positive safe integers. The browser client requires the application origin and refuses redirects. The server must send `application/json` for the manifest and the declared content type for representations.
+
+## Open a REST source
+
+```ts
+openRestContentSource(options): Promise<ContentSnapshot>
+```
+
+`RestContentSourceOptions` accepts `baseUrl`, a required `{ channel, version, language }` publication, and an optional `revision`. It also accepts the same `fetch`, `signal`, and `limits` options as the manifest source. `limits.manifestBytes` bounds the JSON inventory response. Opening fetches that inventory and pins subsequent reads to its revision.
+
+Browser URLs must share the application's origin. Outside a browser, provide an absolute HTTP(S) URL. The base URL must omit credentials, query strings, and fragments. `contentResourceKey(ref)` returns a REST resource key; it is distinct from the local comparison key returned by `contentRefKey(ref)`. See the [HTTP reference](https://www.shoalrun.com/content-delivery/http-api.md) for routes and response types.
+
+## Read a snapshot
+
+A snapshot exposes the following members for one opened revision.
+
+| Member                          | Contract                                            |
+| ------------------------------- | --------------------------------------------------- |
+| `revision`                      | Opened manifest digest                              |
+| `publication`                   | Channel, version, and language                      |
+| `list()`                        | Read-only resource metadata for this revision       |
+| `get(ref, { format, signal? })` | Promise for a checked HTML or Markdown result       |
+| `dispose()`                     | Cancel the snapshot lifetime and refuse later reads |
+
+```ts
+type ContentRef =
+  | { kind: 'page'; documentId: string }
+  | { kind: 'section'; documentId: string; sectionId: string }
+  | { kind: 'snippet'; id: string };
+```
+
+`list()` is synchronous because opening a source loads and freezes its metadata. Each `get()` fetches and checks UTF-8, media type, byte count, and SHA-256 against that revision; the client does not cache response bodies. `dispose()` is idempotent, aborts active reads, and makes later `list()` and `get()` calls fail. The opening signal affects only opening; use the per-read signal or `dispose()` for subsequent reads.
+
+A `ContentResult` contains `resource`, `representation`, `format`, `content`, and `revision`. `contentRefKey(ref)` returns a key for comparing typed references. It is not a URL or authorization decision.
+
+## Validate a manifest
+
+```ts
+validateContentManifest(value, maxResources = 10_000, maxResourceBytes = 8_000_000): asserts value is ContentManifest
+```
+
+This exported helper checks structure, inventory limits, and approved review metadata. It does not fetch files or verify the manifest digest. Use `openManifestContentSource` for the complete loading and integrity checks. See the [manifest reference](https://www.shoalrun.com/content-delivery/manifest.md) for `ContentResource`, `ContentRepresentation`, `ContentAnchor`, and `ContentLink` fields.
+
+## Mount HTML
+
+```ts
+mountContent(container, result, { instanceId?, signal? })
+```
+
+The result must be HTML from a trusted export. Mounting replaces the container's children, assigns instance-specific DOM IDs, and rewrites local ID references. The returned `ContentMount` contains `anchors`, `links`, and `unmount()`. See [render content](https://www.shoalrun.com/content-delivery/render.md) for ownership and routing.
+
+`instanceId` is optional; the default uses a random UUID. A supplied ID must start with an ASCII letter and contain at most 128 letters, numbers, underscores, or hyphens. Use a different ID for each simultaneous mount. `anchors` maps original anchor IDs to mounted DOM IDs, while `links` carries routing metadata. `signal` cancels before insertion; aborting it after mounting does not remove content. Call `unmount()` to remove only nodes still owned by that mount.
+
+## Errors
+
+Use `ContentDeliveryError.code` to distinguish these failures.
+
+| Code                 | Meaning                                                                                                                                |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `invalid_manifest`   | Invalid source URL, options, inventory, manifest shape, digest, or review metadata                                                     |
+| `not_found`          | Missing manifest, unknown resource reference, or REST `404`                                                                            |
+| `unsupported_format` | Unavailable representation, REST `406`, or non-HTML input passed to `mountContent`                                                     |
+| `stale_revision`     | Content bytes differ from the opened revision, a static representation file is missing, or REST returns `409`                          |
+| `network_error`      | Failed or interrupted request; REST `400`, `405`, or `500`; or HTTP failures outside the REST contract, such as `401`, `429`, or `503` |
+| `invalid_content`    | Wrong response media type, invalid UTF-8, exceeded response limit, malformed REST error, or invalid mount content                      |
+| `disposed`           | Reading a disposed snapshot or a read aborted by disposal                                                                              |
+
+The static client maps a missing representation file to `stale_revision`; the REST client preserves `404` as `not_found`. Opening a REST inventory with a different requested revision also produces `stale_revision`.
+
+Defined REST error statuses must carry the documented JSON envelope. A malformed envelope produces `invalid_content`; other HTTP failure statuses produce `network_error` regardless of response body format.
+
+Cancellation can propagate the signal's abort reason instead of a `ContentDeliveryError`. Treat messages as diagnostics rather than parsing them for program logic.
+
+## HTML, Markdown, and agents
+
+The same typed reference selects either available representation. HTML mounting is optional and separate from retrieval. Agents can read Markdown and metadata through the client without a DOM. Digests detect mismatched bytes; they do not establish that an unknown publisher's content is trustworthy.
+
+## Related reading
+
+### Read first
+
+- [Content delivery](https://www.shoalrun.com/content-delivery.md) — Understand resource delivery and its application boundary.
+
+### Related topics
+
+- [Read content with a client](https://www.shoalrun.com/content-delivery/client.md) — Look up client methods, limits, and errors.
+
+- [Serve content through REST](https://www.shoalrun.com/content-delivery/rest.md) — Use the shared snapshot methods and client limits.

package/agent-docs/content-delivery/client.md

@@ -0,0 +1,79 @@
+---
+id: guide.content-client
+title: Read content with a client
+summary: Open a content revision and read typed resources without depending on
+  generated filenames.
+type: how-to
+area: publishing
+subarea: publishing-content-delivery
+canonical: /content-delivery/client
+---
+
+# Read content with a client
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Content delivery > Read content with a client
+
+**Updated: 2026-10-29.**
+
+Use the content client in an application to read a static export. Serve the bundle from the application's origin and use your normal JavaScript build tooling to import `@shoalrun/cli/content`.
+
+Available since `0.1.0-alpha.13`.
+
+## Open a revision
+
+```ts
+import { openManifestContentSource } from '@shoalrun/cli/content';
+
+const snapshot = await openManifestContentSource({
+  manifestUrl: '/content/revisions/r1/manifest.json',
+});
+```
+
+Use an absolute HTTP(S) URL outside a browser. In a browser, the manifest must share the application's origin. Its location must match the export's `publicBase`. The client does not accept URL credentials, query parameters, or fragments in the manifest URL.
+
+Browser use requires HTTPS or localhost because integrity checks use Web Crypto.
+
+Opening fetches and validates the manifest once. `snapshot.revision` identifies that opened revision; it does not track a moving latest pointer.
+
+## Read a resource
+
+```ts
+const resources = snapshot.list();
+const result = await snapshot.get(
+  { kind: 'section', documentId: 'guide.billing', sectionId: 'refunds' },
+  { format: 'markdown' },
+);
+console.log(result.content);
+```
+
+A result includes resource metadata, representation metadata, format, content, and revision. The client verifies representation size and SHA-256 digest before returning content. It does not evaluate MDX, interpolate variables, or run components in the browser.
+
+## Handle changes and cancellation
+
+Pass an `AbortSignal` to an individual `get` to cancel obsolete navigation. Call `snapshot.dispose()` when the application stops using the revision. A disposed snapshot refuses further reads.
+
+If a representation is missing or differs from the opened manifest, the client reports `stale_revision`. Keep the current display, open a complete replacement revision, and retry deliberately. Do not combine resource lists from one revision with files from another.
+
+A custom `fetch` function can integrate the application's request handling. It does not bypass same-origin, content-type, size, or digest checks. Use [openRestContentSource](https://www.shoalrun.com/content-delivery/rest.md) for the same `ContentSnapshot` contract over HTTP.
+
+## HTML, Markdown, and agents
+
+Request HTML for [application rendering](https://www.shoalrun.com/content-delivery/render.md) or Markdown for text consumers and agents. Neither requires a browser widget to recover the content. The manifest records availability per representation; requesting an omitted format returns `unsupported_format` rather than silently converting it.
+
+## Related reading
+
+### Read first
+
+- [Content delivery](https://www.shoalrun.com/content-delivery.md) — Understand resource delivery and its application boundary.
+
+### Related topics
+
+- [Select content resources](https://www.shoalrun.com/content-delivery/select.md) — Read a reviewed export from an application.
+
+- [Content client API](https://www.shoalrun.com/content-delivery/api.md) — Look up client methods, limits, and errors.
+
+- [Render content in an application](https://www.shoalrun.com/content-delivery/render.md) — Mount trusted HTML and route its links.

package/agent-docs/content-delivery/http-api/operations/get-content-representation-fa1d2e3f.md

@@ -0,0 +1,394 @@
+---
+id: reference.content-rest.getContentRepresentation
+title: Read HTML or Markdown
+summary: GET /resources/{key}/representations/{format}
+type: api-reference
+area: api
+subarea: api-reference
+canonical: /content-delivery/http-api/operations/get-content-representation-fa1d2e3f
+---
+
+# Read HTML or Markdown
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Content delivery > Content REST API > Other > Read HTML or Markdown
+
+**Updated: 2026-09-27.**
+
+This reference is generated from the OpenAPI description. It shows the operation contract; follow any related guides below for task steps and context.
+
+OpenAPI for this operation: [Download JSON](https://www.shoalrun.com/api/operations/production/current/en/content-rest-getcontentrepresentation-63a66b7a4eae1e1befb0ade4fd57d8346e3a5548cb933c1718acc72a9ab3ceed.json).
+
+## GET /resources/{key}/representations/{format}
+
+Read HTML or Markdown
+
+Query parameters are single-valued; unknown or duplicate parameters are rejected. Publication and revision checks run before conditional ETag checks. No pagination, search, writes, authentication, or cross-origin policy is supplied by this reference adapter.
+
+### Servers
+
+`/content/v1`
+
+### Parameters
+
+#### channel (query)
+
+Required
+
+Exact publication channel. No default or fallback.
+
+string; minLength: 1; maxLength: 2048
+
+**Default example**: `"production"`
+
+#### version (query)
+
+Required
+
+Exact publication version. No default or fallback.
+
+string; minLength: 1; maxLength: 2048
+
+**Default example**: `"current"`
+
+#### language (query)
+
+Required
+
+Exact publication language. No default or fallback.
+
+string; minLength: 1; maxLength: 2048
+
+**Default example**: `"en"`
+
+#### revision (query)
+
+Required
+
+Exact revision returned by the list endpoint. A different revision returns 409; it never silently reads newer content.
+
+string; pattern: ^\[a-f0-9]{64}$
+
+**Default example**: `"0770e6d70db51967fac8dcc7bb4ff5a5bff87378eb2e2bbb63dea93d090c82e8"`
+
+#### key (path)
+
+Required
+
+Opaque stable typed-reference key. Use the returned key. It is k\_ followed by unpadded base64url of UTF-8 JSON for \["page",documentId], \["section",documentId,sectionId], or \["snippet",id]. Publication and revision are separate selectors.
+
+string; pattern: ^k\_\[A-Za-z0-9\_-]+$
+
+**Default example**: `"k_WyJwYWdlIiwiZ3VpZGUuYmlsbGluZyJd"`
+
+#### format (path)
+
+Required
+
+string
+
+Available options: `"html"`, `"markdown"`
+
+**Default example**: `"markdown"`
+
+#### If-None-Match (header)
+
+Optional
+
+An ETag, comma-separated ETags, or \*. Weak comparison is supported for GET and HEAD.
+
+string
+
+### Example request
+
+```bash
+curl --request GET \
+  --url 'https://YOUR_API_HOST/content/v1/resources/YOUR_KEY/representations/YOUR_FORMAT?channel=YOUR_CHANNEL&version=YOUR_VERSION&language=YOUR_LANGUAGE&revision=YOUR_REVISION'
+```
+
+### Responses
+
+#### 200: OK
+
+`text/html`
+
+`text/markdown`
+
+The selected resource or inventory.
+
+##### Response headers
+
+###### ETag
+
+Optional
+
+Strong SHA-256 validator of the exact UTF-8 response bytes.
+
+Serialization: simple; explode: false.
+
+string
+
+###### Cache-Control
+
+Optional
+
+Unpinned discovery uses no-cache. Revision-pinned success uses public, max-age=31536000, immutable. Errors use no-store.
+
+Serialization: simple; explode: false.
+
+string
+
+##### text/html
+
+string
+
+##### Example: Illustrative content; discover keys and revision from your own host.
+
+Key: illustrative. Location: response 200; text/html. Authored in OpenAPI.
+
+```text
+<p>Contact support.</p>
+
+```
+
+##### text/markdown
+
+string
+
+##### Example: Illustrative content; discover keys and revision from your own host.
+
+Key: illustrative. Location: response 200; text/markdown. Authored in OpenAPI.
+
+```text
+Contact support.
+
+```
+
+#### 304: Not Modified
+
+The validated selected response matches If-None-Match. No response body.
+
+##### Response headers
+
+###### ETag
+
+Optional
+
+Strong SHA-256 validator of the exact UTF-8 response bytes.
+
+Serialization: simple; explode: false.
+
+string
+
+###### Cache-Control
+
+Optional
+
+Unpinned discovery uses no-cache. Revision-pinned success uses public, max-age=31536000, immutable. Errors use no-store.
+
+Serialization: simple; explode: false.
+
+string
+
+#### 400: Bad Request
+
+`application/json`
+
+invalid_request: missing, duplicate, unknown, or malformed query parameter.
+
+##### Response headers
+
+###### Cache-Control
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "no-store"
+
+1 property
+
+- `error` `object` **always present**&#x20;
+
+  2 properties
+
+  - `code` `enum<string>` **always present**&#x20;
+
+    Available options: `"invalid_request"`, `"not_found"`, `"unsupported_format"`, `"stale_revision"`, `"method_not_allowed"`, `"internal_error"`
+
+  - `message` `string` **always present**&#x20;
+
+  Additional properties: not allowed.
+
+Additional properties: not allowed.
+
+#### 404: Not Found
+
+`application/json`
+
+not_found: unknown publication, resource, or route.
+
+##### Response headers
+
+###### Cache-Control
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "no-store"
+
+1 property
+
+- `error` `object` **always present**&#x20;
+
+  2 properties
+
+  - `code` `enum<string>` **always present**&#x20;
+
+    Available options: `"invalid_request"`, `"not_found"`, `"unsupported_format"`, `"stale_revision"`, `"method_not_allowed"`, `"internal_error"`
+
+  - `message` `string` **always present**&#x20;
+
+  Additional properties: not allowed.
+
+Additional properties: not allowed.
+
+#### 405: Method Not Allowed
+
+`application/json`
+
+method_not_allowed: only GET and HEAD are supported; Allow lists both.
+
+##### Response headers
+
+###### Cache-Control
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "no-store"
+
+###### Allow
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "GET, HEAD"
+
+1 property
+
+- `error` `object` **always present**&#x20;
+
+  2 properties
+
+  - `code` `enum<string>` **always present**&#x20;
+
+    Available options: `"invalid_request"`, `"not_found"`, `"unsupported_format"`, `"stale_revision"`, `"method_not_allowed"`, `"internal_error"`
+
+  - `message` `string` **always present**&#x20;
+
+  Additional properties: not allowed.
+
+Additional properties: not allowed.
+
+#### 406: Not Acceptable
+
+`application/json`
+
+unsupported_format: unsupported or unavailable representation format.
+
+##### Response headers
+
+###### Cache-Control
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "no-store"
+
+1 property
+
+- `error` `object` **always present**&#x20;
+
+  2 properties
+
+  - `code` `enum<string>` **always present**&#x20;
+
+    Available options: `"invalid_request"`, `"not_found"`, `"unsupported_format"`, `"stale_revision"`, `"method_not_allowed"`, `"internal_error"`
+
+  - `message` `string` **always present**&#x20;
+
+  Additional properties: not allowed.
+
+Additional properties: not allowed.
+
+#### 409: Conflict
+
+`application/json`
+
+stale_revision: revision unavailable, or source bytes no longer match the pinned snapshot.
+
+##### Response headers
+
+###### Cache-Control
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "no-store"
+
+1 property
+
+- `error` `object` **always present**&#x20;
+
+  2 properties
+
+  - `code` `enum<string>` **always present**&#x20;
+
+    Available options: `"invalid_request"`, `"not_found"`, `"unsupported_format"`, `"stale_revision"`, `"method_not_allowed"`, `"internal_error"`
+
+  - `message` `string` **always present**&#x20;
+
+  Additional properties: not allowed.
+
+Additional properties: not allowed.
+
+#### 500: Internal Server Error
+
+`application/json`
+
+internal_error: the source could not complete the request.
+
+##### Response headers
+
+###### Cache-Control
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "no-store"
+
+1 property
+
+- `error` `object` **always present**&#x20;
+
+  2 properties
+
+  - `code` `enum<string>` **always present**&#x20;
+
+    Available options: `"invalid_request"`, `"not_found"`, `"unsupported_format"`, `"stale_revision"`, `"method_not_allowed"`, `"internal_error"`
+
+  - `message` `string` **always present**&#x20;
+
+  Additional properties: not allowed.
+
+Additional properties: not allowed.