Skip to content

State client facts and send reports with consent - #63

Draft
raghubetina wants to merge 11 commits into
mainfrom
invite/release-cli
Draft

raghubetina wants to merge 11 commits into
mainfrom
invite/release-cli

Conversation

@raghubetina

@raghubetina raghubetina commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Summary

The CLI side of the release that invites October's testers back. They work on their own, so old setups have to say
they are old, the product's own messages have to carry recovery, and First Draft asks before it learns anything
from their agents.

  • Client facts. Every request, /v1 and OAuth, carries
    FirstDraft-Client: cli/<version>; plugin/<version>; agent/<name>; os/<platform>. plugin and agent come from
    FIRSTDRAFT_PLUGIN_VERSION and FIRSTDRAFT_AGENT, which the plugin's launcher is to set; unknown or unsafe parts
    are left out. Login no longer sends the computer's hostname.
  • Old setups say they are old. Every response is checked for FirstDraft-Latest-Plugin,
    FirstDraft-Minimum-Plugin, FirstDraft-Latest-CLI, FirstDraft-Minimum-CLI, and FirstDraft-API-Contract. A
    plugin is compared with the plugin pair and a bare CLI with the CLI pair; an older one gets one First Draft: line
    on stderr per command, with or without a terminal. Below the minimum or
    outside API >= 0.9.0, < 0.10.0, the CLI finishes handling that response (an accepted push still saves its
    ETag) and sends nothing more; when that cut the command short it reports update_required or
    api_contract_unsupported, naming a Compilation that had already started, and otherwise the command keeps its
    result after one line naming the update. A 429 from a daily cap reports rate_limited with retry_at.
  • Profile. plan init writes, and artifact validation accepts only, the working profile
    rails-sketch/2026-11, named once in RAILS_TARGET_PROFILE.
  • New commands. account prints whether reports are on. report progress and report failure print the exact
    JSON they send, then send it once to the Project's pinned origin, and print Sent. only on First Draft's 201
    acknowledgment; reports_off is a message with exit 0. Routes and fields follow the Service's report endpoints,
    and the commands find the Project from an adopted application root. Failure report fields are shaped, not
    redacted: an RSpec rerun, a Ruby constant, app frames with a line number, version numbers, and the plain words of
    free text; what does not fit is left out and named in the preview. conversation send <file> --person-agreed
    refuses without the flag, prints the file's path, size, and SHA-256, and uploads the bytes unchanged. The Service
    does not accept conversations yet, and the docs say so.
  • Recovery. After request_outcome_unknown from a push or a direct Compile, the handled details and
    docs/errors.md say to rerun once with the same options, with the 412 and compilation_active branches,
    instead of stopping.
  • The README's promise now says what each command sends and that the update line comes from First Draft's answer.

No version bump: the version pull request sets it with its changelog entry.

Docs: updated README.md (package promise), docs/commands.md (What the CLI sends, account, reports, conversation,
Service endpoints, profile, API range, add-a-command), and docs/errors.md (update and limit errors, report and
conversation errors, ambiguous-mutation recovery, error index).

Review: Codex, needs attention after 5 rounds of a fresh session over the whole branch (2 rejected and 1 deferred by decision, 2 new findings open), following an earlier 4-round session (30 fixed, 7 after its last round, 3 declined); Antigravity, 2 completed rounds (6 findings fixed), then stopped after two failed runs

Validation

  • npm audit: 0 vulnerabilities
  • npm run check: passes (326 tests, package allowlist, packed smoke); the same suite passes on Node 22.0.0

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.
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.
@raghubetina
raghubetina force-pushed the invite/release-cli branch 2 times, most recently from 467776b to 58e0e9c Compare November 20, 2026 22:49
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.
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.
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.
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.
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.
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.
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.
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.
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.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant