@junoflow/cli 0.6.0 → 0.10.0

package/README.md

@@ -66,7 +66,8 @@ Every command has one effect:
   starts a run, executes code), with nothing to roll back to.
 
 `config set` and `agent-skill install` are **local**: they write a file on your
-machine and change nothing on the instance.
+machine and change nothing on the instance. So is `app dev`, which serves an app
+working copy on localhost and never connects to an instance.
 
 No command of a lower effect is a string prefix of a command of a higher one.
 Claude Code matches a Bash permission rule by prefix, so an allowlist can list
@@ -204,10 +205,11 @@ under `files` by its basename and makes it the `entry`.
 
 **`session`** and **`config`**
 
-| Command                     | Tool | Positional  | Effect |
-| --------------------------- | ---- | ----------- | ------ |
-| `juno session approve <id>` | none | session id  | act    |
-| `juno config set url <url>` | none | `url <url>` | local  |
+| Command                       | Tool | Positional    | Effect |
+| ----------------------------- | ---- | ------------- | ------ |
+| `juno session approve <id>`   | none | session id    | act    |
+| `juno config set url <url>`   | none | `url <url>`   | local  |
+| `juno config set token <key>` | none | `token <key>` | local  |
 
 There is no command that calls a tool by name. One permission rule for such a
 command would allow every act, so each tool has its own command instead, and a
@@ -256,15 +258,15 @@ its own. A missing `jq` or an expression `jq` rejects exits 2.
 
 One table for the whole CLI, the working-copy commands included:
 
-| Code | When                                                                                                  |
-| ---- | ----------------------------------------------------------------------------------------------------- |
-| 0    | Success                                                                                               |
-| 1    | A tool answer with a top-level string `error`, a failed check or deploy, or any other failure         |
-| 2    | Usage: an unknown command or flag, bad `--input`, input the instance rejects, a bad `--jq`            |
-| 3    | The instance is unreachable                                                                           |
-| 4    | `juno flow deploy` / `flow check`: the flow changed on the instance since the working copy was pulled |
-| 5    | `juno ask` / `session approve`: the turn is still running                                             |
-| 6    | `juno ask` / `session approve`: the assistant is waiting for an answer or an approval                 |
+| Code | When                                                                                                 |
+| ---- | ---------------------------------------------------------------------------------------------------- |
+| 0    | Success                                                                                              |
+| 1    | A tool answer with a top-level string `error`, a failed check or deploy, or any other failure        |
+| 2    | Usage: an unknown command or flag, bad `--input`, input the instance rejects, a bad `--jq`           |
+| 3    | The instance is unreachable                                                                          |
+| 4    | A working-copy `deploy` or `check`, any kind: the instance changed since the working copy was pulled |
+| 5    | `juno ask` / `session approve`: the turn is still running                                            |
+| 6    | `juno ask` / `session approve`: the assistant is waiting for an answer or an approval                |
 
 An instance that does not serve a tool the CLI names is older than the CLI; that
 is also exit 2, and the message says so.
@@ -394,10 +396,26 @@ with no setup. `juno config set url <url>` writes the fourth, which is what
 makes `juno` useful outside a project. A bare host such as `juno.local:8080`
 means `http://juno.local:8080`.
 
+## Authenticating
+
+A Juno that identifies its callers answers a request with no credential
+with 401. Create an API key under **Settings → API keys** and give it to the
+CLI; it is sent as `Authorization: Bearer <key>` on every request. In order:
+
+1. `--token <key>`, before or after the command words;
+2. `$JUNO_TOKEN`;
+3. `token` in the user config file, which `juno config set token <key>` writes
+   (mode 0600; the key must start `juno_`).
+
+There is no `package.json` source: a working copy's `package.json` is committed,
+and a key never goes in a file that is. The CLI never prints the key, in an
+error message included.
+
 Every request carries an `X-Juno-Client` header: `cli`, or `cli/claude-code`
