@brass-build/cli 0.1.0 → 0.3.0

package/AGENTS.md

@@ -10,10 +10,8 @@ this file is the short path for you.
 Before you start building, fetch the organization's own agentic-coding
 instructions and follow them: the conventions it wants every app built on
 Brass to follow (its `AGENTS.md` / `CLAUDE.md`). Run the pull rather than
-deciding up front whether the org has any; nothing loads them for you, and an
-empty result (the org set none) is something you learn by running it, not by
-assuming it. Treat what it returns as an instruction file committed to the
-repo.
+deciding up front whether the org has any, because nothing loads them for
+you. Treat what it returns as an instruction file committed to the repo.
 
 ```sh
 npx @brass-build/cli agents pull --out AGENTS.md
@@ -30,18 +28,17 @@ Keep it current one of two ways:
 - **Cache:** commit the pulled file and refresh it periodically. Add a
   `CLAUDE.md` whose entire contents are the single line `@AGENTS.md` so
   Claude Code picks it up too (Claude Code auto-loads `CLAUDE.md`, not
-  `AGENTS.md`); the command prints this reminder after a pull.
-
-The pull needs a signed-in session (`brass login`); a service token is not an
-organization member and cannot read the instructions. If you are not signed
-in, run the sign-in yourself rather than skipping: `brass login --start`,
-relay the printed URL and code to the human, then `brass login --check --wait`
-until it reports approved (it is the same credential you will use to publish).
-[Signing in](#signing-in) covers the whole flow, including what to do while
-you wait for the approval.
-`--org <organizationId>` is only needed when the human belongs to more than
-one organization. An empty result means the organization has set no
-instructions, and there is nothing to follow.
+  `AGENTS.md`). The command prints this reminder after a pull.
+
+The pull needs a signed-in session (`brass login`), since a service token is
+not an organization member and cannot read the instructions. If you are not
+signed in, run the sign-in yourself rather than skipping: `brass login
+--start`, relay the printed URL and code to the human, then `brass login
+--check --wait` until it reports approved (it is the same credential you will
+use to publish). [Signing in](#signing-in) covers the whole flow, including
+what to do while you wait for the approval. Pass `--org <organizationId>`
+when the human belongs to more than one organization. An empty result means
+the organization has set no instructions.
 
 ## Signing in
 
@@ -62,10 +59,10 @@ good at publish time.
 
 The session gates your organization's coding conventions, and those shape the
 code you are about to write, so wait for it before you build rather than
-building twice. If you do have work that does not depend on them, the wait
-costs nothing to repeat: a bound reached with the code still approvable
-reports `pending`, and the next `--check --wait` picks the same sign-in back
-up where it left off.
+building twice. Do work that does not depend on them in the meantime and
+repeat the wait: a bound reached with the code still approvable reports
+`pending`, and the next `--check --wait` picks the same sign-in back up where
+it left off.
 
 Read the `state` in its `--json` result:
 
@@ -73,6 +70,11 @@ Read the `state` in its `--json` result:
 - `pending`: the code you relayed is still good. Run the check again.
 - `renewed`: the code changed. Relay the new one from the same output.
 - `denied`: the human refused. Ask them why before starting another.
+- `none`: nothing is in flight. Run `brass login --start` first.
+
+`brass login --start` reports `started` with the code to relay, and
+`--start --wait` reports the state it reached instead, so either form leaves
+one `--json` document to read.
 
 Run `brass login --start` again only when there is nothing in flight; it
 resumes the sign-in already waiting rather than issuing a second code, so a
@@ -107,7 +109,7 @@ again. The steps below are what it walks you through:
    npx @brass-build/cli publish ./dist
    ```
 
-   The first run creates the app and writes `.brass/project.json`; commit
+   The first run creates the app and writes `.brass/project.json`. Commit
    that so re-runs target the same app. A service token creates the app in
    its own organization, so no `--org` is needed. If the pipeline does not
    persist `.brass/project.json` between runs, set a stable `client_token`
