From 69dea4bfeaff2e2e7a5c46310c62548d049ac059 Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Fri, 20 Nov 2026 16:00:49 -0600 Subject: [PATCH 01/14] Adopt the rails-sketch/2026-11 working profile First Draft's next Rails target adopts foundation-rails-core main, which runs jobs, Cable, and the cache in-process and answers its health check at /up, under a new target profile. The Plan format stays sketch/0.23. plan init writes the new profile and artifact validation accepts only it, so a rails-sketch/2026-10 artifact now reports invalid_artifact. The ID is a working one until the release names the profile; it lives only in RAILS_TARGET_PROFILE, and the documentation test keeps the docs naming that constant's value. The plan status zero-gap digest covers the target, so it is recomputed with the Service's serialization, JSON.pretty_generate plus a newline, which reproduces the previous digest for the old profile. --- docs/commands.md | 4 ++-- src/compilation-artifact.js | 6 +++++- test/compilation-artifact.test.js | 2 +- test/plan-status.test.js | 5 +++-- 4 files changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 46b8683..3b72bf9 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -139,7 +139,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. @@ -440,7 +440,7 @@ 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 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/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/plan-status.test.js b/test/plan-status.test.js index 1bb03e0..26299f3 100644 --- a/test/plan-status.test.js +++ b/test/plan-status.test.js @@ -17,6 +17,7 @@ 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"; /** @typedef {{input: string | URL | Request, init: RequestInit | undefined}} FetchCall */ @@ -37,7 +38,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: @@ -250,7 +251,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)], []), From d072b813795615c4b16e0a1aa443e6d9af0f2649 Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Fri, 20 Nov 2026 16:01:20 -0600 Subject: [PATCH 02/14] Rerun once after an ambiguous push or Compile After request_outcome_unknown from a push or a direct Compilation start, the CLI told the agent to stop until First Draft or an operator reconciled the Project. Testers now work on their own, so that left them with no way forward. The Service already makes one rerun safe. A repeated push with the saved ETag either succeeds or is refused with 412. A 412 says only that First Draft holds another Plan, from the first attempt or from another copy of the Project, so the advice is to continue from that copy or fork a new Project. A repeated Compile is refused with compilation_active while the first one runs, which leads into stuck-Compilation recovery; otherwise it starts a second Compilation whose only cost is service time and one of the day's Compilations. The rerun keeps the original options and environment: a first push has no pinned origin yet, and a bare rerun of plan compile would change its output mode. A fork names the old folder's origin for the same reason. Publication keeps its singleton rules. --- docs/errors.md | 34 +++++++++++++++++++++------------- src/cli.js | 6 +++--- test/plan-push.test.js | 2 +- 3 files changed, 25 insertions(+), 17 deletions(-) diff --git a/docs/errors.md b/docs/errors.md index 887dff4..3fcb704 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -64,19 +64,27 @@ writes a note on standard error; revoke the token on `/api-tokens` if it may sti `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 (`api_url` in + its `.firstdraft/state.json`): `--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 +103,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 diff --git a/src/cli.js b/src/cli.js index 2eed6e3..8c059ff 100644 --- a/src/cli.js +++ b/src/cli.js @@ -376,7 +376,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 (api_url in .firstdraft/state.json), with --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 +419,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 (api_url in .firstdraft/state.json), with --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 +429,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 = diff --git a/test/plan-push.test.js b/test/plan-push.test.js index f97012f..e3c2aaf 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 (api_url in .firstdraft/state.json), with --staging for staging or the same FIRSTDRAFT_API_URL for a custom origin.", ...(status === undefined ? {} : { status }), }); } From 5c9f23dc54ae0dcfe17ef848c77792177af1c1bc Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Fri, 20 Nov 2026 16:21:51 -0600 Subject: [PATCH 03/14] State client facts and send reports with consent Testers invited back work alone, so old setups have to say they are old, and First Draft needs to learn what happens in their apps. Every request now carries FirstDraft-Client: the CLI version, the plugin version and agent name from FIRSTDRAFT_PLUGIN_VERSION and FIRSTDRAFT_AGENT (set by the plugin's launcher), and the operating system, in the grammar the Service parses. Login no longer sends the computer's hostname. The CLI reads FirstDraft-Latest-Plugin, FirstDraft-Minimum-Plugin, and FirstDraft-API-Contract on every response. An older plugin, or the CLI when no plugin version is set, gets one update line on stderr per command, just before its result, whether or not a terminal is attached: an agent runs the CLI without one and must pass the line on. Below the minimum or outside API 0.9.x, the CLI finishes handling that response, so an accepted push still saves its ETag, and sends nothing more. Only when that cut the command short does update_required or api_contract_unsupported replace its result, naming a Compilation that had already started. Otherwise the command keeps its result and any local recovery data, after one line naming the stop. A 429 from an account limit always reports rate_limited with retry_at. The range becomes >= 0.9.0, < 0.10.0, and as in npm ranges a prerelease contract is outside it. New commands: account reads whether reports are on; report progress and report failure print the exact report, send it to the Project's pinned origin, and treat reports_off as a message with exit 0 so the agent's work continues. Their routes and fields follow the Service's report endpoints, they print Sent. only on First Draft's 201 acknowledgment, and they find the Project from an adopted application root, where an agent runs its specs. Failure reports replace emails, absolute paths, assignments, credentials, and token-like strings, and keep only frames in the application. conversation send needs --person-agreed each time and prints the file's path, size, and digest before sending. The README's promise now names what each command sends and where the update line comes from. --- README.md | 5 +- docs/commands.md | 207 ++++- docs/errors.md | 133 ++- release/compatibility.json | 2 +- scripts/check-pack.js | 4 + scripts/smoke-package.js | 39 + src/api-authentication.js | 15 +- src/api-response.js | 33 + src/cli.js | 1237 +++++++++++++++++++++++++--- src/commands/account.js | 97 +++ src/commands/conversation.js | 186 +++++ src/commands/login.js | 35 +- src/commands/report.js | 370 +++++++++ src/oauth.js | 17 +- src/plan-state.js | 59 ++ src/service-client.js | 443 ++++++++++ test/account.test.js | 228 +++++ test/api-environments.test.js | 14 + test/cli.test.js | 13 +- test/conversation.test.js | 306 +++++++ test/login.test.js | 13 +- test/plan-status.test.js | 14 +- test/release-compatibility.test.js | 6 + test/report.test.js | 752 +++++++++++++++++ test/service-client.test.js | 729 ++++++++++++++++ 25 files changed, 4709 insertions(+), 248 deletions(-) create mode 100644 src/commands/account.js create mode 100644 src/commands/conversation.js create mode 100644 src/commands/report.js create mode 100644 src/service-client.js create mode 100644 test/account.test.js create mode 100644 test/conversation.test.js create mode 100644 test/report.test.js create mode 100644 test/service-client.test.js 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 3b72bf9..b685955 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. CLI `0.9.x` requires the +service's `0.9.x` API contract. 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,8 +70,8 @@ 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 +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`. Other failures exit with `login_failed`. No credential is saved unless the login succeeds. See [Errors and recovery](errors.md#login-and-logout-errors). @@ -131,6 +136,58 @@ 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-Latest-Plugin`, `FirstDraft-Minimum-Plugin`, and +`FirstDraft-API-Contract`. The CLI checks every response it receives for them; an OAuth answer or a missing route +may carry none, so it then checks nothing. The CLI compares the plugin version from `FIRSTDRAFT_PLUGIN_VERSION`, or +its own version when that variable is unset, with the first two. 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 says `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 with `Retry-After` when an account reaches a limit, such as its + Compilations for the day or its reports for the hour: 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: @@ -386,11 +443,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`, @@ -497,33 +555,108 @@ 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: 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 `--kind` (`spec_failure`, `setup_failure`, `boot_error`, or `lint_failure`), `--rerun` (the +command that reproduces the failure), and `--error-class` (the exception class, or the lint rule's name). `--message`, +`--frame` (repeatable: a place in the application such as `app/models/post.rb:12`), `--fix-summary` (one line on the +agent's fix), `--ruby-version`, and `--rails-version` are optional. Before it prints the report, the CLI removes +terminal escapes and control characters, then replaces email addresses with `[email]`, the value of an +environment-style `NAME=value` assignment (in `--rerun`, of any `name=value` assignment) with `[value]`, absolute +paths (also after an option such as `-I`, in quotes, or as a `file://` URL) with `[path]`, and recognized credential +formats, and runs of 32 or more letters, digits, `_`, or `-` that mix letters and digits, with `[token]`. An absolute +path inside the current directory becomes relative to it instead. A frame outside it, absolute, or reached through +`..` is left out. It keeps the first +300 characters of the rerun command and of the message, 200 of the fix summary, and 20 frames. This is a safeguard, +not a guarantee, so read the printed report. A failure report carries no diff, environment variable, or file +contents. + +Each command writes `Sending this report for Compilation to :` and the exact JSON +body 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 +664,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 +704,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 +715,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 +735,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 3fcb704..f49b71b 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,6 +62,32 @@ 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 than the CLI + when no plugin version is set. `minimum_plugin_version`, `cli_version`, and, when known, `plugin_version` name the + versions. 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 the account reached a limit. The refused request did nothing. + `response.code` 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. 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 @@ -169,6 +198,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 @@ -186,39 +240,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 serves another API contract ([recovery](#update-and-limit-errors)). | +| Network commands except `logout` | `rate_limited` | 1 | The account reached 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 8c059ff..92b4a14 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 + -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 --rerun + --error-class [options] + +Options: + --staging Use staging; reject a different saved origin + --kind spec_failure, setup_failure, boot_error, or + lint_failure + --rerun Command that reproduces the failure + --error-class Exception class, or the lint rule's name + --message Error message (first 300 characters) + --frame Backtrace frame in the application, repeatable + (first 20) + --fix-summary One line on the fix (first 200 characters) + --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 replaces email addresses, absolute paths, NAME=value assignments, +and token-like strings, leaves out frames outside the current directory, prints +the exact report, then sends it once to the origin pinned by a successful plan +push. Run it from the generated application's root. When the account +has reports off, First Draft keeps nothing and the command still exits 0. +`; + +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 = @@ -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,770 @@ 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: () => progressReportBody(step, counts), + }, + ); +} + +/** @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) || + !hasText(rerun) || + !hasText(errorClass) || + [rubyVersion, railsVersion].some( + (version) => version !== undefined && !RUNTIME_VERSION.test(version), + ) + ) { + 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, + ), + }, + ); +} + +const RUNTIME_VERSION = /^[0-9][0-9A-Za-z.+-]{0,31}$/; + +/** @param {string | undefined} value @returns {value is string} */ +function hasText(value) { + return value !== undefined && value.trim() !== ""; +} + +/** + * @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 Number.isSafeInteger(count) ? count : null; +} + +/** + * 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) => unknown}} 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 text = `${JSON.stringify(body(pinned.cwd), null, 2)}\n`; + stdout.write( + `Sending this ${noun} for Compilation ${compilationId} to ${pinned.apiUrl}:\n${text}`, + ); + 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, + 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 retry = + error instanceof RateLimitedError && error.retryAt !== undefined + ? `Try again after ${error.retryAt}` + : "Try again later"; + writeJson(writer, { + error: "rate_limited", + detail: + `${stopSentence(error)} The refused request did nothing, and the CLI sent nothing after it. ` + + `${retry}; response.detail, when present, says which limit.` + + (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..3046516 --- /dev/null +++ b/src/commands/report.js @@ -0,0 +1,370 @@ +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; + +// Code points kept in each free-text field after redaction. +const MAX_MESSAGE = 300; +const MAX_FIX_SUMMARY = 200; +const MAX_ERROR_CLASS = 200; +const MAX_RERUN = 300; +const MAX_FRAME = 300; + +// eslint-disable-next-line no-control-regex +const ANSI_ESCAPE = /\u001b\[[0-9;?]*[ -/]*[@-~]/g; +// eslint-disable-next-line no-control-regex +const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f]/g; +const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+/g; +// An absolute path: one in a home directory, on a drive, on a network share +// (\\host\share or //host/share), or from the root with at least two +// segments. It may start a word or follow a command option such as -I or +// --require=. A URL's path, a relative path such as app/models/post.rb, and +// ./spec/... are not matched. A path in quotes may contain spaces. +const PATH_CHARACTER = String.raw`[^\s'"` + "`" + String.raw`()<>[\]{},;]`; +const SEGMENT = String.raw`[^\s\\/'"` + "`" + String.raw`()<>[\]{},;]`; +const PATH_START = String.raw`(?:(?} 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] + */ + +/** + * Builds the failure report that is printed and sent. Every free-text field + * is redacted, then cut to its limit, so the printed report is exactly what + * leaves the computer. A frame outside `cwd` is left out, because a report + * describes generated code. + * + * @param {FailureReport} report + * @param {string} cwd absolute paths inside it become relative + */ +export function failureReportBody( + { + kind, + rerun, + errorClass, + message, + frames = [], + fixSummary, + rubyVersion, + railsVersion, + }, + cwd, +) { + /** @param {string} text @param {number} limit */ + const field = (text, limit) => clip(redact(text, cwd), limit); + const kept = frames + .map((frame) => field(frame, MAX_FRAME)) + .filter((frame) => !OUTSIDE_FRAME.test(frame)) + // The Service accepts frames with / separators only. + .map((frame) => frame.replace(/^[^:]*/, (file) => file.replace(/\\/g, "/"))) + .slice(0, MAX_FAILURE_FRAMES); + const versions = { + ...(rubyVersion === undefined ? {} : { ruby: rubyVersion }), + ...(railsVersion === undefined ? {} : { rails: railsVersion }), + }; + + return { + failure_report: { + kind, + rerun: clip( + redact(rerun.replace(COMMAND_ASSIGNMENT, "$1=[value]"), cwd), + MAX_RERUN, + ), + error_class: field(errorClass, MAX_ERROR_CLASS), + ...(message === undefined + ? {} + : { message: field(message, MAX_MESSAGE) }), + ...(kept.length === 0 ? {} : { frames: kept }), + ...(fixSummary === undefined + ? {} + : { fix_summary: field(fixSummary, MAX_FIX_SUMMARY) }), + ...(Object.keys(versions).length === 0 ? {} : { versions }), + }, + }; +} + +/** + * Removes terminal escapes and control characters other than tab and + * newline, then replaces email addresses, absolute paths, and token-like + * strings. An absolute path inside `cwd` becomes relative to it. + * + * @param {string} text + * @param {string} cwd + */ +export function redact(text, cwd) { + const root = cwd.replace(/[\\/]+$/, ""); + /** @param {string} match */ + const replacePath = (match) => { + const inside = + root !== "" && + (match.startsWith(`${root}/`) || match.startsWith(`${root}\\`)); + const relative = match.slice(root.length + 1); + return inside && relative !== "" ? relative : REDACTED_PATH; + }; + // The current directory may contain spaces, which end an unquoted path, so + // its prefix is removed before paths are matched. + const rootPrefix = + root === "" + ? null + : new RegExp( + `${PATH_START}${root.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\\\/](?=${PATH_CHARACTER})`, + "g", + ); + + const quotedPathsRedacted = text + .replace(ANSI_ESCAPE, "") + .replace(CONTROL, "") + .replace(EMAIL, "[email]") + .replace(CREDENTIAL, "[token]") + .replace(ASSIGNMENT, "$1=[value]") + .replace(QUOTED, (match, quote, inner) => + ABSOLUTE_START.test(inner) + ? `${quote}${replacePath(inner)}${quote}` + : match, + ) + .replace(FILE_URL, REDACTED_PATH); + + return ( + rootPrefix === null + ? quotedPathsRedacted + : quotedPathsRedacted.replace(rootPrefix, "") + ) + .replace(OPTION_PATH, replacePath) + .replace(ABSOLUTE_PATH, replacePath) + .replace(TOKEN_CANDIDATE, (match) => + /\d/.test(match) && /[A-Za-z]/.test(match) ? "[token]" : match, + ); +} + +/** @param {string} text @param {number} limit */ +function clip(text, limit) { + const characters = Array.from(text); + return characters.length <= limit + ? text + : characters.slice(0, limit).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" && + report.id !== "" && + report.compilation_id === compilationId + ); +} 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..2f5d0e5 --- /dev/null +++ b/src/service-client.js @@ -0,0 +1,443 @@ +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,63}$/; +const PLATFORM = /^[a-z0-9]{1,32}$/; +const MAX_LIMIT_PROBLEM_BYTES = 64 * 1024; +// The Service ignores the whole header when one value is longer. +const MAX_FACT_LENGTH = 64; + +/** + * 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."); + 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("; "); + /** @type {{component: "plugin" | "cli", version: Version}} */ + const installed = + plugin === null + ? { + component: "cli", + version: /** @type {Version} */ (semver(VERSION)), + } + : { component: "plugin", version: 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) { + const latest = semver(response.headers.get("firstdraft-latest-plugin")); + if ( + updateLine === null && + latest !== null && + compareVersions(installed.version, latest) < 0 + ) { + updateLine = + `First Draft: an update is available (plugin ${latest.text}; this setup has ` + + `${installed.component === "plugin" ? "plugin" : "CLI"} ${installed.version.text}). ` + + `Tell the person 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; + } + + const minimum = semver(response.headers.get("firstdraft-minimum-plugin")); + if (minimum !== null && compareVersions(installed.version, minimum) < 0) { + stop = new UpdateRequiredError({ + component: installed.component, + installed: installed.version.text, + minimum: 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 }); + }, + }; +} + +/** + * @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) { + return `First Draft requires plugin ${stop.minimum} or later, and this setup has ${stop.component === "plugin" ? "plugin" : "CLI"} ${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 this account reached one of its limits."; +} + +/** + * 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/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/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-status.test.js b/test/plan-status.test.js index 26299f3..75ee173 100644 --- a/test/plan-status.test.js +++ b/test/plan-status.test.js @@ -18,6 +18,7 @@ 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 */ @@ -147,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/); }); @@ -1120,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..20848b4 --- /dev/null +++ b/test/report.test.js @@ -0,0 +1,752 @@ +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, redact } 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 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", + "--rerun", + "bin/rails runner 1", + "--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, "--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":"canary","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: "x", compilation_id: PROJECT_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 () => { + const [, , , ...required] = FAILURE; + for (const argv of [ + ["report", "failure", COMPILATION_ID, ...required.slice(2)], + [ + "report", + "failure", + COMPILATION_ID, + ...required.slice(0, 2), + ...required.slice(4), + ], + ["report", "failure", COMPILATION_ID, ...required.slice(0, 4)], + [...FAILURE, "--kind", "lint_failure"], + [ + "report", + "failure", + COMPILATION_ID, + "--kind", + "lint", + ...required.slice(2), + ], + [ + "report", + "failure", + COMPILATION_ID, + ...required.slice(0, 2), + "--rerun", + " ", + ...required.slice(4), + ], + [...FAILURE.slice(0, -1), " "], + [...FAILURE, "--ruby-version", "three"], + [...FAILURE, "--rails-version", "8 1"], + [...FAILURE, "--fix-summary", "a", "--fix-summary", "b"], + ["report", "failure", "canary", ...required], + ]) { + 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 redacts, cuts, and prints exactly what it sends", async (context) => { + const cwd = projectDirectory(context, PRODUCTION); + /** @type {string | undefined} */ + let sent; + const frames = [ + "/usr/lib/ruby/3.4.0/forwardable.rb:238:in 'Forwardable#delegate'", + ...Array.from( + { length: 22 }, + (_, index) => `${cwd}/app/models/movie.rb:${index + 1}:in 'Movie#rate'`, + ), + ]; + const result = await invoke( + [ + "report", + "failure", + COMPILATION_ID, + "--kind", + "spec_failure", + "--rerun", + `bundle exec rspec ${cwd}/spec/models/movie_spec.rb:42`, + "--error-class", + "NoMethodError", + "--message", + `undefined method 'stars' for nil\u001b[31m in /home/sam/.gem/x.rb mail sam@example.com token fd_${"a1".repeat(20)} ${"m".repeat(400)}`, + ...frames.flatMap((frame) => ["--frame", frame]), + "--fix-summary", + `Guarded nil ratings. ${"s".repeat(300)}`, + "--ruby-version", + "3.4.7", + "--rails-version", + "8.1.4", + ], + { + 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.equal( + result.stdout, + `Sending this failure report for Compilation ${COMPILATION_ID} to ${PRODUCTION}:\n${sent}Sent.\n`, + ); + const report = JSON.parse(sent).failure_report; + assert.deepEqual(Object.keys(report), [ + "kind", + "rerun", + "error_class", + "message", + "frames", + "fix_summary", + "versions", + ]); + assert.equal(report.rerun, "bundle exec rspec spec/models/movie_spec.rb:42"); + assert.equal( + report.message, + `undefined method 'stars' for nil in [path] mail [email] token [token] ${"m".repeat(400)}`.slice( + 0, + 300, + ), + ); + assert.equal(report.frames.length, 20); + assert.equal(report.frames[0], "app/models/movie.rb:1:in 'Movie#rate'"); + assert.equal(Array.from(report.fix_summary).length, 200); + assert.ok(report.fix_summary.startsWith("Guarded nil ratings. ")); + assert.deepEqual(report.versions, { ruby: "3.4.7", rails: "8.1.4" }); + assert.doesNotMatch(sent, /\/home|\/usr|sam@|fd_|\\u001b|\/private|\/var/); +}); + +test("a failure report carries only the optional fields that were given", async (context) => { + /** @type {unknown} */ + let sent; + const result = await invoke(FAILURE, { + 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", + rerun: "bin/rails runner 1", + error_class: "NameError", + }, + }); +}); + +test("a rerun command's assignments and frames outside the application stay home", () => { + const { failure_report: report } = failureReportBody( + { + kind: "lint_failure", + rerun: + "npm_config_registry=https://registry.example.test PASS=a\\ b bin/rubocop --format=progress", + errorClass: "Rails/Delegate", + frames: ["/boot.rb:3", "C:\\x.rb:2", "app/x.rb:1", "../lib/y.rb:4"], + }, + CWD, + ); + assert.equal( + report.rerun, + "npm_config_registry=[value] PASS=[value] bin/rubocop --format=progress", + ); + assert.deepEqual(report.frames, ["app/x.rb:1"]); + + const windows = failureReportBody( + { + kind: "spec_failure", + rerun: 'label=North" West" ruby -I /gems -I/Shared\\ Gems x.rb', + errorClass: "NoMethodError", + frames: ["app\\models\\movie.rb:12:in 'Movie#rate'"], + }, + CWD, + ).failure_report; + assert.equal(windows.rerun, "label=[value] ruby -I [path] -I[path] x.rb"); + assert.deepEqual(windows.frames, ["app/models/movie.rb:12:in 'Movie#rate'"]); +}); + +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("a current directory with spaces still makes its paths relative", () => { + for (const [ + text, + cwd, + expected, + ] of /** @type {[string, string, string][]} */ ([ + [ + "Error in /Users/Jane Doe/movie_catalog/app/models/movie.rb:12 here", + "/Users/Jane Doe/movie_catalog", + "Error in app/models/movie.rb:12 here", + ], + [ + "C:\\Users\\Jane Doe\\movie_catalog\\app\\x.rb:3", + "C:\\Users\\Jane Doe\\movie_catalog", + "app\\x.rb:3", + ], + ])) { + assert.equal(redact(text, cwd), expected); + } +}); + +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:in 'Movie#rate'"], + ); +}); + +test("redaction keeps relative paths and URLs and replaces what identifies a computer", () => { + for (const [text, expected] of /** @type {[string, string][]} */ ([ + ["app/models/post.rb:12", "app/models/post.rb:12"], + ["./spec/models/post_spec.rb:3", "./spec/models/post_spec.rb:3"], + ["Rails/Delegate", "Rails/Delegate"], + [ + "see https://firstdraft.com/update now", + "see https://firstdraft.com/update now", + ], + [`${CWD}/config/database.yml:3: bad`, "config/database.yml:3: bad"], + [`${CWD}-other/secret.rb`, "[path]"], + ["/Users/sam/code/app/x.rb", "[path]"], + ["~/code/app/x.rb", "[path]"], + ["C:\\Users\\sam\\app\\x.rb", "[path]"], + ["\\\\fileserver\\share\\Board\\x.md:3", "[path]"], + ["//fileserver/share/x.md", "[path]"], + ["~/notes.txt", "[path]"], + ["file:///Users/sam/x.rb", "[path]"], + ['open "/Users/sam/Work/Board Minutes.md" failed', 'open "[path]" failed'], + [`'${CWD}/app/My File.rb'`, "'app/My File.rb'"], + ["'rspec' and \"/ two\"", "'rspec' and \"/ two\""], + ["LABEL=internal-only bin/rspec", "LABEL=[value] bin/rspec"], + ["SECRET=a\\ b rest", "SECRET=[value] rest"], + ["ruby -I/gems bin/test", "ruby -I[path] bin/test"], + ["token fd_abcdefghijklmnopqrstuv here", "token [token] here"], + [ + 'RAILS_ENV=test SECRET="a b" bin/rails', + "RAILS_ENV=[value] SECRET=[value] bin/rails", + ], + [ + "expected count=3 with --format=progress", + "expected count=3 with --format=progress", + ], + ["ruby -I/Users/example/local-gems/lib x.rb", "ruby -I[path] x.rb"], + ["rspec --require=/Users/x/spec_helper.rb", "rspec --require=[path]"], + [ + 'open "file:///Users/sam/My Secret/a.txt" and "/Users/sam/My Secret.txt"', + 'open "[path]" and "[path]"', + ], + ["(file:///Users/sam/a.rb)", "([path])"], + ["a / b and 3/4", "a / b and 3/4"], + ["user.name+tag@mail.example.org", "[email]"], + ["id 0190f3a2-7c1d-7e00-8b1a-3f9e2d4c5b6a", "id [token]"], + [ + "sha 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", + "sha [token]", + ], + [ + "Compilation 01900000-0000-7000-8000-000000009101", + "Compilation 01900000-0000-7000-8000-000000009101", + ], + [ + "movie_reviews_controller_index_action_name", + "movie_reviews_controller_index_action_name", + ], + ["line\r\nnext\tcolumn\u0007", "line\nnext\tcolumn"], + ])) { + assert.equal(redact(text, CWD), expected, text); + } +}); + +/** @param {string} wrapper the report's key in First Draft's acknowledgment */ +function acknowledgment(wrapper) { + const report = { id: "canary-report", 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..dba7b0a --- /dev/null +++ b/test/service-client.test.js @@ -0,0 +1,729 @@ +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 its own version", async () => { + /** @type {string[]} */ + const lines = []; + const session = createServiceSession({ + env: {}, + notify: (line) => lines.push(line), + }); + await session.fetch(async () => versionedResponse({ latest: "99.0.0" }))( + new URL("/v1/account", ORIGIN), + {}, + ); + session.flush(); + + assert.deepEqual(lines, [ + `First Draft: an update is available (plugin 99.0.0; this setup has CLI ${VERSION}). Tell the person the update steps are at ${UPDATE_URL}\n`, + ]); +}); + +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({ 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"); + 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 reports the limit even when the response also requires an update", async () => { + for (const headers of [ + { "FirstDraft-Minimum-Plugin": "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, { 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, { minimum: "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 plugin 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_plugin_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({ minimum: "99.0.0" }), + }); + + assert.equal(result.status, 1); + assert.deepEqual(errorEnvelope(result.stderr), { + error: "update_required", + detail: `First Draft requires plugin 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_plugin_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 this account reached one of its limits. 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, contract?: string}} versions + * @param {string | null} [body] + * @param {Record} [headers] + */ +function versionedResponse( + { latest, minimum, 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 }), + ...(contract === undefined + ? {} + : { "FirstDraft-API-Contract": contract }), + }, + }); +} + +/** + * @param {string} cwd + * @param {{latest?: string, minimum?: 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"), + ); +} From 0c95ae667705061cfb83cd9b334b76c661d49379 Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Fri, 20 Nov 2026 17:18:37 -0600 Subject: [PATCH 04/14] Compare a bare CLI with the CLI versions Without FIRSTDRAFT_PLUGIN_VERSION the CLI compared its own version with the plugin's latest and minimum. The two packages are numbered separately (plugin 0.9.3 bundles CLI 0.9.0), so a direct npm installation, as in the Codespace and the laptop kit, would have printed the update line, or refused, for versions that were current. The Service now also names FirstDraft-Latest-CLI and FirstDraft-Minimum-CLI. A plugin is compared with the plugin pair and a bare CLI with the CLI pair; a Service that sends no CLI pair produces no line and no refusal. update_required names minimum_cli_version in the second case. --- docs/commands.md | 14 ++++---- docs/errors.md | 6 ++-- src/cli.js | 10 +++--- src/service-client.js | 29 +++++++++++----- test/service-client.test.js | 69 ++++++++++++++++++++++++++++--------- 5 files changed, 90 insertions(+), 38 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index b685955..b70f258 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -165,16 +165,18 @@ Beyond the header, a command sends only what it needs: ### Update line and refusals -First Draft answers each routed `/v1` request with `FirstDraft-Latest-Plugin`, `FirstDraft-Minimum-Plugin`, and -`FirstDraft-API-Contract`. The CLI checks every response it receives for them; an OAuth answer or a missing route -may carry none, so it then checks nothing. The CLI compares the plugin version from `FIRSTDRAFT_PLUGIN_VERSION`, or -its own version when that variable is unset, with the first two. The update notice therefore comes from First Draft's -answer to the command being run, not from a request of its own. +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, and a Service that sends no CLI pair produces no line and no refusal. 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 says `CLI `. + 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 diff --git a/docs/errors.md b/docs/errors.md index f49b71b..4a532d2 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -69,9 +69,9 @@ finished. The CLI finishes handling that response, so a push it accepted still s 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 than the CLI - when no plugin version is set. `minimum_plugin_version`, `cli_version`, and, when known, `plugin_version` name the - versions. Tell the person to update with the steps at `update_url` (`https://firstdraft.com/update`), then run the +- `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. diff --git a/src/cli.js b/src/cli.js index 92b4a14..1b0f043 100644 --- a/src/cli.js +++ b/src/cli.js @@ -3797,10 +3797,12 @@ function writeServiceStop(writer, error) { error: "update_required", detail: `${stopSentence(error)} ${stopped} ${update} ${next}`, ...(error.component === "plugin" - ? { plugin_version: error.installed } - : {}), - cli_version: VERSION, - minimum_plugin_version: error.minimum, + ? { + 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 }), }); diff --git a/src/service-client.js b/src/service-client.js index 2f5d0e5..f51037f 100644 --- a/src/service-client.js +++ b/src/service-client.js @@ -44,7 +44,7 @@ export class ServiceStopError extends Error { 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."); + super("First Draft requires a newer plugin or CLI."); this.component = component; this.installed = installed; this.minimum = minimum; @@ -119,14 +119,26 @@ export function createServiceSession({ : []), ...(PLATFORM.test(platform) ? [`os/${platform}`] : []), ].join("; "); - /** @type {{component: "plugin" | "cli", version: Version}} */ + // 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. + /** @type {{component: "plugin" | "cli", label: string, version: Version, latestHeader: string, minimumHeader: string}} */ const installed = plugin === null ? { component: "cli", + label: "CLI", version: /** @type {Version} */ (semver(VERSION)), + latestHeader: "firstdraft-latest-cli", + minimumHeader: "firstdraft-minimum-cli", } - : { component: "plugin", version: plugin }; + : { + component: "plugin", + label: "plugin", + version: plugin, + latestHeader: "firstdraft-latest-plugin", + minimumHeader: "firstdraft-minimum-plugin", + }; /** @type {ServiceStopError | null} */ let stop = null; let blocked = false; @@ -140,15 +152,15 @@ export function createServiceSession({ * @returns {Promise} the response, rebuilt when its body was read */ async function observe(origin, response) { - const latest = semver(response.headers.get("firstdraft-latest-plugin")); + const latest = semver(response.headers.get(installed.latestHeader)); if ( updateLine === null && latest !== null && compareVersions(installed.version, latest) < 0 ) { updateLine = - `First Draft: an update is available (plugin ${latest.text}; this setup has ` + - `${installed.component === "plugin" ? "plugin" : "CLI"} ${installed.version.text}). ` + + `First Draft: an update is available (${installed.label} ${latest.text}; this setup has ` + + `${installed.label} ${installed.version.text}). ` + `Tell the person the update steps are at ${UPDATE_URL}\n`; } @@ -179,7 +191,7 @@ export function createServiceSession({ return response; } - const minimum = semver(response.headers.get("firstdraft-minimum-plugin")); + const minimum = semver(response.headers.get(installed.minimumHeader)); if (minimum !== null && compareVersions(installed.version, minimum) < 0) { stop = new UpdateRequiredError({ component: installed.component, @@ -376,7 +388,8 @@ function acceptsContract(contract) { */ export function stopSentence(stop) { if (stop instanceof UpdateRequiredError) { - return `First Draft requires plugin ${stop.minimum} or later, and this setup has ${stop.component === "plugin" ? "plugin" : "CLI"} ${stop.installed}.`; + 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" diff --git a/test/service-client.test.js b/test/service-client.test.js index dba7b0a..c7a189c 100644 --- a/test/service-client.test.js +++ b/test/service-client.test.js @@ -127,24 +127,53 @@ test("an older plugin prints one update line per command, however many requests ]); }); -test("without a plugin version the CLI compares its own version", async () => { +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" }))( - new URL("/v1/account", ORIGIN), - {}, - ); - session.flush(); + await session.fetch(async () => + versionedResponse({ + latest: "99.0.0", + minimum: "99.0.0", + latestCli: "98.0.0", + }), + )(new URL("/v1/account", ORIGIN), {}); + assert.equal(await session.settle(Promise.resolve("done")), "done"); assert.deepEqual(lines, [ - `First Draft: an update is available (plugin 99.0.0; this setup has CLI ${VERSION}). Tell the person the update steps are at ${UPDATE_URL}\n`, + `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("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({ @@ -306,7 +335,7 @@ test("a 429 that is the command's first response still carries the update notice test("a 429 reports the limit even when the response also requires an update", async () => { for (const headers of [ - { "FirstDraft-Minimum-Plugin": "99.0.0" }, + { "FirstDraft-Minimum-CLI": "99.0.0" }, { "FirstDraft-API-Contract": "0.10.0" }, ]) { const session = createServiceSession({ @@ -473,7 +502,7 @@ test("plan compile sends nothing after a response below the minimum", async (con env: {}, fetchFunction: async (input, init) => { requests.push(`${init?.method} ${new URL(String(input)).pathname}`); - return acceptedPush(cwd, { minimum: "99.0.0" }); + return acceptedPush(cwd, { minimumCli: "99.0.0" }); }, }); @@ -484,9 +513,9 @@ test("plan compile sends nothing after a response below the minimum", async (con assert.equal(result.stdout, ""); assert.deepEqual(errorEnvelope(result.stderr), { error: "update_required", - detail: `First Draft requires plugin 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.`, + 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_plugin_version: "99.0.0", + minimum_cli_version: "99.0.0", update_url: UPDATE_URL, }); assert.equal(readState(cwd).foundation_plan_etag, ETAG); @@ -531,15 +560,15 @@ test("a stop after a Compilation started names it instead of advising another", const error = await fetchFunction(url, {}).catch((cause) => cause); throw new CompilationRetainedError(error, /** @type {any} */ (current)); }, - fetchFunction: async () => versionedResponse({ minimum: "99.0.0" }), + fetchFunction: async () => versionedResponse({ minimumCli: "99.0.0" }), }); assert.equal(result.status, 1); assert.deepEqual(errorEnvelope(result.stderr), { error: "update_required", - detail: `First Draft requires plugin 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.`, + 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_plugin_version: "99.0.0", + minimum_cli_version: "99.0.0", update_url: UPDATE_URL, current, }); @@ -621,12 +650,12 @@ function limitResponse(retryAfter) { } /** - * @param {{latest?: string, minimum?: string, contract?: string}} versions + * @param {{latest?: string, minimum?: string, latestCli?: string, minimumCli?: string, contract?: string}} versions * @param {string | null} [body] * @param {Record} [headers] */ function versionedResponse( - { latest, minimum, contract }, + { latest, minimum, latestCli, minimumCli, contract }, body = null, headers = {}, ) { @@ -638,6 +667,12 @@ function versionedResponse( ...(minimum === undefined ? {} : { "FirstDraft-Minimum-Plugin": minimum }), + ...(latestCli === undefined + ? {} + : { "FirstDraft-Latest-CLI": latestCli }), + ...(minimumCli === undefined + ? {} + : { "FirstDraft-Minimum-CLI": minimumCli }), ...(contract === undefined ? {} : { "FirstDraft-API-Contract": contract }), @@ -647,7 +682,7 @@ function versionedResponse( /** * @param {string} cwd - * @param {{latest?: string, minimum?: string, contract?: string}} versions + * @param {{latest?: string, minimum?: string, latestCli?: string, minimumCli?: string, contract?: string}} versions */ function acceptedPush(cwd, versions) { const source = readFileSync( From 3dad57411c93df92a07ef19290190139a883966e Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Fri, 20 Nov 2026 17:37:24 -0600 Subject: [PATCH 05/14] Close report redaction and recovery gaps A fresh review of the whole branch found text that still left the computer in a failure report: JWTs whose segments were too short for the token rule, assignments quoted as a whole, paths directly under the root, and a quoted option with its path. The Service scrubs the same forms, but only after the CLI has printed and sent them. A report now counts as sent only when First Draft returns a UUID for it. A plugin version that is set but unreadable compares neither version pair, so a plugin never meets the CLI's minimum. A 429 is described as a limit, not the account's, because device login shares one across all CLIs. The fork advice after a 412 names the origin a first push used when it never pinned one, and reports run from the application root after adoption. --- docs/commands.md | 9 +++--- docs/errors.md | 18 ++++++------ src/cli.js | 4 +-- src/commands/report.js | 39 ++++++++++++++++++++------ src/service-client.js | 56 ++++++++++++++++++++++++------------- test/plan-push.test.js | 2 +- test/report.test.js | 28 +++++++++++++++++-- test/service-client.test.js | 20 ++++++++++++- 8 files changed, 128 insertions(+), 48 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index b70f258..21161d4 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -182,8 +182,8 @@ notice therefore comes from First Draft's answer to the command being run, not f 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 with `Retry-After` when an account reaches a limit, such as its - Compilations for the day or its reports for the hour: the request did nothing, and whatever else the response +- **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` @@ -504,8 +504,9 @@ Artifact validation accepts only Plan format `firstdraft.foundation-plan.sketch/ 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. diff --git a/docs/errors.md b/docs/errors.md index 4a532d2..730db5c 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -78,12 +78,13 @@ one `First Draft: ` line that names the required update ([update line and refusa - `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 the account reached a limit. The refused request did nothing. - `response.code` names the limit: `compilation_limit_reached` or `project_limit_reached` for the Compilations or +- `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. When `current` is present, follow that Compilation as - above instead. + `Retry-After`. Wait until then and run the command again; without either, 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. @@ -100,9 +101,10 @@ phase-specific recovery: 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 (`api_url` in - its `.firstdraft/state.json`): `--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 + 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 @@ -244,7 +246,7 @@ stopped without following the replacement. | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ---: | -------------------------------------------------------------------------------------------------------- | | 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 serves another API contract ([recovery](#update-and-limit-errors)). | -| Network commands except `logout` | `rate_limited` | 1 | The account reached a limit; `retry_at` says when to try again. | +| 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. | diff --git a/src/cli.js b/src/cli.js index 1b0f043..cefdad3 100644 --- a/src/cli.js +++ b/src/cli.js @@ -535,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, 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 (api_url in .firstdraft/state.json), with --staging for staging or the same FIRSTDRAFT_API_URL for a custom origin."; + "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."; @@ -578,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, 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 (api_url in .firstdraft/state.json), with --staging for staging or the same FIRSTDRAFT_API_URL for a custom origin."; + "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 = diff --git a/src/commands/report.js b/src/commands/report.js index 3046516..2426ee6 100644 --- a/src/commands/report.js +++ b/src/commands/report.js @@ -53,12 +53,14 @@ const OPTION_PATH = new RegExp( "g", ); const ABSOLUTE_PATH = new RegExp( - String.raw`${PATH_START}(?:~[\\/]${PATH_CHARACTER}+|[A-Za-z]:[\\/]${PATH_CHARACTER}*|[\\/]{2}${SEGMENT}+${PATH_CHARACTER}*|[\\/](?:${SEGMENT}+[\\/])+${PATH_CHARACTER}*)`, + String.raw`${PATH_START}(?:~[\\/]${PATH_CHARACTER}+|[A-Za-z]:[\\/]${PATH_CHARACTER}*|[\\/]{2}${SEGMENT}+${PATH_CHARACTER}*|[\\/]${SEGMENT}+(?:[\\/]${PATH_CHARACTER}*)?)`, "g", ); const QUOTED = /(['"`])([^'"`\n]+)\1/g; const ABSOLUTE_START = /^(?:file:\/\/|~[\\/]|[A-Za-z]:[\\/]|[\\/]{1,2}[^\s\\/])/i; +// A quoted option and its path together, such as "-I/Team Notes/lib". +const QUOTED_OPTION = /^(--?[A-Za-z][A-Za-z0-9-]*=?)(.*)$/; const FILE_URL = new RegExp(String.raw`\bfile:\/\/${PATH_CHARACTER}*`, "gi"); // NAME=value, as a shell sets an environment variable for one command. // A value may be quoted, or unquoted with backslash escapes. @@ -75,9 +77,12 @@ const COMMAND_ASSIGNMENT = new RegExp( String.raw`(? - ABSOLUTE_START.test(inner) - ? `${quote}${replacePath(inner)}${quote}` - : match, - ) + .replace(QUOTED, (match, quote, inner) => { + if (ABSOLUTE_START.test(inner)) { + return `${quote}${replacePath(inner)}${quote}`; + } + const [, option, operand] = QUOTED_OPTION.exec(inner) ?? []; + return option !== undefined && + operand !== undefined && + ABSOLUTE_START.test(operand) + ? `${quote}${option}${replacePath(operand)}${quote}` + : match; + }) .replace(FILE_URL, REDACTED_PATH); return ( @@ -364,7 +381,11 @@ function isRecord(value) { function isStoredReport(report, compilationId) { return ( typeof report.id === "string" && - report.id !== "" && + 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/service-client.js b/src/service-client.js index f51037f..8fe4d2f 100644 --- a/src/service-client.js +++ b/src/service-client.js @@ -122,23 +122,28 @@ export function createServiceSession({ // 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. - /** @type {{component: "plugin" | "cli", label: string, version: Version, latestHeader: string, minimumHeader: string}} */ + // A plugin version that is set but unreadable says a plugin is present + // without saying which, so neither pair is compared. + const pluginSet = (env[PLUGIN_VERSION_VARIABLE] ?? "").trim() !== ""; + /** @type {{component: "plugin" | "cli", label: string, version: Version, latestHeader: string, minimumHeader: string} | null} */ const installed = - 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", - }; + 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; @@ -152,8 +157,12 @@ export function createServiceSession({ * @returns {Promise} the response, rebuilt when its body was read */ async function observe(origin, response) { - const latest = semver(response.headers.get(installed.latestHeader)); + const latest = + installed === null + ? null + : semver(response.headers.get(installed.latestHeader)); if ( + installed !== null && updateLine === null && latest !== null && compareVersions(installed.version, latest) < 0 @@ -191,8 +200,15 @@ export function createServiceSession({ return response; } - const minimum = semver(response.headers.get(installed.minimumHeader)); - if (minimum !== null && compareVersions(installed.version, minimum) < 0) { + const minimum = + installed === null + ? null + : semver(response.headers.get(installed.minimumHeader)); + if ( + installed !== null && + minimum !== null && + compareVersions(installed.version, minimum) < 0 + ) { stop = new UpdateRequiredError({ component: installed.component, installed: installed.version.text, @@ -396,7 +412,7 @@ export function stopSentence(stop) { ? `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 this account reached one of its limits."; + return "First Draft refused a request because a limit was reached."; } /** diff --git a/test/plan-push.test.js b/test/plan-push.test.js index e3c2aaf..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, 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 (api_url in .firstdraft/state.json), with --staging for staging or the same FIRSTDRAFT_API_URL for a custom origin.", + "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/report.test.js b/test/report.test.js index 20848b4..b01dbbd 100644 --- a/test/report.test.js +++ b/test/report.test.js @@ -17,6 +17,7 @@ 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"); @@ -134,7 +135,7 @@ test("report progress prints the exact report, then sends those bytes once", asy fetchFunction: async (input, init) => { requests.push({ url: String(input), init }); return new Response( - `{"progress_report":{"id":"canary","compilation_id":"${COMPILATION_ID}"}}`, + `{"progress_report":{"id":"${STORED_ID}","compilation_id":"${COMPILATION_ID}"}}`, { status: 201, headers: { "Content-Type": "application/json" }, @@ -250,7 +251,14 @@ test("a success without First Draft's acknowledgment is not reported as sent", a () => new Response( JSON.stringify({ - progress_report: { id: "x", compilation_id: PROJECT_ID }, + 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" } }, ), @@ -631,6 +639,20 @@ test("redaction keeps relative paths and URLs and replaces what identifies a com ["SECRET=a\\ b rest", "SECRET=[value] rest"], ["ruby -I/gems bin/test", "ruby -I[path] bin/test"], ["token fd_abcdefghijklmnopqrstuv here", "token [token] here"], + [ + "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.abc", + "Authorization: Bearer [token]", + ], + ["found /.dockerenv here", "found [path] here"], + ['ruby "-I/Team Notes/lib" x.rb', 'ruby "-I[path]" x.rb'], + [ + "env 'BUILD_LABEL=North West' bin/rspec", + "env 'BUILD_LABEL=[value]' bin/rspec", + ], + [ + "undefined method `/' for nil and/or", + "undefined method `/' for nil and/or", + ], [ 'RAILS_ENV=test SECRET="a b" bin/rails', "RAILS_ENV=[value] SECRET=[value] bin/rails", @@ -669,7 +691,7 @@ test("redaction keeps relative paths and URLs and replaces what identifies a com /** @param {string} wrapper the report's key in First Draft's acknowledgment */ function acknowledgment(wrapper) { - const report = { id: "canary-report", compilation_id: COMPILATION_ID }; + const report = { id: STORED_ID, compilation_id: COMPILATION_ID }; return new Response(JSON.stringify({ [wrapper]: report }), { status: 201, headers: { "Content-Type": "application/json" }, diff --git a/test/service-client.test.js b/test/service-client.test.js index c7a189c..bdba873 100644 --- a/test/service-client.test.js +++ b/test/service-client.test.js @@ -148,6 +148,24 @@ test("without a plugin version the CLI compares itself with the CLI versions", a ]); }); +test("an unreadable plugin version compares neither pair", async () => { + const session = createServiceSession({ + env: { FIRSTDRAFT_PLUGIN_VERSION: "dev" }, + notify: () => assert.fail("No version line was expected"), + }); + 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"); +}); + test("each setup reads only its own pair of version headers", async () => { for (const [ env, @@ -604,7 +622,7 @@ test("a daily cap reports rate_limited with when to try again", async (context) assert.deepEqual(JSON.parse(result.stderr), { error: "rate_limited", detail: - "First Draft refused a request because this account reached one of its limits. 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.", + "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, From ebb5a2443793cf35f5b19ffb86a874c868a8df7f Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Fri, 20 Nov 2026 17:51:31 -0600 Subject: [PATCH 06/14] Redact mixed quotes and say when to retry The second review round still found text that left the computer: a quoted assignment containing the other kind of quote, a quoted -I option whose drive letter was read as part of the option, and an unquoted path with an escaped space. A 429 with neither Retry-After nor a problem detail, as device login sends, now says to try again in a minute instead of "later", and the login reference names the refusals that can end it. --- docs/commands.md | 6 ++++-- docs/errors.md | 2 +- src/cli.js | 14 ++++++++++---- src/commands/report.js | 29 +++++++++++++++++++++++------ test/report.test.js | 7 +++++++ test/service-client.test.js | 17 +++++++++++++++++ 6 files changed, 62 insertions(+), 13 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 21161d4..8fe9f2b 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -72,8 +72,10 @@ slow down, and stops when the code expires. 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`. Other failures exit with `login_failed`. No credential is saved unless the login succeeds. -See [Errors and recovery](errors.md#login-and-logout-errors). +`authorization_expired`. A First Draft limit or a required update ends it with `rate_limited`, `update_required`, or +`api_contract_unsupported` ([update line and refusals](#update-line-and-refusals)). 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 diff --git a/docs/errors.md b/docs/errors.md index 730db5c..a622abf 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -82,7 +82,7 @@ one `First Draft: ` line that names the required update ([update line and refusa `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, wait a minute. `login --interactive` meets + `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. diff --git a/src/cli.js b/src/cli.js index cefdad3..930f5fa 100644 --- a/src/cli.js +++ b/src/cli.js @@ -3826,15 +3826,21 @@ function writeServiceStop(writer, error) { 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 = - error instanceof RateLimitedError && error.retryAt !== undefined - ? `Try again after ${error.retryAt}` - : "Try again later"; + 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}; response.detail, when present, says which limit.` + + retry + (current === undefined ? "" : ` A Compilation had already started: follow it with 'firstdraft compilation status ${current.compilation.id}' instead of compiling again.`), diff --git a/src/commands/report.js b/src/commands/report.js index 2426ee6..49fc268 100644 --- a/src/commands/report.js +++ b/src/commands/report.js @@ -52,15 +52,18 @@ const OPTION_PATH = new RegExp( String.raw`(?<=(?:^|[\s'"(])--?[A-Za-z][A-Za-z0-9-]*(?:=|[ \t]+)?)[\\/](?:\\ |${SEGMENT})+(?:\\ |${PATH_CHARACTER})*`, "g", ); +// A shell-escaped space continues an unquoted path. +const ESCAPED_PATH = String.raw`(?:\\ |${PATH_CHARACTER})`; const ABSOLUTE_PATH = new RegExp( - String.raw`${PATH_START}(?:~[\\/]${PATH_CHARACTER}+|[A-Za-z]:[\\/]${PATH_CHARACTER}*|[\\/]{2}${SEGMENT}+${PATH_CHARACTER}*|[\\/]${SEGMENT}+(?:[\\/]${PATH_CHARACTER}*)?)`, + String.raw`${PATH_START}(?:~[\\/]${ESCAPED_PATH}+|[A-Za-z]:[\\/]${ESCAPED_PATH}*|[\\/]{2}${SEGMENT}+${ESCAPED_PATH}*|[\\/](?:\\ |${SEGMENT})+(?:[\\/]${ESCAPED_PATH}*)?)`, "g", ); const QUOTED = /(['"`])([^'"`\n]+)\1/g; const ABSOLUTE_START = /^(?:file:\/\/|~[\\/]|[A-Za-z]:[\\/]|[\\/]{1,2}[^\s\\/])/i; // A quoted option and its path together, such as "-I/Team Notes/lib". -const QUOTED_OPTION = /^(--?[A-Za-z][A-Za-z0-9-]*=?)(.*)$/; +// The shortest option prefix comes first, so -IC:\lib keeps its drive letter. +const QUOTED_OPTION = /^(--?[A-Za-z][A-Za-z0-9-]*?=?)((?:[A-Za-z]:)?[\\/~].*)$/; const FILE_URL = new RegExp(String.raw`\bfile:\/\/${PATH_CHARACTER}*`, "gi"); // NAME=value, as a shell sets an environment variable for one command. // A value may be quoted, or unquoted with backslash escapes. @@ -78,8 +81,11 @@ const COMMAND_ASSIGNMENT = new RegExp( "g", ); // An assignment quoted as a whole, as in env 'LABEL=North West' bin/rspec. -const QUOTED_ASSIGNMENT = /(['"])([A-Z_][A-Z0-9_]*)=[^'"\n]*\1/g; -const QUOTED_COMMAND_ASSIGNMENT = /(['"])([A-Za-z_][A-Za-z0-9_]*)=[^'"\n]*\1/g; +// Each quote ends only at its own kind, so "LABEL=O'Brien" is one value. +const QUOTED_ASSIGNMENT = + /"([A-Z_][A-Z0-9_]*)=[^"\n]*"|'([A-Z_][A-Z0-9_]*)=[^'\n]*'/g; +const QUOTED_COMMAND_ASSIGNMENT = + /"([A-Za-z_][A-Za-z0-9_]*)=[^"\n]*"|'([A-Za-z_][A-Za-z0-9_]*)=[^'\n]*'/g; // Credential formats that need no digit, as the Service also scrubs them. const CREDENTIAL = /\b(?:eyJ[\w-]*\.[\w-]+\.[\w-]*|fd_[\w-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|github_pat_\w{20,}|sk-[\w-]{20,}|xox[abprs]-[\w-]{10,}|AKIA[0-9A-Z]{16})/g; @@ -190,7 +196,7 @@ export function failureReportBody( rerun: clip( redact( rerun - .replace(QUOTED_COMMAND_ASSIGNMENT, "$1$2=[value]$1") + .replace(QUOTED_COMMAND_ASSIGNMENT, quotedAssignment) .replace(COMMAND_ASSIGNMENT, "$1=[value]"), cwd, ), @@ -242,7 +248,7 @@ export function redact(text, cwd) { .replace(CONTROL, "") .replace(EMAIL, "[email]") .replace(CREDENTIAL, "[token]") - .replace(QUOTED_ASSIGNMENT, "$1$2=[value]$1") + .replace(QUOTED_ASSIGNMENT, quotedAssignment) .replace(ASSIGNMENT, "$1=[value]") .replace(QUOTED, (match, quote, inner) => { if (ABSOLUTE_START.test(inner)) { @@ -269,6 +275,17 @@ export function redact(text, cwd) { ); } +/** + * @param {string} match + * @param {string | undefined} doubleQuoted + * @param {string | undefined} singleQuoted + */ +function quotedAssignment(match, doubleQuoted, singleQuoted) { + return doubleQuoted === undefined + ? `'${singleQuoted}=[value]'` + : `"${doubleQuoted}=[value]"`; +} + /** @param {string} text @param {number} limit */ function clip(text, limit) { const characters = Array.from(text); diff --git a/test/report.test.js b/test/report.test.js index b01dbbd..8931888 100644 --- a/test/report.test.js +++ b/test/report.test.js @@ -645,6 +645,13 @@ test("redaction keeps relative paths and URLs and replaces what identifies a com ], ["found /.dockerenv here", "found [path] here"], ['ruby "-I/Team Notes/lib" x.rb', 'ruby "-I[path]" x.rb'], + [ + `env "BUILD_LABEL=O'Brien West" bin/rspec`, + `env "BUILD_LABEL=[value]" bin/rspec`, + ], + [`env 'LABEL=say "hi" now' x`, "env 'LABEL=[value]' x"], + ['ruby "-IC:\\My Work\\lib" -e 1', 'ruby "-I[path]" -e 1'], + ["ruby /Program\\ Files/setup.rb", "ruby [path]"], [ "env 'BUILD_LABEL=North West' bin/rspec", "env 'BUILD_LABEL=[value]' bin/rspec", diff --git a/test/service-client.test.js b/test/service-client.test.js index bdba873..cf634d7 100644 --- a/test/service-client.test.js +++ b/test/service-client.test.js @@ -351,6 +351,23 @@ test("a 429 that is the command's first response still carries the update notice 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" }, From 4ca3ccbf06e0d15deb78df05e6ac9c83b93f14bb Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Fri, 20 Nov 2026 18:15:51 -0600 Subject: [PATCH 07/14] Shape failure report fields instead of redacting Each review round found another way a secret could slip past a pattern for what secrets look like: a multiline quoted assignment, a quoted path with an apostrophe, a masked assignment that swallowed the command after it. Patterns for secrets will keep missing cases. Each field now has a shape, and what does not fit is left out. rerun is an RSpec run of the app's specs after any leading assignments are dropped; error_class is a Ruby constant; frames are app paths with a line number; versions are numbers. message and fix_summary keep the first line's plain words, with quoted spans and any word that can carry a value replaced by a placeholder. The preview prints the shaped report and names what was left out. The Service applies the same shapes, so the two layers agree. The login reference now says a version stop replaces login's result only when it stops a request login still had to send. --- docs/commands.md | 37 ++-- src/cli.js | 47 ++--- src/commands/report.js | 361 ++++++++++++++++++++------------------ test/report.test.js | 382 ++++++++++++++++++----------------------- 4 files changed, 407 insertions(+), 420 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 8fe9f2b..fd7d6c2 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -72,8 +72,9 @@ slow down, and stops when the code expires. 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 or a required update ends it with `rate_limited`, `update_required`, or -`api_contract_unsupported` ([update line and refusals](#update-line-and-refusals)). Other failures exit 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). @@ -592,22 +593,26 @@ firstdraft report failure --kind spec_failure \ 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 `--kind` (`spec_failure`, `setup_failure`, `boot_error`, or `lint_failure`), `--rerun` (the -command that reproduces the failure), and `--error-class` (the exception class, or the lint rule's name). `--message`, -`--frame` (repeatable: a place in the application such as `app/models/post.rb:12`), `--fix-summary` (one line on the -agent's fix), `--ruby-version`, and `--rails-version` are optional. Before it prints the report, the CLI removes -terminal escapes and control characters, then replaces email addresses with `[email]`, the value of an -environment-style `NAME=value` assignment (in `--rerun`, of any `name=value` assignment) with `[value]`, absolute -paths (also after an option such as `-I`, in quotes, or as a `file://` URL) with `[path]`, and recognized credential -formats, and runs of 32 or more letters, digits, `_`, or `-` that mix letters and digits, with `[token]`. An absolute -path inside the current directory becomes relative to it instead. A frame outside it, absolute, or reached through -`..` is left out. It keeps the first -300 characters of the rerun command and of the message, 200 of the fix summary, and 20 frames. This is a safeguard, -not a guarantee, so read the printed report. A failure report carries no diff, environment variable, or file +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/` made of letters, digits, `_`, `.`, `/`, and `-`, each with optional `:LINE` parts. Leading environment assignments, with or without `env`, are dropped first. | +| `--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`. | + +Free text keeps plain words only. After taking the first line and cutting it, the CLI replaces with `[…]` every span +in single quotes, double quotes, or backticks, and every word that contains `=`, `/`, `\`, `@`, or a quote, or is +longer than 24 characters. A `lint_failure` therefore sends no rule name, and a rerun command that is not an RSpec run +is left out. A failure report carries no diff, environment variable, path outside the application, or file contents. -Each command writes `Sending this report for Compilation to :` and the exact JSON -body on standard output, sends that body once in a `POST` to the origin pinned by a successful push, and writes +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. diff --git a/src/cli.js b/src/cli.js index 930f5fa..93c0a0f 100644 --- a/src/cli.js +++ b/src/cli.js @@ -207,19 +207,18 @@ nothing and the command still exits 0. const REPORT_FAILURE_HELP = `First Draft CLI Usage: - firstdraft report failure --kind --rerun - --error-class [options] + 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 Command that reproduces the failure - --error-class Exception class, or the lint rule's name - --message Error message (first 300 characters) + --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 (first 200 characters) + --fix-summary One line on the fix (plain words) --ruby-version Ruby version --rails-version Rails version -h, --help Show help @@ -228,11 +227,11 @@ Environment: FIRSTDRAFT_API_TOKEN Authenticate production or custom API origins FIRSTDRAFT_STAGING_API_TOKEN Authenticate staging.firstdraft.com -The command replaces email addresses, absolute paths, NAME=value assignments, -and token-like strings, leaves out frames outside the current directory, prints -the exact report, then sends it once to the origin pinned by a successful plan -push. Run it from the generated application's root. When the account -has reports off, First Draft keeps nothing and the command still exits 0. +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 @@ -3292,7 +3291,7 @@ async function runReportProgress(options) { wrapper: "progress_report", route: SERVICE_ROUTES.sendProgressReport, compilationId, - body: () => progressReportBody(step, counts), + body: () => ({ body: progressReportBody(step, counts), omitted: [] }), }, ); } @@ -3352,12 +3351,7 @@ async function runReportFailure(options) { parsed.positionals.length !== 1 || !isUuidV7(compilationId) || kind === undefined || - !FAILURE_KINDS.includes(kind) || - !hasText(rerun) || - !hasText(errorClass) || - [rubyVersion, railsVersion].some( - (version) => version !== undefined && !RUNTIME_VERSION.test(version), - ) + !FAILURE_KINDS.includes(kind) ) { return invalid(); } @@ -3387,13 +3381,6 @@ async function runReportFailure(options) { ); } -const RUNTIME_VERSION = /^[0-9][0-9A-Za-z.+-]{0,31}$/; - -/** @param {string | undefined} value @returns {value is string} */ -function hasText(value) { - return value !== undefined && value.trim() !== ""; -} - /** * @param {string} value * @returns {number | null} null when the value is not a count @@ -3410,7 +3397,7 @@ function parseReportCount(value) { * pinned origin. * * @param {ServiceCommandOptions} options - * @param {{noun: string, wrapper: string, route: {method: string, path: string}, compilationId: string, body: (cwd: string) => unknown}} report + * @param {{noun: string, wrapper: string, route: {method: string, path: string}, compilationId: string, body: (cwd: string) => {body: unknown, omitted: string[]}}} report */ async function sendReportCommand( options, @@ -3424,9 +3411,13 @@ async function sendReportCommand( return 1; } - const text = `${JSON.stringify(body(pinned.cwd), null, 2)}\n`; + 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}`, + `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({ diff --git a/src/commands/report.js b/src/commands/report.js index 49fc268..43d4801 100644 --- a/src/commands/report.js +++ b/src/commands/report.js @@ -26,77 +26,36 @@ export const FAILURE_KINDS = Object.freeze([ ]); const MAX_FAILURE_FRAMES = 20; -// Code points kept in each free-text field after redaction. +// 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; - -// eslint-disable-next-line no-control-regex -const ANSI_ESCAPE = /\u001b\[[0-9;?]*[ -/]*[@-~]/g; -// eslint-disable-next-line no-control-regex -const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f]/g; -const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+/g; -// An absolute path: one in a home directory, on a drive, on a network share -// (\\host\share or //host/share), or from the root with at least two -// segments. It may start a word or follow a command option such as -I or -// --require=. A URL's path, a relative path such as app/models/post.rb, and -// ./spec/... are not matched. A path in quotes may contain spaces. -const PATH_CHARACTER = String.raw`[^\s'"` + "`" + String.raw`()<>[\]{},;]`; -const SEGMENT = String.raw`[^\s\\/'"` + "`" + String.raw`()<>[\]{},;]`; -const PATH_START = String.raw`(?:(? clip(redact(text, cwd), limit); - const kept = frames - .map((frame) => field(frame, MAX_FRAME)) - .filter((frame) => !OUTSIDE_FRAME.test(frame)) - // The Service accepts frames with / separators only. - .map((frame) => frame.replace(/^[^:]*/, (file) => file.replace(/\\/g, "/"))) - .slice(0, MAX_FAILURE_FRAMES); - const versions = { - ...(rubyVersion === undefined ? {} : { ruby: rubyVersion }), - ...(railsVersion === undefined ? {} : { rails: railsVersion }), - }; + /** @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); + const shapedFixSummary = + fixSummary === undefined + ? undefined + : plainWords(fixSummary, MAX_FIX_SUMMARY); return { - failure_report: { - kind, - rerun: clip( - redact( - rerun - .replace(QUOTED_COMMAND_ASSIGNMENT, quotedAssignment) - .replace(COMMAND_ASSIGNMENT, "$1=[value]"), - cwd, - ), - MAX_RERUN, - ), - error_class: field(errorClass, MAX_ERROR_CLASS), - ...(message === undefined - ? {} - : { message: field(message, MAX_MESSAGE) }), - ...(kept.length === 0 ? {} : { frames: kept }), - ...(fixSummary === undefined - ? {} - : { fix_summary: field(fixSummary, MAX_FIX_SUMMARY) }), - ...(Object.keys(versions).length === 0 ? {} : { versions }), + 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, }; } /** - * Removes terminal escapes and control characters other than tab and - * newline, then replaces email addresses, absolute paths, and token-like - * strings. An absolute path inside `cwd` becomes relative to it. + * The command without its leading environment assignments, when what is left + * is an RSpec run of the application's specs. * - * @param {string} text - * @param {string} cwd + * @param {string} command + * @returns {string | undefined} */ -export function redact(text, cwd) { - const root = cwd.replace(/[\\/]+$/, ""); - /** @param {string} match */ - const replacePath = (match) => { - const inside = - root !== "" && - (match.startsWith(`${root}/`) || match.startsWith(`${root}\\`)); - const relative = match.slice(root.length + 1); - return inside && relative !== "" ? relative : REDACTED_PATH; - }; - // The current directory may contain spaces, which end an unquoted path, so - // its prefix is removed before paths are matched. - const rootPrefix = - root === "" - ? null - : new RegExp( - `${PATH_START}${root.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\\\/](?=${PATH_CHARACTER})`, - "g", - ); +export function rspecRun(command) { + const words = shellWords(command); + if (words === null) return undefined; - const quotedPathsRedacted = text - .replace(ANSI_ESCAPE, "") - .replace(CONTROL, "") - .replace(EMAIL, "[email]") - .replace(CREDENTIAL, "[token]") - .replace(QUOTED_ASSIGNMENT, quotedAssignment) - .replace(ASSIGNMENT, "$1=[value]") - .replace(QUOTED, (match, quote, inner) => { - if (ABSOLUTE_START.test(inner)) { - return `${quote}${replacePath(inner)}${quote}`; - } - const [, option, operand] = QUOTED_OPTION.exec(inner) ?? []; - return option !== undefined && - operand !== undefined && - ABSOLUTE_START.test(operand) - ? `${quote}${option}${replacePath(operand)}${quote}` - : match; - }) - .replace(FILE_URL, REDACTED_PATH); + 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; + } - return ( - rootPrefix === null - ? quotedPathsRedacted - : quotedPathsRedacted.replace(rootPrefix, "") - ) - .replace(OPTION_PATH, replacePath) - .replace(ABSOLUTE_PATH, replacePath) - .replace(TOKEN_CANDIDATE, (match) => - /\d/.test(match) && /[A-Za-z]/.test(match) ? "[token]" : match, - ); + const run = words + .slice(start) + .map((word) => word.raw) + .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; } /** - * @param {string} match - * @param {string | undefined} doubleQuoted - * @param {string | undefined} singleQuoted + * 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 first line of free text, cut to `limit`, with every span that can + * carry a value replaced by a placeholder, so plain words remain. + * + * @param {string} text + * @param {number} limit */ -function quotedAssignment(match, doubleQuoted, singleQuoted) { - return doubleQuoted === undefined - ? `'${singleQuoted}=[value]'` - : `"${doubleQuoted}=[value]"`; +export function plainWords(text, limit) { + const [firstLine = ""] = text.split(/\r\n|\r|\n/, 1); + return clip(firstLine.replace(/\t/g, " ").replace(CONTROL, ""), limit) + .replace(QUOTED_SPAN, PLACEHOLDER) + .split(/\s+/) + .filter((word) => word !== "") + .map((word) => + word === PLACEHOLDER || + (!VALUE_WORD.test(word) && Array.from(word).length <= MAX_PLAIN_WORD) + ? word + : PLACEHOLDER, + ) + .join(" "); } /** @param {string} text @param {number} limit */ diff --git a/test/report.test.js b/test/report.test.js index 8931888..cf861fd 100644 --- a/test/report.test.js +++ b/test/report.test.js @@ -11,7 +11,11 @@ import path from "node:path"; import test from "node:test"; import { run } from "../src/cli.js"; -import { failureReportBody, redact } from "../src/commands/report.js"; +import { + failureReportBody, + plainWords, + rspecRun, +} from "../src/commands/report.js"; const PRODUCTION = "https://firstdraft.com"; const STAGING = "https://staging.firstdraft.com"; @@ -30,8 +34,6 @@ const FAILURE = [ COMPILATION_ID, "--kind", "boot_error", - "--rerun", - "bin/rails runner 1", "--error-class", "NameError", ]; @@ -353,40 +355,13 @@ test("report failures are handled without retrying", async (context) => { }); test("report failure validates its arguments before any request", async () => { - const [, , , ...required] = FAILURE; for (const argv of [ - ["report", "failure", COMPILATION_ID, ...required.slice(2)], - [ - "report", - "failure", - COMPILATION_ID, - ...required.slice(0, 2), - ...required.slice(4), - ], - ["report", "failure", COMPILATION_ID, ...required.slice(0, 4)], + ["report", "failure", COMPILATION_ID], + ["report", "failure", COMPILATION_ID, "--kind", "lint"], [...FAILURE, "--kind", "lint_failure"], - [ - "report", - "failure", - COMPILATION_ID, - "--kind", - "lint", - ...required.slice(2), - ], - [ - "report", - "failure", - COMPILATION_ID, - ...required.slice(0, 2), - "--rerun", - " ", - ...required.slice(4), - ], - [...FAILURE.slice(0, -1), " "], - [...FAILURE, "--ruby-version", "three"], - [...FAILURE, "--rails-version", "8 1"], [...FAILURE, "--fix-summary", "a", "--fix-summary", "b"], - ["report", "failure", "canary", ...required], + [...FAILURE, "--canary"], + ["report", "failure", "canary", "--kind", "boot_error"], ]) { const result = await invoke(argv); assert.equal(result.status, 2, argv.join(" ")); @@ -398,17 +373,10 @@ test("report failure validates its arguments before any request", async () => { } }); -test("report failure redacts, cuts, and prints exactly what it sends", async (context) => { +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 frames = [ - "/usr/lib/ruby/3.4.0/forwardable.rb:238:in 'Forwardable#delegate'", - ...Array.from( - { length: 22 }, - (_, index) => `${cwd}/app/models/movie.rb:${index + 1}:in 'Movie#rate'`, - ), - ]; const result = await invoke( [ "report", @@ -417,18 +385,21 @@ test("report failure redacts, cuts, and prints exactly what it sends", async (co "--kind", "spec_failure", "--rerun", - `bundle exec rspec ${cwd}/spec/models/movie_spec.rb:42`, + "RAILS_ENV=test bundle exec rspec ./spec/models/movie_spec.rb:42", "--error-class", "NoMethodError", "--message", - `undefined method 'stars' for nil\u001b[31m in /home/sam/.gem/x.rb mail sam@example.com token fd_${"a1".repeat(20)} ${"m".repeat(400)}`, - ...frames.flatMap((frame) => ["--frame", frame]), + "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. ${"s".repeat(300)}`, + "Guarded nil ratings in Movie#rate.", "--ruby-version", "3.4.7", "--rails-version", - "8.1.4", + "8.1.4-canary", ], { cwd, @@ -445,84 +416,172 @@ test("report failure redacts, cuts, and prints exactly what it sends", async (co 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 […] for nil in […]", + 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}Sent.\n`, + `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", ); - const report = JSON.parse(sent).failure_report; - assert.deepEqual(Object.keys(report), [ - "kind", - "rerun", - "error_class", - "message", - "frames", - "fix_summary", - "versions", - ]); - assert.equal(report.rerun, "bundle exec rspec spec/models/movie_spec.rb:42"); - assert.equal( - report.message, - `undefined method 'stars' for nil in [path] mail [email] token [token] ${"m".repeat(400)}`.slice( - 0, - 300, - ), - ); - assert.equal(report.frames.length, 20); - assert.equal(report.frames[0], "app/models/movie.rb:1:in 'Movie#rate'"); - assert.equal(Array.from(report.fix_summary).length, 200); - assert.ok(report.fix_summary.startsWith("Guarded nil ratings. ")); - assert.deepEqual(report.versions, { ruby: "3.4.7", rails: "8.1.4" }); - assert.doesNotMatch(sent, /\/home|\/usr|sam@|fd_|\\u001b|\/private|\/var/); }); -test("a failure report carries only the optional fields that were given", async (context) => { +test("a failure report carries only the fields that fit their shapes", async (context) => { /** @type {unknown} */ let sent; - const result = await invoke(FAILURE, { - 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", - rerun: "bin/rails runner 1", - error_class: "NameError", - }, - }); -}); - -test("a rerun command's assignments and frames outside the application stay home", () => { - const { failure_report: report } = failureReportBody( + const result = await invoke( + [ + ...FAILURE.slice(0, 5), + "--rerun", + "bin/rubocop", + "--error-class", + "Rails/Delegate", + ], { - kind: "lint_failure", - rerun: - "npm_config_registry=https://registry.example.test PASS=a\\ b bin/rubocop --format=progress", - errorClass: "Rails/Delegate", - frames: ["/boot.rb:3", "C:\\x.rb:2", "app/x.rb:1", "../lib/y.rb:4"], + cwd: projectDirectory(context, PRODUCTION), + fetchFunction: async (_input, init) => { + sent = JSON.parse(String(init?.body)); + return acknowledgment("failure_report"); + }, }, - CWD, ); - assert.equal( - report.rerun, - "npm_config_registry=[value] PASS=[value] bin/rubocop --format=progress", + 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/, ); - assert.deepEqual(report.frames, ["app/x.rb:1"]); +}); - const windows = failureReportBody( +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, + ], + ["bin/rubocop", undefined], + ["bin/rails runner 1", undefined], + ["rspec", undefined], + ["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 of its first line", () => { + for (const [text, expected] of /** @type {[string, string][]} */ ([ + [ + "undefined method 'stars' for nil:NilClass", + "undefined method […] for nil:NilClass", + ], + // The quoted path with an apostrophe, from review. + [`load "/Users/O'Brien/First Draft/report.rb" now`, "load […] now"], + ["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 […]"], + ["can't find `x`", "[…] find […]"], + ["tabs\tand\u0007 bells", "tabs and bells"], + ])) { + assert.equal(plainWords(text, 300), expected, text); + } + assert.equal(plainWords("word ".repeat(100), 300).split(" ").length, 60); +}); + +test("frames, error classes, and versions keep only their shapes", () => { + const { body, omitted } = failureReportBody( { kind: "spec_failure", - rerun: 'label=North" West" ruby -I /gems -I/Shared\\ Gems x.rb', - errorClass: "NoMethodError", - frames: ["app\\models\\movie.rb:12:in 'Movie#rate'"], + 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, - ).failure_report; - assert.equal(windows.rerun, "label=[value] ruby -I [path] -I[path] x.rb"); - assert.deepEqual(windows.frames, ["app/models/movie.rb:12:in 'Movie#rate'"]); + ); + 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) => { @@ -545,27 +604,6 @@ test("a malformed Project state is reported, not replaced by an archived one", a assert.equal(JSON.parse(result.stderr).error, "local_input_unreadable"); }); -test("a current directory with spaces still makes its paths relative", () => { - for (const [ - text, - cwd, - expected, - ] of /** @type {[string, string, string][]} */ ([ - [ - "Error in /Users/Jane Doe/movie_catalog/app/models/movie.rb:12 here", - "/Users/Jane Doe/movie_catalog", - "Error in app/models/movie.rb:12 here", - ], - [ - "C:\\Users\\Jane Doe\\movie_catalog\\app\\x.rb:3", - "C:\\Users\\Jane Doe\\movie_catalog", - "app\\x.rb:3", - ], - ])) { - assert.equal(redact(text, cwd), expected); - } -}); - 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"); @@ -610,92 +648,10 @@ test("reports run from an adopted application root find the archived Project", a ); assert.deepEqual( JSON.parse(String(requests[0]?.body)).failure_report.frames, - ["app/models/movie.rb:12:in 'Movie#rate'"], + ["app/models/movie.rb:12"], ); }); -test("redaction keeps relative paths and URLs and replaces what identifies a computer", () => { - for (const [text, expected] of /** @type {[string, string][]} */ ([ - ["app/models/post.rb:12", "app/models/post.rb:12"], - ["./spec/models/post_spec.rb:3", "./spec/models/post_spec.rb:3"], - ["Rails/Delegate", "Rails/Delegate"], - [ - "see https://firstdraft.com/update now", - "see https://firstdraft.com/update now", - ], - [`${CWD}/config/database.yml:3: bad`, "config/database.yml:3: bad"], - [`${CWD}-other/secret.rb`, "[path]"], - ["/Users/sam/code/app/x.rb", "[path]"], - ["~/code/app/x.rb", "[path]"], - ["C:\\Users\\sam\\app\\x.rb", "[path]"], - ["\\\\fileserver\\share\\Board\\x.md:3", "[path]"], - ["//fileserver/share/x.md", "[path]"], - ["~/notes.txt", "[path]"], - ["file:///Users/sam/x.rb", "[path]"], - ['open "/Users/sam/Work/Board Minutes.md" failed', 'open "[path]" failed'], - [`'${CWD}/app/My File.rb'`, "'app/My File.rb'"], - ["'rspec' and \"/ two\"", "'rspec' and \"/ two\""], - ["LABEL=internal-only bin/rspec", "LABEL=[value] bin/rspec"], - ["SECRET=a\\ b rest", "SECRET=[value] rest"], - ["ruby -I/gems bin/test", "ruby -I[path] bin/test"], - ["token fd_abcdefghijklmnopqrstuv here", "token [token] here"], - [ - "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.abc", - "Authorization: Bearer [token]", - ], - ["found /.dockerenv here", "found [path] here"], - ['ruby "-I/Team Notes/lib" x.rb', 'ruby "-I[path]" x.rb'], - [ - `env "BUILD_LABEL=O'Brien West" bin/rspec`, - `env "BUILD_LABEL=[value]" bin/rspec`, - ], - [`env 'LABEL=say "hi" now' x`, "env 'LABEL=[value]' x"], - ['ruby "-IC:\\My Work\\lib" -e 1', 'ruby "-I[path]" -e 1'], - ["ruby /Program\\ Files/setup.rb", "ruby [path]"], - [ - "env 'BUILD_LABEL=North West' bin/rspec", - "env 'BUILD_LABEL=[value]' bin/rspec", - ], - [ - "undefined method `/' for nil and/or", - "undefined method `/' for nil and/or", - ], - [ - 'RAILS_ENV=test SECRET="a b" bin/rails', - "RAILS_ENV=[value] SECRET=[value] bin/rails", - ], - [ - "expected count=3 with --format=progress", - "expected count=3 with --format=progress", - ], - ["ruby -I/Users/example/local-gems/lib x.rb", "ruby -I[path] x.rb"], - ["rspec --require=/Users/x/spec_helper.rb", "rspec --require=[path]"], - [ - 'open "file:///Users/sam/My Secret/a.txt" and "/Users/sam/My Secret.txt"', - 'open "[path]" and "[path]"', - ], - ["(file:///Users/sam/a.rb)", "([path])"], - ["a / b and 3/4", "a / b and 3/4"], - ["user.name+tag@mail.example.org", "[email]"], - ["id 0190f3a2-7c1d-7e00-8b1a-3f9e2d4c5b6a", "id [token]"], - [ - "sha 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", - "sha [token]", - ], - [ - "Compilation 01900000-0000-7000-8000-000000009101", - "Compilation 01900000-0000-7000-8000-000000009101", - ], - [ - "movie_reviews_controller_index_action_name", - "movie_reviews_controller_index_action_name", - ], - ["line\r\nnext\tcolumn\u0007", "line\nnext\tcolumn"], - ])) { - assert.equal(redact(text, CWD), expected, text); - } -}); - /** @param {string} wrapper the report's key in First Draft's acknowledgment */ function acknowledgment(wrapper) { const report = { id: STORED_ID, compilation_id: COMPILATION_ID }; From 4f6493692c941554dd20347034510e204fcf5d95 Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Fri, 20 Nov 2026 18:29:41 -0600 Subject: [PATCH 08/14] Cut free text at its first quote character Pairing quotes in a failure report's message or fix summary still let words through: a quote that closed on the next line or past the length limit, or an apostrophe in a word paired with one inside a quoted path. Quotes are no longer paired. From the word that holds the first quote character, the rest of the line is one placeholder; before it, words that can carry a value are replaced as before, and the length limit drops whole words. --- docs/commands.md | 11 +++++---- src/commands/report.js | 55 ++++++++++++++++++++++++------------------ test/report.test.js | 27 +++++++++++++++------ 3 files changed, 57 insertions(+), 36 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index fd7d6c2..dc4e4af 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -605,11 +605,12 @@ field is sent only in its shape, and left out otherwise: | `--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`. | -Free text keeps plain words only. After taking the first line and cutting it, the CLI replaces with `[…]` every span -in single quotes, double quotes, or backticks, and every word that contains `=`, `/`, `\`, `@`, or a quote, or is -longer than 24 characters. A `lint_failure` therefore sends no rule name, and a rerun command that is not an RSpec run -is left out. A failure report carries no diff, environment variable, path outside the application, or file -contents. +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. A failure report carries no diff, environment variable, path outside the application, or +file contents. 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 diff --git a/src/commands/report.js b/src/commands/report.js index 43d4801..a730552 100644 --- a/src/commands/report.js +++ b/src/commands/report.js @@ -50,10 +50,12 @@ const VERSION_NUMBER = /^\d+(?:\.\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]/g; -const QUOTED_SPAN = /'[^']*'|"[^"]*"|`[^`]*`/g; -// A word that can carry a value: an assignment, a path or URL, an address, a -// quote, or anything long enough to be a token. -const VALUE_WORD = /[=/\\@'"`]/; +// 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 = "[…]"; @@ -300,33 +302,40 @@ function appFrame(frame, cwd) { } /** - * The first line of free text, cut to `limit`, with every span that can - * carry a value replaced by a placeholder, so plain words remain. + * 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/, 1); - return clip(firstLine.replace(/\t/g, " ").replace(CONTROL, ""), limit) - .replace(QUOTED_SPAN, PLACEHOLDER) + 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 !== "") - .map((word) => - word === PLACEHOLDER || - (!VALUE_WORD.test(word) && Array.from(word).length <= MAX_PLAIN_WORD) - ? word - : PLACEHOLDER, - ) - .join(" "); -} + .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); -/** @param {string} text @param {number} limit */ -function clip(text, limit) { - const characters = Array.from(text); - return characters.length <= limit - ? text - : characters.slice(0, limit).join(""); + /** @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(" "); } /** diff --git a/test/report.test.js b/test/report.test.js index cf861fd..490c526 100644 --- a/test/report.test.js +++ b/test/report.test.js @@ -421,7 +421,7 @@ test("report failure prints exactly the shaped report and what it left out", asy kind: "spec_failure", rerun: "bundle exec rspec ./spec/models/movie_spec.rb:42", error_class: "NoMethodError", - message: "undefined method […] for nil in […]", + message: "undefined method […]", frames: ["app/models/movie.rb:12"], fix_summary: "Guarded nil ratings in Movie#rate.", versions: { ruby: "3.4.7" }, @@ -513,14 +513,23 @@ test("rerun keeps only an RSpec run of the application's specs", () => { } }); -test("free text keeps the plain words of its first line", () => { +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`, "[…]"], [ - "undefined method 'stars' for nil:NilClass", - "undefined method […] for nil:NilClass", + "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", ], - // The quoted path with an apostrophe, from review. - [`load "/Users/O'Brien/First Draft/report.rb" now`, "load […] now"], ["first line\nsecond line with a secret", "first line"], [ "sam@example.com at https://x.test/a and C:\\Users\\sam", @@ -529,12 +538,14 @@ test("free text keeps the plain words of its first line", () => { ["LABEL=North West", "[…] West"], ["token fd_abcdefghijklmnopqrstuvwxyz", "token […]"], ["Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.abc", "Bearer […]"], - ["can't find `x`", "[…] find […]"], ["tabs\tand\u0007 bells", "tabs and bells"], ])) { assert.equal(plainWords(text, 300), expected, text); } - assert.equal(plainWords("word ".repeat(100), 300).split(" ").length, 60); + 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("frames, error classes, and versions keep only their shapes", () => { From 4fd1d4781964b467e0ea6d566e6540e642ed6fb5 Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Fri, 20 Nov 2026 18:41:47 -0600 Subject: [PATCH 09/14] Send spec directories without a trailing slash The Service's shape for a rerun path is components of safe characters separated by single slashes, so bundle exec rspec spec/models/ was refused while the same run without the slash was accepted. The CLI now removes a trailing slash after a spec directory and uses the same component grammar, so it leaves out what the Service would refuse rather than sending it. --- docs/commands.md | 16 ++++++++-------- src/commands/report.js | 6 ++++-- test/report.test.js | 8 ++++++++ 3 files changed, 20 insertions(+), 10 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index dc4e4af..5b88c5b 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -596,14 +596,14 @@ 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/` made of letters, digits, `_`, `.`, `/`, and `-`, each with optional `:LINE` parts. Leading environment assignments, with or without `env`, are dropped first. | -| `--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`. | +| 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`. | 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 `[…]`, diff --git a/src/commands/report.js b/src/commands/report.js index a730552..d097e4a 100644 --- a/src/commands/report.js +++ b/src/commands/report.js @@ -36,7 +36,8 @@ const MAX_ERROR_CLASS = 200; const MAX_RERUN = 300; const MAX_FRAME = 300; const MAX_VERSION = 32; -const SAFE_PATH = String.raw`[A-Za-z0-9_./-]+`; +// 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+)*)+$`, @@ -226,9 +227,10 @@ export function rspecRun(command) { start += 1; } + // A spec directory may be written with a trailing slash: spec/models/. const run = words .slice(start) - .map((word) => word.raw) + .map((word) => word.raw.replace(/^((?:\.\/)?spec\/.*[^/])\/+$/, "$1")) .join(" "); return run.length <= MAX_RERUN && RERUN.test(run) && !PARENT_SEGMENT.test(run) ? run diff --git a/test/report.test.js b/test/report.test.js index 490c526..21c8121 100644 --- a/test/report.test.js +++ b/test/report.test.js @@ -500,6 +500,14 @@ test("rerun keeps only an RSpec run of the application's specs", () => { "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], From 7e86991b43e745d6fc6e9382c233efa27ec97605 Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Fri, 20 Nov 2026 23:46:19 -0600 Subject: [PATCH 10/14] Test report shaping against the service's examples The CLI shapes each failure-report field and the service refuses what does not fit, so the two must agree on the same strings. A copy of the service's accepted and refused examples now drives a test: every accepted example passes through the CLI unchanged, and what the CLI builds from a refused one is a fixed point that is not itself refused, or the field is left out. The test found the CLI leaving out values the service accepts: an error class with a leading :: and versions such as 8.2.0.beta1 or 3.4.0-preview2. Line numbers, control characters, and the client facts' length now match the service's limits too. The fixture is kept byte for byte, so Prettier skips it. --- .prettierignore | 1 + docs/commands.md | 2 +- src/commands/report.js | 12 +- src/service-client.js | 7 +- test/failure-report-shapes.test.js | 134 +++++++++++++++++++++++ test/fixtures/failure-report-shapes.json | 106 ++++++++++++++++++ 6 files changed, 253 insertions(+), 9 deletions(-) create mode 100644 .prettierignore create mode 100644 test/failure-report-shapes.test.js create mode 100644 test/fixtures/failure-report-shapes.json 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/docs/commands.md b/docs/commands.md index 5b88c5b..395e42f 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -603,7 +603,7 @@ field is sent only in its shape, and left out otherwise: | `--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`. | +| `--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 `[…]`, diff --git a/src/commands/report.js b/src/commands/report.js index d097e4a..784651e 100644 --- a/src/commands/report.js +++ b/src/commands/report.js @@ -40,17 +40,19 @@ const MAX_VERSION = 32; 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+)*)+$`, + 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 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+)(?::in .*)?$`, + String.raw`^(?:\./)?((?:app|lib|config|db|spec)/${SAFE_PATH}):(\d{1,7})(?::in .*)?$`, ); const PARENT_SEGMENT = /(?:^|\/)\.\.(?:\/|:|$)/; -const VERSION_NUMBER = /^\d+(?:\.\d+){0,3}$/; +// 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]/g; +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 = /['"`]/; diff --git a/src/service-client.js b/src/service-client.js index 8fe4d2f..5e5ef20 100644 --- a/src/service-client.js +++ b/src/service-client.js @@ -25,11 +25,12 @@ export const AGENT_VARIABLE = "FIRSTDRAFT_AGENT"; // 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,63}$/; +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 when one value is longer. -const MAX_FACT_LENGTH = 64; +// 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 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"}} + ] + } +} From 1ab7a3a470499b2ac250cc53d8908c71dac1e44f Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Sat, 21 Nov 2026 00:07:38 -0600 Subject: [PATCH 11/14] Close the last report and version gaps A half version pair said nothing useful, so the update line and the minimum check now compare a pair only when both headers are readable. A set but unreadable plugin version, blank included, compares neither pair and says so in the one stderr line, since falling back to the CLI pair would judge the wrong install. Failure reports drop paths with a parent segment, end the first line at any Unicode line break, and name a message or fix summary that has no plain words left instead of sending it empty. Progress counts above the service's maximum are refused before anything is sent. The docs now word the API requirement as this development version's and say that plain words may still quote code. --- docs/commands.md | 16 +++++--- docs/errors.md | 80 ++++++++++++++++++------------------ src/cli.js | 6 ++- src/commands/report.js | 11 ++++- src/service-client.js | 59 ++++++++++++++++++++------- test/report.test.js | 38 +++++++++++++++++ test/service-client.test.js | 81 ++++++++++++++++++++++++++----------- 7 files changed, 204 insertions(+), 87 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 395e42f..d6564d3 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -6,8 +6,8 @@ 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, retained-Compilation inspection and cancellation, the -account's report setting, progress and failure reports, and conversation upload. CLI `0.9.x` requires the -service's `0.9.x` API contract. The [changelog](https://github.com/firstdraft/cli/blob/main/CHANGELOG.md) describes +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 @@ -173,7 +173,10 @@ First Draft answers each routed `/v1` request with `FirstDraft-API-Contract` 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, and a Service that sends no CLI pair produces no line and no refusal. The update +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 @@ -589,7 +592,8 @@ firstdraft report failure --kind spec_failure \ ``` `` 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: examples in the spec +`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`. @@ -609,8 +613,8 @@ Free text keeps plain words only: the CLI takes the first line, replaces everyth 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. A failure report carries no diff, environment variable, path outside the application, or -file contents. +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 diff --git a/docs/errors.md b/docs/errors.md index a622abf..2fe8bd8 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -242,46 +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. | -| Network commands except `logout` | `update_required`, `api_contract_unsupported` | 1 | First Draft needs a newer plugin, 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. | +| 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/src/cli.js b/src/cli.js index 93c0a0f..7f5213b 100644 --- a/src/cli.js +++ b/src/cli.js @@ -193,6 +193,7 @@ Options: --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: @@ -3389,9 +3390,12 @@ function parseReportCount(value) { if (!/^(?:0|[1-9][0-9]*)$/.test(value)) return null; const count = Number(value); - return Number.isSafeInteger(count) ? count : null; + 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. diff --git a/src/commands/report.js b/src/commands/report.js index 784651e..2623b8f 100644 --- a/src/commands/report.js +++ b/src/commands/report.js @@ -46,7 +46,8 @@ 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 .*)?$`, ); -const PARENT_SEGMENT = /(?:^|\/)\.\.(?:\/|:|$)/; +// 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})?$/; @@ -181,10 +182,16 @@ export function failureReportBody( } 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: { @@ -315,7 +322,7 @@ function appFrame(frame, cwd) { * @param {number} limit */ export function plainWords(text, limit) { - const [firstLine = ""] = text.split(/\r\n|\r|\n/, 1); + 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)) diff --git a/src/service-client.js b/src/service-client.js index 5e5ef20..b99668c 100644 --- a/src/service-client.js +++ b/src/service-client.js @@ -123,9 +123,10 @@ export function createServiceSession({ // 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 but unreadable says a plugin is present - // without saying which, so neither pair is compared. - const pluginSet = (env[PLUGIN_VERSION_VARIABLE] ?? "").trim() !== ""; + // 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 @@ -158,21 +159,39 @@ export function createServiceSession({ * @returns {Promise} the response, rebuilt when its body was read */ async function observe(origin, response) { - const latest = + // A pair is compared only when both of its versions are readable. + const pair = installed === null ? null - : semver(response.headers.get(installed.latestHeader)); + : versionPair( + response, + installed.latestHeader, + installed.minimumHeader, + ); if ( installed !== null && updateLine === null && - latest !== null && - compareVersions(installed.version, latest) < 0 + pair !== null && + compareVersions(installed.version, pair.latest) < 0 ) { updateLine = - `First Draft: an update is available (${installed.label} ${latest.text}; this setup has ` + + `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) { @@ -201,19 +220,15 @@ export function createServiceSession({ return response; } - const minimum = - installed === null - ? null - : semver(response.headers.get(installed.minimumHeader)); if ( installed !== null && - minimum !== null && - compareVersions(installed.version, minimum) < 0 + pair !== null && + compareVersions(installed.version, pair.minimum) < 0 ) { stop = new UpdateRequiredError({ component: installed.component, installed: installed.version.text, - minimum: minimum.text, + minimum: pair.minimum.text, }); return response; } @@ -287,6 +302,20 @@ export function createServiceSession({ }; } +/** + * 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"} diff --git a/test/report.test.js b/test/report.test.js index 21c8121..87faa0a 100644 --- a/test/report.test.js +++ b/test/report.test.js @@ -98,6 +98,7 @@ test("report progress validates its arguments before any request", async () => { [...PROGRESS, "--examples", "-1"], [...PROGRESS, "--failures=01"], [...PROGRESS, "--items-remaining=1.5"], + [...PROGRESS, "--examples", "1000001"], [...PROGRESS, "--canary"], [...PROGRESS, COMPILATION_ID], ]) { @@ -511,6 +512,11 @@ test("rerun keeps only an RSpec run of the application's specs", () => { ["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], @@ -547,6 +553,10 @@ test("free text keeps the plain words before its first quote character", () => { ["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); } @@ -556,6 +566,34 @@ test("free text keeps the plain words before its first quote character", () => { 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( { diff --git a/test/service-client.test.js b/test/service-client.test.js index cf634d7..9333538 100644 --- a/test/service-client.test.js +++ b/test/service-client.test.js @@ -139,6 +139,7 @@ test("without a plugin version the CLI compares itself with the CLI versions", a 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"); @@ -148,22 +149,55 @@ test("without a plugin version the CLI compares itself with the CLI versions", a ]); }); -test("an unreadable plugin version compares neither pair", async () => { - const session = createServiceSession({ - env: { FIRSTDRAFT_PLUGIN_VERSION: "dev" }, - notify: () => assert.fail("No version line was expected"), - }); - 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"); +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 () => { @@ -245,10 +279,9 @@ test("a stop that did not cut the command short keeps its result and names the s env: { FIRSTDRAFT_PLUGIN_VERSION: "0.9.3" }, notify: (line) => lines.push(line), }); - await session.fetch(async () => versionedResponse({ minimum: "0.10.0" }))( - new URL("/v1/account", ORIGIN), - {}, - ); + 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, @@ -345,6 +378,7 @@ test("a 429 that is the command's first response still carries the update notice }); 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); @@ -514,7 +548,7 @@ test("plan push keeps its accepted result below the minimum and names the stop", env: { FIRSTDRAFT_PLUGIN_VERSION: "0.9.3" }, fetchFunction: async () => { requests += 1; - return acceptedPush(cwd, { minimum: "0.10.0" }); + return acceptedPush(cwd, { latest: "0.10.0", minimum: "0.10.0" }); }, }); @@ -537,7 +571,7 @@ test("plan compile sends nothing after a response below the minimum", async (con env: {}, fetchFunction: async (input, init) => { requests.push(`${init?.method} ${new URL(String(input)).pathname}`); - return acceptedPush(cwd, { minimumCli: "99.0.0" }); + return acceptedPush(cwd, { latestCli: "99.0.0", minimumCli: "99.0.0" }); }, }); @@ -595,7 +629,8 @@ test("a stop after a Compilation started names it instead of advising another", const error = await fetchFunction(url, {}).catch((cause) => cause); throw new CompilationRetainedError(error, /** @type {any} */ (current)); }, - fetchFunction: async () => versionedResponse({ minimumCli: "99.0.0" }), + fetchFunction: async () => + versionedResponse({ latestCli: "99.0.0", minimumCli: "99.0.0" }), }); assert.equal(result.status, 1); From 3bdb56bd7a74c75b26876a2d5ac619204d12cbe4 Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Sat, 21 Nov 2026 02:31:59 -0600 Subject: [PATCH 12/14] Copy the service's final report examples The service added refused rows for carriage returns and Unicode line breaks in message and fix_summary. The CLI already ends free text at the first line break of any kind, so the table test passes unchanged. --- test/fixtures/failure-report-shapes.json | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/test/fixtures/failure-report-shapes.json b/test/fixtures/failure-report-shapes.json index 48bff55..6d1ecd4 100644 --- a/test/fixtures/failure-report-shapes.json +++ b/test/fixtures/failure-report-shapes.json @@ -67,13 +67,17 @@ "mail sam@example.com", "token abcdefghijklmnopqrstuvwxyz", "two\nlines", + "two\rlines", + "two
lines", + "two
lines", + "two\u0085lines", "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"], + "refused": ["Set TOKEN=abc in […]", "Moved the file to app/models", "Returned early
Then saved"], "limit": 200 }, "version": { From 924035ce1b82a039351eeb37739ec6477b2fac22 Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Sat, 21 Nov 2026 02:31:59 -0600 Subject: [PATCH 13/14] Read the account before sending a report A person who said no to reports should have no report body leave their machine. Both report commands now read the account at the pinned origin first and send only when it says reports are on; with reports off they print the reports-off line and exit 0. A failed account read sends nothing and says so, and the 403 reports_off answer stays handled because reports can be turned off between the two requests. A stop recorded on the account read ends the command before it prints the report it would have sent. --- docs/commands.md | 21 +++-- docs/errors.md | 9 +- src/cli.js | 135 +++++++++++++++++++----------- src/service-client.js | 16 +++- test/report.test.js | 188 ++++++++++++++++++++++++++++++++++++++---- 5 files changed, 289 insertions(+), 80 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index d6564d3..d500c8d 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -163,7 +163,7 @@ Beyond the header, a command sends only what it needs: | `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 | +| `report progress`, `report failure` | An account read; with reports on, the report printed just before | | `conversation send` | The file the person agreed to send, unchanged, under its base name | ### Update line and refusals @@ -616,11 +616,17 @@ words that fit the length limit. A `lint_failure` therefore sends no rule name, 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. +Each command first reads the account with a `GET` of `/v1/account` at the origin pinned by a successful push. Unless +First Draft answers `{"reports": "on"}`, no report is sent. With reports off, the command writes a line that says so +and exits 0, so the agent's work continues. When the account cannot be read, the command fails with +`account_unavailable`, or with `invalid_server_response` when the answer breaks the account's contract. + +With reports on, the 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. It then +sends that body once in a `POST` to the same origin, and writes `Sent.` once First Draft acknowledges the stored report +with `201`; any other success is `report_unavailable`. If the person turns reports off between the two requests, First +Draft answers `403 reports_off` and keeps nothing, and the command writes the same line and exits 0. Neither command +retries. ## Send a planning conversation @@ -643,7 +649,8 @@ First Draft does not accept conversations yet. Until its service does, the comma ## Service endpoints 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 +`account` reads `/v1/account` at the origin selected as for `login`; the report commands read it, and every other +`/v1` request goes, 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 diff --git a/docs/errors.md b/docs/errors.md index 2fe8bd8..66c3407 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -202,8 +202,8 @@ Cancel never changes a succeeded or failed Compilation, and repeating it is safe ## 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 progress` and `report failure` never stop an agent's work. Each reads the account first and sends no report +unless it has reports on. With reports off, 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 @@ -212,7 +212,8 @@ keeps nothing and the command exits 0 with a line that says so; that is not an e 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. + `invalid_server_response` from `account` means the response broke its contract. From a report command, either + error means the account read failed, so no report was sent; continue without it. `conversation send` sends nothing unless the person said yes: @@ -278,7 +279,7 @@ stopped without following the replacement. | 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. | +| `report progress`, `report failure` | `report_rejected`, `report_unavailable`, `account_unavailable`, `invalid_server_response` | 1 | The report was refused or its outcome is unconfirmed, or the account read failed; 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. | diff --git a/src/cli.js b/src/cli.js index 7f5213b..29d689e 100644 --- a/src/cli.js +++ b/src/cli.js @@ -200,9 +200,9 @@ 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. +The command first reads the account at the origin pinned by a successful plan +push. With reports on, it prints the exact report, then sends it once there. +With reports off, it sends no report and still exits 0. `; const REPORT_FAILURE_HELP = `First Draft CLI @@ -230,9 +230,11 @@ Environment: 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. +version numbers, and the plain words of free text. It first reads the account +at the origin pinned by a successful plan push. With reports on, it prints the +exact report and what it left out, then sends it once there. With reports off, +it sends no report and still exits 0. Run it from the generated application's +root. `; const CONVERSATION_HELP = `First Draft CLI @@ -682,6 +684,10 @@ 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 REPORT_ACCOUNT_UNAVAILABLE_DETAIL = + "Could not read whether this account sends reports, so no report was sent. Continue without it."; +const REPORT_ACCOUNT_INVALID_RESPONSE_DETAIL = + "First Draft returned an invalid account response, so no report was sent. Continue without it."; const CONVERSATION_SEND_INVALID_ARGUMENTS_DETAIL = "Invalid arguments. Run 'firstdraft conversation send --help' for usage."; const CONVERSATION_CONSENT_REQUIRED_DETAIL = @@ -3182,34 +3188,49 @@ async function runAccount({ writeJson(stdout, account); return 0; } catch (error) { - const status = writeAccountCommandError(stderr, error); + const status = + writeAccountCommandError(stderr, error) ?? + writeAccountReadError(stderr, error, { + unavailable: ACCOUNT_UNAVAILABLE_DETAIL, + invalid: ACCOUNT_INVALID_RESPONSE_DETAIL, + }); if (status !== null) return status; - 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; - } + throw error; + } +} - if (error instanceof AccountResponseInvalidError) { - writeJson(stderr, { - error: "invalid_server_response", - detail: ACCOUNT_INVALID_RESPONSE_DETAIL, - status: error.status, - }); +/** + * @param {Writer} writer + * @param {unknown} error + * @param {{unavailable: string, invalid: string}} details + * @returns {number | null} + */ +function writeAccountReadError(writer, error, { unavailable, invalid }) { + if (error instanceof AccountUnavailableError) { + if (isAuthenticationProblem(error.status, error.response)) { + writeAuthenticationRequired(writer, error.status, error.response); return 1; } + writeJson(writer, { + error: "account_unavailable", + detail: unavailable, + ...(typeof error.status === "number" ? { status: error.status } : {}), + ...(error.response ? { response: error.response } : {}), + }); + return 1; + } - throw error; + if (error instanceof AccountResponseInvalidError) { + writeJson(writer, { + error: "invalid_server_response", + detail: invalid, + status: error.status, + }); + return 1; } + + return null; } /** @param {ServiceCommandOptions} options */ @@ -3397,8 +3418,8 @@ function parseReportCount(value) { const MAX_REPORT_COUNT = 1_000_000; /** - * Prints the exact report, then sends those bytes once to the Project's - * pinned origin. + * Reads the account at the Project's pinned origin and, only when it has + * reports on, prints the exact report and sends those bytes once there. * * @param {ServiceCommandOptions} options * @param {{noun: string, wrapper: string, route: {method: string, path: string}, compilationId: string, body: (cwd: string) => {body: unknown, omitted: string[]}}} report @@ -3417,28 +3438,48 @@ async function sendReportCommand( 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, - }), + const outcome = await service.settle( + (async () => { + // Reports are off until the person says yes, so with them off no + // report body leaves this machine. + const account = await readAccount({ + origin: pinned.apiUrl, + fetchFunction: pinned.fetchFunction, + createRequestSignal, + }); + if (account.reports !== "on") return "reports_off"; + + service.throwIfStopped(); + stdout.write( + `Sending this ${noun} for Compilation ${compilationId} to ${pinned.apiUrl}:\n${text}` + + (shaped.omitted.length === 0 + ? "" + : `Left out: ${shaped.omitted.join("; ")}.\n`), + ); + // The person can turn reports off between the two requests, which + // First Draft answers with 403 reports_off. + const sent = await sendReport({ + origin: pinned.apiUrl, + route, + projectId: pinned.projectId, + compilationId, + body: text, + wrapper, + fetchFunction: pinned.fetchFunction, + createRequestSignal, + }); + return sent.outcome; + })(), ); stdout.write(outcome === "sent" ? "Sent.\n" : REPORTS_OFF_MESSAGE); return 0; } catch (error) { - const status = writePinnedProjectError(stderr, error); + const status = + writePinnedProjectError(stderr, error) ?? + writeAccountReadError(stderr, error, { + unavailable: REPORT_ACCOUNT_UNAVAILABLE_DETAIL, + invalid: REPORT_ACCOUNT_INVALID_RESPONSE_DETAIL, + }); if (status !== null) return status; if (error instanceof ReportRejectedError) { diff --git a/src/service-client.js b/src/service-client.js index b99668c..0841305 100644 --- a/src/service-client.js +++ b/src/service-client.js @@ -85,6 +85,9 @@ export class RateLimitedError extends ServiceStopError { * 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} throwIfStopped + * Throws the recorded stop as the next request would, so a command that + * prints what it is about to send can stop before printing it. * @property {() => void} flush * Writes the version line for a command that does not settle its work. */ @@ -256,15 +259,19 @@ export function createServiceSession({ if (updateLine !== null) notify(updateLine); } + function throwIfStopped() { + if (stop !== null) { + blocked = true; + throw stop; + } + } + return { clientHeader, fetch(request = globalThis.fetch) { /** @type {typeof globalThis.fetch} */ const serviceFetch = async (input, init) => { - if (stop !== null) { - blocked = true; - throw stop; - } + throwIfStopped(); const response = await request(input, { ...init, @@ -296,6 +303,7 @@ export function createServiceSession({ flush({ versionStopReported: false }); return value; }, + throwIfStopped, flush() { flush({ versionStopReported: false }); }, diff --git a/test/report.test.js b/test/report.test.js index 87faa0a..3ccec7e 100644 --- a/test/report.test.js +++ b/test/report.test.js @@ -113,7 +113,7 @@ test("report progress validates its arguments before any request", async () => { } }); -test("report progress prints the exact report, then sends those bytes once", async (context) => { +test("report progress reads the account, prints the exact report, then sends those bytes once", async (context) => { const cwd = projectDirectory(context, PRODUCTION); /** @type {{url: string, init: RequestInit | undefined}[]} */ const requests = []; @@ -137,6 +137,7 @@ test("report progress prints the exact report, then sends those bytes once", asy cwd, fetchFunction: async (input, init) => { requests.push({ url: String(input), init }); + if (requests.length === 1) return account("on"); return new Response( `{"progress_report":{"id":"${STORED_ID}","compilation_id":"${COMPILATION_ID}"}}`, { @@ -168,9 +169,16 @@ test("report progress prints the exact report, then sends those bytes once", asy 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(requests.length, 2); + const [read, request] = requests; + assert(read && request); + assert.equal(read.url, `${PRODUCTION}/v1/account`); + assert.equal(read.init?.method ?? "GET", "GET"); + assert.equal(read.init?.body, undefined); + assert.equal( + new Headers(read.init?.headers).get("authorization"), + `Bearer ${TOKEN}`, + ); assert.equal( request.url, `${PRODUCTION}/v1/projects/${PROJECT_ID}/compilations/${COMPILATION_ID}/progress-reports`, @@ -194,6 +202,9 @@ test("a progress report without counts sends only its step, to the pinned origin new Headers(init?.headers).get("authorization"), `Bearer ${STAGING_TOKEN}`, ); + if (new URL(String(input)).pathname === "/v1/account") { + return account("on"); + } sent = JSON.parse(String(init?.body)); return acknowledgment("progress_report"); }, @@ -231,20 +242,135 @@ test("reports stop on local problems before printing anything", async (context) assert.equal(JSON.parse(noToken.stderr).error, "authentication_required"); }); -test("reports_off is a handled message with exit status 0", async (context) => { +test("with reports off, a report command sends nothing but the account read", async (context) => { + const cwd = projectDirectory(context, PRODUCTION); + for (const argv of [PROGRESS, FAILURE]) { + /** @type {{url: string, init: RequestInit | undefined}[]} */ + const requests = []; + const result = await invoke(argv, { + cwd, + fetchFunction: async (input, init) => { + requests.push({ url: String(input), init }); + return account("off"); + }, + }); + assert.deepEqual(result, { status: 0, stdout: REPORTS_OFF, stderr: "" }); + assert.equal(requests.length, 1, argv.join(" ")); + assert.equal(requests[0]?.url, `${PRODUCTION}/v1/account`); + assert.equal(requests[0]?.init?.method ?? "GET", "GET"); + assert.equal(requests[0]?.init?.body, undefined); + } +}); + +test("reports turned off after the account read are 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 () => + fetchFunction: reportsOn(async () => problem(403, "reports_off", "This account has not agreed to reports."), + ), }); assert.equal(result.status, 0); assert.equal(result.stderr, ""); + assert.match(result.stdout, /^Sending this /); assert.ok(result.stdout.endsWith(REPORTS_OFF), result.stdout); } }); +test("a stop on the account read prints and sends no report", async (context) => { + const cwd = projectDirectory(context, PRODUCTION); + for (const [response, error] of [ + [ + () => + new Response('{"reports":"on"}', { + status: 200, + headers: { + "Content-Type": "application/json", + "FirstDraft-Latest-CLI": "99.0.0", + "FirstDraft-Minimum-CLI": "99.0.0", + }, + }), + "update_required", + ], + [ + () => + new Response(null, { status: 429, headers: { "Retry-After": "60" } }), + "rate_limited", + ], + ]) { + /** @type {string[]} */ + const requests = []; + const result = await invoke(PROGRESS, { + cwd, + fetchFunction: async (input) => { + requests.push(String(input)); + return /** @type {() => Response} */ (response)(); + }, + }); + assert.deepEqual(requests, [`${PRODUCTION}/v1/account`]); + assert.equal(result.status, 1); + assert.equal(result.stdout, ""); + assert.equal(JSON.parse(result.stderr).error, error); + } +}); + +test("a report is not sent when the account cannot be read", async (context) => { + const cwd = projectDirectory(context, PRODUCTION); + const unavailable = + "Could not read whether this account sends reports, so no report was sent. Continue without it."; + const invalid = + "First Draft returned an invalid account response, so no report was sent. Continue without it."; + for (const [response, expected] of [ + [ + () => { + throw new TypeError("canary socket hang up"); + }, + { error: "account_unavailable", detail: unavailable }, + ], + [ + () => new Response("canary", { status: 503 }), + { error: "account_unavailable", detail: unavailable, status: 503 }, + ], + [ + () => + new Response('{"reports":"canary"}', { + status: 200, + headers: { "Content-Type": "application/json" }, + }), + { error: "invalid_server_response", detail: invalid, status: 200 }, + ], + [ + () => + problem(401, "authentication_required", "A valid token is required."), + { error: "authentication_required", status: 401 }, + ], + ]) { + for (const argv of [PROGRESS, FAILURE]) { + /** @type {string[]} */ + const requests = []; + const result = await invoke(argv, { + cwd, + fetchFunction: async (input, init) => { + requests.push(String(input)); + assert.equal(init?.body, undefined); + return /** @type {() => Response} */ (response)(); + }, + }); + assert.deepEqual(requests, [`${PRODUCTION}/v1/account`]); + assert.equal(result.status, 1); + assert.equal(result.stdout, ""); + const error = JSON.parse(result.stderr); + for (const [key, value] of Object.entries( + /** @type {Record} */ (expected), + )) { + assert.deepEqual(error[key], value, key); + } + assert.doesNotMatch(result.stderr, /canary/); + } + } +}); + test("a success without First Draft's acknowledgment is not reported as sent", async (context) => { const cwd = projectDirectory(context, PRODUCTION); for (const response of [ @@ -273,7 +399,7 @@ test("a success without First Draft's acknowledgment is not reported as sent", a ]) { const result = await invoke(PROGRESS, { cwd, - fetchFunction: async () => response(), + fetchFunction: reportsOn(async () => response()), }); assert.equal(result.status, 1); assert.doesNotMatch(result.stdout, /Sent\./); @@ -332,10 +458,10 @@ test("report failures are handled without retrying", async (context) => { let requests = 0; const result = await invoke(PROGRESS, { cwd, - fetchFunction: async () => { + fetchFunction: reportsOn(async () => { requests += 1; return /** @type {() => Response} */ (response)(); - }, + }), }); assert.equal(requests, 1); assert.equal(result.status, 1); @@ -345,8 +471,9 @@ test("report failures are handled without retrying", async (context) => { const unauthenticated = await invoke(PROGRESS, { cwd, - fetchFunction: async () => + fetchFunction: reportsOn(async () => problem(401, "authentication_required", "A valid token is required."), + ), }); assert.equal(unauthenticated.status, 1); assert.equal( @@ -404,14 +531,14 @@ test("report failure prints exactly the shaped report and what it left out", asy ], { cwd, - fetchFunction: async (input, init) => { + fetchFunction: reportsOn(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"); - }, + }), }, ); @@ -449,10 +576,10 @@ test("a failure report carries only the fields that fit their shapes", async (co ], { cwd: projectDirectory(context, PRODUCTION), - fetchFunction: async (_input, init) => { + fetchFunction: reportsOn(async (_input, init) => { sent = JSON.parse(String(init?.body)); return acknowledgment("failure_report"); - }, + }), }, ); assert.equal(result.status, 0, result.stderr); @@ -583,10 +710,10 @@ test("a progress count of the service's maximum is sent", async (context) => { let sent; const result = await invoke([...PROGRESS, "--examples", "1000000"], { cwd: projectDirectory(context, PRODUCTION), - fetchFunction: async (_input, init) => { + fetchFunction: reportsOn(async (_input, init) => { sent = JSON.parse(String(init?.body)); return acknowledgment("progress_report"); - }, + }), }); assert.equal(result.status, 0, result.stderr); assert.deepEqual(sent, { @@ -690,10 +817,10 @@ test("reports run from an adopted application root find the archived Project", a ], { cwd: root, - fetchFunction: async (input, init) => { + fetchFunction: reportsOn(async (input, init) => { requests.push({ url: String(input), body: String(init?.body) }); return acknowledgment("failure_report"); - }, + }), }, ); @@ -709,6 +836,31 @@ test("reports run from an adopted application root find the archived Project", a ); }); +/** + * Answers the account read at the pinned production origin with reports on, + * and hands every other request to `report`. + * + * @param {(input: string | URL | Request, init?: RequestInit) => Promise} report + * @returns {typeof globalThis.fetch} + */ +function reportsOn(report) { + return async (input, init) => { + if (new URL(String(input)).pathname !== "/v1/account") { + return report(input, init); + } + assert.equal(String(input), `${PRODUCTION}/v1/account`); + return account("on"); + }; +} + +/** @param {"on" | "off"} reports */ +function account(reports) { + return new Response(JSON.stringify({ reports }), { + status: 200, + headers: { "Content-Type": "application/json" }, + }); +} + /** @param {string} wrapper the report's key in First Draft's acknowledgment */ function acknowledgment(wrapper) { const report = { id: STORED_ID, compilation_id: COMPILATION_ID }; From cb08072fb981e7e99312561befa48633f78b6208 Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Sat, 21 Nov 2026 02:40:45 -0600 Subject: [PATCH 14/14] Name each error a report's account read ends in The reference listed only the account errors, but a rejected token, a 429, or an update refusal on the account read also ends the command before any report is sent, and each has its own recovery. --- docs/commands.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index d500c8d..e49d23b 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -618,8 +618,10 @@ the plain words of a message or fix summary it is given can still quote code, so Each command first reads the account with a `GET` of `/v1/account` at the origin pinned by a successful push. Unless First Draft answers `{"reports": "on"}`, no report is sent. With reports off, the command writes a line that says so -and exits 0, so the agent's work continues. When the account cannot be read, the command fails with -`account_unavailable`, or with `invalid_server_response` when the answer breaks the account's contract. +and exits 0, so the agent's work continues. When the account read fails, no report is sent either. The command then +ends with `account_unavailable`, with `invalid_server_response` when the answer breaks the account's contract, or with +an error that any request can give: [`authentication_required`](errors.md#environment-and-credential-errors), or +`rate_limited` or an update refusal ([update and limit errors](errors.md#update-and-limit-errors)). With reports on, the 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. It then