@brass-build/cli 0.3.0 → 0.4.0

package/AGENTS.md

@@ -1,8 +1,8 @@
 # Instructions for AI coding agents
 
 You are likely an AI coding agent publishing a Brass app you built against
-`@brass-build/client`. This tool is how you ship it and how you pull a
-schema to build against. The [README](./README.md) is the full reference;
+`@brass-build/client`. This tool is how you ship it, and how you read the
+document you are building against. The [README](./README.md) is the full reference;
 this file is the short path for you.
 
 ## Follow your organization's coding instructions first
@@ -50,8 +50,11 @@ npx @brass-build/cli login --start          # prints the approval URL + code
 npx @brass-build/cli login --check --wait   # polls until they approve
 ```
 
-`--start` prints an approval URL and a short code and exits. Give both to the
-human in your next message, then run `--check --wait`. It polls for up to two
+`--start` prints an approval URL and a short code and exits. **Put both in the
+visible text of your next message**, not only in the command output: most
+interfaces collapse tool output, so a link left there reaches nobody and the
+sign-in waits forever. Write the URL and the code out, say what the person has
+to do with them, then run `--check --wait`. It polls for up to two
 minutes (`--wait <seconds>` for a different bound) and stores the session the
 moment they approve. A code that lapses is replaced and the new one printed,
 so the sign-in outlives any single code and a session started early is still
@@ -95,14 +98,16 @@ publish, deploy, or open the live URL). Run it, do what it says, then run it
 again. The steps below are what it walks you through:
 
 1. Build the app to a static bundle (its `brass-app.json` capability
-   manifest must be in the output).
+   manifest must be in the output, at `/.well-known/brass-app.json`).
+   Confirm it is there after the build: some bundlers skip dot-directories
+   when they copy static assets.
 2. Make sure a credential is available: `BRASS_SERVICE_TOKEN` in the
    environment (or `--token`) for CI, or a `brass login` session for local
    development. When `brass status` reports none, run the sign-in yourself,
    as [Signing in](#signing-in) describes.
    Starting it, relaying the URL, and checking it through to approved is your
    step, not a handoff you stop at. (Or the human mints a service token in
-   the dashboard: org Settings, then Service tokens.)
+   the dashboard: org Settings, then Access tokens.)
 3. Publish:
 
    ```sh
@@ -114,22 +119,141 @@ again. The steps below are what it walks you through:
    its own organization, so no `--org` is needed. If the pipeline does not
    persist `.brass/project.json` between runs, set a stable `client_token`
    (a `"client_token"` in `brass-app.json`, or `--client-token`) so the
-   first create is idempotent and re-runs resolve the same app.
+   first create is idempotent and re-runs resolve the same app. A create
+   that carries no `client_token` warns on stderr; act on that warning,
+   because the duplicate apps it predicts appear only on later runs.
+
+   The command reads `<dir>/.well-known/brass-app.json`, then
+   `brass-app.json` in the working directory, so a manifest in either place
+   is found without `--manifest`.
 
 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, and the reason is
 on stderr.
 
