toolroll 0.5.0

package/dist/backend.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The contract every work graph is driven through, and the guard around it.
+ *
+ * §4's interface, with one deliberate omission: `hold` is not here. A hold is
+ * an operational pause — "not tonight, we are waiting on a person" — and not a
+ * claim about how the work is structured, so it lives in the overlay where it
+ * costs nobody else's tracker anything. Dependency edges are the opposite, and
+ * that asymmetry is the whole rule:
+ *
+ * **Scheduling edges are never emulated.** A backend with no native edges is
+ * *ineligible for dependency scheduling*, not repaired with invisible ones. A
+ * private graph is shadow data: teammates and other tools read a task as ready
+ * while our overlay privately calls it blocked, and the divergence becomes
+ * migration-critical the moment anybody wants out. So `addEdge` on a backend
+ * whose edges are unverified refuses, and says why, rather than storing
+ * something only we can see.
+ *
+ * Every method answers with an outcome rather than throwing. These call other
+ * people's binaries over other people's networks; failure is a normal Tuesday,
+ * and one unreachable backend must not end a run covering four others.
+ */
+import { type Store, type TaskState } from "./store.js";
+import type { Deps } from "./graph.js";
+import type { ExecResult, RunOptions } from "./exec.js";
+export type Runner = (file: string, args: readonly string[], options?: RunOptions) => Promise<ExecResult>;
+/** What a backend can tell us about a task, in terms we share across all of them. */
+export type BackendTask = {
+    id: string;
+    title: string;
+    state: TaskState;
+};
+export type TaskSpec = {
+    title: string;
+    body?: string;
+};
+export type Outcome<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: OutcomeReason;
+    message: string;
+};
+/**
+ * `unsupported` is not a failure of this run — it is a permanent property of
+ * the backend, and a caller should stop asking rather than retry.
+ */
+export type OutcomeReason = "unsupported" | "denied" | "unreachable" | "unreadable" | "rejected";
+export interface GraphBackend {
+    readonly name: string;
+    /** Whether this backend carries dependency edges of its own. */
+    readonly deps: Deps;
+    listReady(): Promise<Outcome<BackendTask[]>>;
+    get(id: string): Promise<Outcome<BackendTask | null>>;
+    create(spec: TaskSpec): Promise<Outcome<string>>;
+    setState(id: string, state: TaskState): Promise<Outcome<void>>;
+    addEdge(blocked: string, blocker: string): Promise<Outcome<void>>;
+}
+export declare const ok: <T>(value: T) => Outcome<T>;
+export declare const no: (reason: OutcomeReason, message: string) => Outcome<never>;
+/**
+ * The refusal a backend without confirmed edges gives, spelled once so every
+ * adapter says the same thing and nobody is tempted to soften it.
+ */
+export declare function edgesNotEmulated(name: string): Outcome<never>;
+/** Turn a failed command into words, without pretending to know more than we do. */
+export declare function describeFailure(result: ExecResult): string;
+export declare function parseJson(text: string): unknown | null;
+/**
+ * The built-in store, behind the same contract as everyone else.
+ *
+ * Worth the wrapper even though it is ours: the scheduler should not be able
+ * to tell which backend it is driving, and the day this is the only one with a
+ * privileged shortcut is the day the interface stops being tested.
+ *
+ * It is the only backend here whose edges are both native and ours to write,
+ * so it is also the only one where dependency scheduling is unconditionally
+ * available.
+ */
+export declare function builtIn(store: Store, now?: () => Date): GraphBackend;
+export type GuardOptions = {
+    store: Store;
+    repo: string;
+};
+/**
+ * Wrap a backend so nothing can write through it without a grant.
+ *
+ * Applied once, at construction, rather than checked inside each adapter — an
+ * authorization that every implementation has to remember to call is one that
+ * a future adapter will forget, and it will forget it silently. Here the only
+ * way to reach a mutating method is through the wrapper, and adding a backend
+ * later inherits the check by construction.
+ *
+ * Reads pass straight through. Discovery has always been read-only and needs
+ * no permission; it is writing to somebody else's tracker that requires one.
+ */
+export declare function guarded(backend: GraphBackend, options: GuardOptions): GraphBackend;

package/dist/backend.js