@@ -115,8 +117,8 @@ again. The steps below are what it walks you through:
    first create is idempotent and re-runs resolve the same app.
 
 Run with `--json` to get the result (`app_id`, `url`) as JSON on stdout for
-your own parsing. A non-zero exit means the publish failed; the reason is on
-stderr.
+your own parsing. A non-zero exit means the publish failed, and the reason is
+on stderr.
 
 ## Pulling a schema to build against
 
@@ -128,11 +130,12 @@ npx @brass-build/cli schema pull --doc <docId> --out brass-app.json
 ```
 
 This writes the schema verbatim into your manifest. Build your types against
-that copy; do not re-approximate it from memory (a mismatched `required`
-shape makes the platform read your app as a different shape). This is a
-development-time step that needs a signed-in session (`brass login`), not a
-service token; if you only have `BRASS_SERVICE_TOKEN`, ask the human to run
-`brass login` or to copy the schema from the document's dashboard page.
+that copy rather than re-approximating it from memory, since a mismatched
+`required` shape makes the platform read your app as a different shape. This
+is a development-time step that needs a signed-in session (`brass login`),
+not a service token. When you only have `BRASS_SERVICE_TOKEN`, ask the human
+to run `brass login` or to copy the schema from the document's dashboard
+page.
 
 ## Verifying
 
@@ -149,10 +152,10 @@ are on. The CLI reports the state it observed, and the states have different
 fixes:
 
 - **A 401 or 403** means the credential is expired, missing, or not allowed.
-  A session expires, so `brass login` is the fix; a service token that is
-  rejected needs a valid `BRASS_SERVICE_TOKEN`. A fresh checkout or a fresh
-  container has no session at all, which is the ordinary starting state, not
-  a broken one.
+  Run `brass login` to replace an expired session, or set a valid
+  `BRASS_SERVICE_TOKEN` for a rejected service token. A fresh checkout or a
+  fresh container has no session at all, which is the ordinary starting
+  state, not a broken one.
 - **"Network error reaching <url>"** is the only error meaning the request
   never completed. It names the host it tried.
 - **Any other status** is a fault on the server side. The credential is

package/CHANGELOG.md

@@ -6,6 +6,38 @@ package follows [semantic versioning](https://semver.org/spec/v2.0.0.html).
 While the version is below `1.0.0`, minor releases may introduce breaking
 changes.
 
+## 0.3.0
+
+### Changed
+
+- `brass logout` keeps your credentials and exits non-zero when it cannot
+  reach Brass, rather than clearing them and reporting success: only the
+  stored record can name the session to end. Run it again once you have a
+  connection. `--json` reports `signed_out: false`.
+- `brass login --start --new` cancels the sign-in it replaces, so a code you
+  already handed to someone stops working.
+
+## 0.2.0
+
+### Added
+
+- `brass publish` waits for the platform to register the hosted slot before
+  reporting success, and fails when it never registers. The slot reaches the
+  serving edges shortly after that, so a URL the command reports can answer
+  404 for a few seconds before it serves.
+
+### Changed
+
+- `brass logout` ends the sign-in on the server as well as on this machine, so
+  a copy of the credentials file left elsewhere stops working. It also cancels
+  a started sign-in this machine has not redeemed yet, so a code relayed to a
+  human cannot be approved and spent afterwards. When Brass cannot be reached,
+  the local credential is still cleared and the command says which half did not
+  happen; `--json` carries this as `revoked`.
+- `brass publish --gate` states the load gate when it enables hosting, so a
+  publish that wants a world-loadable app no longer turns the gate on and
+  straight back off.
+
 ## 0.1.0
 
 Initial public release. The `brass` command-line tool publishes apps and

package/README.md

@@ -5,7 +5,7 @@ app's built bundle and pulls document schemas. It wraps the same data API the
 dashboard uses, authenticated by a token instead of a browser session, so
 the whole publish workflow runs unattended.
 
-This package tracks the platform's `0.1.x` line.
+This package tracks the platform's `0.2.x` line.
 
 ## Install
 
@@ -24,8 +24,8 @@ Two kinds of credential, for two audiences:
   under `~/.config/brass/`. It authorizes everything, including `schema pull`.
 - A **service token** (mint one in the dashboard: org Settings, then Service
   tokens) is the CI credential, supplied as `BRASS_SERVICE_TOKEN`. It
-  authorizes `publish` and `whoami`. It is an org-scoped machine identity
-  and, by design, cannot fetch schemas.
+  authorizes `publish` and `whoami`. It is an org-scoped machine identity,
+  so it cannot fetch schemas.
 
 ```sh
 npx @brass-build/cli login                  # developer: sign in with your browser
