@atarashi/registry 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gautam Suthar
+
+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

@@ -0,0 +1,81 @@
+# `@atarashi/registry`
+
+The only I/O boundary for blueprints. `@atarashi/core` asks this package for a
+`LoadedBlueprint` and never touches the disk or the network itself.
+
+```ts
+import { createRegistry } from '@atarashi/registry';
+import { generate } from '@atarashi/core';
+
+const registry = createRegistry({ cwd: process.cwd(), offline: false });
+const plan = await generate(spec, { source: registry, atarashiVersion });
+```
+
+## Four layers
+
+| Layer | Where | Trust |
+|---|---|---|
+| Local | `./.atarashi/blueprints/<ns>/<name>/blueprint.json` | Untrusted |
+| npm | `atarashi-blueprint-*` packages, by `npm:` spec | Untrusted |
+| Registry | `atarashi.gautamsuthar.in/registry`, verified and cached | Per source |
+| Bundled | `@atarashi/blueprints`, inside the npm package | Trusted |
+
+Local wins outright, so an author can override anything while developing. Then
+npm. Then the registry and the bundled collection compete on version: the newer
+one wins, which is how a registry release ships a blueprint fix without a CLI
+release, while a run with no network still resolves everything from the
+bundled copy.
+
+`trusted` is set by the *source*, never by the document the source serves. Only
+trusted blueprints may run hooks without explicit consent (doc 09, T2).
+
+## Integrity
+
+- The index carries a root hash over its canonicalized entries and version
+  manifest; it is re-verified on every read, including from the cache.
+- Every tarball is checked against its `sha256` digest before extraction.
+- A mismatch is a hard failure that names the artifact. There is no fallback
+  path to an unverified copy: unreachability degrades, tampering does not.
+
+## Extraction
+
+Archives are parsed entirely in memory and only written once every member has
+been validated: no absolute paths, drive letters, UNC paths, `..` segments,
+null bytes, symlinks or hard links; per-file, total-size and entry-count
+ceilings; case-collision detection; and a re-check that each resolved path is
+inside the destination. This is a security boundary; see `tests/extract.test.ts`.
+
+## Cache
+
+```
+$XDG_CACHE_HOME/atarashi/        # ~/Library/Caches on macOS, LOCALAPPDATA on Windows
+  index/1.4.2.json               # verified against its published root hash
+  blueprints/db-postgres-1.2.0-8f2c…/
+  meta.json                      # ETags, fetch timestamps
+```
+
+Content-addressed, so it is safe to share between projects and CI runs
+(`~/.cache/atarashi` makes a good CI cache key). Override with
+`ATARASHI_CACHE_DIR`.
+
+Freshness is a 24 h TTL plus an ETag: inside the TTL nothing is requested, and
+after it a `304` costs one conditional GET. A pinned version skips both: a
+published registry version is immutable, so a cache hit is always correct.
+
+## Offline
+
+`offline: true` or `ATARASHI_OFFLINE=1` skips the network entirely. Bundled
+blueprints and anything already cached still resolve; a registry-only blueprint
+reports what to run to populate the cache.
+
+## Publishing
+
+```bash
+pnpm --filter @atarashi/registry build:index      # pack, hash, emit v1/index.json
+pnpm --filter @atarashi/registry bump:versions    # propose version-manifest bumps
+```
+
+`build-index.mts` is deterministic (sorted members, fixed mtime, no uid/gid),
+so rebuilding the same sources produces byte-identical tarballs and the same
+digests. `.github/workflows/registry-publish.yml` publishes it and refuses to
+overwrite a version that already exists.

package/dist/index.d.ts

