balladeer 0.0.5 → 1.0.1

package/dist/markers.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Which of a promise's scope markers no longer name anything in this checkout.
+ *
+ * A rename is the ordinary way a promise stops being retrievable. Somebody
+ * moves `src/import/preview.ts` to `src/ingest/preview.ts`, the code keeps
+ * working, the check keeps passing, and the promise about it quietly stops
+ * overlapping any path an agent will ever name. Nothing on the server can see
+ * that: Balladeer holds no token for the repository and never reads a file, so
+ * the only place the fact exists is the working tree in front of the runner.
+ *
+ * So it is observed here, locally, and reported as attention rather than
+ * repaired. A marker is a piece of approved meaning; moving one is a semantic
+ * revision a named person makes, and a command that rewrote markers because a
+ * file moved would be editing what somebody agreed to on the strength of a
+ * `git mv`.
+ *
+ * What leaves this machine is nothing. The observation is printed where the
+ * person ran the command.
+ */
+/** How many missing markers one run reports, and how many it will even look at. */
+export declare const MARKER_OBSERVATION_LIMITS: {
+    /** Markers checked on disk in one run. Beyond this the run says it stopped counting. */
+    readonly maxChecked: 500;
+    /** Promises named in the printed row. The rest are counted, not listed. */
+    readonly maxNamed: 5;
+};
+/**
+ * A marker is a path when it names one.
+ *
+ * The grammar admits both `src/import/preview.ts` and `supplier-import-preview`.
+ * Only the first can be missing from a checkout; the second is a topic, and
+ * reporting it as a missing file would tell a person to go looking for
+ * something that was never a file.
+ */
+export declare function isPathShapedMarker(marker: string): boolean;
+export type MarkerObservation = Readonly<{
+    promiseId: string;
+    title: string;
+    /** The markers this promise names that are not in this checkout. */
+    missing: readonly string[];
+}>;
+export type MarkerObservationResult = Readonly<{
+    /** Promises with at least one missing path marker, in the order they were given. */
+    observations: readonly MarkerObservation[];
+    /** How many path-shaped markers were actually looked at. */
+    checked: number;
+    /** True when the run stopped at its ceiling and did not look at every marker. */
+    stoppedEarly: boolean;
+}>;
+export type MarkerSubject = Readonly<{
+    promiseId: string;
+    title: string;
+    surfaces?: readonly string[];
+    labels?: readonly string[];
+}>;
+/**
+ * Look for each promise's path markers in this working tree.
+ *
+ * Bounded twice over: it stops after `maxChecked` markers whatever remains, and
+ * it says that it stopped. A repository with a thousand promises must not turn
+ * `status` into a filesystem walk, and a run that silently examined the first
+ * few hundred would report "nothing missing" about a catalog it never read.
+ */
+export declare function observeMissingMarkers(repositoryRoot: string, subjects: readonly MarkerSubject[], limits?: Readonly<{
+    maxChecked: number;
+}>, exists?: (path: string) => boolean): MarkerObservationResult;
+/**
+ * The attention row a person reads, or nothing at all when every marker is
+ * still there.
+ *
+ * It names what to do and who does it: a marker is approved meaning, so the
+ * remedy is a revision somebody agrees to, never an edit this command makes.
+ */
+export declare function staleMarkerRow(result: MarkerObservationResult, limits?: Readonly<{
+    maxNamed: number;
+}>): string | undefined;

package/dist/markers.js

