@finbheara/archive-client 0.20.2 → 0.22.0

package/README.md

@@ -139,13 +139,23 @@ m.unpin();
 await m.add("<dir>", "archive-YYYY.MM.DD-N");  // a release built locally, under its own tag
 await m.index("pinned");                  // build every index
 m.prune({ keep: 2, dryRun: true });       // the plan: what would go, and its bytes
+await m.use("latest");                    // fetch, index, pin, then prune to the newest 2
 m.remove("<tag>");                        // refuses the pinned release
 m.dropIndexes();                          // the index files only
 await m.verify("<tag>");                  // re-hash every cached file against its receipt
 ```
 
 Every removal answers its plan first (`dryRun`), keeps the pinned release, and touches nothing
-outside the cache root.
+outside the cache root. A release's indexes live under its directory and go with it.
+
+THE CACHE KEEPS ITSELF. A release is gigabytes, so a `use` (and so an `update`) that lands its
+release prunes the cache once the pin has moved: it keeps the newest `keep` releases by tag (date,
+cut, fraction), the new pin, and the pin before it, so a reader still on the previous release is
+not cut off. A release fetched with `--release` and never pinned counts like any other. `keep` is
+the call's own (`--keep N`, `use(spec, { keep })`), else the user-local `config keep <N>`, else
+`DEFAULT_KEEP` (2), and a plain `prune` reads the same count. `--no-prune` (`prune: false`) skips
+it, and a fetch or index that fails prunes nothing. The answer carries the plan (`pruned`), and
+the command line prints one line per release removed and the MB freed.
 
 ## The indexes
 
@@ -707,8 +717,11 @@ is passed to the dancer resolver as asked (`rel.dancers`, above).
 ## The command line
 
     idq config repo <owner/name>
+    idq config keep <N>
     idq list [--remote]
     idq fetch [--release <spec>] [--assets results,majors,<file>...]
+    idq update [--assets results,majors,<file>...] [--keep N] [--no-prune]
+    idq use <spec> [--assets results,majors,<file>...] [--keep N] [--no-prune]
     idq pin <spec> | unpin | current
     idq add <dir> --tag <tag>
     idq index [--release <spec>] [<name>...] [--force]
@@ -748,6 +761,25 @@ is passed to the dancer resolver as asked (`rel.dancers`, above).
 `stream` prints one JSON line per row (or entry), as it reads them. `dancer` prints the results of the one dancer where the answer is unique (every candidate's with
 `--rows`). `--json` prints the call's answer as it is. `--cache` and `--repo` override the defaults.
 
+`update` moves to the newest published release, as a package manager's `update` moves to the newest
+version: it fetches it (verified as every download is), builds every index it knows, and only then
+pins it, so a fetch or index that fails leaves the old pin in force, and then prunes the cache to
+the newest releases (above: the pin and the one before it always stay). `use <spec>` does the same for
+the release a spec names, older or newer (`releases().use(spec)` in the API; `update` is
+`use("latest")`).
+
+A query on the default spec (`pinned`, given or not) whose release is older than the newest
+published one prints ONE line on stderr, and changes neither the answer nor the exit code:
+
+    answered from <tag>. <newer tag> is available: run `idq update` to get the latest
+
+The remote is asked at most once per hour: what it said and when are kept in `<cache>/LATEST.json`,
+and a call inside the hour reads that file. An offline, failed or slow check says nothing, and a
+call waits for one at most 1.5 s, while its own query runs. A release named with `--release` (a
+tag, a cut, `latest`) is never warned about: it was asked for. `main(argv, { freshness })` takes
+`false` to turn the check off, or a `floor` (a cut the caller requires, and why: where only the
+floor is newer, the line says the cut is required, with the why, and to run `idq use <cut>`), the `command` the warning names and the clock.
+
 `resolve` speaks JSON lines: one answer per line out, and with no positional question the
 questions are JSON lines on stdin, one per line (`{feis, code, year?, title?}`,
 `{name, school?, age?, population?, oireachtas?}`,

package/dist/chunks/{index-6028k52f.js → index-zwecpq08.js}

@@ -3741,6 +3741,12 @@ function openCached2(tag, opts = {}) {
   return new Release2(tag, root, JSON.parse(readFileSync3(p, "utf8")), opts);
 }
 
+var DEFAULT_KEEP2 = 2;
+function checkKeep(keep) {
+  if (!Number.isInteger(keep) || keep < 0)
+    throw new Error(`prune: --keep ${keep} is not a count`);
+  return keep;
+}
 function duBytes(p) {
   if (!existsSync5(p))
     return 0;
@@ -3800,6 +3806,26 @@ class ReleaseManager2 {
     writePin(this.root, pin);
     return pin;
   }
+  async use(spec, o = {}) {
+    const keep = o.prune === false ? null : this.keepCount(o.keep);
+    const was = readPin2(this.root)?.tag ?? null;
+    const rel = await this.fetch(spec, o);
+    const tag = rel.tag;
+    rel.close();
+    const { built } = await this.index(tag);
+    const pin = await this.pin(tag);
+    if (keep === null)
+      return { tag, was, pin, built, pruned: null };
+    try {
+      const hold = was === null || was === tag ? [] : [{ tag: was, why: "the pin before this one" }];
+      return { tag, was, pin, built, pruned: this.prune({ keep, hold }) };
+    } catch (e) {
+      return { tag, was, pin, built, pruned: null, pruneError: e.message };
+    }
+  }
+  keepCount(keep) {
+    return checkKeep(keep ?? readConfig2(this.root).keep ?? DEFAULT_KEEP2);
+  }
   unpin() {
     return clearPin(this.root);
   }
@@ -3810,6 +3836,8 @@ class ReleaseManager2 {
   config(patch) {
     if (patch.repo !== undefined)
       repoOf2({ ...this.opts, repo: patch.repo });
+    if (patch.keep !== undefined)
+      checkKeep(patch.keep);
     return writeConfig2(this.root, patch);
   }
   readConfig() {
@@ -3887,16 +3915,17 @@ class ReleaseManager2 {
     return p;
   }
   prune(o = {}) {
-    const keep = o.keep ?? 1;
-    if (!Number.isInteger(keep) || keep < 0)
-      throw new Error(`prune: --keep ${keep} is not a count`);
+    const keep = this.keepCount(o.keep);
     const pin = readPin2(this.root);
     const p = this.plan(o.dryRun ?? false);
     this.cachedTags().forEach((tag, i) => {
+      const held = (o.hold ?? []).filter((h) => h.tag === tag).map((h) => h.why);
       if (tag === pin?.tag)
         p.keep.push({ tag, why: "pinned" });
       else if (i < keep)
         p.keep.push({ tag, why: `among the ${keep} newest` });
+      else if (held.length > 0)
+        p.keep.push({ tag, why: [...new Set(held)].join("; ") });
       else
         this.planRemove(p, tagDir(this.root, tag), `older than the ${keep} newest`);
     });
@@ -3937,4 +3966,93 @@ function releases2(opts = {}) {
   return new ReleaseManager2(opts);
 }
 
-export { DATABASES2, planAsset2, sha256File2, unzstdTo2, NAME_LEVELS2, nameLevel2, NO_CALENDAR2, FeisFinder2, ADVANCEMENT_DANCES2, entryRank2, FEIS_LOCAL_ID_FLOOR2, ResultFinder2, MajorsFinder2, LINEAGE_FILE2, linksOfLineage2, releaseSchoolGraph2, readsSpanishNames2, SchoolResolver2, initialsOnly2, nameOrderOf, DancerResolver2, readPopulation2, syllabusSourceOf2, canonicalOf2, CompResolver2, StaffFinder2, TeamFinder2, EventFinder2, defaultBuilders2, indexPath2, indexKey2, isCurrent2, buildIndex2, ensureIndex2, listIndexes2, readPin2, youngest2, dancerResolverOf2, RegistrationResolver2, ghRemote2, httpsRemote2, fallbackRemote2, setRemote2, columnsOf2, FEATURES2, capabilityOf2, needsRelease2, resolveTag2, Release2, openRelease2, openCached2, ReleaseManager2, releases2 };
+import { existsSync as existsSync6, readFileSync as readFileSync5 } from "fs";
+import { join as join5 } from "path";
+var LATEST_CHECK_MS2 = 60 * 60 * 1000;
+var LATEST_CHECK_BUDGET_MS2 = 1500;
+var latestCheckPath2 = (root) => join5(root, "LATEST.json");
+function readLatestCheck2(root) {
+  const p = latestCheckPath2(root);
+  if (!existsSync6(p))
+    return null;
+  try {
+    const v = JSON.parse(readFileSync5(p, "utf8"));
+    if (typeof v.repo !== "string" || typeof v.checkedAt !== "string")
+      return null;
+    return {
+      repo: v.repo,
+      checkedAt: v.checkedAt,
+      latest: typeof v.latest === "string" ? v.latest : null,
+      tags: Array.isArray(v.tags) ? v.tags.filter((t) => typeof t === "string") : []
+    };
+  } catch {
+    return null;
+  }
+}
+var KEPT_TAGS = 50;
+async function latestCheck2(root, repo, remote, now = Date.now, intervalMs = LATEST_CHECK_MS2) {
+  const kept = readLatestCheck2(root);
+  const prior = kept !== null && kept.repo === repo ? kept : null;
+  if (prior !== null) {
+    const age = now() - Date.parse(prior.checkedAt);
+    if (age >= 0 && age < intervalMs)
+      return prior;
+  }
+  const checkedAt = new Date(now()).toISOString();
+  const held = {
+    repo,
+    checkedAt,
+    latest: prior?.latest ?? null,
+    tags: prior?.tags ?? []
+  };
+  keep(root, held);
+  let check;
+  try {
+    const tags = (await remote.tags(repo)).filter((t) => parseArchiveTag2(t) !== null).sort(compareTagsNewestFirst2);
+    check = {
+      repo,
+      checkedAt,
+      latest: pickTag2(tags, { kind: "latest" }),
+      tags: tags.slice(0, KEPT_TAGS)
+    };
+  } catch {
+    return held;
+  }
+  keep(root, check);
+  return check;
+}
+function keep(root, check) {
+  try {
+    writeJsonAtomic2(latestCheckPath2(root), check);
+  } catch {}
+}
+async function within(p, ms) {
+  let timer;
+  const late = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(null), Math.max(0, ms));
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([p, late]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function staleWarning2(answered, latest, floor, tags = [], command = "idq") {
+  const a = parseArchiveTag2(answered);
+  if (a === null)
+    return null;
+  const belowFloor = floor !== null && (a.cut === undefined || a.cut < floor.cut);
+  const why = belowFloor ? ` (${floor.why})` : "";
+  if (latest !== null && compareTagsNewestFirst2(answered, latest) > 0) {
+    const lp = parseArchiveTag2(latest);
+    if (!belowFloor || lp?.cut !== undefined && lp.cut >= (floor?.cut ?? 0))
+      return `answered from ${answered}. ${latest} is available${why}: run \`${command} update\` to get the latest`;
+  }
+  if (!belowFloor)
+    return null;
+  const floorTag = pickTag2(tags, { kind: "cut", cut: floor.cut, fraction: 0 });
+  return `answered from ${answered}. ${floorTag ?? `cut ${floor.cut}`} is required${why}: run \`${command} use ${floor.cut}\` to get it`;
+}
+
+export { DATABASES2, planAsset2, sha256File2, unzstdTo2, NAME_LEVELS2, nameLevel2, NO_CALENDAR2, FeisFinder2, ADVANCEMENT_DANCES2, entryRank2, FEIS_LOCAL_ID_FLOOR2, ResultFinder2, MajorsFinder2, LINEAGE_FILE2, linksOfLineage2, releaseSchoolGraph2, readsSpanishNames2, SchoolResolver2, initialsOnly2, nameOrderOf, DancerResolver2, readPopulation2, syllabusSourceOf2, canonicalOf2, CompResolver2, StaffFinder2, TeamFinder2, EventFinder2, defaultBuilders2, indexPath2, indexKey2, isCurrent2, buildIndex2, ensureIndex2, listIndexes2, readPin2, youngest2, dancerResolverOf2, RegistrationResolver2, ghRemote2, httpsRemote2, fallbackRemote2, setRemote2, defaultRemote, columnsOf2, FEATURES2, capabilityOf2, needsRelease2, resolveTag2, Release2, openRelease2, openCached2, DEFAULT_KEEP2, ReleaseManager2, releases2, LATEST_CHECK_MS2, LATEST_CHECK_BUDGET_MS2, latestCheckPath2, readLatestCheck2, latestCheck2, within, staleWarning2 };

