handoff-app 2.0.0-1 → 2.0.0-3

package/dist/registry/checkout/index.js

@@ -2,7 +2,7 @@
 /**
  * Connected-workspace checkout orchestration.
  *
- * `checkout <component|pattern> <id>` reads a normalized registry record and its registry-safe
+ * `checkout <components|patterns> <id>` reads a normalized registry record and its registry-safe
  * source files from the connected registry through the shared registry client, then writes them
  * into the local workspace in standard authoring form. The local **declaration is synthesized
  * locally** in the configured `runtime.workspace.declarationFormat` — declarations are never read
@@ -60,10 +60,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.checkoutEntity = exports.resolveConnectionOrThrow = exports.CheckoutError = void 0;
+exports.checkoutEntities = exports.checkoutEntity = exports.resolveConnectionOrThrow = exports.CheckoutError = void 0;
 const p = __importStar(require("@clack/prompts"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
+const entries_1 = require("../../config/entries");
 const runtime_1 = require("../../config/runtime");
 const logger_1 = require("../../utils/logger");
 const client_1 = require("../client");
@@ -92,24 +93,24 @@ const COMPONENT_EXTENSION = /\.(tsx|jsx|ts|js|cjs|mjs)$/i;
  * host has no local workspace to write into) and a resolved registry URL + access token. Throws an
  * actionable {@link CheckoutError} naming the exact misconfiguration.
  */
-const resolveConnectionOrThrow = (handoff) => {
+const resolveConnectionOrThrow = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b, _c;
     const mode = (_c = (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.runtime) === null || _b === void 0 ? void 0 : _b.mode) !== null && _c !== void 0 ? _c : 'workspace';
     if (mode !== 'workspace') {
         throw new CheckoutError(`checkout is only available from a connected workspace (runtime.mode: "workspace"); this project is "${mode}". ` +
             'A registry host stores and serves entities; it has no local workspace to check them out into.');
     }
-    const connection = (0, connection_1.resolveRegistryConnection)(handoff.config);
+    const connection = yield (0, connection_1.resolveAuthenticatedRegistryConnection)(handoff.config, handoff.workingPath);
     if (!connection.url) {
-        throw new CheckoutError(`No registry URL is configured. Set runtime.registryConnection.url, or the "${connection.urlEnv}" environment variable, ` +
-            'to the base URL of the registry to checkout from.');
+        throw new CheckoutError(`No registry is configured. Run \`handoff-app login --url <registry-url>\`, set runtime.registryConnection.url, ` +
+            `or set the "${connection.urlEnv}" environment variable to the base URL of the registry to checkout from.`);
     }
     if (!connection.accessToken) {
-        throw new CheckoutError(`No registry access token is configured. Set the "${connection.accessTokenEnv}" environment variable to the ` +
-            "registry's bearer token to authorize checkout.");
+        throw new CheckoutError(`No registry access token is configured. Run \`handoff-app login --url ${connection.url}\`, or set the ` +
+            `"${connection.accessTokenEnv}" environment variable to a user-issued token for CI.`);
     }
     return connection;
-};
+});
 exports.resolveConnectionOrThrow = resolveConnectionOrThrow;
 /** Map a registry client error to an actionable checkout message. */
 const describeFetchFailure = (error, kind, id, registryUrl) => {
@@ -119,28 +120,69 @@ const describeFetchFailure = (error, kind, id, 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.`;
+            return `The registry rejected the access token (401). Run \`handoff-app login --url ${registryUrl}\` again, or replace the user-issued CI token.`;
+        case 'forbidden':
+            return `The registry token does not have permission to checkout this content (403). Authorize a token with registry:read access.`;
         default:
             return error.message;
     }
 };
 /**
- * Resolve the local directory the entity is written into: an already-checked-out / locally-declared
- * entity keeps its existing source directory (matched by stable `id`); otherwise it lands under the
- * first configured `entries.{components|patterns}` root (falling back to `components`/`patterns`).
+ * Ask the user which collection directory a new entity should land in when the config is ambiguous.
+ * Under `--force` (or any non-interactive run) there's no one to ask, so we fail with an actionable
+ * message rather than guessing a root.
  */