@@ -0,0 +1,125 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, join, normalize, sep } from "node:path";
+/**
+ * Which of a promise's scope markers no longer name anything in this checkout.
+ *
+ * A rename is the ordinary way a promise stops being retrievable. Somebody
+ * moves `src/import/preview.ts` to `src/ingest/preview.ts`, the code keeps
+ * working, the check keeps passing, and the promise about it quietly stops
+ * overlapping any path an agent will ever name. Nothing on the server can see
+ * that: Balladeer holds no token for the repository and never reads a file, so
+ * the only place the fact exists is the working tree in front of the runner.
+ *
+ * So it is observed here, locally, and reported as attention rather than
+ * repaired. A marker is a piece of approved meaning; moving one is a semantic
+ * revision a named person makes, and a command that rewrote markers because a
+ * file moved would be editing what somebody agreed to on the strength of a
+ * `git mv`.
+ *
+ * What leaves this machine is nothing. The observation is printed where the
+ * person ran the command.
+ */
+/** How many missing markers one run reports, and how many it will even look at. */
+export const MARKER_OBSERVATION_LIMITS = {
+    /** Markers checked on disk in one run. Beyond this the run says it stopped counting. */
+    maxChecked: 500,
+    /** Promises named in the printed row. The rest are counted, not listed. */
+    maxNamed: 5,
+};
+/**
+ * A marker is a path when it names one.
+ *
+ * The grammar admits both `src/import/preview.ts` and `supplier-import-preview`.
+ * Only the first can be missing from a checkout; the second is a topic, and
+ * reporting it as a missing file would tell a person to go looking for
+ * something that was never a file.
+ */
+export function isPathShapedMarker(marker) {
+    const trimmed = marker.trim();
+    if (trimmed === "")
+        return false;
+    if (trimmed.includes("/"))
+        return true;
+    return /^[^/]+\.[A-Za-z0-9]{1,8}$/.test(trimmed);
+}
+/**
+ * A marker refused rather than resolved.
+ *
+ * A marker that escapes the repository root, or that arrives absolute, is not a
+ * marker this checkout can answer for. It is skipped rather than reported
+ * missing: telling a person a path is gone because the command would not look
+ * outside their repository is a false alarm about their catalog.
+ */
+function resolveInside(root, marker) {
+    const cleaned = marker.trim().replaceAll("\\", "/");
+    if (cleaned === "" || isAbsolute(cleaned))
+        return undefined;
+    const full = normalize(join(root, cleaned));
+    const bounded = root.endsWith(sep) ? root : `${root}${sep}`;
+    return full === root || full.startsWith(bounded) ? full : undefined;
+}
+/**
+ * Look for each promise's path markers in this working tree.
+ *
+ * Bounded twice over: it stops after `maxChecked` markers whatever remains, and
+ * it says that it stopped. A repository with a thousand promises must not turn
+ * `status` into a filesystem walk, and a run that silently examined the first
+ * few hundred would report "nothing missing" about a catalog it never read.
+ */
+export function observeMissingMarkers(repositoryRoot, subjects, limits = MARKER_OBSERVATION_LIMITS, exists = existsSync) {
+    const root = normalize(repositoryRoot);
+    const observations = [];
+    let checked = 0;
+    let stoppedEarly = false;
+    for (const subject of subjects) {
+        const missing = [];
+        for (const marker of [...(subject.surfaces ?? []), ...(subject.labels ?? [])]) {
+            if (!isPathShapedMarker(marker))
+                continue;
+            if (checked >= limits.maxChecked) {
+                stoppedEarly = true;
+                break;
+            }
+            checked += 1;
+            const resolved = resolveInside(root, marker);
+            if (resolved === undefined)
+                continue;
+            if (!exists(resolved))
+                missing.push(marker.trim());
+        }
+        if (missing.length > 0) {
+            observations.push({ promiseId: subject.promiseId, title: subject.title, missing });
+        }
+        if (stoppedEarly)
+            break;
+    }
+    return { observations, checked, stoppedEarly };
+}
+/**
+ * The attention row a person reads, or nothing at all when every marker is
+ * still there.
+ *
+ * It names what to do and who does it: a marker is approved meaning, so the
+ * remedy is a revision somebody agrees to, never an edit this command makes.
+ */
+export function staleMarkerRow(result, limits = MARKER_OBSERVATION_LIMITS) {
+    const { observations } = result;
+    if (observations.length === 0)
+        return undefined;
+    const named = observations.slice(0, Math.max(0, limits.maxNamed));
+    const lines = named.map((observation) => `      ${observation.promiseId}: ${observation.missing.join(", ")} (${observation.title})`);
+    const rest = observations.length - named.length;
+    const head = observations.length === 1
+        ? "  Attention: 1 promise names a path that is not in this checkout, so it will not be found by the paths a change touches."
+        : `  Attention: ${observations.length} promises name a path that is not in this checkout, so they will not be found by the paths a change touches.`;
+    const tail = [
+        ...(rest > 0 ? [`      and ${rest} more.`] : []),
+        ...(result.stoppedEarly
+            ? [
+                `      This run looked at ${result.checked} markers and stopped there, so there may be more.`,
+            ]
+            : []),
+        "      A marker is part of what somebody agreed to. Propose a revision and let its owner decide; nothing here changed it.",
+    ];
+    return [head, ...lines, ...tail].join("\n");
+}

package/dist/mcp-config.d.ts

@@ -0,0 +1,109 @@
+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;
+/**
+ * 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.
+ *
+ * Exported because the Claude desktop configuration is written under the same
+ * rule and for a stronger reason: that file belongs to a running application,
+ * and a half-written one is a chat client that starts with no servers at all.
+ */
+export declare function writeJsonAtomically(path: string, contents: string): void;
+/**
+ * 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,234 @@
+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.
+ *
+ * Exported because the Claude desktop configuration is written under the same
+ * rule and for a stronger reason: that file belongs to a running application,
+ * and a half-written one is a chat client that starts with no servers at all.
+ */
+export function writeJsonAtomically(path, contents) {
+    const temporary = join(dirname(path), `.balladeer.${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 {
+        writeJsonAtomically(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 };
+    writeJsonAtomically(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;