+## Opening the app in a browser, signed in
+
+Building the app is not verifying it. What a person will do is open it,
+sign in, and use it, and until you have done that yourself you know only
+that it compiles. `brass browser-session` is how you sign in: it prints a
+URL that opens the app as the human whose machine you are on, so you can
+drive the real thing rather than reporting it verified by types.
+
+```sh
+npx @brass-build/cli browser-session --return-to http://localhost:5173/
+```
+
+That prints one URL on stdout. Open it in the browser you drive, and the
+app boots signed in. The URL is single-use and expires two minutes after
+it is printed, so mint it at the moment you are ready to navigate, not
+ahead of time, and put it straight into the browser: it is a credential
+for as long as it lives, so keep it out of files you commit, PR bodies,
+and anything you print back to the human.
+
+`--return-to` is where the browser lands, and it has to be on the app's
+redirect allowlist. A new app allows any `localhost` and `127.0.0.1`
+port, so a dev server needs nothing configured. `--app <appId>` names the
+app, and without it the command reads `.brass/project.json`, so after a
+publish in the same directory you can leave it off.
+
+Point it at the published URL to drive what you actually shipped:
+
+```sh
+npx @brass-build/cli browser-session --return-to https://<slug>.onbrass.app/
+```
+
+A published app allows its own URL, and the printed link carries the
+browser through the hosted app's access gate as well as signing it in, so
+one navigation reaches the running app either way.
+
+The published URL is also the one to use when the app was first created by
+your CI rather than from a machine someone works on. Such an app carries no
+`localhost` entry, so a handoff aimed at a dev server answers that the
+`return_to` is not on the allowlist. Add the entry yourself to work locally
+(the app's Redirect URLs, in its dashboard page) or point the handoff at
+what CI published.
+
+### You can drive a browser
+
+If you have no browser tool to hand, install one rather than concluding
+this cannot be done from where you are: `npm i -D playwright` (then
+`npx playwright install chromium`) or `npm i -D puppeteer` gives you a
+headless Chromium you script from Node, which is all this needs. A
+sandbox with no display still runs headless Chromium. Reaching for a
+`curl` of the page instead does not verify the app: the sign-in and the
+app's own rendering both happen in the browser's JavaScript, so a fetch
+of the HTML shows you a loading shell whatever is wrong underneath.
+
+Drive it the way a person would: sign in through the URL, do the thing
+the app is for, and read the result off the screen. Take a screenshot at
+a phone width as well as a desktop one.
+
+An app your organization owns needs no approval step: the command mints for
+it directly. That covers the ordinary loop, where `brass publish` creates
+the app after you signed in, and it covers an app somebody else published
+first, from a colleague's machine or from CI.
+
+The URL grants no more than your current session: it signs in as the
+same person, in the same apps they have approved. `brass logout` ends
+it along with everything else this machine holds.
+
+That is a session for the app, so drive what the app itself renders.
+Brass's own hosted dialogs (the document picker, sharing, version
+history) authenticate from a Brass session the person established in that
+browser by signing in there, which is deliberately more than a machine's
+credential carries: it would reach their whole account. Exercise those in
+a browser you signed in to yourself, and build the app so the paths you
+drive do not depend on one opening.
+
+### When it says the app needs approving
+
+Opening an app that belongs to another organization is the one case that
+asks a human first. The command answers `needs_approval` with an
+`approval_url`:
+
+```json
+{ "state": "needs_approval", "app_id": "brass_app_...", "approval_url": "https://auth.brass.build/device/approve-app?request=..." }
+```
+
+You cannot approve it. Give the human the `approval_url`, ask them to
+open it and approve, then run the same command again. They have to be
+signed in to Brass as the same account this machine is signed in as: they
+are approving one of their own machines.
+
+Re-running the command while you wait hands you the same link, with its
+lifetime refreshed, so nothing you have already relayed stops working and
+there is no second URL to send. `brass status` reports the outstanding
+approval and how long it has left, so you never have to guess whether one
+is still in flight.
+
+Do not sign out and back in to attach the app to your session: that
+discards a working credential and still needs the same human approval.
+Relay the URL.
+
+When you know that app's id before signing in, and are not signed in yet,
+name it on the sign-in instead and one approval covers the pair:
+
+```sh
+npx @brass-build/cli login --start --app brass_app_...
+```
+
+The approval page then names that app beside the CLI, and
+`brass browser-session` mints for it on the first try.
+
 ## Pulling a schema to build against
 
 To interoperate with documents another app or importer produces, do not
 hand-write the schema. Open one of its documents and pull the real body:
 
 ```sh
-npx @brass-build/cli schema pull --doc <docId> --out brass-app.json
+npx @brass-build/cli schema pull --doc <docId>
 ```
 
