@brass-build/client 0.4.1 → 0.5.0

package/AGENTS.md

@@ -16,19 +16,19 @@ guesses at a shape the real files contradict.
 **The work has a customary shape in the user's trade.** A punch list, a
 timesheet, an RFI, a site diary: people in that line of work pass these
 around as documents whose fields they all expect, so a shape for it
-exists and the user probably holds a copy. Ask for theirs before you
+exists and the user probably has a copy. Ask for theirs before you
 design a schema. Inventing a schema for a shape that already exists
 forks that shape: the picker routes documents to apps by their declared
 schema, so each app's documents stop opening in the other, and the split
 stands. Ask the user rather than searching for the shape yourself: it
-reaches you as a document they already hold.
+reaches you as a document they already have.
 
 Ask as well whenever the user brings up another application. What that
 product can hand over decides whether you adopt a shape or integrate,
 and only the user knows.
 
 A product you assumed, rather than one the user named, works the other
-way round. Data a product holds reaches you through its API rather than
+way round. Data a product stores reaches you through its API rather than
 as a document, so a sprint board, a sales pipeline, or a ticket queue
 you guess lives in some tool leaves you no shape to adopt. Build it as
 below until the user names the tool.
@@ -47,18 +47,40 @@ section), and scaffold the app shell while the user answers.
 
 With an example in hand: the user adds it at their Brass dashboard
 (`https://app.brass.build`) and sends you back the document's link,
-and you read what that document holds. A resolved schema is your
+and you read what that document contains. A resolved schema is your
 record contract: pull it and adopt it verbatim
 (`npx @brass-build/cli schema pull --doc <docId>`). Read the records too,
 before you write code against them
-(`npx @brass-build/cli contents --doc <docId>` writes the whole document as
-JSON): the schema names the fields and the data tells you what is in them.
+(`npx @brass-build/cli contents --doc <docId>` writes the document's
+`default` stream as JSON, and `--stream <name>` writes another stream): the
+schema names the fields and the data tells you what is in them.
+When your app reads that document through `Brass.chooseInputs` rather than
+opening it, pull with `--out input-schema.json` instead and copy that
+file's `schema` into an `inputs` entry. A plain pull writes over your
+manifest's `schema`, and Brass would then offer your app to open that
+document's family.
 Read all of it rather than the first few records, since a file's records are
-grouped by type and its opening records carry a couple of the types it holds
-and none of the rest. A stored file with
-no schema means your app is its first importer: register your parse
-half with `Brass.registerImporter`, and declare the schema of the
-records you write in `brass-app.json` so the next app can adopt it.
+grouped by type and its opening records carry a couple of its types
+and none of the rest.
+When your app reads many documents through `Brass.chooseInputs`, ask the
+user for the project or folder it will read rather than one file, and
+sample that set with `npx @brass-build/cli contents --from project:<projectId>`.
+Run it first with `--max-documents 0`, which lists the set without reading
+it, to see the families the set's files belong to (the `family` on each
+document it lists), then pass `--family` the families your `chooseInputs`
+call names. The command lists the
+documents that call returns, reads several of them whole, and counts every
+record type their streams contain, with a few records of each type drawn from
+different documents. Sample the set because one file shows only the types
+it carries, and other files in the set can carry more. Reading a file
+starts its import, as opening it does, so keep some files of the set out
+of the sample for the first-run check below.
+If a stored file has no schema, your app is its first importer. Register a
+function with `Brass.registerImporter` that takes the file and returns its
+records as JSON, and declare the schema of those records in
+`brass-app.json` so the next app can adopt it. Call `registerImporter` at
+startup, unconditionally, not after sign-in or after a document opens:
+Brass may load your app only to run its importer.
 In your app, the file opens the way every document opens: through the
 session and the hosted picker (the picker also brings a file into
 Brass).
@@ -89,11 +111,22 @@ front whether the org has any: an org that set none prints nothing, and
 you proceed with the defaults below.
 
 The pull needs a signed-in session, so when `brass agents pull` reports
-no credential, run the sign-in yourself first (`brass login --start`,
-relay the printed URL and code to the human, then `brass login --check`
-until it reports approved). That is the same credential you will use to
-publish (see "Ship the app"), so drive the sign-in now. `brass agents
-pull` is detailed in the `@brass-build/cli` package's `AGENTS.md`.
+no credential, run the sign-in yourself first: run `brass login --start`
+and copy the URL and code it prints into the visible text of your reply.
+Most interfaces collapse command output, so the human never sees a code
+that stays there. Then keep running `brass login --check --wait` in the
+same turn until it reports approved: only a check stores the session,
+and if the human approves while no check is running, the approval waits
+for your next check. If the human sees your reply only when your turn
+ends (you run as a subagent, or in a harness that shows only the final
+message), end the turn with the URL and code instead, and run the check
+as soon as you resume. That is the same credential you will use to
+publish (see "Ship the app").
+
+When the pull lists several organizations instead of pulling, ask the
+human which one the app is for, and pass that id as `--org` to the pull
+and to your first `brass publish`. `brass agents pull` is detailed in
+the `@brass-build/cli` package's `AGENTS.md`.
 
 ## Have a second agent review your work
 
