handoff-app 1.2.2-7 → 2.0.0-1

package/src/registry/publish/tokens.ts

@@ -0,0 +1,119 @@
+/**
+ * Connected-workspace token publish orchestration.
+ *
+ * `publish tokens [setId]` runs a **fresh token build** (`handoff.fetch()` — Figma extract +
+ * `buildStyles`) so the local `tokens.json` and generated token outputs are current, discovers the
+ * logical sets from that document, then uploads each selected set (its extracted record + generated
+ * artifacts) to the connected registry. Each set is one atomic upsert; a set whose deterministic
+ * `sourceHash` matches the registry's is skipped. Absent sets are never deleted (explicit deletion is
+ * a separate management action).
+ */
+
+import Handoff from '../../index';
+import type { TokenSetRecord } from '../../store/types';
+import { Logger } from '../../utils/logger';
+import { stableStringify } from '../../utils/stable-stringify';
+import { createRegistryClient } from '../client';
+import type { TokenSetSummary, TokenSetTransferArtifact, TokenSetTransferPackage } from '../tokens/transfer';
+import { describePublishError } from './errors';
+import { PublishError, resolveConnectionOrThrow } from './index';
+import { createCurrentBuild, hashPathValues, sha256 } from './publish-build';
+
+/**
+ * Deterministic content hash for a token set: the key-order-independent record serialization plus the
+ * path-sorted artifact bytes. Independent of JSON key insertion order, so an unchanged set hashes the
+ * same across rebuilds and skip-unchanged works reliably.
+ */
+const hashTokenSet = (record: unknown, artifacts: TokenSetTransferArtifact[]): string => {
+  return hashPathValues(
+    artifacts.map((artifact) => ({ path: artifact.path, value: artifact.content })),
+    stableStringify(record)
+  );
+};
+
+/** Assemble one set's publish package from the freshly generated local token output. */
+const buildTokenSetPackage = async (handoff: Handoff, set: TokenSetRecord): Promise<TokenSetTransferPackage> => {
+  const artifacts: TokenSetTransferArtifact[] = (await handoff.store.tokens.getArtifacts(set.id)).map((artifact) => ({
+    path: artifact.path,
+    format: artifact.format,
+    content: artifact.content,
+    contentType: artifact.contentType,
+    hash: sha256(artifact.content),
+    size: Buffer.byteLength(artifact.content, 'utf8'),
+  }));
+
+  return {
+    id: set.id,
+    kind: set.kind,
+    record: set.record,
+    artifacts,
+    build: createCurrentBuild({ sourceHash: hashTokenSet(set.record, artifacts) }),
+  };
+};
+
+/**
+ * Publish all discovered token sets, or a single set when `setId` is given. Runs a fresh token build,
+ * skips sets whose content is unchanged on the registry, and reports published/unchanged/failed
+ * counts. A per-set upload failure is collected and never leaves a partially written set (each set is
+ * committed atomically server-side); the run throws at the end if any set failed.
+ */
+export const publishTokens = async (handoff: Handoff, setId?: string): Promise<void> => {
+  const connection = resolveConnectionOrThrow(handoff);
+
+  Logger.info(setId ? `Building tokens to publish "${setId}"…` : 'Building tokens for publish…');
+  await handoff.fetch();
+
+  const allSets = await handoff.store.tokens.listSets();
+  let targetSets = allSets;
+  if (setId) {
+    const found = allSets.find((set) => set.id === setId);
+    if (!found) {
+      throw new PublishError(
+        `Token set "${setId}" was not found in the generated tokens. Discovered sets: ${allSets.map((set) => set.id).join(', ') || '(none)'}.`
+      );
+    }
+    targetSets = [found];
+  }
+
+  const packages = await Promise.all(targetSets.map((set) => buildTokenSetPackage(handoff, set)));
+
+  const client = createRegistryClient({ baseUrl: connection.url, accessToken: connection.accessToken });
+  let remote: TokenSetSummary[] = [];
+  try {
+    remote = await client.listTokenSets();
+  } catch (error) {
+    // If the summary listing fails we simply publish everything (the server still no-ops unchanged sets).
+    Logger.info('Could not read current registry token sets; publishing all selected sets.');
+  }
+  const remoteHashById = new Map(remote.map((entry) => [entry.id, entry.sourceHash]));
+
+  let published = 0;
+  let unchanged = 0;
+  const failed: { id: string; message: string }[] = [];
+
+  for (const pkg of packages) {
+    const remoteHash = remoteHashById.get(pkg.id);
+    if (remoteHash && remoteHash === pkg.build.sourceHash) {
+      unchanged += 1;
+      Logger.info(`Unchanged: ${pkg.id}`);
+      continue;
+    }
+    try {
+      await client.publishTokens(pkg);
+      published += 1;
+      Logger.info(`Published: ${pkg.id} (${pkg.artifacts.length} artifact(s))`);
+    } catch (error) {
+      failed.push({ id: pkg.id, message: describePublishError(error, connection.url, 'token set') });
+    }
+  }
+
+  Logger.success(
+    `Tokens 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} token set(s) failed to publish.`);
+  }
+};

