# Recipe: AI-driven product demo on Cloudflare
#
# Use case: produce a walkthrough video + per-story narrative of a deployed
# site (preview, staging, or prod) so a reviewer can SEE the change work
# without checking anything out locally. Offload to the `product-demo` run,
# which attaches Browser Rendering over CDP, records ONE master video while
# driving the site through each story, and writes a holistic summary.
#
# Mode: Action mode, fire-and-forget. The run posts the result through the
#       `flare-dispatch/product-demo` check-run — the video link + the
#       summary land in the check-run summary, which reviewers paste into
#       the PR. See specs/04-gha-integration.md.
# Run:  product-demo — see ./product-demo.run.ts.

name: product-demo
on:
  # On every PR touching the app, drive a fixed default story set against
  # the PR's preview deployment URL (a `vars.PREVIEW_URL_TEMPLATE` or a
  # deploy-env URL — configure per repo).
  pull_request:
    paths: ["apps/**"]
  # On-demand against any URL (preview, staging, prod). Optionally override the
  # tracked markdown script inline. Useful for QA, release sign-off, marketing.
  workflow_dispatch:
    inputs:
      deployed_url:
        description: "URL to drive (preview / staging / prod)"
        required: true
      stories_markdown:
        description: "Markdown story script (each `## ` heading = one chapter). Blank ⇒ the tracked demo-stories.md."
        required: false

jobs:
  product-demo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # The story script lives as readable markdown (each `## ` heading = one
      # chapter; see the README § "Authoring stories"), not inline JSON. Read
      # the tracked demo-stories.md into a step output — unless the dispatch
      # passed an inline override. The run parses `storiesMarkdown` into the
      # same {name, prose} list the structured `stories` array produces.
      - name: Load demo stories
        id: stories
        run: |
          { echo 'md<<DEMO_STORIES_EOF'
            if [ -n "${OVERRIDE}" ]; then printf '%s\n' "${OVERRIDE}"; else cat recipes/product-demo/demo-stories.md; fi
            echo DEMO_STORIES_EOF
          } >> "$GITHUB_OUTPUT"
        env:
          OVERRIDE: ${{ github.event.inputs.stories_markdown }}

      - uses: openhackersclub/flare-dispatch-action@v1
        with:
          run: product-demo
          endpoint: ${{ vars.FLAREDISPATCH_ENDPOINT }}
          hmac-secret: ${{ secrets.FLAREDISPATCH_HMAC }}
          inputs: |
            {
              "repo": "${{ github.repository }}",
              "sha": "${{ github.event.pull_request.head.sha || github.sha }}",
              "deployedUrl": ${{ toJSON(github.event.inputs.deployed_url || vars.PREVIEW_URL) }},
              "storiesMarkdown": ${{ toJSON(steps.stories.outputs.md) }},
              "viewportPreset": "desktop"${{ github.event.pull_request.number && format(', "pr": {0}', github.event.pull_request.number) || '' }}
            }
          # `pr` is what enables the GIF-on-completion comment: on a `pull_request`
          # the run posts the holistic summary + an inline walkthrough GIF to the
          # PR. On `workflow_dispatch` there is no PR, so it is omitted and the
          # run reports via the `flare-dispatch/product-demo` check-run only. For
          # the GIF to render inline, the deploy's `/v1/artifacts/...` route must
          # be public (GitHub's image proxy fetches it server-side).
          #
          # Prefer the structured array? Swap the `"storiesMarkdown"` line for
          # `"stories": [{ "name": "...", "prose": "..." }]` and drop the "Load
          # demo stories" step — `stories` wins if both are supplied.

# Fire-and-forget: this GHA step succeeds as soon as the dispatch is
# accepted; the actual demo runs on Cloudflare and reports back through the
# `flare-dispatch/product-demo` check-run on the PR head SHA. Require that
# check (not this GHA job) in branch protection. The check-run summary
# embeds the signed video URL — reviewers drop it into the PR description.

