recess-cli 1.9.2 → 2.1.0

package/README.md

@@ -1,6 +1,13 @@
 # Recess CLI
 
-`recess-cli` is the typed, agent-friendly command layer for Recess operations. ADMIN accounts receive the full staff surface; GUARDIAN accounts with `access:ai` receive family-scoped class schedules, progress, goals, todos, memories, Rocky configuration, learning research, GoalTemplate, and goal-content commands; GUIDE accounts receive that same student surface for the students they hold an ACTIVE tutor assignment to — not their wider class roster. It uses the web-server OpenAPI document, authenticates through Recess SSO, emits stable JSON, and refuses live writes until the exact command is rerun with `--confirm` after human approval.
+`recess-cli` is the typed, agent-friendly command layer for Recess operations. ADMIN accounts
+receive the full staff surface; GUARDIAN accounts with `access:ai` receive family-scoped class
+schedules, progress, goals, todos, memories, Rocky configuration, learning research, GoalTemplate,
+and goal-content commands; GUIDE accounts receive that same student surface for the students they
+hold an ACTIVE tutor assignment to—not their wider class roster. KID accounts receive only
+authenticated Village home building. It uses the web-server OpenAPI document, authenticates
+through Recess SSO, emits stable JSON, and refuses live writes until the exact command is rerun with
+`--confirm` plus the preview's operation key after human approval.
 
 ## Install (no checkout needed)
 
@@ -8,7 +15,7 @@ Published to npm as [`recess-cli`](https://www.npmjs.com/package/recess-cli). On
 
 ```bash
 npm install -g recess-cli
-recess setup
+recess setup --reason "Install and update the Recess agent skill"
 ```
 
 `setup` installs the bundled skill in the Codex and Claude Code user directories, which Cursor also discovers for compatibility, and then opens Recess SSO in your browser (skip the browser step with `--skill-only`; it is also skipped when a live session already exists). Restart your agent afterwards so it discovers the skill. `npx -y recess-cli setup` works too, but leaves no `recess` on your PATH — which is the command the installed skill tells the agent to run — so `setup` warns when it detects it is running from an npx cache.
@@ -40,11 +47,11 @@ Create an approved `OAuthClient` row in each Recess environment. This remains a
 
 The production row ID (`c7e34138-18f9-45b1-a2fb-26a4e3a6d739`) is the CLI's built-in default, so production login needs no client-ID setup. `--client-id`, `RECESS_CLI_OAUTH_CLIENT_ID`, and a stored client ID remain overrides for local/staging clients. The web-server decodes the assertion audience, loads that exact `OAuthClient`, and requires both `approved` and `adminCliEnabled`; there is no separate server environment allowlist. Production redirect validation is exact, so a different callback port must also be explicitly registered.
 
-The browser SSO assertion is exchanged once and discarded. The CLI stores a separate 12-hour signed Recess session at `~/.recess-cli/config.json` with mode `0600`. A guardian must hold the live `access:ai` permission; removing it immediately invalidates session checks. Guardian sessions cannot call `/admin` routes and every target is independently restricted to their family.
+The browser SSO assertion is exchanged once and discarded. The CLI stores a separate 12-hour signed Recess session at `~/.recess-cli/config.json` with mode `0600`. A guardian must hold the live `access:ai` permission; removing it immediately invalidates session checks. Guardian sessions cannot call `/admin` routes and every target is independently restricted to their family. A KID session has `village_home` scope: application-level and shared-auth fences permit only session inspection and Village assertion minting, denying every other backend route.
 
 ```bash
 recess --json auth login
-recess --json doctor
+recess --json doctor --reason "Verify CLI connectivity, identity, and scope"
 ```
 
 ## Testing against a local server
@@ -54,7 +61,7 @@ recess --json doctor
 ```bash
 export RECESS_CLI_API_ORIGIN=http://localhost:5068
 export RECESS_CLI_COOKIE='recess.auth-token=<signed-value>'
-recess --json doctor
+recess --json doctor --reason "Verify the local Recess API connection"
 ```
 
 To mint `<signed-value>`: sign `{sub, role, cliScope}` with the server's `JWT_SECRET` (audience = `CLIENT_ORIGIN`), then sign THAT string with `cookie.signerFactory(COOKIE_SECRET)` from `@fastify/cookie`. Two traps, both silent:
@@ -97,32 +104,42 @@ Error or write preview:
   "error": {
     "code": "confirmation_required",
     "message": "...",
-    "details": { "preview": {}, "requiredFlag": "--confirm" }
+    "details": { "preview": { "details": { "operationKey": "..." } } }
   }
 }
 ```
 
 Exit code `0` means success, `1` means an input/auth/API failure, and `2` means a write is awaiting explicit human confirmation.
 
+`recess --json agent-context` returns the canonical command/flag/positional schema. `recess --json help payout recipients` returns scoped help. Unknown flags, duplicate non-repeatable flags, missing values, and extra positionals are errors instead of being silently ignored.
+
+Every command-driven request to the Recess API except `auth` requires `--reason "..."`: a
+non-empty, human-readable purpose of at most 1024 characters. The CLI sends it as
+`x-recess-reason`; the server rejects missing reasons before route execution and stores one audit
+row per request. The human-only `recess ui` console is explicitly exempt and identifies itself as
+`x-recess-client: cli-ui` instead.
+
 ## Common flow
 
 ```bash