-when `CLAUDECODE=1` is set, as Claude Code sets it in the shells it starts. Juno
-records a write made through a tool as `operator:<client>`. The header names who
-made a change; it is not a security control.
+when `CLAUDECODE=1` is set, as Claude Code sets it in the shells it starts. The
+header labels the calling client; Juno records a write made through a tool under
+the principal the request authenticated as, and the header is not a security
+control.
 
 ## Working copies
 
@@ -407,30 +425,42 @@ truth and a working copy is where you edit the next version. Its `package.json`
 names the instance (`juno.target`) and the flow or install it belongs to, so a
 fresh clone deploys with no setup.
 
-Both kinds have the same loop and the same npm scripts:
+Both kinds have the same loop and the same npm scripts, and so does an app
+(`juno app init`), whose `check` stores a draft to preview at its `~draft/` URL:
 
 ```bash
 npm install
-npm test               # local tsc and eslint
+npm test               # local tsc, eslint and vitest
 npm run check          # ... then verify against the instance, which writes nothing
 npm run deploy         # verify, commit and activate the next version
-npm run pull           # overwrite the working copy with the active version
+npm run pull           # bring the working copy up to the active version
 ```
 
-| Script         | Flow working copy                   | Integration working copy                                                  |
-| -------------- | ----------------------------------- | ------------------------------------------------------------------------- |
-| `typecheck`    | `tsc --noEmit`                      | `tsc --noEmit`                                                            |
-| `lint`         | `eslint .`                          | `eslint .`                                                                |
-| `verify-types` | (absent)                            | `juno integration verify-types`                                           |
-| `test`         | `npm run typecheck && npm run lint` | `npm run verify-types && npm run typecheck && npm run lint && vitest run` |
-| `types`        | `juno flow gen-types`               | `juno integration gen-types`                                              |
-| `check`        | `juno flow check`                   | `juno integration check`                                                  |
-| `deploy`       | `juno flow deploy`                  | `juno integration deploy`                                                 |
-| `watch`        | `juno flow deploy --watch`          | `juno integration deploy --watch`                                         |
-| `pull`         | `juno flow pull`                    | `juno integration pull`                                                   |
-
-The instance writes these lines, and `pull` rewrites them, so a working copy
-picks up a new command without your editing `package.json`.
+| Script         | Flow working copy                                 | Integration working copy                                                  | App working copy                                  |
+| -------------- | ------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
+| `typecheck`    | `tsc --noEmit`                                    | `tsc --noEmit`                                                            | `tsc --noEmit && tsc --noEmit -p page`            |
+| `lint`         | `eslint .`                                        | `eslint .`                                                                | `eslint .`                                        |
+| `verify-types` | (absent)                                          | `juno integration verify-types`                                           | (absent)                                          |
+| `test`         | `npm run typecheck && npm run lint && vitest run` | `npm run verify-types && npm run typecheck && npm run lint && vitest run` | `npm run typecheck && npm run lint && vitest run` |
+| `types`        | `juno flow gen-types`                             | `juno integration gen-types`                                              | `juno app gen-types`                              |
+| `check`        | `juno flow check`                                 | `juno integration check`                                                  | `juno app check`                                  |
+| `deploy`       | `juno flow deploy`                                | `juno integration deploy`                                                 | `juno app deploy`                                 |
+| `watch`        | `juno flow deploy --watch`                        | `juno integration deploy --watch`                                         | `juno app deploy --watch`                         |
+| `pull`         | `juno flow pull`                                  | `juno integration pull`                                                   | `juno app pull`                                   |
+| `dev`          | (absent)                                          | (absent)                                                                  | `juno app dev`                                    |
+
+`dev` exists only in an app working copy, because flows and integrations have no
+page to serve. `npm run dev` serves the app on `http://localhost:8090/`
+(`--port <n>` picks another) with no instance, no credentials and no network:
+the page is built from `page/` on each request, the handlers run in Node through
+the testkit's `appHarness`, and live values come from a scenario file
+(`--scenario test/fixtures/<name>.json`). A panel beside the page sets values,
+presses controls and switches scenarios, and saving a file rebuilds and reloads.
+It uses the `esbuild` and `@junoflow/testkit` the working copy installs.
+
+`init` writes these lines as the instance renders them. After that they are
+yours: `pull` never changes `scripts`. To see the current lines, run `init` into
+a fresh directory and compare.
 
 The working-copy commands sit in the `flow` and `integration` groups beside the
 commands that act on the instance, and `juno flow --help` and
