pagetrace 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 While the version is below 1.0.0, breaking changes ship in a minor release.
 
+## [0.9.0] - 2026-09-07
+
+### Added
+
+- `pagetrace update` asks the npm registry whether a newer version is published
+  and installs it. `--check` reports without installing. A project-local install
+  is not overwritten with a global one; the command prints the package-manager
+  command instead, because installing globally would leave the version the
+  project actually runs untouched.
+
+### Fixed
+
+- A bare `pagetrace`, or a misspelled command, printed nothing and exited 0,
+  which reads as a silent success. Both now print the command list, and an
+  unknown command exits 2.
+
+## [0.8.1] - 2026-09-06
+
+### Fixed
+
+- The report summary said "1 findings across 13 pages". Both counts are now
+  pluralised properly.
+
 ## [0.8.0] - 2026-09-06
 
 ### Fixed
@@ -249,6 +272,7 @@ Initial release. `snapshot`, `check` and `audit` commands; filesystem and HTTP
 crawling; diff classified by transition; absolute, cross-page and hreflang audit
 rules; pretty, JSON, markdown, GitHub and HTML reporters.
 
+[0.8.1]: https://github.com/shyamexe/pagetrace/compare/v0.8.0...v0.8.1
 [0.8.0]: https://github.com/shyamexe/pagetrace/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/shyamexe/pagetrace/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/shyamexe/pagetrace/compare/v0.5.0...v0.6.0

package/README.md

@@ -115,6 +115,18 @@ Routes are discovered from `robots.txt` sitemap declarations, falling back to `/
 
 URLs pointing at another host are skipped. A page that cannot be fetched stops the run with an error rather than being dropped from the snapshot — a page silently missing from a crawl is indistinguishable from a page you deleted, and reporting a transient outage as a site-wide deletion is worse than failing.
 
+### Version and updates
+
+```bash
+pagetrace                     # command list (same as --help)
+pagetrace <command> --help    # flags for one command
+pagetrace --version           # installed version
+pagetrace update --check      # ask npm whether a newer one exists
+pagetrace update              # install it globally
+```
+
+`update` refuses to install globally over a project-local copy and prints the package-manager command instead. Unrelated to `check --update`, which rewrites the lockfile.
+
 ## What it records
 
 **Per page** — title, meta description, canonical, robots directives, Open Graph and Twitter Card tags, hreflang alternates, `h1` text, heading outline, every JSON-LD entity with its property list, word count, images missing `alt`, and the length of the first quotable paragraph.

package/dist/cli.cjs

@@ -24,6 +24,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/cli.ts
+var import_node_child_process2 = require("child_process");
 var import_promises2 = require("fs/promises");
 var import_cac = require("cac");
 var import_picocolors2 = __toESM(require("picocolors"), 1);
@@ -1030,9 +1031,10 @@ function formatAuditPretty(groups, meta, columns = 80) {
   const counted = ["error", "warn", "info"].filter((s) => issues[s] > 0).map((s) => BADGE[s](`${issues[s]} ${issues[s] === 1 ? SINGULAR[s] : PLURAL[s]}`)).join(import_picocolors.default.dim(" \xB7 "));
   lines.push(import_picocolors.default.dim("\u2500".repeat(width)));
   lines.push(`${import_picocolors.default.bold(`${total} issue${total === 1 ? "" : "s"}`)}  ${counted}`);
+  const found = instances.error + instances.warn + instances.info;
   lines.push(
     import_picocolors.default.dim(
-      `${instances.error + instances.warn + instances.info} findings across ${meta.pageCount} pages`
+      `${found} finding${found === 1 ? "" : "s"} across ${meta.pageCount} page${meta.pageCount === 1 ? "" : "s"}`
     )
   );
   lines.push("");
@@ -1515,6 +1517,27 @@ async function snapshotFromOrigin(origin, options = {}) {
   return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
 }
 
+// src/update.ts
+var REGISTRY = "https://registry.npmjs.org";
+function isNewer(latest, current) {
+  const parts = (v) => v.trim().replace(/^v/, "").split(/[-+]/)[0].split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const [a, b] = [parts(latest), parts(current)];
+  for (let i = 0; i < 3; i += 1) {
+    if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0);
+  }
+  return false;
+}
+async function latestVersion(name, timeoutMs = 5e3) {
+  const response = await fetch(`${REGISTRY}/${name}/latest`, {
+    headers: { accept: "application/json" },
+    signal: AbortSignal.timeout(timeoutMs)
+  });
+  if (!response.ok) throw new Error(`npm registry answered ${response.status} for ${name}.`);
+  const body = await response.json();
+  if (!body.version) throw new Error(`npm registry returned no version for ${name}.`);
+  return body.version;
+}
+
 // src/cli.ts
 var DEFAULT_LOCKFILE = "pagetrace.lock.json";
 var DEFAULT_CONFIG = "pagetrace.config.json";
@@ -1644,11 +1667,44 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
     process.exitCode = EXIT_FINDINGS;
   }
 });
+cli.command("update", "Check npm for a newer pagetrace and install it").option("--check", "Only report whether an update exists").action(async (flags) => {
+  const latest = await latestVersion("pagetrace");
+  if (!isNewer(latest, "0.9.0")) {
+    console.log(import_picocolors2.default.green(`pagetrace ${"0.9.0"} is the latest version.`));
+    return;
+  }
+  console.log(import_picocolors2.default.yellow(`Update available: ${"0.9.0"} \u2192 ${latest}`));
+  if (flags.check) return;
+  if (process.argv[1]?.startsWith(process.cwd())) {
+    console.log(
+      import_picocolors2.default.dim("This is a project-local install. Update it with your package manager, e.g.")
+    );
+    console.log(`  npm install -D pagetrace@${latest}`);
+    return;
+  }
+  const { status, error } = (0, import_node_child_process2.spawnSync)("npm", ["install", "-g", `pagetrace@${latest}`], {
+    stdio: "inherit"
+  });
+  if (error || status !== 0) {
+    throw new Error(`npm install failed. Run \`npm install -g pagetrace@${latest}\` yourself.`);
+  }
+  console.log(import_picocolors2.default.green(`Updated to pagetrace ${latest}.`));
+});
 cli.help();
