handoff-app 2.0.0-8 → 2.0.0

package/dist/registry/auth/ai-keys.js

@@ -0,0 +1,69 @@
+"use strict";
+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.readRegistryAiKey = exports.deleteRegistryAiKey = exports.saveRegistryAiKey = exports.listRegistryAiKeyConnections = void 0;
+const drizzle_orm_1 = require("drizzle-orm");
+const schema_1 = require("../db/schema");
+const crypto_1 = require("./crypto");
+/**
+ * Reader-supplied keys for connections the config declares with `credential: 'user'`.
+ *
+ * The key is write-only across the API boundary: once saved, a read reports only that a key exists.
+ * Only the chat route ever decrypts one, and only to send it to the connection's own endpoint.
+ */
+/**
+ * Ids of the connections this reader has a *usable* key for. A row that no longer decrypts — written
+ * under a rotated `HANDOFF_AI_KEY_SECRET` — is left out, so the account page and the assistant agree
+ * that no key is in place instead of offering a key the provider would never receive.
+ */
+const listRegistryAiKeyConnections = (db, userId) => __awaiter(void 0, void 0, void 0, function* () {
+    const rows = yield db
+        .select({ connectionId: schema_1.registryAiKeys.connectionId, encryptedKey: schema_1.registryAiKeys.encryptedKey })
+        .from(schema_1.registryAiKeys)
+        .where((0, drizzle_orm_1.eq)(schema_1.registryAiKeys.userId, userId))
+        .orderBy(schema_1.registryAiKeys.connectionId);
+    return rows.filter((row) => (0, crypto_1.decryptSecret)(row.encryptedKey) !== null).map((row) => row.connectionId);
+});
+exports.listRegistryAiKeyConnections = listRegistryAiKeyConnections;
+/** Save or replace this reader's key for one connection. */
+const saveRegistryAiKey = (db, input) => __awaiter(void 0, void 0, void 0, function* () {
+    const encryptedKey = (0, crypto_1.encryptSecret)(input.key);
+    yield db
+        .insert(schema_1.registryAiKeys)
+        .values({ userId: input.userId, connectionId: input.connectionId, encryptedKey })
+        .onConflictDoUpdate({
+        target: [schema_1.registryAiKeys.userId, schema_1.registryAiKeys.connectionId],
+        set: { encryptedKey, updatedAt: new Date() },
+    });
+});
+exports.saveRegistryAiKey = saveRegistryAiKey;
+/** Remove this reader's key for one connection. Returns whether a row was there to remove. */
+const deleteRegistryAiKey = (db, input) => __awaiter(void 0, void 0, void 0, function* () {
+    const rows = yield db
+        .delete(schema_1.registryAiKeys)
+        .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema_1.registryAiKeys.userId, input.userId), (0, drizzle_orm_1.eq)(schema_1.registryAiKeys.connectionId, input.connectionId)))
+        .returning({ connectionId: schema_1.registryAiKeys.connectionId });
+    return rows.length > 0;
+});
+exports.deleteRegistryAiKey = deleteRegistryAiKey;
+/**
+ * Read back one reader's key. A row that no longer decrypts reads as absent, so the reader is told
+ * to add a key rather than shown a provider error.
+ */
+const readRegistryAiKey = (db, input) => __awaiter(void 0, void 0, void 0, function* () {
+    const [row] = yield db
+        .select({ encryptedKey: schema_1.registryAiKeys.encryptedKey })
+        .from(schema_1.registryAiKeys)
+        .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema_1.registryAiKeys.userId, input.userId), (0, drizzle_orm_1.eq)(schema_1.registryAiKeys.connectionId, input.connectionId)))
+        .limit(1);
+    return row ? (0, crypto_1.decryptSecret)(row.encryptedKey) : null;
+});
+exports.readRegistryAiKey = readRegistryAiKey;

package/dist/registry/auth/crypto.d.ts

@@ -2,3 +2,20 @@ export declare const hashSecret: (secret: string) => string;
 export declare const createOpaqueSecret: (byteLength?: number) => string;
 export declare const secretHashMatches: (secret: string, expectedHash: string) => boolean;
 export declare const normalizeEmail: (email: string) => string;
