@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.12

package/example-configs/notifications/content/welcome-email.mdx

@@ -0,0 +1,82 @@
+---
+id: recipe.send-welcome-email
+title: Send a welcome email and confirm delivery
+summary: Follow one message from an accepted request through delivery, and
+  inspect a simulated failure.
+type: recipe
+slug: /recipes/send-welcome-email
+channel: production
+version: current
+language: en
+operations:
+  - notifications.send-email
+  - notifications.get-message
+access:
+  policy: public
+---
+
+Follow one message from an accepted request through delivery, and inspect a simulated failure.
+
+## Before you start
+
+- `API_BASE`: Set `export API_BASE=http://127.0.0.1:8787/v1` in your command terminal.
+- From the Shoalrun repository root, run `node framework/example-configs/notifications/demo.mjs` in a separate terminal and keep it running. If it is already running, reuse it.
+- Use a scratch directory for queued.json and delivery.json. These commands replace those files.
+- Have cURL and Node.js available in your command terminal.
+
+## Queue the welcome email
+
+- Use `API_BASE` from **Before you start**: The demo API base URL set in your terminal.
+
+Send the `welcome` template to the demo recipient. The demo stores a simulated message and sends no email.
+
+```sh
+curl --fail-with-body --silent --show-error \
+  --request POST "$API_BASE/messages/email" \
+  --header 'Content-Type: application/json' \
+  --data '{"to":"reader@example.com","template":"welcome","variables":{"firstName":"Avery"}}' \
+  --output queued.json --write-out 'HTTP %{http_code}\n'
+cat queued.json
+MESSAGE_ID=$(node -p "JSON.parse(require('fs').readFileSync('queued.json', 'utf8')).id")
+printf '\nMessage ID: %s\n' "$MESSAGE_ID"
+```
+
+A successful response looks like `{"id":"msg_…","status":"queued"}`. If the POST fails, inspect its HTTP status and response before continuing. Do not reuse a message ID from an earlier attempt.
+
+Save `MESSAGE_ID`: The id returned in queued.json; use this exact value for the delivery check.
+
+**Continue when:** The POST returns HTTP 202, status is queued, and MESSAGE_ID is nonempty. This confirms acceptance only.
+
+## Check delivery for that message
+
+- Use `API_BASE` from **Before you start**: Use the same environment as the queue request.
+- Use `MESSAGE_ID` from **Queue the welcome email**: Put the returned ID into the status URL; do not substitute the example ID.
+
+Look up the message using the ID saved in the previous step:
+
+```sh
+curl --fail-with-body --silent --show-error \
+  "$API_BASE/messages/$MESSAGE_ID" \
+  --output delivery.json --write-out 'HTTP %{http_code}\n'
+cat delivery.json
+```
+
+The local demo returns `queued` on the first lookup. Run the lookup once more to see its terminal status. This deterministic transition is part of the simulation; a real provider needs its own polling interval and timeout.
+
+| Status or error | What to do next |
+| --- | --- |
+| `queued` | The request was accepted; delivery is still pending. In this demo, repeat the lookup once. |
+| `delivered` | Check that `id` matches `MESSAGE_ID`. The delivery check is complete. |
+| `failed` | Inspect `failureReason`. Correct the cause before creating another message; do not keep polling a terminal failure. |
+| HTTP 404 | Check the saved ID and API base URL. Restarting the demo clears its messages. |
+| Connection refused | Start the demo and check that it is listening on port 8787. |
+
+To exercise failure handling, repeat the queue step with `blocked@example.com`, save its new message ID, and check that ID twice. The demo returns `failed` with `failureReason: recipient_rejected`.
+
+Save `deliveryStatus`: The status returned for MESSAGE_ID in delivery.json.
+
+**Continue when:** The response id equals MESSAGE_ID and status is delivered. Queued and failed do not satisfy this recipe's goal.
+
+## Check the outcome
+
+The final response contains the same message ID you saved and `status: delivered`. You have verified the simulated delivery flow. The local demo sends no email; a real provider reporting delivery still does not prove the recipient read it.

