handoff-app 2.0.0-4 → 2.0.0-6

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`,

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

@@ -1,7 +1,7 @@
 /**
  * Connected-workspace asset publish orchestration.
  *
- * `publish assets [collection]` runs a fresh build (`handoff.fetch()`), discovers the collections, and
+ * `publish assets [collection...]` runs a fresh build (`handoff.fetch()`), discovers the collections, and
  * uploads each changed one. A collection is skipped when its deterministic `sourceHash` is unchanged;
  * content transfers blob-by-blob (only hashes the registry lacks, since content-addressed dedup is the
  * per-blob skip-unchanged), and the manifest is finalized atomically only after its blobs exist.
@@ -13,4 +13,4 @@ import Handoff from '../../index';
  * blobs, and finalizes each manifest atomically. Reports published/unchanged/uploaded/failed counts;
  * throws at the end if any collection failed.
  */
-export declare const publishAssets: (handoff: Handoff, collection?: string) => Promise<void>;
+export declare const publishAssets: (handoff: Handoff, selection?: string[]) => Promise<void>;

package/dist/registry/publish/assets.js

@@ -2,7 +2,7 @@
 /**
  * Connected-workspace asset publish orchestration.
  *
- * `publish assets [collection]` runs a fresh build (`handoff.fetch()`), discovers the collections, and
+ * `publish assets [collection...]` runs a fresh build (`handoff.fetch()`), discovers the collections, and
  * uploads each changed one. A collection is skipped when its deterministic `sourceHash` is unchanged;
  * content transfers blob-by-blob (only hashes the registry lacks, since content-addressed dedup is the
  * per-blob skip-unchanged), and the manifest is finalized atomically only after its blobs exist.
@@ -20,7 +20,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.publishAssets = void 0;
 const logger_1 = require("../../utils/logger");
 const sets_1 = require("../assets/sets");
-const client_1 = require("../client");
+const selection_1 = require("../selection");
 const errors_1 = require("./errors");
 const index_1 = require("./index");
 const publish_build_1 = require("./publish-build");
@@ -49,22 +49,29 @@ const toManifestEntry = (asset) => {
  * blobs, and finalizes each manifest atomically. Reports published/unchanged/uploaded/failed counts;
  * throws at the end if any collection failed.
  */
-const publishAssets = (handoff, collection) => __awaiter(void 0, void 0, void 0, function* () {
-    const connection = yield (0, index_1.resolveConnectionOrThrow)(handoff);
-    if (collection && !(0, sets_1.isAssetCollection)(collection)) {
-        throw new index_1.PublishError(`Unknown asset collection "${collection}". Supported collections: ${sets_1.ASSET_COLLECTIONS.join(', ')}.`);
+const publishAssets = (handoff, selection) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const { client, url } = yield (0, index_1.resolveTransport)(handoff);
+    const unsupported = (_a = selection === null || selection === void 0 ? void 0 : selection.filter((collection) => !(0, sets_1.isAssetCollection)(collection))) !== null && _a !== void 0 ? _a : [];
+    if (unsupported.length > 0) {
+        throw new index_1.PublishError(`Unknown asset collection ${unsupported.map((name) => `"${name}"`).join(', ')}. ` +
+            `Supported collections: ${sets_1.ASSET_COLLECTIONS.join(', ')}.`);
     }
-    logger_1.Logger.info(collection ? `Building assets to publish "${collection}"…` : 'Building assets for publish…');
-    yield handoff.fetch();
-    const available = yield handoff.store.assets.listCollections();
-    const targets = collection && (0, sets_1.isAssetCollection)(collection) ? [collection] : available.filter(sets_1.isAssetCollection);
-    const client = (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken });
-    let remote = [];
-    try {
-        remote = yield client.listAssetCollections();
+    if (!handoff.skipBuild) {
+        logger_1.Logger.info(selection ? `Building assets to publish ${selection.join(', ')}…` : 'Building assets for publish…');
+        yield handoff.fetch();
     }
-    catch (_a) {
-        logger_1.Logger.info('Could not read current registry asset collections; publishing all selected collections.');
+    const available = (yield handoff.store.assets.listCollections()).filter(sets_1.isAssetCollection);
+    const targets = (0, selection_1.selectIds)(available, selection).selected;
+    // Without a registry there is nothing to compare against, so a dry run reports every collection.
+    let remote = [];
+    if (client) {
+        try {
+            remote = yield client.listAssetCollections();
+        }
+        catch (_b) {
+            logger_1.Logger.info('Could not read current registry asset collections; publishing all selected collections.');
+        }
     }
     const remoteHashByCollection = new Map(remote.map((entry) => [entry.collection, entry.sourceHash]));
     let published = 0;
@@ -90,35 +97,39 @@ const publishAssets = (handoff, collection) => __awaiter(void 0, void 0, void 0,
                 if (!byHash.has(asset.contentHash))
                     byHash.set(asset.contentHash, asset);
             }
-            const missing = yield client.assetBlobHaveCheck(Array.from(byHash.keys()));
-            for (const hash of missing) {
-                const asset = byHash.get(hash);
-                if (!asset)
-                    continue;
-                const content = yield handoff.store.assets.getAssetContent(col, asset.path);
-                if (!(content === null || content === void 0 ? void 0 : content.body)) {
-                    throw new Error(`Could not read bytes for asset "${asset.path}" in collection "${col}".`);
+            // A dry run has no registry to ask, so every deduped blob counts as one that would upload.
+            const missing = client ? yield client.assetBlobHaveCheck(Array.from(byHash.keys())) : Array.from(byHash.keys());
+            if (client) {
+                for (const hash of missing) {
+                    const asset = byHash.get(hash);
+                    if (!asset)
+                        continue;
+                    const content = yield handoff.store.assets.getAssetContent(col, asset.path);
+                    if (!(content === null || content === void 0 ? void 0 : content.body)) {
+                        throw new Error(`Could not read bytes for asset "${asset.path}" in collection "${col}".`);
+                    }
+                    yield client.uploadAssetBlob(hash, content.contentType, content.body);
+                    uploaded += 1;
                 }
-                yield client.uploadAssetBlob(hash, content.contentType, content.body);
-                uploaded += 1;
+                const pkg = {
+                    collection: col,
+                    build: (0, publish_build_1.createCurrentBuild)({ sourceHash }),
+                    assets: manifest.map(toManifestEntry),
+                };
+                yield client.publishAssetManifest(pkg);
             }
-            const pkg = {
-                collection: col,
-                build: (0, publish_build_1.createCurrentBuild)({ sourceHash }),
-                assets: manifest.map(toManifestEntry),
-            };
-            yield client.publishAssetManifest(pkg);
             published += 1;
-            logger_1.Logger.info(`Published: ${col} (${manifest.length} asset(s), ${missing.length} new blob(s))`);
+            logger_1.Logger.info(`${(0, index_1.publishedLabel)(handoff)}: ${col} (${manifest.length} asset(s), ${missing.length} new blob(s))`);
         }
         catch (error) {
             failed.push({
                 collection: col,
-                message: (0, errors_1.describePublishError)(error, connection.url, 'asset collection'),
+                message: (0, errors_1.describePublishError)(error, url, 'asset collection'),
             });
         }
     }
-    logger_1.Logger.success(`Assets publish complete: ${published} published, ${unchanged} unchanged, ${uploaded} blob(s) uploaded${failed.length ? `, ${failed.length} failed` : ''}.`);
+    logger_1.Logger.success(`Assets publish complete: ${published} ${handoff.dryRun ? 'would be published' : 'published'}, ` +
+        `${unchanged} unchanged, ${uploaded} blob(s) uploaded${failed.length ? `, ${failed.length} failed` : ''}.`);
     if (failed.length > 0) {
         for (const failure of failed) {
             logger_1.Logger.error(`  - ${failure.collection}: ${failure.message}`);

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

@@ -9,26 +9,50 @@
  * that still guarantees the entity's artifacts (and the shared artifacts they reference) are current.
  */
 import Handoff from '../../index';
+import { type RegistryClient } from '../client';
 import type { TransferEntityKind } from '../transfer';
 /** A connected-workspace configuration or precondition failure surfaced to the CLI. */
 export declare class PublishError extends Error {
     constructor(message: string);
 }
+/**
+ * Ensure this project may publish at all: a registry host stores and serves what was published to it,
+ * so only a workspace runtime can be the source. Kept apart from the connection lookup because a dry
+ * run still has to be refused on a registry host while needing no URL or token itself.
+ */
+export declare const assertPublishableWorkspace: (handoff: Handoff) => void;
 /**
  * Ensure the workspace is a connected workspace able to publish: workspace runtime mode (registry
  * hosts do not publish) and a resolved registry URL + access token. Throws an actionable
  * {@link PublishError} naming the exact misconfiguration.
  */
 export declare const resolveConnectionOrThrow: (handoff: Handoff) => Promise<import("../connection").ResolvedRegistryConnection>;
+/**
+ * How a publish run reaches the registry. `client` is `null` on a dry run: the documented dry run
+ * needs no registry URL or token, so it stops at the workspace guard and contacts nothing.
+ */
+export interface PublishTransport {
+    client: RegistryClient | null;
+    /** The registry URL, or a placeholder on a dry run. Used only in log lines and error messages. */
+    url: string;
+}
+/**
+ * Resolve the transport for a publish run. Shared by the entity, token and asset paths so the dry-run
+ * short-circuit lives in one place instead of four call sites.
+ */
+export declare const resolveTransport: (handoff: Handoff) => Promise<PublishTransport>;
+/** Prefix for a per-item progress line: `Published:` normally, `Would publish:` on a dry run. */
+export declare const publishedLabel: (handoff: Handoff) => string;
 /**
  * Publish a single component, pattern, or page from a connected workspace. Components and patterns
  * receive a targeted build, while pages are packaged directly from their source.
  */
 export declare const publishEntity: (handoff: Handoff, kind: TransferEntityKind, id: string) => Promise<void>;
 /**
- * Publish every component, pattern, or page declared in this connected workspace. Builds the kind
- * once, assembles each entity's package, skips entities whose content hash already matches the
- * registry (unless `--force`), and reports published/unchanged/failed counts. A per-entity failure is
- * collected and never aborts the rest; the run throws at the end if any entity failed.
+ * Publish the components, patterns or pages declared in this connected workspace: every one of the
+ * kind, or only `ids` when given. Builds the kind once, assembles each entity's package, skips
+ * entities whose content hash already matches the registry (unless `--force`), and reports
+ * published/unchanged/failed counts. A per-entity failure is collected and never aborts the rest; the
+ * run throws at the end if any entity failed.
  */
-export declare const publishEntities: (handoff: Handoff, kind: TransferEntityKind) => Promise<void>;
+export declare const publishEntities: (handoff: Handoff, kind: TransferEntityKind, ids?: string[]) => Promise<void>;

package/dist/registry/publish/index.js

@@ -22,7 +22,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.publishEntities = exports.publishEntity = exports.resolveConnectionOrThrow = exports.PublishError = void 0;
+exports.publishEntities = exports.publishEntity = exports.publishedLabel = exports.resolveTransport = exports.resolveConnectionOrThrow = exports.assertPublishableWorkspace = exports.PublishError = void 0;
 const css_1 = require("../../transformers/preview/component/css");
 const javascript_1 = require("../../transformers/preview/component/javascript");
 const builder_1 = __importDefault(require("../../transformers/preview/component/builder"));
@@ -30,6 +30,7 @@ const builder_2 = require("../../transformers/preview/pattern/builder");
 const logger_1 = require("../../utils/logger");
 const client_1 = require("../client");
 const connection_1 = require("../connection");
+const selection_1 = require("../selection");
 const errors_1 = require("./errors");
 const package_1 = require("./package");
 /** A connected-workspace configuration or precondition failure surfaced to the CLI. */
@@ -41,17 +42,26 @@ class PublishError extends Error {
 }
 exports.PublishError = PublishError;
 /**
- * Ensure the workspace is a connected workspace able to publish: workspace runtime mode (registry
- * hosts do not publish) and a resolved registry URL + access token. Throws an actionable
- * {@link PublishError} naming the exact misconfiguration.
+ * Ensure this project may publish at all: a registry host stores and serves what was published to it,
+ * so only a workspace runtime can be the source. Kept apart from the connection lookup because a dry
+ * run still has to be refused on a registry host while needing no URL or token itself.
  */
-const resolveConnectionOrThrow = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
+const assertPublishableWorkspace = (handoff) => {
     var _a, _b, _c;
     const mode = (_c = (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.runtime) === null || _b === void 0 ? void 0 : _b.mode) !== null && _c !== void 0 ? _c : 'workspace';
     if (mode !== 'workspace') {
         throw new PublishError(`publish is only available from a connected workspace (runtime.mode: "workspace"); this project is "${mode}". ` +
             'A registry host stores and serves what was published to it; it does not publish.');
     }
+};
+exports.assertPublishableWorkspace = assertPublishableWorkspace;
+/**
+ * Ensure the workspace is a connected workspace able to publish: workspace runtime mode (registry
+ * hosts do not publish) and a resolved registry URL + access token. Throws an actionable
+ * {@link PublishError} naming the exact misconfiguration.
+ */
+const resolveConnectionOrThrow = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    (0, exports.assertPublishableWorkspace)(handoff);
     const connection = yield (0, connection_1.resolveAuthenticatedRegistryConnection)(handoff.config, handoff.workingPath);
     if (!connection.url) {
         throw new PublishError(`No registry is configured. Run \`handoff-app login --url <registry-url>\`, set runtime.registryConnection.url, ` +
