toolroll 0.8.0 → 0.8.1

package/dist/toolroll-update.d.ts

@@ -2,6 +2,7 @@ import type { DatabaseSync } from "node:sqlite";
 import { type SupervisorRunner } from "./daemon.js";
 export declare const PROVENANCE_REPOSITORY = "https://github.com/ap9000/toolroll";
 export declare const PROVENANCE_WORKFLOW = ".github/workflows/publish.yml";
+export declare const PROVENANCE_ISSUER = "https://token.actions.githubusercontent.com";
 /** The steps a person sees, in order. */
 export declare const UPDATE_STEPS: readonly ["verifying", "draining", "backing-up", "rehearsing", "switching", "restarting", "health"];
 export type UpdateStep = typeof UPDATE_STEPS[number];
@@ -66,6 +67,11 @@ export type RuntimeUpdateJournal = {
         unit: string;
         pids: number[];
     };
+    /** Each repo's watch daemon that runs this version, recorded the same way: stopped, switched and restarted with the service. */
+    watches?: {
+        unit: string;
+        pids: number[];
+    }[];
     /** Recorded before each change so a resumed or failed run knows what to put back. */
     switched?: {
         links: {
@@ -76,10 +82,16 @@ export type RuntimeUpdateJournal = {
             path: string;
             saved: string;
         } | null;
+        watches?: {
+            path: string;
+            saved: string;
+        }[];
         databaseRestored?: boolean;
     };
     /** What the live database held when a failed run restored its backup: nothing written is lost. */
     keptAside?: string;
+    /** The live database could not be read, so it was moved aside whole rather than copied. */
+    keptAsideUnreadable?: boolean;
     /** The restore put the backup back: a retried restore never puts it back again (what was written since belongs to
      * the restored version and would be lost), and it keeps a fresh copy aside before every attempt until then. */
     restoredDatabase?: boolean;
@@ -107,6 +119,14 @@ export type UpdateSystem = {
     commands: (from: RuntimeRef) => string[];
     /** The background service's definition, when one runs `from`. */
     serviceUnit: (from: RuntimeRef) => string | null;
+    /** Every repo's watch daemon definition that runs `from`. */
+    watchUnits: (from: RuntimeRef) => string[];
+    /** npm's own Sigstore verifier: the bundle's certificate chains to Sigstore, its signature is in the transparency
+     * log, and the certificate names exactly this identity. */
+    sigstore: (bundle: unknown, identity: {
+        issuer: string;
+        identity: string;
+    }) => Promise<void>;
     /** The processes the service runs now. */
     servicePids: (unit: string) => Promise<number[]>;
     /** Unload the service; resolves once launchd no longer has it. */
@@ -128,16 +148,23 @@ export type UpdateOutcome = {
     journal: RuntimeUpdateJournal | null;
 };
 export declare const runtimeUpdateTerminal: (phase: RuntimePhase) => boolean;
-export declare function readRuntimeUpdate(stateDir: string): RuntimeUpdateJournal | null;
+export declare function readRuntimeUpdate(stateDir: string, file?: string): RuntimeUpdateJournal | null;
+/** The update `--rollback` returns from: the last one that completed, whatever was attempted since. */
+export declare function lastCompletedUpdate(stateDir: string): RuntimeUpdateJournal | null;
 /** Running work by name, for a refusal a person can act on. */
 export declare function runningWorkWords(db: DatabaseSync): string | null;
-/** The npm provenance statement for exactly these bytes must name the
- * Toolroll repository and its publish workflow. Anything else is refused.
- * npm's own check (UpdateSystem.install) verifies the statement's signature. */
-export declare function checkProvenance(attestations: unknown, version: string, sha512Hex: string): {
+export type Provenance = {
     repository: string;
     workflow: string;
+    issuer: string;
+    identity: string;
+    bundle: unknown;
 };
+/** The npm provenance for exactly these bytes of Toolroll itself must be signed by a certificate that names the
+ * Toolroll repository, its publish workflow and GitHub Actions as the issuer. The statement's own claims name
+ * nobody: only the certificate, whose key must have signed the statement. Sigstore's chain and transparency log are
+ * then checked by npm's own verifier (UpdateSystem.sigstore) for the identity returned here. */
+export declare function checkProvenance(attestations: unknown, version: string, sha512Hex: string): Provenance;
 /** Headlines of this version's changelog section: its bold lead phrases. */
 export declare function releaseNotes(changelog: string, version: string): string[];
 /** Every rename here: what is renamed is flushed first (a file itself, a link
@@ -184,7 +211,7 @@ export declare function startRuntimeRollback(o: {
 export declare function resumeRuntimeUpdate(stateDir: string, system: UpdateSystem, id?: string): Promise<UpdateOutcome>;
 /** A prepared update whose job could not start. */
 export declare function abandonRuntimeUpdate(stateDir: string, id: string, why: string, now: Date): void;
-export declare function requestRuntimeUpdateCancel(stateDir: string): string;
+export declare function requestRuntimeUpdateCancel(stateDir: string, now?: Date): string;
 /** Keep the newest release-* runtimes (and any in `keep`), at most KEEP_RUNTIMES; deploy-browser's browser-* and
  * the rollback-* records are not this updater's to remove. */
 export declare function pruneRuntimes(stateDir: string, keep: readonly string[]): string[];
@@ -202,24 +229,30 @@ export declare function markWhatsNewSeen(stateDir: string): void;
 type Exec = (command: string, args: string[], options?: {
     cwd?: string;
     timeout?: number;
+    input?: string;
 }) => {
     status: number | null;
     stdout: string;
     stderr: string;
 };
 export declare function currentRuntime(version: string): RuntimeRef;
-/** Seams for tests: npm and ps (`exec`), launchctl (`run`), and process liveness. */
+/** Seams for tests: npm, node and ps (`exec`), launchctl (`run`), process liveness, and launchd's waits (`sleep`). */
 export type MachineSeams = {
     exec?: Exec;
     run?: SupervisorRunner;
     alive?: (pid: number) => boolean;
+    sleep?: (ms: number) => Promise<void>;
+    execPath?: string;
 };
 export declare function machineSystem(home?: string, env?: Record<string, string | undefined>, seams?: MachineSeams): UpdateSystem;
-/** The console starts the updater for one prepared journal as its own one-off
- * launchd job, so the service it restarts is not its parent. The job resumes
- * that id only; it does not run at login (no RunAtLoad: launchd starts it
- * with a kickstart) and removes its definition when it finishes. Elsewhere it
- * is a detached process. */
+/** npm's own Sigstore verifier. Found from npm itself (the `npm` on PATH, then the one beside node), never only from
+ * `npm root --global`: with a custom global prefix (npm's advice for permission errors) that folder holds the global
+ * packages, not npm. */
+export declare function findSigstoreVerifier(o: {
+    path: string;
+    execPath: string;
+    npmRoot: () => string | null;
+}): string | null;
 export declare function launchRuntimeUpdate(args: {
     databaseFile: string;
     id: string;
@@ -228,6 +261,7 @@ export declare function launchRuntimeUpdate(args: {
     home?: string;
     run?: SupervisorRunner;
     platform?: NodeJS.Platform;
+    npmBin?: () => string | null;
 }): Promise<void>;
 /** The job's last act: its definition goes, so nothing can start it again. Only the definition for this id. */
 export declare function retireUpdateJob(id: string, home?: string): void;