-recess --json users search "Morgan Rivera"
-recess --json users tier get <kid-id>
-recess --json users tier preview <kid-id> --tier lite --slots 1
-recess --json students upload-map-scores --student <kid-id> --file /path/to/map-report.pdf
-recess --json enrollments list --user <kid-id>
-recess --json subscriptions list --family <family-id> --kid <kid-id>
-recess --json invoices list --subscription <subscription-id>
+recess --json users search "Morgan Rivera" --reason "Find the exact student record"
+recess --json users tier get <kid-id> --reason "Inspect the student's current tier"
+recess --json users tier preview <kid-id> --tier lite --slots 1 --reason "Preview a tier change"
+recess --json students upload-map-scores --student <kid-id> --file /path/to/map-report.pdf --reason "Import this student's MAP scores"
+recess --json enrollments list --user <kid-id> --reason "Inspect the student's enrollments"
+recess --json subscriptions list --family <family-id> --kid <kid-id> --reason "Inspect family subscriptions"
+recess --json invoices list --subscription <subscription-id> --reason "Inspect subscription invoices"
 ```
 
 Preview a write by omitting `--confirm`:
 
 ```bash
-recess --json billing pause --subscription <subscription-id> --until 2026-09-01
+recess --json billing pause --subscription <subscription-id> --until 2026-09-01 --reason "Pause billing through September 1"
 ```
 
-After a human approves that exact preview, rerun the unchanged command with `--confirm`. File-backed family edits, deterministic template apply, and goal-content writes also return `details.approvalToken`; echo it with `--approval-token TOKEN`. The token covers the local bytes plus the server preflight/CAS state, so a changed file or goal produces a new preview instead of consuming stale approval.
+After a human approves that exact preview, rerun the unchanged command with `--confirm --operation-key <operationKey>`. File-backed family edits, deterministic template apply, and goal-content writes also return `details.approvalToken`; echo it with `--approval-token TOKEN`. The token covers the local bytes plus the server preflight/CAS state, so a changed file or goal produces a new preview instead of consuming stale approval. Confirmed requests are fenced server-side per actor, operation, route/body, and preview fingerprint; retry an interrupted command with the same operation key to replay a completed response rather than duplicate the write. `jobs list|get` reads the protected local recovery ledger.
+
+Named `profile save|use|list` configurations keep environment selection explicit, with global `--profile` as a one-command override. `--deliver file:<path>` atomically writes the JSON envelope with mode 0600; webhook delivery is intentionally unavailable for authenticated Recess data. `feedback submit` stores deduplicated CLI friction locally and can forward it to `RECESS_CLI_FEEDBACK_ENDPOINT`.
 
 School tier writes require the `updatedAt` token from `users tier get`. Their read-only preflight
 shows `capabilitiesLockedNow`/`capabilitiesLockedAfter`, the resolved class allowance, current
@@ -137,34 +154,49 @@ Village store goods are main-Recess `StoreItem` rows, not Village-island databas
 and preview an availability change with:
 
 ```bash
