@bridgeline-digital/hawk-app-cli 0.1.0-dev.20261020202308 → 0.1.0

package/docs/showcase/README.md

@@ -1,47 +1,47 @@
-# Hawk Apps Showcase
-
-Every Hawk Apps feature in one app, one tab per feature, each call showing its outcome, timing and error code. It is
-built against this repo's bridge and CLI (npm workspace), so it always shows the current code, including unreleased
-changes, and CI builds it on every package change. It is not published to npm: copy from it, or start a new app with
-`npx hawk-app create`.
-
-Slug `showcase`, visibility `internal`: Bridgeline staff see it on every site, clients never do.
-
-| Tab | Shows | Scope |
-|---|---|---|
-| Context | the handshake context (client, user, engine, dates, theme) | — |
-| Analytics | `app.analytics.report` | `reports:read` |
-| Dashboard | `app.dashboard.get`, incl. the versioned-path rejection; a write test that creates a synonym marked `hawk-apps-showcase-…`, reads it back, deletes it and checks it's gone (404), plus a refused write to `Field` (403 `path_not_allowed`). Writes the current client's real HawkSearch data, so use a test client | `hawksearch:read`, `hawksearch:write` |
-| Search | `app.hawksearch.search` / `autocomplete`, live and preview | `hawksearch:search` |
-| Queries | `app.data.query`: an allowed table, a cached repeat, a sensitive table (needs the per-app opt-in in the analytics portal), a 5-query burst (concurrency limit + retry), error cases | `data:read` |
-| Functions | `app.functions.call`: `functions/showcase.ts` runs every capability step by step (zod validation, context, the `TEST_SECRET` secret, `ctx.platform` analytics + dashboard + query in parallel, Athena with `ctx.aws`, outbound `fetch`, CSV and gzip, then `ctx.platform.email.send` of a summary to the signed-in user); `functions/echo.ts`, a 7-call burst, a missing function | `functions:invoke`, `email:send` |
-| Jobs | `app.functions.start` / `wait` on `functions/long-task.ts` (a background job), progress, and the `daily-check` schedule | `functions:invoke` |
-| System parameters | `app.hawksearch.systemParameters`: list the declared ones, set one (empty clears it), and a refused undeclared one (404 `parameter_not_found`). Writes the current engine's real settings, so use a test engine | `hawksearch:sysparams:write` |
-| AI | `app.ai.stream` / `generate` on the `fast` and `smart` tiers, stop, usage and `app.ai.info()` | `ai:invoke` |
-| Host | toast, setTitle, navigate, auto-resize | — |
-
-## Running it
-
-From the repo root (one `npm install` covers the packages and this app):
-
-```bash
-npm install
-npm run build                          # the bridge, which this app imports
-npm run dev -w examples/showcase       # http://localhost:3100/showcase/ — open it in HawkSearch with ?devUrl=…
-```
-
-Deploying uses your own publisher key (`npx hawk-app login` once per machine), from this folder:
-
-```bash
-cd examples/showcase
-npx hawk-app validate
-npx hawk-app register                  # register the app / update its settings from hawk-app.json
-npx hawk-app deploy dist               # builds and deploys a new version (a draft; approvers make it live)
-```
-
-Before the Functions and Jobs tabs work: an admin enables functions for the app in the analytics portal, and
-`npx hawk-app secrets set TEST_SECRET` sets its secret (any value). `npx hawk-app logs echo --follow` shows a function's
-logs. Queries live in `queries/` (`searches-by-day` on an allowed table, `assistant-prompts-by-day` on a sensitive one).
-
-To try a published release instead of this repo's code, create an app with `npx hawk-app create` (which installs the
-packages from npm) rather than changing this one.
+# Hawk Apps Showcase
+
+Every Hawk Apps feature in one app, one tab per feature, each call showing its outcome, timing and error code. It is
+built against this repo's bridge and CLI (npm workspace), so it always shows the current code, including unreleased
+changes, and CI builds it on every package change. It is not published to npm: copy from it, or start a new app with
+`npx hawk-app create`.
+
+Slug `showcase`, visibility `internal`: Bridgeline staff see it on every site, clients never do.
+
+| Tab | Shows | Scope |
+|---|---|---|
+| Context | the handshake context (client, user, engine, dates, theme) | — |
+| Analytics | `app.analytics.report` | `reports:read` |
+| Dashboard | `app.dashboard.get`, incl. the versioned-path rejection; a write test that creates a synonym marked `hawk-apps-showcase-…`, reads it back, deletes it and checks it's gone (404), plus a refused write to `Field` (403 `path_not_allowed`). Writes the current client's real HawkSearch data, so use a test client | `hawksearch:read`, `hawksearch:write` |
+| Search | `app.hawksearch.search` / `autocomplete`, live and preview | `hawksearch:search` |
+| Queries | `app.data.query`: an allowed table, a cached repeat, a sensitive table (needs the per-app opt-in in the analytics portal), a 5-query burst (concurrency limit + retry), error cases | `data:read` |
+| Functions | `app.functions.call`: `functions/showcase.ts` runs every capability step by step (zod validation, context, the `TEST_SECRET` secret, `ctx.platform` analytics + dashboard + query in parallel, Athena with `ctx.aws`, outbound `fetch`, CSV and gzip, then `ctx.platform.email.send` of a summary to the signed-in user); `functions/echo.ts`, a 7-call burst, a missing function | `functions:invoke`, `email:send` |
+| Jobs | `app.functions.start` / `wait` on `functions/long-task.ts` (a background job), progress, and the `daily-check` schedule | `functions:invoke` |
+| System parameters | `app.hawksearch.systemParameters`: list the declared ones, set one (empty clears it), and a refused undeclared one (404 `parameter_not_found`). Writes the current engine's real settings, so use a test engine | `hawksearch:sysparams:write` |
+| AI | `app.ai.stream` / `generate` on the `fast` and `smart` tiers, stop, usage and `app.ai.info()` | `ai:invoke` |
+| Host | toast, setTitle, navigate, auto-resize | — |
+
+## Running it
+
+From the repo root (one `npm install` covers the packages and this app):
+
+```bash
+npm install
+npm run build                          # the bridge, which this app imports
+npm run dev -w examples/showcase       # http://localhost:3100/showcase/ — open it in HawkSearch with ?devUrl=…
+```
+
+Deploying uses your own publisher key (`npx hawk-app login` once per machine), from this folder:
+
+```bash
+cd examples/showcase
+npx hawk-app validate
+npx hawk-app register                  # register the app / update its settings from hawk-app.json
+npx hawk-app deploy dist               # builds and deploys a new version (a draft; approvers make it live)
+```
+
+Before the Functions and Jobs tabs work: an admin enables functions for the app in the analytics portal, and
+`npx hawk-app secrets set TEST_SECRET` sets its secret (any value). `npx hawk-app logs echo --follow` shows a function's
+logs. Queries live in `queries/` (`searches-by-day` on an allowed table, `assistant-prompts-by-day` on a sensitive one).
+
+To try a published release instead of this repo's code, create an app with `npx hawk-app create` (which installs the
+packages from npm) rather than changing this one.

