@finbheara/archive-client 0.21.0 → 0.23.0

package/README.md

@@ -121,6 +121,7 @@ else `archive-client` in your home cache directory.
     <root>/<tag>/index/<name>.sqlite     the per-tag indexes
     <root>/PINNED.json                   the user-local pin
     <root>/config.json                   the user-local config
+    <root>/local/<tag>/                  a local build a default query answered from (below)
 
 A file already in place with no receipt (laid out by hand) is adopted where the manifest's hash
 vouches for it, and fetched again where it does not. A published release never changes, so a
@@ -139,13 +140,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 +718,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 +764,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")`).
 
@@ -768,6 +781,29 @@ tag, a cut, `latest`) is never warned about: it was asked for. `main(argv, { fre
 `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.
 
+A LOCAL BUILD ANSWERS THE DEFAULT SPEC. A project that builds releases can offer the client the
+directories its unpublished builds sit in, `main(argv, { local: { builds } })`, where `builds()`
+answers `{ dir, label, fraction? }[]`: a directory holding a build's `MANIFEST.json` and files as
+its emitter wrote them, what to call it, and the fraction of its cut it builds. A query with no
+`--release` then answers from the NEWEST COMPLETE build strictly newer than the pinned release
+(the cut its manifest's input release names, then the fraction; with no pin, the newest cached
+release; with neither, any complete build), and prints one line on stderr:
+
+    answered from <label> (unpublished, <dir>). Pass --release <tag> for a published one, or --live for the pin.
+
+The answer's format and the exit code are otherwise the call's own. `--release <spec>` names a
+release as ever, and `--live` forces the pinned one; neither reads a build. A build is COMPLETE
+where its manifest parses, names an input release with a cut, and states a `results` database
+that is on disk, each stated database at its stated bytes (`incomplete(dir)` says why not). The
+caller leaves out a build it knows is still being written. A build is never read in place: its
+files are added (hard-linked where the filesystem allows, every database checked against the
+manifest's hash) to `<root>/local/<tag>` and indexed there on first use, the add made in a private
+directory and renamed into place whole. `<root>/local` is no release tag, so `list`, `prune` and
+`use` never see a build, the pin never moves to one, and it never counts among the releases a
+prune keeps. The builds' cache keeps the one build it last answered from, and a build whose
+manifest changed is added again. A verb whose index reads a file the build lacks (a table written
+only when the release is published: `teams`, `events`) answers from the pinned release, saying so.
+
 `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-pfsxe80h.js → index-vsk6837c.js}

@@ -9,6 +9,8 @@ import {
 } from "./index-hne1wadw.js";
 import {
   parseArchiveTag2,
+  renderArchiveTag2,
+  cutOf2,
   compareTagsNewestFirst2,
   parseReleaseSpec2,
   pickTag2
@@ -2804,6 +2806,20 @@ function listIndexes2(rel) {
   });
 }
 
+import { createHash as createHash3 } from "crypto";
+import {
+  copyFileSync as copyFileSync2,
+  existsSync as existsSync6,
+  linkSync as linkSync2,
+  mkdirSync as mkdirSync5,
+  readFileSync as readFileSync5,
+  readdirSync as readdirSync4,
+  renameSync as renameSync3,
+  rmSync as rmSync5,
+  statSync as statSync4
+} from "fs";
+import { join as join5 } from "path";
+
 import {
   copyFileSync,
   existsSync as existsSync5,
@@ -3741,6 +3757,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 +3823,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 +3852,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 +3931,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`);
     });
@@ -3946,17 +3982,178 @@ function releases2(opts = {}) {
   return new ReleaseManager2(opts);
 }
 