@@ -439,27 +469,61 @@ commands that act on the instance, and `juno flow --help` and
 argument: `juno flow deploy porch-light` exits 2 and tells you to run
 `juno flow init porch-light` and deploy from inside it.
 
-| Effect   | Commands                                                       |
-| -------- | -------------------------------------------------------------- |
-| `read`   | `init`, `gen-types`, `verify-types`, `check`, `pull`           |
-| `change` | `deploy`: it adds a version to the flow's or install's history |
+| Effect   | Commands                                                             |
+| -------- | -------------------------------------------------------------------- |
+| `read`   | `init`, `gen-types`, `verify-types`, `check`, `pull`, `flow fixture` |
+| `change` | `deploy`: it adds a version to the flow's or install's history       |
+| `local`  | `app dev`: a server on localhost that touches no instance            |
 
-`init` and `pull` write local files, but change nothing in Juno, so their effect
-is `read`.
+`init`, `pull` and `flow fixture` write local files, but change nothing in Juno,
+so their effect is `read`.
 
 After writing a working copy, `init` prints the skills for writing that kind,
 one `<name> — <description>` line each, the same index Juno's in-app flow or
 integration author is given; load one with `juno skill <name>`.
-`juno flow --help` and `juno integration --help` list them too. `pull` refuses
-to overwrite uncommitted changes in a git working tree unless you pass
-`--force`.
+`juno flow --help` and `juno integration --help` list them too.
+
+### What Juno stores, and what `pull` writes
+
+A working copy holds three kinds of file:
+
+| Kind      | Files                                                                                             | Stored by Juno                         |
+| --------- | ------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| artifact  | `manifest.json`, `src/**`, `test/**`                                                              | yes, with every version, byte for byte |
+| generated | `types/**`                                                                                        | no; generated from the manifest        |
+| project   | everything else: `tsconfig.json`, `eslint.config.js`, `README.md`, `.gitignore`, `package.json` … | no                                     |
+
+`check` and `deploy` send the artifact files. Your tests travel with the
+version, so a copy pulled elsewhere gets them back. Juno stores `test/**` and
+nothing more: it never type-checks, lints or runs a test. `npm test` runs them
+in your checkout.
+
+`pull` makes the artifact files the active version's, exactly as Juno stores
+them, and regenerates `types/`. It deletes a local file only when Juno deleted
+it: the version recorded in `juno.base_version` had the file and the pulled
+version does not. A file neither version has is one you have not deployed yet,
+and `pull` leaves it alone. A working copy with no `base_version` has nothing to
+compare against, so `pull` deletes nothing. It prints what it wrote and, on a
+second line, what it removed:
+
+```text
+pulled porch-light v7 from http://juno.local:8080 (manifest.json, package.json, src/flow.ts)
+removed src/old.ts
+```
+
+`pull` never writes or deletes a project file. In `package.json` it sets two
+keys, `juno.base_version` and `dependencies` (from the manifest), and leaves the
+rest as you wrote it. An integration whose manifest declares no dependencies
+keeps them in `package.json` alone, so there `pull` leaves `dependencies` as it
+is. It refuses to overwrite uncommitted changes in a git working tree unless you
+pass `--force`.
 
 ## Flows as files
 
 ```bash
 juno flow init porch-light          # the flow's active version, or a stub for a new id
 cd porch-light && npm install
-$EDITOR flow.ts manifest.json
+$EDITOR src/flow.ts manifest.json
 npm test
 npm run check
 npm run deploy
@@ -468,33 +532,77 @@ npm run deploy
 `juno flow init <id>` writes `./<id>` (or the current directory, with `--here`).
 For a flow that has an active version, it is that version. For a new id it is a
 stub whose only trigger is a `call` trigger, so a stub deployed by accident
-never fires on its own. A working copy is flat:
-
-| File               | What it is                                                                         |
-| ------------------ | ---------------------------------------------------------------------------------- |
-| `manifest.json`    | the flow's manifest                                                                |
-| `flow.ts`          | the flow's source                                                                  |
-| `flow-env.d.ts`    | types generated from the manifest and the instance's states, integrations, etc.    |
-| `flow-api.d.ts`    | the SDK's declarations; it and `flow-env.d.ts` only typecheck together             |
-| `tsconfig.json`    | extends `@junoflow/cli/tsconfig.base.json`                                         |
-| `eslint.config.js` | `@junoflow/cli/eslint.flow.config.js`: the rules Juno's verify step lints flows by |
-| `package.json`     | the scripts, the dependencies, and `juno.target` / `flow_id` / `base_version`      |
-| `.gitignore`       | `node_modules/`                                                                    |
+never fires on its own. When the version stores no `test/**`, `init` also writes
+a starter `test/flow.test.ts`: a conformance test against `@junoflow/testkit`'s
+`flowHarness`, and one `it.todo` per trigger. A working copy has the same shape
+as an integration's:
+
+| File                  | What it is                                                                                 |
+| --------------------- | ------------------------------------------------------------------------------------------ |
+| `manifest.json`       | the flow's manifest                                                                        |
+| `src/flow.ts`         | the flow's entry                                                                           |
+| `src/**`              | any other `.ts` or `.json` module the entry imports                                        |
+| `test/**`             | your tests and their `.ts` or `.json` fixtures; stored with the flow, never compiled       |
+| `types/flow-env.d.ts` | the module the source imports its types from, generated from the manifest and the instance |
+| `types/flow-api.d.ts` | the SDK's generic declarations, which `flow-env.d.ts` fills in; never import it directly   |
+| `tsconfig.json`       | extends `@junoflow/cli/tsconfig.base.json`                                                 |
+| `eslint.config.js`    | `@junoflow/cli/eslint.flow.config.js`: the rules Juno's verify step lints flows by         |
+| `package.json`        | the scripts, the dependencies, and `juno.target` / `flow_id` / `base_version`              |
+| `.gitignore`          | `node_modules/`                                                                            |
+
+Every source file imports its types from the generated module:
+
+```ts
+// src/flow.ts
+import type { Flow } from '../types/flow-env';
+import { describe } from './describe';
+
+export default {
+  triggers: {
+    onCall: async ({ status }) => status.ok(describe()),
+  },
+} satisfies Flow;
+```
+
+`src/` and `test/` hold `.ts` and `.json` files only, at most 64 of them
+together, each at most 512 KiB. Every one is sent on `check` and `deploy`. The
+files under `src/` are type-checked and linted, and only `src/flow.ts` must
+contain `satisfies Flow`. The files under `test/` are stored as they are; the
+flow's `eslint.config.js` skips them too. `types/` is generated and is never
+sent.
 
 | Command                                         | What it does                                                                           |
 | ----------------------------------------------- | -------------------------------------------------------------------------------------- |
 | `juno flow init <id> [--here]`                  | write a working copy from the instance                                                 |
-| `juno flow gen-types`                           | regenerate `flow-env.d.ts` and `flow-api.d.ts` from `manifest.json`                    |
+| `juno flow gen-types`                           | regenerate `types/flow-env.d.ts` and `types/flow-api.d.ts` from `manifest.json`        |
 | `juno flow check [--skip-local] [--json]`       | local `tsc --noEmit` and `eslint .`, then verify against the instance, writing nothing |
 | `juno flow deploy [--watch] [--force] [--json]` | verify, commit and activate; write back the manifest, the types and `base_version`     |
-| `juno flow pull [--force]`                      | overwrite the working copy with the active version                                     |
+| `juno flow pull [--force]`                      | bring the working copy up to the active version                                        |
+| `juno flow fixture --run <seq> [--force]`       | write run `seq` as a test fixture, `test/fixtures/<flow-id>-<seq>.json`                |
+
+`pull` writes `manifest.json`, `src/**`, `test/**` and both `types/` files, and
+deletes what the flow deleted (see
+[What Juno stores](#what-juno-stores-and-what-pull-writes)).
 
 `deploy` writes back what Juno stored: the canonical `manifest.json`, freshly
-generated types, and the new version number. `--watch` redeploys whenever
-`flow.ts` or `manifest.json` is saved, skips a save that changed nothing, and
-keeps watching after a failure. `--json` on `check` and `deploy` prints the
-instance's JSON answer (or, when verification fails, its diagnostics) on stdout
-instead, for CI; the integration commands take it too.
+generated types, and the new version number. `--watch` redeploys whenever a file
+under `src/` or `manifest.json` is saved (a deploy sends `test/` too, but saving
+a test does not start one), skips a save that changed nothing, and keeps
+watching after a failure. `--json` on `check` and `deploy` prints the instance's
+JSON answer (or, when verification fails, its diagnostics) on stdout instead,
+for CI; the integration commands take it too.
+
+`fixture` turns a recorded run into a scenario a test loads with
+`h.scenario(fixture)` from `@junoflow/testkit`: the event the run received, the
+world it saw as far as Juno recorded it, and, under `expect`, the status, steps
+and target calls it produced. It writes the file the instance builds, prints
+`wrote test/fixtures/porch-light-42.json`, and lists on stderr each thing the
+run did not record, such as a state value reconstructed from history or a
+credential to fill in. It refuses to overwrite an existing fixture without
+`--force` (exit 1), warns when the run ran another version than
+`juno.base_version`, and exits 1 with the instance's reason for a run it cannot
+replay: one still going, one that slept or waited for an event, or one that was
+cancelled.
 
 ### The flow id and `base_version`
 
@@ -522,11 +630,11 @@ differ, naming the packages.
 
 ### Why there is no `flow verify-types`
 
-`flow-env.d.ts` describes the instance as well as the manifest: the states the
-flow binds, the integrations and controls it calls. It goes stale whenever the
-instance changes, and Juno regenerates it on every check and deploy, so stale
-local types never ship. `npm run types` refreshes your copy when the editor
-disagrees with the instance.
+`types/flow-env.d.ts` describes the instance as well as the manifest: the states
+the flow binds, the integrations and controls it calls. It goes stale whenever
+the instance changes, and Juno regenerates it on every check and deploy, so
+stale local types never ship. `npm run types` refreshes your copy when the
+editor disagrees with the instance.
 
 ## Developing integrations
 
@@ -541,31 +649,57 @@ juno integration init my-integration --url http://juno.local:8080
 
 ### Commands
 
-| Command                                                      | What it does                                                                   |
-| ------------------------------------------------------------ | ------------------------------------------------------------------------------ |
-| `juno integration init <id> [--name <name>] [--here]`        | write the install's project from a Juno, or a starter for a new id             |
-| `juno integration gen-types`                                 | POST `manifest.json`, write `types/`                                           |
-| `juno integration verify-types`                              | check `types/` still matches `manifest.json`; talks to nothing                 |
-| `juno integration check [--skip-local] [--id <id>] [--json]` | local `verify-types` + `tsc --noEmit` + `eslint`, then validate against a Juno |
-| `juno integration deploy [--watch] [--id <id>] [--json]`     | upload, verify, activate, and write back the returned types                    |
-| `juno integration pull [--force] [--id <id>]`                | write back the manifest, sources and `package.json` scripts the instance holds |
+| Command                                                            | What it does                                                                   |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| `juno integration init <id> [--name <name>] [--here]`              | write the install's project from a Juno, or a starter for a new id             |
+| `juno integration gen-types`                                       | POST `manifest.json`, write `types/`                                           |
+| `juno integration verify-types`                                    | check `types/` still matches `manifest.json`; talks to nothing                 |
+| `juno integration check [--skip-local] [--id <id>] [--json]`       | local `verify-types` + `tsc --noEmit` + `eslint`, then validate against a Juno |
+| `juno integration deploy [--watch] [--force] [--id <id>] [--json]` | upload, verify, activate, and write back the returned types and `base_version` |
+| `juno integration pull [--force] [--id <id>]`                      | write back the manifest, `src/`, `test/`, `types/` and `base_version`          |
 
 They exit as the [exit-code table](#exit-codes) says: 1 for a failed check or
-deploy, 2 for a usage error, 3 when the instance is unreachable.
+deploy, 2 for a usage error, 3 when the instance is unreachable, 4 for a stale
+working copy (see [`base_version`](#base_version)).
 
 ### Options
 
 | Flag            | Meaning                                                                                                     |
 | --------------- | ----------------------------------------------------------------------------------------------------------- |
 | `--url <url>`   | the instance to talk to                                                                                     |
+| `--token <key>` | the API key to send (see [Authenticating](#authenticating))                                                 |
 | `--id <id>`     | address an install under a different id than the manifest declares (`check`, `deploy`, `pull`)              |
 | `--name <name>` | display name for a new integration (`init`)                                                                 |
 | `--watch`       | redeploy on every save (`deploy`)                                                                           |
-| `--force`       | overwrite a dirty working tree (`pull`)                                                                     |
+| `--force`       | overwrite a dirty working tree (`pull`); replace the active version whatever the base (`deploy`)            |
 | `--here`        | scaffold into the current directory (`init`)                                                                |
 | `--skip-local`  | skip the local verify-types/tsc/eslint pass (`check`)                                                       |
 | `--json`        | print the instance's JSON answer (or the failed verify's diagnostics) on stdout, for CI (`check`, `deploy`) |
 
+### `base_version`
+
+`package.json`'s `juno.base_version` is the version the working copy was pulled
+from or last deployed. `init` of an installed id, the **Download project** zip,
+`pull` and every successful `deploy` write it. `deploy` and `check` send it, and
+when the install's active version is anything else (someone deployed another
+copy, asked the assistant to change the integration, or rolled it back), Juno
+refuses and the CLI exits **4**:
+
+```text
+integration "pushover": active version is v4, but this working copy was pulled from v3 — pull it again, or deploy with --force to replace it
+```
+
+Run `npm run pull` to start from the active version, or
+`juno integration deploy --force` to replace it. A working copy without a
+`base_version` sends none; its first deploy or pull records one.
+
+The base belongs to the install `manifest.json` names. `--id <other>` deploys
+the same code to a different install, whose versions this copy has never seen,
+so it sends no base, writes none back, and warns
+`no stale-base check: deploying to <other>, not <manifest id>`. It needs no
+`--force`. `pull --id <other>` rewrites `manifest.json` to that install, so
+later deploys are checked against it.
+
 ### The loop
 
 ```bash
@@ -629,5 +763,5 @@ of an id that is already installed writes that install's project, the one the
 **Develop locally → Download project** button gives you; `init` of a new id
 writes a starter. Neither is a local template: the CLI writes the files it is
 handed, so a scaffold cannot drift from what the server ejects. To refresh an
-existing checkout use `juno integration pull`, which also rewrites
-`package.json`'s `scripts`; a second download would clobber your working tree.
+existing checkout use `juno integration pull`, which touches only the files Juno
+stores; a second download would clobber your working tree.