package/docs/showcase/functions/echo.ts

@@ -1,12 +1,12 @@
-import type { HawkFunction } from '@bridgeline-digital/hawk-app-bridge/server';
-
-/** Echoes its input with what the function knows about the call: exercises ctx, secrets, config and ctx.platform. */
-export const handler: HawkFunction<unknown, Record<string, unknown>> = async (input, ctx) => ({
-    input,
-    client: ctx.client.id,
-    user: ctx.user.id,
-    version: ctx.version,
-    hasSecret: !!ctx.secrets.TEST_SECRET,
-    config: ctx.config,
-    searches: (await ctx.platform.analytics.report('searches', { limit: 5 })).data.length,
-});
+import type { HawkFunction } from '@bridgeline-digital/hawk-app-bridge/server';
+
+/** Echoes its input with what the function knows about the call: exercises ctx, secrets, config and ctx.platform. */
+export const handler: HawkFunction<unknown, Record<string, unknown>> = async (input, ctx) => ({
+    input,
+    client: ctx.client.id,
+    user: ctx.user.id,
+    version: ctx.version,
+    hasSecret: !!ctx.secrets.TEST_SECRET,
+    config: ctx.config,
+    searches: (await ctx.platform.analytics.report('searches', { limit: 5 })).data.length,
+});

package/docs/showcase/functions/long-task.ts

