balladeer 0.0.4 → 1.0.0

package/dist/mcp-config.d.ts

@@ -0,0 +1,99 @@
+export declare const MCP_CONFIG_FILE = ".mcp.json";
+export type StdioMcpEntry = Readonly<{
+    command: string;
+    args: readonly string[];
+    env?: Readonly<Record<string, string>>;
+}>;
+export type HttpMcpEntry = Readonly<{
+    url: string;
+    headers: Readonly<Record<string, string>>;
+}>;
+export type McpEntry = StdioMcpEntry | HttpMcpEntry;
+export type MergeResult = Readonly<{
+    kind: "written";
+    changed: boolean;
+}> | Readonly<{
+    kind: "refused";
+    reason: string;
+    block: string;
+}>;
+/**
+ * The entry this command writes: this command's own stdio forwarder, bound to
+ * one repository.
+ *
+ * The forwarder reads the bearer from the credential store, so the file carries
+ * no secret and the connection works the moment the step finishes. The remote
+ * form the web setup page hands out is the alternative, and it is deliberately
+ * not what this command writes: it reads the bearer from an environment
+ * variable, which means a person has to open a 600-mode file, copy a credential
+ * out of it by hand, and restart their agent host before the agent this step
+ * just called "connected" can do anything. That is a third human act in a
+ * product whose whole claim is that there are two. `isOurEntry` still
+ * recognises that form, so a team who set a host up in the browser and then ran
+ * this command is never told their own entry is foreign.
+ *
+ * Before publication the entry names this checkout's built entry point by
+ * absolute path, because there is no registry specifier that resolves to this
+ * program. After publication it names the release tag rather than a version, so
+ * the same block works on a machine that never had a checkout and so the host
+ * resolves the newest published command every time it starts the server. A
+ * version written here is a version the repository keeps running until somebody
+ * remembers to edit the file, which is how a customer ends up months behind.
+ *
+ * `npm_config_prefer_online` is the belt to that brace. npm already revalidates
+ * a dist-tag against the registry on every `npx` run, which was measured rather
+ * than assumed, but a machine whose npm configuration sets `prefer-offline` or
+ * `offline` would resolve the tag out of its own cache and never ask. Setting
+ * the variable in the entry's own environment overrides that for this one
+ * process, so the check happens on the machines where it would otherwise be
+ * skipped. With no network the cached copy still runs, and the server then tells
+ * it that it is behind.
+ */
+export declare function stdioEntry(repositoryId: string, publishedVersion: string | null | undefined): StdioMcpEntry;
+/**
+ * Whether an entry already under our key is provably ours.
+ *
+ * Three shapes count, and nothing else. The HTTP form is ours when its URL
+ * points at the very control plane this session paired with; a URL anywhere else
+ * under our key is somebody's redirect, not our server. The published stdio form
+ * is ours when it runs `npx` on `balladeer@latest`, which is what this command
+ * writes now, or on an exact `balladeer@<major>.<minor>.<patch>` release, which
+ * is what it wrote before and what a repository set up earlier still carries;
+ * `balladeer@github:someone/thing`, `balladeer@https://...` and
+ * `balladeer@file:../x` are all valid npm specifiers that a looser check would
+ * have accepted, and each of them runs somebody else's program under our name.
+ * Recognising the old pinned form is what lets `setup --refresh` repair a stale
+ * install in place rather than refusing it as foreign. The checkout stdio form
+ * is ours when it runs `node` on
+ * an absolute path whose file is this command's entry point, with `mcp` as its
+ * subcommand: a relative path, a different file name, or a different interpreter
+ * is somebody else's program and this command will not silently replace it.
+ *
+ * Recognising the HTTP form matters as much as refusing the impostor: it is the
+ * entry the web setup page already hands people, so a team that onboarded
+ * through the browser and then runs this command must not be told their own
+ * Balladeer entry is foreign.
+ */
+export declare function isOurEntry(entry: unknown, controlPlane: string): boolean;
+/**
+ * Merges our entry into the repository's `.mcp.json`, or refuses.
+ *
+ * An unparseable file is never overwritten: it is somebody's configuration and
+ * this command cannot tell what is in it. A foreign entry under our key is never
+ * replaced either; the block to merge is printed instead, so a person decides.
+ */
+export declare function mergeMcpConfig(repositoryRoot: string, entry: McpEntry, controlPlane: string): MergeResult;
+/**
+ * The repository id an entry already under our key names, or nothing.
+ *
+ * `setup --refresh` runs where a stale install is, and the machine it runs on
+ * may hold no credential for this repository: the person who paired it was a
+ * colleague, or the store was cleared. The entry itself still says which
+ * repository this checkout was connected for, and rewriting the entry around
+ * the id it already carries repairs the file without guessing.
+ */
+export declare function entryRepositoryId(entry: unknown): string | undefined;
+/** The entry currently under our key in a parsed `.mcp.json`, or nothing. */
+export declare function currentEntry(parsed: unknown): unknown;
+/** The parsed `.mcp.json` of a repository, or nothing when there is none to read. */
+export declare function readMcpConfig(repositoryRoot: string): unknown;