@@ -0,0 +1,166 @@
+/**
+ * The contract every work graph is driven through, and the guard around it.
+ *
+ * §4's interface, with one deliberate omission: `hold` is not here. A hold is
+ * an operational pause — "not tonight, we are waiting on a person" — and not a
+ * claim about how the work is structured, so it lives in the overlay where it
+ * costs nobody else's tracker anything. Dependency edges are the opposite, and
+ * that asymmetry is the whole rule:
+ *
+ * **Scheduling edges are never emulated.** A backend with no native edges is
+ * *ineligible for dependency scheduling*, not repaired with invisible ones. A
+ * private graph is shadow data: teammates and other tools read a task as ready
+ * while our overlay privately calls it blocked, and the divergence becomes
+ * migration-critical the moment anybody wants out. So `addEdge` on a backend
+ * whose edges are unverified refuses, and says why, rather than storing
+ * something only we can see.
+ *
+ * Every method answers with an outcome rather than throwing. These call other
+ * people's binaries over other people's networks; failure is a normal Tuesday,
+ * and one unreachable backend must not end a run covering four others.
+ */
+import { BUILT_IN } from "./store.js";
+import { permits } from "./grant.js";
+export const ok = (value) => ({ ok: true, value });
+export const no = (reason, message) => ({
+    ok: false,
+    reason,
+    message,
+});
+/**
+ * The refusal a backend without confirmed edges gives, spelled once so every
+ * adapter says the same thing and nobody is tempted to soften it.
+ */
+export function edgesNotEmulated(name) {
+    return no("unsupported", `${name} dependency edges are not confirmed here, and Toolroll does not invent them — a graph only we can see would read as ready to everyone else`);
+}
+/** Turn a failed command into words, without pretending to know more than we do. */
+export function describeFailure(result) {
+    if (result.notFound)
+        return "the command is not installed";
+    if (result.timedOut)
+        return "it timed out";
+    const [line = ""] = result.stderr.trim().split("\n");
+    return line === "" ? `exit ${result.code}` : line;
+}
+export function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The built-in store, behind the same contract as everyone else.
+ *
+ * Worth the wrapper even though it is ours: the scheduler should not be able
+ * to tell which backend it is driving, and the day this is the only one with a
+ * privileged shortcut is the day the interface stops being tested.
+ *
+ * It is the only backend here whose edges are both native and ours to write,
+ * so it is also the only one where dependency scheduling is unconditionally
+ * available.
+ */
+export function builtIn(store, now = () => new Date()) {
+    return {
+        name: BUILT_IN,
+        deps: "native",
+        async listReady() {
+            const ready = store.listReady(now());
+            return ok(ready
+                .map(ref => store.getTask(ref.externalId))
+                .filter((task) => task !== null)
+                .map(task => ({ id: task.id, title: task.title, state: task.state })));
+        },
+        async get(id) {
+            const task = store.getTask(id);
+            return ok(task === null ? null : { id: task.id, title: task.title, state: task.state });
+        },
+        async create(spec) {
+            // The id is derived from the title here rather than by the caller, so
+            // that every backend's `create` has the same shape: hand it a spec, get
+            // an id back.
+            const id = `${slug(spec.title)}-${now().toISOString().slice(11, 19).replace(/:/g, "")}`;
+            if (store.getTask(id) !== null)
+                return no("rejected", `\`${id}\` already exists`);
+            store.createTask({ id, title: spec.title }, now());
+            return ok(id);
+        },
+        async setState(id, state) {
+            const moved = store.setTaskState(id, state, now());
+            if (moved.ok)
+                return ok(undefined);
+            return no("rejected", moved.reason === "external-closed"
+                ? `the tracker closed \`${id}\` — reopen it first`
+                : moved.reason === "reason-required" || moved.reason === "bad-reason"
+                    ? `cancelling \`${id}\` requires a plain reason — use task state ${id} cancelled --reason <text>`
+                    : `no task \`${id}\``);
+        },
+        async addEdge(blocked, blocker) {
+            const result = store.addEdge(blocked, blocker);
+            return result.ok ? ok(undefined) : no("rejected", result.reason);
+        },
+    };
+}
+function slug(title) {
+    const words = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .split("-")
+        .filter(Boolean)
+        .slice(0, 4)
+        .join("-");
+    return words === "" ? "task" : words;
+}
+/**
+ * Wrap a backend so nothing can write through it without a grant.
+ *
+ * Applied once, at construction, rather than checked inside each adapter — an
+ * authorization that every implementation has to remember to call is one that
+ * a future adapter will forget, and it will forget it silently. Here the only
+ * way to reach a mutating method is through the wrapper, and adding a backend
+ * later inherits the check by construction.
+ *
+ * Reads pass straight through. Discovery has always been read-only and needs
+ * no permission; it is writing to somebody else's tracker that requires one.
+ */
+export function guarded(backend, options) {
+    const { store, repo } = options;
+    const allowed = (mutation, id) => {
+        const verdict = permits(store.grantFor(repo, backend.name), {
+            repo,
+            backend: backend.name,
+            mutation,
+            // Read from the overlay, never from the caller. A task we have merely
+            // seen is `theirs` until something explicitly makes it ours.
+            origin: id === undefined ? "ours" : store.originOf(backend.name, id),
+        });
+        return verdict.ok ? null : no("denied", verdict.message);
+    };
+    return {
+        name: backend.name,
+        deps: backend.deps,
+        listReady: () => backend.listReady(),
+        get: id => backend.get(id),
+        async create(spec) {
+            // A task we are about to create is ours by definition; there is no id to
+            // ask the overlay about yet, and the selector cannot be what stops it.
+            const denied = allowed("create");
+            return denied ?? backend.create(spec);
+        },
+        async setState(id, state) {
+            // Closing somebody's issue and moving our own task along are different
+            // acts to a person, however alike they look to a database, so they check
+            // against different mutation classes.
+            const terminal = state === "done" || state === "failed" || state === "cancelled";
+            const denied = allowed(terminal ? "close" : "transition", id);
+            return denied ?? backend.setState(id, state);
+        },
+        async addEdge(blocked, blocker) {
+            const denied = allowed("edge", blocked);
+            return denied ?? backend.addEdge(blocked, blocker);
+        },
+    };
+}