-const resolveTargetDir = (handoff, kind, id) => __awaiter(void 0, void 0, void 0, function* () {
+const promptForCollectionRoot = (handoff, kind, roots) => __awaiter(void 0, void 0, void 0, function* () {
+    const relative = (root) => path_1.default.relative(handoff.workingPath, root) || '.';
+    if (handoff.force) {
+        throw new CheckoutError(`Cannot determine where to checkout the ${kind}: entries.${kind}s declares individual ${kind}s under different ` +
+            `directories (${roots.map(relative).join(', ')}). Declare a single collection directory in handoff.config, ` +
+            `or run checkout without --force to choose interactively.`);
+    }
+    const choice = yield p.select({
+        message: `Where should the new ${kind} be checked out?`,
+        options: roots.map((root) => ({ value: root, label: relative(root) })),
+        initialValue: roots[0],
+    });
+    if (p.isCancel(choice)) {
+        throw new CheckoutError('Checkout cancelled; no target directory chosen.');
+    }
+    return choice;
+});
+/**
+ * Resolve the collection directory a new entity is cloned into from the configured
+ * `entries.{components|patterns}`. Each entry is either a collection directory (used as-is) or a
+ * single declared entity directory, in which case its parent is the collection root so the new
+ * entity lands as a sibling rather than nested inside. Different parents mean the config is
+ * ambiguous, so we ask the user; with nothing configured we fall back to the default subdir.
+ */
+const resolveCollectionRoot = (handoff, kind) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b, _c, _d;
+    const configuredRoots = kind === 'component' ? (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components : (_d = (_c = handoff.config) === null || _c === void 0 ? void 0 : _c.entries) === null || _d === void 0 ? void 0 : _d.patterns;
+    if (!(configuredRoots === null || configuredRoots === void 0 ? void 0 : configuredRoots.length)) {
+        return path_1.default.resolve(handoff.workingPath, DEFAULT_ENTITY_DIR[kind]);
+    }
+    const roots = [
+        ...new Set(configuredRoots.map((entry) => {
+            const resolved = path_1.default.resolve(handoff.workingPath, entry);
+            return (0, runtime_1.isComponentDirectory)(resolved) ? path_1.default.dirname(resolved) : resolved;
+        })),
+    ];
+    return roots.length === 1 ? roots[0] : promptForCollectionRoot(handoff, kind, roots);
+});
+/**
+ * Resolve the local directory the entity is written into. An already-checked-out or locally-declared
+ * entity keeps its existing source directory (matched by stable `id`); otherwise it lands as a
+ * sibling under its configured collection root (see {@link resolveCollectionRoot}).
+ */
+const resolveTargetDir = (handoff, kind, id) => __awaiter(void 0, void 0, void 0, function* () {
     const store = kind === 'component' ? handoff.store.components : handoff.store.patterns;
     const existing = yield store.get(id);
     const existingDir = existing === null || existing === void 0 ? void 0 : existing.path;
     if (existingDir) {
         return existingDir;
     }
-    const configuredRoots = kind === 'component' ? (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components : (_d = (_c = handoff.config) === null || _c === void 0 ? void 0 : _c.entries) === null || _d === void 0 ? void 0 : _d.patterns;
-    const root = (configuredRoots === null || configuredRoots === void 0 ? void 0 : configuredRoots.length)
-        ? path_1.default.resolve(handoff.workingPath, configuredRoots[0])
-        : path_1.default.resolve(handoff.workingPath, DEFAULT_ENTITY_DIR[kind]);
+    const root = yield resolveCollectionRoot(handoff, kind);
     const targetDir = (0, path_2.resolvePathWithin)(root, id);
     if (!targetDir) {
         throw new CheckoutError(`Cannot checkout ${kind} with unsafe id "${id}".`);
@@ -551,33 +593,33 @@ const checkoutPage = (handoff, id, payload) => __awaiter(void 0, void 0, void 0,
     logger_1.Logger.success(`Checked out page "${id}" into ${path_1.default.relative(handoff.workingPath, pagesRoot) || '.'} ` + `(${payload.files.length} markdown file(s)).`);
 });
 /**
- * Checkout a single component or pattern from a connected workspace: precondition checks → fetch the
- * normalized record + source files → resolve the local target → explicit-overwrite guard → write
- * source files and synthesize the local declaration. Throws {@link CheckoutError} with actionable
- * messaging on any precondition or fetch failure.
+ * Checkout one entity through an already-resolved client: precondition checks → fetch the normalized
+ * record + source files → resolve the local target → explicit-overwrite guard → write source files
+ * and synthesize the local declaration. Shared by the single-id and bulk entry points so both behave
+ * identically. Throws {@link CheckoutError} with actionable messaging on any precondition or fetch
+ * failure.
  */
-const checkoutEntity = (handoff, kind, id) => __awaiter(void 0, void 0, void 0, function* () {
+const checkoutSingle = (handoff, kind, id, client, registryUrl) => __awaiter(void 0, void 0, void 0, function* () {
     const validId = kind === 'page' ? (0, path_2.isSafeRelativePath)(id) : (0, path_2.isSafePathSegment)(id);
     if (!validId) {
         throw new CheckoutError(`Cannot checkout ${kind} with unsafe id "${id}".`);
     }
-    const connection = (0, exports.resolveConnectionOrThrow)(handoff);
-    logger_1.Logger.info(`Fetching ${kind} "${id}" from ${connection.url}…`);
-    const client = (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken });
+    logger_1.Logger.info(`Fetching ${kind} "${id}" from ${registryUrl}…`);
     let payload;
     try {
         payload = yield client.checkout(kind, id);
     }
     catch (error) {
         if (error instanceof client_1.RegistryClientError) {
-            throw new CheckoutError(describeFetchFailure(error, kind, id, connection.url));
+            throw new CheckoutError(describeFetchFailure(error, kind, id, registryUrl));
         }
         throw error;
     }
-    // Pages round-trip as a single verbatim `.md` with no declaration synthesis.
+    // Pages round-trip as a single verbatim `.md` with no declaration synthesis, and aren't
+    // declared in `entries`, so there's nothing to register.
     if (kind === 'page') {
         yield checkoutPage(handoff, id, payload);
-        return;
+        return null;
     }
     const targetDir = yield resolveTargetDir(handoff, kind, id);
     const format = resolveDeclarationFormat(handoff, targetDir);
@@ -594,7 +636,7 @@ const checkoutEntity = (handoff, kind, id) => __awaiter(void 0, void 0, void 0,
     const conflicts = [...sourceTargets.map((entry) => entry.absolutePath), declarationPath].filter((file) => fs_extra_1.default.existsSync(file));
     if (!(yield confirmOverwrite(handoff, conflicts))) {
         logger_1.Logger.warn(`Checkout of ${kind} "${id}" cancelled; no files were written.`);
-        return;
+        return null;
     }
     yield fs_extra_1.default.ensureDir(targetDir);
     const written = [];
@@ -606,5 +648,92 @@ const checkoutEntity = (handoff, kind, id) => __awaiter(void 0, void 0, void 0,
     written.push(declarationPath);
     logger_1.Logger.success(`Checked out ${kind} "${id}" into ${path_1.default.relative(handoff.workingPath, targetDir) || '.'} ` +
         `(${payload.files.length} source file(s) + ${declarationFileName}).`);
+    return targetDir;
+});
+/**
+ * Declare freshly checked-out entities in `entries.{components|patterns}` so the workspace build
+ * picks them up. Ones already covered by a collection directory load on their own and are left
+ * alone; the rest are added to the config automatically. If the config can't be edited (a computed
+ * or unusual `entries` array), we print the paths for the user to add so nothing is silently orphaned.
+ */
+const registerCheckedOut = (handoff, kind, targetDirs) => __awaiter(void 0, void 0, void 0, function* () {
+    if (kind === 'page') {
+        return;
+    }
+    const entryKind = kind === 'component' ? 'components' : 'patterns';
+    const uncovered = targetDirs.filter((dir) => !(0, entries_1.isEntryCovered)(handoff, entryKind, dir));
+    if (uncovered.length === 0) {
+        return;
+    }
+    const result = yield (0, entries_1.writeEntries)(handoff, entryKind, uncovered);
+    if (result.status === 'added') {
+        const where = result.configPath ? path_1.default.relative(handoff.workingPath, result.configPath) || path_1.default.basename(result.configPath) : 'handoff.config';
+        logger_1.Logger.success(`Updated ${where} with ${result.added.length} ${entryKind} path(s).`);
+        return;
+    }
+    const where = result.configPath ? path_1.default.relative(handoff.workingPath, result.configPath) : 'handoff.config';
+    logger_1.Logger.warn(`Could not update ${where} automatically. Add these to entries.${entryKind} manually:`);
+    result.pending.forEach((rel) => logger_1.Logger.warn(`  - ${rel}`));
+});
+/**
+ * Checkout a single component, pattern, or page from the connected registry into this workspace.
+ * Overwriting existing local files requires `--force` or an interactive confirmation.
+ */
+const checkoutEntity = (handoff, kind, id) => __awaiter(void 0, void 0, void 0, function* () {
+    const connection = yield (0, exports.resolveConnectionOrThrow)(handoff);
+    const client = (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken });
+    const targetDir = yield checkoutSingle(handoff, kind, id, client, connection.url);
+    if (targetDir) {
+        yield registerCheckedOut(handoff, kind, [targetDir]);
+    }
 });
 exports.checkoutEntity = checkoutEntity;
+/**
+ * Checkout every published component, pattern, or page of the kind into this workspace. Enumerates
+ * the registry's published ids, then checks each out through the shared client. A per-entity failure
+ * is collected and never aborts the rest; the run throws at the end if any entity failed. Overwrite
+ * prompting is per entity (skipped under `--force`).
+ */
+const checkoutEntities = (handoff, kind) => __awaiter(void 0, void 0, void 0, function* () {
+    const connection = yield (0, exports.resolveConnectionOrThrow)(handoff);
+    const client = (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken });
+    let summaries;
+    try {
+        summaries = yield client.listEntities(kind);
+    }
+    catch (error) {
+        if (error instanceof client_1.RegistryClientError) {
+            throw new CheckoutError(`Could not list ${kind}s from the registry at ${connection.url}: ${error.message}`);
+        }
+        throw error;
+    }
+    if (summaries.length === 0) {
+        logger_1.Logger.success(`No ${kind}s are published in the registry; nothing to checkout.`);
+        return;
+    }
+    let checkedOut = 0;
+    const failed = [];
+    const targetDirs = [];
+    for (const { id } of summaries) {
+        try {
+            const targetDir = yield checkoutSingle(handoff, kind, id, client, connection.url);
+            if (targetDir) {
+                targetDirs.push(targetDir);
+            }
+            checkedOut += 1;
+        }
+        catch (error) {
+            failed.push({ id, message: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    // Register everything checked out in one pass, so the config is edited (and confirmed) once.
+    yield registerCheckedOut(handoff, kind, targetDirs);
+    logger_1.Logger.success(`${kind[0].toUpperCase()}${kind.slice(1)}s checkout complete — ${checkedOut} checked out${failed.length ? `, ${failed.length} failed` : ''}.`);
+    if (failed.length > 0) {
+        for (const failure of failed) {
+            logger_1.Logger.error(`  - ${failure.id}: ${failure.message}`);
+        }
+        throw new CheckoutError(`${failed.length} ${kind}(s) failed to checkout.`);
+    }
+});
+exports.checkoutEntities = checkoutEntities;

package/dist/registry/checkout/tokens.js

@@ -61,7 +61,9 @@ const describeFetchFailure = (error, target, 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.`;
+            return `The registry rejected the access token (401). Run \`handoff-app login --url ${registryUrl}\` again, or replace the user-issued CI token.`;
+        case 'forbidden':
+            return `The registry token does not have permission to checkout design tokens (403). Authorize a token with registry:read access.`;
         default:
             return error.message;
     }
@@ -99,7 +101,7 @@ const checkoutTokens = (handoff, setId) => __awaiter(void 0, void 0, void 0, fun
     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 connection = yield (0, index_1.resolveConnectionOrThrow)(handoff);
     const client = (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken });
     let ids;
     if (setId) {

package/dist/registry/client.d.ts

@@ -7,7 +7,7 @@
  * 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 { CheckoutPayload, EntitySummary, TransferEntityKind, TransferPackage } from './transfer';
 import type { TokenSetCheckoutPayload, TokenSetSummary, TokenSetTransferPackage } from './tokens/transfer';
 import type { AssetCollectionCheckoutPayload, AssetCollectionSummary, AssetCollectionTransferPackage } from './assets/transfer';
 /** Standard registry response envelope. */
@@ -44,6 +44,7 @@ export interface RegistryClientOptions {
 export interface RegistryClient {
     publish(kind: TransferEntityKind, id: string, pkg: TransferPackage): Promise<RegistryEnvelope>;
     checkout(kind: TransferEntityKind, id: string): Promise<CheckoutPayload>;
+    listEntities(kind: TransferEntityKind): Promise<EntitySummary[]>;
     listTokenSets(): Promise<TokenSetSummary[]>;
     publishTokens(pkg: TokenSetTransferPackage): Promise<RegistryEnvelope>;
     checkoutTokens(id: string): Promise<TokenSetCheckoutPayload>;

package/dist/registry/client.js

@@ -115,6 +115,14 @@ const createRegistryClient = ({ baseUrl, accessToken }) => {
                 return envelope.data;
             });
         },
+        /** List the registry's entities of one kind (id + build hashes) for skip-unchanged / bulk checkout. */
+        listEntities(kind) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a, _b;
+                const envelope = yield request('GET', `/api/registry/transfer/${kind}`);
+                return (_b = (_a = envelope.data) === null || _a === void 0 ? void 0 : _a.entities) !== null && _b !== void 0 ? _b : [];
+            });
+        },
         /** List the registry's token sets (id + kind + source hash) for skip-unchanged / bulk checkout. */
         listTokenSets() {
             return __awaiter(this, void 0, void 0, function* () {

package/dist/registry/connection.d.ts

@@ -28,3 +28,12 @@ export interface ResolvedRegistryConnection {
  * Callers inspect the resolved URL and access token to surface specific configuration errors.
  */
 export declare const resolveRegistryConnection: (config: Config | null | undefined) => ResolvedRegistryConnection;
+/**
+ * Resolve the same connection for an authenticated CLI operation, letting a saved device login fill
+ * in what the environment does not provide. A valid login supplies both the registry URL and the
+ * access token, so `handoff-app login` alone is enough to publish and checkout. Environment values
+ * keep precedence for deterministic CI: `HANDOFF_REGISTRY_URL` (or inline config) wins over the
+ * saved URL, and `HANDOFF_REGISTRY_ACCESS_TOKEN` wins over the saved token. The saved token only
+ * applies to the URL it was issued for.
+ */
+export declare const resolveAuthenticatedRegistryConnection: (config: Config | null | undefined, workingPath?: string) => Promise<ResolvedRegistryConnection>;

package/dist/registry/connection.js

@@ -8,8 +8,18 @@
  * 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.
  */
+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.resolveRegistryConnection = exports.DEFAULT_REGISTRY_ACCESS_TOKEN_ENV = exports.DEFAULT_REGISTRY_URL_ENV = void 0;
+exports.resolveAuthenticatedRegistryConnection = exports.resolveRegistryConnection = exports.DEFAULT_REGISTRY_ACCESS_TOKEN_ENV = exports.DEFAULT_REGISTRY_URL_ENV = void 0;
+const store_1 = require("../cli/auth/store");
 /** 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. */
@@ -34,3 +44,21 @@ const resolveRegistryConnection = (config) => {
     };
 };
 exports.resolveRegistryConnection = resolveRegistryConnection;
+/**
+ * Resolve the same connection for an authenticated CLI operation, letting a saved device login fill
+ * in what the environment does not provide. A valid login supplies both the registry URL and the
+ * access token, so `handoff-app login` alone is enough to publish and checkout. Environment values
+ * keep precedence for deterministic CI: `HANDOFF_REGISTRY_URL` (or inline config) wins over the
+ * saved URL, and `HANDOFF_REGISTRY_ACCESS_TOKEN` wins over the saved token. The saved token only
+ * applies to the URL it was issued for.
+ */
+const resolveAuthenticatedRegistryConnection = (config_1, ...args_1) => __awaiter(void 0, [config_1, ...args_1], void 0, function* (config, workingPath = process.cwd()) {
+    const connection = (0, exports.resolveRegistryConnection)(config);
+    const auth = yield (0, store_1.readCliAuth)(workingPath);
+    if (!(0, store_1.cliAuthTokenIsValid)(auth))
+        return connection;
+    const url = connection.url || auth.remoteUrl;
+    const accessToken = connection.accessToken || ((0, store_1.cliAuthMatchesRegistry)(auth, url) ? auth.accessToken : '');
+    return Object.assign(Object.assign({}, connection), { url, accessToken });
+});
+exports.resolveAuthenticatedRegistryConnection = resolveAuthenticatedRegistryConnection;

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

@@ -1,21 +1,21 @@
 /**
  * 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
+ * The package ships both built-in drivers (`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
+ * lazily (dynamic import) for the selected driver 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 type { RegistryDatabaseDriver } from './driver';
 import * as schema from './schema';
-/** Typed Drizzle database over the registry schema, regardless of which adapter backs it. */
+/** Typed Drizzle database over the registry schema, regardless of which driver 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;
+    /** Selected driver that produced this connection. */
+    driver: RegistryDatabaseDriver;
     /** Typed Drizzle database. */
     db: RegistryDatabase;
     /** Apply the package-owned migrations found in `migrationsFolder`. */
@@ -24,12 +24,12 @@ export interface RegistryDbConnection {
     close(): Promise<void>;
 }
 export interface CreateRegistryDbConnectionParams {
-    adapter: RegistryDatabaseAdapter;
+    driver: RegistryDatabaseDriver;
     connectionString: string;
 }
 /**
- * Create a registry database connection for the resolved adapter. Both adapters target the
+ * Create a registry database connection for the resolved driver. Both drivers 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>;
+export declare const createRegistryDbConnection: ({ driver, connectionString, }: CreateRegistryDbConnectionParams) => Promise<RegistryDbConnection>;

package/dist/registry/db/client.js

@@ -2,9 +2,9 @@
 /**
  * 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
+ * The package ships both built-in drivers (`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
+ * lazily (dynamic import) for the selected driver only, so workspace dev/build never pulls the
  * Postgres/Neon drivers into memory when the registry is not in use.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
@@ -43,13 +43,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRegistryDbConnection = void 0;
 const schema = __importStar(require("./schema"));
 /**
- * Create a registry database connection for the resolved adapter. Both adapters target the
+ * Create a registry database connection for the resolved driver. Both drivers target the
  * Postgres dialect and share the same schema, so the returned connection is interchangeable for
  * migration and (later) the registry store.
  */
-const createRegistryDbConnection = (_a) => __awaiter(void 0, [_a], void 0, function* ({ adapter, connectionString, }) {
+const createRegistryDbConnection = (_a) => __awaiter(void 0, [_a], void 0, function* ({ driver, connectionString, }) {
     var _b;
-    if (adapter === 'neon') {
+    if (driver === 'neon') {
         const { Pool, neonConfig } = yield Promise.resolve().then(() => __importStar(require('@neondatabase/serverless')));
         // Neon's serverless driver needs a WebSocket constructor in Node; reuse the bundled `ws`.
         const ws = yield Promise.resolve().then(() => __importStar(require('ws')));
@@ -66,7 +66,7 @@ const createRegistryDbConnection = (_a) => __awaiter(void 0, [_a], void 0, funct
         }
         const db = drizzle(pool, { schema });
         return {
-            adapter,
+            driver,
             db,
             migrate: (migrationsFolder) => migrate(db, { migrationsFolder }),
             close: () => pool.end(),
@@ -85,7 +85,7 @@ const createRegistryDbConnection = (_a) => __awaiter(void 0, [_a], void 0, funct
     }
     const db = drizzle(pool, { schema });
     return {
-        adapter,
+        driver,
         db,
         migrate: (migrationsFolder) => migrate(db, { migrationsFolder }),
         close: () => pool.end(),

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

@@ -0,0 +1,46 @@
+/**
+ * Registry database driver resolution.
+ *
+ * PostgreSQL is the supported database. `runtime.registry.database.driver` selects one of two
+ * built-in connection drivers shipped with the `handoff-app` package — `pg` (default) and `neon` —
+ * both targeting the same Postgres dialect over one package-owned schema and migration set. The
+ * driver picks *how* to connect, not *which* database engine to use. `build --target registry` and
+ * `db:migrate` resolve the **same** driver 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 connection driver. Both ship with the package and target Postgres. */
+export type RegistryDatabaseDriver = 'pg' | 'neon';
+/** Default env-var name holding the database connection string. */
+export declare const DEFAULT_DATABASE_URL_ENV = "DATABASE_URL";
+/** @deprecated Fixed registry server secrets are no longer authorized. */
+export declare const DEFAULT_REGISTRY_API_TOKEN_ENV = "HANDOFF_REGISTRY_API_TOKEN";
+/** Default registry database driver when none is configured. */
+export declare const DEFAULT_REGISTRY_DRIVER: RegistryDatabaseDriver;
+/** Fully resolved registry database connection inputs. */
+export interface ResolvedRegistryDatabase {
+    /** Selected built-in driver. */
+    driver: RegistryDatabaseDriver;
+    /** 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 legacy fixed-token env-var name for configuration compatibility.
+ *
+ * @deprecated The returned env var is intentionally ignored by registry authorization. Use a
+ * user-issued access token or `handoff-app login`.
+ */
+export declare const resolveApiTokenEnv: (config: Config | null | undefined) => string;
+/** Resolve the configured registry database driver (defaults to `pg`). */
+export declare const resolveRegistryDriver: (config: Config | null | undefined) => RegistryDatabaseDriver;
+/**
+ * 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 → driver.js}

@@ -1,21 +1,23 @@
 "use strict";
 /**
- * Registry database adapter resolution.
+ * Registry database driver 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.
+ * PostgreSQL is the supported database. `runtime.registry.database.driver` selects one of two
+ * built-in connection drivers shipped with the `handoff-app` package — `pg` (default) and `neon` —
+ * both targeting the same Postgres dialect over one package-owned schema and migration set. The
+ * driver picks *how* to connect, not *which* database engine to use. `build --target registry` and
+ * `db:migrate` resolve the **same** driver 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;
+exports.resolveRegistryDatabase = exports.resolveRegistryDriver = exports.resolveApiTokenEnv = exports.resolveDatabaseUrlEnv = exports.DEFAULT_REGISTRY_DRIVER = 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. */
+/** @deprecated Fixed registry server secrets are no longer authorized. */
 exports.DEFAULT_REGISTRY_API_TOKEN_ENV = 'HANDOFF_REGISTRY_API_TOKEN';
-/** Default registry database adapter when none is configured. */
-exports.DEFAULT_REGISTRY_ADAPTER = 'pg';
+/** Default registry database driver when none is configured. */
+exports.DEFAULT_REGISTRY_DRIVER = 'pg';
 /** Resolve the env-var name holding the database URL (defaults to `DATABASE_URL`). */
 const resolveDatabaseUrlEnv = (config) => {
     var _a, _b, _c;
@@ -24,9 +26,10 @@ const resolveDatabaseUrlEnv = (config) => {
 };
 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.
+ * Resolve the legacy fixed-token env-var name for configuration compatibility.
+ *
+ * @deprecated The returned env var is intentionally ignored by registry authorization. Use a
+ * user-issued access token or `handoff-app login`.
  */
 const resolveApiTokenEnv = (config) => {
     var _a, _b, _c;
@@ -34,12 +37,12 @@ const resolveApiTokenEnv = (config) => {
     return configured || exports.DEFAULT_REGISTRY_API_TOKEN_ENV;
 };
 exports.resolveApiTokenEnv = resolveApiTokenEnv;
-/** Resolve the configured registry adapter (defaults to `pg`). */
-const resolveRegistryAdapter = (config) => {
+/** Resolve the configured registry database driver (defaults to `pg`). */
+const resolveRegistryDriver = (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;
+    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.driver) !== null && _d !== void 0 ? _d : exports.DEFAULT_REGISTRY_DRIVER;
 };
-exports.resolveRegistryAdapter = resolveRegistryAdapter;
+exports.resolveRegistryDriver = resolveRegistryDriver;
 /**
  * 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"
@@ -47,13 +50,13 @@ exports.resolveRegistryAdapter = resolveRegistryAdapter;
  */
 const resolveRegistryDatabase = (config) => {
     var _a;
-    const adapter = (0, exports.resolveRegistryAdapter)(config);
+    const driver = (0, exports.resolveRegistryDriver)(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 };
+    return { driver, databaseUrlEnv, connectionString };
 };
 exports.resolveRegistryDatabase = resolveRegistryDatabase;

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

@@ -1,5 +1,5 @@
-export { buildMetadata, componentFiles, components, docsArtifacts, patternFiles, patterns, registrySchema, type BuildMetadataEntityKind, type DocsArtifactEntityKind, type RegistryReviewMetadata, } from './schema';
+export { buildMetadata, componentFiles, components, docsArtifacts, patternFiles, patterns, registryAccessTokens, registryAuthActionTokens, registryAuthRateLimits, registryDeviceAuthorizations, registryInstallations, registrySchema, registryUsers, type BuildMetadataEntityKind, type DocsArtifactEntityKind, type RegistryAccessScope, type RegistryAuthActionPurpose, type RegistryDeviceAuthorizationStatus, type RegistryRateLimitBucket, type RegistryReviewMetadata, type RegistryUserRole, type RegistryUserStatus, } from './schema';
 export type { ArtifactBuildStatus as RegistryBuildStatus } from '../../artifacts/types';
-export { DEFAULT_DATABASE_URL_ENV, DEFAULT_REGISTRY_ADAPTER, DEFAULT_REGISTRY_API_TOKEN_ENV, resolveApiTokenEnv, resolveDatabaseUrlEnv, resolveRegistryAdapter, resolveRegistryDatabase, type RegistryDatabaseAdapter, type ResolvedRegistryDatabase, } from './adapter';
+export { DEFAULT_DATABASE_URL_ENV, DEFAULT_REGISTRY_DRIVER, DEFAULT_REGISTRY_API_TOKEN_ENV, resolveApiTokenEnv, resolveDatabaseUrlEnv, resolveRegistryDriver, resolveRegistryDatabase, type RegistryDatabaseDriver, type ResolvedRegistryDatabase, } from './driver';
 export { createRegistryDbConnection, type CreateRegistryDbConnectionParams, type RegistryDatabase, type RegistryDbConnection, } from './client';
 export { getMigrationsFolder, runRegistryMigrations } from './migrate';