@@ -43,7 +43,7 @@ agent driving the sign-in), the flow splits in two: `brass login --start`
 prints the approval URL and code and exits immediately, and
 `brass login --check` checks that sign-in, storing the session once you have
 approved. Add `--wait` to poll until you approve, for two minutes by default
-or `--wait <seconds>` for a different bound; a code that lapses inside the
+or `--wait <seconds>` for a different bound. A code that lapses inside the
 wait is replaced and the new one printed, so a sign-in started long before it
 is needed still completes. Reaching the bound with the code still good is
 reported as `pending` and exits 0, so the next check picks the same sign-in
@@ -53,7 +53,9 @@ first. Both phases honor `--json` for a machine-readable result on stdout.
 
 The CLI picks a credential most-explicit first: `--token <token>`, then
 `BRASS_SERVICE_TOKEN`, then the stored `brass login` session. `brass logout`
-forgets the stored session.
+ends that session on the server and forgets it here. It keeps the stored
+session and exits non-zero when it cannot reach Brass, so a retry can still
+name the session to end.
 
 ```sh
 export BRASS_SERVICE_TOKEN=brass_sk_...
@@ -74,10 +76,10 @@ resolved for this directory, and whether that app is deployed, then prints a
 `Next:` line naming the exact next step (sign in, publish to create the app,
 deploy, or open the live URL). When a `brass login --start` sign-in is waiting
 for approval, it reports the code, the approval URL, and how long the code has
-left. Run it before a publish to see what will
-happen, and after one to confirm the app is live. `whoami` is the narrower
-check when you only need to know the credential works. Add `--json` for the
-machine-readable result on stdout.
+left. Run it before a publish to see what will happen, and after one to
+confirm the app is live. `whoami` is the narrower check when you only need to
+know the credential works. Add `--json` for the machine-readable result on
+stdout.
 
 ## Publish
 
@@ -100,15 +102,18 @@ publishes then resolve the same app instead of creating a duplicate each run.
 A service token creates the app in its own organization, so no `--org` is
 needed.
 
-The command enables hosting if needed, uploads the bundle, waits for it to go
-live, and reports the URL. The platform reads your app's capabilities
+The command enables hosting if needed, uploads the bundle, waits for the
+platform to register the slot, and reports the URL. The URL can answer 404
+until the slot reaches the serving edges, so reload if the first request
+misses. The platform reads your app's capabilities
 (`opens` / `creates` / `schema`) from the `/.well-known/brass-app.json` you
 serve, so keep that manifest in the bundle.
 
 Flags: `--app`, `--name`, `--org` (organization to own a newly created app;
 defaults to a service token's own org), `--client-token` (stable idempotency
 key for a first create), `--slug` (preferred subdomain), `--manifest`
-(default `brass-app.json`).
+(default `brass-app.json`), `--visibility` (`private`, `invitee_visible` or
+`public`), `--gate` (`on` or `off`, the hosted load gate).
 
 ## Pull a schema
 
@@ -122,8 +127,8 @@ npx @brass-build/cli schema pull --doc <docId> --out brass-app.json
 This writes the document's schema body verbatim into the manifest's `schema`
 field, preserving everything else. That is the same copy-verbatim step the
 SDK's schema guide describes, done for you. It is a development-time action
-that needs a signed-in session (`brass login`); a service token cannot fetch
-schemas.
+that needs a signed-in session (`brass login`), since a service token cannot
+fetch schemas.
 
 ## Pull your organization's agent instructions
 
@@ -134,13 +139,13 @@ AGENTS.md / CLAUDE.md), pull the current body into your repo:
 npx @brass-build/cli agents pull --out AGENTS.md
 ```
 
