handoff-app 1.2.2-6 → 2.0.0-0

package/dist/artifacts/types.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Structured artifact and build-metadata model for handoff-app v2.
+ *
+ * These types are the contract the rest of v2 reads from instead of parsing generated HTML.
+ * The workspace (filesystem) and registry (database) tracks both produce and consume this
+ * shape, so dependency validation, serving, publish, ingestion, and pattern composition all
+ * rely on structured data rather than HTML inspection.
+ *
+ * This module is a pure prefactor: types and constants only. No artifact is read or written
+ * here — consumers (the store, docs read API, build, publish/ingest) come in later issues.
+ */
+/**
+ * Logical artifact kind. Mirrors the docs read-model artifact record's `artifactKind` — the
+ * broad class an artifact belongs to, independent of how it is stored or served.
+ */
+export type ArtifactKind = 'json' | 'html' | 'css' | 'javascript' | 'other';
+/**
+ * What an artifact (or reference) logically belongs to. Shared/global artifacts are owned by
+ * `asset` with a `null` owner id; entity-owned artifacts name their component or pattern.
+ */
+export type ArtifactOwnerKind = 'component' | 'pattern' | 'asset';
+/**
+ * Kind of a structured artifact reference carried by an HTML artifact. Drives load order,
+ * validation, and pattern dedup without ever parsing the HTML.
+ */
+export type ArtifactReferenceKind = 'client' | 'style' | 'script' | 'shared' | 'other';
+/**
+ * Build status for an artifact/entity. A successful publish sets `current` with `builtAt`,
+ * `builderVersion`, and `artifactHash` all present; metadata-only records report `missing`.
+ */
+export type ArtifactBuildStatus = 'current' | 'stale' | 'missing' | 'error';
+/**
+ * A structured reference from one artifact (typically preview/inspect HTML) to another
+ * artifact it depends on. References are the single source of truth for dependency
+ * resolution — HTML is never parsed for dependencies.
+ */
+export interface ArtifactReference {
+    /** Logical path of the referenced artifact (e.g. `component/main.css`). */
+    path: string;
+    /** Reference kind, used for load ordering and dedup. */
+    kind: ArtifactReferenceKind;
+    /** Whether the referencing artifact cannot render correctly without this reference. */
+    required: boolean;
+    /** What the referenced artifact belongs to, when known. */
+    ownerKind?: ArtifactOwnerKind;
+    /** Owner entity id; `null` for shared/global artifacts. */
+    ownerId?: string | null;
+    /** Optional content type of the referenced artifact. */
+    contentType?: string;
+    /** Optional format/version tag of the referenced artifact. */
+    formatVersion?: string;
+    /** Optional build identity the reference was resolved against. */
+    buildId?: string;
+    /** Optional content hash of the referenced artifact. */
+    hash?: string;
+    /** Optional byte size of the referenced artifact. */
+    size?: number;
+}
+/**
+ * Build metadata for an artifact or entity. Captures enough to validate, serve, and debug docs
+ * output.
+ */
+export interface ArtifactBuildMetadata {
+    /** Current build state for the artifact/entity. */
+    status: ArtifactBuildStatus;
+    /** ISO timestamp of the build that produced the current artifact, when built. */
+    builtAt?: string;
+    /** Version of the builder that produced the artifact. */
+    builderVersion?: string;
+    /** Content hash of the produced artifact. */
+    artifactHash?: string;
+    /** Optional hash of the source that produced the artifact, for staleness detection. */
+    sourceHash?: string;
+    /** Optional non-fatal build warnings. */
+    warnings?: string[];
+    /** Optional fatal build error message. */
+    error?: string;
+}
+/**
+ * Size diagnostics for an artifact, used for publish/build reporting.
+ */
+export interface ArtifactSizeDiagnostics {
+    /** Raw byte size of the artifact content. */
+    bytes: number;
+    /** Optional gzipped byte size, when measured. */
+    gzipBytes?: number;
+}
+/**
+ * Structured description of a single docs read-model artifact. This is the shape the docs read
+ * API serves, the static build materializes, and registry publish/ingest moves over the wire —
+ * carrying enough to validate, serve, and debug an artifact.
+ *
+ * `content` and `storageRef` are intentionally both optional so the model leaves room for
+ * future object storage of large/binary assets rather than assuming inline content for every
+ * kind.
+ */
+export interface ArtifactDescriptor {
+    /** Logical artifact path (e.g. `component/badge-primary.html`). Stable key for serving. */
+    path: string;
+    /** Broad artifact kind. */
+    artifactKind: ArtifactKind;
+    /** Content type to serve the artifact with (e.g. `text/html; charset=utf-8`). */
+    contentType: string;
+    /** Inline artifact content, when stored inline. */
+    content?: string;
+    /** Reference to externally stored content (future object storage), when not inline. */
+    storageRef?: string;
+    /** What the artifact belongs to. */
+    ownerKind: ArtifactOwnerKind;
+    /** Owner entity id; `null` for shared/global artifacts. */
+    ownerId: string | null;
+    /** Structured references this artifact depends on (required and optional). */
+    references: ArtifactReference[];
+    /** Optional format/version tag (e.g. preview/inspect HTML format version). */
+    formatVersion?: string;
+    /** Build identity that produced this artifact. */
+    buildId?: string;
+    /** Content hash of the artifact. */
+    hash?: string;
+    /** Byte size of the artifact. */
+    size?: number;
+    /** Build metadata for the artifact. */
+    build?: ArtifactBuildMetadata;
+    /** Optional size diagnostics. */
+    diagnostics?: ArtifactSizeDiagnostics;
+}
+/** Logical path of the shared global stylesheet artifact. */
+export declare const SHARED_MAIN_CSS_ARTIFACT_PATH = "component/main.css";
+/** Logical path of the shared global script artifact. */
+export declare const SHARED_MAIN_JS_ARTIFACT_PATH = "component/main.js";
+/** Logical path of the shared component styles artifact. */
+export declare const SHARED_STYLES_CSS_ARTIFACT_PATH = "component/shared.css";
+/** Logical path of the per-build artifact metadata manifest. */
+export declare const ARTIFACT_METADATA_PATH = "artifact-metadata.json";
+/** Format version tag carried by generated React preview/inspect HTML. */
+export declare const REACT_PREVIEW_FORMAT_VERSION = "handoff-react-preview-v1";

