@finbheara/archive-client 0.22.0 → 0.24.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
@@ -780,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-zwecpq08.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,
@@ -3966,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 {
@@ -4055,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, DEFAULT_KEEP2, 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,155 +6,397 @@ 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-zwecpq08.js";
+} from "./chunks/index-vsk6837c.js";
 import"./chunks/index-hghdy980.js";
 
-var USAGE = `usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json]
-
-  config repo <owner/name>          set the user-local repository the releases come from
-  config keep <N>                   how many of the newest releases a prune keeps (default 2)
-  list [--remote]                   the cached releases (size, files, indexes, the pin), and
-                                    with --remote the published tags
-  fetch [--release <spec>] [--assets results,majors,<file>...]
-                                    download, verify and cache a release (default: results)
-  update [--assets ...] [--keep N] [--no-prune]
-                                    move to the newest published release: fetch it (verified),
-                                    build its indexes, pin it, then prune the cache to the N
-                                    newest releases (default: config keep, else 2), keeping the
-                                    new pin and the one before it
-  use <spec> [--assets ...] [--keep N] [--no-prune]
-                                    the same for the release a spec names
-  pin <spec>                        the user-local pin: what a bare open (spec "pinned") opens
-  unpin                             remove the pin (a bare open is then "latest")
-  current                           the pin, and whether it is cached
-  add <dir> --tag <tag>             add a release built locally (its MANIFEST.json and files)
-                                    to the cache under its tag
-  index [--release <spec>] [<name>...] [--force]
-                                    build the per-tag indexes (default: every one)
-  verify [--release <spec>]         re-hash every cached file against its receipt
-  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:
-                                    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>]
-                                    the feises a query names
-  series [--release <spec>] <name|host code|feis id>
-                                    the series a name, a host code (fweb:ABC) or any feis id
-                                    names: its years, hosts, codes and next instance
-  school [--release <spec>] <print|school_id> [--region <code>]
-                                    a school print or id to the published schools
-  dancer [--release <spec>] <name> | --surname <s> | --like <glob> | --id <dancer_id>
-         [--order surname-first|given-first] [--school <print|id>]
-         [--yob <y> | --band <U10> [--year <y>] | --comp <competition>] [--as-of <date>]
-         [--population girls|boys] [--oireachtas <region>[:<year>]] [--rows]
-                                    the dancers a name reaches, each with its evidence
-                                    (name level, age, school, population, region) and the arm;
-                                    --oireachtas is the regional the roster is for, its region in
-                                    the release's spelling (SRO, MAO), its year the --as-of year
-                                    where none is given; the results of
-                                    the one dancer where one answers (or --rows for each)
-  results [--release <spec>] [--dancer <id>] [--feis <id>] [--comp <competition>]
-          [--school <print|id>] [--year <y>] [--limit <n>]
-                                    the published result rows, prints and ids
-  majors [--release <spec>] [--event <e>] [--year <y>] [--comp <competition>] [--dancer <id>]
-                                    the majors: every event and its years; an event's
-                                    competitions; a competition's, an event's or a dancer's rows
-  stream [--release <spec>] --scope majors|transcribed|platform|all [--entries] [--event <e,...>]
-         [--year <y> | --year <from>..<to>] [--tier <t,...>] [--category <c,...>]
-         [--level <feis_level,...>] [--dancer <id,...>] [--school <school_id>] [--primary]
-                                    every row a scope holds, one JSON line each, never the
-                                    whole table in memory; --entries one per address (the row
-                                    it stands for, with its recall order)
-  records [--release <spec>] [--dancer <id,...>]
-                                    every dancer's record: display, appearances, birth window,
-                                    populations
-  records --years [--release <spec>] [--dancer <id,...>] [--year <y>]
-                                    each dancer's region, nationals and place per year
-  feis-dates [--release <spec>]     every feis's first and last day
-  tabulated [--release <spec>] [--min-round <n>]
-                                    the majors addresses the marks sheets tabulate to round n
-                                    or later (default 3)
-  teams [--release <spec>] [--event <e>] [--year <y>] [--rosters | --joins]
-                                    the team result rows of an event-year; with --rosters its
-                                    roster teams and their dancers; with --joins how each roster
-                                    team meets the results
-  events [--release <spec>] [--event <e>] [--year <y>]
-                                    each event-year's dates and place
-  teacher [--release <spec>] <name|TD number>
-                                    the staff lists' people: where they taught, the register,
-                                    where they sat
-  adjudicator [--release <spec>] <name|TD number>
-                                    the register's and the panels' people: the same answer
-  comp [--release <spec>] <feis> <code> [--year <y>] [--title <t>]
-                                    a feis's own comp code to the comp it names, through that
-                                    feis's syllabus (the prior year's only where the platform
-                                    numbers every feis alike; elsewhere the title)
-  syllabus [--release <spec>] <feis> [year]
-                                    one feis-year's comps, in printed order
-  syllabus [--release <spec>] --for <series> [year]
-                                    a series' syllabus for a year: that year's where held,
-                                    else the newest, saying which and what it is read from
-  resolve comp [<feis> <code>] [--year <y>] [--title <t>]
-  resolve dancer [<name>] [--school <s>] [--comp <feis>/<code> | --yob <y> | --band <b> --year <y>]
-                 [--order <o>] [--as-of <date>] [--population girls|boys]
-                 [--oireachtas <region>[:<year>]]
-  resolve registrations
-                                    JSONL out, one answer per line; with no positional the
-                                    questions are JSONL on stdin, one per line (a comp:
-                                    {feis, code, year?, title?}, a dancer: {name, school?, age?,
-                                    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.
+var USAGE_HEADER = "usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json] [--live]";
+var GLOBAL_FLAGS = {
+  value: ["--cache", "--repo"],
+  bool: ["--json", "--live"]
+};
+var VERBS = [
+  {
+    verb: "config",
+    value: [],
+    bool: [],
+    usage: [
+      "  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)"
+    ]
+  },
+  {
+    verb: "list",
+    value: [],
+    bool: ["--remote"],
+    usage: [
+      "  list [--remote]                   the cached releases (size, files, indexes, the pin), and",
+      "                                    with --remote the published tags"
+    ]
+  },
+  {
+    verb: "fetch",
+    value: ["--release", "--assets"],
+    bool: [],
+    usage: [
+      "  fetch [--release <spec>] [--assets results,majors,<file>...]",
+      "                                    download, verify and cache a release (default: results)"
+    ]
+  },
+  {
+    verb: "update",
+    value: ["--assets", "--keep"],
+    bool: ["--no-prune"],
+    usage: [
+      "  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"
+    ]
+  },
+  {
+    verb: "use",
+    value: ["--assets", "--keep"],
+    bool: ["--no-prune"],
+    usage: [
+      "  use <spec> [--assets ...] [--keep N] [--no-prune]",
+      "                                    the same for the release a spec names"
+    ]
+  },
+  {
+    verb: "pin",
+    value: [],
+    bool: [],
+    usage: [
+      '  pin <spec>                        the user-local pin: what a bare open (spec "pinned") opens'
+    ]
+  },
+  {
+    verb: "unpin",
+    value: [],
+    bool: [],
+    usage: ['  unpin                             remove the pin (a bare open is then "latest")']
+  },
+  {
+    verb: "current",
+    value: [],
+    bool: [],
+    usage: ["  current                           the pin, and whether it is cached"]
+  },
+  {
+    verb: "add",
+    value: ["--tag"],
+    bool: [],
+    usage: [
+      "  add <dir> --tag <tag>             add a release built locally (its MANIFEST.json and files)",
+      "                                    to the cache under its tag"
+    ]
+  },
+  {
+    verb: "index",
+    value: ["--release"],
+    bool: ["--force"],
+    usage: [
+      "  index [--release <spec>] [<name>...] [--force]",
+      "                                    build the per-tag indexes (default: every one)"
+    ]
+  },
+  {
+    verb: "verify",
+    value: ["--release"],
+    bool: [],
+    usage: ["  verify [--release <spec>]         re-hash every cached file against its receipt"]
+  },
+  {
+    verb: "capabilities",
+    value: ["--release"],
+    bool: [],
+    usage: [
+      "  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)"
+    ]
+  },
+  {
+    verb: "prune",
+    value: ["--keep"],
+    bool: ["--dry-run"],
+    usage: [
+      "  prune [--keep N] [--dry-run]      remove all but the N newest cached releases (default:",
+      "                                    config keep, else 2) and the pinned one"
+    ]
+  },
+  {
+    verb: "rm",
+    value: [],
+    bool: ["--dry-run"],
+    usage: ["  rm <tag> [--dry-run]              remove one cached release (not the pinned one)"]
+  },
+  {
+    verb: "drop-indexes",
+    value: [],
+    bool: ["--dry-run"],
+    usage: [
+      "  drop-indexes [<tag>] [--dry-run]  remove the index files (of one release, or of every one)"
+    ]
+  },
+  {
+    verb: "feis",
+    value: ["--release", "--platform", "--code", "--id", "--name", "--year"],
+    bool: [],
+    usage: [
+      "  feis [--release <spec>] [--platform <p>] [--code <c>] [--id <id>] [--name <glob>] [--year <y>]",
+      "                                    the feises a query names"
+    ]
+  },
+  {
+    verb: "series",
+    value: ["--release"],
+    bool: [],
+    usage: [
+      "  series [--release <spec>] <name|host code|feis id>",
+      "                                    the series a name, a host code (fweb:ABC) or any feis id",
+      "                                    names: its years, hosts, codes and next instance"
+    ]
+  },
+  {
+    verb: "school",
+    value: ["--release", "--region"],
+    bool: [],
+    usage: [
+      "  school [--release <spec>] <print|school_id> [--region <code>]",
+      "                                    a school print or id to the published schools"
+    ]
+  },
+  {
+    verb: "dancer",
+    value: [
+      "--release",
+      "--surname",
+      "--like",
+      "--id",
+      "--order",
+      "--school",
+      "--yob",
+      "--band",
+      "--year",
+      "--comp",
+      "--as-of",
+      "--population",
+      "--oireachtas"
+    ],
+    bool: ["--rows"],
+    usage: [
+      "  dancer [--release <spec>] <name> | --surname <s> | --like <glob> | --id <dancer_id>",
+      "         [--order surname-first|given-first] [--school <print|id>]",
+      "         [--yob <y> | --band <U10> [--year <y>] | --comp <competition>] [--as-of <date>]",
+      "         [--population girls|boys] [--oireachtas <region>[:<year>]] [--rows]",
+      "                                    the dancers a name reaches, each with its evidence",
+      "                                    (name level, age, school, population, region) and the arm;",
+      "                                    --oireachtas is the regional the roster is for, its region in",
+      "                                    the release's spelling (SRO, MAO), its year the --as-of year",
+      "                                    where none is given; the results of",
+      "                                    the one dancer where one answers (or --rows for each)"
+    ]
+  },
+  {
+    verb: "results",
+    value: ["--release", "--dancer", "--feis", "--comp", "--school", "--year", "--limit"],
+    bool: [],
+    usage: [
+      "  results [--release <spec>] [--dancer <id>] [--feis <id>] [--comp <competition>]",
+      "          [--school <print|id>] [--year <y>] [--limit <n>]",
+      "                                    the published result rows, prints and ids"
+    ]
+  },
+  {
+    verb: "majors",
+    value: ["--release", "--event", "--year", "--comp", "--dancer"],
+    bool: [],
+    usage: [
+      "  majors [--release <spec>] [--event <e>] [--year <y>] [--comp <competition>] [--dancer <id>]",
+      "                                    the majors: every event and its years; an event's",
+      "                                    competitions; a competition's, an event's or a dancer's rows"
+    ]
+  },
+  {
+    verb: "stream",
+    value: [
+      "--release",
+      "--scope",
+      "--event",
+      "--year",
+      "--tier",
+      "--category",
+      "--level",
+      "--dancer",
+      "--school"
+    ],
+    bool: ["--entries", "--primary"],
+    usage: [
+      "  stream [--release <spec>] --scope majors|transcribed|platform|all [--entries] [--event <e,...>]",
+      "         [--year <y> | --year <from>..<to>] [--tier <t,...>] [--category <c,...>]",
+      "         [--level <feis_level,...>] [--dancer <id,...>] [--school <school_id>] [--primary]",
+      "                                    every row a scope holds, one JSON line each, never the",
+      "                                    whole table in memory; --entries one per address (the row",
+      "                                    it stands for, with its recall order)"
+    ]
+  },
+  {
+    verb: "records",
+    value: ["--release", "--dancer", "--year"],
+    bool: ["--years"],
+    usage: [
+      "  records [--release <spec>] [--dancer <id,...>]",
+      "                                    every dancer's record: display, appearances, birth window,",
+      "                                    populations",
+      "  records --years [--release <spec>] [--dancer <id,...>] [--year <y>]",
+      "                                    each dancer's region, nationals and place per year"
+    ]
+  },
+  {
+    verb: "feis-dates",
+    value: ["--release"],
+    bool: [],
+    usage: ["  feis-dates [--release <spec>]     every feis's first and last day"]
+  },
+  {
+    verb: "tabulated",
+    value: ["--release", "--min-round"],
+    bool: [],
+    usage: [
+      "  tabulated [--release <spec>] [--min-round <n>]",
+      "                                    the majors addresses the marks sheets tabulate to round n",
+      "                                    or later (default 3)"
+    ]
+  },
+  {
+    verb: "teams",
+    value: ["--release", "--event", "--year"],
+    bool: ["--rosters", "--joins"],
+    usage: [
+      "  teams [--release <spec>] [--event <e>] [--year <y>] [--rosters | --joins]",
+      "                                    the team result rows of an event-year; with --rosters its",
+      "                                    roster teams and their dancers; with --joins how each roster",
+      "                                    team meets the results"
+    ]
+  },
+  {
+    verb: "events",
+    value: ["--release", "--event", "--year"],
+    bool: [],
+    usage: [
+      "  events [--release <spec>] [--event <e>] [--year <y>]",
+      "                                    each event-year's dates and place"
+    ]
+  },
+  {
+    verb: "teacher",
+    value: ["--release"],
+    bool: [],
+    usage: [
+      "  teacher [--release <spec>] <name|TD number>",
+      "                                    the staff lists' people: where they taught, the register,",
+      "                                    where they sat"
+    ]
+  },
+  {
+    verb: "adjudicator",
+    value: ["--release"],
+    bool: [],
+    usage: [
+      "  adjudicator [--release <spec>] <name|TD number>",
+      "                                    the register's and the panels' people: the same answer"
+    ]
+  },
+  {
+    verb: "comp",
+    value: ["--release", "--year", "--title"],
+    bool: [],
+    usage: [
+      "  comp [--release <spec>] <feis> <code> [--year <y>] [--title <t>]",
+      "                                    a feis's own comp code to the comp it names, through that",
+      "                                    feis's syllabus (the prior year's only where the platform",
+      "                                    numbers every feis alike; elsewhere the title)"
+    ]
+  },
+  {
+    verb: "syllabus",
+    value: ["--release", "--for"],
+    bool: [],
+    usage: [
+      "  syllabus [--release <spec>] <feis> [year]",
+      "                                    one feis-year's comps, in printed order",
+      "  syllabus [--release <spec>] --for <series> [year]",
+      "                                    a series' syllabus for a year: that year's where held,",
+      "                                    else the newest, saying which and what it is read from"
+    ]
+  },
+  {
+    verb: "resolve",
+    value: [
+      "--year",
+      "--title",
+      "--school",
+      "--comp",
+      "--yob",
+      "--band",
+      "--order",
+      "--as-of",
+      "--population",
+      "--oireachtas"
+    ],
+    bool: [],
+    usage: [
+      "  resolve comp [<feis> <code>] [--year <y>] [--title <t>]",
+      "  resolve dancer [<name>] [--school <s>] [--comp <feis>/<code> | --yob <y> | --band <b> --year <y>]",
+      "                 [--order <o>] [--as-of <date>] [--population girls|boys]",
+      "                 [--oireachtas <region>[:<year>]]",
+      "  resolve registrations",
+      "                                    JSONL out, one answer per line; with no positional the",
+      "                                    questions are JSONL on stdin, one per line (a comp:",
+      "                                    {feis, code, year?, title?}, a dancer: {name, school?, age?,",
+      "                                    population?, oireachtas?}, a registration: {name, school?,",
+      "                                    codes[], feis, year?, population?, oireachtas?})"
+    ]
+  }
+];
+var USAGE_FOOTER = [
+  "  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.",
+  "",
+  "  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)"
+];
+function renderUsage() {
+  return [USAGE_HEADER, "", ...VERBS.flatMap((v) => v.usage), "", ...USAGE_FOOTER].join(`
+`);
+}
+function valueFlags() {
+  return new Set([...GLOBAL_FLAGS.value, ...VERBS.flatMap((v) => v.value)]);
+}
 
-  <spec>: pinned (the default) | latest | a cut (42, 42.1) | a tag (archive-YYYY.MM.DD-N)`;
-var VALUE = new Set([
-  "--cache",
-  "--repo",
-  "--release",
-  "--assets",
-  "--tag",
-  "--keep",
-  "--platform",
-  "--code",
-  "--id",
-  "--name",
-  "--year",
-  "--region",
-  "--order",
-  "--surname",
-  "--like",
-  "--school",
-  "--yob",
-  "--band",
-  "--comp",
-  "--as-of",
-  "--population",
-  "--oireachtas",
-  "--dancer",
-  "--feis",
-  "--limit",
-  "--event",
-  "--title",
-  "--for",
-  "--scope",
-  "--tier",
-  "--category",
-  "--level",
-  "--min-round"
-]);
+var USAGE = renderUsage();
+var VALUE = valueFlags();
 function parseArgs(argv) {
   const positional = [];
   const flags = new Map;
@@ -449,6 +691,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));
@@ -471,9 +717,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;
   };