package/src/registry/tokens/sets.ts

@@ -0,0 +1,132 @@
+/**
+ * Logical token-set derivation — the pure, dependency-light boundary between the generated token
+ * document and the registry token entity.
+ *
+ * A **logical token set** is the registry entity boundary for tokens. Its stable ids are:
+ *
+ * ```text
+ * foundation/colors
+ * foundation/typography
+ * foundation/effects
+ * component/<componentId>
+ * ```
+ *
+ * The set `record` is the exact slice extracted from the generated `tokens.json`
+ * ({@link CoreTypes.IDocumentationObject}) — no lossy normalization, so new token properties flow
+ * through without a database migration. This module is imported by the store, publish, checkout, and
+ * server ingestion, so it stays free of fs/DB/React dependencies.
+ */
+
+import type { Types as CoreTypes } from 'handoff-core';
+import { isSafePathSegment } from '../path';
+
+/** Kind of a logical token set. */
+export type TokenSetKind = 'foundation' | 'component';
+
+/** A logical token set: its stable id, kind, and the exact extracted token slice. */
+export interface DerivedTokenSet {
+  id: string;
+  kind: TokenSetKind;
+  /** The exact slice from `tokens.json` — `IColorObject[]`/`ITypographyObject[]`/`IEffectObject[]` for a foundation, `IFileComponentObject` for a component. */
+  record: unknown;
+}
+
+/** The three stable foundation set ids, in deterministic order. */
+export const FOUNDATION_SET_IDS = ['foundation/colors', 'foundation/typography', 'foundation/effects'] as const;
+
+/**
+ * Map a foundation set name (the segment after `foundation/`, and the generated-file base name) to
+ * its `localStyles` key. Note the plural set names (`colors`/`effects`) map to the core's singular
+ * `localStyles.color`/`localStyles.effect`.
+ */
+const LOCAL_STYLES_KEY_BY_FOUNDATION: Record<string, keyof CoreTypes.IDocumentationObject['localStyles']> = {
+  colors: 'color',
+  typography: 'typography',
+  effects: 'effect',
+};
+
+/** Whether a set id refers to a component token set. */
+export const isComponentSet = (id: string): boolean => id.startsWith('component/');
+
+export const isTokenSetId = (id: string): boolean => {
+  if ((FOUNDATION_SET_IDS as readonly string[]).includes(id)) {
+    return true;
+  }
+  return isComponentSet(id) && isSafePathSegment(id.slice('component/'.length));
+};
+
+/** The kind of a set id. */
+export const kindForSetId = (id: string): TokenSetKind => (isComponentSet(id) ? 'component' : 'foundation');
+
+/**
+ * The generated-file base name for a set: `colors`/`typography`/`effects` for a foundation, the
+ * component id for a component set. This is the name the style transformers write files under
+ * (`<outDir>/<name>.<format>`).
+ */
+export const setNameForId = (id: string): string => (isComponentSet(id) ? id.slice('component/'.length) : (id.split('/')[1] ?? id));
+
+/** The `foundations/<type>` page type (`colors`/`typography`/`effects`) for a foundation set id, else null. */
+export const foundationTypeForId = (id: string): string | null => (isComponentSet(id) ? null : (id.split('/')[1] ?? null));
+
+/**
+ * Split the generated token document into logical sets: the three foundation sets (each possibly an
+ * empty array) plus one set per component. Foundation sets are always emitted so a set can carry zero
+ * tokens and so a token removed from a set is reflected as a shrunk `record` on republish.
+ */
+export const deriveTokenSets = (doc: CoreTypes.IDocumentationObject | null | undefined): DerivedTokenSet[] => {
+  const localStyles = doc?.localStyles ?? ({} as CoreTypes.IDocumentationObject['localStyles']);
+  const sets: DerivedTokenSet[] = [
+    { id: 'foundation/colors', kind: 'foundation', record: localStyles.color ?? [] },
+    { id: 'foundation/typography', kind: 'foundation', record: localStyles.typography ?? [] },
+    { id: 'foundation/effects', kind: 'foundation', record: localStyles.effect ?? [] },
+  ];
+
+  const components = doc?.components ?? {};
+  for (const componentId of Object.keys(components)) {
+    sets.push({ id: `component/${componentId}`, kind: 'component', record: components[componentId] });
+  }
+
+  return sets;
+};
+
+/** A minimal default token document, used when no local `tokens.json` exists yet on checkout. */
+export const emptyTokenDocument = (): CoreTypes.IDocumentationObject =>
+  ({
+    localStyles: { color: [], typography: [], effect: [] },
+    components: {},
+    assets: {},
+  }) as CoreTypes.IDocumentationObject;
+
+/**
+ * Splice a set of logical token sets into a token document, returning the merged document. Untouched
+ * sets are preserved (single-set checkout never clobbers other sets); a foundation set replaces its
+ * `localStyles` slice, a component set replaces `components[<id>]`.
+ */
+export const mergeTokenSetsIntoDocument = (
+  existing: CoreTypes.IDocumentationObject | null | undefined,
+  sets: DerivedTokenSet[]
+): CoreTypes.IDocumentationObject => {
+  const base = existing ?? emptyTokenDocument();
+  const doc: CoreTypes.IDocumentationObject = {
+    ...base,
+    localStyles: { ...(base.localStyles ?? emptyTokenDocument().localStyles) },
+    components: { ...(base.components ?? {}) },
+  } as CoreTypes.IDocumentationObject;
+
+  for (const set of sets) {
+    if (isComponentSet(set.id)) {
+      doc.components[setNameForId(set.id)] = set.record as CoreTypes.IFileComponentObject;
+      continue;
+    }
+    const localStylesKey = LOCAL_STYLES_KEY_BY_FOUNDATION[setNameForId(set.id)];
+    if (localStylesKey) {
+      (doc.localStyles as Record<string, unknown>)[localStylesKey] = set.record;
+    }
+  }
+
+  return doc;
+};
+
+/** The `localStyles` key backing a `foundations/<type>` page (`colors`→`color`, `effects`→`effect`). */
+export const localStylesKeyForFoundationType = (type: string): keyof CoreTypes.IDocumentationObject['localStyles'] | null =>
+  LOCAL_STYLES_KEY_BY_FOUNDATION[type] ?? null;

