handoff-app 2.0.0-0 → 2.0.0-2

package/src/registry/db/migrate.ts

@@ -2,7 +2,7 @@
  * Registry migration runner.
  *
  * `handoff-app db:migrate` reads the consuming project's config + DB env vars, resolves the same
- * `runtime.registry.database.adapter` used at runtime/build, and applies the package-owned
+ * `runtime.registry.database.driver` used at runtime/build, and applies the package-owned
  * migration set with the bundled Drizzle migrator. Migrations are resolved relative to the
  * installed package (not the consuming project), so the schema is versioned with the tool. This
  * runs independently of `build`.
@@ -12,7 +12,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import type Handoff from '../../';
 import { Logger } from '../../utils/logger';
-import { resolveRegistryDatabase } from './adapter';
+import { resolveRegistryDatabase } from './driver';
 import { createRegistryDbConnection } from './client';
 
 /**
@@ -33,7 +33,7 @@ export const runRegistryMigrations = async (handoff: Handoff): Promise<void> =>
     throw new Error('Handoff is not initialized; cannot resolve registry database configuration.');
   }
 
-  const { adapter, databaseUrlEnv, connectionString } = resolveRegistryDatabase(handoff.config);
+  const { driver, databaseUrlEnv, connectionString } = resolveRegistryDatabase(handoff.config);
 
   const migrationsFolder = getMigrationsFolder(handoff);
   const journalPath = path.join(migrationsFolder, 'meta', '_journal.json');
@@ -44,9 +44,9 @@ export const runRegistryMigrations = async (handoff: Handoff): Promise<void> =>
     );
   }
 
-  Logger.info(`Running registry migrations (adapter: "${adapter}", database url from "${databaseUrlEnv}").`);
+  Logger.info(`Running registry migrations (driver: "${driver}", database url from "${databaseUrlEnv}").`);
 
-  const connection = await createRegistryDbConnection({ adapter, connectionString });
+  const connection = await createRegistryDbConnection({ driver, connectionString });
   try {
     await connection.migrate(migrationsFolder);
     Logger.success('Registry migrations applied successfully.');

package/src/registry/publish/index.ts

@@ -1,7 +1,7 @@
 /**
  * Connected-workspace publish orchestration.
  *
- * `publish <component|pattern|page> <id>` prepares one entity and uploads its record, source files,
+ * `publish <components|patterns|pages> <id>` prepares one entity and uploads its record, source files,
  * applicable rendered artifacts, and build metadata through the shared registry client.
  *
  * The build is targeted: a component builds the global artifacts + that component; a pattern builds
@@ -17,7 +17,7 @@ import { processPatterns } from '../../transformers/preview/pattern/builder';
 import { Logger } from '../../utils/logger';
 import { createRegistryClient, RegistryClientError } from '../client';
 import { resolveRegistryConnection } from '../connection';
-import type { TransferEntityKind } from '../transfer';
+import type { EntitySummary, TransferEntityKind } from '../transfer';
 import { describeUploadFailure } from './errors';
 import { assertRequiredArtifactsPresent, buildPublishPackage, PublishPackageError } from './package';
 
@@ -126,3 +126,101 @@ export const publishEntity = async (handoff: Handoff, kind: TransferEntityKind,
 
   Logger.success(`Published ${kind} "${id}" to the registry.`);
 };
+
+/** The published-content hash a bulk publish compares for skip-unchanged (artifact for rendered kinds, source for pages). */
+const entityHash = (value: { artifactHash?: string; sourceHash?: string }): string | undefined => value.artifactHash ?? value.sourceHash;
+
+/**
+ * Run one build covering every entity of the kind, so a bulk publish builds once instead of per id.
+ * Pages carry no rendered artifacts. Components need the global artifacts + all components; patterns
+ * additionally need all patterns composed (each references pre-built component HTML).
+ */
+const runBulkBuild = async (handoff: Handoff, kind: TransferEntityKind): Promise<void> => {
+  if (kind === 'page') {
+    return;
+  }
+  await buildMainJS(handoff);
+  await buildMainCss(handoff);
+  await processComponents(handoff);
+  if (kind === 'pattern') {
+    await processPatterns(handoff);
+  }
+};
+
+/** List every declared entity id of the kind from the workspace store. */
+const listWorkspaceEntityIds = async (handoff: Handoff, kind: TransferEntityKind): Promise<string[]> => {
+  const store = kind === 'component' ? handoff.store.components : kind === 'pattern' ? handoff.store.patterns : handoff.store.pages;
+  return (await store.list()).map((entity) => entity.id);
+};
+
+/**
+ * Publish every component, pattern, or page declared in this connected workspace. Builds the kind
+ * once, assembles each entity's package, skips entities whose content hash already matches the
+ * registry (unless `--force`), and reports published/unchanged/failed counts. A per-entity failure is
+ * collected and never aborts the rest; the run throws at the end if any entity failed.
+ */
+export const publishEntities = async (handoff: Handoff, kind: TransferEntityKind): Promise<void> => {
+  const connection = resolveConnectionOrThrow(handoff);
+
+  Logger.info(`Building ${kind}s for publish…`);
+  await runBulkBuild(handoff, kind);
+
+  const ids = await listWorkspaceEntityIds(handoff, kind);
+  if (ids.length === 0) {
+    Logger.success(`No ${kind}s are declared in this workspace; nothing to publish.`);
+    return;
+  }
+
+  const client = createRegistryClient({ baseUrl: connection.url, accessToken: connection.accessToken });
+  let remote: EntitySummary[] = [];
+  if (!handoff.force) {
+    try {
+      remote = await client.listEntities(kind);
+    } catch {
+      // If the summary listing fails we simply publish everything (the server still overwrites in place).
+      Logger.info(`Could not read current registry ${kind}s; publishing all.`);
+    }
+  }
+  const remoteHashById = new Map(remote.map((entry) => [entry.id, entityHash(entry)]));
+
+  let published = 0;
+  let unchanged = 0;
+  const failed: { id: string; message: string }[] = [];
+
+  for (const id of ids) {
+    try {
+      const pkg = await buildPublishPackage(handoff, kind, id);
+      assertRequiredArtifactsPresent(pkg);
+
+      const remoteHash = remoteHashById.get(id);
+      const localHash = entityHash(pkg.build);
+      if (!handoff.force && remoteHash && localHash && remoteHash === localHash) {
+        unchanged += 1;
+        Logger.info(`Unchanged: ${id}`);
+        continue;
+      }
+
+      await client.publish(kind, id, pkg);
+      published += 1;
+      Logger.info(`Published: ${id} (${pkg.artifacts.length} artifact(s), ${pkg.files.length} source file(s))`);
+    } catch (error) {
+      const message =
+        error instanceof RegistryClientError
+          ? describeUploadFailure(error, connection.url, 'package')
+          : error instanceof Error
+            ? error.message
+            : String(error);
+      failed.push({ id, message });
+    }
+  }
+
+  Logger.success(
+    `${kind[0].toUpperCase()}${kind.slice(1)}s publish complete — ${published} published, ${unchanged} unchanged${failed.length ? `, ${failed.length} failed` : ''}.`
+  );
+  if (failed.length > 0) {
+    for (const failure of failed) {
+      Logger.error(`  - ${failure.id}: ${failure.message}`);
+    }
+    throw new PublishError(`${failed.length} ${kind}(s) failed to publish.`);
+  }
+};

