handoff-app 1.2.2-7 → 2.0.0-1

package/dist/registry/checkout/index.js

@@ -0,0 +1,610 @@
+"use strict";
+/**
+ * Connected-workspace checkout orchestration.
+ *
+ * `checkout <component|pattern> <id>` reads a normalized registry record and its registry-safe
+ * source files from the connected registry through the shared registry client, then writes them
+ * into the local workspace in standard authoring form. The local **declaration is synthesized
+ * locally** in the configured `runtime.workspace.declarationFormat` — declarations are never read
+ * from the registry (they are workspace-only). Identity is matched by stable `id`, so a checked-out
+ * entity maps to the correct logical component/pattern and can be re-authored and re-published.
+ *
+ * Available only from a connected workspace (`runtime.mode: workspace` + a configured
+ * `registryConnection`). Overwriting existing local files is explicit: a `--force` flag or an
+ * interactive confirmation.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+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 __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkoutEntity = exports.resolveConnectionOrThrow = exports.CheckoutError = void 0;
+const p = __importStar(require("@clack/prompts"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const runtime_1 = require("../../config/runtime");
+const logger_1 = require("../../utils/logger");
+const client_1 = require("../client");
+const connection_1 = require("../connection");
+const path_2 = require("../path");
+/** A connected-workspace configuration or precondition failure surfaced to the CLI. */
+class CheckoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CheckoutError';
+    }
+}
+exports.CheckoutError = CheckoutError;
+/** Default authoring format synthesized when no existing file or configured preference applies. */
+const DEFAULT_DECLARATION_FORMAT = 'ts';
+/** Default workspace subdirectory an entity is written into when none is configured. */
+const DEFAULT_ENTITY_DIR = {
+    component: 'components',
+    pattern: 'patterns',
+    page: 'pages',
+};
+/** Source-file extensions stripped to form a module specifier for a React component import. */
+const COMPONENT_EXTENSION = /\.(tsx|jsx|ts|js|cjs|mjs)$/i;
+/**
+ * Ensure the workspace is a connected workspace able to checkout: workspace runtime mode (a registry
+ * host has no local workspace to write into) and a resolved registry URL + access token. Throws an
+ * actionable {@link CheckoutError} naming the exact misconfiguration.
+ */
+const resolveConnectionOrThrow = (handoff) => {
+    var _a, _b, _c;
+    const mode = (_c = (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.runtime) === null || _b === void 0 ? void 0 : _b.mode) !== null && _c !== void 0 ? _c : 'workspace';
+    if (mode !== 'workspace') {
+        throw new CheckoutError(`checkout is only available from a connected workspace (runtime.mode: "workspace"); this project is "${mode}". ` +
+            'A registry host stores and serves entities; it has no local workspace to check them out into.');
+    }
+    const connection = (0, connection_1.resolveRegistryConnection)(handoff.config);
+    if (!connection.url) {
+        throw new CheckoutError(`No registry URL is configured. Set runtime.registryConnection.url, or the "${connection.urlEnv}" environment variable, ` +
+            'to the base URL of the registry to checkout from.');
+    }
+    if (!connection.accessToken) {
+        throw new CheckoutError(`No registry access token is configured. Set the "${connection.accessTokenEnv}" environment variable to the ` +
+            "registry's bearer token to authorize checkout.");
+    }
+    return connection;
+};
+exports.resolveConnectionOrThrow = resolveConnectionOrThrow;
+/** Map a registry client error to an actionable checkout message. */
+const describeFetchFailure = (error, kind, id, registryUrl) => {
+    switch (error.code) {
+        case 'not_found':
+            return `No ${kind} "${id}" exists in the registry at ${registryUrl}.`;
+        case 'runtime_mode_conflict':
+            return `The registry at ${registryUrl} is not running in registry mode, so it cannot serve a checkout: ${error.message}`;
+        case 'unauthorized':
+            return `The registry rejected the access token (401). Check the configured access token matches the registry's token.`;
+        default:
+            return error.message;
+    }
+};
+/**
+ * Resolve the local directory the entity is written into: an already-checked-out / locally-declared
+ * entity keeps its existing source directory (matched by stable `id`); otherwise it lands under the
+ * first configured `entries.{components|patterns}` root (falling back to `components`/`patterns`).
+ */
+const resolveTargetDir = (handoff, kind, id) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b, _c, _d;
+    const store = kind === 'component' ? handoff.store.components : handoff.store.patterns;
+    const existing = yield store.get(id);
+    const existingDir = existing === null || existing === void 0 ? void 0 : existing.path;
+    if (existingDir) {
+        return existingDir;
+    }
+    const configuredRoots = kind === 'component' ? (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components : (_d = (_c = handoff.config) === null || _c === void 0 ? void 0 : _c.entries) === null || _d === void 0 ? void 0 : _d.patterns;
+    const root = (configuredRoots === null || configuredRoots === void 0 ? void 0 : configuredRoots.length)
+        ? path_1.default.resolve(handoff.workingPath, configuredRoots[0])
+        : path_1.default.resolve(handoff.workingPath, DEFAULT_ENTITY_DIR[kind]);
+    const targetDir = (0, path_2.resolvePathWithin)(root, id);
+    if (!targetDir) {
+        throw new CheckoutError(`Cannot checkout ${kind} with unsafe id "${id}".`);
+    }
+    return targetDir;
+});
+/** Read the extension of an existing local declaration in `dir`, if any maps to a known format. */
+const existingDeclarationFormat = (dir) => {
+    if (!fs_extra_1.default.existsSync(dir)) {
+        return undefined;
+    }
+    const declaration = (0, runtime_1.resolveComponentDeclaration)(dir, path_1.default.basename(dir));
+    if (!declaration) {
+        return undefined;
+    }
+    const ext = path_1.default.extname(declaration.fileName).slice(1).toLowerCase();
+    return ['ts', 'js', 'cjs', 'json'].includes(ext) ? ext : undefined;
+};
+/**
+ * Resolve the declaration format: an existing local declaration's extension wins, else the
+ * configured `runtime.workspace.declarationFormat`, else {@link DEFAULT_DECLARATION_FORMAT}.
+ */
+const resolveDeclarationFormat = (handoff, dir) => {
+    var _a, _b, _c, _d, _e;
+    const configured = (_c = (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.runtime) === null || _b === void 0 ? void 0 : _b.workspace) === null || _c === void 0 ? void 0 : _c.declarationFormat;
+    return (_e = (_d = existingDeclarationFormat(dir)) !== null && _d !== void 0 ? _d : configured) !== null && _e !== void 0 ? _e : DEFAULT_DECLARATION_FORMAT;
+};
+/** The declaration filename to write: reuse an existing local declaration, else `<id>.handoff.<format>`. */
+const resolveDeclarationFileName = (dir, id, format) => {
+    if (fs_extra_1.default.existsSync(dir)) {
+        const existing = (0, runtime_1.resolveComponentDeclaration)(dir, path_1.default.basename(dir));
+        if (existing) {
+            return existing.fileName;
+        }
+    }
+    return `${id}.handoff.${format}`;
+};
+const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * The single authored "primary" entry key per renderer. The normalizer derives the others (e.g. it
+ * mirrors a React `component` into `template`, and a CSF `story` into `template`), so the stored
+ * record carries duplicates that must not be re-authored. React authors `component`; handlebars and
+ * CSF author `template` (a `.stories.*` template is what marks a CSF component).
+ */
+const PRIMARY_ENTRY_BY_RENDERER = {
+    react: 'component',
+    handlebars: 'template',
+    csf: 'template',
+};
+/** Primary entry keys, in preference order, for an unknown renderer. */
+const PRIMARY_ENTRY_KEYS = ['component', 'template', 'story'];
+/** Supporting entry keys kept verbatim regardless of renderer. */
+const SUPPORTING_ENTRY_KEYS = ['js', 'scss', 'schema', 'templates'];
+const asString = (value) => (typeof value === 'string' && value ? value : undefined);
+const asStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === 'string') ? value : undefined;
+/**
+ * Rebuild the authored `entries` for a renderer: keep only the renderer's primary entry key (so the
+ * normalizer-duplicated keys are dropped) plus the supporting source entries (`js`/`scss`/`schema`/
+ * `templates`). An unknown renderer keeps the first available primary key by preference order.
+ */
+const buildEntries = (entries, renderer) => {
+    if (!isPlainObject(entries)) {
+        return undefined;
+    }
+    const result = {};
+    const primaryKey = renderer ? PRIMARY_ENTRY_BY_RENDERER[renderer] : undefined;
+    if (primaryKey && typeof entries[primaryKey] === 'string') {
+        result[primaryKey] = entries[primaryKey];
+    }
+    else if (!primaryKey) {
+        const fallback = PRIMARY_ENTRY_KEYS.find((key) => typeof entries[key] === 'string');
+        if (fallback) {
+            result[fallback] = entries[fallback];
+        }
+    }
+    for (const key of SUPPORTING_ENTRY_KEYS) {
+        if (entries[key] !== undefined) {
+            result[key] = entries[key];
+        }
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+};
+/**
+ * Rebuild the authored `previews` map (`DeclarationPreview`) from the stored previews, keeping only
+ * authored fields (`title`, `args`) and dropping build-derived ones (rendered `url`, `usage`,
+ * `sourcePreview`). The component normalizer maps authored `args` to `values`, so the stored record
+ * carries `values`; checkout re-emits it as `args` to match the authoring convention (the form
+ * `make`/`scaffold` generate). Both rebuild identically.
+ */
+const buildPreviews = (previews) => {
+    if (!isPlainObject(previews)) {
+        return undefined;
+    }
+    const result = {};
+    for (const [key, raw] of Object.entries(previews)) {
+        if (!isPlainObject(raw)) {
+            continue;
+        }
+        const preview = {};
+        if (typeof raw.title === 'string')
+            preview.title = raw.title;
+        const args = raw.args !== undefined ? raw.args : raw.values;
+        if (args !== undefined)
+            preview.args = args;
+        result[key] = preview;
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+};
+/**
+ * Synthesize an authored component declaration (`GenericDeclarationConfig`) from the normalized
+ * record. Only authored fields are kept; registry-/build-derived data (`path`, `image`,
+ * `properties`/docgen, rendered preview URLs, `internalPatternPreviews`, `validations`, `variant`,
+ * review `metadata`) is dropped so the local build regenerates it. `name` carries the record title
+ * (the authored contract uses `name`; normalization maps it back to `title`); `shouldDo`/
+ * `shouldNotDo` are emitted in their camelCase authored form.
+ */
+const buildComponentDeclaration = (item) => {
+    var _a, _b, _c, _d, _e;
+    const declaration = {};
+    const id = asString(item.id);
+    if (id)
+        declaration.id = id;
+    declaration.name = (_c = (_b = (_a = asString(item.title)) !== null && _a !== void 0 ? _a : asString(item.name)) !== null && _b !== void 0 ? _b : id) !== null && _c !== void 0 ? _c : '';
+    const description = asString(item.description);
+    if (description)
+        declaration.description = description;
+    const group = asString(item.group);
+    if (group)
+        declaration.group = group;
+    const type = asString(item.type);
+    if (type)
+        declaration.type = type;
+    const renderer = asString(item.renderer);
+    if (renderer)
+        declaration.renderer = renderer;
+    const entries = buildEntries(item.entries, renderer);
+    if (entries)
+        declaration.entries = entries;
+    const previews = buildPreviews(item.previews);
+    if (previews)
+        declaration.previews = previews;
+    const categories = asStringArray(item.categories);
+    if (categories)
+        declaration.categories = categories;
+    const tags = asStringArray(item.tags);
+    if (tags)
+        declaration.tags = tags;
+    const shouldDo = (_d = asStringArray(item.shouldDo)) !== null && _d !== void 0 ? _d : asStringArray(item.should_do);
+    if (shouldDo)
+        declaration.shouldDo = shouldDo;
+    const shouldNotDo = (_e = asStringArray(item.shouldNotDo)) !== null && _e !== void 0 ? _e : asStringArray(item.should_not_do);
+    if (shouldNotDo)
+        declaration.shouldNotDo = shouldNotDo;
+    const figma = asString(item.figma);
+    if (figma)
+        declaration.figma = figma;
+    const figmaComponentId = asString(item.figmaComponentId);
+    if (figmaComponentId)
+        declaration.figmaComponentId = figmaComponentId;
+    if (isPlainObject(item.page))
+        declaration.page = item.page;
+    if (isPlainObject(item.options))
+        declaration.options = item.options;
+    return declaration;
+};
+/**
+ * Rebuild the authored pattern component refs (`PatternComponentRef`) from the stored entries,
+ * keeping only `id`/`preview`/`args` and dropping build-time resolution fields (`resolvedPreview`,
+ * `resolved`).
+ */
+const buildPatternComponents = (components) => {
+    if (!Array.isArray(components)) {
+        return [];
+    }
+    return components.filter(isPlainObject).map((entry) => {
+        const ref = {};
+        const id = asString(entry.id);
+        if (id)
+            ref.id = id;
+        const preview = asString(entry.preview);
+        if (preview)
+            ref.preview = preview;
+        if (isPlainObject(entry.args))
+            ref.args = entry.args;
+        return ref;
+    });
+};
+/**
+ * Synthesize an authored pattern declaration (`GenericPatternDeclarationConfig`) from the normalized
+ * record. Only the authored fields (`id`, `name`, `description`, `group`, `tags`, `components`) are
+ * kept; derived fields (`path`, rendered `url`, review `metadata`) are dropped.
+ */
+const buildPatternDeclaration = (item) => {
+    var _a, _b, _c;
+    const declaration = {};
+    const id = asString(item.id);
+    if (id)
+        declaration.id = id;
+    declaration.name = (_c = (_b = (_a = asString(item.title)) !== null && _a !== void 0 ? _a : asString(item.name)) !== null && _b !== void 0 ? _b : id) !== null && _c !== void 0 ? _c : '';
+    const description = asString(item.description);
+    if (description)
+        declaration.description = description;
+    const group = asString(item.group);
+    if (group)
+        declaration.group = group;
+    const tags = asStringArray(item.tags);
+    if (tags)
+        declaration.tags = tags;
+    declaration.components = buildPatternComponents(item.components);
+    return declaration;
+};
+/**
+ * Pick the renderer-specific `handoff-app` component factory from the record's renderer so the
+ * synthesized declaration matches the authored contract for that renderer. `react`/`handlebars`/`csf`
+ * each have a dedicated factory that stamps the renderer itself (so the renderer is dropped from the
+ * authored config); an unknown/absent renderer falls back to the generic `defineComponent`, which
+ * keeps `renderer` in the config.
+ */
+const resolveComponentFactory = (renderer) => {
+    switch (renderer) {
+        case 'react':
+            return { name: 'defineReactComponent', stampsRenderer: true };
+        case 'handlebars':
+            return { name: 'defineHandlebarsComponent', stampsRenderer: true };
+        case 'csf':
+            return { name: 'defineCsfComponent', stampsRenderer: true };
+        default:
+            return { name: 'defineComponent', stampsRenderer: false };
+    }
+};
+/** Drop a key from an object without mutating it. */
+const omit = (object, key) => {
+    const _a = object, _b = key, _removed = _a[_b], rest = __rest(_a, [typeof _b === "symbol" ? _b : _b + ""]);
+    return rest;
+};
+/** Turn a relative entry path into a module specifier (extension stripped, `./`-prefixed). */
+const toImportSpecifier = (entryPath) => {
+    const withoutExt = entryPath.replace(COMPONENT_EXTENSION, '').split(path_1.default.sep).join('/');
+    return withoutExt.startsWith('.') ? withoutExt : `./${withoutExt}`;
+};
+/** Derive a safe PascalCase identifier for the imported React component. */
+const toComponentIdentifier = (entryPath, fallback) => {
+    const base = path_1.default.basename(entryPath).replace(COMPONENT_EXTENSION, '');
+    const pascal = (base || fallback)
+        .replace(/[^a-zA-Z0-9]+/g, ' ')
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join('');
+    return /^[A-Za-z_$]/.test(pascal) ? pascal : `Component${pascal}`;
+};
+/** Keys matching this are emitted unquoted in JS/TS object literals; others are single-quoted. */
+const JS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** Serialize a string as a single-quoted JS literal (repo style), escaping safely. */
+const singleQuote = (value) => {
+    var _a;
+    let out = "'";
+    for (const char of value) {
+        const code = (_a = char.codePointAt(0)) !== null && _a !== void 0 ? _a : 0;
+        if (char === '\\')
+            out += '\\\\';
+        else if (char === "'")
+            out += "\\'";
+        else if (char === '\n')
+            out += '\\n';
+        else if (char === '\r')
+            out += '\\r';
+        else if (char === '\t')
+            out += '\\t';
+        else if (code < 0x20)
+            out += `\\u${code.toString(16).padStart(4, '0')}`;
+        else
+            out += char;
+    }
+    return `${out}'`;
+};
+/**
+ * Serialize a value as a JS/TS object literal mirroring `JSON.stringify(value, null, 2)` formatting,
+ * except identifier-safe object keys are emitted unquoted (`id: 'button'` rather than
+ * `"id": "button"`) and strings are single-quoted to match the repo's authoring style. `undefined`
+ * entries are dropped.
+ */
+const toJsLiteral = (value, indentLevel = 0) => {
+    const pad = '  '.repeat(indentLevel);
+    const padInner = '  '.repeat(indentLevel + 1);
+    if (value === null) {
+        return 'null';
+    }
+    if (typeof value === 'string') {
+        return singleQuote(value);
+    }
+    if (typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            return '[]';
+        }
+        const items = value.map((item) => `${padInner}${toJsLiteral(item, indentLevel + 1)}`);
+        return `[\n${items.join(',\n')}\n${pad}]`;
+    }
+    const entries = Object.entries(value).filter(([, v]) => v !== undefined);
+    if (entries.length === 0) {
+        return '{}';
+    }
+    const lines = entries.map(([key, v]) => {
+        const renderedKey = JS_IDENTIFIER.test(key) ? key : singleQuote(key);
+        return `${padInner}${renderedKey}: ${toJsLiteral(v, indentLevel + 1)}`;
+    });
+    return `{\n${lines.join(',\n')}\n${pad}}`;
+};
+/** Wrap a config object in a factory call for the given code format (unquoted identifier keys). */
+const wrapFactory = (factory, config, format) => {
+    const literal = toJsLiteral(config);
+    return format === 'ts'
+        ? `import { ${factory} } from 'handoff-app';\n\nexport default ${factory}(${literal});\n`
+        : `const { ${factory} } = require('handoff-app');\n\nmodule.exports = ${factory}(${literal});\n`;
+};
+/**
+ * Synthesize the component declaration file. JSON declarations are the bare object (carrying
+ * `renderer`/`entries`, which the loader reads directly). Code declarations use the renderer-specific
+ * factory; React additionally imports the component from its `entries.component` source and passes it
+ * as the factory's first argument (matching the authored `defineReactComponent` contract). When the
+ * renderer is `react` but no component entry is available, it falls back to the generic factory.
+ */
+const renderComponentDeclaration = (declaration, format) => {
+    var _a;
+    if (format === 'json') {
+        return `${JSON.stringify(declaration, null, 2)}\n`;
+    }
+    const renderer = asString(declaration.renderer);
+    const factory = resolveComponentFactory(renderer);
+    const componentEntry = isPlainObject(declaration.entries) ? asString(declaration.entries.component) : undefined;
+    if (factory.name === 'defineReactComponent' && componentEntry) {
+        const specifier = toImportSpecifier(componentEntry);
+        const identifier = toComponentIdentifier(componentEntry, (_a = asString(declaration.id)) !== null && _a !== void 0 ? _a : 'Component');
+        const literal = toJsLiteral(omit(declaration, 'renderer'));
+        return format === 'ts'
+            ? `import { defineReactComponent } from 'handoff-app';\nimport ${identifier} from '${specifier}';\n\nexport default defineReactComponent(${identifier}, ${literal});\n`
+            : `const { defineReactComponent } = require('handoff-app');\nconst ${identifier} = require('${specifier}').default;\n\nmodule.exports = defineReactComponent(${identifier}, ${literal});\n`;
+    }
+    // React without a resolvable component entry can't use defineReactComponent; keep renderer and use
+    // the generic factory so the build still infers the renderer.
+    const effective = factory.name === 'defineReactComponent' ? { name: 'defineComponent', stampsRenderer: false } : factory;
+    const config = effective.stampsRenderer ? omit(declaration, 'renderer') : declaration;
+    return wrapFactory(effective.name, config, format);
+};
+/** Synthesize the pattern declaration file via `definePattern` (or a bare object for JSON). */
+const renderPatternDeclaration = (declaration, format) => {
+    if (format === 'json') {
+        return `${JSON.stringify(declaration, null, 2)}\n`;
+    }
+    return wrapFactory('definePattern', declaration, format);
+};
+/** Synthesize the declaration file contents for an entity, faithful to its renderer/kind contract. */
+const synthesizeDeclaration = (kind, item, format) => kind === 'component'
+    ? renderComponentDeclaration(buildComponentDeclaration(item), format)
+    : renderPatternDeclaration(buildPatternDeclaration(item), format);
+/**
+ * Confirm overwriting any local files the checkout would replace. Returns `true` to proceed. With
+ * `--force` (or when nothing would be overwritten) it proceeds without prompting; otherwise it asks
+ * for explicit confirmation and treats a cancel/decline as an abort.
+ */
+const confirmOverwrite = (handoff, conflicts) => __awaiter(void 0, void 0, void 0, function* () {
+    if (conflicts.length === 0 || handoff.force) {
+        return true;
+    }
+    const relative = conflicts.map((file) => `  - ${path_1.default.relative(handoff.workingPath, file)}`).join('\n');
+    const proceed = yield p.confirm({
+        message: `Checkout will overwrite ${conflicts.length} existing local file(s):\n${relative}\nOverwrite?`,
+        initialValue: false,
+    });
+    return !p.isCancel(proceed) && proceed === true;
+});
+/** Write a registry source file at its relative path under the target directory. */
+const writeSourceFile = (targetDir, file) => __awaiter(void 0, void 0, void 0, function* () {
+    const absolutePath = (0, path_2.resolvePathWithin)(targetDir, file.path);
+    if (!absolutePath) {
+        throw new CheckoutError(`Registry returned an unsafe source file path "${file.path}".`);
+    }
+    yield fs_extra_1.default.ensureDir(path_1.default.dirname(absolutePath));
+    yield fs_extra_1.default.writeFile(absolutePath, file.content, 'utf8');
+    return absolutePath;
+});
+/**
+ * Checkout a page: write its single verbatim `.md` (transfer path `<id>.md`) back under
+ * `<workingPath>/pages/`. Unlike components/patterns there is no declaration to synthesize — the
+ * markdown file is itself the authored source — so the page round-trips byte-for-byte.
+ */
+const checkoutPage = (handoff, id, payload) => __awaiter(void 0, void 0, void 0, function* () {
+    const pagesRoot = path_1.default.resolve(handoff.workingPath, DEFAULT_ENTITY_DIR.page);
+    const targets = payload.files.map((file) => {
+        const target = (0, path_2.resolvePathWithin)(pagesRoot, file.path);
+        if (!target) {
+            throw new CheckoutError(`Registry returned an unsafe page source path "${file.path}".`);
+        }
+        return target;
+    });
+    const conflicts = targets.filter((file) => fs_extra_1.default.existsSync(file));
+    if (!(yield confirmOverwrite(handoff, conflicts))) {
+        logger_1.Logger.warn(`Checkout of page "${id}" cancelled; no files were written.`);
+        return;
+    }
+    for (const file of payload.files) {
+        yield writeSourceFile(pagesRoot, file);
+    }
+    logger_1.Logger.success(`Checked out page "${id}" into ${path_1.default.relative(handoff.workingPath, pagesRoot) || '.'} ` + `(${payload.files.length} markdown file(s)).`);
+});
+/**
+ * Checkout a single component or pattern from a connected workspace: precondition checks → fetch the
+ * normalized record + source files → resolve the local target → explicit-overwrite guard → write
+ * source files and synthesize the local declaration. Throws {@link CheckoutError} with actionable
+ * messaging on any precondition or fetch failure.
+ */
+const checkoutEntity = (handoff, kind, id) => __awaiter(void 0, void 0, void 0, function* () {
+    const validId = kind === 'page' ? (0, path_2.isSafeRelativePath)(id) : (0, path_2.isSafePathSegment)(id);
+    if (!validId) {
+        throw new CheckoutError(`Cannot checkout ${kind} with unsafe id "${id}".`);
+    }
+    const connection = (0, exports.resolveConnectionOrThrow)(handoff);
+    logger_1.Logger.info(`Fetching ${kind} "${id}" from ${connection.url}…`);
+    const client = (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken });
+    let payload;
+    try {
+        payload = yield client.checkout(kind, id);
+    }
+    catch (error) {
+        if (error instanceof client_1.RegistryClientError) {
+            throw new CheckoutError(describeFetchFailure(error, kind, id, connection.url));
+        }
+        throw error;
+    }
+    // Pages round-trip as a single verbatim `.md` with no declaration synthesis.
+    if (kind === 'page') {
+        yield checkoutPage(handoff, id, payload);
+        return;
+    }
+    const targetDir = yield resolveTargetDir(handoff, kind, id);
+    const format = resolveDeclarationFormat(handoff, targetDir);
+    const declarationFileName = resolveDeclarationFileName(targetDir, id, format);
+    const declarationPath = path_1.default.join(targetDir, declarationFileName);
+    // Compute everything that would be written, then gate overwrite of any pre-existing file.
+    const sourceTargets = payload.files.map((file) => {
+        const absolutePath = (0, path_2.resolvePathWithin)(targetDir, file.path);
+        if (!absolutePath) {
+            throw new CheckoutError(`Registry returned an unsafe source file path "${file.path}".`);
+        }
+        return { file, absolutePath };
+    });
+    const conflicts = [...sourceTargets.map((entry) => entry.absolutePath), declarationPath].filter((file) => fs_extra_1.default.existsSync(file));
+    if (!(yield confirmOverwrite(handoff, conflicts))) {
+        logger_1.Logger.warn(`Checkout of ${kind} "${id}" cancelled; no files were written.`);
+        return;
+    }
+    yield fs_extra_1.default.ensureDir(targetDir);
+    const written = [];
+    for (const { file } of sourceTargets) {
+        written.push(yield writeSourceFile(targetDir, file));
+    }
+    const declaration = synthesizeDeclaration(kind, payload.item, format);
+    yield fs_extra_1.default.writeFile(declarationPath, declaration, 'utf8');
+    written.push(declarationPath);
+    logger_1.Logger.success(`Checked out ${kind} "${id}" into ${path_1.default.relative(handoff.workingPath, targetDir) || '.'} ` +
+        `(${payload.files.length} source file(s) + ${declarationFileName}).`);
+});
+exports.checkoutEntity = checkoutEntity;

package/dist/registry/checkout/tokens.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Connected-workspace token checkout orchestration.
+ *
+ * `checkout tokens [setId]` pulls published token sets from the connected registry into this
+ * workspace: it reconstructs the canonical local `tokens.json` (splicing each set's record into the
+ * document) and restores the generated token files (CSS/SCSS/Style Dictionary/types/custom) to their
+ * standard configured output paths under `getVariablesFilePath()`. Overwriting changed local token
+ * data requires `--force` or an interactive confirmation. Available only from a connected workspace.
+ */
+import Handoff from '../../index';
+/**
+ * Checkout all published token sets, or a single set when `setId` is given. Reconstructs `tokens.json`
+ * and restores generated files; prompts before overwriting changed local files unless `--force`.
+ */
+export declare const checkoutTokens: (handoff: Handoff, setId?: string) => Promise<void>;