handoff-app 2.0.0-1 → 2.0.0-3

package/dist/commands/checkout/index.js

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

package/dist/commands/index.js

@@ -15,6 +15,8 @@ const pages_1 = __importDefault(require("./eject/pages"));
 const theme_1 = __importDefault(require("./eject/theme"));
 const fetch_1 = __importDefault(require("./fetch"));
 const init_1 = __importDefault(require("./init"));
+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"));
@@ -34,6 +36,8 @@ exports.commands = [
     theme_1.default,
     fetch_1.default,
     init_1.default,
+    login_1.default,
+    logout_1.default,
     page_1.default,
     component_1.default,
     template_1.default,

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

@@ -0,0 +1,8 @@
+import { CommandModule } from 'yargs';
+import { SharedArgs } from '../types';
+export interface LoginArgs extends SharedArgs {
+    url?: string;
+    browser?: boolean;
+}
+declare const command: CommandModule<{}, LoginArgs>;
+export default command;

package/dist/commands/login/index.js

@@ -0,0 +1,53 @@
+"use strict";
+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 });
+const __1 = __importDefault(require("../../"));
+const device_1 = require("../../cli/auth/device");
+const store_1 = require("../../cli/auth/store");
+const connection_1 = require("../../registry/connection");
+const logger_1 = require("../../utils/logger");
+const utils_1 = require("../utils");
+const command = {
+    command: 'login',
+    describe: 'Sign in to a registry using browser device authorization',
+    builder: (yargs) => (0, utils_1.getSharedOptions)(yargs)
+        .option('url', {
+        type: 'string',
+        describe: 'Registry URL, including its base path when configured',
+    })
+        .option('browser', {
+        type: 'boolean',
+        default: true,
+        describe: 'Open the approval URL in the default browser (disable with --no-browser)',
+    }),
+    handler: (args) => __awaiter(void 0, void 0, void 0, function* () {
+        var _a;
+        const handoff = new __1.default(args.debug, args.force);
+        try {
+            const configured = (0, connection_1.resolveRegistryConnection)(handoff.config);
+            const remoteUrl = ((_a = args.url) === null || _a === void 0 ? void 0 : _a.trim()) || configured.url;
+            if (!remoteUrl) {
+                throw new Error(`Pass --url <registry-url>, configure runtime.registryConnection.url, or set "${configured.urlEnv}".`);
+            }
+            yield (0, device_1.loginWithDevice)(handoff.workingPath, remoteUrl, { openBrowser: args.browser !== false });
+            logger_1.Logger.success(`Logged in. Credentials saved to ${(0, store_1.cliAuthFilePath)(handoff.workingPath)}.`);
+            logger_1.Logger.info('Publish and checkout commands will use this login for the matching registry URL.');
+        }
+        catch (error) {
+            logger_1.Logger.error(error instanceof Error ? error.message : String(error));
+            process.exitCode = 1;
+        }
+    }),
+};
+exports.default = command;

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

@@ -0,0 +1,7 @@
+import { CommandModule } from 'yargs';
+import { SharedArgs } from '../types';
+export interface LogoutArgs extends SharedArgs {
+    url?: string;
+}
+declare const command: CommandModule<{}, LogoutArgs>;
+export default command;

package/dist/commands/logout/index.js