@@ -1,31 +1,31 @@
-import type { HawkFunction } from '@bridgeline-digital/hawk-app-bridge/server';
-
-const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
-
-/**
- * A background job (`"job": true`): counts through `steps` steps of `stepSeconds` each, reporting progress, then returns
- * what it knows about the run. Started from the Jobs tab, or by the `daily-check` schedule. `fail: true` throws at
- * the end, to test failed jobs.
- */
-export const handler: HawkFunction<{ steps?: number; stepSeconds?: number; fail?: boolean } | null, Record<string, unknown>> = async (input, ctx) => {
-    const steps = Math.min(Math.max(input?.steps ?? 10, 1), 60);
-    const stepSeconds = Math.min(Math.max(input?.stepSeconds ?? 3, 0), 30);
-    const started = Date.now();
-    for (let i = 1; i <= steps; i++) {
-        await sleep(stepSeconds * 1000);
-        await ctx.job?.progress(Math.round((100 * i) / steps), `Step ${i} of ${steps}`);
-    }
-    if (input?.fail) {
-        throw new Error('Failed on purpose (fail: true)');
-    }
-    return {
-        steps,
-        seconds: Math.round((Date.now() - started) / 1000),
-        job: ctx.job?.id ?? null,
-        trigger: ctx.trigger,
-        client: ctx.client.id,
-        user: ctx.user.id,
-        version: ctx.version,
-        searches: (await ctx.platform.analytics.report('searches', { limit: 5 })).data.length,
-    };
-};
+import type { HawkFunction } from '@bridgeline-digital/hawk-app-bridge/server';
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * A background job (`"job": true`): counts through `steps` steps of `stepSeconds` each, reporting progress, then returns
+ * what it knows about the run. Started from the Jobs tab, or by the `daily-check` schedule. `fail: true` throws at
+ * the end, to test failed jobs.
+ */
+export const handler: HawkFunction<{ steps?: number; stepSeconds?: number; fail?: boolean } | null, Record<string, unknown>> = async (input, ctx) => {
+    const steps = Math.min(Math.max(input?.steps ?? 10, 1), 60);
+    const stepSeconds = Math.min(Math.max(input?.stepSeconds ?? 3, 0), 30);
+    const started = Date.now();
+    for (let i = 1; i <= steps; i++) {
+        await sleep(stepSeconds * 1000);
+        await ctx.job?.progress(Math.round((100 * i) / steps), `Step ${i} of ${steps}`);
+    }
+    if (input?.fail) {
+        throw new Error('Failed on purpose (fail: true)');
+    }
+    return {
+        steps,
+        seconds: Math.round((Date.now() - started) / 1000),
+        job: ctx.job?.id ?? null,
+        trigger: ctx.trigger,
+        client: ctx.client.id,
+        user: ctx.user.id,
+        version: ctx.version,
+        searches: (await ctx.platform.analytics.report('searches', { limit: 5 })).data.length,
+    };
+};

package/docs/showcase/functions/showcase.ts