-The instructions are stored once at the organization level (admins edit them
-on the dashboard Settings tab) so every developer's coding agent works from
-one source of truth. The pull writes the body verbatim, so it round-trips
-byte-for-byte with what the dashboard stored. `--org <organizationId>` is
-optional when you belong to a single organization; pass it when you belong to
-more than one. This needs a signed-in session (`brass login`); a service token
-is not an organization member, so it cannot read the instructions.
+Brass stores the instructions once at the organization level (admins edit
+them on the dashboard Settings tab) so every developer's coding agent works
+from one source of truth. The pull writes the body verbatim, so it
+round-trips byte-for-byte with what the dashboard stored. Pass
+`--org <organizationId>` when you belong to more than one organization. This
+needs a signed-in session (`brass login`), since a service token is not an
+organization member and cannot read the instructions.
 
 Pass `--stdout` instead of `--out` to print the instructions to stdout
 without writing a file (status goes to stderr, so stdout carries only the

package/dist/api.d.ts

@@ -17,6 +17,7 @@ export interface HostingStatus {
     deployed: boolean;
     active_version: string | null;
     require_access?: boolean;
+    gate_settled?: boolean;
 }
 export interface HostingUploadUrl {
     upload_url: string;
@@ -60,6 +61,8 @@ export declare class BrassApiError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
 }
+/** A failed fetch as the caller should read it, naming a timeout as one. */
+export declare function networkError(what: string, cause: unknown): BrassApiError;
 export declare class BrassApi {
     private readonly apiBaseUrl;
     private readonly auth;

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/api.js

@@ -15,6 +15,22 @@ export class BrassApiError extends Error {
         this.status = status;
     }
 }
+// `fetch` carries no timeout of its own, so a host that accepts the connection
+// and then answers nothing holds the command open for as long as the caller
+// leaves it running. In CI that is a job that never finishes rather than a
+// failure anyone can read, so every request the CLI makes is bounded.
+const REQUEST_TIMEOUT_MS = 30_000;
+// The upload carries the whole bundle, so it is bounded far more loosely than
+// a request that carries a few hundred bytes.
+const UPLOAD_TIMEOUT_MS = 300_000;
+/** A failed fetch as the caller should read it, naming a timeout as one. */
+export function networkError(what, cause) {
+    const timedOut = cause instanceof Error &&
+        (cause.name === 'TimeoutError' || cause.name === 'AbortError');
+    return new BrassApiError(0, timedOut
+        ? `Timed out ${what}.`
+        : `Network error ${what}: ${String(cause)}`);
+}
 export class BrassApi {
     apiBaseUrl;
     auth;
@@ -34,7 +50,7 @@ export class BrassApi {
     async request(method, path, body) {
         const headers = {
             ...(await this.auth.headers()),
-            // Version telemetry; the api Lambda logs it so pinned CI copies
+            // Version telemetry; the platform logs it so pinned CI copies
             // stay visible in the deployed-version distribution.
             'x-brass-client': CLI_CLIENT_ID,
         };
@@ -45,10 +61,13 @@ export class BrassApi {
         }
         let response;
         try {
-            response = await fetch(`${this.apiBaseUrl}${path}`, init);
+            response = await fetch(`${this.apiBaseUrl}${path}`, {
+                ...init,
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
         }
         catch (cause) {
-            throw new BrassApiError(0, `Network error reaching ${this.apiBaseUrl}: ${String(cause)}`);
+            throw networkError(`reaching ${this.apiBaseUrl}`, cause);
         }
         if (!response.ok) {
             throw new BrassApiError(response.status, await errorMessage(response));
@@ -58,10 +77,10 @@ export class BrassApi {
         return (await response.json());
     }
 }
-// Upload bytes to a presigned S3 URL. Deliberately carries NO Brass headers
-// and no bearer: the presigned signature pins an exact header set, and a
-// stray `authorization` header would break it (the same rule the SDK's
-// `api-headers` module enforces on the document path).
+// Upload bytes to the presigned storage URL the platform handed back.
+// Deliberately carries NO Brass headers and no bearer: the presigned
+// signature pins an exact header set, so a stray `authorization` header
+// invalidates it and the upload is refused.
 export async function putPresigned(url, bytes, contentType) {
     let response;
     try {
@@ -72,10 +91,11 @@ export async function putPresigned(url, bytes, contentType) {
             // `ArrayBufferLike` is sound and satisfies fetch's `BufferSource`
             // (which pins `ArrayBufferView<ArrayBuffer>`) across lib configs.
             body: bytes,
+            signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
         });
     }
     catch (cause) {
-        throw new BrassApiError(0, `Network error uploading the bundle: ${String(cause)}`);
+        throw networkError('uploading the bundle', cause);
     }
     if (!response.ok) {
         throw new BrassApiError(response.status, `Bundle upload failed (${response.status})`);

package/dist/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,4EAA4E;AAC5E,yEAAyE;AACzE,2EAA2E;AAC3E,mEAAmE;AAGnE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AA6F7C,yEAAyE;AACzE,6EAA6E;AAC7E,8CAA8C;AAC9C,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,MAAM,CAAS;IACxB,YAAY,MAAc,EAAE,OAAe;QACzC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,MAAM,OAAO,QAAQ;IACF,UAAU,CAAS;IACnB,IAAI,CAAe;IAEpC,YAAY,UAAkB,EAAE,IAAkB;QAChD,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,GAAG,CAAI,IAAY;QACjB,OAAO,IAAI,CAAC,OAAO,CAAI,KAAK,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;IACD,IAAI,CAAI,IAAY,EAAE,IAAc;QAClC,OAAO,IAAI,CAAC,OAAO,CAAI,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC7C,CAAC;IACD,KAAK,CAAI,IAAY,EAAE,IAAc;QACnC,OAAO,IAAI,CAAC,OAAO,CAAI,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9C,CAAC;IAEO,KAAK,CAAC,OAAO,CAAI,MAAc,EAAE,IAAY,EAAE,IAAc;QACnE,MAAM,OAAO,GAA2B;YACtC,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAC9B,gEAAgE;YAChE,qDAAqD;YACrD,gBAAgB,EAAE,aAAa;SAChC,CAAC;QACF,IAAI,IAAI,GAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QAC5C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;YAC7C,IAAI,GAAG,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACjD,CAAC;QACD,IAAI,QAAkB,CAAC;QACvB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,UAAU,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;QAC5D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,aAAa,CAAC,CAAC,EAAE,0BAA0B,IAAI,CAAC,UAAU,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC5F,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,aAAa,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC;QACzE,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,SAAc,CAAC;QACnD,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAM,CAAC;IACtC,CAAC;CACF;AAED,4EAA4E;AAC5E,yEAAyE;AACzE,uEAAuE;AACvE,uDAAuD;AACvD,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,GAAW,EACX,KAAiB,EACjB,WAAmB;IAEnB,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAC1B,MAAM,EAAE,KAAK;YACb,OAAO,EAAE,EAAE,cAAc,EAAE,WAAW,EAAE;YACxC,qEAAqE;YACrE,kEAAkE;YAClE,kEAAkE;YAClE,IAAI,EAAE,KAAgC;SACvC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,aAAa,CAAC,CAAC,EAAE,uCAAuC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,aAAa,CAAC,QAAQ,CAAC,MAAM,EAAE,yBAAyB,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IACxF,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,8DAA8D;AAC9D,KAAK,UAAU,YAAY,CAAC,QAAkB;IAC5C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAwB,CAAC;QAC5D,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,KAAK,EAAE;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC;IAC7E,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;IACzE,CAAC;IACD,OAAO,8BAA8B,QAAQ,CAAC,MAAM,EAAE,CAAC;AACzD,CAAC"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/args.d.ts

@@ -1,8 +1,12 @@
 export interface ParsedArgs {
     positionals: string[];
     flags: Record<string, string | true>;
+    valuedBooleans: string[];
 }
 export declare function unknownFlags(parsed: ParsedArgs): string[];
+export declare function flagsNotReadBy(parsed: ParsedArgs, command: string): string[];
+export declare function extraPositionals(parsed: ParsedArgs, command: string): string[];
+export declare function valueFlagsOf(command: string): string[];
 export declare function valuelessFlags(parsed: ParsedArgs, names: readonly string[]): string[];
 export declare function parseArgs(argv: readonly string[]): ParsedArgs;
 export declare function stringFlag(parsed: ParsedArgs, name: string): string | undefined;

package/dist/args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IAGtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACtC;AAyCD,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAEzD;AAOD,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAErF;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CA6B7D;AAID,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAGpB;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAElE"}
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IAGtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IAIrC,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAwCD,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAEzD;AA8CD,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAO5E;AAKD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAI9E;AAKD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAMtD;AAcD,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAKrF;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CAuC7D;AAID,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAGpB;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAElE"}

package/dist/args.js

@@ -1,11 +1,10 @@
 // A minimal argv parser: no dependency, and small enough to unit-test the
 // exact precedence the commands rely on. Supports `--flag value`,
 // `--flag=value`, and boolean `--flag`; everything else is a positional.
-// Flags that never take a value, so `brass publish --yes ./dist` parses
-// `./dist` as a positional rather than the value of `--yes`.
+// Flags that never take a value, so `brass agents pull --stdout ./dir` parses
+// `./dir` as a positional rather than the value of `--stdout`.
 const BOOLEAN_FLAGS = new Set([
     'json',
-    'yes',
     'help',
     'version',
     'stdout',
@@ -41,17 +40,95 @@ const KNOWN_FLAGS = new Set([
 export function unknownFlags(parsed) {
     return Object.keys(parsed.flags).filter((name) => !KNOWN_FLAGS.has(name));
 }
+// The flags every command reads, whichever it is: where to talk to and what
+// to print.
+const COMMON_FLAGS = [
+    'api-url',
+    'auth-url',
+    'dashboard-url',
+    'help',
+    'json',
+    'version',
+];
+// What each command reads beyond those, and how many positionals it takes
+// (the command word included, so `publish [dir]` is 2). A flag one command
+// reads is not thereby a flag of the next: `--wait` is the sign-in poll's
+// deadline and `publish` has its own, so `brass publish --wait 600` waits
+// exactly as long as it would have without the flag. Refusing it names the
+// mistake, where accepting it leaves the caller believing they set something.
+const COMMAND_ARGS = {
+    login: { flags: ['check', 'new', 'start', 'wait'], positionals: 1 },
+    logout: { flags: [], positionals: 1 },
+    status: { flags: ['app', 'manifest', 'token'], positionals: 2 },
+    publish: {
+        flags: [
+            'app',
+            'client-token',
+            'gate',
+            'manifest',
+            'name',
+            'org',
+            'slug',
+            'token',
+            'visibility',
+        ],
+        positionals: 2,
+    },
+    schema: { flags: ['doc', 'out', 'token'], positionals: 2 },
+    agents: { flags: ['org', 'out', 'stdout', 'token'], positionals: 2 },
+    whoami: { flags: ['token'], positionals: 1 },
+};
+// The flags `command` does not read, out of the ones this CLI knows. A name
+// the CLI knows nowhere is `unknownFlags`' answer and stays there, so a
+// misspelling is reported as one rather than as a flag of another command.
+// A command this CLI does not have answers for itself.
+export function flagsNotReadBy(parsed, command) {
+    const spec = COMMAND_ARGS[command];
+    if (spec === undefined)
+        return [];
+    const reads = new Set([...COMMON_FLAGS, ...spec.flags]);
+    return Object.keys(parsed.flags).filter((name) => KNOWN_FLAGS.has(name) && !reads.has(name));
+}
+// The positionals past the ones `command` reads. An ignored one is the same
+// silence a flag no command reads leaves: `brass publish out dist` publishes
+// `out`, and the caller who meant `dist` is told nothing.
+export function extraPositionals(parsed, command) {
+    const spec = COMMAND_ARGS[command];
+    if (spec === undefined)
+        return [];
+    return parsed.positionals.slice(spec.positionals);
+}
+// The flags of `command` that carry a value, so a bare one is the caller
+// naming something the run then resolves a default for. `--wait` is absent
+// here because a bare `--wait` is its own answer (the default deadline).
+export function valueFlagsOf(command) {
+    const spec = COMMAND_ARGS[command];
+    if (spec === undefined)
+        return [];
+    return [...COMMON_FLAGS, ...spec.flags].filter((name) => !BOOLEAN_FLAGS.has(name) && name !== 'wait');
+}
 // Which of `names` were given without a value (`--api-url --json`, or
 // `--api-url` last on the line). The parser stores those as `true` and
 // `stringFlag` reads that as absent, so an origin flag in this state resolves
 // the production default while the command line names another stack. That is
 // the same silent retarget `unknownFlags` catches for a misspelled name.
+//
+// An EMPTY value counts, and it is the shape a caller actually reaches: a
+// script writing `--slug "$SLUG"` against an unset variable passes the flag
+// with nothing behind it. That value is not absent the way a bare flag is, so
+// it resolves no default and travels to the server as an empty string, where
+// the mistake is reported (if at all) in the server's vocabulary rather than
+// as the missing value it is.
 export function valuelessFlags(parsed, names) {
-    return names.filter((name) => parsed.flags[name] === true);
+    return names.filter((name) => {
+        const value = parsed.flags[name];
+        return value === true || value === '';
+    });
 }
 export function parseArgs(argv) {
     const positionals = [];
     const flags = {};
+    const valuedBooleans = [];
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === undefined)
@@ -60,7 +137,16 @@ export function parseArgs(argv) {
             const body = arg.slice(2);
             const eq = body.indexOf('=');
             if (eq !== -1) {
-                flags[body.slice(0, eq)] = body.slice(eq + 1);
+                const name = body.slice(0, eq);
+                if (BOOLEAN_FLAGS.has(name)) {
+                    // Recorded rather than read: `--json=false` reads as ON, which is
+                    // the reverse of what the caller wrote, and `--stdout=false` would
+                    // send a file's contents to stdout and write nothing.
+                    valuedBooleans.push(name);
+                    flags[name] = true;
+                    continue;
+                }
+                flags[name] = body.slice(eq + 1);
                 continue;
             }
             if (BOOLEAN_FLAGS.has(body)) {
@@ -80,7 +166,7 @@ export function parseArgs(argv) {
             positionals.push(arg);
         }
     }
-    return { positionals, flags };
+    return { positionals, flags, valuedBooleans };
 }
 // Read a flag expected to carry a string value; a bare boolean flag (no
 // value) is treated as absent so `--doc` alone doesn't resolve to `true`.

package/dist/args.js.map

@@ -1 +1 @@
-{"version":3,"file":"args.js","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAoCA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,OAAO,EAAE,CAAC;AA2CnB,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA0DlE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AA6CA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,OAAO,EAAE,CAAC;AA2CnB,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAmGlE"}