handoff-app 2.0.0-1 → 2.0.0-3

package/dist/cli/auth/device.js

@@ -0,0 +1,155 @@
+"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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.revokeAccessToken = exports.loginWithDevice = void 0;
+const logger_1 = require("../../utils/logger");
+const browser_1 = require("./browser");
+const store_1 = require("./store");
+const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+const DEFAULT_DEVICE_EXPIRES_IN_SECONDS = 15 * 60;
+const DEFAULT_TOKEN_EXPIRES_IN_SECONDS = 365 * 24 * 60 * 60;
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+const sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+const responsePayload = (value) => {
+    const envelope = value;
+    return envelope && typeof envelope === 'object' && envelope.data ? envelope.data : value;
+};
+const responseError = (value) => {
+    if (!value || typeof value !== 'object')
+        return {};
+    const body = value;
+    if (typeof body.error === 'string') {
+        return { code: body.error, message: body.error_description || body.error };
+    }
+    if (body.error && typeof body.error === 'object') {
+        return { code: body.error.code, message: body.error.message };
+    }
+    return {};
+};
+const readJson = (response) => __awaiter(void 0, void 0, void 0, function* () {
+    const text = yield response.text();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch (_a) {
+        return {};
+    }
+});
+const shouldOpenBrowser = (options) => {
+    if (options.openBrowser === false)
+        return false;
+    if (process.env.CI === '1' || process.env.CI === 'true')
+        return false;
+    return process.env.HANDOFF_LOGIN_NO_BROWSER !== '1' && process.env.HANDOFF_LOGIN_NO_BROWSER !== 'true';
+};
+const positiveNumberOr = (value, fallback) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+/** Complete the device grant and persist the one-time plaintext access token for this workspace. */
+const loginWithDevice = (workingPath_1, remoteUrl_1, ...args_1) => __awaiter(void 0, [workingPath_1, remoteUrl_1, ...args_1], void 0, function* (workingPath, remoteUrl, options = {}) {
+    const baseUrl = (0, store_1.normalizeRegistryUrl)(remoteUrl);
+    let deviceResponse;
+    try {
+        deviceResponse = yield fetch(`${baseUrl}/api/oauth/device`, {
+            method: 'POST',
+            headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+            body: '{}',
+        });
+    }
+    catch (error) {
+        throw new Error(`Could not reach the registry at ${baseUrl}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const rawDevice = yield readJson(deviceResponse);
+    const device = responsePayload(rawDevice);
+    if (!deviceResponse.ok) {
+        const failure = responseError(rawDevice);
+        throw new Error(`Device authorization failed (${deviceResponse.status}): ${failure.message || deviceResponse.statusText}`);
+    }
+    if (!device.device_code || !device.user_code || !device.verification_uri) {
+        throw new Error('The registry returned an invalid device authorization response.');
+    }
+    const verificationUrl = (0, store_1.assertRegistryOriginUrl)(baseUrl, device.verification_uri_complete ||
+        `${device.verification_uri}${device.verification_uri.includes('?') ? '&' : '?'}user_code=${encodeURIComponent(device.user_code)}`);
+    logger_1.Logger.log('');
+    logger_1.Logger.log('Approve this device in your browser:');
+    logger_1.Logger.log(verificationUrl);
+    logger_1.Logger.log('');
+    logger_1.Logger.log(`Device code: ${device.user_code}`);
+    logger_1.Logger.log('');
+    if (shouldOpenBrowser(options)) {
+        (0, browser_1.tryOpenBrowser)(verificationUrl);
+        logger_1.Logger.info('Attempted to open your default browser.');
+    }
+    const deadline = Date.now() + positiveNumberOr(device.expires_in, DEFAULT_DEVICE_EXPIRES_IN_SECONDS) * 1000;
+    let intervalMs = positiveNumberOr(device.interval, DEFAULT_POLL_INTERVAL_SECONDS) * 1000;
+    while (Date.now() < deadline) {
+        yield sleep(Math.min(intervalMs, Math.max(0, deadline - Date.now())));
+        let tokenResponse;
+        try {
+            tokenResponse = yield fetch(`${baseUrl}/api/oauth/token`, {
+                method: 'POST',
+                headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    grant_type: DEVICE_GRANT,
+                    device_code: device.device_code,
+                }),
+            });
+        }
+        catch (error) {
+            throw new Error(`Could not reach the registry at ${baseUrl}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const rawToken = yield readJson(tokenResponse);
+        const token = responsePayload(rawToken);
+        if (tokenResponse.ok && token.access_token) {
+            const expiresIn = positiveNumberOr(token.expires_in, DEFAULT_TOKEN_EXPIRES_IN_SECONDS);
+            const auth = {
+                remoteUrl: baseUrl,
+                accessToken: token.access_token,
+                expiresAtMs: Date.now() + expiresIn * 1000,
+            };
+            yield (0, store_1.writeCliAuth)(workingPath, auth);
+            return auth;
+        }
+        const failure = responseError(token);
+        if (failure.code === 'authorization_pending')
+            continue;
+        if (failure.code === 'slow_down') {
+            intervalMs = Math.min(intervalMs + 5000, 60000);
+            continue;
+        }
+        if (failure.code === 'expired_token')
+            break;
+        throw new Error(`Token request failed: ${failure.message || tokenResponse.statusText || 'unknown error'}`);
+    }
+    throw new Error('Device authorization expired. Run `handoff-app login` again.');
+});
+exports.loginWithDevice = loginWithDevice;
+/**
+ * Best-effort remote revocation. The caller must clear the local credential regardless of failure.
+ * The bearer header identifies the current token while the body supports RFC 7009-style handlers.
+ */
+const revokeAccessToken = (auth) => __awaiter(void 0, void 0, void 0, function* () {
+    const response = yield fetch(`${(0, store_1.normalizeRegistryUrl)(auth.remoteUrl)}/api/oauth/revoke`, {
+        method: 'POST',
+        headers: {
+            Accept: 'application/json',
+            Authorization: `Bearer ${auth.accessToken}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ token: auth.accessToken }),
+    });
+    if (!response.ok) {
+        const body = yield readJson(response);
+        const failure = responseError(body);
+        throw new Error(failure.message || `${response.status} ${response.statusText}`);
+    }
+});
+exports.revokeAccessToken = revokeAccessToken;

package/dist/cli/auth/store.d.ts

@@ -0,0 +1,29 @@
+/** Credentials issued to this workspace by one registry. */
+export interface CliAuth {
+    remoteUrl: string;
+    accessToken: string;
+    /** Epoch milliseconds after which the token must not be used. */
+    expiresAtMs: number;
+}
+/**
+ * Canonicalize a registry URL for both HTTP requests and exact credential matching.
+ * Base paths are retained; query strings, fragments, credentials, and trailing slashes are not.
+ */
+export declare const normalizeRegistryUrl: (value: string) => string;
+/**
+ * A verification URL is only trustworthy if it's a web URL on the same origin as the
+ * registry the CLI is authenticating against. This stops a tampered device-authorization
+ * response from sending the browser to (or injecting a command via) another origin.
+ */
+export declare const assertRegistryOriginUrl: (baseUrl: string, candidate: string) => string;
+export declare const cliAuthFilePath: (workingPath: string) => string;
+/** Invalid or partial credential files are treated as unauthenticated. */
+export declare const readCliAuth: (workingPath: string) => Promise<CliAuth | null>;
+/**
+ * Atomically replace the credential file. Restrictive permissions are best-effort on platforms
+ * whose filesystems do not support POSIX modes.
+ */
+export declare const writeCliAuth: (workingPath: string, auth: CliAuth) => Promise<void>;
+export declare const clearCliAuth: (workingPath: string) => Promise<void>;
+export declare const cliAuthMatchesRegistry: (auth: CliAuth | null, remoteUrl: string) => boolean;
+export declare const cliAuthTokenIsValid: (auth: CliAuth | null, skewMs?: number) => boolean;

package/dist/cli/auth/store.js

@@ -0,0 +1,146 @@
+"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 });
+exports.cliAuthTokenIsValid = exports.cliAuthMatchesRegistry = exports.clearCliAuth = exports.writeCliAuth = exports.readCliAuth = exports.cliAuthFilePath = exports.assertRegistryOriginUrl = exports.normalizeRegistryUrl = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const AUTH_DIRECTORY = '.handoff';
+const AUTH_FILE = 'cli-auth.json';
+/**
+ * Canonicalize a registry URL for both HTTP requests and exact credential matching.
+ * Base paths are retained; query strings, fragments, credentials, and trailing slashes are not.
+ */
+const normalizeRegistryUrl = (value) => {
+    let parsed;
+    try {
+        parsed = new URL(value.trim());
+    }
+    catch (_a) {
+        throw new Error(`Invalid registry URL "${value}". Pass an absolute http:// or https:// URL.`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error(`Invalid registry URL protocol "${parsed.protocol}". Use http:// or https://.`);
+    }
+    if (parsed.username || parsed.password) {
+        throw new Error('Registry URLs must not contain credentials.');
+    }
+    const pathname = parsed.pathname.replace(/\/+$/, '');
+    return `${parsed.origin}${pathname === '/' ? '' : pathname}`;
+};
+exports.normalizeRegistryUrl = normalizeRegistryUrl;
+/**
+ * A verification URL is only trustworthy if it's a web URL on the same origin as the
+ * registry the CLI is authenticating against. This stops a tampered device-authorization
+ * response from sending the browser to (or injecting a command via) another origin.
+ */
+const assertRegistryOriginUrl = (baseUrl, candidate) => {
+    let url;
+    try {
+        url = new URL(candidate);
+    }
+    catch (_a) {
+        throw new Error('The registry returned an invalid verification URL.');
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`The registry returned a verification URL with an unsupported protocol "${url.protocol}".`);
+    }
+    if (url.origin !== new URL(baseUrl).origin) {
+        throw new Error('The registry returned a verification URL for a different origin than the registry.');
+    }
+    return url.toString();
+};
+exports.assertRegistryOriginUrl = assertRegistryOriginUrl;
+const cliAuthFilePath = (workingPath) => path_1.default.resolve(workingPath, AUTH_DIRECTORY, AUTH_FILE);
+exports.cliAuthFilePath = cliAuthFilePath;
+const isCliAuth = (value) => {
+    if (!value || typeof value !== 'object')
+        return false;
+    const auth = value;
+    return (typeof auth.remoteUrl === 'string' &&
+        typeof auth.accessToken === 'string' &&
+        auth.accessToken.length > 0 &&
+        typeof auth.expiresAtMs === 'number' &&
+        Number.isFinite(auth.expiresAtMs));
+};
+/** Invalid or partial credential files are treated as unauthenticated. */
+const readCliAuth = (workingPath) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        const value = (yield fs_extra_1.default.readJson((0, exports.cliAuthFilePath)(workingPath)));
+        if (!isCliAuth(value))
+            return null;
+        return Object.assign(Object.assign({}, value), { remoteUrl: (0, exports.normalizeRegistryUrl)(value.remoteUrl) });
+    }
+    catch (_a) {
+        return null;
+    }
+});
+exports.readCliAuth = readCliAuth;
+/**
+ * Atomically replace the credential file. Restrictive permissions are best-effort on platforms
+ * whose filesystems do not support POSIX modes.
+ */
+const writeCliAuth = (workingPath, auth) => __awaiter(void 0, void 0, void 0, function* () {
+    const filePath = (0, exports.cliAuthFilePath)(workingPath);
+    const directory = path_1.default.dirname(filePath);
+    const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    const value = Object.assign(Object.assign({}, auth), { remoteUrl: (0, exports.normalizeRegistryUrl)(auth.remoteUrl) });
+    yield fs_extra_1.default.ensureDir(directory, 0o700);
+    try {
+        yield fs_extra_1.default.chmod(directory, 0o700);
+    }
+    catch (_a) {
+        // Windows and some mounted filesystems do not implement POSIX modes.
+    }
+    try {
+        yield fs_extra_1.default.writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+        try {
+            yield fs_extra_1.default.chmod(temporaryPath, 0o600);
+        }
+        catch (_b) {
+            // Best effort; see the directory chmod above.
+        }
+        yield fs_extra_1.default.rename(temporaryPath, filePath);
+        try {
+            yield fs_extra_1.default.chmod(filePath, 0o600);
+        }
+        catch (_c) {
+            // Best effort.
+        }
+    }
+    catch (error) {
+        yield fs_extra_1.default.remove(temporaryPath).catch(() => undefined);
+        throw error;
+    }
+});
+exports.writeCliAuth = writeCliAuth;
+const clearCliAuth = (workingPath) => __awaiter(void 0, void 0, void 0, function* () {
+    const filePath = (0, exports.cliAuthFilePath)(workingPath);
+    if (yield fs_extra_1.default.pathExists(filePath)) {
+        yield fs_extra_1.default.remove(filePath);
+    }
+});
+exports.clearCliAuth = clearCliAuth;
+const cliAuthMatchesRegistry = (auth, remoteUrl) => {
+    if (!auth)
+        return false;
+    try {
+        return auth.remoteUrl === (0, exports.normalizeRegistryUrl)(remoteUrl);
+    }
+    catch (_a) {
+        return false;
+    }
+};
+exports.cliAuthMatchesRegistry = cliAuthMatchesRegistry;
+const cliAuthTokenIsValid = (auth, skewMs = 30000) => Boolean((auth === null || auth === void 0 ? void 0 : auth.accessToken) && auth.expiresAtMs > Date.now() + skewMs);
+exports.cliAuthTokenIsValid = cliAuthTokenIsValid;

