@ggui-ai/registry-server 0.1.0-rc.1

package/dist/filesystem-bundle-storage.js

@@ -0,0 +1,152 @@
+/**
+ * Filesystem-backed {@link BundleStorage} for the OSS registry server.
+ *
+ * Blob layout:
+ *
+ *   <root>/bundles/<scope>/<name>/<version>/bundle.js
+ *   <root>/bundles/<scope>/<name>/<version>/bundle.js.sig
+ *   <root>/bundles/<scope>/<name>/<version>/manifest.json
+ *
+ * Scope is written verbatim (`@my-org/...`) because the leading `@`
+ * is filename-safe on every supported OS. The URL composition mirrors
+ * the same path so the public URL the install CLI follows resolves
+ * directly against the file (the hono server's `/bundles/*` route
+ * streams the file).
+ *
+ * ## Path-traversal defense
+ *
+ * Every {scope, name, version} input is checked for `..`, `/`
+ * (except the leading scope `@` which contains no `/`), and `\\`.
+ * Scopes contain a single leading `@` then `[a-z0-9-]+` per the
+ * manifest schema; `name` is kebab-case; `version` is semver. We reject
+ * defensively at the storage layer in addition to the schema enforcement.
+ *
+ * ## Immutability
+ *
+ * Re-puts overwrite the file — the per-version row immutability
+ * invariant on {@link RegistryStorage.putArtifactVersionIfAbsent}
+ * prevents true re-publishes from ever reaching this layer, so
+ * overwrite-on-collision is safe (in practice unreachable).
+ *
+ * ## Protocol & Contract Bar
+ *
+ * Inherits the {@link BundleStorage} contract verbatim. The contract
+ * test exercises bundle / signature / manifest round-trips + URL
+ * composition + missing-blob reads (returns null, never throws).
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isGadgetSignature } from '@ggui-ai/gadget-signing';
+export function createFilesystemBundleStorage(options) {
+    const bundlesRoot = join(options.root, 'bundles');
+    const bundleHost = stripTrailingSlash(options.bundleHost);
+    const dirFor = (scope, name, version) => {
+        rejectTraversal(scope, 'scope');
+        rejectTraversal(name, 'name');
+        rejectTraversal(version, 'version');
+        return join(bundlesRoot, scope, name, version);
+    };
+    return {
+        async putBundle(scope, name, version, bytes) {
+            const dir = dirFor(scope, name, version);
+            await mkdir(dir, { recursive: true });
+            await writeFile(join(dir, 'bundle.js'), bytes);
+            return this.bundleUrl(scope, name, version);
+        },
+        async getBundle(scope, name, version) {
+            const path = join(dirFor(scope, name, version), 'bundle.js');
+            return readFileOrNull(path);
+        },
+        async putSignature(scope, name, version, signature) {
+            const dir = dirFor(scope, name, version);
+            await mkdir(dir, { recursive: true });
+            await writeFile(join(dir, 'bundle.js.sig'), JSON.stringify(signature, null, 2), 'utf8');
+            return this.signatureUrl(scope, name, version);
+        },
+        async getSignature(scope, name, version) {
+            const path = join(dirFor(scope, name, version), 'bundle.js.sig');
+            const text = await readTextOrNull(path);
+            if (text === null)
+                return null;
+            // Runtime-validate the parsed shape against the `GadgetSignature`
+            // union so a malformed on-disk signature can't slip through.
+            // Force-narrowing to `Ed25519Signature` would compile clean but
+            // would silently drop the sigstore-only fields of a sigstore
+            // signature, since both signature kinds persist here.
+            const parsed = JSON.parse(text);
+            if (!isGadgetSignature(parsed))
+                return null;
+            return parsed;
+        },
+        async putManifest(scope, name, version, manifest) {
+            const dir = dirFor(scope, name, version);
+            await mkdir(dir, { recursive: true });
+            await writeFile(join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
+            return this.manifestUrl(scope, name, version);
+        },
+        async getManifest(scope, name, version) {
+            const path = join(dirFor(scope, name, version), 'manifest.json');
+            const text = await readTextOrNull(path);
+            return text === null ? null : JSON.parse(text);
+        },
+        bundleUrl(scope, name, version) {
+            rejectTraversal(scope, 'scope');
+            rejectTraversal(name, 'name');
+            rejectTraversal(version, 'version');
+            return `${bundleHost}/bundles/${scope}/${name}/${version}/bundle.js`;
+        },
+        signatureUrl(scope, name, version) {
+            rejectTraversal(scope, 'scope');
+            rejectTraversal(name, 'name');
+            rejectTraversal(version, 'version');
+            return `${bundleHost}/bundles/${scope}/${name}/${version}/bundle.js.sig`;
+        },
+        manifestUrl(scope, name, version) {
+            rejectTraversal(scope, 'scope');
+            rejectTraversal(name, 'name');
+            rejectTraversal(version, 'version');
+            return `${bundleHost}/bundles/${scope}/${name}/${version}/manifest.json`;
+        },
+    };
+}
+/**
+ * Defensive path-traversal reject. `scope`, `name`, `version` are all
+ * regex-validated by the manifest schema at parse time. This is the
+ * second wall — if a caller bypasses the schema, the storage layer
+ * still rejects. Scope is allowed to contain a single `/` ONLY if it's
+ * the first character after `@` AND the value is exactly the canonical
+ * scope form — but scopes are `@ns` (no `/`), so `/` is unambiguously
+ * rejected here.
+ */
+function rejectTraversal(value, fieldName) {
+    if (value.includes('..') || value.includes('/') || value.includes('\\')) {
+        throw new Error(`path-traversal: filesystem bundle storage rejects ${fieldName}=${JSON.stringify(value)} (contains "..", "/", or "\\")`);
+    }
+}
+async function readFileOrNull(path) {
+    try {
+        const buf = await readFile(path);
+        return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+    }
+    catch (err) {
+        if (isErrnoException(err) && err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+async function readTextOrNull(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (err) {
+        if (isErrnoException(err) && err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+function stripTrailingSlash(s) {
+    return s.endsWith('/') ? s.slice(0, -1) : s;
+}
+function isErrnoException(err) {
+    return err instanceof Error && typeof err.code === 'string';
+}

package/dist/filesystem-registry-storage.d.ts

@@ -0,0 +1,7 @@
+import type { RegistryStorage } from '@ggui-ai/registry-core';
+export interface FilesystemRegistryStorageOptions {
+    /** Absolute path to the state root. Must already exist or be `mkdir -p`-able. */
+    readonly root: string;
+}
+export declare function createFilesystemRegistryStorage(options: FilesystemRegistryStorageOptions): RegistryStorage;
+//# sourceMappingURL=filesystem-registry-storage.d.ts.map

package/dist/filesystem-registry-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-registry-storage.d.ts","sourceRoot":"","sources":["../src/filesystem-registry-storage.ts"],"names":[],"mappings":"AA+DA,OAAO,KAAK,EAMV,eAAe,EAChB,MAAM,wBAAwB,CAAC;AAKhC,MAAM,WAAW,gCAAgC;IAC/C,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,gCAAgC,GACxC,eAAe,CAuLjB"}

package/dist/filesystem-registry-storage.js

@@ -0,0 +1,362 @@
+/**
+ * Filesystem-backed {@link RegistryStorage} for the OSS registry
+ * server. Row-per-file under `<root>/state/`:
+ *
+ *   <root>/state/plugins/<encoded artifactId>.json     → ArtifactsMetadataRow
+ *   <root>/state/versions/<encoded artifactId>__<v>.json → ArtifactVersionRow
+ *   <root>/state/author-keys/<subject>__<keyId>.json   → AuthorKeyRow
+ *
+ * The `__` separator is chosen because npm pkg names + semvers never
+ * contain it (semver disallows underscores entirely; npm names disallow
+ * leading underscores). `artifactId` contains `/` so we URL-encode the
+ * whole id; encoded form is filename-safe + reversible.
+ *
+ * ## Atomic conflict detection
+ *
+ * {@link putArtifactVersionIfAbsent} uses `fs.writeFile(..., { flag: 'wx' })`
+ * — the open(2) `O_EXCL` flag. `wx` fails with `EEXIST` if the file is
+ * already present, which we map to `{ ok: false, reason: 'version_exists' }`.
+ * Mirrors DDB's `ConditionExpression: attribute_not_exists(...)`. The
+ * happy-path write is atomic at the inode level — partial writes on
+ * crash leave the file absent rather than half-populated.
+ *
+ * ## Path-traversal defense
+ *
+ * Every `artifactId` is URL-encoded before becoming a filename, so
+ * `../` characters in arbitrary input are turned into `%2E%2E%2F` and
+ * cannot escape the directory. We also defensively reject any input
+ * containing literal `..`, `/`, or `\\` at the row-key boundary even
+ * though the manifest schema regex already rejects them — defense in
+ * depth, the cost is two `String#includes` calls per write.
+ *
+ * ## Scan semantics
+ *
+ * {@link scanArtifacts} reads every metadata file, applies the same
+ * AND-composition filter the memory impl does, and slices the result
+ * to `[offset, offset+limit)`. Cursor is an integer offset encoded as
+ * a base-10 string — opaque to consumers, identical to memory's
+ * encoding. For typical OSS deployments (< 10k artifacts) the full
+ * scan is sub-millisecond; large deployments should migrate to the
+ * cloud DDB adapter.
+ *
+ * ## Protocol & Contract Bar
+ *
+ * Inherits the {@link RegistryStorage} interface contract verbatim.
+ * Additional impl-specific obligations:
+ *
+ * **Obligations:**
+ * - Every method MUST be safe to call before the underlying directory
+ *   exists. The impl `mkdir -p`s on first write; reads return `null`
+ *   on `ENOENT` at any level.
+ *
+ * **Failure mode:**
+ * - Transport-level failures (disk full, permission denied) throw.
+ *   `publishArtifact` wraps and returns 500. `ENOENT` on a read is
+ *   NOT a transport failure — it's a "row absent" signal, returns `null`.
+ *
+ * **Observable violation:**
+ * - Contract test `filesystem-registry-storage.test.ts` runs the full
+ *   {@link registryStorageContract} suite against a fresh tmpdir per
+ *   test. Plus path-traversal rejection tests local to this file.
+ */
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 200;
+export function createFilesystemRegistryStorage(options) {
+    const stateRoot = join(options.root, 'state');
+    const pluginsDir = join(stateRoot, 'plugins');
+    const versionsDir = join(stateRoot, 'versions');
+    const authorKeysDir = join(stateRoot, 'author-keys');
+    // Content-addressed compiled-blob rows. Filenames are the 64-char
+    // hex digest + `.json`. The digest itself is filename-safe (hex
+    // chars only), so no URL-encoding is needed.
+    const compiledBlobsDir = join(stateRoot, 'compiled-blobs');
+    const compiledBlobPath = (compiledDigest) => {
+        rejectTraversal(compiledDigest, 'compiledDigest');
+        return join(compiledBlobsDir, `${compiledDigest}.json`);
+    };
+    const metadataPath = (artifactId) => join(pluginsDir, `${encodeRowKey(artifactId)}.json`);
+    const versionPath = (artifactId, version) => {
+        rejectTraversal(version, 'version');
+        return join(versionsDir, `${encodeRowKey(artifactId)}__${encodeRowKey(version)}.json`);
+    };
+    const authorKeyPath = (subject, keyId) => {
+        rejectTraversal(subject, 'subject');
+        rejectTraversal(keyId, 'keyId');
+        return join(authorKeysDir, `${encodeRowKey(subject)}__${encodeRowKey(keyId)}.json`);
+    };
+    return {
+        async getArtifactMetadata(artifactId) {
+            return readJsonOrNull(metadataPath(artifactId));
+        },
+        async putArtifactMetadata(row) {
+            await ensureDir(pluginsDir);
+            await writeJson(metadataPath(row.artifactId), row);
+        },
+        async scanArtifacts(filter) {
+            const rows = await readAllMetadata(pluginsDir);
+            const filtered = rows.filter((row) => rowMatchesFilter(row, filter));
+            const limit = clampLimit(filter.limit);
+            const offset = parseCursor(filter.cursor);
+            const page = filtered.slice(offset, offset + limit);
+            const nextOffset = offset + page.length;
+            const nextCursor = nextOffset < filtered.length ? String(nextOffset) : undefined;
+            return { rows: page, nextCursor };
+        },
+        async getArtifactVersion(artifactId, version) {
+            return readJsonOrNull(versionPath(artifactId, version));
+        },
+        async listArtifactVersions(artifactId) {
+            // Walk the versions/ directory; pick filenames whose URL-encoded
+            // artifactId prefix matches. The `__` separator is safe because
+            // semver versions never contain `__` (semver: ASCII alphanum +
+            // `.` + `-`) and the URL-encoded artifactId can't contain `__`
+            // either (encoder maps `_` → `_`, never doubles it).
+            const prefix = `${encodeRowKey(artifactId)}__`;
+            let entries;
+            try {
+                entries = await readdir(versionsDir);
+            }
+            catch (err) {
+                if (isErrnoException(err) && err.code === 'ENOENT')
+                    return [];
+                throw err;
+            }
+            const matches = [];
+            for (const entry of entries) {
+                if (!entry.startsWith(prefix) || !entry.endsWith('.json'))
+                    continue;
+                const row = await readJsonOrNull(join(versionsDir, entry));
+                if (row !== null)
+                    matches.push(row);
+            }
+            return matches;
+        },
+        async putArtifactVersionIfAbsent(row) {
+            await ensureDir(versionsDir);
+            const path = versionPath(row.artifactId, row.version);
+            try {
+                await writeFile(path, JSON.stringify(row, null, 2), {
+                    flag: 'wx',
+                    encoding: 'utf8',
+                });
+                return { ok: true };
+            }
+            catch (err) {
+                if (isErrnoException(err) && err.code === 'EEXIST') {
+                    return { ok: false, reason: 'version_exists' };
+                }
+                throw err;
+            }
+        },
+        async yankArtifactVersion(artifactId, version) {
+            const path = versionPath(artifactId, version);
+            const existing = await readJsonOrNull(path);
+            if (existing === null)
+                return;
+            const yanked = { ...existing, yanked: true };
+            await writeJson(path, yanked);
+        },
+        async getCompiledBlob(compiledDigest) {
+            return readJsonOrNull(compiledBlobPath(compiledDigest));
+        },
+        async commitVersionAndBlob(versionRow, blobRow) {
+            // Atomic write — the filesystem impl gets its atomicity from the
+            // JS event loop (single-writer assumption; the server runs one
+            // process). The version-row write goes first using `wx`
+            // (O_EXCL); on EEXIST we surface `version_exists` WITHOUT
+            // touching the blob row. If the version write succeeds, we then
+            // either INSERT a new blob row or read+rewrite the existing
+            // one's refCount.
+            await ensureDir(versionsDir);
+            await ensureDir(compiledBlobsDir);
+            const vPath = versionPath(versionRow.artifactId, versionRow.version);
+            try {
+                await writeFile(vPath, JSON.stringify(versionRow, null, 2), {
+                    flag: 'wx',
+                    encoding: 'utf8',
+                });
+            }
+            catch (err) {
+                if (isErrnoException(err) && err.code === 'EEXIST') {
+                    return { ok: false, reason: 'version_exists' };
+                }
+                throw err;
+            }
+            // Version row is durable. Now the blob row — INSERT-or-bump.
+            const blobFsPath = compiledBlobPath(blobRow.compiledDigest);
+            try {
+                await writeFile(blobFsPath, JSON.stringify(blobRow, null, 2), {
+                    flag: 'wx',
+                    encoding: 'utf8',
+                });
+                return { ok: true, mode: 'new-blob' };
+            }
+            catch (err) {
+                if (isErrnoException(err) && err.code === 'EEXIST') {
+                    // Dedup — read the existing row and bump refCount.
+                    const existing = await readJsonOrNull(blobFsPath);
+                    if (existing === null) {
+                        // Vanished between EEXIST and read — treat as race; the
+                        // single-writer OSS server doesn't have a delete path so
+                        // this is a corruption signal we surface as a throw.
+                        throw new Error(`commitVersionAndBlob: blob row vanished between EEXIST and read for compiledDigest=${blobRow.compiledDigest}`);
+                    }
+                    const updated = {
+                        ...existing,
+                        refCount: existing.refCount + 1,
+                    };
+                    await writeJson(blobFsPath, updated);
+                    return { ok: true, mode: 'dedup' };
+                }
+                throw err;
+            }
+        },
+        async getAuthorKey(subject, keyId) {
+            return readJsonOrNull(authorKeyPath(subject, keyId));
+        },
+        async putAuthorKey(row) {
+            await ensureDir(authorKeysDir);
+            await writeJson(authorKeyPath(row.subject, row.keyId), row);
+        },
+        async listAuthorKeys(subject) {
+            const prefix = `${encodeRowKey(subject)}__`;
+            let entries;
+            try {
+                entries = await readdir(authorKeysDir);
+            }
+            catch (err) {
+                if (isErrnoException(err) && err.code === 'ENOENT')
+                    return [];
+                throw err;
+            }
+            const matches = [];
+            for (const entry of entries) {
+                if (!entry.startsWith(prefix) || !entry.endsWith('.json'))
+                    continue;
+                const row = await readJsonOrNull(join(authorKeysDir, entry));
+                if (row !== null)
+                    matches.push(row);
+            }
+            return matches;
+        },
+    };
+}
+/**
+ * URL-encode the key. Filename-safe + reversible. `/` becomes `%2F`,
+ * `..` becomes `..` (allowed because the manifest schema rejects it
+ * before we ever get here, AND we `rejectTraversal` defensively) but
+ * even if it slipped through, the encoded form is what gets joined to
+ * the directory — `..` as a literal filename segment is just a file
+ * named `..`, not a directory traversal.
+ */
+function encodeRowKey(key) {
+    return encodeURIComponent(key);
+}
+/**
+ * Defensive path-traversal reject. The manifest schema regex blocks
+ * `..`, `/`, and `\\` at parse time. This is a second wall — if a
+ * caller bypasses the schema (programmatic injection from a fuzzed
+ * test, future row type added without schema coverage), the storage
+ * layer still rejects.
+ */
+function rejectTraversal(value, fieldName) {
+    if (value.includes('..') || value.includes('/') || value.includes('\\')) {
+        throw new Error(`path-traversal: filesystem storage rejects ${fieldName}=${JSON.stringify(value)} (contains "..", "/", or "\\")`);
+    }
+}
+async function ensureDir(dir) {
+    await mkdir(dir, { recursive: true });
+}
+async function readJsonOrNull(path) {
+    try {
+        const text = await readFile(path, 'utf8');
+        return JSON.parse(text);
+    }
+    catch (err) {
+        if (isErrnoException(err) && err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+async function writeJson(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(value, null, 2), 'utf8');
+}
+async function readAllMetadata(pluginsDir) {
+    let entries;
+    try {
+        entries = await readdir(pluginsDir);
+    }
+    catch (err) {
+        if (isErrnoException(err) && err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const rows = [];
+    for (const entry of entries) {
+        if (!entry.endsWith('.json'))
+            continue;
+        const row = await readJsonOrNull(join(pluginsDir, entry));
+        if (row !== null)
+            rows.push(row);
+    }
+    return rows;
+}
+function clampLimit(limit) {
+    if (limit === undefined)
+        return DEFAULT_LIMIT;
+    if (!Number.isInteger(limit))
+        return DEFAULT_LIMIT;
+    if (limit < 1)
+        return 1;
+    if (limit > MAX_LIMIT)
+        return MAX_LIMIT;
+    return limit;
+}
+function parseCursor(cursor) {
+    if (cursor === undefined || cursor.length === 0)
+        return 0;
+    const n = Number.parseInt(cursor, 10);
+    if (!Number.isInteger(n) || n < 0)
+        return 0;
+    return n;
+}
+/**
+ * Mirrors {@link inMemoryRegistryStorage}'s filter — same
+ * AND-composition, same case-insensitive substring match on q, same
+ * publisher-sub OR author-name match. Kept inline so the filesystem
+ * impl doesn't depend on a private helper from registry-core.
+ */
+function rowMatchesFilter(row, q) {
+    if (q.kind !== undefined && row.kind !== q.kind)
+        return false;
+    if (q.hook !== undefined && row.hook !== q.hook)
+        return false;
+    if (q.tag !== undefined) {
+        if (row.tags === undefined || !row.tags.includes(q.tag))
+            return false;
+    }
+    if (q.author !== undefined) {
+        const matchesSub = row.publishedBy === q.author;
+        const matchesName = row.authorName !== undefined &&
+            row.authorName.toLowerCase().includes(q.author.toLowerCase());
+        if (!matchesSub && !matchesName)
+            return false;
+    }
+    if (q.q !== undefined) {
+        const needle = q.q.toLowerCase();
+        const slashIdx = row.artifactId.indexOf('/');
+        const namePart = slashIdx >= 0 ? row.artifactId.slice(slashIdx + 1) : row.artifactId;
+        const inName = namePart.toLowerCase().includes(needle);
+        const inDescription = row.description !== undefined && row.description.toLowerCase().includes(needle);
+        const inTags = row.tags !== undefined && row.tags.some((t) => t.toLowerCase().includes(needle));
+        if (!inName && !inDescription && !inTags)
+            return false;
+    }
+    return true;
+}
+function isErrnoException(err) {
+    return err instanceof Error && typeof err.code === 'string';
+}

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import type { BlueprintProbeRunner, BundleStorage, RegistryStorage } from '@ggui-ai/registry-core';
+import type { BearerAuthn } from './authn/bearer.js';
+export { createBearerAuthn, type BearerAuthn, type CreateBearerAuthnOptions } from './authn/bearer.js';
+export { createFilesystemBundleStorage, type FilesystemBundleStorageOptions, } from './filesystem-bundle-storage.js';
+export { createFilesystemRegistryStorage, type FilesystemRegistryStorageOptions, } from './filesystem-registry-storage.js';
+export { createRegistryApp, type RegistryAppOptions } from './server.js';
+export interface CreateRegistryServerOptions {
+    readonly storage: RegistryStorage;
+    readonly bundleStorage: BundleStorage;
+    readonly authn: BearerAuthn;
+    /** Default: `'0.0.0.0'`. */
+    readonly host?: string;
+    /** Default: `9001`. Pass `0` to let the OS assign a free port. */
+    readonly port?: number;
+    /**
+     * Public URL prefix the install CLI / iframe runtime fetches bundles
+     * from. Typically `http://localhost:<port>` for local dev. Required
+     * because the server cannot reliably guess its own public address
+     * (operator may front it with a reverse proxy at a different host).
+     * No trailing slash.
+     */
+    readonly bundleHost: string;
+    /**
+     * Hostname (no protocol) embedded into the `installCommand` field of
+     * `POST /publish` responses. Example: `localhost:9001`, or
+     * `registry.example.com` behind a reverse proxy.
+     */
+    readonly registryHostname: string;
+    /** Wall-clock provider — overridable for deterministic tests. */
+    readonly clock?: () => Date;
+    /**
+     * Optional blueprint runtime probe. Wire `@ggui-ai/blueprint-probe`'s
+     * `blueprintProbeRunner` to enable the publish-time runtime gate.
+     * Forwarded to `createRegistryApp`.
+     *
+     * Intentionally opt-in: `vm.runInContext` is NOT a security boundary
+     * — sandboxed code can escape it (e.g. via
+     * `require('react').useState.constructor`). Wire this only when the
+     * trust boundary is the caller's process — e.g. CLI-local checks or
+     * e2e fixtures, not unauthenticated public publish endpoints.
+     */
+    readonly blueprintProbe?: BlueprintProbeRunner;
+}
+export interface RegistryServerHandle {
+    /** The port the server is actually bound to. Resolves after {@link start}. */
+    readonly actualPort: number;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare function createRegistryServer(options: CreateRegistryServerOptions): RegistryServerHandle;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EACV,oBAAoB,EACpB,aAAa,EACb,eAAe,EAChB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,KAAK,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AACvG,OAAO,EACL,6BAA6B,EAC7B,KAAK,8BAA8B,GACpC,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,+BAA+B,EAC/B,KAAK,gCAAgC,GACtC,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEzE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,oBAAoB,CAAC;CAChD;AAED,MAAM,WAAW,oBAAoB;IACnC,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,2BAA2B,GACnC,oBAAoB,CAiDtB"}

package/dist/index.js

@@ -0,0 +1,78 @@
+/**
+ * `@ggui-ai/registry-server` — self-hostable HTTP server for the ggui
+ * marketplace registry.
+ *
+ * Wraps `@ggui-ai/registry-core` with hono + filesystem storage +
+ * bearer-token auth. The hosted registry uses the same registry-core
+ * ops behind a different transport (a managed gateway, DynamoDB,
+ * object storage, and hosted auth).
+ *
+ * Two entry points:
+ *
+ *   - `createRegistryApp({...})`    — hono app object only (no port binding).
+ *                                     Use this when embedding inside an
+ *                                     existing hono / express / next.js server.
+ *
+ *   - `createRegistryServer({...})` — boots a `@hono/node-server` on a port.
+ *                                     Returns `{ start, stop, actualPort }`.
+ *                                     Use this for `npx @ggui-ai/registry-server`
+ *                                     + e2e fixtures + standalone deployments.
+ */
+import { serve } from '@hono/node-server';
+import { createRegistryApp } from './server.js';
+export { createBearerAuthn } from './authn/bearer.js';
+export { createFilesystemBundleStorage, } from './filesystem-bundle-storage.js';
+export { createFilesystemRegistryStorage, } from './filesystem-registry-storage.js';
+export { createRegistryApp } from './server.js';
+export function createRegistryServer(options) {
+    const app = createRegistryApp({
+        storage: options.storage,
+        bundleStorage: options.bundleStorage,
+        authn: options.authn,
+        registryHostname: options.registryHostname,
+        clock: options.clock,
+        ...(options.blueprintProbe !== undefined
+            ? { blueprintProbe: options.blueprintProbe }
+            : {}),
+    });
+    const host = options.host ?? '0.0.0.0';
+    const requestedPort = options.port ?? 9001;
+    // `actualPort` is mutable until `start()` resolves with the bound
+    // port — we expose a getter to keep the interface read-only.
+    let actualPort = requestedPort;
+    let server = null;
+    return {
+        get actualPort() {
+            return actualPort;
+        },
+        async start() {
+            if (server !== null)
+                return; // idempotent
+            await new Promise((resolve, reject) => {
+                try {
+                    server = serve({ fetch: app.fetch, hostname: host, port: requestedPort }, (info) => {
+                        actualPort = info.port;
+                        resolve();
+                    });
+                }
+                catch (err) {
+                    reject(err);
+                }
+            });
+        },
+        async stop() {
+            if (server === null)
+                return;
+            const s = server;
+            server = null;
+            await new Promise((resolve, reject) => {
+                s.close((err) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+            });
+        },
+    };
+}