handoff-app 2.0.0-0 → 2.0.0-2

package/dist/artifacts/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeBasePath = exports.buildArtifactUrl = exports.ARTIFACTS_ROUTE_SEGMENT = exports.SHARED_STYLES_CSS_ARTIFACT_PATH = exports.SHARED_MAIN_JS_ARTIFACT_PATH = exports.SHARED_MAIN_CSS_ARTIFACT_PATH = exports.REACT_PREVIEW_FORMAT_VERSION = exports.ARTIFACT_METADATA_PATH = void 0;
+exports.normalizeBasePath = exports.buildAssetUrl = exports.buildAssetDownloadUrl = exports.buildArtifactUrl = exports.ASSETS_ROUTE_SEGMENT = exports.ARTIFACTS_ROUTE_SEGMENT = exports.SHARED_STYLES_CSS_ARTIFACT_PATH = exports.SHARED_MAIN_JS_ARTIFACT_PATH = exports.SHARED_MAIN_CSS_ARTIFACT_PATH = exports.REACT_PREVIEW_FORMAT_VERSION = exports.ARTIFACT_METADATA_PATH = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "ARTIFACT_METADATA_PATH", { enumerable: true, get: function () { return types_1.ARTIFACT_METADATA_PATH; } });
 Object.defineProperty(exports, "REACT_PREVIEW_FORMAT_VERSION", { enumerable: true, get: function () { return types_1.REACT_PREVIEW_FORMAT_VERSION; } });
