balladeer 0.0.5 → 1.0.1

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/desktop-config.d.ts

@@ -0,0 +1,85 @@
+import { type StdioMcpEntry } from "./mcp-config.js";
+/** The file the Claude desktop app reads its stdio servers out of, on every platform that has one. */
+export declare const DESKTOP_CONFIG_FILE = "claude_desktop_config.json";
+/**
+ * Where that file lives, or why this machine has no such place.
+ *
+ * Two platforms are documented and both are handled: macOS keeps it under
+ * `Library/Application Support/Claude`, Windows under `%APPDATA%\Claude`.
+ * Claude desktop is published for those two and no others, so every other
+ * platform is told so by name rather than written to on a guess. A person
+ * running an unofficial build, or a Windows install whose packaging redirects
+ * that directory, points `BALLADEER_CLAUDE_DESKTOP_CONFIG` at the file itself
+ * and this writes exactly there.
+ */
+export type DesktopLocation = Readonly<{
+    kind: "path";
+    path: string;
+    directory: string;
+}> | Readonly<{
+    kind: "unsupported";
+    platform: string;
+    reason: string;
+}>;
+export declare function desktopConfigLocation(environment?: NodeJS.ProcessEnv, platform?: string): DesktopLocation;
+/**
+ * One key per repository, named after the repository.
+ *
+ * The desktop app has no notion of a project: every server in that file is
+ * loaded into every chat. A person who plans work in two repositories therefore
+ * has two of our servers running at once, and the only thing that tells them
+ * apart in the app's own connector list is the key. `balladeer-owner-name` is
+ * that name. A directory whose GitHub origin this command could not read has no
+ * name to use, so the key falls back to the repository's own id, which is unique
+ * by construction and still tells two entries apart.
+ */
+export declare function desktopServerKey(repositoryName: string, repositoryId: string): string;
+/**
+ * The entry the desktop app can actually start, which is not the one a coding
+ * agent gets.
+ *
+ * Claude desktop launches a stdio server from the application rather than from a
+ * login shell, with a minimal PATH carrying none of the places a developer's
+ * node lives: nvm, volta, asdf, Homebrew, fnm. So `node` and `npx` both resolve
+ * to nothing there, and what a person gets instead of a server is a line in a
+ * log file nobody opens. This names the interpreter running setup by its
+ * absolute path and this command's own entry point by its absolute path, so the
+ * entry needs no PATH at all.
+ *
+ * The environment is written for the same reason. The forwarder reads the bearer
+ * out of this machine's credential store, and where that store is depends on a
+ * variable the desktop app never inherits, so the resolved directory goes into
+ * the entry rather than being left to a shell that is not there. It is a path
+ * and never a secret: the credential itself stays in the store, mode 600.
+ */
+export declare function desktopStdioEntry(repositoryId: string, environment?: NodeJS.ProcessEnv, controlPlane?: string, nodePath?: string, entryPath?: string): StdioMcpEntry;
+export type DesktopMergeResult = Readonly<{
+    kind: "written";
+    changed: boolean;
+    path: string;
+    key: string;
+}> | Readonly<{
+    kind: "absent";
+    directory: string;
+    reason: string;
+}> | Readonly<{
+    kind: "refused";
+    reason: string;
+    block: string;
+}>;
+export declare function desktopBlock(key: string, entry: StdioMcpEntry): string;
+/**
+ * Merges our entry into the desktop app's configuration, or refuses.
+ *
+ * Everything already in that file stays in it. Other people's servers are other
+ * people's servers, and so is every top-level key beside `mcpServers`, which is
+ * where the app keeps settings this command knows nothing about. An unparseable
+ * file is never overwritten, and a key of ours holding somebody else's server is
+ * never replaced: the block is printed and a person decides.
+ *
+ * The key is found by what the entry says rather than by what it is called. An
+ * entry of ours already bound to this repository is rewritten where it sits,
+ * whatever it was named, so a repository renamed on GitHub does not quietly
+ * acquire a second server that starts alongside the first.
+ */
+export declare function mergeDesktopConfig(location: DesktopLocation, key: string, entry: StdioMcpEntry, repositoryId: string, controlPlane: string): DesktopMergeResult;

