balladeer 0.0.4 → 1.0.0

package/dist/commands/touch-map.js

@@ -0,0 +1,251 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { runCommand } from "../gh.js";
+import { repositoryRoot } from "../git.js";
+import { CONTINUITY_DIRECTORY, TOUCH_MAP_FILE, buildTouchMap, executedPaths, mappablePath, measurableWithNode, readCoverageDirectory, readLocalPackages, repositoryPath, serializeTouchMap, touchMapBody, touchMapEnvironment, verifierCwd, verifierDigest, } from "../touch-map.js";
+import {} from "../wire.js";
+/** A verifier gets this long before the measurement gives up on it. */
+const DEFAULT_TIMEOUT_MS = 120_000;
+/** However long a package asks for, no verifier holds this command longer. */
+const MAXIMUM_TIMEOUT_MS = 300_000;
+/** How many promises a plain-text summary names before it says how many more. */
+const NAMED_LIMIT = 20;
+/**
+ * Where the promises are, which is not always the git root.
+ *
+ * A repository keeps its promises at its top level, so the git root is the
+ * answer almost every time. It is not the answer when somebody is standing in a
+ * sub-tree that carries its own `.continuity/` directory, which is how this
+ * repository's own dogfood packages are laid out, and running there and mapping
+ * the outer tree instead would answer a question nobody asked.
+ */
+export async function promiseRoot(cwd) {
+    const chosen = existsSync(join(cwd, CONTINUITY_DIRECTORY)) ? cwd : await repositoryRoot(cwd);
+    if (chosen === undefined)
+        return undefined;
+    // Resolved through its symlinks, because V8 reports the real path of every
+    // script it recorded. A checkout reached through a link would otherwise
+    // measure correctly and attribute nothing, which reads as a repository where
+    // no promise touches anything.
+    try {
+        return realpathSync(chosen);
+    }
+    catch {
+        return chosen;
+    }
+}
+/**
+ * Measure one promise: run its verifier against this working tree, under
+ * coverage, and keep the list of repository files it executed.
+ *
+ * It runs the verifier's own declared entry point rather than the pinned
+ * runner. The runner hands its child a closed environment on purpose, and
+ * `NODE_V8_COVERAGE` is not in it, so a measurement taken through the runner
+ * would come back empty every time. The invocation is the package's own, so
+ * what runs here is what CI runs; only the environment differs, by the one
+ * variable that turns the recorder on.
+ */
+async function measure(root, pkg, environment) {
+    if (pkg.target.executable === "" || pkg.target.args.length === 0) {
+        return {
+            promiseId: pkg.promiseId,
+            reason: "no_verifier_target",
+            detail: `${pkg.promiseId} declares no runnable verifier target in ${pkg.packageFile}, so nothing could be measured.`,
+        };
+    }
+    if (!measurableWithNode(pkg.target)) {
+        return {
+            promiseId: pkg.promiseId,
+            reason: "unsupported_executable",
+            detail: `${pkg.promiseId} runs ${pkg.target.executable}, and this release measures Node verifiers ` +
+                "only. Other languages come later; until then its path markers answer for it.",
+        };
+    }
+    const cwd = verifierCwd(root, pkg.target);
+    if (cwd === undefined) {
+        return {
+            promiseId: pkg.promiseId,
+            reason: "cwd_outside_repository",
+            detail: `${pkg.promiseId} runs its verifier outside this repository, so it was not measured.`,
+        };
+    }
+    const scratch = mkdtempSync(join(tmpdir(), "balladeer-touch-map-"));
+    try {
+        const coverage = join(scratch, "coverage");
+        mkdirSync(coverage, { recursive: true });
+        const budget = Math.min(pkg.target.timeoutMs ?? DEFAULT_TIMEOUT_MS, MAXIMUM_TIMEOUT_MS);
+        const started = Date.now();
+        const answer = await runCommand(process.execPath, [...pkg.target.args], {
+            cwd,
+            timeoutMs: budget,
+            // Cast, not a widening: this is a closed allow-list by construction, and
+            // the ambient environment type insists on names a verifier must not get.
+            env: touchMapEnvironment(environment, coverage, join(scratch, "result.json")),
+        });
+        // A verifier that outlived the budget was stopped by this command, and
+        // saying "could not be run (exit 1)" would send somebody hunting for a crash
+        // that never happened. The elapsed time is what tells the two apart, because
+        // a killed process reports an ordinary non-zero exit.
+        const outOfTime = !answer.ok && Date.now() - started >= budget;
+        const executed = new Set();
+        for (const document of readCoverageDirectory(coverage))
+            for (const path of executedPaths(root, document))
+                executed.add(path);
+        // Whether the verifier ran is answered by whether V8 recorded the verifier
+        // itself, not by its exit code. A verifier that reports a refutation exits
+        // non-zero and has still told us exactly which files it read; one that died
+        // on a missing import exits non-zero and has told us nothing, and the two
+        // must not be reported as the same thing.
+        if (!ranAtAll(root, cwd, pkg, executed)) {
+            return {
+                promiseId: pkg.promiseId,
+                reason: outOfTime ? "timed_out" : answer.ok ? "no_coverage" : "did_not_run",
+                detail: outOfTime
+                    ? `${pkg.promiseId} was still running after ${Math.round(budget / 1000)} seconds and was stopped, so it is not in the map.`
+                    : answer.ok
+                        ? `${pkg.promiseId} ran and left no coverage of its own verifier behind, so nothing could be attributed to it.`
+                        : `${pkg.promiseId} could not be run here (exit ${answer.code ?? "none"}), so it is not in the map.`,
+            };
+        }
+        return {
+            promiseId: pkg.promiseId,
+            verifierDigest: verifierDigest(root, pkg),
+            // A promise whose verifier reads only its own sealed tree maps no files,
+            // and that is a true answer rather than a failure: nothing else in the
+            // repository is what it checks.
+            paths: [...executed].filter(mappablePath).sort(),
+        };
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}
+function isCoverage(value) {
+    return "paths" in value;
+}
+/**
+ * Whether the verifier itself is among the scripts V8 recorded.
+ *
+ * The package names the program to run, so the honest test of "did it run" is
+ * whether that program appears in the coverage. Where the invocation's first
+ * argument is not a file in this repository, which no package the scaffold
+ * writes produces, any recorded repository file stands in for it rather than
+ * refusing to answer.
+ */
+function ranAtAll(root, cwd, pkg, executed) {
+    const entry = pkg.target.args[0];
+    const path = entry === undefined ? undefined : repositoryPath(root, resolve(cwd, entry));
+    if (path === undefined)
+        return executed.size > 0;
+    return executed.has(path);
+}
+/**
+ * The command that turns "which files does this verifier read" from a guess
+ * into a measurement.
+ *
+ * It runs every sealed promise in this checkout under V8's coverage recorder
+ * and writes what each one executed to `.continuity/touch-map.json`. The file
+ * stays on the customer's disk. Nothing here posts it, and the map is a list of
+ * a customer's own file names, which is exactly the thing the boundary copy
+ * promises Balladeer never receives.
+ */
+export async function runTouchMap(options) {
+    const emit = (step) => {
+        if (options.json)
+            options.write(`${JSON.stringify(step)}\n`);
+    };
+    const say = (text) => {
+        if (!options.json)
+            options.write(`${text}\n`);
+    };
+    const root = await promiseRoot(options.cwd);
+    if (root === undefined) {
+        const message = "This is not a git repository and there are no promise packages here, so there is nothing to map. Run it from inside your checkout.";
+        if (options.json)
+            emit({ step: "error", reason: "not_a_repository", message, changed: false, exitCode: 4 });
+        else
+            options.write(`${message}\n`);
+        return 4;
+    }
+    const packages = readLocalPackages(root);
+    if (packages.length === 0) {
+        const message = "This checkout holds no sealed promise packages, so there is nothing to map yet. A promise gets one when somebody seals its verifier.";
+        emit({ step: "touch_map", promises: 0, files: 0, unmapped: 0, bytes: 0, changed: false });
+        say(message);
+        return 0;
+    }
+    const covered = [];
+    const unmapped = [];
+    for (const pkg of packages) {
+        const answer = await measure(root, pkg, options.environment);
+        if (isCoverage(answer))
+            covered.push(answer);
+        else
+            unmapped.push(answer);
+    }
+    const now = options.now?.() ?? new Date();
+    const map = buildTouchMap({ generatedAt: now.toISOString(), covered, unmapped });
+    const written = writeTouchMap(root, map);
+    emit({
+        step: "touch_map",
+        promises: map.promises.length,
+        files: map.files.length,
+        unmapped: map.unmapped.length,
+        bytes: written.bytes,
+        changed: written.changed,
+        ...(map.truncated ? { truncated: true } : {}),
+    });
+    say(`Mapped ${map.promises.length} ${map.promises.length === 1 ? "promise" : "promises"} across ` +
+        `${map.files.length} ${map.files.length === 1 ? "file" : "files"}, in ${TOUCH_MAP_FILE} ` +
+        `(${written.bytes} bytes).`);
+    say("This file stays here. Balladeer is never sent it.");
+    if (map.truncated) {
+        say("It hit this release's size cap, so it is a partial map. Treat a file it does not name as unanswered rather than as untouched.");
+    }
+    if (map.unmapped.length > 0) {
+        say("");
+        say(map.unmapped.length === 1
+            ? "One promise could not be measured, so nothing is mapped to it:"
+            : `${map.unmapped.length} promises could not be measured, so nothing is mapped to them:`);
+        for (const entry of map.unmapped.slice(0, NAMED_LIMIT))
+            say(`  ${entry.detail}`);
+        if (map.unmapped.length > NAMED_LIMIT)
+            say(`  and ${map.unmapped.length - NAMED_LIMIT} more, not listed here.`);
+    }
+    say("");
+    say("Ask it which promises a change touches with: balladeer affected <paths...>");
+    return 0;
+}
+/**
+ * Write the map, and leave the file alone when nothing about it changed.
+ *
+ * The timestamp is the only field that moves on every run, so comparing the
+ * document without it is what makes a second run a no-op. A command that
+ * rewrote a byte of a committed file every time it was asked a question would
+ * put a diff in front of somebody who changed nothing.
+ */
+export function writeTouchMap(root, map) {
+    const path = join(root, TOUCH_MAP_FILE);
+    const serialized = serializeTouchMap(map);
+    let existing;
+    try {
+        existing = readFileSync(path, "utf8");
+    }
+    catch {
+        existing = undefined;
+    }
+    if (existing !== undefined) {
+        try {
+            const before = JSON.parse(existing);
+            if (touchMapBody(before) === touchMapBody(map))
+                return { changed: false, bytes: Buffer.byteLength(existing, "utf8") };
+        }
+        catch {
+            // An unreadable map is replaced rather than kept.
+        }
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, serialized, "utf8");
+    return { changed: true, bytes: Buffer.byteLength(serialized, "utf8") };
+}

package/dist/commands/whoami.d.ts

@@ -0,0 +1,8 @@
+export type WhoamiOptions = Readonly<{
+    controlPlane: string;
+    json: boolean;
+    environment: NodeJS.ProcessEnv;
+    write: (text: string) => void;
+}>;
+/** Reads the session's standing from the server, never from the stored copy. */
+export declare function runWhoami(options: WhoamiOptions): Promise<number>;

package/dist/commands/whoami.js

@@ -0,0 +1,79 @@
+import { ClientTooOldError, RefusalError, TransportError, request } from "../client.js";
+import { StoreError, dropSession, findSession, readCredentials, writeCredentials, } from "../store.js";
+import { commandLine } from "../release.js";
+import {} from "../wire.js";
+function emit(options, step) {
+    if (options.json)
+        options.write(`${JSON.stringify(step)}\n`);
+}
+/**
+ * The same sentence a person reads, in the shape `--json` promised. Without it,
+ * the machine-readable mode answers a failure with prose on the stream it said
+ * would carry objects only.
+ */
+function fail(options, reason, message, exitCode, changed = false) {
+    if (options.json)
+        emit(options, { step: "error", reason, message, changed, exitCode });
+    else
+        options.write(`${message}\n`);
+    return exitCode;
+}
+function noSession(options, changed = false) {
+    return fail(options, "no_stored_session", `No Balladeer session is stored for ${options.controlPlane}. Run: ${commandLine(null, "setup")}`, 4, changed);
+}
+/** Reads the session's standing from the server, never from the stored copy. */
+export async function runWhoami(options) {
+    let credentials;
+    try {
+        credentials = readCredentials(options.environment);
+    }
+    catch (error) {
+        return fail(options, error instanceof StoreError ? error.code : "credential_store_unusable", error instanceof StoreError ? error.message : String(error), 4);
+    }
+    const stored = findSession(credentials, options.controlPlane);
+    if (!stored)
+        return noSession(options);
+    try {
+        const answer = await request(options.controlPlane, {
+            method: "GET",
+            path: "/api/pair/session",
+            bearer: stored.token,
+        });
+        const session = answer.session;
+        if (options.json) {
+            emit(options, { step: "whoami", session });
+        }
+        else {
+            options.write([
+                `Signed in as ${session.membershipDisplayName}, workspace "${session.workspaceName}" (${session.workspaceSlug}).`,
+                `Role: ${session.role}.`,
+                `This session may: ${session.scopeMeanings.join(", ")}.`,
+                `It expires at ${session.expiresAt}.`,
+                "",
+            ].join("\n"));
+        }
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof ClientTooOldError) {
+            return fail(options, "client_too_old", error.message, 3);
+        }
+        if (error instanceof TransportError) {
+            return fail(options, "control_plane_unreachable", `Balladeer could not be reached at ${options.controlPlane}: ${error.message}. Nothing was changed.`, 5);
+        }
+        if (error instanceof RefusalError) {
+            // Expired, revoked, or the membership behind it is gone. The stored copy
+            // is now a lie, so it is deleted rather than left to mislead the next run.
+            let changed = false;
+            try {
+                writeCredentials(dropSession(credentials, options.controlPlane), options.environment);
+                changed = true;
+            }
+            catch {
+                // Reporting the truth matters more than tidying the file.
+            }
+            return noSession(options, changed);
+        }
+        return fail(options, "session_unreadable", "Balladeer could not read this session. Nothing was changed.", 5);
+    }
+}