package/src/registry/tokens/transfer.ts

@@ -0,0 +1,53 @@
+/**
+ * Transfer payload contract for token sets, shared by the connected-workspace publish/checkout client
+ * and the registry-side token ingestion endpoint.
+ *
+ * Tokens are their own transfer concern (a `record` slice + byte-for-byte generated artifacts, no
+ * source files and no artifact reference graph), so they use this dedicated shape rather than the
+ * component/pattern/page {@link import('../transfer').TransferPackage}. Types only — no behavior.
+ */
+
+import type { TransferBuild } from '../transfer';
+import type { ArtifactBuildStatus } from '../../artifacts/types';
+import type { TokenSetKind } from './sets';
+
+/** A generated token artifact in a transfer package (CSS/SCSS/Style Dictionary/types/custom output). */
+export interface TokenSetTransferArtifact {
+  /** Registry-safe relative output path under the tokens dir (e.g. `css/colors.css`). */
+  path: string;
+  /** Logical format label (`css`|`scss`|`types`|`styleDictionary`|custom outDir). */
+  format: string;
+  content: string;
+  contentType: string;
+  hash?: string;
+  size?: number;
+}
+
+/**
+ * The full token set publish package uploaded to `PUT /api/registry/transfer/tokens/:setId`: the
+ * extracted record slice, the generated artifacts, and build metadata keyed by `sourceHash`.
+ */
+export interface TokenSetTransferPackage {
+  id: string;
+  kind: TokenSetKind;
+  /** The exact extracted token slice (`IColorObject[]`/…/`IFileComponentObject`). */
+  record: unknown;
+  artifacts: TokenSetTransferArtifact[];
+  build: TransferBuild;
+}
+
+/** The checkout payload returned by `GET /api/registry/transfer/tokens/:setId`. */
+export interface TokenSetCheckoutPayload {
+  id: string;
+  kind: TokenSetKind;
+  record: unknown;
+  artifacts: TokenSetTransferArtifact[];
+}
+
+/** A lightweight token-set summary (`GET /api/registry/transfer/tokens`) driving skip-unchanged + bulk checkout. */
+export interface TokenSetSummary {
+  id: string;
+  kind: TokenSetKind;
+  sourceHash: string | null;
+  status: ArtifactBuildStatus | null;
+}

