versioncam 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,62 @@ and versions follow [semantic versioning](https://semver.org/). While the
 major version is 0, a minor version may change the config or the clip DSL,
 and its entry here says how.
 
+## 0.5.0 (2026-10-07)
+
+A minor version: commands for version.cam, and the skill learns to use them.
+Nothing records or renders differently, and the config and the clip DSL are
+as they were.
+
+### Added
+
+- **`versioncam cloud`** does from a terminal, or from an agent's shell, what
+  the dashboard at app.version.cam does. `cloud login` signs the command
+  line in with a code you approve in a browser, on any device, so it works
+  over SSH and in a sandbox. The token lasts seven days and is kept in
+  `~/.config/versioncam/credentials.json`, or under `$XDG_CONFIG_HOME`: a
+  file only you may read, with each API's sign-in apart, so staging and
+  production sit side by side. No command prints it, and `cloud logout`
+  revokes it. `VERSIONCAM_API` chooses the API from the shell alone: unlike
+  `publish`, the `cloud` commands never take it, or `XDG_CONFIG_HOME`, from
+  a `.env` file, and say so when one sets it, so a cloned repository cannot
+  send a sign-in to a server of its choosing.
+- Reading needs nothing more. `cloud status` says of each clip whether it is
+  current or broken, since when, who acknowledged it, and what your pages
+  play meanwhile, then the plan and where to manage the project; outside a
+  clone it lists every project you can see. `cloud failure <clip>` says
+  which step stopped a broken clip and why, and saves the page as it was to
+  `.versioncam/failures/<clip>.png`. `cloud ack <clip>` is the dashboard's
+  "I know, keep the old one". `cloud embed <clip>` prints the snippets that
+  embed a clip, and its files, and `cloud plan` the plan and the pages to
+  upgrade and pay on. Each read takes `--json`, and `--project owner/repo`
+  names a project when the repository's `origin` on GitHub is not the one.
+- **`cloud set`** changes a project's visibility, retention, "Tell viewers
+  when a clip is broken" or alerts, and only once you approve that one change
+  in the browser: it prints the change in a sentence, an address and a code,
+  and waits up to ten minutes. Paying, deleting a project and tokens for CI
+  outside GitHub stay on app.version.cam.
+- **The skill's `platform.md`**, which `versioncam init` installs beside the
+  other briefs: `/versioncam status`, `/versioncam fix [clip]` (why a clip
+  broke, a repair, and a pull request for it) and `/versioncam embed <clip>`,
+  and any question about the project on version.cam. It changes nothing you
+  did not ask for, leaves every approval to you, and never touches the
+  token. A skill already installed gets it from `versioncam init --force`,
+  which also overwrites any brief you edited.
+- The README's **`## version.cam`** section: connecting a repository, what
+  happens when a clip breaks on each plan, who can see the clips, the
+  `cloud` commands, and a repository whose CI runs elsewhere.
+
+### Changed
+
+- `publish --report` writes version.cam's whole answer, not only its
+  `project` and `versions`, so a field the service adds reaches the
+  Action's job summary without a release of this package to carry it:
+  where to manage the project, who can see its clips, whether its plan tells
+  anyone when a clip breaks, and what a broken clip's pages play.
+- `publish` calls a clip whose check failed on the default branch "broken",
+  not "stale", and says that a project token, `VERSIONCAM_TOKEN`, is for a
+  repository outside GitHub.
+
 ## 0.4.1 (2026-10-06)
 
 A patch version: nothing records or renders differently.

package/README.md

@@ -371,18 +371,18 @@ versioncam render [id…]            composite and encode recordings and scenes
 Send what the last run recorded to [version.cam](https://version.cam), which
 renders it and keeps it at a living address. `publish` records nothing and
 renders nothing: for each clip the config defines, it sends the recording if
-the clip's last run passed, or the failure if it did not, so a clip that
-broke says so on every page that embeds it. Only the states the service has
-not seen are uploaded, so a version that changed one screen sends one
-screen.
+the clip's last run passed, or the failure if it did not, so version.cam
+knows when a clip broke (see *When a clip breaks*). Only the states the
+service has not seen are uploaded, so a version that changed one screen
+sends one screen.
 
 It needs a credential in the environment, never on the command line:
 `VERSIONCAM_OIDC_TOKEN`, which the versioncam GitHub Action requests from
 GitHub for the run (no secret to store), or `VERSIONCAM_TOKEN`, a project
-token from version.cam for any other CI. `VERSIONCAM_API` points it
-somewhere other than `https://api.version.cam`. Outside GitHub Actions it
-reads the commit and branch from git; `VERSIONCAM_COMMIT` and
-`VERSIONCAM_BRANCH` set them outright.
+token from version.cam for a repository outside GitHub (see *Other CI*).
+`VERSIONCAM_API` points it somewhere other than `https://api.version.cam`.
+Outside GitHub Actions it reads the commit and branch from git;
+`VERSIONCAM_COMMIT` and `VERSIONCAM_BRANCH` set them outright.
 
 ```
 versioncam publish [id…]           send the recordings and their checks to version.cam
@@ -390,6 +390,31 @@ versioncam publish [id…]           send the recordings and their checks to ver
     --report <file>                and write the living URLs there, as JSON
 ```
 
+### Manage
+
+What version.cam knows about a project, and its settings, from the command
+line: what the dashboard shows and does, once you have signed in with a code
+you approve in a browser. A setting changes only when you approve that one
+change in the browser too. These need no `versioncam.config.ts`, and run
+anywhere in a clone of the repository. See *From the command line*.
+
+```
+versioncam cloud login             sign in to version.cam, with a code you approve in a browser
+    --label <name>                 what the approval page calls this machine
+versioncam cloud logout            sign out: revoke the token, and delete it
+versioncam cloud status [project]  each clip, current or broken, and what plays meanwhile
+versioncam cloud failure <clip>    why a clip broke, and its picture, into .versioncam/failures/
+versioncam cloud ack <clip>        "I know, keep the old one": the reminders stop
+versioncam cloud embed <clip>      the snippets that embed a clip, and its files
+versioncam cloud set <name> <val>  change a setting, once you approve it in a browser:
+                                   visibility public|unlisted|private, retention <days>|off,
+                                   viewers on|off, alerts email|slack <address>|off,
+                                   alerts issues on|off
+versioncam cloud plan [account]    the plan, and the pages to upgrade and pay on
+    --project <owner/repo>         which project, when not this repository's
+    --json                         machine-readable, for status, failure, embed and plan
+```
+
 ### From another directory
 
 In a monorepo the app is one directory among many. A command run from
@@ -409,6 +434,133 @@ versioncam <command> --cwd <dir>   as if run in <dir>, which holds versioncam.co
 versioncam --version               which versioncam this is
 ```
 
+## version.cam
+
+[version.cam](https://version.cam) renders what `versioncam publish` sends
+and keeps each clip at a living address,
+`clips.version.cam/<owner>/<repo>/<clip>`. It plays the newest version from
+your default branch that passed, so a page that embeds it never needs
+editing. Projects are managed on [app.version.cam](https://app.version.cam).
+
+### Connect a repository
+
+Sign in at [app.version.cam](https://app.version.cam) with GitHub, and
+install the Versioncam GitHub App on the repositories you choose. Then
+publish from GitHub Actions with the
+[versioncam Action](https://github.com/versioncam/action), which signs in
+with GitHub's own token, so there is no secret to store. A repository's
+project appears the first time it publishes, or when the App is installed
+on it.
+
+The App is how version.cam learns from GitHub, each time someone signs in,
+who may do what: whoever may read a repository sees its project, and
+whoever administers the repository changes the project's settings. The App
+also reports each publish on GitHub: a check on its commit, and on a pull
+request a comment naming the clips that look different and the ones that
+failed.
+
+### When a clip breaks
+
+A clip breaks when its check fails on the default branch: a control it uses
+was renamed or removed, a page moved, a step waited for something that never
+came, or the app would not start. A change in how the app looks never breaks
+a clip. It makes a new version.
+
+Your pages keep playing the last version that passed, and say nothing about
+the break. A project that wants its viewers told, open source docs perhaps,
+turns on "Tell viewers when a clip is broken" in its settings.
+
+On every plan, CI says so, and so does the dashboard: a pull request's check
+fails and the Action comments on it, the App's check on the commit says the
+clip is broken, and the summary of the job that publishes says what your
+pages play meanwhile.
+
+On Pro and Max, version.cam also tells your team, by email, in Slack or with
+a GitHub issue, as the project's settings choose. It reminds them two days
+after a clip broke and then every week, until the clip passes again or
+someone acknowledges it on the dashboard ("I know, keep the old one"). An
+acknowledged clip gets one more reminder a month later if it is still
+broken. When the clip passes again, the team is told it is fixed.
+
+### Who can see the clips
+
+| Visibility | Who can see the clips |
+|---|---|
+| public | Anyone, and search engines. |
+| unlisted | Anyone with the address, kept out of search. The address is made of names, so unlisted means not listed, not secret. |
+| private | Whoever GitHub lets read the repository, signed in at app.version.cam. |
+
+A private repository's clips start private, and a public repository's start
+public. A private clip plays only for the people who may see it, so never on
+a public page: to show a private repository's clips in public docs or on a
+landing page, make them public or unlisted in the project's settings.
+
+### From the command line
+
+`versioncam cloud` does what the dashboard does, from a terminal, and so
+from an agent working in one:
+
+```bash
+npx versioncam cloud login              # a code you approve in a browser, once a week
+npx versioncam cloud status             # this repository's clips: current or broken, and what plays
+npx versioncam cloud failure checkout   # where a broken clip stopped, and the page as it was
+```
+
+**Signing in.** `cloud login` prints an address and a code. Open the address
+on any device, sign in with GitHub, check that the page shows the same code,
+and approve it. Nothing calls back to the machine that runs the command, so
+it works over SSH and in a sandbox. The command line then holds a token that
+lasts seven days, in `~/.config/versioncam/credentials.json`, or under
+`$XDG_CONFIG_HOME` when that is set: a file only you may read, which no
+command prints. `cloud logout` revokes it. `VERSIONCAM_API`, set in the
+shell, points the commands at another version.cam, and each one's sign-in
+is kept apart. Unlike `publish`, they never take it, or `XDG_CONFIG_HOME`,
+from a `.env` file, so a repository you clone cannot send your sign-in to a
+server of its choosing, or have the token written inside it.
+
+**Reading** needs nothing more. `status` lists the clips: current or broken,
+since when, who acknowledged a broken one, and the version your pages play
+meanwhile; then the plan, and where to manage the project. `failure <clip>`
+says which step stopped a broken clip and why, and saves the page as it was
+then to `.versioncam/failures/<clip>.png`. `embed <clip>` prints the
+snippets that embed it, and `plan` says which plan, why and until when, and
+where to upgrade and pay. Each takes `--json`. They act on the repository
+they run in, from its `origin` remote on GitHub, or on the one that
+`--project owner/repo` names. `ack <clip>` is the dashboard's "I know, keep
+the old one".
+
+**A setting changes only once you approve it in the browser,** one change at
+a time. `cloud set visibility public` prints the change in a sentence, an
+address and a code, and waits up to ten minutes. The page shows exactly that
+change, so an agent running the commands for you cannot change a project
+without you seeing what it asked for. The settings are `visibility`,
+`retention`, `viewers` ("Tell viewers when a clip is broken") and `alerts`,
+by email, in Slack or with a GitHub issue.
+
+Three things stay a click on app.version.cam: paying (`cloud plan` prints
+the page), deleting a project, and making a project token for CI outside
+GitHub.
+
+The authoring skill runs these commands too: `/versioncam status`,
+`/versioncam fix [clip]` and `/versioncam embed <clip>`.
+
+### Other CI
+
+A repository on GitHub publishes from GitHub Actions, whatever builds it
+otherwise. GitHub's token says which repository, commit and branch a run is
+of, and version.cam takes them from it. A project token, `VERSIONCAM_TOKEN`,
+would have to say all that itself, with nothing to check it against, so it
+speaks only for a project with no GitHub repository.
+
+So when your CI runs elsewhere, run just the clips in GitHub Actions: a
+workflow beside the CI you have, with the versioncam Action checking the
+clips on pull requests and publishing them from your default branch. The
+[Action's README](https://github.com/versioncam/action) has one to copy.
+
+A repository outside GitHub publishes with a project token, given to
+`versioncam publish` as `VERSIONCAM_TOKEN` and made on the project's page at
+app.version.cam. Its project is set up by hand: write to hello@version.cam.
+
 ## What a recording leaves behind
 
 `versioncam record` writes each clip to `.versioncam/recordings/<id>/`.

package/dist/cli/commands/cloud.d.ts

@@ -0,0 +1,59 @@
+import type { ChangeRequest } from "../../cloud/protocol.js";
+import { type Clock } from "../../cloud/wait.js";
+/**
+ * `versioncam cloud`: what the dashboard at app.version.cam does, from a
+ * terminal, and so from an agent's shell.
+ *
+ * `versioncam login` was already taken, by the command that saves the app's
+ * own browser session for recording, so the platform's commands live under
+ * a name of their own.
+ *
+ * A person signs in once, with a code they approve in a browser, and the
+ * commands then read for them: a project's clips and whether each is
+ * broken, why one broke, how to embed one, the plan. Acknowledging a broken
+ * clip needs no more than that, as on the dashboard. Every setting change
+ * prints a code and waits for the person to approve that one change in the
+ * browser, because whoever runs these commands may be an agent, and what an
+ * agent reads here (clip titles, failure messages) was written by whoever
+ * published. Nothing it is told can change a project without a person seeing
+ * the change.
+ *
+ * The token never reaches the output, whatever the service says: every line
+ * written passes through a filter that knows it.
+ *
+ * And the commands run in the environment the shell gave, never with what
+ * the repository's `.env.recording` or `.env` added, which the CLI loads
+ * before every command. Those files come with whatever was cloned: one that
+ * set VERSIONCAM_API could send a sign-in, and every command holding a
+ * token, to a server of the repository's choosing, and one that set
+ * XDG_CONFIG_HOME could have the token written into the repository itself.
+ * `publish` still reads the files: CI sets its environment itself.
+ */
+/** A variable a file set that these commands read only from the shell. */
+export type Ignored = {
+    name: string;
+    file: string;
+    value: string;
+};
+/** What a cloud command needs from the world, so a test can hand it another one. */
+export type CloudIo = {
+    /** The shell's environment, never a repository file's. */
+    env: NodeJS.ProcessEnv;
+    /** What a file tried to set, said once so that nobody wonders why it did nothing. */
+    ignored?: Ignored[];
+    /** The directory the command runs in: its repository, and its `.versioncam/`. */
+    cwd: string;
+    out(text: string): void;
+    err(text: string): void;
+    fetch: typeof fetch;
+    clock: Clock;
+    hostname(): string;
+    /** The zone dates are written in: the machine's own, unless a test pins one. */
+    timeZone?: string;
+};
+/** The environment a cloud command runs in, and what the files tried to add to it. */
+export declare function shellEnvironment(): Pick<CloudIo, "env" | "ignored">;
+export declare function cloud(argv: string[]): Promise<number>;
+export declare function runCloud(argv: string[], io: CloudIo): Promise<number>;
+/** The setting and value as the API takes them, or why not. */
+export declare function changeRequest(args: string[]): ChangeRequest | string;