package/dist/conventions.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The fence, which never changes again.
+ *
+ * The first version of this file spelled the marker
+ * `<!-- balladeer:conventions:start v1 -->`, so the version travelled in the one
+ * string the lookup matches on. Bumping the block therefore bumped the marker,
+ * the lookup for the old marker missed, and the next run appended a second block
+ * below the stale one instead of replacing it: the customer's committed file
+ * grew a copy per release, each of them contradicting the last.
+ *
+ * The version now lives in a managed-by line inside the fence, where a refresh
+ * can read it and the lookup never depends on it. The marker a version 1 install
+ * wrote is still recognised, so a repository onboarded before this change is
+ * migrated in place rather than given a second block of its own.
+ */
+export declare const CONVENTIONS_START = "<!-- balladeer:conventions:start -->";
+export declare const CONVENTIONS_END = "<!-- balladeer:conventions:end -->";
+/**
+ * The version of the text between the markers. It is written into the block and
+ * read back out of it, and nothing about finding the block depends on it.
+ */
+export declare const CONVENTIONS_VERSION = 10;
+export declare function managedByLine(version: number): string;
+/**
+ * Which version of the block a file already carries, or nothing when it carries
+ * no Balladeer block at all.
+ *
+ * A version 1 install has no managed-by line, so its version is read from the
+ * marker it was written with. A block with neither is one somebody hand-copied,
+ * and treating it as version 0 refreshes it rather than leaving it to rot.
+ */
+export declare function installedConventionsVersion(contents: string): number | undefined;
+export type ConventionsResult = Readonly<{
+    kind: "written";
+    file: string;
+    changed: boolean;
+    version: number;
+    /** What the file carried before this run, when it carried a block. */
+    previousVersion?: number;
+}> | Readonly<{
+    kind: "refused";
+    file: string;
+    reason: string;
+}>;
+/**
+ * Writes the marker-fenced conventions block into the repository's agent
+ * instructions file, so a future session reads the team's promises before
+ * planning without being told to.
+ *
+ * The markers are the whole discipline. Everything outside them is somebody
+ * else's file and is copied through byte for byte; everything between them is
+ * replaced. Running the command twice therefore leaves the file identical, which
+ * is what makes it safe to run on every setup.
+ *
+ * A file whose markers are damaged is refused rather than appended to. One start
+ * with no end, an end with no start, a pair in the wrong order, or two of either
+ * are all states this command cannot repair without guessing where somebody's
+ * own writing begins, and guessing wrong means either deleting their text or
+ * leaving a second block behind. The person is told which file and what is wrong
+ * with it.
+ *
+ * Project-scoped and committed by the developer, never a file in their home
+ * directory: the promises belong to this repository, and a teammate who clones
+ * it should get the same instructions.
+ */
+export declare function writeConventions(repositoryRoot: string, options?: Readonly<{
+    version?: number;
+    body?: string;
+}>): ConventionsResult;