+/** Env var holding the deployment secret that reader-supplied AI keys are encrypted with. */
+export declare const AI_KEY_SECRET_ENV = "HANDOFF_AI_KEY_SECRET";
+/** Thrown when a key must be encrypted but the deployment secret is missing or too short. */
+export declare class MissingEncryptionSecretError extends Error {
+    constructor();
+}
+/**
+ * Encrypt a value that has to be read back, such as a reader's provider key. AES-256-GCM, with the
+ * salt, nonce and authentication tag carried in the payload so a row is self-describing.
+ */
+export declare const encryptSecret: (plaintext: string) => string;
+/**
+ * Decrypt a value written by {@link encryptSecret}. Returns `null` for anything that does not
+ * authenticate — a payload in another format, or one written under a secret that has since been
+ * rotated — so a stale row reads as "no key saved" instead of failing the request.
+ */
+export declare const decryptSecret: (payload: string) => string | null;

package/dist/registry/auth/crypto.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeEmail = exports.secretHashMatches = exports.createOpaqueSecret = exports.hashSecret = void 0;
+exports.decryptSecret = exports.encryptSecret = exports.MissingEncryptionSecretError = exports.AI_KEY_SECRET_ENV = exports.normalizeEmail = exports.secretHashMatches = exports.createOpaqueSecret = exports.hashSecret = void 0;
 const node_crypto_1 = require("node:crypto");
 const hashSecret = (secret) => (0, node_crypto_1.createHash)('sha256').update(secret, 'utf8').digest('hex');
 exports.hashSecret = hashSecret;