// Recipe: AI-driven product demo — the `product-demo` Run
//
// The typed Run that ./ci.yml dispatches. A team hands it a deployed URL
// (preview / staging / prod) and a list of user stories as prose; the run
// drives the site through each story in sequence over a single CDP
// session with Browser Run's native rrweb session recording enabled,
// captures key screenshots, writes a per-story narrative, and then
// produces a holistic markdown summary across all stories that a reviewer
// can paste into the PR.
//
// No checkout — the target is a deployed URL, not the repo. The run only
// attaches to Browser Run over CDP and shells out to the bundled
// `demo-agent` CLI (baked into the `flare-dispatch-demo:latest` image, the
// same shape as `review-agent` in recipes/ai-code-review). The agent owns
// the model loop and CDP action application; the platform owns recording
// (Browser Run records rrweb DOM events at the session level when the CDP
// connect URL carries `?recording=true`); this run only orchestrates:
// attach → record start (set viewport, capture sessionId) → for each
// story play → record stop (close session, pull rrweb events from the
// Browser Run REST API, upload as R2 JSON) → summarize.
//
// Mode: Action — dispatched by ./ci.yml on `pull_request` and on manual
//       `workflow_dispatch`. See specs/04-gha-integration.md § Action mode.
// DSL:  uses `browser.newCDPSession`, `sandbox.exec`, `artifact.upload`,
//       `config.get`, and `io.priorExecution` — specs/03-dsl.md § Capabilities.

import { Effect, Schema, Option } from "effect";
import {
  defineRun,
  step,
  sandbox,
  browser,
  artifact,
  config,
  io,
} from "@flare-dispatch/core";
import { loadSecrets } from "@flare-dispatch/core/primitives";

// A user story is just a name + prose. The agent reads the prose, decides
// the next browser action, applies it over the live CDP session, captures
// screenshots, and emits a narrative. Names must be unique within the
// `stories` array — they become chapter markers on the rrweb replay timeline.
const Story = Schema.Struct({
  name: Schema.String,
  prose: Schema.String,
});

/**
 * Parse a markdown stories doc into `{ name, prose }[]` — each level-2 ATX
 * heading (`## `) is one story (heading = name, body until the next `## ` =
 * prose). Content before the first heading is ignored. Pure + deterministic.
 * The canonical copy lives in `runs/product-demo.ts`; kept in sync here so the
 * teaching example shows the markdown-authoring path.
 */
export const parseStoriesMarkdown = (
  markdown: string,
): ReadonlyArray<{ name: string; prose: string }> => {
  const headingRe = /^ {0,3}##\s+(.+?)\s*#*\s*$/;
  const stories: Array<{ name: string; prose: string[] }> = [];
  let current: { name: string; prose: string[] } | null = null;
  for (const line of markdown.split(/\r?\n/)) {
    const match = headingRe.exec(line);
    if (match) {
      current = { name: match[1]!.trim(), prose: [] };
      stories.push(current);
      continue;
    }
    if (current) current.prose.push(line);
  }
  return stories.map((s) => ({
    name: s.name,
    prose: s.prose.join("\n").trim(),
  }));
};

const Input = Schema.Struct({
  // The deployed URL the demo runs against. No checkout — this is the
  // target site, not the repo. `repo` and `sha` are still required because
  // the check-run callback anchors to them (specs/04-gha-integration.md
  // § Check-runs callback).
  repo: Schema.String,
  sha: Schema.String,
  deployedUrl: Schema.String,
  // Provide exactly one: `stories` (structured `{ name, prose }[]`) or
  // `storiesMarkdown` (a markdown doc, one `## ` heading per story). `stories`
  // wins if both are present; the run resolves the effective list below.
  stories: Schema.optional(Schema.Array(Story)),
  storiesMarkdown: Schema.optional(Schema.String),
  // The viewport preset is passed through to the agent — it sets the CDP
  // viewport once at attach time via Emulation.setDeviceMetricsOverride so
  // every rrweb event in the session uses one resolution. Default desktop;
  // "mobile" emulates a phone profile in the agent.
  viewportPreset: Schema.optional(Schema.Literal("desktop", "mobile")),
  // Per-story wall-clock ceiling. Stories run sequentially against ONE
  // rrweb-recorded session so the replay timeline is continuous; without
  // a per-story cap one stuck story would burn the whole run's
  // `maxDurationSec`.
  maxDurationSecPerStory: Schema.optional(Schema.Number),
});

