balladeer 0.0.4 → 1.0.0

package/dist/copy.js

@@ -0,0 +1,459 @@
+/**
+ * The boundary copy, byte for byte. It is the same text in `docs/setup-boundary.md`
+ * and in the control plane's `/agent` instructions, and a packaging test compares
+ * all three, so what the command tells a person Balladeer can see cannot drift
+ * from what the documentation says.
+ *
+ * It describes the product's boundary, not one release's behaviour. What this
+ * release actually performs is stamped separately, outside this constant.
+ */
+export const BOUNDARY_COPY = `Balladeer never receives your code. It cannot read your repository: it holds no GitHub token,
+installs no GitHub App, and has no access to your files, tests, fixtures, logs, prompts, or
+transcripts.
+
+What it does receive is small and bounded. From you: the text of each promise a named person on your
+team approves, the numeric ids of your repository and its GitHub owner, and the name of its default
+branch. From CI: GitHub's signed statement of which repository, workflow, and run is reporting, and
+for each promise the run checked, the pass or fail outcome, the exact commit it checked, and content
+hashes of the verifier package and its output. Hashes cannot be turned back into your code or your
+test output.
+
+The verify job in your CI runs your tests with your checkout and has no Balladeer credential. A
+separate publish job, with no checkout, sends only those outcomes and hashes.
+
+This setup creates two credentials, both of which you control. Approving in the browser lets this
+session act as you to add repositories, connect your coding agent, connect CI, and propose promises;
+it cannot approve, activate, or remove anything. That session lasts a day, each use buys it another
+day, and it is gone seven days after you approved it however much you used it. The coding agent's
+own connection has no expiry: it lets the agent read the promises your team has approved, propose
+new ones, and propose replacing, retiring, excepting, or reassigning one you already have; every one
+of those waits for a named person to decide it. It can also carry out one of those acts for you, and
+only this way: you open a Balladeer page in your own browser, read what the act is, sign it off
+there, and read back the one-time code that page gives you. That code covers that one act on that
+one thing, once, and Balladeer records you as the person who took it and the connection as the
+messenger. Without a code you signed, the connection cannot approve, activate, grant, transfer,
+retire, or delete anything. You can revoke either one at any time in Balladeer, and the setup
+session also ends on its own.
+
+Adding the workflow puts a check on pull requests into your default branch. That check is advisory
+on Balladeer's side; whether it blocks a merge is your own branch protection.
+`;
+/**
+ * How a person gets a workspace to approve into, for an agent reading the
+ * setup instructions.
+ *
+ * The pairing page is one page doing two jobs, and only one of them was ever
+ * described: an agent whose person had no workspace read instructions that
+ * assumed there was one to join. The name can be carried to that page so the
+ * person does not retype it, and carrying it is all an agent may do. Creating a
+ * workspace is a person's act, so the copy says the flag pre-fills a form and
+ * says who presses the button, rather than leaving an agent to read a flag name
+ * and conclude it creates something.
+ *
+ * Byte for byte the same text as `AGENT_INSTRUCTIONS_JOIN_OR_CREATE` in the
+ * control plane, and a packaging test compares them: the page an agent fetches
+ * and the terminal it is reading cannot come to describe this differently.
+ */
+export const JOIN_OR_CREATE = `The pairing page joins an existing workspace or makes a new one. Somebody whose team already has
+a Balladeer workspace signs in and approves the code from the terminal. Somebody who is the first
+person from their team signs in, names a workspace, and clicks Create, and only then is there
+anything to approve into.
+
+You can save them the typing, and nothing else. Ask what the workspace should be called, then run
+\`balladeer setup --create-workspace "<name>"\` with the name they gave you. The pairing link this
+command prints then carries \`?create=<name>\`, which pre-fills that name in the create form on the
+pairing page. It fills the box and no more than that: the person signs in and clicks Create, and
+until they do there is no workspace. An agent never creates one, and Balladeer refuses the attempt
+whatever it was told in conversation. Never invent the name either. A workspace is named once and
+the whole team reads it.`;
+/**
+ * When a coding agent reads this repository's promises, and when it does not.
+ *
+ * The instruction it replaces said "retrieve by identity, never in bulk" and
+ * then left the choice of read to the agent, which in a repository holding a
+ * thousand promises means a session that opens by paging a catalog it has no
+ * question about. This says which read answers which situation, and names the
+ * one read that must never happen at session start.
+ *
+ * Byte for byte the same text in three carriers: the conventions block written
+ * into the customer's own instructions file, the instructions this server sends
+ * a host on initialize, and the `/agent` page. A packaging test compares them,
+ * because an agent that met one of the three and not the others would read the
+ * catalog on the strength of the carrier that was quiet about it.
+ */
+export const RETRIEVAL_SCOPE = `### Reading what is already agreed
+
+Retrieve by promise, and only when this session has a reason to. One repository here can hold a
+thousand agreed promises, and a plan built from whatever survived a truncated catalog read is worse
+than a plan built from none of it, because nothing tells you which half went missing.
+
+When a person gives you a promise id, expand exactly that one with get_promise and stop there. Every
+promise page carries a control that copies its id, so an id is what a person hands you when they
+mean a particular promise. Ask for one rather than searching for what they meant.
+
+Consult list_promises in two situations and no others. The person asks what this repository has
+promised, in which case page the index they asked for. Or the change you are about to make touches
+paths that carry promises, in which case give those paths to list_promises: it answers with the
+promises whose scope overlaps them, closest first, and with the few that name no path and so cover
+the whole repository. That answer is a selection rather than a page and does not continue with a
+cursor, so when the total beside it is larger than what you were handed, narrow the paths rather
+than asking for more.
+
+When you do not yet know which paths you are about to touch, do not call the index at all. Work from
+ids until you do, because a page you did not ask a question of is not about your change, and reading
+one as though it were is how a plan quietly misses the promise it breaks.
+
+To learn which paths those are, read \`paths\` on a list_promises answer you asked for
+without paths of your own. It is the set of
+repository paths this repository's promises are scoped to, deduplicated and bounded, with
+\`pathsTruncated\` saying whether there were more than the answer carries. Compare the files you are
+about to change against it. Nothing matching means there is nothing here to read, and saying so is a
+better answer than a page of promises about somewhere else.
+
+Never call get_promise_context at the start of a session. It answers the markers you give it, and
+before you know what you are changing there are no markers to give: what comes back is a slice of
+the catalog chosen by nothing. Call it once the work is in front of you, with that work's markers.
+
+Every one of these reads is bounded and none of them returns the whole catalog. Read the total
+beside the rows and the sentence in \`scope\` that says what the total is a total of, and when the
+total is larger than what you were handed, page or narrow rather than planning as though you had
+seen everything.`;
+/**
+ * The two things an agent offers in a connected repository without being asked
+ * for them, and starts neither of on its own.
+ *
+ * Both exist because the person cannot see what the agent can. A promise nobody
+ * is checking looks exactly like a promise that is protected until somebody
+ * opens the catalog, and a proposal sitting in a browser tab is a proposal
+ * nobody reads. Neither of these is a licence to act: the first is a sentence
+ * and a question, the second is a rendering of work already done. The capture
+ * style stays what it was, and nothing here proposes a promise nobody asked
+ * for.
+ *
+ * It sits inside `CONVENTIONS_BLOCK` rather than beside it, because the block
+ * is what reaches a session in the customer's own repository. The control
+ * plane's `/agent` page carries the same bytes under its own constant, and a
+ * packaging test compares them.
+ */
+export const SESSION_BEHAVIORS = `### Two things to offer without being asked
+
+At the start of any session in this repository, before you plan anything, ask list_promises for the
+promises nothing is checking yet that belong to the person you are working with: \`unverified\` true
+and \`mine\` true, which is one bounded read rather than the catalog. If it returns any, say so in one
+line and offer to build their verifiers now. Name each one by its one-sentence claim rather than by
+an id, so the person can see which behavior is unguarded. Ask the same tool for
+\`brokenSinceLastSeen\` true as well, and where that returns any, say in one line that those promises
+broke since they last looked, name each by its claim, and offer to fix them. Then wait for their
+answer. The offer is the whole of it, and never start building or repairing one because nobody said
+no.
+
+Theirs, and nobody else's. \`mine\` keeps the promises this person owns or agreed to, and a teammate's
+unguarded promise is that teammate's to hear about: a session that opens by reading out other
+people's unfinished work reads as an audit of them. \`brokenSinceLastSeen\` is that person's own by
+construction and needs no \`mine\` beside it. Drop \`mine\` when this person asks what the rest of the
+team has promised, and say whose promises you are showing them when you do.
+
+When you have proposed promises, show them here as well as there. Put each proposal in the
+conversation in full: its one-sentence claim, who it is for, when it applies and what must then be
+true, the numbered cases that must keep working and the ones that must be caught, and every question
+you left open. Then offer to finish the agreement from here, by asking for a sign-off, giving them
+the page it returns and taking the one-time code that page shows them, so the browser is needed only
+for signing. Give them the review link in the same message too, because some people would rather
+read it there and edit it before they agree.`;
+/**
+ * What a session may spend on reading, in three sentences.
+ *
+ * The bounded index says what one read may carry. This says how many reads
+ * there should be, which is the half no ceiling can enforce: an agent that
+ * pages the whole index and expands every row has obeyed every limit in the
+ * protocol and has still put the entire catalog in front of a model. So the
+ * budget is written where the agent reads it, beside the rule that makes it
+ * affordable: a row carries what it takes to rule its promise out, and an
+ * expansion is what you spend once a row could not.
+ *
+ * Three carriers say it, byte for byte: the block setup writes into the
+ * customer's own instructions file, the instructions the MCP server sends on
+ * initialize, and the page `/agent` serves. A packaging test holds them
+ * together.
+ */
+export const FETCH_BUDGET = `Fetch by id, and only for an id the person gave you or an index row whose paths match the change in
+front of you. Never enumerate the catalog. Never chain one fetch into the next to see the whole of
+something: when the rows do not settle it, narrow the filter rather than expanding another promise.`;
+/**
+ * What a coder must know before their editor opens a file inside a promise's
+ * own directory.
+ *
+ * A seal is broken by an ordinary edit, and the person who breaks one rarely
+ * meant to: a rename swept a directory, a formatter reached everything, a
+ * dependency upgrade rewrote an import. The cost lands on somebody else, who
+ * has to qualify the promise again before it protects anything. So this says
+ * three things in the order a coder needs them: those files are sealed, here is
+ * how to see which ones before you edit and before you push, and here is the
+ * single case where editing one is the right move.
+ *
+ * It sits inside `CONVENTIONS_BLOCK` rather than beside it, because the block
+ * is what reaches a session in the customer's own repository. The MCP server's
+ * tool guidance and the control plane's `/agent` page carry the same bytes
+ * under their own constants, and a packaging test compares all three.
+ */
+export const SEALED_FILES = `### Files that are sealed, and the one reason to edit one
+
+Every file under .continuity/promises/ is sealed. The promise that owns that directory records the
+exact bytes of each file in it, so editing one, adding one there, renaming one or deleting one
+breaks the seal. A promise whose seal is broken stops being checked, and it stays that way until a
+named person qualifies it again, which is their afternoon rather than your commit. Nothing in there
+is ordinary source: keep it out of refactors, formatting runs and dependency upgrades.
+
+Find out which directories are sealed before you plan an edit, not after. balladeer status lists
+them, and list_promises names a promise's sealed directory on its row once a verifier is bound to
+it. Then, before you push, run balladeer check-seals. It prints nothing and exits zero when your
+change touches no seal, and names the promise, its owner and its page when your change would break
+one.
+
+The one reason to edit a sealed file is to repair a verifier that can no longer run: something it
+imports moved, or the language it is written in changed under it. Never edit one to make a failing
+check pass. A check going red is the promise doing its job, and the repair for that belongs in the
+behavior it protects. A repair is not finished until the promise is sealed again with the runner
+this repository is pinned to. get_promise_setup carries that exact seal command, and balladeer
+check-seals prints it beside any promise it names.`;
+/**
+ * Which promises a change touches, measured rather than guessed.
+ *
+ * A promise's scope paths are what somebody typed when they agreed it, and they
+ * age the moment a module moves. The touch map is the measurement instead: the
+ * files each verifier actually executed, recorded on the customer's machine and
+ * sent nowhere. An agent that does not know the command exists goes on matching
+ * markers and never asks for the better answer sitting in the repository.
+ *
+ * The last paragraph is the whole reason the signal is named here. Whether the
+ * map is worth keeping is answerable only if the receipt says which fetches it
+ * caused, and no surface can infer that after the fact.
+ *
+ * Three carriers say it, byte for byte, and a packaging test holds them
+ * together.
+ */
+export const TOUCH_MAP_GUIDANCE = `Prefer the measurement over the markers. Where this repository has a touch map, \`balladeer affected
+<paths...>\` answers which promises ran the files in front of you, out of what each verifier actually
+executed the last time \`balladeer touch-map\` measured it. Both commands run on this machine and
+send Balladeer nothing, so you may name any path in the change.
+
+An answer marked stale was measured against a verifier that has changed since, so read it as the
+last thing anybody measured rather than as fact, and offer to run \`balladeer touch-map\` again.
+Where there is no map, where it does not name your paths, or where it reports a promise it could not
+measure, fall back to the paths on the index rows. The map narrows which promises are worth
+fetching. It never widens what you may read: the catalog is still never enumerated, and the fetch
+budget is unchanged.
+
+When a retrieval receipt asks why you read a row, the answer for one the map named is \`touch\`.`;
+/**
+ * The conventions block written between markers into this repository's agent
+ * instructions file. Fixed text, compared byte for byte by a test, because a
+ * block that drifts per run would rewrite a customer's committed file on every
+ * setup and the diff would say nothing.
+ */
+export const CONVENTIONS_BLOCK = `## Balladeer promises
+
+Before planning work in this repository, read the promises this team has already approved through
+the Balladeer MCP server. They are the behaviors a named person has agreed the software keeps, so
+your plan has to hold them, not just read them.
+
+${RETRIEVAL_SCOPE}
+
+Each index row carries what it takes to rule that promise out without fetching it: the repository,
+the paths it covers, its one-sentence claim, what protects it and why, and when anything last
+checked it.
+
+${TOUCH_MAP_GUIDANCE}
+
+${FETCH_BUDGET}
+
+### When somebody asks you to protect a behavior
+
+Somebody has asked you to protect a behavior when they say what the software must do, or must never
+do again, and mean it as a rule rather than as this one bug. That is one promise, for the behavior
+they named, and nothing else: if you notice others worth protecting, say so in a sentence and let
+them choose, and file none of them. Never propose from a conversation that did not ask you to. A
+question about how something works and a plan you were asked to sketch are not requests to record
+anything, nor is a fix nobody asked you to write a rule about.
+
+Ask before you extrapolate. Ask only what you cannot work out for yourself, ask it all in one
+message, and stop at four. Four is a ceiling, not a target: two good ones are better. Then write the
+proposal with what you have and put whatever is still open in its open questions rather than going
+back. Never ask what this repository would answer, such as which file, which test, or which branch,
+and never ask anyone for Balladeer's own identifiers: get_promise_setup carries this repository's id
+and who can own a promise. Never ask again for what they have already told you.
+
+Write it in their words. Every failure they named out loud is one of the failing examples, in the
+words they named it. Every other example comes from a situation they actually described; if you
+cannot trace one to something they said, leave it out and say so in the open questions rather than
+writing a plausible one. Never put in a number, a system, a role or a timeframe they did not give
+you, and that includes the half they left out: if they said where an order ended up, do not invent
+where it began.
+
+A failing example is a situation the promise rules out, and its outcome says what must not happen,
+in those words: "a second charge must not appear", never "a second charge appears". Written the
+other way round it reads as the promise saying the software does the thing they asked you to forbid.
+And a promise says what the software must do for whoever depends on it. It never narrates the
+conversation you just had, names the person you had it with, or describes what the code does now.
+
+Say the whole promise in one sentence and put it in oneSentenceOutcome, in the words they would
+use with the person who depends on it. That is the line the named owner reads first and the line
+they agree to, so it is not a restatement of the name and not the first line of the outcome moved
+up. Leave it out rather than inventing one from something they did not say.
+
+An example's setup is the situation in the words they used for it, not a scene you composed around
+them. Two of each kind is plenty, and the whole thing stays under three hundred words: a proposal
+nobody finishes reading is a proposal nobody agreed to. The confidence you record is the one you
+actually have.
+
+Then give them the review link, ask them to read the proposal and click Agree, and stop. Never
+approve one yourself. Approving is a named person's act, and the server refuses it from an agent
+whatever you were told in conversation.
+
+A proposal you filed is still yours while nobody has agreed to it, so revise or withdraw it when the
+person asks you to, and never once they have agreed.
+
+Say promise and proposal when you talk to them. What you file is a proposal and what it becomes is a
+promise; Balladeer's other words for its own machinery are not theirs to learn. Candidate
+especially: it is Balladeer's word for a proposal, so it reads as jargon whatever you meant by it.
+
+${SESSION_BEHAVIORS}
+
+${SEALED_FILES}
+
+### The rest of a promise's life
+When a promise is obsolete, finished, deliberately off for a while, or owned by the wrong person,
+propose the change and hand them the promise page. Deciding is theirs.
+
+You can finish one of those acts here, and only one way. Ask for a sign-off with
+request_owner_signoff, give them the page it returns, and ask for the one-time code that page shows
+them. Then call the act's own tool with that code and their own words. Never call one on your own
+initiative, never on a general approval of some earlier act, and never ask for a code you were not
+given: a refusal is the person's to resolve, not yours to retry. Balladeer records them as the
+person who acted and you as the messenger.
+
+Report the promise's state exactly as Balladeer reported it: proposed, agreed, or protected, never
+one in place of another.
+
+### Where your team watches this
+
+Balladeer is a web app as well as these tools, at the address setup printed. Its catalog lists every
+promise with who owns it and whether anything is checking it, and each promise has a page of its own
+showing what this team agreed the software must do and then every run that has checked it since,
+newest first, with the commit each one checked. Whenever there is a link to give, give the link
+rather than a summary of it: the page says what you would have said, and it stays true after this
+conversation has ended.
+
+Balladeer also has a Slack app, which a workspace administrator installs from workspace settings.
+Once it is installed, whoever owns a promise gets a direct message when theirs goes live and when a
+run on the default branch breaks it. Until somebody installs it, nothing is sent anywhere, so say it
+is available rather than saying they will be told.
+
+### Questions people ask
+
+Answer these when they come up. Where you do not know, say so and point at the address setup
+printed: a confident wrong answer about what a vendor can see is worse than no answer.
+
+What it does: it holds the behaviors this team has agreed the software must keep, and reports
+whether each one is still being kept, from this repository's own tests running in its own CI.
+
+What it sees: the text of each promise somebody approves, this repository's numeric ids and the name
+of its default branch, and from CI the pass or fail outcome, the commit checked, and content hashes.
+Never the code, the tests, the fixtures, the logs, the prompts, or the transcripts.
+
+What stopping costs: nothing that matters to their tests. The verifier package, its fixtures and the
+workflow file are theirs, in their repository, running in their CI, and disconnecting changes none
+of them. An administrator can download everything Balladeer holds at any time from workspace
+settings, and disconnecting hands them that same download in the response that ends access.
+
+Who can approve one: the named person who owns it, in their own browser. Not an administrator on
+their behalf, and never you.
+
+Whether it blocks a merge: no. The check is advisory on Balladeer's side, and their own branch
+protection is what decides whether a failing check stops anything.
+
+Who can invite people and change setup: a workspace administrator. A contributor can read the
+workspace and propose promises, and a viewer can read it. If somebody asks you to add a teammate,
+invite_teammate returns the page an administrator sends the invitation from, with the address filled
+in for them to read. The tool sends nothing itself: an administrator presses Send.`;
+/**
+ * How an agent turns a repository that has just been connected into a catalog a
+ * person can read. Setup's last step prints it, and the control plane's `/agent`
+ * page serves it byte for byte, so the instruction a connected agent reads on
+ * the page cannot drift from the one the command prints in the terminal.
+ *
+ * The runnable invocation is deliberately not in here. Only the server knows
+ * whether the package is published, and a playbook carrying a literal command
+ * would either name a registry version npm does not have or name somebody
+ * else's package. Each carrier prints that one line underneath this text.
+ *
+ * The capture rules this leans on are `CONVENTIONS_BLOCK`'s, not a second set:
+ * one promise per behavior, the person's own words, and never an agent
+ * approving anything. This says how to find the behaviors in a repository
+ * nobody has interviewed yet; that says how to write one down.
+ *
+ * The seam that is not shipped: a fifth source, the person's own local agent
+ * transcripts, would be the richest of all, because a behavior somebody argued
+ * about in a session is a behavior they care about. It is dark on purpose here.
+ * Reading it means walking files Balladeer promises never to receive, so
+ * shipping it needs three things this release does not have: the person's
+ * explicit spoken yes each time, a bounded extraction that never carries a line
+ * of a transcript off the machine, and the privacy test extended to plant a
+ * sentinel in every host's transcript directory. Until then the text below tells
+ * the agent not to read them, which is the visible half of the same seam:
+ * nothing quietly starts doing it.
+ */
+export const DISCOVERY_PLAYBOOK = `## Discover this repository's promises
+
+This repository is connected and holds no promises yet. Work the four sources below in order and
+hand back between five and ten promises this repository already keeps. Stop at ten however much you
+find: a person has to read every one of them, and eleven is where reading turns into skimming.
+
+1. The repository's own tests. A test that has been green for months is a behavior somebody already
+   decided matters. Read the test names and the assertions rather than the implementation.
+2. Merged pull requests of the last 90 days. Read the ones whose title or body says what had to keep
+   working, and the review comments that argued for it.
+3. Guarantee sentences in the documentation. The README, the docs directory, and the comments that
+   say always, never, must, or is guaranteed to. Those sentences are promises somebody already wrote
+   down in prose.
+4. Incidents and reverts. A revert commit, a hotfix, a postmortem note. A behavior that broke once
+   and was repaired on purpose is the behavior most worth protecting.
+
+Do not read the person's local agent transcripts, and do not offer to. They are not a source in this
+release, and Balladeer never receives them.
+
+For each promise you propose:
+
+- One promise per behavior. Two behaviors found in one source are two proposals, not one proposal
+  with two outcomes.
+- One passing example and one failing example, both drawn from the source you found it in. The
+  passing example is the case the source shows working; the failing example is the case the source
+  shows being caught, or the regression the revert repaired. Write both in the source's own words
+  rather than in words of your own.
+- One provenance sentence, precise enough for a person to check it without asking you: the test file
+  and the test's name, the pull request number, the document and its heading, or the commit that
+  reverted it. Put that sentence first in explicitIntent.
+- Never propose a promise this repository does not keep. A source saying a behavior should exist,
+  where nothing in the repository does it, is a wish rather than a promise. Leave it out, and tell
+  the person you left it out.
+- Anything you could not settle from the source goes in unresolvedQuestions. Never fill an unknown
+  in plausibly: an invented answer is the one thing a person cannot catch by reading.
+- One confidence number from 0 to 1, saying how sure you are that this is a behavior the repository
+  actually keeps and that you have described it as its source describes it. Nine promises from nine
+  sources are not nine equally certain readings, and the person reading them is entitled to know
+  which one you were least sure of. Never write 1 to get past the check.
+
+Write them all into one file, an object with a promises array, each entry shaped exactly as one
+proposal file:
+
+{"promises": [{"explicitIntent": "...", "teachBack": {"confidence": 0.9, "meaning": {"title": "..."}}}]}
+
+An entry carries explicitIntent and teachBack, and inside teachBack only meaning, confidence,
+unresolvedQuestions, and proposedOwnerId. Anything else is refused on this machine before the file
+leaves it, and one bad entry means not one of them is sent.
+
+Every promise in the file is proposed as owned by whoever ran setup, and waits for that person. The
+command prints one link that opens all of them at once. Give the person that link and ask them to
+read each promise and click Agree. Nothing you can run agrees to one.
+
+File the whole catalog in one go with the discover subcommand, naming that file:`;