package/dist/artifacts/types.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Structured artifact and build-metadata model for handoff-app v2.
+ *
+ * These types are the contract the rest of v2 reads from instead of parsing generated HTML.
+ * The workspace (filesystem) and registry (database) tracks both produce and consume this
+ * shape, so dependency validation, serving, publish, ingestion, and pattern composition all
+ * rely on structured data rather than HTML inspection.
+ *
+ * This module is a pure prefactor: types and constants only. No artifact is read or written
+ * here — consumers (the store, docs read API, build, publish/ingest) come in later issues.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REACT_PREVIEW_FORMAT_VERSION = exports.ARTIFACT_METADATA_PATH = exports.SHARED_STYLES_CSS_ARTIFACT_PATH = exports.SHARED_MAIN_JS_ARTIFACT_PATH = exports.SHARED_MAIN_CSS_ARTIFACT_PATH = void 0;
+/** Logical path of the shared global stylesheet artifact. */
+exports.SHARED_MAIN_CSS_ARTIFACT_PATH = 'component/main.css';
+/** Logical path of the shared global script artifact. */
+exports.SHARED_MAIN_JS_ARTIFACT_PATH = 'component/main.js';
+/** Logical path of the shared component styles artifact. */
+exports.SHARED_STYLES_CSS_ARTIFACT_PATH = 'component/shared.css';
+/** Logical path of the per-build artifact metadata manifest. */
+exports.ARTIFACT_METADATA_PATH = 'artifact-metadata.json';
+/** Format version tag carried by generated React preview/inspect HTML. */
+exports.REACT_PREVIEW_FORMAT_VERSION = 'handoff-react-preview-v1';