@@ -1015,21 +1295,30 @@ 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}.`));
     }
   }
 }
 if (import.meta.main)
   process.exit(await main(process.argv.slice(2)));
 export {
+  GLOBAL_FLAGS,
   USAGE,
+  USAGE_FOOTER,
+  USAGE_HEADER,
+  VERBS,
   jsonLines,
   main,
   parseArgs,
-  streamQueryOf
+  renderUsage,
+  streamQueryOf,
+  valueFlags
 };

package/dist/index.js

@@ -53,13 +53,22 @@ import {
   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-zwecpq08.js";
+} from "./chunks/index-vsk6837c.js";
 import {
   cacheRoot2,
   repoOf2
@@ -87,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,
@@ -98,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,
@@ -111,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,
@@ -119,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,
@@ -132,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,
@@ -139,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-spec.d.ts

@@ -0,0 +1,15 @@
+export interface VerbSpec {
+    verb: string;
+    value: readonly string[];
+    bool: readonly string[];
+    usage: readonly string[];
+}
+export declare const USAGE_HEADER = "usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json] [--live]";
+export declare const GLOBAL_FLAGS: {
+    value: readonly string[];
+    bool: readonly string[];
+};
+export declare const VERBS: readonly VerbSpec[];
+export declare const USAGE_FOOTER: readonly string[];
+export declare function renderUsage(): string;
+export declare function valueFlags(): Set<string>;

package/dist/types/cli.d.ts

@@ -1,8 +1,10 @@
 #!/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  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 { GLOBAL_FLAGS, USAGE_FOOTER, USAGE_HEADER, VERBS, type VerbSpec, renderUsage, valueFlags, } from "./cli-spec.js";
+export declare const USAGE: string;
 export interface Parsed {
     positional: string[];
     flags: Map<string, string>;
@@ -18,6 +20,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 +35,5 @@ 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/index.d.ts

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

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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/archive-client",
-	"version": "0.22.0",
+	"version": "0.24.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",