demoman 0.7.2 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/recipe.md CHANGED
@@ -11,12 +11,13 @@ the user; section 7 lists every reason.
11
11
  1. Call `status`. It answers `executor` (`"cli"`), `version`,
12
12
  `browserInstalled`, `browserRunning`, `runnerVersion`, `runPage` (the
13
13
  latest run's report or its progress, or null), `sessions`, `accounts`,
14
- `secretsFile` and `update`.
14
+ `secretsFile`, `expiry` and `update`.
15
15
  `sessions` is `[{site, savedAt, refreshedAt, signInUrl}]`; it and
16
- `display` (the screen headless records as) can be `{unreadable}`: tell the user why. `accounts` and `secretsFile` are the demo
17
- accounts below. The browser starts on the first `snapshot`, `run`
18
- or `export`. Demoman updates itself: say nothing about `update`. When `browserInstalled` is false, the first
19
- `snapshot` or `run` answers `browserMissing`.
16
+ `display` can be `{unreadable}`: tell the user why. `accounts` and
17
+ `secretsFile` are the demo accounts below. The browser starts on the
18
+ first `snapshot`, `run` or `export`. Say nothing about `update`. When
19
+ `browserInstalled` is false, the first `snapshot` or `run` answers
20
+ `browserMissing`.
20
21
  2. The browser is signed in wherever the user ran `npx demoman signin <url>`,
21
22
  and nowhere else; `status`'s `sessions` lists those sites. A demo account records best. A page
22
23
  that sends this browser to its sign-in page answers `signedOut` (section
@@ -29,8 +30,8 @@ the user; section 7 lists every reason.
29
30
  hidden on disk and in the report.
30
31
  3. Takes are saved under `<DEMOMAN_HOME, default ~/.demoman>/takes/<id>/`.
31
32
  `takes` lists them, newest first: `id`, `name`, `createdAt`, `mode`,
32
- `actions`. A folder that is not a readable take comes last as
33
- `{ id, unreadable }`, saying why. Demoman keeps no telemetry.
33
+ `actions`; an unreadable folder comes last as `{ id, unreadable }`.
34
+ Demoman keeps no telemetry.
34
35
 
35
36
  ### Behind a login: demo accounts
36
37
 
@@ -70,15 +71,16 @@ its site. Then, in this order:
70
71
  create a demo account and the data the demo needs, with a seed script
71
72
  committed in the app and safe to run twice (`priv/repo/demo_seeds.exs`,
72
73
  `db/seeds/demo.rb`). Generate a random password of 20 or more characters.
73
- Write `DEMOMAN_SECRET_<NAME>=…` to `.demoman/secrets.env`, and add
74
+ Write `DEMOMAN_SECRET_<NAME>=…` and
75
+ `DEMOMAN_SECRET_<NAME>_ORIGIN=<the site's origin>` to
76
+ `.demoman/secrets.env`, and add
74
77
  `.demoman/secrets.env` to `.gitignore` if it is missing. Add the account
75
78
  to `accounts.json`. Tell the user in one line.
76
79
  Then `snapshot` again.
77
80
  3. **Two-factor or a magic link in the way:** add a dev-only "sign in as"
78
81
  route, reachable only in development, and make the account's `signIn` one
79
82
  `goto` to it. Phoenix:
80
- `if Mix.env() == :dev, do: get "/dev/sign-in-as/:email", DevController, :sign_in`.
81
- Rails: `get "/dev/sign_in_as/:email", to: "dev#sign_in" if Rails.env.development?`.
83
+ `if Mix.env() == :dev, do: get "/dev/sign-in-as/:email", DevController, :sign_in`; Rails: the same under `Rails.env.development?`.
82
84
  The action starts a session; nothing else.
83
85
  4. **The database is not clearly local** (a remote `DATABASE_URL`, staging,
84
86
  production): create nothing. Ask the user, or give them
@@ -113,24 +115,22 @@ The file, with one account:
113
115
  ```
114
116
 
115
117
  - Sites are keyed by origin. An account name is lower-case letters,
116
- digits, `-` and `_`, starting with a letter or digit, at most 64
117
- characters: `seller`, `demo-customer`. `signIn` uses the script's steps and targets
118
+ digits, `-` and `_`, at most 64: `seller`. `signIn` uses the script's steps and targets
118
119
  (`type` names its field with `into`; copy targets from a `snapshot` of the
119
120
  login page) plus `goto`, which must be the first step. `checkUrl` is
120
121
  required: a page behind the login, a path on the origin, that a browser
121
- signed in to nothing cannot open (the app redirects it to its sign-in
122
- page, or shows a password form there) and that shows no password field
123
- once signed in. Demoman opens it signed out first and treats where it
124
- lands as the sign-in page. `about` names who the account is and what data
122
+ signed in to nothing cannot open (it redirects to sign-in, or shows a
123
+ password form) and that shows no password field once signed in. Demoman
124
+ opens it signed out first and treats where it lands as the sign-in page. `about` names who the account is and what data
125
125
  it has, so the next agent reuses it.
126
126
  - `{secret:NAME}` goes in a `signIn` step's `text`, `NAME` being
127
127
  `[A-Z0-9_]+`, not ending in `_ORIGIN`. Demoman reads
128
128
  `DEMOMAN_SECRET_NAME` from the environment, else the same line of
129
129
  `.demoman/secrets.env`, which it reads only when git ignores it. A value
130
- is at least 8 characters. An environment value is typed only with
131
- `DEMOMAN_SECRET_NAME_ORIGIN` beside it, naming the account's site; the
132
- user sets both, and you never set or change them. `secrets.env` lines
133
- need no origin. A `{secret:…}` in a demo
130
+ is at least 8 characters, typed only with `DEMOMAN_SECRET_NAME_ORIGIN`
131
+ beside it, naming the account's site. In the environment the user sets
132
+ both and you never change them; in `secrets.env` you write both.
133
+ A `{secret:…}` in a demo
134
134
  script is refused (`invalidScript`): secrets work only in `signIn`.
135
135
  Environment secrets serve only the accounts.json of the repo Demoman was
136
136
  started in; one reached through `project` reads only its own
@@ -157,10 +157,6 @@ The file, with one account:
157
157
  (`{account, steps, ms}`) in the snapshot or the report says it did. A
158
158
  second failure answers `signInFailed`. A session that lapses mid-run keeps
159
159
  no take; Demoman has signed in again: just run again.
160
- - In CI: `npx demoman signin --account <name>` as a smoke step (`--site
161
- <origin>` when two sites share a name, `--project <dir>` for another
162
- folder), with `DEMOMAN_SECRET_*` from the CI provider's secrets,
163
- each with its `DEMOMAN_SECRET_*_ORIGIN`.
164
160
 
165
161
  ## 2. Look at the page
166
162
 
@@ -169,8 +165,7 @@ and leaves the page open. Each entry is
169
165
  `{ target, kind, text, rect, inFirstViewport }`. Every `target` listed is one
170
166
  a run resolves to exactly that element: Demoman checked it.
171
167
 
172
- `snapshot` may answer `stillRunning` with an `id` after about 50 s, like
173
- `run`: call `report(id)`.
168
+ `snapshot` may answer `stillRunning` too: call `report(id)`.
174
169
 
175
170
  - **Copy a `target` into a step verbatim. Never compose one**, and never
176
171
  translate a name from another tool's accessibility tree: Demoman's roles
@@ -209,11 +204,10 @@ a run resolves to exactly that element: Demoman checked it.
209
204
  for the part you need; with it given, a positive count means narrow it
210
205
  further.
211
206
  - Iframe and shadow-root elements are not listed.
212
- - A snapshot sees only the page as it loads: no steps. Hidden content
213
- already in the page is listed. Content a click creates (a dialog or menu
214
- built when it opens) is not, so a step on it has no target: tell the user
215
- it cannot be scripted yet. Never compose its target. A page the flow
216
- navigates to has its own URL to snapshot.
207
+ - A snapshot sees only the page as it loads: hidden content already in the
208
+ page is listed; content a click creates (a dialog or menu built when it
209
+ opens) is not, so a step on it has no target: tell the user it cannot be
210
+ scripted yet. A page the flow navigates to has its own URL to snapshot.
217
211
 
218
212
  ### Recording a phone demo
219
213
 
@@ -272,19 +266,26 @@ to change and run again.
272
266
  - `unreadable` - a stored take cannot be read; report its `reason`.
273
267
  - `threw` - report its `error`.
274
268
 
275
- **Re-recording an edited take.** `run({ takeId })` runs a take again from its
276
- saved script and its current `scene.json`: the steps' text and targets,
277
- name and look as they are now, the original's pauses, and any step added
278
- since. It is a run: a new take, counted toward the three. Pass `takeId` instead of `script`; both
279
- or neither is `invalidScript`. Refused with `unfilledHoles` when
280
- the take did not keep a value (a redacted field): `derive`, fill, `run`.
281
- Refused with `invalidScript` (`field` `steps.<i>.do`) when a step's verb
282
- was changed by hand: `derive`, check that step, `run` the draft.
283
- Refused with `nothingToRerecord` when no step that acts is left.
269
+ **Re-recording an edited take.** `run({ video: { id } })` with no `script`
270
+ records the video's current version again from its saved script and current
271
+ `scene.json` (steps, name, look, pauses, added steps), as a new version and a
272
+ run toward the three. Refused with `unfilledHoles` when the take did not keep
273
+ a value: `derive`, fill, `run`. `invalidScript` (`field` `steps.<i>.do`): a
274
+ verb was changed by hand: `derive`, check it, `run` the draft.
284
275
 
285
276
  ## 4. Run and read
286
277
 
287
- 1. `run(script)`. It answers the run's report, or
278
+ 0. Name the video first: every run adds a version to one. If the repo
279
+ has an exported file of it, `videos({ file:
280
+ <absolute path> })`. Else `videos({ query: "<what the flow shows>" })`;
281
+ `videos()` lists the repo's. Answers: `{ videos, unreadable, deferred }`;
282
+ `file` adds `{ version, current, expired }`. Then `run({ script, video:
283
+ { id } })` adds a version; `video: { new: "<name>" }` starts one.
284
+ `possibleDuplicate` lists `matches`: use one's `id`, or repeat with
285
+ `confirmedNew: true` for a different flow. `nameTaken` names the
286
+ `holder`: use its `id` or another name. The report's `videoVersion`
287
+ (`id`, `version`, `created`) says what was made.
288
+ 1. `run(script, video)`. It answers the run's report, or
288
289
  `{ "outcome": "stillRunning", "id": … }` after about 50 s; then call
289
290
  `report(id)` until the outcome is neither `running` nor `stillRunning`.
290
291
  Never `run` again while one is in progress: it is refused
@@ -310,10 +311,9 @@ Refused with `nothingToRerecord` when no step that acts is left.
310
311
  show the way the script asked. `matches` with every
311
312
  `steps[i].candidates` at 1 means the steps are right.
312
313
  - In any outcome, a step whose `textHidden` is set typed into a credential
313
- field (`"credentialField"`) or the page could not say whether it was
314
- (`"credentialUnchecked"`): its text is kept nowhere, and `intent.text` reads `(hidden: typed into a
315
- credential field)`. Re-recording or deriving that take asks for a demo
316
- value. `landing.startedElsewhere` names where the start URL went
314
+ field (`"credentialField"`, or `"credentialUnchecked"` if the page could
315
+ not say): its text is kept nowhere. Re-recording or deriving that take
316
+ asks for a demo value. `landing.startedElsewhere` names where the start URL went
317
317
  instead; `landing.unchecked`: the page could not be checked for a
318
318
  sign-in page. `notStored` with `what: "session"` means the saved
319
319
  session could not be refreshed: name it to the user.
@@ -328,10 +328,8 @@ Refused with `nothingToRerecord` when no step that acts is left.
328
328
  `frames.unconfirmedClicks` names each such step and says why; check in
329
329
  the video that the step did what it should before saying so.
330
330
  - A re-recording's report carries `rerecord`: `from` (the take), `notes`
331
- (`noSkeleton` or `skeletonUnreadable`: the original's pauses were not
332
- kept; `stepDropped`, with `why` `actionGone` or `neverPerformed`;
333
- `actionAdded`: a `scene.json` step the saved script lacked;
334
- `migrated`: a `sentence`) and `notCarried` (each `removed`, `split`,
331
+ (as `report.skeleton` above, `stepDropped` with `why` `actionGone` or
332
+ `neverPerformed`; `migrated`: a `sentence`) and `notCarried` (each `removed`, `split`,
335
333
  mask, hold, gap or trim the old take had and the new one lacks, and
336
334
  each zoom the editor aimed or ended by hand, `zoom`; every other zoom
337
335
  the new take makes again from its own clicks). Name every
@@ -346,8 +344,7 @@ Refused with `nothingToRerecord` when no step that acts is left.
346
344
  whose `actionId` equals `video.steps[i].actionId`; `steps[k].index` is
347
345
  its 0-based position in your script.
348
346
  - `video` may be `{ "unavailable": … }` (`refused`, `noTake`, `noFrames`,
349
- `checkFailed` with `error`): the check could not look. That is not a
350
- clean bill; say so, and do not retry. Likewise
347
+ `checkFailed` with `error`): not a clean bill; say so, do not retry. Likewise
351
348
  `video.steps[i].unknown` and `video.noCursor: true`.
352
349
  - `recording` is `{ "unavailable": … }` or
353
350
  `{ recordingTakeId, steps[], notInRecording[] }`, comparing the run with
@@ -368,8 +365,7 @@ Refused with `nothingToRerecord` when no step that acts is left.
368
365
  than the target you named.
369
366
 
370
367
  **Stop after three runs**, done or not, then export: every run drives the
371
- user's real app. A take
372
- zooms on every click and starts from the kit named in `look.kit`, else the
368
+ user's real app. A take zooms on every click and starts from the kit named in `look.kit`, else the
373
369
  user's default brand kit; a draft derived from a take keeps that take's
374
370
  branding. The report's `look.branding` says where it came from: `script`,
375
371
  `kit` (you named it; `look.kit.name` says which), `defaultKit`, or
@@ -410,12 +406,12 @@ too.
410
406
  lacks (a logo, motion, a still, an edit). `warnings` holds more:
411
407
  Demoman's own calls (`zooms`, `detailViolations`, a size cap's `steps`,
412
408
  a GIF's widths, `targetCheck`). They are
413
- not the user's to act on: do not pass them on. None is the script's to
414
- fix either.
409
+ not the user's to act on: do not pass them on. None is the script's to fix.
415
410
  `warnings.editedSinceRecorded` lists steps whose `scene.json` no longer
416
411
  matches the frames; the summary says so and names the re-recording
417
- (`run({ takeId })`, or `derive` then `run` when a step's verb changed).
418
- Re-record only on request.
412
+ (`run({ video: { id } })`, or `derive` then `run` when a verb changed).
413
+ Re-record only on request. `warnings.untagged`: the file has no video
414
+ tag (`error` says why); not the user's to act on.
419
415
  `links` holds the export's one-click actions for the user, each present
420
416
  only where it works: `studio`, `file` (the file itself) and `copy` (the
421
417
  file to the clipboard; none for stills). `linksError`, set instead, says
@@ -434,39 +430,35 @@ too.
434
430
 
435
431
  ### Pull requests
436
432
 
437
- Before opening a pull request, read `status.pullRequests` (pass `project`
438
- in another checkout): `attach`, `ask`, `off`, or `{ unreadable, file }`,
433
+ Before opening a PR, read `status.pullRequests` (`project` for
434
+ another checkout): `attach`, `ask`, `off`, or `{ unreadable, file }`,
439
435
  which is not `off`: tell the user. `off`: only when asked. If the diff
440
- changes something a user would see, record that one flow (only the change),
436
+ changes what a user sees, record that one flow (only the change),
441
437
  push and open the PR, then `attach({ takeId, into: "description" })`, or
442
- `"comment"` on a PR that is not yours. A later `gh pr edit --body` drops the
443
- video. `ask`: offer once; on a no, nothing to see or a failed run (say why),
438
+ `"comment"` on a PR that is not yours. The video carries its own line; write no other. On `line.notWritten`,
439
+ tell the user the video lacks its line, quoting why. A later `gh pr edit --body` drops the video. `ask`: offer once; on a no, nothing to see or a failed run (say why),
444
440
  the PR says nothing of it. `attach`: with no video, the PR description gets
445
441
  one line, `No demo: <why>`, and so does the user.
446
442
  `attach` takes `maxMB` as `export` does. On `stillRunning`, `report(id)`
447
- until the outcome is none of `attaching`, `stillRunning`. On `busy`,
448
- `report(id)` on the export in flight, then `attach` again. On `ghMissing`, `ghOutdated`,
449
- `ghSignedOut`, `notGitHub` or `copyFailed`, call
450
- `export({ takeId, maxMB: 9.5 })` and give the user that `file.path` to drag
451
- into the PR, saying why: the browser refuses video over 10 MB on a free
452
- plan. On `uploadRefused`, do as its `detail` says: one more `attach` with
453
- `maxMB: 9.5`, or the file by hand. On `partial` or `unconfirmed`, do not
454
- post again; tell the user to look at the PR. For the other reasons, follow
455
- section 7. An export that did not save comes back as the export's answer.
443
+ until the outcome is neither `attaching` nor `stillRunning`. On `busy`,
444
+ `report(id)` on the export in flight, then `attach` again. On `ghMissing`,
445
+ `ghOutdated`, `ghSignedOut`, `notGitHub` or `copyFailed`, call
446
+ `export({ takeId, maxMB: 9.5 })` and give the user its `file.path` to drag
447
+ into the PR, saying why. On `uploadRefused`, do as its `detail` says. On `partial` or `unconfirmed`, do not
448
+ post again; tell the user to check the PR. Other reasons: section 7. An unsaved export answers as `export` does.
456
449
 
457
450
  Hand back, on `saved`, two lines and nothing else: the `summary` as it is,
458
- then the `links` as markdown links on one line, in this order and only
451
+ then the `links` as markdown links on one line, in this order, only
459
452
  those present: `[Open in Studio](links.studio) · [<file name>](links.file) · [Copy video](links.copy)`
460
453
  (`Copy GIF` for a GIF). Add one line only for `look.brandKitError`,
461
- `size.error`, `linksError`, or something you could not fix. For any other
462
- outcome, say it with its `error` or `detail`, quoted.
454
+ `size.error`, `linksError`, or something you could not fix. Any other
455
+ outcome: quote its `error` or `detail`.
463
456
 
464
- When the `studio` tool is listed and there is no `links.studio` (after a
465
- run with no export), **offer** it; never open it unasked. `studio({ takeId })`
466
- opens a window where the person edits and exports the take.
467
- `{ outcome: "opened", url, takeId?, note? }`: say the window is open and
468
- quote `note` if set; `url` is single-use, never offer it. Studio exports go
469
- to `~/Downloads`.
457
+ When the `studio` tool is listed and there is no `links.studio`, **offer**
458
+ it; never open it unasked. `studio({ takeId })`
459
+ opens a window to edit and export the take.
460
+ `{ outcome: "opened", takeId?, note? }`: say the window is open;
461
+ quote `note` if set. Studio exports go to `~/Downloads`.
470
462
 
471
463
  ## 6. The format
472
464
 
@@ -531,12 +523,11 @@ recorded action each step came from (`recorded`, in `recordedFrom`):
531
523
  `viewport`, not both. A device has no hover, so a `hover` step under one is
532
524
  refused. `look` takes `branding` or `kit`, plus `cursor`, `canvas` and
533
525
  `motion`; absent means the user's default brand kit. `kit` names one of
534
- the user's brand kits, as `snapshot`'s `kits` lists them (case does not
535
- matter); name a kit or give a branding, not both. An unknown key in
536
- `look` is refused and named. A `branding` is the whole of one: `background`, `logo` (or `null`) and `padding`, the
537
- margin around the recording as a fraction of the frame's shorter side
538
- (0 to 0.2). A `padding` left out is 0.08; a missing `background` or
539
- `logo` is refused and named.
526
+ `snapshot`'s `kits` (case does not matter); name a kit or give a
527
+ branding, not both. An unknown key in `look` is refused and named. A
528
+ `branding` is the whole of one: `background`, `logo` (or `null`) and
529
+ `padding`, the margin as a fraction of the frame's shorter side (0 to
530
+ 0.2; left out is 0.08); a missing `background` or `logo` is refused.
540
531
  A `canvas` is `{ "aspect": "auto" | "16:9" | "9:16" }`; `auto`, the
541
532
  default, is the recording's own shape plus an even margin.
542
533
  A `motion` is how the camera moves, `{ "smoothness": 0-1, "blur": 0-1, "follow": true | false }`; a derived draft carries the take's own, so keep it.
@@ -549,14 +540,15 @@ recorded action each step came from (`recorded`, in `recordedFrom`):
549
540
 
550
541
  | Reason | Where | What it means, and the move |
551
542
  | --- | --- | --- |
552
- | `browserMissing` | `snapshot`, `run` (`refusedBeforeRun`), `studio` | Demoman's browser is not installed; `detail` gives the command that installs it. Ask the user to run it, then call again. |
553
- | `sessionUnreadable` | `snapshot`, `run` (`refusedBeforeRun`) | A saved session file or folder could not be read, or others can read it; `detail` names it and the fix (often a `chmod`). Tell the user; it is not the script's. |
543
+ | `browserMissing` | `snapshot`, `run` (`refusedBeforeRun`), `studio` | Demoman's browser or its libraries are missing; `detail` gives the command. Ask the user to run it, then call again. |
544
+ | `unsupportedPlatform` | `snapshot`, `run`, `export` | This machine cannot record (arm64 Linux, or another OS); quote `detail` to the user. |
545
+ | `sessionUnreadable` | `snapshot`, `run` (`refusedBeforeRun`) | A saved session file or folder could not be read, or others can read it; `detail` names the fix. Tell the user. |
554
546
  | `sessionNotLoaded` | `snapshot`, `run` (`refusedBeforeRun`) | The browser refused the saved sessions; `detail` says why. Tell the user to run `npx demoman signin` again for that site. |
555
- | `signInFailed` | `snapshot`, `run` (`refusedBeforeRun`) | Demoman signed in as the account and the page still showed a sign-in page, or a step could not run; `detail` names the account, the step and where it landed. It tried once. Fix the account's steps or the secret, or tell the user; do not run again unchanged. |
556
- | `secretMissing` | `snapshot`, `run` (`refusedBeforeRun`) | A `{secret:NAME}` has no `DEMOMAN_SECRET_NAME` and no line in `.demoman/secrets.env`; `detail` names `NAME` and both places. Through `project`, the environment is not used, and `detail` says so when it holds the name. Write one (section 1), or ask the user. |
547
+ | `signInFailed` | `snapshot`, `run` (`refusedBeforeRun`) | Demoman signed in as the account and the page still showed a sign-in page, or a step could not run; `detail` says where. It tried once. Fix the account's steps or the secret, or tell the user; do not run again unchanged. |
548
+ | `secretMissing` | `snapshot`, `run` (`refusedBeforeRun`) | A `{secret:NAME}` has no `DEMOMAN_SECRET_NAME` and no line in `.demoman/secrets.env`; `detail` names both. Through `project` the environment is not used. Write one (section 1), or ask the user. |
557
549
  | `secretTooShort` | `snapshot`, `run` (`refusedBeforeRun`) | The secret `NAME` is under 8 characters. Generate a longer one and write it again. |
558
- | `secretUnbound` | `snapshot`, `run` (`refusedBeforeRun`) | `DEMOMAN_SECRET_NAME` is in Demoman's environment with no `DEMOMAN_SECRET_NAME_ORIGIN`, or one that is not an origin; `detail` names the variable and the site. Nothing was typed. Tell the user; never set it yourself. |
559
- | `secretOffOrigin` | `snapshot`, `run` (`refusedBeforeRun`) | A secret was about to be typed off its site: a sign-in step's page is not the site's origin, or an environment secret's `_ORIGIN` names another site; `detail` names both. Nothing was typed. Check the account's site and `goto`, then tell the user. |
550
+ | `secretUnbound` | `snapshot`, `run` (`refusedBeforeRun`) | `DEMOMAN_SECRET_NAME` has no `DEMOMAN_SECRET_NAME_ORIGIN` beside it, or one that is not an origin; `detail` names the line and the site. Nothing was typed. Add it to `secrets.env` for an account you made; else tell the user. |
551
+ | `secretOffOrigin` | `snapshot`, `run` (`refusedBeforeRun`) | A secret was about to be typed off its site: a sign-in step's page is not the site's origin, or the secret's `_ORIGIN` names another site; `detail` names both. Nothing was typed. Check the account's site and `goto`, then tell the user. |
560
552
  | `secretsFileNotIgnored` | `snapshot`, `run` (`refusedBeforeRun`) | Git does not ignore `.demoman/secrets.env`, so Demoman did not read it. Add `.demoman/secrets.env` to `.gitignore` (`detail` says the line), or take the file out of git if tracked. |
561
553
  | `secretsFileInvalid` | `snapshot`, `run` (`refusedBeforeRun`) | A line of `.demoman/secrets.env` is not `DEMOMAN_SECRET_NAME=value`, a comment or blank; `detail` gives the line number. Fix it. |
562
554
  | `accountsInvalid` | `snapshot`, `run` (`refusedBeforeRun`) | `.demoman/accounts.json` is malformed or breaks a rule; `detail` names the field and the rule. Fix the file. |
@@ -565,38 +557,46 @@ recorded action each step came from (`recorded`, in `recordedFrom`):
565
557
  | `ghMissing`, `ghOutdated`, `ghSignedOut` | `attach` (`refusedBeforeAttach`) | `gh` is missing, too old or signed out; `detail` gives the fix. Hand the user the file (section 5). |
566
558
  | `notGitHub`, `prNotFound`, `prUnreadable` | `attach` (`refusedBeforeAttach`) | Not a GitHub remote; no such PR; the PR could not be read. Nothing was posted: quote `detail` to the user. |
567
559
  | `invalidAttach` | `attach` (`refusedBeforeAttach`) | The call is malformed; `detail` says how. Fix it. |
568
- | `uploadRefused` | `attach` (`notAttached`) | GitHub refused the video and nothing landed. Retry as the Pull requests text says. |
560
+ | `uploadRefused` | `attach` (`notAttached`) | GitHub refused the video. Retry as the Pull requests text says. |
569
561
  | `partial` | `attach` (`notAttached`) | `gh` failed but the video is on the PR; do not post again. |
570
- | `unconfirmed` | `attach` (`notAttached`) | Unknown what landed: the PR shows nothing new, or could not be read back. Do not post again; tell the user to look at it. |
571
- | `copyFailed` | `attach` (`notAttached`) | The video could not be copied to post it; nothing was posted. Hand the user the capped export's file. |
562
+ | `unconfirmed` | `attach` (`notAttached`) | Unknown what landed. Do not post again; tell the user to look at the PR. |
563
+ | `copyFailed` | `attach` (`notAttached`) | The video could not be copied; nothing was posted. Hand the user the capped export's file. |
572
564
  | `windowDidNotOpen` | `snapshot`; `run` (`refusedBeforeRun`); `studio` | The window would not open; try once more. |
573
565
  | `studioDidNotStart` | `studio` | The Studio did not start; `detail` quotes the end of `~/.demoman/studio.log`. Tell the user, quoting it. |
574
- | `alreadyRunning` | `snapshot`, `run`, `derive` | A run, snapshot or export is in progress. Call `report(id)` on it and try again when it settles. |
575
- | `busy` | `export` (`refusedBeforeExport`) | The same, for an export: a run or snapshot is in progress. Call `report(id)` on that call first. |
576
- | `browserSilent` | `status`, `takes`, `derive`, `report` | Demoman's browser did not answer within about 50 s (frozen, or still starting). Call `status` once; if it answers this again, tell the user. From `report`, the run may still be going: call `report(id)` again. |
566
+ | `alreadyRunning` | `snapshot`, `run`, `derive` | A run, snapshot or export is in progress. Call `report(id)` on it; try again when it settles. |
567
+ | `busy` | `export` (`refusedBeforeExport`) | A run or snapshot is in progress. Call `report(id)` on it first. |
568
+ | `browserSilent` | `status`, `takes`, `derive`, `report` | The browser did not answer within about 50 s. Call `status` once; if again, tell the user. From `report`, the run may still be going: call `report(id)` again. |
577
569
  | `libraryUnreadable` | `takes`, `studio` | The library could not be read; report it. |
578
- | `libraryUnwritable` | `run` (in `notStored`) | Not a `reason`: a take that cannot be written gives the report a `notStored` entry `{ "what": "take", "error": … }` naming the path, and a null `provenance.takeId`. Nothing was saved; quote the `error`. |
579
- | `unknownRun` | `report` | This demoman-mcp never issued that id (ids do not survive a restart of the server). |
580
- | `noReport` | `report` | No report for that id: this server keeps only its latest runs and exports (an old one was let go), or the call left none; `detail` says which. Do not run again for it. |
570
+ | `libraryUnwritable` | `run` (in `notStored`) | Not a `reason`: the report has a `notStored` entry `{ "what": "take", "error": … }` and a null `provenance.takeId`. Nothing was saved; quote the `error`. |
571
+ | `unknownRun` | `report` | This demoman-mcp never issued that id (ids do not survive a server restart). |
572
+ | `noReport` | `report` | No report for that id: this server keeps only its latest; `detail` says which. Do not run again. |
581
573
  | `notAnObject` | `run` | The script is not a JSON object. |
582
574
  | `invalidScript` | `run` | The schema refused the script; `field` names where. |
583
- | `unfilledHoles` | `run` | A derived draft still has holes (section 3); also `run({ takeId })` of a take that did not keep a value. |
575
+ | `unfilledHoles` | `run` | A derived draft still has holes (section 3); also a re-record of a take that did not keep a value. |
576
+ | `videoRequired` | `run` (`refusedBeforeRun`) | No `video` was given. Find one (section 4), or pass `{ new }`. |
577
+ | `possibleDuplicate`, `nameTaken` | `run` (`refusedBeforeRun`) | A similar video exists (`matches`) or the name is taken (`holder`). Section 4. |
578
+ | `videoNotFound` | `run` (`refusedBeforeRun`) | No video has that `id`; call `videos`. |
579
+ | `videoUnreadable`, `videoUnwritable` | `run` (`refusedBeforeRun`), `videos` | The video records could not be read or written; quote `detail`. Nothing was recorded. |
580
+ | `noTag`, `unknownVideo`, `fileNotFound` | `videos` | The file has no Demoman tag; its video is not in this library; no file there. Use `query` instead. |
581
+ | `invalidArgs` | `videos` | `file` with `query`, or not an absolute path. |
582
+ | `versionExpired` | `export` (`refusedBeforeExport`) | The take's frames expired: `run({ video: { id } })`, then export. |
583
+ | `failed` | `status` (`expiry`) | Not a refusal: `expiry` is the last cleanup `{ ranAt, expired, freedBytes, skippedLeased }`. Say nothing unless it is `{ failed }` or `{ unreadable }`: quote it. |
584
584
  | `nothingToRerecord` | `run` (`refusedBeforeRun`) | The take has no step left that acts; tell the user. |
585
- | `unknownKit` | `run` (`refusedBeforeRun`) | `look.kit` names no brand kit, or one that cannot be read; `detail` lists the kits there are. Fix the name from `snapshot`'s `kits`, or ask the user. |
586
- | `kitsUnreadable` | `run` (`refusedBeforeRun`) | The brand kits file could not be read, so `look.kit` could not be checked; not a wrong name. Quote `detail` to the user; do not change the name. |
587
- | `invalidDevice` | `snapshot` | `device` names no phone or tablet Demoman has; `detail` lists the ones it does. Use one of them. |
588
- | `deviceFailed` | `snapshot`, `run` | The browser would not emulate the device, so nothing was listed or recorded; `detail` says which command and why. Not the script's: tell the user; do not run it again. |
585
+ | `unknownKit` | `run` (`refusedBeforeRun`) | `look.kit` names no brand kit, or one that cannot be read; `detail` lists the kits. Fix the name from `snapshot`'s `kits`, or ask the user. |
586
+ | `kitsUnreadable` | `run` (`refusedBeforeRun`) | The brand kits file could not be read, so `look.kit` was not checked. Quote `detail` to the user; do not change the name. |
587
+ | `invalidDevice` | `snapshot` | `device` names no phone or tablet Demoman has; `detail` lists those it has. Use one. |
588
+ | `deviceFailed` | `snapshot`, `run` | The browser would not emulate the device; nothing was listed or recorded; `detail` says why. Tell the user; do not run again. |
589
589
  | `nonHttpTarget` | `run`, `snapshot` | The target or url is not `http(s)`, or its host contains `*`. |
590
590
  | `invalidFileType` | `export` (`refusedBeforeExport`) | Not answered here: the schema takes only `mp4`, `gif`, `stills`. |
591
591
  | `invalidStillsOptions` | `export` (`refusedBeforeExport`) | `stills` was given for an MP4 or GIF, or holds a width outside 320-3840 (or `"native"`), a zoom other than `"none"` or `"step"`, or another field; `detail` says which. Fix the call. |
592
592
  | `invalidQuality`, `invalidMaxMB` | `export` (`refusedBeforeExport`), `attach` | Through these tools, only `quality` or `maxMB` given for a GIF or stills; the schema rejects a bad value first. |
593
593
  | `noTakeId`, `noFrames` | `export` (`refusedBeforeExport`) | No take id; the take has no frames to render. |
594
- | `takeNotFound`, `takeUnreadable` | `export` (`refusedBeforeExport`), `run` with `takeId` (`refusedBeforeRun`), `studio` (`takeNotFound`: call `takes`) | No such take; the take could not be read (or, for `run`, built into a script). |
594
+ | `takeNotFound`, `takeUnreadable` | `export` (`refusedBeforeExport`), `run` re-record (`refusedBeforeRun`), `studio` (`takeNotFound`: call `takes`) | No such take; it could not be read (or, for `run`, built into a script). |
595
595
  | `dragEndOutOfView`, `dragNoDistance` | `run` (`stopped.reason`) | A drag's end was off screen (a drag cannot scroll), or on its start. Fix the script. |
596
- | `clickNotDelivered` | `run` (`stopped.reason`) | The browser put a click elsewhere than where it was sent; `stopped.at` names the step and `stopped.detail` says where the click went. Not the script's fault: run again (it counts toward the three); tell the user if it repeats. |
597
- | `signedOut` | `run` (`stopped.reason`) | The app sent this browser to its sign-in page: no saved session signs this page in. Nothing was recorded or kept. Give the user the command in `stopped.detail`; run again only after they have run it. As an account there is no command to give: the detail says whether Demoman signed in again; repeat only if it says so. |
598
- | `windowClosed` | `run` (`stopped.reason`) | `--headed` only: Demoman's window was closed before the run finished; the script is fine. Ask the user to leave it open; run once more. During an export it answers `renderFailed`; export again. |
599
- | `pageDidNotLoad` | `snapshot` | The url did not load: the browser showed its own error page. Ask the user whether the app is running at that address; spend no run. |
600
- | `pageSilent` | `snapshot` | The page never answered, or took too long. Call once more, and if it answers this again, the page blocked Demoman's script; tell the user. |
601
- | `pageFaulted` | `snapshot` | The page's own code threw while Demoman walked it; quote `detail`. |
596
+ | `clickNotDelivered` | `run` (`stopped.reason`) | The browser put a click elsewhere than where it was sent; `stopped.detail` says where. Not the script's fault: run again (it counts); tell the user if it repeats. |
597
+ | `signedOut` | `run` (`stopped.reason`) | The app sent this browser to its sign-in page. Nothing was kept. Give the user the command in `stopped.detail`; run again only after they ran it. As an account there is no command: the detail says whether Demoman signed in again; repeat only if it says so. |
598
+ | `windowClosed` | `run` (`stopped.reason`) | `--headed` only: the window was closed mid-run; the script is fine. Ask the user to leave it open; run once more. In an export it answers `renderFailed`; export again. |
599
+ | `pageDidNotLoad` | `snapshot` | The url did not load. Ask the user whether the app is running at that address; spend no run. |
600
+ | `pageSilent` | `snapshot` | The page never answered. Call once more; if again, the page blocked Demoman's script; tell the user. |
601
+ | `pageFaulted` | `snapshot` | The page's own code threw; quote `detail`. |
602
602
  | `snapshotThrew` | `snapshot` | A fault in the snapshot; quote `detail`. |
@@ -11,11 +11,14 @@ this machine, then render the take to an MP4.
11
11
  1. Call the `recipe` tool and follow it. It is the whole procedure: the
12
12
  script format with examples, how to read each report, and what every
13
13
  refusal means. Do not write a script before reading it.
14
- 2. The browser is signed in only where the user ran `npx demoman signin <url>`
14
+ 2. Every run belongs to a video. Before recording, find it: `videos` with
15
+ `file` (an exported video the repo already has) or else `query`; then
16
+ `run` with `video: { id }`, or `video: { new: "<name>" }` for a new one.
17
+ 3. The browser is signed in only where the user ran `npx demoman signin <url>`
15
18
  or where a demo account in `.demoman/accounts.json` signs it in. On
16
19
  `signedOut`, follow the recipe's "Behind a login: demo accounts": reuse one,
17
20
  or create one on a local development database, else give the user the
18
21
  command from its detail. Only demo accounts; never ask for the user's own
19
22
  password.
20
- 3. When `export` answers `saved`, end on two lines: `summary` as it is, then
23
+ 4. When `export` answers `saved`, end on two lines: `summary` as it is, then
21
24
  its `links` as markdown links on one line, as the recipe's hand-back says.