package/dist/backup-ui.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Settings → Backups (sprint 8): how the last backup went and one button to
+ * back up now, then the schedule. Past backups and how to restore sit in
+ * disclosures.
+ */
+import type { BackupRun, BackupSettings } from "./store.js";
+/** The schedules on offer and the most copies kept. Here rather than in backup.ts so the page never loads `node:sqlite`. */
+export declare const BACKUP_EVERY_HOURS: readonly [1, 6, 12, 24];
+export declare const MAX_KEEP = 100;
+export declare const BACKUP_CSS: string;
+export type BackupView = {
+    settings: BackupSettings;
+    folder: string;
+    defaultFolder: string;
+    runs: BackupRun[];
+    csrf: string;
+    now: Date;
+};
+export declare function backupHtml(view: BackupView, notice: {
+    said?: string | null;
+    problem?: string | null;
+}): string;

package/dist/backup-ui.js

@@ -0,0 +1,59 @@
+import { bytesWords } from "./storage.js";
+/** The schedules on offer and the most copies kept. Here rather than in backup.ts so the page never loads `node:sqlite`. */
+export const BACKUP_EVERY_HOURS = [1, 6, 12, 24];
+export const MAX_KEEP = 100;
+const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+const when = (at) => `${e(at.slice(0, 16).replace("T", " "))} UTC`;
+const everyWords = (hours) => hours === 1 ? "Every hour" : hours === 24 ? "Every day" : `Every ${hours} hours`;
+const fileName = (path) => path.slice(path.lastIndexOf("/") + 1);
+export const BACKUP_CSS = `.backups{max-width:720px;min-width:0;overflow-wrap:anywhere}.backups .backup-state{display:flex;gap:16px;align-items:flex-start;justify-content:space-between;flex-wrap:wrap}` +
+    `.backups .backup-state>div{flex:1 1 320px;min-width:0}.backups .backup-state h2{margin:0;font-size:1.0625rem}.backups .backup-state p{margin:4px 0 0}.backups .backup-state .problem{color:var(--danger)}` +
+    `.backups .backup-state form{margin:0}.backups .backup-state button{white-space:nowrap}` +
+    `.backups fieldset{border:0;padding:0;margin:0;min-width:0}.backups label{display:grid;gap:4px;margin:12px 0 0;font-size:.875rem}` +
+    `.backups input[type=text],.backups input[type=number],.backups input[type=password],.backups select{width:100%;box-sizing:border-box;max-width:100%}` +
+    `.backups .pair{display:grid;grid-template-columns:1fr 1fr;gap:12px}.backups button[type=submit]{margin-top:14px}` +
+    `.backups details{margin-top:16px}.backups summary{cursor:pointer}.backups ol{list-style:none;padding:0;margin:8px 0 0}` +
+    `.backups li{display:flex;gap:8px 12px;flex-wrap:wrap;padding:8px 0;border-top:1px solid var(--line, rgba(0,0,0,.08));font-size:.875rem}` +
+    `.backups li .failed{color:var(--danger)}.backups code{white-space:nowrap}.backups pre{overflow-x:auto;margin:8px 0}` +
+    `@media (max-width:900px){.backups .backup-state form,.backups .backup-state button{width:100%}.backups .pair{grid-template-columns:1fr}}`;
+/** The state in one line, and the next backup (if any), for the top of the page. */
+function state(view) {
+    const last = view.runs[0];
+    const good = view.runs.find(one => one.ok === true);
+    const next = !view.settings.enabled ? "Scheduled backups are off."
+        : good === undefined ? "The first scheduled backup runs within a minute or two of the console starting."
+            : `Next one about ${when(new Date(Date.parse(good.startedAt) + view.settings.everyHours * 3_600_000).toISOString())}.`;
+    if (last === undefined)
+        return `<h2>No backups yet</h2><p class="meta">${e(next)}</p>`;
+    if (last.ok === null)
+        return `<h2>Backing up</h2><p class="meta">Started ${when(last.startedAt)}.</p>`;
+    if (last.ok === false) {
+        return `<h2 data-backup-state="failed">Last backup failed</h2><p class="problem" role="alert">${when(last.startedAt)}: ${e(last.error ?? "no reason was recorded")}</p>` +
+            `<p class="meta">${good === undefined ? "No backup has succeeded yet." : `Last good backup ${when(good.startedAt)}.`} ${e(next)}</p>`;
+    }
+    return `<h2 data-backup-state="ok">Backed up ${when(last.startedAt)}</h2><p class="meta">${last.bytes === null ? "" : `${e(bytesWords(last.bytes))} · `}${e(next)}</p>`;
+}
+export function backupHtml(view, notice) {
+    const s = view.settings;
+    const note = notice.problem ? `<p class="problem" role="alert">${e(notice.problem)}</p>` : notice.said ? `<p role="status">${e(notice.said)}</p>` : "";
+    const csrf = `<input type="hidden" name="csrf" value="${e(view.csrf)}">`;
+    const choices = [`<option value="off"${s.enabled ? "" : " selected"}>Off</option>`,
+        ...BACKUP_EVERY_HOURS.map(hours => `<option value="${hours}"${s.enabled && s.everyHours === hours ? " selected" : ""}>${everyWords(hours)}</option>`)].join("");
+    const runs = view.runs.map(run => `<li data-backup-run="${run.id}"><span>${when(run.startedAt)}</span>` +
+        (run.ok === true ? `<span>Succeeded${run.bytes === null ? "" : ` · ${e(bytesWords(run.bytes))}`}</span>${run.file === null ? "" : `<span class="mono meta">${e(fileName(run.file))}</span>`}`
+            : run.ok === false ? `<span class="failed">Failed: ${e(run.error ?? "no reason recorded")}</span>` : `<span>Running</span>`) +
+        `<span class="meta">${run.trigger === "manual" ? "by hand" : "scheduled"}</span></li>`).join("");
+    return `<section class="backups">${note}` +
+        `<div class="card backup-state"><div>${state(view)}</div>` +
+        `<form method="post" action="/settings/backups/now">${csrf}<button type="submit">Back up now</button></form></div>` +
+        `<h2>Schedule</h2>` +
+        `<form method="post" action="/settings/backups">${csrf}<fieldset>` +
+        `<div class="pair"><label>Back up<select name="every">${choices}</select></label>` +
+        `<label>Keep the newest<input type="number" name="keep" min="1" max="${MAX_KEEP}" step="1" value="${s.keep}" required></label></div>` +
+        `<label>Folder<input type="text" name="folder" value="${e(s.folder ?? "")}" placeholder="${e(view.defaultFolder)}" spellcheck="false"></label>` +
+        `<label>Your Toolroll password<input type="password" name="password" autocomplete="current-password"></label>` +
+        `</fieldset><button type="submit">Save</button></form>` +
+        `<details><summary>Recent backups${view.runs.length === 0 ? "" : ` (${view.runs.length})`}</summary>${runs === "" ? `<p class="meta">None yet.</p>` : `<ol>${runs}</ol>`}<p class="meta">In <span class="mono">${e(view.folder)}</span>. Only the database is copied: provider keys and sign-in files stay out.</p></details>` +
+        `<details><summary>Restore a backup</summary><p>Stop Toolroll, then run:</p><pre><code>toolroll restore &lt;file&gt; --dry-run</code></pre>` +
+        `<p class="meta">The dry run checks the backup (its version and ledger chain) and changes nothing. Run it again without <code>--dry-run</code> to restore; the current database is kept as a copy first.</p></details></section>`;
+}