package/src/registry/transfer.ts

@@ -80,3 +80,17 @@ export interface CheckoutPayload {
   item: Record<string, unknown>;
   files: TransferFile[];
 }
+
+/**
+ * A published entity's summary from `GET /api/registry/transfer/{component|pattern|page}`. Carries
+ * the build hashes so a connected workspace can skip unchanged entities on a bulk publish and
+ * enumerate published ids for a bulk checkout. Components/patterns key on `artifactHash`; pages key
+ * on `sourceHash`.
+ */
+export interface EntitySummary {
+  id: string;
+  kind: TransferEntityKind;
+  status?: string;
+  artifactHash?: string;
+  sourceHash?: string;
+}

package/src/types/config.ts

@@ -138,8 +138,12 @@ export interface HandoffRuntimeConfig {
     /** Name of the env var holding the registry API token. @default "HANDOFF_REGISTRY_API_TOKEN" */
     apiTokenEnv?: string;
     database?: {
-      /** @default "pg" */
-      adapter?: 'pg' | 'neon';
+      /**
+       * PostgreSQL is the supported database. `driver` selects the built-in connection driver — how
+       * to connect, not which engine — over the same package-owned Postgres schema and migrations.
+       * @default "pg"
+       */
+      driver?: 'pg' | 'neon';
     };
     /**
      * Where published asset blobs (icons/logos/fonts/sprites/archives) are stored. Defaults to the
@@ -214,18 +218,18 @@ export interface Config {
    */
   entries?: ConfigEntries;
   /**
-   * Configuration for asset zip file download links
-   * @default { icons: "/icons.zip", logos: "/logos.zip" }
+   * Override URLs for the asset zip download links. When unset, each link defaults to the
+   * basePath-aware asset route `{basePath}/api/docs/assets/{collection}/{collection}.zip`, served by
+   * the docs read API in every runtime mode (from the DB in registry mode, from statically
+   * materialized files in a static export).
    */
   assets_zip_links?: {
     /**
-     * Path to the icons zip file
-     * @default "/icons.zip"
+     * Override URL for the icons zip. Defaults to `/api/docs/assets/icons/icons.zip` (basePath-aware).
      */
     icons?: string;
     /**
-     * Path to the logos zip file
-     * @default "/logos.zip"
+     * Override URL for the logos zip. Defaults to `/api/docs/assets/logos/logos.zip` (basePath-aware).
      */
     logos?: string;
   };

package/templates/default/README.md.tpl

@@ -12,4 +12,43 @@ A design system documentation site powered by Handoff App.
 
 - `npm run fetch` - Fetch design data from Figma
 - `npm run start` - Start the documentation server
-- `npm run build` - Build for production
+- `npm run dev` - Start the server in watch mode
+- `npm run build` - Build the documentation site
+- `npm run db:migrate` - Apply registry database migrations
+
+## Deploying
+
+Handoff builds two deployment shapes:
+
+- **Static** — plain files served by any static file server or CDN. Build with
+  `handoff-app build --target static`. The simplest to deploy and run.
+- **Registry** — a live, database-backed Node app that serves a shared catalog.
+  Build with `handoff-app build --target registry`, run it on any Node host, and
+  provide a Postgres `DATABASE_URL`. The more capable, actively evolving option,
+  and the recommended path for a design system you plan to grow.
+
+Add `--package vercel` to either build to produce a `.vercel/output` bundle. If
+you scaffolded a `vercel.json`, it runs the build for the deployment you chose;
+edit its `buildCommand` to switch.
+
+## Registry mode
+
+New projects run in **workspace mode**, which needs no database and is the default
+for building and iterating locally. The database-backed **registry mode** lets you
+publish and share a design system across projects and is where Handoff's
+capabilities are expanding, so it's the recommended path as your design system
+grows. See the Handoff docs for setting up the database and publishing.
+
+### Database migrations
+
+A registry deployment stores its catalog in Postgres, so its schema has to be
+migrated before you deploy new code. Run this against the target database:
+
+```bash
+npm run db:migrate
+```
+
+It reads `DATABASE_URL` from the environment and applies the migrations bundled
+with Handoff. It runs on its own, separate from build and start, so use it as a
+release step (for example in CI/CD). Static deployments don't use a database and
+can skip it.

package/templates/default/gitignore.tpl

@@ -1,7 +1,22 @@
+# Dependencies
 node_modules/
-.env
+
+# Build output
 dist/
-.next/
 out/
-.DS_Store
+.next/
+
+# Generated build artifacts
+public/api
+
+# Environment
+.env
+
+# Deployment
+.vercel
+
+# Logs
 *.log
+
+# OS files
+.DS_Store

package/templates/default/handoff.config.js.tpl

@@ -61,6 +61,20 @@ const config = {
   //   patterns: ["patterns"],
   // },
 
+  // Registry deployment settings, used by `build --target registry` and `db:migrate`.
+  // These are only needed when publishing to a hosted registry. The default workspace mode
+  // doesn't use a database, so these should stay commented out unless deploying one.
+  // Handoff runs on PostgreSQL, and `driver` just picks the connection driver to use, not
+  // the database engine. Secrets are referenced by env var name and never written here.
+  // runtime: {
+  //   mode: "registry",
+  //   registry: {
+  //     databaseUrlEnv: "DATABASE_URL",
+  //     apiTokenEnv: "HANDOFF_REGISTRY_API_TOKEN",
+  //     database: { driver: "pg" }, // 'pg' | 'neon'
+  //   },
+  // },
+
   // Optional handoff-docgen settings used by component docs generation
   // reactDocgen: {
   //   maxDepth: 7,

package/templates/default/handoff.config.ts.tpl

@@ -59,6 +59,20 @@ export default defineConfig({
   //   patterns: ["patterns"],
   // },
 
+  // Registry deployment settings, used by `build --target registry` and `db:migrate`.
+  // These are only needed when publishing to a hosted registry. The default workspace mode
+  // doesn't use a database, so these should stay commented out unless deploying one.
+  // Handoff runs on PostgreSQL, and `driver` just picks the connection driver to use, not
+  // the database engine. Secrets are referenced by env var name and never written here.
+  // runtime: {
+  //   mode: "registry",
+  //   registry: {
+  //     databaseUrlEnv: "DATABASE_URL",
+  //     apiTokenEnv: "HANDOFF_REGISTRY_API_TOKEN",
+  //     database: { driver: "pg" }, // 'pg' | 'neon'
+  //   },
+  // },
+
   // Optional handoff-docgen settings used by component docs generation
   // reactDocgen: {
   //   maxDepth: 7,

package/templates/default/handoff.config.with-examples.js.tpl

@@ -60,6 +60,20 @@ const config = {
     // patterns: [],
   },
 
+  // Registry deployment settings, used by `build --target registry` and `db:migrate`.
+  // These are only needed when publishing to a hosted registry. The default workspace mode
+  // doesn't use a database, so these should stay commented out unless deploying one.
+  // Handoff runs on PostgreSQL, and `driver` just picks the connection driver to use, not
+  // the database engine. Secrets are referenced by env var name and never written here.
+  // runtime: {
+  //   mode: "registry",
+  //   registry: {
+  //     databaseUrlEnv: "DATABASE_URL",
+  //     apiTokenEnv: "HANDOFF_REGISTRY_API_TOKEN",
+  //     database: { driver: "pg" }, // 'pg' | 'neon'
+  //   },
+  // },
+
   // Optional handoff-docgen settings used by component docs generation
   // reactDocgen: {
   //   maxDepth: 7,

package/templates/default/handoff.config.with-examples.ts.tpl

@@ -58,6 +58,20 @@ export default defineConfig({
     // patterns: [],
   },
 
+  // Registry deployment settings, used by `build --target registry` and `db:migrate`.
+  // These are only needed when publishing to a hosted registry. The default workspace mode
+  // doesn't use a database, so these should stay commented out unless deploying one.
+  // Handoff runs on PostgreSQL, and `driver` just picks the connection driver to use, not
+  // the database engine. Secrets are referenced by env var name and never written here.
+  // runtime: {
+  //   mode: "registry",
+  //   registry: {
+  //     databaseUrlEnv: "DATABASE_URL",
+  //     apiTokenEnv: "HANDOFF_REGISTRY_API_TOKEN",
+  //     database: { driver: "pg" }, // 'pg' | 'neon'
+  //   },
+  // },
+
   // Optional handoff-docgen settings used by component docs generation
   // reactDocgen: {
   //   maxDepth: 7,

package/templates/default/package.json.tpl

@@ -6,8 +6,9 @@
   "scripts": {
     "start": "handoff-app start",
     "dev": "handoff-app dev",
+    "fetch": "handoff-app fetch",
     "build": "handoff-app build",
-    "fetch": "handoff-app fetch"
+    "db:migrate": "handoff-app db:migrate"
   },
   "dependencies": {},
   "devDependencies": {},

package/templates/default/vercel.json.tpl

@@ -0,0 +1,4 @@
+{
+  "framework": null,
+  "buildCommand": "{{vercelBuildCommand}}"
+}