@nebutra/design-sync 0.1.0 → 0.1.1

package/dist/providers/penpot.js

@@ -0,0 +1,137 @@
+import { logger } from "@nebutra/logger";
+import { defaultTokensDir, defaultTokensStudioDir, readTokenSets, validateDtcgTree } from "../io";
+// =============================================================================
+// Penpot Provider — China-friendly + self-hostable Figma alternative
+// =============================================================================
+// Penpot speaks DTCG natively (one of its differentiators) and exposes a
+// public REST API. The provider is wired with full surface area so customers
+// can swap providers without changing application code, but real network
+// calls stay behind a `dryRun || !credsReady` guard until the operator
+// explicitly provisions PENPOT_TOKEN.
+//
+// Why this matters:
+//   - Penpot can be self-hosted, sidesteps the Figma block in mainland China.
+//   - DTCG-native means we do not need a translation step like with Figma.
+//   - Tokens Studio plugin also targets Penpot — designers keep the same UX.
+// =============================================================================
+const DEFAULT_PENPOT_API = "https://design.penpot.app/api";
+export class PenpotProvider {
+    name = "penpot";
+    tokensDir;
+    tokensStudioDir;
+    apiUrl;
+    token;
+    fileId;
+    teamId;
+    constructor(config) {
+        this.tokensDir = config.tokensDir ?? defaultTokensDir();
+        this.tokensStudioDir = config.tokensStudioDir ?? defaultTokensStudioDir();
+        this.apiUrl = config.apiUrl ?? process.env.PENPOT_API_URL ?? DEFAULT_PENPOT_API;
+        this.token = config.token ?? process.env.PENPOT_TOKEN ?? undefined;
+        this.fileId = config.fileId ?? process.env.PENPOT_FILE_ID ?? undefined;
+        this.teamId = config.teamId ?? process.env.PENPOT_TEAM_ID ?? undefined;
+        logger.info("[design-sync:penpot] Provider initialised", {
+            apiUrl: this.apiUrl,
+            hasToken: Boolean(this.token),
+            hasFileId: Boolean(this.fileId),
+        });
+    }
+    async pull(options = {}) {
+        if (!this.credsReady()) {
+            // No credentials → fall through to local DTCG, mirroring git-only.
+            const sets = await readTokenSets(this.tokensDir);
+            const filtered = filterSets(sets, options.themes);
+            logger.warn("[design-sync:penpot] pull falling back to local DTCG (no PENPOT_TOKEN)");
+            return {
+                sets: filtered,
+                written: false,
+                provider: "penpot",
+                pulledAt: new Date().toISOString(),
+                summary: `penpot: PENPOT_TOKEN missing — returned ${filtered.length} local DTCG set(s)`,
+            };
+        }
+        // Real pull placeholder — when wired up, this calls:
+        //   GET {apiUrl}/rpc/command/get-file?id={fileId}
+        //   Authorization: Token {token}
+        // and projects the design-tokens collection back into DTCG sets.
+        // See https://design.penpot.app/api/docs for the full RPC catalogue.
+        throw new Error("[design-sync:penpot] live pull is not yet implemented. " +
+            "Unset PENPOT_TOKEN to fall back to local DTCG, or open packages/design/design-sync/DESIGN.md for the rollout plan.");
+    }
+    async push(options = {}) {
+        const all = await readTokenSets(this.tokensDir);
+        const sets = filterSets(all, options.themes);
+        for (const set of sets) {
+            const errors = validateDtcgTree(set.tokens);
+            if (errors.length > 0) {
+                throw new Error(`[design-sync:penpot] DTCG validation failed for ${set.relativePath}:\n  - ${errors.join("\n  - ")}`);
+            }
+        }
+        const credsReady = this.credsReady();
+        const explicitDryRun = options.dryRun ?? false;
+        const dryRun = explicitDryRun || !credsReady;
+        if (dryRun) {
+            logger.warn("[design-sync:penpot] push skipped (dry-run scaffold)", {
+                reason: credsReady ? "explicit dryRun" : "missing credentials",
+                sets: sets.length,
+            });
+            return {
+                pushed: false,
+                sets: sets.map((s) => s.relativePath),
+                provider: "penpot",
+                pushedAt: new Date().toISOString(),
+                summary: credsReady
+                    ? `penpot: dry-run — would POST ${sets.length} DTCG set(s) to ${this.apiUrl}/rpc/command/update-file-design-tokens`
+                    : "penpot: dry-run — PENPOT_TOKEN or PENPOT_FILE_ID missing",
+                dryRun: true,
+            };
+        }
+        // Real push placeholder — when wired up, this calls:
+        //   POST {apiUrl}/rpc/command/update-file-design-tokens
+        //   Authorization: Token {token}
+        //   body: { fileId, tokens: dtcgTree }
+        throw new Error("[design-sync:penpot] live push is not yet implemented. " +
+            "Use { dryRun: true } until the Penpot RPC integration is wired up.");
+    }
+    async healthcheck() {
+        const detected = [];
+        const missing = [];
+        if (this.token)
+            detected.push("PENPOT_TOKEN");
+        else
+            missing.push("PENPOT_TOKEN");
+        if (this.fileId)
+            detected.push("PENPOT_FILE_ID");
+        else
+            missing.push("PENPOT_FILE_ID");
+        if (this.teamId)
+            detected.push("PENPOT_TEAM_ID");
+        detected.push(`PENPOT_API_URL=${this.apiUrl}`);
+        const ok = missing.length === 0;
+        return {
+            ok,
+            provider: "penpot",
+            message: ok
+                ? `penpot: credentials present (api=${this.apiUrl})`
+                : `penpot: not ready — missing ${missing.join(", ")}`,
+            detectedEnv: detected,
+            missingEnv: missing,
+        };
+    }
+    /**
+     * Reserved for future use — exposes the configured tokens-studio directory
+     * so consumers (e.g. CI workflows) can attach Penpot-side metadata mirrors.
+     */
+    getTokensStudioDir() {
+        return this.tokensStudioDir;
+    }
+    credsReady() {
+        return Boolean(this.token && this.fileId);
+    }
+}
+function filterSets(sets, themes) {
+    if (!themes || themes.length === 0)
+        return sets;
+    const wanted = new Set(themes);
+    return sets.filter((s) => wanted.has(s.name) || wanted.has(s.relativePath));
+}

