hi
"); + git("add", "-A"); + git("commit", "-qm", "init"); + }); + afterEach(() => fs.rm(dir, { recursive: true, force: true })); + + it("reads HEAD, the branch and a clean tree", async () => { + const s = await readSource(dir, { target: "http://localhost:1/" }); + expect(s?.commit).toMatch(/^[0-9a-f]{40}$/); + expect(s?.branch).toBe("main"); + expect(s?.dirty).toBe(0); + expect(s?.local).toBe(true); + }); + + it("lists dirty files, leaving the crawl's own out", async () => { + await fs.writeFile(path.join(dir, "index.html"), "changed
"); + await fs.writeFile(path.join(dir, "visualice.routes.md"), "# Routes"); + const s = await readSource(dir, { ignore: [path.join(dir, "visualice.routes.md")] }); + expect(s?.dirty).toBe(1); + expect(s?.dirtyFiles).toEqual(["index.html"]); + }); + + it("is undefined outside a repository", async () => { + const plain = await fs.mkdtemp(path.join(os.tmpdir(), "vc-plain-")); + try { + expect(await readSource(plain)).toBeUndefined(); + } finally { + await fs.rm(plain, { recursive: true, force: true }); + } + }); +}); diff --git a/viewer/src/App.tsx b/viewer/src/App.tsx index d21b520..6af12f8 100644 --- a/viewer/src/App.tsx +++ b/viewer/src/App.tsx @@ -985,6 +985,15 @@ export default function App({ onHome }: { onHome?: () => void } = {}) { closing={!selected} onClosed={() => setDetailed(null)} onFullScreen={openFull} + compare={ + siteEntry && shownSite && shownRun && siteEntry.runs.length > 1 + ? { + runs: siteEntry.runs.filter((r) => r !== shownRun), + baseFor: (r) => runBase(shownSite, r), + current: shownRun, + } + : undefined + } position={ detailedIndex >= 0 ? { index: detailedIndex + 1, total: layout.placed.length } diff --git a/viewer/src/Canvas.tsx b/viewer/src/Canvas.tsx index a4f4812..5c7de09 100644 --- a/viewer/src/Canvas.tsx +++ b/viewer/src/Canvas.tsx @@ -898,6 +898,7 @@ function TileCaption({ p, place }: { p: Placed; place: CaptionPlace }) { {tile.stateLabel}
{/* Short of room, the kind gives way first: the warnings matter more. */}
+ {tile.updated && updated }
{tile.stateKind}
{tile.device}
{p.page ? (
@@ -970,10 +977,13 @@ function DeviceCaption({ p, t, device }: { p: Placed; t: Transform; device?: Dev
function TileBadge({
children,
warn,
+ accent,
yields,
}: {
children: string;
warn?: boolean;
+ /** Shot by this (partial) run, where the rest was carried over. */
+ accent?: boolean;
/** The one that gives up its room when there isn't enough; the others keep theirs. */
yields?: boolean;
}) {
@@ -983,7 +993,11 @@ function TileBadge({
className={cx(
"truncate rounded-[4px] border bg-chip px-1 font-mono text-[10px] leading-[15px] whitespace-nowrap",
yields ? "min-w-[2.5ch]" : "shrink-0",
- warn ? "border-amber-line text-amber" : "border-line-strong text-dim",
+ warn
+ ? "border-amber-line text-amber"
+ : accent
+ ? "border-accent-line bg-accent-soft font-semibold text-accent"
+ : "border-line-strong text-dim",
)}
>
{children}
diff --git a/viewer/src/Compare.tsx b/viewer/src/Compare.tsx
new file mode 100644
index 0000000..719e867
--- /dev/null
+++ b/viewer/src/Compare.tsx
@@ -0,0 +1,149 @@
+import { useEffect, useState } from "react";
+import { fetchViewerData } from "./load";
+import { runLabel } from "./format";
+import type { ViewerData, ViewerTile } from "./types";
+import { Caption, cx } from "./ui";
+
+/** Other versions of the site this shot can be compared with. */
+export interface CompareRuns {
+ /** Run ids, newest first, without the one on screen. */
+ runs: string[];
+ /** Where a run's files are served. */
+ baseFor: (run: string) => string;
+ /** The run on screen. */
+ current: string;
+}
+
+/** Each run's data, fetched once: stepping through shots compares against the same run. */
+const cache = new Map>();
+function loadRun(url: string): Promise {
+ let hit = cache.get(url);
+ if (!hit) {
+ hit = fetchViewerData(url);
+ hit.catch(() => cache.delete(url));
+ cache.set(url, hit);
+ }
+ return hit;
+}
+
+/** The run a shot was really taken in: its own run, or the one it was carried from. */
+const takenIn = (tile: ViewerTile, run: string): string => tile.carried?.runId ?? run;
+
+/**
+ * The same shot in another version of the site, side by side with this one. Shots
+ * match by id (route, state and device), which stays put across runs. Two shots
+ * taken in the same run are the same image: a partial run carried it over.
+ */
+export function Compare({
+ tile,
+ base,
+ compare,
+}: {
+ tile: ViewerTile;
+ base: string;
+ compare: CompareRuns;
+}) {
+ // The version before this one by default: what "what changed?" usually means.
+ const older = compare.runs.find((r) => r < compare.current);
+ const [other, setOther] = useState(older ?? compare.runs[0]);
+ const [open, setOpen] = useState(false);
+ const [state, setState] = useState<
+ { run: string; tile?: ViewerTile; error?: string } | undefined
+ >();
+
+ // A string, not `compare`: the parent builds that object afresh on every render.
+ const otherBase = other ? compare.baseFor(other) : "";
+ useEffect(() => {
+ if (!open || !other) return;
+ let live = true;
+ setState(undefined);
+ loadRun(otherBase + "viewer-data.json")
+ .then(
+ (data) => live && setState({ run: other, tile: data.tiles.find((t) => t.id === tile.id) }),
+ )
+ .catch((e: Error) => live && setState({ run: other, error: e.message }));
+ return () => {
+ live = false;
+ };
+ }, [open, other, otherBase, tile.id]);
+
+ const theirs = state?.tile;
+ const same = theirs && takenIn(theirs, other) === takenIn(tile, compare.current);
+
+ return (
+
+ {label}
+ {tile && src && !tile.error ? (
+
+ 
+
+ ) : (
+
+ );
+}
diff --git a/viewer/src/Inspector.tsx b/viewer/src/Inspector.tsx
index 33b6ed2..64887cb 100644
--- a/viewer/src/Inspector.tsx
+++ b/viewer/src/Inspector.tsx
@@ -4,6 +4,7 @@ import type { Device, ViewerData, ViewerTile } from "./types";
import { runLabel } from "./format";
import { routePath } from "./layout";
import { ShotActions } from "./ShotActions";
+import { Compare, type CompareRuns } from "./Compare";
import { Caption, cx, deviceIcon, Icon, KindTag } from "./ui";
interface Props {
@@ -23,8 +24,12 @@ interface Props {
position?: { index: number; total: number };
/** Open this shot full screen. */
onFullScreen?: () => void;
+ /** Other versions of the site, to compare this shot with. */
+ compare?: CompareRuns;
}
+const short = (commit: string) => commit.slice(0, 7);
+
/** The label/value grid the details (and the shortcuts popover) use. */
export const DL = "grid gap-x-3 gap-y-2 text-[12.5px] [&>dd]:wrap-anywhere [&>dt]:text-dim";
@@ -52,6 +57,7 @@ export function Inspector({
onClosed,
position,
onFullScreen,
+ compare,
}: Props) {
const device: Device | undefined = data.devices.find((d) => d.name === tile.device);
@@ -219,6 +225,34 @@ export function Inspector({
)}
+ {tile.carried ? (
+
+ Carried over
+
+ ) : tile.updated ? (
+
+ Updated in this version
+
+ ) : null}
+
{tile.a11y ? (
setOpen((e.currentTarget as HTMLDetailsElement).open)}
+ >
+
+
+
+ );
+}
+
+function Side({ label, tile, base }: { label: string; tile?: ViewerTile; base: string }) {
+ const src = tile?.mid ?? tile?.thumb ?? tile?.full;
+ return (
+
+ Compare with another version
+
+ ▾
+
+
+
+
+ {!state ? (
+ Loading…
+ ) : state.error ? (
+
+ That version couldn’t be read: {state.error}
+
+ ) : (
+ <>
+
+
+
+
+ {!theirs
+ ? "This shot isn’t in that version: the page or state is new since."
+ : same
+ ? "The same shot: it was carried over unchanged, not taken again."
+ : "Taken separately in each version."}
+
+
+ )}
+
+ {tile?.error ? "Capture failed" : "Not captured"}
+
+ )}
+
+ Not shot in this version: nothing that changed touched this page, so the shot from{" "}
+ {runLabel(tile.carried.runId)} UTC
+ {tile.carried.commit && (
+ <>
+ {" "}
+ (commit {short(tile.carried.commit)})
+
+ )}{" "}
+ was kept.
+
+ Shot again because this page changed + {data.partial?.carriedFrom ? ( + <> since {runLabel(data.partial.carriedFrom)} UTC + ) : null} + ; pages nothing touched were carried over. +
+
@@ -262,6 +296,9 @@ export function Inspector({
)}
) : null}
+ {compare && compare.runs.length > 0 && (
+
{/* Pinned to the foot, where the hand ends up after reading. */}
@@ -274,7 +311,17 @@ export function Inspector({
/>
- Captured {runLabel(data.site.runId)} UTC
+
+ Captured {runLabel(tile.carried?.runId ?? data.site.runId)} UTC
+ {(tile.carried ? tile.carried.commit : data.source?.commit) && (
+ <>
+ {" · "}
+
Date: Tue, 10 Nov 2026 00:12:54 +0800
Subject: [PATCH 2/8] fix: Carry only shot files that stay inside their run
folder
---
src/crawl/carry.ts | 26 ++++++++++++++++++++++++--
tests/carry.test.ts | 11 +++++++++++
2 files changed, 35 insertions(+), 2 deletions(-)
diff --git a/src/crawl/carry.ts b/src/crawl/carry.ts
index d35ef23..a280968 100644
--- a/src/crawl/carry.ts
+++ b/src/crawl/carry.ts
@@ -163,7 +163,9 @@ export async function verifyCarry(
for (const route of plan.carry) {
const prev = source.manifest.routes.find((r) => r.url === route.url);
const files = prev ? carriedFiles(route, prev, devices) : [];
- const present = await Promise.all(files.map((f) => pathExists(path.join(source.runDir, f))));
+ const present = await Promise.all(
+ files.map((f) => (f ? pathExists(path.join(source.runDir, f)) : false)),
+ );
if (present.every(Boolean)) {
out.carry.push(route);
} else {
@@ -183,7 +185,9 @@ function carriedFiles(route: RouteNode, prev: RouteNode, devices: Device[]): str
if (!before) continue;
for (const device of devicesFor(state, devices)) {
const ref = before.shots[device];
- if (ref?.full && !ref.error) files.push(...shotFiles(ref));
+ if (!ref?.full || ref.error) continue;
+ if (!safeShotFiles(ref)) return [""]; // never carried: verifyCarry shoots the route
+ files.push(...shotFiles(ref));
}
}
return files;
@@ -196,6 +200,20 @@ function shotFiles(ref: ShotRef): string[] {
);
}
+/**
+ * Is every file a shot points at a plain relative path inside its run directory?
+ * The paths come from an earlier run's crawl-map.json, which is only data: one that
+ * names `../` or an absolute path must not make carrying read, replace or delete a
+ * file outside the run.
+ */
+export function safeShotFiles(ref: ShotRef): boolean {
+ return shotFiles(ref).every((rel) => {
+ if (!rel || path.isAbsolute(rel) || path.win32.isAbsolute(rel)) return false;
+ const norm = path.posix.normalize(rel.replace(/\\/g, "/"));
+ return norm !== ".." && !norm.startsWith("../") && !norm.startsWith("/");
+ });
+}
+
/** Hard-link `from` to `to`, copying instead where links aren't possible. */
async function linkOrCopy(from: string, to: string): Promise {
await fs.mkdir(path.dirname(to), { recursive: true });
@@ -228,6 +246,10 @@ export async function carryRoute(
for (const device of devicesFor(state, devices)) {
const ref = before.shots[device];
if (!ref?.full || ref.error) continue;
+ if (!safeShotFiles(ref)) {
+ state.shots[device] = { error: `run ${source.runId} lists a shot file outside its run` };
+ continue;
+ }
try {
for (const rel of shotFiles(ref)) {
await linkOrCopy(path.join(source.runDir, rel), path.join(runDir, rel));
diff --git a/tests/carry.test.ts b/tests/carry.test.ts
index 1663854..9a8b9ed 100644
--- a/tests/carry.test.ts
+++ b/tests/carry.test.ts
@@ -9,6 +9,7 @@ import {
findCarrySource,
matchesOnly,
planCarry,
+ safeShotFiles,
verifyCarry,
} from "../src/crawl/carry";
import { markRunIncomplete, runDir } from "../src/crawl/runs";
@@ -241,3 +242,13 @@ describe("--only seeds", () => {
]);
});
});
+
+describe("shot paths from an earlier run", () => {
+ it("are carried only when they stay inside the run", () => {
+ expect(safeShotFiles({ full: "screenshots/home/default/desktop.png" })).toBe(true);
+ expect(safeShotFiles({ full: "../../.bashrc" })).toBe(false);
+ expect(safeShotFiles({ full: "screenshots/../../x.png" })).toBe(false);
+ expect(safeShotFiles({ full: "/etc/passwd" })).toBe(false);
+ expect(safeShotFiles({ full: "a.png", thumb: "..\\..\\x.webp" })).toBe(false);
+ });
+});
From 0028f686dc8434e0c8c7f655f5174b7833df1739 Mon Sep 17 00:00:00 2001
From: Alexander Tenepere
Date: Tue, 10 Nov 2026 11:21:49 +0800
Subject: [PATCH 3/8] feat: Tell users when a newer visualice is out, and how
to turn on plugin auto-update
---
CHANGELOG.md | 9 +++
README.md | 5 ++
docs/crawling.md | 9 +++
skills/visualice/SKILL.md | 4 ++
src/cli.ts | 32 ++++++++++
src/shared/update-check.ts | 122 +++++++++++++++++++++++++++++++++++++
tests/update-check.test.ts | 112 ++++++++++++++++++++++++++++++++++
7 files changed, 293 insertions(+)
create mode 100644 src/shared/update-check.ts
create mode 100644 tests/update-check.test.ts
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 656e587..9e0e878 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,6 +27,15 @@
- **Compare with another version** in the details panel shows the same shot from another
run beside this one.
+### Update notice
+
+- An installed CLI tells you when a newer visualice is out (checked against npm at most
+ once a day, in the background, never in the way), with the command to update the
+ plugin or the CLI. The skill passes it on. Off with `--quiet`, in CI, or with
+ `VISUALICE_NO_UPDATE_CHECK=1`.
+- The README says how to turn on auto-update for the plugin: a marketplace plugin
+ doesn't update itself unless you do.
+
## 0.1.1
### Fixes
diff --git a/README.md b/README.md
index 6085246..c3d412a 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,11 @@ Needs Node 22.18 or newer.
/plugin install visualice@visualice
```
+Plugins from a marketplace like this one don't update on their own unless you ask: turn
+it on under `/plugin` → **Marketplaces** → visualice → **Enable auto-update**, or update
+by hand with `claude plugin update visualice@visualice`. The CLI also says when a newer
+version is out.
+
Then run `/visualice https://your.site`, or just ask Claude to "run visualice on
https://your.site". It maps the site, shows you the plan (the kinds of page, how many
screenshots, anything exploring would change on the site) and asks once, explores each
diff --git a/docs/crawling.md b/docs/crawling.md
index 4aa24cc..ac976eb 100644
--- a/docs/crawling.md
+++ b/docs/crawling.md
@@ -92,6 +92,15 @@ gitignored folder; once tracked, git keeps it) or restore it from a CI cache, th
`visualice crawl --replay --json --quiet --fail-on-error`. Without it, `--replay` falls
back to a full discovery and the explored states are missing.
+### Update notice
+
+An installed CLI checks npm for a newer visualice at most once a day, in the background,
+and says so on stderr at the start of a later command (`ℹ visualice 0.3.0 is available
+…`). It never delays a command for more than a moment, and a failed lookup is ignored.
+It is off with `--quiet`, in CI (`CI` set), in a source checkout, and with
+`VISUALICE_NO_UPDATE_CHECK=1` (or `NO_UPDATE_NOTIFIER=1`). The last answer is cached in
+`~/.cache/visualice/update-check.json` (`$XDG_CACHE_HOME` when set).
+
## Output
Output lands under the configured output directory (default `.visualice/`), one folder
diff --git a/skills/visualice/SKILL.md b/skills/visualice/SKILL.md
index 7bb8618..0a441dc 100644
--- a/skills/visualice/SKILL.md
+++ b/skills/visualice/SKILL.md
@@ -19,6 +19,10 @@ from any directory, no repo checkout needed. In a source checkout of this repo i
use the npm scripts instead: `npm run vc -- ` for anything below, `npm run crawl --
` for crawls. The commands below say `visualice`; substitute whichever applies.
+If a command prints `ℹ visualice X is available (you have Y)…` on stderr, tell the user
+once, with the update command it gives (`claude plugin update visualice@visualice`), and
+carry on with the task: don't update anything yourself.
+
Before the first crawl in a project, run `visualice doctor` — an idempotent preflight
that checks Node/Playwright chromium/sharp/the viewer build and self-heals what it
safely can (installs chromium, builds the viewer; `--no-fix` to only report). This
diff --git a/src/cli.ts b/src/cli.ts
index 5efc4f8..a3e753e 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -34,6 +34,7 @@ import {
} from "./crawl/routes-file";
import { ensureStorageState } from "./crawl/auth";
import { pathExists } from "./shared/fsx";
+import { startUpdateCheck, updateCheckDisabled, type UpdateCheck } from "./shared/update-check";
import { nodeBinCommand } from "./shared/node-bin";
import { serveDirectory } from "./shared/static-server";
import { serveViewer } from "./serve";
@@ -95,6 +96,9 @@ Usage:
visualice serve [opts] Launch the zoomable results viewer
visualice --version Print the version
+An installed CLI says on stderr when a newer version is out (checked at most daily);
+VISUALICE_NO_UPDATE_CHECK=1, --quiet or CI turns that off.
+
Project files: visualice.config.json controls behavior; visualice.routes.md lists
pages + UI states and is regenerated after every crawl (edit it: 'skip:' excludes,
'[ ]' requests a state). A visualice.config.* in the cwd is picked up automatically.
@@ -1014,6 +1018,34 @@ async function main(): Promise {
}
const flags = parseFlags(cmd, rest);
setHeaded(flags.headed === true);
+ const update = await updateCheck(flags);
+ if (update?.notice) console.error(`ℹ ${update.notice}`);
+ try {
+ await runCommand(cmd, flags);
+ } finally {
+ // Let a background registry lookup save its answer, but never hold a finished
+ // command up for long: an unanswered lookup is simply tried again next time.
+ if (update) await Promise.race([update.refreshed, delay(1500)]);
+ }
+}
+
+/**
+ * The update check, for an installed CLI. A source checkout (this repo, or one
+ * `npm link`ed) is never "behind" in a way worth telling, and `--quiet` asks for silence.
+ */
+async function updateCheck(flags: Flags): Promise {
+ if (flags.quiet === true || updateCheckDisabled()) return undefined;
+ if (await pathExists(path.join(PROJECT_ROOT, ".git"))) return undefined;
+ try {
+ return await startUpdateCheck(await readVersion());
+ } catch {
+ return undefined;
+ }
+}
+
+const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms).unref());
+
+async function runCommand(cmd: string, flags: Flags): Promise {
switch (cmd) {
case "init":
return cmdInit(flags);
diff --git a/src/shared/update-check.ts b/src/shared/update-check.ts
new file mode 100644
index 0000000..909699b
--- /dev/null
+++ b/src/shared/update-check.ts
@@ -0,0 +1,122 @@
+import os from "node:os";
+import path from "node:path";
+import { promises as fs } from "node:fs";
+
+// "A newer visualice is out" notice. A plugin install doesn't auto-update by default,
+// and the plugin's skill pins the CLI version it runs, so without this a user only
+// learns about a release by going to look. The check is cheap and never in the way:
+// the notice comes from a cached answer, the registry is asked at most once a day,
+// and a slow or failed lookup is dropped without a word.
+
+const REGISTRY_URL = "https://registry.npmjs.org/visualice/latest";
+const DAY_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 2000;
+
+interface Cache {
+ checkedAt: number;
+ latest?: string;
+}
+
+/** Where the last answer is kept: the user's cache folder, outside any project. */
+export function cacheFile(env: NodeJS.ProcessEnv = process.env): string {
+ const base =
+ env.XDG_CACHE_HOME ||
+ (process.platform === "win32" && env.LOCALAPPDATA) ||
+ path.join(os.homedir(), ".cache");
+ return path.join(base, "visualice", "update-check.json");
+}
+
+/** Is the check switched off here: opted out, CI, or a test run? */
+export function updateCheckDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
+ return !!(
+ env.VISUALICE_NO_UPDATE_CHECK ||
+ env.NO_UPDATE_NOTIFIER ||
+ env.CI ||
+ env.VITEST ||
+ env.NODE_ENV === "test"
+ );
+}
+
+/** `a` > `b` for plain x.y.z versions; a prerelease is never "newer". */
+export function isNewer(a: string, b: string): boolean {
+ const parse = (v: string) => {
+ const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
+ return m ? m.slice(1).map(Number) : undefined;
+ };
+ const x = parse(a);
+ const y = parse(b);
+ if (!x || !y) return false;
+ for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i];
+ return false;
+}
+
+/** The notice for a user on `current` when `latest` is out. */
+export function updateNotice(current: string, latest: string): string {
+ return (
+ `visualice ${latest} is available (you have ${current}). Update the plugin: ` +
+ `claude plugin update visualice@visualice — or the CLI: npm i -g visualice@latest`
+ );
+}
+
+async function readCache(file: string): Promise {
+ try {
+ const c = JSON.parse(await fs.readFile(file, "utf8")) as Cache;
+ return typeof c.checkedAt === "number" ? c : undefined;
+ } catch {
+ return undefined;
+ }
+}
+
+export interface UpdateCheck {
+ /** The notice to show now, from the cached answer; undefined when up to date. */
+ notice?: string;
+ /** Settles once a stale cache has been refreshed (never rejects). */
+ refreshed: Promise;
+}
+
+/**
+ * Start an update check for `current`. The notice comes from the last answer at
+ * once; when that answer is a day old, the registry is asked again in the background
+ * and the next run shows what it said.
+ */
+export async function startUpdateCheck(
+ current: string,
+ opts: { file?: string; now?: number; fetchFn?: typeof fetch } = {},
+): Promise {
+ const file = opts.file ?? cacheFile();
+ const now = opts.now ?? Date.now();
+ const cache = await readCache(file);
+ const notice =
+ cache?.latest && isNewer(cache.latest, current)
+ ? updateNotice(current, cache.latest)
+ : undefined;
+ if (cache && now - cache.checkedAt < DAY_MS) return { notice, refreshed: Promise.resolve() };
+ return { notice, refreshed: refresh(file, now, opts.fetchFn ?? fetch, cache) };
+}
+
+async function refresh(
+ file: string,
+ now: number,
+ fetchFn: typeof fetch,
+ previous: Cache | undefined,
+): Promise {
+ let latest = previous?.latest;
+ try {
+ const res = await fetchFn(REGISTRY_URL, {
+ headers: { accept: "application/json" },
+ signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+ });
+ if (res.ok) {
+ const body = (await res.json()) as { version?: unknown };
+ if (typeof body.version === "string") latest = body.version;
+ }
+ } catch {
+ // offline, blocked or slow: try again tomorrow
+ }
+ try {
+ await fs.mkdir(path.dirname(file), { recursive: true });
+ await fs.writeFile(file, JSON.stringify({ checkedAt: now, latest } satisfies Cache));
+ } catch {
+ // a read-only home: the check just runs again next time
+ }
+}
diff --git a/tests/update-check.test.ts b/tests/update-check.test.ts
new file mode 100644
index 0000000..ce2707a
--- /dev/null
+++ b/tests/update-check.test.ts
@@ -0,0 +1,112 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+ cacheFile,
+ isNewer,
+ startUpdateCheck,
+ updateCheckDisabled,
+ updateNotice,
+} from "../src/shared/update-check";
+
+const DAY = 24 * 60 * 60 * 1000;
+
+/** A fetch that answers with `version`, and counts its calls. */
+function registry(version: string | Error) {
+ const calls: string[] = [];
+ const fn = (async (url: string) => {
+ calls.push(url);
+ if (version instanceof Error) throw version;
+ return new Response(JSON.stringify({ version }), { status: 200 });
+ }) as unknown as typeof fetch;
+ return { fn, calls };
+}
+
+describe("versions", () => {
+ it("compares plain x.y.z versions", () => {
+ expect(isNewer("0.2.0", "0.1.1")).toBe(true);
+ expect(isNewer("0.10.0", "0.9.9")).toBe(true);
+ expect(isNewer("1.0.0", "1.0.0")).toBe(false);
+ expect(isNewer("0.1.0", "0.1.1")).toBe(false);
+ expect(isNewer("0.3.0-beta.1", "0.2.0")).toBe(false);
+ expect(isNewer("nonsense", "0.2.0")).toBe(false);
+ });
+
+ it("names both update commands", () => {
+ const n = updateNotice("0.2.0", "0.3.0");
+ expect(n).toContain("visualice 0.3.0 is available (you have 0.2.0)");
+ expect(n).toContain("claude plugin update visualice@visualice");
+ expect(n).toContain("npm i -g visualice@latest");
+ });
+});
+
+describe("when it runs", () => {
+ it("is off when opted out, in CI and in tests", () => {
+ expect(updateCheckDisabled({})).toBe(false);
+ expect(updateCheckDisabled({ VISUALICE_NO_UPDATE_CHECK: "1" })).toBe(true);
+ expect(updateCheckDisabled({ NO_UPDATE_NOTIFIER: "1" })).toBe(true);
+ expect(updateCheckDisabled({ CI: "true" })).toBe(true);
+ });
+
+ it("caches under XDG_CACHE_HOME when set", () => {
+ expect(cacheFile({ XDG_CACHE_HOME: "/c" })).toBe(
+ path.join("/c", "visualice", "update-check.json"),
+ );
+ });
+});
+
+describe("startUpdateCheck", () => {
+ let dir: string;
+ let file: string;
+ beforeEach(async () => {
+ dir = await fs.mkdtemp(path.join(os.tmpdir(), "vc-update-"));
+ file = path.join(dir, "nested", "update-check.json");
+ });
+ afterEach(() => fs.rm(dir, { recursive: true, force: true }));
+
+ it("says nothing on the first run, asks the registry, and tells the next run", async () => {
+ const reg = registry("0.3.0");
+ const first = await startUpdateCheck("0.2.0", { file, now: 1000, fetchFn: reg.fn });
+ expect(first.notice).toBeUndefined();
+ await first.refreshed;
+ expect(reg.calls).toEqual(["https://registry.npmjs.org/visualice/latest"]);
+
+ const next = await startUpdateCheck("0.2.0", { file, now: 2000, fetchFn: reg.fn });
+ expect(next.notice).toContain("0.3.0 is available");
+ await next.refreshed;
+ expect(reg.calls).toHaveLength(1); // a fresh answer isn't asked for again
+ });
+
+ it("asks again once the answer is a day old, and says nothing when up to date", async () => {
+ await fs.mkdir(path.dirname(file), { recursive: true });
+ await fs.writeFile(file, JSON.stringify({ checkedAt: 0, latest: "0.2.0" }));
+ const reg = registry("0.2.0");
+ const check = await startUpdateCheck("0.2.0", { file, now: DAY + 1, fetchFn: reg.fn });
+ expect(check.notice).toBeUndefined();
+ await check.refreshed;
+ expect(reg.calls).toHaveLength(1);
+ });
+
+ it("keeps the last answer when the registry can't be reached", async () => {
+ await fs.mkdir(path.dirname(file), { recursive: true });
+ await fs.writeFile(file, JSON.stringify({ checkedAt: 0, latest: "0.3.0" }));
+ const check = await startUpdateCheck("0.2.0", {
+ file,
+ now: DAY + 1,
+ fetchFn: registry(new Error("offline")).fn,
+ });
+ expect(check.notice).toContain("0.3.0");
+ await expect(check.refreshed).resolves.toBeUndefined();
+ const saved = JSON.parse(await fs.readFile(file, "utf8"));
+ expect(saved).toEqual({ checkedAt: DAY + 1, latest: "0.3.0" });
+ });
+
+ it("ignores a cache it can't read", async () => {
+ await fs.mkdir(path.dirname(file), { recursive: true });
+ await fs.writeFile(file, "{not json");
+ const check = await startUpdateCheck("0.2.0", { file, now: 1, fetchFn: registry("0.2.0").fn });
+ expect(check.notice).toBeUndefined();
+ await check.refreshed;
+ });
+});
From 32b0b1f509d0f6ce29c10b29f90f204e6f29f60f Mon Sep 17 00:00:00 2001
From: Alexander Tenepere
Date: Tue, 10 Nov 2026 14:23:24 +0800
Subject: [PATCH 4/8] chore: End-to-end test of the update loop through the CLI
in a git repository
---
tests/integration/update-flow.test.ts | 157 ++++++++++++++++++++++++++
1 file changed, 157 insertions(+)
create mode 100644 tests/integration/update-flow.test.ts
diff --git a/tests/integration/update-flow.test.ts b/tests/integration/update-flow.test.ts
new file mode 100644
index 0000000..e88f412
--- /dev/null
+++ b/tests/integration/update-flow.test.ts
@@ -0,0 +1,157 @@
+import { describe, expect, it, beforeAll, afterAll } from "vitest";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { serveDirectory } from "../../src/shared/static-server";
+import type { StaticServer } from "../../src/shared/file-serve";
+import type { ChangesReport } from "../../src/crawl/changes";
+import type { Manifest } from "../../src/shared/types";
+import { FIXTURE_DIR, tempDir } from "./helpers";
+
+const exec = promisify(execFile);
+
+const REPO = path.resolve(import.meta.dirname, "..", "..");
+const BIN = path.join(REPO, "cli", "visualice.mjs");
+
+/**
+ * The update loop end to end, through the real CLI in a real git repository, the
+ * way a project uses it: a full crawl records the commit it shot; `changes` reads
+ * that record back out of the routes file and diffs against it; the partial crawl
+ * it suggests shoots the changed pages and carries the rest; and a change that
+ * reaches every page asks for a full run. The unit tests cover each piece; this
+ * covers the hand-offs between them (routes-file line, run manifests, the CLI).
+ */
+
+let site: string;
+let server: StaticServer;
+
+const env = { ...process.env, NO_COLOR: "1", VISUALICE_NO_UPDATE_CHECK: "1" };
+
+const git = async (...args: string[]) =>
+ (await exec("git", args, { cwd: site, env })).stdout.trim();
+
+const visualice = async (...args: string[]) =>
+ (await exec(process.execPath, [BIN, ...args], { cwd: site, env, maxBuffer: 1 << 26 })).stdout;
+
+const changes = async (): Promise =>
+ JSON.parse(await visualice("changes", "--json", "--quiet")) as ChangesReport;
+
+const commit = async (message: string) => {
+ await git("add", "-A");
+ await git("commit", "-q", "-m", message);
+};
+
+const sourceLine = async () =>
+ /visualice-source commit=([0-9a-f]+)/.exec(
+ await fs.readFile(path.join(site, "visualice.routes.md"), "utf8"),
+ )?.[1];
+
+beforeAll(async () => {
+ site = await tempDir("update-flow");
+ await fs.cp(FIXTURE_DIR, site, { recursive: true });
+ await fs.rm(path.join(site, "crawl-map.input.json"), { force: true });
+ await fs.writeFile(path.join(site, ".gitignore"), ".visualice/\n");
+ // Small and quick: one device, few interactions. The site is the repository.
+ await fs.writeFile(
+ path.join(site, "visualice.config.json"),
+ JSON.stringify(
+ {
+ scope: { maxPages: 6, maxDepth: 1 },
+ devices: [{ name: "small", width: 420, height: 640, dpr: 1 }],
+ discovery: { interactions: { maxPerPage: 1 }, mobileStates: false },
+ stabilize: { extraDelayMs: 50 },
+ politeness: { minDelayMs: 0, concurrency: 4 },
+ },
+ null,
+ 2,
+ ),
+ );
+ await git("init", "-q");
+ // A Windows runner converts line endings by default, which would make every
+ // checked-out file look modified.
+ await git("config", "core.autocrlf", "false");
+ await git("config", "user.email", "test@example.com");
+ await git("config", "user.name", "test");
+ await commit("site");
+ server = await serveDirectory(site);
+}, 60000);
+
+afterAll(async () => {
+ await server?.close();
+ if (site) await fs.rm(site, { recursive: true, force: true });
+});
+
+describe("updating a catalogue after code changes", () => {
+ it("records, diffs, reruns only what changed, and asks for everything when it should", async () => {
+ // 1. A full crawl records the commit it shot in the routes file.
+ const first = JSON.parse(await visualice("crawl", server.url, "--json", "--quiet"));
+ expect(first.shots).toBeGreaterThan(0);
+ expect(first.failed).toBe(0);
+ expect(await sourceLine()).toBe(await git("rev-parse", "HEAD"));
+ const firstManifest = JSON.parse(await fs.readFile(first.manifest, "utf8")) as Manifest;
+ const pages = firstManifest.routes.map((r) => r.url);
+ expect(pages).toContain("/about");
+
+ // 2. Committing the catalogue changes nothing that counts.
+ await commit("catalogue");
+ expect((await changes()).verdict).toBe("none");
+
+ // 3. One page edited, one added: partial, with exactly those pages.
+ const about = path.join(site, "about.html");
+ const before = await fs.readFile(about, "utf8");
+ const edited = before.replace("
+ {short((tile.carried ? tile.carried.commit : data.source?.commit)!)}
+
+
+ )}
+
{position && (
Shot {position.index} of {position.total}
diff --git a/viewer/src/load.ts b/viewer/src/load.ts
index 4b486b0..cbce670 100644
--- a/viewer/src/load.ts
+++ b/viewer/src/load.ts
@@ -65,6 +65,39 @@ function parseTile(raw: unknown, i: number): ViewerTile {
meta: isString(raw.meta) ? raw.meta : undefined,
a11y: typeof raw.a11y === "number" ? raw.a11y : undefined,
error: isString(raw.error) ? raw.error : undefined,
+ carried: parseCarried(raw.carried),
+ updated: raw.updated === true || undefined,
+ };
+}
+
+/** Where a carried-over shot was really taken; dropped unless it names a run. */
+function parseCarried(raw: unknown): ViewerTile["carried"] {
+ if (!isObject(raw) || !isString(raw.runId)) return undefined;
+ return {
+ runId: raw.runId,
+ commit: isString(raw.commit) ? raw.commit : undefined,
+ capturedAt: isString(raw.capturedAt) ? raw.capturedAt : undefined,
+ };
+}
+
+/** The commit a run was shot from, when it recorded one. */
+function parseSource(raw: unknown): ViewerData["source"] {
+ if (!isObject(raw) || !isString(raw.commit)) return undefined;
+ return {
+ commit: raw.commit,
+ branch: isString(raw.branch) ? raw.branch : undefined,
+ dirty: typeof raw.dirty === "number" ? raw.dirty : 0,
+ capturedAt: isString(raw.capturedAt) ? raw.capturedAt : "",
+ target: isString(raw.target) ? raw.target : undefined,
+ local: typeof raw.local === "boolean" ? raw.local : undefined,
+ };
+}
+
+function parsePartial(raw: unknown): ViewerData["partial"] {
+ if (!isObject(raw) || !Array.isArray(raw.only)) return undefined;
+ return {
+ only: raw.only.filter(isString),
+ carriedFrom: isString(raw.carriedFrom) ? raw.carriedFrom : undefined,
};
}
@@ -110,6 +143,8 @@ export function parseViewerData(raw: unknown): ViewerData {
runId: isString(site.runId) ? site.runId : "unknown",
generatedAt: isString(site.generatedAt) ? site.generatedAt : "",
},
+ source: parseSource(raw.source),
+ partial: parsePartial(raw.partial),
devices,
tiles,
groups,
From 8a2607bbbebc585d1afbf349587c9bcf9166c26b Mon Sep 17 00:00:00 2001
From: Alexander Tenepere