-This writes the schema verbatim into your manifest. Build your types against
+This writes the schema verbatim into your manifest. Without `--out` it
+merges into an existing one (`brass-app.json`, `.well-known/`,
+`public/.well-known/`, `static/.well-known/`, in that order), so the
+schema lands in the file your bundle serves rather than a second one
+beside it. Build your types against
 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`),
@@ -137,13 +261,48 @@ 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.
 
+## Reading what the document holds
+
+The schema is the shape; this is the data. Read it before you write code
+against it, so your field names, types, and the values you branch on come
+from the document rather than from a guess at what the schema's words mean:
+
+```sh
+npx @brass-build/cli contents --doc <docId>
+```
+
+This writes `contents.json`: the whole document, keyed by root container. A
+map root is the object your app reads through `doc.map(root)`, so what is in
+the file is what you will render. `--stdout` pipes it instead.
+
+Read the whole file, not the first few records. A file's records are grouped
+by type, so its opening records are a couple of the types it carries and none
+of the rest, and an app built against those breaks on the first record of any
+other type. Work out the full set before you design anything:
+
+```sh
+npx @brass-build/cli contents --doc <docId> --stdout \
+  | jq '.instances | map(.type) | group_by(.) | map({type: .[0], count: length})'
+```
+
+Then pull an example of each type you plan to handle and build against those.
+`--stream <name>` reads a stream other than `default`. This needs the same
+signed-in session `schema pull` does.
+
+Reading a file Brass is still importing waits for the import to finish, so
+the command runs long on a large one rather than failing. It prints each step
+to stderr; `--no-wait` reads once and fails instead.
+
 ## Verifying
 
 `npx @brass-build/cli status` is the check to run before and after a publish:
 it confirms the credential authenticates and reports whether the app is
 deployed, with the next step to take. `npx @brass-build/cli whoami` is the
-narrower check when you only need to confirm the credential works. After a
-publish, open the reported URL to confirm the app loads.
+narrower check when you only need to confirm the credential works.
+
+After a publish, open the reported URL and drive the app signed in, as
+[Opening the app in a browser](#opening-the-app-in-a-browser-signed-in)
+describes. That is the check the others stand in for.
 
 ## When a command fails
 

package/CHANGELOG.md

@@ -6,6 +6,24 @@ 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.4.0
+
+### Added
+
+- `brass contents --doc <docId>` writes a document out as JSON, so you can
+  build and test against the data your app will really see rather than
+  against a fixture you wrote by hand. Each root container is a key,
+  holding what `doc.map(root)` and `doc.list(root)` return.
+- `brass browser-session --return-to <url>` prints a single-use URL that opens
+  your app signed in as you, so a coding agent driving a browser can check its
+  work as a signed-in user.
+
+### Changed
+
+- `brass publish` and `brass schema pull` look for `brass-app.json` in the
+  current directory and the common bundle locations, so neither needs
+  `--manifest` or `--out` unless the manifest sits somewhere else.
+
 ## 0.3.0
 
 ### Changed

package/README.md

@@ -1,12 +1,10 @@
 # @brass-build/cli
 
 From a terminal or a CI pipeline, the `brass` command publishes a Brass
-app's built bundle and pulls document schemas. It wraps the same data API the
+app's built bundle and reads the documents you build against. 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.2.x` line.
-
 ## Install
 
 No install step. Run it with `npx`:
@@ -62,6 +60,21 @@ export BRASS_SERVICE_TOKEN=brass_sk_...
 npx @brass-build/cli whoami
 ```
 
+## Opening your app signed in
+
+`browser-session` prints a single-use URL that opens your app as you, for a
+browser an automated tool is driving:
+
+```sh
+npx @brass-build/cli browser-session --return-to http://localhost:5173/
+```
+
+It exists for coding agents, which have no browser session of their own and
+otherwise cannot check that what they built works for a signed-in user. If you
+are at your own machine, opening the app in your own browser does the same
+thing with fewer steps. `AGENTS.md` in this package documents the flow,
+including what to do when the app has not been approved for this machine yet.
+
 ## Status
 
 `status` reports the credential and app state for the target environment and
@@ -99,8 +112,9 @@ For a pipeline that stands the app up from scratch and does not persist
 `.brass/project.json` between runs, set a stable `client_token` (a
 `"client_token"` in `brass-app.json`, or `--client-token`). Repeated first
 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.
+A create that carries no `client_token` says so on stderr, since the duplicate
+it can produce shows up only later. 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 the
 platform to register the slot, and reports the URL. The URL can answer 404
@@ -109,11 +123,17 @@ 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.
 
+Without `--manifest`, the command reads `<dir>/.well-known/brass-app.json`
+and falls back to `brass-app.json` in the working directory, so the manifest
+you ship at `/.well-known/` is found where it already sits. A manifest that is
+present and cannot be parsed fails the publish, naming the file.
+
 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`), `--visibility` (`private`, `invitee_visible` or
-`public`), `--gate` (`on` or `off`, the hosted load gate).
+key for a first create), `--slug` (preferred subdomain), `--manifest` (a
+manifest path, overriding the search above), `--visibility` (`private`,
+`invitee_visible` or `public`), `--gate` (`on` or `off`, the hosted load
+gate).
 
 ## Pull a schema
 
@@ -121,14 +141,55 @@ To build against a shape another app or importer produces, open one of its
 documents and copy its schema into your manifest:
 
 ```sh
-npx @brass-build/cli schema pull --doc <docId> --out brass-app.json
+npx @brass-build/cli schema pull --doc <docId>
 ```
 
 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`), since a service token cannot
-fetch schemas.
+SDK's schema guide describes, done for you.
+
+Without `--out` it merges into an existing manifest, checking
+`brass-app.json`, `.well-known/`, `public/.well-known/` and
+`static/.well-known/` in that order, and writes `brass-app.json` when it finds
+none. It never writes into a build output directory, where the next build
+would drop it.
+
+Pulling a schema is a development-time action that needs a signed-in session
+(`brass login`), since a service token cannot fetch schemas.
+
+## Read what a document holds
+
+A schema says what shape the records take; to get the records themselves,
+write the document out as JSON:
+
+```sh
+npx @brass-build/cli contents --doc <docId>
+```
+
+This writes `contents.json` (`--out <path>` for somewhere else, `--stdout` to
+pipe it). The file is the whole document, keyed by root container: a map root
+is the object your app reads through `doc.map(root)`, a list root its items,
+in the same shapes your code will see.
+
+The whole document, not a sample. A file's records are grouped by type, so any
+slice off the front carries a couple of the types it holds and none of the
+rest; with the file on disk you can count the types, pull an example of each,
+or filter to one, and every answer covers everything the document has:
+
+```sh
+npx @brass-build/cli contents --doc <docId> --stdout \
+  | jq '.instances | map(.type) | group_by(.) | map({type: .[0], count: length})'
+```
+
+Brass fetches the document the way an app does, as the compact CRDT snapshot
+plus the ops after it, and unpacks it here, so the download stays small
+whatever the file's size. `--stream <name>` reads a stream other than
+`default` and `--branch <id>` a branch other than the default. Like
+`schema pull`, this needs a signed-in session (`brass login`).
+
+Reading a file Brass is still importing waits for the import to finish, and
+reports each step it moves through. `--wait <seconds>` moves the deadline
+(900 by default) and `--no-wait` reads once and fails instead.
 
 ## Pull your organization's agent instructions
 
@@ -169,9 +230,10 @@ whenever you pull to any file other than `CLAUDE.md`.
 ```
 
 The service token creates the app in its own organization on the first run.
-Give `brass-app.json` a stable `"client_token"` so that first create is
+Give your `brass-app.json` a stable `"client_token"` so that first create is
 idempotent (repeated runs resolve the same app rather than duplicating it),
-or commit `.brass/project.json` to pin the app id.
+or commit `.brass/project.json` to pin the app id. A run with neither creates
+a new app each time, and warns that it did.
 
 Add `--json` to any command to emit the machine-readable result on stdout
 (human status stays on stderr).

package/dist/api.d.ts