// Each story round-trips its own per-chapter record so the summary can
// point a reviewer at the exact span of the rrweb replay to look at.
const StoryResult = Schema.Struct({
  name: Schema.String,
  status: Schema.Literal("passed", "failed"),
  durationMs: Schema.Number,
  // rrweb timestamps in ms from session start — a reviewer can jump straight
  // to a story's chapter in the replay player by seeking to chapterStartMs.
  chapterStartMs: Schema.Number,
  chapterEndMs: Schema.Number,
  narrative: Schema.String,
  keyScreenshotUri: Schema.String,
});

const Output = Schema.Struct({
  // The docs-site rrweb player URL (https://<docsBase>/replay/<sessionId>).
  // Reviewers click through to scrub the recording. The replay UI itself
  // ships separately — see specs/pm/plan.md § Replay UI; until then this
  // links to a "coming soon" page that displays the raw replayJsonUri.
  replayUri: Schema.String,
  // Signed R2 URL to the raw rrweb event JSON (30-day TTL). Power-user
  // escape hatch — drop into an rrweb-player iframe to self-host the
  // replay. The dispatcher mirrors Browser Run's 30-day retention.
  replayJsonUri: Schema.String,
  summaryMd: Schema.String,       // the holistic LLM-written summary
  stories: Schema.Array(StoryResult),
});

