diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..7fa036a --- /dev/null +++ b/.prettierignore @@ -0,0 +1 @@ +test/fixtures/failure-report-shapes.json diff --git a/README.md b/README.md index 53c4835..4863be6 100644 --- a/README.md +++ b/README.md @@ -97,7 +97,10 @@ The published package: - installs the firstdraft executable; - runs reviewed JavaScript source directly; - has no runtime dependencies or install scripts; -- performs no telemetry, update check, or network request unless the caller invokes an API command; +- sends nothing in the background or beyond the command the caller runs. [What the CLI sends](docs/commands.md#what-the-cli-sends) + lists each command's requests and their `FirstDraft-Client` header: CLI and plugin versions, agent, and operating + system. `report` prints its exact report and `conversation send` the file's path, size, and digest before sending; +- makes no update check of its own: its update line comes from First Draft's answer to the command; - reads Bearer credentials from the environment or its private `firstdraft login` credentials file; and - carries npm provenance linking registry bytes to its GitHub workflow and commit. diff --git a/docs/commands.md b/docs/commands.md index 46b8683..d6564d3 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -5,9 +5,10 @@ group's `--help` for concise executable syntax. See [Errors and recovery](errors The current `0.9.x` source line contains the auditable command shell, browser and device login, local Foundation Plan initialization, local application-key and UUID generation, conditional whole-document push, whole-graph analysis status polling, direct -Compile-and-materialize and private publish orchestration, and retained-Compilation inspection and cancellation. -CLI `0.9.x` requires the service's `0.8.x` API contract. The -[changelog](https://github.com/firstdraft/cli/blob/main/CHANGELOG.md) describes each version. +Compile-and-materialize and private publish orchestration, retained-Compilation inspection and cancellation, the +account's report setting, progress and failure reports, and conversation upload. This development version requires +the service's `0.9.x` API contract; the release that carries it names its own version in the changelog. The [changelog](https://github.com/firstdraft/cli/blob/main/CHANGELOG.md) describes +each version. [What the CLI sends](#what-the-cli-sends) lists every request and what it carries. ## Command map @@ -25,6 +26,10 @@ CLI `0.9.x` requires the service's `0.8.x` API contract. The | `firstdraft compilation status` | Yes | Inspect a retained Compilation by ID | | `firstdraft compilation download` | Yes | Verify and materialize a successful retained Compilation | | `firstdraft compilation cancel` | Yes | Cancel a queued or running Compilation by ID | +| `firstdraft account` | Yes | Show whether the account sends reports | +| `firstdraft report progress` | Yes | Print, then send, how far a generated application has come | +| `firstdraft report failure` | Yes | Print, then send, an unexpected failure in generated code | +| `firstdraft conversation send` | Yes | Print, then send, one conversation the person agreed to | ## Select an environment and authenticate @@ -65,10 +70,13 @@ The CLI prints a verification URL, a short user code, and a URL that already inc any device, confirm the code, and approve. The CLI polls at the server's interval, adds five seconds when asked to slow down, and stops when the code expires. -Both flows send this machine's hostname as the device name shown on the approval page and in the token's name on -`/api-tokens`. A denied approval exits with `authorization_denied`. A login that is not approved in time exits with -`authorization_expired`. Other failures exit with `login_failed`. No credential is saved unless the login succeeds. -See [Errors and recovery](errors.md#login-and-logout-errors). +Neither flow sends this computer's hostname. Their requests carry `FirstDraft-Client` like every other request +([What the CLI sends](#what-the-cli-sends)). A denied approval exits with `authorization_denied`. A login that is not approved in time exits with +`authorization_expired`. A First Draft limit ends it with `rate_limited`. A required update or an unsupported API +contract replaces its result with `update_required` or `api_contract_unsupported` only when it stops a request the +login still had to send, as [update line and refusals](#update-line-and-refusals) describes. Other failures exit with +`login_failed`. No credential is saved unless the login succeeds. See +[Errors and recovery](errors.md#login-and-logout-errors). ### Saved credentials @@ -131,6 +139,63 @@ print it, or require it for local commands. Revoke a token in the environment th missing token, or First Draft's validated `401` problem response with the `authentication_required` code, produces that stable CLI error. +## What the CLI sends + +The CLI sends nothing on its own: no telemetry, no background request, and no separate update check. A command sends +only its own requests, listed under [Service endpoints](#service-endpoints); `plan init`, `generate`, and `--help` +make none. Each request carries the selected token (except the OAuth requests of `login` and `logout`) and this +header: + +```text +FirstDraft-Client: cli/; plugin/; agent/; os/ +``` + +`cli` is this package's version. `plugin` and `agent` come from `FIRSTDRAFT_PLUGIN_VERSION` and `FIRSTDRAFT_AGENT`, +which the First Draft plugin's launcher sets to its own version and to the agent's name, such as `claude-code` or +`codex`. `os` is Node.js's `process.platform`, such as `darwin`, `linux`, or `win32`. A part that is unset, or is not a +plain version or name, is left out. The header carries no hostname, user name, path, or token. A setup that runs the +CLI without the plugin's launcher, such as a direct npm installation, may set the two variables itself. + +Beyond the header, a command sends only what it needs: + +| Commands | Request content | +| ----------------------------------------- | ------------------------------------------------------------------ | +| `login`, `logout` | OAuth parameters; `logout` sends the saved token to revoke it | +| `plan push`, `plan compile` | The exact local Plan bytes and the saved Head ETag | +| `plan status`, `compilation *`, `account` | Only the IDs in the request path | +| `report progress`, `report failure` | The report that the command prints just before sending it | +| `conversation send` | The file the person agreed to send, unchanged, under its base name | + +### Update line and refusals + +First Draft answers each routed `/v1` request with `FirstDraft-API-Contract` and two pairs of versions: +`FirstDraft-Latest-Plugin` and `FirstDraft-Minimum-Plugin` for the plugin, and `FirstDraft-Latest-CLI` and +`FirstDraft-Minimum-CLI` for this package, which is numbered separately. The CLI checks every response it receives; +an OAuth answer or a missing route may carry none of them, so it then checks nothing. With +`FIRSTDRAFT_PLUGIN_VERSION` set, the CLI compares that plugin version with the plugin pair. Without it, it compares +its own version with the CLI pair. A pair is compared only when both of its versions are readable, so a Service that +sends no CLI pair, or half of one, produces no line and no refusal. A `FIRSTDRAFT_PLUGIN_VERSION` that is set but is +not a version, even blank, compares neither pair; the command's one line then says the CLI could not tell whether the +setup is current. The update +notice therefore comes from First Draft's answer to the command being run, not from a request of its own. + +- **Older than the latest:** the CLI writes one line on standard error, once per command and just before the + command's own result, whether or not a terminal is attached, so an agent sees it and can pass it on: + `First Draft: an update is available (plugin ; this setup has plugin ). Tell the person the update steps are at https://firstdraft.com/update`. + Without a plugin version the line names `CLI ` and `CLI `. +- **Older than the minimum, or a contract other than API `0.9.x`:** the CLI finishes handling that response, so + local state stays in step with First Draft, and sends nothing more. When the command still had a request to send, + it exits with `update_required` or `api_contract_unsupported` instead of its own result. When that response was the + command's last, the command reports its own result, after one `First Draft: ` line on standard error that names + the stop and says the command finished. For an older contract, or a prerelease of a release inside the accepted range, it says to use the CLI that origin supports instead of updating; a prerelease of a newer release counts as newer. Either replaces the update line above. +- **A `429` answer**, which First Draft sends when a limit is reached, such as an account's Compilations for the day + or its reports for the hour, usually with `Retry-After`: the request did nothing, and whatever else the response + says, the command exits with `rate_limited` and the time to try again. + +A header value that is not a version is ignored, and a prerelease contract counts as outside the range. `logout` +always finishes removing the local token, so neither the stop line nor a refusal replaces its result. +[Errors and recovery](errors.md#update-and-limit-errors) explains each error. + ## Start a Foundation Plan From the project that the Plan describes: @@ -139,7 +204,7 @@ From the project that the Plan describes: firstdraft plan init --name "Oscar Party" ``` -This creates an empty `firstdraft.foundation-plan.sketch/0.23` Plan targeting `rails-sketch/2026-10` and a +This creates an empty `firstdraft.foundation-plan.sketch/0.23` Plan targeting `rails-sketch/2026-11` and a client-generated Project ID under `.firstdraft/`. A nested ignore file keeps that local scratch area out of Git without changing the project's own `.gitignore`. Initialization makes no network request and refuses to replace an existing `.firstdraft` path. @@ -386,11 +451,12 @@ progress to stderr, with every line prefixed by `First Draft:`. It reports analy terminal failure or cancellation, the current GitHub phase, and an allowlisted reason, retry count, and exact UTC retry time when a GitHub preflight check is delayed. A retained retry with no next time is reported as paused and requiring operator recovery. Progress never includes IDs, hashes, repository names or URLs, raw server projections, -local paths, or environment values. Success writes exactly the validated private GitHub repository URL plus a +local paths, or environment values. The [update line](#update-line-and-refusals), which can appear among the +progress lines, names only versions and the public update page. Success writes exactly the validated private GitHub repository URL plus a newline to stdout. If the command fails after progress has begun, its structured JSON error envelope is the final stderr document after the progress lines. -The closed API `0.8.x` progress-reason allowlist is `github.configuration_missing`, `github.oauth_unavailable`, +The closed API `0.9.x` progress-reason allowlist is `github.configuration_missing`, `github.oauth_unavailable`, `github.api_unavailable`, `github.reauthorization_required`, `github.account_mismatch`, `github.installation_unavailable`, `github.installation_not_ready`, `github.preflight_unavailable`, the legacy-only `github.preflight_unclassified`, and these stage-specific fallbacks: `github.preflight_unavailable.configuration`, @@ -440,12 +506,13 @@ never starts replacement work. An incomplete rollback leaves `.firstdraft-root-o reconciliation before this command can run again. Artifact validation accepts only Plan format `firstdraft.foundation-plan.sketch/0.23` and target profile -`rails-sketch/2026-10`, in addition to matching the retained Compilation's provenance and verifying file integrity. +`rails-sketch/2026-11`, in addition to matching the retained Compilation's provenance and verifying file integrity. An earlier format or profile is rejected before materialization, even when the retained status names that profile. Successful root adoption is intentionally one-way. The original `.firstdraft` authoring state moves under -`.firstdraft/design/.firstdraft`; run later First Draft commands from `.firstdraft/design`. Run ordinary Rails -setup, preview, and tests from the generated application root. Retain the archive when further First Draft +`.firstdraft/design/.firstdraft`; run later Plan and Compilation commands from `.firstdraft/design`. Run ordinary +Rails setup, preview, and tests, and `report` and `conversation send`, from the generated application root, where +the CLI finds the archived Project and failure frames are relative to the application. Retain the archive when further First Draft authoring is useful. The CLI does not run or qualify the generated application's setup, preview, or test commands. Compiling a later Plan revision does not overwrite an already adopted root: choose a new absent output and deliberately reconcile it with application work. @@ -497,33 +564,114 @@ If the Compilation was started by `plan compile --github`, Cancel also cancels t Publication is a Project singleton in this release, so `plan compile --github` cannot start another one for that Project. +## Read the account + +```sh +firstdraft account +``` + +The command makes one `GET` and prints `{"reports": "on"}` or `{"reports": "off"}`. Reports are off until the person +says yes, when approving `firstdraft login` or later on their First Draft account page, where they can also turn +reports off again; an agent cannot turn them on. The command is not tied to a +Project: like `login`, it uses production, `--staging`, or `FIRSTDRAFT_API_URL`, with that origin's token. It prints +no other account fact. + +## Send progress and failure reports + +When reports are on, an agent tells First Draft how far a generated application has come, and about an unexpected +failure in generated code. Run these from the generated application's root after root adoption, where the CLI finds +the Project's state archived at `.firstdraft/design`, or from the Project's directory: + +```sh +firstdraft report progress --step specs_first_run --examples 120 --failures 14 \ + --behavior-to-write-failures 12 --items-remaining 9 +firstdraft report failure --kind spec_failure \ + --rerun "bin/rspec ./spec/models/movie_spec.rb:42" --error-class NoMethodError \ + --message "undefined method 'stars' for nil" --frame "app/models/movie.rb:12:in 'Movie#average'" \ + --fix-summary "Guarded a nil rating in Movie#average" +``` + +`` is `compilation.id` from `plan compile`. `--step` is `setup`, `specs_first_run`, +`behavior_written`, `specs_passing`, or `preview_started`. The counts are optional whole numbers of at most 1000000: +examples in the spec +run, failing examples, failing examples that the README's Behavior to write names, and Behavior to write items still +to write. The report carries the given counts under `counts`. + +A failure report needs only `--kind` (`spec_failure`, `setup_failure`, `boot_error`, or `lint_failure`). Each other +field is sent only in its shape, and left out otherwise: + +| Option | Field | What it may contain | +| ----------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--rerun` | `rerun` | An RSpec run of the application's specs: an optional `bundle exec ` or `bin/`, `rspec`, then one or more paths under `spec/` whose parts are letters, digits, `_`, `.`, and `-` separated by single slashes, each with optional `:LINE` parts. Leading environment assignments, with or without `env`, are dropped first, and a trailing slash after a spec directory is removed. | +| `--error-class` | `error_class` | A Ruby constant path, such as `ActiveRecord::RecordInvalid`. | +| `--frame` | `frames` | Up to 20 frames in the application's files: a relative path under `app/`, `lib/`, `config/`, `db/`, or `spec/` made of the same characters, with a line number, sent as `path:LINE`. A path inside the current directory may be absolute. | +| `--message` | `message` | Plain words: the first line, at most 300 characters. | +| `--fix-summary` | `fix_summary` | Plain words: the first line, at most 200 characters. | +| `--ruby-version`, `--rails-version` | `versions` | Version numbers, such as `3.4.7`, `8.1.4.1`, or `8.2.0.beta1`. | + +Free text keeps plain words only: the CLI takes the first line, replaces everything from the word that holds the first +quote character (`'`, `"`, or a backtick, including an apostrophe inside a word) to the end of the line with one `[…]`, +replaces each earlier word that contains `=`, `/`, `\`, or `@` or is longer than 24 characters with `[…]`, and keeps the +words that fit the length limit. A `lint_failure` therefore sends no rule name, and a rerun command that is not an +RSpec run is left out. The CLI reads no file for a failure report and attaches no diff or environment variable, but +the plain words of a message or fix summary it is given can still quote code, so pass only text that may be sent. + +Each command writes `Sending this report for Compilation to :`, the exact JSON +body, and, when a field did not fit its shape, a `Left out:` line naming it, on standard output, sends that body once in a `POST` to the origin pinned by a successful push, and writes +`Sent.` once First Draft acknowledges the stored report with `201`; any other success is `report_unavailable`. When the +account has reports off, First Draft answers `403 reports_off` and keeps nothing; the command writes +a line that says so and exits 0, so the agent's work continues. Neither command retries. + +## Send a planning conversation + +Only when the person says yes, and each time: + +```sh +firstdraft conversation send --person-agreed +``` + +Show the person the file first. Without `--person-agreed`, the command stops with `consent_required` before it reads +anything. With it, the command reads the Project pinned by a successful push, then the file, which must be a regular +file of 1 byte to 32 MiB. It writes `Sending ( bytes, SHA-256 ) for Project to .` +on standard output, then sends the file's bytes unchanged, once, as the `conversation[file]` part of a +`multipart/form-data` `POST`, named by its base name only. The CLI does not redact the file. Run the command from the +generated application's root after root adoption, or from the Project's directory. + +First Draft does not accept conversations yet. Until its service does, the command ends with status `404`: as +`conversation_unavailable` when the answer is not a problem document, or as `conversation_rejected` when it is. + ## Service endpoints -The CLI calls these Service API routes. The `/v1` routes go to the origin pinned for the Project and send the -selected token as a Bearer credential. The `/oauth` routes go to the origin selected for `login` or `logout` and -send form-encoded OAuth parameters without a Bearer credential. Every request refuses redirects and has a bounded +The CLI calls these Service API routes. The `/v1` routes send the selected token as a Bearer credential; +`/v1/account` goes to the origin selected as for `login`, and the others go to the origin pinned for the Project. The `/oauth` routes go to the origin selected for `login` or `logout` and send form-encoded OAuth parameters +without a Bearer credential. Every request refuses redirects and has a bounded timeout. Each request takes its method and path from one `SERVICE_ROUTES` entry in `src/api-response.js`. `test/service-endpoints.test.js` fails when this table and `SERVICE_ROUTES` differ, or when no file in `src/` uses a declared route. -| Method | Path | Purpose | -| ------ | ------------------------------------------------------------------ | ------------------------------------ | -| `PUT` | `/v1/projects/{project_id}/foundation-plan` | Create or replace the Head | -| `GET` | `/v1/projects/{project_id}/analysis` | Read the Head's current analysis | -| `POST` | `/v1/projects/{project_id}/compilations` | Start a Compilation of the Head | -| `GET` | `/v1/projects/{project_id}/compilations/{compilation_id}` | Read one retained Compilation | -| `POST` | `/v1/projects/{project_id}/compilations/{compilation_id}/cancel` | Cancel that Compilation | -| `GET` | `/v1/projects/{project_id}/compilations/{compilation_id}/artifact` | Download that Compilation's artifact | -| `PUT` | `/v1/projects/{project_id}/github-publication` | Start or rejoin the Publication | -| `GET` | `/v1/projects/{project_id}/github-publication` | Poll or reconcile the Publication | -| `POST` | `/oauth/token` | Exchange a login grant for a token | -| `POST` | `/oauth/device_authorization` | Start a device-flow login | -| `POST` | `/oauth/revoke` | Revoke a saved token | +| Method | Path | Purpose | +| ------ | -------------------------------------------------------------------------- | ------------------------------------ | +| `PUT` | `/v1/projects/{project_id}/foundation-plan` | Create or replace the Head | +| `GET` | `/v1/projects/{project_id}/analysis` | Read the Head's current analysis | +| `POST` | `/v1/projects/{project_id}/compilations` | Start a Compilation of the Head | +| `GET` | `/v1/projects/{project_id}/compilations/{compilation_id}` | Read one retained Compilation | +| `POST` | `/v1/projects/{project_id}/compilations/{compilation_id}/cancel` | Cancel that Compilation | +| `GET` | `/v1/projects/{project_id}/compilations/{compilation_id}/artifact` | Download that Compilation's artifact | +| `PUT` | `/v1/projects/{project_id}/github-publication` | Start or rejoin the Publication | +| `GET` | `/v1/projects/{project_id}/github-publication` | Poll or reconcile the Publication | +| `GET` | `/v1/account` | Read whether the account reports | +| `POST` | `/v1/projects/{project_id}/compilations/{compilation_id}/progress-reports` | Send a progress report | +| `POST` | `/v1/projects/{project_id}/compilations/{compilation_id}/failure-reports` | Send a failure report | +| `POST` | `/v1/projects/{project_id}/conversations` | Send a planning conversation | +| `POST` | `/oauth/token` | Exchange a login grant for a token | +| `POST` | `/oauth/device_authorization` | Start a device-flow login | +| `POST` | `/oauth/revoke` | Revoke a saved token | `plan push` sends the Plan `PUT`, and `plan status` reads the analysis. `plan compile` does both. It then starts a Compilation, polls it, and downloads its artifact. With `--github`, it starts and polls the Publication instead. `compilation status` reads one retained Compilation. `compilation download` reads it and downloads its artifact. -`compilation cancel` cancels it. +`compilation cancel` cancels it. `account` reads `/v1/account`. `report progress` and `report failure` post their +report, and `conversation send` posts its file. `login` exchanges its authorization code at `/oauth/token`. With `--interactive`, it starts at `/oauth/device_authorization` and then polls `/oauth/token`. `logout` calls `/oauth/revoke`. The browser, not the CLI, opens `/oauth/authorize` and `/device`, so they have no rows. @@ -531,10 +679,13 @@ CLI, opens `/oauth/authorize` and `/device`, so they have no rows. The first push sends `If-None-Match: *`. Later pushes, the Compilation start `POST`, and the Publication `PUT` send the saved Head ETag in `If-Match`. The cancel `POST` sends no precondition header. -The `/v1` routes belong to the API-contract range that `release/compatibility.json` accepts. The CLI does not read the -Service's `FirstDraft-API-Contract` response header. Instead, the Service's release compatibility check compares the -declared ranges before a release. The Service documents the routes in its Foundation Plan machine reference, -`docs/architecture/reference/README.md` in the private `firstdraft/firstdraft` repository. +The `/v1` routes belong to API contract `0.9.x`. `API_CONTRACT_RANGE` in `src/service-client.js` declares that range, +`release/compatibility.json` declares it for the Service's release compatibility check, and +`test/release-compatibility.test.js` keeps the two equal. The CLI reads `FirstDraft-API-Contract` on every response +and stops at a Service outside the range, as [update line and refusals](#update-line-and-refusals) describes: with +`api_contract_unsupported` when the command had a request still to send. The Service documents the routes in its +Foundation Plan machine reference, `docs/architecture/reference/README.md` in the private `firstdraft/firstdraft` +repository. ### Head and its ETag @@ -568,8 +719,10 @@ Use this checklist when a change adds a command or subcommand. Each step names t `COMPILATION_HELP`, or `GENERATE_HELP`. A new group also needs a line in `ROOT_HELP` and a branch in `run`. - Add the branch in `runPlan`, `runCompilation`, or `runGenerate`, and a `run` function. - Parse arguments with strict `parseArgs`. Invalid syntax writes `invalid_arguments` and exits 2. - - A command that calls the Service also accepts `--staging` and calls `authenticateApiCommand`. It maps each - error class to one `writeJson(stderr, …)` envelope and its exit status. + - A command that calls the Service also accepts `--staging` and calls `authenticateApiCommand` with + `service.fetch(fetchFunction)`, and awaits its module through `service.settle(…)` so that + [refusals](#update-line-and-refusals) replace its result. It maps each error class to one + `writeJson(stderr, …)` envelope and its exit status. 3. **Test it.** - Add `test/-.test.js`. Cover the help text, invalid arguments, the success output, and every handled `error` value. @@ -577,7 +730,8 @@ Use this checklist when a change adds a command or subcommand. Each step names t or `GENERATE_HELP` in `test/generate-uuid.test.js`. No test asserts the whole `compilation` group help. - Append a command that calls the Service to `REMOTE_COMMANDS` in `test/api-environments.test.js`. Some tests there select entries by index, so add it at the end. The command's first request must reach the pinned origin - with that origin's token, and one `401` must produce `authentication_required`. + with that origin's token, and one `401` must produce `authentication_required`. A command not tied to a Project, + such as `account`, selects its origin as `login` does; test that in its own file instead. - Add packed-package cases to `scripts/smoke-package.js`, including at least an invalid-arguments case. 4. **Package it.** Add each new `src/` file to the exact list in `scripts/check-pack.js`. `firstdraft/skills` keeps a copy of that list as `packedFileAllowlist` in `script/cli-contract/config.mjs`. The copy must change when @@ -596,6 +750,6 @@ Use this checklist when a change adds a command or subcommand. Each step names t [version rule](https://github.com/firstdraft/cli/blob/main/RELEASING.md#versions), and apply it with the [version pull request](https://github.com/firstdraft/cli/blob/main/RELEASING.md#prepare-the-version-pull-request) steps. If the command needs a route or response that the accepted API range lacks, the Service ships it first - under a new API-contract version. Then raise `requires.api_contract` in `release/compatibility.json`, and align - the Skills CLI requirement. Because the CLI does not read the contract header, an older Service rejects the new - route as not found. + under a new API-contract version. Then raise `requires.api_contract` in `release/compatibility.json` and + `API_CONTRACT_RANGE` in `src/service-client.js`, and align the Skills CLI requirement. The CLI then stops at a + Service outside the new range, as [update line and refusals](#update-line-and-refusals) describes. diff --git a/docs/errors.md b/docs/errors.md index 887dff4..2fe8bd8 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -5,10 +5,13 @@ This page owns handled-error interpretation, retry safety, and recovery guidance ## Handled output contract -Every handled subcommand failure ends with exactly one JSON object on standard error. `plan compile` may first write -progress lines; machine consumers can remove only lines beginning with the exact `First Draft: ` prefix and parse the +Every handled subcommand failure ends with exactly one JSON object on standard error. Any network command may first +write one [update or stop line](commands.md#update-line-and-refusals), and `plan compile` may first write progress lines; +both begin with the exact `First Draft: ` prefix, so machine consumers can remove only those lines and parse the remaining JSON document. `login` may first write its human-readable authorization instructions; its JSON object -starts on the line after them. Branch on the stable `error` value rather than the human-readable `detail`. +starts on the line after them. `report` and `conversation send` print what they send on standard output before +sending it, so standard output may hold that preview when they fail. Branch on the stable `error` value rather than +the human-readable `detail`. Handled output never includes command arguments, local Plan bytes, raw artifact bytes, raw filesystem or network errors, or unvalidated response bodies. `local_state_not_saved` is the sole exception to private-state redaction: @@ -59,24 +62,60 @@ command's recovery instructions below. If a saved login is rejected, run `firstd invalid. A logout whose server revocation is not confirmed still succeeds after removing the local entry. It writes a note on standard error; revoke the token on `/api-tokens` if it may still be active. +## Update and limit errors + +These errors replace a command's result when a First Draft response told the CLI to stop before the command +finished. The CLI finishes handling that response, so a push it accepted still saves its ETag, and then sends +nothing more. When the stopping response was the command's last, the command reports its own result instead, after +one `First Draft: ` line that names the required update ([update line and refusals](commands.md#update-line-and-refusals)). + +- `update_required`: First Draft's `FirstDraft-Minimum-Plugin` is newer than this setup's plugin, or, when no plugin + version is set, its `FirstDraft-Minimum-CLI` is newer than this CLI. `plugin_version` and `minimum_plugin_version`, + or `minimum_cli_version`, name the versions, beside `cli_version`. Tell the person to update with the steps at `update_url` (`https://firstdraft.com/update`), then run the + same command again with the same options; the CLI saved the ETag of any push that First Draft accepted. When + `current` is present, a Compilation had already started: follow `current.compilation.id` with + `compilation status` instead of compiling again. +- `api_contract_unsupported`: First Draft serves an API contract outside `accepted_api_contract`. When `api_contract` + is newer, update and continue as above. When it is older, the CLI is newer than that origin's Service; use the CLI + that the origin supports. +- `rate_limited`: First Draft answered `429` because a limit was reached. The refused request did nothing. + `response.code`, when present, names the limit: `compilation_limit_reached` or `project_limit_reached` for the Compilations or + new Projects an account may start in a day, and `reports_rate_limited` for its reports in an hour. + `response.detail` says when the next one can start, and `retry_at`, when present, is that UTC time from + `Retry-After`. Wait until then and run the command again; without either, the detail says to wait a minute. `login --interactive` meets + a limit shared by every CLI that starts a device login at once. When `current` is present, follow that Compilation + as above instead. + +A local failure while handling the stopping response, such as `local_state_not_saved` or `materialization_failed`, +is reported as itself, with its recovery data, after the stop line. + ## Ambiguous mutations `plan compile` supplies `phase: "push" | "compilation" | "publication"` when `request_outcome_unknown` requires phase-specific recovery: -- `phase: "push"` means the Plan mutation may have been accepted. Stop and reconcile local Head state. Until First - Draft has a Foundation Plan Head reconciliation endpoint, an accepted request whose response cannot be verified - may require manual recovery. Do not construct an ETag from the Plan digest or trust an unverified response. -- `phase: "compilation"` means a local Compilation (the default mode, with optional `--output`) may have started, but its retained identity is unknown. - The CLI never repeats that `POST`. Do not start another Compilation until the Project is reconciled through First - Draft or an operator can identify the retained work. +- `phase: "push"`, and `request_outcome_unknown` from `plan push`, mean the Plan may have been accepted, but the + response could not be verified, so local state was not changed. Run the same command once more, with the same + options and environment; a first push without a pinned origin otherwise goes to production. If First Draft accepts + it, carry on. If it answers `server_rejected` with status `412` (`precondition_failed`), its Plan is no longer the + one this folder last pushed: the first push may have landed, or another copy of the Project pushed. If another + copy holds newer work, continue from that copy. Otherwise start a new Project, which forks this one: run + `firstdraft plan init --name ` in a new folder, copy `.firstdraft/foundation-plan.json` from the old folder + over the new one, and push or compile from there with the same options and the old folder's origin: the `api_url` + in its `.firstdraft/state.json`, or, when a first push never saved one, the origin that push used. Select it with + `--staging` for staging, or the same `FIRSTDRAFT_API_URL` for a custom origin. A new folder has no pinned origin, + so without one the push goes to production. Never construct an ETag from the Plan + digest or edit `.firstdraft/state.json`. +- `phase: "compilation"` means a local Compilation (the default mode, with optional `--output`) may have started, + but its identity is unknown. The CLI never repeats that `POST` itself. Run the same `plan compile` command, with + the same options and environment, once more. If a Compilation is still active, First Draft refuses with + `compilation_active` and names it; follow [stuck Compilation recovery](#stuck-compilation-recovery). Otherwise the + rerun starts a new Compilation; one that the first attempt may have started costs only service time and one of the + day's Compilations. - `phase: "publication"` means the singleton Publication mutation was not resolved. Do not run concurrent Compile commands. After the prior invocation exits, wait and rerun `plan compile --github` with unchanged Plan bytes to safely reconcile or resume the retained singleton. -`plan push` also reports `request_outcome_unknown` if a failure happens after sending its request. Local state remains -unchanged. Stop and reconcile rather than assuming the request failed and repeating the mutation. - If a verified Plan response cannot replace local state, preserve the printed `recovery_state`; an adjacent `.tmp` file may contain the same private recovery copy. Do not push again until the accepted ETag state is repaired. @@ -95,12 +134,12 @@ starts a new Compilation after analysis. ## Direct Compilation recovery -Do not blindly rerun `plan compile` after its Compilation start was accepted or may have been accepted. -That command creates new work; it is not a retained-Compilation reconciliation command. +Do not rerun `plan compile` after its Compilation start was accepted: that command creates new work; it is not a +retained-Compilation reconciliation command. If `request_outcome_unknown` reports `phase: "compilation"`, the start request did not yield a validated retained -ID. The CLI sent exactly one `POST` and did not retry it. Stop until First Draft or an operator can reconcile the -Project and identify whether work was retained. +ID. The CLI sent exactly one `POST` and did not retry it. Rerun `plan compile` once, as +[ambiguous mutations](#ambiguous-mutations) describes. Once the start response has yielded a validated retained Compilation, later status, artifact, authentication, and materialization failure envelopes include that last validated projection as `current`. Preserve @@ -161,6 +200,31 @@ Cancel never changes a succeeded or failed Compilation, and repeating it is safe - `invalid_compilation_status` means the response violated the Compilation contract, so the cancellation may or may not have happened. Check with `compilation status` rather than repeating the unchanged request. +## Report and conversation errors + +`report progress` and `report failure` never stop an agent's work. When the account has reports off, First Draft +keeps nothing and the command exits 0 with a line that says so; that is not an error. + +- `report_rejected`: First Draft refused the report and kept nothing. `response.code` says why, for example + `compilation_not_found` when the Compilation is not in this Project, or `invalid_report` when a field breaks the + report's shape. Continue without the report. +- `report_unavailable`: a network failure, timeout, server error, or a success without First Draft's `201` + acknowledgment left the outcome unconfirmed, and First Draft may hold the report. Continue without it rather than + sending it again. +- `account_unavailable`: `account` could not read the account. This read-only request is safe to retry. + `invalid_server_response` from `account` means the response broke its contract. + +`conversation send` sends nothing unless the person said yes: + +- `consent_required`: `--person-agreed` was missing. Ask the person, show them the file, and pass the flag only after + they say yes this time. No file or state was read. +- `conversation_unreadable`: the file was missing or not a regular file (`reason: "unreadable"`), empty, or larger + than 32 MiB (`too_large`). Nothing was sent. +- `conversation_rejected`: First Draft refused the file and kept nothing; `response.code` says why. +- `conversation_unavailable`: the outcome is unconfirmed, and First Draft may hold the file. Ask the person before + sending it again. Until First Draft's service accepts conversations, an upload ends with status `404`: here when the + answer is not a problem document, and as `conversation_rejected` when it is. + ## Publication recovery The Publication is a Project singleton. If its initial conditional `PUT` is ambiguous, the CLI attempts one @@ -178,39 +242,46 @@ stopped without following the replacement. ## Error index -| Commands | `error` | Exit | Meaning | -| -------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---: | ------------------------------------------------------------------------------------------------------ | -| Any leaf command | `invalid_arguments` | 2 | Syntax was invalid; no request was made. | -| `plan init` | `local_initialization_failed` | 1 | Initialization failed without overwriting an existing path. | -| Network commands | `invalid_configuration` | 2 | API origin or saved Head state is incompatible. | -| `login` | `authorization_denied`, `authorization_expired` | 1 | The approval was denied, or not granted before the callback wait or device code expired. | -| `login` | `login_failed` | 1 | Nothing was saved; `phase: "write"` means a token was issued ([recovery](#login-and-logout-errors)). | -| `logout` | `logout_failed` | 1 | Check `phase` and `revoked`; revocation may have happened ([recovery](#login-and-logout-errors)). | -| Network commands | `authentication_required` | 1 | No environment or saved token exists for the origin, or First Draft rejected it. | -| Plan commands, `compilation *` | `local_input_unreadable` | 1 | Required local Plan or private state could not be read. | -| Status, Compile, Compilation commands | `project_not_pushed` | 1 | No API origin is pinned for the local Project. | -| `plan push`, `plan compile` | `request_outcome_unknown` | 1 | A mutation or its response could not be verified; `plan compile` identifies its mutation phase. | -| `plan push`, `plan compile` | `local_state_not_saved` | 1 | The Plan was accepted but the private ETag state could not be replaced; includes `recovery_state`. | -| `plan push`, `plan compile` | `server_rejected` | 1 | First Draft returned validated Plan diagnostics or rejected the request with a validated problem. | -| `plan status` | `server_rejected` | 1 | First Draft rejected the analysis status request with a validated non-authentication problem. | -| `plan status` | `status_unavailable`, `invalid_server_response` | 1 | The analysis read failed or violated its protocol. | -| `plan compile` | `analysis_status_unavailable`, `invalid_analysis_status`, `analysis_status_rejected` | 1 | The bounded analysis read failed, was invalid, or was rejected. | -| Analysis waits | `analysis_changed`, `wait_timed_out`, `analysis_wait_timed_out` | 1 | The pinned analysis changed or remained processing at the deadline. | -| `plan compile` | `plan_not_valid` | 1 | Analysis completed without `valid`; `current` contains diagnostics and status. | -| `plan compile` | `local_plan_changed` | 1 | Local bytes or saved state changed after acceptance, before the selected mutation. | -| `plan compile` | `compilation_start_rejected`, `compilation_status_unavailable`, `invalid_compilation_status` | 1 | Direct start was rejected or retained status failed; post-start errors include `current`. | -| `plan compile` | `compilation_changed`, `compilation_wait_timed_out`, `compilation_failed`, `compilation_cancelled` | 1 | The pinned direct Compilation changed, timed out, failed, or was cancelled. | -| `plan compile --github` | `publication_start_rejected`, `publication_status_unavailable`, `invalid_publication_status` | 1 | Publication start or status failed its validated transport contract. | -| `plan compile --github` | `publication_changed`, `publication_wait_timed_out`, `publication_failed`, `publication_cancelled` | 1 | The pinned Publication changed, timed out, or reached a non-success terminal state. | -| `compilation status`, `compilation download` | `compilation_status_unavailable`, `invalid_compilation_status` | 1 | The retained status could not be read or violated its exact contract. | -| `compilation status --wait` | `compilation_changed`, `compilation_wait_timed_out` | 1 | Retained identity/provenance changed or the wait ended. | -| `compilation download` | `compilation_not_succeeded` | 1 | Status was not `succeeded`; no artifact request was made. | -| `compilation cancel` | `compilation_cancel_rejected` | 1 | Nothing was cancelled; `response.code` says why ([recovery](#stuck-compilation-recovery)). | -| `compilation cancel` | `compilation_cancel_unavailable` | 1 | The cancellation could not be confirmed; repeating it is safe. | -| `compilation cancel` | `invalid_compilation_status` | 1 | The response violated the Compilation contract; check status before repeating. | -| Download commands | `artifact_unavailable`, `invalid_artifact` | 1 | Artifact transport or integrity validation failed; direct Compile post-start errors include `current`. | -| Download commands | `invalid_output_path` | 2 | The absent destination or root-adoption preconditions failed; `reason` identifies the stable refusal. | -| Download commands | `materialization_failed` | 1 | The output changed or its transaction failed; `reason` identifies incomplete rollback when applicable. | +| Commands | `error` | Exit | Meaning | +| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ---: | --------------------------------------------------------------------------------------------------------------- | +| Any leaf command | `invalid_arguments` | 2 | Syntax was invalid; no request was made. | +| Network commands except `logout` | `update_required`, `api_contract_unsupported` | 1 | First Draft needs a newer plugin or CLI, or serves another API contract ([recovery](#update-and-limit-errors)). | +| Network commands except `logout` | `rate_limited` | 1 | First Draft refused a request at a limit; `retry_at` says when to try again. | +| `plan init` | `local_initialization_failed` | 1 | Initialization failed without overwriting an existing path. | +| Network commands | `invalid_configuration` | 2 | API origin or saved Head state is incompatible. | +| `login` | `authorization_denied`, `authorization_expired` | 1 | The approval was denied, or not granted before the callback wait or device code expired. | +| `login` | `login_failed` | 1 | Nothing was saved; `phase: "write"` means a token was issued ([recovery](#login-and-logout-errors)). | +| `logout` | `logout_failed` | 1 | Check `phase` and `revoked`; revocation may have happened ([recovery](#login-and-logout-errors)). | +| Network commands | `authentication_required` | 1 | No environment or saved token exists for the origin, or First Draft rejected it. | +| Plan, `compilation *`, `report`, `conversation` | `local_input_unreadable` | 1 | Required local Plan or private state could not be read. | +| Status, Compile, Compilation, `report`, `conversation` | `project_not_pushed` | 1 | No API origin is pinned for the local Project. | +| `plan push`, `plan compile` | `request_outcome_unknown` | 1 | A mutation or its response could not be verified; `plan compile` identifies its mutation phase. | +| `plan push`, `plan compile` | `local_state_not_saved` | 1 | The Plan was accepted but the private ETag state could not be replaced; includes `recovery_state`. | +| `plan push`, `plan compile` | `server_rejected` | 1 | First Draft returned validated Plan diagnostics or rejected the request with a validated problem. | +| `plan status` | `server_rejected` | 1 | First Draft rejected the analysis status request with a validated non-authentication problem. | +| `plan status` | `status_unavailable`, `invalid_server_response` | 1 | The analysis read failed or violated its protocol. | +| `plan compile` | `analysis_status_unavailable`, `invalid_analysis_status`, `analysis_status_rejected` | 1 | The bounded analysis read failed, was invalid, or was rejected. | +| Analysis waits | `analysis_changed`, `wait_timed_out`, `analysis_wait_timed_out` | 1 | The pinned analysis changed or remained processing at the deadline. | +| `plan compile` | `plan_not_valid` | 1 | Analysis completed without `valid`; `current` contains diagnostics and status. | +| `plan compile` | `local_plan_changed` | 1 | Local bytes or saved state changed after acceptance, before the selected mutation. | +| `plan compile` | `compilation_start_rejected`, `compilation_status_unavailable`, `invalid_compilation_status` | 1 | Direct start was rejected or retained status failed; post-start errors include `current`. | +| `plan compile` | `compilation_changed`, `compilation_wait_timed_out`, `compilation_failed`, `compilation_cancelled` | 1 | The pinned direct Compilation changed, timed out, failed, or was cancelled. | +| `plan compile --github` | `publication_start_rejected`, `publication_status_unavailable`, `invalid_publication_status` | 1 | Publication start or status failed its validated transport contract. | +| `plan compile --github` | `publication_changed`, `publication_wait_timed_out`, `publication_failed`, `publication_cancelled` | 1 | The pinned Publication changed, timed out, or reached a non-success terminal state. | +| `compilation status`, `compilation download` | `compilation_status_unavailable`, `invalid_compilation_status` | 1 | The retained status could not be read or violated its exact contract. | +| `compilation status --wait` | `compilation_changed`, `compilation_wait_timed_out` | 1 | Retained identity/provenance changed or the wait ended. | +| `compilation download` | `compilation_not_succeeded` | 1 | Status was not `succeeded`; no artifact request was made. | +| `compilation cancel` | `compilation_cancel_rejected` | 1 | Nothing was cancelled; `response.code` says why ([recovery](#stuck-compilation-recovery)). | +| `compilation cancel` | `compilation_cancel_unavailable` | 1 | The cancellation could not be confirmed; repeating it is safe. | +| `compilation cancel` | `invalid_compilation_status` | 1 | The response violated the Compilation contract; check status before repeating. | +| Download commands | `artifact_unavailable`, `invalid_artifact` | 1 | Artifact transport or integrity validation failed; direct Compile post-start errors include `current`. | +| Download commands | `invalid_output_path` | 2 | The absent destination or root-adoption preconditions failed; `reason` identifies the stable refusal. | +| Download commands | `materialization_failed` | 1 | The output changed or its transaction failed; `reason` identifies incomplete rollback when applicable. | +| `account` | `account_unavailable`, `invalid_server_response` | 1 | The account read failed or violated its contract. | +| `report progress`, `report failure` | `report_rejected`, `report_unavailable` | 1 | The report was refused, or its outcome is unconfirmed; continue without it. | +| `conversation send` | `consent_required` | 2 | `--person-agreed` was missing; nothing was read or sent. | +| `conversation send` | `conversation_unreadable` | 1 | The file is unreadable, empty, or too large; nothing was sent. | +| `conversation send` | `conversation_rejected`, `conversation_unavailable` | 1 | The upload was refused, or its outcome is unconfirmed. | Root-output `invalid_output_path.reason` values are `destination_exists`, `root_not_real`, `root_not_writable`, `root_platform_unsupported`, `root_reserved_path`, `root_entry_unsupported`, `root_enclosing_worktree`, diff --git a/release/compatibility.json b/release/compatibility.json index e01eb2a..b9a90d6 100644 --- a/release/compatibility.json +++ b/release/compatibility.json @@ -3,7 +3,7 @@ "component": "cli", "version": "0.9.0", "requires": { - "api_contract": [">= 0.8.0", "< 0.9.0"], + "api_contract": [">= 0.9.0", "< 0.10.0"], "foundation_plan_formats": ["firstdraft.foundation-plan.sketch/0.23"] } } diff --git a/scripts/check-pack.js b/scripts/check-pack.js index 275d01d..195801b 100644 --- a/scripts/check-pack.js +++ b/scripts/check-pack.js @@ -40,7 +40,9 @@ if (result.status !== 0) { "src/api-response.js", "src/application-identity.js", "src/cli.js", + "src/commands/account.js", "src/commands/compilation.js", + "src/commands/conversation.js", "src/commands/login.js", "src/commands/logout.js", "src/commands/plan-compile.js", @@ -48,6 +50,7 @@ if (result.status !== 0) { "src/commands/plan-publish.js", "src/commands/plan-push.js", "src/commands/plan-status.js", + "src/commands/report.js", "src/compilation-artifact.js", "src/credentials.js", "src/file-system.js", @@ -55,6 +58,7 @@ if (result.status !== 0) { "src/plan-compile-progress.js", "src/plan-state.js", "src/root-output.js", + "src/service-client.js", "src/uuid-v7.js", "src/version.js", ]); diff --git a/scripts/smoke-package.js b/scripts/smoke-package.js index 16b2f2e..0e79e9a 100644 --- a/scripts/smoke-package.js +++ b/scripts/smoke-package.js @@ -273,6 +273,45 @@ try { "Invalid arguments. Run 'firstdraft compilation cancel --help' for usage.", }); + const invalidAccount = spawnPackedCli( + ["account", "--canary-secret-option"], + installationDirectory, + ); + assertHandledFailure(invalidAccount, 2, { + error: "invalid_arguments", + detail: "Invalid arguments. Run 'firstdraft account --help' for usage.", + }); + + const invalidReport = spawnPackedCli( + ["report", "progress", "not-a-uuid", "--step", "setup"], + installationDirectory, + ); + assertHandledFailure(invalidReport, 2, { + error: "invalid_arguments", + detail: + "Invalid arguments. Run 'firstdraft report progress --help' for usage.", + }); + + const invalidFailureReport = spawnPackedCli( + ["report", "failure", "not-a-uuid", "--kind", "lint"], + installationDirectory, + ); + assertHandledFailure(invalidFailureReport, 2, { + error: "invalid_arguments", + detail: + "Invalid arguments. Run 'firstdraft report failure --help' for usage.", + }); + + const conversationWithoutConsent = spawnPackedCli( + ["conversation", "send", "canary-secret.jsonl"], + installationDirectory, + ); + assertHandledFailure(conversationWithoutConsent, 2, { + error: "consent_required", + detail: + "Nothing was sent. Ask the person whether to send this conversation, show them the file, and pass --person-agreed only after they say yes this time.", + }); + const invalidLogin = spawnPackedCli( ["login", "--canary-secret-option"], installationDirectory, diff --git a/src/api-authentication.js b/src/api-authentication.js index 7af9d13..087deae 100644 --- a/src/api-authentication.js +++ b/src/api-authentication.js @@ -66,6 +66,10 @@ export function authenticateApiCommand({ let selectedOrigin = staging ? STAGING_API_URL : undefined; const request = fetchFunction ?? globalThis.fetch; + /** @param {string} origin */ + const tokenFor = (origin) => + environmentTokenFor(origin, { apiToken, stagingApiToken }) ?? + storedToken(readStoredTokens(), origin); /** @type {typeof globalThis.fetch} */ const authorizedFetch = (input, init) => { const endpoint = new URL(input instanceof Request ? input.url : input); @@ -74,9 +78,7 @@ export function authenticateApiCommand({ "The requested API environment does not match the Project origin. No request was made.", ); } - const token = - environmentTokenFor(endpoint.origin, { apiToken, stagingApiToken }) ?? - storedToken(readStoredTokens(), endpoint.origin); + const token = tokenFor(endpoint.origin); if (token === undefined) throw new ApiAuthenticationRequiredError(); selectedOrigin = endpoint.origin; return request(input, { @@ -87,7 +89,12 @@ export function authenticateApiCommand({ }, }); }; - return { apiUrl: configured, fetchFunction: authorizedFetch }; + return { + apiUrl: configured, + fetchFunction: authorizedFetch, + /** Whether a request to `origin` would carry a token. @param {string} origin */ + hasTokenFor: (origin) => tokenFor(origin) !== undefined, + }; } /** @param {Readonly>} tokens @param {string} origin */ diff --git a/src/api-response.js b/src/api-response.js index ebdfb4d..203e4fc 100644 --- a/src/api-response.js +++ b/src/api-response.js @@ -59,6 +59,22 @@ export const SERVICE_ROUTES = { method: "GET", path: "/v1/projects/{project_id}/github-publication", }, + readAccount: { + method: "GET", + path: "/v1/account", + }, + sendProgressReport: { + method: "POST", + path: "/v1/projects/{project_id}/compilations/{compilation_id}/progress-reports", + }, + sendFailureReport: { + method: "POST", + path: "/v1/projects/{project_id}/compilations/{compilation_id}/failure-reports", + }, + sendConversation: { + method: "POST", + path: "/v1/projects/{project_id}/conversations", + }, requestOAuthToken: { method: "POST", path: "/oauth/token", @@ -164,6 +180,23 @@ export function isProblemBody(response, body) { ); } +/** + * The fields of a problem that isProblemBody accepted, and nothing else. + * + * @param {unknown} body + */ +export function problemProjection(body) { + const problem = /** @type {Record} */ (body); + + return { + ...(problem.type === "about:blank" ? { type: problem.type } : {}), + title: problem.title, + status: problem.status, + code: problem.code, + detail: problem.detail, + }; +} + /** * @param {unknown} value * @returns {value is Record & {severity: "error" | "warning"}} diff --git a/src/cli.js b/src/cli.js index 2eed6e3..7f5213b 100644 --- a/src/cli.js +++ b/src/cli.js @@ -83,10 +83,46 @@ import { PlanStatusTimeoutError, readPlanStatus, } from "./commands/plan-status.js"; +import { + AccountResponseInvalidError, + AccountUnavailableError, + readAccount, +} from "./commands/account.js"; +import { + ConversationFileError, + ConversationRejectedError, + ConversationUnavailableError, + readConversationFile, + sendConversation, +} from "./commands/conversation.js"; +import { + FAILURE_KINDS, + PROGRESS_STEPS, + ReportRejectedError, + ReportUnavailableError, + failureReportBody, + progressReportBody, + sendReport, +} from "./commands/report.js"; +import { SERVICE_ROUTES } from "./api-response.js"; import { storedTokenReader } from "./credentials.js"; import { isFileSystemError } from "./file-system.js"; import { createPlanCompileProgressReporter } from "./plan-compile-progress.js"; -import { isUuidV7 } from "./plan-state.js"; +import { + PlanStateNotPushedError, + isUuidV7, + readPinnedProject, +} from "./plan-state.js"; +import { + API_CONTRACT_RANGE, + ApiContractUnsupportedError, + RateLimitedError, + ServiceStopError, + UPDATE_URL, + UpdateRequiredError, + createServiceSession, + stopSentence, +} from "./service-client.js"; import { generateUuidV7 } from "./uuid-v7.js"; import { VERSION } from "./version.js"; @@ -97,11 +133,14 @@ Usage: firstdraft [options] Commands: - compilation Inspect, download, and cancel Compilations - generate Generate local values - login Log in to First Draft and save a token - logout Revoke and remove the saved token - plan Work with Foundation Plans + account Show whether this account sends reports + compilation Inspect, download, and cancel Compilations + conversation Send a planning conversation to First Draft + generate Generate local values + login Log in to First Draft and save a token + logout Revoke and remove the saved token + plan Work with Foundation Plans + report Send a progress or failure report to First Draft Options: --staging Use staging for API commands (production is the default) @@ -109,6 +148,124 @@ Options: -V, --version Show version `; +const ACCOUNT_HELP = `First Draft CLI + +Usage: + firstdraft account + +Options: + --staging Use staging + -h, --help Show help + +Environment: + FIRSTDRAFT_API_TOKEN Authenticate production or custom API origins + FIRSTDRAFT_STAGING_API_TOKEN Authenticate staging.firstdraft.com + FIRSTDRAFT_API_URL Use a custom API origin + +The command reads the signed-in account once and prints whether it sends +progress and failure reports. Only the person turns reports on or off: when +approving firstdraft login, or later on their First Draft account page. +`; + +const REPORT_HELP = `First Draft CLI + +Usage: + firstdraft report [options] + +Commands: + progress Report how far the generated application has come + failure Report an unexpected failure in generated code + +Options: + -h, --help Show help +`; + +const REPORT_PROGRESS_HELP = `First Draft CLI + +Usage: + firstdraft report progress --step [counts] + +Options: + --staging Use staging; reject a different saved origin + --step setup, specs_first_run, behavior_written, + specs_passing, or preview_started + --examples Examples in the spec run + --failures Failing examples + --behavior-to-write-failures Failing examples that Behavior to write names + --items-remaining Behavior to write items still to write + (each count at most 1000000) + -h, --help Show help + +Environment: + FIRSTDRAFT_API_TOKEN Authenticate production or custom API origins + FIRSTDRAFT_STAGING_API_TOKEN Authenticate staging.firstdraft.com + +The command prints the exact report, then sends it once to the origin pinned +by a successful plan push. When the account has reports off, First Draft keeps +nothing and the command still exits 0. +`; + +const REPORT_FAILURE_HELP = `First Draft CLI + +Usage: + firstdraft report failure --kind [options] + +Options: + --staging Use staging; reject a different saved origin + --kind spec_failure, setup_failure, boot_error, or + lint_failure + --rerun The RSpec run that reproduces the failure + --error-class The exception's Ruby constant + --message Error message (first line, plain words) + --frame Backtrace frame in the application, repeatable + (first 20) + --fix-summary One line on the fix (plain words) + --ruby-version Ruby version + --rails-version Rails version + -h, --help Show help + +Environment: + FIRSTDRAFT_API_TOKEN Authenticate production or custom API origins + FIRSTDRAFT_STAGING_API_TOKEN Authenticate staging.firstdraft.com + +The command keeps each field only in its shape: an RSpec run of the +application's specs, a Ruby constant, frames in the application's files, +version numbers, and the plain words of free text. It prints the exact report +and what it left out, then sends it once to the origin pinned by a successful +plan push. Run it from the generated application's root. +`; + +const CONVERSATION_HELP = `First Draft CLI + +Usage: + firstdraft conversation [options] + +Commands: + send Send one planning conversation file to First Draft + +Options: + -h, --help Show help +`; + +const CONVERSATION_SEND_HELP = `First Draft CLI + +Usage: + firstdraft conversation send --person-agreed + +Options: + --staging Use staging; reject a different saved origin + --person-agreed The person said yes to sending this file, this time + -h, --help Show help + +Environment: + FIRSTDRAFT_API_TOKEN Authenticate production or custom API origins + FIRSTDRAFT_STAGING_API_TOKEN Authenticate staging.firstdraft.com + +Ask the person each time, and show them the file first. The command prints the +file's path, size, and SHA-256 and the Project, then sends the file's bytes +unchanged, once, to the origin pinned by a successful plan push. +`; + const PLAN_HELP = `First Draft CLI Usage: @@ -366,6 +523,8 @@ const PLAN_USAGE_ERROR = "Invalid arguments.\nRun 'firstdraft plan --help' for usage.\n"; const PLAN_UNKNOWN_COMMAND = "Unknown command.\nRun 'firstdraft plan --help' for usage.\n"; +const REPORTS_OFF_MESSAGE = + "Not kept: this account has reports off, so First Draft kept nothing. Continue without sending reports.\n"; const PLAN_INIT_INVALID_ARGUMENTS_DETAIL = "Invalid arguments. Run 'firstdraft plan init --help' for usage."; const PLAN_INIT_FAILED_DETAIL = @@ -376,7 +535,7 @@ const PLAN_PUSH_INVALID_ARGUMENTS_DETAIL = const PLAN_PUSH_LOCAL_INPUT_UNREADABLE_DETAIL = "Could not read the local First Draft Plan or state. No network request was made. Preserve the local files for manual recovery."; const PLAN_PUSH_REQUEST_OUTCOME_UNKNOWN_DETAIL = - "The Plan may have been accepted, but the response could not be verified. Stop and reconcile before pushing again; local state was not changed."; + "The Plan may have been accepted, but the response could not be verified, so local state was not changed. Run the same command once more, with the same options and environment. If First Draft rejects it with status 412, its Plan is no longer the one this folder last pushed: the first push may have landed, or another copy of this Project pushed. If nothing else pushes this Project, start a new one: run 'firstdraft plan init --name ' in a new folder, copy this .firstdraft/foundation-plan.json over the new one, and push from there to this folder's origin: the api_url in its .firstdraft/state.json, or, when a first push never saved one, the origin that push used. Use --staging for staging or the same FIRSTDRAFT_API_URL for a custom origin."; const PLAN_PUSH_SERVER_REJECTED_DETAIL = "First Draft rejected the Plan."; const AUTHENTICATION_REQUIRED_DETAIL = "First Draft authentication is required. Run 'firstdraft login' for the same environment, or set FIRSTDRAFT_API_TOKEN for production or custom origins, or FIRSTDRAFT_STAGING_API_TOKEN for staging."; @@ -419,7 +578,7 @@ const PLAN_COMPILE_LOCAL_INPUT_UNREADABLE_DETAIL = const PLAN_COMPILE_NOT_PUSHED_DETAIL = "The current Foundation Plan could not be associated with a pushed Project."; const PLAN_COMPILE_REQUEST_OUTCOME_UNKNOWN_DETAIL = - "The current Plan may have been accepted, but its response could not be verified. Stop and reconcile before compiling again."; + "The current Plan may have been accepted, but its response could not be verified, so local state was not changed. Run the same command once more, with the same options and environment. If First Draft rejects the push with status 412, its Plan is no longer the one this folder last pushed: the first push may have landed, or another copy of this Project pushed. If nothing else pushes this Project, start a new one: run 'firstdraft plan init --name ' in a new folder, copy this .firstdraft/foundation-plan.json over the new one, and compile from there with the same options and this folder's origin: the api_url in its .firstdraft/state.json, or, when a first push never saved one, the origin that push used. Use --staging for staging or the same FIRSTDRAFT_API_URL for a custom origin."; const PLAN_COMPILE_PLAN_REJECTED_DETAIL = "First Draft rejected the current Foundation Plan."; const PLAN_COMPILE_ANALYSIS_REJECTED_DETAIL = @@ -429,7 +588,7 @@ const PLAN_COMPILE_ANALYSIS_NOT_VALID_DETAIL = const PLAN_COMPILE_LOCAL_PLAN_CHANGED_DETAIL = "The local Foundation Plan changed after validation. Run 'firstdraft plan compile' again to submit the current bytes."; const PLAN_COMPILE_DIRECT_REQUEST_OUTCOME_UNKNOWN_DETAIL = - "A Compilation may have started, but its response could not be verified. Do not rerun 'firstdraft plan compile' or start another Compilation until the current Project is reconciled."; + "A Compilation may have started, but its response could not be verified. Run the same command once more, with the same options and environment. If First Draft answers compilation_active, check the Compilation it names with 'firstdraft compilation status', and cancel it with 'firstdraft compilation cancel' only if it is stuck."; const PLAN_COMPILE_DIRECT_START_REJECTED_DETAIL = "First Draft rejected the direct Compilation request."; const PLAN_COMPILE_DIRECT_STATUS_UNAVAILABLE_DETAIL = @@ -509,6 +668,34 @@ const GENERATE_UUID_INVALID_ARGUMENTS_DETAIL = "Invalid arguments. Run 'firstdraft generate uuid --help' for usage."; const GENERATE_APPLICATION_KEY_INVALID_ARGUMENTS_DETAIL = "Invalid arguments. Run 'firstdraft generate application-key --help' for usage."; +const ACCOUNT_INVALID_ARGUMENTS_DETAIL = + "Invalid arguments. Run 'firstdraft account --help' for usage."; +const ACCOUNT_UNAVAILABLE_DETAIL = + "Could not read the account. This read-only request is safe to retry."; +const ACCOUNT_INVALID_RESPONSE_DETAIL = + "First Draft returned an invalid account response. Retrying the unchanged request will not repair this protocol mismatch."; +const REPORT_PROGRESS_INVALID_ARGUMENTS_DETAIL = + "Invalid arguments. Run 'firstdraft report progress --help' for usage."; +const REPORT_FAILURE_INVALID_ARGUMENTS_DETAIL = + "Invalid arguments. Run 'firstdraft report failure --help' for usage."; +const REPORT_REJECTED_DETAIL = + "First Draft rejected the report, so it was not kept; response.code says why. Continue without it."; +const REPORT_UNAVAILABLE_DETAIL = + "Could not confirm that First Draft received the report, and First Draft may hold it already. Continue without it rather than sending it again."; +const CONVERSATION_SEND_INVALID_ARGUMENTS_DETAIL = + "Invalid arguments. Run 'firstdraft conversation send --help' for usage."; +const CONVERSATION_CONSENT_REQUIRED_DETAIL = + "Nothing was sent. Ask the person whether to send this conversation, show them the file, and pass --person-agreed only after they say yes this time."; +const PINNED_LOCAL_INPUT_UNREADABLE_DETAIL = + "Could not read valid local First Draft state, so nothing was sent. Run the command from the generated application's root after root adoption, or from the Project's directory."; +const PINNED_NOT_PUSHED_DETAIL = + "The local Project has no pinned API origin, so nothing was sent. Run 'firstdraft plan push' first."; +const CONVERSATION_UNREADABLE_DETAIL = + "The conversation file cannot be sent, so nothing was sent. reason says why: unreadable, empty, or too_large."; +const CONVERSATION_REJECTED_DETAIL = + "First Draft rejected the conversation, so it was not kept; response.code says why."; +const CONVERSATION_UNAVAILABLE_DETAIL = + "Could not confirm that First Draft received the conversation, and First Draft may hold it already. Do not send it again without asking the person."; /** * @typedef {object} Writer @@ -548,10 +735,10 @@ const GENERATE_APPLICATION_KEY_INVALID_ARGUMENTS_DETAIL = * @property {() => string} [homedir] * @property {import("./credentials.js").CredentialsFileSystem} [credentialsFileSystem] * @property {number} [credentialsLockTimeoutMs] - * @property {() => string} [hostname] * @property {(delayMs: number, signal?: AbortSignal) => Promise} [loginSleep] * @property {() => number} [loginNow] * @property {import("./oauth.js").StartLoopbackServer} [startLoopbackServer] + * @property {() => number} [serviceNow] the clock for a limit's retry time */ /** @@ -584,10 +771,10 @@ const GENERATE_APPLICATION_KEY_INVALID_ARGUMENTS_DETAIL = * @property {string} [stagingApiToken] * @property {boolean} [staging] * @property {import("./credentials.js").CredentialStore} [credentials] - * @property {() => string} [hostname] * @property {(delayMs: number, signal?: AbortSignal) => Promise} [loginSleep] * @property {() => number} [loginNow] * @property {import("./oauth.js").StartLoopbackServer} [startLoopbackServer] + * @property {import("./service-client.js").ServiceSession} service */ /** @@ -603,7 +790,15 @@ const GENERATE_APPLICATION_KEY_INVALID_ARGUMENTS_DETAIL = */ /** - * @typedef {Pick} LoginCommandOptions + * @typedef {Pick} LoginCommandOptions + */ + +/** + * @typedef {Pick} AccountCommandOptions + */ + +/** + * @typedef {AccountCommandOptions & {cwd?: string, getCwd: () => string, planPushFileSystem?: import("./commands/plan-push.js").PlanPushFileSystem}} ServiceCommandOptions */ /** @param {RunOptions} options */ @@ -639,10 +834,10 @@ export async function run({ homedir, credentialsFileSystem, credentialsLockTimeoutMs, - hostname, loginSleep, loginNow, startLoopbackServer, + serviceNow, }) { const staging = argv[0] === "--staging"; if (staging) argv = argv.slice(1); @@ -653,6 +848,11 @@ export async function run({ fileSystem: credentialsFileSystem, lockTimeoutMs: credentialsLockTimeoutMs, }; + const service = createServiceSession({ + env, + notify: (line) => stderr.write(line), + now: serviceNow, + }); if (argv[0] === "login" || argv[0] === "logout") { return (argv[0] === "login" ? runLogin : runLogout)({ @@ -662,7 +862,6 @@ export async function run({ fetchFunction, createRequestSignal, credentials, - hostname, loginSleep, loginNow, startLoopbackServer, @@ -670,6 +869,35 @@ export async function run({ apiToken, stagingApiToken, staging, + service, + }); + } + + if ( + argv[0] === "account" || + argv[0] === "report" || + argv[0] === "conversation" + ) { + const commands = { + account: runAccount, + report: runReport, + conversation: runConversation, + }; + return commands[argv[0]]({ + argv: argv.slice(1), + stdout, + stderr, + cwd, + getCwd, + fetchFunction, + planPushFileSystem, + createRequestSignal, + apiUrl, + apiToken, + stagingApiToken, + staging, + credentials, + service, }); } @@ -712,6 +940,7 @@ export async function run({ stagingApiToken, staging, credentials, + service, }); } @@ -732,6 +961,7 @@ export async function run({ stagingApiToken, staging, credentials, + service, }); } @@ -811,6 +1041,7 @@ async function runPlan({ stagingApiToken, staging, credentials, + service, }) { if (argv[0] === "init") { return runPlanInit({ @@ -838,6 +1069,7 @@ async function runPlan({ stagingApiToken, staging, credentials, + service, }); } @@ -857,6 +1089,7 @@ async function runPlan({ stagingApiToken, staging, credentials, + service, }); } @@ -885,6 +1118,7 @@ async function runPlan({ stagingApiToken, staging, credentials, + service, }); } @@ -933,6 +1167,7 @@ async function runCompilation({ stagingApiToken, staging, credentials, + service, }) { if (argv[0] === "status") { return runCompilationStatus({ @@ -950,6 +1185,7 @@ async function runCompilation({ stagingApiToken, staging, credentials, + service, }); } @@ -967,6 +1203,7 @@ async function runCompilation({ stagingApiToken, staging, credentials, + service, }); } @@ -984,6 +1221,7 @@ async function runCompilation({ stagingApiToken, staging, credentials, + service, }); } @@ -1016,7 +1254,7 @@ async function runCompilation({ } /** - * @param {Pick} options + * @param {Pick} options */ async function runCompilationStatus({ argv, @@ -1033,6 +1271,7 @@ async function runCompilationStatus({ stagingApiToken, staging, credentials, + service, }) { const parsed = parseArguments(() => parseArgs({ @@ -1072,7 +1311,7 @@ async function runCompilationStatus({ try { const authentication = authenticateApiCommand({ - fetchFunction, + fetchFunction: service.fetch(fetchFunction), apiUrl, apiToken, stagingApiToken, @@ -1083,16 +1322,18 @@ async function runCompilationStatus({ writeAuthenticationRequired(stderr); return 1; } - const result = await readCompilation({ - cwd, - compilationId, - wait: parsed.values.wait, - fetchFunction: authentication.fetchFunction, - fileSystem: planPushFileSystem, - createRequestSignal, - sleep: compilationSleep, - now: compilationNow, - }); + const result = await service.settle( + readCompilation({ + cwd, + compilationId, + wait: parsed.values.wait, + fetchFunction: authentication.fetchFunction, + fileSystem: planPushFileSystem, + createRequestSignal, + sleep: compilationSleep, + now: compilationNow, + }), + ); writeJson(stdout, result); return 0; } catch (error) { @@ -1103,7 +1344,7 @@ async function runCompilationStatus({ } /** - * @param {Pick} options + * @param {Pick} options */ async function runCompilationDownload({ argv, @@ -1118,6 +1359,7 @@ async function runCompilationDownload({ stagingApiToken, staging, credentials, + service, }) { const parsed = parseArguments(() => parseArgs({ @@ -1163,7 +1405,7 @@ async function runCompilationDownload({ try { const authentication = authenticateApiCommand({ - fetchFunction, + fetchFunction: service.fetch(fetchFunction), apiUrl, apiToken, stagingApiToken, @@ -1174,14 +1416,16 @@ async function runCompilationDownload({ writeAuthenticationRequired(stderr); return 1; } - const result = await downloadCompilation({ - cwd, - compilationId, - output, - fetchFunction: authentication.fetchFunction, - fileSystem: planPushFileSystem, - createRequestSignal, - }); + const result = await service.settle( + downloadCompilation({ + cwd, + compilationId, + output, + fetchFunction: authentication.fetchFunction, + fileSystem: planPushFileSystem, + createRequestSignal, + }), + ); writeJson(stdout, result); return 0; } catch (error) { @@ -1253,7 +1497,7 @@ async function runCompilationDownload({ } /** - * @param {Pick} options + * @param {Pick} options */ async function runCompilationCancel({ argv, @@ -1268,6 +1512,7 @@ async function runCompilationCancel({ stagingApiToken, staging, credentials, + service, }) { const parsed = parseArguments(() => parseArgs({ @@ -1306,7 +1551,7 @@ async function runCompilationCancel({ try { const authentication = authenticateApiCommand({ - fetchFunction, + fetchFunction: service.fetch(fetchFunction), apiUrl, apiToken, stagingApiToken, @@ -1317,16 +1562,21 @@ async function runCompilationCancel({ writeAuthenticationRequired(stderr); return 1; } - const result = await cancelCompilation({ - cwd, - compilationId, - fetchFunction: authentication.fetchFunction, - fileSystem: planPushFileSystem, - createRequestSignal, - }); + const result = await service.settle( + cancelCompilation({ + cwd, + compilationId, + fetchFunction: authentication.fetchFunction, + fileSystem: planPushFileSystem, + createRequestSignal, + }), + ); writeJson(stdout, result); return 0; } catch (error) { + const stopStatus = writeServiceStop(stderr, error); + if (stopStatus !== null) return stopStatus; + if (error instanceof CompilationCancelRejectedError) { if (isAuthenticationProblem(error.status, error.response)) { writeAuthenticationRequired(stderr, error.status, error.response); @@ -1377,6 +1627,9 @@ function writeCompilationInvalidArguments(writer, detail) { * @param {boolean} [throwUnknown] */ function writeCompilationReadError(writer, error, throwUnknown = true) { + const stopStatus = writeServiceStop(writer, error); + if (stopStatus !== null) return stopStatus; + if (error instanceof ApiAuthenticationRequiredError) { writeAuthenticationRequired(writer); return 1; @@ -1463,7 +1716,6 @@ async function runLogin({ fetchFunction, createRequestSignal, credentials, - hostname, loginSleep, loginNow, startLoopbackServer, @@ -1471,6 +1723,7 @@ async function runLogin({ apiToken, stagingApiToken, staging, + service, }) { const parsed = parseArguments(() => parseArgs({ @@ -1511,19 +1764,23 @@ async function runLogin({ if (origin === null) return 2; try { - await login({ - origin, - device: parsed.values.interactive || parsed.values.device, - prompt: (text) => stderr.write(text), - fetchFunction, - createRequestSignal, - sleep: loginSleep, - now: loginNow, - hostname, - startLoopback: startLoopbackServer, - credentials, - }); + await service.settle( + login({ + origin, + device: parsed.values.interactive || parsed.values.device, + prompt: (text) => stderr.write(text), + fetchFunction: service.fetch(fetchFunction), + createRequestSignal, + sleep: loginSleep, + now: loginNow, + startLoopback: startLoopbackServer, + credentials, + }), + ); } catch (error) { + const stopStatus = writeServiceStop(stderr, error); + if (stopStatus !== null) return stopStatus; + if (error instanceof LoginDeniedError) { writeJson(stderr, { error: "authorization_denied", @@ -1579,6 +1836,7 @@ async function runLogout({ apiToken, stagingApiToken, staging, + service, }) { const parsed = parseArguments(() => parseArgs({ @@ -1614,14 +1872,19 @@ async function runLogout({ let result; try { + // Logout removes the local token whatever First Draft answers, so a stop + // never replaces its result; a refused revocation is reported as one + // that First Draft did not confirm. result = await logout({ origin, - fetchFunction, + fetchFunction: service.fetch(fetchFunction), createRequestSignal, credentials, }); + service.flush(); } catch (error) { if (!(error instanceof LogoutFailedError)) throw error; + service.flush(); writeJson(stderr, { error: "logout_failed", @@ -1841,7 +2104,7 @@ function runGenerateApplicationKey({ argv, stdout, stderr }) { } /** - * @param {Pick} options + * @param {Pick} options */ async function runPlanPush({ argv, @@ -1857,6 +2120,7 @@ async function runPlanPush({ stagingApiToken, staging, credentials, + service, }) { const parsed = parseArguments(() => parseArgs({ @@ -1887,7 +2151,7 @@ async function runPlanPush({ let result; try { const authentication = authenticateApiCommand({ - fetchFunction, + fetchFunction: service.fetch(fetchFunction), apiUrl, apiToken, stagingApiToken, @@ -1898,15 +2162,20 @@ async function runPlanPush({ writeAuthenticationRequired(stderr); return 1; } - result = await pushPlan({ - cwd, - apiUrl: authentication.apiUrl, - fetchFunction: authentication.fetchFunction, - fileSystem: planPushFileSystem, - createTemporaryId, - createRequestSignal, - }); + result = await service.settle( + pushPlan({ + cwd, + apiUrl: authentication.apiUrl, + fetchFunction: authentication.fetchFunction, + fileSystem: planPushFileSystem, + createTemporaryId, + createRequestSignal, + }), + ); } catch (error) { + const stopStatus = writeServiceStop(stderr, error); + if (stopStatus !== null) return stopStatus; + if (error instanceof ApiAuthenticationRequiredError) { writeAuthenticationRequired(stderr); return 1; @@ -1988,7 +2257,7 @@ async function runPlanPush({ } /** - * @param {Pick} options + * @param {Pick} options */ async function runPlanStatus({ argv, @@ -2005,6 +2274,7 @@ async function runPlanStatus({ stagingApiToken, staging, credentials, + service, }) { const parsed = parseArguments(() => parseArgs({ @@ -2036,7 +2306,7 @@ async function runPlanStatus({ let result; try { const authentication = authenticateApiCommand({ - fetchFunction, + fetchFunction: service.fetch(fetchFunction), apiUrl, apiToken, stagingApiToken, @@ -2047,16 +2317,21 @@ async function runPlanStatus({ writeAuthenticationRequired(stderr); return 1; } - result = await readPlanStatus({ - cwd, - wait: parsed.values.wait, - fetchFunction: authentication.fetchFunction, - fileSystem: planPushFileSystem, - createRequestSignal, - sleep: planStatusSleep, - now: planStatusNow, - }); + result = await service.settle( + readPlanStatus({ + cwd, + wait: parsed.values.wait, + fetchFunction: authentication.fetchFunction, + fileSystem: planPushFileSystem, + createRequestSignal, + sleep: planStatusSleep, + now: planStatusNow, + }), + ); } catch (error) { + const stopStatus = writeServiceStop(stderr, error); + if (stopStatus !== null) return stopStatus; + if (error instanceof ApiAuthenticationRequiredError) { writeAuthenticationRequired(stderr); return 1; @@ -2154,7 +2429,7 @@ async function runPlanStatus({ } /** - * @param {Pick} options + * @param {Pick} options */ async function runPlanCompile({ argv, @@ -2180,6 +2455,7 @@ async function runPlanCompile({ stagingApiToken, staging, credentials, + service, }) { const parsed = parseArguments(() => parseArgs({ @@ -2221,7 +2497,7 @@ async function runPlanCompile({ let authentication; try { authentication = authenticateApiCommand({ - fetchFunction, + fetchFunction: service.fetch(fetchFunction), apiUrl, apiToken, stagingApiToken, @@ -2252,13 +2528,15 @@ async function runPlanCompile({ }; if (!github) { try { - const result = await compilePlanToDirectory({ - ...shared, - output: output ?? ".", - compilationSleep, - compilationNow, - compile: planCompileDownload, - }); + const result = await service.settle( + compilePlanToDirectory({ + ...shared, + output: output ?? ".", + compilationSleep, + compilationNow, + compile: planCompileDownload, + }), + ); writeJson(stdout, result); return 0; } catch (error) { @@ -2267,12 +2545,14 @@ async function runPlanCompile({ } try { - const result = await compilePlanToGitHub({ - ...shared, - publicationSleep: planPublishSleep, - publicationNow: planPublishNow, - publish: planCompilePublish, - }); + const result = await service.settle( + compilePlanToGitHub({ + ...shared, + publicationSleep: planPublishSleep, + publicationNow: planPublishNow, + publish: planCompilePublish, + }), + ); const repository = /** @type {NonNullable} */ ( result.publication.repository @@ -2286,6 +2566,9 @@ async function runPlanCompile({ /** @param {Writer} writer @param {unknown} error */ function writePlanCompileError(writer, error) { + const stopStatus = writeServiceStop(writer, error); + if (stopStatus !== null) return stopStatus; + if (error instanceof ApiAuthenticationRequiredError) { writeAuthenticationRequired(writer); return 1; @@ -2837,38 +3120,773 @@ function runPlanInit({ return 0; } -/** @param {unknown} value */ -function parseUuidCount(value) { - if (value === undefined) return 1; - if (typeof value !== "string" || !/^[1-9][0-9]*$/.test(value)) return null; +/** @param {ServiceCommandOptions} options */ +async function runAccount({ + argv, + stdout, + stderr, + fetchFunction, + createRequestSignal, + credentials, + apiUrl, + apiToken, + stagingApiToken, + staging, + service, +}) { + const parsed = parseArguments(() => + parseArgs({ + args: [...argv], + options: { + staging: { type: "boolean" }, + help: { type: "boolean", short: "h" }, + }, + allowPositionals: false, + strict: true, + tokens: true, + }), + ); - const count = Number(value); - return Number.isSafeInteger(count) ? count : null; -} + if (!parsed || repeatedValueOption(parsed.tokens)) { + writeJson(stderr, { + error: "invalid_arguments", + detail: ACCOUNT_INVALID_ARGUMENTS_DETAIL, + }); + return 2; + } + + if (parsed.values.help) { + stdout.write(ACCOUNT_HELP); + return 0; + } + + const authentication = authenticateAccountCommand(stderr, { + fetchFunction, + credentials, + apiUrl, + apiToken, + stagingApiToken, + staging: staging || parsed.values.staging, + service, + }); + if (typeof authentication === "number") return authentication; -/** - * @template T - * @param {() => T} callback - * @returns {T | null} - */ -function parseArguments(callback) { try { - return callback(); + const account = await service.settle( + readAccount({ + origin: authentication.origin, + fetchFunction: authentication.fetchFunction, + createRequestSignal, + }), + ); + writeJson(stdout, account); + return 0; } catch (error) { - if (!isParseArgsError(error)) throw error; + const status = writeAccountCommandError(stderr, error); + if (status !== null) return status; - return null; + if (error instanceof AccountUnavailableError) { + if (isAuthenticationProblem(error.status, error.response)) { + writeAuthenticationRequired(stderr, error.status, error.response); + return 1; + } + writeJson(stderr, { + error: "account_unavailable", + detail: ACCOUNT_UNAVAILABLE_DETAIL, + ...(typeof error.status === "number" ? { status: error.status } : {}), + ...(error.response ? { response: error.response } : {}), + }); + return 1; + } + + if (error instanceof AccountResponseInvalidError) { + writeJson(stderr, { + error: "invalid_server_response", + detail: ACCOUNT_INVALID_RESPONSE_DETAIL, + status: error.status, + }); + return 1; + } + + throw error; + } +} + +/** @param {ServiceCommandOptions} options */ +async function runReport(options) { + const [command, ...rest] = options.argv; + if (command === "progress") { + return runReportProgress({ ...options, argv: rest }); } + if (command === "failure") { + return runReportFailure({ ...options, argv: rest }); + } + + return runCommandGroup(options, "report", REPORT_HELP); } -/** @param {readonly {kind: string, name?: string}[]} tokens */ -function repeatedValueOption(tokens) { +/** @param {ServiceCommandOptions} options */ +async function runReportProgress(options) { + const { argv, stdout, stderr, staging } = options; + const parsed = parseArguments(() => + parseArgs({ + args: [...argv], + options: { + staging: { type: "boolean" }, + step: { type: "string" }, + examples: { type: "string" }, + failures: { type: "string" }, + "behavior-to-write-failures": { type: "string" }, + "items-remaining": { type: "string" }, + help: { type: "boolean", short: "h" }, + }, + allowPositionals: true, + strict: true, + tokens: true, + }), + ); + + const invalid = () => { + writeJson(stderr, { + error: "invalid_arguments", + detail: REPORT_PROGRESS_INVALID_ARGUMENTS_DETAIL, + }); + return 2; + }; + if (!parsed || repeatedValueOption(parsed.tokens)) return invalid(); + + if (parsed.values.help) { + stdout.write(REPORT_PROGRESS_HELP); + return 0; + } + + const [compilationId] = parsed.positionals; + const { step } = parsed.values; + /** @type {Record} */ + const counts = {}; + for (const [option, key] of /** @type {const} */ ([ + ["examples", "examples"], + ["failures", "failures"], + ["behavior-to-write-failures", "behavior_to_write_failures"], + ["items-remaining", "items_remaining"], + ])) { + const value = parsed.values[option]; + if (value === undefined) continue; + const count = parseReportCount(value); + if (count === null) return invalid(); + counts[key] = count; + } + if ( + parsed.positionals.length !== 1 || + !isUuidV7(compilationId) || + step === undefined || + !PROGRESS_STEPS.includes(step) + ) { + return invalid(); + } + + return sendReportCommand( + { ...options, staging: staging || parsed.values.staging }, + { + noun: "progress report", + wrapper: "progress_report", + route: SERVICE_ROUTES.sendProgressReport, + compilationId, + body: () => ({ body: progressReportBody(step, counts), omitted: [] }), + }, + ); +} + +/** @param {ServiceCommandOptions} options */ +async function runReportFailure(options) { + const { argv, stdout, stderr, staging } = options; + const parsed = parseArguments(() => + parseArgs({ + args: [...argv], + options: { + staging: { type: "boolean" }, + kind: { type: "string" }, + rerun: { type: "string" }, + "error-class": { type: "string" }, + message: { type: "string" }, + frame: { type: "string", multiple: true }, + "fix-summary": { type: "string" }, + "ruby-version": { type: "string" }, + "rails-version": { type: "string" }, + help: { type: "boolean", short: "h" }, + }, + allowPositionals: true, + strict: true, + tokens: true, + }), + ); + + const invalid = () => { + writeJson(stderr, { + error: "invalid_arguments", + detail: REPORT_FAILURE_INVALID_ARGUMENTS_DETAIL, + }); + return 2; + }; + if (!parsed || repeatedValueOption(parsed.tokens, ["frame"])) { + return invalid(); + } + + if (parsed.values.help) { + stdout.write(REPORT_FAILURE_HELP); + return 0; + } + + const [compilationId] = parsed.positionals; + const { + kind, + rerun, + "error-class": errorClass, + message, + frame: frames, + "fix-summary": fixSummary, + "ruby-version": rubyVersion, + "rails-version": railsVersion, + } = parsed.values; + if ( + parsed.positionals.length !== 1 || + !isUuidV7(compilationId) || + kind === undefined || + !FAILURE_KINDS.includes(kind) + ) { + return invalid(); + } + + return sendReportCommand( + { ...options, staging: staging || parsed.values.staging }, + { + noun: "failure report", + wrapper: "failure_report", + route: SERVICE_ROUTES.sendFailureReport, + compilationId, + body: (cwd) => + failureReportBody( + { + kind, + rerun, + errorClass, + message, + frames, + fixSummary, + rubyVersion, + railsVersion, + }, + cwd, + ), + }, + ); +} + +/** + * @param {string} value + * @returns {number | null} null when the value is not a count + */ +function parseReportCount(value) { + if (!/^(?:0|[1-9][0-9]*)$/.test(value)) return null; + + const count = Number(value); + return count <= MAX_REPORT_COUNT ? count : null; +} + +// First Draft refuses a larger count. +const MAX_REPORT_COUNT = 1_000_000; + +/** + * Prints the exact report, then sends those bytes once to the Project's + * pinned origin. + * + * @param {ServiceCommandOptions} options + * @param {{noun: string, wrapper: string, route: {method: string, path: string}, compilationId: string, body: (cwd: string) => {body: unknown, omitted: string[]}}} report + */ +async function sendReportCommand( + options, + { noun, wrapper, route, compilationId, body }, +) { + const { stdout, stderr, createRequestSignal, service } = options; + try { + const pinned = authenticatePinnedProject(options); + if (pinned === null) { + writeAuthenticationRequired(stderr); + return 1; + } + + const shaped = body(pinned.cwd); + const text = `${JSON.stringify(shaped.body, null, 2)}\n`; + stdout.write( + `Sending this ${noun} for Compilation ${compilationId} to ${pinned.apiUrl}:\n${text}` + + (shaped.omitted.length === 0 + ? "" + : `Left out: ${shaped.omitted.join("; ")}.\n`), + ); + const { outcome } = await service.settle( + sendReport({ + origin: pinned.apiUrl, + route, + projectId: pinned.projectId, + compilationId, + body: text, + wrapper, + fetchFunction: pinned.fetchFunction, + createRequestSignal, + }), + ); + stdout.write(outcome === "sent" ? "Sent.\n" : REPORTS_OFF_MESSAGE); + return 0; + } catch (error) { + const status = writePinnedProjectError(stderr, error); + if (status !== null) return status; + + if (error instanceof ReportRejectedError) { + if (isAuthenticationProblem(error.status, error.response)) { + writeAuthenticationRequired(stderr, error.status, error.response); + return 1; + } + writeJson(stderr, { + error: "report_rejected", + detail: REPORT_REJECTED_DETAIL, + status: error.status, + response: error.response, + }); + return 1; + } + + if (error instanceof ReportUnavailableError) { + writeJson(stderr, { + error: "report_unavailable", + detail: REPORT_UNAVAILABLE_DETAIL, + ...(typeof error.status === "number" ? { status: error.status } : {}), + ...(error.response ? { response: error.response } : {}), + }); + return 1; + } + + throw error; + } +} + +/** @param {ServiceCommandOptions} options */ +async function runConversation(options) { + const [command, ...rest] = options.argv; + if (command === "send") { + return runConversationSend({ ...options, argv: rest }); + } + + return runCommandGroup(options, "conversation", CONVERSATION_HELP); +} + +/** @param {ServiceCommandOptions} options */ +async function runConversationSend(options) { + const { argv, stdout, stderr, staging, createRequestSignal, service } = + options; + const parsed = parseArguments(() => + parseArgs({ + args: [...argv], + options: { + staging: { type: "boolean" }, + "person-agreed": { type: "boolean" }, + help: { type: "boolean", short: "h" }, + }, + allowPositionals: true, + strict: true, + tokens: true, + }), + ); + + const [file] = parsed?.positionals ?? []; + if ( + !parsed || + repeatedValueOption(parsed.tokens) || + (!parsed.values.help && (parsed.positionals.length !== 1 || !file)) + ) { + writeJson(stderr, { + error: "invalid_arguments", + detail: CONVERSATION_SEND_INVALID_ARGUMENTS_DETAIL, + }); + return 2; + } + + if (parsed.values.help) { + stdout.write(CONVERSATION_SEND_HELP); + return 0; + } + + if (!parsed.values["person-agreed"]) { + writeJson(stderr, { + error: "consent_required", + detail: CONVERSATION_CONSENT_REQUIRED_DETAIL, + }); + return 2; + } + + try { + const pinned = authenticatePinnedProject({ + ...options, + staging: staging || parsed.values.staging, + }); + if (pinned === null) { + writeAuthenticationRequired(stderr); + return 1; + } + + const conversation = readConversationFile({ + cwd: pinned.cwd, + file: /** @type {string} */ (file), + }); + stdout.write( + `Sending ${conversation.path} (${conversation.bytes.byteLength} bytes, SHA-256 ${conversation.sha256}) ` + + `for Project ${pinned.projectId} to ${pinned.apiUrl}.\n`, + ); + await service.settle( + sendConversation({ + apiUrl: pinned.apiUrl, + projectId: pinned.projectId, + conversation, + fetchFunction: pinned.fetchFunction, + createRequestSignal, + }), + ); + stdout.write("Sent.\n"); + return 0; + } catch (error) { + const status = writePinnedProjectError(stderr, error); + if (status !== null) return status; + + if (error instanceof ConversationFileError) { + writeJson(stderr, { + error: "conversation_unreadable", + detail: CONVERSATION_UNREADABLE_DETAIL, + reason: error.reason, + }); + return 1; + } + + if (error instanceof ConversationRejectedError) { + if (isAuthenticationProblem(error.status, error.response)) { + writeAuthenticationRequired(stderr, error.status, error.response); + return 1; + } + writeJson(stderr, { + error: "conversation_rejected", + detail: CONVERSATION_REJECTED_DETAIL, + status: error.status, + response: error.response, + }); + return 1; + } + + if (error instanceof ConversationUnavailableError) { + writeJson(stderr, { + error: "conversation_unavailable", + detail: CONVERSATION_UNAVAILABLE_DETAIL, + ...(typeof error.status === "number" ? { status: error.status } : {}), + ...(error.response ? { response: error.response } : {}), + }); + return 1; + } + + throw error; + } +} + +/** + * Reads the Project that a successful push pinned and authenticates its + * origin, before a command prints what it will send there. Returns null when + * no token is available for that origin. + * + * @param {ServiceCommandOptions} options + */ +function authenticatePinnedProject({ + cwd, + getCwd, + fetchFunction, + credentials, + apiUrl, + apiToken, + stagingApiToken, + staging, + service, +}) { + const authentication = authenticateApiCommand({ + fetchFunction: service.fetch(fetchFunction), + apiUrl, + apiToken, + stagingApiToken, + staging, + readStoredTokens: storedTokenReader(credentials), + }); + if (authentication === null) return null; + + const directory = cwd ?? getCwd(); + const project = readPinnedProject({ cwd: directory }); + if (staging && project.apiUrl !== STAGING_API_URL) { + throw new PlanPushConfigurationError( + "The requested API environment does not match the Project origin. No request was made.", + ); + } + if (!authentication.hasTokenFor(project.apiUrl)) return null; + + return { + cwd: directory, + ...project, + fetchFunction: authentication.fetchFunction, + }; +} + +/** + * The local and environment errors of a command that sends to the pinned + * Project. + * + * @param {Writer} writer + * @param {unknown} error + */ +function writePinnedProjectError(writer, error) { + const status = writeAccountCommandError(writer, error); + if (status !== null) return status; + + if (error instanceof PlanPushLocalError) { + writeJson(writer, { + error: "local_input_unreadable", + detail: PINNED_LOCAL_INPUT_UNREADABLE_DETAIL, + }); + return 1; + } + + if (error instanceof PlanStateNotPushedError) { + writeJson(writer, { + error: "project_not_pushed", + detail: PINNED_NOT_PUSHED_DETAIL, + }); + return 1; + } + + return null; +} + +/** + * Prints a command group's help, or its usage error for anything else. + * + * @param {Pick} options + * @param {string} group + * @param {string} help + */ +function runCommandGroup({ argv, stdout, stderr }, group, help) { + const parsed = parseArguments(() => + parseArgs({ + args: [...argv], + options: { help: { type: "boolean", short: "h" } }, + allowPositionals: true, + strict: true, + }), + ); + + if (!parsed || parsed.positionals.length > 0) { + stderr.write( + `${parsed ? "Unknown command." : "Invalid arguments."}\nRun 'firstdraft ${group} --help' for usage.\n`, + ); + return 2; + } + + stdout.write(help); + return 0; +} + +/** + * Selects the origin as login does (--staging, else FIRSTDRAFT_API_URL, else + * production) for a command that is not tied to a Project, and authenticates + * it. Returns the exit status when it has already written an error. + * + * @param {Writer} stderr + * @param {Pick} options + * @returns {{origin: string, fetchFunction: typeof globalThis.fetch} | number} + */ +function authenticateAccountCommand( + stderr, + { + fetchFunction, + credentials, + apiUrl, + apiToken, + stagingApiToken, + staging, + service, + }, +) { + const origin = selectLoginOrigin(stderr, { apiUrl, staging }); + if (origin === null) return 2; + + const authentication = authenticateApiCommand({ + fetchFunction: service.fetch(fetchFunction), + apiUrl: origin, + apiToken, + stagingApiToken, + staging, + readStoredTokens: storedTokenReader(credentials), + }); + // Checked before a report is printed, so a missing token prints nothing. + if (authentication === null || !authentication.hasTokenFor(origin)) { + writeAuthenticationRequired(stderr); + return 1; + } + return { origin, fetchFunction: authentication.fetchFunction }; +} + +/** + * The errors that every account, report, and conversation command handles + * the same way. + * + * @param {Writer} writer + * @param {unknown} error + */ +function writeAccountCommandError(writer, error) { + const stopStatus = writeServiceStop(writer, error); + if (stopStatus !== null) return stopStatus; + + if (error instanceof ApiAuthenticationRequiredError) { + writeAuthenticationRequired(writer); + return 1; + } + + if (error instanceof PlanPushConfigurationError) { + writeJson(writer, { + error: "invalid_configuration", + detail: error.message, + }); + return 2; + } + + return null; +} + +/** + * Writes the error for a response that told the CLI to stop before the + * command finished. A Compilation that had already started is named, so the + * caller follows it instead of starting another. + * + * @param {Writer} writer + * @param {unknown} error + * @returns {number | null} + */ +function writeServiceStop(writer, error) { + if (!(error instanceof ServiceStopError)) return null; + + const current = + error.replaced instanceof CompilationRetainedError + ? error.replaced.current + : undefined; + const update = `Tell the person to update with the steps at ${UPDATE_URL}, then`; + const next = + current === undefined + ? "run the same command again, with the same options." + : "follow the Compilation that had already started with 'firstdraft compilation status " + + `${current.compilation.id}' instead of compiling again.`; + const stopped = + "The CLI stopped before the command finished and sent nothing more."; + + if (error instanceof UpdateRequiredError) { + writeJson(writer, { + error: "update_required", + detail: `${stopSentence(error)} ${stopped} ${update} ${next}`, + ...(error.component === "plugin" + ? { + plugin_version: error.installed, + cli_version: VERSION, + minimum_plugin_version: error.minimum, + } + : { cli_version: VERSION, minimum_cli_version: error.minimum }), + update_url: UPDATE_URL, + ...(current === undefined ? {} : { current }), + }); + return 1; + } + + if (error instanceof ApiContractUnsupportedError) { + writeJson(writer, { + error: "api_contract_unsupported", + detail: + `${stopSentence(error)} ${stopped} ` + + (error.kind === "newer" + ? `${update} ${next}` + : "Use the CLI version that this First Draft origin supports."), + api_contract: error.contract, + accepted_api_contract: API_CONTRACT_RANGE, + cli_version: VERSION, + update_url: UPDATE_URL, + ...(current === undefined ? {} : { current }), + }); + return 1; + } + + const retryAt = error instanceof RateLimitedError ? error.retryAt : undefined; + const limit = error instanceof RateLimitedError ? error.response : null; + // A limit without Retry-After or a problem detail, such as the one shared + // by device logins, lasts about a minute. + const retry = + retryAt !== undefined + ? `Try again after ${retryAt}; response.detail, when present, says which limit.` + : limit + ? "Try again when response.detail says." + : "Try again in a minute."; + writeJson(writer, { + error: "rate_limited", + detail: + `${stopSentence(error)} The refused request did nothing, and the CLI sent nothing after it. ` + + retry + + (current === undefined + ? "" + : ` A Compilation had already started: follow it with 'firstdraft compilation status ${current.compilation.id}' instead of compiling again.`), + status: 429, + ...(error instanceof RateLimitedError && error.retryAt !== undefined + ? { retry_at: error.retryAt } + : {}), + ...(error instanceof RateLimitedError && error.response + ? { response: error.response } + : {}), + ...(current === undefined ? {} : { current }), + }); + return 1; +} + +/** @param {unknown} value */ +function parseUuidCount(value) { + if (value === undefined) return 1; + if (typeof value !== "string" || !/^[1-9][0-9]*$/.test(value)) return null; + + const count = Number(value); + return Number.isSafeInteger(count) ? count : null; +} + +/** + * @template T + * @param {() => T} callback + * @returns {T | null} + */ +function parseArguments(callback) { + try { + return callback(); + } catch (error) { + if (!isParseArgsError(error)) throw error; + + return null; + } +} + +/** + * @param {readonly {kind: string, name?: string}[]} tokens + * @param {readonly string[]} [repeatable] options that may appear more than once + */ +function repeatedValueOption(tokens, repeatable = []) { const names = tokens .filter( (token) => token.kind === "option" && typeof token.name === "string" && - token.name !== "help", + token.name !== "help" && + !repeatable.includes(token.name), ) .map((token) => token.name); diff --git a/src/commands/account.js b/src/commands/account.js new file mode 100644 index 0000000..657d428 --- /dev/null +++ b/src/commands/account.js @@ -0,0 +1,97 @@ +import { + FirstDraftNetworkError, + FirstDraftProtocolError, + SERVICE_ROUTES, + isProblemBody, + problemProjection, + readResponseBody, + responseMediaType, + sendRequest, + serviceEndpoint, +} from "../api-response.js"; + +const REQUEST_TIMEOUT_MS = 30_000; + +export class AccountUnavailableError extends Error { + /** + * @param {number | undefined} status + * @param {Record | null} [response] + */ + constructor(status, response = null) { + super("The account could not be read."); + this.status = status; + this.response = response; + } +} + +export class AccountResponseInvalidError extends Error { + /** @param {number} status */ + constructor(status) { + super("The account response is invalid."); + this.status = status; + } +} + +/** + * @typedef {object} ReadAccountOptions + * @property {string} origin + * @property {typeof globalThis.fetch} [fetchFunction] + * @property {(timeoutMs: number) => AbortSignal} [createRequestSignal] + */ + +/** + * Reads whether the signed-in account sends progress and failure reports. + * Only the person turns reports on, on the login approval page. + * + * @param {ReadAccountOptions} options + * @returns {Promise<{reports: "on" | "off"}>} + */ +export async function readAccount({ + origin, + fetchFunction = globalThis.fetch, + createRequestSignal = (timeoutMs) => AbortSignal.timeout(timeoutMs), +}) { + const endpoint = serviceEndpoint(SERVICE_ROUTES.readAccount, origin, {}); + let response; + let body; + try { + response = await sendRequest(fetchFunction, endpoint, { + headers: { Accept: "application/json, application/problem+json" }, + redirect: "error", + signal: createRequestSignal(REQUEST_TIMEOUT_MS), + }); + body = await readResponseBody(response); + } catch (error) { + if (error instanceof FirstDraftNetworkError) { + throw new AccountUnavailableError(error.status); + } + if (error instanceof FirstDraftProtocolError) { + throw error.status >= 200 && error.status < 300 + ? new AccountResponseInvalidError(error.status) + : new AccountUnavailableError(error.status); + } + throw error; + } + + if (response.status !== 200) { + if (response.ok) throw new AccountResponseInvalidError(response.status); + + throw new AccountUnavailableError( + response.status, + isProblemBody(response, body) ? problemProjection(body) : null, + ); + } + + // Other keys are ignored so the Service can add account facts without + // breaking this command; only the validated value is printed. + if ( + responseMediaType(response) !== "application/json" || + typeof body !== "object" || + body === null || + (body.reports !== "on" && body.reports !== "off") + ) { + throw new AccountResponseInvalidError(response.status); + } + + return { reports: body.reports }; +} diff --git a/src/commands/conversation.js b/src/commands/conversation.js new file mode 100644 index 0000000..23a77a8 --- /dev/null +++ b/src/commands/conversation.js @@ -0,0 +1,186 @@ +import { createHash } from "node:crypto"; +import { readFileSync, statSync } from "node:fs"; +import path from "node:path"; + +import { + FirstDraftNetworkError, + FirstDraftProtocolError, + SERVICE_ROUTES, + isProblemBody, + problemProjection, + readResponseBody, + sendRequest, + serviceEndpoint, +} from "../api-response.js"; +import { isFileSystemError } from "../file-system.js"; + +export const MAX_CONVERSATION_BYTES = 32 * 1024 * 1024; +const REQUEST_TIMEOUT_MS = 120_000; + +/** + * @typedef {object} ConversationFileSystem + * @property {typeof statSync} statSync + * @property {typeof readFileSync} readFileSync + */ + +/** @type {ConversationFileSystem} */ +const DEFAULT_FILE_SYSTEM = { statSync, readFileSync }; + +export class ConversationFileError extends Error { + /** @param {"unreadable" | "empty" | "too_large"} reason @param {{cause?: unknown}} [options] */ + constructor(reason, options = {}) { + super("The conversation file cannot be sent.", { cause: options.cause }); + this.reason = reason; + } +} + +export class ConversationRejectedError extends Error { + /** + * @param {number} status + * @param {Record} response + */ + constructor(status, response) { + super("First Draft rejected the conversation."); + this.status = status; + this.response = response; + } +} + +export class ConversationUnavailableError extends Error { + /** + * @param {number | undefined} status + * @param {Record | null} [response] + */ + constructor(status, response = null) { + super("The conversation upload could not be confirmed."); + this.status = status; + this.response = response; + } +} + +/** + * @typedef {object} Conversation + * @property {string} path absolute path of the file on this computer + * @property {string} name the file's base name, the only part of the path sent + * @property {Buffer} bytes + * @property {string} sha256 + */ + +/** + * Reads the conversation file, so the person can see what will be sent + * before any request. + * + * @param {object} options + * @param {string} options.cwd + * @param {string} options.file + * @param {ConversationFileSystem} [options.fileSystem] + * @returns {Conversation} + */ +export function readConversationFile({ + cwd, + file, + fileSystem = DEFAULT_FILE_SYSTEM, +}) { + const absolute = path.resolve(cwd, file); + let bytes; + try { + const stat = fileSystem.statSync(absolute); + if (!stat.isFile()) throw new ConversationFileError("unreadable"); + if (stat.size > MAX_CONVERSATION_BYTES) { + throw new ConversationFileError("too_large"); + } + bytes = fileSystem.readFileSync(absolute); + } catch (error) { + if (error instanceof ConversationFileError) throw error; + if (!isFileSystemError(error)) throw error; + + throw new ConversationFileError("unreadable", { cause: error }); + } + if (bytes.byteLength > MAX_CONVERSATION_BYTES) { + throw new ConversationFileError("too_large"); + } + if (bytes.byteLength === 0) throw new ConversationFileError("empty"); + + return { + path: absolute, + name: path.basename(absolute), + bytes, + sha256: createHash("sha256").update(bytes).digest("hex"), + }; +} + +/** + * @typedef {object} SendConversationOptions + * @property {string} apiUrl + * @property {string} projectId + * @property {Conversation} conversation + * @property {typeof globalThis.fetch} [fetchFunction] + * @property {(timeoutMs: number) => AbortSignal} [createRequestSignal] + */ + +/** + * Uploads the file's bytes unchanged, once, as the `conversation[file]` part + * of a multipart form. Nothing is retried: First Draft may already hold the + * file when the outcome is unconfirmed. + * + * @param {SendConversationOptions} options + * @returns {Promise<{outcome: "sent"}>} + */ +export async function sendConversation({ + apiUrl, + projectId, + conversation, + fetchFunction = globalThis.fetch, + createRequestSignal = (timeoutMs) => AbortSignal.timeout(timeoutMs), +}) { + const endpoint = serviceEndpoint(SERVICE_ROUTES.sendConversation, apiUrl, { + project_id: projectId, + }); + const form = new FormData(); + form.append( + "conversation[file]", + new Blob([conversation.bytes], { type: "application/octet-stream" }), + conversation.name, + ); + + let response; + try { + response = await sendRequest(fetchFunction, endpoint, { + headers: { Accept: "application/json, application/problem+json" }, + body: form, + redirect: "error", + signal: createRequestSignal(REQUEST_TIMEOUT_MS), + }); + } catch (error) { + if (error instanceof FirstDraftNetworkError) { + throw new ConversationUnavailableError(error.status); + } + throw error; + } + + if (response.ok) { + await response.body?.cancel().catch(() => undefined); + return { outcome: "sent" }; + } + + let body; + try { + body = await readResponseBody(response); + } catch (error) { + if ( + error instanceof FirstDraftNetworkError || + error instanceof FirstDraftProtocolError + ) { + throw new ConversationUnavailableError(response.status); + } + throw error; + } + + const problem = isProblemBody(response, body) + ? problemProjection(body) + : null; + if (problem !== null && response.status !== 408 && response.status < 500) { + throw new ConversationRejectedError(response.status, problem); + } + throw new ConversationUnavailableError(response.status, problem); +} diff --git a/src/commands/login.js b/src/commands/login.js index 7d509f0..a2d6bcb 100644 --- a/src/commands/login.js +++ b/src/commands/login.js @@ -1,4 +1,3 @@ -import { hostname as osHostname } from "node:os"; import { setTimeout as delay } from "node:timers/promises"; import { @@ -27,8 +26,6 @@ import { import { normalizeApiUrl } from "../plan-state.js"; import { DEFAULT_API_URL } from "./plan-push.js"; -const MAX_DEVICE_NAME_LENGTH = 100; - export class LoginDeniedError extends Error {} export class LoginExpiredError extends Error {} @@ -67,7 +64,6 @@ export function resolveLoginOrigin({ apiUrl, staging = false }) { * @property {(timeoutMs?: number) => AbortSignal} [createRequestSignal] * @property {(delayMs: number, signal?: AbortSignal) => Promise} [sleep] * @property {() => number} [now] - * @property {() => string} [hostname] * @property {import("../oauth.js").StartLoopbackServer} [startLoopback] * @property {import("../credentials.js").CredentialStore} [credentials] */ @@ -86,14 +82,12 @@ export async function login({ createRequestSignal, sleep = defaultSleep, now = Date.now, - hostname = osHostname, startLoopback = startLoopbackServer, credentials = {}, }) { // Reject an unreadable or invalid store before any network request. // A later write can still fail after a token has been issued. readStore(credentials); - const deviceName = safeDeviceName(hostname); const request = { origin, fetchFunction, createRequestSignal }; /** @param {import("../oauth.js").AccessToken} token */ @@ -111,11 +105,10 @@ export async function login({ try { if (device) { - save(await deviceLogin({ ...request, deviceName, prompt, sleep, now })); + save(await deviceLogin({ ...request, prompt, sleep, now })); } else { await browserLogin({ ...request, - deviceName, prompt, sleep, startLoopback, @@ -130,7 +123,6 @@ export async function login({ /** * @param {import("../oauth.js").RequestOptions & { - * deviceName: string | undefined, * prompt: (text: string) => void, * sleep: (delayMs: number, signal?: AbortSignal) => Promise, * startLoopback: import("../oauth.js").StartLoopbackServer, @@ -138,7 +130,6 @@ export async function login({ * }} options */ async function browserLogin({ - deviceName, prompt, sleep, startLoopback, @@ -165,7 +156,6 @@ async function browserLogin({ redirectUri: listener.redirectUri, state, challenge, - deviceName, }); prompt( `To log in to ${request.origin}, open this URL in your browser:\n\n ${url}\n\n` + @@ -210,17 +200,13 @@ async function browserLogin({ /** * @param {import("../oauth.js").RequestOptions & { - * deviceName: string | undefined, * prompt: (text: string) => void, * sleep: (delayMs: number) => Promise, * now: () => number, * }} options */ -async function deviceLogin({ deviceName, prompt, sleep, now, ...request }) { - const authorization = await requestDeviceAuthorization({ - ...request, - deviceName, - }); +async function deviceLogin({ prompt, sleep, now, ...request }) { + const authorization = await requestDeviceAuthorization(request); prompt( `To log in to ${request.origin}, open this URL in a browser on any device:\n\n` + ` ${authorization.verificationUri}\n\n` + @@ -293,21 +279,6 @@ function loginError(error) { }); } -/** @param {() => string} hostname */ -function safeDeviceName(hostname) { - let name; - try { - name = hostname(); - } catch { - return undefined; - } - // eslint-disable-next-line no-control-regex - const cleaned = name.replace(/[\u0000-\u001f\u007f]/g, "").trim(); - return cleaned.length === 0 - ? undefined - : cleaned.slice(0, MAX_DEVICE_NAME_LENGTH); -} - /** @param {number} delayMs @param {AbortSignal} [signal] */ function defaultSleep(delayMs, signal) { return delay(delayMs, undefined, { signal }); diff --git a/src/commands/report.js b/src/commands/report.js new file mode 100644 index 0000000..2623b8f --- /dev/null +++ b/src/commands/report.js @@ -0,0 +1,463 @@ +import { + FirstDraftNetworkError, + FirstDraftProtocolError, + isProblemBody, + problemProjection, + readResponseBody, + responseMediaType, + sendRequest, + serviceEndpoint, +} from "../api-response.js"; + +const REQUEST_TIMEOUT_MS = 30_000; + +export const PROGRESS_STEPS = Object.freeze([ + "setup", + "specs_first_run", + "behavior_written", + "specs_passing", + "preview_started", +]); +export const FAILURE_KINDS = Object.freeze([ + "spec_failure", + "setup_failure", + "boot_error", + "lint_failure", +]); +const MAX_FAILURE_FRAMES = 20; + +// A failure report carries only fields of a known shape. Free text keeps +// plain words, and anything that does not fit its shape is left out, so the +// rules say what may leave the computer rather than guessing what a secret +// looks like. The Service refuses the same shapes. +const MAX_MESSAGE = 300; +const MAX_FIX_SUMMARY = 200; +const MAX_ERROR_CLASS = 200; +const MAX_RERUN = 300; +const MAX_FRAME = 300; +const MAX_VERSION = 32; +// Components of safe characters, each separated by one slash. +const SAFE_PATH = String.raw`[A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)*`; +// bundle exec rspec ./spec/models/post_spec.rb:42, bin/rspec spec/x_spec.rb +const RERUN = new RegExp( + String.raw`^(?:bundle exec |bin/)?rspec(?: (?:\./)?spec/${SAFE_PATH}(?::\d{1,7})*)+$`, +); +const ERROR_CLASS = /^(?:::)?[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*$/; +const FRAME = new RegExp( + String.raw`^(?:\./)?((?:app|lib|config|db|spec)/${SAFE_PATH}):(\d{1,7})(?::in .*)?$`, +); +// Checked in every argument and frame: spec/.. spec/models has one too. +const PARENT_SEGMENT = /(?:^|[/\s:])\.\.(?=[/\s:]|$)/; +// 4.0.6, 8.1.4.1, 8.2.0.beta1, 3.4.0-preview2 +const VERSION_NUMBER = + /^\d{1,4}(?:\.\d{1,4}){0,3}(?:[.-](?:alpha|beta|rc|pre|preview)\d{0,3})?$/; +const ASSIGNMENT_WORD = /^[A-Za-z_][A-Za-z0-9_]*=/; +// eslint-disable-next-line no-control-regex +const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g; +// Quotes are not paired: from the word holding the first one, the rest of the +// line is one placeholder, so no quoted value survives. +const QUOTE = /['"`]/; +// A word that can carry a value: an assignment, a path or URL, an address, +// or anything long enough to be a token. +const VALUE_WORD = /[=/\\@]/; +const MAX_PLAIN_WORD = 24; +const PLACEHOLDER = "[…]"; + +export class ReportRejectedError extends Error { + /** + * @param {number} status + * @param {Record} response + */ + constructor(status, response) { + super("First Draft rejected the report."); + this.status = status; + this.response = response; + } +} + +export class ReportUnavailableError extends Error { + /** + * @param {number | undefined} status + * @param {Record | null} [response] + */ + constructor(status, response = null) { + super("The report's outcome could not be confirmed."); + this.status = status; + this.response = response; + } +} + +/** + * @typedef {object} ProgressCounts + * @property {number} [examples] + * @property {number} [failures] + * @property {number} [behavior_to_write_failures] + * @property {number} [items_remaining] + */ + +/** + * @param {string} step one of PROGRESS_STEPS + * @param {ProgressCounts} counts only the counts that were given + */ +export function progressReportBody(step, counts) { + return { + progress_report: { + step, + ...(Object.keys(counts).length === 0 ? {} : { counts }), + }, + }; +} + +/** + * @typedef {object} FailureReport + * @property {string} kind one of FAILURE_KINDS + * @property {string} [rerun] + * @property {string} [errorClass] + * @property {string} [message] + * @property {readonly string[]} [frames] + * @property {string} [fixSummary] + * @property {string} [rubyVersion] + * @property {string} [railsVersion] + */ + +/** + * Shapes the failure report that is printed and sent. Each field keeps only + * what fits its shape; `omitted` says, for the preview, what was left out. + * + * @param {FailureReport} report + * @param {string} cwd an absolute frame inside it becomes relative + */ +export function failureReportBody( + { + kind, + rerun, + errorClass, + message, + frames = [], + fixSummary, + rubyVersion, + railsVersion, + }, + cwd, +) { + /** @type {string[]} */ + const omitted = []; + const shapedRerun = rerun === undefined ? undefined : rspecRun(rerun); + if (rerun !== undefined && shapedRerun === undefined) { + omitted.push("rerun, which is not an RSpec run of the application's specs"); + } + const shapedErrorClass = + errorClass !== undefined && + errorClass.length <= MAX_ERROR_CLASS && + ERROR_CLASS.test(errorClass) + ? errorClass + : undefined; + if (errorClass !== undefined && shapedErrorClass === undefined) { + omitted.push("error_class, which is not a Ruby constant"); + } + const shapedFrames = frames + .map((frame) => appFrame(frame, cwd)) + .filter((frame) => frame !== undefined); + if (shapedFrames.length < frames.length) { + const dropped = frames.length - shapedFrames.length; + omitted.push( + `${dropped} ${dropped === 1 ? "frame" : "frames"} not in the application's files with a line number`, + ); + } + if (shapedFrames.length > MAX_FAILURE_FRAMES) { + omitted.push(`frames after the first ${MAX_FAILURE_FRAMES}`); + } + /** @type {Record} */ + const versions = {}; + for (const [name, value] of /** @type {const} */ ([ + ["ruby", rubyVersion], + ["rails", railsVersion], + ])) { + if (value === undefined) continue; + if (value.length <= MAX_VERSION && VERSION_NUMBER.test(value)) { + versions[name] = value; + } else { + omitted.push(`the ${name} version, which is not a version number`); + } + } + const shapedMessage = + message === undefined ? undefined : plainWords(message, MAX_MESSAGE); + if (message !== undefined && !shapedMessage) { + omitted.push("message, which has no plain words on its first line"); + } + const shapedFixSummary = + fixSummary === undefined + ? undefined + : plainWords(fixSummary, MAX_FIX_SUMMARY); + if (fixSummary !== undefined && !shapedFixSummary) { + omitted.push("fix_summary, which has no plain words on its first line"); + } + + return { + body: { + failure_report: { + kind, + ...(shapedRerun === undefined ? {} : { rerun: shapedRerun }), + ...(shapedErrorClass === undefined + ? {} + : { error_class: shapedErrorClass }), + ...(shapedMessage ? { message: shapedMessage } : {}), + ...(shapedFrames.length === 0 + ? {} + : { frames: shapedFrames.slice(0, MAX_FAILURE_FRAMES) }), + ...(shapedFixSummary ? { fix_summary: shapedFixSummary } : {}), + ...(Object.keys(versions).length === 0 ? {} : { versions }), + }, + }, + omitted, + }; +} + +/** + * The command without its leading environment assignments, when what is left + * is an RSpec run of the application's specs. + * + * @param {string} command + * @returns {string | undefined} + */ +export function rspecRun(command) { + const words = shellWords(command); + if (words === null) return undefined; + + let start = 0; + if ( + words[0]?.value === "env" && + words[1] !== undefined && + ASSIGNMENT_WORD.test(words[1].value) + ) { + start = 1; + } + while (ASSIGNMENT_WORD.test(words[start]?.value ?? "")) { + start += 1; + } + + // A spec directory may be written with a trailing slash: spec/models/. + const run = words + .slice(start) + .map((word) => word.raw.replace(/^((?:\.\/)?spec\/.*[^/])\/+$/, "$1")) + .join(" "); + return run.length <= MAX_RERUN && RERUN.test(run) && !PARENT_SEGMENT.test(run) + ? run + : undefined; +} + +/** + * Splits a command into shell words, keeping each word's text as written + * and its value with quotes and escapes removed. Returns null for an + * unterminated quote. + * + * @param {string} command + * @returns {{raw: string, value: string}[] | null} + */ +function shellWords(command) { + /** @type {{raw: string, value: string}[]} */ + const words = []; + let raw = ""; + let value = ""; + let inWord = false; + let index = 0; + while (index < command.length) { + const character = /** @type {string} */ (command[index]); + if (/\s/.test(character)) { + if (inWord) words.push({ raw, value }); + raw = ""; + value = ""; + inWord = false; + index += 1; + continue; + } + + inWord = true; + if (character === "'" || character === '"') { + const close = command.indexOf(character, index + 1); + if (close === -1) return null; + raw += command.slice(index, close + 1); + value += command.slice(index + 1, close); + index = close + 1; + } else if (character === "\\" && index + 1 < command.length) { + raw += command.slice(index, index + 2); + value += command[index + 1]; + index += 2; + } else { + raw += character; + value += character; + index += 1; + } + } + if (inWord) words.push({ raw, value }); + return words; +} + +/** + * A frame in the application's own files, as `path:line`. + * + * @param {string} frame + * @param {string} cwd + * @returns {string | undefined} + */ +function appFrame(frame, cwd) { + const root = `${cwd.replace(/[\\/]+$/, "")}/`; + const relative = frame.startsWith(root) ? frame.slice(root.length) : frame; + const match = FRAME.exec( + relative.replace(/^[^:]*/, (file) => file.replace(/\\/g, "/")), + ); + if (match === null || PARENT_SEGMENT.test(match[1] ?? "")) return undefined; + + const shaped = `${match[1]}:${match[2]}`; + return shaped.length <= MAX_FRAME ? shaped : undefined; +} + +/** + * The plain words of free text's first line. From the word that holds the + * first quote character to the end of the line is one placeholder; before + * it, a word that can carry a value is one too; then words that fit within + * `limit` are kept. + * + * @param {string} text + * @param {number} limit + */ +export function plainWords(text, limit) { + const [firstLine = ""] = text.split(/\r\n|[\r\n\u0085\u2028\u2029]/, 1); + const line = firstLine.replace(/\t/g, " ").replace(CONTROL, ""); + const quote = line.search(QUOTE); + const words = (quote === -1 ? line : line.slice(0, quote)) + .split(/\s+/) + .filter((word) => word !== ""); + // The word that holds the quote goes with the rest of the line. + if (quote !== -1 && !/\s/.test(line[quote - 1] ?? " ")) words.pop(); + const shaped = words.map((word) => + !VALUE_WORD.test(word) && Array.from(word).length <= MAX_PLAIN_WORD + ? word + : PLACEHOLDER, + ); + if (quote !== -1) shaped.push(PLACEHOLDER); + + /** @type {string[]} */ + const kept = []; + let length = 0; + for (const word of shaped) { + const next = length + (kept.length === 0 ? 0 : 1) + Array.from(word).length; + if (next > limit) break; + kept.push(word); + length = next; + } + return kept.join(" "); +} + +/** + * @typedef {object} SendReportOptions + * @property {string} origin + * @property {{method: string, path: string}} route + * @property {string} projectId + * @property {string} compilationId + * @property {string} body the exact JSON text that was printed + * @property {string} wrapper the key, such as progress_report, under which + * First Draft acknowledges the stored report with its id and Compilation + * @property {typeof globalThis.fetch} [fetchFunction] + * @property {(timeoutMs: number) => AbortSignal} [createRequestSignal] + */ + +/** + * Sends one report once. A report is never retried: First Draft may already + * hold it when the outcome is unconfirmed. + * + * @param {SendReportOptions} options + * @returns {Promise<{outcome: "sent" | "reports_off"}>} + */ +export async function sendReport({ + origin, + route, + projectId, + compilationId, + body, + wrapper, + fetchFunction = globalThis.fetch, + createRequestSignal = (timeoutMs) => AbortSignal.timeout(timeoutMs), +}) { + const endpoint = serviceEndpoint(route, origin, { + project_id: projectId, + compilation_id: compilationId, + }); + let response; + try { + response = await sendRequest(fetchFunction, endpoint, { + headers: { + Accept: "application/json, application/problem+json", + "Content-Type": "application/json", + }, + body, + redirect: "error", + signal: createRequestSignal(REQUEST_TIMEOUT_MS), + }); + } catch (error) { + if (error instanceof FirstDraftNetworkError) { + throw new ReportUnavailableError(error.status); + } + throw error; + } + + let responseBody; + try { + responseBody = await readResponseBody(response); + } catch (error) { + if ( + error instanceof FirstDraftNetworkError || + error instanceof FirstDraftProtocolError + ) { + throw new ReportUnavailableError(response.status); + } + throw error; + } + + // First Draft acknowledges a stored report with 201 and the report itself. + // Any other success, such as a proxy's page, confirms nothing. + if (response.ok) { + if ( + response.status === 201 && + responseMediaType(response) === "application/json" && + isRecord(responseBody) && + isRecord(responseBody[wrapper]) && + isStoredReport(responseBody[wrapper], compilationId) + ) { + return { outcome: "sent" }; + } + throw new ReportUnavailableError(response.status); + } + + const problem = isProblemBody(response, responseBody) + ? problemProjection(responseBody) + : null; + if (response.status === 403 && problem?.code === "reports_off") { + return { outcome: "reports_off" }; + } + if (problem !== null && response.status !== 408 && response.status < 500) { + throw new ReportRejectedError(response.status, problem); + } + throw new ReportUnavailableError(response.status, problem); +} + +/** @param {unknown} value @returns {value is Record} */ +function isRecord(value) { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + +/** + * @param {Record} report + * @param {string} compilationId + */ +function isStoredReport(report, compilationId) { + return ( + typeof report.id === "string" && + STORED_ID.test(report.id) && + report.compilation_id === compilationId + ); +} + +// First Draft stores each report under a UUID. +const STORED_ID = + /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i; diff --git a/src/compilation-artifact.js b/src/compilation-artifact.js index 50e8eb9..64a5445 100644 --- a/src/compilation-artifact.js +++ b/src/compilation-artifact.js @@ -27,7 +27,11 @@ export const ARTIFACT_MEDIA_TYPE = "application/vnd.firstdraft.compilation-artifact+json"; export const ARTIFACT_FORMAT = "firstdraft.compilation-artifact/1"; export const FOUNDATION_PLAN_FORMAT = "firstdraft.foundation-plan.sketch/0.23"; -export const RAILS_TARGET_PROFILE = "rails-sketch/2026-10"; +// The one place the CLI names the Rails target profile: plan init writes it, +// artifact validation accepts only it, and the documentation test requires +// the docs to name only it. The value is a working ID until the release names +// the profile. +export const RAILS_TARGET_PROFILE = "rails-sketch/2026-11"; export const MAX_ARTIFACT_BYTES = 128 * 1024 * 1024; const ARTIFACT_KEYS = ["format", "provenance", "manifest_sha256", "files"]; diff --git a/src/oauth.js b/src/oauth.js index 09e7c4e..543048d 100644 --- a/src/oauth.js +++ b/src/oauth.js @@ -88,12 +88,9 @@ export function createState(random = randomBytes) { /** * @param {string} origin - * @param {{redirectUri: string, state: string, challenge: string, deviceName?: string}} options + * @param {{redirectUri: string, state: string, challenge: string}} options */ -export function authorizationUrl( - origin, - { redirectUri, state, challenge, deviceName }, -) { +export function authorizationUrl(origin, { redirectUri, state, challenge }) { const url = new URL("/oauth/authorize", origin); url.search = new URLSearchParams({ response_type: "code", @@ -102,7 +99,6 @@ export function authorizationUrl( state, code_challenge: challenge, code_challenge_method: "S256", - ...(deviceName ? { device_name: deviceName } : {}), }).toString(); return url.href; } @@ -290,17 +286,14 @@ export async function exchangeAuthorizationCode({ */ /** - * @param {RequestOptions & {deviceName?: string}} options + * @param {RequestOptions} request * @returns {Promise} */ -export async function requestDeviceAuthorization({ deviceName, ...request }) { +export async function requestDeviceAuthorization(request) { const { status, body } = await postForm( request, SERVICE_ROUTES.requestDeviceAuthorization, - { - client_id: CLIENT_ID, - ...(deviceName ? { device_name: deviceName } : {}), - }, + { client_id: CLIENT_ID }, ); if (status !== 200) throw oauthFailure(status, body); diff --git a/src/plan-state.js b/src/plan-state.js index bb365f8..0f4dd2e 100644 --- a/src/plan-state.js +++ b/src/plan-state.js @@ -21,6 +21,7 @@ const DEFAULT_FILE_SYSTEM = { lstatSync, readFileSync }; export class PlanStateConfigurationError extends Error {} export class PlanStateLocalError extends Error {} +export class PlanStateNotPushedError extends Error {} /** * @param {object} options @@ -39,6 +40,35 @@ export function readPlanState({ cwd, fileSystem = DEFAULT_FILE_SYSTEM }) { return parsePlanState(source); } +/** + * The Project and API origin that a successful plan push pinned, read from + * the Project's directory or, in an application that adopted the current + * directory, from the planning state archived at .firstdraft/design. + * + * @param {object} options + * @param {string} options.cwd + * @param {PlanStateFileSystem} [options.fileSystem] + */ +export function readPinnedProject({ cwd, fileSystem }) { + // Only an adopted root, whose real .firstdraft holds no state.json, falls + // back; any other local problem is reported for this directory. + const adoptedRoot = + isDirectory(path.join(cwd, ".firstdraft"), fileSystem) && + isAbsent(path.join(cwd, ".firstdraft", "state.json"), fileSystem) && + isDirectory(path.join(cwd, ".firstdraft", "design"), fileSystem); + const state = readPlanState({ + cwd: adoptedRoot ? path.join(cwd, ".firstdraft", "design") : cwd, + fileSystem, + }); + if (state.api_url === undefined) { + throw new PlanStateNotPushedError( + "The local Foundation Plan has not been pushed.", + ); + } + + return { apiUrl: state.api_url, projectId: state.project_id }; +} + /** @param {string} value */ export function normalizeApiUrl(value) { let url; @@ -72,6 +102,35 @@ export function normalizeApiUrl(value) { return url.origin; } +/** + * @param {string} directory + * @param {PlanStateFileSystem} [fileSystem] + */ +function isDirectory(directory, fileSystem = DEFAULT_FILE_SYSTEM) { + try { + return fileSystem.lstatSync(directory).isDirectory(); + } catch (error) { + if (!isFileSystemError(error)) throw error; + + return false; + } +} + +/** + * @param {string} filePath + * @param {PlanStateFileSystem} [fileSystem] + */ +function isAbsent(filePath, fileSystem = DEFAULT_FILE_SYSTEM) { + try { + fileSystem.lstatSync(filePath); + return false; + } catch (error) { + if (!isFileSystemError(error)) throw error; + + return error.code === "ENOENT"; + } +} + /** @param {unknown} value @returns {value is string} */ export function isUuidV7(value) { return typeof value === "string" && PROJECT_ID_PATTERN.test(value); diff --git a/src/service-client.js b/src/service-client.js new file mode 100644 index 0000000..b99668c --- /dev/null +++ b/src/service-client.js @@ -0,0 +1,502 @@ +import { + FirstDraftNetworkError, + FirstDraftProtocolError, + isProblemBody, + problemProjection, + readResponseBytes, +} from "./api-response.js"; +import { VERSION } from "./version.js"; + +/** The public page with the update steps for each setup. */ +export const UPDATE_URL = "https://firstdraft.com/update"; + +/** + * The Service API contracts this CLI accepts. release/compatibility.json + * declares the same range for the release check, and + * test/release-compatibility.test.js keeps the two equal. + */ +export const API_CONTRACT_RANGE = Object.freeze([">= 0.9.0", "< 0.10.0"]); + +/** Set by the plugin's launcher; docs/commands.md names them for wrappers. */ +export const PLUGIN_VERSION_VARIABLE = "FIRSTDRAFT_PLUGIN_VERSION"; +export const AGENT_VARIABLE = "FIRSTDRAFT_AGENT"; + +// SemVer 2.0.0, as test/release-compatibility.test.js validates it. Build +// metadata after `+` is kept in the text but has no precedence. +const SEMVER = + /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/; +const AGENT_NAME = /^[a-z0-9][a-z0-9._-]{0,39}$/; +const PLATFORM = /^[a-z0-9]{1,32}$/; +const MAX_LIMIT_PROBLEM_BYTES = 64 * 1024; +// The Service ignores the whole header, or keeps no client facts with a +// report, when one value is longer. +const MAX_FACT_LENGTH = 40; + +/** + * A response told the CLI to stop. The CLI finishes handling that response + * and sends nothing after it. When the stop cut the command short, this + * replaces the command's result, and `replaced` holds the error it replaced. + */ +export class ServiceStopError extends Error { + /** @type {unknown} */ + replaced = undefined; +} + +export class UpdateRequiredError extends ServiceStopError { + /** @param {{component: "plugin" | "cli", installed: string, minimum: string}} options */ + constructor({ component, installed, minimum }) { + super("First Draft requires a newer plugin or CLI."); + this.component = component; + this.installed = installed; + this.minimum = minimum; + } +} + +export class ApiContractUnsupportedError extends ServiceStopError { + /** @param {{origin: string, contract: string, kind: "newer" | "older" | "prerelease"}} options */ + constructor({ origin, contract, kind }) { + super("First Draft serves an API contract this CLI does not accept."); + this.origin = origin; + this.contract = contract; + this.kind = kind; + } +} + +export class RateLimitedError extends ServiceStopError { + /** @param {{retryAt: string | undefined, response: Record | null}} options */ + constructor({ retryAt, response }) { + super("First Draft refused a request because of an account limit."); + this.status = 429; + this.retryAt = retryAt; + this.response = response; + } +} + +/** + * @typedef {object} ServiceSession + * @property {string} clientHeader the FirstDraft-Client value sent on every request + * @property {(request?: typeof globalThis.fetch) => typeof globalThis.fetch} fetch + * Wraps a fetch function so every request carries FirstDraft-Client and + * every response is checked. + * @property {(work: Promise) => Promise} settle + * Awaits a command's work. When a response told the CLI to stop and the + * stop cut the work short (a later request was not sent) or was a 429, + * rejects with that ServiceStopError. Otherwise the work finished on its + * own terms: settle writes one line that names the stop and resolves or + * rejects as the work did, so its result or recovery data is kept. Either + * way it then writes the command's one version line, if any. + * @property {() => void} flush + * Writes the version line for a command that does not settle its work. + */ + +/** + * One session per command invocation, so the update line is printed at most + * once however many requests the command makes. + * + * @param {object} options + * @param {Readonly>} options.env + * @param {(line: string) => void} options.notify writes one line to stderr + * @param {string} [options.platform] + * @param {() => number} [options.now] + * @returns {ServiceSession} + */ +export function createServiceSession({ + env, + notify, + platform = process.platform, + now = Date.now, +}) { + const plugin = semver(env[PLUGIN_VERSION_VARIABLE]); + const agent = env[AGENT_VARIABLE]?.toLowerCase(); + // The Service parses this grammar and ignores a header that breaks it, so + // build metadata, which has no precedence, is not sent. + const clientHeader = [ + `cli/${VERSION}`, + ...(plugin === null || plugin.release.length > MAX_FACT_LENGTH + ? [] + : [`plugin/${plugin.release}`]), + ...(agent !== undefined && AGENT_NAME.test(agent) + ? [`agent/${agent}`] + : []), + ...(PLATFORM.test(platform) ? [`os/${platform}`] : []), + ].join("; "); + // A plugin is compared with the plugin versions First Draft names; a CLI + // run without one, such as a direct npm installation, with the CLI + // versions. The two packages are numbered separately. + // A plugin version that is set, even blank, but unreadable says a plugin is + // present without saying which, so neither pair is compared, and the + // command's one version line says why. + const pluginSet = env[PLUGIN_VERSION_VARIABLE] !== undefined; + /** @type {{component: "plugin" | "cli", label: string, version: Version, latestHeader: string, minimumHeader: string} | null} */ + const installed = + pluginSet && plugin === null + ? null + : plugin === null + ? { + component: "cli", + label: "CLI", + version: /** @type {Version} */ (semver(VERSION)), + latestHeader: "firstdraft-latest-cli", + minimumHeader: "firstdraft-minimum-cli", + } + : { + component: "plugin", + label: "plugin", + version: plugin, + latestHeader: "firstdraft-latest-plugin", + minimumHeader: "firstdraft-minimum-plugin", + }; + /** @type {ServiceStopError | null} */ + let stop = null; + let blocked = false; + /** @type {string | null} */ + let updateLine = null; + let flushed = false; + + /** + * @param {string} origin + * @param {Response} response + * @returns {Promise} the response, rebuilt when its body was read + */ + async function observe(origin, response) { + // A pair is compared only when both of its versions are readable. + const pair = + installed === null + ? null + : versionPair( + response, + installed.latestHeader, + installed.minimumHeader, + ); + if ( + installed !== null && + updateLine === null && + pair !== null && + compareVersions(installed.version, pair.latest) < 0 + ) { + updateLine = + `First Draft: an update is available (${installed.label} ${pair.latest.text}; this setup has ` + + `${installed.label} ${installed.version.text}). ` + + `Tell the person the update steps are at ${UPDATE_URL}\n`; + } + if ( + installed === null && + updateLine === null && + versionPair( + response, + "firstdraft-latest-plugin", + "firstdraft-minimum-plugin", + ) !== null + ) { + updateLine = + `First Draft: ${PLUGIN_VERSION_VARIABLE} is set but is not a plugin version, so the CLI could not ` + + `tell whether this setup is current. The update steps are at ${UPDATE_URL}\n`; + } + + // A 429 refused the request, whatever else the response says. + if (response.status === 429) { + // The body is read here rather than through a clone: a tee holds a + // cancelled branch until the other branch is read, so an oversized + // body would stall. The command gets the same bytes back. + const { body, problem } = await readLimitProblem(response); + stop = new RateLimitedError({ + retryAt: retryTime(response.headers.get("retry-after"), now), + response: problem, + }); + return new Response(body, { + status: response.status, + statusText: response.statusText, + headers: response.headers, + }); + } + + const contract = semver(response.headers.get("firstdraft-api-contract")); + if (contract !== null && !acceptsContract(contract)) { + stop = new ApiContractUnsupportedError({ + origin, + contract: contract.text, + kind: contractKind(contract), + }); + return response; + } + + if ( + installed !== null && + pair !== null && + compareVersions(installed.version, pair.minimum) < 0 + ) { + stop = new UpdateRequiredError({ + component: installed.component, + installed: installed.version.text, + minimum: pair.minimum.text, + }); + return response; + } + + return response; + } + + /** + * Writes the one version line for this command: the stop when a response + * required an update the command survived, else the update notice. + * + * @param {{versionStopReported: boolean}} options + */ + function flush({ versionStopReported }) { + if (flushed) return; + flushed = true; + if (stop !== null && !(stop instanceof RateLimitedError)) { + if (!versionStopReported) { + notify( + `First Draft: ${stopSentence(stop)} This command finished; ${stopAction(stop)} before the next one.\n`, + ); + } + return; + } + if (updateLine !== null) notify(updateLine); + } + + return { + clientHeader, + fetch(request = globalThis.fetch) { + /** @type {typeof globalThis.fetch} */ + const serviceFetch = async (input, init) => { + if (stop !== null) { + blocked = true; + throw stop; + } + + const response = await request(input, { + ...init, + headers: { ...init?.headers, "FirstDraft-Client": clientHeader }, + }); + const url = new URL(input instanceof Request ? input.url : input); + return observe(url.origin, response); + }; + return serviceFetch; + }, + async settle(work) { + let value; + try { + value = await work; + } catch (error) { + if (stop !== null && (blocked || stop instanceof RateLimitedError)) { + stop.replaced = error; + flush({ versionStopReported: true }); + throw stop; + } + flush({ versionStopReported: false }); + throw error; + } + // A 429 refused the request, so a result built from it is a refusal. + if (stop instanceof RateLimitedError) { + flush({ versionStopReported: true }); + throw stop; + } + flush({ versionStopReported: false }); + return value; + }, + flush() { + flush({ versionStopReported: false }); + }, + }; +} + +/** + * Both versions of a latest-and-minimum pair, or null unless both are + * readable. + * + * @param {Response} response + * @param {string} latestHeader + * @param {string} minimumHeader + */ +function versionPair(response, latestHeader, minimumHeader) { + const latest = semver(response.headers.get(latestHeader)); + const minimum = semver(response.headers.get(minimumHeader)); + return latest === null || minimum === null ? null : { latest, minimum }; +} + +/** + * @param {Version} contract + * @returns {"newer" | "older" | "prerelease"} + */ +function contractKind(contract) { + if (compareVersions(contract, API_CONTRACT_FLOOR) < 0) return "older"; + return acceptsContract({ ...contract, prerelease: [] }) + ? "prerelease" + : "newer"; +} + +/** @param {ServiceStopError} stop */ +export function stopAction(stop) { + return stop instanceof ApiContractUnsupportedError && stop.kind !== "newer" + ? "use the CLI version that this First Draft origin supports" + : `tell the person to update with the steps at ${UPDATE_URL}`; +} + +/** @typedef {{major: number, minor: number, patch: number, prerelease: string[], text: string, release: string}} Version */ + +/** + * @param {string | null | undefined} value + * @returns {Version | null} + */ +function semver(value) { + const match = typeof value === "string" ? SEMVER.exec(value.trim()) : null; + if (match === null) return null; + + return { + major: Number(match[1]), + minor: Number(match[2]), + patch: Number(match[3]), + prerelease: match[4] === undefined ? [] : match[4].split("."), + text: match[0], + release: match[0].replace(/\+.*$/, ""), + }; +} + +/** + * SemVer 2.0.0 precedence: a prerelease sorts before its release, numeric + * identifiers compare numerically and before alphanumeric ones. + * + * @param {Version} left + * @param {Version} right + */ +export function compareVersions(left, right) { + const core = + left.major - right.major || + left.minor - right.minor || + left.patch - right.patch; + if (core !== 0) return Math.sign(core); + if (left.prerelease.length === 0 || right.prerelease.length === 0) { + return Math.sign(right.prerelease.length - left.prerelease.length); + } + + const length = Math.max(left.prerelease.length, right.prerelease.length); + for (let index = 0; index < length; index += 1) { + const a = left.prerelease[index]; + const b = right.prerelease[index]; + if (a === undefined) return -1; + if (b === undefined) return 1; + if (a === b) continue; + + const aNumeric = /^\d+$/.test(a); + const bNumeric = /^\d+$/.test(b); + if (aNumeric && bNumeric) return Math.sign(Number(a) - Number(b)); + if (aNumeric) return -1; + if (bNumeric) return 1; + return a < b ? -1 : 1; + } + return 0; +} + +const COMPARATOR_SIGNS = new Map([ + ["=", [0]], + ["<", [-1]], + ["<=", [-1, 0]], + [">", [1]], + [">=", [0, 1]], +]); + +const API_CONTRACT_COMPARATORS = API_CONTRACT_RANGE.map((requirement) => { + const [operator, bound] = requirement.split(/\s+/); + const signs = COMPARATOR_SIGNS.get(operator ?? ""); + const version = semver(bound); + if (signs === undefined || version === null) { + throw new TypeError(`Invalid API contract requirement: ${requirement}`); + } + return { signs, version }; +}); + +const API_CONTRACT_FLOOR = /** @type {Version} */ ( + API_CONTRACT_COMPARATORS.find(({ signs }) => signs.includes(1))?.version +); + +/** + * As in npm ranges, a prerelease contract is outside a range whose bounds + * name none, so `0.10.0-rc.1` is refused like `0.10.0`. + * + * @param {Version} contract + */ +function acceptsContract(contract) { + return ( + contract.prerelease.length === 0 && + API_CONTRACT_COMPARATORS.every(({ signs, version }) => + signs.includes(compareVersions(contract, version)), + ) + ); +} + +/** + * The sentence that names a stop, shared by the stop line and the handled + * errors in src/cli.js. + * + * @param {ServiceStopError} stop + */ +export function stopSentence(stop) { + if (stop instanceof UpdateRequiredError) { + const label = stop.component === "plugin" ? "plugin" : "CLI"; + return `First Draft requires ${label} ${stop.minimum} or later, and this setup has ${label} ${stop.installed}.`; + } + if (stop instanceof ApiContractUnsupportedError) { + return stop.kind === "prerelease" + ? `First Draft at ${stop.origin} serves prerelease API contract ${stop.contract}, which CLI ${VERSION} does not accept.` + : `First Draft at ${stop.origin} serves API contract ${stop.contract}, which is ${stop.kind} than CLI ${VERSION} accepts.`; + } + return "First Draft refused a request because a limit was reached."; +} + +/** + * RFC 9110 Retry-After: delay-seconds or an HTTP-date. Returns a UTC time to + * the second, or undefined when the header is absent or unreadable. + * + * @param {string | null} value + * @param {() => number} now + */ +function retryTime(value, now) { + if (value === null) return undefined; + + const trimmed = value.trim(); + const milliseconds = /^\d{1,10}$/.test(trimmed) + ? now() + Number(trimmed) * 1000 + : /[A-Za-z]/.test(trimmed) + ? Date.parse(trimmed) + : Number.NaN; + if (!Number.isFinite(milliseconds)) return undefined; + + return new Date(Math.ceil(milliseconds / 1000) * 1000) + .toISOString() + .replace(/\.\d{3}Z$/, "Z"); +} + +/** @param {Response} response */ +async function readLimitProblem(response) { + let bytes; + try { + bytes = await readResponseBytes(response, MAX_LIMIT_PROBLEM_BYTES); + } catch (error) { + // The limit still applies when its explanation cannot be read. + if ( + error instanceof FirstDraftNetworkError || + error instanceof FirstDraftProtocolError + ) { + return { body: null, problem: null }; + } + throw error; + } + + const body = parseJson(bytes); + return { + body: bytes, + problem: isProblemBody(response, body) ? problemProjection(body) : null, + }; +} + +/** @param {Buffer} bytes */ +function parseJson(bytes) { + try { + return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)); + } catch (error) { + if (error instanceof SyntaxError || error instanceof TypeError) return null; + throw error; + } +} diff --git a/test/account.test.js b/test/account.test.js new file mode 100644 index 0000000..785d474 --- /dev/null +++ b/test/account.test.js @@ -0,0 +1,228 @@ +import assert from "node:assert/strict"; +import test from "node:test"; + +import { run } from "../src/cli.js"; + +const PRODUCTION = "https://firstdraft.com"; +const STAGING = "https://staging.firstdraft.com"; +const PRODUCTION_TOKEN = "canary-production-token"; +const STAGING_TOKEN = "canary-staging-token"; +const ACCOUNT_HELP = `First Draft CLI + +Usage: + firstdraft account + +Options: + --staging Use staging + -h, --help Show help + +Environment: + FIRSTDRAFT_API_TOKEN Authenticate production or custom API origins + FIRSTDRAFT_STAGING_API_TOKEN Authenticate staging.firstdraft.com + FIRSTDRAFT_API_URL Use a custom API origin + +The command reads the signed-in account once and prints whether it sends +progress and failure reports. Only the person turns reports on or off: when +approving firstdraft login, or later on their First Draft account page. +`; + +test("account help is printed without a request", async () => { + for (const argv of [ + ["account", "--help"], + ["account", "-h"], + ]) { + assert.deepEqual(await invoke(argv), { + status: 0, + stdout: ACCOUNT_HELP, + stderr: "", + }); + } +}); + +test("account rejects invalid arguments before any request", async () => { + for (const argv of [ + ["account", "canary-positional"], + ["account", "--canary-option"], + ["account", "--staging", "--staging"], + ]) { + const result = await invoke(argv); + assert.equal(result.status, 2); + assert.deepEqual(JSON.parse(result.stderr), { + error: "invalid_arguments", + detail: "Invalid arguments. Run 'firstdraft account --help' for usage.", + }); + assert.doesNotMatch(result.stderr, /canary/); + } +}); + +test("account prints whether reports are on, and nothing else the Service sent", async () => { + for (const reports of ["on", "off"]) { + /** @type {RequestInit | undefined} */ + let sent; + const result = await invoke(["account"], { + fetchFunction: async (input, init) => { + sent = init; + assert.equal(String(input), `${PRODUCTION}/v1/account`); + return json({ reports, canary_extra: "ignored" }); + }, + }); + + assert.deepEqual(result, { + status: 0, + stdout: `${JSON.stringify({ reports }, null, 2)}\n`, + stderr: "", + }); + assert.equal(sent?.method, "GET"); + assert.equal(sent?.redirect, "error"); + const headers = new Headers(sent?.headers); + assert.equal(headers.get("authorization"), `Bearer ${PRODUCTION_TOKEN}`); + assert.match(String(headers.get("firstdraft-client")), /^cli\//); + } +}); + +test("account selects its origin as login does", async () => { + for (const [argv, options, origin, token] of [ + [["--staging", "account"], {}, STAGING, STAGING_TOKEN], + [["account", "--staging"], {}, STAGING, STAGING_TOKEN], + [ + ["account"], + { apiUrl: "http://127.0.0.1:3000" }, + "http://127.0.0.1:3000", + PRODUCTION_TOKEN, + ], + ]) { + const result = await invoke(/** @type {string[]} */ (argv), { + .../** @type {object} */ (options), + fetchFunction: async (input, init) => { + assert.equal(new URL(String(input)).origin, origin); + assert.equal( + new Headers(init?.headers).get("authorization"), + `Bearer ${token}`, + ); + return json({ reports: "off" }); + }, + }); + assert.equal(result.status, 0, result.stderr); + } + + const conflict = await invoke(["account", "--staging"], { + apiUrl: "https://canary.example", + }); + assert.equal(conflict.status, 2); + assert.equal(JSON.parse(conflict.stderr).error, "invalid_configuration"); +}); + +test("account maps authentication, unavailable, and invalid responses", async () => { + const missing = await invoke(["account"], { apiToken: "" }); + assert.equal(missing.status, 1); + assert.equal(JSON.parse(missing.stderr).error, "authentication_required"); + + const rejected = await invoke(["account"], { + fetchFunction: async () => + problem(401, "authentication_required", "A valid token is required."), + }); + assert.equal(rejected.status, 1); + assert.equal(JSON.parse(rejected.stderr).error, "authentication_required"); + assert.equal(JSON.parse(rejected.stderr).status, 401); + + for (const [response, expected] of [ + [ + () => problem(503, "service_unavailable", "Try again."), + { + error: "account_unavailable", + detail: + "Could not read the account. This read-only request is safe to retry.", + status: 503, + response: { + type: "about:blank", + title: "Service Unavailable", + status: 503, + code: "service_unavailable", + detail: "Try again.", + }, + }, + ], + [ + () => new Response("canary", { status: 404 }), + { + error: "account_unavailable", + detail: + "Could not read the account. This read-only request is safe to retry.", + status: 404, + }, + ], + [ + () => { + throw new TypeError("canary network failure"); + }, + { + error: "account_unavailable", + detail: + "Could not read the account. This read-only request is safe to retry.", + }, + ], + ...[ + json({ reports: "maybe" }), + json({ reports: true }), + json([]), + new Response('{"reports":"on"}', { status: 200 }), + new Response(null, { status: 204 }), + ].map((value) => [ + () => value, + { + error: "invalid_server_response", + detail: + "First Draft returned an invalid account response. Retrying the unchanged request will not repair this protocol mismatch.", + status: value.status, + }, + ]), + ]) { + const result = await invoke(["account"], { + fetchFunction: async () => /** @type {() => Response} */ (response)(), + }); + assert.equal(result.status, 1); + assert.equal(result.stdout, ""); + assert.deepEqual(JSON.parse(result.stderr), expected); + assert.doesNotMatch(result.stderr, /canary/); + } +}); + +/** @param {unknown} body */ +function json(body) { + return new Response(JSON.stringify(body), { + status: 200, + headers: { "Content-Type": "application/json" }, + }); +} + +/** @param {number} status @param {string} code @param {string} detail */ +function problem(status, code, detail) { + return new Response( + JSON.stringify({ + type: "about:blank", + title: status === 401 ? "Unauthorized" : "Service Unavailable", + status, + code, + detail, + }), + { status, headers: { "Content-Type": "application/problem+json" } }, + ); +} + +/** @param {readonly string[]} argv @param {Partial} [options] */ +async function invoke(argv, options = {}) { + let stdout = ""; + let stderr = ""; + const status = await run({ + argv, + stdout: { write: (text) => (stdout += text) }, + stderr: { write: (text) => (stderr += text) }, + apiToken: PRODUCTION_TOKEN, + stagingApiToken: STAGING_TOKEN, + apiUrl: undefined, + env: { XDG_CONFIG_HOME: "/nonexistent/firstdraft-test-config" }, + fetchFunction: async () => assert.fail("No network request was expected"), + ...options, + }); + return { status, stdout, stderr }; +} diff --git a/test/api-environments.test.js b/test/api-environments.test.js index 12285fe..2a7b33d 100644 --- a/test/api-environments.test.js +++ b/test/api-environments.test.js @@ -24,6 +24,19 @@ const REMOTE_COMMANDS = [ ["compilation", "status", COMPILATION_ID], ["compilation", "download", COMPILATION_ID, "--output", "application"], ["compilation", "cancel", COMPILATION_ID], + ["conversation", "send", "conversation.jsonl", "--person-agreed"], + ["report", "progress", COMPILATION_ID, "--step", "setup"], + [ + "report", + "failure", + COMPILATION_ID, + "--kind", + "lint_failure", + "--rerun", + "bin/rubocop", + "--error-class", + "Rails/Delegate", + ], ]; test("production and staging credentials follow the pinned origin on every remote command", async (context) => { @@ -346,6 +359,7 @@ function projectDirectory(context, origin) { context.after(() => rmSync(cwd, { recursive: true, force: true })); mkdirSync(path.join(cwd, ".firstdraft")); writeFileSync(path.join(cwd, ".firstdraft", "foundation-plan.json"), "{}\n"); + writeFileSync(path.join(cwd, "conversation.jsonl"), "{}\n"); writeFileSync( path.join(cwd, ".firstdraft", "state.json"), `${JSON.stringify({ diff --git a/test/cli.test.js b/test/cli.test.js index 80d9063..36a5002 100644 --- a/test/cli.test.js +++ b/test/cli.test.js @@ -15,11 +15,14 @@ Usage: firstdraft [options] Commands: - compilation Inspect, download, and cancel Compilations - generate Generate local values - login Log in to First Draft and save a token - logout Revoke and remove the saved token - plan Work with Foundation Plans + account Show whether this account sends reports + compilation Inspect, download, and cancel Compilations + conversation Send a planning conversation to First Draft + generate Generate local values + login Log in to First Draft and save a token + logout Revoke and remove the saved token + plan Work with Foundation Plans + report Send a progress or failure report to First Draft Options: --staging Use staging for API commands (production is the default) diff --git a/test/compilation-artifact.test.js b/test/compilation-artifact.test.js index 914bc7c..af2cf03 100644 --- a/test/compilation-artifact.test.js +++ b/test/compilation-artifact.test.js @@ -308,7 +308,7 @@ test("pins external provenance identities and validates nested metadata", () => test("rejects an older target profile even when retained status agrees", () => { const target = { id: "rails", - profile: "rails-sketch/2026-09-bookmark-assets", + profile: "rails-sketch/2026-10", }; const fixture = artifactFixture({ provenance: { target } }); diff --git a/test/conversation.test.js b/test/conversation.test.js new file mode 100644 index 0000000..136938d --- /dev/null +++ b/test/conversation.test.js @@ -0,0 +1,306 @@ +import assert from "node:assert/strict"; +import { createHash } from "node:crypto"; +import { + mkdirSync, + mkdtempSync, + realpathSync, + rmSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import test from "node:test"; + +import { run } from "../src/cli.js"; + +const PRODUCTION = "https://firstdraft.com"; +const STAGING = "https://staging.firstdraft.com"; +const PROJECT_ID = "01900000-0000-7000-8000-000000009201"; +const TOKEN = "canary-conversation-token"; +const CONVERSATION = '{"role":"user","text":"A movie catalog, please."}\n'; +const CONSENT_REQUIRED = { + error: "consent_required", + detail: + "Nothing was sent. Ask the person whether to send this conversation, show them the file, and pass --person-agreed only after they say yes this time.", +}; + +test("conversation help is printed without a request", async () => { + for (const argv of [["conversation"], ["conversation", "--help"]]) { + const result = await invoke(argv); + assert.equal(result.status, 0); + assert.match(result.stdout, /send {2}Send one planning conversation file/); + } + + const help = await invoke(["conversation", "send", "--help"]); + assert.equal(help.status, 0); + assert.match( + help.stdout, + /firstdraft conversation send --person-agreed/, + ); + assert.match(help.stdout, /--person-agreed {2}The person said yes/); + + const unknown = await invoke(["conversation", "canary"]); + assert.equal(unknown.status, 2); + assert.match( + unknown.stderr, + /^Unknown command\.\nRun 'firstdraft conversation --help' for usage\.\n$/, + ); +}); + +test("conversation send requires the person's yes before reading anything", async () => { + for (const argv of [ + ["conversation", "send", "canary.jsonl"], + ["conversation", "send", "canary.jsonl", "--staging"], + ]) { + const result = await invoke(argv, { cwd: "/nonexistent/canary" }); + assert.equal(result.status, 2); + assert.equal(result.stdout, ""); + assert.deepEqual(JSON.parse(result.stderr), CONSENT_REQUIRED); + } + + for (const argv of [ + ["conversation", "send", "--person-agreed"], + ["conversation", "send", "a", "b", "--person-agreed"], + ["conversation", "send", "", "--person-agreed"], + ["conversation", "send", "a", "--person-agreed", "--person-agreed"], + ["conversation", "send", "a", "--canary"], + ]) { + const result = await invoke(argv); + assert.equal(result.status, 2, argv.join(" ")); + assert.deepEqual(JSON.parse(result.stderr), { + error: "invalid_arguments", + detail: + "Invalid arguments. Run 'firstdraft conversation send --help' for usage.", + }); + } +}); + +test("conversation send prints the file and its size, then uploads its bytes once", async (context) => { + const cwd = projectDirectory(context, PRODUCTION); + /** @type {{url: string, init: RequestInit | undefined}[]} */ + const requests = []; + const result = await invoke( + ["conversation", "send", "transcripts/planning.jsonl", "--person-agreed"], + { + cwd, + fetchFunction: async (input, init) => { + requests.push({ url: String(input), init }); + return new Response('{"id":"canary"}', { + status: 201, + headers: { "Content-Type": "application/json" }, + }); + }, + }, + ); + + const file = path.join(cwd, "transcripts", "planning.jsonl"); + const digest = createHash("sha256").update(CONVERSATION).digest("hex"); + assert.deepEqual(result, { + status: 0, + stdout: + `Sending ${file} (${Buffer.byteLength(CONVERSATION)} bytes, SHA-256 ${digest}) for Project ${PROJECT_ID} ` + + `to ${PRODUCTION}.\nSent.\n`, + stderr: "", + }); + assert.equal(requests.length, 1); + const [request] = requests; + assert(request); + assert.equal( + request.url, + `${PRODUCTION}/v1/projects/${PROJECT_ID}/conversations`, + ); + assert.equal(request.init?.method, "POST"); + assert.equal( + new Headers(request.init?.headers).get("authorization"), + `Bearer ${TOKEN}`, + ); + const form = /** @type {FormData} */ (request.init?.body); + assert.deepEqual([...form.keys()], ["conversation[file]"]); + const part = form.get("conversation[file]"); + assert(part instanceof File); + assert.equal(part.name, "planning.jsonl"); + assert.equal(await part.text(), CONVERSATION); +}); + +test("conversation send stops on local problems before printing or sending", async (context) => { + const unpushed = projectDirectory(context); + const result = await invoke( + ["conversation", "send", "transcripts/planning.jsonl", "--person-agreed"], + { cwd: unpushed }, + ); + assert.equal(result.status, 1); + assert.equal(result.stdout, ""); + assert.equal(JSON.parse(result.stderr).error, "project_not_pushed"); + + const missingState = await invoke( + ["conversation", "send", "x.jsonl", "--person-agreed"], + { cwd: temporaryDirectory(context) }, + ); + assert.equal(missingState.status, 1); + assert.equal(JSON.parse(missingState.stderr).error, "local_input_unreadable"); + + const cwd = projectDirectory(context, PRODUCTION); + writeFileSync(path.join(cwd, "empty.jsonl"), ""); + mkdirSync(path.join(cwd, "folder")); + for (const [file, reason] of [ + ["missing.jsonl", "unreadable"], + ["folder", "unreadable"], + ["empty.jsonl", "empty"], + ]) { + const outcome = await invoke( + ["conversation", "send", /** @type {string} */ (file), "--person-agreed"], + { cwd }, + ); + assert.equal(outcome.status, 1); + assert.equal(outcome.stdout, ""); + assert.deepEqual(JSON.parse(outcome.stderr), { + error: "conversation_unreadable", + detail: + "The conversation file cannot be sent, so nothing was sent. reason says why: unreadable, empty, or too_large.", + reason, + }); + } + + const mismatch = await invoke( + ["conversation", "send", "transcripts/planning.jsonl", "--person-agreed"], + { cwd }, + ["--staging"], + ); + assert.equal(mismatch.status, 2); + assert.equal(mismatch.stdout, ""); + assert.equal(JSON.parse(mismatch.stderr).error, "invalid_configuration"); + + const noToken = await invoke( + ["conversation", "send", "transcripts/planning.jsonl", "--person-agreed"], + { cwd: projectDirectory(context, STAGING), apiToken: TOKEN }, + ); + assert.equal(noToken.status, 1); + assert.equal(noToken.stdout, ""); + assert.equal(JSON.parse(noToken.stderr).error, "authentication_required"); +}); + +test("conversation send reports a refusal or an unconfirmed upload without retrying", async (context) => { + const cwd = projectDirectory(context, PRODUCTION); + for (const [response, expected] of [ + [ + () => + new Response( + JSON.stringify({ + type: "about:blank", + title: "Content Too Large", + status: 413, + code: "conversation_too_large", + detail: "Send at most 10 MiB.", + }), + { + status: 413, + headers: { "Content-Type": "application/problem+json" }, + }, + ), + { + error: "conversation_rejected", + detail: + "First Draft rejected the conversation, so it was not kept; response.code says why.", + status: 413, + response: { + type: "about:blank", + title: "Content Too Large", + status: 413, + code: "conversation_too_large", + detail: "Send at most 10 MiB.", + }, + }, + ], + [ + () => new Response("Not Found", { status: 404 }), + { + error: "conversation_unavailable", + detail: + "Could not confirm that First Draft received the conversation, and First Draft may hold it already. Do not send it again without asking the person.", + status: 404, + }, + ], + [ + () => { + throw new TypeError("canary reset"); + }, + { + error: "conversation_unavailable", + detail: + "Could not confirm that First Draft received the conversation, and First Draft may hold it already. Do not send it again without asking the person.", + }, + ], + ]) { + let requests = 0; + const result = await invoke( + ["conversation", "send", "transcripts/planning.jsonl", "--person-agreed"], + { + cwd, + fetchFunction: async () => { + requests += 1; + return /** @type {() => Response} */ (response)(); + }, + }, + ); + assert.equal(requests, 1); + assert.equal(result.status, 1); + assert.match(result.stdout, /^Sending .*planning\.jsonl/); + assert.deepEqual(JSON.parse(result.stderr), expected); + } +}); + +/** + * @param {import("node:test").TestContext} context + * @param {string} [origin] + */ +function projectDirectory(context, origin) { + const cwd = temporaryDirectory(context); + mkdirSync(path.join(cwd, ".firstdraft")); + writeFileSync( + path.join(cwd, ".firstdraft", "state.json"), + `${JSON.stringify({ + format: "firstdraft.cli-state/1", + project_id: PROJECT_ID, + ...(origin + ? { + api_url: origin, + foundation_plan_etag: '"sha256:' + "1".repeat(64) + '"', + } + : {}), + })}\n`, + ); + mkdirSync(path.join(cwd, "transcripts")); + writeFileSync(path.join(cwd, "transcripts", "planning.jsonl"), CONVERSATION); + return cwd; +} + +/** @param {import("node:test").TestContext} context */ +function temporaryDirectory(context) { + const cwd = realpathSync( + mkdtempSync(path.join(tmpdir(), "firstdraft-conversation-")), + ); + context.after(() => rmSync(cwd, { recursive: true, force: true })); + return cwd; +} + +/** + * @param {readonly string[]} argv + * @param {Partial} [options] + * @param {readonly string[]} [prefix] root arguments before the command + */ +async function invoke(argv, options = {}, prefix = []) { + let stdout = ""; + let stderr = ""; + const status = await run({ + stdout: { write: (text) => (stdout += text) }, + stderr: { write: (text) => (stderr += text) }, + apiToken: TOKEN, + stagingApiToken: "", + apiUrl: undefined, + env: { XDG_CONFIG_HOME: "/nonexistent/firstdraft-test-config" }, + fetchFunction: async () => assert.fail("No network request was expected"), + ...options, + argv: [...prefix, ...argv], + }); + return { status, stdout, stderr }; +} diff --git a/test/failure-report-shapes.test.js b/test/failure-report-shapes.test.js new file mode 100644 index 0000000..0293384 --- /dev/null +++ b/test/failure-report-shapes.test.js @@ -0,0 +1,134 @@ +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import path from "node:path"; +import test from "node:test"; + +import { + FAILURE_KINDS, + failureReportBody, + plainWords, + rspecRun, +} from "../src/commands/report.js"; + +// A copy of the service's failure-report examples, kept unchanged so the two +// sides test the same strings. Refresh it whenever the service's copy changes. +const shapes = JSON.parse( + readFileSync( + new URL("fixtures/failure-report-shapes.json", import.meta.url), + "utf8", + ), +); +const CWD = path.resolve("/work/movie_catalog"); + +/** + * Each field as the CLI shapes it on its own, or undefined when the CLI + * leaves it out. + * + * @type {Record string | undefined>} + */ +const SHAPERS = { + rerun: (value) => rspecRun(value), + error_class: (value) => + failureReportBody({ kind: "spec_failure", errorClass: value }, CWD).body + .failure_report.error_class, + frame: (value) => + failureReportBody({ kind: "spec_failure", frames: [value] }, CWD).body + .failure_report.frames?.[0], + message: (value) => + plainWords(value, shapes.fields.message.limit) || undefined, + fix_summary: (value) => + plainWords(value, shapes.fields.fix_summary.limit) || undefined, + version: (value) => + failureReportBody({ kind: "spec_failure", rubyVersion: value }, CWD).body + .failure_report.versions?.ruby, +}; + +test("the examples name exactly the fields the CLI shapes", () => { + assert.deepEqual( + Object.keys(shapes.fields).sort(), + Object.keys(SHAPERS).sort(), + ); +}); + +test("every accepted example passes through the CLI's shaping unchanged", () => { + for (const [field, { accepted }] of Object.entries(shapes.fields)) { + const shape = /** @type {(value: string) => string | undefined} */ ( + SHAPERS[field] + ); + for (const example of /** @type {string[]} */ (accepted)) { + assert.equal(shape(example), example, `${field}: ${example}`); + } + } +}); + +test("the CLI turns every refused example into an accepted value or leaves it out", () => { + for (const [field, { refused }] of Object.entries(shapes.fields)) { + const shape = /** @type {(value: string) => string | undefined} */ ( + SHAPERS[field] + ); + for (const example of /** @type {string[]} */ (refused)) { + const shaped = shape(example); + if (shaped === undefined) continue; + + assert.ok( + !refused.includes(shaped), + `${field}: ${JSON.stringify(example)} became a refused value`, + ); + // What the CLI sends is already in its final shape. + assert.equal( + shape(shaped), + shaped, + `${field}: ${JSON.stringify(example)} became ${JSON.stringify(shaped)}`, + ); + } + } +}); + +test("free text is cut to the limit the service refuses past", () => { + for (const field of ["message", "fix_summary"]) { + const { limit } = shapes.fields[field]; + const shaped = plainWords("word ".repeat(limit), limit); + assert.ok(Array.from(shaped).length <= limit, field); + } +}); + +test("accepted reports pass through unchanged, and refused ones do not leave as they are", () => { + for (const report of shapes.reports.accepted) { + assert.deepEqual( + failureReportBody(asOptions(report), CWD).body.failure_report, + report, + ); + } + + for (const report of shapes.reports.refused) { + // The CLI refuses a missing or unknown kind before it builds a report. + if (!FAILURE_KINDS.includes(report.kind)) continue; + + const shaped = failureReportBody(asOptions(report), CWD).body + .failure_report; + assert.notDeepEqual(shaped, report, JSON.stringify(report)); + for (const [key, value] of Object.entries(shaped)) { + if (key === "kind") continue; + assert.notDeepEqual(value, report[key], `${key} left unchanged`); + } + } +}); + +/** + * The CLI options that would produce a report, ignoring keys it has no + * option for. + * + * @param {Record} report + */ +function asOptions(report) { + return { + kind: report.kind, + rerun: report.rerun, + errorClass: report.error_class, + message: report.message, + frames: report.frames, + fixSummary: report.fix_summary, + rubyVersion: report.versions?.ruby, + railsVersion: report.versions?.rails, + }; +} diff --git a/test/fixtures/failure-report-shapes.json b/test/fixtures/failure-report-shapes.json new file mode 100644 index 0000000..48bff55 --- /dev/null +++ b/test/fixtures/failure-report-shapes.json @@ -0,0 +1,106 @@ +{ + "about": "Examples of what the service accepts and refuses in each failure-report field. The service tests Compilation::ReportShape against this file, and the CLI tests its own shaping against a copy. docs/architecture/reference/README.md#current-account-and-report-http states the rules.", + "fields": { + "rerun": { + "accepted": [ + "rspec spec/models/post_spec.rb", + "bin/rspec ./spec/models/post_spec.rb:42", + "bundle exec rspec spec/models", + "bundle exec rspec spec/a_spec.rb:3:9 spec/system/b-c_spec.rb" + ], + "refused": [ + "bin/rspec", + "bin/rspec spec/models/", + "RAILS_ENV=test bin/rspec spec/models/post_spec.rb", + "bin/rspec spec/models/post_spec.rb --seed 4242", + "bin/rspec 'spec/models/post_spec.rb'", + "bin/rspec spec/models/post_spec.rb[1:2]", + "bin/rspec /Users/sam/app/spec/models/post_spec.rb", + "bin/rspec spec/../secrets.rb", + "bin/rails test test/models/post_test.rb", + "rspec lib/post_spec.rb" + ] + }, + "error_class": { + "accepted": ["NoMethodError", "ActiveRecord::RecordNotFound", "::Foo::Bar2"], + "refused": ["noMethodError", "Layout/LineLength", "Foo::", "Foo Bar", "Foo::bar", "/Users/sam/app"] + }, + "frame": { + "accepted": [ + "app/models/post.rb:12", + "lib/tasks/seed.rake:1", + "config/routes.rb:3", + "db/seeds.rb:9", + "spec/models/post_spec.rb:42", + "app/plugins/feature-x/post.rb:3" + ], + "refused": [ + "app/models/post.rb", + "app/models/:12", + "app/models/post.rb:12:in 'Post#title'", + "/app/models/post.rb:12", + "./app/models/post.rb:12", + "vendor/bundle/gems/x.rb:1", + "app/../secrets.rb:1", + "app\\models\\post.rb:1", + "app/models/my post.rb:1" + ] + }, + "message": { + "accepted": [ + "undefined method […]", + "Read […] failed", + "Validation failed: Email has already been taken", + "Setting […]", + "[…] […] expected 3, got 4", + "array[0] was nil" + ], + "refused": [ + "undefined method 'title' for nil", + "Setting \"secret value\"", + "run `make`", + "it's broken", + "DATABASE_URL=postgres://db failed", + "Read /tmp/sample.log failed", + "see https://example.com", + "path C:\\Users", + "mail sam@example.com", + "token abcdefghijklmnopqrstuvwxyz", + "two\nlines", + "one\ttab" + ], + "limit": 300 + }, + "fix_summary": { + "accepted": ["Returned early when the post has no title.", "Guarded […] before saving."], + "refused": ["Set TOKEN=abc in […]", "Moved the file to app/models"], + "limit": 200 + }, + "version": { + "accepted": ["4.0.6", "8.1.4.1", "8.2.0.beta1", "3.4.0-preview2", "4"], + "refused": ["v4.0.6", "4.0.6p1 secret", "..", "0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f", "4.0.6+build"] + } + }, + "reports": { + "accepted": [ + {"kind": "boot_error"}, + { + "kind": "spec_failure", + "rerun": "bin/rspec ./spec/models/post_spec.rb:42", + "error_class": "NoMethodError", + "message": "undefined method […] for nil", + "frames": ["app/models/post.rb:12", "spec/models/post_spec.rb:42"], + "fix_summary": "Returned early when the post has no title.", + "versions": {"ruby": "4.0.6", "rails": "8.1.4"} + } + ], + "refused": [ + {}, + {"kind": "crash"}, + {"kind": "spec_failure", "rerun": "bin/rspec spec/models/"}, + {"kind": "spec_failure", "message": "Setting 'value'"}, + {"kind": "spec_failure", "rerun": "TOKEN=abc bin/rspec spec/models/post_spec.rb"}, + {"kind": "spec_failure", "environment": {"HOME": "/Users/sam"}} + ] + } +} diff --git a/test/login.test.js b/test/login.test.js index c626c72..79dabc6 100644 --- a/test/login.test.js +++ b/test/login.test.js @@ -16,6 +16,7 @@ import path from "node:path"; import test from "node:test"; import { run } from "../src/cli.js"; +import { VERSION } from "../src/version.js"; const PRODUCTION = "https://firstdraft.com"; const STAGING = "https://staging.firstdraft.com"; @@ -90,7 +91,6 @@ test("browser login exchanges a PKCE code from the loopback callback and saves t const configHome = temporaryConfigHome(context); const result = await invoke(context, ["login"], { configHome, - hostname: () => "canary-laptop\u001b[31m", onStderr: (text) => { const url = authorizationUrlIn(text); if (!url) return; @@ -111,6 +111,10 @@ test("browser login exchanges a PKCE code from the loopback callback and saves t new Headers(init?.headers).get("content-type"), "application/x-www-form-urlencoded", ); + assert.equal( + new Headers(init?.headers).get("firstdraft-client"), + `cli/${VERSION}; os/${process.platform}`, + ); assert(authorization); const form = new URLSearchParams(String(init?.body)); assert.equal(form.get("grant_type"), "authorization_code"); @@ -143,7 +147,8 @@ test("browser login exchanges a PKCE code from the loopback callback and saves t assert.equal(params.get("code_challenge_method"), "S256"); assert.match(String(params.get("code_challenge")), /^[A-Za-z0-9_-]{43}$/); assert.match(String(params.get("state")), /^[A-Za-z0-9_-]{43}$/); - assert.equal(params.get("device_name"), "canary-laptop[31m"); + // The computer's hostname is no longer sent as a device name. + assert.equal(params.get("device_name"), null); assert.match( String(params.get("redirect_uri")), /^http:\/\/127\.0\.0\.1:\d+\/callback$/, @@ -555,7 +560,6 @@ test("device login prints the code, honors interval and slow_down, and saves the const polls = []; const outcomes = ["authorization_pending", "slow_down", null]; const result = await invoke(context, ["login", flag], { - hostname: () => "canary-host", loginSleep: clock.sleep, loginNow: clock.now, startLoopbackServer: async () => assert.fail("No server was expected"), @@ -564,7 +568,7 @@ test("device login prints the code, honors interval and slow_down, and saves the const form = new URLSearchParams(String(init?.body)); assert.equal(form.get("client_id"), "firstdraft-cli"); if (endpoint.pathname === "/oauth/device_authorization") { - assert.equal(form.get("device_name"), "canary-host"); + assert.equal(form.get("device_name"), null); return deviceAuthorizationResponse(); } assert.equal(endpoint.href, `${PRODUCTION}/oauth/token`); @@ -687,7 +691,6 @@ async function invoke(context, argv, options = {}) { stagingApiToken: "", env: { XDG_CONFIG_HOME: configHome }, homedir: () => assert.fail("The home directory must not be used"), - hostname: () => "test-host", loginNow: () => Date.parse("2026-09-29T12:00:00.000Z"), fetchFunction: async () => assert.fail("No network request was expected"), ...rest, diff --git a/test/plan-push.test.js b/test/plan-push.test.js index f97012f..3aaa617 100644 --- a/test/plan-push.test.js +++ b/test/plan-push.test.js @@ -1378,7 +1378,7 @@ function requestOutcomeUnknownOutput(status) { return jsonOutput({ error: "request_outcome_unknown", detail: - "The Plan may have been accepted, but the response could not be verified. Stop and reconcile before pushing again; local state was not changed.", + "The Plan may have been accepted, but the response could not be verified, so local state was not changed. Run the same command once more, with the same options and environment. If First Draft rejects it with status 412, its Plan is no longer the one this folder last pushed: the first push may have landed, or another copy of this Project pushed. If nothing else pushes this Project, start a new one: run 'firstdraft plan init --name ' in a new folder, copy this .firstdraft/foundation-plan.json over the new one, and push from there to this folder's origin: the api_url in its .firstdraft/state.json, or, when a first push never saved one, the origin that push used. Use --staging for staging or the same FIRSTDRAFT_API_URL for a custom origin.", ...(status === undefined ? {} : { status }), }); } diff --git a/test/plan-status.test.js b/test/plan-status.test.js index 1bb03e0..75ee173 100644 --- a/test/plan-status.test.js +++ b/test/plan-status.test.js @@ -17,6 +17,8 @@ import { fileURLToPath } from "node:url"; import { run } from "../src/cli.js"; import { MAX_PLAN_STATUS_RESPONSE_BYTES } from "../src/commands/plan-status.js"; +import { RAILS_TARGET_PROFILE } from "../src/compilation-artifact.js"; +import { VERSION } from "../src/version.js"; /** @typedef {{input: string | URL | Request, init: RequestInit | undefined}} FetchCall */ @@ -37,7 +39,7 @@ const ANALYZER_RELEASE = "foundation-plan-rails/application-2026-09-27-bookmark-assets"; const COMPILER_RELEASE = "foundation-plan-rails/compiler-application-2026-09-27-bookmark-assets"; -const TARGET = { id: "rails", profile: "rails-sketch/2026-10" }; +const TARGET = { id: "rails", profile: RAILS_TARGET_PROFILE }; const PLAN_STATUS_HELP = `First Draft CLI Usage: @@ -146,13 +148,11 @@ test("plan status makes one bounded GET to only the pinned origin", async (conte assert.equal(call.init?.method, "GET"); assert.equal(call.init?.redirect, "error"); assert.equal(call.init?.signal, signal); - assert.deepEqual( - new Headers(call.init?.headers), - new Headers({ - Accept: "application/json, application/problem+json", - Authorization: `Bearer ${API_TOKEN}`, - }), - ); + assert.deepEqual(Object.fromEntries(new Headers(call.init?.headers)), { + accept: "application/json, application/problem+json", + authorization: `Bearer ${API_TOKEN}`, + "firstdraft-client": `cli/${VERSION}; os/${process.platform}`, + }); assert.equal(call.init?.body, undefined); assert.doesNotMatch(result.stdout, /api\.example|opaque|canary-secret/); }); @@ -250,7 +250,7 @@ test("plan status accepts the pinned Service zero-gap canonical digest", async ( const body = analysisBody("valid"); body.analysis.gap_set.gaps = []; body.analysis.gap_set_sha256 = - "c38373ec9f208fb4abb6eeec29c447142dc4f6dd706c8a48286abee4d55d66a8"; + "c9599e35f30761180fc0cb1d57e33fd0106b4a8d8ff93df056b322e6fdfcfe58"; const result = await invoke(["plan", "status"], { cwd, fetchFunction: recordingFetch([jsonResponse(body)], []), @@ -1119,6 +1119,7 @@ async function invoke(argv, overrides = {}) { stdout: { write: (text) => (stdout += text) }, stderr: { write: (text) => (stderr += text) }, apiToken: API_TOKEN, + env: {}, ...overrides, }); diff --git a/test/release-compatibility.test.js b/test/release-compatibility.test.js index 043c6d6..5a2299f 100644 --- a/test/release-compatibility.test.js +++ b/test/release-compatibility.test.js @@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises"; import test from "node:test"; import { FOUNDATION_PLAN_FORMAT } from "../src/compilation-artifact.js"; +import { API_CONTRACT_RANGE } from "../src/service-client.js"; const packageMetadata = JSON.parse( await readFile(new URL("../package.json", import.meta.url), "utf8"), @@ -40,6 +41,11 @@ test("release compatibility declares the coordinated CLI contract", () => { ]); assert.ok(Array.isArray(compatibility.requires.api_contract)); assert.notEqual(compatibility.requires.api_contract.length, 0); + assert.deepEqual( + compatibility.requires.api_contract, + [...API_CONTRACT_RANGE], + "Declare the API range that src/service-client.js refuses outside of", + ); assert.deepEqual( compatibility.requires.foundation_plan_formats, [FOUNDATION_PLAN_FORMAT], diff --git a/test/report.test.js b/test/report.test.js new file mode 100644 index 0000000..87faa0a --- /dev/null +++ b/test/report.test.js @@ -0,0 +1,794 @@ +import assert from "node:assert/strict"; +import { + mkdirSync, + mkdtempSync, + realpathSync, + rmSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import test from "node:test"; + +import { run } from "../src/cli.js"; +import { + failureReportBody, + plainWords, + rspecRun, +} from "../src/commands/report.js"; + +const PRODUCTION = "https://firstdraft.com"; +const STAGING = "https://staging.firstdraft.com"; +const PROJECT_ID = "01900000-0000-7000-8000-000000009100"; +const COMPILATION_ID = "01900000-0000-7000-8000-000000009101"; +const STORED_ID = "0f1e2d3c-4b5a-4968-8778-695a4b3c2d1e"; +const TOKEN = "canary-report-token"; +const STAGING_TOKEN = "canary-staging-report-token"; +const CWD = path.resolve("/work/movie_catalog"); +const REPORTS_OFF = + "Not kept: this account has reports off, so First Draft kept nothing. Continue without sending reports.\n"; +const PROGRESS = ["report", "progress", COMPILATION_ID, "--step", "setup"]; +const FAILURE = [ + "report", + "failure", + COMPILATION_ID, + "--kind", + "boot_error", + "--error-class", + "NameError", +]; + +test("report help lists both reports and each report's options", async () => { + for (const argv of [["report"], ["report", "--help"], ["report", "-h"]]) { + const result = await invoke(argv); + assert.equal(result.status, 0); + assert.match(result.stdout, /firstdraft report /); + assert.match(result.stdout, /progress {2}Report how far/); + assert.match(result.stdout, /failure {3}Report an unexpected failure/); + } + + const progress = await invoke(["report", "progress", "--help"]); + assert.equal(progress.status, 0); + for (const option of [ + "--step ", + "--examples ", + "--failures ", + "--behavior-to-write-failures ", + "--items-remaining ", + ]) { + assert.match(progress.stdout, new RegExp(option)); + } + + const failure = await invoke(["report", "failure", "-h"]); + assert.equal(failure.status, 0); + for (const option of [ + "--kind ", + "--rerun ", + "--error-class ", + "--message ", + "--frame ", + "--fix-summary ", + "--ruby-version ", + "--rails-version ", + ]) { + assert.match(failure.stdout, new RegExp(option)); + } + + for (const argv of [ + ["report", "canary"], + ["report", "--canary"], + ]) { + const result = await invoke(argv); + assert.equal(result.status, 2); + assert.match( + result.stderr, + /Run 'firstdraft report --help' for usage\.\n$/, + ); + assert.doesNotMatch(result.stderr, /canary/); + } +}); + +test("report progress validates its arguments before any request", async () => { + for (const argv of [ + ["report", "progress", "--step", "setup"], + ["report", "progress", "not-a-uuid", "--step", "setup"], + ["report", "progress", COMPILATION_ID], + ["report", "progress", COMPILATION_ID, "--step", "canary"], + [...PROGRESS, "--step", "setup"], + [...PROGRESS, "--examples", "-1"], + [...PROGRESS, "--failures=01"], + [...PROGRESS, "--items-remaining=1.5"], + [...PROGRESS, "--examples", "1000001"], + [...PROGRESS, "--canary"], + [...PROGRESS, COMPILATION_ID], + ]) { + const result = await invoke(argv); + assert.equal(result.status, 2, argv.join(" ")); + assert.equal(result.stdout, ""); + assert.deepEqual(JSON.parse(result.stderr), { + error: "invalid_arguments", + detail: + "Invalid arguments. Run 'firstdraft report progress --help' for usage.", + }); + } +}); + +test("report progress prints the exact report, then sends those bytes once", async (context) => { + const cwd = projectDirectory(context, PRODUCTION); + /** @type {{url: string, init: RequestInit | undefined}[]} */ + const requests = []; + const result = await invoke( + [ + "report", + "progress", + COMPILATION_ID, + "--step", + "specs_first_run", + "--examples", + "120", + "--failures", + "14", + "--behavior-to-write-failures", + "12", + "--items-remaining", + "0", + ], + { + cwd, + fetchFunction: async (input, init) => { + requests.push({ url: String(input), init }); + return new Response( + `{"progress_report":{"id":"${STORED_ID}","compilation_id":"${COMPILATION_ID}"}}`, + { + status: 201, + headers: { "Content-Type": "application/json" }, + }, + ); + }, + }, + ); + + const body = `${JSON.stringify( + { + progress_report: { + step: "specs_first_run", + counts: { + examples: 120, + failures: 14, + behavior_to_write_failures: 12, + items_remaining: 0, + }, + }, + }, + null, + 2, + )}\n`; + assert.deepEqual(result, { + status: 0, + stdout: `Sending this progress report for Compilation ${COMPILATION_ID} to ${PRODUCTION}:\n${body}Sent.\n`, + stderr: "", + }); + assert.equal(requests.length, 1); + const [request] = requests; + assert(request); + assert.equal( + request.url, + `${PRODUCTION}/v1/projects/${PROJECT_ID}/compilations/${COMPILATION_ID}/progress-reports`, + ); + assert.equal(request.init?.method, "POST"); + assert.equal(request.init?.body, body); + const headers = new Headers(request.init?.headers); + assert.equal(headers.get("content-type"), "application/json"); + assert.equal(headers.get("authorization"), `Bearer ${TOKEN}`); + assert.match(String(headers.get("firstdraft-client")), /^cli\//); +}); + +test("a progress report without counts sends only its step, to the pinned origin", async (context) => { + /** @type {unknown} */ + let sent; + const result = await invoke(["--staging", ...PROGRESS], { + cwd: projectDirectory(context, STAGING), + fetchFunction: async (input, init) => { + assert.equal(new URL(String(input)).origin, STAGING); + assert.equal( + new Headers(init?.headers).get("authorization"), + `Bearer ${STAGING_TOKEN}`, + ); + sent = JSON.parse(String(init?.body)); + return acknowledgment("progress_report"); + }, + }); + assert.equal(result.status, 0, result.stderr); + assert.deepEqual(sent, { progress_report: { step: "setup" } }); +}); + +test("reports stop on local problems before printing anything", async (context) => { + for (const [cwd, error] of [ + [projectDirectory(context), "project_not_pushed"], + [temporaryDirectory(context), "local_input_unreadable"], + ]) { + for (const argv of [PROGRESS, FAILURE]) { + const result = await invoke(argv, { cwd }); + assert.equal(result.status, 1); + assert.equal(result.stdout, ""); + assert.equal(JSON.parse(result.stderr).error, error); + } + } + + const mismatch = await invoke([...PROGRESS, "--staging"], { + cwd: projectDirectory(context, PRODUCTION), + }); + assert.equal(mismatch.status, 2); + assert.equal(mismatch.stdout, ""); + assert.equal(JSON.parse(mismatch.stderr).error, "invalid_configuration"); + + const noToken = await invoke(PROGRESS, { + cwd: projectDirectory(context, STAGING), + stagingApiToken: "", + }); + assert.equal(noToken.status, 1); + assert.equal(noToken.stdout, ""); + assert.equal(JSON.parse(noToken.stderr).error, "authentication_required"); +}); + +test("reports_off is a handled message with exit status 0", async (context) => { + const cwd = projectDirectory(context, PRODUCTION); + for (const argv of [PROGRESS, FAILURE]) { + const result = await invoke(argv, { + cwd, + fetchFunction: async () => + problem(403, "reports_off", "This account has not agreed to reports."), + }); + assert.equal(result.status, 0); + assert.equal(result.stderr, ""); + assert.ok(result.stdout.endsWith(REPORTS_OFF), result.stdout); + } +}); + +test("a success without First Draft's acknowledgment is not reported as sent", async (context) => { + const cwd = projectDirectory(context, PRODUCTION); + for (const response of [ + () => new Response("canary", { status: 200 }), + () => new Response(null, { status: 204 }), + () => acknowledgment("failure_report"), + () => + new Response( + JSON.stringify({ + progress_report: { id: STORED_ID, compilation_id: PROJECT_ID }, + }), + { status: 201, headers: { "Content-Type": "application/json" } }, + ), + () => + new Response( + JSON.stringify({ + progress_report: { id: " ", compilation_id: COMPILATION_ID }, + }), + { status: 201, headers: { "Content-Type": "application/json" } }, + ), + () => + new Response('{"progress_report":{}}', { + status: 200, + headers: { "Content-Type": "application/json" }, + }), + ]) { + const result = await invoke(PROGRESS, { + cwd, + fetchFunction: async () => response(), + }); + assert.equal(result.status, 1); + assert.doesNotMatch(result.stdout, /Sent\./); + assert.equal(JSON.parse(result.stderr).error, "report_unavailable"); + } +}); + +test("report failures are handled without retrying", async (context) => { + const cwd = projectDirectory(context, PRODUCTION); + const rejected = + "First Draft rejected the report, so it was not kept; response.code says why. Continue without it."; + const unavailable = + "Could not confirm that First Draft received the report, and First Draft may hold it already. Continue without it rather than sending it again."; + for (const [response, expected] of [ + [ + () => problem(404, "compilation_not_found", "No such Compilation."), + { + error: "report_rejected", + detail: rejected, + status: 404, + response: { + type: "about:blank", + title: "Not Found", + status: 404, + code: "compilation_not_found", + detail: "No such Compilation.", + }, + }, + ], + [ + () => problem(400, "invalid_report", "frames item 1 is not a path."), + { + error: "report_rejected", + detail: rejected, + status: 400, + response: { + type: "about:blank", + title: "Bad Request", + status: 400, + code: "invalid_report", + detail: "frames item 1 is not a path.", + }, + }, + ], + [ + () => new Response("canary", { status: 502 }), + { error: "report_unavailable", detail: unavailable, status: 502 }, + ], + [ + () => { + throw new TypeError("canary socket hang up"); + }, + { error: "report_unavailable", detail: unavailable }, + ], + ]) { + let requests = 0; + const result = await invoke(PROGRESS, { + cwd, + fetchFunction: async () => { + requests += 1; + return /** @type {() => Response} */ (response)(); + }, + }); + assert.equal(requests, 1); + assert.equal(result.status, 1); + assert.deepEqual(JSON.parse(result.stderr), expected); + assert.doesNotMatch(result.stderr, /canary/); + } + + const unauthenticated = await invoke(PROGRESS, { + cwd, + fetchFunction: async () => + problem(401, "authentication_required", "A valid token is required."), + }); + assert.equal(unauthenticated.status, 1); + assert.equal( + JSON.parse(unauthenticated.stderr).error, + "authentication_required", + ); +}); + +test("report failure validates its arguments before any request", async () => { + for (const argv of [ + ["report", "failure", COMPILATION_ID], + ["report", "failure", COMPILATION_ID, "--kind", "lint"], + [...FAILURE, "--kind", "lint_failure"], + [...FAILURE, "--fix-summary", "a", "--fix-summary", "b"], + [...FAILURE, "--canary"], + ["report", "failure", "canary", "--kind", "boot_error"], + ]) { + const result = await invoke(argv); + assert.equal(result.status, 2, argv.join(" ")); + assert.deepEqual(JSON.parse(result.stderr), { + error: "invalid_arguments", + detail: + "Invalid arguments. Run 'firstdraft report failure --help' for usage.", + }); + } +}); + +test("report failure prints exactly the shaped report and what it left out", async (context) => { + const cwd = projectDirectory(context, PRODUCTION); + /** @type {string | undefined} */ + let sent; + const result = await invoke( + [ + "report", + "failure", + COMPILATION_ID, + "--kind", + "spec_failure", + "--rerun", + "RAILS_ENV=test bundle exec rspec ./spec/models/movie_spec.rb:42", + "--error-class", + "NoMethodError", + "--message", + "undefined method 'stars' for nil in /home/sam/x.rb\nsecond line", + "--frame", + `${cwd}/app/models/movie.rb:12:in 'Movie#rate'`, + "--frame", + "/usr/lib/ruby/3.4.0/forwardable.rb:238", + "--fix-summary", + "Guarded nil ratings in Movie#rate.", + "--ruby-version", + "3.4.7", + "--rails-version", + "8.1.4-canary", + ], + { + cwd, + fetchFunction: async (input, init) => { + assert.equal( + String(input), + `${PRODUCTION}/v1/projects/${PROJECT_ID}/compilations/${COMPILATION_ID}/failure-reports`, + ); + sent = String(init?.body); + return acknowledgment("failure_report"); + }, + }, + ); + + assert.equal(result.status, 0, result.stderr); + assert(sent); + assert.deepEqual(JSON.parse(sent), { + failure_report: { + kind: "spec_failure", + rerun: "bundle exec rspec ./spec/models/movie_spec.rb:42", + error_class: "NoMethodError", + message: "undefined method […]", + frames: ["app/models/movie.rb:12"], + fix_summary: "Guarded nil ratings in Movie#rate.", + versions: { ruby: "3.4.7" }, + }, + }); + assert.equal( + result.stdout, + `Sending this failure report for Compilation ${COMPILATION_ID} to ${PRODUCTION}:\n${sent}` + + "Left out: 1 frame not in the application's files with a line number; the rails version, which is not a version number.\n" + + "Sent.\n", + ); +}); + +test("a failure report carries only the fields that fit their shapes", async (context) => { + /** @type {unknown} */ + let sent; + const result = await invoke( + [ + ...FAILURE.slice(0, 5), + "--rerun", + "bin/rubocop", + "--error-class", + "Rails/Delegate", + ], + { + cwd: projectDirectory(context, PRODUCTION), + fetchFunction: async (_input, init) => { + sent = JSON.parse(String(init?.body)); + return acknowledgment("failure_report"); + }, + }, + ); + assert.equal(result.status, 0, result.stderr); + assert.deepEqual(sent, { failure_report: { kind: "boot_error" } }); + assert.match( + result.stdout, + /\nLeft out: rerun, which is not an RSpec run of the application's specs; error_class, which is not a Ruby constant\.\n/, + ); +}); + +test("rerun keeps only an RSpec run of the application's specs", () => { + for (const [ + command, + expected, + ] of /** @type {[string, string | undefined][]} */ ([ + [ + "bundle exec rspec ./spec/models/post_spec.rb:42", + "bundle exec rspec ./spec/models/post_spec.rb:42", + ], + ["rspec spec/requests/posts_spec.rb", "rspec spec/requests/posts_spec.rb"], + [ + "bin/rspec spec/a_spec.rb:1:2 spec/b_spec.rb", + "bin/rspec spec/a_spec.rb:1:2 spec/b_spec.rb", + ], + // Leading assignments are dropped, and the RSpec run after them survives. + [ + "RAILS_ENV=test bin/rspec spec/models/movie_spec.rb:42", + "bin/rspec spec/models/movie_spec.rb:42", + ], + [ + "env 'RAILS_ENV=test' bundle exec rspec spec/models/movie_spec.rb", + "bundle exec rspec spec/models/movie_spec.rb", + ], + [ + "npm_config_registry=https://r.example.test PASS=a\\ b rspec spec/x_spec.rb", + "rspec spec/x_spec.rb", + ], + // The multiline quoted assignment from review: the whole value goes. + [ + '\'APP_CONFIG={\n "tenant": "Team West"\n}\' bin/rspec spec/models/movie_spec.rb', + "bin/rspec spec/models/movie_spec.rb", + ], + // The quoted assignment followed by a quoted argument, from review: an + // -e option is not a spec path, so the field is left out. + [ + "env 'RAILS_ENV=test' bin/rspec spec/models/movie_spec.rb -e 'creates a movie'", + undefined, + ], + // A spec directory with a trailing slash is sent without it. + ["bundle exec rspec spec/models/", "bundle exec rspec spec/models"], + [ + "rspec ./spec/requests// spec/models/a_spec.rb:3", + "rspec ./spec/requests spec/models/a_spec.rb:3", + ], + ["rspec spec/", undefined], + ["rspec spec//models/a_spec.rb", undefined], + ["bin/rubocop", undefined], + ["bin/rails runner 1", undefined], + ["rspec", undefined], + // A parent segment in any argument, not only the last. + ["rspec spec/.. spec/models", undefined], + ["rspec spec/models/../ spec/models/post_spec.rb", undefined], + ["rspec spec/models/post_spec.rb:3 spec/..", undefined], + ["rspec spec/a..b_spec.rb", "rspec spec/a..b_spec.rb"], + ["rspec /Users/sam/app/spec/a_spec.rb", undefined], + ["rspec spec/../../etc/a_spec.rb", undefined], + ["rspec spec/a_spec.rb; curl https://example.test", undefined], + ["RAILS_ENV=test", undefined], + ["'unterminated bin/rspec spec/a_spec.rb", undefined], + ])) { + assert.equal(rspecRun(command), expected, command); + } +}); + +test("free text keeps the plain words before its first quote character", () => { + for (const [text, expected] of /** @type {[string, string][]} */ ([ + // Codex's two inputs: quotes are never paired, so nothing past the + // first one survives, even across a line break. + [`couldn't read "/Users/O'Brien/Client North Team/data.rb" today`, "[…]"], + [ + "Setting 'BUILD_LABEL=North West Research\nlater' it closes", + "Setting […]", + ], + [`load "/Users/O'Brien/First Draft/report.rb" now`, "load […]"], + ["undefined method 'stars' for nil:NilClass", "undefined method […]"], + ["can't find `x`", "[…]"], + ["`x` first", "[…]"], + [ + "Validation failed: Email has already been taken", + "Validation failed: Email has already been taken", + ], + ["first line\nsecond line with a secret", "first line"], + [ + "sam@example.com at https://x.test/a and C:\\Users\\sam", + "[…] at […] and […]", + ], + ["LABEL=North West", "[…] West"], + ["token fd_abcdefghijklmnopqrstuvwxyz", "token […]"], + ["Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.abc", "Bearer […]"], + ["tabs\tand\u0007 bells", "tabs and bells"], + // Unicode line breaks end the first line too. + ["First line\u2028Second line", "First line"], + ["First line\u2029Second line", "First line"], + ["First line\u0085Second line", "First line"], + ])) { + assert.equal(plainWords(text, 300), expected, text); + } + const long = plainWords("word ".repeat(100), 300); + assert.equal(long.split(" ").length, 60); + assert.ok(Array.from(long).length <= 300); + assert.equal(plainWords("Guarded the nil 'x' case", 12), "Guarded the"); +}); + +test("free text with no plain words is left out and named", () => { + const { body, omitted } = failureReportBody( + { kind: "spec_failure", message: "\nsecond line", fixSummary: " " }, + CWD, + ); + assert.deepEqual(body.failure_report, { kind: "spec_failure" }); + assert.deepEqual(omitted, [ + "message, which has no plain words on its first line", + "fix_summary, which has no plain words on its first line", + ]); +}); + +test("a progress count of the service's maximum is sent", async (context) => { + /** @type {unknown} */ + let sent; + const result = await invoke([...PROGRESS, "--examples", "1000000"], { + cwd: projectDirectory(context, PRODUCTION), + fetchFunction: async (_input, init) => { + sent = JSON.parse(String(init?.body)); + return acknowledgment("progress_report"); + }, + }); + assert.equal(result.status, 0, result.stderr); + assert.deepEqual(sent, { + progress_report: { step: "setup", counts: { examples: 1000000 } }, + }); +}); + +test("frames, error classes, and versions keep only their shapes", () => { + const { body, omitted } = failureReportBody( + { + kind: "spec_failure", + errorClass: "ActiveRecord::RecordInvalid", + frames: [ + "app/models/movie.rb:12:in 'Movie#rate'", + "./spec/models/movie_spec.rb:3", + `${CWD}/lib/tasks/import.rb:7`, + "app\\controllers\\movies_controller.rb:9", + "/usr/lib/ruby/3.4.0/forwardable.rb:238", + "../other/lib/x.rb:1", + "app/models/movie.rb", + "vendor/bundle/x.rb:1", + "app/models/my movie.rb:1", + ], + rubyVersion: "3.4.7", + railsVersion: "8.1", + }, + CWD, + ); + assert.deepEqual(body.failure_report, { + kind: "spec_failure", + error_class: "ActiveRecord::RecordInvalid", + frames: [ + "app/models/movie.rb:12", + "spec/models/movie_spec.rb:3", + "lib/tasks/import.rb:7", + "app/controllers/movies_controller.rb:9", + ], + versions: { ruby: "3.4.7", rails: "8.1" }, + }); + assert.deepEqual(omitted, [ + "5 frames not in the application's files with a line number", + ]); + + for (const errorClass of [ + "Rails/Delegate", + "no_method_error", + "Foo::", + "A::b", + ]) { + const shaped = failureReportBody({ kind: "lint_failure", errorClass }, CWD); + assert.equal(shaped.body.failure_report.error_class, undefined, errorClass); + } +}); + +test("a malformed Project state is reported, not replaced by an archived one", async (context) => { + const cwd = projectDirectory(context, PRODUCTION); + writeFileSync(path.join(cwd, ".firstdraft", "state.json"), "{canary\n"); + const design = path.join(cwd, ".firstdraft", "design", ".firstdraft"); + mkdirSync(design, { recursive: true }); + writeFileSync( + path.join(design, "state.json"), + `${JSON.stringify({ + format: "firstdraft.cli-state/1", + project_id: "01900000-0000-7000-8000-000000009199", + api_url: PRODUCTION, + foundation_plan_etag: '"sha256:' + "1".repeat(64) + '"', + })}\n`, + ); + const result = await invoke(PROGRESS, { cwd }); + assert.equal(result.status, 1); + assert.equal(result.stdout, ""); + assert.equal(JSON.parse(result.stderr).error, "local_input_unreadable"); +}); + +test("reports run from an adopted application root find the archived Project", async (context) => { + const root = temporaryDirectory(context); + const design = path.join(root, ".firstdraft", "design"); + mkdirSync(design, { recursive: true }); + writeFileSync(path.join(root, ".firstdraft", "gaps.json"), "{}\n"); + mkdirSync(path.join(design, ".firstdraft")); + writeFileSync( + path.join(design, ".firstdraft", "state.json"), + `${JSON.stringify({ + format: "firstdraft.cli-state/1", + project_id: PROJECT_ID, + api_url: PRODUCTION, + foundation_plan_etag: '"sha256:' + "1".repeat(64) + '"', + })}\n`, + ); + /** @type {{url: string, body: string}[]} */ + const requests = []; + const result = await invoke( + [ + ...FAILURE, + "--frame", + `${root}/app/models/movie.rb:12:in 'Movie#rate'`, + "--frame", + "../other_project/lib/work.rb:10", + "--frame", + "app/../../outside.rb:1", + ], + { + cwd: root, + fetchFunction: async (input, init) => { + requests.push({ url: String(input), body: String(init?.body) }); + return acknowledgment("failure_report"); + }, + }, + ); + + assert.equal(result.status, 0, result.stderr); + assert.equal(requests.length, 1); + assert.equal( + requests[0]?.url, + `${PRODUCTION}/v1/projects/${PROJECT_ID}/compilations/${COMPILATION_ID}/failure-reports`, + ); + assert.deepEqual( + JSON.parse(String(requests[0]?.body)).failure_report.frames, + ["app/models/movie.rb:12"], + ); +}); + +/** @param {string} wrapper the report's key in First Draft's acknowledgment */ +function acknowledgment(wrapper) { + const report = { id: STORED_ID, compilation_id: COMPILATION_ID }; + return new Response(JSON.stringify({ [wrapper]: report }), { + status: 201, + headers: { "Content-Type": "application/json" }, + }); +} + +/** + * @param {number} status + * @param {string} code + * @param {string} detail + */ +function problem(status, code, detail) { + const titles = /** @type {Record} */ ({ + 400: "Bad Request", + 401: "Unauthorized", + 403: "Forbidden", + 404: "Not Found", + }); + return new Response( + JSON.stringify({ + type: "about:blank", + title: titles[status], + status, + code, + detail, + }), + { status, headers: { "Content-Type": "application/problem+json" } }, + ); +} + +/** + * @param {import("node:test").TestContext} context + * @param {string} [origin] + */ +function projectDirectory(context, origin) { + const cwd = temporaryDirectory(context); + mkdirSync(path.join(cwd, ".firstdraft")); + writeFileSync( + path.join(cwd, ".firstdraft", "state.json"), + `${JSON.stringify({ + format: "firstdraft.cli-state/1", + project_id: PROJECT_ID, + ...(origin + ? { + api_url: origin, + foundation_plan_etag: '"sha256:' + "1".repeat(64) + '"', + } + : {}), + })}\n`, + ); + return cwd; +} + +/** @param {import("node:test").TestContext} context */ +function temporaryDirectory(context) { + const cwd = realpathSync( + mkdtempSync(path.join(tmpdir(), "firstdraft-report-")), + ); + context.after(() => rmSync(cwd, { recursive: true, force: true })); + return cwd; +} + +/** @param {readonly string[]} argv @param {Partial} [options] */ +async function invoke(argv, options = {}) { + let stdout = ""; + let stderr = ""; + const status = await run({ + argv, + stdout: { write: (text) => (stdout += text) }, + stderr: { write: (text) => (stderr += text) }, + cwd: CWD, + apiToken: TOKEN, + stagingApiToken: STAGING_TOKEN, + apiUrl: undefined, + env: { XDG_CONFIG_HOME: "/nonexistent/firstdraft-test-config" }, + fetchFunction: async () => assert.fail("No network request was expected"), + ...options, + }); + return { status, stdout, stderr }; +} diff --git a/test/service-client.test.js b/test/service-client.test.js new file mode 100644 index 0000000..9333538 --- /dev/null +++ b/test/service-client.test.js @@ -0,0 +1,834 @@ +import assert from "node:assert/strict"; +import { createHash } from "node:crypto"; +import { mkdtempSync, readFileSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import test from "node:test"; + +import { run } from "../src/cli.js"; +import { CompilationRetainedError } from "../src/commands/compilation.js"; +import { + API_CONTRACT_RANGE, + ApiContractUnsupportedError, + RateLimitedError, + UpdateRequiredError, + compareVersions, + createServiceSession, +} from "../src/service-client.js"; +import { VERSION } from "../src/version.js"; + +const ORIGIN = "https://firstdraft.com"; +const PROJECT_ID = "01900000-0000-7000-8000-000000009001"; +const COMPILATION_ID = "01900000-0000-7000-8000-000000009002"; +const TOKEN = "canary-service-token"; +const ETAG = '"sha256:' + "a".repeat(64) + '"'; +const NOW = Date.parse("2026-11-20T12:00:00.000Z"); +const UPDATE_URL = "https://firstdraft.com/update"; + +test("FirstDraft-Client names the CLI, plugin, agent, and operating system", async () => { + /** @type {Headers[]} */ + const sent = []; + const session = createServiceSession({ + env: { FIRSTDRAFT_PLUGIN_VERSION: "0.10.2", FIRSTDRAFT_AGENT: "codex" }, + notify: () => assert.fail("No update line was expected"), + platform: "linux", + }); + const request = session.fetch(async (_input, init) => { + sent.push(new Headers(init?.headers)); + return new Response(null, { status: 204 }); + }); + + await request(new URL("/v1/account", ORIGIN), { + headers: { Authorization: "Bearer x" }, + }); + await request(new URL("/oauth/token", ORIGIN), {}); + + for (const headers of sent) { + assert.equal( + headers.get("firstdraft-client"), + `cli/${VERSION}; plugin/0.10.2; agent/codex; os/linux`, + ); + } + assert.equal(sent[0]?.get("authorization"), "Bearer x"); +}); + +test("FirstDraft-Client keeps to the grammar the Service parses", () => { + const session = createServiceSession({ + env: { + FIRSTDRAFT_PLUGIN_VERSION: "0.10.2+ci.7", + FIRSTDRAFT_AGENT: "Codex", + }, + notify: () => undefined, + platform: "win32", + }); + assert.equal( + session.clientHeader, + `cli/${VERSION}; plugin/0.10.2; agent/codex; os/win32`, + ); +}); + +test("FirstDraft-Client leaves out a value longer than the Service accepts", () => { + const long = `0.10.0-${"a".repeat(58)}`; + assert.equal( + createServiceSession({ + env: { FIRSTDRAFT_PLUGIN_VERSION: long, FIRSTDRAFT_AGENT: "codex" }, + notify: () => undefined, + platform: "linux", + }).clientHeader, + `cli/${VERSION}; agent/codex; os/linux`, + ); +}); + +test("FirstDraft-Client omits parts that are unknown or not safe to send", async () => { + for (const env of [ + {}, + { FIRSTDRAFT_PLUGIN_VERSION: "latest", FIRSTDRAFT_AGENT: "" }, + { FIRSTDRAFT_PLUGIN_VERSION: "0.10", FIRSTDRAFT_AGENT: "claude code" }, + { FIRSTDRAFT_PLUGIN_VERSION: "v0.10.0", FIRSTDRAFT_AGENT: "a\nb" }, + ]) { + const session = createServiceSession({ + env, + notify: () => undefined, + platform: "darwin", + }); + assert.equal(session.clientHeader, `cli/${VERSION}; os/darwin`); + } + assert.equal( + createServiceSession({ + env: {}, + notify: () => undefined, + platform: "Bad Platform", + }).clientHeader, + `cli/${VERSION}`, + ); +}); + +test("an older plugin prints one update line per command, however many requests it makes", async () => { + /** @type {string[]} */ + const lines = []; + const session = createServiceSession({ + env: { FIRSTDRAFT_PLUGIN_VERSION: "0.10.0" }, + notify: (line) => lines.push(line), + }); + const request = session.fetch(async () => + versionedResponse({ latest: "0.10.1", minimum: "0.10.0" }), + ); + + for (let index = 0; index < 3; index += 1) { + await request(new URL("/v1/account", ORIGIN), {}); + } + + // The line waits for the command's outcome, then comes just before it. + assert.deepEqual(lines, []); + assert.equal(await session.settle(Promise.resolve("done")), "done"); + session.flush(); + assert.deepEqual(lines, [ + `First Draft: an update is available (plugin 0.10.1; this setup has plugin 0.10.0). Tell the person the update steps are at ${UPDATE_URL}\n`, + ]); +}); + +test("without a plugin version the CLI compares itself with the CLI versions", async () => { + /** @type {string[]} */ + const lines = []; + const session = createServiceSession({ + env: {}, + notify: (line) => lines.push(line), + }); + await session.fetch(async () => + versionedResponse({ + latest: "99.0.0", + minimum: "99.0.0", + latestCli: "98.0.0", + minimumCli: "0.1.0", + }), + )(new URL("/v1/account", ORIGIN), {}); + assert.equal(await session.settle(Promise.resolve("done")), "done"); + + assert.deepEqual(lines, [ + `First Draft: an update is available (CLI 98.0.0; this setup has CLI ${VERSION}). Tell the person the update steps are at ${UPDATE_URL}\n`, + ]); +}); + +test("a set but unreadable plugin version compares neither pair and says so", async () => { + for (const pluginVersion of ["dev", "", " "]) { + /** @type {string[]} */ + const lines = []; + const session = createServiceSession({ + env: { FIRSTDRAFT_PLUGIN_VERSION: pluginVersion }, + notify: (line) => lines.push(line), + }); + assert.equal(session.clientHeader.includes("plugin/"), false); + const request = session.fetch(async () => + versionedResponse({ + latest: "99.0.0", + minimum: "99.0.0", + latestCli: "99.0.0", + minimumCli: "99.0.0", + }), + ); + await request(new URL("/v1/account", ORIGIN), {}); + await request(new URL("/v1/account", ORIGIN), {}); + assert.equal(await session.settle(Promise.resolve("done")), "done"); + assert.deepEqual(lines, [ + `First Draft: FIRSTDRAFT_PLUGIN_VERSION is set but is not a plugin version, so the CLI could not tell whether this setup is current. The update steps are at ${UPDATE_URL}\n`, + ]); + } +}); + +test("half a version pair is not compared", async () => { + for (const [ + env, + versions, + ] of /** @type {[Record, Record][]} */ ([ + [{}, { minimumCli: "99.0.0" }], + [{}, { latestCli: "99.0.0" }], + [{ FIRSTDRAFT_PLUGIN_VERSION: "0.10.0" }, { minimum: "99.0.0" }], + [ + { FIRSTDRAFT_PLUGIN_VERSION: "0.10.0" }, + { latest: "99.0.0", minimum: "soon" }, + ], + ])) { + const session = createServiceSession({ + env, + notify: () => + assert.fail(`No line was expected for ${JSON.stringify(versions)}`), + }); + const request = session.fetch(async () => versionedResponse(versions)); + await request(new URL("/v1/account", ORIGIN), {}); + await request(new URL("/v1/account", ORIGIN), {}); + assert.equal(await session.settle(Promise.resolve("done")), "done"); + } +}); + +test("each setup reads only its own pair of version headers", async () => { + for (const [ + env, + versions, + ] of /** @type {[Record, Record][]} */ ([ + // A plugin ignores the CLI versions. + [ + { FIRSTDRAFT_PLUGIN_VERSION: "0.10.0" }, + { latestCli: "99.0.0", minimumCli: "99.0.0" }, + ], + // A bare CLI ignores the plugin versions, and an older Service sends no CLI pair. + [{}, { latest: "99.0.0", minimum: "99.0.0" }], + [{}, {}], + ])) { + const session = createServiceSession({ + env, + notify: () => + assert.fail(`No line was expected for ${JSON.stringify(versions)}`), + }); + const request = session.fetch(async () => versionedResponse(versions)); + await request(new URL("/v1/account", ORIGIN), {}); + await request(new URL("/v1/account", ORIGIN), {}); + assert.equal(await session.settle(Promise.resolve("done")), "done"); + } +}); + +test("a current, newer, or unreadable latest version prints nothing", async () => { + for (const latest of ["0.10.0", "0.9.9", "0.10.0-rc.1", "soon", ""]) { + const session = createServiceSession({ + env: { FIRSTDRAFT_PLUGIN_VERSION: "0.10.0" }, + notify: () => assert.fail(`No update line was expected for ${latest}`), + }); + await session.fetch(async () => versionedResponse({ latest }))( + new URL("/v1/account", ORIGIN), + {}, + ); + } +}); + +test("below the minimum, the CLI finishes that response and sends nothing more", async () => { + let requests = 0; + const session = createServiceSession({ + env: { FIRSTDRAFT_PLUGIN_VERSION: "0.9.3" }, + notify: () => assert.fail("A cut-short command prints no stop line"), + }); + const request = session.fetch(async () => { + requests += 1; + return versionedResponse({ latest: "0.10.1", minimum: "0.10.0" }); + }); + + const response = await request(new URL("/v1/account", ORIGIN), {}); + assert.equal(response.status, 200); + const blocked = request(new URL("/v1/account", ORIGIN), {}); + await assert.rejects(blocked, UpdateRequiredError); + assert.equal(requests, 1); + + const cause = new Error("the blocked request failed"); + await assert.rejects(session.settle(Promise.reject(cause)), (error) => { + assert(error instanceof UpdateRequiredError); + assert.equal(error.component, "plugin"); + assert.equal(error.installed, "0.9.3"); + assert.equal(error.minimum, "0.10.0"); + assert.equal(error.replaced, cause); + return true; + }); +}); + +test("a stop that did not cut the command short keeps its result and names the stop", async () => { + const stopLine = `First Draft: First Draft requires plugin 0.10.0 or later, and this setup has plugin 0.9.3. This command finished; tell the person to update with the steps at ${UPDATE_URL} before the next one.\n`; + for (const work of [ + Promise.resolve("finished"), + Promise.reject(new TypeError("its own local failure")), + ]) { + /** @type {string[]} */ + const lines = []; + const session = createServiceSession({ + env: { FIRSTDRAFT_PLUGIN_VERSION: "0.9.3" }, + notify: (line) => lines.push(line), + }); + await session.fetch(async () => + versionedResponse({ latest: "0.10.0", minimum: "0.10.0" }), + )(new URL("/v1/account", ORIGIN), {}); + + const outcome = await session.settle(work).then( + (value) => value, + (error) => error, + ); + assert.equal(outcome, await work.catch((error) => error)); + assert.deepEqual(lines, [stopLine]); + } +}); + +test("the CLI accepts only its declared API contract range", async () => { + assert.deepEqual(API_CONTRACT_RANGE, [">= 0.9.0", "< 0.10.0"]); + + for (const contract of [ + "0.9.0", + "0.9.7", + " 0.9.1 ", + "0.9.2+build.7", + "unknown", + "0.10", + ]) { + const session = createServiceSession({ + env: {}, + notify: () => assert.fail(`${contract} is accepted`), + }); + await session.fetch(async () => versionedResponse({ contract }))( + new URL("/v1/account", ORIGIN), + {}, + ); + assert.equal(await session.settle(Promise.resolve(contract)), contract); + } + + for (const [contract, kind] of /** @type {[string, string][]} */ ([ + ["0.10.0", "newer"], + ["0.10.0+build.7", "newer"], + ["0.10.0-rc.1", "newer"], + ["1.0.0", "newer"], + ["0.8.1", "older"], + ["0.9.0-rc.1", "older"], + ["0.9.1-rc.1", "prerelease"], + ])) { + const session = createServiceSession({ env: {}, notify: () => undefined }); + const request = session.fetch(async () => versionedResponse({ contract })); + await request(new URL("/v1/account", ORIGIN), {}); + const cutShort = request(new URL("/v1/account", ORIGIN), {}); + await assert.rejects(session.settle(cutShort), (error) => { + assert(error instanceof ApiContractUnsupportedError); + assert.equal(error.contract, contract); + assert.equal(error.kind, kind); + assert.equal(error.origin, ORIGIN); + return true; + }); + } +}); + +test("a 429 stops the command with the retry time and the validated problem", async () => { + for (const [ + retryAfter, + retryAt, + ] of /** @type {[string | null, string | undefined][]} */ ([ + ["3600", "2026-11-20T13:00:00Z"], + ["Fri, 21 Nov 2026 00:00:00 GMT", "2026-11-21T00:00:00Z"], + ["tomorrow-ish", undefined], + [null, undefined], + ])) { + const session = createServiceSession({ + env: {}, + notify: () => assert.fail("A 429 replaces the result"), + now: () => NOW, + }); + const response = await session.fetch(async () => limitResponse(retryAfter))( + new URL("/v1/projects/x/compilations", ORIGIN), + {}, + ); + const limit = /** @type {{code: string}} */ (await response.json()); + assert.equal(limit.code, "daily_compilation_limit"); + + await assert.rejects(session.settle(Promise.resolve()), (error) => { + assert(error instanceof RateLimitedError); + assert.equal(error.retryAt, retryAt); + assert.deepEqual(error.response, LIMIT_PROBLEM); + return true; + }); + } +}); + +test("a 429 that is the command's first response still carries the update notice", async () => { + /** @type {string[]} */ + const lines = []; + const session = createServiceSession({ + env: { FIRSTDRAFT_PLUGIN_VERSION: "0.10.0" }, + notify: (line) => lines.push(line), + now: () => NOW, + }); + const limited = limitResponse("60"); + limited.headers.set("FirstDraft-Latest-Plugin", "0.10.1"); + limited.headers.set("FirstDraft-Minimum-Plugin", "0.9.0"); + await session.fetch(async () => limited)(new URL("/v1/account", ORIGIN), {}); + await assert.rejects(session.settle(Promise.resolve()), RateLimitedError); + assert.equal(lines.length, 1); + assert.match(String(lines[0]), /^First Draft: an update is available/); +}); + +test("a 429 without Retry-After or a problem says to wait a minute", async () => { + const result = await invoke(["account"], { + fetchFunction: async () => + new Response('{"error":"temporarily_unavailable"}', { + status: 429, + headers: { "Content-Type": "application/json" }, + }), + }); + assert.equal(result.status, 1); + assert.deepEqual(JSON.parse(result.stderr), { + error: "rate_limited", + detail: + "First Draft refused a request because a limit was reached. The refused request did nothing, and the CLI sent nothing after it. Try again in a minute.", + status: 429, + }); +}); + +test("a 429 reports the limit even when the response also requires an update", async () => { + for (const headers of [ + { "FirstDraft-Minimum-CLI": "99.0.0" }, + { "FirstDraft-API-Contract": "0.10.0" }, + ]) { + const session = createServiceSession({ + env: {}, + notify: () => assert.fail("The limit is the command's outcome"), + now: () => NOW, + }); + const limited = limitResponse("3600"); + for (const [name, value] of Object.entries(headers)) { + limited.headers.set(name, value); + } + await session.fetch(async () => limited)( + new URL("/v1/account", ORIGIN), + {}, + ); + await assert.rejects(session.settle(Promise.resolve()), (error) => { + assert(error instanceof RateLimitedError); + assert.equal(error.retryAt, "2026-11-20T13:00:00Z"); + return true; + }); + } +}); + +test("the stop line for an older or prerelease contract does not advise updating", async () => { + for (const [contract, sentence] of /** @type {[string, string][]} */ ([ + ["0.8.7", "serves API contract 0.8.7, which is older than"], + ["0.9.1-rc.1", "serves prerelease API contract 0.9.1-rc.1, which"], + ])) { + /** @type {string[]} */ + const lines = []; + const session = createServiceSession({ + env: {}, + notify: (line) => lines.push(line), + }); + await session.fetch(async () => versionedResponse({ contract }))( + new URL("/v1/account", ORIGIN), + {}, + ); + assert.equal(await session.settle(Promise.resolve("done")), "done"); + assert.equal(lines.length, 1); + assert.ok(lines[0]?.includes(sentence), lines[0]); + assert.ok( + lines[0]?.endsWith( + "This command finished; use the CLI version that this First Draft origin supports before the next one.\n", + ), + lines[0], + ); + } +}); + +test("a command writes one version line, the stop line replacing an earlier notice", async () => { + /** @type {string[]} */ + const lines = []; + const session = createServiceSession({ + env: { FIRSTDRAFT_PLUGIN_VERSION: "0.10.0" }, + notify: (line) => lines.push(line), + }); + const request = session.fetch( + (() => { + const responses = [ + versionedResponse({ latest: "0.10.1", minimum: "0.9.0" }), + versionedResponse({ latest: "0.11.0", minimum: "0.11.0" }), + ]; + return async () => /** @type {Response} */ (responses.shift()); + })(), + ); + await request(new URL("/v1/account", ORIGIN), {}); + assert.deepEqual(lines, []); + await request(new URL("/v1/account", ORIGIN), {}); + assert.equal(await session.settle(Promise.resolve("done")), "done"); + assert.deepEqual(lines, [ + `First Draft: First Draft requires plugin 0.11.0 or later, and this setup has plugin 0.10.0. This command finished; tell the person to update with the steps at ${UPDATE_URL} before the next one.\n`, + ]); +}); + +test("SemVer precedence orders prereleases before their release", () => { + const ordered = [ + "0.9.0-alpha", + "0.9.0-alpha.1", + "0.9.0-alpha.beta", + "0.9.0-beta.2", + "0.9.0-beta.11", + "0.9.0-rc.1", + "0.9.0", + "0.9.1", + "0.10.0", + "1.0.0", + ].map(parse); + + for (let index = 1; index < ordered.length; index += 1) { + const [left, right] = [ordered[index - 1], ordered[index]]; + assert(left && right); + assert.equal( + compareVersions(left, right), + -1, + `${left.text} < ${right.text}`, + ); + assert.equal(compareVersions(right, left), 1); + assert.equal(compareVersions(left, left), 0); + } +}); + +test("an oversized 429 body is read once and does not stall the command", async () => { + const chunk = new Uint8Array(16 * 1024).fill(32); + let pulls = 0; + const session = createServiceSession({ env: {}, notify: () => undefined }); + const response = await session.fetch( + async () => + new Response( + new ReadableStream({ + pull(controller) { + pulls += 1; + if (pulls > 10) controller.close(); + else controller.enqueue(chunk); + }, + }), + { + status: 429, + headers: { + "Content-Type": "application/problem+json", + "Retry-After": "60", + }, + }, + ), + )(new URL("/v1/projects/x/compilations", ORIGIN), {}); + + assert.equal(response.status, 429); + assert.equal(await response.text(), ""); + await assert.rejects(session.settle(Promise.resolve()), (error) => { + assert(error instanceof RateLimitedError); + assert.equal(error.response, null); + return true; + }); +}); + +test("plan push keeps its accepted result below the minimum and names the stop", async (context) => { + const cwd = await initializedProject(context); + let requests = 0; + const result = await invoke(["plan", "push"], { + cwd, + env: { FIRSTDRAFT_PLUGIN_VERSION: "0.9.3" }, + fetchFunction: async () => { + requests += 1; + return acceptedPush(cwd, { latest: "0.10.0", minimum: "0.10.0" }); + }, + }); + + assert.equal(requests, 1); + assert.equal(result.status, 0); + assert.equal(JSON.parse(result.stdout).etag, ETAG); + assert.equal( + result.stderr, + `First Draft: First Draft requires plugin 0.10.0 or later, and this setup has plugin 0.9.3. This command finished; tell the person to update with the steps at ${UPDATE_URL} before the next one.\n`, + ); + assert.equal(readState(cwd).foundation_plan_etag, ETAG); +}); + +test("plan compile sends nothing after a response below the minimum", async (context) => { + const cwd = await initializedProject(context); + /** @type {string[]} */ + const requests = []; + const result = await invoke(["plan", "compile", "--output", "application"], { + cwd, + env: {}, + fetchFunction: async (input, init) => { + requests.push(`${init?.method} ${new URL(String(input)).pathname}`); + return acceptedPush(cwd, { latestCli: "99.0.0", minimumCli: "99.0.0" }); + }, + }); + + assert.deepEqual(requests, [ + `PUT /v1/projects/${PROJECT_ID}/foundation-plan`, + ]); + assert.equal(result.status, 1); + assert.equal(result.stdout, ""); + assert.deepEqual(errorEnvelope(result.stderr), { + error: "update_required", + detail: `First Draft requires CLI 99.0.0 or later, and this setup has CLI ${VERSION}. The CLI stopped before the command finished and sent nothing more. Tell the person to update with the steps at ${UPDATE_URL}, then run the same command again, with the same options.`, + cli_version: VERSION, + minimum_cli_version: "99.0.0", + update_url: UPDATE_URL, + }); + assert.equal(readState(cwd).foundation_plan_etag, ETAG); +}); + +test("a stop after a Compilation started names it instead of advising another", async (context) => { + const cwd = await initializedProject(context); + const current = { + project: { id: PROJECT_ID, graph_version: 1 }, + compilation: { id: COMPILATION_ID, status: "queued" }, + }; + const result = await invoke(["plan", "compile", "--output", "application"], { + cwd, + planCompilePush: async () => ({ + outcome: "updated", + etag: ETAG, + status: 200, + body: { + project: { id: PROJECT_ID, graph_version: 1 }, + foundation_plan: { source_sha256: "a".repeat(64) }, + diagnostics: [], + }, + }), + planCompileReadStatus: async () => ({ + status: 200, + body: /** @type {any} */ ({ + project: { id: PROJECT_ID, graph_version: 1 }, + analysis: { + id: COMPILATION_ID, + graph_version: 1, + head_source_sha256: "a".repeat(64), + status: "valid", + compiler_release: "release", + target: { id: "rails", profile: "profile" }, + }, + }), + }), + planCompileDownload: async ({ fetchFunction }) => { + assert(fetchFunction); + const url = new URL(`/v1/projects/${PROJECT_ID}/compilations`, ORIGIN); + await fetchFunction(url, {}); + const error = await fetchFunction(url, {}).catch((cause) => cause); + throw new CompilationRetainedError(error, /** @type {any} */ (current)); + }, + fetchFunction: async () => + versionedResponse({ latestCli: "99.0.0", minimumCli: "99.0.0" }), + }); + + assert.equal(result.status, 1); + assert.deepEqual(errorEnvelope(result.stderr), { + error: "update_required", + detail: `First Draft requires CLI 99.0.0 or later, and this setup has CLI ${VERSION}. The CLI stopped before the command finished and sent nothing more. Tell the person to update with the steps at ${UPDATE_URL}, then follow the Compilation that had already started with 'firstdraft compilation status ${COMPILATION_ID}' instead of compiling again.`, + cli_version: VERSION, + minimum_cli_version: "99.0.0", + update_url: UPDATE_URL, + current, + }); +}); + +test("a Service outside the API contract range is refused with both versions", async (context) => { + const cwd = await initializedProject(context); + const result = await invoke(["plan", "compile", "--output", "application"], { + cwd, + fetchFunction: async () => acceptedPush(cwd, { contract: "0.10.0" }), + }); + + assert.equal(result.status, 1); + assert.deepEqual(errorEnvelope(result.stderr), { + error: "api_contract_unsupported", + detail: `First Draft at ${ORIGIN} serves API contract 0.10.0, which is newer than CLI ${VERSION} accepts. The CLI stopped before the command finished and sent nothing more. Tell the person to update with the steps at ${UPDATE_URL}, then run the same command again, with the same options.`, + api_contract: "0.10.0", + accepted_api_contract: [">= 0.9.0", "< 0.10.0"], + cli_version: VERSION, + update_url: UPDATE_URL, + }); +}); + +test("a daily cap reports rate_limited with when to try again", async (context) => { + const cwd = await initializedProject(context); + const result = await invoke(["plan", "push"], { + cwd, + serviceNow: () => NOW, + fetchFunction: async () => limitResponse("43200"), + }); + + assert.equal(result.status, 1); + assert.deepEqual(JSON.parse(result.stderr), { + error: "rate_limited", + detail: + "First Draft refused a request because a limit was reached. The refused request did nothing, and the CLI sent nothing after it. Try again after 2026-11-21T00:00:00Z; response.detail, when present, says which limit.", + status: 429, + retry_at: "2026-11-21T00:00:00Z", + response: LIMIT_PROBLEM, + }); + assert.equal(readState(cwd).foundation_plan_etag, undefined); +}); + +test("the update line precedes the command's own output on stderr", async (context) => { + const cwd = await initializedProject(context); + const result = await invoke(["plan", "push"], { + cwd, + env: { FIRSTDRAFT_PLUGIN_VERSION: "0.10.0" }, + fetchFunction: async () => + acceptedPush(cwd, { latest: "0.10.4", minimum: "0.10.0" }), + }); + + assert.equal(result.status, 0); + assert.equal(JSON.parse(result.stdout).etag, ETAG); + assert.equal( + result.stderr, + `First Draft: an update is available (plugin 0.10.4; this setup has plugin 0.10.0). Tell the person the update steps are at ${UPDATE_URL}\n`, + ); +}); + +const LIMIT_PROBLEM = { + type: "about:blank", + title: "Too Many Requests", + status: 429, + code: "daily_compilation_limit", + detail: + "This account has started 50 Compilations today. Try again after midnight UTC.", +}; + +/** @param {string | null} retryAfter */ +function limitResponse(retryAfter) { + return new Response(JSON.stringify(LIMIT_PROBLEM), { + status: 429, + headers: { + "Content-Type": "application/problem+json", + ...(retryAfter === null ? {} : { "Retry-After": retryAfter }), + }, + }); +} + +/** + * @param {{latest?: string, minimum?: string, latestCli?: string, minimumCli?: string, contract?: string}} versions + * @param {string | null} [body] + * @param {Record} [headers] + */ +function versionedResponse( + { latest, minimum, latestCli, minimumCli, contract }, + body = null, + headers = {}, +) { + return new Response(body, { + status: body === null ? 200 : 201, + headers: { + ...headers, + ...(latest === undefined ? {} : { "FirstDraft-Latest-Plugin": latest }), + ...(minimum === undefined + ? {} + : { "FirstDraft-Minimum-Plugin": minimum }), + ...(latestCli === undefined + ? {} + : { "FirstDraft-Latest-CLI": latestCli }), + ...(minimumCli === undefined + ? {} + : { "FirstDraft-Minimum-CLI": minimumCli }), + ...(contract === undefined + ? {} + : { "FirstDraft-API-Contract": contract }), + }, + }); +} + +/** + * @param {string} cwd + * @param {{latest?: string, minimum?: string, latestCli?: string, minimumCli?: string, contract?: string}} versions + */ +function acceptedPush(cwd, versions) { + const source = readFileSync( + path.join(cwd, ".firstdraft", "foundation-plan.json"), + ); + return versionedResponse( + versions, + JSON.stringify({ + project: { id: PROJECT_ID, graph_version: 1 }, + foundation_plan: { + format: "firstdraft.foundation-plan.sketch/0.23", + source_sha256: createHash("sha256").update(source).digest("hex"), + }, + diagnostics: [], + }), + { "Content-Type": "application/json", ETag: ETAG }, + ); +} + +/** @param {string} value */ +function parse(value) { + const match = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(value); + assert(match); + return { + major: Number(match[1]), + minor: Number(match[2]), + patch: Number(match[3]), + prerelease: match[4] === undefined ? [] : match[4].split("."), + text: value, + release: value, + }; +} + +/** @param {import("node:test").TestContext} context */ +async function initializedProject(context) { + const cwd = mkdtempSync(path.join(tmpdir(), "firstdraft-service-")); + context.after(() => rmSync(cwd, { recursive: true, force: true })); + const result = await invoke(["plan", "init", "--name", "Oscar Party"], { + cwd, + createProjectId: () => PROJECT_ID, + }); + assert.equal(result.status, 0); + return cwd; +} + +/** @param {string} cwd */ +function readState(cwd) { + return JSON.parse( + readFileSync(path.join(cwd, ".firstdraft", "state.json"), "utf8"), + ); +} + +/** @param {readonly string[]} argv @param {Partial} [options] */ +async function invoke(argv, options = {}) { + let stdout = ""; + let stderr = ""; + const status = await run({ + argv, + stdout: { write: (text) => (stdout += text) }, + stderr: { write: (text) => (stderr += text) }, + apiToken: TOKEN, + stagingApiToken: "", + apiUrl: undefined, + env: {}, + fetchFunction: async () => assert.fail("No network request was expected"), + ...options, + }); + return { status, stdout, stderr }; +} + +/** @param {string} stderr */ +function errorEnvelope(stderr) { + return JSON.parse( + stderr + .split("\n") + .filter((line) => !line.startsWith("First Draft: ")) + .join("\n"), + ); +}