@@ -14,3 +14,63 @@ const secretHashMatches = (secret, expectedHash) => {
 exports.secretHashMatches = secretHashMatches;
 const normalizeEmail = (email) => email.trim().toLowerCase();
 exports.normalizeEmail = normalizeEmail;
+/** Env var holding the deployment secret that reader-supplied AI keys are encrypted with. */
+exports.AI_KEY_SECRET_ENV = 'HANDOFF_AI_KEY_SECRET';
+/** Shortest secret worth accepting. Matches the guidance the installer gives for `AUTH_SECRET`. */
+const MIN_KEY_SECRET_LENGTH = 32;
+/** Format marker, so a later algorithm is distinguishable from this one rather than guessed at. */
+const ENCRYPTED_SECRET_VERSION = 'v1';
+/** Thrown when a key must be encrypted but the deployment secret is missing or too short. */
+class MissingEncryptionSecretError extends Error {
+    constructor() {
+        super(`Reader-supplied AI keys cannot be stored because ${exports.AI_KEY_SECRET_ENV} is not set. Set it to a ` +
+            `random value of at least ${MIN_KEY_SECRET_LENGTH} characters, or declare no connection with ` +
+            `"credential: 'user'".`);
+        this.name = 'MissingEncryptionSecretError';
+    }
+}
+exports.MissingEncryptionSecretError = MissingEncryptionSecretError;
+/**
+ * Derive the record key. A per-record salt means two rows holding the same provider key produce
+ * different ciphertexts, and the fixed `info` label keeps this key distinct from anything else the
+ * same secret is ever used for.
+ */
+const deriveKey = (salt) => {
+    var _a;
+    const secret = (_a = process.env[exports.AI_KEY_SECRET_ENV]) === null || _a === void 0 ? void 0 : _a.trim();
+    if (!secret || secret.length < MIN_KEY_SECRET_LENGTH)
+        throw new MissingEncryptionSecretError();
+    return Buffer.from((0, node_crypto_1.hkdfSync)('sha256', Buffer.from(secret, 'utf8'), salt, 'handoff-ai-key', 32));
+};
+/**
+ * Encrypt a value that has to be read back, such as a reader's provider key. AES-256-GCM, with the
+ * salt, nonce and authentication tag carried in the payload so a row is self-describing.
+ */
+const encryptSecret = (plaintext) => {
+    const salt = (0, node_crypto_1.randomBytes)(16);
+    const iv = (0, node_crypto_1.randomBytes)(12);
+    const cipher = (0, node_crypto_1.createCipheriv)('aes-256-gcm', deriveKey(salt), iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const parts = [salt, iv, cipher.getAuthTag(), encrypted].map((part) => part.toString('base64url'));
+    return [ENCRYPTED_SECRET_VERSION, ...parts].join('.');
+};
+exports.encryptSecret = encryptSecret;
+/**
+ * Decrypt a value written by {@link encryptSecret}. Returns `null` for anything that does not
+ * authenticate — a payload in another format, or one written under a secret that has since been
+ * rotated — so a stale row reads as "no key saved" instead of failing the request.
+ */
+const decryptSecret = (payload) => {
+    const [version, salt, iv, tag, encrypted] = payload.split('.');
+    if (version !== ENCRYPTED_SECRET_VERSION || !salt || !iv || !tag || !encrypted)
+        return null;
+    try {
+        const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', deriveKey(Buffer.from(salt, 'base64url')), Buffer.from(iv, 'base64url'));
+        decipher.setAuthTag(Buffer.from(tag, 'base64url'));
+        return Buffer.concat([decipher.update(Buffer.from(encrypted, 'base64url')), decipher.final()]).toString('utf8');
+    }
+    catch (_a) {
+        return null;
+    }
+};
+exports.decryptSecret = decryptSecret;

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

@@ -1,6 +1,7 @@
 export { createRegistryAccessToken, listRegistryAccessTokens, revokeRegistryAccessToken, revokeAllRegistryAccessTokens, authenticateRegistryAccessToken, formatRegistryAccessToken, parseRegistryAccessToken, normalizeRegistryScopes, expandRegistryScopes, resolveRegistryScope, registryRoleAllowsScopes, type RegistryAccessTokenSummary, type CreateRegistryAccessTokenResult, } from './access-tokens';
 export { createUserInvitation, resendUserInvitation, acceptUserInvitation, createPasswordReset, resetPassword, INVITATION_LIFETIME_MS, PASSWORD_RESET_LIFETIME_MS, type CreateUserInvitationResult, type ResendUserInvitationResult, type ConsumeAuthActionResult, } from './action-tokens';
-export { createOpaqueSecret, hashSecret, normalizeEmail, secretHashMatches } from './crypto';
+export { AI_KEY_SECRET_ENV, MissingEncryptionSecretError, createOpaqueSecret, decryptSecret, encryptSecret, hashSecret, normalizeEmail, secretHashMatches, } from './crypto';
+export { deleteRegistryAiKey, listRegistryAiKeyConnections, readRegistryAiKey, saveRegistryAiKey } from './ai-keys';
 export { buildGravatarUrl } from './gravatar';
 export { authenticateRegistrySyncSecret, resolveRegistrySyncSecret, SYNC_SECRET_ENV } from './sync-secret';
 export { createRegistryDeviceAuthorization, approveRegistryDeviceAuthorization, denyRegistryDeviceAuthorization, exchangeRegistryDeviceAuthorization, purgeExpiredRegistryDeviceAuthorizations, generateRegistryUserCode, normalizeRegistryUserCode, DEVICE_AUTHORIZATION_LIFETIME_SECONDS, DEVICE_AUTHORIZATION_POLL_INTERVAL_SECONDS, type CreateRegistryDeviceAuthorizationResult, type RegistryDeviceApprovalResult, type ExchangeRegistryDeviceAuthorizationResult, } from './device-authorizations';

package/dist/registry/auth/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getRegistryUserById = exports.hashRateLimitIdentifier = exports.purgeExpiredAuthRateLimits = exports.clearAuthRateLimit = exports.consumeAuthRateLimit = exports.MAXIMUM_PASSWORD_LENGTH = exports.MINIMUM_PASSWORD_LENGTH = exports.validatePassword = exports.verifyPassword = exports.hashPassword = exports.REGISTRY_INSTALLATION_ID = exports.REGISTRY_AUTH_SCHEMA_VERSION = exports.installRegistry = exports.getRegistryInstallationState = exports.getRegistryInstallation = exports.DEVICE_AUTHORIZATION_POLL_INTERVAL_SECONDS = exports.DEVICE_AUTHORIZATION_LIFETIME_SECONDS = exports.normalizeRegistryUserCode = exports.generateRegistryUserCode = exports.purgeExpiredRegistryDeviceAuthorizations = exports.exchangeRegistryDeviceAuthorization = exports.denyRegistryDeviceAuthorization = exports.approveRegistryDeviceAuthorization = exports.createRegistryDeviceAuthorization = exports.SYNC_SECRET_ENV = exports.resolveRegistrySyncSecret = exports.authenticateRegistrySyncSecret = exports.buildGravatarUrl = exports.secretHashMatches = exports.normalizeEmail = exports.hashSecret = exports.createOpaqueSecret = exports.PASSWORD_RESET_LIFETIME_MS = exports.INVITATION_LIFETIME_MS = exports.resetPassword = exports.createPasswordReset = exports.acceptUserInvitation = exports.resendUserInvitation = exports.createUserInvitation = exports.registryRoleAllowsScopes = exports.resolveRegistryScope = exports.expandRegistryScopes = exports.normalizeRegistryScopes = exports.parseRegistryAccessToken = exports.formatRegistryAccessToken = exports.authenticateRegistryAccessToken = exports.revokeAllRegistryAccessTokens = exports.revokeRegistryAccessToken = exports.listRegistryAccessTokens = exports.createRegistryAccessToken = void 0;
-exports.validateRegistryImageUrl = exports.validateRegistryEmail = exports.validateRegistryDisplayName = exports.isTransmittableCredential = exports.isRegistryTokenPrincipal = exports.registryPrincipalHasScope = exports.scopesForRegistryRole = exports.REGISTRY_WRITE_SCOPE = exports.REGISTRY_READ_SCOPE = exports.setRegistryUserStatus = exports.updateRegistryUserRole = exports.updateRegistryUserProfile = exports.authenticateRegistryCredentials = exports.listRegistryUsers = void 0;
+exports.verifyPassword = exports.hashPassword = exports.REGISTRY_INSTALLATION_ID = exports.REGISTRY_AUTH_SCHEMA_VERSION = exports.installRegistry = exports.getRegistryInstallationState = exports.getRegistryInstallation = exports.DEVICE_AUTHORIZATION_POLL_INTERVAL_SECONDS = exports.DEVICE_AUTHORIZATION_LIFETIME_SECONDS = exports.normalizeRegistryUserCode = exports.generateRegistryUserCode = exports.purgeExpiredRegistryDeviceAuthorizations = exports.exchangeRegistryDeviceAuthorization = exports.denyRegistryDeviceAuthorization = exports.approveRegistryDeviceAuthorization = exports.createRegistryDeviceAuthorization = exports.SYNC_SECRET_ENV = exports.resolveRegistrySyncSecret = exports.authenticateRegistrySyncSecret = exports.buildGravatarUrl = exports.saveRegistryAiKey = exports.readRegistryAiKey = exports.listRegistryAiKeyConnections = exports.deleteRegistryAiKey = exports.secretHashMatches = exports.normalizeEmail = exports.hashSecret = exports.encryptSecret = exports.decryptSecret = exports.createOpaqueSecret = exports.MissingEncryptionSecretError = exports.AI_KEY_SECRET_ENV = exports.PASSWORD_RESET_LIFETIME_MS = exports.INVITATION_LIFETIME_MS = exports.resetPassword = exports.createPasswordReset = exports.acceptUserInvitation = exports.resendUserInvitation = exports.createUserInvitation = exports.registryRoleAllowsScopes = exports.resolveRegistryScope = exports.expandRegistryScopes = exports.normalizeRegistryScopes = exports.parseRegistryAccessToken = exports.formatRegistryAccessToken = exports.authenticateRegistryAccessToken = exports.revokeAllRegistryAccessTokens = exports.revokeRegistryAccessToken = exports.listRegistryAccessTokens = exports.createRegistryAccessToken = void 0;
+exports.validateRegistryImageUrl = exports.validateRegistryEmail = exports.validateRegistryDisplayName = exports.isTransmittableCredential = exports.isRegistryTokenPrincipal = exports.registryPrincipalHasScope = exports.scopesForRegistryRole = exports.REGISTRY_WRITE_SCOPE = exports.REGISTRY_READ_SCOPE = exports.setRegistryUserStatus = exports.updateRegistryUserRole = exports.updateRegistryUserProfile = exports.authenticateRegistryCredentials = exports.listRegistryUsers = exports.getRegistryUserById = exports.hashRateLimitIdentifier = exports.purgeExpiredAuthRateLimits = exports.clearAuthRateLimit = exports.consumeAuthRateLimit = exports.MAXIMUM_PASSWORD_LENGTH = exports.MINIMUM_PASSWORD_LENGTH = exports.validatePassword = void 0;
 var access_tokens_1 = require("./access-tokens");
 Object.defineProperty(exports, "createRegistryAccessToken", { enumerable: true, get: function () { return access_tokens_1.createRegistryAccessToken; } });
 Object.defineProperty(exports, "listRegistryAccessTokens", { enumerable: true, get: function () { return access_tokens_1.listRegistryAccessTokens; } });
@@ -23,10 +23,19 @@ Object.defineProperty(exports, "resetPassword", { enumerable: true, get: functio
 Object.defineProperty(exports, "INVITATION_LIFETIME_MS", { enumerable: true, get: function () { return action_tokens_1.INVITATION_LIFETIME_MS; } });
 Object.defineProperty(exports, "PASSWORD_RESET_LIFETIME_MS", { enumerable: true, get: function () { return action_tokens_1.PASSWORD_RESET_LIFETIME_MS; } });
 var crypto_1 = require("./crypto");
+Object.defineProperty(exports, "AI_KEY_SECRET_ENV", { enumerable: true, get: function () { return crypto_1.AI_KEY_SECRET_ENV; } });
+Object.defineProperty(exports, "MissingEncryptionSecretError", { enumerable: true, get: function () { return crypto_1.MissingEncryptionSecretError; } });
 Object.defineProperty(exports, "createOpaqueSecret", { enumerable: true, get: function () { return crypto_1.createOpaqueSecret; } });
+Object.defineProperty(exports, "decryptSecret", { enumerable: true, get: function () { return crypto_1.decryptSecret; } });
+Object.defineProperty(exports, "encryptSecret", { enumerable: true, get: function () { return crypto_1.encryptSecret; } });
 Object.defineProperty(exports, "hashSecret", { enumerable: true, get: function () { return crypto_1.hashSecret; } });
 Object.defineProperty(exports, "normalizeEmail", { enumerable: true, get: function () { return crypto_1.normalizeEmail; } });
 Object.defineProperty(exports, "secretHashMatches", { enumerable: true, get: function () { return crypto_1.secretHashMatches; } });
+var ai_keys_1 = require("./ai-keys");
+Object.defineProperty(exports, "deleteRegistryAiKey", { enumerable: true, get: function () { return ai_keys_1.deleteRegistryAiKey; } });
+Object.defineProperty(exports, "listRegistryAiKeyConnections", { enumerable: true, get: function () { return ai_keys_1.listRegistryAiKeyConnections; } });
+Object.defineProperty(exports, "readRegistryAiKey", { enumerable: true, get: function () { return ai_keys_1.readRegistryAiKey; } });
+Object.defineProperty(exports, "saveRegistryAiKey", { enumerable: true, get: function () { return ai_keys_1.saveRegistryAiKey; } });
 var gravatar_1 = require("./gravatar");
 Object.defineProperty(exports, "buildGravatarUrl", { enumerable: true, get: function () { return gravatar_1.buildGravatarUrl; } });
 var sync_secret_1 = require("./sync-secret");

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

@@ -6,7 +6,8 @@
  * into the local workspace in standard authoring form. The local **declaration is synthesized
  * locally** in the configured `runtime.workspace.declarationFormat` — declarations are never read
  * from the registry (they are workspace-only). Identity is matched by stable `id`, so a checked-out
- * entity maps to the correct logical component/pattern and can be re-authored and re-published.
+ * entity maps to the correct logical component/pattern and can be re-authored and re-published. A
+ * new entity goes to the directory it was published from (`sourceDir`).
  *
  * Available only from a connected workspace (`runtime.mode: workspace` + a configured
  * `registryConnection`). Overwriting existing local files is explicit: a `--force` flag or an

package/dist/registry/checkout/index.js

@@ -7,7 +7,8 @@
  * into the local workspace in standard authoring form. The local **declaration is synthesized
  * locally** in the configured `runtime.workspace.declarationFormat` — declarations are never read
  * from the registry (they are workspace-only). Identity is matched by stable `id`, so a checked-out
- * entity maps to the correct logical component/pattern and can be re-authored and re-published.
+ * entity maps to the correct logical component/pattern and can be re-authored and re-published. A
+ * new entity goes to the directory it was published from (`sourceDir`).
  *
  * Available only from a connected workspace (`runtime.mode: workspace` + a configured
  * `registryConnection`). Overwriting existing local files is explicit: a `--force` flag or an
@@ -69,12 +70,12 @@ const path_1 = __importDefault(require("path"));
 const previews_1 = require("../../catalog/previews");
 const define_1 = require("../../catalog/define");
 const renderers_1 = require("../../catalog/renderers");
-const catalog_include_1 = require("../../config/catalog-include");
 const runtime_1 = require("../../config/runtime");
 const logger_1 = require("../../utils/logger");
+const path_2 = require("../../utils/path");
 const client_1 = require("../client");
 const connection_1 = require("../connection");
-const path_2 = require("../path");
+const path_3 = require("../path");
 const selection_1 = require("../selection");
 /** A connected-workspace configuration or precondition failure surfaced to the CLI. */
 class CheckoutError extends Error {
@@ -86,12 +87,7 @@ class CheckoutError extends Error {
 exports.CheckoutError = CheckoutError;
 /** Default authoring format synthesized when no existing file or configured preference applies. */
 const DEFAULT_DECLARATION_FORMAT = 'ts';
-/** Default workspace subdirectory an entity is written into when none is configured. */
-const DEFAULT_ENTITY_DIR = {
-    component: 'components',
-    pattern: 'patterns',
-    page: 'pages',
-};
+const PAGES_DIR = 'pages';
 /** Source-file extensions stripped to form a module specifier for a React component import. */
 const COMPONENT_EXTENSION = /\.(tsx|jsx|ts|js|cjs|mjs)$/i;
 /**
@@ -133,78 +129,40 @@ const describeFetchFailure = (error, kind, id, registryUrl) => {
             return error.message;
     }
 };
-/**
- * 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 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}: catalog.include declares directories under different ` +
-            `parents (${roots.map(relative).join(', ')}), and none is named "${DEFAULT_ENTITY_DIR[kind]}". 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],
+/** `dir` is a `catalog.include` entry, or a direct child of a collection entry. */
+const isInCatalog = (handoff, dir) => {
+    var _a, _b, _c;
+    return ((_c = (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.catalog) === null || _b === void 0 ? void 0 : _b.include) !== null && _c !== void 0 ? _c : []).some((entry) => {
+        const included = path_1.default.resolve(handoff.workingPath, entry);
+        return (0, path_2.arePathsEqual)(included, dir) || (!(0, runtime_1.isComponentDirectory)(included) && (0, path_2.arePathsEqual)(included, path_1.default.dirname(dir)));
     });
-    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
- * `catalog.include`. 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 are settled by the
- * conventional directory name for the kind, and only then by asking 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;
-    const configuredRoots = (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.catalog) === null || _b === void 0 ? void 0 : _b.include;
-    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;
-        })),
-    ];
-    if (roots.length === 1) {
-        return roots[0];
-    }
-    // `catalog.include` is one list for both lanes, so a project that registers `components` and
-    // `patterns` offers two roots for every checkout. Without this, every such project prompts, and a
-    // non-interactive `--force` run fails.
-    const conventional = roots.filter((root) => path_1.default.basename(root) === DEFAULT_ENTITY_DIR[kind]);
-    if (conventional.length === 1) {
-        return conventional[0];
-    }
-    return 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* () {
+};
+/** A locally declared entity keeps its directory. A new one goes to the directory it was published from. */
+const resolveTargetDir = (handoff, kind, id, sourceDir) => __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;
+        return { dir: existingDir, isInCatalog: true };
     }
-    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}".`);
+    if (!(0, path_3.isWorkspaceRelativePath)(sourceDir)) {
+        throw new CheckoutError(`The registry has no valid source directory for ${kind} "${id}". Republish it, then checkout again.`);
     }
-    return targetDir;
+    const dir = path_1.default.resolve(handoff.workingPath, sourceDir);
+    return { dir, isInCatalog: isInCatalog(handoff, dir) };
+});
+/** `--force` fails here: it skips overwrite prompts, not approval of a location the registry chose. */
+const confirmLocation = (handoff, kind, id, dir) => __awaiter(void 0, void 0, void 0, function* () {
+    const relative = path_1.default.relative(handoff.workingPath, dir) || '.';
+    if (handoff.force) {
+        throw new CheckoutError(`The registry places ${kind} "${id}" at ${relative}, which is outside catalog.include. ` +
+            `Add "${relative}" or its parent directory to catalog.include, or run checkout without --force to accept the location.`);
+    }
+    const proceed = yield p.confirm({
+        message: `The registry places ${kind} "${id}" at ${relative}, which is outside catalog.include. Write it there?`,
+        initialValue: false,
+    });
+    return !p.isCancel(proceed) && proceed === true;
 });
 /** Read the extension of an existing local declaration in `dir`, if any maps to a known format. */
 const existingDeclarationFormat = (dir) => {
@@ -685,7 +643,7 @@ const confirmOverwrite = (handoff, conflicts) => __awaiter(void 0, void 0, void
 });
 /** Write a registry source file at its relative path under the target directory. */
 const writeSourceFile = (targetDir, file) => __awaiter(void 0, void 0, void 0, function* () {
-    const absolutePath = (0, path_2.resolvePathWithin)(targetDir, file.path);
+    const absolutePath = (0, path_3.resolvePathWithin)(targetDir, file.path);
     if (!absolutePath) {
         throw new CheckoutError(`Registry returned an unsafe source file path "${file.path}".`);
     }
@@ -714,9 +672,9 @@ exports.reportPlannedWrites = reportPlannedWrites;
  * markdown file is itself the authored source — so the page round-trips byte-for-byte.
  */
 const checkoutPage = (handoff, id, payload) => __awaiter(void 0, void 0, void 0, function* () {
-    const pagesRoot = path_1.default.resolve(handoff.workingPath, DEFAULT_ENTITY_DIR.page);
+    const pagesRoot = path_1.default.resolve(handoff.workingPath, PAGES_DIR);
     const targets = payload.files.map((file) => {
-        const target = (0, path_2.resolvePathWithin)(pagesRoot, file.path);
+        const target = (0, path_3.resolvePathWithin)(pagesRoot, file.path);
         if (!target) {
             throw new CheckoutError(`Registry returned an unsafe page source path "${file.path}".`);
         }
@@ -744,7 +702,7 @@ const checkoutPage = (handoff, id, payload) => __awaiter(void 0, void 0, void 0,
  * failure.
  */
 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);
+    const validId = kind === 'page' ? (0, path_3.isSafeRelativePath)(id) : (0, path_3.isSafePathSegment)(id);
     if (!validId) {
         throw new CheckoutError(`Cannot checkout ${kind} with unsafe id "${id}".`);
     }
@@ -759,19 +717,20 @@ const checkoutSingle = (handoff, kind, id, client, registryUrl) => __awaiter(voi
         }
         throw error;
     }
-    // Pages round-trip as a single verbatim `.md` with no declaration synthesis, and aren't
-    // listed in `catalog.include`, so there's nothing to register.
     if (kind === 'page') {
         yield checkoutPage(handoff, id, payload);
-        return null;
+        return;
     }
-    const targetDir = yield resolveTargetDir(handoff, kind, id);
+    const target = yield resolveTargetDir(handoff, kind, id, payload.sourceDir);
+    const targetDir = target.dir;
+    const relativeDir = path_1.default.relative(handoff.workingPath, targetDir) || '.';
+    const outsideCatalogWarning = `Add "${relativeDir}" to catalog.include, or the build will not load ${kind} "${id}".`;
     const format = resolveDeclarationFormat(handoff, targetDir);
     const declarationFileName = resolveDeclarationFileName(targetDir, id, format);
     const declarationPath = path_1.default.join(targetDir, declarationFileName);
     // Compute everything that would be written, then gate overwrite of any pre-existing file.
     const sourceTargets = payload.files.map((file) => {
-        const absolutePath = (0, path_2.resolvePathWithin)(targetDir, file.path);
+        const absolutePath = (0, path_3.resolvePathWithin)(targetDir, file.path);
         if (!absolutePath) {
             throw new CheckoutError(`Registry returned an unsafe source file path "${file.path}".`);
         }
@@ -781,13 +740,19 @@ const checkoutSingle = (handoff, kind, id, client, registryUrl) => __awaiter(voi
     const plannedWrites = [...sourceTargets.map((entry) => entry.absolutePath), declarationPath];
     const conflicts = plannedWrites.filter((file) => fs_extra_1.default.existsSync(file));
     if (handoff.dryRun) {
-        // Returning null also skips `registerCheckedOut`, so a dry run never edits handoff.config either.
         (0, exports.reportPlannedWrites)(handoff, `${kind} "${id}"`, plannedWrites, conflicts);
-        return null;
+        if (!target.isInCatalog) {
+            logger_1.Logger.warn(`${relativeDir} is outside catalog.include. ${outsideCatalogWarning}`);
+        }
+        return;
+    }
+    if (!target.isInCatalog && !(yield confirmLocation(handoff, kind, id, targetDir))) {
+        logger_1.Logger.warn(`Checkout of ${kind} "${id}" cancelled; no files were written.`);
+        return;
     }
     if (!(yield confirmOverwrite(handoff, conflicts))) {
         logger_1.Logger.warn(`Checkout of ${kind} "${id}" cancelled; no files were written.`);
-        return null;
+        return;
     }
     yield fs_extra_1.default.ensureDir(targetDir);
     const written = [];
@@ -796,36 +761,10 @@ const checkoutSingle = (handoff, kind, id, client, registryUrl) => __awaiter(voi
     }
     yield fs_extra_1.default.writeFile(declarationPath, declaration, 'utf8');
     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 `catalog.include` 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 `include` 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;
+    logger_1.Logger.success(`Checked out ${kind} "${id}" into ${relativeDir} (${payload.files.length} source file(s) + ${declarationFileName}).`);
+    if (!target.isInCatalog) {
+        logger_1.Logger.warn(outsideCatalogWarning);
     }
-    const kindLabel = kind === 'component' ? 'components' : 'patterns';
-    const unlisted = targetDirs.filter((dir) => !(0, catalog_include_1.isIncluded)(handoff, dir));
-    if (unlisted.length === 0) {
-        return;
-    }
-    const result = yield (0, catalog_include_1.addToCatalog)(handoff, unlisted);
-    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} ${kindLabel} 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 catalog.include manually:`);
-    result.pending.forEach((rel) => logger_1.Logger.warn(`  - ${rel}`));
 });
 /**
  * Checkout a single component, pattern, or page from the connected registry into this workspace.
@@ -834,10 +773,7 @@ const registerCheckedOut = (handoff, kind, targetDirs) => __awaiter(void 0, void
 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]);
-    }
+    yield checkoutSingle(handoff, kind, id, client, connection.url);
 });
 exports.checkoutEntity = checkoutEntity;
 /** List the ids the registry publishes for one kind, naming the registry in a listing failure. */
@@ -854,7 +790,7 @@ const listPublishedIds = (kind, client, registryUrl) => __awaiter(void 0, void 0
     }
 });
 /**
- * Check out the given ids of one kind and register what landed. The caller selects the ids, because a
+ * Check out the given ids of one kind. The caller selects the ids, because a
  * catalog run resolves them across both entity lanes before any of them is written.
  *
  * A per-entity failure is collected and never aborts the rest. Failures are reported here, and the
@@ -863,21 +799,15 @@ const listPublishedIds = (kind, client, registryUrl) => __awaiter(void 0, void 0
 const checkoutSelected = (handoff, kind, targets, client, registryUrl) => __awaiter(void 0, void 0, void 0, function* () {
     let checkedOut = 0;
     const failed = [];
-    const targetDirs = [];
     for (const id of targets) {
         try {
-            const targetDir = yield checkoutSingle(handoff, kind, id, client, registryUrl);
-            if (targetDir) {
-                targetDirs.push(targetDir);
-            }
+            yield checkoutSingle(handoff, kind, id, client, registryUrl);
             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} ${handoff.dryRun ? 'would be checked out' : 'checked out'}` +
         `${failed.length ? `, ${failed.length} failed` : ''}.`);
     for (const failure of failed) {

package/dist/registry/client.js

@@ -100,6 +100,27 @@ const createRegistryClient = ({ baseUrl, accessToken }) => {
         }
         return envelope;
     });
+    const uploadAssetBlobThroughRegistry = (blobPath, contentType, bytes) => __awaiter(void 0, void 0, void 0, function* () {
+        var _a, _b;
+        const url = `${root}${blobPath}`;
+        // 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 });
+        }
+    });
     return {
         /** Publish (`PUT`) an entity's package to the registry transfer endpoint. */
         publish(kind, id, pkg) {
@@ -161,28 +182,43 @@ const createRegistryClient = ({ baseUrl, accessToken }) => {
                 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. */
+        /**
+         * Upload one content-addressed blob. Sends it directly to storage when the registry returns a
+         * signed URL, otherwise through the registry. 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,
-                });
+                const blobPath = `/api/registry/transfer/assets/blobs/${encodeURIComponent(hash)}`;
+                const size = bytes.length;
+                const envelope = yield request('POST', `${blobPath}/upload`, { size, contentType });
+                if ((_a = envelope.data) === null || _a === void 0 ? void 0 : _a.stored) {
+                    return;
+                }
+                const upload = (_b = envelope.data) === null || _b === void 0 ? void 0 : _b.upload;
+                if (!upload) {
+                    yield uploadAssetBlobThroughRegistry(blobPath, contentType, bytes);
+                    return;
+                }
+                // Name only the origin in errors: the signed query string must not reach logs.
+                const storage = new URL(upload.url).origin;
+                let response;
+                try {
+                    response = yield fetch(upload.url, {
+                        method: 'PUT',
+                        headers: upload.headers,
+                        body: new Blob([new Uint8Array(bytes)]),
+                    });
+                }
+                catch (error) {
+                    const cause = error === null || error === void 0 ? void 0 : error.cause;
+                    throw new RegistryClientError(`Could not reach asset storage at ${storage}: ${(cause === null || cause === void 0 ? void 0 : cause.code) || (cause === null || cause === void 0 ? void 0 : cause.message) || 'network error'}.`);
+                }
                 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 });
+                    const detail = (yield response.text().catch(() => '')).slice(0, 300);
+                    throw new RegistryClientError(`Asset storage at ${storage} rejected the upload of blob "${hash}" (${response.status} ${response.statusText})${detail ? `: ${detail}` : ''}.`, { status: response.status });
                 }
+                yield request('POST', `${blobPath}/complete`, { storageRef: upload.storageRef, size, contentType });
             });
         },
         /** Download one blob's raw bytes by hash (follows any provider redirect). */