Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 43 additions & 2 deletions apps/cli/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -246,6 +246,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 |
Expand Down Expand Up @@ -384,20 +385,60 @@ 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
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

Expand Down
1 change: 1 addition & 0 deletions apps/cli/scripts/smoke.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ const TOOLS = [
'generate_demo',
'get_task',
'list_demos',
'share_demo',
'validate_scenario',
];
const browsers = process.argv.includes('--browsers');
Expand Down
10 changes: 7 additions & 3 deletions apps/cli/src/auth/client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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)) {
Expand Down Expand Up @@ -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);
}
13 changes: 12 additions & 1 deletion apps/cli/src/commands/errors.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
65 changes: 30 additions & 35 deletions apps/cli/src/commands/render.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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');
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -174,24 +187,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
Expand Down
22 changes: 21 additions & 1 deletion apps/cli/src/commands/scenario-file.ts
Original file line number Diff line number Diff line change
@@ -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,
Expand Down Expand Up @@ -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;
}
}
Loading
Loading