package/example-configs/notifications/demo.mjs

@@ -0,0 +1,43 @@
+import { createServer } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+
+// A local teaching fixture. It never contacts a notification provider or sends mail.
+export function createNotificationDemo() {
+  const messages = new Map();
+  return createServer(async (request, response) => {
+    const send = (code, value) => { response.writeHead(code, { 'content-type': 'application/json' }); response.end(JSON.stringify(value)); };
+    const url = new URL(request.url, 'http://localhost');
+    if (request.method === 'POST' && url.pathname === '/v1/messages/email') {
+      let body = '';
+      try {
+        for await (const chunk of request) {
+          body += chunk;
+          if (body.length > 16384) { send(413, { error: 'Request too large' }); return; }
+        }
+        const value = JSON.parse(body);
+        if (typeof value.to !== 'string' || !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(value.to) || value.template !== 'welcome') {
+          send(400, { error: 'Use an email address and the welcome template' }); return;
+        }
+        const id = `msg_${randomUUID()}`;
+        messages.set(id, { reads: 0, failed: value.to === 'blocked@example.com' });
+        send(202, { id, status: 'queued' });
+      } catch { send(400, { error: 'Expected a JSON request body' }); }
+      return;
+    }
+    if (request.method === 'GET' && url.pathname.startsWith('/v1/messages/')) {
+      const id = url.pathname.slice('/v1/messages/'.length);
+      const message = messages.get(id);
+      if (!message) { send(404, { error: 'Message not found' }); return; }
+      const status = message.reads++ === 0 ? 'queued' : message.failed ? 'failed' : 'delivered';
+      send(200, { id, status, ...(status === 'failed' ? { failureReason: 'recipient_rejected' } : {}) });
+      return;
+    }
+    send(404, { error: 'Route not found' });
+  });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const server = createNotificationDemo();
+  server.listen(8787, '127.0.0.1', () => console.log('Notification demo: http://127.0.0.1:8787/v1 (simulated delivery; no mail is sent)'));
+}

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

@@ -0,0 +1,88 @@
+schemaVersion: 1
+
+site:
+  title: Notifications API
+  origin: https://docs.example.com
+
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current }
+
+frontmatter:
+  defaults:
+    type: guide
+    channel: production
+    version: current
+    access: { policy: public }
+
+apis:
+  notifications:
+    publicReview:
+      digest: 16837b2b5d0d4aa28c30368e3ff2fefd0d8a62a5dda50a9a4379839778942599
+    source: { kind: file, path: ./apis/notifications.yaml }
+    operations:
+      - id: notifications.send-email
+        sourceOperationId: sendEmail
+        reference: reference.send-email
+      - id: notifications.send-push
+        sourceOperationId: sendPush
+        reference: reference.send-push
+      - id: notifications.send-sms
+        sourceOperationId: sendSms
+        reference: reference.send-sms
+
+      - id: notifications.get-message
+        sourceOperationId: getMessage
+        reference: reference.get-message
+
+cookbooks:
+  welcome-email:
+    title: What do you need to confirm?
+    mode: single
+    options:
+      - id: accepted
+        label: Confirm the request was accepted
+        doc: recipe.queue-email
+        when: You are testing the request payload and only need an acceptance check.
+        needs: A running local demo, cURL, and Node.js.
+        outcome: A queued response and a message ID. Delivery is still unknown.
+      - id: delivered
+        label: Follow the email through delivery
+        doc: recipe.send-welcome-email
+        when: You need to distinguish acceptance, delivery, and a delivery failure.
+        needs: A running local demo, cURL, and Node.js.
+        outcome: A delivery status tied to the message you queued, with a failure check.
+  notify-users:
+    title: Choose notification channels
+    options:
+      - { id: email, label: Email, doc: recipe.queue-email }
+      - { id: push, label: Push, doc: recipe.queue-push }
+      - { id: sms, label: SMS, doc: recipe.queue-sms }
+
+navigation:
+  - id: start
+    doc: guide.notifications-start
+  - id: api
+    doc: reference.send-email
+  - id: push-api
+    doc: reference.send-push
+  - id: sms-api
+    doc: reference.send-sms
+  - id: cookbook
+    label: Cookbook
+    items:
+      - { id: notify-users, doc: cookbook.notify-users }
+      - { id: queue-email, doc: recipe.queue-email }
+      - { id: queue-push, doc: recipe.queue-push }
+      - { id: queue-sms, doc: recipe.queue-sms }
+  - id: delivery-api
+    doc: reference.get-message
+  - id: welcome-cookbook
+    doc: cookbook.welcome-email
+  - id: welcome-recipe
+    doc: recipe.send-welcome-email

