handoff-app 1.2.2-7 → 2.0.0-1

package/src/artifacts/types.ts

@@ -0,0 +1,146 @@
+/**
+ * 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 const SHARED_MAIN_CSS_ARTIFACT_PATH = 'component/main.css';
+/** Logical path of the shared global script artifact. */
+export const SHARED_MAIN_JS_ARTIFACT_PATH = 'component/main.js';
+/** Logical path of the shared component styles artifact. */
+export const SHARED_STYLES_CSS_ARTIFACT_PATH = 'component/shared.css';
+
+/** Logical path of the per-build artifact metadata manifest. */
+export const ARTIFACT_METADATA_PATH = 'artifact-metadata.json';
+/** Format version tag carried by generated React preview/inspect HTML. */
+export const REACT_PREVIEW_FORMAT_VERSION = 'handoff-react-preview-v1';

package/src/artifacts/url.ts

@@ -0,0 +1,122 @@
+/**
+ * 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 const ARTIFACTS_ROUTE_SEGMENT = 'api/docs/artifacts';
+
+/** Route prefix for docs read API metadata (`.json`) reads. */
+export const DOCS_ROUTE_SEGMENT = 'api/docs';
+
+/** Canonical route prefix all asset content URLs are served under (mode-independent). */
+export const ASSETS_ROUTE_SEGMENT = 'api/docs/assets';
+
+/**
+ * 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 const normalizeBasePath = (basePath?: string | null): string => {
+  if (!basePath) {
+    return '';
+  }
+  const trimmed = basePath.replace(/^\/+|\/+$/g, '');
+  return trimmed ? `/${trimmed}` : '';
+};
+
+/**
+ * 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: string): string[] =>
+  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: string): boolean => 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.
+ */
+export const buildArtifactUrl = (artifactPath: string, basePath?: string | null): string => {
+  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 `${normalizeBasePath(basePath)}/${ARTIFACTS_ROUTE_SEGMENT}/${encoded}`;
+};
+
+/**
+ * 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 const buildComponentDetailUrl = (id: string, basePath?: string | null): string =>
+  `${normalizeBasePath(basePath)}/${DOCS_ROUTE_SEGMENT}/components/${encodeURIComponent(id)}.json`;
+
+/**
+ * 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 const buildPatternDetailUrl = (id: string, basePath?: string | null): string =>
+  `${normalizeBasePath(basePath)}/${DOCS_ROUTE_SEGMENT}/patterns/${encodeURIComponent(id)}.json`;
+
+/**
+ * Build the canonical, basePath-aware content URL for one asset within a collection
+ * (`{basePath}/api/docs/assets/{collection}/{logicalPath}`). This is the same route the docs read API
+ * serves in every runtime mode: from the database in registry mode, and from statically materialized
+ * files in a static export. Each segment is individually encoded and traversal segments are rejected,
+ * mirroring {@link buildArtifactUrl}.
+ *
+ * @throws If the collection or logical path has no usable segments, or contains a `.`/`..` segment.
+ */
+export const buildAssetUrl = (collection: string, logicalPath: string, basePath?: string | null): string => {
+  const segments = [...toArtifactSegments(collection), ...toArtifactSegments(logicalPath)];
+  if (segments.length < 2) {
+    throw new Error(`Cannot build asset URL: empty collection ("${collection}") or path ("${logicalPath}").`);
+  }
+  if (segments.some(isTraversalSegment)) {
+    throw new Error(`Cannot build asset URL: path traversal is not allowed in "${collection}/${logicalPath}".`);
+  }
+  const encoded = segments.map((segment) => encodeURIComponent(segment)).join('/');
+  return `${normalizeBasePath(basePath)}/${ASSETS_ROUTE_SEGMENT}/${encoded}`;
+};
+
+/**
+ * Build the canonical download URL for a collection's whole-collection zip bundle
+ * (`{basePath}/api/docs/assets/{collection}/{collection}.zip`) — the default target for the docs
+ * "Download" links, overridable via `assets_zip_links`.
+ */
+export const buildAssetDownloadUrl = (collection: string, basePath?: string | null): string =>
+  buildAssetUrl(collection, `${collection}.zip`, basePath);

package/src/cache/build-cache.ts