@@ -0,0 +1,54 @@
+"use strict";
+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 });
+const __1 = __importDefault(require("../../"));
+const device_1 = require("../../cli/auth/device");
+const store_1 = require("../../cli/auth/store");
+const logger_1 = require("../../utils/logger");
+const utils_1 = require("../utils");
+const command = {
+    command: 'logout',
+    describe: 'Revoke and remove saved registry credentials',
+    builder: (yargs) => (0, utils_1.getSharedOptions)(yargs).option('url', {
+        type: 'string',
+        describe: 'Revoke credentials only when they belong to this exact registry URL',
+    }),
+    handler: (args) => __awaiter(void 0, void 0, void 0, function* () {
+        const handoff = new __1.default(args.debug, args.force);
+        const auth = yield (0, store_1.readCliAuth)(handoff.workingPath);
+        if (args.url && auth && !(0, store_1.cliAuthMatchesRegistry)(auth, args.url)) {
+            logger_1.Logger.error(`The saved login belongs to ${auth.remoteUrl}, not ${(0, store_1.normalizeRegistryUrl)(args.url)}. No credentials were changed.`);
+            process.exitCode = 1;
+            return;
+        }
+        if (auth) {
+            try {
+                yield (0, device_1.revokeAccessToken)(auth);
+            }
+            catch (error) {
+                logger_1.Logger.warn(`Could not revoke the registry token remotely (${error instanceof Error ? error.message : String(error)}). ` +
+                    'It will still be removed from this workspace.');
+            }
+        }
+        try {
+            yield (0, store_1.clearCliAuth)(handoff.workingPath);
+            logger_1.Logger.success(`Logged out. Removed ${(0, store_1.cliAuthFilePath)(handoff.workingPath)}.`);
+        }
+        catch (error) {
+            logger_1.Logger.error(`Could not remove saved credentials: ${error instanceof Error ? error.message : String(error)}`);
+            process.exitCode = 1;
+        }
+    }),
+};
+exports.default = command;

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

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

package/dist/commands/publish/index.js

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

package/dist/commands/utils.d.ts

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

package/dist/commands/utils.js

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

