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

package/agent-docs/start.md

@@ -36,7 +36,7 @@ Install an exact version of the alpha and initialize the minimal starter:
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.19
 npx --no-install shoalrun init .
 ```
 

package/agent-docs/start.sections/start-your-own-project.md

@@ -38,7 +38,7 @@ Install an exact version of the alpha and initialize the minimal starter:
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.19
 npx --no-install shoalrun init .
 ```
 

package/assets/ask-widget.js

@@ -252,7 +252,7 @@
   });
   const checkVisitor = async () => {
     const turnstile = await loadTurnstile();
-    if (widget === undefined) widget = turnstile.render(challengeBox, { sitekey: hosted.siteKey, appearance: 'interaction-only', execution: 'execute', callback: token => waiter?.resolve(token), 'error-callback': () => waiter?.reject(new Error('The check did not pass.')) });
+    if (widget === undefined) widget = turnstile.render(challengeBox, { sitekey: hosted.siteKey, ...(hosted.action ? { action: hosted.action } : {}), appearance: 'interaction-only', execution: 'execute', callback: token => waiter?.resolve(token), 'error-callback': () => waiter?.reject(new Error('The check did not pass.')) });
     else turnstile.reset(widget);
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => reject(new Error('The check timed out.')), 30000);

package/dist/ask-function.js

@@ -14,6 +14,7 @@ import { createSession, turnstileVerifier } from './turnstile.js';
 import { envRedis } from './budget-store.js';
 import { pausedKey } from './chat-pause.js';
 import { deleteKvLogRecord, kvLogSink } from './ask-log-kv.js';
+import { turnstileHostnames } from './turnstile-policy.js';
 // The answer function for a hosted site. The build writes a directory holding `runtime.json` (the chat and retrieval settings, with no
 // keys) and `site/ai` (the passages and vectors), and this module turns that directory into a Web `Request` to `Response` function. Keys come
 // only from the environment variables the settings name. It refuses to start without a shared budget store, because per-instance counters
