handoff-app 2.0.0-3 → 2.0.0-5

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

@@ -1,3 +1,14 @@
+/**
+ * Whether a credential can be presented unambiguously in a request header. One rule shared by the
+ * authentication headers and by whatever a deployment configures as a secret, so a value is never
+ * accepted through one carrier and rejected by the other.
+ *
+ * Whitespace is out so nothing can be trimmed away or smuggled past a parser, and the comma with it:
+ * repeats of a header Node does not de-duplicate arrive joined with `, `, and no accepted credential
+ * may look like that. Non-ASCII bytes are out too, since their header encoding is ambiguous and a
+ * credential has to reproduce exactly.
+ */
+export declare const isTransmittableCredential: (value: string) => boolean;
 export declare const validateRegistryEmail: (email: string) => string | null;
 export declare const validateRegistryDisplayName: (name: string) => string | null;
 export declare const validateRegistryImageUrl: (image: string | null | undefined) => string | null | false;

package/dist/registry/auth/validation.js

@@ -1,8 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateRegistryImageUrl = exports.validateRegistryDisplayName = exports.validateRegistryEmail = void 0;
+exports.validateRegistryImageUrl = exports.validateRegistryDisplayName = exports.validateRegistryEmail = exports.isTransmittableCredential = void 0;
 const crypto_1 = require("./crypto");
 const SIMPLE_EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/**
+ * Printable ASCII (`!` through `~`) except the comma: HTTP's `VCHAR`, minus the character Node joins
+ * duplicate header values with.
+ */
+const TRANSMITTABLE_CREDENTIAL_PATTERN = /^[\x21-\x2B\x2D-\x7E]+$/;
+/**
+ * Whether a credential can be presented unambiguously in a request header. One rule shared by the
+ * authentication headers and by whatever a deployment configures as a secret, so a value is never
+ * accepted through one carrier and rejected by the other.
+ *
+ * Whitespace is out so nothing can be trimmed away or smuggled past a parser, and the comma with it:
+ * repeats of a header Node does not de-duplicate arrive joined with `, `, and no accepted credential
+ * may look like that. Non-ASCII bytes are out too, since their header encoding is ambiguous and a
+ * credential has to reproduce exactly.
+ */
+const isTransmittableCredential = (value) => TRANSMITTABLE_CREDENTIAL_PATTERN.test(value);
+exports.isTransmittableCredential = isTransmittableCredential;
 const validateRegistryEmail = (email) => {
     const normalized = (0, crypto_1.normalizeEmail)(email);
     return normalized.length <= 320 && SIMPLE_EMAIL_PATTERN.test(normalized) ? normalized : null;

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

@@ -13,4 +13,4 @@ import Handoff from '../../index';
  * Checkout all published asset collections, or a single collection when `collection` is given.
  * Recreates workspace asset files; prompts before overwriting changed local files unless `--force`.
  */
-export declare const checkoutAssets: (handoff: Handoff, collection?: string) => Promise<void>;
+export declare const checkoutAssets: (handoff: Handoff, selection?: string[]) => Promise<void>;

package/dist/registry/checkout/assets.js

@@ -84,15 +84,19 @@ const wouldChange = (absolutePath, bytes) => {
  * Checkout all published asset collections, or a single collection when `collection` is given.
  * Recreates workspace asset files; prompts before overwriting changed local files unless `--force`.
  */
-const checkoutAssets = (handoff, collection) => __awaiter(void 0, void 0, void 0, function* () {
+const checkoutAssets = (handoff, selection) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
     const connection = yield (0, index_1.resolveConnectionOrThrow)(handoff);
-    if (collection && !(0, sets_1.isAssetCollection)(collection)) {
-        throw new index_1.CheckoutError(`Unknown asset collection "${collection}". Supported collections: ${sets_1.ASSET_COLLECTIONS.join(', ')}.`);
+    const unsupported = (_a = selection === null || selection === void 0 ? void 0 : selection.filter((name) => !(0, sets_1.isAssetCollection)(name))) !== null && _a !== void 0 ? _a : [];
+    if (unsupported.length > 0) {
+        throw new index_1.CheckoutError(`Unknown asset collection ${unsupported.map((name) => `"${name}"`).join(', ')}. ` +
+            `Supported collections: ${sets_1.ASSET_COLLECTIONS.join(', ')}.`);
     }
     const client = (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken });
+    // A named selection is trusted as-is; only a full checkout has to ask the registry what exists.
     let collections;
-    if (collection) {
-        collections = [collection];
+    if (selection) {
+        collections = selection;
     }
     else {
         const summaries = yield client.listAssetCollections();
@@ -123,16 +127,27 @@ const checkoutAssets = (handoff, collection) => __awaiter(void 0, void 0, void 0
     // Download each referenced blob once (dedup by hash), then resolve every asset to a physical write.
     const blobCache = new Map();
     const writes = [];
+    const plannedPaths = [];
     for (const payload of payloads) {
         for (const asset of payload.assets) {
+            const absolutePath = (0, layout_1.resolveAssetPhysicalPath)(asset.path, roots);
+            plannedPaths.push(absolutePath);
+            // A dry run reports paths only, so there is no reason to pull the bytes down.
+            if (handoff.dryRun) {
+                continue;
+            }
             let bytes = blobCache.get(asset.contentHash);
             if (!bytes) {
                 bytes = yield client.downloadAssetBlob(asset.contentHash);
                 blobCache.set(asset.contentHash, bytes);
             }
-            writes.push({ absolutePath: (0, layout_1.resolveAssetPhysicalPath)(asset.path, roots), bytes });
+            writes.push({ absolutePath, bytes });
         }
     }
+    if (handoff.dryRun) {
+        (0, index_1.reportPlannedWrites)(handoff, 'asset collections', plannedPaths, plannedPaths.filter((target) => fs_extra_1.default.existsSync(target)));
+        return;
+    }
     const existingChanges = writes.filter((write) => fs_extra_1.default.existsSync(write.absolutePath) && wouldChange(write.absolutePath, write.bytes));
     if (existingChanges.length > 0 && !handoff.force) {
         const proceed = yield p.confirm({

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

@@ -24,6 +24,13 @@ export declare class CheckoutError extends Error {
  * actionable {@link CheckoutError} naming the exact misconfiguration.
  */
 export declare const resolveConnectionOrThrow: (handoff: Handoff) => Promise<import("../connection").ResolvedRegistryConnection>;
+/**
+ * Report the files a checkout would create or replace, and write nothing. Called once the real
+ * checkout has computed its targets but before it prompts or writes, so a dry run exercises the same
+ * path resolution and conflict detection as the real thing. Shared by the entity, page, token and
+ * asset checkout paths.
+ */
+export declare const reportPlannedWrites: (handoff: Handoff, label: string, targets: string[], conflicts: string[]) => void;
 /**
  * Checkout a single component, pattern, or page from the connected registry into this workspace.
  * Overwriting existing local files requires `--force` or an interactive confirmation.
@@ -35,4 +42,4 @@ export declare const checkoutEntity: (handoff: Handoff, kind: TransferEntityKind
  * 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`).
  */
-export declare const checkoutEntities: (handoff: Handoff, kind: TransferEntityKind) => Promise<void>;
+export declare const checkoutEntities: (handoff: Handoff, kind: TransferEntityKind, ids?: string[]) => Promise<void>;

package/dist/registry/checkout/index.js

@@ -60,7 +60,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.checkoutEntities = exports.checkoutEntity = exports.resolveConnectionOrThrow = exports.CheckoutError = void 0;
+exports.checkoutEntities = exports.checkoutEntity = exports.reportPlannedWrites = 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"));
@@ -70,6 +70,7 @@ const logger_1 = require("../../utils/logger");
 const client_1 = require("../client");
 const connection_1 = require("../connection");
 const path_2 = require("../path");
+const selection_1 = require("../selection");
 /** A connected-workspace configuration or precondition failure surfaced to the CLI. */
 class CheckoutError extends Error {
     constructor(message) {
@@ -568,6 +569,21 @@ const writeSourceFile = (targetDir, file) => __awaiter(void 0, void 0, void 0, f
     yield fs_extra_1.default.writeFile(absolutePath, file.content, 'utf8');
     return absolutePath;
 });
+/**
+ * Report the files a checkout would create or replace, and write nothing. Called once the real
+ * checkout has computed its targets but before it prompts or writes, so a dry run exercises the same
+ * path resolution and conflict detection as the real thing. Shared by the entity, page, token and
+ * asset checkout paths.
+ */
+const reportPlannedWrites = (handoff, label, targets, conflicts) => {
+    const conflicting = new Set(conflicts);
+    logger_1.Logger.info(`Would checkout ${label} (${targets.length} file(s)):`);
+    for (const target of targets) {
+        const relative = path_1.default.relative(handoff.workingPath, target) || target;
+        logger_1.Logger.info(`  ${conflicting.has(target) ? 'overwrite' : 'create'}: ${relative}`);
+    }
+};
+exports.reportPlannedWrites = reportPlannedWrites;
 /**
  * Checkout a page: write its single verbatim `.md` (transfer path `<id>.md`) back under
  * `<workingPath>/pages/`. Unlike components/patterns there is no declaration to synthesize — the
@@ -583,6 +599,10 @@ const checkoutPage = (handoff, id, payload) => __awaiter(void 0, void 0, void 0,
         return target;
     });
     const conflicts = targets.filter((file) => fs_extra_1.default.existsSync(file));
+    if (handoff.dryRun) {
+        (0, exports.reportPlannedWrites)(handoff, `page "${id}"`, targets, conflicts);
+        return;
+    }
     if (!(yield confirmOverwrite(handoff, conflicts))) {
         logger_1.Logger.warn(`Checkout of page "${id}" cancelled; no files were written.`);
         return;
@@ -633,7 +653,13 @@ const checkoutSingle = (handoff, kind, id, client, registryUrl) => __awaiter(voi
         }
         return { file, absolutePath };
     });
-    const conflicts = [...sourceTargets.map((entry) => entry.absolutePath), declarationPath].filter((file) => fs_extra_1.default.existsSync(file));
+    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 (!(yield confirmOverwrite(handoff, conflicts))) {
         logger_1.Logger.warn(`Checkout of ${kind} "${id}" cancelled; no files were written.`);
         return null;
@@ -694,7 +720,7 @@ exports.checkoutEntity = checkoutEntity;
  * 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 checkoutEntities = (handoff, kind, ids) => __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;
@@ -707,14 +733,20 @@ const checkoutEntities = (handoff, kind) => __awaiter(void 0, void 0, void 0, fu
         }
         throw error;
     }
-    if (summaries.length === 0) {
+    const published = summaries.map((summary) => summary.id);
+    const { selected: targets, unknown } = (0, selection_1.selectIds)(published, ids);
+    if (unknown.length > 0) {
+        throw new CheckoutError(`No ${kind} named ${unknown.map((id) => `"${id}"`).join(', ')} is published in the registry. ` +
+            `Published ${kind}s: ${published.join(', ') || '(none)'}.`);
+    }
+    if (targets.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) {
+    for (const id of targets) {
         try {
             const targetDir = yield checkoutSingle(handoff, kind, id, client, connection.url);
             if (targetDir) {
@@ -728,7 +760,8 @@ const checkoutEntities = (handoff, kind) => __awaiter(void 0, void 0, void 0, fu
     }
     // 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` : ''}.`);
+    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` : ''}.`);
     if (failed.length > 0) {
         for (const failure of failed) {
             logger_1.Logger.error(`  - ${failure.id}: ${failure.message}`);

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

@@ -12,4 +12,4 @@ import Handoff from '../../index';
  * 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`.
  */
-export declare const checkoutTokens: (handoff: Handoff, setId?: string) => Promise<void>;
+export declare const checkoutTokens: (handoff: Handoff, selection?: string[]) => Promise<void>;

package/dist/registry/checkout/tokens.js

@@ -97,15 +97,18 @@ const wouldChange = (absolutePath, content) => {
  * 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 checkoutTokens = (handoff, selection) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const unsupported = (_a = selection === null || selection === void 0 ? void 0 : selection.filter((id) => !(0, sets_1.isTokenSetId)(id))) !== null && _a !== void 0 ? _a : [];
+    if (unsupported.length > 0) {
+        throw new index_1.CheckoutError(`Unknown or unsafe token set id ${unsupported.map((id) => `"${id}"`).join(', ')}.`);
     }
     const connection = yield (0, index_1.resolveConnectionOrThrow)(handoff);
     const client = (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken });
+    // A named selection is trusted as-is; only a full checkout has to ask the registry what exists.
     let ids;
-    if (setId) {
-        ids = [setId];
+    if (selection) {
+        ids = selection;
     }
     else {
         const summaries = yield client.listTokenSets();
@@ -153,6 +156,10 @@ const checkoutTokens = (handoff, setId) => __awaiter(void 0, void 0, void 0, fun
         }
     }
     const existingChanges = changed.filter((filePath) => fs_extra_1.default.existsSync(filePath));
+    if (handoff.dryRun) {
+        (0, index_1.reportPlannedWrites)(handoff, 'token sets', changed, existingChanges);
+        return;
+    }
     if (existingChanges.length > 0 && !handoff.force) {
         const proceed = yield p.confirm({
             message: `Checkout will overwrite ${existingChanges.length} changed local token file(s). Continue?`,

package/dist/registry/connection.d.ts

@@ -6,6 +6,9 @@
  * 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.
+ *
+ * The older `HANDOFF_CLOUD_*` names still work as deprecated fallbacks; see
+ * {@link DEPRECATED_ENV_ALIASES}.
  */
 import type { Config } from '../types/config';
 /** Default env-var name holding the remote registry base URL. */
@@ -26,6 +29,9 @@ export interface ResolvedRegistryConnection {
 /**
  * Resolve the connected-workspace registry connection from config + environment. Never throws —
  * Callers inspect the resolved URL and access token to surface specific configuration errors.
+ *
+ * `urlEnv` and `accessTokenEnv` always report the canonical name, even when an alias supplied the
+ * value, so errors built from them point at the variable to adopt.
  */
 export declare const resolveRegistryConnection: (config: Config | null | undefined) => ResolvedRegistryConnection;
 /**
@@ -35,5 +41,9 @@ export declare const resolveRegistryConnection: (config: Config | null | undefin
  * 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.
+ *
+ * A configured `HANDOFF_SYNC_SECRET` is the last resort. Being deployment-wide rather than personal,
+ * it fills in only where there is no explicit token and no login (CI, in practice), instead of quietly
+ * speaking for a developer who is signed in.
  */
 export declare const resolveAuthenticatedRegistryConnection: (config: Config | null | undefined, workingPath?: string) => Promise<ResolvedRegistryConnection>;

package/dist/registry/connection.js

@@ -7,6 +7,9 @@
  * 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.
+ *
+ * The older `HANDOFF_CLOUD_*` names still work as deprecated fallbacks; see
+ * {@link DEPRECATED_ENV_ALIASES}.
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -20,22 +23,60 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveAuthenticatedRegistryConnection = exports.resolveRegistryConnection = exports.DEFAULT_REGISTRY_ACCESS_TOKEN_ENV = exports.DEFAULT_REGISTRY_URL_ENV = void 0;
 const store_1 = require("../cli/auth/store");
+// Imported straight from the module, not the `auth` barrel, to keep the database schema off the CLI
+// startup path; this file is resolved for every command.
+const sync_secret_1 = require("./auth/sync-secret");
+const logger_1 = require("../utils/logger");
 /** 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';
+/**
+ * Old env-var names we still read, keyed by the name that replaced them. Keeps workspaces set up
+ * from the older docs working instead of silently reporting no registry.
+ */
+const DEPRECATED_ENV_ALIASES = {
+    [exports.DEFAULT_REGISTRY_URL_ENV]: 'HANDOFF_CLOUD_URL',
+    [exports.DEFAULT_REGISTRY_ACCESS_TOKEN_ENV]: 'HANDOFF_CLOUD_TOKEN',
+};
+/** Aliases we've already warned about, so each one warns once per run and not once per lookup. */
+const warnedAliases = new Set();
+/**
+ * Value of the named env var, falling back to its deprecated alias. Only the default names have
+ * aliases: a custom `urlEnv`/`accessTokenEnv` is a deliberate choice, so a stray `HANDOFF_CLOUD_*`
+ * must not stand in for it. The warning goes through {@link Logger.warn}, so
+ * `HANDOFF_LOG_LEVEL=error` silences it in CI.
+ */
+const readConnectionEnv = (name) => {
+    var _a, _b;
+    const configured = (_a = process.env[name]) === null || _a === void 0 ? void 0 : _a.trim();
+    if (configured)
+        return configured;
+    const alias = DEPRECATED_ENV_ALIASES[name];
+    const inherited = alias ? (_b = process.env[alias]) === null || _b === void 0 ? void 0 : _b.trim() : '';
+    if (!inherited)
+        return '';
+    if (!warnedAliases.has(alias)) {
+        warnedAliases.add(alias);
+        logger_1.Logger.warn(`${alias} is deprecated and will be removed in a future release; set ${name} instead.`);
+    }
+    return inherited;
+};
 /**
  * Resolve the connected-workspace registry connection from config + environment. Never throws —
  * Callers inspect the resolved URL and access token to surface specific configuration errors.
+ *
+ * `urlEnv` and `accessTokenEnv` always report the canonical name, even when an alias supplied the
+ * value, so errors built from them point at the variable to adopt.
  */
 const resolveRegistryConnection = (config) => {
-    var _a, _b, _c, _d, _e, _f, _g, _h;
+    var _a, _b, _c, _d;
     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 : '';
+    const url = inlineUrl || readConnectionEnv(urlEnv);
+    const accessToken = readConnectionEnv(accessTokenEnv);
     return {
         url,
         accessToken,
@@ -51,14 +92,18 @@ exports.resolveRegistryConnection = resolveRegistryConnection;
  * 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.
+ *
+ * A configured `HANDOFF_SYNC_SECRET` is the last resort. Being deployment-wide rather than personal,
+ * it fills in only where there is no explicit token and no login (CI, in practice), instead of quietly
+ * speaking for a developer who is signed in.
  */
 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 : '');
+    const login = (0, store_1.cliAuthTokenIsValid)(auth) ? auth : null;
+    const url = connection.url || (login === null || login === void 0 ? void 0 : login.remoteUrl) || '';
+    const savedToken = login && (0, store_1.cliAuthMatchesRegistry)(login, url) ? login.accessToken : '';
+    const accessToken = connection.accessToken || savedToken || (0, sync_secret_1.resolveRegistrySyncSecret)();
     return Object.assign(Object.assign({}, connection), { url, accessToken });
 });
 exports.resolveAuthenticatedRegistryConnection = resolveAuthenticatedRegistryConnection;

package/dist/registry/content-kinds.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Logical content-kind vocabulary: the dependency-light boundary shared by the CLI, the
+ * publish/checkout orchestration, and the compatibility layer.
+ *
+ * A workspace publishes and checks out five kinds of content. Components, patterns and pages are
+ * entities with a singular wire kind ({@link TransferEntityKind}); tokens and assets travel through
+ * their own transfer endpoints. This module owns only the stable plural vocabulary and its ordering,
+ * so it stays free of fs, DB and React dependencies.
+ */
+import type { TransferEntityKind } from './transfer';
+/** Stable identity used to publish `pages/index.md` while serving it at the root route. */
+export declare const HOME_PAGE_ID = "index";
+export declare const HOME_PAGE_PATH = "/";
+/** Plural content kinds accepted wherever a publish or checkout target is named. */
+export declare const REGISTRY_ENTITY_KINDS: readonly ["components", "patterns", "pages", "tokens", "assets"];
+export type RegistryEntityKind = (typeof REGISTRY_ENTITY_KINDS)[number];
+/** Map the plural content kind to the singular wire kind used by entity publish/checkout. */
+export declare const ENTITY_WIRE_KIND: Record<'components' | 'patterns' | 'pages', TransferEntityKind>;
+/** The entity kinds, in the order a full run visits them: patterns compose components, pages reference both. */
+export declare const ENTITY_KIND_ORDER: readonly ["components", "patterns", "pages"];
+/**
+ * Every kind, in dependency order. Tokens and assets come first because rendered component
+ * artifacts reference the CSS variables and asset URLs they produce.
+ */
+export declare const ALL_KIND_ORDER: readonly RegistryEntityKind[];
+/** Whether a string names a supported content kind. */
+export declare const isRegistryEntityKind: (value: string) => value is RegistryEntityKind;

package/dist/registry/content-kinds.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Logical content-kind vocabulary: the dependency-light boundary shared by the CLI, the
+ * publish/checkout orchestration, and the compatibility layer.
+ *
+ * A workspace publishes and checks out five kinds of content. Components, patterns and pages are
+ * entities with a singular wire kind ({@link TransferEntityKind}); tokens and assets travel through
+ * their own transfer endpoints. This module owns only the stable plural vocabulary and its ordering,
+ * so it stays free of fs, DB and React dependencies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRegistryEntityKind = exports.ALL_KIND_ORDER = exports.ENTITY_KIND_ORDER = exports.ENTITY_WIRE_KIND = exports.REGISTRY_ENTITY_KINDS = exports.HOME_PAGE_PATH = exports.HOME_PAGE_ID = void 0;
+/** Stable identity used to publish `pages/index.md` while serving it at the root route. */
+exports.HOME_PAGE_ID = 'index';
+exports.HOME_PAGE_PATH = '/';
+/** Plural content kinds accepted wherever a publish or checkout target is named. */
+exports.REGISTRY_ENTITY_KINDS = ['components', 'patterns', 'pages', 'tokens', 'assets'];
+/** Map the plural content kind to the singular wire kind used by entity publish/checkout. */
+exports.ENTITY_WIRE_KIND = {
+    components: 'component',
+    patterns: 'pattern',
+    pages: 'page',
+};
+/** The entity kinds, in the order a full run visits them: patterns compose components, pages reference both. */
+exports.ENTITY_KIND_ORDER = ['components', 'patterns', 'pages'];
+/**
+ * Every kind, in dependency order. Tokens and assets come first because rendered component
+ * artifacts reference the CSS variables and asset URLs they produce.
+ */
+exports.ALL_KIND_ORDER = ['tokens', 'assets', ...exports.ENTITY_KIND_ORDER];
+/** Whether a string names a supported content kind. */
+const isRegistryEntityKind = (value) => exports.REGISTRY_ENTITY_KINDS.includes(value);
+exports.isRegistryEntityKind = isRegistryEntityKind;

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

@@ -26,10 +26,15 @@ export interface RegistryDbConnection {
 export interface CreateRegistryDbConnectionParams {
     driver: RegistryDatabaseDriver;
     connectionString: string;
+    /**
+     * Apply {@link SERVING_POOL_LIMITS}. `db:migrate` leaves this unset, because a migration statement can run for
+     * minutes.
+     */
+    serving?: boolean;
 }
 /**
  * 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: ({ driver, connectionString, }: CreateRegistryDbConnectionParams) => Promise<RegistryDbConnection>;
+export declare const createRegistryDbConnection: ({ driver, connectionString, serving, }: CreateRegistryDbConnectionParams) => Promise<RegistryDbConnection>;

package/dist/registry/db/client.js

@@ -42,13 +42,26 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRegistryDbConnection = void 0;
 const schema = __importStar(require("./schema"));
+/**
+ * One pool backs the anonymous docs read API, the authenticated management API, and every auth query, so a request
+ * must not hold a connection, or wait for one, without a deadline.
+ *
+ * `statement_timeout` bounds one statement, not a transaction, so it does not cut a publish short — an ingest is many
+ * small row writes in one transaction. `connectionTimeoutMillis` makes a saturated pool fail a request instead of
+ * queueing it forever, which is the `pg` default.
+ */
+const SERVING_POOL_LIMITS = {
+    statement_timeout: 15000,
+    connectionTimeoutMillis: 5000,
+};
 /**
  * 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* ({ driver, connectionString, }) {
+const createRegistryDbConnection = (_a) => __awaiter(void 0, [_a], void 0, function* ({ driver, connectionString, serving, }) {
     var _b;
+    const limits = serving ? SERVING_POOL_LIMITS : {};
     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`.
@@ -56,7 +69,7 @@ const createRegistryDbConnection = (_a) => __awaiter(void 0, [_a], void 0, funct
         neonConfig.webSocketConstructor = (_b = ws.default) !== null && _b !== void 0 ? _b : ws;
         const { drizzle } = yield Promise.resolve().then(() => __importStar(require('drizzle-orm/neon-serverless')));
         const { migrate } = yield Promise.resolve().then(() => __importStar(require('drizzle-orm/neon-serverless/migrator')));
-        const pool = new Pool({ connectionString });
+        const pool = new Pool(Object.assign({ connectionString }, limits));
         try {
             yield pool.query('select 1');
         }
@@ -75,7 +88,7 @@ const createRegistryDbConnection = (_a) => __awaiter(void 0, [_a], void 0, funct
     const { Pool } = yield Promise.resolve().then(() => __importStar(require('pg')));
     const { drizzle } = yield Promise.resolve().then(() => __importStar(require('drizzle-orm/node-postgres')));
     const { migrate } = yield Promise.resolve().then(() => __importStar(require('drizzle-orm/node-postgres/migrator')));
-    const pool = new Pool({ connectionString });
+    const pool = new Pool(Object.assign({ connectionString }, limits));
     try {
         yield pool.query('select 1');
     }

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

@@ -998,9 +998,9 @@ export declare const pages: import("drizzle-orm/pg-core").PgTableWithColumns<{
     dialect: "pg";
 }>;
 /**
- * Page source files. A page has a single verbatim `.md` (kind `markdown`) stored for byte-exact
- * checkout and for resolving the rendered body at request time. Declaration files are rejected at the
- * schema level (consistent with the other file tables, though pages never carry declarations).
+ * Published pages store one verbatim `.md` file for byte-exact checkout and runtime body resolution.
+ * The schema permits at most one row per page, and its path must be `${pageId}.md`. This invariant
+ * lets readers select the body without ordering or deduplication.
  */
 export declare const pageFiles: import("drizzle-orm/pg-core").PgTableWithColumns<{
     name: "page_files";
@@ -1076,6 +1076,23 @@ export declare const pageFiles: import("drizzle-orm/pg-core").PgTableWithColumns
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        body: import("drizzle-orm/pg-core").PgColumn<{
+            name: "body";
+            tableName: "page_files";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         storageRef: import("drizzle-orm/pg-core").PgColumn<{
             name: "storage_ref";
             tableName: "page_files";
@@ -4376,6 +4393,23 @@ export declare const registrySchema: {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
+            body: import("drizzle-orm/pg-core").PgColumn<{
+                name: "body";
+                tableName: "page_files";
+                dataType: "string";
+                columnType: "PgText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
             storageRef: import("drizzle-orm/pg-core").PgColumn<{
                 name: "storage_ref";
                 tableName: "page_files";

package/dist/registry/db/schema.js

@@ -129,9 +129,9 @@ exports.patternFiles = (0, pg_core_1.pgTable)('pattern_files', {
  * the record — see {@link pageFiles}.
  */
 exports.pages = (0, pg_core_1.pgTable)('pages', {
-    /** Stable page id (slug path, e.g. `guides/setup`). Join key across stores. */
+    /** Stable page id (e.g. `guides/setup`; `index` is the root page). Join key across stores. */
     id: (0, pg_core_1.text)('id').primaryKey(),
-    /** Logical route the page is served at (e.g. `/guides/setup`). */
+    /** Logical route the page is served at (e.g. `/guides/setup`, or `/` for `index`). */
     path: (0, pg_core_1.text)('path').notNull(),
     title: (0, pg_core_1.text)('title'),
     description: (0, pg_core_1.text)('description'),
@@ -146,9 +146,9 @@ exports.pages = (0, pg_core_1.pgTable)('pages', {
     updatedAt: (0, pg_core_1.timestamp)('updated_at', { withTimezone: true }).notNull().defaultNow(),
 }, (table) => [(0, pg_core_1.index)('pages_group_idx').on(table.group)]);
 /**
- * Page source files. A page has a single verbatim `.md` (kind `markdown`) stored for byte-exact
- * checkout and for resolving the rendered body at request time. Declaration files are rejected at the
- * schema level (consistent with the other file tables, though pages never carry declarations).
+ * Published pages store one verbatim `.md` file for byte-exact checkout and runtime body resolution.
+ * The schema permits at most one row per page, and its path must be `${pageId}.md`. This invariant
+ * lets readers select the body without ordering or deduplication.
  */
 exports.pageFiles = (0, pg_core_1.pgTable)('page_files', {
     pageId: (0, pg_core_1.text)('page_id')
@@ -158,13 +158,15 @@ exports.pageFiles = (0, pg_core_1.pgTable)('page_files', {
     path: (0, pg_core_1.text)('path').notNull(),
     kind: (0, pg_core_1.text)('kind').$type().notNull(),
     content: (0, pg_core_1.text)('content'),
+    body: (0, pg_core_1.text)('body').notNull(),
     storageRef: (0, pg_core_1.text)('storage_ref'),
     contentType: (0, pg_core_1.text)('content_type').notNull(),
     createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull().defaultNow(),
     updatedAt: (0, pg_core_1.timestamp)('updated_at', { withTimezone: true }).notNull().defaultNow(),
 }, (table) => [
-    (0, pg_core_1.primaryKey)({ columns: [table.pageId, table.path] }),
-    (0, pg_core_1.check)('page_files_kind_not_declaration', (0, drizzle_orm_1.sql) `${table.kind} <> 'declaration'`),
+    (0, pg_core_1.primaryKey)({ columns: [table.pageId] }),
+    (0, pg_core_1.check)('page_files_kind_markdown', (0, drizzle_orm_1.sql) `${table.kind} = 'markdown'`),
+    (0, pg_core_1.check)('page_files_canonical_path', (0, drizzle_orm_1.sql) `${table.path} = ${table.pageId} || '.md'`),
 ]);
 /**
  * Docs read-model artifacts. Path-keyed so shared/global artifacts (`component/main.css`,