@atarashi/registry 1.0.0

package/dist/index.js

@@ -0,0 +1,1191 @@
+import { existsSync } from 'fs';
+import { mkdir, writeFile, rm, readdir, rename, readFile, stat, lstat } from 'fs/promises';
+import { join, posix, resolve, sep, dirname, isAbsolute, relative } from 'path';
+import { error, DIAGNOSTIC_CODES, parseRegistryIndex, warning, parseBlueprintManifest, parsePresetManifest } from '@atarashi/schema';
+import { gunzipSync } from 'zlib';
+import { Parser } from 'tar';
+import { createHash, timingSafeEqual } from 'crypto';
+import { homedir } from 'os';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { valid, rcompare, gt } from 'semver';
+import { createRequire } from 'module';
+
+// src/cache.ts
+var RegistryError = class extends Error {
+  code;
+  suggestions;
+  detail;
+  constructor(code, message, options = {}) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "RegistryError";
+    this.code = code;
+    this.suggestions = options.suggestions ?? [];
+    this.detail = options.detail;
+  }
+  toDiagnostic() {
+    const rest = {};
+    if (this.suggestions.length > 0) rest.suggestions = this.suggestions;
+    if (this.detail) rest.detail = this.detail;
+    return error(this.code, this.message, rest);
+  }
+};
+var unavailable = (message, suggestions = []) => new RegistryError(DIAGNOSTIC_CODES.REGISTRY_UNAVAILABLE, message, { suggestions });
+var integrityFailure = (message, detail) => new RegistryError(DIAGNOSTIC_CODES.INTEGRITY_MISMATCH, message, {
+  detail,
+  suggestions: [
+    "Run `atarashi registry clear` and retry \u2014 a corrupt cache entry is the usual cause",
+    "If it reproduces, the artifact has been tampered with: do not use it, and report it"
+  ]
+});
+var DEFAULT_LIMITS = {
+  maxEntries: 4e3,
+  maxFileSize: 8 * 1024 * 1024,
+  maxTotalSize: 64 * 1024 * 1024
+};
+var unsafe = (message, detail) => new RegistryError(DIAGNOSTIC_CODES.PATH_ESCAPE, message, {
+  detail,
+  suggestions: ["This artifact is malformed or malicious; do not use it, and report it"]
+});
+var GZIP_MAGIC = [31, 139];
+function decompress(tarball, limits) {
+  const gzipped = tarball[0] === GZIP_MAGIC[0] && tarball[1] === GZIP_MAGIC[1];
+  if (!gzipped) return tarball;
+  try {
+    return gunzipSync(tarball, { maxOutputLength: limits.maxTotalSize });
+  } catch (cause) {
+    throw new RegistryError(
+      DIAGNOSTIC_CODES.INTEGRITY_MISMATCH,
+      "Tarball could not be decompressed, or exceeds the uncompressed size limit",
+      { cause, detail: `limit ${limits.maxTotalSize} bytes` }
+    );
+  }
+}
+function safeEntryPath(raw, strip = 0) {
+  const unified = raw.replace(/\\/g, "/");
+  if (unified.includes("\0")) throw unsafe("Archive member path contains a null byte", raw);
+  if (unified.startsWith("//")) throw unsafe(`Archive member \`${raw}\` is a UNC path`);
+  if (unified.startsWith("/")) throw unsafe(`Archive member \`${raw}\` is an absolute path`);
+  if (/^[a-zA-Z]:\//.test(unified)) throw unsafe(`Archive member \`${raw}\` is a drive path`);
+  const segments = unified.split("/").filter((segment) => segment !== "" && segment !== ".");
+  if (segments.includes("..")) {
+    throw unsafe(`Archive member \`${raw}\` escapes the extraction directory`);
+  }
+  const stripped = segments.slice(strip);
+  if (stripped.length === 0) return void 0;
+  return posix.join(...stripped);
+}
+async function readTarball(tarball, options = {}) {
+  const limits = { ...DEFAULT_LIMITS, ...options.limits };
+  const raw = decompress(tarball, limits);
+  const files = [];
+  const seen = /* @__PURE__ */ new Set();
+  let entries = 0;
+  let total = 0;
+  let failure;
+  const parser = new Parser({
+    onReadEntry(entry) {
+      try {
+        if (failure) {
+          entry.resume();
+          return;
+        }
+        if (++entries > limits.maxEntries) {
+          throw unsafe(`Archive has more than ${limits.maxEntries} members`);
+        }
+        if (entry.type === "SymbolicLink" || entry.type === "Link") {
+          throw unsafe(`Archive member \`${entry.path}\` is a link`);
+        }
+        if (entry.type === "Directory" || entry.type === "GNUDumpDir") {
+          entry.resume();
+          return;
+        }
+        if (entry.type !== "File" && entry.type !== "OldFile" && entry.type !== "ContiguousFile") {
+          throw unsafe(
+            `Archive member \`${entry.path}\` has unsupported type ${entry.type}`
+          );
+        }
+        const path = safeEntryPath(String(entry.path), options.strip ?? 0);
+        if (path === void 0) {
+          entry.resume();
+          return;
+        }
+        if (seen.has(path.toLowerCase())) {
+          throw unsafe(`Archive contains \`${path}\` twice, or two names that collide`);
+        }
+        seen.add(path.toLowerCase());
+        if ((entry.size ?? 0) > limits.maxFileSize) {
+          throw unsafe(
+            `Archive member \`${path}\` is larger than the ${limits.maxFileSize} byte limit`
+          );
+        }
+        const chunks = [];
+        let size = 0;
+        entry.on("data", (chunk) => {
+          size += chunk.length;
+          total += chunk.length;
+          if (size > limits.maxFileSize || total > limits.maxTotalSize) {
+            failure ??= unsafe(`Archive exceeds the ${limits.maxTotalSize} byte limit`);
+            return;
+          }
+          chunks.push(chunk);
+        });
+        entry.on("end", () => {
+          if (failure) return;
+          const mode = (entry.mode ?? 420) & 73 ? 493 : 420;
+          files.push({ path, mode, contents: Buffer.concat(chunks) });
+        });
+      } catch (thrown) {
+        failure ??= thrown;
+        entry.resume();
+      }
+    }
+  });
+  await new Promise((resolvePromise, rejectPromise) => {
+    parser.on("error", rejectPromise);
+    parser.on("end", () => resolvePromise());
+    parser.end(raw);
+  });
+  if (failure) throw failure;
+  if (files.length === 0) throw unsafe("Archive contains no files");
+  return files.sort((a, b) => a.path < b.path ? -1 : 1);
+}
+async function extractTarball(tarball, dest, options = {}) {
+  const files = await readTarball(tarball, options);
+  const root = resolve(dest);
+  for (const file of files) {
+    const target = resolve(root, file.path);
+    if (target !== root && !target.startsWith(root + sep)) {
+      throw unsafe(
+        `Archive member \`${file.path}\` resolves outside the extraction directory`
+      );
+    }
+  }
+  await mkdir(root, { recursive: true });
+  for (const file of files) {
+    const target = join(root, file.path);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, file.contents, { mode: file.mode, flag: "wx" });
+  }
+  return files.map((file) => file.path);
+}
+var SRI = /^(sha256|sha384|sha512)-([A-Za-z0-9+/]+={0,2})$/;
+function digest(data, algorithm = "sha256") {
+  return `${algorithm}-${createHash(algorithm).update(data).digest("base64")}`;
+}
+function hexDigest(data, algorithm = "sha256") {
+  return createHash(algorithm).update(data).digest("hex");
+}
+function parseIntegrity(value) {
+  const match = SRI.exec(value);
+  if (!match) {
+    throw integrityFailure(`\`${value}\` is not a valid integrity digest`);
+  }
+  return { algorithm: match[1], base64: match[2] };
+}
+function verifyIntegrity(data, expected, what) {
+  const { algorithm } = parseIntegrity(expected);
+  const actual = digest(data, algorithm);
+  const a = Buffer.from(actual);
+  const b = Buffer.from(expected);
+  if (a.length !== b.length || !timingSafeEqual(a, b)) {
+    throw integrityFailure(
+      `Integrity check failed for ${what}`,
+      `expected ${expected}, computed ${actual}`
+    );
+  }
+}
+function canonicalize(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value ?? null);
+  if (Array.isArray(value)) return `[${value.map(canonicalize).join(",")}]`;
+  const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, v]) => `${JSON.stringify(key)}:${canonicalize(v)}`);
+  return `{${entries.join(",")}}`;
+}
+function indexRootHash(index) {
+  return digest(
+    canonicalize({
+      indexVersion: index.indexVersion,
+      version: index.version,
+      entries: index.entries,
+      versionManifest: index.versionManifest ?? null
+    })
+  );
+}
+function verifyIndexIntegrity(index, source) {
+  if (!index.integrity) return;
+  const actual = indexRootHash(index);
+  if (actual !== index.integrity) {
+    throw integrityFailure(
+      `Registry index ${index.version} failed its root hash check (${source})`,
+      `expected ${index.integrity}, computed ${actual}`
+    );
+  }
+}
+var DEFAULT_REGISTRY_URL = "https://atarashi.gautamsuthar.in/registry";
+var DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
+function resolveCacheRoot(env = process.env, platform = process.platform) {
+  const override = env.ATARASHI_CACHE_DIR?.trim();
+  if (override) return override;
+  if (platform === "win32") {
+    const base = env.LOCALAPPDATA?.trim() || join(homedir(), "AppData", "Local");
+    return join(base, "atarashi", "Cache");
+  }
+  if (platform === "darwin") {
+    return join(homedir(), "Library", "Caches", "atarashi");
+  }
+  const xdg = env.XDG_CACHE_HOME?.trim();
+  return join(xdg || join(homedir(), ".cache"), "atarashi");
+}
+function cacheLayout(root) {
+  return {
+    root,
+    index: join(root, "index"),
+    blueprints: join(root, "blueprints"),
+    meta: join(root, "meta.json")
+  };
+}
+var slugifyId = (id) => id.replace(/\//g, "-");
+
+// src/cache.ts
+var EMPTY_META = { metaVersion: 1, index: {}, blueprints: {} };
+var hasManifest = (dir) => existsSync(join(dir, "blueprint.json")) || existsSync(join(dir, "preset.json"));
+var readJson = async (path) => {
+  const raw = await readFile(path, "utf8");
+  return JSON.parse(raw);
+};
+var writeJson = async (path, value) => {
+  await mkdir(join(path, ".."), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+  await rename(temporary, path);
+};
+var RegistryCache = class {
+  layout;
+  meta;
+  constructor(root) {
+    this.layout = cacheLayout(root);
+  }
+  async readMeta() {
+    if (this.meta) return this.meta;
+    try {
+      const parsed = await readJson(this.layout.meta);
+      this.meta = parsed && parsed.metaVersion === 1 ? { ...EMPTY_META, ...parsed } : { ...EMPTY_META };
+    } catch {
+      this.meta = { ...EMPTY_META };
+    }
+    return this.meta;
+  }
+  async writeMeta(update) {
+    const meta = await this.readMeta();
+    update(meta);
+    this.meta = meta;
+    await writeJson(this.layout.meta, meta);
+  }
+  indexPath(version) {
+    return join(this.layout.index, `${version}.json`);
+  }
+  async readIndex(version, source) {
+    const path = this.indexPath(version);
+    if (!existsSync(path)) return void 0;
+    let raw;
+    try {
+      raw = await readJson(path);
+    } catch (cause) {
+      await rm(path, { force: true });
+      throw new RegistryError(
+        DIAGNOSTIC_CODES.REGISTRY_UNAVAILABLE,
+        `Cached registry index ${version} is unreadable`,
+        { cause, suggestions: ["Run `atarashi registry update` to fetch it again"] }
+      );
+    }
+    const parsed = parseRegistryIndex(raw, path);
+    if (!parsed.ok) {
+      await rm(path, { force: true });
+      throw new RegistryError(parsed.error.code, parsed.error.message, {
+        suggestions: ["Run `atarashi registry update` to fetch a fresh index"]
+      });
+    }
+    verifyIndexIntegrity(parsed.value, `${source} (cached)`);
+    return parsed.value;
+  }
+  async writeIndex(index) {
+    await mkdir(this.layout.index, { recursive: true });
+    await writeJson(this.indexPath(index.version), index);
+  }
+  /** Every registry version this machine has already verified. */
+  async cachedIndexVersions() {
+    try {
+      const files = await readdir(this.layout.index);
+      return files.filter((file) => file.endsWith(".json")).map((file) => file.slice(0, -".json".length));
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Content-addressed, but still legible: `db-postgres-1.2.0-8f2c…`. The hash
+   * suffix is what makes it content-addressed; the rest is for humans reading
+   * `atarashi registry verify` output.
+   */
+  blueprintDir(id, version, integrity) {
+    const { base64 } = parseIntegrity(integrity);
+    const short = Buffer.from(base64, "base64").toString("hex").slice(0, 12);
+    return join(this.layout.blueprints, `${slugifyId(id)}-${version}-${short}`);
+  }
+  hasBlueprint(id, version, integrity) {
+    return hasManifest(this.blueprintDir(id, version, integrity));
+  }
+  /**
+   * Verifies, extracts into a temp directory, then renames into place — so a
+   * cache directory only ever exists in its complete, verified form.
+   */
+  async storeBlueprint(entry, tarball) {
+    verifyIntegrity(tarball, entry.integrity, `${entry.id}@${entry.version}`);
+    const target = this.blueprintDir(entry.id, entry.version, entry.integrity);
+    if (hasManifest(target)) return target;
+    const staging = `${target}.${process.pid}.${hexDigest(String(Date.now())).slice(0, 8)}`;
+    await rm(staging, { recursive: true, force: true });
+    try {
+      await extractTarball(tarball, staging);
+      if (!hasManifest(staging)) {
+        throw integrityFailure(
+          `${entry.id}@${entry.version} has no \`blueprint.json\` at its root`
+        );
+      }
+      await mkdir(this.layout.blueprints, { recursive: true });
+      await rm(target, { recursive: true, force: true });
+      await rename(staging, target);
+    } finally {
+      await rm(staging, { recursive: true, force: true });
+    }
+    await this.writeMeta((meta) => {
+      meta.blueprints[`${entry.id}@${entry.version}`] = {
+        id: entry.id,
+        version: entry.version,
+        integrity: entry.integrity,
+        dir: target
+      };
+    });
+    return target;
+  }
+  async clear() {
+    this.meta = void 0;
+    await rm(this.layout.root, { recursive: true, force: true });
+  }
+  /**
+   * Re-checks that everything the meta file claims is cached is still there.
+   * Extracted trees cannot be re-hashed against the tarball digest, so this
+   * reports presence and shape, and prunes what has gone missing.
+   */
+  async verify() {
+    const meta = await this.readMeta();
+    const removed = [];
+    let checked = 0;
+    for (const [key, record] of Object.entries(meta.blueprints)) {
+      checked += 1;
+      if (!hasManifest(record.dir)) removed.push(key);
+    }
+    for (const version of await this.cachedIndexVersions()) {
+      checked += 1;
+      try {
+        await this.readIndex(version, "cache");
+      } catch {
+        removed.push(`index@${version}`);
+      }
+    }
+    if (removed.length > 0) {
+      await this.writeMeta((current) => {
+        for (const key of removed) delete current.blueprints[key];
+      });
+    }
+    return { checked, removed };
+  }
+  async size() {
+    const walk = async (dir) => {
+      let total = 0;
+      let entries;
+      try {
+        entries = await readdir(dir);
+      } catch {
+        return 0;
+      }
+      for (const entry of entries) {
+        const path = join(dir, entry);
+        const info = await stat(path).catch(() => void 0);
+        if (!info) continue;
+        total += info.isDirectory() ? await walk(path) : info.size;
+      }
+      return total;
+    };
+    return walk(this.layout.root);
+  }
+};
+function assertFetchable(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw unavailable(`\`${url}\` is not a valid registry URL`);
+  }
+  if (parsed.protocol === "https:" || parsed.protocol === "file:") return parsed;
+  if (parsed.protocol === "http:") {
+    throw unavailable(`Refusing to fetch the registry over plain HTTP: ${url}`, [
+      "Use an `https://` registry URL"
+    ]);
+  }
+  throw unavailable(`Unsupported registry protocol \`${parsed.protocol}\` in ${url}`);
+}
+async function httpGet(url, options = {}) {
+  const parsed = assertFetchable(url);
+  const maxBytes = options.maxBytes ?? DEFAULT_LIMITS.maxTotalSize;
+  if (parsed.protocol === "file:") {
+    try {
+      const body = await readFile(fileURLToPath(parsed));
+      return { status: 200, body, etag: void 0 };
+    } catch {
+      throw unavailable(`Cannot read ${url}`);
+    }
+  }
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  if (!fetchImpl) {
+    throw unavailable("This Node build has no global `fetch`", [
+      "Upgrade to Node 20.11 or newer"
+    ]);
+  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 15e3);
+  try {
+    const headers = { accept: "application/json, application/gzip" };
+    if (options.etag) headers["if-none-match"] = options.etag;
+    const response = await fetchImpl(url, { headers, signal: controller.signal });
+    const etag = response.headers.get("etag") ?? void 0;
+    if (response.status === 304) return { status: 304, body: Buffer.alloc(0), etag };
+    if (!response.ok) {
+      throw unavailable(`${url} responded ${response.status} ${response.statusText}`.trim());
+    }
+    const body = Buffer.from(await response.arrayBuffer());
+    if (body.byteLength > maxBytes) {
+      throw unavailable(
+        `${url} returned ${body.byteLength} bytes, over the ${maxBytes} limit`
+      );
+    }
+    return { status: response.status, body, etag };
+  } catch (cause) {
+    if (cause instanceof RegistryError) throw cause;
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    throw unavailable(`Cannot reach ${url}: ${reason}`, [
+      "Check your network connection, or run with `--offline` to use the cache"
+    ]);
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+var joinUrl = (base, path) => /^[a-z][a-z0-9+.-]*:/i.test(path) ? path : `${base.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+var indexUrl = (base, pin) => pin ? joinUrl(base, `v1/${pin}/index.json`) : joinUrl(base, "v1/index.json");
+var IndexStore = class {
+  options;
+  loaded;
+  diagnostics = [];
+  constructor(options) {
+    this.options = {
+      url: DEFAULT_REGISTRY_URL,
+      ttlMs: DEFAULT_TTL_MS,
+      ...options
+    };
+  }
+  get url() {
+    return this.options.url;
+  }
+  get origin() {
+    return this.loaded?.origin;
+  }
+  /** Resolves once per process; subsequent calls reuse the verified document. */
+  async load() {
+    if (this.loaded) return this.loaded;
+    this.loaded = this.options.pin ? await this.loadPinned(this.options.pin) : await this.loadLatest();
+    return this.loaded;
+  }
+  /** Discards the TTL and re-checks the network — `atarashi registry update`. */
+  async refresh() {
+    this.loaded = void 0;
+    const cache = this.options.cache;
+    await cache.writeMeta((meta) => {
+      delete meta.index[indexUrl(this.options.url, this.options.pin)];
+    });
+    return this.load();
+  }
+  async loadPinned(version) {
+    const cache = this.options.cache;
+    if (!valid(version)) {
+      throw unavailable(`\`${version}\` is not a valid registry version`, [
+        "Registry versions are exact semver, e.g. `atarashi registry pin 1.4.2`"
+      ]);
+    }
+    const cached = await cache.readIndex(version, this.options.url);
+    if (cached) {
+      return { index: cached, origin: this.originOf(cached, "cache") };
+    }
+    if (this.options.offline) {
+      throw unavailable(`Registry ${version} is pinned but not cached, and you are offline`, [
+        "Run `atarashi registry update` with a network connection",
+        "Or remove the pin with `atarashi registry unpin`"
+      ]);
+    }
+    const url = indexUrl(this.options.url, version);
+    const response = await httpGet(url, { fetchImpl: this.options.fetchImpl });
+    const index = this.parse(response.body, url);
+    if (index.version !== version) {
+      throw unavailable(
+        `Registry ${version} was requested but ${url} served ${index.version}`
+      );
+    }
+    await this.persist(index, url, response.etag);
+    return { index, origin: this.originOf(index, "network") };
+  }
+  async loadLatest() {
+    const cache = this.options.cache;
+    const url = indexUrl(this.options.url);
+    const meta = await cache.readMeta();
+    const record = meta.index[url];
+    const cachedIndex = record ? await cache.readIndex(record.version, url) : void 0;
+    if (this.options.offline) {
+      const offlineIndex = cachedIndex ?? await this.newestCached();
+      if (offlineIndex)
+        return { index: offlineIndex, origin: this.originOf(offlineIndex, "cache") };
+      throw unavailable("No cached registry index, and the network is disabled", [
+        "Run `atarashi registry update` with a network connection",
+        "Bundled blueprints still work offline \u2014 drop `--offline` only if you need registry-only ones"
+      ]);
+    }
+    if (cachedIndex && record && this.isFresh(record.fetchedAt)) {
+      return {
+        index: cachedIndex,
+        origin: this.originOf(cachedIndex, "cache", record.fetchedAt)
+      };
+    }
+    try {
+      const response = await httpGet(url, {
+        etag: record?.etag,
+        fetchImpl: this.options.fetchImpl
+      });
+      if (response.status === 304 && cachedIndex) {
+        await this.touch(url, cachedIndex.version, record?.etag);
+        return { index: cachedIndex, origin: this.originOf(cachedIndex, "cache") };
+      }
+      const index = this.parse(response.body, url);
+      await this.persist(index, url, response.etag);
+      return { index, origin: this.originOf(index, "network") };
+    } catch (thrown) {
+      if (thrown instanceof RegistryError && thrown.code !== DIAGNOSTIC_CODES.REGISTRY_UNAVAILABLE) {
+        throw thrown;
+      }
+      const fallback = cachedIndex ?? await this.newestCached();
+      if (!fallback) throw thrown;
+      this.diagnostics.push(
+        warning(
+          DIAGNOSTIC_CODES.REGISTRY_UNAVAILABLE,
+          `Registry unreachable; using the cached index ${fallback.version}`,
+          {
+            detail: thrown instanceof Error ? thrown.message : String(thrown),
+            suggestions: ["Run `atarashi registry update` once you are back online"]
+          }
+        )
+      );
+      return { index: fallback, origin: this.originOf(fallback, "cache") };
+    }
+  }
+  parse(body, url) {
+    let raw;
+    try {
+      raw = JSON.parse(body.toString("utf8"));
+    } catch (cause) {
+      throw new RegistryError(
+        DIAGNOSTIC_CODES.REGISTRY_UNAVAILABLE,
+        `${url} did not return valid JSON`,
+        { cause }
+      );
+    }
+    const parsed = parseRegistryIndex(raw, url);
+    if (!parsed.ok) {
+      throw new RegistryError(parsed.error.code, `${parsed.error.message} (${url})`, {
+        suggestions: ["Upgrade Atarashi \u2014 this index may use a newer index version"]
+      });
+    }
+    verifyIndexIntegrity(parsed.value, url);
+    return parsed.value;
+  }
+  async persist(index, url, etag) {
+    await this.options.cache.writeIndex(index);
+    await this.touch(url, index.version, etag);
+  }
+  async touch(url, version, etag) {
+    const fetchedAt = this.nowIso();
+    await this.options.cache.writeMeta((meta) => {
+      meta.index[url] = etag ? { etag, fetchedAt, version } : { fetchedAt, version };
+    });
+  }
+  async newestCached() {
+    const versions = (await this.options.cache.cachedIndexVersions()).filter((version) => valid(version)).sort(rcompare);
+    for (const version of versions) {
+      const index = await this.options.cache.readIndex(version, this.options.url);
+      if (index) return index;
+    }
+    return void 0;
+  }
+  isFresh(fetchedAt) {
+    const age = this.now() - Date.parse(fetchedAt);
+    return Number.isFinite(age) && age >= 0 && age < this.options.ttlMs;
+  }
+  originOf(index, from, fetchedAt) {
+    const origin = { version: index.version, url: this.options.url, from };
+    if (fetchedAt) origin.fetchedAt = fetchedAt;
+    if (index.integrity) origin.integrity = index.integrity;
+    return origin;
+  }
+  now() {
+    return (this.options.now?.() ?? /* @__PURE__ */ new Date()).getTime();
+  }
+  nowIso() {
+    return new Date(this.now()).toISOString();
+  }
+};
+var MANIFEST_FILE = "blueprint.json";
+var PRESET_FILE = "preset.json";
+var invalid = (message, suggestions = []) => new RegistryError(DIAGNOSTIC_CODES.SCHEMA_INVALID, message, { suggestions });
+async function readInside(root, path) {
+  if (path.includes("\0")) throw invalid(`Blueprint file path contains a null byte`);
+  if (isAbsolute(path)) throw invalid(`Blueprint file \`${path}\` must be relative`);
+  const target = resolve(root, path);
+  const rel = relative(root, target);
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+    throw new RegistryError(
+      DIAGNOSTIC_CODES.PATH_ESCAPE,
+      `Blueprint file \`${path}\` resolves outside its own directory`
+    );
+  }
+  let walked = root;
+  for (const segment of rel.split(sep)) {
+    walked = join(walked, segment);
+    const info = await lstat(walked).catch(() => void 0);
+    if (info?.isSymbolicLink()) {
+      throw new RegistryError(
+        DIAGNOSTIC_CODES.PATH_ESCAPE,
+        `Blueprint file \`${path}\` passes through the symlink \`${segment}\``
+      );
+    }
+  }
+  return readFile(target);
+}
+async function loadBlueprintDir(dir, options) {
+  const manifestPath = join(dir, MANIFEST_FILE);
+  if (!existsSync(manifestPath)) {
+    throw invalid(`No \`${MANIFEST_FILE}\` in ${dir}`, [
+      "Run `atarashi create-blueprint --validate .` inside the blueprint"
+    ]);
+  }
+  const raw = await readFile(manifestPath, "utf8");
+  let parsedJson;
+  try {
+    parsedJson = JSON.parse(raw);
+  } catch (cause) {
+    throw new RegistryError(
+      DIAGNOSTIC_CODES.SCHEMA_INVALID,
+      `${manifestPath} is not valid JSON`,
+      { cause }
+    );
+  }
+  const parsed = parseBlueprintManifest(parsedJson, manifestPath);
+  if (!parsed.ok) {
+    throw new RegistryError(parsed.error.code, parsed.error.message, {
+      detail: parsed.error.diagnostics.map((d) => d.message).join("\n")
+    });
+  }
+  return {
+    manifest: parsed.value,
+    origin: options.origin ?? dir,
+    dir,
+    trusted: options.trusted,
+    readFile: (path) => readInside(dir, path)
+  };
+}
+async function loadPresetFile(path) {
+  const parsed = parsePresetManifest(JSON.parse(await readFile(path, "utf8")), path);
+  if (!parsed.ok) {
+    throw new RegistryError(parsed.error.code, parsed.error.message, {
+      detail: parsed.error.diagnostics.map((d) => d.message).join("\n")
+    });
+  }
+  return parsed.value;
+}
+var summarize = (manifest) => ({
+  id: manifest.id,
+  version: manifest.version,
+  provides: manifest.provides,
+  requires: manifest.requires,
+  conflicts: manifest.conflicts,
+  deprecated: Boolean(manifest.deprecated)
+});
+var DirectorySource = class {
+  constructor(root, options) {
+    this.root = root;
+    this.options = options;
+  }
+  root;
+  options;
+  manifests;
+  /** Scans lazily and once — a cold `atarashi list` should not pay twice. */
+  async scan() {
+    if (this.manifests) return this.manifests;
+    const found = /* @__PURE__ */ new Map();
+    if (existsSync(this.root)) {
+      for (const namespace of await readdir(this.root, { withFileTypes: true })) {
+        if (!namespace.isDirectory()) continue;
+        const namespaceDir = join(this.root, namespace.name);
+        for (const name of await readdir(namespaceDir, { withFileTypes: true })) {
+          if (!name.isDirectory()) continue;
+          const dir = join(namespaceDir, name.name);
+          if (existsSync(join(dir, MANIFEST_FILE))) {
+            found.set(`${namespace.name}/${name.name}`, dir);
+          }
+        }
+      }
+    }
+    this.manifests = found;
+    return found;
+  }
+  async ids() {
+    return [...(await this.scan()).keys()].sort();
+  }
+  async has(id) {
+    return (await this.scan()).has(id);
+  }
+  async load(id) {
+    const dir = (await this.scan()).get(id);
+    if (!dir) return void 0;
+    return loadBlueprintDir(dir, this.options);
+  }
+  async summaries() {
+    const out = [];
+    for (const id of await this.ids()) {
+      const blueprint = await this.load(id);
+      if (blueprint) out.push(summarize(blueprint.manifest));
+    }
+    return out;
+  }
+  async loadPreset(id) {
+    const dir = this.options.presetsDir;
+    if (!dir) return void 0;
+    const file = join(dir, `${id.replace(/^preset\//, "")}.json`);
+    if (!existsSync(file)) return void 0;
+    return loadPresetFile(file);
+  }
+  async presets() {
+    const dir = this.options.presetsDir;
+    if (!dir || !existsSync(dir)) return [];
+    const files = (await readdir(dir)).filter((file) => file.endsWith(".json")).sort();
+    return Promise.all(files.map((file) => loadPresetFile(join(dir, file))));
+  }
+};
+
+// src/loaders/bundled.ts
+var require_ = createRequire(import.meta.url);
+function findBundledRoot(explicit) {
+  if (explicit) return existsSync(explicit) ? explicit : void 0;
+  try {
+    return dirname(require_.resolve("@atarashi/blueprints/package.json"));
+  } catch {
+    return void 0;
+  }
+}
+function createBundledSource(explicit) {
+  const root = findBundledRoot(explicit);
+  if (!root) return void 0;
+  return {
+    root,
+    versionManifestPath: join(root, "version-manifest.json"),
+    source: new DirectorySource(join(root, "blueprints"), {
+      trusted: true,
+      origin: "bundled",
+      presetsDir: join(root, "presets")
+    })
+  };
+}
+async function readBundledVersionManifest(path) {
+  if (!existsSync(path)) return void 0;
+  try {
+    const raw = JSON.parse(await readFile(path, "utf8"));
+    return raw.packages ?? {};
+  } catch {
+    return void 0;
+  }
+}
+var LOCAL_BLUEPRINTS_DIR = join(".atarashi", "blueprints");
+function createLocalSource(cwd, dir) {
+  const root = dir ?? join(cwd, LOCAL_BLUEPRINTS_DIR);
+  return new DirectorySource(root, {
+    trusted: false,
+    origin: `local:${root}`,
+    presetsDir: join(root, "..", "presets")
+  });
+}
+var NPM_PREFIX = "npm:";
+var NPM_PACKAGE_PATTERN = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?atarashi-blueprint-[a-z0-9-]+$/;
+var parseNpmSpec = (spec) => spec.startsWith(NPM_PREFIX) ? spec.slice(NPM_PREFIX.length) : void 0;
+var NpmSource = class {
+  constructor(cwd, packages = []) {
+    this.cwd = cwd;
+    this.packages = packages;
+  }
+  cwd;
+  packages;
+  cache = /* @__PURE__ */ new Map();
+  resolved;
+  /** Adds a package for this run, e.g. from `--add npm:atarashi-blueprint-redis`. */
+  add(spec) {
+    const name = parseNpmSpec(spec) ?? spec;
+    if (!this.packages.includes(name)) {
+      this.packages.push(name);
+      this.resolved = void 0;
+    }
+    return this;
+  }
+  async loadPackage(name) {
+    const existing = this.cache.get(name);
+    if (existing) return existing;
+    if (!NPM_PACKAGE_PATTERN.test(name)) {
+      throw new RegistryError(
+        DIAGNOSTIC_CODES.UNKNOWN_BLUEPRINT,
+        `\`${name}\` is not a blueprint package name`,
+        {
+          suggestions: [
+            "Community blueprint packages are named `atarashi-blueprint-<name>`"
+          ]
+        }
+      );
+    }
+    const require_2 = createRequire(pathToFileURL(join(this.cwd, "noop.js")));
+    let packageJsonPath;
+    try {
+      packageJsonPath = require_2.resolve(`${name}/package.json`);
+    } catch {
+      throw new RegistryError(
+        DIAGNOSTIC_CODES.UNKNOWN_BLUEPRINT,
+        `\`${name}\` is not installed in ${this.cwd}`,
+        { suggestions: [`Install it first: \`npm install ${name}\``] }
+      );
+    }
+    const packageRoot = dirname(packageJsonPath);
+    const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    if (!packageJson.atarashi) {
+      throw new RegistryError(
+        DIAGNOSTIC_CODES.SCHEMA_INVALID,
+        `\`${name}\` has no \`atarashi\` field pointing at its blueprint`,
+        { suggestions: ['Add `"atarashi": "./blueprint"` to the package'] }
+      );
+    }
+    const dir = resolve(packageRoot, packageJson.atarashi);
+    if (!dir.startsWith(packageRoot) || !existsSync(dir)) {
+      throw new RegistryError(
+        DIAGNOSTIC_CODES.SCHEMA_INVALID,
+        `\`${name}\` points its \`atarashi\` field outside the package`
+      );
+    }
+    const blueprint = await loadBlueprintDir(dir, {
+      trusted: false,
+      origin: `npm:${name}@${packageJson.version ?? "unknown"}`
+    });
+    this.cache.set(name, blueprint);
+    return blueprint;
+  }
+  async all() {
+    if (this.resolved) return this.resolved;
+    const map = /* @__PURE__ */ new Map();
+    for (const name of this.packages) {
+      const blueprint = await this.loadPackage(name);
+      map.set(blueprint.manifest.id, blueprint);
+    }
+    this.resolved = map;
+    return map;
+  }
+  async load(id) {
+    const name = parseNpmSpec(id);
+    if (name) return this.loadPackage(name);
+    return (await this.all()).get(id);
+  }
+  async summaries() {
+    return [...(await this.all()).values()].map((entry) => summarize(entry.manifest));
+  }
+};
+var entrySummary = (entry) => ({
+  id: entry.id,
+  version: entry.version,
+  provides: entry.provides,
+  requires: entry.requires,
+  conflicts: entry.conflicts,
+  deprecated: entry.deprecated
+});
+var RemoteSource = class {
+  constructor(store, cache, options = {}) {
+    this.store = store;
+    this.cache = cache;
+    this.options = options;
+  }
+  store;
+  cache;
+  options;
+  /** `undefined` when the index cannot be reached at all — bundled still works. */
+  async index() {
+    try {
+      return (await this.store.load()).index;
+    } catch (thrown) {
+      if (thrown instanceof RegistryError && thrown.code === DIAGNOSTIC_CODES.INTEGRITY_MISMATCH) {
+        throw thrown;
+      }
+      return void 0;
+    }
+  }
+  async entry(id) {
+    const index = await this.index();
+    return index?.entries.find(
+      (candidate) => candidate.id === id && candidate.kind !== "preset"
+    );
+  }
+  async summaries() {
+    const index = await this.index();
+    return (index?.entries ?? []).filter((entry) => entry.kind !== "preset").map(entrySummary);
+  }
+  async versionManifest() {
+    const index = await this.index();
+    return index?.versionManifest?.packages;
+  }
+  async load(id) {
+    const entry = await this.entry(id);
+    if (!entry) return void 0;
+    return this.loadEntry(entry);
+  }
+  async loadEntry(entry) {
+    const dir = await this.materialize(entry);
+    return loadBlueprintDir(dir, {
+      // Trust is a property of the source, not of the document it
+      // serves: an index cannot promote its own entries.
+      trusted: this.options.trusted ?? false,
+      origin: `registry:${entry.id}@${entry.version}`
+    });
+  }
+  async preset(id) {
+    const index = await this.index();
+    return index?.entries.find((entry) => entry.id === id && entry.kind === "preset");
+  }
+  async loadPreset(id) {
+    const entry = await this.preset(id);
+    if (!entry) return void 0;
+    const dir = await this.materialize(entry);
+    return loadPresetFile(join(dir, "preset.json"));
+  }
+  /** Downloads and verifies once; every later run is a cache hit. */
+  async materialize(entry) {
+    if (this.cache.hasBlueprint(entry.id, entry.version, entry.integrity)) {
+      return this.cache.blueprintDir(entry.id, entry.version, entry.integrity);
+    }
+    if (this.options.offline) {
+      throw unavailable(
+        `${entry.id}@${entry.version} is not cached, and the network is disabled`,
+        ["Run the same command without `--offline` once to populate the cache"]
+      );
+    }
+    const url = joinUrl(this.store.url, entry.tarball);
+    const response = await httpGet(url, { fetchImpl: this.options.fetchImpl });
+    return this.cache.storeBlueprint(entry, response.body);
+  }
+};
+var isOffline = (options) => {
+  if (options.offline !== void 0) return options.offline;
+  const env = options.env ?? process.env;
+  return env.ATARASHI_OFFLINE === "1" || env.ATARASHI_OFFLINE === "true";
+};
+var Registry = class {
+  local;
+  npm;
+  bundled;
+  remotes = [];
+  primary;
+  cache;
+  offline;
+  constructor(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    this.offline = isOffline(options);
+    this.cache = new RegistryCache(
+      options.cacheDir ?? resolveCacheRoot(options.env ?? process.env)
+    );
+    this.local = createLocalSource(cwd, options.localDir);
+    this.npm = new NpmSource(cwd, [...options.npmPackages ?? []]);
+    this.bundled = createBundledSource(options.bundledDir);
+    const configured = options.sources?.length ? options.sources : [
+      {
+        name: "atarashi",
+        url: options.url ?? DEFAULT_REGISTRY_URL,
+        trusted: true,
+        enabled: true
+      }
+    ];
+    for (const source of configured.filter((candidate) => candidate.enabled !== false)) {
+      const store = new IndexStore({
+        cache: this.cache,
+        url: source.url,
+        pin: options.pin ?? null,
+        offline: this.offline,
+        ttlMs: options.ttlMs ?? DEFAULT_TTL_MS,
+        fetchImpl: options.fetchImpl,
+        now: options.now
+      });
+      this.remotes.push({
+        name: source.name,
+        store,
+        source: new RemoteSource(store, this.cache, {
+          offline: this.offline,
+          fetchImpl: options.fetchImpl,
+          trusted: source.trusted === true
+        })
+      });
+    }
+    this.primary = this.remotes[0];
+  }
+  /** Warnings collected while resolving — degraded-network notices, mostly. */
+  get diagnostics() {
+    return this.remotes.flatMap((layer) => layer.store.diagnostics);
+  }
+  // ── BlueprintSource ──────────────────────────────────────────────────────
+  async load(id) {
+    if (id.startsWith(NPM_PREFIX)) return this.npm.load(id);
+    const local = await this.local.load(id);
+    if (local) return local;
+    const fromNpm = await this.npm.load(id);
+    if (fromNpm) return fromNpm;
+    const bundled = await this.bundled?.source.load(id);
+    for (const layer of this.remotes) {
+      const entry = await layer.source.entry(id);
+      if (!entry) continue;
+      if (bundled && !isNewer(entry.version, bundled.manifest.version)) break;
+      try {
+        return await layer.source.loadEntry(entry);
+      } catch (thrown) {
+        if (thrown instanceof RegistryError && thrown.code === DIAGNOSTIC_CODES.INTEGRITY_MISMATCH) {
+          throw thrown;
+        }
+        if (!bundled) throw thrown;
+        break;
+      }
+    }
+    return bundled;
+  }
+  async providersOf(capability) {
+    const all = await this.summaries();
+    return all.filter((summary) => summary.provides.includes(capability)).sort((a, b) => a.id < b.id ? -1 : 1);
+  }
+  async loadPreset(id) {
+    const local = await this.local.loadPreset(id);
+    if (local) return local;
+    for (const layer of this.remotes) {
+      const preset = await layer.source.loadPreset(id);
+      if (preset) return preset;
+    }
+    return this.bundled?.source.loadPreset(id);
+  }
+  /** Every preset visible from every layer, deduplicated by precedence — `atarashi list presets`. */
+  async presets() {
+    const merged = /* @__PURE__ */ new Map();
+    for (const preset of await this.bundled?.source.presets() ?? [])
+      merged.set(preset.id, preset);
+    for (const layer of this.remotes) {
+      const loaded = await layer.store.load().catch(() => void 0);
+      const presetEntries = loaded?.index.entries.filter((entry) => entry.kind === "preset") ?? [];
+      for (const entry of presetEntries) {
+        const preset = await layer.source.loadPreset(entry.id);
+        if (preset) merged.set(preset.id, preset);
+      }
+    }
+    for (const preset of await this.local.presets()) merged.set(preset.id, preset);
+    return [...merged.values()].sort((a, b) => a.id < b.id ? -1 : 1);
+  }
+  /**
+   * One place defines the range every blueprint uses. The registry's manifest
+   * wins over the bundled one; anything the registry does not pin keeps the
+   * bundled value, so an offline run resolves the same names.
+   */
+  async versionManifest() {
+    const bundled = this.bundled ? await readBundledVersionManifest(this.bundled.versionManifestPath) ?? {} : {};
+    const remote = await this.primary?.source.versionManifest() ?? {};
+    return { ...bundled, ...remote };
+  }
+  // ── Beyond the core interface ────────────────────────────────────────────
+  /** Every blueprint visible from every layer, deduplicated by precedence. */
+  async summaries() {
+    const merged = /* @__PURE__ */ new Map();
+    const put = (summary, overwrite) => {
+      const existing = merged.get(summary.id);
+      if (!existing || overwrite && isNewer(summary.version, existing.version)) {
+        merged.set(summary.id, summary);
+      }
+    };
+    for (const summary of await this.bundled?.source.summaries() ?? []) put(summary, false);
+    for (const layer of this.remotes) {
+      for (const summary of await layer.source.summaries()) put(summary, true);
+    }
+    for (const summary of await this.npm.summaries()) merged.set(summary.id, summary);
+    for (const summary of await this.local.summaries()) merged.set(summary.id, summary);
+    return [...merged.values()].sort((a, b) => a.id < b.id ? -1 : 1);
+  }
+  async list() {
+    return this.summaries();
+  }
+  /** Which layer an id resolves from, without loading its files. */
+  async originOf(id) {
+    if (await this.local.has(id)) return "local";
+    if (await this.npm.load(id).catch(() => void 0)) return "npm";
+    for (const layer of this.remotes) {
+      if (await layer.source.entry(id)) return "registry";
+    }
+    return await this.bundled?.source.load(id) ? "bundled" : void 0;
+  }
+  /** What gets written into `atarashi.json` so this run can be reproduced. */
+  async pin() {
+    if (!this.primary) return void 0;
+    try {
+      const { index, origin } = await this.primary.store.load();
+      const record = { version: index.version };
+      if (index.integrity) record.integrity = index.integrity;
+      if (origin.url !== DEFAULT_REGISTRY_URL) record.source = origin.url;
+      return record;
+    } catch {
+      return void 0;
+    }
+  }
+  /** `atarashi registry update` — ignore the TTL and re-check every source. */
+  async update() {
+    const results = [];
+    for (const layer of this.remotes) {
+      const { index, origin } = await layer.store.refresh();
+      results.push({ name: layer.name, version: index.version, from: origin.from });
+    }
+    return results;
+  }
+  /** `atarashi registry list` — every version this machine has verified. */
+  async cachedVersions() {
+    return this.cache.cachedIndexVersions();
+  }
+  verifyCache() {
+    return this.cache.verify();
+  }
+  clearCache() {
+    return this.cache.clear();
+  }
+  addNpmPackage(spec) {
+    this.npm.add(spec);
+    return this;
+  }
+};
+var isNewer = (candidate, incumbent) => valid(candidate) && valid(incumbent) ? gt(candidate, incumbent) : false;
+var createRegistry = (options = {}) => new Registry(options);
+
+export { DEFAULT_LIMITS, DEFAULT_REGISTRY_URL, DEFAULT_TTL_MS, DirectorySource, IndexStore, LOCAL_BLUEPRINTS_DIR, MANIFEST_FILE, NPM_PREFIX, NpmSource, PRESET_FILE, Registry, RegistryCache, RegistryError, RemoteSource, assertFetchable, cacheLayout, canonicalize, createBundledSource, createLocalSource, createRegistry, digest, entrySummary, extractTarball, findBundledRoot, hexDigest, httpGet, indexRootHash, integrityFailure, joinUrl, loadBlueprintDir, loadPresetFile, parseIntegrity, parseNpmSpec, readBundledVersionManifest, readTarball, resolveCacheRoot, safeEntryPath, slugifyId, summarize, unavailable, verifyIndexIntegrity, verifyIntegrity };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map