@@ -226,6 +226,23 @@ export function getComponentFilePaths(handoff: Handoff, componentId: string): {
     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 = handoff.runtimeConfig?.entries?.patterns ?? {};
+  for (const configPath of configPaths) {
+    const entry = handoff.getConfigFileEntry(configPath);
+    if (entry?.kind !== 'pattern') continue;
+    const pattern = runtimePatterns[entry.entityId];
+    if (!pattern) continue;
+    if (pattern.components?.some((ref) => ref.id === componentId)) {
+      files.push(configPath);
+    }
+  }
+
   return { files, templateDir };
 }
 
@@ -302,8 +319,36 @@ export function hasComponentChanged(
  * Checks if the component output files exist
  */
 export async function checkOutputExists(handoff: Handoff, componentId: string): Promise<boolean> {
-  const outputPath = path.resolve(handoff.workingPath, 'public/api/component', `${componentId}.json`);
-  return fs.pathExists(outputPath);
+  const outputDirectory = path.resolve(handoff.workingPath, 'public/api/component');
+  const componentPath = path.resolve(outputDirectory, `${componentId}.json`);
+  if (!(await fs.pathExists(componentPath))) {
+    return false;
+  }
+
+  const runtimeComponent = handoff.runtimeConfig?.entries?.components?.[componentId];
+  const previewIds = new Set([
+    ...Object.keys(runtimeComponent?.previews ?? {}),
+    ...Object.keys(runtimeComponent?.internalPatternPreviews ?? {}),
+  ]);
+
+  try {
+    const component = await fs.readJson(componentPath);
+    for (const previewId of Object.keys(component?.previews ?? {})) {
+      previewIds.add(previewId);
+    }
+  } catch {
+    return false;
+  }
+
+  for (const previewId of previewIds) {
+    const previewPath = path.resolve(outputDirectory, `${componentId}-${previewId}.html`);
+    const inspectPath = path.resolve(outputDirectory, `${componentId}-${previewId}-inspect.html`);
+    if (!(await fs.pathExists(previewPath)) || !(await fs.pathExists(inspectPath))) {
+      return false;
+    }
+  }
+
+  return true;
 }
 
 /**

package/src/commands/build/app.ts

@@ -16,11 +16,10 @@ const command: CommandModule<{}, BuildAppArgs> = {
       type: 'boolean',
       default: false,
     });
-    return getSharedOptions(yargs);
   },
   handler: async (args: BuildAppArgs) => {
     const handoff = new Handoff(args.debug, args.force);
-    await handoff.build(args.skipComponents ?? false);
+    await handoff.build('static', args.skipComponents ?? false);
   },
 };
 

package/src/commands/build/index.ts

@@ -0,0 +1,61 @@
+import { CommandModule } from 'yargs';
+import Handoff from '../../';
+import { DEFAULT_BUILD_TARGET, HandoffBuildError, type BuildPackage, type BuildTarget } from '../../app-builder';
+import { Logger } from '../../utils/logger';
+import { SharedArgs } from '../types';
+import { getSharedOptions } from '../utils';
+
+const BUILD_TARGETS: BuildTarget[] = ['static', 'registry'];
+const BUILD_PACKAGES: BuildPackage[] = ['standalone', 'vercel'];
+
+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`.
+ */
+const command: CommandModule<{}, BuildArgs> = {
+  command: 'build',
+  describe: 'Build the design system for the given target (default: static export)',
+  builder: (yargs) => {
+    return getSharedOptions(yargs)
+      .option('target', {
+        describe: 'Build target (what is built)',
+        choices: BUILD_TARGETS,
+        default: 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: async (args: BuildArgs) => {
+    const handoff = new Handoff(args.debug, args.force);
+    try {
+      await handoff.build(args.target ?? DEFAULT_BUILD_TARGET, args.skipComponents ?? 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 HandoffBuildError) {
+        Logger.error(error.message);
+        process.exitCode = 1;
+        return;
+      }
+      throw error;
+    }
+  },
+};
+
+export default command;

package/src/commands/checkout/index.ts

@@ -0,0 +1,66 @@
+import { CommandModule } from 'yargs';
+import Handoff from '../../';
+import { Logger } from '../../utils/logger';
+import { SharedArgs } from '../types';
+import { getSharedOptions } from '../utils';
+
+/** Entity kinds checkout-able from a connected workspace. */
+const ENTITY_KINDS = ['component', 'pattern', 'page', 'tokens', 'assets'] as const;
+
+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.
+ */
+const command: CommandModule<{}, CheckoutArgs> = {
+  command: 'checkout <type> [id]',
+  describe: 'Pull a component, pattern, page, design tokens, or assets from the connected registry into this workspace',
+  builder: (yargs) => {
+    return 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: async (args: CheckoutArgs) => {
+    const handoff = new Handoff(args.debug, args.force);
+    try {
+      if (args.type === 'tokens') {
+        await handoff.checkoutTokens(args.id);
+        return;
+      }
+      if (args.type === 'assets') {
+        await 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>").`);
+      }
+      await handoff.checkout(args.type, args.id);
+    } catch (error) {
+      Logger.error(error instanceof Error ? error.message : String(error));
+      process.exitCode = 1;
+    }
+  },
+};
+
+export default command;

package/src/commands/db/migrate.ts

@@ -0,0 +1,25 @@
+import { CommandModule } from 'yargs';
+import Handoff from '../../';
+import { SharedArgs } from '../types';
+import { getSharedOptions } from '../utils';
+
+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`.
+ */
+const command: CommandModule<{}, DbMigrateArgs> = {
+  command: 'db:migrate',
+  describe: 'Run registry database migrations (Drizzle / PostgreSQL)',
+  builder: (yargs) => {
+    return getSharedOptions(yargs);
+  },
+  handler: async (args: DbMigrateArgs) => {
+    const handoff = new Handoff(args.debug, args.force);
+    await handoff.dbMigrate();
+  },
+};
+
+export default command;

package/src/commands/index.ts

@@ -1,5 +1,8 @@
+import buildCommand from './build';
 import buildAppCommand from './build/app';
 import buildComponentsCommand from './build/components';
+import checkoutCommand from './checkout';
+import dbMigrateCommand from './db/migrate';
 import devCommand from './dev';
 import ejectConfigCommand from './eject/config';
 import ejectPagesCommand from './eject/pages';
@@ -9,13 +12,17 @@ import initCommand from './init';
 import makeComponentCommand from './make/component';
 import makePageCommand from './make/page';
 import makeTemplateCommand from './make/template';
+import publishCommand from './publish';
 import scaffoldCommand from './scaffold';
 import startCommand from './start';
 import validateComponentsCommand from './validate/components';
 
 export const commands = [
+  buildCommand,
   buildAppCommand,
   buildComponentsCommand,
+  checkoutCommand,
+  dbMigrateCommand,
   devCommand,
   ejectConfigCommand,
   ejectPagesCommand,
@@ -25,6 +32,7 @@ export const commands = [
   makePageCommand,
   makeComponentCommand,
   makeTemplateCommand,
+  publishCommand,
   scaffoldCommand,
   startCommand,
   validateComponentsCommand,

package/src/commands/publish/index.ts

@@ -0,0 +1,63 @@
+import { CommandModule } from 'yargs';
+import Handoff from '../../';
+import { Logger } from '../../utils/logger';
+import { SharedArgs } from '../types';
+import { getSharedOptions } from '../utils';
+
+/** Entity kinds publishable from a connected workspace. */
+const ENTITY_KINDS = ['component', 'pattern', 'page', 'tokens', 'assets'] as const;
+
+export interface PublishArgs extends SharedArgs {
+  type: (typeof ENTITY_KINDS)[number];
+  id?: string;
+}
+
+/**
+ * `handoff-app publish <component|pattern|page> <id>` — fresh targeted local build + upload of the
+ * selected entity to the connected registry.
+ *
+ * `handoff-app publish tokens [setId]` — fresh token build + upload of every logical token set, or
+ * only the named set (`foundation/colors`, `component/button`).
+ *
+ * `handoff-app publish assets [collection]` runs a fresh build and uploads every asset collection, or
+ * only the named one (`icons`, `logos`, `fonts`). Available only from a connected workspace
+ * (`runtime.mode: workspace` + a configured `registryConnection`).
+ */
+const command: CommandModule<{}, PublishArgs> = {
+  command: 'publish <type> [id]',
+  describe: 'Build and publish a component, pattern, page, design tokens, or assets to the connected registry',
+  builder: (yargs) => {
+    return getSharedOptions(yargs)
+      .positional('type', {
+        describe: 'The kind of entity to publish',
+        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: async (args: PublishArgs) => {
+    const handoff = new Handoff(args.debug, args.force);
+    try {
+      if (args.type === 'tokens') {
+        await handoff.publishTokens(args.id);
+        return;
+      }
+      if (args.type === 'assets') {
+        await handoff.publishAssets(args.id);
+        return;
+      }
+      if (!args.id) {
+        throw new Error(`An id is required to publish a ${args.type} (e.g. "handoff-app publish ${args.type} <id>").`);
+      }
+      await handoff.publish(args.type, args.id);
+    } catch (error) {
+      Logger.error(error instanceof Error ? error.message : String(error));
+      process.exitCode = 1;
+    }
+  },
+};
+
+export default command;

package/src/config/defaults.ts

@@ -1,3 +1,4 @@
+import { resolveRegistryConnection } from '../registry/connection';
 import { ClientConfig, Config } from '../types/config';
 
 export interface ImageStyle {
@@ -11,6 +12,9 @@ export interface ImageStyle {
 export const defaultConfig = (): Config => ({
   dev_access_token: process.env.HANDOFF_DEV_ACCESS_TOKEN ?? null,
   figma_project_id: process.env.HANDOFF_FIGMA_PROJECT_ID ?? null,
+  runtime: {
+    mode: 'workspace',
+  },
   exportsOutputDirectory: process.env.HANDOFF_OUTPUT_DIR ?? 'exported',
   sitesOutputDirectory: process.env.HANDOFF_SITES_DIR ?? 'out',
   useVariables: process.env.HANDOFF_USE_VARIABLES === 'true',
@@ -66,13 +70,24 @@ export const getClientConfig = (config: Config): ClientConfig => {
     sitesOutputDirectory,
     assets_zip_links = { icons: null, logos: null },
     useVariables,
+    runtime,
   } = { ...defaultConfig(), ...config };
 
+  const mode = runtime?.mode ?? 'workspace';
+  // Connected-workspace affordance: only a workspace with a resolvable registry URL is "connected".
+  // URL-only threshold (no token required) so the publish hint surfaces before the access token is
+  // set. Never project the URL/token value itself — only this boolean crosses to the browser.
+  const connected = mode === 'workspace' && Boolean(resolveRegistryConnection(config).url);
+
   return {
     app,
     exportsOutputDirectory,
     sitesOutputDirectory,
     assets_zip_links,
     useVariables,
+    runtime: {
+      mode,
+      connected,
+    },
   };
 };

package/src/config/loader.ts

@@ -1,5 +1,6 @@
 import esbuild from 'esbuild';
 import fs from 'fs-extra';
+import merge from 'lodash/merge';
 import { createRequire } from 'module';
 import path from 'path';
 import { Config } from '../types/config';
@@ -109,7 +110,15 @@ export const initConfigWithMetadata = (configOverride?: Partial<Config>): Config
     });
   }
 
-  const resolvedConfig = { ...defaultConfig(), ...config } as Config;
+  const defaults = defaultConfig();
+  // Top-level merge stays shallow to preserve 1.x semantics, except for the `runtime`
+  // block which is deep-merged so a partial user `runtime` (e.g. only `mode`) does not
+  // wipe the defaults supplied for the rest of the block.
+  const resolvedConfig = {
+    ...defaults,
+    ...config,
+    runtime: merge({}, defaults.runtime, config.runtime),
+  } as Config;
   return { config: resolvedConfig, configPath };
 };
 

package/src/config/normalizers/declaration.ts

@@ -172,5 +172,8 @@ export const normalizeComponentDeclaration = (raw: RawDeclaration, options: Norm
     renderer: resolvedRenderer,
     entries,
     previews: normalizedPreviews,
+    // Source location of the entity (declaration directory), retained so the store can expose a
+    // stable source reference for checkout/publish.
+    path: path.dirname(options.declarationPath),
   };
 };