toolroll 0.9.62 → 0.9.65

package/dist/flow-unattended-words.d.ts

@@ -0,0 +1,28 @@
+/** The words a "runs on its own" grant signs (flow-unattended.ts), kept free of server imports so the flow page's
+ * signing form says each limit exactly as the signature will. */
+export declare const dollarWords: (micro: number) => string;
+/** "Oct 19": the end's day, where space is short (the exact time goes beside it, on hover). */
+export declare const untilDayWords: (iso: string) => string;
+/** "Oct 19, 14:05 UTC": the expiry as every surface says it. */
+export declare const untilWords: (iso: string) => string;
+/** Who approves, with what permissions and against which criteria. */
+export declare function unattendedHeadWords(owner: string, acceptance: {
+    task: readonly {
+        statement: string;
+    }[];
+    report: readonly {
+        statement: string;
+    }[];
+}): string[];
+/** "daily at 09:00" from a stored schedule ("daily:09:00@Europe/London"), kept here so every surface says it alike. */
+export declare function scheduleWords(stored: string): string;
+/** Which schedules the grant covers, by name and time. */
+export declare const unattendedCoverWords: (triggers: readonly {
+    words: string;
+}[]) => string;
+/** The optional limits. */
+export declare function unattendedLimitWords(budgetMicrousd: number | null, dailyRunCap: number | null): string[];
+/** What it never covers, and what ends it. */
+export declare const UNATTENDED_RULE_WORDS: readonly string[];
+export declare const unattendedEndWords: (expiry: string) => string;
+export declare const unattendedEndAfterWords: (days: number) => string;

package/dist/flow-unattended-words.js

@@ -0,0 +1,50 @@
+/** The words a "runs on its own" grant signs (flow-unattended.ts), kept free of server imports so the flow page's
+ * signing form says each limit exactly as the signature will. */
+export const dollarWords = (micro) => `$${(micro / 1_000_000).toFixed(2)}`;
+/** "Oct 19": the end's day, where space is short (the exact time goes beside it, on hover). */
+export const untilDayWords = (iso) => new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", timeZone: "UTC" }).format(new Date(iso));
+/** "Oct 19, 14:05 UTC": the expiry as every surface says it. */
+export const untilWords = (iso) => `${new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", timeZone: "UTC" }).format(new Date(iso))}, ${iso.slice(11, 16)} UTC`;
+/** Who approves, with what permissions and against which criteria. */
+export function unattendedHeadWords(owner, acceptance) {
+    return [
+        `Cards this flow's own schedule adds file their work approved by ${owner}, without waiting in Needs you.`,
+        "Builds use safe permissions: routine project commands and edits proceed; risky acts stop for approval.",
+        `Builds are checked against: “${acceptance.task.map(one => one.statement).join("”; “")}”.`,
+        `Research is checked against: “${acceptance.report.map(one => one.statement).join("”; “")}”.`,
+    ];
+}
+/** "daily at 09:00" from a stored schedule ("daily:09:00@Europe/London"), kept here so every surface says it alike. */
+export function scheduleWords(stored) {
+    const days = ["Sundays", "Mondays", "Tuesdays", "Wednesdays", "Thursdays", "Fridays", "Saturdays"];
+    const [when, zone] = stored.split("@");
+    const parts = (when ?? "").split(":");
+    const tz = zone === undefined ? "" : ` ${zone}`;
+    if (parts[0] === "every") {
+        const n = Number(parts[1]);
+        return n % 1440 === 0 ? `every ${n / 1440} day${n === 1440 ? "" : "s"}` : n % 60 === 0 ? `every ${n / 60} hour${n === 60 ? "" : "s"}` : `every ${n} minutes`;
+    }
+    if (parts[0] === "daily" || parts[0] === "weekdays")
+        return `${parts[0]} at ${parts[1]}:${parts[2]}${tz}`;
+    if (parts[0] === "weekly")
+        return `${days[Number(parts[1])] ?? "weekly"} at ${parts[2]}:${parts[3]}${tz}`;
+    return stored;
+}
+/** Which schedules the grant covers, by name and time. */
+export const unattendedCoverWords = (triggers) => `It covers ${triggers.length === 1 ? "this schedule" : "these schedules"} when ${triggers.length === 1 ? "it fires" : "they fire"} on time: ${triggers.map(one => one.words).join("; ")}. Run now, and schedules added or changed later, wait for you.`;
+/** The optional limits. */
+export function unattendedLimitWords(budgetMicrousd, dailyRunCap) {
+    return [
+        budgetMicrousd === null ? "No dollar cap per attempt." : `Each attempt may spend up to ${dollarWords(budgetMicrousd)}.`,
+        dailyRunCap === null ? "No daily limit on runs." : `At most ${dailyRunCap} run${dailyRunCap === 1 ? "" : "s"} a day (UTC); after that, cards wait for you.`,
+    ];
+}
+/** What it never covers, and what ends it. */
+export const UNATTENDED_RULE_WORDS = [
+    "Plans are approved only when they keep the filed request exactly. Questions and plan changes still wait for you.",
+    "Never covered: Person decides steps, pull request merges, publish or deploy scripts, and anything it sends. Cards people add and other triggers wait as usual.",
+    "Editing the flow, its schedules, a script they run or a project file it imports, changing its owner, the owner losing access, or protecting the project ends this.",
+    "Signing again replaces it: work it approved that hasn't started goes back to waiting for you.",
+];
+export const unattendedEndWords = (expiry) => `Ends ${untilWords(expiry)}. Revoking it earlier is one click.`;
+export const unattendedEndAfterWords = (days) => `Ends ${days} day${days === 1 ? "" : "s"} after you sign. Revoking it earlier is one click.`;