-cli.version("0.8.0");
+cli.version("0.9.0");
 async function main() {
   try {
     cli.parse(process.argv, { run: false });
+    if (!cli.matchedCommand) {
+      if (cli.options.help || cli.options.version) return;
+      cli.outputHelp();
+      if (cli.args[0]) {
+        console.error(import_picocolors2.default.red(`
+Unknown command "${cli.args[0]}".`));
+        process.exitCode = EXIT_FAILURE;
+      }
+      return;
+    }
     await cli.runMatchedCommand();
   } catch (error) {
     console.error(import_picocolors2.default.red(error.message));

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { spawnSync } from "child_process";
 import { readFile as readFile2, writeFile } from "fs/promises";
 import { cac } from "cac";
 import pc2 from "picocolors";
@@ -1007,9 +1008,10 @@ function formatAuditPretty(groups, meta, columns = 80) {
   const counted = ["error", "warn", "info"].filter((s) => issues[s] > 0).map((s) => BADGE[s](`${issues[s]} ${issues[s] === 1 ? SINGULAR[s] : PLURAL[s]}`)).join(pc.dim(" \xB7 "));
   lines.push(pc.dim("\u2500".repeat(width)));
   lines.push(`${pc.bold(`${total} issue${total === 1 ? "" : "s"}`)}  ${counted}`);
+  const found = instances.error + instances.warn + instances.info;
   lines.push(
     pc.dim(
-      `${instances.error + instances.warn + instances.info} findings across ${meta.pageCount} pages`
+      `${found} finding${found === 1 ? "" : "s"} across ${meta.pageCount} page${meta.pageCount === 1 ? "" : "s"}`
     )
   );
   lines.push("");
@@ -1492,6 +1494,27 @@ async function snapshotFromOrigin(origin, options = {}) {
   return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
 }
 
+// src/update.ts
+var REGISTRY = "https://registry.npmjs.org";
+function isNewer(latest, current) {
+  const parts = (v) => v.trim().replace(/^v/, "").split(/[-+]/)[0].split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const [a, b] = [parts(latest), parts(current)];
+  for (let i = 0; i < 3; i += 1) {
+    if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0);
+  }
+  return false;
+}
+async function latestVersion(name, timeoutMs = 5e3) {
+  const response = await fetch(`${REGISTRY}/${name}/latest`, {
+    headers: { accept: "application/json" },
+    signal: AbortSignal.timeout(timeoutMs)
+  });
+  if (!response.ok) throw new Error(`npm registry answered ${response.status} for ${name}.`);
+  const body = await response.json();
+  if (!body.version) throw new Error(`npm registry returned no version for ${name}.`);
+  return body.version;
+}
+
 // src/cli.ts
 var DEFAULT_LOCKFILE = "pagetrace.lock.json";
 var DEFAULT_CONFIG = "pagetrace.config.json";
@@ -1621,11 +1644,44 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
     process.exitCode = EXIT_FINDINGS;
   }
 });
