handoff-app 1.2.2-7 → 2.0.0-0

package/dist/registry/checkout/tokens.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * Connected-workspace token checkout orchestration.
+ *
+ * `checkout tokens [setId]` pulls published token sets from the connected registry into this
+ * workspace: it reconstructs the canonical local `tokens.json` (splicing each set's record into the
+ * document) and restores the generated token files (CSS/SCSS/Style Dictionary/types/custom) to their
+ * standard configured output paths under `getVariablesFilePath()`. Overwriting changed local token
+ * data requires `--force` or an interactive confirmation. Available only from a connected workspace.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkoutTokens = void 0;
+const p = __importStar(require("@clack/prompts"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const logger_1 = require("../../utils/logger");
+const client_1 = require("../client");
+const path_2 = require("../path");
+const sets_1 = require("../tokens/sets");
+const index_1 = require("./index");
+/** Map a registry client error to an actionable checkout message. */
+const describeFetchFailure = (error, target, registryUrl) => {
+    switch (error.code) {
+        case 'not_found':
+            return `No token set "${target}" exists in the registry at ${registryUrl}.`;
+        case 'runtime_mode_conflict':
+            return `The registry at ${registryUrl} is not running in registry mode, so it cannot serve a checkout: ${error.message}`;
+        case 'unauthorized':
+            return `The registry rejected the access token (401). Check the configured access token matches the registry's token.`;
+        default:
+            return error.message;
+    }
+};
+/** Read the existing local token document, or `null` when none exists yet. */
+const readExistingDocument = (handoff) => {
+    const tokensFilePath = handoff.getTokensFilePath();
+    if (!fs_extra_1.default.existsSync(tokensFilePath)) {
+        return null;
+    }
+    try {
+        return JSON.parse(fs_extra_1.default.readFileSync(tokensFilePath, 'utf8'));
+    }
+    catch (_a) {
+        return null;
+    }
+};
+/** Whether writing `content` to `absolutePath` would change (or create) the file. */
+const wouldChange = (absolutePath, content) => {
+    if (!fs_extra_1.default.existsSync(absolutePath)) {
+        return true;
+    }
+    try {
+        return fs_extra_1.default.readFileSync(absolutePath, 'utf8') !== content;
+    }
+    catch (_a) {
+        return true;
+    }
+};
+/**
+ * Checkout all published token sets, or a single set when `setId` is given. Reconstructs `tokens.json`
+ * and restores generated files; prompts before overwriting changed local files unless `--force`.
+ */
+const checkoutTokens = (handoff, setId) => __awaiter(void 0, void 0, void 0, function* () {
+    if (setId && !(0, sets_1.isTokenSetId)(setId)) {
+        throw new index_1.CheckoutError(`Unknown or unsafe token set id "${setId}".`);
+    }
+    const connection = (0, index_1.resolveConnectionOrThrow)(handoff);
+    const client = (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken });
+    let ids;
+    if (setId) {
+        ids = [setId];
+    }
+    else {
+        const summaries = yield client.listTokenSets();
+        ids = summaries.map((summary) => summary.id);
+        if (ids.length === 0) {
+            logger_1.Logger.info('No token sets are published to the registry; nothing to checkout.');
+            return;
+        }
+    }
+    const payloads = [];
+    for (const id of ids) {
+        if (!(0, sets_1.isTokenSetId)(id)) {
+            throw new index_1.CheckoutError(`Registry returned an unknown or unsafe token set id "${id}".`);
+        }
+        try {
+            payloads.push(yield client.checkoutTokens(id));
+        }
+        catch (error) {
+            if (error instanceof client_1.RegistryClientError) {
+                throw new index_1.CheckoutError(describeFetchFailure(error, id, connection.url));
+            }
+            throw error;
+        }
+    }
+    const existingDoc = readExistingDocument(handoff);
+    const sets = payloads.map((payload) => ({ id: payload.id, kind: payload.kind, record: payload.record }));
+    const mergedDoc = (0, sets_1.mergeTokenSetsIntoDocument)(existingDoc, sets);
+    const mergedDocContent = `${JSON.stringify(mergedDoc, null, 2)}\n`;
+    const variablesDir = handoff.getVariablesFilePath();
+    const artifactWrites = payloads.flatMap((payload) => payload.artifacts.map((artifact) => {
+        const absolutePath = (0, path_2.resolvePathWithin)(variablesDir, artifact.path);
+        if (!absolutePath) {
+            throw new index_1.CheckoutError(`Registry returned an unsafe token artifact path "${artifact.path}".`);
+        }
+        return { absolutePath, content: artifact.content };
+    }));
+    const tokensFilePath = handoff.getTokensFilePath();
+    const changed = [];
+    if (wouldChange(tokensFilePath, mergedDocContent)) {
+        changed.push(tokensFilePath);
+    }
+    for (const write of artifactWrites) {
+        if (wouldChange(write.absolutePath, write.content)) {
+            changed.push(write.absolutePath);
+        }
+    }
+    const existingChanges = changed.filter((filePath) => fs_extra_1.default.existsSync(filePath));
+    if (existingChanges.length > 0 && !handoff.force) {
+        const proceed = yield p.confirm({
+            message: `Checkout will overwrite ${existingChanges.length} changed local token file(s). Continue?`,
+        });
+        if (p.isCancel(proceed) || proceed !== true) {
+            logger_1.Logger.info('Token checkout cancelled; no files were written.');
+            return;
+        }
+    }
+    yield fs_extra_1.default.ensureDir(path_1.default.dirname(tokensFilePath));
+    yield fs_extra_1.default.writeFile(tokensFilePath, mergedDocContent);
+    for (const write of artifactWrites) {
+        yield fs_extra_1.default.ensureDir(path_1.default.dirname(write.absolutePath));
+        yield fs_extra_1.default.writeFile(write.absolutePath, write.content);
+    }
+    logger_1.Logger.success(`Checked out ${ids.length} token set(s) into ${tokensFilePath} (${artifactWrites.length} generated file(s) restored).`);
+});
+exports.checkoutTokens = checkoutTokens;

package/dist/registry/client.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared registry HTTP client.
+ *
+ * One client both the CLI and the app use to talk to a remote registry over its HTTP API. It owns
+ * the transfer endpoint URL shape, bearer-token auth, and the `{ data | error, meta }` envelope
+ * decoding, mapping registry error responses to an actionable {@link RegistryClientError} so callers
+ * surface a clear message instead of a raw fetch failure. Transport is the global `fetch` (Node 18+
+ * and the browser both provide it), so this module stays runtime-agnostic.
+ */
+import type { CheckoutPayload, TransferEntityKind, TransferPackage } from './transfer';
+import type { TokenSetCheckoutPayload, TokenSetSummary, TokenSetTransferPackage } from './tokens/transfer';
+import type { AssetCollectionCheckoutPayload, AssetCollectionSummary, AssetCollectionTransferPackage } from './assets/transfer';
+/** Standard registry response envelope. */
+export interface RegistryEnvelope<T = unknown> {
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+    meta?: Record<string, unknown>;
+}
+/**
+ * A failed registry request. Carries the HTTP status and (when the server returned the registry
+ * error envelope) the registry error `code`/`details`, so callers can tailor messaging.
+ */
+export declare class RegistryClientError extends Error {
+    status?: number;
+    code?: string;
+    details?: Record<string, unknown>;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        details?: Record<string, unknown>;
+    });
+}
+export interface RegistryClientOptions {
+    /** Remote registry base URL (may include a configured basePath). */
+    baseUrl: string;
+    /** Bearer token sent on mutating requests. */
+    accessToken: string;
+}
+/** HTTP operations used by connected workspace publish and checkout workflows. */
+export interface RegistryClient {
+    publish(kind: TransferEntityKind, id: string, pkg: TransferPackage): Promise<RegistryEnvelope>;
+    checkout(kind: TransferEntityKind, id: string): Promise<CheckoutPayload>;
+    listTokenSets(): Promise<TokenSetSummary[]>;
+    publishTokens(pkg: TokenSetTransferPackage): Promise<RegistryEnvelope>;
+    checkoutTokens(id: string): Promise<TokenSetCheckoutPayload>;
+    listAssetCollections(): Promise<AssetCollectionSummary[]>;
+    assetBlobHaveCheck(hashes: string[]): Promise<string[]>;
+    uploadAssetBlob(hash: string, contentType: string, bytes: Buffer): Promise<void>;
+    downloadAssetBlob(hash: string): Promise<Buffer>;
+    publishAssetManifest(pkg: AssetCollectionTransferPackage): Promise<RegistryEnvelope>;
+    checkoutAssetCollection(collection: string): Promise<AssetCollectionCheckoutPayload>;
+}
+/**
+ * Build a registry HTTP client bound to one connection. Methods reject with a
+ * {@link RegistryClientError} on transport failure, non-2xx responses, or an error envelope.
+ */
+export declare const createRegistryClient: ({ baseUrl, accessToken }: RegistryClientOptions) => RegistryClient;