package/src/registry/transfer.ts

@@ -0,0 +1,82 @@
+/**
+ * Transfer payload contract shared by the connected-workspace publish client and the registry-side
+ * ingestion endpoint.
+ *
+ * Publish is the only path allowed to set render/build-defining fields, source files, rendered
+ * artifacts, and build metadata. This module is the single shared description of that wire shape so
+ * the CLI (which builds and uploads the package) and the registry API (which validates and ingests
+ * it) never drift. Types only — no runtime behavior.
+ */
+
+import type { ArtifactBuildStatus, ArtifactKind, ArtifactOwnerKind, ArtifactReference } from '../artifacts/types';
+import type { RegistryTextFileKind } from '../store/types';
+
+/** Entity kinds that can be transferred (published/checked out). */
+export type TransferEntityKind = 'component' | 'pattern' | 'page';
+
+/**
+ * A registry-safe source file in a transfer package. Declarations are workspace-only (synthesized on
+ * checkout) and are never present here — `kind` excludes `declaration` by type.
+ */
+export interface TransferFile {
+  /** Registry-safe relative path within the entity (e.g. `Badge.tsx`). */
+  path: string;
+  kind: RegistryTextFileKind;
+  content: string;
+  contentType: string;
+}
+
+/**
+ * A rendered docs read-model artifact in a transfer package. Carries the structured ownership and
+ * references the registry stores so it can validate, serve, and dedup the artifact without ever
+ * parsing HTML.
+ */
+export interface TransferArtifact {
+  /** Logical artifact path (e.g. `component/badge-primary.html`, `component/main.css`). */
+  path: string;
+  artifactKind: ArtifactKind;
+  content: string;
+  contentType: string;
+  /** What the artifact belongs to — shared/global artifacts are `asset` with a `null` owner id. */
+  ownerKind: ArtifactOwnerKind;
+  ownerId: string | null;
+  /** Structured references this artifact depends on (drives required-reference validation). */
+  references?: ArtifactReference[];
+  formatVersion?: string;
+  hash?: string;
+  size?: number;
+}
+
+/** Build metadata for the published entity. */
+export interface TransferBuild {
+  status: ArtifactBuildStatus;
+  builtAt?: string;
+  builderVersion?: string;
+  artifactHash?: string;
+  sourceHash?: string;
+  warnings?: string[];
+  error?: string;
+}
+
+/**
+ * The full publish package uploaded to `PUT /api/registry/transfer/{component|pattern|page}/:id`.
+ * Rendered artifacts are included when the entity has a render pipeline.
+ */
+export interface TransferPackage {
+  /** Normalized component, pattern, or page record stored as the served record. */
+  item: Record<string, unknown>;
+  files: TransferFile[];
+  artifacts: TransferArtifact[];
+  build: TransferBuild;
+}
+
+/**
+ * The checkout payload returned by `GET /api/registry/transfer/{component|pattern|page}/:id`.
+ * Declarations are omitted because the consuming workspace creates them locally.
+ */
+export interface CheckoutPayload {
+  kind: TransferEntityKind;
+  /** Normalized record used to reconstruct the entity. */
+  item: Record<string, unknown>;
+  files: TransferFile[];
+}

package/src/store/filesystem-assets.ts