-import { existsSync as existsSync6, readFileSync as readFileSync5 } from "fs";
-import { join as join5 } from "path";
+var LOCAL_DIR2 = "local";
+var localRoot2 = (root) => join5(root, LOCAL_DIR2);
+var newerThan2 = (a, b) => a.cut > b.cut || a.cut === b.cut && a.fraction > b.fraction;
+function readManifest(dir) {
+  const p = join5(dir, "MANIFEST.json");
+  if (!existsSync6(p))
+    return null;
+  try {
+    const v = JSON.parse(readFileSync5(p, "utf8"));
+    return v !== null && typeof v === "object" && !Array.isArray(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+function incomplete2(dir) {
+  const m = readManifest(dir);
+  if (m === null)
+    return "no MANIFEST.json that parses";
+  if (cutOf2(typeof m.corpusRelease === "string" ? m.corpusRelease : undefined) === undefined)
+    return "its manifest names no input release with a cut";
+  const dbs = m.databases ?? {};
+  if (dbs.results === undefined)
+    return "its manifest states no results database";
+  for (const name of DATABASES2) {
+    const d = dbs[name];
+    if (d === undefined)
+      continue;
+    const p = join5(dir, d.file ?? `${name}.sqlite`);
+    if (!existsSync6(p))
+      return `no ${d.file ?? `${name}.sqlite`}`;
+    if (d.bytes !== undefined && statSync4(p).size !== d.bytes)
+      return `${d.file ?? `${name}.sqlite`} is ${statSync4(p).size} bytes, the manifest says ${d.bytes}`;
+  }
+  return null;
+}
+function releaseVersion2(rel) {
+  const t = parseArchiveTag2(rel.tag);
+  const cut = cutOf2(typeof rel.manifest.corpusRelease === "string" ? rel.manifest.corpusRelease : undefined) ?? t?.cut;
+  if (cut === undefined)
+    return null;
+  const f = rel.manifest.archiveFraction;
+  return { cut, fraction: typeof f === "number" ? f : t?.fraction ?? 0 };
+}
+function pickBuild2(builds, base) {
+  let best = null;
+  for (const b of builds) {
+    if (incomplete2(b.dir) !== null)
+      continue;
+    const manifest = readManifest(b.dir);
+    const version = {
+      cut: cutOf2(manifest.corpusRelease),
+      fraction: b.fraction ?? 0
+    };
+    if (base !== null && !newerThan2(version, base))
+      continue;
+    if (best === null || newerThan2(version, best.version))
+      best = { build: b, version, manifest };
+  }
+  return best;
+}
+function buildTag2(p) {
+  const at = typeof p.manifest.emittedAt === "string" && !Number.isNaN(Date.parse(p.manifest.emittedAt)) ? new Date(p.manifest.emittedAt) : statSync4(join5(p.build.dir, "MANIFEST.json")).mtime;
+  const date = at.toISOString().slice(0, 10).replaceAll("-", ".");
+  return renderArchiveTag2({ date, cut: p.version.cut, fraction: p.version.fraction });
+}
+function buildFiles(dir) {
+  return readdirSync4(dir).filter((n) => statSync4(join5(dir, n)).isFile()).filter((n) => {
+    const m = /^(.*)\.sqlite(\.zst)?$/.exec(n);
+    return m === null || isDatabase(m[1]);
+  }).sort();
+}
+function lacks(b, manifest, inputs) {
+  return inputs.filter((a) => !planAsset2(a, manifest).published.some((n) => existsSync6(join5(b.dir, n))));
+}
+function buildRemote(label) {
+  const refuse = async () => {
+    throw new Error(`archive-client: ${label} is a local build: it carries only its own files`);
+  };
+  return { name: "local-build", tags: refuse, assets: refuse, download: refuse };
+}
+var sha256Of = (path) => createHash3("sha256").update(readFileSync5(path)).digest("hex");
+var scratchName = (kind) => `.${kind}-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+function buildOptions(root, label, opts) {
+  return { ...opts, cache: localRoot2(root), remote: buildRemote(label), assets: [] };
+}
+async function openBuild2(root, p, opts) {
+  const o = buildOptions(root, p.build.label, opts);
+  const local = localRoot2(root);
+  const tag = buildTag2(p);
+  const want = sha256Of(join5(p.build.dir, "MANIFEST.json"));
+  const current = () => {
+    const rel = openCached2(tag, o);
+    return rel !== null && rel.receipt().files["MANIFEST.json"]?.sha256 === want ? rel : null;
+  };
+  const have = current();
+  if (have !== null)
+    return have;
+  mkdirSync5(local, { recursive: true });
+  const work = join5(local, scratchName("add"));
+  try {
+    const stage = join5(work, "stage");
+    mkdirSync5(stage, { recursive: true });
+    for (const f of buildFiles(p.build.dir)) {
+      try {
+        linkSync2(join5(p.build.dir, f), join5(stage, f));
+      } catch {
+        copyFileSync2(join5(p.build.dir, f), join5(stage, f));
+      }
+    }
+    const added = await new ReleaseManager2({ ...o, cache: join5(work, "cache") }).add(stage, tag);
+    const receipt = added.receipt();
+    receipt.source = `local:${p.build.dir}`;
+    writeJsonAtomic2(receiptPath(added.dir), receipt);
+    added.close();
+    const dest = join5(local, tag);
+    if (existsSync6(dest) && current() === null) {
+      try {
+        renameSync3(dest, join5(local, scratchName("old")));
+      } catch {}
+    }
+    try {
+      renameSync3(added.dir, dest);
+    } catch {}
+  } finally {
+    rmSync5(work, { recursive: true, force: true });
+  }
+  const rel = current();
+  if (rel === null)
+    throw new Error(`archive-client: ${p.build.label} did not land in ${local}`);
+  return rel;
+}
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
+function sweepBuilds2(root, keep) {
+  const local = localRoot2(root);
+  if (!existsSync6(local))
+    return [];
+  const gone = [];
+  for (const name of readdirSync4(local).sort()) {
+    if (name === keep)
+      continue;
+    const m = /^\.(add|old)-(\d+)-/.exec(name);
+    if (m !== null && m[1] === "add" && alive(Number(m[2])))
+      continue;
+    if (m === null && parseArchiveTag2(name) === null)
+      continue;
+    const path = join5(local, name);
+    try {
+      rmSync5(path, { recursive: true, force: true });
+      gone.push(path);
+    } catch {}
+  }
+  return gone;
+}
+
+import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
+import { join as join6 } from "path";
 var LATEST_CHECK_MS2 = 60 * 60 * 1000;
 var LATEST_CHECK_BUDGET_MS2 = 1500;
-var latestCheckPath2 = (root) => join5(root, "LATEST.json");
+var latestCheckPath2 = (root) => join6(root, "LATEST.json");
 function readLatestCheck2(root) {
   const p = latestCheckPath2(root);
-  if (!existsSync6(p))
+  if (!existsSync7(p))
     return null;
   try {
-    const v = JSON.parse(readFileSync5(p, "utf8"));
+    const v = JSON.parse(readFileSync6(p, "utf8"));
     if (typeof v.repo !== "string" || typeof v.checkedAt !== "string")
       return null;
     return {
@@ -4035,4 +4232,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, LOCAL_DIR2, localRoot2, newerThan2, incomplete2, releaseVersion2, pickBuild2, buildTag2, lacks, openBuild2, sweepBuilds2, LATEST_CHECK_MS2, LATEST_CHECK_BUDGET_MS2, latestCheckPath2, readLatestCheck2, latestCheck2, within, staleWarning2 };

package/dist/cli.js

@@ -6,26 +6,39 @@ import {
 } from "./chunks/index-hne1wadw.js";
 import {
   nameOrderOf,
+  defaultBuilders2,
+  readPin2,
   defaultRemote,
   openRelease2,
+  openCached2,
   releases2,
+  releaseVersion2,
+  pickBuild2,
+  lacks,
+  openBuild2,
+  sweepBuilds2,
   LATEST_CHECK_BUDGET_MS2,
   latestCheck2,
   within,
   staleWarning2
-} from "./chunks/index-pfsxe80h.js";
+} from "./chunks/index-vsk6837c.js";
 import"./chunks/index-hghdy980.js";
 
-var USAGE = `usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json]
+var USAGE = `usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json] [--live]
 
   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 +50,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>]
@@ -114,6 +127,10 @@ var USAGE = `usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json]
   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.
 
+  Where the caller names local builds (a wrapper's option), a query with no --release answers
+  from the newest COMPLETE build newer than the pinned release, and says so in one line on
+  stderr; --release <spec> names a release, and --live forces the pinned one.
+
   <spec>: pinned (the default) | latest | a cut (42, 42.1) | a tag (archive-YYYY.MM.DD-N)`;
 var VALUE = new Set([
   "--cache",
@@ -177,6 +194,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)" : ""}`);
@@ -441,6 +461,10 @@ var ANSWERING = new Set([
   "syllabus",
   "resolve"
 ]);
+var VERB_INDEXES = {
+  teams: ["teams"],
+  events: ["events"]
+};
 async function main(argv, io = {}) {
   const say = io.say ?? ((s) => console.log(s));
   const log = io.log ?? ((s) => console.error(s));
@@ -463,9 +487,43 @@ 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 answered = { tag: null, build: null };
+  const local = io.local === undefined || io.local === false || p.flags.has("--release") || p.bools.has("--live") || verb === undefined || verb === "current" || !ANSWERING.has(verb) ? null : io.local;
+  const fromBuild = async (o) => {
+    if (local === null)
+      return null;
+    const root = cacheRoot2(o);
+    const builds = local.builds();
+    const pin = readPin2(root);
+    const baseTag = pin?.tag ?? m.cachedTags()[0] ?? null;
+    const baseRel = baseTag === null ? null : openCached2(baseTag, o);
+    const base = baseTag === null ? null : releaseVersion2(baseRel ?? { tag: baseTag, manifest: {} });
+    baseRel?.close();
+    const picked = builds.length === 0 ? null : pickBuild2(builds, base);
+    if (picked === null) {
+      sweepBuilds2(root, null);
+      return null;
+    }
+    const known = o.builders ?? defaultBuilders2();
+    const inputs = (VERB_INDEXES[verb] ?? []).flatMap((n) => known.find((x) => x.name === n)?.inputs ?? []);
+    const missing = lacks(picked.build, picked.manifest, inputs);
+    if (missing.length > 0) {
+      log(`${picked.build.label} (unpublished, ${picked.build.dir}) carries no ${missing.join(", ")}: answered from the published release`);
+      return null;
+    }
+    let rel;
+    try {
+      rel = await openBuild2(root, picked, o);
+    } catch (e) {
+      log(`${picked.build.label} (unpublished, ${picked.build.dir}) could not be read (${e.message}): answered from the published release`);
+      return null;
+    }
+    sweepBuilds2(root, rel.tag);
+    answered.build = picked;
+    return rel;
+  };
   const open = async (s, o) => {
-    const rel = await openRelease2(s, o);
+    const rel = await fromBuild(o) ?? await openRelease2(s, o);
     answered.tag = rel.tag;
     return rel;
   };
@@ -488,12 +546,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 +596,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": {
@@ -998,12 +1065,15 @@ async function main(argv, io = {}) {
     log(`idq ${verb}: ${e.message}`);
     return 1;
   } finally {
+    const b = answered.build;
+    if (b !== null)
+      log(`answered from ${b.build.label} (unpublished, ${b.build.dir}). Pass --release <tag> for a published one, or --live for the pin.`);
     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);
+        log(b === null ? w : w.replace(`answered from ${answered.tag}.`, `answered from ${b.build.label}.`));
     }
   }
 }

