@a2f0/agent-tool 0.1.40 → 0.1.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2f0/agent-tool",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "packageManager": "bun@1.4.4",
   "type": "module",
   "description": "Portable cross-agent review, PR workflows, and shared skills",

package/src/commands/group.ts

@@ -41,6 +41,63 @@ export function parseGroup(source: string): { label: string; steps: Step[] } {
   }
   return plan;
 }
+/** One step of a run-group report: only a finished step has a receipt, and a failed one lacks it only when its runner could not start. */
+export type GroupStep =
+  | { label: string; status: "pending" | "running"; receipt: null }
+  | { label: string; status: "passed" | "failed"; receipt: RunReceipt | null };
+
+/**
+ * A run-group report as saved and printed. Field order is the report's JSON
+ * order. `endedAt` is set exactly when the group is no longer running; `after`
+ * stays null when the final source state could not be read.
+ */
+export type GroupRecord = {
+  schemaVersion: 1; id: string; label: string; startedAt: string; endedAt: string | null; durationMs: number;
+  status: "running" | "passed" | "failed"; before: SourceState; after: SourceState | null; steps: GroupStep[]; error: string | null;
+};
+
+export type GroupEvent =
+  | { type: "stepStarted"; index: number }
+  | { type: "stepFinished"; index: number; receipt: RunReceipt }
+  | { type: "failed"; error: string }
+  | { type: "finished"; passed: boolean; endedAt: string; durationMs: number }
+  | { type: "settled"; after: SourceState }
+  | { type: "settleFailed"; error: string };
+
+/**
+ * The only writer of a run-group report. Events outside their state are
+ * ignored: a step starts only from pending, finishes only while running, and
+ * nothing but the final source read changes a finished group. A failure while
+ * a step runs (its runner could not start) finishes that step as failed with
+ * no receipt, so a finished report never shows a step still running.
+ */
+export function groupTransition(record: GroupRecord, event: GroupEvent): GroupRecord {
+  const step = (index: number, next: GroupStep) => ({ ...record, steps: record.steps.map((item, at) => at === index ? next : item) });
+  switch (event.type) {
+    case "stepStarted": {
+      const current = record.steps[event.index];
+      return record.status === "running" && current?.status === "pending" ? step(event.index, { label: current.label, status: "running", receipt: null }) : record;
+    }
+    case "stepFinished": {
+      const current = record.steps[event.index];
+      return record.status === "running" && current?.status === "running" ? step(event.index, { label: current.label, status: event.receipt.status === "passed" ? "passed" : "failed", receipt: event.receipt }) : record;
+    }
+    case "failed":
+      if (record.status !== "running") return record;
+      return { ...record, steps: record.steps.map(item => item.status === "running" ? { label: item.label, status: "failed", receipt: null } : item), error: event.error };
+    case "finished":
+      return record.status === "running" ? { ...record, status: event.passed ? "passed" : "failed", endedAt: event.endedAt, durationMs: event.durationMs } : record;
+    case "settled":
+      return record.status !== "running" && record.after === null ? { ...record, after: event.after } : record;
+    case "settleFailed":
+      return record.status !== "running" && record.after === null ? { ...record, status: "failed", error: record.error ?? event.error } : record;
+    default:
+      return assertNever(event);
+  }
+}
+
+function assertNever(value: never): never { throw new Error(`Unhandled run-group event: ${JSON.stringify(value)}`); }
+
 export async function runGroup(args: string[]): Promise<number> {
   assert(args.length === 1, "Usage: run-group <plan.json>");
   const plan = parseGroup(readFileSync(args[0]!, "utf8"));
@@ -49,21 +106,21 @@ export async function runGroup(args: string[]): Promise<number> {
   const id = `${new Date().toISOString().replaceAll(":", "-")}-${randomUUID()}`;
   const report = path.join(directory, `${id}.json`);
   const started = performance.now();
-  const record = { schemaVersion: 1, id, label: plan.label, startedAt: new Date().toISOString(), endedAt: null as string | null, durationMs: 0, status: "running", before, after: null as SourceState | null, steps: plan.steps.map(step => ({ label: step.label, status: "pending", receipt: null as RunReceipt | null })), error: null as string | null };
+  let record: GroupRecord = { schemaVersion: 1, id, label: plan.label, startedAt: new Date().toISOString(), endedAt: null, durationMs: 0, status: "running", before, after: null, steps: plan.steps.map(step => ({ label: step.label, status: "pending", receipt: null })), error: null };
+  const send = (event: GroupEvent) => { record = groupTransition(record, event); };
   save(report, record);
   let code = 0;
   try {
     for (const [index, step] of plan.steps.entries()) {
-      record.steps[index]!.status = "running"; save(report, record);
-      code = await runCommand(["--label", step.label, "--", ...step.command], receipt => { record.steps[index]!.receipt = receipt; record.steps[index]!.status = receipt.status; save(report, record); }, { quiet: true, reraiseChildSignal: false });
+      send({ type: "stepStarted", index }); save(report, record);
+      code = await runCommand(["--label", step.label, "--", ...step.command], receipt => { send({ type: "stepFinished", index, receipt }); save(report, record); }, { quiet: true, reraiseChildSignal: false });
       const after = sourceState();
       assert(JSON.stringify(after) === JSON.stringify(before), "Source state changed during validation; results do not establish the current checkout.");
       if (code !== 0) break;
     }
-  } catch (error) { code = 1; record.error = (error as Error).message; }
-  record.status = code === 0 ? "passed" : "failed";
-  record.endedAt = new Date().toISOString(); record.durationMs = Math.round(performance.now() - started);
-  try { record.after = sourceState(); } catch (error) { code = 1; record.status = "failed"; record.error ??= (error as Error).message; }
+  } catch (error) { code = 1; send({ type: "failed", error: (error as Error).message }); }
+  send({ type: "finished", passed: code === 0, endedAt: new Date().toISOString(), durationMs: Math.round(performance.now() - started) });
+  try { send({ type: "settled", after: sourceState() }); } catch (error) { code = 1; send({ type: "settleFailed", error: (error as Error).message }); }
   save(report, record);
   output({ ...record, report }); return code;
 }