package/dist/currency.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Whether this copy is the newest one, answered by the server on every call.
+ *
+ * Legacy customers ran a months-old command because nothing ever told them
+ * otherwise: the invocation in their config named a version, the version kept
+ * working, and a working thing announces nothing. So the server stamps what the
+ * newest published version is on every answer it gives a program, and this
+ * module is where the command notices.
+ *
+ * It is a nag, never a refusal. Refusing is the floor's job, and the floor is
+ * the server's to enforce; a copy that is merely behind still works, and a
+ * command that stopped working the day after a publish would be worse than the
+ * problem it fixes.
+ */
+export declare const CLI_NEWEST_HEADER = "x-balladeer-cli-newest";
+export declare const CLI_FLOOR_HEADER = "x-balladeer-cli-minimum";
+export declare const CLI_ADVICE_HEADER = "x-balladeer-cli-advice";
+/**
+ * Reads the version signals off one response.
+ *
+ * The comparison is this command's own, against the number the server named.
+ * The server's sentence is used for the wording when it sent one, because only
+ * the server knows whether the registry form or the checkout form is the line a
+ * person can actually run, but the decision to say anything at all is made here
+ * against a version this program knows for certain: its own.
+ */
+export declare function noteServerVersion(headers: Headers): void;
+/** The one line this run prints about itself, or nothing when it is current. */
+export declare function updateNotice(): string | undefined;
+/** For tests, and for a process that runs more than one command. */
+export declare function resetUpdateNotice(): void;