package/dist/artifacts/url.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Centralized, basePath-aware canonical artifact URL builder.
+ *
+ * Every artifact reference emitted in generated HTML and docs read data flows through this one
+ * builder. URLs are always of the canonical form:
+ *
+ *   {basePath}/api/docs/artifacts/{artifactPath}
+ *
+ * intended for use directly in native `href`/`src` attributes. By contract these URLs never carry
+ * a query string and never depend on artifact-specific data attributes — artifact references come
+ * from structured metadata, not the URL or the HTML.
+ *
+ * This module is pure and runtime-agnostic (no Node or browser globals) so the build and the
+ * Next app can both import it.
+ */
+/** Canonical route prefix all artifact URLs are served under. */
+export declare const ARTIFACTS_ROUTE_SEGMENT = "api/docs/artifacts";
+/** Route prefix for docs read API metadata (`.json`) reads. */
+export declare const DOCS_ROUTE_SEGMENT = "api/docs";
+/**
+ * Normalize a configured basePath to either an empty string or a single-leading-slash,
+ * no-trailing-slash form. Mirrors the Next app's `resolveBasePath` so builder output composes
+ * correctly with the configured Next `basePath`.
+ */
+export declare const normalizeBasePath: (basePath?: string | null) => string;
+/**
+ * Build a canonical artifact URL for a logical artifact path.
+ *
+ * Each path segment is individually `encodeURIComponent`-encoded (so a slash separating logical
+ * segments is preserved while reserved characters within a segment are escaped), and the
+ * configured `basePath` is preserved ahead of the canonical route.
+ *
+ * @param artifactPath Logical artifact path, e.g. `component/badge-primary.html`.
+ * @param basePath Optional configured base path; normalized like the Next app's basePath.
+ * @returns A canonical `{basePath}/api/docs/artifacts/{encodedPath}` URL.
+ * @throws If `artifactPath` has no usable segments, or contains a `.`/`..` traversal segment.
+ */
+export declare const buildArtifactUrl: (artifactPath: string, basePath?: string | null) => string;
+/**
+ * Build the canonical docs read API URL for a component's detail metadata
+ * (`{basePath}/api/docs/components/{id}.json`). The id is URL-encoded; `basePath` is preserved.
+ * This is the single source of the metadata-read URL that the build records as an entity's `path`.
+ */
+export declare const buildComponentDetailUrl: (id: string, basePath?: string | null) => string;
+/**
+ * Build the canonical docs read API URL for a pattern's detail metadata
+ * (`{basePath}/api/docs/patterns/{id}.json`). The id is URL-encoded; `basePath` is preserved.
+ */
+export declare const buildPatternDetailUrl: (id: string, basePath?: string | null) => string;