package/dist/registry/client.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * Shared registry HTTP client.
+ *
+ * One client both the CLI and the app use to talk to a remote registry over its HTTP API. It owns
+ * the transfer endpoint URL shape, bearer-token auth, and the `{ data | error, meta }` envelope
+ * decoding, mapping registry error responses to an actionable {@link RegistryClientError} so callers
+ * surface a clear message instead of a raw fetch failure. Transport is the global `fetch` (Node 18+
+ * and the browser both provide it), so this module stays runtime-agnostic.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRegistryClient = exports.RegistryClientError = void 0;
+/** Encode a token set id for the catch-all transfer route, preserving `/` between segments. */
+const encodeSetIdPath = (id) => id
+    .split('/')
+    .map((segment) => encodeURIComponent(segment))
+    .join('/');
+/**
+ * A failed registry request. Carries the HTTP status and (when the server returned the registry
+ * error envelope) the registry error `code`/`details`, so callers can tailor messaging.
+ */
+class RegistryClientError extends Error {
+    constructor(message, options = {}) {
+        super(message);
+        this.name = 'RegistryClientError';
+        this.status = options.status;
+        this.code = options.code;
+        this.details = options.details;
+    }
+}
+exports.RegistryClientError = RegistryClientError;
+/** Strip a single trailing slash so URL joining never doubles separators. */
+const trimTrailingSlash = (value) => value.replace(/\/+$/, '');
+/**
+ * Describe a transport-level fetch failure. `fetch` reports a generic "fetch failed"; the actionable
+ * detail (ECONNREFUSED / ECONNRESET / socket closed) lives on `error.cause`, so surface it.
+ */
+const describeNetworkError = (url, error) => {
+    const message = error instanceof Error ? error.message : 'network error';
+    const cause = error === null || error === void 0 ? void 0 : error.cause;
+    const detail = (cause === null || cause === void 0 ? void 0 : cause.code) || (cause === null || cause === void 0 ? void 0 : cause.message);
+    return `Could not reach the registry at ${url}: ${message}${detail ? ` (${detail})` : ''}.`;
+};
+const fetchRegistry = (url, init) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        return yield fetch(url, init);
+    }
+    catch (error) {
+        throw new RegistryClientError(describeNetworkError(url, error));
+    }
+});
+const readEnvelope = (response) => __awaiter(void 0, void 0, void 0, function* () {
+    const text = yield response.text();
+    if (!text) {
+        return {};
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (_a) {
+        return {};
+    }
+});
+const readErrorEnvelope = (response) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        return yield readEnvelope(response);
+    }
+    catch (_a) {
+        return {};
+    }
+});
+/**
+ * Build a registry HTTP client bound to one connection. Methods reject with a
+ * {@link RegistryClientError} on transport failure, non-2xx responses, or an error envelope.
+ */
+const createRegistryClient = ({ baseUrl, accessToken }) => {
+    const root = trimTrailingSlash(baseUrl);
+    const request = (method, path, body) => __awaiter(void 0, void 0, void 0, function* () {
+        var _a, _b, _c;
+        const url = `${root}${path}`;
+        const response = yield fetchRegistry(url, {
+            method,
+            headers: Object.assign({ 'Content-Type': 'application/json', Accept: 'application/json' }, (accessToken ? { Authorization: `Bearer ${accessToken}` } : {})),
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const envelope = yield readEnvelope(response);
+        if (!response.ok || envelope.error) {
+            const code = (_a = envelope.error) === null || _a === void 0 ? void 0 : _a.code;
+            const message = ((_b = envelope.error) === null || _b === void 0 ? void 0 : _b.message) || `Registry request failed (${response.status} ${response.statusText}).`;
+            throw new RegistryClientError(message, { status: response.status, code, details: (_c = envelope.error) === null || _c === void 0 ? void 0 : _c.details });
+        }
+        return envelope;
+    });
+    return {
+        /** Publish (`PUT`) an entity's package to the registry transfer endpoint. */
+        publish(kind, id, pkg) {
+            return request('PUT', `/api/registry/transfer/${kind}/${encodeURIComponent(id)}`, pkg);
+        },
+        /** Checkout (`GET`) an entity's normalized record + registry-safe source files. */
+        checkout(kind, id) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const envelope = yield request('GET', `/api/registry/transfer/${kind}/${encodeURIComponent(id)}`);
+                if (!envelope.data) {
+                    throw new RegistryClientError(`The registry returned no data for ${kind} "${id}".`);
+                }
+                return envelope.data;
+            });
+        },
+        /** List the registry's token sets (id + kind + source hash) for skip-unchanged / bulk checkout. */
+        listTokenSets() {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a, _b;
+                const envelope = yield request('GET', '/api/registry/transfer/tokens');
+                return (_b = (_a = envelope.data) === null || _a === void 0 ? void 0 : _a.sets) !== null && _b !== void 0 ? _b : [];
+            });
+        },
+        /** Publish (`PUT`) one token set's package (record + generated artifacts). */
+        publishTokens(pkg) {
+            return request('PUT', `/api/registry/transfer/tokens/${encodeSetIdPath(pkg.id)}`, pkg);
+        },
+        /** Checkout (`GET`) one token set's record + generated artifacts. */
+        checkoutTokens(id) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const envelope = yield request('GET', `/api/registry/transfer/tokens/${encodeSetIdPath(id)}`);
+                if (!envelope.data) {
+                    throw new RegistryClientError(`The registry returned no data for token set "${id}".`);
+                }
+                return envelope.data;
+            });
+        },
+        /** List the registry's asset collections (collection + source hash) for skip-unchanged / bulk checkout. */
+        listAssetCollections() {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a, _b;
+                const envelope = yield request('GET', '/api/registry/transfer/assets');
+                return (_b = (_a = envelope.data) === null || _a === void 0 ? void 0 : _a.collections) !== null && _b !== void 0 ? _b : [];
+            });
+        },
+        /** Ask which of the given content hashes the registry does not yet have (the blobs to upload). */
+        assetBlobHaveCheck(hashes) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a, _b;
+                const envelope = yield request('POST', '/api/registry/transfer/assets/blobs/have', { hashes });
+                return (_b = (_a = envelope.data) === null || _a === void 0 ? void 0 : _a.missing) !== null && _b !== void 0 ? _b : [];
+            });
+        },
+        /** Upload one content-addressed blob (binary-safe body). Idempotent: re-uploading an existing hash no-ops. */
+        uploadAssetBlob(hash, contentType, bytes) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a, _b;
+                const url = `${root}/api/registry/transfer/assets/blobs/${encodeURIComponent(hash)}`;
+                // Send a Blob, not a Buffer/Uint8Array: under Next `trailingSlash: true` this PUT is
+                // 308-redirected and undici must re-send the body; a typed-array body's ArrayBuffer is detached
+                // after the first send ("slice on a detached ArrayBuffer"), but a Blob is re-readable.
+                const body = new Blob([new Uint8Array(bytes)]);
+                const response = yield fetchRegistry(url, {
+                    method: 'PUT',
+                    headers: Object.assign({ 'Content-Type': contentType || 'application/octet-stream' }, (accessToken ? { Authorization: `Bearer ${accessToken}` } : {})),
+                    body,
+                });
+                if (!response.ok) {
+                    let code;
+                    let message = `Blob upload failed (${response.status} ${response.statusText}).`;
+                    const envelope = yield readErrorEnvelope(response);
+                    code = (_a = envelope === null || envelope === void 0 ? void 0 : envelope.error) === null || _a === void 0 ? void 0 : _a.code;
+                    message = ((_b = envelope === null || envelope === void 0 ? void 0 : envelope.error) === null || _b === void 0 ? void 0 : _b.message) || message;
+                    throw new RegistryClientError(message, { status: response.status, code });
+                }
+            });
+        },
+        /** Download one blob's raw bytes by hash (follows any provider redirect). */
+        downloadAssetBlob(hash) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const url = `${root}/api/registry/transfer/assets/blobs/${encodeURIComponent(hash)}`;
+                const response = yield fetchRegistry(url, {
+                    headers: Object.assign({}, (accessToken ? { Authorization: `Bearer ${accessToken}` } : {})),
+                });
+                if (!response.ok) {
+                    throw new RegistryClientError(`Blob download failed for "${hash}" (${response.status} ${response.statusText}).`, {
+                        status: response.status,
+                    });
+                }
+                return Buffer.from(yield response.arrayBuffer());
+            });
+        },
+        /** Publish (`PUT`) one asset collection's manifest (blobs must already be uploaded). */
+        publishAssetManifest(pkg) {
+            return request('PUT', `/api/registry/transfer/assets/${encodeURIComponent(pkg.collection)}`, pkg);
+        },
+        /** Checkout (`GET`) one asset collection's manifest. */
+        checkoutAssetCollection(collection) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const envelope = yield request('GET', `/api/registry/transfer/assets/${encodeURIComponent(collection)}`);
+                if (!envelope.data) {
+                    throw new RegistryClientError(`The registry returned no data for asset collection "${collection}".`);
+                }
+                return envelope.data;
+            });
+        },
+    };
+};
+exports.createRegistryClient = createRegistryClient;