@@ -42,6 +42,45 @@ export interface DocumentStreams {
 export interface DocumentTypeSummary {
     schema_type?: string;
 }
+export type DocumentJoinSnapshot = {
+    kind: 'inline';
+    data_b64: string;
+} | {
+    kind: 'presigned';
+    url: string;
+    expires_at: string;
+    raw_bytes: number;
+};
+export type DocumentJoinTailOp = {
+    seq: number;
+    op_blob_b64: string;
+} | {
+    seq: number;
+    op_blob_url: string;
+    op_blob_bytes: number;
+};
+export interface DocumentWorkStatus {
+    message: string;
+    pending: boolean;
+    blocking: boolean;
+    progress?: number;
+}
+export interface DocumentJoin {
+    doc_id: string;
+    branch_id: string;
+    stream_branch_id?: string;
+    name?: string;
+    schema_type?: string;
+    snapshot: DocumentJoinSnapshot | null;
+    tail_ops: DocumentJoinTailOp[];
+    snapshot_seq: number;
+    current_seq: number;
+    status?: DocumentWorkStatus;
+}
+export interface DocumentDetail {
+    doc_id: string;
+    status?: DocumentWorkStatus;
+}
 export interface AgentInstructionsResponse {
     content: string;
     updated_at?: string;
@@ -61,6 +100,12 @@ export declare class BrassApiError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
 }
+/**
+ * Fetch bytes from a presigned URL. Not an API call: the signature is the
+ * credential, so no auth header goes with it, and sending one is refused as
+ * a second credential on the request.
+ */
+export declare function getPresigned(url: string): Promise<Uint8Array>;
 /** 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 {

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

@@ -23,6 +23,24 @@ 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;
+/**
+ * Fetch bytes from a presigned URL. Not an API call: the signature is the
+ * credential, so no auth header goes with it, and sending one is refused as
+ * a second credential on the request.
+ */
+export async function getPresigned(url) {
+    let response;
+    try {
+        response = await fetch(url, { signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS) });
+    }
+    catch (cause) {
+        throw networkError('fetching document bytes', cause);
+    }
+    if (!response.ok) {
+        throw new BrassApiError(response.status, `Could not fetch the document's bytes (${response.status}).`);
+    }
+    return new Uint8Array(await response.arrayBuffer());
+}
 /** A failed fetch as the caller should read it, naming a timeout as one. */
 export function networkError(what, cause) {
     const timedOut = cause instanceof Error &&
@@ -50,8 +68,9 @@ export class BrassApi {
     async request(method, path, body) {
         const headers = {
             ...(await this.auth.headers()),
-            // Version telemetry; the platform logs it so pinned CI copies
-            // stay visible in the deployed-version distribution.
+            // Names this CLI and its version. Brass answers a build too old to
+            // serve with an upgrade message, rather than a failure that names
+            // something else.
             'x-brass-client': CLI_CLIENT_ID,
         };
         let init = { method, headers };

package/dist/api.js.map

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

package/dist/approval-prompt.d.ts

@@ -0,0 +1,25 @@
+export interface ApprovalPromptInput {
+    /** Where the human approves, user code prefilled where the server offers it. */
+    url: string;
+    /** The code they confirm on that page, for a request that carries one. An
+     *  app approval names the app on its own page instead, so it has none. */
+    code?: string;
+    /** What the reader is being asked to approve. Defaults to the device grant,
+     *  which is what most of these are. */
+    heading?: string;
+    /** Why this prompt is showing again, when it is not the first time. */
+    lead?: string | null;
+    /** The command that finishes the sign-in, for a caller that exits before
+     *  approval. A blocking sign-in polls on its own and passes the line it
+     *  waits under instead. */
+    nextCommand?: string | null;
+    /** What a caller with no command to name says under the block. */
+    closing?: string | null;
+    /** Set by the flow a caller who cannot approve is the usual reason to run
+     *  (`--start` / `--check`), which adds the note asking an agent to pass the
+     *  link on. The blocking `brass login` leaves it unset: whoever ran it is
+     *  waiting to approve. */
+    relaying?: boolean;
+}
+export declare function renderApprovalPrompt(input: ApprovalPromptInput): string;
+//# sourceMappingURL=approval-prompt.d.ts.map

package/dist/approval-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-prompt.d.ts","sourceRoot":"","sources":["../src/approval-prompt.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ;8EAC0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;2CACuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;+BAE2B;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;;8BAG0B;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CA0BvE"}

package/dist/approval-prompt.js

@@ -0,0 +1,44 @@
+// The one rendering of an approval a human has to give: the URL to open, the
+// code to confirm where there is one, plus what to do next. Every phase of the
+// sign-in prints through here, so a fresh grant, a resumed one, and a renewed
+// one read the same, and so does the app approval `brass browser-session`
+// asks for, which is the same request with a different subject.
+//
+// Whether the reader is the person who approves decides whether the block
+// needs a relay instruction, and the caller narrows it: `brass login` blocks
+// until approval, so whoever ran it is waiting to approve, while `--start` /
+// `--check` exist for a caller that cannot hold a command open, which is
+// usually an agent. Usually, not always, so the note there is addressed to an
+// agent as a condition rather than asserted about the reader, and a person
+// running `--start` themselves reads past it.
+//
+// The caller is what narrows it because `isTTY` answers the wrong question
+// twice: an agent harness that allocates a pty (many do, for colored output)
+// reads as a watched terminal, and `brass login | tee` reads as an agent.
+//
+// The frame is ASCII: this goes to whatever console the caller has, and a
+// box-drawing character that renders as a replacement glyph costs more
+// prominence than the frame buys.
+const RULE = '='.repeat(64);
+export function renderApprovalPrompt(input) {
+    const lines = [];
+    if (input.lead)
+        lines.push(input.lead, '');
+    lines.push(RULE, input.heading ?? ' To approve this sign-in, open this link and confirm the code:', '', `   ${input.url}`);
+    if (input.code)
+        lines.push(`   Code:  ${input.code}`);
+    if (input.relaying === true) {
+        lines.push('', input.code
+            ? ' If you are an AI agent, put the link and the code directly in your'
+            : ' If you are an AI agent, put the link directly in your', ' reply. The person who approves often cannot see this output.');
+    }
+    lines.push(RULE);
+    if (input.nextCommand) {
+        lines.push('', `Then run \`${input.nextCommand}\` to finish signing in.`);
+    }
+    else if (input.closing) {
+        lines.push('', input.closing);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=approval-prompt.js.map

package/dist/approval-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-prompt.js","sourceRoot":"","sources":["../src/approval-prompt.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,+EAA+E;AAC/E,8EAA8E;AAC9E,0EAA0E;AAC1E,gEAAgE;AAChE,EAAE;AACF,0EAA0E;AAC1E,6EAA6E;AAC7E,6EAA6E;AAC7E,yEAAyE;AACzE,8EAA8E;AAC9E,2EAA2E;AAC3E,8CAA8C;AAC9C,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,0EAA0E;AAC1E,EAAE;AACF,0EAA0E;AAC1E,uEAAuE;AACvE,kCAAkC;AAElC,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AA0B5B,MAAM,UAAU,oBAAoB,CAAC,KAA0B;IAC7D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,KAAK,CAAC,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC3C,KAAK,CAAC,IAAI,CACR,IAAI,EACJ,KAAK,CAAC,OAAO,IAAI,gEAAgE,EACjF,EAAE,EACF,MAAM,KAAK,CAAC,GAAG,EAAE,CAClB,CAAC;IACF,IAAI,KAAK,CAAC,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,aAAa,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACtD,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CACR,EAAE,EACF,KAAK,CAAC,IAAI;YACR,CAAC,CAAC,qEAAqE;YACvE,CAAC,CAAC,wDAAwD,EAC5D,+DAA+D,CAChE,CAAC;IACJ,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,cAAc,KAAK,CAAC,WAAW,0BAA0B,CAAC,CAAC;IAC5E,CAAC;SAAM,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

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;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"}
+{"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;AA4CD,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAEzD;AAmDD,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"}