package/dist/types.d.ts

@@ -0,0 +1,175 @@
+import { z } from "zod";
+/**
+ * Supported design-sync backend providers.
+ *
+ * - `figma`     — Figma + Tokens Studio plugin (DTCG via GitHub provider sync)
+ * - `penpot`    — Penpot REST API (self-hostable, China-friendly)
+ * - `git-only`  — No design tool; reads/writes local DTCG files directly
+ * - `memory`    — In-memory test fixture (CI / unit tests only)
+ */
+export type DesignSyncProviderType = "figma" | "penpot" | "git-only" | "memory";
+/**
+ * A W3C Design Tokens Community Group (DTCG) leaf token.
+ * Every leaf MUST carry both `$value` and `$type`.
+ *
+ * Spec: https://design-tokens.github.io/community-group/format/
+ */
+export declare const DesignTokenLeafSchema: z.ZodObject<{
+    $value: z.ZodUnknown;
+    $type: z.ZodString;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
+export type DesignTokenLeaf = z.infer<typeof DesignTokenLeafSchema>;
+/**
+ * A DTCG token tree is a recursive map of named groups and leaves.
+ * Groups are plain objects; leaves carry `$value` + `$type`.
+ */
+export type DesignTokenTree = {
+    [key: string]: DesignTokenTree | DesignTokenLeaf;
+};
+/**
+ * A single DTCG file = one token set (e.g. `core.json`, `themes/light.json`).
+ */
+export interface DesignTokenSet {
+    /** Token-set name (matches file basename without extension, e.g. "core") */
+    name: string;
+    /** Path relative to the tokens directory (e.g. "themes/light.json") */
+    relativePath: string;
+    /** Parsed DTCG tree */
+    tokens: DesignTokenTree;
+}
+export interface PullOptions {
+    /**
+     * Optional theme/token-set filter. When omitted, all sets are pulled.
+     * Provider-specific naming applies (e.g. Figma collection IDs).
+     */
+    themes?: string[];
+    /**
+     * If true, the provider should validate but NOT write to the local repo.
+     * Used by CI to verify a remote state without producing diffs.
+     */
+    dryRun?: boolean;
+    /** Tenant scoping for multi-workspace SaaS deployments */
+    tenantId?: string;
+}
+export interface PushOptions {
+    /** Restrict the push to specific token sets */
+    themes?: string[];
+    /**
+     * If true, the provider should compute the diff but NOT call the remote API.
+     * `figma.push({ dryRun: true })` is the default until the user opts in.
+     */
+    dryRun?: boolean;
+    /** Tenant scoping */
+    tenantId?: string;
+}
+export interface PullResult {
+    /** Token sets that were retrieved */
+    sets: DesignTokenSet[];
+    /** Whether the local repo was modified */
+    written: boolean;
+    /** Provider that produced the result */
+    provider: DesignSyncProviderType;
+    /** ISO-8601 timestamp */
+    pulledAt: string;
+    /** Human-readable summary line for CLI output */
+    summary: string;
+}
+export interface PushResult {
+    /** Whether the remote design tool was modified */
+    pushed: boolean;
+    /** Token sets that were sent (or would have been sent in a dry-run) */
+    sets: string[];
+    /** Provider name */
+    provider: DesignSyncProviderType;
+    /** ISO-8601 timestamp */
+    pushedAt: string;
+    /** Human-readable summary */
+    summary: string;
+    /** True when the provider intentionally skipped the call (no creds, dry-run) */
+    dryRun: boolean;
+}
+export interface HealthStatus {
+    /** Is the provider configured + reachable? */
+    ok: boolean;
+    /** Provider name */
+    provider: DesignSyncProviderType;
+    /** Free-form diagnostic */
+    message: string;
+    /** Detected env var names that are present (not their values) */
+    detectedEnv: string[];
+    /** Detected env var names that are missing */
+    missingEnv: string[];
+}
+/**
+ * Every design-sync backend implements this interface.
+ * The factory (`createDesignSync`) returns a `DesignSyncProvider`.
+ */
+export interface DesignSyncProvider {
+    readonly name: DesignSyncProviderType;
+    /**
+     * Pull: design-tool → repo (DTCG JSON).
+     * For `git-only` this is a no-op read of local files.
+     */
+    pull(options?: PullOptions): Promise<PullResult>;
+    /**
+     * Push: repo (DTCG JSON) → design-tool.
+     * For `git-only` this is a no-op write/format of local files.
+     * Real providers default to dry-run unless explicit credentials exist.
+     */
+    push(options?: PushOptions): Promise<PushResult>;
+    /**
+     * Confirm the provider has the env vars / file access it needs.
+     */
+    healthcheck(): Promise<HealthStatus>;
+}
+/**
+ * Shared options every provider accepts. The tokens directory is the
+ * filesystem source of truth (DTCG JSON), independent of which design tool
+ * we sync with.
+ */
+export interface BaseProviderConfig {
+    /**
+     * Absolute path to the DTCG tokens directory.
+     * Defaults to `<cwd>/packages/design/design-tokens/tokens`.
+     */
+    tokensDir?: string;
+    /**
+     * Absolute path to the `.tokens-studio` metadata directory (if used).
+     * Defaults to `<cwd>/.tokens-studio`.
+     */
+    tokensStudioDir?: string;
+}
+export interface FigmaProviderConfig extends BaseProviderConfig {
+    provider: "figma";
+    /** Figma personal access token. Defaults to `process.env.FIGMA_PERSONAL_ACCESS_TOKEN`. */
+    personalAccessToken?: string;
+    /** Figma file ID (the `:file_key` segment in the URL). */
+    fileId?: string;
+    /** GitHub repo (owner/name) used by the Tokens Studio plugin sync. */
+    githubRepo?: string;
+    /** GitHub branch the plugin pushes to. Defaults to `main`. */
+    githubBranch?: string;
+}
+export interface PenpotProviderConfig extends BaseProviderConfig {
+    provider: "penpot";
+    /** Penpot API URL — public cloud or self-hosted. */
+    apiUrl?: string;
+    /** Penpot personal access token. */
+    token?: string;
+    /** Penpot file ID. */
+    fileId?: string;
+    /** Penpot team / workspace ID. */
+    teamId?: string;
+}
+export interface GitOnlyProviderConfig extends BaseProviderConfig {
+    provider: "git-only";
+}
+export interface MemoryProviderConfig extends BaseProviderConfig {
+    provider: "memory";
+    /** Optional initial in-memory token sets (used in tests). */
+    initialSets?: DesignTokenSet[];
+}
+export type DesignSyncConfig = FigmaProviderConfig | PenpotProviderConfig | GitOnlyProviderConfig | MemoryProviderConfig;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+// ── DTCG Token Schema ───────────────────────────────────────────────────────
+/**
+ * A W3C Design Tokens Community Group (DTCG) leaf token.
+ * Every leaf MUST carry both `$value` and `$type`.
+ *
+ * Spec: https://design-tokens.github.io/community-group/format/
+ */
+export const DesignTokenLeafSchema = z
+    .object({
+    $value: z.unknown(),
+    $type: z.string(),
+    $description: z.string().optional(),
+    $extensions: z.record(z.string(), z.unknown()).optional(),
+})
+    .passthrough();

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@nebutra/design-sync",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Provider-agnostic design-tool sync. Figma + Tokens Studio | Penpot | git-only | memory.",
   "private": false,
-  "license": "AGPL-3.0",
+  "license": "MIT",
   "type": "module",
   "nebutra": {
     "status": "foundation",
@@ -59,7 +59,7 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@nebutra/logger": "0.1.0"
+    "@nebutra/logger": "0.1.1"
   },
   "devDependencies": {
     "@types/node": "^22.19.15",