package/dist/conventions.js

@@ -0,0 +1,175 @@
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { dirname, join } from "node:path";
+import { CONVENTIONS_BLOCK } from "./copy.js";
+/**
+ * The fence, which never changes again.
+ *
+ * The first version of this file spelled the marker
+ * `<!-- balladeer:conventions:start v1 -->`, so the version travelled in the one
+ * string the lookup matches on. Bumping the block therefore bumped the marker,
+ * the lookup for the old marker missed, and the next run appended a second block
+ * below the stale one instead of replacing it: the customer's committed file
+ * grew a copy per release, each of them contradicting the last.
+ *
+ * The version now lives in a managed-by line inside the fence, where a refresh
+ * can read it and the lookup never depends on it. The marker a version 1 install
+ * wrote is still recognised, so a repository onboarded before this change is
+ * migrated in place rather than given a second block of its own.
+ */
+export const CONVENTIONS_START = "<!-- balladeer:conventions:start -->";
+export const CONVENTIONS_END = "<!-- balladeer:conventions:end -->";
+/**
+ * The version of the text between the markers. It is written into the block and
+ * read back out of it, and nothing about finding the block depends on it.
+ */
+export const CONVENTIONS_VERSION = 10;
+/** Both spellings: the stable marker, and the versioned one version 1 wrote. */
+const START_MARKER = /<!-- balladeer:conventions:start(?: v(\d{1,4}))? -->/g;
+const END_MARKER = /<!-- balladeer:conventions:end -->/g;
+const MANAGED_BY = /Managed by Balladeer \(conventions v(\d{1,4})\)/;
+const CANDIDATE_FILES = ["CLAUDE.md", "AGENTS.md"];
+export function managedByLine(version) {
+    return (`Managed by Balladeer (conventions v${version}). Everything between the markers is replaced ` +
+        `whenever setup runs in this repository, so put your own notes outside them.`);
+}
+function fenced(version, body) {
+    return `${CONVENTIONS_START}\n${managedByLine(version)}\n\n${body.trim()}\n${CONVENTIONS_END}\n`;
+}
+/**
+ * Which version of the block a file already carries, or nothing when it carries
+ * no Balladeer block at all.
+ *
+ * A version 1 install has no managed-by line, so its version is read from the
+ * marker it was written with. A block with neither is one somebody hand-copied,
+ * and treating it as version 0 refreshes it rather than leaving it to rot.
+ */
+export function installedConventionsVersion(contents) {
+    const start = [...contents.matchAll(START_MARKER)][0];
+    if (start === undefined)
+        return undefined;
+    const managed = MANAGED_BY.exec(contents.slice(start.index));
+    if (managed?.[1] !== undefined)
+        return Number(managed[1]);
+    return start[1] === undefined ? 0 : Number(start[1]);
+}
+function writeAtomically(path, contents) {
+    const temporary = join(dirname(path), `.conventions.${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;
+    }
+}
+/**
+ * Writes the marker-fenced conventions block into the repository's agent
+ * instructions file, so a future session reads the team's promises before
+ * planning without being told to.
+ *
+ * The markers are the whole discipline. Everything outside them is somebody
+ * else's file and is copied through byte for byte; everything between them is
+ * replaced. Running the command twice therefore leaves the file identical, which
+ * is what makes it safe to run on every setup.
+ *
+ * A file whose markers are damaged is refused rather than appended to. One start
+ * with no end, an end with no start, a pair in the wrong order, or two of either
+ * are all states this command cannot repair without guessing where somebody's
+ * own writing begins, and guessing wrong means either deleting their text or
+ * leaving a second block behind. The person is told which file and what is wrong
+ * with it.
+ *
+ * Project-scoped and committed by the developer, never a file in their home
+ * directory: the promises belong to this repository, and a teammate who clones
+ * it should get the same instructions.
+ */
+export function writeConventions(repositoryRoot, options = {}) {
+    const version = options.version ?? CONVENTIONS_VERSION;
+    const existingName = CANDIDATE_FILES.find((name) => existsSync(join(repositoryRoot, name)));
+    const name = existingName ?? "CLAUDE.md";
+    const path = join(repositoryRoot, name);
+    const block = fenced(version, options.body ?? CONVENTIONS_BLOCK);
+    let existing = "";
+    try {
+        existing = readFileSync(path, "utf8");
+    }
+    catch {
+        writeAtomically(path, block);
+        return { kind: "written", file: name, changed: true, version };
+    }
+    const starts = [...existing.matchAll(START_MARKER)];
+    const ends = [...existing.matchAll(END_MARKER)];
+    const damaged = markerDamage(starts.length, ends.length, starts[0]?.index, ends[0]?.index);
+    if (damaged !== undefined) {
+        return {
+            kind: "refused",
+            file: name,
+            reason: `${name} ${damaged}, so I could not tell where Balladeer's block ends and yours begins; I did not change it.`,
+        };
+    }
+    const start = starts[0];
+    const end = ends[0];
+    let next;
+    let previousVersion;
+    if (start !== undefined && end !== undefined) {
+        previousVersion = installedConventionsVersion(existing);
+        const after = end.index + CONVENTIONS_END.length;
+        next = `${existing.slice(0, start.index)}${block}${existing.slice(existing[after] === "\n" ? after + 1 : after)}`;
+    }
+    else {
+        const separator = existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+        next = `${existing}${separator}${block}`;
+    }
+    if (next === existing) {
+        return {
+            kind: "written",
+            file: name,
+            changed: false,
+            version,
+            ...(previousVersion === undefined ? {} : { previousVersion }),
+        };
+    }
+    writeAtomically(path, next);
+    return {
+        kind: "written",
+        file: name,
+        changed: true,
+        version,
+        ...(previousVersion === undefined ? {} : { previousVersion }),
+    };
+}
+/** What is wrong with the markers, said the way a person would fix it. */
+function markerDamage(startCount, endCount, startAt, endAt) {
+    if (startCount > 1 || endCount > 1)
+        return "carries more than one Balladeer conventions block";
+    if (startCount === 1 && endCount === 0) {
+        return "has a Balladeer conventions start marker with no end marker";
+    }
+    if (startCount === 0 && endCount === 1) {
+        return "has a Balladeer conventions end marker with no start marker";
+    }
+    if (startAt !== undefined && endAt !== undefined && endAt < startAt) {
+        return "has its Balladeer conventions markers in the wrong order";
+    }
+    return undefined;
+}