toolroll 0.9.71 → 0.9.72

package/dist/release-cli.js

@@ -15,7 +15,11 @@ import { checkedEnvelopeJson } from "./contracts/cli.js";
 import { RELEASE_LIMITS, runRelease } from "./release.js";
 import { processes, releaseAdapters } from "./release-adapters.js";
 import { releaseGate } from "./release-gate.js";
-import { databasePath } from "./store.js";
+import { databasePath, openStore, revokeRelease } from "./store.js";
+import { carryRefusalWords, proveCarry, setAskEveryReleaseCommit } from "./release-carry.js";
+import { authenticateApprover, machineActing, personProof } from "./scope.js";
+import { createNightlyCheckFlow } from "./nightly-check.js";
+import { parseSchedule } from "./flow-schedule.js";
 export const RELEASE_HELP = `toolroll release <branch> — release Toolroll itself, from a pushed branch with an open pull request
 
   Requires an active approver's scope approval (the only human step) and a passing Full check on the exact commit.
@@ -31,7 +35,24 @@ toolroll release --release-gate <id> [--yes] — lift the update pause a deploym
   database, service definition and running service are all still the previous build's. --yes lifts that one pause.
   Any missing or contradicting evidence refuses and leaves the pause in place.
 
+toolroll release carry <release> --to <commit> [--request <id>] — carry a person's release approval to a later commit
+
+  Only tests, docs and the changelog may change after the approval, within the limits, with an identical production
+  build. Anything else is refused, naming the commit, path and rule, and that commit needs a person's approval.
+
+toolroll release revoke <release> — stop carrying later commits (before the merge starts)
+
+toolroll release nightly --repo <path> --as <you> --token <password> [--schedule daily:03:00@<zone>] [--start]
+  — the full release check of main's head every night, approved once with your password; it never deploys,
+  merges or completes, and a failure tells you and holds composed releases until a full check passes
+
+toolroll release ask-every-commit on|off --repo <path> [--as <you> --token <password>] — this project's releases ask
+  for every later commit (on), or carry test-only commits again (off: your password, never the lead's token)
+
 Options
+  --no-carry             every later commit of this release asks for approval again
+  --to <commit>          with carry: the later commit
+  --request <id>         with carry: the request's own id, so a retry is the same request
   --repo <path>          the gate checkout the release check runs in (default: this checkout)
   --new                  release a new commit on the branch, setting the earlier unfinished release aside
   --limit <step>=<min>   change one step's time limit (${Object.entries(RELEASE_LIMITS).map(([step, minutes]) => `${step} ${minutes}`).join(", ")})
@@ -44,8 +65,8 @@ A runner's lease is returned with \`toolroll worker release <lease>\`.`;
 /** A runner lease id (claim.ts mints randomUUID()). */
 export const LEASE_SHAPED = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export const LEASE_DEPRECATION = "`toolroll release <lease>` is now `toolroll worker release <lease>`; the old form goes in the next minor version.";