export const productDemo = defineRun({
  name: "product-demo",
  version: "1.0.0",
  // The operator's sandbox image (the one bound to `RUNS_SANDBOX` via
  // `wrangler.jsonc`) MUST include the `demo-agent` binary on PATH — model
  // loop, CDP-driver glue, and the Browser Run recording REST client.
  // FlareDispatch has one container binding per Worker, pinned by
  // `infra/Dockerfile.sandbox`; drop the `demo-agent` layer from
  // `recipes/product-demo/Dockerfile.example` into your own sandbox image
  // to enable this run.
  inputs: Input,
  outputs: Output,
  // Stories run SEQUENTIALLY against one CDP session so the rrweb timeline
  // stays continuous. `maxConcurrency: 1` makes the sequencing explicit and
  // keeps the Browser Run session count to 1. `requiresBrowser: true`
  // reserves a slot in the Browser Run pool — and the dispatcher's
  // `newCDPSession` primitive appends `?recording=true` so Browser Run
  // captures the rrweb event stream for the session's lifetime.
  limits: { maxDurationSec: 3600, maxConcurrency: 1, requiresBrowser: true },

  run: (input) =>
    Effect.gen(function* () {
      const viewport = input.viewportPreset ?? "desktop";
      const perStorySec = input.maxDurationSecPerStory ?? 180;

      // -1. Resolve the effective story list before any browser/sandbox work.
      //     `stories` wins over `storiesMarkdown`; the markdown is parsed into
      //     the same `{ name, prose }` shape, so nothing downstream is markdown
      //     -aware. Die loudly on a payload with neither / on duplicate names.
      const resolvedStories =
        input.stories !== undefined && input.stories.length > 0
          ? input.stories
          : input.storiesMarkdown !== undefined
            ? parseStoriesMarkdown(input.storiesMarkdown)
            : [];
      if (resolvedStories.length === 0) {
        return yield* Effect.die(
          "product-demo: no stories to play — supply a non-empty `stories` array, " +
            "or a `storiesMarkdown` doc with at least one `## ` heading.",
        );
      }
      const duplicateNames = [
        ...new Set(
          resolvedStories
            .map((s) => s.name)
            .filter((n, i, a) => a.indexOf(n) !== i),
        ),
      ];
      if (duplicateNames.length > 0) {
        return yield* Effect.die(
          `product-demo: duplicate story names ${JSON.stringify(duplicateNames)} — ` +
            "each story name becomes a unique rrweb chapter marker.",
        );
      }

      // 0. Resolve the demo-agent's runtime credentials from CONFIG_KV. The
      //    container holds NO ambient credentials. The agent is
      //    provider-agnostic on `@effect/ai`'s `LanguageModel` Tag and speaks
      //    the OpenAI wire format, always routed through a Cloudflare AI
      //    Gateway; the upstream is the operator's gateway config.
      //      * `CF_AI_GATEWAY_ID`       — gateway slug. The endpoint
      //        `https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/compat`
      //        is derived from this + `CLOUDFLARE_ACCOUNT_ID` (no
      //        `MODEL_BASE_URL`).
      //      * `CLOUDFLARE_ACCOUNT_ID`  — account that owns the gateway AND the
      //        Browser Rendering session.
      //      * `CLOUDFLARE_API_TOKEN`   — recording REST fetch auth.
      //      * `MODEL_API_KEY` (optional) — upstream provider key
      //        (`Authorization: Bearer`); unset under gateway BYOK.
      //      * `CF_AI_GATEWAY_TOKEN` (optional) — the gateway's own auth
      //        (`cf-aig-authorization`), for an Authenticated Gateway.
      //        Orthogonal to `MODEL_API_KEY`.
      const requiredAgentEnv = yield* loadSecrets(
        ["CF_AI_GATEWAY_ID", "CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_API_TOKEN"],
        { prefix: "product-demo.secret/", required: true },
      );
      const optionalAgentEnv = yield* loadSecrets(
        ["MODEL_API_KEY", "CF_AI_GATEWAY_TOKEN"],
        { prefix: "product-demo.secret/" },
      );
      const agentEnv = { ...requiredAgentEnv, ...optionalAgentEnv };

      // 1. Attach Browser Run over CDP against the DEPLOYED URL. No
      //    checkout, no app boot — the site is already live. The dispatcher's
      //    `newCDPSession` primitive composes the connect URL with
      //    `?recording=true` so Browser Run records rrweb DOM events for
      //    the whole session; the agent doesn't have to start recording —
      //    it inherits a session that's already recording.
      const session = yield* step("attach-cdp", () =>
        browser.newCDPSession({ targetUrl: input.deployedUrl }),
      );

      // Filesystem layout inside the container — relative paths the agent
      // writes through. The session-id file is the handoff between
      // `record-start` (which queries it via puppeteer.sessionId()) and
      // `record-stop` (which uses it to call Browser Run's recording REST
      // endpoint after the session closes).
      const sessionIdPath = "/tmp/demo/session-id";
      const replayJsonPath = "/tmp/demo/replay.json";
      const screenshotsDir = "/tmp/demo/screenshots";
      const storiesJsonPath = "/tmp/demo/stories.json";
      const summaryPath = "/tmp/demo/summary.md";

      // 2. Validate the connect URL carries `?recording=true`, set the
      //    viewport once (one resolution for the whole rrweb stream), and
      //    capture the session ID for the REST pull in step 4. The agent
      //    does NOT start a recording pipeline of its own — Browser Run is
      //    already recording on the platform side.
      yield* step("record-start", () =>
        sandbox.exec({
          command: [
            "demo-agent", "record", "start",
            "--cdp-ws", session.wsEndpoint,
            "--viewport", viewport,
            "--session-id-out", sessionIdPath,
          ],
          env: agentEnv,
        }),
      );

      // 2.5. Resolve per-step model ids through CONFIG_KV — same seam as
      //      `pr-review`. Both required; no provider-specific default lives
      //      in code (a default like `claude-opus-4-7` is meaningless if the
      //      gateway is pointed at OpenAI / Workers AI / Bedrock). Unset
      //      keys die loudly.
      const playModel = yield* step("resolve-play-model", () =>
        config.get("product-demo.model.play").pipe(
          Effect.flatMap((v) =>
            v !== undefined && v !== ""
              ? Effect.succeed(v)
              : Effect.die(
                  "CONFIG_KV missing required key: product-demo.model.play",
                ),
          ),
        ),
      );

      // 3. Walk the stories in order. Each `demo-agent play` reads the
      //    prose, applies actions over the SAME CDP session (so the rrweb
      //    timeline stays continuous), captures key screenshots into
      //    `screenshotsDir`, and emits one JSON line per story with the
      //    chapter offsets (rrweb timestamps), status, narrative, and the
      //    key-screenshot path. Concurrency 1 — see `limits` above.
      const playResults = yield* step("play-stories", () =>
        Effect.forEach(
          resolvedStories,
          (story) =>
            sandbox.exec({
              command: [
                "demo-agent", "play",
                "--cdp-ws", session.wsEndpoint,
                "--name", story.name,
                "--prose", story.prose,
                "--screenshots", screenshotsDir,
                "--max-sec", String(perStorySec),
                "--model", playModel,
              ],
              env: agentEnv,
              timeoutSec: perStorySec + 30,
            }),
          { concurrency: 1 },
        ),
      );

      // 4. Close the CDP session and pull the recording. Browser Run only
      //    finalizes rrweb events after the session closes; `demo-agent
      //    record stop` closes the session, polls
      //    GET /accounts/<id>/browser-rendering/recording/<sessionId>, writes
      //    the event array to `--out`, and emits a JSON last-line with the
      //    sessionId + the realized event count.
      const recordStopResult = yield* step("record-stop", () =>
        sandbox.exec({
          command: [
            "demo-agent", "record", "stop",
            "--cdp-ws", session.wsEndpoint,
            "--session-id-in", sessionIdPath,
            "--out", replayJsonPath,
          ],
          env: agentEnv,
        }),
      );

      // 5. Parse each `play` step's JSON stdout. The agent's contract: one
      //    JSON object per invocation on the LAST line of stdout (anything
      //    before is logs). The shape is fixed by the agent — mirrors the
      //    `review-agent coordinate --json` pattern in recipes/ai-code-review.
      type PlayJson = {
        status: "passed" | "failed";
        durationMs: number;
        chapterStartMs: number;
        chapterEndMs: number;
        narrative: string;
        keyScreenshotPath: string;
      };
      const parsed = playResults.map((r, i) => {
        const lastLine = r.stdout.trim().split("\n").pop() ?? "{}";
        return {
          story: resolvedStories[i],
          json: JSON.parse(lastLine) as PlayJson,
        };
      });

      type RecordStopJson = { sessionId: string; eventCount: number };
      const recordStopJson = JSON.parse(
        recordStopResult.stdout.trim().split("\n").pop() ?? "{}",
      ) as RecordStopJson;

      // 6. Upload the rrweb event JSON once, signed for 30 days so the link
      //    survives PR-review cycles. Reviewers paste the URL straight into
      //    the PR description, or feed it to an rrweb-player iframe.
      const replayJsonUri = yield* step("upload-replay-json", () =>
        artifact.upload({
          name: "replay.json",
          path: replayJsonPath,
          contentType: "application/json",
          signedUrlTTL: "30 days",
        }),
      );

      // 7. Upload each story's key screenshot in parallel (concurrency 4
      //    — independent uploads, no shared state). Each returns its own
      //    signed URL embedded into the per-story result.
      const screenshotUris = yield* step("upload-screenshots", () =>
        Effect.forEach(
          parsed,
          (p) =>
            artifact.upload({
              name: `${p.story.name}.png`,
              path: p.json.keyScreenshotPath,
              contentType: "image/png",
              signedUrlTTL: "30 days",
            }),
          { concurrency: 4 },
        ),
      );

      // 8. Resolve the summary model id (required, same shape as
      //    `product-demo.model.play` above) and the docs-site base. Docs
      //    base IS tuning, not gating, so it keeps a default; the model id
      //    has no provider-neutral default and dies loudly when unset.
      const summaryModel = yield* step("resolve-summary-model", () =>
        config.get("product-demo.model.summary").pipe(
          Effect.flatMap((v) =>
            v !== undefined && v !== ""
              ? Effect.succeed(v)
              : Effect.die(
                  "CONFIG_KV missing required key: product-demo.model.summary",
                ),
          ),
        ),
      );
      const docsBase = yield* step("resolve-docs-base", () =>
        config.get("product-demo.docsBase").pipe(
          Effect.map(
            (override) => override ?? "https://flare-dispatch.openhackersclub.com",
          ),
        ),
      );
      const replayUri = `${docsBase}/replay/${recordStopJson.sessionId}`;

      // 9. Stitch typed per-story results, then write them to disk for the
      //    agent's summarizer. Doing the file write through `sandbox.exec`
      //    keeps everything inside the container — the agent and the file
      //    sit on the same filesystem.
      const stories = parsed.map((p, i) => ({
        name: p.story.name,
        status: p.json.status,
        durationMs: p.json.durationMs,
        chapterStartMs: p.json.chapterStartMs,
        chapterEndMs: p.json.chapterEndMs,
        narrative: p.json.narrative,
        keyScreenshotUri: screenshotUris[i],
      }));
      yield* step("write-stories-json", () =>
        sandbox.exec({
          command: [
            "demo-agent", "write-json",
            "--out", storiesJsonPath,
            "--data", JSON.stringify({ stories, replayUri, replayJsonUri }),
          ],
          env: agentEnv,
        }),
      );

      // 10. Load the previous execution for this (repo, deployedUrl) so
      //     `summarize` can call out what's new / regressed since the last
      //     demo run. `Option.match` — never `_tag` access (CLAUDE.md
      //     Effect-TS rules).
      const prior = yield* step("load-prior", () =>
        io.priorExecution({
          family: `product-demo:${input.repo}:${input.deployedUrl}`,
          outputSchema: Output,
        }),
      );

      // 11. Hand the previous summary to the agent as a file IF it exists.
      //     Seeding via an intermediate file (instead of `--previous-json
      //     '<...>'`) avoids ARG_MAX surprises when the prior summary is
      //     long-form prose.
      const previousArgs = yield* Option.match(prior, {
        onNone: () => Effect.succeed<readonly string[]>([]),
        onSome: (p) =>
          step("seed-prior", () =>
            sandbox.exec({
              command: [
                "demo-agent", "write-prior",
                "--out", "/tmp/demo/previous.md",
                "--data", p.output.summaryMd,
              ],
              env: agentEnv,
            }).pipe(Effect.as(["--previous", "/tmp/demo/previous.md"] as const)),
          ),
      });

      // 12. Generate the holistic summary. The agent emits the markdown to
      //     stdout AND writes it to `--out`; we read it from stdout because
      //     `io` has no file-read primitive — see specs/03-dsl.md § io.
      const summaryResult = yield* step("summarize", () =>
        sandbox.exec({
          command: [
            "demo-agent", "summarize",
            "--stories-json", storiesJsonPath,
            "--model", summaryModel,
            "--out", summaryPath,
            ...previousArgs,
          ],
          env: agentEnv,
        }),
      );

      yield* io.log(
        "info",
        `product-demo: ${stories.length} stories, ${stories.filter((s) => s.status === "passed").length} passed, ${recordStopJson.eventCount} rrweb events`,
      );

      // The check-run summary the Dispatcher posts EMBEDS `summaryMd`
      // verbatim and links `replayUri` — reviewers see the holistic write-up
      // on the PR's Checks tab and one signed replay link they can drop
      // straight into the PR description (see specs/04-gha-integration.md
      // § Inline findings — summary).
      return {
        replayUri,
        replayJsonUri,
        summaryMd: summaryResult.stdout.trim(),
        stories,
      };
    }),
});