handoff-app 2.0.0-4 → 2.0.0-5

package/dist/commands/utils.js

@@ -1,20 +1,53 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-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',
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
 };
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTarget = exports.withTargetPositionals = exports.getCheckoutOptions = exports.getPublishOptions = exports.getSharedOptions = exports.runRegistryCommand = exports.createHandoff = exports.REGISTRY_TARGET_KINDS = void 0;
+const __1 = __importDefault(require("../"));
+const content_kinds_1 = require("../registry/content-kinds");
+const logger_1 = require("../utils/logger");
+/** The `type` argument accepted by publish/checkout: any content kind, or `all` for every kind. */
+exports.REGISTRY_TARGET_KINDS = [...content_kinds_1.REGISTRY_ENTITY_KINDS, 'all'];
+const createHandoff = (args) => new __1.default({
+    debug: args.debug,
+    force: args.force,
+    configPath: args.config,
+    dryRun: args.dryRun,
+    // yargs gives `--no-build` as `build: false`; anything else leaves the build in place.
+    skipBuild: args.build === false,
+});
+exports.createHandoff = createHandoff;
+/**
+ * Run a registry command against a fresh Handoff. Registry failures are the user's to act on, so they
+ * surface as one actionable line and a non-zero exit rather than a stack trace.
+ */
+const runRegistryCommand = (args, run) => __awaiter(void 0, void 0, void 0, function* () {
+    const handoff = (0, exports.createHandoff)(args);
+    try {
+        yield run(handoff);
+    }
+    catch (error) {
+        logger_1.Logger.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+});
+exports.runRegistryCommand = runRegistryCommand;
 const getSharedOptions = (yargs) => {
     return yargs.options({
         config: {
             alias: 'c',
             type: 'string',
-            description: 'Path to config file',
+            description: 'Path to config file, relative to the working directory',
         },
         force: {
             alias: 'f',
@@ -29,3 +62,49 @@ const getSharedOptions = (yargs) => {
     });
 };
 exports.getSharedOptions = getSharedOptions;
+/** Shared options plus the transfer options: publish and its compatibility aliases use these. */
+const getPublishOptions = (yargs) => (0, exports.getSharedOptions)(yargs).options({
+    'dry-run': {
+        type: 'boolean',
+        description: 'Report what would be published without contacting the registry (the build still runs; add --no-build to skip it)',
+    },
+    build: {
+        type: 'boolean',
+        default: true,
+        description: 'Run a fresh build first; use --no-build to publish the existing output',
+    },
+});
+exports.getPublishOptions = getPublishOptions;
+/** Shared options plus `--dry-run`: checkout and its compatibility aliases use these. */
+const getCheckoutOptions = (yargs) => (0, exports.getSharedOptions)(yargs).options({
+    'dry-run': {
+        type: 'boolean',
+        description: 'Report what would be written without changing any workspace file',
+    },
+});
+exports.getCheckoutOptions = getCheckoutOptions;
+/**
+ * Positional `type` + variadic `id`, shared by publish, checkout, and their compatibility aliases.
+ * `choices` is always declared: yargs allows an omitted optional positional while still rejecting an
+ * unrecognized one, so the deprecated commands get the same guard as the canonical ones.
+ */
+const withTargetPositionals = (yargs, verb) => yargs
+    .positional('type', {
+    describe: `The kind of content to ${verb}, or "all" for every kind`,
+    choices: exports.REGISTRY_TARGET_KINDS,
+    type: 'string',
+})
+    .positional('id', {
+    describe: `The stable id (component/pattern/page id, token set id, or asset collection); omit to ${verb} all of that kind`,
+    type: 'string',
+    array: true,
+});
+exports.withTargetPositionals = withTargetPositionals;
+/** Dispatch one `type` argument to the matching Handoff entry point. */
+const runTarget = (handoff, type, ids, verb) => {
+    if (type === 'all') {
+        return verb === 'publish' ? handoff.publishAll() : handoff.checkoutAll();
+    }
+    return verb === 'publish' ? handoff.publishKind(type, ids) : handoff.checkoutKind(type, ids);
+};
+exports.runTarget = runTarget;

package/dist/commands/validate/components.js

@@ -8,11 +8,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-const __1 = __importDefault(require("../../"));
 const utils_1 = require("../utils");
 const command = {
     command: 'validate:components',
@@ -27,7 +23,7 @@ const command = {
     },
     handler: (args) => __awaiter(void 0, void 0, void 0, function* () {
         var _a;
-        const handoff = new __1.default(args.debug, args.force);
+        const handoff = (0, utils_1.createHandoff)(args);
         yield handoff.validateComponents((_a = args.skipBuild) !== null && _a !== void 0 ? _a : false);
     }),
 };

package/dist/config/index.d.ts

@@ -1,6 +1,7 @@
 export { defaultConfig, getClientConfig } from './defaults';
 export type { ImageStyle } from './defaults';
-export { initConfig, initConfigWithMetadata } from './loader';
+export { HandoffConfigError, initConfig, initConfigWithMetadata } from './loader';
+export type { ConfigLoadContext } from './loader';
 export { defineConfig } from './helpers';
 export { initRuntimeConfig } from './runtime';
 export { validateConfig } from './validator';

package/dist/config/index.js

@@ -1,12 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.writeEntries = exports.isEntryCovered = exports.validateConfig = exports.initRuntimeConfig = exports.defineConfig = exports.initConfigWithMetadata = exports.initConfig = exports.getClientConfig = exports.defaultConfig = void 0;
+exports.writeEntries = exports.isEntryCovered = exports.validateConfig = exports.initRuntimeConfig = exports.defineConfig = exports.initConfigWithMetadata = exports.initConfig = exports.HandoffConfigError = exports.getClientConfig = exports.defaultConfig = void 0;
 // Config defaults and client config
 var defaults_1 = require("./defaults");
 Object.defineProperty(exports, "defaultConfig", { enumerable: true, get: function () { return defaults_1.defaultConfig; } });
 Object.defineProperty(exports, "getClientConfig", { enumerable: true, get: function () { return defaults_1.getClientConfig; } });
 // Config file loading
 var loader_1 = require("./loader");
+Object.defineProperty(exports, "HandoffConfigError", { enumerable: true, get: function () { return loader_1.HandoffConfigError; } });
 Object.defineProperty(exports, "initConfig", { enumerable: true, get: function () { return loader_1.initConfig; } });
 Object.defineProperty(exports, "initConfigWithMetadata", { enumerable: true, get: function () { return loader_1.initConfigWithMetadata; } });
 // Config helpers

package/dist/config/loader.d.ts

@@ -1,20 +1,33 @@
 import { Config } from '../types/config';
+/** Raised when an explicitly requested config file cannot be used. */
+export declare class HandoffConfigError extends Error {
+    constructor(message: string);
+}
 type ConfigLoadResult = {
     config: Config;
     configPath?: string;
 };
+/** Where to look for the config: the working directory, plus an optional explicit file. */
+export type ConfigLoadContext = {
+    /** Directory relative config paths resolve from, and the root that gets searched. */
+    workingPath?: string;
+    /** Explicit config file (the CLI's `-c, --config`), replacing discovery entirely. */
+    configPath?: string;
+};
 /**
- * Loads the handoff configuration from the project root and returns metadata.
+ * Loads the handoff configuration for the given working directory and returns metadata.
  */
-export declare const initConfigWithMetadata: (configOverride?: Partial<Config>) => ConfigLoadResult;
+export declare const initConfigWithMetadata: (configOverride?: Partial<Config>, context?: ConfigLoadContext) => ConfigLoadResult;
 /**
- * Loads the handoff configuration from the project root.
+ * Loads the handoff configuration for the given working directory.
  *
- * Searches for config files in order: handoff.config.ts, handoff.config.js, handoff.config.cjs, handoff.config.json.
- * Merges file config with any provided overrides, then applies defaults for missing values.
+ * Searches for config files in order: handoff.config.ts, handoff.config.js, handoff.config.cjs, handoff.config.json,
+ * unless `context.configPath` names one explicitly. Merges file config with any provided overrides,
+ * then applies defaults for missing values.
  *
  * @param configOverride - Optional partial config to override file-loaded values.
+ * @param context - Optional working directory and explicit config file to load.
  * @returns The fully resolved Config object.
  */
-export declare const initConfig: (configOverride?: Partial<Config>) => Config;
+export declare const initConfig: (configOverride?: Partial<Config>, context?: ConfigLoadContext) => Config;
 export {};

package/dist/config/loader.js

@@ -3,13 +3,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.initConfig = exports.initConfigWithMetadata = void 0;
+exports.initConfig = exports.initConfigWithMetadata = exports.HandoffConfigError = void 0;
 const esbuild_1 = __importDefault(require("esbuild"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const merge_1 = __importDefault(require("lodash/merge"));
 const module_1 = require("module");
 const path_1 = __importDefault(require("path"));
 const logger_1 = require("../utils/logger");
+const path_2 = require("../utils/path");
 const defaults_1 = require("./defaults");
 const CONFIG_FILE_PREFERENCE = [
     'handoff.config.ts',
@@ -17,6 +18,16 @@ const CONFIG_FILE_PREFERENCE = [
     'handoff.config.cjs',
     'handoff.config.json',
 ];
+/** Extensions the loader knows how to evaluate, derived from the discoverable file names. */
+const SUPPORTED_CONFIG_EXTENSIONS = Array.from(new Set(CONFIG_FILE_PREFERENCE.map((fileName) => path_1.default.extname(fileName))));
+/** Raised when an explicitly requested config file cannot be used. */
+class HandoffConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HandoffConfigError';
+    }
+}
+exports.HandoffConfigError = HandoffConfigError;
 const evaluateTypeScriptConfig = (filePath, handoffModulePath) => {
     var _a, _b;
     const buildResult = esbuild_1.default.buildSync({
@@ -49,11 +60,12 @@ const evaluateTypeScriptConfig = (filePath, handoffModulePath) => {
     return mod.exports;
 };
 const loadConfigFile = (configPath) => {
-    if (configPath.endsWith('.json')) {
+    const extension = path_1.default.extname(configPath);
+    if (extension === '.json') {
         const buffer = fs_extra_1.default.readFileSync(configPath);
         return JSON.parse(buffer.toString());
     }
-    if (configPath.endsWith('.ts')) {
+    if (extension === '.ts') {
         const handoffModulePath = path_1.default.resolve(__dirname, '../..');
         const importedConfig = evaluateTypeScriptConfig(configPath, handoffModulePath);
         return (importedConfig.default || importedConfig);
@@ -63,9 +75,24 @@ const loadConfigFile = (configPath) => {
     const importedConfig = require(configPath);
     return (importedConfig.default || importedConfig);
 };
-const resolveConfigFilePath = () => {
+/**
+ * Picks the config file to load. An explicitly requested file replaces discovery - it is resolved
+ * from `workingPath` and must exist in a format the loader can evaluate. Otherwise every known
+ * config name is looked for in `workingPath`, the first match winning.
+ */
+const resolveConfigFilePath = (workingPath, requestedPath) => {
+    if (requestedPath) {
+        const selected = path_1.default.resolve(workingPath, requestedPath);
+        if (!fs_extra_1.default.existsSync(selected)) {
+            throw new HandoffConfigError(`Config file not found: "${requestedPath}" (resolved to ${selected})`);
+        }
+        if (!SUPPORTED_CONFIG_EXTENSIONS.includes(path_1.default.extname(selected))) {
+            throw new HandoffConfigError(`Unsupported config file "${path_1.default.basename(selected)}". Supported extensions: ${SUPPORTED_CONFIG_EXTENSIONS.join(', ')}`);
+        }
+        return { selected, ignored: [] };
+    }
     const existing = CONFIG_FILE_PREFERENCE
-        .map((fileName) => path_1.default.resolve(process.cwd(), fileName))
+        .map((fileName) => path_1.default.resolve(workingPath, fileName))
         .filter((filePath) => fs_extra_1.default.existsSync(filePath));
     if (!existing.length) {
         return { selected: undefined, ignored: [] };
@@ -74,11 +101,12 @@ const resolveConfigFilePath = () => {
     return { selected, ignored };
 };
 /**
- * Loads the handoff configuration from the project root and returns metadata.
+ * Loads the handoff configuration for the given working directory and returns metadata.
  */
-const initConfigWithMetadata = (configOverride) => {
+const initConfigWithMetadata = (configOverride, context) => {
+    var _a;
     let config = {};
-    const { selected: configPath, ignored } = resolveConfigFilePath();
+    const { selected: configPath, ignored } = resolveConfigFilePath((_a = context === null || context === void 0 ? void 0 : context.workingPath) !== null && _a !== void 0 ? _a : (0, path_2.resolveWorkingPath)(), context === null || context === void 0 ? void 0 : context.configPath);
     if (ignored.length > 0 && configPath) {
         logger_1.Logger.warn(`Multiple config files found. Using "${path_1.default.basename(configPath)}" and ignoring: ${ignored
             .map((filePath) => `"${path_1.default.basename(filePath)}"`)
@@ -104,15 +132,17 @@ const initConfigWithMetadata = (configOverride) => {
 };
 exports.initConfigWithMetadata = initConfigWithMetadata;
 /**
- * Loads the handoff configuration from the project root.
+ * Loads the handoff configuration for the given working directory.
  *
- * Searches for config files in order: handoff.config.ts, handoff.config.js, handoff.config.cjs, handoff.config.json.
- * Merges file config with any provided overrides, then applies defaults for missing values.
+ * Searches for config files in order: handoff.config.ts, handoff.config.js, handoff.config.cjs, handoff.config.json,
+ * unless `context.configPath` names one explicitly. Merges file config with any provided overrides,
+ * then applies defaults for missing values.
  *
  * @param configOverride - Optional partial config to override file-loaded values.
+ * @param context - Optional working directory and explicit config file to load.
  * @returns The fully resolved Config object.
  */
-const initConfig = (configOverride) => {
-    return (0, exports.initConfigWithMetadata)(configOverride).config;
+const initConfig = (configOverride, context) => {
+    return (0, exports.initConfigWithMetadata)(configOverride, context).config;
 };
 exports.initConfig = initConfig;

package/dist/config/normalizers/page.d.ts

@@ -1,18 +1,18 @@
 import { PageListObject } from '../../transformers/preview/types';
 type RawPageFrontmatter = Record<string, any>;
 type NormalizePageOptions = {
-    /** The page id — its slug path (e.g. `guides/setup`), derived from the file location. */
+    /** The page id derived from its file location (`index` is reserved for the root home page). */
     id: string;
     /** Logical route the page is served at (e.g. `/guides/setup`). */
     routePath: string;
     /** Absolute filesystem path of the source `.md` (workspace-only, stripped on publish). */
-    sourcePath: string;
+    sourcePath?: string;
 };
 /**
  * Normalize a page's parsed markdown frontmatter into a {@link PageListObject}. Pages have no
  * required authored fields (a bare `.md` is valid); the title falls back to a humanized last slug
- * segment. The id is always the slug path (a page is addressed by its URL, so id ≡ route): the file
- * location is the single source of identity for both filesystem and registry serving.
+ * segment. The file location is the source of identity for filesystem and registry serving. Normal
+ * page ids match their routes; the reserved `index` id is served at `/`.
  */
 export declare const normalizePageDeclaration: (raw: RawPageFrontmatter, options: NormalizePageOptions) => PageListObject;
 export {};

package/dist/config/normalizers/page.js

@@ -9,8 +9,8 @@ const humanize = (segment) => segment
 /**
  * Normalize a page's parsed markdown frontmatter into a {@link PageListObject}. Pages have no
  * required authored fields (a bare `.md` is valid); the title falls back to a humanized last slug
- * segment. The id is always the slug path (a page is addressed by its URL, so id ≡ route): the file
- * location is the single source of identity for both filesystem and registry serving.
+ * segment. The file location is the source of identity for filesystem and registry serving. Normal
+ * page ids match their routes; the reserved `index` id is served at `/`.
  */
 const normalizePageDeclaration = (raw, options) => {
     var _a;

package/dist/config/runtime.js

@@ -6,12 +6,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.toLowerCaseKeysAndValues = exports.getItemsForPath = exports.getComponentsForPath = exports.isComponentDirectory = exports.initRuntimeConfig = exports.resolveComponentDeclaration = void 0;
 const esbuild_1 = __importDefault(require("esbuild"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
-const gray_matter_1 = __importDefault(require("gray-matter"));
 const module_1 = require("module");
 const path_1 = __importDefault(require("path"));
+const content_kinds_1 = require("../registry/content-kinds");
 const csf_1 = require("../transformers/utils/csf");
 const module_2 = require("../transformers/utils/module");
 const logger_1 = require("../utils/logger");
+const markdown_1 = require("../utils/markdown");
+const pages_1 = require("../utils/pages");
 const path_2 = require("../utils/path");
 const declaration_1 = require("./normalizers/declaration");
 const page_1 = require("./normalizers/page");
@@ -240,15 +242,16 @@ const initRuntimeConfig = (handoff) => {
     // Discover markdown pages
     // -------------------------------------------------------------------------
     // Working pages under `<workingPath>/pages/` are first-class registry entities (publish/checkout).
-    // Discovery mirrors the catch-all/static-path walk: every `.md` except `index.md` becomes a page
-    // keyed by its slug path. Package `config/docs` defaults are NOT entities (they ship with the tool).
+    // The root `index.md` uses the stable id `index` but is served at `/`; nested index files remain
+    // excluded because section indexes are owned by dedicated routes. Package defaults are not entities.
     const pagesRoot = path_1.default.resolve(handoff.workingPath, 'pages');
-    for (const segments of collectPageMarkdownPaths(pagesRoot)) {
+    for (const segments of (0, pages_1.collectPageSlugSegments)(pagesRoot, { includeRootIndex: true })) {
         const slug = segments.join('/');
         const sourcePath = path_1.default.resolve(pagesRoot, `${slug}.md`);
         try {
-            const { data: frontmatter } = (0, gray_matter_1.default)(fs_extra_1.default.readFileSync(sourcePath, 'utf-8'));
-            const page = (0, page_1.normalizePageDeclaration)(frontmatter, { id: slug, routePath: `/${slug}`, sourcePath });
+            const { data: frontmatter } = (0, markdown_1.parseMarkdown)(fs_extra_1.default.readFileSync(sourcePath, 'utf-8'));
+            const routePath = slug === content_kinds_1.HOME_PAGE_ID ? content_kinds_1.HOME_PAGE_PATH : `/${slug}`;
+            const page = (0, page_1.normalizePageDeclaration)(frontmatter, { id: slug, routePath, sourcePath });
             result.entries.pages[page.id] = page;
         }
         catch (err) {
@@ -263,25 +266,6 @@ const initRuntimeConfig = (handoff) => {
     return [result, Array.from(configFiles), configFileIndex];
 };
 exports.initRuntimeConfig = initRuntimeConfig;
-/**
- * Recursively collect `.md` files under a root, returning slug segments (relative path without the
- * `.md`). `index.md` is excluded — section index content is served by dedicated/home routes.
- */
-const collectPageMarkdownPaths = (rootDir, relativeParts = []) => {
-    if (!fs_extra_1.default.existsSync(rootDir))
-        return [];
-    const results = [];
-    for (const entry of fs_extra_1.default.readdirSync(rootDir)) {
-        const fullPath = path_1.default.join(rootDir, entry);
-        if (fs_extra_1.default.lstatSync(fullPath).isDirectory()) {
-            results.push(...collectPageMarkdownPaths(fullPath, [...relativeParts, entry]));
-        }
-        else if (entry.endsWith('.md') && entry !== 'index.md') {
-            results.push([...relativeParts, entry.replace(/\.md$/, '')]);
-        }
-    }
-    return results;
-};
 /**
  * True when `searchPath` is itself a single component directory: it holds a declaration file named
  * after the directory (`{dirname}.handoff.*`, or a legacy `{dirname}.{json,js,cjs}`). This is what

package/dist/index.d.ts

@@ -1,12 +1,41 @@
 import 'dotenv/config';
 import { Types as CoreTypes, Handoff as HandoffRunner } from 'handoff-core';
 import { type BuildPackage, type BuildTarget } from './app-builder';
+import { type RegistryEntityKind } from './registry/content-kinds';
+import type { TransferEntityKind } from './registry/transfer';
 import { type HandoffStore } from './store';
 import { Config, ConfigFileEntry, RuntimeConfig } from './types/config';
+/** How a {@link Handoff} instance is set up. */
+export interface HandoffOptions {
+    debug?: boolean;
+    force?: boolean;
+    /**
+     * Report what would happen instead of doing it: publish uploads nothing and needs no registry URL
+     * or token, and checkout writes no workspace file. A publish dry run still runs the build, so build
+     * output on disk is refreshed; pair it with `skipBuild` to leave that alone too.
+     */
+    dryRun?: boolean;
+    /** Publish from the existing build output instead of running a fresh build. */
+    skipBuild?: boolean;
+    /** Partial config merged over the loaded config file. */
+    config?: Partial<Config>;
+    /** Explicit config file (the CLI's `-c, --config`), resolved from the working path. */
+    configPath?: string;
+}
+/**
+ * A content kind to act on, optionally narrowed to specific ids. The plain form is the common case
+ * (`'components'`); the object form publishes or checks out only part of a kind.
+ */
+export type ContentTarget = RegistryEntityKind | {
+    kind: RegistryEntityKind;
+    ids?: string[];
+};
 declare class Handoff {
     config: Config | null;
     debug: boolean;
     force: boolean;
+    dryRun: boolean;
+    skipBuild: boolean;
     modulePath: string;
     workingPath: string;
     exportsDirectory: string;
@@ -23,13 +52,13 @@ declare class Handoff {
      * and assets. It is created lazily and reads live from `runtimeConfig`.
      */
     get store(): HandoffStore;
-    private _initialArgs;
+    private _options;
     private _configFilePaths;
     private _configFileIndex;
     private _mainConfigFilePath?;
     private _documentationObjectCache?;
     private _handoffRunner?;
-    constructor(debug?: boolean, force?: boolean, config?: Partial<Config>);
+    constructor(options?: HandoffOptions);
     private construct;
     init(configOverride?: Partial<Config>): Handoff;
     reload(): Handoff;
@@ -46,50 +75,68 @@ declare class Handoff {
     dbMigrate(): Promise<Handoff>;
     /**
      * 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.
+     * registry. With a single `id` it publishes that one entity after a targeted build; with a list of
+     * ids, or none, it builds the kind once and publishes the selected (or 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: TransferEntityKind, id?: string | string[]): Promise<Handoff>;
     /**
      * 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.
+     * With a single `id` it checks out that one entity; with a list of ids, or none, it checks out the
+     * selected (or 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: TransferEntityKind, id?: string | 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
      * each changed set (its extracted record + generated artifacts). Publishes every set when `setId` is
-     * omitted, or only the named set (`foundation/colors`, `component/<id>`). Loaded lazily so the
+     * omitted, or only the named set(s) (`foundation/colors`, `component/<id>`). Loaded lazily so the
      * registry client/build code never enters the docs app bundle.
      */
-    publishTokens(setId?: string): Promise<Handoff>;
+    publishTokens(setId?: string | string[]): Promise<Handoff>;
     /**
      * Checkout design token sets from the connected remote registry into this workspace: reconstruct
      * the canonical local `tokens.json` and restore the generated token files to their configured output
-     * paths. Checks out every published set when `setId` is omitted, or only the named set. Loaded lazily
-     * so the registry client never enters the docs app bundle.
+     * paths. Checks out every published set when `setId` is omitted, or only the named set(s). Loaded
+     * lazily so the registry client never enters the docs app bundle.
      */
-    checkoutTokens(setId?: string): Promise<Handoff>;
+    checkoutTokens(setId?: string | string[]): Promise<Handoff>;
     /**
      * Publish asset collections (icons/logos/fonts) from this connected workspace to the configured
      * remote registry. Runs a fresh build (Figma extract + asset generation), discovers the collections,
      * uploads only content hashes the registry lacks, and finalizes each collection manifest atomically.
-     * Publishes every collection when `collection` is omitted, or only the named one. Loaded lazily so
+     * Publishes every collection when `collection` is omitted, or only the named one(s). Loaded lazily so
      * the registry client/build code never enters the docs app bundle.
      */
-    publishAssets(collection?: string): Promise<Handoff>;
+    publishAssets(collection?: string | string[]): Promise<Handoff>;
     /**
      * Checkout asset collections from the connected remote registry into this workspace: recreate the
      * standard workspace asset files, collection JSON, icon sprite/manifest, and downloadable archives.
-     * Checks out every published collection when `collection` is omitted, or only the named one. Loaded
-     * lazily so the registry client never enters the docs app bundle.
+     * Checks out every published collection when `collection` is omitted, or only the named one(s).
+     * Loaded lazily so the registry client never enters the docs app bundle.
+     */
+    checkoutAssets(collection?: string | string[]): Promise<Handoff>;
+    /**
+     * Publish one content kind named by its plural form (`components`, `tokens`, …). The entry point for
+     * callers working in the plural vocabulary, so the plural-to-transfer-path mapping lives in one
+     * place.
+     */
+    publishKind(kind: RegistryEntityKind, id?: string | string[]): Promise<Handoff>;
+    /** Checkout one content kind named by its plural form. Mirrors {@link publishKind}. */
+    checkoutKind(kind: RegistryEntityKind, id?: string | string[]): Promise<Handoff>;
+    /**
+     * Publish every content kind, or the given subset of kinds and ids, in dependency order: tokens and
+     * assets first (rendered component artifacts reference the CSS variables and asset URLs they
+     * produce), then components, patterns and pages. A failing kind is reported and never aborts the
+     * rest; the run throws at the end if any kind failed.
      */
-    checkoutAssets(collection?: string): Promise<Handoff>;
+    publishAll(targets?: readonly ContentTarget[]): Promise<Handoff>;
+    /** Checkout every content kind, or the given subset, in the same order. Mirrors {@link publishAll}. */
+    checkoutAll(targets?: readonly ContentTarget[]): Promise<Handoff>;
     ejectConfig(): Promise<Handoff>;
     ejectPages(): Promise<Handoff>;
     ejectTheme(): Promise<Handoff>;