-recess --json store-items list --item-type VILLAGE_ITEM
-recess --json store-items set-status <store-item-id> --status INACTIVE
+recess --json store-items list --item-type VILLAGE_ITEM --reason "Inspect the Village item catalog"
+recess --json store-items set-status <store-item-id> --status INACTIVE --reason "Deactivate this Village item"
 ```
 
 The status command resolves the exact `VILLAGE_ITEM` first and includes its name, catalog metadata,
 current status, purchase count, and lack of feed-publication side effects in the approval preview;
-it refuses non-Village item IDs. After approval, rerun the unchanged command with `--confirm`. The
+it refuses non-Village item IDs. After approval, rerun the unchanged command with `--confirm` and
+the preview's `--operation-key`. The
 separate `village models` commands edit the Village island's reusable models and placements.
+`village build cmd` sends one confirmed command through Village's ordinary authenticated command
+dispatcher. `village library search|get`, `village objects list|get`, and `village render` use the
+same scoped Village identity and are own-home-only outside ADMIN. `village worlds
+export|import|promote` moves or promotes data-built worlds through the fixed admin bridge.
 
 ## Authoring learning content
 
 ```bash
-recess --json skills guardian get recess-goal-authoring --all-references
-recess --json content-library search "fractions through visual puzzles" --limit 8
-recess --json content-library status <gem-id-or-url>
-recess --json content-library set-stage <gem-id-or-url...> --stage archived
-recess --json goal-templates validate-spec --file ./template.json   # iterate; writes nothing
-recess --json goal-templates create --file ./template.json          # preview, exit 2
-recess --json goal-templates create --file ./template.json --confirm
-recess --json goal-templates patch-spec <id-or-slug> --expected-version 7 --patches-file ./patches.json
-recess --json goals files write --student <kid-id> --draft <draft-slug> --source-dir ./goal-content
-recess --json goals pdf upload --student <kid-id> --draft <draft-slug> --source-file ./textbook.pdf
-recess --json goal-templates capture-snapshot <id-or-slug> --source-draft <draft-slug> --student <kid-id> --dry-run
-recess --json goal-templates apply <id-or-slug> --answers-file ./answers.json --dry-run
-recess --json goals create --student <kid-id> --title "..." --description-file ./goal.md
-recess --json goals create --student <kid-id> --draft <draft-slug> --title "..." \
-  --description-file ./goal.md --enable-applet-follow-ups
-recess --json goals files list --student <kid-id> --goal <goal-id>
+recess --json skills guardian get recess-goal-authoring --all-references --reason "Load goal authoring guidance"
+recess --json content-library search "fractions through visual puzzles" --limit 8 --reason "Find visual fraction resources"
+recess --json content-library status <gem-id-or-url> --reason "Inspect this gem's pipeline status"
+recess --json content-library set-stage <gem-id-or-url...> --stage archived --reason "Archive these gems"
+recess --json goal-templates validate-spec --file ./template.json --reason "Validate this template draft"
+recess --json goal-templates create --file ./template.json --reason "Create this reusable goal template"
+recess --json goal-templates create --file ./template.json --confirm \
+  --operation-key <preview-operation-key> --reason "Create this reusable goal template"
+recess --json goal-templates patch-spec <id-or-slug> --expected-version 7 --patches-file ./patches.json --reason "Update this template specification"
+recess --json goals files init --student <kid-id> --draft <draft-slug> \
+  --output-dir ./goal-content --reason "Start this goal draft"
+git -C ./goal-content add -A
+git -C ./goal-content commit -m "Author the learning path"
+recess --json goals files push --source-dir ./goal-content --reason "Publish this goal draft"
+recess --json goals pdf upload --student <kid-id> --draft <draft-slug> --source-file ./textbook.pdf --reason "Attach this textbook to the goal draft"
+recess --json goal-templates capture-snapshot <id-or-slug> --source-dir ./goal-content --dry-run --reason "Preview a template snapshot"
+recess --json goal-templates apply <id-or-slug> --answers-file ./answers.json --dry-run --reason "Preview applying this template"
+recess --json goals create --student <kid-id> --title "..." --description-file ./goal.md --reason "Create this student goal"
+recess --json goals create --source-dir ./goal-content --title "..." \
+  --description-file ./goal.md --enable-applet-follow-ups --reason "Create this student goal draft"
+recess --json goals files list --student <kid-id> --goal <goal-id> --reason "Inspect the goal workspace files"
+recess --json goals files checkout --student <kid-id> --goal <goal-id> \
+  --output-dir ./goal-content --reason "Check out this goal for editing"
+git -C ./goal-content add -A
+git -C ./goal-content commit -m "Revise module 3"
+recess --json goals files push --source-dir ./goal-content --reason "Publish the module revision"
 ```
 
 ADMIN discovery batches use the same Content Library admission door as the dashboard. Omit
@@ -173,9 +205,10 @@ Review preselected; JSON/non-interactive runs safely default to Review. Use `--s
 start automatic decoration immediately:
 
 ```bash
-recess --json content-library submit https://example.org/activity --stage review
-recess --json content-library submit --file ./gems.json
-recess --json content-library submit --file ./urls.txt --stage polish --confirm
+recess --json content-library submit https://example.org/activity --stage review --reason "Submit this activity for review"
+recess --json content-library submit --file ./gems.json --reason "Submit this resource batch for review"
+recess --json content-library submit --file ./urls.txt --stage polish --confirm \
+  --operation-key <preview-operation-key> --reason "Submit this batch for polishing"
 ```
 
 JSON files are arrays of URL strings or `{ "url", "title"?, "summary"?, "lane"? }` objects;