package/src/release/commands.ts

@@ -6,12 +6,19 @@ import { assert, flag, json, oid, option, output, poll, repository, timeoutOptio
 
 function packageName(name: unknown): asserts name is string { assert(typeof name === "string" && /^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/.test(name), "Invalid npm package name."); }
 export interface ReleaseRun { databaseId: number; status: string; conclusion: string; headSha: string; url: string }
-export async function verifyTarball(metadata: { name: string; version: string; dist: { tarball: string; integrity: string } }): Promise<{ tarball: string; integrity: string }> {
+/**
+ * Downloads and checks the published tarball. Resolves null only when the
+ * registry answers 404 or 410: npm can list a version minutes before its
+ * tarball is served, so absence is a propagation delay. Any other failure,
+ * including a tarball that downloads but does not match, throws.
+ */
+export async function verifyTarball(metadata: { name: string; version: string; dist: { tarball: string; integrity: string } }): Promise<{ tarball: string; integrity: string } | null> {
   const url = new URL(metadata.dist.tarball);
   assert(url.protocol === "https:" && url.hostname === "registry.npmjs.org", "Expected an HTTPS npm registry tarball.");
   const integrity = /^sha512-([A-Za-z0-9+/]+={0,2})$/.exec(metadata.dist.integrity);
   assert(integrity, "Package must have SHA-512 tarball integrity.");
   const response = await fetch(url, { signal: AbortSignal.timeout(60_000), redirect: "error" });
+  if (response.status === 404 || response.status === 410) { await response.body?.cancel(); return null; }
   assert(response.ok && response.body, "Could not download the published tarball.");
   const chunks: Uint8Array[] = []; let size = 0;
   for await (const chunk of response.body) { size += chunk.length; assert(size <= 100 * 1024 * 1024, "Tarball exceeds the 100 MiB verification limit."); chunks.push(chunk); }
@@ -39,6 +46,7 @@ export async function inspectRelease(
   assert(metadata.name === expected.name && metadata.version === expected.version, "Registry returned a different package version.");
   assert(!metadata.gitHead || metadata.gitHead === expected.commit, "Registry gitHead differs from the publishing merge commit.");
   const artifact = await checkArtifact(metadata);
+  if (!artifact) return { done: false, value: { ok: false, reason: "Tarball has not propagated to npm.", run } };
   return { done: true, value: { ok: true, reason: "Workflow and published tarball verified.", run, ...artifact, gitHead: metadata.gitHead ?? null } };
 }
 

package/src/screenshots/gallery.ts

@@ -125,6 +125,49 @@ export function typicalRatio(entries: readonly { width: number; height: number }
   return ratios.length % 2 ? ratios[middle]! : (ratios[middle - 1]! + ratios[middle]!) / 2;
 }
 
+/**
+ * Where a gallery is in loading its manifest. Each load gets a new request
+ * number, and only the current request may finish: a manifest or failure that
+ * arrives for a replaced request, or after disconnecting, is ignored. A
+ * rendered gallery is `ready`; while it first renders (`rendering`) its initial
+ * selection leaves the URL alone. Loading, failed, and empty galleries ignore
+ * selections.
+ */
+export type GalleryPhase =
+  | { status: "idle" }
+  | { status: "loading"; request: number }
+  | { status: "failed" }
+  | { status: "empty" }
+  | { status: "rendering" }
+  | { status: "ready" };
+
+export type GalleryEvent =
+  | { type: "load"; request: number }
+  | { type: "loaded"; request: number; empty: boolean }
+  | { type: "fail"; request: number }
+  | { type: "rendered" }
+  | { type: "disconnect" };
+
+/** The only writer of a gallery's phase; an event that does not apply returns the same phase. */
+export function galleryTransition(phase: GalleryPhase, event: GalleryEvent): GalleryPhase {
+  switch (event.type) {
+    case "load":
+      return phase.status === "loading" && phase.request === event.request ? phase : { status: "loading", request: event.request };
+    case "loaded":
+      return phase.status === "loading" && phase.request === event.request ? { status: event.empty ? "empty" : "rendering" } : phase;
+    case "fail":
+      return phase.status === "loading" && phase.request === event.request ? { status: "failed" } : phase;
+    case "rendered":
+      return phase.status === "rendering" ? { status: "ready" } : phase;
+    case "disconnect":
+      return phase.status === "idle" ? phase : { status: "idle" };
+    default:
+      return assertNever(event);
+  }
+}
+
+function assertNever(value: never): never { throw new Error(`Unhandled gallery event: ${JSON.stringify(value)}`); }
+
 export interface ScreenshotChangeDetail { project: string; theme: string; screen: string; index: number; total: number }
 
 export interface ScreenshotGalleryElement extends HTMLElement {
@@ -241,7 +284,8 @@ function defineGallery(): CustomElementConstructor {
     #target: number | null = null;
     #expanded = false;
     #overflow = "";
-    #rendered = false;
+    #phase: GalleryPhase = { status: "idle" };
+    #requests = 0;
     #announced = "";
     #wheel = createWheelStepper();
 
@@ -259,7 +303,7 @@ function defineGallery(): CustomElementConstructor {
 
     #connected = false;
     connectedCallback(): void { this.#connected = true; this.#load(); }
-    disconnectedCallback(): void { this.#connected = false; this.#teardown(); }
+    disconnectedCallback(): void { this.#connected = false; this.#send({ type: "disconnect" }); this.#teardown(); }
     // An upgrade reports initial attributes before connecting; only later changes reload.
     attributeChangedCallback(_name: string, previous: string | null, next: string | null): void {
       if (previous !== next && this.#connected && !this.#data) this.#load();
@@ -272,22 +316,37 @@ function defineGallery(): CustomElementConstructor {
       this.#expanded = false;
     }
 
+    /** Applies `event`; false when it did not apply, so its work must not run. */
+    #send(event: GalleryEvent): boolean {
+      const next = galleryTransition(this.#phase, event);
+      if (next === this.#phase) return false;
+      this.#phase = next;
+      return true;
+    }
+
     #load(): void {
       this.#teardown();
-      const abort = new AbortController();
-      this.#abort = abort;
-      this.#rendered = false;
+      this.#abort = new AbortController();
+      this.#send({ type: "load", request: ++this.#requests });
       this.classList.add("shots-host");
-      if (this.#data) { this.#render(this.#data); return; }
+      // The work belongs to the request just entered, never to whichever load is merely in progress.
+      if (this.#phase.status === "loading") this.#fetch(this.#phase.request, this.#abort.signal);
+    }
+
+    #fetch(request: number, signal: AbortSignal): void {
+      if (this.#data) { this.#receive(request, this.#data); return; }
       const url = this.getAttribute("manifest");
       status(this, "loading", "Loading screenshots…");
-      if (!url) { this.#fail(new Error("screenshot-gallery needs a manifest attribute.")); return; }
-      loadManifest(url, abort.signal).then(manifest => { if (!abort.signal.aborted) this.#render(manifest); }, (error: unknown) => {
-        if (!abort.signal.aborted) this.#fail(error);
-      });
+      if (!url) { this.#fail(request, new Error("screenshot-gallery needs a manifest attribute.")); return; }
+      loadManifest(url, signal).then(manifest => this.#receive(request, manifest), (error: unknown) => this.#fail(request, error));
     }
 
-    #fail(error: unknown): void {
+    #receive(request: number, manifest: ScreenshotManifest): void {
+      if (this.#send({ type: "loaded", request, empty: !manifest.entries.length })) this.#render(manifest);
+    }
+
+    #fail(request: number, error: unknown): void {
+      if (!this.#send({ type: "fail", request })) return;
       status(this, "error", this.getAttribute("error-message") ?? "Screenshots didn't load. Refresh to try again.");
       this.dispatchEvent(new CustomEvent("screenshot-error", { bubbles: true, detail: { error } }));
     }
@@ -296,7 +355,7 @@ function defineGallery(): CustomElementConstructor {
 
     #render(manifest: ScreenshotManifest): void {
       this.#manifest = manifest;
-      if (!manifest.entries.length) { status(this, "empty", this.getAttribute("empty-message") ?? "Screenshots aren't available yet."); return; }
+      if (this.#phase.status === "empty") { status(this, "empty", this.getAttribute("empty-message") ?? "Screenshots aren't available yet."); return; }
       const deepLink = typeof location === "undefined" ? undefined : parseScreenshotPath(this.#basePath(), location.pathname);
       const requestedProject = this.getAttribute("initial-project") ?? deepLink?.project;
       const requestedScreen = this.getAttribute("initial-screen") ?? deepLink?.screen;
@@ -357,7 +416,7 @@ function defineGallery(): CustomElementConstructor {
       }
       window.addEventListener("keydown", (event: KeyboardEvent) => this.#key(event), { signal });
       this.#renderProject(screen);
-      this.#rendered = true;
+      this.#send({ type: "rendered" });
     }
 
     #key(event: KeyboardEvent): void {
@@ -564,7 +623,7 @@ function defineGallery(): CustomElementConstructor {
       const key = `${this.#project} ${this.#theme} ${name}`;
       if (key === this.#announced) return;
       this.#announced = key;
-      if (this.#rendered || !initial) this.#syncUrl(name);
+      if (this.#phase.status === "ready" || !initial) this.#syncUrl(name);
       this.dispatchEvent(new CustomEvent<ScreenshotChangeDetail>("screenshot-change", { bubbles: true, detail: { project: this.#project, theme: this.#theme, screen: name, index: this.#index, total: count } }));
     }
 
@@ -627,7 +686,7 @@ function defineGallery(): CustomElementConstructor {
 
     select(selection: { project?: string; theme?: string; screen?: string }): void {
       const manifest = this.#manifest;
-      if (!manifest || !this.#root) return;
+      if (!this.#shows() || !manifest) return;
       const screen = selection.screen ?? this.screen;
       if (selection.project && selection.project !== this.#project && manifest.projects.some(project => project.name === selection.project)) {
         this.#project = selection.project;
@@ -646,7 +705,14 @@ function defineGallery(): CustomElementConstructor {
       if (selection.screen && this.#screens.includes(selection.screen)) this.#select(this.#screens.indexOf(selection.screen), scrollBehavior());
     }
 
-    step(delta: number): void { this.#select(this.#index + delta, scrollBehavior()); }
+    step(delta: number): void { if (this.#shows()) this.#select(this.#index + delta, scrollBehavior()); }
+
+    /**
+     * Whether the fields describe what the gallery shows: loading, failed, and empty galleries keep the
+     * last render's fields. A first render shows once its DOM is built, so a listener to its initial
+     * `screenshot-change` can already select.
+     */
+    #shows(): boolean { return this.#phase.status === "ready" || this.#phase.status === "rendering"; }
   };
 }