package/dist/registry/connection.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Connected-workspace registry connection resolution.
+ *
+ * A connected workspace is `runtime.mode: 'workspace'` plus a `runtime.registryConnection` block
+ * pointing at a remote registry — it is not a third runtime mode. The connection is resolved from
+ * config + environment: the registry URL may be given inline or via an env-var *name*, and the
+ * access token is always read from an env-var name (never persisted as a value). This is the single
+ * source the publish (and later checkout) client reads its target + credentials from.
+ */
+import type { Config } from '../types/config';
+/** Default env-var name holding the remote registry base URL. */
+export declare const DEFAULT_REGISTRY_URL_ENV = "HANDOFF_REGISTRY_URL";
+/** Default env-var name holding the connected-workspace access token. */
+export declare const DEFAULT_REGISTRY_ACCESS_TOKEN_ENV = "HANDOFF_REGISTRY_ACCESS_TOKEN";
+/** Fully resolved connected-workspace registry connection. */
+export interface ResolvedRegistryConnection {
+    /** Resolved registry base URL (inline config value wins, else the named env var), or `''`. */
+    url: string;
+    /** Resolved access token value (from the named env var), or `''`. */
+    accessToken: string;
+    /** Name of the env var the URL falls back to. */
+    urlEnv: string;
+    /** Name of the env var the access token is read from. */
+    accessTokenEnv: string;
+}
+/**
+ * Resolve the connected-workspace registry connection from config + environment. Never throws —
+ * Callers inspect the resolved URL and access token to surface specific configuration errors.
+ */
+export declare const resolveRegistryConnection: (config: Config | null | undefined) => ResolvedRegistryConnection;