@@ -105,20 +138,34 @@ reviewing your own work reconfirms it. Build with a review loop.
 
 Once the integration builds, have a **separate** agent (not you)
 adversarially review it and drive it in a real browser against the
-live backend. Hold that reviewer to implementation-independent checks:
+live backend. Give that reviewer implementation-independent checks:
 
-- It should take the document's own records from a subscriber of its
-  own (`doc.map(...).subscribe(...)` / `doc.list(...).subscribe(...)`)
-  and validate them against the data spec itself, rather than trusting
-  the app's own helpers.
+- It should read the document's records itself (walk
+  `doc.map(...).entries()` / `doc.list(...).values()`, or subscribe to
+  follow edits) and validate them against the data spec, rather than
+  trusting the app's own helpers.
 - It should push the negative, zero, and boundary inputs of every
   operation.
 - It should confirm each edit round-trips and leaves the document
   consistent.
-- It should open the same document as **two** signed-in readers and put
-  them in the same field at once: with one reader's caret sitting in a
-  field, the other edits it. The first reader's screen has to show that
-  value once their caret leaves, and a reader whose own edit goes over a
+- If the app reads across many documents, it should run the app over a
+  set that includes files nobody has opened yet (the ones you kept out of
+  your `contents --from` sample, or files added just before the run),
+  because a file's import can still be running when the app opens it. It should confirm the app shows
+  a loading state while such an open waits, and renders the records once
+  it resolves. It should include a file only another app imports, and
+  confirm the app shows that file as not imported yet when its open
+  rejects with `not_imported`. Once the other app has imported the file,
+  Brass calls the key's handler for it again, and the app should then
+  read it.
+- If the app offers use without an account, it should make a document
+  signed out, then sign in through the app's own sign-in on that page and
+  confirm the document is still there. Signing in any other way, such as
+  through `brass browser-session`, leaves the document behind.
+- It should open the same document as **two** signed-in users and put
+  them in the same field at once: with one user's caret sitting in a
+  field, the other edits it. The first user's screen has to show that
+  value once their caret leaves, and a user whose own edit goes over a
   peer's has to be told so. Both halves fail silently, and a single
   session never reaches either.
 
@@ -134,14 +181,18 @@ Point `--return-to` at your dev server while you build, and at the
 published URL once you have one. Run the command once per browser
 context, at the moment that context is ready to navigate. Each URL signs
 in one browser once and expires two minutes after it is printed. Give
-the two readers a URL each. Both readers are you, so ask the human for a
-second account when a check needs them to be different people.
+each of the two users a URL. Both sign in to the human's account, so ask
+the human for a second account when a check needs two different people.
 
 Open the document by its id, through `Brass.openDocumentById` or the
-`?doc=` parameter the session restores on boot. The picker and Brass's
-other dialogs need a Brass sign-in, which this URL does not provide. The
-`@brass-build/cli` package's `AGENTS.md` covers the rest, including how
-to install and drive a headless browser.
+`?doc=` parameter the session restores on boot. Use a document your app
+created, or one a user previously opened in your app from Brass. Brass refuses
+access to documents the user has not granted to your app, returning a 403 status.
+Brass's own dialogs, such as the picker, open in that browser too once the human
+has signed in to the Brass dashboard before. Otherwise a dialog asks for a
+sign-in that the human has to complete. The `@brass-build/cli` package's
+`AGENTS.md` covers the rest, including how to install and drive a headless
+browser.
 
 Have the reviewer drive any gesture on a touch device as well as a
 desktop mouse. Drags, multi-point taps, and anything else
@@ -162,13 +213,23 @@ the baseline for when there is no design.
   viewport; do not center the app in a `max-width: 720px` column.
 - **Render two distinct shells, signed-out and signed-in.** A
   signed-in shell with disabled buttons next to a sign-in CTA reads as