package/dist/artifacts/url.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Centralized, basePath-aware canonical artifact URL builder.
+ *
+ * Every artifact reference emitted in generated HTML and docs read data flows through this one
+ * builder. URLs are always of the canonical form:
+ *
+ *   {basePath}/api/docs/artifacts/{artifactPath}
+ *
+ * intended for use directly in native `href`/`src` attributes. By contract these URLs never carry
+ * a query string and never depend on artifact-specific data attributes — artifact references come
+ * from structured metadata, not the URL or the HTML.
+ *
+ * This module is pure and runtime-agnostic (no Node or browser globals) so the build and the
+ * Next app can both import it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPatternDetailUrl = exports.buildComponentDetailUrl = exports.buildArtifactUrl = exports.normalizeBasePath = exports.DOCS_ROUTE_SEGMENT = exports.ARTIFACTS_ROUTE_SEGMENT = void 0;
+/** Canonical route prefix all artifact URLs are served under. */
+exports.ARTIFACTS_ROUTE_SEGMENT = 'api/docs/artifacts';
+/** Route prefix for docs read API metadata (`.json`) reads. */
+exports.DOCS_ROUTE_SEGMENT = 'api/docs';
+/**
+ * Normalize a configured basePath to either an empty string or a single-leading-slash,
+ * no-trailing-slash form. Mirrors the Next app's `resolveBasePath` so builder output composes
+ * correctly with the configured Next `basePath`.
+ */
+const normalizeBasePath = (basePath) => {
+    if (!basePath) {
+        return '';
+    }
+    const trimmed = basePath.replace(/^\/+|\/+$/g, '');
+    return trimmed ? `/${trimmed}` : '';
+};
+exports.normalizeBasePath = normalizeBasePath;
+/**
+ * Split a logical artifact path into its non-empty segments. Leading/trailing/duplicate slashes
+ * are ignored; backslashes are treated as separators so Windows-style inputs normalize too.
+ */
+const toArtifactSegments = (artifactPath) => artifactPath
+    .split(/[\\/]+/)
+    .filter((segment) => segment.length > 0);
+/**
+ * Whether a logical path segment is a relative-traversal marker (`.` or `..`). These survive
+ * `encodeURIComponent` (dots are unreserved) and so must be rejected explicitly to keep emitted
+ * URLs canonical and contained — mirrors the server resolver's segment validation as defense in
+ * depth.
+ */
+const isTraversalSegment = (segment) => segment === '.' || segment === '..';
+/**
+ * Build a canonical artifact URL for a logical artifact path.
+ *
+ * Each path segment is individually `encodeURIComponent`-encoded (so a slash separating logical
+ * segments is preserved while reserved characters within a segment are escaped), and the
+ * configured `basePath` is preserved ahead of the canonical route.
+ *
+ * @param artifactPath Logical artifact path, e.g. `component/badge-primary.html`.
+ * @param basePath Optional configured base path; normalized like the Next app's basePath.
+ * @returns A canonical `{basePath}/api/docs/artifacts/{encodedPath}` URL.
+ * @throws If `artifactPath` has no usable segments, or contains a `.`/`..` traversal segment.
+ */
+const buildArtifactUrl = (artifactPath, basePath) => {
+    const segments = toArtifactSegments(artifactPath);
+    if (segments.length === 0) {
+        throw new Error(`Cannot build artifact URL: empty artifact path "${artifactPath}".`);
+    }
+    if (segments.some(isTraversalSegment)) {
+        throw new Error(`Cannot build artifact URL: path traversal is not allowed in "${artifactPath}".`);
+    }
+    const encoded = segments.map((segment) => encodeURIComponent(segment)).join('/');
+    return `${(0, exports.normalizeBasePath)(basePath)}/${exports.ARTIFACTS_ROUTE_SEGMENT}/${encoded}`;
+};
+exports.buildArtifactUrl = buildArtifactUrl;
+/**
+ * Build the canonical docs read API URL for a component's detail metadata
+ * (`{basePath}/api/docs/components/{id}.json`). The id is URL-encoded; `basePath` is preserved.
+ * This is the single source of the metadata-read URL that the build records as an entity's `path`.
+ */
+const buildComponentDetailUrl = (id, basePath) => `${(0, exports.normalizeBasePath)(basePath)}/${exports.DOCS_ROUTE_SEGMENT}/components/${encodeURIComponent(id)}.json`;
+exports.buildComponentDetailUrl = buildComponentDetailUrl;
+/**
+ * Build the canonical docs read API URL for a pattern's detail metadata
+ * (`{basePath}/api/docs/patterns/{id}.json`). The id is URL-encoded; `basePath` is preserved.
+ */
+const buildPatternDetailUrl = (id, basePath) => `${(0, exports.normalizeBasePath)(basePath)}/${exports.DOCS_ROUTE_SEGMENT}/patterns/${encodeURIComponent(id)}.json`;
+exports.buildPatternDetailUrl = buildPatternDetailUrl;

package/dist/cache/build-cache.js