@@ -39,8 +40,10 @@ export async function createAskFunction(directory, env = process.env, send) {
     if (chat.challenge) {
         const secret = env[chat.challenge.secretEnv];
         if (secret) {
-            session = createSession({ secret });
-            const verify = turnstileVerifier({ secret, ...(send ? { fetch: send } : {}) });
+            const allowedHostnames = turnstileHostnames(chat.challenge.hostnames ?? hosts.map(host => new URL(`https://${host}`).hostname), 'Turnstile allowedHostnames');
+            const context = JSON.stringify({ version: 1, hostnames: [...allowedHostnames].sort(), action: chat.challenge.action ?? null });
+            session = createSession({ secret, context });
+            const verify = turnstileVerifier({ secret, allowedHostnames, ...(chat.challenge.action ? { action: chat.challenge.action } : {}), ...(send ? { fetch: send } : {}) });
             challenge = ({ token, ip }) => verify({ token, ip });
         }
         else {

package/dist/chat-config.d.ts

@@ -31,6 +31,8 @@ export type ChatChallenge = {
     provider: 'turnstile';
     siteKey: string;
     secretEnv: string;
+    hostnames?: string[];
+    action?: string;
     when: 'adaptive' | 'always';
     freeQuestions: number;
     busyShare: number;

package/dist/chat-config.js

@@ -1,5 +1,6 @@
 import { reservedBodyFields } from './chat.js';
 import { validateReaderSelection } from './reader-filters.js';
+import { turnstileHostnames } from './turnstile-policy.js';
 export const escalateReasons = ['unsupported-claim', 'unsupported-code', 'uncited'];
 export const defaultLogNotice = 'Questions are recorded, with personal details removed, to improve these docs.';
 const mapping = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
@@ -305,9 +306,9 @@ export function validateChat(value, readerFilters) {
         if (!mapping(challenge))
             throw new Error('chat.challenge must be a mapping with provider, siteKey, and secretEnv');
         for (const key of Object.keys(challenge)) {
-            if (['provider', 'siteKey', 'secretEnv', 'when', 'freeQuestions', 'busyShare'].includes(key))
+            if (['provider', 'siteKey', 'secretEnv', 'hostnames', 'action', 'when', 'freeQuestions', 'busyShare'].includes(key))
                 continue;
-            throw new Error(/key|secret|token|password/i.test(key) ? `chat.challenge.${key} is not a setting. The config never holds a secret; name the environment variable that does with secretEnv` : `chat.challenge has an unknown setting ${key}; it accepts provider, siteKey, secretEnv, when, freeQuestions, and busyShare`);
+            throw new Error(/key|secret|token|password/i.test(key) ? `chat.challenge.${key} is not a setting. The config never holds a secret; name the environment variable that does with secretEnv` : `chat.challenge has an unknown setting ${key}; it accepts provider, siteKey, secretEnv, hostnames, action, when, freeQuestions, and busyShare`);
         }
         if (challenge.provider !== 'turnstile')
             throw new Error('chat.challenge.provider must be turnstile');
@@ -322,6 +323,13 @@ export function validateChat(value, readerFilters) {
         if (challenge.busyShare !== undefined && (typeof challenge.busyShare !== 'number' || !(challenge.busyShare > 0 && challenge.busyShare <= 1)))
             throw new Error('chat.challenge.busyShare must be a number above 0 and at most 1');
         result.challenge = { provider: 'turnstile', siteKey, secretEnv, when: challenge.when ?? 'adaptive', freeQuestions: challenge.freeQuestions === undefined ? 3 : integer(challenge.freeQuestions, 'chat.challenge.freeQuestions', 0, 1000), busyShare: challenge.busyShare ?? 0.5 };
+        if (challenge.hostnames !== undefined)
+            result.challenge.hostnames = turnstileHostnames(challenge.hostnames, 'chat.challenge.hostnames');
+        if (challenge.action !== undefined) {
+            if (typeof challenge.action !== 'string' || !/^[A-Za-z0-9_-]{1,32}$/.test(challenge.action))
+                throw new Error('chat.challenge.action must contain 1 to 32 letters, numbers, underscores, or hyphens');
+            result.challenge.action = challenge.action;
+        }
     }
     if (value.budget !== undefined) {
         if (!mapping(value.budget))

package/dist/cli.js

@@ -40,7 +40,7 @@ import { buildChunkIndex, embeddingInput } from './index-build.js';
 import { createProvider, embedChunkIndex, readEmbeddings } from './embeddings.js';
 import { embeddingProviderConfig, queryProviderConfig, validateRetrieval } from './retrieval-config.js';
 import { defaultLogNotice, validateChat } from './chat-config.js';
-import { createSession, turnstileVerifier } from './turnstile.js';
+import { createSession, turnstilePreviewVerifier } from './turnstile.js';
 import { adaptiveChallenge } from './budget.js';
 import { validateReaderFilters } from './reader-filters.js';
 import { askQuestion } from './ask.js';
@@ -269,7 +269,7 @@ try {
             if (publicPreview) {
                 chatConfigForPreview = chatConfig;
                 publicSettings = { siteKey: '1x00000000000000000000AA', ...(chatConfig?.challenge?.when === 'always' ? { prewarm: true } : {}), notice: chatConfig?.log?.notice ?? defaultLogNotice, ...(chatConfig?.panel ? { panel: chatConfig.panel } : {}) };
-                const verify = turnstileVerifier({ secret: '1x0000000000000000000000000000000AA' });
+                const verify = turnstilePreviewVerifier();
                 challenge = ({ token, ip }) => verify({ token, ip });
             }
             const handler = createAskHandler({ hosts, exposeErrors: true, ...(publicPreview ? { response: 'public', challenge, session: createSession({ secret: '1x0000000000000000000000000000000AA' }), ...(chatConfigForPreview?.challenge?.when === 'always' || !setup.budget ? {} : { challengeNeeded: adaptiveChallenge(setup.budget, { freeQuestions: chatConfigForPreview?.challenge?.freeQuestions, busyShare: chatConfigForPreview?.challenge?.busyShare }) }) } : {}), ...(log ? { record: event => log.write(event) } : {}), ...(setup.budget ? { budget: setup.budget } : {}), answer: (question, history, context) => askQuestion({ question, history, ...setup.options, modelAllowed: context.modelAllowed, signal: context.signal, ...(publicPreview ? { requireCitations: true } : {}) }) });

package/dist/turnstile-policy.d.ts

@@ -0,0 +1,2 @@
+export declare function turnstileHostname(value: unknown): string | undefined;
+export declare function turnstileHostnames(value: unknown, setting: string): string[];

package/dist/turnstile-policy.js

@@ -0,0 +1,23 @@
+// Canonical, exact hostnames only: no wildcard, URL, credentials, or port.
+export function turnstileHostname(value) {
+    if (typeof value !== 'string' || !value || value.length > 253 || /[\s*]/.test(value))
+        return;
+    const hostname = value.toLowerCase().replace(/\.$/, '');
+    try {
+        const url = new URL(`https://${hostname}`);
+        if (url.host !== hostname || url.pathname !== '/' || url.search || url.hash || url.username || url.password)
+            return;
+        return hostname;
+    }
+    catch {
+        return;
+    }
+}
+export function turnstileHostnames(value, setting) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > 100)
+        throw new Error(`${setting} must be a nonempty list of at most 100 exact hostnames`);
+    const names = value.map(turnstileHostname);
+    if (names.some(name => name === undefined))
+        throw new Error(`${setting} must contain exact hostnames without wildcards, URLs, or ports`);
+    return [...new Set(names)];
+}

package/dist/turnstile.d.ts

@@ -1,15 +1,22 @@
 export type TurnstileOptions = {
     secret: string;
+    allowedHostnames: readonly string[];
+    action?: string;
     timeoutMs?: number;
     fetch?: typeof fetch;
 };
 export declare const turnstileVerifyUrl = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+export declare function turnstilePreviewVerifier(options?: Pick<TurnstileOptions, 'fetch' | 'timeoutMs'>): (input: {
+    token?: string;
+    ip?: string;
+}) => Promise<boolean>;
 export declare function turnstileVerifier(options: TurnstileOptions): (input: {
     token?: string;
     ip?: string;
 }) => Promise<boolean>;
 export type SessionOptions = {
     secret: string;
+    context?: string;
     maxAgeSeconds?: number;
     now?: () => number;
 };

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,7 +83,7 @@ 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;

package/package.json

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

package/skills/shoalrun-brand/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: shoalrun-brand
+description: Apply a visual brand to a Shoalrun documentation site or local demo using theme settings, fonts, logos, and scoped CSS. Use for matching a supplied website or brand guide, or refining an existing site's visual identity.
+---
+
+# Brand a documentation site
+
+Inspect the target project's configuration, styles, assets, installed package version, and applicable project instructions. Preserve documentation, routes, navigation, publication selection, and existing edits. For a separate demo, copy source into a new directory and keep its build output separate. Visual branding doesn't establish product facts; retain sample-content labels and don't invent product capabilities or release histories.
+
+## Establish the brand
+
+Use the supplied website, assets, or brand guide as evidence. Inspect the rendered reference when browser access is available; stylesheets and font declarations can identify exact values. Record the relevant source URLs or file paths with the project, along with colors, font roles and weights, logo variants, spacing, shapes, and intended color modes. Distinguish observed values from approximations. If the reference is unavailable, work from supplied evidence and identify what couldn't be verified.
+
+Keep brand-specific values and assets in the customer project. Use available logo and font files with suitable usage rights; preserve notices. Don't copy a reference site's tracking scripts or application bundle into the documentation site.
+
+Before editing an existing project, capture a baseline with `shoalrun docs baseline --config docs.config.yaml --out .shoalrun/brand-before.json`. For a customer edition, use the same explicit `--profile FILE` throughout baseline, validation, build, and preview. Read the installed edition guidance before changing profile-owned branding.
+
+## Apply supported configuration first
+
+Use the installed CLI's bundled references before choosing unfamiliar keys:
+
+```sh
+shoalrun docs read reference.config-site
+shoalrun docs read guide.themes
+shoalrun docs read guide.palettes
+shoalrun docs read guide.css
+```
+
+Set site identity, logo, favicon, and header links through supported `site` settings. Choose the closest `theme.preset`; use `theme.palette` for checked color pairs, `theme.mode` for the requested color behavior, and `theme.fonts` for local body, heading, and code fonts. Declare static font weights accurately and retain fallback families. Keep source and asset paths relative to the configuration that declares them.
+
+Use `site.customCss` for remaining visual changes. Prefer documented tokens for broad adjustments and verified generated selectors for specific regions. Project CSS loads after generated styles. Relative CSS images and imports aren't copied automatically; use the documented asset mechanism or site-root URLs for assets that are actually served.
+
+## Keep each surface readable
+
+A dark header can contain light inputs and result panels. Scope foreground and background tokens together for each surface; don't let header text colors leak into inputs, option lists, buttons, or search results. Inspect actual markup and computed styles before choosing selectors. Search selection can be expressed on a result's parent element rather than its link.
+
+Check these states where present:
+
+- Header links and buttons: normal, hover, focus, and active.
+- Search: typed text, placeholder, shortcut key, results, summaries, matched terms, empty state, hover, and keyboard selection.
+- Publication and product selectors: label, selected value, open options, and focus ring.
+- Navigation, cards, callouts, tables, and code: text, fills, borders, and links.
+
+Check every requested color mode. Normal text needs at least 4.5:1 contrast; large text needs 3:1. Required control boundaries and state indicators need 3:1 against adjacent colors. Keep keyboard focus visible. The compiler checks configured palette pairs, but custom CSS and inherited interaction states need separate verification.
+
+## Validate and preview
+
+Validate against the baseline with `shoalrun docs validate --baseline .shoalrun/brand-before.json --config docs.config.yaml`, including the selected profile when applicable. Read the report's findings and coverage. Reuse its captured output with `shoalrun docs preview REPORT --port 0`, or follow the project's required build workflow and serve that output. Rebuild when styles, configuration, or assets change.
+
+Inspect a landing page and a representative article at desktop and mobile widths. Check font and image loading, overflow, keyboard navigation, dropdown destinations, and search interactions. Confirm HTML navigation and Markdown twins retain the documentation's meaning. A successful build doesn't establish visual correctness; state any browser checks that couldn't run.
+
+Present the preview URL, changed files, verified states, and unresolved approximations. Keep the review concise and link to detailed evidence when needed. Follow the user's authorization for commits and publication.