-const VALUE_FLAGS = new Set(["--repo", "--limit", "--tap", "--release-gate"]);
-const BARE_FLAGS = new Set(["--new", "--json", "--help", "--yes"]);
+const VALUE_FLAGS = new Set(["--repo", "--limit", "--tap", "--release-gate", "--to", "--request", "--as", "--token", "--schedule"]);
+const BARE_FLAGS = new Set(["--new", "--json", "--help", "--yes", "--no-carry", "--start"]);
 export async function runReleaseCommand(args, write, deps = {}) {
     const json = args.includes("--json");
     const refuse = (reason, message, code) => {
@@ -54,7 +75,7 @@ export async function runReleaseCommand(args, write, deps = {}) {
     };
     const positional = [];
     const limits = {};
-    let repo, tap, gate;
+    let repo, tap, gate, to, request, as, token, scheduleFlag;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (BARE_FLAGS.has(arg))
@@ -66,6 +87,16 @@ export async function runReleaseCommand(args, write, deps = {}) {
             i += 1;
             if (arg === "--repo")
                 repo = value;
+            else if (arg === "--to")
+                to = value;
+            else if (arg === "--request")
+                request = value;
+            else if (arg === "--as")
+                as = value;
+            else if (arg === "--token")
+                token = value;
+            else if (arg === "--schedule")
+                scheduleFlag = value;
             else if (arg === "--tap")
                 tap = value;
             else if (arg === "--release-gate")
@@ -93,6 +124,11 @@ export async function runReleaseCommand(args, write, deps = {}) {
     }
     if (args.includes("--yes"))
         return refuse("usage", "--yes goes with --release-gate <id>; a release needs no confirmation beyond the owner's approval.", 2);
+    if (positional[0] === "nightly" && positional.length === 1)
+        return runNightlyCommand({ repo: repo === undefined ? undefined : resolve(deps.cwd ?? process.cwd(), repo), as, token, schedule: scheduleFlag, start: args.includes("--start") }, write, json, deps);
+    if (["carry", "revoke", "ask-every-commit"].includes(positional[0] ?? "") && positional.length === 2) {
+        return runAuthorityCommand(positional[0], positional[1], { to, request, as, token, repo: repo === undefined ? undefined : resolve(deps.cwd ?? process.cwd(), repo) }, write, json, deps);
+    }
     if (positional.length !== 1)
         return refuse("usage", `Which branch? \`toolroll release <branch>\`.\n${RELEASE_HELP}`, 2);
     const branch = positional[0];
@@ -117,7 +153,7 @@ export async function runReleaseCommand(args, write, deps = {}) {
     const adapters = deps.adapters === undefined
         ? releaseAdapters({ checkout, say, ...(tap === undefined ? {} : { tap }), ...(limits["deploy"] === undefined ? {} : { deployMinutes: limits["deploy"] }) })
         : { ...deps.adapters, say };
-    const outcome = await runRelease({ branch, checkout, stateDir, limits, fresh: args.includes("--new") }, adapters);
+    const outcome = await runRelease({ branch, checkout, stateDir, limits, fresh: args.includes("--new"), noCarry: args.includes("--no-carry") }, adapters);
     return report(outcome, write, json, lines);
 }
 function report(outcome, write, json, lines) {
@@ -179,3 +215,86 @@ function runGateRelease(id, yes, write, json, world) {
         write(`Lift it: toolroll release --release-gate ${outcome.id} --yes`);
     return 0;
 }
+/**
+ * The release's authority from the command line (release-once.md): ask for a carry (anyone may ask, the lead
+ * included; only the rules decide), stop carrying (only ever stricter), or change the project's carry setting
+ * (turning carrying back on is a person's own command, never the lead's or a remote token's).
+ */
+async function runAuthorityCommand(command, target, flags, write, json, deps) {
+    const name = `release ${command}`;
+    const answer = (ok, fields, words, code) => {
+        write(json ? checkedEnvelopeJson({ ok, command: name, ...fields }) : words);
+        return code;
+    };
+    const database = deps.database ?? databasePath(process.env, homedir());
+    if (!existsSync(database))
+        return answer(false, { reason: "no-plane", message: "This machine has no Toolroll database." }, "This machine has no Toolroll database.", 1);
+    const store = openStore(database);
+    const now = (deps.now ?? (() => new Date()))();
+    try {
+        if (command === "ask-every-commit") {
+            if (target !== "on" && target !== "off")
+                return answer(false, { reason: "usage", message: "ask-every-commit takes on or off." }, "ask-every-commit takes on or off.", 2);
+            if (flags.repo === undefined)
+                return answer(false, { reason: "usage", message: "Name the project with --repo <path>." }, "Name the project with --repo <path>.", 2);
+            // Turning carrying back on relaxes a release's rules: a person's own ceremony, as an approval needs (a password
+            // typed now, a re-check, or their own session), never a lead or remote token. Turning it off is only stricter.
+            let actor = "cli";
+            if (target === "off") {
+                const refused = (message) => answer(false, { reason: "person-only", message }, message, 1);
+                if (machineActing() || process.env["TOOLROLL_LEAD_TOKEN"] !== undefined || process.env["TOOLROLL_REMOTE_TOKEN"] !== undefined)
+                    return refused("Only a person turns carrying back on, never the lead or a remote token.");
+                if (flags.as === undefined || flags.token === undefined)
+                    return refused("Turning carrying back on needs your password: add --as <you> --token <password>.");
+                const proved = authenticateApprover(store, flags.as, flags.token, flags.repo);
+                if (!proved.ok || !personProof(proved.method))
+                    return refused("Only an approver of this project, proved as a person, turns carrying back on.");
+                actor = flags.as;
+            }
+            setAskEveryReleaseCommit(store, flags.repo, target === "on", actor, now);
+            const words = target === "on" ? "Every later release commit in this project asks for approval." : "Later test-only release commits ship under the release approval.";
+            return answer(true, { repo: flags.repo, ask: target === "on" }, words, 0);
+        }
+        const id = Number(target);
+        if (!Number.isSafeInteger(id) || id < 1)
+            return answer(false, { reason: "usage", message: `${target} isn't a release id.` }, `${target} isn't a release id.`, 2);
+        if (command === "revoke") {
+            const done = revokeRelease(store, id, "cli", now);
+            return done.ok ? answer(true, { release: id }, `Release ${id} no longer carries later commits.`, 0) : answer(false, { reason: "refused", message: done.why }, done.why, 1);
+        }
+        if (flags.to === undefined || !/^[0-9a-f]{40}$/.test(flags.to))
+            return answer(false, { reason: "usage", message: "carry takes --to <full commit id>." }, "carry takes --to <full commit id>.", 2);
+        const result = await proveCarry(store, { authority: id, to: flags.to, ...(flags.request === undefined ? {} : { requestId: flags.request }), now });
+        if (result.ok)
+            return answer(true, { release: id, task: result.taskId, retried: result.retried, carry: { files: result.carry.files, lines: result.carry.changedLines } }, `Carried release ${id} to ${flags.to.slice(0, 7)}: task ${result.taskId} (${result.carry.files} files, ${result.carry.changedLines} lines).`, 0);
+        return answer(false, { reason: result.reason, message: result.message, ...(result.path === undefined ? {} : { path: result.path }) }, carryRefusalWords(result, flags.to), 1);
+    }
+    finally {
+        store.close();
+    }
+}
+/** `toolroll release nightly`: the nightly full check on main, approved with a person's password (nightly-check.ts). */
+async function runNightlyCommand(flags, write, json, deps) {
+    const answer = (ok, fields, words, code) => { write(json ? checkedEnvelopeJson({ ok, command: "release nightly", ...fields }) : words); return code; };
+    if (flags.repo === undefined)
+        return answer(false, { reason: "usage", message: "Name the project with --repo <path>." }, "Name the project with --repo <path>.", 2);
+    if (flags.as === undefined || flags.token === undefined)
+        return answer(false, { reason: "usage", message: "The nightly check is approved with your password: add --as <you> --token <password>." }, "The nightly check is approved with your password: add --as <you> --token <password>.", 2);
+    if (machineActing() || process.env["TOOLROLL_LEAD_TOKEN"] !== undefined || process.env["TOOLROLL_REMOTE_TOKEN"] !== undefined)
+        return answer(false, { reason: "person-only", message: "Only a person sets up the nightly check." }, "Only a person sets up the nightly check.", 1);
+    const zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    const schedule = flags.schedule ?? `daily:03:00${zone ? `@${zone}` : ""}`;
+    if (parseSchedule(schedule) === null)
+        return answer(false, { reason: "usage", message: `${schedule} isn't a schedule (daily:03:00@Europe/Paris, say).` }, `${schedule} isn't a schedule (daily:03:00@Europe/Paris, say).`, 2);
+    const database = deps.database ?? databasePath(process.env, homedir());
+    const store = openStore(database);
+    try {
+        const made = createNightlyCheckFlow(store, { repo: flags.repo, schedule, as: flags.as, token: flags.token, start: flags.start }, (deps.now ?? (() => new Date()))());
+        if (!made.ok)
+            return answer(false, { reason: "refused", message: made.message }, made.message, 1);
+        return answer(true, { flow: made.flow, trigger: made.trigger, schedule }, `The nightly check of main runs ${schedule}${flags.start ? "" : " once you turn its schedule on"} (flow ${made.flow}).`, 0);
+    }
+    finally {
+        store.close();
+    }
+}

package/dist/release-coverage.js

@@ -63,6 +63,9 @@ function passingReleases(store, root, repo) {
             if (!gate.ok || gate.bytes === null)
                 return [];
             const receipt = JSON.parse(gate.bytes);
+            // A release check whose coverage is partial or lost a required test covers nothing.
+            if (receipt.coverage !== undefined && receipt.coverage !== "full" && receipt.coverage !== "composed")
+                return [];
             const head = store.getRun(run)?.headRevision ?? null;
             if (receipt.run !== run || receipt.result?.ran !== true || receipt.result.exitCode !== 0)
                 return [];

package/dist/release-recheck.d.ts

@@ -0,0 +1,146 @@
+import { type CheckContext, type CheckPart, type CheckReport, type ObligationSnapshot, type SealedInventory, type TargetedPlan } from "./contracts/release-check.js";
+import { type CheckAttempt, type Store, type VerifyCommand } from "./store.js";
+/** The sanity pass every targeted check runs beside its plan: a few fast tests of the core rules, when the tree has them. */
+export declare const SANITY_UNITS: readonly string[];
+/** A run's sealed check evidence, read back and verified (check-report.ts). */
+export type SealedRun = {
+    run: number;
+    attempt: CheckAttempt;
+    report: CheckReport | null;
+    reportDigest: string | null;
+    inventory: SealedInventory | null;
+    context: CheckContext | null;
+    plan: TargetedPlan | null;
+    planDigest: string | null;
+    snapshot: ObligationSnapshot | null;
+    snapshotDigest: string | null;
+};
+export declare function sealedRun(store: Store, root: string, run: number): SealedRun | null;
+/** R(A): what a later check must run again, from A's sealed evidence alone — or why only a full check will do. */
+export type Obligations = {
+    full: string | null;
+    units: string[];
+    parts: CheckPart[];
+    groups: {
+        script: "app" | "flows";
+        kind: "scripted" | "real";
+        groups: string[];
+    }[];
+    versions: string[];
+    /** The identities that have to be reported, and pass. */
+    required: string[];
+    /** Identities skipped at A: they may stay skipped. */
+    skipped: string[];
+};
+/** The disposition of every outcome at A (the table in the plan). */
+export declare function requiredSet(a: {
+    report: CheckReport | null;
+    inventory: SealedInventory | null;
+}): Obligations;
+/** The identities that failed in one run's sealed report (for an obligation snapshot). */
+export declare function failedIdentities(report: CheckReport | null): string[];
+/** The earlier targeted runs of this generation after A, with their sealed report digests and what failed in them. */
+export declare function obligationSnapshot(store: Store, root: string, authority: number, base: number, before: number): ObligationSnapshot;
+/** The plan a targeted run runs: R(A), the snapshot's failures, every test changed since A, and the sanity pass. */
+export declare function planFrom(base: number, obligations: Obligations, snapshot: ObligationSnapshot, changed: readonly string[], units: readonly string[], journeysRan: readonly CheckPart[]): TargetedPlan;
+export type RecheckDecision = {
+    mode: "targeted";
+    authority: number;
+    plan: TargetedPlan;
+    snapshot: ObligationSnapshot;
+    watch: string[];
+} | {
+    mode: "full";
+    authority: number | null;
+    why: string;
+    watch: string[];
+};
+/**
+ * Whether the check about to run for this release task may be targeted (planTargetedRecheck): only when A and this run
+ * are gate tasks of the same current generation, A is the generation's newest full check with a valid report that
+ * accounts for every item and reused nothing from CI, everything since A is test-only (the carry proved it), the
+ * execution context matches A's, and no main-check failure is open. Otherwise a full check, told which identities it
+ * must still report (watch).
+ */
+export declare function planTargetedRecheck(store: Store, root: string, input: {
+    runId: number;
+    taskId: string;
+    repo: string;
+    head: string;
+    command: VerifyCommand;
+    access: string;
+    now: Date;
+}): RecheckDecision;
+/** Coverage of a check: full, composed from A, partial (never passes), or identity-removed (asks again). */
+export type Coverage = "full" | "composed" | "partial" | "identity-removed";
+/**
+ * Whether a targeted run B, with A's sealed evidence, its plan and snapshot, covers every item of B's inventory
+ * (coverage conservation), and every required identity passed — re-derived from sealed values only.
+ */
+export declare function coverageOf(input: {
+    a: {
+        report: CheckReport;
+        inventory: SealedInventory;
+    };
+    b: {
+        report: CheckReport | null;
+        inventory: SealedInventory | null;
+        exitCode: number | null;
+    };
+    plan: TargetedPlan;
+    snapshot: ObligationSnapshot;
+}): Coverage;
+/** A full run's own check: a required identity of the generation that is gone or newly skipped. */
+export declare function fullRunRemovedIdentity(report: CheckReport | null, watch: readonly string[], skippedAtBase: readonly string[]): boolean;
+/** What a composed receipt names (receipt version 3): each link is proved again by provedComposition. */
+export type ComposedLinks = {
+    base: number;
+    baseReceipt: string;
+    baseReport: string;
+    authority: number;
+    carries: number[];
+    artifacts: string;
+    plan: string;
+    snapshot: string;
+    report: string;
+};
+/**
+ * After the check: its coverage, and for a composed one the links its receipt names. An identity-removed result stops
+ * the release carrying (a person approves it again). `gateOf` reads a run's verified receipt digest.
+ */
+export declare function settleCoverage(store: Store, root: string, input: {
+    runId: number;
+    taskId: string;
+    exitCode: number | null;
+    now: Date;
+}, gateOf: (run: number) => string | null): {
+    coverage: Coverage;
+    composed: ComposedLinks | null;
+};
+/**
+ * Re-prove every link a composed receipt names, from sealed artifacts and the store: A's receipt and report, this run's
+ * plan (re-derived from A's sealed evidence and the sealed snapshot), its snapshot and report, the release's artifact
+ * digest on every carry of this task, the generation and the grant. Null when every link holds; else why not.
+ */
+export declare function provedComposition(store: Store, root: string, runId: number, links: ComposedLinks, gateOf: (run: number) => string | null, grantOf: (run: number) => string | null): string | null;
+/** The identities a later check of this release still has to run again and pass (the anchor page's obligations). */
+export declare function releaseObligationsOf(store: Store, root: string, authority: number): string[];
+/**
+ * The identities a release generation still owes, independent of whether a targeted check is allowed (review round
+ * 1): every identity that failed in any of its checks before `before`, until a later check reported it PASSED by name.
+ * A failed typecheck or build doesn't wipe them, and a full fallback keeps them: each must be reported again, and a
+ * check that drops or newly skips one asks a person again.
+ */
+export declare function owedIdentities(store: Store, root: string, authority: number, before: number): string[];
+/**
+ * The generation's protected identities (review round 2): every identity that failed in any of its checks before
+ * `before`. Never shrinks — a later pass doesn't forgive a later removal: removing, renaming or newly skipping any of
+ * them, in any later run of the generation, asks a person again. Separate from what is still owed (owedIdentities).
+ */
+export declare function protectedIdentities(store: Store, root: string, authority: number, before: number): string[];
+/**
+ * Whether a run's report removed one of the protected identities: a unit test or journey gone or newly skipped from a
+ * file or group the run did report, a unit file gone from its inventory, a group or upgrade version missing from a lane
+ * that finished. A lane that didn't run or finish is no pass, so it is judged by the next run that does.
+ */
+export declare function removedProtected(report: CheckReport | null, inventory: SealedInventory | null, kept: readonly string[]): boolean;