@@ -186,21 +219,24 @@ reports its Review/Polishing/Live/Archived stage plus metadata, cover, and searc
 `content-library set-stage` accepts one or many IDs/URLs (or a newline/JSON-string-array `--file`),
 previews every resolved current stage, and requires `--confirm`. It uses the same lifecycle as
 Manage: direct-to-Live routes unfinished gems through Polishing, and moving out of Polishing
-cancels that exact run first.
+cancels that exact run first. Add `--wait --timeout 900` when promoting to Live (or submitting to
+polish) to poll the durable island status with bounded concurrency and exponential backoff.
 
 ## Family AI operations
 
 ```bash
-recess --json students list
-recess --json students today --student <kid-id>
-recess --json students schedule --student <kid-id> --days 30
-recess --json students xp-history --student <kid-id> --range month
-recess --json goals list --student <kid-id>
-recess --json todos create --student <kid-id> --title "Read chapter 4"
-recess --json todos generate-applet <todo-id> --student <kid-id> [--due-date YYYY-MM-DD]
-recess --json memories context --student <kid-id>
-recess --json memories log --student <kid-id> --date 2026-08-12
-recess --json rocky get --student <kid-id>
+recess --json students list --reason "List the students I can support"
+recess --json students today --student <kid-id> --reason "Review today's learning plan"
+recess --json students schedule --student <kid-id> --days 30 --reason "Review the student's upcoming schedule"
+recess --json students xp-history --student <kid-id> --range month --reason "Review recent XP history"
+recess --json goals list --student <kid-id> --reason "Review the student's goals"
+recess --json todos create --student <kid-id> --title "Read chapter 4" --reason "Add the assigned reading"
+recess --json goals delete <goal-id> --student <kid-id> --reason "Remove this obsolete goal"
+recess --json todos delete <todo-id> --reason "Remove this disposable todo"
+recess --json todos generate-applet <todo-id> --student <kid-id> --reason "Generate this todo's applet"
+recess --json memories context --student <kid-id> --reason "Review durable tutor context"
+recess --json memories log --student <kid-id> --date 2026-08-12 --reason "Review the learning log for this date"
+recess --json rocky get --student <kid-id> --reason "Inspect the student's Rocky configuration"
 ```
 
 All family writes still preview first. Goal/todo/Rocky edits also carry the current server version
@@ -216,8 +252,8 @@ not expose Postgres `UserMemory`.
 
 ```bash
 recess --json --version          # {cliVersion, skillVersion}
-recess --json doctor             # .skill reports whether a newer bundle exists
-recess --json setup --skill-only # bundled copy, then the served upgrade
+recess --json doctor --reason "Check CLI health" # .skill reports whether a newer bundle exists
+recess --json setup --skill-only --reason "Update the installed Recess skill"
 ```
 
 The CLI's small shared router skill is **both** bundled in this package and served from