@@ -1,186 +1,186 @@
-import { AthenaClient, GetQueryExecutionCommand, GetQueryResultsCommand, StartQueryExecutionCommand } from '@aws-sdk/client-athena';
-import type { HawkFunction, HawkFunctionContext } from '@bridgeline-digital/hawk-app-bridge/server';
-import { createHash } from 'node:crypto';
-import { gzipSync } from 'node:zlib';
-import { z } from 'zod';
-
-/**
- * Showcase: everything a Hawk Apps function can do today, one step at a time. Each step reports ok/fail, timing and
- * a short summary, and a failing step never stops the others, so the result doubles as a health check of the
- * function runtime. Called from the Functions tab ("Run showcase").
- */
-
-// 1. npm packages are bundled with the function (zod here; the AWS SDK below).
-const Input = z.object({
-    from: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
-    to: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
-    url: z.string().url().default('https://api.github.com/zen'),
-    dashboardPath: z.string().default('Synonym'),
-});
-type Input = z.infer<typeof Input>;
-
-interface Step {
-    name: string;
-    ok: boolean;
-    ms: number;
-    summary: string;
-    detail?: unknown;
-}
-
-interface ShowcaseResult {
-    steps: Step[];
-    totalMs: number;
-    runtime: Record<string, unknown>;
-}
-
-async function step(name: string, run: () => Promise<{ summary: string; detail?: unknown }>): Promise<Step> {
-    const started = performance.now();
-    try {
-        const { summary, detail } = await run();
-        return { name, ok: true, ms: Math.round(performance.now() - started), summary, detail };
-    } catch (e) {
-        const error = e as { message?: string; code?: string; status?: number };
-        const code = error.code ? ` (${error.code}${error.status ? ` ${error.status}` : ''})` : '';
-        return { name, ok: false, ms: Math.round(performance.now() - started), summary: `${error.message ?? String(e)}${code}` };
-    }
-}
-
-export const handler: HawkFunction<unknown, ShowcaseResult> = async (raw, ctx) => {
-    const started = performance.now();
-    const steps: Step[] = [];
-
-    // Validate the input first: a bad input fails fast with a readable message (thrown errors become 502 function_failed).
-    const parsed = Input.safeParse(raw ?? {});
-    if (!parsed.success) {
-        throw new Error(`Invalid input: ${parsed.error.issues.map((i) => `${i.path.join('.') || 'input'} ${i.message}`).join('; ')}`);
-    }
-    const input = parsed.data;
-    steps.push({ name: 'Validate input (zod, an npm package)', ok: true, ms: 0, summary: `from ${input.from} to ${input.to}` });
-
-    // 2. Who is calling, for which client and version: ctx comes from the signed app token, never from the browser.
-    steps.push(await step('Context (who, which client, which version)', async () => ({
-        summary: `client ${ctx.client.id} · user ${ctx.user.id}${ctx.internal ? ' (Bridgeline)' : ''} · ${ctx.app.slug} v${ctx.version}`,
-        detail: { client: ctx.client, user: { id: ctx.user.id, roles: ctx.user.roles }, internal: ctx.internal, app: ctx.app, version: ctx.version, host: ctx.host },
-    })));
-
-    // 3. Secrets: only the ones declared in hawk-app.json, read by the platform at call time. Never return the value.
-    steps.push(await step('Secret (TEST_SECRET)', async () => {
-        const secret = ctx.secrets.TEST_SECRET;
-        if (!secret) throw new Error('TEST_SECRET is not set: npx hawk-app secrets set TEST_SECRET');
-        const fingerprint = createHash('sha256').update(secret).digest('hex').slice(0, 12);
-        return { summary: `${secret.length} characters · sha256 ${fingerprint}… (value not shown)` };
-    }));
-
-    // 4-6. The platform, as the current user (same scopes as the app), in parallel.
-    const [analytics, dashboard, query] = await Promise.all([
-        step('Analytics API (ctx.platform.analytics, reports:read)', async () => {
-            const report = await ctx.platform.analytics.report<{ search_count?: number | string }>('searches', { startDate: input.from, endDate: input.to, limit: 1000 });
-            const total = report.data.reduce((sum, row) => sum + Number(row.search_count ?? 0), 0);
-            return { summary: `${report.data.length} rows · ${total.toLocaleString()} searches`, detail: report.data.slice(0, 3) };
-        }),
-        step(`Dashboard API (ctx.platform.dashboard, hawksearch:read): ${input.dashboardPath}`, async () => {
-            const data = await ctx.platform.dashboard.get<unknown>(input.dashboardPath);
-            return { summary: Array.isArray(data) ? `${data.length} items` : 'object', detail: Array.isArray(data) ? data.slice(0, 2) : data };
-        }),
-        step("App query (ctx.platform.data, data:read): 'searches-by-day'", async () => {
-            const result = await ctx.platform.data.query<{ search_date: string; searches: number }>('searches-by-day', { from: input.from, to: input.to });
-            return {
-                summary: `${result.rowCount} days · ${result.bytesScanned} B scanned${result.cached ? ' · cached' : ''}`,
-                detail: result.rows,
-            };
-        }),
-    ]);
-    steps.push(analytics, dashboard, query);
-
-    // 7. Athena directly with the AWS SDK and client-scoped credentials (ctx.aws: only this client's tables).
-    steps.push(await step('Athena directly (AWS SDK + ctx.aws)', async () => {
-        const aws = ctx.aws;
-        if (!aws) throw new Error('ctx.aws is missing: the app needs the data:read scope');
-        const athena = new AthenaClient({
-            region: aws.region,
-            credentials: { accessKeyId: aws.accessKeyId, secretAccessKey: aws.secretAccessKey, sessionToken: aws.sessionToken },
-        });
-        const { QueryExecutionId } = await athena.send(new StartQueryExecutionCommand({
-            // dailysearches has a row per day *and* request type/engine/…: count distinct dates, not rows.
-            QueryString: 'SELECT count(DISTINCT search_date) AS days, sum(search_count) AS searches FROM dailysearches WHERE search_date BETWEEN ? AND ?',
-            ExecutionParameters: [`DATE '${input.from}'`, `DATE '${input.to}'`],
-            QueryExecutionContext: { Database: aws.database },
-            WorkGroup: aws.workGroup,
-            ResultConfiguration: { OutputLocation: aws.outputLocation },
-        }));
-        for (let i = 0; i < 40; i++) {
-            const { QueryExecution } = await athena.send(new GetQueryExecutionCommand({ QueryExecutionId }));
-            const state = QueryExecution?.Status?.State;
-            if (state === 'SUCCEEDED') {
-                const results = await athena.send(new GetQueryResultsCommand({ QueryExecutionId }));
-                const [days, searches] = results.ResultSet?.Rows?.[1]?.Data?.map((d) => d.VarCharValue) ?? [];
-                return { summary: `${days} days · ${Number(searches ?? 0).toLocaleString()} searches · ${QueryExecution?.Statistics?.DataScannedInBytes ?? 0} B scanned` };
-            }
-            if (state === 'FAILED' || state === 'CANCELLED') throw new Error(QueryExecution?.Status?.StateChangeReason ?? state);
-            await new Promise((resolve) => setTimeout(resolve, 500));
-        }
-        throw new Error('Athena query still running after 20 s');
-    }));
-
-    // 8. Outbound HTTP: functions can call any https API (with secrets for authenticated ones).
-    steps.push(await step(`Outbound HTTP (fetch): ${input.url}`, async () => {
-        const response = await fetch(input.url, { headers: { 'User-Agent': 'hawk-apps-showcase', Accept: 'application/json, text/plain' }, signal: AbortSignal.timeout(5000) });
-        const body = await response.text();
-        return { summary: `${response.status} · ${body.length} bytes`, detail: body.slice(0, 300) };
-    }));
-
-    // 9. Your own logic: combine the results, build a file, use Node built-ins.
-    steps.push(await step('Business logic (combine, CSV, gzip)', async () => {
-        const days = query.ok ? ((query.detail as Array<{ search_date: string; searches: number }>) ?? []) : [];
-        if (!days.length) throw new Error('No days from the app query to work with');
-        const busiest = days.reduce((best, d) => (d.searches > best.searches ? d : best));
-        const average = days.reduce((sum, d) => sum + d.searches, 0) / days.length;
-        const csv = ['date,searches,vs_average', ...days.map((d) => `${d.search_date},${d.searches},${(d.searches / average - 1).toFixed(3)}`)].join('\n');
-        return {
-            summary: `busiest ${busiest.search_date} (${busiest.searches}) · average ${Math.round(average)} · CSV ${csv.length} B → gzip ${gzipSync(csv).length} B`,
-            detail: csv.split('\n').slice(0, 6).join('\n'),
-        };
-    }));
-
-    // 10. Email through the platform (email:send): to the signed-in user only, never to anyone else.
-    steps.push(await step('Email (ctx.platform.email)', async () => {
-        const to = ctx.user.email;
-        if (!to) throw new Error('ctx.user.email is missing: the host did not pass an email address for this user, so nothing was sent');
-        const passed = steps.filter((s) => s.ok).length;
-        const days = query.ok ? ((query.detail as Array<{ search_date: string; searches: number }>) ?? []) : [];
-        const busiest = days.length ? days.reduce((best, d) => (d.searches > best.searches ? d : best)) : undefined;
-        const busiestText = busiest ? `${busiest.search_date} (${busiest.searches.toLocaleString()} searches)` : 'not available (the app query returned no days)';
-        const { messageId, recipients } = await ctx.platform.email.send({
-            to,
-            subject: 'Hawk Apps showcase',
-            text: [
-                `Hawk Apps showcase for client ${ctx.client.id}, ${input.from} to ${input.to}.`,
-                `${passed} of ${steps.length} steps passed so far.`,
-                `Busiest day: ${busiestText}.`,
-            ].join('\n'),
-            html:
-                `<p>Hawk Apps showcase for client <strong>${escapeHtml(ctx.client.id)}</strong>, ${escapeHtml(input.from)} to ${escapeHtml(input.to)}.</p>` +
-                `<ul><li>${passed} of ${steps.length} steps passed so far</li><li>Busiest day: ${escapeHtml(busiestText)}</li></ul>`,
-        });
-        return { summary: `sent to ${recipients} recipient${recipients === 1 ? '' : 's'} · messageId ${messageId}` };
-    }));
-
-    return { steps, totalMs: Math.round(performance.now() - started), runtime: runtime(ctx) };
-};
-
-function escapeHtml(value: string): string {
-    return value.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]!);
-}
-
-/** Where it ran: safe Lambda facts only (never the function's credentials from process.env). */
-function runtime(ctx: HawkFunctionContext): Record<string, unknown> {
-    return {
-        node: process.version,
-        region: process.env.AWS_REGION,
-        function: process.env.AWS_LAMBDA_FUNCTION_NAME,
-        lambdaVersion: process.env.AWS_LAMBDA_FUNCTION_VERSION,
-        memoryMb: Number(process.env.AWS_LAMBDA_FUNCTION_MEMORY_SIZE),
-        heapUsedMb: Math.round(process.memoryUsage().heapUsed / 1048576),
-        appVersion: ctx.version,
-    };
-}
+import { AthenaClient, GetQueryExecutionCommand, GetQueryResultsCommand, StartQueryExecutionCommand } from '@aws-sdk/client-athena';
+import type { HawkFunction, HawkFunctionContext } from '@bridgeline-digital/hawk-app-bridge/server';
+import { createHash } from 'node:crypto';
+import { gzipSync } from 'node:zlib';
+import { z } from 'zod';
+
+/**
+ * Showcase: everything a Hawk Apps function can do today, one step at a time. Each step reports ok/fail, timing and
+ * a short summary, and a failing step never stops the others, so the result doubles as a health check of the
+ * function runtime. Called from the Functions tab ("Run showcase").
+ */
+
+// 1. npm packages are bundled with the function (zod here; the AWS SDK below).
+const Input = z.object({
+    from: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+    to: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+    url: z.string().url().default('https://api.github.com/zen'),
+    dashboardPath: z.string().default('Synonym'),
+});
+type Input = z.infer<typeof Input>;
+
+interface Step {
+    name: string;
+    ok: boolean;
+    ms: number;
+    summary: string;
+    detail?: unknown;
+}
+
+interface ShowcaseResult {
+    steps: Step[];
+    totalMs: number;
+    runtime: Record<string, unknown>;
+}
+
+async function step(name: string, run: () => Promise<{ summary: string; detail?: unknown }>): Promise<Step> {
+    const started = performance.now();
+    try {
+        const { summary, detail } = await run();
+        return { name, ok: true, ms: Math.round(performance.now() - started), summary, detail };
+    } catch (e) {
+        const error = e as { message?: string; code?: string; status?: number };
+        const code = error.code ? ` (${error.code}${error.status ? ` ${error.status}` : ''})` : '';
+        return { name, ok: false, ms: Math.round(performance.now() - started), summary: `${error.message ?? String(e)}${code}` };
+    }
+}
+
+export const handler: HawkFunction<unknown, ShowcaseResult> = async (raw, ctx) => {
+    const started = performance.now();
+    const steps: Step[] = [];
+
+    // Validate the input first: a bad input fails fast with a readable message (thrown errors become 502 function_failed).
+    const parsed = Input.safeParse(raw ?? {});
+    if (!parsed.success) {
+        throw new Error(`Invalid input: ${parsed.error.issues.map((i) => `${i.path.join('.') || 'input'} ${i.message}`).join('; ')}`);
+    }
+    const input = parsed.data;
+    steps.push({ name: 'Validate input (zod, an npm package)', ok: true, ms: 0, summary: `from ${input.from} to ${input.to}` });
+
+    // 2. Who is calling, for which client and version: ctx comes from the signed app token, never from the browser.
+    steps.push(await step('Context (who, which client, which version)', async () => ({
+        summary: `client ${ctx.client.id} · user ${ctx.user.id}${ctx.internal ? ' (Bridgeline)' : ''} · ${ctx.app.slug} v${ctx.version}`,
+        detail: { client: ctx.client, user: { id: ctx.user.id, roles: ctx.user.roles }, internal: ctx.internal, app: ctx.app, version: ctx.version, host: ctx.host },
+    })));
+
+    // 3. Secrets: only the ones declared in hawk-app.json, read by the platform at call time. Never return the value.
+    steps.push(await step('Secret (TEST_SECRET)', async () => {
+        const secret = ctx.secrets.TEST_SECRET;
+        if (!secret) throw new Error('TEST_SECRET is not set: npx hawk-app secrets set TEST_SECRET');
+        const fingerprint = createHash('sha256').update(secret).digest('hex').slice(0, 12);
+        return { summary: `${secret.length} characters · sha256 ${fingerprint}… (value not shown)` };
+    }));
+
+    // 4-6. The platform, as the current user (same scopes as the app), in parallel.
+    const [analytics, dashboard, query] = await Promise.all([
+        step('Analytics API (ctx.platform.analytics, reports:read)', async () => {
+            const report = await ctx.platform.analytics.report<{ search_count?: number | string }>('searches', { startDate: input.from, endDate: input.to, limit: 1000 });
+            const total = report.data.reduce((sum, row) => sum + Number(row.search_count ?? 0), 0);
+            return { summary: `${report.data.length} rows · ${total.toLocaleString()} searches`, detail: report.data.slice(0, 3) };
+        }),
+        step(`Dashboard API (ctx.platform.dashboard, hawksearch:read): ${input.dashboardPath}`, async () => {
+            const data = await ctx.platform.dashboard.get<unknown>(input.dashboardPath);
+            return { summary: Array.isArray(data) ? `${data.length} items` : 'object', detail: Array.isArray(data) ? data.slice(0, 2) : data };
+        }),
+        step("App query (ctx.platform.data, data:read): 'searches-by-day'", async () => {
+            const result = await ctx.platform.data.query<{ search_date: string; searches: number }>('searches-by-day', { from: input.from, to: input.to });
+            return {
+                summary: `${result.rowCount} days · ${result.bytesScanned} B scanned${result.cached ? ' · cached' : ''}`,
+                detail: result.rows,
+            };
+        }),
+    ]);
+    steps.push(analytics, dashboard, query);
+
+    // 7. Athena directly with the AWS SDK and client-scoped credentials (ctx.aws: only this client's tables).
+    steps.push(await step('Athena directly (AWS SDK + ctx.aws)', async () => {
+        const aws = ctx.aws;
+        if (!aws) throw new Error('ctx.aws is missing: the app needs the data:read scope');
+        const athena = new AthenaClient({
+            region: aws.region,
+            credentials: { accessKeyId: aws.accessKeyId, secretAccessKey: aws.secretAccessKey, sessionToken: aws.sessionToken },
+        });
+        const { QueryExecutionId } = await athena.send(new StartQueryExecutionCommand({
+            // dailysearches has a row per day *and* request type/engine/…: count distinct dates, not rows.
+            QueryString: 'SELECT count(DISTINCT search_date) AS days, sum(search_count) AS searches FROM dailysearches WHERE search_date BETWEEN ? AND ?',
+            ExecutionParameters: [`DATE '${input.from}'`, `DATE '${input.to}'`],
+            QueryExecutionContext: { Database: aws.database },
+            WorkGroup: aws.workGroup,
+            ResultConfiguration: { OutputLocation: aws.outputLocation },
+        }));
+        for (let i = 0; i < 40; i++) {
+            const { QueryExecution } = await athena.send(new GetQueryExecutionCommand({ QueryExecutionId }));
+            const state = QueryExecution?.Status?.State;
+            if (state === 'SUCCEEDED') {
+                const results = await athena.send(new GetQueryResultsCommand({ QueryExecutionId }));
+                const [days, searches] = results.ResultSet?.Rows?.[1]?.Data?.map((d) => d.VarCharValue) ?? [];
+                return { summary: `${days} days · ${Number(searches ?? 0).toLocaleString()} searches · ${QueryExecution?.Statistics?.DataScannedInBytes ?? 0} B scanned` };
+            }
+            if (state === 'FAILED' || state === 'CANCELLED') throw new Error(QueryExecution?.Status?.StateChangeReason ?? state);
+            await new Promise((resolve) => setTimeout(resolve, 500));
+        }
+        throw new Error('Athena query still running after 20 s');
+    }));
+
+    // 8. Outbound HTTP: functions can call any https API (with secrets for authenticated ones).
+    steps.push(await step(`Outbound HTTP (fetch): ${input.url}`, async () => {
+        const response = await fetch(input.url, { headers: { 'User-Agent': 'hawk-apps-showcase', Accept: 'application/json, text/plain' }, signal: AbortSignal.timeout(5000) });
+        const body = await response.text();
+        return { summary: `${response.status} · ${body.length} bytes`, detail: body.slice(0, 300) };
+    }));
+
+    // 9. Your own logic: combine the results, build a file, use Node built-ins.
+    steps.push(await step('Business logic (combine, CSV, gzip)', async () => {
+        const days = query.ok ? ((query.detail as Array<{ search_date: string; searches: number }>) ?? []) : [];
+        if (!days.length) throw new Error('No days from the app query to work with');
+        const busiest = days.reduce((best, d) => (d.searches > best.searches ? d : best));
+        const average = days.reduce((sum, d) => sum + d.searches, 0) / days.length;
+        const csv = ['date,searches,vs_average', ...days.map((d) => `${d.search_date},${d.searches},${(d.searches / average - 1).toFixed(3)}`)].join('\n');
+        return {
+            summary: `busiest ${busiest.search_date} (${busiest.searches}) · average ${Math.round(average)} · CSV ${csv.length} B → gzip ${gzipSync(csv).length} B`,
+            detail: csv.split('\n').slice(0, 6).join('\n'),
+        };
+    }));
+
+    // 10. Email through the platform (email:send): to the signed-in user only, never to anyone else.
+    steps.push(await step('Email (ctx.platform.email)', async () => {
+        const to = ctx.user.email;
+        if (!to) throw new Error('ctx.user.email is missing: the host did not pass an email address for this user, so nothing was sent');
+        const passed = steps.filter((s) => s.ok).length;
+        const days = query.ok ? ((query.detail as Array<{ search_date: string; searches: number }>) ?? []) : [];
+        const busiest = days.length ? days.reduce((best, d) => (d.searches > best.searches ? d : best)) : undefined;
+        const busiestText = busiest ? `${busiest.search_date} (${busiest.searches.toLocaleString()} searches)` : 'not available (the app query returned no days)';
+        const { messageId, recipients } = await ctx.platform.email.send({
+            to,
+            subject: 'Hawk Apps showcase',
+            text: [
+                `Hawk Apps showcase for client ${ctx.client.id}, ${input.from} to ${input.to}.`,
+                `${passed} of ${steps.length} steps passed so far.`,
+                `Busiest day: ${busiestText}.`,
+            ].join('\n'),
+            html:
+                `<p>Hawk Apps showcase for client <strong>${escapeHtml(ctx.client.id)}</strong>, ${escapeHtml(input.from)} to ${escapeHtml(input.to)}.</p>` +
+                `<ul><li>${passed} of ${steps.length} steps passed so far</li><li>Busiest day: ${escapeHtml(busiestText)}</li></ul>`,
+        });
+        return { summary: `sent to ${recipients} recipient${recipients === 1 ? '' : 's'} · messageId ${messageId}` };
+    }));
+
+    return { steps, totalMs: Math.round(performance.now() - started), runtime: runtime(ctx) };
+};
+
+function escapeHtml(value: string): string {
+    return value.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]!);
+}
+
+/** Where it ran: safe Lambda facts only (never the function's credentials from process.env). */
+function runtime(ctx: HawkFunctionContext): Record<string, unknown> {
+    return {
+        node: process.version,
+        region: process.env.AWS_REGION,
+        function: process.env.AWS_LAMBDA_FUNCTION_NAME,
+        lambdaVersion: process.env.AWS_LAMBDA_FUNCTION_VERSION,
+        memoryMb: Number(process.env.AWS_LAMBDA_FUNCTION_MEMORY_SIZE),
+        heapUsedMb: Math.round(process.memoryUsage().heapUsed / 1048576),
+        appVersion: ctx.version,
+    };
+}