package/example-configs/notifications/ingredient-drafts/README.md

@@ -0,0 +1,41 @@
+# Notification ingredient and recipe drafts
+
+`queue-welcome-email.mdx` is a generated API ingredient draft. Its source is
+`../ingredient-specs/queue-welcome-email.yaml` plus the configured
+`notifications.send-email` OpenAPI operation. It copies the example request
+and queued response; it does not send an email or prove delivery.
+
+The authored ingredients under `../ingredients/` declare their inputs, outputs,
+shared prerequisites, and continuation checks in `workflow` frontmatter.
+`../recipe-specs/send-welcome-email.yaml` combines them into the generated
+`../recipe-drafts/send-welcome-email.mdx`. The published example is
+`../content/welcome-email.mdx`, with the draft notice and review checklist removed.
+
+Run `node framework/example-configs/notifications/demo.mjs` from the repository
+root for a local simulation. It sends no mail. The first status lookup returns
+queued; the next returns delivered, or failed for `blocked@example.com`.
+The welcome-email cookbook offers an acceptance-only path and a complete
+delivery path. Both are covered by an integration test using the published
+shell commands.
+
+From the repository root, build the CLI and compare the drafts with their
+inputs:
+
+```sh
+npm --prefix framework run build
+node framework/dist/cli.js ingredient draft \
+  --config framework/example-configs/notifications/docs.config.yaml \
+  --spec framework/example-configs/notifications/ingredient-specs/queue-welcome-email.yaml \
+  --out framework/example-configs/notifications/ingredient-drafts/queue-welcome-email.mdx \
+  --check
+node framework/dist/cli.js recipe draft \
+  --config framework/example-configs/notifications/docs.config.yaml \
+  --spec framework/example-configs/notifications/recipe-specs/send-welcome-email.yaml \
+  --out framework/example-configs/notifications/recipe-drafts/send-welcome-email.mdx \
+  --check
+```
+
+`--check` reports `unchanged`, `would-create`, or `would-change` and prints the
+proposed content. Without `--check`, each command creates a new file and
+refuses to overwrite an existing one. A custodian reviews and tests the whole
+workflow before publishing a recipe.

package/example-configs/notifications/ingredient-drafts/check-delivery.mdx

@@ -0,0 +1,13 @@
+---
+id: ingredient.check-delivery
+title: Check message delivery
+summary: Confirm that the welcome email reached its recipient.
+type: ingredient
+slug: /ingredients/check-delivery
+channel: production
+version: current
+language: en
+access: { policy: draft }
+---
+
+[[TODO: Identify the delivery status source and the exact value that means the welcome email was delivered. The API example only shows `queued`.]]

package/example-configs/notifications/ingredient-drafts/queue-welcome-email.mdx

@@ -0,0 +1,48 @@
+---
+id: ingredient.queue-welcome-email
+title: Queue a welcome email
+summary: Send the welcome email request and inspect the queued response.
+type: ingredient
+slug: /ingredients/queue-welcome-email
+channel: production
+version: current
+language: en
+operations:
+  - notifications.send-email
+access:
+  policy: draft
+---
+
+> Generated draft from `apis/notifications.yaml` (21c6fb6cfeb5). Review every instruction before publishing.
+
+Send the welcome email request and inspect the queued response.
+
+## Before you start
+
+[[TODO: State the credentials, tools, and setup needed to run this request. The OpenAPI example does not prove they work.]]
+
+## Send the request
+
+The following cURL command comes from the `welcome` request example for [POST /messages/email](doc:reference.send-email). Check its host, authentication, and values before using it.
+
+```sh
+curl --request POST \
+  --url 'https://api.example.com/v1/messages/email' \
+  --header 'Content-Type: application/json' \
+  --data-raw '{"to":"reader@example.com","template":"welcome","variables":{"firstName":"Avery"}}'
+```
+
+## Expected response
+
+The OpenAPI source gives this example for HTTP 202. It is an example, not a verified live result.
+
+```json
+{
+  "id": "msg_123",
+  "status": "queued"
+}
+```
+
+## Check it worked
+
+[[TODO: Give a concrete check against a real environment, including the value that means success and what to inspect if it fails.]]

