@basein/runner 0.2.8 → 0.2.11

package/dist/bin/scenario-edit.js

@@ -0,0 +1,771 @@
+/**
+ * scenario-edit — read, check, change and undo one step of a calculated
+ * scenario (editSteps.md in the BaseIn repository; docs/calculatedReplayGuide.md §9.2).
+ *
+ *   bir scenario show  <runId|scnId> [--step <n>]
+ *   bir scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->] [--unfreeze]
+ *   bir scenario edit  <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]
+ *                      [--freeze | --unfreeze] [--note "why"] [--force --note "why"] [--revision <n>]
+ *   bir scenario edits <runId|scnId>
+ *   bir scenario undo  <runId|scnId> [--edit <sedit_id>]
+ *   bir scenario calc  <runId> [--force [--discard-edits]]
+ *   bir scenario editing on|off|status
+ *
+ * WHY THIS IS A CLIENT AND NOTHING MORE. Whether a change may be saved is
+ * decided on the service, against the recording, by the calculation's own
+ * check (D3) — and `check` and `edit` are the same function there (D11). A
+ * runner-side pre-check would be a second opinion that can disagree with the
+ * one that counts, so this module reads logic from files, sends it, and says
+ * in words what the service answered. `--json` prints the answer unchanged,
+ * which is what the `bir` MCP server hands the model.
+ *
+ * Logic never comes from the command line itself. A JavaScript body is full
+ * of quotes, braces and `$`, and every shell mangles a different subset of
+ * them; a file, or stdin with `-`, arrives byte for byte.
+ *
+ * Everything the commands touch is injected ({@link ScenarioEditDeps}), as in
+ * `investigate.ts`, so all of it is tested in-process against a fake service.
+ * The exception is `editing`, which writes the install sidecar — tests point
+ * `BIR_HOME` at a temporary directory for that.
+ */
+import { normalizePath } from "../control/paths.js";
+import { SCENARIO_SERVER_KEY, editingEnabled, projectRecord, readSidecar, setEditing, writeSidecar, } from "../config/generate.js";
+import { errText } from "../util/log.js";
+/** The `bir scenario` words this module answers; `list` and `replay` stay in bir.ts. */
+export const SCENARIO_EDIT_SUBCOMMANDS = new Set([
+    "show",
+    "check",
+    "edit",
+    "edits",
+    "undo",
+    "calc",
+    "editing",
+]);
+/** The `bir` MCP server's tools that only read: always offered (D2). */
+export const READ_TOOLS = ["scenario_show", "scenario_edits", "investigate"];
+/** The ones that change a scenario: offered only after `bir scenario editing on` (D2). */
+export const EDIT_TOOLS = ["scenario_check", "scenario_edit", "scenario_undo"];
+const USAGE = {
+    show: "usage: bir scenario show <runId|scnId> [--step <n>]",
+    check: "usage: bir scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->] [--unfreeze] [--json]",
+    edit: "usage: bir scenario edit <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]\n" +
+        '                          [--freeze | --unfreeze] [--note "why"] [--force --note "why"] [--revision <n>] [--json]',
+    edits: "usage: bir scenario edits <runId|scnId> [--json]",
+    undo: "usage: bir scenario undo <runId|scnId> [--edit <sedit_id>] [--json]",
+    calc: "usage: bir scenario calc <runId> [--force [--discard-edits]]",
+    editing: "usage: bir scenario editing on|off|status",
+};
+export async function scenarioEditCommand(args, deps) {
+    switch (args.positionals[0] ?? "") {
+        case "show":
+            return show(args, deps);
+        case "check":
+            return checkOrEdit(args, deps, false);
+        case "edit":
+            return checkOrEdit(args, deps, true);
+        case "edits":
+            return listEdits(args, deps);
+        case "undo":
+            return undo(args, deps);
+        case "calc":
+            return calc(args, deps);
+        case "editing":
+            return editing(args, deps);
+        default:
+            deps.out("usage: bir scenario <list|show|calc|check|edit|edits|undo|editing|replay> …");
+            return 2;
+    }
+}
+/**
+ * The raw JSON, as it always was — scripts and the guide read it. A `scn_` id
+ * goes to `GET /scenarios/:id`, which also serves sub-task scenarios (they have
+ * no run of their own); `--step` narrows the print to that one step object.
+ */
+async function show(args, deps) {
+    const { out } = deps;
+    const target = args.positionals[1];
+    if (!target)
+        return usageError(deps, "show");
+    const byScenario = target.startsWith("scn_");
+    const reply = await deps.service("GET", byScenario ? `/scenarios/${seg(target)}` : `/recordings/runs/${seg(target)}/scenario`);
+    if ("error" in reply || reply.status !== 200) {
+        return explain(reply, args, deps, {
+            verb: "Could not read the scenario",
+            target,
+            notFound: byScenario
+                ? `No such scenario, or it is not yours: ${target}.`
+                : "No scenario for that run yet — `bir scenario calc <runId>` first.",
+        });
+    }
+    if (args.step === undefined) {
+        out(JSON.stringify(reply.body, null, 2));
+        return 0;
+    }
+    const scenario = reply.body?.scenario;
+    if (!scenario) {
+        out(`${target} has no calculated scenario yet — \`bir scenario calc ${target}\` first.`);
+        return 1;
+    }
+    if (!Array.isArray(scenario.steps)) {
+        out(`${scenario.id ?? target} is ${scenario.state ?? "not ready"}, so it has no steps to show yet.`);
+        return 1;
+    }
+    const step = scenario.steps.find((s) => s.stepIndex === args.step);
+    if (!step) {
+        const indexes = scenario.steps.map((s) => s.stepIndex).filter((n) => typeof n === "number");
+        out(`${scenario.id ?? target} has no step ${args.step}${indexes.length ? ` (its steps are ${Math.min(...indexes)}–${Math.max(...indexes)})` : " (it has no steps)"}.`);
+        return 1;
+    }
+    out(JSON.stringify(step, null, 2));
+    return 0;
+}
+/**
+ * `check` and `edit` share everything up to the request, on purpose: the
+ * service runs the same function for both (D11), so the same flags must build
+ * the same body. `check` asks and writes nothing; `edit` writes only what the
+ * check approves — or, with `--force` and a note, what it did not.
+ */
+async function checkOrEdit(args, deps, save) {
+    const sub = save ? "edit" : "check";
+    const { out } = deps;
+    const target = args.positionals[1];
+    if (!target)
+        return usageError(deps, sub);
+    if (args.step === undefined) {
+        return usageError(deps, sub, "Which step? Give --step <n>, the stepIndex `bir scenario show` prints.");
+    }
+    if (!save && (args.freeze || args.force)) {
+        return usageError(deps, sub, "`check` never saves, so --freeze and --force belong to `bir scenario edit`.");
+    }
+    if (args.freeze && args.unfreeze) {
+        return usageError(deps, sub, "--freeze and --unfreeze ask for opposite things; give one of them.");
+    }
+    const note = args.note?.trim() ? args.note : undefined;
+    if (save && args.force && !note) {
+        // Before any request: a forced save is the one kind the check did not
+        // approve, and the note is the only record of why somebody wanted it.
+        return usageError(deps, sub, '--force needs --note "why" (note_required): a change saved on purpose says why, and the history keeps it.');
+    }
+    if (!args.inputLogic && !args.outputLogic && !args.unfreeze && !(save && args.freeze)) {
+        return usageError(deps, sub, save
+            ? "Nothing to change: give --input-logic <file>, --output-logic <file>, --freeze or --unfreeze."
+            : "Nothing to check: give --input-logic <file>, --output-logic <file> or --unfreeze.");
+    }
+    if (args.inputLogic === "-" && args.outputLogic === "-") {
+        return usageError(deps, sub, "Only one of --input-logic and --output-logic can read stdin (-); put the other in a file.");
+    }
+    // Read the files before any request, so a typo in a path costs nothing.
+    const body = {};
+    const sources = [
+        [args.inputLogic, "input logic", "toolInputLogic"],
+        [args.outputLogic, "output logic", "toolOutputLogic"],
+    ];
+    for (const [spec, what, key] of sources) {
+        if (spec === undefined)
+            continue;
+        const read = await readLogic(spec, what, deps);
+        if ("problem" in read)
+            return usageError(deps, sub, read.problem);
+        body[key] = read.text;
+    }
+    const resolved = await resolveTarget(target, args, deps);
+    if ("code" in resolved)
+        return resolved.code;
+    const path = `/scenarios/${seg(resolved.id)}/steps/${args.step}`;
+    const explained = { target, step: args.step };
+    if (!save) {
+        if (args.unfreeze)
+            body.unfreeze = true;
+        const reply = await deps.service("POST", `${path}/check`, body);
+        if ("error" in reply || reply.status !== 200)
+            return explain(reply, args, deps, { verb: "Not checked", ...explained });
+        const report = reply.body?.report;
+        if (args.json) {
+            out(JSON.stringify(reply.body, null, 2));
+            return report?.ok ? 0 : 1;
+        }
+        if (!report) {
+            out("The service answered the check without a report.");
+            return 1;
+        }
+        renderReport(out, report);
+        if (report.ok) {
+            out(`Nothing saved. To save: ${editCommand(target, args)}`);
+            return 0;
+        }
+        refusal(out, report.problems ?? [], "Nothing saved, and `bir scenario edit` would refuse it", '  Fix the code and check again. If the recording itself was wrong, edit can save it on purpose: add --force --note "why".');
+        return 1;
+    }
+    if (args.freeze)
+        body.freeze = true;
+    else if (args.unfreeze)
+        body.freeze = false;
+    if (args.force)
+        body.force = true;
+    if (note)
+        body.note = note;
+    if (args.revision !== undefined)
+        body.expectedRevision = args.revision;
+    const reply = await deps.service("PATCH", path, body);
+    const answer = ("error" in reply ? undefined : reply.body);
+    const refused = !("error" in reply) && reply.status === 422 && Boolean(answer?.report);
+    if ("error" in reply || (reply.status !== 200 && !refused)) {
+        return explain(reply, args, deps, { verb: "Not saved", ...explained });
+    }
+    if (args.json) {
+        out(JSON.stringify(reply.body, null, 2));
+        return refused ? 1 : 0;
+    }
+    if (answer?.report)
+        renderReport(out, answer.report);
+    if (refused) {
+        refusal(out, answer?.report?.problems ?? [], "Not saved", '  Fix the code and try again, or save it on purpose: add --force --note "why".');
+        return 1;
+    }
+    const edit = answer?.edit;
+    const revision = answer?.chainRevision ?? edit?.chainRevisionAfter;
+    out(`Saved as ${edit?.id ?? "(no id)"} (revision ${revision ?? "?"}).` +
+        (edit?.id ? ` Undo: bir scenario undo ${target} --edit ${edit.id}` : ""));
+    if (edit?.forced) {
+        out("  Saved on purpose (--force): `bir investigate` keeps reporting it as forced.");
+        for (const p of answer?.report?.problems ?? [])
+            out(`  The check said: ${sentence(p)}`);
+    }
+    return 0;
+}
+/** What `check` printed, turned into the `edit` that would save it. */
+function editCommand(target, args) {
+    const parts = ["bir scenario edit", target, "--step", String(args.step)];
+    if (args.inputLogic)
+        parts.push("--input-logic", quoteArg(args.inputLogic));
+    if (args.outputLogic)
+        parts.push("--output-logic", quoteArg(args.outputLogic));
+    if (args.unfreeze)
+        parts.push("--unfreeze");
+    return parts.join(" ");
+}
+function quoteArg(value) {
+    return /\s/.test(value) ? `"${value}"` : value;
+}
+/**
+ * A logic file's text. UTF-8, with a byte-order mark dropped — and UTF-16 with
+ * its mark decoded, because that is what `"…" > step.js` writes in Windows
+ * PowerShell 5.1, and a service answering "SyntaxError" to a file that looks
+ * fine in every editor is a riddle nobody should have to solve.
+ */
+export function decodeLogic(bytes) {
+    if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe)
+        return bytes.subarray(2).toString("utf16le");
+    const text = bytes.toString("utf8");
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+async function readLogic(spec, what, deps) {
+    const from = spec === "-" ? "stdin" : spec;
+    let text;
+    try {
+        text = decodeLogic(spec === "-" ? await deps.readStdin() : deps.readFile(spec));
+    }
+    catch (err) {
+        return { problem: `Could not read the ${what} from ${from}: ${errText(err)}` };
+    }
+    // Trailing whitespace is a file's last newline, not code; the history reads
+    // better without it, and `check` and `edit` trim it the same way.
+    text = text.replace(/\s+$/, "");
+    if (!text)
+        return { problem: `The ${what} from ${from} is empty.` };
+    return { text };
+}
+// ── rendering the report ──────────────────────────────────────────────────────
+/** Characters of context shown on either side of the first difference. */
+const CONTEXT = 40;
+const label = (name, text) => `  ${name.padEnd(9)}${text}`;
+/**
+ * The report in the lines editSteps.md "What a person sees" shows:
+ * `input`, `output` (when the output logic changed), `later`, `answer` (when
+ * the final answer read anything before) and `mark`.
+ */
+export function renderReport(out, r) {
+    out(`Step ${r.stepIndex} (${r.toolName ?? "?"}) — checked against ${r.sourceRunId}`);
+    const i = r.input ?? { changed: false, before: "not_checked", after: "not_checked" };
+    const unchanged = i.changed ? "" : " (input logic unchanged)";
+    if (i.after === "differs") {
+        const d = i.firstDifference ?? firstDifference(i.computed, i.recorded);
+        out(label("input", `differs from the recorded call${d ? ` at character ${d.at}` : ""}${unchanged}`));
+        if (d) {
+            out(`           computed  ${around(d.computed, d.at)}`);
+            out(`           recorded  ${around(d.recorded, d.at)}`);
+        }
+    }
+    else if (i.after === "throws") {
+        out(label("input", `throws: ${i.error ?? "(no message)"}${unchanged}`));
+    }
+    else {
+        out(label("input", `${inputPhrase(i.after, r.verifiable)}${unchanged}`));
+    }
+    if (r.output?.changed) {
+        const o = r.output;
+        out(label("output", o.status === "runs"
+            ? `runs; keeps ${o.emittedKeys?.length ? o.emittedKeys.join(", ") : "nothing"}`
+            : o.status === "throws"
+                ? `throws: ${o.error ?? "(no message)"}`
+                : o.status === "not_object"
+                    ? "does not return an object"
+                    : "unchanged"));
+    }
+    const later = r.later ?? [];
+    const regressed = later.filter((l) => l.regressed);
+    if (later.length === 0) {
+        out(label("later", "no later steps"));
+    }
+    else if (regressed.length === 0) {
+        const still = later.filter((l) => l.after === "reproduces").map((l) => l.stepIndex);
+        out(label("later", still.length === 0
+            ? "no later step reproduced before, so none can break"
+            : still.length === 1
+                ? `step ${still[0]} still reproduces`
+                : `steps ${still.join(", ")} still reproduce`));
+    }
+    else {
+        for (const l of regressed) {
+            out(label("later", `step ${l.stepIndex} (${l.toolName ?? "?"}) reproduced before; now it ${laterPhrase(l.after)}`));
+        }
+    }
+    if (r.answer?.informativeBefore) {
+        out(label("answer", r.answer.informativeAfter
+            ? "still gets its values"
+            : "no longer gets its values: the final answer's logic stops finding what it reads"));
+    }
+    if (r.mark?.before && r.mark.after) {
+        const { before, after } = r.mark;
+        out(label("mark", before.marked === after.marked && before.why === after.why
+            ? before.marked
+                ? `${markWord(before)} → stays marked`
+                : "runs by itself"
+            : `${markWord(before)} → ${markWord(after)}`));
+    }
+}
+function inputPhrase(status, verifiable) {
+    switch (status) {
+        case "reproduces":
+            return "reproduces the recorded call";
+        case "copy":
+            return "is a copy: it returns the recorded call whatever the parameters say";
+        case "not_checked":
+            return verifiable
+                ? "not checked: the recorded call is plain text, not an object"
+                : "not checked: the step comes after a sub-task call, whose outputs the check cannot rebuild";
+        case "differs":
+            return "differs from the recorded call";
+        case "throws":
+            return "throws";
+        default:
+            return String(status);
+    }
+}
+function laterPhrase(status) {
+    switch (status) {
+        case "differs":
+            return "differs from its recorded call";
+        case "throws":
+            return "throws";
+        case "copy":
+            return "is a copy of its recorded call";
+        case "not_checked":
+            return "cannot be checked";
+        default:
+            return status;
+    }
+}
+/** A report's `MarkState` or a history entry's `StepState`, in the words the report uses. */
+const markWord = (m) => (m.marked ?? m.nondeterministic)
+    ? `needs a judgement (${m.why ?? m.nondeterministicWhy ?? "?"})`
+    : "runs by itself";
+/**
+ * The report's `firstDifference`, or the same computed here from `computed` and
+ * `recorded` when the service sent only those: whitespace-squashed JSON text,
+ * as the service compares it.
+ */
+function firstDifference(computed, recorded) {
+    if (computed === undefined || recorded === undefined)
+        return undefined;
+    const squash = (v) => (JSON.stringify(v) ?? String(v)).replace(/\s+/g, " ");
+    const a = squash(computed);
+    const b = squash(recorded);
+    let at = 0;
+    while (at < a.length && at < b.length && a[at] === b[at])
+        at += 1;
+    return { at, computed: a, recorded: b };
+}
+/**
+ * About {@link CONTEXT} characters either side of `at`. A text already that
+ * short — a window the service cut itself, or a small call — is printed whole.
+ */
+export function around(text, at) {
+    if (text.length <= 2 * CONTEXT + 2)
+        return text;
+    const from = Math.max(0, Math.min(at, text.length) - CONTEXT);
+    const to = Math.min(text.length, from + 2 * CONTEXT);
+    return `${from > 0 ? "…" : ""}${text.slice(from, to)}${to < text.length ? "…" : ""}`;
+}
+/** One problem sentence, continuing a line that already opened with "Not saved:". */
+function sentence(problem) {
+    const text = problem.trim();
+    const lowered = /^[A-Z][a-z]/.test(text) ? text[0].toLowerCase() + text.slice(1) : text;
+    return /[.!?]$/.test(lowered) ? lowered : `${lowered}.`;
+}
+function refusal(out, problems, opening, hint) {
+    const list = problems.length ? problems : ["the check did not pass"];
+    if (list.length === 1) {
+        out(`${opening}: ${sentence(list[0])}`);
+    }
+    else {
+        out(`${opening}:`);
+        for (const p of list)
+            out(`  - ${sentence(p)}`);
+    }
+    out(hint);
+}
+// ── edits / undo ──────────────────────────────────────────────────────────────
+async function fetchEdits(scenarioId, deps) {
+    const reply = await deps.service("GET", `/scenarios/${seg(scenarioId)}/edits`);
+    if ("error" in reply || reply.status !== 200)
+        return { reply };
+    const edits = reply.body?.edits;
+    return { edits: Array.isArray(edits) ? edits : [] };
+}
+async function listEdits(args, deps) {
+    const { out } = deps;
+    const target = args.positionals[1];
+    if (!target)
+        return usageError(deps, "edits");
+    const resolved = await resolveTarget(target, args, deps);
+    if ("code" in resolved)
+        return resolved.code;
+    const reply = await deps.service("GET", `/scenarios/${seg(resolved.id)}/edits`);
+    if ("error" in reply || reply.status !== 200) {
+        return explain(reply, args, deps, { verb: "Could not read the history", target });
+    }
+    if (args.json) {
+        out(JSON.stringify(reply.body, null, 2));
+        return 0;
+    }
+    const edits = reply.body?.edits ?? [];
+    if (edits.length === 0) {
+        out(`No hand edits of ${target}.`);
+        return 0;
+    }
+    // Ids are printed whole: they are what `undo --edit` takes. The detail line
+    // is indented rather than aligned under the date, which a 42-character id
+    // would push past most terminals' width.
+    for (const e of edits) {
+        const note = e.note ? `  "${e.note.replace(/\s+/g, " ")}"` : "";
+        out(`${e.id}  ${when(e.createdAt)}  step ${e.stepIndex}  ${String(e.kind).padEnd(7)} revision ${e.chainRevisionBefore} → ${e.chainRevisionAfter}${note}`);
+        out(`    ${editSummary(e)}`);
+    }
+    return 0;
+}
+/** The second line of an `edits` entry: what the edit changed, and what became of it. */
+function editSummary(e) {
+    const parts = [];
+    if (e.kind === "revert" && e.revertsEditId)
+        parts.push(`undoes ${e.revertsEditId}`);
+    const b = e.before;
+    const a = e.after;
+    if (b && a) {
+        if ((b.toolInputLogic ?? null) !== (a.toolInputLogic ?? null))
+            parts.push("input logic changed");
+        if ((b.toolOutputLogic ?? null) !== (a.toolOutputLogic ?? null))
+            parts.push("output logic changed");
+        if (Boolean(b.nondeterministic) !== Boolean(a.nondeterministic) || (b.nondeterministicWhy ?? null) !== (a.nondeterministicWhy ?? null)) {
+            parts.push(`${markWord(b)} → ${markWord(a)}`);
+        }
+    }
+    if (e.forced)
+        parts.push("saved on purpose (--force)");
+    if (e.revertedAt)
+        parts.push(`undone ${when(e.revertedAt)}`);
+    if (e.replacedAt)
+        parts.push(`replaced by a recalculation ${when(e.replacedAt)}`);
+    return parts.length ? parts.join("; ") : "no change to the code or the mark";
+}
+/**
+ * Undo puts one step back as it was before its newest edit (D9). Without
+ * `--edit`, that is the newest entry nothing has put back and no
+ * recalculation replaced — which is by construction the newest of its step.
+ * An undo is itself such an entry, so a second `undo` redoes.
+ */
+export function newestUndoable(edits) {
+    // Newest first, as the service lists them; sorted again so a reordering
+    // there cannot make this undo the wrong one.
+    return [...edits]
+        .sort((x, y) => (x.createdAt < y.createdAt ? 1 : x.createdAt > y.createdAt ? -1 : 0))
+        .find((e) => !e.revertedAt && !e.replacedAt);
+}
+async function undo(args, deps) {
+    const { out } = deps;
+    const target = args.positionals[1];
+    if (!target)
+        return usageError(deps, "undo");
+    if (args.edit !== undefined && !/^sedit_[\w-]+$/.test(args.edit)) {
+        return usageError(deps, "undo", `--edit takes a sedit_… id, as \`bir scenario edits\` prints it; got ${args.edit}.`);
+    }
+    const resolved = await resolveTarget(target, args, deps);
+    if ("code" in resolved)
+        return resolved.code;
+    let editId = args.edit;
+    if (!editId) {
+        const listed = await fetchEdits(resolved.id, deps);
+        if ("reply" in listed)
+            return explain(listed.reply, args, deps, { verb: "Could not read the history", target });
+        const pick = newestUndoable(listed.edits);
+        if (!pick) {
+            return localFailure(args, deps, "nothing_to_undo", `Nothing to undo: ${target} has no hand edit that can be undone.`);
+        }
+        editId = pick.id;
+    }
+    const body = {};
+    if (args.note?.trim())
+        body.note = args.note;
+    if (args.revision !== undefined)
+        body.expectedRevision = args.revision;
+    const reply = await deps.service("POST", `/scenarios/${seg(resolved.id)}/edits/${seg(editId)}/revert`, body);
+    if ("error" in reply || reply.status !== 200) {
+        return explain(reply, args, deps, {
+            verb: "Not undone",
+            target,
+            notFound: `Not undone (not_found): ${target} has no edit ${editId}, or it is not yours.`,
+        });
+    }
+    if (args.json) {
+        out(JSON.stringify(reply.body, null, 2));
+        return 0;
+    }
+    const b = reply.body;
+    const entry = b?.edit;
+    const revision = b?.chainRevision ?? entry?.chainRevisionAfter;
+    out(`Step ${entry?.stepIndex ?? "?"} is back as it was before ${entry?.revertsEditId ?? editId} (revision ${revision ?? "?"}).` +
+        (entry?.id ? ` Redo: bir scenario undo ${target} --edit ${entry.id}` : ""));
+    return 0;
+}
+// ── calc ──────────────────────────────────────────────────────────────────────
+/**
+ * `calc` lives here because of one answer: a recalculation rebuilds every
+ * step from the recording, so the service refuses `--force` on a plan with
+ * hand edits (D4) unless `--discard-edits` says to throw them away.
+ */
+async function calc(args, deps) {
+    const { out } = deps;
+    const target = args.positionals[1];
+    if (!target)
+        return usageError(deps, "calc");
+    if (args.discardEdits && !args.force) {
+        return usageError(deps, "calc", "--discard-edits only means something with --force (a recalculation in place).");
+    }
+    const reply = await deps.service("POST", `/recordings/runs/${seg(target)}/calculate`, args.force ? { force: true, ...(args.discardEdits ? { discardEdits: true } : {}) } : {});
+    if ("error" in reply)
+        return explain(reply, args, deps, { verb: "Could not start calculation", target });
+    if (args.json) {
+        out(JSON.stringify(reply.body ?? null, null, 2));
+        return reply.status === 202 ? 0 : 1;
+    }
+    const { status, body } = reply;
+    const code = body?.error;
+    if (status === 202) {
+        const b = body;
+        out(`Calculating ${b.scenarioId ?? ""} — poll with \`bir scenario show ${target}\`.`);
+        return 0;
+    }
+    if (status === 409 && code === "scenario_has_edits") {
+        const steps = body.editedSteps;
+        const list = Array.isArray(steps) ? steps.map(String) : [];
+        const which = list.length === 0 ? "some steps were" : list.length === 1 ? `step ${list[0]} was` : `steps ${list.join(", ")} were`;
+        out(`Not recalculated: ${which} edited by hand, and a recalculation rebuilds every step.`);
+        out(`  To recalculate anyway and discard the edits: bir scenario calc ${target} --force --discard-edits`);
+        out("  (the edits stay in `bir scenario edits`, marked replaced)");
+        return 1;
+    }
+    if (status === 409 && code === "calculation_in_flight") {
+        out("Another calculation of yours is running, and the service calculates one at a time. Try again when it is ready.");
+        return 1;
+    }
+    if (status === 409) {
+        out("That run already has a scenario. Re-derive it in place with --force.");
+        return 1;
+    }
+    if (status === 503) {
+        out("The service has no Anthropic configuration, so it cannot calculate scenarios.");
+        return 1;
+    }
+    out(`Could not start calculation (HTTP ${status}): ${JSON.stringify(body)}`);
+    return 1;
+}
+// ── editing on|off|status ─────────────────────────────────────────────────────
+/**
+ * Which tools this project's `bir` MCP server offers (D2). Stored in the
+ * project's record in `installed.json`, next to the replay switches, so a
+ * server Claude Code starts with its own environment reads the same answer.
+ * The server reads it when the session lists its tools, hence the restart.
+ */
+function editing(args, deps) {
+    const { out, cwd } = deps;
+    const word = args.positionals[1];
+    if (word !== "on" && word !== "off" && word !== "status")
+        return usageError(deps, "editing");
+    const sidecar = readSidecar();
+    if (word !== "status") {
+        if (!setEditing(sidecar, cwd, word === "on")) {
+            out("This directory has not been installed — run `bir setup` (or `bir install --replay`) here first.");
+            return 1;
+        }
+        writeSidecar(sidecar);
+    }
+    describeEditing(out, sidecar, cwd);
+    if (word !== "status")
+        out("Restart Claude Code in this project: a running session does not see the change.");
+    return 0;
+}
+function describeEditing(out, sidecar, cwd) {
+    const on = editingEnabled(sidecar, cwd);
+    out(`Scenario editing for ${cwd}: ${on ? "on" : "off"}`);
+    if (!projectRecord(sidecar, cwd)) {
+        out("  (this directory has not been installed — `bir setup` here first)");
+        return;
+    }
+    if (!hasScenarioServer(sidecar, cwd)) {
+        out("  (no `bir` MCP server is installed here, so no tool is offered at all — `bir install --replay` adds it)");
+    }
+    out(`  the bir MCP server offers  ${READ_TOOLS.join(", ")}  (they read)`);
+    if (on)
+        out(`                        and  ${EDIT_TOOLS.join(", ")}  (they change a scenario)`);
+    else
+        out(`  \`bir scenario editing on\` adds ${EDIT_TOOLS.join(", ")}  (they change a scenario)`);
+    out("  The `bir scenario` commands work either way: this switch decides only the MCP tools.");
+}
+function hasScenarioServer(sidecar, cwd) {
+    const here = normalizePath(cwd);
+    return Object.entries(sidecar.servers ?? {}).some(([key, record]) => key.endsWith(`::${SCENARIO_SERVER_KEY}`) && normalizePath(record.cwd) === here);
+}
+// ── shared ────────────────────────────────────────────────────────────────────
+const seg = (id) => encodeURIComponent(id);
+const when = (iso) => iso ? iso.replace("T", " ").replace(/\.\d+Z$/, "Z") : "—";
+function usageError(deps, sub, why) {
+    if (why)
+        deps.out(why);
+    deps.out(USAGE[sub] ?? "usage: bir scenario …");
+    return 2;
+}
+/** A failure this side decided on; `--json` still gets JSON, in the service's `{error, details}` shape. */
+function localFailure(args, deps, code, text) {
+    deps.out(args.json ? JSON.stringify({ error: code, details: text }, null, 2) : text);
+    return 1;
+}
+/**
+ * A `run_` id is the recording's; the routes that change a scenario take its
+ * `scn_` id (D7). A `scn_` id is used as it is — sub-task scenarios have
+ * nothing else.
+ */
+async function resolveTarget(target, args, deps) {
+    if (target.startsWith("scn_"))
+        return { id: target };
+    const reply = await deps.service("GET", `/recordings/runs/${seg(target)}/scenario`);
+    if ("error" in reply || reply.status !== 200) {
+        return {
+            code: explain(reply, args, deps, {
+                verb: "Could not find the scenario",
+                target,
+                notFound: `No scenario for ${target}: it is not a run of yours, or nothing was calculated from it yet (\`bir scenario calc ${target}\`).`,
+            }),
+        };
+    }
+    const id = reply.body?.scenario?.id;
+    if (typeof id !== "string") {
+        return {
+            code: localFailure(args, deps, "no_scenario", `${target} has no calculated scenario yet — \`bir scenario calc ${target}\` first.`),
+        };
+    }
+    return { id };
+}
+/**
+ * Every answer that is not the one asked for, in words — with the service's
+ * error code in brackets, because that is what the guide's troubleshooting
+ * table is keyed on. `--json` gets the service's body unchanged.
+ */
+function explain(reply, args, deps, e) {
+    const { out } = deps;
+    if ("error" in reply) {
+        if (args.json)
+            out(JSON.stringify({ error: "service_unreachable", details: reply.error }, null, 2));
+        else
+            out(`Could not reach the service: ${reply.error}`);
+        return 1;
+    }
+    if (args.json) {
+        out(JSON.stringify(reply.body ?? null, null, 2));
+        return 1;
+    }
+    const body = (reply.body && typeof reply.body === "object" ? reply.body : {});
+    const code = typeof body.error === "string" ? body.error : "";
+    const target = e.target ?? "<id>";
+    const stepFlag = e.step !== undefined ? ` --step ${e.step}` : "";
+    if (reply.status === 404) {
+        out(e.notFound ??
+            `${e.verb} (not_found): no such scenario, step or edit — or it is not yours. Only a scenario's owner can see or change it.`);
+        return 1;
+    }
+    if (reply.status === 401) {
+        out(`${e.verb}: the service did not accept this machine's session (HTTP 401) — run \`bir login\`.`);
+        return 1;
+    }
+    switch (code) {
+        case "invalid_input": {
+            const details = brief(body.details);
+            out(`${e.verb} (invalid_input): the service found the request invalid${details ? ` — ${details}` : ""}.`);
+            return 1;
+        }
+        case "not_a_tool_step":
+            out(`${e.verb} (not_a_tool_step): step ${e.step ?? "?"} is a sub-task call row, not a tool step. Call rows belong to the service; only tool steps can be edited.`);
+            return 1;
+        case "nothing_to_change":
+            out(`${e.verb} (nothing_to_change): give --input-logic, --output-logic, --freeze or --unfreeze.`);
+            return 1;
+        case "note_required":
+            out(`${e.verb} (note_required): --force needs --note "why".`);
+            return 1;
+        case "not_ready":
+        case "scenario_calculating":
+            out(`${e.verb} (${code}): the scenario is not ready, or a recalculation of it is running. Wait for it to finish (\`bir scenario show ${target}\`), then try again.`);
+            return 1;
+        case "revision_changed": {
+            const now = typeof body.chainRevision === "number" ? ` — it is at revision ${body.chainRevision} now` : "";
+            out(`${e.verb} (revision_changed): the plan changed since it was read${now}. Show it again (\`bir scenario show ${target}${stepFlag}\`), check again, then save again.`);
+            return 1;
+        }
+        case "not_latest_edit": {
+            const latest = typeof body.latestEditId === "string" ? body.latestEditId : "<the newer edit>";
+            out(`${e.verb} (not_latest_edit): a newer edit of the same step follows it. Undo that one first:`);
+            out(`  bir scenario undo ${target} --edit ${latest}`);
+            return 1;
+        }
+        case "edit_replaced":
+            out(`${e.verb} (edit_replaced): a recalculation replaced the plan after that edit. It stays in \`bir scenario edits\`, but there is nothing left to undo.`);
+            return 1;
+        case "rate_limited": {
+            const ms = typeof body.retryAfterMs === "number" ? body.retryAfterMs : undefined;
+            out(`${e.verb} (rate_limited): too many checks, edits and undos in a minute. Try again${ms !== undefined ? ` in ${Math.ceil(ms / 1000)} s` : " in a minute"}.`);
+            return 1;
+        }
+        default: {
+            const details = brief(body.details);
+            out(`${e.verb} (HTTP ${reply.status}${code ? `, ${code}` : ""})${details ? `: ${details}` : ""}.`);
+            return 1;
+        }
+    }
+}
+/** A service's `details`, short enough for one line. */
+function brief(details) {
+    if (details === undefined || details === null)
+        return "";
+    const text = typeof details === "string" ? details : JSON.stringify(details);
+    return text.length > 300 ? `${text.slice(0, 300)}…` : text;
+}
+//# sourceMappingURL=scenario-edit.js.map