@finbheara/archive-client 0.21.0 → 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,10 +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>...]
-    idq use <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]
@@ -752,7 +763,8 @@ is passed to the dancer resolver as asked (`rel.dancers`, above).
 
 `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
+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")`).
 

package/dist/chunks/{index-pfsxe80h.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;
@@ -3801,13 +3807,24 @@ class ReleaseManager2 {
     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);
-    return { tag, was, pin, built };
+    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);
@@ -3819,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() {
@@ -3896,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`);
     });
@@ -4035,4 +4055,4 @@ function staleWarning2(answered, latest, floor, tags = [], command = "idq") {
   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 };
+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

@@ -13,19 +13,24 @@ import {
   latestCheck2,
   within,
   staleWarning2
-} from "./chunks/index-pfsxe80h.js";
+} 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 ...]             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
+  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
@@ -37,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>]
@@ -177,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)" : ""}`);
@@ -488,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": {
@@ -538,12 +546,21 @@ async function main(argv, io = {}) {
           return 2;
         }
         const assets = (p.flags.get("--assets") ?? "results").split(",").filter((a) => a !== "");
-        const u = await m.use(target, { assets });
+        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": {

package/dist/index.js

@@ -50,6 +50,7 @@ import {
   Release2,
   openRelease2,
   openCached2,
+  DEFAULT_KEEP2,
   ReleaseManager2,
   releases2,
   LATEST_CHECK_MS2,
@@ -58,7 +59,7 @@ import {
   readLatestCheck2,
   latestCheck2,
   staleWarning2
-} from "./chunks/index-pfsxe80h.js";
+} from "./chunks/index-zwecpq08.js";
 import {
   cacheRoot2,
   repoOf2
@@ -77,6 +78,7 @@ 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,

package/dist/types/cli.d.ts

@@ -2,7 +2,7 @@
 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  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 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>;

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/index.d.ts

@@ -7,7 +7,7 @@ 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";

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;
@@ -50,28 +63,17 @@ export declare class ReleaseManager {
     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;
-        }[];
-    }>;
+        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;
@@ -88,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.21.0",
+	"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",