-  broken. Mount the signed-in shell after `onUserChange` fires with a
-  non-null user, and render **neither** shell during the bootstrap
-  window before that first fire (see "Rendering auth state" in the
-  README).
+  broken. Mount the working shell when `Brass.authStatus` is
+  `'signed-in'` or `'guest'` (a visitor working without an account has no
+  user), the signed-out shell only on `'signed-out'`, and **neither**
+  during the `'unknown'` window before `init` settles (see "Rendering auth
+  state" in the README).
+- **Let a visitor try the app without an account.** Give the signed-out
+  shell New and Upload buttons beside Sign in, declare
+  `"access": { "create": "anyone" }`, and publish with
+  `--gate off --visibility public` (see "Try before signing in" in the
+  README). Declare `"create": "signed-in"` instead only when the app's
+  content comes from files people pick with `Brass.chooseInputs`, or
+  when every action calls a service. When one feature calls a service,
+  disable that feature for a visitor and offer the rest.
 - **Put auth chrome in the header of the signed-in shell only**: the
-  user's email or sub, plus sign out. The sign-in CTA belongs in the
-  body of the signed-out shell, not in a pre-rendered header.
+  user's email or sub, plus sign out. The sign-in CTA, and any way in
+  without an account (see "Try before signing in" in the README), belong
+  in the body of the signed-out shell, not in a pre-rendered header.
 - **Include the viewport meta tag**:
   `<meta name="viewport" content="width=device-width, initial-scale=1">`.
 - **If you toggle shells with `el.hidden`, add
@@ -190,14 +251,23 @@ the baseline for when there is no design.
 - **Disable, don't hide, on read-only documents.** When
   `doc.readOnly` is true, render the editor and share controls disabled
   with a `title` explaining why, rather than removing them. It covers
-  every reason this reader cannot write: a view-only grant, a view-only
-  share link, a historical-version preview, and a document still
-  loading. Re-read it in your `doc.subscribe` handler rather than
+  every reason this user cannot write: a view-only grant, a view-only
+  share link, a historical-version preview, a document still loading
+  or being prepared for editing, a file too large to edit
+  (`doc.atCapacity`), and a copy your app opened with `readOnly` or
+  `frozen`. Re-read it in your `doc.subscribe` handler rather than
   reading it once at bind: it also flips when someone withdraws the
-  reader's access while the document is open, which is what closes the
+  user's access while the document is open, which is what closes the
   editor at the moment writing stops working. Pair it with
   `Brass.onError`, where the sentence explaining a refused write
   arrives.
+- **Make each user action one Undo step.** Call
+  `void doc.createCheckpoint()` at the end of every action that edits
+  the document: on `pointerup` after a drag, after a command runs, after
+  a field commits. In a text editor, call it in `beforeinput`
+  whenever the coming edit starts a new step (see "Undo, checkpoints,
+  and version history" in the README), and leave the automatic interval
+  as it is.
 - **Name the next action in empty states.** "No document open. Use
   Open to pick or create one."
 - **Gate edit affordances on an open document.** When
@@ -225,7 +295,7 @@ the baseline for when there is no design.
   resting button-like affordance so it reads as clickable rather than
   as a heading.
 - **Wire presence by default, and wire both halves.** When
-  `doc.presence` is non-null (any open writable doc), publish your own
+  `doc.presence` is non-null (any live open), publish your own
   pointer / camera / selection state on every move AND render other
   participants' state in the working surface, not just an initials
   list in the header (the README's "Presence" section explains why
@@ -269,11 +339,13 @@ them. Drive each to completion rather than noting it and stopping:
   drive the sign-in: run `brass login`. In a local session it opens the
   human's browser to approve and completes on approval. On a headless
   box it prints a URL and short code the human approves from any device.
+  Copy both into the visible text of your reply, since most interfaces
+  collapse command output.
   Running it and getting the human through approval is your step. For CI
   the human supplies `BRASS_SERVICE_TOKEN` instead.
 - **A key for every service you declared.** An app that declares
   `services` in `brass-app.json` calls those hosts through Brass, which
-  holds the credential, and the credential comes from the provider's own
+  stores the credential, and the credential comes from the provider's own
   console. `brass publish` names each host still waiting and the page
   that takes its key, in the log and in `warnings` under `--json`. Give
   the human that line as it stands: it carries the host and a link
@@ -285,10 +357,17 @@ Once `brass status` reports a credential, publish:
 
 ```sh
 npm run build
-npx @brass-build/cli publish ./dist
+npx @brass-build/cli publish ./dist --name "My app"
 ```
 
-This deploys to `https://<slug>.onbrass.app`. Report the integration
+This deploys to `https://<slug>.onbrass.app`. If the app lets a visitor
+work without an account, declare `"access": { "create": "anyone" }` in
+`brass-app.json` and add `--gate off --visibility public`. Without
+`--gate off`, Brass asks every visitor to sign in before the app loads.
+Without `--visibility public`, a visitor with no account cannot create a
+document, and `Brass.session.error` carries the
+reason.
+Report the integration
 against this end state, and close out every item before you call it
 done:
 

package/CHANGELOG.md

@@ -6,6 +6,82 @@ and the package follows [semantic versioning](https://semver.org/spec/v2.0.0.htm
 While the version is below `1.0.0`, minor releases may introduce
 breaking changes.
 
+## 0.5.0
+
+### Breaking
+
+- `registerImporter` takes `(file) => { streams, report? }` in place of
+  `(source, doc) => void`. Return your records instead of writing them to a
+  document.
+- 0.5.0 removes `DocumentSourceStream` and `DocumentSourceBlob.streams`.
+- `doc.createCheckpoint()` resolves to `void`, and 0.5.0 removes
+  `DocumentCheckpoint`. Remove code that reads the result.
+
+### Added
+
+- Support for dashboards and other derived content
+  - `Brass.chooseInputs(families)` asks a user to select files, folders, or
+    projects. `Brass.chooseInput(families)` asks the user to pick a single
+    file.
+  - `doc.dependsOn(key, refs)` saves picked references in your document.
+  - `doc.subscribeInputDocuments(key, handlers)` calls your handlers as the
+    referenced files load, change or leave. See "Referencing other
+    documents" in the README.
+  - `Brass.documents.get(id)` returns a document's `family`, and
+    `member_of.chain` lists the folders and archives containing it.
+  - `inputs` in `brass-app.json` lists the schemas your app reads. The picker
+    offers files that match one of them.
+- Faster read-only opening
+  - `readOnly: true` on `Brass.openDocumentById` or `session.open` opens a
+    `ReadOnlyDocument`, for apps that only display documents. Large documents
+    load significantly faster, and unchanged ones reopen without downloading
+    again.
+  - `Brass.init(appId, { open: { readOnly: true } })` opens every session
+    document read-only. Documents the session creates still open editable.
+  - `frozen: true` opens a copy that ignores later edits, for reading many
+    documents at once. `doc.onChanged(cb)` reports a change, and
+    `doc.reload()` updates the same copy to the latest version.
+  - `doc.reopen()` switches an open document between editable, `readOnly` and
+    `frozen`, so a user can view first and edit later.
+- Optional trial use for signed-out users
+  - Signed-out users can create and open temporary documents, to try your app
+    before signing up. `doc.expiresAt` gives the expiry. Signing in from that
+    page keeps the document. See "Try before signing in" in the README.
+  - `access` in `brass-app.json` sets who can use your app. `create`
+    (`false`, `"signed-in"` or `"anyone"`) sets who can make new documents
+    (`"anyone"` needs a public app). Use `false` for an app that makes no
+    documents of its own. `open` (`"signed-in"` or `"anyone"`) sets who can
+    open a public link. A public app with its hosted load gate off and no
+    `create` lets signed-out users create documents. Set
+    `create: "signed-in"` to require a sign-in.
+- `shared_schemas` in `brass-app.json` defines a schema once for other fields
+  to refer to.
+- An `imports` entry can set its own `schema`, for imported files that differ
+  from your app's documents.
+- List handles have `get(index)`, so you can read one item by its position.
+  To walk every entry, map and ordered map handles have `entries()` and list
+  handles have `values()`.
+- `mutate(fn, { undoable: false })` keeps changes the user did not make out of
+  Undo.
+- `doc.importReport` returns the report your importer produced.
+
+### Changed
+
+- `callService` retries brief refusals itself and returns `rate_limited` if
+  they continue. Do not add your own immediate retry.
+- Call `registerImporter` at startup, so your importer is ready whenever an
+  import starts.
+
+### Deprecated
+
+- `read()` on `StoredMap` and `StoredList`. Use `keys()`, `entries()` or
+  `values()`.
+- `session.pick()` and `Brass.selectDocument()`. Use `session.open()` with no
+  id.
+- `documentOptions.readOnly`. Use the top-level `readOnly`, which returns a
+  `ReadOnlyDocument`.
+- `ordered()` on ordered map handles. Use `entries()`.
+
 ## 0.4.1
 
 ### Fixed
@@ -50,10 +126,10 @@ breaking changes.
 
 ### Fixed
 
-- A document that cannot reach Brass reports the failure instead of accepting
-  edits it cannot save. The first write calls `Brass.onError` and sets
-  `doc.readOnly`, and a later `mutate` throws. Disable your editor on
-  `doc.readOnly`.
+- A document opened with no live connection configured to write through
+  reports the failure instead of accepting edits it cannot save. The first
+  write calls `Brass.onError` and sets `doc.readOnly`, and a later `mutate`
+  throws. Disable your editor on `doc.readOnly`.
 - Reopening a document whose import did not finish runs the import again.
 - A `doc.stream(name)` open that fails closes its connection, instead of
   leaving it open for the life of the page.