package/dist/cli.js

@@ -1,20 +1,36 @@
 #!/usr/bin/env bun
 // @bun
+import {
+  cacheRoot2,
+  repoOf2
+} from "./chunks/index-hne1wadw.js";
 import {
   nameOrderOf,
+  defaultRemote,
   openRelease2,
-  releases2
-} from "./chunks/index-6028k52f.js";
-import"./chunks/index-hne1wadw.js";
+  releases2,
+  LATEST_CHECK_BUDGET_MS2,
+  latestCheck2,
+  within,
+  staleWarning2
+} from "./chunks/index-zwecpq08.js";
 import"./chunks/index-hghdy980.js";
 
 var USAGE = `usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json]
 
   config repo <owner/name>          set the user-local repository the releases come from
+  config keep <N>                   how many of the newest releases a prune keeps (default 2)
   list [--remote]                   the cached releases (size, files, indexes, the pin), and
                                     with --remote the published tags
   fetch [--release <spec>] [--assets results,majors,<file>...]
                                     download, verify and cache a release (default: results)
+  update [--assets ...] [--keep N] [--no-prune]
+                                    move to the newest published release: fetch it (verified),
+                                    build its indexes, pin it, then prune the cache to the N
+                                    newest releases (default: config keep, else 2), keeping the
+                                    new pin and the one before it
+  use <spec> [--assets ...] [--keep N] [--no-prune]
+                                    the same for the release a spec names
   pin <spec>                        the user-local pin: what a bare open (spec "pinned") opens
   unpin                             remove the pin (a bare open is then "latest")
   current                           the pin, and whether it is cached
@@ -26,8 +42,8 @@ var USAGE = `usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json]
   capabilities [--release <spec>]   what the release carries of what the client reads, from
                                     its own schema: each feature full or missing (its calls
                                     refuse, naming the first cut that publishes it)
