handoff-app 2.0.0-5 → 2.0.0-7

package/dist/cli/scaffold.js

@@ -40,7 +40,7 @@ const p = __importStar(require("@clack/prompts"));
 const chalk_1 = __importDefault(require("chalk"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
-const entries_1 = require("../config/entries");
+const catalog_include_1 = require("../config/catalog-include");
 // Constants
 const COMPONENTS_DIR = 'components';
 const DEFAULT_GROUPS = [
@@ -63,49 +63,41 @@ const toTitleCase = (str) => {
  * Generate the component JS stub content
  */
 const generateComponentStub = (config) => {
+    // `implementation` names the source, so `entries` carries only supporting files.
     const entriesLines = [];
-    if (config.generateTsx) {
-        entriesLines.push(`    component: './${config.name}.tsx',`);
-    }
-    else {
-        entriesLines.push(`    template: './${config.name}.hbs',`);
-    }
     if (config.generateScss) {
         entriesLines.push(`    scss: './${config.name}.scss',`);
     }
+    const entriesBlock = entriesLines.length ? `\n  entries: {\n${entriesLines.join('\n')}\n  },` : '';
     const commonMetadata = `  id: "${config.name}",
   name: "${config.title}",
   description: "${config.description}",
   group: "${config.group}",
   type: "element",
   figmaComponentId: "${config.name}",`;
+    const previewExport = `
+exports.Default = {
+  args: {},
+};
+`;
     if (config.generateTsx) {
-        return `const { defineReactComponent } = require('handoff-app');
-const ${toTitleCase(config.name).replace(/\s/g, '')} = require('./${config.name}').default;
+        const identifier = toTitleCase(config.name).replace(/\s/g, '');
+        return `const { defineCatalogItem } = require('handoff-app/react');
+const ${identifier} = require('./${config.name}').default;
 
-module.exports = defineReactComponent(${toTitleCase(config.name).replace(/\s/g, '')}, {
+exports.default = defineCatalogItem({
 ${commonMetadata}
-  entries: {
-${entriesLines.join('\n')}
-  },
-  previews: {
-    default: { title: "Default", args: {} }
-  }
+  implementation: ${identifier},${entriesBlock}
 });
-`;
+${previewExport}`;
     }
-    return `const { defineHandlebarsComponent } = require('handoff-app');
+    return `const { defineCatalogItem } = require('handoff-app/handlebars');
 
-module.exports = defineHandlebarsComponent({
+exports.default = defineCatalogItem({
 ${commonMetadata}
-  entries: {
-${entriesLines.join('\n')}
-  },
-  previews: {
-    default: { title: "Default", args: {} }
-  }
+  implementation: './${config.name}.hbs',${entriesBlock}
 });
-`;
+${previewExport}`;
 };
 /**
  * Generate a basic React component stub with variant props
@@ -179,8 +171,8 @@ const getFigmaComponents = (handoff) => __awaiter(void 0, void 0, void 0, functi
  * Get list of registered component IDs from runtime config
  */
 const getRegisteredComponentIds = (handoff) => {
-    var _a, _b;
-    const components = ((_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components) || {};
+    var _a;
+    const components = ((_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.components) || {};
     return Object.keys(components);
 };
 /**
@@ -385,22 +377,22 @@ const runScaffold = (handoff) => __awaiter(void 0, void 0, void 0, function* ()
         console.log(chalk_1.default.dim(`  ${relativePath}`));
     }
     // Update config if requested. Components already covered by a collection directory auto-load,
-    // so we only write the uncovered ones into entries.components.
+    // so we only write the unlisted ones into catalog.include.
     if (updateConfig) {
         const componentDirs = componentNames.map((name) => path_1.default.resolve(handoff.workingPath, COMPONENTS_DIR, name));
-        const uncovered = componentDirs.filter((dir) => !(0, entries_1.isEntryCovered)(handoff, 'components', dir));
-        if (uncovered.length === 0) {
+        const unlisted = componentDirs.filter((dir) => !(0, catalog_include_1.isIncluded)(handoff, dir));
+        if (unlisted.length === 0) {
             p.log.info(`Config already covers these components - they'll auto-load`);
         }
         else {
-            const result = yield (0, entries_1.writeEntries)(handoff, 'components', uncovered);
+            const result = yield (0, catalog_include_1.addToCatalog)(handoff, unlisted);
             if (result.status === 'added') {
                 const configFileName = result.configPath ? path_1.default.basename(result.configPath) : 'handoff.config.json';
                 p.log.success(`Updated ${configFileName} with component paths`);
             }
             else {
                 const where = result.configPath ? path_1.default.relative(handoff.workingPath, result.configPath) : 'handoff.config';
-                p.log.warn(`Could not automatically update ${where}. Please manually add these paths to entries.components:`);
+                p.log.warn(`Could not automatically update ${where}. Please manually add these paths to catalog.include:`);
                 for (const rel of result.pending) {
                     console.log(chalk_1.default.yellow(`  '${rel}'`));
                 }

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

@@ -6,10 +6,13 @@ export interface CheckoutArgs extends SharedArgs {
     id?: string[];
 }
 /**
- * `handoff-app checkout <components|patterns|pages> [id...]` pulls entities from the connected
- * registry into this workspace, writing their source files in standard authoring form and
- * synthesizing local declarations. Pass ids to pull only those entities, or omit them for every
- * published entity of that kind.
+ * `handoff-app checkout <catalog|pages> [id...]` pulls entities from the connected registry into this
+ * workspace, writing their source files in standard authoring form and synthesizing local
+ * declarations. Pass ids to pull only those entities, or omit them for every published entity of that
+ * kind.
+ *
+ * `catalog` covers every published catalog item. The lane an item was published into is looked up in
+ * the registry, so an id is enough and no lane is named here.
  *
  * `handoff-app checkout tokens [setId...]` pulls every published token set, or only the named ones,
  * reconstructing `tokens.json` and restoring the generated token files.

package/dist/commands/checkout/index.js

@@ -2,10 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const utils_1 = require("../utils");
 /**
- * `handoff-app checkout <components|patterns|pages> [id...]` pulls entities from the connected
- * registry into this workspace, writing their source files in standard authoring form and
- * synthesizing local declarations. Pass ids to pull only those entities, or omit them for every
- * published entity of that kind.
+ * `handoff-app checkout <catalog|pages> [id...]` pulls entities from the connected registry into this
+ * workspace, writing their source files in standard authoring form and synthesizing local
+ * declarations. Pass ids to pull only those entities, or omit them for every published entity of that
+ * kind.
+ *
+ * `catalog` covers every published catalog item. The lane an item was published into is looked up in
+ * the registry, so an id is enough and no lane is named here.
  *
  * `handoff-app checkout tokens [setId...]` pulls every published token set, or only the named ones,
  * reconstructing `tokens.json` and restoring the generated token files.
@@ -21,8 +24,8 @@ const utils_1 = require("../utils");
  */
 const command = {
     command: 'checkout <type> [id..]',
-    describe: 'Pull components, patterns, pages, design tokens, or assets from the connected registry into this workspace',
-    builder: (yargs) => (0, utils_1.withTargetPositionals)((0, utils_1.getCheckoutOptions)(yargs), 'checkout'),
+    describe: 'Pull catalog items, pages, design tokens, or assets from the connected registry into this workspace',
+    builder: (yargs) => (0, utils_1.withTargetPositionals)((0, utils_1.getCheckoutOptions)(yargs), 'checkout', utils_1.REGISTRY_TARGET_KINDS),
     handler: (args) => (0, utils_1.runRegistryCommand)(args, (handoff) => (0, utils_1.runTarget)(handoff, args.type, args.id, 'checkout')),
 };
 exports.default = command;

package/dist/commands/compat/push-args.d.ts

@@ -7,11 +7,11 @@
  * {@link Handoff.publishAll}, so no orchestration lives here.
  */
 import { type RegistryEntityKind } from '../../registry/content-kinds';
-import type { RegistryTargetKind } from '../utils';
+import type { CompatTargetKind } from '../utils';
 import type { ContentTarget } from '../../index';
 /** The documented `push` / `pull` arguments read here. */
 export interface CompatTargetArgs {
-    type?: RegistryTargetKind;
+    type?: CompatTargetKind;
     id?: string[];
     components?: string[];
     patterns?: string[];

package/dist/commands/index.js

@@ -19,7 +19,6 @@ const login_1 = __importDefault(require("./login"));
 const logout_1 = __importDefault(require("./logout"));
 const component_1 = __importDefault(require("./make/component"));
 const page_1 = __importDefault(require("./make/page"));
-const template_1 = __importDefault(require("./make/template"));
 const pull_1 = __importDefault(require("./pull"));
 const publish_1 = __importDefault(require("./publish"));
 const push_1 = require("./push");
@@ -42,7 +41,6 @@ exports.commands = [
     logout_1.default,
     page_1.default,
     component_1.default,
-    template_1.default,
     publish_1.default,
     pull_1.default,
     ...push_1.pushCommands,

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

@@ -6,10 +6,13 @@ export interface PublishArgs extends SharedArgs {
     id?: string[];
 }
 /**
- * `handoff-app publish <components|patterns|pages> [id...]` runs a fresh local build and uploads to
- * the connected registry. Pass ids to build and upload only those entities, or omit them to build the
- * kind once and upload every declared entity, skipping any whose content already matches the registry
- * (`--force` re-uploads everything).
+ * `handoff-app publish <catalog|pages> [id...]` runs a fresh local build and uploads to the connected
+ * registry. Pass ids to build and upload only those entities, or omit them to build the kind once and
+ * upload every declared entity, skipping any whose content already matches the registry (`--force`
+ * re-uploads everything).
+ *
+ * `catalog` covers every declared catalog item. Whether an item is stored as a component or as a
+ * pattern follows from its declaration, so an id is enough and no lane is named here.
  *
  * `handoff-app publish tokens [setId...]` does a fresh token build and uploads every logical token
  * set, or only the named ones (`foundation/colors`, `component/button`).
@@ -17,8 +20,8 @@ export interface PublishArgs extends SharedArgs {
  * `handoff-app publish assets [collection...]` runs a fresh build and uploads every asset collection,
  * or only the named ones (`icons`, `logos`, `fonts`).
  *
- * `handoff-app publish all` runs every kind in dependency order: tokens, assets, components,
- * patterns, then pages.
+ * `handoff-app publish all` runs every kind in dependency order: tokens, assets, catalog items, then
+ * pages.
  *
  * Available only from a connected workspace (`runtime.mode: workspace` + a configured
  * `registryConnection`), except under `--dry-run`, which reports what would be uploaded and needs no

package/dist/commands/publish/index.js

@@ -2,10 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const utils_1 = require("../utils");
 /**
- * `handoff-app publish <components|patterns|pages> [id...]` runs a fresh local build and uploads to
- * the connected registry. Pass ids to build and upload only those entities, or omit them to build the
- * kind once and upload every declared entity, skipping any whose content already matches the registry
- * (`--force` re-uploads everything).
+ * `handoff-app publish <catalog|pages> [id...]` runs a fresh local build and uploads to the connected
+ * registry. Pass ids to build and upload only those entities, or omit them to build the kind once and
+ * upload every declared entity, skipping any whose content already matches the registry (`--force`
+ * re-uploads everything).
+ *
+ * `catalog` covers every declared catalog item. Whether an item is stored as a component or as a
+ * pattern follows from its declaration, so an id is enough and no lane is named here.
  *
  * `handoff-app publish tokens [setId...]` does a fresh token build and uploads every logical token
  * set, or only the named ones (`foundation/colors`, `component/button`).
@@ -13,8 +16,8 @@ const utils_1 = require("../utils");
  * `handoff-app publish assets [collection...]` runs a fresh build and uploads every asset collection,
  * or only the named ones (`icons`, `logos`, `fonts`).
  *
- * `handoff-app publish all` runs every kind in dependency order: tokens, assets, components,
- * patterns, then pages.
+ * `handoff-app publish all` runs every kind in dependency order: tokens, assets, catalog items, then
+ * pages.
  *
  * Available only from a connected workspace (`runtime.mode: workspace` + a configured
  * `registryConnection`), except under `--dry-run`, which reports what would be uploaded and needs no
@@ -22,8 +25,8 @@ const utils_1 = require("../utils");
  */
 const command = {
     command: 'publish <type> [id..]',
-    describe: 'Build and publish components, patterns, pages, design tokens, or assets to the connected registry',
-    builder: (yargs) => (0, utils_1.withTargetPositionals)((0, utils_1.getPublishOptions)(yargs), 'publish'),
+    describe: 'Build and publish catalog items, pages, design tokens, or assets to the connected registry',
+    builder: (yargs) => (0, utils_1.withTargetPositionals)((0, utils_1.getPublishOptions)(yargs), 'publish', utils_1.REGISTRY_TARGET_KINDS),
     handler: (args) => (0, utils_1.runRegistryCommand)(args, (handoff) => (0, utils_1.runTarget)(handoff, args.type, args.id, 'publish')),
 };
 exports.default = command;

package/dist/commands/pull/index.js

@@ -7,7 +7,7 @@ const pull = {
     command: 'pull [type] [id..]',
     describe: 'Deprecated alias for checkout',
     deprecated: true,
-    builder: (yargs) => (0, utils_1.withTargetPositionals)((0, utils_1.getCheckoutOptions)(yargs), 'checkout').options({
+    builder: (yargs) => (0, utils_1.withTargetPositionals)((0, utils_1.getCheckoutOptions)(yargs), 'checkout', utils_1.COMPAT_TARGET_KINDS).options({
         components: { type: 'array', string: true, description: 'Checkout only these component ids' },
         patterns: { type: 'array', string: true, description: 'Checkout only these pattern ids' },
         pages: { type: 'array', string: true, description: 'Checkout only these page slugs' },

package/dist/commands/push/index.js

@@ -9,7 +9,7 @@ const push = {
     command: 'push [type] [id..]',
     describe: 'Deprecated alias for publish',
     deprecated: true,
-    builder: (yargs) => (0, utils_1.withTargetPositionals)((0, utils_1.getPublishOptions)(yargs), 'publish').options(Object.assign({ components: { type: 'array', string: true, description: 'Publish only these component ids' }, patterns: { type: 'array', string: true, description: 'Publish only these pattern ids' }, pages: { type: 'array', string: true, description: 'Publish only these page slugs' } }, (0, deprecations_1.hiddenOptions)(deprecations_1.UNSUPPORTED_PUSH_OPTIONS))),
+    builder: (yargs) => (0, utils_1.withTargetPositionals)((0, utils_1.getPublishOptions)(yargs), 'publish', utils_1.COMPAT_TARGET_KINDS).options(Object.assign({ components: { type: 'array', string: true, description: 'Publish only these component ids' }, patterns: { type: 'array', string: true, description: 'Publish only these pattern ids' }, pages: { type: 'array', string: true, description: 'Publish only these page slugs' } }, (0, deprecations_1.hiddenOptions)(deprecations_1.UNSUPPORTED_PUSH_OPTIONS))),
     handler: (args) => (0, utils_1.runRegistryCommand)(args, (handoff) => {
         (0, deprecations_1.warnDeprecatedCommand)('push', 'publish');
         (0, deprecations_1.warnUnsupportedOptions)(args, deprecations_1.UNSUPPORTED_PUSH_OPTIONS);

package/dist/commands/utils.d.ts

@@ -1,9 +1,20 @@
 import { Argv } from 'yargs';
 import Handoff from '../';
 import { SharedArgs } from './types';
-/** The `type` argument accepted by publish/checkout: any content kind, or `all` for every kind. */
-export declare const REGISTRY_TARGET_KINDS: readonly ["components", "patterns", "pages", "tokens", "assets", "all"];
+/**
+ * The `type` argument accepted by publish and checkout, or `all` for every kind. `catalog` covers
+ * every catalog item. An item's lane comes from its declaration, so the command line names items and
+ * never a lane.
+ */
+export declare const REGISTRY_TARGET_KINDS: readonly ["catalog", "pages", "tokens", "assets", "all"];
 export type RegistryTargetKind = (typeof REGISTRY_TARGET_KINDS)[number];
+/**
+ * The `type` argument accepted by the deprecated `push` / `pull` aliases: the plural content kinds the
+ * published docs name. This list keeps `components` and `patterns`, which the canonical commands do
+ * not take, and omits `catalog`, which the docs do not describe.
+ */
+export declare const COMPAT_TARGET_KINDS: readonly ["components", "patterns", "pages", "tokens", "assets", "all"];
+export type CompatTargetKind = (typeof COMPAT_TARGET_KINDS)[number];
 export declare const createHandoff: (args: SharedArgs) => Handoff;
 /**
  * Run a registry command against a fresh Handoff. Registry failures are the user's to act on, so they
@@ -83,8 +94,8 @@ export declare const getCheckoutOptions: (yargs: Argv) => Argv<import("yargs").O
  * `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.
  */
-export declare const withTargetPositionals: (yargs: Argv, verb: "publish" | "checkout") => Argv<{
-    type: "pages" | "components" | "patterns" | "assets" | "tokens" | "all";
+export declare const withTargetPositionals: <TKind extends string>(yargs: Argv, verb: "publish" | "checkout", choices: readonly TKind[]) => Argv<{
+    type: (unknown extends TKind ? true : false) extends false ? TKind : unknown;
 } & {
     id: string[];
 }>;

package/dist/commands/utils.js

@@ -12,12 +12,22 @@ 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;
+exports.runTarget = exports.withTargetPositionals = exports.getCheckoutOptions = exports.getPublishOptions = exports.getSharedOptions = exports.runRegistryCommand = exports.createHandoff = exports.COMPAT_TARGET_KINDS = 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'];
+/**
+ * The `type` argument accepted by publish and checkout, or `all` for every kind. `catalog` covers
+ * every catalog item. An item's lane comes from its declaration, so the command line names items and
+ * never a lane.
+ */
+exports.REGISTRY_TARGET_KINDS = ['catalog', 'pages', 'tokens', 'assets', 'all'];
+/**
+ * The `type` argument accepted by the deprecated `push` / `pull` aliases: the plural content kinds the
+ * published docs name. This list keeps `components` and `patterns`, which the canonical commands do
+ * not take, and omits `catalog`, which the docs do not describe.
+ */
+exports.COMPAT_TARGET_KINDS = [...content_kinds_1.REGISTRY_ENTITY_KINDS, 'all'];
 const createHandoff = (args) => new __1.default({
     debug: args.debug,
     force: args.force,
@@ -88,14 +98,14 @@ exports.getCheckoutOptions = getCheckoutOptions;
  * `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
+const withTargetPositionals = (yargs, verb, choices) => yargs
     .positional('type', {
     describe: `The kind of content to ${verb}, or "all" for every kind`,
-    choices: exports.REGISTRY_TARGET_KINDS,
+    choices,
     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`,
+    describe: `The stable id (catalog item id, page id, token set id, or asset collection); omit to ${verb} all of that kind`,
     type: 'string',
     array: true,
 });
@@ -105,6 +115,9 @@ const runTarget = (handoff, type, ids, verb) => {
     if (type === 'all') {
         return verb === 'publish' ? handoff.publishAll() : handoff.checkoutAll();
     }
+    if (type === 'catalog') {
+        return verb === 'publish' ? handoff.publishCatalog(ids) : handoff.checkoutCatalog(ids);
+    }
     return verb === 'publish' ? handoff.publishKind(type, ids) : handoff.checkoutKind(type, ids);
 };
 exports.runTarget = runTarget;

package/dist/config/catalog-include.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Registering catalog directories in the handoff config. Both scaffolding new item stubs and
+ * checking entities out of a registry need a freshly-written entity to be discoverable by the
+ * workspace build, so both have to handle every way a path can be declared:
+ *
+ * - a collection directory (e.g. `"components"`) whose subdirectories are entities: a new sibling
+ *   is auto-discovered at runtime, so nothing needs writing to the config;
+ * - an individual entity directory (e.g. `"components/button"`): the entity stays invisible until
+ *   its own path is added to the list.
+ *
+ * A workspace registers items under `catalog.include`. Discovery expands collection directories;
+ * the writer appends unlisted paths in JSON, TypeScript, JavaScript, and CommonJS project configs.
+ */
+import { Config } from '../types/config';
+/** Minimal handoff shape needed here; avoids importing the full Handoff class (circular dep). */
+interface ConfigContext {
+    config?: Config;
+    workingPath: string;
+}
+/** Outcome of {@link addToCatalog}: `added` on success, `unsupported` when the config couldn't be edited. */
+export interface AddToCatalogResult {
+    status: 'added' | 'unsupported';
+    /** The config file written (or that would need editing); null only when none exists and creation failed. */
+    configPath: string | null;
+    /** Workspace-relative POSIX paths written into the config. */
+    added: string[];
+    /** Workspace-relative POSIX paths the caller must add manually (`status: 'unsupported'`). */
+    pending: string[];
+}
+/**
+ * True when `targetDir` already loads through an existing declaration: listed directly, or sitting
+ * under a declared collection directory that runtime discovery expands. Reuses the same expansion
+ * the runtime uses, so every declaration style is covered.
+ */
+export declare const isIncluded: (handoff: ConfigContext, targetDir: string) => boolean;
+/**
+ * Add `targetDirs` to the config so the build discovers them. Callers should first drop
+ * already-loading dirs via {@link isIncluded}. Paths are stored workspace-relative; a `.json`
+ * config is edited losslessly, a code config best-effort. When no config file exists a minimal
+ * `handoff.config.json` is created.
+ */
+export declare const addToCatalog: (handoff: ConfigContext, targetDirs: string[]) => Promise<AddToCatalogResult>;
+export {};

package/dist/config/catalog-include.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * Registering catalog directories in the handoff config. Both scaffolding new item stubs and
+ * checking entities out of a registry need a freshly-written entity to be discoverable by the
+ * workspace build, so both have to handle every way a path can be declared:
+ *
+ * - a collection directory (e.g. `"components"`) whose subdirectories are entities: a new sibling
+ *   is auto-discovered at runtime, so nothing needs writing to the config;
+ * - an individual entity directory (e.g. `"components/button"`): the entity stays invisible until
+ *   its own path is added to the list.
+ *
+ * A workspace registers items under `catalog.include`. Discovery expands collection directories;
+ * the writer appends unlisted paths in JSON, TypeScript, JavaScript, and CommonJS project configs.
+ */
+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.addToCatalog = exports.isIncluded = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const path_2 = require("../utils/path");
+const runtime_1 = require("./runtime");
+/** Config files in precedence order; the first that exists is the one we mutate. */
+const CONFIG_FILES = ['handoff.config.ts', 'handoff.config.js', 'handoff.config.cjs', 'handoff.config.json'];
+/** Workspace-relative, POSIX-separated path, as stored in `catalog.include`. */
+const toIncludePath = (handoff, targetDir) => path_1.default.relative(handoff.workingPath, targetDir).split(path_1.default.sep).join('/');
+const includedPaths = (handoff) => { var _a, _b, _c; return (_c = (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.catalog) === null || _b === void 0 ? void 0 : _b.include) !== null && _c !== void 0 ? _c : []; };
+/**
+ * True when `targetDir` already loads through an existing declaration: listed directly, or sitting
+ * under a declared collection directory that runtime discovery expands. Reuses the same expansion
+ * the runtime uses, so every declaration style is covered.
+ */
+const isIncluded = (handoff, targetDir) => {
+    const configured = includedPaths(handoff);
+    if (!configured.length) {
+        return false;
+    }
+    return configured
+        .flatMap((included) => (0, runtime_1.getComponentsForPath)(path_1.default.resolve(handoff.workingPath, included)))
+        .some((dir) => (0, path_2.arePathsEqual)(dir, targetDir));
+};
+exports.isIncluded = isIncluded;
+/** Format the path list as source, matching the surrounding indentation of a code config. */
+const formatPathArray = (paths, indent) => {
+    if (paths.length === 0)
+        return '[]';
+    if (paths.length === 1)
+        return `['${paths[0]}']`;
+    return `[\n${paths.map((relPath) => `${indent}'${relPath}',`).join('\n')}\n${indent.slice(2)}]`;
+};
+/** Append paths to a structured `.json` config (lossless read/modify/write). */
+const addToJsonConfig = (configPath, relPaths) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    try {
+        const config = yield fs_extra_1.default.readJSON(configPath);
+        config.catalog = (_a = config.catalog) !== null && _a !== void 0 ? _a : {};
+        const parent = config.catalog;
+        const existing = Array.isArray(parent.include) ? parent.include : [];
+        const existingSet = new Set(existing);
+        for (const relPath of relPaths) {
+            if (!existingSet.has(relPath))
+                existing.push(relPath);
+        }
+        parent.include = existing;
+        yield fs_extra_1.default.writeJSON(configPath, config, { spaces: 2 });
+        return true;
+    }
+    catch (_b) {
+        return false;
+    }
+});
+/**
+ * Blanks out comment regions while keeping every index in place, so a match found here points at
+ * the same offset in the original source. A project config often carries a commented-out `catalog`
+ * example, and a plain search would rewrite that comment instead of the live code.
+ */
+const maskComments = (content) => content
+    .replace(/\/\*[\s\S]*?\*\//g, (comment) => ' '.repeat(comment.length))
+    .replace(/(^|[^:])\/\/[^\n]*/g, (comment, prefix) => prefix + ' '.repeat(comment.length - prefix.length));
+/** Index of the brace closing the one at `openIndex`, or -1. */
+const findMatchingBrace = (source, openIndex) => {
+    let depth = 0;
+    for (let i = openIndex; i < source.length; i += 1) {
+        if (source[i] === '{')
+            depth += 1;
+        if (source[i] === '}') {
+            depth -= 1;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+};
+/** Locates `parent: { key: [ ... ] }` in a code config, ignoring commented-out examples. */
+const locateList = (masked) => {
+    const parentMatch = new RegExp(`(^|[\\s{,;])catalog\\s*:\\s*\\{`, 'm').exec(masked);
+    if (!parentMatch)
+        return undefined;
+    const parentBrace = masked.indexOf('{', parentMatch.index + parentMatch[0].length - 1);
+    const parentClose = findMatchingBrace(masked, parentBrace);
+    if (parentClose < 0)
+        return { parentBrace };
+    const block = masked.slice(parentBrace, parentClose + 1);
+    const keyMatch = new RegExp(`(^|[\\s{,])include\\s*:\\s*\\[`).exec(block);
+    if (!keyMatch)
+        return { parentBrace };
+    const listStart = parentBrace + block.indexOf('[', keyMatch.index);
+    const listEnd = masked.indexOf(']', listStart);
+    if (listEnd < 0)
+        return { parentBrace };
+    return { parentBrace, listStart, listEnd };
+};
+/**
+ * Best-effort splice of paths into an executable `.ts` / `.js` / `.cjs` config. These are
+ * modules, not data, so there's no lossless structured write; if a computed or spread list can't be
+ * edited textually, the caller falls back to printing the paths for the user to add.
+ */
+const addToCodeConfig = (configPath, relPaths) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        const content = yield fs_extra_1.default.readFile(configPath, 'utf8');
+        const masked = maskComments(content);
+        const arrayBlock = formatPathArray(relPaths, '      ');
+        const location = locateList(masked);
+        // 1) The list already exists, so merge into it.
+        if ((location === null || location === void 0 ? void 0 : location.listStart) !== undefined && location.listEnd !== undefined) {
+            const existing = content
+                .slice(location.listStart + 1, location.listEnd)
+                .split(',')
+                .map((listed) => listed.trim().replace(/['"]/g, ''))
+                .filter(Boolean);
+            const existingSet = new Set(existing);
+            const toAdd = relPaths.filter((relPath) => !existingSet.has(relPath));
+            if (toAdd.length > 0) {
+                const indentMatch = /\[\s*\n(\s*)/.exec(content.slice(location.listStart));
+                const indent = indentMatch ? indentMatch[1] : '      ';
+                const merged = formatPathArray([...existing, ...toAdd], indent);
+                yield fs_extra_1.default.writeFile(configPath, content.slice(0, location.listStart) + merged + content.slice(location.listEnd + 1), 'utf8');
+            }
+            return true;
+        }
+        // 2) The parent object exists but not this key, so add the key.
+        if (location) {
+            const insertAt = location.parentBrace + 1;
+            yield fs_extra_1.default.writeFile(configPath, `${content.slice(0, insertAt)}\n    include: ${arrayBlock},${content.slice(insertAt)}`, 'utf8');
+            return true;
+        }
+        // 3) No parent object, so insert one into the exported config object.
+        const parentBlock = `  catalog: {\n    include: ${arrayBlock},\n  },\n`;
+        for (const anchor of [/module\.exports\s*=\s*\{/, /export\s+default\s+\{/, /defineConfig\s*\(\s*\{/]) {
+            const anchorMatch = anchor.exec(masked);
+            if (anchorMatch) {
+                const insertAt = anchorMatch.index + anchorMatch[0].length;
+                yield fs_extra_1.default.writeFile(configPath, `${content.slice(0, insertAt)}\n${parentBlock}${content.slice(insertAt)}`, 'utf8');
+                return true;
+            }
+        }
+        return false;
+    }
+    catch (_a) {
+        return false;
+    }
+});
+/**
+ * Add `targetDirs` to the config so the build discovers them. Callers should first drop
+ * already-loading dirs via {@link isIncluded}. Paths are stored workspace-relative; a `.json`
+ * config is edited losslessly, a code config best-effort. When no config file exists a minimal
+ * `handoff.config.json` is created.
+ */
+const addToCatalog = (handoff, targetDirs) => __awaiter(void 0, void 0, void 0, function* () {
+    const relPaths = [...new Set(targetDirs.map((dir) => toIncludePath(handoff, dir)))];
+    const configFile = CONFIG_FILES.find((file) => fs_extra_1.default.existsSync(path_1.default.resolve(handoff.workingPath, file)));
+    const configPath = configFile ? path_1.default.resolve(handoff.workingPath, configFile) : null;
+    if (relPaths.length === 0) {
+        return { status: 'added', configPath, added: [], pending: [] };
+    }
+    if (!configPath) {
+        const newConfigPath = path_1.default.resolve(handoff.workingPath, 'handoff.config.json');
+        try {
+            yield fs_extra_1.default.writeJSON(newConfigPath, { catalog: { include: relPaths } }, { spaces: 2 });
+            return { status: 'added', configPath: newConfigPath, added: relPaths, pending: [] };
+        }
+        catch (_a) {
+            return { status: 'unsupported', configPath: null, added: [], pending: relPaths };
+        }
+    }
+    const ok = configPath.endsWith('.json')
+        ? yield addToJsonConfig(configPath, relPaths)
+        : yield addToCodeConfig(configPath, relPaths);
+    return ok
+        ? { status: 'added', configPath, added: relPaths, pending: [] }
+        : { status: 'unsupported', configPath, added: [], pending: relPaths };
+});
+exports.addToCatalog = addToCatalog;

package/dist/config/defaults.d.ts

@@ -6,6 +6,8 @@ export interface ImageStyle {
     width: number;
     description: string;
 }
+/** Whether the MCP endpoint is served. On unless `runtime.mcp` is explicitly `false`. */
+export declare const isMcpEnabled: (config: Config | null | undefined) => boolean;
 export declare const defaultConfig: () => Config;
 /**
  * Retrieves the client configuration from the provided handoff configuration.