@@ -0,0 +1,152 @@
+import crypto from 'crypto';
+import fs from 'fs-extra';
+import { Types as CoreTypes } from 'handoff-core';
+import path from 'path';
+import { resolveAssetPhysicalPath, type AssetPhysicalRoots } from '../registry/assets/layout';
+import { ASSET_COLLECTIONS, assetContentType } from '../registry/assets/sets';
+import type { FilesystemStoreContext } from './filesystem';
+import type { AssetContentResource, AssetMetadata, AssetStore } from './types';
+
+const sha256 = (bytes: Buffer): string => crypto.createHash('sha256').update(bytes).digest('hex');
+
+interface AssetFileEntry {
+  logicalPath: string;
+  name: string;
+  metadata?: Record<string, unknown> | null;
+  absolutePath: string;
+}
+
+const isFile = (absolutePath: string): boolean => {
+  try {
+    return fs.existsSync(absolutePath) && fs.statSync(absolutePath).isFile();
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Filesystem backed asset store. Enumerates each collection from the generated `public/api` tree
+ * plus the downloadable ZIP and font archives.
+ */
+export class FilesystemAssetStore implements AssetStore {
+  constructor(private readonly context: FilesystemStoreContext) {}
+
+  private roots(): AssetPhysicalRoots | null {
+    const apiPath = this.context.getAssetsApiPath?.();
+    const iconsZip = this.context.getIconsZipFilePath?.();
+    const logosZip = this.context.getLogosZipFilePath?.();
+    const workingPath = this.context.workingPath;
+    if (!apiPath || !iconsZip || !logosZip || !workingPath) {
+      return null;
+    }
+    return { apiPath, iconsZip, logosZip, workingPath };
+  }
+
+  private enumerate(collection: string): AssetFileEntry[] {
+    const roots = this.roots();
+    if (!roots) {
+      return [];
+    }
+
+    if (collection === 'icons' || collection === 'logos') {
+      const entries: AssetFileEntry[] = [];
+      const collectionJson = `assets/${collection}.json`;
+      let assetObjects: CoreTypes.IAssetObject[] = [];
+      try {
+        const raw = fs.readFileSync(resolveAssetPhysicalPath(collectionJson, roots), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed)) assetObjects = parsed as CoreTypes.IAssetObject[];
+      } catch {
+        assetObjects = [];
+      }
+      for (const asset of assetObjects) {
+        const logicalPath = `assets/${collection}/${asset.path}`;
+        entries.push({
+          logicalPath,
+          name: asset.name,
+          metadata: { icon: asset.icon, index: asset.index, description: asset.description ?? null },
+          absolutePath: resolveAssetPhysicalPath(logicalPath, roots),
+        });
+      }
+      const extras =
+        collection === 'icons'
+          ? [collectionJson, 'icons-sprite.svg', 'icons-sprite-manifest.json', 'icons.zip']
+          : [collectionJson, 'logos.zip'];
+      for (const logicalPath of extras) {
+        entries.push({ logicalPath, name: path.basename(logicalPath), absolutePath: resolveAssetPhysicalPath(logicalPath, roots) });
+      }
+      return entries.filter((entry) => isFile(entry.absolutePath));
+    }
+
+    if (collection === 'fonts') {
+      const fontsDir = path.resolve(roots.workingPath, 'fonts');
+      if (!fs.existsSync(fontsDir)) {
+        return [];
+      }
+      try {
+        return fs
+          .readdirSync(fontsDir)
+          .filter((file) => file.toLowerCase().endsWith('.zip'))
+          .map((file) => ({ logicalPath: `fonts/${file}`, name: file, absolutePath: path.join(fontsDir, file) }))
+          .filter((entry) => isFile(entry.absolutePath));
+      } catch {
+        return [];
+      }
+    }
+
+    return [];
+  }
+
+  private toMetadata(collection: string, entry: AssetFileEntry, bytes: Buffer): AssetMetadata {
+    return {
+      collection,
+      path: entry.logicalPath,
+      name: entry.name,
+      contentType: assetContentType(entry.logicalPath),
+      size: bytes.length,
+      contentHash: sha256(bytes),
+      metadata: entry.metadata ?? null,
+    };
+  }
+
+  listCollections(): string[] {
+    return ASSET_COLLECTIONS.filter((collection) => this.enumerate(collection).length > 0);
+  }
+
+  listAssets(collection: string): AssetMetadata[] {
+    const out: AssetMetadata[] = [];
+    for (const entry of this.enumerate(collection)) {
+      try {
+        out.push(this.toMetadata(collection, entry, fs.readFileSync(entry.absolutePath)));
+      } catch {
+        // Skip files that vanished between enumeration and read.
+      }
+    }
+    return out;
+  }
+
+  getAsset(collection: string, assetPath: string): AssetMetadata | null {
+    const entry = this.enumerate(collection).find((candidate) => candidate.logicalPath === assetPath);
+    if (!entry) {
+      return null;
+    }
+    try {
+      return this.toMetadata(collection, entry, fs.readFileSync(entry.absolutePath));
+    } catch {
+      return null;
+    }
+  }
+
+  getAssetContent(collection: string, assetPath: string): AssetContentResource | null {
+    const entry = this.enumerate(collection).find((candidate) => candidate.logicalPath === assetPath);
+    if (!entry) {
+      return null;
+    }
+    try {
+      const bytes = fs.readFileSync(entry.absolutePath);
+      return { ...this.toMetadata(collection, entry, bytes), body: bytes };
+    } catch {
+      return null;
+    }
+  }
+}