package/dist/mcp-config.js

@@ -0,0 +1,230 @@
+import { closeSync, fsyncSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { basename, dirname, isAbsolute, join } from "node:path";
+import { PUBLISHED_SPECIFIER, checkoutEntryPath } from "./release.js";
+export const MCP_CONFIG_FILE = ".mcp.json";
+/**
+ * The entry this command writes: this command's own stdio forwarder, bound to
+ * one repository.
+ *
+ * The forwarder reads the bearer from the credential store, so the file carries
+ * no secret and the connection works the moment the step finishes. The remote
+ * form the web setup page hands out is the alternative, and it is deliberately
+ * not what this command writes: it reads the bearer from an environment
+ * variable, which means a person has to open a 600-mode file, copy a credential
+ * out of it by hand, and restart their agent host before the agent this step
+ * just called "connected" can do anything. That is a third human act in a
+ * product whose whole claim is that there are two. `isOurEntry` still
+ * recognises that form, so a team who set a host up in the browser and then ran
+ * this command is never told their own entry is foreign.
+ *
+ * Before publication the entry names this checkout's built entry point by
+ * absolute path, because there is no registry specifier that resolves to this
+ * program. After publication it names the release tag rather than a version, so
+ * the same block works on a machine that never had a checkout and so the host
+ * resolves the newest published command every time it starts the server. A
+ * version written here is a version the repository keeps running until somebody
+ * remembers to edit the file, which is how a customer ends up months behind.
+ *
+ * `npm_config_prefer_online` is the belt to that brace. npm already revalidates
+ * a dist-tag against the registry on every `npx` run, which was measured rather
+ * than assumed, but a machine whose npm configuration sets `prefer-offline` or
+ * `offline` would resolve the tag out of its own cache and never ask. Setting
+ * the variable in the entry's own environment overrides that for this one
+ * process, so the check happens on the machines where it would otherwise be
+ * skipped. With no network the cached copy still runs, and the server then tells
+ * it that it is behind.
+ */
+export function stdioEntry(repositoryId, publishedVersion) {
+    return publishedVersion === null || publishedVersion === undefined
+        ? { command: "node", args: [checkoutEntryPath(), "mcp", "--repository", repositoryId] }
+        : {
+            command: "npx",
+            args: ["-y", PUBLISHED_SPECIFIER, "mcp", "--repository", repositoryId],
+            env: { npm_config_prefer_online: "true" },
+        };
+}
+function sameOrigin(left, right) {
+    try {
+        return new URL(left).origin === new URL(right).origin;
+    }
+    catch {
+        return false;
+    }
+}
+/** `node`, however the host spells the path to it, and nothing else. */
+function isNodeCommand(command) {
+    const name = basename(command);
+    return name === "node" || name === "node.exe";
+}
+/**
+ * Whether an entry already under our key is provably ours.
+ *
+ * Three shapes count, and nothing else. The HTTP form is ours when its URL
+ * points at the very control plane this session paired with; a URL anywhere else
+ * under our key is somebody's redirect, not our server. The published stdio form
+ * is ours when it runs `npx` on `balladeer@latest`, which is what this command
+ * writes now, or on an exact `balladeer@<major>.<minor>.<patch>` release, which
+ * is what it wrote before and what a repository set up earlier still carries;
+ * `balladeer@github:someone/thing`, `balladeer@https://...` and
+ * `balladeer@file:../x` are all valid npm specifiers that a looser check would
+ * have accepted, and each of them runs somebody else's program under our name.
+ * Recognising the old pinned form is what lets `setup --refresh` repair a stale
+ * install in place rather than refusing it as foreign. The checkout stdio form
+ * is ours when it runs `node` on
+ * an absolute path whose file is this command's entry point, with `mcp` as its
+ * subcommand: a relative path, a different file name, or a different interpreter
+ * is somebody else's program and this command will not silently replace it.
+ *
+ * Recognising the HTTP form matters as much as refusing the impostor: it is the
+ * entry the web setup page already hands people, so a team that onboarded
+ * through the browser and then runs this command must not be told their own
+ * Balladeer entry is foreign.
+ */
+export function isOurEntry(entry, controlPlane) {
+    if (entry === null || typeof entry !== "object")
+        return false;
+    const record = entry;
+    if (typeof record.url === "string")
+        return sameOrigin(record.url, controlPlane);
+    if (typeof record.command !== "string" || !Array.isArray(record.args))
+        return false;
+    const args = record.args;
+    if (record.command === "npx") {
+        const specifier = args[1];
+        return (typeof specifier === "string" &&
+            /^balladeer@(?:latest|\d+\.\d+\.\d+)$/.test(specifier) &&
+            args[2] === "mcp");
+    }
+    if (isNodeCommand(record.command)) {
+        const script = args[0];
+        return (typeof script === "string" &&
+            isAbsolute(script) &&
+            basename(script) === "cli.js" &&
+            args[1] === "mcp");
+    }
+    return false;
+}
+function renderBlock(entry) {
+    return JSON.stringify({ mcpServers: { balladeer: entry } }, null, 2);
+}
+/**
+ * Atomic, and never through a path something could have pre-planted: the
+ * temporary file is opened with `wx` under a random name in the same directory,
+ * flushed, and renamed over the target.
+ */
+function writeAtomically(path, contents) {
+    const temporary = join(dirname(path), `.mcp.${randomBytes(8).toString("hex")}.tmp`);
+    let descriptor;
+    try {
+        descriptor = openSync(temporary, "wx", 0o644);
+        writeSync(descriptor, contents);
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = undefined;
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        if (descriptor !== undefined) {
+            try {
+                closeSync(descriptor);
+            }
+            catch {
+                // The unlink below is the cleanup that matters.
+            }
+        }
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            // The temporary file may never have been created.
+        }
+        throw error;
+    }
+}
+/**
+ * Merges our entry into the repository's `.mcp.json`, or refuses.
+ *
+ * An unparseable file is never overwritten: it is somebody's configuration and
+ * this command cannot tell what is in it. A foreign entry under our key is never
+ * replaced either; the block to merge is printed instead, so a person decides.
+ */
+export function mergeMcpConfig(repositoryRoot, entry, controlPlane) {
+    const path = join(repositoryRoot, MCP_CONFIG_FILE);
+    const block = renderBlock(entry);
+    let existing = "";
+    try {
+        existing = readFileSync(path, "utf8");
+    }
+    catch {
+        writeAtomically(path, `${JSON.stringify({ mcpServers: { balladeer: entry } }, null, 2)}\n`);
+        return { kind: "written", changed: true };
+    }
+    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: `The repository's ${MCP_CONFIG_FILE} could not be parsed; I did not change it.`,
+            block,
+        };
+    }
+    const servers = parsed.mcpServers !== null &&
+        typeof parsed.mcpServers === "object" &&
+        !Array.isArray(parsed.mcpServers)
+        ? { ...parsed.mcpServers }
+        : {};
+    const current = servers.balladeer;
+    if (current !== undefined && !isOurEntry(current, controlPlane)) {
+        return {
+            kind: "refused",
+            reason: `${MCP_CONFIG_FILE} already has an entry named balladeer that is not this workspace's server; I did not change it.`,
+            block,
+        };
+    }
+    servers.balladeer = entry;
+    const next = `${JSON.stringify({ ...parsed, mcpServers: servers }, null, 2)}\n`;
+    if (next === existing)
+        return { kind: "written", changed: false };
+    writeAtomically(path, next);
+    return { kind: "written", changed: true };
+}
+/**
+ * The repository id an entry already under our key names, or nothing.
+ *
+ * `setup --refresh` runs where a stale install is, and the machine it runs on
+ * may hold no credential for this repository: the person who paired it was a
+ * colleague, or the store was cleared. The entry itself still says which
+ * repository this checkout was connected for, and rewriting the entry around
+ * the id it already carries repairs the file without guessing.
+ */
+export function entryRepositoryId(entry) {
+    const args = entry?.args;
+    if (!Array.isArray(args))
+        return undefined;
+    const at = args.indexOf("--repository");
+    const value = at === -1 ? undefined : args[at + 1];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/** The entry currently under our key in a parsed `.mcp.json`, or nothing. */
+export function currentEntry(parsed) {
+    const servers = parsed?.mcpServers;
+    if (servers === null || typeof servers !== "object")
+        return undefined;
+    return servers.balladeer;
+}
+/** The parsed `.mcp.json` of a repository, or nothing when there is none to read. */
+export function readMcpConfig(repositoryRoot) {
+    try {
+        return JSON.parse(readFileSync(join(repositoryRoot, MCP_CONFIG_FILE), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/release.d.ts

@@ -0,0 +1,55 @@
+/**
+ * How to say "run this command again", in a way that actually runs it.
+ *
+ * The package name `balladeer` is taken on npm by an unrelated 0.0.x package
+ * that installs a different program, and until the publish happens the version
+ * this repository builds is not on the registry at all. So this command never
+ * writes a registry invocation as a literal. It asks the server, which reads
+ * the publication from one setting, and falls back to the checkout form
+ * whenever it has not been told otherwise. A sentence that names a command a
+ * person cannot run is worse than no sentence at all.
+ *
+ * What that setting no longer decides is the specifier. Nothing this product
+ * hands a customer pins a version any more: a pinned line is what left legacy
+ * customers running a months-old command, because the line in their config and
+ * the line on their screen both named the version that was newest the day they
+ * ran setup. The tag is resolved against the registry on every invocation, so a
+ * publish reaches a machine at its next session start.
+ */
+/** What a person runs from the root of a built checkout. */
+export declare const CHECKOUT_COMMAND = "node packages/cli/dist/cli.js";
+/** The specifier every published surface names, which is a tag and never a pin. */
+export declare const PUBLISHED_SPECIFIER = "balladeer@latest";
+/**
+ * How to invoke this command, with no subcommand attached.
+ *
+ * The parameter still says whether the package is published, because until it
+ * is, the tag resolves to somebody else's package. It no longer says which
+ * version to name.
+ */
+export declare function commandPrefix(publishedVersion: string | null | undefined): string;
+/** One runnable line. */
+export declare function commandLine(publishedVersion: string | null | undefined, subcommand: string): string;
+/**
+ * The absolute path an agent host runs to reach this checkout's built command.
+ *
+ * Resolved from this module rather than from the working directory, because the
+ * `.mcp.json` entry is executed later, by another program, from a directory
+ * this command never sees. It is the same path whether this file is running
+ * from `src` under a loader or from `dist` after a build, because both sit one
+ * directory below the package root.
+ */
+export declare function checkoutEntryPath(): string;
+/**
+ * Whether this copy is running out of a registry install rather than a
+ * checkout.
+ *
+ * `setup --refresh` has to write the same invocation the first setup wrote, and
+ * it has to do it without a server to ask: a repair runs where a stale install
+ * is, which may be a laptop that cannot reach the control plane at that moment.
+ * The honest local answer is how this copy was itself obtained. npm and npx
+ * both unpack a registry install under a `node_modules` directory, and a
+ * checkout of this repository never has one on the path to its own entry point,
+ * so the presence of that segment is what separates the two.
+ */
+export declare function runningFromRegistryInstall(): boolean;

package/dist/release.js

@@ -0,0 +1,67 @@
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * How to say "run this command again", in a way that actually runs it.
+ *
+ * The package name `balladeer` is taken on npm by an unrelated 0.0.x package
+ * that installs a different program, and until the publish happens the version
+ * this repository builds is not on the registry at all. So this command never
+ * writes a registry invocation as a literal. It asks the server, which reads
+ * the publication from one setting, and falls back to the checkout form
+ * whenever it has not been told otherwise. A sentence that names a command a
+ * person cannot run is worse than no sentence at all.
+ *
+ * What that setting no longer decides is the specifier. Nothing this product
+ * hands a customer pins a version any more: a pinned line is what left legacy
+ * customers running a months-old command, because the line in their config and
+ * the line on their screen both named the version that was newest the day they
+ * ran setup. The tag is resolved against the registry on every invocation, so a
+ * publish reaches a machine at its next session start.
+ */
+/** What a person runs from the root of a built checkout. */
+export const CHECKOUT_COMMAND = "node packages/cli/dist/cli.js";
+/** The specifier every published surface names, which is a tag and never a pin. */
+export const PUBLISHED_SPECIFIER = "balladeer@latest";
+/**
+ * How to invoke this command, with no subcommand attached.
+ *
+ * The parameter still says whether the package is published, because until it
+ * is, the tag resolves to somebody else's package. It no longer says which
+ * version to name.
+ */
+export function commandPrefix(publishedVersion) {
+    return publishedVersion === null || publishedVersion === undefined
+        ? CHECKOUT_COMMAND
+        : `npx -y ${PUBLISHED_SPECIFIER}`;
+}
+/** One runnable line. */
+export function commandLine(publishedVersion, subcommand) {
+    return `${commandPrefix(publishedVersion)} ${subcommand}`;
+}
+/**
+ * The absolute path an agent host runs to reach this checkout's built command.
+ *
+ * Resolved from this module rather than from the working directory, because the
+ * `.mcp.json` entry is executed later, by another program, from a directory
+ * this command never sees. It is the same path whether this file is running
+ * from `src` under a loader or from `dist` after a build, because both sit one
+ * directory below the package root.
+ */
+export function checkoutEntryPath() {
+    return join(resolve(dirname(fileURLToPath(import.meta.url)), ".."), "dist", "cli.js");
+}
+/**
+ * Whether this copy is running out of a registry install rather than a
+ * checkout.
+ *
+ * `setup --refresh` has to write the same invocation the first setup wrote, and
+ * it has to do it without a server to ask: a repair runs where a stale install
+ * is, which may be a laptop that cannot reach the control plane at that moment.
+ * The honest local answer is how this copy was itself obtained. npm and npx
+ * both unpack a registry install under a `node_modules` directory, and a
+ * checkout of this repository never has one on the path to its own entry point,
+ * so the presence of that segment is what separates the two.
+ */
+export function runningFromRegistryInstall() {
+    return checkoutEntryPath().split(/[\\/]/).includes("node_modules");
+}

package/dist/repository.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The two display hints, and nothing else. They exist so a person can recognise
+ * their own pairing on the approval page, and the server refuses anything that
+ * is not the shape of an owner/name or a hostname, so a hint can never be
+ * written to read like Balladeer's own assertion.
+ */
+export declare function repositoryHint(cwd?: string): string;
+export declare function hostHint(): string;

package/dist/repository.js

@@ -0,0 +1,32 @@
+import { execFileSync } from "node:child_process";
+import { hostname } from "node:os";
+const REPOSITORY_HINT_PATTERN = /^[A-Za-z0-9._-]{1,39}\/[A-Za-z0-9._-]{1,100}$/;
+const HOST_HINT_PATTERN = /^[A-Za-z0-9.-]{1,63}$/;
+/**
+ * The two display hints, and nothing else. They exist so a person can recognise
+ * their own pairing on the approval page, and the server refuses anything that
+ * is not the shape of an owner/name or a hostname, so a hint can never be
+ * written to read like Balladeer's own assertion.
+ */
+export function repositoryHint(cwd = process.cwd()) {
+    let remote;
+    try {
+        remote = execFileSync("git", ["-C", cwd, "remote", "get-url", "origin"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return "unknown/unknown";
+    }
+    const match = /github\.com[:/]+([A-Za-z0-9._-]{1,39})\/([A-Za-z0-9._-]{1,100}?)(?:\.git)?$/.exec(remote);
+    if (!match)
+        return "unknown/unknown";
+    const hint = `${match[1]}/${match[2]}`;
+    return REPOSITORY_HINT_PATTERN.test(hint) ? hint : "unknown/unknown";
+}
+export function hostHint() {
+    const raw = hostname().split(".")[0] ?? "";
+    const cleaned = raw.replace(/[^A-Za-z0-9.-]/g, "").slice(0, 63);
+    return HOST_HINT_PATTERN.test(cleaned) ? cleaned : "unknown";
+}

package/dist/seals.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Where a promise's sealed files live, and where the package that seals them
+ * lives. Both are fixed by the runner: `materials[].path` is refused unless it
+ * starts with `.continuity/promises/<promise-id>/`, and the sealed package is
+ * written to `.continuity/packages/<promise-id>.json`.
+ */
+export declare const PROMISE_TREE_ROOT = ".continuity/promises";
+export declare const PACKAGE_DIRECTORY = ".continuity/packages";
+/** How many sealed directories one report names before it says how many more. */
+export declare const SEALED_PATHS_SHOWN = 10;
+/**
+ * One promise's seal, as this checkout carries it.
+ *
+ * Everything here is read out of the customer's own sealed package file. None
+ * of it is a judgement about whether the seal still holds: that verdict comes
+ * from the pinned runner, which is the only thing entitled to give it.
+ */
+export type SealedPromise = Readonly<{
+    promiseId: string;
+    /** The directory whose every file the package digest-locks, with a trailing slash. */
+    sealedPath: string;
+    /** The sealed package file, repository-relative. */
+    packageFile: string;
+    title?: string;
+    owner?: string;
+    promiseUrl?: string;
+}>;
+/**
+ * Every promise this checkout has a sealed package for, in id order.
+ *
+ * It reads the package files and nothing else, so it works with no network, no
+ * credential, and no runner checkout. A file that is not a readable sealed
+ * package is skipped rather than reported: a half-written draft in that
+ * directory is not a seal, and refusing to say anything about the other
+ * promises because of it would be worse than leaving it out.
+ */
+export declare function sealedPromises(repositoryRoot: string): SealedPromise[];
+/**
+ * Which promise a changed path belongs to, or nothing when the path is
+ * ordinary source.
+ *
+ * Two paths belong to a promise: a file inside its sealed directory, whose
+ * bytes the package locks, and the sealed package itself, which is what a
+ * reseal rewrites. A change to either one is the change worth checking; every
+ * other path in a repository is somebody's ordinary work and this says so by
+ * answering nothing.
+ */
+export declare function promiseForPath(path: string): string | undefined;

package/dist/seals.js

@@ -0,0 +1,112 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Where a promise's sealed files live, and where the package that seals them
+ * lives. Both are fixed by the runner: `materials[].path` is refused unless it
+ * starts with `.continuity/promises/<promise-id>/`, and the sealed package is
+ * written to `.continuity/packages/<promise-id>.json`.
+ */
+export const PROMISE_TREE_ROOT = ".continuity/promises";
+export const PACKAGE_DIRECTORY = ".continuity/packages";
+/** How many sealed directories one report names before it says how many more. */
+export const SEALED_PATHS_SHOWN = 10;
+/** A promise id as the runner spells it. Anything else is not one of ours. */
+const PROMISE_ID = /^prom_[a-z0-9]{8,64}$/;
+function readableString(value, limit) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed === "")
+        return undefined;
+    // Bounded, and stripped of anything that could reflow a terminal: this text
+    // came out of a file in the customer's repository and is about to be printed.
+    return trimmed.replace(/[\u0000-\u001f\u007f]/g, " ").slice(0, limit);
+}
+/**
+ * Every promise this checkout has a sealed package for, in id order.
+ *
+ * It reads the package files and nothing else, so it works with no network, no
+ * credential, and no runner checkout. A file that is not a readable sealed
+ * package is skipped rather than reported: a half-written draft in that
+ * directory is not a seal, and refusing to say anything about the other
+ * promises because of it would be worse than leaving it out.
+ */
+export function sealedPromises(repositoryRoot) {
+    let entries;
+    try {
+        entries = readdirSync(join(repositoryRoot, PACKAGE_DIRECTORY));
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const entry of entries.sort()) {
+        if (!entry.endsWith(".json"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(join(repositoryRoot, PACKAGE_DIRECTORY, entry), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const promise = parsed.promise;
+        const attribution = parsed.attribution;
+        const promiseId = typeof promise?.id === "string" ? promise.id : undefined;
+        if (promiseId === undefined || !PROMISE_ID.test(promiseId))
+            continue;
+        if (!Array.isArray(parsed.materials) || parsed.materials.length === 0)
+            continue;
+        found.push({
+            promiseId,
+            sealedPath: `${PROMISE_TREE_ROOT}/${promiseId}/`,
+            packageFile: `${PACKAGE_DIRECTORY}/${entry}`,
+            ...(readableString(promise?.title, 160) === undefined
+                ? {}
+                : { title: readableString(promise?.title, 160) }),
+            ...(readableString(attribution?.owner, 160) === undefined
+                ? {}
+                : { owner: readableString(attribution?.owner, 160) }),
+            ...(readableString(attribution?.promiseUrl, 300) === undefined
+                ? {}
+                : { promiseUrl: readableString(attribution?.promiseUrl, 300) }),
+        });
+    }
+    return found.sort((left, right) => left.promiseId.localeCompare(right.promiseId));
+}
+/**
+ * Which promise a changed path belongs to, or nothing when the path is
+ * ordinary source.
+ *
+ * Two paths belong to a promise: a file inside its sealed directory, whose
+ * bytes the package locks, and the sealed package itself, which is what a
+ * reseal rewrites. A change to either one is the change worth checking; every
+ * other path in a repository is somebody's ordinary work and this says so by
+ * answering nothing.
+ */
+export function promiseForPath(path) {
+    const normalized = path.replace(/\\/g, "/").replace(/^\.\//, "");
+    const treePrefix = `${PROMISE_TREE_ROOT}/`;
+    const packagePrefix = `${PACKAGE_DIRECTORY}/`;
+    if (normalized.startsWith(treePrefix)) {
+        const rest = normalized.slice(treePrefix.length);
+        const slash = rest.indexOf("/");
+        // A file directly under the tree root belongs to no promise: the id is a
+        // directory, and something dropped beside those directories is not sealed.
+        if (slash > 0 && rest.length > slash + 1) {
+            const id = rest.slice(0, slash);
+            if (PROMISE_ID.test(id))
+                return id;
+        }
+        return undefined;
+    }
+    if (normalized.startsWith(packagePrefix)) {
+        const rest = normalized.slice(packagePrefix.length);
+        if (rest.endsWith(".json") && !rest.slice(0, -5).includes("/")) {
+            const id = rest.slice(0, -5);
+            if (PROMISE_ID.test(id))
+                return id;
+        }
+    }
+    return undefined;
+}