@shoalrun/cli 0.1.0-alpha.17 → 0.1.0-alpha.19

package/dist/turnstile.js

@@ -1,8 +1,31 @@
 import { createHmac, timingSafeEqual } from 'node:crypto';
+import { turnstileHostname, turnstileHostnames } from './turnstile-policy.js';
 export const turnstileVerifyUrl = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
+const previewSecret = '1x0000000000000000000000000000000AA';
+const previewToken = 'XXXX.DUMMY.TOKEN.XXXX';
+// Cloudflare's published test pair returns synthetic hostname metadata rather
+// than a real browser hostname. This helper is used only by loopback preview.
+export function turnstilePreviewVerifier(options = {}) {
+    const send = options.fetch ?? fetch;
+    const verify = turnstileVerifier({ ...options, secret: previewSecret, allowedHostnames: ['example.com'], fetch: async (url, init) => {
+            const response = await send(url, init);
+            if (!response.ok)
+                return response;
+            const result = await response.json();
+            return Response.json({ success: result.success === true && result.metadata?.result_with_testing_key === true, hostname: result.hostname });
+        } });
+    return async (input) => {
+        if (input.token !== previewToken)
+            return false;
+        return verify(input);
+    };
+}
 export function turnstileVerifier(options) {
     if (!options.secret)
         throw new Error('Turnstile needs a secret key');
+    const allowed = new Set(turnstileHostnames(options.allowedHostnames, 'Turnstile allowedHostnames'));
+    if (options.action !== undefined && !/^[A-Za-z0-9_-]{1,32}$/.test(options.action))
+        throw new Error('Turnstile action must contain 1 to 32 letters, numbers, underscores, or hyphens');
     const send = options.fetch ?? fetch;
     return async ({ token, ip }) => {
         // Tokens are short. A missing or oversized one is refused without asking Cloudflare.
@@ -16,7 +39,8 @@ export function turnstileVerifier(options) {
             if (!response.ok)
                 return false;
             const body = await response.json();
-            return body?.success === true;
+            const hostname = turnstileHostname(body?.hostname);
+            return body?.success === true && hostname !== undefined && allowed.has(hostname) && (options.action === undefined || body.action === options.action);
         }
         catch {
             return false;
@@ -30,7 +54,10 @@ export function createSession(options) {
     const maxAge = options.maxAgeSeconds ?? 900;
     const name = 'sr_ask';
     // A separate key, so the cookie signature is never the Turnstile secret itself.
-    const key = createHmac('sha256', options.secret).update('shoalrun-ask-session').digest();
+    const derivation = createHmac('sha256', options.secret).update('shoalrun-ask-session');
+    if (options.context !== undefined)
+        derivation.update('\0').update(options.context);
+    const key = derivation.digest();
     const sign = (expires, caller) => createHmac('sha256', key).update(`${expires}.${caller}`).digest('base64url');
     return {
         name,

package/dist/vercel-function.js

@@ -83,14 +83,14 @@ export async function addAskFunction(input) {
     await mkdir(shoalrun, { recursive: true });
     const assets = path.join(input.distDirectory ?? path.dirname(fileURLToPath(import.meta.url)), '..', 'assets');
     await cp(path.join(assets, 'ask-widget.js'), path.join(shoalrun, 'ask.js'));
-    await writeFile(path.join(shoalrun, 'chat.json'), JSON.stringify({ ...(chat.challenge ? { siteKey: chat.challenge.siteKey, ...(chat.challenge.when === 'always' ? { prewarm: true } : {}) } : {}), ...(chat.log ? { notice: chat.log.notice } : {}), ...(chat.panel ? { panel: chat.panel } : {}) }, null, 2) + '\n');
+    await writeFile(path.join(shoalrun, 'chat.json'), JSON.stringify({ ...(chat.challenge ? { siteKey: chat.challenge.siteKey, ...(chat.challenge.action ? { action: chat.challenge.action } : {}), ...(chat.challenge.when === 'always' ? { prewarm: true } : {}) } : {}), ...(chat.log ? { notice: chat.log.notice } : {}), ...(chat.panel ? { panel: chat.panel } : {}) }, null, 2) + '\n');
     await addPanelToPages(input.staticDirectory, basePath);
     const publications = settings.publications?.defaults;
     const origin = settings.site?.origin;
     const runtime = {
         schemaVersion: 1,
         settings: { chat: settings.chat, retrieval: settings.retrieval, ...(settings.search ? { search: settings.search } : {}), ...(settings.readerFilters ? { readerFilters: settings.readerFilters } : {}) },
-        ...(publications?.channel && publications.version && publications.language ? { variant: { channel: publications.channel, version: publications.version, language: publications.language } } : {}),
+        ...(publications?.channel && publications.version && publications.language ? { variant: { ...(publications.product ? { product: publications.product } : {}), channel: publications.channel, version: publications.version, language: publications.language } } : {}),
         ...(origin ? { hosts: [new URL(origin).host] } : {})
     };
     await writeFile(path.join(func, 'runtime.json'), JSON.stringify(runtime, null, 2) + '\n');

package/example-configs/products/README.md

@@ -0,0 +1,37 @@
+# Independent product editions
+
+This runnable example publishes a small Payments and Reporting documentation site from six source pages. Payments has v2 and v3 releases; Reporting has an independent v1 release. The operating checklist is one source with explicit membership in all three publications.
+
+| Customer profile | Payments | Reporting | Feature grants |
+| --- | --- | --- | --- |
+| Customer A | v3 | v1 | Priority settlement and scheduled exports |
+| Customer B | v2 | v1 | Neither optional feature |
+
+From the repository root, build the CLI once with `npm --prefix framework run build`, then start either preview:
+
+```sh
+node framework/dist/cli.js dev framework/example-configs/products/docs.config.yaml /tmp/shoalrun-products-a --profile framework/example-configs/products/profiles/customer-a.yaml --port 8775
+```
+
+Open <http://127.0.0.1:8775/payments/v3/start> or <http://127.0.0.1:8775/reporting/v1/start>.
+
+```sh
+node framework/dist/cli.js dev framework/example-configs/products/docs.config.yaml /tmp/shoalrun-products-b --profile framework/example-configs/products/profiles/customer-b.yaml --port 8776
+```
+
+Open <http://127.0.0.1:8776/payments/v2/start> or <http://127.0.0.1:8776/reporting/v1/start>.
+
+To include both Payments releases in the same preview, select `profiles/all-releases.yaml` instead. The publication dropdown then offers Payments v2, Payments v3, and Reporting v1. Customer profiles A and B expose only their selected releases.
+
+Language labels are hidden automatically because this example publishes English only. Set `site.publicationSelector.showLanguage: false` to suppress language labels explicitly, or `true` to show them.
+
+Inspect these differences:
+
+- Customer A gets Payments v3 instructions and its priority settlement page. Customer B gets Payments v2 instructions.
+- Both editions use Reporting v1, but only Customer A includes the scheduled exports page and feature-specific sections.
+- Links from the shared operating checklist return to the current product and release.
+- Editing the selected profile, SKU manifest, or page source refreshes the preview. For example, change Customer A's Payments selection from v3 to v2 while leaving Reporting at v1.
+
+`requires` removes whole pages during compilation. `<ForFeature>` removes sections. Neither relies on browser reader filters. `profiles.requireClassification` checks every public source for an explicit `shared: true` or feature requirement.
+
+For a static edition, replace `dev` with `build` and omit `--port`; pass the same profile and output directory. The data and workflows in this example describe a fictional product suite.

package/example-configs/products/content/operations.mdx

@@ -0,0 +1,50 @@
+---
+id: guide.operations
+title: Daily operating checklist
+summary: A shared source page published explicitly into each supported product release.
+slug: /operations
+shared: true
+publications:
+  - { product: payments, channel: production, version: v2 }
+  - { product: payments, channel: production, version: v3 }
+  - { product: reporting, channel: production, version: v1 }
+---
+Run this checklist before closing a reporting period. The same source page serves Payments v2, Payments v3, and Reporting v1; each publication keeps its own links and navigation.
+
+## Before you start
+
+- Confirm the product and release shown in the page header.
+- Check the account and currency used for the day's activity.
+- Keep a list of orders that still need investigation.
+
+## Close the day
+
+1. Review completed payments and unsettled orders.
+2. Compare the settlement total with the matching reporting period.
+3. Record any unresolved discrepancy and assign an owner.
+
+<ForPublication product="payments" version="v2">
+
+### Payments v2 check
+
+Match settlement records using the merchant reference. This instruction belongs only to the Payments v2 publication.
+
+</ForPublication>
+
+<ForPublication product="payments" version="v3">
+
+### Payments v3 check
+
+Match settlement records using the order reference. Use the idempotency key only when investigating retries.
+
+</ForPublication>
+
+<ForFeature allOf="scheduled-exports">
+
+## Check automatic deliveries
+
+Confirm the latest scheduled export arrived and covers the expected period. This section is compiled into Customer A's edition.
+
+</ForFeature>
+
+[Return to this product's getting-started guide](doc:guide.start).

package/example-configs/products/content/payments-v2.mdx

@@ -0,0 +1,30 @@
+---
+id: guide.start
+title: Start with Payments v2
+summary: Configure the reference-based payment workflow used by Customer B.
+slug: /start
+product: payments
+version: v2
+shared: true
+---
+Payments v2 uses a merchant reference to track a payment from creation through settlement. This edition follows the v2 workflow while Reporting remains on its own v1 release.
+
+## Create a payment
+
+1. Choose a unique merchant reference for the order.
+2. Submit the amount and currency with that reference.
+3. Save the returned payment identifier before confirming the order.
+
+```json
+{
+  "merchantReference": "order-1042",
+  "amount": 12500,
+  "currency": "USD"
+}
+```
+
+## Confirm settlement
+
+Match the merchant reference on the settlement record to the original order. Retry a failed submission with the same reference so reconciliation can identify it.
+
+[Review the daily operating checklist](doc:guide.operations).

package/example-configs/products/content/payments-v3.mdx

@@ -0,0 +1,38 @@
+---
+id: guide.start
+title: Start with Payments v3
+summary: Use an idempotency key and a separate reconciliation reference in Payments v3.
+slug: /start
+product: payments
+version: v3
+shared: true
+---
+Payments v3 separates request retries from business reconciliation. Use an idempotency key for retry safety and an order reference for settlement matching. Reporting can stay on v1 when Payments moves to v3.
+
+## Create a payment
+
+1. Generate an idempotency key for this payment attempt.
+2. Send the order reference separately from the key.
+3. Save the returned payment identifier and status.
+
+```json
+{
+  "idempotencyKey": "payment-attempt-1042",
+  "orderReference": "order-1042",
+  "amount": { "value": 12500, "currency": "USD" }
+}
+```
+
+## Retry a submission
+
+Reuse the idempotency key for the same attempt. A new order needs a new key. Keep the order reference stable when comparing payment and settlement records.
+
+<ForFeature allOf="priority-settlement">
+
+## Settle an eligible payment sooner
+
+Your edition includes priority settlement. [Prepare and submit a priority batch](doc:guide.priority-settlement) after the payment reaches the eligible state.
+
+</ForFeature>
+
+[Review the daily operating checklist](doc:guide.operations).

package/example-configs/products/content/priority-settlement.mdx

@@ -0,0 +1,23 @@
+---
+id: guide.priority-settlement
+title: Submit a priority settlement batch
+summary: Check eligibility and submit a Payments v3 priority batch.
+slug: /priority-settlement
+product: payments
+version: v3
+requires:
+  allOf: [priority-settlement]
+---
+Priority settlement is included in Customer A's feature grants. This entire page is absent from an edition without that grant.
+
+## Prepare the batch
+
+1. Select payments that have completed authorization and meet the settlement rules.
+2. Confirm the settlement account, currency, and batch total.
+3. Assign a unique batch reference and submit the batch once.
+
+## Check the result
+
+Save the batch identifier and compare its accepted count with the submitted count. Investigate rejected entries before retrying them; do not resubmit payments already accepted into the batch.
+
+[Return to Payments v3](doc:guide.start).

package/example-configs/products/content/reporting-v1.mdx

@@ -0,0 +1,36 @@
+---
+id: guide.start
+title: Start with Reporting v1
+summary: Reconcile completed payments with a daily reporting period.
+slug: /start
+product: reporting
+version: v1
+shared: true
+---
+Reporting v1 organizes completed transactions by reporting period. Both customer editions use this release, even though they use different Payments versions.
+
+## Prepare a daily report
+
+1. Select a completed reporting period.
+2. Choose the account and settlement currency.
+3. Generate the report and record its period and creation time.
+
+| Field | Check before reconciliation |
+| --- | --- |
+| Reporting period | Covers the day being reconciled. |
+| Currency | Matches the settlement account. |
+| Order reference | Identifies the original order. |
+
+## Compare totals
+
+Compare the report total to the settlement record. Investigate missing orders and currency mismatches before closing the period.
+
+<ForFeature allOf="scheduled-exports">
+
+## Receive reports automatically
+
+Your edition includes scheduled exports. [Configure a recurring delivery](doc:guide.scheduled-exports) after reviewing the account and reporting period.
+
+</ForFeature>
+
+[Use the shared operating checklist](doc:guide.operations).

package/example-configs/products/content/scheduled-exports.mdx

@@ -0,0 +1,23 @@
+---
+id: guide.scheduled-exports
+title: Schedule a daily reporting export
+summary: Choose a delivery period and verify the first Reporting v1 export.
+slug: /scheduled-exports
+product: reporting
+version: v1
+requires:
+  allOf: [scheduled-exports]
+---
+Scheduled exports are included in Customer A's feature grants. Customer B uses the same Reporting v1 release with manual reporting instructions.
+
+## Configure the delivery
+
+1. Select the account, reporting period, and settlement currency.
+2. Choose a daily delivery time after the reporting period closes.
+3. Set the delivery destination and save the schedule.
+
+## Verify the first export
+
+Check that the first delivered file uses the expected period and currency. Compare its row count and total with a report generated manually for the same period.
+
+[Return to Reporting v1](doc:guide.start).

package/example-configs/products/docs.config.yaml

@@ -0,0 +1,56 @@
+schemaVersion: 1
+
+site:
+  title: Harbor product documentation
+  editionBadge: always
+
+theme:
+  preset: reef
+  palette: harbor
+  mode: system
+
+publications:
+  defaults: { channel: production, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  products:
+    payments:
+      label: Payments
+      pathPrefix: /payments
+      defaultVersion: v3
+      versions:
+        v2: { pathPrefix: /v2 }
+        v3: { pathPrefix: /v3 }
+    reporting:
+      label: Reporting
+      pathPrefix: /reporting
+      defaultVersion: v1
+      versions:
+        v1: { pathPrefix: /v1 }
+  enabled:
+    - { product: payments, channel: production, version: v2 }
+    - { product: payments, channel: production, version: v3 }
+    - { product: reporting, channel: production, version: v1 }
+
+profiles:
+  manifest: ./skus.yaml
+  requireClassification: true
+  pruneNavigation: true
+
+frontmatter:
+  defaults:
+    type: guide
+    channel: production
+    language: en
+    access: { policy: public }
+
+navigation:
+  - { id: start, doc: guide.start }
+  - { id: operations, doc: guide.operations }
+  - { id: priority-settlement, doc: guide.priority-settlement }
+  - { id: scheduled-exports, doc: guide.scheduled-exports }
+
+outputs:
+  html:
+    highlighting: { provider: none }
+    shareImages: false

package/example-configs/products/profiles/all-releases.yaml

@@ -0,0 +1,9 @@
+schemaVersion: 1
+skus:
+  - { id: business, revision: '2026' }
+site:
+  title: Harbor - All publications
+  header:
+    links:
+      - { label: Payments, href: /payments/v3/start }
+      - { label: Reporting, href: /reporting/v1/start }

package/example-configs/products/profiles/customer-a.yaml

@@ -0,0 +1,13 @@
+schemaVersion: 1
+skus:
+  - { id: business, revision: '2026' }
+site:
+  title: Harbor - Customer A
+  header:
+    links:
+      - { label: Payments, href: /payments/v3/start }
+      - { label: Reporting, href: /reporting/v1/start }
+publications:
+  enabled:
+    - { product: payments, channel: production, version: v3 }
+    - { product: reporting, channel: production, version: v1 }

package/example-configs/products/profiles/customer-b.yaml

@@ -0,0 +1,13 @@
+schemaVersion: 1
+skus:
+  - { id: business, revision: '2025' }
+site:
+  title: Harbor - Customer B
+  header:
+    links:
+      - { label: Payments, href: /payments/v2/start }
+      - { label: Reporting, href: /reporting/v1/start }
+publications:
+  enabled:
+    - { product: payments, channel: production, version: v2 }
+    - { product: reporting, channel: production, version: v1 }

package/example-configs/products/skus.yaml

@@ -0,0 +1,11 @@
+schemaVersion: 1
+features:
+  priority-settlement:
+    description: Priority settlement instructions for Payments v3.
+  scheduled-exports:
+    description: Scheduled export instructions for Reporting v1.
+skus:
+  business:
+    revisions:
+      '2025': { features: [] }
+      '2026': { features: [priority-settlement, scheduled-exports] }

package/examples/content-delivery/preview.mjs

@@ -24,7 +24,7 @@ const clientDirectory = path.dirname(clientEntry);
 const clientFiles = new Map([
   ['/shoalrun/content-delivery.js', clientEntry],
   ['/shoalrun/content-delivery-contract.js', path.join(clientDirectory, 'content-delivery-contract.js')],
-  ...['content-mount', 'content-delivery-validation', 'content-delivery-transport', 'content-rest-client', 'content-rest-contract'].map(name => [`/shoalrun/${name}.js`, path.join(clientDirectory, `${name}.js`)]),
+  ...['content-mount', 'content-delivery-validation', 'content-delivery-transport', 'content-rest-client', 'content-rest-contract', 'publication-identity'].map(name => [`/shoalrun/${name}.js`, path.join(clientDirectory, `${name}.js`)]),
 ]);
 const mount = '/help/releases/demo/';
 const types = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.json': 'application/json', '.svg': 'image/svg+xml', '.md': 'text/markdown; charset=utf-8', '.png': 'image/png' };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoalrun/cli",
-  "version": "0.1.0-alpha.17",
+  "version": "0.1.0-alpha.19",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"

package/schemas/content-export.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://shoalrun.com/schemas/content-export.schema.json",
-  "title": "Shoalrun content delivery manifest, version 1",
+  "title": "Shoalrun content delivery manifest, versions 1 and 2",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -18,7 +18,10 @@
   ],
   "properties": {
     "schemaVersion": {
-      "const": 1
+      "enum": [
+        1,
+        2
+      ]
     },
     "kind": {
       "const": "shoalrun-content-export"
@@ -229,6 +232,10 @@
         "language": {
           "type": "string",
           "minLength": 1
+        },
+        "product": {
+          "type": "string",
+          "minLength": 1
         }
       }
     },
@@ -487,5 +494,36 @@
         }
       ]
     }
-  }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "schemaVersion": {
+            "const": 1
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "publication": {
+            "not": {
+              "required": [
+                "product"
+              ]
+            }
+          }
+        }
+      },
+      "else": {
+        "properties": {
+          "publication": {
+            "required": [
+              "product"
+            ]
+          }
+        }
+      }
+    }
+  ]
 }