@finbheara/archive-client 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Finbheara Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,359 @@
-# Temporary Holding Version
+# @finbheara/archive-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Open a versioned release of an Irish dance results dataset and work with it locally: download,
+verify, decompress and cache it by tag, keep a user-local cache of releases, and resolve feises,
+schools, competitions, registration lists, dancers, results, majors, teachers and
+adjudicators against one. A command line, `idq`, is a thin wrapper over the same calls.
+
+Bun 1.4.2 or later (the databases open through `bun:sqlite`). MIT.
+
+## Install
+
+```sh
+bun add @finbheara/archive-client
+```
+
+Bun only: the databases open through `bun:sqlite`. The package ships built JavaScript and its
+type declarations (`.d.ts`), so a TypeScript project needs Bun's types (`"types": ["bun"]` or
+`["bun-types"]`) and nothing else from the client: no `allowImportingTsExtensions`, no
+`preserveSymlinks`. The `idq` command line comes with it: in a project that installed it,
+`bunx idq <verb>`.
+
+The version is 0.x while the API settles: a minor bump may break, so pin a minor
+(`"@finbheara/archive-client": "0.1.x"`).
+
+## Configuration
+
+The package carries no data and names no releases repository: it reads releases from a
+repository you name, your own.
+
+| what | option | environment | user-local |
+| --- | --- | --- | --- |
+| the releases repository (`owner/name`) | `repo` | `ARCHIVE_CLIENT_REPO` | `idq config repo <owner/name>` |
+| the cache root | `cache` | `ARCHIVE_CLIENT_CACHE` | |
+
+The option wins over the environment, the environment over the user-local config. With no
+repository, a call that needs the network refuses by name. With no cache set, the cache is
+`archive-client` in your home cache directory.
+
+A private releases repository needs credentials: `gh` logged in to an account that can read it,
+or `GITHUB_TOKEN` (or `GH_TOKEN`) holding a token that can.
+
+## Where the releases come from
+
+A release is a GitHub release of some repository: a `MANIFEST.json`, the databases
+(`results.sqlite.zst`, `majors.sqlite.zst`) and the side files (jsonl, parquet). The package names
+no repository. Give one, in order of precedence:
+
+- the `repo` option (`owner/name`)
+- the `ARCHIVE_CLIENT_REPO` environment variable
+- the user-local config: `idq config repo <owner/name>`
+
+`gh` is used first (it reads your own login), and the public API over HTTPS where `gh` is missing
+or fails (`GITHUB_TOKEN` or `GH_TOKEN` as a bearer token, needed where the repository is not public).
+
+## Open a release
+
+```ts
+import { openRelease } from "@finbheara/archive-client";
+
+const rel = await openRelease("latest", { assets: ["results", "majors"] });
+rel.tag;       // the release tag
+rel.cut;       // the cut number the tag carries
+rel.manifest;  // its MANIFEST.json
+rel.db("results").query("SELECT count(*) AS n FROM results").get();  // read-only handle
+await rel.fetch("school-registry.jsonl");                            // any other asset, on demand
+rel.path("school-registry.jsonl");                                   // its cached file
+rel.close();
+```
+
+A spec is `pinned` (the default: the user-local pin, else the latest), `latest`, a cut number
+(`42`, or `42.1` for a fraction) or a tag (`archive-YYYY.MM.DD-N`).
+
+EVERY FILE IS CHECKED before it lands: the downloaded bytes against the host's own sha256 digest,
+and the content against the manifest (a database's decompressed bytes against
+`databases.<name>.sha256`, a parquet file against `parquet.files[<name>].sha256`). A mismatch
+refuses and leaves nothing in place. A file nothing vouches for is kept and its receipt says so
+(`strict: true` refuses it). A database is decompressed in process, streamed, never through a
+`zstd` binary.
+
+## The cache
+
+One directory per tag under the cache root: the `cache` option, else `ARCHIVE_CLIENT_CACHE`,
+else `archive-client` in your home cache directory.
+
+    <root>/<tag>/MANIFEST.json
+    <root>/<tag>/results.sqlite          decompressed, verified
+    <root>/<tag>/<asset>                 any other file, as published
+    <root>/<tag>/.client.json            the receipt: every file's sha256 and what verified it
+    <root>/<tag>/index/<name>.sqlite     the per-tag indexes
+    <root>/PINNED.json                   the user-local pin
+    <root>/config.json                   the user-local config
+
+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
+verified file is never fetched twice.
+
+## The release manager
+
+```ts
+import { releases } from "@finbheara/archive-client";
+
+const m = releases();
+await m.list({ remote: true });           // cached releases, sizes, files, indexes, the pin
+await m.fetch("latest", { assets: ["results"] });
+await m.pin("42");                        // a bare openRelease() now opens it
+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
+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.
+
+## The indexes
+
+The release databases carry a primary key per table and nothing more, so lookups build side
+indexes, one SQLite file per index per tag, each keyed on its builder's version and the sha256 of
+every input it read. A file whose key is stale is rebuilt, never served. Four ship here, and a
+caller may hand its own (`builders` option, an `IndexBuilder`):
+
+- `schools`: every published school print with the ids its rows carry, filed into a
+  `@finbheara/domain` `schoolEncoder` noun index, with the registry and the retired ids
+- `feises`: every feis by id, platform, host code, series and name, with its competition and
+  result counts and the regions its competitions read
+- `dancers` (keyed on the names and domain package versions too): every published dancer print at the names package's keys (one row per print and
+  reading, a `@finbheara/domain` `personEncoder` noun index), the dancers each print was
+  published under, each dancer's schools and years
+- `staff` (keyed the same way): teachers and adjudicators by name (a `roleEncoder` noun index) and TD number: the
+  schools' staff lists and TD links, the adjudicator register, and the seats each sat
+- `comps`: every competition by its feis and the feis's own code, with its series and year
+
+## Feises
+
+```ts
+await rel.feises.find({ platform: "feisweb", code: "ABC24" });  // a source or its id token
+await rel.feises.find({ id: "<feis, series instance or brand id>" });  // a retired id followed
+await rel.feises.find({ name: "*Spring*", year: 2024 });
+```
+
+One answer per feis id: dates, location, series ids, regions, and how many competitions, rows
+and captures it has.
+
+```ts
+const s = await rel.feises.series("Ardvarna Spring");  // a name, a host code ("fweb:ABC", "fweb:ABC26"), any feis id
+s.arm;        // "unique" | "ambiguous" | "none"
+s.series_id;  // the series, with s.name, s.host ("feisweb"), s.years, s.instances
+s.next;       // the next scheduled instance where the release knows one, else null with s.next_why
+```
+
+A series is asked by any id of it (a feis, instance or brand id, a retired one followed), by a
+host code with or without its year (held codes `<stem><yy>` whose two digits are their own year),
+or by a name (a glob, or a plain word read as `*word*`). Two series answer `ambiguous` with both.
+A release holds a feis-year once its results are captured and carries no calendar, so `next` is
+`null` today, with the reason.
+
+## Schools
+
+```ts
+const a = await rel.schools.resolve("Ardvarna Academy of Irish Dance (Calgary, AB)", { region: "WCRO" });
+a.arm;          // "unique" | "ambiguous" | "none"
+a.candidates;   // [{ school_id, display, rows, by, prints, regions, places }]
+```
+
+The rungs, the first that answers wins: a school id, a retired id followed to the live one, the
+print exactly as the release published it, then the print read by `@finbheara/domain`'s school
+reader at its filing key (`sn3`) and at its real words. `ambiguous` and `none` are answers: a
+best guess is never promoted to `unique`. `region` drops only a candidate the registry places in
+other regions, and keeps one it places nowhere. A print the reader refuses (a placeholder)
+answers `none` with the reason.
+
+Every answer carries the release tag it came from.
+
+## Dancers
+
+```ts
+const r = await rel.dancers.resolve({
+  name: "Quellan, A", order: "surname-first",     // initials and partial given names are first-class
+  school: "Ardvarna Academy",                      // a print or an id, through rel.schools
+  age: { band: "U10", year: 2026 },                // or { yob: 2016 }, or { comp: "<competition>" }
+  asOf: "2026-10-17",                              // the school as of then
+});
+r.arm;         // "unique" | "ambiguous" | "none"
+r.candidates;  // [{ dancer_id, display, scope, score, evidence: { nameLevel, age, school }, prints, ... }]
+r.excluded;    // the candidates an age contradiction set aside (why: "age")
+r.preferred;   // NON-BINDING: { dancer_id, why } where the school singles one out; never moves arm
+r.unlinked;    // rows printing a matched name that the release linked to no dancer
+
+await rel.dancers.search({ surname: "Quellan" });  // or { like: "a* quellan" }, or { name }
+await rel.dancers.get(1001);                        // every print and school of one dancer
+```
+
+NO NEW MATCHER. A print is read in the dancer's role by `@finbheara/domain` over
+`@finbheara/names`, and a candidate's `nameLevel` is the finest of: `nn0` to `nn4` (equal at that
+level of the names package: the print, the key, the folded key, the tokens in any order),
+`initial` (one surname, one given name the other's made poorer: `givenAbbreviates`), `middle`
+(a middle name one print omits: `nameRelation`). `age` is how the dancer's published birth window
+meets the asked age (`Age.fitsIn`, `overlaps`): `fits`, `overlaps`, `contradicts`, `unknown`.
+`school` is how the dancer's schools meet the asked one: `same` (the latest school as of `asOf`),
+`moved` (an earlier one), `none`, `unresolved` (the print reached no school).
+
+NO SILENT GUESS. Only a contradiction sets a candidate aside: a birth window that shares no birth
+year with the asked age (listed in `excluded`). The school is evidence and order, never a reason
+to drop anyone: candidates whose latest school is the asked one come first, then those that ever
+danced for it, then the rest. A school row meets the asked school by its id, else by its print
+(one `rel.schools` resolves to the asked ids), so a latest print the release
+filed under no id is still `same`. `unique` is one candidate left after the age, never a best
+guess promoted. Where the school singles out one candidate, `preferred` names it with the reason,
+for a caller to weigh, and `arm` stays as counted. The `score` orders candidates and is no
+probability.
+
+A FEIS-LOCAL ID (`FEIS_LOCAL_ID_FLOOR`, 2^34, and up) is valid in its release only: a candidate and a result row
+carrying one say `scope: "per-release"` (`dancer_scope` on a row), so a caller never stores one
+across releases. Every answer carries the release tag.
+
+## Results and the majors
+
+```ts
+await rel.results.query({ dancer_id: 1001 });        // a dancer's rows, oldest first
+await rel.results.query({ feis: "<feis id>", year: 2025 });
+await rel.results.query({ competition: "<competition>" });
+await rel.results.query({ school_id: "<school id>", year: 2025, limit: 100 });
+await rel.majors.events();                            // every major and its years
+await rel.majors.competitions({ event: "<event>", year: 2023 });
+await rel.majors.results({ dancer_id: 1001 });       // a dancer's majors
+```
+
+A row carries the prints and the ids that stand for them: the address, the competition's title
+and age, the place, the name and school as printed with the dancer and school ids. The majors are
+read from `majors.sqlite`, fetched on first use.
+
+## Teachers and adjudicators
+
+```ts
+await rel.staff.teacher("<name>");        // or a TD number
+await rel.staff.adjudicator("<name>");
+```
+
+One person per TD number (else per judge id, else per name): the schools taught at (role,
+credentials, years), the schools that list the TD number, the adjudicator register by year, and
+the seats sat, per event and year, at majors and at feiseanna.
+## Competitions
+
+```ts
+const c = await rel.comps.resolve({ feis: "fweb:ABC26", code: "610" });
+c.arm;        // "unique" | "ambiguous" | "none"
+c.source;     // "syllabus" | "prior-year" | "title"
+c.kind;       // "championship" | "grade" | "unrated"
+c.level;      // "OC" (FF, BG, AB, NV, PW, PC, OC), c.feis_level 700
+c.age;        // "U10", c.population "mixed", c.canonical "710OC", c.title, c.competition
+c.from;       // { feis_ids: ["fweb:ABC25"], year: 2025 } where an earlier year answered
+c.check;      // "unchecked", or what the caller's `title` says about the earlier comp
+c.syllabus_source;  // "results": what the syllabus the answer read is read from
+await rel.comps.syllabus("fweb:ABC25");   // one feis-year's competitions, in printed order
+const syl = await rel.comps.syllabusFor("Ardvarna Spring", 2026);  // or a `feises.series` answer
+syl.year;     // the asked year where the release holds it, else its newest (syl.held, syl.why)
+syl.source;   // "results" (a syllabus document is a source of its own name, shipped by no release yet)
+syl.entries;  // the comps, syl.championships how many are championships, syl.note where none
+```
+
+EVERY SYLLABUS SAYS WHAT IT IS READ FROM. Today that is the comps the release's result captures
+list (`results`): a comp the feis held whose results the platform did not tabulate is not in it.
+A feis whose platform tabulated its grades only has a syllabus with no championship, and
+`syllabusFor` says so (`note`), as does a `none` answer of `resolve` on such a series.
+
+A code is matched trimmed and case folded (`412a` finds `412A`). A code is the feis's own: FeisWeb, FeisWorx and a local QuickFeis number their competitions as
+the host likes, so a code is answered from that feis's competitions in the release, never from
+another platform's numbering. The sources, in order:
+
+- `syllabus`: the feis-year is in the release, and one of its competitions prints the code
+- `prior-year`: the feis-year is not (next year's, before its results): the newest earlier year
+  of the same series printing the code. Give the comp's `title` and `matchTitle` checks it
+  against the earlier comp (`check`), and with no title the answer says `unchecked`
+- `title`: the code answers nothing and a `title` was given: the competitions of that syllabus
+  the title names, by band and population
+
+A feis the release holds names itself, its year and its series. A series instance or brand id
+names the series. A feis id the release does not hold is placed in a series by its host code
+(`<token>:<stem><yy>` where the held codes of that stem carry their own year), and a stem two
+series share answers `ambiguous`. A held feis-year never falls back to an earlier year, and two
+competitions printing one code are never folded into one.
+
+`kind` and `level` are read off the release's published rung (`feis_level`: 100 first feis to
+700 open championship): `championship` from 600, `grade` below, `unrated` where the release
+publishes none (specials, sets, adult and team events). No level word is read from a title, so
+a title alone names every comp of its band and population. `canonical` is a rendering of a
+championship in the QuickFeis shape, never a key: an `Under N` band prints `N` (`609PC`,
+`710OC`), and an `N & over` band prints `N + 1`, the slot after the oldest `Under` band, as
+QuickFeis numbers its own and-over championships (`15 & over` prelim `616PC`, `18 & over` open
+`719OC`). An and-over code is then the same string as an `Under N + 1` one, and `age` (`O18`)
+tells them apart. An adult band, a range and a grade render none.
+
+## Registrations
+
+```ts
+const rows = await rel.registrations.resolve([
+  { name: "Doe, J", school: "Ardvarna Academy", codes: ["610", "611"], feis: "fweb:ABC26" },
+]);
+rows[0].comps;    // one competition answer per code
+rows[0].age;      // { band: "U10", year: 2026, code: "610", from: "comp" }: the band the dancer is asked at
+rows[0].dancer;   // the dancer resolver's answer
+```
+
+Each code is resolved as above. The dancer is asked at the YOUNGEST band the row's competitions
+read (the lowest ceiling, then the highest floor): a dancer may dance up into an older band and
+never down, so the youngest bounds the dancer. Every band a row read is listed (`bands`) where
+there are several. Where no comp answers with a band (a syllabus read from results that lacks the
+feis's championships), the band is read from the row's own titles (`titles`, by code) by the
+domain package's title reader, the youngest again, and `age.from` says `title`. Nothing else
+stands in for a band. The dancer resolver is the release's own (`rel.dancers`, above), or the
+`dancerResolver` option. With `dancerResolver: null`, each row's dancer answers `unavailable`
+and the competitions still resolve.
+
+## The command line
+
+    idq config repo <owner/name>
+    idq list [--remote]
+    idq fetch [--release <spec>] [--assets results,majors,<file>...]
+    idq pin <spec> | unpin | current
+    idq add <dir> --tag <tag>
+    idq index [--release <spec>] [<name>...] [--force]
+    idq verify [--release <spec>]
+    idq prune [--keep N] [--dry-run]
+    idq rm <tag> [--dry-run]
+    idq drop-indexes [<tag>] [--dry-run]
+    idq feis [--release <spec>] [--platform p] [--code c] [--id i] [--name glob] [--year y]
+    idq series [--release <spec>] <name|host code|feis id>
+    idq school [--release <spec>] <print|school_id> [--region <code>]
+    idq dancer [--release <spec>] <name> | --surname <s> | --like <glob> | --id <dancer_id>
+               [--order surname-first|given-first] [--school <print|id>]
+               [--yob <y> | --band <band> [--year <y>] | --comp <competition>] [--as-of <date>] [--rows]
+    idq results [--release <spec>] [--dancer <id>] [--feis <id>] [--comp <c>] [--school <s>] [--year <y>] [--limit <n>]
+    idq majors [--release <spec>] [--event <e>] [--year <y>] [--comp <c>] [--dancer <id>] [--rows]
+    idq teacher [--release <spec>] <name|TD number>
+    idq adjudicator [--release <spec>] <name|TD number>
+    idq comp [--release <spec>] <feis> <code> [--year y] [--title t]
+    idq syllabus [--release <spec>] <feis> [year]
+    idq syllabus [--release <spec>] --for <series> [year]
+    idq resolve comp [<feis> <code>] [--year y] [--title t]
+    idq resolve dancer [<name>] [--school s] [--comp <feis>/<code> | --yob y | --band b --year y]
+    idq resolve registrations
+
+`dancer` prints the results of the one dancer where the answer is unique (every candidate's with
+`--rows`). `--json` prints the call's answer as it is. `--cache` and `--repo` override the defaults.
+
+`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?}`, `{name, school?, codes, feis, year?}`). A line that is no JSON object,
+or no question of its kind, answers `{tag, line, error}` and the other lines still answer. The
+exit is non-zero where any line erred. A dancer's age may be given as a comp
+(`{"comp": "<feis>/<code>"}`, or `--comp` on the command line): `rel.registrations.dancer` reads
+it through the comp's syllabus and asks the dancer resolver at that comp's band.
+
+## Licence
+
+MIT

package/dist/chunks/index-hghdy980.js

@@ -0,0 +1,75 @@
+// @bun
+var ARCHIVE_TAG2 = /^archive-(\d{4}\.\d{2}\.\d{2})(?:-(\d+)(?:\.([1-9]\d*))?)?$/;
+function parseArchiveTag2(tag) {
+  const m = ARCHIVE_TAG2.exec(tag);
+  if (m === null)
+    return null;
+  const out = { date: m[1] };
+  if (m[2] !== undefined)
+    out.cut = Number(m[2]);
+  if (m[3] !== undefined)
+    out.fraction = Number(m[3]);
+  return out;
+}
+function renderArchiveTag2(t) {
+  if (t.cut === undefined) {
+    if ((t.fraction ?? 0) > 0)
+      throw new Error("archive tag: a fraction needs a cut number");
+    return `archive-${t.date}`;
+  }
+  return `archive-${t.date}-${t.cut}${(t.fraction ?? 0) > 0 ? `.${t.fraction}` : ""}`;
+}
+function cutOf2(inputRelease) {
+  const m = inputRelease === undefined ? null : /-(\d+)$/.exec(inputRelease);
+  return m === null ? undefined : Number(m[1]);
+}
+function compareTagsNewestFirst2(a, b) {
+  const pa = parseArchiveTag2(a);
+  const pb = parseArchiveTag2(b);
+  if (pa === null || pb === null)
+    return pa === null ? pb === null ? a < b ? 1 : -1 : 1 : -1;
+  if (pa.date !== pb.date)
+    return pa.date < pb.date ? 1 : -1;
+  const ca = pa.cut ?? -1;
+  const cb = pb.cut ?? -1;
+  if (ca !== cb)
+    return cb - ca;
+  const fa = pa.fraction ?? 0;
+  const fb = pb.fraction ?? 0;
+  if (fa !== fb)
+    return fb - fa;
+  return a < b ? 1 : a > b ? -1 : 0;
+}
+function parseReleaseSpec2(spec) {
+  if (typeof spec === "number")
+    return Number.isInteger(spec) && spec >= 0 ? { kind: "cut", cut: spec, fraction: 0 } : `release: ${spec} is not a cut number`;
+  const s = spec.trim();
+  if (s === "latest")
+    return { kind: "latest" };
+  if (s === "pinned")
+    return { kind: "pinned" };
+  const m = /^(\d+)(?:\.(\d+))?$/.exec(s);
+  if (m !== null)
+    return { kind: "cut", cut: Number(m[1]), fraction: Number(m[2] ?? 0) };
+  if (parseArchiveTag2(s) !== null)
+    return { kind: "tag", tag: s };
+  return `release: "${spec}" is not latest, pinned, a cut number (42, 42.1) or a release tag (archive-YYYY.MM.DD-N)`;
+}
+function pickTag2(tags, spec) {
+  const sorted = tags.filter((t) => parseArchiveTag2(t) !== null).sort(compareTagsNewestFirst2);
+  switch (spec.kind) {
+    case "latest":
+      return sorted.find((t) => parseArchiveTag2(t)?.cut !== undefined) ?? sorted[0] ?? null;
+    case "tag":
+      return tags.includes(spec.tag) ? spec.tag : null;
+    case "cut":
+      return sorted.find((t) => {
+        const p = parseArchiveTag2(t);
+        return p?.cut === spec.cut && (p.fraction ?? 0) === spec.fraction;
+      }) ?? null;
+    case "pinned":
+      return null;
+  }
+}
+
+export { ARCHIVE_TAG2, parseArchiveTag2, renderArchiveTag2, cutOf2, compareTagsNewestFirst2, parseReleaseSpec2, pickTag2 };

package/dist/chunks/index-hne1wadw.js

@@ -0,0 +1,57 @@
+// @bun
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+var set = (v) => v !== undefined && v.trim() !== "";
+function expandHome2(p) {
+  return p === "~" || p.startsWith("~/") ? join(homedir(), p.slice(1)) : p;
+}
+function cacheRoot2(opts = {}) {
+  const env = opts.env ?? process.env;
+  if (set(opts.cache))
+    return expandHome2(opts.cache);
+  if (set(env.ARCHIVE_CLIENT_CACHE))
+    return expandHome2(env.ARCHIVE_CLIENT_CACHE);
+  return join(homedir(), ".cache", "archive-client");
+}
+var configPath2 = (root) => join(root, "config.json");
+function readConfig2(root) {
+  const p = configPath2(root);
+  if (!existsSync(p))
+    return {};
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeJsonAtomic2(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  const part = `${path}.${process.pid}.part`;
+  writeFileSync(part, `${JSON.stringify(value, null, "\t")}
+`);
+  renameSync(part, path);
+}
+function writeConfig2(root, patch) {
+  const next = { ...readConfig2(root), ...patch };
+  writeJsonAtomic2(configPath2(root), next);
+  return next;
+}
+var REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+function repoOf2(opts = {}) {
+  const env = opts.env ?? process.env;
+  const r = [opts.repo, env.ARCHIVE_CLIENT_REPO, readConfig2(cacheRoot2(opts)).repo].find(set)?.trim();
+  if (r === undefined)
+    return null;
+  if (!REPO.test(r))
+    throw new Error(`archive-client: repo "${r}" is not owner/name`);
+  return r;
+}
+function requireRepo2(opts = {}) {
+  const r = repoOf2(opts);
+  if (r === null)
+    throw new Error("archive-client: no repository: pass `repo`, set ARCHIVE_CLIENT_REPO, or run `config repo <owner/name>`");
+  return r;
+}
+
+export { expandHome2, cacheRoot2, configPath2, readConfig2, writeJsonAtomic2, writeConfig2, repoOf2, requireRepo2 };