package/dist/index.js

@@ -50,15 +50,25 @@ import {
   Release2,
   openRelease2,
   openCached2,
+  DEFAULT_KEEP2,
   ReleaseManager2,
   releases2,
+  LOCAL_DIR2,
+  localRoot2,
+  newerThan2,
+  incomplete2,
+  releaseVersion2,
+  pickBuild2,
+  buildTag2,
+  openBuild2,
+  sweepBuilds2,
   LATEST_CHECK_MS2,
   LATEST_CHECK_BUDGET_MS2,
   latestCheckPath2,
   readLatestCheck2,
   latestCheck2,
   staleWarning2
-} from "./chunks/index-pfsxe80h.js";
+} from "./chunks/index-vsk6837c.js";
 import {
   cacheRoot2,
   repoOf2
@@ -77,6 +87,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,
@@ -85,6 +96,7 @@ export {
   LATEST_CHECK_BUDGET_MS2 as LATEST_CHECK_BUDGET_MS,
   LATEST_CHECK_MS2 as LATEST_CHECK_MS,
   LINEAGE_FILE2 as LINEAGE_FILE,
+  LOCAL_DIR2 as LOCAL_DIR,
   MajorsFinder2 as MajorsFinder,
   NAME_LEVELS2 as NAME_LEVELS,
   NO_CALENDAR2 as NO_CALENDAR,
@@ -96,6 +108,7 @@ export {
   StaffFinder2 as StaffFinder,
   TeamFinder2 as TeamFinder,
   buildIndex2 as buildIndex,
+  buildTag2 as buildTag,
   cacheRoot2 as cacheRoot,
   canonicalOf2 as canonicalOf,
   capabilityOf2 as capabilityOf,
@@ -109,6 +122,7 @@ export {
   fallbackRemote2 as fallbackRemote,
   ghRemote2 as ghRemote,
   httpsRemote2 as httpsRemote,
+  incomplete2 as incomplete,
   indexKey2 as indexKey,
   indexPath2 as indexPath,
   initialsOnly2 as initialsOnly,
@@ -117,12 +131,16 @@ export {
   latestCheckPath2 as latestCheckPath,
   linksOfLineage2 as linksOfLineage,
   listIndexes2 as listIndexes,
+  localRoot2 as localRoot,
   nameLevel2 as nameLevel,
   needsRelease2 as needsRelease,
+  newerThan2 as newerThan,
+  openBuild2 as openBuild,
   openCached2 as openCached,
   openRelease2 as openRelease,
   parseArchiveTag2 as parseArchiveTag,
   parseReleaseSpec2 as parseReleaseSpec,
+  pickBuild2 as pickBuild,
   pickTag2 as pickTag,
   planAsset2 as planAsset,
   readLatestCheck2 as readLatestCheck,
@@ -130,6 +148,7 @@ export {
   readPopulation2 as readPopulation,
   readsSpanishNames2 as readsSpanishNames,
   releaseSchoolGraph2 as releaseSchoolGraph,
+  releaseVersion2 as releaseVersion,
   releases2 as releases,
   renderArchiveTag2 as renderArchiveTag,
   repoOf2 as repoOf,
@@ -137,6 +156,7 @@ export {
   setRemote2 as setRemote,
   sha256File2 as sha256File,
   staleWarning2 as staleWarning,
+  sweepBuilds2 as sweepBuilds,
   syllabusSourceOf2 as syllabusSourceOf,
   unzstdTo2 as unzstdTo,
   youngest2 as youngest

package/dist/types/cli.d.ts

@@ -1,8 +1,9 @@
 #!/usr/bin/env bun
 import { type FreshnessFloor } from "./freshness.js";
+import { type LocalBuild } from "./local.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] [--live]\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  Where the caller names local builds (a wrapper's option), a query with no --release answers\n  from the newest COMPLETE build newer than the pinned release, and says so in one line on\n  stderr; --release <spec> names a release, and --live forces the pinned one.\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>;
@@ -18,6 +19,9 @@ 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 LocalIO {
+    builds: () => readonly LocalBuild[];
+}
 export interface FreshnessIO {
     floor?: FreshnessFloor | null;
     command?: string;
@@ -30,5 +34,6 @@ export declare function main(argv: readonly string[], io?: {
     opts?: OpenOptions;
     stdin?: () => Promise<string>;
     freshness?: FreshnessIO | false;
+    local?: LocalIO | 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/index.d.ts

@@ -7,7 +7,8 @@ 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 CutVersion, LOCAL_DIR, type LocalBuild, type PickedBuild, buildTag, incomplete, localRoot, newerThan, openBuild, pickBuild, releaseVersion, sweepBuilds, } from "./local.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/local.d.ts

@@ -0,0 +1,33 @@
+import { type ReleaseManifest } from "./assets.js";
+import { type OpenOptions, type Release } from "./release.js";
+import type { Remote } from "./remote.js";
+export interface LocalBuild {
+    dir: string;
+    label: string;
+    fraction?: number;
+}
+export interface CutVersion {
+    cut: number;
+    fraction: number;
+}
+export declare const LOCAL_DIR = "local";
+export declare const localRoot: (root: string) => string;
+export declare const newerThan: (a: CutVersion, b: CutVersion) => boolean;
+export declare function incomplete(dir: string): string | null;
+export declare function releaseVersion(rel: {
+    tag: string;
+    manifest: ReleaseManifest;
+}): CutVersion | null;
+export interface PickedBuild {
+    build: LocalBuild;
+    version: CutVersion;
+    manifest: ReleaseManifest;
+}
+export declare function pickBuild(builds: readonly LocalBuild[], base: CutVersion | null): PickedBuild | null;
+export declare function buildTag(p: PickedBuild): string;
+export declare function buildFiles(dir: string): string[];
+export declare function lacks(b: LocalBuild, manifest: ReleaseManifest, inputs: readonly string[]): string[];
+export declare function buildRemote(label: string): Remote;
+export declare function buildOptions(root: string, label: string, opts: OpenOptions): OpenOptions;
+export declare function openBuild(root: string, p: PickedBuild, opts: OpenOptions): Promise<Release>;
+export declare function sweepBuilds(root: string, keep: string | null): string[];

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.23.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",