toolroll 0.9.104 → 0.9.105

package/dist/release-approval.js

@@ -1,19 +1,3 @@
-/**
- * One-tap release approval (docs/plans/trusted-release-reports.md, slice A v3): the plane's side of one push, one
- * screen and one proof for a release a person must approve.
- *
- * - `releaseApprovalCard`: the authoritative card snapshot of a release task waiting for its person, for the sheet
- *   (`/t/<id>/release`) and `toolroll release approve`: either sealed form (release terms or a release check's purpose),
- *   the change list, GitHub CI as the coordinator last read it on the exact commit, why it can't be approved now (shown,
- *   never hidden) and the card digest, which binds all of it.
- * - `approveReleaseCard`: the one wrapper both doors call. It rebuilds the card, compares the digest the person saw,
- *   re-reads the store's parts inside one transaction and only then passes THAT snapshot's scope digest into the
- *   unchanged transactional `approve()` the caller hands in. The digest is never swapped after the person was asked.
- * - The notification's whole life: `noteReleaseReady` (one per task and scope digest, older ones resolved), the push
- *   class derived at send time from the plane's own state (`releasePushOf`), `noteReleaseStopped` for a manual
- *   release's stop, and the coordinator's CI snapshots (`recordReleaseCi`).
- * Nothing here proves a person, widens a proof or seals anything itself.
- */
 import { createHash } from "node:crypto";
 import { lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
 import { join } from "node:path";
@@ -24,23 +8,14 @@ import { releaseProgressFor } from "./store.js";
 import { taskArchived } from "./task-archive.js";
 import { cleanTerminalLine } from "./terminal-text.js";
 import { ciName, ciWords, refusalOf, releaseCiOf, RELEASE_CI_SEEN_ACTION } from "./release-refusal.js";
-// The CI reading and the refusals live in release-refusal.ts, so scope.ts approve() can read them without a cycle.
 export { ciWords, releaseApprovalRefusal, releaseCiOf, RELEASE_CI_SEEN_ACTION } from "./release-refusal.js";
 const SHA = /^[0-9a-f]{40}$/;
 const DIGEST = /^[0-9a-f]{64}$/;
-/** A scope digest as scope.ts writes it. */
 const SCOPE_DIGEST = /^[0-9a-f]{32,64}$/;
 const sha256 = (text) => createHash("sha256").update(text).digest("hex");
-// ---- GitHub CI as the coordinator read it -------------------------------------------------------------------------
-/**
- * Record what the coordinator just read of the pull request's CI on `candidate` (its verdict and every check's newest
- * attempt), when it differs from the last reading recorded: the sheet and the CLI show it, and the card digest binds
- * it. The coordinator is Toolroll's own runtime reading GitHub through the plane's recorded repository.
- */
 export function recordReleaseCi(store, input) {
     if (!SHA.test(input.candidate) || store.lookupRef(input.taskId) === null)
         return false;
-    // The newest attempt of each check (the adapter lists attempts oldest first), by name.
     const latest = new Map();
     for (const run of input.runs.slice(0, 2_000)) {
         const name = ciName(run.name);
@@ -57,13 +32,9 @@ export function recordReleaseCi(store, input) {
         action: RELEASE_CI_SEEN_ACTION, outcome: input.state, source: "work", detail });
     return true;
 }
-/** What of a CI reading the card binds: its state and each check's attempt, whether it finished, and how. Queued and
- * in progress read alike (neither is finished); the time it was read is not bound. */
 export function ciBinding(ci) {
     return ci === null ? null : { candidate: ci.candidate, state: ci.state, failed: ci.failed, runs: ci.runs.map(run => [run.id, run.name, run.status === "completed", run.conclusion]) };
 }
-/** A release task from the plane's own state: a sealed form (terms or a release check's purpose) whose repository is the
- * task's project and whose approved commit is the scope's candidate. Never from a title or a task id. */
 export function releaseTaskOf(store, taskId) {
     const ref = store.lookupRef(taskId);
     const scope = store.getScope(taskId);
@@ -72,7 +43,6 @@ export function releaseTaskOf(store, taskId) {
         return null;
     return { ref: { id: ref.id, repo: ref.repo }, scope, seal };
 }
-/** The authoritative card for a release task waiting for its person, or why there is none. Reads only. */
 export function releaseApprovalCard(store, taskId, options = {}) {
     const found = releaseTaskOf(store, taskId);
     if (found === null)
@@ -89,8 +59,6 @@ export function releaseApprovalCard(store, taskId, options = {}) {
     const digest = sha256(`release-sheet:v1:${JSON.stringify([card.digest, scope.digest, ciBinding(ci), refusal, approved])}`);
     return { ok: true, card: { taskId, taskRef: ref.id, repo: ref.repo, scope, seal, card, terms, ci, refusal, approved, stopped, digest } };
 }
-/** What approving does, in the sheet's and the CLI's words: the consequence, the check's access, and whether later
- * commits carry. */
 export function releaseConsequence(card) {
     const id = card.seal.identity;
     const carries = card.seal.kind === "terms" && card.seal.terms.policy.carry;
@@ -100,12 +68,6 @@ export function releaseConsequence(card) {
         carries ? "Later commits that only change tests, docs or the changelog carry this approval." : "Every later commit asks again.",
     ];
 }
-/**
- * The one card-approval wrapper (Codex round 2, finding 2): rebuild the authoritative card and compare the digest the
- * person saw; then, in one transaction, re-read the store's parts (the scope digest, the CI reading, the refusal state)
- * and refuse on any change; then hand THAT snapshot's scope digest to `approveNow`, the caller's unchanged
- * transactional `approve()`, which proves the person and seals. Nothing here proves anyone.
- */
 export function approveReleaseCard(store, input) {
     if (!DIGEST.test(input.cardDigest))
         return { ok: false, reason: "changed", message: "This release changed while you were reading it. Read it again." };
@@ -132,20 +94,11 @@ export function approveReleaseCard(store, input) {
         return result.ok ? { ok: true, scope: result.scope } : { ok: false, reason: "approve", result };
     });
 }
-// ---- notifications --------------------------------------------------------------------------------------------
 export const RELEASE_READY_KIND = "release-ready";
 export const RELEASE_STOPPED_KIND = "release-stopped";
-/** The one push phrase for a release waiting on its person (push.ts PUSH_WORDS.release). */
 export const RELEASE_PUSH_WORDS = "A release is ready for your approval";
 const READY_KEY = /^release-ready:([1-9][0-9]{0,14}):([0-9a-f]{32,64})$/;
-/** The sheet's own address for a task (the in-app link; a push carries the opaque `/approve/<task ref>` instead). */
 export const releaseSheetHref = (taskId) => `/t/${encodeURIComponent(taskId)}/release`;
-/**
- * The coordinator asked a person (on entering the approval step, a fresh filing or a resumed one): one notification per
- * task and stable scope digest, so a crash between filing and asking is healed by the next run and a repeat says nothing
- * new. Every older `release-ready` row of the project (another task or digest) is resolved first. Nothing when the task
- * isn't a release waiting for a person.
- */
 export function noteReleaseReady(store, input) {
     return store.transact(() => {
         const found = releaseTaskOf(store, input.taskId);
@@ -164,16 +117,9 @@ export function noteReleaseReady(store, input) {
             subject: `Release ${id.packageVersion} is ready for your approval`, body }, input.now);
     });
 }
-/** Resolve a task's `release-ready` rows (it was approved, or the release stopped): a push not sent yet never is. */
 export function retireReleaseReady(store, taskRef, now) {
     return Number(store.handle.prepare("UPDATE notification SET resolved_at = ? WHERE kind = ? AND resolved_at IS NULL AND task_ref = ?").run(now.toISOString(), RELEASE_READY_KIND, taskRef).changes);
 }
-/**
- * The push class `release` and its link, derived at send time from the plane's own state, never from a title, a task id,
- * the stored link or the stored class: the row is a `release-ready` row for exactly its task ref and a scope digest, and
- * that task is a release scope (terms or a release check's purpose, its candidate the approved commit), not put away,
- * not approved, at that same digest. Null otherwise.
- */
 export function releasePushOf(store, notification) {
     if (notification.kind !== RELEASE_READY_KIND || notification.taskRef === null || notification.resolvedAt !== null)
         return null;
@@ -190,16 +136,9 @@ export function releasePushOf(store, notification) {
         return null;
     return { link: `/approve/${notification.taskRef}` };
 }
-/** A `release-ready` row that no longer stands (the push pass resolves it instead of sending it). */
 export function releaseReadyObsolete(store, notification) {
     return notification.kind === RELEASE_READY_KIND && releasePushOf(store, notification) === null;
 }
-/**
- * A person's release stopped (CI failed, the check failed, the deploy, the merge, the tag or publication failed, or it
- * stopped waiting): one attention notification per task, step and reason, with the stop's words in the app (the push
- * says only the fixed attention phrase). Its `release-ready` row is resolved, except while it only stopped waiting
- * for the approval (the sheet still approves it then).
- */
 export function noteReleaseStopped(store, input) {
     const ref = store.lookupRef(input.taskId);
     if (ref === null)
@@ -216,8 +155,6 @@ export function noteReleaseStopped(store, input) {
             subject: `Release${seal === null ? "" : ` ${seal.identity.packageVersion}`} stopped at ${step}`, body: words === "" ? "The release stopped. Open it to see why." : words }, input.now);
     });
 }