package/dist/registry/connection.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Connected-workspace registry connection resolution.
+ *
+ * A connected workspace is `runtime.mode: 'workspace'` plus a `runtime.registryConnection` block
+ * pointing at a remote registry — it is not a third runtime mode. The connection is resolved from
+ * config + environment: the registry URL may be given inline or via an env-var *name*, and the
+ * access token is always read from an env-var name (never persisted as a value). This is the single
+ * source the publish (and later checkout) client reads its target + credentials from.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRegistryConnection = exports.DEFAULT_REGISTRY_ACCESS_TOKEN_ENV = exports.DEFAULT_REGISTRY_URL_ENV = void 0;
+/** Default env-var name holding the remote registry base URL. */
+exports.DEFAULT_REGISTRY_URL_ENV = 'HANDOFF_REGISTRY_URL';
+/** Default env-var name holding the connected-workspace access token. */
+exports.DEFAULT_REGISTRY_ACCESS_TOKEN_ENV = 'HANDOFF_REGISTRY_ACCESS_TOKEN';
+/**
+ * Resolve the connected-workspace registry connection from config + environment. Never throws —
+ * Callers inspect the resolved URL and access token to surface specific configuration errors.
+ */
+const resolveRegistryConnection = (config) => {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const connection = (_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.registryConnection;
+    const urlEnv = ((_b = connection === null || connection === void 0 ? void 0 : connection.urlEnv) === null || _b === void 0 ? void 0 : _b.trim()) || exports.DEFAULT_REGISTRY_URL_ENV;
+    const accessTokenEnv = ((_c = connection === null || connection === void 0 ? void 0 : connection.accessTokenEnv) === null || _c === void 0 ? void 0 : _c.trim()) || exports.DEFAULT_REGISTRY_ACCESS_TOKEN_ENV;
+    const inlineUrl = (_d = connection === null || connection === void 0 ? void 0 : connection.url) === null || _d === void 0 ? void 0 : _d.trim();
+    const url = (_f = (inlineUrl || ((_e = process.env[urlEnv]) === null || _e === void 0 ? void 0 : _e.trim()))) !== null && _f !== void 0 ? _f : '';
+    const accessToken = (_h = (_g = process.env[accessTokenEnv]) === null || _g === void 0 ? void 0 : _g.trim()) !== null && _h !== void 0 ? _h : '';
+    return {
+        url,
+        accessToken,
+        urlEnv,
+        accessTokenEnv,
+    };
+};
+exports.resolveRegistryConnection = resolveRegistryConnection;

package/dist/registry/db/adapter.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Registry database adapter resolution.
+ *
+ * `runtime.registry.database.adapter` selects one of two built-in adapters shipped with the
+ * `handoff-app` package — `pg` (default) and `neon` — both targeting the Postgres dialect.
+ * `build --target registry` and `db:migrate` resolve the **same** adapter so build and migration
+ * never diverge. Connection credentials are referenced by environment-variable name only and
+ * resolved to a value at runtime; the value is never stored in config.
+ */
+import type { Config } from '../../types/config';
+/** Built-in registry database adapter. Both ship with the package and target Postgres. */
+export type RegistryDatabaseAdapter = 'pg' | 'neon';
+/** Default env-var name holding the database connection string. */
+export declare const DEFAULT_DATABASE_URL_ENV = "DATABASE_URL";
+/** Default env-var name holding the registry management API bearer token. */
+export declare const DEFAULT_REGISTRY_API_TOKEN_ENV = "HANDOFF_REGISTRY_API_TOKEN";
+/** Default registry database adapter when none is configured. */
+export declare const DEFAULT_REGISTRY_ADAPTER: RegistryDatabaseAdapter;
+/** Fully resolved registry database connection inputs. */
+export interface ResolvedRegistryDatabase {
+    /** Selected built-in adapter. */
+    adapter: RegistryDatabaseAdapter;
+    /** Name of the env var the connection string was read from. */
+    databaseUrlEnv: string;
+    /** Resolved connection string (never persisted in config). */
+    connectionString: string;
+}
+/** Resolve the env-var name holding the database URL (defaults to `DATABASE_URL`). */
+export declare const resolveDatabaseUrlEnv: (config: Config | null | undefined) => string;
+/**
+ * Resolve the env-var *name* holding the registry management API bearer token (defaults to
+ * `HANDOFF_REGISTRY_API_TOKEN`). Like the database URL, only the name is ever persisted — the token
+ * value is resolved from the environment at request time and never written to config.
+ */
+export declare const resolveApiTokenEnv: (config: Config | null | undefined) => string;
+/** Resolve the configured registry adapter (defaults to `pg`). */
+export declare const resolveRegistryAdapter: (config: Config | null | undefined) => RegistryDatabaseAdapter;
+/**
+ * Resolve the registry database connection from config + environment. Throws an actionable error
+ * when the configured env var is unset so the CLI can surface a clear "missing database URL"
+ * message instead of failing deep inside the driver.
+ */
+export declare const resolveRegistryDatabase: (config: Config | null | undefined) => ResolvedRegistryDatabase;

package/dist/registry/db/adapter.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Registry database adapter resolution.
+ *
+ * `runtime.registry.database.adapter` selects one of two built-in adapters shipped with the
+ * `handoff-app` package — `pg` (default) and `neon` — both targeting the Postgres dialect.
+ * `build --target registry` and `db:migrate` resolve the **same** adapter so build and migration
+ * never diverge. Connection credentials are referenced by environment-variable name only and
+ * resolved to a value at runtime; the value is never stored in config.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRegistryDatabase = exports.resolveRegistryAdapter = exports.resolveApiTokenEnv = exports.resolveDatabaseUrlEnv = exports.DEFAULT_REGISTRY_ADAPTER = exports.DEFAULT_REGISTRY_API_TOKEN_ENV = exports.DEFAULT_DATABASE_URL_ENV = void 0;
+/** Default env-var name holding the database connection string. */
+exports.DEFAULT_DATABASE_URL_ENV = 'DATABASE_URL';
+/** Default env-var name holding the registry management API bearer token. */
+exports.DEFAULT_REGISTRY_API_TOKEN_ENV = 'HANDOFF_REGISTRY_API_TOKEN';
+/** Default registry database adapter when none is configured. */
+exports.DEFAULT_REGISTRY_ADAPTER = 'pg';
+/** Resolve the env-var name holding the database URL (defaults to `DATABASE_URL`). */
+const resolveDatabaseUrlEnv = (config) => {
+    var _a, _b, _c;
+    const configured = (_c = (_b = (_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.registry) === null || _b === void 0 ? void 0 : _b.databaseUrlEnv) === null || _c === void 0 ? void 0 : _c.trim();
+    return configured || exports.DEFAULT_DATABASE_URL_ENV;
+};
+exports.resolveDatabaseUrlEnv = resolveDatabaseUrlEnv;
+/**
+ * Resolve the env-var *name* holding the registry management API bearer token (defaults to
+ * `HANDOFF_REGISTRY_API_TOKEN`). Like the database URL, only the name is ever persisted — the token
+ * value is resolved from the environment at request time and never written to config.
+ */
+const resolveApiTokenEnv = (config) => {
+    var _a, _b, _c;
+    const configured = (_c = (_b = (_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.registry) === null || _b === void 0 ? void 0 : _b.apiTokenEnv) === null || _c === void 0 ? void 0 : _c.trim();
+    return configured || exports.DEFAULT_REGISTRY_API_TOKEN_ENV;
+};
+exports.resolveApiTokenEnv = resolveApiTokenEnv;
+/** Resolve the configured registry adapter (defaults to `pg`). */
+const resolveRegistryAdapter = (config) => {
+    var _a, _b, _c, _d;
+    return (_d = (_c = (_b = (_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.registry) === null || _b === void 0 ? void 0 : _b.database) === null || _c === void 0 ? void 0 : _c.adapter) !== null && _d !== void 0 ? _d : exports.DEFAULT_REGISTRY_ADAPTER;
+};
+exports.resolveRegistryAdapter = resolveRegistryAdapter;
+/**
+ * Resolve the registry database connection from config + environment. Throws an actionable error
+ * when the configured env var is unset so the CLI can surface a clear "missing database URL"
+ * message instead of failing deep inside the driver.
+ */
+const resolveRegistryDatabase = (config) => {
+    var _a;
+    const adapter = (0, exports.resolveRegistryAdapter)(config);
+    const databaseUrlEnv = (0, exports.resolveDatabaseUrlEnv)(config);
+    const connectionString = (_a = process.env[databaseUrlEnv]) === null || _a === void 0 ? void 0 : _a.trim();
+    if (!connectionString) {
+        throw new Error(`Registry database URL is not configured. Set the "${databaseUrlEnv}" environment variable to a ` +
+            `PostgreSQL connection string (or change "runtime.registry.databaseUrlEnv" to point at the env var you use).`);
+    }
+    return { adapter, databaseUrlEnv, connectionString };
+};
+exports.resolveRegistryDatabase = resolveRegistryDatabase;

package/dist/registry/db/client.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Bundled Drizzle client + migrator for the registry database.
+ *
+ * The package ships both built-in adapters (`pg` and `neon`) and the Drizzle client/migrator, so a
+ * consuming project needs no global Drizzle install or separate CLI. Driver modules are loaded
+ * lazily (dynamic import) for the selected adapter only, so workspace dev/build never pulls the
+ * Postgres/Neon drivers into memory when the registry is not in use.
+ */
+import type { NeonDatabase } from 'drizzle-orm/neon-serverless';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type { RegistryDatabaseAdapter } from './adapter';
+import * as schema from './schema';
+/** Typed Drizzle database over the registry schema, regardless of which adapter backs it. */
+export type RegistryDatabase = NodePgDatabase<typeof schema> | NeonDatabase<typeof schema>;
+/** A live registry database connection plus its lifecycle operations. */
+export interface RegistryDbConnection {
+    /** Selected adapter that produced this connection. */
+    adapter: RegistryDatabaseAdapter;
+    /** Typed Drizzle database. */
+    db: RegistryDatabase;
+    /** Apply the package-owned migrations found in `migrationsFolder`. */
+    migrate(migrationsFolder: string): Promise<void>;
+    /** Close the underlying connection pool. */
+    close(): Promise<void>;
+}
+export interface CreateRegistryDbConnectionParams {
+    adapter: RegistryDatabaseAdapter;
+    connectionString: string;
+}
+/**
+ * Create a registry database connection for the resolved adapter. Both adapters target the
+ * Postgres dialect and share the same schema, so the returned connection is interchangeable for
+ * migration and (later) the registry store.
+ */
+export declare const createRegistryDbConnection: ({ adapter, connectionString, }: CreateRegistryDbConnectionParams) => Promise<RegistryDbConnection>;