package/dist/flow-unattended.d.ts

@@ -0,0 +1,227 @@
+import type { AcceptanceCriterion } from "./contracts/scope.js";
+import { untilWords } from "./flow-unattended-words.js";
+import type { FlowRow, FlowTriggerRow, Store } from "./store.js";
+/** Grant history, run reservations and the last prepared script snapshots shared by UI/worker processes. Additive only. */
+export declare const FLOW_UNATTENDED_SCHEMA = "\nCREATE TABLE IF NOT EXISTS flow_script_provenance (\n  repo TEXT NOT NULL, name TEXT NOT NULL, snapshot TEXT, PRIMARY KEY (repo, name)\n);\nCREATE TABLE IF NOT EXISTS flow_unattended_grant (\n  id              INTEGER PRIMARY KEY AUTOINCREMENT,\n  flow            INTEGER NOT NULL,\n  repo            TEXT NOT NULL,\n  flow_revision   INTEGER NOT NULL,\n  terms_json      TEXT NOT NULL,\n  digest          TEXT NOT NULL,\n  signed_by       TEXT NOT NULL,\n  signed_at       TEXT NOT NULL,\n  absolute_expiry TEXT NOT NULL,\n  revoked_at      TEXT,\n  revoked_by      TEXT,\n  revoke_reason   TEXT\n);\nCREATE UNIQUE INDEX IF NOT EXISTS flow_unattended_live ON flow_unattended_grant (flow) WHERE revoked_at IS NULL;\nCREATE INDEX IF NOT EXISTS flow_unattended_digest ON flow_unattended_grant (digest);\nCREATE TABLE IF NOT EXISTS flow_unattended_run (\n  grant_id INTEGER NOT NULL,\n  day      TEXT NOT NULL,\n  task_id  TEXT NOT NULL,\n  at       TEXT NOT NULL,\n  PRIMARY KEY (grant_id, task_id)\n);\nCREATE INDEX IF NOT EXISTS flow_unattended_run_day ON flow_unattended_run (grant_id, day);\n";
+/** The fixed acceptance criteria a flow's work zones file with: the same for every card, so a grant can freeze them. */
+export declare const FLOW_ACCEPTANCE: {
+    report: AcceptanceCriterion[];
+    task: AcceptanceCriterion[];
+};
+/** The most runs a day a grant may allow. */
+export declare const UNATTENDED_MAX_RUNS = 50;
+/** The largest per-attempt budget a grant may name: $100. */
+export declare const UNATTENDED_MAX_BUDGET_MICROUSD = 100000000;
+/** The code a script schedule runs, as signed: the script's version and content digest, and for one that runs a project
+ * file, that file's path and, sorted by path, the digest of its bytes and of every project file it statically imports. */
+export type SignedScript = {
+    provenance: 2;
+    name: string;
+    version: number;
+    digest: string;
+    file: string | null;
+    files: {
+        path: string;
+        digest: string;
+    }[];
+};
+/** One schedule a grant covers: which trigger, what sort, the digest of its settings when signed, and its name in words.
+ * `script` is there exactly when the kind is "script". */
+export type CoveredTrigger = {
+    id: number;
+    kind: "schedule" | "script" | "plane-review";
+    digest: string;
+    words: string;
+    script?: SignedScript;
+};
+export type UnattendedTerms = {
+    flow: number;
+    /** Saving the flow moves its revision: what was signed was this drawing. */
+    flowRevision: number;
+    repo: string;
+    /** The signer, who must stay the flow's owner. */
+    owner: string;
+    /** The schedules signed for, frozen: any other trigger, or one of these changed, is not covered. */
+    triggers: CoveredTrigger[];
+    /** Always safe: an escalated posture is never covered. */
+    permissions: "safe";
+    acceptance: {
+        report: AcceptanceCriterion[];
+        task: AcceptanceCriterion[];
+    };
+    perAttemptBudgetMicrousd: number | null;
+    /** Filings per UTC day, reserved at filing. */
+    dailyRunCap: number | null;
+    absoluteExpiry: string;
+};
+export declare const unattendedTermsJson: (terms: UnattendedTerms) => string;
+/** sha256 over a domain-separated canonical encoding, 32 hex like the mode digest. */
+export declare function unattendedDigestOf(terms: UnattendedTerms): string;
+/** Strict rehydration: anything unexpected is null, never a guess. */
+export declare function unattendedTermsFromJson(json: string | null): UnattendedTerms | null;
+export { untilWords };
+/** Every term in words: what the ceremony shows and the password signs. */
+export declare function unattendedWords(terms: UnattendedTerms): string[];
+export type UnattendedGrant = {
+    id: number;
+    flow: number;
+    repo: string;
+    terms: UnattendedTerms;
+    digest: string;
+    signedBy: string;
+    signedAt: string;
+    absoluteExpiry: string;
+};
+/** SQL: whether the grant whose digest is `digest` still stands at `now` for work in `repo` — live, unexpired, its
+ * signer an active approver who can still reach the flow's project and this one, still the owner of the very flow
+ * revision signed, and neither project protected. Shared by every dispatch belt. */
+export declare const grantStandsSql: (digest: string, now: string, repo: string) => string;
+/** Why a grant ended, as its row and ledger line say it. A renewal's ledger line is the new signature's. */
+export type UnattendedEnd = "expired" | "revoked" | "renewed" | "schedule changed" | "script changed" | "project protected" | "access changed";
+/**
+ * The one road for what ends grants from outside this module (store.ts calls it): a flow's schedule added, paused,
+ * resumed or removed; a project's approval rules protecting work; an account's access or standing changing. Every live
+ * grant the filter names ends now, durably, with its ledger line, and its queued approvals are withdrawn. Call inside
+ * the mutation's transaction. Returns how many ended.
+ */
+export declare function endUnattendedGrants(store: Store, filter: {
+    flow: number;
+} | {
+    repo: string;
+} | {
+    signer: string;
+} | {
+    script: {
+        repo: string;
+        name: string;
+    };
+}, by: string, reason: Exclude<UnattendedEnd, "expired" | "revoked" | "renewed">, now: Date): number;
+/** The live grant for a flow, or null. One past its expiry is closed here, durably (like activeMode). A grant whose
+ * signer is no longer an active approver, or whose flow moved on, covers nothing. */
+export declare function activeUnattendedGrant(store: Store, flowId: number, now: Date): UnattendedGrant | null;
+/** sha256 over a trigger's identity and canonical settings: what a grant freezes for each schedule it covers. */
+export declare function triggerDigestOf(trigger: Pick<FlowTriggerRow, "id" | "flow" | "kind" | "configJson">): string | null;
+/** Asynchronous preparation, never called from filing transactions or page rendering. */
+export declare function scriptProvenanceOf(store: Store, repo: string, name: string, fresh?: boolean): Promise<SignedScript | null>;
+export declare function prepareUnattendedCandidates(store: Store, flowId: number): Promise<void>;
+/** What an on-time script firing ran, as its firing records it: a digest of the code pinned just before and just after
+ * the run, when both were the same and were the script row that ran; else null (it can't have run the code signed). */
+export declare function scriptRanDigestOf(before: SignedScript | null, after: SignedScript | null, ran: {
+    version: number;
+    digest: string;
+}): string | null;
+/** Whether `flowId`'s live grant signed `triggerId`'s script: only then does a firing pin the code it runs. */
+export declare function grantSignsScriptOf(store: Store, flowId: number, triggerId: number, now: Date): boolean;
+/** A schedule a grant could cover, and whether it is covered only when the owner picks it (`optional`, with why). */
+export type UnattendedCandidate = CoveredTrigger & {
+    optional: string | null;
+};
+/**
+ * The flow's active schedules a grant could cover. A plain schedule makes its own card from its own words, so it is
+ * covered by default. A script's items and a plane review's problems are outside content (issues, mail, what a run
+ * saw), so they are covered only when the owner picks them. A standing order files under its own signed terms, and a
+ * paused or unreadable schedule, or a script whose code can't be read safely, is never offered.
+ */
+export declare function unattendedCandidates(store: Store, flowId: number): UnattendedCandidate[];
+/** A digest of the schedules the page offered, so a signature never covers one the person didn't read. */
+export declare const candidatesDigestOf: (candidates: readonly UnattendedCandidate[]) => string;
+/** Why `signer` can't let this flow run on its own, or null: what the flow page shows instead of the form. */
+export declare function unattendedSignProblem(store: Store, flow: FlowRow, signer: string): string | null;
+/** `include`: the schedules (trigger ids) the owner picked beyond the plain ones covered by default. */
+export type UnattendedAsk = {
+    days: number;
+    budgetMicrousd: number | null;
+    dailyRunCap: number | null;
+    include?: number[];
+};
+/** Read what a person typed: whole days 1–MODE_MAX_DAYS, an optional dollar budget, an optional runs-a-day cap. */
+export declare function parseUnattendedAsk(input: {
+    days: unknown;
+    budget?: unknown;
+    runs?: unknown;
+    include?: unknown;
+}): {
+    ok: true;
+    ask: UnattendedAsk;
+} | {
+    ok: false;
+    message: string;
+};
+/** The exact terms a signature would cover now, for these schedules. */
+export declare function unattendedTermsFor(flow: FlowRow, owner: string, ask: UnattendedAsk, triggers: readonly CoveredTrigger[], now: Date): UnattendedTerms;
+/** Sign (or renew) the grant. The caller has already checked the signer's password; every predicate is proved again
+ * here against the flow as it now stands: files asynchronously first, then database facts inside the transaction. `sawRevision` and `sawSchedules` (candidatesDigestOf),
+ * when given, are the flow and the schedules the person read. Renewing ends the old grant and withdraws what it sealed. */
+export declare function signUnattended(store: Store, input: {
+    flow: number;
+    signer: string;
+    ask: UnattendedAsk;
+    sawRevision?: number;
+    sawSchedules?: string;
+}, now: Date): Promise<{
+    ok: true;
+    grant: UnattendedGrant;
+} | {
+    ok: false;
+    message: string;
+}>;
+/** One click for any approver on the project: lowering authority needs no password. False when there was none. */
+export declare function revokeUnattended(store: Store, flowId: number, by: string, now: Date): boolean;
+/**
+ * Whether a card came from one of the schedules this grant signed for, fired on time after it was signed: the firing
+ * names the card and was the clock's (never Run now), its trigger is still active with the very settings signed, and no
+ * person has moved the card or sent it back since. Anything else is a person's card, or one the grant never read.
+ * A script schedule's firing must have run the very code signed (scriptRanDigestOf), and it must still be that code;
+ * when it isn't, the grant ends here (unattendedCoverageFor).
+ */
+export declare function cardFromSignedSchedule(store: Store, grant: UnattendedGrant, cardId: number, requireScript?: boolean): boolean;
+/** How many runs a grant has filed on `now`'s UTC day. */
+export declare function unattendedRunsToday(store: Store, grantId: number, now: Date): number;
+/** Whether the grant covers this card's next filing (in `repo`) now; call inside the filing transaction. */
+export declare function unattendedCoverageFor(store: Store, flow: FlowRow, card: {
+    id: number;
+}, repo: string, now: Date): UnattendedGrant | null;
+/** Count one run against the grant's day, in one statement that admits it only under the cap (so two filings racing
+ * on two connections can't both take the last run). False when the day is full; then nothing is sealed. */
+export declare function reserveUnattendedRun(store: Store, grant: UnattendedGrant, taskId: string, now: Date): boolean;
+/** Give back a run reserved for a filing that then couldn't be sealed. */
+export declare function releaseUnattendedRun(store: Store, grant: UnattendedGrant, taskId: string): void;
+/** The grant that sealed (or pre-authorized) a task still stands for it: the same live digest, the flow unchanged and
+ * still owned by the signer, the signer able to approve in the task's project, its scripts' code unchanged (else it
+ * ends here), and the work not protected. */
+export declare function unattendedGrantStands(store: Store, digest: string, signer: string, taskRepo: string | null, touches: readonly string[], now: Date): boolean;
+/** The flow page's and CLI's view of the grant: the live state, and whether (and why not) this viewer can sign. */
+export type UnattendedView = {
+    active: {
+        until: string;
+        untilWords: string;
+        signedBy: string;
+        budgetMicrousd: number | null;
+        dailyRunCap: number | null;
+        runsToday: number;
+        words: string[];
+        covers: string[];
+    } | null;
+    canSign: boolean;
+    problem: string | null;
+    maxDays: number;
+    /** Whether the flow has a schedule, the only thing a grant covers. */
+    scheduled: boolean;
+    /** What a signature covers besides the limits and schedules the form chooses (unattendedLimitWords, unattendedCoverWords,
+     * unattendedEndAfterWords). */
+    terms: {
+        head: string[];
+        rules: string[];
+    };
+    /** The schedules it could cover (optional ones only when picked), and their digest, which the form sends back. */
+    schedules: {
+        id: number;
+        words: string;
+        optional: string | null;
+    }[];
+    schedulesDigest: string;
+};
+export declare function unattendedViewOf(store: Store, flow: FlowRow, viewer: {
+    name: string;
+    approver: boolean;
+}, now: Date): UnattendedView;