@@ -64,6 +74,25 @@ const resolveConnectionOrThrow = (handoff) => __awaiter(void 0, void 0, void 0,
     return connection;
 });
 exports.resolveConnectionOrThrow = resolveConnectionOrThrow;
+/**
+ * Resolve the transport for a publish run. Shared by the entity, token and asset paths so the dry-run
+ * short-circuit lives in one place instead of four call sites.
+ */
+const resolveTransport = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    if (handoff.dryRun) {
+        (0, exports.assertPublishableWorkspace)(handoff);
+        return { client: null, url: '(dry run)' };
+    }
+    const connection = yield (0, exports.resolveConnectionOrThrow)(handoff);
+    return {
+        client: (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken }),
+        url: connection.url,
+    };
+});
+exports.resolveTransport = resolveTransport;
+/** Prefix for a per-item progress line: `Published:` normally, `Would publish:` on a dry run. */
+const publishedLabel = (handoff) => (handoff.dryRun ? 'Would publish' : 'Published');
+exports.publishedLabel = publishedLabel;
 /** Run the smallest build that guarantees the selected entity's artifacts are current. */
 const runTargetedBuild = (handoff, kind, id) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
@@ -105,19 +134,26 @@ const runTargetedBuild = (handoff, kind, id) => __awaiter(void 0, void 0, void 0
  * receive a targeted build, while pages are packaged directly from their source.
  */
 const publishEntity = (handoff, kind, id) => __awaiter(void 0, void 0, void 0, function* () {
-    const connection = yield (0, exports.resolveConnectionOrThrow)(handoff);
-    logger_1.Logger.info(kind === 'page' ? `Preparing page "${id}" for publish…` : `Building ${kind} "${id}" for publish…`);
-    yield runTargetedBuild(handoff, kind, id);
+    const { client, url } = yield (0, exports.resolveTransport)(handoff);
+    if (!handoff.skipBuild) {
+        logger_1.Logger.info(kind === 'page' ? `Preparing page "${id}" for publish…` : `Building ${kind} "${id}" for publish…`);
+        yield runTargetedBuild(handoff, kind, id);
+    }
     const pkg = yield (0, package_1.buildPublishPackage)(handoff, kind, id);
     (0, package_1.assertRequiredArtifactsPresent)(pkg);
-    logger_1.Logger.info(`Uploading ${kind} "${id}" to ${connection.url} (${pkg.artifacts.length} artifact(s), ${pkg.files.length} source file(s))…`);
-    const client = (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken });
+    const contents = `${pkg.artifacts.length} artifact(s), ${pkg.files.length} source file(s)`;
+    if (!client) {
+        logger_1.Logger.info(`Would publish ${kind} "${id}" (${contents}).`);
+        logger_1.Logger.success(`Dry run: ${kind} "${id}" would be published.`);
+        return;
+    }
+    logger_1.Logger.info(`Uploading ${kind} "${id}" to ${url} (${contents})…`);
     try {
         yield client.publish(kind, id, pkg);
     }
     catch (error) {
         if (error instanceof client_1.RegistryClientError) {
-            throw new PublishError((0, errors_1.describeUploadFailure)(error, connection.url, 'package'));
+            throw new PublishError((0, errors_1.describeUploadFailure)(error, url, 'package'));
         }
         throw error;
     }
@@ -144,27 +180,46 @@ const runBulkBuild = (handoff, kind) => __awaiter(void 0, void 0, void 0, functi
 });
 /** List every declared entity id of the kind from the workspace store. */
 const listWorkspaceEntityIds = (handoff, kind) => __awaiter(void 0, void 0, void 0, function* () {
-    const store = kind === 'component' ? handoff.store.components : kind === 'pattern' ? handoff.store.patterns : handoff.store.pages;
+    const stores = { component: handoff.store.components, pattern: handoff.store.patterns, page: handoff.store.pages };
+    const store = stores[kind];
+    if (!store) {
+        throw new PublishError(`Unknown entity kind "${kind}".`);
+    }
     return (yield store.list()).map((entity) => entity.id);
 });
 /**
- * Publish every component, pattern, or page declared in this connected workspace. Builds the kind
- * once, assembles each entity's package, skips entities whose content hash already matches the
- * registry (unless `--force`), and reports published/unchanged/failed counts. A per-entity failure is
- * collected and never aborts the rest; the run throws at the end if any entity failed.
+ * Narrow the workspace's declared ids to the requested subset, naming any id that is not declared
+ * here instead of silently publishing fewer entities than asked for.
  */
-const publishEntities = (handoff, kind) => __awaiter(void 0, void 0, void 0, function* () {
-    const connection = yield (0, exports.resolveConnectionOrThrow)(handoff);
-    logger_1.Logger.info(`Building ${kind}s for publish…`);
-    yield runBulkBuild(handoff, kind);
-    const ids = yield listWorkspaceEntityIds(handoff, kind);
-    if (ids.length === 0) {
+const selectEntityIds = (available, requested, kind) => {
+    const { selected, unknown } = (0, selection_1.selectIds)(available, requested);
+    if (unknown.length > 0) {
+        throw new PublishError(`No ${kind} named ${unknown.map((id) => `"${id}"`).join(', ')} is declared in this workspace. ` +
+            `Declared ${kind}s: ${available.join(', ') || '(none)'}.`);
+    }
+    return selected;
+};
+/**
+ * Publish the components, patterns or pages declared in this connected workspace: every one of the
+ * kind, or only `ids` when given. Builds the kind once, assembles each entity's package, skips
+ * entities whose content hash already matches the registry (unless `--force`), and reports
+ * published/unchanged/failed counts. A per-entity failure is collected and never aborts the rest; the
+ * run throws at the end if any entity failed.
+ */
+const publishEntities = (handoff, kind, ids) => __awaiter(void 0, void 0, void 0, function* () {
+    const { client, url } = yield (0, exports.resolveTransport)(handoff);
+    if (!handoff.skipBuild) {
+        logger_1.Logger.info(`Building ${kind}s for publish…`);
+        yield runBulkBuild(handoff, kind);
+    }
+    const targets = selectEntityIds(yield listWorkspaceEntityIds(handoff, kind), ids, kind);
+    if (targets.length === 0) {
         logger_1.Logger.success(`No ${kind}s are declared in this workspace; nothing to publish.`);
         return;
     }
-    const client = (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken });
+    // Without a registry there is nothing to compare against, so a dry run reports every target.
     let remote = [];
-    if (!handoff.force) {
+    if (client && !handoff.force) {
         try {
             remote = yield client.listEntities(kind);
         }
@@ -177,7 +232,7 @@ const publishEntities = (handoff, kind) => __awaiter(void 0, void 0, void 0, fun
     let published = 0;
     let unchanged = 0;
     const failed = [];
-    for (const id of ids) {
+    for (const id of targets) {
         try {
             const pkg = yield (0, package_1.buildPublishPackage)(handoff, kind, id);
             (0, package_1.assertRequiredArtifactsPresent)(pkg);
@@ -188,20 +243,18 @@ const publishEntities = (handoff, kind) => __awaiter(void 0, void 0, void 0, fun
                 logger_1.Logger.info(`Unchanged: ${id}`);
                 continue;
             }
-            yield client.publish(kind, id, pkg);
+            if (client) {
+                yield client.publish(kind, id, pkg);
+            }
             published += 1;
-            logger_1.Logger.info(`Published: ${id} (${pkg.artifacts.length} artifact(s), ${pkg.files.length} source file(s))`);
+            logger_1.Logger.info(`${(0, exports.publishedLabel)(handoff)}: ${id} (${pkg.artifacts.length} artifact(s), ${pkg.files.length} source file(s))`);
         }
         catch (error) {
-            const message = error instanceof client_1.RegistryClientError
-                ? (0, errors_1.describeUploadFailure)(error, connection.url, 'package')
-                : error instanceof Error
-                    ? error.message
-                    : String(error);
-            failed.push({ id, message });
+            failed.push({ id, message: (0, errors_1.describePublishError)(error, url, 'package') });
         }
     }
-    logger_1.Logger.success(`${kind[0].toUpperCase()}${kind.slice(1)}s publish complete — ${published} published, ${unchanged} unchanged${failed.length ? `, ${failed.length} failed` : ''}.`);
+    logger_1.Logger.success(`${kind[0].toUpperCase()}${kind.slice(1)}s publish complete — ${published} ${handoff.dryRun ? 'would be published' : 'published'}, ` +
+        `${unchanged} unchanged${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/publish/tokens.d.ts

@@ -1,7 +1,7 @@
 /**
  * Connected-workspace token publish orchestration.
  *
- * `publish tokens [setId]` runs a **fresh token build** (`handoff.fetch()` — Figma extract +
+ * `publish tokens [setId...]` runs a **fresh token build** (`handoff.fetch()` — Figma extract +
  * `buildStyles`) so the local `tokens.json` and generated token outputs are current, discovers the
  * logical sets from that document, then uploads each selected set (its extracted record + generated
  * artifacts) to the connected registry. Each set is one atomic upsert; a set whose deterministic
@@ -15,4 +15,4 @@ import Handoff from '../../index';
  * counts. A per-set upload failure is collected and never leaves a partially written set (each set is
  * committed atomically server-side); the run throws at the end if any set failed.
  */
-export declare const publishTokens: (handoff: Handoff, setId?: string) => Promise<void>;
+export declare const publishTokens: (handoff: Handoff, selection?: string[]) => Promise<void>;