@@ -243,11 +279,13 @@ previews the per-student outcome. `set-metadata` and `delete` require `--expecte
 it always runs the backend's guarded preview first and requires the preview's exact loss token in
 addition to `--confirm` when protected template data would be removed.
 
-Module-backed content is authored as a local workspace tree and batch-upserted to a named goal
-draft. For a personal one-off goal, `goals create --draft` validates and materializes that draft
-directly. For reusable content, attach it to a BLUEPRINT with `capture-snapshot`. Every mutation
-runs a server preview before the confirmation gate and is compare-and-set against the previewed
-revision. Direct live-goal `modules/` and `state/` writes remain blocked because those files have
-database projections.
+Module-backed content starts with `goals files init --draft`, which creates a normal local Git
+repository pinned to the student's Mesa revision. Edit, rename, delete, inspect, and commit with
+ordinary Git, then use `goals files push`. The same checkout can become a personal goal through
+`goals create --source-dir` or a reusable BLUEPRINT snapshot through
+`goal-templates capture-snapshot --source-dir`; successful goal creation retargets its metadata to
+the new live goal for continued pushes. Existing live goals use `checkout --goal`. Every push
+previews the committed range as one Mesa change and refuses a stale remote tip. The direct
+`goals files write` upsert remains available for small or automated writes.
 
 See `recess --help` for the complete command surface. The raw escape hatch is intentionally read-only: `recess --json request get /path`.

package/dist/api.js

@@ -1,16 +1,43 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import createClient from "openapi-fetch";
 import { apiError, CliError } from "./errors.js";
+import { cliRequestHeaders, markCliRequest, RECESS_CLIENT_CLI, } from "./http.js";
+const idempotencyContext = new AsyncLocalStorage();
+export function withIdempotencyContext(context, execute) {
+    return idempotencyContext.run(context, execute);
+}
+function applyIdempotencyHeaders(headers) {
+    const context = idempotencyContext.getStore();
+    if (!context)
+        return;
+    headers.set("x-recess-operation-key", context.operationKey);
+    headers.set("x-recess-operation-fingerprint", context.fingerprint);
+}
 export class RecessAdminApi {
     config;
+    reason;
+    clientTag;
     client;
-    constructor(config) {
+    villageSessionPromise;
+    constructor(config, reason, clientTag = RECESS_CLIENT_CLI) {
         this.config = config;
+        this.reason = reason;
+        this.clientTag = clientTag;
         this.client = createClient({
             baseUrl: config.apiOrigin,
             headers: config.sessionCookie
                 ? { cookie: config.sessionCookie }
                 : undefined,
         });
+        const requestReason = this.reason;
+        const requestClientTag = this.clientTag;
+        this.client.use({
+            onRequest({ request }) {
+                markCliRequest(request.headers, requestReason, requestClientTag);
+                applyIdempotencyHeaders(request.headers);
+                return request;
+            },
+        });
     }
     requireAuth() {
         if (!this.config.sessionCookie) {
@@ -23,7 +50,7 @@ export class RecessAdminApi {
             throw new CliError("invalid_arguments", "Raw request paths must start with one '/'.");
         }
         const response = await fetch(new URL(path, this.config.apiOrigin), {
-            headers: { cookie: this.config.sessionCookie },
+            headers: cliRequestHeaders({ cookie: this.config.sessionCookie }, this.reason, this.clientTag),
         });
         const text = await response.text();
         let body = text;
@@ -39,14 +66,16 @@ export class RecessAdminApi {
     }
     async villageRequest(path, options = {}) {
         this.requireAuth();
+        const headers = cliRequestHeaders({
+            cookie: this.config.sessionCookie,
+            ...(options.body === undefined
+                ? {}
+                : { "content-type": "application/json" }),
+        }, this.reason, this.clientTag);
+        applyIdempotencyHeaders(headers);
         const response = await fetch(new URL(path, this.config.apiOrigin), {
             method: options.method ?? "GET",
-            headers: {
-                cookie: this.config.sessionCookie,
-                ...(options.body === undefined
-                    ? {}
-                    : { "content-type": "application/json" }),
-            },
+            headers,
             ...(options.body === undefined
                 ? {}
                 : { body: JSON.stringify(options.body) }),
@@ -63,6 +92,28 @@ export class RecessAdminApi {
             throw apiError(response.status, body);
         return body;
     }
+    async villageCommand(worldId, command) {
+        const result = await this.villageScopedRequest("/api/cli/command", {
+            method: "POST",
+            body: { worldId, command },
+        });
+        if (result &&
+            typeof result === "object" &&
+            "ok" in result &&
+            result.ok === false) {
+            const reason = "reason" in result && typeof result.reason === "string"
+                ? result.reason
+                : "Village rejected the command.";
+            throw new CliError("village_command_rejected", reason, 1, result);
+        }
+        return result;
+    }
+    async villageRead(path) {
+        if (!path.startsWith("/api/cli/") || path.startsWith("//")) {
+            throw new CliError("invalid_arguments", "Village read paths must stay under /api/cli/.");
+        }
+        return this.villageScopedRequest(path);
+    }
     async uploadVillageModel(worldId, file, fileName, metadata) {
         this.requireAuth();
         const form = new FormData();
@@ -72,9 +123,11 @@ export class RecessAdminApi {
         }
         const arrayBuffer = file.buffer.slice(file.byteOffset, file.byteOffset + file.byteLength);
         form.set("file", new Blob([arrayBuffer], { type: "model/gltf-binary" }), fileName);
+        const headers = cliRequestHeaders({ cookie: this.config.sessionCookie }, this.reason, this.clientTag);
+        applyIdempotencyHeaders(headers);
         const response = await fetch(new URL(`/admin/village/models/upload?worldId=${encodeURIComponent(worldId)}`, this.config.apiOrigin), {
             method: "POST",
-            headers: { cookie: this.config.sessionCookie },
+            headers,
             body: form,
         });
         const text = await response.text();
@@ -93,9 +146,11 @@ export class RecessAdminApi {
         this.requireAuth();
         const formData = new FormData();
         formData.append("file", new Blob([pdf], { type: "application/pdf" }), fileName);
+        const headers = cliRequestHeaders({ cookie: this.config.sessionCookie }, this.reason, this.clientTag);
+        applyIdempotencyHeaders(headers);
         const response = await fetch(new URL(`/tutor/students/${encodeURIComponent(studentId)}/map-test-scores/upload`, this.config.apiOrigin), {
             method: "POST",
-            headers: { cookie: this.config.sessionCookie },
+            headers,
             body: formData,
         });
         const text = await response.text();
@@ -110,6 +165,63 @@ export class RecessAdminApi {
             throw apiError(response.status, body);
         return body;
     }
+    villageSession() {
+        this.requireAuth();
+        this.villageSessionPromise ??= (async () => {
+            const assertionResult = await this.client.POST("/auth/admin-cli/village-assertion/");
+            const signed = unwrap(assertionResult);
+            const exchangeResponse = await fetch(new URL("/api/auth/cli/exchange", signed.villageOrigin), {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ assertion: signed.assertion }),
+            });
+            const exchangeBody = await readResponseBody(exchangeResponse);
+            if (!exchangeResponse.ok) {
+                throw apiError(exchangeResponse.status, exchangeBody);
+            }
+            const token = exchangeBody &&
+                typeof exchangeBody === "object" &&
+                "token" in exchangeBody &&
+                typeof exchangeBody.token === "string"
+                ? exchangeBody.token
+                : null;
+            if (!token) {
+                throw new CliError("invalid_response", "Village assertion exchange returned no scoped token.");
+            }
+            return { villageOrigin: signed.villageOrigin, token };
+        })();
+        return this.villageSessionPromise;
+    }
+    async villageScopedRequest(path, options = {}) {
+        const { villageOrigin, token } = await this.villageSession();
+        const response = await fetch(new URL(path, villageOrigin), {
+            method: options.method ?? "GET",
+            headers: {
+                authorization: `Bearer ${token}`,
+                ...(options.body === undefined
+                    ? {}
+                    : { "content-type": "application/json" }),
+            },
+            ...(options.body === undefined
+                ? {}
+                : { body: JSON.stringify(options.body) }),
+        });
+        const body = await readResponseBody(response);
+        if (!response.ok)
+            throw apiError(response.status, body);
+        return body;
+    }
+}
+async function readResponseBody(response) {
+    const text = await response.text();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
 }
 export function unwrap(result) {
     if (!result.response.ok || result.data === undefined) {

package/dist/args.js

@@ -10,6 +10,7 @@ const BOOLEAN_FLAGS = new Set([
     "allow-strand",
     "cancel-subscriptions",
     "archived",
+    "confirm-destructive-changes",
     "confirm",
     "dry-run",
     "disable-applet-follow-ups",
@@ -19,20 +20,28 @@ const BOOLEAN_FLAGS = new Set([
     "immediate",
     "include-deleted",
     "mirrored",
+    "no-invite",
     "no-collision",
     "json",
     "refresh",
     "restore",
     "revoke",
     "send-email",
+    "skill-only",
     "spec-only",
     "starter-only",
     "visual-only",
+    "version",
+    "wait",
 ]);
 export function parseArgs(args) {
     const positionals = [];
     const flags = new Map();
     const repeated = new Map();
+    const occurrences = new Map();
+    const markSeen = (name) => {
+        occurrences.set(name, (occurrences.get(name) ?? 0) + 1);
+    };
     const record = (name, value) => {
         if (!REPEATABLE_FLAGS.has(name))
             return;
@@ -52,11 +61,13 @@ export function parseArgs(args) {
         if (equalsAt > 2) {
             const name = value.slice(2, equalsAt);
             const flagValue = value.slice(equalsAt + 1);
+            markSeen(name);
             flags.set(name, flagValue);
             record(name, flagValue);
             continue;
         }
         const name = value.slice(2);
+        markSeen(name);
         if (BOOLEAN_FLAGS.has(name)) {
             flags.set(name, true);
             continue;
@@ -71,7 +82,7 @@ export function parseArgs(args) {
             flags.set(name, true);
         }
     }
-    return { positionals, flags, repeated };
+    return { positionals, flags, repeated, occurrences };
 }
 /**
  * Every value given for a repeatable flag, in order.

package/dist/auth.js

@@ -3,6 +3,7 @@ import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
 import { clearPendingDeviceAuth, updateStoredConfig } from "./config.js";
 import { apiError, CliError } from "./errors.js";
+import { cliRequestHeaders } from "./http.js";
 function openBrowser(url) {
     // Windows goes through rundll32, not `cmd /c start`: cmd treats `&` (and the
     // `%`-encoded redirect_uri) as metacharacters and chops the URL at the first
@@ -76,7 +77,7 @@ export async function login(config, options) {
     const assertion = await callback;
     const response = await fetch(new URL("/auth/admin-cli/exchange/", config.apiOrigin), {
         method: "POST",
-        headers: { authorization: `Bearer ${assertion}` },
+        headers: cliRequestHeaders({ authorization: `Bearer ${assertion}` }),
     });
     const body = (await response.json());
     if (!response.ok)
@@ -93,7 +94,7 @@ export async function login(config, options) {
         sessionCookie: pair,
         sessionExpiresAt: exchange.expiresAt,
         user: exchange.user,
-    });
+    }, config.profileName);
     return exchange;
 }
 // Start the headless (device-authorization) sign-in. Non-blocking: it stores the secret
@@ -102,7 +103,7 @@ export async function login(config, options) {
 export async function requestDeviceAuth(config, options) {
     const response = await fetch(new URL("/auth/admin-cli/device/authorize/", config.apiOrigin), {
         method: "POST",
-        headers: { "content-type": "application/json" },
+        headers: cliRequestHeaders({ "content-type": "application/json" }),
         body: JSON.stringify(options.label ? { label: options.label } : {}),
     });
     const body = (await response.json());
@@ -116,7 +117,7 @@ export async function requestDeviceAuth(config, options) {
         pendingUserCode: authorize.userCode,
         pendingApprovalUrl: authorize.approvalUrl,
         pendingExpiresAt: authorize.expiresAt,
-    });
+    }, config.profileName);
     return {
         approvalUrl: authorize.approvalUrl,
         userCode: authorize.userCode,
@@ -142,12 +143,12 @@ export async function pollDeviceAuth(config, options) {
     for (;;) {
         const response = await fetch(new URL("/auth/admin-cli/device/token/", config.apiOrigin), {
             method: "POST",
-            headers: { "content-type": "application/json" },
+            headers: cliRequestHeaders({ "content-type": "application/json" }),
             body: JSON.stringify({ deviceCode }),
         });
         const body = (await response.json());
         if (!response.ok) {
-            await clearPendingDeviceAuth();
+            await clearPendingDeviceAuth(config.profileName);
             throw apiError(response.status, body);
         }
         const token = body;
@@ -167,16 +168,16 @@ export async function pollDeviceAuth(config, options) {
                 sessionCookie: pair,
                 sessionExpiresAt: exchange.expiresAt,
                 user: exchange.user,
-            });
-            await clearPendingDeviceAuth();
+            }, config.profileName);
+            await clearPendingDeviceAuth(config.profileName);
             return exchange;
         }
         if (token.status === "denied") {
-            await clearPendingDeviceAuth();
+            await clearPendingDeviceAuth(config.profileName);
             throw new CliError("auth_failed", "The sign-in request was denied.");
         }
         if (token.status === "expired" || token.status === "consumed") {
-            await clearPendingDeviceAuth();
+            await clearPendingDeviceAuth(config.profileName);
             throw new CliError("auth_failed", token.status === "expired"
                 ? "The sign-in request expired. Run `recess auth request` again."
                 : "The sign-in request was already used. Run `recess auth request` again.");