package/dist/backup.d.ts

@@ -0,0 +1,84 @@
+import { BACKUP_EVERY_HOURS, MAX_KEEP } from "./backup-ui.js";
+import { type BackupSettings, type Store } from "./store.js";
+/** The oldest schema whose ledger has a hash chain to verify. */
+export declare const OLDEST_RESTORABLE = 103;
+export { BACKUP_EVERY_HOURS, MAX_KEEP };
+export declare const defaultBackupFolder: (databaseFile: string) => string;
+export declare const backupFolderOf: (settings: BackupSettings, databaseFile: string) => string;
+/** Copy `sourceFile` into `target` with the online backup (all pages in one step: one consistent snapshot, and
+ * writers carry on meanwhile), then make the copy one self-contained file and check it. */
+export declare function onlineCopy(sourceFile: string, target: string): Promise<{
+    bytes: number;
+    schemaVersion: number | null;
+}>;
+/** A folder the operator may choose: a full path, outside every project and build checkout (agents work there). */
+export declare function checkBackupFolder(path: string, forbidden: readonly string[]): string | null;
+/** A short tag for one database, from its full path, so databases that share a backup folder tell their backups apart. */
+export declare function databaseTag(databaseFile: string): string;
+/** Whose backups are whose: this database's tag, and every backup file its own history records making. */
+export type BackupOwner = {
+    tag: string;
+    made: ReadonlySet<string>;
+};
+export declare function backupOwner(store: Store, databaseFile: string): BackupOwner;
+/** This database's backups in a folder, made on a schedule or by `backup now`, newest first. A backup tagged for
+ * another database is never this one's. An untagged one (made before backups were tagged) is this one's only when its
+ * own history records making it: pruning deletes, so what can't be proved ours is left alone. */
+export declare function backupFiles(folder: string, owner: BackupOwner): {
+    name: string;
+    path: string;
+    bytes: number;
+}[];
+/** Remove all but this database's newest `keep` backups. Never touches another database's, or anything else in the folder. */
+export declare function pruneBackups(folder: string, keep: number, owner: BackupOwner): number;
+export type BackupOutcome = {
+    ok: true;
+    id: number;
+    file: string;
+    bytes: number;
+    removed: number;
+} | {
+    ok: false;
+    id: number;
+    error: string;
+};
+/** Back the database up now, keep the newest N, and record how it went. */
+export declare function backupNow(store: Store, databaseFile: string, trigger: "scheduled" | "manual", clock?: () => Date): Promise<BackupOutcome>;
+/** Whether a scheduled backup is due: the last good one is older than the schedule, and the last try over an hour ago. */
+export declare function backupDue(store: Store, now: Date): boolean;
+/** One pass of the loop beside the console: renew the lease (a restore sees it), and back up when due. */
+export declare function backupPass(store: Store, databaseFile: string, holder: string, clock?: () => Date): Promise<BackupOutcome | null>;
+/** The loop beside the console: a pass a minute. */
+export declare function startBackups(store: Store, databaseFile: string, everyMs?: number): () => void;
+/** What's running against the database now: the console (its backup lease), and workers (watch leases, runner heartbeats). */
+export declare function runningNow(store: Store, now: Date): string[];
+export type RestoreRefusal = "not-found" | "same-file" | "running" | "unreadable" | "schema" | "ledger";
+export type RestoreReport = {
+    ok: boolean;
+    dryRun: boolean;
+    file: string;
+    /** Why it won't restore, each in words (every check that failed, so one attempt shows them all). */
+    refusals: {
+        reason: RestoreRefusal;
+        words: string;
+    }[];
+    schemaVersion: number | null;
+    ledger: {
+        entries: number;
+        through: number | null;
+    } | null;
+    /** Where the database as it was before the restore is kept (null on a dry run or a refusal). */
+    savedAs: string | null;
+};
+/**
+ * Put a backup back in place of the database. Refuses while Toolroll is running, when the backup isn't a
+ * Toolroll database this build can read (its schema version), or when its ledger chain doesn't verify. The
+ * backup is copied beside the database first and every check runs on that copy, so what was checked is what goes in.
+ */
+export declare function restoreDatabase(options: {
+    databaseFile: string;
+    file: string;
+    dryRun: boolean;
+    now: Date;
+    actor?: string;
+}): Promise<RestoreReport>;