package/dist/desktop-config.js

@@ -0,0 +1,217 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { entryRepositoryId, isOurEntry, writeJsonAtomically, } from "./mcp-config.js";
+import { checkoutEntryPath } from "./release.js";
+import { configHome } from "./store.js";
+import { DEFAULT_CONTROL_PLANE } from "./wire.js";
+/** The file the Claude desktop app reads its stdio servers out of, on every platform that has one. */
+export const DESKTOP_CONFIG_FILE = "claude_desktop_config.json";
+export function desktopConfigLocation(environment = process.env, platform = process.platform) {
+    const override = environment.BALLADEER_CLAUDE_DESKTOP_CONFIG?.trim();
+    if (override !== undefined && override.length > 0) {
+        // An override that is not absolute would be resolved against whatever
+        // directory this command happens to have been started in, which is never
+        // the directory the person meant.
+        return isAbsolute(override)
+            ? { kind: "path", path: override, directory: parentOf(override) }
+            : {
+                kind: "unsupported",
+                platform,
+                reason: `BALLADEER_CLAUDE_DESKTOP_CONFIG is set to ${override}, which is not an absolute path, so I did not guess what it meant.`,
+            };
+    }
+    const home = homeOf(environment);
+    if (platform === "darwin") {
+        if (home === undefined)
+            return noHome(platform);
+        const directory = join(home, "Library", "Application Support", "Claude");
+        return { kind: "path", path: join(directory, DESKTOP_CONFIG_FILE), directory };
+    }
+    if (platform === "win32") {
+        const appData = environment.APPDATA?.trim();
+        const roaming = appData !== undefined && appData.length > 0
+            ? appData
+            : home === undefined
+                ? undefined
+                : join(home, "AppData", "Roaming");
+        if (roaming === undefined)
+            return noHome(platform);
+        const directory = join(roaming, "Claude");
+        return { kind: "path", path: join(directory, DESKTOP_CONFIG_FILE), directory };
+    }
+    return {
+        kind: "unsupported",
+        platform,
+        reason: `Claude desktop is published for macOS and Windows, and this machine reports ${platform}, so there is no ${DESKTOP_CONFIG_FILE} here to write. If you run an unofficial build, set BALLADEER_CLAUDE_DESKTOP_CONFIG to the absolute path of its ${DESKTOP_CONFIG_FILE} and run this again.`,
+    };
+}
+/**
+ * The home directory this environment names, and never the one the operating
+ * system would name instead.
+ *
+ * Asking the OS whose home this is would be a second source, and it answers for
+ * the account the process runs under rather than for the environment it was
+ * handed. A command given a bounded environment on purpose, which is what the
+ * tests hand it and what a service account hands it, would reach past that
+ * environment and write into a real person's chat client. So an environment that
+ * names no home is an answer: this run cannot tell where Claude desktop's
+ * configuration is, and it says so rather than guessing.
+ */
+function homeOf(environment) {
+    for (const value of [environment.HOME, environment.USERPROFILE]) {
+        const trimmed = value?.trim();
+        if (trimmed !== undefined && trimmed.length > 0)
+            return trimmed;
+    }
+    return undefined;
+}
+function noHome(platform) {
+    return {
+        kind: "unsupported",
+        platform,
+        reason: `This process was given no HOME, so I could not tell where Claude desktop keeps ${DESKTOP_CONFIG_FILE} and did not guess. Set BALLADEER_CLAUDE_DESKTOP_CONFIG to its absolute path, or run this from a shell that sets HOME.`,
+    };
+}
+function parentOf(path) {
+    const at = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+    return at <= 0 ? path : path.slice(0, at);
+}
+/**
+ * One key per repository, named after the repository.
+ *
+ * The desktop app has no notion of a project: every server in that file is
+ * loaded into every chat. A person who plans work in two repositories therefore
+ * has two of our servers running at once, and the only thing that tells them
+ * apart in the app's own connector list is the key. `balladeer-owner-name` is
+ * that name. A directory whose GitHub origin this command could not read has no
+ * name to use, so the key falls back to the repository's own id, which is unique
+ * by construction and still tells two entries apart.
+ */
+export function desktopServerKey(repositoryName, repositoryId) {
+    const cleaned = repositoryName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    const usable = cleaned.length > 0 && cleaned !== "unknown-unknown" ? cleaned : repositoryId.toLowerCase();
+    return `balladeer-${usable}`.slice(0, 100).replace(/-+$/, "");
+}
+/**
+ * The entry the desktop app can actually start, which is not the one a coding
+ * agent gets.
+ *
+ * Claude desktop launches a stdio server from the application rather than from a
+ * login shell, with a minimal PATH carrying none of the places a developer's
+ * node lives: nvm, volta, asdf, Homebrew, fnm. So `node` and `npx` both resolve
+ * to nothing there, and what a person gets instead of a server is a line in a
+ * log file nobody opens. This names the interpreter running setup by its
+ * absolute path and this command's own entry point by its absolute path, so the
+ * entry needs no PATH at all.
+ *
+ * The environment is written for the same reason. The forwarder reads the bearer
+ * out of this machine's credential store, and where that store is depends on a
+ * variable the desktop app never inherits, so the resolved directory goes into
+ * the entry rather than being left to a shell that is not there. It is a path
+ * and never a secret: the credential itself stays in the store, mode 600.
+ */
+export function desktopStdioEntry(repositoryId, environment = process.env, controlPlane, nodePath = process.execPath, entryPath = checkoutEntryPath()) {
+    const env = { BALLADEER_CONFIG_HOME: configHome(environment) };
+    // Only when it is not the default. A deployment nobody named is the one the
+    // forwarder already reaches on its own, and writing it down would pin an
+    // address that a later release moves.
+    if (controlPlane !== undefined && controlPlane !== DEFAULT_CONTROL_PLANE) {
+        env.BALLADEER_CONTROL_PLANE = controlPlane;
+    }
+    return { command: nodePath, args: [entryPath, "mcp", "--repository", repositoryId], env };
+}
+export function desktopBlock(key, entry) {
+    return JSON.stringify({ mcpServers: { [key]: entry } }, null, 2);
+}
+/**
+ * Merges our entry into the desktop app's configuration, or refuses.
+ *
+ * Everything already in that file stays in it. Other people's servers are other
+ * people's servers, and so is every top-level key beside `mcpServers`, which is
+ * where the app keeps settings this command knows nothing about. An unparseable
+ * file is never overwritten, and a key of ours holding somebody else's server is
+ * never replaced: the block is printed and a person decides.
+ *
+ * The key is found by what the entry says rather than by what it is called. An
+ * entry of ours already bound to this repository is rewritten where it sits,
+ * whatever it was named, so a repository renamed on GitHub does not quietly
+ * acquire a second server that starts alongside the first.
+ */
+export function mergeDesktopConfig(location, key, entry, repositoryId, controlPlane) {
+    const block = desktopBlock(key, entry);
+    if (location.kind === "unsupported") {
+        return { kind: "refused", reason: location.reason, block };
+    }
+    // The app creates its own directory the first time it runs. Creating one it
+    // never made would leave a configuration file behind for an application that
+    // is not installed, and the person would read "connected" about a chat client
+    // they do not have.
+    if (!existsSync(location.directory)) {
+        return {
+            kind: "absent",
+            directory: location.directory,
+            reason: `Claude desktop was not found on this machine: ${location.directory} does not exist, so I wrote no ${DESKTOP_CONFIG_FILE}. Install Claude desktop and open it once, then run this again.`,
+        };
+    }
+    let existing = "";
+    try {
+        existing = readFileSync(location.path, "utf8");
+    }
+    catch {
+        writeJsonAtomically(location.path, `${block}\n`);
+        return { kind: "written", changed: true, path: location.path, key };
+    }
+    let parsed;
+    try {
+        const value = JSON.parse(existing);
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            throw new Error("not an object");
+        }
+        parsed = value;
+    }
+    catch {
+        return {
+            kind: "refused",
+            reason: `Claude desktop's ${DESKTOP_CONFIG_FILE} could not be parsed; I did not change it.`,
+            block,
+        };
+    }
+    const raw = parsed.mcpServers;
+    if (raw !== undefined && (raw === null || typeof raw !== "object" || Array.isArray(raw))) {
+        return {
+            kind: "refused",
+            reason: `Claude desktop's ${DESKTOP_CONFIG_FILE} has an mcpServers value that is not a set of servers; I did not change it.`,
+            block,
+        };
+    }
+    const servers = raw === undefined ? {} : { ...raw };
+    const target = ourKeyFor(servers, repositoryId, controlPlane) ?? key;
+    const current = servers[target];
+    if (current !== undefined && !isOurEntry(current, controlPlane)) {
+        return {
+            kind: "refused",
+            reason: `Claude desktop's ${DESKTOP_CONFIG_FILE} already has an entry named ${target} that is not this workspace's server; I did not change it.`,
+            block: desktopBlock(target, entry),
+        };
+    }
+    servers[target] = entry;
+    const next = `${JSON.stringify({ ...parsed, mcpServers: servers }, null, 2)}\n`;
+    if (next === existing) {
+        return { kind: "written", changed: false, path: location.path, key: target };
+    }
+    writeJsonAtomically(location.path, next);
+    return { kind: "written", changed: true, path: location.path, key: target };
+}
+/** The key already carrying our server for this repository, whatever it is called. */
+function ourKeyFor(servers, repositoryId, controlPlane) {
+    for (const [name, value] of Object.entries(servers)) {
+        if (!isOurEntry(value, controlPlane))
+            continue;
+        if (entryRepositoryId(value) === repositoryId)
+            return name;
+    }
+    return 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>;

package/dist/gh.js

@@ -0,0 +1,188 @@
+import { execFile } from "node:child_process";
+/**
+ * The person's own GitHub access, used through the tool they already signed in
+ * to. Balladeer holds no GitHub token and this command never sends one anywhere.
+ *
+ * Every call goes through `execFile` with an argument array, never a shell, so
+ * nothing here can be turned into a command by a repository name. Standard error
+ * is captured rather than inherited, because a `gh` failure has to become one
+ * plain sentence with a next action rather than provider noise in the middle of
+ * a step.
+ */
+const TIMEOUT_MS = 20_000;
+export function runCommand(file, args, options = {}) {
+    return new Promise((done) => {
+        execFile(file, [...args], {
+            ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+            ...(options.env === undefined ? {} : { env: { ...options.env } }),
+            timeout: options.timeoutMs ?? TIMEOUT_MS,
+            maxBuffer: 4 * 1024 * 1024,
+            windowsHide: true,
+        }, (error, stdout, stderr) => {
+            const code = error === null ? 0 : typeof error.code === "number" ? error.code : 1;
+            done({
+                ok: error === null,
+                code,
+                stdout: String(stdout),
+                // Bounded: a refusal is a sentence, never a page of output.
+                stderr: String(stderr).trim().slice(0, 500),
+            });
+        });
+    });
+}
+function readFacts(raw, authenticated) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    const id = typeof parsed.id === "number" ? String(parsed.id) : undefined;
+    const ownerId = typeof parsed.owner?.id === "number" ? String(parsed.owner.id) : undefined;
+    const branch = typeof parsed.default_branch === "string" ? parsed.default_branch : undefined;
+    if (!id || !ownerId || !branch)
+        return undefined;
+    // GitHub returns `permissions` only for an authenticated request, so its
+    // absence is exactly the case where nothing was proved about the caller.
+    const canWrite = parsed.permissions?.admin === true || parsed.permissions?.push === true;
+    return {
+        githubRepositoryId: id,
+        githubOwnerId: ownerId,
+        defaultBranch: branch,
+        canWrite,
+        authenticated,
+    };
+}
+export async function ghAvailable() {
+    return (await runCommand("gh", ["--version"])).ok;
+}
+export async function ghSignedIn() {
+    return (await runCommand("gh", ["auth", "status"])).ok;
+}
+/**
+ * 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 async function readRepositoryFacts(repository) {
+    if (await ghAvailable()) {
+        if (!(await ghSignedIn())) {
+            return {
+                kind: "unavailable",
+                reason: "gh is installed but not signed in",
+                next: "Run `gh auth login`, then run this command again.",
+            };
+        }
+        const answer = await runCommand("gh", ["api", `repos/${repository}`]);
+        if (answer.ok) {
+            const facts = readFacts(answer.stdout, true);
+            if (facts)
+                return { kind: "found", facts };
+            return {
+                kind: "unavailable",
+                reason: "GitHub's answer did not carry the repository's ids",
+                next: "Check that the name is right and that GitHub is reachable, then run this command again.",
+            };
+        }
+        return {
+            kind: "unavailable",
+            reason: answer.stderr || `gh could not read repos/${repository}`,
+            next: `Check that ${repository} exists and that your GitHub account can see it, then run this command again.`,
+        };
+    }
+    return {
+        kind: "unavailable",
+        reason: "the GitHub CLI is not installed",
+        next: "Install the GitHub CLI from https://cli.github.com, sign in with `gh auth login`, then run this command again.",
+    };
+}
+/**
+ * The public read is a display convenience with no next action of its own: the
+ * caller is already printing the by-hand block, and this only fills its values.
+ */
+const PUBLIC_NEXT = "Add the repository by hand instead.";
+/** The public read, for rendering the fallback block only. */
+export async function readPublicRepositoryFacts(repository) {
+    let response;
+    try {
+        response = await fetch(`https://api.github.com/repos/${repository}`, {
+            headers: { accept: "application/vnd.github+json" },
+            redirect: "manual",
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+    }
+    catch {
+        return { kind: "unavailable", reason: "GitHub could not be reached", next: PUBLIC_NEXT };
+    }
+    if (!response.ok) {
+        return {
+            kind: "unavailable",
+            reason: `GitHub answered ${response.status}`,
+            next: PUBLIC_NEXT,
+        };
+    }
+    const facts = readFacts(await response.text(), false);
+    return facts === undefined
+        ? {
+            kind: "unavailable",
+            reason: "GitHub's answer did not carry the repository's ids",
+            next: PUBLIC_NEXT,
+        }
+        : { kind: "found", facts };
+}
+const WRITE_PERMISSIONS = new Set(["ADMIN", "MAINTAIN", "WRITE"]);
+function readRepositoryList(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const rows = [];
+    for (const entry of parsed) {
+        const name = typeof entry?.nameWithOwner === "string" ? entry.nameWithOwner : undefined;
+        if (name === undefined || entry.isArchived === true)
+            continue;
+        const permission = typeof entry.viewerPermission === "string" ? entry.viewerPermission.toUpperCase() : "";
+        rows.push({ repository: name, canWrite: WRITE_PERMISSIONS.has(permission) });
+    }
+    return rows;
+}
+/**
+ * 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 async function listVisibleRepositories(owner, limit = 100) {
+    const answer = await runCommand("gh", [
+        "repo",
+        "list",
+        ...(owner === undefined ? [] : [owner]),
+        "--limit",
+        String(limit),
+        "--no-archived",
+        "--json",
+        "nameWithOwner,isArchived,viewerPermission",
+    ]);
+    return answer.ok ? readRepositoryList(answer.stdout) : [];
+}
+/** The signed-in GitHub account's login, or nothing. */
+export async function ghLogin() {
+    const answer = await runCommand("gh", ["api", "user", "--jq", ".login"]);
+    const login = answer.stdout.trim();
+    return answer.ok && /^[A-Za-z0-9-]{1,39}$/.test(login) ? login : undefined;
+}
+export async function setRepositoryVariable(repository, name, value) {
+    return runCommand("gh", ["variable", "set", name, "--repo", repository, "--body", value]);
+}