-  prune [--keep N] [--dry-run]      remove all but the N newest cached releases (default 1)
-                                    and the pinned one
+  prune [--keep N] [--dry-run]      remove all but the N newest cached releases (default:
+                                    config keep, else 2) and the pinned one
   rm <tag> [--dry-run]              remove one cached release (not the pinned one)
   drop-indexes [<tag>] [--dry-run]  remove the index files (of one release, or of every one)
   feis [--release <spec>] [--platform <p>] [--code <c>] [--id <id>] [--name <glob>] [--year <y>]
@@ -99,6 +115,10 @@ var USAGE = `usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json]
                                     population?, oireachtas?}, a registration: {name, school?,
                                     codes[], feis, year?, population?, oireachtas?})
 
+  A query on the default spec prints one warning line on stderr when its release is older than
+  the newest published one (the remote asked at most once per hour, <cache>/LATEST.json); the
+  answer and the exit code are unchanged, and an offline check says nothing.
+
   <spec>: pinned (the default) | latest | a cut (42, 42.1) | a tag (archive-YYYY.MM.DD-N)`;
 var VALUE = new Set([
   "--cache",
@@ -162,6 +182,9 @@ var mb = (n) => `${(n / 1e6).toFixed(1)} MB`;
 function printPlan(p, say) {
   for (const k of p.keep)
     say(`keep    ${k.tag} (${k.why})`);
+  printRemovals(p, say);
+}
+function printRemovals(p, say) {
   for (const r of p.remove)
     say(`${p.dryRun ? "would remove" : "removed"} ${r.path} ${mb(r.bytes)} (${r.why})`);
   say(`${p.dryRun ? "would free" : "freed"} ${mb(p.bytes)}${p.dryRun ? " (dry run: nothing removed)" : ""}`);
@@ -405,6 +428,27 @@ function eventYearOf(p) {
     ...year !== undefined ? { year: Number(year) } : {}
   };
 }
+var ANSWERING = new Set([
+  "current",
+  "capabilities",
+  "feis",
+  "series",
+  "school",
+  "dancer",
+  "results",
+  "majors",
+  "stream",
+  "records",
+  "feis-dates",
+  "tabulated",
+  "teams",
+  "events",
+  "teacher",
+  "adjudicator",
+  "comp",
+  "syllabus",
+  "resolve"
+]);
 async function main(argv, io = {}) {
   const say = io.say ?? ((s) => console.log(s));
   const log = io.log ?? ((s) => console.error(s));
@@ -426,6 +470,23 @@ async function main(argv, io = {}) {
   };
   const spec = p.flags.get("--release") ?? "pinned";
   const m = releases2(opts);
+  const fresh = io.freshness === false || spec.trim() !== "pinned" || verb === undefined || !ANSWERING.has(verb) ? null : io.freshness ?? {};
+  const answered = { tag: null };
+  const open = async (s, o) => {
+    const rel = await openRelease2(s, o);
+    answered.tag = rel.tag;
+    return rel;
+  };
+  const now = fresh?.now ?? Date.now;
+  const started = now();
+  let check = null;
+  if (fresh !== null) {
+    try {
+      const repo = repoOf2(opts);
+      if (repo !== null)
+        check = latestCheck2(cacheRoot2(opts), repo, opts.remote ?? defaultRemote(), now).catch(() => null);
+    } catch {}
+  }
   const out = (v, text) => {
     if (json)
       say(JSON.stringify(v, null, 2));
@@ -435,12 +496,12 @@ async function main(argv, io = {}) {
   try {
     switch (verb) {
       case "config": {
-        if (rest[0] !== "repo" || rest[1] === undefined) {
+        if (rest[0] !== "repo" && rest[0] !== "keep" || rest[1] === undefined) {
           out(m.readConfig(), () => say(JSON.stringify(m.readConfig())));
           return rest.length === 0 ? 0 : 2;
         }
-        const c = m.config({ repo: rest[1] });
-        out(c, () => say(`repo ${c.repo}`));
+        const c = rest[0] === "repo" ? m.config({ repo: rest[1] }) : m.config({ keep: Number(rest[1]) });
+        out(c, () => say(rest[0] === "repo" ? `repo ${c.repo}` : `keep ${c.keep}`));
         return 0;
       }
       case "list": {
@@ -477,6 +538,31 @@ async function main(argv, io = {}) {
         out(pin, () => say(`pinned ${pin.tag} (from ${pin.source})`));
         return 0;
       }
+      case "update":
+      case "use": {
+        const target = verb === "update" ? "latest" : rest[0];
+        if (target === undefined) {
+          log("use <spec>");
+          return 2;
+        }
+        const assets = (p.flags.get("--assets") ?? "results").split(",").filter((a) => a !== "");
+        const keep = p.flags.has("--keep") ? Number(p.flags.get("--keep")) : undefined;
+        const u = await m.use(target, {
+          assets,
+          prune: !p.bools.has("--no-prune"),
+          ...keep !== undefined ? { keep } : {}
+        });
+        out(u, () => {
+          for (const b of u.built)
+            say(`${u.tag} ${b.name}  ${b.path}`);
+          say(u.was === u.tag ? `pinned ${u.tag} (already pinned; its indexes are built)` : `pinned ${u.tag}${u.was === null ? "" : ` (was ${u.was})`}`);
+          if (u.pruned !== null && u.pruned.remove.length > 0)
+            printRemovals(u.pruned, say);
+        });
+        if (u.pruneError !== undefined)
+          log(`prune after ${verb} failed: ${u.pruneError}`);
+        return 0;
+      }
       case "unpin": {
         const was = m.unpin();
         out({ unpinned: was }, () => say(was ? "unpinned" : "no pin was set"));
@@ -484,6 +570,7 @@ async function main(argv, io = {}) {
       }
       case "current": {
         const c = m.current();
+        answered.tag = c.pin?.tag ?? null;
         out(c, () => say(c.pin === null ? "no pin: a bare open is latest" : `pinned ${c.pin.tag}${c.cached ? "" : " (not cached)"}`));
         return 0;
       }
@@ -506,7 +593,7 @@ async function main(argv, io = {}) {
         return 0;
       }
       case "capabilities": {
-        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        const rel = await open(spec, { ...opts, assets: [] });
         try {
           const c = await rel.capabilities();
           out(c, () => {
@@ -550,7 +637,7 @@ async function main(argv, io = {}) {
         return 0;
       }
       case "feis": {
-        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        const rel = await open(spec, { ...opts, assets: [] });
         const year = p.flags.get("--year");
         const a = await rel.feises.find({
           ...p.flags.has("--platform") ? { platform: p.flags.get("--platform") } : {},
@@ -574,7 +661,7 @@ async function main(argv, io = {}) {
           log("series <name|host code|feis id>");
           return 2;
         }
-        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        const rel = await open(spec, { ...opts, assets: [] });
         const a = await rel.feises.series(rest.join(" "));
         out(a, () => {
           say(`${a.arm}  "${a.asked}"  via ${a.via ?? "-"}  in ${a.tag}${a.redirected !== undefined ? `  (${a.redirected.from} -> ${a.redirected.to})` : ""}${a.why !== undefined ? `  (${a.why})` : ""}`);
@@ -594,7 +681,7 @@ async function main(argv, io = {}) {
           log("school <print|school_id> [--region <code>]");
           return 2;
         }
-        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        const rel = await open(spec, { ...opts, assets: [] });
         const region = p.flags.get("--region");
         const a = await rel.schools.resolve(rest.join(" "), region !== undefined ? { region } : {});
         out(a, () => {
@@ -606,7 +693,7 @@ async function main(argv, io = {}) {
         return a.arm === "none" ? 1 : 0;
       }
       case "dancer": {
-        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        const rel = await open(spec, { ...opts, assets: [] });
         try {
           const id = p.flags.get("--id");
           if (id !== undefined) {
@@ -665,7 +752,7 @@ async function main(argv, io = {}) {
         }
       }
       case "results": {
-        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        const rel = await open(spec, { ...opts, assets: [] });
         try {
           const q = {
             ...p.flags.has("--dancer") ? { dancer_id: Number(p.flags.get("--dancer")) } : {},
@@ -683,7 +770,7 @@ async function main(argv, io = {}) {
         }
       }
       case "majors": {
-        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        const rel = await open(spec, { ...opts, assets: [] });
         try {
           const event = p.flags.get("--event");
           const year = p.flags.get("--year");
@@ -725,7 +812,7 @@ async function main(argv, io = {}) {
       }
       case "stream": {
         const q = streamQueryOf(p);
-        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        const rel = await open(spec, { ...opts, assets: [] });
         try {
           let n = 0;
           const rows = p.bools.has("--entries") ? rel.results.entries(q) : rel.results.stream(q);
@@ -740,7 +827,7 @@ async function main(argv, io = {}) {
         }
       }
       case "records": {
-        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        const rel = await open(spec, { ...opts, assets: [] });
         try {
           const ids = idsOf(p.flags.get("--dancer"));
           if (p.bools.has("--years")) {
@@ -768,7 +855,7 @@ async function main(argv, io = {}) {
         }
       }
       case "feis-dates": {
-        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        const rel = await open(spec, { ...opts, assets: [] });
         try {
           const a = await rel.feises.dates();
           out(a, () => {
@@ -782,7 +869,7 @@ async function main(argv, io = {}) {
         }
       }
       case "tabulated": {
-        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        const rel = await open(spec, { ...opts, assets: [] });
         try {
           const min = p.flags.get("--min-round");
           const a = await rel.majors.tabulated(min !== undefined ? { min_true_round: Number(min) } : {});
@@ -797,7 +884,7 @@ async function main(argv, io = {}) {
         }
       }
       case "teams": {
-        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        const rel = await open(spec, { ...opts, assets: [] });
         try {
           const q = eventYearOf(p);
           if (p.bools.has("--rosters")) {
@@ -833,7 +920,7 @@ async function main(argv, io = {}) {
         }
       }
       case "events": {
-        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        const rel = await open(spec, { ...opts, assets: [] });
         try {
           const a = await rel.events.years(eventYearOf(p));
           out(a, () => {
@@ -852,7 +939,7 @@ async function main(argv, io = {}) {
           log(`${verb} <name|TD number>`);
           return 2;
         }
-        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        const rel = await open(spec, { ...opts, assets: [] });
         try {
           const a = verb === "teacher" ? await rel.staff.teacher(rest.join(" ")) : await rel.staff.adjudicator(rest.join(" "));
           out(a, () => printStaff(a, say));
@@ -866,7 +953,7 @@ async function main(argv, io = {}) {
           log("comp <feis> <code> [--year <y>] [--title <t>]");
           return 2;
         }
-        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        const rel = await open(spec, { ...opts, assets: [] });
         const year = p.flags.get("--year");
         const a = await rel.comps.resolve({
           feis: rest[0],
@@ -882,7 +969,7 @@ async function main(argv, io = {}) {
         const of = p.flags.get("--for");
         if (of !== undefined) {
           const y = rest[0] ?? p.flags.get("--year");
-          const rel = await openRelease2(spec, { ...opts, assets: [] });
+          const rel = await open(spec, { ...opts, assets: [] });
           const a = await rel.comps.syllabusFor(of, y !== undefined ? Number(y) : undefined);
           out(a, () => {
             say(`${a.arm}  ${a.asked.series}  asked ${a.asked.year ?? "-"}  read ${a.year ?? "-"} (${a.held ? "held" : "not held"})  from ${a.source ?? "-"}  series ${a.series_id ?? "-"} (years ${a.years.join(", ") || "-"})  in ${a.tag}`);
@@ -901,7 +988,7 @@ async function main(argv, io = {}) {
           log("syllabus <feis> [year]");
           return 2;
         }
-        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        const rel = await open(spec, { ...opts, assets: [] });
         const a = await rel.comps.syllabus(rest[0], rest[1] !== undefined ? Number(rest[1]) : undefined);
         out(a, () => {
           say(`${a.feis.asked}  ${a.year ?? "?"}  ${a.held ? `held: ${a.feis.feis_ids.join(", ")}` : "not held"}  series ${a.feis.brand_id ?? "-"} (years ${a.years.join(", ") || "-"})  in ${a.tag}`);
@@ -913,7 +1000,7 @@ async function main(argv, io = {}) {
         return a.held ? 0 : 1;
       }
       case "resolve": {
-        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        const rel = await open(spec, { ...opts, assets: [] });
         try {
           return await resolveVerb(rel, rest[0], rest.slice(1), p, say, io.stdin ?? (() => Bun.stdin.text()));
         } finally {
@@ -927,6 +1014,14 @@ async function main(argv, io = {}) {
   } catch (e) {
     log(`idq ${verb}: ${e.message}`);
     return 1;
+  } finally {
+    if (fresh !== null && answered.tag !== null) {
+      const budget = fresh.budgetMs ?? LATEST_CHECK_BUDGET_MS2;
+      const c = check === null ? null : await within(check, budget - (now() - started));
+      const w = staleWarning2(answered.tag, c?.latest ?? null, fresh.floor ?? null, c?.tags ?? [], fresh.command);
+      if (w !== null)
+        log(w);
+    }
   }
 }
 if (import.meta.main)

package/dist/index.js

@@ -50,9 +50,16 @@ import {
   Release2,
   openRelease2,
   openCached2,
+  DEFAULT_KEEP2,
   ReleaseManager2,
-  releases2
-} from "./chunks/index-6028k52f.js";
+  releases2,
+  LATEST_CHECK_MS2,
+  LATEST_CHECK_BUDGET_MS2,
+  latestCheckPath2,
+  readLatestCheck2,
+  latestCheck2,
+  staleWarning2
+} from "./chunks/index-zwecpq08.js";
 import {
   cacheRoot2,
   repoOf2
@@ -71,11 +78,14 @@ export {
   ARCHIVE_TAG2 as ARCHIVE_TAG,
   CompResolver2 as CompResolver,
   DATABASES2 as DATABASES,
+  DEFAULT_KEEP2 as DEFAULT_KEEP,
   DancerResolver2 as DancerResolver,
   EventFinder2 as EventFinder,
   FEATURES2 as FEATURES,
   FEIS_LOCAL_ID_FLOOR2 as FEIS_LOCAL_ID_FLOOR,
   FeisFinder2 as FeisFinder,
+  LATEST_CHECK_BUDGET_MS2 as LATEST_CHECK_BUDGET_MS,
+  LATEST_CHECK_MS2 as LATEST_CHECK_MS,
   LINEAGE_FILE2 as LINEAGE_FILE,
   MajorsFinder2 as MajorsFinder,
   NAME_LEVELS2 as NAME_LEVELS,
@@ -105,6 +115,8 @@ export {
   indexPath2 as indexPath,
   initialsOnly2 as initialsOnly,
   isCurrent2 as isCurrent,
+  latestCheck2 as latestCheck,
+  latestCheckPath2 as latestCheckPath,
   linksOfLineage2 as linksOfLineage,
   listIndexes2 as listIndexes,
   nameLevel2 as nameLevel,
@@ -115,6 +127,7 @@ export {
   parseReleaseSpec2 as parseReleaseSpec,
   pickTag2 as pickTag,
   planAsset2 as planAsset,
+  readLatestCheck2 as readLatestCheck,
   readPin2 as readPin,
   readPopulation2 as readPopulation,
   readsSpanishNames2 as readsSpanishNames,
@@ -125,6 +138,7 @@ export {
   resolveTag2 as resolveTag,
   setRemote2 as setRemote,
   sha256File2 as sha256File,
+  staleWarning2 as staleWarning,
   syllabusSourceOf2 as syllabusSourceOf,
   unzstdTo2 as unzstdTo,
   youngest2 as youngest

package/dist/types/cli.d.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env bun
+import { type FreshnessFloor } from "./freshness.js";
 import type { OpenOptions } from "./release.js";
 import type { StreamQuery } from "./stream.js";
-export declare const USAGE = "usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json]\n\n  config repo <owner/name>          set the user-local repository the releases come from\n  list [--remote]                   the cached releases (size, files, indexes, the pin), and\n                                    with --remote the published tags\n  fetch [--release <spec>] [--assets results,majors,<file>...]\n                                    download, verify and cache a release (default: results)\n  pin <spec>                        the user-local pin: what a bare open (spec \"pinned\") opens\n  unpin                             remove the pin (a bare open is then \"latest\")\n  current                           the pin, and whether it is cached\n  add <dir> --tag <tag>             add a release built locally (its MANIFEST.json and files)\n                                    to the cache under its tag\n  index [--release <spec>] [<name>...] [--force]\n                                    build the per-tag indexes (default: every one)\n  verify [--release <spec>]         re-hash every cached file against its receipt\n  capabilities [--release <spec>]   what the release carries of what the client reads, from\n                                    its own schema: each feature full or missing (its calls\n                                    refuse, naming the first cut that publishes it)\n  prune [--keep N] [--dry-run]      remove all but the N newest cached releases (default 1)\n                                    and the pinned one\n  rm <tag> [--dry-run]              remove one cached release (not the pinned one)\n  drop-indexes [<tag>] [--dry-run]  remove the index files (of one release, or of every one)\n  feis [--release <spec>] [--platform <p>] [--code <c>] [--id <id>] [--name <glob>] [--year <y>]\n                                    the feises a query names\n  series [--release <spec>] <name|host code|feis id>\n                                    the series a name, a host code (fweb:ABC) or any feis id\n                                    names: its years, hosts, codes and next instance\n  school [--release <spec>] <print|school_id> [--region <code>]\n                                    a school print or id to the published schools\n  dancer [--release <spec>] <name> | --surname <s> | --like <glob> | --id <dancer_id>\n         [--order surname-first|given-first] [--school <print|id>]\n         [--yob <y> | --band <U10> [--year <y>] | --comp <competition>] [--as-of <date>]\n         [--population girls|boys] [--oireachtas <region>[:<year>]] [--rows]\n                                    the dancers a name reaches, each with its evidence\n                                    (name level, age, school, population, region) and the arm;\n                                    --oireachtas is the regional the roster is for, its region in\n                                    the release's spelling (SRO, MAO), its year the --as-of year\n                                    where none is given; the results of\n                                    the one dancer where one answers (or --rows for each)\n  results [--release <spec>] [--dancer <id>] [--feis <id>] [--comp <competition>]\n          [--school <print|id>] [--year <y>] [--limit <n>]\n                                    the published result rows, prints and ids\n  majors [--release <spec>] [--event <e>] [--year <y>] [--comp <competition>] [--dancer <id>]\n                                    the majors: every event and its years; an event's\n                                    competitions; a competition's, an event's or a dancer's rows\n  stream [--release <spec>] --scope majors|transcribed|platform|all [--entries] [--event <e,...>]\n         [--year <y> | --year <from>..<to>] [--tier <t,...>] [--category <c,...>]\n         [--level <feis_level,...>] [--dancer <id,...>] [--school <school_id>] [--primary]\n                                    every row a scope holds, one JSON line each, never the\n                                    whole table in memory; --entries one per address (the row\n                                    it stands for, with its recall order)\n  records [--release <spec>] [--dancer <id,...>]\n                                    every dancer's record: display, appearances, birth window,\n                                    populations\n  records --years [--release <spec>] [--dancer <id,...>] [--year <y>]\n                                    each dancer's region, nationals and place per year\n  feis-dates [--release <spec>]     every feis's first and last day\n  tabulated [--release <spec>] [--min-round <n>]\n                                    the majors addresses the marks sheets tabulate to round n\n                                    or later (default 3)\n  teams [--release <spec>] [--event <e>] [--year <y>] [--rosters | --joins]\n                                    the team result rows of an event-year; with --rosters its\n                                    roster teams and their dancers; with --joins how each roster\n                                    team meets the results\n  events [--release <spec>] [--event <e>] [--year <y>]\n                                    each event-year's dates and place\n  teacher [--release <spec>] <name|TD number>\n                                    the staff lists' people: where they taught, the register,\n                                    where they sat\n  adjudicator [--release <spec>] <name|TD number>\n                                    the register's and the panels' people: the same answer\n  comp [--release <spec>] <feis> <code> [--year <y>] [--title <t>]\n                                    a feis's own comp code to the comp it names, through that\n                                    feis's syllabus (the prior year's only where the platform\n                                    numbers every feis alike; elsewhere the title)\n  syllabus [--release <spec>] <feis> [year]\n                                    one feis-year's comps, in printed order\n  syllabus [--release <spec>] --for <series> [year]\n                                    a series' syllabus for a year: that year's where held,\n                                    else the newest, saying which and what it is read from\n  resolve comp [<feis> <code>] [--year <y>] [--title <t>]\n  resolve dancer [<name>] [--school <s>] [--comp <feis>/<code> | --yob <y> | --band <b> --year <y>]\n                 [--order <o>] [--as-of <date>] [--population girls|boys]\n                 [--oireachtas <region>[:<year>]]\n  resolve registrations\n                                    JSONL out, one answer per line; with no positional the\n                                    questions are JSONL on stdin, one per line (a comp:\n                                    {feis, code, year?, title?}, a dancer: {name, school?, age?,\n                                    population?, oireachtas?}, a registration: {name, school?,\n                                    codes[], feis, year?, population?, oireachtas?})\n\n  <spec>: pinned (the default) | latest | a cut (42, 42.1) | a tag (archive-YYYY.MM.DD-N)";
+export declare const USAGE = "usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json]\n\n  config repo <owner/name>          set the user-local repository the releases come from\n  config keep <N>                   how many of the newest releases a prune keeps (default 2)\n  list [--remote]                   the cached releases (size, files, indexes, the pin), and\n                                    with --remote the published tags\n  fetch [--release <spec>] [--assets results,majors,<file>...]\n                                    download, verify and cache a release (default: results)\n  update [--assets ...] [--keep N] [--no-prune]\n                                    move to the newest published release: fetch it (verified),\n                                    build its indexes, pin it, then prune the cache to the N\n                                    newest releases (default: config keep, else 2), keeping the\n                                    new pin and the one before it\n  use <spec> [--assets ...] [--keep N] [--no-prune]\n                                    the same for the release a spec names\n  pin <spec>                        the user-local pin: what a bare open (spec \"pinned\") opens\n  unpin                             remove the pin (a bare open is then \"latest\")\n  current                           the pin, and whether it is cached\n  add <dir> --tag <tag>             add a release built locally (its MANIFEST.json and files)\n                                    to the cache under its tag\n  index [--release <spec>] [<name>...] [--force]\n                                    build the per-tag indexes (default: every one)\n  verify [--release <spec>]         re-hash every cached file against its receipt\n  capabilities [--release <spec>]   what the release carries of what the client reads, from\n                                    its own schema: each feature full or missing (its calls\n                                    refuse, naming the first cut that publishes it)\n  prune [--keep N] [--dry-run]      remove all but the N newest cached releases (default:\n                                    config keep, else 2) and the pinned one\n  rm <tag> [--dry-run]              remove one cached release (not the pinned one)\n  drop-indexes [<tag>] [--dry-run]  remove the index files (of one release, or of every one)\n  feis [--release <spec>] [--platform <p>] [--code <c>] [--id <id>] [--name <glob>] [--year <y>]\n                                    the feises a query names\n  series [--release <spec>] <name|host code|feis id>\n                                    the series a name, a host code (fweb:ABC) or any feis id\n                                    names: its years, hosts, codes and next instance\n  school [--release <spec>] <print|school_id> [--region <code>]\n                                    a school print or id to the published schools\n  dancer [--release <spec>] <name> | --surname <s> | --like <glob> | --id <dancer_id>\n         [--order surname-first|given-first] [--school <print|id>]\n         [--yob <y> | --band <U10> [--year <y>] | --comp <competition>] [--as-of <date>]\n         [--population girls|boys] [--oireachtas <region>[:<year>]] [--rows]\n                                    the dancers a name reaches, each with its evidence\n                                    (name level, age, school, population, region) and the arm;\n                                    --oireachtas is the regional the roster is for, its region in\n                                    the release's spelling (SRO, MAO), its year the --as-of year\n                                    where none is given; the results of\n                                    the one dancer where one answers (or --rows for each)\n  results [--release <spec>] [--dancer <id>] [--feis <id>] [--comp <competition>]\n          [--school <print|id>] [--year <y>] [--limit <n>]\n                                    the published result rows, prints and ids\n  majors [--release <spec>] [--event <e>] [--year <y>] [--comp <competition>] [--dancer <id>]\n                                    the majors: every event and its years; an event's\n                                    competitions; a competition's, an event's or a dancer's rows\n  stream [--release <spec>] --scope majors|transcribed|platform|all [--entries] [--event <e,...>]\n         [--year <y> | --year <from>..<to>] [--tier <t,...>] [--category <c,...>]\n         [--level <feis_level,...>] [--dancer <id,...>] [--school <school_id>] [--primary]\n                                    every row a scope holds, one JSON line each, never the\n                                    whole table in memory; --entries one per address (the row\n                                    it stands for, with its recall order)\n  records [--release <spec>] [--dancer <id,...>]\n                                    every dancer's record: display, appearances, birth window,\n                                    populations\n  records --years [--release <spec>] [--dancer <id,...>] [--year <y>]\n                                    each dancer's region, nationals and place per year\n  feis-dates [--release <spec>]     every feis's first and last day\n  tabulated [--release <spec>] [--min-round <n>]\n                                    the majors addresses the marks sheets tabulate to round n\n                                    or later (default 3)\n  teams [--release <spec>] [--event <e>] [--year <y>] [--rosters | --joins]\n                                    the team result rows of an event-year; with --rosters its\n                                    roster teams and their dancers; with --joins how each roster\n                                    team meets the results\n  events [--release <spec>] [--event <e>] [--year <y>]\n                                    each event-year's dates and place\n  teacher [--release <spec>] <name|TD number>\n                                    the staff lists' people: where they taught, the register,\n                                    where they sat\n  adjudicator [--release <spec>] <name|TD number>\n                                    the register's and the panels' people: the same answer\n  comp [--release <spec>] <feis> <code> [--year <y>] [--title <t>]\n                                    a feis's own comp code to the comp it names, through that\n                                    feis's syllabus (the prior year's only where the platform\n                                    numbers every feis alike; elsewhere the title)\n  syllabus [--release <spec>] <feis> [year]\n                                    one feis-year's comps, in printed order\n  syllabus [--release <spec>] --for <series> [year]\n                                    a series' syllabus for a year: that year's where held,\n                                    else the newest, saying which and what it is read from\n  resolve comp [<feis> <code>] [--year <y>] [--title <t>]\n  resolve dancer [<name>] [--school <s>] [--comp <feis>/<code> | --yob <y> | --band <b> --year <y>]\n                 [--order <o>] [--as-of <date>] [--population girls|boys]\n                 [--oireachtas <region>[:<year>]]\n  resolve registrations\n                                    JSONL out, one answer per line; with no positional the\n                                    questions are JSONL on stdin, one per line (a comp:\n                                    {feis, code, year?, title?}, a dancer: {name, school?, age?,\n                                    population?, oireachtas?}, a registration: {name, school?,\n                                    codes[], feis, year?, population?, oireachtas?})\n\n  A query on the default spec prints one warning line on stderr when its release is older than\n  the newest published one (the remote asked at most once per hour, <cache>/LATEST.json); the\n  answer and the exit code are unchanged, and an offline check says nothing.\n\n  <spec>: pinned (the default) | latest | a cut (42, 42.1) | a tag (archive-YYYY.MM.DD-N)";
 export interface Parsed {
     positional: string[];
     flags: Map<string, string>;
@@ -17,10 +18,17 @@ type Line<T> = {
 };
 export declare function jsonLines<T>(text: string, check: (v: T) => string | null): Line<T>[];
 export declare function streamQueryOf(p: Parsed): StreamQuery;
+export interface FreshnessIO {
+    floor?: FreshnessFloor | null;
+    command?: string;
+    now?: () => number;
+    budgetMs?: number;
+}
 export declare function main(argv: readonly string[], io?: {
     say?: (s: string) => void;
     log?: (s: string) => void;
     opts?: OpenOptions;
     stdin?: () => Promise<string>;
+    freshness?: FreshnessIO | false;
 }): Promise<number>;
 export {};

package/dist/types/config.d.ts

@@ -7,6 +7,7 @@ export declare function expandHome(p: string): string;
 export declare function cacheRoot(opts?: ClientOptions): string;
 export interface UserConfig {
     repo?: string;
+    keep?: number;
 }
 export declare const configPath: (root: string) => string;
 export declare function readConfig(root: string): UserConfig;

package/dist/types/freshness.d.ts

@@ -0,0 +1,18 @@
+import type { Remote } from "./remote.js";
+export declare const LATEST_CHECK_MS: number;
+export declare const LATEST_CHECK_BUDGET_MS = 1500;
+export interface LatestCheck {
+    repo: string;
+    checkedAt: string;
+    latest: string | null;
+    tags: string[];
+}
+export interface FreshnessFloor {
+    cut: number;
+    why: string;
+}
+export declare const latestCheckPath: (root: string) => string;
+export declare function readLatestCheck(root: string): LatestCheck | null;
+export declare function latestCheck(root: string, repo: string, remote: Remote, now?: () => number, intervalMs?: number): Promise<LatestCheck>;
+export declare function within<T>(p: Promise<T>, ms: number): Promise<T | null>;
+export declare function staleWarning(answered: string, latest: string | null, floor: FreshnessFloor | null, tags?: readonly string[], command?: string): string | null;

package/dist/types/index.d.ts

@@ -7,8 +7,9 @@ export { type Comp, type CompAnswer, type CompDance, type CompKind, type CompQue
 export { type ClientOptions, cacheRoot, repoOf } from "./config.js";
 export { type Feis, type FeisAnswer, FeisFinder, type FeisQuery, NO_CALENDAR, type Series, type SeriesAnswer, type SeriesInstance, type SeriesNext, } from "./feises.js";
 export { type IndexBuilder, type IndexFile, buildIndex, defaultBuilders, ensureIndex, indexKey, indexPath, isCurrent, listIndexes, } from "./indexes.js";
-export { type CachedRelease, type ReleaseList, ReleaseManager, type RemovalPlan, releases, } from "./manager.js";
+export { type CachedRelease, DEFAULT_KEEP, type ReleaseList, ReleaseManager, type RemovalPlan, type UseResult, releases, } from "./manager.js";
 export { type Registered, type Sat, type StaffAnswer, StaffFinder, type StaffPerson, type Taught, type TdLink, } from "./people.js";
+export { type FreshnessFloor, LATEST_CHECK_BUDGET_MS, LATEST_CHECK_MS, type LatestCheck, latestCheck, latestCheckPath, readLatestCheck, staleWarning, } from "./freshness.js";
 export { type Pin, readPin } from "./pin.js";
 export { type Remote, type RemoteAsset, fallbackRemote, ghRemote, httpsRemote, setRemote, } from "./remote.js";
 export { type OpenOptions, Release, openCached, openRelease, resolveTag, } from "./release.js";

package/dist/types/manager.d.ts

@@ -1,4 +1,5 @@
 import { type LandedFile } from "./assets.js";
+import { type UserConfig } from "./config.js";
 import { type IndexFile } from "./indexes.js";
 import { type Pin } from "./pin.js";
 import { type OpenOptions, type Release, resolveTag } from "./release.js";
@@ -35,6 +36,18 @@ export interface RemovalPlan {
     }[];
     bytes: number;
 }
+export declare const DEFAULT_KEEP = 2;
+export interface UseResult {
+    tag: string;
+    was: string | null;
+    pin: Pin;
+    built: {
+        name: string;
+        path: string;
+    }[];
+    pruned: RemovalPlan | null;
+    pruneError?: string;
+}
 export declare class ReleaseManager {
     private readonly opts;
     readonly root: string;
@@ -48,19 +61,19 @@ export declare class ReleaseManager {
         assets?: readonly string[];
     }): Promise<Release>;
     pin(spec: string | number): Promise<Pin>;
+    use(spec: string | number, o?: {
+        assets?: readonly string[];
+        prune?: boolean;
+        keep?: number;
+    }): Promise<UseResult>;
+    keepCount(keep?: number): number;
     unpin(): boolean;
     current(): {
         pin: Pin | null;
         cached: boolean;
     };
-    config(patch: {
-        repo?: string;
-    }): {
-        repo?: string;
-    };
-    readConfig(): {
-        repo?: string;
-    };
+    config(patch: UserConfig): UserConfig;
+    readConfig(): UserConfig;
     add(dir: string, tag: string): Promise<Release>;
     index(spec: string | number, names?: readonly string[], o?: {
         force?: boolean;
@@ -77,6 +90,10 @@ export declare class ReleaseManager {
     prune(o?: {
         keep?: number;
         dryRun?: boolean;
+        hold?: readonly {
+            tag: string;
+            why: string;
+        }[];
     }): RemovalPlan;
     remove(tag: string, o?: {
         dryRun?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/archive-client",
-	"version": "0.20.2",
+	"version": "0.22.0",
 	"description": "Open a versioned release of an Irish dance results archive: download, verify, decompress and cache it by tag, keep the cache, and resolve feises and schools against it",
 	"keywords": ["irish-dance", "results", "release", "cache", "sqlite"],
 	"license": "MIT",