@@ -0,0 +1,477 @@
+import * as _atarashi_schema from '@atarashi/schema';
+import { RegistryIndex, Diagnostic, JsonValue, PresetManifest, BlueprintManifest, RegistryEntry, RegistrySource, RegistryPin } from '@atarashi/schema';
+import { LoadedBlueprint, BlueprintSummary, BlueprintSource } from '@atarashi/core';
+
+/** The default public registry. Overridable per-run and per-source. */
+declare const DEFAULT_REGISTRY_URL = "https://atarashi.gautamsuthar.in/registry";
+/** The index is re-checked at most once a day; pinned versions are immutable. */
+declare const DEFAULT_TTL_MS: number;
+interface CacheLayout {
+    root: string;
+    /** Verified index documents, one file per registry version. */
+    index: string;
+    /** Extracted blueprints, each directory named by its content hash. */
+    blueprints: string;
+    /** ETags and fetch timestamps. */
+    meta: string;
+}
+/**
+ * XDG on Linux, the platform convention elsewhere. `ATARASHI_CACHE_DIR` wins so
+ * CI can point the whole cache at a single restorable directory.
+ */
+declare function resolveCacheRoot(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;
+declare function cacheLayout(root: string): CacheLayout;
+/** `db/postgres` → `db-postgres`, so ids are usable as path and file names. */
+declare const slugifyId: (id: string) => string;
+
+/** What we remember between runs: ETags, fetch times and what is extracted. */
+interface CacheMeta {
+    metaVersion: 1;
+    index: Record<string, {
+        etag?: string;
+        fetchedAt: string;
+        version: string;
+    }>;
+    blueprints: Record<string, {
+        id: string;
+        version: string;
+        integrity: string;
+        dir: string;
+    }>;
+}
+/**
+ * The on-disk cache. Content-addressed: a blueprint directory is named by its
+ * tarball's hash, so entries for different versions never collide and the whole
+ * directory is safe to share between projects and CI runs.
+ */
+declare class RegistryCache {
+    readonly layout: CacheLayout;
+    private meta;
+    constructor(root: string);
+    readMeta(): Promise<CacheMeta>;
+    writeMeta(update: (meta: CacheMeta) => void): Promise<void>;
+    indexPath(version: string): string;
+    readIndex(version: string, source: string): Promise<RegistryIndex | undefined>;
+    writeIndex(index: RegistryIndex): Promise<void>;
+    /** Every registry version this machine has already verified. */
+    cachedIndexVersions(): Promise<string[]>;
+    /**
+     * 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: string, version: string, integrity: string): string;
+    hasBlueprint(id: string, version: string, integrity: string): boolean;
+    /**
+     * Verifies, extracts into a temp directory, then renames into place — so a
+     * cache directory only ever exists in its complete, verified form.
+     */
+    storeBlueprint(entry: {
+        id: string;
+        version: string;
+        integrity: string;
+    }, tarball: Buffer): Promise<string>;
+    clear(): Promise<void>;
+    /**
+     * 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.
+     */
+    verify(): Promise<{
+        checked: number;
+        removed: string[];
+    }>;
+    size(): Promise<number>;
+}
+
+/**
+ * Every failure that crosses the registry boundary. Carries a
+ * `DIAGNOSTIC_CODES` value so the CLI can map it to an exit code (6 for every
+ * registry failure, per doc 04) and the web builder to a UI affordance.
+ */
+declare class RegistryError extends Error {
+    readonly code: string;
+    readonly suggestions: string[];
+    readonly detail: string | undefined;
+    constructor(code: string, message: string, options?: {
+        suggestions?: string[];
+        detail?: string;
+        cause?: unknown;
+    });
+    toDiagnostic(): Diagnostic;
+}
+declare const unavailable: (message: string, suggestions?: string[]) => RegistryError;
+declare const integrityFailure: (message: string, detail?: string) => RegistryError;
+
+interface ExtractLimits {
+    /** Refuses archives with an absurd number of members. */
+    maxEntries: number;
+    /** Per-file ceiling. */
+    maxFileSize: number;
+    /** Total uncompressed bytes — the zip-bomb guard. */
+    maxTotalSize: number;
+}
+declare const DEFAULT_LIMITS: ExtractLimits;
+interface ExtractedFile {
+    path: string;
+    mode: number;
+    contents: Buffer;
+}
+/**
+ * The same path rules the writer applies to generated files, applied to archive
+ * members: no absolute paths, no drive letters, no `..`, no null bytes. This is
+ * a security boundary (doc 09, T1) — every rejection here is a hard failure,
+ * never a skipped entry.
+ */
+declare function safeEntryPath(raw: string, strip?: number): string | undefined;
+/**
+ * Parses a tarball entirely in memory. Nothing reaches the filesystem until
+ * every member has been validated, so a malicious archive cannot leave a
+ * half-extracted mess behind.
+ */
+declare function readTarball(tarball: Buffer, options?: {
+    strip?: number;
+    limits?: Partial<ExtractLimits>;
+}): Promise<ExtractedFile[]>;
+/**
+ * Writes a validated archive into `dest`. Every resolved path is re-checked
+ * against the destination root, so a bug in the path rules above still cannot
+ * write outside it.
+ */
+declare function extractTarball(tarball: Buffer, dest: string, options?: {
+    strip?: number;
+    limits?: Partial<ExtractLimits>;
+}): Promise<string[]>;
+
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+interface HttpResponse {
+    status: number;
+    body: Buffer;
+    etag: string | undefined;
+}
+/**
+ * TLS only, with no plaintext fallback (doc 09, T4). `file:` is allowed so a
+ * local mirror — and the test suite — can stand in for the CDN.
+ */
+declare function assertFetchable(url: string): URL;
+interface HttpOptions {
+    etag?: string | undefined;
+    timeoutMs?: number;
+    maxBytes?: number;
+    fetchImpl?: FetchLike;
+}
+/**
+ * A conditional GET. `304` comes back with an empty body and the caller keeps
+ * what it has cached; anything else is a registry failure with the URL named.
+ */
+declare function httpGet(url: string, options?: HttpOptions): Promise<HttpResponse>;
+/** Joins a registry base URL with a path, tolerating a trailing slash either way. */
+declare const joinUrl: (base: string, path: string) => string;
+
+interface IndexStoreOptions {
+    cache: RegistryCache;
+    url?: string;
+    /** Exact registry version to resolve against. Immutable once published. */
+    pin?: string | null;
+    offline?: boolean;
+    ttlMs?: number;
+    fetchImpl?: FetchLike;
+    now?: () => Date;
+    /** Third-party sources never get to run hooks, whatever their index says. */
+    trusted?: boolean;
+}
+/** Where a resolved index came from — reported by `atarashi doctor`. */
+interface IndexOrigin {
+    version: string;
+    url: string;
+    from: 'network' | 'cache' | 'bundled';
+    fetchedAt?: string;
+    integrity?: string;
+}
+/**
+ * Fetches, verifies and caches the registry index.
+ *
+ * Freshness is a 24 h TTL plus an ETag: inside the TTL nothing is requested at
+ * all, and after it a `304` costs one conditional GET. A pinned version skips
+ * both — it is immutable, so a cache hit is always correct.
+ */
+declare class IndexStore {
+    private readonly options;
+    private loaded;
+    readonly diagnostics: Diagnostic[];
+    constructor(options: IndexStoreOptions);
+    get url(): string;
+    get origin(): IndexOrigin | undefined;
+    /** Resolves once per process; subsequent calls reuse the verified document. */
+    load(): Promise<{
+        index: RegistryIndex;
+        origin: IndexOrigin;
+    }>;
+    /** Discards the TTL and re-checks the network — `atarashi registry update`. */
+    refresh(): Promise<{
+        index: RegistryIndex;
+        origin: IndexOrigin;
+    }>;
+    private loadPinned;
+    private loadLatest;
+    private parse;
+    private persist;
+    private touch;
+    private newestCached;
+    private isFresh;
+    private originOf;
+    private now;
+    private nowIso;
+}
+
+type HashAlgorithm = 'sha256' | 'sha384' | 'sha512';
+/** Subresource-integrity style digest: `sha256-<base64>`. */
+declare function digest(data: Buffer | string, algorithm?: HashAlgorithm): string;
+/** The hex form, used for content-addressed directory names. */
+declare function hexDigest(data: Buffer | string, algorithm?: HashAlgorithm): string;
+declare function parseIntegrity(value: string): {
+    algorithm: HashAlgorithm;
+    base64: string;
+};
+/**
+ * A mismatch is a hard failure that names the artifact — never a silent
+ * fallback to an unverified copy (doc 09, T4).
+ */
+declare function verifyIntegrity(data: Buffer, expected: string, what: string): void;
+/**
+ * Deterministic JSON: object keys sorted, no incidental whitespace. Two
+ * machines must produce the same bytes for the same document, or the root hash
+ * is meaningless.
+ */
+declare function canonicalize(value: JsonValue | unknown): string;
+/** The index's root hash covers its entries and its version manifest. */
+declare function indexRootHash(index: Pick<RegistryIndex, 'entries' | 'versionManifest' | 'version' | 'indexVersion'>): string;
+declare function verifyIndexIntegrity(index: RegistryIndex, source: string): void;
+
+declare const MANIFEST_FILE = "blueprint.json";
+declare const PRESET_FILE = "preset.json";
+interface DirectoryBlueprintOptions {
+    trusted: boolean;
+    /** Human-readable provenance for diagnostics. Defaults to the directory. */
+    origin?: string;
+}
+/** Loads one blueprint from a directory containing a `blueprint.json`. */
+declare function loadBlueprintDir(dir: string, options: DirectoryBlueprintOptions): Promise<LoadedBlueprint>;
+declare function loadPresetFile(path: string): Promise<PresetManifest>;
+declare const summarize: (manifest: BlueprintManifest) => BlueprintSummary;
+/**
+ * A tree of blueprints laid out as `<root>/<namespace>/<name>/blueprint.json`,
+ * with presets in `<root>/../presets/*.json`. Backs both the bundled collection
+ * and a project's own `./.atarashi/blueprints`.
+ */
+declare class DirectorySource {
+    readonly root: string;
+    private readonly options;
+    private manifests;
+    constructor(root: string, options: DirectoryBlueprintOptions & {
+        presetsDir?: string;
+    });
+    /** Scans lazily and once — a cold `atarashi list` should not pay twice. */
+    private scan;
+    ids(): Promise<string[]>;
+    has(id: string): Promise<boolean>;
+    load(id: string): Promise<LoadedBlueprint | undefined>;
+    summaries(): Promise<BlueprintSummary[]>;
+    loadPreset(id: string): Promise<PresetManifest | undefined>;
+    presets(): Promise<PresetManifest[]>;
+}
+
+/**
+ * The first-party collection shipped inside the npm package. Its presence is
+ * why `atarashi new` works on a plane: no index fetch, no tarball, no network.
+ */
+declare function findBundledRoot(explicit?: string): string | undefined;
+interface BundledSource {
+    source: DirectorySource;
+    root: string;
+    versionManifestPath: string;
+}
+declare function createBundledSource(explicit?: string): BundledSource | undefined;
+/**
+ * The bundled fallback for the registry's version manifest, so dependency
+ * ranges resolve offline exactly as they do online.
+ */
+declare function readBundledVersionManifest(path: string): Promise<Record<string, string> | undefined>;
+
+/** Where a project keeps blueprints it is developing or vendoring. */
+declare const LOCAL_BLUEPRINTS_DIR: string;
+/**
+ * Project-local blueprints win over every other source, so an author can
+ * override a published blueprint by dropping a directory in the project. They
+ * are untrusted all the same: being on disk is not review.
+ */
+declare function createLocalSource(cwd: string, dir?: string): DirectorySource;
+
+declare const NPM_PREFIX = "npm:";
+/** `npm:atarashi-blueprint-redis` → `atarashi-blueprint-redis`. */
+declare const parseNpmSpec: (spec: string) => string | undefined;
+/**
+ * A community blueprint published to npm. The package's `atarashi` field points
+ * at the directory holding its `blueprint.json`; everything else about it is
+ * treated as hostile — untrusted, so hooks require explicit consent.
+ */
+declare class NpmSource {
+    private readonly cwd;
+    private readonly packages;
+    private readonly cache;
+    private resolved;
+    constructor(cwd: string, packages?: string[]);
+    /** Adds a package for this run, e.g. from `--add npm:atarashi-blueprint-redis`. */
+    add(spec: string): this;
+    private loadPackage;
+    private all;
+    load(id: string): Promise<LoadedBlueprint | undefined>;
+    summaries(): Promise<BlueprintSummary[]>;
+}
+
+declare const entrySummary: (entry: RegistryEntry) => BlueprintSummary;
+/**
+ * Blueprints from the remote index. Resolution is index-only — capabilities,
+ * versions and conflicts all come from entry summaries — so nothing is
+ * downloaded until a blueprint is actually part of the graph.
+ */
+declare class RemoteSource {
+    private readonly store;
+    private readonly cache;
+    private readonly options;
+    constructor(store: IndexStore, cache: RegistryCache, options?: {
+        offline?: boolean;
+        fetchImpl?: FetchLike;
+        /** Set from the *source* config, never from the index it serves. */
+        trusted?: boolean;
+    });
+    /** `undefined` when the index cannot be reached at all — bundled still works. */
+    private index;
+    entry(id: string): Promise<RegistryEntry | undefined>;
+    summaries(): Promise<BlueprintSummary[]>;
+    versionManifest(): Promise<Record<string, string> | undefined>;
+    load(id: string): Promise<LoadedBlueprint | undefined>;
+    loadEntry(entry: RegistryEntry): Promise<LoadedBlueprint>;
+    preset(id: string): Promise<{
+        kind: "blueprint" | "preset";
+        name: string;
+        version: string;
+        description: string;
+        id: string;
+        category: string;
+        tags: string[];
+        experimental: boolean;
+        deprecated: boolean;
+        provides: string[];
+        requires: string[];
+        conflicts: string[];
+        engines: {
+            atarashi?: string | undefined;
+        };
+        tarball: string;
+        integrity: string;
+        bundled: boolean;
+    } | undefined>;
+    loadPreset(id: string): Promise<{
+        blueprints: string[];
+        kind: "preset";
+        name: string;
+        version: string;
+        description: string;
+        manifestVersion: number;
+        id: string;
+        tags: string[];
+        experimental: boolean;
+        recommended: boolean;
+        answers: Record<string, _atarashi_schema.JsonValue>;
+        deprecated?: {
+            since: string;
+            use?: string | undefined;
+            reason?: string | undefined;
+        } | null | undefined;
+    } | undefined>;
+    /** Downloads and verifies once; every later run is a cache hit. */
+    private materialize;
+}
+
+interface RegistryOptions {
+    /** The project directory — where local and npm blueprints are looked up. */
+    cwd?: string;
+    cacheDir?: string;
+    url?: string;
+    /** Exact registry version, from `atarashi.json` or `atarashi registry pin`. */
+    pin?: string | null;
+    offline?: boolean;
+    ttlMs?: number;
+    /** Extra third-party sources. Untrusted unless the user marked them trusted. */
+    sources?: RegistrySource[];
+    /** Community packages pulled in with `--add npm:atarashi-blueprint-x`. */
+    npmPackages?: string[];
+    bundledDir?: string;
+    localDir?: string;
+    fetchImpl?: FetchLike;
+    now?: () => Date;
+    env?: NodeJS.ProcessEnv;
+}
+/** Where a blueprint id was resolved from, for `atarashi info` and diagnostics. */
+type SourceKind = 'local' | 'npm' | 'registry' | 'bundled';
+/**
+ * The one I/O boundary for blueprints. Core asks this for a `LoadedBlueprint`
+ * and never touches disk or the network itself.
+ *
+ * Four layers, in precedence order:
+ *
+ * 1. `./.atarashi/blueprints` — a project's own, so an author can override
+ *    anything while developing.
+ * 2. `npm:` packages the user explicitly asked for.
+ * 3. the remote registry and the bundled collection, whichever has the newer
+ *    version — this is what lets a registry release ship a blueprint fix
+ *    without a CLI release, while a plane-mode run still works.
+ */
+declare class Registry implements BlueprintSource {
+    private readonly local;
+    private readonly npm;
+    private readonly bundled;
+    private readonly remotes;
+    private readonly primary;
+    readonly cache: RegistryCache;
+    readonly offline: boolean;
+    constructor(options?: RegistryOptions);
+    /** Warnings collected while resolving — degraded-network notices, mostly. */
+    get diagnostics(): Diagnostic[];
+    load(id: string): Promise<LoadedBlueprint | undefined>;
+    providersOf(capability: string): Promise<BlueprintSummary[]>;
+    loadPreset(id: string): Promise<PresetManifest | undefined>;
+    /** Every preset visible from every layer, deduplicated by precedence — `atarashi list presets`. */
+    presets(): Promise<PresetManifest[]>;
+    /**
+     * 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.
+     */
+    versionManifest(): Promise<Record<string, string>>;
+    /** Every blueprint visible from every layer, deduplicated by precedence. */
+    summaries(): Promise<BlueprintSummary[]>;
+    list(): Promise<BlueprintSummary[]>;
+    /** Which layer an id resolves from, without loading its files. */
+    originOf(id: string): Promise<SourceKind | undefined>;
+    /** What gets written into `atarashi.json` so this run can be reproduced. */
+    pin(): Promise<RegistryPin | undefined>;
+    /** `atarashi registry update` — ignore the TTL and re-check every source. */
+    update(): Promise<{
+        name: string;
+        version: string;
+        from: string;
+    }[]>;
+    /** `atarashi registry list` — every version this machine has verified. */
+    cachedVersions(): Promise<string[]>;
+    verifyCache(): Promise<{
+        checked: number;
+        removed: string[];
+    }>;
+    clearCache(): Promise<void>;
+    addNpmPackage(spec: string): this;
+}
+declare const createRegistry: (options?: RegistryOptions) => Registry;
+
+export { type CacheLayout, type CacheMeta, DEFAULT_LIMITS, DEFAULT_REGISTRY_URL, DEFAULT_TTL_MS, DirectorySource, type ExtractLimits, type ExtractedFile, type FetchLike, type HttpResponse, type IndexOrigin, IndexStore, type IndexStoreOptions, LOCAL_BLUEPRINTS_DIR, MANIFEST_FILE, NPM_PREFIX, NpmSource, PRESET_FILE, Registry, RegistryCache, RegistryError, type RegistryOptions, RemoteSource, type SourceKind, 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 };