package/dist/cli/create.js

@@ -85,7 +85,7 @@ const createDirectory = (dirPath) => {
  * Get mandatory templates based on whether examples are included
  * Uses different handoff config templates for blank vs. with-examples projects
  */
-const getMandatoryTemplates = (includeExamples, languagePreference) => {
+const getMandatoryTemplates = (includeExamples, languagePreference, includeVercel) => {
     const configFormat = languagePreference;
     const configTemplateBaseName = includeExamples ? 'handoff.config.with-examples' : 'handoff.config';
     const configTemplateSource = `${configTemplateBaseName}.${configFormat === 'typescript' ? 'ts' : 'js'}.tpl`;
@@ -103,6 +103,9 @@ const getMandatoryTemplates = (includeExamples, languagePreference) => {
     if (languagePreference === 'typescript') {
         templates.push({ source: 'tsconfig.json.tpl', destination: 'tsconfig.json' });
     }
+    if (includeVercel) {
+        templates.push({ source: 'vercel.json.tpl', destination: 'vercel.json' });
+    }
     return templates;
 };
 const getExampleTemplates = (languagePreference) => {
@@ -127,7 +130,8 @@ const renderTemplate = (content, data) => {
     });
 };
 const getDependenciesToInstall = (options) => {
-    const dependencies = ['handoff-app@latest'];
+    // TODO: switch back to `handoff-app@latest` before the 2.0 stable release.
+    const dependencies = ['handoff-app@next'];
     const devDependencies = [];
     if (options.includeExamples) {
         dependencies.push('react', 'react-dom');
@@ -250,6 +254,45 @@ const create = () => __awaiter(void 0, void 0, void 0, function* () {
             process.exit(0);
         }
         const languagePreference = languagePreferenceSelection;
+        const includeVercelSelection = yield p.confirm({
+            message: 'Add a Vercel deployment config (vercel.json)?',
+            initialValue: true,
+        });
+        if (p.isCancel(includeVercelSelection)) {
+            p.cancel('Project creation cancelled.');
+            process.exit(0);
+        }
+        const includeVercel = includeVercelSelection;
+        // When a Vercel config is scaffolded, choose which deployment its build command produces. Both
+        // package to `.vercel/output`; they differ in what is served. Registry is the recommended,
+        // pre-selected option; static stays available as the simplest deploy.
+        let vercelBuildCommand = 'npm run build -- --target registry --package vercel';
+        if (includeVercel) {
+            const vercelDeploymentSelection = yield p.select({
+                message: 'Which deployment should Vercel build?',
+                options: [
+                    {
+                        value: 'registry',
+                        label: 'Registry (dynamic)',
+                        hint: 'Live, database-backed app (needs a Postgres DATABASE_URL). The more capable, actively evolving option — recommended for a shared design system.',
+                    },
+                    {
+                        value: 'static',
+                        label: 'Static site',
+                        hint: 'Prebuilt snapshot served as plain files. The simplest to deploy and run.',
+                    },
+                ],
+                initialValue: 'registry',
+            });
+            if (p.isCancel(vercelDeploymentSelection)) {
+                p.cancel('Project creation cancelled.');
+                process.exit(0);
+            }
+            vercelBuildCommand =
+                vercelDeploymentSelection === 'registry'
+                    ? 'npm run build -- --target registry --package vercel'
+                    : 'npm run build -- --target static --package vercel';
+        }
         // Get Figma project ID
         p.log.step(chalk_1.default.blue('Figma Configuration'));
         const figmaProjectId = yield p.text({
@@ -277,6 +320,8 @@ const create = () => __awaiter(void 0, void 0, void 0, function* () {
             figmaAccessToken: (figmaAccessToken || '').trim(),
             languagePreference,
             includeExamples,
+            includeVercel,
+            vercelBuildCommand,
         };
         // Create files
         const spinner = p.spinner();
@@ -287,7 +332,7 @@ const create = () => __awaiter(void 0, void 0, void 0, function* () {
         }
         // Combine mandatory templates with example templates based on user choice
         const templates = [
-            ...getMandatoryTemplates(includeExamples, languagePreference),
+            ...getMandatoryTemplates(includeExamples, languagePreference, includeVercel),
             ...(includeExamples ? getExampleTemplates(languagePreference) : []),
         ];
         try {

package/dist/cli/scaffold.js

@@ -40,8 +40,8 @@ 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");
 // Constants
-const CONFIG_FILES = ['handoff.config.ts', 'handoff.config.js', 'handoff.config.cjs', 'handoff.config.json'];
 const COMPONENTS_DIR = 'components';
 const DEFAULT_GROUPS = [
     { value: 'Atomic Elements', label: 'Atomic Elements' },
@@ -197,142 +197,6 @@ const countMatchingRegisteredComponents = (figmaComponents, registeredIds) => {
     const figmaSet = new Set(figmaComponents.map((c) => c.name.toLowerCase()));
     return registeredIds.filter((id) => figmaSet.has(id.toLowerCase())).length;
 };
-/**
- * Check if components will be auto-loaded by an existing entry
- * e.g., if 'components' directory is listed, all subdirectories are auto-loaded
- */
-const willComponentsAutoLoad = (existingPaths) => {
-    // Normalize paths for comparison
-    const normalizedPaths = existingPaths.map((p) => p.replace(/\/$/, '').toLowerCase());
-    // If 'components' directory itself is in the list, all components auto-load
-    return normalizedPaths.includes(COMPONENTS_DIR);
-};
-/**
- * Format component paths as a properly indented array string for JS files
- */
-const formatComponentsArray = (paths, indent = '      ') => {
-    if (paths.length === 0)
-        return '[]';
-    if (paths.length === 1)
-        return `['${paths[0]}']`;
-    return `[\n${paths.map((p) => `${indent}'${p}',`).join('\n')}\n${indent.slice(2)}]`;
-};
-/**
- * Update handoff config file to add component paths
- */
-const updateConfigFile = (handoff, componentNames) => __awaiter(void 0, void 0, void 0, function* () {
-    const configFile = CONFIG_FILES.find((file) => fs_extra_1.default.existsSync(path_1.default.resolve(handoff.workingPath, file)));
-    const newComponentPaths = componentNames.map((name) => `${COMPONENTS_DIR}/${name}`);
-    if (!configFile) {
-        // Create a new handoff.config.json
-        const newConfig = {
-            entries: {
-                components: newComponentPaths,
-            },
-        };
-        const configPath = path_1.default.resolve(handoff.workingPath, 'handoff.config.json');
-        yield fs_extra_1.default.writeJSON(configPath, newConfig, { spaces: 2 });
-        return { success: true, isJsConfig: false, configPath, skipped: false };
-    }
-    const configPath = path_1.default.resolve(handoff.workingPath, configFile);
-    if (configFile.endsWith('.json')) {
-        const config = yield fs_extra_1.default.readJSON(configPath);
-        // Initialize entries if not present
-        if (!config.entries) {
-            config.entries = {};
-        }
-        if (!config.entries.components) {
-            config.entries.components = [];
-        }
-        // Check if components will auto-load
-        if (willComponentsAutoLoad(config.entries.components)) {
-            return { success: true, isJsConfig: false, configPath, skipped: true };
-        }
-        // Add new component paths
-        const existingPaths = new Set(config.entries.components);
-        for (const componentPath of newComponentPaths) {
-            if (!existingPaths.has(componentPath)) {
-                config.entries.components.push(componentPath);
-            }
-        }
-        yield fs_extra_1.default.writeJSON(configPath, config, { spaces: 2 });
-        return { success: true, isJsConfig: false, configPath, skipped: false };
-    }
-    // For code config files, try to update them programmatically
-    if (configFile.endsWith('.ts') || configFile.endsWith('.js') || configFile.endsWith('.cjs')) {
-        try {
-            let content = yield fs_extra_1.default.readFile(configPath, 'utf8');
-            // Check if entries.components already exists
-            const hasEntriesComponents = /entries\s*:\s*\{[\s\S]*?components\s*:/.test(content);
-            if (hasEntriesComponents) {
-                // Find and update the components array
-                // Match: components: [...] or components: ["..."]
-                const componentsArrayRegex = /(components\s*:\s*\[)([^\]]*)(\])/;
-                const match = content.match(componentsArrayRegex);
-                if (match) {
-                    const existingContent = match[2].trim();
-                    const existingPaths = existingContent
-                        .split(',')
-                        .map((s) => s.trim().replace(/['"]/g, ''))
-                        .filter((s) => s.length > 0);
-                    // Check if components will auto-load
-                    if (willComponentsAutoLoad(existingPaths)) {
-                        return { success: true, isJsConfig: true, configPath, skipped: true };
-                    }
-                    const existingSet = new Set(existingPaths);
-                    const pathsToAdd = newComponentPaths.filter((p) => !existingSet.has(p));
-                    if (pathsToAdd.length > 0) {
-                        const allPaths = [...existingPaths, ...pathsToAdd];
-                        // Format with proper indentation (detect existing indentation)
-                        const indentMatch = content.match(/components\s*:\s*\[\s*\n(\s*)/);
-                        const indent = indentMatch ? indentMatch[1] : '      ';
-                        const formattedArray = formatComponentsArray(allPaths, indent);
-                        content = content.replace(componentsArrayRegex, `components: ${formattedArray}`);
-                        yield fs_extra_1.default.writeFile(configPath, content, 'utf8');
-                    }
-                    return { success: true, isJsConfig: true, configPath, skipped: false };
-                }
-            }
-            // If entries exists but no components, or no entries at all
-            // Try to add the entries.components section
-            const hasEntries = /entries\s*:\s*\{/.test(content);
-            if (hasEntries) {
-                // Add components to existing entries object with proper formatting
-                const formattedArray = formatComponentsArray(newComponentPaths);
-                content = content.replace(/(entries\s*:\s*\{)/, `$1\n    components: ${formattedArray},`);
-                yield fs_extra_1.default.writeFile(configPath, content, 'utf8');
-                return { success: true, isJsConfig: true, configPath, skipped: false };
-            }
-            // No entries object, try to add it before the closing of exported object
-            const formattedArray = formatComponentsArray(newComponentPaths);
-            const entriesBlock = `  entries: {\n    components: ${formattedArray},\n  },\n`;
-            // Try to insert after module.exports = {
-            if (content.includes('module.exports = {')) {
-                content = content.replace(/(module\.exports\s*=\s*\{)/, `$1\n${entriesBlock}`);
-                yield fs_extra_1.default.writeFile(configPath, content, 'utf8');
-                return { success: true, isJsConfig: true, configPath, skipped: false };
-            }
-            // Try to insert after export default {
-            if (/export\s+default\s+\{/.test(content)) {
-                content = content.replace(/(export\s+default\s+\{)/, `$1\n${entriesBlock}`);
-                yield fs_extra_1.default.writeFile(configPath, content, 'utf8');
-                return { success: true, isJsConfig: true, configPath, skipped: false };
-            }
-            // Try to insert into defineConfig({ ... })
-            if (/defineConfig\s*\(\s*\{/.test(content)) {
-                content = content.replace(/(defineConfig\s*\(\s*\{)/, `$1\n${entriesBlock}`);
-                yield fs_extra_1.default.writeFile(configPath, content, 'utf8');
-                return { success: true, isJsConfig: true, configPath, skipped: false };
-            }
-            // Fallback: couldn't parse the JS config
-            return { success: false, isJsConfig: true, configPath, skipped: false };
-        }
-        catch (_a) {
-            return { success: false, isJsConfig: true, configPath, skipped: false };
-        }
-    }
-    return { success: false, isJsConfig: false, configPath, skipped: false };
-});
 /**
  * Create component files
  */
@@ -513,18 +377,6 @@ const runScaffold = (handoff) => __awaiter(void 0, void 0, void 0, function* ()
         allCreatedFiles.push(...createdFiles);
         componentNames.push(config.name);
     }
-    // Update config if requested
-    let configUpdateResult = null;
-    if (updateConfig) {
-        configUpdateResult = yield updateConfigFile(handoff, componentNames);
-        if (!configUpdateResult.success) {
-            const relativePath = path_1.default.relative(handoff.workingPath, configUpdateResult.configPath);
-            p.log.warn(`Could not automatically update ${relativePath}. Please manually add these paths to entries.components:`);
-            for (const name of componentNames) {
-                console.log(chalk_1.default.yellow(`  'components/${name}'`));
-            }
-        }
-    }
     generationSpinner.stop('Files created successfully');
     // Display summary
     p.log.success('Created files:');
@@ -532,13 +384,27 @@ const runScaffold = (handoff) => __awaiter(void 0, void 0, void 0, function* ()
         const relativePath = path_1.default.relative(handoff.workingPath, file);
         console.log(chalk_1.default.dim(`  ${relativePath}`));
     }
-    if (updateConfig && (configUpdateResult === null || configUpdateResult === void 0 ? void 0 : configUpdateResult.success)) {
-        const configFileName = path_1.default.basename(configUpdateResult.configPath);
-        if (configUpdateResult.skipped) {
-            p.log.info(`Config already includes 'components' directory - new components will auto-load`);
+    // Update config if requested. Components already covered by a collection directory auto-load,
+    // so we only write the uncovered ones into entries.components.
+    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) {
+            p.log.info(`Config already covers these components - they'll auto-load`);
         }
         else {
-            p.log.success(`Updated ${configFileName} with component paths`);
+            const result = yield (0, entries_1.writeEntries)(handoff, 'components', uncovered);
+            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:`);
+                for (const rel of result.pending) {
+                    console.log(chalk_1.default.yellow(`  '${rel}'`));
+                }
+            }
         }
     }
     p.outro(chalk_1.default.green(`Successfully created ${componentConfigs.length} component stub(s)!`));

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

@@ -1,15 +1,15 @@
 import { CommandModule } from 'yargs';
 import { SharedArgs } from '../types';
-/** Entity kinds checkout-able from a connected workspace. */
-declare const ENTITY_KINDS: readonly ["component", "pattern", "page", "tokens", "assets"];
+import { RegistryEntityKind } from '../utils';
 export interface CheckoutArgs extends SharedArgs {
-    type: (typeof ENTITY_KINDS)[number];
+    type: RegistryEntityKind;
     id?: string;
 }
 /**
- * `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.