package/example-configs/notifications/ingredient-specs/queue-welcome-email.yaml

@@ -0,0 +1,7 @@
+schemaVersion: 1
+id: ingredient.queue-welcome-email
+title: Queue a welcome email
+summary: Send the welcome email request and inspect the queued response.
+slug: /ingredients/queue-welcome-email
+operation: notifications.send-email
+requestExample: welcome

package/example-configs/notifications/ingredients/check-delivery.mdx

@@ -0,0 +1,42 @@
+---
+id: ingredient.check-delivery
+title: Check delivery for that message
+summary: Read the status for the message you just queued and handle pending or failed delivery.
+type: ingredient
+slug: /ingredients/check-delivery
+channel: production
+version: current
+language: en
+operations: [notifications.get-message]
+access: { policy: draft }
+workflow:
+  inputs:
+    API_BASE: Use the same environment as the queue request.
+    MESSAGE_ID: Put the returned ID into the status URL; do not substitute the example ID.
+  outputs:
+    deliveryStatus: The status returned for MESSAGE_ID in delivery.json.
+  prerequisites:
+    - Have cURL and Node.js available in your command terminal.
+  check: The response id equals MESSAGE_ID and status is delivered. Queued and failed do not satisfy this recipe's goal.
+---
+
+Look up the message using the ID saved in the previous step:
+
+```sh
+curl --fail-with-body --silent --show-error \
+  "$API_BASE/messages/$MESSAGE_ID" \
+  --output delivery.json --write-out 'HTTP %{http_code}\n'
+cat delivery.json
+```
+
+The local demo returns `queued` on the first lookup. Run the lookup once more to see its terminal status. This deterministic transition is part of the simulation; a real provider needs its own polling interval and timeout.
+
+| Status or error | What to do next |
+| --- | --- |
+| `queued` | The request was accepted; delivery is still pending. In this demo, repeat the lookup once. |
+| `delivered` | Check that `id` matches `MESSAGE_ID`. The delivery check is complete. |
+| `failed` | Inspect `failureReason`. Correct the cause before creating another message; do not keep polling a terminal failure. |
+| HTTP 404 | Check the saved ID and API base URL. Restarting the demo clears its messages. |
+| Connection refused | Start the demo and check that it is listening on port 8787. |
+
+To exercise failure handling, repeat the queue step with `blocked@example.com`, save its new message ID, and check that ID twice. The demo returns `failed` with `failureReason: recipient_rejected`.

package/example-configs/notifications/ingredients/queue-welcome-email.mdx