@@ -136,7 +136,7 @@ function haveGlobalDepsChanged(cached, current) {
  * Gets all file paths that should be tracked for a component
  */
 function getComponentFilePaths(handoff, componentId) {
-    var _a, _b, _c;
+    var _a, _b, _c, _d, _e, _f, _g;
     const runtimeComponent = (_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components) === null || _c === void 0 ? void 0 : _c[componentId];
     if (!runtimeComponent) {
         return { files: [] };
@@ -169,7 +169,7 @@ function getComponentFilePaths(handoff, componentId) {
                     componentDirs.add((0, path_2.normalizePathForCompare)(path_1.default.dirname(templatePath)));
                 }
             }
-            catch (_d) {
+            catch (_h) {
                 // File doesn't exist, still add to track
                 files.push(templatePath);
                 componentDirs.add((0, path_2.normalizePathForCompare)(path_1.default.dirname(templatePath)));
@@ -202,6 +202,24 @@ function getComponentFilePaths(handoff, componentId) {
     if (matchingConfigPath) {
         files.push(matchingConfigPath);
     }
+    // Include every pattern config file whose declaration references this component.
+    // When a pattern is added or modified, injectPatternPreviews injects new
+    // __pattern_* synthetic preview keys onto the referenced component, changing
+    // what processComponents must render. Without tracking these files here, the
+    // cache would incorrectly consider the component unchanged and skip the preview
+    // rebuild, leaving buildPatterns unable to find the required HTML fragments.
+    const runtimePatterns = (_f = (_e = (_d = handoff.runtimeConfig) === null || _d === void 0 ? void 0 : _d.entries) === null || _e === void 0 ? void 0 : _e.patterns) !== null && _f !== void 0 ? _f : {};
+    for (const configPath of configPaths) {
+        const entry = handoff.getConfigFileEntry(configPath);
+        if ((entry === null || entry === void 0 ? void 0 : entry.kind) !== 'pattern')
+            continue;
+        const pattern = runtimePatterns[entry.entityId];
+        if (!pattern)
+            continue;
+        if ((_g = pattern.components) === null || _g === void 0 ? void 0 : _g.some((ref) => ref.id === componentId)) {
+            files.push(configPath);
+        }
+    }
     return { files, templateDir };
 }
 /**
@@ -262,8 +280,34 @@ function hasComponentChanged(cached, current) {
  */
 function checkOutputExists(handoff, componentId) {
     return __awaiter(this, void 0, void 0, function* () {
-        const outputPath = path_1.default.resolve(handoff.workingPath, 'public/api/component', `${componentId}.json`);
-        return fs_extra_1.default.pathExists(outputPath);
+        var _a, _b, _c, _d, _e, _f;
+        const outputDirectory = path_1.default.resolve(handoff.workingPath, 'public/api/component');
+        const componentPath = path_1.default.resolve(outputDirectory, `${componentId}.json`);
+        if (!(yield fs_extra_1.default.pathExists(componentPath))) {
+            return false;
+        }
+        const runtimeComponent = (_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components) === null || _c === void 0 ? void 0 : _c[componentId];
+        const previewIds = new Set([
+            ...Object.keys((_d = runtimeComponent === null || runtimeComponent === void 0 ? void 0 : runtimeComponent.previews) !== null && _d !== void 0 ? _d : {}),
+            ...Object.keys((_e = runtimeComponent === null || runtimeComponent === void 0 ? void 0 : runtimeComponent.internalPatternPreviews) !== null && _e !== void 0 ? _e : {}),
+        ]);
+        try {
+            const component = yield fs_extra_1.default.readJson(componentPath);
+            for (const previewId of Object.keys((_f = component === null || component === void 0 ? void 0 : component.previews) !== null && _f !== void 0 ? _f : {})) {
+                previewIds.add(previewId);
+            }
+        }
+        catch (_g) {
+            return false;
+        }
+        for (const previewId of previewIds) {
+            const previewPath = path_1.default.resolve(outputDirectory, `${componentId}-${previewId}.html`);
+            const inspectPath = path_1.default.resolve(outputDirectory, `${componentId}-${previewId}-inspect.html`);
+            if (!(yield fs_extra_1.default.pathExists(previewPath)) || !(yield fs_extra_1.default.pathExists(inspectPath))) {
+                return false;
+            }
+        }
+        return true;
     });
 }
 /**

package/dist/commands/build/app.js

@@ -23,12 +23,11 @@ const command = {
             type: 'boolean',
             default: false,
         });
-        return (0, utils_1.getSharedOptions)(yargs);
     },
     handler: (args) => __awaiter(void 0, void 0, void 0, function* () {
         var _a;
         const handoff = new __1.default(args.debug, args.force);
-        yield handoff.build((_a = args.skipComponents) !== null && _a !== void 0 ? _a : false);
+        yield handoff.build('static', (_a = args.skipComponents) !== null && _a !== void 0 ? _a : false);
     }),
 };
 exports.default = command;

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

@@ -0,0 +1,17 @@
+import { CommandModule } from 'yargs';
+import { type BuildPackage, type BuildTarget } from '../../app-builder';
+import { SharedArgs } from '../types';
+export interface BuildArgs extends SharedArgs {
+    target?: BuildTarget;
+    package?: BuildPackage;
+    skipComponents?: boolean;
+}
+/**
+ * `handoff-app build [--target static|registry] [--package standalone|vercel]` — builds the
+ * documentation site for the resolved target and packages it for the resolved deliverable.
+ * `--target` selects *what* is built; the optional, additive `--package` selects *how* it is
+ * packaged. Bare `build` resolves to the static target with the `out/<projectId>` export;
+ * `--package` never implies a `--target`.
+ */
+declare const command: CommandModule<{}, BuildArgs>;
+export default command;

package/dist/commands/build/index.js

@@ -0,0 +1,66 @@
+"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 app_builder_1 = require("../../app-builder");
+const logger_1 = require("../../utils/logger");
+const utils_1 = require("../utils");
+const BUILD_TARGETS = ['static', 'registry'];
+const BUILD_PACKAGES = ['standalone', 'vercel'];
+/**
+ * `handoff-app build [--target static|registry] [--package standalone|vercel]` — builds the
+ * documentation site for the resolved target and packages it for the resolved deliverable.
+ * `--target` selects *what* is built; the optional, additive `--package` selects *how* it is
+ * packaged. Bare `build` resolves to the static target with the `out/<projectId>` export;
+ * `--package` never implies a `--target`.
+ */
+const command = {
+    command: 'build',
+    describe: 'Build the design system for the given target (default: static export)',
+    builder: (yargs) => {
+        return (0, utils_1.getSharedOptions)(yargs)
+            .option('target', {
+            describe: 'Build target (what is built)',
+            choices: BUILD_TARGETS,
+            default: app_builder_1.DEFAULT_BUILD_TARGET,
+        })
+            .option('package', {
+            describe: 'Packaging format (how it is delivered). Omit for the default per-target deliverable.',
+            choices: BUILD_PACKAGES,
+        })
+            .option('skip-components', {
+            describe: 'Skip building components before building the app',
+            type: 'boolean',
+            default: false,
+        });
+    },
+    handler: (args) => __awaiter(void 0, void 0, void 0, function* () {
+        var _a, _b;
+        const handoff = new __1.default(args.debug, args.force);
+        try {
+            yield handoff.build((_a = args.target) !== null && _a !== void 0 ? _a : app_builder_1.DEFAULT_BUILD_TARGET, (_b = args.skipComponents) !== null && _b !== void 0 ? _b : false, args.package);
+        }
+        catch (error) {
+            // Expected business/flow failures (invalid combinations, unsupported runtime modes) print as a
+            // single actionable line; unexpected errors re-throw so their stack trace is preserved.
+            if (error instanceof app_builder_1.HandoffBuildError) {
+                logger_1.Logger.error(error.message);
+                process.exitCode = 1;
+                return;
+            }
+            throw error;
+        }
+    }),
+};
+exports.default = command;

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

@@ -0,0 +1,24 @@
+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"];
+export interface CheckoutArgs extends SharedArgs {
+    type: (typeof ENTITY_KINDS)[number];
+    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 tokens [setId]` — pull every published token set (or only the named set) into
+ * this workspace: reconstruct `tokens.json` and restore the generated token files.
+ *
+ * `handoff-app checkout assets [collection]` pulls every published asset collection (or only the
+ * named one) into this workspace, recreating the standard asset files, sprite/manifest, and archives.
+ * Available only from a connected workspace (`runtime.mode: workspace` + a configured
+ * `registryConnection`). Overwriting existing local files requires `--force` or an interactive
+ * confirmation.
+ */
+declare const command: CommandModule<{}, CheckoutArgs>;
+export default command;

package/dist/commands/checkout/index.js

@@ -0,0 +1,71 @@
+"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 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 tokens [setId]` — pull every published token set (or only the named set) into
+ * this workspace: reconstruct `tokens.json` and restore the generated token files.
+ *
+ * `handoff-app checkout assets [collection]` pulls every published asset collection (or only the
+ * named one) into this workspace, recreating the standard asset files, sprite/manifest, and archives.
+ * Available only from a connected workspace (`runtime.mode: workspace` + a configured
+ * `registryConnection`). Overwriting existing local files requires `--force` or an interactive
+ * confirmation.
+ */
+const command = {
+    command: 'checkout <type> [id]',
+    describe: 'Pull a component, pattern, page, 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,
+            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',
+            type: 'string',
+        });
+    },
+    handler: (args) => __awaiter(void 0, void 0, void 0, function* () {
+        const handoff = new __1.default(args.debug, args.force);
+        try {
+            if (args.type === 'tokens') {
+                yield handoff.checkoutTokens(args.id);
+                return;
+            }
+            if (args.type === 'assets') {
+                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);
+        }
+        catch (error) {
+            logger_1.Logger.error(error instanceof Error ? error.message : String(error));
+            process.exitCode = 1;
+        }
+    }),
+};
+exports.default = command;

package/dist/commands/db/migrate.d.ts

@@ -0,0 +1,11 @@
+import { CommandModule } from 'yargs';
+import { SharedArgs } from '../types';
+export interface DbMigrateArgs extends SharedArgs {
+}
+/**
+ * `handoff-app db:migrate` — runs the package-owned registry database migrations against the
+ * configured PostgreSQL/Neon database. Reads the consuming project's config + DB env vars and runs
+ * independently of `build`.
+ */
+declare const command: CommandModule<{}, DbMigrateArgs>;
+export default command;

package/dist/commands/db/migrate.js

@@ -0,0 +1,33 @@
+"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 utils_1 = require("../utils");
+/**
+ * `handoff-app db:migrate` — runs the package-owned registry database migrations against the
+ * configured PostgreSQL/Neon database. Reads the consuming project's config + DB env vars and runs
+ * independently of `build`.
+ */
+const command = {
+    command: 'db:migrate',
+    describe: 'Run registry database migrations (Drizzle / PostgreSQL)',
+    builder: (yargs) => {
+        return (0, utils_1.getSharedOptions)(yargs);
+    },
+    handler: (args) => __awaiter(void 0, void 0, void 0, function* () {
+        const handoff = new __1.default(args.debug, args.force);
+        yield handoff.dbMigrate();
+    }),
+};
+exports.default = command;

package/dist/commands/index.js

@@ -4,8 +4,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.commands = void 0;
+const build_1 = __importDefault(require("./build"));
 const app_1 = __importDefault(require("./build/app"));
 const components_1 = __importDefault(require("./build/components"));
+const checkout_1 = __importDefault(require("./checkout"));
+const migrate_1 = __importDefault(require("./db/migrate"));
 const dev_1 = __importDefault(require("./dev"));
 const config_1 = __importDefault(require("./eject/config"));
 const pages_1 = __importDefault(require("./eject/pages"));
@@ -15,12 +18,16 @@ const init_1 = __importDefault(require("./init"));
 const component_1 = __importDefault(require("./make/component"));
 const page_1 = __importDefault(require("./make/page"));
 const template_1 = __importDefault(require("./make/template"));
+const publish_1 = __importDefault(require("./publish"));
 const scaffold_1 = __importDefault(require("./scaffold"));
 const start_1 = __importDefault(require("./start"));
 const components_2 = __importDefault(require("./validate/components"));
 exports.commands = [
+    build_1.default,
     app_1.default,
     components_1.default,
+    checkout_1.default,
+    migrate_1.default,
     dev_1.default,
     config_1.default,
     pages_1.default,
@@ -30,6 +37,7 @@ exports.commands = [
     page_1.default,
     component_1.default,
     template_1.default,
+    publish_1.default,
     scaffold_1.default,
     start_1.default,
     components_2.default,