From 2808eef158c705a4740dd5c4b4d5acce10ab8d37 Mon Sep 17 00:00:00 2001 From: Archi Date: Mon, 26 Oct 2026 12:29:08 +0100 Subject: [PATCH 01/71] =?UTF-8?q?docs:=20Phase=208=20=E2=80=94=20share=20l?= =?UTF-8?q?inks,=20website=20editor,=20scheduled=20checks,=20hold=20the=20?= =?UTF-8?q?result?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ADR-0019 (opt-in share links), ADR-0020 (edits from the website), ADR-0021 (scheduled checks), the Phase 8 roadmap section and specs for #347-#365. --- docs/adr/0019-opt-in-share-links.md | 110 +++++++ docs/adr/0020-edits-from-the-website.md | 124 ++++++++ docs/adr/0021-scheduled-checks.md | 107 +++++++ docs/adr/README.md | 3 + docs/product/roadmap.md | 32 +- docs/specs/347-share-storage-api.md | 309 ++++++++++++++++++++ docs/specs/348-share-public-endpoints.md | 156 ++++++++++ docs/specs/349-cli-share.md | 182 ++++++++++++ docs/specs/350-web-share-dialog.md | 121 ++++++++ docs/specs/351-web-share-page.md | 124 ++++++++ docs/specs/352-docs-sharing.md | 86 ++++++ docs/specs/353-edits-schema-and-render.md | 201 +++++++++++++ docs/specs/354-trim-and-cuts.md | 153 ++++++++++ docs/specs/355-runner-edits-and-rerender.md | 218 ++++++++++++++ docs/specs/356-editor-relay-api.md | 170 +++++++++++ docs/specs/357-timeline-editor.md | 168 +++++++++++ docs/specs/358-edits-export-reset-share.md | 121 ++++++++ docs/specs/359-editor-docs.md | 102 +++++++ docs/specs/360-run-check-mode.md | 208 +++++++++++++ docs/specs/361-config-schedule.md | 177 +++++++++++ docs/specs/362-check-schedules-api.md | 243 +++++++++++++++ docs/specs/363-check-schedules-web.md | 153 ++++++++++ docs/specs/364-checks-docs.md | 98 +++++++ docs/specs/365-hold-the-result.md | 218 ++++++++++++++ docs/specs/README.md | 19 ++ 25 files changed, 3600 insertions(+), 3 deletions(-) create mode 100644 docs/adr/0019-opt-in-share-links.md create mode 100644 docs/adr/0020-edits-from-the-website.md create mode 100644 docs/adr/0021-scheduled-checks.md create mode 100644 docs/specs/347-share-storage-api.md create mode 100644 docs/specs/348-share-public-endpoints.md create mode 100644 docs/specs/349-cli-share.md create mode 100644 docs/specs/350-web-share-dialog.md create mode 100644 docs/specs/351-web-share-page.md create mode 100644 docs/specs/352-docs-sharing.md create mode 100644 docs/specs/353-edits-schema-and-render.md create mode 100644 docs/specs/354-trim-and-cuts.md create mode 100644 docs/specs/355-runner-edits-and-rerender.md create mode 100644 docs/specs/356-editor-relay-api.md create mode 100644 docs/specs/357-timeline-editor.md create mode 100644 docs/specs/358-edits-export-reset-share.md create mode 100644 docs/specs/359-editor-docs.md create mode 100644 docs/specs/360-run-check-mode.md create mode 100644 docs/specs/361-config-schedule.md create mode 100644 docs/specs/362-check-schedules-api.md create mode 100644 docs/specs/363-check-schedules-web.md create mode 100644 docs/specs/364-checks-docs.md create mode 100644 docs/specs/365-hold-the-result.md diff --git a/docs/adr/0019-opt-in-share-links.md b/docs/adr/0019-opt-in-share-links.md new file mode 100644 index 00000000..cce7c5d1 --- /dev/null +++ b/docs/adr/0019-opt-in-share-links.md @@ -0,0 +1,110 @@ +# ADR-0019: Opt-in share links — one render, uploaded on an explicit share + +Status: accepted · Date: 2026-10-26 · Supersedes: the roadmap's Phase 5 rule "No public share links" ([roadmap](../product/roadmap.md), Phase 5) · Extends: [ADR-0008](0008-cloud-boundary.md) §2 and §3 + +## Context + +Until now a video never left the user's machine. [ADR-0008](0008-cloud-boundary.md) +§2 lists video among the things a runner **never** sends, §5 leaves "cloud +upload of a video" to "a later, explicit, per-video action", and the website +plays a run only through the relay ([ADR-0009](0009-playback-relay-and-luna-player-adapter.md)): +the API asks the owning runner for byte ranges and stores nothing. The +roadmap's Phase 5 made the consequence explicit: "No public share links … +Sharing is by file or through the GitHub Action." + +That leaves the product without its most common use. A demo is made to be +shown to someone who has no DemoFlow account: a colleague, a customer, a +reviewer, a README. Today the person downloads the file and sends it by +other means, and a link to the run page works only for its owner and only +while the machine is online. + +The owner decided, in the Phase 8 interview (2026-10-26), to add share +links: stored on the server's disk, open to anyone with the link, optionally +behind a password, and created only by an explicit action. + +## Decision + +1. **A share is an explicit, per-video action.** A share is created only + when a person (on the website or with `demoflow share`) or an MCP client + the project allows (Decision 6) asks for it. Nothing is ever uploaded + because a run finished, a render changed or a machine came online. + ADR-0008 §5 still holds; this ADR is the action it left for later. +2. **What crosses, on a share, and nothing more** (extends ADR-0008 §2): + - **one rendered file**, in the one format the person chose, exactly as + the renderer wrote it; + - **a poster**: one JPEG frame of that file, at most 1280 px wide, made on + the machine; + - the scenario's **name** (already on the server, ADR-0008 §2) and its + **description**, which crosses for the first time: the daemon reads it + from the scenario file on the machine at share time; + - the **chapter list**: each scene's title and its start time in that + render, in milliseconds. + + Still never: the source recording, other formats, `fill` values, query + strings, logs, screenshots, traces, local paths, the scenario body. A share + does not change what an ordinary run report sends. +3. **What the website may make a runner do** gains one item (extends + ADR-0008 §3): **upload one render of a run it reported, for a share the + owner created**. The upload reuses the relay's pull model: the API asks, + the runner answers with the file in acknowledged chunks over its existing + socket. The runner checks that the run is one it reported and the format + one it rendered, as it does for playback, and never reads a path or a + name from the message. +4. **The server stores the shared copy on its own disk**, in a directory + outside the database, one directory per share. No third-party object store. + - Limits, set in the API's environment: **200 MB per file, 2 GB per user** + (the sum of the user's live shares). An upload that would exceed either + is refused before a byte is sent. + - The files are **not backed up**. The original is always on the user's + machine. A share whose file is gone is marked lost; its owner uploads it + again. +5. **Access: anyone with the link, optionally a password.** A share has an + unguessable token in its URL (`/s/`). The owner may set a password; + only its argon2id hash is stored, attempts are rate-limited, and while a + password is set the file is served only to a browser that entered it — the + direct file URL works only for shares without a password. + - **Lifetime:** 7, 30 (default) or 90 days, chosen at creation; the owner + may extend by 30 days, never beyond 90 days from now. There is no + share without an expiry. Expired shares are deleted with their files. + - **Revocation is immediate:** revoking a share, deleting its run on the + website, deleting its project and deleting the account all delete the + share; the link stops working at once and the file is deleted. + - Deleting the run's files on the machine, or pruning local runs, does + **not** revoke a share: the share is a copy. + - The owner sees how many times the share page was opened. No IP address, + user agent or other data about viewers is stored. +6. **Who may create a share:** the website (the run's owner), the CLI + (`demoflow share`, signed in with `demoflow login`) and the MCP server. An + MCP client publishes outside the machine without a person in the loop, so + **the MCP tool is refused unless the project's committed + `demoflow.config.json` says `share: { allowMcp: true }`**. The decision to + let agents publish is a commit a person reviews. +7. **A machine says it can share before it is asked to.** A daemon that + implements this ADR announces `share` in the capability list + (`features: string[]`) of its first frame on each socket, the same list + ADR-0020 adds `edits` to, as + [ADR-0017](0017-website-run-options.md) §5 does for run options. The API + never sends a share request to a daemon that did not, and answers that the + machine needs a newer CLI. + +## Consequences + +- The server now holds user video. Disk on the production host is a + capacity the owner watches; the per-user limit and the expiry bound it, and + the stored files are excluded from database backups. +- Viewers download from the server, not from the machine: a share keeps + working while the machine is off. Upload traffic passes through Cloudflare + and the API once per share. +- A share is a snapshot. Re-rendering the run (the Phase 8 editor) does not + change it. Replacing the file of an existing share is an explicit action + only — the owner's "Update link" ([ADR-0020](0020-edits-from-the-website.md) + §6, `POST /shares/:id/update`, added by #356): same token, same expiry and + view count, a new upload under Decisions 2–4. Nothing replaces it + automatically. +- A leaked link exposes that one video until it is revoked or expires. The + token is stored so the owner can copy the link again; the password and the + expiry are the owner's tools against a leak. +- An older CLI cannot share. The website shows why and how to update. +- The roadmap's Phase 5 rule "No public share links" no longer holds; + "sharing is by file or through the GitHub Action" remains true for anyone + who does not create a share. diff --git a/docs/adr/0020-edits-from-the-website.md b/docs/adr/0020-edits-from-the-website.md new file mode 100644 index 00000000..d143717c --- /dev/null +++ b/docs/adr/0020-edits-from-the-website.md @@ -0,0 +1,124 @@ +# ADR-0020: A run's edits come from the website, and the Runner re-renders + +Status: accepted · Date: 2026-10-26 · Extends: [ADR-0008](0008-cloud-boundary.md) §2 and §3 · Specs: [353](../specs/353-edits-schema-and-render.md), [354](../specs/354-trim-and-cuts.md), [355](../specs/355-runner-edits-and-rerender.md), [356](../specs/356-editor-relay-api.md), [357](../specs/357-timeline-editor.md), [358](../specs/358-edits-export-reset-share.md), [359](../specs/359-editor-docs.md) + +## Context + +A rendered video is fixed by three things: the recording (`source.webm`, +`timeline.json`), the scenario that drove it, and the project's `render.*` +([ADR-0004](0004-recording-is-separate-from-rendering.md)). Fixing a typo in a +caption, moving a zoom from one step to another, retitling the outro, or +cutting a slow page load means editing the scenario or the config and running +the whole scenario again: the app, the browser, its timing. +`demoflow render ` (spec 255) re-renders without the browser, but only +with the project's *current* config, and only from the command line. + +The owner wants a timeline editor on the run page: captions (text and timing), +zoom per step, cards and style, and trimming with any number of cuts, previewed +in the browser and rendered by the machine that holds the recording. + +Two decisions stand in the way: + +- [ADR-0008](0008-cloud-boundary.md) §3 lists what the website may make a + Runner do: start a run of a committed scenario, cancel it, stream a video, + delete a run's artifacts. "Nothing else." Re-rendering is not on the list + (spec 255 names this in its Out of scope), and neither is reading or writing + anything in a run directory. +- ADR-0008 §2 lists what crosses to the cloud: a scenario's name and id, its + steps as action, locator and caption, stage statuses, durations, resolution, + file sizes, a failed step's error. Step times, target boxes and the + scenario's `description` are not on the list, and an editor cannot place a + caption or a zoom without them. + +## Decision + +1. **Edits are a file in the run directory: `runs//edits.json`.** + Its shape is `RunEditsSchema` in `@demoflow/core`: captions, zoom per + step, card text, background and window style, a trim and cuts. All times + are **timeline milliseconds** (the engine clock of `timeline.json`), never + output milliseconds, so an edit stays where it was put when the idle map, + the cards or a cut move the output around it. The file is optional; a run + without it renders exactly as it does today. Nothing else in the run + directory is ever written by an edit: `source.webm`, `timeline.json`, + `scenario.json` and the capture stages of `result.json` stay as recorded. +2. **The renderer applies the edits over the run's own inputs.** + `buildRenderPlan` reads `edits.json` beside `timeline.json`. An edit + replaces what the timeline and the config would have given for that one + thing (a caption list, a step's zoom, a card's text, the background, the + window, the time range); everything it does not name is unchanged. This + holds for `demoflow render` and for a re-render the website asks for. + - *Relation to [ADR-0012](0012-camera-directed-by-the-scenario.md):* the + camera still zooms only on a step, and only on a step whose event carries + a target box (§2). An edit may set, change or remove a step's `zoom` for + this run; it cannot zoom at an arbitrary time or on a region that is not + a step's target. ADR-0012's Consequences ("zoom at an arbitrary time + would be a new field, decided on its own") still hold. + - *Relation to ADR-0004 §4:* a failed run is still visibly failed. Edits + never remove the failure card or the watermark, and a trim or a cut can + never hide the failed step: the time range always ends on it. +3. **What the website may make a Runner do — two additions to ADR-0008 §3:** + - *read and write the edits of a run it reported:* the Runner answers with + the run's **edit model** (Decision 4) and saves or deletes `edits.json` + when asked; + - *re-render a run it reported*, with the project's current `render.*` + plus the run's edits, and report the new renders back. + + The run is named by its id and found through the Runner's own + `reported-runs.jsonl`, the same lookup `artifacts.delete` uses (spec 233). + Every other "nothing else" of §3 holds word for word: the website never + sends a scenario body, a command or a URL; the Runner validates `edits.json` + with `RunEditsSchema` before writing it, and an edit holds data only — + text, times, numbers, a background value — never a path, a URL, a locator + or a step. +4. **The edit model crosses live, and is never stored on the server.** + When the editor opens, the Runner sends, for that run: each event's step + index, action, start and end time, target box and `zoom`; captions and + scene titles (from steps and from the page, ADR-0014); the scenario's + `name` and `description`; the `render.*` style that would apply; the + current edits; and the current render's output-to-timeline time map, so + the browser can draw a preview over the video it already plays. This + extends ADR-0008 §2 by step times, target boxes and the description. It + still never carries `fill` values, URL query strings, locators beyond + what §2 already allows, logs, screenshots, traces or local paths. The API + relays it to the browser and keeps nothing; the run detail and the run + report are unchanged. When the Runner is offline, the editor says so and + shows nothing. +5. **The website never writes a file in the repository.** The scenario and + `demoflow.config.json` stay the person's. "Export" produces, on the Runner, + an RFC 6902 JSON Patch against the scenario file that touches only + `caption` and `zoom` of top-level steps, and a `render` fragment for the + config. The person applies it — `demoflow edits apply ` on the + machine, by hand, or through an agent — and commits it. Edits that a + scenario cannot express (a caption at a free time, a trim, a cut, a step + that came from a `repeat` or an `include`) are listed as not exportable, + with the reason. +6. **A re-render replaces the run's render files.** As `demoflow render` + does today (spec 255): `renders[]` and the `rendering` stage of + `result.json` change, the verdict never does. Resetting the edits deletes + `edits.json`, and the next render is the original. There are no render + versions. A shared copy (ADR-0019) is never replaced on its own: the + person updates it explicitly, which keeps ADR-0008 §5 ("nothing is + uploaded automatically"). + +## Consequences + +- **Cost: more crosses the boundary.** Step times and target boxes describe + the layout of the user's application (where a button is, how long a page + took). They cross only while the editor is open, only to the run's owner, + and are never stored; the cost is accepted for an editor that can place + anything at all. +- **Cost: the scenario's `description` crosses.** It is author-written text, + like a caption. ADR-0019 sends it with a share for the same reason. +- **Cost: the Runner does more work on the website's behalf.** A re-render + spends the machine's CPU and disk. It is bounded like a run: one render of a + run at a time, the daemon's 15-minute cap (spec 248), and only the formats + the website may already choose (ADR-0017). +- **Cost: the timeline contract grows a sibling.** `RunEditsSchema` is a + versioned contract of `@demoflow/core` like `TimelineSchema` (ADR-0004 + Consequences); changing it is a versioned change. +- An edited run and its scenario drift apart until the person exports and + commits. The next run of the scenario does not know the edits of the last. + The run page says which runs carry edits. +- A run recorded before edits existed is editable: the model is built from + `timeline.json`, which every run has. +- Editing needs the machine online, like playback (ADR-0009). diff --git a/docs/adr/0021-scheduled-checks.md b/docs/adr/0021-scheduled-checks.md new file mode 100644 index 00000000..be304d2a --- /dev/null +++ b/docs/adr/0021-scheduled-checks.md @@ -0,0 +1,107 @@ +# ADR-0021: Scheduled checks, and check passes started from the website + +Status: accepted · Date: 2026-10-26 · Extends: [ADR-0017](0017-website-run-options.md) §1 and §3 and [ADR-0008](0008-cloud-boundary.md) §3 (one more request: a check pass) + +## Context + +A demo is written once and goes stale silently: the application changes, a +locator stops matching, an assertion fails, and nobody runs the scenario +again until someone opens the video in the docs and sees it lie. The GitHub +Action covers pull requests of the repository that holds the scenarios; it +does not cover "the product moved, the demo stayed". + +The owner decided (interview of 2026-10-26, Phase 8) to check every scenario +of a project on a schedule and to mark a scenario **stale** on the website +when its check fails. Two places may hold a schedule: + +- **The website.** The person sets it on the project page. The API already + starts a run on the machine the project belongs to + ([ADR-0016](0016-website-started-runs.md), [ADR-0017](0017-website-run-options.md)). +- **`demoflow.config.json`.** The team commits it; the runner daemon on the + machine runs it. It works without the website. + +A scheduled check must not record or render: a pass a day of video files +fills the disk, and nobody watches a check. `demoflow run` has no mode +without recording today (`apps/cli/src/commands/run.ts`, `packages/engine/src/run.ts`). +ADR-0017 §6 says any new run option the website may choose takes a new ADR. + +## Decision + +1. **Check mode.** `demoflow run --check` runs the scenario's steps and its + verifications in a headless browser, and records nothing: no video, no + sync mark, no render. Its `result.json` is written as for any run, with + `recording` and `rendering` `skipped` and `renders: []`. The run status + follows from the stages as it does today (ADR-0004 §3–4): a failed + verification is a failed check. A check run is reported to the website like + any run, marked as a check. +2. **The website may start a check pass** of a registered project: a + request, beside `run.start`, whose only fields are the project's root (the + server's key into the machine's registry, ADR-0016 §3) and the ids of the + scenarios to leave out (ids from the scenario listing, ADR-0016 §1). The + daemon runs it as `demoflow run --check` over the project (Decision 3). It + takes no formats: a check renders nothing. This is the only new thing the + website may make a runner do, and it extends ADR-0008 §3 and ADR-0017 §1; + the rules of ADR-0017 §4 apply to it unchanged: a closed set of fields, + checked again on the machine, the whole request refused on anything + unknown. A machine says it accepts check passes in `launches.sync` before + it is sent one (ADR-0017 §5). Every "never" of ADR-0017 §3 still holds: + a check pass adds no command, URL, path or environment the website may + choose. +3. **A check covers the whole project.** One pass runs every scenario of the + project (`demoflow/**/*.demo.json`, ADR-0003 §2) except those the schedule + excludes, one after another, and starts the application from `devCommand` + once for the pass. Each scenario still gets its own run directory, its own + `result.json` and its own report. +4. **Two sources of a schedule; the config wins.** + - A `schedule` in `demoflow.config.json` is run by the runner daemon on the + machine, by its local clock. It needs no account: without one the + results are local (`demoflow runs`). When the machine is paired, the + daemon also reports the project's config schedule to the website, which + shows it read-only. + - A schedule set on the website is run by the API: at the due time it + starts a check pass on the project's machine through the runner socket, + with the request of Decision 2. + - A project whose config has a `schedule` cannot have a website schedule. + The API refuses to create one and, when a config schedule appears for a + project that already has a website schedule, the website schedule is + paused (kept, not run) and the page says why. + - *Why the config wins:* it is the team's committed decision, reviewed in + a pull request. A website setting that silently doubled or overrode it + would surprise the team. +5. **Cadence.** A schedule is one of `daily`, `weekdays` or `weekly` + (with a weekday), at `HH:MM` in the machine's local time zone. Nothing more + frequent than once a day. A machine that was off or asleep at the due time + runs **one** catch-up pass when it is next able to (the API: when the + machine reconnects; the daemon: when it starts or wakes), never one per + missed slot. +6. **Stale is a per-scenario state on the server.** A scenario is stale + when the last reported run of it in the project failed, for any reason + (readiness, execution, verification). Checks and ordinary runs both count. + The website shows a badge on the project and the scenario, and a block on + `/app`. It changes only on a transition (passed → failed: stale; failed → + passed: fixed). Alerts are on the website only: no email, no webhook. +7. **What crosses to the cloud** is what ADR-0008 §2 already allows for a + run, plus: that a run was a check, and the project's config schedule + (cadence, time, time zone name, the excluded scenario ids). No new step + data, no logs, no screenshots. + +## Consequences + +- A check pass costs the machine one application start and one headless + browser session per scenario, once a day at most. It costs no disk beyond + `result.json` and the timeline per run. +- The daemon must be running for a config schedule to fire; a machine with + no autostart unit checks nothing. Today the daemon refuses to start without + credentials (`apps/cli/src/runner/daemon.ts`); spec 361 adds a local mode + for the scheduler. A machine without an account runs scheduled checks but + no website ever sees them. +- Website schedules run only while the machine is online; the website says + "next check when the machine is online" instead of pretending a check ran. +- A project on two machines is two `Project` rows (`@@unique([runnerId, rootPath])`); + each has its own schedule and its own stale state. +- Check runs appear in the run library like any run, with a "check" label and + no video. A user who prunes runs prunes them too. +- Adding another alert channel (email, webhook) later is a spec, not an ADR: + it adds no crossing of the cloud boundary. Making checks more frequent than + daily, or letting the website choose anything else about a run, takes a new + ADR (ADR-0017 §6). diff --git a/docs/adr/README.md b/docs/adr/README.md index 54d38a68..48308806 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -23,3 +23,6 @@ it is accepted: a later record supersedes it and says so. | [0016](0016-website-started-runs.md) | Runs started from the website: scenario listing (ids and names), a registered project is a root the machine reported a run from | accepted; §4 superseded by 0017 | | [0017](0017-website-run-options.md) | The website may choose the output formats of a run it starts (formats only; always headless) | accepted | | [0018](0018-fragments-and-off-camera-steps.md) | Step fragments (`include`) are inlined at load time; off-camera steps (`setup`, `record: false`) are an unrecorded prefix run in its own context | accepted | +| [0019](0019-opt-in-share-links.md) | Opt-in share links: one render uploaded to the server on an explicit share, unlisted link with an optional password | accepted; supersedes the roadmap's Phase 5 "no public share links", extends 0008 §2–§3 | +| [0020](0020-edits-from-the-website.md) | The website may send a run's edits as data and ask its runner to re-render it; edits live in the run directory | accepted; extends 0008 §3 | +| [0021](0021-scheduled-checks.md) | Scheduled checks from the website and the project config; check mode runs without recording | accepted; extends 0017 | diff --git a/docs/product/roadmap.md b/docs/product/roadmap.md index d50728f5..28104a23 100644 --- a/docs/product/roadmap.md +++ b/docs/product/roadmap.md @@ -18,6 +18,8 @@ that contradicts this file wins, and this file is updated with it. 6. **Phase 5 — Website and Runner pairing.** 7. **Phase 6 — Luna Player.** 8. **Phase 7 — Optional SDK.** +9. **Phase 8 — Share, edit, keep fresh** (below): sharing first, then the + website editor, then scheduled checks. The release branch flow applies from the first phase completed after this file lands; the GitHub Action follows the npm release whenever the queue allows. @@ -86,10 +88,11 @@ lands; the GitHub Action follows the npm release whenever the queue allows. - **Order**: sign-in → Runner pairing ([ADR-0007](../adr/0007-runner-pairing-and-connection.md)) → projects → demo library. -- **No public share links.** Videos stay on the user's machine (ADR-0008) and - play through the relay +- **No public share links** in this phase. Videos stay on the user's machine + (ADR-0008) and play through the relay ([ADR-0009](../adr/0009-playback-relay-and-luna-player-adapter.md)). Sharing - is by file or through the GitHub Action. + is by file or through the GitHub Action. *Superseded in Phase 8 by + [ADR-0019](../adr/0019-opt-in-share-links.md).* - **Language**: English UI, with strings in an i18n dictionary from the start. - **A simple public landing page**: what DemoFlow is, a demo video made with DemoFlow, "Install" (`npx demoflow`) and "Sign in"; documentation as its own @@ -167,6 +170,29 @@ All four, in this order: [224](../specs/224-record-wait-for-ready.md) (a "Wait for ready" control in the `demoflow record` panel, spec 198's follow-up). +## Phase 8 — Share, edit, keep fresh + +Decided by the owner in an interview on 2026-10-26. Voiceover (TTS, music) and +a render matrix (theme × locale × device) are **later**, not in this phase. + +- **Sharing** ([ADR-0019](../adr/0019-opt-in-share-links.md)): an explicit, + per-video upload of one chosen render to the server's disk, behind an + unlisted link `/s/` with an optional password; 7 / 30 (default) / 90 + days, extendable; 200 MB per file and 2 GB per user. Entry points: the run + page, `demoflow share`, and the MCP `share_demo` tool, which is refused until + the project config sets `share.allowMcp: true`. Specs: #347–#352. +- **Editor** ([ADR-0020](../adr/0020-edits-from-the-website.md)): captions, + per-step zoom, cards and style, free trimming and cuts, edited on the run + page with an in-browser preview; the edits live in `runs//edits.json` + on the machine and are exported as a patch the person commits. Specs: + #353–#359. +- **Scheduled checks** ([ADR-0021](../adr/0021-scheduled-checks.md)): + `demoflow run --check`, schedules on the website and in + `demoflow.config.json` (the config wins), one catch-up run, a stale badge on + the website when a scenario goes from passed to failed. Specs: #360–#364. +- **Hold the result** (#365): `render.endHoldMs` and a per-step `hold`, so a + demo shows what its last action did. + ## Cross-cutting - **npm release** — the luna-player pattern diff --git a/docs/specs/347-share-storage-api.md b/docs/specs/347-share-storage-api.md new file mode 100644 index 00000000..ae7ecd72 --- /dev/null +++ b/docs/specs/347-share-storage-api.md @@ -0,0 +1,309 @@ +# Share a run's video: the Share model, disk storage, upload through the runner socket + +Issue: [#347](https://github.com/AndreyBegma/DemoFlow/issues/347) +Depends on: nothing. Implements [ADR-0019](../adr/0019-opt-in-share-links.md). + +## Summary + +[ADR-0019](../adr/0019-opt-in-share-links.md) lets a person share one render +of a run through a link that works without an account. This slice is the +API's half of creating, listing, extending and revoking a share: the `Share` +table, the directory the shared files live in, the upload that pulls one +render and a poster from the owning runner over its existing socket, the +per-file and per-user limits, and the deletes that cascade from a run, a +project and an account. The public page and file (#348), the daemon's side +(#349) and the website (#350, #351) build on it. + +## Scope + +### In scope + +- `apps/api/prisma/schema.prisma`: the `Share` model and `ShareStatus` enum; + `User.shares` and `Run.shares` relations. +- `apps/api/prisma/migrations/20261027090000_shares/migration.sql` (new). +- `apps/api/src/shares/` (new module): `shares.module.ts`, + `shares.controller.ts` (session), `runner-shares.controller.ts` (device + token), `shares.dto.ts`, `shares.service.ts`, `share-storage.ts` (the + directory), `share-upload.service.ts` (the pull), `share-sweeper.ts`, and + their specs. +- `apps/api/src/runner/runner-socket.ts`: `share.prepare` (server → daemon), + `share.prepared` / `share.error` (daemon → server), `asset` on + `video.open`, `features` on `launches.sync`. +- `apps/api/src/runner/runner-connections.service.ts`: store a connection's + `features`; route `share.*` answers. +- `apps/api/src/videos/video-relay.service.ts`: a file sink beside the HTTP + response sink, so an upload reuses streams, credit and timeouts. +- `apps/api/src/videos/runs.service.ts`: `machine.features` on the run page; + after `remove`, delete the removed shares' directories. +- `apps/api/src/projects/projects.service.ts`: the same after a project + delete and a bulk run delete. +- `apps/api/src/users/account.service.ts`: the same after an account delete. +- `apps/api/src/app.module.ts`: register `SharesModule`. +- `apps/api/.env.example`, `deploy/staging/env/api.env.example`: the share + variables (Configuration). +- `deploy/staging/docker-compose.yml`: the `shares` volume on `api`. +- `apps/api/Dockerfile`: create `/data/shares` owned by `node` before + `USER node`, so the named volume is writable. +- `deploy/README.md`: the shares volume, its limits, and that it is not + backed up. + +### Out of scope + +- `GET /s/:token`, the file, the poster, the password unlock and the view + counter (#348). +- The daemon's answer to `share.prepare`, the poster, `demoflow share` and + the MCP tool (#349). +- Every web page (#350, #351). +- Replacing the file of an existing share after a re-render: #356 adds + `POST /shares/:id/update` inside `apps/api/src/shares/**` after this + merges (ADR-0020 §6; ADR-0019, Consequences). Keep the upload in + `share-upload.service.ts` callable for an existing share so #356 reuses it. +- `deploy/production/`: it does not exist on `develop` yet [Confirmed]; it is + #289's. Whichever of #289 and this slice merges second adds the `shares` + volume and variables there too (Risks). +- Changing a share's password after creation (Open questions). + +## Decisions + +1. **Table.** [Source: ADR-0019 §4–5] + + ```prisma + enum ShareStatus { + uploading + ready + failed + lost + } + + model Share { + id String @id @default(cuid()) + // 32 random bytes, base64url (`generateToken`). Stored as is: the owner + // copies the link again (ADR-0019, Consequences). + token String @unique + userId String + user User @relation(fields: [userId], references: [id], onDelete: Cascade) + runId String + run Run @relation(fields: [runId], references: [id], onDelete: Cascade) + format String + status ShareStatus @default(uploading) + // The scenario's name at share time, and what the daemon sent (#349). + title String + description String? + // `[{ title, atMs }]`, at most 100. + chapters Json @default("[]") + sizeBytes Int @default(0) + posterBytes Int @default(0) + width Int? + height Int? + durationMs Int? + // argon2id (`PasswordHasher`), null without a password. + passwordHash String? + expiresAt DateTime + views Int @default(0) + failure String? + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@unique([runId, format]) + @@index([userId, createdAt(sort: Desc)]) + @@index([expiresAt]) + } + ``` + + - `token` comes from `generateToken()` in `apps/api/src/auth/tokens.ts` + [Confirmed: it exists]. + - `@@unique([runId, format])`: **one share per run and format.** Creating + a second answers `409 share-exists` with the existing id; the website + shows the existing link instead. + - `sizeBytes` is an `Int`: the 200 MB file limit is far below 2³¹. + - `runId` cascades: deleting the run on the website deletes the share + (ADR-0019 §5). `userId` cascades: deleting the account deletes them all. +2. **Storage.** `ShareStorage` owns one directory, `SHARE_DIR`. A share's + files are `//file.` (`ext` is `mp4`, `gif` or + `webm` from the format) and `//poster.jpg`. Bytes are + written to `.part` and renamed when the stream ends with the size + its head announced; anything else deletes the `.part`. Ids are cuids from + the database, never a string from a request, so no path is built from + input. +3. **Limits.** [Source: owner, Phase 8 interview] `SHARE_MAX_FILE_BYTES` + (default 209 715 200, 200 MB) and `SHARE_USER_QUOTA_BYTES` (default + 2 147 483 648, 2 GB). The quota counts `sizeBytes + posterBytes` of the + user's shares in `uploading` and `ready`. Both are checked **before** the + upload against the size in the run's `renders` (`Run.renders`, spec #263 + [Confirmed]) and **again** against the size the daemon's `video.head` + announces; a head over either limit cancels the stream (`video.cancel`) + and fails the share with `file-too-large` / `quota-exceeded`. +4. **Upload: the API pulls.** [Source: owner, "WebSocket, the relay's + chunk protocol"; ADR-0019 §3] After the row is created (`uploading`): + 1. The API sends `share.prepare { requestId, runId, format }` and waits up + to 30 s for the answer. + 2. The daemon answers `share.prepared { requestId, description?, + chapters, posterSize }` or `share.error { requestId, code }` + (`not-found`, `no-render`, `io`; any string ≤ 64, as `video.error`). + `description` ≤ 2 000 characters; `chapters` ≤ 100 entries of + `{ title ≤ 200 characters, atMs ≥ 0 integer }`; `posterSize` ≤ 1 MB. + 3. The API opens `video.open { streamId, runId, format, range: null, + asset: 'poster' }` into a file sink, then `video.open { streamId, + runId, format, range: null }` for the render. Both use + `VideoRelay`'s existing head timeout, chunk timeout, credit and + acknowledgements (`VIDEO_CHUNK_MAX`, `VIDEO_CREDIT`, spec #191 + [Confirmed]); the file sink acknowledges a chunk once it is written. + Uploads count against `MAX_STREAMS_PER_RUNNER` like playback. + 4. Both files complete: `status = ready`, sizes and the render's + `width`, `height`, `durationMs` (from `Run.renders`) stored. Any + failure: `status = failed`, `failure = `, files deleted, quota + released. + + `asset` is sent only to a daemon that announced `share` (Decision 6), so + a daemon that does not know the field never receives it. +5. **Lifetime.** `expiresInDays` is `7`, `30` or `90`, default `30`. + `POST /shares/:id/extend` sets `expiresAt = min(max(expiresAt, now) + 30 + days, now + 90 days)`; a share already at the cap answers `409 + at-max-expiry`. [Source: owner, Q8] +6. **Capability.** `launches.sync` carries `features?: string[]` + (`ArrayMaxSize(8)`, each ≤ 32), next to `runOptions` (spec #325 + [Confirmed]) — one capability list shared with the editor, which adds + `edits` (ADR-0020). Whichever of this slice and #355/#356 lands first adds + the field; the other appends its string. The API keeps the strings it + knows per connection; this slice knows `share`. A share for a machine without `share` answers + `409 runner-outdated`; an offline machine `409 runner-offline`. The run + page's `machine` gains `features: string[]` beside `runOptions`. + [Source: ADR-0019 §7] +7. **Who may create.** The website: the run's owner, through the session. + The CLI and MCP (#349): `POST /runner/shares` with the device token + (`RunnerTokenGuard` [Confirmed]); the run must be one **this** runner + reported (`Run.runnerId`). The MCP rule (`share.allowMcp`) is enforced by + the CLI on the machine, where the config is; the API cannot tell an MCP + call from a CLI call and does not try. +8. **Password.** Optional, 8–128 characters, hashed with `PasswordHasher` + (argon2id, ADR-0006 [Confirmed]) and never returned. Unlocking is #348. +9. **Deletes.** [Source: owner, Q13; ADR-0019 §5] + - `DELETE /shares/:id` deletes the row and the directory. + - Run delete (`RunsService.remove`), bulk run delete and project delete + (`ProjectsService`), and account delete (`AccountService.delete`) + delete the rows through the cascades; after the transaction commits + each deletes the directories of the share ids it collected first. + - `ShareSweeper`, every 10 minutes and once on boot: deletes expired + shares and their directories; deletes any directory under `SHARE_DIR` + with no row (the backstop for every cascade); fails `uploading` rows + older than 15 minutes (`failure = 'timed-out'`). On boot it also marks + `ready` rows whose `file.` is missing as `lost`. + - Deleting a run's artifacts on the machine (`DELETE /runs/:id/artifacts`) + does **not** touch its shares. +10. **Logging.** As the run delete does (spec #263, Decision 7): event, + share id, run id, outcome. Never the token, the password, the title or + the description. + +## API + +All under the session (`SessionGuard`) unless marked. Bodies are DTOs with +`class-validator` decorators; the global `ValidationPipe` rejects unknown +fields. + +| Method and path | Body | Answer | +|---|---|---| +| `POST /shares` | `{ runId: uuid, format: RunFormat, expiresInDays?: 7 \| 30 \| 90, password?: string }` | `202 ShareView` (`status: uploading`) | +| `GET /shares` | — | `200 { shares: ShareView[], quota: { usedBytes, limitBytes, maxFileBytes } }`, newest first | +| `GET /shares/:id` | — | `200 ShareView` | +| `POST /shares/:id/extend` | — | `200 ShareView` | +| `DELETE /shares/:id` | — | `204` | +| `POST /runner/shares` (device token) | as `POST /shares` | `202 ShareView` | +| `GET /runner/shares/:id` (device token) | — | `200 ShareView` | + +`ShareView`: `{ id, url, fileUrl, runId, projectId, title, format, status, +failure, sizeBytes, width, height, durationMs, hasPassword, views, expiresAt, +createdAt }`. `url` is `${WEB_URL}/s/`; `fileUrl` is +`${WEB_URL}/s//file`, or `null` while a password is set. + +Errors (`{ error }`, as the runs API): `404 not-found` (no such run or share +for this user — never "forbidden"), `409 format-not-rendered`, `409 +artifacts-deleted`, `409 runner-offline`, `409 runner-outdated`, `409 +share-exists` (with `shareId`), `413 file-too-large` (with `maxFileBytes`), +`409 quota-exceeded` (with `usedBytes`, `limitBytes`), `409 at-max-expiry`. + +## Configuration + +| Variable | Default | Where | +|---|---|---| +| `SHARE_DIR` | `./data/shares` (relative to the API's working directory) | `apps/api/.env.example`; staging `/data/shares` | +| `SHARE_MAX_FILE_BYTES` | `209715200` | both examples | +| `SHARE_USER_QUOTA_BYTES` | `2147483648` | both examples | + +`deploy/staging/docker-compose.yml`: a named volume `shares` mounted at +`/data/shares` on `api`, and `SHARE_DIR: /data/shares` in its environment. +`.gitignore` gains `apps/api/data/` if it is not covered [Unknown]. + +## Acceptance criteria + +- [ ] The migration `20261027090000_shares` applies on an empty database and + on `develop`'s schema; `prisma migrate dev` reports no drift. +- [ ] With a fake daemon that announced `share` (`runner-socket.fixtures.ts`): + `POST /shares` answers 202, the daemon receives `share.prepare`, then a + poster `video.open` with `asset: 'poster'`, then the render's + `video.open`; after both streams end, `GET /shares/:id` is `ready` and + both files exist under `SHARE_DIR//` with the announced sizes. +- [ ] A daemon without `share` in `launches.sync` gets nothing and the + request answers `409 runner-outdated`; an offline machine `409 + runner-offline`. +- [ ] A render whose size in `Run.renders` exceeds `SHARE_MAX_FILE_BYTES` + answers 413 before any message is sent; a `video.head` over the limit + cancels the stream and fails the share with `file-too-large`, leaving + no file. +- [ ] A share that would push the user over `SHARE_USER_QUOTA_BYTES` + answers `409 quota-exceeded`; deleting a share frees its bytes for the + next one. +- [ ] `share.error`, a head timeout and a dropped socket each leave the share + `failed` with no `.part` file. +- [ ] `POST /shares/:id/extend` follows Decision 5, including the 90-day cap. +- [ ] **Authorization:** user B gets `404` for `GET`, `POST …/extend` and + `DELETE` on user A's share, `GET /shares` never lists A's shares, and + `POST /shares` with A's run id answers `404`. A device token of B's + machine cannot share a run reported by A's machine, nor a run of B's + reported by another of B's machines. +- [ ] Deleting the run (single and bulk), its project, or the account deletes + the share rows and, once the call returns, their directories. +- [ ] `DELETE /runs/:id/artifacts` leaves the run's shares `ready`. +- [ ] The sweeper deletes expired shares and orphan directories, fails stale + `uploading` rows, and marks a `ready` share whose file is gone as + `lost`. +- [ ] No log line contains a token, a password, a title or a description. +- [ ] `bun run check`, `bun run build`, `bun run test` pass. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i347-api | the whole slice | apps/api/prisma/schema.prisma, apps/api/prisma/migrations/20261027090000_shares/**, apps/api/src/shares/**, apps/api/src/runner/runner-socket.ts, apps/api/src/runner/runner-connections.service.ts, apps/api/src/runner/runner-socket.fixtures.ts, apps/api/src/videos/video-relay.service.ts, apps/api/src/videos/runs.service.ts, apps/api/src/projects/projects.service.ts, apps/api/src/users/account.service.ts, apps/api/src/app.module.ts, apps/api/.env.example, apps/api/Dockerfile, deploy/staging/docker-compose.yml, deploy/staging/env/api.env.example, deploy/README.md | — | yes | opus | + +One slot: the schema, the protocol and the relay's sink are one design and +cannot be reviewed apart. + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| apps/api/prisma/schema.prisma | i347-api | #362 adds a distinct table (`Schedule`): an append, keep both | +| apps/api/src/runner/runner-socket.ts, runner-connections.service.ts | i347-api | #356 and #362 also add messages; cut after this merges | +| apps/api/src/videos/video-relay.service.ts | i347-api | do not open it | +| deploy/staging/docker-compose.yml, deploy/staging/env/api.env.example | i347-api | #289 may copy them into deploy/production/; #348 adds one variable after this merges | + +## Risks + +- **Disk fills on the shared host** (medium). The quota bounds each user, not + the number of users. Mitigation: limits in env, expiry ≤ 90 days, `status.sh` + can be extended to print the volume's size; watch it after launch. +- **#289 lands production without the volume** (medium). Mitigation: the + second of the two to merge adds `shares` to `deploy/production/`; the + reviewer of the second checks it. +- **Upload competes with playback** (low). Both use the runner's four + streams; a fifth is `busy`. Mitigation: an upload failing `busy` fails the + share with `runner-busy`; the person tries again. +- **The stored token** (low). A database leak exposes live links. Mitigation: + expiry, revocation, optional password (ADR-0019, Consequences). + +## Open questions + +- Changing or removing a share's password after creation — default: not in + this slice; revoke and share again. +- One share per run and format — default: yes (Decision 1); several links for + one file is a later change if asked. diff --git a/docs/specs/348-share-public-endpoints.md b/docs/specs/348-share-public-endpoints.md new file mode 100644 index 00000000..6a1ac148 --- /dev/null +++ b/docs/specs/348-share-public-endpoints.md @@ -0,0 +1,156 @@ +# Public share endpoints: page data, file, poster, password, views, expiry + +Issue: [#348](https://github.com/AndreyBegma/DemoFlow/issues/348) +Depends on: #347. Implements [ADR-0019](../adr/0019-opt-in-share-links.md) §5. + +## Summary + +#347 stores a share; nobody can open it yet. This slice adds what a viewer +without an account reaches: the share page's data (`GET /s/:token`), the +file and the poster (`/s/:token/file`, `/s/:token/poster`) with byte ranges, +the password unlock with a rate limit, the view counter, and expiry enforced +on every request. The page that renders it is #351. + +## Scope + +### In scope + +- `apps/api/src/shares/public-shares.controller.ts` (new, no session guard), + `public-shares.service.ts`, `share-access.ts` (the unlock cookie), their + specs, and their registration in `apps/api/src/shares/shares.module.ts`. +- `apps/api/src/auth/auth-throttle.ts`: the `share-unlock` throttler. +- `apps/api/.env.example`, `deploy/staging/.env.example`, + `deploy/staging/docker-compose.yml`, `deploy/staging/refresh.sh`: + `SHARE_SIGNING_SECRET`. +- `deploy/staging/Caddyfile`: route `/s//file` and `/s//poster` + to the API. +- `apps/web/next.config.ts`: the same two paths rewritten to the API locally. +- `deploy/README.md`: the route and the secret. + +### Out of scope + +- The page `/s/[token]` itself and its password form (#351). +- Owner endpoints and storage (#347). +- `deploy/production/` (#289; the second to merge mirrors the Caddy route and + the secret, as #347 says for the volume). +- Embedding through an iframe (the owner chose page + direct file, Q6). + +## Decisions + +1. **URLs.** [Source: owner, Q6] The share page is `${WEB_URL}/s/` (a + Next page, #351). Its data is `GET /api/s/:token` — the API route + `GET /s/:token` behind Caddy's `/api` prefix strip [Confirmed: + `deploy/staging/Caddyfile`]. The file and the poster live **on the page's + own path**, so a link reads well in a README: `${WEB_URL}/s//file` + and `${WEB_URL}/s//poster`. Caddy sends exactly those two paths to + the API unchanged (`path_regexp ^/s/[A-Za-z0-9_-]{43}/(file|poster)$`, + before the `web` handler); `next.config.ts` adds the same rewrite for + local development. The API routes are therefore `GET /s/:token`, + `GET|HEAD /s/:token/file`, `GET|HEAD /s/:token/poster`, + `POST /s/:token/unlock`. +2. **What a share answers.** + + | Share state | `GET /s/:token` | file / poster | + |---|---|---| + | unknown token, `uploading`, `failed` | `404 not-found` | `404` | + | `ready`, expired (`expiresAt ≤ now`, not yet swept) | `410 expired` | `410` | + | `lost`, or `ready` but the file is missing (marks it `lost`) | `410 unavailable` | `410` | + | `ready`, password set, no valid unlock cookie | `200 { locked: true }` | `403 locked` | + | `ready`, no password, or a valid cookie | `200 ShareData` | `200` / `206` | + + A locked answer carries nothing about the video — not the title, not the + size. Expiry is checked on every request; the sweeper (#347) only cleans up. +3. **`ShareData`:** `{ title, description, chapters, format, kind: + 'video' | 'image', width, height, durationMs, sizeBytes, expiresAt, + fileUrl, posterUrl, downloadUrl }`. `kind` is `image` for the three GIF + formats. `fileUrl` and `posterUrl` are the Decision 1 paths; + `downloadUrl` is `fileUrl + '?download=1'`. +4. **The file.** Byte ranges through `apps/api/src/videos/byte-range.ts` + [Confirmed], `Content-Type` from `VIDEO_CONTENT_TYPES` + (`video-relay.service.ts` [Confirmed]), `Content-Disposition: inline`, + or `attachment` with `download-name.ts`'s name for `?download=1` + [Confirmed]. Without a password: `Cache-Control: public, max-age=300` and + `Cross-Origin-Resource-Policy: cross-origin`, so the file embeds in + another site (helmet's default is `same-origin`). With a password: + `Cache-Control: private, no-store`, CORP left at `same-origin`. + [Source: ADR-0019 §5, "the direct file URL works only for shares without a + password"] +5. **Unlock.** `POST /s/:token/unlock { password }` (8–128 characters) checks + with `PasswordHasher.verify` [Confirmed]. Right: `204` and a cookie + `df_share_`, `HttpOnly`, `Secure` (except in development), + `SameSite=Lax`, `Path=/`, `Max-Age` 12 hours, whose value is + `.` with `hmac = HMAC-SHA256(SHARE_SIGNING_SECRET, share.id + + exp + passwordHash)`. Including the hash means a later password change + would void old cookies. Wrong: `401 wrong-password`. The global origin + check covers this POST [Confirmed: `security/origin-check.ts`]. +6. **Rate limit.** A `share-unlock` throttler in `auth-throttle.ts`, + following its pattern [Confirmed]: 10 attempts per 10 minutes per IP and + token, off by default and switched on only for the unlock route. Over the + limit: `429`. +7. **Views.** [Source: owner, Q10] `GET /s/:token` adds 1 to `views` with an + atomic `update … increment` each time it returns `ShareData`. File, poster + and locked answers do not count. Nothing about the viewer is stored or + logged — no IP, no user agent, no referrer. Page loads by link unfurlers + count; that is accepted. +8. **`SHARE_SIGNING_SECRET`.** At least 32 characters. Production + (`APP_ENV=production`) refuses to start without it and names the variable, + as the mail check does [Confirmed: `apps/api/.env.example`]. Development + without it uses a random value per boot (unlock cookies end at restart). + Staging generates it: `deploy/staging/.env.example` gains an empty + `SHARE_SIGNING_SECRET=`, `refresh.sh` fills it like `POSTGRES_PASSWORD` + [Confirmed: `fill_if_empty`], and `docker-compose.yml` passes it to `api`. + +## Acceptance criteria + +- [ ] `GET /s/:token` answers each row of the Decision 2 table, checked with a + row per state in an integration spec. +- [ ] A locked answer's JSON has exactly one key, `locked`. +- [ ] `GET /s/:token/file` with `Range: bytes=0-99` answers `206` with 100 + bytes and `Content-Range`; `?download=1` answers `attachment`; a GIF + share answers `image/gif`. +- [ ] Without a password the file carries `Cross-Origin-Resource-Policy: + cross-origin` and `Cache-Control: public, max-age=300`; with a password + and no cookie it answers `403 locked`, and with the cookie from a right + unlock it answers `200`. +- [ ] Wrong passwords answer `401`; the 11th attempt within 10 minutes from + one IP for one token answers `429`; a cookie signed for share A does not + open share B. +- [ ] `views` grows by one per unlocked `GET /s/:token` and not on file, + poster or locked requests; no log line holds an IP or a token. +- [ ] A share whose `expiresAt` passed answers `410 expired` before the + sweeper ran. +- [ ] **Authorization:** the public endpoints never return a share by id, a + user id, a run id or a project id; only the token opens a share, and a + token of one share never reaches another's file. +- [ ] Locally (`bun run start:dev`), `http://localhost:3670/s//file` + plays through the Next rewrite; on staging the same path is answered + by the API through Caddy. +- [ ] The API refuses to start with `APP_ENV=production` and no + `SHARE_SIGNING_SECRET`. +- [ ] `bun run check`, `bun run build`, `bun run test` pass. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i348-public | the public endpoints | apps/api/src/shares/public-shares.*, apps/api/src/shares/share-access.*, apps/api/src/shares/shares.module.ts, apps/api/src/auth/auth-throttle.ts, apps/api/.env.example, apps/web/next.config.ts, deploy/staging/Caddyfile, deploy/staging/.env.example, deploy/staging/docker-compose.yml, deploy/staging/refresh.sh, deploy/README.md | #347 | yes | sonnet | + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| deploy/staging/** | i348-public after #347 merged | #289 mirrors into deploy/production/ | +| apps/web/next.config.ts | i348-public | do not open it | +| apps/api/src/shares/shares.module.ts | i348-public after #347 | do not open it | + +## Risks + +- **Caddy regex out of step with the token format** (low). A different token + length breaks the route. Mitigation: the length comes from + `generateToken()`; a spec asserts the token matches the Caddy pattern. +- **Unfurlers inflate views** (low). Accepted (Decision 7). + +## Open questions + +- A password change endpoint — default: none (#347, Open questions); the + cookie format already supports it. diff --git a/docs/specs/349-cli-share.md b/docs/specs/349-cli-share.md new file mode 100644 index 00000000..23b5e4d4 --- /dev/null +++ b/docs/specs/349-cli-share.md @@ -0,0 +1,182 @@ +# The runner uploads a render for a share; `demoflow share` and the MCP `share_demo` tool + +Issue: [#349](https://github.com/AndreyBegma/DemoFlow/issues/349) +Depends on: #347. Implements [ADR-0019](../adr/0019-opt-in-share-links.md) §2, §3, §6, §7. + +## Summary + +#347 defines how the API pulls a shared file: `share.prepare`, then a +poster stream and the render's stream over the runner socket. This slice is +the machine's side. The daemon announces `share`, answers `share.prepare` +with the scenario's description, the render's chapters and a poster it makes +with FFmpeg, and serves the poster through the relay. The renderer starts +writing chapters into `result.json` so there is something to answer with. +On top of that, `demoflow share ` creates a share from the terminal, +and the MCP server gains `share_demo`, refused unless the project's committed +config says `share.allowMcp: true`. + +## Scope + +### In scope + +- `packages/core/src/run-result.ts`: optional `chapters` on + `RenderOutputSchema`. +- `packages/core/src/project-config.ts`: the optional `share` block; + `packages/core/schemas/project-config.schema.json` regenerated with + `bun run --filter @demoflow/core schema` (`scripts/generate-schemas.ts` + [Confirmed]). +- `packages/renderer/src/renderer.ts` (and the plan code that knows the + placed scene cards): write `chapters` per render. +- `apps/cli/src/runner/connection.ts`: `features: ['share']` in + `launches.sync`; route `share.prepare`. +- `apps/cli/src/runner/share/` (new): `prepare.ts` (description, chapters, + poster), `poster.ts` (FFmpeg). +- `apps/cli/src/runner/relay/index.ts`: serve `asset: 'poster'`. +- `apps/cli/src/commands/share.ts` (new) and `apps/cli/src/main.ts`: the + `share` command. +- `apps/cli/src/mcp/server.ts` (and `tasks.ts` / `project.ts` as needed): + `share_demo`. +- `apps/cli/test/**`: tests, Vitest under Node. +- `apps/cli/README.md`: the command, the tool and `share.allowMcp`. + +### Out of scope + +- The API (#347, #348) and the website (#350–#352). +- Website docs pages (#352). +- Re-uploading after a re-render (#356). + +## Decisions + +1. **Chapters are written at render time.** `RenderOutputSchema` gains + `chapters: z.array(z.strictObject({ title: NonEmptyString ≤ 200, atMs: + int ≥ 0 })).max(100).optional()`. The renderer fills it for every render + from the scene cards the plan placed — the scenario's `scene` markers and + the page's scenes (ADR-0014) alike — with each card's start in **output** + time. A run rendered before this slice has no `chapters`; its share has + none. [Unknown: which plan value carries the placed cards to + `recordRender`; `packages/renderer/src/plan/cards.ts` places them + (`PlacedCard`, kind `scene` [Confirmed]).] + - *Why in `result.json`:* the output time of a scene depends on cards, + cuts and idle trimming; the renderer is the only place that knows it, + and recomputing a plan at share time would use today's config, not the + render's. +2. **`share.prepare` on the daemon.** `{ requestId, runId, format }`, with + `runId` the server's id, looked up with `findReportedRun` + (`apps/cli/src/runs-report/reported-runs.ts` [Confirmed]) exactly as the + relay does. Then: + - no entry, no `result.json` that parses, or no render of `format` whose + file exists → `share.error { code: 'not-found' | 'no-render' }`; + - `description`: the scenario's, read from `/` the + way `demoflow render` reads it (spec 255, Decision 3 [Confirmed: + `apps/cli/src/commands/render.ts`]); absent when the file is gone or does + not load; + - `chapters`: the render's `chapters`, or `[]`; + - the poster (Decision 3); its size is `posterSize`. + - Answer `share.prepared { requestId, description?, chapters, posterSize }`. + Only these fields; never a path. FFmpeg failing → `share.error { code: + 'io' }`. +3. **Poster.** One JPEG frame of the render at `min(1500, ⌊durationMs / 2⌋)` + ms, scaled to at most 1280 px wide keeping the aspect, `-q:v 4`, written to + `/share/poster-.jpg` and reused while it is newer than the + render's file. FFmpeg is the renderer's (`resolveFfmpeg` / `runFfmpeg`, + exported from `@demoflow/renderer` [Confirmed]). A poster over 1 MB is + `io`. GIF renders get a poster too. +4. **`asset: 'poster'` on `video.open`.** The relay serves + `/share/poster-.jpg` for it, with the same checks as a + render (the run is reported, the format is a `RENDER_FORMATS` member) and + the same chunking and credit. An unknown `asset` value is `not-found`. +5. **Capability.** `launches.sync` carries `features: ['share']` (#347, + Decision 6). +6. **`demoflow share`.** + + ``` + demoflow share [--format ] [--expires <7|30|90>] [--password] [--json] + ``` + + plus a hidden `--project `, like `render`. + - `` is the local run id, resolved to a run directory as `demoflow + render` does (spec 255, Decisions 1–2 [Confirmed]); the server id comes + from the reported-runs index by run directory + (`readReportedRunsByDir` [Confirmed]). + - `--format` defaults to the run's first render; `--expires` to 30. + - `--password` asks for it without echo on a terminal; without a terminal + it reads `DEMOFLOW_SHARE_PASSWORD`. A password is never a flag value + (shell history). + - It calls `POST /runner/shares` with the stored device token, then polls + `GET /runner/shares/:id` every second for up to 10 minutes, printing + progress on stderr, and prints the link (and the file link when there is + no password). `--json` prints the `ShareView`. + - Refusals are `CommandError`s, exit 2: `not-logged-in` (no credentials: + "run demoflow login"), `run-not-found`, `run-not-reported` (the run was + made signed out or with reporting off), `format-not-rendered`, + `runner-offline` ("start the runner: demoflow runner start"), + `runner-outdated` ("restart the runner"), `file-too-large`, + `quota-exceeded` (with used and limit). `share-exists` is not an error: + it prints the existing link and says so. An upload that ends `failed` + exits 1 with its `failure`. +7. **`share_demo` (MCP).** Input `{ runId, format?, expiresInDays? }`, no + password. It does what `demoflow share` does and returns `{ shareId, url, + fileUrl, expiresAt }`. **Refused with `share-not-allowed`** unless the + `demoflow.config.json` of the run's project root has `share.allowMcp: + true`. The root is the reported run's `root` [Confirmed: `ReportedRun.root`]; + a run without one is refused the same way. [Source: owner, Q12; ADR-0019 §6] +8. **Config.** `share: z.strictObject({ allowMcp: z.boolean().default(false) + }).optional()` on `ProjectConfigSchema`, with a description that says the + MCP server may then publish videos outside the machine without asking. + +## Acceptance criteria + +- [ ] A fresh run's `result.json` has `chapters` on each render, one per scene + card, in output milliseconds; a run with no scenes has `chapters: []`; + an old `result.json` without the field still parses. +- [ ] The daemon's first frame carries `features: ['share']`. +- [ ] Given a reported run with an `mp4` render, `share.prepare` answers + `share.prepared` with the scenario's description, the render's chapters + and the poster's size; the poster is a JPEG ≤ 1280 px wide. +- [ ] `share.prepare` for an unreported run, a missing render file or an + unrendered format answers `share.error` with `not-found` / `no-render`, + and never reads outside the runs directory. +- [ ] `video.open` with `asset: 'poster'` streams exactly the poster file. +- [ ] `demoflow share ` against a fake API prints the link once the + share is `ready`; each refusal of Decision 6 exits 2 with its code; + `--password` never appears in the process arguments of the request. +- [ ] `share_demo` answers `share-not-allowed` without `share.allowMcp: true` + and creates the share with it. +- [ ] `project-config.schema.json` is regenerated and `share.allowMcp` + validates in an editor. +- [ ] Tests pass under Node with Vitest on Linux, macOS and Windows + (`execution-plane.yml`). + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i349-core | chapters and the config block | packages/core/src/run-result.ts, packages/core/src/project-config.ts, packages/core/schemas/project-config.schema.json, packages/core/test/**, packages/renderer/src/renderer.ts, packages/renderer/src/plan/**, packages/renderer/test/** | — | yes | opus | +| i349-cli | daemon, relay, command, MCP | apps/cli/src/runner/connection.ts, apps/cli/src/runner/share/**, apps/cli/src/runner/relay/index.ts, apps/cli/src/commands/share.ts, apps/cli/src/main.ts, apps/cli/src/mcp/**, apps/cli/test/**, apps/cli/README.md | i349-core | no | sonnet | + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| packages/core/src/project-config.ts, packages/core/schemas/project-config.schema.json | i349-core | #361 (`schedule`) and #365 (`render.endHoldMs`) also add keys: one at a time, regenerate the schema each time | +| packages/core/src/run-result.ts | i349-core | #353/#354 or #360 may touch it; cut after this merges | +| packages/renderer/src/renderer.ts, packages/renderer/src/plan/** | i349-core | #353, #354, #365 edit the plan; serialize | +| apps/cli/src/runner/connection.ts | i349-cli | #355 and #361 route new messages; serialize | +| apps/cli/src/main.ts | i349-cli | #360 adds `--check`; serialize | +| apps/cli/src/mcp/server.ts | i349-cli | do not open it | + +## Risks + +- **Chapters wrong after idle trimming** (medium). A scene placed in a + trimmed span. Mitigation: take the time after the time map, from the same + placed card the compositor draws; a test with a trimmed pause. +- **FFmpeg seek on GIF** (low). Mitigation: decode from the start for GIF + (`-ss` after `-i`); a test per container. +- **An agent shares a video with customer data** (medium). Mitigation: the + config flag is off by default and lives in a reviewed commit (ADR-0019 §6). + +## Open questions + +- A password for `share_demo` — default: none; an agent should not hold one. +- Auto-starting the daemon when `demoflow share` finds it offline — default: + no; print the command. diff --git a/docs/specs/350-web-share-dialog.md b/docs/specs/350-web-share-dialog.md new file mode 100644 index 00000000..08820cb5 --- /dev/null +++ b/docs/specs/350-web-share-dialog.md @@ -0,0 +1,121 @@ +# Share dialog on the run page and the `/app/shares` list + +Issue: [#350](https://github.com/AndreyBegma/DemoFlow/issues/350) +Depends on: #347. Implements the owner's side of [ADR-0019](../adr/0019-opt-in-share-links.md). + +## Summary + +#347 lets the API create, list, extend and revoke shares. This slice is the +website's owner side: a **Share** button on the run page that opens a dialog +(format, expiry, optional password, the quota), shows the upload's progress +and then the link; and a page, `/app/shares`, that lists every share with its +size, views and expiry, the quota used, and Extend / Revoke per row. + +## Scope + +### In scope + +- `apps/web/src/lib/shares.ts` (new) and `shares.test.mjs`: the client calls + of #347's owner API and their types, plus pure helpers (quota text, expiry + text, which actions a row offers). Kept out of `apps/web/src/lib/api.ts` + so other Phase 8 slices do not collide there; it may import that file's + request helper. +- `apps/web/src/components/shares/` (new): `share-button.tsx`, + `share-dialog.tsx`, `share-list.tsx`, `quota-meter.tsx`. +- `apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx`: mount the + Share button in the page header actions. +- `apps/web/src/app/app/shares/page.tsx` (new). +- `apps/web/src/app/app/page.tsx`: a "Shares" link beside Projects, Machines + and Settings [Confirmed: those links exist there]. +- `apps/web/src/i18n/en.ts`: `shares.*`. + +### Out of scope + +- The public page `/s/[token]` (#351). +- The API (#347). +- "Update link" after a re-render (#358). +- Changing a password (no endpoint, #347 Open questions). + +## Decisions + +1. **The button.** On the run page, beside the existing actions. Enabled + when the run has at least one render, its artifacts are not deleted, and + its machine is online and lists `share` in `machine.features` (#347, + Decision 6). Otherwise disabled with the reason as its hint: no render, + files deleted on the machine, machine offline, or "update DemoFlow on + to share" [Source: ADR-0019 §7]. A run that already has a share + for a format shows it in the dialog instead of creating a second + (`409 share-exists`, #347 Decision 1). +2. **The dialog** (Glass UI dialog primitives, as `delete-run.tsx` uses + `ConfirmDialog` [Confirmed]): + - **Format:** a select of the run's renders, each with its size; default + the first. A render over the file limit is disabled with "over 200 MB". + - **Expires in:** 7 / 30 / 90 days, default 30. + - **Password (optional):** a field, 8–128 characters, with a note that the + direct file link is off while a password is set. + - **Quota:** "`` of `` used"; the share's size is added in a + preview, and Create is disabled with "not enough space" when it would + not fit. + - **Create** posts `POST /shares`, then polls `GET /shares/:id` every + second while `uploading` (no fake percentage: an indeterminate + progress). `ready` shows the link with Copy, and — without a password — + the file link with Copy and, for a GIF, a Markdown snippet + `![](<fileUrl>)` with Copy. `failed` shows the failure in words + and Try again. + - The text says plainly that the file is uploaded to DemoFlow's server + and anyone with the link can watch it until it expires. +3. **`/app/shares`.** A table of `GET /shares`, newest first: title (linking + to the run page), format, size, views, "expires in N days", password + yes/no, status. Row actions: Copy link, Open, Extend 30 days (hidden at + the 90-day cap), Revoke (`ConfirmDialog`). `failed` rows offer Retry from + the run page; `lost` rows say "the file is gone from the server — share + again". Above the table: the quota meter. Empty: an empty state that says + shares are created from a run's page. +4. **Content surfaces stay readable.** Glass is for the dialog's chrome only; + the table and the dialog's body use the readable surfaces, as + `docs/product/vision.md` §9 and `CLAUDE.md` require. +5. **Strings** live in `en.ts` under `shares.*` (spec #48's i18n + dictionary [Confirmed: `apps/web/src/i18n/en.ts`]). + +## Acceptance criteria + +- [ ] The Share button's enabled and disabled states follow Decision 1, + covered by a pure helper's tests in `shares.test.mjs`. +- [ ] Creating a share shows progress, then the link; Copy writes the link + to the clipboard; a password hides the file link. +- [ ] Opening the dialog on a run that has a share for the chosen format + shows that share, not a second Create. +- [ ] `quota-exceeded`, `file-too-large`, `runner-offline` and + `runner-outdated` each show their own message. +- [ ] `/app/shares` lists the user's shares with views and expiry; Extend + moves the expiry and disappears at the cap; Revoke removes the row and + the link answers 404 afterwards. +- [ ] `/app` links to `/app/shares`; `/app/shares` is behind the `/app` + guard [Confirmed: `apps/web/src/app/app/layout.tsx` guards every page]. +- [ ] `bun run check`, `bun run build` pass; `node --test` of + `apps/web/src/lib/*.test.mjs` passes. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i350-web | the dialog and the list | apps/web/src/lib/shares.ts, apps/web/src/lib/shares.test.mjs, apps/web/src/components/shares/**, apps/web/src/app/app/shares/**, apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx, apps/web/src/app/app/page.tsx, apps/web/src/i18n/en.ts | #347 | yes | sonnet | + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| apps/web/src/i18n/en.ts | i350-web while it runs | #351, #352, #357–#359, #363, #364 add their own keys: appends, rebase | +| apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx | i350-web | #357/#358 mount the editor there; cut after this merges | +| apps/web/src/app/app/page.tsx | i350-web | #363 adds the stale block; rebase | + +## Risks + +- **Long uploads look stuck** (low). Mitigation: show elapsed time and the + file size under the progress; the API fails a stale upload after 15 + minutes (#347). + +## Open questions + +- A per-share "copy as embed" for MP4 (`<video>` tag) — default: no; the + file link is enough. diff --git a/docs/specs/351-web-share-page.md b/docs/specs/351-web-share-page.md new file mode 100644 index 00000000..1b74e39e --- /dev/null +++ b/docs/specs/351-web-share-page.md @@ -0,0 +1,124 @@ +# Public share page `/s/[token]`: player, chapters, download, password + +Issue: [#351](https://github.com/AndreyBegma/DemoFlow/issues/351) +Depends on: #348. + +## Summary + +#348 answers a share's data, file and poster to anyone with the token, and +unlocks a password-protected share. This slice is the page the link opens, +for a viewer with no account: the video in the player the run page already +uses, the scenario's title and description, its scenes as chapters that seek +the video, a Download button, a small "Made with DemoFlow" badge, a password +form for a protected share, and clear pages for expired and unavailable +links. Link unfurlers (Slack, Telegram, X) get a title and the poster. + +## Scope + +### In scope + +- `apps/web/src/app/s/[token]/page.tsx` (new, server component, outside + `/app`), `not-found.tsx` as needed. +- `apps/web/src/components/share-page/` (new): `share-view.tsx`, + `chapters.tsx`, `unlock-form.tsx`, `made-with-badge.tsx`. +- `apps/web/src/lib/share-page.ts` (new) and `share-page.test.mjs`: the + server fetch of `GET /s/:token` (forwarding the viewer's cookies, as + `apps/web/src/lib/session.ts` does [Confirmed]) and pure helpers (chapter + time text, which state to render). +- `apps/web/src/components/player/video-player.ts`, + `luna-video-player.tsx`, `native-video-player.tsx`: an optional way to + seek (Decision 3). +- `apps/web/src/i18n/en.ts`: `sharePage.*`. + +### Out of scope + +- The API (#348) and the owner's dialog and list (#350). +- An embeddable iframe player (owner, Q6). +- Comments, reactions, viewer analytics. + +## Decisions + +1. **States.** From #348's answer: `ShareData` → the share; `{ locked: true }` + → the password form only (no title, no poster); `404` → Next's not-found; + `410 expired` → "This link has expired"; `410 unavailable` → "This video + is no longer available". The page sends `noindex` in every state. +2. **The share.** Title (`h1`) and description; the player; chapters; + Download; the badge. + - **Video formats** play in the `VideoPlayer` adapter — `choosePlayer()` + (Luna Player with the native fallback, ADR-0009 §2 [Confirmed: + `video-player.ts`]) — with `src = fileUrl`, `shape` from the share's + width and height (`16:9`, `9:16` or `1:1`), and the poster. + - **GIF formats** (`kind: 'image'`) are an `<img>` of `fileUrl` with the + title as `alt`; they have no chapters to seek. + - **Download** links `downloadUrl` (#348, Decision 3). + - **"Made with DemoFlow"** links `/` (the landing page), small and below + the player, never over the video. [Source: owner, Q14] +3. **Seeking for chapters.** `VideoPlayerProps` gains an optional + `onControls?(controls: { seek(ms: number): void }): void`; both + implementations call it once they can seek. The native element sets + `currentTime`; Luna uses its seek API if it has one [Unknown: check + `luna-player` 0.2.0's exports], otherwise this slice falls back to the + native player on the share page. Chapters render as a list of `mm:ss + title` buttons; clicking seeks and plays. No chapters → no list. +4. **Password form.** One password field and Unlock; posts + `/api/s/:token/unlock`, then `router.refresh()` so the server component + fetches again with the new cookie. `401` → "Wrong password"; `429` → "Too + many attempts, try again in a few minutes". +5. **Unfurl metadata.** `generateMetadata` sets `og:title` (title), + `og:description` (description), `og:image` (`posterUrl`, absolute), and + `og:type: video.other` with `og:video` = `fileUrl` for MP4 shares without + a password. A locked share's metadata is "A shared DemoFlow video" and no + image. [Source: ADR-0019 §2 — nothing of a locked share leaves] +6. **Look.** A content surface, readable, centred, max width like the run + page; glass only for floating chrome (the badge), per + `docs/product/vision.md` §9. The page works without JavaScript for the + video itself (the native fallback renders the `<video>` tag). +7. **No account UI.** No sign-in prompt, no header of the app; a viewer is + never asked to sign up. The landing link is the badge. + +## Acceptance criteria + +- [ ] An MP4 share renders title, description, the player with the poster, + chapters, Download and the badge; clicking a chapter seeks to its time. +- [ ] A GIF share renders an `<img>` and no player. +- [ ] A locked share renders only the password form; a right password shows + the video after refresh; wrong and rate-limited attempts show their + messages. +- [ ] Expired, unavailable and unknown tokens render their pages; an + unknown token answers 404 (`notFound()`). Expired and unavailable + answer 410 if the App Router lets a page set it [Unknown], otherwise + 200 with `noindex` (Open questions). +- [ ] The HTML of an unlocked share has `og:title`, `og:image` and + `noindex`; a locked share's HTML contains neither its title nor its + poster URL. +- [ ] `/s/<token>` is reachable without a session; the `/app` guard does not + apply [Confirmed: the proxy matcher is `/app/:path*` only]. +- [ ] The run page still plays through the adapter unchanged. +- [ ] `bun run check`, `bun run build` pass; `node --test` of the new + `.test.mjs` passes. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i351-web | the public page | apps/web/src/app/s/**, apps/web/src/components/share-page/**, apps/web/src/lib/share-page.ts, apps/web/src/lib/share-page.test.mjs, apps/web/src/components/player/video-player.ts, apps/web/src/components/player/luna-video-player.tsx, apps/web/src/components/player/native-video-player.tsx, apps/web/src/i18n/en.ts | #348 | yes | sonnet | + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| apps/web/src/components/player/video-player.ts and both players | i351-web | #357 (editor preview) needs time and seek too: whichever is second builds on the first's `onControls` | +| apps/web/src/i18n/en.ts | shared | appends; rebase | + +## Risks + +- **Luna Player has no seek API** (medium). Mitigation: Decision 3's native + fallback on this page; note it for luna-player. +- **Large files on mobile data** (low). Mitigation: `preload="metadata"` and + the poster; nothing autoplays. + +## Open questions + +- Showing the expiry date to viewers — default: no; it is the owner's detail. +- HTTP 410 for expired and unavailable pages — default: 200 with `noindex` + if a page cannot set the status; the body says what happened either way. diff --git a/docs/specs/352-docs-sharing.md b/docs/specs/352-docs-sharing.md new file mode 100644 index 00000000..7cd656de --- /dev/null +++ b/docs/specs/352-docs-sharing.md @@ -0,0 +1,86 @@ +# Docs: sharing a video + +Issue: [#352](https://github.com/AndreyBegma/DemoFlow/issues/352) +Depends on: #349, #350, #351. + +## Summary + +Sharing (ADR-0019) reaches users through three doors — the run page, `demoflow +share` and the MCP tool `share_demo` — and changes what leaves the machine. +This slice adds a **Sharing** page to the website's docs and brings the CLI, +MCP, config and runner pages up to date, so a user learns what a share +uploads, who can open it, how long it lives and how to revoke it before they +press the button. + +## Scope + +### In scope + +- `apps/web/src/app/docs/share/page.mdx` (new). +- `apps/web/src/lib/docs-nav.ts`: `{ href: '/docs/share', label: + 'docs.nav.share' }` after `/docs/runner` [Confirmed: `DOCS_NAV`]; the nav + test keeps passing (`docs-nav.test.mjs` checks every entry has a page + [Confirmed: `docsPageFile`]). +- `apps/web/src/i18n/en.ts`: `docs.nav.share`. +- `apps/web/src/app/docs/cli/page.mdx`: `demoflow share`. +- `apps/web/src/app/docs/mcp/page.mdx`: `share_demo` and its refusal. +- `apps/web/src/app/docs/config/page.mdx`: `share.allowMcp`. +- `apps/web/src/app/docs/runner/page.mdx`: one paragraph — the runner + uploads a render only for a share you created, and an older CLI cannot + share. + +### Out of scope + +- `apps/cli/README.md` (#349 documents the command there). +- `deploy/README.md` (#347, #348). + +## Decisions + +1. **The Sharing page**, in this order: + 1. *What a share is:* a copy of one rendered file on DemoFlow's server, + opened by anyone with the link, until it expires or you revoke it. + 2. *What is uploaded:* exactly ADR-0019 §2's list, and what never is. + 3. *Creating one:* from the run page (with a screenshot-free description + of the dialog), `demoflow share <runId>` with its flags, and + `share_demo` with `share.allowMcp`. + 4. *Password, expiry, extend, revoke, views.* That the file link is off + while a password is set; 7/30/90 days; Extend adds 30 up to 90 days + from now; what deletes a share and what does not (deleting local files + does not). + 5. *Limits:* 200 MB per file and 2 GB per account on demoflow's hosted + service; self-hosters set `SHARE_MAX_FILE_BYTES`, + `SHARE_USER_QUOTA_BYTES`. + 6. *Embedding:* the file link in a README (`![…](…/file)` for a GIF) and + as a `<video src>`. + 7. *Errors:* `runner-offline`, `runner-outdated`, `quota-exceeded`, + `file-too-large`, `share-not-allowed`, and what to do about each. +2. **Wording follows the code**, not this spec: the writer reads the merged + #347–#351 and quotes their real flags, codes and limits. Where they + differ from this spec, the code wins and the page says what the code does. +3. Every page stays English, MDX, in the style of the existing docs pages. + +## Acceptance criteria + +- [ ] `/docs/share` renders and appears in the side navigation after Runner. +- [ ] The page lists what is uploaded and what never is, matching ADR-0019 §2. +- [ ] Every flag of `demoflow share` and every error code above appear with + the exact spelling the merged code uses. +- [ ] The CLI, MCP, config and runner pages link to `/docs/share`. +- [ ] `bun run check`, `bun run build` pass; `docs-nav.test.mjs` passes. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i352-docs | the docs | apps/web/src/app/docs/share/**, apps/web/src/app/docs/cli/page.mdx, apps/web/src/app/docs/mcp/page.mdx, apps/web/src/app/docs/config/page.mdx, apps/web/src/app/docs/runner/page.mdx, apps/web/src/lib/docs-nav.ts, apps/web/src/i18n/en.ts | #349, #350, #351 | yes | sonnet | + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| apps/web/src/lib/docs-nav.ts | i352-docs | #359 and #364 add entries; one at a time | +| apps/web/src/app/docs/cli/page.mdx, mcp/page.mdx, config/page.mdx | i352-docs | #359, #364, #365 may add sections; rebase | + +## Open questions + +- A screenshot of the dialog — default: none until the UI settles. diff --git a/docs/specs/353-edits-schema-and-render.md b/docs/specs/353-edits-schema-and-render.md new file mode 100644 index 00000000..a5a5797b --- /dev/null +++ b/docs/specs/353-edits-schema-and-render.md @@ -0,0 +1,201 @@ +# `edits.json`: captions, zoom, cards and style applied at render + +Issue: [#353](https://github.com/AndreyBegma/DemoFlow/issues/353) +Depends on: nothing. [ADR-0020](../adr/0020-edits-from-the-website.md) lands +with the Phase 8 docs pull request. + +## Summary + +[ADR-0020](../adr/0020-edits-from-the-website.md) puts a run's edits in +`runs/<runId>/edits.json` and has the renderer apply them over the run's own +inputs. This slice is the contract and the renderer half: `RunEditsSchema` in +`@demoflow/core`, a pure check of an edits file against the run's timeline, +and `buildRenderPlan` reading the file and applying caption, zoom, card and +style edits. Trimming and cuts are #354. Nothing on the Runner, the API or the +website changes here; `demoflow render <runId>` picks the file up on its own, +because it calls `buildRenderPlan` [Confirmed: `apps/cli/src/commands/render.ts`]. + +## Scope + +### In scope + +- `packages/core/src/edits.ts` (new): `RunEditsSchema`, `RunEdits`, + `checkRunEdits(edits, timeline)`, `RUN_EDITS_FILE = 'edits.json'`. +- `packages/core/src/index.ts`: `export * from './edits.ts'`. +- `packages/core/src/json-schema.ts`: a JSON Schema for `edits.json`, like the + scenario's and the config's [Confirmed: the module exists; whether it is + generated per contract or by a list is [Unknown] — follow what it does]. +- `packages/core/test/edits.spec.ts` (new). +- `packages/renderer/src/plan/plan.ts`: `PLAN_INPUTS.edits`, + `PlanInput.edits`, reading and applying the file. +- `packages/renderer/src/plan/cards.ts`: card text and switches from edits. +- `packages/renderer/test/plan/edits.spec.ts` (new), and fixture runs in + `packages/renderer/test/plan/fixture-runs.ts` if a run directory is needed. + +### Out of scope + +- `trim` and `cuts` (#354). The schema here has no such keys; #354 adds them. +- Who writes the file: the Runner (#355), the API relay (#356), the editor + (#357). +- Exporting edits to a scenario or the config (#355, #358). +- Any change to `TimelineSchema`, `RunResultSchema`, the engine or + `demoflow run`. A fresh run has no `edits.json` and renders as today. +- Editing scene card titles, the intro/outro durations, the GIF, vertical or + square tuning, the output size or fps, transitions, or the idle thresholds. + The owner's list is captions, zoom per step, card text, background and + window (ADR-0020 Context). + +## Data + +`edits.json`, validated by `RunEditsSchema` (zod, strict objects): + +```ts +{ + schemaVersion: 1, + // The complete caption list of the run, when present. It replaces every + // caption from steps (`caption`, `marker` kind caption) and from the page + // (ADR-0014). `[]` means no captions at all. + captions?: Array<{ startMs: number; endMs: number; text: string }>, + // Per-step zoom overrides; a step not listed keeps its timeline `zoom`. + zoom?: Array<{ stepIndex: number; zoom: boolean | number }>, + cards?: { + intro?: { enabled?: boolean; title?: string; subtitle?: string | null }, + scenes?: { enabled?: boolean }, + // `null` removes the outro; an object sets it, even if the config has none. + outro?: { title: string; cta?: string } | null, + }, + background?: BackgroundConfig, // as in render.background + frame?: { enabled?: boolean; radius?: number; shadow?: boolean }, +} +``` + +- **Times are timeline ms** (ADR-0020 §1): `msSchema` from `timeline.ts`, + integers ≥ 0. +- **Captions:** at most 200; `text` is trimmed, 1 to 120 characters (the + limit of a page caption, `AnnotationSchema` [Confirmed]); `endMs > startMs`; + ordered by `startMs` and not overlapping. *Why a full list, not per-step + patches:* the editor moves and retimes captions freely (owner), and a caption + moved off its step is no longer the step's; one list is the only shape both + can share without merge rules. +- **Zoom:** `stepIndex` unique within the list; `zoom` is `ZoomSchema` + (`true`, `false`, or `1 ≤ n ≤ 3`) [Confirmed: `step.ts`]; at most one entry + per step. +- **Cards:** text fields reuse `CardTextSchema` of `project-config.ts` (1–80, + not only spaces) [Confirmed]; `subtitle: null` removes the intro's subtitle. +- **Background:** `BackgroundConfigSchema` [Confirmed]; **frame:** the + `FrameConfigSchema` fields named above with the same bounds, all optional + and without defaults (absent means "as configured"). +- **Size cap:** the Runner rejects a file over 256 KiB before parsing (#355); + the schema caps the arrays so that a valid file fits. + +`checkRunEdits(edits, timeline): Issue[]` (the `issues.ts` shape [Confirmed]), +pure, used by the Runner before it writes and by the renderer before it plans: + +- every `zoom[].stepIndex` is an event of the timeline whose event carries a + `target` (ADR-0012 §2), else `zoom-no-target` at that entry; +- every caption ends at or before the timeline's last event `endMs` plus the + tail the renderer keeps, else `caption-out-of-range`. + +## Decisions + +1. **The renderer reads the file itself.** `buildRenderPlan(runDir, options)` + reads `edits.json` when it exists, parses it with `RunEditsSchema`, runs + `checkRunEdits`, and passes it to `planRender` as `PlanInput.edits`. A file + that fails either check fails the plan with a message naming the file and + the first issue. *Why fail, not ignore:* a render that silently drops the + person's edits looks like a renderer bug. *Why in `buildRenderPlan`, not in + the CLI:* every caller (`demoflow render`, the daemon in #355) gets the same + behaviour, and `planRender` stays pure and testable (spec 4). +2. **Captions.** With `edits.captions`, `captions()` returns that list mapped + through `out()`, and step and page captions are not read. The vertical and + square crops use the same list [Confirmed: `cropCaption` takes the + planned captions]. +3. **Zoom.** Before `cameraKeyframes`, each event's `zoom` is replaced by its + override when one exists. The rest of ADR-0012 is unchanged: the default + strength, the fit cap and the merge rule apply to the overridden values + exactly as to a scenario's. +4. **Cards.** `placeCards` takes the edits: + - intro `enabled` overrides `render.cards.intro.enabled`; `title` replaces + `result.scenarioName`; `subtitle` replaces the description, `null` + removes it; + - scenes `enabled` overrides `render.cards.scenes.enabled`; + - outro: an object is the outro whatever the config says (duration from + the config's `outro.durationMs`); `null` removes it. A failed run still + never gets an outro [Confirmed: `cards.ts`, `!input.failed`]. + - With no `render.cards` in the options at all, card edits are ignored: a + project with cards off stays off [Confirmed: `placeCards` returns `[]` + without a config]. +5. **Style.** `edits.background` replaces `options.background`; + `edits.frame` is merged over `options.frame` field by field before + `FrameConfigSchema.parse`. +6. **A failed run stays visibly failed** (ADR-0004 §4, ADR-0020 §2). Edits + change nothing about the failure card or the watermark. +7. **No schema version bump of the timeline.** `edits.json` has its own + `schemaVersion: 1`. + +## Configuration + +None. `edits.json` is per run. + +## Acceptance criteria + +`packages/core/test/edits.spec.ts` (Vitest under Node): + +- [ ] A minimal `{ schemaVersion: 1 }` parses; an unknown key, a + `schemaVersion: 2`, a caption with `endMs <= startMs`, overlapping or + unordered captions, 201 captions, a 121-character caption, a duplicate + `stepIndex`, `zoom: 4`, and an outro without `title` are rejected. +- [ ] `checkRunEdits` reports `zoom-no-target` for a `wait` step and for a + step index not in the timeline, and nothing for a `click` with a box. + +`packages/renderer/test/plan/edits.spec.ts`: + +- [ ] Without `edits.json`, the plan of every fixture run is identical to + today's (deep equality with the plan built without the new code path). +- [ ] `captions: [{ startMs, endMs, text }]` gives exactly one caption at + `out(startMs)…out(endMs)`, and none of the scenario's or the page's. +- [ ] `captions: []` gives no captions; the vertical output has none either. +- [ ] A zoom override `true` on an unzoomed `click` adds a zoom keyframe at + that click with the default strength; `false` on a zoomed step removes + it; `2` uses 2 (capped by the fit rule as before). +- [ ] Intro `title`/`subtitle: null`, scenes `enabled: false`, outro set on a + config without one, and outro `null` on a config with one each give the + expected cards; a failed run with an outro edit has no outro. +- [ ] `background: { color: '#112233' }` and `frame: { radius: 0 }` change + the plan's frame and nothing else. +- [ ] `buildRenderPlan` on a run directory with an invalid `edits.json` + rejects with a message that contains `edits.json`. +- [ ] `bun run check` and the renderer and core Vitest suites are green. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i353-edits | the schema and the renderer apply | packages/core/src/edits.ts, packages/core/src/index.ts, packages/core/src/json-schema.ts, packages/core/test/edits.spec.ts, packages/renderer/src/plan/plan.ts, packages/renderer/src/plan/cards.ts, packages/renderer/test/plan/** | — | yes | opus | + +One slot: the schema decides what the renderer can apply, and the renderer +change is small once the schema exists. + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| `packages/renderer/src/plan/plan.ts` | this issue | #354 (trim, cuts) follows it. #365 (end hold) also edits `TIMING.tailMs` and the source end: rebase on whichever merges first. | +| `packages/core/src/index.ts`, `json-schema.ts` | this issue | One export line each; #361 (schedule config) may add its own. | +| `packages/core/src/project-config.ts` | nobody here | Read only; #361 and #365 edit it. | + +## Risks + +- **Medium — captions replace both sources.** A run whose page set captions + (ADR-0014) loses them once the person edits any caption. Mitigation: the + editor (#357) seeds the list with every caption the plan would show, from + both sources, so the first save keeps them. +- **Low — an edit refers to a step of a different timeline.** A run directory + is never re-recorded, so the indices stay valid; `checkRunEdits` catches a + hand-edited file. + +## Open questions + +- Should a caption list keep a link to the step it came from (for export in + #355)? Default: no. Export matches a caption to a step by time (#355, + Decision 6). diff --git a/docs/specs/354-trim-and-cuts.md b/docs/specs/354-trim-and-cuts.md new file mode 100644 index 00000000..442d0a24 --- /dev/null +++ b/docs/specs/354-trim-and-cuts.md @@ -0,0 +1,153 @@ +# Trim and cut segments from `edits.json` + +Issue: [#354](https://github.com/AndreyBegma/DemoFlow/issues/354) +Depends on #353 (`RunEditsSchema` and the renderer's edits path). + +## Summary + +The owner wants trimming to be free: a new start, a new end, and any number of +cut segments anywhere in the run, all dragged on the timeline (#357). This +slice adds `trim` and `cuts` to `RunEditsSchema` and makes the renderer's time +map drop them, next to the idle compression that already squeezes frozen +stretches (ADR-0004 §5). Overlays inside a cut drop with it. + +## Scope + +### In scope + +- `packages/core/src/edits.ts`: `trim`, `cuts`, their checks in + `checkRunEdits`, which now also takes the run's `RunResult`. +- `packages/core/test/edits.spec.ts`. +- `packages/renderer/src/plan/time-map.ts`: cuts in the time map. +- `packages/renderer/src/plan/plan.ts`: the trimmed range, cuts passed to the + map, overlays and cards inside a cut. +- `packages/renderer/src/plan/cards.ts`, `masks.ts`, `transitions.ts` as the + decisions below need. +- `packages/renderer/test/plan/**`: tests. + +### Out of scope + +- Speed changes (play a stretch faster). Not asked for. +- Cutting the source file. The source stays as recorded (ADR-0020 §1). +- The editor UI (#357). + +## Data + +Added to `RunEditsSchema`: + +```ts +trim?: { startMs?: number; endMs?: number }, // timeline ms +cuts?: Array<{ startMs: number; endMs: number }>, // timeline ms +``` + +- `trim.startMs < trim.endMs` when both are set. +- `cuts`: at most 100, each `endMs > startMs`, ordered by `startMs`, not + overlapping, not touching (a gap of at least one millisecond; two touching + cuts are one cut — the editor merges them). + +`checkRunEdits(edits, timeline, result)` adds: + +- `cut-outside-trim`: a cut not entirely inside the trimmed range (or the + run's range without a trim); +- `trim-hides-failure`: on a failed run, `trim.endMs` before the failed + step's `endMs`, or a cut that overlaps the failed step's event + (ADR-0004 §4, ADR-0020 §2); +- `too-short`: less than 500 ms of page left after the trim and the cuts. + +## Decisions + +1. **Trim sets the page range.** The output's page starts at + `max(startMs, toSource(trim.startMs))` and ends at + `min(sourceEndMs, toSource(trim.endMs))`, where `startMs` and + `sourceEndMs` are what `planRender` computes today (after the sync mark, + and the failure or the last event plus the tail) [Confirmed: + `plan.ts`, `planRender`]. A trim can only shorten the range, never extend + it past the recording. +2. **A cut is a stretch of source that plays in 0 ms.** `buildTimeMap` takes + the cuts besides the idle stretches. A frozen stretch that overlaps a cut + is subtracted by the cut first; what is left of it is still idle and is + compressed as today. *Why in the same map:* every overlay is already + planned through `out()` over this map [Confirmed: `pageMap`, `out`], so a + cut moves captions, the camera, masks and cursor for free; a second map + would have to be kept in step with the first. +3. **Overlays at a cut.** + - A caption whose whole span is inside a cut is dropped (its mapped span + is empty and the existing `endMs > startMs` filter removes it + [Confirmed]); one that crosses a cut is shown on both sides. + - A click ring whose `atMs` falls inside a cut is dropped. + - A cursor move that crosses a cut is split at it, like at a card + [Confirmed: `splitMoves` in `cards.ts`]; the cursor jumps to where it + is after the cut. + - The camera is held across the cut at its state on the cut, like across a + card [Confirmed: `holdAcross`]; a zoom that starts inside a cut starts at + the cut's end. + - A scene card whose marker or page scene falls inside a cut or outside the + trim is not placed. The intro stays at 0; the outro stays at the end. +4. **A visible join.** With `render.transitions.enabled`, each cut gets the + dissolve a page load gets, of `transitions.durationMs` [Confirmed: + `transitions.ts`, spec 114]. Without, a cut is a hard join. +5. **Masks never leak at a cut.** A mask span that overlaps a cut keeps + covering on both sides; the lead and trail of a mask (#48) are measured so + that the output frames on both sides of a join are covered whenever the + masked field was visible in the source frame they show. The slot proves + this with a test, not by reading. [Unknown: whether `maskSpans` applies the + lead and trail before or after `out()`; the slot finds out and makes the + rule hold either way.] +6. **The real durations stay.** `result.json` keeps the run's real durations + (ADR-0004 §5); `renders[].durationMs` is the trimmed output's. + +## Acceptance criteria + +Vitest under Node: + +- [ ] Schema: unordered, overlapping and touching cuts, 101 cuts, and + `trim.startMs >= trim.endMs` are rejected. +- [ ] `checkRunEdits`: `cut-outside-trim`, `trim-hides-failure` (both forms) + and `too-short` each on a minimal case; a passed run with a cut over its + last step passes. +- [ ] `buildTimeMap` with one cut gives segments whose output skips the cut, + and with a cut over half an idle stretch compresses only the other half. +- [ ] A plan with `trim { startMs: 2000 }` starts its page at the source frame + of timeline 2000 (± one frame); with `trim { endMs }` its page ends + there, followed by the outro when there is one. +- [ ] A caption inside a cut is absent; one crossing it appears before and + after; a click ring inside a cut is absent; a scene card whose marker is + inside a cut is absent. +- [ ] With transitions on, a cut has a dissolve; off, it does not. +- [ ] **Masking:** on the fixture run with a masked `fill`, every placement of + a cut boundary within 300 ms of the field's visibility edges (step + through in 10 ms) leaves no output frame in which the field is visible + and unmasked (assert on the planned spans against the field's + `maskVisibility`). +- [ ] Without `trim` and `cuts`, every existing plan test is unchanged. +- [ ] `bun run check` is green. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i354-cuts | trim and cuts | packages/core/src/edits.ts, packages/core/test/edits.spec.ts, packages/renderer/src/plan/time-map.ts, packages/renderer/src/plan/plan.ts, packages/renderer/src/plan/cards.ts, packages/renderer/src/plan/masks.ts, packages/renderer/src/plan/transitions.ts, packages/renderer/test/plan/** | #353 merged | yes | opus | + +One slot. It decides the mask rule at a join (Decision 5). + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| `packages/renderer/src/plan/plan.ts`, `time-map.ts` | this issue, after #353 | #365 (end hold) edits the source end and must not let idle compression cut its hold: rebase on whichever merges first; the hold and the trim compose (a trim end before the hold ends the video there). | +| `packages/core/src/edits.ts` | #353, then this issue | nobody else | + +## Risks + +- **High — a mask leak at a join.** A cut can put a frame where a masked + field is visible right after a frame where the mask was timed to start. + Mitigation: Decision 5 and its exhaustive acceptance test. +- **Medium — the camera at a join.** Holding the camera across a cut can leave + the view zoomed on something that is gone. Mitigation: the hold is the rule + for cards today and reads well there; the visual baseline suite + ([73](73-visual-baselines.md)) gets one cut case. + +## Open questions + +- Should a cut shorter than one frame be refused? Default: no; it maps to + nothing and changes nothing. diff --git a/docs/specs/355-runner-edits-and-rerender.md b/docs/specs/355-runner-edits-and-rerender.md new file mode 100644 index 00000000..0fd6f8fe --- /dev/null +++ b/docs/specs/355-runner-edits-and-rerender.md @@ -0,0 +1,218 @@ +# The Runner serves and saves a run's edits, re-renders on request, and exports patches + +Issue: [#355](https://github.com/AndreyBegma/DemoFlow/issues/355) +Depends on #353 (`RunEditsSchema`, `checkRunEdits`, the renderer applying +edits). Works with #354 when it has landed (trim and cuts are part of the +schema then); nothing here depends on it. + +## Summary + +[ADR-0020](../adr/0020-edits-from-the-website.md) §3 lets the website read and +write a reported run's edits and ask the Runner to re-render it; §4 says what +the edit model carries; §5 makes export a patch the person applies. This slice +is the machine side: four new socket requests in the daemon, a `--progress` +flag on `demoflow render`, and a new `demoflow edits apply <runId>` command. +The API relay is #356. + +## Scope + +### In scope + +- `apps/cli/src/runner/edits/` (new): the handler of `edits.get`, + `edits.save`, `edits.export` and `render.start`; the edit model builder; the + patch builder. +- `apps/cli/src/runner/connection.ts`: routes the new message types to the + handler; `launches.sync` announces `features: ['edits']`. +- `apps/cli/src/runner/daemon.ts`: wires the handler [Confirmed: the daemon + builds `relay`, `artifacts` and `launches` deps for the connection]. +- `apps/cli/src/commands/render.ts` and `apps/cli/src/main.ts`: + `demoflow render --progress`. +- `apps/cli/src/commands/edits.ts` (new) and `apps/cli/src/main.ts`: + `demoflow edits apply <runId> [--dry-run] [--config]`. +- `apps/cli/test/**`: tests (Vitest under Node). +- `apps/cli/README.md` and `apps/web/src/app/docs/cli/page.mdx`: the two + command changes. + +### Out of scope + +- The API and the website (#356, #357, #358). +- Uploading a new render to a share (#356 asks; the upload itself is #349's + `share` handler). +- An MCP tool for edits. No source asks for one. +- Cancelling a re-render. A render is bounded (Decision 7). + +## Protocol + +New frames on the runner socket (spec 247's framing). Times are timeline ms. + +| Direction | Message | Answer | +|---|---|---| +| API → Runner | `{ type: 'edits.get', requestId, runId }` | `{ type: 'edits.model', requestId, model }` or `edits.error` | +| API → Runner | `{ type: 'edits.save', requestId, runId, edits: RunEdits \| null }` | `{ type: 'edits.saved', requestId }` or `edits.error` | +| API → Runner | `{ type: 'edits.export', requestId, runId }` | `{ type: 'edits.exported', requestId, scenarioPatch, config, notExportable }` or `edits.error` | +| API → Runner | `{ type: 'render.start', requestId, runId, formats? }` | `{ type: 'render.started', requestId }`, then any number of `{ type: 'render.progress', requestId, percent? }`, then `{ type: 'render.finished', requestId, rendering, renders }`; or `{ type: 'render.error', requestId, code }` instead of `render.started` | +| Runner → API | `{ type: 'edits.error', requestId, code }` | — | +| Runner → API | `launches.sync` gains `features?: string[]` | this daemon sends `['edits']` | + +- **`model`** (ADR-0020 §4): + ```ts + { + runId, scenarioName, description: string | null, + failed: boolean, failedStepIndex: number | null, + durationMs, // the timeline's range the editor may use + events: Array<{ stepIndex, action, startMs, endMs, + box: Box | null, zoom: boolean | number | null, + caption: string | null, scene: string | null }>, + pageCaptions: Array<{ atMs, title }>, pageScenes: Array<{ atMs, title }>, + style: { background, frame, cards }, // the resolved render.* the next render uses, without edits + edits: RunEdits | null, + timeMap: Array<{ outputStartMs, outputEndMs, timelineStartMs, timelineEndMs }>, + renders: Array<{ format, width, height, sizeBytes, durationMs }>, + } + ``` + `timeMap` is the current render's map from output time back to timeline + time, so the browser can draw over the video it plays (#357). Segments with + no timeline span are cards. +- **`edits: null`** on `edits.save` deletes `edits.json` (ADR-0020 §6, + "reset"). +- **`scenarioPatch`**: an RFC 6902 array of `add`, `replace` and `remove` + operations whose paths are only `/steps/<n>/caption` and `/steps/<n>/zoom` + (ADR-0020 §5). **`config`**: `{ render: { background?, frame?, cards? } }`, + the style edits as a `demoflow.config.json` fragment. **`notExportable`**: + `Array<{ kind: 'caption' | 'zoom' | 'trim' | 'cut' | 'card', at?: number, reason }>`. +- **`formats`** on `render.start`: as `run.start`'s (ADR-0017), 1 to 9 + members of `RENDER_FORMATS`; absent means the formats of the current render. +- **`rendering`** is the `rendering` stage status after the render; + **`renders`** the new `renders[]` of `result.json`, in the run report's + shape (spec 263) [Confirmed: the shape of `Run.renders`]. +- **Error codes:** `run-not-found` (not in `reported-runs.jsonl`, or its + directory is gone), `run-unfinished`, `no-recording` (as `demoflow render`, + spec 255), `edits-invalid` (schema or `checkRunEdits` issues; the first + issue's path in the message), `too-large` (an `edits` over 256 KiB), + `busy` (a re-render is already running on this machine), `failed` (any + other error, logged locally). + +## Decisions + +1. **A run is found as `artifacts.delete` finds it** (spec 233): by `runId` + in the daemon's `reported-runs.jsonl`, which gives the canonical root and + the run directory [Confirmed: `apps/cli/src/runner/artifacts/index.ts` + reads `indexFile`]. A run id that fails `assertSafeRunId` is + `run-not-found`. Nothing outside that run directory and its project's + scenario file and config is read; nothing outside the run directory is + written by a socket request. +2. **The model is built on request, never cached.** The daemon reads + `timeline.json`, `result.json`, `edits.json`, the project's + `demoflow.config.json` and the scenario's `description` (from the scenario + file, as `demoflow render` reads it, spec 255 Decision 3), and builds the + current plan with `buildRenderPlan` to get `timeMap` [Confirmed: + `RenderPlan.timeMap` in `packages/renderer/src/plan/types.ts`]. Fields + ADR-0008 §2 forbids are never in it: no `value`, no `screenshot`, no + `pointer`, no `scroll`, no locator, no URL. The builder is a pure function + of those inputs with a test that the model of a run with a masked `fill` + contains neither its value nor `***`. +3. **Save validates, then writes atomically.** `edits.save` parses with + `RunEditsSchema`, runs `checkRunEdits` against the run's timeline and + result, writes `edits.json.tmp` and renames it over `edits.json`. +4. **Re-render is `demoflow render` as a child**, spawned like a website run + (spec 248): `render <runId> --json --progress --project <root>`, plus a + `--format` per entry of `formats`. Its progress lines become + `render.progress`; its JSON result becomes `render.finished`. + *Why a child:* the daemon never loads the renderer in its own process + [Confirmed: the daemon does not import `@demoflow/renderer`; runs are + children], and a crash stays in the child. +5. **`demoflow render --progress`** prints the progress lines of + `demoflow run --progress` (spec 302) for the `rendering` phase only, with + `percent` when the renderer can tell [Unknown: whether the FFmpeg + renderer exposes frame progress; without it, one line at the start and + one at the end]. +6. **Export maps the timeline back to the authored scenario.** + - A step's `zoom` edit becomes an op on `/steps/<n>/zoom` when expanded + step `stepIndex` came from top-level step `n` with no `repeat` or + `include` in between; otherwise `notExportable` with + `reason: 'from-repeat'` or `'from-include'`. [Unknown: `ExpandedStep` + carries `origin` for `repeat` only and no top-level index; the slot + computes the index by walking the authored steps of `scenario.json` in + the run directory.] + - A caption becomes the `caption` of a step when its `startMs` is within + 100 ms of that step's event `startMs` and that step is exportable; + a removed caption of an exportable step becomes `remove`; anything else + (a free-timed caption, a page caption) is `notExportable`. + - `trim` and `cuts` are always `notExportable` (`reason: 'not-in-scenario'`). + - The patch is built against `scenario.json` of the run directory, and the + daemon refuses with `edits-invalid` (message `scenario-changed`) when the + scenario file on disk no longer has the same steps (compared by action + and locator), so a patch never lands on the wrong step. +7. **Bounds.** One re-render at a time per machine (`busy`), the daemon's + 15-minute cap per child (spec 248, Decision 9), and the formats allowed by + ADR-0017. +8. **`demoflow edits apply <runId>`** reads `edits.json` of the run in the + resolved home, builds the same patch, and applies it to the scenario file + under the project root; with `--config`, it also merges the `render` + fragment into `demoflow.config.json`. It writes JSON with two-space + indentation and a trailing newline, and prints a unified diff of each + file. `--dry-run` prints the diffs and writes nothing. Exit 2 with + `scenario-changed` under Decision 6's condition. It needs no account. + +## Acceptance criteria + +Vitest under Node, a fake socket and temporary run directories: + +- [ ] `edits.get` for a reported run returns a model whose `events` match + `timeline.json`, whose `edits` is `null` without a file, and that + contains no `value`, `pointer`, `scroll`, `screenshot` or URL key + anywhere (recursive key scan) for the fixture run with a masked fill. +- [ ] `edits.get` for an unknown id, a `../x` id, and a reported run whose + directory is gone is `run-not-found`. +- [ ] `edits.save` with a valid object writes `edits.json`; with `null` + deletes it; with an unknown key, a `zoom-no-target` entry, or 300 KiB is + `edits-invalid` / `too-large` and leaves the previous file untouched. +- [ ] `render.start` spawns `render <runId> --json --progress --project <root>` + (and `--format gif` for `formats: ['gif']`), sends `render.started`, at + least one `render.progress`, and `render.finished` with the child's + `renders`; a second `render.start` meanwhile is `busy`. +- [ ] `edits.export`: a zoom edit on a top-level step gives one `replace` (or + `add`) at `/steps/<n>/zoom`; one on a step from a `repeat` is + `notExportable` `from-repeat`; a cut is `not-in-scenario`; a changed + scenario file is `scenario-changed`. +- [ ] `launches.sync` carries `features: ['edits']`. +- [ ] `demoflow edits apply <runId> --dry-run` prints a diff and changes no + file; without `--dry-run` the scenario file has the new caption and + zoom and still parses with `parseScenario`; `--config` adds the + background to `demoflow.config.json`. +- [ ] `demoflow render <runId>` on a run with `edits.json` renders the + edited plan (the plan builder receives the run directory; the edits are + read by #353's code). +- [ ] `bun run check` and the CLI Vitest suite are green. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i355-daemon | the socket handler, model and patch builders | apps/cli/src/runner/edits/**, apps/cli/src/runner/connection.ts, apps/cli/src/runner/daemon.ts, apps/cli/test/runner/edits/** | #353 | yes | opus | +| i355-commands | `render --progress`, `edits apply` | apps/cli/src/commands/render.ts, apps/cli/src/commands/edits.ts, apps/cli/src/main.ts, apps/cli/test/commands/**, apps/cli/README.md, apps/web/src/app/docs/cli/page.mdx | i355-daemon (the patch builder) | no | sonnet | + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| `apps/cli/src/runner/connection.ts` (message routing, `launches.sync`) | i355-daemon | #349 (share upload) adds `share.*` routing and likely a `features` entry; #361 (schedule) may add a frame too. Whichever lands second rebases; the `features` array is shared: each issue appends its own string. | +| `apps/cli/src/main.ts` | i355-commands | #349 (`demoflow share`) and #360 (`run --check`) add commands/flags: append-only, rebase. | +| `apps/web/src/app/docs/cli/page.mdx` | i355-commands | #352, #360 and #361 docs touch it: rebase. | + +## Risks + +- **High — a field that must not cross leaks into the model.** Mitigation: + the model is built field by field from an allow-list (Decision 2), with + the recursive key-scan test. +- **Medium — the patch lands on the wrong step.** Mitigation: the + `scenario-changed` guard (Decision 6) and building against the run's own + `scenario.json`. +- **Medium — `edits apply` reformats a hand-formatted scenario.** + Mitigation: the diff is printed first and `--dry-run` exists; formatting + preservation is an open question. + +## Open questions + +- Preserve the scenario file's formatting on `edits apply`? Default: no; + rewrite with two-space JSON and say so in the docs. diff --git a/docs/specs/356-editor-relay-api.md b/docs/specs/356-editor-relay-api.md new file mode 100644 index 00000000..d81cfc6e --- /dev/null +++ b/docs/specs/356-editor-relay-api.md @@ -0,0 +1,170 @@ +# Editor relay (API): edit model, save, re-render, progress, update a share + +Issue: [#356](https://github.com/AndreyBegma/DemoFlow/issues/356) +Depends on #355 (the Runner's `edits.*` and `render.*` frames) and #347 +(the `Share` model and the upload through the runner socket). + +## Summary + +The browser never talks to a Runner. This slice gives the run page's editor +(#357, #358) its HTTP API: read the edit model live from the run's machine, +save or reset the edits, get the export, start a re-render and follow it, and +replace a share's file with the new render. Nothing about a run's edits is +stored on the server (ADR-0020 §4); the only rows that change are the run's +`renders` and `stages` after a re-render, and a share's file after an update. + +## Scope + +### In scope + +- `apps/api/src/editor/` (new module): `editor.controller.ts`, + `editor.service.ts`, `editor.dto.ts`, `editor.integration.spec.ts`, + registered in `apps/api/src/app.module.ts`. +- `apps/api/src/runner/runner-socket.ts`: the frames of #355 (types and + class-validator messages), `features` on `launches.sync`. +- `apps/api/src/runner/runner-connections.service.ts`: routing the new + answers to the editor service; keeping each connection's `features`. +- `apps/api/src/runner/runner-socket.fixtures.ts`: a fake Runner that answers + the new frames. +- `apps/api/src/shares/`: one endpoint, `POST /shares/:id/update`, in the + module #347 creates. + +### Out of scope + +- The website (#357, #358). +- Storing the edit model, the edits or a render history (ADR-0020 §4, §6). +- Uploading the new render automatically after a re-render (ADR-0020 §6, + ADR-0008 §5). + +## API + +All endpoints need a session; the run is looked up with +`RunsService.find(userId, id)`, which matches `project: { userId }` +[Confirmed: `apps/api/src/videos/runs.service.ts`]. Another user's run, a +missing run, and a malformed id are all **404**, and nothing is sent to any +Runner. + +| Method and path | Body | Answer | +|---|---|---| +| `GET /runs/:id/editor` | — | 200 `model` of #355 | +| `PUT /runs/:id/edits` | `{ edits }` | 204 | +| `DELETE /runs/:id/edits` | — | 204 (reset: `edits.save` with `null`) | +| `GET /runs/:id/edits/export` | — | 200 `{ scenarioPatch, config, notExportable }` | +| `POST /runs/:id/render` | `{ formats? }` | 202 `{ state: 'rendering' }` | +| `GET /runs/:id/render` | — | 200 `{ state: 'idle' \| 'rendering' \| 'finished' \| 'failed', percent: number \| null, error: string \| null }` | +| `POST /shares/:id/update` | — | 202; the share keeps its token, expiry and view count | + +Errors, common to the run endpoints: + +| Status, `error` | When | +|---|---| +| 409 `runner-offline` | the run's machine has no socket | +| 409 `runner-outdated` | its `launches.sync` did not announce `'edits'` | +| 410 `artifacts-deleted` | `run.artifactsDeletedAt` is set [Confirmed: the field and the 410 pattern in `runs.controller.ts`] | +| 422 with the Runner's code | `edits-invalid`, `too-large`, `run-unfinished`, `no-recording`, `scenario-changed` | +| 409 `busy` | the machine is already re-rendering | +| 504 `runner-timeout` | no answer in time (Decision 4) | +| 404 `run-not-found` | the Runner does not know the run (as `artifacts.delete`, spec 233) | + +## Decisions + +1. **Validation.** `PUT /runs/:id/edits` takes an `EditsDto` with + class-validator decorators that mirror `RunEditsSchema`'s shape and + bounds (`ValidateNested`, `ArrayMaxSize`, `MaxLength`, `IsInt`, `Min`), + under the global `whitelist` and `forbidNonWhitelisted` pipe (CLAUDE.md). + The Runner is the authority on everything that needs the timeline + (`checkRunEdits`); its `edits-invalid` comes back as 422. *Why not import + `RunEditsSchema`:* `apps/api` depends only on `@demoflow/shared` + [Confirmed: `apps/api/package.json`]; the API already keeps its own copy of + the format enum (`RUN_FORMATS`, `projects.dto.ts`) for the same reason. + The request body is capped at 256 KiB. +2. **`formats`** on `POST /runs/:id/render` is validated exactly as on a + launch (`RUN_FORMATS`, 1–9, unique; spec 325). +3. **After `render.finished`** the service writes the new `renders` and the + `rendering` stage into the run row (`Run.renders`, `Run.stages`), so the + run page and the library show the new sizes and durations + [Confirmed: both are `Json?` columns, spec 263]. No migration. A + `render.finished` whose `rendering` is `failed` sets `state: 'failed'` and + leaves `renders` as they were. +4. **Timeouts** on the injected clock, swept like `artifacts.service.ts` + [Confirmed: `DELETE_TIMEOUT_MS` and its sweep]: 30 s for `edits.get` + (the Runner probes the source video, #355 Decision 2), 15 s for + `edits.save` and `edits.export`, 30 s until `render.started`, and + 20 minutes until `render.finished` (above the daemon's 15-minute cap, + spec 248). +5. **Render state is in memory**, one entry per run, like a launch + (spec 247): `idle` until a render starts; kept after `finished` or + `failed` until the next start or 10 minutes. A socket replaced while + rendering marks it `failed` with `runner-disconnected`. +6. **The model is relayed, not shaped.** The API validates the model's + envelope (sizes: at most 10,000 events, as `MAX_PROGRESS_STEPS` + [Confirmed: `runner-socket.ts`], 200 captions) and passes it through. It is + never logged and never written. +7. **Update a share.** `POST /shares/:id/update` checks that the share + belongs to the user (404 otherwise), that its run's machine is online, and + asks the Runner to upload the run's current file of the share's format + through #347's upload flow. The new file replaces the old one only once + the upload is complete; until then the link serves the old one. Token, + expiry, password and view count are unchanged. The quota of #347 applies + to the difference in size. [Unknown: #347's upload frame names; this slot + uses them as #347 lands them.] + +## Acceptance criteria + +API integration tests with the fake Runner socket and a fake clock: + +- [ ] **Authorization:** for a run of user B, user A gets 404 from every + endpoint in the table (`GET editor`, `PUT`/`DELETE edits`, `GET export`, + `POST`/`GET render`), and the fake Runner of user B receives no frame; + `POST /shares/:id/update` on B's share is 404 for A. +- [ ] `GET /runs/:id/editor` sends `edits.get { requestId, runId }` and + returns the Runner's model unchanged; offline → 409 `runner-offline`; a + machine without `features: ['edits']` → 409 `runner-outdated`; no + answer in 30 s → 504. +- [ ] `PUT /runs/:id/edits` with a valid body sends `edits.save` with that + object; an unknown key, 201 captions, a 121-character caption, or a + body over 256 KiB is 400 and sends nothing; the Runner's + `edits-invalid` is 422. +- [ ] `DELETE /runs/:id/edits` sends `edits.save` with `edits: null`. +- [ ] `POST /runs/:id/render` → 202, then `GET` shows `rendering` with the + latest `percent`; `render.finished` updates `Run.renders` and + `stages.rendering` and `GET` shows `finished`; the Runner's `busy` is + 409. +- [ ] A run with `artifactsDeletedAt` is 410 on every run endpoint. +- [ ] `POST /shares/:id/update` keeps the share's token, `expiresAt` and + view count, and serves the new file only after the upload completed. +- [ ] `parseClientMessage` accepts the new answers and rejects malformed ones + (`runner-socket.spec.ts`). +- [ ] Existing runner socket, launches, artifacts, video and share tests are + green; `bun run check`, `bun run test`, `bun run build` are green. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i356-editor | the editor module and the socket frames | apps/api/src/editor/**, apps/api/src/app.module.ts, apps/api/src/runner/runner-socket.ts, apps/api/src/runner/runner-socket.spec.ts, apps/api/src/runner/runner-connections.service.ts, apps/api/src/runner/runner-socket.fixtures.ts | #355 merged | yes | sonnet | +| i356-share-update | `POST /shares/:id/update` | apps/api/src/shares/** (the update endpoint and its test only) | i356-editor, #347 merged | no | sonnet | + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| `apps/api/src/runner/runner-socket.ts`, `runner-connections.service.ts`, `runner-socket.fixtures.ts` | i356-editor | #347 (share upload frames) and #362 (scheduled check runs) also add frames and routing: whichever lands second rebases. `features` on `launches.sync` is one shared array. | +| `apps/api/src/app.module.ts` | i356-editor | #347 and #362 add their modules: one line each. | +| `apps/api/src/shares/**` | #347 | i356-share-update adds one endpoint after it merges. | +| `apps/api/prisma/schema.prisma` | nobody here | #347 and #362 change it; this issue needs no migration. | + +## Risks + +- **Medium — the model is large for a long run.** Mitigation: the size caps + of Decision 6; a run over 10,000 steps is refused by the Runner already + (`MAX_PROGRESS_STEPS`). +- **Low — the DTO and `RunEditsSchema` drift.** Mitigation: an integration + test sends the fixtures of `packages/core/test/edits.spec.ts`'s valid + cases through the DTO. + +## Open questions + +- Should a re-render be possible while a website-started run of the same + project is running? Default: yes; the daemon's `busy` covers only + re-renders, and runs and renders are separate children. diff --git a/docs/specs/357-timeline-editor.md b/docs/specs/357-timeline-editor.md new file mode 100644 index 00000000..ce2bed18 --- /dev/null +++ b/docs/specs/357-timeline-editor.md @@ -0,0 +1,168 @@ +# Timeline editor with an in-browser preview on the run page + +Issue: [#357](https://github.com/AndreyBegma/DemoFlow/issues/357) +Depends on #356 (the editor API). + +## Summary + +The owner wants to fix a video on the website without re-recording: retime +and retype captions, choose which steps zoom and how much, retitle the cards, +change the background and the window, and trim the run with any number of +freely placed cuts. Everything is dragged on a timeline and previewed at once +in the browser over the video already playing; the exact result comes from +**Render**, which the machine does (ADR-0020). This slice is the editor: +loading the model, editing it in the browser, saving, rendering and showing +progress. Export, reset and the share update are #358. + +## Scope + +### In scope + +- `apps/web/src/app/app/projects/[id]/runs/[runId]/edit/page.tsx` (new): the + editor route. +- `apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx`: an **Edit** + button next to Run again / Delete [Confirmed: the page renders + `RunAgain` and `DeleteRun`]. +- `apps/web/src/components/editor/` (new): the editor shell, the timeline and + its tracks, the inspector, the preview overlay, the render bar. +- `apps/web/src/lib/edits.ts` and `edits.test.mjs` (new): the edit state as + pure functions (time mapping, drag, snapping, merge of cuts, dirty check, + the request body). +- `apps/web/src/lib/api.ts`: client calls for the endpoints of #356. +- `apps/web/src/i18n/en.ts`: `editor.*`. + +### Out of scope + +- Export, reset and update share (#358). +- An exact preview: the browser draws an approximation (Decision 5). +- Undo history beyond the current session (Decision 7). +- Editing on a phone. The editor needs a pointer and a wide window; below + 768 px it shows a notice and a link back. + +## UI + +The page: the player on top, the timeline under it, an inspector on the +right (Glass UI `SidePanel` [Confirmed: exported by `@andrewbehma/glass-ui`]). +Content surfaces stay solid; glass is for the floating render bar only +(vision §9). + +- **Timeline**, in output time of the current render, with a playhead that + follows the video and seeks on click. Tracks, top to bottom: + - **Steps:** one block per event from `startMs` to `endMs`, labelled by + action; a targeted step shows a zoom marker when it zooms. + - **Captions:** one block per caption; drag to move, drag either edge to + retime, double-click to edit the text inline (Glass UI `InlineEdit`), a + button to add one at the playhead, Delete to remove. + - **Trim and cuts:** the two trim handles at the ends; drag on the track to + draw a cut; drag a cut's edges or body; Delete removes it. Overlapping or + touching cuts merge. + - **Cards:** intro, scene and outro blocks, read-only in position. +- **Inspector**, for the selection: a step's zoom (`Toggle` + `Slider` + 1–3, default "renderer default"); a caption's text; the cards (intro + on/off, title, subtitle; scenes on/off; outro on/off, title, CTA); style + (background preset `SegmentedControl` of the six presets, or a colour; window + on/off, corner radius `Slider`, shadow `Toggle`). Limits as in + `RunEditsSchema` (#353): captions 1–120 characters, card text 1–80. +- **Render bar:** **Save** (enabled when dirty), **Render** (saves first), + a format choice defaulting to the current render's formats (as the launch + dialog's, spec 327 — the same component if it can be shared), and progress + from `GET /runs/:id/render` (`Progress` with `percent`, indeterminate when + null). On `finished` the player reloads the new file; on `failed` a + `Banner` with the error. +- **Unavailable states**, each a `SectionUnavailable` with the reason and, + where it helps, a link: machine offline (`runner-offline`), daemon too old + (`runner-outdated`, "update the CLI"), artifacts deleted (410), run not + renderable (`no-recording`, `run-unfinished`). + +## Decisions + +1. **Edits are kept in timeline ms; the timeline is drawn in output ms.** The + page converts through the model's `timeMap` (#355). A drag in output time + maps to timeline time through the segment under the pointer. Inside a card + segment there is no timeline time: a caption cannot start in a card, and a + cut handle snaps to the card's edge. *Why:* ADR-0020 §1 fixes edits to the + timeline; the person sees and drags the video they watch. +2. **The first state is what the video shows.** Without `edits`, the caption + list is seeded with every caption the model has (step captions, + `pageCaptions`), at the times the renderer uses (a step caption from the + step's start to its end plus 800 ms, a page caption for 3 s, each cut by + the next [Confirmed: `TIMING.captionTailMs`, `pageCaptionMs` in + `plan.ts`]), so saving without a change keeps every caption (#353, + Risks). +3. **Only what changed is sent.** The request body holds `captions` only when + the list differs from the seed, `zoom` only for steps whose value + differs from the timeline's, and so on; an unchanged editor saves `{ + schemaVersion: 1 }` — or nothing: Save stays disabled. +4. **Zoom only on a step.** The zoom controls exist only for events with a + `box` (ADR-0012 §2); the timeline offers no free-time zoom (ADR-0020 §2). +5. **The preview is approximate and says so.** Over the playing video the page + draws: the caption text in a band like the renderer's; a rectangle for the + zoom target and the zoom strength as a label (no actual zoom of the + picture); grey veils over cut and trimmed-off ranges, and playback jumps + over them; the background colour and corner radius in a small swatch, not + on the video. A note under the player: "Preview — render for the exact + result". *Why not more:* the video playing is the *current render*, with + its own captions, zoom and cards baked in; drawing a faithful second + composite in the browser would be a second renderer (ADR-0005). +6. **Playback uses a native `<video>` element** with the same relay URL as the + run page (`apps/web/src/lib/playback.ts` [Confirmed]). The editor needs + `currentTime`, seeking and `timeupdate`, which `VideoPlayerProps` does not + expose [Confirmed: `src`, `shape`, `onError` only]. The run page keeps + the Luna adapter. +7. **Leaving with unsaved edits** asks for confirmation (`beforeunload` and a + `ConfirmDialog` on in-app navigation). Undo/redo (Ctrl+Z / Ctrl+Shift+Z) + works within the page's session. +8. **A failed run** can be edited, but the trim's end handle stops at the + failed step and a cut cannot cover it (#354, `trim-hides-failure`); the + track shows why on hover. + +## Acceptance criteria + +`apps/web/src/lib/edits.test.mjs` (`node --test`, like the other lib tests +[Confirmed: `apps/web/src/lib/*.test.mjs`]): + +- [ ] Output → timeline → output round-trips within 1 ms on a map with idle + segments and two cards; a time inside a card maps to its edge. +- [ ] Seeding: a model with two step captions and one page caption gives + three captions at the renderer's times; an unchanged state is not dirty + and builds no `captions` key. +- [ ] Drawing a cut over another merges them; a cut over the failed step of a + failed model is refused; trim handles never cross. +- [ ] Moving a caption past the next one keeps the list ordered and + non-overlapping (the next one is pushed or the move stops — the + function documents which). + +Manual check on staging with a paired machine (written in the pull request): + +- [ ] Edit opens the editor for a run; captions, a zoom, a cut, an outro + title and a background change, Save, Render: the new video has them. +- [ ] Machine offline: the editor shows the offline state and no tracks. +- [ ] Another user's run id in the URL is a 404 page (the API answers 404). +- [ ] `bun run check` and `bun run build` are green. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i357-state | edit state and API calls | apps/web/src/lib/edits.ts, apps/web/src/lib/edits.test.mjs, apps/web/src/lib/api.ts | #356 merged | yes | opus | +| i357-ui | the editor page and components | apps/web/src/app/app/projects/[id]/runs/[runId]/edit/**, apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx, apps/web/src/components/editor/**, apps/web/src/i18n/en.ts | i357-state | no | sonnet | + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| `apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx` | i357-ui | #350 (Share dialog) adds a button to the same row; #358 adds nothing here. Rebase on whichever lands first. | +| `apps/web/src/i18n/en.ts` | i357-ui | #350, #351, #358, #363 add their own keys: append-only blocks, rebase. | +| `apps/web/src/lib/api.ts` | i357-state | #350, #351, #363 add calls: rebase. | + +## Risks + +- **Medium — the preview misleads.** It cannot show the real zoom or the + card look. Mitigation: Decision 5's note, and Render is one click away. +- **Medium — a large timeline is slow to drag.** Mitigation: tracks render + only the visible window; the state functions are pure and tested. + +## Open questions + +- Should the timeline zoom horizontally for long runs? Default: yes, with + Ctrl+scroll and a fit-to-width button. diff --git a/docs/specs/358-edits-export-reset-share.md b/docs/specs/358-edits-export-reset-share.md new file mode 100644 index 00000000..27448829 --- /dev/null +++ b/docs/specs/358-edits-export-reset-share.md @@ -0,0 +1,121 @@ +# Export edits to the scenario and the config, reset edits, update the share + +Issue: [#358](https://github.com/AndreyBegma/DemoFlow/issues/358) +Depends on #357 (the editor page) and, for the share button, #350 (the +Share dialog and the run's share state on the run page). + +## Summary + +Edits live with the run (ADR-0020 §1); the next run of the scenario knows +nothing of them until the person carries them into the repository. The +website never writes there (§5). This slice adds the editor's three remaining +actions: **Export** (show the scenario patch and the config fragment, copy +them, and the one command that applies them on the machine), **Reset edits** +(back to the original render), and **Update share link** (replace a shared +copy with the new render, keeping the link). + +## Scope + +### In scope + +- `apps/web/src/components/editor/export-dialog.tsx` (new), + `reset-edits.tsx` (new), `update-share.tsx` (new). +- `apps/web/src/components/editor/render-bar.tsx` (from #357): the three + buttons. +- `apps/web/src/lib/edits-export.ts` and `edits-export.test.mjs` (new): + formatting the patch and the fragment for display and copy. +- `apps/web/src/lib/api.ts`: `getEditsExport`, `resetEdits`, `updateShare`. +- `apps/web/src/i18n/en.ts`: `editor.export.*`, `editor.reset.*`, + `editor.share.*`. + +### Out of scope + +- Writing any repository file from the website (ADR-0020 §5). +- Exporting trims, cuts or free-timed captions: the scenario cannot express + them (#355, Decision 6). +- Automatic share updates (ADR-0020 §6). + +## UI + +- **Export** (Glass UI `Dialog`): three sections. + 1. *Scenario:* the JSON Patch from `GET /runs/:id/edits/export`, in a + `CodeBlock` with copy, and the file it applies to (the run's + `scenarioPath` [Confirmed: on the run row]). + 2. *Config:* the `render` fragment as JSON, with copy, and the note "merge + into `demoflow.config.json`". + 3. *Apply on your machine:* `npx demoflow edits apply <runId>` and, when the + fragment is not empty, the same with `--config`, each with copy; a line + that `--dry-run` shows the diff first. + - Below, **Not exported**: each `notExportable` entry in plain words + ("Caption at 0:12 is not on a step", "Cuts stay with this run"). + - `scenario-changed` (422) shows a `Banner`: the scenario file has changed + since this run; run it again to export. + - With no saved edits, Export is disabled with a tooltip. +- **Reset edits** (`ConfirmDialog`): "Remove every edit of this run? The next + render is the original." Then `DELETE /runs/:id/edits`, the editor reloads + its model, and the person is offered **Render** to restore the original + file now. *Why not render automatically:* rendering spends the machine's + time; the person may want to reset and edit again. +- **Update share link**: shown only when the run has a share whose format the + last render wrote. It calls `POST /shares/:id/update` and shows the result + with a `Toast`; disabled while a render runs, and while the render is older + than the saved edits (the page knows: it saved after the last + `finished`), with the tooltip "Render first". + +## Decisions + +1. **Copy, not download.** The patch and the fragment are small text; a + person pastes them into an editor or an agent prompt. *Why also the + command:* it is the one path that applies the patch exactly as the Runner + built it (#355, Decision 8). +2. **The fragment is shown as nested JSON** (`{ "render": { … } }`), so it + can be merged by hand into the config's root object. +3. **Reset does not touch a share.** A shared copy stays what it was until + the person updates it (ADR-0020 §6). +4. **Update share uses the share's own format**, never the editor's format + choice; if the last render did not write that format, the button explains + that the share's format must be rendered first. + +## Acceptance criteria + +`apps/web/src/lib/edits-export.test.mjs` (`node --test`): + +- [ ] A patch with two ops and a fragment format as pretty JSON with + two-space indentation; an empty fragment is reported as empty. +- [ ] Each `notExportable` kind has a sentence; an unknown kind falls back to + its `reason`. + +Manual check on staging with a paired machine (in the pull request): + +- [ ] After saving a caption and a zoom on top-level steps, Export shows a + patch with those two paths and the apply command; running + `npx demoflow edits apply <runId>` on the machine changes the scenario + file accordingly. +- [ ] A cut shows under Not exported. +- [ ] Reset, then Render: the video is the original. +- [ ] With a share of the run, Render, then Update share link: the same + `/s/<token>` plays the new video; the view count is unchanged. +- [ ] `bun run check` and `bun run build` are green. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i358-actions | export, reset, update share | apps/web/src/components/editor/export-dialog.tsx, apps/web/src/components/editor/reset-edits.tsx, apps/web/src/components/editor/update-share.tsx, apps/web/src/components/editor/render-bar.tsx, apps/web/src/lib/edits-export.ts, apps/web/src/lib/edits-export.test.mjs, apps/web/src/lib/api.ts, apps/web/src/i18n/en.ts | #357, #350 merged | yes | sonnet | + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| `apps/web/src/i18n/en.ts`, `apps/web/src/lib/api.ts` | this issue | #350, #351, #363 add their own blocks: rebase. | +| `apps/web/src/components/editor/render-bar.tsx` | #357, then this issue | nobody else | + +## Risks + +- **Low — a person pastes the patch into the wrong file.** Mitigation: the + dialog names the file, and the command is the recommended path. + +## Open questions + +- Offer a "Copy as agent prompt" (patch plus instructions)? Default: no; + the MCP has no edits tool yet (#355, Out of scope). diff --git a/docs/specs/359-editor-docs.md b/docs/specs/359-editor-docs.md new file mode 100644 index 00000000..d4c2a9b2 --- /dev/null +++ b/docs/specs/359-editor-docs.md @@ -0,0 +1,102 @@ +# Docs: editing a video on the website + +Issue: [#359](https://github.com/AndreyBegma/DemoFlow/issues/359) +Depends on #358 (the last editor slice); describes #353–#358 as they landed. + +## Summary + +The editor (#357, #358) changes how a person fixes a video: edit, render, +export into the repository. The website's docs (`/docs`, spec 179) need one +page for it and two corrections: what crosses to the server while the editor +is open (ADR-0020 §4), and `edits.json` in a run directory. + +## Scope + +### In scope + +- `apps/web/src/app/docs/editor/page.mdx` (new): the page. +- `apps/web/src/lib/docs-nav.ts`: an entry `{ href: '/docs/editor', label: + 'docs.nav.editor' }` after `/docs/runner` [Confirmed: `DOCS_NAV` and its + label union]. +- `apps/web/src/lib/docs-nav.test.mjs`: the new entry [Confirmed: the test + checks every entry has a page file]. +- `apps/web/src/i18n/en.ts`: `docs.nav.editor`. +- `apps/web/src/app/docs/runner/page.mdx`: a short section "Editing from the + website" (what the website may ask the machine, what crosses, that nothing + is stored), linking to the new page. +- `apps/web/src/app/docs/config/page.mdx`: one paragraph on `edits.json` + overriding `render.*` for one run, and that it is never read from the + config. + +### Out of scope + +- The CLI page: `demoflow render --progress` and `demoflow edits apply` are + documented by #355. +- The sharing page (#352). + +## The page + +Sections, in this order, with screenshots of the editor on the fixture +project (`apps/fixture`): + +1. **What you can change** — captions (text and timing), zoom per step, + intro and outro text, scene cards on or off, background and window, trim + and cuts. What you cannot: zoom at a free time (ADR-0012), steps, URLs, + anything the scenario runs. +2. **Preview and Render** — the preview is approximate; Render runs on your + machine with the project's current config plus the edits, and replaces the + run's files. +3. **Where edits live** — `runs/<runId>/edits.json` on the machine; the + server keeps nothing; the next run of the scenario does not know them. +4. **Export to the repository** — the patch, the config fragment, + `npx demoflow edits apply <runId>` (`--dry-run`, `--config`), and what is + never exported (trims, cuts, free-timed captions, steps from a `repeat` + or an `include`). +5. **Reset** — and that Reset does not change a shared copy. +6. **Shared links** — Update share link keeps the URL, expiry and views. +7. **When the editor is unavailable** — machine offline, CLI too old, + files deleted, run not renderable; what to do for each. +8. **Privacy** — while the editor is open, step times and target positions + cross to your browser through the server and are not stored + (ADR-0020 §4). + +## Decisions + +1. **One page, not a section of the runner page.** The editor is a task of + its own ("fix my video"), and the runner page is about pairing and the + daemon. +2. **Screenshots are from the fixture app**, never from a real application, + like the other docs pages [Unknown: whether the docs keep screenshots in + `apps/web/public/docs/`; follow what existing pages do]. + +## Acceptance criteria + +- [ ] `/docs/editor` renders, is in the side navigation after Runner, and + `docs-nav.test.mjs` passes. +- [ ] Every command and flag on the page exists in `apps/cli/src/main.ts` + (`edits apply`, `--dry-run`, `--config`, `render --progress`). +- [ ] The runner page's new section and the config page's paragraph link to + `/docs/editor`. +- [ ] `bun run check` and `bun run build` are green. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i359-docs | the docs | apps/web/src/app/docs/editor/**, apps/web/src/lib/docs-nav.ts, apps/web/src/lib/docs-nav.test.mjs, apps/web/src/i18n/en.ts, apps/web/src/app/docs/runner/page.mdx, apps/web/src/app/docs/config/page.mdx | #358 merged | yes | sonnet | + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| `apps/web/src/lib/docs-nav.ts`, `docs-nav.test.mjs`, the `docs.nav.*` keys | this issue | #352 (sharing docs) and #364 (schedule docs) add entries: one line each, rebase. | +| `apps/web/src/app/docs/runner/page.mdx`, `config/page.mdx` | this issue | #352, #364 and #365's docs may add sections: rebase. | + +## Risks + +- **Low — the docs describe a behaviour that changed during review.** + Mitigation: the page is written last, against merged code. + +## Open questions + +None. diff --git a/docs/specs/360-run-check-mode.md b/docs/specs/360-run-check-mode.md new file mode 100644 index 00000000..e1802a00 --- /dev/null +++ b/docs/specs/360-run-check-mode.md @@ -0,0 +1,208 @@ +# `demoflow run --check`: run and verify without recording or rendering + +Issue: [#360](https://github.com/AndreyBegma/DemoFlow/issues/360) +Depends on: nothing. Decision record: [ADR-0021](../adr/0021-scheduled-checks.md). + +## Summary + +Phase 8 checks every demo of a project on a schedule and marks a scenario +stale when it breaks (ADR-0021). A check must not record or render: nobody +watches it, and a video a day per scenario fills the disk. Today +`demoflow run` always records, and renders whenever a video exists +(`apps/cli/src/commands/run.ts`, `execute()`) [Confirmed]. + +This slice adds check mode to the engine and the CLI, a check pass over a +whole project, the daemon's handling of a check pass the website starts, and +the API's acceptance of a reported check run. The schedules themselves are +specs 361 (config, daemon) and 362 (website, API). + +## Scope + +### In scope + +- `packages/engine/src/run.ts`: a `record?: boolean` run option (default + `true`). With `false` the recorded context is opened with + `toContextOptions(recording, version, { video: false })`, the same option + the off-camera context already uses (ADR-0018) [Confirmed], no sync mark is + recorded, and the `recording` stage is `skipped`. +- `packages/engine/test/**`: its tests. +- `apps/cli/src/main.ts`, `apps/cli/src/commands/run.ts`: the `--check` and + `--exclude` flags and the check pass (Decisions 2–4). +- `apps/cli/src/runs-report/report.ts`: `kind: 'check'` on a reported check + run (Decision 5). +- `apps/cli/src/runner/launch/**`, `apps/cli/src/runner/connection.ts`: the + `check.start` request and `checks: true` in `launches.sync` (Decision 6). +- `apps/cli/test/**`: their tests (Vitest under Node). +- `apps/api/prisma/schema.prisma`: `Run.kind`; migration + `apps/api/prisma/migrations/20261026120000_run_kind/`. +- `apps/api/src/projects/projects.dto.ts` (`RunReportDto.kind`), + `apps/api/src/projects/projects.service.ts` and + `apps/api/src/projects/runner-runs.controller.ts`: store it and return it + with a run. +- `apps/cli/README.md`: the flags. + +### Out of scope + +- Any schedule (specs 361, 362) and the stale state (spec 362). +- The website starting a check pass: the daemon side is here, the API side is + spec 362. +- Showing check runs differently on the website (spec 363). +- An MCP tool for a check. No source asks for one; `demoflow check` and the + MCP `check_project` stay what they are (spec 266). +- `--check` with `--format`, `--headed`: refused (Decision 2). + +## Decisions + +1. **The engine records nothing in check mode** (ADR-0021 §1). `runScenario` + gets `record: false`: steps and verifications run exactly as today, in a + context without `recordVideo`; no sync mark (`recordSyncMark` needs the + video); `stages.recording = { status: 'skipped' }`. The timeline events + are still written: they cost little and carry the failed step. The status + is `deriveRunStatus(stages)` as for every run (ADR-0004 §3–4). +2. **The flag.** `demoflow run --check [scenario] [--exclude <id>]... [--json]`, + with every existing flag except `--format` and `--headed`, which are refused + with `CommandError` `check-flag` (exit 2) before anything runs. + - With `<scenario>`: one check run of that file. + - Without it: a **check pass** of every `demoflow/**/*.demo.json` under + the project root, sorted by scenario id, minus `--exclude` ids. The + daemon's scenario listing (`apps/cli/src/runner/launch/list.ts`) already + walks those files with its limits (`LIST_MAX_SCENARIOS` and the others); + the pass reuses that walk, not a second one. An `--exclude` id that is no + scenario is ignored (a deleted scenario must not break a schedule). + - `<scenario>` is optional only with `--check`; without it the command is + refused as today. +3. **One application start per pass** (ADR-0021 §3). `devCommand` is started + once before the first scenario and stopped after the last, by the same + start/stop the single run uses. A scenario whose readiness fails does not + stop the pass; an application that fails to start fails every scenario of + the pass with the same readiness error, each in its own `result.json`. +4. **Results.** Each scenario has its own run directory and `result.json`, + with `renders: []` and `rendering: skipped`, and is reported on its own + (Decision 5), so the run library and the stale state stay per scenario. + - Text output: one summary line per scenario, then `N passed, M failed`. + - `--json`: one object `{ "check": true, "runs": [<the run JSON of each>] }`. + A single-file `--check --json` prints the same shape with one entry. + - Exit code: `0` when every run passed, the existing stage-failed code when + any failed, `2` for a refusal. + - `--run-id` is accepted only with a single scenario (the daemon's plumbing, + spec 248); a pass names its run directories as `demoflow run` does. +5. **Reporting.** A check run's report is the run report of spec 178 plus + `kind: 'check'`. Ordinary runs send no `kind`. The API takes `kind` as + optional `@IsIn(['check'])`; `Run.kind` is a nullable column (`null` is an + ordinary run), returned with every run the API lists or shows. + - *Why the API change is here:* the global `ValidationPipe` has + `forbidNonWhitelisted` (CLAUDE.md), so a CLI that sends `kind` to an API + without the field is refused with 400 and the run is never reported. The + API part of this slice merges first (Parallel plan). + - *Why a column, not a flag in `stages`:* the run library and the stale + state filter on it; a JSON field would be read in application code only. +6. **The daemon runs a check pass the website starts** (ADR-0021 §2). + - `launches.sync` gains `checks: true` when the daemon handles launches + (beside `runOptions`, `apps/cli/src/runner/connection.ts:185`). + - A new server frame `check.start { requestId, rootPath, exclude: string[] }`. + The daemon checks it like `run.start` (spec 248, Decision 3): the root is + a key into the machine's registry, `exclude` is at most + `LIST_MAX_SCENARIOS` strings, each a valid scenario id + (`apps/cli/src/runner/launch/scenario-id.ts`). Any other field, or any + invalid entry, refuses the whole request with `check.error { requestId, code }` + and spawns nothing. + - It spawns `run --check --json --progress --project <root>` plus + `--exclude <id>` for each checked id, and nothing else from the message. + - It counts as the machine's one active launch (the API's `runner-busy`, + `apps/api/src/launches/launches.service.ts`) and answers + `check.started { requestId }` and `check.finished { requestId, passed, failed }` + (counts). Cancel is the existing launch cancel with the same `requestId`. + - The 15-minute launch cap (spec 248, Decision 9) applies per scenario, not + per pass; the pass as a whole is capped at 2 hours. + +## Data / Schema + +```prisma +enum RunKind { + check +} + +model Run { + // … + // Spec 360: `check` for a run made with `demoflow run --check`; null otherwise. + kind RunKind? +} +``` + +Migration `20261026120000_run_kind`: `CREATE TYPE "RunKind"` and +`ALTER TABLE "Run" ADD COLUMN "kind" "RunKind"`. No backfill. + +## API + +- `POST /runner/runs` (`RunReportDto`): optional `kind: 'check'`. +- Every response that carries a run (the project's runs list, the run page's + details) gains `kind: 'check' | null`. + +## Configuration + +None. Check mode reads the same `demoflow.config.json`. + +## Acceptance criteria + +- [ ] `demoflow run --check demoflow/customers.demo.json` on the fixture passes, + writes `result.json` with `recording: skipped`, `rendering: skipped`, + `renders: []`, and leaves no video file in the run directory. +- [ ] The fixture's `failing` scenario under `--check` exits with the + stage-failed code and its `result.json` has `verification: failed`. +- [ ] `demoflow run --check` with no scenario runs every fixture scenario, starts + the application once (asserted through the start hook in tests), and + prints one line per scenario and the totals. +- [ ] `--exclude login.demo.json` leaves that scenario out; an unknown id is ignored. +- [ ] `--check --format gif` and `--check --headed` are refused with exit 2 + and write nothing. +- [ ] A reported check run arrives with `kind: 'check'` and the API stores it; + an ordinary run is stored with `kind = null`; a report with + `kind: 'video'` is refused with 400. +- [ ] The daemon sends `checks: true` in `launches.sync`; a `check.start` with + an unregistered root, an extra field or an invalid exclude id is + refused with `check.error` and spawns nothing (unit test on the spawn + fake). +- [ ] A valid `check.start` spawns exactly + `run --check --json --progress --project <root> [--exclude <id>]...`. +- [ ] The engine, CLI and package-smoke suites pass on Linux, macOS and Windows. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i360-api | `Run.kind`, the migration, the report DTO | apps/api/prisma/schema.prisma, apps/api/prisma/migrations/20261026120000_run_kind/**, apps/api/src/projects/** | — | yes | sonnet | +| i360-engine | `record: false` | packages/engine/src/run.ts, packages/engine/test/** | — | yes | sonnet | +| i360-cli | `--check`, the pass, the report's `kind` | apps/cli/src/main.ts, apps/cli/src/commands/run.ts, apps/cli/src/runs-report/report.ts, apps/cli/test/commands/**, apps/cli/test/runs-report/**, apps/cli/README.md | i360-engine, i360-api | no | opus | +| i360-daemon | `check.start`, `checks` in `launches.sync` | apps/cli/src/runner/launch/**, apps/cli/src/runner/connection.ts, apps/cli/test/runner/** | i360-cli | no | sonnet | + +`i360-cli` is `opus`: the pass's handling of one application across several +runs (Decision 3) has to be fitted into `runCommand`'s start/stop and signal +handling, which this spec does not lay out line by line. + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| apps/api/prisma/schema.prisma | i360-api | do not open it (spec 362 adds its own tables after this merges) | +| apps/cli/src/runner/connection.ts | i360-daemon | do not open it | +| apps/cli/src/commands/run.ts | i360-cli | do not open it | + +## Risks + +- **Medium — the name.** `demoflow check` (spec 266) is the project check and + `demoflow run --check` is a check run. Mitigation: the help text of both + says what each does; the website and docs call this a "check run" and the + pass a "check pass". +- **Medium — a pass that hangs.** One stuck scenario holds the machine's only + launch slot. Mitigation: the per-scenario 15-minute cap and the 2-hour pass + cap; the cancel path is the existing one. +- **Low — timing without video.** Some steps wait on the video clock today + [Unknown]. Mitigation: the engine tests run the fixture scenarios with + `record: false` on all three OS. + +## Open questions + +- Should a check pass stop at the first failure? Default: no, every scenario + runs, so the stale state is complete. + +Depends on nothing. diff --git a/docs/specs/361-config-schedule.md b/docs/specs/361-config-schedule.md new file mode 100644 index 00000000..64597192 --- /dev/null +++ b/docs/specs/361-config-schedule.md @@ -0,0 +1,177 @@ +# `schedule` in `demoflow.config.json`: the runner daemon runs check passes on a schedule + +Issue: [#361](https://github.com/AndreyBegma/DemoFlow/issues/361) +Depends on: #360 (`demoflow run --check` and the check pass). Decision record: [ADR-0021](../adr/0021-scheduled-checks.md). + +## Summary + +A team that commits its demos wants them checked without anyone remembering +to (ADR-0021). This slice adds a `schedule` block to the project config and a +scheduler inside the runner daemon that runs a check pass (spec 360) of the +project at the due time, with one catch-up pass after the machine was off or +asleep. It works without an account. When the machine is paired, the daemon +tells the website which schedule each project has, so the project page can +show it read-only (spec 363); the results reach the website as ordinary run +reports with `kind: 'check'` (spec 360). + +## Scope + +### In scope + +- `packages/core/src/project-config.ts`: `ScheduleConfigSchema` and the + optional `schedule` key of `ProjectConfigSchema`; `packages/core/src/index.ts` + exports; `packages/core/schemas/project-config.schema.json` regenerated + (`packages/core/scripts/generate-schemas.ts`); `packages/core/test/**`. +- `packages/core/src/schedule.ts` (new): `lastDueSlot(schedule, now, zone)`, + pure, no Node APIs (ADR-0001). +- `apps/cli/src/runner/schedule/**` (new): the scheduler, its state file and + the roots it watches. +- `apps/cli/src/runner/daemon.ts`: start the scheduler; the local mode + (Decision 5). +- `apps/cli/src/commands/run.ts`: record the run's root in the local roots + file (Decision 4) — one call, after the run directory is created. +- `apps/cli/src/runner/connection.ts`: send `schedules.sync` (Decision 6). +- `apps/cli/src/runner/command.ts`: `demoflow runner status` prints each + scheduled project's next and last check. +- `apps/cli/test/**`, `apps/cli/README.md`. + +### Out of scope + +- The API storing `schedules.sync` and showing it: specs 362 and 363. The API + ignores an unknown frame type until then (`parseClientMessage`, + `apps/api/src/runner/runner-socket.ts`) [Confirmed], so this slice can merge + first. +- Website schedules (spec 362). +- Desktop notifications. The owner chose site-only alerts; locally the result + is in `demoflow runs` and the daemon log. + +## Decisions + +1. **The config shape** (ADR-0021 §5; owner, 2026-10-26: presets and a time). + + ```json + "schedule": { + "cadence": "weekdays", + "at": "09:30", + "exclude": ["demoflow/wip.demo.json"] + } + ``` + + - `cadence`: `daily` | `weekdays` (Monday–Friday) | `weekly`. + - `weekday`: `mon`…`sun`, required with `weekly`, refused otherwise. + - `at`: `HH:MM`, 24-hour, machine-local time. + - `exclude`: optional, scenario ids relative to the root, at most 100. + - A strict object: any other key is a config error, like every config block. + - No time zone in the file: a committed schedule means "09:30 wherever + this machine is". The daemon reports its zone name to the website + (Decision 6). +2. **Due slots.** `lastDueSlot(schedule, now, zone)` returns the latest slot + at or before `now`. A pass is due when that slot is later than the last + pass's start for this root. One pass per due slot; a machine that missed + several slots runs **one** pass (ADR-0021 §5, owner: one catch-up run). + DST: a local time that does not exist that day runs at the next valid + minute; one that repeats runs once. +3. **The scheduler** ticks once a minute and on daemon start. For each + watched root (Decision 4) it loads the config with `loadProjectConfig`; a + root without `schedule`, or whose config fails to load, is skipped and the + failure logged once per change. A due pass is queued; passes run one at a + time, and never while a website-started launch runs (the daemon's one + launch slot, spec 248). It spawns + `run --check --json --project <root> [--exclude <id>]...` through the same + `SpawnRun` as launches. The state file + `<runner dir>/schedule.state.json` keeps, per root, the last pass's start + and its counts; it is written before the spawn so a crash does not repeat + the slot. + - *Why a minute:* the cadence is daily at most; a minute is the precision + the person sets. + - *Wake from sleep:* a tick after a sleep sees a missed slot and runs the + one catch-up pass; no OS wake API is needed. +4. **Which projects it watches.** The union of the registry of reported roots + (`knownRoots`, `apps/cli/src/runs-report/reported-runs.ts`) [Confirmed] and + a new local file `<runner dir>/local-roots.jsonl` that every `demoflow run` + appends its canonical root to, deduplicated, last 500 lines. + - *Why a second file:* the registry is written only when a report reached + the server, and a machine without an account reports nothing; its + schedules would never fire. A root in `local-roots.jsonl` is only ever + used to run that root's own committed config locally, so it adds no + power to the website (ADR-0016 §2 still keys website requests on the + reported registry only). +5. **Local mode** (owner: works without login). Today `runForeground` exits + with `EXIT_DAEMON_NOT_LOGGED_IN` without credentials + (`apps/cli/src/runner/daemon.ts:67`) [Confirmed]. With no credentials and + at least one watched root that has a `schedule`, the daemon runs the + scheduler only: no socket, no relay, no launches. `runner status` says + "local mode: scheduled checks only". Without credentials and with no + schedule anywhere it exits as today. `demoflow login` later and a daemon + restart switch it to the full mode. +6. **`schedules.sync`** (ADR-0021 §7). When connected, after `launches.sync` + and whenever a watched root's schedule changes (checked on the tick), the + daemon sends + `{ type: 'schedules.sync', zone: <IANA name>, projects: [{ rootPath, schedule | null }] }` + for the roots of the **reported registry only** (Decision 4's local-only + roots are not sent). `schedule` is the parsed block of Decision 1 or `null` + when the root's config has none. Nothing else from the config crosses. +7. **Reporting** is unchanged: each check run of a pass is reported by the + `demoflow run` child with `kind: 'check'` (spec 360). Reporting off + (`CI`, `DEMOFLOW_NO_REPORT=1`) keeps them local, as for any run. + +## Configuration + +`demoflow.config.json`: the `schedule` block of Decision 1. The website's +config docs (spec 364) and `apps/cli/README.md` describe it. + +## Acceptance criteria + +- [ ] `ProjectConfigSchema` accepts the three cadences, refuses `weekly` + without `weekday`, `weekday` with `daily`, `at: "9:30"`, `at: "24:00"` + and an unknown key; the regenerated JSON schema matches. +- [ ] `lastDueSlot` is right for daily, weekdays across a weekend, weekly, + and both DST transitions in `Europe/Berlin` and `America/New_York`. +- [ ] With a fake clock, a daemon whose slot passes while it is running + spawns exactly one `run --check …` for that root; a daemon started + three days after the last pass spawns one, not three. +- [ ] No pass starts while a website-started launch is running; it starts + when that launch ends. +- [ ] Without credentials and with a scheduled root, the daemon runs in local + mode, opens no socket and runs the pass; without a scheduled root it + exits with `EXIT_DAEMON_NOT_LOGGED_IN` as today. +- [ ] `schedules.sync` carries only roots of the reported registry, with + `schedule` exactly as parsed or `null`, and the zone name. +- [ ] `demoflow runner status` shows the next and last check per scheduled + project. +- [ ] CLI tests pass on Linux, macOS and Windows. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i361-core | the config block and `lastDueSlot` | packages/core/src/project-config.ts, packages/core/src/schedule.ts, packages/core/src/index.ts, packages/core/schemas/project-config.schema.json, packages/core/test/** | — | yes | sonnet | +| i361-daemon | the scheduler, local mode, `schedules.sync`, status, the local roots file | apps/cli/src/runner/**, apps/cli/src/commands/run.ts, apps/cli/test/runner/**, apps/cli/README.md | i361-core | no | opus | + +`i361-daemon` is `opus`: local mode changes the daemon's start path and its +interaction with the launch slot, which this spec states but does not lay out. + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| packages/core/src/project-config.ts, packages/core/schemas/project-config.schema.json | i361-core | other Phase 8 issues that add config keys (#353, #365) rebase on whichever merges first; never edit the generated schema by hand | +| apps/cli/src/runner/connection.ts | i361-daemon | #360 also edits it; this slice starts after #360 merges | + +## Risks + +- **Medium — the daemon is not running.** A machine without autostart runs no + schedule. Mitigation: `demoflow runner status` and the website (spec 363) + say "next check when the runner is running"; the docs say to use + `demoflow runner install`. +- **Medium — local mode surprises.** A daemon that used to exit now stays up + without an account. Mitigation: only when a committed config asks for a + schedule; `runner status` names the mode. +- **Low — a slow pass overlaps the next slot.** Mitigation: one pass at a + time; a slot due during a pass is the catch-up pass. + +## Open questions + +- Should `exclude` accept globs? Default: no, exact ids; a glob is a later spec. + +Depends on #360 diff --git a/docs/specs/362-check-schedules-api.md b/docs/specs/362-check-schedules-api.md new file mode 100644 index 00000000..9d9fddb3 --- /dev/null +++ b/docs/specs/362-check-schedules-api.md @@ -0,0 +1,243 @@ +# Check schedules in the API: scheduler, check passes started from the website, stale state + +Issue: [#362](https://github.com/AndreyBegma/DemoFlow/issues/362) +Depends on: #360 (`Run.kind`, the daemon's `check.start`). Decision record: [ADR-0021](../adr/0021-scheduled-checks.md). + +## Summary + +The website side of scheduled checks (ADR-0021). The API stores a project's +schedule, set on the website or reported from the project's config by the +daemon (spec 361), starts a check pass on the project's machine when a +website schedule is due, catches up once when the machine comes back, and +keeps a per-scenario **stale** state from the runs the machine reports. The +web UI is spec 363. + +## Scope + +### In scope + +- `apps/api/prisma/schema.prisma`: `CheckSchedule` and `ScenarioHealth` (new + tables), their enums; migration + `apps/api/prisma/migrations/20261026130000_check_schedules/`. +- `apps/api/src/checks/**` (new module): schedules controller and service, + the scheduler loop, the slot computation, the stale-state service, DTOs and + their tests; registered in `apps/api/src/app.module.ts`. +- `apps/api/src/launches/launches.service.ts`: `startCheckPass(target, exclude)`, + the `check.*` replies, the `checks` capability from `launches.sync`. +- `apps/api/src/runner/runner-socket.ts`: the `check.started`, + `check.finished`, `check.error` and `schedules.sync` client messages, and + `checks?: boolean` on `LaunchesSyncMessage`; + `apps/api/src/runner/runner.gateway.ts`: route them. +- `apps/api/src/projects/projects.service.ts`: after a report is stored, call + the stale-state service in the same transaction (Decision 7). +- `apps/api/src/projects/projects.dto.ts`: `staleCount` on a project in + `GET /projects`. + +### Out of scope + +- The web UI (spec 363), the CLI and the daemon (specs 360, 361). +- Email, webhook or any alert besides the state the website reads (owner: + site only). +- A "check now" button. Default: not in this slice (Open questions). +- Changing the in-memory launch model (spec 247): a check pass is one more + kind of launch in it. + +## Decisions + +1. **One machine per project, by the data model.** A `Project` row belongs to + one Runner (`@@unique([runnerId, rootPath])`, + `apps/api/prisma/schema.prisma`) [Confirmed]; a project on two machines is + two rows. The owner's "the machine chosen in the schedule, default the + last one that ran the project" is therefore always the project's + `runnerId`: the schedule names no machine of its own, and the project page + shows which machine runs it. A project whose `runnerId` is null (the + machine was removed) cannot have a website schedule; an existing one is + paused with reason `no-machine`. +2. **Two sources, one table** (ADR-0021 §4). `CheckSchedule` has a `source` + of `site` or `config`, unique per `(projectId, source)`. + - `PUT /projects/:id/schedule` creates or replaces the `site` row. It is + refused `409 config-schedule` when a `config` row exists. + - `schedules.sync` (spec 361, Decision 6) upserts the `config` row of each + project matched by `(runnerId, rootPath)`, or deletes it when `schedule` + is `null`. A project not yet known to the server is ignored. When a + `config` row appears and a `site` row exists, the `site` row gets + `pausedReason = 'config-schedule'`; when the `config` row goes, the + pause is lifted. + - `config` rows are never run by the API: the daemon runs them (spec 361). + They are stored only to be shown, and their `lastPassAt` is the latest + reported check run of the project. +3. **Cadence and time zone** (ADR-0021 §5). `cadence` `daily | weekdays | weekly`, + `weekday` `mon…sun` with `weekly` only, `at` `HH:MM`, `timeZone` an IANA + name, `exclude` at most 100 scenario ids (`IsScenarioId`, + `apps/api/src/launches/scenario-id.ts`). The website sends the machine's + zone when the latest `schedules.sync` gave one, otherwise the browser's; + the API checks it with `Intl.supportedValuesOf('timeZone')`. +4. **The scheduler** ticks every 60 s, with `setInterval` in the service like + the existing sweeps (`launches.service.ts`, `artifacts.service.ts`) + [Confirmed]; no new dependency. For each unpaused `site` row it computes + the latest due slot (`apps/api/src/checks/slots.ts`; the API does not + depend on `@demoflow/core` [Confirmed], so the function is ported with the + same test vectors as spec 361's `lastDueSlot`). When that slot is later + than `lastSlotAt`: + - machine online, accepts checks, idle → `startCheckPass`; `lastSlotAt` is + set to the slot **before** the request is sent, so a crash or restart + does not send it twice; + - machine offline, or busy with a launch → nothing now; it runs on a later + tick, at most once for all slots missed meanwhile (owner: one catch-up + run); + - machine online but without `checks: true` → `pausedReason = 'cli-too-old'` + until a `launches.sync` with `checks: true`. + - *Why `lastSlotAt` and not a queue:* a missed slot is a fact computed from + the clock, so a restart of the API loses nothing. +5. **A check pass is a launch.** `startCheckPass` uses the launch map and the + one-active-launch-per-Runner rule of `LaunchesService` [Confirmed]. It + sends `check.start { requestId, rootPath, exclude }` (spec 360, Decision 6); + `check.finished` ends it with counts. The run reports of the pass arrive + over `POST /runner/runs` with `kind: 'check'` as usual. `GET /projects/:id/launch` + shows a pass as `{ kind: 'check', status, passed?, failed? }`. +6. **The stale state** (ADR-0021 §6). `ScenarioHealth` has one row per + `(projectId, scenarioPath)`: `state` (`passed | failed`), `since` + (the time of the run that made the last transition), `lastRunId`. + - Every stored report updates it, a check or an ordinary run: same state → + only `lastRunId` changes; a different state → `state`, `since` and + `lastRunId` change. + - "Stale" is `state = failed`. No email or other alert (owner: site only). + - Deleting a run does not recompute the state; deleting the project + cascades. +7. **Same transaction.** The health update runs inside the report's + transaction (`projects.service.ts` `report`) so a report and its state + never disagree. + +## Data / Schema + +```prisma +enum ScheduleSource { + site + config +} + +enum ScheduleCadence { + daily + weekdays + weekly +} + +model CheckSchedule { + id String @id @default(uuid()) + projectId String + project Project @relation(fields: [projectId], references: [id], onDelete: Cascade) + source ScheduleSource + cadence ScheduleCadence + // `mon`…`sun`; set only for `weekly`. + weekday String? + // `HH:MM`, 24-hour, in `timeZone`. + at String + timeZone String + exclude String[] + // `config-schedule`, `no-machine` or `cli-too-old`; null while it runs. + pausedReason String? + // The latest slot a pass was started for (site rows only). + lastSlotAt DateTime? + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@unique([projectId, source]) +} + +model ScenarioHealth { + projectId String + project Project @relation(fields: [projectId], references: [id], onDelete: Cascade) + scenarioPath String + state RunStatus + since DateTime + lastRunId String + + @@id([projectId, scenarioPath]) + @@index([projectId, state]) +} +``` + +`Project` gains the back-relations `schedules CheckSchedule[]` and +`health ScenarioHealth[]`. Migration `20261026130000_check_schedules` +creates both tables and enums, and backfills `ScenarioHealth` from each +`(projectId, scenarioPath)`'s latest `Run`. + +## API + +All routes take the session (`SessionGuard`) and act only on the caller's +projects; another user's project is `404`, as for every project route. + +| Route | Body / answer | +|---|---| +| `GET /projects/:id/schedule` | `{ site: Schedule \| null, config: Schedule \| null, machine: { id, name, online } \| null }` | +| `PUT /projects/:id/schedule` | `{ cadence, weekday?, at, timeZone, exclude? }` → the `site` schedule; `409 config-schedule`, `409 no-machine` | +| `DELETE /projects/:id/schedule` | deletes the `site` row; `204` | +| `GET /projects/:id/health` | `[{ scenarioPath, scenarioName, state, since, lastRunId }]` | +| `GET /checks/stale` | the caller's stale scenarios across projects, newest `since` first, at most 50: `[{ projectId, projectName, scenarioPath, scenarioName, since, lastRunId }]` | +| `GET /projects` | each project gains `staleCount` | + +`Schedule` is `{ source, cadence, weekday, at, timeZone, exclude, pausedReason, nextDueAt, lastPassAt }`. +`nextDueAt` is computed, never stored. + +## Acceptance criteria + +- [ ] **Authorization:** another user's project id on every route above is + `404`; `GET /checks/stale` and `GET /projects` never return another + user's schedules or stale scenarios (integration test with two users, + each with a failed run). +- [ ] `PUT` with `weekly` and no `weekday`, `at: "25:00"`, an unknown zone, + 101 excludes, or an unknown key is `400`. +- [ ] `PUT` on a project with a `config` row is `409 config-schedule`. +- [ ] A `schedules.sync` with a schedule creates the `config` row and pauses + an existing `site` row; one with `null` deletes it and lifts the pause. +- [ ] With a fake clock: a due slot with the machine online and idle sends one + `check.start`; the same slot never sends a second; three missed slots + while offline send one after reconnect; a busy machine gets it after its + launch ends. +- [ ] A machine whose `launches.sync` lacks `checks: true` is never sent + `check.start`, and the schedule shows `cli-too-old`. +- [ ] A failed report after a passed one flips `ScenarioHealth` to `failed` + with `since` = that run's start; a second failure changes only + `lastRunId`; a later pass flips it back. +- [ ] The migration's backfill gives each scenario the state of its latest run. +- [ ] `bun run test` passes in `apps/api`. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i362-schema | the tables, the migration, the stale state, `staleCount` | apps/api/prisma/schema.prisma, apps/api/prisma/migrations/20261026130000_check_schedules/**, apps/api/src/checks/health/**, apps/api/src/projects/** | — | yes | opus | +| i362-scheduler | schedules routes, scheduler, slots, socket messages, check passes | apps/api/src/checks/schedules/**, apps/api/src/checks/checks.module.ts, apps/api/src/app.module.ts, apps/api/src/launches/**, apps/api/src/runner/runner-socket.ts, apps/api/src/runner/runner.gateway.ts | i362-schema | no | opus | + +Both are `opus`: the schema and the backfill are decided here but not +written out as SQL, and the scheduler's interplay with the in-memory launch +map has to be fitted into code this spec only cites. + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| apps/api/prisma/schema.prisma | i362-schema | #360 adds `Run.kind` first; other Phase 8 API issues that add tables (#347) append distinct tables and keep both on conflict | +| apps/api/src/runner/runner-socket.ts | i362-scheduler | #347 and #356 add their own messages; rebase, keep every entry of `CLIENT_MESSAGES` | +| apps/api/src/app.module.ts | i362-scheduler | one import line each for other new modules | + +## Risks + +- **Medium — two slot implementations** (CLI core and API). Mitigation: the + same table of test vectors in both suites; spec 364 documents one rule. +- **Medium — one API process.** The scheduler and the launch map are in + memory; two API containers would start a pass twice. Staging and + production run one API container (`deploy/README.md`) [Confirmed]; + `lastSlotAt` written before sending limits the damage to one duplicate. +- **Low — the backfill** on a large `Run` table. Mitigation: one + `DISTINCT ON` query; the table is small today. + +## Open questions + +- A "Check now" button on the project page? Default: not in Phase 8; the + person can start a run. +- Should a stale scenario clear when the scenario is deleted from the + repository? Default: no; the row stays until a run passes or the project is + deleted. + +Depends on #360 diff --git a/docs/specs/363-check-schedules-web.md b/docs/specs/363-check-schedules-web.md new file mode 100644 index 00000000..4e1ecab4 --- /dev/null +++ b/docs/specs/363-check-schedules-web.md @@ -0,0 +1,153 @@ +# Check schedules on the project page, and stale badges + +Issue: [#363](https://github.com/AndreyBegma/DemoFlow/issues/363) +Depends on: #362 (the schedule and health routes). Decision record: [ADR-0021](../adr/0021-scheduled-checks.md). + +## Summary + +The person sets when a project's demos are checked, sees a schedule the +team committed in `demoflow.config.json` (read-only), and sees which demos are +broken: a **stale** badge on the project and on each scenario, and a block on +`/app` listing every stale scenario. Check runs appear in the run library +with a "Check" label and no video. Alerts live on the website only (owner, +2026-10-26). + +## Scope + +### In scope + +- `apps/web/src/components/projects/check-schedule.tsx` (new): the schedule + card of the project page. +- `apps/web/src/components/projects/scenario-health.tsx` (new): the + per-scenario state list on the project page. +- `apps/web/src/components/projects/stale-badge.tsx` (new). +- `apps/web/src/components/dashboard/stale-demos.tsx` (new): the `/app` block. +- `apps/web/src/lib/schedule.ts` and `schedule.test.mjs` (new): form ↔ body, + "next check" text, validation. +- `apps/web/src/app/app/projects/[id]/page.tsx`: the two new cards. +- `apps/web/src/app/app/projects/_data.ts`: fetch schedule and health. +- `apps/web/src/components/projects/project-list.tsx`: the badge with `staleCount`. +- `apps/web/src/components/projects/runs-table.tsx` and + `apps/web/src/components/projects/run-details.tsx`: the "Check" label for + `kind: 'check'` and "A check run records no video" in place of the player. +- `apps/web/src/app/app/page.tsx`: the stale block. +- `apps/web/src/i18n/en.ts`: `projects.schedule.*`, `projects.health.*`, + `dashboard.stale.*`, `runs.kind.check`. + +### Out of scope + +- The API (spec 362), the CLI (specs 360, 361), the docs pages (spec 364). +- Email or push notifications. +- Editing a config schedule from the website: it is the repository's. + +## Decisions + +1. **The schedule card** (ADR-0021 §4–5). On the project page, under the + project header and above Start run. + - **No schedule:** "Not checked on a schedule" and a **Set schedule** + button. + - **Form:** cadence as a segmented control (Daily · Weekdays · Weekly), + a weekday select shown for Weekly, a time input (`HH:MM`), the time zone + (the machine's when the API knows it, else the browser's, shown as text + with a **Change** link to a select), and **Leave out** — a checklist of + the project's scenarios from `GET /projects/:id/scenarios` (needs the + machine online; offline shows "Scenarios are listed when the machine is + online" and keeps the saved list). Save is `PUT /projects/:id/schedule`; + Remove is `DELETE` behind a confirm. + - **Set:** "Checks every weekday at 09:30 (Europe/Berlin) on <machine>", + next check (relative), last pass (relative, with passed/failed counts + when known), Edit and Remove. + - **Paused** (`pausedReason`): a warning banner with the reason — + `config-schedule`: "The project's demoflow.config.json has its own + schedule, which wins"; `no-machine`: "The machine was removed"; `cli-too-old`: + "Update DemoFlow on <machine> to run scheduled checks". + - **Config schedule:** the same summary, read-only, with "Set in + demoflow.config.json" and a link to `/docs/checks` (spec 364); no form. + - Offline machine: the next-check line says "when <machine> is online". +2. **Stale badge.** `Glass UI` `Badge` with tone `danger`, text "Stale" + (one scenario) or "N stale" (project list). Shown only when the count is + above zero; no "healthy" badge (an absent badge is the healthy state). +3. **Scenario health list** on the project page: one row per scenario the API + has health for — name, state (Stale since <relative> / Passing), a link to + the last run. Stale rows first. Hidden when the API returns none. +4. **The `/app` block** "Stale demos": up to 10 rows from `GET /checks/stale` + (project, scenario, since, link to the run), and "All passing" when empty + for a user who has at least one schedule; hidden for a user with no + schedule and no stale scenario. +5. **Check runs in the library.** A run with `kind: 'check'` shows a "Check" + label in `runs-table` and, on the run page, the stages and the failure as + today, with "A check run records no video" instead of the player and no + download or format controls. +6. **Content surfaces stay readable** (CLAUDE.md, vision §9): the cards are + Glass UI `Card`s like the rest of the page; glass only on the existing + chrome. + +## UI + +Copy (English, i18n keys under the namespaces of Scope): + +| Key | Text | +|---|---| +| `projects.schedule.title` | Scheduled checks | +| `projects.schedule.none` | Not checked on a schedule | +| `projects.schedule.set` | Set schedule | +| `projects.schedule.summary` | Checks {cadence} at {at} ({zone}) on {machine} | +| `projects.schedule.next` | Next check {when} | +| `projects.schedule.nextOffline` | Next check when {machine} is online | +| `projects.schedule.fromConfig` | Set in demoflow.config.json | +| `projects.health.stale` | Stale since {when} | +| `dashboard.stale.title` | Stale demos | +| `dashboard.stale.allPassing` | All passing | +| `runs.kind.check` | Check | + +## Acceptance criteria + +- [ ] A project with no schedule shows "Not checked on a schedule"; setting + Weekdays 09:30 saves and the card shows the summary and a next check. +- [ ] Weekly shows the weekday select; Daily and Weekdays hide it; an invalid + time cannot be saved (`schedule.test.mjs` covers the form mapping). +- [ ] A project with a config schedule shows it read-only with no form and no + Remove. +- [ ] Each `pausedReason` shows its banner text. +- [ ] A project with two failed scenarios shows "2 stale" in the project list + and a Stale badge on both rows of the health list; `/app` lists both. +- [ ] A check run in the library shows "Check", and its run page shows no + player, no download and the "records no video" line. +- [ ] Keyboard: the form is operable without a mouse; the badge has text, not + only colour. +- [ ] `bun run build` and `bun run check` pass for `apps/web`. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i363-schedule | the schedule card and its lib | apps/web/src/components/projects/check-schedule.tsx, apps/web/src/lib/schedule.ts, apps/web/src/lib/schedule.test.mjs, apps/web/src/app/app/projects/[id]/page.tsx, apps/web/src/app/app/projects/_data.ts, apps/web/src/i18n/en.ts | — | yes | sonnet | +| i363-stale | badges, health list, `/app` block, check runs | apps/web/src/components/projects/stale-badge.tsx, apps/web/src/components/projects/scenario-health.tsx, apps/web/src/components/dashboard/stale-demos.tsx, apps/web/src/components/projects/project-list.tsx, apps/web/src/components/projects/runs-table.tsx, apps/web/src/components/projects/run-details.tsx, apps/web/src/app/app/page.tsx | i363-schedule | no | sonnet | + +`i363-stale` waits for `i363-schedule` because the page file and `en.ts` have +one writer: `i363-schedule` adds every key of the UI table and mounts the +health list on the project page with a placeholder import that `i363-stale` +fills. + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| apps/web/src/i18n/en.ts | i363-schedule | other Phase 8 web issues (#350, #351, #357, #358) add their own namespaces; rebase and keep both | +| apps/web/src/components/projects/run-details.tsx | i363-stale | #350 and #357 also edit the run page; land in issue order | +| apps/web/src/app/app/projects/[id]/page.tsx | i363-schedule | — | + +## Risks + +- **Medium — time zone confusion.** A schedule in the machine's zone shown to + a person in another. Mitigation: the zone is always printed next to the + time; "next check" is relative. +- **Low — scenario list needs the machine online.** Mitigation: the saved + exclusions are kept and shown by id when offline. + +## Open questions + +- Should the stale block also show on the project list page? Default: the + badge there is enough. + +Depends on #362 diff --git a/docs/specs/364-checks-docs.md b/docs/specs/364-checks-docs.md new file mode 100644 index 00000000..a67d7a66 --- /dev/null +++ b/docs/specs/364-checks-docs.md @@ -0,0 +1,98 @@ +# Website docs: scheduled checks and stale demos + +Issue: [#364](https://github.com/AndreyBegma/DemoFlow/issues/364) +Depends on: #361 (the config schedule and the daemon), #363 (the website UI). Decision record: [ADR-0021](../adr/0021-scheduled-checks.md). + +## Summary + +Document scheduled checks on the website's docs: what a check run is, the +two places a schedule can live and which wins, how a scenario becomes stale +and how it clears, and what the daemon must be doing for any of it to +happen. Written once specs 360–363 have merged, from the code as merged. + +## Scope + +### In scope + +- `apps/web/src/app/docs/checks/page.mdx` (new): the page "Scheduled checks". +- `apps/web/src/lib/docs-nav.ts`: the entry `{ href: '/docs/checks', label: 'docs.nav.checks' }` + after `/docs/runner`; `apps/web/src/lib/docs-nav.test.mjs` if it lists the + pages. +- `apps/web/src/i18n/en.ts`: `docs.nav.checks`. +- `apps/web/src/app/docs/config/page.mdx`: the `schedule` block in the config + reference, linking to the new page. +- `apps/web/src/app/docs/cli/page.mdx`: `demoflow run --check` and + `--exclude`; `demoflow runner status`'s schedule lines. +- `apps/web/src/app/docs/runner/page.mdx`: local mode (scheduled checks + without an account) and "a check pass counts as the machine's one launch". + +### Out of scope + +- `apps/cli/README.md` (updated by specs 360 and 361). +- Any product code. + +## Decisions + +1. **One new page, three short additions.** The concept lives on + `/docs/checks`; the reference pages say only what their reader needs and + link to it. +2. **The page's sections**, in order: + 1. *What a check is* — `demoflow run --check`: the steps and the + verifications, no video, no render; a check pass is every scenario of + the project minus exclusions, one application start. + 2. *Schedule in the config* — the `schedule` block (cadence, weekday, at, + exclude), machine-local time, the daemon runs it, works without an + account; results in `demoflow runs`; shown read-only on the website + when paired. + 3. *Schedule on the website* — the project page card; the project's machine + runs it; time zone; what "paused" means for each reason. + 4. *Which wins* — the config; the website schedule is paused while a + config schedule exists. + 5. *Missed checks* — one catch-up pass after the machine was off, asleep or + offline. + 6. *Stale demos* — a scenario is stale when its last run failed, a check or + not; the badge, the project list count and the `/app` block; it clears + on the next passing run. No email. + 7. *What reaches the server* — the ADR-0021 §7 list in plain words. +3. **Examples are real.** Every command and JSON block on the page is run + against the fixture app before merge, and its output pasted from that run. + +## Acceptance criteria + +- [ ] `/docs/checks` renders, is in the docs navigation after Runner, and + every link on it resolves (the docs-nav test passes). +- [ ] The config reference documents `schedule` with each field, its values + and a full example that `demoflow validate` accepts. +- [ ] The CLI page documents `--check` and `--exclude`, and says `--format` + and `--headed` are refused with `--check`. +- [ ] The Runner page documents local mode. +- [ ] Nothing on the pages contradicts ADR-0021 or the merged specs 360–363 + (reviewer checks section by section). +- [ ] `bun run build` and `bun run check` pass for `apps/web`. + +## Parallel plan + +One slot: the pages are short and share the nav and i18n files. + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i364-docs | the checks docs | apps/web/src/app/docs/checks/**, apps/web/src/app/docs/config/page.mdx, apps/web/src/app/docs/cli/page.mdx, apps/web/src/app/docs/runner/page.mdx, apps/web/src/lib/docs-nav.ts, apps/web/src/lib/docs-nav.test.mjs, apps/web/src/i18n/en.ts | — | yes | sonnet | + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| apps/web/src/lib/docs-nav.ts, apps/web/src/i18n/en.ts | i364-docs | the sharing (#352), editor (#359) and hold (#365) docs also add entries; keep every entry, in the order of the nav | +| apps/web/src/app/docs/config/page.mdx, apps/web/src/app/docs/cli/page.mdx | i364-docs | #352, #359, #365 also add sections; rebase and keep both | + +## Risks + +- **Low — docs written before behaviour settles.** Mitigation: this issue + starts only after 361 and 363 merge (Depends on). + +## Open questions + +- None. + +Depends on #361 +Depends on #363 diff --git a/docs/specs/365-hold-the-result.md b/docs/specs/365-hold-the-result.md new file mode 100644 index 00000000..279343c3 --- /dev/null +++ b/docs/specs/365-hold-the-result.md @@ -0,0 +1,218 @@ +# Hold the result on screen + +Issue: [#365](https://github.com/AndreyBegma/DemoFlow/issues/365) +Depends on: nothing + +## Summary + +A demo such as "create a post" ends right after its last action. The viewer +sees the click on **Publish** and the video stops before the new post shows +up, so the one thing the demo exists to prove (the feature works) is +never on screen. Three things in the code cause it: + +- The engine closes the browser context as soon as the last step returns + (`packages/engine/src/run.ts`, `await context.close()` after `execute`). + The source video ends there, before a late server response has painted. + [Confirmed] +- The renderer keeps a fixed `TIMING.tailMs = 1_000` after the last event + (`packages/renderer/src/plan/plan.ts`), and it cannot be configured. + [Confirmed] +- A trailing `wait` is a frozen stretch outside every `ACTIVE` action, so the + idle trim (`render.idle.thresholdMs`, 1000 ms by default) shortens it to + `compressToMs` (400 ms). An author who adds a `wait` to show the result + loses it in the render. [Confirmed: `idleStretches` in + `packages/renderer/src/plan/time-map.ts` subtracts only the `ACTIVE` + windows] + +This slice adds a hold at the end of every successful video +(`render.endHoldMs`) and a `hold` on any step. The engine records the hold and +the idle trim never cuts it. An assertion step with `zoom` keeps the camera on +the element it found for the length of its hold, so the result is both shown +and pointed at. + +## Scope + +### In scope + +- `packages/core/src/step.ts`: `hold` in the fields every step may carry. +- `packages/core/src/project-config.ts`: `render.endHoldMs`. +- `packages/core/src/timeline.ts`: `holdMs` on `TimelineEventSchema`. +- `packages/core/schemas/*.schema.json`: regenerated + (`bun run --filter @demoflow/core schema`; `test/json-schema.spec.ts` fails + while they are stale). +- `packages/engine/src/run.ts`: sleep the step's `hold` after the step and + stamp `holdMs`; on success, sleep `endHoldMs` after the last step before + `context.close()`. `RunOptions.endHoldMs`. +- `packages/renderer/src/plan/types.ts`, `plan.ts`, `time-map.ts` (only if + `idleStretches` needs a new input): the hold windows count as active, the + tail is `endHoldMs`, and an assertion's zoom lasts through its hold. +- `apps/cli/src/commands/run.ts` and `render.ts` (`renderPlanOptions`): pass + `config.render.endHoldMs` to `runScenario` and to `buildRenderPlan`. +- Tests: `packages/core/test/**`, `packages/engine/test/**`, + `packages/renderer/test/plan/**` and one real-run test under + `packages/renderer/test/ffmpeg/**` (Vitest under Node). +- Docs: `apps/web/src/app/docs/scenarios/page.mdx` (a `### hold` section next + to `### Zoom`, and a "Show the result" example), and + `apps/web/src/app/docs/config/page.mdx` (the `render.endHoldMs` row in the + render table, next to `idle.*`). + +### Out of scope + +- A "wait for the page to settle" mode (network idle, stable DOM). The owner + chose explicit holds; a polling page would never settle. +- The `demoflow record` panel. It can gain a "Hold" control later, like spec + 224's "Wait for ready". +- The `demoflow/playwright` fixture (`packages/playwright`). It records a + `.demo.json`, the engine replays it, and a hold in that file just works. +- Failed runs. They keep ending at the failure, followed by the failure card + (ADR-0004 §4). +- A new overlay style beyond the highlight in Decision 5. + +## Decisions + +1. **`render.endHoldMs`**, an integer from 0 to 10000, default **2500** + (owner, R1). After the last step of a **successful** run the engine keeps + recording this long. The renderer keeps the same length after the last + event and puts the outro card (if any) after it. `0` gives the old ending + minus the 1 s tail: the video ends at the last event. + - *Why in `render.*` and not in the scenario:* it is a style choice for the + whole project, like `idle` and `cards`. A scenario that wants more uses a + `hold` on its last step (Decision 2). + - `TIMING.tailMs` is removed; `endHoldMs` replaces it. +2. **`hold` on any step**: an integer from 100 to 10000 ms, optional, in + `common` next to `caption`, `timeoutMs` and `record` (owner, R1). After the + step's action returns, the engine sleeps `hold` ms. The timeline event + keeps `endMs` at the end of the action and adds `holdMs`, so the action's + duration stays truthful and the renderer knows the window + `[endMs, endMs + holdMs]`. + - A `hold` on an off-camera step (`record: false`) is refused at parse + time, because nothing would show it. + - A `hold` on the last step and `endHoldMs` both apply: the hold first, + then the end hold. + - A step that fails does not hold. The run stops at the failure as today. +3. **The idle trim never cuts a hold.** Every hold window and the end-hold + window join the `active` intervals passed to `idleStretches`, so a frozen + page during a hold plays at real speed. This is the reason `hold` exists + rather than `wait`. `wait` keeps its current behaviour (it is idle and gets + compressed), and the docs say to use `hold` to show something. +4. **The engine records the hold.** `RunOptions.endHoldMs` (default 0, so + callers that do not pass it keep today's behaviour) is slept after a + successful `execute`, before `marked.list()` and `context.close()`. The CLI + passes `config.render.endHoldMs`. Holds count towards the run's + `durationMs`. +5. **An assertion with `zoom` stays zoomed through its hold** (owner, R2). On + an `assertVisible` or `assertText` that has `zoom`, the shot's `endMs` in + `cameraKeyframes` becomes `out(endMs + holdMs)`; on the last step it also + covers the end hold. The camera then zooms out over 400 ms as usual, or the + video ends zoomed in if the hold runs to the end. + - Assertion steps already accept `zoom`: `step('assertVisible', + { target, ...zoom })` and `assertText` in `packages/core/src/step.ts`. + ADR-0012 is unchanged: nothing zooms unless the step asks. [Confirmed] + - **Highlight:** for the same window, a soft outline is drawn around the + asserted element's box (2 px, the frame's accent colour, 8 px corner + radius, fading in over 200 ms). It is drawn only when the step has + `zoom`, because the owner asked for the highlight together with the zoom. + It is planned like a click ring (`ClickRing` in + `packages/renderer/src/plan/types.ts`) and follows the camera and the + vertical and square crops. +6. **Old runs re-rendered.** `demoflow render` on a run recorded before this + change has no `holdMs` and a source that ends about at the last event. The + tail is clamped to the source's duration, so these runs render as before, + minus whatever the old 1 s tail took beyond the source. No migration is + needed. + +## Configuration + +```jsonc +// demoflow.config.json +{ "render": { "endHoldMs": 2500 } } // 0–10000, default 2500 +``` + +```jsonc +// a step +{ "action": "click", "target": { "role": "button", "name": "Publish" } }, +{ "action": "assertVisible", "target": { "text": "My first post" }, "zoom": true, "hold": 2000 } +``` + +`hold`: 100–10000 ms. Refused on a `record: false` step. + +## Acceptance criteria + +- [ ] `ProjectConfigSchema` accepts `render.endHoldMs` 0–10000, defaults it + to 2500, and refuses −1, 10001 and 1.5. `StepSchema` accepts `hold` + 100–10000 on every action, refuses 99 and 10001, and refuses `hold` + together with `record: false`. The committed `schemas/` match + `jsonSchemas()`. +- [ ] Engine: a two-step scenario with `hold: 1500` on step 0 and + `endHoldMs: 2000` produces a timeline whose event 0 has `holdMs: 1500` + and `endMs` at the end of the action. Event 1 starts at least 1500 ms + after event 0's `endMs`, and the source video lasts at least 2000 ms + past event 1's `endMs`. +- [ ] Engine: a run whose step fails does not sleep `endHoldMs` (duration + within 500 ms of the failure). +- [ ] Renderer plan (unit, `packages/renderer/test/plan/**`): with a freeze + covering a step's whole hold window, the time map keeps that window at + 1:1. The same freeze covering a `wait` of the same length is compressed + to `compressToMs`. +- [ ] Renderer plan: the video ends at `lastEvent.endMs + endHoldMs` (in + output time, before any outro card), clamped to the source's duration. + `endHoldMs: 0` ends it at the last event. +- [ ] Renderer plan: an `assertVisible` with `zoom: true` and `hold: 2000` + has a camera keyframe at full zoom at `out(endMs + 2000)` and an outline + overlay covering `[out(endMs), out(endMs + 2000)]`. Without `zoom` there + is no zoom and no outline. +- [ ] **Real run** (`packages/renderer/test/ffmpeg/**`, the fixture app): a + scenario that clicks a button which reveals an element after 600 ms, + with `endHoldMs: 2500`. In the rendered MP4 the revealed element is + visible in every sampled frame from the moment it appears until at + least 2500 ms before the end. Sample the frames the way + `render.spec.ts` already does. +- [ ] Failed runs render exactly as before: the frames up to the failure, + then the failure card. The existing failure-card tests pass unchanged. +- [ ] `demoflow render` of a run directory recorded before this change (a + fixture timeline without `holdMs`) succeeds, and its duration does not + exceed the source's. +- [ ] The docs pages describe `hold`, `render.endHoldMs`, and why `hold` + rather than `wait`, with the example above. + +## Parallel plan + +Honestly one slot. The timeline field, the engine and the renderer are one +contract and change together, and the renderer cannot be tested without the +engine's `holdMs`. + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i365-hold | the hold end to end | packages/core/src/step.ts, packages/core/src/project-config.ts, packages/core/src/timeline.ts, packages/core/schemas/**, packages/core/test/**, packages/engine/src/run.ts, packages/engine/test/**, packages/renderer/src/plan/**, packages/renderer/test/**, apps/cli/src/commands/run.ts, apps/cli/src/commands/render.ts, apps/cli/test/**, apps/web/src/app/docs/scenarios/page.mdx, apps/web/src/app/docs/config/page.mdx | — | yes | opus | + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| packages/core/src/step.ts, project-config.ts, timeline.ts, packages/core/schemas/** | i365-hold | Phase 8 slices #353 (edits.json) and #361 (`schedule`) also edit `packages/core`. Merge #365 first, or rebase onto it. The schema files are regenerated, never hand-merged | +| packages/renderer/src/plan/plan.ts | i365-hold | #353 and #354 (edits and trims) apply to the same plan. Whoever merges second rebases | +| apps/cli/src/commands/render.ts (`renderPlanOptions`) | i365-hold | #355 adds `edits.json` there | + +## Risks + +- **Medium: longer runs and CI time.** Every successful run grows by 2.5 s. + Mitigation: the fixture's CI scenarios and real-run tests set + `endHoldMs: 0` except the one test that checks it. +- **Medium: the visual baselines change.** The extra tail changes the frame + count of renders that `packages/renderer/test/visual/**` compares. + Mitigation: regenerate the baselines in this pull request, as the roadmap + asks of an intended change. +- **Low: clock offset at the end.** The tail is measured in timeline time and + converted with `toSource`; a source shorter than expected is clamped + (Decision 6) rather than read past its end. +- **Low: highlight on a moving element.** The box is the one measured when the + assertion passed. An element that animates afterwards drifts out of its + outline. The docs advise putting the hold on a settled element. + +## Open questions + +- Should a `hold` on a step that the page annotates with `window.demoflow.caption` + extend the caption? Default: no. Captions keep their own timing + (`captionTailMs`, `pageCaptionMs`). +- Should the outline also show on a `waitFor` with `zoom`? Default: no, only + the two assertions (owner, R2). diff --git a/docs/specs/README.md b/docs/specs/README.md index 777b8002..6825c636 100644 --- a/docs/specs/README.md +++ b/docs/specs/README.md @@ -178,3 +178,22 @@ Work traced to an ADR, the vision or spec 179 that no phase had picked up. | [#329](https://github.com/AndreyBegma/DemoFlow/issues/329) | [`scenarios.list` truncation test times out on the Windows runner](329-scenarios-list-windows-flake.md) | — | | [#288](https://github.com/AndreyBegma/DemoFlow/issues/288) | [Luna Player `VideoPlayer` adapter](288-luna-video-player.md) — ADR-0009 §2, Phase 6 | luna-player 0.2.0 | | [#337](https://github.com/AndreyBegma/DemoFlow/issues/337) | [`${PORT}` templating, `--port` and `--fresh-app` for parallel runs](337-port-templating.md) — Nautelle ADR-0090 | — | +| [#347](https://github.com/AndreyBegma/DemoFlow/issues/347) | [Share a run's video: the Share model, disk storage, upload through the runner socket](347-share-storage-api.md) — ADR-0019, Phase 8 | — | +| [#348](https://github.com/AndreyBegma/DemoFlow/issues/348) | [Public share endpoints: page data, file, poster, password, views, expiry](348-share-public-endpoints.md) — ADR-0019, Phase 8 | #347 | +| [#349](https://github.com/AndreyBegma/DemoFlow/issues/349) | [The runner uploads a render for a share; `demoflow share` and the MCP `share_demo` tool](349-cli-share.md) — ADR-0019, Phase 8 | #347 | +| [#350](https://github.com/AndreyBegma/DemoFlow/issues/350) | [Share dialog on the run page and the `/app/shares` list](350-web-share-dialog.md) — ADR-0019, Phase 8 | #347 | +| [#351](https://github.com/AndreyBegma/DemoFlow/issues/351) | [Public share page `/s/[token]`: player, chapters, download, password](351-web-share-page.md) — ADR-0019, Phase 8 | #348 | +| [#352](https://github.com/AndreyBegma/DemoFlow/issues/352) | [Docs: sharing a video](352-docs-sharing.md) — ADR-0019, Phase 8 | #349, #350, #351 | +| [#353](https://github.com/AndreyBegma/DemoFlow/issues/353) | [`edits.json`: captions, zoom, cards and style applied at render](353-edits-schema-and-render.md) — ADR-0020, Phase 8 | — | +| [#354](https://github.com/AndreyBegma/DemoFlow/issues/354) | [Trim and cut segments from `edits.json`](354-trim-and-cuts.md) — ADR-0020, Phase 8 | #353 | +| [#355](https://github.com/AndreyBegma/DemoFlow/issues/355) | [The Runner serves and saves a run's edits, re-renders on request, and exports patches](355-runner-edits-and-rerender.md) — ADR-0020, Phase 8 | #353 | +| [#356](https://github.com/AndreyBegma/DemoFlow/issues/356) | [Editor relay (API): edit model, save, re-render, progress, update a share](356-editor-relay-api.md) — ADR-0020, Phase 8 | #347, #355 | +| [#357](https://github.com/AndreyBegma/DemoFlow/issues/357) | [Timeline editor with an in-browser preview on the run page](357-timeline-editor.md) — ADR-0020, Phase 8 | #356 | +| [#358](https://github.com/AndreyBegma/DemoFlow/issues/358) | [Export edits to the scenario and the config, reset edits, update the share](358-edits-export-reset-share.md) — ADR-0020, Phase 8 | #350, #357 | +| [#359](https://github.com/AndreyBegma/DemoFlow/issues/359) | [Docs: editing a video on the website](359-editor-docs.md) — ADR-0020, Phase 8 | #353, #358 | +| [#360](https://github.com/AndreyBegma/DemoFlow/issues/360) | [`demoflow run --check`: run and verify without recording or rendering](360-run-check-mode.md) — ADR-0021, Phase 8 | — | +| [#361](https://github.com/AndreyBegma/DemoFlow/issues/361) | [`schedule` in `demoflow.config.json`: the runner daemon runs check passes on a schedule](361-config-schedule.md) — ADR-0021, Phase 8 | #360 | +| [#362](https://github.com/AndreyBegma/DemoFlow/issues/362) | [Check schedules in the API: scheduler, check passes started from the website, stale state](362-check-schedules-api.md) — ADR-0021, Phase 8 | #360 | +| [#363](https://github.com/AndreyBegma/DemoFlow/issues/363) | [Check schedules on the project page, and stale badges](363-check-schedules-web.md) — ADR-0021, Phase 8 | #362 | +| [#364](https://github.com/AndreyBegma/DemoFlow/issues/364) | [Website docs: scheduled checks and stale demos](364-checks-docs.md) — ADR-0021, Phase 8 | #361, #363 | +| [#365](https://github.com/AndreyBegma/DemoFlow/issues/365) | [Hold the result on screen](365-hold-the-result.md) — Phase 8 | — | From c55e12d3430073ce28858e58561fbc655ef9ca2e Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 13:22:19 +0100 Subject: [PATCH 02/71] fix(cli): default demoflow login to production instead of staging --- apps/cli/README.md | 2 +- apps/cli/src/auth/server.ts | 4 ++-- apps/cli/src/main.ts | 2 +- apps/cli/test/auth/auth.spec.ts | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/apps/cli/README.md b/apps/cli/README.md index d7e779a3..a16dc4f5 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -215,7 +215,7 @@ expires after 10 minutes. - `demoflow logout` revokes the token on the server, then deletes the file. If the server cannot be reached it still deletes the file; the machine stays listed under `/app/machines` until you revoke it there. -- The server is `https://demoflow-app.luna-realm.com` (staging) unless +- The server is `https://demoflow.luna-realm.com` (production) unless `--server <url>` or `DEMOFLOW_SERVER` says otherwise. It is the website's origin; the API is under `/api`. `logout` uses the server stored at login. - The token is in `credentials.json` (`{ server, token, runnerId }`, mode 0600) diff --git a/apps/cli/src/auth/server.ts b/apps/cli/src/auth/server.ts index 91591c0b..999a93fe 100644 --- a/apps/cli/src/auth/server.ts +++ b/apps/cli/src/auth/server.ts @@ -1,7 +1,7 @@ import { CliError } from '../config/index.ts'; -/** Staging, until production exists (spec 135, Decision 9). */ -export const DEFAULT_SERVER = 'https://demoflow-app.luna-realm.com'; +/** Production; staging is reachable with `--server` or `DEMOFLOW_SERVER`. */ +export const DEFAULT_SERVER = 'https://demoflow.luna-realm.com'; /** `--server`, then `DEMOFLOW_SERVER`, then the default. Returns an origin-and-path without a trailing slash. */ export function resolveServer( diff --git a/apps/cli/src/main.ts b/apps/cli/src/main.ts index 1140a8ec..26e05145 100644 --- a/apps/cli/src/main.ts +++ b/apps/cli/src/main.ts @@ -195,7 +195,7 @@ export async function main( .description('Pair this machine with your DemoFlow account') .option( '--server <url>', - 'the DemoFlow server (default: DEMOFLOW_SERVER or staging)', + 'the DemoFlow server (default: DEMOFLOW_SERVER or production)', ) .option('--force', 'pair again, revoking the stored token first') .option('--start', 'start the runner afterwards, without asking') diff --git a/apps/cli/test/auth/auth.spec.ts b/apps/cli/test/auth/auth.spec.ts index f2aefe30..5bdfc1ae 100644 --- a/apps/cli/test/auth/auth.spec.ts +++ b/apps/cli/test/auth/auth.spec.ts @@ -235,11 +235,11 @@ describe('credentials', () => { }); describe('resolveServer', () => { - it('prefers the flag, then DEMOFLOW_SERVER, then staging', () => { + it('prefers the flag, then DEMOFLOW_SERVER, then production', () => { const env = { DEMOFLOW_SERVER: 'http://env.test/' }; expect(resolveServer('http://flag.test', env)).toBe('http://flag.test'); expect(resolveServer(undefined, env)).toBe('http://env.test'); - expect(resolveServer(undefined, {})).toBe(DEFAULT_SERVER); + expect(resolveServer(undefined, {})).toBe('https://demoflow.luna-realm.com'); }); it('rejects anything but http(s)', () => { From eeab0782d8265d4b99d3d36c99903aa4f1d32a2c Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 13:23:24 +0100 Subject: [PATCH 03/71] fix(web): serve apps/web/public from the Docker image The runtime stage copied .next/standalone and .next/static but not public/, which the standalone output leaves out, so /demo/landing.mp4 and its poster answered 404 on staging and production. status.sh now also requests /demo/landing-poster.png and exits non-zero unless every public path answers 200, and refresh.sh waits for the web container to serve the poster before it records the deploy. Closes #370 --- apps/web/Dockerfile | 3 +++ deploy/README.md | 4 ++-- deploy/production/refresh.sh | 14 ++++++++++++++ deploy/production/status.sh | 10 ++++++++-- deploy/staging/refresh.sh | 14 ++++++++++++++ deploy/staging/status.sh | 10 ++++++++-- 6 files changed, 49 insertions(+), 6 deletions(-) diff --git a/apps/web/Dockerfile b/apps/web/Dockerfile index 78bb96f2..f6bdf4e4 100644 --- a/apps/web/Dockerfile +++ b/apps/web/Dockerfile @@ -53,6 +53,9 @@ ENV HOSTNAME=0.0.0.0 COPY --from=builder /app/apps/web/.next/standalone ./ COPY --from=builder /app/apps/web/.next/static ./apps/web/.next/static +# The standalone output leaves public/ out; server.js serves it from next to +# itself, so without this every file under it (the landing video) is a 404. +COPY --from=builder /app/apps/web/public ./apps/web/public RUN mkdir -p /app/apps/web/.next/cache && chown -R node:node /app/apps/web/.next diff --git a/deploy/README.md b/deploy/README.md index 6a276ed8..87b39c84 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -203,7 +203,7 @@ Nothing is published on the host. The stack runs on its own compose network | Command (on the host) | What it does | |---|---| -| `/home/archi/stacks/demoflow-staging/status.sh` | the deployed commit, containers, image revisions, and the public `/` and `/api/health` | +| `/home/archi/stacks/demoflow-staging/status.sh` | the deployed commit, containers, image revisions, and the public `/`, `/api/health` and `/demo/landing-poster.png` (non-zero exit unless all answer 200) | | `/home/archi/stacks/demoflow-staging/up.sh` | starts the stack from the images already built | | `/home/archi/stacks/demoflow-staging/down.sh` | stops it; the volumes are kept | | `sh deploy/staging/refresh.sh` (from a checkout) | what `deploy-staging` runs | @@ -325,7 +325,7 @@ The Woodpecker settings are the staging ones; nothing else is needed. | Command (on the host) | What it does | |---|---| -| `/home/archi/stacks/demoflow-production/status.sh` | the deployed commit, containers, image revisions, and the public `/` and `/api/health` | +| `/home/archi/stacks/demoflow-production/status.sh` | the deployed commit, containers, image revisions, and the public `/`, `/api/health` and `/demo/landing-poster.png` (non-zero exit unless all answer 200) | | `/home/archi/stacks/demoflow-production/up.sh` | starts the stack from the images already built | | `/home/archi/stacks/demoflow-production/down.sh` | stops it; the volumes are kept | | `sh deploy/production/refresh.sh` (from a checkout of `main`) | what `deploy-production` runs | diff --git a/deploy/production/refresh.sh b/deploy/production/refresh.sh index b6c5f3e8..784c2cf8 100755 --- a/deploy/production/refresh.sh +++ b/deploy/production/refresh.sh @@ -108,6 +108,20 @@ while :; do waited=$((waited + 5)) done +# The web image must serve apps/web/public; the poster stands for all of it. +# Asked from inside the container, so it does not depend on the tunnel. +echo "Waiting for the web app to serve /demo/landing-poster.png (up to ${HEALTH_TIMEOUT}s)..." +waited=0 +until docker exec demoflow-production-web node -e "fetch('http://127.0.0.1:'+(process.env.PORT||3670)+'/demo/landing-poster.png').then(r=>process.exit(r.status===200?0:1)).catch(()=>process.exit(1))" 2>/dev/null; do + if [ "$waited" -ge "$HEALTH_TIMEOUT" ]; then + echo "demoflow-production-web does not serve /demo/landing-poster.png after ${HEALTH_TIMEOUT}s" >&2 + docker logs --tail 60 demoflow-production-web >&2 || true + exit 1 + fi + sleep 5 + waited=$((waited + 5)) +done + { echo "DEPLOYED_SHA=${CI_COMMIT_SHA:-unknown}" echo "DEPLOYED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)" diff --git a/deploy/production/status.sh b/deploy/production/status.sh index 59e57256..41706139 100755 --- a/deploy/production/status.sh +++ b/deploy/production/status.sh @@ -22,7 +22,13 @@ done echo echo "── public" -for path in / /api/health; do - printf '%-14s %s\n' "$path" "$(curl -s -o /dev/null -w '%{http_code}' --max-time 10 "$HOST$path")" +# The poster stands for apps/web/public: a 404 there means the web image was +# built without it. +failed=0 +for path in / /api/health /demo/landing-poster.png; do + code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 10 "$HOST$path")" + printf '%-26s %s\n' "$path" "$code" + [ "$code" = 200 ] || failed=1 done echo "(530 / error 1033: the hostname exists but no tunnel connector is running)" +exit "$failed" diff --git a/deploy/staging/refresh.sh b/deploy/staging/refresh.sh index 17b0ec32..d8bd2303 100755 --- a/deploy/staging/refresh.sh +++ b/deploy/staging/refresh.sh @@ -108,6 +108,20 @@ while :; do waited=$((waited + 5)) done +# The web image must serve apps/web/public; the poster stands for all of it. +# Asked from inside the container, so it does not depend on the tunnel. +echo "Waiting for the web app to serve /demo/landing-poster.png (up to ${HEALTH_TIMEOUT}s)..." +waited=0 +until docker exec demoflow-staging-web node -e "fetch('http://127.0.0.1:'+(process.env.PORT||3670)+'/demo/landing-poster.png').then(r=>process.exit(r.status===200?0:1)).catch(()=>process.exit(1))" 2>/dev/null; do + if [ "$waited" -ge "$HEALTH_TIMEOUT" ]; then + echo "demoflow-staging-web does not serve /demo/landing-poster.png after ${HEALTH_TIMEOUT}s" >&2 + docker logs --tail 60 demoflow-staging-web >&2 || true + exit 1 + fi + sleep 5 + waited=$((waited + 5)) +done + { echo "DEPLOYED_SHA=${CI_COMMIT_SHA:-unknown}" echo "DEPLOYED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)" diff --git a/deploy/staging/status.sh b/deploy/staging/status.sh index ba190124..fb1b4a55 100755 --- a/deploy/staging/status.sh +++ b/deploy/staging/status.sh @@ -22,7 +22,13 @@ done echo echo "── public" -for path in / /api/health; do - printf '%-14s %s\n' "$path" "$(curl -s -o /dev/null -w '%{http_code}' --max-time 10 "$HOST$path")" +# The poster stands for apps/web/public: a 404 there means the web image was +# built without it. +failed=0 +for path in / /api/health /demo/landing-poster.png; do + code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 10 "$HOST$path")" + printf '%-26s %s\n' "$path" "$code" + [ "$code" = 200 ] || failed=1 done echo "(530 / error 1033: the hostname exists but no tunnel connector is running)" +exit "$failed" From 854ccfee8ae36d78be7c3c3b287f5ed6b6c670c3 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 13:24:14 +0100 Subject: [PATCH 04/71] fix(cli): drop unused import and format auth spec --- apps/cli/test/auth/auth.spec.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/apps/cli/test/auth/auth.spec.ts b/apps/cli/test/auth/auth.spec.ts index 5bdfc1ae..48e5003a 100644 --- a/apps/cli/test/auth/auth.spec.ts +++ b/apps/cli/test/auth/auth.spec.ts @@ -22,7 +22,7 @@ import { readCredentials, writeCredentials, } from '../../src/auth/credentials.ts'; -import { DEFAULT_SERVER, resolveServer } from '../../src/auth/server.ts'; +import { resolveServer } from '../../src/auth/server.ts'; import type { Io } from '../../src/commands/io.ts'; import { type AuthDeps, loginCommand } from '../../src/commands/login.ts'; import { logoutCommand } from '../../src/commands/logout.ts'; @@ -239,7 +239,9 @@ describe('resolveServer', () => { const env = { DEMOFLOW_SERVER: 'http://env.test/' }; expect(resolveServer('http://flag.test', env)).toBe('http://flag.test'); expect(resolveServer(undefined, env)).toBe('http://env.test'); - expect(resolveServer(undefined, {})).toBe('https://demoflow.luna-realm.com'); + expect(resolveServer(undefined, {})).toBe( + 'https://demoflow.luna-realm.com', + ); }); it('rejects anything but http(s)', () => { From 21b2a0021186fe4e9da3ba2aa22ded2c4a826a34 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 13:30:13 +0100 Subject: [PATCH 05/71] docs: Glass UI redesign and adding a project from the website ADR-0022 (projects added from the website, inside allowed roots) and specs for #373-#380. --- .../0022-projects-added-from-the-website.md | 93 +++++++ docs/adr/README.md | 3 +- docs/specs/373-glass-app-shell.md | 240 ++++++++++++++++++ .../specs/374-glass-projects-runs-machines.md | 164 ++++++++++++ docs/specs/375-glass-auth-device-settings.md | 118 +++++++++ docs/specs/376-glass-landing-and-docs.md | 110 ++++++++ .../377-runner-allowed-roots-inspect-init.md | 193 ++++++++++++++ docs/specs/378-add-project-api.md | 163 ++++++++++++ docs/specs/379-add-project-dialog.md | 149 +++++++++++ docs/specs/380-docs-add-project.md | 81 ++++++ docs/specs/README.md | 8 + 11 files changed, 1321 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0022-projects-added-from-the-website.md create mode 100644 docs/specs/373-glass-app-shell.md create mode 100644 docs/specs/374-glass-projects-runs-machines.md create mode 100644 docs/specs/375-glass-auth-device-settings.md create mode 100644 docs/specs/376-glass-landing-and-docs.md create mode 100644 docs/specs/377-runner-allowed-roots-inspect-init.md create mode 100644 docs/specs/378-add-project-api.md create mode 100644 docs/specs/379-add-project-dialog.md create mode 100644 docs/specs/380-docs-add-project.md diff --git a/docs/adr/0022-projects-added-from-the-website.md b/docs/adr/0022-projects-added-from-the-website.md new file mode 100644 index 00000000..0fbfe39c --- /dev/null +++ b/docs/adr/0022-projects-added-from-the-website.md @@ -0,0 +1,93 @@ +# ADR-0022: Projects added from the website, inside allowed roots + +Status: accepted · Date: 2026-10-26 · Supersedes: [ADR-0016](0016-website-started-runs.md) §2 · Extends: [ADR-0008](0008-cloud-boundary.md) §3 (three more requests: inspect, initialise and register a folder) + +## Context + +Today a project reaches the website only after its machine reported a run: +ADR-0016 §2 makes the Runner's `reported-runs.jsonl` the registry, and a root +bound by hand on the website (spec 178, Decision 4) is never enough. The +first experience is therefore "install the CLI, `cd` into the repository, run +a scenario, then come back to the website". The owner wants to add a project +from the website: name a folder on a paired machine, see whether it is a +DemoFlow project, create the config if it is not, and link its GitHub +repository (interview, 2026-10-26). + +ADR-0016 §2 exists for one reason: a compromised website account must not be +able to point a Runner at any folder of the user that holds a +`demoflow.config.json` and run its `devCommand`. Letting the website name a +folder reopens exactly that, so the Runner needs its own boundary that the +website cannot move. + +## Decision + +1. **Allowed roots are the machine's, never the website's.** The Runner keeps + a list of allowed roots in `allowed-roots.json`, next to + `credentials.json` (the directory of `runnerPaths`). The person edits it + only on the machine: `demoflow runner allow <dir>`, + `demoflow runner disallow <dir>`, `demoflow runner roots`. With no file, + the one allowed root is the user's home directory. No request from the + server reads or changes the list. +2. **A folder the website may name** is a canonical directory (its real path, + no symbolic link on the way) that is inside an allowed root, with **no path + segment below that root that starts with `.`** (so `~/.ssh`, `~/.config` + and `~/.cache` are out unless the person allows one of them as a root + itself). Anything else is refused with one code, `path-not-allowed`, and + the refusal does not say whether the folder exists. +3. **Three new requests the website may make a Runner do**, in addition to + ADR-0008 §3 and ADR-0016 §1: + - **inspect** a named folder: whether it is allowed (§2), whether it holds + `demoflow.config.json` and whether that config parses, the scenario ids + and names under it (the same fields ADR-0016 §1 already lets cross), the + folder's base name, and the GitHub URL of its `origin` remote when that + remote is on `github.com`. The Runner reads the remote from the + repository's git config file; it never runs `git` or any other command. + - **initialise** a named folder: write the `demoflow init` template + (`demoflow.config.json` and `demoflow/first.demo.json`, spec 273) with + the same never-overwrite rule. The website sends no file body, no + `baseUrl`, no command: the template is the CLI's own. `devCommand` and + every other setting stay the person's to edit in the repository. + - **register** a named folder: after re-checking §2 and that the config + exists, the Runner appends the canonical root to its local + `website-projects.jsonl` and answers with that canonical string, which + becomes the project's `rootPath` on the server. +4. **The registry is the union of the two local files.** ADR-0016 §2's rule + becomes: a project is registered on a machine when that machine reported a + run from its root **or** registered the root through §3. ADR-0016 §3 still + holds: the server names a project by the `rootPath` it holds, and the + Runner acts only when that string is in its registry. A registered root + that leaves the allowed roots later (`disallow`) stops being served for + website-started work until it is allowed again; a root that came from a + local run is unaffected, because the person ran it there. +5. **The GitHub URL is display metadata.** It is stored on the project + (`https://github.com/<owner>/<repo>` only), shown as a link, and editable + on the website. Nothing clones, fetches or pulls it. A project added from + the website records its origin (`website` vs `reported`) for support and + for the UI. +6. **The machine must be online.** Inspect, initialise and register are live + requests over the Runner socket, like `scenarios.list`; with the machine + offline the website says so and adds nothing. + +## Consequences + +- A compromised website account can learn, for folders inside the allowed + roots, whether they are DemoFlow projects, their scenario names and their + GitHub remotes, and can write the init template into a folder that has no + config. It still cannot run a `devCommand` the person did not write: the + template has none, and a folder needs a config before it can be + registered. The person narrows this exposure with `demoflow runner allow`; + the default (the home directory without hidden folders) is the cost + accepted for a first experience that works without a terminal. +- Writing into the repository from the website happens for the first time, + limited to two fixed files that are never overwritten. ADR-0020's rule that + the website never writes repository files otherwise stands: its edits are + exported as a patch. +- The bind-by-hand path of spec 178 (Decision 4) stays in the API for + existing callers; the website's projects page uses the inspect → register + flow instead. +- The Runner gains a second local file to read on every website-started run. + `website-projects.jsonl` is small (one line per added project) and is not + rotated. +- No cloning means a repository that is not on the machine cannot be added; + that is a later decision with its own record, since it would make the + Runner fetch and later execute code it was told about by the server. diff --git a/docs/adr/README.md b/docs/adr/README.md index 48308806..f7cdf960 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -20,9 +20,10 @@ it is accepted: a later record supersedes it and says so. | [0013](0013-page-side-contract.md) | The page-side contract: `data-demoflow-mask` and `window.demoflow` (`ready`, `waitForReady`) | accepted; extended by 0014 | | [0014](0014-page-annotations.md) | Scenes and captions from the page: `window.demoflow.scene` and `caption` | accepted | | [0015](0015-playwright-tests-become-scenarios.md) | Playwright tests become scenarios: a `demoflow/playwright` fixture records a `.demo.json`, the engine replays it; new module `packages/playwright`, optional peer `@playwright/test` | accepted | -| [0016](0016-website-started-runs.md) | Runs started from the website: scenario listing (ids and names), a registered project is a root the machine reported a run from | accepted; §4 superseded by 0017 | +| [0016](0016-website-started-runs.md) | Runs started from the website: scenario listing (ids and names), a registered project is a root the machine reported a run from | accepted; §4 superseded by 0017; §2 superseded by 0022 | | [0017](0017-website-run-options.md) | The website may choose the output formats of a run it starts (formats only; always headless) | accepted | | [0018](0018-fragments-and-off-camera-steps.md) | Step fragments (`include`) are inlined at load time; off-camera steps (`setup`, `record: false`) are an unrecorded prefix run in its own context | accepted | | [0019](0019-opt-in-share-links.md) | Opt-in share links: one render uploaded to the server on an explicit share, unlisted link with an optional password | accepted; supersedes the roadmap's Phase 5 "no public share links", extends 0008 §2–§3 | | [0020](0020-edits-from-the-website.md) | The website may send a run's edits as data and ask its runner to re-render it; edits live in the run directory | accepted; extends 0008 §3 | | [0021](0021-scheduled-checks.md) | Scheduled checks from the website and the project config; check mode runs without recording | accepted; extends 0017 | +| [0022](0022-projects-added-from-the-website.md) | A project may be added from the website: a folder inside the machine's allowed roots, inspected and optionally initialised by the runner; GitHub link as metadata, no cloning | accepted; supersedes 0016 §2, extends 0008 §3 | diff --git a/docs/specs/373-glass-app-shell.md b/docs/specs/373-glass-app-shell.md new file mode 100644 index 00000000..bb9f9188 --- /dev/null +++ b/docs/specs/373-glass-app-shell.md @@ -0,0 +1,240 @@ +# Glass UI app shell: sidebar, breadcrumbs, account menu, light and dark theme, Overview + +Issue: [#373](https://github.com/AndreyBegma/DemoFlow/issues/373) +Depends on: nothing + +## Summary + +Every `/app` page draws its own chrome today. `apps/web/src/app/app/page.tsx` +opens with a line of text ("Signed in as …") and four underlined links; +`projects/page.tsx` and `machines/page.tsx` have a single "back" link; each page +sets its own `mx-auto … max-w-*` column [Confirmed]. Glass UI is installed and +its primitives are used inside the pages (`Card`, `Banner`, `Button`, +`EmptyState`, …), but there is no navigation, no app frame and no theme choice: +`apps/web/src/app/layout.tsx` hard-codes `data-theme="dark"` [Confirmed]. + +`docs/product/vision.md` §9 asks for glass chrome — navigation, top bars, +summary cards, runner connection status — over readable content surfaces. This +slice builds that chrome once, in `apps/web/src/app/app/layout.tsx`, so every +present and future `/app/**` page sits inside it, and gives the website a light +theme next to the dark one. It also redesigns the Overview (`/app`), the first +page a signed-in person sees. + +The reference design is the Nautelle web app +([AndreyBegma/Nautelle](https://github.com/AndreyBegma/Nautelle), +`apps/web/src/components/shell/**`, `apps/web/src/components/page-header/page-header.tsx`, +`apps/web/src/components/overview/dashboard.tsx`), which builds the same shell +from the same library. + +## Scope + +### In scope + +- `apps/web/src/components/shell/**` (new): `app-shell.tsx`, `sidebar.tsx`, + `top-bar.tsx`, `account-menu.tsx`, `machine-status.tsx`, `crumb-names.tsx` + (the client context of Decision 5). +- `apps/web/src/components/brand/logo.tsx` (new): the DemoFlow mark and + wordmark, used by the sidebar here and by #375 (auth pages) and #376 + (landing and docs headers). +- `apps/web/src/lib/` (new, pure, tested the way the existing `lib/*.test.mjs` + are): `nav.ts`, `crumbs.ts` + `crumbs.test.mjs`, `theme.ts` + + `theme.test.mjs`, `overview-stats.ts` + `overview-stats.test.mjs`. +- `apps/web/src/app/app/layout.tsx`: renders the shell around `children`; keeps + the session guard unchanged (spec 124, decision 4; spec 135, decision 6). +- `apps/web/src/app/layout.tsx`: theme bootstrap script in `<head>`, + `suppressHydrationWarning` on `<html>`, no hard-coded `data-theme`. +- `apps/web/src/app/app/page.tsx` and `apps/web/src/components/dashboard/**`: + the Overview inside the shell (summary cards, recent projects, machines, + empty states). The verify-email banner moves into the shell (shown on every + `/app` page while the address is unverified). +- Every other `/app/**` page loses its own header row ("back" links, the + signed-in line, the sign-out button): `projects/page.tsx`, + `projects/[id]/page.tsx`, `projects/[id]/runs/[runId]/page.tsx`, + `machines/page.tsx`, `settings/page.tsx`, `device/page.tsx`. Only the header + rows and the outer `<main>` column change; the page bodies are #374 and #375. +- `apps/web/package.json`, `bun.lock`: `@andrewbehma/glass-ui` 0.34.0 → 0.37.0 + (Decision 7). +- `apps/web/src/i18n/en.ts`: `app.shell.*` keys (nav labels, account menu, + theme names, machine status), `dashboard.*` for the new cards. +- `apps/web/package.json` `test` script: the two new `*.test.mjs`. + +### Out of scope + +- The bodies of projects, runs, the run page and machines (#374); auth pages, + device approval and settings bodies (#375); landing and docs (#376). +- The Shares entry in the sidebar (Decision 3): #350 adds it. +- A command palette, notifications, keyboard shortcuts (Nautelle has them; no + source asks for them here). +- Any API change. The Overview uses only `getProjects()` and `getRunners()` + that `app/page.tsx` already calls [Confirmed]. +- Glass UI's `material-light` module: it is a pointer-highlight effect for + `.lit` surfaces, not the light theme [Confirmed: `dist/material-light.d.ts`]. + The light theme is `data-theme="light"` in `tokens.css` / `material.css` + [Confirmed]. + +## Decisions + +1. **Layout: a glass sidebar** — owner's choice in the 2026-10-26 interview + (the left-sidebar preview). Desktop (≥ the library's `desktop` breakpoint): + a fixed left `NavRail` (`@andrewbehma/glass-ui/nav-rail`) with the brand, + the nav items and the machine status at the bottom; a top bar over the + content with breadcrumbs on the left and the account menu on the right. + Narrow screens: the sidebar becomes a `Sheet` drawer + (`@andrewbehma/glass-ui/sheet`) opened from a menu button in the top bar. + Same pairing as Nautelle's `rail.tsx` + `app-shell.tsx` + (`useBreakpoint() === 'desktop'`). +2. **Nav items, in order**: Overview (`/app`), Projects (`/app/projects`), + Machines (`/app/machines`), Settings (`/app/settings`). The active item is + the longest matching prefix of the pathname. The list is one exported array + in `nav.ts`, so later slices add an item with a one-line change. +3. **Shares is not shown until #350 lands.** A disabled item leads nowhere and + reads as broken; #350 owns `/app/shares` and adds its entry to `nav.ts` in + the same pull request. The owner's preview listed Shares — it arrives with + its page, not before. +4. **Machine status at the bottom of the sidebar**: one row per paired machine + (name, a dot: online = success tone, offline = muted), from `getRunners()` + (`Runner.online`, `lastSeenAt` [Confirmed `apps/web/src/lib/api.ts`]); more + than three machines collapse to "N machines · M online" linking to + `/app/machines`. No machine: a "Pair a machine" link to `/docs/runner`. + The data is read once per navigation on the server, like the Overview + today; no polling in this slice. +5. **Breadcrumbs from the pathname, names from the page.** `crumbs.ts` maps a + pathname to segments (`/app/projects/<id>/runs/<runId>` → Projects › + `<project>` › `<run>`); a page that knows a segment's display name passes it + through a small client context (`useCrumbName(segment, name)`), as + Nautelle's `use-crumb-names.ts` does. Until a name arrives the crumb shows a + neutral placeholder, never a raw id. The existing + `apps/web/src/components/projects/run-breadcrumbs.tsx` is replaced by this + (its page is #374's; this slice removes only its use in the header row). +6. **Theme: system, dark, light.** `theme.ts` holds the modes, a + `df-theme` localStorage key, and an inline bootstrap script that sets + `data-theme` before first paint (Nautelle's `theme.ts`, spec D7 there). The + default is the system preference. The account menu has a three-way + `SegmentedControl` (System / Dark / Light). `data-scale="desk"` stays. + Storage blocked → the choice lasts until reload; no flash of the wrong theme + either way. +7. **Glass UI 0.37.0.** Nautelle pins it; 0.35–0.37 add `breakpoints`, + `use-breakpoint`, `section`, `list-detail`, `launcher`, `date-field`, + `time-field`, `floating-window`, `period-switcher`, `use-scroll-into-row` + and remove nothing that DemoFlow imports today [Confirmed: export maps of + 0.34.0 and 0.37.0 compared; DemoFlow imports 18 subpaths, all present in + 0.37.0]. The shell needs `use-breakpoint`. The bump is pinned exactly + (`bunfig.toml`) and lives in this slice only. 0.38.0 exists; not taken + without a reason — the reference app runs 0.37.0. +8. **Account menu** (`Menu` + `Avatar`): the email, Account settings, the theme + control, Sign out (the existing `SignOutButton` logic). It replaces the + "Signed in as" line. +9. **Overview** — the owner's preview: a row of `StatTile`s, then Recent + projects, then Machines. + - Tiles: **Projects** (count), **Runs** (sum of `Project.runCount`), + **Failing** (projects whose `lastRun.status` is `failed`). The preview's + "Stale" tile is #363's: it becomes Stale when #362/#363 land. Until then + Failing is the honest number the API already returns. + - Recent projects and Machines keep their data and links + (`recent-projects.tsx`, `machines-summary.tsx`), restyled as `Card`s with + `EmptyState` for none. + - A failed load shows a `Banner` per section, as today. +10. **Glass where vision §9 puts it.** Glass material on the sidebar, top bar, + account menu, drawer and stat tiles. Lists and content cards use the solid + card surface. No component of our own where Glass UI has one (CLAUDE.md). + +## UI + +``` +┌──────────┬──────────────────────────────────┐ +│ ◆DemoFlow│ Projects › landing (A)▾ │ ← top bar (glass) +│░░░░░░░░░░├──────────────────────────────────┤ +│ Overview │ ┌────────┐ ┌────────┐ ┌───────┐ │ +│ Projects │ │Projects│ │ Runs │ │Failing│ │ ← StatTile row +│ Machines │ └────────┘ └────────┘ └───────┘ │ +│ Settings │ Recent projects │ +│ │ │ landing ● passed 2m ago │ │ +│ ● devbox │ Machines │ +└──────────┴──────────────────────────────────┘ + sidebar (glass), machine status at the bottom +``` + +Narrow: top bar with ☰ (opens the drawer) · crumbs · avatar; content full width. + +## Acceptance criteria + +- [ ] Every `/app/**` page (`/app`, `/app/projects`, `/app/projects/[id]`, + `/app/projects/[id]/runs/[runId]`, `/app/machines`, `/app/settings`, + `/app/device`) renders inside the shell; none renders its own back link, + signed-in line or sign-out button. +- [ ] The active nav item matches the page, including nested routes (a run + page highlights Projects). +- [ ] At 375 px wide there is no horizontal scroll on any `/app` page; the + sidebar is a drawer that opens and closes from the top bar and with Esc. +- [ ] Theme: System follows `prefers-color-scheme` live; Dark and Light stick + across reloads; no flash of the other theme on load (checked with a + throttled reload in both modes); blocked storage still renders. +- [ ] Body text and secondary text meet WCAG AA contrast in both themes on + the shell surfaces and the Overview (checked with the browser's contrast + tool; values in the PR). +- [ ] Breadcrumbs never show a raw id: the run page shows the project name and + the scenario name. +- [ ] The Overview tiles show the right numbers for a fixture of projects + (`overview-stats.test.mjs`), and empty states + appear for no projects and no machines. +- [ ] The unverified-email banner appears on every `/app` page while + unverified, and never after verification. +- [ ] `bun run check`, `bun run build`, `bun run --filter web test` pass; + `crumbs.test.mjs` covers every `/app` route and `theme.test.mjs` covers mode resolution and blocked storage. +- [ ] The PR has screenshots of `/app` and `/app/projects` in both themes, at + desktop and 375 px. + +## Parallel plan + +Honestly one slot: the shell, the layout and the header-row removals are one +change — a page without its header but outside the shell would have no +navigation at all. + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i373-shell | shell, theme, Overview, Glass UI bump | apps/web/src/components/shell/**, apps/web/src/components/brand/**, apps/web/src/lib/nav.ts, apps/web/src/lib/crumbs*, apps/web/src/lib/theme*, apps/web/src/lib/overview-stats*, apps/web/src/components/dashboard/**, apps/web/src/app/layout.tsx, apps/web/src/app/app/layout.tsx, apps/web/src/app/app/page.tsx, apps/web/src/app/app/**/page.tsx, apps/web/src/i18n/en.ts, apps/web/package.json, bun.lock | — | yes | opus | + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| apps/web/package.json, bun.lock | i373-shell | no other slice of #373–#376 changes dependencies | +| apps/web/src/app/app/layout.tsx, apps/web/src/app/layout.tsx | i373-shell | #374–#376 do not open them | +| apps/web/src/components/brand/logo.tsx | i373-shell | #375 and #376 import it, never edit it | +| apps/web/src/lib/nav.ts | i373-shell | #350 adds the Shares item after this merges | +| apps/web/src/app/app/**/page.tsx | i373-shell (header rows) | #374/#375 rebase onto it for the page bodies | +| apps/web/src/i18n/en.ts | i373-shell | every web slice appends keys; whoever merges second rebases (append-only) | +| apps/web/src/app/app/page.tsx | i373-shell | #363 (stale tile, stale block on `/app`) and #350 build on the new Overview — they come after this | + +Phase 8 web slices #350, #351, #357, #358 and #363 build on the shell and on +#374's pages; they are ordered after #373 (and #374 where they touch its +pages). + +## Risks + +- **Hydration warnings from the theme script** (medium). Mitigation: + `suppressHydrationWarning` on `<html>` only, script is a constant string. +- **Luna Player's stylesheet in light theme** (medium): `luna-player/player.css` + is imported globally [Confirmed `globals.css`]; its controls may assume a + dark backdrop. The player sits on a black video surface either way; check it + in light and note it in the PR. A fix belongs to #374. +- **Glass UI 0.37 behaviour changes** inside components DemoFlow already uses + (low–medium): exports are a superset, but styles may move. Mitigation: the + PR screenshots cover every page; a regression found there is fixed in this + slice or the bump is dropped to 0.34.0 with `use-breakpoint` replaced by a + CSS breakpoint. +- **Server data in a client shell** (low): the shell's machine list comes from + the layout (server) and is passed down; no client fetch is added. + +## Open questions + +- **Logo.** [Unknown] whether a brand asset exists — `apps/web/public/` holds + only the landing poster and video [Confirmed]. Default: a simple geometric + SVG mark drawn with the accent token plus the "DemoFlow" wordmark in the UI + font; the owner can replace the SVG later. + +- **Collapse the sidebar on desktop?** Default: no — fixed width, no collapse + control, as the owner's preview. Nautelle's `rail-collapse.ts` is the + reference if it is wanted later. +- **Theme in the account settings page too?** Default: only the account menu; + settings is #375's and can link to it. diff --git a/docs/specs/374-glass-projects-runs-machines.md b/docs/specs/374-glass-projects-runs-machines.md new file mode 100644 index 00000000..f65ea60a --- /dev/null +++ b/docs/specs/374-glass-projects-runs-machines.md @@ -0,0 +1,164 @@ +# Glass UI for projects, runs, the run page and machines + +Issue: [#374](https://github.com/AndreyBegma/DemoFlow/issues/374) +Depends on: #373 (the shell, the theme, Glass UI 0.37.0) + +## Summary + +After #373 every `/app` page sits in the glass shell, but the page bodies are +still the first-version layouts: a single `Card` per page with an `h1`, hand +`<table>`s with fixed minimum widths (`runs-table.tsx` `min-w-[44rem]`, +`machine-list.tsx` `min-w-[48rem]` [Confirmed]), status as two `Badge`s +(`run-status.tsx`) and launch state as a `StatusPill` (`launch-status.tsx`) +[Confirmed]. Vision §9 asks for functional status indicators for running, +completed, failed and unavailable, a video page with a glass metadata panel, +and readable dense tables (no glass on them). + +This slice redesigns the bodies of the projects list, the project page, the +runs table, the run page and the machines page on Glass UI primitives, with one +status vocabulary used everywhere. Behaviour, data and API calls stay as they +are. + +## Scope + +### In scope + +- `apps/web/src/app/app/projects/page.tsx`, `projects/[id]/page.tsx`, + `projects/[id]/runs/[runId]/page.tsx`, `machines/page.tsx`: page bodies. +- `apps/web/src/components/projects/**`: `project-list.tsx`, `runs-table.tsx`, + `run-details.tsx`, `run-status.tsx`, `launch-status.tsx`, `start-run.tsx`, + `format-choice.tsx`, `run-again.tsx`, `delete-run.tsx`; `run-breadcrumbs.tsx` + is deleted (its job moved to the shell crumbs in #373). +- `apps/web/src/components/player/run-playback.tsx` (the frame around the + player; the adapters `luna-video-player.tsx`, `native-video-player.tsx` and + `video-player.ts` are not changed). +- `apps/web/src/components/machines/machine-list.tsx`. +- `apps/web/src/components/status/status-indicator.tsx` (new, Decision 2) and + `apps/web/src/lib/status.ts` + `status.test.mjs` (the mapping). +- `apps/web/src/i18n/en.ts`: keys these pages add (status labels, empty states). + +### Out of scope + +- The shell, nav, breadcrumbs and theme (#373). +- Share (#350), the editor's Edit button and route (#357), schedule controls and + stale badges (#363): they build on these pages after this merges. +- API changes, new data on any page. +- Luna Player's own controls and stylesheet. + +## Decisions + +1. **Page frame: `PageHeader` + sections.** Each page starts with + `@andrewbehma/glass-ui/page-header` (title, one-line description, primary + action on the right — e.g. Start run on the project page) and groups its + content in `section-header` + solid `Card`s. No page renders a back link; + the shell crumbs do that (#373 Decision 5). Same structure as Nautelle's + `apps/web/src/components/page-header/page-header.tsx`. +2. **One status vocabulary.** `lib/status.ts` maps every state the pages show + to one of five kinds — `running`, `passed`, `failed`, `unavailable` + (artifacts deleted, machine offline for playback), `idle` (never run) — and + `status-indicator.tsx` renders it with Glass UI `StatusPill` (dot + label, + tone per kind). `RunStatus` and `LaunchStatus` use it; the runs table, + project list, run page and machines page show the same pill for the same + state. Colour is never the only signal: every pill has its text label. +3. **Tables stay solid and readable** (vision §9 "where not to overuse + glass"). The runs table and machines list move to Glass UI + `@andrewbehma/glass-ui/table` (or `data-table` where sorting is already + offered — keep the existing behaviour, add none) on the solid card surface. + On narrow screens they become stacked rows instead of a horizontal scroll + (`responsive-rows` pattern in Nautelle's `apps/web/src/components/responsive-rows`), + so the `min-w-[44rem]` / `min-w-[48rem]` go. +4. **Run page: player first, glass metadata panel beside it.** Desktop: the + player (16:9, black surface) takes the main column; a glass side panel holds + status, scenario, path, when, duration, machine, formats, stages and the + failure message, plus the actions (Run again, Download, Delete). Narrow: the + panel stacks under the player. The `KeyValueList` stays the content of the + panel. Failure messages and stage details are code-like text: solid surface, + monospace, never glass (vision §9). +5. **Project page**: header with the project name, root path (muted, truncated + with a tooltip), machine pill; Start run as the header's primary action + (`start-run.tsx` behaviour unchanged); the status filter + (`SegmentedControl`) above the runs table. +6. **Projects list**: one row per project — name, machine, last run pill, + relative time, run count — as a solid list card; `EmptyState` with a link to + the first-run docs when there are none. +7. **Machines page**: one row per machine — name, OS, CLI version, online pill + (online is a success-tone "Online" pill, offline the `unavailable` kind — + not `running`, which means a run in progress), last seen; revoke stays a + `ConfirmDialog`. + +## UI + +``` +Run page (desktop) +┌─ crumbs: Projects › landing › Create a post ─────────────── (A)▾ ┐ +│ Create a post ● Passed [Run again][⋯] │ +│ ┌──────────────────────────────┐ ┌──────────────── glass ──────┐ │ +│ │ │ │ Scenario Create a post │ │ +│ │ player 16:9 │ │ Path demoflow/post… │ │ +│ │ │ │ When 2 min ago │ │ +│ └──────────────────────────────┘ │ Duration 14 s · mp4, gif │ │ +│ │ Machine ● devbox │ │ +│ │ Stages ✓✓✓✓✓✓ │ │ +│ └─────────────────────────────┘ │ +└──────────────────────────────────────────────────────────────────┘ +``` + +## Acceptance criteria + +- [ ] The five status kinds render with the same pill (tone and label) on the + projects list, the project page, the runs table, the run page and the + machines page; `status.test.mjs` covers the mapping from every run, + launch, artifact and machine state the API returns. +- [ ] At 375 px no page scrolls horizontally; the runs table and the machines + list show stacked rows. +- [ ] The run page shows the player and the metadata panel side by side at + ≥ 1024 px and stacked below; playback, download, run again and delete + behave exactly as before (existing `lib/*.test.mjs` still pass). +- [ ] Failure messages and stage details are on a solid surface in a monospace + font in both themes. +- [ ] Text meets WCAG AA contrast in both themes on every page in scope + (values in the PR). +- [ ] No page renders its own back link; `run-breadcrumbs.tsx` is gone. +- [ ] `bun run check`, `bun run build`, `bun run --filter web test` pass. +- [ ] The PR has screenshots of each page in both themes at desktop and 375 px, + including a failed run and an unavailable video. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i374-pages | the four page bodies and their components | apps/web/src/app/app/projects/**, apps/web/src/app/app/machines/**, apps/web/src/components/projects/**, apps/web/src/components/machines/**, apps/web/src/components/player/run-playback.tsx, apps/web/src/components/status/**, apps/web/src/lib/status.ts, apps/web/src/lib/status.test.mjs, apps/web/src/i18n/en.ts, apps/web/package.json | #373 | yes | sonnet | + +One slot: the status vocabulary is shared by all four pages, and splitting the +pages would put `status-indicator.tsx` and `en.ts` in every branch. +`apps/web/package.json` is touched only to add `status.test.mjs` to the `test` +script — no dependency change. + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx | i374-pages | #350 (Share button), #357 (Edit button), #358 come after this merges | +| apps/web/src/components/projects/run-details.tsx, runs-table.tsx | i374-pages | #363 (stale badges) comes after | +| apps/web/src/app/app/projects/[id]/page.tsx | i374-pages | #363 (schedule controls) comes after | +| apps/web/src/i18n/en.ts | i374-pages | append-only; whoever merges second rebases | +| apps/web/package.json (`test` script line only) | i374-pages | #373 owns the dependency bump and merges first | + +## Risks + +- **Stacked rows lose sorting cues** (low): the runs table has a status filter, + not column sorting [Confirmed `runs-table.tsx` takes a filter]; nothing to + lose. Re-check if a later slice adds sorting. +- **Player in light theme** (medium): the player stays on a black surface in + both themes; if `luna-player/player.css` controls read poorly in light, the + frame keeps a dark backdrop around the player only. +- **Behaviour regressions in actions** (medium): delete, run again and download + have their own specs (281, 282, 300). The slice moves them into the panel + without changing their logic; the PR lists each and how it was checked. + +## Open questions + +- **Run page side panel width.** Default: 22 rem at ≥ 1024 px; the player takes + the rest. +- **Project root path on the project page** — full or truncated? Default: + truncated from the left with the full path in a tooltip and a copy button. diff --git a/docs/specs/375-glass-auth-device-settings.md b/docs/specs/375-glass-auth-device-settings.md new file mode 100644 index 00000000..fc7f5eae --- /dev/null +++ b/docs/specs/375-glass-auth-device-settings.md @@ -0,0 +1,118 @@ +# Glass UI for sign-in, sign-up, password reset, device approval and account settings + +Issue: [#375](https://github.com/AndreyBegma/DemoFlow/issues/375) +Depends on: #373 (the theme and Glass UI 0.37.0; device and settings sit in the shell) + +## Summary + +The auth pages (`/sign-in`, `/sign-up`, `/verify-email`, `/forgot-password`, +`/reset-password`) all render through `AuthCard` +(`apps/web/src/components/auth/auth-card.tsx`): a plain `Card` centred on an +empty page [Confirmed]. They are the first thing a new user sees after the +landing page, and the device page (`/app/device`) is where `demoflow login` +sends them — today a narrow column with a form. Account settings +(`/app/settings`) is a single column of sections. None of them has a brand +mark, and none follows the theme the user picked (that arrives with #373). + +This slice gives the auth pages a branded glass frame, makes device approval a +clear, single-purpose screen, and lays out account settings as sections inside +the shell — with the same forms, flows and API calls. + +## Scope + +### In scope + +- `apps/web/src/components/auth/**`: `auth-card.tsx` (the frame), + `form-parts.tsx`, the forms (`sign-in-form.tsx`, `sign-up-form.tsx`, + `forgot-password-form.tsx`, `reset-password-form.tsx`, `verify-email.tsx`, + `resend-button.tsx`), `unlink-github-button.tsx`; their visuals only. +- `apps/web/src/app/{sign-in,sign-up,verify-email,forgot-password,reset-password}/page.tsx`. +- `apps/web/src/app/app/device/page.tsx`, `apps/web/src/components/device/**`. +- `apps/web/src/app/app/settings/page.tsx`, `apps/web/src/components/settings/**`. +- `apps/web/src/i18n/en.ts`: keys these pages add. + +### Out of scope + +- Auth logic, validation, throttling, GitHub OAuth, session handling. +- The shell around device and settings (#373). +- The landing page and docs (#376), except that they may import `logo.tsx`. + +## Decisions + +1. **Auth frame: a glass panel on a quiet background.** The auth pages are + outside `/app`, so they have no shell. `AuthCard` becomes: the logo above, + a glass `Card` (max-w-md) with the title, the form and the footer links, on + the page background with a soft gradient from the theme tokens (no image). + Forms stay inside the card on the readable field surface — glass is the + frame, not the fields (vision §9). +2. **Same forms, Glass UI fields.** Every input is `@andrewbehma/glass-ui/field` + (already used in `form-parts.tsx` [Confirmed]); errors stay `Banner`s; + primary actions are full-width solid `Button`s; "Continue with GitHub" + (`ProviderSlot`, shown only while the API has GitHub credentials, spec 126 + Decision 5) gets the GitHub mark from `lucide-react` (already a dependency + [Confirmed]). +3. **Device approval is one decision on one screen.** The page states which + code it is approving in large monospace (the code from the URL, or the + entry form when there is none), the machine/CLI context the API returns, + and two buttons: Approve (solid) and Deny. After approval: a success state + ("You can close this tab, `demoflow` is signed in") instead of returning to + a form. Behaviour of `device-approval.tsx` / `device-code-form.tsx` is + unchanged. +4. **One brand component.** The auth pages use + `apps/web/src/components/brand/logo.tsx`, which #373 creates for the + sidebar; #376 uses it on the landing and docs headers. +5. **Settings as sections.** Inside the shell: `PageHeader` "Account settings", + then sections — Profile (email, verification state), Sign-in methods + (password, GitHub link/unlink), Danger zone (delete account, + `ConfirmDialog`, existing `delete-account.tsx` flow). The theme control + stays in the account menu (#373, Open question) and settings links to it + with one line. +6. **Both themes.** Every page here is checked in light and dark; no colour + outside the Glass UI tokens. + +## Acceptance criteria + +- [ ] Each auth page renders the logo, a glass card and the form; at 375 px + there is no horizontal scroll and the card has a 16 px gutter. +- [ ] Every flow still works end to end: sign up → verify email → sign in; + forgot → reset → sign in; sign in with GitHub when configured, hidden + when not (`/api/auth/providers` `{ github: false }`). +- [ ] `/app/device?code=XXXX-XXXX` shows the code, Approve and Deny; approving + shows the success state; a wrong or expired code shows the existing error + in a `Banner`. +- [ ] Settings shows the three sections; unlink GitHub and delete account + keep their confirmations. +- [ ] Text and focus rings meet WCAG AA contrast in both themes (values in the PR). +- [ ] `bun run check`, `bun run build`, `bun run --filter web test` pass. +- [ ] The PR has screenshots of sign-in, sign-up, device approval (before and + after approve) and settings in both themes. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i375-auth | auth frame, device, settings | apps/web/src/components/auth/**, apps/web/src/components/device/**, apps/web/src/components/settings/**, apps/web/src/app/sign-in/**, apps/web/src/app/sign-up/**, apps/web/src/app/verify-email/**, apps/web/src/app/forgot-password/**, apps/web/src/app/reset-password/**, apps/web/src/app/app/device/**, apps/web/src/app/app/settings/**, apps/web/src/i18n/en.ts | #373 | yes | sonnet | + +It can run in parallel with #374 and #376: no shared file except `en.ts` +(append-only). + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| apps/web/src/components/brand/logo.tsx | #373 | this slice imports it, never edits it | +| apps/web/src/app/app/settings/page.tsx, device/page.tsx | i375-auth (body) | #373 removed their header rows first | +| apps/web/src/i18n/en.ts | i375-auth | append-only; whoever merges second rebases | + +## Risks + +- **A broken auth flow is a locked-out user** (high). Mitigation: no logic + change; the PR records each flow of the acceptance list run against staging + or a local stack. +- **Glass behind form fields hurts legibility** (medium). Mitigation: + Decision 1 — fields on the solid field surface; contrast values in the PR. + +## Open questions + +- **Background on the auth pages.** Default: the token gradient only, no + illustration. diff --git a/docs/specs/376-glass-landing-and-docs.md b/docs/specs/376-glass-landing-and-docs.md new file mode 100644 index 00000000..aa47f0d9 --- /dev/null +++ b/docs/specs/376-glass-landing-and-docs.md @@ -0,0 +1,110 @@ +# Glass UI polish for the landing page and the docs + +Issue: [#376](https://github.com/AndreyBegma/DemoFlow/issues/376) +Depends on: #373 (the theme, the logo, Glass UI 0.37.0) + +## Summary + +The landing page (`apps/web/src/app/page.tsx`) and the docs +(`apps/web/src/app/docs/layout.tsx`) already have a floating glass header +(`className="glass … rounded-surface"`) and use `Card` for the benefit tiles +and the install block [Confirmed]. They were built before the light theme and +the logo, and they are the website's front door: the landing page is the first +impression, the docs are where a new user stays longest. + +This slice brings both in line with the app shell of #373 — same logo, same +theme control, same header language — and polishes the landing sections, +while keeping the docs a readable long-form surface (vision §9: no glass on +long-form text, code or tables). + +## Scope + +### In scope + +- `apps/web/src/app/page.tsx` and `apps/web/src/components/landing/**` + (`copy-install.tsx`, `demo-video.tsx` — its frame only, not its source). +- `apps/web/src/app/docs/layout.tsx`, `apps/web/src/app/docs/_components/**` + (`docs-sidebar.tsx`, `on-this-page.tsx`), `apps/web/src/mdx-components.tsx`. +- `apps/web/src/components/site-header.tsx` (new): the one header the landing + page and the docs share (Decision 1). +- `apps/web/src/i18n/en.ts`: keys these pages add. + +### Out of scope + +- The landing video's 404 on production and staging: #368 fixes the Docker + image (the file is never copied into it). This slice does not touch + `apps/web/Dockerfile` or `apps/web/public/`. +- The docs' content (`apps/web/src/app/docs/**/page.mdx`) and + `apps/web/src/lib/docs-nav.ts` — Phase 8 docs slices (#352, #359, #364, #365) + edit those. +- Re-recording the landing video (spec 153). + +## Decisions + +1. **One site header** for the landing and the docs, extracted from the two + copies in `page.tsx` and `docs/layout.tsx` [Confirmed: both inline a + `<header className="sticky top-0 z-10 p-3">` with a glass bar]: logo + (`components/brand/logo.tsx` from #373), Docs, a theme toggle (the same + modes and storage key as #373's `lib/theme.ts`), and Open app / Sign in + depending on the session. Glass, floating, as today. +2. **Landing sections.** Hero (headline, subline, primary "Open app" and + secondary copy-install), the demo video in a glass frame with a soft shadow + (the `<video>` itself stays a solid black surface), "Why DemoFlow" as + Glass UI `Card`s with an icon each (`lucide-react`), the install block, and + a short footer (Docs, GitHub, npm). Text stays on solid or near-solid + surfaces; glass for the header, the video frame and the feature cards only. +3. **Docs stay readable.** Sidebar and on-this-page stay glass (they are + navigation); the article column is the plain page surface. Code blocks, + tables and callouts in `mdx-components.tsx` use the solid raised surface + with token colours that pass AA in both themes. Long-form text width stays + at `max-w-3xl` [Confirmed]. +4. **Both themes, no hard-coded colours.** Every colour comes from Glass UI + tokens; the landing hero gradient (if any) is built from tokens so it works + in light. + +## Acceptance criteria + +- [ ] The landing page and every docs page show the shared header with the + logo and a working theme toggle; the choice is the same one the app + shell uses (switching on the landing page carries into `/app`). +- [ ] At 375 px no horizontal scroll on the landing page or on any docs page + (code blocks scroll inside themselves). +- [ ] Docs body text, code and tables meet WCAG AA contrast in both themes + (values in the PR); no glass behind the article text. +- [ ] `bun run check`, `bun run build`, `bun run --filter web test` pass + (`docs-nav.test.mjs` unchanged and green). +- [ ] The PR has screenshots of the landing page and two docs pages (one with + code and a table) in both themes, desktop and 375 px. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i376-site | landing, docs chrome, shared header | apps/web/src/app/page.tsx, apps/web/src/components/landing/**, apps/web/src/components/site-header.tsx, apps/web/src/app/docs/layout.tsx, apps/web/src/app/docs/_components/**, apps/web/src/mdx-components.tsx, apps/web/src/i18n/en.ts | #373 | yes | sonnet | + +Parallel with #374 and #375 once #373 has merged. + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| apps/web/src/app/docs/layout.tsx, mdx-components.tsx | i376-site | Phase 8 docs slices change only `page.mdx` files and `docs-nav.ts`, not these | +| apps/web/src/components/landing/demo-video.tsx | i376-site | #368 changes the Dockerfile only; if it touches this file, merge #368 first | +| apps/web/src/components/brand/logo.tsx, apps/web/src/lib/theme.ts | #373 | imported, never edited | +| apps/web/src/i18n/en.ts | i376-site | append-only; whoever merges second rebases | + +## Risks + +- **Landing changes hide the video fix** (low): the video stays black until + #368 deploys. Check the frame with the local dev server, where + `/demo/landing.mp4` is served from `public/`. +- **Theme toggle on a static page** (low): the landing page is server-rendered; + the toggle is a small client component reusing #373's `lib/theme.ts`, and the + bootstrap script in the root layout already prevents a flash. + +## Open questions + +- **Footer links.** Default: Docs, GitHub (`https://github.com/AndreyBegma/DemoFlow`), + npm (`https://www.npmjs.com/package/demoflow`). +- **Screenshots of the app on the landing page** besides the video. Default: + none in this slice. diff --git a/docs/specs/377-runner-allowed-roots-inspect-init.md b/docs/specs/377-runner-allowed-roots-inspect-init.md new file mode 100644 index 00000000..450fbdd6 --- /dev/null +++ b/docs/specs/377-runner-allowed-roots-inspect-init.md @@ -0,0 +1,193 @@ +# The Runner inspects, initialises and registers a folder the website names, inside allowed roots + +Issue: [#377](https://github.com/AndreyBegma/DemoFlow/issues/377) +Depends on: nothing. Decided by [ADR-0022](../adr/0022-projects-added-from-the-website.md). + +## Summary + +The website will let a person add a project by naming a folder on a paired +machine (#378, #379). This slice is the machine's half: the allowed roots the +person controls on the machine, the path rule that keeps the website out of +everything else, and three socket requests — `project.inspect`, +`project.init`, `project.register` — that the daemon answers. It also widens +the registry that website-started runs check (ADR-0016 §3) to the folders +registered this way. + +## Scope + +### In scope + +- `apps/cli/src/runner/paths.ts`: `allowedRoots` (`allowed-roots.json`) and + `websiteProjects` (`website-projects.jsonl`) in `RunnerPaths` [Confirmed: + the file and `runnerPaths` exist]. +- `apps/cli/src/runner/roots/**` (new): reading and writing the allowed roots, + the path rule (Decision 3), inspection (Decision 5), the git remote reader + (Decision 6), registration (Decision 8). +- `apps/cli/src/runner/command.ts`: `demoflow runner allow <dir>`, + `demoflow runner disallow <dir>`, `demoflow runner roots` [Confirmed: + `registerRunnerCommands` holds the `runner` subcommands]. +- `apps/cli/src/commands/init.ts`: the file-writing half of `initCommand` + moves into an exported `writeInitTemplate(root)` that the daemon and the + command share; the command's output is unchanged [Confirmed: + `initCommand`, `createExclusive` with `flag: 'wx'`]. +- `apps/cli/src/runner/connection.ts`: routing of the three requests, and + `'projects'` in the daemon's announced `features` (Decision 9) [Confirmed: + `case 'scenarios.list'` routing; `launches.sync` is sent at line ~186]. +- `apps/cli/src/runner/launch/checks.ts`: `checkProject` accepts a root found + in either registry file (Decision 8) [Confirmed: it reads `knownRoots` from + `reported-runs.jsonl` today]. +- `apps/cli/test/runner/**`: tests (Vitest under Node). +- `apps/cli/README.md`: the three `runner` subcommands. + +### Out of scope + +- The API messages and endpoints (#378), the dialog (#379), the website docs + (#380). +- Cloning a repository (ADR-0022, Consequences). +- Any change to the `demoflow init` command's flags or output. + +## Decisions + +1. **Allowed roots file.** `allowed-roots.json` is + `{ "roots": ["<absolute canonical dir>", …] }`, at most 32 entries, written + with mode 600 like `credentials.json`. Missing file = `[homedir]`. A file + that does not parse is treated as **no roots** (every path refused) and + `demoflow runner roots` reports it, so a corrupt file never widens access. + *Source:* ADR-0022 §1. +2. **Commands** (all local; no server involved): + - `demoflow runner allow <dir>` — resolves `<dir>` against the cwd, + requires an existing directory, stores its real path. When the file is + missing, the first `allow` writes `[<dir>]` only and prints that the home + directory is no longer allowed. *Why:* a person who narrows the roots + means it; an implicit home entry would undo it. + - `demoflow runner disallow <dir>` — removes the entry equal to its real + path (or to the resolved path when it no longer exists); removing the + last entry leaves `{ "roots": [] }` (nothing allowed), never the default. + - `demoflow runner roots` — prints the effective list, marking the default. + - `--json` on `roots`, like the other commands' structured output. + The daemon reads the file on every request; no restart is needed. +3. **The path rule** (`isAllowedPath(raw, roots, host)`), in order; any + failure is `path-not-allowed`: + - `raw` is a string of 1–4096 characters, absolute for the host platform + (`path.win32.isAbsolute` / `path.posix.isAbsolute`); on Windows a UNC or + device path (`\\`, `\\?\`) is refused. + - its real path (`realpathSync.native`, like `canonicalRoot` in + `apps/cli/src/runs-report/report.ts`) equals the normalised input, i.e. + no symbolic link or junction anywhere on the way. *Why:* a link inside + an allowed root that points outside it must not count as inside. + - it is a directory (`lstat`). + - it equals a root or lies below one: compared segment-wise after + `realpath`, case-insensitively on Windows and macOS, case-sensitively on + Linux. + - no segment between the root and the folder starts with `.`. + The refusal never says which check failed or whether the folder exists. + *Source:* ADR-0022 §2. +4. **Socket requests** (server → daemon), each answered with one reply that + carries the same `requestId`: + + | Request | Fields | Reply | + |---|---|---| + | `project.inspect` | `requestId`, `path` | `project.inspected` with the inspection (Decision 5) | + | `project.init` | `requestId`, `path` | `project.initialised` with `{ created: string[], kept: string[] }` and a fresh inspection | + | `project.register` | `requestId`, `path` | `project.registered` with `{ rootPath }` (canonical) | + | any of them, failing | — | `project.error` with `code`: `path-not-allowed`, `config-missing` (register only), `config-invalid` (register only), `busy`, `internal` | + + Field names and limits are final here; #378 mirrors them in DTOs. +5. **Inspection** answers only: + `{ rootPath, name, hasConfig, configValid, scenarios: [{ id, name }], githubUrl? }` + — `rootPath` canonical; `name` the folder's base name; `scenarios` from + `listScenarios` (`apps/cli/src/runner/launch/list.ts`, ADR-0016 §1 limits) + only when the config is valid; never file contents, never `baseUrl`, + `devCommand` or any other config value. *Source:* ADR-0022 §3, + ADR-0008 §2. +6. **GitHub URL.** Read `<root>/.git/config` (or, when `.git` is a file with + `gitdir: <dir>`, that directory's `config`, one level only, and only when + the gitdir resolves inside an allowed root or inside the folder's parent + repository), at most 64 KiB, parse the `[remote "origin"]` `url`. Accept + `https://github.com/<owner>/<repo>(.git)?`, `git@github.com:<owner>/<repo>(.git)?` + and `ssh://git@github.com/<owner>/<repo>(.git)?`; answer + `https://github.com/<owner>/<repo>`, owner and repo matching + `[A-Za-z0-9._-]{1,100}`. Anything else: no `githubUrl`. No credentials in + the URL ever reach the answer. No `git` process is spawned. *Source:* + ADR-0022 §3. +7. **Init** calls `writeInitTemplate(root)` after the path rule passes: the + same two files and the same `wx` never-overwrite rule as `demoflow init`, + with `baseUrl` `http://localhost:3000`. *Source:* ADR-0022 §3, spec 273. +8. **Register** re-checks the path rule and that `demoflow.config.json` exists + and parses, then appends `{ rootPath, registeredAt }` to + `website-projects.jsonl` (no duplicate lines; at most 1,000 entries, the + oldest dropped beyond). `checkProject` treats a root as known when it is in + `reported-runs.jsonl` **or** in `website-projects.jsonl` **and** still + passes the path rule. *Source:* ADR-0022 §4. +9. **Capability.** The daemon announces `'projects'` in the `features` array + of `launches.sync`. If no earlier Phase 8 slice has added `features` yet + (ADR-0020 introduces it; #347/#355 append to it), this slice adds the + field with `['projects']`, and the API side (#378) accepts it. +10. **Concurrency.** One project request at a time per daemon; a second one + while the first is in flight answers `busy`. Each request is answered + within 5 s or with `internal`. + +## Configuration + +- `allowed-roots.json` (Decision 1). No new environment variable. + +## Acceptance criteria + +- [ ] With no `allowed-roots.json`, `project.inspect` of a folder in the home + directory answers an inspection; of `~/.ssh`, `/etc`, or a folder + outside home answers `path-not-allowed`. +- [ ] A symbolic link inside the home directory pointing to `/tmp/outside` + is refused; so is a path with `..` that resolves outside the root. +- [ ] `demoflow runner allow ~/work` then inspecting `~/other` is refused and + `~/work/app` is accepted; `disallow` of the last root refuses everything. +- [ ] A corrupt `allowed-roots.json` refuses every path and `runner roots` + says the file is invalid. +- [ ] Inspection of a folder without config answers `hasConfig: false`, no + scenarios; with a valid config, the scenario ids and names; it never + contains `baseUrl` or `devCommand`. +- [ ] `githubUrl` is filled for https, scp-style and ssh `origin` remotes on + github.com, empty for other hosts and for a URL with credentials (the + credentials never appear). +- [ ] `project.init` on an empty allowed folder creates both files; + run again, answers both as `kept` and the files are byte-identical. +- [ ] `project.register` of a folder without config answers `config-missing`; + with config, the root appears in `website-projects.jsonl`, and a + website-started `scenarios.list` / `run.start` for that root is accepted + by `checkProject`; after `disallow` of its root it is refused. +- [ ] Path tests run on Linux, macOS and Windows in the execution-plane matrix + (case-insensitive compare on Windows and macOS, drive letters). + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i377-roots | allowed roots, path rule, commands, inspection, init, register | apps/cli/src/runner/roots/**, apps/cli/src/runner/paths.ts, apps/cli/src/runner/command.ts, apps/cli/src/commands/init.ts, apps/cli/src/runner/connection.ts, apps/cli/src/runner/launch/checks.ts, apps/cli/test/runner/**, apps/cli/README.md | — | yes | opus | + +One slot: the path rule, the registry and the socket handlers are one +contract, and the path rule still has platform decisions to make in code. + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| apps/cli/src/runner/connection.ts | i377-roots | #349, #355, #360, #361 add their own routes and `features` strings; rebase, keep every case | +| apps/cli/src/runner/launch/checks.ts | i377-roots | #360 (check mode) may touch it; keep both | +| apps/cli/src/runner/command.ts | i377-roots | #361 (local schedule mode) may add a subcommand | +| apps/cli/README.md | i377-roots | #349, #355, #360, #361 append sections | + +## Risks + +- **Path rule gaps on Windows** (high): junctions, 8.3 short names, case. + Mitigation: compare real paths only; tests on the Windows runner. +- **Default root is broad** (medium): the whole home directory without hidden + folders. Accepted by the owner; the docs (#380) show `runner allow`. +- **`.git` worktree indirection** (low): followed one level, only inside + allowed space; otherwise no GitHub URL. + +## Open questions + +- Should `runner allow` warn when the new root contains no project? + Default: no. +- Should the hidden-segment rule allow `.github`-style folders inside a + project? Default: the rule applies to the path to the project root only, + not to files inside it, so it does not matter. diff --git a/docs/specs/378-add-project-api.md b/docs/specs/378-add-project-api.md new file mode 100644 index 00000000..a4242674 --- /dev/null +++ b/docs/specs/378-add-project-api.md @@ -0,0 +1,163 @@ +# Add a project from the website (API): machine, local path, GitHub link + +Issue: [#378](https://github.com/AndreyBegma/DemoFlow/issues/378) +Depends on: #377 (the Runner's half of the protocol). It can be built against +[that spec](377-runner-allowed-roots-inspect-init.md)'s message table and +merged after it. Decided by +[ADR-0022](../adr/0022-projects-added-from-the-website.md). + +## Summary + +Today `POST /projects` creates a project from a name only, and a folder is +attached by hand with `PATCH /projects/:id` (`runnerId` + `rootPath`, spec 178 +Decision 4) — which ADR-0016 §2 never trusts. This slice adds the website's +inspect → (initialise) → register flow: the API relays three live requests to +the chosen online machine, and creates the project only with the canonical +`rootPath` the Runner answered. Projects gain an optional GitHub URL and a +marker of how they were added. + +## Scope + +### In scope + +- `apps/api/prisma/schema.prisma` + migration + `apps/api/prisma/migrations/20261027150000_project_github_url/` (Data). +- `apps/api/src/projects/folders/**` (new): `FoldersService` (pending + requests keyed by `requestId`, timeouts) and `FoldersController` + (endpoints below), registered in `ProjectsModule` + [Confirmed: `ProjectsModule` imports `RunnerModule`]. +- `apps/api/src/projects/projects.service.ts`, `projects.dto.ts`, + `projects.controller.ts`: `githubUrl` and `source` in `ProjectView`; + `PATCH` accepts `githubUrl` [Confirmed: `ProjectView`, `UpdateProjectDto`, + `PATH_MAX = 4096`]. +- `apps/api/src/runner/runner-socket.ts`: the server messages + `project.inspect | project.init | project.register` and the client DTOs + `project.inspected | project.initialised | project.registered | + project.error` in `CLIENT_MESSAGES`; `features` accepted on + `launches.sync` if no earlier slice added it [Confirmed: `CLIENT_MESSAGES` + record, `scenarios.list` server message]. +- `apps/api/src/runner/runner-connections.service.ts`: routing of the new + replies to `FoldersService`, and the machine's `features` exposed for the + UI [Confirmed: `isOnline(runnerId)`]. +- `apps/api/src/projects/**/*.spec.ts`, `*.integration.spec.ts`: tests. + +### Out of scope + +- The Runner (#377), the dialog (#379), docs (#380). +- Removing the bind-by-hand `PATCH` path (ADR-0022, Consequences). + +## Decisions + +1. **Endpoints** (all behind `SessionGuard`, JSON, `ValidationPipe`): + + | Method | Path | Body | Answer | + |---|---|---|---| + | POST | `/projects/folders/inspect` | `{ runnerId, path }` | `{ inspection }` (#377 Decision 5) | + | POST | `/projects/folders/init` | `{ runnerId, path }` | `{ created, kept, inspection }` | + | POST | `/projects/folders/register` | `{ runnerId, path, name?, githubUrl? }` | `201 { project }` | + + `path` 1–4096 chars (`PATH_MAX`); `name` 1–200 (`PROJECT_NAME_MAX`), + default the inspection's `name`; `githubUrl` must match + `^https://github\.com/[A-Za-z0-9._-]{1,100}/[A-Za-z0-9._-]{1,100}$`, + default the inspection's `githubUrl`. +2. **Ownership first.** Every endpoint resolves `runnerId` to a Runner of the + session's user that is not revoked; otherwise `404 runner-not-found` — + the same answer for "another user's machine" and "no such machine". + *Source:* ADR-0006 tenancy; ADR-0007. +3. **Online and capable.** A machine that is not `isOnline`, or that did not + announce `'projects'` in `features`, answers `409 runner-offline` / + `409 runner-outdated` without sending anything. *Source:* ADR-0022 §6. +4. **Relay.** Each call sends one message with a fresh `requestId` and waits + for the matching reply, at most **10 s** (`FOLDER_TIMEOUT_MS`, like + `LIST_TIMEOUT_MS` in `launches.service.ts`) → `504 runner-timeout`. + `project.error` codes map to `422` (`path-not-allowed`, `config-missing`, + `config-invalid`), `409 busy`, `502 internal`. A reply whose `requestId` + is unknown or belongs to another machine is dropped. +5. **Register creates the row from the Runner's answer.** On + `project.registered`, the API creates `Project { userId, runnerId, + rootPath: <answered canonical path>, name, githubUrl, source: website }`. + The path the browser sent is never stored. An existing project with the + same `(runnerId, rootPath)` of this user answers `409 project-exists` with + its `id`; the `@@unique([runnerId, rootPath])` constraint backs it. +6. **Nothing is stored by inspect or init.** The inspection lives only in the + HTTP answer (ADR-0016 §1 already: lists are read live). +7. **GitHub URL editable.** `PATCH /projects/:id` accepts `githubUrl` (same + pattern) or `null` to clear it. +8. **Throttle.** The three endpoints share a per-user limit of 30 requests per + minute (the existing `ThrottlerGuard` setup), so a hijacked session cannot + scan the home directory quickly. + +## Data / Schema + +```prisma +enum ProjectSource { + reported + website +} + +model Project { + // … existing fields + // https://github.com/<owner>/<repo>; display only (ADR-0022 §5). + githubUrl String? + source ProjectSource @default(reported) +} +``` + +Migration `20261027150000_project_github_url`: `CREATE TYPE "ProjectSource"`, +`ALTER TABLE "Project" ADD COLUMN "githubUrl" TEXT, ADD COLUMN "source" +"ProjectSource" NOT NULL DEFAULT 'reported'`. No backfill. + +## API + +`ProjectView` gains `githubUrl: string | null` and `source: 'reported' | +'website'`. The run page and project list keep their shapes otherwise. + +## Acceptance criteria + +- [ ] `inspect`, `init` and `register` relay to the right machine and answer + what the Runner answered; with the machine offline, `409 runner-offline` + and no socket message is sent. +- [ ] **Authorization:** with user B's session, every endpoint given user A's + `runnerId` answers `404 runner-not-found` and sends nothing to A's + machine; `PATCH` of A's project by B answers 404; `GET /projects` of B + never lists A's website-added projects. +- [ ] `register` stores the canonical `rootPath` from `project.registered`, + not the request's `path` (test: request `~/app/../app`, Runner answers + `/home/u/app`, row holds `/home/u/app`). +- [ ] Registering the same folder twice answers `409 project-exists` with the + first project's id. +- [ ] `githubUrl` with another host or with credentials is rejected with 400. +- [ ] A reply for an unknown `requestId` is ignored; a silent Runner gives + `504 runner-timeout` after 10 s (fake clock). +- [ ] `ProjectView` exposes `githubUrl` and `source`; existing projects read + `source: 'reported'`. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i378-api | schema, migration, folders module, socket messages, view fields | apps/api/prisma/schema.prisma, apps/api/prisma/migrations/20261027150000_project_github_url/**, apps/api/src/projects/**, apps/api/src/runner/runner-socket.ts, apps/api/src/runner/runner-connections.service.ts, apps/api/src/runner/runner-socket.fixtures.ts | #377 merged | yes | sonnet | + +One slot: the column, the relay and the view are one reviewable change. + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| apps/api/prisma/schema.prisma | i378-api (alters `Project`) | #347 adds `Share`, #360 adds `Run.kind`, #362 adds `CheckSchedule`/`ScenarioHealth`; distinct tables/columns — keep both on conflict; migrations have distinct timestamps | +| apps/api/src/runner/runner-socket.ts | i378-api | #347, #356, #362 add messages; rebase, keep every `CLIENT_MESSAGES` entry and the shared `features` array | +| apps/api/src/runner/runner-connections.service.ts | i378-api | #347, #356, #362 add routing | +| apps/api/src/projects/projects.service.ts / dto | i378-api | #362 adds `staleCount`; append both | + +## Risks + +- **Scanning by a hijacked session** (medium): mitigated by the Runner's + allowed roots (#377) and the throttle (Decision 8). +- **Merge order of schema slices** (low): migrations carry distinct + timestamps; the later slice rebases. + +## Open questions + +- Should a website-added project be deletable without touching the Runner's + `website-projects.jsonl`? Default: yes, deleting the row is enough; the + stale local line is harmless because the server never names it again. diff --git a/docs/specs/379-add-project-dialog.md b/docs/specs/379-add-project-dialog.md new file mode 100644 index 00000000..8ecd166e --- /dev/null +++ b/docs/specs/379-add-project-dialog.md @@ -0,0 +1,149 @@ +# Add project dialog: machine, path, inspection result, create config, GitHub link + +Issue: [#379](https://github.com/AndreyBegma/DemoFlow/issues/379) +Depends on: #378 (the endpoints), #374 (the Glass UI projects page this +dialog lives on). Decided by +[ADR-0022](../adr/0022-projects-added-from-the-website.md). + +## Summary + +The projects page today creates a project from a name and binds it by hand +to a machine and a typed `rootPath` (`apps/web/src/components/projects/project-list.tsx`, +`CreateForm`, `mode: 'bind'`) [Confirmed]. This slice replaces both with one +**Add project** dialog: pick an online machine, type a folder path, see what +the machine found there (config, scenarios, GitHub remote), create the +config when it is missing, and add the project. It is built with Glass UI +primitives on the shell and projects page that #374 delivers. + +## Scope + +### In scope + +- `apps/web/src/components/projects/add-project-dialog.tsx` (new) and its + helpers under `apps/web/src/components/projects/add-project/**`. +- `apps/web/src/components/projects/project-list.tsx`: the **Add project** + button opens the dialog; the old name-only `CreateForm` and the inline + bind form are removed from the page; a GitHub link icon on rows with + `githubUrl`. +- `apps/web/src/lib/api.ts`: `inspectFolder`, `initFolder`, `registerFolder`, + `githubUrl` in `updateProject` and in the `Project` type [Confirmed: + `createProject`, `updateProject`, `listRunners` exist]. +- `apps/web/src/lib/add-project.ts` + `add-project.test.mjs`: the pure state + machine of the dialog (Decision 3), tested like `launch.test.mjs`. +- `apps/web/src/i18n/en.ts`: `projects.add.*`. + +### Out of scope + +- The API (#378), the Runner (#377), docs (#380). +- Editing a project's path after it is added (delete and add again). +- A folder browser on the machine: the path is typed (Open questions). + +## Decisions + +1. **Glass UI primitives only** (`CLAUDE.md`, vision §9): `Dialog` (glass + overlay), `Select` or `Combobox` for the machine, `Field`/`Input` for path, + name and GitHub URL, `StatusPill` for the machine state, `Banner` for + refusals, `KeyValueList` for the inspection, `Button`, `Spinner`. Content + inside the dialog stays on readable surfaces, not glass. [Confirmed: the + package exports `dialog`, `combobox`, `select`, `status-pill`, + `key-value-list`, `banner`, `spinner`.] +2. **Machine picker.** Lists the user's machines from `listRunners`; offline + machines are shown disabled with "Offline", machines without the + `'projects'` feature with "Update the CLI to add projects from the + website" (`409 runner-outdated`). The last machine that reported a run is + preselected when online. +3. **Flow** (`add-project.ts` state machine): + `idle → inspecting → inspected(found | no-config | refused) → + (initialising → inspected) → registering → done | error`. + - Typing a path debounces 600 ms, then `inspectFolder`. A new keystroke + cancels the pending result (stale answers are dropped by request + sequence number). + - **Found** (`hasConfig && configValid`): show folder name, scenario count + and the first five scenario names, the GitHub link; **Add project** + enabled. + - **No config**: "This folder has no `demoflow.config.json`." and a + **Create config** button → `initFolder` → shows what was created + ("created demoflow.config.json, demoflow/first.demo.json") and a hint to + set `devCommand` and `baseUrl` in the repository; then the state is + "found". + - **Config invalid**: the refusal text, no Add button. + - **Refused** (`path-not-allowed`): "This folder is outside the folders + this machine allows. On that machine run `demoflow runner allow <dir>`." + with a link to the docs (#380). + - **Add project** → `registerFolder` with the name (default the folder + name) and the GitHub URL (default the inspection's, editable, may be + cleared) → navigates to the new project's page. `409 project-exists` + offers "Open the existing project". +4. **Path hints.** The placeholder shows the machine's platform style + (`/home/you/app`, `C:\Users\you\app`) when the runner reports a platform + [Unknown: whether `listRunners` exposes the platform; if not, a neutral + placeholder]. +5. **No secret or file content is ever displayed**; the dialog renders only + the inspection fields of #377 Decision 5. +6. **Keyboard and a11y.** Focus starts in the machine field, Enter submits + the enabled primary action, Escape closes; status changes are announced + through an `aria-live` region. + +## UI + +``` +┌ Add project ───────────────────────────────┐ +│ Machine [ devbox ● Online ▾ ] │ +│ Folder [ /home/you/dev/my-app ] │ +│ ┌────────────────────────────────────────┐ │ +│ │ ✓ demoflow.config.json 3 scenarios │ │ +│ │ login · create post · billing │ │ +│ │ github.com/you/my-app │ │ +│ └────────────────────────────────────────┘ │ +│ Name [ my-app ] │ +│ GitHub [ https://github.com/you/my-app ]│ +│ [Cancel] [Add project]│ +└────────────────────────────────────────────┘ +``` + +## Acceptance criteria + +- [ ] With an online machine and a folder holding a valid config, the dialog + shows its scenarios and GitHub link and **Add project** creates it and + opens its page. +- [ ] With a folder without config, **Create config** writes the template + through the API, the dialog then shows "found" with one scenario. +- [ ] A `path-not-allowed` answer shows the allow-roots hint and no Add + button. +- [ ] Offline machines cannot be chosen; an outdated machine shows the + update hint. +- [ ] Typing quickly sends at most one inspection per 600 ms pause and never + shows a stale result (unit test on `add-project.ts`). +- [ ] Adding a folder that is already a project offers to open it. +- [ ] Rows with `githubUrl` show a link that opens the repository in a new + tab with `rel="noopener noreferrer"`. +- [ ] The page has no name-only create form and no hand bind form any more. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i379-dialog | the dialog, its state machine, client calls, strings | apps/web/src/components/projects/add-project-dialog.tsx, apps/web/src/components/projects/add-project/**, apps/web/src/components/projects/project-list.tsx, apps/web/src/lib/add-project.ts, apps/web/src/lib/add-project.test.mjs, apps/web/src/lib/api.ts, apps/web/src/i18n/en.ts | #378, #374 merged | yes | sonnet | + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| apps/web/src/components/projects/project-list.tsx | i379-dialog | #374 restyles it first; this slice rebases on it | +| apps/web/src/lib/api.ts | i379-dialog | #350, #351, #357, #358, #363 append functions | +| apps/web/src/i18n/en.ts | i379-dialog | every web issue appends keys | + +## Risks + +- **Restyle collision with #374** (medium): this slice starts only after #374 + merges (board dependency). +- **Typing a path is error-prone** (low): the inspection answers live; a + folder picker is an open question. + +## Open questions + +- A folder browser listing subfolders of the allowed roots? Default: no — + it would be a fourth request that lists directory names; revisit with + usage. +- Keep a "create an empty project without a machine" action? Default: no; + projects without a machine have nothing to show. diff --git a/docs/specs/380-docs-add-project.md b/docs/specs/380-docs-add-project.md new file mode 100644 index 00000000..946314dc --- /dev/null +++ b/docs/specs/380-docs-add-project.md @@ -0,0 +1,81 @@ +# Docs: adding a project from the website, and allowed roots + +Issue: [#380](https://github.com/AndreyBegma/DemoFlow/issues/380) +Depends on: #379 (the dialog this page describes; #377 and #378 come before +it). Decided by [ADR-0022](../adr/0022-projects-added-from-the-website.md). + +## Summary + +The website's Runner page (`apps/web/src/app/docs/runner/page.mdx`) explains +pairing, autostart and website-started runs, and says a project appears after +the machine reported a run [Confirmed: sections "Pair a machine" … "Status on +the site"]. With #377–#379 a project can be added from the website. This +slice documents the flow, the allowed roots and their commands, and corrects +the sentences that ADR-0022 made untrue. + +## Scope + +### In scope + +- `apps/web/src/app/docs/runner/page.mdx`: a new section **Add a project from + the website** after "Runs started from the website", and a section + **Allowed folders** (`demoflow runner allow | disallow | roots`, the default + home-without-hidden-folders rule, what the website can and cannot see, + what "Create config" writes). +- `apps/web/src/app/docs/cli/page.mdx`: the three `runner` subcommands in the + command reference [Confirmed: the page exists]. +- Every sentence on the docs pages that says a project only appears after a + local run: rewritten to "after a local run, or when added from the + website". +- `apps/web/src/lib/docs-nav.test.mjs` only if a new page is added (it is not + by default: both sections live on the Runner page). + +### Out of scope + +- Product code. Screenshots are optional; a short Glass UI–styled diagram of + the flow is enough. + +## Decisions + +1. **One page, two sections**, no new nav entry. *Why:* adding a project is a + Runner capability; the nav (`apps/web/src/lib/docs-nav.ts`) stays at ten + entries. +2. **Security note in plain words:** the machine decides which folders the + website may name; nothing is cloned or downloaded; "Create config" writes + two files and never overwrites; `devCommand` is set by the person in the + repository. *Source:* ADR-0022 §1–§3. +3. **Troubleshooting table:** `Offline`, `Update the CLI`, + `outside the allowed folders`, `config invalid`, `already a project`, + each with the fix. + +## Acceptance criteria + +- [ ] The Runner page documents the dialog's steps and every refusal shown by + #379, with the fix for each. +- [ ] `demoflow runner allow`, `disallow` and `roots` are documented with an + example on Linux/macOS and on Windows paths. +- [ ] No docs page still says a project can only be registered by a local run. +- [ ] `bun run check` and the docs nav test pass. + +## Parallel plan + +| Slot | Owns | Touches | Depends on | Lead | Model | +|---|---|---|---|---|---| +| i380-docs | the two sections and the CLI reference | apps/web/src/app/docs/runner/page.mdx, apps/web/src/app/docs/cli/page.mdx | #379 merged | yes | sonnet | + +## Contention + +| Resource | Owner | Everyone else | +|---|---|---| +| apps/web/src/app/docs/runner/page.mdx | i380-docs | #352, #359, #364 add sections; keep all | +| apps/web/src/app/docs/cli/page.mdx | i380-docs | #349, #355, #360, #361 add commands | + +## Risks + +- **Docs drift from #377's final command names** (low): written after #379 + merges, from the merged code. + +## Open questions + +- A dedicated "Projects" docs page? Default: no, until projects gain more + than one way in. diff --git a/docs/specs/README.md b/docs/specs/README.md index 6825c636..128b69b0 100644 --- a/docs/specs/README.md +++ b/docs/specs/README.md @@ -197,3 +197,11 @@ Work traced to an ADR, the vision or spec 179 that no phase had picked up. | [#363](https://github.com/AndreyBegma/DemoFlow/issues/363) | [Check schedules on the project page, and stale badges](363-check-schedules-web.md) — ADR-0021, Phase 8 | #362 | | [#364](https://github.com/AndreyBegma/DemoFlow/issues/364) | [Website docs: scheduled checks and stale demos](364-checks-docs.md) — ADR-0021, Phase 8 | #361, #363 | | [#365](https://github.com/AndreyBegma/DemoFlow/issues/365) | [Hold the result on screen](365-hold-the-result.md) — Phase 8 | — | +| [#373](https://github.com/AndreyBegma/DemoFlow/issues/373) | [Glass UI app shell: sidebar, breadcrumbs, account menu, light and dark theme, Overview](373-glass-app-shell.md) — Glass UI, vision §9 | — | +| [#374](https://github.com/AndreyBegma/DemoFlow/issues/374) | [Glass UI for projects, runs, the run page and machines](374-glass-projects-runs-machines.md) — Glass UI, vision §9 | #373 | +| [#375](https://github.com/AndreyBegma/DemoFlow/issues/375) | [Glass UI for sign-in, sign-up, password reset, device approval and account settings](375-glass-auth-device-settings.md) — Glass UI, vision §9 | #373 | +| [#376](https://github.com/AndreyBegma/DemoFlow/issues/376) | [Glass UI polish for the landing page and the docs](376-glass-landing-and-docs.md) — Glass UI, vision §9 | #373 | +| [#377](https://github.com/AndreyBegma/DemoFlow/issues/377) | [The Runner inspects, initialises and registers a folder the website names, inside allowed roots](377-runner-allowed-roots-inspect-init.md) — ADR-0022 | — | +| [#378](https://github.com/AndreyBegma/DemoFlow/issues/378) | [Add a project from the website (API): machine, local path, GitHub link](378-add-project-api.md) — ADR-0022 | #377 | +| [#379](https://github.com/AndreyBegma/DemoFlow/issues/379) | [Add project dialog: machine, path, inspection result, create config, GitHub link](379-add-project-dialog.md) — ADR-0022 | #374, #378 | +| [#380](https://github.com/AndreyBegma/DemoFlow/issues/380) | [Docs: adding a project from the website, and allowed roots](380-docs-add-project.md) — ADR-0022 | #377, #378, #379 | From 465d7c89b836e3d654d1f369fd35bd6f1741be81 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 13:34:58 +0100 Subject: [PATCH 06/71] feat(core): render.endHoldMs, a hold on any step and holdMs on the timeline The project config gains render.endHoldMs (0-10000, default 2500): how long a successful video keeps the result on screen after the last step. Every step accepts hold (100-10000 ms), refused on an off-camera step, and a timeline event records the hold it kept as holdMs. Schemas regenerated (spec 365). --- packages/core/schemas/fragment.schema.json | 256 +++++- .../core/schemas/project-config.schema.json | 7 + packages/core/schemas/scenario.schema.json | 768 +++++++++++++++++- packages/core/src/project-config.ts | 5 + packages/core/src/step.ts | 30 +- packages/core/src/timeline.ts | 3 + packages/core/test/project-config.spec.ts | 29 + packages/core/test/scenario.spec.ts | 24 + 8 files changed, 1085 insertions(+), 37 deletions(-) diff --git a/packages/core/schemas/fragment.schema.json b/packages/core/schemas/fragment.schema.json index 669c0841..3325c5d6 100644 --- a/packages/core/schemas/fragment.schema.json +++ b/packages/core/schemas/fragment.schema.json @@ -84,10 +84,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "oneOf": [ { "required": ["path"] @@ -227,10 +244,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "not": { "required": ["state", "zoom"], "properties": { @@ -357,10 +391,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -493,10 +544,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "oneOf": [ { "required": ["value"] @@ -626,10 +694,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target", "option"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -748,10 +833,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -881,10 +983,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "key"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "dependentRequired": { "zoom": ["target"] } @@ -1091,10 +1210,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "oneOf": [ { "required": ["to"] @@ -1221,10 +1357,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -1360,10 +1513,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target", "text"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -1397,10 +1567,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "name"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -1439,10 +1626,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "title"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -1469,10 +1673,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "ms"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -1506,10 +1727,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "name"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", diff --git a/packages/core/schemas/project-config.schema.json b/packages/core/schemas/project-config.schema.json index 471e3269..ba2ef8eb 100644 --- a/packages/core/schemas/project-config.schema.json +++ b/packages/core/schemas/project-config.schema.json @@ -99,6 +99,13 @@ }, "additionalProperties": false }, + "endHoldMs": { + "default": 2500, + "description": "How long a successful video keeps the result on screen after the last step: the engine keeps recording and the renderer keeps the frames. 0 ends the video at the last step.", + "type": "integer", + "minimum": 0, + "maximum": 10000 + }, "frame": { "default": {}, "type": "object", diff --git a/packages/core/schemas/scenario.schema.json b/packages/core/schemas/scenario.schema.json index 0d1324da..4359cefb 100644 --- a/packages/core/schemas/scenario.schema.json +++ b/packages/core/schemas/scenario.schema.json @@ -109,10 +109,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "oneOf": [ { "required": ["path"] @@ -244,10 +261,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "not": { "required": ["state", "zoom"], "properties": { @@ -374,10 +408,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -510,10 +561,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "oneOf": [ { "required": ["value"] @@ -643,10 +711,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target", "option"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -765,10 +850,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -890,10 +992,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "key"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "dependentRequired": { "zoom": ["target"] } @@ -1092,10 +1211,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "oneOf": [ { "required": ["to"] @@ -1222,10 +1358,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -1353,10 +1506,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target", "text"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -1382,10 +1552,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "name"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -1416,10 +1603,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "title"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -1446,10 +1650,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "ms"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -1475,10 +1696,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "name"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -1550,10 +1788,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "oneOf": [ { "required": ["path"] @@ -1685,10 +1940,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "not": { "required": ["state", "zoom"], "properties": { @@ -1815,10 +2087,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -1951,10 +2240,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "oneOf": [ { "required": ["value"] @@ -2084,10 +2390,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target", "option"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -2206,10 +2529,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -2331,10 +2671,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "key"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "dependentRequired": { "zoom": ["target"] } @@ -2533,10 +2890,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "oneOf": [ { "required": ["to"] @@ -2663,10 +3037,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -2794,10 +3185,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target", "text"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -2823,10 +3231,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "name"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -2857,10 +3282,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "title"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -2887,10 +3329,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "ms"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -2916,10 +3375,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "name"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -2988,10 +3464,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "oneOf": [ { "required": ["path"] @@ -3131,10 +3624,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "not": { "required": ["state", "zoom"], "properties": { @@ -3261,10 +3771,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -3397,10 +3924,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "oneOf": [ { "required": ["value"] @@ -3530,10 +4074,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target", "option"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -3652,10 +4213,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -3785,10 +4363,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "key"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "dependentRequired": { "zoom": ["target"] } @@ -3995,10 +4590,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action"], "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + }, "oneOf": [ { "required": ["to"] @@ -4125,10 +4737,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -4264,10 +4893,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "target", "text"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -4301,10 +4947,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "name"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -4343,10 +5006,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "title"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -4373,10 +5053,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "ms"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } }, { "type": "object", @@ -4410,10 +5107,27 @@ "record": { "description": "false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.", "type": "boolean" + }, + "hold": { + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "type": "integer", + "minimum": 100, + "maximum": 10000 } }, "required": ["action", "name"], - "additionalProperties": false + "additionalProperties": false, + "dependentSchemas": { + "hold": { + "properties": { + "record": { + "not": { + "const": false + } + } + } + } + } } ] } diff --git a/packages/core/src/project-config.ts b/packages/core/src/project-config.ts index e5b3df90..6a6b7d30 100644 --- a/packages/core/src/project-config.ts +++ b/packages/core/src/project-config.ts @@ -202,6 +202,11 @@ export const RenderConfigSchema = z compressToMs: z.number().int().nonnegative().default(400), }) .prefault({}), + // Kept on screen after the last step of a successful run (spec 365). + endHoldMs: z.number().int().min(0).max(10_000).default(2500).meta({ + description: + 'How long a successful video keeps the result on screen after the last step: the engine keeps recording and the renderer keeps the frames. 0 ends the video at the last step.', + }), frame: FrameConfigSchema, background: BackgroundConfigSchema.default({ preset: 'ocean' }), cards: CardsConfigSchema, diff --git a/packages/core/src/step.ts b/packages/core/src/step.ts index b2de845d..2124ccc7 100644 --- a/packages/core/src/step.ts +++ b/packages/core/src/step.ts @@ -43,8 +43,26 @@ const common = { caption: z.string().max(120).optional(), timeoutMs: z.number().int().min(100).max(60_000).default(10_000), record: RecordSchema, + hold: z.number().int().min(100).max(10_000).optional().meta({ + description: + 'Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.', + }), }; +/** Reports a `hold` on an off-camera step: nothing would show it (spec 365). */ +function holdNeedsCamera(value: object, ctx: z.RefinementCtx): void { + if ( + Reflect.get(value, 'hold') !== undefined && + Reflect.get(value, 'record') === false + ) { + ctx.addIssue({ + code: 'custom', + message: 'expected no hold on an off-camera step (record: false)', + path: ['hold'], + }); + } +} + /** * Camera zoom on the step's target (ADR-0012): `true` for the renderer's * default strength, a number for that strength (`1` is no zoom). Only on steps @@ -71,7 +89,17 @@ function step<A extends StepAction, S extends z.ZodRawShape>( action: A, shape: S, ) { - return z.strictObject({ action: z.literal(action), ...shape, ...common }); + return ( + z + .strictObject({ action: z.literal(action), ...shape, ...common }) + .superRefine(holdNeedsCamera) + // Not both `hold` and `record: false`. + .meta({ + dependentSchemas: { + hold: { properties: { record: { not: { const: false } } } }, + }, + }) + ); } /** Key names a `press` may send, as Playwright spells them. Typing text is `fill`. */ diff --git a/packages/core/src/timeline.ts b/packages/core/src/timeline.ts index f18e61f8..5dbff7b8 100644 --- a/packages/core/src/timeline.ts +++ b/packages/core/src/timeline.ts @@ -158,7 +158,10 @@ export const TimelineEventSchema = z origin: StepOriginSchema.optional(), action: StepActionSchema, startMs: msSchema, + // The end of the action; a `hold` follows it (spec 365). endMs: msSchema, + // The step's `hold`, slept after `endMs`: `[endMs, endMs + holdMs]` is on screen. + holdMs: z.number().int().positive().optional(), target: z.strictObject({ box: BoxSchema }).optional(), // The real pointer path (ADR-0004 §2). pointer: z.strictObject({ from: PointSchema, to: PointSchema }).optional(), diff --git a/packages/core/test/project-config.spec.ts b/packages/core/test/project-config.spec.ts index 6b859866..b1517484 100644 --- a/packages/core/test/project-config.spec.ts +++ b/packages/core/test/project-config.spec.ts @@ -16,6 +16,7 @@ describe('parseProjectConfig', () => { height: 1080, fps: 30, idle: { thresholdMs: 1000, compressToMs: 400 }, + endHoldMs: 2500, frame: { enabled: true, marginRatio: 0.06, radius: 12, shadow: true }, background: { preset: 'ocean' }, cards: { @@ -295,6 +296,34 @@ describe('parseProjectConfig', () => { }); }); + it.each([ + 0, 2500, 10_000, + ])('accepts the end hold %d (spec 365)', (endHoldMs) => { + const result = parseProjectConfig({ + baseUrl: 'https://a.example', + render: { endHoldMs }, + }); + expect(result).toMatchObject({ + ok: true, + value: { render: { endHoldMs } }, + }); + }); + + it.each([ + -1, 10_001, 1.5, + ])('rejects the end hold %d (spec 365)', (endHoldMs) => { + const result = parseProjectConfig({ + baseUrl: 'https://a.example', + render: { endHoldMs }, + }); + expect(result.ok).toBe(false); + if (!result.ok) { + expect(result.errors).toContainEqual( + expect.objectContaining({ path: 'render.endHoldMs' }), + ); + } + }); + it.each([ [{ intro: { durationMs: 499 } }, 'render.cards.intro.durationMs'], [{ intro: { durationMs: 10_001 } }, 'render.cards.intro.durationMs'], diff --git a/packages/core/test/scenario.spec.ts b/packages/core/test/scenario.spec.ts index bc45a617..06506451 100644 --- a/packages/core/test/scenario.spec.ts +++ b/packages/core/test/scenario.spec.ts @@ -369,6 +369,30 @@ describe('parseScenario — every action', () => { ); }); + it.each([100, 10_000])('accepts hold %d (spec 365)', (hold) => { + const result = parseScenario(scenario({ action, ...valid, hold })); + expect(result).toMatchObject({ + ok: true, + value: { steps: [expect.objectContaining({ hold })] }, + }); + }); + + it.each([99, 10_001, 500.5])('rejects hold %d at steps[0].hold', (hold) => { + expect(errorsOf(scenario({ action, ...valid, hold }))).toContainEqual( + expect.objectContaining({ path: 'steps[0].hold' }), + ); + }); + + it('rejects hold on an off-camera step (spec 365)', () => { + expect( + errorsOf(scenario({ action, ...valid, hold: 1500, record: false })), + ).toContainEqual({ + path: 'steps[0].hold', + code: 'custom', + message: 'expected no hold on an off-camera step (record: false)', + }); + }); + it('rejects an unknown field at its path', () => { expect( errorsOf(scenario({ action, ...valid, colour: 'red' })), From 097dc7ee76d6b2f4d5b6952a05dec85e3f038a6b Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 13:35:42 +0100 Subject: [PATCH 07/71] feat(api): add the Share table, the share protocol and a file sink in the relay The Share model and its migration hold one shared render per run and format. The runner protocol gains share.prepare, share.prepared and share.error, the poster asset on video.open and the features list on launches.sync. VideoRelay can now pull a whole file into disk through the same streams, credit and timeouts that playback uses. --- .../20261027090000_shares/migration.sql | 46 +++ apps/api/prisma/schema.prisma | 45 +++ .../src/runner/runner-connections.service.ts | 53 ++- apps/api/src/runner/runner-socket.ts | 98 ++++- apps/api/src/videos/video-relay.service.ts | 369 ++++++++++++++---- 5 files changed, 521 insertions(+), 90 deletions(-) create mode 100644 apps/api/prisma/migrations/20261027090000_shares/migration.sql diff --git a/apps/api/prisma/migrations/20261027090000_shares/migration.sql b/apps/api/prisma/migrations/20261027090000_shares/migration.sql new file mode 100644 index 00000000..803ac1af --- /dev/null +++ b/apps/api/prisma/migrations/20261027090000_shares/migration.sql @@ -0,0 +1,46 @@ +-- CreateEnum +CREATE TYPE "ShareStatus" AS ENUM ('uploading', 'ready', 'failed', 'lost'); + +-- CreateTable +CREATE TABLE "Share" ( + "id" TEXT NOT NULL, + "token" TEXT NOT NULL, + "userId" TEXT NOT NULL, + "runId" TEXT NOT NULL, + "format" TEXT NOT NULL, + "status" "ShareStatus" NOT NULL DEFAULT 'uploading', + "title" TEXT NOT NULL, + "description" TEXT, + "chapters" JSONB NOT NULL DEFAULT '[]', + "sizeBytes" INTEGER NOT NULL DEFAULT 0, + "posterBytes" INTEGER NOT NULL DEFAULT 0, + "width" INTEGER, + "height" INTEGER, + "durationMs" INTEGER, + "passwordHash" TEXT, + "expiresAt" TIMESTAMP(3) NOT NULL, + "views" INTEGER NOT NULL DEFAULT 0, + "failure" TEXT, + "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + "updatedAt" TIMESTAMP(3) NOT NULL, + + CONSTRAINT "Share_pkey" PRIMARY KEY ("id") +); + +-- CreateIndex +CREATE UNIQUE INDEX "Share_token_key" ON "Share"("token"); + +-- CreateIndex +CREATE INDEX "Share_userId_createdAt_idx" ON "Share"("userId", "createdAt" DESC); + +-- CreateIndex +CREATE INDEX "Share_expiresAt_idx" ON "Share"("expiresAt"); + +-- CreateIndex +CREATE UNIQUE INDEX "Share_runId_format_key" ON "Share"("runId", "format"); + +-- AddForeignKey +ALTER TABLE "Share" ADD CONSTRAINT "Share_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE; + +-- AddForeignKey +ALTER TABLE "Share" ADD CONSTRAINT "Share_runId_fkey" FOREIGN KEY ("runId") REFERENCES "Run"("id") ON DELETE CASCADE ON UPDATE CASCADE; diff --git a/apps/api/prisma/schema.prisma b/apps/api/prisma/schema.prisma index bfca23f9..9f927e81 100644 --- a/apps/api/prisma/schema.prisma +++ b/apps/api/prisma/schema.prisma @@ -20,6 +20,7 @@ model User { githubIdentity GithubIdentity? runners Runner[] projects Project[] + shares Share[] } // The GitHub account a user signs in with (spec #126). At most one per user, @@ -151,10 +152,54 @@ model Run { failureStage String? failureMessage String? createdAt DateTime @default(now()) + shares Share[] @@index([projectId, startedAt(sort: Desc), id(sort: Desc)]) } +enum ShareStatus { + uploading + ready + failed + lost +} + +// One render of a run behind a public link (spec #347, ADR-0019). The files +// live under `SHARE_DIR/<id>/`, never in the database. One per run and format. +model Share { + id String @id @default(cuid()) + // 32 random bytes, base64url (`generateToken`). Stored as is: the owner + // copies the link again (ADR-0019, Consequences). + token String @unique + userId String + user User @relation(fields: [userId], references: [id], onDelete: Cascade) + runId String + run Run @relation(fields: [runId], references: [id], onDelete: Cascade) + format String + status ShareStatus @default(uploading) + // The scenario's name at share time, and what the daemon sent (#349). + title String + description String? + // `[{ title, atMs }]`, at most 100. + chapters Json @default("[]") + sizeBytes Int @default(0) + posterBytes Int @default(0) + width Int? + height Int? + durationMs Int? + // argon2id (`PasswordHasher`), null without a password. + passwordHash String? + expiresAt DateTime + views Int @default(0) + failure String? + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@unique([runId, format]) + @@index([userId, createdAt(sort: Desc)]) + @@index([expiresAt]) +} + // A pending `demoflow login` (RFC 8628). Only the SHA-256 hash of the polling // secret is stored. `approvedById` is a plain column: the row lives at most // ten minutes and is deleted once its token is issued. diff --git a/apps/api/src/runner/runner-connections.service.ts b/apps/api/src/runner/runner-connections.service.ts index 3d1d587c..387964fc 100644 --- a/apps/api/src/runner/runner-connections.service.ts +++ b/apps/api/src/runner/runner-connections.service.ts @@ -16,6 +16,8 @@ import { CLOSE_REPLACED, CLOSE_REVOKED, type ClientMessage, + FEATURES, + type Feature, HEARTBEAT_TICK_MS, IDLE_TIMEOUT_MS, LAST_SEEN_WRITE_INTERVAL_MS, @@ -25,6 +27,7 @@ import { RUN_OPTIONS, type RunOption, type ServerMessage, + type ShareMessage, type VideoChunk, type VideoMessage, } from './runner-socket'; @@ -49,6 +52,10 @@ interface Connection { warnedStrayLaunch: boolean; /** The known `run.start` options this socket's `launches.sync` announced (spec #325, Decision 4). */ runOptions: RunOption[]; + /** The known features the same frame announced (spec #347, Decision 6). */ + features: Feature[]; + /** A `share.*` answer for no pending request was logged on this socket. */ + warnedStrayShare: boolean; } /** @@ -84,6 +91,16 @@ export interface LaunchSink { closed(runnerId: string): void; } +/** + * Where share uploads (spec #347) hear from the sockets. `message` answers + * false for a request it does not hold. + */ +export interface ShareSink { + message(runnerId: string, message: ShareMessage): boolean; + /** The machine's socket is gone: closed, replaced, revoked or shut down. */ + closed(runnerId: string): void; +} + /** * The open runner sockets of this API instance (one today, #120): online is * "has an entry here", never a column. One socket per machine — a second one @@ -101,6 +118,7 @@ export class RunnerConnections private videoSink: VideoSink | undefined; private artifactsSink: ArtifactsSink | undefined; private launchSink: LaunchSink | undefined; + private shareSink: ShareSink | undefined; constructor( private readonly prisma: PrismaService, @@ -154,6 +172,11 @@ export class RunnerConnections return this.open.get(runnerId)?.runOptions ?? []; } + /** What the machine's current socket can do (spec #347); none offline or before its sync. */ + features(runnerId: string): readonly Feature[] { + return this.open.get(runnerId)?.features ?? []; + } + /** To the machine's current socket; false when it is not online. */ sendTo(runnerId: string, message: ServerMessage): boolean { const connection = this.open.get(runnerId); @@ -179,6 +202,11 @@ export class RunnerConnections this.launchSink = sink; } + /** Share uploads' hook (spec #347). One sink per instance. */ + setShareSink(sink: ShareSink): void { + this.shareSink = sink; + } + /** An authenticated socket, straight after the upgrade. */ async accept( socket: WebSocket, @@ -196,6 +224,8 @@ export class RunnerConnections warnedStrayArtifacts: false, warnedStrayLaunch: false, runOptions: [], + features: [], + warnedStrayShare: false, }; // Listeners first: a frame that arrives during the writes below counts. socket.on('message', (data, isBinary) => @@ -360,12 +390,19 @@ export class RunnerConnections this.relayLaunch(connection, message); return; case 'launches.sync': - // Unknown options are dropped without a log (spec #325). + // Unknown options and features are dropped without a log (specs #325, #347). connection.runOptions = RUN_OPTIONS.filter((option) => message.runOptions?.includes(option), ); + connection.features = FEATURES.filter((feature) => + message.features?.includes(feature), + ); this.relayLaunch(connection, message); return; + case 'share.prepared': + case 'share.error': + this.relayShare(connection, message); + return; } } @@ -382,6 +419,19 @@ export class RunnerConnections } } + /** As `relayArtifacts`, with its own once-per-socket warning. */ + private relayShare(connection: Connection, message: ShareMessage): void { + if (this.shareSink?.message(connection.runnerId, message)) { + return; + } + if (!connection.warnedStrayShare) { + connection.warnedStrayShare = true; + this.logger.warn( + `Dropped ${message.type} from runner ${connection.runnerId} for a request that is not pending`, + ); + } + } + /** * An answer for no pending request — a late one after a timeout, or a * skewed daemon — is dropped, logged once per socket, and the socket stays. @@ -405,6 +455,7 @@ export class RunnerConnections this.videoSink?.closed(runnerId); this.artifactsSink?.closed(runnerId); this.launchSink?.closed(runnerId); + this.shareSink?.closed(runnerId); } private touch(connection: Connection): void { diff --git a/apps/api/src/runner/runner-socket.ts b/apps/api/src/runner/runner-socket.ts index 97406fa3..d5b1fcf6 100644 --- a/apps/api/src/runner/runner-socket.ts +++ b/apps/api/src/runner/runner-socket.ts @@ -75,6 +75,8 @@ export type ServerMessage = runId: string; format: string; range: VideoRange | null; + /** The share's poster instead of the render (spec #347), only to a daemon with `share`. */ + asset?: VideoAsset; } | { type: 'video.ack'; streamId: string; bytes: number } | { type: 'video.cancel'; streamId: string } @@ -88,7 +90,11 @@ export type ServerMessage = /** Only when the browser chose formats (spec #325): the default frame is unchanged. */ options?: RunStartOptions; } - | { type: 'run.cancel'; requestId: string }; + | { type: 'run.cancel'; requestId: string } + | { type: 'share.prepare'; requestId: string; runId: string; format: string }; + +/** What `video.open` may ask for besides the render itself (spec #347). */ +export type VideoAsset = 'poster'; /** What a website-started run may choose (ADR-0017): the output formats, nothing else. */ export interface RunStartOptions { @@ -102,7 +108,8 @@ export type ClientMessage = | ByeMessage | VideoMessage | ArtifactsMessage - | LaunchMessage; + | LaunchMessage + | ShareMessage; export type VideoMessage = | VideoHeadMessage @@ -129,6 +136,15 @@ export type LaunchMessage = | RunProgressMessage | LaunchesSyncMessage; +/** A Runner's answer to `share.prepare` (spec #347, Decision 4). */ +export type ShareMessage = SharePreparedMessage | ShareErrorMessage; + +/** `share.prepared` limits (Decision 4). */ +export const SHARE_DESCRIPTION_MAX = 2000; +export const SHARE_CHAPTERS_MAX = 100; +export const SHARE_CHAPTER_TITLE_MAX = 200; +export const SHARE_POSTER_MAX_BYTES = 1024 * 1024; + /** `scenarios.listed` carries this many entries at most. */ export const MAX_LISTED_SCENARIOS = 100; /** `launches.sync` carries this many launch ids at most. */ @@ -151,6 +167,15 @@ export type RunOption = (typeof RUN_OPTIONS)[number]; /** `launches.sync` announces this many options at most, each this long at most. */ export const MAX_RUN_OPTIONS = 8; export const RUN_OPTION_MAX_LENGTH = 32; +/** + * The capabilities this API knows a daemon may announce (ADR-0019 §7): `share` + * answers `share.prepare` and `video.open` with an `asset`. + */ +export const FEATURES = ['share'] as const; +export type Feature = (typeof FEATURES)[number]; +/** `launches.sync` announces this many features at most, each this long at most. */ +export const MAX_FEATURES = 8; +export const FEATURE_MAX_LENGTH = 32; class PingMessage { @IsIn(['ping']) @@ -379,9 +404,9 @@ class RunProgressMessage { /** * The daemon's first frame on every socket (spec #284, Decision 1): the - * launch ids whose child it still has, possibly none, and the `run.start` - * options it accepts (spec #325). Unknown options pass here and are dropped - * when the frame is routed. + * launch ids whose child it still has, possibly none, the `run.start` + * options it accepts (spec #325) and its features (spec #347). Unknown + * options and features pass here and are dropped when the frame is routed. */ class LaunchesSyncMessage { @IsIn(['launches.sync']) @@ -399,6 +424,67 @@ class LaunchesSyncMessage { @IsString({ each: true }) @MaxLength(RUN_OPTION_MAX_LENGTH, { each: true }) runOptions?: string[]; + + /** Absent from a daemon before #349: it can do none. Unknown ones are dropped. */ + @IsOptional() + @IsArray() + @ArrayMaxSize(MAX_FEATURES) + @IsString({ each: true }) + @MaxLength(FEATURE_MAX_LENGTH, { each: true }) + features?: string[]; +} + +class ShareChapter { + @IsString() + @Length(1, SHARE_CHAPTER_TITLE_MAX) + title!: string; + + @IsInt() + @Min(0) + @Max(Number.MAX_SAFE_INTEGER) + atMs!: number; +} + +/** The daemon has the render and its poster; the bytes follow over `video.open`. */ +class SharePreparedMessage { + @IsIn(['share.prepared']) + type!: 'share.prepared'; + + @IsUUID('4') + requestId!: string; + + /** The scenario's description, read from its file at share time (ADR-0019 §2). */ + @IsOptional() + @IsString() + @MaxLength(SHARE_DESCRIPTION_MAX) + description?: string; + + @IsArray() + @ArrayMaxSize(SHARE_CHAPTERS_MAX) + @ValidateNested({ each: true }) + @Type(() => ShareChapter) + chapters!: ShareChapter[]; + + @IsInt() + @Min(1) + @Max(SHARE_POSTER_MAX_BYTES) + posterSize!: number; +} + +/** + * `not-found`, `no-render` or `io`. Any string, so a code a newer daemon adds + * still ends the request instead of being dropped. + */ +class ShareErrorMessage { + @IsIn(['share.error']) + type!: 'share.error'; + + @IsUUID('4') + requestId!: string; + + @IsString() + @MaxLength(64) + code!: string; } const CLIENT_MESSAGES: Record< @@ -421,6 +507,8 @@ const CLIENT_MESSAGES: Record< 'run.finished': RunFinishedMessage, 'run.progress': RunProgressMessage, 'launches.sync': LaunchesSyncMessage, + 'share.prepared': SharePreparedMessage, + 'share.error': ShareErrorMessage, }; /** A binary frame: part of a stream's file, in order. */ diff --git a/apps/api/src/videos/video-relay.service.ts b/apps/api/src/videos/video-relay.service.ts index 5bbcaf7a..31b59020 100644 --- a/apps/api/src/videos/video-relay.service.ts +++ b/apps/api/src/videos/video-relay.service.ts @@ -1,4 +1,6 @@ import { randomUUID } from 'node:crypto'; +import { createWriteStream, type WriteStream } from 'node:fs'; +import { rename, rm } from 'node:fs/promises'; import { Injectable, Logger, @@ -14,6 +16,7 @@ import { type VideoSink, } from '../runner/runner-connections.service'; import type { + VideoAsset, VideoChunk, VideoMessage, VideoRange, @@ -52,23 +55,200 @@ const RUNNER_ERRORS: Record<string, { status: number; error: string }> = { }; const UNKNOWN_RUNNER_ERROR = { status: 502, error: 'runner-error' }; +interface Head { + size: number; + start: number; + end: number; +} + +/** + * Where one stream's bytes go: a playback response, or a share's file (spec + * #347, Decision 4). The relay owns the protocol — spans, timeouts, credit — + * and a sink only takes what passed it. + */ +interface StreamSink { + /** Logged with the stream's outcome. */ + readonly kind: 'play' | 'download' | 'upload'; + /** The head passed the span check. An error code refuses it. */ + head(head: Head, expected: number): string | null; + /** In order. `taken` once the sink holds the bytes: they are acknowledged then. */ + write(bytes: Buffer, taken: () => void): void; + /** Every byte the head announced came. */ + end(): void; + /** Failed: `status` and `headers` count only for a response not yet started. */ + fail(status: number, error: string, headers?: Record<string, string>): void; +} + +/** The HTTP response of `GET /runs/:id/video/:format` (spec #191). */ +class ResponseSink implements StreamSink { + readonly kind: 'play' | 'download'; + /** Chunks the response has not taken yet, acknowledged on `drain`. */ + private unacked: Array<() => void> = []; + + constructor( + private readonly res: Response, + private readonly format: RunFormat, + private readonly range: VideoRange | null, + /** Set for `?download=1`: the head says `attachment` (spec #299). */ + private readonly download: { fileName: string } | undefined, + ) { + this.kind = download ? 'download' : 'play'; + } + + head(head: Head, expected: number): null { + const partial = this.range !== null; + this.res.writeHead(partial ? 206 : 200, { + ...COMMON_HEADERS, + 'Content-Type': VIDEO_CONTENT_TYPES[this.format], + 'Content-Length': String(expected), + 'Content-Disposition': this.download + ? `attachment; filename="${this.download.fileName}"` + : 'inline', + ...(partial + ? { 'Content-Range': `bytes ${head.start}-${head.end}/${head.size}` } + : {}), + }); + return null; + } + + write(bytes: Buffer, taken: () => void): void { + const took = this.res.write(bytes); + if (took && this.unacked.length === 0) { + taken(); + return; + } + this.unacked.push(taken); + if (this.unacked.length === 1) { + this.res.once('drain', () => { + for (const ack of this.unacked.splice(0)) { + ack(); + } + }); + } + } + + end(): void { + this.res.end(); + } + + /** `{ error }` before the head; after it, the status is sent: destroy. */ + fail( + status: number, + error: string, + headers: Record<string, string> = {}, + ): void { + if (this.res.headersSent) { + this.res.destroy(); + return; + } + this.res + .status(status) + .set({ ...COMMON_HEADERS, ...headers }) + .json({ error }); + } +} + +/** What an upload into a file settles with: the file's size, or an error code. */ +export type UploadOutcome = + | { ok: true; size: number } + | { ok: false; error: string }; + +export interface UploadVideo { + runnerId: string; + runId: string; + format: RunFormat; + /** The share's poster instead of the render. */ + asset?: VideoAsset; + /** Where the file lands. Bytes go to `<path>.part` until the last one came. */ + path: string; + /** Checks the head's size before a byte is written; an error code refuses it. */ + accept: (size: number) => string | null; +} + +/** + * A share's file (spec #347, Decision 2): written to `<path>.part`, renamed + * once every announced byte is on disk, deleted on anything else. + */ +class FileSink implements StreamSink { + readonly kind = 'upload'; + private file: WriteStream | undefined; + private failed = false; + + constructor( + private readonly path: string, + private readonly accept: (size: number) => string | null, + /** The disk failed under the stream: the relay cancels it. */ + private readonly broken: () => void, + private readonly settle: (outcome: UploadOutcome) => void, + ) {} + + private get part(): string { + return `${this.path}.part`; + } + + head({ size }: Head): string | null { + const refused = this.accept(size); + if (refused !== null) { + return refused; + } + this.file = createWriteStream(this.part); + this.file.once('error', () => this.broken()); + return null; + } + + write(bytes: Buffer, taken: () => void): void { + this.file?.write(bytes, (error) => { + if (!error) { + taken(); + } + }); + } + + end(): void { + const file = this.file; + if (!file) { + return; + } + // `close`, not `finish`: the descriptor is released before the rename. + file.once('close', () => { + if (this.failed) { + return; + } + rename(this.part, this.path).then( + () => this.settle({ ok: true, size: file.bytesWritten }), + () => this.discard('io'), + ); + }); + file.end(); + } + + fail(_status: number, error: string): void { + this.failed = true; + this.file?.destroy(); + this.discard(error); + } + + private discard(error: string): void { + rm(this.part, { force: true }).then( + () => this.settle({ ok: false, error }), + () => this.settle({ ok: false, error }), + ); + } +} + interface Stream { id: string; runnerId: string; runId: string; format: RunFormat; range: VideoRange | null; - /** Set for `?download=1`: the head says `attachment` (spec #299). */ - download: { fileName: string } | undefined; - res: Response; + sink: StreamSink; /** Clock ms. */ openedAt: number; lastChunkAt: number; /** `end - start + 1` of the head; null until it came. */ expected: number | null; relayed: number; - /** Sizes of chunks the response has not taken yet, acknowledged on `drain`. */ - unacked: number[]; } export interface OpenVideo { @@ -84,7 +264,7 @@ export interface OpenVideo { * Plays a run's video from the machine that recorded it (spec #191, ADR-0009 * §1): asks the Runner over its socket for the bytes and relays them into the * HTTP response, acknowledging each chunk once the response has taken it. - * Nothing is stored here. + * A share's upload (spec #347) pulls the same way into a file instead. * * Works only on the instance that holds the Runner's socket. Staging runs one * API instance; more would need sticky routing or a broker (Decision 10). @@ -115,7 +295,7 @@ export class VideoRelay clearInterval(this.timer); } - /** Streams open to the machine right now. */ + /** Streams open to the machine right now, uploads included. */ openTo(runnerId: string): number { let count = 0; for (const stream of this.streams.values()) { @@ -128,22 +308,13 @@ export class VideoRelay /** Sends `video.open`; the response is answered from here on. */ open({ runnerId, runId, format, range, download, res }: OpenVideo): void { - const now = this.clock.now().getTime(); - const stream: Stream = { - id: randomUUID(), + const stream = this.start( runnerId, runId, format, range, - download, - res, - openedAt: now, - lastChunkAt: now, - expected: null, - relayed: 0, - unacked: [], - }; - this.streams.set(stream.id, stream); + new ResponseSink(res, format, range, download), + ); // Seeked or left: the Runner stops reading (Decision 6). res.on('close', () => { if (this.streams.get(stream.id) === stream) { @@ -151,16 +322,37 @@ export class VideoRelay this.finish(stream, 'aborted'); } }); - const sent = this.connections.sendTo(runnerId, { - type: 'video.open', - streamId: stream.id, - runId, - format, - range, + this.send(stream, undefined); + } + + /** + * Pulls the whole file into `path` (spec #347, Decision 4), with the + * playback's timeouts and credit. Settles once the file is in place or gone. + */ + upload({ + runnerId, + runId, + format, + asset, + path, + accept, + }: UploadVideo): Promise<UploadOutcome> { + return new Promise((settle) => { + let stream: Stream | undefined; + const sink = new FileSink( + path, + accept, + () => { + if (stream && this.streams.get(stream.id) === stream) { + this.cancel(stream); + this.fail(stream, 500, 'io'); + } + }, + settle, + ); + stream = this.start(runnerId, runId, format, null, sink); + this.send(stream, asset); }); - if (!sent) { - this.fail(stream, 503, 'runner-offline'); - } } message(runnerId: string, message: VideoMessage): void { @@ -194,20 +386,16 @@ export class VideoRelay // Bytes beyond the head's span must never pass as the file (Decision 7). if (stream.relayed + bytes.length > stream.expected) { this.cancel(stream); - this.destroy(stream, 'overrun'); + this.fail(stream, 502, 'overrun'); return true; } stream.relayed += bytes.length; stream.lastChunkAt = this.clock.now().getTime(); - const taken = stream.res.write(bytes); - if (taken && stream.unacked.length === 0) { - this.ack(stream, bytes.length); - return true; - } - stream.unacked.push(bytes.length); - if (stream.unacked.length === 1) { - stream.res.once('drain', () => this.drained(stream)); - } + stream.sink.write(bytes, () => { + if (this.streams.get(stream.id) === stream) { + this.ack(stream, bytes.length); + } + }); return true; } @@ -231,15 +419,51 @@ export class VideoRelay } } else if (now - stream.lastChunkAt >= CHUNK_TIMEOUT_MS) { this.cancel(stream); - this.destroy(stream, 'stalled'); + this.fail(stream, 504, 'stalled'); } } } - private head( - stream: Stream, - head: { size: number; start: number; end: number }, - ): void { + private start( + runnerId: string, + runId: string, + format: RunFormat, + range: VideoRange | null, + sink: StreamSink, + ): Stream { + const now = this.clock.now().getTime(); + const stream: Stream = { + id: randomUUID(), + runnerId, + runId, + format, + range, + sink, + openedAt: now, + lastChunkAt: now, + expected: null, + relayed: 0, + }; + this.streams.set(stream.id, stream); + return stream; + } + + /** `asset` only for an upload: a daemon without `share` never sees the field. */ + private send(stream: Stream, asset: VideoAsset | undefined): void { + const sent = this.connections.sendTo(stream.runnerId, { + type: 'video.open', + streamId: stream.id, + runId: stream.runId, + format: stream.format, + range: stream.range, + ...(asset ? { asset } : {}), + }); + if (!sent) { + this.fail(stream, 503, 'runner-offline'); + } + } + + private head(stream: Stream, head: Head): void { // A second head, or one that is not the span asked for, is a broken daemon. const span = spanOf(stream.range, head.size); if ( @@ -252,20 +476,15 @@ export class VideoRelay this.fail(stream, 502, 'runner-error'); return; } - stream.expected = head.end - head.start + 1; + const expected = head.end - head.start + 1; + const refused = stream.sink.head(head, expected); + if (refused !== null) { + this.cancel(stream); + this.fail(stream, 502, refused); + return; + } + stream.expected = expected; stream.lastChunkAt = this.clock.now().getTime(); - const partial = stream.range !== null; - stream.res.writeHead(partial ? 206 : 200, { - ...COMMON_HEADERS, - 'Content-Type': VIDEO_CONTENT_TYPES[stream.format], - 'Content-Length': String(stream.expected), - 'Content-Disposition': stream.download - ? `attachment; filename="${stream.download.fileName}"` - : 'inline', - ...(partial - ? { 'Content-Range': `bytes ${head.start}-${head.end}/${head.size}` } - : {}), - }); } private end(stream: Stream): void { @@ -274,11 +493,11 @@ export class VideoRelay return; } if (stream.relayed !== stream.expected) { - this.destroy(stream, 'short'); + this.fail(stream, 502, 'short'); return; } this.finish(stream, 'complete'); - stream.res.end(); + stream.sink.end(); } private runnerError( @@ -287,7 +506,7 @@ export class VideoRelay size: number | undefined, ): void { if (stream.expected !== null) { - this.destroy(stream, `runner ${code}`.slice(0, 80)); + this.fail(stream, 502, `runner ${code}`.slice(0, 80)); return; } if (code === 'bad-range' && size !== undefined) { @@ -300,15 +519,6 @@ export class VideoRelay this.fail(stream, status, error); } - private drained(stream: Stream): void { - if (this.streams.get(stream.id) !== stream) { - return; - } - for (const bytes of stream.unacked.splice(0)) { - this.ack(stream, bytes); - } - } - private ack(stream: Stream, bytes: number): void { this.connections.sendTo(stream.runnerId, { type: 'video.ack', @@ -324,28 +534,18 @@ export class VideoRelay }); } - /** Answers `{ error }` before the head; after it, the status is sent: destroy. */ + /** + * Ends the stream with `error`. A short or broken body must never pass as a + * complete one (Decision 7): a started response is destroyed, a file deleted. + */ private fail( stream: Stream, status: number, error: string, headers: Record<string, string> = {}, ): void { - if (stream.res.headersSent) { - this.destroy(stream, error); - return; - } this.finish(stream, error); - stream.res - .status(status) - .set({ ...COMMON_HEADERS, ...headers }) - .json({ error }); - } - - /** A short or broken body must never pass as a complete one (Decision 7). */ - private destroy(stream: Stream, outcome: string): void { - this.finish(stream, outcome); - stream.res.destroy(); + stream.sink.fail(status, error, headers); } private finish(stream: Stream, outcome: string): void { @@ -356,7 +556,8 @@ export class VideoRelay event: 'video.stream', runId: stream.runId, format: stream.format, - download: stream.download !== undefined, + download: stream.sink.kind === 'download', + upload: stream.sink.kind === 'upload', bytes: stream.relayed, outcome, durationMs: this.clock.now().getTime() - stream.openedAt, From db014748c31c699d6c85fc26b2c4e88311f08c23 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 13:39:13 +0100 Subject: [PATCH 08/71] feat(engine): record a step's hold and the end hold of a successful run A step with hold keeps the page on camera that long after its action, stamps holdMs on its event and keeps endMs at the action's end. After the last step of a run that passed, RunOptions.endHoldMs (default 0) is slept before the recording closes; demoflow run passes render.endHoldMs. A failed step holds nothing, and a page that leaves during a hold fails the step it held (spec 365). --- apps/cli/src/commands/run.ts | 1 + packages/engine/src/run.ts | 49 ++++++++- packages/engine/test/execute/hold.spec.ts | 126 ++++++++++++++++++++++ 3 files changed, 174 insertions(+), 2 deletions(-) create mode 100644 packages/engine/test/execute/hold.spec.ts diff --git a/apps/cli/src/commands/run.ts b/apps/cli/src/commands/run.ts index 921b48cf..6835cb36 100644 --- a/apps/cli/src/commands/run.ts +++ b/apps/cli/src/commands/run.ts @@ -196,6 +196,7 @@ export async function runCommand( allowedOrigins: config.allowedOrigins, env: host.env, headless: flags.headed !== true, + endHoldMs: config.render.endHoldMs, observers: [ createCaptureObserver({ scenarioId: scenarioId(root, file), runId }), ...(progress ? [progressObserver(io)] : []), diff --git a/packages/engine/src/run.ts b/packages/engine/src/run.ts index 68a0b748..e2cd90a1 100644 --- a/packages/engine/src/run.ts +++ b/packages/engine/src/run.ts @@ -1,4 +1,5 @@ import { mkdir } from 'node:fs/promises'; +import { setTimeout as sleep } from 'node:timers/promises'; import { type Annotation, deriveRunStatus, @@ -54,6 +55,11 @@ export interface RunOptions { /** Defaults to `true`. */ headless?: boolean; observers?: readonly EngineObserver[]; + /** + * Milliseconds the recording goes on after the last step of a successful + * run (`render.endHoldMs`, spec 365). Defaults to 0: the video ends there. + */ + endHoldMs?: number; } const ASSERTIONS = new Set(['assertVisible', 'assertText']); @@ -130,7 +136,7 @@ export async function runScenario( } const execute = ( session: Session, - range: { from: number; to: number }, + range: { from: number; to: number; endHoldMs?: number }, events: TimelineEvent[], ): Promise<Failure | undefined> => executeSteps({ @@ -150,6 +156,7 @@ export async function runScenario( annotations: session.annotations, scrub, emit, + endHoldMs: range.endHoldMs ?? 0, }); // The opening off-camera steps run in a context of their own with no @@ -203,7 +210,7 @@ export async function runScenario( const events: TimelineEvent[] = []; failure ??= await execute( session, - { from: hidden, to: steps.length }, + { from: hidden, to: steps.length, endHoldMs: options.endHoldMs }, events, ); // Before the context closes: a document's clock exchange may still be running on it. @@ -343,6 +350,8 @@ interface ExecuteInput { hook: K, event: Parameters<NonNullable<EngineObserver[K]>>[0], ) => Promise<void>; + /** Slept after the last step when every step passed. */ + endHoldMs: number; } interface Failure { @@ -355,6 +364,15 @@ interface Failure { /** Runs the steps in order and returns the first failure, if any. */ async function executeSteps(input: ExecuteInput): Promise<Failure | undefined> { const { clock, emit, scrub } = input; + // Keeps the page on camera; a field that shows up meanwhile is masked from + // then, and a page that leaves meanwhile is the step's failure (spec 365). + const hold = async (ms: number): Promise<string | undefined> => { + const fromMs = clock.now(); + await sleep(ms); + const sightings = await input.masks.look(); + input.masks.record(sightings, fromMs, Math.max(fromMs, clock.now())); + return input.navigation.take(); + }; let pointer = input.pointer; for (let stepIndex = input.from; stepIndex < input.to; stepIndex++) { const step = input.steps[stepIndex]; @@ -425,6 +443,19 @@ async function executeSteps(input: ExecuteInput): Promise<Failure | undefined> { if (step.action === 'fill') { await input.masks.track(event, step.target); } + // A failed step does not hold; an off-camera one has nothing to show. + if ( + failure === undefined && + step.hold !== undefined && + step.record !== false + ) { + event.holdMs = step.hold; + const left = await hold(step.hold); + if (left !== undefined) { + failure = new StepFailure('execution', originNotAllowed(left)); + event.error = { message: scrub(failure.message) }; + } + } input.events.push(event); await emit('onStepFinished', { stepIndex, step, event }); @@ -437,6 +468,20 @@ async function executeSteps(input: ExecuteInput): Promise<Failure | undefined> { }; } } + const last = input.events.at(-1); + if (input.endHoldMs > 0 && last !== undefined) { + const left = await hold(input.endHoldMs); + if (left !== undefined) { + const message = scrub(originNotAllowed(left)); + last.error = { message }; + return { + stage: 'execution', + message, + stepIndex: last.stepIndex, + origin: last.origin, + }; + } + } return undefined; } diff --git a/packages/engine/test/execute/hold.spec.ts b/packages/engine/test/execute/hold.spec.ts new file mode 100644 index 00000000..60960620 --- /dev/null +++ b/packages/engine/test/execute/hold.spec.ts @@ -0,0 +1,126 @@ +import { mkdtemp, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import { afterAll, beforeAll, describe, expect, it } from 'vitest'; +import { type RunOptions, runScenario } from '../../src/index.ts'; +import { type FixtureServer, startFixtureServer } from './fixture-server.ts'; +import { scenario } from './scenario.ts'; + +let fixture: FixtureServer; +const runDirs: string[] = []; + +beforeAll(async () => { + fixture = await startFixtureServer(); +}); + +afterAll(async () => { + await fixture.close(); + await Promise.all( + runDirs.map((dir) => rm(dir, { recursive: true, force: true })), + ); +}); + +async function options(extra: Partial<RunOptions> = {}): Promise<RunOptions> { + const runDir = await mkdtemp(path.join(tmpdir(), 'demoflow-engine-')); + runDirs.push(runDir); + return { + runDir, + baseUrl: fixture.origin, + allowedOrigins: [fixture.origin], + env: {}, + ...extra, + }; +} + +describe('hold (spec 365)', () => { + it('keeps the page on camera after a step, and after the last one', async () => { + let lastFinishedAt = 0; + let runFinishedAt = 0; + const outcome = await runScenario( + scenario([ + { action: 'navigate', path: '/customers', hold: 1500 }, + { action: 'waitFor', target: { role: 'heading', name: 'Customers' } }, + ]), + await options({ + endHoldMs: 2000, + observers: [ + { + onStepFinished: ({ stepIndex }) => { + if (stepIndex === 1) lastFinishedAt = performance.now(); + }, + onRunFinished: () => { + runFinishedAt = performance.now(); + }, + }, + ], + }), + ); + expect(outcome.stages.execution.status).toBe('passed'); + const [first, second] = outcome.events; + expect(first.holdMs).toBe(1500); + // endMs is where the action ended, not the hold. + expect(first.endMs - first.startMs).toBeLessThan(1500); + expect(second.startMs - first.endMs).toBeGreaterThanOrEqual(1500); + expect(second.holdMs).toBeUndefined(); + // The recording stops after the end hold, never before. + expect(runFinishedAt - lastFinishedAt).toBeGreaterThanOrEqual(2000); + }); + + it('holds nothing after a failed step', async () => { + let failedAt = 0; + let runFinishedAt = 0; + const outcome = await runScenario( + scenario([ + { action: 'navigate', path: '/' }, + { + action: 'click', + target: { testId: 'missing' }, + timeoutMs: 500, + hold: 3000, + }, + ]), + await options({ + endHoldMs: 5000, + observers: [ + { + onStepFinished: ({ stepIndex }) => { + if (stepIndex === 1) failedAt = performance.now(); + }, + onRunFinished: () => { + runFinishedAt = performance.now(); + }, + }, + ], + }), + ); + expect(outcome.stages.execution).toMatchObject({ + status: 'failed', + error: { stepIndex: 1 }, + }); + expect(outcome.events[1].holdMs).toBeUndefined(); + // Closing the context and saving the video takes a moment; no hold does. + expect(runFinishedAt - failedAt).toBeLessThan(2000); + }); + + it('sleeps no end hold by default', async () => { + let lastFinishedAt = 0; + let runFinishedAt = 0; + const outcome = await runScenario( + scenario([{ action: 'navigate', path: '/' }]), + await options({ + observers: [ + { + onStepFinished: () => { + lastFinishedAt = performance.now(); + }, + onRunFinished: () => { + runFinishedAt = performance.now(); + }, + }, + ], + }), + ); + expect(outcome.stages.execution.status).toBe('passed'); + expect(runFinishedAt - lastFinishedAt).toBeLessThan(2000); + }); +}); From d85763a11d3a71b4e573f0b9b5470e7bd8641dd5 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 13:45:42 +0100 Subject: [PATCH 09/71] chore(cli): bump demoflow to 0.7.1 --- apps/cli/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/cli/package.json b/apps/cli/package.json index f72a9006..a6ecd25b 100644 --- a/apps/cli/package.json +++ b/apps/cli/package.json @@ -1,6 +1,6 @@ { "name": "@demoflow/cli", - "version": "0.7.0", + "version": "0.7.1", "private": true, "description": "Turn a scenario into a demo video: a browser runs it, FFmpeg renders it. CLI and MCP server.", "keywords": [ From be2cfa76ed7a3a5eb185bb97a0f879382d4ae9fa Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 13:48:08 +0100 Subject: [PATCH 10/71] feat(engine): run a scenario without recording it (record: false) --- packages/engine/src/run.ts | 44 +++++--- packages/engine/test/execute/check.spec.ts | 114 +++++++++++++++++++++ 2 files changed, 143 insertions(+), 15 deletions(-) create mode 100644 packages/engine/test/execute/check.spec.ts diff --git a/packages/engine/src/run.ts b/packages/engine/src/run.ts index 68a0b748..a5ffecdd 100644 --- a/packages/engine/src/run.ts +++ b/packages/engine/src/run.ts @@ -53,6 +53,12 @@ export interface RunOptions { env?: Readonly<Record<string, string | undefined>>; /** Defaults to `true`. */ headless?: boolean; + /** + * Defaults to `true`. With `false` (a check run, ADR-0021 §1) the steps run + * in a context with no video, no sync mark is recorded and the `recording` + * stage is `skipped`. + */ + record?: boolean; observers?: readonly EngineObserver[]; } @@ -80,6 +86,7 @@ export async function runScenario( }; const startedAt = timestamp(); + const record = options.record ?? true; const stages = pendingStages(); const recording = recordingOptions(scenario, options.runDir); const baseUrl = scenario.baseUrl ?? options.baseUrl; @@ -184,10 +191,12 @@ export async function runScenario( } } - stages.recording = { status: 'running', startedAt: timestamp() }; + stages.recording = record + ? { status: 'running', startedAt: timestamp() } + : { status: 'skipped' }; const session = await openSession(browser, scenario, guard, { options: { - ...toContextOptions(recording, browser.version()), + ...toContextOptions(recording, browser.version(), { video: record }), ...(start === undefined ? {} : { storageState: start.storageState }), }, }); @@ -198,7 +207,8 @@ export async function runScenario( if (start !== undefined && /^https?:/.test(start.url)) { failure = await reopen(page, start.url, hidden - 1, steps, scrub); } - const syncMark = await recordSyncMark(page, clock); + // The sync mark is read from the video; a check records none. + const syncMark = record ? await recordSyncMark(page, clock) : undefined; const events: TimelineEvent[] = []; failure ??= await execute( @@ -220,19 +230,23 @@ export async function runScenario( // Closing the context finalises the video, also after a failed step. await context.close(); - const video = page.video(); + const video = record ? page.video() : null; let videoPath: string | undefined; - try { - videoPath = video === null ? undefined : await video.path(); - stages.recording = finish( - stages.recording, - videoPath === undefined ? 'failed' : 'passed', - videoPath === undefined ? { message: 'no video recorded' } : undefined, - ); - } catch (error) { - stages.recording = finish(stages.recording, 'failed', { - message: errorMessage(error), - }); + if (record) { + try { + videoPath = video === null ? undefined : await video.path(); + stages.recording = finish( + stages.recording, + videoPath === undefined ? 'failed' : 'passed', + videoPath === undefined + ? { message: 'no video recorded' } + : undefined, + ); + } catch (error) { + stages.recording = finish(stages.recording, 'failed', { + message: errorMessage(error), + }); + } } const outcome = conclude(startedAt, stages, events, { diff --git a/packages/engine/test/execute/check.spec.ts b/packages/engine/test/execute/check.spec.ts new file mode 100644 index 00000000..354ff703 --- /dev/null +++ b/packages/engine/test/execute/check.spec.ts @@ -0,0 +1,114 @@ +import { mkdtemp, readdir, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import { afterAll, beforeAll, describe, expect, it } from 'vitest'; +import { type RunOptions, runScenario } from '../../src/index.ts'; +import { + type FixtureServer, + SIGN_IN_PATH, + startFixtureServer, +} from './fixture-server.ts'; +import { scenario } from './scenario.ts'; + +let fixture: FixtureServer; +const runDirs: string[] = []; + +beforeAll(async () => { + fixture = await startFixtureServer(); +}); + +afterAll(async () => { + await fixture.close(); + await Promise.all( + runDirs.map((dir) => rm(dir, { recursive: true, force: true })), + ); +}); + +async function options(extra: Partial<RunOptions> = {}): Promise<RunOptions> { + const runDir = await mkdtemp(path.join(tmpdir(), 'demoflow-engine-')); + runDirs.push(runDir); + return { + runDir, + baseUrl: fixture.origin, + allowedOrigins: [fixture.origin], + env: {}, + record: false, + ...extra, + }; +} + +/** Every file under the run directory, relative to it. */ +async function files(runDir: string): Promise<string[]> { + const entries = await readdir(runDir, { + recursive: true, + withFileTypes: true, + }); + return entries.filter((entry) => entry.isFile()).map((entry) => entry.name); +} + +describe('check runs (record: false)', () => { + it('runs and verifies every step and records nothing', async () => { + const run = await options(); + const outcome = await runScenario( + scenario([ + { action: 'navigate', path: '/customers' }, + { action: 'waitFor', target: { role: 'heading', name: 'Customers' } }, + { + action: 'assertText', + target: { role: 'heading', name: 'Customers' }, + text: 'Customers', + }, + ]), + run, + ); + expect(outcome.stages.execution.status).toBe('passed'); + expect(outcome.stages.verification.status).toBe('passed'); + expect(outcome.stages.recording).toEqual({ status: 'skipped' }); + expect(outcome.events.map((event) => event.stepIndex)).toEqual([0, 1, 2]); + expect(outcome.videoPath).toBeUndefined(); + expect(outcome.syncMark).toBeUndefined(); + expect(await files(run.runDir)).toEqual([]); + }); + + it('fails verification on an assertion that does not hold', async () => { + const outcome = await runScenario( + scenario([ + { action: 'navigate', path: '/customers' }, + { action: 'waitFor', target: { role: 'heading', name: 'Customers' } }, + { + action: 'assertText', + target: { role: 'heading', name: 'Customers' }, + text: 'Invoices', + timeoutMs: 500, + }, + ]), + await options(), + ); + expect(outcome.stages.verification).toMatchObject({ + status: 'failed', + error: { stepIndex: 2 }, + }); + expect(outcome.stages.recording).toEqual({ status: 'skipped' }); + expect(outcome.status).toBe('failed'); + expect(outcome.videoPath).toBeUndefined(); + }); + + it('runs the off-camera steps before the checked ones', async () => { + const outcome = await runScenario( + scenario( + [{ action: 'fill', target: { label: 'Password' }, value: 'visible' }], + { + setup: [ + { action: 'navigate', path: SIGN_IN_PATH }, + { action: 'navigate', path: '/login' }, + ], + }, + ), + await options(), + ); + expect(outcome.stages.execution.status).toBe('passed'); + expect(outcome.stages.recording).toEqual({ status: 'skipped' }); + expect(outcome.events.map((event) => event.stepIndex)).toEqual([2]); + expect(outcome.videoPath).toBeUndefined(); + }); +}); From 61db429acaa7c68162a1aedf2b957c3f0cbef4be Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 13:51:26 +0100 Subject: [PATCH 11/71] feat(api): store whether a reported run was a check (Run.kind) --- .../20261026120000_run_kind/migration.sql | 5 +++ apps/api/prisma/schema.prisma | 6 +++ apps/api/src/projects/projects.dto.ts | 8 ++++ .../src/projects/projects.integration.spec.ts | 38 +++++++++++++++++++ apps/api/src/projects/projects.service.ts | 4 ++ .../videos/run-details.integration.spec.ts | 1 + .../api/src/videos/videos.integration.spec.ts | 1 + 7 files changed, 63 insertions(+) create mode 100644 apps/api/prisma/migrations/20261026120000_run_kind/migration.sql diff --git a/apps/api/prisma/migrations/20261026120000_run_kind/migration.sql b/apps/api/prisma/migrations/20261026120000_run_kind/migration.sql new file mode 100644 index 00000000..14366199 --- /dev/null +++ b/apps/api/prisma/migrations/20261026120000_run_kind/migration.sql @@ -0,0 +1,5 @@ +-- CreateEnum +CREATE TYPE "RunKind" AS ENUM ('check'); + +-- AlterTable +ALTER TABLE "Run" ADD COLUMN "kind" "RunKind"; diff --git a/apps/api/prisma/schema.prisma b/apps/api/prisma/schema.prisma index bfca23f9..b6f7c91a 100644 --- a/apps/api/prisma/schema.prisma +++ b/apps/api/prisma/schema.prisma @@ -123,6 +123,10 @@ enum RunStatus { failed } +enum RunKind { + check +} + // The metadata of one `demoflow run`. Never a video, a frame or a step value: // values can hold secrets, and videos stay on the machine (ADR-0008). model Run { @@ -150,6 +154,8 @@ model Run { renders Json? failureStage String? failureMessage String? + // Spec 360: `check` for a run made with `demoflow run --check`; null otherwise. + kind RunKind? createdAt DateTime @default(now()) @@index([projectId, startedAt(sort: Desc), id(sort: Desc)]) diff --git a/apps/api/src/projects/projects.dto.ts b/apps/api/src/projects/projects.dto.ts index b4d3ffda..a202948c 100644 --- a/apps/api/src/projects/projects.dto.ts +++ b/apps/api/src/projects/projects.dto.ts @@ -38,6 +38,9 @@ export const RUN_FORMATS = [ ] as const; export type RunFormat = (typeof RUN_FORMATS)[number]; export const RUN_STATUSES = ['passed', 'failed'] as const; +/** A run's kind (spec 360); an ordinary run sends none. */ +export const RUN_KINDS = ['check'] as const; +export type RunKind = (typeof RUN_KINDS)[number]; /** `STAGE_NAMES` of `@demoflow/core`. */ export const RUN_STAGES = [ @@ -194,6 +197,11 @@ export class RunReportDto { @ValidateNested() @Type(() => RunFailureDto) failure?: RunFailureDto; + + /** `check` for a check run (spec 360); absent for an ordinary run. */ + @IsOptional() + @IsIn(RUN_KINDS) + kind?: RunKind; } export class CreateProjectDto { diff --git a/apps/api/src/projects/projects.integration.spec.ts b/apps/api/src/projects/projects.integration.spec.ts index 9a282e20..5c9c8573 100644 --- a/apps/api/src/projects/projects.integration.spec.ts +++ b/apps/api/src/projects/projects.integration.spec.ts @@ -101,6 +101,7 @@ describe('projects (integration)', () => { failedStep: null, cliVersion: '0.4.0', artifactsDeletedAt: null, + kind: null, }, createdAt: expect.any(String), updatedAt: expect.any(String), @@ -171,6 +172,43 @@ describe('projects (integration)', () => { expect(projects[0].lastRun.formats).toEqual(formats); }); + it('stores a check run with kind check, and an ordinary run with none (#360)', async () => { + const check = await report( + laptop.token, + runReport({ kind: 'check', formats: [] }), + ).expect(201); + const ordinary = await report(laptop.token).expect(201); + + const rows = await t.prisma.run.findMany({ + where: { id: { in: [check.body.runId, ordinary.body.runId] } }, + select: { id: true, kind: true }, + }); + expect(new Map(rows.map((row) => [row.id, row.kind]))).toEqual( + new Map([ + [check.body.runId, 'check'], + [ordinary.body.runId, null], + ]), + ); + const page = (await runs(alice.cookie, check.body.projectId).expect(200)) + .body; + expect( + page.runs.map((run: { id: string; kind: string | null }) => [ + run.id, + run.kind, + ]), + ).toEqual( + expect.arrayContaining([ + [check.body.runId, 'check'], + [ordinary.body.runId, null], + ]), + ); + }); + + it('refuses any kind but check', async () => { + await report(laptop.token, runReport({ kind: 'video' })).expect(400); + await report(laptop.token, runReport({ kind: null })).expect(201); + }); + it('stores no field it was not given a column for', async () => { await report(laptop.token, { ...runReport(), diff --git a/apps/api/src/projects/projects.service.ts b/apps/api/src/projects/projects.service.ts index b7d7c310..08d2866b 100644 --- a/apps/api/src/projects/projects.service.ts +++ b/apps/api/src/projects/projects.service.ts @@ -35,6 +35,8 @@ export interface RunView { cliVersion: string; /** When the machine deleted the run's directory (spec #233); null while it is there. */ artifactsDeletedAt: Date | null; + /** `check` for a check run (spec 360); null for an ordinary run. */ + kind: 'check' | null; } export interface ProjectView { @@ -81,6 +83,7 @@ export function toRunView(run: Run): RunView { failedStep: run.failedStep, cliVersion: run.cliVersion, artifactsDeletedAt: run.artifactsDeletedAt, + kind: run.kind, }; } @@ -249,6 +252,7 @@ export class ProjectsService { : Prisma.DbNull, failureStage: report.failure?.stage ?? null, failureMessage: report.failure?.message ?? null, + kind: report.kind ?? null, }, select: { id: true }, }); diff --git a/apps/api/src/videos/run-details.integration.spec.ts b/apps/api/src/videos/run-details.integration.spec.ts index 20f8e006..04ed073f 100644 --- a/apps/api/src/videos/run-details.integration.spec.ts +++ b/apps/api/src/videos/run-details.integration.spec.ts @@ -178,6 +178,7 @@ describe('run details (integration)', () => { 'failedStep', 'cliVersion', 'artifactsDeletedAt', + 'kind', ].sort(), ); } diff --git a/apps/api/src/videos/videos.integration.spec.ts b/apps/api/src/videos/videos.integration.spec.ts index eed877ae..cbaba340 100644 --- a/apps/api/src/videos/videos.integration.spec.ts +++ b/apps/api/src/videos/videos.integration.spec.ts @@ -690,6 +690,7 @@ describe('run video through the runner relay (integration)', () => { failedStep: null, cliVersion: '0.4.0', artifactsDeletedAt: null, + kind: null, stages: null, renders: null, failure: null, From ec3a6ec4c90903742d980d58f73639995b7ebc90 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 13:54:36 +0100 Subject: [PATCH 12/71] feat(api): share a run's video through /shares and /runner/shares A share is created with POST /shares (or POST /runner/shares from the machine that reported the run), checked against the file limit and the account quota, and answered 202 while the API pulls the poster and the render through the runner socket into SHARE_DIR. The share turns ready when both files are on disk, or failed with a short code; a failed or lost share of the same render is replaced by the next POST. The owner lists, reads, extends (30 days at a time, at most 90 ahead) and revokes shares. Deleting a run, a project or the account removes the share directories after the rows. A sweeper deletes expired shares, fails stuck uploads and orphan directories, and marks a ready share whose file is missing as lost at boot. The run page reports the features the machine announced, so the web can offer sharing only when the daemon supports it. --- .gitignore | 3 + apps/api/.env.example | 9 + apps/api/src/app.module.ts | 2 + apps/api/src/auth/auth.module.ts | 2 +- apps/api/src/projects/projects.module.ts | 3 +- apps/api/src/projects/projects.service.ts | 25 +- apps/api/src/runner/runner-socket.fixtures.ts | 30 +- apps/api/src/runner/runner.module.ts | 3 +- .../src/shares/runner-shares.controller.ts | 42 + apps/api/src/shares/share-config.ts | 54 ++ apps/api/src/shares/share-storage.ts | 90 +++ apps/api/src/shares/share-sweeper.ts | 149 ++++ apps/api/src/shares/share-upload.service.ts | 302 +++++++ apps/api/src/shares/shares.controller.ts | 68 ++ apps/api/src/shares/shares.dto.ts | 36 + .../api/src/shares/shares.integration.spec.ts | 764 ++++++++++++++++++ apps/api/src/shares/shares.module.ts | 22 + apps/api/src/shares/shares.service.ts | 365 +++++++++ apps/api/src/test/test-app.ts | 8 +- apps/api/src/users/account.service.ts | 33 +- apps/api/src/videos/runs.service.ts | 16 +- .../api/src/videos/videos.integration.spec.ts | 13 + apps/api/src/videos/videos.module.ts | 5 +- 23 files changed, 2017 insertions(+), 27 deletions(-) create mode 100644 apps/api/src/shares/runner-shares.controller.ts create mode 100644 apps/api/src/shares/share-config.ts create mode 100644 apps/api/src/shares/share-storage.ts create mode 100644 apps/api/src/shares/share-sweeper.ts create mode 100644 apps/api/src/shares/share-upload.service.ts create mode 100644 apps/api/src/shares/shares.controller.ts create mode 100644 apps/api/src/shares/shares.dto.ts create mode 100644 apps/api/src/shares/shares.integration.spec.ts create mode 100644 apps/api/src/shares/shares.module.ts create mode 100644 apps/api/src/shares/shares.service.ts diff --git a/.gitignore b/.gitignore index ebc2ccc6..7e518170 100644 --- a/.gitignore +++ b/.gitignore @@ -39,3 +39,6 @@ Thumbs.db # Prisma prisma/generated/ + +# Shared videos stored by the API in development (SHARE_DIR) +apps/api/data/ diff --git a/apps/api/.env.example b/apps/api/.env.example index 7aff02e8..180be6fb 100644 --- a/apps/api/.env.example +++ b/apps/api/.env.example @@ -21,3 +21,12 @@ MAIL_FROM=DemoFlow <no-reply@localhost> # http://localhost:3670/api/auth/github/callback. GITHUB_CLIENT_ID= GITHUB_CLIENT_SECRET= + +# Share links (spec #347): the directory that holds every shared video and +# poster, relative to the API's working directory unless absolute. Nothing +# else is written there; it is not backed up. +SHARE_DIR=./data/shares +# The largest render a share may hold (200 MB), and every account's total +# across its shares, posters included (2 GB). +SHARE_MAX_FILE_BYTES=209715200 +SHARE_USER_QUOTA_BYTES=2147483648 diff --git a/apps/api/src/app.module.ts b/apps/api/src/app.module.ts index 601fc36b..187c6c83 100644 --- a/apps/api/src/app.module.ts +++ b/apps/api/src/app.module.ts @@ -8,6 +8,7 @@ import { LaunchesModule } from './launches/launches.module'; import { MailModule } from './mail/mail.module'; import { ProjectsModule } from './projects/projects.module'; import { RunnerModule } from './runner/runner.module'; +import { SharesModule } from './shares/shares.module'; import { VideosModule } from './videos/videos.module'; @Module({ @@ -24,6 +25,7 @@ import { VideosModule } from './videos/videos.module'; ProjectsModule, VideosModule, LaunchesModule, + SharesModule, ], controllers: [HealthController], }) diff --git a/apps/api/src/auth/auth.module.ts b/apps/api/src/auth/auth.module.ts index 3bb92dd2..8edac5bf 100644 --- a/apps/api/src/auth/auth.module.ts +++ b/apps/api/src/auth/auth.module.ts @@ -29,6 +29,6 @@ import { VerifiedGuard } from './verified.guard'; GithubAuthService, { provide: GithubClient, useClass: HttpGithubClient }, ], - exports: [SessionService, SessionGuard, VerifiedGuard], + exports: [SessionService, SessionGuard, VerifiedGuard, PasswordHasher], }) export class AuthModule {} diff --git a/apps/api/src/projects/projects.module.ts b/apps/api/src/projects/projects.module.ts index 978d0d4c..67c7be2c 100644 --- a/apps/api/src/projects/projects.module.ts +++ b/apps/api/src/projects/projects.module.ts @@ -1,13 +1,14 @@ import { Module } from '@nestjs/common'; import { AuthModule } from '../auth/auth.module'; import { RunnerModule } from '../runner/runner.module'; +import { ShareStorageModule } from '../shares/share-storage'; import { ProjectsController } from './projects.controller'; import { ProjectsService } from './projects.service'; import { RunnerRunsController } from './runner-runs.controller'; /** Projects and the demo library (spec #178): metadata only, never video. */ @Module({ - imports: [AuthModule, RunnerModule], + imports: [AuthModule, RunnerModule, ShareStorageModule], controllers: [ProjectsController, RunnerRunsController], providers: [ProjectsService], }) diff --git a/apps/api/src/projects/projects.service.ts b/apps/api/src/projects/projects.service.ts index b7d7c310..a4d73618 100644 --- a/apps/api/src/projects/projects.service.ts +++ b/apps/api/src/projects/projects.service.ts @@ -7,6 +7,7 @@ import { } from '@nestjs/common'; import { Prisma, type Run, type Runner, type RunStatus } from '@prisma/client'; import { PrismaService } from '../database/prisma.service'; +import { ShareStorage } from '../shares/share-storage'; import { type CreateProjectDto, RUN_FORMATS, @@ -153,7 +154,7 @@ function parseStages(value: Prisma.JsonValue): RunStages | null { const RENDER_KEYS = ['format', 'width', 'height', 'sizeBytes', 'durationMs']; -function parseRenders(value: Prisma.JsonValue): RunRender[] | null { +export function parseRenders(value: Prisma.JsonValue): RunRender[] | null { if (!Array.isArray(value)) { return null; } @@ -209,7 +210,10 @@ function lastActivity(project: ProjectView): number { export class ProjectsService { private readonly logger = new Logger(ProjectsService.name); - constructor(private readonly prisma: PrismaService) {} + constructor( + private readonly prisma: PrismaService, + private readonly shareStorage: ShareStorage, + ) {} /** Upserts the folder's project and adds the run (Decision 3). */ async report( @@ -346,14 +350,22 @@ export class ProjectsService { return this.get(userId, id); } - /** Deletes the project; its runs cascade. */ + /** + * Deletes the project; its runs and their shares cascade, and the shares' + * directories go once the rows are gone (spec #347, Decision 9). + */ async remove(userId: string, id: string): Promise<void> { + const shares = await this.prisma.share.findMany({ + where: { run: { project: { id, userId } } }, + select: { id: true }, + }); const { count } = await this.prisma.project.deleteMany({ where: { id, userId }, }); if (count !== 1) { throw new NotFoundException(); } + await this.shareStorage.remove(shares.map((share) => share.id)); } /** @@ -400,7 +412,7 @@ export class ProjectsService { /** * Deletes the project's runs among `runIds` in one statement (spec #286). * Ids that are not runs of this project are skipped; only the rows go, the - * video files on the machine stay. + * video files on the machine stay. Shares of those runs go with them. */ async removeRuns( userId: string, @@ -414,12 +426,17 @@ export class ProjectsService { if (!project) { throw new NotFoundException(); } + const shares = await this.prisma.share.findMany({ + where: { run: { projectId: id, id: { in: runIds } } }, + select: { id: true }, + }); const { count } = await this.prisma.run.deleteMany({ where: { projectId: id, id: { in: runIds } }, }); this.logger.log( `runs.delete project=${id} asked=${runIds.length} deleted=${count}`, ); + await this.shareStorage.remove(shares.map((share) => share.id)); return { deleted: count }; } diff --git a/apps/api/src/runner/runner-socket.fixtures.ts b/apps/api/src/runner/runner-socket.fixtures.ts index 8889fc14..c0f9dcac 100644 --- a/apps/api/src/runner/runner-socket.fixtures.ts +++ b/apps/api/src/runner/runner-socket.fixtures.ts @@ -25,6 +25,13 @@ export interface LaunchRequest extends Received { requestId: string; } +/** `share.prepare` (spec #347). */ +export interface SharePrepare extends Received { + requestId: string; + runId: string; + format: string; +} + export interface Closed { code: number; reason: string; @@ -139,16 +146,27 @@ export class TestSocket { return ask as LaunchRequest; } + /** The next `share.prepare` (spec #347), with its request id as a string. */ + async nextShare(): Promise<SharePrepare> { + const ask = await this.next('share.prepare'); + if (typeof ask.requestId !== 'string') { + throw new Error('share.prepare carries no requestId'); + } + return ask as SharePrepare; + } + /** * `launches.sync` (spec #284): the launch ids this daemon still runs, and * the `run.start` options it accepts (spec #325) — none sent when omitted. + * `features` is its capability list, as `share` (spec #347). */ - sync(running: string[], runOptions?: unknown): void { - this.send( - runOptions === undefined - ? { type: 'launches.sync', running } - : { type: 'launches.sync', running, runOptions }, - ); + sync(running: string[], runOptions?: unknown, features?: string[]): void { + this.send({ + type: 'launches.sync', + running, + ...(runOptions === undefined ? {} : { runOptions }), + ...(features === undefined ? {} : { features }), + }); } /** `run.progress` (spec #301): `step` of `steps` for `steps`, both null otherwise. */ diff --git a/apps/api/src/runner/runner.module.ts b/apps/api/src/runner/runner.module.ts index 4ab1500c..a12239a0 100644 --- a/apps/api/src/runner/runner.module.ts +++ b/apps/api/src/runner/runner.module.ts @@ -1,5 +1,6 @@ import { Module } from '@nestjs/common'; import { AuthModule } from '../auth/auth.module'; +import { ShareStorageModule } from '../shares/share-storage'; import { AccountController } from '../users/account.controller'; import { AccountService } from '../users/account.service'; import { DeviceCodeService } from './device-code.service'; @@ -18,7 +19,7 @@ import { RunnersService } from './runners.service'; * would close an import cycle with `AuthModule`. */ @Module({ - imports: [AuthModule], + imports: [AuthModule, ShareStorageModule], controllers: [RunnerController, RunnersController, AccountController], providers: [ AccountService, diff --git a/apps/api/src/shares/runner-shares.controller.ts b/apps/api/src/shares/runner-shares.controller.ts new file mode 100644 index 00000000..6c2acab2 --- /dev/null +++ b/apps/api/src/shares/runner-shares.controller.ts @@ -0,0 +1,42 @@ +import { + Body, + Controller, + Get, + HttpCode, + HttpStatus, + Param, + Post, + UseGuards, +} from '@nestjs/common'; +import type { RunnerContext } from '../runner/runner-token'; +import { CurrentRunner, RunnerTokenGuard } from '../runner/runner-token.guard'; +import { CreateShareDto, ShareIdParamsDto } from './shares.dto'; +import { SharesService, type ShareView } from './shares.service'; + +/** + * `demoflow share` and the MCP tool (spec #347, Decision 7): only a run this + * machine reported. Whether an MCP client may share is checked on the + * machine, where the project's config is. + */ +@Controller('runner/shares') +@UseGuards(RunnerTokenGuard) +export class RunnerSharesController { + constructor(private readonly shares: SharesService) {} + + @Post() + @HttpCode(HttpStatus.ACCEPTED) + create( + @CurrentRunner() caller: RunnerContext, + @Body() body: CreateShareDto, + ): Promise<ShareView> { + return this.shares.create(caller.user.id, body, caller.runner.id); + } + + @Get(':id') + get( + @CurrentRunner() caller: RunnerContext, + @Param() { id }: ShareIdParamsDto, + ): Promise<ShareView> { + return this.shares.get(caller.user.id, id, caller.runner.id); + } +} diff --git a/apps/api/src/shares/share-config.ts b/apps/api/src/shares/share-config.ts new file mode 100644 index 00000000..1079e33e --- /dev/null +++ b/apps/api/src/shares/share-config.ts @@ -0,0 +1,54 @@ +import { resolve } from 'node:path'; +import { Injectable } from '@nestjs/common'; +import { ConfigService } from '@nestjs/config'; + +/** 200 MB (spec #347, Decision 3). */ +export const DEFAULT_SHARE_MAX_FILE_BYTES = 209_715_200; +/** 2 GB per user. */ +export const DEFAULT_SHARE_USER_QUOTA_BYTES = 2_147_483_648; + +/** + * Where shared files live and how much of them a user may keep (spec #347, + * Configuration). A limit that is set but not a positive integer stops the + * API at boot rather than falling back silently. + */ +@Injectable() +export class ShareConfig { + /** Absolute: `SHARE_DIR` resolved against the API's working directory. */ + readonly dir: string; + readonly maxFileBytes: number; + readonly quotaBytes: number; + /** The web origin a share's link points at. */ + readonly webUrl: string; + + constructor(config: ConfigService) { + this.dir = resolve( + config.get<string>('SHARE_DIR')?.trim() || './data/shares', + ); + this.maxFileBytes = bytes( + config, + 'SHARE_MAX_FILE_BYTES', + DEFAULT_SHARE_MAX_FILE_BYTES, + ); + this.quotaBytes = bytes( + config, + 'SHARE_USER_QUOTA_BYTES', + DEFAULT_SHARE_USER_QUOTA_BYTES, + ); + this.webUrl = ( + config.get<string>('WEB_URL') ?? 'http://localhost:3670' + ).replace(/\/+$/, ''); + } +} + +function bytes(config: ConfigService, name: string, fallback: number): number { + const raw = config.get<string>(name)?.trim(); + if (!raw) { + return fallback; + } + const value = Number(raw); + if (!Number.isSafeInteger(value) || value <= 0) { + throw new Error(`${name} must be a positive integer, got "${raw}"`); + } + return value; +} diff --git a/apps/api/src/shares/share-storage.ts b/apps/api/src/shares/share-storage.ts new file mode 100644 index 00000000..e60a0528 --- /dev/null +++ b/apps/api/src/shares/share-storage.ts @@ -0,0 +1,90 @@ +import { access, mkdir, readdir, rm } from 'node:fs/promises'; +import { join } from 'node:path'; +import { Injectable, Module } from '@nestjs/common'; +import type { RunFormat } from '../projects/projects.dto'; +import { ShareConfig } from './share-config'; + +/** A cuid from the database: never a string from a request (Decision 2). */ +const SHARE_ID = /^[a-z0-9]+$/; + +/** + * The share directory, `SHARE_DIR` (spec #347, Decision 2): one directory + * per share, holding `file.<ext>` and `poster.jpg`. Every path is built from + * a share id the database made, checked here once more before it touches + * the disk. + */ +@Injectable() +export class ShareStorage { + constructor(private readonly config: ShareConfig) {} + + dirOf(id: string): string { + if (!SHARE_ID.test(id)) { + throw new Error('Not a share id'); + } + return join(this.config.dir, id); + } + + /** `mp4`, `gif` or `webm`: the format without its orientation. */ + filePath(id: string, format: RunFormat): string { + return join(this.dirOf(id), `file.${extensionOf(format)}`); + } + + posterPath(id: string): string { + return join(this.dirOf(id), 'poster.jpg'); + } + + /** An empty directory for the share's files. */ + async prepare(id: string): Promise<void> { + await mkdir(this.dirOf(id), { recursive: true }); + } + + async exists(path: string): Promise<boolean> { + try { + await access(path); + return true; + } catch { + return false; + } + } + + /** Deletes the shares' directories; one already gone is no error. */ + async remove(ids: readonly string[]): Promise<void> { + await Promise.all( + ids.map((id) => rm(this.dirOf(id), { recursive: true, force: true })), + ); + } + + /** The share ids that have a directory. Anything else in `SHARE_DIR` is left. */ + async list(): Promise<string[]> { + try { + const entries = await readdir(this.config.dir, { withFileTypes: true }); + return entries + .filter((entry) => entry.isDirectory() && SHARE_ID.test(entry.name)) + .map((entry) => entry.name); + } catch (error) { + if (isMissing(error)) { + return []; + } + throw error; + } + } +} + +export function extensionOf(format: RunFormat): string { + const [extension] = format.split('-'); + return extension ?? format; +} + +function isMissing(error: unknown): boolean { + return error instanceof Error && 'code' in error && error.code === 'ENOENT'; +} + +/** + * Its own module so the run, project and account deletes can reach the + * directory without importing the shares module and its controllers. + */ +@Module({ + providers: [ShareConfig, ShareStorage], + exports: [ShareConfig, ShareStorage], +}) +export class ShareStorageModule {} diff --git a/apps/api/src/shares/share-sweeper.ts b/apps/api/src/shares/share-sweeper.ts new file mode 100644 index 00000000..f12c2932 --- /dev/null +++ b/apps/api/src/shares/share-sweeper.ts @@ -0,0 +1,149 @@ +import { + Injectable, + Logger, + type OnApplicationBootstrap, + type OnModuleDestroy, +} from '@nestjs/common'; +import { Clock } from '../common/clock'; +import { PrismaService } from '../database/prisma.service'; +import { RUN_FORMATS, type RunFormat } from '../projects/projects.dto'; +import { ShareStorage } from './share-storage'; + +/** Spec #347, Decision 9. */ +export const SHARE_SWEEP_INTERVAL_MS = 10 * 60 * 1000; +/** An upload still running this long after the share was created has failed. */ +export const SHARE_UPLOAD_STALE_MS = 15 * 60 * 1000; + +export interface SweepResult { + expired: number; + timedOut: number; + orphans: number; + lost: number; +} + +/** + * Keeps the share directory and the table in step (spec #347, Decision 9): + * expired shares go with their files, stale uploads fail, directories with + * no row go, and on boot a ready share whose file is gone is marked lost. + * The backstop for every cascade that deletes rows before their files. + */ +@Injectable() +export class ShareSweeper implements OnApplicationBootstrap, OnModuleDestroy { + private readonly logger = new Logger(ShareSweeper.name); + private timer: NodeJS.Timeout | undefined; + private running = false; + + constructor( + private readonly prisma: PrismaService, + private readonly storage: ShareStorage, + private readonly clock: Clock, + ) {} + + onApplicationBootstrap(): void { + void this.run(true); + this.timer = setInterval( + () => void this.run(false), + SHARE_SWEEP_INTERVAL_MS, + ); + this.timer.unref(); + } + + onModuleDestroy(): void { + clearInterval(this.timer); + } + + /** One pass. `boot` also checks that every ready share still has its file. */ + async sweep(boot: boolean): Promise<SweepResult> { + const now = this.clock.now(); + const expired = await this.prisma.share.findMany({ + where: { expiresAt: { lte: now } }, + select: { id: true }, + }); + const expiredIds = expired.map(({ id }) => id); + await this.prisma.share.deleteMany({ + where: { id: { in: expiredIds }, expiresAt: { lte: now } }, + }); + await this.storage.remove(expiredIds); + + const stale = await this.prisma.share.findMany({ + where: { + status: 'uploading', + createdAt: { lt: new Date(now.getTime() - SHARE_UPLOAD_STALE_MS) }, + }, + select: { id: true }, + }); + const staleIds = stale.map(({ id }) => id); + await this.prisma.share.updateMany({ + where: { id: { in: staleIds }, status: 'uploading' }, + data: { status: 'failed', failure: 'timed-out' }, + }); + await this.storage.remove(staleIds); + + const orphans = await this.orphans(); + await this.storage.remove(orphans); + + const lost = boot ? await this.markLost() : []; + return { + expired: expiredIds.length, + timedOut: staleIds.length, + orphans: orphans.length, + lost: lost.length, + }; + } + + private async run(boot: boolean): Promise<void> { + // A slow pass is not overlapped by the next one. + if (this.running) { + return; + } + this.running = true; + try { + const result = await this.sweep(boot); + this.logger.log( + JSON.stringify({ event: 'share.sweep', boot, ...result }), + ); + } catch (error) { + this.logger.error(error); + } finally { + this.running = false; + } + } + + /** Directories with no row. The row is created before its directory. */ + private async orphans(): Promise<string[]> { + const ids = await this.storage.list(); + if (ids.length === 0) { + return []; + } + const rows = await this.prisma.share.findMany({ + where: { id: { in: ids } }, + select: { id: true }, + }); + const known = new Set(rows.map(({ id }) => id)); + return ids.filter((id) => !known.has(id)); + } + + /** Not backed up (ADR-0019 §4): the owner uploads a lost share again. */ + private async markLost(): Promise<string[]> { + const ready = await this.prisma.share.findMany({ + where: { status: 'ready' }, + select: { id: true, format: true }, + }); + const lost: string[] = []; + for (const { id, format } of ready) { + const known = RUN_FORMATS.find((candidate) => candidate === format); + if (!known || !(await this.hasFile(id, known))) { + lost.push(id); + } + } + await this.prisma.share.updateMany({ + where: { id: { in: lost }, status: 'ready' }, + data: { status: 'lost' }, + }); + return lost; + } + + private hasFile(id: string, format: RunFormat): Promise<boolean> { + return this.storage.exists(this.storage.filePath(id, format)); + } +} diff --git a/apps/api/src/shares/share-upload.service.ts b/apps/api/src/shares/share-upload.service.ts new file mode 100644 index 00000000..16f7a031 --- /dev/null +++ b/apps/api/src/shares/share-upload.service.ts @@ -0,0 +1,302 @@ +import { randomUUID } from 'node:crypto'; +import { + Injectable, + Logger, + type OnApplicationBootstrap, + type OnModuleDestroy, + type OnModuleInit, +} from '@nestjs/common'; +import { Clock } from '../common/clock'; +import { PrismaService } from '../database/prisma.service'; +import type { RunFormat } from '../projects/projects.dto'; +import type { RunRender } from '../projects/projects.service'; +import { + RunnerConnections, + type ShareSink, +} from '../runner/runner-connections.service'; +import { + MAX_STREAMS_PER_RUNNER, + SHARE_POSTER_MAX_BYTES, + type ShareMessage, +} from '../runner/runner-socket'; +import { + type UploadOutcome, + type UploadVideo, + VideoRelay, +} from '../videos/video-relay.service'; +import { ShareConfig } from './share-config'; +import { ShareStorage } from './share-storage'; + +/** No answer this long after `share.prepare`: the share fails (spec #347, Decision 4). */ +export const PREPARE_TIMEOUT_MS = 30 * 1000; +/** How often the timeout is checked. */ +const SWEEP_INTERVAL_MS = 1000; + +/** What the daemon answered to `share.prepare`. */ +interface Prepared { + description: string | null; + chapters: Array<{ title: string; atMs: number }>; +} + +type PrepareOutcome = + | { ok: true; prepared: Prepared } + | { ok: false; error: string }; + +interface Pending { + id: string; + runnerId: string; + /** Clock ms. */ + sentAt: number; + settle: (outcome: PrepareOutcome) => void; +} + +/** One share's upload: which machine, which file, and what the run reported. */ +export interface ShareUpload { + shareId: string; + userId: string; + runId: string; + format: RunFormat; + runnerId: string; + /** The run's `renders` entry for the format; null when the CLI did not report it. */ + render: RunRender | null; +} + +/** + * Pulls a share's files from the machine that recorded the run (spec #347, + * Decision 4, ADR-0019 §3): `share.prepare`, then the poster and the render + * through `VideoRelay` into the share's directory. The row ends `ready`, or + * `failed` with its files deleted. + * + * Works only on the instance that holds the Runner's socket, like the relay. + */ +@Injectable() +export class ShareUploadService + implements ShareSink, OnModuleInit, OnApplicationBootstrap, OnModuleDestroy +{ + private readonly logger = new Logger(ShareUploadService.name); + private readonly pending = new Map<string, Pending>(); + private timer: NodeJS.Timeout | undefined; + + constructor( + private readonly connections: RunnerConnections, + private readonly relay: VideoRelay, + private readonly prisma: PrismaService, + private readonly storage: ShareStorage, + private readonly config: ShareConfig, + private readonly clock: Clock, + ) {} + + onModuleInit(): void { + this.connections.setShareSink(this); + } + + onApplicationBootstrap(): void { + this.timer = setInterval(() => this.tick(), SWEEP_INTERVAL_MS); + this.timer.unref(); + } + + onModuleDestroy(): void { + clearInterval(this.timer); + } + + /** + * Uploads the share's files and records the outcome. Never throws: a share + * that cannot be uploaded ends `failed`. Settles once the row says so. + */ + async upload(target: ShareUpload): Promise<void> { + const startedAt = this.clock.now().getTime(); + let outcome: string; + try { + outcome = await this.pull(target); + } catch (error) { + this.logger.error(error); + outcome = 'error'; + } + if (outcome !== 'ready') { + await this.fail(target.shareId, outcome); + } + // Decision 10: never the token, the password, the title or the description. + this.logger.log( + JSON.stringify({ + event: 'share.upload', + shareId: target.shareId, + runId: target.runId, + outcome, + durationMs: this.clock.now().getTime() - startedAt, + }), + ); + } + + message(runnerId: string, message: ShareMessage): boolean { + const request = this.pending.get(message.requestId); + // Only the machine a request was sent to can answer it. + if (request?.runnerId !== runnerId) { + return false; + } + if (message.type === 'share.prepared') { + this.settle(request, { + ok: true, + prepared: { + description: message.description ?? null, + chapters: message.chapters.map(({ title, atMs }) => ({ + title, + atMs, + })), + }, + }); + } else { + this.settle(request, { ok: false, error: message.code }); + } + return true; + } + + /** Every request on the machine's socket ends with it. */ + closed(runnerId: string): void { + for (const request of [...this.pending.values()]) { + if (request.runnerId === runnerId) { + this.settle(request, { ok: false, error: 'runner-offline' }); + } + } + } + + /** The timeout, on the injected clock. Runs every `SWEEP_INTERVAL_MS`. */ + tick(): void { + const now = this.clock.now().getTime(); + for (const request of [...this.pending.values()]) { + if (now - request.sentAt >= PREPARE_TIMEOUT_MS) { + this.settle(request, { ok: false, error: 'runner-timeout' }); + } + } + } + + /** `ready`, or the code the share fails with. */ + private async pull(target: ShareUpload): Promise<string> { + const { shareId, userId, runnerId, runId, format, render } = target; + await this.storage.prepare(shareId); + const prepare = await this.prepare(runnerId, runId, format); + if (!prepare.ok) { + return prepare.error; + } + + const poster = await this.stream({ + runnerId, + runId, + format, + asset: 'poster', + path: this.storage.posterPath(shareId), + accept: (size) => + size > SHARE_POSTER_MAX_BYTES ? 'poster-too-large' : null, + }); + if (!poster.ok) { + return poster.error; + } + + // Read once, so the head's check stays synchronous. A share created + // meanwhile reserved its bytes under the user's lock and is counted. + const others = await this.usedBytes(userId, shareId); + const file = await this.stream({ + runnerId, + runId, + format, + path: this.storage.filePath(shareId, format), + accept: (size) => { + if (size > this.config.maxFileBytes) { + return 'file-too-large'; + } + if (others + poster.size + size > this.config.quotaBytes) { + return 'quota-exceeded'; + } + return null; + }, + }); + if (!file.ok) { + return file.error; + } + + // Only an upload still running may finish: a revoked or swept share stays gone. + const { count } = await this.prisma.share.updateMany({ + where: { id: shareId, status: 'uploading' }, + data: { + status: 'ready', + failure: null, + sizeBytes: file.size, + posterBytes: poster.size, + description: prepare.prepared.description, + chapters: prepare.prepared.chapters, + width: render?.width ?? null, + height: render?.height ?? null, + durationMs: render?.durationMs ?? null, + }, + }); + if (count !== 1) { + await this.storage.remove([shareId]); + return 'gone'; + } + return 'ready'; + } + + /** As playback: a fifth stream to the machine is `runner-busy`. */ + private stream(upload: UploadVideo): Promise<UploadOutcome> { + if (this.relay.openTo(upload.runnerId) >= MAX_STREAMS_PER_RUNNER) { + return Promise.resolve({ ok: false, error: 'runner-busy' }); + } + return this.relay.upload(upload); + } + + private prepare( + runnerId: string, + runId: string, + format: RunFormat, + ): Promise<PrepareOutcome> { + return new Promise((settle) => { + const request: Pending = { + id: randomUUID(), + runnerId, + sentAt: this.clock.now().getTime(), + settle, + }; + this.pending.set(request.id, request); + const sent = this.connections.sendTo(runnerId, { + type: 'share.prepare', + requestId: request.id, + runId, + format, + }); + if (!sent) { + this.settle(request, { ok: false, error: 'runner-offline' }); + } + }); + } + + private settle(request: Pending, outcome: PrepareOutcome): void { + this.pending.delete(request.id); + request.settle(outcome); + } + + /** The user's live shares other than this one: what the quota counts. */ + private async usedBytes(userId: string, exceptId: string): Promise<number> { + const { _sum } = await this.prisma.share.aggregate({ + where: { + userId, + id: { not: exceptId }, + status: { in: ['uploading', 'ready'] }, + }, + _sum: { sizeBytes: true, posterBytes: true }, + }); + return (_sum.sizeBytes ?? 0) + (_sum.posterBytes ?? 0); + } + + /** The files go, and with them the bytes the quota counted. */ + private async fail(shareId: string, failure: string): Promise<void> { + try { + await this.prisma.share.updateMany({ + where: { id: shareId, status: 'uploading' }, + data: { status: 'failed', failure: failure.slice(0, 64) }, + }); + await this.storage.remove([shareId]); + } catch (error) { + // The sweeper fails a stale upload and deletes its directory. + this.logger.error(error); + } + } +} diff --git a/apps/api/src/shares/shares.controller.ts b/apps/api/src/shares/shares.controller.ts new file mode 100644 index 00000000..0c3d7a09 --- /dev/null +++ b/apps/api/src/shares/shares.controller.ts @@ -0,0 +1,68 @@ +import { + Body, + Controller, + Delete, + Get, + HttpCode, + HttpStatus, + Param, + Post, + UseGuards, +} from '@nestjs/common'; +import type { User } from '@prisma/client'; +import { CurrentUser } from '../auth/current-user.decorator'; +import { SessionGuard } from '../auth/session.guard'; +import { CreateShareDto, ShareIdParamsDto } from './shares.dto'; +import { + type SharesList, + SharesService, + type ShareView, +} from './shares.service'; + +/** The owner's share links (spec #347, ADR-0019). */ +@Controller('shares') +@UseGuards(SessionGuard) +export class SharesController { + constructor(private readonly shares: SharesService) {} + + /** 202: the row exists, the upload runs in the background. */ + @Post() + @HttpCode(HttpStatus.ACCEPTED) + create( + @CurrentUser() user: User, + @Body() body: CreateShareDto, + ): Promise<ShareView> { + return this.shares.create(user.id, body); + } + + @Get() + list(@CurrentUser() user: User): Promise<SharesList> { + return this.shares.list(user.id); + } + + @Get(':id') + get( + @CurrentUser() user: User, + @Param() { id }: ShareIdParamsDto, + ): Promise<ShareView> { + return this.shares.get(user.id, id); + } + + @Post(':id/extend') + @HttpCode(HttpStatus.OK) + extend( + @CurrentUser() user: User, + @Param() { id }: ShareIdParamsDto, + ): Promise<ShareView> { + return this.shares.extend(user.id, id); + } + + @Delete(':id') + @HttpCode(HttpStatus.NO_CONTENT) + remove( + @CurrentUser() user: User, + @Param() { id }: ShareIdParamsDto, + ): Promise<void> { + return this.shares.remove(user.id, id); + } +} diff --git a/apps/api/src/shares/shares.dto.ts b/apps/api/src/shares/shares.dto.ts new file mode 100644 index 00000000..270c361b --- /dev/null +++ b/apps/api/src/shares/shares.dto.ts @@ -0,0 +1,36 @@ +import { IsIn, IsOptional, IsString, IsUUID, Length } from 'class-validator'; +import { RUN_FORMATS, type RunFormat } from '../projects/projects.dto'; + +/** A share's lifetime in days (spec #347, Decision 5). */ +export const SHARE_LIFETIMES = [7, 30, 90] as const; +export type ShareLifetime = (typeof SHARE_LIFETIMES)[number]; +export const DEFAULT_SHARE_LIFETIME: ShareLifetime = 30; + +/** Decision 8. */ +export const SHARE_PASSWORD_MIN = 8; +export const SHARE_PASSWORD_MAX = 128; + +/** `POST /shares` and `POST /runner/shares`. */ +export class CreateShareDto { + @IsUUID() + runId!: string; + + @IsIn(RUN_FORMATS) + format!: RunFormat; + + @IsOptional() + @IsIn(SHARE_LIFETIMES) + expiresInDays?: ShareLifetime; + + /** Never trimmed: a password is what the person typed. */ + @IsOptional() + @IsString() + @Length(SHARE_PASSWORD_MIN, SHARE_PASSWORD_MAX) + password?: string; +} + +export class ShareIdParamsDto { + @IsString() + @Length(1, 64) + id!: string; +} diff --git a/apps/api/src/shares/shares.integration.spec.ts b/apps/api/src/shares/shares.integration.spec.ts new file mode 100644 index 00000000..9777f5ee --- /dev/null +++ b/apps/api/src/shares/shares.integration.spec.ts @@ -0,0 +1,764 @@ +import { randomBytes } from 'node:crypto'; +import { + mkdir, + mkdtemp, + readdir, + readFile, + rm, + writeFile, +} from 'node:fs/promises'; +import type { AddressInfo } from 'node:net'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { Logger } from '@nestjs/common'; +import request from 'supertest'; +import type { App } from 'supertest/types'; +import { generateToken } from '../auth/tokens'; +import { + type Paired, + pair, + type SignedIn, + signedInUser, +} from '../runner/runner.fixtures'; +import { eventually, TestSocket } from '../runner/runner-socket.fixtures'; +import { createTestApp, type TestApp } from '../test/test-app'; +import { HEAD_TIMEOUT_MS, VideoRelay } from '../videos/video-relay.service'; +import { ShareConfig } from './share-config'; +import { ShareStorage } from './share-storage'; +import { ShareSweeper } from './share-sweeper'; + +const FILE = randomBytes(5000); +const POSTER = randomBytes(300); +const MAX_FILE = 10_000; +const QUOTA = 20_000; +const DAY_MS = 24 * 60 * 60 * 1000; +const TITLE = 'Checkout flow 7f3a'; +const DESCRIPTION = 'Buys one item, secret description 9c2e.'; +const PASSWORD = 'hunter22-correct-horse'; + +interface ShareBody { + id: string; + url: string; + fileUrl: string | null; + status: string; + failure: string | null; + sizeBytes: number; + expiresAt: string; +} + +describe('share links (integration)', () => { + let t: TestApp; + let http: App; + let port: number; + let dir: string; + let alice: SignedIn; + let bob: SignedIn; + let machine: Paired; + let runId: string; + const sockets: TestSocket[] = []; + + beforeEach(async () => { + dir = await mkdtemp(join(tmpdir(), 'demoflow-shares-')); + const config: ShareConfig = { + dir, + maxFileBytes: MAX_FILE, + quotaBytes: QUOTA, + webUrl: 'http://web.test', + }; + t = await createTestApp([], [{ provide: ShareConfig, useValue: config }]); + await t.app.listen(0, '127.0.0.1'); + http = t.app.getHttpServer(); + port = (http.address() as AddressInfo).port; + alice = await signedInUser(t, 'alice'); + bob = await signedInUser(t, 'bob'); + machine = await pair(http, alice, 'Laptop'); + runId = await report(machine); + }); + + afterEach(async () => { + for (const socket of sockets.splice(0)) { + socket.ws.terminate(); + } + // Uploads still waiting settle on the closed sockets before the app goes. + await eventually(async () => { + const uploading = await t.prisma.share.count({ + where: { + run: { project: { userId: alice.user.id } }, + status: 'uploading', + }, + }); + return uploading === 0; + }).catch(() => undefined); + await t.app.close(); + await rm(dir, { recursive: true, force: true }); + }); + + /** A run with `mp4`, `webm` and `gif`; `sizes` sets what `renders` says. */ + async function report( + by: Paired, + sizes: Record<string, number> = { mp4: 6000, webm: 6000, gif: 6000 }, + ): Promise<string> { + const formats = Object.keys(sizes); + const res = await request(http) + .post('/runner/runs') + .set('Authorization', `Bearer ${by.token}`) + .send({ + rootPath: '/home/alice/shop', + projectName: 'shop', + scenarioName: TITLE, + scenarioPath: 'demos/checkout.yaml', + status: 'passed', + startedAt: t.clock.now().toISOString(), + durationMs: 12_345, + formats, + cliVersion: '0.7.0', + renders: formats.map((format) => ({ + format, + width: 1280, + height: 720, + sizeBytes: sizes[format], + durationMs: 12_000, + })), + }) + .expect(201); + return res.body.runId; + } + + /** A daemon on `by`'s token that announced `features`; `null` sends none. */ + async function daemon( + by: Paired = machine, + features: string[] | null = ['share'], + ): Promise<TestSocket> { + const socket = await TestSocket.connect( + `ws://127.0.0.1:${port}/runner`, + by.token, + ); + sockets.push(socket); + socket.sync([], undefined, features ?? undefined); + await socket.roundTrip(); + return socket; + } + + function create( + body: Record<string, unknown>, + cookie = alice.cookie, + ): request.Test { + return request(http).post('/shares').set('Cookie', cookie).send(body); + } + + /** Answers `share.prepare`, then serves the poster and the render. */ + async function serveShare(socket: TestSocket, file = FILE): Promise<void> { + const prepare = await socket.nextShare(); + socket.send({ + type: 'share.prepared', + requestId: prepare.requestId, + description: DESCRIPTION, + chapters: [ + { title: 'Open the cart', atMs: 0 }, + { title: 'Pay', atMs: 4000 }, + ], + posterSize: POSTER.length, + }); + const poster = await socket.nextOpen(); + socket.serve(poster.streamId, POSTER); + const render = await socket.nextOpen(); + socket.serve(render.streamId, file); + } + + async function shareOf(id: string): Promise<ShareBody> { + const res = await request(http) + .get(`/shares/${id}`) + .set('Cookie', alice.cookie) + .expect(200); + return res.body as ShareBody; + } + + async function settled(id: string, status: string): Promise<ShareBody> { + await eventually(async () => (await shareOf(id)).status === status); + return shareOf(id); + } + + async function ready(format = 'mp4', run = runId): Promise<string> { + const socket = sockets[0] ?? (await daemon()); + const res = await create({ runId: run, format }).expect(202); + await serveShare(socket); + await settled(res.body.id, 'ready'); + return res.body.id; + } + + /** Every entry left under the share's directory, `.part` files included. */ + async function filesOf(id: string): Promise<string[] | null> { + try { + return (await readdir(join(dir, id))).sort(); + } catch { + return null; + } + } + + describe('upload', () => { + it('pulls the poster and the render, then the share is ready', async () => { + const socket = await daemon(); + const res = await create({ runId, format: 'mp4' }).expect(202); + expect(res.body).toMatchObject({ + status: 'uploading', + runId, + title: TITLE, + format: 'mp4', + hasPassword: false, + views: 0, + failure: null, + }); + const token = (res.body.url as string).replace('http://web.test/s/', ''); + expect(token).toMatch(/^[A-Za-z0-9_-]{43}$/); + expect(res.body.fileUrl).toBe(`${res.body.url}/file`); + expect(res.body).not.toHaveProperty('token'); + expect(res.body).not.toHaveProperty('passwordHash'); + + const prepare = await socket.nextShare(); + expect(prepare).toMatchObject({ runId, format: 'mp4' }); + socket.send({ + type: 'share.prepared', + requestId: prepare.requestId, + description: DESCRIPTION, + chapters: [{ title: 'Open the cart', atMs: 0 }], + posterSize: POSTER.length, + }); + const poster = await socket.nextOpen(); + expect(poster).toMatchObject({ + runId, + format: 'mp4', + range: null, + asset: 'poster', + }); + socket.serve(poster.streamId, POSTER); + const render = await socket.nextOpen(); + expect(render).toMatchObject({ runId, format: 'mp4', range: null }); + expect(render).not.toHaveProperty('asset'); + socket.serve(render.streamId, FILE); + + const share = await settled(res.body.id, 'ready'); + expect(share).toMatchObject({ + sizeBytes: FILE.length, + width: 1280, + height: 720, + durationMs: 12_000, + }); + expect(await filesOf(share.id)).toEqual(['file.mp4', 'poster.jpg']); + expect(await readFile(join(dir, share.id, 'file.mp4'))).toEqual(FILE); + expect(await readFile(join(dir, share.id, 'poster.jpg'))).toEqual(POSTER); + const row = await t.prisma.share.findUniqueOrThrow({ + where: { id: share.id }, + }); + expect(row).toMatchObject({ + description: DESCRIPTION, + chapters: [{ title: 'Open the cart', atMs: 0 }], + posterBytes: POSTER.length, + }); + + const list = await request(http) + .get('/shares') + .set('Cookie', alice.cookie) + .expect(200); + expect(list.body.shares.map((s: ShareBody) => s.id)).toEqual([share.id]); + expect(list.body.quota).toEqual({ + usedBytes: FILE.length + POSTER.length, + limitBytes: QUOTA, + maxFileBytes: MAX_FILE, + }); + }); + + it('keeps only the hash of a password and hides the file URL', async () => { + await daemon(); + const res = await create({ + runId, + format: 'mp4', + password: PASSWORD, + expiresInDays: 7, + }).expect(202); + expect(res.body).toMatchObject({ hasPassword: true, fileUrl: null }); + expect(new Date(res.body.expiresAt).getTime()).toBe( + t.clock.now().getTime() + 7 * DAY_MS, + ); + const row = await t.prisma.share.findUniqueOrThrow({ + where: { id: res.body.id }, + }); + expect(row.passwordHash).toMatch(/^\$argon2id\$/); + }); + + it('validates the body', async () => { + await create({ runId, format: 'mp4', expiresInDays: 14 }).expect(400); + await create({ runId, format: 'mp4', password: 'short' }).expect(400); + await create({ runId, format: 'mov' }).expect(400); + await create({ runId, format: 'mp4', extra: 1 }).expect(400); + }); + + it('answers share-exists for a second share of the same render', async () => { + await daemon(); + const first = await create({ runId, format: 'mp4' }).expect(202); + const second = await create({ runId, format: 'mp4' }).expect(409); + expect(second.body).toEqual({ + error: 'share-exists', + shareId: first.body.id, + }); + }); + + it('replaces a failed share of the same render', async () => { + const socket = await daemon(); + const first = await create({ runId, format: 'mp4' }).expect(202); + const prepare = await socket.nextShare(); + socket.send({ + type: 'share.error', + requestId: prepare.requestId, + code: 'io', + }); + await settled(first.body.id, 'failed'); + const second = await create({ runId, format: 'mp4' }).expect(202); + expect(second.body.id).not.toBe(first.body.id); + expect(await t.prisma.share.count({ where: { id: first.body.id } })).toBe( + 0, + ); + }); + + it('refuses a format the run did not render', async () => { + await daemon(); + const res = await create({ runId, format: 'webm-square' }).expect(409); + expect(res.body).toEqual({ error: 'format-not-rendered' }); + }); + }); + + describe('the machine', () => { + it('sends nothing to a daemon without `share`: runner-outdated', async () => { + const socket = await daemon(machine, null); + const res = await create({ runId, format: 'mp4' }).expect(409); + expect(res.body).toEqual({ error: 'runner-outdated' }); + await socket.roundTrip(); + expect(socket.received.map((m) => m.type)).not.toContain('share.prepare'); + expect(await t.prisma.share.count({ where: { runId } })).toBe(0); + }); + + it('answers runner-offline without a socket', async () => { + const res = await create({ runId, format: 'mp4' }).expect(409); + expect(res.body).toEqual({ error: 'runner-offline' }); + }); + + it('refuses a run whose files were deleted', async () => { + await daemon(); + await t.prisma.run.update({ + where: { id: runId }, + data: { artifactsDeletedAt: t.clock.now() }, + }); + const res = await create({ runId, format: 'mp4' }).expect(409); + expect(res.body).toEqual({ error: 'artifacts-deleted' }); + }); + + it('shows the features on the run page', async () => { + await daemon(); + const res = await request(http) + .get(`/runs/${runId}`) + .set('Cookie', alice.cookie) + .expect(200); + expect(res.body.machine.features).toEqual(['share']); + }); + }); + + describe('limits', () => { + it('answers 413 before any message for a render over the file limit', async () => { + const big = await report(machine, { mp4: MAX_FILE + 1 }); + const socket = await daemon(); + const res = await create({ runId: big, format: 'mp4' }).expect(413); + expect(res.body).toEqual({ + error: 'file-too-large', + maxFileBytes: MAX_FILE, + }); + await socket.roundTrip(); + expect(socket.received.map((m) => m.type)).not.toContain('share.prepare'); + }); + + it('cancels a head over the file limit and fails the share', async () => { + const socket = await daemon(); + const res = await create({ runId, format: 'mp4' }).expect(202); + const prepare = await socket.nextShare(); + socket.send({ + type: 'share.prepared', + requestId: prepare.requestId, + chapters: [], + posterSize: POSTER.length, + }); + const poster = await socket.nextOpen(); + socket.serve(poster.streamId, POSTER); + const render = await socket.nextOpen(); + socket.send({ + type: 'video.head', + streamId: render.streamId, + size: MAX_FILE + 1, + start: 0, + end: MAX_FILE, + }); + const cancel = await socket.next('video.cancel'); + expect(cancel.streamId).toBe(render.streamId); + const share = await settled(res.body.id, 'failed'); + expect(share.failure).toBe('file-too-large'); + expect(await filesOf(share.id)).toBeNull(); + }); + + it('answers quota-exceeded, and a delete frees the bytes', async () => { + await daemon(); + // 6000 bytes reserved per uploading share, from the run's renders. + const mp4 = await create({ runId, format: 'mp4' }).expect(202); + await create({ runId, format: 'webm' }).expect(202); + await create({ runId, format: 'gif' }).expect(202); + const other = await report(machine, { mp4: 6000 }); + const over = await create({ runId: other, format: 'mp4' }).expect(409); + expect(over.body).toEqual({ + error: 'quota-exceeded', + usedBytes: 18_000, + limitBytes: QUOTA, + }); + await request(http) + .delete(`/shares/${mp4.body.id}`) + .set('Cookie', alice.cookie) + .expect(204); + await create({ runId: other, format: 'mp4' }).expect(202); + }); + }); + + describe('failures', () => { + it('share.error fails the share', async () => { + const socket = await daemon(); + const res = await create({ runId, format: 'mp4' }).expect(202); + const prepare = await socket.nextShare(); + socket.send({ + type: 'share.error', + requestId: prepare.requestId, + code: 'no-render', + }); + const share = await settled(res.body.id, 'failed'); + expect(share.failure).toBe('no-render'); + expect(await filesOf(share.id)).toBeNull(); + }); + + it('a head timeout fails the share', async () => { + const socket = await daemon(); + const res = await create({ runId, format: 'mp4' }).expect(202); + const prepare = await socket.nextShare(); + socket.send({ + type: 'share.prepared', + requestId: prepare.requestId, + chapters: [], + posterSize: POSTER.length, + }); + await socket.nextOpen(); + t.clock.advance(HEAD_TIMEOUT_MS); + t.app.get(VideoRelay).tick(); + const share = await settled(res.body.id, 'failed'); + expect(share.failure).toBe('runner-timeout'); + expect(await filesOf(share.id)).toBeNull(); + }); + + it('a dropped socket mid-file fails the share and leaves no .part', async () => { + const socket = await daemon(); + const res = await create({ runId, format: 'mp4' }).expect(202); + const prepare = await socket.nextShare(); + socket.send({ + type: 'share.prepared', + requestId: prepare.requestId, + chapters: [], + posterSize: POSTER.length, + }); + const poster = await socket.nextOpen(); + socket.serve(poster.streamId, POSTER); + const render = await socket.nextOpen(); + socket.send({ + type: 'video.head', + streamId: render.streamId, + size: FILE.length, + start: 0, + end: FILE.length - 1, + }); + socket.sendChunk(render.streamId, FILE.subarray(0, 1000)); + await socket.roundTrip(); + await eventually(async () => + ((await filesOf(res.body.id)) ?? []).includes('file.mp4.part'), + ); + socket.ws.terminate(); + const share = await settled(res.body.id, 'failed'); + expect(share.failure).toBe('runner-offline'); + expect(await filesOf(share.id)).toBeNull(); + }); + }); + + describe('extend', () => { + it('adds 30 days, never beyond 90 days from now', async () => { + const id = await ready(); + const start = t.clock.now().getTime(); + const extend = () => + request(http).post(`/shares/${id}/extend`).set('Cookie', alice.cookie); + + const once = await extend().expect(200); + expect(new Date(once.body.expiresAt).getTime()).toBe(start + 60 * DAY_MS); + const twice = await extend().expect(200); + expect(new Date(twice.body.expiresAt).getTime()).toBe( + start + 90 * DAY_MS, + ); + const capped = await extend().expect(409); + expect(capped.body).toEqual({ error: 'at-max-expiry' }); + + t.clock.advance(10 * DAY_MS); + const later = await extend().expect(200); + expect(new Date(later.body.expiresAt).getTime()).toBe( + start + 100 * DAY_MS, + ); + }); + }); + + describe('authorization', () => { + it('hides every share of another account', async () => { + const id = await ready(); + for (const call of [ + request(http).get(`/shares/${id}`), + request(http).post(`/shares/${id}/extend`), + request(http).delete(`/shares/${id}`), + ]) { + const res = await call.set('Cookie', bob.cookie).expect(404); + expect(res.body).toEqual({ error: 'not-found' }); + } + const list = await request(http) + .get('/shares') + .set('Cookie', bob.cookie) + .expect(200); + expect(list.body.shares).toEqual([]); + const res = await create({ runId, format: 'webm' }, bob.cookie).expect( + 404, + ); + expect(res.body).toEqual({ error: 'not-found' }); + expect(await t.prisma.share.count({ where: { id } })).toBe(1); + }); + + it('lets a machine share only the runs it reported', async () => { + await daemon(); + const second = await pair(http, alice, 'Desktop'); + const bobs = await pair(http, bob, 'Bob laptop'); + const viaRunner = (by: Paired, body: Record<string, unknown>) => + request(http) + .post('/runner/shares') + .set('Authorization', `Bearer ${by.token}`) + .send(body); + + await viaRunner(bobs, { runId, format: 'mp4' }).expect(404); + await viaRunner(second, { runId, format: 'mp4' }).expect(404); + const res = await viaRunner(machine, { runId, format: 'mp4' }).expect( + 202, + ); + expect(res.body.status).toBe('uploading'); + + const read = (by: Paired) => + request(http) + .get(`/runner/shares/${res.body.id}`) + .set('Authorization', `Bearer ${by.token}`); + await read(machine).expect(200); + await read(second).expect(404); + await read(bobs).expect(404); + }); + }); + + describe('deletes', () => { + it('revokes a share: row and directory', async () => { + const id = await ready(); + await request(http) + .delete(`/shares/${id}`) + .set('Cookie', alice.cookie) + .expect(204); + expect(await t.prisma.share.count({ where: { id } })).toBe(0); + expect(await filesOf(id)).toBeNull(); + await request(http) + .delete(`/shares/${id}`) + .set('Cookie', alice.cookie) + .expect(404); + }); + + it('a run delete takes its shares and their files', async () => { + const id = await ready(); + await request(http) + .delete(`/runs/${runId}`) + .set('Cookie', alice.cookie) + .expect(204); + expect(await t.prisma.share.count({ where: { id } })).toBe(0); + expect(await filesOf(id)).toBeNull(); + }); + + it('a bulk run delete takes their shares and files', async () => { + const id = await ready(); + const { projectId } = await t.prisma.run.findUniqueOrThrow({ + where: { id: runId }, + }); + await request(http) + .post(`/projects/${projectId}/runs/delete`) + .set('Cookie', alice.cookie) + .send({ runIds: [runId] }) + .expect(200); + expect(await t.prisma.share.count({ where: { id } })).toBe(0); + expect(await filesOf(id)).toBeNull(); + }); + + it('a project delete takes its shares and files', async () => { + const id = await ready(); + const { projectId } = await t.prisma.run.findUniqueOrThrow({ + where: { id: runId }, + }); + await request(http) + .delete(`/projects/${projectId}`) + .set('Cookie', alice.cookie) + .expect(204); + expect(await t.prisma.share.count({ where: { id } })).toBe(0); + expect(await filesOf(id)).toBeNull(); + }); + + it('an account delete takes its shares and files', async () => { + const id = await ready(); + await request(http) + .delete('/me') + .set('Cookie', alice.cookie) + .send({ email: alice.user.email }) + .expect(204); + expect(await t.prisma.share.count({ where: { id } })).toBe(0); + expect(await filesOf(id)).toBeNull(); + }); + + it('deleting the run files on the machine leaves the share', async () => { + const id = await ready(); + const socket = sockets[0]; + const deleting = request(http) + .delete(`/runs/${runId}/artifacts`) + .set('Cookie', alice.cookie) + .then((res) => res.status); + const ask = await socket.nextDelete(); + socket.send({ type: 'artifacts.deleted', requestId: ask.requestId }); + expect(await deleting).toBe(204); + expect((await shareOf(id)).status).toBe('ready'); + expect(await filesOf(id)).toEqual(['file.mp4', 'poster.jpg']); + }); + }); + + describe('sweeper', () => { + /** A share row with a directory, as an upload would have left it. */ + async function seed( + format: string, + fields: { + status?: 'uploading' | 'ready'; + expiresAt?: Date; + createdAt?: Date; + }, + files: string[], + ): Promise<string> { + const share = await t.prisma.share.create({ + data: { + token: generateToken(), + userId: alice.user.id, + runId, + format, + title: TITLE, + status: fields.status ?? 'ready', + expiresAt: + fields.expiresAt ?? new Date(t.clock.now().getTime() + DAY_MS), + ...(fields.createdAt ? { createdAt: fields.createdAt } : {}), + }, + }); + await mkdir(join(dir, share.id), { recursive: true }); + for (const name of files) { + await writeFile(join(dir, share.id, name), 'x'); + } + return share.id; + } + + it('deletes expired and orphaned files, fails stale uploads, marks lost', async () => { + const now = t.clock.now().getTime(); + const expired = await seed('mp4', { expiresAt: new Date(now - 1000) }, [ + 'file.mp4', + 'poster.jpg', + ]); + const stale = await seed( + 'webm', + { status: 'uploading', createdAt: new Date(now - 16 * 60 * 1000) }, + ['file.webm.part'], + ); + const lost = await seed('gif', {}, ['poster.jpg']); + const orphan = 'cl0rphan0000000000000000'; + await mkdir(join(dir, orphan)); + await writeFile(join(dir, 'README'), 'not a share'); + + const sweeper = new ShareSweeper( + t.prisma, + t.app.get(ShareStorage), + t.clock, + ); + await sweeper.sweep(true); + + expect(await t.prisma.share.count({ where: { id: expired } })).toBe(0); + expect(await filesOf(expired)).toBeNull(); + expect( + await t.prisma.share.findUniqueOrThrow({ where: { id: stale } }), + ).toMatchObject({ status: 'failed', failure: 'timed-out' }); + expect(await filesOf(stale)).toBeNull(); + expect( + (await t.prisma.share.findUniqueOrThrow({ where: { id: lost } })) + .status, + ).toBe('lost'); + expect(await filesOf(orphan)).toBeNull(); + expect(await readdir(dir)).toContain('README'); + }); + + it('marks nothing lost outside the boot pass', async () => { + const lost = await seed('gif', {}, []); + const sweeper = new ShareSweeper( + t.prisma, + t.app.get(ShareStorage), + t.clock, + ); + await sweeper.sweep(false); + expect( + (await t.prisma.share.findUniqueOrThrow({ where: { id: lost } })) + .status, + ).toBe('ready'); + }); + }); + + describe('logging', () => { + it('never logs the token, the password, the title or the description', async () => { + const lines: string[] = []; + const spy = jest + .spyOn(Logger.prototype, 'log') + .mockImplementation((message: unknown) => { + lines.push(String(message)); + }); + try { + const socket = await daemon(); + const res = await create({ + runId, + format: 'mp4', + password: PASSWORD, + }).expect(202); + await serveShare(socket); + await settled(res.body.id, 'ready'); + await request(http) + .post(`/shares/${res.body.id}/extend`) + .set('Cookie', alice.cookie) + .expect(200); + await request(http) + .delete(`/shares/${res.body.id}`) + .set('Cookie', alice.cookie) + .expect(204); + + const row = lines.join('\n'); + expect(row).toContain('share.create'); + expect(row).toContain('share.upload'); + expect(row).toContain('share.delete'); + const token = (res.body.url as string).split('/').pop() ?? ''; + for (const secret of [token, PASSWORD, TITLE, DESCRIPTION]) { + expect(row).not.toContain(secret); + } + } finally { + spy.mockRestore(); + } + }); + }); +}); diff --git a/apps/api/src/shares/shares.module.ts b/apps/api/src/shares/shares.module.ts new file mode 100644 index 00000000..624d8e5f --- /dev/null +++ b/apps/api/src/shares/shares.module.ts @@ -0,0 +1,22 @@ +import { Module } from '@nestjs/common'; +import { AuthModule } from '../auth/auth.module'; +import { RunnerModule } from '../runner/runner.module'; +import { VideosModule } from '../videos/videos.module'; +import { RunnerSharesController } from './runner-shares.controller'; +import { ShareStorageModule } from './share-storage'; +import { ShareSweeper } from './share-sweeper'; +import { ShareUploadService } from './share-upload.service'; +import { SharesController } from './shares.controller'; +import { SharesService } from './shares.service'; + +/** + * Share links (spec #347, ADR-0019): a copy of one render on the server's + * disk, pulled from the machine through the video relay. The public page + * and file are #348. + */ +@Module({ + imports: [AuthModule, RunnerModule, VideosModule, ShareStorageModule], + controllers: [SharesController, RunnerSharesController], + providers: [SharesService, ShareUploadService, ShareSweeper], +}) +export class SharesModule {} diff --git a/apps/api/src/shares/shares.service.ts b/apps/api/src/shares/shares.service.ts new file mode 100644 index 00000000..6f9da083 --- /dev/null +++ b/apps/api/src/shares/shares.service.ts @@ -0,0 +1,365 @@ +import { HttpException, HttpStatus, Injectable, Logger } from '@nestjs/common'; +import { Prisma, type Share, type ShareStatus } from '@prisma/client'; +import { PasswordHasher } from '../auth/password-hasher'; +import { generateToken } from '../auth/tokens'; +import { Clock } from '../common/clock'; +import { PrismaService } from '../database/prisma.service'; +import { parseRenders } from '../projects/projects.service'; +import { RunnerConnections } from '../runner/runner-connections.service'; +import { ShareConfig } from './share-config'; +import { ShareStorage } from './share-storage'; +import { ShareUploadService } from './share-upload.service'; +import { type CreateShareDto, DEFAULT_SHARE_LIFETIME } from './shares.dto'; + +const DAY_MS = 24 * 60 * 60 * 1000; +/** `POST /shares/:id/extend` adds this much (spec #347, Decision 5). */ +export const SHARE_EXTEND_DAYS = 30; +/** Never beyond this far from now. */ +export const SHARE_MAX_DAYS = 90; + +/** The statuses whose bytes count against the quota (Decision 3). */ +const LIVE: ShareStatus[] = ['uploading', 'ready']; + +type ShareWithRun = Share & { run: { projectId: string } }; + +const SHARE_INCLUDE = { + run: { select: { projectId: true } }, +} satisfies Prisma.ShareInclude; + +/** What the owner sees of a share. Never the token's hash, never the password. */ +export interface ShareView { + id: string; + url: string; + /** Null while a password is set: the file is served only after unlocking. */ + fileUrl: string | null; + runId: string; + projectId: string; + title: string; + format: string; + status: ShareStatus; + failure: string | null; + sizeBytes: number; + width: number | null; + height: number | null; + durationMs: number | null; + hasPassword: boolean; + views: number; + expiresAt: Date; + createdAt: Date; +} + +export interface SharesList { + shares: ShareView[]; + quota: { usedBytes: number; limitBytes: number; maxFileBytes: number }; +} + +/** `{ error, ...details }` with a status, as the runs API answers. */ +function shareError( + status: HttpStatus, + error: string, + details: Record<string, string | number> = {}, +): HttpException { + return new HttpException({ error, ...details }, status); +} + +function notFound(): HttpException { + return shareError(HttpStatus.NOT_FOUND, 'not-found'); +} + +/** + * Share links (spec #347, ADR-0019): created by the run's owner on the + * website or by the machine that reported the run, uploaded in the + * background, extended and revoked by the owner. Every query is scoped by + * the user: another account's share or run answers 404. + */ +@Injectable() +export class SharesService { + private readonly logger = new Logger(SharesService.name); + + constructor( + private readonly prisma: PrismaService, + private readonly connections: RunnerConnections, + private readonly uploads: ShareUploadService, + private readonly storage: ShareStorage, + private readonly config: ShareConfig, + private readonly hasher: PasswordHasher, + private readonly clock: Clock, + ) {} + + /** + * Every check before anything goes to the machine, then the row, then the + * upload in the background. `runnerId` limits the run to one that machine + * reported (Decision 7). + */ + async create( + userId: string, + body: CreateShareDto, + runnerId?: string, + ): Promise<ShareView> { + const run = await this.prisma.run.findFirst({ + where: { + id: body.runId, + project: { userId }, + ...(runnerId === undefined ? {} : { runnerId }), + }, + include: { runner: { select: { id: true, revokedAt: true } } }, + }); + if (!run) { + throw notFound(); + } + if (!run.formats.includes(body.format)) { + throw shareError(HttpStatus.CONFLICT, 'format-not-rendered'); + } + await this.replaceFailed(run.id, body.format); + if (run.artifactsDeletedAt) { + throw shareError(HttpStatus.CONFLICT, 'artifacts-deleted'); + } + // A revoked machine can never serve again: it counts as offline. + const machine = run.runner?.revokedAt === null ? run.runner : null; + if (!machine || !this.connections.isOnline(machine.id)) { + throw shareError(HttpStatus.CONFLICT, 'runner-offline'); + } + if (!this.connections.features(machine.id).includes('share')) { + throw shareError(HttpStatus.CONFLICT, 'runner-outdated'); + } + const render = + parseRenders(run.renders)?.find(({ format }) => format === body.format) ?? + null; + // Unknown until the head when the CLI did not report it: checked there. + const reserved = render?.sizeBytes ?? 0; + if (reserved > this.config.maxFileBytes) { + throw shareError(HttpStatus.PAYLOAD_TOO_LARGE, 'file-too-large', { + maxFileBytes: this.config.maxFileBytes, + }); + } + + const passwordHash = + body.password === undefined + ? null + : await this.hasher.hash(body.password); + const now = this.clock.now(); + const days = body.expiresInDays ?? DEFAULT_SHARE_LIFETIME; + const share = await this.insert(userId, run.id, reserved, { + token: generateToken(), + format: body.format, + title: run.scenarioName, + sizeBytes: reserved, + passwordHash, + expiresAt: new Date(now.getTime() + days * DAY_MS), + }); + this.log('share.create', share.id, run.id, 'uploading'); + + void this.uploads.upload({ + shareId: share.id, + userId, + runId: run.id, + format: body.format, + runnerId: machine.id, + render, + }); + return this.toView(share); + } + + /** Newest first, with what the quota counts now. */ + async list(userId: string): Promise<SharesList> { + const [shares, usedBytes] = await Promise.all([ + this.prisma.share.findMany({ + where: { userId, expiresAt: { gt: this.clock.now() } }, + include: SHARE_INCLUDE, + orderBy: [{ createdAt: 'desc' }, { id: 'desc' }], + }), + this.usedBytes(this.prisma, userId), + ]); + return { + shares: shares.map((share) => this.toView(share)), + quota: { + usedBytes, + limitBytes: this.config.quotaBytes, + maxFileBytes: this.config.maxFileBytes, + }, + }; + } + + async get(userId: string, id: string, runnerId?: string): Promise<ShareView> { + return this.toView(await this.findOwned(userId, id, runnerId)); + } + + /** 30 more days, never beyond 90 days from now (Decision 5). */ + async extend(userId: string, id: string): Promise<ShareView> { + const share = await this.findOwned(userId, id); + const now = this.clock.now().getTime(); + const expiresAt = Math.min( + Math.max(share.expiresAt.getTime(), now) + SHARE_EXTEND_DAYS * DAY_MS, + now + SHARE_MAX_DAYS * DAY_MS, + ); + if (expiresAt <= share.expiresAt.getTime()) { + throw shareError(HttpStatus.CONFLICT, 'at-max-expiry'); + } + const updated = await this.prisma.share.update({ + where: { id: share.id }, + data: { expiresAt: new Date(expiresAt) }, + include: SHARE_INCLUDE, + }); + this.log('share.extend', share.id, share.runId, 'extended'); + return this.toView(updated); + } + + /** The link stops working at once; the files go after the row (ADR-0019 §5). */ + async remove(userId: string, id: string): Promise<void> { + // Read first only for the log line: the delete itself is scoped again. + const share = await this.prisma.share.findFirst({ + where: { id, userId }, + select: { id: true, runId: true }, + }); + if (!share) { + throw notFound(); + } + const { count } = await this.prisma.share.deleteMany({ + where: { id: share.id, userId }, + }); + this.log( + 'share.delete', + share.id, + share.runId, + count === 1 ? 'deleted' : 'not-found', + ); + if (count !== 1) { + throw notFound(); + } + await this.storage.remove([share.id]); + } + + /** + * A failed or lost share of the same run and format is replaced by a new + * one: retrying must not need a revoke first. A live one is `share-exists`. + */ + private async replaceFailed(runId: string, format: string): Promise<void> { + const existing = await this.prisma.share.findUnique({ + where: { runId_format: { runId, format } }, + select: { id: true, status: true }, + }); + if (!existing) { + return; + } + if (LIVE.includes(existing.status)) { + throw shareError(HttpStatus.CONFLICT, 'share-exists', { + shareId: existing.id, + }); + } + const { count } = await this.prisma.share.deleteMany({ + where: { id: existing.id, status: { notIn: LIVE } }, + }); + if (count === 1) { + await this.storage.remove([existing.id]); + this.log('share.delete', existing.id, runId, 'replaced'); + } + } + + /** + * The quota check and the insert under the user's row lock, so two shares + * created at once cannot both pass it (Decision 3). + */ + private async insert( + userId: string, + runId: string, + reserved: number, + data: Omit<Prisma.ShareUncheckedCreateInput, 'userId' | 'runId'>, + ): Promise<ShareWithRun> { + try { + return await this.prisma.$transaction(async (tx) => { + await tx.$queryRaw`SELECT 1 FROM "User" WHERE "id" = ${userId} FOR UPDATE`; + const usedBytes = await this.usedBytes(tx, userId); + if (usedBytes + reserved > this.config.quotaBytes) { + throw shareError(HttpStatus.CONFLICT, 'quota-exceeded', { + usedBytes, + limitBytes: this.config.quotaBytes, + }); + } + return tx.share.create({ + data: { ...data, userId, runId }, + include: SHARE_INCLUDE, + }); + }); + } catch (error) { + // Another request shared the same run and format in between. + if ( + error instanceof Prisma.PrismaClientKnownRequestError && + error.code === 'P2002' + ) { + const existing = await this.prisma.share.findUnique({ + where: { runId_format: { runId, format: data.format } }, + select: { id: true }, + }); + throw shareError(HttpStatus.CONFLICT, 'share-exists', { + ...(existing ? { shareId: existing.id } : {}), + }); + } + throw error; + } + } + + private async usedBytes( + db: Prisma.TransactionClient, + userId: string, + ): Promise<number> { + const { _sum } = await db.share.aggregate({ + where: { userId, status: { in: LIVE } }, + _sum: { sizeBytes: true, posterBytes: true }, + }); + return (_sum.sizeBytes ?? 0) + (_sum.posterBytes ?? 0); + } + + /** An expired share is gone for its owner too, before the sweeper deletes it. */ + private async findOwned( + userId: string, + id: string, + runnerId?: string, + ): Promise<ShareWithRun> { + const share = await this.prisma.share.findFirst({ + where: { + id, + userId, + expiresAt: { gt: this.clock.now() }, + ...(runnerId === undefined ? {} : { run: { runnerId } }), + }, + include: SHARE_INCLUDE, + }); + if (!share) { + throw notFound(); + } + return share; + } + + private toView(share: ShareWithRun): ShareView { + const url = `${this.config.webUrl}/s/${share.token}`; + return { + id: share.id, + url, + fileUrl: share.passwordHash === null ? `${url}/file` : null, + runId: share.runId, + projectId: share.run.projectId, + title: share.title, + format: share.format, + status: share.status, + failure: share.failure, + sizeBytes: share.sizeBytes, + width: share.width, + height: share.height, + durationMs: share.durationMs, + hasPassword: share.passwordHash !== null, + views: share.views, + expiresAt: share.expiresAt, + createdAt: share.createdAt, + }; + } + + /** Decision 10: event, share id, run id, outcome. Nothing else. */ + private log( + event: string, + shareId: string, + runId: string | null, + outcome: string, + ): void { + this.logger.log(JSON.stringify({ event, shareId, runId, outcome })); + } +} diff --git a/apps/api/src/test/test-app.ts b/apps/api/src/test/test-app.ts index 48da4c89..13d58719 100644 --- a/apps/api/src/test/test-app.ts +++ b/apps/api/src/test/test-app.ts @@ -8,6 +8,7 @@ import { Clock } from '../common/clock'; import { PrismaService } from '../database/prisma.service'; import { Mailer } from '../mail/mailer'; import { RecordingMailer } from '../mail/recording.mailer'; +import { ShareSweeper } from '../shares/share-sweeper'; /** A clock the test moves by hand. */ export class FakeClock extends Clock { @@ -63,7 +64,12 @@ export async function createTestApp( .overrideProvider(Mailer) .useValue(mailer) .overrideProvider(Clock) - .useValue(clock); + .useValue(clock) + // The sweeper acts on every share in the shared test database: a pass on + // boot in each parallel suite would delete and mark other suites' shares. + // Its spec builds one and calls `sweep` itself. + .overrideProvider(ShareSweeper) + .useValue({}); for (const { provide, useValue } of overrides) { builder.overrideProvider(provide).useValue(useValue); } diff --git a/apps/api/src/users/account.service.ts b/apps/api/src/users/account.service.ts index b5e09c10..a9f98f80 100644 --- a/apps/api/src/users/account.service.ts +++ b/apps/api/src/users/account.service.ts @@ -3,6 +3,7 @@ import type { User } from '@prisma/client'; import { normalizeEmail } from '../auth/email'; import { PrismaService } from '../database/prisma.service'; import { RunnerConnections } from '../runner/runner-connections.service'; +import { ShareStorage } from '../shares/share-storage'; export const CONFIRMATION_MISMATCH = 'confirmation-mismatch'; @@ -17,6 +18,7 @@ export class AccountService { constructor( private readonly prisma: PrismaService, private readonly connections: RunnerConnections, + private readonly shareStorage: ShareStorage, ) {} /** `typedEmail` must be the account's email, trimmed, in any case. */ @@ -26,21 +28,32 @@ export class AccountService { throw new BadRequestException({ error: CONFIRMATION_MISMATCH }); } - const runnerIds = await this.prisma.$transaction(async (tx) => { - const runners = await tx.runner.findMany({ - where: { userId: user.id }, - select: { id: true }, - }); - // A plain column, no cascade: the codes this user approved. - await tx.deviceCode.deleteMany({ where: { approvedById: user.id } }); - await tx.user.delete({ where: { id: user.id } }); - return runners.map(({ id }) => id); - }); + const { runnerIds, shareIds } = await this.prisma.$transaction( + async (tx) => { + const runners = await tx.runner.findMany({ + where: { userId: user.id }, + select: { id: true }, + }); + const shares = await tx.share.findMany({ + where: { userId: user.id }, + select: { id: true }, + }); + // A plain column, no cascade: the codes this user approved. + await tx.deviceCode.deleteMany({ where: { approvedById: user.id } }); + await tx.user.delete({ where: { id: user.id } }); + return { + runnerIds: runners.map(({ id }) => id), + shareIds: shares.map(({ id }) => id), + }; + }, + ); // After the commit: a socket accepted meanwhile finds no row and closes. for (const runnerId of runnerIds) { this.connections.revoke(runnerId); } + // The shares cascaded with the user; their files go now (spec #347, Decision 9). + await this.shareStorage.remove(shareIds); this.logger.log( JSON.stringify({ event: 'account.deleted', userId: user.id }), ); diff --git a/apps/api/src/videos/runs.service.ts b/apps/api/src/videos/runs.service.ts index 3493b648..e6c3655e 100644 --- a/apps/api/src/videos/runs.service.ts +++ b/apps/api/src/videos/runs.service.ts @@ -6,7 +6,8 @@ import { toRunDetailView, } from '../projects/projects.service'; import { RunnerConnections } from '../runner/runner-connections.service'; -import type { RunOption } from '../runner/runner-socket'; +import type { Feature, RunOption } from '../runner/runner-socket'; +import { ShareStorage } from '../shares/share-storage'; const RUN_INCLUDE = { project: { select: { id: true, name: true } }, @@ -21,13 +22,15 @@ export interface RunPage { project: { id: string; name: string }; /** * Null when the machine was removed: deleted or revoked. `runOptions` is - * what it accepts on a start, none while offline (spec #325, Decision 7). + * what it accepts on a start, none while offline (spec #325, Decision 7); + * `features` what its daemon announced, as `share` (spec #347, Decision 6). */ machine: { id: string; name: string; online: boolean; runOptions: RunOption[]; + features: Feature[]; } | null; } @@ -44,6 +47,7 @@ export class RunsService { constructor( private readonly prisma: PrismaService, private readonly connections: RunnerConnections, + private readonly shareStorage: ShareStorage, ) {} async find(userId: string, id: string): Promise<OwnedRun> { @@ -68,6 +72,7 @@ export class RunsService { name: machine.name, online: this.connections.isOnline(machine.id), runOptions: [...this.connections.runOptions(machine.id)], + features: [...this.connections.features(machine.id)], }, }; } @@ -75,8 +80,14 @@ export class RunsService { /** * Deletes the run's row, never its files (spec #280, Decisions 2–4). One * statement: ownership and delete cannot race. Already gone is 404 too. + * Its shares cascade; their directories go once the row is gone (spec + * #347, Decision 9). */ async remove(userId: string, id: string): Promise<void> { + const shares = await this.prisma.share.findMany({ + where: { runId: id, run: { project: { userId } } }, + select: { id: true }, + }); const { count } = await this.prisma.run.deleteMany({ where: { id, project: { userId } }, }); @@ -88,6 +99,7 @@ export class RunsService { if (count !== 1) { throw runError(HttpStatus.NOT_FOUND, 'not-found'); } + await this.shareStorage.remove(shares.map((share) => share.id)); } } diff --git a/apps/api/src/videos/videos.integration.spec.ts b/apps/api/src/videos/videos.integration.spec.ts index eed877ae..d036e74f 100644 --- a/apps/api/src/videos/videos.integration.spec.ts +++ b/apps/api/src/videos/videos.integration.spec.ts @@ -700,6 +700,7 @@ describe('run video through the runner relay (integration)', () => { name: 'Laptop', online: true, runOptions: [], + features: [], }, }); }); @@ -711,6 +712,7 @@ describe('run video through the runner relay (integration)', () => { name: 'Laptop', online: false, runOptions: [], + features: [], }); }); @@ -725,6 +727,17 @@ describe('run video through the runner relay (integration)', () => { }); }); + it('shows the known features an online machine announced (spec #347)', async () => { + const socket = await daemon(); + socket.sync([], undefined, ['later', 'share']); + await socket.roundTrip(); + const res = await page().expect(200); + expect(res.body.machine).toMatchObject({ + online: true, + features: ['share'], + }); + }); + it('shows no run options once the announcing machine went offline', async () => { const socket = await daemon(); socket.sync([], ['formats']); diff --git a/apps/api/src/videos/videos.module.ts b/apps/api/src/videos/videos.module.ts index d666e803..8f1c5650 100644 --- a/apps/api/src/videos/videos.module.ts +++ b/apps/api/src/videos/videos.module.ts @@ -1,6 +1,7 @@ import { Module } from '@nestjs/common'; import { AuthModule } from '../auth/auth.module'; import { RunnerModule } from '../runner/runner.module'; +import { ShareStorageModule } from '../shares/share-storage'; import { ArtifactsService } from './artifacts.service'; import { RunsController } from './runs.controller'; import { RunsService } from './runs.service'; @@ -12,8 +13,10 @@ import { VideoRelay } from './video-relay.service'; * Deleting them goes through the same socket (spec #233). */ @Module({ - imports: [AuthModule, RunnerModule], + imports: [AuthModule, RunnerModule, ShareStorageModule], controllers: [RunsController], providers: [RunsService, VideoRelay, ArtifactsService], + // The share upload pulls through the same relay (spec #347, Decision 4). + exports: [VideoRelay], }) export class VideosModule {} From 3a80d440229b7f36d590f7b5d96db048120ccd71 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 13:54:41 +0100 Subject: [PATCH 13/71] chore(deploy): mount a shares volume for the API on staging and production The API image creates /data/shares owned by node so a new named volume starts writable. Both stacks mount the shares volume there, set SHARE_DIR, and document the file limit and the quota in their env examples. deploy/README.md explains the volume, the limits, the sweeper and that shared videos are not backed up. --- apps/api/Dockerfile | 4 ++++ deploy/README.md | 21 +++++++++++++++++++++ deploy/production/docker-compose.yml | 5 +++++ deploy/production/env/api.env.example | 4 ++++ deploy/staging/docker-compose.yml | 5 +++++ deploy/staging/env/api.env.example | 4 ++++ 6 files changed, 43 insertions(+) diff --git a/apps/api/Dockerfile b/apps/api/Dockerfile index f5546aaa..5145378c 100644 --- a/apps/api/Dockerfile +++ b/apps/api/Dockerfile @@ -52,6 +52,10 @@ COPY --from=builder --chown=node:node /app/node_modules node_modules/ COPY --from=builder --chown=node:node /app/packages/shared packages/shared/ COPY --from=builder --chown=node:node /app/apps/api apps/api/ +# The shares volume mounts here; a new named volume copies this directory's +# owner, so the API can write to it as `node` (spec #347). +RUN mkdir -p /data/shares && chown node:node /data/shares + USER node WORKDIR /app/apps/api diff --git a/deploy/README.md b/deploy/README.md index 87b39c84..b92a16d9 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -273,6 +273,26 @@ The app asks for `read:user user:email` only, and keeps no GitHub token. The client secret also signs the short-lived `df_oauth` cookie, so rotating it only fails sign-ins that are in flight. +### Shared videos on staging + +A share link (ADR-0019, spec #347) keeps a copy of one render and its poster +on the server, so the link plays while the Runner is offline. The API writes +them to `SHARE_DIR`, which `docker-compose.yml` sets to `/data/shares`: the +named volume `demoflow-staging_shares`. The image creates that directory +owned by `node`, so a new volume starts writable. + +- **Limits.** `SHARE_MAX_FILE_BYTES` (default 200 MB) caps one render, and + `SHARE_USER_QUOTA_BYTES` (default 2 GB) caps one account's shares, posters + included. Both are in `env/api.env`; a change needs an API restart. A value + that is not a positive whole number stops the API at boot. +- **Cleanup.** Every 10 minutes, and at boot, the API deletes expired shares + and their files, fails uploads stuck for 15 minutes, and removes directories + no share row points at. At boot it also marks a ready share whose file is + missing as lost. Each pass logs one `share.sweep` line. +- **Not backed up.** Losing the volume loses every shared video; the rows + turn `lost` at the next boot and their owners share again. Watch its size + with `docker system df -v | grep shares`. + ## Production — https://demoflow.luna-realm.com Every push to `main` runs the pipeline. Once `check`, `build` and the full @@ -297,6 +317,7 @@ nothing with it: | Compose project | `demoflow-staging` | `demoflow-production` | | Network | `demoflow-staging_staging` | `demoflow-production` | | Postgres volume | `demoflow-staging_pgdata` | `demoflow-production_pgdata` | +| Shares volume | `demoflow-staging_shares` | `demoflow-production_shares` | | Containers | `demoflow-staging-*` | `demoflow-production-*` | | Images | `demoflow-{api,web}:staging` | `demoflow-{api,web}:production` | | Tunnel | `demoflow-app` | `demoflow-prod` | diff --git a/deploy/production/docker-compose.yml b/deploy/production/docker-compose.yml index 24badb8f..7d0d77ef 100644 --- a/deploy/production/docker-compose.yml +++ b/deploy/production/docker-compose.yml @@ -49,6 +49,10 @@ services: env_file: ./env/api.env environment: DATABASE_URL: postgresql://postgres:${POSTGRES_PASSWORD}@postgres:5432/demoflow?schema=public + SHARE_DIR: /data/shares + # Shared videos and posters (spec #347). Not backed up. + volumes: + - shares:/data/shares depends_on: postgres: { condition: service_healthy } mem_limit: 1g @@ -97,6 +101,7 @@ services: # Compose names it demoflow-production_pgdata: never staging's volume. volumes: pgdata: + shares: networks: production: diff --git a/deploy/production/env/api.env.example b/deploy/production/env/api.env.example index 9f9d2c56..6a03463e 100644 --- a/deploy/production/env/api.env.example +++ b/deploy/production/env/api.env.example @@ -18,3 +18,7 @@ MAIL_TRANSPORT=log # https://demoflow.luna-realm.com/api/auth/github/callback GITHUB_CLIENT_ID= GITHUB_CLIENT_SECRET= +# Share links (deploy/README.md, "Shared videos on staging"). SHARE_DIR comes +# from docker-compose.yml: the `shares` volume at /data/shares. +SHARE_MAX_FILE_BYTES=209715200 +SHARE_USER_QUOTA_BYTES=2147483648 diff --git a/deploy/staging/docker-compose.yml b/deploy/staging/docker-compose.yml index 9723ad86..6ba2b3c2 100644 --- a/deploy/staging/docker-compose.yml +++ b/deploy/staging/docker-compose.yml @@ -45,6 +45,10 @@ services: env_file: ./env/api.env environment: DATABASE_URL: postgresql://postgres:${POSTGRES_PASSWORD}@postgres:5432/demoflow?schema=public + SHARE_DIR: /data/shares + # Shared videos and posters (spec #347). Not backed up. + volumes: + - shares:/data/shares depends_on: postgres: { condition: service_healthy } mem_limit: 1g @@ -92,6 +96,7 @@ services: volumes: pgdata: + shares: networks: staging: diff --git a/deploy/staging/env/api.env.example b/deploy/staging/env/api.env.example index 004baa92..27b0237a 100644 --- a/deploy/staging/env/api.env.example +++ b/deploy/staging/env/api.env.example @@ -19,3 +19,7 @@ MAIL_TRANSPORT=log # https://demoflow-app.luna-realm.com/api/auth/github/callback GITHUB_CLIENT_ID= GITHUB_CLIENT_SECRET= +# Share links (deploy/README.md, "Shared videos on staging"). SHARE_DIR comes +# from docker-compose.yml: the `shares` volume at /data/shares. +SHARE_MAX_FILE_BYTES=209715200 +SHARE_USER_QUOTA_BYTES=2147483648 From fcbaeedcf6bb34d854937ac86b77eaf8fe1c132d Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 14:03:53 +0100 Subject: [PATCH 14/71] feat(cli): demoflow run --check runs and verifies without recording or rendering A check runs one scenario, or with no scenario every scenario of the project against one start of the app, with record: false and no render. It prints a line per scenario and the totals (or one JSON object with --json), exits 0 when every run passed and 1 otherwise, and reports each run with kind: 'check'. --format, --headed, --run-id in a pass and --exclude beside a scenario are refused before anything runs (spec 360). --- apps/cli/src/commands/errors.ts | 4 +- apps/cli/src/commands/output.ts | 38 +++ apps/cli/src/commands/progress.ts | 24 ++ apps/cli/src/commands/run.ts | 281 ++++++++++++++++++----- apps/cli/src/main.ts | 33 ++- apps/cli/src/runs-report/report.ts | 8 +- apps/cli/test/commands/check-run.spec.ts | 264 +++++++++++++++++++++ apps/cli/test/runs-report/report.spec.ts | 27 +++ 8 files changed, 616 insertions(+), 63 deletions(-) create mode 100644 apps/cli/test/commands/check-run.spec.ts diff --git a/apps/cli/src/commands/errors.ts b/apps/cli/src/commands/errors.ts index 3bff6020..af16e249 100644 --- a/apps/cli/src/commands/errors.ts +++ b/apps/cli/src/commands/errors.ts @@ -14,7 +14,9 @@ export type CommandErrorCode = | 'no-recording' | 'invalid-port' | 'app-already-running' - | 'fresh-app-needs-dev-command'; + | 'fresh-app-needs-dev-command' + | 'missing-scenario' + | 'check-flag'; /** Bad input to a command (spec 5: exit 2) that is not a config problem. */ export class CommandError extends Error { diff --git a/apps/cli/src/commands/output.ts b/apps/cli/src/commands/output.ts index cde7e592..70892696 100644 --- a/apps/cli/src/commands/output.ts +++ b/apps/cli/src/commands/output.ts @@ -40,3 +40,41 @@ function failedStep(error: NonNullable<Stage['error']>): string { : ` (repeat steps[${error.origin.repeatIndex}], iteration ${error.origin.iteration + 1})`; return `step ${error.stepIndex}${origin}: `; } + +/** + * One line per scenario of a check (spec 360, Decision 4): its verdict, its + * id and, when it failed, the first failed stage with its error. + */ +export function formatCheckLine(result: RunResult): string { + const verdict = result.status === 'failed' ? 'failed' : 'passed'; + const line = `${verdict} ${result.scenarioId}`; + if (result.status !== 'failed') return `${line}\n`; + const failed = STAGE_NAMES.find( + (name) => result.stages[name].status === 'failed', + ); + if (failed === undefined) return `${line}\n`; + const { error } = result.stages[failed]; + const detail = + error === undefined + ? '' + : ` ${failedStep(error)}${firstLine(error.message)}`; + return `${line} ${failed}:${detail}\n`; +} + +/** `--check --json`: every run of the check, each with its `runDir`. */ +export function formatCheckJson( + runs: readonly { result: RunResult; runDir: string }[], +): string { + const failed = runs.filter(({ result }) => result.status === 'failed').length; + return `${JSON.stringify({ + check: true, + passed: runs.length - failed, + failed, + runs: runs.map(({ result, runDir }) => ({ ...result, runDir })), + })}\n`; +} + +function firstLine(text: string): string { + const end = text.indexOf('\n'); + return end === -1 ? text : text.slice(0, end); +} diff --git a/apps/cli/src/commands/progress.ts b/apps/cli/src/commands/progress.ts index e4c52084..c31ac06c 100644 --- a/apps/cli/src/commands/progress.ts +++ b/apps/cli/src/commands/progress.ts @@ -49,3 +49,27 @@ export function progressObserver(io: Io): EngineObserver { }, }; } + +/** + * `demoflow run --check --progress` (spec 360): one line as each scenario of + * a check pass starts, `run` 1-based. The daemon restarts its per-scenario + * time limit on it. + */ +export interface CheckProgress { + run: number; + runs: number; +} + +/** The check line as printed on stdout, newline included. */ +export function formatCheckProgress(progress: CheckProgress): string { + return `${JSON.stringify({ type: 'progress', phase: 'check', ...progress })}\n`; +} + +/** Writes a check line; best effort, like {@link emitProgress}. */ +export function emitCheckProgress(io: Io, progress: CheckProgress): void { + try { + io.stdout(formatCheckProgress(progress)); + } catch { + // Progress is best effort. + } +} diff --git a/apps/cli/src/commands/run.ts b/apps/cli/src/commands/run.ts index 921b48cf..4fc41b6e 100644 --- a/apps/cli/src/commands/run.ts +++ b/apps/cli/src/commands/run.ts @@ -6,6 +6,7 @@ import { parsePort, type RenderFormat, type RunResult, + type Scenario, } from '@demoflow/core'; import { createCaptureObserver, @@ -28,11 +29,14 @@ import { loadGlobalConfig, PROJECT_CONFIG_FILE, projectFragments, + projectRootAbove, projectRootAt, resolveHome, runDir as runDirFor, scenarioId, } from '../config/index.ts'; +import { nodeLaunchFs } from '../runner/launch/checks.ts'; +import { LIST_MAX_SCENARIOS, listScenarios } from '../runner/launch/list.ts'; import { defaultReportDeps, type ReportDeps, @@ -42,8 +46,17 @@ import { type BrowserDeps, ensureChromium } from './browser.ts'; import { CommandError, EXIT_STAGE_FAILED } from './errors.ts'; import { exitCodeFor } from './exit.ts'; import type { Io } from './io.ts'; -import { formatJson, formatSummary } from './output.ts'; -import { emitProgress, progressObserver } from './progress.ts'; +import { + formatCheckJson, + formatCheckLine, + formatJson, + formatSummary, +} from './output.ts'; +import { + emitCheckProgress, + emitProgress, + progressObserver, +} from './progress.ts'; import { renderPlanOptions } from './render.ts'; import { assertSafeRunId, generateRunId } from './run-id.ts'; import { loadScenario } from './scenario-file.ts'; @@ -66,6 +79,10 @@ export interface RunFlags { project?: string; /** Hidden: one JSON progress line on stdout per phase change and step (spec 302). */ progress?: boolean; + /** `--check`: run and verify, record and render nothing (spec 360). */ + check?: boolean; + /** `--exclude`: a scenario id a check pass leaves out, repeatable (spec 360). */ + exclude?: string[]; } export interface RunDeps { @@ -76,29 +93,59 @@ export interface RunDeps { browser?: BrowserDeps; /** The report to the server after the run; the real one by default. */ report?: ReportDeps; + /** Starts `devCommand`; the real start by default. */ + startApp?: typeof startApp; } export function defaultRunDeps(): RunDeps { return { host: currentHost(), cwd: process.cwd(), runId: generateRunId }; } +/** A scenario about to run, and the run it became. */ +interface Planned { + file: string; + id: string; + scenario: Scenario; +} + +interface Finished { + result: RunResult; + runDir: string; + /** A render crash before the stage was recorded (an ordinary run only). */ + renderError?: unknown; +} + /** * `demoflow run <scenario>`: validate, load the config, resolve the home, run * the engine, render, print. Input errors are thrown (exit 2); a finished run * returns its exit code. + * + * With `--check` (spec 360) nothing is recorded or rendered, and without a + * scenario every scenario of the project runs, one after another, against one + * start of the app: a check pass. */ export async function runCommand( - file: string, + file: string | undefined, flags: RunFlags, io: Io, deps: RunDeps = defaultRunDeps(), ): Promise<number> { const { host } = deps; + const check = flags.check === true; + if (check) assertCheckFlags(file, flags); + else if (file === undefined) { + throw new CommandError( + 'missing-scenario', + 'a scenario is required; only --check runs every scenario of the project', + ); + } const port = flags.port === undefined ? undefined : portFlag(flags.port); const root = - flags.project === undefined - ? findProjectRoot(file) - : projectRootAt(path.resolve(deps.cwd, flags.project)); + flags.project !== undefined + ? projectRootAt(path.resolve(deps.cwd, flags.project)) + : file !== undefined + ? findProjectRoot(file) + : projectRootAbove(deps.cwd); const app = loadAppConfig(root, { port, baseUrl: flags.baseUrl, @@ -118,32 +165,39 @@ export async function runCommand( projectConfig: config, globalConfig: loadGlobalConfig(host), }); - const { scenario, warnings } = loadScenario( - file, - projectFragments(root, config.fragmentsDir), - ); - for (const warning of warnings) { - io.stderr(`warning ${warning.path}: ${warning.message}\n`); - } + const files = + file !== undefined + ? [file] + : await passFiles(root, config.fragmentsDir, flags.exclude ?? [], io); + const fragments = projectFragments(root, config.fragmentsDir); + const planned: Planned[] = files.map((scenarioFile) => { + const { scenario, warnings } = loadScenario(scenarioFile, fragments); + for (const warning of warnings) { + io.stderr(`warning ${warning.path}: ${warning.message}\n`); + } + return { file: scenarioFile, id: scenarioId(root, scenarioFile), scenario }; + }); - const runId = flags.runId ?? deps.runId(); - if (flags.runId !== undefined) assertSafeRunId(flags.runId); - const runDir = runDirFor(home, runId, host.platform); - if (flags.runId !== undefined && existsSync(runDir)) { - throw new CommandError( - 'invalid-run-id', - `run directory already exists: ${runDir}`, - ); + if (flags.runId !== undefined) { + assertSafeRunId(flags.runId); + const runDir = runDirFor(home, flags.runId, host.platform); + if (existsSync(runDir)) { + throw new CommandError( + 'invalid-run-id', + `run directory already exists: ${runDir}`, + ); + } } const fresh = flags.freshApp === true; if (fresh) await assertNoAppRunning(config.devCommand); // After every input check: a bad scenario never costs a browser download // or an app start. The start overlaps with the download; the app's output - // is kept and shown only if the start fails. + // is kept and shown only if the start fails. A check pass starts the app + // once for all its scenarios (spec 360, Decision 3). const progress = flags.progress === true; if (progress) emitProgress(io, { phase: 'app' }); const tail = outputTail(); - const starting: Promise<Started> = startApp(config, root, { + const starting: Promise<Started> = (deps.startApp ?? startApp)(config, root, { log: (text) => tail.push(text), env: app.port === undefined ? undefined : { PORT: String(app.port) }, fresh, @@ -167,43 +221,76 @@ export async function runCommand( return EXIT_STAGE_FAILED; } const started = await starting; - if ('error' in started) { - if (!(started.error instanceof AppStartError)) throw started.error; - return await reportAppNotReady({ - error: started.error, - output: tail.lines(), - scenarioName: scenario.name, - scenarioFile: scenarioId(root, file), - runId, - runDir, - json: flags.json === true, - io, - }); + if ('error' in started && !(started.error instanceof AppStartError)) { + throw started.error; + } + const output = tail.lines(); + if ('error' in started && output.length > 0) { + io.stderr(`${output.join('\n')}\n`); + } + const finished: Finished[] = []; + for (const [index, run] of planned.entries()) { + if (check && progress) { + emitCheckProgress(io, { run: index + 1, runs: planned.length }); + } + const runId = flags.runId ?? deps.runId(); + const runDir = runDirFor(home, runId, host.platform); + const done: Finished = + 'error' in started + ? { + result: await writeAppNotReady({ + error: started.error as AppStartError, + output, + scenarioName: run.scenario.name, + scenarioFile: run.id, + runId, + runDir, + }), + runDir, + } + : await execute(run, runId, runDir); + // A run whose app never answered was never reported before spec 360; a + // check reports it, so the stale state sees a readiness failure too. + if (!('error' in started) || check) { + await reportRun( + { root, runDir, result: done.result, check }, + deps.report ?? defaultReportDeps(host), + ); + } + if (check && flags.json !== true) { + io.stdout(formatCheckLine(done.result)); + } + finished.push(done); } - return await execute(); + return check ? concludeCheck(finished) : concludeRun(finished); } finally { process.off('SIGINT', onInterrupt); process.off('SIGTERM', onTerminate); await stopApp(); } - async function execute(): Promise<number> { - io.stderr(`Running ${scenarioId(root, file)} (${runId})\n`); + async function execute( + run: Planned, + runId: string, + runDir: string, + ): Promise<Finished> { + io.stderr(`${check ? 'Checking' : 'Running'} ${run.id} (${runId})\n`); // Secrets come from the process environment only (spec 5). - await runScenario(scenario, { + await runScenario(run.scenario, { runDir, baseUrl: flags.baseUrl ?? config.baseUrl, allowedOrigins: config.allowedOrigins, env: host.env, headless: flags.headed !== true, + record: !check, observers: [ - createCaptureObserver({ scenarioId: scenarioId(root, file), runId }), + createCaptureObserver({ scenarioId: run.id, runId }), ...(progress ? [progressObserver(io)] : []), ], }); // A recorded run is rendered whatever the verdict: the video of a failed - // verification is the evidence (ADR-0004 §4). + // verification is the evidence (ADR-0004 §4). A check recorded nothing. let renderError: unknown; if (existsSync(path.join(runDir, RUN_FILES.video))) { io.stderr('Rendering\n'); @@ -211,7 +298,7 @@ export async function runCommand( try { const plan = await buildRenderPlan( runDir, - renderPlanOptions(config, flags.format, scenario.description), + renderPlanOptions(config, flags.format, run.scenario.description), ); await ffmpegRenderer.render(runDir, plan); } catch (error) { @@ -227,21 +314,106 @@ export async function runCommand( : String(renderError); io.stderr(`rendering failed: ${reason}\n`); } + return { result, runDir, renderError }; + } + + /** An ordinary run: its result as before spec 360, and its exit code. */ + function concludeRun([done]: Finished[]): number { + if (done === undefined) return EXIT_STAGE_FAILED; + const { result, runDir, renderError } = done; io.stdout( flags.json === true ? formatJson(result, runDir) : formatSummary(result, runDir), ); - await reportRun( - { root, runDir, result }, - deps.report ?? defaultReportDeps(host), - ); const code = exitCodeFor(result); // A render crash before the stage was recorded must not read as success. return code === 0 && renderError !== undefined ? EXIT_STAGE_FAILED : code; } + + /** Spec 360, Decision 4: every run, then `0` when all passed, else `1`. */ + function concludeCheck(finished: Finished[]): number { + const failed = finished.filter( + ({ result }) => result.status === 'failed', + ).length; + io.stdout( + flags.json === true + ? formatCheckJson(finished) + : `${finished.length - failed} passed, ${failed} failed\n`, + ); + return failed === 0 ? 0 : EXIT_CHECK_FAILED; + } } +/** A check run or pass that failed: any run of it failed, whatever the stage. */ +export const EXIT_CHECK_FAILED = 1; + +/** + * Spec 360, Decision 2: what a check refuses before anything runs. A check + * renders nothing and nobody watches it. + */ +function assertCheckFlags(file: string | undefined, flags: RunFlags): void { + if (flags.format !== undefined) { + throw new CommandError( + 'check-flag', + '--check renders nothing: --format cannot be used with it', + ); + } + if (flags.headed === true) { + throw new CommandError( + 'check-flag', + '--check runs headless: --headed cannot be used with it', + ); + } + if (file === undefined && flags.runId !== undefined) { + throw new CommandError( + 'check-flag', + '--run-id names one run: give a scenario, or leave --run-id out of a check pass', + ); + } + if (file !== undefined && (flags.exclude ?? []).length > 0) { + throw new CommandError( + 'check-flag', + '--exclude applies to a check pass: leave out the scenario, or --exclude', + ); + } +} + +/** + * The scenarios of a check pass: the daemon's own listing (spec 247), sorted + * by id, minus `--exclude`. An excluded id that is no scenario is ignored: a + * deleted scenario must not break a schedule. An id may leave out the + * leading `demoflow/`. + */ +async function passFiles( + root: string, + fragmentsDir: string | undefined, + exclude: readonly string[], + io: Io, +): Promise<string[]> { + const listing = await listScenarios(root, nodeLaunchFs, fragmentsDir); + const excluded = new Set( + exclude.map((id) => + id.startsWith(SCENARIOS_PREFIX) ? id : `${SCENARIOS_PREFIX}${id}`, + ), + ); + if (listing.skipped > 0) { + io.stderr( + `warning: ${listing.skipped} scenario file(s) left out: not valid (run demoflow validate)\n`, + ); + } + if (listing.truncated) { + io.stderr( + `warning: the project has more scenarios than a check pass runs (${LIST_MAX_SCENARIOS})\n`, + ); + } + return listing.scenarios + .filter((scenario) => !excluded.has(scenario.id)) + .map((scenario) => path.join(root, ...scenario.id.split('/'))); +} + +const SCENARIOS_PREFIX = 'demoflow/'; + type Started = { app: RunningApp } | { error: unknown }; /** `--port <n>`: a decimal integer from 1 to 65535, used or not (spec 337). */ @@ -282,24 +454,21 @@ async function assertNoAppRunning( /** * The app never answered, so the engine never ran: the CLI writes the run's * `result.json` itself — readiness failed with the app's last output, the - * other stages skipped (spec 5) — and prints it like any finished run. + * other stages skipped (spec 5) — and settles it like any finished run. */ -async function reportAppNotReady(input: { +async function writeAppNotReady(input: { error: AppStartError; output: string[]; scenarioName: string; scenarioFile: string; runId: string; runDir: string; - json: boolean; - io: Io; -}): Promise<number> { - const { error, output, runDir, io } = input; +}): Promise<RunResult> { + const { error, output, runDir } = input; const message = output.length === 0 ? error.message : `${error.message}\nLast output of devCommand:\n${output.join('\n')}`; - if (output.length > 0) io.stderr(`${output.join('\n')}\n`); const now = new Date().toISOString(); const skipped = { status: 'skipped' } as const; const pending = { status: 'pending' } as const; @@ -333,9 +502,5 @@ async function reportAppNotReady(input: { path.join(runDir, RUN_FILES.result), `${JSON.stringify(unsettled, null, 2)}\n`, ); - const result = await settleRun(runDir); - io.stdout( - input.json ? formatJson(result, runDir) : formatSummary(result, runDir), - ); - return exitCodeFor(result); + return settleRun(runDir); } diff --git a/apps/cli/src/main.ts b/apps/cli/src/main.ts index 26e05145..af8d845a 100644 --- a/apps/cli/src/main.ts +++ b/apps/cli/src/main.ts @@ -67,8 +67,13 @@ export async function main( program .command('run') - .description('Run a scenario and render its video') - .argument('<scenario>', 'path to a .demo.json file') + .description( + 'Run a scenario and render its video; with --check, run and verify only', + ) + .argument( + '[scenario]', + 'path to a .demo.json file; required unless --check, which then runs every scenario', + ) .option('--base-url <url>', 'override baseUrl from demoflow.config.json') .option( '--port <n>', @@ -88,6 +93,16 @@ export async function main( `a file to render, repeatable; replaces render.formats (${RENDER_FORMATS.join(', ')})`, ).argParser(collectFormat), ) + .option( + '--check', + 'run and verify against the live app, recording and rendering nothing (demoflow check only validates files)', + ) + .addOption( + new Option( + '--exclude <id>', + 'with --check and no scenario: leave out this scenario id, repeatable', + ).argParser(collectExclude), + ) .addOption(new Option('--run-id <id>', 'name the run directory').hideHelp()) .addOption(new Option('--project <dir>', 'the project root').hideHelp()) .addOption( @@ -98,7 +113,7 @@ export async function main( ) .action( async ( - scenario: string, + scenario: string | undefined, flags: { baseUrl?: string; port?: string; @@ -107,11 +122,19 @@ export async function main( headed?: boolean; json?: boolean; format?: RenderFormat[]; + check?: boolean; + exclude?: string[]; runId?: string; project?: string; progress?: boolean; }, + command: Command, ) => { + if (scenario === undefined && flags.check !== true) { + command.error("error: missing required argument 'scenario'", { + code: 'commander.missingArgument', + }); + } exitCode = await runCommand(scenario, flags, io); }, ); @@ -265,6 +288,10 @@ function collectFormat( return [...previous, format]; } +function collectExclude(value: string, previous: string[] = []): string[] { + return [...previous, value]; +} + function isCommanderError(error: unknown): error is CommanderError { return error instanceof CommanderError; } diff --git a/apps/cli/src/runs-report/report.ts b/apps/cli/src/runs-report/report.ts index 8438ce54..98dd4dd8 100644 --- a/apps/cli/src/runs-report/report.ts +++ b/apps/cli/src/runs-report/report.ts @@ -39,6 +39,8 @@ export interface RunReport { renders: ReportedRender[]; /** Decision 3: a failed run's first failed stage, its message redacted. */ failure?: { stage: StageName; message: string }; + /** Spec 360: `check` for a run of `demoflow run --check`; absent otherwise. */ + kind?: 'check'; } export interface ReportedRender { @@ -79,6 +81,7 @@ export function buildReport(input: { cliVersion: string; pathApi?: path.PlatformPath; home?: string; + check?: boolean; }): RunReport { const { root, result, cliVersion, pathApi = path, home = homedir() } = input; const failedStep = Object.values(result.stages) @@ -109,6 +112,8 @@ export function buildReport(input: { const failure = failureOf(result, { root, home, pathApi }); if (failure !== undefined) report.failure = failure; } + // An ordinary run sends no `kind`: an API before spec 360 refuses the field. + if (input.check === true) report.kind = 'check'; return report; } @@ -184,7 +189,7 @@ function projectIdOf(body: unknown): string | undefined { * `reported-runs.jsonl`, so the daemon can stream its video (spec 192). */ export async function reportRun( - input: { root: string; runDir: string; result: RunResult }, + input: { root: string; runDir: string; result: RunResult; check?: boolean }, deps: ReportDeps, ): Promise<void> { try { @@ -198,6 +203,7 @@ export async function reportRun( cliVersion: deps.version(), pathApi: pathFor(deps.host.platform), home: deps.host.homedir, + check: input.check, }); const response = await deps.fetch( `${apiBase(credentials.server)}/runner/runs`, diff --git a/apps/cli/test/commands/check-run.spec.ts b/apps/cli/test/commands/check-run.spec.ts new file mode 100644 index 00000000..f588253f --- /dev/null +++ b/apps/cli/test/commands/check-run.spec.ts @@ -0,0 +1,264 @@ +import { existsSync, readdirSync, readFileSync } from 'node:fs'; +import { cp, mkdtemp, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; +import type { RunResult } from '@demoflow/core'; +import { afterAll, beforeAll, describe, expect, it } from 'vitest'; +// Read-only helper of the engine's tests: serves the built fixture on an ephemeral port. +import { + type FixtureServer, + startFixtureServer, +} from '../../../../packages/engine/test/execute/fixture-server.ts'; +import { AppStartError } from '../../src/app/dev-server.ts'; +import { CommandError } from '../../src/commands/errors.ts'; +import type { Io } from '../../src/commands/io.ts'; +import { + type RunDeps, + type RunFlags, + runCommand, +} from '../../src/commands/run.ts'; + +const REPO = path.resolve( + path.dirname(fileURLToPath(import.meta.url)), + '../../../..', +); +const FIXTURE_SCENARIOS = path.join(REPO, 'apps/fixture/demoflow'); + +let fixture: FixtureServer; +let project: string; + +beforeAll(async () => { + fixture = await startFixtureServer(); + project = await mkdtemp(path.join(tmpdir(), 'demoflow-check-project-')); + await writeFile( + path.join(project, 'demoflow.config.json'), + JSON.stringify({ baseUrl: fixture.origin }), + ); + await cp(FIXTURE_SCENARIOS, path.join(project, 'demoflow'), { + recursive: true, + }); +}); + +afterAll(async () => { + await fixture.close(); + await rm(project, { recursive: true, force: true }); +}); + +/** An in-process `demoflow run` with a start hook that counts app starts. */ +async function harness(start?: RunDeps['startApp']) { + const home = await mkdtemp(path.join(tmpdir(), 'demoflow-check-home-')); + const io: Io & { out: string; err: string } = { + out: '', + err: '', + stdout: (text) => { + io.out += text; + }, + stderr: (text) => { + io.err += text; + }, + }; + let starts = 0; + let stops = 0; + let runs = 0; + const run = (file: string | undefined, flags: RunFlags) => + runCommand(file, flags, io, { + host: { + platform: process.platform, + env: { + DEMOFLOW_HOME: home, + DEMOFLOW_NO_REPORT: '1', + // landing, login and phone sign in; any password does. + FIXTURE_PASSWORD: 'correct horse', + }, + homedir: path.join(home, 'user'), + }, + cwd: project, + runId: () => `check-${++runs}`, + startApp: async (...args) => { + starts++; + if (start !== undefined) return start(...args); + return { + started: true, + stop: async () => { + stops++; + }, + }; + }, + }); + return { + io, + run, + home, + runsDir: path.join(home, 'runs'), + counts: () => ({ starts, stops }), + }; +} + +function scenario(name: string): string { + return path.join(project, 'demoflow', `${name}.demo.json`); +} + +function resultOf(runDir: string): RunResult { + return JSON.parse( + readFileSync(path.join(runDir, 'result.json'), 'utf8'), + ) as RunResult; +} + +async function refusal(promise: Promise<unknown>): Promise<CommandError> { + const error = await promise.then( + () => undefined, + (reason: unknown) => reason, + ); + expect(error).toBeInstanceOf(CommandError); + return error as CommandError; +} + +describe('demoflow run --check', () => { + it('runs and verifies one scenario, recording and rendering nothing', async () => { + const { io, run, runsDir } = await harness(); + const code = await run(scenario('customers'), { check: true }); + expect(code).toBe(0); + const runDir = path.join(runsDir, 'check-1'); + const result = resultOf(runDir); + expect(result.status).not.toBe('failed'); + expect(result.stages.recording.status).toBe('skipped'); + expect(result.stages.rendering.status).toBe('skipped'); + expect(result.stages.verification.status).toBe('passed'); + expect(result.renders).toEqual([]); + expect( + readdirSync(runDir).filter((file) => file.endsWith('.webm')), + ).toEqual([]); + expect(readdirSync(runDir).filter((file) => file.endsWith('.mp4'))).toEqual( + [], + ); + expect(io.out).toBe( + 'passed demoflow/customers.demo.json\n1 passed, 0 failed\n', + ); + }); + + it('fails the check of a failing scenario: exit 1, verification failed', async () => { + const { io, run, runsDir } = await harness(); + const code = await run(scenario('failing'), { check: true, json: true }); + expect(code).toBe(1); + const result = resultOf(path.join(runsDir, 'check-1')); + expect(result.status).toBe('failed'); + expect(result.stages.verification.status).toBe('failed'); + const printed = JSON.parse(io.out) as { + check: true; + passed: number; + failed: number; + runs: { scenarioId: string; status: string; runDir: string }[]; + }; + expect(printed).toMatchObject({ check: true, passed: 0, failed: 1 }); + expect(printed.runs.map((entry) => entry.scenarioId)).toEqual([ + 'demoflow/failing.demo.json', + ]); + }); + + it('runs every scenario of the project against one app start, leaving out the excluded', async () => { + const { io, run, runsDir, counts } = await harness(); + const code = await run(undefined, { + check: true, + exclude: [ + 'login.demo.json', + 'demoflow/failing.demo.json', + 'gone.demo.json', + ], + }); + expect(counts()).toEqual({ starts: 1, stops: 1 }); + const expected = [ + 'demoflow/customers-repeat.demo.json', + 'demoflow/customers.demo.json', + 'demoflow/landing.demo.json', + 'demoflow/masked-elements.demo.json', + 'demoflow/phone.demo.json', + 'demoflow/tour.demo.json', + ]; + const lines = io.out.trimEnd().split('\n'); + expect(lines.slice(0, -1).map((line) => line.split(/\s+/)[1])).toEqual( + expected, + ); + expect(lines.at(-1), io.out).toBe(`${expected.length} passed, 0 failed`); + expect(code).toBe(0); + for (const runDir of readdirSync(runsDir)) { + const result = resultOf(path.join(runsDir, runDir)); + expect(result.stages.recording.status).toBe('skipped'); + expect(result.renders).toEqual([]); + } + expect(readdirSync(runsDir)).toHaveLength(expected.length); + }, 180_000); + + it('prints one check progress line per scenario of a pass', async () => { + const { io, run } = await harness(); + await run(undefined, { + check: true, + progress: true, + json: true, + exclude: [ + 'login.demo.json', + 'customers-repeat.demo.json', + 'landing.demo.json', + 'masked-elements.demo.json', + 'phone.demo.json', + 'tour.demo.json', + ], + }); + const checks = io.out + .split('\n') + .filter((line) => line.includes('"phase":"check"')) + .map((line) => JSON.parse(line) as unknown); + expect(checks).toEqual([ + { type: 'progress', phase: 'check', run: 1, runs: 2 }, + { type: 'progress', phase: 'check', run: 2, runs: 2 }, + ]); + }, 60_000); + + it.each<[string, string | undefined, RunFlags]>([ + ['--format', 'customers', { format: ['gif'] }], + ['--headed', 'customers', { headed: true }], + ['--run-id in a pass', undefined, { runId: 'mine' }], + ['--exclude with a scenario', 'customers', { exclude: ['x.demo.json'] }], + ])('refuses %s: exit 2, nothing started or written', async (_, name, extra) => { + const { io, run, runsDir, counts } = await harness(); + const file = name === undefined ? undefined : scenario(name); + const error = await refusal(run(file, { check: true, ...extra })); + expect(error.code).toBe('check-flag'); + expect(error.exitCode).toBe(2); + expect(counts().starts).toBe(0); + expect(io.out).toBe(''); + expect(existsSync(runsDir)).toBe(false); + }); + + it('fails every scenario of a pass whose app never answered, each with its own result', async () => { + const { io, run, runsDir } = await harness(async () => { + throw new AppStartError('the app did not answer'); + }); + const code = await run(undefined, { + check: true, + exclude: [ + 'customers-repeat.demo.json', + 'landing.demo.json', + 'login.demo.json', + 'masked-elements.demo.json', + 'phone.demo.json', + 'tour.demo.json', + ], + }); + expect(code).toBe(1); + expect(readdirSync(runsDir).sort()).toEqual(['check-1', 'check-2']); + for (const runDir of ['check-1', 'check-2']) { + const result = resultOf(path.join(runsDir, runDir)); + expect(result.stages.readiness.status).toBe('failed'); + expect(result.stages.recording.status).toBe('skipped'); + } + expect(io.out).toMatch(/0 passed, 2 failed\n$/); + }); + + it('refuses a run with no scenario and no --check', async () => { + const { run } = await harness(); + const error = await refusal(run(undefined, {})); + expect(error.code).toBe('missing-scenario'); + expect(error.exitCode).toBe(2); + }); +}); diff --git a/apps/cli/test/runs-report/report.spec.ts b/apps/cli/test/runs-report/report.spec.ts index 5671e296..35873508 100644 --- a/apps/cli/test/runs-report/report.spec.ts +++ b/apps/cli/test/runs-report/report.spec.ts @@ -113,6 +113,23 @@ describe('buildReport', () => { }); }); + it('marks a check run with kind check, and an ordinary run with no kind (#360)', () => { + const check = buildReport({ + root: ROOT, + result: result(), + cliVersion: 'x', + check: true, + }); + expect(check.kind).toBe('check'); + const ordinary = buildReport({ + root: ROOT, + result: result(), + cliVersion: 'x', + check: false, + }); + expect('kind' in ordinary).toBe(false); + }); + it('is failed with the 0-based failed step', () => { const failed = result({ status: 'failed', @@ -382,6 +399,16 @@ describe('reportRun', () => { }); }); + it('sends kind check for a check run only (#360)', async () => { + pair(); + await reportRun({ ...input(), check: true }, deps(ok)); + await reportRun(input(), deps(ok)); + const bodies = calls.map( + (call) => JSON.parse(String(call.init.body)) as Record<string, unknown>, + ); + expect(bodies.map((body) => body.kind)).toEqual(['check', undefined]); + }); + it('sends the canonical root: a symlinked folder is the same project', async () => { pair(); const real = path.join(home, 'real'); From caa2270241f1da6ae83f015b261bd07155d2312b Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 14:07:20 +0100 Subject: [PATCH 15/71] feat(cli): the runner daemon runs a check pass the website starts launches.sync now carries checks: true when the daemon handles launches. A check.start is checked like a run.start: exactly requestId, rootPath and exclude, a registered root, and at most LIST_MAX_SCENARIOS valid scenario ids. A refusal answers check.error and spawns nothing; a valid request spawns run --check --json --progress --project <root> with one --exclude per id, answers check.started, then check.finished with the pass's counts. The 15-minute launch cap restarts with each scenario, and the whole pass is capped at two hours (spec 360, Decision 6). --- apps/cli/src/runner/connection.ts | 8 +- apps/cli/src/runner/launch/check.ts | 79 +++++ apps/cli/src/runner/launch/index.ts | 160 +++++++++- apps/cli/test/runner/connection.spec.ts | 8 +- apps/cli/test/runner/daemon-launch.spec.ts | 9 +- apps/cli/test/runner/launch-check.spec.ts | 336 +++++++++++++++++++++ 6 files changed, 587 insertions(+), 13 deletions(-) create mode 100644 apps/cli/src/runner/launch/check.ts create mode 100644 apps/cli/test/runner/launch-check.spec.ts diff --git a/apps/cli/src/runner/connection.ts b/apps/cli/src/runner/connection.ts index 38d1d803..328a4206 100644 --- a/apps/cli/src/runner/connection.ts +++ b/apps/cli/src/runner/connection.ts @@ -183,7 +183,13 @@ export class RunnerConnection { // Spec 326, Decision 1: a connection without a launcher ignores run.start, // so it claims no options. const runOptions = this.deps.launches !== undefined ? [...RUN_OPTIONS] : []; - this.send({ type: 'launches.sync', running, runOptions }); + this.send({ + type: 'launches.sync', + running, + runOptions, + // Spec 360, Decision 6: a daemon that handles launches runs check passes. + ...(this.deps.launches !== undefined ? { checks: true } : {}), + }); this.deps.logger.log( 'info', `announced ${running.length} running launch${running.length === 1 ? '' : 'es'}`, diff --git a/apps/cli/src/runner/launch/check.ts b/apps/cli/src/runner/launch/check.ts new file mode 100644 index 00000000..69b4130b --- /dev/null +++ b/apps/cli/src/runner/launch/check.ts @@ -0,0 +1,79 @@ +import { LIST_MAX_SCENARIOS } from './list.ts'; +import { isScenarioId } from './scenario-id.ts'; + +/** Spec 360, Decision 6: the launch cap, per scenario of a check pass. */ +export const CHECK_SCENARIO_MAX_MS = 15 * 60_000; +/** Spec 360, Decision 6: a whole check pass is killed after this. */ +export const CHECK_PASS_MAX_MS = 2 * 60 * 60_000; + +const CHECK_START_FIELDS = new Set([ + 'type', + 'requestId', + 'rootPath', + 'exclude', +]); + +export type CheckStart = + | { ok: true; requestId: string; rootPath: string; exclude: string[] } + | { + ok: false; + requestId: string; + code: 'request-invalid' | 'exclude-invalid'; + } + | { ok: false; requestId: null }; + +/** + * Spec 360, Decision 6: `check.start { requestId, rootPath, exclude }` and + * nothing else; `exclude` holds at most `LIST_MAX_SCENARIOS` scenario ids. + * Pure: a refused request touches no file. A request with no string + * `requestId` cannot be answered and is ignored. + */ +export function checkCheckStart(message: Record<string, unknown>): CheckStart { + const { requestId, rootPath, exclude } = message; + if (typeof requestId !== 'string') return { ok: false, requestId: null }; + if ( + typeof rootPath !== 'string' || + Object.keys(message).some((key) => !CHECK_START_FIELDS.has(key)) + ) { + return { ok: false, requestId, code: 'request-invalid' }; + } + if ( + !Array.isArray(exclude) || + exclude.length > LIST_MAX_SCENARIOS || + !exclude.every(isScenarioId) + ) { + return { ok: false, requestId, code: 'exclude-invalid' }; + } + return { ok: true, requestId, rootPath, exclude: [...new Set(exclude)] }; +} + +function parsed(line: string): Record<string, unknown> | null { + try { + const value: unknown = JSON.parse(line); + return typeof value === 'object' && value !== null && !Array.isArray(value) + ? (value as Record<string, unknown>) + : null; + } catch { + return null; + } +} + +function isCount(value: unknown): value is number { + return typeof value === 'number' && Number.isInteger(value) && value >= 0; +} + +/** True for the line `run --check --progress` prints as each scenario starts. */ +export function isCheckProgressLine(line: string): boolean { + const value = parsed(line); + return value?.type === 'progress' && value.phase === 'check'; +} + +/** The totals of the pass's final `--json` object, or `null` for any other line. */ +export function checkTotals( + line: string, +): { passed: number; failed: number } | null { + const value = parsed(line); + if (value?.check !== true) return null; + const { passed, failed } = value; + return isCount(passed) && isCount(failed) ? { passed, failed } : null; +} diff --git a/apps/cli/src/runner/launch/index.ts b/apps/cli/src/runner/launch/index.ts index 0eff5405..644e31c1 100644 --- a/apps/cli/src/runner/launch/index.ts +++ b/apps/cli/src/runner/launch/index.ts @@ -13,6 +13,13 @@ import { isReportOff } from '../../runs-report/report.ts'; import { readReportedRunsByDir } from '../../runs-report/reported-runs.ts'; import type { Clock } from '../connection.ts'; import type { Logger } from '../log.ts'; +import { + CHECK_PASS_MAX_MS, + CHECK_SCENARIO_MAX_MS, + checkCheckStart, + checkTotals, + isCheckProgressLine, +} from './check.ts'; import { type CheckDeps, checkProject, @@ -132,7 +139,8 @@ class Refused extends Error { /** * Spec 248: the daemon's side of `scenarios.list`, `run.start` and - * `run.cancel`. One website-started run at a time, an ordinary `demoflow run` + * `run.cancel`, and (spec 360) `check.start`. One website-started run or + * check pass at a time, an ordinary `demoflow run` * child that reports itself (ADR-0016 §4). `runner.log` gets request ids, * outcomes, codes and run ids, never a path or a scenario id (Decision 13). */ @@ -171,6 +179,9 @@ export class Launcher implements LaunchPort { } this.start(requestId, rootPath, scenarioId, options, reply, current); return; + case 'check.start': + this.startCheck(message, reply, current); + return; case 'run.cancel': if (typeof requestId !== 'string') { logger.log('warn', 'ignored a malformed run.cancel'); @@ -254,15 +265,7 @@ export class Launcher implements LaunchPort { ); reply.send({ type: 'run.error', requestId, code }); }; - // Decision 6: a start still in its checks counts as running. - const early = - this.launch !== null - ? 'busy' - : this.closing !== null - ? 'io' - : isReportOff(this.deps.env) - ? 'reporting-off' - : null; + const early = this.refusedEarly(); if (early !== null) { refuse(early); return; @@ -298,6 +301,143 @@ export class Launcher implements LaunchPort { }); } + /** Decision 6: a start still in its checks counts as running. */ + private refusedEarly(): string | null { + return this.launch !== null + ? 'busy' + : this.closing !== null + ? 'io' + : isReportOff(this.deps.env) + ? 'reporting-off' + : null; + } + + /** + * Spec 360, Decision 6: a check pass the website starts. Checked like a + * `run.start`, then one `run --check` child for the whole project; it is + * the machine's one launch and is cancelled with `run.cancel`. + */ + private startCheck( + message: Record<string, unknown>, + reply: LaunchSender, + current: LaunchSender, + ): void { + const { logger } = this.deps; + const checked = checkCheckStart(message); + if (!checked.ok && checked.requestId === null) { + logger.log('warn', 'ignored a malformed check.start'); + return; + } + const { requestId } = checked; + const refuse = (code: string) => { + logger.log('info', `check ${shown(requestId)}: refused ${code}`); + reply.send({ type: 'check.error', requestId, code }); + }; + if (!checked.ok) { + refuse(checked.code); + return; + } + const early = this.refusedEarly(); + if (early !== null) { + refuse(early); + return; + } + const launch: Launch = { requestId, done: Promise.resolve() }; + this.launch = launch; + launch.done = this.runCheck( + launch, + checked.rootPath, + checked.exclude, + reply, + current, + ) + .catch((error: unknown) => { + if (error instanceof Refused) refuse(error.code); + else if (launch.child === undefined) refuse('io'); + else + logger.log('error', `check ${shown(requestId)}: failed after start`); + }) + .finally(() => { + if (this.launch === launch) this.launch = null; + }); + } + + private async runCheck( + launch: Launch, + rootPath: string, + exclude: string[], + reply: LaunchSender, + current: LaunchSender, + ): Promise<void> { + const { deps } = this; + const { requestId } = launch; + const project = await checkProject(rootPath, deps); + if (!project.ok) throw new Refused(project.code); + if (launch.ending !== undefined) { + deps.logger.log( + 'info', + `check ${shown(requestId)}: cancelled before start`, + ); + return; + } + let totals: { passed: number; failed: number } | null = null; + // The launch cap applies per scenario: each scenario's start resets it. + let cancelScenarioCap = (): void => {}; + const capScenario = () => { + cancelScenarioCap(); + cancelScenarioCap = deps.clock.after(CHECK_SCENARIO_MAX_MS, () => { + void this.stop(launch, 'timed-out'); + }); + }; + // Nothing from the message but the checked root and scenario ids. + const child = deps.spawn( + [ + 'run', + '--check', + '--json', + '--progress', + '--project', + project.root, + ...exclude.flatMap((id) => ['--exclude', id]), + ], + project.root, + { + killGraceMs: LAUNCH_KILL_GRACE_MS, + onStdoutLine: (line) => { + if (isCheckProgressLine(line)) capScenario(); + totals = checkTotals(line) ?? totals; + }, + }, + ); + if (child.pid === undefined) { + await child.exited; + throw new Refused('io'); + } + launch.child = child; + reply.send({ type: 'check.started', requestId }); + deps.logger.log( + 'info', + `check ${shown(requestId)}: started, ${exclude.length} excluded`, + ); + capScenario(); + const cancelPassCap = deps.clock.after(CHECK_PASS_MAX_MS, () => { + void this.stop(launch, 'timed-out'); + }); + await child.exited; + cancelScenarioCap(); + cancelPassCap(); + // A pass that was ended, or crashed before its summary, verified nothing. + const { passed, failed } = + launch.ending === undefined && totals !== null + ? totals + : { passed: 0, failed: 0 }; + deps.logger.log( + 'info', + `check ${shown(requestId)}: ${launch.ending ?? 'finished'}, ${passed} passed, ${failed} failed`, + ); + current.send({ type: 'check.finished', requestId, passed, failed }); + } + private async run( launch: Launch, rootPath: string, diff --git a/apps/cli/test/runner/connection.spec.ts b/apps/cli/test/runner/connection.spec.ts index 77567a51..15ea7b5b 100644 --- a/apps/cli/test/runner/connection.spec.ts +++ b/apps/cli/test/runner/connection.spec.ts @@ -491,6 +491,7 @@ describe('RunnerConnection and the video relay', () => { type: 'launches.sync', running: ids, runOptions: ['formats'], + checks: true, }); expect(logger.text()).toContain('announced 1 running launch'); first.serverClose(1006); @@ -500,7 +501,12 @@ describe('RunnerConnection and the video relay', () => { last().open(); expect(last()).not.toBe(first); expect(last().sent).toEqual([ - { type: 'launches.sync', running: [], runOptions: ['formats'] }, + { + type: 'launches.sync', + running: [], + runOptions: ['formats'], + checks: true, + }, ]); }); diff --git a/apps/cli/test/runner/daemon-launch.spec.ts b/apps/cli/test/runner/daemon-launch.spec.ts index 2582c682..b236e5ae 100644 --- a/apps/cli/test/runner/daemon-launch.spec.ts +++ b/apps/cli/test/runner/daemon-launch.spec.ts @@ -191,6 +191,7 @@ describe('the daemon with a website-started run', () => { type: 'launches.sync', running: [], runOptions: ['formats'], + checks: true, }); first.receive({ type: 'run.start', @@ -230,6 +231,7 @@ describe('the daemon with a website-started run', () => { type: 'launches.sync', running: [REQUEST], runOptions: ['formats'], + checks: true, }); await stop(next); }); @@ -241,7 +243,12 @@ describe('the daemon with a website-started run', () => { await new Promise((r) => setTimeout(r, 50)); const next = await reconnect(); expect(next.sent).toEqual([ - { type: 'launches.sync', running: [], runOptions: ['formats'] }, + { + type: 'launches.sync', + running: [], + runOptions: ['formats'], + checks: true, + }, ]); }); }); diff --git a/apps/cli/test/runner/launch-check.spec.ts b/apps/cli/test/runner/launch-check.spec.ts new file mode 100644 index 00000000..ce514b75 --- /dev/null +++ b/apps/cli/test/runner/launch-check.spec.ts @@ -0,0 +1,336 @@ +import { + mkdirSync, + mkdtempSync, + realpathSync, + rmSync, + writeFileSync, +} from 'node:fs'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import type { + ChildExit, + RunChild, + SpawnRun, + SpawnRunOptions, +} from '../../src/mcp/child.ts'; +import { + CHECK_PASS_MAX_MS, + CHECK_SCENARIO_MAX_MS, +} from '../../src/runner/launch/check.ts'; +import { nodeLaunchFs } from '../../src/runner/launch/checks.ts'; +import { Launcher, type LauncherDeps } from '../../src/runner/launch/index.ts'; +import { LIST_MAX_SCENARIOS } from '../../src/runner/launch/list.ts'; +import { appendReportedRun } from '../../src/runs-report/reported-runs.ts'; +import { FakeClock, memoryLogger } from './fakes.ts'; + +const REQUEST = '6f1c2b8e-3d4a-4b5c-9e7f-0a1b2c3d4e5f'; + +interface Spawned { + args: string[]; + options: SpawnRunOptions | undefined; + killed: number; + exit(code?: number | null): void; + print(...lines: string[]): void; +} + +function fakeSpawn(): { spawn: SpawnRun; calls: Spawned[] } { + const calls: Spawned[] = []; + const spawn: SpawnRun = (args, _cwd, options) => { + let resolve: (exit: ChildExit) => void = () => {}; + const exited = new Promise<ChildExit>((r) => { + resolve = r; + }); + const child: RunChild = { + pid: 4242, + exited, + kill: async () => { + call.killed++; + resolve({ code: null, stderrTail: '' }); + await exited; + }, + }; + const call: Spawned = { + args, + options, + killed: 0, + exit: (code = 0) => resolve({ code, stderrTail: '' }), + print: (...lines) => { + for (const line of lines) options?.onStdoutLine?.(line); + }, + }; + calls.push(call); + return child; + }; + return { spawn, calls }; +} + +function recorder() { + const sent: Array<Record<string, unknown>> = []; + return { + sent, + send: (message: Record<string, unknown>) => sent.push(message), + }; +} + +let tmp: string; +let root: string; +let indexFile: string; +let clock: FakeClock; +let logger: ReturnType<typeof memoryLogger>; +let spawned: ReturnType<typeof fakeSpawn>; +let reply: ReturnType<typeof recorder>; +let current: ReturnType<typeof recorder>; +let env: Record<string, string | undefined>; + +beforeEach(() => { + tmp = realpathSync.native( + mkdtempSync(path.join(tmpdir(), 'demoflow-launch-check-')), + ); + root = path.join(tmp, 'shop'); + indexFile = path.join(tmp, 'config', 'reported-runs.jsonl'); + mkdirSync(root); + writeFileSync( + path.join(root, 'demoflow.config.json'), + '{"baseUrl":"http://localhost:1"}', + ); + clock = new FakeClock(); + logger = memoryLogger(); + spawned = fakeSpawn(); + reply = recorder(); + current = recorder(); + env = {}; +}); +afterEach(() => { + rmSync(tmp, { recursive: true, force: true }); +}); + +function register(): void { + appendReportedRun(indexFile, { + id: 'srv-0', + runDir: path.join(tmp, 'home', 'runs', 'old'), + at: '2026-10-23T10:00:00.000Z', + root, + }); +} + +function launcher(overrides: Partial<LauncherDeps> = {}): Launcher { + return new Launcher({ + indexFile, + fs: nodeLaunchFs, + logger, + clock, + platform: process.platform, + env, + spawn: spawned.spawn, + loadProject: () => ({ ok: true, home: path.join(tmp, 'home') }), + newRunId: () => 'local-1', + readStatus: async () => 'completed', + ...overrides, + }); +} + +function send(target: Launcher, message: Record<string, unknown>): void { + target.handle(message, reply, current); +} + +const checkOf = (extra: Record<string, unknown> = {}) => ({ + type: 'check.start', + requestId: REQUEST, + rootPath: root, + exclude: [], + ...extra, +}); + +async function answered(count = 1): Promise<Record<string, unknown>> { + await vi.waitFor(() => + expect(reply.sent.length).toBeGreaterThanOrEqual(count), + ); + return reply.sent[count - 1] as Record<string, unknown>; +} + +async function finished(): Promise<Record<string, unknown>> { + await vi.waitFor(() => + expect(current.sent.some((frame) => frame.type === 'check.finished')).toBe( + true, + ), + ); + return current.sent.find((frame) => frame.type === 'check.finished') ?? {}; +} + +async function started(target: Launcher, extra = {}): Promise<Spawned> { + register(); + send(target, checkOf(extra)); + expect(await answered()).toEqual({ + type: 'check.started', + requestId: REQUEST, + }); + const call = spawned.calls[0]; + if (call === undefined) throw new Error('nothing spawned'); + return call; +} + +describe('check.start', () => { + it('spawns exactly run --check --json --progress --project <root> and the checked excludes', async () => { + const call = await started(launcher(), { + exclude: ['demoflow/login.demo.json', 'demoflow/a/b.demo.json'], + }); + expect(call.args).toEqual([ + 'run', + '--check', + '--json', + '--progress', + '--project', + root, + '--exclude', + 'demoflow/login.demo.json', + '--exclude', + 'demoflow/a/b.demo.json', + ]); + call.print(JSON.stringify({ check: true, passed: 3, failed: 1, runs: [] })); + call.exit(1); + expect(await finished()).toEqual({ + type: 'check.finished', + requestId: REQUEST, + passed: 3, + failed: 1, + }); + }); + + it.each<[string, boolean, () => Record<string, unknown>, string]>([ + ['an unregistered root', false, () => checkOf(), 'project-unknown'], + [ + 'an extra field', + true, + () => checkOf({ scenarioId: 'demoflow/a.demo.json' }), + 'request-invalid', + ], + [ + 'a root that is not a string', + true, + () => checkOf({ rootPath: 42 }), + 'request-invalid', + ], + [ + 'no exclude', + true, + () => ({ type: 'check.start', requestId: REQUEST, rootPath: root }), + 'exclude-invalid', + ], + [ + 'an exclude id outside demoflow/', + true, + () => checkOf({ exclude: ['../a.demo.json'] }), + 'exclude-invalid', + ], + [ + 'an exclude id that is not a string', + true, + () => checkOf({ exclude: [7] }), + 'exclude-invalid', + ], + [ + 'too many exclude ids', + true, + () => + checkOf({ + exclude: Array.from( + { length: LIST_MAX_SCENARIOS + 1 }, + (_, i) => `demoflow/s${i}.demo.json`, + ), + }), + 'exclude-invalid', + ], + ])('refuses %s with check.error and spawns nothing', async (_why, registered, message, code) => { + if (registered) register(); + send(launcher(), message()); + expect(await answered()).toEqual({ + type: 'check.error', + requestId: REQUEST, + code, + }); + expect(spawned.calls).toEqual([]); + }); + + it('ignores a check.start with no request id', () => { + send(launcher(), { ...checkOf(), requestId: 7 }); + expect(reply.sent).toEqual([]); + expect(logger.text()).toMatch(/ignored a malformed check\.start/); + }); + + it("is the machine's one launch: busy for a run.start, and refused with reporting off", async () => { + const target = launcher(); + const call = await started(target); + send(target, { + type: 'run.start', + requestId: 'next', + rootPath: root, + scenarioId: 'demoflow/a.demo.json', + }); + expect(await answered(2)).toEqual({ + type: 'run.error', + requestId: 'next', + code: 'busy', + }); + expect(target.running()).toEqual([REQUEST]); + call.exit(0); + await finished(); + + env.DEMOFLOW_NO_REPORT = '1'; + send(target, { ...checkOf(), requestId: 'off' }); + expect(await answered(3)).toEqual({ + type: 'check.error', + requestId: 'off', + code: 'reporting-off', + }); + }); + + it('is cancelled with run.cancel and the same request id', async () => { + const target = launcher(); + const call = await started(target); + send(target, { type: 'run.cancel', requestId: REQUEST }); + expect(await finished()).toEqual({ + type: 'check.finished', + requestId: REQUEST, + passed: 0, + failed: 0, + }); + expect(call.killed).toBe(1); + }); + + it('caps each scenario at 15 minutes: a new scenario restarts the limit', async () => { + const call = await started(launcher()); + const scenarioLine = (run: number) => + JSON.stringify({ type: 'progress', phase: 'check', run, runs: 3 }); + call.print(scenarioLine(1)); + await clock.advance(CHECK_SCENARIO_MAX_MS - 1); + call.print(scenarioLine(2)); + await clock.advance(CHECK_SCENARIO_MAX_MS - 1); + expect(call.killed).toBe(0); + await clock.advance(1); + expect(call.killed).toBe(1); + await finished(); + }); + + it('caps the whole pass at 2 hours', async () => { + const call = await started(launcher()); + const step = CHECK_SCENARIO_MAX_MS - 1; + for ( + let at = 0, run = 1; + at + step < CHECK_PASS_MAX_MS; + at += step, run++ + ) { + call.print( + JSON.stringify({ type: 'progress', phase: 'check', run, runs: 99 }), + ); + await clock.advance(step); + expect(call.killed).toBe(0); + } + call.print( + JSON.stringify({ type: 'progress', phase: 'check', run: 99, runs: 99 }), + ); + await clock.advance(step); + expect(call.killed).toBe(1); + await finished(); + }); +}); From d6486ca3ba64aecab2a620781c6418b516b07bfc Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 14:18:37 +0100 Subject: [PATCH 16/71] feat(renderer): keep holds and the end hold at real speed, outline a zoomed assertion The plan ends at the last event plus its hold and render.endHoldMs (0 after a failure), clamped to the source, replacing the fixed 1 s tail. Hold windows count as active so the idle trim never cuts them, and an assertion with zoom keeps the camera and an outline on its element through its hold. --- packages/renderer/src/ffmpeg/compose.ts | 39 +++++ packages/renderer/src/plan/cards.ts | 3 + packages/renderer/src/plan/frame.ts | 16 ++ packages/renderer/src/plan/plan.ts | 117 ++++++++++++--- packages/renderer/src/plan/time-map.ts | 3 +- packages/renderer/src/plan/types.ts | 20 +++ packages/renderer/test/ffmpeg/render.spec.ts | 76 ++++++++++ packages/renderer/test/plan/fixture-runs.ts | 3 + packages/renderer/test/plan/plan.spec.ts | 137 +++++++++++++++++- .../renderer/test/plan/transitions.spec.ts | 3 +- 10 files changed, 395 insertions(+), 22 deletions(-) diff --git a/packages/renderer/src/ffmpeg/compose.ts b/packages/renderer/src/ffmpeg/compose.ts index c6ccdd7a..dea3d41f 100644 --- a/packages/renderer/src/ffmpeg/compose.ts +++ b/packages/renderer/src/ffmpeg/compose.ts @@ -47,6 +47,8 @@ export const LOOK = { mask: { sigma: 12, wash: hex('#808080'), washAlpha: 0.35 }, cursor: { fill: WHITE, outline: hex('#111111'), outlineWidth: 2 }, ring: { colour: WHITE, width: 4, fromRadius: 12, toRadius: 36 }, + /** Around an asserted element (spec 365): `padding` outside its box. */ + highlight: { width: 2, radius: 8, padding: 4 }, caption: { panel: BLACK, panelAlpha: 0.6, @@ -270,6 +272,9 @@ export function createCompositor( blurBox(target, box, LOOK.mask.sigma); fillBox(target, box, LOOK.mask.wash, LOOK.mask.washAlpha); } + for (const highlight of state.highlights ?? []) { + drawHighlight(target, highlight, state.scale); + } for (const ring of state.rings) { drawRing(target, ring.point, ring.progress, state.scale); } @@ -361,6 +366,40 @@ function drawRing( ); } +function drawHighlight( + target: Picture, + { box, colour, opacity }: NonNullable<FrameState['highlights']>[number], + scale: number, +): void { + const { width, radius, padding } = LOOK.highlight; + const pad = padding * scale; + const outline: Box = { + x: box.x - pad, + y: box.y - pad, + width: box.width + 2 * pad, + height: box.height + 2 * pad, + }; + const corner = Math.min( + radius * scale, + outline.width / 2, + outline.height / 2, + ); + const half = (width * scale) / 2; + const reach = half + 1; + paint( + target, + { + x: outline.x - reach, + y: outline.y - reach, + width: outline.width + 2 * reach, + height: outline.height + 2 * reach, + }, + hex(colour), + opacity, + (x, y) => edge(half - Math.abs(roundRectDistance(outline, corner, x, y))), + ); +} + function drawCursor( target: Picture, tip: { x: number; y: number }, diff --git a/packages/renderer/src/plan/cards.ts b/packages/renderer/src/plan/cards.ts index 1f80972a..2c879eaa 100644 --- a/packages/renderer/src/plan/cards.ts +++ b/packages/renderer/src/plan/cards.ts @@ -8,6 +8,7 @@ import type { ClickRing, CursorMove, FollowKey, + Highlight, KeyBadge, MaskSpan, } from './types.ts'; @@ -96,6 +97,7 @@ export function placeCards(input: { export interface Overlays { cursor: CursorMove[]; clicks: ClickRing[]; + highlights: Highlight[]; camera: CameraKeyframe[]; /** The vertical output's follow camera (spec 176). */ follow: FollowKey[]; @@ -133,6 +135,7 @@ export function shiftOverlays( return { cursor: splitMoves(overlays.cursor, cards).map(span), clicks: overlays.clicks.map((ring) => ({ ...ring, atMs: at(ring.atMs) })), + highlights: overlays.highlights.map(span), camera: holdAcross(overlays.camera, cards, at, (pageMs, atMs) => ({ atMs, ...cameraStateAt(overlays.camera, pageMs), diff --git a/packages/renderer/src/plan/frame.ts b/packages/renderer/src/plan/frame.ts index f821d8f5..9eb98185 100644 --- a/packages/renderer/src/plan/frame.ts +++ b/packages/renderer/src/plan/frame.ts @@ -234,6 +234,21 @@ function liveAt(plan: RenderPlan, view: View, atMs: number): FrameState { ? [{ point: toOutput(ring.point), progress }] : []; }); + const highlights = plan.highlights.flatMap((highlight) => { + if (atMs < highlight.startMs || atMs >= highlight.endMs) return []; + const corner = toOutput(highlight.box); + return [ + { + box: { + ...corner, + width: highlight.box.width * scale, + height: highlight.box.height * scale, + }, + colour: highlight.colour, + opacity: Math.min(1, (atMs - highlight.startMs) / highlight.fadeMs), + }, + ]; + }); const masks = maskBoxes( plan.masks.flatMap((mask) => atMs < mask.startMs || atMs >= mask.endMs ? [] : [maskBoxAt(mask, atMs)], @@ -256,6 +271,7 @@ function liveAt(plan: RenderPlan, view: View, atMs: number): FrameState { ...(stage === undefined ? {} : { frame: stage }), ...(cursor === undefined ? {} : { cursor: toOutput(cursor) }), rings, + ...(highlights.length === 0 ? {} : { highlights }), masks, ...(caption === undefined ? {} : { caption }), ...(badge === undefined diff --git a/packages/renderer/src/plan/plan.ts b/packages/renderer/src/plan/plan.ts index ff6879e3..8c1781e9 100644 --- a/packages/renderer/src/plan/plan.ts +++ b/packages/renderer/src/plan/plan.ts @@ -37,6 +37,7 @@ import type { FailureSpec, FollowKey, FrameSpec, + Highlight, Interval, KeyBadge, OutputFile, @@ -60,6 +61,8 @@ export const DEFAULTS = { idleThresholdMs: 1_000, idleCompressToMs: 400, output: { width: 1920, height: 1080, fps: 30 }, + /** `render.endHoldMs`'s default (spec 365). */ + endHoldMs: 2_500, /** What `zoom: true` means on a source with at least two pixels per CSS pixel (ADR-0012). */ zoom: 1.35, /** Zoom on a 1× source: past the source pixels already, so kept gentle (spec 4, Risks). */ @@ -87,8 +90,8 @@ const TIMING = { maskLeadMs: 200, /** Masks end this late, for the same reason: an early end leaks, a late one is safe (#48). */ maskTrailMs: 200, - /** A successful run keeps this much video after its last event. */ - tailMs: 1_000, + /** An asserted element's outline fades in over this long (spec 365). */ + highlightFadeMs: 200, /** A target box fills at most this share of the zoomed view. */ targetFill: 0.9, } as const; @@ -104,6 +107,12 @@ const ACTIVE: ReadonlySet<StepAction> = new Set([ 'scroll', ]); +/** Steps whose `zoom` stays on the element through the hold, outlined (spec 365, Decision 5). */ +const ASSERTIONS: ReadonlySet<StepAction> = new Set([ + 'assertVisible', + 'assertText', +]); + export interface PlanInput { timeline: Timeline; result: RunResult; @@ -212,25 +221,36 @@ export function planRender( const toSource = (timelineMs: number): number => clamp(timelineMs + offsetMs, 0, source.durationMs); - // The video ends at the failure, or a little after the last event. + // The video ends at the failure, or `endHoldMs` after the last event and + // its hold (spec 365). A source that ends sooner, as one recorded before + // the end hold did, ends it sooner: `toSource` clamps (Decision 6). const failedEvent = failure?.stepIndex === undefined ? undefined : events.find((event) => event.stepIndex === failure.stepIndex); const lastEvent = events.at(-1); + const endHoldMs = + failure === undefined ? (options.endHoldMs ?? DEFAULTS.endHoldMs) : 0; + // Timeline time each event stays on screen until: its hold, and the end + // hold after the last. + const shownUntil = (event: TimelineEvent): number => + heldUntil(event) + (event === lastEvent ? endHoldMs : 0); const sourceEndMs = failure !== undefined ? toSource(failedEvent?.endMs ?? lastEvent?.endMs ?? source.durationMs) : lastEvent === undefined ? source.durationMs - : toSource(lastEvent.endMs + TIMING.tailMs); - - const active: Interval[] = events - .filter((event) => ACTIVE.has(event.action)) - .map((event) => ({ - startMs: toSource(event.startMs), - endMs: toSource(event.endMs), - })); + : toSource(shownUntil(lastEvent)); + + // A hold is never idle: a page frozen on its result plays at 1:1 (Decision 3). + const active: Interval[] = events.flatMap((event) => [ + ...(ACTIVE.has(event.action) + ? [{ startMs: toSource(event.startMs), endMs: toSource(event.endMs) }] + : []), + ...(shownUntil(event) > event.endMs + ? [{ startMs: toSource(event.endMs), endMs: toSource(shownUntil(event)) }] + : []), + ]); const idle = idleStretches(source.freezes, active, thresholdMs, sourceEndMs); // Page time: the map before cards. Overlays are planned in it, then moved // past the cards, so no lead or trail is ever measured across a card. @@ -259,6 +279,9 @@ export function planRender( transitions: options.transitions?.enabled === true, sourceFrameMs: 1000 / source.fps, }); + const cardBackground = + frame?.background ?? + resolveBackground(options.background ?? { preset: 'ocean' }); const verticalConfig = VerticalConfigSchema.parse(options.vertical ?? {}); const squareConfig = SquareConfigSchema.parse(options.square ?? {}); const { follow, squareFollow, ...overlays } = shiftOverlays( @@ -266,7 +289,14 @@ export function planRender( // A phone has no mouse pointer: the click ring is the tap (spec 307). cursor: timeline.device === 'phone' ? [] : cursorMoves(events, out), clicks: clickRings(events, out), - camera: cameraKeyframes(events, out, viewport, defaultZoom), + highlights: highlights( + events, + out, + shownUntil, + pageEndMs, + cardBackground.to, + ), + camera: cameraKeyframes(events, out, viewport, defaultZoom, shownUntil), follow: followKeys( events, out, @@ -359,9 +389,7 @@ export function planRender( durationMs: videoEndMs + (failureSpec?.endCard.durationMs ?? 0), timeMap, cards: cards.map(({ atMs: _, ...card }) => card), - cardBackground: - frame?.background ?? - resolveBackground(options.background ?? { preset: 'ocean' }), + cardBackground, ...overlays, ...(transitions === undefined ? {} : { transitions }), ...(failureSpec === undefined ? {} : { failure: failureSpec }), @@ -660,6 +688,54 @@ function clickRings( ); } +/** The end of an event's hold, or of the event itself without one. */ +function heldUntil(event: TimelineEvent): number { + return event.endMs + (event.holdMs ?? 0); +} + +/** Whether the step asked for a zoom (ADR-0012): `true`, or a strength above 1. */ +function asksForZoom(event: TimelineEvent): boolean { + return ( + event.zoom === true || (typeof event.zoom === 'number' && event.zoom > 1) + ); +} + +/** + * An outline around the element of every assertion with `zoom`, from the end + * of the assertion for as long as its hold keeps it on screen (spec 365, + * Decision 5). + */ +function highlights( + events: readonly TimelineEvent[], + out: (timelineMs: number) => number, + shownUntil: (event: TimelineEvent) => number, + videoEndMs: number, + colour: string, +): Highlight[] { + return events.flatMap((event) => { + if ( + !ASSERTIONS.has(event.action) || + event.target === undefined || + !asksForZoom(event) + ) { + return []; + } + const startMs = out(event.endMs); + const endMs = Math.min(videoEndMs, out(shownUntil(event))); + return endMs > startMs + ? [ + { + startMs, + endMs, + box: event.target.box, + colour, + fadeMs: TIMING.highlightFadeMs, + }, + ] + : []; + }); +} + interface Shot { /** The action itself: the press of a click, the whole of a fill or select. */ startMs: number; @@ -680,6 +756,7 @@ function cameraKeyframes( out: (timelineMs: number) => number, viewport: { width: number; height: number }, defaultZoom: number, + shownUntil: (event: TimelineEvent) => number, ): CameraKeyframe[] { // `null`: a targeted step that does not zoom. const shots: (Shot | null)[] = events.flatMap((event) => { @@ -700,11 +777,17 @@ function cameraKeyframes( ), ); if (zoom === 1) return [null]; - // A click and a press zoom for the moment of the press. + // A click and a press zoom for the moment of the press; an assertion + // stays on its element through its hold (spec 365, Decision 5). const action = event.action === 'click' || event.action === 'press' ? { startMs: out(pressMs(event)), endMs: out(pressMs(event)) } - : { startMs: out(event.startMs), endMs: out(event.endMs) }; + : { + startMs: out(event.startMs), + endMs: out( + ASSERTIONS.has(event.action) ? shownUntil(event) : event.endMs, + ), + }; return [{ ...action, centre: centreOf(box), zoom }]; }); diff --git a/packages/renderer/src/plan/time-map.ts b/packages/renderer/src/plan/time-map.ts index 61a98fc6..0ed543bb 100644 --- a/packages/renderer/src/plan/time-map.ts +++ b/packages/renderer/src/plan/time-map.ts @@ -226,5 +226,6 @@ function lerp( b0: number, b1: number, ): number { - return a1 === a0 ? b0 : b0 + ((value - a0) / (a1 - a0)) * (b1 - b0); + // Multiplied first: whole milliseconds on a 1:1 segment stay whole. + return a1 === a0 ? b0 : b0 + ((value - a0) * (b1 - b0)) / (a1 - a0); } diff --git a/packages/renderer/src/plan/types.ts b/packages/renderer/src/plan/types.ts index 489d9f4b..620833e1 100644 --- a/packages/renderer/src/plan/types.ts +++ b/packages/renderer/src/plan/types.ts @@ -49,6 +49,11 @@ export interface RenderPlanOptions { /** An idle stretch plays in this long. Default 400. */ compressToMs?: number; }; + /** + * How long a successful video keeps the page after its last event, before + * the outro card (`render.endHoldMs`, spec 365). Default 2 500. + */ + endHoldMs?: number; /** * What a step's `zoom: true` resolves to; it does not make a step zoom * (ADR-0012). Default 1.35 on a 2× source, 1.25 below. @@ -189,6 +194,18 @@ export interface ClickRing { point: Point; } +/** An outline around an asserted element while its hold keeps it on screen (spec 365, Decision 5). */ +export interface Highlight { + startMs: number; + endMs: number; + /** The element's box when the assertion passed, viewport CSS pixels. */ + box: Box; + /** `#rrggbb`: the frame's accent, the background's second stop. */ + colour: string; + /** From transparent to opaque over this long from `startMs`. */ + fadeMs: number; +} + /** The camera eases from each keyframe to the next. Zoom 1 shows the whole viewport. */ export interface CameraKeyframe { atMs: number; @@ -324,6 +341,7 @@ export interface RenderPlan { cardBackground: GradientSpec; cursor: CursorMove[]; clicks: ClickRing[]; + highlights: Highlight[]; camera: CameraKeyframe[]; masks: MaskSpan[]; captions: Caption[]; @@ -352,6 +370,8 @@ export interface FrameState { cursor?: Point; /** `progress` runs from 0 to 1 over the ring's life. */ rings: { point: Point; progress: number }[]; + /** Asserted elements outlined (spec 365): output pixels, `opacity` 0–1 as they fade in. */ + highlights?: { box: Box; colour: string; opacity: number }[]; /** Clipped to `content` and to the output frame. */ masks: Box[]; caption?: string; diff --git a/packages/renderer/test/ffmpeg/render.spec.ts b/packages/renderer/test/ffmpeg/render.spec.ts index 269e07e5..cca7cefe 100644 --- a/packages/renderer/test/ffmpeg/render.spec.ts +++ b/packages/renderer/test/ffmpeg/render.spec.ts @@ -676,4 +676,80 @@ describe.skipIf(!hasFfmpeg)('the FFmpeg compositor on real runs', () => { console.info(`page load: frame ${lastHeld} without the hold, ${blank}`); expect(blank).toBeGreaterThan(0.01); }); + + it('keeps a result that shows after the last step on screen through the end hold (spec 365)', async () => { + // A button whose result shows 600 ms after the click: after the last step. + const box = { x: 100, y: 120, width: 400, height: 300 }; + const delayedResult: EngineObserver = { + async onPageCreated({ page }) { + // A string: this file's `setTimeout` is the Node one, and a function + // would have a bare call rewritten into a module reference. + await page.addInitScript(`document.addEventListener('DOMContentLoaded', () => { + const button = document.createElement('button'); + button.textContent = 'Reveal'; + button.style.cssText = 'position:fixed;top:24px;right:24px;z-index:9999;padding:8px 16px'; + button.addEventListener('click', () => setTimeout(() => { + const result = document.createElement('div'); + result.style.cssText = 'position:fixed;left:${box.x}px;top:${box.y}px;width:${box.width}px;height:${box.height}px;background:#00c853;z-index:9999'; + document.body.append(result); + }, 600)); + document.body.append(button); +})`); + }, + }; + const runDir = await recordInlineRun( + 'end-hold', + { + schemaVersion: 1, + name: 'End hold', + viewport: { width: 1280, height: 720 }, + steps: [ + { action: 'navigate', path: '/customers' }, + { action: 'click', target: { role: 'button', name: 'Reveal' } }, + ], + }, + parent, + [delayedResult], + 2500, + ); + const plan = await buildRenderPlan(runDir, { + frame: { enabled: false }, + endHoldMs: 2500, + }); + const events = await readEvents(runDir); + const clicked = events.at(-1); + if (clicked === undefined) throw new Error('no events'); + const { fps } = plan.output; + const toFrame = (ms: number): number => Math.floor((ms * fps) / 1000); + const clickEndMs = toOutputMs(plan.timeMap, clicked.endMs + plan.offsetMs); + // The video runs on for the end hold after the click. + expect(plan.durationMs - clickEndMs).toBeGreaterThanOrEqual(2400); + + const file = renderPath(runDir, 'ffmpeg'); + await ffmpegRenderer.render(runDir, plan); + const numbers = sampleFrames(toFrame(clickEndMs), frameCount(plan), 5); + const frames = await extractFrames(file, numbers, plan); + // Full-bleed: viewport pixels × 1.5 on the 1920 × 1080 output. + const { width } = plan.output; + const centre = { + x: (box.x + box.width / 2) * 1.5, + y: (box.y + box.height / 2) * 1.5, + }; + const shows = frames.map((frame) => { + const [r, g, b] = rgb(frame, width, centre.x, centre.y); + return r < 80 && g > 150 && b < 140; + }); + const first = shows.indexOf(true); + expect(first, 'the result never shows').toBeGreaterThan(-1); + console.info( + `end hold: the result shows from frame ${numbers[first]} of ${frameCount(plan)}`, + ); + // From the moment it shows to the last frame, and long enough to read. + shows.slice(first).forEach((shown, i) => { + expect(shown, `frame ${numbers[first + i]}`).toBe(true); + }); + expect( + ((frameCount(plan) - numbers[first]) * 1000) / fps, + ).toBeGreaterThanOrEqual(1500); + }); }); diff --git a/packages/renderer/test/plan/fixture-runs.ts b/packages/renderer/test/plan/fixture-runs.ts index 303e2296..f3e88124 100644 --- a/packages/renderer/test/plan/fixture-runs.ts +++ b/packages/renderer/test/plan/fixture-runs.ts @@ -63,12 +63,14 @@ export async function recordFixtureRun( /** * Records a scenario given inline — validated as a scenario file is — against * the fixture, into `<parentDir>/<name>`, and returns that run directory. + * No end hold unless `endHoldMs` asks for one (spec 365): it only lengthens a run. */ export async function recordInlineRun( name: string, input: unknown, parentDir: string, observers: readonly EngineObserver[] = [], + endHoldMs = 0, ): Promise<string> { const parsed = parseScenario(input); if (!parsed.ok) throw new Error(JSON.stringify(parsed.errors)); @@ -81,6 +83,7 @@ export async function recordInlineRun( baseUrl: fixture.origin, allowedOrigins: [fixture.origin], env: { FIXTURE_PASSWORD }, + endHoldMs, observers: [ ...observers, createCaptureObserver({ scenarioId: `demoflow/${name}.demo.json` }), diff --git a/packages/renderer/test/plan/plan.spec.ts b/packages/renderer/test/plan/plan.spec.ts index 3687b6cd..4ffa9b95 100644 --- a/packages/renderer/test/plan/plan.spec.ts +++ b/packages/renderer/test/plan/plan.spec.ts @@ -164,7 +164,8 @@ describe('time map', () => { }); // The second click now happens at 1 400 ms of output. expect(toOutputMs(rendered.timeMap, 4000)).toBe(1400); - expect(rendered.durationMs).toBe(4600 + 1000 - 2600); + // The end hold (2 500 ms by default) is kept after the last event. + expect(rendered.durationMs).toBe(4600 + 2500 - 2600); }); it('compresses a frozen passive step (a wait, a failed assertion)', () => { @@ -250,8 +251,8 @@ describe('time map', () => { output = segment.outputEndMs; source = segment.sourceEndMs; } - // The run ends 1 000 ms after its last event; that tail is frozen too. - expect(source).toBe(8000); + // The video ends the end hold after its last event, kept though frozen. + expect(source).toBe(9500); }); it('applies the clock offset: source = timeline + offsetMs', () => { @@ -629,6 +630,136 @@ describe('camera', () => { }); }); +describe('hold (spec 365)', () => { + const box = { x: 500, y: 300, width: 200, height: 40 }; + const assertion = (extra: Partial<TimelineEvent> = {}): TimelineEvent => + event({ + action: 'assertVisible', + startMs: 1000, + endMs: 1200, + target: { box }, + assertion: { passed: true }, + ...extra, + }); + + it("keeps a frozen step's hold at 1:1, and compresses the same freeze on a wait", () => { + const held = plan( + [ + { ...click(0, 1000, { x: 300, y: 200 }), holdMs: 3000 }, + click(4000, 4600, { x: 900, y: 500 }), + ], + [{ startMs: 1000, endMs: 4000 }], + ); + expect(toOutputMs(held.timeMap, 4000)).toBe(4000); + const waited = plan( + [ + click(0, 1000, { x: 300, y: 200 }), + event({ action: 'wait', startMs: 1000, endMs: 4000 }), + click(4000, 4600, { x: 900, y: 500 }), + ], + [{ startMs: 1000, endMs: 4000 }], + ); + expect(toOutputMs(waited.timeMap, 4000)).toBe(1400); + }); + + it('ends the video endHoldMs after the last event, frozen or not', () => { + const events = [click(0, 1000, { x: 300, y: 200 })]; + const frozen = [{ startMs: 1000, endMs: 20_000 }]; + expect(plan(events, frozen, { endHoldMs: 2000 }).durationMs).toBe(3000); + expect(plan(events, [], { endHoldMs: 2000 }).durationMs).toBe(3000); + expect(plan(events, frozen).durationMs).toBe(3500); + expect(plan(events, frozen, { endHoldMs: 0 }).durationMs).toBe(1000); + }); + + it("adds the end hold after the last step's own hold", () => { + const events = [{ ...click(0, 1000, { x: 300, y: 200 }), holdMs: 500 }]; + expect(plan(events, [], { endHoldMs: 2000 }).durationMs).toBe(3500); + }); + + it('holds nothing after a failure', () => { + const rendered = plan( + [ + click(0, 1000, { x: 300, y: 200 }), + { ...click(1000, 2000, { x: 900, y: 500 }), holdMs: 3000 }, + ], + [], + { + endHoldMs: 2000, + failed: { stage: 'execution', stepIndex: 1, message: 'boom' }, + }, + ); + expect(rendered.timeMap.at(-1)?.sourceEndMs).toBe(2000); + }); + + it('clamps the end to a source recorded before the end hold (an old run)', () => { + const rendered = planRender( + { + timeline: timeline([click(0, 1000, { x: 300, y: 200 })]), + result: result(), + source: { + width: 1280, + height: 720, + fps: 25, + durationMs: 1300, + codec: 'vp9', + freezes: [], + }, + }, + { offsetMs: 0, frame: { enabled: false } }, + ); + expect(rendered.durationMs).toBe(1300); + }); + + it('keeps the camera on a zoomed assertion through its hold, and outlines it', () => { + const rendered = plan( + [ + click(0, 1000, { x: 300, y: 200 }), + assertion({ zoom: true, holdMs: 2000 }), + ], + [], + { endHoldMs: 0 }, + ); + const full = Math.max(...rendered.camera.map((key) => key.zoom)); + expect(full).toBeGreaterThan(1); + expect(rendered.camera).toContainEqual( + expect.objectContaining({ atMs: 3200, zoom: full }), + ); + expect(zoomAt(rendered, 2000)).toBeCloseTo(full); + expect(rendered.highlights).toEqual([ + { + startMs: 1200, + endMs: 3200, + box, + colour: expect.stringMatching(/^#[0-9a-f]{6}$/i), + fadeMs: 200, + }, + ]); + // Frame 39 is 1 300 ms: halfway through the 200 ms fade-in. + expect(frameAt(rendered, 39).highlights).toEqual([ + expect.objectContaining({ opacity: 0.5 }), + ]); + expect(frameAt(rendered, 30).highlights).toBeUndefined(); + }); + + it('outlines a zoomed assertion at the end of the run through the end hold', () => { + const rendered = plan([assertion({ zoom: true })], [], { + endHoldMs: 1500, + }); + expect(rendered.highlights).toMatchObject([{ startMs: 1200, endMs: 2700 }]); + }); + + it('neither zooms nor outlines an assertion without zoom', () => { + const rendered = plan( + [click(0, 1000, { x: 300, y: 200 }), assertion({ holdMs: 2000 })], + [], + ); + expect(rendered.highlights).toEqual([]); + for (const atMs of [1000, 1200, 2000, 3200]) { + expect(zoomAt(rendered, atMs)).toBe(1); + } + }); +}); + describe('cursor and clicks', () => { it('is hidden before the first pointer event, glides, then rests', () => { const rendered = plan( diff --git a/packages/renderer/test/plan/transitions.spec.ts b/packages/renderer/test/plan/transitions.spec.ts index 85fa76e2..1af03f42 100644 --- a/packages/renderer/test/plan/transitions.spec.ts +++ b/packages/renderer/test/plan/transitions.spec.ts @@ -485,7 +485,8 @@ describe('a masked field across a document navigation (spec 146)', () => { expect( plan({ ...options, events: UNMEASURED, navigations: undefined }).masks, ).toEqual([ - { startMs: 600, endMs: 6000, keys: [{ atMs: 600, box: MASKED }] }, + // To the end of the page: the last event plus the end hold (spec 365). + { startMs: 600, endMs: 7500, keys: [{ atMs: 600, box: MASKED }] }, ]); } }); From 4e202619a11ced99f2232370cbfeed9b00515e31 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 14:18:44 +0100 Subject: [PATCH 17/71] docs: hold on a step and render.endHoldMs Why hold and not wait: the idle trim shortens a wait on a still page, never a hold. --- apps/web/src/app/docs/config/page.mdx | 1 + apps/web/src/app/docs/scenarios/page.mdx | 36 +++++++++++++++++++++++- 2 files changed, 36 insertions(+), 1 deletion(-) diff --git a/apps/web/src/app/docs/config/page.mdx b/apps/web/src/app/docs/config/page.mdx index 5ea80885..5a7802f7 100644 --- a/apps/web/src/app/docs/config/page.mdx +++ b/apps/web/src/app/docs/config/page.mdx @@ -104,6 +104,7 @@ Every `render` key is optional. These are the defaults: | `fps` | 30 | Frames per second. | | `idle.thresholdMs` | 1000 | A still stretch longer than this is shortened. | | `idle.compressToMs` | 400 | …to this long. | +| `endHoldMs` | 2500 | How long a successful video stays on screen after the last step, 0 to 10000 ms. The run records it, so a result that shows late is in the video. A failed run ends at the failure. To hold after any step, see [`hold`](/docs/scenarios#hold). | | `frame` | on | See below. | | `background` | `{ "preset": "ocean" }` | See below. | | `cards` | see below | Intro, scene and outro cards. | diff --git a/apps/web/src/app/docs/scenarios/page.mdx b/apps/web/src/app/docs/scenarios/page.mdx index df816888..d774690c 100644 --- a/apps/web/src/app/docs/scenarios/page.mdx +++ b/apps/web/src/app/docs/scenarios/page.mdx @@ -74,7 +74,8 @@ whole string instead of a part of it. ## Steps Every step has an `action`. Every step may also carry a `caption`, a -`timeoutMs` and `"record": false` (see [Off-camera steps](#off-camera-steps)). +`timeoutMs`, a [`hold`](#hold) and `"record": false` (see +[Off-camera steps](#off-camera-steps)). | Action | What it does | Fields | |---|---|---| @@ -128,6 +129,39 @@ steps that have a target, `waitFor` for a hidden element excepted, and on } ``` +### hold + +`hold` keeps the page on screen after the step, for 100 to 10000 ms. The run +waits that long once the step is done, and the video plays the whole hold at +real speed: the [idle trim](/docs/config#render) never shortens it. A step that +fails does not hold. `hold` is refused on an off-camera step +(`"record": false`). + +Use `hold`, not `wait`, to show something. A `wait` on a still page is idle +time, and the render shortens it to `render.idle.compressToMs` (400 ms by +default). + +#### Show the result + +Assert the result, zoom in on it and hold it. An assertion with `zoom` keeps the +camera on the element it found through its hold, and outlines it: + +```json +{ + "action": "assertVisible", + "target": { "text": "My first post" }, + "zoom": true, + "hold": 2000 +} +``` + +The outline is drawn where the element was when the assertion passed, so hold +an element that has stopped moving. + +Every successful video also ends on its last frame for +[`render.endHoldMs`](/docs/config#render) (2500 ms by default), after the last +step's own `hold`. + ### Scene markers A `marker` with `kind: "scene"` starts a new scene. It gets a scene card in the From e213587a317f8e206db814904829dcd5c3144cb2 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 14:19:48 +0100 Subject: [PATCH 18/71] docs(cli): document demoflow run --check and --exclude --- apps/cli/README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/apps/cli/README.md b/apps/cli/README.md index a16dc4f5..adfbe3f3 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -140,6 +140,21 @@ are no longer listed. The website is not told, so its runs list keeps the first render's formats. A run that is unfinished or has no recording is refused with exit 2; a render that fails exits 3. +`demoflow run --check <scenario>` runs and verifies the scenario against the +live app like `run`, but records and renders nothing: the run directory holds +only `result.json`, with `recording` and `rendering` skipped. Without a +scenario, `demoflow run --check` runs every valid scenario of the project +(the files under `demoflow/`, sorted, at most 100) one after another against a +single start of `devCommand`, and prints one line per scenario, then +`N passed, M failed`. `--exclude <id>` leaves a scenario out of such a pass +(repeatable; `demoflow/login.demo.json` or `login.demo.json`; an id that is no +scenario is ignored). `--json` prints `{ "check": true, "passed", "failed", +"runs": [...] }`, each run as `run --json` prints it. It exits 0 when every run +passed and 1 when any failed. `--format` and `--headed` are refused with exit 2 +before anything runs. Each run is reported like any other, marked as a check. +Unlike `demoflow check`, which only inspects files and tools, this opens the +app. + `demoflow init [--base-url <url>]` writes `demoflow.config.json` (default `baseUrl` `http://localhost:3000`) and `demoflow/first.demo.json`, a scenario that opens `/` and passes against any app at `baseUrl`, in the current folder. @@ -185,6 +200,7 @@ typed value. Secret fills are left as recorded. | `demoflow record [name]` | record a scenario by using the app | | `demoflow validate <scenario>` | check a scenario against the schema | | `demoflow run <scenario>` | run it in a browser and render the video | +| `demoflow run --check [scenario]` | run and verify one scenario, or all of them, without a video | | `demoflow render <runId>` | render an existing run again with the current config | | `demoflow list` | list recent runs of the current project, newest first | | `demoflow runs list` | list every run on this machine, with its size | From ca32816751665f697f10223d31c02301e10e6716 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 14:20:44 +0100 Subject: [PATCH 19/71] feat(cli): pass render.endHoldMs to the render plan CLI test projects set endHoldMs to 0 to keep runs short; one test checks the default reaches the plan. --- apps/cli/src/commands/render.ts | 1 + apps/cli/test/commands/cli.spec.ts | 7 +++++-- apps/cli/test/commands/render.spec.ts | 2 ++ 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/apps/cli/src/commands/render.ts b/apps/cli/src/commands/render.ts index 23351976..4263cf53 100644 --- a/apps/cli/src/commands/render.ts +++ b/apps/cli/src/commands/render.ts @@ -204,6 +204,7 @@ export function renderPlanOptions( ): RenderPlanOptions { return { idle: config.render.idle, + endHoldMs: config.render.endHoldMs, output: { width: config.render.width, height: config.render.height, diff --git a/apps/cli/test/commands/cli.spec.ts b/apps/cli/test/commands/cli.spec.ts index 341465c2..9d9104a2 100644 --- a/apps/cli/test/commands/cli.spec.ts +++ b/apps/cli/test/commands/cli.spec.ts @@ -110,7 +110,8 @@ beforeAll(async () => { out = await mkdtemp(path.join(tmpdir(), 'demoflow-cli-out-')); await writeFile( path.join(project, 'demoflow.config.json'), - JSON.stringify({ baseUrl: fixture.origin }), + // No end hold (spec 365): it only lengthens every run of these tests. + JSON.stringify({ baseUrl: fixture.origin, render: { endHoldMs: 0 } }), ); await cp(FIXTURE_SCENARIOS, path.join(project, 'demoflow'), { recursive: true, @@ -357,6 +358,7 @@ describe('demoflow run', () => { JSON.stringify({ baseUrl: fixture.origin, render: { + endHoldMs: 0, frame: { marginRatio: 0.2 }, background: { color: '#c03020' }, // Frame 0 is the page, not the intro card nor the first load's @@ -422,7 +424,7 @@ describe('demoflow run', () => { path.join(carded, 'demoflow.config.json'), JSON.stringify({ baseUrl: fixture.origin, - render: { background: { color: '#c03020' }, cards }, + render: { endHoldMs: 0, background: { color: '#c03020' }, cards }, }), ); const result = await demoflow( @@ -485,6 +487,7 @@ describe('demoflow run', () => { JSON.stringify({ baseUrl: fixture.origin, render: { + endHoldMs: 0, background: { color: '#c03020' }, cards: { intro: { enabled: false } }, }, diff --git a/apps/cli/test/commands/render.spec.ts b/apps/cli/test/commands/render.spec.ts index d7719e30..acd19c53 100644 --- a/apps/cli/test/commands/render.spec.ts +++ b/apps/cli/test/commands/render.spec.ts @@ -215,6 +215,8 @@ describe('demoflow render', () => { expect(d.plans[0]?.dir).toBe(runDir); expect(d.plans[0]?.options.formats).toEqual(['mp4', 'webm']); expect(d.plans[0]?.options.output?.fps).toBe(24); + // The default end hold, as `demoflow run` recorded it (spec 365). + expect(d.plans[0]?.options.endHoldMs).toBe(2500); expect(io.err).toContain('Rendering\n'); expect(io.out).toContain(RUN_ID); const written = await readResultFile(); From 4ef0fb9536db6fe628aebc3405dc8d5cd0c4411d Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 14:26:11 +0100 Subject: [PATCH 20/71] feat(web): nav, crumbs, theme and overview stats for the app shell Bumps @andrewbehma/glass-ui to 0.37.0 for use-breakpoint (spec #373, Decision 7) and adds the pure modules the shell is built on, each with a node:test suite. --- apps/web/package.json | 4 +- apps/web/src/lib/crumbs.test.mjs | 72 +++++++++++++ apps/web/src/lib/crumbs.ts | 74 ++++++++++++++ apps/web/src/lib/nav.test.mjs | 20 ++++ apps/web/src/lib/nav.ts | 67 +++++++++++++ apps/web/src/lib/overview-stats.test.mjs | 31 ++++++ apps/web/src/lib/overview-stats.ts | 26 +++++ apps/web/src/lib/theme.test.mjs | 122 +++++++++++++++++++++++ apps/web/src/lib/theme.ts | 62 ++++++++++++ bun.lock | 6 +- 10 files changed, 480 insertions(+), 4 deletions(-) create mode 100644 apps/web/src/lib/crumbs.test.mjs create mode 100644 apps/web/src/lib/crumbs.ts create mode 100644 apps/web/src/lib/nav.test.mjs create mode 100644 apps/web/src/lib/nav.ts create mode 100644 apps/web/src/lib/overview-stats.test.mjs create mode 100644 apps/web/src/lib/overview-stats.ts create mode 100644 apps/web/src/lib/theme.test.mjs create mode 100644 apps/web/src/lib/theme.ts diff --git a/apps/web/package.json b/apps/web/package.json index e26e158c..c5fafb6b 100644 --- a/apps/web/package.json +++ b/apps/web/package.json @@ -7,10 +7,10 @@ "start": "next start -p 3670", "start:dev": "node scripts/dev.mjs", "lint": "biome lint src", - "test": "node --test src/lib/docs-nav.test.mjs src/lib/playback.test.mjs src/lib/launch.test.mjs src/lib/format-bytes.test.mjs src/lib/run-delete.test.mjs src/lib/player-choice.test.mjs" + "test": "node --test src/lib/docs-nav.test.mjs src/lib/playback.test.mjs src/lib/launch.test.mjs src/lib/format-bytes.test.mjs src/lib/run-delete.test.mjs src/lib/player-choice.test.mjs src/lib/nav.test.mjs src/lib/crumbs.test.mjs src/lib/theme.test.mjs src/lib/overview-stats.test.mjs" }, "dependencies": { - "@andrewbehma/glass-ui": "0.34.0", + "@andrewbehma/glass-ui": "0.37.0", "@demoflow/shared": "workspace:*", "@mdx-js/loader": "3.1.1", "@mdx-js/react": "3.1.1", diff --git a/apps/web/src/lib/crumbs.test.mjs b/apps/web/src/lib/crumbs.test.mjs new file mode 100644 index 00000000..18e2d52d --- /dev/null +++ b/apps/web/src/lib/crumbs.test.mjs @@ -0,0 +1,72 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { crumbsFor } from './crumbs.ts'; + +const labels = { + overview: 'Overview', + projects: 'Projects', + project: 'Project', + run: 'Run', + machines: 'Machines', + settings: 'Settings', + device: 'Pair a machine', +}; +const none = new Map(); +const trail = (pathname, names = none) => + crumbsFor(pathname, names, labels).map(({ label, href }) => + href ? `${label} ${href}` : label, + ); + +test('the Overview is a single crumb', () => { + assert.deepEqual(trail('/app'), ['Overview']); + assert.deepEqual(trail('/app/'), ['Overview']); +}); + +test('each top-level page is its own crumb', () => { + assert.deepEqual(trail('/app/projects'), ['Projects']); + assert.deepEqual(trail('/app/machines'), ['Machines']); + assert.deepEqual(trail('/app/settings'), ['Settings']); + assert.deepEqual(trail('/app/device'), ['Pair a machine']); +}); + +test('a project page shows the project name under Projects', () => { + assert.deepEqual(trail('/app/projects/p1', new Map([['p1', 'landing']])), [ + 'Projects /app/projects', + 'landing', + ]); +}); + +test('a run page shows the project and the scenario names', () => { + const names = new Map([ + ['p1', 'landing'], + ['r9', 'sign up'], + ]); + assert.deepEqual(trail('/app/projects/p1/runs/r9', names), [ + 'Projects /app/projects', + 'landing /app/projects/p1', + 'sign up', + ]); +}); + +test('an unnamed segment shows its kind, never the raw id', () => { + const crumbs = trail('/app/projects/cm8x1/runs/cm9y2'); + assert.deepEqual(crumbs, [ + 'Projects /app/projects', + 'Project /app/projects/cm8x1', + 'Run', + ]); + assert.ok(crumbs.every((crumb) => !crumb.startsWith('cm'))); +}); + +test('ids are decoded for lookup and encoded in links', () => { + const names = new Map([['a b', 'Spaced']]); + assert.deepEqual(trail('/app/projects/a%20b/runs/r', names), [ + 'Projects /app/projects', + 'Spaced /app/projects/a%20b', + 'Run', + ]); +}); + +test('an unknown path falls back to the Overview', () => { + assert.deepEqual(trail('/app/nowhere/else'), ['Overview']); +}); diff --git a/apps/web/src/lib/crumbs.ts b/apps/web/src/lib/crumbs.ts new file mode 100644 index 00000000..c3cdde44 --- /dev/null +++ b/apps/web/src/lib/crumbs.ts @@ -0,0 +1,74 @@ +/** What a crumb stands for; the shell gives each kind its label. */ +export type CrumbKind = + | 'overview' + | 'projects' + | 'project' + | 'run' + | 'machines' + | 'settings' + | 'device'; + +export interface Crumb { + id: string; + label: string; + /** Absent on the last crumb: the page itself is not a link. */ + href?: string; +} + +/** A display name per path segment (a project or run id), from the pages. */ +export type CrumbNames = ReadonlyMap<string, string>; + +const SECTIONS: Readonly<Record<string, CrumbKind>> = { + projects: 'projects', + machines: 'machines', + settings: 'settings', + device: 'device', +}; + +function decode(part: string): string { + try { + return decodeURIComponent(part); + } catch { + return part; + } +} + +/** + * The trail for an `/app` pathname (spec #373, Decision 5). A project or run + * segment shows its name from `names`, or its kind's label until the page + * passes one — never the raw id. An unknown path falls back to Overview. + */ +export function crumbsFor( + pathname: string, + names: CrumbNames, + labels: Readonly<Record<CrumbKind, string>>, +): Crumb[] { + const parts = pathname + .replace(/^\/app\/?/, '') + .split('/') + .filter(Boolean) + .map(decode); + const [section, id, sub, runId] = parts; + const kind = section ? SECTIONS[section] : undefined; + if (!kind) return [{ id: 'overview', label: labels.overview }]; + + const crumbs: Crumb[] = [ + { id: kind, label: labels[kind], href: `/app/${section}` }, + ]; + if (kind === 'projects' && id) { + crumbs.push({ + id: `project:${id}`, + label: names.get(id) ?? labels.project, + href: `/app/projects/${encodeURIComponent(id)}`, + }); + if (sub === 'runs' && runId) { + crumbs.push({ + id: `run:${runId}`, + label: names.get(runId) ?? labels.run, + }); + } + } + const last = crumbs.at(-1); + if (last) delete last.href; + return crumbs; +} diff --git a/apps/web/src/lib/nav.test.mjs b/apps/web/src/lib/nav.test.mjs new file mode 100644 index 00000000..1c8946fa --- /dev/null +++ b/apps/web/src/lib/nav.test.mjs @@ -0,0 +1,20 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { activeNavId, NAV_ITEMS } from './nav.ts'; + +test('each nav page lights its own item', () => { + for (const item of NAV_ITEMS) { + assert.equal(activeNavId(item.href), item.id); + } +}); + +test('nested routes light the longest matching item', () => { + assert.equal(activeNavId('/app/projects/p1'), 'projects'); + assert.equal(activeNavId('/app/projects/p1/runs/r1'), 'projects'); + assert.equal(activeNavId('/app/device'), 'overview'); +}); + +test('a shared prefix that is not a segment does not match', () => { + assert.equal(activeNavId('/app/projectsx'), 'overview'); + assert.equal(activeNavId('/docs'), null); +}); diff --git a/apps/web/src/lib/nav.ts b/apps/web/src/lib/nav.ts new file mode 100644 index 00000000..c60f0e42 --- /dev/null +++ b/apps/web/src/lib/nav.ts @@ -0,0 +1,67 @@ +// Labels without placeholders, so `t(label)` takes no params. +type NavLabel = + | 'app.shell.nav.overview' + | 'app.shell.nav.projects' + | 'app.shell.nav.machines' + | 'app.shell.nav.settings'; + +/** Names an icon the sidebar draws; kept out of this module so it stays pure. */ +export type NavIcon = 'overview' | 'projects' | 'machines' | 'settings'; + +export interface NavItem { + id: string; + href: string; + label: NavLabel; + icon: NavIcon; +} + +/** + * The app's sidebar, in order (spec #373, Decision 2). A later page adds its + * entry here with one line; Shares arrives with #350. + */ +export const NAV_ITEMS: readonly NavItem[] = [ + { + id: 'overview', + href: '/app', + label: 'app.shell.nav.overview', + icon: 'overview', + }, + { + id: 'projects', + href: '/app/projects', + label: 'app.shell.nav.projects', + icon: 'projects', + }, + { + id: 'machines', + href: '/app/machines', + label: 'app.shell.nav.machines', + icon: 'machines', + }, + { + id: 'settings', + href: '/app/settings', + label: 'app.shell.nav.settings', + icon: 'settings', + }, +]; + +function matches(pathname: string, href: string): boolean { + return pathname === href || pathname.startsWith(`${href}/`); +} + +/** + * The item whose `href` is the longest prefix of `pathname`, so a run page + * lights Projects; null when no item matches. + */ +export function activeNavId( + pathname: string, + items: readonly NavItem[] = NAV_ITEMS, +): string | null { + let best: NavItem | null = null; + for (const item of items) { + if (!matches(pathname, item.href)) continue; + if (!best || item.href.length > best.href.length) best = item; + } + return best?.id ?? null; +} diff --git a/apps/web/src/lib/overview-stats.test.mjs b/apps/web/src/lib/overview-stats.test.mjs new file mode 100644 index 00000000..d85bdfd0 --- /dev/null +++ b/apps/web/src/lib/overview-stats.test.mjs @@ -0,0 +1,31 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { onlineCount, overviewStats } from './overview-stats.ts'; + +const run = (status) => ({ status }); + +test('no projects: every tile is zero', () => { + assert.deepEqual(overviewStats([]), { projects: 0, runs: 0, failing: 0 }); +}); + +test('tiles count projects, sum runs and count failing last runs', () => { + const projects = [ + { runCount: 12, lastRun: run('passed') }, + { runCount: 3, lastRun: run('failed') }, + { runCount: 0, lastRun: null }, + { runCount: 7, lastRun: run('failed') }, + ]; + assert.deepEqual(overviewStats(projects), { + projects: 4, + runs: 22, + failing: 2, + }); +}); + +test('onlineCount counts connected machines', () => { + assert.equal(onlineCount([]), 0); + assert.equal( + onlineCount([{ online: true }, { online: false }, { online: true }]), + 2, + ); +}); diff --git a/apps/web/src/lib/overview-stats.ts b/apps/web/src/lib/overview-stats.ts new file mode 100644 index 00000000..6fb77574 --- /dev/null +++ b/apps/web/src/lib/overview-stats.ts @@ -0,0 +1,26 @@ +import type { Project } from './api'; + +export interface OverviewStats { + projects: number; + runs: number; + /** Projects whose latest run failed. */ + failing: number; +} + +/** The Overview's tiles (spec #373, Decision 9), from the project list. */ +export function overviewStats( + projects: readonly Pick<Project, 'runCount' | 'lastRun'>[], +): OverviewStats { + let runs = 0; + let failing = 0; + for (const project of projects) { + runs += project.runCount; + if (project.lastRun?.status === 'failed') failing += 1; + } + return { projects: projects.length, runs, failing }; +} + +/** How many of the machines are connected now. */ +export function onlineCount(runners: readonly { online: boolean }[]): number { + return runners.filter((runner) => runner.online).length; +} diff --git a/apps/web/src/lib/theme.test.mjs b/apps/web/src/lib/theme.test.mjs new file mode 100644 index 00000000..c57e1c62 --- /dev/null +++ b/apps/web/src/lib/theme.test.mjs @@ -0,0 +1,122 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { + applyTheme, + readStoredTheme, + resolveTheme, + storeTheme, + THEME_BOOTSTRAP_SCRIPT, + THEME_STORAGE_KEY, +} from './theme.ts'; + +function memoryStorage(initial = {}) { + const values = new Map(Object.entries(initial)); + return { + getItem: (key) => values.get(key) ?? null, + setItem: (key, value) => values.set(key, String(value)), + removeItem: (key) => values.delete(key), + values, + }; +} +const blocked = () => { + throw new Error('SecurityError: storage is blocked'); +}; + +test('system follows the preference; dark and light ignore it', () => { + assert.equal(resolveTheme('system', true), 'light'); + assert.equal(resolveTheme('system', false), 'dark'); + assert.equal(resolveTheme('dark', true), 'dark'); + assert.equal(resolveTheme('light', false), 'light'); +}); + +test('a stored mode is read back; anything else is system', () => { + assert.equal(readStoredTheme(() => memoryStorage({ 'df-theme': 'light' })), 'light'); + assert.equal(readStoredTheme(() => memoryStorage({ 'df-theme': 'dark' })), 'dark'); + assert.equal(readStoredTheme(() => memoryStorage({ 'df-theme': 'neon' })), 'system'); + assert.equal(readStoredTheme(() => memoryStorage()), 'system'); +}); + +test('system clears the key; dark and light store it', () => { + const storage = memoryStorage(); + storeTheme('light', () => storage); + assert.equal(storage.values.get(THEME_STORAGE_KEY), 'light'); + storeTheme('system', () => storage); + assert.equal(storage.values.has(THEME_STORAGE_KEY), false); +}); + +test('blocked storage reads as system and never throws on write', () => { + assert.equal(readStoredTheme(blocked), 'system'); + assert.doesNotThrow(() => storeTheme('dark', blocked)); +}); + +test('applyTheme sets the mode and the resolved theme', () => { + const attributes = {}; + applyTheme({ setAttribute: (k, v) => (attributes[k] = v) }, 'system', true); + assert.deepEqual(attributes, { + 'data-theme-mode': 'system', + 'data-theme': 'light', + }); +}); + +/** Runs the inline script against a fake document and returns its root. */ +function boot({ storage, prefersLight }) { + const attributes = {}; + const listeners = []; + const query = { + matches: prefersLight, + addEventListener: (_type, listener) => listeners.push(listener), + }; + const root = { + setAttribute: (k, v) => (attributes[k] = v), + getAttribute: (k) => attributes[k] ?? null, + }; + const window = { matchMedia: () => query }; + // A browser that blocks storage throws on any use of `localStorage`. + const localStorage = + storage === 'blocked' + ? new Proxy({}, { get: blocked }) + : storage; + new Function('document', 'window', 'localStorage', THEME_BOOTSTRAP_SCRIPT)( + { documentElement: root }, + window, + localStorage, + ); + return { + attributes, + flip(matches) { + query.matches = matches; + for (const listener of listeners) listener(); + }, + }; +} + +test('the bootstrap script applies a stored theme', () => { + const { attributes } = boot({ + storage: memoryStorage({ 'df-theme': 'light' }), + prefersLight: false, + }); + assert.equal(attributes['data-theme'], 'light'); + assert.equal(attributes['data-theme-mode'], 'light'); +}); + +test('the bootstrap script follows the system live while in system mode', () => { + const page = boot({ storage: memoryStorage(), prefersLight: true }); + assert.equal(page.attributes['data-theme'], 'light'); + page.flip(false); + assert.equal(page.attributes['data-theme'], 'dark'); +}); + +test('a fixed mode ignores a system change', () => { + const page = boot({ + storage: memoryStorage({ 'df-theme': 'dark' }), + prefersLight: false, + }); + page.flip(true); + assert.equal(page.attributes['data-theme'], 'dark'); +}); + +test('blocked storage still renders, following the system', () => { + const page = boot({ storage: 'blocked', prefersLight: true }); + assert.equal(page.attributes['data-theme-mode'], 'system'); + assert.equal(page.attributes['data-theme'], 'light'); +}); diff --git a/apps/web/src/lib/theme.ts b/apps/web/src/lib/theme.ts new file mode 100644 index 00000000..c0ef2650 --- /dev/null +++ b/apps/web/src/lib/theme.ts @@ -0,0 +1,62 @@ +export const THEME_STORAGE_KEY = 'df-theme'; + +export const THEME_MODES = ['system', 'dark', 'light'] as const; +export type ThemeMode = (typeof THEME_MODES)[number]; +export type Theme = 'dark' | 'light'; + +/** The chosen mode lives on `<html>` too, so every script reads one value. */ +export const THEME_MODE_ATTRIBUTE = 'data-theme-mode'; + +export const LIGHT_QUERY = '(prefers-color-scheme: light)'; + +export function isThemeMode(value: unknown): value is ThemeMode { + return THEME_MODES.some((mode) => mode === value); +} + +/** The concrete theme a mode resolves to, given the system preference. */ +export function resolveTheme(mode: ThemeMode, prefersLight: boolean): Theme { + if (mode !== 'system') return mode; + return prefersLight ? 'light' : 'dark'; +} + +/** + * The stored mode, or `system`. `storage` is a getter because reading + * `window.localStorage` itself throws when the browser blocks storage. + */ +export function readStoredTheme(storage: () => Storage): ThemeMode { + try { + const stored = storage().getItem(THEME_STORAGE_KEY); + return isThemeMode(stored) ? stored : 'system'; + } catch { + return 'system'; + } +} + +/** Remembers `mode`; with storage blocked the choice lasts until reload. */ +export function storeTheme(mode: ThemeMode, storage: () => Storage): void { + try { + if (mode === 'system') storage().removeItem(THEME_STORAGE_KEY); + else storage().setItem(THEME_STORAGE_KEY, mode); + } catch { + // Storage blocked: the attribute on <html> still holds it for this page. + } +} + +/** Sets the mode and the theme it resolves to on the root element. */ +export function applyTheme( + root: Pick<Element, 'setAttribute'>, + mode: ThemeMode, + prefersLight: boolean, +): void { + root.setAttribute(THEME_MODE_ATTRIBUTE, mode); + root.setAttribute('data-theme', resolveTheme(mode, prefersLight)); +} + +/** + * Runs inline in `<head>` before first paint, so a page never flashes the + * other theme (spec #373, Decision 6). It reads the stored mode, sets + * `data-theme-mode` and `data-theme`, and while the mode is `system` follows + * the OS live — on every page, inside the app shell or not. A string, not a + * module: it must not depend on anything. + */ +export const THEME_BOOTSTRAP_SCRIPT = `(function(){var d=document.documentElement,m=null;try{m=localStorage.getItem('${THEME_STORAGE_KEY}')}catch(e){}if(m!=='dark'&&m!=='light')m='system';d.setAttribute('${THEME_MODE_ATTRIBUTE}',m);var q=window.matchMedia?window.matchMedia('${LIGHT_QUERY}'):null;function a(){var c=d.getAttribute('${THEME_MODE_ATTRIBUTE}');d.setAttribute('data-theme',c==='dark'||c==='light'?c:q&&q.matches?'light':'dark')}a();if(q&&q.addEventListener)q.addEventListener('change',a)})()`; diff --git a/bun.lock b/bun.lock index 09701291..0b74e94f 100644 --- a/bun.lock +++ b/bun.lock @@ -58,7 +58,7 @@ }, "apps/cli": { "name": "@demoflow/cli", - "version": "0.5.0", + "version": "0.7.0", "bin": { "demoflow": "./dist/main.js", }, @@ -118,7 +118,7 @@ "name": "@demoflow/web", "version": "0.0.1", "dependencies": { - "@andrewbehma/glass-ui": "0.34.0", + "@andrewbehma/glass-ui": "0.37.0", "@demoflow/shared": "workspace:*", "@mdx-js/loader": "3.1.1", "@mdx-js/react": "3.1.1", @@ -2372,6 +2372,8 @@ "@demoflow/renderer/@types/node": ["@types/node@24.19.0", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-zY+5tKxXdhGh1PYI0ac+7juvEu4OI6vWtVVoj5i2m42jxAY1U+zHGt6QCyOFwykdP62sM3MJ9stoYYUw5aCWew=="], + "@demoflow/web/@andrewbehma/glass-ui": ["@andrewbehma/glass-ui@0.37.0", "", { "dependencies": { "tailwind-merge": "3.6.0", "tailwind-variants": "3.3.1" }, "peerDependencies": { "@dagrejs/dagre": ">=3.0.0", "@radix-ui/react-context-menu": ">=2.2.0", "@radix-ui/react-dialog": ">=1.1.0", "@radix-ui/react-dropdown-menu": ">=2.1.0", "@radix-ui/react-popover": ">=1.1.0", "@radix-ui/react-slider": ">=1.3.0", "@radix-ui/react-tooltip": ">=1.1.0", "@xterm/addon-fit": ">=0.11.0", "@xterm/xterm": ">=6.0.0", "@xyflow/react": ">=12.0.0", "cron-parser": ">=5.0.0", "cronstrue": ">=3.0.0", "lucide-react": ">=0.400.0", "motion": ">=12.0.0", "react": "^19.0.0", "react-dom": "^19.0.0", "sonner": ">=2.0.0", "tailwindcss": "^4.0.0" }, "optionalPeers": ["@dagrejs/dagre", "@xterm/addon-fit", "@xterm/xterm", "@xyflow/react", "cron-parser", "cronstrue"] }, "sha512-0zZg+Ie/P+c8LJOzZqJnk5HuT2ZOEF0VYXqjw131vO2A1V3wfQN3XvsfkK9hitCzr6WVBvaIv6qtJhlXpKdNRQ=="], + "@isaacs/cliui/string-width": ["string-width@5.1.2", "", { "dependencies": { "eastasianwidth": "^0.2.0", "emoji-regex": "^9.2.2", "strip-ansi": "^7.0.1" } }, "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA=="], "@isaacs/cliui/strip-ansi": ["strip-ansi@7.2.0", "", { "dependencies": { "ansi-regex": "^6.2.2" } }, "sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w=="], From 117ad1ed01877d5f041204d0060aab7844dd7c64 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 14:29:08 +0100 Subject: [PATCH 21/71] test(cli): stop the API-500 report test matching '500' inside the run id The test asserted that stderr never matches /report|500|runner\/runs/i, but stderr carries 'Running <scenario> (<run id>)' and the run id holds the UTC time as HHmmss. Any run started at hh:50:0x or 15:00:xx printed '500' and failed the test on any OS; the Windows failure in #387 started at 12:50:08. The test now pins that run id, so the case is exercised on every run, and matches 500 only as a number of its own, plus the server URL itself. Refs #387 --- apps/cli/test/commands/cli.spec.ts | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/apps/cli/test/commands/cli.spec.ts b/apps/cli/test/commands/cli.spec.ts index 341465c2..d44088f7 100644 --- a/apps/cli/test/commands/cli.spec.ts +++ b/apps/cli/test/commands/cli.spec.ts @@ -291,13 +291,26 @@ describe('demoflow run on a paired machine', () => { status = 500; const env = pairedEnv(apiUrl()); const result = await demoflow( - ['run', scenario('customers'), '--json', '--out', out], + [ + 'run', + scenario('customers'), + '--json', + '--out', + out, + // The id of the Windows run that flaked (#387): a run started at + // 12:50:08 UTC prints "125008", "500" included, on stderr. + '--run-id', + '20261026-125008-xamdgj', + ], project, env, ); expect(result.code, result.stderr).toBe(0); expect(JSON.parse(result.stdout).status).toBe('completed'); - expect(result.stderr).not.toMatch(/report|500|runner\/runs/i); + // What a printed report failure would name: the status as a number of its + // own, the endpoint or the server. Bare digits match the run id (#387). + expect(result.stderr).not.toMatch(/report|\b500\b|runner\/runs/i); + expect(result.stderr).not.toContain(apiUrl()); const index = runnerPaths({ platform: process.platform, env, From 19e839cd2fded0afbdd609a9e2071a9983c7b731 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 14:37:06 +0100 Subject: [PATCH 22/71] feat(web): Glass UI app shell around every /app page Every /app page now renders inside one shell: a glass sidebar with the brand, the nav and the machine status, a top bar with the breadcrumb and the account menu, the verify-email banner and one content column. Narrow screens open the same navigation in a bottom sheet. The theme is System, Dark or Light from the account menu. An inline script sets it before first paint and follows the OS while on System. The Overview gets stat tiles for projects, runs and failing projects. Pages drop their own back links and outer columns, and project and run pages name their breadcrumb segments instead of showing ids. --- apps/web/src/app/app/device/page.tsx | 87 +++++--------- apps/web/src/app/app/layout.tsx | 19 ++- apps/web/src/app/app/machines/page.tsx | 28 ++--- apps/web/src/app/app/page.tsx | 77 ++++++------- apps/web/src/app/app/projects/[id]/page.tsx | 12 +- .../app/projects/[id]/runs/[runId]/page.tsx | 19 +-- apps/web/src/app/app/projects/page.tsx | 28 ++--- apps/web/src/app/app/settings/page.tsx | 11 +- apps/web/src/app/layout.tsx | 14 ++- .../src/components/auth/sign-out-button.tsx | 25 ---- apps/web/src/components/brand/logo.tsx | 38 ++++++ .../components/dashboard/machines-summary.tsx | 9 +- .../components/dashboard/recent-projects.tsx | 2 +- .../web/src/components/shell/account-menu.tsx | 107 +++++++++++++++++ apps/web/src/components/shell/app-shell.tsx | 73 ++++++++++++ apps/web/src/components/shell/crumb-names.tsx | 62 ++++++++++ .../src/components/shell/machine-status.tsx | 69 +++++++++++ apps/web/src/components/shell/sidebar.tsx | 84 ++++++++++++++ apps/web/src/components/shell/top-bar.tsx | 109 ++++++++++++++++++ apps/web/src/i18n/en.ts | 59 +++++++--- apps/web/src/lib/session.ts | 9 +- apps/web/src/lib/theme.test.mjs | 24 ++-- 22 files changed, 744 insertions(+), 221 deletions(-) delete mode 100644 apps/web/src/components/auth/sign-out-button.tsx create mode 100644 apps/web/src/components/brand/logo.tsx create mode 100644 apps/web/src/components/shell/account-menu.tsx create mode 100644 apps/web/src/components/shell/app-shell.tsx create mode 100644 apps/web/src/components/shell/crumb-names.tsx create mode 100644 apps/web/src/components/shell/machine-status.tsx create mode 100644 apps/web/src/components/shell/sidebar.tsx create mode 100644 apps/web/src/components/shell/top-bar.tsx diff --git a/apps/web/src/app/app/device/page.tsx b/apps/web/src/app/app/device/page.tsx index ad877e80..a66cc9ac 100644 --- a/apps/web/src/app/app/device/page.tsx +++ b/apps/web/src/app/app/device/page.tsx @@ -1,8 +1,6 @@ import { Banner } from '@andrewbehma/glass-ui/banner'; import { Card } from '@andrewbehma/glass-ui/card'; -import Link from 'next/link'; import { redirect } from 'next/navigation'; -import { ResendButton } from '@/components/auth/resend-button'; import { DeviceApproval } from '@/components/device/device-approval'; import { DeviceCodeForm } from '@/components/device/device-code-form'; import { t } from '@/i18n'; @@ -24,60 +22,39 @@ export default async function DevicePage({ const request = code ? await getDevice(code) : undefined; return ( - <main className="mx-auto flex min-h-screen max-w-2xl flex-col gap-4 p-6"> - <header> - <Link href="/app" className="text-sm text-ink-2 underline"> - {t('device.back')} - </Link> - </header> - {user.emailVerified ? null : ( - <Banner tone="warn" title={t('device.verify.title')}> - <p className="break-words"> - {t('device.verify.body', { email: user.email })} - </p> - <div className="mt-3"> - <ResendButton - label={t('device.verify.resend')} - sentLabel={t('device.verify.resent')} - /> + // The shell's banner asks for verification; this card says why it matters. + <Card pad="lg" className="w-full max-w-2xl"> + {request && typeof request === 'object' ? ( + <> + <h1 className="text-2xl font-semibold"> + {t('device.approve.title')} + </h1> + {user.emailVerified ? null : ( + <p className="mt-2 text-sm text-ink-2">{t('device.verifyFirst')}</p> + )} + <div className="mt-4"> + <DeviceApproval request={request} canApprove={user.emailVerified} /> </div> - </Banner> + </> + ) : ( + <> + <h1 className="text-2xl font-semibold"> + {request === 'not_found' + ? t('device.notFound.title') + : t('device.code.title')} + </h1> + <div className="mt-4 flex flex-col gap-4"> + {request === 'not_found' ? ( + <p className="text-sm text-ink-2">{t('device.notFound.body')}</p> + ) : request === 'error' ? ( + <Banner tone="danger">{t('device.unavailable')}</Banner> + ) : ( + <p className="text-sm text-ink-2">{t('device.code.body')}</p> + )} + <DeviceCodeForm /> + </div> + </> )} - <Card pad="lg"> - {request && typeof request === 'object' ? ( - <> - <h1 className="text-2xl font-semibold"> - {t('device.approve.title')} - </h1> - <div className="mt-4"> - <DeviceApproval - request={request} - canApprove={user.emailVerified} - /> - </div> - </> - ) : ( - <> - <h1 className="text-2xl font-semibold"> - {request === 'not_found' - ? t('device.notFound.title') - : t('device.code.title')} - </h1> - <div className="mt-4 flex flex-col gap-4"> - {request === 'not_found' ? ( - <p className="text-sm text-ink-2"> - {t('device.notFound.body')} - </p> - ) : request === 'error' ? ( - <Banner tone="danger">{t('device.unavailable')}</Banner> - ) : ( - <p className="text-sm text-ink-2">{t('device.code.body')}</p> - )} - <DeviceCodeForm /> - </div> - </> - )} - </Card> - </main> + </Card> ); } diff --git a/apps/web/src/app/app/layout.tsx b/apps/web/src/app/app/layout.tsx index 210a2334..bb8d46a3 100644 --- a/apps/web/src/app/app/layout.tsx +++ b/apps/web/src/app/app/layout.tsx @@ -1,15 +1,28 @@ import { headers } from 'next/headers'; import { redirect } from 'next/navigation'; import type { ReactNode } from 'react'; +import { AppShell } from '@/components/shell/app-shell'; import { signInUrl } from '@/lib/return-to'; -import { getSessionUser } from '@/lib/session'; +import { getRunners, getSessionUser } from '@/lib/session'; import { RETURN_TO_HEADER } from '@/proxy'; // One guard for every present and future `/app/**` page (spec 124, decision 4). // A guest comes back to the page they asked for (spec 135, decision 6). export default async function AppLayout({ children }: { children: ReactNode }) { - if (!(await getSessionUser())) { + const user = await getSessionUser(); + if (!user) { redirect(signInUrl((await headers()).get(RETURN_TO_HEADER) ?? undefined)); } - return children; + // For the sidebar's machine status (spec #373): read when the layout + // renders, shared with the page through the request cache; no polling. + const runners = await getRunners(); + return ( + <AppShell + email={user.email} + emailVerified={user.emailVerified} + runners={runners} + > + {children} + </AppShell> + ); } diff --git a/apps/web/src/app/app/machines/page.tsx b/apps/web/src/app/app/machines/page.tsx index 79968c2b..7befa3b2 100644 --- a/apps/web/src/app/app/machines/page.tsx +++ b/apps/web/src/app/app/machines/page.tsx @@ -1,6 +1,5 @@ import { Banner } from '@andrewbehma/glass-ui/banner'; import { Card } from '@andrewbehma/glass-ui/card'; -import Link from 'next/link'; import { MachineList } from '@/components/machines/machine-list'; import { t } from '@/i18n'; import { getRunners } from '@/lib/session'; @@ -8,22 +7,15 @@ import { getRunners } from '@/lib/session'; export default async function MachinesPage() { const runners = await getRunners(); return ( - <main className="mx-auto flex min-h-screen max-w-5xl flex-col gap-4 p-6"> - <header> - <Link href="/app" className="text-sm text-ink-2 underline"> - {t('machines.back')} - </Link> - </header> - <Card pad="lg"> - <h1 className="text-2xl font-semibold">{t('machines.title')}</h1> - <div className="mt-4"> - {runners ? ( - <MachineList runners={runners} /> - ) : ( - <Banner tone="danger">{t('machines.loadFailed')}</Banner> - )} - </div> - </Card> - </main> + <Card pad="lg"> + <h1 className="text-2xl font-semibold">{t('machines.title')}</h1> + <div className="mt-4"> + {runners ? ( + <MachineList runners={runners} /> + ) : ( + <Banner tone="danger">{t('machines.loadFailed')}</Banner> + )} + </div> + </Card> ); } diff --git a/apps/web/src/app/app/page.tsx b/apps/web/src/app/app/page.tsx index 90ba9791..6035945d 100644 --- a/apps/web/src/app/app/page.tsx +++ b/apps/web/src/app/app/page.tsx @@ -1,53 +1,46 @@ -import { Banner } from '@andrewbehma/glass-ui/banner'; -import Link from 'next/link'; -import { redirect } from 'next/navigation'; -import { ResendButton } from '@/components/auth/resend-button'; -import { SignOutButton } from '@/components/auth/sign-out-button'; +import { PageHeader } from '@andrewbehma/glass-ui/page-header'; +import { StatTile } from '@andrewbehma/glass-ui/stat-tile'; import { MachinesSummary } from '@/components/dashboard/machines-summary'; import { RecentProjects } from '@/components/dashboard/recent-projects'; import { t } from '@/i18n'; -import { getRunners, getSessionUser } from '@/lib/session'; +import { overviewStats } from '@/lib/overview-stats'; +import { getRunners } from '@/lib/session'; import { getProjects } from './projects/_data'; export default async function AppPage() { - const user = await getSessionUser(); - if (!user) redirect('/sign-in'); const [projects, runners] = await Promise.all([getProjects(), getRunners()]); + const stats = projects ? overviewStats(projects) : null; + const unavailable = t('dashboard.stats.unavailable'); return ( - <main className="mx-auto flex min-h-screen max-w-2xl flex-col gap-4 p-6"> - <header className="flex flex-wrap items-center justify-between gap-3"> - <p className="min-w-0 break-words text-sm text-ink-2"> - {t('app.shell.signedInAs', { email: user.email })} - </p> - <div className="flex items-center gap-3"> - <Link href="/app/projects" className="text-sm text-ink underline"> - {t('projects.nav')} - </Link> - <Link href="/app/machines" className="text-sm text-ink underline"> - {t('app.shell.machines')} - </Link> - <Link href="/app/settings" className="text-sm text-ink underline"> - {t('app.shell.settings')} - </Link> - <SignOutButton /> + <> + <PageHeader + title={t('dashboard.title')} + description={t('dashboard.description')} + /> + <section + aria-label={t('dashboard.title')} + className="grid grid-cols-1 gap-3 tablet:grid-cols-3" + > + <StatTile + label={t('dashboard.stats.projects')} + value={stats?.projects ?? unavailable} + /> + <StatTile + label={t('dashboard.stats.runs')} + value={stats?.runs ?? unavailable} + /> + <StatTile + label={t('dashboard.stats.failing')} + value={stats?.failing ?? unavailable} + hint={t('dashboard.stats.failingHint')} + /> + </section> + <div className="grid grid-cols-1 gap-6 desktop:grid-cols-3"> + <div className="desktop:col-span-2"> + <RecentProjects projects={projects} /> </div> - </header> - {user.emailVerified ? null : ( - <Banner tone="warn" title={t('app.shell.verifyTitle')}> - <p className="break-words"> - {t('app.shell.verifyBody', { email: user.email })} - </p> - <div className="mt-3"> - <ResendButton - label={t('app.shell.resend')} - sentLabel={t('app.shell.resent')} - /> - </div> - </Banner> - )} - <h1 className="text-2xl font-semibold">{t('dashboard.title')}</h1> - <RecentProjects projects={projects} /> - <MachinesSummary runners={runners} /> - </main> + <MachinesSummary runners={runners} /> + </div> + </> ); } diff --git a/apps/web/src/app/app/projects/[id]/page.tsx b/apps/web/src/app/app/projects/[id]/page.tsx index 35726b63..32ee0aab 100644 --- a/apps/web/src/app/app/projects/[id]/page.tsx +++ b/apps/web/src/app/app/projects/[id]/page.tsx @@ -1,9 +1,9 @@ import { Banner } from '@andrewbehma/glass-ui/banner'; import { Card } from '@andrewbehma/glass-ui/card'; -import Link from 'next/link'; import { notFound } from 'next/navigation'; import { RunsTable } from '@/components/projects/runs-table'; import { StartRun } from '@/components/projects/start-run'; +import { CrumbName } from '@/components/shell/crumb-names'; import { t } from '@/i18n'; import { getFirstRuns, getProjects } from '../_data'; @@ -26,12 +26,8 @@ export default async function ProjectLibraryPage({ const project = projects?.find((candidate) => candidate.id === id); if (projects && !project) notFound(); return ( - <main className="mx-auto flex min-h-screen max-w-5xl flex-col gap-4 p-6"> - <header> - <Link href="/app/projects" className="text-sm text-ink-2 underline"> - {t('projects.back')} - </Link> - </header> + <> + {project ? <CrumbName segment={id} name={project.name} /> : null} <Card pad="lg"> <h1 className="break-words text-2xl font-semibold"> {project?.name ?? t('projects.title')} @@ -67,6 +63,6 @@ export default async function ProjectLibraryPage({ /> )} </Card> - </main> + </> ); } diff --git a/apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx b/apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx index 57b52254..74d9159a 100644 --- a/apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx +++ b/apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx @@ -5,12 +5,12 @@ import { notFound } from 'next/navigation'; import { RunPlayback } from '@/components/player/run-playback'; import { DeleteRun } from '@/components/projects/delete-run'; import { RunAgain } from '@/components/projects/run-again'; -import { RunBreadcrumbs } from '@/components/projects/run-breadcrumbs'; import { RunDetails, RunFailureBanner, } from '@/components/projects/run-details'; import { RunStatus } from '@/components/projects/run-status'; +import { CrumbName } from '@/components/shell/crumb-names'; import { t } from '@/i18n'; import { formatDate } from '@/lib/format-date'; import { formatDuration } from '@/lib/format-duration'; @@ -27,11 +27,7 @@ export default async function RunPage({ const detail = await getRunDetail(runId); if (detail === 'not_found') notFound(); if (detail === 'error') { - return ( - <main className="mx-auto flex min-h-screen max-w-5xl flex-col gap-4 p-6"> - <Banner tone="danger">{t('runPage.pageFailed')}</Banner> - </main> - ); + return <Banner tone="danger">{t('runPage.pageFailed')}</Banner>; } const { run, project, machine } = detail; if (project.id !== id) notFound(); @@ -44,12 +40,9 @@ export default async function RunPage({ scenarioPath: run.scenarioPath, }); return ( - <main className="mx-auto flex min-h-screen max-w-5xl flex-col gap-4 p-6"> - <RunBreadcrumbs - projectId={project.id} - projectName={project.name} - runName={run.scenarioName} - /> + <> + <CrumbName segment={project.id} name={project.name} /> + <CrumbName segment={run.id} name={run.scenarioName} /> <Card pad="lg"> <h1 className="break-words text-2xl font-semibold"> {t('runPage.title', { name: run.scenarioName })} @@ -139,6 +132,6 @@ export default async function RunPage({ /> </Card> <RunDetails stages={run.stages} renders={run.renders} /> - </main> + </> ); } diff --git a/apps/web/src/app/app/projects/page.tsx b/apps/web/src/app/app/projects/page.tsx index edb700ff..02d3f582 100644 --- a/apps/web/src/app/app/projects/page.tsx +++ b/apps/web/src/app/app/projects/page.tsx @@ -1,6 +1,5 @@ import { Banner } from '@andrewbehma/glass-ui/banner'; import { Card } from '@andrewbehma/glass-ui/card'; -import Link from 'next/link'; import { ProjectList } from '@/components/projects/project-list'; import { t } from '@/i18n'; import { getMachines, getProjects } from './_data'; @@ -11,22 +10,15 @@ export default async function ProjectsPage() { getMachines(), ]); return ( - <main className="mx-auto flex min-h-screen max-w-3xl flex-col gap-4 p-6"> - <header> - <Link href="/app" className="text-sm text-ink-2 underline"> - {t('projects.back')} - </Link> - </header> - <Card pad="lg"> - <h1 className="text-2xl font-semibold">{t('projects.title')}</h1> - <div className="mt-4"> - {projects ? ( - <ProjectList projects={projects} machines={machines} /> - ) : ( - <Banner tone="danger">{t('projects.loadFailed')}</Banner> - )} - </div> - </Card> - </main> + <Card pad="lg"> + <h1 className="text-2xl font-semibold">{t('projects.title')}</h1> + <div className="mt-4"> + {projects ? ( + <ProjectList projects={projects} machines={machines} /> + ) : ( + <Banner tone="danger">{t('projects.loadFailed')}</Banner> + )} + </div> + </Card> ); } diff --git a/apps/web/src/app/app/settings/page.tsx b/apps/web/src/app/app/settings/page.tsx index 26bdef6e..d2a857f6 100644 --- a/apps/web/src/app/app/settings/page.tsx +++ b/apps/web/src/app/app/settings/page.tsx @@ -1,7 +1,6 @@ import { Banner } from '@andrewbehma/glass-ui/banner'; import { buttonClassName } from '@andrewbehma/glass-ui/button'; import { Card } from '@andrewbehma/glass-ui/card'; -import Link from 'next/link'; import { redirect } from 'next/navigation'; import { UnlinkGithubButton } from '@/components/auth/unlink-github-button'; import { DeleteAccount } from '@/components/settings/delete-account'; @@ -24,12 +23,8 @@ export default async function SettingsPage({ const error = githubErrorMessage((await searchParams).error); return ( - <main className="mx-auto flex min-h-screen max-w-2xl flex-col gap-4 p-6"> - <header> - <Link href="/app" className="text-sm text-ink-2 underline"> - {t('app.settings.back')} - </Link> - </header> + // Forms read best narrower than the shell's column. + <div className="flex w-full max-w-2xl flex-col gap-6"> {error ? <Banner tone="danger">{error}</Banner> : null} <Card pad="lg"> <h1 className="text-2xl font-semibold">{t('app.settings.title')}</h1> @@ -69,6 +64,6 @@ export default async function SettingsPage({ </dl> </Card> <DeleteAccount email={user.email} /> - </main> + </div> ); } diff --git a/apps/web/src/app/layout.tsx b/apps/web/src/app/layout.tsx index f9513e03..18fa5001 100644 --- a/apps/web/src/app/layout.tsx +++ b/apps/web/src/app/layout.tsx @@ -1,5 +1,6 @@ import type { Metadata } from 'next'; import { t } from '@/i18n'; +import { THEME_BOOTSTRAP_SCRIPT } from '@/lib/theme'; import './globals.css'; export const metadata: Metadata = { @@ -12,10 +13,17 @@ export default function RootLayout({ }: { children: React.ReactNode; }) { - // Glass UI reads its appearance from these attributes: a dark developer - // tool at desk density until there is an appearance setting. + // Glass UI reads its appearance from attributes on <html>. The theme ones + // are set by the inline script before first paint (spec #373, Decision 6), + // so the server's markup differs from the client's on purpose. return ( - <html lang="en" data-theme="dark" data-scale="desk"> + <html lang="en" data-scale="desk" suppressHydrationWarning> + <head> + <script + // biome-ignore lint/security/noDangerouslySetInnerHtml: a constant, bundled script + dangerouslySetInnerHTML={{ __html: THEME_BOOTSTRAP_SCRIPT }} + /> + </head> <body>{children}</body> </html> ); diff --git a/apps/web/src/components/auth/sign-out-button.tsx b/apps/web/src/components/auth/sign-out-button.tsx deleted file mode 100644 index 2e54ffa2..00000000 --- a/apps/web/src/components/auth/sign-out-button.tsx +++ /dev/null @@ -1,25 +0,0 @@ -'use client'; - -import { Button } from '@andrewbehma/glass-ui/button'; -import { useRouter } from 'next/navigation'; -import { useState } from 'react'; -import { t } from '@/i18n'; -import { signOut } from '@/lib/api'; - -export function SignOutButton() { - const router = useRouter(); - const [pending, setPending] = useState(false); - - async function submit() { - setPending(true); - await signOut(); - router.replace('/sign-in'); - router.refresh(); - } - - return ( - <Button type="button" variant="glass" disabled={pending} onClick={submit}> - {pending ? t('app.shell.signingOut') : t('app.shell.signOut')} - </Button> - ); -} diff --git a/apps/web/src/components/brand/logo.tsx b/apps/web/src/components/brand/logo.tsx new file mode 100644 index 00000000..738974b9 --- /dev/null +++ b/apps/web/src/components/brand/logo.tsx @@ -0,0 +1,38 @@ +/** + * The DemoFlow mark: a play triangle on an accent tile, with a frame line + * under it — a recording that runs. Drawn with the accent token, so it follows + * the theme (spec #373, open question "Logo"). The owner can replace the SVG. + */ +export function Logomark({ size = 24 }: { size?: number }) { + return ( + <svg + width={size} + height={size} + viewBox="0 0 24 24" + aria-hidden="true" + className="shrink-0" + > + <rect width="24" height="24" rx="6" className="fill-accent" /> + <path d="M9.5 6.5v8l6.5-4z" className="fill-on-accent" /> + <rect + x="6" + y="17" + width="12" + height="1.75" + rx="0.875" + className="fill-on-accent" + opacity="0.7" + /> + </svg> + ); +} + +/** The mark and the name, for headers and the app sidebar. */ +export function Logo({ size = 24 }: { size?: number }) { + return ( + <span className="inline-flex items-center gap-2 font-semibold tracking-tight text-ink"> + <Logomark size={size} /> + <span>DemoFlow</span> + </span> + ); +} diff --git a/apps/web/src/components/dashboard/machines-summary.tsx b/apps/web/src/components/dashboard/machines-summary.tsx index 804bf872..fa2b60a3 100644 --- a/apps/web/src/components/dashboard/machines-summary.tsx +++ b/apps/web/src/components/dashboard/machines-summary.tsx @@ -1,3 +1,4 @@ +import { Badge } from '@andrewbehma/glass-ui/badge'; import { Banner } from '@andrewbehma/glass-ui/banner'; import { Card } from '@andrewbehma/glass-ui/card'; import { EmptyState } from '@andrewbehma/glass-ui/empty-state'; @@ -44,13 +45,15 @@ export function MachinesSummary({ runners }: { runners: Runner[] | null }) { function MachineRow({ runner }: { runner: Runner }) { return ( - <li className="flex flex-wrap items-center justify-between gap-2 border-t border-current/10 py-3 first:border-t-0 first:pt-0"> + <li className="flex flex-wrap items-center justify-between gap-2 border-t border-line py-3 first:border-t-0 first:pt-0"> <span className="min-w-0 break-words font-semibold">{runner.name}</span> <span className="flex items-center gap-3 text-sm"> <span className="inline-flex items-center gap-2"> - <span + <Badge + dot + tone={runner.online ? 'ok' : 'neutral'} aria-hidden="true" - className={`size-2.5 rounded-full ${runner.online ? 'bg-green-500' : 'bg-gray-400'}`} + className="size-2" /> {runner.online ? t('machines.status.online') diff --git a/apps/web/src/components/dashboard/recent-projects.tsx b/apps/web/src/components/dashboard/recent-projects.tsx index 80da51e4..24e26fa8 100644 --- a/apps/web/src/components/dashboard/recent-projects.tsx +++ b/apps/web/src/components/dashboard/recent-projects.tsx @@ -48,7 +48,7 @@ export function RecentProjects({ projects }: { projects: Project[] | null }) { function ProjectRow({ project }: { project: Project }) { const { lastRun } = project; return ( - <li className="flex flex-col gap-1 border-t border-current/10 py-3 first:border-t-0 first:pt-0"> + <li className="flex flex-col gap-1 border-t border-line py-3 first:border-t-0 first:pt-0"> <Link href={`/app/projects/${encodeURIComponent(project.id)}`} className="break-words font-semibold underline" diff --git a/apps/web/src/components/shell/account-menu.tsx b/apps/web/src/components/shell/account-menu.tsx new file mode 100644 index 00000000..4a240437 --- /dev/null +++ b/apps/web/src/components/shell/account-menu.tsx @@ -0,0 +1,107 @@ +'use client'; + +import { Avatar } from '@andrewbehma/glass-ui/avatar'; +import { + MenuContent, + MenuItem, + MenuLabel, + MenuRadioGroup, + MenuRadioItem, + MenuRoot, + MenuSeparator, + MenuTrigger, +} from '@andrewbehma/glass-ui/menu'; +import { useRouter } from 'next/navigation'; +import { useEffect, useState } from 'react'; +import { t } from '@/i18n'; +import { signOut } from '@/lib/api'; +import { + applyTheme, + isThemeMode, + LIGHT_QUERY, + storeTheme, + THEME_MODE_ATTRIBUTE, + THEME_MODES, + type ThemeMode, +} from '@/lib/theme'; + +/** + * The account menu in the top bar (spec #373, Decision 6): who is signed in, + * account settings, the theme and sign out. The theme is a radio group rather + * than a segmented control: glass-ui documents that a segmented control inside + * a menu is unreachable by Tab and the arrow keys. + */ +export function AccountMenu({ email }: { email: string }) { + const router = useRouter(); + const [mode, setMode] = useState<ThemeMode>('system'); + const [signingOut, setSigningOut] = useState(false); + + // The bootstrap script has already set the mode on <html>; read it back. + useEffect(() => { + const current = document.documentElement.getAttribute(THEME_MODE_ATTRIBUTE); + if (isThemeMode(current)) setMode(current); + }, []); + + function chooseTheme(value: string) { + if (!isThemeMode(value)) return; + setMode(value); + storeTheme(value, () => window.localStorage); + applyTheme( + document.documentElement, + value, + window.matchMedia(LIGHT_QUERY).matches, + ); + } + + async function leave() { + setSigningOut(true); + await signOut(); + router.replace('/sign-in'); + router.refresh(); + } + + return ( + <MenuRoot> + <MenuTrigger + aria-label={t('app.shell.account.label')} + className="rounded-full focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent" + > + <Avatar size="sm" name={email} /> + </MenuTrigger> + <MenuContent align="end"> + <MenuLabel className="normal-case tracking-normal"> + <span className="block truncate text-sm text-ink-2">{email}</span> + </MenuLabel> + <MenuSeparator /> + <MenuItem onSelect={() => router.push('/app/settings')}> + {t('app.shell.account.settings')} + </MenuItem> + <MenuSeparator /> + <MenuLabel>{t('app.shell.account.theme')}</MenuLabel> + <MenuRadioGroup value={mode} onValueChange={chooseTheme}> + {THEME_MODES.map((value) => ( + <MenuRadioItem + key={value} + value={value} + // Keep the menu open so the change can be seen and undone. + onSelect={(event) => event.preventDefault()} + > + {t(`app.shell.theme.${value}`)} + </MenuRadioItem> + ))} + </MenuRadioGroup> + <MenuSeparator /> + <MenuItem + tone="danger" + disabled={signingOut} + onSelect={(event) => { + event.preventDefault(); + void leave(); + }} + > + {signingOut ? t('app.shell.signingOut') : t('app.shell.signOut')} + </MenuItem> + </MenuContent> + </MenuRoot> + ); +} diff --git a/apps/web/src/components/shell/app-shell.tsx b/apps/web/src/components/shell/app-shell.tsx new file mode 100644 index 00000000..b642fa6d --- /dev/null +++ b/apps/web/src/components/shell/app-shell.tsx @@ -0,0 +1,73 @@ +'use client'; + +import { Banner } from '@andrewbehma/glass-ui/banner'; +import { usePathname } from 'next/navigation'; +import type { ReactNode } from 'react'; +import { ResendButton } from '@/components/auth/resend-button'; +import { t } from '@/i18n'; +import type { Runner } from '@/lib/api'; +import { activeNavId, NAV_ITEMS } from '@/lib/nav'; +import { CrumbNamesProvider } from './crumb-names'; +import { Sidebar } from './sidebar'; +import { TopBar } from './top-bar'; + +/** + * The frame around every `/app` page (spec #373, Decisions 1–3): the canvas, + * a fixed glass rail on a desktop, the top bar, the verify-email banner and + * one readable content column. Pages render their content only. + */ +export function AppShell({ + email, + emailVerified, + runners, + children, +}: { + email: string; + emailVerified: boolean; + runners: Runner[] | null; + children: ReactNode; +}) { + const pathname = usePathname(); + return ( + <CrumbNamesProvider> + <a + href="#main-content" + className="sr-only z-top rounded-control bg-paper px-3 py-2 text-ink focus:not-sr-only focus:fixed focus:top-3 focus:left-3" + > + {t('app.shell.skip')} + </a> + <div className="canvas" aria-hidden="true" /> + <div className="flex min-h-dvh gap-2 p-2"> + <aside className="sticky top-2 hidden h-[calc(100dvh-1rem)] shrink-0 desktop:block"> + <Sidebar + activeId={activeNavId(pathname, NAV_ITEMS)} + runners={runners} + /> + </aside> + <div className="flex min-w-0 flex-1 flex-col gap-2"> + <TopBar email={email} runners={runners} /> + <main + id="main-content" + tabIndex={-1} + className="mx-auto flex w-full max-w-5xl flex-col gap-6 px-2 py-4 outline-none tablet:px-4 tablet:py-6" + > + {emailVerified ? null : ( + <Banner tone="warn" title={t('app.shell.verifyTitle')}> + <p className="break-words"> + {t('app.shell.verifyBody', { email })} + </p> + <div className="mt-3"> + <ResendButton + label={t('app.shell.resend')} + sentLabel={t('app.shell.resent')} + /> + </div> + </Banner> + )} + {children} + </main> + </div> + </div> + </CrumbNamesProvider> + ); +} diff --git a/apps/web/src/components/shell/crumb-names.tsx b/apps/web/src/components/shell/crumb-names.tsx new file mode 100644 index 00000000..64596a12 --- /dev/null +++ b/apps/web/src/components/shell/crumb-names.tsx @@ -0,0 +1,62 @@ +'use client'; + +import { + createContext, + type ReactNode, + useCallback, + useContext, + useEffect, + useState, +} from 'react'; +import type { CrumbNames } from '@/lib/crumbs'; + +type Register = (segment: string, name: string) => () => void; + +const RegisterContext = createContext<Register | null>(null); +const NamesContext = createContext<CrumbNames>(new Map()); + +/** + * Holds the display names pages give their path segments (spec #373, + * Decision 5), so the breadcrumb shows a project or run name, never its id. + */ +export function CrumbNamesProvider({ children }: { children: ReactNode }) { + const [names, setNames] = useState<CrumbNames>(() => new Map()); + const register = useCallback<Register>((segment, name) => { + setNames((current) => new Map(current).set(segment, name)); + return () => + setNames((current) => { + if (current.get(segment) !== name) return current; + const next = new Map(current); + next.delete(segment); + return next; + }); + }, []); + return ( + <RegisterContext.Provider value={register}> + <NamesContext.Provider value={names}>{children}</NamesContext.Provider> + </RegisterContext.Provider> + ); +} + +/** The names registered so far, keyed by segment. */ +export function useCrumbNames(): CrumbNames { + return useContext(NamesContext); +} + +/** Names `segment` in the breadcrumb while the calling component is mounted. */ +export function useCrumbName(segment: string, name: string): void { + const register = useContext(RegisterContext); + useEffect(() => register?.(segment, name), [register, segment, name]); +} + +/** `useCrumbName` for a server page: renders nothing. */ +export function CrumbName({ + segment, + name, +}: { + segment: string; + name: string; +}) { + useCrumbName(segment, name); + return null; +} diff --git a/apps/web/src/components/shell/machine-status.tsx b/apps/web/src/components/shell/machine-status.tsx new file mode 100644 index 00000000..92dc8b59 --- /dev/null +++ b/apps/web/src/components/shell/machine-status.tsx @@ -0,0 +1,69 @@ +import { Badge } from '@andrewbehma/glass-ui/badge'; +import Link from 'next/link'; +import { t } from '@/i18n'; +import type { Runner } from '@/lib/api'; +import { onlineCount } from '@/lib/overview-stats'; + +/** Up to this many machines get a row each; more collapse to a summary. */ +export const MACHINE_ROWS = 3; + +const ROW = + 'flex min-h-8 items-center gap-2 rounded-control px-3 text-sm text-ink-2 hover:bg-hover hover:text-ink'; + +/** + * The paired machines at the bottom of the sidebar (spec #373, Decision 4): + * a row per machine with its connection, a summary past three, or a way to + * pair the first one. Read once per navigation by the layout; no polling. + */ +export function MachineStatus({ runners }: { runners: Runner[] | null }) { + return ( + <section + aria-label={t('app.shell.status.title')} + className="flex flex-col gap-0.5 border-t border-line pt-2" + > + {runners === null ? ( + <p className="px-3 text-sm text-ink-3"> + {t('app.shell.status.failed')} + </p> + ) : runners.length === 0 ? ( + <Link href="/docs/runner" className={ROW}> + {t('app.shell.status.pair')} + </Link> + ) : runners.length > MACHINE_ROWS ? ( + <Link href="/app/machines" className={ROW}> + <Badge + dot + tone={onlineCount(runners) > 0 ? 'ok' : 'neutral'} + aria-hidden="true" + className="size-2" + /> + {t('app.shell.status.summary', { + count: runners.length, + online: onlineCount(runners), + })} + </Link> + ) : ( + <ul className="flex flex-col gap-0.5"> + {runners.map((runner) => ( + <li key={runner.id}> + <Link href="/app/machines" className={ROW}> + <Badge + dot + tone={runner.online ? 'ok' : 'neutral'} + aria-hidden="true" + className="size-2 shrink-0" + /> + <span className="min-w-0 flex-1 truncate">{runner.name}</span> + <span className="sr-only"> + {runner.online + ? t('machines.status.online') + : t('machines.status.offline')} + </span> + </Link> + </li> + ))} + </ul> + )} + </section> + ); +} diff --git a/apps/web/src/components/shell/sidebar.tsx b/apps/web/src/components/shell/sidebar.tsx new file mode 100644 index 00000000..620e5c29 --- /dev/null +++ b/apps/web/src/components/shell/sidebar.tsx @@ -0,0 +1,84 @@ +'use client'; + +import { NavRail } from '@andrewbehma/glass-ui/nav-rail'; +import { + FolderKanban, + LayoutDashboard, + type LucideIcon, + Server, + Settings, +} from 'lucide-react'; +import Link from 'next/link'; +import { Logo } from '@/components/brand/logo'; +import { t } from '@/i18n'; +import type { Runner } from '@/lib/api'; +import { NAV_ITEMS, type NavIcon } from '@/lib/nav'; +import { MachineStatus } from './machine-status'; + +const ICONS: Record<NavIcon, LucideIcon> = { + overview: LayoutDashboard, + projects: FolderKanban, + machines: Server, + settings: Settings, +}; + +// Inside the drawer the sheet is the glass; the rail drops its own, so there +// is one blur per stack (vision §9). +const IN_SHEET = + 'h-auto! w-full! border-0! bg-transparent! bg-none! p-0! shadow-none! backdrop-blur-none!'; + +/** + * The app's navigation (spec #373, Decisions 1–4): the brand, the nav items + * with the active one marked, and the machine status pinned at the bottom. + * A fixed glass rail on a desktop; the same content inside the drawer. + */ +export function Sidebar({ + activeId, + runners, + inSheet = false, +}: { + activeId: string | null; + runners: Runner[] | null; + inSheet?: boolean; +}) { + return ( + <NavRail + aria-label={t('app.shell.navLabel')} + // The drawer and the rail are never on screen together, but both stay + // mounted on a resize; separate ids keep their capsules apart. + layoutId={inSheet ? 'sheet-nav' : 'rail-nav'} + className={inSheet ? IN_SHEET : 'h-full'} + head={ + inSheet ? undefined : ( + // As tall as the top bar's row (rail p-2 + h-10 = top bar h-14). + <Link + href="/app" + aria-label={t('app.shell.home')} + className="flex h-10 items-center rounded-control px-3" + > + <Logo size={22} /> + </Link> + ) + } + groups={[ + { + id: 'workspace', + title: t('app.shell.navGroup'), + items: NAV_ITEMS.map((item) => ({ + id: item.id, + label: t(item.label), + icon: ICONS[item.icon], + href: item.href, + active: item.id === activeId, + })), + }, + ]} + footer={<MachineStatus runners={runners} />} + link={({ href, className, children, ...rest }) => ( + <Link href={href} className={className} {...rest}> + {children} + </Link> + )} + /> + ); +} diff --git a/apps/web/src/components/shell/top-bar.tsx b/apps/web/src/components/shell/top-bar.tsx new file mode 100644 index 00000000..cf25710b --- /dev/null +++ b/apps/web/src/components/shell/top-bar.tsx @@ -0,0 +1,109 @@ +'use client'; + +import { Breadcrumb } from '@andrewbehma/glass-ui/breadcrumb'; +import { SheetContent, SheetRoot } from '@andrewbehma/glass-ui/sheet'; +import { Menu } from 'lucide-react'; +import Link from 'next/link'; +import { usePathname } from 'next/navigation'; +import { useEffect, useMemo, useState } from 'react'; +import { Logomark } from '@/components/brand/logo'; +import { t } from '@/i18n'; +import type { Runner } from '@/lib/api'; +import { type CrumbKind, crumbsFor } from '@/lib/crumbs'; +import { activeNavId, NAV_ITEMS } from '@/lib/nav'; +import { AccountMenu } from './account-menu'; +import { useCrumbNames } from './crumb-names'; +import { Sidebar } from './sidebar'; + +/** Tailwind's `desktop:` breakpoint, where the rail replaces the drawer. */ +const DESKTOP_QUERY = '(min-width: 1024px)'; + +function crumbLabels(): Record<CrumbKind, string> { + return { + overview: t('app.shell.nav.overview'), + projects: t('app.shell.nav.projects'), + project: t('app.shell.crumbs.project'), + run: t('app.shell.crumbs.run'), + machines: t('app.shell.nav.machines'), + settings: t('app.shell.nav.settings'), + device: t('app.shell.crumbs.device'), + }; +} + +/** + * The bar above every app page (spec #373, Decisions 2, 5, 6): the drawer + * button on narrow screens, the breadcrumb, and the account menu. + */ +export function TopBar({ + email, + runners, +}: { + email: string; + runners: Runner[] | null; +}) { + const pathname = usePathname(); + const names = useCrumbNames(); + const crumbs = useMemo( + () => crumbsFor(pathname, names, crumbLabels()), + [pathname, names], + ); + const [navOpen, setNavOpen] = useState(false); + + // Following a link in the drawer closes it. + // biome-ignore lint/correctness/useExhaustiveDependencies: runs on navigation + useEffect(() => setNavOpen(false), [pathname]); + + // Widening to a desktop closes it too: the rail is on screen there. + useEffect(() => { + const query = window.matchMedia(DESKTOP_QUERY); + const close = () => { + if (query.matches) setNavOpen(false); + }; + query.addEventListener('change', close); + return () => query.removeEventListener('change', close); + }, []); + + return ( + <header className="glass sticky top-2 z-chrome flex h-14 items-center gap-2 rounded-surface px-2 tablet:px-3"> + <SheetRoot open={navOpen} onOpenChange={setNavOpen}> + <button + type="button" + aria-label={t('app.shell.openNav')} + aria-expanded={navOpen} + onClick={() => setNavOpen(true)} + className="inline-flex size-10 shrink-0 items-center justify-center rounded-control text-ink-2 hover:bg-hover hover:text-ink desktop:hidden" + > + <Menu aria-hidden="true" className="size-5" /> + </button> + <SheetContent title={t('app.shell.navSheet')} side="bottom"> + <div className="pb-4"> + <Sidebar + activeId={activeNavId(pathname, NAV_ITEMS)} + runners={runners} + inSheet + /> + </div> + </SheetContent> + </SheetRoot> + <Link + href="/app" + aria-label={t('app.shell.home')} + className="inline-flex size-10 shrink-0 items-center justify-center rounded-control desktop:hidden" + > + <Logomark size={22} /> + </Link> + <Breadcrumb + items={crumbs} + aria-label={t('app.shell.crumbs.label')} + overflowLabel={t('app.shell.crumbs.overflow')} + className="min-w-0 flex-1 px-1" + link={({ href, className, children, ...rest }) => ( + <Link href={href} className={className} {...rest}> + {children} + </Link> + )} + /> + <AccountMenu email={email} /> + </header> + ); +} diff --git a/apps/web/src/i18n/en.ts b/apps/web/src/i18n/en.ts index 3e03c757..27b8858f 100644 --- a/apps/web/src/i18n/en.ts +++ b/apps/web/src/i18n/en.ts @@ -4,7 +4,6 @@ export const en = { app: { tagline: 'Verified, polished demo videos of the features you ship.', shell: { - signedInAs: 'Signed in as {email}', signOut: 'Sign out', signingOut: 'Signing out…', verifyTitle: 'Verify your email', @@ -12,12 +11,44 @@ export const en = { resend: 'Resend email', resending: 'Sending…', resent: 'Verification email sent. Check your inbox.', - settings: 'Account settings', - machines: 'Machines', + skip: 'Skip to content', + home: 'DemoFlow, overview', + navLabel: 'Main', + navGroup: 'Workspace', + openNav: 'Open navigation', + navSheet: 'Navigation', + nav: { + overview: 'Overview', + projects: 'Projects', + machines: 'Machines', + settings: 'Settings', + }, + crumbs: { + label: 'Breadcrumb', + overflow: 'Show the path', + project: 'Project', + run: 'Run', + device: 'Pair a machine', + }, + account: { + label: 'Account menu', + settings: 'Account settings', + theme: 'Theme', + }, + theme: { + system: 'System', + dark: 'Dark', + light: 'Light', + }, + status: { + title: 'Machines', + summary: '{count} machines · {online} online', + pair: 'Pair a machine', + failed: 'Machines unavailable', + }, }, settings: { title: 'Account settings', - back: 'Back to your projects', email: 'Email', github: { title: 'GitHub', @@ -34,7 +65,6 @@ export const en = { }, }, device: { - back: 'Back to your projects', code: { title: 'Pair a machine', body: 'Run demoflow login in a terminal and enter the code it prints.', @@ -48,12 +78,8 @@ export const en = { body: 'It may have expired, been used, or been mistyped. Run demoflow login again for a new one.', }, unavailable: 'We could not load this code. Try again in a moment.', - verify: { - title: 'Verify your email first', - body: 'Only a verified account can pair a machine. We sent a link to {email}.', - resend: 'Resend email', - resent: 'Verification email sent. Check your inbox.', - }, + verifyFirst: + 'Only a verified account can pair a machine. Verify your email first.', approve: { title: 'Approve this machine?', code: 'Code', @@ -87,6 +113,14 @@ export const en = { }, dashboard: { title: 'Overview', + description: 'Your projects, their latest runs and your machines.', + stats: { + projects: 'Projects', + runs: 'Runs', + failing: 'Failing', + failingHint: 'Latest run failed', + unavailable: '—', + }, projects: { title: 'Recent projects', all: 'All projects', @@ -110,7 +144,6 @@ export const en = { }, machines: { title: 'Machines', - back: 'Back to your projects', empty: { title: 'No machines paired yet', body: 'Run this in a terminal on the machine you want to pair:', @@ -172,8 +205,6 @@ export const en = { }, projects: { title: 'Projects', - back: 'Back to your projects', - nav: 'Projects', loadFailed: 'We could not load your projects. Try again in a moment.', empty: { title: 'No projects yet', diff --git a/apps/web/src/lib/session.ts b/apps/web/src/lib/session.ts index 96678185..beff3791 100644 --- a/apps/web/src/lib/session.ts +++ b/apps/web/src/lib/session.ts @@ -28,12 +28,15 @@ export const getSessionUser = cache(async (): Promise<AccountUser | null> => { return result.ok ? result.data.user : null; }); -/** The signed-in user's paired machines, or null when the API fails. */ -export async function getRunners(): Promise<Runner[] | null> { +/** + * The signed-in user's paired machines, or null when the API fails. Cached + * per request, so the shell's machine status and a page share one call. + */ +export const getRunners = cache(async (): Promise<Runner[] | null> => { const cookie = (await cookies()).toString(); const result = await listRunners({ baseUrl: apiUrl(), cookie }); return result.ok ? result.data.runners : null; -} +}); /** * A pending device code: the request, `'not_found'` for an unknown, expired or diff --git a/apps/web/src/lib/theme.test.mjs b/apps/web/src/lib/theme.test.mjs index c57e1c62..feec690e 100644 --- a/apps/web/src/lib/theme.test.mjs +++ b/apps/web/src/lib/theme.test.mjs @@ -30,10 +30,22 @@ test('system follows the preference; dark and light ignore it', () => { }); test('a stored mode is read back; anything else is system', () => { - assert.equal(readStoredTheme(() => memoryStorage({ 'df-theme': 'light' })), 'light'); - assert.equal(readStoredTheme(() => memoryStorage({ 'df-theme': 'dark' })), 'dark'); - assert.equal(readStoredTheme(() => memoryStorage({ 'df-theme': 'neon' })), 'system'); - assert.equal(readStoredTheme(() => memoryStorage()), 'system'); + assert.equal( + readStoredTheme(() => memoryStorage({ 'df-theme': 'light' })), + 'light', + ); + assert.equal( + readStoredTheme(() => memoryStorage({ 'df-theme': 'dark' })), + 'dark', + ); + assert.equal( + readStoredTheme(() => memoryStorage({ 'df-theme': 'neon' })), + 'system', + ); + assert.equal( + readStoredTheme(() => memoryStorage()), + 'system', + ); }); test('system clears the key; dark and light store it', () => { @@ -73,9 +85,7 @@ function boot({ storage, prefersLight }) { const window = { matchMedia: () => query }; // A browser that blocks storage throws on any use of `localStorage`. const localStorage = - storage === 'blocked' - ? new Proxy({}, { get: blocked }) - : storage; + storage === 'blocked' ? new Proxy({}, { get: blocked }) : storage; new Function('document', 'window', 'localStorage', THEME_BOOTSTRAP_SCRIPT)( { documentElement: root }, window, From c2e8c4998b2a6cb863cb7fd29e404daaba7713db Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 14:39:35 +0100 Subject: [PATCH 23/71] refactor(web): close the nav drawer with Glass UI's useBreakpoint --- apps/web/src/components/shell/top-bar.tsx | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/apps/web/src/components/shell/top-bar.tsx b/apps/web/src/components/shell/top-bar.tsx index cf25710b..d4ee4756 100644 --- a/apps/web/src/components/shell/top-bar.tsx +++ b/apps/web/src/components/shell/top-bar.tsx @@ -2,6 +2,7 @@ import { Breadcrumb } from '@andrewbehma/glass-ui/breadcrumb'; import { SheetContent, SheetRoot } from '@andrewbehma/glass-ui/sheet'; +import { useBreakpoint } from '@andrewbehma/glass-ui/use-breakpoint'; import { Menu } from 'lucide-react'; import Link from 'next/link'; import { usePathname } from 'next/navigation'; @@ -15,9 +16,6 @@ import { AccountMenu } from './account-menu'; import { useCrumbNames } from './crumb-names'; import { Sidebar } from './sidebar'; -/** Tailwind's `desktop:` breakpoint, where the rail replaces the drawer. */ -const DESKTOP_QUERY = '(min-width: 1024px)'; - function crumbLabels(): Record<CrumbKind, string> { return { overview: t('app.shell.nav.overview'), @@ -54,14 +52,10 @@ export function TopBar({ useEffect(() => setNavOpen(false), [pathname]); // Widening to a desktop closes it too: the rail is on screen there. + const breakpoint = useBreakpoint(); useEffect(() => { - const query = window.matchMedia(DESKTOP_QUERY); - const close = () => { - if (query.matches) setNavOpen(false); - }; - query.addEventListener('change', close); - return () => query.removeEventListener('change', close); - }, []); + if (breakpoint === 'desktop') setNavOpen(false); + }, [breakpoint]); return ( <header className="glass sticky top-2 z-chrome flex h-14 items-center gap-2 rounded-surface px-2 tablet:px-3"> From 9b61ad477ee6d8c66343e956dfd5e60d3ec04374 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 14:41:51 +0100 Subject: [PATCH 24/71] fix(cli): list check-pass scenarios from the canonical project root --- apps/cli/src/commands/run.ts | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/apps/cli/src/commands/run.ts b/apps/cli/src/commands/run.ts index 4fc41b6e..c4075ccb 100644 --- a/apps/cli/src/commands/run.ts +++ b/apps/cli/src/commands/run.ts @@ -38,6 +38,7 @@ import { import { nodeLaunchFs } from '../runner/launch/checks.ts'; import { LIST_MAX_SCENARIOS, listScenarios } from '../runner/launch/list.ts'; import { + canonicalRoot, defaultReportDeps, type ReportDeps, reportRun, @@ -391,7 +392,9 @@ async function passFiles( exclude: readonly string[], io: Io, ): Promise<string[]> { - const listing = await listScenarios(root, nodeLaunchFs, fragmentsDir); + // The listing compares real paths: a Windows 8.3 root would list nothing. + const real = await canonicalRoot(root); + const listing = await listScenarios(real, nodeLaunchFs, fragmentsDir); const excluded = new Set( exclude.map((id) => id.startsWith(SCENARIOS_PREFIX) ? id : `${SCENARIOS_PREFIX}${id}`, @@ -409,7 +412,7 @@ async function passFiles( } return listing.scenarios .filter((scenario) => !excluded.has(scenario.id)) - .map((scenario) => path.join(root, ...scenario.id.split('/'))); + .map((scenario) => path.join(real, ...scenario.id.split('/'))); } const SCENARIOS_PREFIX = 'demoflow/'; From 013fcffff896b8792f2de3077c06b5bd6aba75d3 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 14:44:22 +0100 Subject: [PATCH 25/71] test(demo): record the Glass UI app shell walk-through Adds the shared sign-in fragment the card demos include in setup, and the C-201 scenario: Overview, sidebar navigation with the breadcrumb following it, and the theme switch in the account menu. --- ...-glass-ui-app-shell-glass-sideba.demo.json | 70 +++++++++++++++++++ demoflow/fragments/sign-in.json | 31 ++++++++ 2 files changed, 101 insertions(+) create mode 100644 demoflow/cards/C-201-feat-web-glass-ui-app-shell-glass-sideba.demo.json create mode 100644 demoflow/fragments/sign-in.json diff --git a/demoflow/cards/C-201-feat-web-glass-ui-app-shell-glass-sideba.demo.json b/demoflow/cards/C-201-feat-web-glass-ui-app-shell-glass-sideba.demo.json new file mode 100644 index 00000000..6d68338b --- /dev/null +++ b/demoflow/cards/C-201-feat-web-glass-ui-app-shell-glass-sideba.demo.json @@ -0,0 +1,70 @@ +{ + "schemaVersion": 1, + "name": "Glass UI app shell", + "description": "Sign in off camera, then walk the new app shell: the Overview with its stat tiles, the sidebar navigation with the breadcrumb following it, and the theme switch in the account menu.", + "viewport": { "width": 1280, "height": 720 }, + "setup": [ + { "action": "include", "fragment": "sign-in", "with": { "next": "/app" } } + ], + "steps": [ + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Overview", "exact": true } + }, + { + "action": "assertVisible", + "target": { "role": "navigation", "name": "Main", "exact": true } + }, + { + "action": "click", + "target": { "role": "link", "name": "Projects", "exact": true } + }, + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Projects", "exact": true } + }, + { + "action": "assertText", + "target": { "role": "navigation", "name": "Breadcrumb" }, + "text": "Projects" + }, + { + "action": "click", + "target": { "role": "link", "name": "Machines", "exact": true } + }, + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Machines", "exact": true } + }, + { + "action": "click", + "target": { "role": "button", "name": "Account menu" } + }, + { + "action": "click", + "target": { "role": "menuitemradio", "name": "Light", "exact": true } + }, + { "action": "press", "key": "Escape" }, + { + "action": "click", + "target": { + "role": "link", + "name": "DemoFlow, overview", + "exact": true + } + }, + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Overview", "exact": true } + }, + { + "action": "click", + "target": { "role": "button", "name": "Account menu" } + }, + { + "action": "click", + "target": { "role": "menuitemradio", "name": "Dark", "exact": true } + }, + { "action": "press", "key": "Escape" } + ] +} diff --git a/demoflow/fragments/sign-in.json b/demoflow/fragments/sign-in.json new file mode 100644 index 00000000..e31070b8 --- /dev/null +++ b/demoflow/fragments/sign-in.json @@ -0,0 +1,31 @@ +{ + "schemaVersion": 1, + "description": "Signs in with the demo account and lands on an /app page.", + "params": { + "next": { + "description": "The /app page to land on once signed in.", + "default": "/app" + } + }, + "steps": [ + { "action": "navigate", "path": "/sign-in?next={{params.next}}" }, + { + "action": "fill", + "target": { "label": "Email" }, + "valueFrom": { "env": "DEMO_LOGIN_EMAIL" } + }, + { + "action": "fill", + "target": { "label": "Password", "exact": true }, + "valueFrom": { "env": "DEMO_LOGIN_PASSWORD" } + }, + { + "action": "click", + "target": { "role": "button", "name": "Sign in", "exact": true } + }, + { + "action": "waitFor", + "target": { "role": "navigation", "name": "Breadcrumb" } + } + ] +} From 5e4710698371b0bdbf60b89ede4a77a59032c58d Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 14:51:00 +0100 Subject: [PATCH 26/71] chore(deploy): daily backups of the production database backup.sh dumps demoflow-production-postgres with pg_dump -Fc into /home/archi/backups/demoflow-production (dir 700, dumps 600), verifies the dump with pg_restore --list and keeps the newest 14. A failed dump exits non-zero and leaves existing dumps untouched. restore.sh replaces the database from a dump in one transaction, stopping the API meanwhile, and refuses without --yes-replace-production-database. install-backup-timer.sh is the one-time host setup for a daily systemd user timer; refresh.sh copies all three scripts into the stack directory. test-backup.sh checks the scripts against throwaway Postgres containers. Closes #345 --- deploy/README.md | 76 +++++++++++++- deploy/production/backup.sh | 50 ++++++++++ deploy/production/install-backup-timer.sh | 52 ++++++++++ deploy/production/refresh.sh | 2 +- deploy/production/restore.sh | 54 ++++++++++ deploy/production/test-backup.sh | 115 ++++++++++++++++++++++ 6 files changed, 346 insertions(+), 3 deletions(-) create mode 100755 deploy/production/backup.sh create mode 100755 deploy/production/install-backup-timer.sh create mode 100755 deploy/production/restore.sh create mode 100755 deploy/production/test-backup.sh diff --git a/deploy/README.md b/deploy/README.md index b92a16d9..5509743b 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -322,8 +322,8 @@ nothing with it: | Images | `demoflow-{api,web}:staging` | `demoflow-{api,web}:production` | | Tunnel | `demoflow-app` | `demoflow-prod` | -Nothing is published on the host. Backups of the production database are not -set up yet. +Nothing is published on the host. The production database is backed up daily +(see *Backups of the production database*). ### One-time setup @@ -350,6 +350,8 @@ The Woodpecker settings are the staging ones; nothing else is needed. | `/home/archi/stacks/demoflow-production/up.sh` | starts the stack from the images already built | | `/home/archi/stacks/demoflow-production/down.sh` | stops it; the volumes are kept | | `sh deploy/production/refresh.sh` (from a checkout of `main`) | what `deploy-production` runs | +| `/home/archi/stacks/demoflow-production/backup.sh` | dumps the database now (see below) | +| `/home/archi/stacks/demoflow-production/restore.sh <dump> --yes-replace-production-database` | replaces the database with a dump | Secrets, migrations, zero-drop deploys, the runner socket and `530` / error 1033 behave as on staging (see above), with `demoflow-production-*` container @@ -371,3 +373,73 @@ Hidden until both `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` are set in `https://demoflow.luna-realm.com` and authorization callback URL `https://demoflow.luna-realm.com/api/auth/github/callback`, puts its client id and secret in `env/api.env` on the host, and restarts the API container. + +### Backups of the production database + +A systemd user timer runs `backup.sh` every day at 03:30 UTC (plus up to 10 +minutes of random delay). The script runs `pg_dump -Fc` inside +`demoflow-production-postgres` and writes +`/home/archi/backups/demoflow-production/demoflow-production-<UTC timestamp>.dump`. +The directory is mode 700 and each dump 600. The shares volume is not backed +up (see *Shared videos on staging*). + +- **Retention.** The newest 14 dumps are kept; older ones are deleted after a + new dump has been written and `pg_restore --list` has read it back. +- **A failed dump** exits non-zero, deletes its partial file and leaves every + existing dump and `last-backup.env` as they were. The timer's service then + shows as failed. +- **Off-host copies** are not made: the dumps live on the same disk as the + database, so they protect against a bad migration or a deleted row, not + against losing the host. + +#### One-time setup + +`refresh.sh` copies `backup.sh`, `restore.sh` and `install-backup-timer.sh` into +the stack directory on every deploy; the pipeline never installs the timer. +Once, on the host, as the operator (uid 1000, in the `docker` group): + +```sh +/home/archi/stacks/demoflow-production/install-backup-timer.sh +sudo loginctl enable-linger archi # if the script says lingering is off +``` + +It writes `demoflow-production-backup.service` and `.timer` to +`~/.config/systemd/user`, enables the timer and lists its next run. Lingering +keeps user timers running when nobody is logged in. Running the script again +rewrites the units. + +#### Checking the last backup + +```sh +cat /home/archi/backups/demoflow-production/last-backup.env # file, time and size of the last good dump +systemctl --user list-timers demoflow-production-backup.timer # last and next run +systemctl --user status demoflow-production-backup.service # result of the last run +journalctl --user -u demoflow-production-backup.service -n 50 # its output +ls -l /home/archi/backups/demoflow-production +``` + +`last-backup.env` changes only on success, so a `LAST_BACKUP_AT` older than a +day means the backup has stopped working. + +#### Restoring + +```sh +/home/archi/stacks/demoflow-production/restore.sh \ + /home/archi/backups/demoflow-production/demoflow-production-<timestamp>.dump \ + --yes-replace-production-database +``` + +Without the flag it only says what it would do. With it, it checks the dump is +readable, stops `demoflow-production-api`, restores with +`pg_restore --clean --if-exists --single-transaction` — a failed restore rolls +back and leaves the database as it was — and starts the API again either way. +Take a fresh `backup.sh` first if the current data may still be needed. + +#### Testing the scripts + +`sh deploy/production/test-backup.sh`, from a checkout on a host with Docker, +runs both scripts against two throwaway Postgres containers, never the +production one: a backup restores with the same row counts (also over a +database that has drifted, with a stand-in API container stopped and started), +dumps beyond the newest 14 are deleted, a failed dump exits non-zero and changes +nothing, and `restore.sh` refuses without the flag. diff --git a/deploy/production/backup.sh b/deploy/production/backup.sh new file mode 100755 index 00000000..9c3efd9d --- /dev/null +++ b/deploy/production/backup.sh @@ -0,0 +1,50 @@ +#!/bin/sh +# Dumps the production database (pg_dump -Fc) into BACKUP_DIR and keeps the +# newest KEEP dumps. Run daily on the host by the systemd user timer +# demoflow-production-backup.timer (deploy/README.md), or by hand. +# +# A failed dump exits non-zero, removes its partial file and deletes nothing +# else: old dumps are pruned only after a new one is written and verified. +set -eu + +CONTAINER="${CONTAINER:-demoflow-production-postgres}" +DB_NAME="${DB_NAME:-demoflow}" +DB_USER="${DB_USER:-postgres}" +BACKUP_DIR="${BACKUP_DIR:-/home/archi/backups/demoflow-production}" +KEEP="${KEEP:-14}" + +umask 077 +mkdir -p "$BACKUP_DIR" +chmod 700 "$BACKUP_DIR" + +stamp="$(date -u +%Y%m%dT%H%M%SZ)" +dump="$BACKUP_DIR/demoflow-production-$stamp.dump" +partial="$BACKUP_DIR/.partial-$stamp.dump" +trap 'rm -f "$partial"' EXIT + +if ! docker exec "$CONTAINER" pg_dump -U "$DB_USER" -Fc "$DB_NAME" >"$partial"; then + echo "backup failed: pg_dump in $CONTAINER exited non-zero; previous dumps kept" >&2 + exit 1 +fi +# A dump pg_restore cannot list is no backup. +if ! docker exec -i "$CONTAINER" pg_restore --list >/dev/null <"$partial"; then + echo "backup failed: pg_restore cannot read the new dump; previous dumps kept" >&2 + exit 1 +fi + +chmod 600 "$partial" +mv "$partial" "$dump" + +# Timestamps sort lexically, so the newest come first in reverse order. +ls -1 "$BACKUP_DIR"/demoflow-production-*.dump | sort -r | tail -n +"$((KEEP + 1))" | while IFS= read -r old; do + rm -f "$old" + echo "removed $old" +done + +{ + echo "LAST_BACKUP=$dump" + echo "LAST_BACKUP_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)" + echo "LAST_BACKUP_BYTES=$(wc -c <"$dump" | tr -d ' ')" +} >"$BACKUP_DIR/last-backup.env" + +echo "wrote $dump" diff --git a/deploy/production/install-backup-timer.sh b/deploy/production/install-backup-timer.sh new file mode 100755 index 00000000..07379a82 --- /dev/null +++ b/deploy/production/install-backup-timer.sh @@ -0,0 +1,52 @@ +#!/bin/sh +# One-time setup, run by the operator on the host (not by the pipeline): +# installs and starts the systemd user timer that runs backup.sh daily. +# +# /home/archi/stacks/demoflow-production/install-backup-timer.sh +# +# Safe to run again: it rewrites the units and restarts the timer. +set -eu + +PRODUCTION_DIR="${PRODUCTION_DIR:-/home/archi/stacks/demoflow-production}" +UNIT_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user" +NAME=demoflow-production-backup + +[ -x "$PRODUCTION_DIR/backup.sh" ] \ + || { echo "$PRODUCTION_DIR/backup.sh is missing — deploy production first (deploy/README.md)" >&2; exit 1; } + +mkdir -p "$UNIT_DIR" + +cat >"$UNIT_DIR/$NAME.service" <<EOF +[Unit] +Description=Back up the DemoFlow production database +After=docker.service + +[Service] +Type=oneshot +ExecStart=$PRODUCTION_DIR/backup.sh +EOF + +# Persistent: a run missed while the host was off happens at the next boot. +cat >"$UNIT_DIR/$NAME.timer" <<EOF +[Unit] +Description=Daily backup of the DemoFlow production database + +[Timer] +OnCalendar=*-*-* 03:30:00 UTC +RandomizedDelaySec=10min +Persistent=true + +[Install] +WantedBy=timers.target +EOF + +systemctl --user daemon-reload +systemctl --user enable --now "$NAME.timer" + +# Without lingering, user timers stop when the operator logs out. +if [ "$(loginctl show-user "$(id -un)" -p Linger --value 2>/dev/null || echo no)" != yes ]; then + echo "Lingering is off: the timer runs only while you are logged in. Turn it on with:" >&2 + echo " sudo loginctl enable-linger $(id -un)" >&2 +fi + +systemctl --user list-timers "$NAME.timer" diff --git a/deploy/production/refresh.sh b/deploy/production/refresh.sh index 784c2cf8..e43f791f 100755 --- a/deploy/production/refresh.sh +++ b/deploy/production/refresh.sh @@ -63,7 +63,7 @@ fill_if_empty POSTGRES_PASSWORD "$(hex)" "$PRODUCTION_DIR/.env" # ── stack files: always the commit's own ──────────────────────────────────── caddy_changed=false cmp -s "$SRC/Caddyfile" "$PRODUCTION_DIR/Caddyfile" || caddy_changed=true -for file in docker-compose.yml Caddyfile up.sh down.sh status.sh; do +for file in docker-compose.yml Caddyfile up.sh down.sh status.sh backup.sh restore.sh install-backup-timer.sh; do cp "$SRC/$file" "$PRODUCTION_DIR/$file" done chmod +x "$PRODUCTION_DIR"/*.sh diff --git a/deploy/production/restore.sh b/deploy/production/restore.sh new file mode 100755 index 00000000..fc613a2d --- /dev/null +++ b/deploy/production/restore.sh @@ -0,0 +1,54 @@ +#!/bin/sh +# Restores a dump written by backup.sh into the production database, replacing +# what is there. Run on the host: +# +# restore.sh <dump> --yes-replace-production-database +# +# Without the flag it only says what it would do. The API is stopped during the +# restore so nothing writes into a half-restored database, and started again +# afterwards whether the restore worked or not. +set -eu + +CONTAINER="${CONTAINER:-demoflow-production-postgres}" +API_CONTAINER="${API_CONTAINER:-demoflow-production-api}" +DB_NAME="${DB_NAME:-demoflow}" +DB_USER="${DB_USER:-postgres}" +CONFIRM=--yes-replace-production-database + +usage() { + echo "usage: $0 <dump> $CONFIRM" >&2 + exit 2 +} + +[ $# -ge 1 ] || usage +dump="$1" +[ -f "$dump" ] || { echo "no such dump: $dump" >&2; exit 1; } + +if [ "${2:-}" != "$CONFIRM" ]; then + echo "This replaces database '$DB_NAME' in $CONTAINER with $dump." >&2 + echo "Re-run with $CONFIRM to do it." >&2 + exit 2 +fi + +docker exec -i "$CONTAINER" pg_restore --list >/dev/null <"$dump" \ + || { echo "$dump is not a dump pg_restore can read" >&2; exit 1; } + +api_stopped=false +if [ "$(docker inspect -f '{{.State.Running}}' "$API_CONTAINER" 2>/dev/null || echo false)" = true ]; then + echo "stopping $API_CONTAINER" + docker stop "$API_CONTAINER" >/dev/null + api_stopped=true +fi +restart_api() { + if [ "$api_stopped" = true ]; then + echo "starting $API_CONTAINER" + docker start "$API_CONTAINER" >/dev/null + fi +} +trap restart_api EXIT + +# One transaction: a failed restore leaves the database as it was. +docker exec -i "$CONTAINER" pg_restore -U "$DB_USER" -d "$DB_NAME" \ + --clean --if-exists --no-owner --single-transaction --exit-on-error <"$dump" + +echo "restored $dump into $DB_NAME" diff --git a/deploy/production/test-backup.sh b/deploy/production/test-backup.sh new file mode 100755 index 00000000..7af6b70a --- /dev/null +++ b/deploy/production/test-backup.sh @@ -0,0 +1,115 @@ +#!/bin/sh +# Checks backup.sh and restore.sh against two throwaway Postgres containers — +# never the production one. Run from a checkout on a host with Docker: +# +# sh deploy/production/test-backup.sh +# +# 1. A dump of a seeded database restores into an empty one with the same row +# counts; the directory is 700 and the dump 600. +# 2. With more than 14 dumps, the oldest are deleted. +# 3. A failed dump exits non-zero and leaves the existing dumps untouched. +# 4. restore.sh refuses without its confirmation flag. +set -eu + +HERE="$(cd "$(dirname "$0")" && pwd)" +TAG="demoflow-backup-test-${NAUTELLE_CARD:-$$}" +SRC_DB="$TAG-src" +DST_DB="$TAG-dst" +API="$TAG-api" +WORK="$(mktemp -d)" +BACKUP_DIR="$WORK/backups" + +cleanup() { + docker rm -f "$SRC_DB" "$DST_DB" "$API" >/dev/null 2>&1 || true + rm -rf "$WORK" +} +trap cleanup EXIT + +fail() { echo "FAIL: $*" >&2; exit 1; } + +start_db() { + docker run -d --name "$1" -e POSTGRES_PASSWORD=test -e POSTGRES_DB=demoflow postgres:16.5-alpine >/dev/null +} +wait_db() { + tries=0 + until docker exec "$1" psql -U postgres -d demoflow -c 'select 1' >/dev/null 2>&1; do + tries=$((tries + 1)) + [ "$tries" -lt 60 ] || fail "$1 did not start" + sleep 1 + done +} +psql_in() { + container="$1" + shift + docker exec -i "$container" psql -U postgres -d demoflow -v ON_ERROR_STOP=1 -tA "$@" +} +counts() { + psql_in "$1" -c "select (select count(*) from account) || ' ' || (select count(*) from run)" | sed -n '1p' +} + +start_db "$SRC_DB" +start_db "$DST_DB" +wait_db "$SRC_DB" +wait_db "$DST_DB" + +psql_in "$SRC_DB" >/dev/null <<'SQL' +create table account (id serial primary key, email text not null unique); +create table run (id serial primary key, account_id int not null references account(id), name text); +insert into account (email) select 'user' || g || '@example.test' from generate_series(1, 137) g; +insert into run (account_id, name) select 1 + g % 137, 'run ' || g from generate_series(1, 1009) g; +SQL + +export BACKUP_DIR CONTAINER="$SRC_DB" + +echo "── 1. backup and restore" +sh "$HERE/backup.sh" +dump="$(ls -1 "$BACKUP_DIR"/demoflow-production-*.dump)" +[ "$(stat -c %a "$BACKUP_DIR")" = 700 ] || fail "backup dir is not 700" +[ "$(stat -c %a "$dump")" = 600 ] || fail "dump is not 600" +grep -q "^LAST_BACKUP=$dump$" "$BACKUP_DIR/last-backup.env" || fail "last-backup.env does not name the dump" + +CONTAINER="$DST_DB" API_CONTAINER="$TAG-no-api" sh "$HERE/restore.sh" "$dump" --yes-replace-production-database +want="$(counts "$SRC_DB")" +got="$(counts "$DST_DB")" +[ "$want" = "137 1009" ] || fail "source counts are '$want'" +[ "$got" = "$want" ] || fail "restored counts '$got', want '$want'" +echo "row counts match: $got" + +# Again over a database that has drifted, with a stand-in API container that +# must be running again afterwards. +psql_in "$DST_DB" -c "insert into account (email) values ('late@example.test')" >/dev/null +docker run -d --name "$API" alpine:3.20 sleep 600 >/dev/null +CONTAINER="$DST_DB" API_CONTAINER="$API" sh "$HERE/restore.sh" "$dump" --yes-replace-production-database +got="$(counts "$DST_DB")" +[ "$got" = "$want" ] || fail "second restore counts '$got', want '$want'" +[ "$(docker inspect -f '{{.State.Running}}' "$API")" = true ] || fail "the API was not started again" +echo "restore over existing data matches, API running again" + +echo "── 2. retention" +i=10 +while [ "$i" -le 24 ]; do + touch "$BACKUP_DIR/demoflow-production-200001${i}T000000Z.dump" + i=$((i + 1)) +done +sh "$HERE/backup.sh" +left="$(ls -1 "$BACKUP_DIR"/demoflow-production-*.dump | wc -l | tr -d ' ')" +[ "$left" = 14 ] || fail "$left dumps left, want 14" +[ ! -e "$BACKUP_DIR/demoflow-production-20000110T000000Z.dump" ] || fail "the oldest dump was kept" +[ -e "$dump" ] || fail "the first real dump was deleted" +echo "14 dumps kept, oldest removed" + +echo "── 3. a failed dump" +before="$(ls -1a "$BACKUP_DIR")" +if DB_NAME=no_such_database sh "$HERE/backup.sh"; then + fail "backup.sh succeeded against a missing database" +fi +[ "$(ls -1a "$BACKUP_DIR")" = "$before" ] || fail "a failed dump changed the backup directory" +echo "failed dump exited non-zero, dumps untouched" + +echo "── 4. restore without confirmation" +if CONTAINER="$DST_DB" sh "$HERE/restore.sh" "$dump"; then + fail "restore.sh ran without the confirmation flag" +fi +echo "restore refused" + +echo "OK" From 56ae19410792eb37f3e162f4926c82c62e3287b7 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 14:55:51 +0100 Subject: [PATCH 27/71] feat(api): serve public share pages, files and password unlocks GET /s/:token answers the share page's data, or { locked: true } before a password is entered, and counts a view only when it returns the data. GET|HEAD /s/:token/file and /poster stream with byte ranges; without a password they embed cross-origin and cache for five minutes, with one they need the signed unlock cookie and are never cached. POST /s/:token/unlock checks the password, is throttled to ten attempts per ten minutes per address and token, and sets an HttpOnly cookie signed with SHARE_SIGNING_SECRET for twelve hours. Unknown, uploading and failed shares are 404, expired ones 410 expired, lost ones and ready ones whose file is gone 410 unavailable. Caddy routes the file and poster paths to the API in staging and production. Refs #348 --- apps/api/src/auth/auth-throttle.ts | 18 + .../src/shares/public-shares.controller.ts | 68 +++ apps/api/src/shares/public-shares.dto.ts | 17 + .../shares/public-shares.integration.spec.ts | 533 ++++++++++++++++++ apps/api/src/shares/public-shares.service.ts | 325 +++++++++++ apps/api/src/shares/share-access.spec.ts | 108 ++++ apps/api/src/shares/share-access.ts | 150 +++++ apps/api/src/shares/shares.module.ts | 21 +- deploy/production/Caddyfile | 14 + deploy/staging/Caddyfile | 14 + 10 files changed, 1264 insertions(+), 4 deletions(-) create mode 100644 apps/api/src/shares/public-shares.controller.ts create mode 100644 apps/api/src/shares/public-shares.dto.ts create mode 100644 apps/api/src/shares/public-shares.integration.spec.ts create mode 100644 apps/api/src/shares/public-shares.service.ts create mode 100644 apps/api/src/shares/share-access.spec.ts create mode 100644 apps/api/src/shares/share-access.ts diff --git a/apps/api/src/auth/auth-throttle.ts b/apps/api/src/auth/auth-throttle.ts index d8f664ac..c7ccb138 100644 --- a/apps/api/src/auth/auth-throttle.ts +++ b/apps/api/src/auth/auth-throttle.ts @@ -19,6 +19,8 @@ export const THROTTLE_MAIL = 'mail-email'; * minutes, which the shared `ip` budget would cut off after 20 polls. */ export const THROTTLE_DEVICE_POLL = 'device-poll'; +/** A share's password (spec #348, Decision 6): per address and share token. */ +export const THROTTLE_SHARE_UNLOCK = 'share-unlock'; /** Class-level: every throttler skipped until a route opts in. */ export const SKIP_ALL_THROTTLERS = { @@ -26,6 +28,7 @@ export const SKIP_ALL_THROTTLERS = { [THROTTLE_SIGN_IN]: true, [THROTTLE_MAIL]: true, [THROTTLE_DEVICE_POLL]: true, + [THROTTLE_SHARE_UNLOCK]: true, }; export const authThrottlerOptions: ThrottlerModuleOptions = { @@ -61,6 +64,15 @@ export const authThrottlerOptions: ThrottlerModuleOptions = { ttl: 10 * MINUTE_MS, getTracker: (req) => `ip:${(req as AuthenticatedRequest).ip ?? ''}`, }, + { + name: THROTTLE_SHARE_UNLOCK, + limit: 10, + ttl: 10 * MINUTE_MS, + getTracker: (req) => { + const request = req as AuthenticatedRequest; + return `ip:${request.ip ?? ''}:share:${routeToken(request)}`; + }, + }, ], // The default key includes the route, which would give each endpoint its // own budget. The limits are across the auth endpoints. @@ -68,6 +80,12 @@ export const authThrottlerOptions: ThrottlerModuleOptions = { `${name}:${tracker}`, }; +/** Guards run after routing: `:token` is already parsed. */ +function routeToken(req: AuthenticatedRequest): string { + const token: unknown = req.params?.token; + return typeof token === 'string' ? token : ''; +} + /** Guards run before the validation pipe, so the body is still raw here. */ function bodyEmail(req: AuthenticatedRequest): string { const body: unknown = req.body; diff --git a/apps/api/src/shares/public-shares.controller.ts b/apps/api/src/shares/public-shares.controller.ts new file mode 100644 index 00000000..1cb2b097 --- /dev/null +++ b/apps/api/src/shares/public-shares.controller.ts @@ -0,0 +1,68 @@ +import { + Body, + Controller, + Get, + HttpCode, + HttpStatus, + Param, + Post, + Query, + Req, + Res, + UseGuards, +} from '@nestjs/common'; +import { SkipThrottle, ThrottlerGuard } from '@nestjs/throttler'; +import type { Request, Response } from 'express'; +import { + SKIP_ALL_THROTTLERS, + THROTTLE_SHARE_UNLOCK, +} from '../auth/auth-throttle'; +import { ShareFileQueryDto, UnlockShareDto } from './public-shares.dto'; +import { PublicSharesService, type SharePage } from './public-shares.service'; + +/** + * A share link, opened without an account (spec #348). No session guard: the + * token is the only key. Express answers HEAD through the GET routes. + */ +@Controller('s') +@SkipThrottle(SKIP_ALL_THROTTLERS) +export class PublicSharesController { + constructor(private readonly shares: PublicSharesService) {} + + @Get(':token') + page(@Param('token') token: string, @Req() req: Request): Promise<SharePage> { + return this.shares.page(token, req.cookies); + } + + @Get(':token/file') + file( + @Param('token') token: string, + @Query() { download }: ShareFileQueryDto, + @Req() req: Request, + @Res() res: Response, + ): Promise<void> { + return this.shares.serve(req, res, token, 'file', download === '1'); + } + + @Get(':token/poster') + poster( + @Param('token') token: string, + @Req() req: Request, + @Res() res: Response, + ): Promise<void> { + return this.shares.serve(req, res, token, 'poster', false); + } + + /** 10 attempts per 10 minutes per address and token (Decision 6). */ + @Post(':token/unlock') + @HttpCode(HttpStatus.NO_CONTENT) + @UseGuards(ThrottlerGuard) + @SkipThrottle({ [THROTTLE_SHARE_UNLOCK]: false }) + unlock( + @Param('token') token: string, + @Body() { password }: UnlockShareDto, + @Res({ passthrough: true }) res: Response, + ): Promise<void> { + return this.shares.unlock(token, password, res); + } +} diff --git a/apps/api/src/shares/public-shares.dto.ts b/apps/api/src/shares/public-shares.dto.ts new file mode 100644 index 00000000..bb8233c8 --- /dev/null +++ b/apps/api/src/shares/public-shares.dto.ts @@ -0,0 +1,17 @@ +import { IsIn, IsOptional, IsString, Length } from 'class-validator'; +import { SHARE_PASSWORD_MAX, SHARE_PASSWORD_MIN } from './shares.dto'; + +/** `POST /s/:token/unlock` (spec #348, Decision 5). */ +export class UnlockShareDto { + /** Never trimmed: a password is what the person typed. */ + @IsString() + @Length(SHARE_PASSWORD_MIN, SHARE_PASSWORD_MAX) + password!: string; +} + +/** `?download=1` saves the file instead of playing it (Decision 4). */ +export class ShareFileQueryDto { + @IsOptional() + @IsIn(['1']) + download?: '1'; +} diff --git a/apps/api/src/shares/public-shares.integration.spec.ts b/apps/api/src/shares/public-shares.integration.spec.ts new file mode 100644 index 00000000..8a60f6b4 --- /dev/null +++ b/apps/api/src/shares/public-shares.integration.spec.ts @@ -0,0 +1,533 @@ +import { randomBytes } from 'node:crypto'; +import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { Logger } from '@nestjs/common'; +import type { ShareStatus } from '@prisma/client'; +import request from 'supertest'; +import type { App } from 'supertest/types'; +import { PasswordHasher } from '../auth/password-hasher'; +import { generateToken } from '../auth/tokens'; +import type { RunFormat } from '../projects/projects.dto'; +import { type SignedIn, signedInUser } from '../runner/runner.fixtures'; +import { createTestApp, type TestApp } from '../test/test-app'; +import { SHARE_ACCESS_MS } from './share-access'; +import { ShareConfig } from './share-config'; +import { extensionOf } from './share-storage'; + +const FILE = randomBytes(5000); +const POSTER = randomBytes(300); +const DAY_MS = 24 * 60 * 60 * 1000; +const TITLE = 'Checkout flow 7f3a'; +const DESCRIPTION = 'Buys one item.'; +const PASSWORD = 'hunter22-correct-horse'; +const WEB = 'http://web.test'; + +interface Made { + id: string; + token: string; + runId: string; + projectId: string; +} + +interface MakeOptions { + status?: ShareStatus; + format?: string; + /** From now; negative is already expired. */ + expiresInMs?: number; + password?: string; + /** Write `file.<ext>` and `poster.jpg` under the share's directory. */ + files?: boolean; +} + +describe('public share links (integration)', () => { + let t: TestApp; + let http: App; + let dir: string; + let alice: SignedIn; + let hasher: PasswordHasher; + + beforeEach(async () => { + dir = await mkdtemp(join(tmpdir(), 'demoflow-public-shares-')); + const config: ShareConfig = { + dir, + maxFileBytes: 10_000, + quotaBytes: 20_000, + webUrl: WEB, + }; + t = await createTestApp([], [{ provide: ShareConfig, useValue: config }]); + http = t.app.getHttpServer(); + alice = await signedInUser(t, 'alice'); + hasher = t.app.get(PasswordHasher); + }); + + afterEach(async () => { + await t.app.close(); + await rm(dir, { recursive: true, force: true }); + }); + + /** A share row as #347 leaves it, made directly, with its files on disk. */ + async function make(options: MakeOptions = {}): Promise<Made> { + const format = options.format ?? 'mp4'; + const project = await t.prisma.project.create({ + data: { userId: alice.user.id, name: 'shop' }, + }); + const run = await t.prisma.run.create({ + data: { + projectId: project.id, + scenarioName: TITLE, + scenarioPath: 'demos/checkout.demo.json', + status: 'passed', + startedAt: t.clock.now(), + durationMs: 12_345, + formats: [format], + cliVersion: '0.7.0', + }, + }); + const token = generateToken(); + const share = await t.prisma.share.create({ + data: { + token, + userId: alice.user.id, + runId: run.id, + format, + status: options.status ?? 'ready', + title: TITLE, + description: DESCRIPTION, + chapters: [ + { title: 'Open the cart', atMs: 0 }, + { title: 'Pay', atMs: 4000 }, + ], + sizeBytes: FILE.length, + posterBytes: POSTER.length, + width: 1280, + height: 720, + durationMs: 12_000, + passwordHash: + options.password === undefined + ? null + : await hasher.hash(options.password), + expiresAt: new Date( + t.clock.now().getTime() + (options.expiresInMs ?? 30 * DAY_MS), + ), + }, + }); + if (options.files ?? true) { + await mkdir(join(dir, share.id), { recursive: true }); + await writeFile( + join(dir, share.id, `file.${extensionOf(format as RunFormat)}`), + FILE, + ); + await writeFile(join(dir, share.id, 'poster.jpg'), POSTER); + } + return { id: share.id, token, runId: run.id, projectId: project.id }; + } + + function page(token: string, cookie?: string): request.Test { + const req = request(http).get(`/s/${token}`); + return cookie === undefined ? req : req.set('Cookie', cookie); + } + + function unlock(token: string, password = PASSWORD): request.Test { + return request(http).post(`/s/${token}/unlock`).send({ password }); + } + + /** The `name=value` of the unlock cookie a right password answers with. */ + async function unlocked(token: string): Promise<string> { + const res = await unlock(token).expect(204); + const header = res.headers['set-cookie'] as unknown as string[]; + expect(header).toHaveLength(1); + return header[0].split(';')[0]; + } + + async function views(id: string): Promise<number> { + const share = await t.prisma.share.findUniqueOrThrow({ where: { id } }); + return share.views; + } + + describe('what a share answers (Decision 2)', () => { + it('an unknown or malformed token is 404', async () => { + await page(generateToken()).expect(404, { error: 'not-found' }); + await page('nope').expect(404, { error: 'not-found' }); + await request(http).get(`/s/${generateToken()}/file`).expect(404); + await request(http).get(`/s/${generateToken()}/poster`).expect(404); + }); + + it.each<ShareStatus>([ + 'uploading', + 'failed', + ])('a share still %s is 404', async (status) => { + const share = await make({ status }); + await page(share.token).expect(404, { error: 'not-found' }); + await request(http).get(`/s/${share.token}/file`).expect(404); + await request(http).get(`/s/${share.token}/poster`).expect(404); + }); + + it('an expired share is 410 expired before the sweeper ran', async () => { + const share = await make({ expiresInMs: DAY_MS }); + await page(share.token).expect(200); + t.clock.advance(DAY_MS); + await page(share.token).expect(410, { error: 'expired' }); + await request(http) + .get(`/s/${share.token}/file`) + .expect(410, { error: 'expired' }); + await request(http).get(`/s/${share.token}/poster`).expect(410); + // The row is still there: only the sweeper deletes it. + expect(await t.prisma.share.count({ where: { id: share.id } })).toBe(1); + }); + + it('a lost share is 410 unavailable', async () => { + const share = await make({ status: 'lost' }); + await page(share.token).expect(410, { error: 'unavailable' }); + await request(http) + .get(`/s/${share.token}/file`) + .expect(410, { error: 'unavailable' }); + await request(http).get(`/s/${share.token}/poster`).expect(410); + }); + + it('a ready share whose file is gone is 410 unavailable and marked lost', async () => { + const page1 = await make({ files: false }); + await page(page1.token).expect(410, { error: 'unavailable' }); + expect( + (await t.prisma.share.findUniqueOrThrow({ where: { id: page1.id } })) + .status, + ).toBe('lost'); + + const file = await make({ files: false }); + await request(http) + .get(`/s/${file.token}/file`) + .expect(410, { error: 'unavailable' }); + expect( + (await t.prisma.share.findUniqueOrThrow({ where: { id: file.id } })) + .status, + ).toBe('lost'); + }); + + it('a share with a password and no cookie is locked, and nothing else', async () => { + const share = await make({ password: PASSWORD }); + const res = await page(share.token).expect(200); + expect(res.body).toEqual({ locked: true }); + expect(Object.keys(res.body)).toEqual(['locked']); + await request(http) + .get(`/s/${share.token}/file`) + .expect(403, { error: 'locked' }); + await request(http) + .get(`/s/${share.token}/poster`) + .expect(403, { error: 'locked' }); + }); + + it('a ready share answers its data, file and poster', async () => { + const share = await make(); + const res = await page(share.token).expect(200); + const url = `${WEB}/s/${share.token}`; + expect(res.body).toEqual({ + title: TITLE, + description: DESCRIPTION, + chapters: [ + { title: 'Open the cart', atMs: 0 }, + { title: 'Pay', atMs: 4000 }, + ], + format: 'mp4', + kind: 'video', + width: 1280, + height: 720, + durationMs: 12_000, + sizeBytes: FILE.length, + expiresAt: new Date( + t.clock.now().getTime() + 30 * DAY_MS, + ).toISOString(), + fileUrl: `${url}/file`, + posterUrl: `${url}/poster`, + downloadUrl: `${url}/file?download=1`, + }); + + const file = await request(http) + .get(`/s/${share.token}/file`) + .expect(200); + expect(file.headers['content-type']).toBe('video/mp4'); + expect(file.headers['content-length']).toBe(String(FILE.length)); + expect(file.headers['content-disposition']).toBe('inline'); + expect(Buffer.compare(file.body as Buffer, FILE)).toBe(0); + + const poster = await request(http) + .get(`/s/${share.token}/poster`) + .expect(200); + expect(poster.headers['content-type']).toBe('image/jpeg'); + expect(Buffer.compare(poster.body as Buffer, POSTER)).toBe(0); + }); + }); + + describe('the file (Decision 4)', () => { + it('answers a byte range with 206 and Content-Range', async () => { + const share = await make(); + const res = await request(http) + .get(`/s/${share.token}/file`) + .set('Range', 'bytes=0-99') + .expect(206); + expect(res.headers['content-range']).toBe(`bytes 0-99/${FILE.length}`); + expect(res.headers['content-length']).toBe('100'); + expect(res.headers['accept-ranges']).toBe('bytes'); + expect(Buffer.compare(res.body as Buffer, FILE.subarray(0, 100))).toBe(0); + }); + + it('answers a range past the end with 416', async () => { + const share = await make(); + const res = await request(http) + .get(`/s/${share.token}/file`) + .set('Range', `bytes=${FILE.length}-`) + .expect(416); + expect(res.headers['content-range']).toBe(`bytes */${FILE.length}`); + }); + + it('answers HEAD with the headers and no body', async () => { + const share = await make(); + const res = await request(http) + .head(`/s/${share.token}/file`) + .expect(200); + expect(res.headers['content-length']).toBe(String(FILE.length)); + expect(res.headers['content-type']).toBe('video/mp4'); + await request(http).head(`/s/${share.token}/poster`).expect(200); + }); + + it('saves as an attachment with ?download=1', async () => { + const share = await make(); + const res = await request(http) + .get(`/s/${share.token}/file?download=1`) + .expect(200); + expect(res.headers['content-disposition']).toBe( + 'attachment; filename="checkout-flow-7f3a-2026-10-20.mp4"', + ); + }); + + it('serves a GIF share as image/gif, kind image', async () => { + const share = await make({ format: 'gif-vertical' }); + const data = await page(share.token).expect(200); + expect(data.body).toMatchObject({ + format: 'gif-vertical', + kind: 'image', + }); + const res = await request(http).get(`/s/${share.token}/file`).expect(200); + expect(res.headers['content-type']).toBe('image/gif'); + }); + + it('without a password embeds anywhere and caches for 5 minutes', async () => { + const share = await make(); + for (const asset of ['file', 'poster']) { + const res = await request(http) + .get(`/s/${share.token}/${asset}`) + .expect(200); + expect(res.headers['cross-origin-resource-policy']).toBe( + 'cross-origin', + ); + expect(res.headers['cache-control']).toBe('public, max-age=300'); + } + }); + + it('with a password opens only with the unlock cookie, never cached', async () => { + const share = await make({ password: PASSWORD }); + await request(http).get(`/s/${share.token}/file`).expect(403); + const cookie = await unlocked(share.token); + const res = await request(http) + .get(`/s/${share.token}/file`) + .set('Cookie', cookie) + .expect(200); + expect(Buffer.compare(res.body as Buffer, FILE)).toBe(0); + expect(res.headers['cache-control']).toBe('private, no-store'); + expect(res.headers['cross-origin-resource-policy']).toBe('same-origin'); + await request(http) + .get(`/s/${share.token}/poster`) + .set('Cookie', cookie) + .expect(200); + const data = await page(share.token, cookie).expect(200); + expect(data.body).toMatchObject({ title: TITLE }); + }); + }); + + describe('unlock (Decisions 5–6)', () => { + it('sets an HttpOnly, SameSite=Lax cookie for 12 hours', async () => { + const share = await make({ password: PASSWORD }); + const res = await unlock(share.token).expect(204); + const [cookie] = res.headers['set-cookie'] as unknown as string[]; + expect(cookie).toMatch(new RegExp(`^df_share_${share.id}=\\d+\\.`)); + expect(cookie).toContain('HttpOnly'); + expect(cookie).toContain('SameSite=Lax'); + expect(cookie).toContain('Path=/'); + expect(cookie).toContain(`Max-Age=${SHARE_ACCESS_MS / 1000}`); + }); + + it('the cookie ends after 12 hours', async () => { + const share = await make({ password: PASSWORD }); + const cookie = await unlocked(share.token); + t.clock.advance(SHARE_ACCESS_MS); + const res = await page(share.token, cookie).expect(200); + expect(res.body).toEqual({ locked: true }); + }); + + it('a wrong password is 401', async () => { + const share = await make({ password: PASSWORD }); + const res = await unlock(share.token, 'wrong-password-1').expect(401, { + error: 'wrong-password', + }); + expect(res.headers['set-cookie']).toBeUndefined(); + }); + + it('a share without a password has nothing to unlock', async () => { + const share = await make(); + const res = await unlock(share.token).expect(204); + expect(res.headers['set-cookie']).toBeUndefined(); + }); + + it('a password outside 8–128 characters is 400', async () => { + const share = await make({ password: PASSWORD }); + await unlock(share.token, 'short').expect(400); + await unlock(share.token, 'x'.repeat(129)).expect(400); + }); + + it('unlocks follow expiry and the 404 rows too', async () => { + await unlock(generateToken()).expect(404); + const expired = await make({ password: PASSWORD, expiresInMs: -1 }); + await unlock(expired.token).expect(410, { error: 'expired' }); + }); + + it('the 11th attempt in 10 minutes from one address for one token is 429', async () => { + const share = await make({ password: PASSWORD }); + const other = await make({ password: PASSWORD }); + for (let attempt = 0; attempt < 10; attempt += 1) { + await unlock(share.token, 'wrong-password-1').expect(401); + } + await unlock(share.token, 'wrong-password-1').expect(429); + // Right or wrong, the budget is spent for this token only. + await unlock(share.token).expect(429); + await unlock(other.token).expect(204); + }); + + it('a cookie signed for share A does not open share B', async () => { + const a = await make({ password: PASSWORD }); + const b = await make({ password: PASSWORD }); + const cookie = await unlocked(a.token); + const value = cookie.split('=')[1]; + for (const sent of [cookie, `df_share_${b.id}=${value}`]) { + const res = await page(b.token, sent).expect(200); + expect(res.body).toEqual({ locked: true }); + await request(http) + .get(`/s/${b.token}/file`) + .set('Cookie', sent) + .expect(403); + } + }); + + it('a cross-origin unlock is refused', async () => { + const share = await make({ password: PASSWORD }); + await unlock(share.token) + .set('Origin', 'https://evil.example') + .expect(403); + }); + }); + + describe('views (Decision 7)', () => { + it('grow by one per unlocked page load, not on file, poster or locked', async () => { + const open = await make(); + await page(open.token).expect(200); + await page(open.token).expect(200); + await request(http).get(`/s/${open.token}/file`).expect(200); + await request(http).get(`/s/${open.token}/poster`).expect(200); + await request(http).head(`/s/${open.token}/file`).expect(200); + expect(await views(open.id)).toBe(2); + + const locked = await make({ password: PASSWORD }); + await page(locked.token).expect(200); + expect(await views(locked.id)).toBe(0); + const cookie = await unlocked(locked.token); + await page(locked.token, cookie).expect(200); + await request(http) + .get(`/s/${locked.token}/file`) + .set('Cookie', cookie) + .expect(200); + expect(await views(locked.id)).toBe(1); + }); + }); + + describe('authorization', () => { + it('never answers by id, and never names a user, run, project or share', async () => { + const share = await make(); + for (const key of [ + share.id, + share.runId, + share.projectId, + alice.user.id, + ]) { + await page(key).expect(404); + await request(http).get(`/s/${key}/file`).expect(404); + } + const res = await page(share.token).expect(200); + const body = JSON.stringify(res.body); + for (const key of [ + share.id, + share.runId, + share.projectId, + alice.user.id, + ]) { + expect(body).not.toContain(key); + } + for (const key of [ + 'id', + 'userId', + 'runId', + 'projectId', + 'token', + 'views', + ]) { + expect(res.body).not.toHaveProperty(key); + } + }); + + it("one share's token never reaches another's file", async () => { + const a = await make(); + const b = await make(); + await writeFile(join(dir, b.id, 'file.mp4'), randomBytes(5000)); + const res = await request(http).get(`/s/${a.token}/file`).expect(200); + expect(Buffer.compare(res.body as Buffer, FILE)).toBe(0); + }); + }); + + describe('logging', () => { + it('never logs an address or a token', async () => { + const lines: string[] = []; + const spies = (['log', 'warn', 'error', 'debug', 'verbose'] as const).map( + (level) => + jest + .spyOn(Logger.prototype, level) + .mockImplementation((...args: unknown[]) => { + lines.push(args.map(String).join(' ')); + }), + ); + try { + const open = await make(); + const locked = await make({ password: PASSWORD }); + const gone = await make({ files: false }); + await page(open.token).expect(200); + await request(http).get(`/s/${open.token}/file`).expect(200); + await page(locked.token).expect(200); + await unlock(locked.token, 'wrong-password-1').expect(401); + await unlocked(locked.token); + await page(gone.token).expect(410); + + const all = lines.join('\n'); + expect(all).toContain('share.lost'); + for (const secret of [ + open.token, + locked.token, + gone.token, + '127.0.0.1', + PASSWORD, + ]) { + expect(all).not.toContain(secret); + } + } finally { + for (const spy of spies) { + spy.mockRestore(); + } + } + }); + }); +}); diff --git a/apps/api/src/shares/public-shares.service.ts b/apps/api/src/shares/public-shares.service.ts new file mode 100644 index 00000000..ca288fd6 --- /dev/null +++ b/apps/api/src/shares/public-shares.service.ts @@ -0,0 +1,325 @@ +import { type FileHandle, open } from 'node:fs/promises'; +import { pipeline } from 'node:stream/promises'; +import { HttpException, HttpStatus, Injectable, Logger } from '@nestjs/common'; +import type { Share } from '@prisma/client'; +import type { Request, Response } from 'express'; +import { PasswordHasher } from '../auth/password-hasher'; +import { Clock } from '../common/clock'; +import { PrismaService } from '../database/prisma.service'; +import { RUN_FORMATS, type RunFormat } from '../projects/projects.dto'; +import { parseRange, spanOf } from '../videos/byte-range'; +import { type DownloadNameRun, downloadName } from '../videos/download-name'; +import { VIDEO_CONTENT_TYPES } from '../videos/video-relay.service'; +import { ShareAccess } from './share-access'; +import { ShareConfig } from './share-config'; +import { ShareStorage } from './share-storage'; + +/** + * `generateToken()`: 32 random bytes, base64url. Caddy routes + * `/s/<token>/file` and `/s/<token>/poster` with the same pattern (Decision 1). + */ +export const SHARE_TOKEN = /^[A-Za-z0-9_-]{43}$/; + +/** `kind` is `image` for the GIF formats (Decision 3). */ +export type ShareKind = 'video' | 'image'; + +export interface ShareChapter { + title: string; + atMs: number; +} + +/** What the share page shows (Decision 3). Nothing that names an owner, a run or a share id. */ +export interface ShareData { + title: string; + description: string | null; + chapters: ShareChapter[]; + format: RunFormat; + kind: ShareKind; + width: number | null; + height: number | null; + durationMs: number | null; + sizeBytes: number; + expiresAt: Date; + fileUrl: string; + posterUrl: string; + downloadUrl: string; +} + +/** A share with a password, before its cookie: nothing about the video. */ +export interface LockedSharePage { + locked: true; +} + +export type SharePage = ShareData | LockedSharePage; + +export type ShareAsset = 'file' | 'poster'; + +type PublicShare = Share & { run: DownloadNameRun }; + +/** `{ error }` with a status, as the owner's share API answers. */ +function publicError(status: HttpStatus, error: string): HttpException { + return new HttpException({ error }, status); +} + +function notFound(): HttpException { + return publicError(HttpStatus.NOT_FOUND, 'not-found'); +} + +function unavailable(): HttpException { + return publicError(HttpStatus.GONE, 'unavailable'); +} + +/** Not `instanceof Error`: Node's fs errors can come from another realm. */ +function isMissing(error: unknown): boolean { + return ( + typeof error === 'object' && + error !== null && + 'code' in error && + error.code === 'ENOENT' + ); +} + +function parseChapters(value: unknown): ShareChapter[] { + if (!Array.isArray(value)) { + return []; + } + return value.flatMap((entry: unknown) => { + if (typeof entry !== 'object' || entry === null) { + return []; + } + const { title, atMs } = entry as Record<string, unknown>; + return typeof title === 'string' && typeof atMs === 'number' + ? [{ title, atMs }] + : []; + }); +} + +/** + * What a viewer without an account reaches (spec #348, ADR-0019 §5): the + * share page's data, its file and poster, and the password unlock. Only the + * token opens a share; expiry is checked on every request, before the + * sweeper cleans up. Nothing about the viewer is stored or logged. + */ +@Injectable() +export class PublicSharesService { + private readonly logger = new Logger(PublicSharesService.name); + + constructor( + private readonly prisma: PrismaService, + private readonly storage: ShareStorage, + private readonly config: ShareConfig, + private readonly access: ShareAccess, + private readonly hasher: PasswordHasher, + private readonly clock: Clock, + ) {} + + /** `GET /s/:token`. Counts a view only when it returns the data (Decision 7). */ + async page( + token: string, + cookies: Record<string, unknown> | undefined, + ): Promise<SharePage> { + const share = await this.resolve(token); + const format = await this.formatOf(share); + if (!(await this.storage.exists(this.storage.filePath(share.id, format)))) { + await this.markLost(share.id); + throw unavailable(); + } + if (!this.opens(share, cookies)) { + return { locked: true }; + } + await this.prisma.share.updateMany({ + where: { id: share.id }, + data: { views: { increment: 1 } }, + }); + return this.toData(share, token, format); + } + + /** + * `POST /s/:token/unlock`. Right: the cookie. A share without a password + * has nothing to unlock and answers the same, without one. + */ + async unlock(token: string, password: string, res: Response): Promise<void> { + const share = await this.resolve(token); + if (share.passwordHash === null) { + return; + } + if (!(await this.hasher.verify(share.passwordHash, password))) { + throw publicError(HttpStatus.UNAUTHORIZED, 'wrong-password'); + } + this.access.grant(res, { id: share.id, passwordHash: share.passwordHash }); + } + + /** `GET|HEAD /s/:token/file` and `/s/:token/poster`, with byte ranges (Decision 4). */ + async serve( + req: Request, + res: Response, + token: string, + asset: ShareAsset, + download: boolean, + ): Promise<void> { + const share = await this.resolve(token); + if (!this.opens(share, req.cookies)) { + throw publicError(HttpStatus.FORBIDDEN, 'locked'); + } + const format = await this.formatOf(share); + const path = + asset === 'file' + ? this.storage.filePath(share.id, format) + : this.storage.posterPath(share.id); + let handle: FileHandle; + try { + handle = await open(path, 'r'); + } catch (error) { + if (!isMissing(error)) { + throw error; + } + // The poster alone missing leaves the video playable. + if (asset === 'file') { + await this.markLost(share.id); + } + throw unavailable(); + } + + let streaming = false; + try { + const { size } = await handle.stat(); + const range = parseRange(req.headers.range); + const span = spanOf(range, size); + const headers: Record<string, string> = { + 'Accept-Ranges': 'bytes', + // Without a password the file embeds in another site; with one it + // stays behind the cookie (ADR-0019 §5). + ...(share.passwordHash === null + ? { + 'Cache-Control': 'public, max-age=300', + 'Cross-Origin-Resource-Policy': 'cross-origin', + } + : { 'Cache-Control': 'private, no-store' }), + }; + if (span === null && range !== null) { + res.writeHead(HttpStatus.REQUESTED_RANGE_NOT_SATISFIABLE, { + ...headers, + 'Content-Range': `bytes */${size}`, + }); + res.end(); + return; + } + const partial = range !== null && span !== null; + res.writeHead(partial ? HttpStatus.PARTIAL_CONTENT : HttpStatus.OK, { + ...headers, + 'Content-Type': + asset === 'file' ? VIDEO_CONTENT_TYPES[format] : 'image/jpeg', + 'Content-Length': String(span === null ? 0 : span.end - span.start + 1), + 'Content-Disposition': + asset === 'file' && download + ? `attachment; filename="${downloadName(share.run, format)}"` + : 'inline', + ...(partial + ? { 'Content-Range': `bytes ${span.start}-${span.end}/${size}` } + : {}), + }); + if (req.method === 'HEAD' || span === null) { + res.end(); + return; + } + streaming = true; + // A viewer closing the tab mid-file is no error. + await pipeline( + handle.createReadStream({ start: span.start, end: span.end }), + res, + ).catch(() => undefined); + } finally { + if (!streaming) { + await handle.close(); + } + } + } + + /** + * The Decision 2 table, up to the file: unknown, uploading and failed are + * 404; expired and lost are 410. + */ + private async resolve(token: string): Promise<PublicShare> { + if (!SHARE_TOKEN.test(token)) { + throw notFound(); + } + const share = await this.prisma.share.findUnique({ + where: { token }, + include: { + run: { + select: { scenarioName: true, scenarioPath: true, startedAt: true }, + }, + }, + }); + if (!share || (share.status !== 'ready' && share.status !== 'lost')) { + throw notFound(); + } + if (share.expiresAt.getTime() <= this.clock.now().getTime()) { + throw publicError(HttpStatus.GONE, 'expired'); + } + if (share.status === 'lost') { + throw unavailable(); + } + return share; + } + + private opens( + share: PublicShare, + cookies: Record<string, unknown> | undefined, + ): boolean { + return ( + share.passwordHash === null || + this.access.allows(cookies, { + id: share.id, + passwordHash: share.passwordHash, + }) + ); + } + + /** A format the API no longer knows has no file it can name: lost. */ + private async formatOf(share: PublicShare): Promise<RunFormat> { + const format = RUN_FORMATS.find((known) => known === share.format); + if (format === undefined) { + await this.markLost(share.id); + throw unavailable(); + } + return format; + } + + /** Not backed up (ADR-0019 §4): the owner shares the run again. */ + private async markLost(id: string): Promise<void> { + const { count } = await this.prisma.share.updateMany({ + where: { id, status: 'ready' }, + data: { status: 'lost' }, + }); + if (count === 1) { + // As the owner's API logs (spec #347, Decision 10): never the token. + this.logger.log( + JSON.stringify({ event: 'share.lost', shareId: id, outcome: 'lost' }), + ); + } + } + + private toData( + share: PublicShare, + token: string, + format: RunFormat, + ): ShareData { + const fileUrl = `${this.config.webUrl}/s/${token}/file`; + return { + title: share.title, + description: share.description, + chapters: parseChapters(share.chapters), + format, + kind: format.startsWith('gif') ? 'image' : 'video', + width: share.width, + height: share.height, + durationMs: share.durationMs, + sizeBytes: share.sizeBytes, + expiresAt: share.expiresAt, + fileUrl, + posterUrl: `${this.config.webUrl}/s/${token}/poster`, + downloadUrl: `${fileUrl}?download=1`, + }; + } +} diff --git a/apps/api/src/shares/share-access.spec.ts b/apps/api/src/shares/share-access.spec.ts new file mode 100644 index 00000000..48b0c5c9 --- /dev/null +++ b/apps/api/src/shares/share-access.spec.ts @@ -0,0 +1,108 @@ +import { readFileSync } from 'node:fs'; +import { join } from 'node:path'; +import { generateToken } from '../auth/tokens'; +import { SHARE_TOKEN } from './public-shares.service'; +import { + accessAllows, + accessValue, + resolveSigningSecret, + SHARE_ACCESS_MS, +} from './share-access'; + +const SECRET = 'a'.repeat(32); +const SHARE = { id: 'cshare1', passwordHash: '$argon2id$v=19$one' }; +const NOW = Date.parse('2026-10-20T12:00:00.000Z'); + +describe('resolveSigningSecret', () => { + it('uses the secret when it is long enough', () => { + expect( + resolveSigningSecret({ + APP_ENV: 'production', + SHARE_SIGNING_SECRET: SECRET, + }), + ).toBe(SECRET); + }); + + it('refuses a short secret', () => { + expect(() => + resolveSigningSecret({ SHARE_SIGNING_SECRET: 'short' }), + ).toThrow('SHARE_SIGNING_SECRET must be at least 32 characters'); + }); + + it('refuses to start in production without one, naming the variable', () => { + expect(() => resolveSigningSecret({ APP_ENV: 'production' })).toThrow( + 'SHARE_SIGNING_SECRET is not set', + ); + }); + + it('makes a random one per boot below production', () => { + const first = resolveSigningSecret({ APP_ENV: 'development' }); + const second = resolveSigningSecret({ APP_ENV: 'development' }); + expect(first.length).toBeGreaterThanOrEqual(32); + expect(first).not.toBe(second); + }); +}); + +describe('the unlock cookie', () => { + const value = accessValue(SECRET, SHARE, NOW + SHARE_ACCESS_MS); + + it('is <exp>.<hmac> and opens its share until it expires', () => { + expect(value).toMatch(/^\d+\.[A-Za-z0-9_-]{43}$/); + expect(accessAllows(SECRET, SHARE, value, NOW)).toBe(true); + expect(accessAllows(SECRET, SHARE, value, NOW + SHARE_ACCESS_MS)).toBe( + false, + ); + }); + + it('does not open another share', () => { + expect(accessAllows(SECRET, { ...SHARE, id: 'cshare2' }, value, NOW)).toBe( + false, + ); + }); + + it('is void once the password changes', () => { + expect( + accessAllows( + SECRET, + { ...SHARE, passwordHash: '$argon2id$v=19$two' }, + value, + NOW, + ), + ).toBe(false); + }); + + it('is void under another secret', () => { + expect(accessAllows('b'.repeat(32), SHARE, value, NOW)).toBe(false); + }); + + it('refuses a later expiry with the old signature, and garbage', () => { + const [, hmac] = value.split('.'); + const later = `${Math.floor(NOW / 1000) + 10 * 24 * 3600}.${hmac}`; + expect(accessAllows(SECRET, SHARE, later, NOW)).toBe(false); + expect(accessAllows(SECRET, SHARE, undefined, NOW)).toBe(false); + expect(accessAllows(SECRET, SHARE, 'nope', NOW)).toBe(false); + }); +}); + +describe('the share token and the Caddy route', () => { + const route = /path_regexp\s+(?:\S+\s+)?(\^\/s\/\S+\$)/; + + it.each([ + 'staging', + 'production', + ])('the %s Caddyfile routes /s/<token>/file and /poster for a real token', (env) => { + const caddyfile = readFileSync( + join(__dirname, '../../../../deploy', env, 'Caddyfile'), + 'utf8', + ); + const pattern = route.exec(caddyfile)?.[1]; + expect(pattern).toBeDefined(); + const regexp = new RegExp(pattern ?? '$^'); + const token = generateToken(); + expect(token).toMatch(SHARE_TOKEN); + expect(regexp.test(`/s/${token}/file`)).toBe(true); + expect(regexp.test(`/s/${token}/poster`)).toBe(true); + expect(regexp.test(`/s/${token}`)).toBe(false); + expect(regexp.test(`/s/${token}/unlock`)).toBe(false); + }); +}); diff --git a/apps/api/src/shares/share-access.ts b/apps/api/src/shares/share-access.ts new file mode 100644 index 00000000..fcf25d14 --- /dev/null +++ b/apps/api/src/shares/share-access.ts @@ -0,0 +1,150 @@ +import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'; +import { Injectable, Logger } from '@nestjs/common'; +import { ConfigService } from '@nestjs/config'; +import type { CookieOptions, Response } from 'express'; +import { Clock } from '../common/clock'; + +/** How long an unlock lasts (spec #348, Decision 5). */ +export const SHARE_ACCESS_MS = 12 * 60 * 60 * 1000; +export const SHARE_SIGNING_SECRET_MIN = 32; + +const COOKIE_PREFIX = 'df_share_'; +/** `<exp>.<hmac>`: seconds since the epoch, then base64url SHA-256. */ +const COOKIE_VALUE = /^(\d{1,12})\.([A-Za-z0-9_-]{43})$/; + +/** What an unlock is bound to: the share, and its password as it is now. */ +export interface LockedShare { + id: string; + passwordHash: string; +} + +export interface SigningEnv { + APP_ENV?: string; + SHARE_SIGNING_SECRET?: string; +} + +/** + * `SHARE_SIGNING_SECRET` (Decision 8): at least 32 characters. Production + * refuses to start without it; below production a random value per boot is + * used, so unlocks end at a restart. + */ +export function resolveSigningSecret(env: SigningEnv): string { + const secret = env.SHARE_SIGNING_SECRET?.trim() || undefined; + if (secret !== undefined) { + if (secret.length < SHARE_SIGNING_SECRET_MIN) { + throw new Error( + `SHARE_SIGNING_SECRET must be at least ${SHARE_SIGNING_SECRET_MIN} characters.`, + ); + } + return secret; + } + if (env.APP_ENV === 'production') { + throw new Error( + 'SHARE_SIGNING_SECRET is not set, and APP_ENV=production does not fall ' + + 'back to a random one. Set it to at least 32 random characters.', + ); + } + new Logger('ShareAccess').warn( + 'SHARE_SIGNING_SECRET is not set: share unlocks are signed with a random ' + + 'value and end when the API restarts.', + ); + return randomBytes(32).toString('base64url'); +} + +export function shareCookieName(shareId: string): string { + return `${COOKIE_PREFIX}${shareId}`; +} + +/** + * The hash is signed too, so a later password change voids every unlock made + * with the old one. + */ +function sign(secret: string, share: LockedShare, exp: number): string { + return createHmac('sha256', secret) + .update(`${share.id}.${exp}.${share.passwordHash}`) + .digest('base64url'); +} + +export function accessValue( + secret: string, + share: LockedShare, + expiresAtMs: number, +): string { + const exp = Math.floor(expiresAtMs / 1000); + return `${exp}.${sign(secret, share, exp)}`; +} + +/** True for a value this secret signed for this share that has not expired. */ +export function accessAllows( + secret: string, + share: LockedShare, + value: string | undefined, + nowMs: number, +): boolean { + const match = value === undefined ? null : COOKIE_VALUE.exec(value); + if (!match) { + return false; + } + const exp = Number(match[1]); + if (exp * 1000 <= nowMs) { + return false; + } + const expected = Buffer.from(sign(secret, share, exp)); + const given = Buffer.from(match[2]); + return expected.length === given.length && timingSafeEqual(expected, given); +} + +/** + * The unlock cookie of a share with a password (spec #348, Decision 5): one + * per share, `df_share_<share.id>`, HMAC-signed and good for 12 hours. + */ +@Injectable() +export class ShareAccess { + private readonly secret: string; + private readonly secure: boolean; + + constructor( + config: ConfigService, + private readonly clock: Clock, + ) { + const appEnv = config.get<string>('APP_ENV'); + this.secret = resolveSigningSecret({ + APP_ENV: appEnv, + SHARE_SIGNING_SECRET: config.get<string>('SHARE_SIGNING_SECRET'), + }); + // As the session cookie: staging and production run APP_ENV=production. + this.secure = appEnv === 'production'; + } + + grant(res: Response, share: LockedShare): void { + const options: CookieOptions = { + httpOnly: true, + secure: this.secure, + sameSite: 'lax', + path: '/', + maxAge: SHARE_ACCESS_MS, + }; + res.cookie( + shareCookieName(share.id), + accessValue( + this.secret, + share, + this.clock.now().getTime() + SHARE_ACCESS_MS, + ), + options, + ); + } + + allows( + cookies: Record<string, unknown> | undefined, + share: LockedShare, + ): boolean { + const value = cookies?.[shareCookieName(share.id)]; + return accessAllows( + this.secret, + share, + typeof value === 'string' ? value : undefined, + this.clock.now().getTime(), + ); + } +} diff --git a/apps/api/src/shares/shares.module.ts b/apps/api/src/shares/shares.module.ts index 624d8e5f..ae070132 100644 --- a/apps/api/src/shares/shares.module.ts +++ b/apps/api/src/shares/shares.module.ts @@ -2,7 +2,10 @@ import { Module } from '@nestjs/common'; import { AuthModule } from '../auth/auth.module'; import { RunnerModule } from '../runner/runner.module'; import { VideosModule } from '../videos/videos.module'; +import { PublicSharesController } from './public-shares.controller'; +import { PublicSharesService } from './public-shares.service'; import { RunnerSharesController } from './runner-shares.controller'; +import { ShareAccess } from './share-access'; import { ShareStorageModule } from './share-storage'; import { ShareSweeper } from './share-sweeper'; import { ShareUploadService } from './share-upload.service'; @@ -11,12 +14,22 @@ import { SharesService } from './shares.service'; /** * Share links (spec #347, ADR-0019): a copy of one render on the server's - * disk, pulled from the machine through the video relay. The public page - * and file are #348. + * disk, pulled from the machine through the video relay, and opened by + * anyone with the token (spec #348). */ @Module({ imports: [AuthModule, RunnerModule, VideosModule, ShareStorageModule], - controllers: [SharesController, RunnerSharesController], - providers: [SharesService, ShareUploadService, ShareSweeper], + controllers: [ + SharesController, + RunnerSharesController, + PublicSharesController, + ], + providers: [ + SharesService, + ShareUploadService, + ShareSweeper, + PublicSharesService, + ShareAccess, + ], }) export class SharesModule {} diff --git a/deploy/production/Caddyfile b/deploy/production/Caddyfile index 28a7343d..3c0b85c2 100644 --- a/deploy/production/Caddyfile +++ b/deploy/production/Caddyfile @@ -25,6 +25,20 @@ } } + # A share's file and poster (spec #348) live on the share page's own path, + # so a link reads well in a README. Exactly these two go to the API + # unchanged; the page itself, /s/<token>, is the web app's. The token is + # `generateToken()`'s 43 base64url characters. + @share_file path_regexp ^/s/[A-Za-z0-9_-]{43}/(file|poster)$ + handle @share_file { + reverse_proxy api:8370 { + lb_try_duration 60s + lb_try_interval 250ms + health_uri /health + health_interval 2s + } + } + handle { reverse_proxy web:3670 { lb_try_duration 60s diff --git a/deploy/staging/Caddyfile b/deploy/staging/Caddyfile index 9edaef2c..7bc6a1bd 100644 --- a/deploy/staging/Caddyfile +++ b/deploy/staging/Caddyfile @@ -25,6 +25,20 @@ } } + # A share's file and poster (spec #348) live on the share page's own path, + # so a link reads well in a README. Exactly these two go to the API + # unchanged; the page itself, /s/<token>, is the web app's. The token is + # `generateToken()`'s 43 base64url characters. + @share_file path_regexp ^/s/[A-Za-z0-9_-]{43}/(file|poster)$ + handle @share_file { + reverse_proxy api:8370 { + lb_try_duration 60s + lb_try_interval 250ms + health_uri /health + health_interval 2s + } + } + handle { reverse_proxy web:3670 { lb_try_duration 60s From 9c81e42343fd826fb2a4ff8aa4631b3873c7c0bb Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 14:58:54 +0100 Subject: [PATCH 28/71] chore(deploy): generate the share signing secret and route share files locally Staging and production generate SHARE_SIGNING_SECRET in the stack's .env with refresh.sh, as they do POSTGRES_PASSWORD, and compose passes it to the API, which refuses to start in production without it. The web app rewrites /s/<token>/file and /poster to the API locally, matching the Caddy route. The API example and deploy/README document the secret and the route. Refs #348 --- apps/api/.env.example | 5 +++++ apps/web/next.config.ts | 10 +++++++++- deploy/README.md | 30 ++++++++++++++++++++-------- deploy/production/.env.example | 2 ++ deploy/production/docker-compose.yml | 1 + deploy/production/refresh.sh | 1 + deploy/staging/.env.example | 2 ++ deploy/staging/docker-compose.yml | 1 + deploy/staging/refresh.sh | 1 + 9 files changed, 44 insertions(+), 9 deletions(-) diff --git a/apps/api/.env.example b/apps/api/.env.example index 180be6fb..51547649 100644 --- a/apps/api/.env.example +++ b/apps/api/.env.example @@ -30,3 +30,8 @@ SHARE_DIR=./data/shares # across its shares, posters included (2 GB). SHARE_MAX_FILE_BYTES=209715200 SHARE_USER_QUOTA_BYTES=2147483648 + +# Signs the cookie a share password unlock sets (spec #348). At least 32 +# characters. APP_ENV=production refuses to start without it; below production +# an empty value means a random one per boot, so unlocks end at restart. +SHARE_SIGNING_SECRET= diff --git a/apps/web/next.config.ts b/apps/web/next.config.ts index c655fdc5..1b2d52f7 100644 --- a/apps/web/next.config.ts +++ b/apps/web/next.config.ts @@ -13,8 +13,16 @@ const nextConfig: NextConfig = { pageExtensions: ['ts', 'tsx', 'md', 'mdx'], // `/api` is reserved for the API. Stripping the prefix matches Caddy, so // the browser sees one origin locally and on staging alike. + // A share's file and poster live on the share page's own path (spec #348), + // as Caddy routes them on staging and production. async rewrites() { - return [{ source: '/api/:path*', destination: `${API_URL}/:path*` }]; + return [ + { source: '/api/:path*', destination: `${API_URL}/:path*` }, + { + source: '/s/:token([A-Za-z0-9_-]{43})/:asset(file|poster)', + destination: `${API_URL}/s/:token/:asset`, + }, + ]; }, }; diff --git a/deploy/README.md b/deploy/README.md index b92a16d9..07bc5910 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -169,8 +169,9 @@ agent host. `deploy-staging` then replaces the containers in `/home/archi/stacks/demoflow-staging`. ``` -Cloudflare ──tunnel──▶ cloudflared ──▶ proxy (Caddy :80) ─┬─ /api/* ─▶ api :8370 ─▶ postgres - └─ /* ─▶ web :3670 +Cloudflare ──tunnel──▶ cloudflared ──▶ proxy (Caddy :80) ─┬─ /api/* ─▶ api :8370 ─▶ postgres + ├─ /s/<token>/file|poster ─▶ api :8370 + └─ /* ─▶ web :3670 ``` Nothing is published on the host. The stack runs on its own compose network @@ -191,8 +192,8 @@ Nothing is published on the host. The stack runs on its own compose network - Timeout: 60 min. 3. **The first run.** Push to `develop`, or run the pipeline by hand on `develop`. `refresh.sh` creates the stack directory, copies the examples in - and generates `POSTGRES_PASSWORD`. It then stops, because the tunnel token - is missing. + and generates `POSTGRES_PASSWORD` and `SHARE_SIGNING_SECRET`. It then + stops, because the tunnel token is missing. 4. **Add the token and start the stack:** ```sh cp ~/.demoflow/cloudflared.env /home/archi/stacks/demoflow-staging/env/cloudflared.env @@ -292,6 +293,18 @@ owned by `node`, so a new volume starts writable. - **Not backed up.** Losing the volume loses every shared video; the rows turn `lost` at the next boot and their owners share again. Watch its size with `docker system df -v | grep shares`. +- **The public link** (spec #348). `/s/<token>` is the web app's page; it + reads `GET /api/s/<token>`. The file and the poster live on the page's own + path, `/s/<token>/file` and `/s/<token>/poster`, so Caddy sends exactly + those two paths (a 43-character token) to the API before the web handler. + Without a password they embed in other sites and are cached for 5 minutes; + with one they need the unlock cookie. +- **`SHARE_SIGNING_SECRET`.** Signs the 12-hour cookie a password unlock + sets. `refresh.sh` generates it in the stack's `.env` like + `POSTGRES_PASSWORD`, adding it to a stack that predates it, and compose + passes it to `api`; the API refuses to start in production without one. + Changing it ends every unlock, nothing more: viewers type the password + again. ## Production — https://demoflow.luna-realm.com @@ -303,8 +316,9 @@ approval gate, and neither step runs on `develop`, on a manual run or on a pull request. ``` -Cloudflare ──tunnel demoflow-prod──▶ cloudflared ──▶ proxy (Caddy :80) ─┬─ /api/* ─▶ api :8370 ─▶ postgres - └─ /* ─▶ web :3670 +Cloudflare ──tunnel demoflow-prod──▶ cloudflared ──▶ proxy (Caddy :80) ─┬─ /api/* ─▶ api :8370 ─▶ postgres + ├─ /s/<token>/file|poster ─▶ api :8370 + └─ /* ─▶ web :3670 ``` Production runs on the same host and Docker daemon as staging and shares @@ -332,8 +346,8 @@ set up yet. `~/.demoflow/production/cloudflared.env`, mode 600, as one line: `TUNNEL_TOKEN=...`. 2. **The first run.** Push to `main`. `refresh.sh` creates the stack directory, - copies the examples in and generates `POSTGRES_PASSWORD`. It then stops, - because the tunnel token is missing. + copies the examples in and generates `POSTGRES_PASSWORD` and + `SHARE_SIGNING_SECRET`. It then stops, because the tunnel token is missing. 3. **Add the token and start the stack:** ```sh cp ~/.demoflow/production/cloudflared.env /home/archi/stacks/demoflow-production/env/cloudflared.env diff --git a/deploy/production/.env.example b/deploy/production/.env.example index 4951b145..fde184d1 100644 --- a/deploy/production/.env.example +++ b/deploy/production/.env.example @@ -2,3 +2,5 @@ # /home/archi/stacks/demoflow-production/.env (mode 600) on the first run and # fills every empty value with fresh randomness; nothing here is typed by hand. POSTGRES_PASSWORD= +# Signs share unlock cookies (spec #348). +SHARE_SIGNING_SECRET= diff --git a/deploy/production/docker-compose.yml b/deploy/production/docker-compose.yml index 7d0d77ef..6621d1f5 100644 --- a/deploy/production/docker-compose.yml +++ b/deploy/production/docker-compose.yml @@ -50,6 +50,7 @@ services: environment: DATABASE_URL: postgresql://postgres:${POSTGRES_PASSWORD}@postgres:5432/demoflow?schema=public SHARE_DIR: /data/shares + SHARE_SIGNING_SECRET: ${SHARE_SIGNING_SECRET:?set it in .env} # Shared videos and posters (spec #347). Not backed up. volumes: - shares:/data/shares diff --git a/deploy/production/refresh.sh b/deploy/production/refresh.sh index 784c2cf8..dc43abde 100755 --- a/deploy/production/refresh.sh +++ b/deploy/production/refresh.sh @@ -59,6 +59,7 @@ fill_if_empty() { } hex() { od -An -tx1 -N24 /dev/urandom | tr -d ' \n'; } fill_if_empty POSTGRES_PASSWORD "$(hex)" "$PRODUCTION_DIR/.env" +fill_if_empty SHARE_SIGNING_SECRET "$(hex)" "$PRODUCTION_DIR/.env" # ── stack files: always the commit's own ──────────────────────────────────── caddy_changed=false diff --git a/deploy/staging/.env.example b/deploy/staging/.env.example index a5a43f4c..c109ecd5 100644 --- a/deploy/staging/.env.example +++ b/deploy/staging/.env.example @@ -2,3 +2,5 @@ # /home/archi/stacks/demoflow-staging/.env (mode 600) on the first run and # fills every empty value with fresh randomness; nothing here is typed by hand. POSTGRES_PASSWORD= +# Signs share unlock cookies (spec #348). +SHARE_SIGNING_SECRET= diff --git a/deploy/staging/docker-compose.yml b/deploy/staging/docker-compose.yml index 6ba2b3c2..0c70d610 100644 --- a/deploy/staging/docker-compose.yml +++ b/deploy/staging/docker-compose.yml @@ -46,6 +46,7 @@ services: environment: DATABASE_URL: postgresql://postgres:${POSTGRES_PASSWORD}@postgres:5432/demoflow?schema=public SHARE_DIR: /data/shares + SHARE_SIGNING_SECRET: ${SHARE_SIGNING_SECRET:?set it in .env} # Shared videos and posters (spec #347). Not backed up. volumes: - shares:/data/shares diff --git a/deploy/staging/refresh.sh b/deploy/staging/refresh.sh index d8bd2303..3f5ab54f 100755 --- a/deploy/staging/refresh.sh +++ b/deploy/staging/refresh.sh @@ -59,6 +59,7 @@ fill_if_empty() { } hex() { od -An -tx1 -N24 /dev/urandom | tr -d ' \n'; } fill_if_empty POSTGRES_PASSWORD "$(hex)" "$STAGING_DIR/.env" +fill_if_empty SHARE_SIGNING_SECRET "$(hex)" "$STAGING_DIR/.env" # ── stack files: always the commit's own ──────────────────────────────────── caddy_changed=false From 698d27f12e2c1cbeae803b3ac8fd101d7b5c6cb8 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 15:04:28 +0100 Subject: [PATCH 29/71] feat(cli): the runner inspects and initialises a project folder the website names, inside allowed roots Adds allowed-roots.json with runner allow/disallow/roots, the path rule, and the project.inspect, project.init and project.register socket requests (#377, ADR-0022). Website-registered roots are kept in website-projects.jsonl and accepted by checkProject while they still pass the path rule. launches.sync announces features: ['projects']. --- apps/cli/README.md | 31 + apps/cli/src/commands/init.ts | 64 +- apps/cli/src/runner/command.ts | 31 + apps/cli/src/runner/connection.ts | 15 +- apps/cli/src/runner/daemon.ts | 23 +- apps/cli/src/runner/launch/checks.ts | 10 +- apps/cli/src/runner/paths.ts | 6 + apps/cli/src/runner/roots/allowed.ts | 105 +++ apps/cli/src/runner/roots/commands.ts | 149 ++++ apps/cli/src/runner/roots/git-remote.ts | 138 ++++ apps/cli/src/runner/roots/index.ts | 228 ++++++ apps/cli/src/runner/roots/inspect.ts | 84 +++ apps/cli/src/runner/roots/path-rule.ts | 100 +++ apps/cli/src/runner/roots/registry.ts | 90 +++ apps/cli/test/runner/connection.spec.ts | 56 +- apps/cli/test/runner/daemon-launch.spec.ts | 9 +- apps/cli/test/runner/roots.spec.ts | 817 +++++++++++++++++++++ 17 files changed, 1942 insertions(+), 14 deletions(-) create mode 100644 apps/cli/src/runner/roots/allowed.ts create mode 100644 apps/cli/src/runner/roots/commands.ts create mode 100644 apps/cli/src/runner/roots/git-remote.ts create mode 100644 apps/cli/src/runner/roots/index.ts create mode 100644 apps/cli/src/runner/roots/inspect.ts create mode 100644 apps/cli/src/runner/roots/path-rule.ts create mode 100644 apps/cli/src/runner/roots/registry.ts create mode 100644 apps/cli/test/runner/roots.spec.ts diff --git a/apps/cli/README.md b/apps/cli/README.md index a16dc4f5..4cbc043d 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -197,6 +197,7 @@ typed value. Secret fills are left as recorded. | `demoflow runner start` | keep this machine connected, in the background | | `demoflow runner stop` / `status` / `logs` | stop it, check it, read its log | | `demoflow runner install` / `uninstall` | start the runner at every login, or stop doing so | +| `demoflow runner allow <dir>` / `disallow <dir>` / `roots` | choose the folders the website may name | ## Pair this machine with your account @@ -272,6 +273,36 @@ A crash is restarted (systemd, launchd). A runner stopped on purpose, or revoked on the website, exits cleanly and stays down. Windows does not restart a crash; the next logon starts it again. Neither file holds the token. +### Folders the website may name + +From the website you can add a project by naming a folder on this machine. +The runner then reads that folder (whether it has `demoflow.config.json`, +its scenarios' ids and names, the GitHub `origin` of `.git/config`), can +create the `demoflow init` files in it, and can register it so the website +may start runs there. It never sends a file's contents or a config value. + +A folder qualifies only inside an allowed root. By default the only root is +your home directory. + +```sh +npx demoflow runner allow ~/code # the first allow replaces the home directory +npx demoflow runner disallow ~/code # removing the last root allows nothing +npx demoflow runner roots # the roots in force; --json for a script +``` + +- The roots are in `allowed-roots.json` (`{ "roots": [...] }`, at most 32, + mode 0600) next to `credentials.json`. A file that does not parse refuses + every folder until you fix or delete it; `roots` says so. +- The folder must exist, be a directory, and be reached without a link that + leads out of its root. No folder below the root may start with `.`, so + `~/.ssh` or `~/.config` are never offered. +- On Windows a drive path is required (`C:\…`); network (`\\server\…`) and + device (`\\?\…`) paths are refused. Windows and macOS compare paths without + case. +- The folders registered from the website are kept in + `website-projects.jsonl` next to `credentials.json` (the last 1,000). A + folder whose root you disallow stops being runnable from the website. + ## Runs on the website On a paired machine, `demoflow run` tells the website that the run happened, so diff --git a/apps/cli/src/commands/init.ts b/apps/cli/src/commands/init.ts index 3753bc72..d47feed2 100644 --- a/apps/cli/src/commands/init.ts +++ b/apps/cli/src/commands/init.ts @@ -1,3 +1,4 @@ +import { realpathSync } from 'node:fs'; import { mkdir, writeFile } from 'node:fs/promises'; import path from 'node:path'; import { parseProjectConfig } from '@demoflow/core'; @@ -50,13 +51,11 @@ export async function initCommand( return EXIT_INVALID_INPUT; } - const files: [string, unknown][] = [ - [PROJECT_CONFIG_FILE, config], - [FIRST_SCENARIO, FIRST_SCENARIO_TEMPLATE], - ]; - for (const [rel, content] of files) { - const created = await createExclusive(deps.cwd, rel, content); - io.stdout(`${created ? 'created' : 'kept'} ${rel}\n`); + const written = await writeInitTemplate(deps.cwd, { + baseUrl: config.baseUrl, + }); + for (const rel of INIT_FILES) { + io.stdout(`${written.created.includes(rel) ? 'created' : 'kept'} ${rel}\n`); } io.stdout( [ @@ -71,15 +70,64 @@ export async function initCommand( return 0; } +/** The files `demoflow init` writes, in the order it reports them. */ +export const INIT_FILES = [PROJECT_CONFIG_FILE, FIRST_SCENARIO] as const; + +export interface InitTemplateOptions { + baseUrl?: string; + /** + * Spec 377: for a folder the website named, a file is never written through + * a linked directory, which could point anywhere; it throws instead. + */ + noLinks?: boolean; +} + +export interface InitTemplateResult { + created: string[]; + kept: string[]; +} + +/** + * The file-writing half of `demoflow init`, shared with the runner's + * `project.init` (spec 377, Decision 7): the config and the first scenario, + * each created only when it does not exist yet. + */ +export async function writeInitTemplate( + root: string, + options: InitTemplateOptions = {}, +): Promise<InitTemplateResult> { + const contents: Record<(typeof INIT_FILES)[number], unknown> = { + [PROJECT_CONFIG_FILE]: { baseUrl: options.baseUrl ?? DEFAULT_BASE_URL }, + [FIRST_SCENARIO]: FIRST_SCENARIO_TEMPLATE, + }; + const result: InitTemplateResult = { created: [], kept: [] }; + for (const rel of INIT_FILES) { + const created = await createExclusive( + root, + rel, + contents[rel], + options.noLinks === true, + ); + (created ? result.created : result.kept).push(rel); + } + return result; +} + /** `false` when the file already exists; it is left untouched. */ async function createExclusive( cwd: string, rel: string, content: unknown, + noLinks: boolean, ): Promise<boolean> { const file = path.join(cwd, ...rel.split('/')); - await mkdir(path.dirname(file), { recursive: true }); + const dir = path.dirname(file); + await mkdir(dir, { recursive: true }); + if (noLinks && realpathSync.native(dir) !== dir) { + throw new Error(`${path.dirname(rel)} is reached through a link`); + } try { + // `wx` also refuses a link in the file's place, dangling or not. await writeFile(file, `${JSON.stringify(content, null, 2)}\n`, { flag: 'wx', }); diff --git a/apps/cli/src/runner/command.ts b/apps/cli/src/runner/command.ts index 5b61c93f..de493e83 100644 --- a/apps/cli/src/runner/command.ts +++ b/apps/cli/src/runner/command.ts @@ -10,6 +10,11 @@ import { } from './control.ts'; import { defaultDaemonDeps, runForeground } from './daemon.ts'; import { installCommand, uninstallCommand } from './install/commands.ts'; +import { + allowCommand, + disallowCommand, + rootsCommand, +} from './roots/commands.ts'; /** * `demoflow runner`: the background daemon of spec 151. The hidden @@ -79,5 +84,31 @@ export function registerRunnerCommands( setExit(uninstallCommand(io, defaultControlDeps())); }); + const rootsDeps = () => ({ host: currentHost(), cwd: process.cwd() }); + + runner + .command('allow') + .description('Let the website name folders inside this directory') + .argument('<dir>', 'an existing directory') + .action((dir: string) => { + setExit(allowCommand(dir, io, rootsDeps())); + }); + + runner + .command('disallow') + .description('Stop the website naming folders inside this directory') + .argument('<dir>', 'an allowed root') + .action((dir: string) => { + setExit(disallowCommand(dir, io, rootsDeps())); + }); + + runner + .command('roots') + .description('List the directories the website may name folders in') + .option('--json', 'print the roots as one JSON object') + .action((flags: { json?: boolean }) => { + setExit(rootsCommand(flags, io, rootsDeps())); + }); + return runner; } diff --git a/apps/cli/src/runner/connection.ts b/apps/cli/src/runner/connection.ts index 38d1d803..d8d75dd9 100644 --- a/apps/cli/src/runner/connection.ts +++ b/apps/cli/src/runner/connection.ts @@ -7,6 +7,7 @@ import { } from './launch/index.ts'; import type { Logger } from './log.ts'; import type { RelaySender, VideoRelayPort } from './relay/index.ts'; +import type { ProjectsPort } from './roots/index.ts'; import type { ConnectionState } from './state.ts'; /** Decision 6: each side pings every 25 s and gives up after 60 s of silence. */ @@ -77,6 +78,8 @@ export interface ConnectionDeps { artifacts?: ArtifactsPort; /** Answers `scenarios.list` and `run.*` (spec 248); without it, logged as unknown. */ launches?: LaunchPort; + /** Answers `project.*` (spec 377); without it, logged as unknown. */ + projects?: ProjectsPort; } export type ConnectionOutcome = 'stopped' | 'revoked'; @@ -183,7 +186,9 @@ export class RunnerConnection { // Spec 326, Decision 1: a connection without a launcher ignores run.start, // so it claims no options. const runOptions = this.deps.launches !== undefined ? [...RUN_OPTIONS] : []; - this.send({ type: 'launches.sync', running, runOptions }); + // Spec 377, Decision 9: what else this daemon answers. + const features = this.deps.projects !== undefined ? ['projects'] : []; + this.send({ type: 'launches.sync', running, runOptions, features }); this.deps.logger.log( 'info', `announced ${running.length} running launch${running.length === 1 ? '' : 'es'}`, @@ -254,6 +259,14 @@ export class RunnerConnection { return; } break; + case 'project.inspect': + case 'project.init': + case 'project.register': + if (this.deps.projects !== undefined) { + this.deps.projects.handle(fields, this.relaySender()); + return; + } + break; } this.deps.logger.log( 'warn', diff --git a/apps/cli/src/runner/daemon.ts b/apps/cli/src/runner/daemon.ts index 9946fe4d..8c92a6ed 100644 --- a/apps/cli/src/runner/daemon.ts +++ b/apps/cli/src/runner/daemon.ts @@ -18,6 +18,11 @@ import { acquireLock, releaseLock } from './lock.ts'; import { fileLogger, type Logger } from './log.ts'; import { runnerPaths } from './paths.ts'; import { nodeRelayFs, VideoRelay } from './relay/index.ts'; +import { + defaultWriteTemplate, + isWebsiteRegistered, + ProjectRequests, +} from './roots/index.ts'; import { type ConnectionState, writeState } from './state.ts'; /** How often the daemon looks for `runner.stop`. */ @@ -105,14 +110,22 @@ export async function runForeground(io: Io, deps: DaemonDeps): Promise<number> { logger, platform: deps.host.platform, }); + const projectsFiles = { + allowedRootsFile: paths.allowedRoots, + websiteProjectsFile: paths.websiteProjects, + host: deps.host, + }; + const launcherDeps = defaultLauncherDeps(deps.host); const launcher = new Launcher({ indexFile: paths.reportedRuns, + websiteRegistered: (rootPath) => + isWebsiteRegistered(rootPath, { ...projectsFiles, fs: nodeLaunchFs }), fs: nodeLaunchFs, logger, clock: deps.clock, env: deps.host.env, spawn: deps.spawn, - ...defaultLauncherDeps(deps.host), + ...launcherDeps, }); const connection = new RunnerConnection({ server: credentials.server, @@ -140,6 +153,14 @@ export async function runForeground(io: Io, deps: DaemonDeps): Promise<number> { closeRun: (runId) => relay.closeRun(runId), }), launches: launcher, + projects: new ProjectRequests({ + ...projectsFiles, + fs: nodeLaunchFs, + logger, + clock: deps.clock, + loadProject: launcherDeps.loadProject, + writeTemplate: defaultWriteTemplate, + }), }); const stop = (why: string) => { diff --git a/apps/cli/src/runner/launch/checks.ts b/apps/cli/src/runner/launch/checks.ts index 1007cbad..888e6634 100644 --- a/apps/cli/src/runner/launch/checks.ts +++ b/apps/cli/src/runner/launch/checks.ts @@ -72,6 +72,11 @@ export type ProjectLoad = export interface CheckDeps { /** `reported-runs.jsonl`: the registry (Decision 1). */ indexFile: string; + /** + * Spec 377, Decision 8: is the root registered from the website and still + * allowed? The registry is the union of both files (ADR-0022 §4). + */ + websiteRegistered?(rootPath: string): Promise<boolean>; fs: LaunchFs; loadProject(root: string): ProjectLoad; } @@ -90,7 +95,10 @@ export async function checkProject( deps: CheckDeps, ): Promise<ProjectCheck> { const unknown = { ok: false, code: 'project-unknown' } as const; - if (!(await knownRoots(deps.indexFile)).has(rootPath)) return unknown; + const known = + (await knownRoots(deps.indexFile)).has(rootPath) || + ((await deps.websiteRegistered?.(rootPath)) ?? false); + if (!known) return unknown; try { if ((await deps.fs.realpath(rootPath)) !== rootPath) return unknown; if (!(await deps.fs.lstat(rootPath)).isDirectory()) return unknown; diff --git a/apps/cli/src/runner/paths.ts b/apps/cli/src/runner/paths.ts index bae0a755..11bb6b1a 100644 --- a/apps/cli/src/runner/paths.ts +++ b/apps/cli/src/runner/paths.ts @@ -14,6 +14,10 @@ export interface RunnerPaths { stop: string; /** Server run id → run directory, one JSON line per reported run (spec 192). */ reportedRuns: string; + /** The folders the website may name (spec 377, Decision 1). */ + allowedRoots: string; + /** Roots registered from the website, one JSON line each (spec 377, Decision 8). */ + websiteProjects: string; } export function runnerPaths(host: HostEnvironment): RunnerPaths { @@ -26,5 +30,7 @@ export function runnerPaths(host: HostEnvironment): RunnerPaths { state: p.join(dir, 'runner.state.json'), stop: p.join(dir, 'runner.stop'), reportedRuns: p.join(dir, 'reported-runs.jsonl'), + allowedRoots: p.join(dir, 'allowed-roots.json'), + websiteProjects: p.join(dir, 'website-projects.jsonl'), }; } diff --git a/apps/cli/src/runner/roots/allowed.ts b/apps/cli/src/runner/roots/allowed.ts new file mode 100644 index 00000000..00d377ea --- /dev/null +++ b/apps/cli/src/runner/roots/allowed.ts @@ -0,0 +1,105 @@ +import { + chmodSync, + mkdirSync, + readFileSync, + renameSync, + rmSync, + writeFileSync, +} from 'node:fs'; +import { type HostEnvironment, pathFor } from '../../config/platform.ts'; + +/** Decision 1: the list holds at most this many roots. */ +export const ALLOWED_ROOTS_MAX = 32; +/** Decision 3: a path longer than this is never allowed. */ +export const PATH_MAX_LENGTH = 4096; + +/** + * Decision 1: what `allowed-roots.json` says. `default` is the home directory + * of a machine without the file; `invalid` is a file that does not parse, + * which allows nothing. + */ +export type AllowedRoots = + | { source: 'default' | 'file'; roots: string[] } + | { source: 'invalid'; roots: [] }; + +function errorCode(error: unknown): unknown { + return typeof error === 'object' && error !== null && 'code' in error + ? error.code + : undefined; +} + +/** Absolute for the host, at most 4,096 characters, no NUL. */ +export function isAbsoluteFor( + value: unknown, + platform: NodeJS.Platform, +): value is string { + if ( + typeof value !== 'string' || + value.length === 0 || + value.length > PATH_MAX_LENGTH || + value.includes('\0') + ) { + return false; + } + // A drive letter only: `\foo` is drive-relative and UNC or device paths + // (`\\server`, `\\?\`) are refused. + if (platform === 'win32') return /^[A-Za-z]:[\\/]/.test(value); + return pathFor(platform).isAbsolute(value); +} + +/** + * The roots in force, read afresh on every call so the daemon needs no + * restart. Never throws; anything but a missing file that does not parse is + * `invalid`, so a broken file never widens access. + */ +export function readAllowedRoots( + file: string, + host: HostEnvironment, +): AllowedRoots { + let text: string; + try { + text = readFileSync(file, 'utf8'); + } catch (error) { + if (errorCode(error) === 'ENOENT') { + return { source: 'default', roots: [host.homedir] }; + } + return { source: 'invalid', roots: [] }; + } + try { + const parsed: unknown = JSON.parse(text); + if (typeof parsed !== 'object' || parsed === null) throw new Error(); + const { roots } = parsed as Record<string, unknown>; + if ( + !Array.isArray(roots) || + roots.length > ALLOWED_ROOTS_MAX || + !roots.every((root) => isAbsoluteFor(root, host.platform)) + ) { + throw new Error(); + } + return { source: 'file', roots: roots as string[] }; + } catch { + return { source: 'invalid', roots: [] }; + } +} + +/** Written atomically with mode 600, like `credentials.json`. */ +export function writeAllowedRoots( + file: string, + roots: readonly string[], + platform: NodeJS.Platform, +): void { + const p = pathFor(platform); + mkdirSync(p.dirname(file), { recursive: true }); + const temp = `${file}.${process.pid}.tmp`; + try { + writeFileSync(temp, `${JSON.stringify({ roots }, null, 2)}\n`, { + mode: 0o600, + }); + // `mode` is masked by the umask and ignored on an existing file. + if (platform !== 'win32') chmodSync(temp, 0o600); + renameSync(temp, file); + } catch (error) { + rmSync(temp, { force: true }); + throw error; + } +} diff --git a/apps/cli/src/runner/roots/commands.ts b/apps/cli/src/runner/roots/commands.ts new file mode 100644 index 00000000..04476f31 --- /dev/null +++ b/apps/cli/src/runner/roots/commands.ts @@ -0,0 +1,149 @@ +import { realpathSync, statSync } from 'node:fs'; +import type { Io } from '../../commands/io.ts'; +import { EXIT_INVALID_INPUT } from '../../config/index.ts'; +import { type HostEnvironment, pathFor } from '../../config/platform.ts'; +import { runnerPaths } from '../paths.ts'; +import { + ALLOWED_ROOTS_MAX, + type AllowedRoots, + readAllowedRoots, + writeAllowedRoots, +} from './allowed.ts'; +import { samePath } from './path-rule.ts'; + +export interface RootsDeps { + host: HostEnvironment; + cwd: string; +} + +function invalidNote(file: string): string { + return `${file} is invalid: every folder is refused until it is fixed or removed`; +} + +/** + * `demoflow runner roots [--json]` (spec 377, Decision 2): the roots in + * force, the default marked. Exits 1 when the file is invalid. + */ +export function rootsCommand( + flags: { json?: boolean }, + io: Io, + deps: RootsDeps, +): number { + const file = runnerPaths(deps.host).allowedRoots; + const allowed = readAllowedRoots(file, deps.host); + const valid = allowed.source !== 'invalid'; + if (flags.json === true) { + io.stdout( + `${JSON.stringify({ roots: allowed.roots, default: allowed.source === 'default', valid })}\n`, + ); + return valid ? 0 : 1; + } + if (!valid) { + io.stderr(`${invalidNote(file)}\n`); + return 1; + } + if (allowed.roots.length === 0) { + io.stdout('No allowed roots: the website may name no folder\n'); + return 0; + } + for (const root of allowed.roots) { + io.stdout( + `${root}${allowed.source === 'default' ? ' (default: the home directory)' : ''}\n`, + ); + } + return 0; +} + +/** + * `demoflow runner allow <dir>`: adds the real path of an existing + * directory. The first `allow` on a machine without the file replaces the + * default home directory (Decision 2). + */ +export function allowCommand(dir: string, io: Io, deps: RootsDeps): number { + const { platform } = deps.host; + const resolved = pathFor(platform).resolve(deps.cwd, dir); + let real: string; + try { + if (!statSync(resolved).isDirectory()) throw new Error(); + real = realpathSync.native(resolved); + } catch { + io.stderr(`Not a directory: ${resolved}\n`); + return EXIT_INVALID_INPUT; + } + const file = runnerPaths(deps.host).allowedRoots; + const allowed = readAllowedRoots(file, deps.host); + const current = allowed.source === 'file' ? allowed.roots : []; + if (current.some((root) => samePath(root, real, platform))) { + io.stdout(`Already allowed: ${real}\n`); + return 0; + } + if (current.length >= ALLOWED_ROOTS_MAX) { + io.stderr( + `At most ${ALLOWED_ROOTS_MAX} allowed roots; disallow one first\n`, + ); + return EXIT_INVALID_INPUT; + } + writeAllowedRoots(file, [...current, real], platform); + io.stdout(`Allowed: ${real}\n`); + printReplaced(allowed, real, io, deps.host); + return 0; +} + +function printReplaced( + allowed: AllowedRoots, + added: string, + io: Io, + host: HostEnvironment, +): void { + if (allowed.source === 'invalid') { + io.stdout('The invalid allowed-roots file was replaced\n'); + } else if ( + allowed.source === 'default' && + !samePath(added, realOrResolved(host.homedir, host.platform), host.platform) + ) { + io.stdout( + `The home directory (${host.homedir}) is no longer allowed; allow it again to keep it\n`, + ); + } +} + +function realOrResolved(dir: string, platform: NodeJS.Platform): string { + try { + return realpathSync.native(dir); + } catch { + return pathFor(platform).resolve(dir); + } +} + +/** + * `demoflow runner disallow <dir>`: removes the entry equal to the folder's + * real path, or its resolved path once it is gone. Removing the last one + * allows nothing, never the default again (Decision 2). + */ +export function disallowCommand(dir: string, io: Io, deps: RootsDeps): number { + const { platform } = deps.host; + const target = realOrResolved( + pathFor(platform).resolve(deps.cwd, dir), + platform, + ); + const file = runnerPaths(deps.host).allowedRoots; + const allowed = readAllowedRoots(file, deps.host); + if (allowed.source === 'invalid') { + io.stderr(`${invalidNote(file)}\n`); + return 1; + } + const matches = (root: string) => + samePath(root, target, platform) || + samePath(realOrResolved(root, platform), target, platform); + const kept = allowed.roots.filter((root) => !matches(root)); + if (kept.length === allowed.roots.length) { + io.stderr(`Not an allowed root: ${target}\n`); + return 1; + } + writeAllowedRoots(file, kept, platform); + io.stdout(`Disallowed: ${target}\n`); + if (kept.length === 0) { + io.stdout('No allowed roots left: the website may name no folder\n'); + } + return 0; +} diff --git a/apps/cli/src/runner/roots/git-remote.ts b/apps/cli/src/runner/roots/git-remote.ts new file mode 100644 index 00000000..997d54b4 --- /dev/null +++ b/apps/cli/src/runner/roots/git-remote.ts @@ -0,0 +1,138 @@ +import { pathFor } from '../../config/platform.ts'; +import type { LaunchFs } from '../launch/checks.ts'; +import { realRoots, segmentsBelow } from './path-rule.ts'; + +/** Decision 6: a git config file is read only up to this size. */ +export const GIT_CONFIG_MAX_BYTES = 64 * 1024; +/** A `.git` file or `commondir` is one short line. */ +const GIT_POINTER_MAX_BYTES = 4096; + +const NAME = '[A-Za-z0-9._-]{1,100}'; +const GITHUB_REMOTES = [ + new RegExp(`^https://github\\.com/(${NAME})/(${NAME})/?$`), + new RegExp(`^git@github\\.com:(${NAME})/(${NAME})$`), + new RegExp(`^ssh://git@github\\.com/(${NAME})/(${NAME})/?$`), +]; + +/** + * Decision 6: `https://github.com/<owner>/<repo>` for an https, scp-style or + * ssh remote on github.com; anything else — another host, a port, a URL with + * credentials — is `undefined`. + */ +export function githubUrlFrom(remote: string): string | undefined { + for (const pattern of GITHUB_REMOTES) { + const match = pattern.exec(remote); + if (match === null) continue; + const owner = match[1] as string; + const repo = (match[2] as string).replace(/\.git$/, ''); + if ([owner, repo].some((name) => /^\.*$/.test(name))) return undefined; + return `https://github.com/${owner}/${repo}`; + } + return undefined; +} + +/** The first `url` of `[remote "origin"]` in a git config file, unquoted. */ +export function originUrl(config: string): string | undefined { + let inOrigin = false; + for (const raw of config.split(/\r?\n/)) { + const line = raw.trim(); + const section = /^\[\s*([^\s\]"]+)(?:\s+"((?:[^"\\]|\\.)*)")?\s*\]/.exec( + line, + ); + if (section !== null) { + // Section names ignore case; subsection names do not. + inOrigin = + section[1]?.toLowerCase() === 'remote' && section[2] === 'origin'; + continue; + } + if (!inOrigin) continue; + const entry = /^url\s*=\s*(.*)$/i.exec(line); + if (entry === null) continue; + let value = (entry[1] as string).trim(); + if (value.startsWith('"')) { + const end = value.indexOf('"', 1); + value = end === -1 ? '' : value.slice(1, end); + } else { + value = value.replace(/\s[#;].*$/, '').trim(); + } + return value; + } + return undefined; +} + +async function readRegularFile( + file: string, + maxBytes: number, + fs: LaunchFs, +): Promise<string> { + if (!(await fs.lstat(file)).isFile()) throw new Error('not a file'); + return fs.readFile(file, maxBytes); +} + +/** + * Decision 6: the GitHub URL of the canonical folder `root`'s `origin`, read + * from its git config without running git. A `.git` file is followed one + * level (to its `gitdir`, and from a worktree's gitdir to its `commondir`), + * and only to a directory inside an allowed root. Never throws. + */ +export async function githubUrlOf( + root: string, + roots: readonly string[], + platform: NodeJS.Platform, + fs: LaunchFs, +): Promise<string | undefined> { + const p = pathFor(platform); + try { + const dotGit = p.join(root, '.git'); + const stats = await fs.lstat(dotGit); + let config: string; + if (stats.isDirectory()) { + config = await readRegularFile( + p.join(dotGit, 'config'), + GIT_CONFIG_MAX_BYTES, + fs, + ); + } else if (stats.isFile()) { + const allowed = await realRoots(roots, fs); + const follow = async (from: string, value: string) => { + const target = await fs.realpath(p.resolve(from, value.trim())); + if (!allowed.some((r) => segmentsBelow(target, r, platform) !== null)) { + throw new Error('outside the allowed roots'); + } + if (!(await fs.lstat(target)).isDirectory()) { + throw new Error('not a directory'); + } + return target; + }; + const pointer = await readRegularFile(dotGit, GIT_POINTER_MAX_BYTES, fs); + const gitdir = /^gitdir:\s*(.+)$/m.exec(pointer)?.[1]; + if (gitdir === undefined) return undefined; + const dir = await follow(root, gitdir); + try { + config = await readRegularFile( + p.join(dir, 'config'), + GIT_CONFIG_MAX_BYTES, + fs, + ); + } catch { + // A worktree's gitdir keeps its config in the common directory. + const common = await readRegularFile( + p.join(dir, 'commondir'), + GIT_POINTER_MAX_BYTES, + fs, + ); + config = await readRegularFile( + p.join(await follow(dir, common), 'config'), + GIT_CONFIG_MAX_BYTES, + fs, + ); + } + } else { + return undefined; + } + const url = originUrl(config); + return url === undefined ? undefined : githubUrlFrom(url); + } catch { + return undefined; + } +} diff --git a/apps/cli/src/runner/roots/index.ts b/apps/cli/src/runner/roots/index.ts new file mode 100644 index 00000000..c15ab88e --- /dev/null +++ b/apps/cli/src/runner/roots/index.ts @@ -0,0 +1,228 @@ +import { + type InitTemplateResult, + writeInitTemplate, +} from '../../commands/init.ts'; +import { PROJECT_CONFIG_FILE } from '../../config/index.ts'; +import { type HostEnvironment, pathFor } from '../../config/platform.ts'; +import type { Clock } from '../connection.ts'; +import type { LaunchFs, ProjectLoad } from '../launch/checks.ts'; +import type { Logger } from '../log.ts'; +import { readAllowedRoots } from './allowed.ts'; +import { fitted, type Inspection, inspectFolder } from './inspect.ts'; +import { isAllowedPath } from './path-rule.ts'; +import { registerWebsiteProject, websiteRoots } from './registry.ts'; + +/** Decision 10: a request not answered by then is answered `internal`. */ +export const PROJECT_REQUEST_MAX_MS = 5_000; + +export const PROJECT_REQUESTS = [ + 'project.inspect', + 'project.init', + 'project.register', +] as const; +type ProjectRequest = (typeof PROJECT_REQUESTS)[number]; + +/** Decision 4: the codes of `project.error`. */ +export type ProjectErrorCode = + | 'path-not-allowed' + | 'config-missing' + | 'config-invalid' + | 'busy' + | 'internal'; + +/** The socket, as the project requests see it: JSON text frames only. */ +export interface ProjectsSender { + send(message: Record<string, unknown>): void; +} + +/** What the connection needs from the project requests. */ +export interface ProjectsPort { + handle(message: Record<string, unknown>, sender: ProjectsSender): void; +} + +export interface ProjectsDeps { + /** `allowed-roots.json`, read on every request. */ + allowedRootsFile: string; + /** `website-projects.jsonl`. */ + websiteProjectsFile: string; + host: HostEnvironment; + fs: LaunchFs; + logger: Logger; + clock: Clock; + loadProject(root: string): ProjectLoad; + /** The `demoflow init` template, never through a link (Decision 7). */ + writeTemplate(root: string): Promise<InitTemplateResult>; +} + +export const defaultWriteTemplate = (root: string) => + writeInitTemplate(root, { noLinks: true }); + +/** A refusal that becomes `project.error` with its code. */ +class Refused extends Error { + readonly code: ProjectErrorCode; + + constructor(code: ProjectErrorCode) { + super(code); + this.code = code; + } +} + +/** A request id as `runner.log` shows it: one short line, whatever was sent. */ +function shown(requestId: string): string { + return requestId.slice(0, 64).replace(/[^A-Za-z0-9-]/g, '?'); +} + +/** + * Decision 8: a root the website registered counts for `checkProject` only + * while it is still in the file and still passes the path rule, as itself. + */ +export async function isWebsiteRegistered( + rootPath: string, + deps: Pick< + ProjectsDeps, + 'allowedRootsFile' | 'websiteProjectsFile' | 'host' + > & { + fs: Pick<LaunchFs, 'realpath' | 'lstat'>; + }, +): Promise<boolean> { + if (!(await websiteRoots(deps.websiteProjectsFile)).has(rootPath)) { + return false; + } + const { roots } = readAllowedRoots(deps.allowedRootsFile, deps.host); + const check = await isAllowedPath( + rootPath, + roots, + deps.host.platform, + deps.fs, + ); + return check.ok && check.root === rootPath; +} + +/** + * Spec 377: the daemon's side of `project.inspect`, `project.init` and + * `project.register` (ADR-0022 §3). One at a time; each is answered within + * 5 s. `runner.log` gets request ids, outcomes and codes, never a path. + */ +export class ProjectRequests implements ProjectsPort { + private readonly deps: ProjectsDeps; + private inFlight = false; + + constructor(deps: ProjectsDeps) { + this.deps = deps; + } + + handle(message: Record<string, unknown>, sender: ProjectsSender): void { + const { type, requestId, path } = message; + const { logger } = this.deps; + if (!PROJECT_REQUESTS.includes(type as ProjectRequest)) return; + if (typeof requestId !== 'string') { + logger.log('warn', `ignored a malformed ${type as string}`); + return; + } + const request = type as ProjectRequest; + const label = `${request} ${shown(requestId)}`; + const refuse = (code: ProjectErrorCode) => { + logger.log('info', `${label}: refused ${code}`); + sender.send({ type: 'project.error', requestId, code }); + }; + if (this.inFlight) { + refuse('busy'); + return; + } + this.inFlight = true; + let answered = false; + const answer = (send: () => void) => { + if (answered) return; + answered = true; + cancelTimer(); + send(); + }; + const cancelTimer = this.deps.clock.after(PROJECT_REQUEST_MAX_MS, () => { + answer(() => refuse('internal')); + }); + void this.run(request, path) + .then( + (reply) => + answer(() => { + logger.log('info', `${label}: answered`); + sender.send({ ...reply, requestId }); + }), + (error: unknown) => + answer(() => + refuse(error instanceof Refused ? error.code : 'internal'), + ), + ) + .finally(() => { + // Busy until the work itself is over, even after a timeout. + this.inFlight = false; + }); + } + + private async run( + request: ProjectRequest, + raw: unknown, + ): Promise<Record<string, unknown>> { + const { roots } = readAllowedRoots( + this.deps.allowedRootsFile, + this.deps.host, + ); + const check = await isAllowedPath( + raw, + roots, + this.deps.host.platform, + this.deps.fs, + ); + if (!check.ok) throw new Refused('path-not-allowed'); + const root = check.root; + switch (request) { + case 'project.inspect': + return fitted( + (inspection) => ({ type: 'project.inspected', inspection }), + await this.inspect(root, roots), + ); + case 'project.init': { + const { created, kept } = await this.deps.writeTemplate(root); + return fitted( + (inspection) => ({ + type: 'project.initialised', + created, + kept, + inspection, + }), + await this.inspect(root, roots), + ); + } + case 'project.register': + await this.register(root); + return { type: 'project.registered', rootPath: root }; + } + } + + private inspect(root: string, roots: readonly string[]): Promise<Inspection> { + return inspectFolder(root, roots, { + fs: this.deps.fs, + platform: this.deps.host.platform, + loadProject: this.deps.loadProject, + }); + } + + /** Decision 8: a config that exists and loads, then one line in the registry. */ + private async register(root: string): Promise<void> { + const p = pathFor(this.deps.host.platform); + try { + const config = await this.deps.fs.lstat( + p.join(root, PROJECT_CONFIG_FILE), + ); + if (!config.isFile()) throw new Refused('config-missing'); + } catch (error) { + if (error instanceof Refused) throw error; + throw new Refused('config-missing'); + } + if (!this.deps.loadProject(root).ok) throw new Refused('config-invalid'); + registerWebsiteProject( + this.deps.websiteProjectsFile, + root, + new Date(this.deps.clock.now()).toISOString(), + ); + } +} diff --git a/apps/cli/src/runner/roots/inspect.ts b/apps/cli/src/runner/roots/inspect.ts new file mode 100644 index 00000000..703f94e3 --- /dev/null +++ b/apps/cli/src/runner/roots/inspect.ts @@ -0,0 +1,84 @@ +import { PROJECT_CONFIG_FILE } from '../../config/index.ts'; +import { pathFor } from '../../config/platform.ts'; +import type { LaunchFs, ProjectLoad } from '../launch/checks.ts'; +import { + LIST_MAX_FRAME_BYTES, + type ListedScenario, + listScenarios, +} from '../launch/list.ts'; +import { githubUrlOf } from './git-remote.ts'; + +/** + * Decision 5: everything an inspection says. Never a file's contents and + * never a config value such as `baseUrl` or `devCommand`. + */ +export interface Inspection { + rootPath: string; + name: string; + hasConfig: boolean; + configValid: boolean; + scenarios: ListedScenario[]; + githubUrl?: string; +} + +export interface InspectDeps { + fs: LaunchFs; + platform: NodeJS.Platform; + loadProject(root: string): ProjectLoad; +} + +/** + * Decision 5: inspects `root`, a folder that already passed the path rule. + * Scenarios are listed only for a config that loads, by the same rules and + * limits as `scenarios.list`. Throws only when listing them fails. + */ +export async function inspectFolder( + root: string, + roots: readonly string[], + deps: InspectDeps, +): Promise<Inspection> { + const p = pathFor(deps.platform); + let hasConfig = false; + try { + // `lstat`: a linked config is not this folder's config. + hasConfig = ( + await deps.fs.lstat(p.join(root, PROJECT_CONFIG_FILE)) + ).isFile(); + } catch { + // No config. + } + const loaded = hasConfig ? deps.loadProject(root) : null; + const configValid = loaded?.ok === true; + const scenarios = + loaded?.ok === true + ? (await listScenarios(root, deps.fs, loaded.fragmentsDir)).scenarios + : []; + const githubUrl = await githubUrlOf(root, roots, deps.platform, deps.fs); + return { + rootPath: root, + name: p.basename(root), + hasConfig, + configValid, + scenarios, + ...(githubUrl === undefined ? {} : { githubUrl }), + }; +} + +/** + * A reply frame with its inspection's scenarios dropped from the end until it + * is at most 60,000 bytes, as `scenarios.listed` is cut. + */ +export function fitted( + frame: (inspection: Inspection) => Record<string, unknown>, + inspection: Inspection, +): Record<string, unknown> { + const scenarios = [...inspection.scenarios]; + const build = () => frame({ ...inspection, scenarios }); + while ( + scenarios.length > 0 && + Buffer.byteLength(JSON.stringify(build()), 'utf8') > LIST_MAX_FRAME_BYTES + ) { + scenarios.pop(); + } + return build(); +} diff --git a/apps/cli/src/runner/roots/path-rule.ts b/apps/cli/src/runner/roots/path-rule.ts new file mode 100644 index 00000000..1e2a3830 --- /dev/null +++ b/apps/cli/src/runner/roots/path-rule.ts @@ -0,0 +1,100 @@ +import { pathFor } from '../../config/platform.ts'; +import type { LaunchFs } from '../launch/checks.ts'; +import { isAbsoluteFor } from './allowed.ts'; + +/** What the path rule touches: real paths and `lstat`, never a link followed. */ +export type PathFs = Pick<LaunchFs, 'realpath' | 'lstat'>; + +/** `ok` carries the canonical folder; a refusal says nothing more. */ +export type PathCheck = { ok: true; root: string } | { ok: false }; + +/** Decision 3: Windows and macOS compare paths without case. */ +function fold(value: string, platform: NodeJS.Platform): string { + return platform === 'win32' || platform === 'darwin' + ? value.toLowerCase() + : value; +} + +function segments(value: string, platform: NodeJS.Platform): string[] { + return value.split(platform === 'win32' ? /[\\/]/ : '/').filter(Boolean); +} + +export function samePath( + a: string, + b: string, + platform: NodeJS.Platform, +): boolean { + return fold(a, platform) === fold(b, platform); +} + +/** + * The segments of `child` below `parent`, compared segment-wise; `null` when + * `child` is neither `parent` nor below it. Both are real paths. + */ +export function segmentsBelow( + child: string, + parent: string, + platform: NodeJS.Platform, +): string[] | null { + const inner = segments(child, platform); + const outer = segments(parent, platform); + if (outer.length > inner.length) return null; + for (let i = 0; i < outer.length; i++) { + if (!samePath(outer[i] as string, inner[i] as string, platform)) { + return null; + } + } + return inner.slice(outer.length); +} + +/** The real paths of the roots that still resolve; a root that does not is skipped. */ +export async function realRoots( + roots: readonly string[], + fs: PathFs, +): Promise<string[]> { + const real: string[] = []; + for (const root of roots) { + try { + real.push(await fs.realpath(root)); + } catch { + // A root that is gone allows nothing. + } + } + return real; +} + +/** + * Decision 3 (ADR-0022 §2): `raw` names a folder the website may use when it + * is an absolute path for the host, its real path is the path itself (no link + * or junction anywhere on the way, no `..` that leaves it), it is a + * directory, and it is an allowed root or lies below one with no segment + * below that root starting with `.`. Every failure is the same refusal. + */ +export async function isAllowedPath( + raw: unknown, + roots: readonly string[], + platform: NodeJS.Platform, + fs: PathFs, +): Promise<PathCheck> { + const refused = { ok: false } as const; + if (!isAbsoluteFor(raw, platform)) return refused; + let real: string; + try { + // The OS resolves `..` after links, so `link/..` lands where the link + // points and differs from the lexical form below. + real = await fs.realpath(raw); + if (!samePath(real, pathFor(platform).resolve(raw), platform)) { + return refused; + } + if (!(await fs.lstat(real)).isDirectory()) return refused; + } catch { + return refused; + } + for (const root of await realRoots(roots, fs)) { + const below = segmentsBelow(real, root, platform); + if (below?.every((segment) => !segment.startsWith('.'))) { + return { ok: true, root: real }; + } + } + return refused; +} diff --git a/apps/cli/src/runner/roots/registry.ts b/apps/cli/src/runner/roots/registry.ts new file mode 100644 index 00000000..4cd5701c --- /dev/null +++ b/apps/cli/src/runner/roots/registry.ts @@ -0,0 +1,90 @@ +import { + appendFileSync, + chmodSync, + mkdirSync, + readFileSync, + renameSync, + rmSync, + writeFileSync, +} from 'node:fs'; +import { readFile } from 'node:fs/promises'; +import path from 'node:path'; + +/** Decision 8: beyond this many entries the oldest are dropped. */ +export const WEBSITE_PROJECTS_MAX = 1_000; + +/** One line of `website-projects.jsonl`: a root registered from the website. */ +export interface WebsiteProject { + rootPath: string; + registeredAt: string; +} + +function parseLine(line: string): WebsiteProject | null { + try { + const value: unknown = JSON.parse(line); + if (typeof value !== 'object' || value === null) return null; + const { rootPath, registeredAt } = value as Record<string, unknown>; + if (typeof rootPath !== 'string' || rootPath === '') return null; + if (typeof registeredAt !== 'string') return null; + return { rootPath, registeredAt }; + } catch { + return null; + } +} + +function parse(text: string): WebsiteProject[] { + return text + .split('\n') + .map(parseLine) + .filter((entry) => entry !== null); +} + +/** + * Decision 8: the roots registered from the website, read once. Never throws: + * a missing or unreadable file registers nothing. + */ +export async function websiteRoots(file: string): Promise<Set<string>> { + try { + return new Set(parse(await readFile(file, 'utf8')).map((e) => e.rootPath)); + } catch { + return new Set(); + } +} + +/** + * Decision 8: appends `rootPath` once. A root already there is left as it + * is; past 1,000 entries the file is rewritten without the oldest. + */ +export function registerWebsiteProject( + file: string, + rootPath: string, + registeredAt: string, +): void { + let entries: WebsiteProject[] = []; + try { + entries = parse(readFileSync(file, 'utf8')); + } catch { + // A missing file starts empty. + } + if (entries.some((entry) => entry.rootPath === rootPath)) return; + const entry: WebsiteProject = { rootPath, registeredAt }; + mkdirSync(path.dirname(file), { recursive: true }); + if (entries.length < WEBSITE_PROJECTS_MAX) { + appendFileSync(file, `${JSON.stringify(entry)}\n`, { mode: 0o600 }); + return; + } + const kept = [...entries.slice(-(WEBSITE_PROJECTS_MAX - 1)), entry]; + const temp = `${file}.${process.pid}.tmp`; + try { + writeFileSync( + temp, + kept.map((line) => `${JSON.stringify(line)}\n`).join(''), + { mode: 0o600 }, + ); + if (process.platform !== 'win32') chmodSync(temp, 0o600); + renameSync(temp, file); + } catch (error) { + rmSync(temp, { force: true }); + throw error; + } +} diff --git a/apps/cli/test/runner/connection.spec.ts b/apps/cli/test/runner/connection.spec.ts index 77567a51..b62604de 100644 --- a/apps/cli/test/runner/connection.spec.ts +++ b/apps/cli/test/runner/connection.spec.ts @@ -17,6 +17,7 @@ import type { RelaySender, VideoRelayPort, } from '../../src/runner/relay/index.ts'; +import type { ProjectsPort } from '../../src/runner/roots/index.ts'; import type { ConnectionState } from '../../src/runner/state.ts'; import { FakeClock, @@ -28,7 +29,12 @@ import { const TOKEN = 'dfr_old-token'; const NEW_TOKEN = 'dfr_new-token'; -const EMPTY_SYNC = { type: 'launches.sync', running: [], runOptions: [] }; +const EMPTY_SYNC = { + type: 'launches.sync', + running: [], + runOptions: [], + features: [], +}; let clock: FakeClock; let sockets: FakeSocket[]; @@ -45,6 +51,7 @@ function start( relay?: VideoRelayPort, artifacts?: ArtifactsPort, launches?: LaunchPort, + projects?: ProjectsPort, ) { const fake = fakeSockets(); sockets = fake.sockets; @@ -70,6 +77,7 @@ function start( ...(relay === undefined ? {} : { relay }), ...(artifacts === undefined ? {} : { artifacts }), ...(launches === undefined ? {} : { launches }), + ...(projects === undefined ? {} : { projects }), }); void connection.run().then((value) => { outcome = value; @@ -491,6 +499,7 @@ describe('RunnerConnection and the video relay', () => { type: 'launches.sync', running: ids, runOptions: ['formats'], + features: [], }); expect(logger.text()).toContain('announced 1 running launch'); first.serverClose(1006); @@ -500,7 +509,12 @@ describe('RunnerConnection and the video relay', () => { last().open(); expect(last()).not.toBe(first); expect(last().sent).toEqual([ - { type: 'launches.sync', running: [], runOptions: ['formats'] }, + { + type: 'launches.sync', + running: [], + runOptions: ['formats'], + features: [], + }, ]); }); @@ -510,6 +524,44 @@ describe('RunnerConnection and the video relay', () => { expect(last().sent).toEqual([EMPTY_SYNC]); }); + it('announces the projects feature and routes project.* to it (spec 377)', () => { + const handled: Array<Record<string, unknown>> = []; + start(0.5, undefined, undefined, undefined, { + handle: (message, sender) => { + handled.push(message); + sender.send({ type: 'project.error', requestId: 'q', code: 'busy' }); + }, + }); + last().open(); + expect(last().sent[0]).toEqual({ ...EMPTY_SYNC, features: ['projects'] }); + for (const type of [ + 'project.inspect', + 'project.init', + 'project.register', + ]) { + last().receive({ type, requestId: 'q', path: '/x' }); + } + expect(handled.map((message) => message.type)).toEqual([ + 'project.inspect', + 'project.init', + 'project.register', + ]); + expect(last().sent).toContainEqual({ + type: 'project.error', + requestId: 'q', + code: 'busy', + }); + }); + + it('logs project.inspect as unknown without the projects port', () => { + start(); + last().open(); + last().receive({ type: 'project.inspect', requestId: 'q', path: '/x' }); + expect(logger.text()).toMatch( + /ignored a message of type "project.inspect"/, + ); + }); + it('logs run.start as unknown without a launcher, as a daemon before #248 did', () => { start(); last().open(); diff --git a/apps/cli/test/runner/daemon-launch.spec.ts b/apps/cli/test/runner/daemon-launch.spec.ts index 2582c682..87dd5658 100644 --- a/apps/cli/test/runner/daemon-launch.spec.ts +++ b/apps/cli/test/runner/daemon-launch.spec.ts @@ -191,6 +191,7 @@ describe('the daemon with a website-started run', () => { type: 'launches.sync', running: [], runOptions: ['formats'], + features: ['projects'], }); first.receive({ type: 'run.start', @@ -230,6 +231,7 @@ describe('the daemon with a website-started run', () => { type: 'launches.sync', running: [REQUEST], runOptions: ['formats'], + features: ['projects'], }); await stop(next); }); @@ -241,7 +243,12 @@ describe('the daemon with a website-started run', () => { await new Promise((r) => setTimeout(r, 50)); const next = await reconnect(); expect(next.sent).toEqual([ - { type: 'launches.sync', running: [], runOptions: ['formats'] }, + { + type: 'launches.sync', + running: [], + runOptions: ['formats'], + features: ['projects'], + }, ]); }); }); diff --git a/apps/cli/test/runner/roots.spec.ts b/apps/cli/test/runner/roots.spec.ts new file mode 100644 index 00000000..65b37620 --- /dev/null +++ b/apps/cli/test/runner/roots.spec.ts @@ -0,0 +1,817 @@ +import { + mkdirSync, + mkdtempSync, + readFileSync, + realpathSync, + rmSync, + statSync, + symlinkSync, + writeFileSync, +} from 'node:fs'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import type { Io } from '../../src/commands/io.ts'; +import type { HostEnvironment } from '../../src/config/platform.ts'; +import { + checkProject, + type LaunchStats, + nodeLaunchFs, +} from '../../src/runner/launch/checks.ts'; +import { loadProjectFor } from '../../src/runner/launch/index.ts'; +import { runnerPaths } from '../../src/runner/paths.ts'; +import { + ALLOWED_ROOTS_MAX, + readAllowedRoots, +} from '../../src/runner/roots/allowed.ts'; +import { + allowCommand, + disallowCommand, + rootsCommand, +} from '../../src/runner/roots/commands.ts'; +import { + githubUrlFrom, + githubUrlOf, + originUrl, +} from '../../src/runner/roots/git-remote.ts'; +import { + defaultWriteTemplate, + isWebsiteRegistered, + PROJECT_REQUEST_MAX_MS, + ProjectRequests, + type ProjectsDeps, +} from '../../src/runner/roots/index.ts'; +import { + isAllowedPath, + type PathFs, +} from '../../src/runner/roots/path-rule.ts'; +import { + registerWebsiteProject, + WEBSITE_PROJECTS_MAX, + websiteRoots, +} from '../../src/runner/roots/registry.ts'; +import { FakeClock, memoryLogger } from './fakes.ts'; + +const REQUEST = '6f1c2b8e-3d4a-4b5c-9e7f-0a1b2c3d4e5f'; +const FIXTURE = readFileSync( + path.join( + import.meta.dirname, + '../../../fixture/demoflow/customers.demo.json', + ), + 'utf8', +); +const CONFIG = JSON.stringify({ + baseUrl: 'http://localhost:4123', + devCommand: { + command: 'secret-dev-command', + readyUrl: 'http://localhost:4123', + }, +}); + +let tmp: string; +let home: string; +let outside: string; +let host: HostEnvironment; +let clock: FakeClock; +let logger: ReturnType<typeof memoryLogger>; +let sent: Array<Record<string, unknown>>; + +function write(file: string, text: string): void { + mkdirSync(path.dirname(file), { recursive: true }); + writeFileSync(file, text); +} + +function dir(...parts: string[]): string { + const target = path.join(...parts); + mkdirSync(target, { recursive: true }); + return target; +} + +/** A directory link; a junction on Windows, which needs no privilege. */ +function link(target: string, at: string): void { + symlinkSync(target, at, 'junction'); +} + +function files() { + return runnerPaths(host); +} + +function deps(overrides: Partial<ProjectsDeps> = {}): ProjectsDeps { + return { + allowedRootsFile: files().allowedRoots, + websiteProjectsFile: files().websiteProjects, + host, + fs: nodeLaunchFs, + logger, + clock, + loadProject: loadProjectFor(host), + writeTemplate: defaultWriteTemplate, + ...overrides, + }; +} + +function requests(overrides: Partial<ProjectsDeps> = {}): ProjectRequests { + return new ProjectRequests(deps(overrides)); +} + +async function ask( + type: string, + target: unknown, + handler: ProjectRequests = requests(), +): Promise<Record<string, unknown>> { + const before = sent.length; + handler.handle( + { type, requestId: REQUEST, path: target }, + { send: (message) => sent.push(message) }, + ); + await vi.waitFor(() => expect(sent.length).toBe(before + 1)); + return sent[before] as Record<string, unknown>; +} + +const refused = { + type: 'project.error', + requestId: REQUEST, + code: 'path-not-allowed', +}; + +function memoryIo(): Io & { out: string; err: string } { + const io = { + out: '', + err: '', + stdout: (text: string) => { + io.out += text; + }, + stderr: (text: string) => { + io.err += text; + }, + }; + return io as Io & { out: string; err: string }; +} + +const commandDeps = () => ({ host, cwd: home }); + +beforeEach(() => { + tmp = realpathSync.native( + mkdtempSync(path.join(tmpdir(), 'demoflow-roots-')), + ); + home = dir(tmp, 'home'); + outside = dir(tmp, 'outside'); + host = { platform: process.platform, env: {}, homedir: home }; + clock = new FakeClock(); + logger = memoryLogger(); + sent = []; +}); +afterEach(() => { + rmSync(tmp, { recursive: true, force: true }); +}); + +describe('the path rule on this machine', () => { + it('allows a folder in the home directory by default, nothing hidden and nothing outside', async () => { + const app = dir(home, 'work', 'app'); + const ssh = dir(home, '.ssh'); + const hiddenParent = dir(home, '.config', 'app'); + const answer = await ask('project.inspect', app); + expect(answer).toMatchObject({ + type: 'project.inspected', + requestId: REQUEST, + inspection: { rootPath: app, name: 'app' }, + }); + for (const target of [ssh, hiddenParent, outside, tmp]) { + expect(await ask('project.inspect', target)).toEqual(refused); + } + }); + + it('refuses a link inside home that points outside, and a .. that leaves the root', async () => { + const at = path.join(home, 'out'); + link(outside, at); + expect(await ask('project.inspect', at)).toEqual(refused); + expect(await ask('project.inspect', path.join(at, '.'))).toEqual(refused); + expect( + await ask('project.inspect', `${home}${path.sep}..${path.sep}outside`), + ).toEqual(refused); + if (process.platform !== 'win32') { + // POSIX resolves `..` after the link: `jump/..` is `outside`, not `inner`. + dir(home, 'inner'); + link(dir(outside, 'deep'), path.join(home, 'inner', 'jump')); + expect( + await ask('project.inspect', `${path.join(home, 'inner', 'jump')}/..`), + ).toEqual(refused); + } + }); + + it('refuses a relative path, a file, a folder that does not exist, and a non-string', async () => { + write(path.join(home, 'note.txt'), 'x'); + for (const target of [ + 'work/app', + path.join(home, 'note.txt'), + path.join(home, 'missing'), + 42, + '', + 'x'.repeat(4097), + ]) { + expect(await ask('project.inspect', target)).toEqual(refused); + } + }); + + it('accepts another case of the path where the file system ignores case', async () => { + const app = dir(home, 'App'); + const variant = path.join(home, 'APP'); + const answer = await ask('project.inspect', variant); + if (process.platform === 'win32' || process.platform === 'darwin') { + expect(answer).toMatchObject({ + type: 'project.inspected', + inspection: { rootPath: realpathSync.native(variant) }, + }); + } else { + expect(answer).toEqual(refused); + } + expect(await ask('project.inspect', app)).toMatchObject({ + type: 'project.inspected', + }); + }); +}); + +/** A file system of directories only, for another platform's rules. */ +function fakeFs( + platform: NodeJS.Platform, + dirs: string[], + links: Record<string, string> = {}, +): PathFs { + const fold = (value: string) => + platform === 'linux' ? value : value.toLowerCase(); + const p = platform === 'win32' ? path.win32 : path.posix; + const real = new Map(dirs.map((d) => [fold(d), d])); + const stats = (directory: boolean): LaunchStats => ({ + isDirectory: () => directory, + isFile: () => !directory, + isSymbolicLink: () => false, + }); + return { + realpath: async (file) => { + const resolved = p.resolve(file); + const linked = links[fold(resolved)]; + if (linked !== undefined) return linked; + const found = real.get(fold(resolved)); + if (found === undefined) throw new Error('ENOENT'); + return found; + }, + lstat: async (file) => { + if (!real.has(fold(file))) throw new Error('ENOENT'); + return stats(true); + }, + }; +} + +describe('the path rule on other platforms', () => { + it('compares without case and needs a drive letter on Windows', async () => { + const fs = fakeFs('win32', [ + 'C:\\Users\\Ann', + 'C:\\Users\\Ann\\Work', + 'C:\\Users\\Ann\\.ssh', + 'D:\\Work', + ]); + const roots = ['C:\\Users\\Ann']; + expect( + await isAllowedPath('c:\\users\\ann\\work', roots, 'win32', fs), + ).toEqual({ ok: true, root: 'C:\\Users\\Ann\\Work' }); + expect( + await isAllowedPath('C:/Users/Ann/Work/', roots, 'win32', fs), + ).toEqual({ ok: true, root: 'C:\\Users\\Ann\\Work' }); + for (const raw of [ + 'C:\\Users\\Ann\\.ssh', + 'D:\\Work', + '\\\\server\\share\\Work', + '\\\\?\\C:\\Users\\Ann\\Work', + '\\Users\\Ann\\Work', + 'Users\\Ann\\Work', + ]) { + expect(await isAllowedPath(raw, roots, 'win32', fs)).toEqual({ + ok: false, + }); + } + }); + + it('refuses a junction whose real path is elsewhere on Windows', async () => { + const fs = fakeFs('win32', ['C:\\Users\\Ann', 'D:\\Secret'], { + 'c:\\users\\ann\\link': 'D:\\Secret', + }); + expect( + await isAllowedPath( + 'C:\\Users\\Ann\\link', + ['C:\\Users\\Ann'], + 'win32', + fs, + ), + ).toEqual({ ok: false }); + }); + + it('compares without case on macOS and with case on Linux', async () => { + const dirs = ['/Users/ann', '/Users/ann/Work']; + expect( + await isAllowedPath( + '/users/ann/work', + ['/Users/ann'], + 'darwin', + fakeFs('darwin', dirs), + ), + ).toEqual({ ok: true, root: '/Users/ann/Work' }); + expect( + await isAllowedPath( + '/home/ann/Work', + ['/home/ann'], + 'linux', + fakeFs('linux', ['/home/ann', '/home/ann/Work']), + ), + ).toEqual({ ok: true, root: '/home/ann/Work' }); + expect( + await isAllowedPath( + '/home/ann/Work', + ['/home/Ann'], + 'linux', + fakeFs('linux', ['/home/ann', '/home/Ann', '/home/ann/Work']), + ), + ).toEqual({ ok: false }); + }); + + it('allows a hidden folder that is itself a root, and a folder below the root /', async () => { + const fs = fakeFs('linux', [ + '/', + '/home/ann', + '/home/ann/.config', + '/home/ann/.config/app', + '/srv/app', + ]); + expect( + await isAllowedPath( + '/home/ann/.config/app', + ['/home/ann', '/home/ann/.config'], + 'linux', + fs, + ), + ).toEqual({ ok: true, root: '/home/ann/.config/app' }); + expect(await isAllowedPath('/srv/app', ['/'], 'linux', fs)).toEqual({ + ok: true, + root: '/srv/app', + }); + }); +}); + +describe('the allowed roots commands', () => { + it('allow narrows from the home directory to one root, disallow of the last refuses everything', async () => { + const work = dir(home, 'work'); + const app = dir(work, 'app'); + const other = dir(home, 'other'); + const io = memoryIo(); + expect(allowCommand('work', io, commandDeps())).toBe(0); + expect(io.out).toContain(`Allowed: ${work}`); + expect(io.out).toContain('home directory'); + expect(readAllowedRoots(files().allowedRoots, host)).toEqual({ + source: 'file', + roots: [work], + }); + expect(await ask('project.inspect', other)).toEqual(refused); + expect(await ask('project.inspect', app)).toMatchObject({ + type: 'project.inspected', + }); + + expect(disallowCommand(work, memoryIo(), commandDeps())).toBe(0); + expect(readAllowedRoots(files().allowedRoots, host)).toEqual({ + source: 'file', + roots: [], + }); + expect(await ask('project.inspect', app)).toEqual(refused); + expect(await ask('project.inspect', other)).toEqual(refused); + }); + + it('writes the file with mode 600', () => { + dir(home, 'work'); + allowCommand('work', memoryIo(), commandDeps()); + if (process.platform !== 'win32') { + expect(statSync(files().allowedRoots).mode & 0o777).toBe(0o600); + } + }); + + it('lists the default marked, then the roots as JSON', () => { + const io = memoryIo(); + expect(rootsCommand({}, io, commandDeps())).toBe(0); + expect(io.out).toBe(`${home} (default: the home directory)\n`); + const work = dir(home, 'work'); + allowCommand(work, memoryIo(), commandDeps()); + const json = memoryIo(); + expect(rootsCommand({ json: true }, json, commandDeps())).toBe(0); + expect(JSON.parse(json.out)).toEqual({ + roots: [work], + default: false, + valid: true, + }); + }); + + it('refuses every path when the file is corrupt, and roots says so', async () => { + write(files().allowedRoots, '{ "roots": ['); + expect(await ask('project.inspect', dir(home, 'app'))).toEqual(refused); + const io = memoryIo(); + expect(rootsCommand({}, io, commandDeps())).toBe(1); + expect(io.err).toMatch(/is invalid/); + const json = memoryIo(); + rootsCommand({ json: true }, json, commandDeps()); + expect(JSON.parse(json.out)).toMatchObject({ roots: [], valid: false }); + }); + + it('treats a file with a relative or too many roots as invalid', () => { + write(files().allowedRoots, JSON.stringify({ roots: ['work'] })); + expect(readAllowedRoots(files().allowedRoots, host).source).toBe('invalid'); + write( + files().allowedRoots, + JSON.stringify({ + roots: Array.from({ length: ALLOWED_ROOTS_MAX + 1 }, () => home), + }), + ); + expect(readAllowedRoots(files().allowedRoots, host).source).toBe('invalid'); + }); + + it('refuses to allow a path that is not a directory, and reports a root it does not hold', () => { + const io = memoryIo(); + expect(allowCommand('missing', io, commandDeps())).not.toBe(0); + expect(io.err).toMatch(/Not a directory/); + const gone = memoryIo(); + expect(disallowCommand(outside, gone, commandDeps())).toBe(1); + expect(gone.err).toMatch(/Not an allowed root/); + }); + + it('disallows a root that no longer exists by its resolved path', () => { + const work = dir(home, 'work'); + allowCommand(work, memoryIo(), commandDeps()); + allowCommand(outside, memoryIo(), commandDeps()); + rmSync(work, { recursive: true }); + expect(disallowCommand(work, memoryIo(), commandDeps())).toBe(0); + expect(readAllowedRoots(files().allowedRoots, host).roots).toEqual([ + outside, + ]); + }); +}); + +describe('inspection', () => { + it('answers hasConfig false and no scenarios for a folder without config', async () => { + const app = dir(home, 'app'); + write(path.join(app, 'demoflow', 'a.demo.json'), FIXTURE); + expect(await ask('project.inspect', app)).toEqual({ + type: 'project.inspected', + requestId: REQUEST, + inspection: { + rootPath: app, + name: 'app', + hasConfig: false, + configValid: false, + scenarios: [], + }, + }); + }); + + it('lists the scenarios of a valid config and never a config value', async () => { + const app = dir(home, 'app'); + write(path.join(app, 'demoflow.config.json'), CONFIG); + write( + path.join(app, 'demoflow', 'b.demo.json'), + JSON.stringify({ ...JSON.parse(FIXTURE), name: 'Bee' }), + ); + write( + path.join(app, 'demoflow', 'a.demo.json'), + JSON.stringify({ ...JSON.parse(FIXTURE), name: 'Ay' }), + ); + const answer = await ask('project.inspect', app); + expect(answer).toMatchObject({ + inspection: { + hasConfig: true, + configValid: true, + scenarios: [ + { id: 'demoflow/a.demo.json', name: 'Ay' }, + { id: 'demoflow/b.demo.json', name: 'Bee' }, + ], + }, + }); + const text = JSON.stringify(answer); + expect(text).not.toContain('4123'); + expect(text).not.toContain('secret-dev-command'); + expect(text).not.toContain('baseUrl'); + }); + + it('answers configValid false and no scenarios for a config that does not load', async () => { + const app = dir(home, 'app'); + write(path.join(app, 'demoflow.config.json'), '{ "baseUrl": 7 }'); + write(path.join(app, 'demoflow', 'a.demo.json'), FIXTURE); + expect(await ask('project.inspect', app)).toMatchObject({ + inspection: { hasConfig: true, configValid: false, scenarios: [] }, + }); + }); + + it('fills githubUrl from the origin remote of the folder', async () => { + const app = dir(home, 'app'); + write( + path.join(app, '.git', 'config'), + '[core]\n\tbare = false\n[remote "origin"]\n\turl = git@github.com:acme/shop.git\n\tfetch = +refs/heads/*:refs/remotes/origin/*\n', + ); + expect(await ask('project.inspect', app)).toMatchObject({ + inspection: { githubUrl: 'https://github.com/acme/shop' }, + }); + }); +}); + +describe('the GitHub URL', () => { + it.each([ + ['https://github.com/acme/shop', 'https://github.com/acme/shop'], + ['https://github.com/acme/shop.git', 'https://github.com/acme/shop'], + ['git@github.com:acme/shop.git', 'https://github.com/acme/shop'], + ['git@github.com:a.b-c/d_e', 'https://github.com/a.b-c/d_e'], + ['ssh://git@github.com/acme/shop.git', 'https://github.com/acme/shop'], + ])('reads %s', (remote, url) => { + expect(githubUrlFrom(remote)).toBe(url); + }); + + it.each([ + 'https://gitlab.com/acme/shop', + 'https://user:token@github.com/acme/shop.git', + 'https://token@github.com/acme/shop', + 'ssh://git@github.com:22/acme/shop', + 'git@github.com:acme/shop/extra', + 'https://github.com/acme', + 'https://github.com/../shop', + 'https://github.com.evil.test/acme/shop', + 'file:///srv/shop', + ])('ignores %s', (remote) => { + expect(githubUrlFrom(remote)).toBeUndefined(); + }); + + it('reads the first url of [remote "origin"] only', () => { + const config = [ + '[remote "upstream"]', + ' url = https://github.com/other/shop', + '[Remote "origin"]', + ' URL = "https://github.com/acme/shop" ; a comment', + ' url = https://github.com/acme/second', + '[branch "main"]', + ' url = https://github.com/never/this', + ].join('\n'); + expect(originUrl(config)).toBe('https://github.com/acme/shop'); + expect(originUrl('[remote "Origin"]\nurl = x\n')).toBeUndefined(); + }); + + it('never answers credentials from the config', async () => { + const app = dir(home, 'app'); + write( + path.join(app, '.git', 'config'), + '[remote "origin"]\n\turl = https://ann:ghp_secret@github.com/acme/shop.git\n', + ); + const answer = await ask('project.inspect', app); + expect(answer).toMatchObject({ type: 'project.inspected' }); + expect(JSON.stringify(answer)).not.toContain('ghp_secret'); + expect( + (answer.inspection as Record<string, unknown>).githubUrl, + ).toBeUndefined(); + }); + + it('follows a .git file to a gitdir inside an allowed root, and a worktree to its commondir', async () => { + const main = dir(home, 'main'); + write( + path.join(main, '.git', 'config'), + '[remote "origin"]\n\turl = https://github.com/acme/shop\n', + ); + const worktreeDir = dir(main, '.git', 'worktrees', 'wt'); + write(path.join(worktreeDir, 'commondir'), '../..\n'); + const wt = dir(home, 'wt'); + write(path.join(wt, '.git'), `gitdir: ${worktreeDir}\n`); + expect(await githubUrlOf(wt, [home], process.platform, nodeLaunchFs)).toBe( + 'https://github.com/acme/shop', + ); + + const sub = dir(main, 'sub'); + const modules = dir(main, '.git', 'modules', 'sub'); + write( + path.join(modules, 'config'), + '[remote "origin"]\n\turl = git@github.com:acme/sub.git\n', + ); + write(path.join(sub, '.git'), 'gitdir: ../.git/modules/sub\n'); + expect(await githubUrlOf(sub, [home], process.platform, nodeLaunchFs)).toBe( + 'https://github.com/acme/sub', + ); + }); + + it('does not follow a gitdir outside the allowed roots', async () => { + write( + path.join(outside, 'repo', 'config'), + '[remote "origin"]\n\turl = https://github.com/acme/shop\n', + ); + const app = dir(home, 'app'); + write(path.join(app, '.git'), `gitdir: ${path.join(outside, 'repo')}\n`); + expect( + await githubUrlOf(app, [home], process.platform, nodeLaunchFs), + ).toBeUndefined(); + }); + + it('ignores a config over 64 KiB', async () => { + const app = dir(home, 'app'); + write( + path.join(app, '.git', 'config'), + `[remote "origin"]\n\turl = https://github.com/acme/shop\n${'#'.repeat(64 * 1024)}\n`, + ); + expect( + await githubUrlOf(app, [home], process.platform, nodeLaunchFs), + ).toBeUndefined(); + }); +}); + +describe('project.init', () => { + it('creates both files in an empty allowed folder, then keeps them byte for byte', async () => { + const app = dir(home, 'app'); + const first = await ask('project.init', app); + expect(first).toMatchObject({ + type: 'project.initialised', + requestId: REQUEST, + created: ['demoflow.config.json', 'demoflow/first.demo.json'], + kept: [], + inspection: { + rootPath: app, + hasConfig: true, + configValid: true, + scenarios: [{ id: 'demoflow/first.demo.json', name: 'First demo' }], + }, + }); + const config = readFileSync(path.join(app, 'demoflow.config.json')); + const scenario = readFileSync( + path.join(app, 'demoflow', 'first.demo.json'), + ); + expect(JSON.parse(config.toString())).toEqual({ + baseUrl: 'http://localhost:3000', + }); + + const second = await ask('project.init', app); + expect(second).toMatchObject({ + created: [], + kept: ['demoflow.config.json', 'demoflow/first.demo.json'], + }); + expect(readFileSync(path.join(app, 'demoflow.config.json'))).toEqual( + config, + ); + expect(readFileSync(path.join(app, 'demoflow', 'first.demo.json'))).toEqual( + scenario, + ); + }); + + it('writes nothing outside the path rule', async () => { + expect(await ask('project.init', outside)).toEqual(refused); + expect(() => + readFileSync(path.join(outside, 'demoflow.config.json')), + ).toThrow(); + }); + + it('never writes through a linked demoflow/ folder', async () => { + const app = dir(home, 'app'); + link(outside, path.join(app, 'demoflow')); + expect(await ask('project.init', app)).toEqual({ + type: 'project.error', + requestId: REQUEST, + code: 'internal', + }); + expect(() => readFileSync(path.join(outside, 'first.demo.json'))).toThrow(); + }); +}); + +describe('project.register', () => { + const ROOTS = () => ({ + allowedRootsFile: files().allowedRoots, + websiteProjectsFile: files().websiteProjects, + host, + fs: nodeLaunchFs, + }); + const checkDeps = () => ({ + indexFile: path.join(tmp, 'reported-runs.jsonl'), + websiteRegistered: (rootPath: string) => + isWebsiteRegistered(rootPath, ROOTS()), + fs: nodeLaunchFs, + loadProject: loadProjectFor(host), + }); + + it('answers config-missing for a folder without config, config-invalid for a broken one', async () => { + const app = dir(home, 'app'); + expect(await ask('project.register', app)).toEqual({ + type: 'project.error', + requestId: REQUEST, + code: 'config-missing', + }); + write(path.join(app, 'demoflow.config.json'), '{'); + expect(await ask('project.register', app)).toEqual({ + type: 'project.error', + requestId: REQUEST, + code: 'config-invalid', + }); + expect(await websiteRoots(files().websiteProjects)).toEqual(new Set()); + }); + + it('registers the canonical root once, which checkProject then accepts until its root is disallowed', async () => { + const work = dir(home, 'work'); + const app = dir(work, 'app'); + write(path.join(app, 'demoflow.config.json'), CONFIG); + expect((await checkProject(app, checkDeps())).ok).toBe(false); + + expect(await ask('project.register', app)).toEqual({ + type: 'project.registered', + requestId: REQUEST, + rootPath: app, + }); + await ask('project.register', `${app}${path.sep}`); + const lines = readFileSync(files().websiteProjects, 'utf8') + .trim() + .split('\n'); + expect(lines).toHaveLength(1); + expect(JSON.parse(lines[0] as string)).toEqual({ + rootPath: app, + registeredAt: new Date(0).toISOString(), + }); + expect(await checkProject(app, checkDeps())).toMatchObject({ + ok: true, + root: app, + }); + + allowCommand(work, memoryIo(), commandDeps()); + expect((await checkProject(app, checkDeps())).ok).toBe(true); + disallowCommand(work, memoryIo(), commandDeps()); + expect(await checkProject(app, checkDeps())).toEqual({ + ok: false, + code: 'project-unknown', + }); + }); + + it('keeps the last 1,000 roots', () => { + const file = files().websiteProjects; + for (let i = 0; i < WEBSITE_PROJECTS_MAX; i++) { + registerWebsiteProject(file, `/p/${i}`, 'at'); + } + registerWebsiteProject(file, '/p/new', 'at'); + const lines = readFileSync(file, 'utf8').trim().split('\n'); + expect(lines).toHaveLength(WEBSITE_PROJECTS_MAX); + expect(lines[0]).toContain('/p/1"'); + expect(lines.at(-1)).toContain('/p/new'); + }); +}); + +describe('one request at a time', () => { + it('answers busy while one is in flight, and internal after 5 s', async () => { + const app = dir(home, 'app'); + let release: (() => void) | undefined; + const handler = requests({ + writeTemplate: () => + new Promise((resolve) => { + release = () => resolve({ created: [], kept: [] }); + }), + }); + const reply = { + send: (message: Record<string, unknown>) => sent.push(message), + }; + handler.handle({ type: 'project.init', requestId: 'a', path: app }, reply); + await vi.waitFor(() => expect(release).toBeDefined()); + handler.handle( + { type: 'project.inspect', requestId: 'b', path: app }, + reply, + ); + expect(sent).toEqual([ + { type: 'project.error', requestId: 'b', code: 'busy' }, + ]); + await clock.advance(PROJECT_REQUEST_MAX_MS); + expect(sent).toContainEqual({ + type: 'project.error', + requestId: 'a', + code: 'internal', + }); + // Still busy until the work itself ends; then answered once only. + handler.handle( + { type: 'project.inspect', requestId: 'c', path: app }, + reply, + ); + expect(sent.at(-1)).toEqual({ + type: 'project.error', + requestId: 'c', + code: 'busy', + }); + release?.(); + // Free once the late work ends; its answer is never sent. + await vi.waitFor(async () => { + expect(await ask('project.inspect', app, handler)).toMatchObject({ + type: 'project.inspected', + }); + }); + expect(sent.filter((m) => m.requestId === 'a')).toHaveLength(1); + }); + + it('ignores a request without a request id and logs no path', async () => { + const app = dir(home, 'secret-name'); + const handler = requests(); + handler.handle( + { type: 'project.inspect', path: app }, + { send: (m) => sent.push(m) }, + ); + expect(sent).toEqual([]); + await ask('project.inspect', app, handler); + await ask('project.register', app, handler); + expect(logger.text()).not.toContain('secret-name'); + expect(logger.text()).toContain(`project.inspect ${REQUEST}: answered`); + }); +}); From a9b4a7af775e6ddbbf2f9b3a53c69f7c2148f932 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 15:06:28 +0100 Subject: [PATCH 30/71] fix(cli): check pass builds scenario paths from the given root so ids stay demoflow/... --- apps/cli/src/commands/run.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/cli/src/commands/run.ts b/apps/cli/src/commands/run.ts index c4075ccb..55c5ee40 100644 --- a/apps/cli/src/commands/run.ts +++ b/apps/cli/src/commands/run.ts @@ -412,7 +412,7 @@ async function passFiles( } return listing.scenarios .filter((scenario) => !excluded.has(scenario.id)) - .map((scenario) => path.join(real, ...scenario.id.split('/'))); + .map((scenario) => path.join(root, ...scenario.id.split('/'))); } const SCENARIOS_PREFIX = 'demoflow/'; From f21c84859f9277ed950a0f65d6c5ac917d320081 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 15:27:54 +0100 Subject: [PATCH 31/71] test(renderer): select sampled frames with between(n,a,b) ranges The frame samplers built one eq(n,...) term per frame. With the default render.endHoldMs of 2500 the video is longer, and the masked-elements check asked for ~130 consecutive frames: FFmpeg could not allocate the select filter on the CI agent. Fold each run of consecutive frames into one between term so the expression stays small at any video length. --- .../test/ffmpeg/masked-elements.spec.ts | 4 +-- packages/renderer/test/ffmpeg/render.spec.ts | 4 +-- .../test/ffmpeg/sample-frames.spec.ts | 31 ++++++++++++++++++- .../renderer/test/ffmpeg/sample-frames.ts | 22 +++++++++++++ 4 files changed, 56 insertions(+), 5 deletions(-) diff --git a/packages/renderer/test/ffmpeg/masked-elements.spec.ts b/packages/renderer/test/ffmpeg/masked-elements.spec.ts index 9ad77cd7..dfc61f5f 100644 --- a/packages/renderer/test/ffmpeg/masked-elements.spec.ts +++ b/packages/renderer/test/ffmpeg/masked-elements.spec.ts @@ -14,7 +14,7 @@ import { toOutputMs, } from '../../src/index.ts'; import { hasFfmpeg, recordFixtureRun } from '../plan/fixture-runs.ts'; -import { countFrames } from './sample-frames.ts'; +import { countFrames, selectFrames } from './sample-frames.ts'; interface Region { x0: number; @@ -41,7 +41,7 @@ async function extractCropped( crop: Crop, ): Promise<Uint8Array[]> { const raw = `${file}.crop.rgb`; - const select = numbers.map((n) => `eq(n\\,${n})`).join('+'); + const select = selectFrames(numbers); await runFfmpeg([ '-y', '-i', diff --git a/packages/renderer/test/ffmpeg/render.spec.ts b/packages/renderer/test/ffmpeg/render.spec.ts index cca7cefe..ea1b701d 100644 --- a/packages/renderer/test/ffmpeg/render.spec.ts +++ b/packages/renderer/test/ffmpeg/render.spec.ts @@ -35,7 +35,7 @@ import { checkLayout, type LayoutReport, } from '../visual/layout.ts'; -import { countFrames, sampleFrames } from './sample-frames.ts'; +import { countFrames, sampleFrames, selectFrames } from './sample-frames.ts'; if (!hasFfmpeg) { console.warn('no usable FFmpeg: skipping the FFmpeg compositor tests'); @@ -48,7 +48,7 @@ async function extractFrames( plan: RenderPlan, ): Promise<Uint8Array[]> { const raw = `${file}.${numbers[0]}.rgb`; - const select = numbers.map((n) => `eq(n\\,${n})`).join('+'); + const select = selectFrames(numbers); await runFfmpeg([ '-y', '-i', diff --git a/packages/renderer/test/ffmpeg/sample-frames.spec.ts b/packages/renderer/test/ffmpeg/sample-frames.spec.ts index 923d1f25..53e33c4f 100644 --- a/packages/renderer/test/ffmpeg/sample-frames.spec.ts +++ b/packages/renderer/test/ffmpeg/sample-frames.spec.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from 'vitest'; -import { sampleFrames } from './sample-frames.ts'; +import { sampleFrames, selectFrames } from './sample-frames.ts'; describe('sampleFrames', () => { it('does not repeat the last frame when it falls on a step (#44)', () => { @@ -35,3 +35,32 @@ describe('sampleFrames', () => { } }); }); + +describe('selectFrames', () => { + it('folds a run of consecutive frames into one between term (#365)', () => { + // CI ran out of memory on eq(n,67)+eq(n,68)+…+eq(n,197). + const run = Array.from({ length: 131 }, (_, i) => 67 + i); + expect(selectFrames(run)).toBe('between(n\\,67\\,197)'); + }); + + it('keeps a lone frame as eq and splits runs at gaps', () => { + expect(selectFrames([3, 7, 8, 9, 12, 20, 21])).toBe( + 'eq(n\\,3)+between(n\\,7\\,9)+eq(n\\,12)+between(n\\,20\\,21)', + ); + }); + + it('selects exactly the given frames', () => { + const numbers = [0, 1, 2, 5, 6, 10, 15, 16, 17, 18, 30]; + const terms = selectFrames(numbers) + .split('+') + .map((term) => term.match(/\d+/g)?.map(Number) ?? []); + const selected = Array.from({ length: 40 }, (_, n) => n).filter((n) => + terms.some(([a, b = a]) => n >= a && n <= b), + ); + expect(selected).toEqual(numbers); + }); + + it('is empty for no frames', () => { + expect(selectFrames([])).toBe(''); + }); +}); diff --git a/packages/renderer/test/ffmpeg/sample-frames.ts b/packages/renderer/test/ffmpeg/sample-frames.ts index b47715c3..cb11f92d 100644 --- a/packages/renderer/test/ffmpeg/sample-frames.ts +++ b/packages/renderer/test/ffmpeg/sample-frames.ts @@ -13,6 +13,28 @@ export function sampleFrames(from: number, to: number, step: number): number[] { return numbers; } +/** + * An FFmpeg `select` expression that passes exactly the frames `numbers` + * (ascending, distinct). Each run of consecutive frames is one + * `between(n,a,b)` term, so a long run stays one term: one `eq(n,…)` per + * frame grew past what FFmpeg can allocate once the end hold lengthened + * the video (#365). + */ +export function selectFrames(numbers: readonly number[]): string { + const terms: string[] = []; + let start = 0; + for (let i = 1; i <= numbers.length; i++) { + if (i < numbers.length && numbers[i] === numbers[i - 1] + 1) continue; + const from = numbers[start]; + const to = numbers[i - 1]; + terms.push( + from === to ? `eq(n\\,${from})` : `between(n\\,${from}\\,${to})`, + ); + start = i; + } + return terms.join('+'); +} + /** * The number of video frames in `file`, counted by decoding it: with * `-c copy` the pinned FFmpeg reports no `frame=` progress. From 66b50bbdfa689df5c6ad22eeb7573b678c235d2a Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 16:16:20 +0100 Subject: [PATCH 32/71] feat(web): shared glass site header and polished landing and docs Extract one SiteHeader for the landing page and the docs with the logo, Docs, a theme toggle and Open app / Sign in. The toggle shares a new useThemeMode hook with the app's account menu, so a choice made on the landing page carries into /app. The landing hero gets an eyebrow, an accent glow built from tokens, an Open app button next to the install command, the demo video in a glass frame, benefit cards with icons, and a footer with Docs, GitHub and npm. Docs links use accent-ink instead of accent (4.05:1 on the dark ground, below WCAG AA), the small nav labels use ink-2 instead of ink-3, and inline code wraps so it cannot widen the page at 375 px. Refs #376 --- .../src/app/docs/_components/docs-sidebar.tsx | 2 +- .../src/app/docs/_components/on-this-page.tsx | 4 +- apps/web/src/app/docs/layout.tsx | 25 +--- apps/web/src/app/page.tsx | 124 +++++++++++------- .../web/src/components/landing/demo-video.tsx | 2 +- .../web/src/components/shell/account-menu.tsx | 32 +---- apps/web/src/components/site-header.tsx | 51 +++++++ apps/web/src/components/theme-toggle.tsx | 56 ++++++++ apps/web/src/i18n/en.ts | 28 ++-- apps/web/src/lib/use-theme-mode.ts | 39 ++++++ apps/web/src/mdx-components.tsx | 12 +- 11 files changed, 258 insertions(+), 117 deletions(-) create mode 100644 apps/web/src/components/site-header.tsx create mode 100644 apps/web/src/components/theme-toggle.tsx create mode 100644 apps/web/src/lib/use-theme-mode.ts diff --git a/apps/web/src/app/docs/_components/docs-sidebar.tsx b/apps/web/src/app/docs/_components/docs-sidebar.tsx index 09720e1d..b3a04e3a 100644 --- a/apps/web/src/app/docs/_components/docs-sidebar.tsx +++ b/apps/web/src/app/docs/_components/docs-sidebar.tsx @@ -12,7 +12,7 @@ export function DocsSidebar() { aria-label={t('docs.nav.label')} className="glass rounded-surface p-3 lg:sticky lg:top-24" > - <p className="px-3 pb-2 text-xs font-semibold uppercase tracking-wide text-ink-3"> + <p className="px-3 pb-2 text-xs font-semibold uppercase tracking-wide text-ink-2"> {t('docs.nav.title')} </p> <ul className="flex flex-wrap gap-1 lg:flex-col"> diff --git a/apps/web/src/app/docs/_components/on-this-page.tsx b/apps/web/src/app/docs/_components/on-this-page.tsx index 1e08dd0a..36c77a3e 100644 --- a/apps/web/src/app/docs/_components/on-this-page.tsx +++ b/apps/web/src/app/docs/_components/on-this-page.tsx @@ -30,9 +30,9 @@ export function OnThisPage() { return ( <nav aria-label={t('docs.toc.label')} - className="text-sm lg:sticky lg:top-24" + className="glass rounded-surface p-4 text-sm lg:sticky lg:top-24" > - <p className="pb-2 text-xs font-semibold uppercase tracking-wide text-ink-3"> + <p className="pb-2 text-xs font-semibold uppercase tracking-wide text-ink-2"> {t('docs.toc.label')} </p> <ul className="flex flex-col gap-1.5 border-l border-line pl-3"> diff --git a/apps/web/src/app/docs/layout.tsx b/apps/web/src/app/docs/layout.tsx index 41c01670..6bf52d32 100644 --- a/apps/web/src/app/docs/layout.tsx +++ b/apps/web/src/app/docs/layout.tsx @@ -1,6 +1,5 @@ -import { buttonClassName } from '@andrewbehma/glass-ui/button'; import type { Metadata } from 'next'; -import Link from 'next/link'; +import { SiteHeader } from '@/components/site-header'; import { t } from '@/i18n'; import { DocsSidebar } from './_components/docs-sidebar'; import { OnThisPage } from './_components/on-this-page'; @@ -13,6 +12,8 @@ export const metadata: Metadata = { }; // No session is read here: every docs page is static (spec #179, Decision 5). +// The article column is the plain page surface; only the navigation is glass +// (spec #376, Decision 3). export default function DocsLayout({ children, }: { @@ -20,25 +21,9 @@ export default function DocsLayout({ }) { return ( <> - <header className="sticky top-0 z-10 p-3"> - <div className="glass mx-auto flex max-w-6xl items-center justify-between rounded-surface px-4 py-2"> - <Link - href="/" - aria-label={t('docs.header.home')} - className="text-lg font-semibold" - > - {t('meta.title')} - </Link> - <Link - href="/app" - className={buttonClassName({ variant: 'solid', size: 'sm' })} - > - {t('docs.header.openApp')} - </Link> - </div> - </header> + <SiteHeader width="max-w-6xl" /> <div className="mx-auto grid max-w-6xl gap-8 px-4 pb-16 pt-6 sm:px-6 lg:grid-cols-[14rem_minmax(0,1fr)] xl:grid-cols-[14rem_minmax(0,1fr)_12rem]"> - <aside> + <aside className="min-w-0"> <DocsSidebar /> </aside> <article className="min-w-0 max-w-3xl">{children}</article> diff --git a/apps/web/src/app/page.tsx b/apps/web/src/app/page.tsx index 9515e638..9deb4c26 100644 --- a/apps/web/src/app/page.tsx +++ b/apps/web/src/app/page.tsx @@ -1,25 +1,31 @@ import { buttonClassName } from '@andrewbehma/glass-ui/button'; import { Card } from '@andrewbehma/glass-ui/card'; +import { Bot, Laptop, ShieldCheck } from 'lucide-react'; import type { Metadata } from 'next'; import Link from 'next/link'; import { CopyInstall } from '@/components/landing/copy-install'; import { DemoVideo } from '@/components/landing/demo-video'; import { AccountDeletedNotice } from '@/components/settings/account-deleted-notice'; +import { SiteHeader } from '@/components/site-header'; import { t } from '@/i18n'; import { getSessionUser } from '@/lib/session'; const REPO_URL = 'https://github.com/AndreyBegma/DemoFlow'; +const NPM_URL = 'https://www.npmjs.com/package/demoflow'; const BENEFITS = [ { + icon: Bot, title: t('landing.benefits.write.title'), body: t('landing.benefits.write.body'), }, { + icon: ShieldCheck, title: t('landing.benefits.secrets.title'), body: t('landing.benefits.secrets.body'), }, { + icon: Laptop, title: t('landing.benefits.local.title'), body: t('landing.benefits.local.body'), }, @@ -51,47 +57,44 @@ export function generateMetadata(): Metadata { export default async function LandingPage() { const user = await getSessionUser(); return ( - <> - <header className="sticky top-0 z-10 p-3"> - <div className="glass mx-auto flex max-w-5xl items-center justify-between rounded-surface px-4 py-2"> - <Link - href="/" - aria-label={t('landing.nav.home')} - className="text-lg font-semibold" - > - {t('meta.title')} - </Link> - <nav - aria-label={t('landing.nav.label')} - className="flex items-center gap-2" - > - <Link - href="/docs" - className={buttonClassName({ variant: 'ghost', size: 'sm' })} - > - {t('landing.nav.docs')} - </Link> - <Link - href={user ? '/app' : '/sign-in'} - className={buttonClassName({ variant: 'solid', size: 'sm' })} - > - {user ? t('landing.nav.openApp') : t('landing.nav.signIn')} - </Link> - </nav> - </div> - </header> - <main className="mx-auto flex max-w-5xl flex-col gap-16 px-4 pb-16 pt-8 sm:px-6 sm:pt-16"> + <div className="relative isolate overflow-x-clip"> + {/* A soft accent glow behind the hero, from tokens so it works in both + themes (spec #376, Decision 4); it also gives the glass something + to blur. */} + <div + aria-hidden="true" + className="pointer-events-none absolute inset-x-0 top-0 -z-10 h-[40rem] bg-[radial-gradient(60%_50%_at_50%_0%,var(--color-accent-soft),transparent)]" + /> + <SiteHeader signedIn={Boolean(user)} /> + <main className="mx-auto flex max-w-5xl flex-col gap-20 px-4 pb-20 pt-10 sm:px-6 sm:pt-20"> <AccountDeletedNotice /> - <section className="flex flex-col gap-4 text-center"> - <h1 className="mx-auto max-w-3xl text-balance text-3xl font-semibold sm:text-5xl"> + <section className="flex flex-col items-center gap-6 text-center"> + <p className="rounded-full border border-line bg-raised px-3 py-1 text-xs font-medium text-ink-2"> + {t('landing.hero.eyebrow')} + </p> + <h1 className="max-w-3xl text-balance text-3xl font-semibold tracking-tight sm:text-5xl"> {t('landing.hero.title')} </h1> - <p className="mx-auto max-w-2xl text-pretty text-base text-ink-2 sm:text-lg"> + <p className="max-w-2xl text-pretty text-base text-ink-2 sm:text-lg"> {t('landing.hero.subtitle')} </p> + <div className="flex w-full max-w-md flex-col gap-3 text-left sm:flex-row sm:items-start"> + <Link + href="/app" + className={`${buttonClassName({ variant: 'solid' })} shrink-0 sm:h-[3.25rem]`} + > + {t('landing.hero.openApp')} + </Link> + <div className="min-w-0 flex-1"> + <CopyInstall /> + </div> + </div> </section> - <section className="flex flex-col gap-3"> - <DemoVideo /> + <section className="flex flex-col gap-4"> + {/* Glass is the frame only; the video stays a solid black surface. */} + <div className="glass rounded-surface p-2 shadow-2xl sm:p-3"> + <DemoVideo /> + </div> <p className="text-center text-sm text-ink-2"> {t('landing.video.caption')} </p> @@ -100,45 +103,66 @@ export default async function LandingPage() { aria-labelledby="benefits-title" className="flex flex-col gap-6" > - <h2 id="benefits-title" className="text-2xl font-semibold"> + <h2 + id="benefits-title" + className="text-2xl font-semibold tracking-tight" + > {t('landing.benefits.title')} </h2> <div className="grid gap-4 md:grid-cols-3"> - {BENEFITS.map((benefit) => ( + {BENEFITS.map(({ icon: Icon, title, body }) => ( <Card - key={benefit.title} + key={title} + variant="glass" pad="lg" - className="flex flex-col gap-2" + className="flex flex-col gap-3" > - <h3 className="text-lg font-semibold">{benefit.title}</h3> - <p className="text-sm text-ink-2">{benefit.body}</p> + <span className="inline-flex size-10 items-center justify-center rounded-control bg-accent-soft text-accent-ink"> + <Icon aria-hidden="true" className="size-5" /> + </span> + <h3 className="text-lg font-semibold">{title}</h3> + <p className="text-sm leading-6 text-ink-2">{body}</p> </Card> ))} </div> </section> <section aria-labelledby="install-title"> <Card pad="lg" className="mx-auto flex max-w-xl flex-col gap-4"> - <h2 id="install-title" className="text-2xl font-semibold"> + <h2 + id="install-title" + className="text-2xl font-semibold tracking-tight" + > {t('landing.install.title')} </h2> - <CopyInstall /> - <p className="text-sm text-ink-2">{t('landing.install.body')}</p> + <p className="text-ink-2">{t('landing.install.body')}</p> + <Link + href="/docs" + className={`${buttonClassName({ variant: 'ghost' })} self-start`} + > + {t('landing.install.readDocs')} + </Link> </Card> </section> </main> - <footer className="border-t border-line px-4 py-6 text-sm text-ink-2"> - <div className="mx-auto flex max-w-5xl flex-wrap items-center justify-between gap-3"> + <footer className="border-t border-line px-4 py-8 text-sm text-ink-2 sm:px-6"> + <div className="mx-auto flex max-w-5xl flex-wrap items-center justify-between gap-4"> <p>{t('landing.footer.license')}</p> - <nav className="flex gap-4"> - <Link href="/docs" className="underline"> + <nav + aria-label={t('landing.footer.label')} + className="flex flex-wrap gap-5" + > + <Link href="/docs" className="hover:text-ink"> {t('landing.footer.docs')} </Link> - <a href={REPO_URL} className="underline"> + <a href={REPO_URL} className="hover:text-ink"> {t('landing.footer.github')} </a> + <a href={NPM_URL} className="hover:text-ink"> + {t('landing.footer.npm')} + </a> </nav> </div> </footer> - </> + </div> ); } diff --git a/apps/web/src/components/landing/demo-video.tsx b/apps/web/src/components/landing/demo-video.tsx index f51c1db4..fa4cb9f4 100644 --- a/apps/web/src/components/landing/demo-video.tsx +++ b/apps/web/src/components/landing/demo-video.tsx @@ -22,7 +22,7 @@ export function DemoVideo() { return ( <video ref={ref} - className="aspect-video w-full rounded-surface border border-line bg-black" + className="block aspect-video w-full rounded-control bg-black" src="/demo/landing.mp4" poster="/demo/landing-poster.png" aria-label={t('landing.video.label')} diff --git a/apps/web/src/components/shell/account-menu.tsx b/apps/web/src/components/shell/account-menu.tsx index 4a240437..94a4ce37 100644 --- a/apps/web/src/components/shell/account-menu.tsx +++ b/apps/web/src/components/shell/account-menu.tsx @@ -12,18 +12,11 @@ import { MenuTrigger, } from '@andrewbehma/glass-ui/menu'; import { useRouter } from 'next/navigation'; -import { useEffect, useState } from 'react'; +import { useState } from 'react'; import { t } from '@/i18n'; import { signOut } from '@/lib/api'; -import { - applyTheme, - isThemeMode, - LIGHT_QUERY, - storeTheme, - THEME_MODE_ATTRIBUTE, - THEME_MODES, - type ThemeMode, -} from '@/lib/theme'; +import { THEME_MODES } from '@/lib/theme'; +import { useThemeMode } from '@/lib/use-theme-mode'; /** * The account menu in the top bar (spec #373, Decision 6): who is signed in, @@ -33,26 +26,9 @@ import { */ export function AccountMenu({ email }: { email: string }) { const router = useRouter(); - const [mode, setMode] = useState<ThemeMode>('system'); + const [mode, chooseTheme] = useThemeMode(); const [signingOut, setSigningOut] = useState(false); - // The bootstrap script has already set the mode on <html>; read it back. - useEffect(() => { - const current = document.documentElement.getAttribute(THEME_MODE_ATTRIBUTE); - if (isThemeMode(current)) setMode(current); - }, []); - - function chooseTheme(value: string) { - if (!isThemeMode(value)) return; - setMode(value); - storeTheme(value, () => window.localStorage); - applyTheme( - document.documentElement, - value, - window.matchMedia(LIGHT_QUERY).matches, - ); - } - async function leave() { setSigningOut(true); await signOut(); diff --git a/apps/web/src/components/site-header.tsx b/apps/web/src/components/site-header.tsx new file mode 100644 index 00000000..2a04dfd3 --- /dev/null +++ b/apps/web/src/components/site-header.tsx @@ -0,0 +1,51 @@ +import { buttonClassName } from '@andrewbehma/glass-ui/button'; +import Link from 'next/link'; +import { Logo } from '@/components/brand/logo'; +import { ThemeToggle } from '@/components/theme-toggle'; +import { t } from '@/i18n'; + +/** + * The floating glass header of the public site, shared by the landing page + * and the docs (spec #376, Decision 1). `signedIn` picks "Open app" or + * "Sign in"; a static page that reads no session leaves it out and gets + * "Open app", which sends a signed-out visitor to sign in anyway. + */ +export function SiteHeader({ + signedIn, + width = 'max-w-5xl', +}: { + signedIn?: boolean; + width?: 'max-w-5xl' | 'max-w-6xl'; +}) { + const showSignIn = signedIn === false; + return ( + <header className="sticky top-0 z-chrome p-3"> + <div + className={`glass mx-auto flex ${width} items-center justify-between gap-2 rounded-surface py-2 pl-4 pr-2`} + > + <Link + href="/" + aria-label={t('site.home')} + className="rounded-control focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent" + > + <Logo /> + </Link> + <nav aria-label={t('site.nav')} className="flex items-center gap-1"> + <Link + href="/docs" + className={buttonClassName({ variant: 'ghost', size: 'sm' })} + > + {t('site.docs')} + </Link> + <ThemeToggle /> + <Link + href={showSignIn ? '/sign-in' : '/app'} + className={buttonClassName({ variant: 'solid', size: 'sm' })} + > + {showSignIn ? t('site.signIn') : t('site.openApp')} + </Link> + </nav> + </div> + </header> + ); +} diff --git a/apps/web/src/components/theme-toggle.tsx b/apps/web/src/components/theme-toggle.tsx new file mode 100644 index 00000000..7672d8e0 --- /dev/null +++ b/apps/web/src/components/theme-toggle.tsx @@ -0,0 +1,56 @@ +'use client'; + +import { + MenuContent, + MenuLabel, + MenuRadioGroup, + MenuRadioItem, + MenuRoot, + MenuTrigger, +} from '@andrewbehma/glass-ui/menu'; +import { Monitor, Moon, Sun } from 'lucide-react'; +import { t } from '@/i18n'; +import { THEME_MODES, type ThemeMode } from '@/lib/theme'; +import { useThemeMode } from '@/lib/use-theme-mode'; + +const ICONS: Record<ThemeMode, typeof Sun> = { + system: Monitor, + dark: Moon, + light: Sun, +}; + +/** + * The theme control of the site header (spec #376, Decision 1): the same + * modes and storage as the app's account menu, so a choice made on the + * landing page carries into `/app`. A radio menu for the same reason the + * account menu uses one: it is reachable by Tab and the arrow keys. + */ +export function ThemeToggle() { + const [mode, chooseTheme] = useThemeMode(); + const Icon = ICONS[mode]; + return ( + <MenuRoot> + <MenuTrigger + aria-label={t('site.theme.label')} + className="inline-flex size-9 shrink-0 items-center justify-center rounded-control text-ink-2 hover:bg-hover hover:text-ink focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent" + > + <Icon aria-hidden="true" className="size-4" /> + </MenuTrigger> + <MenuContent align="end"> + <MenuLabel>{t('app.shell.account.theme')}</MenuLabel> + <MenuRadioGroup value={mode} onValueChange={chooseTheme}> + {THEME_MODES.map((value) => ( + <MenuRadioItem + key={value} + value={value} + // Keep the menu open so the change can be seen and undone. + onSelect={(event) => event.preventDefault()} + > + {t(`app.shell.theme.${value}`)} + </MenuRadioItem> + ))} + </MenuRadioGroup> + </MenuContent> + </MenuRoot> + ); +} diff --git a/apps/web/src/i18n/en.ts b/apps/web/src/i18n/en.ts index 27b8858f..3c7dc228 100644 --- a/apps/web/src/i18n/en.ts +++ b/apps/web/src/i18n/en.ts @@ -533,17 +533,12 @@ export const en = { 'DemoFlow drives your running app in a real browser, checks every step and renders a polished demo video. Everything runs on your machine.', imageAlt: 'A DemoFlow demo video of a sample app', }, - nav: { - label: 'Main', - home: 'DemoFlow home', - docs: 'Docs', - signIn: 'Sign in', - openApp: 'Open app', - }, hero: { + eyebrow: 'Open source · runs on your machine', title: 'Demo videos of the features you ship, from one JSON scenario.', subtitle: 'DemoFlow drives your running app in a real browser, checks every step, and renders a polished video (MP4, GIF or WebM) with a drawn cursor, zoom on the action and captions.', + openApp: 'Open app', }, video: { label: 'A demo video of a sample app, recorded with DemoFlow', @@ -567,25 +562,34 @@ export const en = { install: { title: 'Run it in your project', command: 'npx demoflow', - body: 'Then run demoflow record to capture a scenario by clicking through your app.', + body: 'Run npx demoflow in your project, then demoflow record to capture a scenario by clicking through your app.', + readDocs: 'Read the getting started guide', copy: 'Copy command', copied: 'Copied', copyFailed: 'Could not copy. Select the command and copy it.', }, footer: { + label: 'Links', license: 'DemoFlow · MIT licence', github: 'GitHub', docs: 'Docs', + npm: 'npm', + }, + }, + site: { + home: 'DemoFlow home', + nav: 'Main', + docs: 'Docs', + signIn: 'Sign in', + openApp: 'Open app', + theme: { + label: 'Theme', }, }, docs: { meta: { title: 'Documentation', }, - header: { - home: 'DemoFlow home', - openApp: 'Open app', - }, nav: { label: 'Documentation', title: 'Docs', diff --git a/apps/web/src/lib/use-theme-mode.ts b/apps/web/src/lib/use-theme-mode.ts new file mode 100644 index 00000000..02d41cde --- /dev/null +++ b/apps/web/src/lib/use-theme-mode.ts @@ -0,0 +1,39 @@ +'use client'; + +import { useEffect, useState } from 'react'; +import { + applyTheme, + isThemeMode, + LIGHT_QUERY, + storeTheme, + THEME_MODE_ATTRIBUTE, + type ThemeMode, +} from './theme'; + +/** + * The theme mode and a setter that stores and applies it. Every theme control + * — the account menu in the app, the toggle in the site header — uses this, so + * a choice made on one page is the one every other page reads. + */ +export function useThemeMode(): [ThemeMode, (value: string) => void] { + const [mode, setMode] = useState<ThemeMode>('system'); + + // The bootstrap script has already set the mode on <html>; read it back. + useEffect(() => { + const current = document.documentElement.getAttribute(THEME_MODE_ATTRIBUTE); + if (isThemeMode(current)) setMode(current); + }, []); + + function chooseTheme(value: string) { + if (!isThemeMode(value)) return; + setMode(value); + storeTheme(value, () => window.localStorage); + applyTheme( + document.documentElement, + value, + window.matchMedia(LIGHT_QUERY).matches, + ); + } + + return [mode, chooseTheme]; +} diff --git a/apps/web/src/mdx-components.tsx b/apps/web/src/mdx-components.tsx index a961677b..0c7344d2 100644 --- a/apps/web/src/mdx-components.tsx +++ b/apps/web/src/mdx-components.tsx @@ -12,6 +12,8 @@ export function headingId(children: ReactNode): string | undefined { } // Content surfaces stay plain and readable (vision §9): tokens only, no glass. +// Links use `accent-ink`, not `accent`: the accent is 4.05:1 on the dark +// ground and fails WCAG AA for body text (spec #376, Decision 3). const components: MDXComponents = { h1: (props) => ( <h1 className="text-3xl font-semibold text-balance" {...props} /> @@ -45,18 +47,22 @@ const components: MDXComponents = { strong: (props) => <strong className="font-semibold text-ink" {...props} />, a: ({ href = '', ...props }: ComponentPropsWithoutRef<'a'>) => href.startsWith('/') ? ( - <Link href={href} className="text-accent underline" {...props} /> + <Link + href={href} + className="text-accent-ink underline underline-offset-2 hover:decoration-2" + {...props} + /> ) : ( <a href={href} - className="text-accent underline" + className="text-accent-ink underline underline-offset-2 hover:decoration-2" rel="noopener noreferrer" {...props} /> ), code: (props) => ( <code - className="rounded-sm border border-line bg-raised px-1.5 py-0.5 font-mono text-[0.9em] text-ink" + className="rounded-sm border border-line bg-raised px-1.5 py-0.5 font-mono text-[0.9em] text-ink [overflow-wrap:anywhere]" {...props} /> ), From eddccf705448803e64a6e49cbac7790075fe36e9 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 16:19:11 +0100 Subject: [PATCH 33/71] fix(web): keep table code on one line and align the hero button Inline code may wrap anywhere so a long name cannot widen the page at 375 px, but inside a docs table that split keys mid-word. Table cells keep their code on one line; the table already scrolls by itself. The hero Open app button now matches the install box height on desktop. Refs #376 --- apps/web/next-env.d.ts | 2 +- apps/web/src/app/page.tsx | 2 +- apps/web/src/mdx-components.tsx | 5 ++++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/apps/web/next-env.d.ts b/apps/web/next-env.d.ts index 9edff1c7..c4b7818f 100644 --- a/apps/web/next-env.d.ts +++ b/apps/web/next-env.d.ts @@ -1,6 +1,6 @@ /// <reference types="next" /> /// <reference types="next/image-types/global" /> -import "./.next/types/routes.d.ts"; +import "./.next/dev/types/routes.d.ts"; // NOTE: This file should not be edited // see https://nextjs.org/docs/app/api-reference/config/typescript for more information. diff --git a/apps/web/src/app/page.tsx b/apps/web/src/app/page.tsx index 9deb4c26..dfc7cf26 100644 --- a/apps/web/src/app/page.tsx +++ b/apps/web/src/app/page.tsx @@ -81,7 +81,7 @@ export default async function LandingPage() { <div className="flex w-full max-w-md flex-col gap-3 text-left sm:flex-row sm:items-start"> <Link href="/app" - className={`${buttonClassName({ variant: 'solid' })} shrink-0 sm:h-[3.25rem]`} + className={`${buttonClassName({ variant: 'solid' })} shrink-0 sm:h-[3.625rem]`} > {t('landing.hero.openApp')} </Link> diff --git a/apps/web/src/mdx-components.tsx b/apps/web/src/mdx-components.tsx index 0c7344d2..42b712fe 100644 --- a/apps/web/src/mdx-components.tsx +++ b/apps/web/src/mdx-components.tsx @@ -93,7 +93,10 @@ const components: MDXComponents = { /> ), td: (props) => ( - <td className="border-b border-line px-3 py-2 align-top" {...props} /> + <td + className="border-b border-line px-3 py-2 align-top [&>code]:whitespace-nowrap" + {...props} + /> ), }; From c637fa25b3800bcaae6c4ddcfcff399409b44cf7 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 16:19:26 +0100 Subject: [PATCH 34/71] chore(web): restore next-env.d.ts the dev server rewrote --- apps/web/next-env.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/web/next-env.d.ts b/apps/web/next-env.d.ts index c4b7818f..9edff1c7 100644 --- a/apps/web/next-env.d.ts +++ b/apps/web/next-env.d.ts @@ -1,6 +1,6 @@ /// <reference types="next" /> /// <reference types="next/image-types/global" /> -import "./.next/dev/types/routes.d.ts"; +import "./.next/types/routes.d.ts"; // NOTE: This file should not be edited // see https://nextjs.org/docs/app/api-reference/config/typescript for more information. From 6df62ea4263dcfc544bcacec5fd9c529b79b9b15 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 16:20:07 +0100 Subject: [PATCH 35/71] feat(web): Glass UI for auth, device approval and account settings The auth pages sit in a branded glass frame on the theme canvas, with the GitHub mark on Continue with GitHub. Device approval is one decision: the code in large monospace, the machine context, Approve and Deny, and a success state that says the tab can be closed. Account settings is a page header with Profile, Sign-in methods and Danger zone sections. No auth logic changes (spec #375). --- apps/web/src/app/app/device/page.tsx | 52 +++--- apps/web/src/app/app/settings/page.tsx | 161 +++++++++++++----- apps/web/src/components/auth/auth-card.tsx | 20 ++- apps/web/src/components/auth/github-mark.tsx | 19 +++ .../src/components/device/device-approval.tsx | 99 +++++++---- .../components/device/device-code-form.tsx | 5 +- .../components/settings/delete-account.tsx | 3 +- apps/web/src/i18n/en.ts | 26 +++ 8 files changed, 280 insertions(+), 105 deletions(-) create mode 100644 apps/web/src/components/auth/github-mark.tsx diff --git a/apps/web/src/app/app/device/page.tsx b/apps/web/src/app/app/device/page.tsx index a66cc9ac..6bbf6018 100644 --- a/apps/web/src/app/app/device/page.tsx +++ b/apps/web/src/app/app/device/page.tsx @@ -1,5 +1,6 @@ import { Banner } from '@andrewbehma/glass-ui/banner'; import { Card } from '@andrewbehma/glass-ui/card'; +import { PageHeader } from '@andrewbehma/glass-ui/page-header'; import { redirect } from 'next/navigation'; import { DeviceApproval } from '@/components/device/device-approval'; import { DeviceCodeForm } from '@/components/device/device-code-form'; @@ -9,7 +10,8 @@ import { normalizeUserCode } from '@/lib/user-code'; // Approve or deny a machine that ran `demoflow login` (spec #135, Decision 6). // `?code=ABCD-1234` comes from the link the CLI opens; without it the person -// types the code shown in their terminal. +// types the code shown in their terminal. One decision on one screen (spec +// #375, Decision 3). export default async function DevicePage({ searchParams, }: { @@ -22,39 +24,43 @@ export default async function DevicePage({ const request = code ? await getDevice(code) : undefined; return ( - // The shell's banner asks for verification; this card says why it matters. - <Card pad="lg" className="w-full max-w-2xl"> + // A single decision reads best narrower than the shell's column. + <div className="flex w-full max-w-2xl flex-col gap-6"> {request && typeof request === 'object' ? ( <> - <h1 className="text-2xl font-semibold"> - {t('device.approve.title')} - </h1> - {user.emailVerified ? null : ( - <p className="mt-2 text-sm text-ink-2">{t('device.verifyFirst')}</p> - )} - <div className="mt-4"> + {/* The shell's banner asks for verification; this says why it matters. */} + <PageHeader + title={t('device.approve.title')} + description={ + user.emailVerified + ? t('device.description') + : t('device.verifyFirst') + } + /> + <Card pad="lg"> <DeviceApproval request={request} canApprove={user.emailVerified} /> - </div> + </Card> </> ) : ( <> - <h1 className="text-2xl font-semibold"> - {request === 'not_found' - ? t('device.notFound.title') - : t('device.code.title')} - </h1> - <div className="mt-4 flex flex-col gap-4"> + <PageHeader + title={ + request === 'not_found' + ? t('device.notFound.title') + : t('device.code.title') + } + description={t('device.code.body')} + /> + <Card pad="lg" className="flex flex-col gap-4"> {request === 'not_found' ? ( - <p className="text-sm text-ink-2">{t('device.notFound.body')}</p> + <Banner tone="danger">{t('device.notFound.body')}</Banner> ) : request === 'error' ? ( <Banner tone="danger">{t('device.unavailable')}</Banner> - ) : ( - <p className="text-sm text-ink-2">{t('device.code.body')}</p> - )} + ) : null} <DeviceCodeForm /> - </div> + </Card> </> )} - </Card> + </div> ); } diff --git a/apps/web/src/app/app/settings/page.tsx b/apps/web/src/app/app/settings/page.tsx index d2a857f6..d6717f20 100644 --- a/apps/web/src/app/app/settings/page.tsx +++ b/apps/web/src/app/app/settings/page.tsx @@ -1,7 +1,13 @@ import { Banner } from '@andrewbehma/glass-ui/banner'; import { buttonClassName } from '@andrewbehma/glass-ui/button'; import { Card } from '@andrewbehma/glass-ui/card'; +import { PageHeader } from '@andrewbehma/glass-ui/page-header'; +import { SectionHeader } from '@andrewbehma/glass-ui/section-header'; +import { Separator } from '@andrewbehma/glass-ui/separator'; +import { StatusPill } from '@andrewbehma/glass-ui/status-pill'; +import { Palette } from 'lucide-react'; import { redirect } from 'next/navigation'; +import type { ReactNode } from 'react'; import { UnlinkGithubButton } from '@/components/auth/unlink-github-button'; import { DeleteAccount } from '@/components/settings/delete-account'; import { t } from '@/i18n'; @@ -9,9 +15,50 @@ import { githubStartUrl } from '@/lib/api'; import { githubErrorMessage } from '@/lib/github-errors'; import { getProviders, getSessionUser } from '@/lib/session'; -// Account settings: linking and unlinking GitHub (spec #126, Decision 1), and -// deleting the account (spec #177). A failed link comes back here with -// `?error=<code>`. +/** One titled section of the page (spec #375, Decision 5). */ +function SettingsSection({ + id, + title, + description, + children, +}: { + id: string; + title: string; + description: string; + children: ReactNode; +}) { + return ( + <section aria-labelledby={id} className="flex flex-col gap-3"> + <SectionHeader headingId={id} title={title} description={description} /> + {children} + </section> + ); +} + +/** A labelled fact with its state under it and, optionally, its action. */ +function SettingRow({ + label, + children, + action, +}: { + label: string; + children: ReactNode; + action?: ReactNode; +}) { + return ( + <div className="flex flex-col gap-3 tablet:flex-row tablet:items-start tablet:justify-between tablet:gap-6"> + <div className="flex min-w-0 flex-col gap-1"> + <h3 className="text-sm font-medium text-ink-2">{label}</h3> + <div className="min-w-0 break-words">{children}</div> + </div> + {action ? <div className="shrink-0 tablet:max-w-64">{action}</div> : null} + </div> + ); +} + +// Account settings: the profile, linking and unlinking GitHub (spec #126, +// Decision 1), and deleting the account (spec #177). A failed link comes back +// here with `?error=<code>`. export default async function SettingsPage({ searchParams, }: { @@ -24,46 +71,80 @@ export default async function SettingsPage({ return ( // Forms read best narrower than the shell's column. - <div className="flex w-full max-w-2xl flex-col gap-6"> + <div className="flex w-full max-w-2xl flex-col gap-8"> + <PageHeader + title={t('app.settings.title')} + description={t('app.settings.description')} + /> {error ? <Banner tone="danger">{error}</Banner> : null} - <Card pad="lg"> - <h1 className="text-2xl font-semibold">{t('app.settings.title')}</h1> - <dl className="mt-6 flex flex-col gap-6"> - <div className="flex flex-col gap-1"> - <dt className="text-sm text-ink-2">{t('app.settings.email')}</dt> - <dd className="min-w-0 break-words">{user.email}</dd> - </div> - <div className="flex flex-col gap-3"> - <dt className="text-sm text-ink-2"> - {t('app.settings.github.title')} - </dt> - <dd className="flex flex-col gap-3"> - <p> - {user.githubLinked - ? t('app.settings.github.linked') - : t('app.settings.github.notLinked')} - </p> - {user.githubLinked ? ( + + <SettingsSection + id="settings-profile" + title={t('app.settings.profile.title')} + description={t('app.settings.profile.description')} + > + <Card pad="lg" className="flex flex-col gap-5"> + <SettingRow label={t('app.settings.email')}>{user.email}</SettingRow> + <SettingRow label={t('app.settings.profile.verification')}> + <StatusPill + status={user.emailVerified ? 'done' : 'waiting'} + label={ + user.emailVerified + ? t('app.settings.profile.verified') + : t('app.settings.profile.unverified') + } + /> + </SettingRow> + </Card> + <p className="flex items-center gap-2 text-sm text-ink-2"> + <Palette size={16} aria-hidden="true" className="shrink-0" /> + {t('app.settings.theme')} + </p> + </SettingsSection> + + <SettingsSection + id="settings-methods" + title={t('app.settings.methods.title')} + description={t('app.settings.methods.description')} + > + <Card pad="lg" className="flex flex-col gap-5"> + <SettingRow label={t('app.settings.password.title')}> + {user.hasPassword + ? t('app.settings.password.set') + : t('app.settings.password.notSet')} + </SettingRow> + <Separator /> + <SettingRow + label={t('app.settings.github.title')} + action={ + user.githubLinked ? ( <UnlinkGithubButton hasPassword={user.hasPassword} /> ) : github ? ( - <div> - <a - href={githubStartUrl('link')} - className={buttonClassName({ variant: 'solid' })} - > - {t('app.settings.github.link')} - </a> - </div> - ) : ( - <p className="text-sm text-ink-2"> - {t('app.settings.github.unavailable')} - </p> - )} - </dd> - </div> - </dl> - </Card> - <DeleteAccount email={user.email} /> + <a + href={githubStartUrl('link')} + className={buttonClassName({ variant: 'solid' })} + > + {t('app.settings.github.link')} + </a> + ) : undefined + } + > + {user.githubLinked + ? t('app.settings.github.linked') + : github + ? t('app.settings.github.notLinked') + : t('app.settings.github.unavailable')} + </SettingRow> + </Card> + </SettingsSection> + + <SettingsSection + id="settings-danger" + title={t('app.settings.danger.title')} + description={t('app.settings.danger.description')} + > + <DeleteAccount email={user.email} /> + </SettingsSection> </div> ); } diff --git a/apps/web/src/components/auth/auth-card.tsx b/apps/web/src/components/auth/auth-card.tsx index 6ac455ce..40e68647 100644 --- a/apps/web/src/components/auth/auth-card.tsx +++ b/apps/web/src/components/auth/auth-card.tsx @@ -1,11 +1,18 @@ import { buttonClassName } from '@andrewbehma/glass-ui/button'; import { Card } from '@andrewbehma/glass-ui/card'; +import Link from 'next/link'; import type { ReactNode } from 'react'; +import { Logo } from '@/components/brand/logo'; import { t } from '@/i18n'; import { githubStartUrl } from '@/lib/api'; import { getProviders } from '@/lib/session'; +import { GithubMark } from './github-mark'; -/** The one readable card every auth page sits in, centred like the home page. */ +/** + * The frame every auth page sits in (spec #375, Decision 1): the logo above a + * glass card, on the theme's soft canvas gradient. Glass is the frame; the + * fields inside keep their solid surface. + */ export function AuthCard({ title, children, @@ -16,10 +23,14 @@ export function AuthCard({ footer?: ReactNode; }) { return ( - <main className="flex min-h-screen items-center justify-center p-6"> - <Card pad="lg" className="w-full max-w-md"> + <main className="flex min-h-screen flex-col items-center justify-center gap-6 px-4 py-10"> + <div className="canvas" aria-hidden="true" /> + <Link href="/" className="rounded-control px-2 py-1"> + <Logo size={28} /> + </Link> + <Card variant="glass" pad="lg" className="w-full max-w-md"> <h1 className="text-2xl font-semibold">{title}</h1> - <div className="mt-4 flex flex-col gap-4">{children}</div> + <div className="mt-6 flex flex-col gap-4">{children}</div> {footer ? ( <div className="mt-6 flex flex-col gap-1 text-sm text-ink-2"> {footer} @@ -48,6 +59,7 @@ export async function ProviderSlot() { href={githubStartUrl('sign-in')} className={buttonClassName({ variant: 'glass', full: true })} > + <GithubMark /> {t('auth.github.continue')} </a> </> diff --git a/apps/web/src/components/auth/github-mark.tsx b/apps/web/src/components/auth/github-mark.tsx new file mode 100644 index 00000000..a2897cf4 --- /dev/null +++ b/apps/web/src/components/auth/github-mark.tsx @@ -0,0 +1,19 @@ +/** + * The GitHub mark, for "Continue with GitHub". lucide-react dropped its brand + * icons in 1.0, so the mark is drawn here; `currentColor` keeps it on the + * button's ink in both themes. + */ +export function GithubMark({ size = 16 }: { size?: number }) { + return ( + <svg + width={size} + height={size} + viewBox="0 0 16 16" + aria-hidden="true" + fill="currentColor" + className="shrink-0" + > + <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" /> + </svg> + ); +} diff --git a/apps/web/src/components/device/device-approval.tsx b/apps/web/src/components/device/device-approval.tsx index c0a9db88..956134ff 100644 --- a/apps/web/src/components/device/device-approval.tsx +++ b/apps/web/src/components/device/device-approval.tsx @@ -3,6 +3,8 @@ import { Banner } from '@andrewbehma/glass-ui/banner'; import { Button, buttonClassName } from '@andrewbehma/glass-ui/button'; import { Field, Input } from '@andrewbehma/glass-ui/field'; +import { KeyValueList } from '@andrewbehma/glass-ui/key-value-list'; +import { CircleCheck, CircleX } from 'lucide-react'; import Link from 'next/link'; import { useId, useState } from 'react'; import { t } from '@/i18n'; @@ -52,29 +54,35 @@ export function DeviceApproval({ const [failure, setFailure] = useState<Failure | undefined>(); const [outcome, setOutcome] = useState<Outcome | null>(null); + // The answer replaces the question (spec #375, Decision 3): nothing is left + // to approve, so no form comes back. if (outcome) { + const approved = outcome === 'approved'; + const Icon = approved ? CircleCheck : CircleX; return ( - <div className="flex flex-col gap-4"> - <Banner tone={outcome === 'approved' ? 'ok' : 'info'}> - <p className="font-medium"> - {outcome === 'approved' - ? t('device.done.approvedTitle') - : t('device.done.deniedTitle')} - </p> - <p> - {outcome === 'approved' - ? t('device.done.approvedBody') - : t('device.done.deniedBody')} - </p> - </Banner> - <div> - <Link - href="/app/machines" - className={buttonClassName({ variant: 'glass' })} - > - {t('device.done.machines')} - </Link> - </div> + <div + role="status" + className="flex flex-col items-center gap-3 py-4 text-center" + > + <Icon + size={40} + aria-hidden="true" + className={approved ? 'text-ok' : 'text-ink-3'} + /> + <h2 className="text-xl font-semibold"> + {approved + ? t('device.done.approvedTitle') + : t('device.done.deniedTitle')} + </h2> + <p className="text-ink-2"> + {approved ? t('device.done.closeTab') : t('device.done.deniedBody')} + </p> + <Link + href="/app/machines" + className={`mt-2 ${buttonClassName({ variant: 'glass' })}`} + > + {t('device.done.machines')} + </Link> </div> ); } @@ -110,22 +118,35 @@ export function DeviceApproval({ } return ( - <div className="flex flex-col gap-4"> + <div className="flex flex-col gap-5"> {failure ? <Banner tone="danger">{t(failure)}</Banner> : null} - <dl className="grid grid-cols-[auto_1fr] gap-x-4 gap-y-2 text-sm"> - <dt className="text-ink-2">{t('device.approve.code')}</dt> - <dd className="font-mono text-lg font-semibold tracking-widest"> + <dl className="flex flex-col items-center gap-1 text-center"> + <dt className="text-sm text-ink-2">{t('device.approve.code')}</dt> + <dd className="break-all font-mono text-3xl font-semibold tracking-widest tablet:text-4xl"> {request.userCode} </dd> - <dt className="text-ink-2">{t('device.approve.hostname')}</dt> - <dd className="min-w-0 break-words">{request.hostname}</dd> - <dt className="text-ink-2">{t('device.approve.os')}</dt> - <dd className="min-w-0 break-words">{request.os}</dd> - <dt className="text-ink-2">{t('device.approve.cliVersion')}</dt> - <dd className="min-w-0 break-words">{request.cliVersion}</dd> - <dt className="text-ink-2">{t('device.approve.requested')}</dt> - <dd>{formatDate(request.createdAt)}</dd> </dl> + <KeyValueList + columns={2} + items={[ + { + key: 'hostname', + label: t('device.approve.hostname'), + value: request.hostname, + }, + { key: 'os', label: t('device.approve.os'), value: request.os }, + { + key: 'cliVersion', + label: t('device.approve.cliVersion'), + value: request.cliVersion, + }, + { + key: 'requested', + label: t('device.approve.requested'), + value: formatDate(request.createdAt), + }, + ]} + /> {canApprove ? ( <> <Banner tone="warn">{t('device.approve.warning')}</Banner> @@ -144,15 +165,21 @@ export function DeviceApproval({ required /> </Field> - <div className="flex gap-3"> - <Button type="button" disabled={pending !== null} onClick={approve}> + <div className="flex flex-col gap-3 tablet:flex-row"> + <Button + type="button" + size="lg" + disabled={pending !== null} + onClick={approve} + > {pending === 'approve' ? t('device.approve.submitting') : t('device.approve.submit')} </Button> <Button type="button" - variant="danger" + size="lg" + variant="glass" disabled={pending !== null} onClick={deny} > diff --git a/apps/web/src/components/device/device-code-form.tsx b/apps/web/src/components/device/device-code-form.tsx index 0fd4b9de..94c690fa 100644 --- a/apps/web/src/components/device/device-code-form.tsx +++ b/apps/web/src/components/device/device-code-form.tsx @@ -40,12 +40,15 @@ export function DeviceCodeForm() { autoComplete="off" autoCapitalize="characters" spellCheck={false} + className="font-mono text-lg tracking-widest" placeholder={t('device.code.placeholder')} aria-invalid={invalid ? true : undefined} required /> </Field> - <Button type="submit">{t('device.code.submit')}</Button> + <Button type="submit" size="lg"> + {t('device.code.submit')} + </Button> </form> ); } diff --git a/apps/web/src/components/settings/delete-account.tsx b/apps/web/src/components/settings/delete-account.tsx index 6c311b02..9c8758bc 100644 --- a/apps/web/src/components/settings/delete-account.tsx +++ b/apps/web/src/components/settings/delete-account.tsx @@ -65,7 +65,8 @@ export function DeleteAccount({ email }: { email: string }) { return ( <Card pad="lg"> - <h2 className="text-lg font-semibold">{t('accountDeletion.title')}</h2> + {/* Under the page's "Danger zone" section heading. */} + <h3 className="font-semibold">{t('accountDeletion.title')}</h3> <p className="mt-2 text-sm text-ink-2">{t('accountDeletion.body')}</p> <div className="mt-4"> <Button type="button" variant="danger" onClick={() => setOpen(true)}> diff --git a/apps/web/src/i18n/en.ts b/apps/web/src/i18n/en.ts index 27b8858f..11f8916c 100644 --- a/apps/web/src/i18n/en.ts +++ b/apps/web/src/i18n/en.ts @@ -62,6 +62,29 @@ export const en = { needsPassword: 'You sign in only with GitHub. To unlink it, first set a password with “Forgot your password?” on the sign-in page.', }, + description: 'Your profile, how you sign in, and your account.', + profile: { + title: 'Profile', + description: 'The email you sign in with and get notices at.', + verification: 'Email verification', + verified: 'Verified', + unverified: 'Not verified', + }, + methods: { + title: 'Sign-in methods', + description: 'The ways you can sign in to DemoFlow.', + }, + password: { + title: 'Password', + set: 'Set. You can sign in with your email and password.', + notSet: + 'Not set. To add one, use “Forgot your password?” on the sign-in page.', + }, + danger: { + title: 'Danger zone', + description: 'Actions here cannot be undone.', + }, + theme: 'Light, dark or system theme: choose it in the account menu.', }, }, device: { @@ -109,7 +132,10 @@ export const en = { deniedTitle: 'Request denied', deniedBody: 'The machine was not paired.', machines: 'Go to machines', + closeTab: 'You can close this tab, demoflow is signed in.', }, + description: + 'A terminal ran demoflow login and is waiting for your answer.', }, dashboard: { title: 'Overview', From 13e9e317063236085d8e5ce97169eb8b91363801 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 16:28:34 +0100 Subject: [PATCH 36/71] fix(web): allow 127.0.0.1 as a dev origin so recorded pages hydrate Next.js 16 blocks dev scripts and the HMR socket for any host but localhost. DemoFlow records the site at 127.0.0.1 (demoflow.config.json), so the page never hydrated and client controls such as the theme menu did not respond in recordings. --- apps/web/next.config.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/apps/web/next.config.ts b/apps/web/next.config.ts index c655fdc5..30011257 100644 --- a/apps/web/next.config.ts +++ b/apps/web/next.config.ts @@ -11,6 +11,10 @@ const nextConfig: NextConfig = { transpilePackages: ['@demoflow/shared'], // The docs pages are `page.mdx` (spec #179). pageExtensions: ['ts', 'tsx', 'md', 'mdx'], + // DemoFlow records this site at 127.0.0.1 (demoflow.config.json). The dev + // server blocks its scripts and HMR socket for any host but localhost, so + // without this the page never hydrates and no client control responds. + allowedDevOrigins: ['127.0.0.1'], // `/api` is reserved for the API. Stripping the prefix matches Caddy, so // the browser sees one origin locally and on staging alike. async rewrites() { From fa7850cbaed569caf2291f67ff1987f1a587977d Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 16:28:34 +0100 Subject: [PATCH 37/71] docs(demo): add the Glass UI landing and docs demo scenario Walks the landing page, switches the theme from the shared site header, follows it into the docs and shows code and tables on plain surfaces. --- ...-glass-ui-polish-for-the-landing.demo.json | 82 +++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 demoflow/cards/C-198-feat-web-glass-ui-polish-for-the-landing.demo.json diff --git a/demoflow/cards/C-198-feat-web-glass-ui-polish-for-the-landing.demo.json b/demoflow/cards/C-198-feat-web-glass-ui-polish-for-the-landing.demo.json new file mode 100644 index 00000000..0ffef452 --- /dev/null +++ b/demoflow/cards/C-198-feat-web-glass-ui-polish-for-the-landing.demo.json @@ -0,0 +1,82 @@ +{ + "schemaVersion": 1, + "name": "Glass UI landing and docs", + "description": "Walk the polished landing page — the hero, the demo video in its glass frame and the benefit cards — switch to the dark theme from the shared site header, then follow the theme into the docs, where the article, code and tables stay on plain readable surfaces.", + "viewport": { "width": 1280, "height": 720 }, + "setup": [{ "action": "navigate", "path": "/" }], + "steps": [ + { + "action": "assertVisible", + "target": { + "role": "heading", + "name": "Demo videos of the features you ship, from one JSON scenario.", + "exact": true + }, + "caption": "One header for the landing page and the docs" + }, + { + "action": "scroll", + "target": { "role": "heading", "name": "Why DemoFlow", "exact": true }, + "caption": "The demo video in a glass frame, benefit cards with icons" + }, + { "action": "wait", "ms": 1200 }, + { + "action": "click", + "target": { "role": "button", "name": "Theme", "exact": true }, + "caption": "The theme toggle shares its choice with the app", + "zoom": true + }, + { + "action": "click", + "target": { "role": "menuitemradio", "name": "Dark", "exact": true } + }, + { "action": "press", "key": "Escape" }, + { "action": "wait", "ms": 800 }, + { + "action": "scroll", + "target": { + "role": "link", + "name": "Read the getting started guide", + "exact": true + } + }, + { + "action": "click", + "target": { + "role": "link", + "name": "Read the getting started guide", + "exact": true + } + }, + { + "action": "waitFor", + "target": { "role": "heading", "name": "Getting started", "exact": true }, + "caption": "The docs keep the dark theme" + }, + { + "action": "include", + "fragment": "open-docs", + "with": { "page": "config", "heading": "Project config" } + }, + { + "action": "scroll", + "target": { + "role": "cell", + "name": "Where your app runs. Scenario paths are relative to it.", + "exact": true + }, + "caption": "Code and tables on solid surfaces that pass WCAG AA" + }, + { "action": "wait", "ms": 1200 }, + { + "action": "click", + "target": { "role": "button", "name": "Theme", "exact": true } + }, + { + "action": "click", + "target": { "role": "menuitemradio", "name": "Light", "exact": true } + }, + { "action": "press", "key": "Escape" }, + { "action": "wait", "ms": 1000 } + ] +} From 0065d8863dcfbe056ecd83a469ec9ce73ed99a31 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 16:32:41 +0100 Subject: [PATCH 38/71] feat(web): solid primary actions on auth and device pages Glass UI's Button defaults to the glass variant; spec #375 asks for solid, full-width primary actions. Also allow 127.0.0.1 as a Next dev origin: the DemoFlow runner records on it and the page did not hydrate otherwise. --- apps/web/next.config.ts | 4 ++++ .../web/src/components/auth/forgot-password-form.tsx | 2 +- apps/web/src/components/auth/reset-password-form.tsx | 12 +++++++++--- apps/web/src/components/auth/sign-in-form.tsx | 7 ++++++- apps/web/src/components/auth/sign-up-form.tsx | 2 +- apps/web/src/components/auth/verify-email.tsx | 10 ++++++++-- apps/web/src/components/device/device-approval.tsx | 1 + apps/web/src/components/device/device-code-form.tsx | 2 +- 8 files changed, 31 insertions(+), 9 deletions(-) diff --git a/apps/web/next.config.ts b/apps/web/next.config.ts index c655fdc5..bd5c1385 100644 --- a/apps/web/next.config.ts +++ b/apps/web/next.config.ts @@ -11,6 +11,10 @@ const nextConfig: NextConfig = { transpilePackages: ['@demoflow/shared'], // The docs pages are `page.mdx` (spec #179). pageExtensions: ['ts', 'tsx', 'md', 'mdx'], + // The DemoFlow runner opens the dev server on 127.0.0.1 + // (demoflow.config.json); Next 16 blocks its dev resources from any host but + // localhost, so the page would never hydrate. Dev only, ignored by builds. + allowedDevOrigins: ['127.0.0.1'], // `/api` is reserved for the API. Stripping the prefix matches Caddy, so // the browser sees one origin locally and on staging alike. async rewrites() { diff --git a/apps/web/src/components/auth/forgot-password-form.tsx b/apps/web/src/components/auth/forgot-password-form.tsx index 39022c6a..dbb3f8a0 100644 --- a/apps/web/src/components/auth/forgot-password-form.tsx +++ b/apps/web/src/components/auth/forgot-password-form.tsx @@ -47,7 +47,7 @@ export function ForgotPasswordForm() { defaultValue={state.email} error={state.error} /> - <Button type="submit" full disabled={pending}> + <Button type="submit" variant="solid" full disabled={pending}> {pending ? t('auth.forgot.submitting') : t('auth.forgot.submit')} </Button> </form> diff --git a/apps/web/src/components/auth/reset-password-form.tsx b/apps/web/src/components/auth/reset-password-form.tsx index ff56daaa..4a94040a 100644 --- a/apps/web/src/components/auth/reset-password-form.tsx +++ b/apps/web/src/components/auth/reset-password-form.tsx @@ -41,7 +41,10 @@ export function ResetPasswordForm({ token }: { token: string }) { <Banner tone="ok" title={t('auth.reset.doneTitle')}> {t('auth.reset.doneBody')} </Banner> - <Link href="/sign-in" className={buttonClassName({ full: true })}> + <Link + href="/sign-in" + className={buttonClassName({ variant: 'solid', full: true })} + > {t('auth.reset.signIn')} </Link> </> @@ -63,7 +66,7 @@ export function ResetPasswordForm({ token }: { token: string }) { hint={t('auth.fields.passwordHint')} error={state.error} /> - <Button type="submit" full disabled={pending}> + <Button type="submit" variant="solid" full disabled={pending}> {pending ? t('auth.reset.submitting') : t('auth.reset.submit')} </Button> </form> @@ -76,7 +79,10 @@ export function InvalidResetLink() { <Banner tone="warn" title={t('auth.reset.invalidTitle')}> {t('auth.reset.invalidBody')} </Banner> - <Link href="/forgot-password" className={buttonClassName({ full: true })}> + <Link + href="/forgot-password" + className={buttonClassName({ variant: 'solid', full: true })} + > {t('auth.reset.requestNew')} </Link> </> diff --git a/apps/web/src/components/auth/sign-in-form.tsx b/apps/web/src/components/auth/sign-in-form.tsx index d7db1d0c..83ad99ad 100644 --- a/apps/web/src/components/auth/sign-in-form.tsx +++ b/apps/web/src/components/auth/sign-in-form.tsx @@ -67,7 +67,12 @@ export function SignInForm({ next }: { next?: string }) { autoComplete="current-password" error={state.errors.password} /> - <Button type="submit" full disabled={pending || state.done}> + <Button + type="submit" + variant="solid" + full + disabled={pending || state.done} + > {pending || state.done ? t('auth.signIn.submitting') : t('auth.signIn.submit')} diff --git a/apps/web/src/components/auth/sign-up-form.tsx b/apps/web/src/components/auth/sign-up-form.tsx index 8d979558..03a6caa3 100644 --- a/apps/web/src/components/auth/sign-up-form.tsx +++ b/apps/web/src/components/auth/sign-up-form.tsx @@ -73,7 +73,7 @@ export function SignUpForm() { hint={t('auth.fields.passwordHint')} error={state.errors.password} /> - <Button type="submit" full disabled={pending}> + <Button type="submit" variant="solid" full disabled={pending}> {pending ? t('auth.signUp.submitting') : t('auth.signUp.submit')} </Button> </form> diff --git a/apps/web/src/components/auth/verify-email.tsx b/apps/web/src/components/auth/verify-email.tsx index 5639c1ae..ed3edc47 100644 --- a/apps/web/src/components/auth/verify-email.tsx +++ b/apps/web/src/components/auth/verify-email.tsx @@ -54,7 +54,10 @@ export function VerifyEmail({ <Banner tone="ok" title={t('auth.verify.doneTitle')}> {t('auth.verify.doneBody')} </Banner> - <Link href="/app" className={buttonClassName({ full: true })}> + <Link + href="/app" + className={buttonClassName({ variant: 'solid', full: true })} + > {t('auth.verify.toApp')} </Link> </> @@ -76,7 +79,10 @@ export function VerifyEmail({ sentLabel={t('auth.verify.resent')} /> ) : ( - <Link href="/sign-in" className={buttonClassName({ full: true })}> + <Link + href="/sign-in" + className={buttonClassName({ variant: 'solid', full: true })} + > {t('auth.verify.signIn')} </Link> )} diff --git a/apps/web/src/components/device/device-approval.tsx b/apps/web/src/components/device/device-approval.tsx index 956134ff..7ae0cafe 100644 --- a/apps/web/src/components/device/device-approval.tsx +++ b/apps/web/src/components/device/device-approval.tsx @@ -168,6 +168,7 @@ export function DeviceApproval({ <div className="flex flex-col gap-3 tablet:flex-row"> <Button type="button" + variant="solid" size="lg" disabled={pending !== null} onClick={approve} diff --git a/apps/web/src/components/device/device-code-form.tsx b/apps/web/src/components/device/device-code-form.tsx index 94c690fa..cb9746bf 100644 --- a/apps/web/src/components/device/device-code-form.tsx +++ b/apps/web/src/components/device/device-code-form.tsx @@ -46,7 +46,7 @@ export function DeviceCodeForm() { required /> </Field> - <Button type="submit" size="lg"> + <Button type="submit" variant="solid" size="lg"> {t('device.code.submit')} </Button> </form> From ce5a74ab93ebcb247b7b8ce609add020eb367344 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 16:35:01 +0100 Subject: [PATCH 39/71] feat(web): Glass UI for projects, runs, the run page and machines One status vocabulary (lib/status.ts) maps every run, launch, stage, artifact and machine state to five kinds drawn with the Glass UI StatusPill, always with a text label, through the new StatusIndicator. The projects list, the project page and the machines page open with a PageHeader and keep their content on solid cards. The runs table and the machine list use the Glass UI table and stack their rows below 768px. The run page puts the player on a black frame with a glass side panel that holds the details, the stages, the failure message and the actions; it stacks below 1024px. Failure and stage text is monospace on a solid surface. The run breadcrumbs are gone. Refs #374 --- apps/web/package.json | 2 +- apps/web/src/app/app/machines/page.tsx | 23 +- apps/web/src/app/app/projects/[id]/page.tsx | 67 ++-- .../app/projects/[id]/runs/[runId]/page.tsx | 207 +++++++------ apps/web/src/app/app/projects/page.tsx | 23 +- .../src/components/machines/machine-list.tsx | 131 ++++---- .../src/components/player/run-playback.tsx | 290 ++++++++++++------ .../src/components/projects/delete-run.tsx | 4 +- .../src/components/projects/launch-status.tsx | 34 +- .../src/components/projects/machine-pill.tsx | 15 + .../src/components/projects/project-list.tsx | 178 ++++++----- .../src/components/projects/project-path.tsx | 56 ++++ .../web/src/components/projects/run-again.tsx | 67 ++-- .../components/projects/run-breadcrumbs.tsx | 41 --- .../src/components/projects/run-details.tsx | 167 +++++----- .../src/components/projects/run-status.tsx | 10 +- .../src/components/projects/runs-table.tsx | 158 +++++----- .../src/components/projects/stacked-rows.tsx | 29 ++ .../web/src/components/projects/start-run.tsx | 34 +- .../components/status/status-indicator.tsx | 27 ++ apps/web/src/i18n/en.ts | 74 +++-- apps/web/src/lib/status.test.mjs | 121 ++++++++ apps/web/src/lib/status.ts | 131 ++++++++ 23 files changed, 1168 insertions(+), 721 deletions(-) create mode 100644 apps/web/src/components/projects/machine-pill.tsx create mode 100644 apps/web/src/components/projects/project-path.tsx delete mode 100644 apps/web/src/components/projects/run-breadcrumbs.tsx create mode 100644 apps/web/src/components/projects/stacked-rows.tsx create mode 100644 apps/web/src/components/status/status-indicator.tsx create mode 100644 apps/web/src/lib/status.test.mjs create mode 100644 apps/web/src/lib/status.ts diff --git a/apps/web/package.json b/apps/web/package.json index c5fafb6b..ae52f674 100644 --- a/apps/web/package.json +++ b/apps/web/package.json @@ -7,7 +7,7 @@ "start": "next start -p 3670", "start:dev": "node scripts/dev.mjs", "lint": "biome lint src", - "test": "node --test src/lib/docs-nav.test.mjs src/lib/playback.test.mjs src/lib/launch.test.mjs src/lib/format-bytes.test.mjs src/lib/run-delete.test.mjs src/lib/player-choice.test.mjs src/lib/nav.test.mjs src/lib/crumbs.test.mjs src/lib/theme.test.mjs src/lib/overview-stats.test.mjs" + "test": "node --test src/lib/docs-nav.test.mjs src/lib/playback.test.mjs src/lib/launch.test.mjs src/lib/format-bytes.test.mjs src/lib/run-delete.test.mjs src/lib/player-choice.test.mjs src/lib/nav.test.mjs src/lib/crumbs.test.mjs src/lib/theme.test.mjs src/lib/overview-stats.test.mjs src/lib/status.test.mjs" }, "dependencies": { "@andrewbehma/glass-ui": "0.37.0", diff --git a/apps/web/src/app/app/machines/page.tsx b/apps/web/src/app/app/machines/page.tsx index 7befa3b2..32d4fa8d 100644 --- a/apps/web/src/app/app/machines/page.tsx +++ b/apps/web/src/app/app/machines/page.tsx @@ -1,5 +1,5 @@ import { Banner } from '@andrewbehma/glass-ui/banner'; -import { Card } from '@andrewbehma/glass-ui/card'; +import { PageHeader } from '@andrewbehma/glass-ui/page-header'; import { MachineList } from '@/components/machines/machine-list'; import { t } from '@/i18n'; import { getRunners } from '@/lib/session'; @@ -7,15 +7,16 @@ import { getRunners } from '@/lib/session'; export default async function MachinesPage() { const runners = await getRunners(); return ( - <Card pad="lg"> - <h1 className="text-2xl font-semibold">{t('machines.title')}</h1> - <div className="mt-4"> - {runners ? ( - <MachineList runners={runners} /> - ) : ( - <Banner tone="danger">{t('machines.loadFailed')}</Banner> - )} - </div> - </Card> + <> + <PageHeader + title={t('machines.title')} + description={t('machines.description')} + /> + {runners ? ( + <MachineList runners={runners} /> + ) : ( + <Banner tone="danger">{t('machines.loadFailed')}</Banner> + )} + </> ); } diff --git a/apps/web/src/app/app/projects/[id]/page.tsx b/apps/web/src/app/app/projects/[id]/page.tsx index 32ee0aab..e6fed326 100644 --- a/apps/web/src/app/app/projects/[id]/page.tsx +++ b/apps/web/src/app/app/projects/[id]/page.tsx @@ -1,6 +1,10 @@ import { Banner } from '@andrewbehma/glass-ui/banner'; import { Card } from '@andrewbehma/glass-ui/card'; +import { PageHeader } from '@andrewbehma/glass-ui/page-header'; +import { SectionHeader } from '@andrewbehma/glass-ui/section-header'; import { notFound } from 'next/navigation'; +import { MachinePill } from '@/components/projects/machine-pill'; +import { ProjectPath } from '@/components/projects/project-path'; import { RunsTable } from '@/components/projects/runs-table'; import { StartRun } from '@/components/projects/start-run'; import { CrumbName } from '@/components/shell/crumb-names'; @@ -28,22 +32,23 @@ export default async function ProjectLibraryPage({ return ( <> {project ? <CrumbName segment={id} name={project.name} /> : null} - <Card pad="lg"> - <h1 className="break-words text-2xl font-semibold"> - {project?.name ?? t('projects.title')} - </h1> - {project?.rootPath ? ( - <div className="mt-1 flex flex-col gap-0.5 text-sm text-ink-2"> - <p className="break-all"> - {t('projects.library.path')}: {project.rootPath} - </p> - <p className="break-words"> - {t('projects.library.machine')}:{' '} - {project.runner?.name ?? t('projects.item.machineRemoved')} - </p> - </div> - ) : null} - </Card> + <PageHeader + title={ + <span className="break-words"> + {project?.name ?? t('projects.title')} + </span> + } + status={ + project?.rootPath ? <MachinePill machine={project.runner} /> : null + } + description={ + project?.rootPath ? ( + <ProjectPath path={project.rootPath} /> + ) : project ? ( + t('projects.item.noFolder') + ) : null + } + /> {project ? ( <StartRun projectId={id} @@ -51,18 +56,24 @@ export default async function ProjectLibraryPage({ machine={project.runner} /> ) : null} - <Card pad="lg"> - {runs === 'error' ? ( - <Banner tone="danger">{t('projects.library.pageFailed')}</Banner> - ) : ( - <RunsTable - key={status ?? 'all'} - projectId={id} - first={runs} - status={status} - /> - )} - </Card> + <section aria-labelledby="project-runs" className="flex flex-col gap-3"> + <SectionHeader + title={t('projects.library.runsTitle')} + headingId="project-runs" + /> + <Card pad="md"> + {runs === 'error' ? ( + <Banner tone="danger">{t('projects.library.pageFailed')}</Banner> + ) : ( + <RunsTable + key={status ?? 'all'} + projectId={id} + first={runs} + status={status} + /> + )} + </Card> + </section> </> ); } diff --git a/apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx b/apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx index 74d9159a..9a018f39 100644 --- a/apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx +++ b/apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx @@ -1,13 +1,16 @@ import { Banner } from '@andrewbehma/glass-ui/banner'; -import { Card } from '@andrewbehma/glass-ui/card'; import { KeyValueList } from '@andrewbehma/glass-ui/key-value-list'; +import { PageHeader } from '@andrewbehma/glass-ui/page-header'; import { notFound } from 'next/navigation'; import { RunPlayback } from '@/components/player/run-playback'; import { DeleteRun } from '@/components/projects/delete-run'; +import { formatList } from '@/components/projects/format-choice'; +import { MachinePill } from '@/components/projects/machine-pill'; import { RunAgain } from '@/components/projects/run-again'; import { - RunDetails, - RunFailureBanner, + RunFailure, + RunFiles, + RunStages, } from '@/components/projects/run-details'; import { RunStatus } from '@/components/projects/run-status'; import { CrumbName } from '@/components/shell/crumb-names'; @@ -39,99 +42,121 @@ export default async function RunPage({ machine, scenarioPath: run.scenarioPath, }); + const details = ( + <> + <KeyValueList + columns={1} + dense + items={[ + { + key: 'status', + label: t('runPage.metadata.status'), + value: <RunStatus status={run.status} />, + }, + { + key: 'scenario', + label: t('runPage.metadata.scenario'), + value: <span className="break-words">{run.scenarioName}</span>, + }, + { + key: 'path', + label: t('runPage.metadata.path'), + value: ( + <span className="break-all font-mono text-xs"> + {run.scenarioPath} + </span> + ), + }, + { + key: 'when', + label: t('runPage.metadata.when'), + value: ( + <time dateTime={run.startedAt}> + {formatDate(run.startedAt)} ( + {relative ?? t('runPage.metadata.justNow')}) + </time> + ), + }, + { + key: 'duration', + label: t('runPage.metadata.duration'), + value: formatDuration(run.durationMs), + }, + { + key: 'failedStep', + label: t('runPage.metadata.failedStep'), + value: + run.failedStep === null + ? t('runPage.metadata.noFailedStep') + : t('runPage.metadata.step', { + number: run.failedStep + 1, + }), + }, + { + key: 'machine', + label: t('runPage.metadata.machine'), + value: <MachinePill machine={machine} />, + }, + { + key: 'formats', + label: t('runPage.metadata.formats'), + value: + run.formats.length > 0 + ? formatList(run.formats) + : t('runPage.metadata.noFormats'), + }, + { + key: 'cliVersion', + label: t('runPage.metadata.cliVersion'), + value: <span className="font-mono text-xs">{run.cliVersion}</span>, + }, + ]} + /> + <RunFailure failure={run.failure} /> + <RunStages stages={run.stages} /> + </> + ); return ( <> <CrumbName segment={project.id} name={project.name} /> <CrumbName segment={run.id} name={run.scenarioName} /> - <Card pad="lg"> - <h1 className="break-words text-2xl font-semibold"> - {t('runPage.title', { name: run.scenarioName })} - </h1> - <div className="mt-4"> - <KeyValueList - columns={2} - items={[ - { - key: 'scenario', - label: t('runPage.metadata.scenario'), - value: run.scenarioName, - }, - { - key: 'path', - label: t('runPage.metadata.path'), - value: run.scenarioPath, - }, - { - key: 'status', - label: t('runPage.metadata.status'), - value: <RunStatus status={run.status} />, - }, - { - key: 'when', - label: t('runPage.metadata.when'), - value: ( - <time dateTime={run.startedAt}> - {formatDate(run.startedAt)} ( - {relative ?? t('runPage.metadata.justNow')}) - </time> - ), - }, - { - key: 'duration', - label: t('runPage.metadata.duration'), - value: formatDuration(run.durationMs), - }, - { - key: 'failedStep', - label: t('runPage.metadata.failedStep'), - value: - run.failedStep === null - ? t('runPage.metadata.noFailedStep') - : t('runPage.metadata.step', { - number: run.failedStep + 1, - }), - }, - { - key: 'machine', - label: t('runPage.metadata.machine'), - value: machine?.name ?? t('projects.item.machineRemoved'), - }, - { - key: 'cliVersion', - label: t('runPage.metadata.cliVersion'), - value: run.cliVersion, - }, - ]} + <PageHeader + title={ + <span className="break-words"> + {t('runPage.title', { name: run.scenarioName })} + </span> + } + description={project.name} + /> + <RunPlayback + runId={run.id} + formats={run.formats} + machine={machine} + artifactsDeletedAt={run.artifactsDeletedAt} + details={details} + runAgain={ + machine !== null && againState !== 'hidden' ? ( + <RunAgain + projectId={project.id} + scenarioId={run.scenarioPath} + scenarioName={run.scenarioName} + machineName={machine.name} + offline={againState === 'offline'} + formats={runAgainFormats(run.formats, machine.runOptions)} + /> + ) : null + } + deleteRun={ + <DeleteRun + runId={run.id} + projectId={project.id} + filesRemain={ + run.formats.length > 0 && run.artifactsDeletedAt === null + } /> - </div> - <DeleteRun - runId={run.id} - projectId={project.id} - filesRemain={ - run.formats.length > 0 && run.artifactsDeletedAt === null - } - /> - </Card> - <RunFailureBanner failure={run.failure} /> - {machine !== null && againState !== 'hidden' ? ( - <RunAgain - projectId={project.id} - scenarioId={run.scenarioPath} - scenarioName={run.scenarioName} - machineName={machine.name} - offline={againState === 'offline'} - formats={runAgainFormats(run.formats, machine.runOptions)} - /> - ) : null} - <Card pad="lg"> - <RunPlayback - runId={run.id} - formats={run.formats} - machine={machine} - artifactsDeletedAt={run.artifactsDeletedAt} - /> - </Card> - <RunDetails stages={run.stages} renders={run.renders} /> + } + /> + <RunFiles renders={run.renders} /> </> ); } diff --git a/apps/web/src/app/app/projects/page.tsx b/apps/web/src/app/app/projects/page.tsx index 02d3f582..83040c04 100644 --- a/apps/web/src/app/app/projects/page.tsx +++ b/apps/web/src/app/app/projects/page.tsx @@ -1,5 +1,5 @@ import { Banner } from '@andrewbehma/glass-ui/banner'; -import { Card } from '@andrewbehma/glass-ui/card'; +import { PageHeader } from '@andrewbehma/glass-ui/page-header'; import { ProjectList } from '@/components/projects/project-list'; import { t } from '@/i18n'; import { getMachines, getProjects } from './_data'; @@ -10,15 +10,16 @@ export default async function ProjectsPage() { getMachines(), ]); return ( - <Card pad="lg"> - <h1 className="text-2xl font-semibold">{t('projects.title')}</h1> - <div className="mt-4"> - {projects ? ( - <ProjectList projects={projects} machines={machines} /> - ) : ( - <Banner tone="danger">{t('projects.loadFailed')}</Banner> - )} - </div> - </Card> + <> + <PageHeader + title={t('projects.title')} + description={t('projects.description')} + /> + {projects ? ( + <ProjectList projects={projects} machines={machines} /> + ) : ( + <Banner tone="danger">{t('projects.loadFailed')}</Banner> + )} + </> ); } diff --git a/apps/web/src/components/machines/machine-list.tsx b/apps/web/src/components/machines/machine-list.tsx index c784c477..30a49a07 100644 --- a/apps/web/src/components/machines/machine-list.tsx +++ b/apps/web/src/components/machines/machine-list.tsx @@ -2,15 +2,25 @@ import { Banner } from '@andrewbehma/glass-ui/banner'; import { Button } from '@andrewbehma/glass-ui/button'; +import { Card } from '@andrewbehma/glass-ui/card'; import { ConfirmDialog } from '@andrewbehma/glass-ui/confirm-dialog'; import { EmptyState } from '@andrewbehma/glass-ui/empty-state'; import { Input } from '@andrewbehma/glass-ui/field'; +import { + Table, + TableCell, + TableHead, + TableRow, +} from '@andrewbehma/glass-ui/table'; import { useRouter } from 'next/navigation'; import { useEffect, useState } from 'react'; +import { CellLabel, stacked } from '@/components/projects/stacked-rows'; +import { StatusIndicator } from '@/components/status/status-indicator'; import { t } from '@/i18n'; import { type Runner, renameRunner, revokeRunner } from '@/lib/api'; import { formatDate } from '@/lib/format-date'; import { formatRelative } from '@/lib/format-relative'; +import { machineStatus } from '@/lib/status'; import type { ErrorKey } from '@/lib/validation'; import { apiErrorKey } from '../auth/form-parts'; @@ -128,40 +138,34 @@ export function MachineList({ runners }: { runners: Runner[] }) { </code> </Banner> )} - <div className="overflow-x-auto"> - <table className="w-full min-w-[48rem] text-left text-sm"> - <thead className="text-ink-2"> + <Card pad="sm"> + <Table className={stacked.table}> + <TableHead className={stacked.head}> <tr> - <th scope="col" className="py-2 pr-4 font-normal"> + <TableCell head scope="col"> {t('machines.columns.name')} - </th> - <th scope="col" className="py-2 pr-4 font-normal"> - {t('machines.columns.status')} - </th> - <th scope="col" className="py-2 pr-4 font-normal"> - {t('machines.columns.lastSeen')} - </th> - <th scope="col" className="py-2 pr-4 font-normal"> + </TableCell> + <TableCell head scope="col"> {t('machines.columns.os')} - </th> - <th scope="col" className="py-2 pr-4 font-normal"> + </TableCell> + <TableCell head scope="col"> {t('machines.columns.cliVersion')} - </th> - <th scope="col" className="py-2 pr-4 font-normal"> - {t('machines.columns.paired')} - </th> - <th scope="col" className="py-2 pr-4 font-normal"> - {t('machines.columns.lastUsed')} - </th> - <th scope="col" className="py-2 font-normal"> + </TableCell> + <TableCell head scope="col"> + {t('machines.columns.status')} + </TableCell> + <TableCell head scope="col"> + {t('machines.columns.lastSeen')} + </TableCell> + <TableCell head scope="col"> <span className="sr-only">{t('machines.columns.actions')}</span> - </th> + </TableCell> </tr> - </thead> - <tbody> + </TableHead> + <tbody className={stacked.body}> {runners.map((runner) => ( - <tr key={runner.id} className="border-t border-current/10"> - <td className="py-3 pr-4 align-top"> + <TableRow key={runner.id} className={stacked.row}> + <TableCell className={stacked.lead}> {renaming === runner.id ? ( <RenameForm runner={runner} @@ -173,38 +177,45 @@ export function MachineList({ runners }: { runners: Runner[] }) { }} /> ) : ( - <span className="break-words">{runner.name}</span> + <> + <span className="break-words font-medium text-ink"> + {runner.name} + </span> + <span className="block text-xs text-ink-2"> + {t('machines.paired', { + date: formatDate(runner.createdAt), + })}{' '} + ·{' '} + {runner.lastUsedAt + ? t('machines.lastUsed', { + date: formatDate(runner.lastUsedAt), + }) + : t('machines.neverUsed')} + </span> + </> )} - </td> - <td className="py-3 pr-4 align-top"> - <span className="inline-flex items-center gap-2"> - <span - aria-hidden="true" - className={`size-2.5 rounded-full ${runner.online ? 'bg-green-500' : 'bg-gray-400'}`} - /> - {runner.online - ? t('machines.status.online') - : t('machines.status.offline')} - </span> - </td> - <td className="py-3 pr-4 align-top"> + </TableCell> + <TableCell className={`${stacked.cell} break-words`}> + <CellLabel>{t('machines.columns.os')}</CellLabel> + {runner.os} + </TableCell> + <TableCell className={`${stacked.cell} font-mono text-xs`}> + <CellLabel>{t('machines.columns.cliVersion')}</CellLabel> + {runner.cliVersion} + </TableCell> + <TableCell className={stacked.cell}> + <CellLabel>{t('machines.columns.status')}</CellLabel> + <StatusIndicator status={machineStatus(runner.online)} /> + </TableCell> + <TableCell className={stacked.cell}> + <CellLabel>{t('machines.columns.lastSeen')}</CellLabel> <LastSeen runner={runner} now={now} /> - </td> - <td className="py-3 pr-4 align-top break-words">{runner.os}</td> - <td className="py-3 pr-4 align-top">{runner.cliVersion}</td> - <td className="py-3 pr-4 align-top"> - {formatDate(runner.createdAt)} - </td> - <td className="py-3 pr-4 align-top"> - {runner.lastUsedAt - ? formatDate(runner.lastUsedAt) - : t('machines.neverUsed')} - </td> - <td className="py-3 align-top"> - <div className="flex gap-2"> + </TableCell> + <TableCell className={stacked.cell}> + <div className="flex gap-2 md:justify-end"> <Button type="button" - variant="glass" + variant="ghost" size="sm" onClick={() => { setRenaming(runner.id); @@ -222,12 +233,12 @@ export function MachineList({ runners }: { runners: Runner[] }) { {t('machines.revoke')} </Button> </div> - </td> - </tr> + </TableCell> + </TableRow> ))} </tbody> - </table> - </div> + </Table> + </Card> <ConfirmDialog open={revoking !== null} onOpenChange={(open) => { @@ -255,7 +266,7 @@ function LastSeen({ runner, now }: { runner: Runner; now: number | null }) { : (formatRelative(runner.lastSeenAt, now) ?? t('machines.lastSeen.justNow')); return ( - <div className="flex flex-col"> + <div className="flex min-w-0 flex-col"> <time dateTime={runner.lastSeenAt} title={formatDate(runner.lastSeenAt)}> {when} </time> diff --git a/apps/web/src/components/player/run-playback.tsx b/apps/web/src/components/player/run-playback.tsx index f1a627e7..42109cc1 100644 --- a/apps/web/src/components/player/run-playback.tsx +++ b/apps/web/src/components/player/run-playback.tsx @@ -2,14 +2,15 @@ import { Banner } from '@andrewbehma/glass-ui/banner'; import { Button } from '@andrewbehma/glass-ui/button'; +import { Card } from '@andrewbehma/glass-ui/card'; import { ConfirmDialog } from '@andrewbehma/glass-ui/confirm-dialog'; -import { EmptyState } from '@andrewbehma/glass-ui/empty-state'; import { SegmentedControl, SegmentedControlItem, } from '@andrewbehma/glass-ui/segmented-control'; import { useRouter } from 'next/navigation'; -import { useState } from 'react'; +import { type ReactNode, useState } from 'react'; +import { StatusIndicator } from '@/components/status/status-indicator'; import { t } from '@/i18n'; import { deleteRunArtifacts, getRun, type RunDetail } from '@/lib/api'; import { formatDate } from '@/lib/format-date'; @@ -24,22 +25,62 @@ import { playerShape, videoUrl, } from '@/lib/playback'; +import { type StatusView, videoStatus } from '@/lib/status'; import { choosePlayer } from './video-player'; /** - * The format switcher, the player (or image), the availability messages and - * the control that deletes the run's files from its machine. + * Why the video cannot be shown, inside the black frame. The message sits on a + * solid surface, so its text keeps the theme's contrast over the black. + */ +function FrameMessage({ + status, + title, + body, + children, +}: { + status: StatusView | null; + title: string; + body?: string; + children?: ReactNode; +}) { + return ( + <div className="flex aspect-video items-center justify-center p-4"> + <Card + variant="content" + pad="md" + className="flex max-w-md flex-col items-center gap-2 text-center" + > + {status ? <StatusIndicator status={status} /> : null} + <p className="font-medium">{title}</p> + {body ? <p className="text-sm text-ink-2">{body}</p> : null} + {children} + </Card> + </div> + ); +} + +/** + * The run page's body (spec #374, Decision 4): the player on a black frame, + * and beside it the glass panel with the run's `details` and its actions — + * `runAgain`, Download, the control that deletes the run's files from its + * machine, and `deleteRun`. Below 1024px the panel stacks under the player. */ export function RunPlayback({ runId, formats: runFormats, machine: initialMachine, artifactsDeletedAt: initialDeletedAt, + details, + runAgain, + deleteRun, }: { runId: string; formats: string[]; machine: RunDetail['machine']; artifactsDeletedAt: string | null; + details: ReactNode; + runAgain: ReactNode; + deleteRun: ReactNode; }) { const router = useRouter(); const formats = orderFormats(runFormats); @@ -60,19 +101,6 @@ export function RunPlayback({ DeleteFailureKey | undefined >(); - if (deletedAt !== null) { - return ( - <EmptyState - title={t('runPage.deleted.title')} - description={t('runPage.deleted.body', { date: formatDate(deletedAt) })} - /> - ); - } - - if (format === undefined) { - return <Banner tone="info">{t('runPage.noFormats')}</Banner>; - } - /** Asks the API again whether the machine is still there and online. */ async function refetchMachine() { setBusy(true); @@ -134,108 +162,166 @@ export function RunPlayback({ setAttempt((current) => current + 1); } - const state = deleting ? 'deleting' : availability(machine, playerFailed); const online = machine?.online === true; - const Player = choosePlayer(); - const src = videoUrl(runId, format); - const isGif = isGifFormat(format); + const unavailable = videoStatus( + { artifactsDeletedAt: deletedAt, formats: runFormats }, + machine, + ); + // Download and Delete video files only make sense while there are files. + const hasFiles = deletedAt === null && format !== undefined; - return ( - <div className="flex flex-col gap-4"> - <div className="flex flex-wrap items-center gap-3"> - {formats.length > 1 ? ( - <SegmentedControl aria-label={t('runPage.formats.label')}> - {formats.map((candidate) => ( - <SegmentedControlItem - key={candidate} - active={candidate === format} - layoutId="run-format" - > - <button - type="button" - aria-pressed={candidate === format} - className="px-3 py-1 text-sm" - onClick={() => { - setFormat(candidate); - setPlayerFailed(false); - }} - > - {t(`runPage.formats.${candidate}`)} - </button> - </SegmentedControlItem> - ))} - </SegmentedControl> - ) : null} - <Button - type="button" - variant="glass" - disabled={!online || deleting || checking} - onClick={() => void download(format)} - > - {checking - ? t('runPage.download.checking') - : t('runPage.download.button')} - </Button> - {online ? null : ( - <span className="text-sm text-ink-2"> - {t('runPage.download.offlineHint')} - </span> - )} - </div> - {state === 'ready' && isGif ? ( + function frame(): ReactNode { + if (deletedAt !== null) { + return ( + <FrameMessage + status={unavailable} + title={t('runPage.deleted.title')} + body={t('runPage.deleted.body', { date: formatDate(deletedAt) })} + /> + ); + } + if (format === undefined) { + return ( + <FrameMessage status={unavailable} title={t('runPage.noFormats')} /> + ); + } + const state = deleting ? 'deleting' : availability(machine, playerFailed); + const src = videoUrl(runId, format); + if (state === 'ready' && isGifFormat(format)) { + return ( // biome-ignore lint/performance/noImgElement: a relay stream, not a static asset next/image can optimize <img key={`${src}-${attempt}`} src={src} alt={t('runPage.gifAlt')} onError={handlePlayerError} - className="mx-auto max-h-[70vh] rounded-control" + className="mx-auto max-h-[70vh]" /> - ) : null} - {state === 'ready' && !isGif ? ( + ); + } + if (state === 'ready') { + const Player = choosePlayer(); + return ( <Player key={`${src}-${attempt}`} src={src} shape={playerShape(format)} onError={handlePlayerError} /> - ) : null} - {state === 'removed' ? ( - <Banner tone="warn">{t('runPage.removed')}</Banner> - ) : null} - {state === 'offline' && machine ? ( - <Banner tone="warn"> - {t('runPage.offline', { name: machine.name })} - </Banner> - ) : null} - {state === 'failed' && machine ? ( - <Banner tone="danger"> - {t('runPage.failed', { name: machine.name })} - </Banner> - ) : null} - {state === 'offline' || state === 'failed' ? ( - <div> - <Button type="button" variant="glass" disabled={busy} onClick={retry}> - {busy ? t('runPage.retrying') : t('runPage.retry')} - </Button> - </div> - ) : null} - {deleteError ? <Banner tone="danger">{t(deleteError)}</Banner> : null} - <div className="flex flex-wrap items-center gap-3"> - <Button - type="button" - variant="danger" - disabled={!online || deleting} - onClick={() => setConfirming(true)} + ); + } + if (state === 'deleting') return <div className="aspect-video" />; + const retryButton = ( + <Button type="button" variant="glass" disabled={busy} onClick={retry}> + {busy ? t('runPage.retrying') : t('runPage.retry')} + </Button> + ); + if (state === 'removed') { + return <FrameMessage status={unavailable} title={t('runPage.removed')} />; + } + const name = machine?.name ?? ''; + return state === 'offline' ? ( + <FrameMessage status={unavailable} title={t('runPage.offline', { name })}> + {retryButton} + </FrameMessage> + ) : ( + <FrameMessage status={null} title={t('runPage.failed', { name })}> + {retryButton} + </FrameMessage> + ); + } + + return ( + <div className="grid gap-4 lg:grid-cols-[minmax(0,1fr)_22rem] lg:items-start"> + <div className="flex min-w-0 flex-col gap-3"> + <div + data-testid="run-player" + className="overflow-hidden rounded-surface bg-black" > - {t('runPage.delete.open')} - </Button> - {online ? null : ( - <span className="text-sm text-ink-2"> - {t('runPage.delete.offlineHint')} - </span> - )} + {frame()} + </div> + {format !== undefined && deletedAt === null && formats.length > 1 ? ( + <div className="max-w-full overflow-x-auto"> + <SegmentedControl aria-label={t('runPage.formats.label')}> + {formats.map((candidate) => ( + <SegmentedControlItem + key={candidate} + active={candidate === format} + layoutId="run-format" + > + <button + type="button" + aria-pressed={candidate === format} + className="whitespace-nowrap px-3 py-1 text-sm" + onClick={() => { + setFormat(candidate); + setPlayerFailed(false); + }} + > + {t(`runPage.formats.${candidate}`)} + </button> + </SegmentedControlItem> + ))} + </SegmentedControl> + </div> + ) : null} </div> + <Card + variant="glass" + pad="md" + role="complementary" + aria-label={t('runPage.panel')} + className="flex min-w-0 flex-col gap-4" + > + {details} + <section + aria-labelledby="run-actions" + className="flex flex-col gap-3 border-t border-line pt-4" + > + <h2 id="run-actions" className="text-sm font-semibold"> + {t('runPage.actions')} + </h2> + {runAgain} + {hasFiles && format !== undefined ? ( + <div className="flex flex-wrap items-center gap-3"> + <Button + type="button" + variant="solid" + disabled={!online || deleting || checking} + onClick={() => void download(format)} + > + {checking + ? t('runPage.download.checking') + : t('runPage.download.button')} + </Button> + {online ? null : ( + <span className="text-sm text-ink-2"> + {t('runPage.download.offlineHint')} + </span> + )} + </div> + ) : null} + {deleteError ? <Banner tone="danger">{t(deleteError)}</Banner> : null} + {hasFiles ? ( + <div className="flex flex-wrap items-center gap-3"> + <Button + type="button" + variant="danger" + disabled={!online || deleting} + onClick={() => setConfirming(true)} + > + {t('runPage.delete.open')} + </Button> + {online ? null : ( + <span className="text-sm text-ink-2"> + {t('runPage.delete.offlineHint')} + </span> + )} + </div> + ) : null} + {deleteRun} + </section> + </Card> <ConfirmDialog open={confirming} onOpenChange={setConfirming} diff --git a/apps/web/src/components/projects/delete-run.tsx b/apps/web/src/components/projects/delete-run.tsx index 5f6f163a..d72868cf 100644 --- a/apps/web/src/components/projects/delete-run.tsx +++ b/apps/web/src/components/projects/delete-run.tsx @@ -45,11 +45,11 @@ export function DeleteRun({ } return ( - <div className="mt-4 flex flex-col gap-3"> + <div className="flex flex-col gap-3"> {failed ? ( <Banner tone="danger">{t('auth.errors.unknown')}</Banner> ) : null} - <div className="flex justify-end"> + <div> <Button type="button" variant="danger" diff --git a/apps/web/src/components/projects/launch-status.tsx b/apps/web/src/components/projects/launch-status.tsx index 6da1788a..23ee7756 100644 --- a/apps/web/src/components/projects/launch-status.tsx +++ b/apps/web/src/components/projects/launch-status.tsx @@ -2,35 +2,14 @@ import { Button } from '@andrewbehma/glass-ui/button'; import { Progress } from '@andrewbehma/glass-ui/progress'; -import { StatusPill } from '@andrewbehma/glass-ui/status-pill'; import Link from 'next/link'; +import { StatusIndicator } from '@/components/status/status-indicator'; import { t } from '@/i18n'; -import type { LaunchState, LaunchView } from '@/lib/api'; +import type { LaunchView } from '@/lib/api'; import { formatElapsed, isActive, launchProgress } from '@/lib/launch'; +import { launchStatus } from '@/lib/status'; import { formatList } from './format-choice'; -const PILL: Record<LaunchState, Parameters<typeof StatusPill>[0]['status']> = { - starting: 'waiting', - running: 'running', - cancelling: 'paused', - passed: 'done', - failed: 'error', - cancelled: 'idle', - 'timed-out': 'error', - lost: 'blocked', -}; - -function stateLabel(state: LaunchState): string { - switch (state) { - case 'timed-out': - return t('projects.launch.state.timedOut'); - case 'lost': - return t('projects.launch.state.lostLabel'); - default: - return t(`projects.launch.state.${state}`); - } -} - /** The row of a launch: name, state, elapsed time, cancel, and the new run. */ export function LaunchStatus({ projectId, @@ -57,10 +36,7 @@ export function LaunchStatus({ <span className="min-w-0 break-words font-medium"> {launch.scenarioName ?? launch.scenarioId} </span> - <StatusPill - status={PILL[launch.state]} - label={stateLabel(launch.state)} - /> + <StatusIndicator status={launchStatus(launch.state)} /> {active ? ( <span className="text-sm text-ink-2"> {t('projects.launch.elapsed', { @@ -100,7 +76,7 @@ export function LaunchStatus({ <p className="text-sm text-ink-2">{t(progress.key)}</p> ) : null} {launch.state === 'lost' ? ( - <p className="text-sm text-ink-2">{t('projects.launch.state.lost')}</p> + <p className="text-sm text-ink-2">{t('projects.launch.lost')}</p> ) : null} {!active && launch.runId ? ( <Link diff --git a/apps/web/src/components/projects/machine-pill.tsx b/apps/web/src/components/projects/machine-pill.tsx new file mode 100644 index 00000000..1dd80692 --- /dev/null +++ b/apps/web/src/components/projects/machine-pill.tsx @@ -0,0 +1,15 @@ +import { Badge } from '@andrewbehma/glass-ui/badge'; +import { StatusIndicator } from '@/components/status/status-indicator'; +import { MACHINE_REMOVED } from '@/lib/status'; + +/** + * The machine a project is bound to, as a pill; a removed machine is the + * `unavailable` status, the same pill the run page shows for it. + */ +export function MachinePill({ machine }: { machine: { name: string } | null }) { + return machine === null ? ( + <StatusIndicator status={MACHINE_REMOVED} /> + ) : ( + <Badge tone="neutral" size="md" label={machine.name} /> + ); +} diff --git a/apps/web/src/components/projects/project-list.tsx b/apps/web/src/components/projects/project-list.tsx index 0c814232..f16a937a 100644 --- a/apps/web/src/components/projects/project-list.tsx +++ b/apps/web/src/components/projects/project-list.tsx @@ -2,12 +2,14 @@ import { Banner } from '@andrewbehma/glass-ui/banner'; import { Button } from '@andrewbehma/glass-ui/button'; +import { Card } from '@andrewbehma/glass-ui/card'; import { ConfirmDialog } from '@andrewbehma/glass-ui/confirm-dialog'; import { EmptyState } from '@andrewbehma/glass-ui/empty-state'; import { Field, Input, Select } from '@andrewbehma/glass-ui/field'; import Link from 'next/link'; import { useRouter } from 'next/navigation'; import { type FormEvent, useId, useState } from 'react'; +import { StatusIndicator } from '@/components/status/status-indicator'; import { t } from '@/i18n'; import { type ApiResult, @@ -18,9 +20,11 @@ import { updateProject, } from '@/lib/api'; import { formatDate } from '@/lib/format-date'; +import { formatRelative } from '@/lib/format-relative'; +import { lastRunStatus } from '@/lib/status'; import type { ErrorKey } from '@/lib/validation'; import { apiErrorKey } from '../auth/form-parts'; -import { RunStatus } from './run-status'; +import { MachinePill } from './machine-pill'; const NAME_MAX = 200; @@ -127,68 +131,77 @@ export function ProjectList({ <EmptyState title={t('projects.empty.title')} description={t('projects.empty.body')} + action={ + <Link href="/docs" className="text-sm text-ink underline"> + {t('projects.empty.docs')} + </Link> + } /> ) : ( - <ul className="flex flex-col"> - {projects.map((project) => ( - <li - key={project.id} - className="flex flex-col gap-3 border-t border-current/10 py-4" - > - {editing?.id === project.id && editing.mode === 'rename' ? ( - <RenameForm - project={project} - busy={busy} - onSave={(value) => rename(project, value)} - onCancel={stop} - /> - ) : ( - <ProjectSummary project={project} /> - )} - {editing?.id === project.id && editing.mode === 'bind' ? ( - <BindForm - project={project} - machines={machines} - busy={busy} - onBind={(runnerId, path) => bind(project, runnerId, path)} - onCancel={stop} - /> - ) : null} - <div className="flex flex-wrap gap-2"> - <Button - type="button" - variant="glass" - size="sm" - onClick={() => { - setEditing({ id: project.id, mode: 'rename' }); - setError(undefined); - }} - > - {t('projects.rename.action')} - </Button> - <Button - type="button" - variant="glass" - size="sm" - onClick={() => { - setEditing({ id: project.id, mode: 'bind' }); - setError(undefined); - }} - > - {t('projects.bind.action')} - </Button> - <Button - type="button" - variant="danger" - size="sm" - onClick={() => setDeleting(project)} - > - {t('projects.delete.action')} - </Button> - </div> - </li> - ))} - </ul> + <Card pad="none"> + <ul aria-label={t('projects.title')} className="flex flex-col"> + {projects.map((project) => ( + <li + key={project.id} + className="flex flex-col gap-3 border-b border-line px-4 py-3 last:border-0 md:flex-row md:items-start md:justify-between" + > + <div className="flex min-w-0 flex-1 flex-col gap-3"> + {editing?.id === project.id && editing.mode === 'rename' ? ( + <RenameForm + project={project} + busy={busy} + onSave={(value) => rename(project, value)} + onCancel={stop} + /> + ) : ( + <ProjectSummary project={project} /> + )} + {editing?.id === project.id && editing.mode === 'bind' ? ( + <BindForm + project={project} + machines={machines} + busy={busy} + onBind={(runnerId, path) => bind(project, runnerId, path)} + onCancel={stop} + /> + ) : null} + </div> + <div className="flex shrink-0 flex-wrap gap-2"> + <Button + type="button" + variant="ghost" + size="sm" + onClick={() => { + setEditing({ id: project.id, mode: 'rename' }); + setError(undefined); + }} + > + {t('projects.rename.action')} + </Button> + <Button + type="button" + variant="ghost" + size="sm" + onClick={() => { + setEditing({ id: project.id, mode: 'bind' }); + setError(undefined); + }} + > + {t('projects.bind.action')} + </Button> + <Button + type="button" + variant="danger" + size="sm" + onClick={() => setDeleting(project)} + > + {t('projects.delete.action')} + </Button> + </div> + </li> + ))} + </ul> + </Card> )} <ConfirmDialog open={deleting !== null} @@ -207,45 +220,42 @@ export function ProjectList({ ); } +/** One project's row: its name, machine, last run and how many runs it has. */ function ProjectSummary({ project }: { project: Project }) { const { lastRun } = project; return ( - <div className="flex flex-col gap-1"> + <div className="flex min-w-0 flex-col gap-1"> <Link href={`/app/projects/${encodeURIComponent(project.id)}`} - className="break-words text-lg font-semibold underline" + className="break-words font-semibold text-ink underline-offset-2 hover:underline" > {project.name} </Link> - <p className="break-all text-sm text-ink-2"> - {project.rootPath === null - ? t('projects.item.noFolder') - : `${t('projects.item.path')}: ${project.rootPath}`} - </p> - {project.rootPath !== null ? ( - <p className="break-words text-sm text-ink-2"> - {t('projects.item.machine')}:{' '} - {project.runner?.name ?? t('projects.item.machineRemoved')} - </p> - ) : null} - <p className="flex flex-wrap items-center gap-2 text-sm"> + <p className="flex flex-wrap items-center gap-x-2 gap-y-1 text-sm text-ink-2"> + {project.rootPath === null ? ( + <span>{t('projects.item.noFolder')}</span> + ) : ( + <MachinePill machine={project.runner} /> + )} + <StatusIndicator status={lastRunStatus(lastRun)} /> {lastRun ? ( <> - <span className="text-ink-2">{t('projects.item.lastRun')}</span> - <RunStatus status={lastRun.status} /> - <time dateTime={lastRun.startedAt}> - {formatDate(lastRun.startedAt)} + <time + dateTime={lastRun.startedAt} + title={formatDate(lastRun.startedAt)} + suppressHydrationWarning + > + {formatRelative(lastRun.startedAt, Date.now()) ?? + t('runPage.metadata.justNow')} </time> - <span className="text-ink-2"> - ·{' '} + <span aria-hidden>·</span> + <span> {project.runCount === 1 ? t('projects.item.runCountOne') : t('projects.item.runCount', { count: project.runCount })} </span> </> - ) : ( - <span className="text-ink-2">{t('projects.item.noRuns')}</span> - )} + ) : null} </p> </div> ); diff --git a/apps/web/src/components/projects/project-path.tsx b/apps/web/src/components/projects/project-path.tsx new file mode 100644 index 00000000..5774c279 --- /dev/null +++ b/apps/web/src/components/projects/project-path.tsx @@ -0,0 +1,56 @@ +'use client'; + +import { Button } from '@andrewbehma/glass-ui/button'; +import { Tooltip } from '@andrewbehma/glass-ui/tooltip'; +import { Check, Copy } from 'lucide-react'; +import { useState } from 'react'; +import { t } from '@/i18n'; + +/** + * A project's root folder in the page header: muted, truncated from the left + * so the folder's own name stays in view, the full path in a tooltip, and a + * button that copies it (spec #374, Decision 5). + */ +export function ProjectPath({ path }: { path: string }) { + const [status, setStatus] = useState<'idle' | 'copied' | 'failed'>('idle'); + + async function copy() { + try { + await navigator.clipboard.writeText(path); + setStatus('copied'); + } catch { + setStatus('failed'); + } + } + + return ( + <span className="flex min-w-0 items-center gap-1"> + <Tooltip content={path}> + <span + // biome-ignore lint/a11y/noNoninteractiveTabindex: the tooltip opens on keyboard focus too, so its trigger takes focus + tabIndex={0} + className="min-w-0 truncate rounded-control font-mono text-sm text-ink-2 [direction:rtl]" + > + <bdi dir="ltr">{path}</bdi> + </span> + </Tooltip> + <Button + type="button" + variant="ghost" + size="sm" + aria-label={t('projects.library.copyPath')} + onClick={copy} + > + {status === 'copied' ? ( + <Check aria-hidden size={14} /> + ) : ( + <Copy aria-hidden size={14} /> + )} + </Button> + <span aria-live="polite" className="shrink-0 text-xs text-ink-2"> + {status === 'copied' ? t('projects.library.pathCopied') : null} + {status === 'failed' ? t('projects.library.copyFailed') : null} + </span> + </span> + ); +} diff --git a/apps/web/src/components/projects/run-again.tsx b/apps/web/src/components/projects/run-again.tsx index e0d985b6..6479bb42 100644 --- a/apps/web/src/components/projects/run-again.tsx +++ b/apps/web/src/components/projects/run-again.tsx @@ -2,7 +2,6 @@ import { Banner } from '@andrewbehma/glass-ui/banner'; import { Button } from '@andrewbehma/glass-ui/button'; -import { Card } from '@andrewbehma/glass-ui/card'; import { ConfirmDialog } from '@andrewbehma/glass-ui/confirm-dialog'; import { useEffect, useState } from 'react'; import { t } from '@/i18n'; @@ -14,7 +13,8 @@ import { LaunchStatus } from './launch-status'; * "Run again" on the run page (spec #282): starts the run's own scenario on * the machine that recorded it, through the project's launch, with the * formats the run rendered when the machine takes them (spec #327). - * Only rendered when `canRunAgain` allows it. + * Only rendered when `canRunAgain` allows it; it sits in the run page's + * panel, so it draws no surface of its own. */ export function RunAgain({ projectId, @@ -51,38 +51,35 @@ export function RunAgain({ const showStatus = launch !== null && (active || followed); return ( - <Card pad="lg"> - <h2 className="text-lg font-semibold">{t('runPage.again.title')}</h2> - <div className="mt-3 flex flex-col gap-3"> - {error ? <Banner tone="danger">{t(error)}</Banner> : null} - {showStatus ? ( - <LaunchStatus - projectId={projectId} - launch={launch} - now={now} - cancelling={cancelling} - onCancel={() => void cancel()} - bordered={false} - /> - ) : null} - {active ? null : ( - <div className="flex flex-wrap items-center gap-3"> - <Button - type="button" - variant="solid" - disabled={offline || starting} - onClick={() => setConfirming(true)} - > - {t('runPage.again.button')} - </Button> - {offline ? ( - <span className="text-sm text-ink-2"> - {t('runPage.again.offlineHint')} - </span> - ) : null} - </div> - )} - </div> + <div className="flex flex-col gap-3"> + {error ? <Banner tone="danger">{t(error)}</Banner> : null} + {showStatus ? ( + <LaunchStatus + projectId={projectId} + launch={launch} + now={now} + cancelling={cancelling} + onCancel={() => void cancel()} + bordered={false} + /> + ) : null} + {active ? null : ( + <div className="flex flex-wrap items-center gap-3"> + <Button + type="button" + variant="solid" + disabled={offline || starting} + onClick={() => setConfirming(true)} + > + {t('runPage.again.button')} + </Button> + {offline ? ( + <span className="text-sm text-ink-2"> + {t('runPage.again.offlineHint')} + </span> + ) : null} + </div> + )} <ConfirmDialog open={confirming} onOpenChange={setConfirming} @@ -103,6 +100,6 @@ export function RunAgain({ busy={starting} onConfirm={() => void confirmStart()} /> - </Card> + </div> ); } diff --git a/apps/web/src/components/projects/run-breadcrumbs.tsx b/apps/web/src/components/projects/run-breadcrumbs.tsx deleted file mode 100644 index 7bdd8455..00000000 --- a/apps/web/src/components/projects/run-breadcrumbs.tsx +++ /dev/null @@ -1,41 +0,0 @@ -'use client'; - -import { Breadcrumb } from '@andrewbehma/glass-ui/breadcrumb'; -import Link from 'next/link'; -import { t } from '@/i18n'; - -/** Projects › project › this run. A client component: `link` is a function. */ -export function RunBreadcrumbs({ - projectId, - projectName, - runName, -}: { - projectId: string; - projectName: string; - runName: string; -}) { - return ( - <Breadcrumb - aria-label={t('runPage.breadcrumbs.label')} - overflowLabel={t('runPage.breadcrumbs.overflow')} - link={({ href, className, children }) => ( - <Link href={href} className={className}> - {children} - </Link> - )} - items={[ - { - id: 'projects', - label: t('runPage.breadcrumbs.projects'), - href: '/app/projects', - }, - { - id: 'project', - label: projectName, - href: `/app/projects/${encodeURIComponent(projectId)}`, - }, - { id: 'run', label: runName }, - ]} - /> - ); -} diff --git a/apps/web/src/components/projects/run-details.tsx b/apps/web/src/components/projects/run-details.tsx index f38e721e..7bf8f365 100644 --- a/apps/web/src/components/projects/run-details.tsx +++ b/apps/web/src/components/projects/run-details.tsx @@ -1,10 +1,13 @@ -import { Banner } from '@andrewbehma/glass-ui/banner'; import { Card } from '@andrewbehma/glass-ui/card'; import { KeyValueList } from '@andrewbehma/glass-ui/key-value-list'; +import { SectionHeader } from '@andrewbehma/glass-ui/section-header'; +import { StatusIndicator } from '@/components/status/status-indicator'; import { t } from '@/i18n'; import type { RunDetailView, RunStageName } from '@/lib/api'; import { formatBytes } from '@/lib/format-bytes'; import { formatDuration } from '@/lib/format-duration'; +import { stageStatus } from '@/lib/status'; +import { formatLabel } from './format-choice'; const STAGE_ORDER: RunStageName[] = [ 'readiness', @@ -15,108 +18,84 @@ const STAGE_ORDER: RunStageName[] = [ 'storage', ]; -const FORMAT_LABELS = [ - 'mp4', - 'webm', - 'mp4-vertical', - 'webm-vertical', - 'mp4-square', - 'webm-square', - 'gif', - 'gif-vertical', - 'gif-square', -] as const; - -function formatLabel(format: string): string { - const known = FORMAT_LABELS.find((candidate) => candidate === format); - return known ? t(`runPage.formats.${known}`) : format; -} - -/** The reason a failed run failed; the message is plain text, never markup. */ -export function RunFailureBanner({ - failure, -}: { - failure: RunDetailView['failure']; -}) { +/** + * The reason a failed run failed. The message is plain text, never markup, and + * sits on a solid surface in monospace so it stays readable over the glass + * panel (spec #374, Decision 4). + */ +export function RunFailure({ failure }: { failure: RunDetailView['failure'] }) { if (failure === null) return null; return ( - <Banner tone="danger"> - <p className="font-medium"> + <Card + variant="content" + pad="sm" + role="alert" + className="border-l-4 border-l-danger" + > + <p className="text-sm font-medium text-danger"> {t('runPage.failure.title', { stage: t(`runPage.stages.names.${failure.stage}`), })} </p> - <p className="mt-1 whitespace-pre-wrap break-words">{failure.message}</p> - </Banner> + <pre className="mt-1.5 whitespace-pre-wrap break-words font-mono text-xs text-ink"> + {failure.message} + </pre> + </Card> ); } -/** Stage statuses and rendered files; renders nothing for a run that reported neither. */ -export function RunDetails({ - stages, - renders, -}: Pick<RunDetailView, 'stages' | 'renders'>) { - if (stages === null && renders === null) return null; +/** The run's stage statuses as pills; nothing for a run that reported none. */ +export function RunStages({ stages }: Pick<RunDetailView, 'stages'>) { + if (stages === null) return null; return ( - <Card pad="lg"> - {stages !== null ? ( - <section aria-labelledby="run-stages"> - <h2 id="run-stages" className="text-lg font-semibold"> - {t('runPage.stages.title')} - </h2> - <div className="mt-3"> - <KeyValueList - columns={2} - items={STAGE_ORDER.map((stage) => ({ - key: stage, - label: t(`runPage.stages.names.${stage}`), - value: ( - <span - className={ - stages[stage] === 'failed' - ? 'text-red-600 dark:text-red-400' - : undefined - } - > - {t(`runPage.stages.statuses.${stages[stage]}`)} - </span> - ), - }))} - /> - </div> - </section> - ) : null} - {renders !== null ? ( - <section - aria-labelledby="run-files" - className={stages !== null ? 'mt-6' : undefined} - > - <h2 id="run-files" className="text-lg font-semibold"> - {t('runPage.files.title')} - </h2> - {renders.length === 0 ? ( - <p className="mt-3">{t('runPage.files.none')}</p> - ) : ( - <div className="mt-3"> - <KeyValueList - columns={1} - items={renders.map((render) => ({ - key: render.format, - label: formatLabel(render.format), - value: [ - t('runPage.files.resolution', { - width: render.width, - height: render.height, - }), - formatBytes(render.sizeBytes), - formatDuration(render.durationMs), - ].join(' · '), - }))} - /> - </div> - )} - </section> - ) : null} - </Card> + <section aria-labelledby="run-stages"> + <h2 id="run-stages" className="text-sm font-semibold"> + {t('runPage.stages.title')} + </h2> + <Card variant="content" pad="sm" className="mt-2"> + <ul className="flex flex-col gap-1.5"> + {STAGE_ORDER.map((stage) => ( + <li + key={stage} + className="flex items-center justify-between gap-3 font-mono text-xs" + > + <span>{t(`runPage.stages.names.${stage}`)}</span> + <StatusIndicator status={stageStatus(stages[stage])} /> + </li> + ))} + </ul> + </Card> + </section> + ); +} + +/** The files the run rendered; nothing for a run that reported none. */ +export function RunFiles({ renders }: Pick<RunDetailView, 'renders'>) { + if (renders === null) return null; + return ( + <section aria-labelledby="run-files"> + <SectionHeader title={t('runPage.files.title')} headingId="run-files" /> + <Card pad="md"> + {renders.length === 0 ? ( + <p>{t('runPage.files.none')}</p> + ) : ( + <KeyValueList + columns={1} + items={renders.map((render) => ({ + key: render.format, + label: formatLabel(render.format), + value: [ + t('runPage.files.resolution', { + width: render.width, + height: render.height, + }), + formatBytes(render.sizeBytes), + formatDuration(render.durationMs), + ].join(' · '), + }))} + /> + )} + </Card> + </section> ); } diff --git a/apps/web/src/components/projects/run-status.tsx b/apps/web/src/components/projects/run-status.tsx index 9661f0f0..79203c6d 100644 --- a/apps/web/src/components/projects/run-status.tsx +++ b/apps/web/src/components/projects/run-status.tsx @@ -1,11 +1,7 @@ -import { Badge } from '@andrewbehma/glass-ui/badge'; -import { t } from '@/i18n'; +import { StatusIndicator } from '@/components/status/status-indicator'; import type { ProjectRun } from '@/lib/api'; +import { runStatus } from '@/lib/status'; export function RunStatus({ status }: { status: ProjectRun['status'] }) { - return status === 'passed' ? ( - <Badge tone="ok" label={t('projects.status.passed')} /> - ) : ( - <Badge tone="danger" label={t('projects.status.failed')} /> - ); + return <StatusIndicator status={runStatus(status)} />; } diff --git a/apps/web/src/components/projects/runs-table.tsx b/apps/web/src/components/projects/runs-table.tsx index 3233b945..2c821dd7 100644 --- a/apps/web/src/components/projects/runs-table.tsx +++ b/apps/web/src/components/projects/runs-table.tsx @@ -1,7 +1,6 @@ 'use client'; import { SelectionBar } from '@andrewbehma/glass-ui'; -import { Badge } from '@andrewbehma/glass-ui/badge'; import { Banner } from '@andrewbehma/glass-ui/banner'; import { Button } from '@andrewbehma/glass-ui/button'; import { Checkbox } from '@andrewbehma/glass-ui/checkbox'; @@ -11,9 +10,16 @@ import { SegmentedControl, SegmentedControlItem, } from '@andrewbehma/glass-ui/segmented-control'; +import { + Table, + TableCell, + TableHead, + TableRow, +} from '@andrewbehma/glass-ui/table'; import Link from 'next/link'; import { useRouter } from 'next/navigation'; import { useState } from 'react'; +import { StatusIndicator } from '@/components/status/status-indicator'; import { t } from '@/i18n'; import { deleteProjectRuns, @@ -25,7 +31,9 @@ import { import { formatDate } from '@/lib/format-date'; import { formatDuration } from '@/lib/format-duration'; import { bulkDeleteOutcome, DELETE_RUNS_MAX } from '@/lib/run-delete'; +import { artifactStatus } from '@/lib/status'; import { RunStatus } from './run-status'; +import { CellLabel, stacked } from './stacked-rows'; const FILTERS: { status: RunStatusFilter | undefined; label: string }[] = [ { status: undefined, label: 'projects.library.filter.all' }, @@ -147,42 +155,43 @@ export function RunsTable({ return ( <div className="flex flex-col gap-4"> <div>{filter}</div> - <div className="overflow-x-auto"> - <table className="w-full min-w-[44rem] text-left text-sm"> - <thead className="text-ink-2"> - <tr> - <th scope="col" className="w-10 py-2 pr-2 font-normal"> - <Checkbox - aria-label={t('projects.library.select.all')} - checked={allSelected} - indeterminate={selected.size > 0 && !allSelected} - onChange={toggleAll} - /> - </th> - <th scope="col" className="py-2 pr-4 font-normal"> - {t('projects.library.columns.scenario')} - </th> - <th scope="col" className="py-2 pr-4 font-normal"> - {t('projects.library.columns.status')} - </th> - <th scope="col" className="py-2 pr-4 font-normal"> - {t('projects.library.columns.when')} - </th> - <th scope="col" className="py-2 pr-4 font-normal"> - {t('projects.library.columns.duration')} - </th> - <th scope="col" className="py-2 pr-4 font-normal"> - {t('projects.library.columns.formats')} - </th> - <th scope="col" className="py-2 font-normal"> - {t('projects.library.columns.failedStep')} - </th> - </tr> - </thead> - <tbody> - {runs.map((run) => ( - <tr key={run.id} className="border-t border-current/10"> - <td className="py-3 pr-2 align-top"> + <Table className={stacked.table}> + <TableHead className={stacked.head}> + <tr> + <TableCell head scope="col" className="w-10"> + <Checkbox + aria-label={t('projects.library.select.all')} + checked={allSelected} + indeterminate={selected.size > 0 && !allSelected} + onChange={toggleAll} + /> + </TableCell> + <TableCell head scope="col"> + {t('projects.library.columns.scenario')} + </TableCell> + <TableCell head scope="col"> + {t('projects.library.columns.status')} + </TableCell> + <TableCell head scope="col"> + {t('projects.library.columns.when')} + </TableCell> + <TableCell head scope="col"> + {t('projects.library.columns.duration')} + </TableCell> + <TableCell head scope="col"> + {t('projects.library.columns.formats')} + </TableCell> + <TableCell head scope="col"> + {t('projects.library.columns.failedStep')} + </TableCell> + </tr> + </TableHead> + <tbody className={stacked.body}> + {runs.map((run) => { + const artifacts = artifactStatus(run); + return ( + <TableRow key={run.id} className={stacked.row}> + <TableCell className={stacked.control}> <Checkbox aria-label={t('projects.library.select.row', { name: run.scenarioName, @@ -190,59 +199,62 @@ export function RunsTable({ checked={selected.has(run.id)} onChange={() => toggle(run.id)} /> - </td> - <td className="py-3 pr-4 align-top"> + </TableCell> + <TableCell className={stacked.lead}> <Link href={`/app/projects/${encodeURIComponent(projectId)}/runs/${encodeURIComponent(run.id)}`} - className="break-words font-medium underline" + className="break-words font-medium text-ink underline-offset-2 hover:underline" > {run.scenarioName} </Link> - <div className="break-all text-xs text-ink-2"> + <div className="break-all font-mono text-xs text-ink-2"> {run.scenarioPath} </div> - </td> - <td className="py-3 pr-4 align-top"> + </TableCell> + <TableCell className={stacked.cell}> + <CellLabel>{t('projects.library.columns.status')}</CellLabel> <RunStatus status={run.status} /> - </td> - <td className="py-3 pr-4 align-top"> + </TableCell> + <TableCell className={`${stacked.cell} whitespace-nowrap`}> + <CellLabel>{t('projects.library.columns.when')}</CellLabel> <time dateTime={run.startedAt}> {formatDate(run.startedAt)} </time> - </td> - <td className="py-3 pr-4 align-top"> + </TableCell> + <TableCell className={`${stacked.cell} tabular-nums`}> + <CellLabel> + {t('projects.library.columns.duration')} + </CellLabel> {formatDuration(run.durationMs)} - </td> - <td className="py-3 pr-4 align-top"> - {run.formats.length === 0 ? ( - <span className="text-ink-2"> - {t('projects.library.noFormats')} - </span> - ) : ( - <span>{run.formats.join(', ')}</span> - )} - {run.artifactsDeletedAt === null ? null : ( - <div className="mt-1"> - <Badge - tone="neutral" - size="md" - label={t('projects.library.filesDeleted')} - /> - </div> - )} - </td> - <td className="py-3 align-top"> + </TableCell> + <TableCell className={stacked.cell}> + <CellLabel>{t('projects.library.columns.formats')}</CellLabel> + <span className="flex min-w-0 flex-wrap items-center gap-2"> + {run.formats.length === 0 ? ( + <span className="text-ink-2"> + {t('projects.library.noFormats')} + </span> + ) : ( + <span>{run.formats.join(', ')}</span> + )} + {artifacts ? <StatusIndicator status={artifacts} /> : null} + </span> + </TableCell> + <TableCell className={stacked.cell}> + <CellLabel> + {t('projects.library.columns.failedStep')} + </CellLabel> {run.failedStep === null ? t('projects.library.noFailedStep') : t('projects.library.step', { number: run.failedStep + 1, })} - </td> - </tr> - ))} - </tbody> - </table> - </div> + </TableCell> + </TableRow> + ); + })} + </tbody> + </Table> {failed ? ( <Banner tone="danger">{t('projects.library.loadFailed')}</Banner> ) : null} diff --git a/apps/web/src/components/projects/stacked-rows.tsx b/apps/web/src/components/projects/stacked-rows.tsx new file mode 100644 index 00000000..8f9fe8c7 --- /dev/null +++ b/apps/web/src/components/projects/stacked-rows.tsx @@ -0,0 +1,29 @@ +import type { ReactNode } from 'react'; + +/** + * Classes that turn a Glass UI table into stacked rows below the `md` + * breakpoint (spec #374, Decision 3): the header hides, every row becomes a + * block and every cell a labelled line, so a narrow screen never scrolls + * sideways. One DOM for both layouts, so a locator finds each cell once. + */ +export const stacked = { + table: 'block md:table', + head: 'hidden md:table-header-group', + body: 'block md:table-row-group', + row: 'flex flex-wrap items-start gap-x-3 gap-y-1.5 px-1 py-3 md:table-row md:p-0', + /** A labelled line on its own; a normal cell from `md` up. */ + cell: 'flex w-full min-w-0 items-baseline gap-3 p-0 md:table-cell md:w-auto md:px-3 md:py-2.5', + /** The row's title on a narrow screen: it takes what the line has left. */ + lead: 'block min-w-0 flex-1 p-0 md:table-cell md:px-3 md:py-2.5', + /** A control that sits before the title on a narrow screen. */ + control: 'block shrink-0 p-0 md:table-cell md:w-10 md:px-3 md:py-2.5', +} as const; + +/** The column name before a cell's value, shown only while rows are stacked. */ +export function CellLabel({ children }: { children: ReactNode }) { + return ( + <span className="w-24 shrink-0 text-xs text-ink-2 md:hidden"> + {children} + </span> + ); +} diff --git a/apps/web/src/components/projects/start-run.tsx b/apps/web/src/components/projects/start-run.tsx index 89c0651a..8593613e 100644 --- a/apps/web/src/components/projects/start-run.tsx +++ b/apps/web/src/components/projects/start-run.tsx @@ -5,6 +5,7 @@ import { Button } from '@andrewbehma/glass-ui/button'; import { Card } from '@andrewbehma/glass-ui/card'; import { ConfirmDialog } from '@andrewbehma/glass-ui/confirm-dialog'; import { EmptyState } from '@andrewbehma/glass-ui/empty-state'; +import { SectionHeader } from '@andrewbehma/glass-ui/section-header'; import { Select } from '@andrewbehma/glass-ui/select'; import { Spinner } from '@andrewbehma/glass-ui/spinner'; import { useCallback, useEffect, useState } from 'react'; @@ -17,7 +18,7 @@ import { FormatChoice, formatList } from './format-choice'; import { LaunchStatus } from './launch-status'; /** - * The "Run a scenario" card: pick a scenario of the project's machine, start + * The "Run a scenario" section: pick a scenario of the project's machine, start * it, follow it and cancel it (spec #249). With no folder or no machine it * only says so and makes no request. */ @@ -82,14 +83,19 @@ export function StartRun({ if (!enabled) { return ( - <Card pad="lg"> - <h2 className="text-lg font-semibold">{t('projects.launch.title')}</h2> - <p className="mt-2 text-sm text-ink-2"> - {rootPath === null - ? t('projects.launch.unbound') - : t('projects.launch.removed')} - </p> - </Card> + <section aria-labelledby="start-run" className="flex flex-col gap-3"> + <SectionHeader + title={t('projects.launch.title')} + headingId="start-run" + /> + <Card pad="md"> + <p className="text-sm text-ink-2"> + {rootPath === null + ? t('projects.launch.unbound') + : t('projects.launch.removed')} + </p> + </Card> + </section> ); } @@ -98,9 +104,9 @@ export function StartRun({ const locked = active || starting; return ( - <Card pad="lg"> - <h2 className="text-lg font-semibold">{t('projects.launch.title')}</h2> - <div className="mt-3 flex flex-col gap-3"> + <section aria-labelledby="start-run" className="flex flex-col gap-3"> + <SectionHeader title={t('projects.launch.title')} headingId="start-run" /> + <Card pad="md" className="flex flex-col gap-3"> {error ? <Banner tone="danger">{t(error)}</Banner> : null} {loading && list === null ? ( <Spinner size="sm" label={t('projects.launch.loading')} /> @@ -175,7 +181,7 @@ export function StartRun({ onCancel={() => void cancel()} /> ) : null} - </div> + </Card> <ConfirmDialog open={confirming} onOpenChange={setConfirming} @@ -196,6 +202,6 @@ export function StartRun({ busy={starting} onConfirm={() => void confirmStart()} /> - </Card> + </section> ); } diff --git a/apps/web/src/components/status/status-indicator.tsx b/apps/web/src/components/status/status-indicator.tsx new file mode 100644 index 00000000..efeddf01 --- /dev/null +++ b/apps/web/src/components/status/status-indicator.tsx @@ -0,0 +1,27 @@ +import { StatusPill } from '@andrewbehma/glass-ui/status-pill'; +import { t } from '@/i18n'; +import { PILL_STATUS, type StatusView } from '@/lib/status'; + +/** + * A status as a pill: the dot in the kind's tone and its text label, the same + * on every page that shows the state (spec #374, Decision 2). + */ +export function StatusIndicator({ + status, + size = 'sm', + className, +}: { + status: StatusView; + size?: 'sm' | 'md'; + className?: string; +}) { + return ( + <StatusPill + status={PILL_STATUS[status.kind]} + label={t(status.label)} + size={size} + className={className} + data-status-kind={status.kind} + /> + ); +} diff --git a/apps/web/src/i18n/en.ts b/apps/web/src/i18n/en.ts index 27b8858f..a86aba8f 100644 --- a/apps/web/src/i18n/en.ts +++ b/apps/web/src/i18n/en.ts @@ -144,6 +144,10 @@ export const en = { }, machines: { title: 'Machines', + description: + 'The computers paired with your account. A machine records runs while it is online.', + paired: 'Paired {date}', + lastUsed: 'Last used {date}', empty: { title: 'No machines paired yet', body: 'Run this in a terminal on the machine you want to pair:', @@ -154,13 +158,11 @@ export const en = { name: 'Name', os: 'System', cliVersion: 'CLI', - paired: 'Paired', status: 'Status', lastSeen: 'Last seen', - lastUsed: 'Last used', actions: 'Actions', }, - neverUsed: 'Never', + neverUsed: 'Never used', status: { online: 'Online', offline: 'Offline', @@ -205,10 +207,13 @@ export const en = { }, projects: { title: 'Projects', + description: + 'Each project is a folder on a paired machine and the runs recorded there.', loadFailed: 'We could not load your projects. Try again in a moment.', empty: { title: 'No projects yet', body: 'A project appears when a paired machine runs a scenario in a folder. You can also create one here and bind it to a folder later.', + docs: 'Read how to record a first run', }, create: { label: 'New project', @@ -219,17 +224,9 @@ export const en = { item: { noFolder: 'No folder bound yet', machineRemoved: 'Machine removed', - machine: 'Machine', - path: 'Folder', - lastRun: 'Last run', noRuns: 'No runs yet', runCount: '{count} runs', runCountOne: '1 run', - open: 'Open library', - }, - status: { - passed: 'Passed', - failed: 'Failed', }, rename: { action: 'Rename', @@ -264,8 +261,10 @@ export const en = { }, library: { title: '{name}', - machine: 'Machine', - path: 'Folder', + copyPath: 'Copy the folder path', + pathCopied: 'Copied', + copyFailed: 'Could not copy', + runsTitle: 'Runs', empty: { title: 'No runs yet', body: 'Runs show up here after demoflow run on a paired machine in this folder.', @@ -289,7 +288,6 @@ export const en = { failedStep: 'Failed step', }, noFormats: 'None', - filesDeleted: 'Files deleted', noFailedStep: '—', step: 'Step {number}', loadMore: 'Load more', @@ -352,17 +350,7 @@ export const en = { cancelling: 'Cancelling…', openRun: 'Open the run', noReport: 'The run finished, but its report did not reach the site.', - state: { - starting: 'Starting', - running: 'Running', - cancelling: 'Cancelling', - passed: 'Passed', - failed: 'Failed', - cancelled: 'Cancelled', - timedOut: 'Timed out (15 min)', - lostLabel: 'Lost contact', - lost: 'Lost contact. The run may still finish and appear in the library.', - }, + lost: 'Lost contact. The run may still finish and appear in the library.', errors: { runnerOffline: 'The machine is offline. Start the runner on it (demoflow runner start) and try again.', @@ -391,8 +379,9 @@ export const en = { }, runPage: { title: 'Run of {name}', + panel: 'Run details', + actions: 'Actions', again: { - title: 'Run this scenario again', button: 'Run again', offlineHint: 'The machine is offline.', }, @@ -406,11 +395,6 @@ export const en = { confirm: 'Delete run', cancel: 'Keep', }, - breadcrumbs: { - label: 'Path', - overflow: 'Show the path', - projects: 'Projects', - }, metadata: { scenario: 'Scenario', path: 'Path', @@ -420,6 +404,8 @@ export const en = { failedStep: 'Failed step', machine: 'Machine', cliVersion: 'CLI version', + formats: 'Formats', + noFormats: 'None', justNow: 'just now', noFailedStep: '—', step: 'Step {number}', @@ -449,13 +435,6 @@ export const en = { rendering: 'Rendering', storage: 'Storage', }, - statuses: { - passed: 'Passed', - failed: 'Failed', - skipped: 'Skipped', - pending: 'Pending', - running: 'Running', - }, }, files: { title: 'Files', @@ -520,6 +499,25 @@ export const en = { body: 'Deleted from the machine on {date}.', }, }, + // One status vocabulary for every /app page (spec #374, lib/status.ts). + status: { + passed: 'Passed', + failed: 'Failed', + neverRun: 'Never run', + starting: 'Starting', + running: 'Running', + cancelling: 'Cancelling', + cancelled: 'Cancelled', + timedOut: 'Timed out (15 min)', + lost: 'Lost contact', + pending: 'Pending', + skipped: 'Skipped', + filesDeleted: 'Files deleted', + noVideo: 'No video', + machineRemoved: 'Machine removed', + offline: 'Offline', + online: 'Online', + }, meta: { title: 'DemoFlow', }, diff --git a/apps/web/src/lib/status.test.mjs b/apps/web/src/lib/status.test.mjs new file mode 100644 index 00000000..4a325957 --- /dev/null +++ b/apps/web/src/lib/status.test.mjs @@ -0,0 +1,121 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { + artifactStatus, + lastRunStatus, + launchStatus, + machineStatus, + PILL_STATUS, + runStatus, + stageStatus, + videoStatus, +} from './status.ts'; + +test('every kind is drawn with its own Glass UI pill state', () => { + assert.deepEqual(PILL_STATUS, { + running: 'running', + passed: 'done', + failed: 'error', + unavailable: 'paused', + idle: 'idle', + }); + assert.equal(new Set(Object.values(PILL_STATUS)).size, 5); +}); + +test('a run is passed or failed', () => { + assert.deepEqual(runStatus('passed'), { + kind: 'passed', + label: 'status.passed', + }); + assert.deepEqual(runStatus('failed'), { + kind: 'failed', + label: 'status.failed', + }); +}); + +test('a project without a last run has never run', () => { + assert.deepEqual(lastRunStatus(null), { + kind: 'idle', + label: 'status.neverRun', + }); + assert.deepEqual(lastRunStatus({ status: 'failed' }), runStatus('failed')); + assert.deepEqual(lastRunStatus({ status: 'passed' }), runStatus('passed')); +}); + +test('every launch state maps to a kind and its own label', () => { + const cases = { + starting: ['running', 'status.starting'], + running: ['running', 'status.running'], + cancelling: ['running', 'status.cancelling'], + passed: ['passed', 'status.passed'], + failed: ['failed', 'status.failed'], + 'timed-out': ['failed', 'status.timedOut'], + cancelled: ['idle', 'status.cancelled'], + lost: ['unavailable', 'status.lost'], + }; + for (const [state, [kind, label]] of Object.entries(cases)) { + assert.deepEqual(launchStatus(state), { kind, label }, state); + } +}); + +test('a finished launch reads the same as the run it produced', () => { + assert.deepEqual(launchStatus('passed'), runStatus('passed')); + assert.deepEqual(launchStatus('failed'), runStatus('failed')); +}); + +test('every stage status maps to a kind', () => { + const cases = { + pending: ['idle', 'status.pending'], + running: ['running', 'status.running'], + passed: ['passed', 'status.passed'], + failed: ['failed', 'status.failed'], + skipped: ['idle', 'status.skipped'], + }; + for (const [state, [kind, label]] of Object.entries(cases)) { + assert.deepEqual(stageStatus(state), { kind, label }, state); + } +}); + +test('an online machine is a success pill, an offline one is unavailable', () => { + assert.deepEqual(machineStatus(true), { + kind: 'passed', + label: 'status.online', + }); + assert.deepEqual(machineStatus(false), { + kind: 'unavailable', + label: 'status.offline', + }); + assert.notEqual(machineStatus(true).kind, 'running'); +}); + +test('deleted files are unavailable, present files show nothing', () => { + assert.equal(artifactStatus({ artifactsDeletedAt: null }), null); + assert.deepEqual( + artifactStatus({ artifactsDeletedAt: '2026-10-01T00:00:00Z' }), + { + kind: 'unavailable', + label: 'status.filesDeleted', + }, + ); +}); + +test('the video says why it cannot play, or nothing when it can', () => { + const run = { artifactsDeletedAt: null, formats: ['mp4'] }; + assert.equal(videoStatus(run, { online: true }), null); + assert.deepEqual(videoStatus(run, { online: false }), machineStatus(false)); + assert.deepEqual(videoStatus(run, null), { + kind: 'unavailable', + label: 'status.machineRemoved', + }); + assert.deepEqual(videoStatus({ ...run, formats: [] }, { online: true }), { + kind: 'idle', + label: 'status.noVideo', + }); + assert.deepEqual( + videoStatus( + { artifactsDeletedAt: '2026-10-01T00:00:00Z', formats: ['mp4'] }, + { online: false }, + ), + { kind: 'unavailable', label: 'status.filesDeleted' }, + ); +}); diff --git a/apps/web/src/lib/status.ts b/apps/web/src/lib/status.ts new file mode 100644 index 00000000..6f2f41b3 --- /dev/null +++ b/apps/web/src/lib/status.ts @@ -0,0 +1,131 @@ +// One status vocabulary for every /app page (spec #374, Decision 2). Pure, so +// `node --test` runs it as it is: no React, no Node APIs, type imports only. + +import type { LaunchState, ProjectRun, RunDetail, RunStageStatus } from './api'; + +/** The five kinds a page can show; the pill's tone follows the kind. */ +export type StatusKind = + | 'running' + | 'passed' + | 'failed' + | 'unavailable' + | 'idle'; + +/** The Glass UI `StatusPill` state each kind is drawn with. */ +export const PILL_STATUS = { + running: 'running', + passed: 'done', + failed: 'error', + unavailable: 'paused', + idle: 'idle', +} as const satisfies Record<StatusKind, string>; + +export type StatusLabel = + | 'status.passed' + | 'status.failed' + | 'status.neverRun' + | 'status.starting' + | 'status.running' + | 'status.cancelling' + | 'status.cancelled' + | 'status.timedOut' + | 'status.lost' + | 'status.pending' + | 'status.skipped' + | 'status.filesDeleted' + | 'status.noVideo' + | 'status.machineRemoved' + | 'status.offline' + | 'status.online'; + +/** A kind and the dictionary key of its label: colour is never the only signal. */ +export interface StatusView { + kind: StatusKind; + label: StatusLabel; +} + +/** A finished run's own result. */ +export function runStatus(status: ProjectRun['status']): StatusView { + return status === 'passed' + ? { kind: 'passed', label: 'status.passed' } + : { kind: 'failed', label: 'status.failed' }; +} + +/** A project's last run; a project without one has never run. */ +export function lastRunStatus( + lastRun: Pick<ProjectRun, 'status'> | null, +): StatusView { + return lastRun === null + ? { kind: 'idle', label: 'status.neverRun' } + : runStatus(lastRun.status); +} + +const LAUNCH: Record<LaunchState, StatusView> = { + starting: { kind: 'running', label: 'status.starting' }, + running: { kind: 'running', label: 'status.running' }, + cancelling: { kind: 'running', label: 'status.cancelling' }, + passed: { kind: 'passed', label: 'status.passed' }, + failed: { kind: 'failed', label: 'status.failed' }, + 'timed-out': { kind: 'failed', label: 'status.timedOut' }, + cancelled: { kind: 'idle', label: 'status.cancelled' }, + lost: { kind: 'unavailable', label: 'status.lost' }, +}; + +/** A run started from the website, while it goes and once it ends. */ +export function launchStatus(state: LaunchState): StatusView { + return LAUNCH[state]; +} + +const STAGE: Record<RunStageStatus, StatusView> = { + pending: { kind: 'idle', label: 'status.pending' }, + running: { kind: 'running', label: 'status.running' }, + passed: { kind: 'passed', label: 'status.passed' }, + failed: { kind: 'failed', label: 'status.failed' }, + skipped: { kind: 'idle', label: 'status.skipped' }, +}; + +/** One stage of a run's report. */ +export function stageStatus(status: RunStageStatus): StatusView { + return STAGE[status]; +} + +/** + * A paired machine. Online uses the success tone, not `running`, which means a + * run in progress (Decision 7); offline is `unavailable`. + */ +export function machineStatus(online: boolean): StatusView { + return online + ? { kind: 'passed', label: 'status.online' } + : { kind: 'unavailable', label: 'status.offline' }; +} + +/** A project's or a run's machine that was removed from the account. */ +export const MACHINE_REMOVED: StatusView = { + kind: 'unavailable', + label: 'status.machineRemoved', +}; + +/** A run whose files the machine deleted; null while they are there. */ +export function artifactStatus( + run: Pick<ProjectRun, 'artifactsDeletedAt'>, +): StatusView | null { + return run.artifactsDeletedAt === null + ? null + : { kind: 'unavailable', label: 'status.filesDeleted' }; +} + +/** + * Why a run's video cannot be played from the site, or null when it can: its + * files were deleted, it rendered none, its machine was removed or is offline. + */ +export function videoStatus( + run: Pick<ProjectRun, 'artifactsDeletedAt' | 'formats'>, + machine: Pick<NonNullable<RunDetail['machine']>, 'online'> | null, +): StatusView | null { + const artifacts = artifactStatus(run); + if (artifacts) return artifacts; + if (run.formats.length === 0) + return { kind: 'idle', label: 'status.noVideo' }; + if (machine === null) return MACHINE_REMOVED; + return machine.online ? null : machineStatus(false); +} From 7012a1d93a2cb7130b45de6af15fa6b2fb0100ba Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 16:37:10 +0100 Subject: [PATCH 40/71] feat(web): public share page /s/[token] with player, chapters, download and password The page a share link opens, for a viewer with no account (spec #351): title, description, the video through the player adapter with its poster, chapters that seek it, Download and a Made with DemoFlow badge; a GIF share is an image. A protected share shows only the password form; expired, unavailable and unknown links have their own pages. Every state is noindex, and unfurlers get the title and poster of an open share. The VideoPlayer contract gains an optional poster and onControls (seek and play), through Luna's PlayerHandle and the native <video>. --- apps/web/package.json | 2 +- apps/web/src/app/s/[token]/not-found.tsx | 12 ++ apps/web/src/app/s/[token]/page.tsx | 137 +++++++++++++ .../components/player/luna-video-player.tsx | 57 +++++- .../components/player/native-video-player.tsx | 24 ++- .../web/src/components/player/video-player.ts | 15 +- .../src/components/share-page/chapters.tsx | 48 +++++ .../components/share-page/made-with-badge.tsx | 23 +++ .../components/share-page/share-notice.tsx | 28 +++ .../src/components/share-page/share-view.tsx | 90 +++++++++ .../src/components/share-page/unlock-form.tsx | 62 ++++++ apps/web/src/i18n/en.ts | 38 ++++ apps/web/src/lib/session.ts | 3 +- apps/web/src/lib/share-page.test.mjs | 106 ++++++++++ apps/web/src/lib/share-page.ts | 183 ++++++++++++++++++ 15 files changed, 816 insertions(+), 12 deletions(-) create mode 100644 apps/web/src/app/s/[token]/not-found.tsx create mode 100644 apps/web/src/app/s/[token]/page.tsx create mode 100644 apps/web/src/components/share-page/chapters.tsx create mode 100644 apps/web/src/components/share-page/made-with-badge.tsx create mode 100644 apps/web/src/components/share-page/share-notice.tsx create mode 100644 apps/web/src/components/share-page/share-view.tsx create mode 100644 apps/web/src/components/share-page/unlock-form.tsx create mode 100644 apps/web/src/lib/share-page.test.mjs create mode 100644 apps/web/src/lib/share-page.ts diff --git a/apps/web/package.json b/apps/web/package.json index c5fafb6b..b81c3de8 100644 --- a/apps/web/package.json +++ b/apps/web/package.json @@ -7,7 +7,7 @@ "start": "next start -p 3670", "start:dev": "node scripts/dev.mjs", "lint": "biome lint src", - "test": "node --test src/lib/docs-nav.test.mjs src/lib/playback.test.mjs src/lib/launch.test.mjs src/lib/format-bytes.test.mjs src/lib/run-delete.test.mjs src/lib/player-choice.test.mjs src/lib/nav.test.mjs src/lib/crumbs.test.mjs src/lib/theme.test.mjs src/lib/overview-stats.test.mjs" + "test": "node --test src/lib/docs-nav.test.mjs src/lib/playback.test.mjs src/lib/launch.test.mjs src/lib/format-bytes.test.mjs src/lib/run-delete.test.mjs src/lib/player-choice.test.mjs src/lib/nav.test.mjs src/lib/crumbs.test.mjs src/lib/theme.test.mjs src/lib/overview-stats.test.mjs src/lib/share-page.test.mjs" }, "dependencies": { "@andrewbehma/glass-ui": "0.37.0", diff --git a/apps/web/src/app/s/[token]/not-found.tsx b/apps/web/src/app/s/[token]/not-found.tsx new file mode 100644 index 00000000..8df2c904 --- /dev/null +++ b/apps/web/src/app/s/[token]/not-found.tsx @@ -0,0 +1,12 @@ +import { ShareNotice } from '@/components/share-page/share-notice'; +import { t } from '@/i18n'; + +/** An unknown token (spec #351, Decision 1). Next answers 404 and `noindex`. */ +export default function ShareNotFound() { + return ( + <ShareNotice + title={t('sharePage.notFound.title')} + body={t('sharePage.notFound.body')} + /> + ); +} diff --git a/apps/web/src/app/s/[token]/page.tsx b/apps/web/src/app/s/[token]/page.tsx new file mode 100644 index 00000000..4d788211 --- /dev/null +++ b/apps/web/src/app/s/[token]/page.tsx @@ -0,0 +1,137 @@ +import type { Metadata } from 'next'; +import { cookies } from 'next/headers'; +import { notFound } from 'next/navigation'; +import { cache } from 'react'; +import { ShareNotice } from '@/components/share-page/share-notice'; +import { ShareView } from '@/components/share-page/share-view'; +import { UnlockForm } from '@/components/share-page/unlock-form'; +import { t } from '@/i18n'; +import { apiUrl } from '@/lib/session'; +import { fetchSharePage, unfurlsVideo } from '@/lib/share-page'; + +// Every request carries the viewer's cookies to the API (an unlock opens a +// protected share), so nothing here is rendered ahead of time. +export const dynamic = 'force-dynamic'; + +const NOINDEX: Metadata['robots'] = { index: false, follow: false }; + +/** + * One `GET /s/:token` per request: the metadata and the page share it, so a + * page load counts one view (spec #348, Decision 7). + */ +const getShare = cache(async (token: string) => { + const cookie = (await cookies()).toString(); + return { + cookie, + state: await fetchSharePage(token, { baseUrl: apiUrl(), cookie }), + }; +}); + +/** + * Unfurl metadata (spec #351, Decision 5). A locked share says nothing of + * itself (ADR-0019 §2); every state is `noindex`. + */ +export async function generateMetadata({ + params, +}: { + params: Promise<{ token: string }>; +}): Promise<Metadata> { + const { token } = await params; + const { state, cookie } = await getShare(token); + switch (state.kind) { + case 'share': { + const { share } = state; + const description = share.description ?? undefined; + return { + title: share.title, + description, + robots: NOINDEX, + openGraph: { + title: share.title, + description, + type: 'video.other', + images: [{ url: share.posterUrl }], + videos: unfurlsVideo(share, cookie) + ? [ + { + url: share.fileUrl, + type: 'video/mp4', + width: share.width ?? undefined, + height: share.height ?? undefined, + }, + ] + : undefined, + }, + twitter: { + card: 'summary_large_image', + title: share.title, + description, + images: [share.posterUrl], + }, + }; + } + case 'expired': + return { title: t('sharePage.expired.title'), robots: NOINDEX }; + case 'unavailable': + return { title: t('sharePage.unavailable.title'), robots: NOINDEX }; + default: + return { + title: t('sharePage.meta.locked'), + robots: NOINDEX, + openGraph: { title: t('sharePage.meta.locked') }, + }; + } +} + +/** + * The page a share link opens, for a viewer with no account (spec #351). No + * app header and no sign-in prompt; the badge is the way to the landing page. + * Expired and unavailable links answer 200: an App Router page cannot set 410. + */ +export default async function SharePage({ + params, +}: { + params: Promise<{ token: string }>; +}) { + const { token } = await params; + const { state } = await getShare(token); + if (state.kind === 'not-found') notFound(); + switch (state.kind) { + case 'share': + return ( + <main className="mx-auto w-full max-w-5xl p-4 sm:p-6 lg:py-10"> + <ShareView share={state.share} /> + </main> + ); + case 'locked': + return ( + <ShareNotice + title={t('sharePage.locked.title')} + body={t('sharePage.locked.body')} + > + <UnlockForm token={token} /> + </ShareNotice> + ); + case 'expired': + return ( + <ShareNotice + title={t('sharePage.expired.title')} + body={t('sharePage.expired.body')} + /> + ); + case 'unavailable': + return ( + <ShareNotice + title={t('sharePage.unavailable.title')} + body={t('sharePage.unavailable.body')} + /> + ); + case 'error': + return ( + <ShareNotice + title={t('sharePage.failed.title')} + body={t('sharePage.failed.body')} + /> + ); + } +} diff --git a/apps/web/src/components/player/luna-video-player.tsx b/apps/web/src/components/player/luna-video-player.tsx index 941a5525..e3f7dffe 100644 --- a/apps/web/src/components/player/luna-video-player.tsx +++ b/apps/web/src/components/player/luna-video-player.tsx @@ -1,8 +1,8 @@ 'use client'; -import type { PlayerProps } from 'luna-player/player'; -import type { ComponentType } from 'react'; -import { lazy, Suspense, useState } from 'react'; +import type { PlayerHandle, PlayerProps } from 'luna-player/player'; +import type { ForwardRefExoticComponent, RefAttributes } from 'react'; +import { lazy, Suspense, useCallback, useState } from 'react'; import { t } from '@/i18n'; import type { PlayerShape } from '@/lib/playback'; import { @@ -61,12 +61,33 @@ const labels: PlayerProps['labels'] = { }; /** Luna's `<Player>` behind the `VideoPlayer` contract, in the native box. */ -function adapt(Player: ComponentType<PlayerProps>): VideoPlayer { - return function Luna({ src, shape, onError }: VideoPlayerProps) { +function adapt( + Player: ForwardRefExoticComponent<PlayerProps & RefAttributes<PlayerHandle>>, +): VideoPlayer { + return function Luna({ + src, + shape, + poster, + onError, + onControls, + }: VideoPlayerProps) { + // Luna's handle seeks in seconds (`luna-player` 0.2.0, `PlayerHandle`). + const ref = useCallback( + (handle: PlayerHandle | null) => { + if (handle === null || onControls === undefined) return; + onControls({ + seek: (ms) => handle.seekTo(ms / 1000), + play: () => handle.play(), + }); + }, + [onControls], + ); return ( <div className={boxClass(shape)}> <Player + ref={ref} src={src} + poster={poster} aspectRatio={lunaAspectRatio(shape)} labels={labels} storage={null} @@ -91,7 +112,13 @@ const LazyLuna = lazy(async () => ({ * when Luna's chunk does not load, or Luna gives up on `src`, the native one * plays the same stream; only its failure reaches the page's `onError`. */ -export function LunaVideoPlayer({ src, shape, onError }: VideoPlayerProps) { +export function LunaVideoPlayer({ + src, + shape, + poster, + onError, + onControls, +}: VideoPlayerProps) { const [current, setCurrent] = useState<PlayerKind>('luna'); function handleError() { @@ -100,13 +127,27 @@ export function LunaVideoPlayer({ src, shape, onError }: VideoPlayerProps) { } if (current === 'native') { - return <NativeVideoPlayer src={src} shape={shape} onError={handleError} />; + return ( + <NativeVideoPlayer + src={src} + shape={shape} + poster={poster} + onError={handleError} + onControls={onControls} + /> + ); } return ( <Suspense fallback={<div className={`${boxClass(shape)} ${ASPECT[shape]}`} />} > - <LazyLuna src={src} shape={shape} onError={handleError} /> + <LazyLuna + src={src} + shape={shape} + poster={poster} + onError={handleError} + onControls={onControls} + /> </Suspense> ); } diff --git a/apps/web/src/components/player/native-video-player.tsx b/apps/web/src/components/player/native-video-player.tsx index 4d6fc7e3..65999f80 100644 --- a/apps/web/src/components/player/native-video-player.tsx +++ b/apps/web/src/components/player/native-video-player.tsx @@ -1,5 +1,6 @@ 'use client'; +import { useCallback } from 'react'; import type { VideoPlayerProps } from './video-player'; const BOX = { @@ -9,11 +10,32 @@ const BOX = { } as const; /** The browser's own `<video>`; the `VideoPlayer` implementation in use. */ -export function NativeVideoPlayer({ src, shape, onError }: VideoPlayerProps) { +export function NativeVideoPlayer({ + src, + shape, + poster, + onError, + onControls, +}: VideoPlayerProps) { + const ref = useCallback( + (video: HTMLVideoElement | null) => { + if (video === null || onControls === undefined) return; + onControls({ + seek: (ms) => { + video.currentTime = ms / 1000; + }, + // A play the browser refuses (autoplay policy) is no error. + play: () => void video.play().catch(() => undefined), + }); + }, + [onControls], + ); return ( <video key={src} + ref={ref} src={src} + poster={poster} controls preload="metadata" playsInline diff --git a/apps/web/src/components/player/video-player.ts b/apps/web/src/components/player/video-player.ts index c23a4b80..d64f8c75 100644 --- a/apps/web/src/components/player/video-player.ts +++ b/apps/web/src/components/player/video-player.ts @@ -2,13 +2,26 @@ import type { ComponentType } from 'react'; import type { PlayerShape } from '@/lib/playback'; import { LunaVideoPlayer } from './luna-video-player'; -/** What the run page needs from a player, whichever implementation plays. */ +/** What a page drives the playhead with, once the player can seek. */ +export interface VideoPlayerControls { + seek(ms: number): void; + play(): void; +} + +/** What a page needs from a player, whichever implementation plays. */ export interface VideoPlayerProps { src: string; /** The picture's aspect ratio: 16:9, 9:16 or 1:1. */ shape: PlayerShape; + /** Shown before playback starts. */ + poster?: string; /** The player could not load or play `src`. */ onError(): void; + /** + * Called once the player can seek, and again when another implementation + * takes over (the native fallback). The share page's chapters use it. + */ + onControls?(controls: VideoPlayerControls): void; } export type VideoPlayer = ComponentType<VideoPlayerProps>; diff --git a/apps/web/src/components/share-page/chapters.tsx b/apps/web/src/components/share-page/chapters.tsx new file mode 100644 index 00000000..58c25e7b --- /dev/null +++ b/apps/web/src/components/share-page/chapters.tsx @@ -0,0 +1,48 @@ +'use client'; + +import { t } from '@/i18n'; +import { chapterTime, type ShareChapter } from '@/lib/share-page'; + +/** + * The scenario's scenes as `mm:ss title` buttons; a click seeks the video to + * the scene and plays (spec #351, Decision 3). No chapters, no list. + */ +export function Chapters({ + chapters, + onSeek, +}: { + chapters: ShareChapter[]; + onSeek(ms: number): void; +}) { + if (chapters.length === 0) return null; + return ( + <nav aria-labelledby="share-chapters"> + <h2 id="share-chapters" className="text-sm font-semibold text-ink-2"> + {t('sharePage.chapters.title')} + </h2> + <ol className="mt-2 flex flex-col"> + {chapters.map((chapter) => { + const time = chapterTime(chapter.atMs); + return ( + <li key={`${chapter.atMs}-${chapter.title}`}> + <button + type="button" + aria-label={t('sharePage.chapters.seek', { + time, + title: chapter.title, + })} + onClick={() => onSeek(chapter.atMs)} + className="flex w-full items-baseline gap-3 rounded-control px-2 py-1.5 text-left text-sm hover:bg-hover" + > + <span className="shrink-0 font-mono tabular-nums text-ink-2"> + {time} + </span> + <span className="break-words">{chapter.title}</span> + </button> + </li> + ); + })} + </ol> + </nav> + ); +} diff --git a/apps/web/src/components/share-page/made-with-badge.tsx b/apps/web/src/components/share-page/made-with-badge.tsx new file mode 100644 index 00000000..061e56ac --- /dev/null +++ b/apps/web/src/components/share-page/made-with-badge.tsx @@ -0,0 +1,23 @@ +import { buttonClassName } from '@andrewbehma/glass-ui/button'; +import { Logomark } from '@/components/brand/logo'; +import { t } from '@/i18n'; + +/** + * "Made with DemoFlow": the share page's only way to the landing page, small + * and below the player, never over the video (spec #351, Decision 2). + */ +export function MadeWithBadge() { + return ( + <a + href="/" + className={buttonClassName({ + variant: 'glass', + size: 'sm', + className: 'gap-2', + })} + > + <Logomark size={16} /> + {t('sharePage.madeWith')} + </a> + ); +} diff --git a/apps/web/src/components/share-page/share-notice.tsx b/apps/web/src/components/share-page/share-notice.tsx new file mode 100644 index 00000000..5abc2742 --- /dev/null +++ b/apps/web/src/components/share-page/share-notice.tsx @@ -0,0 +1,28 @@ +import { Card } from '@andrewbehma/glass-ui/card'; +import type { ReactNode } from 'react'; +import { MadeWithBadge } from './made-with-badge'; + +/** + * A share page that shows no video: locked, expired, unavailable, unknown or + * failed. One readable card, centred, with the badge under it. + */ +export function ShareNotice({ + title, + body, + children, +}: { + title: string; + body: string; + children?: ReactNode; +}) { + return ( + <main className="flex min-h-screen flex-col items-center justify-center gap-4 p-4 sm:p-6"> + <Card pad="lg" className="w-full max-w-md"> + <h1 className="text-2xl font-semibold">{title}</h1> + <p className="mt-2 text-ink-2">{body}</p> + {children ? <div className="mt-4">{children}</div> : null} + </Card> + <MadeWithBadge /> + </main> + ); +} diff --git a/apps/web/src/components/share-page/share-view.tsx b/apps/web/src/components/share-page/share-view.tsx new file mode 100644 index 00000000..b7d5ecf9 --- /dev/null +++ b/apps/web/src/components/share-page/share-view.tsx @@ -0,0 +1,90 @@ +'use client'; + +import { Banner } from '@andrewbehma/glass-ui/banner'; +import { buttonClassName } from '@andrewbehma/glass-ui/button'; +import { Card } from '@andrewbehma/glass-ui/card'; +import { useCallback, useRef, useState } from 'react'; +import { + choosePlayer, + type VideoPlayerControls, +} from '@/components/player/video-player'; +import { t } from '@/i18n'; +import { type ShareData, samePath, shareShape } from '@/lib/share-page'; +import { Chapters } from './chapters'; +import { MadeWithBadge } from './made-with-badge'; + +/** + * An open share (spec #351, Decision 2): the title and description, the video + * (or the GIF), its chapters, Download and the badge. + */ +export function ShareView({ share }: { share: ShareData }) { + const controls = useRef<VideoPlayerControls | null>(null); + // A chapter clicked before the player loaded plays once it can seek. + const pending = useRef<number | null>(null); + const [failed, setFailed] = useState(false); + const Player = choosePlayer(); + const src = samePath(share.fileUrl); + + const handleControls = useCallback((next: VideoPlayerControls) => { + controls.current = next; + if (pending.current !== null) { + next.seek(pending.current); + next.play(); + pending.current = null; + } + }, []); + + function seek(ms: number) { + if (controls.current === null) { + pending.current = ms; + return; + } + controls.current.seek(ms); + controls.current.play(); + } + + const video = share.kind === 'video'; + + return ( + <Card pad="lg" className="flex flex-col gap-6"> + <header className="flex flex-col gap-2"> + <h1 className="break-words text-2xl font-semibold">{share.title}</h1> + {share.description ? ( + <p className="whitespace-pre-line break-words text-ink-2"> + {share.description} + </p> + ) : null} + </header> + {video ? ( + <Player + src={src} + shape={shareShape(share.width, share.height)} + poster={samePath(share.posterUrl)} + onError={() => setFailed(true)} + onControls={handleControls} + /> + ) : ( + // biome-ignore lint/performance/noImgElement: a streamed share file, not a static asset next/image can optimize + <img + src={src} + alt={share.title} + className="mx-auto max-h-[70vh] rounded-control" + /> + )} + {failed ? ( + <Banner tone="danger">{t('sharePage.playbackFailed')}</Banner> + ) : null} + {video ? <Chapters chapters={share.chapters} onSeek={seek} /> : null} + <div className="flex flex-wrap items-center justify-between gap-3"> + <a + href={samePath(share.downloadUrl)} + download + className={buttonClassName({ variant: 'solid' })} + > + {t('sharePage.download')} + </a> + <MadeWithBadge /> + </div> + </Card> + ); +} diff --git a/apps/web/src/components/share-page/unlock-form.tsx b/apps/web/src/components/share-page/unlock-form.tsx new file mode 100644 index 00000000..de6bd621 --- /dev/null +++ b/apps/web/src/components/share-page/unlock-form.tsx @@ -0,0 +1,62 @@ +'use client'; + +import { Banner } from '@andrewbehma/glass-ui/banner'; +import { Button } from '@andrewbehma/glass-ui/button'; +import { Field, Input } from '@andrewbehma/glass-ui/field'; +import { useRouter } from 'next/navigation'; +import { useActionState, useId } from 'react'; +import { t } from '@/i18n'; +import { type UnlockOutcome, unlockShare } from '@/lib/share-page'; + +const MESSAGES = { + 'wrong-password': 'sharePage.locked.wrongPassword', + 'rate-limited': 'sharePage.locked.rateLimited', + error: 'sharePage.locked.failed', +} as const; + +type Failure = keyof typeof MESSAGES; + +/** + * The password form of a protected share (spec #351, Decision 4). A right + * password sets the unlock cookie; the page then fetches the share again. + */ +export function UnlockForm({ token }: { token: string }) { + const router = useRouter(); + const id = useId(); + const [failure, action, pending] = useActionState( + async (_previous: Failure | null, data: FormData) => { + const outcome: UnlockOutcome = await unlockShare( + token, + String(data.get('password') ?? ''), + ); + if (outcome === 'unlocked' || outcome === 'changed') { + // An expired or removed share shows its own page after the refresh. + router.refresh(); + return null; + } + return outcome; + }, + null, + ); + + return ( + <form action={action} className="flex flex-col gap-4"> + {failure ? <Banner tone="danger">{t(MESSAGES[failure])}</Banner> : null} + <Field label={t('sharePage.locked.password')} htmlFor={id}> + <Input + id={id} + name="password" + type="password" + autoComplete="current-password" + aria-invalid={failure === 'wrong-password' ? true : undefined} + required + /> + </Field> + <Button type="submit" full disabled={pending}> + {pending + ? t('sharePage.locked.submitting') + : t('sharePage.locked.submit')} + </Button> + </form> + ); +} diff --git a/apps/web/src/i18n/en.ts b/apps/web/src/i18n/en.ts index 27b8858f..4d7bcdde 100644 --- a/apps/web/src/i18n/en.ts +++ b/apps/web/src/i18n/en.ts @@ -520,6 +520,44 @@ export const en = { body: 'Deleted from the machine on {date}.', }, }, + sharePage: { + download: 'Download', + madeWith: 'Made with DemoFlow', + playbackFailed: 'The video could not be played. Try Download instead.', + chapters: { + title: 'Chapters', + seek: 'Play from {time}: {title}', + }, + locked: { + title: 'This video is protected', + body: 'Enter the password you were given to watch it.', + password: 'Password', + submit: 'Unlock', + submitting: 'Unlocking…', + wrongPassword: 'Wrong password.', + rateLimited: 'Too many attempts, try again in a few minutes.', + failed: 'We could not check the password. Try again in a moment.', + }, + expired: { + title: 'This link has expired', + body: 'Ask the person who shared it for a new link.', + }, + unavailable: { + title: 'This video is no longer available', + body: 'Ask the person who shared it to share it again.', + }, + notFound: { + title: 'This link does not exist', + body: 'Check the address, or ask the person who shared it for the link again.', + }, + failed: { + title: 'We could not load this video', + body: 'Try again in a moment.', + }, + meta: { + locked: 'A shared DemoFlow video', + }, + }, meta: { title: 'DemoFlow', }, diff --git a/apps/web/src/lib/session.ts b/apps/web/src/lib/session.ts index beff3791..f160f2c7 100644 --- a/apps/web/src/lib/session.ts +++ b/apps/web/src/lib/session.ts @@ -11,7 +11,8 @@ import { type Runner, } from './api'; -function apiUrl(): string { +/** The API's internal origin, for server-side calls. */ +export function apiUrl(): string { return process.env.API_URL ?? 'http://localhost:8370'; } diff --git a/apps/web/src/lib/share-page.test.mjs b/apps/web/src/lib/share-page.test.mjs new file mode 100644 index 00000000..c6027582 --- /dev/null +++ b/apps/web/src/lib/share-page.test.mjs @@ -0,0 +1,106 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { + chapterTime, + hasUnlockCookie, + samePath, + sharePageState, + shareShape, + unfurlsVideo, + unlockOutcome, +} from './share-page.ts'; + +const share = { + title: 'Sign in', + description: null, + chapters: [], + format: 'mp4', + kind: 'video', + width: 1920, + height: 1080, + durationMs: 12000, + sizeBytes: 1024, + expiresAt: '2026-11-01T00:00:00.000Z', + fileUrl: 'https://demoflow.example/s/abc/file', + posterUrl: 'https://demoflow.example/s/abc/poster', + downloadUrl: 'https://demoflow.example/s/abc/file?download=1', +}; + +test('an open share renders the share', () => { + assert.deepEqual(sharePageState(200, share), { kind: 'share', share }); +}); + +test('a locked answer renders the password form only', () => { + assert.deepEqual(sharePageState(200, { locked: true }), { kind: 'locked' }); +}); + +test('an unknown token is not found', () => { + assert.deepEqual(sharePageState(404, { error: 'not-found' }), { + kind: 'not-found', + }); +}); + +test('a 410 tells an expired link from an unavailable video', () => { + assert.deepEqual(sharePageState(410, { error: 'expired' }), { + kind: 'expired', + }); + assert.deepEqual(sharePageState(410, { error: 'unavailable' }), { + kind: 'unavailable', + }); + assert.deepEqual(sharePageState(410, undefined), { kind: 'unavailable' }); +}); + +test('anything else is an error, never a share', () => { + assert.deepEqual(sharePageState(500, undefined), { kind: 'error' }); + assert.deepEqual(sharePageState(200, undefined), { kind: 'error' }); + assert.deepEqual(sharePageState(200, { title: 'x' }), { kind: 'error' }); +}); + +test('chapter times read mm:ss, and h:mm:ss from an hour on', () => { + assert.equal(chapterTime(0), '00:00'); + assert.equal(chapterTime(4_999), '00:04'); + assert.equal(chapterTime(65_000), '01:05'); + assert.equal(chapterTime(3_725_000), '1:02:05'); + assert.equal(chapterTime(-10), '00:00'); +}); + +test('the player box follows the picture', () => { + assert.equal(shareShape(1920, 1080), 'landscape'); + assert.equal(shareShape(1080, 1920), 'vertical'); + assert.equal(shareShape(1080, 1080), 'square'); + assert.equal(shareShape(null, null), 'landscape'); + assert.equal(shareShape(0, 1080), 'landscape'); +}); + +test('in-page URLs keep the path and query only', () => { + assert.equal(samePath(share.fileUrl), '/s/abc/file'); + assert.equal(samePath(share.downloadUrl), '/s/abc/file?download=1'); + assert.equal(samePath('/s/abc/file'), '/s/abc/file'); +}); + +test('an unlock cookie is spotted among others', () => { + assert.equal(hasUnlockCookie(''), false); + assert.equal(hasUnlockCookie('df_session=1; theme=dark'), false); + assert.equal(hasUnlockCookie('theme=dark; df_share_abc=1.sig'), true); +}); + +test('og:video goes only to MP4 shares read without an unlock cookie', () => { + assert.equal(unfurlsVideo(share, ''), true); + assert.equal(unfurlsVideo({ ...share, format: 'mp4-vertical' }, ''), true); + assert.equal(unfurlsVideo({ ...share, format: 'webm' }, ''), false); + assert.equal( + unfurlsVideo({ ...share, format: 'gif', kind: 'image' }, ''), + false, + ); + assert.equal(unfurlsVideo(share, 'df_share_abc=1.sig'), false); +}); + +test('unlock answers map to their messages', () => { + assert.equal(unlockOutcome(204), 'unlocked'); + assert.equal(unlockOutcome(401), 'wrong-password'); + assert.equal(unlockOutcome(400), 'wrong-password'); + assert.equal(unlockOutcome(429), 'rate-limited'); + assert.equal(unlockOutcome(410), 'changed'); + assert.equal(unlockOutcome(404), 'changed'); + assert.equal(unlockOutcome(500), 'error'); +}); diff --git a/apps/web/src/lib/share-page.ts b/apps/web/src/lib/share-page.ts new file mode 100644 index 00000000..2a9ce4a7 --- /dev/null +++ b/apps/web/src/lib/share-page.ts @@ -0,0 +1,183 @@ +// The public share page (spec #351): the fetch of `GET /s/:token` (spec #348) +// and the pure logic around it. No React, no Next, no Node APIs, so +// `node --test` runs it as it is. + +import type { PlayerShape } from './playback'; + +/** A scene of the scenario, as a chapter of the video. */ +export interface ShareChapter { + title: string; + atMs: number; +} + +/** What `GET /s/:token` answers for an open share (spec #348, Decision 3). */ +export interface ShareData { + title: string; + description: string | null; + chapters: ShareChapter[]; + format: string; + kind: 'video' | 'image'; + width: number | null; + height: number | null; + durationMs: number | null; + sizeBytes: number; + expiresAt: string; + fileUrl: string; + posterUrl: string; + downloadUrl: string; +} + +/** What the page renders (Decision 1). */ +export type SharePageState = + | { kind: 'share'; share: ShareData } + | { kind: 'locked' } + | { kind: 'not-found' } + | { kind: 'expired' } + | { kind: 'unavailable' } + | { kind: 'error' }; + +/** The state for an answer of `GET /s/:token`: its status and JSON body. */ +export function sharePageState(status: number, body: unknown): SharePageState { + const record = + typeof body === 'object' && body !== null + ? (body as Record<string, unknown>) + : {}; + if (status === 200) { + if (record.locked === true) return { kind: 'locked' }; + if (typeof record.title === 'string' && typeof record.fileUrl === 'string') + return { kind: 'share', share: body as ShareData }; + return { kind: 'error' }; + } + if (status === 404) return { kind: 'not-found' }; + if (status === 410) + return record.error === 'expired' + ? { kind: 'expired' } + : { kind: 'unavailable' }; + return { kind: 'error' }; +} + +/** + * Asks the API for a share, on its internal origin with the viewer's cookies, + * so an unlock cookie opens a protected share. A network failure is `error`. + */ +export async function fetchSharePage( + token: string, + { baseUrl, cookie }: { baseUrl: string; cookie: string }, +): Promise<SharePageState> { + try { + const response = await fetch(`${baseUrl}/s/${encodeURIComponent(token)}`, { + headers: cookie ? { cookie } : {}, + cache: 'no-store', + }); + let body: unknown; + try { + body = await response.json(); + } catch { + body = undefined; + } + return sharePageState(response.status, body); + } catch { + return { kind: 'error' }; + } +} + +/** `mm:ss`, or `h:mm:ss` from an hour on: a chapter's start. */ +export function chapterTime(ms: number): string { + const total = Math.max(0, Math.floor(ms / 1000)); + const hours = Math.floor(total / 3600); + const minutes = Math.floor((total % 3600) / 60); + const seconds = String(total % 60).padStart(2, '0'); + return hours > 0 + ? `${hours}:${String(minutes).padStart(2, '0')}:${seconds}` + : `${String(minutes).padStart(2, '0')}:${seconds}`; +} + +/** + * The player's box for a picture of `width` × `height`: wider than tall is + * 16:9, taller than wide is 9:16, roughly even is 1:1. Unknown is 16:9. + */ +export function shareShape( + width: number | null, + height: number | null, +): PlayerShape { + if (!width || !height) return 'landscape'; + const ratio = width / height; + if (ratio > 1.2) return 'landscape'; + if (ratio < 1 / 1.2) return 'vertical'; + return 'square'; +} + +/** + * The path and query of one of the API's absolute share URLs. The page plays + * and downloads on its own origin, so the unlock cookie goes with the request + * whatever origin the API was configured with. + */ +export function samePath(url: string): string { + try { + const { pathname, search } = new URL(url); + return `${pathname}${search}`; + } catch { + return url; + } +} + +/** + * True when the request carries an unlock cookie (`df_share_<id>`, spec #348, + * Decision 5). `ShareData` does not say whether the share has a password, so + * a request with one may be reading a protected share. + */ +export function hasUnlockCookie(cookie: string): boolean { + return cookie.split(';').some((part) => part.trim().startsWith('df_share_')); +} + +/** + * Unfurlers get the file as `og:video` only for an MP4 share known to have + * no password: a request without any unlock cookie (Decision 5). + */ +export function unfurlsVideo(share: ShareData, cookie: string): boolean { + return ( + share.kind === 'video' && + share.format.startsWith('mp4') && + !hasUnlockCookie(cookie) + ); +} + +export type UnlockOutcome = + | 'unlocked' + | 'wrong-password' + | 'rate-limited' + | 'changed' + | 'error'; + +/** + * What an answer of `POST /s/:token/unlock` means (Decision 4). A password + * the API refuses to check (too short or too long) cannot be the right one; + * a share that expired or went away meanwhile is `changed`, and the page + * fetches again to show it. + */ +export function unlockOutcome(status: number): UnlockOutcome { + if (status >= 200 && status < 300) return 'unlocked'; + if (status === 400 || status === 401) return 'wrong-password'; + if (status === 429) return 'rate-limited'; + if (status === 404 || status === 410) return 'changed'; + return 'error'; +} + +/** Posts the password from the browser; the API sets the unlock cookie. */ +export async function unlockShare( + token: string, + password: string, +): Promise<UnlockOutcome> { + try { + const response = await fetch(`/api/s/${encodeURIComponent(token)}/unlock`, { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ password }), + credentials: 'same-origin', + cache: 'no-store', + }); + return unlockOutcome(response.status); + } catch { + return 'error'; + } +} From 822f0da7455671510f9eb829a74d8fb202e5d194 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 16:38:06 +0100 Subject: [PATCH 41/71] test(demo): add the C-200 demo scenario for the Glass projects and machines pages The scenario signs in off camera, then walks the Projects and Machines pages in both themes. It uses only pages that render without seeded runs, so it holds on an empty account. Refs #374. --- ...b-glass-ui-for-projects-runs-the.demo.json | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 demoflow/cards/C-200-feat-web-glass-ui-for-projects-runs-the.demo.json diff --git a/demoflow/cards/C-200-feat-web-glass-ui-for-projects-runs-the.demo.json b/demoflow/cards/C-200-feat-web-glass-ui-for-projects-runs-the.demo.json new file mode 100644 index 00000000..c4ef6e00 --- /dev/null +++ b/demoflow/cards/C-200-feat-web-glass-ui-for-projects-runs-the.demo.json @@ -0,0 +1,53 @@ +{ + "schemaVersion": 1, + "name": "Glass UI for projects and machines", + "description": "Sign in off camera, then walk the redesigned Projects page with its page header and solid project list, and the Machines page with its Glass table and status pills, in the dark and the light theme.", + "viewport": { "width": 1280, "height": 720 }, + "setup": [ + { + "action": "include", + "fragment": "sign-in", + "with": { "next": "/app/projects" } + } + ], + "steps": [ + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Projects", "exact": true } + }, + { + "action": "click", + "target": { "role": "link", "name": "Machines", "exact": true } + }, + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Machines", "exact": true } + }, + { + "action": "click", + "target": { "role": "button", "name": "Account menu" } + }, + { + "action": "click", + "target": { "role": "menuitemradio", "name": "Light", "exact": true } + }, + { "action": "press", "key": "Escape" }, + { + "action": "click", + "target": { "role": "link", "name": "Projects", "exact": true } + }, + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Projects", "exact": true } + }, + { + "action": "click", + "target": { "role": "button", "name": "Account menu" } + }, + { + "action": "click", + "target": { "role": "menuitemradio", "name": "Dark", "exact": true } + }, + { "action": "press", "key": "Escape" } + ] +} From b61620c21b22a09b5f4de72e8769da3596bc35c1 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 16:38:11 +0100 Subject: [PATCH 42/71] test(demo): C-199 scenario for the glass auth, device and settings pages Signs in off camera, enters an unknown device code to show the danger banner, walks the three settings sections, then signs out to the glass sign-in and sign-up cards. --- ...-glass-ui-for-sign-in-sign-up-pa.demo.json | 93 +++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 demoflow/cards/C-199-feat-web-glass-ui-for-sign-in-sign-up-pa.demo.json diff --git a/demoflow/cards/C-199-feat-web-glass-ui-for-sign-in-sign-up-pa.demo.json b/demoflow/cards/C-199-feat-web-glass-ui-for-sign-in-sign-up-pa.demo.json new file mode 100644 index 00000000..eac918cd --- /dev/null +++ b/demoflow/cards/C-199-feat-web-glass-ui-for-sign-in-sign-up-pa.demo.json @@ -0,0 +1,93 @@ +{ + "schemaVersion": 1, + "name": "Glass UI auth, device and settings", + "description": "Sign in off camera, then walk the restyled pages: the device code entry with a wrong code in a danger banner, account settings with its three sections, then sign out to the glass sign-in and sign-up cards.", + "viewport": { "width": 1280, "height": 720 }, + "setup": [ + { + "action": "include", + "fragment": "sign-in", + "with": { "next": "/app/device" } + } + ], + "steps": [ + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Pair a machine", "exact": true } + }, + { + "action": "fill", + "target": { "label": "Code", "exact": true }, + "value": "ZZZZ-9999", + "caption": "A code the API does not know" + }, + { + "action": "click", + "target": { "role": "button", "name": "Continue", "exact": true } + }, + { + "action": "assertVisible", + "target": { + "role": "heading", + "name": "This code is not valid", + "exact": true + } + }, + { + "action": "click", + "target": { "role": "link", "name": "Settings", "exact": true } + }, + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Account settings", "exact": true } + }, + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Profile", "exact": true } + }, + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Sign-in methods", "exact": true } + }, + { + "action": "scroll", + "target": { "role": "heading", "name": "Danger zone", "exact": true } + }, + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Danger zone", "exact": true } + }, + { + "action": "click", + "target": { "role": "button", "name": "Account menu" } + }, + { + "action": "click", + "target": { "role": "menuitem", "name": "Sign out", "exact": true } + }, + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Sign in", "exact": true } + }, + { + "action": "click", + "target": { "role": "link", "name": "Create an account", "exact": true } + }, + { + "action": "assertVisible", + "target": { + "role": "heading", + "name": "Create your account", + "exact": true + } + }, + { + "action": "click", + "target": { "role": "link", "name": "Sign in", "exact": true } + }, + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Sign in", "exact": true } + } + ] +} From 5423db1e48831d0f7a6e60c82a6e7284013fcd43 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 17:07:30 +0100 Subject: [PATCH 43/71] feat(api): check schedules, check passes and per-scenario stale state CheckSchedule and ScenarioHealth tables with a backfill from each scenario's latest run. Reports update the stale state in their own transaction; GET /projects gains staleCount. The runner socket carries check.started/finished/error and schedules.sync, and launches.sync says whether the daemon accepts check.start. A check pass is one more kind of launch. The scheduler ticks every minute, starts one pass per due slot, and catches up once after a machine was offline or busy. Routes: GET/PUT/DELETE /projects/:id/schedule, GET /projects/:id/health, GET /checks/stale. --- .../migration.sql | 77 +++++ apps/api/prisma/schema.prisma | 53 ++++ apps/api/src/app.module.ts | 2 + apps/api/src/checks/checks.controller.ts | 74 +++++ apps/api/src/checks/checks.module.ts | 20 ++ apps/api/src/checks/health/health.service.ts | 85 ++++++ apps/api/src/checks/health/health.ts | 98 ++++++ .../src/checks/schedules/check-scheduler.ts | 174 +++++++++++ .../api/src/checks/schedules/schedules.dto.ts | 50 +++ .../src/checks/schedules/schedules.service.ts | 289 ++++++++++++++++++ apps/api/src/checks/schedules/time-zone.ts | 36 +++ apps/api/src/checks/slots.spec.ts | 169 ++++++++++ apps/api/src/checks/slots.ts | 135 ++++++++ .../src/launches/launches.integration.spec.ts | 3 + apps/api/src/launches/launches.module.ts | 1 + apps/api/src/launches/launches.service.ts | 156 ++++++++-- .../src/projects/projects.integration.spec.ts | 9 + apps/api/src/projects/projects.service.ts | 12 +- .../src/runner/runner-connections.service.ts | 30 ++ apps/api/src/runner/runner-socket.fixtures.ts | 15 +- apps/api/src/runner/runner-socket.ts | 131 +++++++- 21 files changed, 1585 insertions(+), 34 deletions(-) create mode 100644 apps/api/prisma/migrations/20261028090000_check_schedules/migration.sql create mode 100644 apps/api/src/checks/checks.controller.ts create mode 100644 apps/api/src/checks/checks.module.ts create mode 100644 apps/api/src/checks/health/health.service.ts create mode 100644 apps/api/src/checks/health/health.ts create mode 100644 apps/api/src/checks/schedules/check-scheduler.ts create mode 100644 apps/api/src/checks/schedules/schedules.dto.ts create mode 100644 apps/api/src/checks/schedules/schedules.service.ts create mode 100644 apps/api/src/checks/schedules/time-zone.ts create mode 100644 apps/api/src/checks/slots.spec.ts create mode 100644 apps/api/src/checks/slots.ts diff --git a/apps/api/prisma/migrations/20261028090000_check_schedules/migration.sql b/apps/api/prisma/migrations/20261028090000_check_schedules/migration.sql new file mode 100644 index 00000000..f26447a0 --- /dev/null +++ b/apps/api/prisma/migrations/20261028090000_check_schedules/migration.sql @@ -0,0 +1,77 @@ +-- CreateEnum +CREATE TYPE "ScheduleSource" AS ENUM ('site', 'config'); + +-- CreateEnum +CREATE TYPE "ScheduleCadence" AS ENUM ('daily', 'weekdays', 'weekly'); + +-- CreateTable +CREATE TABLE "CheckSchedule" ( + "id" TEXT NOT NULL, + "projectId" TEXT NOT NULL, + "source" "ScheduleSource" NOT NULL, + "cadence" "ScheduleCadence" NOT NULL, + "weekday" TEXT, + "at" TEXT NOT NULL, + "timeZone" TEXT NOT NULL, + "exclude" TEXT[], + "pausedReason" TEXT, + "lastSlotAt" TIMESTAMP(3), + "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + "updatedAt" TIMESTAMP(3) NOT NULL, + + CONSTRAINT "CheckSchedule_pkey" PRIMARY KEY ("id") +); + +-- CreateTable +CREATE TABLE "ScenarioHealth" ( + "projectId" TEXT NOT NULL, + "scenarioPath" TEXT NOT NULL, + "state" "RunStatus" NOT NULL, + "since" TIMESTAMP(3) NOT NULL, + "lastRunId" TEXT NOT NULL, + + CONSTRAINT "ScenarioHealth_pkey" PRIMARY KEY ("projectId","scenarioPath") +); + +-- CreateIndex +CREATE UNIQUE INDEX "CheckSchedule_projectId_source_key" ON "CheckSchedule"("projectId", "source"); + +-- CreateIndex +CREATE INDEX "ScenarioHealth_projectId_state_idx" ON "ScenarioHealth"("projectId", "state"); + +-- AddForeignKey +ALTER TABLE "CheckSchedule" ADD CONSTRAINT "CheckSchedule_projectId_fkey" FOREIGN KEY ("projectId") REFERENCES "Project"("id") ON DELETE CASCADE ON UPDATE CASCADE; + +-- AddForeignKey +ALTER TABLE "ScenarioHealth" ADD CONSTRAINT "ScenarioHealth_projectId_fkey" FOREIGN KEY ("projectId") REFERENCES "Project"("id") ON DELETE CASCADE ON UPDATE CASCADE; + +-- Backfill: each scenario's state is its latest run's status, `since` the +-- start of the oldest run after the latest run with the other status. +INSERT INTO "ScenarioHealth" ("projectId", "scenarioPath", "state", "since", "lastRunId") +SELECT + latest."projectId", + latest."scenarioPath", + latest."status", + COALESCE(( + SELECT MIN(r."startedAt") + FROM "Run" r + WHERE r."projectId" = latest."projectId" + AND r."scenarioPath" = latest."scenarioPath" + AND r."startedAt" > COALESCE( + ( + SELECT MAX(o."startedAt") + FROM "Run" o + WHERE o."projectId" = latest."projectId" + AND o."scenarioPath" = latest."scenarioPath" + AND o."status" <> latest."status" + ), + '-infinity'::timestamp + ) + ), latest."startedAt"), + latest."id" +FROM ( + SELECT DISTINCT ON ("projectId", "scenarioPath") + "projectId", "scenarioPath", "status", "startedAt", "id" + FROM "Run" + ORDER BY "projectId", "scenarioPath", "startedAt" DESC, "id" DESC +) latest; diff --git a/apps/api/prisma/schema.prisma b/apps/api/prisma/schema.prisma index b680c041..cf0afd2a 100644 --- a/apps/api/prisma/schema.prisma +++ b/apps/api/prisma/schema.prisma @@ -114,6 +114,8 @@ model Project { createdAt DateTime @default(now()) updatedAt DateTime @updatedAt runs Run[] + schedules CheckSchedule[] + health ScenarioHealth[] @@unique([runnerId, rootPath]) @@index([userId]) @@ -206,6 +208,57 @@ model Share { @@index([expiresAt]) } +enum ScheduleSource { + site + config +} + +enum ScheduleCadence { + daily + weekdays + weekly +} + +// When a project's scenarios are checked (spec #362, ADR-0021). A `site` row +// is set on the website and run by the API; a `config` row is what the daemon +// reported from `demoflow.config.json`, stored only to be shown. +model CheckSchedule { + id String @id @default(uuid()) + projectId String + project Project @relation(fields: [projectId], references: [id], onDelete: Cascade) + source ScheduleSource + cadence ScheduleCadence + // `mon`…`sun`; set only for `weekly`. + weekday String? + // `HH:MM`, 24-hour, in `timeZone`. + at String + timeZone String + exclude String[] + // `config-schedule`, `no-machine` or `cli-too-old`; null while it runs. + pausedReason String? + // The latest slot a pass was started for (site rows only). + lastSlotAt DateTime? + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@unique([projectId, source]) +} + +// The state of a project's scenario after its latest reported run (spec #362, +// ADR-0021 §6). `failed` is "stale". `since` is the start of the run that made +// the last transition; `lastRunId` is a plain column: deleting a run keeps it. +model ScenarioHealth { + projectId String + project Project @relation(fields: [projectId], references: [id], onDelete: Cascade) + scenarioPath String + state RunStatus + since DateTime + lastRunId String + + @@id([projectId, scenarioPath]) + @@index([projectId, state]) +} + // A pending `demoflow login` (RFC 8628). Only the SHA-256 hash of the polling // secret is stored. `approvedById` is a plain column: the row lives at most // ten minutes and is deleted once its token is issued. diff --git a/apps/api/src/app.module.ts b/apps/api/src/app.module.ts index 187c6c83..9f8337bf 100644 --- a/apps/api/src/app.module.ts +++ b/apps/api/src/app.module.ts @@ -1,6 +1,7 @@ import { Module } from '@nestjs/common'; import { ConfigModule } from '@nestjs/config'; import { AuthModule } from './auth/auth.module'; +import { ChecksModule } from './checks/checks.module'; import { ClockModule } from './common/clock.module'; import { DatabaseModule } from './database/database.module'; import { HealthController } from './health.controller'; @@ -26,6 +27,7 @@ import { VideosModule } from './videos/videos.module'; VideosModule, LaunchesModule, SharesModule, + ChecksModule, ], controllers: [HealthController], }) diff --git a/apps/api/src/checks/checks.controller.ts b/apps/api/src/checks/checks.controller.ts new file mode 100644 index 00000000..f5d15596 --- /dev/null +++ b/apps/api/src/checks/checks.controller.ts @@ -0,0 +1,74 @@ +import { + Body, + Controller, + Delete, + Get, + HttpCode, + HttpStatus, + Param, + Put, + UseGuards, +} from '@nestjs/common'; +import type { User } from '@prisma/client'; +import { CurrentUser } from '../auth/current-user.decorator'; +import { SessionGuard } from '../auth/session.guard'; +import { + HealthService, + type HealthView, + type StaleView, +} from './health/health.service'; +import { PutScheduleDto } from './schedules/schedules.dto'; +import { + type ProjectSchedules, + SchedulesService, + type ScheduleView, +} from './schedules/schedules.service'; + +/** + * A project's check schedule and the per-scenario state (spec #362, API). + * Another user's project is `404`, as on every project route. + */ +@Controller() +@UseGuards(SessionGuard) +export class ChecksController { + constructor( + private readonly schedules: SchedulesService, + private readonly health: HealthService, + ) {} + + @Get('projects/:id/schedule') + schedule( + @CurrentUser() user: User, + @Param('id') id: string, + ): Promise<ProjectSchedules> { + return this.schedules.get(user.id, id); + } + + @Put('projects/:id/schedule') + put( + @CurrentUser() user: User, + @Param('id') id: string, + @Body() dto: PutScheduleDto, + ): Promise<ScheduleView> { + return this.schedules.put(user.id, id, dto); + } + + @Delete('projects/:id/schedule') + @HttpCode(HttpStatus.NO_CONTENT) + remove(@CurrentUser() user: User, @Param('id') id: string): Promise<void> { + return this.schedules.remove(user.id, id); + } + + @Get('projects/:id/health') + projectHealth( + @CurrentUser() user: User, + @Param('id') id: string, + ): Promise<HealthView[]> { + return this.health.project(user.id, id); + } + + @Get('checks/stale') + stale(@CurrentUser() user: User): Promise<StaleView[]> { + return this.health.stale(user.id); + } +} diff --git a/apps/api/src/checks/checks.module.ts b/apps/api/src/checks/checks.module.ts new file mode 100644 index 00000000..5bce79e7 --- /dev/null +++ b/apps/api/src/checks/checks.module.ts @@ -0,0 +1,20 @@ +import { Module } from '@nestjs/common'; +import { AuthModule } from '../auth/auth.module'; +import { LaunchesModule } from '../launches/launches.module'; +import { RunnerModule } from '../runner/runner.module'; +import { ChecksController } from './checks.controller'; +import { HealthService } from './health/health.service'; +import { CheckScheduler } from './schedules/check-scheduler'; +import { SchedulesService } from './schedules/schedules.service'; + +/** + * Scheduled checks on the website side (spec #362, ADR-0021): the schedules, + * the scheduler that starts a check pass when one is due, and the + * per-scenario stale state. + */ +@Module({ + imports: [AuthModule, RunnerModule, LaunchesModule], + controllers: [ChecksController], + providers: [SchedulesService, CheckScheduler, HealthService], +}) +export class ChecksModule {} diff --git a/apps/api/src/checks/health/health.service.ts b/apps/api/src/checks/health/health.service.ts new file mode 100644 index 00000000..7538df55 --- /dev/null +++ b/apps/api/src/checks/health/health.service.ts @@ -0,0 +1,85 @@ +import { HttpStatus, Injectable } from '@nestjs/common'; +import type { RunStatus } from '@prisma/client'; +import { PrismaService } from '../../database/prisma.service'; +import { runError } from '../../videos/runs.service'; + +/** At most this many in `GET /checks/stale`. */ +export const STALE_LIMIT = 50; + +export interface HealthView { + scenarioPath: string; + scenarioName: string; + state: RunStatus; + since: Date; + lastRunId: string; +} + +export interface StaleView { + projectId: string; + projectName: string; + scenarioPath: string; + scenarioName: string; + since: Date; + lastRunId: string; +} + +/** + * Reads the per-scenario state (spec #362, Decision 6). "Stale" is + * `state = failed`; `recordHealth` writes it with each report. + */ +@Injectable() +export class HealthService { + constructor(private readonly prisma: PrismaService) {} + + async project(userId: string, projectId: string): Promise<HealthView[]> { + const count = await this.prisma.project.count({ + where: { id: projectId, userId }, + }); + if (count !== 1) { + throw runError(HttpStatus.NOT_FOUND, 'not-found'); + } + const rows = await this.prisma.scenarioHealth.findMany({ + where: { projectId }, + orderBy: { scenarioPath: 'asc' }, + }); + const names = await this.names(rows.map((row) => row.lastRunId)); + return rows.map((row) => ({ + scenarioPath: row.scenarioPath, + scenarioName: names.get(row.lastRunId) ?? row.scenarioPath, + state: row.state, + since: row.since, + lastRunId: row.lastRunId, + })); + } + + /** The caller's stale scenarios across projects, newest `since` first. */ + async stale(userId: string): Promise<StaleView[]> { + const rows = await this.prisma.scenarioHealth.findMany({ + where: { state: 'failed', project: { userId } }, + orderBy: [{ since: 'desc' }, { scenarioPath: 'asc' }], + take: STALE_LIMIT, + include: { project: { select: { name: true } } }, + }); + const names = await this.names(rows.map((row) => row.lastRunId)); + return rows.map((row) => ({ + projectId: row.projectId, + projectName: row.project.name, + scenarioPath: row.scenarioPath, + scenarioName: names.get(row.lastRunId) ?? row.scenarioPath, + since: row.since, + lastRunId: row.lastRunId, + })); + } + + /** + * Each run's scenario name. A deleted run leaves the state as it was + * (Decision 6), so a missing one falls back to the path. + */ + private async names(runIds: string[]): Promise<Map<string, string>> { + const runs = await this.prisma.run.findMany({ + where: { id: { in: runIds } }, + select: { id: true, scenarioName: true }, + }); + return new Map(runs.map((run) => [run.id, run.scenarioName])); + } +} diff --git a/apps/api/src/checks/health/health.ts b/apps/api/src/checks/health/health.ts new file mode 100644 index 00000000..e220ab25 --- /dev/null +++ b/apps/api/src/checks/health/health.ts @@ -0,0 +1,98 @@ +import type { Prisma, RunStatus } from '@prisma/client'; + +/** A stored run, as the stale state needs it. */ +export interface HealthRun { + id: string; + scenarioPath: string; + status: RunStatus; + startedAt: Date; +} + +/** + * Moves a scenario's state on after a stored run (spec #362, Decision 6): + * same state → only `lastRunId`; another state → `state`, `since` and + * `lastRunId`. A run that started before the one the state comes from is + * older news and changes nothing. Called inside the report's transaction. + */ +export async function recordHealth( + tx: Prisma.TransactionClient, + projectId: string, + run: HealthRun, +): Promise<void> { + const key = { + projectId_scenarioPath: { projectId, scenarioPath: run.scenarioPath }, + }; + const created = await tx.$executeRaw` + INSERT INTO "ScenarioHealth" ("projectId", "scenarioPath", "state", "since", "lastRunId") + VALUES (${projectId}, ${run.scenarioPath}, ${run.status}::"RunStatus", ${run.startedAt}, ${run.id}) + ON CONFLICT ("projectId", "scenarioPath") DO NOTHING`; + if (created === 1) { + return; + } + // Locks the row, so two reports of one scenario apply one after the other. + const [row] = await tx.$queryRaw< + { state: RunStatus; lastRunId: string }[] + >`SELECT "state", "lastRunId" FROM "ScenarioHealth" + WHERE "projectId" = ${projectId} AND "scenarioPath" = ${run.scenarioPath} + FOR UPDATE`; + if (!row) { + return; + } + const last = await tx.run.findUnique({ + where: { id: row.lastRunId }, + select: { startedAt: true }, + }); + if (last && last.startedAt > run.startedAt) { + return; + } + await tx.scenarioHealth.update({ + where: key, + data: + row.state === run.status + ? { lastRunId: run.id } + : { state: run.status, since: run.startedAt, lastRunId: run.id }, + }); +} + +/** + * Recomputes a project's states from its runs, as the migration's backfill + * does: each scenario's latest run gives the state, and `since` is the start + * of the oldest run after the latest run with the other status. Used when a + * merge moves another project's runs here. + */ +export async function rebuildHealth( + tx: Prisma.TransactionClient, + projectId: string, +): Promise<void> { + await tx.scenarioHealth.deleteMany({ where: { projectId } }); + await tx.$executeRaw` + INSERT INTO "ScenarioHealth" ("projectId", "scenarioPath", "state", "since", "lastRunId") + SELECT + latest."projectId", + latest."scenarioPath", + latest."status", + COALESCE(( + SELECT MIN(r."startedAt") + FROM "Run" r + WHERE r."projectId" = latest."projectId" + AND r."scenarioPath" = latest."scenarioPath" + AND r."startedAt" > COALESCE( + ( + SELECT MAX(o."startedAt") + FROM "Run" o + WHERE o."projectId" = latest."projectId" + AND o."scenarioPath" = latest."scenarioPath" + AND o."status" <> latest."status" + ), + '-infinity'::timestamp + ) + ), latest."startedAt"), + latest."id" + FROM ( + SELECT DISTINCT ON ("scenarioPath") + "projectId", "scenarioPath", "status", "startedAt", "id" + FROM "Run" + WHERE "projectId" = ${projectId} + ORDER BY "scenarioPath", "startedAt" DESC, "id" DESC + ) latest`; +} diff --git a/apps/api/src/checks/schedules/check-scheduler.ts b/apps/api/src/checks/schedules/check-scheduler.ts new file mode 100644 index 00000000..1e996f0f --- /dev/null +++ b/apps/api/src/checks/schedules/check-scheduler.ts @@ -0,0 +1,174 @@ +import { + Injectable, + Logger, + type OnApplicationBootstrap, + type OnModuleDestroy, +} from '@nestjs/common'; +import type { CheckSchedule } from '@prisma/client'; +import { Clock } from '../../common/clock'; +import { PrismaService } from '../../database/prisma.service'; +import { LaunchesService } from '../../launches/launches.service'; +import { RunnerConnections } from '../../runner/runner-connections.service'; +import { lastDueSlot } from '../slots'; +import type { PausedReason } from './schedules.service'; + +export const SCHEDULER_INTERVAL_MS = 60 * 1000; + +/** Start failures after which the slot is still owed: the pass never began. */ +const RETRIABLE = new Set(['runner-busy', 'runner-offline']); + +interface Row extends CheckSchedule { + project: { + rootPath: string | null; + runner: { id: string; revokedAt: Date | null } | null; + }; +} + +/** + * Starts a check pass when a `site` schedule is due (spec #362, Decision 4). + * A missed slot is computed from the clock and `lastSlotAt`, so a machine + * that was offline, busy or restarting gets one catch-up pass for all of + * them, and an API restart loses nothing. + * + * One API process (deploy/README.md): two would start a pass twice. + */ +@Injectable() +export class CheckScheduler implements OnApplicationBootstrap, OnModuleDestroy { + private readonly logger = new Logger(CheckScheduler.name); + private timer: NodeJS.Timeout | undefined; + private pass: Promise<void> | undefined; + + constructor( + private readonly prisma: PrismaService, + private readonly connections: RunnerConnections, + private readonly launches: LaunchesService, + private readonly clock: Clock, + ) {} + + onApplicationBootstrap(): void { + this.timer = setInterval(() => void this.tick(), SCHEDULER_INTERVAL_MS); + this.timer.unref(); + } + + onModuleDestroy(): void { + clearInterval(this.timer); + } + + /** + * One pass over the schedules; resolves once every due `check.start` is + * sent. A tick while one is in flight joins it. + */ + tick(): Promise<void> { + this.pass ??= this.run().finally(() => { + this.pass = undefined; + }); + return this.pass; + } + + private async run(): Promise<void> { + const rows = await this.prisma.checkSchedule.findMany({ + // `config-schedule` lifts only with the `config` row, in `SchedulesService`. + where: { + source: 'site', + OR: [ + { pausedReason: null }, + { pausedReason: { not: 'config-schedule' } }, + ], + }, + include: { + project: { + select: { + rootPath: true, + runner: { select: { id: true, revokedAt: true } }, + }, + }, + }, + }); + const now = this.clock.now(); + for (const row of rows) { + try { + await this.consider(row, now); + } catch (error) { + this.logger.error( + `Schedule ${row.id} failed`, + error instanceof Error ? error.stack : String(error), + ); + } + } + } + + private async consider(row: Row, now: Date): Promise<void> { + const { runner, rootPath } = row.project; + if (!runner || runner.revokedAt !== null || rootPath === null) { + await this.pause(row, 'no-machine'); + return; + } + // Null until the machine's `launches.sync`: keep what is known. + const checks = this.connections.isOnline(runner.id) + ? this.connections.checks(runner.id) + : null; + if (checks === false) { + await this.pause(row, 'cli-too-old'); + return; + } + if (checks === true || row.pausedReason === 'no-machine') { + await this.pause(row, null); + } + if (checks !== true) { + return; + } + const slot = lastDueSlot(row, now, row.timeZone); + if ( + slot === null || + (row.lastSlotAt !== null && slot <= row.lastSlotAt) || + this.launches.isBusy(runner.id) + ) { + return; + } + // Written before the request, so a crash or restart never sends it twice. + const claimed = await this.prisma.checkSchedule.updateMany({ + where: { id: row.id, lastSlotAt: row.lastSlotAt, pausedReason: null }, + data: { lastSlotAt: slot }, + }); + if (claimed.count !== 1) { + return; + } + // Not awaited: `check.start` is sent now, the answer may take seconds. + void this.launches + .startCheckPass( + { projectId: row.projectId, runnerId: runner.id, rootPath }, + row.exclude, + ) + .then(async (outcome) => { + if (outcome.ok) { + return; + } + this.logger.warn( + `Check pass of project ${row.projectId} not started: ${outcome.error}`, + ); + if (RETRIABLE.has(outcome.error)) { + await this.prisma.checkSchedule.updateMany({ + where: { id: row.id, lastSlotAt: slot }, + data: { lastSlotAt: row.lastSlotAt }, + }); + } + }) + .catch((error: unknown) => { + this.logger.error( + `Check pass of project ${row.projectId} failed`, + error instanceof Error ? error.stack : String(error), + ); + }); + } + + private async pause(row: Row, reason: PausedReason | null): Promise<void> { + if (row.pausedReason === reason) { + return; + } + await this.prisma.checkSchedule.updateMany({ + where: { id: row.id, pausedReason: row.pausedReason }, + data: { pausedReason: reason }, + }); + row.pausedReason = reason; + } +} diff --git a/apps/api/src/checks/schedules/schedules.dto.ts b/apps/api/src/checks/schedules/schedules.dto.ts new file mode 100644 index 00000000..6dcce347 --- /dev/null +++ b/apps/api/src/checks/schedules/schedules.dto.ts @@ -0,0 +1,50 @@ +import { + ArrayMaxSize, + ArrayUnique, + IsArray, + IsIn, + Matches, + ValidateBy, + ValidateIf, +} from 'class-validator'; +import { IsScenarioId } from '../../launches/scenario-id'; +import { CADENCES, type Cadence, TIME_OF_DAY, WEEKDAYS } from '../slots'; +import { IsTimeZone } from './time-zone'; + +/** At most this many scenarios left out of a pass (spec #362, Decision 3). */ +export const MAX_EXCLUDES = 100; + +/** `PUT /projects/:id/schedule`: the website's schedule of a project. */ +export class PutScheduleDto { + @IsIn(CADENCES) + cadence!: Cadence; + + /** Required with `weekly`, refused with any other cadence. */ + @ValidateIf( + (dto: PutScheduleDto, value) => + dto.cadence === 'weekly' || value !== undefined, + ) + @IsIn(WEEKDAYS) + @ValidateBy({ + name: 'onlyWithWeekly', + validator: { + validate: (_, args) => + (args?.object as PutScheduleDto).cadence === 'weekly', + defaultMessage: () => 'weekday is only allowed with the weekly cadence', + }, + }) + weekday?: string; + + @Matches(TIME_OF_DAY, { message: 'at must be HH:MM, 24-hour' }) + at!: string; + + @IsTimeZone() + timeZone!: string; + + @ValidateIf((_, value) => value !== undefined) + @IsArray() + @ArrayMaxSize(MAX_EXCLUDES) + @ArrayUnique() + @IsScenarioId({ each: true }) + exclude?: string[]; +} diff --git a/apps/api/src/checks/schedules/schedules.service.ts b/apps/api/src/checks/schedules/schedules.service.ts new file mode 100644 index 00000000..5f9cc358 --- /dev/null +++ b/apps/api/src/checks/schedules/schedules.service.ts @@ -0,0 +1,289 @@ +import { + HttpStatus, + Injectable, + Logger, + type OnModuleInit, +} from '@nestjs/common'; +import type { CheckSchedule, Prisma } from '@prisma/client'; +import { Clock } from '../../common/clock'; +import { PrismaService } from '../../database/prisma.service'; +import { + RunnerConnections, + type SchedulesSink, +} from '../../runner/runner-connections.service'; +import type { + SchedulesMessage, + SyncedSchedule, +} from '../../runner/runner-socket'; +import { runError } from '../../videos/runs.service'; +import { lastDueSlot, nextDueSlot } from '../slots'; +import type { PutScheduleDto } from './schedules.dto'; + +/** Why a `site` schedule does not run (spec #362). */ +export type PausedReason = 'config-schedule' | 'no-machine' | 'cli-too-old'; + +/** A schedule as the website reads it (spec #362, API). */ +export interface ScheduleView { + source: 'site' | 'config'; + cadence: CheckSchedule['cadence']; + weekday: string | null; + at: string; + timeZone: string; + exclude: string[]; + pausedReason: string | null; + /** Computed, never stored; null while paused. */ + nextDueAt: Date | null; + /** The start of the project's latest reported check run. */ + lastPassAt: Date | null; +} + +export interface ScheduleMachine { + id: string; + name: string; + online: boolean; + /** The zone of the machine's latest `schedules.sync`, for the form's default. */ + zone: string | null; +} + +export interface ProjectSchedules { + site: ScheduleView | null; + config: ScheduleView | null; + machine: ScheduleMachine | null; +} + +/** + * A project's check schedules (spec #362, Decision 2): the `site` row the + * website sets, and the `config` row the daemon reports from the project's + * config with `schedules.sync`. The API runs only `site` rows + * (`CheckScheduler`); `config` rows are shown. + */ +@Injectable() +export class SchedulesService implements SchedulesSink, OnModuleInit { + private readonly logger = new Logger(SchedulesService.name); + /** The zone of each machine's latest `schedules.sync`. */ + private readonly zones = new Map<string, string>(); + /** One machine's syncs apply in the order they came. */ + private readonly syncs = new Map<string, Promise<void>>(); + + constructor( + private readonly prisma: PrismaService, + private readonly connections: RunnerConnections, + private readonly clock: Clock, + ) {} + + onModuleInit(): void { + this.connections.setSchedulesSink(this); + } + + async get(userId: string, projectId: string): Promise<ProjectSchedules> { + const project = await this.owned(userId, projectId); + const rows = await this.prisma.checkSchedule.findMany({ + where: { projectId }, + }); + const lastPassAt = await this.lastPassAt(projectId); + const view = (source: 'site' | 'config') => { + const row = rows.find((candidate) => candidate.source === source); + return row ? this.toView(row, lastPassAt) : null; + }; + const runner = project.runner; + return { + site: view('site'), + config: view('config'), + machine: + runner && runner.revokedAt === null + ? { + id: runner.id, + name: runner.name, + online: this.connections.isOnline(runner.id), + zone: this.zones.get(runner.id) ?? null, + } + : null, + }; + } + + /** + * Creates or replaces the `site` row. A new schedule never fires at once: + * `lastSlotAt` starts at the slot already due. + */ + async put( + userId: string, + projectId: string, + dto: PutScheduleDto, + ): Promise<ScheduleView> { + const project = await this.owned(userId, projectId); + const config = await this.prisma.checkSchedule.count({ + where: { projectId, source: 'config' }, + }); + if (config > 0) { + throw runError(HttpStatus.CONFLICT, 'config-schedule'); + } + if ( + !project.runner || + project.runner.revokedAt !== null || + project.rootPath === null + ) { + throw runError(HttpStatus.CONFLICT, 'no-machine'); + } + const fields = { + cadence: dto.cadence, + weekday: dto.cadence === 'weekly' ? (dto.weekday ?? null) : null, + at: dto.at, + timeZone: dto.timeZone, + exclude: dto.exclude ?? [], + }; + const data = { + ...fields, + pausedReason: null, + lastSlotAt: lastDueSlot(fields, this.clock.now(), fields.timeZone), + }; + const row = await this.prisma.checkSchedule.upsert({ + where: { projectId_source: { projectId, source: 'site' } }, + create: { projectId, source: 'site', ...data }, + update: data, + }); + return this.toView(row, await this.lastPassAt(projectId)); + } + + async remove(userId: string, projectId: string): Promise<void> { + await this.owned(userId, projectId); + await this.prisma.checkSchedule.deleteMany({ + where: { projectId, source: 'site' }, + }); + } + + /** `schedules.sync` (spec 361, Decision 6), from `RunnerConnections`. */ + sync(runnerId: string, message: SchedulesMessage): void { + const previous = this.syncs.get(runnerId) ?? Promise.resolve(); + const next = previous + .then(() => this.apply(runnerId, message)) + .catch((error: unknown) => { + this.logger.error( + `schedules.sync from ${runnerId} failed`, + error instanceof Error ? error.stack : String(error), + ); + }) + .finally(() => { + if (this.syncs.get(runnerId) === next) { + this.syncs.delete(runnerId); + } + }); + this.syncs.set(runnerId, next); + } + + private async apply( + runnerId: string, + message: SchedulesMessage, + ): Promise<void> { + this.zones.set(runnerId, message.zone); + const roots = message.projects.map((project) => project.rootPath); + // A project the server does not know yet is ignored (Decision 2). + const projects = await this.prisma.project.findMany({ + where: { runnerId, rootPath: { in: roots } }, + select: { id: true, rootPath: true }, + }); + for (const project of projects) { + const synced = message.projects.find( + (candidate) => candidate.rootPath === project.rootPath, + ); + if (!synced) { + continue; + } + await this.prisma.$transaction((tx) => + synced.schedule + ? this.setConfig(tx, project.id, synced.schedule, message.zone) + : this.dropConfig(tx, project.id), + ); + } + } + + private async setConfig( + tx: Prisma.TransactionClient, + projectId: string, + schedule: SyncedSchedule, + zone: string, + ): Promise<void> { + const data = { + cadence: schedule.cadence, + weekday: + schedule.cadence === 'weekly' ? (schedule.weekday ?? null) : null, + at: schedule.at, + timeZone: zone, + exclude: schedule.exclude ?? [], + }; + await tx.checkSchedule.upsert({ + where: { projectId_source: { projectId, source: 'config' } }, + create: { projectId, source: 'config', ...data }, + update: data, + }); + await tx.checkSchedule.updateMany({ + where: { projectId, source: 'site' }, + data: { pausedReason: 'config-schedule' }, + }); + } + + /** The pause lifts without a catch-up: the slots it skipped were the daemon's. */ + private async dropConfig( + tx: Prisma.TransactionClient, + projectId: string, + ): Promise<void> { + const { count } = await tx.checkSchedule.deleteMany({ + where: { projectId, source: 'config' }, + }); + if (count === 0) { + return; + } + const site = await tx.checkSchedule.findUnique({ + where: { projectId_source: { projectId, source: 'site' } }, + }); + if (site?.pausedReason !== 'config-schedule') { + return; + } + await tx.checkSchedule.update({ + where: { id: site.id }, + data: { + pausedReason: null, + lastSlotAt: lastDueSlot(site, this.clock.now(), site.timeZone), + }, + }); + } + + private async owned(userId: string, projectId: string) { + const project = await this.prisma.project.findFirst({ + where: { id: projectId, userId }, + select: { + rootPath: true, + runner: { select: { id: true, name: true, revokedAt: true } }, + }, + }); + if (!project) { + throw runError(HttpStatus.NOT_FOUND, 'not-found'); + } + return project; + } + + private async lastPassAt(projectId: string): Promise<Date | null> { + const run = await this.prisma.run.findFirst({ + where: { projectId, kind: 'check' }, + orderBy: [{ startedAt: 'desc' }, { id: 'desc' }], + select: { startedAt: true }, + }); + return run?.startedAt ?? null; + } + + private toView(row: CheckSchedule, lastPassAt: Date | null): ScheduleView { + return { + source: row.source, + cadence: row.cadence, + weekday: row.weekday, + at: row.at, + timeZone: row.timeZone, + exclude: row.exclude, + pausedReason: row.pausedReason, + nextDueAt: + row.pausedReason === null + ? nextDueSlot(row, this.clock.now(), row.timeZone) + : null, + lastPassAt, + }; + } +} diff --git a/apps/api/src/checks/schedules/time-zone.ts b/apps/api/src/checks/schedules/time-zone.ts new file mode 100644 index 00000000..7efdd5ad --- /dev/null +++ b/apps/api/src/checks/schedules/time-zone.ts @@ -0,0 +1,36 @@ +import { ValidateBy, type ValidationOptions } from 'class-validator'; + +/** Whether `zone` is an IANA time zone this runtime knows. */ +export function isTimeZone(zone: string): boolean { + if (zone.length === 0 || zone.length > 64) { + return false; + } + if (Intl.supportedValuesOf('timeZone').includes(zone)) { + return true; + } + // `supportedValuesOf` lists canonical names only: `UTC`, `Europe/Kyiv` + // and other aliases are missing from it on some runtimes. + if (!/^[A-Za-z][A-Za-z0-9_+-]*(\/[A-Za-z0-9_+-]+)*$/.test(zone)) { + return false; + } + try { + new Intl.DateTimeFormat('en-US', { timeZone: zone }); + return true; + } catch { + return false; + } +} + +/** An IANA time zone name (spec #362, Decision 3). */ +export function IsTimeZone(options?: ValidationOptions): PropertyDecorator { + return ValidateBy( + { + name: 'isTimeZone', + validator: { + validate: (value) => typeof value === 'string' && isTimeZone(value), + defaultMessage: () => '$property is not a time zone', + }, + }, + options, + ); +} diff --git a/apps/api/src/checks/slots.spec.ts b/apps/api/src/checks/slots.spec.ts new file mode 100644 index 00000000..37ae6424 --- /dev/null +++ b/apps/api/src/checks/slots.spec.ts @@ -0,0 +1,169 @@ +import { isTimeZone } from './schedules/time-zone'; +import { lastDueSlot, nextDueSlot, type SlotSchedule } from './slots'; + +function daily(at: string): SlotSchedule { + return { cadence: 'daily', weekday: null, at }; +} + +function iso(date: Date | null): string | null { + return date ? date.toISOString() : null; +} + +describe('slots', () => { + describe('lastDueSlot', () => { + it('is today when the time has passed, yesterday when it has not', () => { + expect( + iso( + lastDueSlot( + daily('09:30'), + new Date('2026-10-20T12:00:00Z'), + 'Europe/Berlin', + ), + ), + ).toBe('2026-10-20T07:30:00.000Z'); + expect( + iso( + lastDueSlot( + daily('09:30'), + new Date('2026-10-20T07:29:59Z'), + 'Europe/Berlin', + ), + ), + ).toBe('2026-10-19T07:30:00.000Z'); + }); + + it('counts a slot exactly at now as due', () => { + expect( + iso( + lastDueSlot(daily('12:00'), new Date('2026-10-20T12:00:00Z'), 'UTC'), + ), + ).toBe('2026-10-20T12:00:00.000Z'); + }); + + it('skips the weekend for weekdays', () => { + const weekdays: SlotSchedule = { + cadence: 'weekdays', + weekday: null, + at: '09:00', + }; + // Sunday 2026-10-25. + const sunday = new Date('2026-10-25T12:00:00Z'); + expect(iso(lastDueSlot(weekdays, sunday, 'UTC'))).toBe( + '2026-10-23T09:00:00.000Z', + ); + expect(iso(nextDueSlot(weekdays, sunday, 'UTC'))).toBe( + '2026-10-26T09:00:00.000Z', + ); + }); + + it('finds the named day for weekly', () => { + const monday: SlotSchedule = { + cadence: 'weekly', + weekday: 'mon', + at: '09:00', + }; + // Tuesday 2026-10-20. + const tuesday = new Date('2026-10-20T12:00:00Z'); + expect(iso(lastDueSlot(monday, tuesday, 'UTC'))).toBe( + '2026-10-19T09:00:00.000Z', + ); + expect(iso(nextDueSlot(monday, tuesday, 'UTC'))).toBe( + '2026-10-26T09:00:00.000Z', + ); + }); + + it('uses the local day of the zone, not the UTC one', () => { + // 2026-10-20 23:30 in New York is already the 21st in UTC. + expect( + iso( + lastDueSlot( + daily('23:00'), + new Date('2026-10-21T03:30:00Z'), + 'America/New_York', + ), + ), + ).toBe('2026-10-21T03:00:00.000Z'); + }); + }); + + describe('DST', () => { + it('moves a missing time to the next valid minute (Europe/Berlin, spring)', () => { + // 2026-03-29 02:00 CET jumps to 03:00 CEST. + expect( + iso( + lastDueSlot( + daily('02:30'), + new Date('2026-03-29T12:00:00Z'), + 'Europe/Berlin', + ), + ), + ).toBe('2026-03-29T01:00:00.000Z'); + }); + + it('runs a repeated time once, at its first occurrence (Europe/Berlin, autumn)', () => { + // 2026-10-25 03:00 CEST falls back to 02:00 CET. + const schedule = daily('02:30'); + expect( + iso( + lastDueSlot( + schedule, + new Date('2026-10-25T12:00:00Z'), + 'Europe/Berlin', + ), + ), + ).toBe('2026-10-25T00:30:00.000Z'); + // Between the two occurrences, the next slot is the next day. + expect( + iso( + nextDueSlot( + schedule, + new Date('2026-10-25T01:00:00Z'), + 'Europe/Berlin', + ), + ), + ).toBe('2026-10-26T01:30:00.000Z'); + }); + + it('moves a missing time to the next valid minute (America/New_York, spring)', () => { + // 2026-03-08 02:00 EST jumps to 03:00 EDT. + expect( + iso( + lastDueSlot( + daily('02:30'), + new Date('2026-03-08T12:00:00Z'), + 'America/New_York', + ), + ), + ).toBe('2026-03-08T07:00:00.000Z'); + }); + + it('runs a repeated time once, at its first occurrence (America/New_York, autumn)', () => { + // 2026-11-01 02:00 EDT falls back to 01:00 EST. + expect( + iso( + lastDueSlot( + daily('01:30'), + new Date('2026-11-01T12:00:00Z'), + 'America/New_York', + ), + ), + ).toBe('2026-11-01T05:30:00.000Z'); + }); + }); + + describe('isTimeZone', () => { + it('accepts IANA names and their aliases', () => { + expect(isTimeZone('Europe/Berlin')).toBe(true); + expect(isTimeZone('America/New_York')).toBe(true); + expect(isTimeZone('UTC')).toBe(true); + expect(isTimeZone('Europe/Kyiv')).toBe(true); + }); + + it('refuses anything else', () => { + expect(isTimeZone('Mars/Olympus')).toBe(false); + expect(isTimeZone('')).toBe(false); + expect(isTimeZone('+02:00')).toBe(false); + expect(isTimeZone('Europe/Berlin\n')).toBe(false); + }); + }); +}); diff --git a/apps/api/src/checks/slots.ts b/apps/api/src/checks/slots.ts new file mode 100644 index 00000000..1c5ddde0 --- /dev/null +++ b/apps/api/src/checks/slots.ts @@ -0,0 +1,135 @@ +/** + * When a check schedule is due (spec #362, Decision 4). A port of spec 361's + * `lastDueSlot`: the API does not depend on `@demoflow/core`, so the rule and + * its test vectors are kept in both places. + * + * DST: a local time that does not exist that day falls on the next valid + * minute; one that repeats falls on its first occurrence. + */ + +export const WEEKDAYS = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat']; +export const CADENCES = ['daily', 'weekdays', 'weekly'] as const; + +export type Cadence = (typeof CADENCES)[number]; +/** `HH:MM`, 24-hour. */ +export const TIME_OF_DAY = /^([01]\d|2[0-3]):[0-5]\d$/; + +export interface SlotSchedule { + cadence: Cadence; + /** `mon`…`sun`; only with `weekly`. */ + weekday: string | null; + /** `HH:MM`, 24-hour, local to the zone. */ + at: string; +} + +const MINUTE = 60_000; +const DAY = 24 * 60 * MINUTE; +// Enough days to reach a weekly slot from any day, either way. +const DAYS_SEARCHED = 8; +// The longest DST gap in use is one hour; some zones have moved by more. +const GAP_MINUTES = 180; + +const formatters = new Map<string, Intl.DateTimeFormat>(); + +function formatter(zone: string): Intl.DateTimeFormat { + let format = formatters.get(zone); + if (!format) { + format = new Intl.DateTimeFormat('en-US', { + timeZone: zone, + hourCycle: 'h23', + year: 'numeric', + month: 'numeric', + day: 'numeric', + hour: 'numeric', + minute: 'numeric', + }); + formatters.set(zone, format); + } + return format; +} + +/** The wall-clock time at `instant` in `zone`, as if it were UTC, in ms. */ +function wallTime(instant: number, zone: string): number { + const parts: Record<string, number> = {}; + for (const part of formatter(zone).formatToParts(instant)) { + if (part.type !== 'literal') { + parts[part.type] = Number(part.value); + } + } + return Date.UTC( + parts.year, + parts.month - 1, + parts.day, + parts.hour, + parts.minute, + ); +} + +/** The first instant whose wall time in `zone` is `wall`, or null in a gap. */ +function instantOf(wall: number, zone: string): number | null { + const candidates = [wall - 14 * 60 * MINUTE, wall, wall + 14 * 60 * MINUTE] + .map((probe) => wall - (wallTime(probe, zone) - probe)) + .filter((candidate) => wallTime(candidate, zone) === wall); + return candidates.length > 0 ? Math.min(...candidates) : null; +} + +/** The slot of the local day `day` (a UTC midnight), or null when none. */ +function slotOn( + schedule: SlotSchedule, + day: number, + zone: string, +): number | null { + const weekday = new Date(day).getUTCDay(); + if (schedule.cadence === 'weekdays' && (weekday === 0 || weekday === 6)) { + return null; + } + if (schedule.cadence === 'weekly' && WEEKDAYS[weekday] !== schedule.weekday) { + return null; + } + const [hours, minutes] = schedule.at.split(':').map(Number); + const wall = day + hours * 60 * MINUTE + minutes * MINUTE; + for (let shift = 0; shift <= GAP_MINUTES; shift += 1) { + const instant = instantOf(wall + shift * MINUTE, zone); + if (instant !== null) { + return instant; + } + } + return null; +} + +function localDay(now: Date, zone: string): number { + const wall = wallTime(now.getTime(), zone); + return wall - (wall % DAY); +} + +/** The latest slot at or before `now`, or null when there is none. */ +export function lastDueSlot( + schedule: SlotSchedule, + now: Date, + zone: string, +): Date | null { + const today = localDay(now, zone); + for (let back = 0; back <= DAYS_SEARCHED; back += 1) { + const slot = slotOn(schedule, today - back * DAY, zone); + if (slot !== null && slot <= now.getTime()) { + return new Date(slot); + } + } + return null; +} + +/** The first slot after `now`, or null when there is none. */ +export function nextDueSlot( + schedule: SlotSchedule, + now: Date, + zone: string, +): Date | null { + const today = localDay(now, zone); + for (let ahead = 0; ahead <= DAYS_SEARCHED; ahead += 1) { + const slot = slotOn(schedule, today + ahead * DAY, zone); + if (slot !== null && slot > now.getTime()) { + return new Date(slot); + } + } + return null; +} diff --git a/apps/api/src/launches/launches.integration.spec.ts b/apps/api/src/launches/launches.integration.spec.ts index 274559a4..285ba280 100644 --- a/apps/api/src/launches/launches.integration.spec.ts +++ b/apps/api/src/launches/launches.integration.spec.ts @@ -252,6 +252,7 @@ describe('starting and cancelling a run from the website (integration)', () => { expect(res.status).toBe(202); const launch = { id: ask.requestId, + kind: 'run', scenarioId: SCENARIO, scenarioName: 'Checkout', state: 'running', @@ -260,6 +261,8 @@ describe('starting and cancelling a run from the website (integration)', () => { runId: null, progress: null, formats: null, + passed: null, + failed: null, }; expect(res.body).toEqual({ launch }); expect((await latest()).body).toEqual({ launch }); diff --git a/apps/api/src/launches/launches.module.ts b/apps/api/src/launches/launches.module.ts index e54419f6..ee9c1588 100644 --- a/apps/api/src/launches/launches.module.ts +++ b/apps/api/src/launches/launches.module.ts @@ -12,5 +12,6 @@ import { LaunchesService } from './launches.service'; imports: [AuthModule, RunnerModule], controllers: [LaunchesController], providers: [LaunchesService], + exports: [LaunchesService], }) export class LaunchesModule {} diff --git a/apps/api/src/launches/launches.service.ts b/apps/api/src/launches/launches.service.ts index 8d1cb280..ac624119 100644 --- a/apps/api/src/launches/launches.service.ts +++ b/apps/api/src/launches/launches.service.ts @@ -30,6 +30,8 @@ export const START_TIMEOUT_MS = 15 * 1000; export const CANCEL_TIMEOUT_MS = 30 * 1000; /** No `run.finished` this long after `run.started`: `lost`. The daemon's own cap is 15 min. */ export const RUN_TIMEOUT_MS = 20 * 60 * 1000; +/** No `check.finished` this long after `check.started`: `lost`. The daemon caps a pass at 2 h (spec 360). */ +export const CHECK_TIMEOUT_MS = 2 * 60 * 60 * 1000 + 5 * 60 * 1000; /** A finished launch is kept this long for `GET` (Decision 9). */ export const LAUNCH_RETENTION_MS = 10 * 60 * 1000; /** A detached launch whose machine has no new socket this long is `lost` (spec #284, Decision 3). */ @@ -59,10 +61,15 @@ export interface RunProgress { steps: number | null; } +/** A run of one scenario, or a check pass of the whole project (spec #362, Decision 5). */ +export type LaunchKind = 'run' | 'check'; + /** What the browser polls (Decision 1). */ export interface LaunchView { id: string; - scenarioId: string; + kind: LaunchKind; + /** Null for a check pass. */ + scenarioId: string | null; scenarioName: string | null; state: LaunchState; startedAt: string; @@ -72,6 +79,9 @@ export interface LaunchView { progress: RunProgress | null; /** The formats the browser chose; null for the project's own (spec #325, Decision 5). */ formats: RunFormat[] | null; + /** A finished check pass's counts (`check.finished`); null otherwise. */ + passed: number | null; + failed: number | null; } export interface ScenarioList { @@ -130,6 +140,10 @@ const TIMEOUT: Failure = { status: HttpStatus.GATEWAY_TIMEOUT, error: 'runner-timeout', }; +const BUSY: Failure = RUNNER_ERRORS.busy; + +/** How `startCheckPass` ended: started, or why not (`runner-busy`, `runner-offline`, …). */ +export type CheckPassStart = { ok: true } | { ok: false; error: string }; function runnerFailure(code: string): Failure { return Object.hasOwn(RUNNER_ERRORS, code) @@ -148,9 +162,10 @@ interface PendingList { interface Launch { id: string; + kind: LaunchKind; projectId: string; runnerId: string; - scenarioId: string; + scenarioId: string | null; scenarioName: string | null; /** Set at start, never changed. */ formats: RunFormat[] | null; @@ -170,6 +185,8 @@ interface Launch { detachedAt: number | null; /** The latest valid `run.progress`, kept across a detach (spec #301, Decision 6). */ progress: RunProgress | null; + passed: number | null; + failed: number | null; /** The `POST` waiting while `starting`. */ settle?: (outcome: Outcome<LaunchView>) => void; } @@ -254,24 +271,8 @@ export class LaunchesService throw runError(HttpStatus.CONFLICT, 'runner-busy'); } const outcome = await new Promise<Outcome<LaunchView>>((settle) => { - const now = this.now(); - const launch: Launch = { - id: randomUUID(), - projectId: target.projectId, - runnerId: target.runnerId, - scenarioId, - scenarioName: null, - formats: formats ?? null, - state: 'starting', - startedAt: now, - since: now, - finishedAt: null, - runId: null, - finishing: false, - detachedAt: null, - progress: null, - settle, - }; + const launch = this.newLaunch('run', target, scenarioId, settle); + launch.formats = formats ?? null; this.launches.set(launch.id, launch); const sent = this.connections.sendTo(target.runnerId, { type: 'run.start', @@ -291,6 +292,39 @@ export class LaunchesService return outcome.value; } + /** + * Sends `check.start` for the whole project (spec #362, Decision 5) and + * settles once the machine says it started. The same one-launch-per-Runner + * rule as `start`; never throws: the scheduler decides what to do next. + */ + async startCheckPass( + target: LaunchTarget, + exclude: string[], + ): Promise<CheckPassStart> { + if (this.busy(target.runnerId)) { + return { ok: false, error: BUSY.error }; + } + const outcome = await new Promise<Outcome<LaunchView>>((settle) => { + const launch = this.newLaunch('check', target, null, settle); + this.launches.set(launch.id, launch); + const sent = this.connections.sendTo(target.runnerId, { + type: 'check.start', + requestId: launch.id, + rootPath: target.rootPath, + exclude, + }); + if (!sent) { + this.failStart(launch, OFFLINE, OFFLINE.error); + } + }); + return outcome.ok ? { ok: true } : { ok: false, error: outcome.error }; + } + + /** Whether the machine has an active launch: a run or a check pass. */ + isBusy(runnerId: string): boolean { + return this.busy(runnerId); + } + /** The project's latest launch, or null. */ latest(projectId: string): LaunchView | null { const launch = this.latestOf(projectId); @@ -353,27 +387,60 @@ export class LaunchesService return true; } case 'run.started': - case 'run.error': { + case 'run.error': + case 'check.started': + case 'check.error': { const launch = this.launches.get(message.requestId); - if (launch?.runnerId !== runnerId || launch.state !== 'starting') { + if ( + launch?.runnerId !== runnerId || + launch.state !== 'starting' || + launch.kind !== kindOf(message.type) + ) { return false; } - if (message.type === 'run.error') { + if (message.type === 'run.error' || message.type === 'check.error') { this.failStart(launch, runnerFailure(message.code), message.code); return true; } launch.state = 'running'; launch.since = this.now(); - launch.scenarioName = message.scenarioName; + if (message.type === 'run.started') { + launch.scenarioName = message.scenarioName; + } const settle = launch.settle; launch.settle = undefined; settle?.({ ok: true, value: toView(launch) }); return true; } + case 'check.finished': { + const launch = this.launches.get(message.requestId); + if ( + launch?.runnerId !== runnerId || + launch.kind !== 'check' || + (launch.state !== 'running' && launch.state !== 'cancelling') || + launch.finishing + ) { + return false; + } + launch.passed = message.passed; + launch.failed = message.failed; + // A pass that verified nothing did not pass: cancelled, timed out or crashed. + this.end( + launch, + launch.state === 'cancelling' + ? 'cancelled' + : message.failed > 0 || message.passed === 0 + ? 'failed' + : 'passed', + null, + ); + return true; + } case 'run.finished': { const launch = this.launches.get(message.requestId); if ( launch?.runnerId !== runnerId || + launch.kind !== 'run' || (launch.state !== 'running' && launch.state !== 'cancelling') || launch.finishing ) { @@ -499,7 +566,9 @@ export class LaunchesService } break; case 'running': - if (age >= RUN_TIMEOUT_MS) { + if ( + age >= (launch.kind === 'check' ? CHECK_TIMEOUT_MS : RUN_TIMEOUT_MS) + ) { this.end(launch, 'lost', null); } break; @@ -567,6 +636,35 @@ export class LaunchesService ); } + private newLaunch( + kind: LaunchKind, + target: LaunchTarget, + scenarioId: string | null, + settle: (outcome: Outcome<LaunchView>) => void, + ): Launch { + const now = this.now(); + return { + id: randomUUID(), + kind, + projectId: target.projectId, + runnerId: target.runnerId, + scenarioId, + scenarioName: null, + formats: null, + state: 'starting', + startedAt: now, + since: now, + finishedAt: null, + runId: null, + finishing: false, + detachedAt: null, + progress: null, + passed: null, + failed: null, + settle, + }; + } + /** A `run.cancel` the machine cannot get leaves the launch `lost`. */ private sendCancel(launch: Launch): void { const sent = this.connections.sendTo(launch.runnerId, { @@ -669,6 +767,7 @@ export class LaunchesService this.logger.log( JSON.stringify({ event: 'launch', + kind: launch.kind, projectId: launch.projectId, runnerId: launch.runnerId, outcome: label, @@ -687,6 +786,7 @@ export class LaunchesService function toView(launch: Launch): LaunchView { return { id: launch.id, + kind: launch.kind, scenarioId: launch.scenarioId, scenarioName: launch.scenarioName, state: launch.state, @@ -698,9 +798,15 @@ function toView(launch: Launch): LaunchView { runId: launch.runId, progress: launch.state === 'running' ? launch.progress : null, formats: launch.formats, + passed: launch.passed, + failed: launch.failed, }; } +function kindOf(type: LaunchMessage['type']): LaunchKind { + return type.startsWith('check.') ? 'check' : 'run'; +} + /** * Spec #301, Decision 3: `steps` carries both numbers with `step ≤ steps`, * any other phase carries neither. diff --git a/apps/api/src/projects/projects.integration.spec.ts b/apps/api/src/projects/projects.integration.spec.ts index 5c9c8573..0874ebf9 100644 --- a/apps/api/src/projects/projects.integration.spec.ts +++ b/apps/api/src/projects/projects.integration.spec.ts @@ -90,6 +90,7 @@ describe('projects (integration)', () => { rootPath: ROOT, runner: { id: laptop.runnerId, name: 'Laptop' }, runCount: 1, + staleCount: 0, lastRun: { id: res.body.runId, scenarioName: 'checkout', @@ -128,6 +129,7 @@ describe('projects (integration)', () => { expect.objectContaining({ name: 'shop', runCount: 2, + staleCount: 1, lastRun: expect.objectContaining({ id: second.body.runId, status: 'failed', @@ -313,8 +315,15 @@ describe('projects (integration)', () => { rootPath: ROOT, runner: { id: laptop.runnerId, name: 'Laptop' }, runCount: 2, + staleCount: 0, }), ); + expect( + await t.prisma.scenarioHealth.findMany({ + where: { projectId: body.project.id }, + select: { scenarioPath: true, state: true }, + }), + ).toEqual([{ scenarioPath: 'demos/checkout.yaml', state: 'passed' }]); expect( await t.prisma.project.findUnique({ where: { id: auto1.body.projectId }, diff --git a/apps/api/src/projects/projects.service.ts b/apps/api/src/projects/projects.service.ts index 067e8e6d..940ea96e 100644 --- a/apps/api/src/projects/projects.service.ts +++ b/apps/api/src/projects/projects.service.ts @@ -6,6 +6,7 @@ import { NotFoundException, } from '@nestjs/common'; import { Prisma, type Run, type Runner, type RunStatus } from '@prisma/client'; +import { rebuildHealth, recordHealth } from '../checks/health/health'; import { PrismaService } from '../database/prisma.service'; import { ShareStorage } from '../shares/share-storage'; import { @@ -47,6 +48,8 @@ export interface ProjectView { /** Null for a project never bound, or whose machine was revoked. */ runner: { id: string; name: string } | null; runCount: number; + /** Scenarios whose latest run failed (spec #362, Decision 6). */ + staleCount: number; lastRun: RunView | null; createdAt: Date; updatedAt: Date; @@ -65,7 +68,9 @@ const NEWEST_FIRST: Prisma.RunOrderByWithRelationInput[] = [ const PROJECT_INCLUDE = { runner: { select: { id: true, name: true } }, runs: { orderBy: NEWEST_FIRST, take: 1 }, - _count: { select: { runs: true } }, + _count: { + select: { runs: true, health: { where: { state: 'failed' } } }, + }, } satisfies Prisma.ProjectInclude; type ProjectWithSummary = Prisma.ProjectGetPayload<{ @@ -194,6 +199,7 @@ function toProjectView(project: ProjectWithSummary): ProjectView { rootPath: project.rootPath, runner: project.runner, runCount: project._count.runs, + staleCount: project._count.health, lastRun: lastRun ? toRunView(lastRun) : null, createdAt: project.createdAt, updatedAt: project.updatedAt, @@ -258,8 +264,9 @@ export class ProjectsService { failureMessage: report.failure?.message ?? null, kind: report.kind ?? null, }, - select: { id: true }, + select: { id: true, scenarioPath: true, status: true, startedAt: true }, }); + await recordHealth(tx, project.id, run); return { projectId: project.id, runId: run.id }; }); } @@ -335,6 +342,7 @@ export class ProjectsService { data: { projectId: id }, }); await tx.project.delete({ where: { id: holder.id } }); + await rebuildHealth(tx, id); } data.runner = { connect: { id: runner.id } }; data.rootPath = body.rootPath; diff --git a/apps/api/src/runner/runner-connections.service.ts b/apps/api/src/runner/runner-connections.service.ts index 387964fc..9e150958 100644 --- a/apps/api/src/runner/runner-connections.service.ts +++ b/apps/api/src/runner/runner-connections.service.ts @@ -26,6 +26,7 @@ import { parseClientMessage, RUN_OPTIONS, type RunOption, + type SchedulesMessage, type ServerMessage, type ShareMessage, type VideoChunk, @@ -54,6 +55,8 @@ interface Connection { runOptions: RunOption[]; /** The known features the same frame announced (spec #347, Decision 6). */ features: Feature[]; + /** Whether the same frame said it answers `check.start` (spec 360); null before it. */ + checks: boolean | null; /** A `share.*` answer for no pending request was logged on this socket. */ warnedStrayShare: boolean; } @@ -101,6 +104,11 @@ export interface ShareSink { closed(runnerId: string): void; } +/** Where check schedules (spec #362) hear a machine's config schedules. */ +export interface SchedulesSink { + sync(runnerId: string, message: SchedulesMessage): void; +} + /** * The open runner sockets of this API instance (one today, #120): online is * "has an entry here", never a column. One socket per machine — a second one @@ -119,6 +127,7 @@ export class RunnerConnections private artifactsSink: ArtifactsSink | undefined; private launchSink: LaunchSink | undefined; private shareSink: ShareSink | undefined; + private schedulesSink: SchedulesSink | undefined; constructor( private readonly prisma: PrismaService, @@ -177,6 +186,14 @@ export class RunnerConnections return this.open.get(runnerId)?.features ?? []; } + /** + * Whether the machine's current socket answers `check.start` (spec #362, + * Decision 4); null offline or before its `launches.sync`. + */ + checks(runnerId: string): boolean | null { + return this.open.get(runnerId)?.checks ?? null; + } + /** To the machine's current socket; false when it is not online. */ sendTo(runnerId: string, message: ServerMessage): boolean { const connection = this.open.get(runnerId); @@ -207,6 +224,11 @@ export class RunnerConnections this.shareSink = sink; } + /** Check schedules' hook (spec #362). One sink per instance. */ + setSchedulesSink(sink: SchedulesSink): void { + this.schedulesSink = sink; + } + /** An authenticated socket, straight after the upgrade. */ async accept( socket: WebSocket, @@ -225,6 +247,7 @@ export class RunnerConnections warnedStrayLaunch: false, runOptions: [], features: [], + checks: null, warnedStrayShare: false, }; // Listeners first: a frame that arrives during the writes below counts. @@ -387,6 +410,9 @@ export class RunnerConnections case 'run.error': case 'run.finished': case 'run.progress': + case 'check.started': + case 'check.finished': + case 'check.error': this.relayLaunch(connection, message); return; case 'launches.sync': @@ -397,8 +423,12 @@ export class RunnerConnections connection.features = FEATURES.filter((feature) => message.features?.includes(feature), ); + connection.checks = message.checks === true; this.relayLaunch(connection, message); return; + case 'schedules.sync': + this.schedulesSink?.sync(connection.runnerId, message); + return; case 'share.prepared': case 'share.error': this.relayShare(connection, message); diff --git a/apps/api/src/runner/runner-socket.fixtures.ts b/apps/api/src/runner/runner-socket.fixtures.ts index c0f9dcac..0992fb2d 100644 --- a/apps/api/src/runner/runner-socket.fixtures.ts +++ b/apps/api/src/runner/runner-socket.fixtures.ts @@ -135,9 +135,9 @@ export class TestSocket { return ask as ArtifactsDelete; } - /** The next `scenarios.list`, `run.start` or `run.cancel`, with its request id. */ + /** The next `scenarios.list`, `run.start`, `run.cancel` or `check.start`, with its request id. */ async nextLaunch( - type: 'scenarios.list' | 'run.start' | 'run.cancel', + type: 'scenarios.list' | 'run.start' | 'run.cancel' | 'check.start', ): Promise<LaunchRequest> { const ask = await this.next(type); if (typeof ask.requestId !== 'string') { @@ -158,14 +158,21 @@ export class TestSocket { /** * `launches.sync` (spec #284): the launch ids this daemon still runs, and * the `run.start` options it accepts (spec #325) — none sent when omitted. - * `features` is its capability list, as `share` (spec #347). + * `features` is its capability list, as `share` (spec #347); `checks` + * says it answers `check.start` (spec 360). */ - sync(running: string[], runOptions?: unknown, features?: string[]): void { + sync( + running: string[], + runOptions?: unknown, + features?: string[], + checks?: boolean, + ): void { this.send({ type: 'launches.sync', running, ...(runOptions === undefined ? {} : { runOptions }), ...(features === undefined ? {} : { features }), + ...(checks === undefined ? {} : { checks }), }); } diff --git a/apps/api/src/runner/runner-socket.ts b/apps/api/src/runner/runner-socket.ts index d5b1fcf6..27066290 100644 --- a/apps/api/src/runner/runner-socket.ts +++ b/apps/api/src/runner/runner-socket.ts @@ -15,6 +15,7 @@ import { IsString, IsUUID, Length, + Matches, Max, MaxLength, Min, @@ -23,8 +24,10 @@ import { validateSync, } from 'class-validator'; import type { RawData } from 'ws'; +import { IsTimeZone } from '../checks/schedules/time-zone'; +import { CADENCES, type Cadence, TIME_OF_DAY, WEEKDAYS } from '../checks/slots'; import { IsScenarioId } from '../launches/scenario-id'; -import type { RunFormat } from '../projects/projects.dto'; +import { PATH_MAX, type RunFormat } from '../projects/projects.dto'; import type { RunnerContext } from './runner-token'; /** @@ -91,6 +94,13 @@ export type ServerMessage = options?: RunStartOptions; } | { type: 'run.cancel'; requestId: string } + /** A check pass of the whole project (spec 360), cancelled with `run.cancel`. */ + | { + type: 'check.start'; + requestId: string; + rootPath: string; + exclude: string[]; + } | { type: 'share.prepare'; requestId: string; runId: string; format: string }; /** What `video.open` may ask for besides the render itself (spec #347). */ @@ -109,7 +119,8 @@ export type ClientMessage = | VideoMessage | ArtifactsMessage | LaunchMessage - | ShareMessage; + | ShareMessage + | SchedulesMessage; export type VideoMessage = | VideoHeadMessage @@ -134,7 +145,17 @@ export type LaunchMessage = | RunErrorMessage | RunFinishedMessage | RunProgressMessage - | LaunchesSyncMessage; + | LaunchesSyncMessage + | CheckMessage; + +/** A machine's project-config schedules (spec 361, Decision 6). */ +export type SchedulesMessage = SchedulesSyncMessage; + +/** A Runner's answers to `check.start` (spec 360, Decision 6). */ +export type CheckMessage = + | CheckStartedMessage + | CheckFinishedMessage + | CheckErrorMessage; /** A Runner's answer to `share.prepare` (spec #347, Decision 4). */ export type ShareMessage = SharePreparedMessage | ShareErrorMessage; @@ -176,6 +197,12 @@ export type Feature = (typeof FEATURES)[number]; /** `launches.sync` announces this many features at most, each this long at most. */ export const MAX_FEATURES = 8; export const FEATURE_MAX_LENGTH = 32; +/** `schedules.sync` carries this many projects at most (spec 361, Decision 6). */ +export const MAX_SYNCED_SCHEDULES = 500; +/** A schedule excludes this many scenarios at most (ADR-0021 §5). */ +export const MAX_SCHEDULE_EXCLUDES = 100; +/** `check.finished` counts this many scenarios at most. */ +const MAX_CHECK_COUNT = 100_000; class PingMessage { @IsIn(['ping']) @@ -432,6 +459,100 @@ class LaunchesSyncMessage { @IsString({ each: true }) @MaxLength(FEATURE_MAX_LENGTH, { each: true }) features?: string[]; + + /** `true` from a daemon that answers `check.start` (spec 360); absent before. */ + @IsOptional() + @IsBoolean() + checks?: boolean; +} + +/** The `demoflow run --check` child is running. `requestId` is the launch id. */ +class CheckStartedMessage { + @IsIn(['check.started']) + type!: 'check.started'; + + @IsUUID('4') + requestId!: string; +} + +/** The pass ended; both counts are 0 when it was cancelled, timed out or crashed. */ +class CheckFinishedMessage { + @IsIn(['check.finished']) + type!: 'check.finished'; + + @IsUUID('4') + requestId!: string; + + @IsInt() + @Min(0) + @Max(MAX_CHECK_COUNT) + passed!: number; + + @IsInt() + @Min(0) + @Max(MAX_CHECK_COUNT) + failed!: number; +} + +/** Sent instead of `check.started`; any code string, as for `run.error`. */ +class CheckErrorMessage { + @IsIn(['check.error']) + type!: 'check.error'; + + @IsUUID('4') + requestId!: string; + + @IsString() + @MaxLength(64) + code!: string; +} + +/** A project config's `schedule` block (spec 361, Decision 1). */ +export class SyncedSchedule { + @IsIn(CADENCES) + cadence!: Cadence; + + @ValidateIf((schedule: SyncedSchedule) => schedule.cadence === 'weekly') + @IsIn(WEEKDAYS) + weekday?: string; + + @Matches(TIME_OF_DAY) + at!: string; + + @IsOptional() + @IsArray() + @ArrayMaxSize(MAX_SCHEDULE_EXCLUDES) + @IsScenarioId({ each: true }) + exclude?: string[]; +} + +class SyncedProject { + @IsString() + @Length(1, PATH_MAX) + rootPath!: string; + + @ValidateIf((_, value) => value !== null) + @ValidateNested() + @Type(() => SyncedSchedule) + schedule!: SyncedSchedule | null; +} + +/** + * The schedules of a machine's project configs (spec 361, Decision 6), with + * the machine's time zone: sent after `launches.sync` and on every change. + */ +class SchedulesSyncMessage { + @IsIn(['schedules.sync']) + type!: 'schedules.sync'; + + @IsTimeZone() + zone!: string; + + @IsArray() + @ArrayMaxSize(MAX_SYNCED_SCHEDULES) + @ValidateNested({ each: true }) + @Type(() => SyncedProject) + projects!: SyncedProject[]; } class ShareChapter { @@ -507,6 +628,10 @@ const CLIENT_MESSAGES: Record< 'run.finished': RunFinishedMessage, 'run.progress': RunProgressMessage, 'launches.sync': LaunchesSyncMessage, + 'check.started': CheckStartedMessage, + 'check.finished': CheckFinishedMessage, + 'check.error': CheckErrorMessage, + 'schedules.sync': SchedulesSyncMessage, 'share.prepared': SharePreparedMessage, 'share.error': ShareErrorMessage, }; From a966edd7a72357030e6c7310efac2e852d33d809 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 17:19:53 +0100 Subject: [PATCH 44/71] test(api): integration tests for check schedules, scheduler and stale state --- .../api/src/checks/checks.integration.spec.ts | 629 ++++++++++++++++++ 1 file changed, 629 insertions(+) create mode 100644 apps/api/src/checks/checks.integration.spec.ts diff --git a/apps/api/src/checks/checks.integration.spec.ts b/apps/api/src/checks/checks.integration.spec.ts new file mode 100644 index 00000000..f1718d1b --- /dev/null +++ b/apps/api/src/checks/checks.integration.spec.ts @@ -0,0 +1,629 @@ +import { readFileSync } from 'node:fs'; +import type { AddressInfo } from 'node:net'; +import { join } from 'node:path'; +import request, { type Test } from 'supertest'; +import type { App } from 'supertest/types'; +import { LaunchesService } from '../launches/launches.service'; +import { + type Paired, + pair, + type SignedIn, + signedInUser, +} from '../runner/runner.fixtures'; +import { eventually, TestSocket } from '../runner/runner-socket.fixtures'; +import { createTestApp, type TestApp } from '../test/test-app'; +import { CheckScheduler } from './schedules/check-scheduler'; + +const ROOT = '/home/alice/shop'; +const SCENARIO = 'demoflow/checkout.demo.json'; +const MINUTE = 60 * 1000; +const DAY = 24 * 60 * MINUTE; +// The fake clock starts at 2026-10-20T12:00:00Z; this slot is five minutes on. +const DAILY = { cadence: 'daily', at: '12:05', timeZone: 'UTC' }; + +describe('check schedules (integration)', () => { + let t: TestApp; + let http: App; + let port: number; + let alice: SignedIn; + let bob: SignedIn; + let machine: Paired; + let projectId: string; + let bobProjectId: string; + const sockets: TestSocket[] = []; + + beforeEach(async () => { + t = await createTestApp(); + await t.app.listen(0, '127.0.0.1'); + http = t.app.getHttpServer(); + port = (http.address() as AddressInfo).port; + alice = await signedInUser(t, 'alice'); + bob = await signedInUser(t, 'bob'); + machine = await pair(http, alice, 'Laptop'); + projectId = (await report(machine, 'passed')).projectId; + const bobMachine = await pair(http, bob, 'Desktop'); + bobProjectId = (await report(bobMachine, 'failed', '/home/bob/blog')) + .projectId; + }); + + afterEach(async () => { + for (const socket of sockets.splice(0)) { + socket.ws.terminate(); + } + await t.app.close(); + }); + + async function report( + on: Paired, + status: 'passed' | 'failed', + rootPath = ROOT, + scenarioPath = SCENARIO, + kind?: 'check', + ): Promise<{ projectId: string; runId: string }> { + const res = await request(http) + .post('/runner/runs') + .set('Authorization', `Bearer ${on.token}`) + .send({ + rootPath, + projectName: 'shop', + scenarioName: 'Checkout', + scenarioPath, + status, + startedAt: t.clock.now().toISOString(), + durationMs: 12_345, + formats: ['mp4'], + cliVersion: '0.4.0', + ...(kind && { kind }), + }) + .expect(201); + return res.body; + } + + /** A daemon on `machine`; `checks` is what its `launches.sync` says, null for none. */ + async function daemon(checks: boolean | null = true): Promise<TestSocket> { + const socket = await TestSocket.connect( + `ws://127.0.0.1:${port}/runner`, + machine.token, + ); + sockets.push(socket); + socket.sync([], undefined, undefined, checks ?? undefined); + await socket.roundTrip(); + return socket; + } + + function put(body: unknown, cookie = alice.cookie, id = projectId): Test { + return request(http) + .put(`/projects/${id}/schedule`) + .set('Cookie', cookie) + .send(body as object); + } + + function schedule(cookie = alice.cookie, id = projectId): Test { + return request(http).get(`/projects/${id}/schedule`).set('Cookie', cookie); + } + + function tick(): Promise<void> { + return t.app.get(CheckScheduler).tick(); + } + + /** The `check.start`s the socket got and nobody consumed. */ + async function checkStarts(socket: TestSocket): Promise<number> { + await socket.roundTrip(); + return socket.received.filter((m) => m.type === 'check.start').length; + } + + describe('authorization', () => { + it('answers 404 for another user’s project on every route', async () => { + await put(DAILY, alice.cookie, bobProjectId).expect(404); + await schedule(alice.cookie, bobProjectId).expect(404); + await request(http) + .delete(`/projects/${bobProjectId}/schedule`) + .set('Cookie', alice.cookie) + .expect(404); + await request(http) + .get(`/projects/${bobProjectId}/health`) + .set('Cookie', alice.cookie) + .expect(404); + await request(http) + .get('/projects/not-a-project/schedule') + .set('Cookie', alice.cookie) + .expect(404); + }); + + it('needs a session', async () => { + await request(http).get(`/projects/${projectId}/schedule`).expect(401); + await request(http).get('/checks/stale').expect(401); + }); + + it('never shows another user’s stale scenarios', async () => { + await report(machine, 'failed'); + const res = await request(http) + .get('/checks/stale') + .set('Cookie', alice.cookie) + .expect(200); + expect(res.body).toEqual([ + { + projectId, + projectName: 'shop', + scenarioPath: SCENARIO, + scenarioName: 'Checkout', + since: t.clock.now().toISOString(), + lastRunId: expect.any(String), + }, + ]); + const projects = await request(http) + .get('/projects') + .set('Cookie', bob.cookie) + .expect(200); + expect( + projects.body.projects.map((p: { id: string; staleCount: number }) => [ + p.id, + p.staleCount, + ]), + ).toEqual([[bobProjectId, 1]]); + }); + }); + + describe('PUT /projects/:id/schedule', () => { + it('stores the site schedule and computes the next slot', async () => { + const res = await put({ + ...DAILY, + exclude: ['demoflow/slow.demo.json'], + }).expect(200); + expect(res.body).toEqual({ + source: 'site', + cadence: 'daily', + weekday: null, + at: '12:05', + timeZone: 'UTC', + exclude: ['demoflow/slow.demo.json'], + pausedReason: null, + nextDueAt: '2026-10-20T12:05:00.000Z', + lastPassAt: null, + }); + const read = await schedule().expect(200); + expect(read.body).toEqual({ + site: res.body, + config: null, + machine: { + id: machine.runnerId, + name: 'Laptop', + online: false, + zone: null, + }, + }); + }); + + it('keeps weekday for weekly only', async () => { + const res = await put({ + cadence: 'weekly', + weekday: 'mon', + at: '09:00', + timeZone: 'Europe/Berlin', + }).expect(200); + expect(res.body).toMatchObject({ + weekday: 'mon', + nextDueAt: '2026-10-26T08:00:00.000Z', + }); + }); + + it.each([ + ['weekly without a weekday', { ...DAILY, cadence: 'weekly' }], + ['a weekday without weekly', { ...DAILY, weekday: 'mon' }], + ['an unknown weekday', { ...DAILY, cadence: 'weekly', weekday: 'mo' }], + ['an unknown cadence', { ...DAILY, cadence: 'hourly' }], + ['at 25:00', { ...DAILY, at: '25:00' }], + ['at 9:00', { ...DAILY, at: '9:00' }], + ['an unknown zone', { ...DAILY, timeZone: 'Mars/Olympus' }], + ['no zone', { cadence: 'daily', at: '12:05' }], + [ + '101 excludes', + { + ...DAILY, + exclude: Array.from( + { length: 101 }, + (_, i) => `demoflow/s${i}.demo.json`, + ), + }, + ], + ['an exclude that is not a scenario id', { ...DAILY, exclude: ['../x'] }], + ['an unknown key', { ...DAILY, machine: 'other' }], + ])('refuses %s with 400', async (_, body) => { + await put(body).expect(400); + }); + + it('is 409 no-machine when the project has no machine', async () => { + await t.prisma.project.update({ + where: { id: projectId }, + data: { runnerId: null }, + }); + const res = await put(DAILY).expect(409); + expect(res.body.error).toBe('no-machine'); + }); + + it('is 409 config-schedule when the config has one', async () => { + const socket = await daemon(); + syncSchedule(socket, { cadence: 'daily', at: '08:00' }); + await eventually(async () => (await configRow()) !== null); + const res = await put(DAILY).expect(409); + expect(res.body.error).toBe('config-schedule'); + }); + + it('DELETE removes the site schedule', async () => { + await put(DAILY).expect(200); + await request(http) + .delete(`/projects/${projectId}/schedule`) + .set('Cookie', alice.cookie) + .expect(204); + const res = await schedule().expect(200); + expect(res.body.site).toBeNull(); + }); + }); + + function syncSchedule( + socket: TestSocket, + synced: Record<string, unknown> | null, + zone = 'Europe/Kyiv', + ): void { + socket.send({ + type: 'schedules.sync', + zone, + projects: [ + { rootPath: ROOT, schedule: synced }, + { rootPath: '/home/alice/unknown', schedule: synced }, + ], + }); + } + + function configRow() { + return t.prisma.checkSchedule.findUnique({ + where: { projectId_source: { projectId, source: 'config' } }, + }); + } + + function siteRow() { + return t.prisma.checkSchedule.findUnique({ + where: { projectId_source: { projectId, source: 'site' } }, + }); + } + + describe('schedules.sync', () => { + it('creates the config row and pauses the site row; null lifts it', async () => { + await put(DAILY).expect(200); + const socket = await daemon(); + syncSchedule(socket, { + cadence: 'weekly', + weekday: 'fri', + at: '18:30', + exclude: [SCENARIO], + }); + await eventually(async () => (await configRow()) !== null); + const paused = await schedule().expect(200); + expect(paused.body.config).toMatchObject({ + source: 'config', + cadence: 'weekly', + weekday: 'fri', + at: '18:30', + timeZone: 'Europe/Kyiv', + exclude: [SCENARIO], + pausedReason: null, + }); + expect(paused.body.site).toMatchObject({ + pausedReason: 'config-schedule', + nextDueAt: null, + }); + expect(paused.body.machine).toMatchObject({ + online: true, + zone: 'Europe/Kyiv', + }); + // A project the server does not know is ignored. + expect(await t.prisma.checkSchedule.count({ where: { projectId } })).toBe( + 2, + ); + + // The daemon runs config schedules; the API sends nothing for them. + t.clock.advance(DAY); + await tick(); + expect(await checkStarts(socket)).toBe(0); + + syncSchedule(socket, null); + await eventually(async () => (await configRow()) === null); + const lifted = await schedule().expect(200); + expect(lifted.body.site).toMatchObject({ pausedReason: null }); + // Lifting does not catch up the slots the daemon owned. + await tick(); + expect(await checkStarts(socket)).toBe(0); + }); + + it('refuses a sync with an unknown zone', async () => { + const socket = await daemon(); + syncSchedule(socket, { cadence: 'daily', at: '08:00' }, 'Mars/Olympus'); + await socket.roundTrip(); + expect(await configRow()).toBeNull(); + }); + }); + + describe('the scheduler', () => { + it('sends one check.start for a due slot, and never a second', async () => { + await put({ ...DAILY, exclude: [SCENARIO] }).expect(200); + const socket = await daemon(); + await tick(); + expect(await checkStarts(socket)).toBe(0); + + t.clock.advance(5 * MINUTE); + await tick(); + const ask = await socket.nextLaunch('check.start'); + expect(ask).toEqual({ + type: 'check.start', + requestId: ask.requestId, + rootPath: ROOT, + exclude: [SCENARIO], + }); + expect((await siteRow())?.lastSlotAt?.toISOString()).toBe( + '2026-10-20T12:05:00.000Z', + ); + socket.send({ type: 'check.started', requestId: ask.requestId }); + await socket.roundTrip(); + + const launch = await request(http) + .get(`/projects/${projectId}/launch`) + .set('Cookie', alice.cookie) + .expect(200); + expect(launch.body.launch).toMatchObject({ + id: ask.requestId, + kind: 'check', + scenarioId: null, + state: 'running', + passed: null, + failed: null, + }); + + socket.send({ + type: 'check.finished', + requestId: ask.requestId, + passed: 3, + failed: 1, + }); + await socket.roundTrip(); + const done = await request(http) + .get(`/projects/${projectId}/launch`) + .set('Cookie', alice.cookie) + .expect(200); + expect(done.body.launch).toMatchObject({ + kind: 'check', + state: 'failed', + passed: 3, + failed: 1, + }); + + t.clock.advance(MINUTE); + await tick(); + await tick(); + expect(await checkStarts(socket)).toBe(0); + }); + + it('sends one pass after three slots missed while offline', async () => { + await put(DAILY).expect(200); + t.clock.advance(3 * DAY); + await tick(); + const socket = await daemon(); + await tick(); + await socket.nextLaunch('check.start'); + await tick(); + expect(await checkStarts(socket)).toBe(0); + expect((await siteRow())?.lastSlotAt?.toISOString()).toBe( + '2026-10-22T12:05:00.000Z', + ); + }); + + it('waits for a busy machine’s launch to end', async () => { + await put(DAILY).expect(200); + const socket = await daemon(); + const pending = request(http) + .post(`/projects/${projectId}/launch`) + .set('Cookie', alice.cookie) + .send({ scenarioId: SCENARIO }) + .then((res) => res); + const run = await socket.nextLaunch('run.start'); + socket.send({ + type: 'run.started', + requestId: run.requestId, + scenarioName: 'Checkout', + }); + await pending; + + t.clock.advance(5 * MINUTE); + await tick(); + expect(await checkStarts(socket)).toBe(0); + + socket.send({ + type: 'run.finished', + requestId: run.requestId, + outcome: 'failed', + runId: null, + }); + const launches = t.app.get(LaunchesService); + await eventually(() => !launches.isBusy(machine.runnerId)); + await tick(); + await socket.nextLaunch('check.start'); + }); + + it('owes the slot again when the machine answers busy', async () => { + await put(DAILY).expect(200); + const socket = await daemon(); + t.clock.advance(5 * MINUTE); + await tick(); + const ask = await socket.nextLaunch('check.start'); + socket.send({ + type: 'check.error', + requestId: ask.requestId, + code: 'busy', + }); + // Back to the slot PUT started from: yesterday's. + await eventually( + async () => + (await siteRow())?.lastSlotAt?.toISOString() === + '2026-10-19T12:05:00.000Z', + ); + await tick(); + await socket.nextLaunch('check.start'); + }); + + it('pauses with cli-too-old and never sends check.start without checks: true', async () => { + await put(DAILY).expect(200); + const socket = await daemon(null); + t.clock.advance(5 * MINUTE); + await tick(); + expect(await checkStarts(socket)).toBe(0); + const res = await schedule().expect(200); + expect(res.body.site).toMatchObject({ + pausedReason: 'cli-too-old', + nextDueAt: null, + }); + + // The upgraded daemon replaces the socket and gets the slot it missed. + const upgraded = await daemon(true); + await tick(); + await upgraded.nextLaunch('check.start'); + expect((await siteRow())?.pausedReason).toBeNull(); + }); + + it('pauses with no-machine when the project lost its machine', async () => { + await put(DAILY).expect(200); + await t.prisma.project.update({ + where: { id: projectId }, + data: { runnerId: null }, + }); + await tick(); + expect((await siteRow())?.pausedReason).toBe('no-machine'); + const res = await schedule().expect(200); + expect(res.body.machine).toBeNull(); + }); + }); + + describe('the stale state', () => { + function health(): Test { + return request(http) + .get(`/projects/${projectId}/health`) + .set('Cookie', alice.cookie); + } + + it('flips on a failure, keeps since on a second, flips back on a pass', async () => { + const passedAt = t.clock.now().toISOString(); + const first = await health().expect(200); + expect(first.body).toEqual([ + { + scenarioPath: SCENARIO, + scenarioName: 'Checkout', + state: 'passed', + since: passedAt, + lastRunId: expect.any(String), + }, + ]); + + t.clock.advance(MINUTE); + const failedAt = t.clock.now().toISOString(); + const failed = await report(machine, 'failed', ROOT, SCENARIO, 'check'); + expect((await health()).body[0]).toMatchObject({ + state: 'failed', + since: failedAt, + lastRunId: failed.runId, + }); + + t.clock.advance(MINUTE); + const again = await report(machine, 'failed'); + expect((await health()).body[0]).toMatchObject({ + state: 'failed', + since: failedAt, + lastRunId: again.runId, + }); + + // The check run is the schedule's last pass. + await put(DAILY).expect(200); + expect((await schedule()).body.site.lastPassAt).toBe(failedAt); + + t.clock.advance(MINUTE); + const fixedAt = t.clock.now().toISOString(); + const fixed = await report(machine, 'passed'); + expect((await health()).body[0]).toMatchObject({ + state: 'passed', + since: fixedAt, + lastRunId: fixed.runId, + }); + }); + + it('ignores a report older than the state', async () => { + t.clock.advance(-MINUTE); + await report(machine, 'failed'); + expect((await health()).body[0]).toMatchObject({ state: 'passed' }); + }); + }); + + describe('the migration backfill', () => { + /** The backfill's `SELECT`, as the migration runs it, for one project. */ + function backfill(id: string) { + const sql = readFileSync( + join( + __dirname, + '../../prisma/migrations/20261028090000_check_schedules/migration.sql', + ), + 'utf8', + ); + const select = sql + .slice( + sql.indexOf('SELECT', sql.indexOf('INSERT INTO "ScenarioHealth"')), + ) + .trim() + .replace(/;$/, ''); + return t.prisma.$queryRawUnsafe< + { scenarioPath: string; status: string; since: Date; id: string }[] + >( + `SELECT b."scenarioPath", b."status", b."since", b."id" + FROM (${select}) AS b("projectId", "scenarioPath", "status", "since", "id") + WHERE b."projectId" = $1 ORDER BY b."scenarioPath"`, + id, + ); + } + + it('gives each scenario the state of its latest run', async () => { + t.clock.advance(MINUTE); + const failedAt = t.clock.now(); + await report(machine, 'failed'); + t.clock.advance(MINUTE); + const last = await report(machine, 'failed'); + const other = await report( + machine, + 'passed', + ROOT, + 'demoflow/signup.demo.json', + ); + expect(await backfill(projectId)).toEqual([ + { + scenarioPath: SCENARIO, + status: 'failed', + since: failedAt, + id: last.runId, + }, + { + scenarioPath: 'demoflow/signup.demo.json', + status: 'passed', + since: t.clock.now(), + id: other.runId, + }, + ]); + // And the rows the reports wrote agree with it. + const rows = await t.prisma.scenarioHealth.findMany({ + where: { projectId }, + orderBy: { scenarioPath: 'asc' }, + }); + expect( + rows.map((row) => ({ + scenarioPath: row.scenarioPath, + status: row.state, + since: row.since, + id: row.lastRunId, + })), + ).toEqual(await backfill(projectId)); + }); + }); +}); From 80cab111a4eeee495c4a4151b5d57e8ee795f93d Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 17:42:36 +0100 Subject: [PATCH 45/71] feat(core): RunEditsSchema and checkRunEdits for a run's edits.json edits.json holds the captions, per-step zoom, card text and style a person changed on the website (ADR-0020). The schema rejects unordered or overlapping captions, a duplicate step, and anything outside the bounds of the matching config fields; checkRunEdits checks the file against the run's timeline. The JSON Schema is published as schemas/edits.schema.json. --- packages/core/schemas/edits.schema.json | 204 ++++++++++++++++++++++++ packages/core/src/edits.ts | 160 +++++++++++++++++++ packages/core/src/index.ts | 1 + packages/core/src/json-schema.ts | 2 + packages/core/src/project-config.ts | 2 +- packages/core/test/edits.spec.ts | 167 +++++++++++++++++++ packages/core/test/json-schema.spec.ts | 1 + 7 files changed, 536 insertions(+), 1 deletion(-) create mode 100644 packages/core/schemas/edits.schema.json create mode 100644 packages/core/src/edits.ts create mode 100644 packages/core/test/edits.spec.ts diff --git a/packages/core/schemas/edits.schema.json b/packages/core/schemas/edits.schema.json new file mode 100644 index 00000000..d943b5b8 --- /dev/null +++ b/packages/core/schemas/edits.schema.json @@ -0,0 +1,204 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "schemaVersion": { + "type": "number", + "const": 1 + }, + "captions": { + "maxItems": 200, + "type": "array", + "items": { + "type": "object", + "properties": { + "startMs": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "endMs": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "text": { + "type": "string", + "minLength": 1, + "maxLength": 120 + } + }, + "required": ["startMs", "endMs", "text"], + "additionalProperties": false + } + }, + "zoom": { + "type": "array", + "items": { + "type": "object", + "properties": { + "stepIndex": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "zoom": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "number", + "minimum": 1, + "maximum": 3 + } + ] + } + }, + "required": ["stepIndex", "zoom"], + "additionalProperties": false + } + }, + "cards": { + "type": "object", + "properties": { + "intro": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + }, + "title": { + "type": "string", + "minLength": 1, + "maxLength": 80, + "pattern": "\\S" + }, + "subtitle": { + "anyOf": [ + { + "type": "string", + "minLength": 1, + "maxLength": 80, + "pattern": "\\S" + }, + { + "type": "null" + } + ] + } + }, + "additionalProperties": false + }, + "scenes": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + } + }, + "additionalProperties": false + }, + "outro": { + "anyOf": [ + { + "type": "object", + "properties": { + "title": { + "type": "string", + "minLength": 1, + "maxLength": 80, + "pattern": "\\S" + }, + "cta": { + "type": "string", + "minLength": 1, + "maxLength": 80, + "pattern": "\\S" + } + }, + "required": ["title"], + "additionalProperties": false + }, + { + "type": "null" + } + ] + } + }, + "additionalProperties": false + }, + "background": { + "anyOf": [ + { + "type": "object", + "properties": { + "preset": { + "type": "string", + "enum": ["ocean", "sunset", "forest", "dusk", "graphite", "paper"] + } + }, + "required": ["preset"], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "color": { + "type": "string", + "pattern": "^#[0-9a-fA-F]{6}$" + } + }, + "required": ["color"], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "gradient": { + "type": "object", + "properties": { + "from": { + "type": "string", + "pattern": "^#[0-9a-fA-F]{6}$" + }, + "to": { + "type": "string", + "pattern": "^#[0-9a-fA-F]{6}$" + }, + "angle": { + "type": "number", + "minimum": 0, + "maximum": 360, + "description": "Degrees, as in CSS linear-gradient: 0 runs towards the top, clockwise (90 towards the right)." + } + }, + "required": ["from", "to", "angle"], + "additionalProperties": false + } + }, + "required": ["gradient"], + "additionalProperties": false + } + ] + }, + "frame": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + }, + "radius": { + "type": "number", + "minimum": 0 + }, + "shadow": { + "type": "boolean" + } + }, + "additionalProperties": false + } + }, + "required": ["schemaVersion"], + "additionalProperties": false +} diff --git a/packages/core/src/edits.ts b/packages/core/src/edits.ts new file mode 100644 index 00000000..ba9f5a35 --- /dev/null +++ b/packages/core/src/edits.ts @@ -0,0 +1,160 @@ +import { z } from 'zod'; +import type { Issue } from './issues.ts'; +import { + BackgroundConfigSchema, + CardTextSchema, + FrameConfigSchema, +} from './project-config.ts'; +import { ZoomSchema } from './step.ts'; +import type { Timeline } from './timeline.ts'; + +/** The edits of a run, beside `timeline.json` in its directory (ADR-0020 §1). */ +export const RUN_EDITS_FILE = 'edits.json'; + +/** `render.endHoldMs`'s default: the tail a caption may reach into when none is given (spec 365). */ +const DEFAULT_TAIL_MS = 2_500; + +/** Timeline milliseconds: the engine clock of `timeline.json` (ADR-0020 §1). */ +const msSchema = z.number().int().nonnegative(); + +const MAX_CAPTIONS = 200; + +const EditedCaptionSchema = z + .strictObject({ + startMs: msSchema, + endMs: msSchema, + // The limit of a caption the page sets (ADR-0014). + text: z.string().trim().min(1).max(120), + }) + .refine((caption) => caption.endMs > caption.startMs, { + message: 'expected endMs to be after startMs', + path: ['endMs'], + }); + +/** Ordered by `startMs` and not overlapping. */ +const EditedCaptionsSchema = z + .array(EditedCaptionSchema) + .max(MAX_CAPTIONS) + .superRefine((captions, ctx) => { + for (const [index, caption] of captions.entries()) { + const previous = captions[index - 1]; + if (previous !== undefined && caption.startMs < previous.endMs) { + ctx.addIssue({ + code: 'custom', + message: 'expected captions ordered by startMs and not overlapping', + path: [index, 'startMs'], + }); + } + } + }); + +/** At most one entry per step. */ +const ZoomEditsSchema = z + .array( + z.strictObject({ + stepIndex: z.number().int().nonnegative(), + zoom: ZoomSchema, + }), + ) + .superRefine((entries, ctx) => { + const seen = new Set<number>(); + for (const [index, entry] of entries.entries()) { + if (seen.has(entry.stepIndex)) { + ctx.addIssue({ + code: 'custom', + message: `expected one zoom per step; step ${entry.stepIndex} is listed twice`, + path: [index, 'stepIndex'], + }); + } + seen.add(entry.stepIndex); + } + }); + +const frameFields = FrameConfigSchema.unwrap().shape; + +/** + * `edits.json` (spec 353): what the person changed on the website, applied by + * the renderer over the run's timeline and the project's `render.*`. Anything + * absent renders as configured. + */ +export const RunEditsSchema = z.strictObject({ + schemaVersion: z.literal(1), + // The complete caption list when present: it replaces the captions of the + // steps and of the page. `[]` means none. + captions: EditedCaptionsSchema.optional(), + // A step not listed keeps its timeline `zoom`. + zoom: ZoomEditsSchema.optional(), + cards: z + .strictObject({ + intro: z + .strictObject({ + enabled: z.boolean().optional(), + title: CardTextSchema.optional(), + // `null` removes the description from the card. + subtitle: CardTextSchema.nullable().optional(), + }) + .optional(), + scenes: z.strictObject({ enabled: z.boolean().optional() }).optional(), + // An object is the outro, even when the config has none; `null` removes it. + outro: z + .strictObject({ + title: CardTextSchema, + cta: CardTextSchema.optional(), + }) + .nullable() + .optional(), + }) + .optional(), + background: BackgroundConfigSchema.optional(), + frame: z + .strictObject({ + enabled: frameFields.enabled.removeDefault().optional(), + radius: frameFields.radius.removeDefault().optional(), + shadow: frameFields.shadow.removeDefault().optional(), + }) + .optional(), +}); +export type RunEdits = z.infer<typeof RunEditsSchema>; + +/** + * Checks parsed edits against the run's timeline (spec 353): a zoom only on a + * step whose event has a target box (ADR-0012 §2), and no caption past the + * end of the video. `tailMs` is the end hold the renderer keeps after the + * last event and its hold (`render.endHoldMs`). + */ +export function checkRunEdits( + edits: RunEdits, + timeline: Timeline, + { tailMs = DEFAULT_TAIL_MS }: { tailMs?: number } = {}, +): Issue[] { + const issues: Issue[] = []; + const events = new Map( + timeline.events.map((event) => [event.stepIndex, event]), + ); + for (const [index, entry] of (edits.zoom ?? []).entries()) { + const event = events.get(entry.stepIndex); + if (event?.target === undefined) { + issues.push({ + path: `zoom[${index}].stepIndex`, + code: 'zoom-no-target', + message: + event === undefined + ? `step ${entry.stepIndex} is not in the timeline` + : `step ${entry.stepIndex} (${event.action}) has no target to zoom on`, + }); + } + } + const last = timeline.events.at(-1); + const endMs = + (last === undefined ? 0 : last.endMs + (last.holdMs ?? 0)) + tailMs; + for (const [index, caption] of (edits.captions ?? []).entries()) { + if (caption.endMs > endMs) { + issues.push({ + path: `captions[${index}].endMs`, + code: 'caption-out-of-range', + message: `expected the caption to end by ${endMs} ms, the end of the video`, + }); + } + } + return issues; +} diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index a9962be4..b26dd8ab 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -1,5 +1,6 @@ export * from './common.ts'; export * from './config-template.ts'; +export * from './edits.ts'; export { type ExpandedStep, expandScenario, diff --git a/packages/core/src/json-schema.ts b/packages/core/src/json-schema.ts index 1f051a24..697a8e31 100644 --- a/packages/core/src/json-schema.ts +++ b/packages/core/src/json-schema.ts @@ -1,4 +1,5 @@ import { z } from 'zod'; +import { RunEditsSchema } from './edits.ts'; import { FragmentSchema } from './fragment.ts'; import { ProjectConfigSchema } from './project-config.ts'; import { ScenarioSchema } from './scenario.ts'; @@ -12,6 +13,7 @@ export function jsonSchemas(): Record<string, z.core.JSONSchema.BaseSchema> { return { 'scenario.schema.json': z.toJSONSchema(ScenarioSchema, options), 'fragment.schema.json': z.toJSONSchema(FragmentSchema, options), + 'edits.schema.json': z.toJSONSchema(RunEditsSchema, options), 'project-config.schema.json': withoutUriFormat( z.toJSONSchema(ProjectConfigSchema, options), ), diff --git a/packages/core/src/project-config.ts b/packages/core/src/project-config.ts index 6a6b7d30..1f6f4b8a 100644 --- a/packages/core/src/project-config.ts +++ b/packages/core/src/project-config.ts @@ -61,7 +61,7 @@ export type FrameConfig = z.infer<typeof FrameConfigSchema>; const CardDurationSchema = z.number().int().min(500).max(10_000); -const CardTextSchema = z +export const CardTextSchema = z .string() .min(1) .max(80) diff --git a/packages/core/test/edits.spec.ts b/packages/core/test/edits.spec.ts new file mode 100644 index 00000000..f43bbf43 --- /dev/null +++ b/packages/core/test/edits.spec.ts @@ -0,0 +1,167 @@ +import { describe, expect, it } from 'vitest'; +import { + checkRunEdits, + type RunEdits, + RunEditsSchema, + type Timeline, + TimelineSchema, +} from '../src/index.ts'; + +const timeline: Timeline = TimelineSchema.parse({ + schemaVersion: 1, + viewport: { width: 1280, height: 720 }, + deviceScaleFactor: 2, + videoFile: 'source.webm', + events: [ + { stepIndex: 0, action: 'navigate', startMs: 0, endMs: 800 }, + { + stepIndex: 1, + action: 'click', + startMs: 800, + endMs: 1400, + target: { box: { x: 100, y: 200, width: 80, height: 32 } }, + }, + { stepIndex: 2, action: 'wait', startMs: 1400, endMs: 2400, holdMs: 500 }, + ], +}); + +const caption = (startMs: number, endMs: number, text = 'Hello') => ({ + startMs, + endMs, + text, +}); + +describe('RunEditsSchema', () => { + it('parses a minimal file', () => { + expect(RunEditsSchema.parse({ schemaVersion: 1 })).toEqual({ + schemaVersion: 1, + }); + }); + + it('parses every kind of edit', () => { + const edits = { + schemaVersion: 1, + captions: [caption(0, 500), caption(500, 900, 'Next')], + zoom: [ + { stepIndex: 1, zoom: 2 }, + { stepIndex: 3, zoom: false }, + ], + cards: { + intro: { enabled: true, title: 'Sign up', subtitle: null }, + scenes: { enabled: false }, + outro: { title: 'Try it', cta: 'example.com' }, + }, + background: { color: '#112233' }, + frame: { enabled: true, radius: 0, shadow: false }, + }; + expect(RunEditsSchema.parse(edits)).toEqual(edits); + }); + + it('trims caption text', () => { + const edits = RunEditsSchema.parse({ + schemaVersion: 1, + captions: [caption(0, 10, ' Hi ')], + }); + expect(edits.captions?.[0]?.text).toBe('Hi'); + }); + + it.each([ + ['an unknown key', { schemaVersion: 1, trim: { startMs: 0 } }], + ['schemaVersion 2', { schemaVersion: 2 }], + ['an empty caption span', { captions: [caption(100, 100)] }], + ['a caption ending before it starts', { captions: [caption(100, 50)] }], + ['overlapping captions', { captions: [caption(0, 200), caption(100, 300)] }], + ['unordered captions', { captions: [caption(500, 600), caption(0, 100)] }], + [ + '201 captions', + { + captions: Array.from({ length: 201 }, (_, index) => + caption(index * 10, index * 10 + 5), + ), + }, + ], + ['a 121-character caption', { captions: [caption(0, 10, 'x'.repeat(121))] }], + ['a blank caption', { captions: [caption(0, 10, ' ')] }], + ['a fractional time', { captions: [caption(0.5, 10)] }], + [ + 'a duplicate stepIndex', + { + zoom: [ + { stepIndex: 1, zoom: true }, + { stepIndex: 1, zoom: false }, + ], + }, + ], + ['zoom 4', { zoom: [{ stepIndex: 1, zoom: 4 }] }], + ['an outro without title', { cards: { outro: { cta: 'example.com' } } }], + ['an 81-character card title', { cards: { intro: { title: 'x'.repeat(81) } } }], + ['a negative frame radius', { frame: { radius: -1 } }], + ['a frame margin', { frame: { marginRatio: 0.1 } }], + ['an image background', { background: { image: 'a.png' } }], + ])('rejects %s', (_, edits) => { + expect( + RunEditsSchema.safeParse({ schemaVersion: 1, ...edits }).success, + ).toBe(false); + }); + + it('accepts 200 captions', () => { + const captions = Array.from({ length: 200 }, (_, index) => + caption(index * 10, index * 10 + 5), + ); + expect( + RunEditsSchema.safeParse({ schemaVersion: 1, captions }).success, + ).toBe(true); + }); +}); + +describe('checkRunEdits', () => { + const check = (edits: Omit<RunEdits, 'schemaVersion'>, tailMs?: number) => + checkRunEdits( + RunEditsSchema.parse({ schemaVersion: 1, ...edits }), + timeline, + tailMs === undefined ? {} : { tailMs }, + ); + + it('accepts a zoom on a click with a box', () => { + expect(check({ zoom: [{ stepIndex: 1, zoom: true }] })).toEqual([]); + }); + + it('reports zoom-no-target for a wait step and for a step not in the timeline', () => { + expect( + check({ + zoom: [ + { stepIndex: 2, zoom: true }, + { stepIndex: 1, zoom: false }, + { stepIndex: 9, zoom: 2 }, + ], + }), + ).toEqual([ + expect.objectContaining({ + path: 'zoom[0].stepIndex', + code: 'zoom-no-target', + }), + expect.objectContaining({ + path: 'zoom[2].stepIndex', + code: 'zoom-no-target', + }), + ]); + }); + + it('lets a caption reach the end hold after the last event and its hold', () => { + // The last event ends at 2400, holds 500, and the default tail is 2500. + expect(check({ captions: [caption(0, 5_400)] })).toEqual([]); + expect(check({ captions: [caption(0, 5_401)] })).toEqual([ + expect.objectContaining({ + path: 'captions[0].endMs', + code: 'caption-out-of-range', + }), + ]); + }); + + it('measures the tail the renderer keeps', () => { + expect(check({ captions: [caption(0, 3_000)] }, 0)).toEqual([ + expect.objectContaining({ code: 'caption-out-of-range' }), + ]); + expect(check({ captions: [caption(0, 2_900)] }, 0)).toEqual([]); + }); +}); diff --git a/packages/core/test/json-schema.spec.ts b/packages/core/test/json-schema.spec.ts index e7f5a3c5..4a82c30d 100644 --- a/packages/core/test/json-schema.spec.ts +++ b/packages/core/test/json-schema.spec.ts @@ -6,6 +6,7 @@ import { jsonSchemas } from '../src/index.ts'; describe('committed JSON Schemas', () => { it('publishes the scenario, fragment and project config schemas', () => { expect(Object.keys(jsonSchemas()).sort()).toEqual([ + 'edits.schema.json', 'fragment.schema.json', 'project-config.schema.json', 'scenario.schema.json', From 23579f1b3d9b156aa0f56610ad831f021cc45090 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 17:50:11 +0100 Subject: [PATCH 46/71] feat(core): schedule block in the project config and lastDueSlot (spec 361) --- .../core/schemas/project-config.schema.json | 32 +++ packages/core/src/index.ts | 1 + packages/core/src/project-config.ts | 92 +++++++++ packages/core/src/schedule.ts | 140 +++++++++++++ packages/core/test/schedule.spec.ts | 195 ++++++++++++++++++ 5 files changed, 460 insertions(+) create mode 100644 packages/core/src/schedule.ts create mode 100644 packages/core/test/schedule.spec.ts diff --git a/packages/core/schemas/project-config.schema.json b/packages/core/schemas/project-config.schema.json index ba2ef8eb..b24af05e 100644 --- a/packages/core/schemas/project-config.schema.json +++ b/packages/core/schemas/project-config.schema.json @@ -375,6 +375,38 @@ } }, "additionalProperties": false + }, + "schedule": { + "type": "object", + "properties": { + "cadence": { + "type": "string", + "enum": ["daily", "weekdays", "weekly"], + "description": "daily, weekdays (Monday to Friday) or weekly (on weekday)." + }, + "weekday": { + "description": "The day of a weekly schedule; only with cadence weekly.", + "type": "string", + "enum": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"] + }, + "at": { + "type": "string", + "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", + "description": "HH:MM, 24-hour, in the time zone of the machine the runner runs on." + }, + "exclude": { + "description": "Scenario ids, relative to the project root, the scheduled pass leaves out.", + "maxItems": 100, + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 255 + } + } + }, + "required": ["cadence", "at"], + "additionalProperties": false } }, "required": ["baseUrl"], diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index a9962be4..e7ca6c4a 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -12,5 +12,6 @@ export * from './parse.ts'; export * from './project-config.ts'; export * from './run-result.ts'; export * from './scenario.ts'; +export { lastDueSlot, nextDueSlot } from './schedule.ts'; export * from './step.ts'; export * from './timeline.ts'; diff --git a/packages/core/src/project-config.ts b/packages/core/src/project-config.ts index 6a6b7d30..2cd47de3 100644 --- a/packages/core/src/project-config.ts +++ b/packages/core/src/project-config.ts @@ -269,6 +269,97 @@ export const RenderConfigSchema = z .prefault({}); export type RenderConfig = z.infer<typeof RenderConfigSchema>; +/** How often a scheduled check pass runs (spec 361, Decision 1). */ +export const SCHEDULE_CADENCES = ['daily', 'weekdays', 'weekly'] as const; +export type ScheduleCadence = (typeof SCHEDULE_CADENCES)[number]; + +/** The day of a `weekly` schedule, Monday first. */ +export const SCHEDULE_WEEKDAYS = [ + 'mon', + 'tue', + 'wed', + 'thu', + 'fri', + 'sat', + 'sun', +] as const; +export type ScheduleWeekday = (typeof SCHEDULE_WEEKDAYS)[number]; + +/** A scheduled pass leaves out at most this many scenarios (spec 361, Decision 1). */ +export const SCHEDULE_EXCLUDE_MAX = 100; + +/** + * Spec 247's scenario id: a `/`-separated path inside `demoflow/`, ending in + * `.demo.json`, with no empty, `.` or `..` segment and no `\`, `:` or control + * character. + */ +const ScheduleScenarioIdSchema = z + .string() + .min(1) + .max(255) + .refine( + (id) => + id.startsWith('demoflow/') && + id.endsWith('.demo.json') && + // biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what it refuses. + !/[\u0000-\u001f\u007f\\:]/.test(id) && + id + .split('/') + .every( + (segment) => segment !== '' && segment !== '.' && segment !== '..', + ), + 'expected a scenario id such as demoflow/sign-in.demo.json', + ); + +/** + * `schedule` (spec 361, ADR-0021 §5): the runner daemon runs a check pass of + * the project at `at`, machine-local time, on the days of `cadence`. + */ +export const ScheduleConfigSchema = z + .strictObject({ + cadence: z.enum(SCHEDULE_CADENCES).meta({ + description: 'daily, weekdays (Monday to Friday) or weekly (on weekday).', + }), + weekday: z.enum(SCHEDULE_WEEKDAYS).optional().meta({ + description: 'The day of a weekly schedule; only with cadence weekly.', + }), + at: z + .string() + .regex( + /^([01]\d|2[0-3]):[0-5]\d$/, + 'expected a 24-hour time such as 09:30', + ) + .meta({ + description: + 'HH:MM, 24-hour, in the time zone of the machine the runner runs on.', + }), + exclude: z + .array(ScheduleScenarioIdSchema) + .max(SCHEDULE_EXCLUDE_MAX) + .optional() + .meta({ + description: + 'Scenario ids, relative to the project root, the scheduled pass leaves out.', + }), + }) + .superRefine(({ cadence, weekday }, ctx) => { + if (cadence === 'weekly' && weekday === undefined) { + ctx.addIssue({ + code: 'custom', + message: 'expected a weekday with cadence weekly', + path: ['weekday'], + }); + } + if (cadence !== 'weekly' && weekday !== undefined) { + ctx.addIssue({ + code: 'custom', + message: `expected no weekday with cadence ${cadence}`, + path: ['weekday'], + }); + } + }); +export type ScheduleConfig = z.infer<typeof ScheduleConfigSchema>; + const PORT_TEMPLATE = // biome-ignore lint/suspicious/noTemplateCurlyInString: `${PORT}` is the config's own syntax. '${PORT} is the port of the run: --port, else PORT from the environment, else the default in ${PORT:-3000}. $${ is a literal ${.'; @@ -306,6 +397,7 @@ export const ProjectConfigSchema = z 'Where the fragments scenarios include live, relative to the project root. Default demoflow/fragments.', }), render: RenderConfigSchema, + schedule: ScheduleConfigSchema.optional(), }) .transform(({ allowedOrigins, ...config }) => { const origin = new URL(config.baseUrl).origin; diff --git a/packages/core/src/schedule.ts b/packages/core/src/schedule.ts new file mode 100644 index 00000000..6e91f751 --- /dev/null +++ b/packages/core/src/schedule.ts @@ -0,0 +1,140 @@ +import { SCHEDULE_WEEKDAYS, type ScheduleConfig } from './project-config.ts'; + +const MINUTE_MS = 60_000; +const DAY_MS = 24 * 60 * MINUTE_MS; +/** A weekly slot is at most a week away; a day more covers a DST shift. */ +const SEARCH_DAYS = 8; + +const formatters = new Map<string, Intl.DateTimeFormat>(); + +function formatter(zone: string): Intl.DateTimeFormat { + let format = formatters.get(zone); + if (format === undefined) { + // Throws a RangeError for a zone the runtime does not know. + format = new Intl.DateTimeFormat('en-US', { + timeZone: zone, + hourCycle: 'h23', + year: 'numeric', + month: 'numeric', + day: 'numeric', + hour: 'numeric', + minute: 'numeric', + }); + formatters.set(zone, format); + } + return format; +} + +/** The wall clock of `zone` at instant `at`, as if it were UTC, to the minute. */ +function wallClock(at: number, zone: string): number { + const fields: Record<string, number> = {}; + for (const part of formatter(zone).formatToParts(at)) { + if (part.type !== 'literal') fields[part.type] = Number(part.value); + } + return Date.UTC( + fields.year ?? 0, + (fields.month ?? 1) - 1, + fields.day ?? 1, + fields.hour ?? 0, + fields.minute ?? 0, + ); +} + +/** The earliest whole minute whose wall clock in `zone` is at or past `wall`. */ +function firstInstantAt(wall: number, zone: string): number { + // UTC offsets lie within ±14 h, so the answer is in this range. + let low = Math.floor((wall - 15 * 60 * MINUTE_MS) / MINUTE_MS); + let high = Math.ceil((wall + 15 * 60 * MINUTE_MS) / MINUTE_MS); + while (low < high) { + const middle = Math.floor((low + high) / 2); + if (wallClock(middle * MINUTE_MS, zone) >= wall) high = middle; + else low = middle + 1; + } + return low * MINUTE_MS; +} + +/** + * The instant of wall time `wall` in `zone` (spec 361, Decision 2): a time + * that repeats when the clocks go back is its first occurrence, and one that + * does not exist when they go forward is the next valid minute. + */ +function instantOf(wall: number, zone: string): number { + // Offsets a day either side: at most one transition lies between them. + const offsets = new Set( + [wall - DAY_MS, wall + DAY_MS].map((at) => wallClock(at, zone) - at), + ); + const exact = [...offsets] + .map((offset) => wall - offset) + .filter((at) => wallClock(at, zone) === wall); + return exact.length > 0 ? Math.min(...exact) : firstInstantAt(wall, zone); +} + +/** Monday 0 … Sunday 6, as `SCHEDULE_WEEKDAYS` lists them. */ +function weekdayOf(day: number): number { + return (new Date(day).getUTCDay() + 6) % 7; +} + +function runsOn(schedule: ScheduleConfig, day: number): boolean { + const weekday = weekdayOf(day); + switch (schedule.cadence) { + case 'daily': + return true; + case 'weekdays': + return weekday < 5; + case 'weekly': + return SCHEDULE_WEEKDAYS[weekday] === schedule.weekday; + } +} + +/** The instant of the slot on local day `day` (midnight, as UTC), or `null`. */ +function slotOn( + schedule: ScheduleConfig, + day: number, + zone: string, +): number | null { + if (!runsOn(schedule, day)) return null; + const [hours, minutes] = schedule.at.split(':').map(Number); + return instantOf( + day + ((hours ?? 0) * 60 + (minutes ?? 0)) * MINUTE_MS, + zone, + ); +} + +/** Local midnight of `now` in `zone`, as UTC. */ +function localDay(now: number, zone: string): number { + const wall = wallClock(now, zone); + return wall - (wall % DAY_MS); +} + +/** + * Spec 361, Decision 2: the latest slot of `schedule` at or before `now`, in + * milliseconds since the epoch, for a machine in time zone `zone` (an IANA + * name). A pass is due when this is later than the last pass's start. + */ +export function lastDueSlot( + schedule: ScheduleConfig, + now: number, + zone: string, +): number { + const today = localDay(now, zone); + for (let back = 0; back <= SEARCH_DAYS; back++) { + const slot = slotOn(schedule, today - back * DAY_MS, zone); + if (slot !== null && slot <= now) return slot; + } + // Unreachable for a valid schedule: every cadence runs once a week. + throw new RangeError('no slot in the last week'); +} + +/** The earliest slot of `schedule` after `now`: what `runner status` shows. */ +export function nextDueSlot( + schedule: ScheduleConfig, + now: number, + zone: string, +): number { + const today = localDay(now, zone); + for (let ahead = 0; ahead <= SEARCH_DAYS; ahead++) { + const slot = slotOn(schedule, today + ahead * DAY_MS, zone); + if (slot !== null && slot > now) return slot; + } + throw new RangeError('no slot in the next week'); +} diff --git a/packages/core/test/schedule.spec.ts b/packages/core/test/schedule.spec.ts new file mode 100644 index 00000000..5567e6a2 --- /dev/null +++ b/packages/core/test/schedule.spec.ts @@ -0,0 +1,195 @@ +import { describe, expect, it } from 'vitest'; +import { + lastDueSlot, + nextDueSlot, + parseProjectConfig, + type ScheduleConfig, +} from '../src/index.ts'; + +const at = (iso: string) => Date.parse(iso); +const iso = (ms: number) => new Date(ms).toISOString(); + +function parsed(schedule: unknown) { + return parseProjectConfig({ baseUrl: 'http://localhost:3000', schedule }); +} + +describe('schedule in the project config (spec 361, Decision 1)', () => { + it.each([ + { cadence: 'daily', at: '09:30' }, + { cadence: 'weekdays', at: '00:00' }, + { + cadence: 'weekly', + weekday: 'sun', + at: '23:59', + exclude: ['demoflow/wip.demo.json', 'demoflow/a/b.demo.json'], + }, + ])('accepts %o as written', (schedule) => { + const result = parsed(schedule); + expect(result.ok && result.value.schedule).toEqual(schedule); + }); + + it('leaves schedule out when the file has none', () => { + const result = parseProjectConfig({ baseUrl: 'http://localhost:3000' }); + expect(result.ok && 'schedule' in result.value).toBe(false); + }); + + it.each([ + ['weekly without a weekday', { cadence: 'weekly', at: '09:30' }], + ['a weekday with daily', { cadence: 'daily', weekday: 'mon', at: '09:30' }], + [ + 'a weekday with weekdays', + { cadence: 'weekdays', weekday: 'fri', at: '09:30' }, + ], + ['an hour without its zero', { cadence: 'daily', at: '9:30' }], + ['24:00', { cadence: 'daily', at: '24:00' }], + ['seconds', { cadence: 'daily', at: '09:30:00' }], + ['an unknown cadence', { cadence: 'hourly', at: '09:30' }], + ['an unknown key', { cadence: 'daily', at: '09:30', zone: 'UTC' }], + [ + 'an exclude outside demoflow/', + { cadence: 'daily', at: '09:30', exclude: ['wip.demo.json'] }, + ], + [ + 'an exclude with ..', + { + cadence: 'daily', + at: '09:30', + exclude: ['demoflow/../wip.demo.json'], + }, + ], + [ + 'more than 100 excludes', + { + cadence: 'daily', + at: '09:30', + exclude: Array.from( + { length: 101 }, + (_, i) => `demoflow/s${i}.demo.json`, + ), + }, + ], + ])('refuses %s', (_, schedule) => { + expect(parsed(schedule).ok).toBe(false); + }); +}); + +const daily: ScheduleConfig = { cadence: 'daily', at: '09:30' }; +const weekdays: ScheduleConfig = { cadence: 'weekdays', at: '09:30' }; +const weekly: ScheduleConfig = { + cadence: 'weekly', + weekday: 'wed', + at: '18:00', +}; + +describe('lastDueSlot (spec 361, Decision 2)', () => { + it('is today once the time has come, else yesterday (daily)', () => { + expect(iso(lastDueSlot(daily, at('2026-10-21T09:30:00Z'), 'UTC'))).toBe( + '2026-10-21T09:30:00.000Z', + ); + expect(iso(lastDueSlot(daily, at('2026-10-21T09:29:59Z'), 'UTC'))).toBe( + '2026-10-20T09:30:00.000Z', + ); + }); + + it('follows the zone of the machine', () => { + // 09:30 in Kyiv (UTC+3 in summer) is 06:30 UTC. + expect( + iso(lastDueSlot(daily, at('2026-07-01T07:00:00Z'), 'Europe/Kyiv')), + ).toBe('2026-07-01T06:30:00.000Z'); + }); + + it('skips the weekend (weekdays)', () => { + // Monday 2026-10-26 08:00: the last slot is Friday's. + expect(iso(lastDueSlot(weekdays, at('2026-10-26T08:00:00Z'), 'UTC'))).toBe( + '2026-10-23T09:30:00.000Z', + ); + // Sunday evening: still Friday's. + expect(iso(lastDueSlot(weekdays, at('2026-10-25T20:00:00Z'), 'UTC'))).toBe( + '2026-10-23T09:30:00.000Z', + ); + // Monday after the time: Monday's. + expect(iso(lastDueSlot(weekdays, at('2026-10-26T10:00:00Z'), 'UTC'))).toBe( + '2026-10-26T09:30:00.000Z', + ); + }); + + it('is the last weekday given (weekly)', () => { + // Wednesday 2026-10-21 17:59: last week's Wednesday. + expect(iso(lastDueSlot(weekly, at('2026-10-21T17:59:00Z'), 'UTC'))).toBe( + '2026-10-14T18:00:00.000Z', + ); + expect(iso(lastDueSlot(weekly, at('2026-10-21T18:00:00Z'), 'UTC'))).toBe( + '2026-10-21T18:00:00.000Z', + ); + expect(iso(lastDueSlot(weekly, at('2026-10-27T12:00:00Z'), 'UTC'))).toBe( + '2026-10-21T18:00:00.000Z', + ); + }); + + describe.each([ + { + zone: 'Europe/Berlin', + // 2026-03-29: 02:00 CET → 03:00 CEST (01:00 UTC). + spring: { day: '2026-03-29', instant: '2026-03-29T01:00:00.000Z' }, + // 2026-10-25: 03:00 CEST → 02:00 CET; 02:30 is first 00:30 UTC. + fall: { at: '02:30', instant: '2026-10-25T00:30:00.000Z' }, + }, + { + zone: 'America/New_York', + // 2026-03-08: 02:00 EST → 03:00 EDT (07:00 UTC). + spring: { day: '2026-03-08', instant: '2026-03-08T07:00:00.000Z' }, + // 2026-11-01: 02:00 EDT → 01:00 EST; 01:30 is first 05:30 UTC. + fall: { at: '01:30', instant: '2026-11-01T05:30:00.000Z' }, + }, + ])('across DST in $zone', ({ zone, spring, fall }) => { + const gap: ScheduleConfig = { cadence: 'daily', at: '02:30' }; + const repeated: ScheduleConfig = { cadence: 'daily', at: fall.at }; + + it('runs a time that does not exist at the next valid minute', () => { + const slot = lastDueSlot(gap, at(`${spring.day}T12:00:00Z`), zone); + expect(iso(slot)).toBe(spring.instant); + // Just before the jump, the slot is still the day before's. + expect(lastDueSlot(gap, slot - 60_000, zone)).toBeLessThan(slot); + }); + + it('runs a time that repeats once, at its first occurrence', () => { + const first = at(fall.instant); + const second = first + 60 * 60_000; + expect(iso(lastDueSlot(repeated, first, zone))).toBe(fall.instant); + // During and after the repeat, the slot stays the first one. + expect(lastDueSlot(repeated, second, zone)).toBe(first); + expect(lastDueSlot(repeated, second + 6 * 60 * 60_000, zone)).toBe(first); + // The day the clocks go back is 25 hours long. + expect(nextDueSlot(repeated, first, zone)).toBe(first + 25 * 60 * 60_000); + }); + + it('keeps the wall time on the days either side', () => { + const before = lastDueSlot( + daily, + at(`${spring.day}T00:00:00Z`) - 86_400_000, + zone, + ); + const after = lastDueSlot( + daily, + at(`${spring.day}T00:00:00Z`) + 2 * 86_400_000, + zone, + ); + // Three days apart, one of them 23 hours long. + expect(after - before).toBe(3 * 86_400_000 - 60 * 60_000); + }); + }); +}); + +describe('nextDueSlot', () => { + it('is the first slot after now', () => { + expect(iso(nextDueSlot(daily, at('2026-10-21T09:30:00Z'), 'UTC'))).toBe( + '2026-10-22T09:30:00.000Z', + ); + expect(iso(nextDueSlot(weekdays, at('2026-10-23T10:00:00Z'), 'UTC'))).toBe( + '2026-10-26T09:30:00.000Z', + ); + expect(iso(nextDueSlot(weekly, at('2026-10-21T18:00:00Z'), 'UTC'))).toBe( + '2026-10-28T18:00:00.000Z', + ); + }); +}); From 6959fe0e85daf67363ee354e7a4f2339fdac4642 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 17:50:18 +0100 Subject: [PATCH 47/71] feat(renderer): apply a run's edits.json at render buildRenderPlan reads edits.json beside timeline.json, validates it with RunEditsSchema and checkRunEdits, and fails the plan with a message naming the file when either check fails. planRender applies the edits: an edited caption list replaces the step and page captions, zoom overrides replace each step's zoom before the camera is planned, the background replaces the configured one, and the window fields are merged over render.frame. placeCards switches the intro and scenes and replaces the intro and outro text. A failed run still gets no outro, and a run without edits.json plans exactly as before (spec 353). --- packages/core/test/edits.spec.ts | 15 +- packages/renderer/src/plan/cards.ts | 34 +- packages/renderer/src/plan/plan.ts | 118 ++++- packages/renderer/test/plan/build.spec.ts | 51 ++- packages/renderer/test/plan/edits.spec.ts | 501 ++++++++++++++++++++++ 5 files changed, 695 insertions(+), 24 deletions(-) create mode 100644 packages/renderer/test/plan/edits.spec.ts diff --git a/packages/core/test/edits.spec.ts b/packages/core/test/edits.spec.ts index f43bbf43..9c6bac2b 100644 --- a/packages/core/test/edits.spec.ts +++ b/packages/core/test/edits.spec.ts @@ -70,7 +70,10 @@ describe('RunEditsSchema', () => { ['schemaVersion 2', { schemaVersion: 2 }], ['an empty caption span', { captions: [caption(100, 100)] }], ['a caption ending before it starts', { captions: [caption(100, 50)] }], - ['overlapping captions', { captions: [caption(0, 200), caption(100, 300)] }], + [ + 'overlapping captions', + { captions: [caption(0, 200), caption(100, 300)] }, + ], ['unordered captions', { captions: [caption(500, 600), caption(0, 100)] }], [ '201 captions', @@ -80,7 +83,10 @@ describe('RunEditsSchema', () => { ), }, ], - ['a 121-character caption', { captions: [caption(0, 10, 'x'.repeat(121))] }], + [ + 'a 121-character caption', + { captions: [caption(0, 10, 'x'.repeat(121))] }, + ], ['a blank caption', { captions: [caption(0, 10, ' ')] }], ['a fractional time', { captions: [caption(0.5, 10)] }], [ @@ -94,7 +100,10 @@ describe('RunEditsSchema', () => { ], ['zoom 4', { zoom: [{ stepIndex: 1, zoom: 4 }] }], ['an outro without title', { cards: { outro: { cta: 'example.com' } } }], - ['an 81-character card title', { cards: { intro: { title: 'x'.repeat(81) } } }], + [ + 'an 81-character card title', + { cards: { intro: { title: 'x'.repeat(81) } } }, + ], ['a negative frame radius', { frame: { radius: -1 } }], ['a frame margin', { frame: { marginRatio: 0.1 } }], ['an image background', { background: { image: 'a.png' } }], diff --git a/packages/renderer/src/plan/cards.ts b/packages/renderer/src/plan/cards.ts index 2c879eaa..44d1dd47 100644 --- a/packages/renderer/src/plan/cards.ts +++ b/packages/renderer/src/plan/cards.ts @@ -1,4 +1,9 @@ -import type { Annotation, CardsConfig, TimelineEvent } from '@demoflow/core'; +import type { + Annotation, + CardsConfig, + RunEdits, + TimelineEvent, +} from '@demoflow/core'; import { cameraStateAt, cursorAt, followAt, maskBoxAt } from './frame.ts'; import { type CardSlot, shiftPastCards } from './time-map.ts'; import type { @@ -20,6 +25,8 @@ export type PlacedCard = CardSpec & CardSlot; * The cards of a run, in page order (spec 108): the intro at the start, a * card on every `scene` marker before the page ends, and — on a successful * run with a title — the outro after it. `out` maps timeline ms to page ms. + * `edits` (spec 353) switch cards and replace their text; without a config + * there are no cards, edited or not. */ export function placeCards(input: { config?: CardsConfig; @@ -31,22 +38,27 @@ export function placeCards(input: { scenarioName: string; description?: string; failed: boolean; + edits?: RunEdits['cards']; }): PlacedCard[] { - const { config, events, out, pageEndMs } = input; + const { config, events, out, pageEndMs, edits } = input; const annotations = input.annotations ?? []; if (config === undefined) return []; const cards: Omit<PlacedCard, 'startMs'>[] = []; - if (config.intro.enabled) { - const subtitle = input.description?.trim(); + if (edits?.intro?.enabled ?? config.intro.enabled) { + // `null` removes the description; absent keeps it. + const subtitle = + edits?.intro?.subtitle === null + ? undefined + : (edits?.intro?.subtitle ?? input.description)?.trim(); cards.push({ kind: 'intro', atMs: 0, durationMs: config.intro.durationMs, - title: input.scenarioName, + title: edits?.intro?.title ?? input.scenarioName, ...(subtitle === undefined || subtitle === '' ? {} : { subtitle }), }); } - if (config.scenes.enabled) { + if (edits?.scenes?.enabled ?? config.scenes.enabled) { // Scenario markers, then the page's own scenes (#201); stable, so at an // equal time a marker comes first. Both give the same card. const scenes = [ @@ -73,8 +85,14 @@ export function placeCards(input: { }); } } - const { outro } = config; - if (!input.failed && outro.title !== undefined) { + // An edited outro is the outro whatever the config says; `null` removes it. + const outro = + edits?.outro === undefined + ? config.outro + : edits.outro === null + ? undefined + : { ...edits.outro, durationMs: config.outro.durationMs }; + if (!input.failed && outro?.title !== undefined) { cards.push({ kind: 'outro', atMs: pageEndMs, diff --git a/packages/renderer/src/plan/plan.ts b/packages/renderer/src/plan/plan.ts index 8c1781e9..40af886f 100644 --- a/packages/renderer/src/plan/plan.ts +++ b/packages/renderer/src/plan/plan.ts @@ -3,8 +3,13 @@ import path from 'node:path'; import { type Annotation, type Box, + checkRunEdits, FrameConfigSchema, + formatPath, type RenderFormat, + RUN_EDITS_FILE, + type RunEdits, + RunEditsSchema, type RunResult, RunResultSchema, SquareConfigSchema, @@ -52,6 +57,8 @@ import type { export const PLAN_INPUTS = { timeline: 'timeline.json', result: 'result.json', + /** Optional: a run without it renders as recorded (ADR-0020 §1). */ + edits: RUN_EDITS_FILE, } as const; /** The Playwright video leads the engine clock by ~100 ms (#3, measured −90…−123 ms). */ @@ -120,12 +127,16 @@ export interface PlanInput { source: VideoProbe; /** The source time of the first frame after `timeline.syncMark`, when it was found. */ syncClearMs?: number; + /** The run's `edits.json`, already checked against the timeline (spec 353). */ + edits?: RunEdits; } /** * Reads a run directory and plans its video: `timeline.json`, `result.json`, - * one FFmpeg pass over the source (size, frame rate, frozen stretches) and, - * when the timeline has a sync mark, one over its start to find the mark. + * `edits.json` when there is one, one FFmpeg pass over the source (size, + * frame rate, frozen stretches) and, when the timeline has a sync mark, one + * over its start to find the mark. Edits that fail their schema or do not fit + * the timeline fail the plan: a render that drops them would look like a bug. */ export async function buildRenderPlan( runDir: string, @@ -137,6 +148,11 @@ export async function buildRenderPlan( const result = RunResultSchema.parse( await readJson(path.join(runDir, PLAN_INPUTS.result)), ); + const edits = await readEdits( + path.join(runDir, PLAN_INPUTS.edits), + timeline, + options.endHoldMs ?? DEFAULTS.endHoldMs, + ); const videoFile = path.join(runDir, timeline.videoFile); const source = await probeVideo(videoFile, { freezes: { @@ -153,11 +169,52 @@ export async function buildRenderPlan( result, source, ...(syncClearMs === undefined ? {} : { syncClearMs }), + ...(edits === undefined ? {} : { edits }), }, options, ); } +/** The run's edits, or `undefined` when it has no `edits.json`. */ +async function readEdits( + file: string, + timeline: Timeline, + tailMs: number, +): Promise<RunEdits | undefined> { + let text: string; + try { + text = await readFile(file, 'utf8'); + } catch (error) { + if (isNotFound(error)) return undefined; + throw error; + } + const name = PLAN_INPUTS.edits; + let json: unknown; + try { + json = JSON.parse(text); + } catch (error) { + throw new Error(`${name} is not JSON: ${(error as Error).message}`); + } + const parsed = RunEditsSchema.safeParse(json); + if (!parsed.success) { + const [issue] = parsed.error.issues; + throw new Error( + `${name} is invalid at ${formatPath(issue.path) || '(root)'}: ${issue.message}`, + ); + } + const [issue] = checkRunEdits(parsed.data, timeline, { tailMs }); + if (issue !== undefined) { + throw new Error( + `${name} does not fit the run at ${issue.path}: ${issue.message}`, + ); + } + return parsed.data; +} + +function isNotFound(error: unknown): boolean { + return error instanceof Error && Reflect.get(error, 'code') === 'ENOENT'; +} + async function readJson(file: string): Promise<unknown> { return JSON.parse(await readFile(file, 'utf8')); } @@ -167,7 +224,7 @@ export function planRender( input: PlanInput, options: RenderPlanOptions = {}, ): RenderPlan { - const { timeline, result, source } = input; + const { timeline, result, source, edits } = input; // Measured on the sync mark when it was found (#19); otherwise the defaults. const measuredMs = timeline.syncMark === undefined @@ -195,15 +252,20 @@ export function planRender( fps: options.output?.fps ?? DEFAULTS.output.fps, }; const viewport = timeline.viewport; - const frameConfig = FrameConfigSchema.parse(options.frame ?? {}); + // Edited style: the background replaces the config's, the window's fields + // replace the config's one by one (spec 353, Decision 5). + const frameConfig = FrameConfigSchema.parse({ + ...options.frame, + ...edits?.frame, + }); + const background = edits?.background ?? + options.background ?? { preset: 'ocean' }; // The radius and margin are given at 1080p and follow the output height. const frame: FrameSpec | undefined = frameConfig.enabled ? { radius: (frameConfig.radius * output.height) / 1080, shadow: frameConfig.shadow, - background: resolveBackground( - options.background ?? { preset: 'ocean' }, - ), + background: resolveBackground(background), } : undefined; const fit = @@ -216,7 +278,7 @@ export function planRender( options.zoom ?? (sourceScale >= 2 ? DEFAULTS.zoom : DEFAULTS.zoomOnLowResSource); - const events = timeline.events; + const events = withZoomEdits(timeline.events, edits?.zoom ?? []); const failure = failedStage(result); const toSource = (timelineMs: number): number => clamp(timelineMs + offsetMs, 0, source.durationMs); @@ -270,6 +332,7 @@ export function planRender( ? {} : { description: options.scenario.description }), failed: failure !== undefined, + ...(edits?.cards === undefined ? {} : { edits: edits.cards }), }); const masks = maskSpans(events, out, viewport, pageEndMs, { leadMs: maskLeadMs, @@ -279,9 +342,7 @@ export function planRender( transitions: options.transitions?.enabled === true, sourceFrameMs: 1000 / source.fps, }); - const cardBackground = - frame?.background ?? - resolveBackground(options.background ?? { preset: 'ocean' }); + const cardBackground = frame?.background ?? resolveBackground(background); const verticalConfig = VerticalConfigSchema.parse(options.vertical ?? {}); const squareConfig = SquareConfigSchema.parse(options.square ?? {}); const { follow, squareFollow, ...overlays } = shiftOverlays( @@ -312,7 +373,10 @@ export function planRender( squareConfig, ), masks, - captions: captions(events, timeline.annotations ?? [], out, pageEndMs), + captions: + edits?.captions === undefined + ? captions(events, timeline.annotations ?? [], out, pageEndMs) + : editedCaptions(edits.captions, out, pageEndMs), keys: keyBadges(events, out, pageEndMs, viewport), }, cards, @@ -398,6 +462,19 @@ export function planRender( }; } +/** Each event's `zoom` replaced by its edit (spec 353, Decision 3). */ +function withZoomEdits( + events: readonly TimelineEvent[], + zoom: NonNullable<RunEdits['zoom']>, +): readonly TimelineEvent[] { + if (zoom.length === 0) return events; + const byStep = new Map(zoom.map((entry) => [entry.stepIndex, entry.zoom])); + return events.map((event) => { + const edited = byStep.get(event.stepIndex); + return edited === undefined ? event : { ...event, zoom: edited }; + }); +} + /** The vertical output's size and caption type (spec 176, Decisions 1 and 4). */ export const VERTICAL = { width: 1080, @@ -942,3 +1019,20 @@ function captions( } return list.filter((caption) => caption.endMs > caption.startMs); } + +/** + * The edited caption list in place of every step and page caption (spec 353, + * Decision 2): each at its own times, kept within the page. The list is + * ordered and does not overlap, so no caption cuts another. + */ +function editedCaptions( + list: NonNullable<RunEdits['captions']>, + out: (timelineMs: number) => number, + videoEndMs: number, +): Caption[] { + return list.flatMap((caption) => { + const startMs = out(caption.startMs); + const endMs = Math.min(videoEndMs, out(caption.endMs)); + return endMs > startMs ? [{ startMs, endMs, text: caption.text }] : []; + }); +} diff --git a/packages/renderer/test/plan/build.spec.ts b/packages/renderer/test/plan/build.spec.ts index 1e2cefcb..fd747333 100644 --- a/packages/renderer/test/plan/build.spec.ts +++ b/packages/renderer/test/plan/build.spec.ts @@ -2,7 +2,11 @@ import { cp, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import path from 'node:path'; import { performance } from 'node:perf_hooks'; -import { RunResultSchema } from '@demoflow/core'; +import { + CardsConfigSchema, + type RenderFormat, + RunResultSchema, +} from '@demoflow/core'; import type { EngineObserver } from '@demoflow/engine'; import { afterAll, beforeAll, describe, expect, it } from 'vitest'; import { @@ -10,6 +14,7 @@ import { DEFAULT_OFFSET_MS, frameAt, frameCount, + PLAN_INPUTS, parseProbe, probeVideo, type RenderPlan, @@ -481,6 +486,50 @@ describe.skipIf(!hasFfmpeg)('buildRenderPlan on real runs', () => { expect(isMark(decoded[Math.round(first / DRIFT_FRAME_MS)])).toBe(false); }); + it('plans every fixture run with an empty edits.json as without one', async () => { + const options = { + cards: CardsConfigSchema.parse({ outro: { title: 'Thanks' } }), + scenario: { description: 'A fixture run' }, + formats: ['mp4', 'mp4-vertical'] as RenderFormat[], + }; + for (const [name, runDir] of Object.entries({ customers, failing, tour })) { + const edited = path.join(parent, `${name}-edited`); + await cp(runDir, edited, { recursive: true }); + await writeFile( + path.join(edited, PLAN_INPUTS.edits), + JSON.stringify({ schemaVersion: 1 }), + ); + expect(await buildRenderPlan(edited, options), name).toEqual( + await buildRenderPlan(runDir, options), + ); + } + }); + + it('applies an edits.json beside a real run', async () => { + const edited = path.join(parent, 'customers-captions'); + await cp(customers, edited, { recursive: true }); + const { events } = JSON.parse( + await readFile(path.join(customers, 'timeline.json'), 'utf8'), + ) as { events: { startMs: number; endMs: number }[] }; + const last = events.at(-1); + if (last === undefined) throw new Error('customers run has no events'); + await writeFile( + path.join(edited, PLAN_INPUTS.edits), + JSON.stringify({ + schemaVersion: 1, + captions: [ + { + startMs: Math.round(last.startMs), + endMs: Math.round(last.endMs) + 500, + text: 'Edited', + }, + ], + }), + ); + const plan = await buildRenderPlan(edited); + expect(plan.captions.map((caption) => caption.text)).toEqual(['Edited']); + }); + it('keeps the defaults when the mark is not in the video', async () => { // The same recording, told the mark was green: nothing matches. const runDir = path.join(parent, 'no-mark'); diff --git a/packages/renderer/test/plan/edits.spec.ts b/packages/renderer/test/plan/edits.spec.ts new file mode 100644 index 00000000..c191f934 --- /dev/null +++ b/packages/renderer/test/plan/edits.spec.ts @@ -0,0 +1,501 @@ +import { mkdtemp, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import { + type Annotation, + type CardsConfig, + CardsConfigSchema, + deriveRunStatus, + type RunEdits, + type RunResult, + type Stages, + type Timeline, + type TimelineEvent, +} from '@demoflow/core'; +import { afterAll, beforeAll, describe, expect, it } from 'vitest'; +import { + buildRenderPlan, + frameAt, + PLAN_INPUTS, + planRender, + type RenderPlan, + type RenderPlanOptions, +} from '../../src/index.ts'; + +const VIEWPORT = { width: 1280, height: 720 }; + +function result(failedAt?: number): RunResult { + const passed = { status: 'passed' as const }; + const stages: Stages = { + readiness: passed, + execution: + failedAt === undefined + ? passed + : { + status: 'failed', + error: { message: 'boom', stepIndex: failedAt }, + }, + verification: passed, + recording: passed, + rendering: { status: 'pending' }, + storage: { status: 'pending' }, + }; + return { + schemaVersion: 1, + runId: 'run', + scenarioId: 'inline', + scenarioName: 'Create a customer', + startedAt: '2026-10-26T10:00:00.000Z', + finishedAt: '2026-10-26T10:00:10.000Z', + status: deriveRunStatus(stages), + stages, + renders: [], + warnings: [], + }; +} + +function timeline( + events: Omit<TimelineEvent, 'stepIndex'>[], + annotations?: Annotation[], +): Timeline { + return { + schemaVersion: 1, + viewport: VIEWPORT, + deviceScaleFactor: 2, + videoFile: 'source.webm', + events: events.map((event, stepIndex) => ({ ...event, stepIndex })), + ...(annotations === undefined ? {} : { annotations }), + }; +} + +/** No freezes and no offset: page time is timeline time. */ +function plan( + events: Omit<TimelineEvent, 'stepIndex'>[], + edits: Omit<RunEdits, 'schemaVersion'> | undefined, + options: RenderPlanOptions & { + failedAt?: number; + annotations?: Annotation[]; + } = {}, +): RenderPlan { + const { failedAt, annotations, ...rest } = options; + return planRender( + { + timeline: timeline(events, annotations), + result: result(failedAt), + source: { + width: 2560, + height: 1440, + fps: 25, + durationMs: 20_000, + codec: 'vp9', + freezes: [], + }, + ...(edits === undefined ? {} : { edits: { schemaVersion: 1, ...edits } }), + }, + { offsetMs: 0, frame: {}, ...rest }, + ); +} + +function click( + startMs: number, + endMs: number, + extra: Partial<TimelineEvent> = {}, +): Omit<TimelineEvent, 'stepIndex'> { + return { + action: 'click', + startMs, + endMs, + target: { box: { x: 580, y: 346, width: 120, height: 28 } }, + pointer: { from: { x: 640, y: 360 }, to: { x: 640, y: 360 } }, + ...extra, + }; +} + +const wait = (startMs: number, endMs: number) => ({ + action: 'wait' as const, + startMs, + endMs, +}); + +const maxZoom = (rendered: RenderPlan): number => + Math.max(1, ...rendered.camera.map((key) => key.zoom)); + +/** Every card off unless a test turns it on, so each test reads one kind. */ +function cards(overrides: Partial<CardsConfig> = {}): CardsConfig { + return { + intro: { enabled: false, durationMs: 2000 }, + scenes: { enabled: false, durationMs: 1500 }, + outro: { durationMs: 2500 }, + ...overrides, + }; +} + +describe('edited captions', () => { + const events = [ + click(1000, 2000, { caption: 'Open the form' }), + { ...wait(2000, 4000), marker: { title: 'Saved', kind: 'caption' } }, + wait(4000, 6000), + ] as const; + const annotations: Annotation[] = [ + { atMs: 4500, kind: 'caption', title: 'From the page' }, + ]; + + it('keeps the step and page captions without edits', () => { + const rendered = plan([...events], undefined, { annotations }); + expect(rendered.captions.map((caption) => caption.text)).toEqual([ + 'Open the form', + 'Saved', + 'From the page', + ]); + }); + + it('replaces every step and page caption with the edited list', () => { + const rendered = plan( + [...events], + { captions: [{ startMs: 2500, endMs: 3700, text: 'Moved' }] }, + { annotations }, + ); + expect(rendered.captions).toEqual([ + { startMs: 2500, endMs: 3700, text: 'Moved' }, + ]); + }); + + it('maps the edited times through the idle map and the cards', () => { + const rendered = planRender( + { + timeline: timeline([click(1000, 2000), wait(2000, 6000)]), + result: result(), + source: { + width: 2560, + height: 1440, + fps: 25, + durationMs: 20_000, + codec: 'vp9', + // The wait is frozen, and compressed to 400 ms. + freezes: [{ startMs: 2000, endMs: 6000 }], + }, + edits: { + schemaVersion: 1, + captions: [{ startMs: 1000, endMs: 7000, text: 'Across the wait' }], + }, + }, + { + offsetMs: 0, + cards: cards({ intro: { enabled: true, durationMs: 2000 } }), + }, + ); + const [caption] = rendered.captions; + // After the 2 s intro; 4 s of the wait saved. + expect(caption.startMs).toBe(3000); + expect(caption.endMs).toBeLessThan(9000); + expect(caption.endMs).toBeGreaterThan(caption.startMs); + }); + + it('shows no caption at all for an empty list, in the vertical output either', () => { + const rendered = plan( + [...events], + { captions: [] }, + { + annotations, + formats: ['mp4', 'mp4-vertical'], + }, + ); + expect(rendered.captions).toEqual([]); + expect(rendered.vertical).toBeDefined(); + const frame = Math.round((1500 * 30) / 1000); + expect(frameAt(rendered, frame, 'vertical').caption).toBeUndefined(); + expect(frameAt(rendered, frame).caption).toBeUndefined(); + }); + + it('shows an edited caption in the vertical output at the same time', () => { + const rendered = plan( + [...events], + { captions: [{ startMs: 2500, endMs: 3700, text: 'Moved' }] }, + { formats: ['mp4-vertical'] }, + ); + const frame = Math.round((3000 * 30) / 1000); + expect(frameAt(rendered, frame, 'vertical').caption).toBe('Moved'); + }); +}); + +describe('edited zoom', () => { + it('zooms an unzoomed click with the default strength', () => { + const events = [click(1000, 2000), wait(2000, 4000)]; + expect(maxZoom(plan(events, undefined))).toBe(1); + const rendered = plan(events, { zoom: [{ stepIndex: 0, zoom: true }] }); + expect(maxZoom(rendered)).toBeCloseTo(1.35); + // The camera arrives as the click presses. + expect(rendered.camera).toContainEqual( + expect.objectContaining({ atMs: 1900, zoom: 1.35 }), + ); + }); + + it('removes the zoom of a zoomed step', () => { + const events = [click(1000, 2000, { zoom: true }), wait(2000, 4000)]; + expect(maxZoom(plan(events, undefined))).toBeCloseTo(1.35); + const rendered = plan(events, { zoom: [{ stepIndex: 0, zoom: false }] }); + expect(rendered.camera).toEqual([]); + }); + + it('uses a number as the strength, capped by the fit rule as before', () => { + const events = [click(1000, 2000), wait(2000, 4000)]; + expect( + maxZoom(plan(events, { zoom: [{ stepIndex: 0, zoom: 2 }] })), + ).toBeCloseTo(2); + const wide = [ + click(1000, 2000, { + target: { box: { x: 240, y: 300, width: 800, height: 40 } }, + }), + wait(2000, 4000), + ]; + // 90 % of 1280 over 800 px. + expect( + maxZoom(plan(wide, { zoom: [{ stepIndex: 0, zoom: 2 }] })), + ).toBeCloseTo(1.44); + }); + + it('leaves a step that is not listed as recorded', () => { + const events = [ + click(1000, 2000, { zoom: true }), + wait(2000, 3000), + // Far from the first target, so the camera zooms out between them. + click(6000, 7000, { + target: { box: { x: 40, y: 40, width: 120, height: 28 } }, + }), + wait(7000, 8000), + ]; + const rendered = plan(events, { zoom: [{ stepIndex: 2, zoom: 2 }] }); + expect(rendered.camera.filter((key) => key.atMs < 3000)).toEqual( + plan(events, undefined).camera, + ); + expect(maxZoom(rendered)).toBeCloseTo(2); + }); +}); + +describe('edited cards', () => { + const events = [ + { + action: 'marker' as const, + startMs: 0, + endMs: 0, + marker: { title: 'Start', kind: 'scene' as const }, + }, + click(1000, 2000), + wait(2000, 3000), + ]; + const kinds = (rendered: RenderPlan) => + rendered.cards.map(({ kind, title, subtitle }) => ({ + kind, + title, + ...(subtitle === undefined ? {} : { subtitle }), + })); + + it('retitles the intro and removes its subtitle', () => { + const options = { + cards: cards({ intro: { enabled: true, durationMs: 2000 } }), + scenario: { description: 'From the list' }, + }; + expect(kinds(plan(events, undefined, options))).toEqual([ + { kind: 'intro', title: 'Create a customer', subtitle: 'From the list' }, + ]); + expect( + kinds( + plan( + events, + { cards: { intro: { title: 'Sign up', subtitle: null } } }, + options, + ), + ), + ).toEqual([{ kind: 'intro', title: 'Sign up' }]); + expect( + kinds( + plan( + events, + { cards: { intro: { subtitle: 'In a minute' } } }, + options, + ), + ), + ).toEqual([ + { kind: 'intro', title: 'Create a customer', subtitle: 'In a minute' }, + ]); + }); + + it('switches the intro and the scenes', () => { + const options = { + cards: cards({ scenes: { enabled: true, durationMs: 1500 } }), + }; + expect(kinds(plan(events, undefined, options))).toEqual([ + { kind: 'scene', title: 'Start' }, + ]); + expect( + kinds( + plan( + events, + { cards: { scenes: { enabled: false }, intro: { enabled: true } } }, + options, + ), + ), + ).toEqual([{ kind: 'intro', title: 'Create a customer' }]); + }); + + it('adds an outro to a config without one, with the config’s duration', () => { + const rendered = plan( + events, + { cards: { outro: { title: 'Try it', cta: 'example.com' } } }, + { cards: cards() }, + ); + expect(rendered.cards).toEqual([ + expect.objectContaining({ + kind: 'outro', + title: 'Try it', + subtitle: 'example.com', + durationMs: 2500, + }), + ]); + }); + + it('removes the outro of a config with one', () => { + const options = { + cards: cards({ outro: { title: 'Thanks', durationMs: 2500 } }), + }; + expect(kinds(plan(events, undefined, options))).toEqual([ + { kind: 'outro', title: 'Thanks' }, + ]); + expect(plan(events, { cards: { outro: null } }, options).cards).toEqual([]); + }); + + it('never gives a failed run an outro', () => { + const rendered = plan( + events, + { cards: { outro: { title: 'Try it' } } }, + { cards: cards(), failedAt: 1 }, + ); + expect(rendered.cards).toEqual([]); + expect(rendered.failure?.watermark).toBe(true); + }); + + it('ignores card edits when the project has no cards', () => { + const rendered = plan(events, { + cards: { intro: { enabled: true }, outro: { title: 'Try it' } }, + }); + expect(rendered.cards).toEqual([]); + }); + + it('reads the config defaults through CardsConfigSchema', () => { + const rendered = plan( + events, + { cards: { intro: { enabled: false }, scenes: { enabled: false } } }, + { cards: CardsConfigSchema.parse({}) }, + ); + expect(rendered.cards).toEqual([]); + }); +}); + +describe('edited style', () => { + const events = [click(1000, 2000), wait(2000, 3000)]; + const base = plan(events, undefined); + + it('replaces the background of the window and the cards, and nothing else', () => { + const rendered = plan(events, { background: { color: '#112233' } }); + const colour = { from: '#112233', to: '#112233', angle: 0 }; + expect(rendered.frame).toEqual({ ...base.frame, background: colour }); + expect(rendered.cardBackground).toEqual(colour); + expect({ + ...rendered, + frame: base.frame, + cardBackground: base.cardBackground, + }).toEqual(base); + }); + + it('merges the window fields over the config', () => { + const rendered = plan( + events, + { frame: { radius: 0 } }, + { + frame: { shadow: false }, + }, + ); + const configured = plan(events, undefined, { frame: { shadow: false } }); + expect(rendered.frame).toEqual({ ...configured.frame, radius: 0 }); + expect({ ...rendered, frame: configured.frame }).toEqual(configured); + }); + + it('turns the window off', () => { + const rendered = plan(events, { frame: { enabled: false } }); + expect(rendered.frame).toBeUndefined(); + expect(rendered.fit).toEqual({ x: 0, y: 0, scale: 1.5 }); + }); +}); + +describe('an empty edits file', () => { + it('plans exactly what no file plans', () => { + const events = [ + click(1000, 2000, { caption: 'Open', zoom: true }), + { + action: 'marker' as const, + startMs: 2000, + endMs: 2000, + marker: { title: 'Next', kind: 'scene' as const }, + }, + wait(2000, 4000), + ]; + const options = { + cards: cards({ + intro: { enabled: true, durationMs: 2000 }, + scenes: { enabled: true, durationMs: 1500 }, + outro: { title: 'Thanks', durationMs: 2500 }, + }), + formats: ['mp4', 'mp4-vertical', 'mp4-square'] as const, + background: { preset: 'dusk' as const }, + }; + expect( + plan(events, {}, { ...options, formats: [...options.formats] }), + ).toEqual( + plan(events, undefined, { ...options, formats: [...options.formats] }), + ); + }); +}); + +describe('buildRenderPlan with edits.json', () => { + let runDir: string; + + beforeAll(async () => { + runDir = await mkdtemp(path.join(tmpdir(), 'demoflow-edits-')); + await writeFile( + path.join(runDir, PLAN_INPUTS.timeline), + JSON.stringify(timeline([click(1000, 2000), wait(2000, 3000)])), + ); + await writeFile( + path.join(runDir, PLAN_INPUTS.result), + JSON.stringify(result()), + ); + }); + + afterAll(async () => { + await rm(runDir, { recursive: true, force: true }); + }); + + // The edits are read and checked before the source is probed, so a run + // without a video is enough to see them rejected. + it.each([ + ['not JSON', '{ captions'], + ['against its schema', JSON.stringify({ schemaVersion: 2 })], + [ + 'against the timeline', + JSON.stringify({ + schemaVersion: 1, + zoom: [{ stepIndex: 1, zoom: true }], + }), + ], + [ + 'with a caption past the end', + JSON.stringify({ + schemaVersion: 1, + captions: [{ startMs: 0, endMs: 60_000, text: 'Too long' }], + }), + ], + ])('rejects an edits.json that is invalid %s', async (_, content) => { + await writeFile(path.join(runDir, PLAN_INPUTS.edits), content); + await expect(buildRenderPlan(runDir)).rejects.toThrow(/edits\.json/); + }); +}); From c2795d1e05f23e347284c1c847204c3958cd668f Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 18:00:01 +0100 Subject: [PATCH 48/71] feat(cli): the runner daemon runs check passes on a schedule (spec 361) A scheduler in the daemon ticks on start and once a minute, runs one run --check pass per due slot in the launch slot website launches use, and keeps schedule.state.json. Without an account and with a scheduled root, the daemon runs in local mode. schedules.sync names the reported roots' schedules; runner status shows next and last check; demoflow run records its root in local-roots.jsonl. --- apps/cli/src/commands/run.ts | 13 + apps/cli/src/runner/connection.ts | 13 + apps/cli/src/runner/control.ts | 106 +++++- apps/cli/src/runner/daemon.ts | 135 +++++--- apps/cli/src/runner/install/commands.ts | 8 +- apps/cli/src/runner/launch/index.ts | 39 ++- apps/cli/src/runner/paths.ts | 6 + apps/cli/src/runner/schedule/local-roots.ts | 76 +++++ apps/cli/src/runner/schedule/roots.ts | 48 +++ apps/cli/src/runner/schedule/scheduler.ts | 359 ++++++++++++++++++++ apps/cli/src/runner/schedule/state.ts | 109 ++++++ apps/cli/src/runner/state.ts | 12 +- apps/cli/src/runs-report/reported-runs.ts | 25 +- apps/cli/test/runner/daemon-launch.spec.ts | 5 +- 14 files changed, 888 insertions(+), 66 deletions(-) create mode 100644 apps/cli/src/runner/schedule/local-roots.ts create mode 100644 apps/cli/src/runner/schedule/roots.ts create mode 100644 apps/cli/src/runner/schedule/scheduler.ts create mode 100644 apps/cli/src/runner/schedule/state.ts diff --git a/apps/cli/src/commands/run.ts b/apps/cli/src/commands/run.ts index b6b805f2..5012f28d 100644 --- a/apps/cli/src/commands/run.ts +++ b/apps/cli/src/commands/run.ts @@ -37,6 +37,8 @@ import { } from '../config/index.ts'; import { nodeLaunchFs } from '../runner/launch/checks.ts'; import { LIST_MAX_SCENARIOS, listScenarios } from '../runner/launch/list.ts'; +import { runnerPaths } from '../runner/paths.ts'; +import { recordLocalRoot } from '../runner/schedule/local-roots.ts'; import { canonicalRoot, defaultReportDeps, @@ -250,6 +252,8 @@ export async function runCommand( runDir, } : await execute(run, runId, runDir); + // Spec 361, Decision 4: the daemon watches this root's schedule. + if (index === 0) await recordRoot(root, host); // A run whose app never answered was never reported before spec 360; a // check reports it, so the stale state sees a readiness failure too. if (!('error' in started) || check) { @@ -418,6 +422,15 @@ async function passFiles( const SCENARIOS_PREFIX = 'demoflow/'; +/** Never throws: a run's outcome does not depend on the local roots file. */ +async function recordRoot(root: string, host: HostEnvironment): Promise<void> { + try { + recordLocalRoot(runnerPaths(host).localRoots, await canonicalRoot(root)); + } catch { + // A root not recorded waits for the next run. + } +} + type Started = { app: RunningApp } | { error: unknown }; /** `--port <n>`: a decimal integer from 1 to 65535, used or not (spec 337). */ diff --git a/apps/cli/src/runner/connection.ts b/apps/cli/src/runner/connection.ts index 328a4206..d256aaec 100644 --- a/apps/cli/src/runner/connection.ts +++ b/apps/cli/src/runner/connection.ts @@ -77,6 +77,11 @@ export interface ConnectionDeps { artifacts?: ArtifactsPort; /** Answers `scenarios.list` and `run.*` (spec 248); without it, logged as unknown. */ launches?: LaunchPort; + /** + * Spec 361, Decision 6: the current `schedules.sync`, sent after + * `launches.sync`; `null` while the scheduler has not looked yet. + */ + schedules?: () => Record<string, unknown> | null; } export type ConnectionOutcome = 'stopped' | 'revoked'; @@ -149,6 +154,13 @@ export class RunnerConnection { return this.done; } + /** Spec 361, Decision 6: a watched schedule changed; tell an open socket. */ + syncSchedules(): void { + if (!this.opened || this.stopping) return; + const frame = this.deps.schedules?.() ?? null; + if (frame !== null) this.send(frame); + } + private connect(): void { if (this.stopping) return; this.opened = false; @@ -194,6 +206,7 @@ export class RunnerConnection { 'info', `announced ${running.length} running launch${running.length === 1 ? '' : 'es'}`, ); + this.syncSchedules(); this.resetIdle(); this.schedulePing(); } diff --git a/apps/cli/src/runner/control.ts b/apps/cli/src/runner/control.ts index fba7ffb1..f6d7e1a6 100644 --- a/apps/cli/src/runner/control.ts +++ b/apps/cli/src/runner/control.ts @@ -11,6 +11,7 @@ import { writeFileSync, } from 'node:fs'; import { setTimeout as delay } from 'node:timers/promises'; +import { nextDueSlot, type ScheduleConfig } from '@demoflow/core'; import { readCredentials } from '../auth/credentials.ts'; import type { Io } from '../commands/io.ts'; import { currentHost, type HostEnvironment } from '../config/platform.ts'; @@ -20,6 +21,8 @@ import { platformAutostart } from './install/autostart.ts'; import { isAlive, type LockHolder, readLock, releaseLock } from './lock.ts'; import { redact } from './log.ts'; import { type RunnerPaths, runnerPaths } from './paths.ts'; +import { hasScheduledRoot } from './schedule/roots.ts'; +import { type LastPass, readScheduleState } from './schedule/state.ts'; import { type ConnectionState, type RunnerState, readState } from './state.ts'; /** `start` waits this long for the child to take the lock. */ @@ -64,7 +67,11 @@ export const defaultControlDeps = (): ControlDeps => ({ /** `demoflow runner start`: spawns the daemon detached, its output into the log. */ export async function startRunner(io: Io, deps: ControlDeps): Promise<number> { const paths = runnerPaths(deps.host); - if (readCredentials(deps.host) === null) { + // Spec 361, Decision 5: a scheduled root runs without an account. + if ( + readCredentials(deps.host) === null && + !hasScheduledRoot(paths, deps.host.env) + ) { io.stderr('Not logged in; run demoflow login first\n'); return 1; } @@ -183,6 +190,18 @@ export interface RunnerStatus { retryInSeconds: number | null; server: string | null; autostart: boolean; + /** Spec 361: each scheduled project, as the daemon last saw it. */ + schedules: ScheduledProject[]; +} + +export interface ScheduledProject { + rootPath: string; + schedule: ScheduleConfig; + /** The machine's zone the times are in. */ + zone: string; + /** `null` while the runner is not running: nothing will run it. */ + nextCheckAt: string | null; + lastCheck: LastPass | null; } export function runnerStatus(deps: ControlDeps): RunnerStatus { @@ -215,11 +234,40 @@ export function runnerStatus(deps: ControlDeps): RunnerStatus { : Math.max(0, Math.floor((deps.now() - started) / 1000)), connection, retryInSeconds, - server: credentials?.server ?? (own ? state.server : null), + server: credentials?.server ?? (own ? (state.server ?? null) : null), autostart: deps.autostart.installed(deps.host), + schedules: scheduledProjects(paths, holder !== null, deps.now()), }; } +/** From `schedule.state.json`: the daemon's view, no config is read here. */ +function scheduledProjects( + paths: RunnerPaths, + running: boolean, + now: number, +): ScheduledProject[] { + const saved = readScheduleState(paths.scheduleState); + if (saved === null) return []; + const projects: ScheduledProject[] = []; + for (const [rootPath, entry] of Object.entries(saved.roots)) { + if (entry.schedule === undefined) continue; + let next: number | null = null; + try { + next = running ? nextDueSlot(entry.schedule, now, saved.zone) : null; + } catch { + // A zone this Node does not know: no time to show. + } + projects.push({ + rootPath, + schedule: entry.schedule, + zone: saved.zone, + nextCheckAt: next === null ? null : new Date(next).toISOString(), + lastCheck: entry.last ?? null, + }); + } + return projects; +} + /** `demoflow runner status [--json]`. */ export function statusCommand( flags: { json?: boolean }, @@ -233,14 +281,66 @@ export function statusCommand( } const lines = [ `Runner: ${status.running ? `running (PID ${status.pid}${status.uptimeSeconds === null ? '' : `, up ${formatDuration(status.uptimeSeconds)}`})` : 'not running'}`, - `Connection: ${status.connection === 'reconnecting' && status.retryInSeconds !== null ? `reconnecting in ${status.retryInSeconds}s` : status.connection}`, + `Connection: ${connectionText(status)}`, `Server: ${status.server ?? 'not logged in'}`, `Autostart: ${status.autostart ? 'installed' : 'not installed'}`, ]; + for (const project of status.schedules) { + lines.push( + `Schedule: ${project.rootPath} (${scheduleText(project.schedule)})`, + ` next check: ${project.nextCheckAt === null ? 'when the runner is running' : localTime(project.nextCheckAt, project.zone)}`, + ` last check: ${lastCheckText(project.lastCheck, project.zone)}`, + ); + } io.stdout(`${redact(lines.join('\n'))}\n`); return 0; } +function connectionText(status: RunnerStatus): string { + if (status.connection === 'local') return 'local mode: scheduled checks only'; + if (status.connection === 'reconnecting' && status.retryInSeconds !== null) { + return `reconnecting in ${status.retryInSeconds}s`; + } + return status.connection; +} + +function scheduleText(schedule: ScheduleConfig): string { + const when = + schedule.cadence === 'weekly' + ? `weekly on ${schedule.weekday ?? '?'}` + : schedule.cadence; + const excluded = schedule.exclude?.length ?? 0; + return `${when} at ${schedule.at}${excluded === 0 ? '' : `, ${excluded} excluded`}`; +} + +function lastCheckText(last: LastPass | null, zone: string): string { + if (last === null) return 'none yet'; + const at = localTime(last.startedAt, zone); + if (last.outcome === undefined) return `${at}, no result yet`; + if (last.outcome !== 'finished') return `${at}, ${last.outcome}`; + return `${at}, ${last.passed ?? 0} passed, ${last.failed ?? 0} failed`; +} + +/** `YYYY-MM-DD HH:MM` in the daemon's zone; the ISO time when the zone is unknown. */ +function localTime(iso: string, zone: string): string { + try { + const parts = new Intl.DateTimeFormat('en-US', { + timeZone: zone, + hourCycle: 'h23', + year: 'numeric', + month: '2-digit', + day: '2-digit', + hour: '2-digit', + minute: '2-digit', + }).formatToParts(new Date(iso)); + const part = (type: Intl.DateTimeFormatPartTypes) => + parts.find((entry) => entry.type === type)?.value ?? ''; + return `${part('year')}-${part('month')}-${part('day')} ${part('hour')}:${part('minute')}`; + } catch { + return iso; + } +} + /** `demoflow runner logs [--follow]`: the current `runner.log`, then what is appended. */ export async function logsCommand( flags: { follow?: boolean }, diff --git a/apps/cli/src/runner/daemon.ts b/apps/cli/src/runner/daemon.ts index 9946fe4d..c004300c 100644 --- a/apps/cli/src/runner/daemon.ts +++ b/apps/cli/src/runner/daemon.ts @@ -18,6 +18,13 @@ import { acquireLock, releaseLock } from './lock.ts'; import { fileLogger, type Logger } from './log.ts'; import { runnerPaths } from './paths.ts'; import { nodeRelayFs, VideoRelay } from './relay/index.ts'; +import { + hasScheduledRoot, + machineZone, + scheduleLoader, + watchedRoots, +} from './schedule/roots.ts'; +import { Scheduler } from './schedule/scheduler.ts'; import { type ConnectionState, writeState } from './state.ts'; /** How often the daemon looks for `runner.stop`. */ @@ -43,6 +50,8 @@ export interface DaemonDeps { spawn: SpawnRun; /** Mirror log lines here as well, e.g. a terminal running `--foreground`. */ echo?: (line: string) => void; + /** The machine's IANA zone for schedules (spec 361); the system's when absent. */ + zone?: () => string; } export const defaultDaemonDeps = (host: HostEnvironment): DaemonDeps => ({ @@ -60,12 +69,14 @@ export const defaultDaemonDeps = (host: HostEnvironment): DaemonDeps => ({ /** * `demoflow runner --foreground`: the daemon itself. `runner start` spawns it - * detached; the autostart units run it directly. One per machine. + * detached; the autostart units run it directly. One per machine. Without an + * account it runs scheduled checks only, when a watched root has a schedule + * (spec 361, Decision 5). */ export async function runForeground(io: Io, deps: DaemonDeps): Promise<number> { const paths = runnerPaths(deps.host); const credentials = readCredentials(deps.host); - if (credentials === null) { + if (credentials === null && !hasScheduledRoot(paths, deps.host.env)) { io.stderr('Not logged in; run demoflow login first\n'); return EXIT_DAEMON_NOT_LOGGED_IN; } @@ -80,16 +91,19 @@ export async function runForeground(io: Io, deps: DaemonDeps): Promise<number> { now: () => new Date(deps.clock.now()), ...(deps.echo === undefined ? {} : { echo: deps.echo }), }); - logger.log('info', `runner started (PID ${deps.pid})`); + logger.log( + 'info', + `runner started (PID ${deps.pid})${credentials === null ? ', local mode: scheduled checks only' : ''}`, + ); let current: { state: ConnectionState; retryAt?: number } = { - state: 'connecting', + state: credentials === null ? 'local' : 'connecting', }; const saveState = () => { writeState(paths.state, { pid: deps.pid, startedAt, - server: credentials.server, + ...(credentials === null ? {} : { server: credentials.server }), state: current.state, ...(current.retryAt === undefined ? {} @@ -99,54 +113,80 @@ export async function runForeground(io: Io, deps: DaemonDeps): Promise<number> { }; saveState(); - const relay = new VideoRelay({ - indexFile: paths.reportedRuns, - fs: nodeRelayFs, - logger, - platform: deps.host.platform, - }); - const launcher = new Launcher({ - indexFile: paths.reportedRuns, - fs: nodeLaunchFs, - logger, + // Spec 361, Decision 5: without an account, no socket, relay or launches. + let connection: RunnerConnection | null = null; + let launcher: Launcher | null = null; + const scheduler = new Scheduler({ clock: deps.clock, - env: deps.host.env, + logger, + zone: deps.zone ?? machineZone, + roots: () => watchedRoots(paths), + loadSchedule: scheduleLoader(deps.host.env), + stateFile: paths.scheduleState, spawn: deps.spawn, - ...defaultLauncherDeps(deps.host), + // Spec 248: one launch slot per machine, shared with the website. + claim: () => (launcher === null ? () => {} : launcher.claim()), + onSchedules: () => connection?.syncSchedules(), + local: credentials === null, }); - const connection = new RunnerConnection({ - server: credentials.server, - token: credentials.token, - runnerId: credentials.runnerId, - connect: deps.connect, - clock: deps.clock, - random: deps.random, - logger, - saveToken: (token) => - writeCredentials(deps.host, { ...credentials, token }), - isRevoked: async (token) => - (await fetchSelf(credentials.server, token, deps.fetch)) === null, - onState: (state, retryAt) => { - current = retryAt === undefined ? { state } : { state, retryAt }; - saveState(); - }, - relay, - artifacts: new ArtifactsDeleter({ + if (credentials !== null) { + const relay = new VideoRelay({ indexFile: paths.reportedRuns, - fs: nodeArtifactsFs, + fs: nodeRelayFs, logger, platform: deps.host.platform, - homeDir: deps.host.homedir, - closeRun: (runId) => relay.closeRun(runId), - }), - launches: launcher, - }); + }); + launcher = new Launcher({ + indexFile: paths.reportedRuns, + fs: nodeLaunchFs, + logger, + clock: deps.clock, + env: deps.host.env, + spawn: deps.spawn, + onIdle: () => scheduler.wake(), + ...defaultLauncherDeps(deps.host), + }); + connection = new RunnerConnection({ + server: credentials.server, + token: credentials.token, + runnerId: credentials.runnerId, + connect: deps.connect, + clock: deps.clock, + random: deps.random, + logger, + saveToken: (token) => + writeCredentials(deps.host, { ...credentials, token }), + isRevoked: async (token) => + (await fetchSelf(credentials.server, token, deps.fetch)) === null, + onState: (state, retryAt) => { + current = retryAt === undefined ? { state } : { state, retryAt }; + saveState(); + }, + relay, + artifacts: new ArtifactsDeleter({ + indexFile: paths.reportedRuns, + fs: nodeArtifactsFs, + logger, + platform: deps.host.platform, + homeDir: deps.host.homedir, + closeRun: (runId) => relay.closeRun(runId), + }), + launches: launcher, + schedules: () => scheduler.schedules(), + }); + } + let stopped = (): void => {}; + const stopping = new Promise<void>((resolve) => { + stopped = resolve; + }); const stop = (why: string) => { logger.log('info', `stopping (${why})`); // Spec 248, Decision 11: the run is cancelled; `finally` waits for it. - void launcher.close(); - void connection.stop(); + void launcher?.close(); + void scheduler.stop(); + if (connection === null) stopped(); + else void connection.stop(); }; const watch = setInterval(() => { if (existsSync(paths.stop)) stop('runner stop'); @@ -159,6 +199,13 @@ export async function runForeground(io: Io, deps: DaemonDeps): Promise<number> { process.on('SIGINT', onSignal); try { + scheduler.start(); + if (connection === null) { + await stopping; + rmSync(paths.state, { force: true }); + logger.log('info', 'stopped'); + return EXIT_DAEMON_DONE; + } const outcome = await connection.run(); if (outcome === 'revoked') { current = { state: 'revoked' }; @@ -173,7 +220,7 @@ export async function runForeground(io: Io, deps: DaemonDeps): Promise<number> { return EXIT_DAEMON_CRASHED; } finally { // No child outlives the daemon, whatever ended it. - await launcher.close(); + await Promise.all([launcher?.close(), scheduler.stop()]); clearInterval(watch); clearInterval(tick); process.off('SIGTERM', onSignal); diff --git a/apps/cli/src/runner/install/commands.ts b/apps/cli/src/runner/install/commands.ts index 1976d070..3be8d4e0 100644 --- a/apps/cli/src/runner/install/commands.ts +++ b/apps/cli/src/runner/install/commands.ts @@ -2,6 +2,8 @@ import { readCredentials } from '../../auth/credentials.ts'; import type { Io } from '../../commands/io.ts'; import type { ControlDeps } from '../control.ts'; import { redact } from '../log.ts'; +import { runnerPaths } from '../paths.ts'; +import { hasScheduledRoot } from '../schedule/roots.ts'; /** * `demoflow runner install`: registers login autostart for this user. The @@ -9,7 +11,11 @@ import { redact } from '../log.ts'; * and carries no token — the daemon reads `credentials.json` itself. */ export function installCommand(io: Io, deps: ControlDeps): number { - if (readCredentials(deps.host) === null) { + // Spec 361, Decision 5: a scheduled root runs without an account. + if ( + readCredentials(deps.host) === null && + !hasScheduledRoot(runnerPaths(deps.host), deps.host.env) + ) { io.stderr('Not logged in; run demoflow login first\n'); return 1; } diff --git a/apps/cli/src/runner/launch/index.ts b/apps/cli/src/runner/launch/index.ts index 644e31c1..7b883f90 100644 --- a/apps/cli/src/runner/launch/index.ts +++ b/apps/cli/src/runner/launch/index.ts @@ -80,6 +80,8 @@ export interface LauncherDeps extends CheckDeps { newRunId(): string; /** The run's `result.json` status; throws when there is none. */ readStatus(runDir: string): Promise<string>; + /** Called once a launch is over and the slot is free (spec 361, Decision 3). */ + onIdle?: () => void; } /** The project's config, loaded the way `demoflow mcp` loads it. */ @@ -148,6 +150,8 @@ export class Launcher implements LaunchPort { private readonly deps: LauncherDeps; private launch: Launch | null = null; private closing: Promise<void> | null = null; + /** A scheduled check pass holds the slot (spec 361, Decision 3). */ + private claimed = false; constructor(deps: LauncherDeps) { this.deps = deps; @@ -210,6 +214,31 @@ export class Launcher implements LaunchPort { return [launch.requestId]; } + /** + * Spec 361, Decision 3: the machine's one launch slot, for a scheduled + * check pass. `null` while a launch runs or the daemon is closing; else a + * release, and until it is called a website start is refused `busy`. + */ + claim(): (() => void) | null { + if (this.launch !== null || this.closing !== null || this.claimed) { + return null; + } + this.claimed = true; + let released = false; + return () => { + if (released) return; + released = true; + this.claimed = false; + }; + } + + /** Frees the slot of a launch that is over and tells the scheduler. */ + private ended(launch: Launch): void { + if (this.launch !== launch) return; + this.launch = null; + this.deps.onIdle?.(); + } + /** Decision 11: cancels the running launch and resolves once its child is gone. */ close(): Promise<void> { this.closing ??= (async () => { @@ -296,14 +325,12 @@ export class Launcher implements LaunchPort { `launch ${shown(requestId)}: failed after start`, ); }) - .finally(() => { - if (this.launch === launch) this.launch = null; - }); + .finally(() => this.ended(launch)); } /** Decision 6: a start still in its checks counts as running. */ private refusedEarly(): string | null { - return this.launch !== null + return this.launch !== null || this.claimed ? 'busy' : this.closing !== null ? 'io' @@ -357,9 +384,7 @@ export class Launcher implements LaunchPort { else logger.log('error', `check ${shown(requestId)}: failed after start`); }) - .finally(() => { - if (this.launch === launch) this.launch = null; - }); + .finally(() => this.ended(launch)); } private async runCheck( diff --git a/apps/cli/src/runner/paths.ts b/apps/cli/src/runner/paths.ts index bae0a755..05758dad 100644 --- a/apps/cli/src/runner/paths.ts +++ b/apps/cli/src/runner/paths.ts @@ -14,6 +14,10 @@ export interface RunnerPaths { stop: string; /** Server run id → run directory, one JSON line per reported run (spec 192). */ reportedRuns: string; + /** Every root `demoflow run` ran in, one JSON line each (spec 361, Decision 4). */ + localRoots: string; + /** Per scheduled root: its schedule and last check pass (spec 361, Decision 3). */ + scheduleState: string; } export function runnerPaths(host: HostEnvironment): RunnerPaths { @@ -26,5 +30,7 @@ export function runnerPaths(host: HostEnvironment): RunnerPaths { state: p.join(dir, 'runner.state.json'), stop: p.join(dir, 'runner.stop'), reportedRuns: p.join(dir, 'reported-runs.jsonl'), + localRoots: p.join(dir, 'local-roots.jsonl'), + scheduleState: p.join(dir, 'schedule.state.json'), }; } diff --git a/apps/cli/src/runner/schedule/local-roots.ts b/apps/cli/src/runner/schedule/local-roots.ts new file mode 100644 index 00000000..e94c32a2 --- /dev/null +++ b/apps/cli/src/runner/schedule/local-roots.ts @@ -0,0 +1,76 @@ +import { + appendFileSync, + mkdirSync, + readFileSync, + renameSync, + writeFileSync, +} from 'node:fs'; +import path from 'node:path'; + +/** Spec 361, Decision 4: the file keeps the last 500 roots. */ +export const LOCAL_ROOTS_KEEP = 500; + +/** + * The roots of `local-roots.jsonl`, oldest first, once each. Never throws: a + * missing or unreadable file holds none, and malformed lines are skipped. + */ +export function readLocalRoots(file: string): string[] { + let text: string; + try { + text = readFileSync(file, 'utf8'); + } catch { + return []; + } + return parseRoots(text); +} + +function parseRoots(text: string): string[] { + const roots = new Set<string>(); + for (const line of text.split('\n')) { + if (line.trim() === '') continue; + let value: unknown; + try { + value = JSON.parse(line); + } catch { + continue; + } + const root = + typeof value === 'object' && value !== null + ? (value as Record<string, unknown>).root + : undefined; + if (typeof root !== 'string' || root === '') continue; + // The last line for a root is where it sits now. + roots.delete(root); + roots.add(root); + } + return [...roots]; +} + +/** + * Spec 361, Decision 4: `demoflow run` records its canonical root, so the + * daemon watches a project's schedule without an account. A root already + * listed is not appended again; past 500 roots the oldest go. Never throws: + * a run's outcome does not depend on this file. + */ +export function recordLocalRoot(file: string, root: string): void { + try { + const roots = readLocalRoots(file); + if (roots.includes(root)) return; + mkdirSync(path.dirname(file), { recursive: true }); + if (roots.length < LOCAL_ROOTS_KEEP) { + // One append of one short line: two runs together never interleave. + appendFileSync(file, `${JSON.stringify({ root })}\n`, { mode: 0o600 }); + return; + } + const kept = [...roots.slice(-(LOCAL_ROOTS_KEEP - 1)), root]; + const temp = `${file}.${process.pid}.tmp`; + writeFileSync( + temp, + kept.map((entry) => `${JSON.stringify({ root: entry })}\n`).join(''), + { mode: 0o600 }, + ); + renameSync(temp, file); + } catch { + // A root not recorded is a schedule that waits for the next run. + } +} diff --git a/apps/cli/src/runner/schedule/roots.ts b/apps/cli/src/runner/schedule/roots.ts new file mode 100644 index 00000000..d9b29ee0 --- /dev/null +++ b/apps/cli/src/runner/schedule/roots.ts @@ -0,0 +1,48 @@ +import type { ScheduleConfig } from '@demoflow/core'; +import { loadProjectConfig } from '../../config/project.ts'; +import { knownRootsSync } from '../../runs-report/reported-runs.ts'; +import type { RunnerPaths } from '../paths.ts'; +import { readLocalRoots } from './local-roots.ts'; + +type Env = Readonly<Record<string, string | undefined>>; + +/** Decision 4: the reported registry and the roots `demoflow run` ran in. */ +export function watchedRoots(paths: RunnerPaths): { + reported: Set<string>; + local: string[]; +} { + return { + reported: knownRootsSync(paths.reportedRuns), + local: readLocalRoots(paths.localRoots), + }; +} + +/** The root's committed `schedule`; throws when its config does not load. */ +export function scheduleLoader( + env: Env, +): (root: string) => ScheduleConfig | undefined { + return (root) => loadProjectConfig(root, env).schedule; +} + +/** + * Decision 5: true when a watched root's config asks for a schedule, so a + * daemon without an account has something to do. A config that does not + * load asks for nothing. + */ +export function hasScheduledRoot(paths: RunnerPaths, env: Env): boolean { + const { reported, local } = watchedRoots(paths); + const load = scheduleLoader(env); + for (const root of new Set([...reported, ...local])) { + try { + if (load(root) !== undefined) return true; + } catch { + // Skipped, as the scheduler skips it. + } + } + return false; +} + +/** The machine's IANA zone name. */ +export function machineZone(): string { + return Intl.DateTimeFormat().resolvedOptions().timeZone; +} diff --git a/apps/cli/src/runner/schedule/scheduler.ts b/apps/cli/src/runner/schedule/scheduler.ts new file mode 100644 index 00000000..08c55ae0 --- /dev/null +++ b/apps/cli/src/runner/schedule/scheduler.ts @@ -0,0 +1,359 @@ +import path from 'node:path'; +import { lastDueSlot, type ScheduleConfig } from '@demoflow/core'; +import type { RunChild, SpawnRun } from '../../mcp/child.ts'; +import type { Clock } from '../connection.ts'; +import { + CHECK_PASS_MAX_MS, + CHECK_SCENARIO_MAX_MS, + checkTotals, + isCheckProgressLine, +} from '../launch/check.ts'; +import { LAUNCH_KILL_GRACE_MS } from '../launch/index.ts'; +import type { Logger } from '../log.ts'; +import { + type LastPass, + type PassOutcome, + readScheduleState, + type ScheduledRoot, + type ScheduleState, + writeScheduleState, +} from './state.ts'; + +/** Decision 3: the cadence is daily at most; a minute is the precision set. */ +export const SCHEDULE_TICK_MS = 60_000; + +/** Decision 6: what the website learns of the machine's schedules. */ +export type SchedulesSync = { + type: 'schedules.sync'; + zone: string; + projects: Array<{ rootPath: string; schedule: ScheduleConfig | null }>; +}; + +export interface SchedulerDeps { + clock: Clock; + logger: Logger; + /** The machine's IANA zone, asked on every tick: a laptop travels. */ + zone(): string; + /** + * Decision 4, read on every tick: the reported registry (the only roots + * `schedules.sync` names) and the roots `demoflow run` ran in. + */ + roots(): { reported: Iterable<string>; local: Iterable<string> }; + /** The root's `schedule`, `undefined` without one; throws when the config does not load. */ + loadSchedule(root: string): ScheduleConfig | undefined; + stateFile: string; + spawn: SpawnRun; + /** The daemon's one launch slot; `null` while a website launch holds it. */ + claim(): (() => void) | null; + /** A `schedules.sync` whose content changed since the last one. */ + onSchedules?: (frame: SchedulesSync) => void; + /** Decision 5: the daemon runs without an account. */ + local?: boolean; +} + +interface Pass { + root: string; + child?: RunChild; + ending?: 'cancelled' | 'timed-out'; + done: Promise<void>; +} + +/** A root as `runner.log` names it: its folder name, never its path. */ +function label(root: string): string { + return path.basename(root) || 'root'; +} + +/** + * Spec 361, Decision 3: runs a check pass of each watched root at its due + * slot, one pass at a time and never alongside a website launch. A machine + * that missed several slots runs one pass (Decision 2). + */ +export class Scheduler { + private readonly deps: SchedulerDeps; + private state: ScheduleState = { zone: 'UTC', roots: {} }; + private readonly queue: string[] = []; + private pass: Pass | null = null; + private cancelTick: () => void = () => {}; + private stopping: Promise<void> | null = null; + /** The config failure last logged per root, so each is logged once. */ + private readonly failures = new Map<string, string>(); + private frame: SchedulesSync | null = null; + private sentFrame = ''; + + constructor(deps: SchedulerDeps) { + this.deps = deps; + } + + /** Reads the state file and ticks: on start, then once a minute. */ + start(): void { + const saved = readScheduleState(this.deps.stateFile); + if (saved !== null) this.state = saved; + this.tick(); + } + + /** Called when the launch slot frees up: a queued pass may start. */ + wake(): void { + this.pump(); + } + + /** The current `schedules.sync`, for the frame after `launches.sync`. */ + schedules(): SchedulesSync | null { + return this.frame; + } + + /** Stops ticking and kills a running pass; resolves once it is gone. */ + stop(): Promise<void> { + this.stopping ??= (async () => { + this.cancelTick(); + this.queue.length = 0; + const pass = this.pass; + if (pass === null) return; + pass.ending ??= 'cancelled'; + await pass.child?.kill(); + await pass.done; + })(); + return this.stopping; + } + + private tick(): void { + if (this.stopping !== null) return; + const { clock } = this.deps; + const now = clock.now(); + try { + this.look(now); + } catch { + this.deps.logger.log('error', 'schedule: the tick failed'); + } + // On the minute, so 09:30 runs at 09:30 and not at 09:30:59. + const delay = SCHEDULE_TICK_MS - (clock.now() % SCHEDULE_TICK_MS); + this.cancelTick = clock.after(delay, () => this.tick()); + } + + private look(now: number): void { + const zone = this.deps.zone(); + const { reported, local } = this.deps.roots(); + const registry = new Set(reported); + const watched = [...new Set([...registry, ...local])].sort(); + const roots: Record<string, ScheduledRoot> = {}; + for (const root of watched) { + const previous = this.state.roots[root]; + const schedule = this.scheduleOf(root); + const entry: ScheduledRoot = {}; + if (previous?.last !== undefined) entry.last = previous.last; + if (schedule !== undefined) { + entry.schedule = schedule; + // A new schedule is not due for a slot before the daemon saw it. + entry.seenAt = previous?.seenAt ?? new Date(now).toISOString(); + } + if (entry.schedule !== undefined || entry.last !== undefined) { + roots[root] = entry; + } + } + const next: ScheduleState = { + zone, + ...(this.deps.local === true ? { local: true } : {}), + roots, + }; + if (JSON.stringify(next) !== JSON.stringify(this.state)) { + this.state = next; + this.save(); + } + for (const [root, entry] of Object.entries(roots)) { + if (this.isDue(root, entry, now, zone)) this.queue.push(root); + } + this.sync( + zone, + watched.filter((root) => registry.has(root)), + ); + this.pump(); + } + + private scheduleOf(root: string): ScheduleConfig | undefined { + try { + const schedule = this.deps.loadSchedule(root); + if (this.failures.delete(root)) { + this.deps.logger.log('info', `schedule: ${label(root)}: config loads`); + } + return schedule; + } catch (error) { + // Not the message: it may hold a path (spec 248, Decision 13). + const reason = error instanceof Error ? error.message : String(error); + if (this.failures.get(root) !== reason) { + this.failures.set(root, reason); + this.deps.logger.log( + 'warn', + `schedule: ${label(root)}: skipped, the config does not load`, + ); + } + return undefined; + } + } + + private isDue( + root: string, + entry: ScheduledRoot, + now: number, + zone: string, + ): boolean { + if (entry.schedule === undefined) return false; + if (this.pass?.root === root || this.queue.includes(root)) return false; + const since = Date.parse(entry.last?.startedAt ?? entry.seenAt ?? ''); + if (Number.isNaN(since)) return false; + try { + return lastDueSlot(entry.schedule, now, zone) > since; + } catch { + return false; + } + } + + private sync(zone: string, reported: string[]): void { + const frame: SchedulesSync = { + type: 'schedules.sync', + zone, + projects: reported.map((rootPath) => ({ + rootPath, + schedule: this.state.roots[rootPath]?.schedule ?? null, + })), + }; + this.frame = frame; + const text = JSON.stringify(frame); + if (text === this.sentFrame) return; + this.sentFrame = text; + this.deps.onSchedules?.(frame); + } + + private save(): void { + try { + writeScheduleState(this.deps.stateFile, this.state); + } catch { + this.deps.logger.log('warn', 'schedule: could not write the state file'); + } + } + + /** One pass at a time, in the slot the website's launches use. */ + private pump(): void { + if (this.pass !== null || this.stopping !== null) return; + for (;;) { + const root = this.queue[0]; + if (root === undefined) return; + const schedule = this.state.roots[root]?.schedule; + if (schedule === undefined) { + this.queue.shift(); + continue; + } + const release = this.deps.claim(); + if (release === null) return; + this.queue.shift(); + const pass: Pass = { root, done: Promise.resolve() }; + this.pass = pass; + pass.done = this.run(pass, schedule) + .catch(() => { + this.deps.logger.log( + 'error', + `schedule: ${label(root)}: pass failed`, + ); + }) + .finally(() => { + this.pass = null; + release(); + this.pump(); + }); + return; + } + } + + private async run(pass: Pass, schedule: ScheduleConfig): Promise<void> { + const { clock, logger } = this.deps; + const { root } = pass; + // Decision 3: written before the spawn, so a crash does not repeat the slot. + const last: LastPass = { startedAt: new Date(clock.now()).toISOString() }; + this.record(root, last); + // Set from the child's stdout; an object, so the narrowing survives. + const seen: { totals: { passed: number; failed: number } | null } = { + totals: null, + }; + let cancelScenarioCap = (): void => {}; + const capScenario = () => { + cancelScenarioCap(); + cancelScenarioCap = clock.after(CHECK_SCENARIO_MAX_MS, () => { + void this.end(pass, 'timed-out'); + }); + }; + const exclude = schedule.exclude ?? []; + const child = this.deps.spawn( + [ + 'run', + '--check', + '--json', + '--progress', + '--project', + root, + ...exclude.flatMap((id) => ['--exclude', id]), + ], + root, + { + killGraceMs: LAUNCH_KILL_GRACE_MS, + onStdoutLine: (line) => { + if (isCheckProgressLine(line)) capScenario(); + seen.totals = checkTotals(line) ?? seen.totals; + }, + }, + ); + if (child.pid === undefined) { + await child.exited; + logger.log('warn', `schedule: ${label(root)}: the pass did not start`); + this.finish(root, last, 'not-started', null); + return; + } + pass.child = child; + logger.log( + 'info', + `schedule: ${label(root)}: check pass started, ${exclude.length} excluded`, + ); + capScenario(); + const cancelPassCap = clock.after(CHECK_PASS_MAX_MS, () => { + void this.end(pass, 'timed-out'); + }); + await child.exited; + cancelScenarioCap(); + cancelPassCap(); + const outcome: PassOutcome = pass.ending ?? 'finished'; + const counts = outcome === 'finished' ? seen.totals : null; + logger.log( + 'info', + `schedule: ${label(root)}: ${outcome}, ${counts?.passed ?? 0} passed, ${counts?.failed ?? 0} failed`, + ); + this.finish(root, last, outcome, counts); + } + + private async end( + pass: Pass, + reason: 'cancelled' | 'timed-out', + ): Promise<void> { + pass.ending ??= reason; + await pass.child?.kill(); + } + + private finish( + root: string, + started: LastPass, + outcome: PassOutcome, + counts: { passed: number; failed: number } | null, + ): void { + this.record(root, { + ...started, + finishedAt: new Date(this.deps.clock.now()).toISOString(), + outcome, + ...(counts ?? {}), + }); + } + + private record(root: string, last: LastPass): void { + const entry = this.state.roots[root] ?? {}; + this.state = { + ...this.state, + roots: { ...this.state.roots, [root]: { ...entry, last } }, + }; + this.save(); + } +} diff --git a/apps/cli/src/runner/schedule/state.ts b/apps/cli/src/runner/schedule/state.ts new file mode 100644 index 00000000..a3fbb0a4 --- /dev/null +++ b/apps/cli/src/runner/schedule/state.ts @@ -0,0 +1,109 @@ +import { readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'; +import { type ScheduleConfig, ScheduleConfigSchema } from '@demoflow/core'; + +/** How a scheduled check pass ended. */ +export type PassOutcome = + | 'finished' + | 'timed-out' + | 'cancelled' + | 'not-started'; + +const OUTCOMES: readonly PassOutcome[] = [ + 'finished', + 'timed-out', + 'cancelled', + 'not-started', +]; + +/** The last scheduled pass of a root. Counts only once it finished. */ +export interface LastPass { + startedAt: string; + finishedAt?: string; + outcome?: PassOutcome; + passed?: number; + failed?: number; +} + +/** One root of `schedule.state.json`. */ +export interface ScheduledRoot { + /** The root's parsed `schedule`; absent once its config has none. */ + schedule?: ScheduleConfig; + /** + * When the daemon first saw this schedule: a slot before it is not due, so a + * schedule added today does not fire for yesterday. + */ + seenAt?: string; + last?: LastPass; +} + +/** + * `schedule.state.json` (spec 361, Decision 3): written by the daemon only, + * read by `runner status`. Never a token, never a scenario. + */ +export interface ScheduleState { + /** The machine's IANA zone when the daemon last looked. */ + zone: string; + /** `true` while the daemon runs without an account (Decision 5). */ + local?: boolean; + roots: Record<string, ScheduledRoot>; +} + +/** Through a temp file and a rename, so `status` never reads half a file. */ +export function writeScheduleState(file: string, state: ScheduleState): void { + const temp = `${file}.${process.pid}.tmp`; + try { + writeFileSync(temp, `${JSON.stringify(state)}\n`, { mode: 0o600 }); + renameSync(temp, file); + } catch (error) { + rmSync(temp, { force: true }); + throw error; + } +} + +/** A missing or malformed file is `null`; a malformed root is left out. */ +export function readScheduleState(file: string): ScheduleState | null { + let raw: unknown; + try { + raw = JSON.parse(readFileSync(file, 'utf8')); + } catch { + return null; + } + if (!isRecord(raw) || typeof raw.zone !== 'string' || !isRecord(raw.roots)) { + return null; + } + const roots: Record<string, ScheduledRoot> = {}; + for (const [root, value] of Object.entries(raw.roots)) { + if (!isRecord(value)) continue; + const entry: ScheduledRoot = {}; + const schedule = ScheduleConfigSchema.safeParse(value.schedule); + if (schedule.success) entry.schedule = schedule.data; + if (typeof value.seenAt === 'string') entry.seenAt = value.seenAt; + const last = lastPassOf(value.last); + if (last !== undefined) entry.last = last; + roots[root] = entry; + } + return { + zone: raw.zone, + ...(raw.local === true ? { local: true } : {}), + roots, + }; +} + +function lastPassOf(value: unknown): LastPass | undefined { + if (!isRecord(value) || typeof value.startedAt !== 'string') return undefined; + const last: LastPass = { startedAt: value.startedAt }; + if (typeof value.finishedAt === 'string') last.finishedAt = value.finishedAt; + const outcome = OUTCOMES.find((known) => known === value.outcome); + if (outcome !== undefined) last.outcome = outcome; + if (isCount(value.passed)) last.passed = value.passed; + if (isCount(value.failed)) last.failed = value.failed; + return last; +} + +function isRecord(value: unknown): value is Record<string, unknown> { + return typeof value === 'object' && value !== null && !Array.isArray(value); +} + +function isCount(value: unknown): value is number { + return typeof value === 'number' && Number.isInteger(value) && value >= 0; +} diff --git a/apps/cli/src/runner/state.ts b/apps/cli/src/runner/state.ts index 1dd425d6..bdbfa1c9 100644 --- a/apps/cli/src/runner/state.ts +++ b/apps/cli/src/runner/state.ts @@ -4,20 +4,24 @@ export type ConnectionState = | 'connecting' | 'connected' | 'reconnecting' - | 'revoked'; + | 'revoked' + /** Spec 361, Decision 5: no account, scheduled checks only. */ + | 'local'; const STATES: readonly ConnectionState[] = [ 'connecting', 'connected', 'reconnecting', 'revoked', + 'local', ]; /** `runner.state.json`: what the daemon tells `status`. Never the token. */ export interface RunnerState { pid: number; startedAt: string; - server: string; + /** Absent in local mode: there is no server (spec 361, Decision 5). */ + server?: string; state: ConnectionState; /** When the next attempt starts, while `reconnecting`. */ retryAt?: string; @@ -54,7 +58,7 @@ export function readState(file: string): RunnerState | null { if ( typeof pid !== 'number' || typeof startedAt !== 'string' || - typeof server !== 'string' || + (server !== undefined && typeof server !== 'string') || typeof updatedAt !== 'string' || known === undefined ) { @@ -63,7 +67,7 @@ export function readState(file: string): RunnerState | null { return { pid, startedAt, - server, + ...(typeof server === 'string' ? { server } : {}), state: known, ...(typeof retryAt === 'string' ? { retryAt } : {}), updatedAt, diff --git a/apps/cli/src/runs-report/reported-runs.ts b/apps/cli/src/runs-report/reported-runs.ts index c48e068f..be526268 100644 --- a/apps/cli/src/runs-report/reported-runs.ts +++ b/apps/cli/src/runs-report/reported-runs.ts @@ -63,15 +63,28 @@ export async function readReportedRunsByDir( * throws: a missing or unreadable index registers nothing. */ export async function knownRoots(file: string): Promise<Set<string>> { - const roots = new Set<string>(); try { - const text = await readFile(file, 'utf8'); - for (const line of text.split('\n')) { - const root = parseLine(line)?.root; - if (root !== undefined) roots.add(root); - } + return rootsIn(await readFile(file, 'utf8')); } catch { // An unreadable index is an empty one. + return new Set(); + } +} + +/** `knownRoots` for a caller that cannot wait: the scheduler's tick, `runner status`. */ +export function knownRootsSync(file: string): Set<string> { + try { + return rootsIn(readFileSync(file, 'utf8')); + } catch { + return new Set(); + } +} + +function rootsIn(text: string): Set<string> { + const roots = new Set<string>(); + for (const line of text.split('\n')) { + const root = parseLine(line)?.root; + if (root !== undefined) roots.add(root); } return roots; } diff --git a/apps/cli/test/runner/daemon-launch.spec.ts b/apps/cli/test/runner/daemon-launch.spec.ts index b236e5ae..0f296066 100644 --- a/apps/cli/test/runner/daemon-launch.spec.ts +++ b/apps/cli/test/runner/daemon-launch.spec.ts @@ -242,7 +242,10 @@ describe('the daemon with a website-started run', () => { // Let the launcher settle: the run.finished has no socket and is dropped. await new Promise((r) => setTimeout(r, 50)); const next = await reconnect(); - expect(next.sent).toEqual([ + // Spec 361: `schedules.sync` follows; it is not about this run. + expect( + next.sent.filter((frame) => frame.type !== 'schedules.sync'), + ).toEqual([ { type: 'launches.sync', running: [], From 591dd461a9ab2475fa0ede68cab5e8c1be4b4343 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 18:04:28 +0100 Subject: [PATCH 49/71] feat(api): store a project's GitHub link and how it was added Projects gain githubUrl (https://github.com/<owner>/<repo>, display only) and source (reported | website). PATCH /projects/:id sets or clears the link; ProjectView exposes both, and existing rows read source 'reported'. createFromFolder stores a website-added project and answers 409 project-exists with the holder's id for a folder already registered. Refs #378 --- .../migration.sql | 6 ++ apps/api/prisma/schema.prisma | 9 +++ apps/api/src/projects/projects.dto.ts | 26 +++++++- .../src/projects/projects.integration.spec.ts | 2 + apps/api/src/projects/projects.service.ts | 63 ++++++++++++++++++- 5 files changed, 104 insertions(+), 2 deletions(-) create mode 100644 apps/api/prisma/migrations/20261027150000_project_github_url/migration.sql diff --git a/apps/api/prisma/migrations/20261027150000_project_github_url/migration.sql b/apps/api/prisma/migrations/20261027150000_project_github_url/migration.sql new file mode 100644 index 00000000..1fc7e106 --- /dev/null +++ b/apps/api/prisma/migrations/20261027150000_project_github_url/migration.sql @@ -0,0 +1,6 @@ +-- CreateEnum +CREATE TYPE "ProjectSource" AS ENUM ('reported', 'website'); + +-- AlterTable +ALTER TABLE "Project" ADD COLUMN "githubUrl" TEXT, +ADD COLUMN "source" "ProjectSource" NOT NULL DEFAULT 'reported'; diff --git a/apps/api/prisma/schema.prisma b/apps/api/prisma/schema.prisma index b680c041..a1424b79 100644 --- a/apps/api/prisma/schema.prisma +++ b/apps/api/prisma/schema.prisma @@ -111,6 +111,9 @@ model Project { runner Runner? @relation(fields: [runnerId], references: [id], onDelete: SetNull) // Absolute path of the project root on that machine, as the CLI sent it. rootPath String? + // https://github.com/<owner>/<repo>; display only (ADR-0022 §5). + githubUrl String? + source ProjectSource @default(reported) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt runs Run[] @@ -119,6 +122,12 @@ model Project { @@index([userId]) } +// How a project was added (spec #378): by a CLI report, or from the website. +enum ProjectSource { + reported + website +} + enum RunStatus { passed failed diff --git a/apps/api/src/projects/projects.dto.ts b/apps/api/src/projects/projects.dto.ts index a202948c..70094701 100644 --- a/apps/api/src/projects/projects.dto.ts +++ b/apps/api/src/projects/projects.dto.ts @@ -1,3 +1,4 @@ +import { applyDecorators } from '@nestjs/common'; import { Transform, Type } from 'class-transformer'; import { ArrayMaxSize, @@ -11,6 +12,7 @@ import { IsOptional, IsString, Length, + Matches, Max, MaxLength, Min, @@ -23,6 +25,21 @@ const trim = ({ value }: { value: unknown }): unknown => export const PROJECT_NAME_MAX = 200; export const PATH_MAX = 4096; +/** + * A repository page and nothing else (spec #378, Decision 1): no other host, + * no credentials, no path below the repository. + */ +export const GITHUB_URL_PATTERN = + /^https:\/\/github\.com\/[A-Za-z0-9._-]{1,100}\/[A-Za-z0-9._-]{1,100}$/; + +/** With `@IsOptional()`, which also lets `null` through: no URL. */ +export const IsGithubUrl = () => + applyDecorators( + IsString(), + Matches(GITHUB_URL_PATTERN, { + message: 'githubUrl must be https://github.com/<owner>/<repo>', + }), + ); /** `RENDER_FORMATS` of `@demoflow/core`, which the API does not depend on. */ export const RUN_FORMATS = [ @@ -211,7 +228,10 @@ export class CreateProjectDto { name!: string; } -/** Renames and binds. `runnerId` and `rootPath` come together or not at all. */ +/** + * Renames, binds, and sets or clears the GitHub URL (spec #378, Decision 7). + * `runnerId` and `rootPath` come together or not at all. + */ export class UpdateProjectDto { @IsOptional() @Transform(trim) @@ -219,6 +239,10 @@ export class UpdateProjectDto { @Length(1, PROJECT_NAME_MAX) name?: string; + @IsOptional() + @IsGithubUrl() + githubUrl?: string | null; + @ValidateIf((dto: UpdateProjectDto) => dto.rootPath !== undefined) @IsString() @Length(1, 64) diff --git a/apps/api/src/projects/projects.integration.spec.ts b/apps/api/src/projects/projects.integration.spec.ts index 5c9c8573..0f7f412d 100644 --- a/apps/api/src/projects/projects.integration.spec.ts +++ b/apps/api/src/projects/projects.integration.spec.ts @@ -88,6 +88,8 @@ describe('projects (integration)', () => { id: res.body.projectId, name: 'shop', rootPath: ROOT, + githubUrl: null, + source: 'reported', runner: { id: laptop.runnerId, name: 'Laptop' }, runCount: 1, lastRun: { diff --git a/apps/api/src/projects/projects.service.ts b/apps/api/src/projects/projects.service.ts index 067e8e6d..5d502ae9 100644 --- a/apps/api/src/projects/projects.service.ts +++ b/apps/api/src/projects/projects.service.ts @@ -1,11 +1,19 @@ import { BadRequestException, ConflictException, + HttpException, + HttpStatus, Injectable, Logger, NotFoundException, } from '@nestjs/common'; -import { Prisma, type Run, type Runner, type RunStatus } from '@prisma/client'; +import { + Prisma, + type ProjectSource, + type Run, + type Runner, + type RunStatus, +} from '@prisma/client'; import { PrismaService } from '../database/prisma.service'; import { ShareStorage } from '../shares/share-storage'; import { @@ -46,6 +54,10 @@ export interface ProjectView { rootPath: string | null; /** Null for a project never bound, or whose machine was revoked. */ runner: { id: string; name: string } | null; + /** `https://github.com/<owner>/<repo>`, display only (ADR-0022 §5). */ + githubUrl: string | null; + /** `website` when added through the folder dialog (spec #378). */ + source: ProjectSource; runCount: number; lastRun: RunView | null; createdAt: Date; @@ -193,6 +205,8 @@ function toProjectView(project: ProjectWithSummary): ProjectView { name: project.name, rootPath: project.rootPath, runner: project.runner, + githubUrl: project.githubUrl, + source: project.source, runCount: project._count.runs, lastRun: lastRun ? toRunView(lastRun) : null, createdAt: project.createdAt, @@ -286,6 +300,50 @@ export class ProjectsService { return toProjectView(project); } + /** + * The project of a folder the machine registered (spec #378, Decision 5): + * `rootPath` is the machine's canonical answer, never the browser's path. + * A folder another project already holds answers `409 project-exists` + * with that project's id. + */ + async createFromFolder( + userId: string, + folder: { + runnerId: string; + rootPath: string; + name: string; + githubUrl: string | null; + }, + ): Promise<ProjectView> { + try { + const project = await this.prisma.project.create({ + data: { userId, ...folder, source: 'website' }, + include: PROJECT_INCLUDE, + }); + return toProjectView(project); + } catch (error) { + if ( + error instanceof Prisma.PrismaClientKnownRequestError && + error.code === 'P2002' + ) { + const holder = await this.prisma.project.findUnique({ + where: { + runnerId_rootPath: { + runnerId: folder.runnerId, + rootPath: folder.rootPath, + }, + }, + select: { id: true }, + }); + throw new HttpException( + { error: 'project-exists', projectId: holder?.id ?? null }, + HttpStatus.CONFLICT, + ); + } + throw error; + } + } + /** * Renames and binds. Binding to a folder another project already holds * merges it into this one, in one transaction: its runs move here, it is @@ -309,6 +367,9 @@ export class ProjectsService { if (body.name !== undefined) { data.name = body.name; } + if (body.githubUrl !== undefined) { + data.githubUrl = body.githubUrl; + } if (body.runnerId !== undefined && body.rootPath !== undefined) { const runner = await tx.runner.findFirst({ where: { id: body.runnerId, userId, revokedAt: null }, From 2b2f9ebc1cfcebfc124b3d513699e42bcf576e43 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 18:04:33 +0100 Subject: [PATCH 50/71] feat(api): add a project from a folder on one of the user's machines POST /projects/folders/inspect, /init and /register relay project.inspect, project.init and project.register to the chosen online machine and answer what it said. register stores only the canonical rootPath the Runner answered. Checks run before anything is sent: another account's machine answers 404 runner-not-found, an offline one 409 runner-offline, one without the projects feature 409 runner-outdated. A silent Runner gives 504 runner-timeout after 10 s; Runner error codes map to 422/409/502. The three routes share a 30-per-minute per-user throttle. Runner views list the features of the machine's socket. Refs #378 --- apps/api/src/auth/auth-throttle.ts | 14 + .../projects/folders/folders.controller.ts | 58 ++ apps/api/src/projects/folders/folders.dto.ts | 35 ++ .../folders/folders.integration.spec.ts | 514 ++++++++++++++++++ .../src/projects/folders/folders.service.ts | 330 +++++++++++ apps/api/src/projects/projects.module.ts | 7 +- .../src/runner/runner-connections.service.ts | 40 ++ apps/api/src/runner/runner-socket.fixtures.ts | 17 + apps/api/src/runner/runner-socket.spec.ts | 83 +++ apps/api/src/runner/runner-socket.ts | 137 ++++- .../src/runner/runners.integration.spec.ts | 1 + apps/api/src/runner/runners.service.ts | 17 +- 12 files changed, 1243 insertions(+), 10 deletions(-) create mode 100644 apps/api/src/projects/folders/folders.controller.ts create mode 100644 apps/api/src/projects/folders/folders.dto.ts create mode 100644 apps/api/src/projects/folders/folders.integration.spec.ts create mode 100644 apps/api/src/projects/folders/folders.service.ts diff --git a/apps/api/src/auth/auth-throttle.ts b/apps/api/src/auth/auth-throttle.ts index c7ccb138..1851de15 100644 --- a/apps/api/src/auth/auth-throttle.ts +++ b/apps/api/src/auth/auth-throttle.ts @@ -21,6 +21,11 @@ export const THROTTLE_MAIL = 'mail-email'; export const THROTTLE_DEVICE_POLL = 'device-poll'; /** A share's password (spec #348, Decision 6): per address and share token. */ export const THROTTLE_SHARE_UNLOCK = 'share-unlock'; +/** + * Adding a project from a folder (spec #378, Decision 8): per user, across + * inspect, init and register, so a hijacked session cannot probe a machine. + */ +export const THROTTLE_PROJECT_FOLDERS = 'project-folders'; /** Class-level: every throttler skipped until a route opts in. */ export const SKIP_ALL_THROTTLERS = { @@ -29,6 +34,7 @@ export const SKIP_ALL_THROTTLERS = { [THROTTLE_MAIL]: true, [THROTTLE_DEVICE_POLL]: true, [THROTTLE_SHARE_UNLOCK]: true, + [THROTTLE_PROJECT_FOLDERS]: true, }; export const authThrottlerOptions: ThrottlerModuleOptions = { @@ -73,6 +79,14 @@ export const authThrottlerOptions: ThrottlerModuleOptions = { return `ip:${request.ip ?? ''}:share:${routeToken(request)}`; }, }, + { + name: THROTTLE_PROJECT_FOLDERS, + limit: 30, + ttl: MINUTE_MS, + // Behind `SessionGuard`: there is always a user. + getTracker: (req) => + `user:${(req as AuthenticatedRequest).auth?.user.id ?? ''}`, + }, ], // The default key includes the route, which would give each endpoint its // own budget. The limits are across the auth endpoints. diff --git a/apps/api/src/projects/folders/folders.controller.ts b/apps/api/src/projects/folders/folders.controller.ts new file mode 100644 index 00000000..75baf5fa --- /dev/null +++ b/apps/api/src/projects/folders/folders.controller.ts @@ -0,0 +1,58 @@ +import { + Body, + Controller, + HttpCode, + HttpStatus, + Post, + UseGuards, +} from '@nestjs/common'; +import { SkipThrottle, ThrottlerGuard } from '@nestjs/throttler'; +import type { User } from '@prisma/client'; +import { + SKIP_ALL_THROTTLERS, + THROTTLE_PROJECT_FOLDERS, +} from '../../auth/auth-throttle'; +import { CurrentUser } from '../../auth/current-user.decorator'; +import { SessionGuard } from '../../auth/session.guard'; +import type { ProjectView } from '../projects.service'; +import { FolderDto, RegisterFolderDto } from './folders.dto'; +import { + FoldersService, + type InitView, + type InspectionView, +} from './folders.service'; + +/** + * Adding a project from a folder on one of the user's machines (spec #378). + * The three routes share one per-user budget (Decision 8). + */ +@Controller('projects/folders') +// One decorator: two on a class set the same keys, and the outer one wins. +@SkipThrottle({ ...SKIP_ALL_THROTTLERS, [THROTTLE_PROJECT_FOLDERS]: false }) +@UseGuards(SessionGuard, ThrottlerGuard) +export class FoldersController { + constructor(private readonly folders: FoldersService) {} + + @Post('inspect') + @HttpCode(HttpStatus.OK) + inspect( + @CurrentUser() user: User, + @Body() body: FolderDto, + ): Promise<InspectionView> { + return this.folders.inspect(user.id, body.runnerId, body.path); + } + + @Post('init') + @HttpCode(HttpStatus.OK) + init(@CurrentUser() user: User, @Body() body: FolderDto): Promise<InitView> { + return this.folders.init(user.id, body.runnerId, body.path); + } + + @Post('register') + async register( + @CurrentUser() user: User, + @Body() body: RegisterFolderDto, + ): Promise<{ project: ProjectView }> { + return { project: await this.folders.register(user.id, body) }; + } +} diff --git a/apps/api/src/projects/folders/folders.dto.ts b/apps/api/src/projects/folders/folders.dto.ts new file mode 100644 index 00000000..48bbb161 --- /dev/null +++ b/apps/api/src/projects/folders/folders.dto.ts @@ -0,0 +1,35 @@ +import { Transform } from 'class-transformer'; +import { IsOptional, IsString, Length, ValidateIf } from 'class-validator'; +import { IsGithubUrl, PATH_MAX, PROJECT_NAME_MAX } from '../projects.dto'; + +const trim = ({ value }: { value: unknown }): unknown => + typeof value === 'string' ? value.trim() : value; + +/** `POST /projects/folders/inspect` and `/init` (spec #378, Decision 1). */ +export class FolderDto { + @IsString() + @Length(1, 64) + runnerId!: string; + + /** As the person typed it: the machine resolves it, and only its answer is stored. */ + @IsString() + @Length(1, PATH_MAX) + path!: string; +} + +/** + * `POST /projects/folders/register`. Without `name`, the folder's name; without + * `githubUrl`, the inspection's; `githubUrl: null` stores none. + */ +export class RegisterFolderDto extends FolderDto { + // Not `@IsOptional()`: `null` is no second spelling of the default. + @ValidateIf((_, value) => value !== undefined) + @Transform(trim) + @IsString() + @Length(1, PROJECT_NAME_MAX) + name?: string; + + @IsOptional() + @IsGithubUrl() + githubUrl?: string | null; +} diff --git a/apps/api/src/projects/folders/folders.integration.spec.ts b/apps/api/src/projects/folders/folders.integration.spec.ts new file mode 100644 index 00000000..fbf9d4fb --- /dev/null +++ b/apps/api/src/projects/folders/folders.integration.spec.ts @@ -0,0 +1,514 @@ +import type { AddressInfo } from 'node:net'; +import request, { type Response } from 'supertest'; +import type { App } from 'supertest/types'; +import { + type Paired, + pair, + type SignedIn, + signedInUser, +} from '../../runner/runner.fixtures'; +import { + type ProjectRequest, + TestSocket, +} from '../../runner/runner-socket.fixtures'; +import { createTestApp, type TestApp } from '../../test/test-app'; +import { + FOLDER_TIMEOUT_MS, + FoldersService, + folderName, +} from './folders.service'; + +const ROOT = '/home/u/app'; +const GITHUB = 'https://github.com/acme/app'; +const PROJECT_TYPES = ['project.inspect', 'project.init', 'project.register']; + +function inspection(overrides: Record<string, unknown> = {}) { + return { + rootPath: ROOT, + name: 'app', + hasConfig: true, + configValid: true, + scenarios: [{ id: 'demoflow/checkout.demo.json', name: 'Checkout' }], + githubUrl: GITHUB, + ...overrides, + }; +} + +describe('adding a project from a folder (integration)', () => { + let t: TestApp; + let http: App; + let port: number; + let alice: SignedIn; + let bob: SignedIn; + let machine: Paired; + const sockets: TestSocket[] = []; + + beforeEach(async () => { + t = await createTestApp(); + await t.app.listen(0, '127.0.0.1'); + http = t.app.getHttpServer(); + port = (http.address() as AddressInfo).port; + alice = await signedInUser(t, 'alice'); + bob = await signedInUser(t, 'bob'); + machine = await pair(http, alice, 'Laptop'); + }); + + afterEach(async () => { + for (const socket of sockets.splice(0)) { + socket.ws.terminate(); + } + await t.app.close(); + }); + + /** A connected daemon announcing `features` (`projects` by default). */ + async function daemon( + features: string[] = ['projects'], + on = machine, + ): Promise<TestSocket> { + const socket = await TestSocket.connect( + `ws://127.0.0.1:${port}/runner`, + on.token, + ); + sockets.push(socket); + socket.sync([], undefined, features); + await socket.roundTrip(); + return socket; + } + + /** Starts the request, so a test can answer as the daemon meanwhile. */ + function post( + action: 'inspect' | 'init' | 'register', + body: object, + cookie = alice.cookie, + ): Promise<Response> { + return request(http) + .post(`/projects/folders/${action}`) + .set('Cookie', cookie) + .send(body) + .then((res) => res); + } + + function projects(cookie = alice.cookie): Promise<Response> { + return request(http) + .get('/projects') + .set('Cookie', cookie) + .then((res) => res); + } + + function sentProjectMessages(socket: TestSocket): unknown[] { + return socket.received.filter((m) => PROJECT_TYPES.includes(m.type)); + } + + /** Plays the daemon through a whole `register` without a `githubUrl`. */ + async function register( + socket: TestSocket, + body: object = { runnerId: machine.runnerId, path: '~/app/../app' }, + rootPath = ROOT, + ): Promise<Response> { + const pending = post('register', body); + const inspect = await socket.nextProject('project.inspect'); + socket.send({ + type: 'project.inspected', + requestId: inspect.requestId, + inspection: inspection({ rootPath }), + }); + const ask = await socket.nextProject('project.register'); + socket.send({ + type: 'project.registered', + requestId: ask.requestId, + rootPath, + }); + return pending; + } + + describe('relaying to the machine', () => { + it('inspects a folder and answers what the Runner said', async () => { + const socket = await daemon(); + const pending = post('inspect', { + runnerId: machine.runnerId, + path: '~/app', + }); + const ask = await socket.nextProject('project.inspect'); + expect(ask.path).toBe('~/app'); + socket.send({ + type: 'project.inspected', + requestId: ask.requestId, + inspection: inspection(), + }); + + const res = await pending; + expect(res.status).toBe(200); + expect(res.body).toEqual(inspection()); + }); + + it('drops a githubUrl the API would not accept', async () => { + const socket = await daemon(); + const pending = post('inspect', { + runnerId: machine.runnerId, + path: '~/app', + }); + const ask = await socket.nextProject('project.inspect'); + socket.send({ + type: 'project.inspected', + requestId: ask.requestId, + inspection: inspection({ githubUrl: 'https://gitlab.com/acme/app' }), + }); + + expect((await pending).body.githubUrl).toBeNull(); + }); + + it('initialises a folder and answers the files and the new inspection', async () => { + const socket = await daemon(); + const pending = post('init', { + runnerId: machine.runnerId, + path: '~/app', + }); + const ask = await socket.nextProject('project.init'); + socket.send({ + type: 'project.initialised', + requestId: ask.requestId, + created: ['demoflow.config.json', 'demoflow/hello.demo.json'], + kept: [], + inspection: inspection(), + }); + + const res = await pending; + expect(res.status).toBe(200); + expect(res.body).toEqual({ + created: ['demoflow.config.json', 'demoflow/hello.demo.json'], + kept: [], + inspection: inspection(), + }); + }); + + it('registers the canonical rootPath the Runner answered, not the request path', async () => { + const socket = await daemon(); + const res = await register(socket); + + expect(res.status).toBe(201); + expect(res.body.project).toEqual( + expect.objectContaining({ + name: 'app', + rootPath: ROOT, + githubUrl: GITHUB, + source: 'website', + runner: { id: machine.runnerId, name: 'Laptop' }, + runCount: 0, + lastRun: null, + }), + ); + const row = await t.prisma.project.findUniqueOrThrow({ + where: { id: res.body.project.id }, + }); + expect(row.rootPath).toBe(ROOT); + expect(row.userId).toBe(alice.user.id); + }); + + it('takes the name and githubUrl of the body without inspecting', async () => { + const socket = await daemon(); + const pending = post('register', { + runnerId: machine.runnerId, + path: '~/app', + name: ' Shop ', + githubUrl: null, + }); + const ask = await socket.nextProject('project.register'); + socket.send({ + type: 'project.registered', + requestId: ask.requestId, + rootPath: ROOT, + }); + + const res = await pending; + expect(res.status).toBe(201); + expect(res.body.project).toEqual( + expect.objectContaining({ name: 'Shop', githubUrl: null }), + ); + expect(sentProjectMessages(socket)).toEqual([]); + }); + + it('answers 409 project-exists with the first project for the same folder', async () => { + const socket = await daemon(); + const first = await register(socket); + const second = await register(socket, { + runnerId: machine.runnerId, + path: ROOT, + }); + + expect(second.status).toBe(409); + expect(second.body).toEqual({ + error: 'project-exists', + projectId: first.body.project.id, + }); + }); + + it('answers 409 runner-offline and sends nothing without a socket', async () => { + for (const action of ['inspect', 'init', 'register'] as const) { + const res = await post(action, { + runnerId: machine.runnerId, + path: '~/app', + }); + expect(res.status).toBe(409); + expect(res.body).toEqual({ error: 'runner-offline' }); + } + }); + + it('answers 409 runner-outdated to a Runner without the projects feature', async () => { + const socket = await daemon(['share']); + const res = await post('inspect', { + runnerId: machine.runnerId, + path: '~/app', + }); + + expect(res.status).toBe(409); + expect(res.body).toEqual({ error: 'runner-outdated' }); + await socket.roundTrip(); + expect(sentProjectMessages(socket)).toEqual([]); + }); + + it('lists the features of an online machine', async () => { + await daemon(); + const res = await request(http) + .get('/runners') + .set('Cookie', alice.cookie) + .expect(200); + expect(res.body.runners[0]).toEqual( + expect.objectContaining({ online: true, features: ['projects'] }), + ); + }); + + it.each([ + ['path-not-allowed', 422, 'path-not-allowed'], + ['config-missing', 422, 'config-missing'], + ['config-invalid', 422, 'config-invalid'], + ['busy', 409, 'runner-busy'], + ['internal', 502, 'runner-error'], + ['something-new', 502, 'runner-error'], + ])('maps project.error %s to %i %s', async (code, status, error) => { + const socket = await daemon(); + const pending = post('inspect', { + runnerId: machine.runnerId, + path: '/etc', + }); + const ask = await socket.nextProject('project.inspect'); + socket.send({ type: 'project.error', requestId: ask.requestId, code }); + + const res = await pending; + expect(res.status).toBe(status); + expect(res.body).toEqual({ error }); + }); + + it('ends a request with runner-offline when the socket closes', async () => { + const socket = await daemon(); + const pending = post('inspect', { + runnerId: machine.runnerId, + path: '~/app', + }); + await socket.nextProject('project.inspect'); + await socket.close(); + + const res = await pending; + expect(res.status).toBe(409); + expect(res.body).toEqual({ error: 'runner-offline' }); + }); + }); + + describe('replies', () => { + it('ignores an unknown requestId, a reply of the wrong kind and another machine', async () => { + const socket = await daemon(); + const other = await pair(http, alice, 'Desktop'); + const otherSocket = await daemon(['projects'], other); + const pending = post('inspect', { + runnerId: machine.runnerId, + path: '~/app', + }); + const ask: ProjectRequest = await socket.nextProject('project.inspect'); + + socket.send({ + type: 'project.inspected', + requestId: '6a1f0d4e-2b9c-4c3e-8f7a-1d2e3f4a5b6c', + inspection: inspection({ name: 'unknown' }), + }); + socket.send({ + type: 'project.registered', + requestId: ask.requestId, + rootPath: '/elsewhere', + }); + otherSocket.send({ + type: 'project.inspected', + requestId: ask.requestId, + inspection: inspection({ name: 'other machine' }), + }); + await socket.roundTrip(); + await otherSocket.roundTrip(); + socket.send({ + type: 'project.inspected', + requestId: ask.requestId, + inspection: inspection(), + }); + + const res = await pending; + expect(res.status).toBe(200); + expect(res.body.name).toBe('app'); + // Unanswerable frames never close the socket. + await socket.roundTrip(); + }); + + it('answers 504 runner-timeout when the Runner stays silent for 10 s', async () => { + const socket = await daemon(); + const pending = post('inspect', { + runnerId: machine.runnerId, + path: '~/app', + }); + const ask = await socket.nextProject('project.inspect'); + const folders = t.app.get(FoldersService); + + t.clock.advance(FOLDER_TIMEOUT_MS - 1); + folders.tick(); + t.clock.advance(1); + folders.tick(); + + const res = await pending; + expect(res.status).toBe(504); + expect(res.body).toEqual({ error: 'runner-timeout' }); + // A late answer finds nothing to settle. + socket.send({ + type: 'project.inspected', + requestId: ask.requestId, + inspection: inspection(), + }); + await socket.roundTrip(); + }); + }); + + describe('authorization', () => { + it("answers 404 runner-not-found to another account's machine and sends nothing", async () => { + const socket = await daemon(); + for (const action of ['inspect', 'init', 'register'] as const) { + const res = await post( + action, + { runnerId: machine.runnerId, path: '~/app' }, + bob.cookie, + ); + expect(res.status).toBe(404); + expect(res.body).toEqual({ error: 'runner-not-found' }); + } + await socket.roundTrip(); + expect(sentProjectMessages(socket)).toEqual([]); + }); + + it('answers 404 to an unknown machine', async () => { + const res = await post('inspect', { + runnerId: 'not-a-machine', + path: '~/app', + }); + expect(res.status).toBe(404); + expect(res.body).toEqual({ error: 'runner-not-found' }); + }); + + it("keeps a website-added project out of another account's reach", async () => { + const socket = await daemon(); + const { body } = await register(socket); + + await request(http) + .patch(`/projects/${body.project.id}`) + .set('Cookie', bob.cookie) + .send({ name: 'mine' }) + .expect(404); + expect((await projects(bob.cookie)).body.projects).toEqual([]); + expect((await projects()).body.projects).toEqual([ + expect.objectContaining({ id: body.project.id, name: 'app' }), + ]); + }); + + it('shares 30 requests a minute per user across the three routes', async () => { + const body = { runnerId: 'not-a-machine', path: '~/app' }; + for (let i = 0; i < 30; i++) { + const action = (['inspect', 'init', 'register'] as const)[i % 3]; + expect((await post(action, body)).status).toBe(404); + } + expect((await post('inspect', body)).status).toBe(429); + // Per user: another account still has its budget. + expect((await post('inspect', body, bob.cookie)).status).toBe(404); + }); + + it('needs a session', async () => { + await request(http) + .post('/projects/folders/inspect') + .send({ runnerId: machine.runnerId, path: '~/app' }) + .expect(401); + }); + }); + + describe('githubUrl', () => { + it.each([ + 'https://gitlab.com/acme/app', + 'https://user:secret@github.com/acme/app', + 'http://github.com/acme/app', + 'https://github.com/acme', + 'https://github.com/acme/app/tree/main', + 'https://github.com.evil.example/acme/app', + ])('rejects %s with 400 and sends nothing', async (githubUrl) => { + const socket = await daemon(); + const res = await post('register', { + runnerId: machine.runnerId, + path: '~/app', + githubUrl, + }); + expect(res.status).toBe(400); + await socket.roundTrip(); + expect(sentProjectMessages(socket)).toEqual([]); + }); + + it('is set, rejected and cleared with PATCH', async () => { + const created = await request(http) + .post('/projects') + .set('Cookie', alice.cookie) + .send({ name: 'shop' }) + .expect(201); + const id = created.body.project.id; + const patch = (body: object) => + request(http) + .patch(`/projects/${id}`) + .set('Cookie', alice.cookie) + .send(body); + + expect(created.body.project).toEqual( + expect.objectContaining({ githubUrl: null, source: 'reported' }), + ); + expect( + (await patch({ githubUrl: GITHUB }).expect(200)).body.project, + ).toEqual(expect.objectContaining({ githubUrl: GITHUB })); + await patch({ githubUrl: 'https://user:pw@github.com/acme/app' }).expect( + 400, + ); + expect( + (await patch({ githubUrl: null }).expect(200)).body.project, + ).toEqual(expect.objectContaining({ githubUrl: null })); + }); + }); + + describe('input', () => { + it.each([ + [{ path: '~/app' }], + [{ runnerId: 'r' }], + [{ runnerId: 'r', path: '' }], + [{ runnerId: 'r', path: '~/app', extra: true }], + ])('rejects %j with 400', async (body) => { + const res = await post('inspect', body); + expect(res.status).toBe(400); + }); + }); +}); + +describe('folderName', () => { + it.each([ + ['/home/u/app', 'app'], + ['/home/u/app/', 'app'], + ['C:\\Users\\u\\shop', 'shop'], + ['\\\\server\\share\\demo', 'demo'], + ['/', '/'], + ])('names %s %s', (rootPath, name) => { + expect(folderName(rootPath)).toBe(name); + }); +}); diff --git a/apps/api/src/projects/folders/folders.service.ts b/apps/api/src/projects/folders/folders.service.ts new file mode 100644 index 00000000..e2a4c3a2 --- /dev/null +++ b/apps/api/src/projects/folders/folders.service.ts @@ -0,0 +1,330 @@ +import { randomUUID } from 'node:crypto'; +import { posix, win32 } from 'node:path'; +import { + HttpStatus, + Injectable, + Logger, + type OnApplicationBootstrap, + type OnModuleDestroy, + type OnModuleInit, +} from '@nestjs/common'; +import { Clock } from '../../common/clock'; +import { PrismaService } from '../../database/prisma.service'; +import { + type ProjectSink, + RunnerConnections, +} from '../../runner/runner-connections.service'; +import type { + FolderInspection, + ProjectMessage, +} from '../../runner/runner-socket'; +import { runError } from '../../videos/runs.service'; +import { GITHUB_URL_PATTERN, PROJECT_NAME_MAX } from '../projects.dto'; +import { ProjectsService, type ProjectView } from '../projects.service'; +import type { RegisterFolderDto } from './folders.dto'; + +/** No answer this long after a `project.*` request: 504 (spec #378, Decision 4). */ +export const FOLDER_TIMEOUT_MS = 10 * 1000; +/** How often the timeout is checked. */ +const SWEEP_INTERVAL_MS = 1000; + +/** What the browser gets of a Runner's inspection (spec #377, Decision 5). */ +export interface InspectionView { + rootPath: string; + name: string; + hasConfig: boolean; + configValid: boolean; + scenarios: { id: string; name: string }[]; + githubUrl: string | null; +} + +export interface InitView { + created: string[]; + kept: string[]; + inspection: InspectionView; +} + +type FolderRequest = 'project.inspect' | 'project.init' | 'project.register'; + +/** The reply each request waits for, besides `project.error`. */ +const REPLIES = { + 'project.inspect': 'project.inspected', + 'project.init': 'project.initialised', + 'project.register': 'project.registered', +} as const satisfies Record<FolderRequest, ProjectMessage['type']>; + +type Reply<R extends FolderRequest> = Extract< + ProjectMessage, + { type: (typeof REPLIES)[R] } +>; + +interface Failure { + status: HttpStatus; + error: string; +} + +type Outcome = { ok: true; reply: ProjectMessage } | ({ ok: false } & Failure); + +/** `project.error` codes as HTTP (Decision 4); anything else is `runner-error`. */ +const RUNNER_ERRORS: Record<string, Failure> = { + 'path-not-allowed': { + status: HttpStatus.UNPROCESSABLE_ENTITY, + error: 'path-not-allowed', + }, + 'config-missing': { + status: HttpStatus.UNPROCESSABLE_ENTITY, + error: 'config-missing', + }, + 'config-invalid': { + status: HttpStatus.UNPROCESSABLE_ENTITY, + error: 'config-invalid', + }, + busy: { status: HttpStatus.CONFLICT, error: 'runner-busy' }, +}; +const RUNNER_ERROR: Failure = { + status: HttpStatus.BAD_GATEWAY, + error: 'runner-error', +}; +const OFFLINE: Failure = { + status: HttpStatus.CONFLICT, + error: 'runner-offline', +}; +const TIMEOUT: Failure = { + status: HttpStatus.GATEWAY_TIMEOUT, + error: 'runner-timeout', +}; + +function runnerFailure(code: string): Failure { + return Object.hasOwn(RUNNER_ERRORS, code) + ? RUNNER_ERRORS[code] + : RUNNER_ERROR; +} + +interface Pending { + id: string; + runnerId: string; + type: FolderRequest; + /** Clock ms. */ + sentAt: number; + settle: (outcome: Outcome) => void; +} + +/** + * Adds a project from a folder on one of the user's machines (spec #378, + * ADR-0022): relays `project.inspect`, `project.init` and `project.register` + * to the machine and answers what it said. Only `register` stores anything, + * and only the path the machine answered. + * + * Works only on the instance that holds the Runner's socket, like the + * scenario list (spec #247). + */ +@Injectable() +export class FoldersService + implements ProjectSink, OnModuleInit, OnApplicationBootstrap, OnModuleDestroy +{ + private readonly logger = new Logger(FoldersService.name); + private readonly pending = new Map<string, Pending>(); + private timer: NodeJS.Timeout | undefined; + + constructor( + private readonly connections: RunnerConnections, + private readonly prisma: PrismaService, + private readonly projects: ProjectsService, + private readonly clock: Clock, + ) {} + + onModuleInit(): void { + this.connections.setProjectSink(this); + } + + onApplicationBootstrap(): void { + this.timer = setInterval(() => this.tick(), SWEEP_INTERVAL_MS); + this.timer.unref(); + } + + onModuleDestroy(): void { + clearInterval(this.timer); + } + + async inspect( + userId: string, + runnerId: string, + path: string, + ): Promise<InspectionView> { + await this.target(userId, runnerId); + const reply = await this.ask(runnerId, 'project.inspect', path); + return toInspectionView(reply.inspection); + } + + async init( + userId: string, + runnerId: string, + path: string, + ): Promise<InitView> { + await this.target(userId, runnerId); + const reply = await this.ask(runnerId, 'project.init', path); + return { + created: [...reply.created], + kept: [...reply.kept], + inspection: toInspectionView(reply.inspection), + }; + } + + /** + * Decision 5: the project row holds the canonical `rootPath` of + * `project.registered`. Without a `githubUrl` in the body, the folder is + * inspected first for its default. + */ + async register( + userId: string, + body: RegisterFolderDto, + ): Promise<ProjectView> { + const { runnerId, path } = body; + await this.target(userId, runnerId); + let githubUrl = body.githubUrl; + if (githubUrl === undefined) { + const inspected = await this.ask(runnerId, 'project.inspect', path); + githubUrl = toInspectionView(inspected.inspection).githubUrl; + } + const { rootPath } = await this.ask(runnerId, 'project.register', path); + return this.projects.createFromFolder(userId, { + runnerId, + rootPath, + name: body.name ?? folderName(rootPath), + githubUrl, + }); + } + + message(runnerId: string, message: ProjectMessage): boolean { + const request = this.pending.get(message.requestId); + // Only the machine a request was sent to can answer it, and only in kind. + if ( + request?.runnerId !== runnerId || + (message.type !== 'project.error' && + message.type !== REPLIES[request.type]) + ) { + return false; + } + if (message.type === 'project.error') { + this.end( + request, + { ok: false, ...runnerFailure(message.code) }, + message.code, + ); + } else { + this.end(request, { ok: true, reply: message }, 'answered'); + } + return true; + } + + /** Every request on the machine's socket ends with it. */ + closed(runnerId: string): void { + for (const request of [...this.pending.values()]) { + if (request.runnerId === runnerId) { + this.end(request, { ok: false, ...OFFLINE }, OFFLINE.error); + } + } + } + + /** The timeout, on the injected clock. Runs every `SWEEP_INTERVAL_MS`. */ + tick(): void { + const now = this.now(); + for (const request of [...this.pending.values()]) { + if (now - request.sentAt >= FOLDER_TIMEOUT_MS) { + this.end(request, { ok: false, ...TIMEOUT }, TIMEOUT.error); + } + } + } + + /** + * Decisions 2 and 3, in order, before anything is sent: the user's own + * machine (another account's answers as an unknown one), online, and new + * enough to answer `project.*`. + */ + private async target(userId: string, runnerId: string): Promise<void> { + const count = await this.prisma.runner.count({ + where: { id: runnerId, userId, revokedAt: null }, + }); + if (count !== 1) { + throw runError(HttpStatus.NOT_FOUND, 'runner-not-found'); + } + if (!this.connections.isOnline(runnerId)) { + throw runError(OFFLINE.status, OFFLINE.error); + } + if (!this.connections.features(runnerId).includes('projects')) { + throw runError(HttpStatus.CONFLICT, 'runner-outdated'); + } + } + + private async ask<R extends FolderRequest>( + runnerId: string, + type: R, + path: string, + ): Promise<Reply<R>> { + const outcome = await new Promise<Outcome>((settle) => { + const request: Pending = { + id: randomUUID(), + runnerId, + type, + sentAt: this.now(), + settle, + }; + this.pending.set(request.id, request); + const sent = this.connections.sendTo(runnerId, { + type, + requestId: request.id, + path, + }); + if (!sent) { + this.end(request, { ok: false, ...OFFLINE }, OFFLINE.error); + } + }); + if (!outcome.ok) { + throw runError(outcome.status, outcome.error); + } + // `message` settles a request only with its own reply type. + return outcome.reply as Reply<R>; + } + + private end(request: Pending, outcome: Outcome, label: string): void { + this.pending.delete(request.id); + // No path, no folder name: the machine's layout stays off the logs. + this.logger.log( + JSON.stringify({ + event: request.type, + runnerId: request.runnerId, + outcome: label, + durationMs: this.now() - request.sentAt, + }), + ); + request.settle(outcome); + } + + private now(): number { + return this.clock.now().getTime(); + } +} + +/** A URL the API would not accept from the browser is dropped, not passed on. */ +function toInspectionView(inspection: FolderInspection): InspectionView { + const { githubUrl } = inspection; + return { + rootPath: inspection.rootPath, + name: inspection.name, + hasConfig: inspection.hasConfig, + configValid: inspection.configValid, + scenarios: inspection.scenarios.map(({ id, name }) => ({ id, name })), + githubUrl: + githubUrl !== undefined && GITHUB_URL_PATTERN.test(githubUrl) + ? githubUrl + : null, + }; +} + +/** The canonical root's base name, as the inspection names it; Windows paths too. */ +export function folderName(rootPath: string): string { + const name = /^[A-Za-z]:[\\/]|^\\\\/.test(rootPath) + ? win32.basename(rootPath) + : posix.basename(rootPath); + return (name || rootPath).slice(0, PROJECT_NAME_MAX); +} diff --git a/apps/api/src/projects/projects.module.ts b/apps/api/src/projects/projects.module.ts index 67c7be2c..a1b928c8 100644 --- a/apps/api/src/projects/projects.module.ts +++ b/apps/api/src/projects/projects.module.ts @@ -2,6 +2,8 @@ import { Module } from '@nestjs/common'; import { AuthModule } from '../auth/auth.module'; import { RunnerModule } from '../runner/runner.module'; import { ShareStorageModule } from '../shares/share-storage'; +import { FoldersController } from './folders/folders.controller'; +import { FoldersService } from './folders/folders.service'; import { ProjectsController } from './projects.controller'; import { ProjectsService } from './projects.service'; import { RunnerRunsController } from './runner-runs.controller'; @@ -9,7 +11,8 @@ import { RunnerRunsController } from './runner-runs.controller'; /** Projects and the demo library (spec #178): metadata only, never video. */ @Module({ imports: [AuthModule, RunnerModule, ShareStorageModule], - controllers: [ProjectsController, RunnerRunsController], - providers: [ProjectsService], + // `projects/folders/*` before `projects/:id/*`. + controllers: [FoldersController, ProjectsController, RunnerRunsController], + providers: [ProjectsService, FoldersService], }) export class ProjectsModule {} diff --git a/apps/api/src/runner/runner-connections.service.ts b/apps/api/src/runner/runner-connections.service.ts index 387964fc..f0e66df2 100644 --- a/apps/api/src/runner/runner-connections.service.ts +++ b/apps/api/src/runner/runner-connections.service.ts @@ -23,6 +23,7 @@ import { LAST_SEEN_WRITE_INTERVAL_MS, type LaunchMessage, PING_INTERVAL_MS, + type ProjectMessage, parseClientMessage, RUN_OPTIONS, type RunOption, @@ -56,6 +57,8 @@ interface Connection { features: Feature[]; /** A `share.*` answer for no pending request was logged on this socket. */ warnedStrayShare: boolean; + /** A `project.*` answer for no pending request was logged on this socket. */ + warnedStrayProject: boolean; } /** @@ -101,6 +104,16 @@ export interface ShareSink { closed(runnerId: string): void; } +/** + * Where folder requests (spec #378) hear from the sockets. `message` answers + * false for a request it does not hold. + */ +export interface ProjectSink { + message(runnerId: string, message: ProjectMessage): boolean; + /** The machine's socket is gone: closed, replaced, revoked or shut down. */ + closed(runnerId: string): void; +} + /** * The open runner sockets of this API instance (one today, #120): online is * "has an entry here", never a column. One socket per machine — a second one @@ -119,6 +132,7 @@ export class RunnerConnections private artifactsSink: ArtifactsSink | undefined; private launchSink: LaunchSink | undefined; private shareSink: ShareSink | undefined; + private projectSink: ProjectSink | undefined; constructor( private readonly prisma: PrismaService, @@ -207,6 +221,11 @@ export class RunnerConnections this.shareSink = sink; } + /** Folder requests' hook (spec #378). One sink per instance. */ + setProjectSink(sink: ProjectSink): void { + this.projectSink = sink; + } + /** An authenticated socket, straight after the upgrade. */ async accept( socket: WebSocket, @@ -226,6 +245,7 @@ export class RunnerConnections runOptions: [], features: [], warnedStrayShare: false, + warnedStrayProject: false, }; // Listeners first: a frame that arrives during the writes below counts. socket.on('message', (data, isBinary) => @@ -403,6 +423,12 @@ export class RunnerConnections case 'share.error': this.relayShare(connection, message); return; + case 'project.inspected': + case 'project.initialised': + case 'project.registered': + case 'project.error': + this.relayProject(connection, message); + return; } } @@ -432,6 +458,19 @@ export class RunnerConnections } } + /** As `relayArtifacts`, with its own once-per-socket warning. */ + private relayProject(connection: Connection, message: ProjectMessage): void { + if (this.projectSink?.message(connection.runnerId, message)) { + return; + } + if (!connection.warnedStrayProject) { + connection.warnedStrayProject = true; + this.logger.warn( + `Dropped ${message.type} from runner ${connection.runnerId} for a request that is not pending`, + ); + } + } + /** * An answer for no pending request — a late one after a timeout, or a * skewed daemon — is dropped, logged once per socket, and the socket stays. @@ -456,6 +495,7 @@ export class RunnerConnections this.artifactsSink?.closed(runnerId); this.launchSink?.closed(runnerId); this.shareSink?.closed(runnerId); + this.projectSink?.closed(runnerId); } private touch(connection: Connection): void { diff --git a/apps/api/src/runner/runner-socket.fixtures.ts b/apps/api/src/runner/runner-socket.fixtures.ts index c0f9dcac..e7b7e1c7 100644 --- a/apps/api/src/runner/runner-socket.fixtures.ts +++ b/apps/api/src/runner/runner-socket.fixtures.ts @@ -32,6 +32,12 @@ export interface SharePrepare extends Received { format: string; } +/** `project.inspect`, `project.init` or `project.register` (spec #378). */ +export interface ProjectRequest extends Received { + requestId: string; + path: string; +} + export interface Closed { code: number; reason: string; @@ -155,6 +161,17 @@ export class TestSocket { return ask as SharePrepare; } + /** The next `project.*` request (spec #378), with its request id and path. */ + async nextProject( + type: 'project.inspect' | 'project.init' | 'project.register', + ): Promise<ProjectRequest> { + const ask = await this.next(type); + if (typeof ask.requestId !== 'string' || typeof ask.path !== 'string') { + throw new Error(`${type} carries no requestId or path`); + } + return ask as ProjectRequest; + } + /** * `launches.sync` (spec #284): the launch ids this daemon still runs, and * the `run.start` options it accepts (spec #325) — none sent when omitted. diff --git a/apps/api/src/runner/runner-socket.spec.ts b/apps/api/src/runner/runner-socket.spec.ts index 56323aed..b7e83062 100644 --- a/apps/api/src/runner/runner-socket.spec.ts +++ b/apps/api/src/runner/runner-socket.spec.ts @@ -364,3 +364,86 @@ describe('launches.sync (spec #284)', () => { }); }); }); + +describe('project messages (spec #378)', () => { + const requestId = randomUUID(); + const inspection = { + rootPath: '/home/u/app', + name: 'app', + hasConfig: true, + configValid: true, + scenarios: [{ id: 'demoflow/checkout.demo.json', name: 'Checkout' }], + githubUrl: 'https://github.com/acme/app', + }; + + function parse(message: unknown) { + return parseClientMessage(Buffer.from(JSON.stringify(message)), false); + } + + it('reads the four replies', () => { + for (const message of [ + { type: 'project.inspected', requestId, inspection }, + { + type: 'project.inspected', + requestId, + inspection: { ...inspection, githubUrl: undefined, scenarios: [] }, + }, + { + type: 'project.initialised', + requestId, + created: ['demoflow.config.json'], + kept: [], + inspection, + }, + { type: 'project.registered', requestId, rootPath: '/home/u/app' }, + { type: 'project.error', requestId, code: 'path-not-allowed' }, + { type: 'project.error', requestId, code: 'a-code-from-a-newer-cli' }, + ]) { + expect(parse(message)).toEqual({ + ok: true, + message: expect.objectContaining(message), + }); + } + }); + + it.each([ + [ + 'an inspection without a request id', + { type: 'project.inspected', inspection }, + ], + ['a missing inspection', { type: 'project.inspected', requestId }], + [ + 'a non-boolean hasConfig', + { + type: 'project.inspected', + requestId, + inspection: { ...inspection, hasConfig: 'yes' }, + }, + ], + [ + 'a scenario without a name', + { + type: 'project.inspected', + requestId, + inspection: { ...inspection, scenarios: [{ id: 'x' }] }, + }, + ], + [ + 'an empty created file', + { + type: 'project.initialised', + requestId, + created: [''], + kept: [], + inspection, + }, + ], + [ + 'an empty rootPath', + { type: 'project.registered', requestId, rootPath: '' }, + ], + ['an error without a code', { type: 'project.error', requestId }], + ])('refuses %s', (_label, message) => { + expect(parse(message).ok).toBe(false); + }); +}); diff --git a/apps/api/src/runner/runner-socket.ts b/apps/api/src/runner/runner-socket.ts index d5b1fcf6..8ae48957 100644 --- a/apps/api/src/runner/runner-socket.ts +++ b/apps/api/src/runner/runner-socket.ts @@ -11,6 +11,7 @@ import { IsBoolean, IsIn, IsInt, + IsObject, IsOptional, IsString, IsUUID, @@ -24,7 +25,7 @@ import { } from 'class-validator'; import type { RawData } from 'ws'; import { IsScenarioId } from '../launches/scenario-id'; -import type { RunFormat } from '../projects/projects.dto'; +import { PATH_MAX, type RunFormat } from '../projects/projects.dto'; import type { RunnerContext } from './runner-token'; /** @@ -91,7 +92,12 @@ export type ServerMessage = options?: RunStartOptions; } | { type: 'run.cancel'; requestId: string } - | { type: 'share.prepare'; requestId: string; runId: string; format: string }; + | { type: 'share.prepare'; requestId: string; runId: string; format: string } + | { + type: 'project.inspect' | 'project.init' | 'project.register'; + requestId: string; + path: string; + }; /** What `video.open` may ask for besides the render itself (spec #347). */ export type VideoAsset = 'poster'; @@ -109,7 +115,8 @@ export type ClientMessage = | VideoMessage | ArtifactsMessage | LaunchMessage - | ShareMessage; + | ShareMessage + | ProjectMessage; export type VideoMessage = | VideoHeadMessage @@ -139,6 +146,18 @@ export type LaunchMessage = /** A Runner's answer to `share.prepare` (spec #347, Decision 4). */ export type ShareMessage = SharePreparedMessage | ShareErrorMessage; +/** A Runner's answers to `project.*` (spec #377, Decision 4; spec #378). */ +export type ProjectMessage = + | ProjectInspectedMessage + | ProjectInitialisedMessage + | ProjectRegisteredMessage + | ProjectErrorMessage; + +/** A file name `project.initialised` lists, relative to the folder. */ +const INIT_FILE_MAX = 512; +/** `demoflow init` writes two files; room for a newer template. */ +const MAX_INIT_FILES = 16; + /** `share.prepared` limits (Decision 4). */ export const SHARE_DESCRIPTION_MAX = 2000; export const SHARE_CHAPTERS_MAX = 100; @@ -169,9 +188,10 @@ export const MAX_RUN_OPTIONS = 8; export const RUN_OPTION_MAX_LENGTH = 32; /** * The capabilities this API knows a daemon may announce (ADR-0019 §7): `share` - * answers `share.prepare` and `video.open` with an `asset`. + * answers `share.prepare` and `video.open` with an `asset`; `projects` answers + * `project.*` (ADR-0022 §6). */ -export const FEATURES = ['share'] as const; +export const FEATURES = ['share', 'projects'] as const; export type Feature = (typeof FEATURES)[number]; /** `launches.sync` announces this many features at most, each this long at most. */ export const MAX_FEATURES = 8; @@ -487,6 +507,109 @@ class ShareErrorMessage { code!: string; } +/** + * What a Runner says about a folder (spec #377, Decision 5): never a file's + * contents nor a config value. `githubUrl` is any string here; the API keeps + * it only when it is a plain `https://github.com/<owner>/<repo>`. + */ +export class FolderInspection { + /** Canonical: the folder's real path. */ + @IsString() + @Length(1, PATH_MAX) + rootPath!: string; + + /** The folder's base name. */ + @IsString() + @MaxLength(PATH_MAX) + name!: string; + + @IsBoolean() + hasConfig!: boolean; + + @IsBoolean() + configValid!: boolean; + + @IsArray() + @ArrayMaxSize(MAX_LISTED_SCENARIOS) + @ValidateNested({ each: true }) + @Type(() => ListedScenario) + scenarios!: ListedScenario[]; + + @IsOptional() + @IsString() + @MaxLength(PATH_MAX) + githubUrl?: string; +} + +class ProjectInspectedMessage { + @IsIn(['project.inspected']) + type!: 'project.inspected'; + + @IsUUID('4') + requestId!: string; + + @IsObject() + @ValidateNested() + @Type(() => FolderInspection) + inspection!: FolderInspection; +} + +/** `demoflow init`'s files: those written now, and those already there. */ +class ProjectInitialisedMessage { + @IsIn(['project.initialised']) + type!: 'project.initialised'; + + @IsUUID('4') + requestId!: string; + + @IsArray() + @ArrayMaxSize(MAX_INIT_FILES) + @IsString({ each: true }) + @Length(1, INIT_FILE_MAX, { each: true }) + created!: string[]; + + @IsArray() + @ArrayMaxSize(MAX_INIT_FILES) + @IsString({ each: true }) + @Length(1, INIT_FILE_MAX, { each: true }) + kept!: string[]; + + @IsObject() + @ValidateNested() + @Type(() => FolderInspection) + inspection!: FolderInspection; +} + +/** The folder is in the machine's registry; `rootPath` is its canonical path. */ +class ProjectRegisteredMessage { + @IsIn(['project.registered']) + type!: 'project.registered'; + + @IsUUID('4') + requestId!: string; + + @IsString() + @Length(1, PATH_MAX) + rootPath!: string; +} + +/** + * `path-not-allowed`, `config-missing`, `config-invalid`, `busy` or + * `internal`. Any string, so a code a newer daemon adds still ends the + * request instead of being dropped; the API maps it to `runner-error`. + */ +class ProjectErrorMessage { + @IsIn(['project.error']) + type!: 'project.error'; + + @IsUUID('4') + requestId!: string; + + @IsString() + @MaxLength(64) + code!: string; +} + const CLIENT_MESSAGES: Record< ClientMessage['type'], ClassConstructor<ClientMessage> @@ -509,6 +632,10 @@ const CLIENT_MESSAGES: Record< 'launches.sync': LaunchesSyncMessage, 'share.prepared': SharePreparedMessage, 'share.error': ShareErrorMessage, + 'project.inspected': ProjectInspectedMessage, + 'project.initialised': ProjectInitialisedMessage, + 'project.registered': ProjectRegisteredMessage, + 'project.error': ProjectErrorMessage, }; /** A binary frame: part of a stream's file, in order. */ diff --git a/apps/api/src/runner/runners.integration.spec.ts b/apps/api/src/runner/runners.integration.spec.ts index aa394a8f..34d2b0e8 100644 --- a/apps/api/src/runner/runners.integration.spec.ts +++ b/apps/api/src/runner/runners.integration.spec.ts @@ -59,6 +59,7 @@ describe('runners (integration)', () => { createdAt: expect.any(String), lastUsedAt: null, online: false, + features: [], lastSeenAt: null, lastSeenIp: null, }, diff --git a/apps/api/src/runner/runners.service.ts b/apps/api/src/runner/runners.service.ts index 751fc1f4..96102bcf 100644 --- a/apps/api/src/runner/runners.service.ts +++ b/apps/api/src/runner/runners.service.ts @@ -3,7 +3,7 @@ import type { Runner } from '@prisma/client'; import { Clock } from '../common/clock'; import { PrismaService } from '../database/prisma.service'; import { RunnerConnections } from './runner-connections.service'; -import { CLOSE_REVOKED } from './runner-socket'; +import { CLOSE_REVOKED, type Feature } from './runner-socket'; /** A machine as the API returns it: never its token hash. */ export interface RunnerView { @@ -15,11 +15,17 @@ export interface RunnerView { lastUsedAt: Date | null; /** Has an open socket on this API right now (spec #151). */ online: boolean; + /** What its current socket can do (spec #378: `projects`); none offline. */ + features: Feature[]; lastSeenAt: Date | null; lastSeenIp: string | null; } -export function toRunnerView(runner: Runner, online: boolean): RunnerView { +export function toRunnerView( + runner: Runner, + online: boolean, + features: readonly Feature[], +): RunnerView { return { id: runner.id, name: runner.name, @@ -28,6 +34,7 @@ export function toRunnerView(runner: Runner, online: boolean): RunnerView { createdAt: runner.createdAt, lastUsedAt: runner.lastUsedAt, online, + features: [...features], lastSeenAt: runner.lastSeenAt, lastSeenIp: runner.lastSeenIp, }; @@ -95,6 +102,10 @@ export class RunnersService { } private view(runner: Runner): RunnerView { - return toRunnerView(runner, this.connections.isOnline(runner.id)); + return toRunnerView( + runner, + this.connections.isOnline(runner.id), + this.connections.features(runner.id), + ); } } From 1a1f08b5d7fc7c307d33d63b99f6a1cd6a1f80af Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 18:13:59 +0100 Subject: [PATCH 51/71] test(cli): scheduler, local mode, runner status schedules and run root recording (spec 361) --- apps/cli/test/commands/check-run.spec.ts | 36 +- apps/cli/test/runner/fakes.ts | 7 +- apps/cli/test/runner/schedule-daemon.spec.ts | 211 ++++++++++ apps/cli/test/runner/schedule.spec.ts | 417 +++++++++++++++++++ 4 files changed, 659 insertions(+), 12 deletions(-) create mode 100644 apps/cli/test/runner/schedule-daemon.spec.ts create mode 100644 apps/cli/test/runner/schedule.spec.ts diff --git a/apps/cli/test/commands/check-run.spec.ts b/apps/cli/test/commands/check-run.spec.ts index f588253f..a132d82d 100644 --- a/apps/cli/test/commands/check-run.spec.ts +++ b/apps/cli/test/commands/check-run.spec.ts @@ -1,4 +1,4 @@ -import { existsSync, readdirSync, readFileSync } from 'node:fs'; +import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'; import { cp, mkdtemp, rm, writeFile } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import path from 'node:path'; @@ -18,6 +18,9 @@ import { type RunFlags, runCommand, } from '../../src/commands/run.ts'; +import type { HostEnvironment } from '../../src/config/platform.ts'; +import { runnerPaths } from '../../src/runner/paths.ts'; +import { readLocalRoots } from '../../src/runner/schedule/local-roots.ts'; const REPO = path.resolve( path.dirname(fileURLToPath(import.meta.url)), @@ -61,18 +64,19 @@ async function harness(start?: RunDeps['startApp']) { let starts = 0; let stops = 0; let runs = 0; + const host: HostEnvironment = { + platform: process.platform, + env: { + DEMOFLOW_HOME: home, + DEMOFLOW_NO_REPORT: '1', + // landing, login and phone sign in; any password does. + FIXTURE_PASSWORD: 'correct horse', + }, + homedir: path.join(home, 'user'), + }; const run = (file: string | undefined, flags: RunFlags) => runCommand(file, flags, io, { - host: { - platform: process.platform, - env: { - DEMOFLOW_HOME: home, - DEMOFLOW_NO_REPORT: '1', - // landing, login and phone sign in; any password does. - FIXTURE_PASSWORD: 'correct horse', - }, - homedir: path.join(home, 'user'), - }, + host, cwd: project, runId: () => `check-${++runs}`, startApp: async (...args) => { @@ -90,6 +94,7 @@ async function harness(start?: RunDeps['startApp']) { io, run, home, + host, runsDir: path.join(home, 'runs'), counts: () => ({ starts, stops }), }; @@ -137,6 +142,15 @@ describe('demoflow run --check', () => { ); }); + it('records the project root for the runner to watch, once (spec 361)', async () => { + const { run, host } = await harness(); + await run(scenario('customers'), { check: true }); + await run(scenario('customers'), { check: true }); + expect(readLocalRoots(runnerPaths(host).localRoots)).toEqual([ + realpathSync.native(project), + ]); + }); + it('fails the check of a failing scenario: exit 1, verification failed', async () => { const { io, run, runsDir } = await harness(); const code = await run(scenario('failing'), { check: true, json: true }); diff --git a/apps/cli/test/runner/fakes.ts b/apps/cli/test/runner/fakes.ts index dc20cf67..b81ee70d 100644 --- a/apps/cli/test/runner/fakes.ts +++ b/apps/cli/test/runner/fakes.ts @@ -8,9 +8,14 @@ import type { Logger, LogLevel } from '../../src/runner/log.ts'; /** Timers that only fire when the test advances time. */ export class FakeClock implements Clock { - private time = 0; + private time: number; private timers: Array<{ at: number; run: () => void; live: boolean }> = []; + /** `start` is the epoch time `now()` begins at; a schedule needs a real date. */ + constructor(start = 0) { + this.time = start; + } + now(): number { return this.time; } diff --git a/apps/cli/test/runner/schedule-daemon.spec.ts b/apps/cli/test/runner/schedule-daemon.spec.ts new file mode 100644 index 00000000..68380711 --- /dev/null +++ b/apps/cli/test/runner/schedule-daemon.spec.ts @@ -0,0 +1,211 @@ +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import type { Io } from '../../src/commands/io.ts'; +import type { HostEnvironment } from '../../src/config/platform.ts'; +import type { ChildExit, RunChild, SpawnRun } from '../../src/mcp/child.ts'; +import { + type ControlDeps, + defaultControlDeps, + runnerStatus, + statusCommand, +} from '../../src/runner/control.ts'; +import { + EXIT_DAEMON_DONE, + EXIT_DAEMON_NOT_LOGGED_IN, + runForeground, +} from '../../src/runner/daemon.ts'; +import { runnerPaths } from '../../src/runner/paths.ts'; +import { recordLocalRoot } from '../../src/runner/schedule/local-roots.ts'; +import { writeScheduleState } from '../../src/runner/schedule/state.ts'; +import { readState } from '../../src/runner/state.ts'; +import { FakeClock } from './fakes.ts'; + +const T0 = Date.parse('2026-10-26T08:00:00.000Z'); +const DAY = 86_400_000; + +let tmp: string; +let host: HostEnvironment; +let root: string; +let out: string; +let err: string; +let spawned: Array<{ args: string[]; killed: number }>; + +const io: Io = { + stdout: (text) => { + out += text; + }, + stderr: (text) => { + err += text; + }, +}; + +const spawn: SpawnRun = (args) => { + let resolve: (exit: ChildExit) => void = () => {}; + const exited = new Promise<ChildExit>((r) => { + resolve = r; + }); + const call = { args, killed: 0 }; + spawned.push(call); + const child: RunChild = { + pid: 4242, + exited, + kill: async () => { + call.killed++; + resolve({ code: null, stderrTail: '' }); + await exited; + }, + }; + return child; +}; + +beforeEach(() => { + tmp = mkdtempSync(path.join(tmpdir(), 'demoflow-schedule-daemon-')); + const env = { + ...process.env, + HOME: tmp, + USERPROFILE: tmp, + XDG_CONFIG_HOME: path.join(tmp, '.config'), + APPDATA: path.join(tmp, 'AppData', 'Roaming'), + }; + host = { platform: process.platform, env, homedir: tmp }; + root = path.join(tmp, 'shop'); + mkdirSync(root); + out = ''; + err = ''; + spawned = []; +}); +afterEach(() => { + rmSync(tmp, { recursive: true, force: true }); +}); + +function scheduledProject(): void { + writeFileSync( + path.join(root, 'demoflow.config.json'), + JSON.stringify({ + baseUrl: 'http://localhost:1', + schedule: { cadence: 'daily', at: '09:00' }, + }), + ); + const paths = runnerPaths(host); + mkdirSync(paths.dir, { recursive: true }); + recordLocalRoot(paths.localRoots, root); +} + +function control(overrides: Partial<ControlDeps> = {}): ControlDeps { + return { ...defaultControlDeps(), host, ...overrides }; +} + +function daemon(connects: string[]) { + return runForeground(io, { + host, + pid: process.pid, + connect: (url) => { + connects.push(url); + throw new Error('no socket in local mode'); + }, + clock: new FakeClock(T0), + random: () => 0.5, + fetch: () => Promise.reject(new Error('no network in local mode')), + spawn, + zone: () => 'UTC', + }); +} + +describe('the daemon without an account', () => { + it('exits as before when no watched root has a schedule', async () => { + writeFileSync( + path.join(root, 'demoflow.config.json'), + '{"baseUrl":"http://localhost:1"}', + ); + recordLocalRoot(runnerPaths(host).localRoots, root); + expect(await daemon([])).toBe(EXIT_DAEMON_NOT_LOGGED_IN); + expect(err).toContain('demoflow login'); + }); + + it('runs in local mode: no socket, the due pass runs, status names the mode', async () => { + scheduledProject(); + const paths = runnerPaths(host); + writeScheduleState(paths.scheduleState, { + zone: 'UTC', + roots: { + [root]: { + schedule: { cadence: 'daily', at: '09:00' }, + seenAt: new Date(T0 - 10 * DAY).toISOString(), + last: { startedAt: new Date(T0 - 3 * DAY).toISOString() }, + }, + }, + }); + const connects: string[] = []; + const done = daemon(connects); + await vi.waitFor(() => expect(spawned).toHaveLength(1)); + expect(spawned[0]?.args.slice(0, 2)).toEqual(['run', '--check']); + const state = readState(paths.state); + expect(state?.state).toBe('local'); + expect(state?.server).toBeUndefined(); + + const status = runnerStatus(control()); + expect(status.connection).toBe('local'); + expect(status.schedules).toEqual([ + expect.objectContaining({ + rootPath: root, + zone: 'UTC', + lastCheck: { startedAt: '2026-10-26T08:00:00.000Z' }, + }), + ]); + expect(status.schedules[0]?.nextCheckAt).not.toBeNull(); + statusCommand({}, io, control()); + expect(out).toContain('Connection: local mode: scheduled checks only'); + expect(out).toContain(`Schedule: ${root} (daily at 09:00)`); + expect(out).toContain('last check: 2026-10-26 08:00, no result yet'); + + writeFileSync(paths.stop, `${process.pid}\n`); + expect(await done).toBe(EXIT_DAEMON_DONE); + expect(connects).toEqual([]); + expect(spawned[0]?.killed).toBe(1); + }); +}); + +describe('runner status and schedules', () => { + it('shows the last check and says the next waits for the runner', () => { + const paths = runnerPaths(host); + mkdirSync(paths.dir, { recursive: true }); + writeScheduleState(paths.scheduleState, { + zone: 'Europe/Berlin', + roots: { + [root]: { + schedule: { + cadence: 'weekly', + weekday: 'mon', + at: '09:30', + exclude: ['demoflow/wip.demo.json'], + }, + last: { + startedAt: '2026-10-26T08:30:00.000Z', + finishedAt: '2026-10-26T08:41:00.000Z', + outcome: 'finished', + passed: 12, + failed: 1, + }, + }, + [path.join(tmp, 'gone')]: { + last: { startedAt: '2026-10-20T08:30:00.000Z' }, + }, + }, + }); + statusCommand({}, io, control()); + expect(out).toContain( + `Schedule: ${root} (weekly on mon at 09:30, 1 excluded)`, + ); + expect(out).toContain('next check: when the runner is running'); + expect(out).toContain('last check: 2026-10-26 09:30, 12 passed, 1 failed'); + expect(out).not.toContain('gone'); + out = ''; + statusCommand({ json: true }, io, control()); + const json = JSON.parse(out) as { schedules: unknown[] }; + expect(json.schedules).toEqual([ + expect.objectContaining({ rootPath: root, nextCheckAt: null }), + ]); + }); +}); diff --git a/apps/cli/test/runner/schedule.spec.ts b/apps/cli/test/runner/schedule.spec.ts new file mode 100644 index 00000000..b081c4d2 --- /dev/null +++ b/apps/cli/test/runner/schedule.spec.ts @@ -0,0 +1,417 @@ +import { + mkdirSync, + mkdtempSync, + readFileSync, + realpathSync, + rmSync, + writeFileSync, +} from 'node:fs'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import type { ScheduleConfig } from '@demoflow/core'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import type { + ChildExit, + RunChild, + SpawnRun, + SpawnRunOptions, +} from '../../src/mcp/child.ts'; +import { nodeLaunchFs } from '../../src/runner/launch/checks.ts'; +import { Launcher } from '../../src/runner/launch/index.ts'; +import { + LOCAL_ROOTS_KEEP, + readLocalRoots, + recordLocalRoot, +} from '../../src/runner/schedule/local-roots.ts'; +import { + Scheduler, + type SchedulerDeps, + type SchedulesSync, +} from '../../src/runner/schedule/scheduler.ts'; +import { + readScheduleState, + writeScheduleState, +} from '../../src/runner/schedule/state.ts'; +import { appendReportedRun } from '../../src/runs-report/reported-runs.ts'; +import { FakeClock, memoryLogger } from './fakes.ts'; + +const MINUTE = 60_000; +const HOUR = 60 * MINUTE; +const DAY = 24 * HOUR; +/** A Monday, an hour before the 09:00 slot. */ +const T0 = Date.parse('2026-10-26T08:00:00.000Z'); +const DAILY: ScheduleConfig = { cadence: 'daily', at: '09:00' }; +const REQUEST = '6f1c2b8e-3d4a-4b5c-9e7f-0a1b2c3d4e5f'; + +interface Spawned { + args: string[]; + cwd: string; + options: SpawnRunOptions | undefined; + killed: number; + exit(code?: number | null): void; + print(...lines: string[]): void; +} + +function fakeSpawn(): { spawn: SpawnRun; calls: Spawned[] } { + const calls: Spawned[] = []; + const spawn: SpawnRun = (args, cwd, options) => { + let resolve: (exit: ChildExit) => void = () => {}; + const exited = new Promise<ChildExit>((r) => { + resolve = r; + }); + const child: RunChild = { + pid: 4242, + exited, + kill: async () => { + call.killed++; + resolve({ code: null, stderrTail: '' }); + await exited; + }, + }; + const call: Spawned = { + args, + cwd, + options, + killed: 0, + exit: (code = 0) => resolve({ code, stderrTail: '' }), + print: (...lines) => { + for (const line of lines) options?.onStdoutLine?.(line); + }, + }; + calls.push(call); + return child; + }; + return { spawn, calls }; +} + +let tmp: string; +let root: string; +let stateFile: string; +let clock: FakeClock; +let logger: ReturnType<typeof memoryLogger>; +let spawned: ReturnType<typeof fakeSpawn>; +let schedules: Map<string, ScheduleConfig | Error>; +let reported: string[]; +let local: string[]; +let frames: SchedulesSync[]; +let running: Scheduler[]; + +beforeEach(() => { + tmp = realpathSync.native( + mkdtempSync(path.join(tmpdir(), 'demoflow-schedule-')), + ); + root = path.join(tmp, 'shop'); + mkdirSync(root); + stateFile = path.join(tmp, 'schedule.state.json'); + clock = new FakeClock(T0); + logger = memoryLogger(); + spawned = fakeSpawn(); + schedules = new Map([[root, DAILY]]); + reported = []; + local = [root]; + frames = []; + running = []; +}); +afterEach(async () => { + for (const scheduler of running) await scheduler.stop(); + rmSync(tmp, { recursive: true, force: true }); +}); + +function scheduler(overrides: Partial<SchedulerDeps> = {}): Scheduler { + const created = new Scheduler({ + clock, + logger, + zone: () => 'UTC', + roots: () => ({ reported, local }), + loadSchedule: (at) => { + const schedule = schedules.get(at); + if (schedule instanceof Error) throw schedule; + return schedule; + }, + stateFile, + spawn: spawned.spawn, + claim: () => () => {}, + onSchedules: (frame) => frames.push(frame), + ...overrides, + }); + running.push(created); + return created; +} + +const totals = (passed: number, failed: number) => + JSON.stringify({ check: true, passed, failed }); + +describe('the scheduler', () => { + it('spawns exactly one check pass when the slot passes while it runs', async () => { + scheduler().start(); + expect(spawned.calls).toHaveLength(0); + await clock.advance(HOUR - 1); + expect(spawned.calls).toHaveLength(0); + await clock.advance(1); + expect(spawned.calls).toHaveLength(1); + const [pass] = spawned.calls; + expect(pass?.args).toEqual([ + 'run', + '--check', + '--json', + '--progress', + '--project', + root, + ]); + expect(pass?.cwd).toBe(root); + // Written before the spawn: a crash now does not repeat the slot. + expect(readScheduleState(stateFile)?.roots[root]?.last).toEqual({ + startedAt: '2026-10-26T09:00:00.000Z', + }); + await clock.advance(10 * MINUTE); + expect(spawned.calls).toHaveLength(1); + pass?.print(totals(3, 1)); + pass?.exit(0); + await clock.advance(22 * HOUR); + expect(spawned.calls).toHaveLength(1); + expect(readScheduleState(stateFile)?.roots[root]?.last).toEqual({ + startedAt: '2026-10-26T09:00:00.000Z', + finishedAt: '2026-10-26T09:10:00.000Z', + outcome: 'finished', + passed: 3, + failed: 1, + }); + expect(logger.text()).toContain('shop: finished, 3 passed, 1 failed'); + expect(logger.text()).not.toContain(tmp); + }); + + it('runs one catch-up pass, not three, three days after the last one', async () => { + writeScheduleState(stateFile, { + zone: 'UTC', + roots: { + [root]: { + schedule: DAILY, + seenAt: new Date(T0 - 10 * DAY).toISOString(), + last: { startedAt: new Date(T0 - 3 * DAY + HOUR).toISOString() }, + }, + }, + }); + scheduler().start(); + expect(spawned.calls).toHaveLength(1); + spawned.calls[0]?.exit(0); + await clock.advance(50 * MINUTE); + expect(spawned.calls).toHaveLength(1); + }); + + it('does not fire for a slot before it first saw the schedule', async () => { + clock = new FakeClock(T0 + 3 * HOUR); + scheduler().start(); + await clock.advance(MINUTE); + expect(spawned.calls).toHaveLength(0); + expect(readScheduleState(stateFile)?.roots[root]?.seenAt).toBe( + '2026-10-26T11:00:00.000Z', + ); + }); + + it('passes the excluded scenario ids', async () => { + schedules.set(root, { + ...DAILY, + exclude: ['demoflow/wip.demo.json', 'demoflow/a/b.demo.json'], + }); + scheduler().start(); + await clock.advance(HOUR); + expect(spawned.calls[0]?.args.slice(6)).toEqual([ + '--exclude', + 'demoflow/wip.demo.json', + '--exclude', + 'demoflow/a/b.demo.json', + ]); + }); + + it('runs one pass at a time', async () => { + const other = path.join(tmp, 'blog'); + schedules.set(other, DAILY); + local = [root, other]; + scheduler().start(); + await clock.advance(HOUR); + expect(spawned.calls).toHaveLength(1); + spawned.calls[0]?.exit(0); + await clock.advance(1); + expect(spawned.calls).toHaveLength(2); + expect(new Set(spawned.calls.map((call) => call.cwd))).toEqual( + new Set([root, other]), + ); + }); + + it('kills a pass that outlives the pass cap and records it timed-out', async () => { + scheduler().start(); + await clock.advance(HOUR); + await clock.advance(2 * HOUR); + expect(spawned.calls[0]?.killed).toBe(1); + expect(readScheduleState(stateFile)?.roots[root]?.last?.outcome).toBe( + 'timed-out', + ); + }); + + it('kills the running pass on stop', async () => { + const created = scheduler(); + created.start(); + await clock.advance(HOUR); + await created.stop(); + expect(spawned.calls[0]?.killed).toBe(1); + expect(readScheduleState(stateFile)?.roots[root]?.last?.outcome).toBe( + 'cancelled', + ); + }); + + it('skips a root whose config does not load and logs it once', async () => { + schedules.set(root, new Error(`${root}/demoflow.config.json is invalid`)); + scheduler().start(); + await clock.advance(2 * HOUR); + expect(spawned.calls).toHaveLength(0); + const warnings = logger.lines.filter((line) => + line.message.includes('does not load'), + ); + expect(warnings).toHaveLength(1); + expect(logger.text()).not.toContain(tmp); + }); + + it('forgets a removed schedule, so adding it back starts fresh', async () => { + const created = scheduler(); + created.start(); + schedules.delete(root); + await clock.advance(2 * HOUR); + expect(spawned.calls).toHaveLength(0); + expect(readScheduleState(stateFile)?.roots[root]).toBeUndefined(); + }); +}); + +describe('the scheduler and website launches', () => { + it('starts no pass while a launch runs, and starts it when the launch ends', async () => { + const indexFile = path.join(tmp, 'reported-runs.jsonl'); + writeFileSync( + path.join(root, 'demoflow.config.json'), + '{"baseUrl":"http://localhost:1"}', + ); + appendReportedRun(indexFile, { + id: 'srv-0', + runDir: path.join(tmp, 'home', 'runs', 'old'), + at: '2026-10-23T10:00:00.000Z', + root, + }); + const replies: Array<Record<string, unknown>> = []; + const reply = { + send: (message: Record<string, unknown>) => replies.push(message), + }; + let created: Scheduler | null = null; + const launcher = new Launcher({ + indexFile, + fs: nodeLaunchFs, + logger, + clock, + platform: process.platform, + env: {}, + spawn: spawned.spawn, + loadProject: () => ({ ok: true, home: path.join(tmp, 'home') }), + newRunId: () => 'local-1', + readStatus: async () => 'completed', + onIdle: () => created?.wake(), + }); + created = scheduler({ claim: () => launcher.claim() }); + created.start(); + await clock.advance(HOUR - 5 * MINUTE); + const check = { + type: 'check.start', + requestId: REQUEST, + rootPath: root, + exclude: [], + }; + launcher.handle(check, reply, reply); + // The launcher checks the root on disk before it spawns. + await vi.waitFor(() => expect(spawned.calls).toHaveLength(1)); + await clock.advance(10 * MINUTE); + // The slot passed at 09:00; the website's pass still holds the launch slot. + expect(spawned.calls).toHaveLength(1); + spawned.calls[0]?.print(totals(1, 0)); + spawned.calls[0]?.exit(0); + await clock.advance(1); + expect(spawned.calls).toHaveLength(2); + // And while the scheduled pass runs, the website is told `busy`. + launcher.handle( + { ...check, requestId: `${REQUEST.slice(0, -1)}0` }, + reply, + reply, + ); + expect(replies.at(-1)).toMatchObject({ type: 'check.error', code: 'busy' }); + expect(spawned.calls).toHaveLength(2); + spawned.calls[1]?.exit(0); + await clock.advance(1); + await launcher.close(); + }); +}); + +describe('schedules.sync', () => { + it('names only reported roots, with the schedule as parsed or null, and the zone', async () => { + const blog = path.join(tmp, 'blog'); + const docs = path.join(tmp, 'docs'); + reported = [root, blog]; + local = [docs]; + schedules.set(docs, DAILY); + const created = scheduler({ zone: () => 'Europe/Berlin' }); + created.start(); + const expected: SchedulesSync = { + type: 'schedules.sync', + zone: 'Europe/Berlin', + projects: [ + { rootPath: blog, schedule: null }, + { rootPath: root, schedule: DAILY }, + ], + }; + expect(frames).toEqual([expected]); + expect(created.schedules()).toEqual(expected); + // Unchanged on the next tick: nothing new is sent. + await clock.advance(MINUTE); + expect(frames).toHaveLength(1); + const weekly: ScheduleConfig = { + cadence: 'weekly', + weekday: 'fri', + at: '18:00', + }; + schedules.set(blog, weekly); + await clock.advance(MINUTE); + expect(frames).toHaveLength(2); + expect(frames[1]?.projects[0]).toEqual({ + rootPath: blog, + schedule: weekly, + }); + }); +}); + +describe('local-roots.jsonl', () => { + it('records each root once, oldest first', () => { + const file = path.join(tmp, 'runner', 'local-roots.jsonl'); + recordLocalRoot(file, '/a'); + recordLocalRoot(file, '/b'); + recordLocalRoot(file, '/a'); + expect(readLocalRoots(file)).toEqual(['/a', '/b']); + expect(readFileSync(file, 'utf8').trim().split('\n')).toHaveLength(2); + }); + + it(`keeps the last ${LOCAL_ROOTS_KEEP} roots`, () => { + const file = path.join(tmp, 'local-roots.jsonl'); + writeFileSync( + file, + Array.from( + { length: LOCAL_ROOTS_KEEP }, + (_, i) => `${JSON.stringify({ root: `/r${i}` })}\n`, + ).join(''), + ); + recordLocalRoot(file, '/new'); + const roots = readLocalRoots(file); + expect(roots).toHaveLength(LOCAL_ROOTS_KEEP); + expect(roots[0]).toBe('/r1'); + expect(roots.at(-1)).toBe('/new'); + }); + + it('skips malformed lines and never throws on a missing file', () => { + const file = path.join(tmp, 'local-roots.jsonl'); + expect(readLocalRoots(file)).toEqual([]); + writeFileSync(file, 'nope\n{"root":""}\n{"root":"/a"}\n[1]\n'); + expect(readLocalRoots(file)).toEqual(['/a']); + }); +}); From 2dc0762326645670cf2b8ec620824c15c9ce9833 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 18:14:48 +0100 Subject: [PATCH 52/71] docs(cli): scheduled checks and local mode in the README (spec 361) --- apps/cli/README.md | 58 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 53 insertions(+), 5 deletions(-) diff --git a/apps/cli/README.md b/apps/cli/README.md index adfbe3f3..5e9b1b72 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -155,6 +155,50 @@ before anything runs. Each run is reported like any other, marked as a check. Unlike `demoflow check`, which only inspects files and tools, this opens the app. +### Scheduled checks + +`schedule` makes the runner (`demoflow runner start`) run `demoflow run --check` +over the whole project on its own, at a set time: + +```json +{ + "baseUrl": "http://localhost:3000", + "schedule": { + "cadence": "weekly", + "weekday": "mon", + "at": "09:30", + "exclude": ["demoflow/wip.demo.json"] + } +} +``` + +- `cadence` is `daily`, `weekdays` (Monday to Friday) or `weekly`; `weekly` + needs `weekday` (`mon` … `sun`), the others refuse it. +- `at` is `HH:MM`, 24-hour, in the time zone of the machine the runner runs on. + A time the clock skips when daylight saving starts runs at the next valid + minute; a time that repeats when it ends runs once, the first time. +- `exclude` lists scenario ids the pass leaves out (at most 100), as + `--exclude` does. +- The runner watches the projects it has reported runs for and the projects + `demoflow run` ran in on this machine. It reads each `schedule` every + minute, so an edit needs no restart. A project with a config that does not + load is skipped and named in `runner.log`. +- One pass at a time, and never next to a run started from the website: a + pass that comes due waits for it. A pass is stopped after 2 hours, or after + 15 minutes on one scenario. +- A machine that was off or asleep at the time runs one pass when the runner + next looks, however many it missed. A new schedule waits for its first time: + it does not run at once. +- The passes are reported like any other check run (off without + `demoflow login`, under `CI`, or with `DEMOFLOW_NO_REPORT=1`). + +Without `demoflow login`, `runner start` and `runner install` still work when a +watched project has a schedule. The runner then runs in local mode: no +connection, scheduled checks only. `runner status` shows each scheduled +project, its next check (while the runner runs) and the last one, with its +result. A schedule runs only while the runner does: use +[`demoflow runner install`](#start-at-login) so it starts at every login. + `demoflow init [--base-url <url>]` writes `demoflow.config.json` (default `baseUrl` `http://localhost:3000`) and `demoflow/first.demo.json`, a scenario that opens `/` and passes against any app at `baseUrl`, in the current folder. @@ -254,8 +298,9 @@ it was last seen. After `login` the CLI asks whether to start it the command). No jobs run over it yet. - `runner status` prints whether it runs (PID, uptime), the connection - (`connected`, `reconnecting in Ns`, `revoked`), the server and whether - autostart is installed. `--json` prints the same as one object. + (`connected`, `reconnecting in Ns`, `revoked`, or local mode), the server, + whether autostart is installed, and the next and last check of each + scheduled project. `--json` prints the same as one object. - `runner logs` prints `runner.log`; `--follow` keeps printing. - `runner stop` stops it; `logout` stops it first. - One runner per machine. A second `start` prints the running PID. @@ -263,8 +308,10 @@ the command). No jobs run over it yet. and exits for good when the machine is revoked on the website. - Every 30 days the server rotates the token over the connection; the runner rewrites `credentials.json`. -- `runner.log` (rotated at 5 MB, three files kept), `runner.lock` and - `runner.state.json` sit next to `credentials.json`. None holds the token. +- `runner.log` (rotated at 5 MB, three files kept), `runner.lock`, + `runner.state.json`, `schedule.state.json` (each scheduled project's last + pass) and `local-roots.jsonl` (the projects `demoflow run` ran in, the last + 500) sit next to `credentials.json`. None holds the token. ### Start at login @@ -273,7 +320,8 @@ npx demoflow runner install ``` Registers the runner for your user, with no admin rights, and starts it now. -It needs `demoflow login` first. The unit runs the same `node` and CLI that +It needs `demoflow login` first, unless a watched project has a `schedule` +(local mode, see [Scheduled checks](#scheduled-checks)). The unit runs the same `node` and CLI that ran `install`, by absolute path; if you move or upgrade the CLI, run `install` again. `runner uninstall` removes it; a running runner keeps running until `runner stop`. From b5330ddf708464901a9f4784835dc9a5879c22dc Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 19:19:56 +0100 Subject: [PATCH 53/71] feat(core): chapters on renders and the share.allowMcp project config A render carries its scene cards as chapters in output ms (at most 100), and a project opts the MCP server into publishing share links with share.allowMcp, off by default (spec 349). --- .../core/schemas/project-config.schema.json | 11 ++++++ packages/core/src/project-config.ts | 13 +++++++ packages/core/src/run-result.ts | 12 +++++++ packages/core/test/project-config.spec.ts | 17 +++++++++ packages/core/test/run-result.spec.ts | 35 +++++++++++++++++++ 5 files changed, 88 insertions(+) diff --git a/packages/core/schemas/project-config.schema.json b/packages/core/schemas/project-config.schema.json index ba2ef8eb..3c2b75f1 100644 --- a/packages/core/schemas/project-config.schema.json +++ b/packages/core/schemas/project-config.schema.json @@ -375,6 +375,17 @@ } }, "additionalProperties": false + }, + "share": { + "type": "object", + "properties": { + "allowMcp": { + "default": false, + "description": "Let the MCP server (share_demo) publish the video of a run as a public link without asking anyone. Off by default; anyone with the link can watch until it expires or is revoked.", + "type": "boolean" + } + }, + "additionalProperties": false } }, "required": ["baseUrl"], diff --git a/packages/core/src/project-config.ts b/packages/core/src/project-config.ts index 1f6f4b8a..d7da5aa0 100644 --- a/packages/core/src/project-config.ts +++ b/packages/core/src/project-config.ts @@ -269,6 +269,18 @@ export const RenderConfigSchema = z .prefault({}); export type RenderConfig = z.infer<typeof RenderConfigSchema>; +/** + * Share links (spec 349, ADR-0019 §6). Off unless committed: an agent may + * then publish a video outside the machine without asking. + */ +export const ShareConfigSchema = z.strictObject({ + allowMcp: z.boolean().default(false).meta({ + description: + 'Let the MCP server (share_demo) publish the video of a run as a public link without asking anyone. Off by default; anyone with the link can watch until it expires or is revoked.', + }), +}); +export type ShareConfig = z.infer<typeof ShareConfigSchema>; + const PORT_TEMPLATE = // biome-ignore lint/suspicious/noTemplateCurlyInString: `${PORT}` is the config's own syntax. '${PORT} is the port of the run: --port, else PORT from the environment, else the default in ${PORT:-3000}. $${ is a literal ${.'; @@ -306,6 +318,7 @@ export const ProjectConfigSchema = z 'Where the fragments scenarios include live, relative to the project root. Default demoflow/fragments.', }), render: RenderConfigSchema, + share: ShareConfigSchema.optional(), }) .transform(({ allowedOrigins, ...config }) => { const origin = new URL(config.baseUrl).origin; diff --git a/packages/core/src/run-result.ts b/packages/core/src/run-result.ts index 966f706c..7c5a9d7e 100644 --- a/packages/core/src/run-result.ts +++ b/packages/core/src/run-result.ts @@ -94,6 +94,16 @@ export const RENDER_FORMATS = [ ] as const; export type RenderFormat = (typeof RENDER_FORMATS)[number]; +/** A scene card of a render: its title and where it starts, in output ms (spec 349). */ +export const ChapterSchema = z.strictObject({ + title: NonEmptyStringSchema.max(200), + atMs: z.number().int().nonnegative(), +}); +export type Chapter = z.infer<typeof ChapterSchema>; + +/** A render carries at most this many chapters (spec 349, Decision 1). */ +export const MAX_CHAPTERS = 100; + export const RenderOutputSchema = z.strictObject({ renderer: NonEmptyStringSchema, // Runs before spec 133 rendered only MP4 and wrote no `format`. @@ -105,6 +115,8 @@ export const RenderOutputSchema = z.strictObject({ width: z.number().int().positive(), height: z.number().int().positive(), fps: z.number().positive(), + // One per scene card, in output ms; renders before spec 349 have none. + chapters: z.array(ChapterSchema).max(MAX_CHAPTERS).optional(), }); /** One rendered file; for a GIF, its own size and frame rate. */ export type RenderOutput = z.infer<typeof RenderOutputSchema>; diff --git a/packages/core/test/project-config.spec.ts b/packages/core/test/project-config.spec.ts index b1517484..c6775fff 100644 --- a/packages/core/test/project-config.spec.ts +++ b/packages/core/test/project-config.spec.ts @@ -34,6 +34,23 @@ describe('parseProjectConfig', () => { }); }); + it('keeps share.allowMcp, off unless set, and rejects unknown keys (spec 349)', () => { + const baseUrl = 'https://a.example'; + expect(parseProjectConfig({ baseUrl, share: {} })).toMatchObject({ + ok: true, + value: { share: { allowMcp: false } }, + }); + expect( + parseProjectConfig({ baseUrl, share: { allowMcp: true } }), + ).toMatchObject({ ok: true, value: { share: { allowMcp: true } } }); + expect(parseProjectConfig({ baseUrl, share: { allowMcp: 'yes' } }).ok).toBe( + false, + ); + expect(parseProjectConfig({ baseUrl, share: { public: true } }).ok).toBe( + false, + ); + }); + it('keeps the square formats and their own settings (spec 304)', () => { const result = parseProjectConfig({ baseUrl: 'https://a.example', diff --git a/packages/core/test/run-result.spec.ts b/packages/core/test/run-result.spec.ts index 049f2e0b..a268cc26 100644 --- a/packages/core/test/run-result.spec.ts +++ b/packages/core/test/run-result.spec.ts @@ -1,6 +1,7 @@ import { describe, expect, it } from 'vitest'; import { deriveRunStatus, + MAX_CHAPTERS, RunResultSchema, type RunStatus, STAGE_NAMES, @@ -139,6 +140,40 @@ describe('RunResultSchema', () => { expect(parsed.renders[0]?.format).toBe('mp4'); }); + it('reads a render without chapters, and keeps the chapters of one (spec 349)', () => { + const [render] = result.renders; + expect(RunResultSchema.parse(result).renders[0]?.chapters).toBeUndefined(); + const chapters = [ + { title: 'Sign in', atMs: 2000 }, + { title: 'Create a project', atMs: 9500 }, + ]; + expect( + RunResultSchema.parse({ ...result, renders: [{ ...render, chapters }] }) + .renders[0]?.chapters, + ).toEqual(chapters); + }); + + it('rejects a chapter that is empty, too long, negative or one too many', () => { + const [render] = result.renders; + const parses = (chapters: unknown) => + RunResultSchema.safeParse({ + ...result, + renders: [{ ...render, chapters }], + }).success; + expect(parses([{ title: '', atMs: 0 }])).toBe(false); + expect(parses([{ title: 'x'.repeat(201), atMs: 0 }])).toBe(false); + expect(parses([{ title: 'x'.repeat(200), atMs: 0 }])).toBe(true); + expect(parses([{ title: 'Intro', atMs: -1 }])).toBe(false); + expect(parses([{ title: 'Intro', atMs: 1.5 }])).toBe(false); + const many = (count: number) => + Array.from({ length: count }, (_, index) => ({ + title: `Scene ${index}`, + atMs: index * 1000, + })); + expect(parses(many(MAX_CHAPTERS))).toBe(true); + expect(parses(many(MAX_CHAPTERS + 1))).toBe(false); + }); + it('keeps each render format, in order, and rejects an unknown one', () => { const [render] = result.renders; const formats = [ From d09c1fadd04bd11d77ae670c13e064ee78849047 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 19:23:14 +0100 Subject: [PATCH 54/71] =?UTF-8?q?feat(web):=20add=20project=20dialog=20?= =?UTF-8?q?=E2=80=94=20machine,=20path,=20inspection,=20create=20config,?= =?UTF-8?q?=20GitHub=20link=20(#379)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the name-only create form and the inline bind form on the projects page with one Add project dialog. It picks a ready machine, inspects the typed folder after a 600 ms pause (stale answers dropped by sequence number), offers Create config for a folder without one, explains a refused folder with the allow command, and registers the project with an optional GitHub link. Rows link to the project's GitHub repository in a new tab. --- apps/web/package.json | 2 +- .../projects/add-project-dialog.tsx | 334 ++++++++++++++++++ .../projects/add-project/inspection-panel.tsx | 189 ++++++++++ .../projects/add-project/machine-field.tsx | 74 ++++ .../src/components/projects/project-list.tsx | 228 +++--------- apps/web/src/i18n/en.ts | 85 +++-- apps/web/src/lib/add-project.test.mjs | 313 ++++++++++++++++ apps/web/src/lib/add-project.ts | 327 +++++++++++++++++ apps/web/src/lib/api.ts | 87 ++++- 9 files changed, 1424 insertions(+), 215 deletions(-) create mode 100644 apps/web/src/components/projects/add-project-dialog.tsx create mode 100644 apps/web/src/components/projects/add-project/inspection-panel.tsx create mode 100644 apps/web/src/components/projects/add-project/machine-field.tsx create mode 100644 apps/web/src/lib/add-project.test.mjs create mode 100644 apps/web/src/lib/add-project.ts diff --git a/apps/web/package.json b/apps/web/package.json index c1ef2f68..dce8c8fa 100644 --- a/apps/web/package.json +++ b/apps/web/package.json @@ -7,7 +7,7 @@ "start": "next start -p 3670", "start:dev": "node scripts/dev.mjs", "lint": "biome lint src", - "test": "node --test src/lib/docs-nav.test.mjs src/lib/playback.test.mjs src/lib/launch.test.mjs src/lib/format-bytes.test.mjs src/lib/run-delete.test.mjs src/lib/player-choice.test.mjs src/lib/nav.test.mjs src/lib/crumbs.test.mjs src/lib/theme.test.mjs src/lib/overview-stats.test.mjs src/lib/status.test.mjs src/lib/share-page.test.mjs" + "test": "node --test src/lib/docs-nav.test.mjs src/lib/playback.test.mjs src/lib/launch.test.mjs src/lib/format-bytes.test.mjs src/lib/run-delete.test.mjs src/lib/player-choice.test.mjs src/lib/nav.test.mjs src/lib/crumbs.test.mjs src/lib/theme.test.mjs src/lib/overview-stats.test.mjs src/lib/status.test.mjs src/lib/share-page.test.mjs src/lib/add-project.test.mjs" }, "dependencies": { "@andrewbehma/glass-ui": "0.37.0", diff --git a/apps/web/src/components/projects/add-project-dialog.tsx b/apps/web/src/components/projects/add-project-dialog.tsx new file mode 100644 index 00000000..536d6a8b --- /dev/null +++ b/apps/web/src/components/projects/add-project-dialog.tsx @@ -0,0 +1,334 @@ +'use client'; + +import { Banner } from '@andrewbehma/glass-ui/banner'; +import { Button } from '@andrewbehma/glass-ui/button'; +import { DialogContent, DialogRoot } from '@andrewbehma/glass-ui/dialog'; +import { Field, Input } from '@andrewbehma/glass-ui/field'; +import Link from 'next/link'; +import { useRouter } from 'next/navigation'; +import { useEffect, useId, useReducer, useRef, useState } from 'react'; +import { t } from '@/i18n'; +import { + type AddProjectState, + addProjectReducer, + canAdd, + canCreateConfig, + createInspector, + folderErrorKey, + githubUrlValue, + INITIAL_STATE, + inspectionResult, + isProjectName, + machineChoice, + pathPlaceholder, + preselectMachine, +} from '@/lib/add-project'; +import { + initFolder, + inspectFolder, + type Project, + type Runner, + registerFolder, +} from '@/lib/api'; +import { InspectionPanel } from './add-project/inspection-panel'; +import { MachineField } from './add-project/machine-field'; + +const FORM_ID = 'add-project-form'; + +/** The folder the dialog asks about, numbered as the reducer numbers it. */ +interface Target { + seq: number; + runnerId: string; + path: string; +} + +/** + * Adds a project from a folder on one of the user's machines (spec #379). The + * page remounts it on every open, so it always starts empty. + */ +export function AddProjectDialog({ + open, + onOpenChange, + machines, + projects, +}: { + open: boolean; + onOpenChange: (open: boolean) => void; + machines: Runner[]; + projects: Project[]; +}) { + const router = useRouter(); + const machineId = useId(); + const pathId = useId(); + const nameId = useId(); + const githubId = useId(); + const [runnerId, setRunnerId] = useState(() => + preselectMachine(machines, projects), + ); + const [path, setPath] = useState(''); + // Until typed, the name and the link follow what the machine found. + const [name, setName] = useState<string | null>(null); + const [githubUrl, setGithubUrl] = useState<string | null>(null); + const [checked, setChecked] = useState(false); + const [state, dispatch] = useReducer(addProjectReducer, INITIAL_STATE); + const target = useRef<Target>({ seq: 0, runnerId, path: '' }); + const [inspector] = useState(() => + createInspector({ + inspect: async (seq) => { + const { runnerId: id, path: folder } = target.current; + if (target.current.seq !== seq) return; + const result = await inspectFolder(id, folder); + dispatch( + result.ok + ? { type: 'inspected', seq, inspection: result.data } + : { type: 'inspect-failed', seq, error: folderErrorKey(result) }, + ); + }, + }), + ); + useEffect(() => inspector.dispose, [inspector]); + + const machine = machines.find((item) => item.id === runnerId); + const inspection = 'inspection' in state ? state.inspection : null; + const nameValue = name ?? inspection?.name ?? ''; + const githubValue = githubUrl ?? inspection?.githubUrl ?? ''; + const nameValid = isProjectName(nameValue); + const githubValid = githubUrlValue(githubValue).ok; + const working = + state.phase === 'initialising' || state.phase === 'registering'; + const showsAdd = + state.phase === 'idle' || + state.phase === 'inspecting' || + state.phase === 'registering' || + canAdd(state); + + /** A new machine or path: a new folder to inspect once typing pauses. */ + function change(nextRunnerId: string, nextPath: string) { + const folder = nextPath.trim(); + const chosen = machines.find((item) => item.id === nextRunnerId); + const ready = + chosen !== undefined && + machineChoice(chosen) === 'ready' && + folder !== ''; + const seq = target.current.seq + 1; + target.current = { seq, runnerId: nextRunnerId, path: folder }; + setName(null); + setGithubUrl(null); + setChecked(false); + dispatch({ type: 'changed', seq, ready }); + inspector.change(seq, ready); + } + + async function createConfig() { + if (!canCreateConfig(state)) return; + const { seq, runnerId: id, path: folder } = target.current; + dispatch({ type: 'init-started', seq }); + const result = await initFolder(id, folder); + dispatch( + result.ok + ? { + type: 'initialised', + seq, + created: result.data.created, + inspection: result.data.inspection, + } + : { type: 'init-failed', seq, error: folderErrorKey(result) }, + ); + } + + async function register() { + if (!canAdd(state)) return; + setChecked(true); + const link = githubUrlValue(githubValue); + if (!nameValid || !link.ok) return; + const { seq, runnerId: id, path: folder } = target.current; + dispatch({ type: 'register-started', seq }); + const result = await registerFolder({ + runnerId: id, + path: folder, + name: nameValue.trim(), + githubUrl: link.url, + }); + if (!result.ok) { + dispatch({ + type: 'register-failed', + seq, + error: folderErrorKey(result), + existingId: + result.code === 'project-exists' ? (result.projectId ?? null) : null, + }); + return; + } + const { id: projectId } = result.data.project; + dispatch({ type: 'registered', seq, projectId }); + router.push(`/app/projects/${encodeURIComponent(projectId)}`); + } + + return ( + <DialogRoot + open={open} + onOpenChange={(next) => { + // A request in flight is not hidden by closing over it. + if (state.phase !== 'registering') onOpenChange(next); + }} + > + <DialogContent + title={t('projects.add.title')} + description={t('projects.add.description')} + footer={ + <div className="flex justify-end gap-2"> + <Button + type="button" + variant="glass" + disabled={state.phase === 'registering'} + onClick={() => onOpenChange(false)} + > + {t('projects.add.cancel')} + </Button> + {machines.length > 0 && showsAdd ? ( + <Button type="submit" form={FORM_ID} disabled={!canAdd(state)}> + {state.phase === 'registering' + ? t('projects.add.submitting') + : t('projects.add.submit')} + </Button> + ) : null} + </div> + } + > + {machines.length === 0 ? ( + <Banner + tone="info" + action={ + <Link href="/app/machines" className="text-sm underline"> + {t('projects.add.machines')} + </Link> + } + > + {t('projects.add.noMachines')} + </Banner> + ) : ( + <form + id={FORM_ID} + className="flex flex-col gap-4" + noValidate + onSubmit={(event) => { + event.preventDefault(); + // Enter runs the action the folder offers (Decision 6). + if (canAdd(state)) void register(); + else if (canCreateConfig(state)) void createConfig(); + }} + > + {machines.every((item) => machineChoice(item) !== 'ready') ? ( + <Banner tone="warn">{t('projects.add.noReadyMachines')}</Banner> + ) : null} + <MachineField + id={machineId} + machines={machines} + value={runnerId} + disabled={working} + onChange={(value) => { + setRunnerId(value); + change(value, path); + }} + /> + <Field + label={t('projects.add.path')} + hint={t('projects.add.pathHint')} + htmlFor={pathId} + > + <Input + id={pathId} + value={path} + placeholder={pathPlaceholder(machine?.os)} + autoComplete="off" + spellCheck={false} + disabled={working} + onChange={(event) => { + setPath(event.target.value); + change(runnerId, event.target.value); + }} + /> + </Field> + <InspectionPanel state={state} onCreateConfig={createConfig} /> + {inspection && inspectionResult(inspection) === 'found' ? ( + <> + <Field + label={t('projects.add.name')} + error={ + checked && !nameValid + ? t('projects.errors.name') + : undefined + } + htmlFor={nameId} + > + <Input + id={nameId} + value={nameValue} + disabled={working} + onChange={(event) => setName(event.target.value)} + /> + </Field> + <Field + label={t('projects.add.githubUrl')} + hint={t('projects.add.githubUrlHint')} + error={ + checked && !githubValid + ? t('projects.add.githubUrlInvalid') + : undefined + } + htmlFor={githubId} + > + <Input + id={githubId} + type="url" + value={githubValue} + placeholder="https://github.com/owner/repo" + autoComplete="off" + spellCheck={false} + disabled={working} + onChange={(event) => setGithubUrl(event.target.value)} + /> + </Field> + </> + ) : null} + <p role="status" aria-live="polite" className="sr-only"> + {announcement(state)} + </p> + </form> + )} + </DialogContent> + </DialogRoot> + ); +} + +/** What the status region reads out as the folder is looked at (Decision 6). */ +function announcement(state: AddProjectState): string { + switch (state.phase) { + case 'idle': + case 'done': + return ''; + case 'inspecting': + return t('projects.add.inspecting'); + case 'failed': + return t(state.error); + case 'initialising': + return t('projects.add.creatingConfig'); + case 'registering': + return t('projects.add.submitting'); + } + if (state.error) return t(state.error); + switch (inspectionResult(state.inspection)) { + case 'found': { + const count = state.inspection.scenarios.length; + return `${t('projects.add.found')}. ${ + count === 1 + ? t('projects.add.scenarioCountOne') + : t('projects.add.scenarioCount', { count }) + }`; + } + case 'no-config': + return t('projects.add.noConfig'); + case 'config-invalid': + return t('projects.add.configInvalid'); + } +} diff --git a/apps/web/src/components/projects/add-project/inspection-panel.tsx b/apps/web/src/components/projects/add-project/inspection-panel.tsx new file mode 100644 index 00000000..09709208 --- /dev/null +++ b/apps/web/src/components/projects/add-project/inspection-panel.tsx @@ -0,0 +1,189 @@ +import { Banner } from '@andrewbehma/glass-ui/banner'; +import { Button } from '@andrewbehma/glass-ui/button'; +import { Card } from '@andrewbehma/glass-ui/card'; +import { KeyValueList } from '@andrewbehma/glass-ui/key-value-list'; +import { Spinner } from '@andrewbehma/glass-ui/spinner'; +import { CircleCheck } from 'lucide-react'; +import Link from 'next/link'; +import { t } from '@/i18n'; +import { + type AddProjectState, + type FolderErrorKey, + type FolderInspection, + inspectionResult, + SCENARIOS_SHOWN, +} from '@/lib/add-project'; + +/** Where the allowed folders are documented (spec #380). */ +const ALLOW_DOCS = '/docs/runner#allowed-folders'; + +/** + * What the machine found in the folder (spec #379, Decision 3). It shows only + * the inspection's fields — never a file's content (Decision 5). + */ +export function InspectionPanel({ + state, + onCreateConfig, +}: { + state: AddProjectState; + onCreateConfig: () => void; +}) { + switch (state.phase) { + case 'idle': + case 'done': + return null; + case 'inspecting': + return ( + <p className="flex items-center gap-2 text-sm text-ink-2"> + <Spinner size="sm" label={null} /> + {t('projects.add.inspecting')} + </p> + ); + case 'failed': + return <FolderError error={state.error} existingId={null} />; + } + const result = inspectionResult(state.inspection); + return ( + <div className="flex flex-col gap-3"> + {result === 'found' ? ( + <Found inspection={state.inspection} /> + ) : result === 'no-config' ? ( + <Banner + tone="info" + action={ + <Button + type="button" + size="sm" + disabled={state.phase !== 'inspected'} + onClick={onCreateConfig} + > + {state.phase === 'initialising' + ? t('projects.add.creatingConfig') + : t('projects.add.createConfig')} + </Button> + } + > + {t('projects.add.noConfig')} + </Banner> + ) : ( + <Banner tone="warn">{t('projects.add.configInvalid')}</Banner> + )} + {state.created && state.created.length > 0 ? ( + <Banner + tone="ok" + title={t('projects.add.created', { + files: state.created.join(', '), + })} + > + {t('projects.add.createdHint')} + </Banner> + ) : null} + {state.error ? ( + <FolderError error={state.error} existingId={state.existingId} /> + ) : null} + </div> + ); +} + +function Found({ inspection }: { inspection: FolderInspection }) { + const { scenarios } = inspection; + const shown = scenarios.slice(0, SCENARIOS_SHOWN).map(({ name }) => name); + const more = scenarios.length - shown.length; + return ( + <Card variant="content" pad="sm" className="flex flex-col gap-3"> + <p className="flex flex-wrap items-center gap-x-3 gap-y-1 text-sm"> + <span className="flex items-center gap-1.5 font-medium text-ink"> + <CircleCheck aria-hidden size={16} className="text-ok" /> + {t('projects.add.found')} + </span> + <span className="text-ink-2"> + {scenarios.length === 1 + ? t('projects.add.scenarioCountOne') + : t('projects.add.scenarioCount', { count: scenarios.length })} + </span> + </p> + <KeyValueList + dense + items={[ + { + key: 'folder', + label: t('projects.add.folderName'), + value: inspection.rootPath, + }, + { + key: 'scenarios', + label: t('projects.add.scenarios'), + value: + shown.length === 0 + ? t('projects.add.noScenarios') + : [ + shown.join(' · '), + more > 0 + ? ` ${t('projects.add.scenarioMore', { count: more })}` + : '', + ].join(''), + }, + ...(inspection.githubUrl + ? [ + { + key: 'github', + label: t('projects.add.github'), + value: ( + <a + href={inspection.githubUrl} + target="_blank" + rel="noopener noreferrer" + className="underline-offset-2 hover:underline" + > + {inspection.githubUrl.replace(/^https:\/\//, '')} + </a> + ), + }, + ] + : []), + ]} + /> + </Card> + ); +} + +function FolderError({ + error, + existingId, +}: { + error: FolderErrorKey; + existingId: string | null; +}) { + if (error === 'projects.add.errors.pathNotAllowed') { + return ( + <Banner + tone="warn" + action={ + <Link href={ALLOW_DOCS} className="text-sm underline"> + {t('projects.add.allowDocs')} + </Link> + } + > + {t(error)}{' '} + <code className="font-mono">{t('projects.add.allowCommand')}</code> + </Banner> + ); + } + return ( + <Banner + tone="danger" + action={ + existingId ? ( + <Link + href={`/app/projects/${encodeURIComponent(existingId)}`} + className="text-sm underline" + > + {t('projects.add.openExisting')} + </Link> + ) : undefined + } + > + {t(error)} + </Banner> + ); +} diff --git a/apps/web/src/components/projects/add-project/machine-field.tsx b/apps/web/src/components/projects/add-project/machine-field.tsx new file mode 100644 index 00000000..2d52f2ad --- /dev/null +++ b/apps/web/src/components/projects/add-project/machine-field.tsx @@ -0,0 +1,74 @@ +import { Field, Select } from '@andrewbehma/glass-ui/field'; +import { StatusPill } from '@andrewbehma/glass-ui/status-pill'; +import { StatusIndicator } from '@/components/status/status-indicator'; +import { t } from '@/i18n'; +import { machineChoice } from '@/lib/add-project'; +import type { Runner } from '@/lib/api'; +import { machineStatus } from '@/lib/status'; + +/** + * The machine picker (spec #379, Decision 2): offline machines and machines + * whose CLI cannot add projects are listed but cannot be chosen. + */ +export function MachineField({ + id, + machines, + value, + disabled, + onChange, +}: { + id: string; + machines: Runner[]; + value: string; + disabled: boolean; + onChange: (runnerId: string) => void; +}) { + const chosen = machines.find((machine) => machine.id === value); + const outdated = machines.some( + (machine) => machineChoice(machine) === 'outdated', + ); + return ( + <Field + label={t('projects.add.machine')} + hint={outdated ? t('projects.add.outdatedHint') : undefined} + htmlFor={id} + > + <div className="flex items-center gap-2"> + <Select + id={id} + value={value} + disabled={disabled} + onChange={(event) => onChange(event.target.value)} + // Focus starts here (Decision 6). + autoFocus + className="min-w-0 flex-1" + > + <option value="">{t('projects.add.machinePlaceholder')}</option> + {machines.map((machine) => { + const choice = machineChoice(machine); + return ( + <option + key={machine.id} + value={machine.id} + disabled={choice !== 'ready'} + > + {choice === 'offline' + ? t('projects.add.optionOffline', { name: machine.name }) + : choice === 'outdated' + ? t('projects.add.optionOutdated', { name: machine.name }) + : machine.name} + </option> + ); + })} + </Select> + {chosen ? ( + machineChoice(chosen) === 'outdated' ? ( + <StatusPill status="paused" label={t('projects.add.outdated')} /> + ) : ( + <StatusIndicator status={machineStatus(chosen.online)} /> + ) + ) : null} + </div> + </Field> + ); +} diff --git a/apps/web/src/components/projects/project-list.tsx b/apps/web/src/components/projects/project-list.tsx index f16a937a..230477ed 100644 --- a/apps/web/src/components/projects/project-list.tsx +++ b/apps/web/src/components/projects/project-list.tsx @@ -5,15 +5,16 @@ import { Button } from '@andrewbehma/glass-ui/button'; import { Card } from '@andrewbehma/glass-ui/card'; import { ConfirmDialog } from '@andrewbehma/glass-ui/confirm-dialog'; import { EmptyState } from '@andrewbehma/glass-ui/empty-state'; -import { Field, Input, Select } from '@andrewbehma/glass-ui/field'; +import { Input } from '@andrewbehma/glass-ui/field'; +import { Plus } from 'lucide-react'; import Link from 'next/link'; import { useRouter } from 'next/navigation'; -import { type FormEvent, useId, useState } from 'react'; +import { useState } from 'react'; import { StatusIndicator } from '@/components/status/status-indicator'; import { t } from '@/i18n'; +import { isProjectName } from '@/lib/add-project'; import { type ApiResult, - createProject, deleteProject, type Project, type Runner, @@ -24,16 +25,11 @@ import { formatRelative } from '@/lib/format-relative'; import { lastRunStatus } from '@/lib/status'; import type { ErrorKey } from '@/lib/validation'; import { apiErrorKey } from '../auth/form-parts'; +import { GithubMark } from '../auth/github-mark'; +import { AddProjectDialog } from './add-project-dialog'; import { MachinePill } from './machine-pill'; -const NAME_MAX = 200; - -type Failure = - | 'projects.errors.name' - | 'projects.errors.bind' - | 'projects.errors.notFound'; - -type Editing = { id: string; mode: 'rename' | 'bind' }; +type Failure = 'projects.errors.name' | 'projects.errors.notFound'; export function ProjectList({ projects, @@ -43,13 +39,16 @@ export function ProjectList({ machines: Runner[]; }) { const router = useRouter(); - const [editing, setEditing] = useState<Editing | null>(null); + const [renaming, setRenaming] = useState<string | null>(null); const [deleting, setDeleting] = useState<Project | null>(null); const [busy, setBusy] = useState(false); const [error, setError] = useState<Failure | ErrorKey | undefined>(); + const [adding, setAdding] = useState(false); + // Every open mounts a fresh dialog, so it never shows the last folder. + const [addKey, setAddKey] = useState(0); function stop() { - setEditing(null); + setRenaming(null); setError(undefined); } @@ -77,44 +76,18 @@ export function ProjectList({ return false; } - async function create(name: string): Promise<boolean> { - const value = name.trim(); - if (value.length < 1 || [...value].length > NAME_MAX) { - setError('projects.errors.name'); - return false; - } - return run(() => createProject(value), 'projects.errors.name'); - } - async function rename(project: Project, name: string) { - const value = name.trim(); - if (value.length < 1 || [...value].length > NAME_MAX) { + if (!isProjectName(name)) { setError('projects.errors.name'); return; } if ( await run( - () => updateProject(project.id, { name: value }), + () => updateProject(project.id, { name: name.trim() }), 'projects.errors.name', ) ) { - setEditing(null); - } - } - - async function bind(project: Project, runnerId: string, rootPath: string) { - const path = rootPath.trim(); - if (!runnerId || path.length < 1) { - setError('projects.errors.bind'); - return; - } - if ( - await run( - () => updateProject(project.id, { runnerId, rootPath: path }), - 'projects.errors.bind', - ) - ) { - setEditing(null); + setRenaming(null); } } @@ -125,8 +98,19 @@ export function ProjectList({ return ( <div className="flex flex-col gap-4"> + <div className="flex justify-end"> + <Button + type="button" + onClick={() => { + setAddKey((key) => key + 1); + setAdding(true); + }} + > + <Plus aria-hidden size={16} /> + {t('projects.add.action')} + </Button> + </div> {error ? <Banner tone="danger">{t(error)}</Banner> : null} - <CreateForm busy={busy} onCreate={create} /> {projects.length === 0 ? ( <EmptyState title={t('projects.empty.title')} @@ -146,7 +130,7 @@ export function ProjectList({ className="flex flex-col gap-3 border-b border-line px-4 py-3 last:border-0 md:flex-row md:items-start md:justify-between" > <div className="flex min-w-0 flex-1 flex-col gap-3"> - {editing?.id === project.id && editing.mode === 'rename' ? ( + {renaming === project.id ? ( <RenameForm project={project} busy={busy} @@ -156,39 +140,33 @@ export function ProjectList({ ) : ( <ProjectSummary project={project} /> )} - {editing?.id === project.id && editing.mode === 'bind' ? ( - <BindForm - project={project} - machines={machines} - busy={busy} - onBind={(runnerId, path) => bind(project, runnerId, path)} - onCancel={stop} - /> - ) : null} </div> - <div className="flex shrink-0 flex-wrap gap-2"> + <div className="flex shrink-0 flex-wrap items-center gap-2"> + {project.githubUrl ? ( + <a + href={project.githubUrl} + target="_blank" + rel="noopener noreferrer" + aria-label={t('projects.item.github', { + name: project.name, + })} + title={t('projects.item.github', { name: project.name })} + className="inline-flex size-8 items-center justify-center rounded-control text-ink-2 hover:bg-hover hover:text-ink" + > + <GithubMark /> + </a> + ) : null} <Button type="button" variant="ghost" size="sm" onClick={() => { - setEditing({ id: project.id, mode: 'rename' }); + setRenaming(project.id); setError(undefined); }} > {t('projects.rename.action')} </Button> - <Button - type="button" - variant="ghost" - size="sm" - onClick={() => { - setEditing({ id: project.id, mode: 'bind' }); - setError(undefined); - }} - > - {t('projects.bind.action')} - </Button> <Button type="button" variant="danger" @@ -216,6 +194,13 @@ export function ProjectList({ if (deleting) void remove(deleting); }} /> + <AddProjectDialog + key={addKey} + open={adding} + onOpenChange={setAdding} + machines={machines} + projects={projects} + /> </div> ); } @@ -261,36 +246,6 @@ function ProjectSummary({ project }: { project: Project }) { ); } -function CreateForm({ - busy, - onCreate, -}: { - busy: boolean; - onCreate: (name: string) => Promise<boolean>; -}) { - const [value, setValue] = useState(''); - async function submit(event: FormEvent) { - event.preventDefault(); - if (await onCreate(value)) setValue(''); - } - return ( - <form className="flex flex-wrap items-end gap-2" onSubmit={submit}> - <div className="min-w-0 flex-1"> - <Input - aria-label={t('projects.create.label')} - placeholder={t('projects.create.placeholder')} - value={value} - onChange={(event) => setValue(event.target.value)} - required - /> - </div> - <Button type="submit" disabled={busy}> - {busy ? t('projects.create.submitting') : t('projects.create.submit')} - </Button> - </form> - ); -} - function RenameForm({ project, busy, @@ -335,84 +290,3 @@ function RenameForm({ </form> ); } - -function BindForm({ - project, - machines, - busy, - onBind, - onCancel, -}: { - project: Project; - machines: Runner[]; - busy: boolean; - onBind: (runnerId: string, rootPath: string) => void; - onCancel: () => void; -}) { - const machineId = useId(); - const pathId = useId(); - const [runnerId, setRunnerId] = useState(project.runner?.id ?? ''); - const [path, setPath] = useState(project.rootPath ?? ''); - if (machines.length === 0) { - return ( - <Banner tone="info"> - {t('projects.bind.noMachines')}{' '} - <Link href="/app/machines" className="underline"> - {t('projects.bind.machines')} - </Link> - </Banner> - ); - } - return ( - <form - className="flex flex-col gap-3 rounded-control bg-hover p-3" - aria-label={t('projects.bind.title', { name: project.name })} - onSubmit={(event) => { - event.preventDefault(); - onBind(runnerId, path); - }} - > - <Field label={t('projects.bind.machine')} htmlFor={machineId}> - <Select - id={machineId} - value={runnerId} - onChange={(event) => setRunnerId(event.target.value)} - required - > - <option value="">{t('projects.bind.machinePlaceholder')}</option> - {machines.map((machine) => ( - <option key={machine.id} value={machine.id}> - {machine.name} - </option> - ))} - </Select> - </Field> - <Field - label={t('projects.bind.path')} - hint={t('projects.bind.pathHint')} - htmlFor={pathId} - > - <Input - id={pathId} - value={path} - onChange={(event) => setPath(event.target.value)} - required - /> - </Field> - <div className="flex gap-2"> - <Button type="submit" size="sm" disabled={busy}> - {busy ? t('projects.bind.submitting') : t('projects.bind.submit')} - </Button> - <Button - type="button" - variant="ghost" - size="sm" - disabled={busy} - onClick={onCancel} - > - {t('projects.bind.cancel')} - </Button> - </div> - </form> - ); -} diff --git a/apps/web/src/i18n/en.ts b/apps/web/src/i18n/en.ts index ff496db2..5eca1689 100644 --- a/apps/web/src/i18n/en.ts +++ b/apps/web/src/i18n/en.ts @@ -238,17 +238,75 @@ export const en = { loadFailed: 'We could not load your projects. Try again in a moment.', empty: { title: 'No projects yet', - body: 'A project appears when a paired machine runs a scenario in a folder. You can also create one here and bind it to a folder later.', + body: 'A project appears when a paired machine runs a scenario in a folder. You can also add a folder from one of your machines here.', docs: 'Read how to record a first run', }, - create: { - label: 'New project', - placeholder: 'Project name', - submit: 'Create project', - submitting: 'Creating…', + add: { + action: 'Add project', + title: 'Add project', + description: + 'Choose one of your machines and a folder on it. DemoFlow asks the machine what it finds there.', + machine: 'Machine', + machinePlaceholder: 'Choose a machine', + outdated: 'Update the CLI', + optionOffline: '{name} (offline)', + optionOutdated: '{name} (update the CLI)', + outdatedHint: + 'A machine marked “update the CLI” runs an older DemoFlow CLI: update it there and restart its runner to add projects from the website.', + noMachines: 'Pair a machine first, then add a folder from it.', + noReadyMachines: + 'None of your machines can be chosen now: start the runner on one, or update its CLI.', + machines: 'Go to machines', + path: 'Folder', + pathHint: 'The project folder on that machine, as an absolute path.', + inspecting: 'Looking at the folder…', + found: 'demoflow.config.json found', + scenarioCountOne: '1 scenario', + scenarioCount: '{count} scenarios', + scenarioMore: 'and {count} more', + scenarios: 'Scenarios', + noScenarios: 'No scenarios yet', + folderName: 'Folder', + github: 'GitHub', + noConfig: 'This folder has no demoflow.config.json.', + createConfig: 'Create config', + creatingConfig: 'Creating…', + created: 'Created {files}.', + createdHint: + 'Set devCommand and baseUrl in demoflow.config.json in the repository so DemoFlow can start your app.', + configInvalid: + 'This folder has a demoflow.config.json that DemoFlow cannot read. Fix it in the repository, then type the path again.', + allowCommand: 'demoflow runner allow <dir>', + allowDocs: 'How to allow a folder', + name: 'Name', + githubUrl: 'GitHub repository', + githubUrlHint: 'Optional. https://github.com/<owner>/<repo>', + githubUrlInvalid: + 'Enter https://github.com/<owner>/<repo>, or leave it empty.', + submit: 'Add project', + submitting: 'Adding…', + cancel: 'Cancel', + openExisting: 'Open the existing project', + errors: { + pathNotAllowed: + 'This folder is outside the folders this machine allows. On that machine run:', + configMissing: 'This folder has no demoflow.config.json.', + configInvalid: 'The demoflow.config.json in this folder is not valid.', + runnerNotFound: 'This machine is gone. Choose another one.', + runnerOffline: + 'This machine went offline. Start its runner and try again.', + runnerOutdated: + 'Update the CLI on this machine to add projects from the website.', + runnerBusy: 'This machine is busy. Try again in a moment.', + runnerTimeout: 'The machine did not answer in time. Try again.', + runnerError: 'The machine could not do that. Try again.', + projectExists: 'This folder is already a project.', + invalid: 'Check the folder path, the name and the GitHub link.', + }, }, item: { noFolder: 'No folder bound yet', + github: 'Open {name} on GitHub', machineRemoved: 'Machine removed', noRuns: 'No runs yet', runCount: '{count} runs', @@ -261,20 +319,6 @@ export const en = { saving: 'Saving…', cancel: 'Cancel', }, - bind: { - action: 'Bind to a folder', - title: 'Bind “{name}” to a folder', - machine: 'Machine', - machinePlaceholder: 'Choose a machine', - path: 'Absolute folder path', - pathHint: - 'The project root on that machine. If DemoFlow already made a project for this folder, its runs move here and it is removed.', - noMachines: 'Pair a machine first, then bind the project to it.', - machines: 'Go to machines', - submit: 'Bind', - submitting: 'Binding…', - cancel: 'Cancel', - }, delete: { action: 'Delete', title: 'Delete “{name}”?', @@ -282,7 +326,6 @@ export const en = { }, errors: { name: 'Enter a name of 1 to 200 characters.', - bind: 'Choose a machine and enter an absolute folder path.', notFound: 'This project is already gone. The list was refreshed.', }, library: { diff --git a/apps/web/src/lib/add-project.test.mjs b/apps/web/src/lib/add-project.test.mjs new file mode 100644 index 00000000..1bd0ea0d --- /dev/null +++ b/apps/web/src/lib/add-project.test.mjs @@ -0,0 +1,313 @@ +import assert from 'node:assert/strict'; +import { mock, test } from 'node:test'; +import { + addProjectReducer, + canAdd, + canCreateConfig, + createInspector, + folderErrorKey, + githubUrlValue, + INITIAL_STATE, + INSPECT_DELAY_MS, + inspectionResult, + isProjectName, + machineChoice, + pathPlaceholder, + preselectMachine, +} from './add-project.ts'; + +const inspection = { + rootPath: '/home/me/app', + name: 'app', + hasConfig: true, + configValid: true, + scenarios: [{ id: 'demoflow/a.demo.json', name: 'Login' }], + githubUrl: 'https://github.com/me/app', +}; +const noConfig = { + ...inspection, + hasConfig: false, + configValid: false, + scenarios: [], +}; + +/** Runs the events through the reducer from the initial state. */ +function play(...events) { + return events.reduce(addProjectReducer, INITIAL_STATE); +} + +test('only an online machine announcing projects can be chosen', () => { + assert.equal( + machineChoice({ online: true, features: ['projects'] }), + 'ready', + ); + assert.equal( + machineChoice({ online: false, features: ['projects'] }), + 'offline', + ); + assert.equal(machineChoice({ online: true, features: [] }), 'outdated'); + assert.equal(machineChoice({ online: true }), 'outdated'); +}); + +test('the machine of the latest run is preselected when it can be chosen', () => { + const machines = [ + { id: 'a', online: true, features: ['projects'] }, + { id: 'b', online: true, features: ['projects'] }, + { id: 'c', online: false, features: ['projects'] }, + ]; + const run = (runnerId, startedAt) => ({ + runner: { id: runnerId }, + lastRun: { startedAt }, + }); + assert.equal( + preselectMachine(machines, [ + run('a', '2026-10-01T00:00:00Z'), + run('b', '2026-10-02T00:00:00Z'), + ]), + 'b', + ); + // The latest run's machine is offline: the first that can be chosen. + assert.equal( + preselectMachine(machines, [run('c', '2026-10-03T00:00:00Z')]), + 'a', + ); + assert.equal(preselectMachine(machines, []), 'a'); + assert.equal(preselectMachine([machines[2]], []), ''); +}); + +test('the path placeholder follows the machine platform', () => { + assert.equal(pathPlaceholder('win32 10.0.22631'), 'C:\\Users\\you\\my-app'); + assert.equal(pathPlaceholder('darwin 24.1.0'), '/Users/you/my-app'); + assert.equal(pathPlaceholder('linux 6.19.10'), '/home/you/my-app'); + assert.equal(pathPlaceholder(undefined), '/home/you/my-app'); +}); + +test('an inspection is found, without config, or with an invalid one', () => { + assert.equal(inspectionResult(inspection), 'found'); + assert.equal(inspectionResult(noConfig), 'no-config'); + assert.equal( + inspectionResult({ ...inspection, configValid: false }), + 'config-invalid', + ); +}); + +test('every folder error code has its own message', () => { + const expected = { + 'path-not-allowed': 'pathNotAllowed', + 'config-missing': 'configMissing', + 'config-invalid': 'configInvalid', + 'runner-not-found': 'runnerNotFound', + 'runner-offline': 'runnerOffline', + 'runner-outdated': 'runnerOutdated', + 'runner-busy': 'runnerBusy', + 'runner-timeout': 'runnerTimeout', + 'runner-error': 'runnerError', + 'project-exists': 'projectExists', + }; + for (const [code, key] of Object.entries(expected)) { + assert.equal( + folderErrorKey({ error: 'invalid', code }), + `projects.add.errors.${key}`, + ); + } + assert.equal( + folderErrorKey({ error: 'rate_limited' }), + 'auth.errors.rateLimited', + ); + assert.equal( + folderErrorKey({ error: 'invalid' }), + 'projects.add.errors.invalid', + ); + assert.equal(folderErrorKey({ error: 'unknown' }), 'auth.errors.unknown'); +}); + +test('a GitHub link is a repository page or nothing', () => { + assert.deepEqual(githubUrlValue(' '), { ok: true, url: null }); + assert.deepEqual(githubUrlValue(' https://github.com/me/app '), { + ok: true, + url: 'https://github.com/me/app', + }); + for (const bad of [ + 'http://github.com/me/app', + 'https://gitlab.com/me/app', + 'https://user:token@github.com/me/app', + 'https://github.com/me/app/tree/main', + ]) { + assert.deepEqual(githubUrlValue(bad), { ok: false }); + } +}); + +test('a project name is 1 to 200 characters', () => { + assert.equal(isProjectName(' app '), true); + assert.equal(isProjectName(' '), false); + assert.equal(isProjectName('a'.repeat(200)), true); + assert.equal(isProjectName('a'.repeat(201)), false); +}); + +test('a folder with a valid config can be added', () => { + const state = play( + { type: 'changed', seq: 1, ready: true }, + { type: 'inspected', seq: 1, inspection }, + ); + assert.equal(state.phase, 'inspected'); + assert.equal(canAdd(state), true); + assert.equal(canCreateConfig(state), false); + const done = [ + { type: 'register-started', seq: 1 }, + { type: 'registered', seq: 1, projectId: 'p1' }, + ].reduce(addProjectReducer, state); + assert.deepEqual(done, { phase: 'done', seq: 1, projectId: 'p1' }); +}); + +test('a folder without config offers Create config, then is found', () => { + const state = play( + { type: 'changed', seq: 1, ready: true }, + { type: 'inspected', seq: 1, inspection: noConfig }, + ); + assert.equal(canAdd(state), false); + assert.equal(canCreateConfig(state), true); + const created = ['demoflow.config.json', 'demoflow/first.demo.json']; + const after = [ + { type: 'init-started', seq: 1 }, + { type: 'initialised', seq: 1, created, inspection }, + ].reduce(addProjectReducer, state); + assert.equal(after.phase, 'inspected'); + assert.deepEqual(after.created, created); + assert.equal(canAdd(after), true); +}); + +test('an invalid config offers neither action', () => { + const state = play( + { type: 'changed', seq: 1, ready: true }, + { + type: 'inspected', + seq: 1, + inspection: { ...inspection, configValid: false }, + }, + ); + assert.equal(canAdd(state), false); + assert.equal(canCreateConfig(state), false); + assert.equal( + addProjectReducer(state, { type: 'register-started', seq: 1 }), + state, + ); +}); + +test('a refused folder fails with the allow-roots message and no Add', () => { + const state = play( + { type: 'changed', seq: 1, ready: true }, + { + type: 'inspect-failed', + seq: 1, + error: 'projects.add.errors.pathNotAllowed', + }, + ); + assert.deepEqual(state, { + phase: 'failed', + seq: 1, + error: 'projects.add.errors.pathNotAllowed', + }); + assert.equal(canAdd(state), false); +}); + +test('a folder that is already a project offers to open it', () => { + const state = play( + { type: 'changed', seq: 1, ready: true }, + { type: 'inspected', seq: 1, inspection }, + { type: 'register-started', seq: 1 }, + { + type: 'register-failed', + seq: 1, + error: 'projects.add.errors.projectExists', + existingId: 'p0', + }, + ); + assert.equal(state.phase, 'inspected'); + assert.equal(state.error, 'projects.add.errors.projectExists'); + assert.equal(state.existingId, 'p0'); +}); + +test('a stale answer is never shown', () => { + const state = play( + { type: 'changed', seq: 1, ready: true }, + { type: 'changed', seq: 2, ready: true }, + { type: 'inspected', seq: 1, inspection: noConfig }, + ); + assert.deepEqual(state, { phase: 'inspecting', seq: 2 }); + const failed = addProjectReducer(state, { + type: 'inspect-failed', + seq: 1, + error: 'projects.add.errors.pathNotAllowed', + }); + assert.equal(failed, state); + assert.equal( + addProjectReducer(state, { type: 'inspected', seq: 2, inspection }).phase, + 'inspected', + ); +}); + +test('an older change does not undo a newer one', () => { + const state = play( + { type: 'changed', seq: 2, ready: true }, + { type: 'changed', seq: 1, ready: false }, + ); + assert.deepEqual(state, { phase: 'inspecting', seq: 2 }); +}); + +test('clearing the path goes back to idle and drops the pending answer', () => { + const state = play( + { type: 'changed', seq: 1, ready: true }, + { type: 'changed', seq: 2, ready: false }, + { type: 'inspected', seq: 1, inspection }, + ); + assert.deepEqual(state, { phase: 'idle', seq: 2 }); +}); + +test('typing quickly sends one inspection per pause', () => { + mock.timers.enable({ apis: ['setTimeout'] }); + try { + const sent = []; + const inspector = createInspector({ + inspect: async (seq) => { + sent.push(seq); + }, + }); + // Five keystrokes, each within the pause of the one before. + for (let seq = 1; seq <= 5; seq++) { + inspector.change(seq, true); + mock.timers.tick(INSPECT_DELAY_MS - 1); + } + assert.deepEqual(sent, []); + mock.timers.tick(1); + assert.deepEqual(sent, [5]); + // A pause, then two more keystrokes: one more inspection. + inspector.change(6, true); + mock.timers.tick(100); + inspector.change(7, true); + mock.timers.tick(INSPECT_DELAY_MS); + assert.deepEqual(sent, [5, 7]); + } finally { + mock.timers.reset(); + } +}); + +test('an empty path or a disposed dialog sends nothing', () => { + mock.timers.enable({ apis: ['setTimeout'] }); + try { + const sent = []; + const inspector = createInspector({ + inspect: async (seq) => { + sent.push(seq); + }, + }); + inspector.change(1, true); + inspector.change(2, false); + mock.timers.tick(INSPECT_DELAY_MS * 2); + inspector.change(3, true); + inspector.dispose(); + mock.timers.tick(INSPECT_DELAY_MS * 2); + assert.deepEqual(sent, []); + } finally { + mock.timers.reset(); + } +}); diff --git a/apps/web/src/lib/add-project.ts b/apps/web/src/lib/add-project.ts new file mode 100644 index 00000000..109d5fda --- /dev/null +++ b/apps/web/src/lib/add-project.ts @@ -0,0 +1,327 @@ +// Rules of the Add project dialog (spec #379). Plain functions and a reducer, +// so they are unit-tested without a browser. + +/** What the machine found in a folder (spec #377, Decision 5). */ +export interface FolderInspection { + rootPath: string; + name: string; + hasConfig: boolean; + configValid: boolean; + scenarios: { id: string; name: string }[]; + githubUrl: string | null; +} + +/** The pause after the last keystroke before the folder is inspected (Decision 3). */ +export const INSPECT_DELAY_MS = 600; + +/** How many scenario names the inspection shows. */ +export const SCENARIOS_SHOWN = 5; + +export const PROJECT_NAME_MAX = 200; + +/** The API's pattern for a project's GitHub link (spec #378, Decision 1). */ +export const GITHUB_URL_PATTERN = + /^https:\/\/github\.com\/[A-Za-z0-9._-]{1,100}\/[A-Za-z0-9._-]{1,100}$/; + +// Machines. + +export type MachineChoice = 'ready' | 'offline' | 'outdated'; + +/** + * Whether a machine can be chosen (Decision 2): online, and announcing + * `projects`. An API older than spec #378 sends no `features`: outdated. + */ +export function machineChoice(machine: { + online: boolean; + features?: readonly string[]; +}): MachineChoice { + if (!machine.online) return 'offline'; + return machine.features?.includes('projects') ? 'ready' : 'outdated'; +} + +/** + * The machine chosen when the dialog opens: the one that reported the latest + * run when it can be chosen, else the first that can, else none. + */ +export function preselectMachine( + machines: readonly { + id: string; + online: boolean; + features?: readonly string[]; + }[], + projects: readonly { + runner: { id: string } | null; + lastRun: { startedAt: string } | null; + }[], +): string { + const ready = machines.filter( + (machine) => machineChoice(machine) === 'ready', + ); + let latest: { runnerId: string; at: number } | null = null; + for (const project of projects) { + if (!project.runner || !project.lastRun) continue; + const at = Date.parse(project.lastRun.startedAt); + if (latest === null || at > latest.at) { + latest = { runnerId: project.runner.id, at }; + } + } + const last = ready.find((machine) => machine.id === latest?.runnerId); + return (last ?? ready[0])?.id ?? ''; +} + +/** + * The path placeholder in the machine's platform style (Decision 4), from the + * `os` its CLI reported at pairing (`win32 10.0…`, `darwin 24…`, `linux 6…`). + */ +export function pathPlaceholder(os: string | undefined): string { + if (os?.startsWith('win32')) return 'C:\\Users\\you\\my-app'; + if (os?.startsWith('darwin')) return '/Users/you/my-app'; + return '/home/you/my-app'; +} + +// What the inspection means. + +export type InspectionResult = 'found' | 'no-config' | 'config-invalid'; + +export function inspectionResult( + inspection: FolderInspection, +): InspectionResult { + if (!inspection.hasConfig) return 'no-config'; + return inspection.configValid ? 'found' : 'config-invalid'; +} + +export type FolderErrorKey = + | 'projects.add.errors.pathNotAllowed' + | 'projects.add.errors.configMissing' + | 'projects.add.errors.configInvalid' + | 'projects.add.errors.runnerNotFound' + | 'projects.add.errors.runnerOffline' + | 'projects.add.errors.runnerOutdated' + | 'projects.add.errors.runnerBusy' + | 'projects.add.errors.runnerTimeout' + | 'projects.add.errors.runnerError' + | 'projects.add.errors.projectExists' + | 'projects.add.errors.invalid' + | 'auth.errors.rateLimited' + | 'auth.errors.unknown'; + +/** The message for a failed folder call, from its `{ error }` code. */ +export function folderErrorKey(failure: { + error: string; + code?: string; +}): FolderErrorKey { + switch (failure.code) { + case 'path-not-allowed': + return 'projects.add.errors.pathNotAllowed'; + case 'config-missing': + return 'projects.add.errors.configMissing'; + case 'config-invalid': + return 'projects.add.errors.configInvalid'; + case 'runner-not-found': + return 'projects.add.errors.runnerNotFound'; + case 'runner-offline': + return 'projects.add.errors.runnerOffline'; + case 'runner-outdated': + return 'projects.add.errors.runnerOutdated'; + case 'runner-busy': + return 'projects.add.errors.runnerBusy'; + case 'runner-timeout': + return 'projects.add.errors.runnerTimeout'; + case 'runner-error': + return 'projects.add.errors.runnerError'; + case 'project-exists': + return 'projects.add.errors.projectExists'; + } + if (failure.error === 'rate_limited') return 'auth.errors.rateLimited'; + if (failure.error === 'invalid') return 'projects.add.errors.invalid'; + return 'auth.errors.unknown'; +} + +/** A typed GitHub link: empty is none, anything else must be a repository page. */ +export function githubUrlValue( + value: string, +): { ok: true; url: string | null } | { ok: false } { + const url = value.trim(); + if (url === '') return { ok: true, url: null }; + return GITHUB_URL_PATTERN.test(url) ? { ok: true, url } : { ok: false }; +} + +export function isProjectName(value: string): boolean { + const name = value.trim(); + return name.length > 0 && [...name].length <= PROJECT_NAME_MAX; +} + +// The flow (Decision 3). + +/** + * `idle → inspecting → inspected | failed → (initialising → inspected) → + * registering → done`, and back to `inspected` with an error when a step + * fails. `seq` numbers the folder the dialog asks about: every machine or path + * change takes a new one, and an answer for another number is stale. + */ +export type AddProjectState = + | { phase: 'idle'; seq: number } + | { phase: 'inspecting'; seq: number } + | { phase: 'failed'; seq: number; error: FolderErrorKey } + | { + phase: 'inspected' | 'initialising' | 'registering'; + seq: number; + inspection: FolderInspection; + /** Files the dialog's Create config wrote, to say so. */ + created: string[] | null; + error: FolderErrorKey | null; + /** With `project-exists`: the project that holds the folder. */ + existingId: string | null; + } + | { phase: 'done'; seq: number; projectId: string }; + +export type AddProjectEvent = + /** A new machine or path; `ready` when both are set and it is inspected next. */ + | { type: 'changed'; seq: number; ready: boolean } + | { type: 'inspected'; seq: number; inspection: FolderInspection } + | { type: 'inspect-failed'; seq: number; error: FolderErrorKey } + | { type: 'init-started'; seq: number } + | { + type: 'initialised'; + seq: number; + created: string[]; + inspection: FolderInspection; + } + | { type: 'init-failed'; seq: number; error: FolderErrorKey } + | { type: 'register-started'; seq: number } + | { type: 'registered'; seq: number; projectId: string } + | { + type: 'register-failed'; + seq: number; + error: FolderErrorKey; + existingId?: string | null; + }; + +export const INITIAL_STATE: AddProjectState = { phase: 'idle', seq: 0 }; + +export function addProjectReducer( + state: AddProjectState, + event: AddProjectEvent, +): AddProjectState { + if (event.type === 'changed') { + if (event.seq <= state.seq || state.phase === 'done') return state; + return { phase: event.ready ? 'inspecting' : 'idle', seq: event.seq }; + } + // Every other event answers a folder: only the current one counts. + if (event.seq !== state.seq) return state; + switch (event.type) { + case 'inspected': + if (state.phase !== 'inspecting') return state; + return found(state.seq, event.inspection, null); + case 'inspect-failed': + if (state.phase !== 'inspecting') return state; + return { phase: 'failed', seq: state.seq, error: event.error }; + case 'init-started': + if ( + state.phase !== 'inspected' || + inspectionResult(state.inspection) !== 'no-config' + ) { + return state; + } + return { ...state, phase: 'initialising', error: null }; + case 'initialised': + if (state.phase !== 'initialising') return state; + return found(state.seq, event.inspection, event.created); + case 'init-failed': + if (state.phase !== 'initialising') return state; + return { ...state, phase: 'inspected', error: event.error }; + case 'register-started': + if ( + state.phase !== 'inspected' || + inspectionResult(state.inspection) !== 'found' + ) { + return state; + } + return { ...state, phase: 'registering', error: null, existingId: null }; + case 'registered': + if (state.phase !== 'registering') return state; + return { phase: 'done', seq: state.seq, projectId: event.projectId }; + case 'register-failed': + if (state.phase !== 'registering') return state; + return { + ...state, + phase: 'inspected', + error: event.error, + existingId: event.existingId ?? null, + }; + } +} + +function found( + seq: number, + inspection: FolderInspection, + created: string[] | null, +): AddProjectState { + return { + phase: 'inspected', + seq, + inspection, + created, + error: null, + existingId: null, + }; +} + +/** Add project is offered only for a folder with a valid config. */ +export function canAdd(state: AddProjectState): boolean { + return ( + state.phase === 'inspected' && + inspectionResult(state.inspection) === 'found' + ); +} + +/** Create config is offered only for a folder without one. */ +export function canCreateConfig(state: AddProjectState): boolean { + return ( + state.phase === 'inspected' && + inspectionResult(state.inspection) === 'no-config' + ); +} + +// The debounce. + +interface Timers { + setTimeout: (callback: () => void, ms: number) => unknown; + clearTimeout: (handle: unknown) => void; +} + +/** + * Inspects the folder once typing pauses for `delayMs` (Decision 3). Every + * `change` cancels the pending inspection; one already sent answers with its + * own `seq`, which the reducer drops as stale. + */ +export function createInspector(options: { + inspect: (seq: number) => Promise<void>; + delayMs?: number; + timers?: Timers; +}): { change: (seq: number, ready: boolean) => void; dispose: () => void } { + const timers: Timers = options.timers ?? { + setTimeout: (callback, ms) => globalThis.setTimeout(callback, ms), + clearTimeout: (handle) => + globalThis.clearTimeout(handle as ReturnType<typeof setTimeout>), + }; + const delayMs = options.delayMs ?? INSPECT_DELAY_MS; + let pending: unknown = null; + + function cancel() { + if (pending !== null) timers.clearTimeout(pending); + pending = null; + } + + return { + change(seq, ready) { + cancel(); + if (!ready) return; + pending = timers.setTimeout(() => { + pending = null; + void options.inspect(seq); + }, delayMs); + }, + dispose: cancel, + }; +} diff --git a/apps/web/src/lib/api.ts b/apps/web/src/lib/api.ts index 104b4671..b5658553 100644 --- a/apps/web/src/lib/api.ts +++ b/apps/web/src/lib/api.ts @@ -2,11 +2,20 @@ // same-origin `/api/…`; a server component passes the API's internal origin // and the request's cookie header instead. +import type { FolderInspection } from './add-project'; + export type ApiError = 'invalid' | 'rate_limited' | 'unknown'; export type ApiResult<T> = | { ok: true; data: T } - | { ok: false; error: ApiError; status?: number; code?: string }; + | { + ok: false; + error: ApiError; + status?: number; + code?: string; + /** With `project-exists`: the project that holds the folder (spec #378). */ + projectId?: string; + }; /** A pending device code, as the signed-in user sees it (spec #135). */ export interface DeviceRequest { @@ -31,6 +40,8 @@ export interface Runner { lastSeenAt: string | null; /** The client IP at connect; shown only to the owner. */ lastSeenIp: string | null; + /** What its current socket can do (`projects`, spec #378); absent on an older API. */ + features?: string[]; } export interface PublicUser { @@ -71,17 +82,27 @@ function errorFor(status: number): ApiError { return 'unknown'; } -/** The `{ error }` code of a failed response, when its body has one. */ -async function errorCode(response: Response): Promise<string | undefined> { +/** The `{ error, projectId }` of a failed response, when its body has them. */ +async function errorBody( + response: Response, +): Promise<{ code?: string; projectId?: string }> { try { const body: unknown = await response.json(); - if (typeof body === 'object' && body !== null && 'error' in body) { - return typeof body.error === 'string' ? body.error : undefined; + if (typeof body === 'object' && body !== null) { + const code = + 'error' in body && typeof body.error === 'string' + ? body.error + : undefined; + const projectId = + 'projectId' in body && typeof body.projectId === 'string' + ? body.projectId + : undefined; + return { code, projectId }; } } catch { // No JSON body: the status alone has to do. } - return undefined; + return {}; } async function request<T>( @@ -105,7 +126,7 @@ async function request<T>( ok: false, error: errorFor(response.status), status: response.status, - code: await errorCode(response), + ...(await errorBody(response)), }; } const text = await response.text(); @@ -238,6 +259,8 @@ export interface Project { rootPath: string | null; /** Null for a project never bound, or whose machine was revoked. */ runner: { id: string; name: string } | null; + /** `https://github.com/<owner>/<repo>`; absent on an API older than #378. */ + githubUrl?: string | null; runCount: number; lastRun: ProjectRun | null; createdAt: string; @@ -257,17 +280,10 @@ export function listProjects(target?: Target) { ); } -export function createProject(name: string) { - return request<{ project: Project }>('/projects', { - method: 'POST', - body: { name }, - }); -} - -/** Renames and binds; `runnerId` and `rootPath` come together or not at all. */ +/** Renames, and sets or clears (`null`) the GitHub link (spec #378). */ export function updateProject( id: string, - changes: { name?: string; runnerId?: string; rootPath?: string }, + changes: { name?: string; githubUrl?: string | null }, ) { return request<{ project: Project }>(`/projects/${encodeURIComponent(id)}`, { method: 'PATCH', @@ -281,6 +297,45 @@ export function deleteProject(id: string) { }); } +// Adding a project from a folder on a machine (spec #379, API from #378). + +export interface FolderInit { + /** Files the machine wrote, relative to the folder. */ + created: string[]; + /** Files that were there already and stayed as they were. */ + kept: string[]; + inspection: FolderInspection; +} + +/** What the machine finds in the folder; nothing is stored. */ +export function inspectFolder(runnerId: string, path: string) { + return request<FolderInspection>('/projects/folders/inspect', { + method: 'POST', + body: { runnerId, path }, + }); +} + +/** Writes the config template into a folder without one. */ +export function initFolder(runnerId: string, path: string) { + return request<FolderInit>('/projects/folders/init', { + method: 'POST', + body: { runnerId, path }, + }); +} + +/** Adds the folder as a project; `githubUrl: null` stores no link. */ +export function registerFolder(folder: { + runnerId: string; + path: string; + name: string; + githubUrl: string | null; +}) { + return request<{ project: Project }>('/projects/folders/register', { + method: 'POST', + body: folder, + }); +} + // The run page (spec #193, API contract from spec #191 Decision 9). /** One run with its project and the machine that recorded it. */ From a65b6fea7c0cba7dc3fec967967bc74339834eee Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 19:24:15 +0100 Subject: [PATCH 55/71] feat(web): add share helpers and API client Pure helpers decide the Share button state, the format options with their sizes, the quota preview, the Extend cap and each row's actions, and map API refusals and upload failures to messages. They are tested with node --test. The calls live in shares-client.ts so the tested module keeps type-only imports. --- apps/web/package.json | 2 +- apps/web/src/lib/api.ts | 6 +- apps/web/src/lib/shares-client.ts | 40 +++++ apps/web/src/lib/shares.test.mjs | 188 ++++++++++++++++++++ apps/web/src/lib/shares.ts | 275 ++++++++++++++++++++++++++++++ 5 files changed, 508 insertions(+), 3 deletions(-) create mode 100644 apps/web/src/lib/shares-client.ts create mode 100644 apps/web/src/lib/shares.test.mjs create mode 100644 apps/web/src/lib/shares.ts diff --git a/apps/web/package.json b/apps/web/package.json index c1ef2f68..bf6884f1 100644 --- a/apps/web/package.json +++ b/apps/web/package.json @@ -7,7 +7,7 @@ "start": "next start -p 3670", "start:dev": "node scripts/dev.mjs", "lint": "biome lint src", - "test": "node --test src/lib/docs-nav.test.mjs src/lib/playback.test.mjs src/lib/launch.test.mjs src/lib/format-bytes.test.mjs src/lib/run-delete.test.mjs src/lib/player-choice.test.mjs src/lib/nav.test.mjs src/lib/crumbs.test.mjs src/lib/theme.test.mjs src/lib/overview-stats.test.mjs src/lib/status.test.mjs src/lib/share-page.test.mjs" + "test": "node --test src/lib/docs-nav.test.mjs src/lib/playback.test.mjs src/lib/launch.test.mjs src/lib/format-bytes.test.mjs src/lib/run-delete.test.mjs src/lib/player-choice.test.mjs src/lib/nav.test.mjs src/lib/crumbs.test.mjs src/lib/theme.test.mjs src/lib/overview-stats.test.mjs src/lib/status.test.mjs src/lib/share-page.test.mjs src/lib/shares.test.mjs" }, "dependencies": { "@andrewbehma/glass-ui": "0.37.0", diff --git a/apps/web/src/lib/api.ts b/apps/web/src/lib/api.ts index 104b4671..a5c9da17 100644 --- a/apps/web/src/lib/api.ts +++ b/apps/web/src/lib/api.ts @@ -58,7 +58,7 @@ export function githubStartUrl(intent: 'sign-in' | 'link'): string { return `/api/auth/github/start?intent=${intent}`; } -interface Target { +export interface Target { /** Origin to call instead of the same-origin `/api` prefix. */ baseUrl?: string; /** The incoming request's `cookie` header, for server-side calls. */ @@ -84,7 +84,7 @@ async function errorCode(response: Response): Promise<string | undefined> { return undefined; } -async function request<T>( +export async function request<T>( path: string, init: { method: 'GET' | 'POST' | 'PATCH' | 'DELETE'; body?: unknown }, target: Target = {}, @@ -324,6 +324,8 @@ export interface RunDetail { online: boolean; /** What the machine accepts on a start; absent on an older API. */ runOptions?: string[]; + /** What its daemon announced, as `share` (spec #347); absent on an older API. */ + features?: string[]; } | null; } diff --git a/apps/web/src/lib/shares-client.ts b/apps/web/src/lib/shares-client.ts new file mode 100644 index 00000000..491172d7 --- /dev/null +++ b/apps/web/src/lib/shares-client.ts @@ -0,0 +1,40 @@ +// The owner's share calls (spec #350, API from spec #347). Kept out of +// `api.ts` so other Phase 8 slices do not collide there; the pure helpers and +// types are in `shares.ts`. + +import { request, type Target } from './api'; +import type { Share, ShareLifetime, SharesList } from './shares'; + +export function listShares(target?: Target) { + return request<SharesList>('/shares', { method: 'GET' }, target); +} + +/** 202: the row exists, the upload runs in the background. */ +export function createShare(body: { + runId: string; + format: string; + expiresInDays: ShareLifetime; + password?: string; +}) { + return request<Share>('/shares', { method: 'POST', body }); +} + +export function getShare(id: string) { + return request<Share>(`/shares/${encodeURIComponent(id)}`, { + method: 'GET', + }); +} + +/** 30 more days, never beyond 90 from now; `at-max-expiry` past the cap. */ +export function extendShare(id: string) { + return request<Share>(`/shares/${encodeURIComponent(id)}/extend`, { + method: 'POST', + }); +} + +/** The link stops working at once; 204 when it is gone. */ +export function revokeShare(id: string) { + return request<void>(`/shares/${encodeURIComponent(id)}`, { + method: 'DELETE', + }); +} diff --git a/apps/web/src/lib/shares.test.mjs b/apps/web/src/lib/shares.test.mjs new file mode 100644 index 00000000..f7999a5d --- /dev/null +++ b/apps/web/src/lib/shares.test.mjs @@ -0,0 +1,188 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { + canExtend, + daysLeft, + defaultShareFormat, + markdownSnippet, + quotaPreview, + shareButtonState, + shareErrorKey, + shareFailureKey, + shareFor, + shareFormatOptions, + sharePasswordError, + shareRowActions, +} from './shares.ts'; + +const DAY = 24 * 60 * 60 * 1000; +const NOW = Date.parse('2026-10-26T12:00:00Z'); +const at = (days) => new Date(NOW + days * DAY).toISOString(); + +const run = { formats: ['mp4', 'gif'], artifactsDeletedAt: null }; +const machine = { online: true, features: ['share'] }; + +test('the Share button is enabled for a rendered run on an online machine that shares', () => { + assert.equal(shareButtonState(run, machine), 'ready'); +}); + +test('a run without a render cannot be shared', () => { + assert.equal(shareButtonState({ ...run, formats: [] }, machine), 'noRender'); +}); + +test('a run whose files were deleted cannot be shared', () => { + assert.equal( + shareButtonState({ ...run, artifactsDeletedAt: at(-1) }, machine), + 'deleted', + ); +}); + +test('a run whose machine was removed cannot be shared', () => { + assert.equal(shareButtonState(run, null), 'removed'); +}); + +test('a run on an offline machine cannot be shared', () => { + assert.equal(shareButtonState(run, { ...machine, online: false }), 'offline'); +}); + +test('a machine that does not announce share must be updated first', () => { + assert.equal( + shareButtonState(run, { online: true, features: [] }), + 'outdated', + ); + assert.equal(shareButtonState(run, { online: true }), 'outdated'); +}); + +test('format options carry their size and mark a render over the limit', () => { + const renders = [ + { format: 'mp4', width: 1, height: 1, sizeBytes: 300, durationMs: 1 }, + { format: 'gif', width: 1, height: 1, sizeBytes: 100, durationMs: 1 }, + ]; + assert.deepEqual(shareFormatOptions(['mp4', 'gif', 'webm'], renders, 200), [ + { format: 'mp4', sizeBytes: 300, tooLarge: true }, + { format: 'gif', sizeBytes: 100, tooLarge: false }, + { format: 'webm', sizeBytes: null, tooLarge: false }, + ]); +}); + +test('the default format is the first one that fits', () => { + assert.equal( + defaultShareFormat([ + { format: 'mp4', sizeBytes: 300, tooLarge: true }, + { format: 'gif', sizeBytes: 100, tooLarge: false }, + ]), + 'gif', + ); + assert.equal( + defaultShareFormat([{ format: 'mp4', sizeBytes: 300, tooLarge: true }]), + 'mp4', + ); + assert.equal(defaultShareFormat([]), null); +}); + +test('the quota preview adds the share and says whether it fits', () => { + const quota = { usedBytes: 700, limitBytes: 1000 }; + assert.deepEqual(quotaPreview(quota, 300), { + usedBytes: 700, + afterBytes: 1000, + limitBytes: 1000, + fits: true, + }); + assert.equal(quotaPreview(quota, 301).fits, false); + assert.equal(quotaPreview(quota).afterBytes, 700); + assert.equal(quotaPreview(quota, null).fits, true); +}); + +test('the run already shared in a format finds that share', () => { + const shares = [ + { id: 'a', runId: 'r1', format: 'gif' }, + { id: 'b', runId: 'r1', format: 'mp4' }, + { id: 'c', runId: 'r2', format: 'mp4' }, + ]; + assert.equal(shareFor(shares, 'r1', 'mp4')?.id, 'b'); + assert.equal(shareFor(shares, 'r2', 'gif'), null); +}); + +test('days left round up and stop at zero', () => { + assert.equal(daysLeft(at(30), NOW), 30); + assert.equal(daysLeft(at(0.2), NOW), 1); + assert.equal(daysLeft(at(-2), NOW), 0); +}); + +test('Extend is offered below the 90-day cap and hidden at it', () => { + assert.equal(canExtend({ status: 'ready', expiresAt: at(30) }, NOW), true); + assert.equal(canExtend({ status: 'ready', expiresAt: at(89) }, NOW), true); + assert.equal(canExtend({ status: 'ready', expiresAt: at(89.5) }, NOW), false); + assert.equal(canExtend({ status: 'ready', expiresAt: at(90) }, NOW), false); +}); + +test('a failed or lost share cannot be extended', () => { + assert.equal(canExtend({ status: 'failed', expiresAt: at(7) }, NOW), false); + assert.equal(canExtend({ status: 'lost', expiresAt: at(7) }, NOW), false); +}); + +test('row actions follow the status', () => { + assert.deepEqual( + shareRowActions({ status: 'ready', expiresAt: at(30) }, NOW), + { + copy: true, + open: true, + extend: true, + revoke: true, + retry: false, + }, + ); + assert.deepEqual( + shareRowActions({ status: 'failed', expiresAt: at(30) }, NOW), + { copy: false, open: false, extend: false, revoke: true, retry: true }, + ); + assert.deepEqual( + shareRowActions({ status: 'lost', expiresAt: at(30) }, NOW), + { + copy: false, + open: false, + extend: false, + revoke: true, + retry: false, + }, + ); +}); + +test('a password is optional, 8 to 128 characters, never trimmed', () => { + assert.equal(sharePasswordError(''), null); + assert.equal( + sharePasswordError('1234567'), + 'shares.dialog.password.tooShort', + ); + assert.equal(sharePasswordError('12345678'), null); + assert.equal(sharePasswordError(' a '), null); + assert.equal( + sharePasswordError('x'.repeat(129)), + 'shares.dialog.password.tooLong', + ); +}); + +test('each refusal of the API has its own message', () => { + assert.equal(shareErrorKey('quota-exceeded'), 'shares.errors.quotaExceeded'); + assert.equal(shareErrorKey('file-too-large'), 'shares.errors.fileTooLarge'); + assert.equal(shareErrorKey('runner-offline'), 'shares.errors.runnerOffline'); + assert.equal( + shareErrorKey('runner-outdated'), + 'shares.errors.runnerOutdated', + ); + assert.equal(shareErrorKey('something-new'), 'shares.errors.unknown'); + assert.equal(shareErrorKey(undefined), 'shares.errors.unknown'); +}); + +test('an upload failure is said in words, an unknown one generically', () => { + assert.equal(shareFailureKey('timed-out'), 'shares.failure.timedOut'); + assert.equal(shareFailureKey('error'), 'shares.failure.unknown'); + assert.equal(shareFailureKey(null), 'shares.failure.unknown'); +}); + +test('the Markdown snippet escapes brackets in the title', () => { + assert.equal( + markdownSnippet('Sign in [beta]', 'https://x/s/t/file'), + '![Sign in \\[beta\\]](https://x/s/t/file)', + ); +}); diff --git a/apps/web/src/lib/shares.ts b/apps/web/src/lib/shares.ts new file mode 100644 index 00000000..de80d8c9 --- /dev/null +++ b/apps/web/src/lib/shares.ts @@ -0,0 +1,275 @@ +// The owner's share links on the website (spec #350, API from spec #347). Pure, +// so `node --test` runs it as it is: no React, no Node APIs, type imports +// only. The calls live in `shares-client.ts`. + +import type { RunDetail, RunRender } from './api'; + +export type ShareStatus = 'uploading' | 'ready' | 'failed' | 'lost'; + +/** What the owner sees of a share (`ShareView` in the API). */ +export interface Share { + id: string; + url: string; + /** Null while a password is set: the file is served only after unlocking. */ + fileUrl: string | null; + runId: string; + projectId: string; + title: string; + format: string; + status: ShareStatus; + failure: string | null; + sizeBytes: number; + width: number | null; + height: number | null; + durationMs: number | null; + hasPassword: boolean; + views: number; + expiresAt: string; + createdAt: string; +} + +export interface ShareQuota { + usedBytes: number; + limitBytes: number; + maxFileBytes: number; +} + +export interface SharesList { + shares: Share[]; + quota: ShareQuota; +} + +/** A share's lifetime in days (spec #347, Decision 5). */ +export const SHARE_LIFETIMES = [7, 30, 90] as const; +export type ShareLifetime = (typeof SHARE_LIFETIMES)[number]; +export const DEFAULT_SHARE_LIFETIME: ShareLifetime = 30; + +export const SHARE_PASSWORD_MIN = 8; +export const SHARE_PASSWORD_MAX = 128; + +/** Extend adds this much, never beyond `SHARE_MAX_DAYS` from now. */ +export const SHARE_EXTEND_DAYS = 30; +export const SHARE_MAX_DAYS = 90; + +/** How often the dialog asks again while a share uploads (Decision 2). */ +export const SHARE_POLL_MS = 1000; + +const DAY_MS = 24 * 60 * 60 * 1000; + +/** Why the Share button is disabled, or `ready` when it is not (Decision 1). */ +export type ShareButtonState = + | 'ready' + | 'noRender' + | 'deleted' + | 'removed' + | 'offline' + | 'outdated'; + +export function shareButtonState( + run: { formats: readonly string[]; artifactsDeletedAt: string | null }, + machine: Pick< + NonNullable<RunDetail['machine']>, + 'online' | 'features' + > | null, +): ShareButtonState { + if (run.formats.length === 0) return 'noRender'; + if (run.artifactsDeletedAt !== null) return 'deleted'; + if (machine === null) return 'removed'; + if (!machine.online) return 'offline'; + if (!machine.features?.includes('share')) return 'outdated'; + return 'ready'; +} + +export interface ShareFormatOption { + format: string; + /** Null when the CLI did not report the file's size. */ + sizeBytes: number | null; + tooLarge: boolean; +} + +/** + * The formats the dialog offers, in the order given, each with its size from + * the run's renders. A render over `maxFileBytes` cannot be shared. + */ +export function shareFormatOptions( + formats: readonly string[], + renders: readonly RunRender[] | null, + maxFileBytes: number, +): ShareFormatOption[] { + return formats.map((format) => { + const sizeBytes = + renders?.find((render) => render.format === format)?.sizeBytes ?? null; + return { + format, + sizeBytes, + tooLarge: sizeBytes !== null && sizeBytes > maxFileBytes, + }; + }); +} + +/** The first format that can be shared, else the first; null when none. */ +export function defaultShareFormat( + options: readonly ShareFormatOption[], +): string | null { + return ( + options.find((option) => !option.tooLarge)?.format ?? + options[0]?.format ?? + null + ); +} + +export interface QuotaPreview { + usedBytes: number; + /** What the quota would hold with the new share; equals used when none. */ + afterBytes: number; + limitBytes: number; + fits: boolean; +} + +/** The quota with `addBytes` more; an unknown size adds nothing (the API checks it). */ +export function quotaPreview( + quota: Pick<ShareQuota, 'usedBytes' | 'limitBytes'>, + addBytes: number | null = null, +): QuotaPreview { + const afterBytes = quota.usedBytes + (addBytes ?? 0); + return { + usedBytes: quota.usedBytes, + afterBytes, + limitBytes: quota.limitBytes, + fits: afterBytes <= quota.limitBytes, + }; +} + +/** The run's share for `format`, whatever its status: one per run and format. */ +export function shareFor( + shares: readonly Share[], + runId: string, + format: string, +): Share | null { + return ( + shares.find((share) => share.runId === runId && share.format === format) ?? + null + ); +} + +/** Whole days until the share expires, rounded up; 0 once it has. */ +export function daysLeft(expiresAt: string, now: number): number { + return Math.max(0, Math.ceil((Date.parse(expiresAt) - now) / DAY_MS)); +} + +/** + * Extend is offered while it would add at least a day: the API caps the expiry + * at 90 days from now and answers `at-max-expiry` beyond it. + */ +export function canExtend( + share: Pick<Share, 'status' | 'expiresAt'>, + now: number, +): boolean { + if (share.status !== 'ready' && share.status !== 'uploading') return false; + return now + SHARE_MAX_DAYS * DAY_MS - Date.parse(share.expiresAt) >= DAY_MS; +} + +export interface ShareRowActions { + copy: boolean; + open: boolean; + extend: boolean; + revoke: boolean; + /** A failed upload is tried again from the run page. */ + retry: boolean; +} + +/** What a row of `/app/shares` offers (Decision 3). */ +export function shareRowActions( + share: Pick<Share, 'status' | 'expiresAt'>, + now: number, +): ShareRowActions { + const ready = share.status === 'ready'; + return { + copy: ready, + open: ready, + extend: canExtend(share, now), + revoke: true, + retry: share.status === 'failed', + }; +} + +export type SharePasswordError = + | 'shares.dialog.password.tooShort' + | 'shares.dialog.password.tooLong'; + +/** An empty password is none; a set one is taken as typed, never trimmed. */ +export function sharePasswordError(value: string): SharePasswordError | null { + if (value === '') return null; + if (value.length < SHARE_PASSWORD_MIN) { + return 'shares.dialog.password.tooShort'; + } + if (value.length > SHARE_PASSWORD_MAX) { + return 'shares.dialog.password.tooLong'; + } + return null; +} + +export type ShareErrorKey = + | 'shares.errors.quotaExceeded' + | 'shares.errors.fileTooLarge' + | 'shares.errors.runnerOffline' + | 'shares.errors.runnerOutdated' + | 'shares.errors.artifactsDeleted' + | 'shares.errors.formatNotRendered' + | 'shares.errors.notFound' + | 'shares.errors.atMaxExpiry' + | 'shares.errors.unknown'; + +const ERRORS: Readonly<Record<string, ShareErrorKey>> = { + 'quota-exceeded': 'shares.errors.quotaExceeded', + 'file-too-large': 'shares.errors.fileTooLarge', + 'runner-offline': 'shares.errors.runnerOffline', + 'runner-outdated': 'shares.errors.runnerOutdated', + 'artifacts-deleted': 'shares.errors.artifactsDeleted', + 'format-not-rendered': 'shares.errors.formatNotRendered', + 'not-found': 'shares.errors.notFound', + 'at-max-expiry': 'shares.errors.atMaxExpiry', +}; + +/** The message for an API answer's `{ error }` code; anything else is generic. */ +export function shareErrorKey(code: string | undefined): ShareErrorKey { + return ( + (code === undefined ? undefined : ERRORS[code]) ?? 'shares.errors.unknown' + ); +} + +export type ShareFailureKey = + | 'shares.failure.runnerOffline' + | 'shares.failure.runnerTimeout' + | 'shares.failure.runnerBusy' + | 'shares.failure.fileTooLarge' + | 'shares.failure.quotaExceeded' + | 'shares.failure.timedOut' + | 'shares.failure.unknown'; + +const FAILURES: Readonly<Record<string, ShareFailureKey>> = { + 'runner-offline': 'shares.failure.runnerOffline', + 'runner-timeout': 'shares.failure.runnerTimeout', + 'runner-busy': 'shares.failure.runnerBusy', + 'file-too-large': 'shares.failure.fileTooLarge', + 'quota-exceeded': 'shares.failure.quotaExceeded', + 'timed-out': 'shares.failure.timedOut', +}; + +/** Why a `failed` share's upload stopped, in words. */ +export function shareFailureKey(failure: string | null): ShareFailureKey { + return ( + (failure === null ? undefined : FAILURES[failure]) ?? + 'shares.failure.unknown' + ); +} + +/** `![title](fileUrl)`, with the title's brackets escaped, for a GIF. */ +export function markdownSnippet(title: string, fileUrl: string): string { + return `![${title.replace(/[[\]\\]/g, '\\$&')}](${fileUrl})`; +} + +/** A GIF gets the Markdown snippet; a video does not. */ +export function isGifShare(format: string): boolean { + return format.startsWith('gif'); +} From 8ded0bbef77a0755315788ba66c792f0da5601de Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 19:24:20 +0100 Subject: [PATCH 56/71] feat(web): Share dialog on the run page and the /app/shares list The run page header gets a Share button that opens a dialog for format, expiry, an optional password and the quota preview, then polls the upload every second and shows the link. /app/shares lists every share with its views and expiry, and offers Copy link, Open, Extend 30 days and Revoke. The sidebar and the breadcrumbs gain a Shares entry. --- .../app/projects/[id]/runs/[runId]/page.tsx | 12 + apps/web/src/app/app/shares/page.tsx | 26 ++ .../web/src/components/shares/copy-button.tsx | 56 +++ .../web/src/components/shares/quota-meter.tsx | 38 ++ .../src/components/shares/share-button.tsx | 68 +++ .../src/components/shares/share-dialog.tsx | 432 ++++++++++++++++++ apps/web/src/components/shares/share-list.tsx | 302 ++++++++++++ apps/web/src/components/shell/sidebar.tsx | 2 + apps/web/src/components/shell/top-bar.tsx | 1 + apps/web/src/i18n/en.ts | 115 +++++ apps/web/src/lib/crumbs.test.mjs | 2 + apps/web/src/lib/crumbs.ts | 2 + apps/web/src/lib/nav.ts | 16 +- 13 files changed, 1070 insertions(+), 2 deletions(-) create mode 100644 apps/web/src/app/app/shares/page.tsx create mode 100644 apps/web/src/components/shares/copy-button.tsx create mode 100644 apps/web/src/components/shares/quota-meter.tsx create mode 100644 apps/web/src/components/shares/share-button.tsx create mode 100644 apps/web/src/components/shares/share-dialog.tsx create mode 100644 apps/web/src/components/shares/share-list.tsx diff --git a/apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx b/apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx index 9a018f39..5e7efe55 100644 --- a/apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx +++ b/apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx @@ -13,6 +13,7 @@ import { RunStages, } from '@/components/projects/run-details'; import { RunStatus } from '@/components/projects/run-status'; +import { ShareButton } from '@/components/shares/share-button'; import { CrumbName } from '@/components/shell/crumb-names'; import { t } from '@/i18n'; import { formatDate } from '@/lib/format-date'; @@ -127,6 +128,17 @@ export default async function RunPage({ </span> } description={project.name} + actions={ + <ShareButton + run={{ + id: run.id, + formats: run.formats, + renders: run.renders, + artifactsDeletedAt: run.artifactsDeletedAt, + }} + machine={machine} + /> + } /> <RunPlayback runId={run.id} diff --git a/apps/web/src/app/app/shares/page.tsx b/apps/web/src/app/app/shares/page.tsx new file mode 100644 index 00000000..bf014d74 --- /dev/null +++ b/apps/web/src/app/app/shares/page.tsx @@ -0,0 +1,26 @@ +import { Banner } from '@andrewbehma/glass-ui/banner'; +import { PageHeader } from '@andrewbehma/glass-ui/page-header'; +import { cookies } from 'next/headers'; +import { ShareList } from '@/components/shares/share-list'; +import { t } from '@/i18n'; +import { apiUrl } from '@/lib/session'; +import { listShares } from '@/lib/shares-client'; + +/** The signed-in user's shares and quota (spec #350, Decision 3). */ +export default async function SharesPage() { + const cookie = (await cookies()).toString(); + const result = await listShares({ baseUrl: apiUrl(), cookie }); + return ( + <> + <PageHeader + title={t('shares.title')} + description={t('shares.description')} + /> + {result.ok ? ( + <ShareList initial={result.data} now={Date.now()} /> + ) : ( + <Banner tone="danger">{t('shares.loadFailed')}</Banner> + )} + </> + ); +} diff --git a/apps/web/src/components/shares/copy-button.tsx b/apps/web/src/components/shares/copy-button.tsx new file mode 100644 index 00000000..119dcfc4 --- /dev/null +++ b/apps/web/src/components/shares/copy-button.tsx @@ -0,0 +1,56 @@ +'use client'; + +import { Button } from '@andrewbehma/glass-ui/button'; +import { useEffect, useState } from 'react'; +import { t } from '@/i18n'; + +const RESET_MS = 2000; + +/** Writes `value` to the clipboard and says so for two seconds. */ +export function CopyButton({ + value, + label = t('shares.copy'), + size = 'sm', + variant = 'glass', +}: { + value: string; + /** The accessible name, when "Copy" alone would not say what is copied. */ + label?: string; + size?: 'sm' | 'md'; + variant?: 'glass' | 'ghost'; +}) { + const [state, setState] = useState<'idle' | 'copied' | 'failed'>('idle'); + + useEffect(() => { + if (state === 'idle') return; + const timer = setTimeout(() => setState('idle'), RESET_MS); + return () => clearTimeout(timer); + }, [state]); + + async function copy() { + try { + await navigator.clipboard.writeText(value); + setState('copied'); + } catch { + setState('failed'); + } + } + + return ( + <Button + type="button" + size={size} + variant={variant} + aria-label={label} + onClick={() => void copy()} + > + <span aria-live="polite"> + {state === 'copied' + ? t('shares.copied') + : state === 'failed' + ? t('shares.copyFailed') + : t('shares.copy')} + </span> + </Button> + ); +} diff --git a/apps/web/src/components/shares/quota-meter.tsx b/apps/web/src/components/shares/quota-meter.tsx new file mode 100644 index 00000000..4a7a9ea6 --- /dev/null +++ b/apps/web/src/components/shares/quota-meter.tsx @@ -0,0 +1,38 @@ +import { Progress } from '@andrewbehma/glass-ui/progress'; +import { t } from '@/i18n'; +import { formatBytes } from '@/lib/format-bytes'; +import { quotaPreview, type ShareQuota } from '@/lib/shares'; + +/** + * "`<used>` of `<limit>` used" (spec #350, Decision 2). With `addBytes` it + * previews the quota with a new share, and says so when it would not fit. + */ +export function QuotaMeter({ + quota, + addBytes = null, +}: { + quota: Pick<ShareQuota, 'usedBytes' | 'limitBytes'>; + addBytes?: number | null; +}) { + const preview = quotaPreview(quota, addBytes); + const used = formatBytes(preview.usedBytes); + const limit = formatBytes(preview.limitBytes); + const label = + addBytes === null + ? t('shares.quota.used', { used, limit }) + : t('shares.quota.preview', { + used, + limit, + after: formatBytes(preview.afterBytes), + }); + return ( + <Progress + aria-label={t('shares.quota.label')} + value={Math.min(preview.afterBytes, preview.limitBytes)} + max={Math.max(preview.limitBytes, 1)} + label={label} + hint={preview.fits ? undefined : t('shares.quota.noSpace')} + tone={preview.fits ? 'neutral' : 'danger'} + /> + ); +} diff --git a/apps/web/src/components/shares/share-button.tsx b/apps/web/src/components/shares/share-button.tsx new file mode 100644 index 00000000..2fa0f5e1 --- /dev/null +++ b/apps/web/src/components/shares/share-button.tsx @@ -0,0 +1,68 @@ +'use client'; + +import { Button } from '@andrewbehma/glass-ui/button'; +import { Share2 } from 'lucide-react'; +import { useState } from 'react'; +import { t } from '@/i18n'; +import type { RunDetail } from '@/lib/api'; +import { orderFormats } from '@/lib/playback'; +import { type ShareButtonState, shareButtonState } from '@/lib/shares'; +import { ShareDialog } from './share-dialog'; + +function hint(state: ShareButtonState, machine: string): string | null { + switch (state) { + case 'ready': + return null; + case 'outdated': + return t('shares.button.hints.outdated', { machine }); + default: + return t(`shares.button.hints.${state}`); + } +} + +/** + * "Share" in the run page's header (spec #350, Decision 1). Disabled, with the + * reason beside it, while the run has no render, its files are deleted, or its + * machine is gone, offline or too old to share. + */ +export function ShareButton({ + run, + machine, +}: { + run: Pick< + RunDetail['run'], + 'id' | 'formats' | 'renders' | 'artifactsDeletedAt' + >; + machine: RunDetail['machine']; +}) { + const [open, setOpen] = useState(false); + const state = shareButtonState(run, machine); + const reason = hint(state, machine?.name ?? ''); + const reasonId = `share-reason-${run.id}`; + return ( + <div className="flex flex-wrap items-center justify-end gap-3"> + {reason ? ( + <span id={reasonId} className="text-sm text-ink-2"> + {reason} + </span> + ) : null} + <Button + type="button" + variant="solid" + disabled={state !== 'ready'} + aria-describedby={reason ? reasonId : undefined} + onClick={() => setOpen(true)} + > + <Share2 className="size-4" aria-hidden="true" /> + {t('shares.button.open')} + </Button> + <ShareDialog + open={open} + onOpenChange={setOpen} + runId={run.id} + formats={orderFormats(run.formats)} + renders={run.renders} + /> + </div> + ); +} diff --git a/apps/web/src/components/shares/share-dialog.tsx b/apps/web/src/components/shares/share-dialog.tsx new file mode 100644 index 00000000..a09b4a69 --- /dev/null +++ b/apps/web/src/components/shares/share-dialog.tsx @@ -0,0 +1,432 @@ +'use client'; + +import { Banner } from '@andrewbehma/glass-ui/banner'; +import { Button, buttonClassName } from '@andrewbehma/glass-ui/button'; +import { Card } from '@andrewbehma/glass-ui/card'; +import { DialogContent, DialogRoot } from '@andrewbehma/glass-ui/dialog'; +import { Field, Input, Select } from '@andrewbehma/glass-ui/field'; +import { Spinner } from '@andrewbehma/glass-ui/spinner'; +import Link from 'next/link'; +import { useCallback, useEffect, useId, useRef, useState } from 'react'; +import { formatLabel } from '@/components/projects/format-choice'; +import { t } from '@/i18n'; +import type { RunRender } from '@/lib/api'; +import { formatBytes } from '@/lib/format-bytes'; +import { formatDuration } from '@/lib/format-duration'; +import { + DEFAULT_SHARE_LIFETIME, + daysLeft, + defaultShareFormat, + isGifShare, + markdownSnippet, + quotaPreview, + SHARE_LIFETIMES, + SHARE_POLL_MS, + type Share, + type ShareErrorKey, + type ShareLifetime, + type SharesList, + shareErrorKey, + shareFailureKey, + shareFor, + shareFormatOptions, + sharePasswordError, +} from '@/lib/shares'; +import { createShare, getShare, listShares } from '@/lib/shares-client'; +import { CopyButton } from './copy-button'; +import { QuotaMeter } from './quota-meter'; + +/** A read-only field with its Copy button. */ +function CopyField({ + label, + copyLabel, + value, +}: { + label: string; + copyLabel: string; + value: string; +}) { + const id = useId(); + return ( + <Field label={label} htmlFor={id}> + <div className="flex gap-2"> + <Input + id={id} + readOnly + value={value} + className="font-mono text-xs" + onFocus={(event) => event.currentTarget.select()} + /> + <CopyButton value={value} label={copyLabel} size="md" /> + </div> + </Field> + ); +} + +/** + * The Share dialog of the run page (spec #350, Decision 2): format, expiry, + * an optional password and the quota; then the upload's progress, polled + * every second, and the link. A run already shared in the chosen format shows + * that share instead of a second Create. Glass is the dialog's chrome only; + * its body sits on the readable content surface. + */ +export function ShareDialog({ + open, + onOpenChange, + runId, + formats, + renders, +}: { + open: boolean; + onOpenChange: (open: boolean) => void; + runId: string; + /** The run's formats, in display order. */ + formats: readonly string[]; + renders: readonly RunRender[] | null; +}) { + const [list, setList] = useState<SharesList | 'error' | null>(null); + const [format, setFormat] = useState<string | null>(null); + const [days, setDays] = useState<ShareLifetime>(DEFAULT_SHARE_LIFETIME); + const [password, setPassword] = useState(''); + const [current, setCurrent] = useState<Share | null>(null); + const [creating, setCreating] = useState(false); + const [error, setError] = useState<ShareErrorKey | undefined>(); + const [now, setNow] = useState(() => Date.now()); + const formatId = useId(); + const daysId = useId(); + const passwordId = useId(); + // Read on open only: a refresh of the page must not reset an open dialog. + const run = useRef({ formats, renders }); + run.current = { formats, renders }; + + const reload = useCallback(async (): Promise<SharesList | null> => { + const result = await listShares(); + if (!result.ok) { + setList('error'); + return null; + } + setList(result.data); + return result.data; + }, []); + + // Every open starts from the server's answer: shares change elsewhere. + useEffect(() => { + if (!open) return; + setList(null); + setError(undefined); + setPassword(''); + setDays(DEFAULT_SHARE_LIFETIME); + void reload().then((fresh) => { + if (!fresh) return; + const chosen = defaultShareFormat( + shareFormatOptions( + run.current.formats, + run.current.renders, + fresh.quota.maxFileBytes, + ), + ); + setFormat(chosen); + setCurrent( + chosen === null ? null : shareFor(fresh.shares, runId, chosen), + ); + }); + }, [open, reload, runId]); + + const uploadingId = current?.status === 'uploading' ? current.id : null; + + // No fake percentage: ask again every second while the upload runs. + useEffect(() => { + if (!open || uploadingId === null) return; + let cancelled = false; + let timer: ReturnType<typeof setTimeout>; + const poll = async () => { + const result = await getShare(uploadingId); + if (cancelled) return; + setNow(Date.now()); + if (result.ok) { + setCurrent(result.data); + if (result.data.status !== 'uploading') { + void reload(); + return; + } + } else if (result.status === 404) { + setCurrent(null); + void reload(); + return; + } + // A failed poll is tried again on the next tick. + timer = setTimeout(poll, SHARE_POLL_MS); + }; + timer = setTimeout(poll, SHARE_POLL_MS); + return () => { + cancelled = true; + clearTimeout(timer); + }; + }, [open, uploadingId, reload]); + + const loaded = list !== null && list !== 'error' ? list : null; + const options = loaded + ? shareFormatOptions(formats, renders, loaded.quota.maxFileBytes) + : []; + const option = options.find((candidate) => candidate.format === format); + const passwordError = sharePasswordError(password); + const fits = loaded + ? quotaPreview(loaded.quota, option?.sizeBytes ?? null).fits + : false; + const canCreate = + option !== undefined && + !option.tooLarge && + fits && + passwordError === null && + !creating; + + function chooseFormat(next: string) { + setFormat(next); + setError(undefined); + setCurrent(loaded ? shareFor(loaded.shares, runId, next) : null); + } + + async function create() { + if (!canCreate || format === null) return; + setCreating(true); + setError(undefined); + const result = await createShare({ + runId, + format, + expiresInDays: days, + ...(password === '' ? {} : { password }), + }); + setCreating(false); + if (result.ok) { + setPassword(''); + setNow(Date.now()); + setCurrent(result.data); + return; + } + if (result.code === 'share-exists') { + // Created in another tab meanwhile: show that one. + const fresh = await reload(); + setCurrent(fresh ? shareFor(fresh.shares, runId, format) : null); + return; + } + setError(shareErrorKey(result.code)); + if (result.code === 'quota-exceeded') void reload(); + } + + function body() { + if (list === 'error') { + return <Banner tone="danger">{t('shares.loadFailed')}</Banner>; + } + if (loaded === null) { + return ( + <div className="flex items-center gap-2 text-sm text-ink-2"> + <Spinner size="sm" label={null} /> + {t('shares.dialog.loading')} + </div> + ); + } + if (current?.status === 'uploading') { + const elapsed = Math.max(0, now - Date.parse(current.createdAt)); + return ( + <div className="flex flex-col items-center gap-3 py-4 text-center"> + <Spinner size="lg" label={t('shares.dialog.uploading')} /> + <p className="font-medium">{t('shares.dialog.uploading')}</p> + <p className="text-sm text-ink-2"> + {t('shares.dialog.uploadingDetail', { + size: + current.sizeBytes > 0 + ? formatBytes(current.sizeBytes) + : t('shares.dialog.unknownSize'), + elapsed: formatDuration(Math.round(elapsed / 1000) * 1000), + })} + </p> + </div> + ); + } + if (current?.status === 'ready') { + return ( + <div className="flex flex-col gap-4"> + <p className="text-sm"> + <span className="font-medium">{t('shares.dialog.ready')}</span>{' '} + {t('shares.dialog.expiresIn', { + days: daysLeft(current.expiresAt, Date.now()), + })} + </p> + <CopyField + label={t('shares.dialog.link')} + copyLabel={`${t('shares.copy')} ${t('shares.dialog.link')}`} + value={current.url} + /> + {current.fileUrl ? ( + <> + <CopyField + label={t('shares.dialog.fileLink')} + copyLabel={`${t('shares.copy')} ${t('shares.dialog.fileLink')}`} + value={current.fileUrl} + /> + {isGifShare(current.format) ? ( + <CopyField + label={t('shares.dialog.markdown')} + copyLabel={`${t('shares.copy')} ${t('shares.dialog.markdown')}`} + value={markdownSnippet(current.title, current.fileUrl)} + /> + ) : null} + </> + ) : ( + <p className="text-sm text-ink-2">{t('shares.dialog.protected')}</p> + )} + </div> + ); + } + if (current?.status === 'failed' || current?.status === 'lost') { + return ( + <Banner tone="danger"> + <span className="font-medium">{t('shares.failure.title')}</span>{' '} + {current.status === 'lost' + ? t('shares.lost') + : t(shareFailureKey(current.failure))} + </Banner> + ); + } + return ( + <form + id="share-form" + className="flex flex-col gap-4" + onSubmit={(event) => { + event.preventDefault(); + void create(); + }} + > + {error ? <Banner tone="danger">{t(error)}</Banner> : null} + <Field label={t('shares.dialog.format')} htmlFor={formatId}> + <Select + id={formatId} + value={format ?? ''} + onChange={(event) => chooseFormat(event.target.value)} + > + {options.map((candidate) => ( + <option + key={candidate.format} + value={candidate.format} + disabled={candidate.tooLarge} + > + {candidate.tooLarge + ? t('shares.dialog.overLimit', { + format: formatLabel(candidate.format), + limit: formatBytes(loaded.quota.maxFileBytes), + }) + : candidate.sizeBytes === null + ? formatLabel(candidate.format) + : t('shares.dialog.formatSize', { + format: formatLabel(candidate.format), + size: formatBytes(candidate.sizeBytes), + })} + </option> + ))} + </Select> + </Field> + <Field label={t('shares.dialog.expires')} htmlFor={daysId}> + <Select + id={daysId} + value={String(days)} + onChange={(event) => { + const next = SHARE_LIFETIMES.find( + (lifetime) => String(lifetime) === event.target.value, + ); + if (next) setDays(next); + }} + > + {SHARE_LIFETIMES.map((lifetime) => ( + <option key={lifetime} value={lifetime}> + {t('shares.dialog.days', { days: lifetime })} + </option> + ))} + </Select> + </Field> + <Field + label={t('shares.dialog.password.label')} + htmlFor={passwordId} + hint={t('shares.dialog.password.hint')} + error={passwordError ? t(passwordError) : undefined} + > + <Input + id={passwordId} + type="password" + autoComplete="new-password" + value={password} + onChange={(event) => setPassword(event.target.value)} + /> + </Field> + <QuotaMeter quota={loaded.quota} addBytes={option?.sizeBytes ?? 0} /> + </form> + ); + } + + function footer() { + const close = ( + <Button type="button" variant="ghost" onClick={() => onOpenChange(false)}> + {t('shares.dialog.close')} + </Button> + ); + if (loaded === null) return close; + if (current?.status === 'uploading') return close; + if (current?.status === 'ready') { + return ( + <> + <Link + href="/app/shares" + className={buttonClassName({ variant: 'ghost' })} + > + {t('shares.dialog.manage')} + </Link> + {close} + </> + ); + } + if (current?.status === 'failed' || current?.status === 'lost') { + return ( + <> + {close} + <Button + type="button" + variant="solid" + onClick={() => { + // Create replaces a failed or lost share (spec #347). + setCurrent(null); + setError(undefined); + }} + > + {t('shares.dialog.tryAgain')} + </Button> + </> + ); + } + return ( + <> + {close} + <Button + type="submit" + form="share-form" + variant="solid" + disabled={!canCreate} + > + {creating ? t('shares.dialog.creating') : t('shares.dialog.create')} + </Button> + </> + ); + } + + return ( + <DialogRoot open={open} onOpenChange={onOpenChange}> + <DialogContent + title={t('shares.dialog.title')} + description={t('shares.dialog.notice')} + footer={footer()} + > + <Card variant="content" pad="md"> + {body()} + </Card> + </DialogContent> + </DialogRoot> + ); +} diff --git a/apps/web/src/components/shares/share-list.tsx b/apps/web/src/components/shares/share-list.tsx new file mode 100644 index 00000000..77988575 --- /dev/null +++ b/apps/web/src/components/shares/share-list.tsx @@ -0,0 +1,302 @@ +'use client'; + +import { Banner } from '@andrewbehma/glass-ui/banner'; +import { Button, buttonClassName } from '@andrewbehma/glass-ui/button'; +import { Card } from '@andrewbehma/glass-ui/card'; +import { ConfirmDialog } from '@andrewbehma/glass-ui/confirm-dialog'; +import { EmptyState } from '@andrewbehma/glass-ui/empty-state'; +import { StatusPill } from '@andrewbehma/glass-ui/status-pill'; +import { + Table, + TableCell, + TableHead, + TableRow, +} from '@andrewbehma/glass-ui/table'; +import Link from 'next/link'; +import { useRouter } from 'next/navigation'; +import { useEffect, useState } from 'react'; +import { formatLabel } from '@/components/projects/format-choice'; +import { CellLabel, stacked } from '@/components/projects/stacked-rows'; +import { t } from '@/i18n'; +import { formatBytes } from '@/lib/format-bytes'; +import { formatDate } from '@/lib/format-date'; +import { + daysLeft, + type Share, + type ShareErrorKey, + type ShareStatus, + type SharesList, + shareErrorKey, + shareFailureKey, + shareRowActions, +} from '@/lib/shares'; +import { extendShare, revokeShare } from '@/lib/shares-client'; +import { CopyButton } from './copy-button'; +import { QuotaMeter } from './quota-meter'; + +/** While a row uploads, the list asks the server again this often. */ +const REFRESH_MS = 3000; + +const PILL: Record<ShareStatus, 'running' | 'done' | 'error' | 'paused'> = { + uploading: 'running', + ready: 'done', + failed: 'error', + lost: 'paused', +}; + +function runHref(share: Share): string { + return `/app/projects/${encodeURIComponent(share.projectId)}/runs/${encodeURIComponent(share.runId)}`; +} + +/** + * `/app/shares` (spec #350, Decision 3): the quota, then every share, newest + * first, with Copy link, Open, Extend 30 days and Revoke per row. The table + * sits on the readable content surface. + */ +export function ShareList({ + initial, + now, +}: { + initial: SharesList; + /** The server's clock at render, so hydration counts the same days. */ + now: number; +}) { + const router = useRouter(); + const [shares, setShares] = useState(initial.shares); + const [busy, setBusy] = useState<string | null>(null); + const [revoking, setRevoking] = useState<Share | null>(null); + const [error, setError] = useState<ShareErrorKey | undefined>(); + + // A refresh brings the server's list: it wins over the local edits. + useEffect(() => setShares(initial.shares), [initial.shares]); + + const uploading = shares.some((share) => share.status === 'uploading'); + useEffect(() => { + if (!uploading) return; + const timer = setInterval(() => router.refresh(), REFRESH_MS); + return () => clearInterval(timer); + }, [uploading, router]); + + async function extend(share: Share) { + setBusy(share.id); + setError(undefined); + const result = await extendShare(share.id); + setBusy(null); + if (result.ok) { + setShares((rows) => + rows.map((row) => (row.id === share.id ? result.data : row)), + ); + } else { + setError(shareErrorKey(result.code)); + } + router.refresh(); + } + + async function revoke(share: Share) { + setBusy(share.id); + setError(undefined); + const result = await revokeShare(share.id); + setBusy(null); + setRevoking(null); + // A 404 is a share already gone: the state the owner asked for. + if (result.ok || result.status === 404) { + setShares((rows) => rows.filter((row) => row.id !== share.id)); + } else { + setError(shareErrorKey(result.code)); + } + router.refresh(); + } + + return ( + <div className="flex flex-col gap-4"> + <Card variant="content" pad="md"> + <QuotaMeter quota={initial.quota} /> + </Card> + {error ? <Banner tone="danger">{t(error)}</Banner> : null} + {shares.length === 0 ? ( + <EmptyState + title={t('shares.empty.title')} + description={t('shares.empty.body')} + action={ + <Link + href="/app/projects" + className={buttonClassName({ variant: 'glass' })} + > + {t('shares.empty.action')} + </Link> + } + /> + ) : ( + <Card variant="content" pad="sm"> + <Table className={stacked.table}> + <TableHead className={stacked.head}> + <tr> + <TableCell head scope="col"> + {t('shares.columns.title')} + </TableCell> + <TableCell head scope="col"> + {t('shares.columns.format')} + </TableCell> + <TableCell head scope="col"> + {t('shares.columns.size')} + </TableCell> + <TableCell head scope="col"> + {t('shares.columns.views')} + </TableCell> + <TableCell head scope="col"> + {t('shares.columns.expires')} + </TableCell> + <TableCell head scope="col"> + {t('shares.columns.password')} + </TableCell> + <TableCell head scope="col"> + {t('shares.columns.status')} + </TableCell> + <TableCell head scope="col"> + <span className="sr-only">{t('shares.columns.actions')}</span> + </TableCell> + </tr> + </TableHead> + <tbody className={stacked.body}> + {shares.map((share) => { + const actions = shareRowActions(share, now); + const days = daysLeft(share.expiresAt, now); + return ( + <TableRow + key={share.id} + className={stacked.row} + data-share-id={share.id} + > + <TableCell className={stacked.lead}> + <Link + href={runHref(share)} + className="break-words font-medium text-ink hover:underline" + > + {share.title} + </Link> + {share.status === 'failed' ? ( + <span className="block text-xs text-danger"> + {t(shareFailureKey(share.failure))} + </span> + ) : null} + {share.status === 'lost' ? ( + <span className="block text-xs text-danger"> + {t('shares.lost')} + </span> + ) : null} + </TableCell> + <TableCell className={stacked.cell}> + <CellLabel>{t('shares.columns.format')}</CellLabel> + {formatLabel(share.format)} + </TableCell> + <TableCell className={stacked.cell}> + <CellLabel>{t('shares.columns.size')}</CellLabel> + {formatBytes(share.sizeBytes)} + </TableCell> + <TableCell className={stacked.cell}> + <CellLabel>{t('shares.columns.views')}</CellLabel> + {share.views} + </TableCell> + <TableCell className={stacked.cell}> + <CellLabel>{t('shares.columns.expires')}</CellLabel> + <time + dateTime={share.expiresAt} + title={formatDate(share.expiresAt)} + > + {days > 0 + ? t('shares.expiresIn', { days }) + : t('shares.expiresToday')} + </time> + </TableCell> + <TableCell className={stacked.cell}> + <CellLabel>{t('shares.columns.password')}</CellLabel> + {share.hasPassword ? t('shares.yes') : t('shares.no')} + </TableCell> + <TableCell className={stacked.cell}> + <CellLabel>{t('shares.columns.status')}</CellLabel> + <StatusPill + size="sm" + status={PILL[share.status]} + label={t(`shares.status.${share.status}`)} + /> + </TableCell> + <TableCell className={stacked.cell}> + <div className="flex flex-wrap gap-2 md:justify-end"> + {actions.copy ? ( + <CopyButton + value={share.url} + label={`${t('shares.copy')} ${t('shares.dialog.link')}`} + /> + ) : null} + {actions.open ? ( + <a + href={share.url} + target="_blank" + rel="noreferrer" + className={buttonClassName({ + variant: 'ghost', + size: 'sm', + })} + > + {t('shares.open')} + </a> + ) : null} + {actions.extend ? ( + <Button + type="button" + variant="ghost" + size="sm" + disabled={busy === share.id} + onClick={() => void extend(share)} + > + {busy === share.id + ? t('shares.extending') + : t('shares.extend')} + </Button> + ) : null} + {actions.retry ? ( + <Link + href={runHref(share)} + className={buttonClassName({ + variant: 'ghost', + size: 'sm', + })} + > + {t('shares.retry')} + </Link> + ) : null} + <Button + type="button" + variant="danger" + size="sm" + disabled={busy === share.id} + onClick={() => setRevoking(share)} + > + {t('shares.revoke')} + </Button> + </div> + </TableCell> + </TableRow> + ); + })} + </tbody> + </Table> + </Card> + )} + <ConfirmDialog + open={revoking !== null} + onOpenChange={(open) => { + if (!open) setRevoking(null); + }} + title={t('shares.revokeTitle', { title: revoking?.title ?? '' })} + consequence={t('shares.revokeBody')} + verb={t('shares.revoke')} + cancelLabel={t('shares.revokeCancel')} + busy={revoking !== null && busy === revoking.id} + onConfirm={() => { + if (revoking) void revoke(revoking); + }} + /> + </div> + ); +} diff --git a/apps/web/src/components/shell/sidebar.tsx b/apps/web/src/components/shell/sidebar.tsx index 620e5c29..ded356b3 100644 --- a/apps/web/src/components/shell/sidebar.tsx +++ b/apps/web/src/components/shell/sidebar.tsx @@ -7,6 +7,7 @@ import { type LucideIcon, Server, Settings, + Share2, } from 'lucide-react'; import Link from 'next/link'; import { Logo } from '@/components/brand/logo'; @@ -19,6 +20,7 @@ const ICONS: Record<NavIcon, LucideIcon> = { overview: LayoutDashboard, projects: FolderKanban, machines: Server, + shares: Share2, settings: Settings, }; diff --git a/apps/web/src/components/shell/top-bar.tsx b/apps/web/src/components/shell/top-bar.tsx index d4ee4756..fec5ce1b 100644 --- a/apps/web/src/components/shell/top-bar.tsx +++ b/apps/web/src/components/shell/top-bar.tsx @@ -23,6 +23,7 @@ function crumbLabels(): Record<CrumbKind, string> { project: t('app.shell.crumbs.project'), run: t('app.shell.crumbs.run'), machines: t('app.shell.nav.machines'), + shares: t('app.shell.nav.shares'), settings: t('app.shell.nav.settings'), device: t('app.shell.crumbs.device'), }; diff --git a/apps/web/src/i18n/en.ts b/apps/web/src/i18n/en.ts index ff496db2..9d275595 100644 --- a/apps/web/src/i18n/en.ts +++ b/apps/web/src/i18n/en.ts @@ -21,6 +21,7 @@ export const en = { overview: 'Overview', projects: 'Projects', machines: 'Machines', + shares: 'Shares', settings: 'Settings', }, crumbs: { @@ -582,6 +583,120 @@ export const en = { locked: 'A shared DemoFlow video', }, }, + // The owner's share links (spec #350). + shares: { + title: 'Shares', + description: + 'Links to runs you shared. Anyone with a link can watch until it expires.', + loadFailed: 'We could not load your shares. Try again in a moment.', + quota: { + label: 'Share storage', + used: '{used} of {limit} used', + preview: '{used} of {limit} used, {after} with this share', + noSpace: 'Not enough space', + }, + button: { + open: 'Share', + hints: { + noRender: 'This run rendered no video to share.', + deleted: 'The video files were deleted on the machine.', + removed: 'The machine that recorded this run was removed.', + offline: 'The machine is offline.', + outdated: 'Update DemoFlow on {machine} to share.', + }, + }, + dialog: { + title: 'Share this run', + notice: + "The file is uploaded to DemoFlow's server. Anyone with the link can watch it until it expires.", + loading: 'Loading…', + format: 'Format', + formatSize: '{format} · {size}', + overLimit: '{format} · over {limit}', + expires: 'Expires in', + days: '{days} days', + password: { + label: 'Password (optional)', + hint: 'While a password is set, there is no direct file link.', + tooShort: 'At least 8 characters.', + tooLong: 'At most 128 characters.', + }, + create: 'Create link', + creating: 'Creating…', + close: 'Close', + uploading: 'Uploading to DemoFlow…', + uploadingDetail: '{size} · {elapsed}', + unknownSize: 'Size unknown', + ready: 'The link is ready.', + link: 'Link', + fileLink: 'File link', + markdown: 'Markdown', + protected: 'Protected by a password: there is no direct file link.', + expiresIn: 'Expires in {days} days.', + tryAgain: 'Try again', + manage: 'Manage shares', + }, + copy: 'Copy', + copied: 'Copied', + copyFailed: 'Copy failed', + errors: { + quotaExceeded: + 'Not enough share storage. Revoke a share or wait for one to expire.', + fileTooLarge: 'This file is larger than the share limit.', + runnerOffline: 'The machine is offline. Start it and try again.', + runnerOutdated: 'Update DemoFlow on the machine to share.', + artifactsDeleted: 'The video files were deleted on the machine.', + formatNotRendered: 'This run did not render that format.', + notFound: 'This share no longer exists.', + atMaxExpiry: 'This share already expires as late as it can.', + unknown: 'Something went wrong. Try again in a moment.', + }, + failure: { + title: 'The upload failed', + runnerOffline: 'The machine went offline during the upload.', + runnerTimeout: 'The machine did not answer in time.', + runnerBusy: 'The machine was busy with another upload.', + fileTooLarge: 'The file is larger than the share limit.', + quotaExceeded: 'The file did not fit in your share storage.', + timedOut: 'The upload took longer than 15 minutes.', + unknown: 'The file could not be uploaded.', + }, + lost: 'The file is gone from the server. Share again.', + columns: { + title: 'Run', + format: 'Format', + size: 'Size', + views: 'Views', + expires: 'Expires', + password: 'Password', + status: 'Status', + actions: 'Actions', + }, + expiresIn: 'in {days} days', + expiresToday: 'today', + yes: 'Yes', + no: 'No', + status: { + uploading: 'Uploading', + ready: 'Ready', + failed: 'Failed', + lost: 'Lost', + }, + open: 'Open', + extend: 'Extend 30 days', + extending: 'Extending…', + retry: 'Retry from the run', + revoke: 'Revoke', + revokeTitle: 'Revoke the link to {title}?', + revokeBody: + 'The link stops working at once and the file is deleted from the server. This cannot be undone.', + revokeCancel: 'Keep', + empty: { + title: 'Shares of your runs', + body: "Create a share from a run's page: it gives you a link anyone can watch.", + action: 'Go to projects', + }, + }, meta: { title: 'DemoFlow', }, diff --git a/apps/web/src/lib/crumbs.test.mjs b/apps/web/src/lib/crumbs.test.mjs index 18e2d52d..1817f89c 100644 --- a/apps/web/src/lib/crumbs.test.mjs +++ b/apps/web/src/lib/crumbs.test.mjs @@ -8,6 +8,7 @@ const labels = { project: 'Project', run: 'Run', machines: 'Machines', + shares: 'Shares', settings: 'Settings', device: 'Pair a machine', }; @@ -26,6 +27,7 @@ test('each top-level page is its own crumb', () => { assert.deepEqual(trail('/app/projects'), ['Projects']); assert.deepEqual(trail('/app/machines'), ['Machines']); assert.deepEqual(trail('/app/settings'), ['Settings']); + assert.deepEqual(trail('/app/shares'), ['Shares']); assert.deepEqual(trail('/app/device'), ['Pair a machine']); }); diff --git a/apps/web/src/lib/crumbs.ts b/apps/web/src/lib/crumbs.ts index c3cdde44..adc96b62 100644 --- a/apps/web/src/lib/crumbs.ts +++ b/apps/web/src/lib/crumbs.ts @@ -5,6 +5,7 @@ export type CrumbKind = | 'project' | 'run' | 'machines' + | 'shares' | 'settings' | 'device'; @@ -21,6 +22,7 @@ export type CrumbNames = ReadonlyMap<string, string>; const SECTIONS: Readonly<Record<string, CrumbKind>> = { projects: 'projects', machines: 'machines', + shares: 'shares', settings: 'settings', device: 'device', }; diff --git a/apps/web/src/lib/nav.ts b/apps/web/src/lib/nav.ts index c60f0e42..d236f70e 100644 --- a/apps/web/src/lib/nav.ts +++ b/apps/web/src/lib/nav.ts @@ -3,10 +3,16 @@ type NavLabel = | 'app.shell.nav.overview' | 'app.shell.nav.projects' | 'app.shell.nav.machines' + | 'app.shell.nav.shares' | 'app.shell.nav.settings'; /** Names an icon the sidebar draws; kept out of this module so it stays pure. */ -export type NavIcon = 'overview' | 'projects' | 'machines' | 'settings'; +export type NavIcon = + | 'overview' + | 'projects' + | 'machines' + | 'shares' + | 'settings'; export interface NavItem { id: string; @@ -17,7 +23,7 @@ export interface NavItem { /** * The app's sidebar, in order (spec #373, Decision 2). A later page adds its - * entry here with one line; Shares arrives with #350. + * entry here with one line. */ export const NAV_ITEMS: readonly NavItem[] = [ { @@ -38,6 +44,12 @@ export const NAV_ITEMS: readonly NavItem[] = [ label: 'app.shell.nav.machines', icon: 'machines', }, + { + id: 'shares', + href: '/app/shares', + label: 'app.shell.nav.shares', + icon: 'shares', + }, { id: 'settings', href: '/app/settings', From a1fd702d943791b65c10b4ba466b25a641ca2a58 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 19:24:27 +0100 Subject: [PATCH 57/71] feat(renderer): write a render's scene cards to result.json as chapters planChapters takes the plan's scene cards at their output start, after the idle map and every earlier card, so a chapter lands where the card is drawn. The FFmpeg renderer records them on every format it writes (spec 349, Decision 1). --- packages/renderer/src/ffmpeg/index.ts | 24 +++- packages/renderer/src/renderer.ts | 20 +++ packages/renderer/test/plan/build.spec.ts | 2 + packages/renderer/test/plan/chapters.spec.ts | 136 +++++++++++++++++++ 4 files changed, 175 insertions(+), 7 deletions(-) create mode 100644 packages/renderer/test/plan/chapters.spec.ts diff --git a/packages/renderer/src/ffmpeg/index.ts b/packages/renderer/src/ffmpeg/index.ts index 0676636a..4ffb192c 100644 --- a/packages/renderer/src/ffmpeg/index.ts +++ b/packages/renderer/src/ffmpeg/index.ts @@ -1,5 +1,10 @@ import path from 'node:path'; -import { type Renderer, recordRender, renderPath } from '../renderer.ts'; +import { + planChapters, + type Renderer, + recordRender, + renderPath, +} from '../renderer.ts'; import { drawPlan } from './pipeline.ts'; /** @@ -15,12 +20,17 @@ export const ffmpegRenderer: Renderer = { format, file: renderPath(runDir, 'ffmpeg', format), })); - return recordRender(runDir, 'ffmpeg', files, () => - drawPlan( - path.resolve(runDir, plan.source.file), - plan, - files.map(({ file }) => file), - ), + return recordRender( + runDir, + 'ffmpeg', + files, + () => + drawPlan( + path.resolve(runDir, plan.source.file), + plan, + files.map(({ file }) => file), + ), + planChapters(plan), ); }, }; diff --git a/packages/renderer/src/renderer.ts b/packages/renderer/src/renderer.ts index f65deb5f..dcf6c2e0 100644 --- a/packages/renderer/src/renderer.ts +++ b/packages/renderer/src/renderer.ts @@ -1,7 +1,9 @@ import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises'; import path from 'node:path'; import { + type Chapter, deriveRunStatus, + MAX_CHAPTERS, type RenderFormat, type RenderOutput, type RunResult, @@ -51,6 +53,21 @@ export function renderPath( return path.join(runDir, 'render', `${renderer}.${EXTENSIONS[format]}`); } +/** + * The chapters of a plan (spec 349): one per scene card, at its start in + * output ms — after the idle map and every card before it, as drawn. The + * intro and the outro are not chapters. + */ +export function planChapters(plan: Pick<RenderPlan, 'cards'>): Chapter[] { + return plan.cards + .filter((card) => card.kind === 'scene' && card.title.trim() !== '') + .slice(0, MAX_CHAPTERS) + .map((card) => ({ + title: card.title.slice(0, 200), + atMs: Math.max(0, Math.round(card.startMs)), + })); +} + /** * Runs `draw`, which writes every one of `files`, and records them in the * run's `result.json`: the `rendering` stage goes `running` → `passed` (or @@ -58,12 +75,14 @@ export function renderPath( * `renders[]` entry per file, in order, replaces every earlier one of the * same renderer, and the run status is derived again (ADR-0004 §3). A file * that fails fails them all: a partial set is never a success (spec 133). + * `chapters`, when given, go on every entry: the formats share one timeline. */ export async function recordRender( runDir: string, renderer: string, files: readonly { format: RenderFormat; file: string }[], draw: () => Promise<void>, + chapters?: readonly Chapter[], ): Promise<RenderOutput[]> { await updateResult(runDir, (result) => { result.stages.rendering = { status: 'running', startedAt: timestamp() }; @@ -89,6 +108,7 @@ export async function recordRender( width: probe.width, height: probe.height, fps: probe.fps, + ...(chapters === undefined ? {} : { chapters: [...chapters] }), }); } await updateResult(runDir, (result) => { diff --git a/packages/renderer/test/plan/build.spec.ts b/packages/renderer/test/plan/build.spec.ts index fd747333..1fda79fb 100644 --- a/packages/renderer/test/plan/build.spec.ts +++ b/packages/renderer/test/plan/build.spec.ts @@ -363,6 +363,7 @@ describe.skipIf(!hasFfmpeg)('buildRenderPlan on real runs', () => { file, ]); }, + [{ title: 'Customers', atMs: 0 }], ); expect(output).toMatchObject({ renderer: 'probe', @@ -371,6 +372,7 @@ describe.skipIf(!hasFfmpeg)('buildRenderPlan on real runs', () => { width: 1920, height: 1080, fps: 30, + chapters: [{ title: 'Customers', atMs: 0 }], }); expect(output.sizeBytes).toBeGreaterThan(0); const mp4 = await probeVideo(file); diff --git a/packages/renderer/test/plan/chapters.spec.ts b/packages/renderer/test/plan/chapters.spec.ts new file mode 100644 index 00000000..601f0ec6 --- /dev/null +++ b/packages/renderer/test/plan/chapters.spec.ts @@ -0,0 +1,136 @@ +import { + type CardsConfig, + deriveRunStatus, + MAX_CHAPTERS, + type RunResult, + type Stages, + type TimelineEvent, +} from '@demoflow/core'; +import { describe, expect, it } from 'vitest'; +import { planChapters, planRender, type VideoProbe } from '../../src/index.ts'; + +function result(): RunResult { + const passed = { status: 'passed' as const }; + const stages: Stages = { + readiness: passed, + execution: passed, + verification: passed, + recording: passed, + rendering: { status: 'pending' }, + storage: { status: 'pending' }, + }; + return { + schemaVersion: 1, + runId: 'run', + scenarioId: 'inline', + scenarioName: 'Create a customer', + startedAt: '2026-10-18T10:00:00.000Z', + finishedAt: '2026-10-18T10:00:10.000Z', + status: deriveRunStatus(stages), + stages, + renders: [], + warnings: [], + }; +} + +const CARDS: CardsConfig = { + intro: { enabled: true, durationMs: 2000 }, + scenes: { enabled: true, durationMs: 1500 }, + outro: { title: 'Thanks', durationMs: 2500 }, +}; + +const scene = (atMs: number, title: string) => ({ + action: 'marker' as const, + startMs: atMs, + endMs: atMs, + marker: { title, kind: 'scene' as const }, +}); + +const wait = (startMs: number, endMs: number) => ({ + action: 'wait' as const, + startMs, + endMs, +}); + +function plan( + events: Omit<TimelineEvent, 'stepIndex'>[], + freezes: VideoProbe['freezes'] = [], + cards: CardsConfig = CARDS, +) { + return planRender( + { + timeline: { + schemaVersion: 1, + viewport: { width: 1280, height: 720 }, + deviceScaleFactor: 2, + videoFile: 'source.webm', + events: events.map((event, stepIndex) => ({ ...event, stepIndex })), + }, + result: result(), + source: { + width: 2560, + height: 1440, + fps: 25, + durationMs: 20_000, + codec: 'vp9', + freezes, + }, + }, + { offsetMs: 0, cards }, + ); +} + +describe('planChapters (spec 349)', () => { + it('gives one chapter per scene card, at its output start, without the intro and outro', () => { + const rendered = plan([scene(1000, 'Sign in'), scene(4000, 'Invoices')]); + expect(rendered.cards.map((card) => card.kind)).toEqual([ + 'intro', + 'scene', + 'scene', + 'outro', + ]); + // After the 2 s intro; the second also after the first 1.5 s scene card. + expect(planChapters(rendered)).toEqual([ + { title: 'Sign in', atMs: 3000 }, + { title: 'Invoices', atMs: 7500 }, + ]); + }); + + it('places a scene after a trimmed idle stretch where the card is drawn', () => { + // The 4 s wait is frozen and plays in 400 ms: 3.6 s saved before the scene. + const rendered = plan( + [wait(1000, 5000), scene(6000, 'Invoices')], + [{ startMs: 1000, endMs: 5000 }], + ); + const [chapter] = planChapters(rendered); + const card = rendered.cards.find((entry) => entry.kind === 'scene'); + expect(chapter).toEqual({ title: 'Invoices', atMs: card?.startMs }); + expect(chapter.atMs).toBe(2000 + 6000 - 3600); + }); + + it('is empty without scenes, or with scene cards off', () => { + expect(planChapters(plan([wait(0, 1000)]))).toEqual([]); + expect( + planChapters( + plan([scene(1000, 'Sign in')], [], { + ...CARDS, + scenes: { enabled: false, durationMs: 1500 }, + }), + ), + ).toEqual([]); + }); + + it('keeps at most MAX_CHAPTERS, each title at most 200 characters', () => { + const chapters = planChapters({ + cards: Array.from({ length: MAX_CHAPTERS + 5 }, (_, index) => ({ + kind: 'scene' as const, + startMs: index * 1000 + 0.4, + durationMs: 1500, + title: index === 0 ? 'x'.repeat(250) : `Scene ${index}`, + })), + }); + expect(chapters).toHaveLength(MAX_CHAPTERS); + expect(chapters[0]).toEqual({ title: 'x'.repeat(200), atMs: 0 }); + expect(chapters[1]).toEqual({ title: 'Scene 1', atMs: 1000 }); + }); +}); From d186bacbcd35e0c353d05a8fcf88ee1e9b7c16e8 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 19:26:22 +0100 Subject: [PATCH 58/71] test(demo): add the Shares page demo scenario for card C-185 --- ...-share-dialog-on-the-run-page-an.demo.json | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 demoflow/cards/C-185-feat-web-share-dialog-on-the-run-page-an.demo.json diff --git a/demoflow/cards/C-185-feat-web-share-dialog-on-the-run-page-an.demo.json b/demoflow/cards/C-185-feat-web-share-dialog-on-the-run-page-an.demo.json new file mode 100644 index 00000000..5302873c --- /dev/null +++ b/demoflow/cards/C-185-feat-web-share-dialog-on-the-run-page-an.demo.json @@ -0,0 +1,37 @@ +{ + "schemaVersion": 1, + "name": "Shares page", + "description": "Sign in off camera, then open Shares from the sidebar: the breadcrumb follows, and the page shows the share storage quota above the list of shared runs.", + "viewport": { "width": 1280, "height": 720 }, + "setup": [ + { "action": "include", "fragment": "sign-in", "with": { "next": "/app" } } + ], + "steps": [ + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Overview", "exact": true } + }, + { + "action": "click", + "target": { "role": "link", "name": "Shares", "exact": true } + }, + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Shares", "exact": true } + }, + { + "action": "assertText", + "target": { "role": "navigation", "name": "Breadcrumb" }, + "text": "Shares" + }, + { + "action": "assertVisible", + "target": { "role": "progressbar", "name": "Share storage" } + }, + { + "action": "assertText", + "target": { "role": "main" }, + "text": "used" + } + ] +} From 93ec5085aab6a7394abd943582483b8dcb762640 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 19:27:49 +0100 Subject: [PATCH 59/71] test(demo): add the C-195 demo scenario for the Add project dialog Signs in off camera, opens the Add project dialog from the Projects page and closes it with Escape. It touches only what renders on an empty account. Refs #379. --- ...-add-project-dialog-machine-path.demo.json | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 demoflow/cards/C-195-feat-web-add-project-dialog-machine-path.demo.json diff --git a/demoflow/cards/C-195-feat-web-add-project-dialog-machine-path.demo.json b/demoflow/cards/C-195-feat-web-add-project-dialog-machine-path.demo.json new file mode 100644 index 00000000..288ec727 --- /dev/null +++ b/demoflow/cards/C-195-feat-web-add-project-dialog-machine-path.demo.json @@ -0,0 +1,32 @@ +{ + "schemaVersion": 1, + "name": "Add project dialog", + "description": "Sign in off camera, then open the new Add project dialog from the Projects page: it replaces the old create and bind forms with one place to choose a machine and a folder, and closes with Escape.", + "viewport": { "width": 1280, "height": 720 }, + "setup": [ + { + "action": "include", + "fragment": "sign-in", + "with": { "next": "/app/projects" } + } + ], + "steps": [ + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Projects", "exact": true } + }, + { + "action": "click", + "target": { "role": "button", "name": "Add project", "exact": true } + }, + { + "action": "assertVisible", + "target": { "role": "dialog", "name": "Add project", "exact": true } + }, + { "action": "press", "key": "Escape" }, + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Projects", "exact": true } + } + ] +} From ea867c88fb8d2d797ca5bfecbcf8ffedfeb5fede Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 19:39:51 +0100 Subject: [PATCH 60/71] feat(cli): the runner prepares shares and serves their posters The daemon announces features: ['share'] and answers share.prepare with the scenario's description, the render's chapters and the size of a poster it makes with FFmpeg (one JPEG frame, at most 1280 px wide, reused while newer than the render). The relay serves that poster for video.open with asset: 'poster'; an unknown asset is not-found. scenarioDescription moves to scenario-file.ts so the daemon reads descriptions the way demoflow render does. --- apps/cli/src/commands/render.ts | 20 +- apps/cli/src/commands/scenario-file.ts | 22 +- apps/cli/src/runner/connection.ts | 19 +- apps/cli/src/runner/daemon.ts | 6 + apps/cli/src/runner/relay/index.ts | 40 +- apps/cli/src/runner/share/files.ts | 14 + apps/cli/src/runner/share/poster.ts | 87 +++++ apps/cli/src/runner/share/prepare.ts | 181 +++++++++ apps/cli/test/runner/connection.spec.ts | 48 +++ apps/cli/test/runner/daemon-launch.spec.ts | 6 +- apps/cli/test/runner/relay.spec.ts | 78 ++++ apps/cli/test/runner/share.spec.ts | 427 +++++++++++++++++++++ 12 files changed, 917 insertions(+), 31 deletions(-) create mode 100644 apps/cli/src/runner/share/files.ts create mode 100644 apps/cli/src/runner/share/poster.ts create mode 100644 apps/cli/src/runner/share/prepare.ts create mode 100644 apps/cli/test/runner/share.spec.ts diff --git a/apps/cli/src/commands/render.ts b/apps/cli/src/commands/render.ts index 4263cf53..9856f107 100644 --- a/apps/cli/src/commands/render.ts +++ b/apps/cli/src/commands/render.ts @@ -28,7 +28,7 @@ import { exitCodeFor } from './exit.ts'; import type { Io } from './io.ts'; import { formatJson, formatSummary } from './output.ts'; import { assertSafeRunId } from './run-id.ts'; -import { loadScenario } from './scenario-file.ts'; +import { scenarioDescription } from './scenario-file.ts'; import { readResult, settleRun } from './settle.ts'; export interface RenderFlags { @@ -174,24 +174,6 @@ async function readRenderable(runDir: string): Promise<RunResult> { return result; } -/** - * The intro card's subtitle: the scenario's `description`, read from the - * project when its file is still there and loads. An inline scenario of - * `demoflow mcp` is gone after its run, so its card has no subtitle. - */ -function scenarioDescription( - root: string, - scenarioId: string, -): string | undefined { - const file = path.join(root, scenarioId); - if (!existsSync(file)) return undefined; - try { - return loadScenario(file).scenario.description; - } catch { - return undefined; - } -} - /** * What `buildRenderPlan` gets from the project's `render.*`, for `run` and * `render` alike: a re-render is styled exactly like a first render would be diff --git a/apps/cli/src/commands/scenario-file.ts b/apps/cli/src/commands/scenario-file.ts index 4a9b4ccc..5aaab559 100644 --- a/apps/cli/src/commands/scenario-file.ts +++ b/apps/cli/src/commands/scenario-file.ts @@ -1,4 +1,5 @@ -import { readFileSync } from 'node:fs'; +import { existsSync, readFileSync } from 'node:fs'; +import path from 'node:path'; import { type FragmentSource, type Issue, @@ -40,3 +41,22 @@ export function loadScenario( } return { scenario: parsed.value, warnings: parsed.warnings }; } + +/** + * The scenario's `description`, read from the project when its file is still + * there and loads (spec 255, Decision 3): the intro card's subtitle and a + * share's description (spec 349). An inline scenario of `demoflow mcp` is + * gone after its run, so it has none. + */ +export function scenarioDescription( + root: string, + scenarioId: string, +): string | undefined { + const file = path.join(root, scenarioId); + if (!existsSync(file)) return undefined; + try { + return loadScenario(file).scenario.description; + } catch { + return undefined; + } +} diff --git a/apps/cli/src/runner/connection.ts b/apps/cli/src/runner/connection.ts index bc96d4d5..396b5557 100644 --- a/apps/cli/src/runner/connection.ts +++ b/apps/cli/src/runner/connection.ts @@ -8,6 +8,7 @@ import { import type { Logger } from './log.ts'; import type { RelaySender, VideoRelayPort } from './relay/index.ts'; import type { ProjectsPort } from './roots/index.ts'; +import type { SharePort } from './share/prepare.ts'; import type { ConnectionState } from './state.ts'; /** Decision 6: each side pings every 25 s and gives up after 60 s of silence. */ @@ -80,6 +81,11 @@ export interface ConnectionDeps { launches?: LaunchPort; /** Answers `project.*` (spec 377); without it, logged as unknown. */ projects?: ProjectsPort; + /** + * Answers `share.prepare` (spec 349); without it, logged as unknown. Its + * poster goes out through `relay`, so it is announced only with one. + */ + share?: SharePort; } export type ConnectionOutcome = 'stopped' | 'revoked'; @@ -187,7 +193,12 @@ export class RunnerConnection { // so it claims no options. const runOptions = this.deps.launches !== undefined ? [...RUN_OPTIONS] : []; // Spec 377, Decision 9: what else this daemon answers. - const features = this.deps.projects !== undefined ? ['projects'] : []; + const features: string[] = []; + if (this.deps.projects !== undefined) features.push('projects'); + // Spec 349, Decision 5: a share needs `share.prepare` and the poster's stream. + if (this.deps.share !== undefined && this.deps.relay !== undefined) { + features.push('share'); + } this.send({ type: 'launches.sync', running, @@ -274,6 +285,12 @@ export class RunnerConnection { return; } break; + case 'share.prepare': + if (this.deps.share !== undefined) { + this.deps.share.handle(fields, this.relaySender()); + return; + } + break; } this.deps.logger.log( 'warn', diff --git a/apps/cli/src/runner/daemon.ts b/apps/cli/src/runner/daemon.ts index 8c92a6ed..2eaf9eb7 100644 --- a/apps/cli/src/runner/daemon.ts +++ b/apps/cli/src/runner/daemon.ts @@ -23,6 +23,7 @@ import { isWebsiteRegistered, ProjectRequests, } from './roots/index.ts'; +import { sharePreparer } from './share/prepare.ts'; import { type ConnectionState, writeState } from './state.ts'; /** How often the daemon looks for `runner.stop`. */ @@ -161,6 +162,11 @@ export async function runForeground(io: Io, deps: DaemonDeps): Promise<number> { loadProject: launcherDeps.loadProject, writeTemplate: defaultWriteTemplate, }), + share: sharePreparer({ + indexFile: paths.reportedRuns, + logger, + platform: deps.host.platform, + }), }); const stop = (why: string) => { diff --git a/apps/cli/src/runner/relay/index.ts b/apps/cli/src/runner/relay/index.ts index 9599f8eb..35145ed3 100644 --- a/apps/cli/src/runner/relay/index.ts +++ b/apps/cli/src/runner/relay/index.ts @@ -7,6 +7,7 @@ import { import { pathFor } from '../../config/platform.ts'; import { findReportedRun } from '../../runs-report/reported-runs.ts'; import type { Logger } from '../log.ts'; +import { posterPath } from '../share/files.ts'; import { parseRange } from './range.ts'; import { type RelayFile, @@ -82,19 +83,36 @@ export function isInside( } /** - * The real path of a reported run's rendered file in `format`, or `null`. - * The run directory comes from the index, never from the message, and only a - * file `result.json` lists, inside that directory, can come out. + * Spec 349, Decision 4: what `video.open` may ask for besides the render. + * Anything else is `not-found`. + */ +export const VIDEO_ASSETS = ['poster'] as const; +export type VideoAsset = (typeof VIDEO_ASSETS)[number]; + +/** + * The real path of a reported run's rendered file in `format` — or, with + * `asset: 'poster'`, of the poster a share made for it — or `null`. The run + * directory comes from the index, never from the message, and only a file + * `result.json` lists, or the poster's fixed name, inside that directory, + * can come out. */ export async function locateVideo( runId: string, format: RenderFormat, deps: RelayDeps, + asset?: VideoAsset, ): Promise<string | null> { const entry = await findReportedRun(deps.indexFile, runId); if (entry === null) return null; const p = pathFor(deps.platform); try { + if (asset === 'poster') { + const root = await deps.fs.realpath(entry.runDir); + const real = await deps.fs.realpath( + posterPath(entry.runDir, format, deps.platform), + ); + return isInside(root, real, deps.platform) ? real : null; + } const parsed = RunResultSchema.safeParse( JSON.parse(await deps.fs.readFile(p.join(entry.runDir, RESULT_FILE))), ); @@ -196,6 +214,11 @@ export class VideoRelay implements VideoRelayPort { return; } const videoFormat = format as RenderFormat; + const { asset } = message; + // An asset this daemon does not know opens, and fails `not-found`. + const known = + asset === undefined || VIDEO_ASSETS.includes(asset as VideoAsset); + const videoAsset = asset === undefined ? undefined : (asset as VideoAsset); if (this.streams.has(streamId)) { this.deps.logger.log( 'warn', @@ -203,9 +226,10 @@ export class VideoRelay implements VideoRelayPort { ); return; } + const what = known && videoAsset !== undefined ? ` ${videoAsset}` : ''; if (this.streams.size >= MAX_STREAMS) { sender.send({ type: 'video.error', streamId, code: 'busy' }); - this.logStream(runId, videoFormat, 0, 'busy'); + this.logStream(runId, videoFormat, what, 0, 'busy'); return; } const stream = new VideoStream(streamId, sender, (outcome, sent) => { @@ -213,12 +237,13 @@ export class VideoRelay implements VideoRelayPort { this.streams.delete(streamId); this.runIds.delete(streamId); } - this.logStream(runId, videoFormat, sent, outcome); + this.logStream(runId, videoFormat, what, sent, outcome); }); this.streams.set(streamId, stream); this.runIds.set(streamId, runId); void stream.begin(async () => { - const file = await locateVideo(runId, videoFormat, this.deps); + if (!known) return null; + const file = await locateVideo(runId, videoFormat, this.deps, videoAsset); return file === null ? null : this.deps.fs.open(file); }, range); } @@ -227,12 +252,13 @@ export class VideoRelay implements VideoRelayPort { private logStream( runId: string, format: RenderFormat, + asset: string, sent: number, outcome: StreamOutcome | 'busy', ): void { this.deps.logger.log( 'info', - `video ${runId} ${format}: ${sent} bytes sent, ${outcome}`, + `video ${runId} ${format}${asset}: ${sent} bytes sent, ${outcome}`, ); } } diff --git a/apps/cli/src/runner/share/files.ts b/apps/cli/src/runner/share/files.ts new file mode 100644 index 00000000..bc1cede6 --- /dev/null +++ b/apps/cli/src/runner/share/files.ts @@ -0,0 +1,14 @@ +import type { RenderFormat } from '@demoflow/core'; +import { pathFor } from '../../config/platform.ts'; + +/** Spec 349, Decision 3: what a share makes lives in `<runDir>/share/`. */ +export const SHARE_DIR = 'share'; + +/** `<runDir>/share/poster-<format>.jpg`: one poster per rendered format. */ +export function posterPath( + runDir: string, + format: RenderFormat, + platform: NodeJS.Platform, +): string { + return pathFor(platform).join(runDir, SHARE_DIR, `poster-${format}.jpg`); +} diff --git a/apps/cli/src/runner/share/poster.ts b/apps/cli/src/runner/share/poster.ts new file mode 100644 index 00000000..353f9367 --- /dev/null +++ b/apps/cli/src/runner/share/poster.ts @@ -0,0 +1,87 @@ +import { mkdir, rename, rm, stat } from 'node:fs/promises'; +import { runFfmpeg } from '@demoflow/renderer'; +import { pathFor } from '../../config/platform.ts'; + +/** #347: the API refuses a poster over 1 MiB, so the daemon does too. */ +export const POSTER_MAX_BYTES = 1024 * 1024; +/** Decision 3: the frame is taken at most this far in. */ +export const POSTER_AT_MAX_MS = 1500; +/** Decision 3: the poster is at most this wide, keeping the aspect. */ +export const POSTER_MAX_WIDTH = 1280; + +/** FFmpeg, as the poster maker runs it; tests stub it. */ +export type RunFfmpeg = (args: readonly string[]) => Promise<unknown>; + +export interface PosterRequest { + /** The render's file, already checked to be inside the run directory. */ + render: string; + /** Where the poster lives: `posterPath(runDir, format)`. */ + poster: string; + /** The render's `durationMs`. */ + durationMs: number; + platform: NodeJS.Platform; +} + +/** The FFmpeg arguments for one JPEG frame of `render` at `atMs`. */ +export function posterArgs( + render: string, + output: string, + atMs: number, +): string[] { + return [ + '-y', + '-i', + render, + // After `-i`: a GIF cannot be seeked on input, and the decode is short. + '-ss', + (atMs / 1000).toFixed(3), + '-frames:v', + '1', + '-an', + '-vf', + `scale='min(${POSTER_MAX_WIDTH},iw)':-2`, + '-q:v', + '4', + output, + ]; +} + +/** Decision 3: `min(1500, ⌊durationMs / 2⌋)`. */ +export function posterAtMs(durationMs: number): number { + return Math.min(POSTER_AT_MAX_MS, Math.floor(Math.max(0, durationMs) / 2)); +} + +/** + * Decision 3: the poster of a render, made with FFmpeg unless the one on + * disk is newer than the render, and its size in bytes. It is written to a + * temporary file and renamed, so a crash never leaves half a JPEG to reuse. + * Rejects when FFmpeg fails or the poster is over `POSTER_MAX_BYTES`. + */ +export async function makePoster( + request: PosterRequest, + ffmpeg: RunFfmpeg = runFfmpeg, +): Promise<number> { + const { render, poster } = request; + const rendered = await stat(render); + const existing = await stat(poster).catch(() => null); + let size: number; + if (existing !== null && existing.mtimeMs > rendered.mtimeMs) { + size = existing.size; + } else { + const p = pathFor(request.platform); + await mkdir(p.dirname(poster), { recursive: true }); + const temp = `${poster.slice(0, -'.jpg'.length)}.tmp.jpg`; + try { + await ffmpeg(posterArgs(render, temp, posterAtMs(request.durationMs))); + await rename(temp, poster); + } catch (error) { + await rm(temp, { force: true }); + throw error; + } + size = (await stat(poster)).size; + } + if (size === 0 || size > POSTER_MAX_BYTES) { + throw new Error(`the poster is ${size} bytes`); + } + return size; +} diff --git a/apps/cli/src/runner/share/prepare.ts b/apps/cli/src/runner/share/prepare.ts new file mode 100644 index 00000000..dc2e131b --- /dev/null +++ b/apps/cli/src/runner/share/prepare.ts @@ -0,0 +1,181 @@ +import { readFile, realpath } from 'node:fs/promises'; +import { + type Chapter, + RENDER_FORMATS, + type RenderFormat, + RunResultSchema, +} from '@demoflow/core'; +import { scenarioDescription } from '../../commands/scenario-file.ts'; +import { pathFor } from '../../config/platform.ts'; +import { findReportedRun } from '../../runs-report/reported-runs.ts'; +import type { Logger } from '../log.ts'; +import { isInside, RUN_ID } from '../relay/index.ts'; +import { posterPath } from './files.ts'; +import { makePoster, type PosterRequest } from './poster.ts'; + +/** `RUN_FILES.result` of the engine, which the daemon does not load. */ +const RESULT_FILE = 'result.json'; +/** #347: the API keeps at most this much of a share's description. */ +export const DESCRIPTION_MAX_LENGTH = 2000; + +export interface ShareDeps { + /** `reported-runs.jsonl`. */ + indexFile: string; + logger: Logger; + platform: NodeJS.Platform; + /** Decision 3; tests stub FFmpeg through it. */ + makePoster(request: PosterRequest): Promise<number>; +} + +/** The socket, as the preparer sees it: JSON text frames only. */ +export interface ShareSender { + send(message: Record<string, unknown>): void; +} + +/** What the connection needs from the preparer. */ +export interface SharePort { + handle(message: Record<string, unknown>, sender: ShareSender): void; +} + +/** What `share.prepare` answers, before the request id is added. */ +export type Prepared = + | { + ok: true; + description?: string; + chapters: Chapter[]; + posterSize: number; + } + | { ok: false; code: 'not-found' | 'no-render' | 'io' }; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i; + +/** + * Spec 349, Decision 2: the daemon's side of `share.prepare`. It answers with + * the scenario's description, the render's chapters and the size of a poster + * it makes, which the relay then serves as `asset: 'poster'`. The server names + * a run by its id; no path is ever sent or logged. + */ +export class SharePreparer implements SharePort { + private readonly deps: ShareDeps; + /** One poster at a time per file: two shares of a render share it. */ + private readonly posters = new Map<string, Promise<number>>(); + + constructor(deps: ShareDeps) { + this.deps = deps; + } + + handle(message: Record<string, unknown>, sender: ShareSender): void { + const { requestId, runId, format } = message; + if ( + typeof requestId !== 'string' || + !UUID.test(requestId) || + typeof runId !== 'string' || + !RUN_ID.test(runId) || + !RENDER_FORMATS.includes(format as RenderFormat) + ) { + this.deps.logger.log('warn', 'ignored a malformed share.prepare'); + return; + } + void this.prepare(runId, format as RenderFormat) + .catch((): Prepared => ({ ok: false, code: 'io' })) + .then((prepared) => { + this.deps.logger.log( + 'info', + `share ${runId} ${format}: ${prepared.ok ? 'prepared' : prepared.code}`, + ); + if (!prepared.ok) { + sender.send({ type: 'share.error', requestId, code: prepared.code }); + return; + } + const { description, chapters, posterSize } = prepared; + sender.send({ + type: 'share.prepared', + requestId, + ...(description === undefined ? {} : { description }), + chapters, + posterSize, + }); + }); + } + + async prepare(runId: string, format: RenderFormat): Promise<Prepared> { + const { platform } = this.deps; + const p = pathFor(platform); + const entry = await findReportedRun(this.deps.indexFile, runId); + if (entry === null) return { ok: false, code: 'not-found' }; + let raw: unknown; + try { + raw = JSON.parse( + await readFile(p.join(entry.runDir, RESULT_FILE), 'utf8'), + ); + } catch { + return { ok: false, code: 'not-found' }; + } + const parsed = RunResultSchema.safeParse(raw); + if (!parsed.success) return { ok: false, code: 'not-found' }; + const render = parsed.data.renders.find((item) => item.format === format); + if (render === undefined) return { ok: false, code: 'no-render' }; + + // The same boundary as the relay: only a file inside the run directory. + let file: string; + try { + const root = await realpath(entry.runDir); + file = await realpath(p.resolve(entry.runDir, render.file)); + if (!isInside(root, file, platform)) { + return { ok: false, code: 'no-render' }; + } + } catch { + return { ok: false, code: 'no-render' }; + } + + const posterSize = await this.poster({ + render: file, + poster: posterPath(entry.runDir, format, platform), + durationMs: render.durationMs, + platform, + }); + const description = this.description(entry.root, parsed.data.scenarioId); + return { + ok: true, + ...(description === undefined ? {} : { description }), + chapters: render.chapters ?? [], + posterSize, + }; + } + + private poster(request: PosterRequest): Promise<number> { + const pending = this.posters.get(request.poster); + if (pending !== undefined) return pending; + const making = this.deps.makePoster(request).finally(() => { + this.posters.delete(request.poster); + }); + this.posters.set(request.poster, making); + return making; + } + + /** + * The scenario's description, from its file in the project the run was + * reported from — and only from inside that project. + */ + private description( + root: string | undefined, + scenarioId: string, + ): string | undefined { + if (root === undefined) return undefined; + const p = pathFor(this.deps.platform); + if (!isInside(root, p.resolve(root, scenarioId), this.deps.platform)) { + return undefined; + } + const description = scenarioDescription(root, scenarioId)?.trim(); + return description === undefined || description === '' + ? undefined + : description.slice(0, DESCRIPTION_MAX_LENGTH); + } +} + +/** The daemon's preparer, with the real FFmpeg. */ +export function sharePreparer( + deps: Omit<ShareDeps, 'makePoster'>, +): SharePreparer { + return new SharePreparer({ ...deps, makePoster: (r) => makePoster(r) }); +} diff --git a/apps/cli/test/runner/connection.spec.ts b/apps/cli/test/runner/connection.spec.ts index 47ceb5df..ad868068 100644 --- a/apps/cli/test/runner/connection.spec.ts +++ b/apps/cli/test/runner/connection.spec.ts @@ -18,6 +18,7 @@ import type { VideoRelayPort, } from '../../src/runner/relay/index.ts'; import type { ProjectsPort } from '../../src/runner/roots/index.ts'; +import type { SharePort } from '../../src/runner/share/prepare.ts'; import type { ConnectionState } from '../../src/runner/state.ts'; import { FakeClock, @@ -52,6 +53,7 @@ function start( artifacts?: ArtifactsPort, launches?: LaunchPort, projects?: ProjectsPort, + share?: SharePort, ) { const fake = fakeSockets(); sockets = fake.sockets; @@ -78,6 +80,7 @@ function start( ...(artifacts === undefined ? {} : { artifacts }), ...(launches === undefined ? {} : { launches }), ...(projects === undefined ? {} : { projects }), + ...(share === undefined ? {} : { share }), }); void connection.run().then((value) => { outcome = value; @@ -564,6 +567,51 @@ describe('RunnerConnection and the video relay', () => { ); }); + it('announces the share feature and routes share.prepare to it (spec 349)', () => { + const relay = recordingRelay(); + const handled: Array<Record<string, unknown>> = []; + const share: SharePort = { + handle(message, sender) { + handled.push(message); + sender.send({ type: 'share.error', requestId: 'q', code: 'io' }); + }, + }; + start(0.5, relay, undefined, undefined, undefined, share); + last().open(); + expect(last().sent[0]).toEqual({ ...EMPTY_SYNC, features: ['share'] }); + last().receive({ + type: 'share.prepare', + requestId: 'q', + runId: 'r', + format: 'mp4', + }); + expect(handled).toEqual([ + { type: 'share.prepare', requestId: 'q', runId: 'r', format: 'mp4' }, + ]); + expect(last().sent).toContainEqual({ + type: 'share.error', + requestId: 'q', + code: 'io', + }); + expect(logger.text()).not.toMatch(/ignored/); + }); + + it('does not announce share without the relay that streams its poster', () => { + start(0.5, undefined, undefined, undefined, undefined, { + handle: () => {}, + }); + last().open(); + expect(last().sent[0]).toEqual(EMPTY_SYNC); + }); + + it('logs share.prepare as unknown without the share port, as a daemon before #349 did', () => { + start(0.5, recordingRelay()); + last().open(); + last().receive({ type: 'share.prepare', requestId: 'q' }); + expect(logger.text()).toMatch(/ignored a message of type "share.prepare"/); + expect(last().sent).toEqual([EMPTY_SYNC]); + }); + it('logs run.start as unknown without a launcher, as a daemon before #248 did', () => { start(); last().open(); diff --git a/apps/cli/test/runner/daemon-launch.spec.ts b/apps/cli/test/runner/daemon-launch.spec.ts index 589ccedb..bc88c2e9 100644 --- a/apps/cli/test/runner/daemon-launch.spec.ts +++ b/apps/cli/test/runner/daemon-launch.spec.ts @@ -191,7 +191,7 @@ describe('the daemon with a website-started run', () => { type: 'launches.sync', running: [], runOptions: ['formats'], - features: ['projects'], + features: ['projects', 'share'], checks: true, }); first.receive({ @@ -232,7 +232,7 @@ describe('the daemon with a website-started run', () => { type: 'launches.sync', running: [REQUEST], runOptions: ['formats'], - features: ['projects'], + features: ['projects', 'share'], checks: true, }); await stop(next); @@ -249,7 +249,7 @@ describe('the daemon with a website-started run', () => { type: 'launches.sync', running: [], runOptions: ['formats'], - features: ['projects'], + features: ['projects', 'share'], checks: true, }, ]); diff --git a/apps/cli/test/runner/relay.spec.ts b/apps/cli/test/runner/relay.spec.ts index 3a292913..20227d53 100644 --- a/apps/cli/test/runner/relay.spec.ts +++ b/apps/cli/test/runner/relay.spec.ts @@ -133,6 +133,7 @@ function open( format?: RenderFormat; range?: VideoRange | null; streamId?: string; + asset?: unknown; } = {}, ): string { const streamId = options.streamId ?? randomUUID(); @@ -143,6 +144,7 @@ function open( runId: options.runId ?? RUN_ID, format: options.format ?? 'mp4', range: options.range ?? null, + ...('asset' in options ? { asset: options.asset } : {}), }, sender, ); @@ -451,6 +453,82 @@ describe('VideoRelay: the ADR-0008 boundary', () => { }); }); +describe('VideoRelay: the poster asset (spec 349)', () => { + let poster: Buffer; + beforeEach(() => { + poster = randomBytes(CHUNK_BYTES + 77); + mkdirSync(path.join(runDir, 'share')); + writeFileSync(path.join(runDir, 'share', 'poster-mp4.jpg'), poster); + }); + + it('streams exactly the poster of the format, and logs it as one', async () => { + const sender = recordingSender(); + const streamId = open(sender, { asset: 'poster' }); + expect((await drain(sender, streamId)).equals(poster)).toBe(true); + expect(sender.messagesOf(streamId)[0]).toMatchObject({ + type: 'video.head', + size: poster.length, + }); + await until(() => logger.lines.length > 0, 'log line'); + expect(logger.lines[0]?.message).toBe( + `video ${RUN_ID} mp4 poster: ${poster.length} bytes sent, sent`, + ); + expect(logger.text()).not.toContain(home); + }); + + it('still serves the render without an asset', async () => { + const sender = recordingSender(); + const streamId = open(sender); + expect((await drain(sender, streamId)).equals(video)).toBe(true); + }); + + it('answers not-found for a format with no poster', async () => { + const sender = recordingSender(); + await expectNotFound( + sender, + open(sender, { asset: 'poster', format: 'gif' }), + ); + }); + + it('answers not-found for a run this machine never reported', async () => { + const sender = recordingSender(); + await expectNotFound( + sender, + open(sender, { asset: 'poster', runId: 'someone-else' }), + ); + }); + + it.each([ + 'thumbnail', + '../result.json', + 42, + null, + ])('answers not-found for the unknown asset %j', async (asset) => { + const sender = recordingSender(); + await expectNotFound(sender, open(sender, { asset })); + expect(counts.open).toBe(0); + }); + + it('answers not-found for a poster that links out of the run directory', async (ctx) => { + const secret = path.join(home, 'secret.jpg'); + writeFileSync(secret, 'secret'); + const link = path.join(runDir, 'share', 'poster-gif.jpg'); + try { + symlinkSync(secret, link, 'file'); + } catch (error) { + if (process.platform === 'win32') { + ctx.skip(`file symlinks need a privilege here: ${String(error)}`); + } + throw error; + } + const sender = recordingSender(); + await expectNotFound( + sender, + open(sender, { asset: 'poster', format: 'gif' }), + ); + }); +}); + describe('VideoRelay: flow and ends', () => { beforeEach(() => { // 2 MiB and a bit: four windows' worth. diff --git a/apps/cli/test/runner/share.spec.ts b/apps/cli/test/runner/share.spec.ts new file mode 100644 index 00000000..78ab3c19 --- /dev/null +++ b/apps/cli/test/runner/share.spec.ts @@ -0,0 +1,427 @@ +import { randomUUID } from 'node:crypto'; +import { + mkdirSync, + mkdtempSync, + readFileSync, + realpathSync, + rmSync, + statSync, + symlinkSync, + utimesSync, + writeFileSync, +} from 'node:fs'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import type { Chapter, RenderFormat, RunResult } from '@demoflow/core'; +import { runFfmpeg } from '@demoflow/renderer'; +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; +import { posterPath } from '../../src/runner/share/files.ts'; +import { + makePoster, + POSTER_MAX_BYTES, + type PosterRequest, + posterArgs, + posterAtMs, +} from '../../src/runner/share/poster.ts'; +import { + DESCRIPTION_MAX_LENGTH, + SharePreparer, +} from '../../src/runner/share/prepare.ts'; +import { appendReportedRun } from '../../src/runs-report/reported-runs.ts'; +import { memoryLogger } from './fakes.ts'; + +const RUN_ID = 'srv-run-1'; +const SCENARIO = 'demoflow/a.demo.json'; + +let base: string; +let root: string; +let runDir: string; +let indexFile: string; +let logger: ReturnType<typeof memoryLogger>; +let posters: PosterRequest[]; +let posterSize: number | Error; + +function writeResult( + renders: Array<{ + format: RenderFormat; + file: string; + chapters?: Chapter[]; + durationMs?: number; + }>, + scenarioId = SCENARIO, +): void { + const done = { status: 'passed' } as const; + const result: RunResult = { + schemaVersion: 1, + runId: 'local-run', + scenarioId, + scenarioName: 'A', + startedAt: '2026-10-22T10:00:00.000Z', + finishedAt: '2026-10-22T10:00:01.000Z', + status: 'completed', + stages: { + readiness: done, + execution: done, + verification: done, + recording: done, + rendering: done, + storage: { status: 'skipped' }, + }, + renders: renders.map((render) => ({ + renderer: 'ffmpeg', + durationMs: 4000, + sizeBytes: 1, + width: 1280, + height: 720, + fps: 30, + ...render, + })), + warnings: [], + }; + writeFileSync(path.join(runDir, 'result.json'), JSON.stringify(result)); +} + +function writeScenario(description?: string, file = SCENARIO): void { + const target = path.join(root, file); + mkdirSync(path.dirname(target), { recursive: true }); + writeFileSync( + target, + JSON.stringify({ + schemaVersion: 1, + name: 'A', + ...(description === undefined ? {} : { description }), + steps: [{ action: 'navigate', path: '/' }], + }), + ); +} + +function preparer(): SharePreparer { + return new SharePreparer({ + indexFile, + logger, + platform: process.platform, + makePoster: async (request) => { + posters.push(request); + if (posterSize instanceof Error) throw posterSize; + return posterSize; + }, + }); +} + +/** Sends one `share.prepare` and waits for its answer. */ +async function prepare( + message: Record<string, unknown> = {}, + share = preparer(), +): Promise<Record<string, unknown>> { + return new Promise((resolve) => { + share.handle( + { + type: 'share.prepare', + requestId: '2f1f6d0e-7a53-4c1b-9d57-0c1f6f1d2a11', + runId: RUN_ID, + format: 'mp4', + ...message, + }, + { send: resolve }, + ); + }); +} + +beforeEach(() => { + base = realpathSync(mkdtempSync(path.join(tmpdir(), 'demoflow-share-'))); + root = path.join(base, 'project'); + runDir = path.join(base, 'home', 'runs', 'local-run'); + mkdirSync(root, { recursive: true }); + mkdirSync(path.join(runDir, 'renders'), { recursive: true }); + indexFile = path.join(base, 'runner', 'reported-runs.jsonl'); + appendReportedRun(indexFile, { + id: RUN_ID, + runDir, + at: '2026-10-22T10:00:01.000Z', + root, + }); + writeFileSync(path.join(runDir, 'renders', 'demo.mp4'), 'mp4 bytes'); + logger = memoryLogger(); + posters = []; + posterSize = 1234; +}); + +afterEach(() => { + rmSync(base, { recursive: true, force: true }); +}); + +describe('SharePreparer (spec 349, Decision 2)', () => { + it('answers with the description, the chapters and the poster size, and no path', async () => { + const chapters = [ + { title: 'Customers', atMs: 0 }, + { title: 'Invoices', atMs: 4200 }, + ]; + writeResult([{ format: 'mp4', file: 'renders/demo.mp4', chapters }]); + writeScenario('Create a customer, then bill them.'); + const answer = await prepare(); + expect(answer).toEqual({ + type: 'share.prepared', + requestId: '2f1f6d0e-7a53-4c1b-9d57-0c1f6f1d2a11', + description: 'Create a customer, then bill them.', + chapters, + posterSize: 1234, + }); + expect(posters).toEqual([ + { + render: path.join(runDir, 'renders', 'demo.mp4'), + poster: posterPath(runDir, 'mp4', process.platform), + durationMs: 4000, + platform: process.platform, + }, + ]); + expect(logger.text()).toContain(`share ${RUN_ID} mp4: prepared`); + expect(logger.text()).not.toContain(base); + }); + + it('answers chapters [] and no description for an old render and a gone scenario', async () => { + writeResult([{ format: 'mp4', file: 'renders/demo.mp4' }]); + const answer = await prepare(); + expect(answer).toEqual({ + type: 'share.prepared', + requestId: '2f1f6d0e-7a53-4c1b-9d57-0c1f6f1d2a11', + chapters: [], + posterSize: 1234, + }); + }); + + it('cuts a long description to the API limit', async () => { + writeResult([{ format: 'mp4', file: 'renders/demo.mp4' }]); + writeScenario('x'.repeat(DESCRIPTION_MAX_LENGTH + 50)); + const answer = await prepare(); + expect(answer.description).toBe('x'.repeat(DESCRIPTION_MAX_LENGTH)); + }); + + it('reads no description for a run without a project root', async () => { + rmSync(indexFile); + appendReportedRun(indexFile, { id: RUN_ID, runDir, at: '' }); + writeResult([{ format: 'mp4', file: 'renders/demo.mp4' }]); + writeScenario('Hidden.'); + expect((await prepare()).description).toBeUndefined(); + }); + + it('reads no description from outside the project', async () => { + writeFileSync( + path.join(base, 'outside.json'), + JSON.stringify({ + schemaVersion: 1, + name: 'O', + description: 'Outside.', + steps: [{ action: 'navigate', path: '/' }], + }), + ); + writeResult( + [{ format: 'mp4', file: 'renders/demo.mp4' }], + '../outside.json', + ); + expect((await prepare()).description).toBeUndefined(); + }); + + it('answers not-found for an unreported run or an unreadable result', async () => { + writeResult([{ format: 'mp4', file: 'renders/demo.mp4' }]); + expect(await prepare({ runId: 'srv-other' })).toEqual({ + type: 'share.error', + requestId: '2f1f6d0e-7a53-4c1b-9d57-0c1f6f1d2a11', + code: 'not-found', + }); + writeFileSync(path.join(runDir, 'result.json'), '{ not json'); + expect((await prepare()).code).toBe('not-found'); + writeFileSync(path.join(runDir, 'result.json'), '{}'); + expect((await prepare()).code).toBe('not-found'); + expect(posters).toEqual([]); + }); + + it('answers no-render for an unrendered format, a missing file or one outside the run', async () => { + writeResult([{ format: 'mp4', file: 'renders/demo.mp4' }]); + expect((await prepare({ format: 'gif' })).code).toBe('no-render'); + + writeResult([{ format: 'mp4', file: 'renders/gone.mp4' }]); + expect((await prepare()).code).toBe('no-render'); + + writeFileSync(path.join(base, 'secret.mp4'), 'secret'); + writeResult([{ format: 'mp4', file: '../../../secret.mp4' }]); + expect((await prepare()).code).toBe('no-render'); + + if (process.platform !== 'win32') { + symlinkSync( + path.join(base, 'secret.mp4'), + path.join(runDir, 'renders', 'link.mp4'), + ); + writeResult([{ format: 'mp4', file: 'renders/link.mp4' }]); + expect((await prepare()).code).toBe('no-render'); + } + expect(posters).toEqual([]); + expect(logger.text()).toContain(`share ${RUN_ID} gif: no-render`); + }); + + it('answers io when the poster cannot be made', async () => { + writeResult([{ format: 'mp4', file: 'renders/demo.mp4' }]); + posterSize = new Error('ffmpeg exited with 1'); + expect((await prepare()).code).toBe('io'); + expect(logger.text()).toContain(`share ${RUN_ID} mp4: io`); + expect(logger.text()).not.toContain('ffmpeg exited'); + }); + + it('ignores a malformed share.prepare', () => { + const share = preparer(); + const sent: unknown[] = []; + for (const message of [ + { requestId: 'not-a-uuid', runId: RUN_ID, format: 'mp4' }, + { requestId: randomUUID(), runId: '../x', format: 'mp4' }, + { requestId: randomUUID(), runId: RUN_ID, format: 'avi' }, + { requestId: randomUUID(), format: 'mp4' }, + ]) { + share.handle( + { type: 'share.prepare', ...message }, + { send: (m) => sent.push(m) }, + ); + } + expect(sent).toEqual([]); + expect(logger.text()).toMatch(/ignored a malformed share.prepare/); + }); + + it('makes one poster for two shares of the same render at once', async () => { + writeResult([{ format: 'mp4', file: 'renders/demo.mp4' }]); + let release = () => {}; + const gate = new Promise<void>((resolve) => { + release = resolve; + }); + const share = new SharePreparer({ + indexFile, + logger, + platform: process.platform, + makePoster: async (request) => { + posters.push(request); + await gate; + return 1234; + }, + }); + setTimeout(release, 200); + const answers = await Promise.all([ + prepare({}, share), + prepare({ requestId: randomUUID() }, share), + ]); + expect(answers.map((answer) => answer.type)).toEqual([ + 'share.prepared', + 'share.prepared', + ]); + expect(posters).toHaveLength(1); + }); +}); + +/** The width of a baseline or progressive JPEG, from its SOF marker. */ +function jpegWidth(bytes: Buffer): number { + expect(bytes.subarray(0, 2)).toEqual(Buffer.from([0xff, 0xd8])); + let at = 2; + while (at < bytes.length) { + const marker = bytes[at + 1] ?? 0; + const length = bytes.readUInt16BE(at + 2); + if (marker === 0xc0 || marker === 0xc2) return bytes.readUInt16BE(at + 7); + at += 2 + length; + } + throw new Error('no SOF marker'); +} + +describe('the poster (spec 349, Decision 3)', () => { + it('is taken at min(1500, durationMs / 2), after -i, at most 1280 wide', () => { + expect(posterAtMs(10_000)).toBe(1500); + expect(posterAtMs(1001)).toBe(500); + expect(posterAtMs(0)).toBe(0); + const args = posterArgs('in.gif', 'out.jpg', 500); + expect(args.indexOf('-ss')).toBeGreaterThan(args.indexOf('-i')); + expect(args).toContain('0.500'); + expect(args).toContain("scale='min(1280,iw)':-2"); + expect(args.slice(-3)).toEqual(['-q:v', '4', 'out.jpg']); + }); + + it.each([ + ['mp4', ['-c:v', 'libx264', '-pix_fmt', 'yuv420p']], + ['gif', []], + ] as const)( + 'makes a JPEG at most 1280 px wide from a %s render', + async (format, codec) => { + const render = path.join(runDir, 'renders', `demo.${format}`); + await runFfmpeg([ + '-y', + '-f', + 'lavfi', + '-i', + 'testsrc=size=1920x1080:rate=10:duration=1', + ...codec, + render, + ]); + const poster = posterPath(runDir, format, process.platform); + const size = await makePoster({ + render, + poster, + durationMs: 1000, + platform: process.platform, + }); + const bytes = readFileSync(poster); + expect(size).toBe(bytes.length); + expect(size).toBeLessThanOrEqual(POSTER_MAX_BYTES); + expect(jpegWidth(bytes)).toBe(1280); + }, + 60_000, + ); + + it('reuses a poster newer than its render, and remakes an older one', async () => { + const render = path.join(runDir, 'renders', 'demo.mp4'); + const poster = posterPath(runDir, 'mp4', process.platform); + const request = { + render, + poster, + durationMs: 4000, + platform: process.platform, + }; + const runs: string[][] = []; + const ffmpeg = async (args: readonly string[]) => { + runs.push([...args]); + writeFileSync(args.at(-1) ?? '', 'jpeg'); + }; + expect(await makePoster(request, ffmpeg)).toBe(4); + expect(runs).toHaveLength(1); + // Written to a temporary file, then renamed. + expect(runs[0]?.at(-1)).toBe(poster.replace(/\.jpg$/, '.tmp.jpg')); + + const later = new Date(statSync(render).mtimeMs + 10_000); + utimesSync(poster, later, later); + expect(await makePoster(request, ffmpeg)).toBe(4); + expect(runs).toHaveLength(1); + + const newer = new Date(later.getTime() + 10_000); + utimesSync(render, newer, newer); + await makePoster(request, ffmpeg); + expect(runs).toHaveLength(2); + }); + + it('rejects a poster over 1 MiB and leaves no temporary file when FFmpeg fails', async () => { + const render = path.join(runDir, 'renders', 'demo.mp4'); + const poster = posterPath(runDir, 'mp4', process.platform); + const request = { + render, + poster, + durationMs: 4000, + platform: process.platform, + }; + await expect( + makePoster(request, async (args) => { + writeFileSync(args.at(-1) ?? '', Buffer.alloc(POSTER_MAX_BYTES + 1)); + }), + ).rejects.toThrow(/bytes/); + + rmSync(poster); + await expect( + makePoster(request, async (args) => { + writeFileSync(args.at(-1) ?? '', 'half'); + throw new Error('ffmpeg exited with 1'); + }), + ).rejects.toThrow(/exited/); + expect(() => statSync(poster.replace(/\.jpg$/, '.tmp.jpg'))).toThrow(); + expect(() => statSync(poster)).toThrow(); + }); +}); From 1e70ff29dbc79de8b51956b8696fa87d2906beee Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 19:42:42 +0100 Subject: [PATCH 61/71] feat(web): add the schedule, health and stale API calls and the schedule rules The client gains the schedule, health and stale routes of spec #362, the run kind and the project stale count. lib/schedule.ts maps the form to the PUT body, validates the time, words the next check and orders the health list, covered by schedule.test.mjs. The copy for the whole of spec #363 lands in en.ts. --- apps/web/package.json | 2 +- apps/web/src/app/app/projects/_data.ts | 26 ++++ apps/web/src/i18n/en.ts | 107 +++++++++++++++ apps/web/src/lib/api.ts | 102 ++++++++++++++- apps/web/src/lib/schedule.test.mjs | 157 ++++++++++++++++++++++ apps/web/src/lib/schedule.ts | 173 +++++++++++++++++++++++++ 6 files changed, 565 insertions(+), 2 deletions(-) create mode 100644 apps/web/src/lib/schedule.test.mjs create mode 100644 apps/web/src/lib/schedule.ts diff --git a/apps/web/package.json b/apps/web/package.json index c1ef2f68..27a32f4d 100644 --- a/apps/web/package.json +++ b/apps/web/package.json @@ -7,7 +7,7 @@ "start": "next start -p 3670", "start:dev": "node scripts/dev.mjs", "lint": "biome lint src", - "test": "node --test src/lib/docs-nav.test.mjs src/lib/playback.test.mjs src/lib/launch.test.mjs src/lib/format-bytes.test.mjs src/lib/run-delete.test.mjs src/lib/player-choice.test.mjs src/lib/nav.test.mjs src/lib/crumbs.test.mjs src/lib/theme.test.mjs src/lib/overview-stats.test.mjs src/lib/status.test.mjs src/lib/share-page.test.mjs" + "test": "node --test src/lib/docs-nav.test.mjs src/lib/playback.test.mjs src/lib/launch.test.mjs src/lib/format-bytes.test.mjs src/lib/run-delete.test.mjs src/lib/player-choice.test.mjs src/lib/nav.test.mjs src/lib/crumbs.test.mjs src/lib/theme.test.mjs src/lib/overview-stats.test.mjs src/lib/status.test.mjs src/lib/share-page.test.mjs src/lib/schedule.test.mjs" }, "dependencies": { "@andrewbehma/glass-ui": "0.37.0", diff --git a/apps/web/src/app/app/projects/_data.ts b/apps/web/src/app/app/projects/_data.ts index 70653333..e62f2f19 100644 --- a/apps/web/src/app/app/projects/_data.ts +++ b/apps/web/src/app/app/projects/_data.ts @@ -1,14 +1,20 @@ import { cookies } from 'next/headers'; import { + getHealth, getRun, + getSchedule, listProjectRuns, listProjects, listRunners, + listStale, type Project, type ProjectRunsPage, + type ProjectSchedules, type RunDetail, type Runner, type RunStatusFilter, + type ScenarioHealth, + type StaleScenario, } from '@/lib/api'; async function target() { @@ -48,3 +54,23 @@ export async function getFirstRuns( if (result.ok) return result.data; return result.status === 404 ? 'not_found' : 'error'; } + +/** A project's check schedules (spec #363), or null when the API fails. */ +export async function getProjectSchedules( + id: string, +): Promise<ProjectSchedules | null> { + const result = await getSchedule(id, await target()); + return result.ok ? result.data : null; +} + +/** The per-scenario state of a project; empty when the API fails. */ +export async function getProjectHealth(id: string): Promise<ScenarioHealth[]> { + const result = await getHealth(id, await target()); + return result.ok ? result.data : []; +} + +/** The user's stale scenarios across projects, or null when the API fails. */ +export async function getStale(): Promise<StaleScenario[] | null> { + const result = await listStale(await target()); + return result.ok ? result.data : null; +} diff --git a/apps/web/src/i18n/en.ts b/apps/web/src/i18n/en.ts index ff496db2..4f1b5e37 100644 --- a/apps/web/src/i18n/en.ts +++ b/apps/web/src/i18n/en.ts @@ -157,6 +157,14 @@ export const en = { docs: 'Read how to make your first run', }, }, + stale: { + title: 'Stale demos', + allPassing: 'All passing', + since: 'since {when}', + sinceJustNow: 'since just now', + openRun: 'Open the run', + loadFailed: 'Stale demos could not be loaded.', + }, machines: { title: 'Machines', manage: 'Manage machines', @@ -402,10 +410,109 @@ export const en = { 'This machine cannot render one of the chosen formats. Update its demoflow CLI.', }, }, + // Scheduled checks (spec #363). + schedule: { + title: 'Scheduled checks', + none: 'Not checked on a schedule', + set: 'Set schedule', + summary: 'Checks {cadence} at {at} ({zone}) on {machine}', + summaryNoMachine: 'Checks {cadence} at {at} ({zone})', + next: 'Next check {when}', + nextSoon: 'Next check any moment', + nextOffline: 'Next check when {machine} is online', + lastPass: 'Last check {when}', + lastPassJustNow: 'Last check just now', + noPass: 'No check has run yet', + fromConfig: 'Set in demoflow.config.json', + docs: 'How scheduled checks work', + edit: 'Edit', + remove: 'Remove', + save: 'Save schedule', + saving: 'Saving…', + cancel: 'Cancel', + cadence: { + label: 'How often', + daily: 'Daily', + weekdays: 'Weekdays', + weekly: 'Weekly', + }, + cadenceText: { + daily: 'every day', + weekdays: 'every weekday', + weekly: 'every {day}', + }, + weekday: 'Day', + days: { + mon: 'Monday', + tue: 'Tuesday', + wed: 'Wednesday', + thu: 'Thursday', + fri: 'Friday', + sat: 'Saturday', + sun: 'Sunday', + }, + at: 'Time', + atHint: '24-hour, HH:MM', + zone: 'Time zone', + zoneValue: 'Time zone: {zone}', + changeZone: 'Change', + exclude: { + label: 'Leave out', + hint: 'Ticked scenarios are not checked.', + offline: 'Scenarios are listed when the machine is online', + saved: 'Left out: {list}', + none: 'No scenarios in demoflow/', + loading: 'Loading scenarios', + scenario: 'Leave out {name}', + }, + paused: { + configSchedule: + "The project's demoflow.config.json has its own schedule, which wins", + noMachine: 'The machine was removed', + cliTooOld: 'Update DemoFlow on {machine} to run scheduled checks', + }, + removeConfirm: { + title: 'Remove the schedule?', + body: "The project's demos are no longer checked on a schedule. Past check runs stay in the library.", + verb: 'Remove', + cancel: 'Keep', + }, + errors: { + time: 'Enter a time as HH:MM, 24-hour.', + zone: 'Choose a time zone.', + exclude: 'Leave out at most 100 scenarios.', + invalid: 'The schedule is not valid. Check the time and the time zone.', + configSchedule: + "The project's demoflow.config.json has its own schedule, so the website cannot set one.", + noMachine: + 'Bind this project to a folder on a machine before setting a schedule.', + }, + unbound: + 'Bind this project to a folder on a machine to check it on a schedule.', + loadFailed: 'We could not load the schedule. Try again in a moment.', + }, + health: { + title: 'Scenario health', + stale: 'Stale since {when}', + staleJustNow: 'Stale since just now', + passing: 'Passing', + lastRun: 'Last run', + }, + stale: { + one: 'Stale', + count: '{count} stale', + }, + }, + runs: { + kind: { + check: 'Check', + }, }, runPage: { title: 'Run of {name}', panel: 'Run details', + checkNoVideo: 'A check run records no video', + kind: 'Kind', actions: 'Actions', again: { button: 'Run again', diff --git a/apps/web/src/lib/api.ts b/apps/web/src/lib/api.ts index 104b4671..532fb8f0 100644 --- a/apps/web/src/lib/api.ts +++ b/apps/web/src/lib/api.ts @@ -86,7 +86,10 @@ async function errorCode(response: Response): Promise<string | undefined> { async function request<T>( path: string, - init: { method: 'GET' | 'POST' | 'PATCH' | 'DELETE'; body?: unknown }, + init: { + method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'; + body?: unknown; + }, target: Target = {}, ): Promise<ApiResult<T>> { const headers: Record<string, string> = {}; @@ -230,6 +233,8 @@ export interface ProjectRun { cliVersion: string; /** When the machine deleted the run's files (spec #233); null while present. */ artifactsDeletedAt: string | null; + /** `check` for a check run, which records no video (spec 360); absent or null otherwise. */ + kind?: 'check' | null; } export interface Project { @@ -239,6 +244,8 @@ export interface Project { /** Null for a project never bound, or whose machine was revoked. */ runner: { id: string; name: string } | null; runCount: number; + /** Scenarios whose latest run failed (spec #362); absent on an older API. */ + staleCount?: number; lastRun: ProjectRun | null; createdAt: string; updatedAt: string; @@ -447,6 +454,99 @@ export function cancelLaunch(projectId: string) { ); } +// Check schedules and the stale state (spec #363, contract from spec #362). + +export type ScheduleCadence = 'daily' | 'weekdays' | 'weekly'; + +/** A project's schedule, set on the website (`site`) or in its config. */ +export interface CheckSchedule { + source: 'site' | 'config'; + cadence: ScheduleCadence; + /** `mon`…`sun`; set only for `weekly`. */ + weekday: string | null; + /** `HH:MM`, 24-hour, in `timeZone`. */ + at: string; + timeZone: string; + exclude: string[]; + /** `config-schedule`, `no-machine` or `cli-too-old`; null while it runs. */ + pausedReason: string | null; + /** Null while paused. */ + nextDueAt: string | null; + lastPassAt: string | null; +} + +export interface ProjectSchedules { + site: CheckSchedule | null; + config: CheckSchedule | null; + machine: { + id: string; + name: string; + online: boolean; + /** The machine's own zone, once it has reported one. */ + zone: string | null; + } | null; +} + +/** What `PUT /projects/:id/schedule` takes. */ +export interface ScheduleBody { + cadence: ScheduleCadence; + weekday?: string; + at: string; + timeZone: string; + exclude: string[]; +} + +/** One scenario's state: `failed` is stale. */ +export interface ScenarioHealth { + scenarioPath: string; + scenarioName: string; + state: 'passed' | 'failed'; + since: string; + lastRunId: string; +} + +export interface StaleScenario { + projectId: string; + projectName: string; + scenarioPath: string; + scenarioName: string; + since: string; + lastRunId: string; +} + +export function getSchedule(projectId: string, target?: Target) { + return request<ProjectSchedules>( + `/projects/${encodeURIComponent(projectId)}/schedule`, + { method: 'GET' }, + target, + ); +} + +export function putSchedule(projectId: string, body: ScheduleBody) { + return request<CheckSchedule>( + `/projects/${encodeURIComponent(projectId)}/schedule`, + { method: 'PUT', body }, + ); +} + +export function deleteSchedule(projectId: string) { + return request<void>(`/projects/${encodeURIComponent(projectId)}/schedule`, { + method: 'DELETE', + }); +} + +export function getHealth(projectId: string, target?: Target) { + return request<ScenarioHealth[]>( + `/projects/${encodeURIComponent(projectId)}/health`, + { method: 'GET' }, + target, + ); +} + +export function listStale(target?: Target) { + return request<StaleScenario[]>('/checks/stale', { method: 'GET' }, target); +} + export type RunStatusFilter = ProjectRun['status']; export function listProjectRuns( diff --git a/apps/web/src/lib/schedule.test.mjs b/apps/web/src/lib/schedule.test.mjs new file mode 100644 index 00000000..76163b96 --- /dev/null +++ b/apps/web/src/lib/schedule.test.mjs @@ -0,0 +1,157 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { + defaultZone, + formatUntil, + formError, + formFor, + healthOrder, + isValidTime, + MAX_EXCLUDES, + pausedKey, + scheduleBody, + scheduleErrorKey, + toggleExclude, +} from './schedule.ts'; + +const saved = { + source: 'site', + cadence: 'weekly', + weekday: 'thu', + at: '18:15', + timeZone: 'Europe/Berlin', + exclude: ['demoflow/a.demo.json'], + pausedReason: null, + nextDueAt: null, + lastPassAt: null, +}; + +test('a new schedule starts on weekdays at 09:00 in the given zone', () => { + assert.deepEqual(formFor(null, 'Europe/Kyiv'), { + cadence: 'weekdays', + weekday: 'mon', + at: '09:00', + timeZone: 'Europe/Kyiv', + exclude: [], + }); +}); + +test('an existing schedule fills the form', () => { + const form = formFor(saved, 'UTC'); + assert.equal(form.cadence, 'weekly'); + assert.equal(form.weekday, 'thu'); + assert.equal(form.at, '18:15'); + assert.equal(form.timeZone, 'Europe/Berlin'); + assert.deepEqual(form.exclude, ['demoflow/a.demo.json']); + assert.notEqual(form.exclude, saved.exclude); +}); + +test('a schedule without a weekday falls back to Monday for the hidden select', () => { + assert.equal( + formFor({ ...saved, cadence: 'daily', weekday: null }, 'UTC').weekday, + 'mon', + ); +}); + +test('the machine zone wins over the browser zone', () => { + assert.equal(defaultZone('Asia/Tokyo', 'Europe/Berlin'), 'Asia/Tokyo'); + assert.equal(defaultZone(null, 'Europe/Berlin'), 'Europe/Berlin'); + assert.equal(defaultZone(null, undefined), 'UTC'); +}); + +test('weekly sends its weekday; daily and weekdays send none', () => { + const form = formFor(saved, 'UTC'); + assert.deepEqual(scheduleBody(form), { + cadence: 'weekly', + weekday: 'thu', + at: '18:15', + timeZone: 'Europe/Berlin', + exclude: ['demoflow/a.demo.json'], + }); + for (const cadence of ['daily', 'weekdays']) { + const body = scheduleBody({ ...form, cadence }); + assert.equal(body.cadence, cadence); + assert.equal('weekday' in body, false); + } +}); + +test('the body drops duplicate excludes', () => { + const form = { ...formFor(null, 'UTC'), exclude: ['a', 'b', 'a'] }; + assert.deepEqual(scheduleBody(form).exclude, ['a', 'b']); +}); + +test('only HH:MM in 24 hours is a valid time', () => { + for (const at of ['00:00', '09:30', '23:59']) { + assert.equal(isValidTime(at), true, at); + } + for (const at of ['', '9:30', '24:00', '25:00', '12:60', '12:3', 'ab:cd']) { + assert.equal(isValidTime(at), false, at); + } +}); + +test('an invalid time, an empty zone or too many excludes cannot be saved', () => { + const form = formFor(null, 'UTC'); + assert.equal(formError(form), null); + assert.equal(formError({ ...form, at: '25:00' }), 'time'); + assert.equal(formError({ ...form, at: '' }), 'time'); + assert.equal(formError({ ...form, timeZone: ' ' }), 'zone'); + const many = Array.from({ length: MAX_EXCLUDES + 1 }, (_, i) => `s${i}`); + assert.equal(formError({ ...form, exclude: many }), 'exclude'); +}); + +test('ticking a scenario leaves it out; unticking brings it back', () => { + assert.deepEqual(toggleExclude([], 'a', true), ['a']); + assert.deepEqual(toggleExclude(['a'], 'a', true), ['a']); + assert.deepEqual(toggleExclude(['a', 'b'], 'a', false), ['b']); +}); + +test('the next check reads as a time ahead', () => { + const now = Date.parse('2026-10-26T08:00:00Z'); + assert.equal(formatUntil('2026-10-26T08:00:30Z', now), null); + assert.equal(formatUntil('2026-10-26T07:00:00Z', now), null); + assert.equal(formatUntil('2026-10-26T08:30:00Z', now), 'in 30 minutes'); + assert.equal(formatUntil('2026-10-26T09:30:00Z', now), 'in 2 hours'); + assert.equal(formatUntil('2026-10-27T08:00:00Z', now), 'tomorrow'); + assert.equal(formatUntil('2026-10-29T08:00:00Z', now), 'in 3 days'); +}); + +test('each paused reason has its banner', () => { + assert.equal( + pausedKey('config-schedule'), + 'projects.schedule.paused.configSchedule', + ); + assert.equal(pausedKey('no-machine'), 'projects.schedule.paused.noMachine'); + assert.equal(pausedKey('cli-too-old'), 'projects.schedule.paused.cliTooOld'); + assert.equal(pausedKey(null), null); + assert.equal(pausedKey('something-new'), null); +}); + +test('save errors map to their messages', () => { + assert.equal( + scheduleErrorKey(409, 'config-schedule'), + 'projects.schedule.errors.configSchedule', + ); + assert.equal( + scheduleErrorKey(409, 'no-machine'), + 'projects.schedule.errors.noMachine', + ); + assert.equal(scheduleErrorKey(404, 'not-found'), 'projects.errors.notFound'); + assert.equal( + scheduleErrorKey(400, undefined), + 'projects.schedule.errors.invalid', + ); + assert.equal(scheduleErrorKey(undefined, undefined), 'auth.errors.unknown'); +}); + +test('stale scenarios come first, then by name', () => { + const rows = [ + { scenarioName: 'b', state: 'passed' }, + { scenarioName: 'c', state: 'failed' }, + { scenarioName: 'a', state: 'passed' }, + { scenarioName: 'a', state: 'failed' }, + ]; + assert.deepEqual( + healthOrder(rows).map((row) => `${row.state}:${row.scenarioName}`), + ['failed:a', 'failed:c', 'passed:a', 'passed:b'], + ); +}); diff --git a/apps/web/src/lib/schedule.ts b/apps/web/src/lib/schedule.ts new file mode 100644 index 00000000..c18fec72 --- /dev/null +++ b/apps/web/src/lib/schedule.ts @@ -0,0 +1,173 @@ +// Rules for the "Scheduled checks" card (spec #363). Plain functions, so they +// are unit-tested without a browser. + +import type { CheckSchedule, ScheduleBody, ScheduleCadence } from './api'; + +export const CADENCES: readonly ScheduleCadence[] = [ + 'daily', + 'weekdays', + 'weekly', +]; + +/** Monday first, the way a person reads a week. */ +export const WEEKDAYS = [ + 'mon', + 'tue', + 'wed', + 'thu', + 'fri', + 'sat', + 'sun', +] as const; + +export type Weekday = (typeof WEEKDAYS)[number]; + +/** `HH:MM`, 24-hour: the API's rule (spec #362, Decision 3). */ +const TIME_OF_DAY = /^([01]\d|2[0-3]):[0-5]\d$/; + +/** At most this many scenarios left out of a pass (spec #362). */ +export const MAX_EXCLUDES = 100; + +/** What the form holds; `weekday` is kept while hidden so Weekly remembers it. */ +export interface ScheduleForm { + cadence: ScheduleCadence; + weekday: Weekday; + at: string; + timeZone: string; + exclude: string[]; +} + +function isWeekday(value: string | null): value is Weekday { + return (WEEKDAYS as readonly (string | null)[]).includes(value); +} + +/** The zone a new schedule starts in: the machine's when known, else the browser's. */ +export function defaultZone( + machineZone: string | null | undefined, + browserZone: string | undefined, +): string { + return machineZone || browserZone || 'UTC'; +} + +/** The form for an existing schedule, or a new one (weekdays at 09:00) in `zone`. */ +export function formFor( + schedule: CheckSchedule | null, + zone: string, +): ScheduleForm { + if (schedule === null) { + return { + cadence: 'weekdays', + weekday: 'mon', + at: '09:00', + timeZone: zone, + exclude: [], + }; + } + return { + cadence: schedule.cadence, + weekday: isWeekday(schedule.weekday) ? schedule.weekday : 'mon', + at: schedule.at, + timeZone: schedule.timeZone, + exclude: [...schedule.exclude], + }; +} + +export function isValidTime(at: string): boolean { + return TIME_OF_DAY.test(at); +} + +export type ScheduleFormError = 'time' | 'zone' | 'exclude'; + +/** Why the form cannot be saved, or null when it can. */ +export function formError(form: ScheduleForm): ScheduleFormError | null { + if (!isValidTime(form.at)) return 'time'; + if (form.timeZone.trim().length === 0) return 'zone'; + if (form.exclude.length > MAX_EXCLUDES) return 'exclude'; + return null; +} + +/** The `PUT` body: `weekday` only with `weekly`, which the API requires. */ +export function scheduleBody(form: ScheduleForm): ScheduleBody { + const body: ScheduleBody = { + cadence: form.cadence, + at: form.at, + timeZone: form.timeZone, + exclude: [...new Set(form.exclude)], + }; + if (form.cadence === 'weekly') body.weekday = form.weekday; + return body; +} + +/** Ticks or unticks one scenario id in the "Leave out" list. */ +export function toggleExclude( + exclude: readonly string[], + id: string, + excluded: boolean, +): string[] { + const rest = exclude.filter((candidate) => candidate !== id); + return excluded ? [...rest, id] : rest; +} + +const future = new Intl.RelativeTimeFormat('en', { numeric: 'auto' }); + +/** + * "in 3 hours" for an ISO time ahead of `now` (epoch ms). Under a minute, or + * already past, returns null so the caller can say "any moment". + */ +export function formatUntil(iso: string, now: number): string | null { + const seconds = Math.round((new Date(iso).getTime() - now) / 1000); + if (seconds < 60) return null; + if (seconds < 3600) return future.format(Math.round(seconds / 60), 'minute'); + if (seconds < 86400) return future.format(Math.round(seconds / 3600), 'hour'); + return future.format(Math.round(seconds / 86400), 'day'); +} + +export type PausedKey = + | 'projects.schedule.paused.configSchedule' + | 'projects.schedule.paused.noMachine' + | 'projects.schedule.paused.cliTooOld'; + +/** The banner for a paused schedule; null when it runs or the reason is new. */ +export function pausedKey(reason: string | null): PausedKey | null { + switch (reason) { + case 'config-schedule': + return 'projects.schedule.paused.configSchedule'; + case 'no-machine': + return 'projects.schedule.paused.noMachine'; + case 'cli-too-old': + return 'projects.schedule.paused.cliTooOld'; + default: + return null; + } +} + +export type ScheduleErrorKey = + | 'projects.schedule.errors.configSchedule' + | 'projects.schedule.errors.noMachine' + | 'projects.schedule.errors.invalid' + | 'projects.errors.notFound' + | 'auth.errors.unknown'; + +/** The message for a failed save or remove. */ +export function scheduleErrorKey( + status: number | undefined, + code: string | undefined, +): ScheduleErrorKey { + if (code === 'config-schedule') { + return 'projects.schedule.errors.configSchedule'; + } + if (code === 'no-machine') return 'projects.schedule.errors.noMachine'; + if (status === 404) return 'projects.errors.notFound'; + if (status === 400) return 'projects.schedule.errors.invalid'; + return 'auth.errors.unknown'; +} + +/** Stale rows first, then by name, so the broken ones lead. */ +export function healthOrder<T extends { state: string; scenarioName: string }>( + rows: readonly T[], +): T[] { + return [...rows].sort((a, b) => { + const stale = Number(b.state === 'failed') - Number(a.state === 'failed'); + return stale !== 0 ? stale : a.scenarioName.localeCompare(b.scenarioName); + }); +} From a54379de6409c883576f4d1805c8d31156012f68 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 19:42:56 +0100 Subject: [PATCH 62/71] feat(web): show the check schedule and the scenario health on the project page The Scheduled checks card sits under the project header: set, edit and remove the website schedule, show a config schedule read-only with a link to the docs, and warn when a schedule is paused. Below it the health list shows each scenario as stale or passing, stale rows first, with a link to the last run. --- apps/web/src/app/app/projects/[id]/page.tsx | 21 +- .../components/projects/check-schedule.tsx | 535 ++++++++++++++++++ .../components/projects/scenario-health.tsx | 79 +++ .../src/components/projects/stale-badge.tsx | 23 + 4 files changed, 656 insertions(+), 2 deletions(-) create mode 100644 apps/web/src/components/projects/check-schedule.tsx create mode 100644 apps/web/src/components/projects/scenario-health.tsx create mode 100644 apps/web/src/components/projects/stale-badge.tsx diff --git a/apps/web/src/app/app/projects/[id]/page.tsx b/apps/web/src/app/app/projects/[id]/page.tsx index e6fed326..2e73f4c4 100644 --- a/apps/web/src/app/app/projects/[id]/page.tsx +++ b/apps/web/src/app/app/projects/[id]/page.tsx @@ -3,13 +3,20 @@ import { Card } from '@andrewbehma/glass-ui/card'; import { PageHeader } from '@andrewbehma/glass-ui/page-header'; import { SectionHeader } from '@andrewbehma/glass-ui/section-header'; import { notFound } from 'next/navigation'; +import { CheckSchedule } from '@/components/projects/check-schedule'; import { MachinePill } from '@/components/projects/machine-pill'; import { ProjectPath } from '@/components/projects/project-path'; import { RunsTable } from '@/components/projects/runs-table'; +import { ScenarioHealth } from '@/components/projects/scenario-health'; import { StartRun } from '@/components/projects/start-run'; import { CrumbName } from '@/components/shell/crumb-names'; import { t } from '@/i18n'; -import { getFirstRuns, getProjects } from '../_data'; +import { + getFirstRuns, + getProjectHealth, + getProjectSchedules, + getProjects, +} from '../_data'; export default async function ProjectLibraryPage({ params, @@ -22,9 +29,11 @@ export default async function ProjectLibraryPage({ const { status: rawStatus } = await searchParams; const status = rawStatus === 'passed' || rawStatus === 'failed' ? rawStatus : undefined; - const [projects, runs] = await Promise.all([ + const [projects, runs, schedules, health] = await Promise.all([ getProjects(), getFirstRuns(id, status), + getProjectSchedules(id), + getProjectHealth(id), ]); if (runs === 'not_found') notFound(); const project = projects?.find((candidate) => candidate.id === id); @@ -49,6 +58,14 @@ export default async function ProjectLibraryPage({ ) : null } /> + {project ? ( + <CheckSchedule + projectId={id} + rootPath={project.rootPath} + schedules={schedules} + /> + ) : null} + <ScenarioHealth projectId={id} rows={health} /> {project ? ( <StartRun projectId={id} diff --git a/apps/web/src/components/projects/check-schedule.tsx b/apps/web/src/components/projects/check-schedule.tsx new file mode 100644 index 00000000..9516e8a6 --- /dev/null +++ b/apps/web/src/components/projects/check-schedule.tsx @@ -0,0 +1,535 @@ +'use client'; + +import { Banner } from '@andrewbehma/glass-ui/banner'; +import { Button } from '@andrewbehma/glass-ui/button'; +import { Card } from '@andrewbehma/glass-ui/card'; +import { Checkbox } from '@andrewbehma/glass-ui/checkbox'; +import { ConfirmDialog } from '@andrewbehma/glass-ui/confirm-dialog'; +import { Field, Input, Select } from '@andrewbehma/glass-ui/field'; +import { SectionHeader } from '@andrewbehma/glass-ui/section-header'; +import { + SegmentedControl, + SegmentedControlItem, +} from '@andrewbehma/glass-ui/segmented-control'; +import { Spinner } from '@andrewbehma/glass-ui/spinner'; +import Link from 'next/link'; +import { useRouter } from 'next/navigation'; +import { type FormEvent, useEffect, useId, useState } from 'react'; +import { t } from '@/i18n'; +import { + deleteSchedule, + listScenarios, + type ProjectSchedules, + putSchedule, + type ScenarioEntry, + type CheckSchedule as Schedule, +} from '@/lib/api'; +import { formatDate } from '@/lib/format-date'; +import { formatRelative } from '@/lib/format-relative'; +import { + CADENCES, + defaultZone, + formatUntil, + formError, + formFor, + pausedKey, + type ScheduleErrorKey, + type ScheduleForm, + scheduleBody, + scheduleErrorKey, + toggleExclude, + WEEKDAYS, + type Weekday, +} from '@/lib/schedule'; + +type Machine = NonNullable<ProjectSchedules['machine']>; + +type FormErrorKey = + | 'projects.schedule.errors.time' + | 'projects.schedule.errors.zone' + | 'projects.schedule.errors.exclude'; + +/** + * The "Scheduled checks" card of the project page (spec #363, Decision 1): the + * website schedule with its form, or the config schedule read-only, and why a + * schedule is paused. + */ +export function CheckSchedule({ + projectId, + rootPath, + schedules, +}: { + projectId: string; + rootPath: string | null; + schedules: ProjectSchedules | null; +}) { + const router = useRouter(); + const [site, setSite] = useState<Schedule | null>(schedules?.site ?? null); + const [form, setForm] = useState<ScheduleForm | null>(null); + const [error, setError] = useState<ScheduleErrorKey | undefined>(); + const [busy, setBusy] = useState(false); + const [confirming, setConfirming] = useState(false); + + const machine = schedules?.machine ?? null; + const config = schedules?.config ?? null; + + function edit() { + const browserZone = Intl.DateTimeFormat().resolvedOptions().timeZone; + setForm(formFor(site, defaultZone(machine?.zone, browserZone))); + setError(undefined); + } + + async function save(next: ScheduleForm) { + setBusy(true); + setError(undefined); + const result = await putSchedule(projectId, scheduleBody(next)); + setBusy(false); + if (!result.ok) { + setError(scheduleErrorKey(result.status, result.code)); + if (result.status === 404 || result.status === 409) router.refresh(); + return; + } + setSite(result.data); + setForm(null); + router.refresh(); + } + + async function remove() { + setBusy(true); + setError(undefined); + const result = await deleteSchedule(projectId); + setBusy(false); + setConfirming(false); + if (!result.ok && result.status !== 404) { + setError(scheduleErrorKey(result.status, result.code)); + return; + } + setSite(null); + router.refresh(); + } + + return ( + <section aria-labelledby="check-schedule" className="flex flex-col gap-3"> + <SectionHeader + title={t('projects.schedule.title')} + headingId="check-schedule" + /> + <Card pad="md" className="flex flex-col gap-3"> + {error ? <Banner tone="danger">{t(error)}</Banner> : null} + {schedules === null ? ( + <p className="text-sm text-ink-2"> + {t('projects.schedule.loadFailed')} + </p> + ) : config !== null ? ( + <> + <Summary schedule={config} machine={machine} /> + <p className="flex flex-wrap items-center gap-x-2 gap-y-1 text-sm text-ink-2"> + <span>{t('projects.schedule.fromConfig')}</span> + <span aria-hidden>·</span> + <Link + href="/docs/checks" + className="text-ink underline underline-offset-2" + > + {t('projects.schedule.docs')} + </Link> + </p> + </> + ) : form !== null && machine !== null ? ( + <EditForm + projectId={projectId} + machine={machine} + initial={form} + busy={busy} + onSave={(next) => void save(next)} + onCancel={() => { + setForm(null); + setError(undefined); + }} + /> + ) : site !== null ? ( + <> + <Summary schedule={site} machine={machine} /> + <div className="flex flex-wrap gap-2"> + {machine !== null ? ( + <Button type="button" variant="glass" size="sm" onClick={edit}> + {t('projects.schedule.edit')} + </Button> + ) : null} + <Button + type="button" + variant="danger" + size="sm" + disabled={busy} + onClick={() => setConfirming(true)} + > + {t('projects.schedule.remove')} + </Button> + </div> + </> + ) : rootPath === null || machine === null ? ( + <p className="text-sm text-ink-2">{t('projects.schedule.unbound')}</p> + ) : ( + <div className="flex flex-wrap items-center justify-between gap-3"> + <p className="text-sm text-ink-2">{t('projects.schedule.none')}</p> + <Button type="button" variant="solid" size="sm" onClick={edit}> + {t('projects.schedule.set')} + </Button> + </div> + )} + </Card> + <ConfirmDialog + open={confirming} + onOpenChange={setConfirming} + title={t('projects.schedule.removeConfirm.title')} + consequence={t('projects.schedule.removeConfirm.body')} + verb={t('projects.schedule.removeConfirm.verb')} + cancelLabel={t('projects.schedule.removeConfirm.cancel')} + busy={busy} + onConfirm={() => void remove()} + /> + </section> + ); +} + +function cadenceText(schedule: Schedule): string { + if (schedule.cadence !== 'weekly') { + return t(`projects.schedule.cadenceText.${schedule.cadence}`); + } + const day = (WEEKDAYS as readonly (string | null)[]).includes( + schedule.weekday, + ) + ? t(`projects.schedule.days.${schedule.weekday as Weekday}`) + : ''; + return t('projects.schedule.cadenceText.weekly', { day }); +} + +/** "Checks every weekday at 09:30 (Europe/Berlin) on …", the next check and the last. */ +function Summary({ + schedule, + machine, +}: { + schedule: Schedule; + machine: Machine | null; +}) { + const now = Date.now(); + const paused = pausedKey(schedule.pausedReason); + const params = { + cadence: cadenceText(schedule), + at: schedule.at, + zone: schedule.timeZone, + }; + return ( + <div className="flex flex-col gap-2"> + {paused ? ( + <Banner tone="warn"> + {t(paused, { machine: machine?.name ?? '' })} + </Banner> + ) : null} + <p className="font-medium text-ink"> + {machine + ? t('projects.schedule.summary', { ...params, machine: machine.name }) + : t('projects.schedule.summaryNoMachine', params)} + </p> + <ul className="flex flex-col gap-1 text-sm text-ink-2"> + {paused ? null : machine !== null && !machine.online ? ( + <li> + {t('projects.schedule.nextOffline', { machine: machine.name })} + </li> + ) : schedule.nextDueAt ? ( + <li> + <time + dateTime={schedule.nextDueAt} + title={formatDate(schedule.nextDueAt)} + suppressHydrationWarning + > + {(() => { + const when = formatUntil(schedule.nextDueAt, now); + return when + ? t('projects.schedule.next', { when }) + : t('projects.schedule.nextSoon'); + })()} + </time> + </li> + ) : null} + <li> + {schedule.lastPassAt ? ( + <time + dateTime={schedule.lastPassAt} + title={formatDate(schedule.lastPassAt)} + suppressHydrationWarning + > + {(() => { + const when = formatRelative(schedule.lastPassAt, now); + return when + ? t('projects.schedule.lastPass', { when }) + : t('projects.schedule.lastPassJustNow'); + })()} + </time> + ) : ( + t('projects.schedule.noPass') + )} + </li> + {schedule.exclude.length > 0 ? ( + <li className="break-all"> + {t('projects.schedule.exclude.saved', { + list: schedule.exclude.join(', '), + })} + </li> + ) : null} + </ul> + </div> + ); +} + +/** Every IANA zone the browser knows, with the current one kept first. */ +function zoneOptions(current: string): string[] { + const known = + typeof Intl.supportedValuesOf === 'function' + ? Intl.supportedValuesOf('timeZone') + : []; + return [current, ...known.filter((zone) => zone !== current)]; +} + +function EditForm({ + projectId, + machine, + initial, + busy, + onSave, + onCancel, +}: { + projectId: string; + machine: Machine; + initial: ScheduleForm; + busy: boolean; + onSave: (form: ScheduleForm) => void; + onCancel: () => void; +}) { + const weekdayId = useId(); + const atId = useId(); + const zoneId = useId(); + const [form, setForm] = useState(initial); + const [invalid, setInvalid] = useState<FormErrorKey | undefined>(); + const [choosingZone, setChoosingZone] = useState(false); + const [scenarios, setScenarios] = useState<ScenarioEntry[] | null>(null); + const [scenariosFailed, setScenariosFailed] = useState(false); + + // The "Leave out" checklist needs the machine online (spec #363). + useEffect(() => { + if (!machine.online) return; + let live = true; + void listScenarios(projectId).then((result) => { + if (!live) return; + if (result.ok) setScenarios(result.data.scenarios); + else setScenariosFailed(true); + }); + return () => { + live = false; + }; + }, [projectId, machine.online]); + + function update(patch: Partial<ScheduleForm>) { + setForm((current) => ({ ...current, ...patch })); + setInvalid(undefined); + } + + function submit(event: FormEvent) { + event.preventDefault(); + const problem = formError(form); + if (problem) { + setInvalid(`projects.schedule.errors.${problem}`); + return; + } + onSave(form); + } + + // Saved ids the machine no longer lists stay visible, so they can be unticked. + const known = new Set(scenarios?.map((scenario) => scenario.id)); + const checklist: ScenarioEntry[] = [ + ...(scenarios ?? []), + ...form.exclude + .filter((id) => !known.has(id)) + .map((id) => ({ id, name: id })), + ]; + + return ( + <form + className="flex flex-col gap-4" + aria-label={t('projects.schedule.title')} + noValidate + onSubmit={submit} + > + {invalid ? <Banner tone="danger">{t(invalid)}</Banner> : null} + <fieldset className="flex flex-col gap-2"> + <legend className="mb-2 text-sm font-medium text-ink"> + {t('projects.schedule.cadence.label')} + </legend> + <div className="max-w-full overflow-x-auto"> + <SegmentedControl + aria-label={t('projects.schedule.cadence.label')} + size="sm" + > + {CADENCES.map((cadence) => ( + <SegmentedControlItem + key={cadence} + active={cadence === form.cadence} + layoutId="schedule-cadence" + > + <button + type="button" + aria-pressed={cadence === form.cadence} + className="whitespace-nowrap px-3 py-1 text-sm" + onClick={() => update({ cadence })} + > + {t(`projects.schedule.cadence.${cadence}`)} + </button> + </SegmentedControlItem> + ))} + </SegmentedControl> + </div> + </fieldset> + <div className="flex flex-wrap gap-3"> + {form.cadence === 'weekly' ? ( + <div className="min-w-40 flex-1"> + <Field label={t('projects.schedule.weekday')} htmlFor={weekdayId}> + <Select + id={weekdayId} + value={form.weekday} + onChange={(event) => + update({ weekday: event.target.value as Weekday }) + } + > + {WEEKDAYS.map((day) => ( + <option key={day} value={day}> + {t(`projects.schedule.days.${day}`)} + </option> + ))} + </Select> + </Field> + </div> + ) : null} + <div className="min-w-40 flex-1"> + <Field + label={t('projects.schedule.at')} + hint={t('projects.schedule.atHint')} + htmlFor={atId} + error={ + invalid === 'projects.schedule.errors.time' + ? t(invalid) + : undefined + } + > + <Input + id={atId} + value={form.at} + inputMode="numeric" + placeholder="09:00" + maxLength={5} + aria-invalid={invalid === 'projects.schedule.errors.time'} + onChange={(event) => update({ at: event.target.value.trim() })} + /> + </Field> + </div> + </div> + {choosingZone ? ( + <Field label={t('projects.schedule.zone')} htmlFor={zoneId}> + <Select + id={zoneId} + value={form.timeZone} + onChange={(event) => update({ timeZone: event.target.value })} + > + {zoneOptions(form.timeZone).map((zone) => ( + <option key={zone} value={zone}> + {zone} + </option> + ))} + </Select> + </Field> + ) : ( + <p className="flex flex-wrap items-center gap-2 text-sm text-ink-2"> + <span> + {t('projects.schedule.zoneValue', { zone: form.timeZone })} + </span> + <Button + type="button" + variant="ghost" + size="sm" + onClick={() => setChoosingZone(true)} + > + {t('projects.schedule.changeZone')} + </Button> + </p> + )} + <fieldset className="flex flex-col gap-2"> + <legend className="mb-1 text-sm font-medium text-ink"> + {t('projects.schedule.exclude.label')} + </legend> + {!machine.online || scenariosFailed ? ( + <> + <p className="text-sm text-ink-2"> + {t('projects.schedule.exclude.offline')} + </p> + {form.exclude.length > 0 ? ( + <p className="break-all text-sm text-ink-2"> + {t('projects.schedule.exclude.saved', { + list: form.exclude.join(', '), + })} + </p> + ) : null} + </> + ) : scenarios === null ? ( + <Spinner size="sm" label={t('projects.schedule.exclude.loading')} /> + ) : checklist.length === 0 ? ( + <p className="text-sm text-ink-2"> + {t('projects.schedule.exclude.none')} + </p> + ) : ( + <> + <p className="text-sm text-ink-2"> + {t('projects.schedule.exclude.hint')} + </p> + <ul className="flex max-h-64 flex-col gap-2 overflow-y-auto"> + {checklist.map((scenario) => ( + <li key={scenario.id}> + <Checkbox + label={scenario.name} + hint={ + scenario.name === scenario.id ? undefined : scenario.id + } + aria-label={t('projects.schedule.exclude.scenario', { + name: scenario.name, + })} + checked={form.exclude.includes(scenario.id)} + onChange={(event) => + update({ + exclude: toggleExclude( + form.exclude, + scenario.id, + event.target.checked, + ), + }) + } + /> + </li> + ))} + </ul> + </> + )} + </fieldset> + <div className="flex flex-wrap gap-2"> + <Button type="submit" size="sm" disabled={busy}> + {busy ? t('projects.schedule.saving') : t('projects.schedule.save')} + </Button> + <Button + type="button" + variant="ghost" + size="sm" + disabled={busy} + onClick={onCancel} + > + {t('projects.schedule.cancel')} + </Button> + </div> + </form> + ); +} diff --git a/apps/web/src/components/projects/scenario-health.tsx b/apps/web/src/components/projects/scenario-health.tsx new file mode 100644 index 00000000..069caf7a --- /dev/null +++ b/apps/web/src/components/projects/scenario-health.tsx @@ -0,0 +1,79 @@ +import { Card } from '@andrewbehma/glass-ui/card'; +import { SectionHeader } from '@andrewbehma/glass-ui/section-header'; +import Link from 'next/link'; +import { t } from '@/i18n'; +import type { ScenarioHealth as Health } from '@/lib/api'; +import { formatDate } from '@/lib/format-date'; +import { formatRelative } from '@/lib/format-relative'; +import { healthOrder } from '@/lib/schedule'; +import { StaleBadge } from './stale-badge'; + +/** + * Each scenario's last check state on the project page (spec #363, Decision 3): + * stale rows first, each with a link to its last run. Hidden when the API has + * no state for any scenario. + */ +export function ScenarioHealth({ + projectId, + rows, +}: { + projectId: string; + rows: Health[]; +}) { + if (rows.length === 0) return null; + const now = Date.now(); + return ( + <section aria-labelledby="scenario-health" className="flex flex-col gap-3"> + <SectionHeader + title={t('projects.health.title')} + headingId="scenario-health" + /> + <Card pad="none"> + <ul aria-label={t('projects.health.title')} className="flex flex-col"> + {healthOrder(rows).map((row) => { + const when = formatRelative(row.since, now); + return ( + <li + key={row.scenarioPath} + className="flex flex-col gap-2 border-b border-line px-4 py-3 last:border-0 sm:flex-row sm:items-center sm:justify-between" + > + <div className="flex min-w-0 flex-col gap-1"> + <span className="flex flex-wrap items-center gap-2"> + <span className="break-words font-medium text-ink"> + {row.scenarioName} + </span> + {row.state === 'failed' ? <StaleBadge /> : null} + </span> + <span className="break-all font-mono text-xs text-ink-2"> + {row.scenarioPath} + </span> + </div> + <div className="flex shrink-0 flex-wrap items-center gap-x-3 gap-y-1 text-sm text-ink-2"> + {row.state === 'failed' ? ( + <time + dateTime={row.since} + title={formatDate(row.since)} + suppressHydrationWarning + > + {when + ? t('projects.health.stale', { when }) + : t('projects.health.staleJustNow')} + </time> + ) : ( + <span>{t('projects.health.passing')}</span> + )} + <Link + href={`/app/projects/${encodeURIComponent(projectId)}/runs/${encodeURIComponent(row.lastRunId)}`} + className="text-ink underline underline-offset-2" + > + {t('projects.health.lastRun')} + </Link> + </div> + </li> + ); + })} + </ul> + </Card> + </section> + ); +} diff --git a/apps/web/src/components/projects/stale-badge.tsx b/apps/web/src/components/projects/stale-badge.tsx new file mode 100644 index 00000000..f05d6570 --- /dev/null +++ b/apps/web/src/components/projects/stale-badge.tsx @@ -0,0 +1,23 @@ +import { Badge } from '@andrewbehma/glass-ui/badge'; +import { t } from '@/i18n'; + +/** + * The stale mark (spec #363, Decision 2): "Stale" on a scenario, "N stale" + * with `count` on a project. Nothing at a zero count — an absent badge is the + * healthy state. The word carries the meaning, so it never depends on colour + * alone. + */ +export function StaleBadge({ count }: { count?: number }) { + if (count !== undefined && count <= 0) return null; + return ( + <Badge + tone="danger" + size="md" + label={ + count === undefined + ? t('projects.stale.one') + : t('projects.stale.count', { count }) + } + /> + ); +} From 66874b7f675f060203bd94adf15d05a1ba3ad773 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 19:43:06 +0100 Subject: [PATCH 63/71] feat(web): mark stale projects, label check runs and list stale demos on /app The project list shows "N stale" next to a project with broken scenarios. A check run carries a Check label in the run library, and its run page says it records no video instead of showing the player, the format switch or the download. /app lists up to ten stale scenarios, says "All passing" when a user with a schedule has none, and hides the block for a user without one. --- apps/web/src/app/app/page.tsx | 25 +++++- .../app/projects/[id]/runs/[runId]/page.tsx | 11 +++ .../src/components/dashboard/stale-demos.tsx | 76 +++++++++++++++++++ .../src/components/player/run-playback.tsx | 11 ++- .../src/components/projects/project-list.tsx | 16 ++-- .../src/components/projects/runs-table.tsx | 22 ++++-- 6 files changed, 145 insertions(+), 16 deletions(-) create mode 100644 apps/web/src/components/dashboard/stale-demos.tsx diff --git a/apps/web/src/app/app/page.tsx b/apps/web/src/app/app/page.tsx index 6035945d..c8b690e0 100644 --- a/apps/web/src/app/app/page.tsx +++ b/apps/web/src/app/app/page.tsx @@ -2,13 +2,33 @@ import { PageHeader } from '@andrewbehma/glass-ui/page-header'; import { StatTile } from '@andrewbehma/glass-ui/stat-tile'; import { MachinesSummary } from '@/components/dashboard/machines-summary'; import { RecentProjects } from '@/components/dashboard/recent-projects'; +import { StaleDemos } from '@/components/dashboard/stale-demos'; import { t } from '@/i18n'; +import type { Project } from '@/lib/api'; import { overviewStats } from '@/lib/overview-stats'; import { getRunners } from '@/lib/session'; -import { getProjects } from './projects/_data'; +import { getProjectSchedules, getProjects, getStale } from './projects/_data'; + +/** + * Whether any bound project has a schedule, so an empty stale list reads "All + * passing" (spec #363, Decision 4). Asked only when nothing is stale. + */ +async function hasSchedule(projects: Project[] | null): Promise<boolean> { + const bound = (projects ?? []).filter((project) => project.rootPath !== null); + const schedules = await Promise.all( + bound.map((project) => getProjectSchedules(project.id)), + ); + return schedules.some((entry) => entry?.site || entry?.config); +} export default async function AppPage() { - const [projects, runners] = await Promise.all([getProjects(), getRunners()]); + const [projects, runners, stale] = await Promise.all([ + getProjects(), + getRunners(), + getStale(), + ]); + const showStale = + stale === null || stale.length > 0 || (await hasSchedule(projects)); const stats = projects ? overviewStats(projects) : null; const unavailable = t('dashboard.stats.unavailable'); return ( @@ -35,6 +55,7 @@ export default async function AppPage() { hint={t('dashboard.stats.failingHint')} /> </section> + {showStale ? <StaleDemos stale={stale} /> : null} <div className="grid grid-cols-1 gap-6 desktop:grid-cols-3"> <div className="desktop:col-span-2"> <RecentProjects projects={projects} /> diff --git a/apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx b/apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx index 9a018f39..cfc359ca 100644 --- a/apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx +++ b/apps/web/src/app/app/projects/[id]/runs/[runId]/page.tsx @@ -42,12 +42,22 @@ export default async function RunPage({ machine, scenarioPath: run.scenarioPath, }); + const check = run.kind === 'check'; const details = ( <> <KeyValueList columns={1} dense items={[ + ...(check + ? [ + { + key: 'kind', + label: t('runPage.kind'), + value: t('runs.kind.check'), + }, + ] + : []), { key: 'status', label: t('runPage.metadata.status'), @@ -134,6 +144,7 @@ export default async function RunPage({ machine={machine} artifactsDeletedAt={run.artifactsDeletedAt} details={details} + check={check} runAgain={ machine !== null && againState !== 'hidden' ? ( <RunAgain diff --git a/apps/web/src/components/dashboard/stale-demos.tsx b/apps/web/src/components/dashboard/stale-demos.tsx new file mode 100644 index 00000000..fab63a24 --- /dev/null +++ b/apps/web/src/components/dashboard/stale-demos.tsx @@ -0,0 +1,76 @@ +import { Banner } from '@andrewbehma/glass-ui/banner'; +import { Card } from '@andrewbehma/glass-ui/card'; +import Link from 'next/link'; +import { t } from '@/i18n'; +import type { StaleScenario } from '@/lib/api'; +import { formatDate } from '@/lib/format-date'; +import { formatRelative } from '@/lib/format-relative'; +import { StaleBadge } from '../projects/stale-badge'; + +export const STALE_LIMIT = 10; + +/** + * The "Stale demos" block of `/app` (spec #363, Decision 4): every broken + * scenario across the user's projects, or "All passing" for a user who has a + * schedule. The caller hides it for a user with neither. + */ +export function StaleDemos({ stale }: { stale: StaleScenario[] | null }) { + const now = Date.now(); + return ( + <Card pad="lg"> + <h2 className="flex flex-wrap items-center gap-2 text-lg font-semibold"> + {t('dashboard.stale.title')} + {stale && stale.length > 0 ? <StaleBadge count={stale.length} /> : null} + </h2> + <div className="mt-4"> + {stale === null ? ( + <Banner tone="danger">{t('dashboard.stale.loadFailed')}</Banner> + ) : stale.length === 0 ? ( + <p className="text-sm text-ink-2"> + {t('dashboard.stale.allPassing')} + </p> + ) : ( + <ul className="flex flex-col"> + {stale.slice(0, STALE_LIMIT).map((row) => { + const when = formatRelative(row.since, now); + return ( + <li + key={`${row.projectId}:${row.scenarioPath}`} + className="flex flex-col gap-1 border-t border-line py-3 first:border-t-0 first:pt-0" + > + <span className="flex flex-wrap items-center gap-x-2 gap-y-1"> + <Link + href={`/app/projects/${encodeURIComponent(row.projectId)}`} + className="break-words font-semibold underline" + > + {row.projectName} + </Link> + <span aria-hidden>·</span> + <span className="break-words">{row.scenarioName}</span> + </span> + <p className="flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-ink-2"> + <time + dateTime={row.since} + title={formatDate(row.since)} + suppressHydrationWarning + > + {when + ? t('dashboard.stale.since', { when }) + : t('dashboard.stale.sinceJustNow')} + </time> + <Link + href={`/app/projects/${encodeURIComponent(row.projectId)}/runs/${encodeURIComponent(row.lastRunId)}`} + className="text-ink underline" + > + {t('dashboard.stale.openRun')} + </Link> + </p> + </li> + ); + })} + </ul> + )} + </div> + </Card> + ); +} diff --git a/apps/web/src/components/player/run-playback.tsx b/apps/web/src/components/player/run-playback.tsx index 42109cc1..de164eeb 100644 --- a/apps/web/src/components/player/run-playback.tsx +++ b/apps/web/src/components/player/run-playback.tsx @@ -64,6 +64,8 @@ function FrameMessage({ * and beside it the glass panel with the run's `details` and its actions — * `runAgain`, Download, the control that deletes the run's files from its * machine, and `deleteRun`. Below 1024px the panel stacks under the player. + * A `check` run records no video (spec #363, Decision 5): the frame says so, + * and there is no format switch, Download or file deletion. */ export function RunPlayback({ runId, @@ -73,6 +75,7 @@ export function RunPlayback({ details, runAgain, deleteRun, + check = false, }: { runId: string; formats: string[]; @@ -81,6 +84,7 @@ export function RunPlayback({ details: ReactNode; runAgain: ReactNode; deleteRun: ReactNode; + check?: boolean; }) { const router = useRouter(); const formats = orderFormats(runFormats); @@ -168,9 +172,12 @@ export function RunPlayback({ machine, ); // Download and Delete video files only make sense while there are files. - const hasFiles = deletedAt === null && format !== undefined; + const hasFiles = !check && deletedAt === null && format !== undefined; function frame(): ReactNode { + if (check) { + return <FrameMessage status={null} title={t('runPage.checkNoVideo')} />; + } if (deletedAt !== null) { return ( <FrameMessage @@ -240,7 +247,7 @@ export function RunPlayback({ > {frame()} </div> - {format !== undefined && deletedAt === null && formats.length > 1 ? ( + {hasFiles && formats.length > 1 ? ( <div className="max-w-full overflow-x-auto"> <SegmentedControl aria-label={t('runPage.formats.label')}> {formats.map((candidate) => ( diff --git a/apps/web/src/components/projects/project-list.tsx b/apps/web/src/components/projects/project-list.tsx index f16a937a..98abd5c3 100644 --- a/apps/web/src/components/projects/project-list.tsx +++ b/apps/web/src/components/projects/project-list.tsx @@ -25,6 +25,7 @@ import { lastRunStatus } from '@/lib/status'; import type { ErrorKey } from '@/lib/validation'; import { apiErrorKey } from '../auth/form-parts'; import { MachinePill } from './machine-pill'; +import { StaleBadge } from './stale-badge'; const NAME_MAX = 200; @@ -225,12 +226,15 @@ function ProjectSummary({ project }: { project: Project }) { const { lastRun } = project; return ( <div className="flex min-w-0 flex-col gap-1"> - <Link - href={`/app/projects/${encodeURIComponent(project.id)}`} - className="break-words font-semibold text-ink underline-offset-2 hover:underline" - > - {project.name} - </Link> + <span className="flex flex-wrap items-center gap-2"> + <Link + href={`/app/projects/${encodeURIComponent(project.id)}`} + className="break-words font-semibold text-ink underline-offset-2 hover:underline" + > + {project.name} + </Link> + <StaleBadge count={project.staleCount ?? 0} /> + </span> <p className="flex flex-wrap items-center gap-x-2 gap-y-1 text-sm text-ink-2"> {project.rootPath === null ? ( <span>{t('projects.item.noFolder')}</span> diff --git a/apps/web/src/components/projects/runs-table.tsx b/apps/web/src/components/projects/runs-table.tsx index 2c821dd7..8aeaaefe 100644 --- a/apps/web/src/components/projects/runs-table.tsx +++ b/apps/web/src/components/projects/runs-table.tsx @@ -1,6 +1,7 @@ 'use client'; import { SelectionBar } from '@andrewbehma/glass-ui'; +import { Badge } from '@andrewbehma/glass-ui/badge'; import { Banner } from '@andrewbehma/glass-ui/banner'; import { Button } from '@andrewbehma/glass-ui/button'; import { Checkbox } from '@andrewbehma/glass-ui/checkbox'; @@ -201,12 +202,21 @@ export function RunsTable({ /> </TableCell> <TableCell className={stacked.lead}> - <Link - href={`/app/projects/${encodeURIComponent(projectId)}/runs/${encodeURIComponent(run.id)}`} - className="break-words font-medium text-ink underline-offset-2 hover:underline" - > - {run.scenarioName} - </Link> + <span className="flex flex-wrap items-center gap-2"> + <Link + href={`/app/projects/${encodeURIComponent(projectId)}/runs/${encodeURIComponent(run.id)}`} + className="break-words font-medium text-ink underline-offset-2 hover:underline" + > + {run.scenarioName} + </Link> + {run.kind === 'check' ? ( + <Badge + tone="neutral" + size="md" + label={t('runs.kind.check')} + /> + ) : null} + </span> <div className="break-all font-mono text-xs text-ink-2"> {run.scenarioPath} </div> From 90a81c01f4c0ab77b56ff4aadd5bfdf435f31498 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 19:47:29 +0100 Subject: [PATCH 64/71] chore(demo): add the C-179 check schedules demo scenario The scenario signs in off camera, creates a project and opens it to show the Scheduled checks card in its unbound state, which renders for any account. --- ...b-check-schedules-on-the-project.demo.json | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 demoflow/cards/C-179-feat-web-check-schedules-on-the-project.demo.json diff --git a/demoflow/cards/C-179-feat-web-check-schedules-on-the-project.demo.json b/demoflow/cards/C-179-feat-web-check-schedules-on-the-project.demo.json new file mode 100644 index 00000000..b2b6301d --- /dev/null +++ b/demoflow/cards/C-179-feat-web-check-schedules-on-the-project.demo.json @@ -0,0 +1,43 @@ +{ + "schemaVersion": 1, + "name": "Check schedules on the project page", + "description": "Sign in off camera, create a project, open it and show its new Scheduled checks card, which asks for a bound folder before a schedule can be set.", + "viewport": { "width": 1280, "height": 720 }, + "setup": [ + { + "action": "include", + "fragment": "sign-in", + "with": { "next": "/app/projects" } + } + ], + "steps": [ + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Projects", "exact": true } + }, + { + "action": "fill", + "target": { "role": "textbox", "name": "New project", "exact": true }, + "value": "C-179 nightly checks" + }, + { + "action": "click", + "target": { "role": "button", "name": "Create project", "exact": true } + }, + { + "action": "click", + "target": { "role": "link", "name": "C-179 nightly checks", "exact": true } + }, + { + "action": "assertVisible", + "target": { "role": "heading", "name": "Scheduled checks", "exact": true } + }, + { + "action": "assertVisible", + "target": { + "text": "Bind this project to a folder on a machine to check it on a schedule.", + "exact": true + } + } + ] +} From 3d1b6b50ba4bc58474c6ac78b6efbc42d137739b Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 19:51:05 +0100 Subject: [PATCH 65/71] feat(cli): demoflow share creates a share link for a reported run The command resolves the run like demoflow render, finds its server id in the reported-runs index, posts /runner/shares with the device token and polls the share every second for up to ten minutes. Server refusals become exit-2 CommandErrors with their codes; an existing share is kept and printed; a failed upload exits 1. --password is asked for without echo on a terminal, else read from DEMOFLOW_SHARE_PASSWORD, and never taken as a flag value. --- apps/cli/src/auth/client.ts | 10 +- apps/cli/src/commands/errors.ts | 13 +- apps/cli/src/commands/render.ts | 45 ++- apps/cli/src/commands/share.ts | 238 ++++++++++++ apps/cli/src/main.ts | 36 ++ apps/cli/src/share/publish.ts | 321 ++++++++++++++++ apps/cli/test/commands/share.spec.ts | 526 +++++++++++++++++++++++++++ 7 files changed, 1169 insertions(+), 20 deletions(-) create mode 100644 apps/cli/src/commands/share.ts create mode 100644 apps/cli/src/share/publish.ts create mode 100644 apps/cli/test/commands/share.spec.ts diff --git a/apps/cli/src/auth/client.ts b/apps/cli/src/auth/client.ts index b1908e0d..53c71982 100644 --- a/apps/cli/src/auth/client.ts +++ b/apps/cli/src/auth/client.ts @@ -133,7 +133,8 @@ export async function revokeSelf( throw unexpected(response.status); } -async function send( +/** One request to the API, with the device token when given. */ +export async function send( fetchFn: Fetch, server: string, path: string, @@ -158,7 +159,10 @@ async function send( } } -async function readJson(response: Response): Promise<Record<string, unknown>> { +/** The JSON object a response carries, or a `ServerError`. */ +export async function readJson( + response: Response, +): Promise<Record<string, unknown>> { try { const body: unknown = await response.json(); if (typeof body === 'object' && body !== null && !Array.isArray(body)) { @@ -186,6 +190,6 @@ function numberField(body: Record<string, unknown>, name: string): number { return value; } -function unexpected(status: number): ServerError { +export function unexpected(status: number): ServerError { return new ServerError(`the server answered ${status}`, false); } diff --git a/apps/cli/src/commands/errors.ts b/apps/cli/src/commands/errors.ts index af16e249..ab5fd021 100644 --- a/apps/cli/src/commands/errors.ts +++ b/apps/cli/src/commands/errors.ts @@ -16,7 +16,18 @@ export type CommandErrorCode = | 'app-already-running' | 'fresh-app-needs-dev-command' | 'missing-scenario' - | 'check-flag'; + | 'check-flag' + | 'invalid-expires' + | 'invalid-password' + // `demoflow share` (spec 349, Decision 6): the server's refusals. + | 'not-logged-in' + | 'run-not-reported' + | 'format-not-rendered' + | 'artifacts-deleted' + | 'runner-offline' + | 'runner-outdated' + | 'file-too-large' + | 'quota-exceeded'; /** Bad input to a command (spec 5: exit 2) that is not a config problem. */ export class CommandError extends Error { diff --git a/apps/cli/src/commands/render.ts b/apps/cli/src/commands/render.ts index 9856f107..81a931a3 100644 --- a/apps/cli/src/commands/render.ts +++ b/apps/cli/src/commands/render.ts @@ -78,22 +78,7 @@ export async function renderCommand( io: Io, deps: RenderDeps = defaultRenderDeps(), ): Promise<number> { - const { host } = deps; - assertSafeRunId(runId); - const root = - flags.project === undefined - ? projectRootAbove(deps.cwd) - : projectRootAt(path.resolve(deps.cwd, flags.project)); - const config = loadProjectConfig(root); - const { home } = resolveHome({ - ...host, - out: flags.out, - cwd: deps.cwd, - projectRoot: root, - projectConfig: config, - globalConfig: loadGlobalConfig(host), - }); - const runDir = runDirFor(home, runId, host.platform); + const { root, config, runDir } = locateRun(runId, flags, deps); const result = await readRenderable(runDir); io.stderr('Rendering\n'); @@ -128,6 +113,34 @@ export async function renderCommand( return code === 0 && renderError !== undefined ? EXIT_STAGE_FAILED : code; } +/** + * Where `<runId>` lives (spec 255, Decisions 1–2): under the home of the + * project above the cwd, or of `--project`. Throws for an unsafe id or a + * missing project; the run directory itself may not exist. + */ +export function locateRun( + runId: string, + flags: { out?: string; project?: string }, + deps: { host: HostEnvironment; cwd: string }, +): { root: string; config: ProjectConfig; runDir: string } { + const { host } = deps; + assertSafeRunId(runId); + const root = + flags.project === undefined + ? projectRootAbove(deps.cwd) + : projectRootAt(path.resolve(deps.cwd, flags.project)); + const config = loadProjectConfig(root); + const { home } = resolveHome({ + ...host, + out: flags.out, + cwd: deps.cwd, + projectRoot: root, + projectConfig: config, + globalConfig: loadGlobalConfig(host), + }); + return { root, config, runDir: runDirFor(home, runId, host.platform) }; +} + /** * The run's `result.json`, if the run can be rendered: the directory exists, * the result is valid, the capture stages are finished and the source video diff --git a/apps/cli/src/commands/share.ts b/apps/cli/src/commands/share.ts new file mode 100644 index 00000000..65878d5e --- /dev/null +++ b/apps/cli/src/commands/share.ts @@ -0,0 +1,238 @@ +import { existsSync } from 'node:fs'; +import { createInterface } from 'node:readline/promises'; +import { Writable } from 'node:stream'; +import { setTimeout as delay } from 'node:timers/promises'; +import type { RenderFormat } from '@demoflow/core'; +import { ServerError } from '../auth/client.ts'; +import { readCredentials } from '../auth/credentials.ts'; +import { currentHost, type HostEnvironment } from '../config/index.ts'; +import { runnerPaths } from '../runner/paths.ts'; +import { + createShare, + DEFAULT_SHARE_LIFETIME, + PASSWORD_MAX_LENGTH, + PASSWORD_MIN_LENGTH, + reportedRunOf, + SHARE_LIFETIMES, + type Share, + type ShareLifetime, + ShareRefused, + shareableFormat, + type WaitDeps, + waitForShare, +} from '../share/publish.ts'; +import { CommandError, EXIT_STAGE_FAILED } from './errors.ts'; +import type { Io } from './io.ts'; +import { locateRun } from './render.ts'; + +/** Decision 6: the upload is polled for up to 10 minutes. */ +export const SHARE_WAIT_MS = 10 * 60_000; +/** How often a long upload says it is still going. */ +const PROGRESS_EVERY_MS = 15_000; +/** Decision 6: where `--password` reads the password without a terminal. */ +export const PASSWORD_ENV = 'DEMOFLOW_SHARE_PASSWORD'; + +export interface ShareFlags { + format?: RenderFormat; + /** `--expires`: 7, 30 or 90 days. */ + expires?: string; + /** `--password`: asked for, never a flag value (shell history). */ + password?: boolean; + json?: boolean; + out?: string; + /** Hidden: the project root, instead of searching up from the cwd. */ + project?: string; +} + +export interface ShareCommandDeps extends WaitDeps { + host: HostEnvironment; + cwd: string; + /** The password typed without echo, or `null` without a terminal. */ + askPassword(): Promise<string | null>; +} + +export const defaultShareDeps = (): ShareCommandDeps => ({ + host: currentHost(), + cwd: process.cwd(), + fetch: (input, init) => fetch(input, init), + sleep: (ms) => delay(ms), + now: () => Date.now(), + askPassword: askPasswordOnTerminal, +}); + +/** + * `demoflow share <runId>` (spec 349, Decision 6): a share link for a render + * of a run this machine reported. The runner uploads the file; this command + * asks the server for the share and waits until it is ready. Refusals are + * `CommandError`s (exit 2); an upload that fails exits 1. + */ +export async function shareCommand( + runId: string, + flags: ShareFlags, + io: Io, + deps: ShareCommandDeps = defaultShareDeps(), +): Promise<number> { + const expiresInDays = parseLifetime(flags.expires); + const credentials = readCredentials(deps.host); + if (credentials === null) { + throw new CommandError( + 'not-logged-in', + 'this machine is not logged in: run demoflow login', + ); + } + const { runDir } = locateRun(runId, flags, deps); + if (!existsSync(runDir)) { + throw new CommandError('run-not-found', `no run directory at ${runDir}`); + } + + try { + const format = await shareableFormat(runDir, flags.format); + const reported = await reportedRunOf( + runnerPaths(deps.host).reportedRuns, + runDir, + credentials.server, + ); + const password = + flags.password === true ? await readPassword(deps) : undefined; + + io.stderr(`Sharing the ${format} render of ${runId}\n`); + const { share, existing } = await createShare( + credentials, + { + runId: reported.id, + format, + expiresInDays, + ...(password === undefined ? {} : { password }), + }, + deps.fetch, + ); + if (existing) { + io.stderr( + `This render is already shared ${share.view.hasPassword === true ? 'with' : 'without'} a password; that link is kept (revoke it on the website to share it again)\n`, + ); + } else if (share.status === 'uploading') { + io.stderr('The runner is uploading the render\n'); + } + + let reportedAt = 0; + const settled = await waitForShare(credentials, share, deps, { + timeoutMs: SHARE_WAIT_MS, + onPoll: (current, elapsedMs) => { + if (current.status !== 'uploading') return; + if (elapsedMs - reportedAt < PROGRESS_EVERY_MS) return; + reportedAt = elapsedMs; + io.stderr(`Still uploading (${Math.round(elapsedMs / 1000)} s)\n`); + }, + }); + return printShare(settled, flags, io); + } catch (error) { + if (error instanceof ShareRefused) { + throw new CommandError(error.code, error.message); + } + if (error instanceof ServerError) { + io.stderr(`${error.message}\n`); + return EXIT_STAGE_FAILED; + } + throw error; + } +} + +/** The link on stdout, and the file link when there is no password. */ +function printShare(share: Share, flags: ShareFlags, io: Io): number { + if (flags.json === true) { + io.stdout(`${JSON.stringify(share.view, null, 2)}\n`); + } + switch (share.status) { + case 'ready': + if (flags.json !== true) { + io.stdout(`${share.url}\n`); + if (share.fileUrl !== null) io.stdout(`${share.fileUrl}\n`); + } + io.stderr( + `Ready; the link works until ${share.expiresAt.slice(0, 10)}\n`, + ); + return 0; + case 'uploading': + io.stderr( + `The upload is still going after ${SHARE_WAIT_MS / 60_000} minutes; the link works once it is done: ${share.url}\n`, + ); + return 1; + case 'failed': + case 'lost': + io.stderr(`The upload failed: ${share.failure ?? share.status}\n`); + return 1; + } +} + +function parseLifetime(value: string | undefined): ShareLifetime { + if (value === undefined) return DEFAULT_SHARE_LIFETIME; + const days = SHARE_LIFETIMES.find((known) => String(known) === value); + if (days === undefined) { + throw new CommandError( + 'invalid-expires', + `--expires must be ${SHARE_LIFETIMES.join(', ')} days, not ${JSON.stringify(value)}`, + ); + } + return days; +} + +/** Decision 6: typed on a terminal, else `DEMOFLOW_SHARE_PASSWORD`. */ +async function readPassword(deps: ShareCommandDeps): Promise<string> { + const typed = await deps.askPassword(); + const password = typed ?? deps.host.env[PASSWORD_ENV]; + if (password === undefined || password === '') { + throw new CommandError( + 'invalid-password', + typed === null + ? `--password without a terminal reads ${PASSWORD_ENV}, which is not set` + : 'the password is empty', + ); + } + if ( + password.length < PASSWORD_MIN_LENGTH || + password.length > PASSWORD_MAX_LENGTH + ) { + throw new CommandError( + 'invalid-password', + `the password must be ${PASSWORD_MIN_LENGTH}–${PASSWORD_MAX_LENGTH} characters`, + ); + } + return password; +} + +/** Typed twice without echo; no terminal, no question. */ +async function askPasswordOnTerminal(): Promise<string | null> { + if (process.stdin.isTTY !== true || process.stderr.isTTY !== true) { + return null; + } + let muted = false; + // The prompt itself is shown; what is typed after it is not. + const output = new Writable({ + write(chunk, _encoding, done) { + if (!muted) process.stderr.write(chunk); + done(); + }, + }); + const prompt = createInterface({ + input: process.stdin, + output, + terminal: true, + }); + const ask = async (question: string): Promise<string> => { + muted = false; + const answer = prompt.question(question); + muted = true; + const typed = await answer; + process.stderr.write('\n'); + return typed; + }; + try { + const password = await ask('Password for the share: '); + if ((await ask('Again: ')) !== password) { + throw new CommandError('invalid-password', 'the passwords differ'); + } + return password; + } finally { + prompt.close(); + } +} diff --git a/apps/cli/src/main.ts b/apps/cli/src/main.ts index af8d845a..73d57583 100644 --- a/apps/cli/src/main.ts +++ b/apps/cli/src/main.ts @@ -27,6 +27,11 @@ import { type RenderFlags, renderCommand } from './commands/render.ts'; import { runCommand } from './commands/run.ts'; import { registerRunsCommands } from './commands/runs.ts'; import { setupCommand } from './commands/setup.ts'; +import { + PASSWORD_ENV, + type ShareFlags, + shareCommand, +} from './commands/share.ts'; import { validateCommand } from './commands/validate.ts'; import { mcpCommand } from './mcp/command.ts'; import { @@ -156,6 +161,32 @@ export async function main( exitCode = await renderCommand(runId, flags, io); }); + program + .command('share') + .description('Share a render of a reported run as a link on the website') + .argument('<runId>', 'the run directory under <home>/runs/') + .addOption( + new Option( + '--format <format>', + `the render to share (default: the run's first; ${RENDER_FORMATS.join(', ')})`, + ).argParser(parseFormat), + ) + .option( + '--expires <days>', + 'how long the link works: 7, 30 or 90 days', + '30', + ) + .option( + '--password', + `protect the link with a password, asked for on the terminal (else ${PASSWORD_ENV})`, + ) + .option('--json', 'print the share as one JSON object on stdout') + .option('--out <dir>', 'artifacts directory (the home of runs/)') + .addOption(new Option('--project <dir>', 'the project root').hideHelp()) + .action(async (runId: string, flags: ShareFlags) => { + exitCode = await shareCommand(runId, flags, io); + }); + program .command('list') .description('List recent runs of the current project, newest first') @@ -288,6 +319,11 @@ function collectFormat( return [...previous, format]; } +/** `--format` of `share`: one known format. */ +function parseFormat(value: string): RenderFormat { + return collectFormat(value)[0] as RenderFormat; +} + function collectExclude(value: string, previous: string[] = []): string[] { return [...previous, value]; } diff --git a/apps/cli/src/share/publish.ts b/apps/cli/src/share/publish.ts new file mode 100644 index 00000000..9a2355c0 --- /dev/null +++ b/apps/cli/src/share/publish.ts @@ -0,0 +1,321 @@ +import path from 'node:path'; +import type { RenderFormat } from '@demoflow/core'; +import { + type Fetch, + readJson, + ServerError, + send, + unexpected, +} from '../auth/client.ts'; +import type { Credentials } from '../auth/credentials.ts'; +import { readResult } from '../commands/settle.ts'; +import { + type ReportedRun, + readReportedRunsByDir, +} from '../runs-report/reported-runs.ts'; + +/** #348: the lifetimes a share can be created with, in days. */ +export const SHARE_LIFETIMES = [7, 30, 90] as const; +export type ShareLifetime = (typeof SHARE_LIFETIMES)[number]; +export const DEFAULT_SHARE_LIFETIME: ShareLifetime = 30; +/** #348: the API's bounds on a share password. */ +export const PASSWORD_MIN_LENGTH = 8; +export const PASSWORD_MAX_LENGTH = 128; +/** Decision 6: `GET /runner/shares/:id` once a second while it uploads. */ +export const SHARE_POLL_MS = 1_000; + +export type ShareStatus = 'uploading' | 'ready' | 'failed' | 'lost'; +const SHARE_STATUSES: readonly string[] = [ + 'uploading', + 'ready', + 'failed', + 'lost', +]; + +/** What the CLI reads of a `ShareView`. */ +export interface Share { + id: string; + url: string; + /** `null` when the share has a password. */ + fileUrl: string | null; + status: ShareStatus; + failure: string | null; + expiresAt: string; + /** The whole `ShareView`, as the server sent it (`--json`). */ + view: Record<string, unknown>; +} + +/** Why a share cannot be made; the command and the MCP tool name it so. */ +export type ShareRefusalCode = + | 'not-logged-in' + | 'invalid-result' + | 'run-not-reported' + | 'format-not-rendered' + | 'artifacts-deleted' + | 'runner-offline' + | 'runner-outdated' + | 'file-too-large' + | 'quota-exceeded'; + +export class ShareRefused extends Error { + readonly code: ShareRefusalCode; + + constructor(code: ShareRefusalCode, message: string) { + super(message); + this.name = 'ShareRefused'; + this.code = code; + } +} + +export interface ShareRequest { + /** The server's run id, from the reported-runs index. */ + runId: string; + format: RenderFormat; + expiresInDays: ShareLifetime; + password?: string; +} + +/** + * The format to share: the one asked for, which the run must have rendered, + * or the run's first render. The daemon reads the same `result.json`. + */ +export async function shareableFormat( + runDir: string, + format: RenderFormat | undefined, +): Promise<RenderFormat> { + let formats: RenderFormat[]; + try { + formats = (await readResult(runDir)).renders.map((render) => render.format); + } catch (error) { + const reason = error instanceof Error ? error.message : String(error); + throw new ShareRefused( + 'invalid-result', + `cannot read the run's result.json: ${reason}`, + ); + } + const chosen = format ?? formats[0]; + if (chosen === undefined) { + throw new ShareRefused( + 'format-not-rendered', + 'the run has no render: make one with demoflow render <runId>', + ); + } + if (!formats.includes(chosen)) { + throw new ShareRefused( + 'format-not-rendered', + `the run has no ${chosen} render (it has ${formats.join(', ')})`, + ); + } + return chosen; +} + +/** The run's line in the reported-runs index, if it went to `server`. */ +export async function reportedRunOf( + indexFile: string, + runDir: string, + server: string, +): Promise<ReportedRun> { + const entry = (await readReportedRunsByDir(indexFile)).get( + path.resolve(runDir), + ); + if (entry === undefined) { + throw new ShareRefused( + 'run-not-reported', + 'the run was never reported to the server: it was made signed out or with reporting off', + ); + } + if (entry.server !== undefined && entry.server !== server) { + throw new ShareRefused( + 'run-not-reported', + `the run was reported to ${entry.server}, not to ${server}`, + ); + } + return entry; +} + +/** + * `POST /runner/shares`. A live share of the same run and format is not an + * error: it is fetched and returned with `existing: true` (Decision 6). + */ +export async function createShare( + credentials: Credentials, + request: ShareRequest, + fetchFn: Fetch, +): Promise<{ share: Share; existing: boolean }> { + // A second try only for a `share-exists` that raced its own insert. + for (let attempt = 0; attempt < 2; attempt++) { + const response = await send(fetchFn, credentials.server, '/runner/shares', { + method: 'POST', + token: credentials.token, + body: { + runId: request.runId, + format: request.format, + expiresInDays: request.expiresInDays, + ...(request.password === undefined + ? {} + : { password: request.password }), + }, + }); + if (response.status === 202) { + return { share: toShare(await readJson(response)), existing: false }; + } + const body = await errorBody(response); + if (response.status === 409 && body.error === 'share-exists') { + if (typeof body.shareId !== 'string') continue; + return { + share: await fetchShare(credentials, body.shareId, fetchFn), + existing: true, + }; + } + throw refusal(response.status, body, request.format); + } + throw new ServerError('the server keeps answering share-exists', false); +} + +/** `GET /runner/shares/:id`. */ +export async function fetchShare( + credentials: Credentials, + id: string, + fetchFn: Fetch, +): Promise<Share> { + const response = await send( + fetchFn, + credentials.server, + `/runner/shares/${encodeURIComponent(id)}`, + { method: 'GET', token: credentials.token }, + ); + if (response.status === 200) return toShare(await readJson(response)); + if (response.status === 401) { + throw refusal(401, await errorBody(response), undefined); + } + throw unexpected(response.status); +} + +export interface WaitDeps { + fetch: Fetch; + sleep(ms: number): Promise<void>; + now(): number; +} + +/** + * Polls a share until it leaves `uploading` or `timeoutMs` passes, and + * returns what it last read: still `uploading` on a timeout. + */ +export async function waitForShare( + credentials: Credentials, + share: Share, + deps: WaitDeps, + options: { + timeoutMs: number; + onPoll?(share: Share, elapsedMs: number): void; + }, +): Promise<Share> { + const started = deps.now(); + let current = share; + while (current.status === 'uploading') { + const elapsed = deps.now() - started; + if (elapsed + SHARE_POLL_MS > options.timeoutMs) break; + await deps.sleep(SHARE_POLL_MS); + current = await fetchShare(credentials, current.id, deps.fetch); + options.onPoll?.(current, deps.now() - started); + } + return current; +} + +/** `1.5 MB`: what a refusal names a size with. */ +export function formatSize(bytes: number): string { + if (bytes < 1000 * 1000) return `${Math.round(bytes / 1000)} kB`; + if (bytes < 1000 * 1000 * 1000) { + return `${(bytes / (1000 * 1000)).toFixed(1)} MB`; + } + return `${(bytes / (1000 * 1000 * 1000)).toFixed(2)} GB`; +} + +function refusal( + status: number, + body: Record<string, unknown>, + format: RenderFormat | undefined, +): Error { + if (status === 401) { + return new ShareRefused( + 'not-logged-in', + 'the stored token was revoked: run demoflow login', + ); + } + if (status === 404) { + return new ShareRefused( + 'run-not-reported', + 'the server does not know this run on this machine: it was made signed out, with reporting off, or before the last login', + ); + } + switch (body.error) { + case 'format-not-rendered': + return new ShareRefused( + 'format-not-rendered', + `the server has no ${format ?? 'such'} render of this run: render it again with demoflow render <runId> while logged in`, + ); + case 'artifacts-deleted': + return new ShareRefused( + 'artifacts-deleted', + "the run's files were deleted on the website", + ); + case 'runner-offline': + return new ShareRefused( + 'runner-offline', + 'the runner is offline: start the runner: demoflow runner start', + ); + case 'runner-outdated': + return new ShareRefused( + 'runner-outdated', + 'the running runner cannot upload shares: restart the runner (demoflow runner stop, then demoflow runner start)', + ); + case 'file-too-large': + return new ShareRefused( + 'file-too-large', + typeof body.maxFileBytes === 'number' + ? `the render is over the ${formatSize(body.maxFileBytes)} a share can hold` + : 'the render is over the size a share can hold', + ); + case 'quota-exceeded': + return new ShareRefused( + 'quota-exceeded', + typeof body.usedBytes === 'number' && + typeof body.limitBytes === 'number' + ? `the share quota is full: ${formatSize(body.usedBytes)} of ${formatSize(body.limitBytes)} used; revoke a share on the website` + : 'the share quota is full; revoke a share on the website', + ); + } + return unexpected(status); +} + +/** An error body, or `{}` when it is not JSON: the status then decides. */ +async function errorBody(response: Response): Promise<Record<string, unknown>> { + try { + return await readJson(response); + } catch { + return {}; + } +} + +function toShare(body: Record<string, unknown>): Share { + const { id, url, fileUrl, status, failure, expiresAt } = body; + if ( + typeof id !== 'string' || + typeof url !== 'string' || + !(typeof fileUrl === 'string' || fileUrl === null) || + typeof status !== 'string' || + !SHARE_STATUSES.includes(status) || + typeof expiresAt !== 'string' + ) { + throw new ServerError('the server sent a share it cannot read', false); + } + return { + id, + url, + fileUrl, + status: status as ShareStatus, + failure: typeof failure === 'string' ? failure : null, + expiresAt, + view: body, + }; +} diff --git a/apps/cli/test/commands/share.spec.ts b/apps/cli/test/commands/share.spec.ts new file mode 100644 index 00000000..aa1bc264 --- /dev/null +++ b/apps/cli/test/commands/share.spec.ts @@ -0,0 +1,526 @@ +import { mkdir, mkdtemp, realpath, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import type { RunResult } from '@demoflow/core'; +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; +import type { Fetch } from '../../src/auth/client.ts'; +import { + credentialsPath, + writeCredentials, +} from '../../src/auth/credentials.ts'; +import { CommandError } from '../../src/commands/errors.ts'; +import type { Io } from '../../src/commands/io.ts'; +import { + type ShareCommandDeps, + type ShareFlags, + shareCommand, +} from '../../src/commands/share.ts'; +import { + type HostEnvironment, + PROJECT_CONFIG_FILE, +} from '../../src/config/index.ts'; +import { main } from '../../src/main.ts'; +import { runnerPaths } from '../../src/runner/paths.ts'; +import { appendReportedRun } from '../../src/runs-report/reported-runs.ts'; + +const RUN_ID = '20261026-101500-abcdef'; +const SERVER = 'https://demoflow.example'; +const TOKEN = 'device-token-123'; +const SERVER_RUN_ID = '0d6f4a52-5d0e-4c55-9a7f-3f6f3d5c1a01'; +const SHARE_ID = 'share-1'; + +let dir: string; +let project: string; +let runDir: string; +let host: HostEnvironment; + +beforeEach(async () => { + dir = await realpath(await mkdtemp(path.join(tmpdir(), 'demoflow-share-'))); + project = path.join(dir, 'project'); + runDir = path.join(project, 'artifacts', 'runs', RUN_ID); + host = { + platform: process.platform, + env: { XDG_CONFIG_HOME: dir, APPDATA: dir }, + homedir: dir, + }; + await mkdir(runDir, { recursive: true }); + await writeFile( + path.join(project, PROJECT_CONFIG_FILE), + JSON.stringify({ + baseUrl: 'http://localhost:3680', + artifactsDir: 'artifacts', + }), + ); + await writeResult(['mp4', 'gif']); + writeCredentials(host, { server: SERVER, token: TOKEN, runnerId: 'r-1' }); + appendReportedRun(runnerPaths(host).reportedRuns, { + id: SERVER_RUN_ID, + runDir, + at: '2026-10-26T10:15:05.000Z', + projectId: 'p-1', + server: SERVER, + root: project, + }); +}); + +afterEach(async () => { + await rm(dir, { recursive: true, force: true }); +}); + +async function writeResult(formats: ('mp4' | 'gif' | 'webm')[]) { + const stage = { status: 'passed' }; + const result = { + schemaVersion: 1, + runId: RUN_ID, + scenarioId: 'demoflow/login.demo.json', + scenarioName: 'Sign in', + startedAt: '2026-10-26T10:15:00.000Z', + finishedAt: '2026-10-26T10:15:05.000Z', + status: 'completed', + stages: { + readiness: stage, + execution: stage, + verification: stage, + recording: stage, + rendering: stage, + storage: { status: 'skipped' }, + }, + renders: formats.map((format) => ({ + renderer: 'ffmpeg', + format, + file: `render/ffmpeg.${format}`, + durationMs: 4000, + sizeBytes: 1000, + width: 1280, + height: 720, + fps: 30, + })), + warnings: [], + } as unknown as RunResult; + await writeFile(path.join(runDir, 'result.json'), JSON.stringify(result)); +} + +function view(overrides: Record<string, unknown> = {}) { + return { + id: SHARE_ID, + url: `${SERVER}/s/abc`, + fileUrl: `${SERVER}/s/abc/file.mp4`, + runId: SERVER_RUN_ID, + projectId: 'p-1', + title: 'Sign in', + format: 'mp4', + status: 'uploading', + failure: null, + sizeBytes: 1000, + width: 1280, + height: 720, + durationMs: 4000, + hasPassword: false, + views: 0, + expiresAt: '2026-11-25T10:00:00.000Z', + createdAt: '2026-10-26T10:00:00.000Z', + ...overrides, + }; +} + +interface Call { + method: string; + url: string; + authorization: string | undefined; + body: Record<string, unknown> | undefined; +} + +type Answer = { status: number; body: unknown }; + +/** The API: the POST answers `post`, each GET the next of `gets` (the last repeats). */ +function fakeApi(post: Answer | Answer[], gets: Answer[] = []) { + const calls: Call[] = []; + const posts = Array.isArray(post) ? [...post] : [post]; + const fetchFn: Fetch = async (input, init) => { + const headers = (init?.headers ?? {}) as Record<string, string>; + const body = + typeof init?.body === 'string' + ? (JSON.parse(init.body) as Record<string, unknown>) + : undefined; + calls.push({ + method: init?.method ?? 'GET', + url: String(input), + authorization: headers.authorization, + body, + }); + const answer = + init?.method === 'POST' + ? posts.length > 1 + ? posts.shift() + : posts[0] + : gets.length > 1 + ? gets.shift() + : gets[0]; + if (answer === undefined) throw new Error('no answer'); + return new Response(JSON.stringify(answer.body), { + status: answer.status, + headers: { 'content-type': 'application/json' }, + }); + }; + return { calls, fetchFn }; +} + +function capture(): Io & { out: string; err: string } { + const io = { + out: '', + err: '', + stdout: (text: string) => { + io.out += text; + }, + stderr: (text: string) => { + io.err += text; + }, + }; + return io; +} + +function deps( + fetchFn: Fetch, + overrides: Partial<ShareCommandDeps> = {}, +): ShareCommandDeps { + let now = 0; + return { + host, + cwd: project, + fetch: fetchFn, + sleep: async (ms) => { + now += ms; + }, + now: () => now, + askPassword: async () => null, + ...overrides, + }; +} + +async function share( + fetchFn: Fetch, + flags: ShareFlags = {}, + overrides: Partial<ShareCommandDeps> = {}, +) { + const io = capture(); + const code = await shareCommand(RUN_ID, flags, io, deps(fetchFn, overrides)); + return { code, ...io }; +} + +async function refusal(promise: Promise<unknown>): Promise<CommandError> { + try { + await promise; + } catch (error) { + if (error instanceof CommandError) return error; + throw error; + } + throw new Error('expected a CommandError'); +} + +describe('demoflow share', () => { + it('creates the share, waits for it and prints both links', async () => { + const api = fakeApi({ status: 202, body: view() }, [ + { status: 200, body: view() }, + { status: 200, body: view({ status: 'ready' }) }, + ]); + const { code, out, err } = await share(api.fetchFn); + expect(code).toBe(0); + expect(out).toBe(`${SERVER}/s/abc\n${SERVER}/s/abc/file.mp4\n`); + expect(err).toContain('Ready; the link works until 2026-11-25'); + expect(api.calls[0]).toEqual({ + method: 'POST', + url: `${SERVER}/api/runner/shares`, + authorization: `Bearer ${TOKEN}`, + body: { runId: SERVER_RUN_ID, format: 'mp4', expiresInDays: 30 }, + }); + expect(api.calls.slice(1).map((call) => call.url)).toEqual([ + `${SERVER}/api/runner/shares/${SHARE_ID}`, + `${SERVER}/api/runner/shares/${SHARE_ID}`, + ]); + }); + + it('shares the format and lifetime asked for', async () => { + const api = fakeApi({ status: 202, body: view({ status: 'ready' }) }); + const { code } = await share(api.fetchFn, { + format: 'gif', + expires: '90', + }); + expect(code).toBe(0); + expect(api.calls[0]?.body).toEqual({ + runId: SERVER_RUN_ID, + format: 'gif', + expiresInDays: 90, + }); + }); + + it('prints the ShareView with --json', async () => { + const api = fakeApi({ status: 202, body: view({ status: 'ready' }) }); + const { code, out } = await share(api.fetchFn, { json: true }); + expect(code).toBe(0); + expect(JSON.parse(out)).toEqual(view({ status: 'ready' })); + }); + + it('prints no file link for a share with a password', async () => { + const api = fakeApi({ + status: 202, + body: view({ status: 'ready', fileUrl: null, hasPassword: true }), + }); + const { out } = await share( + api.fetchFn, + { password: true }, + { askPassword: async () => 'correct horse' }, + ); + expect(out).toBe(`${SERVER}/s/abc\n`); + }); + + it('keeps an existing share and says so', async () => { + const api = fakeApi( + { status: 409, body: { error: 'share-exists', shareId: 'share-0' } }, + [{ status: 200, body: view({ id: 'share-0', status: 'ready' }) }], + ); + const { code, out, err } = await share(api.fetchFn); + expect(code).toBe(0); + expect(out).toContain(`${SERVER}/s/abc\n`); + expect(err).toContain('already shared without a password'); + expect(api.calls[1]?.url).toBe(`${SERVER}/api/runner/shares/share-0`); + }); + + it('asks again when share-exists comes without a share id', async () => { + const api = fakeApi( + [ + { status: 409, body: { error: 'share-exists' } }, + { status: 409, body: { error: 'share-exists', shareId: 'share-0' } }, + ], + [{ status: 200, body: view({ id: 'share-0', status: 'ready' }) }], + ); + const { code } = await share(api.fetchFn); + expect(code).toBe(0); + expect(api.calls.map((call) => call.method)).toEqual([ + 'POST', + 'POST', + 'GET', + ]); + }); + + it('exits 1 with the failure when the upload fails', async () => { + const api = fakeApi({ status: 202, body: view() }, [ + { status: 200, body: view({ status: 'failed', failure: 'runner-gone' }) }, + ]); + const { code, out, err } = await share(api.fetchFn); + expect(code).toBe(1); + expect(out).toBe(''); + expect(err).toContain('The upload failed: runner-gone'); + }); + + it('gives up after 10 minutes of uploading', async () => { + const api = fakeApi({ status: 202, body: view() }, [ + { status: 200, body: view() }, + ]); + const { code, err } = await share(api.fetchFn); + expect(code).toBe(1); + expect(err).toContain('still going after 10 minutes'); + expect(err).toContain('Still uploading (15 s)'); + // One GET a second, for 10 minutes. + expect(api.calls.length).toBe(1 + 600); + }); + + it('exits 3 when the server is unreachable', async () => { + const { code, err } = await share(async () => { + throw new TypeError('fetch failed'); + }); + expect(code).toBe(3); + expect(err).toContain(`cannot reach ${SERVER}`); + }); + + describe('refusals exit 2 with their code', () => { + it.each([ + [401, {}, 'not-logged-in'], + [404, { error: 'not-found' }, 'run-not-reported'], + [409, { error: 'format-not-rendered' }, 'format-not-rendered'], + [409, { error: 'artifacts-deleted' }, 'artifacts-deleted'], + [409, { error: 'runner-offline' }, 'runner-offline'], + [409, { error: 'runner-outdated' }, 'runner-outdated'], + [ + 413, + { error: 'file-too-large', maxFileBytes: 200_000_000 }, + 'file-too-large', + ], + [ + 409, + { + error: 'quota-exceeded', + usedBytes: 900_000_000, + limitBytes: 1_000_000_000, + }, + 'quota-exceeded', + ], + ])('%i %j → %s', async (status, body, code) => { + const api = fakeApi({ status, body }); + const error = await refusal(share(api.fetchFn)); + expect(error.code).toBe(code); + expect(error.exitCode).toBe(2); + }); + + it('names the hint of an offline runner, the size and the quota', async () => { + const offline = await refusal( + share( + fakeApi({ status: 409, body: { error: 'runner-offline' } }).fetchFn, + ), + ); + expect(offline.message).toContain('demoflow runner start'); + const outdated = await refusal( + share( + fakeApi({ status: 409, body: { error: 'runner-outdated' } }).fetchFn, + ), + ); + expect(outdated.message).toContain('restart the runner'); + const large = await refusal( + share( + fakeApi({ + status: 413, + body: { error: 'file-too-large', maxFileBytes: 200_000_000 }, + }).fetchFn, + ), + ); + expect(large.message).toContain('200.0 MB'); + const quota = await refusal( + share( + fakeApi({ + status: 409, + body: { + error: 'quota-exceeded', + usedBytes: 900_000_000, + limitBytes: 1_000_000_000, + }, + }).fetchFn, + ), + ); + expect(quota.message).toContain('900.0 MB of 1.00 GB used'); + }); + + it('not-logged-in without credentials, before any request', async () => { + await rm(credentialsPath(host)); + const api = fakeApi({ status: 500, body: {} }); + const error = await refusal(share(api.fetchFn)); + expect(error.code).toBe('not-logged-in'); + expect(error.message).toContain('demoflow login'); + expect(api.calls).toEqual([]); + }); + + it('run-not-found for a missing run directory', async () => { + const api = fakeApi({ status: 500, body: {} }); + const io = capture(); + const error = await refusal( + shareCommand('20261026-000000-ffffff', {}, io, deps(api.fetchFn)), + ); + expect(error.code).toBe('run-not-found'); + expect(api.calls).toEqual([]); + }); + + it('run-not-reported for a run missing from the index', async () => { + await writeFile(runnerPaths(host).reportedRuns, ''); + const api = fakeApi({ status: 500, body: {} }); + const error = await refusal(share(api.fetchFn)); + expect(error.code).toBe('run-not-reported'); + expect(api.calls).toEqual([]); + }); + + it('run-not-reported for a run reported to another server', async () => { + writeCredentials(host, { + server: 'https://staging.example', + token: TOKEN, + runnerId: 'r-1', + }); + const error = await refusal( + share(fakeApi({ status: 500, body: {} }).fetchFn), + ); + expect(error.code).toBe('run-not-reported'); + expect(error.message).toContain(SERVER); + }); + + it('format-not-rendered for a format the run lacks, or no render', async () => { + const api = fakeApi({ status: 500, body: {} }); + const missing = await refusal(share(api.fetchFn, { format: 'webm' })); + expect(missing.code).toBe('format-not-rendered'); + expect(missing.message).toContain('mp4, gif'); + await writeResult([]); + const none = await refusal(share(api.fetchFn)); + expect(none.code).toBe('format-not-rendered'); + expect(api.calls).toEqual([]); + }); + + it('invalid-expires for a lifetime the server does not offer', async () => { + const error = await refusal( + share(fakeApi({ status: 500, body: {} }).fetchFn, { expires: '14' }), + ); + expect(error.code).toBe('invalid-expires'); + }); + }); + + describe('--password', () => { + it('sends the typed password in the body only', async () => { + const api = fakeApi({ + status: 202, + body: view({ status: 'ready', fileUrl: null, hasPassword: true }), + }); + await share( + api.fetchFn, + { password: true }, + { askPassword: async () => 'typed secret' }, + ); + expect(api.calls[0]?.body?.password).toBe('typed secret'); + expect(api.calls[0]?.url).not.toContain('secret'); + }); + + it('reads DEMOFLOW_SHARE_PASSWORD without a terminal', async () => { + host = { + ...host, + env: { ...host.env, DEMOFLOW_SHARE_PASSWORD: 'from the env' }, + }; + const api = fakeApi({ + status: 202, + body: view({ status: 'ready', fileUrl: null, hasPassword: true }), + }); + await share(api.fetchFn, { password: true }); + expect(api.calls[0]?.body?.password).toBe('from the env'); + }); + + it('is refused without a terminal and without the variable', async () => { + const api = fakeApi({ status: 500, body: {} }); + const error = await refusal(share(api.fetchFn, { password: true })); + expect(error.code).toBe('invalid-password'); + expect(error.message).toContain('DEMOFLOW_SHARE_PASSWORD'); + expect(api.calls).toEqual([]); + }); + + it('is refused outside 8–128 characters', async () => { + const api = fakeApi({ status: 500, body: {} }); + const short = await refusal( + share( + api.fetchFn, + { password: true }, + { askPassword: async () => 'short' }, + ), + ); + expect(short.code).toBe('invalid-password'); + const long = await refusal( + share( + api.fetchFn, + { password: true }, + { askPassword: async () => 'x'.repeat(129) }, + ), + ); + expect(long.code).toBe('invalid-password'); + }); + + it('takes no value on the command line', async () => { + const io = capture(); + const code = await main( + ['share', RUN_ID, '--password', 'hunter2hunter2'], + io, + ); + expect(code).toBe(2); + expect(io.err).toContain('too many arguments'); + }); + }); +}); From c8ffd1cc464163e361951f9b179db56e12fd6f00 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 20:01:54 +0100 Subject: [PATCH 66/71] feat(cli): the MCP share_demo tool, gated by share.allowMcp share_demo creates a share link for a reported run without a password, only when the run's project sets share.allowMcp: true. It waits up to 50 s for the upload and answers uploading when the runner is still at it. --- apps/cli/src/mcp/errors.ts | 8 +- apps/cli/src/mcp/server.ts | 187 ++++++++++++++++++++ apps/cli/test/mcp/server.spec.ts | 9 +- apps/cli/test/mcp/share.spec.ts | 295 +++++++++++++++++++++++++++++++ 4 files changed, 497 insertions(+), 2 deletions(-) create mode 100644 apps/cli/test/mcp/share.spec.ts diff --git a/apps/cli/src/mcp/errors.ts b/apps/cli/src/mcp/errors.ts index 05665b58..0a8529f3 100644 --- a/apps/cli/src/mcp/errors.ts +++ b/apps/cli/src/mcp/errors.ts @@ -1,4 +1,5 @@ import type { Issue } from '@demoflow/core'; +import type { ShareRefusalCode } from '../share/publish.ts'; export type ToolErrorCode = | 'invalid-input' @@ -8,7 +9,12 @@ export type ToolErrorCode = | 'invalid-scenario' | 'scenario-unreadable' | 'file-not-in-project' - | 'task-not-found'; + | 'task-not-found' + // `share_demo` (spec 349, Decision 7). + | 'share-not-allowed' + | 'share-failed' + | 'server-error' + | ShareRefusalCode; /** What an agent gets back from a failed tool call (spec #68, Decision 9). */ export interface ToolErrorPayload { diff --git a/apps/cli/src/mcp/server.ts b/apps/cli/src/mcp/server.ts index 1ab8d83c..9e3fb975 100644 --- a/apps/cli/src/mcp/server.ts +++ b/apps/cli/src/mcp/server.ts @@ -1,6 +1,7 @@ import { existsSync } from 'node:fs'; import { mkdir, writeFile } from 'node:fs/promises'; import path from 'node:path'; +import { setTimeout as delay } from 'node:timers/promises'; import { formatPath, type Issue, @@ -15,6 +16,8 @@ import { type Tool, } from '@modelcontextprotocol/sdk/types.js'; import { z } from 'zod'; +import { ServerError } from '../auth/client.ts'; +import { readCredentials } from '../auth/credentials.ts'; import { CommandError } from '../commands/errors.ts'; import { assertSafeRunId, generateRunId } from '../commands/run-id.ts'; import { readResult } from '../commands/settle.ts'; @@ -22,6 +25,7 @@ import { CliError, type HostEnvironment, loadGlobalConfig, + loadProjectConfig, osDataDir, projectFragments, runDir as runDirFor, @@ -31,6 +35,17 @@ import { pageUrlFor, readReportedRunsByDir, } from '../runs-report/reported-runs.ts'; +import { + createShare, + DEFAULT_SHARE_LIFETIME, + reportedRunOf, + type ShareRefusalCode, + ShareRefused, + type ShareStatus, + shareableFormat, + type WaitDeps, + waitForShare, +} from '../share/publish.ts'; import { packageVersion } from '../version.ts'; import { ToolError } from './errors.ts'; import { @@ -155,6 +170,40 @@ const CheckProjectInput = z.strictObject({ project: z.string().optional().describe(PROJECT_DESCRIPTION), }); +const ShareDemoInput = z.strictObject({ + runId: z + .string() + .describe('The task ID of a finished run (generate_demo, list_demos).'), + format: z + .enum(RENDER_FORMATS) + .optional() + .describe("The render to share; default: the run's first render."), + expiresInDays: z + .union([z.literal(7), z.literal(30), z.literal(90)]) + .optional() + .describe( + `How long the link works, in days; default ${DEFAULT_SHARE_LIFETIME}.`, + ), +}); + +/** What an agent can do about each refusal of the share API. */ +const SHARE_HINTS: Record<ShareRefusalCode, string> = { + 'not-logged-in': 'Ask a person to run `demoflow login` on this machine.', + 'invalid-result': 'The run directory is damaged; generate the demo again.', + 'run-not-reported': + 'Only a run made while logged in, with reporting on, can be shared: generate the demo again after `demoflow login`.', + 'format-not-rendered': + 'Pass a format the run rendered (get_task lists the files), or generate the demo again with that format.', + 'artifacts-deleted': + "The run's files were deleted on the website; generate the demo again.", + 'runner-offline': + 'Ask a person to start the runner: `demoflow runner start`.', + 'runner-outdated': + 'Ask a person to restart the runner: `demoflow runner stop`, then `demoflow runner start`.', + 'file-too-large': 'Share a smaller render, or make a shorter demo.', + 'quota-exceeded': 'Ask a person to revoke old shares on the website.', +}; + const TOOLS: Tool[] = [ { name: 'generate_demo', @@ -191,6 +240,11 @@ const TOOLS: Tool[] = [ 'Whether a project is ready to run demos: its scenario files, a valid config, and FFmpeg and browser availability.', inputSchema: inputSchema(CheckProjectInput), }, + { + name: 'share_demo', + description: `Publish a finished run's render as a link on the DemoFlow website: anyone with the link can watch it, until it expires. Refused with share-not-allowed unless the project's committed demoflow.config.json sets "share": { "allowMcp": true }. Needs a logged-in machine with its runner running. Waits up to ${MAX_WAIT_SECONDS} s for the upload; on status "uploading", call again with the same arguments to wait more — it returns the same share.`, + inputSchema: inputSchema(ShareDemoInput), + }, ]; export interface McpServerDeps { @@ -199,12 +253,21 @@ export interface McpServerDeps { /** The default project, and where `DEMOFLOW_HOME` is resolved. */ cwd: string; newTaskId?: () => string; + /** `share_demo`'s requests and clock; tests replace them. */ + share?: WaitDeps; } +const processShareDeps: WaitDeps = { + fetch: (input, init) => fetch(input, init), + sleep: (ms) => delay(ms), + now: () => Date.now(), +}; + /** The `demoflow mcp` server, before it is connected to a transport. */ export function createMcpServer(deps: McpServerDeps): Server { const { queue, host, cwd } = deps; const newTaskId = deps.newTaskId ?? (() => generateRunId()); + const shareDeps = deps.share ?? processShareDeps; /** Homes of the projects used by this server: where a finished task is found. */ const homes = new Set<string>(); @@ -235,6 +298,8 @@ export function createMcpServer(deps: McpServerDeps): Server { return ok( await checkProject(parse(CheckProjectInput, args), cwd, host), ); + case 'share_demo': + return ok(await shareDemo(parse(ShareDemoInput, args))); default: throw new ToolError( 'invalid-input', @@ -386,6 +451,100 @@ export function createMcpServer(deps: McpServerDeps): Server { ); } + /** + * Spec 349, Decision 7: what `demoflow share` does, without a password, + * and only for a project whose committed config allows it. + */ + async function shareDemo(input: z.infer<typeof ShareDemoInput>): Promise<{ + shareId: string; + url: string; + fileUrl: string | null; + expiresAt: string; + status: ShareStatus; + existing: boolean; + }> { + checkTaskId(input.runId); + const runDir = locateRunDir(input.runId); + const indexFile = runnerPaths(host).reportedRuns; + const entry = (await readReportedRunsByDir(indexFile)).get( + path.resolve(runDir), + ); + if (entry === undefined) { + throw shareRefusal( + new ShareRefused( + 'run-not-reported', + 'the run was never reported to the server: it was made signed out or with reporting off', + ), + ); + } + checkShareAllowed(entry.root); + try { + const credentials = readCredentials(host); + if (credentials === null) { + throw new ShareRefused( + 'not-logged-in', + 'this machine is not logged in', + ); + } + await reportedRunOf(indexFile, runDir, credentials.server); + const format = await shareableFormat(runDir, input.format); + const created = await createShare( + credentials, + { + runId: entry.id, + format, + expiresInDays: input.expiresInDays ?? DEFAULT_SHARE_LIFETIME, + }, + shareDeps.fetch, + ); + const share = await waitForShare(credentials, created.share, shareDeps, { + timeoutMs: MAX_WAIT_SECONDS * 1000, + }); + if (share.status === 'failed' || share.status === 'lost') { + throw new ToolError( + 'share-failed', + `the upload failed: ${share.failure ?? share.status}`, + 'Call share_demo again to retry: a failed share is replaced.', + ); + } + return { + shareId: share.id, + url: share.url, + fileUrl: share.fileUrl, + expiresAt: share.expiresAt, + status: share.status, + existing: created.existing, + }; + } catch (error) { + if (error instanceof ShareRefused) throw shareRefusal(error); + if (error instanceof ServerError || error instanceof CliError) { + throw new ToolError( + 'server-error', + error.message, + error instanceof ServerError && error.unreachable + ? 'Check the network and the DemoFlow server, then call again.' + : 'Ask a person to check `demoflow login` on this machine.', + ); + } + throw error; + } + } + + /** The run directory of a task of this server, or of an earlier one. */ + function locateRunDir(taskId: string): string { + const task = queue.get(taskId); + if (task !== undefined) return task.spec.runDir; + for (const home of candidateHomes()) { + const runDir = runDirFor(home, taskId, host.platform); + if (existsSync(runDir)) return runDir; + } + throw new ToolError( + 'task-not-found', + `no run ${taskId}`, + 'Use a task ID returned by generate_demo or list_demos.', + ); + } + /** Every home this server wrote to, then where an earlier one would have. */ function candidateHomes(): Set<string> { const env = host.env.DEMOFLOW_HOME; @@ -404,6 +563,34 @@ export function createMcpServer(deps: McpServerDeps): Server { return server; } +/** + * ADR-0019 §6: an agent may publish a project's videos only when the + * project's own, reviewed config says so. A run without a root, or a config + * that cannot be read, is refused the same way. + */ +function checkShareAllowed(root: string | undefined): void { + let allowed = false; + if (root !== undefined) { + try { + allowed = loadProjectConfig(root).share?.allowMcp === true; + } catch (error) { + if (!(error instanceof CliError)) throw error; + } + } + if (allowed) return; + throw new ToolError( + 'share-not-allowed', + root === undefined + ? 'the run was reported without its project root, so no project allows sharing it' + : `the project at ${root} does not let the MCP server share its demos`, + 'A person can share it with `demoflow share <runId>`. To let agents share this project\'s demos, a person sets "share": { "allowMcp": true } in its demoflow.config.json and commits it.', + ); +} + +function shareRefusal(error: ShareRefused): ToolError { + return new ToolError(error.code, error.message, SHARE_HINTS[error.code]); +} + /** Task IDs become directory names: no separators, no `..`. */ function checkTaskId(taskId: string): void { try { diff --git a/apps/cli/test/mcp/server.spec.ts b/apps/cli/test/mcp/server.spec.ts index cb3342a4..ffa6f1ce 100644 --- a/apps/cli/test/mcp/server.spec.ts +++ b/apps/cli/test/mcp/server.spec.ts @@ -216,7 +216,7 @@ afterAll(async () => { }); describe('demoflow mcp', () => { - it('lists its six tools with input schemas', async () => { + it('lists its seven tools with input schemas', async () => { const { tools } = await server.client.listTools(); expect(tools.map((tool) => tool.name).sort()).toEqual([ 'cancel_task', @@ -224,6 +224,7 @@ describe('demoflow mcp', () => { 'generate_demo', 'get_task', 'list_demos', + 'share_demo', 'validate_scenario', ]); for (const tool of tools) expect(tool.inputSchema.type).toBe('object'); @@ -243,6 +244,12 @@ describe('demoflow mcp', () => { expect(properties.scenario?.properties).toHaveProperty('steps'); const getTask = tools.find((tool) => tool.name === 'get_task'); expect(getTask?.inputSchema.required).toEqual(['taskId']); + const share = tools.find((tool) => tool.name === 'share_demo'); + expect(Object.keys(share?.inputSchema.properties ?? {}).sort()).toEqual([ + 'expiresInDays', + 'format', + 'runId', + ]); }); let finished: Record<string, unknown>; diff --git a/apps/cli/test/mcp/share.spec.ts b/apps/cli/test/mcp/share.spec.ts new file mode 100644 index 00000000..a3259200 --- /dev/null +++ b/apps/cli/test/mcp/share.spec.ts @@ -0,0 +1,295 @@ +import { + mkdirSync, + mkdtempSync, + realpathSync, + rmSync, + writeFileSync, +} from 'node:fs'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import { Client } from '@modelcontextprotocol/sdk/client/index.js'; +import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'; +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; +import type { Fetch } from '../../src/auth/client.ts'; +import { writeCredentials } from '../../src/auth/credentials.ts'; +import { + type HostEnvironment, + runDir as runDirFor, +} from '../../src/config/index.ts'; +import { createMcpServer } from '../../src/mcp/server.ts'; +import { TaskQueue } from '../../src/mcp/tasks.ts'; +import { runnerPaths } from '../../src/runner/paths.ts'; +import { appendReportedRun } from '../../src/runs-report/reported-runs.ts'; + +const SERVER = 'https://demoflow.example'; +const TOKEN = 'device-token-123'; +const TASK_ID = 't1'; +const SERVER_RUN_ID = '0d6f4a52-5d0e-4c55-9a7f-3f6f3d5c1a01'; + +let dir: string; +let home: string; +let project: string; +let runDir: string; +let host: HostEnvironment; +let client: Client; +let queue: TaskQueue; +let calls: { method: string; url: string; body: unknown }[]; +let gets: { status: number; body: unknown }[]; +let post: { status: number; body: unknown }; + +beforeEach(async () => { + dir = realpathSync(mkdtempSync(path.join(tmpdir(), 'demoflow-mcp-share-'))); + home = path.join(dir, 'home'); + project = path.join(dir, 'project'); + host = { + platform: process.platform, + env: { DEMOFLOW_HOME: home, XDG_CONFIG_HOME: dir, APPDATA: dir }, + homedir: path.join(dir, 'user'), + }; + config({ share: { allowMcp: true } }); + runDir = runDirFor(home, TASK_ID, host.platform); + write(path.join(runDir, 'result.json'), JSON.stringify(result())); + writeCredentials(host, { server: SERVER, token: TOKEN, runnerId: 'r-1' }); + report({ root: project }); + + calls = []; + post = { status: 202, body: view({ status: 'ready' }) }; + gets = []; + const fetchFn: Fetch = async (input, init) => { + calls.push({ + method: init?.method ?? 'GET', + url: String(input), + body: typeof init?.body === 'string' ? JSON.parse(init.body) : undefined, + }); + const answer = + init?.method === 'POST' ? post : gets.length > 1 ? gets.shift() : gets[0]; + return new Response(JSON.stringify(answer?.body ?? {}), { + status: answer?.status ?? 500, + }); + }; + let now = 0; + queue = new TaskQueue({ + spawn: () => { + throw new Error('no runs here'); + }, + readResult: async () => { + throw new Error('no runs here'); + }, + removeFile: async () => undefined, + log: () => undefined, + }); + const server = createMcpServer({ + queue, + host, + cwd: project, + share: { + fetch: fetchFn, + sleep: async (ms) => { + now += ms; + }, + now: () => now, + }, + }); + const [clientSide, serverSide] = InMemoryTransport.createLinkedPair(); + client = new Client({ name: 'test', version: '0' }); + await Promise.all([server.connect(serverSide), client.connect(clientSide)]); +}); + +afterEach(async () => { + await queue.close(); + await client.close(); + rmSync(dir, { recursive: true, force: true }); +}); + +function write(file: string, content: string): void { + mkdirSync(path.dirname(file), { recursive: true }); + writeFileSync(file, content); +} + +function config(extra: Record<string, unknown>): void { + write( + path.join(project, 'demoflow.config.json'), + JSON.stringify({ baseUrl: 'http://x', ...extra }), + ); +} + +function report(extra: { root?: string }): void { + appendReportedRun(runnerPaths(host).reportedRuns, { + id: SERVER_RUN_ID, + runDir, + at: '2026-10-26T10:15:05.000Z', + projectId: 'p-1', + server: SERVER, + ...extra, + }); +} + +function result() { + const stage = { status: 'passed' }; + return { + schemaVersion: 1, + runId: TASK_ID, + scenarioId: 'demoflow/tour.demo.json', + scenarioName: 'Tour', + startedAt: '2026-10-26T10:15:00.000Z', + finishedAt: '2026-10-26T10:15:05.000Z', + status: 'completed', + stages: { + readiness: stage, + execution: stage, + verification: stage, + recording: stage, + rendering: stage, + storage: { status: 'skipped' }, + }, + renders: ['mp4', 'gif'].map((format) => ({ + renderer: 'ffmpeg', + format, + file: `render/ffmpeg.${format}`, + durationMs: 4000, + sizeBytes: 1000, + width: 1280, + height: 720, + fps: 30, + })), + warnings: [], + }; +} + +function view(overrides: Record<string, unknown> = {}) { + return { + id: 'share-1', + url: `${SERVER}/s/abc`, + fileUrl: `${SERVER}/s/abc/file.mp4`, + status: 'uploading', + failure: null, + hasPassword: false, + expiresAt: '2026-11-25T10:00:00.000Z', + ...overrides, + }; +} + +async function shareDemo(args: Record<string, unknown> = {}) { + const answer = await client.callTool({ + name: 'share_demo', + arguments: { runId: TASK_ID, ...args }, + }); + return { + isError: answer.isError === true, + content: answer.structuredContent as Record<string, unknown>, + }; +} + +describe('share_demo', () => { + it('creates the share when the project allows it', async () => { + const { isError, content } = await shareDemo(); + expect(isError).toBe(false); + expect(content).toEqual({ + shareId: 'share-1', + url: `${SERVER}/s/abc`, + fileUrl: `${SERVER}/s/abc/file.mp4`, + expiresAt: '2026-11-25T10:00:00.000Z', + status: 'ready', + existing: false, + }); + expect(calls).toEqual([ + { + method: 'POST', + url: `${SERVER}/api/runner/shares`, + body: { runId: SERVER_RUN_ID, format: 'mp4', expiresInDays: 30 }, + }, + ]); + }); + + it('passes the format and lifetime, and never a password', async () => { + await shareDemo({ format: 'gif', expiresInDays: 7 }); + expect(calls[0]?.body).toEqual({ + runId: SERVER_RUN_ID, + format: 'gif', + expiresInDays: 7, + }); + }); + + it.each([ + ['without a share block', {}], + ['with allowMcp false', { share: { allowMcp: false } }], + ])('is share-not-allowed %s', async (_name, extra) => { + config(extra); + const { isError, content } = await shareDemo(); + expect(isError).toBe(true); + expect(content.code).toBe('share-not-allowed'); + expect(content.hint).toContain('"allowMcp": true'); + expect(calls).toEqual([]); + }); + + it('is share-not-allowed for a run reported without a root', async () => { + rmSync(runnerPaths(host).reportedRuns); + report({}); + const { content } = await shareDemo(); + expect(content.code).toBe('share-not-allowed'); + expect(calls).toEqual([]); + }); + + it('is share-not-allowed when the config cannot be read', async () => { + write(path.join(project, 'demoflow.config.json'), '{not json'); + const { content } = await shareDemo(); + expect(content.code).toBe('share-not-allowed'); + }); + + it('waits for the upload, then answers uploading', async () => { + post = { status: 202, body: view() }; + gets = [{ status: 200, body: view() }]; + const { isError, content } = await shareDemo(); + expect(isError).toBe(false); + expect(content.status).toBe('uploading'); + // One GET a second, under the 60 s request timeout of MCP clients. + expect(calls.filter((call) => call.method === 'GET').length).toBe(50); + }); + + it('returns an existing share', async () => { + post = { status: 409, body: { error: 'share-exists', shareId: 'share-0' } }; + gets = [{ status: 200, body: view({ id: 'share-0', status: 'ready' }) }]; + const { content } = await shareDemo(); + expect(content.shareId).toBe('share-0'); + expect(content.existing).toBe(true); + }); + + it('is share-failed when the upload fails', async () => { + post = { status: 202, body: view() }; + gets = [{ status: 200, body: view({ status: 'failed', failure: 'io' }) }]; + const { isError, content } = await shareDemo(); + expect(isError).toBe(true); + expect(content.code).toBe('share-failed'); + expect(content.message).toContain('io'); + }); + + it('names the server refusal with a hint', async () => { + post = { status: 409, body: { error: 'runner-offline' } }; + const { content } = await shareDemo(); + expect(content.code).toBe('runner-offline'); + expect(content.hint).toContain('demoflow runner start'); + }); + + it('is not-logged-in without credentials', async () => { + rmSync(path.join(runnerPaths(host).dir, 'credentials.json')); + const { content } = await shareDemo(); + expect(content.code).toBe('not-logged-in'); + expect(calls).toEqual([]); + }); + + it('is run-not-reported for a run missing from the index', async () => { + rmSync(runnerPaths(host).reportedRuns); + const { content } = await shareDemo(); + expect(content.code).toBe('run-not-reported'); + }); + + it('is task-not-found for an unknown run', async () => { + const { content } = await shareDemo({ runId: 'nope' }); + expect(content.code).toBe('task-not-found'); + }); + + it('is invalid-input for a lifetime the server does not offer', async () => { + const { content } = await shareDemo({ expiresInDays: 14 }); + expect(content.code).toBe('invalid-input'); + }); +}); From 82c21a94c8104da79d7635276fc3b2a1e40ad428 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 20:02:32 +0100 Subject: [PATCH 67/71] docs(cli): demoflow share, share_demo and share.allowMcp in the README --- apps/cli/README.md | 45 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 43 insertions(+), 2 deletions(-) diff --git a/apps/cli/README.md b/apps/cli/README.md index febb8d5a..e9480c0e 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -202,6 +202,7 @@ typed value. Secret fills are left as recorded. | `demoflow run <scenario>` | run it in a browser and render the video | | `demoflow run --check [scenario]` | run and verify one scenario, or all of them, without a video | | `demoflow render <runId>` | render an existing run again with the current config | +| `demoflow share <runId>` | share a render of a reported run as a link on the website | | `demoflow list` | list recent runs of the current project, newest first | | `demoflow runs list` | list every run on this machine, with its size | | `demoflow runs delete <id…>` / `prune` | delete runs by id, or by age and state | @@ -336,12 +337,41 @@ fragments of URLs are removed, the project path becomes `<project>`, the home directory becomes `~`, and the text is cut to 1,000 characters. It can still contain text from the page under test or other paths. -Videos, frames and step values never leave the machine. +Videos, frames and step values never leave the machine, unless you share a +render (below). The report waits at most two seconds and fails silently; the run's output and exit code are never affected. It is off without `demoflow login`, under `CI`, and with `DEMOFLOW_NO_REPORT=1`. +## Share a render + +```sh +npx demoflow share <runId> +``` + +Makes a link to one render of a run that this machine reported, so anyone with +the link can watch it without an account. The runner uploads the file, so it +must be running (`demoflow runner start`). The command prints the share page's +link and, without a password, the file's own link, then exits 0 once the +upload is done. + +- `--format <format>` picks the render (default: the run's first one). +- `--expires <days>`: 7, 30 (default) or 90 days. +- `--password` asks for a password twice on the terminal, without echo; + without a terminal it reads `DEMOFLOW_SHARE_PASSWORD`. It is never a flag + value, so it never lands in your shell history. A protected share has no file + link (it would skip the password), so only the page link is printed. +- `--json` prints the share as one object on stdout. +- A render already shared keeps its link; the command prints it. Revoke it on + the website to share the render again. +- Only that render leaves the machine, with its poster frame, the chapters + (the scene cards) and the scenario's `description`. +- It exits 2 when the share cannot be made (not logged in, a run this + machine did not report, no such render, the runner offline or too old, the + file over the size limit, the quota full), 1 when the upload fails or is + still going after 10 minutes, and 3 when the server cannot be reached. + ## With Claude Code ```sh @@ -349,7 +379,18 @@ claude mcp add demoflow -- npx demoflow mcp ``` The server offers `generate_demo`, `get_task`, `cancel_task`, -`validate_scenario`, `list_demos` and `check_project`. +`validate_scenario`, `list_demos`, `check_project` and `share_demo`. + +`share_demo` shares a render of a reported run, like `demoflow share` without +a password. It is refused (`share-not-allowed`) unless the run's project allows +it in `demoflow.config.json`, which you commit: + +```json +{ "share": { "allowMcp": true } } +``` + +It waits up to 50 seconds for the upload; when the answer is still +`uploading`, call it again later for the same link. ## Updates From 61148a4f70150deae9a3b11cb2d07cc1f2ed936c Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Mon, 26 Oct 2026 20:25:45 +0100 Subject: [PATCH 68/71] style: format C-179 demo scenario --- .../C-179-feat-web-check-schedules-on-the-project.demo.json | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/demoflow/cards/C-179-feat-web-check-schedules-on-the-project.demo.json b/demoflow/cards/C-179-feat-web-check-schedules-on-the-project.demo.json index b2b6301d..2cebd49a 100644 --- a/demoflow/cards/C-179-feat-web-check-schedules-on-the-project.demo.json +++ b/demoflow/cards/C-179-feat-web-check-schedules-on-the-project.demo.json @@ -26,7 +26,11 @@ }, { "action": "click", - "target": { "role": "link", "name": "C-179 nightly checks", "exact": true } + "target": { + "role": "link", + "name": "C-179 nightly checks", + "exact": true + } }, { "action": "assertVisible", From 42fc75fd4178ae474d15754130708992fab54a5a Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Tue, 27 Oct 2026 10:38:29 +0100 Subject: [PATCH 69/71] fix(cli): list share_demo in the package smoke's expected MCP tools --- apps/cli/scripts/smoke.mjs | 1 + 1 file changed, 1 insertion(+) diff --git a/apps/cli/scripts/smoke.mjs b/apps/cli/scripts/smoke.mjs index 0084710a..13438069 100644 --- a/apps/cli/scripts/smoke.mjs +++ b/apps/cli/scripts/smoke.mjs @@ -46,6 +46,7 @@ const TOOLS = [ 'generate_demo', 'get_task', 'list_demos', + 'share_demo', 'validate_scenario', ]; const browsers = process.argv.includes('--browsers'); From 56a230413e1d56e644668cf64e7f5d6509a52591 Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Tue, 27 Oct 2026 11:00:24 +0100 Subject: [PATCH 70/71] test(cli): resolve the share spec's temp dir with the native realpath --- apps/cli/test/runner/share.spec.ts | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/apps/cli/test/runner/share.spec.ts b/apps/cli/test/runner/share.spec.ts index 78ab3c19..14b664c9 100644 --- a/apps/cli/test/runner/share.spec.ts +++ b/apps/cli/test/runner/share.spec.ts @@ -128,7 +128,11 @@ async function prepare( } beforeEach(() => { - base = realpathSync(mkdtempSync(path.join(tmpdir(), 'demoflow-share-'))); + // The preparer resolves with the native realpath, which expands the 8.3 + // short names of a Windows temp dir (RUNNER~1); the JS one does not. + base = realpathSync.native( + mkdtempSync(path.join(tmpdir(), 'demoflow-share-')), + ); root = path.join(base, 'project'); runDir = path.join(base, 'home', 'runs', 'local-run'); mkdirSync(root, { recursive: true }); From aee6deb1971dc74f526b109e489789dddfcfd59f Mon Sep 17 00:00:00 2001 From: Archi <abegma137@gmail.com> Date: Tue, 27 Oct 2026 11:19:45 +0100 Subject: [PATCH 71/71] docs(web): document adding a project from the website and allowed roots --- apps/web/src/app/docs/cli/page.mdx | 15 ++++ apps/web/src/app/docs/runner/page.mdx | 101 +++++++++++++++++++++++++- 2 files changed, 113 insertions(+), 3 deletions(-) diff --git a/apps/web/src/app/docs/cli/page.mdx b/apps/web/src/app/docs/cli/page.mdx index 82bb01d0..9bb0c756 100644 --- a/apps/web/src/app/docs/cli/page.mdx +++ b/apps/web/src/app/docs/cli/page.mdx @@ -227,6 +227,21 @@ advance whether to start the runner. `demoflow logout` revokes the token and deletes the file. Every other command works without an account. See [Runner](/docs/runner). +## runner + +`demoflow runner start | stop | status | logs | install | uninstall` manage the +background process. Three more subcommands set which folders the website may +name when you add a project from it: + +```sh +npx demoflow runner roots [--json] +npx demoflow runner allow <dir> +npx demoflow runner disallow <dir> +``` + +By default only your home directory is allowed, without hidden folders. See +[Allowed folders](/docs/runner#allowed-folders). + ## Updates A globally installed `demoflow` asks npm for the latest version while a command diff --git a/apps/web/src/app/docs/runner/page.mdx b/apps/web/src/app/docs/runner/page.mdx index 20e66991..058765dc 100644 --- a/apps/web/src/app/docs/runner/page.mdx +++ b/apps/web/src/app/docs/runner/page.mdx @@ -5,7 +5,8 @@ export const metadata = { title: 'Runner' }; You can pair a machine with your DemoFlow account and keep it connected, so the website shows it online. Nothing here is needed to make videos: every other command works without an account. With the runner connected, the site can also -start runs on the machine and delete a run's files. +add a project from a folder on the machine, start runs on it and delete a run's +files. ## Pair a machine @@ -79,8 +80,10 @@ no folder or its machine was removed. ### Which scenarios are listed - A project can be run from the site only after this machine has reported a run - from its folder. Run `demoflow run` in the folder once. A folder bound by hand - is not enough. + from its folder, or after you added the folder from the website (see [Add a + project from the website](#add-a-project-from-the-website)). Run `demoflow + run` in the folder once, or add it there. A folder bound by hand is not + enough. - The list holds every `*.demo.json` under the project's `demoflow/` folder, subfolders included, shown by name with its path. - The machine reads the list when the card opens or when you press **Refresh**, @@ -146,6 +149,98 @@ with an older `demoflow` shows only **Running**. reported, so it never appears in the library and cannot be deleted from the site. To remove it, delete `runs/<id>/` in the DemoFlow home on the machine. +## Add a project from the website + +A project appears on the site after a local run, or when you add its folder +from the website. Adding needs a paired machine whose runner is connected and +whose CLI is up to date. Nothing is cloned or downloaded: the folder must +already be on that machine. + +1. On **Projects**, press **Add project**. +2. Choose the machine. A machine that is offline or runs an older CLI is + marked and cannot be chosen. The page preselects the machine that reported + the latest run. +3. Type the folder as an absolute path on that machine, for example + `/home/you/my-app`, `/Users/you/my-app` or `C:\Users\you\my-app`. After you + stop typing, the machine looks at the folder. +4. The dialog shows what the machine found: + - **`demoflow.config.json` found:** the folder name, up to five scenario + names with the count, and the GitHub link of the `origin` remote when it + is on `github.com`. + - **No config:** press **Create config**. The machine writes + `demoflow.config.json` and `demoflow/first.demo.json`, the same files as + `demoflow init`, and never overwrites a file that exists. The dialog names + the files it wrote. Then set `devCommand` and `baseUrl` in + `demoflow.config.json` in the repository: the website cannot set them. + - **A config that cannot be read:** fix it in the repository, then type the + path again. +5. Give the project a name and, if you like, its GitHub repository + (`https://github.com/<owner>/<repo>`). The link is only shown on the site and + can be edited later; nothing is fetched from it. +6. Press **Add project**. The project opens, and you can run its scenarios from + the site. + +### When the dialog refuses + +| Message | Why | Fix | +|---|---|---| +| `Offline` next to a machine, or "This machine went offline" | The runner is not connected. | Run `demoflow runner start` on the machine. | +| `Update the CLI` | The machine's CLI is older than this feature. | Update `demoflow` there and restart its runner. | +| "This folder is outside the folders this machine allows" | The folder is not inside an allowed folder, or a part of its path below it starts with a dot. The same message appears for a folder that does not exist. | On that machine run `demoflow runner allow <dir>`. See [Allowed folders](#allowed-folders). | +| "This folder has no demoflow.config.json" | The folder has no config. | Press **Create config**, or run `demoflow init` in it. | +| "The demoflow.config.json in this folder is not valid" | The config does not pass validation. | Fix it in the repository, then type the path again. | +| "This folder is already a project" | The folder is registered. | Press **Open the existing project**. | +| "This machine is busy" or "did not answer in time" | The machine is working on another request. | Try again in a moment. | + +## Allowed folders + +The machine decides which folders the website may name, not the website. The +list is kept in `allowed-roots.json` next to `credentials.json`, and only you +change it, on the machine. No request from the server reads or changes it. The +runner reads the file for every request, so a change needs no restart. + +By default the one allowed folder is your home directory. The website may name +a folder inside an allowed folder, with two limits: + +- **No hidden folders.** A folder whose path, below the allowed folder, has a + segment starting with `.` is refused: `~/.ssh`, `~/.config`, `~/.cache`. Allow + such a folder itself if you need it. +- **Real paths.** The folder is resolved first; a symbolic link that leads + outside the allowed folders is refused. + +```sh +npx demoflow runner roots +npx demoflow runner allow ~/work +npx demoflow runner allow 'D:\Projects' +npx demoflow runner disallow ~/work +``` + +| Command | What it does | +|---|---| +| `demoflow runner roots` | Print the allowed folders, marking the default. `--json` prints one object. Exits 1 when the file is invalid. | +| `demoflow runner allow <dir>` | Add an existing directory, by its real path. A relative path is resolved against the current folder. The first `allow` replaces the default home directory; allow the home directory again to keep it. At most 32 folders. | +| `demoflow runner disallow <dir>` | Remove a folder from the list. Removing the last one allows nothing: the website may name no folder. It does not bring the default back. | + +On Windows use a drive path such as `D:\Projects`; network (UNC) and device +paths are refused. A file that does not parse allows nothing until you fix or +delete it, and `roots` says so. + +### What the website can and cannot see + +For a folder inside the allowed folders the website can learn whether it holds +a valid `demoflow.config.json`, its scenario names and its GitHub `origin`. The +runner reads the remote from the repository's git file and never runs `git`. It +can write the two **Create config** files into a folder that has no config, and +register a folder that has one. + +It cannot clone or download anything, overwrite a file, read any other file, or +set `devCommand`: that stays yours, in the repository. A folder outside the +allowed folders is refused with the same answer whether or not it exists. + +A folder you added from the website stops being served for website-started runs +if you `disallow` it, until you allow it again. A folder registered by a local +run is not affected. + ## Delete a run's files On a run's page, **Delete video files** removes the run's files from the machine