@@ -0,0 +1,37 @@
+---
+id: ingredient.queue-welcome-email
+title: Queue the welcome email
+summary: Submit the welcome template and save the returned message ID.
+type: ingredient
+slug: /ingredients/queue-welcome-email
+channel: production
+version: current
+language: en
+operations: [notifications.send-email]
+access: { policy: draft }
+workflow:
+  inputs:
+    API_BASE: The demo API base URL set in your terminal.
+  outputs:
+    MESSAGE_ID: The id returned in queued.json; use this exact value for the delivery check.
+  prerequisites:
+    - From the Shoalrun repository root, run `node framework/example-configs/notifications/demo.mjs` in a separate terminal and keep it running. If it is already running, reuse it.
+    - Use a scratch directory for queued.json and delivery.json. These commands replace those files.
+    - Have cURL and Node.js available in your command terminal.
+  check: The POST returns HTTP 202, status is queued, and MESSAGE_ID is nonempty. This confirms acceptance only.
+---
+
+Send the `welcome` template to the demo recipient. The demo stores a simulated message and sends no email.
+
+```sh
+curl --fail-with-body --silent --show-error \
+  --request POST "$API_BASE/messages/email" \
+  --header 'Content-Type: application/json' \
+  --data '{"to":"reader@example.com","template":"welcome","variables":{"firstName":"Avery"}}' \
+  --output queued.json --write-out 'HTTP %{http_code}\n'
+cat queued.json
+MESSAGE_ID=$(node -p "JSON.parse(require('fs').readFileSync('queued.json', 'utf8')).id")
+printf '\nMessage ID: %s\n' "$MESSAGE_ID"
+```
+
+A successful response looks like `{"id":"msg_…","status":"queued"}`. If the POST fails, inspect its HTTP status and response before continuing. Do not reuse a message ID from an earlier attempt.

package/example-configs/notifications/recipe-drafts/send-welcome-email.mdx

@@ -0,0 +1,91 @@
+---
+id: recipe.send-welcome-email
+title: Send a welcome email and confirm delivery
+summary: Follow one message from an accepted request through delivery, and
+  inspect a simulated failure.
+type: recipe
+slug: /recipes/send-welcome-email
+channel: production
+version: current
+language: en
+operations:
+  - notifications.send-email
+  - notifications.get-message
+access:
+  policy: draft
+---
+
+> Assembled draft from 2 configured ingredients (4b735f4352c4). Review the complete workflow before publishing.
+
+Follow one message from an accepted request through delivery, and inspect a simulated failure.
+
+## Before you start
+
+- `API_BASE`: Set `export API_BASE=http://127.0.0.1:8787/v1` in your command terminal.
+- From the Shoalrun repository root, run `node framework/example-configs/notifications/demo.mjs` in a separate terminal and keep it running. If it is already running, reuse it.
+- Use a scratch directory for queued.json and delivery.json. These commands replace those files.
+- Have cURL and Node.js available in your command terminal.
+
+## Queue the welcome email
+
+- Use `API_BASE` from **Before you start**: The demo API base URL set in your terminal.
+
+Send the `welcome` template to the demo recipient. The demo stores a simulated message and sends no email.
+
+```sh
+curl --fail-with-body --silent --show-error \
+  --request POST "$API_BASE/messages/email" \
+  --header 'Content-Type: application/json' \
+  --data '{"to":"reader@example.com","template":"welcome","variables":{"firstName":"Avery"}}' \
+  --output queued.json --write-out 'HTTP %{http_code}\n'
+cat queued.json
+MESSAGE_ID=$(node -p "JSON.parse(require('fs').readFileSync('queued.json', 'utf8')).id")
+printf '\nMessage ID: %s\n' "$MESSAGE_ID"
+```
+
+A successful response looks like `{"id":"msg_…","status":"queued"}`. If the POST fails, inspect its HTTP status and response before continuing. Do not reuse a message ID from an earlier attempt.
+
+Save `MESSAGE_ID`: The id returned in queued.json; use this exact value for the delivery check.
+
+**Continue when:** The POST returns HTTP 202, status is queued, and MESSAGE_ID is nonempty. This confirms acceptance only.
+
+## Check delivery for that message
+
+- Use `API_BASE` from **Before you start**: Use the same environment as the queue request.
+- Use `MESSAGE_ID` from **Queue the welcome email**: Put the returned ID into the status URL; do not substitute the example ID.
+
+Look up the message using the ID saved in the previous step:
+
+```sh
+curl --fail-with-body --silent --show-error \
+  "$API_BASE/messages/$MESSAGE_ID" \
+  --output delivery.json --write-out 'HTTP %{http_code}\n'
+cat delivery.json
+```
+
+The local demo returns `queued` on the first lookup. Run the lookup once more to see its terminal status. This deterministic transition is part of the simulation; a real provider needs its own polling interval and timeout.
+
+| Status or error | What to do next |
+| --- | --- |
+| `queued` | The request was accepted; delivery is still pending. In this demo, repeat the lookup once. |
+| `delivered` | Check that `id` matches `MESSAGE_ID`. The delivery check is complete. |
+| `failed` | Inspect `failureReason`. Correct the cause before creating another message; do not keep polling a terminal failure. |
+| HTTP 404 | Check the saved ID and API base URL. Restarting the demo clears its messages. |
+| Connection refused | Start the demo and check that it is listening on port 8787. |
+
+To exercise failure handling, repeat the queue step with `blocked@example.com`, save its new message ID, and check that ID twice. The demo returns `failed` with `failureReason: recipient_rejected`.
+
+Save `deliveryStatus`: The status returned for MESSAGE_ID in delivery.json.
+
+**Continue when:** The response id equals MESSAGE_ID and status is delivered. Queued and failed do not satisfy this recipe's goal.
+
+## Check the outcome
+
+The final response contains the same message ID you saved and `status: delivered`. You have verified the simulated delivery flow. The local demo sends no email; a real provider reporting delivery still does not prove the recipient read it.
+
+## Review before publishing
+
+- Confirm ingredient order and that outputs from one step satisfy inputs to the next.
+- Test the complete workflow in a safe environment.
+- Replace TODOs and remove this review section.
+- Inspect both HTML and Markdown output.