@@ -9,5 +9,8 @@ Object.defineProperty(exports, "SHARED_MAIN_JS_ARTIFACT_PATH", { enumerable: tru
 Object.defineProperty(exports, "SHARED_STYLES_CSS_ARTIFACT_PATH", { enumerable: true, get: function () { return types_1.SHARED_STYLES_CSS_ARTIFACT_PATH; } });
 var url_1 = require("./url");
 Object.defineProperty(exports, "ARTIFACTS_ROUTE_SEGMENT", { enumerable: true, get: function () { return url_1.ARTIFACTS_ROUTE_SEGMENT; } });
+Object.defineProperty(exports, "ASSETS_ROUTE_SEGMENT", { enumerable: true, get: function () { return url_1.ASSETS_ROUTE_SEGMENT; } });
 Object.defineProperty(exports, "buildArtifactUrl", { enumerable: true, get: function () { return url_1.buildArtifactUrl; } });
+Object.defineProperty(exports, "buildAssetDownloadUrl", { enumerable: true, get: function () { return url_1.buildAssetDownloadUrl; } });
+Object.defineProperty(exports, "buildAssetUrl", { enumerable: true, get: function () { return url_1.buildAssetUrl; } });
 Object.defineProperty(exports, "normalizeBasePath", { enumerable: true, get: function () { return url_1.normalizeBasePath; } });

package/dist/artifacts/url.d.ts

@@ -17,6 +17,8 @@
 export declare const ARTIFACTS_ROUTE_SEGMENT = "api/docs/artifacts";
 /** Route prefix for docs read API metadata (`.json`) reads. */
 export declare const DOCS_ROUTE_SEGMENT = "api/docs";
+/** Route prefix all asset content URLs are served under, regardless of runtime mode. */
+export declare const ASSETS_ROUTE_SEGMENT = "api/docs/assets";
 /**
  * Normalize a configured basePath to either an empty string or a single-leading-slash,
  * no-trailing-slash form. Mirrors the Next app's `resolveBasePath` so builder output composes
@@ -47,3 +49,19 @@ export declare const buildComponentDetailUrl: (id: string, basePath?: string | n
  * (`{basePath}/api/docs/patterns/{id}.json`). The id is URL-encoded; `basePath` is preserved.
  */
 export declare const buildPatternDetailUrl: (id: string, basePath?: string | null) => string;
+/**
+ * Build the basePath-aware content URL for a single asset in a collection
+ * (`{basePath}/api/docs/assets/{collection}/{logicalPath}`). This is the same route the docs read API
+ * serves in every runtime mode: from the database in registry mode, and from statically materialized
+ * files in a static export. Each segment is encoded on its own and traversal segments are rejected,
+ * matching {@link buildArtifactUrl}.
+ *
+ * @throws If the collection or logical path has no usable segments, or contains a `.`/`..` segment.
+ */
+export declare const buildAssetUrl: (collection: string, logicalPath: string, basePath?: string | null) => string;
+/**
+ * Build the download URL for a collection's zip bundle
+ * (`{basePath}/api/docs/assets/{collection}/{collection}.zip`). This is the default target for the
+ * docs "Download" links and can be overridden via `assets_zip_links`.
+ */
+export declare const buildAssetDownloadUrl: (collection: string, basePath?: string | null) => string;

package/dist/artifacts/url.js

@@ -15,11 +15,13 @@
  * Next app can both import it.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildPatternDetailUrl = exports.buildComponentDetailUrl = exports.buildArtifactUrl = exports.normalizeBasePath = exports.DOCS_ROUTE_SEGMENT = exports.ARTIFACTS_ROUTE_SEGMENT = void 0;
+exports.buildAssetDownloadUrl = exports.buildAssetUrl = exports.buildPatternDetailUrl = exports.buildComponentDetailUrl = exports.buildArtifactUrl = exports.normalizeBasePath = exports.ASSETS_ROUTE_SEGMENT = exports.DOCS_ROUTE_SEGMENT = exports.ARTIFACTS_ROUTE_SEGMENT = void 0;
 /** Canonical route prefix all artifact URLs are served under. */
 exports.ARTIFACTS_ROUTE_SEGMENT = 'api/docs/artifacts';
 /** Route prefix for docs read API metadata (`.json`) reads. */
 exports.DOCS_ROUTE_SEGMENT = 'api/docs';
+/** Route prefix all asset content URLs are served under, regardless of runtime mode. */
+exports.ASSETS_ROUTE_SEGMENT = 'api/docs/assets';
 /**
  * Normalize a configured basePath to either an empty string or a single-leading-slash,
  * no-trailing-slash form. Mirrors the Next app's `resolveBasePath` so builder output composes
@@ -84,3 +86,31 @@ exports.buildComponentDetailUrl = buildComponentDetailUrl;
  */
 const buildPatternDetailUrl = (id, basePath) => `${(0, exports.normalizeBasePath)(basePath)}/${exports.DOCS_ROUTE_SEGMENT}/patterns/${encodeURIComponent(id)}.json`;
 exports.buildPatternDetailUrl = buildPatternDetailUrl;
+/**
+ * Build the basePath-aware content URL for a single asset in a collection
+ * (`{basePath}/api/docs/assets/{collection}/{logicalPath}`). This is the same route the docs read API
+ * serves in every runtime mode: from the database in registry mode, and from statically materialized
+ * files in a static export. Each segment is encoded on its own and traversal segments are rejected,
+ * matching {@link buildArtifactUrl}.
+ *
+ * @throws If the collection or logical path has no usable segments, or contains a `.`/`..` segment.
+ */
+const buildAssetUrl = (collection, logicalPath, basePath) => {
+    const segments = [...toArtifactSegments(collection), ...toArtifactSegments(logicalPath)];
+    if (segments.length < 2) {
+        throw new Error(`Cannot build asset URL: empty collection ("${collection}") or path ("${logicalPath}").`);
+    }
+    if (segments.some(isTraversalSegment)) {
+        throw new Error(`Cannot build asset URL: path traversal is not allowed in "${collection}/${logicalPath}".`);
+    }
+    const encoded = segments.map((segment) => encodeURIComponent(segment)).join('/');
+    return `${(0, exports.normalizeBasePath)(basePath)}/${exports.ASSETS_ROUTE_SEGMENT}/${encoded}`;
+};
+exports.buildAssetUrl = buildAssetUrl;
+/**
+ * Build the download URL for a collection's zip bundle
+ * (`{basePath}/api/docs/assets/{collection}/{collection}.zip`). This is the default target for the
+ * docs "Download" links and can be overridden via `assets_zip_links`.
+ */
+const buildAssetDownloadUrl = (collection, basePath) => (0, exports.buildAssetUrl)(collection, `${collection}.zip`, basePath);
+exports.buildAssetDownloadUrl = buildAssetDownloadUrl;

package/dist/cli/create.js

@@ -85,7 +85,7 @@ const createDirectory = (dirPath) => {
  * Get mandatory templates based on whether examples are included
  * Uses different handoff config templates for blank vs. with-examples projects
  */
-const getMandatoryTemplates = (includeExamples, languagePreference) => {
+const getMandatoryTemplates = (includeExamples, languagePreference, includeVercel) => {
     const configFormat = languagePreference;
     const configTemplateBaseName = includeExamples ? 'handoff.config.with-examples' : 'handoff.config';
     const configTemplateSource = `${configTemplateBaseName}.${configFormat === 'typescript' ? 'ts' : 'js'}.tpl`;
@@ -103,6 +103,9 @@ const getMandatoryTemplates = (includeExamples, languagePreference) => {
     if (languagePreference === 'typescript') {
         templates.push({ source: 'tsconfig.json.tpl', destination: 'tsconfig.json' });
     }
+    if (includeVercel) {
+        templates.push({ source: 'vercel.json.tpl', destination: 'vercel.json' });
+    }
     return templates;
 };
 const getExampleTemplates = (languagePreference) => {
@@ -127,7 +130,8 @@ const renderTemplate = (content, data) => {
     });
 };
 const getDependenciesToInstall = (options) => {
-    const dependencies = ['handoff-app@latest'];
+    // TODO: switch back to `handoff-app@latest` before the 2.0 stable release.
+    const dependencies = ['handoff-app@next'];
     const devDependencies = [];
     if (options.includeExamples) {
         dependencies.push('react', 'react-dom');
@@ -250,6 +254,45 @@ const create = () => __awaiter(void 0, void 0, void 0, function* () {
             process.exit(0);
         }
         const languagePreference = languagePreferenceSelection;
+        const includeVercelSelection = yield p.confirm({
+            message: 'Add a Vercel deployment config (vercel.json)?',
+            initialValue: true,
+        });
+        if (p.isCancel(includeVercelSelection)) {
+            p.cancel('Project creation cancelled.');
+            process.exit(0);
+        }
+        const includeVercel = includeVercelSelection;
+        // When a Vercel config is scaffolded, choose which deployment its build command produces. Both
+        // package to `.vercel/output`; they differ in what is served. Registry is the recommended,
+        // pre-selected option; static stays available as the simplest deploy.
+        let vercelBuildCommand = 'npm run build -- --target registry --package vercel';
+        if (includeVercel) {
+            const vercelDeploymentSelection = yield p.select({
+                message: 'Which deployment should Vercel build?',
+                options: [
+                    {
+                        value: 'registry',
+                        label: 'Registry (dynamic)',
+                        hint: 'Live, database-backed app (needs a Postgres DATABASE_URL). The more capable, actively evolving option — recommended for a shared design system.',
+                    },
+                    {
+                        value: 'static',
+                        label: 'Static site',
+                        hint: 'Prebuilt snapshot served as plain files. The simplest to deploy and run.',
+                    },
+                ],
+                initialValue: 'registry',
+            });
+            if (p.isCancel(vercelDeploymentSelection)) {
+                p.cancel('Project creation cancelled.');
+                process.exit(0);
+            }
+            vercelBuildCommand =
+                vercelDeploymentSelection === 'registry'
+                    ? 'npm run build -- --target registry --package vercel'
+                    : 'npm run build -- --target static --package vercel';
+        }
         // Get Figma project ID
         p.log.step(chalk_1.default.blue('Figma Configuration'));
         const figmaProjectId = yield p.text({
@@ -277,6 +320,8 @@ const create = () => __awaiter(void 0, void 0, void 0, function* () {
             figmaAccessToken: (figmaAccessToken || '').trim(),
             languagePreference,
             includeExamples,
+            includeVercel,
+            vercelBuildCommand,
         };
         // Create files
         const spinner = p.spinner();
@@ -287,7 +332,7 @@ const create = () => __awaiter(void 0, void 0, void 0, function* () {
         }
         // Combine mandatory templates with example templates based on user choice
         const templates = [
-            ...getMandatoryTemplates(includeExamples, languagePreference),
+            ...getMandatoryTemplates(includeExamples, languagePreference, includeVercel),
             ...(includeExamples ? getExampleTemplates(languagePreference) : []),
         ];
         try {

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

@@ -1,15 +1,15 @@
 import { CommandModule } from 'yargs';
 import { SharedArgs } from '../types';
-/** Entity kinds checkout-able from a connected workspace. */
-declare const ENTITY_KINDS: readonly ["component", "pattern", "page", "tokens", "assets"];
+import { RegistryEntityKind } from '../utils';
 export interface CheckoutArgs extends SharedArgs {
-    type: (typeof ENTITY_KINDS)[number];
+    type: RegistryEntityKind;
     id?: string;
 }
 /**
- * `handoff-app checkout <component|pattern|page> <id>` — pull an entity from the connected registry
- * into this workspace: writes its source files in standard authoring form and synthesizes a local
- * declaration.
+ * `handoff-app checkout <components|patterns|pages> [id]` pulls entities from the connected registry
+ * into this workspace, writing their source files in standard authoring form and synthesizing local
+ * declarations. Pass an `id` to pull that one entity, or omit it to pull every published entity of
+ * that kind.
  *
  * `handoff-app checkout tokens [setId]` — pull every published token set (or only the named set) into
  * this workspace: reconstruct `tokens.json` and restore the generated token files.

package/dist/commands/checkout/index.js

@@ -15,12 +15,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const __1 = __importDefault(require("../../"));
 const logger_1 = require("../../utils/logger");
 const utils_1 = require("../utils");
-/** Entity kinds checkout-able from a connected workspace. */
-const ENTITY_KINDS = ['component', 'pattern', 'page', 'tokens', 'assets'];
 /**
- * `handoff-app checkout <component|pattern|page> <id>` — pull an entity from the connected registry
- * into this workspace: writes its source files in standard authoring form and synthesizes a local
- * declaration.
+ * `handoff-app checkout <components|patterns|pages> [id]` pulls entities from the connected registry
+ * into this workspace, writing their source files in standard authoring form and synthesizing local
+ * declarations. Pass an `id` to pull that one entity, or omit it to pull every published entity of
+ * that kind.
  *
  * `handoff-app checkout tokens [setId]` — pull every published token set (or only the named set) into
  * this workspace: reconstruct `tokens.json` and restore the generated token files.
@@ -33,16 +32,16 @@ const ENTITY_KINDS = ['component', 'pattern', 'page', 'tokens', 'assets'];
  */
 const command = {
     command: 'checkout <type> [id]',
-    describe: 'Pull a component, pattern, page, design tokens, or assets from the connected registry into this workspace',
+    describe: 'Pull components, patterns, pages, design tokens, or assets from the connected registry into this workspace',
     builder: (yargs) => {
         return (0, utils_1.getSharedOptions)(yargs)
             .positional('type', {
             describe: 'The kind of entity to checkout',
-            choices: ENTITY_KINDS,
+            choices: utils_1.REGISTRY_ENTITY_KINDS,
             type: 'string',
         })
             .positional('id', {
-            describe: 'The stable id of the entity (component/pattern/page id, token set id, or asset collection); optional for tokens/assets',
+            describe: 'The stable id of the entity (component/pattern/page id, token set id, or asset collection); omit to checkout all of that kind',
             type: 'string',
         });
     },
@@ -57,10 +56,7 @@ const command = {
                 yield handoff.checkoutAssets(args.id);
                 return;
             }
-            if (!args.id) {
-                throw new Error(`An id is required to checkout a ${args.type} (e.g. "handoff-app checkout ${args.type} <id>").`);
-            }
-            yield handoff.checkout(args.type, args.id);
+            yield handoff.checkout(utils_1.ENTITY_WIRE_KIND[args.type], args.id);
         }
         catch (error) {
             logger_1.Logger.error(error instanceof Error ? error.message : String(error));

package/dist/commands/publish/index.d.ts

@@ -1,14 +1,15 @@
 import { CommandModule } from 'yargs';
 import { SharedArgs } from '../types';
-/** Entity kinds publishable from a connected workspace. */
-declare const ENTITY_KINDS: readonly ["component", "pattern", "page", "tokens", "assets"];
+import { RegistryEntityKind } from '../utils';
 export interface PublishArgs extends SharedArgs {
-    type: (typeof ENTITY_KINDS)[number];
+    type: RegistryEntityKind;
     id?: string;
 }
 /**
- * `handoff-app publish <component|pattern|page> <id>` — fresh targeted local build + upload of the
- * selected entity to the connected registry.
+ * `handoff-app publish <components|patterns|pages> [id]` runs a fresh local build and uploads to the
+ * connected registry. Pass an `id` to build and upload that one entity, or omit it to build the kind
+ * once and upload every declared entity, skipping any whose content already matches the registry
+ * (pass `--force` to re-upload everything).
  *
  * `handoff-app publish tokens [setId]` — fresh token build + upload of every logical token set, or
  * only the named set (`foundation/colors`, `component/button`).

package/dist/commands/publish/index.js

@@ -15,11 +15,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const __1 = __importDefault(require("../../"));
 const logger_1 = require("../../utils/logger");
 const utils_1 = require("../utils");
-/** Entity kinds publishable from a connected workspace. */
-const ENTITY_KINDS = ['component', 'pattern', 'page', 'tokens', 'assets'];
 /**
- * `handoff-app publish <component|pattern|page> <id>` — fresh targeted local build + upload of the
- * selected entity to the connected registry.
+ * `handoff-app publish <components|patterns|pages> [id]` runs a fresh local build and uploads to the
+ * connected registry. Pass an `id` to build and upload that one entity, or omit it to build the kind
+ * once and upload every declared entity, skipping any whose content already matches the registry
+ * (pass `--force` to re-upload everything).
  *
  * `handoff-app publish tokens [setId]` — fresh token build + upload of every logical token set, or
  * only the named set (`foundation/colors`, `component/button`).
@@ -30,16 +30,16 @@ const ENTITY_KINDS = ['component', 'pattern', 'page', 'tokens', 'assets'];
  */
 const command = {
     command: 'publish <type> [id]',
-    describe: 'Build and publish a component, pattern, page, design tokens, or assets to the connected registry',
+    describe: 'Build and publish components, patterns, pages, design tokens, or assets to the connected registry',
     builder: (yargs) => {
         return (0, utils_1.getSharedOptions)(yargs)
             .positional('type', {
             describe: 'The kind of entity to publish',
-            choices: ENTITY_KINDS,
+            choices: utils_1.REGISTRY_ENTITY_KINDS,
             type: 'string',
         })
             .positional('id', {
-            describe: 'The stable id of the entity (component/pattern/page id, token set id, or asset collection); optional for tokens/assets',
+            describe: 'The stable id of the entity (component/pattern/page id, token set id, or asset collection); omit to publish all of that kind',
             type: 'string',
         });
     },
@@ -54,10 +54,7 @@ const command = {
                 yield handoff.publishAssets(args.id);
                 return;
             }
-            if (!args.id) {
-                throw new Error(`An id is required to publish a ${args.type} (e.g. "handoff-app publish ${args.type} <id>").`);
-            }
-            yield handoff.publish(args.type, args.id);
+            yield handoff.publish(utils_1.ENTITY_WIRE_KIND[args.type], args.id);
         }
         catch (error) {
             logger_1.Logger.error(error instanceof Error ? error.message : String(error));

package/dist/commands/utils.d.ts

@@ -1,4 +1,10 @@
 import { Argv } from 'yargs';
+import type { TransferEntityKind } from '../registry/transfer';
+/** Plural entity kinds accepted by the `publish`/`checkout` commands. */
+export declare const REGISTRY_ENTITY_KINDS: readonly ["components", "patterns", "pages", "tokens", "assets"];
+export type RegistryEntityKind = (typeof REGISTRY_ENTITY_KINDS)[number];
+/** Map the plural CLI kind to the singular wire kind used by entity publish/checkout. */
+export declare const ENTITY_WIRE_KIND: Record<'components' | 'patterns' | 'pages', TransferEntityKind>;
 export declare const getSharedOptions: (yargs: Argv) => Argv<import("yargs").Omit<{}, "debug" | "config" | "force"> & import("yargs").InferredOptionTypes<{
     config: {
         alias: string;

package/dist/commands/utils.js

@@ -1,6 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSharedOptions = void 0;
+exports.getSharedOptions = exports.ENTITY_WIRE_KIND = exports.REGISTRY_ENTITY_KINDS = void 0;
+/** Plural entity kinds accepted by the `publish`/`checkout` commands. */
+exports.REGISTRY_ENTITY_KINDS = ['components', 'patterns', 'pages', 'tokens', 'assets'];
+/** Map the plural CLI kind to the singular wire kind used by entity publish/checkout. */
+exports.ENTITY_WIRE_KIND = {
+    components: 'component',
+    patterns: 'pattern',
+    pages: 'page',
+};
 const getSharedOptions = (yargs) => {
     return yargs.options({
         config: {

package/dist/index.d.ts

@@ -45,17 +45,21 @@ declare class Handoff {
      */
     dbMigrate(): Promise<Handoff>;
     /**
-     * Publish a single component, pattern, or page from this connected workspace to the configured
-     * remote registry. Components and patterns receive a fresh targeted build before upload. Pages
-     * upload their record and markdown source because they render at runtime. The publish module is
-     * loaded lazily so the registry client and build code never enter the docs app bundle.
+     * Publish components, patterns, or pages from this connected workspace to the configured remote
+     * registry. With `id` it publishes that one entity after a targeted build; without `id` it builds
+     * the kind once and publishes every declared entity, skipping ones whose content is unchanged on
+     * the registry (`--force` re-uploads all). Pages upload their record and markdown source because
+     * they render at runtime. The publish module is loaded lazily so the registry client and build code
+     * never enter the docs app bundle.
      */
-    publish(kind: 'component' | 'pattern' | 'page', id: string): Promise<Handoff>;
+    publish(kind: 'component' | 'pattern' | 'page', id?: string): Promise<Handoff>;
     /**
-     * Checkout a single component, pattern, or page from the connected remote registry. The checkout
-     * module is loaded lazily so the registry client never enters the docs app bundle.
+     * Checkout components, patterns, or pages from the connected remote registry into this workspace.
+     * With `id` it checks out that one entity; without `id` it checks out every published entity of the
+     * kind. Overwriting existing local files requires `--force` or an interactive confirmation. The
+     * checkout module is loaded lazily so the registry client never enters the docs app bundle.
      */
-    checkout(kind: 'component' | 'pattern' | 'page', id: string): Promise<Handoff>;
+    checkout(kind: 'component' | 'pattern' | 'page', id?: string): Promise<Handoff>;
     /**
      * Publish design token sets from this connected workspace to the configured remote registry. Runs a
      * fresh token build (Figma extract + style transformers), discovers the logical sets, and uploads

package/dist/index.js

@@ -159,28 +159,44 @@ class Handoff {
         });
     }
     /**
-     * Publish a single component, pattern, or page from this connected workspace to the configured
-     * remote registry. Components and patterns receive a fresh targeted build before upload. Pages
-     * upload their record and markdown source because they render at runtime. The publish module is
-     * loaded lazily so the registry client and build code never enter the docs app bundle.
+     * Publish components, patterns, or pages from this connected workspace to the configured remote
+     * registry. With `id` it publishes that one entity after a targeted build; without `id` it builds
+     * the kind once and publishes every declared entity, skipping ones whose content is unchanged on
+     * the registry (`--force` re-uploads all). Pages upload their record and markdown source because
+     * they render at runtime. The publish module is loaded lazily so the registry client and build code
+     * never enter the docs app bundle.
      */
     publish(kind, id) {
         return __awaiter(this, void 0, void 0, function* () {
             this.preRunner();
-            const { publishEntity } = yield Promise.resolve().then(() => __importStar(require('./registry/publish')));
-            yield publishEntity(this, kind, id);
+            if (id) {
+                const { publishEntity } = yield Promise.resolve().then(() => __importStar(require('./registry/publish')));
+                yield publishEntity(this, kind, id);
+            }
+            else {
+                const { publishEntities } = yield Promise.resolve().then(() => __importStar(require('./registry/publish')));
+                yield publishEntities(this, kind);
+            }
             return this;
         });
     }
     /**
-     * Checkout a single component, pattern, or page from the connected remote registry. The checkout
-     * module is loaded lazily so the registry client never enters the docs app bundle.
+     * Checkout components, patterns, or pages from the connected remote registry into this workspace.
+     * With `id` it checks out that one entity; without `id` it checks out every published entity of the
+     * kind. Overwriting existing local files requires `--force` or an interactive confirmation. The
+     * checkout module is loaded lazily so the registry client never enters the docs app bundle.
      */
     checkout(kind, id) {
         return __awaiter(this, void 0, void 0, function* () {
             this.preRunner();
-            const { checkoutEntity } = yield Promise.resolve().then(() => __importStar(require('./registry/checkout')));
-            yield checkoutEntity(this, kind, id);
+            if (id) {
+                const { checkoutEntity } = yield Promise.resolve().then(() => __importStar(require('./registry/checkout')));
+                yield checkoutEntity(this, kind, id);
+            }
+            else {
+                const { checkoutEntities } = yield Promise.resolve().then(() => __importStar(require('./registry/checkout')));
+                yield checkoutEntities(this, kind);
+            }
             return this;
         });
     }

package/dist/registry/asset-storage/resolve.d.ts

@@ -3,7 +3,7 @@
  *
  * `runtime.registry.assetStorage` selects the active provider for **new** uploads: the built-in
  * `database` inline default, the pre-packaged `vercel-blob` adapter, or a `custom` module. Mirrors
- * {@link import('../db/adapter')}: only provider selection, module location, non-secret options, and
+ * {@link import('../db/driver')}: only provider selection, module location, non-secret options, and
  * env-var *names* are ever persisted; secret *values* are read from `process.env` at request time.
  */
 import type { Config } from '../../types/config';

package/dist/registry/asset-storage/resolve.js

@@ -4,7 +4,7 @@
  *
  * `runtime.registry.assetStorage` selects the active provider for **new** uploads: the built-in
  * `database` inline default, the pre-packaged `vercel-blob` adapter, or a `custom` module. Mirrors
- * {@link import('../db/adapter')}: only provider selection, module location, non-secret options, and
+ * {@link import('../db/driver')}: only provider selection, module location, non-secret options, and
  * env-var *names* are ever persisted; secret *values* are read from `process.env` at request time.
  */
 Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -1,7 +1,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
@@ -25,9 +25,14 @@ export declare class CheckoutError extends Error {
  */
 export declare const resolveConnectionOrThrow: (handoff: Handoff) => import("../connection").ResolvedRegistryConnection;
 /**
- * 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 a single component, pattern, or page from the connected registry into this workspace.
+ * Overwriting existing local files requires `--force` or an interactive confirmation.
  */
 export declare const checkoutEntity: (handoff: Handoff, kind: TransferEntityKind, id: string) => Promise<void>;
+/**
+ * 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`).
+ */
+export declare const checkoutEntities: (handoff: Handoff, kind: TransferEntityKind) => Promise<void>;

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,7 +60,7 @@ 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"));
@@ -551,26 +551,25 @@ 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;
     }
@@ -607,4 +606,56 @@ const checkoutEntity = (handoff, kind, id) => __awaiter(void 0, void 0, void 0,
     logger_1.Logger.success(`Checked out ${kind} "${id}" into ${path_1.default.relative(handoff.workingPath, targetDir) || '.'} ` +
         `(${payload.files.length} source file(s) + ${declarationFileName}).`);
 });
+/**
+ * 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 = (0, exports.resolveConnectionOrThrow)(handoff);
+    const client = (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken });
+    yield checkoutSingle(handoff, kind, id, client, connection.url);
+});
 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 = (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 = [];
+    for (const { id } of summaries) {
+        try {
+            yield checkoutSingle(handoff, kind, id, client, connection.url);
+            checkedOut += 1;
+        }
+        catch (error) {
+            failed.push({ id, message: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    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/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>;