@finbheara/archive-client 0.20.1 → 0.21.0

package/README.md

@@ -709,6 +709,8 @@ is passed to the dancer resolver as asked (`rel.dancers`, above).
     idq config repo <owner/name>
     idq list [--remote]
     idq fetch [--release <spec>] [--assets results,majors,<file>...]
+    idq update [--assets results,majors,<file>...]
+    idq use <spec> [--assets results,majors,<file>...]
     idq pin <spec> | unpin | current
     idq add <dir> --tag <tag>
     idq index [--release <spec>] [<name>...] [--force]
@@ -748,6 +750,24 @@ 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. `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-pfsxe80h.js}

@@ -3800,6 +3800,15 @@ class ReleaseManager2 {
     writePin(this.root, pin);
     return pin;
   }
+  async use(spec, o = {}) {
+    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);
+    return { tag, was, pin, built };
+  }
   unpin() {
     return clearPin(this.root);
   }
@@ -3937,4 +3946,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, ReleaseManager2, releases2, LATEST_CHECK_MS2, LATEST_CHECK_BUDGET_MS2, latestCheckPath2, readLatestCheck2, latestCheck2, within, staleWarning2 };

package/dist/cli.js

@@ -1,11 +1,19 @@
 #!/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-pfsxe80h.js";
 import"./chunks/index-hghdy980.js";
 
 var USAGE = `usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json]
@@ -15,6 +23,9 @@ var USAGE = `usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json]
                                     with --remote the published tags
   fetch [--release <spec>] [--assets results,majors,<file>...]
                                     download, verify and cache a release (default: results)
+  update [--assets ...]             move to the newest published release: fetch it (verified),
+                                    build its indexes, then pin it
+  use <spec> [--assets ...]         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
@@ -99,6 +110,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",
@@ -405,6 +420,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 +462,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));
@@ -477,6 +530,22 @@ 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 u = await m.use(target, { assets });
+        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})`}`);
+        });
+        return 0;
+      }
       case "unpin": {
         const was = m.unpin();
         out({ unpinned: was }, () => say(was ? "unpinned" : "no pin was set"));
@@ -484,6 +553,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 +576,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 +620,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 +644,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 +664,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 +676,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 +735,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 +753,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 +795,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 +810,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 +838,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 +852,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 +867,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 +903,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 +922,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 +936,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 +952,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 +971,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 +983,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 +997,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

@@ -51,8 +51,14 @@ import {
   openRelease2,
   openCached2,
   ReleaseManager2,
-  releases2
-} from "./chunks/index-6028k52f.js";
+  releases2,
+  LATEST_CHECK_MS2,
+  LATEST_CHECK_BUDGET_MS2,
+  latestCheckPath2,
+  readLatestCheck2,
+  latestCheck2,
+  staleWarning2
+} from "./chunks/index-pfsxe80h.js";
 import {
   cacheRoot2,
   repoOf2
@@ -76,6 +82,8 @@ export {
   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 +113,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 +125,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 +136,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  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 ...]             move to the newest published release: fetch it (verified),\n                                    build its indexes, then pin it\n  use <spec> [--assets ...]         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 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  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/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

@@ -9,6 +9,7 @@ export { type Feis, type FeisAnswer, FeisFinder, type FeisQuery, NO_CALENDAR, ty
 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 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

@@ -48,6 +48,17 @@ export declare class ReleaseManager {
         assets?: readonly string[];
     }): Promise<Release>;
     pin(spec: string | number): Promise<Pin>;
+    use(spec: string | number, o?: {
+        assets?: readonly string[];
+    }): Promise<{
+        tag: string;
+        was: string | null;
+        pin: Pin;
+        built: {
+            name: string;
+            path: string;
+        }[];
+    }>;
     unpin(): boolean;
     current(): {
         pin: Pin | null;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/archive-client",
-	"version": "0.20.1",
+	"version": "0.21.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",
@@ -44,8 +44,8 @@
 		"prepublishOnly": "bun scripts/build.ts && bun ../../tools/checks/archive-client-tarball.ts"
 	},
 	"dependencies": {
-		"@finbheara/domain": "0.57.1",
-		"@finbheara/names": "0.29.0",
+		"@finbheara/domain": "0.57.2",
+		"@finbheara/names": "0.30.0",
 		"hyparquet": "1.31.2"
 	},
 	"devDependencies": {