package/example-configs/notifications/recipe-specs/send-welcome-email.yaml

@@ -0,0 +1,11 @@
+schemaVersion: 1
+id: recipe.send-welcome-email
+title: Send a welcome email and confirm delivery
+summary: Follow one message from an accepted request through delivery, and inspect a simulated failure.
+slug: /recipes/send-welcome-email
+inputs:
+  API_BASE: 'Set `export API_BASE=http://127.0.0.1:8787/v1` in your command terminal.'
+outcome: 'The final response contains the same message ID you saved and `status: delivered`. You have verified the simulated delivery flow. The local demo sends no email; a real provider reporting delivery still does not prove the recipient read it.'
+ingredients:
+  - ../ingredients/queue-welcome-email.mdx
+  - ../ingredients/check-delivery.mdx

package/example-configs/reference-stress/README.md

@@ -0,0 +1,32 @@
+# Cedar Parcel API reference stress project
+
+This is a wholly fictional API written for Shoalrun testing. Its names, hosts, descriptions, and payloads were authored as synthetic data. It is safe to keep in Git; it is not a transformed copy of a private vendor spec. The `.example` hosts do not provide an API.
+
+The project exercises:
+
+- four titled `oneOf` enrollment requests with shared nested objects and different required fields, including an exclusive lower bound, schema-level examples, and a boolean `true` schema;
+- a placeholder `parameters` query field mapped to direct filter expressions;
+- one `200` response that can be JSON, CSV, or a spreadsheet;
+- named examples, enums, nullable required response fields, and multipart binary uploads;
+- object property counts, unique array items, and decimal increments in the parcel-list response;
+- operation and path-level server/auth overrides, a deprecated operation, and an explicit `x-*` lifecycle mapping;
+- an OpenAPI 3.1 webhook and an authored MDX guide among generated operation links.
+
+`EnrollmentBase` is intentionally unused so a focused contract can prove it excludes unrelated components.
+
+From `framework/`, build and serve it:
+
+```sh
+npm run build
+node dist/cli.js build example-configs/reference-stress/docs.config.yaml /tmp/cedar-parcel-site
+DOCS_PREVIEW_ROOT=/tmp/cedar-parcel-site DOCS_PREVIEW_PORT=8768 node preview.mjs
+```
+
+Open `http://127.0.0.1:8768/`. To check the source and both rendered representations, run:
+
+```sh
+node dist/cli.js api audit example-configs/reference-stress/apis/cedar-parcel.yaml
+node dist/cli.js api focused-audit /tmp/cedar-parcel-site
+```
+
+The fixture uses `focused: true` and leaves the full OpenAPI download unpublished. If you edit its source or operation selection, run `shoalrun api review` and update `publicReview.digest` before the next build.