handoff-app 2.0.0-3 → 2.0.0-5

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>;

package/dist/registry/publish/tokens.js

@@ -2,7 +2,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
@@ -22,7 +22,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.publishTokens = void 0;
 const logger_1 = require("../../utils/logger");
 const stable_stringify_1 = require("../../utils/stable-stringify");
-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");
@@ -58,28 +58,31 @@ const buildTokenSetPackage = (handoff, set) => __awaiter(void 0, void 0, void 0,
  * 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.
  */
-const publishTokens = (handoff, setId) => __awaiter(void 0, void 0, void 0, function* () {
-    const connection = yield (0, index_1.resolveConnectionOrThrow)(handoff);
-    logger_1.Logger.info(setId ? `Building tokens to publish "${setId}"…` : 'Building tokens for publish…');
-    yield handoff.fetch();
+const publishTokens = (handoff, selection) => __awaiter(void 0, void 0, void 0, function* () {
+    const { client, url } = yield (0, index_1.resolveTransport)(handoff);
+    if (!handoff.skipBuild) {
+        logger_1.Logger.info(selection ? `Building tokens to publish ${selection.map((id) => `"${id}"`).join(', ')}…` : 'Building tokens for publish…');
+        yield handoff.fetch();
+    }
     const allSets = yield handoff.store.tokens.listSets();
-    let targetSets = allSets;
-    if (setId) {
-        const found = allSets.find((set) => set.id === setId);
-        if (!found) {
-            throw new index_1.PublishError(`Token set "${setId}" was not found in the generated tokens. Discovered sets: ${allSets.map((set) => set.id).join(', ') || '(none)'}.`);
-        }
-        targetSets = [found];
+    const { selected, unknown } = (0, selection_1.selectIds)(allSets.map((set) => set.id), selection);
+    if (unknown.length > 0) {
+        throw new index_1.PublishError(`Token set ${unknown.map((id) => `"${id}"`).join(', ')} was not found in the generated tokens. ` +
+            `Discovered sets: ${allSets.map((set) => set.id).join(', ') || '(none)'}.`);
     }
+    const selectedIds = new Set(selected);
+    const targetSets = allSets.filter((set) => selectedIds.has(set.id));
     const packages = yield Promise.all(targetSets.map((set) => buildTokenSetPackage(handoff, set)));
-    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 set.
     let remote = [];
-    try {
-        remote = yield client.listTokenSets();
-    }
-    catch (error) {
-        // If the summary listing fails we simply publish everything (the server still no-ops unchanged sets).
-        logger_1.Logger.info('Could not read current registry token sets; publishing all selected sets.');
+    if (client) {
+        try {
+            remote = yield client.listTokenSets();
+        }
+        catch (error) {
+            // If the summary listing fails we simply publish everything (the server still no-ops unchanged sets).
+            logger_1.Logger.info('Could not read current registry token sets; publishing all selected sets.');
+        }
     }
     const remoteHashById = new Map(remote.map((entry) => [entry.id, entry.sourceHash]));
     let published = 0;
@@ -93,15 +96,18 @@ const publishTokens = (handoff, setId) => __awaiter(void 0, void 0, void 0, func
             continue;
         }
         try {
-            yield client.publishTokens(pkg);
+            if (client) {
+                yield client.publishTokens(pkg);
+            }
             published += 1;
-            logger_1.Logger.info(`Published: ${pkg.id} (${pkg.artifacts.length} artifact(s))`);
+            logger_1.Logger.info(`${(0, index_1.publishedLabel)(handoff)}: ${pkg.id} (${pkg.artifacts.length} artifact(s))`);
         }
         catch (error) {
-            failed.push({ id: pkg.id, message: (0, errors_1.describePublishError)(error, connection.url, 'token set') });
+            failed.push({ id: pkg.id, message: (0, errors_1.describePublishError)(error, url, 'token set') });
         }
     }
-    logger_1.Logger.success(`Tokens publish complete — ${published} published, ${unchanged} unchanged${failed.length ? `, ${failed.length} failed` : ''}.`);
+    logger_1.Logger.success(`Tokens 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/selection.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Selection narrowing shared by the publish and checkout orchestration.
+ *
+ * Every bulk operation discovers what is available (declared locally or published remotely) and may
+ * be asked for only part of it. Splitting the request into what exists and what does not lets each
+ * caller build its own actionable error while the matching lives in one place.
+ */
+/** Narrow an available list to the requested subset, separating out ids that do not exist. */
+export declare const selectIds: (available: string[], requested?: string[]) => {
+    selected: string[];
+    unknown: string[];
+};

package/dist/registry/selection.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Selection narrowing shared by the publish and checkout orchestration.
+ *
+ * Every bulk operation discovers what is available (declared locally or published remotely) and may
+ * be asked for only part of it. Splitting the request into what exists and what does not lets each
+ * caller build its own actionable error while the matching lives in one place.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectIds = void 0;
+/** Narrow an available list to the requested subset, separating out ids that do not exist. */
+const selectIds = (available, requested) => {
+    if (!requested) {
+        return { selected: available, unknown: [] };
+    }
+    const availableIds = new Set(available);
+    return {
+        selected: requested.filter((id) => availableIds.has(id)),
+        unknown: requested.filter((id) => !availableIds.has(id)),
+    };
+};
+exports.selectIds = selectIds;

package/dist/store/registry.d.ts

@@ -57,6 +57,54 @@ export declare class RegistryPageStore implements PageStore {
     getSource(_ref: SourceReference): Promise<TextFileResource | null>;
     getRelatedSourceFiles(id: string): Promise<TextFileResource[]>;
 }
+/**
+ * The page fields that search reads. The query cuts the stored parsed body to `bodyLength`.
+ * The body is empty for an external-link page and for a page with no stored markdown.
+ */
+export interface PageSearchCandidate {
+    record: PageListObject;
+    body: string;
+}
+export interface PageSearchCandidateQuery {
+    /** Normalized terms. A page is a candidate when any term occurs in any searchable column. */
+    terms: string[];
+    /** Optional group filter, matched case-insensitively. */
+    group?: string;
+    /** Maximum rows returned to the server for one search. */
+    limit: number;
+    /**
+     * Code points of each returned body, and the prefix the body filter reads, so one search costs at most
+     * `limit × bodyLength`. The query cuts with `left`, which counts code points. Workspace search must count the same
+     * unit, or the modes match different text.
+     */
+    bodyLength: number;
+}
+/**
+ * Candidate pages for a search, filtered and capped in SQL.
+ *
+ * `enabled` and `menuTitle` are fields in the `record` JSON, so the query uses JSON operators. An
+ * absent `enabled` field means enabled. The body filter excludes frontmatter, so an excluded field
+ * such as `metaTitle` cannot consume a candidate slot.
+ *
+ * The filter and the projection share one body expression, so every term SQL matched is inside the text that the
+ * server ranks.
+ *
+ * The body expression is empty for an external-link page. Search reads such a page by title, menu title, and
+ * description only. The exclusion must happen in SQL. An external body otherwise satisfies the filter and takes one
+ * of the `limit` rows. It pushes a real candidate past the cap before the server can drop it.
+ *
+ * `C` collation orders IDs by code point, as the merge in registry search does. Both orders must
+ * agree, or the cap can keep different pages in each runtime mode.
+ */
+export declare const searchPageCandidates: (db: RegistryDatabase, query: PageSearchCandidateQuery) => Promise<PageSearchCandidate[]>;
+/**
+ * The candidate IDs that have a published page. Search asks only about packaged default IDs, because
+ * no other ID can replace a default. This keeps the query bounded as the registry grows.
+ *
+ * A published page replaces the default with the same ID even when it does not match the search
+ * terms, so this query ignores the term filter.
+ */
+export declare const filterPublishedPageIds: (db: RegistryDatabase, candidateIds: string[]) => Promise<string[]>;
 export declare class RegistryTokenStore implements TokenStore {
     private readonly context;
     constructor(context: RegistryStoreContext);