package/dist/currency.js

@@ -0,0 +1,72 @@
+import { CLI_VERSION } from "./wire.js";
+/**
+ * Whether this copy is the newest one, answered by the server on every call.
+ *
+ * Legacy customers ran a months-old command because nothing ever told them
+ * otherwise: the invocation in their config named a version, the version kept
+ * working, and a working thing announces nothing. So the server stamps what the
+ * newest published version is on every answer it gives a program, and this
+ * module is where the command notices.
+ *
+ * It is a nag, never a refusal. Refusing is the floor's job, and the floor is
+ * the server's to enforce; a copy that is merely behind still works, and a
+ * command that stopped working the day after a publish would be worse than the
+ * problem it fixes.
+ */
+export const CLI_NEWEST_HEADER = "x-balladeer-cli-newest";
+export const CLI_FLOOR_HEADER = "x-balladeer-cli-minimum";
+export const CLI_ADVICE_HEADER = "x-balladeer-cli-advice";
+/**
+ * How much of the server's sentence may be printed. It is one line from the
+ * control plane this machine paired with, and a ceiling means a server that
+ * answers with pages of text cannot turn a terminal into its own output.
+ */
+const ADVICE_LIMIT = 300;
+const VERSION = /^\d{1,4}\.\d{1,4}\.\d{1,4}$/;
+let notice;
+function older(left, right) {
+    const [a, b] = [left.split(".").map(Number), right.split(".").map(Number)];
+    for (let index = 0; index < 3; index += 1) {
+        const difference = a[index] - b[index];
+        if (difference !== 0)
+            return difference < 0;
+    }
+    return false;
+}
+/** Control characters stripped, length bounded: a server writes words, not terminal control. */
+function bounded(value) {
+    return value
+        .replace(/[\u0000-\u001f\u007f]/g, " ")
+        .trim()
+        .slice(0, ADVICE_LIMIT);
+}
+/**
+ * Reads the version signals off one response.
+ *
+ * The comparison is this command's own, against the number the server named.
+ * The server's sentence is used for the wording when it sent one, because only
+ * the server knows whether the registry form or the checkout form is the line a
+ * person can actually run, but the decision to say anything at all is made here
+ * against a version this program knows for certain: its own.
+ */
+export function noteServerVersion(headers) {
+    const newest = headers.get(CLI_NEWEST_HEADER)?.trim();
+    if (newest === undefined || !VERSION.test(newest))
+        return;
+    if (!older(CLI_VERSION, newest))
+        return;
+    const advice = headers.get(CLI_ADVICE_HEADER);
+    const line = advice === null ? "" : bounded(advice);
+    notice =
+        line === ""
+            ? `A newer Balladeer is available (${newest}; this is ${CLI_VERSION}). Run setup --refresh, or restart this session, before continuing.`
+            : line;
+}
+/** The one line this run prints about itself, or nothing when it is current. */
+export function updateNotice() {
+    return notice;
+}
+/** For tests, and for a process that runs more than one command. */
+export function resetUpdateNotice() {
+    notice = undefined;
+}