package/dist/config/entries.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Registering directory-list entries (`entries.components` / `entries.patterns`) in the handoff
+ * config. Both scaffolding new component 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.
+ *
+ * {@link isEntryCovered} answers "does this already load?" by reusing the runtime expansion
+ * ({@link getComponentsForPath}); {@link writeEntries} appends the paths that don't, across the
+ * `.json`, `.ts`, `.js`, and `.cjs` config formats.
+ */
+import { Config } from '../types/config';
+/** The `entries` keys whose values are declared as a list of directory paths. */
+export type EntryKind = 'components' | 'patterns';
+/** Minimal handoff shape needed here; avoids importing the full Handoff class (circular dep). */
+interface ConfigContext {
+    config?: Config;
+    workingPath: string;
+}
+/** Outcome of {@link writeEntries}: `added` on success, `unsupported` when the config couldn't be edited. */
+export interface WriteEntriesResult {
+    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 `entries[kind]` 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 isEntryCovered: (handoff: ConfigContext, kind: EntryKind, targetDir: string) => boolean;
+/**
+ * Add `targetDirs` to `entries[kind]` in the workspace config so the build discovers them. Callers
+ * should first drop already-loading dirs via {@link isEntryCovered}. 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 writeEntries: (handoff: ConfigContext, kind: EntryKind, targetDirs: string[]) => Promise<WriteEntriesResult>;
+export {};

package/dist/config/entries.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * Registering directory-list entries (`entries.components` / `entries.patterns`) in the handoff
+ * config. Both scaffolding new component 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.
+ *
+ * {@link isEntryCovered} answers "does this already load?" by reusing the runtime expansion
+ * ({@link getComponentsForPath}); {@link writeEntries} appends the paths that don't, across the
+ * `.json`, `.ts`, `.js`, and `.cjs` config formats.
+ */
+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.writeEntries = exports.isEntryCovered = 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 used as a config entry value. */
+const toEntryPath = (handoff, targetDir) => path_1.default.relative(handoff.workingPath, targetDir).split(path_1.default.sep).join('/');
+/**
+ * True when `targetDir` already loads through an existing `entries[kind]` 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 isEntryCovered = (handoff, kind, targetDir) => {
+    var _a, _b;
+    const configured = (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b[kind];
+    if (!(configured === null || configured === void 0 ? void 0 : configured.length)) {
+        return false;
+    }
+    return configured
+        .flatMap((entry) => (0, runtime_1.getComponentsForPath)(path_1.default.resolve(handoff.workingPath, entry)))
+        .some((dir) => (0, path_2.arePathsEqual)(dir, targetDir));
+};
+exports.isEntryCovered = isEntryCovered;
+/** Format an entry array as source, matching the surrounding indentation of a code config. */
+const formatEntryArray = (paths, indent) => {
+    if (paths.length === 0)
+        return '[]';
+    if (paths.length === 1)
+        return `['${paths[0]}']`;
+    return `[\n${paths.map((entry) => `${indent}'${entry}',`).join('\n')}\n${indent.slice(2)}]`;
+};
+/** Append entry paths to a structured `.json` config (lossless read/modify/write). */
+const addToJsonConfig = (configPath, kind, relPaths) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    try {
+        const config = yield fs_extra_1.default.readJSON(configPath);
+        config.entries = (_a = config.entries) !== null && _a !== void 0 ? _a : {};
+        const existing = Array.isArray(config.entries[kind]) ? config.entries[kind] : [];
+        const existingSet = new Set(existing);
+        for (const relPath of relPaths) {
+            if (!existingSet.has(relPath))
+                existing.push(relPath);
+        }
+        config.entries[kind] = existing;
+        yield fs_extra_1.default.writeJSON(configPath, config, { spaces: 2 });
+        return true;
+    }
+    catch (_b) {
+        return false;
+    }
+});
+/**
+ * Best-effort splice of entry 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 `entries`
+ * array can't be edited textually, the caller falls back to printing the paths for the user to add.
+ */
+const addToCodeConfig = (configPath, kind, relPaths) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        let content = yield fs_extra_1.default.readFile(configPath, 'utf8');
+        const arrayBlock = formatEntryArray(relPaths, '      ');
+        // 1) An `entries: { ... <kind>: [ ... ] }` array already exists, so merge into it.
+        const hasKeyArray = new RegExp(`entries\\s*:\\s*\\{[\\s\\S]*?${kind}\\s*:`).test(content);
+        const arrayRegex = new RegExp(`(${kind}\\s*:\\s*\\[)([^\\]]*)(\\])`);
+        const match = hasKeyArray ? content.match(arrayRegex) : null;
+        if (match) {
+            const existing = match[2]
+                .split(',')
+                .map((s) => s.trim().replace(/['"]/g, ''))
+                .filter(Boolean);
+            const existingSet = new Set(existing);
+            const toAdd = relPaths.filter((relPath) => !existingSet.has(relPath));
+            if (toAdd.length > 0) {
+                const indentMatch = content.match(new RegExp(`${kind}\\s*:\\s*\\[\\s*\\n(\\s*)`));
+                const indent = indentMatch ? indentMatch[1] : '      ';
+                content = content.replace(arrayRegex, `${kind}: ${formatEntryArray([...existing, ...toAdd], indent)}`);
+                yield fs_extra_1.default.writeFile(configPath, content, 'utf8');
+            }
+            return true;
+        }
+        // 2) An `entries` object exists but not this key, so add the key.
+        if (/entries\s*:\s*\{/.test(content)) {
+            content = content.replace(/(entries\s*:\s*\{)/, `$1\n    ${kind}: ${arrayBlock},`);
+            yield fs_extra_1.default.writeFile(configPath, content, 'utf8');
+            return true;
+        }
+        // 3) No `entries` object, so insert one into the exported config object.
+        const entriesBlock = `  entries: {\n    ${kind}: ${arrayBlock},\n  },\n`;
+        for (const anchor of [/module\.exports\s*=\s*\{/, /export\s+default\s+\{/, /defineConfig\s*\(\s*\{/]) {
+            if (anchor.test(content)) {
+                content = content.replace(anchor, (matched) => `${matched}\n${entriesBlock}`);
+                yield fs_extra_1.default.writeFile(configPath, content, 'utf8');
+                return true;
+            }
+        }
+        return false;
+    }
+    catch (_a) {
+        return false;
+    }
+});
+/**
+ * Add `targetDirs` to `entries[kind]` in the workspace config so the build discovers them. Callers
+ * should first drop already-loading dirs via {@link isEntryCovered}. 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 writeEntries = (handoff, kind, targetDirs) => __awaiter(void 0, void 0, void 0, function* () {
+    const relPaths = [...new Set(targetDirs.map((dir) => toEntryPath(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, { entries: { [kind]: 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, kind, relPaths)
+        : yield addToCodeConfig(configPath, kind, relPaths);
+    return ok
+        ? { status: 'added', configPath, added: relPaths, pending: [] }
+        : { status: 'unsupported', configPath, added: [], pending: relPaths };
+});
+exports.writeEntries = writeEntries;

package/dist/config/index.d.ts

@@ -4,3 +4,5 @@ export { initConfig, initConfigWithMetadata } from './loader';
 export { defineConfig } from './helpers';
 export { initRuntimeConfig } from './runtime';
 export { validateConfig } from './validator';
+export { isEntryCovered, writeEntries } from './entries';
+export type { EntryKind, WriteEntriesResult } from './entries';

package/dist/config/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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.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; } });
@@ -18,3 +18,7 @@ Object.defineProperty(exports, "initRuntimeConfig", { enumerable: true, get: fun
 // Config validation
 var validator_1 = require("./validator");
 Object.defineProperty(exports, "validateConfig", { enumerable: true, get: function () { return validator_1.validateConfig; } });
+// Registering directory-list entries (components/patterns)
+var entries_1 = require("./entries");
+Object.defineProperty(exports, "isEntryCovered", { enumerable: true, get: function () { return entries_1.isEntryCovered; } });
+Object.defineProperty(exports, "writeEntries", { enumerable: true, get: function () { return entries_1.writeEntries; } });

package/dist/config/runtime.d.ts

@@ -21,17 +21,17 @@ export declare const resolveComponentDeclaration: (componentDir: string, compone
  */
 export declare const initRuntimeConfig: (handoff: HandoffContext) => [runtimeConfig: RuntimeConfig, configs: string[], configFileIndex: Map<string, ConfigFileEntry>];
 /**
- * Returns a list of component directories for a given path.
- *
- * This function determines whether the provided `searchPath` is:
- * 1. A single component directory (contains a config file named after the directory)
- * 2. A collection of component directories (subdirectories are components)
- *
- * A directory is considered a component if it contains a config file matching
- * `{dirname}.json`, `{dirname}.js`, or `{dirname}.cjs`.
+ * 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
+ * separates a declared component from a collection directory.
+ */
+export declare const isComponentDirectory: (searchPath: string) => boolean;
+/**
+ * Returns the component directories for a given path. If `searchPath` is itself a component
+ * directory it's returned as-is; otherwise each subdirectory is treated as a potential component.
  *
  * @param searchPath - The absolute path to check for components.
- * @returns An array of string paths to component directories.
+ * @returns Paths to the component directories.
  */
 export declare const getComponentsForPath: (searchPath: string) => string[];
 /**

package/dist/config/runtime.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toLowerCaseKeysAndValues = exports.getItemsForPath = exports.getComponentsForPath = exports.initRuntimeConfig = exports.resolveComponentDeclaration = void 0;
+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"));
@@ -283,24 +283,24 @@ const collectPageMarkdownPaths = (rootDir, relativeParts = []) => {
     return results;
 };
 /**
- * Returns a list of component directories for a given path.
- *
- * This function determines whether the provided `searchPath` is:
- * 1. A single component directory (contains a config file named after the directory)
- * 2. A collection of component directories (subdirectories are components)
- *
- * A directory is considered a component if it contains a config file matching
- * `{dirname}.json`, `{dirname}.js`, or `{dirname}.cjs`.
+ * 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
+ * separates a declared component from a collection directory.
+ */
+const isComponentDirectory = (searchPath) => !!(0, exports.resolveComponentDeclaration)(searchPath, path_1.default.basename(searchPath));
+exports.isComponentDirectory = isComponentDirectory;
+/**
+ * Returns the component directories for a given path. If `searchPath` is itself a component
+ * directory it's returned as-is; otherwise each subdirectory is treated as a potential component.
  *
  * @param searchPath - The absolute path to check for components.
- * @returns An array of string paths to component directories.
+ * @returns Paths to the component directories.
  */
 const getComponentsForPath = (searchPath) => {
-    const dirName = path_1.default.basename(searchPath);
-    const hasOwnConfig = !!(0, exports.resolveComponentDeclaration)(searchPath, dirName);
-    // Check if searchPath itself is a component directory (has a config file named after the directory)
-    if (hasOwnConfig) {
-        // This directory is a single component
+    if ((0, exports.isComponentDirectory)(searchPath)) {
+        return [searchPath];
+    }
+    if (!fs_extra_1.default.existsSync(searchPath)) {
         return [searchPath];
     }
     // Otherwise, treat each subdirectory as a potential component