-// ---- the terminal -------------------------------------------------------------------------------------------------
-/** The card as the CLI prints it, every line control-free (src/terminal-text.ts). */
 export function releaseCardLines(card) {
     const id = card.seal.identity;
     const changes = card.card.changes;
@@ -242,7 +179,6 @@ export function releaseCardLines(card) {
 const BRANCH = /^[A-Za-z0-9._/-]{1,255}$/;
 const TASK_ID = /^[A-Za-z0-9._-]{1,200}$/;
 const VERSION = /^\d+\.\d+\.\d+$/;
-/** A journal's own fields, strictly; null when any is missing or not its exact shape. */
 export function readWaitingJournal(file, raw, expectedFile) {
     if (raw === null || typeof raw !== "object" || Array.isArray(raw))
         return null;
@@ -261,7 +197,6 @@ export function readWaitingJournal(file, raw, expectedFile) {
         return null;
     if (candidate === null || typeof candidate !== "object" || typeof candidate["sha"] !== "string" || !SHA.test(candidate["sha"]))
         return null;
-    // The file must be the one its own branch maps to: two branches that map to one file name never stand in for each other.
     if (expectedFile(j["branch"]) !== file)
         return null;
     return { file, branch: j["branch"], checkout: j["checkout"], taskId: task["id"], scopeDigest: task["scopeDigest"], candidate: candidate["sha"], version: j["packageVersion"], pr: j["pr"] };
@@ -272,11 +207,6 @@ const real = (path) => { try {
 catch {
     return null;
 } };
-/**
- * Whether a journal (discovery only) names exactly the release the plane sealed: the task is a release scope whose
- * sealed identity has this exact branch, version, pull request and candidate at this scope digest, and the journal's
- * checkout, the task's project and the sealed repository are one real folder (`repo` too, when given). Why not, in words.
- */
 export function journalMatchesPlane(store, journal, repo) {
     const found = releaseTaskOf(store, journal.taskId);
     if (found === null)
@@ -294,7 +224,6 @@ export function journalMatchesPlane(store, journal, repo) {
         return { ok: false, why: `${journal.branch} isn't a release of ${repo}` };
     return { ok: true };
 }
-/** Every release journal in the state folder, read strictly; unreadable ones are counted, never guessed at. */
 export function waitingJournals(stateDir, expectedFile) {
     const folder = join(stateDir, "releases");
     let names = [];
@@ -330,9 +259,6 @@ export function waitingJournals(stateDir, expectedFile) {
     }
     return { journals, unreadable };
 }
-/** A release as Home names it (docs/plans/home-other-asks.md, part 1): its version, and why it can't take a yes now
- * in the sheet's own words (`refusalOf`, the one source), or null when this isn't a release. Reads only; Home never
- * approves one, it links to the sheet. */
 export function releaseAskOf(store, taskId) {
     const found = releaseTaskOf(store, taskId);
     if (found === null)

package/dist/release-authority.js

@@ -1,20 +1,8 @@
-/**
- * The release authority record, read (docs/plans/release-once.md, schema v135): one generation of a release a person
- * approved, its carried commits and its deploy and merge operations. Kept apart from store.ts so the one live-release
- * reader (scope.ts liveReleaseOf) can read it without a module cycle; every write is in store.ts.
- */
 import { readReleasePolicy } from "./contracts/release-terms.js";
 export const LIVE_RELEASE_STATES = ["open", "deploying", "merge-reserved"];
-/**
- * Whether an authority's approval has run out at `now`. Nothing writes the `expired` state: expiry is worked out from
- * `expires_at` here, and every reader that asks whether an authority is still good asks through this (or
- * releaseStateAt). The one SQL reader, approval-authority.ts releaseStandsSql, states the same rule in SQL.
- */
 export function releaseExpiredAt(a, now) {
     return a.state === "expired" || a.expiresAt <= now.toISOString();
 }
-/** An authority's state as read at `now`: a live one (open, deploying, merge-reserved) past its time reads as `expired`;
- * an ended one keeps the state it ended in. */
 export function releaseStateAt(a, now) {
     return LIVE_RELEASE_STATES.includes(a.state) && releaseExpiredAt(a, now) ? "expired" : a.state;
 }
@@ -40,7 +28,6 @@ function readReleaseAuthority(row) {
         expiresAt: String(row["expires_at"]), createdAt: String(row["created_at"]), endedAt: text("ended_at"), endedBy: text("ended_by"),
     };
 }
-/** A sealed policy read strictly; null when this runtime doesn't know it (and so refuses to carry under it). */
 function readReleasePolicyStrict(json) {
     let parsed;
     try {
@@ -82,12 +69,10 @@ export function releaseAuthority(store, id) {
     const row = store.handle.prepare("SELECT * FROM release_authority WHERE id = ?").get(id);
     return row === undefined ? null : readReleaseAuthority(row);
 }
-/** The newest generation of a release, whatever its state. */
 export function newestReleaseGeneration(store, repo, version, pr) {
     const row = store.handle.prepare("SELECT * FROM release_authority WHERE repo = ? AND version = ? AND pr = ? ORDER BY generation DESC LIMIT 1").get(repo, version, pr);
     return row === undefined ? null : readReleaseAuthority(row);
 }
-/** The release authority a task belongs to — as an anchor (any generation) or as a carried commit — or null. */
 export function releaseAuthorityOfTask(store, taskId) {
     const carryRow = store.handle.prepare("SELECT * FROM release_carry WHERE task_id = ?").get(taskId);
     if (carryRow !== undefined) {
@@ -98,15 +83,11 @@ export function releaseAuthorityOfTask(store, taskId) {
     const row = store.handle.prepare("SELECT * FROM release_authority WHERE anchor_task = ? ORDER BY id DESC LIMIT 1").get(taskId);
     return row === undefined ? null : { authority: readReleaseAuthority(row), carry: null };
 }
-/** Whether a task belongs to any release authority (anchor or carried), from the records alone. */
-/** "Carry release approvals when checks aren't sandboxed": a project setting, newest choice wins (a ledger row each);
- * off by default. Turning it on is a person's own proven act (release-cli.ts); turning it off is anyone's. */
 export const UNSANDBOXED_CARRY_ACTION = "release unsandboxed carrying changed";
 export function carriesUnsandboxed(store, repo) {
     const row = store.handle.prepare("SELECT outcome FROM action_ledger WHERE repo = ? AND action = ? ORDER BY id DESC LIMIT 1").get(repo, UNSANDBOXED_CARRY_ACTION);
     return row !== undefined && row["outcome"] === "on";
 }
-/** How far a check reaches, narrowest first. */
 export const CHECK_ACCESS_WIDTH = Object.freeze({ sandboxed: 0, "sign-ins": 1, unsandboxed: 2 });
 export function belongsToRelease(store, taskId) {
     return store.handle.prepare("SELECT 1 AS hit FROM release_authority WHERE anchor_task = ? UNION ALL SELECT 1 FROM release_carry WHERE task_id = ? LIMIT 1").get(taskId, taskId) !== undefined;
@@ -125,14 +106,9 @@ export function releaseOperation(store, id) {
     const row = store.handle.prepare("SELECT * FROM release_operation WHERE id = ?").get(id);
     return row === undefined ? null : readReleaseOperation(row);
 }
-/** Operations nobody has settled yet: until each is reconciled, nothing new starts. */
 export function outstandingReleaseOperations(store, authority) {
     return releaseOperations(store, authority).filter(one => one.state === "reserved" || one.state === "running" || one.state === "unknown");
 }
-/**
- * Why a person's seal of these release terms can't open a new generation now, in words, or null. A live generation is
- * superseded by the new one — but never while one of its operations is unsettled, and never once its merge started.
- */
 export function releaseSealProblem(store, terms) {
     const live = newestReleaseGeneration(store, terms.repo, terms.packageVersion, terms.pr);
     if (live === null)
@@ -146,21 +122,10 @@ export function releaseSealProblem(store, terms) {
     }
     return null;
 }
-// ------------------------------------------------------------------ automatic release approval (auto-approve-green.md)
-/** "Release approval: Ask me / Approve automatically when checks pass": a project setting, newest choice wins (a ledger
- * row each); `ask` by default. Turning it on is a person's credential act (a password typed now); off is one click. */
 export const RELEASE_APPROVAL_ACTION = "release approval changed";
-/** The plane's record of what proved an automatic seal (`auto-check` or `auto-green`): one ledger row per seal, its
- * id named by the seal's `mode_digest` as `auto:<id>`. Only release-auto.ts writes it. */
 export const AUTO_EVIDENCE_ACTION = "release auto-approved";
-/** An automatic seal taken back for good (the setting lowered, a refusal): its outcome names the seal's `auto:<id>`, and
- * that evidence never stands again. */
 export const AUTO_WITHDRAWN_ACTION = "release auto-approval withdrawn";
-/** The setting rows (no task; this action) through the ledger's (task_id, action, …) index: a seek to the few rows every
- * project has written, never a walk down the project's whole ledger. The approval predicate reads this once per task row
- * (SQLite evaluates every operand of an OR in a result column), so a walk made each Needs you count ~10x slower (0.9.76). */
 const SETTING_INDEX = "INDEXED BY work_completion";
-/** Read live at every use. Fail closed: a missing, unreadable or unknown row is `ask`. */
 export function releaseApprovalSetting(store, repo) {
     let row;
     try {
@@ -174,15 +139,8 @@ export function releaseApprovalSetting(store, repo) {
     return { auto: row["outcome"] === "auto", setBy: String(row["actor"]), at: String(row["at"]) };
 }
 export const releaseAutoApproves = (store, repo) => releaseApprovalSetting(store, repo).auto;
-/** SQL: the newest setting row for `repo` (an SQL expression) says `auto`. */
 export const releaseAutoSql = (repo) => `COALESCE((SELECT ra_set.outcome = 'auto' FROM action_ledger ra_set ${SETTING_INDEX} WHERE ra_set.repo = ${repo} AND ra_set.task_id IS NULL
       AND ra_set.action = '${RELEASE_APPROVAL_ACTION}' ORDER BY ra_set.id DESC LIMIT 1), 0)`;
-/**
- * SQL over a `task_scope` alias: its automatic seal (`auto-check` or `auto-green`) stands on its own evidence row — this
- * task, this kind, `mode_digest = 'auto:<row id>'`, the row's digest and candidate exactly the sealed ones — on a release
- * task (a candidate and release terms signed in), while the project's setting is on. The approver's standing is read
- * beside it (approval-authority.ts).
- */
 export const autoSealSql = (scope, repo) => `(${scope}.candidate IS NOT NULL AND ${scope}.release_terms_json IS NOT NULL AND ${releaseAutoSql(repo)}
     AND EXISTS (SELECT 1 FROM action_ledger ae WHERE ae.task_id = ${scope}.task_id AND ae.action = '${AUTO_EVIDENCE_ACTION}'
         AND ae.outcome = ${scope}.approval_basis AND ${scope}.mode_digest = 'auto:' || ae.id AND json_valid(ae.detail)