+cli.command("update", "Check npm for a newer pagetrace and install it").option("--check", "Only report whether an update exists").action(async (flags) => {
+  const latest = await latestVersion("pagetrace");
+  if (!isNewer(latest, "0.9.0")) {
+    console.log(pc2.green(`pagetrace ${"0.9.0"} is the latest version.`));
+    return;
+  }
+  console.log(pc2.yellow(`Update available: ${"0.9.0"} \u2192 ${latest}`));
+  if (flags.check) return;
+  if (process.argv[1]?.startsWith(process.cwd())) {
+    console.log(
+      pc2.dim("This is a project-local install. Update it with your package manager, e.g.")
+    );
+    console.log(`  npm install -D pagetrace@${latest}`);
+    return;
+  }
+  const { status, error } = spawnSync("npm", ["install", "-g", `pagetrace@${latest}`], {
+    stdio: "inherit"
+  });
+  if (error || status !== 0) {
+    throw new Error(`npm install failed. Run \`npm install -g pagetrace@${latest}\` yourself.`);
+  }
+  console.log(pc2.green(`Updated to pagetrace ${latest}.`));
+});
 cli.help();
-cli.version("0.8.0");
+cli.version("0.9.0");
 async function main() {
   try {
     cli.parse(process.argv, { run: false });
+    if (!cli.matchedCommand) {
+      if (cli.options.help || cli.options.version) return;
+      cli.outputHelp();
+      if (cli.args[0]) {
+        console.error(pc2.red(`
+Unknown command "${cli.args[0]}".`));
+        process.exitCode = EXIT_FAILURE;
+      }
+      return;
+    }
     await cli.runMatchedCommand();
   } catch (error) {
     console.error(pc2.red(error.message));

package/dist/index.cjs

@@ -1275,9 +1275,10 @@ function formatAuditPretty(groups, meta, columns = 80) {
   const counted = ["error", "warn", "info"].filter((s) => issues[s] > 0).map((s) => BADGE[s](`${issues[s]} ${issues[s] === 1 ? SINGULAR[s] : PLURAL[s]}`)).join(import_picocolors.default.dim(" \xB7 "));
   lines.push(import_picocolors.default.dim("\u2500".repeat(width)));
   lines.push(`${import_picocolors.default.bold(`${total} issue${total === 1 ? "" : "s"}`)}  ${counted}`);
+  const found = instances.error + instances.warn + instances.info;
   lines.push(
     import_picocolors.default.dim(
-      `${instances.error + instances.warn + instances.info} findings across ${meta.pageCount} pages`
+      `${found} finding${found === 1 ? "" : "s"} across ${meta.pageCount} page${meta.pageCount === 1 ? "" : "s"}`
     )
   );
   lines.push("");

package/dist/index.js

@@ -1204,9 +1204,10 @@ function formatAuditPretty(groups, meta, columns = 80) {
   const counted = ["error", "warn", "info"].filter((s) => issues[s] > 0).map((s) => BADGE[s](`${issues[s]} ${issues[s] === 1 ? SINGULAR[s] : PLURAL[s]}`)).join(pc.dim(" \xB7 "));
   lines.push(pc.dim("\u2500".repeat(width)));
   lines.push(`${pc.bold(`${total} issue${total === 1 ? "" : "s"}`)}  ${counted}`);
+  const found = instances.error + instances.warn + instances.info;
   lines.push(
     pc.dim(
-      `${instances.error + instances.warn + instances.info} findings across ${meta.pageCount} pages`
+      `${found} finding${found === 1 ? "" : "s"} across ${meta.pageCount} page${meta.pageCount === 1 ? "" : "s"}`
     )
   );
   lines.push("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pagetrace",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Baseline your site's SEO and AEO surface, diff every build against it, and fail CI on regressions.",
   "main": "./dist/index.cjs",
   "scripts": {