package/dist/gh.d.ts

@@ -0,0 +1,80 @@
+export type CommandResult = Readonly<{
+    ok: boolean;
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}>;
+export declare function runCommand(file: string, args: readonly string[], options?: Readonly<{
+    cwd?: string;
+    timeoutMs?: number;
+    /**
+     * The whole environment the child gets, when the caller needs to name one.
+     * Left out, the child inherits this process's, which is what every other
+     * call here wants.
+     */
+    env?: NodeJS.ProcessEnv;
+}>): Promise<CommandResult>;
+export type RepositoryFacts = Readonly<{
+    githubRepositoryId: string;
+    githubOwnerId: string;
+    defaultBranch: string;
+    /** Whether the person can push to, or administer, this repository. */
+    canWrite: boolean;
+    /** True when the facts came from an authenticated read. */
+    authenticated: boolean;
+}>;
+export type RepositoryLookup = Readonly<{
+    kind: "found";
+    facts: RepositoryFacts;
+}>
+/**
+ * Why the read did not happen, and what the person does about it. The two
+ * travel together because they came apart once: a developer with no `gh`
+ * installed at all was told to run `gh auth login`, which is a command they do
+ * not have.
+ */
+ | Readonly<{
+    kind: "unavailable";
+    reason: string;
+    next: string;
+}>;
+export declare function ghAvailable(): Promise<boolean>;
+export declare function ghSignedIn(): Promise<boolean>;
+/**
+ * Reads a repository's immutable ids, its default branch, and what the person
+ * may do with it.
+ *
+ * The unauthenticated read is deliberately NOT a fallback for enrolling. It
+ * proves nothing about who is asking, so a workspace could otherwise end up
+ * holding an enrollment, a CI identity, and eventually a protection claim about
+ * a repository nobody in it controls. It exists only so the command can render
+ * the do-it-by-hand block with real values.
+ */
+export declare function readRepositoryFacts(repository: string): Promise<RepositoryLookup>;
+/** The public read, for rendering the fallback block only. */
+export declare function readPublicRepositoryFacts(repository: string): Promise<RepositoryLookup>;
+/**
+ * What this machine's own GitHub access can see, so an agent has a list to
+ * offer instead of asking a person to type repository names from memory.
+ *
+ * Read through the person's own `gh`, exactly as every other GitHub read here
+ * is: Balladeer holds no GitHub token and this list never leaves the machine
+ * unless a person picks something off it. Archived repositories are dropped,
+ * because enrolling one records a claim about a repository nobody is going to
+ * push to again.
+ */
+export type VisibleRepository = Readonly<{
+    repository: string;
+    canWrite: boolean;
+}>;
+/**
+ * The repositories one GitHub account or organization holds, newest first.
+ *
+ * `owner` empty means the signed-in account's own. A refusal is an empty list
+ * rather than an error: this is a convenience for offering a choice, and a
+ * person who cannot list an organization can still name a repository by hand.
+ */
+export declare function listVisibleRepositories(owner: string | undefined, limit?: number): Promise<readonly VisibleRepository[]>;
+/** The signed-in GitHub account's login, or nothing. */
+export declare function ghLogin(): Promise<string | undefined>;
+export declare function setRepositoryVariable(repository: string, name: string, value: string): Promise<CommandResult>;