@nebutra/design-sync 0.1.0 → 0.1.1

package/dist/io.js

@@ -0,0 +1,119 @@
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import { DesignTokenLeafSchema } from "./types";
+// =============================================================================
+// DTCG Filesystem I/O
+// =============================================================================
+// Shared helpers used by every provider. Reading and writing the canonical
+// W3C DTCG JSON tree on disk is identical across Figma / Penpot / git-only —
+// the only thing that differs is what the provider does AFTER it has the data.
+// =============================================================================
+const TOKEN_FILE_EXT = ".json";
+/**
+ * Recursively list every `.json` file beneath `root`. Skips dotfiles.
+ */
+async function listJsonFiles(root) {
+    const out = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.startsWith("."))
+                continue;
+            const full = join(dir, entry);
+            const info = await stat(full);
+            if (info.isDirectory()) {
+                await walk(full);
+            }
+            else if (info.isFile() && entry.endsWith(TOKEN_FILE_EXT)) {
+                out.push(full);
+            }
+        }
+    }
+    await walk(root);
+    return out.sort();
+}
+/**
+ * Validate that every leaf in a DTCG tree carries `$value` and `$type`.
+ * Returns a list of dot-paths that violate the contract.
+ */
+export function validateDtcgTree(tree, pathPrefix = "") {
+    const errors = [];
+    if (tree === null || typeof tree !== "object" || Array.isArray(tree)) {
+        return errors;
+    }
+    const node = tree;
+    // A leaf has `$value` (or `value` for legacy Tokens Studio v1).
+    const hasValue = "$value" in node || "value" in node;
+    if (hasValue) {
+        const parsed = DesignTokenLeafSchema.safeParse(node);
+        if (!parsed.success) {
+            errors.push(`${pathPrefix || "<root>"}: ${parsed.error.message}`);
+        }
+        return errors;
+    }
+    for (const [key, value] of Object.entries(node)) {
+        if (key.startsWith("$"))
+            continue;
+        const childPath = pathPrefix ? `${pathPrefix}.${key}` : key;
+        errors.push(...validateDtcgTree(value, childPath));
+    }
+    return errors;
+}
+/**
+ * Read all DTCG token files under `tokensDir` into memory.
+ * Each file becomes one `DesignTokenSet`.
+ */
+export async function readTokenSets(tokensDir) {
+    const files = await listJsonFiles(tokensDir);
+    const sets = [];
+    for (const file of files) {
+        const raw = await readFile(file, "utf8");
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (error) {
+            throw new Error(`[design-sync] Failed to parse DTCG file ${file}: ${error.message}`);
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error(`[design-sync] DTCG file ${file} must contain an object at the root.`);
+        }
+        const relativePath = relative(tokensDir, file).split(sep).join("/");
+        const name = relativePath.replace(/\.json$/u, "").replace(/\//gu, "/");
+        sets.push({
+            name,
+            relativePath,
+            tokens: parsed,
+        });
+    }
+    return sets;
+}
+/**
+ * Write a `DesignTokenSet` back to disk under `tokensDir`. Creates
+ * parent directories as needed and uses 2-space indentation with a
+ * trailing newline (matches `.tokens-studio/config.json#format`).
+ */
+export async function writeTokenSet(tokensDir, set) {
+    const target = join(tokensDir, set.relativePath);
+    await mkdir(dirname(target), { recursive: true });
+    const serialized = `${JSON.stringify(set.tokens, null, 2)}\n`;
+    await writeFile(target, serialized, "utf8");
+}
+/**
+ * Default tokens directory for the Nebutra-Sailor monorepo.
+ */
+export function defaultTokensDir(cwd = process.cwd()) {
+    return join(cwd, "packages", "design", "design-tokens", "tokens");
+}
+/**
+ * Default Tokens Studio metadata directory for the Nebutra-Sailor monorepo.
+ */
+export function defaultTokensStudioDir(cwd = process.cwd()) {
+    return join(cwd, ".tokens-studio");
+}

package/dist/providers/figma.d.ts

@@ -0,0 +1,21 @@
+import type { DesignSyncProvider, FigmaProviderConfig, HealthStatus, PullOptions, PullResult, PushOptions, PushResult } from "../types";
+export declare class FigmaProvider implements DesignSyncProvider {
+    readonly name: "figma";
+    private readonly tokensDir;
+    private readonly tokensStudioDir;
+    private readonly personalAccessToken;
+    private readonly fileId;
+    private readonly githubRepo;
+    private readonly githubBranch;
+    constructor(config: FigmaProviderConfig);
+    pull(options?: PullOptions): Promise<PullResult>;
+    push(options?: PushOptions): Promise<PushResult>;
+    healthcheck(): Promise<HealthStatus>;
+    /**
+     * Assert that `.tokens-studio/{config,metadata,themes}.json` exist + parse.
+     * The plugin refuses to load the design system if any of these are missing
+     * or malformed; surfacing the failure here prevents silent drift.
+     */
+    private assertTokensStudioMetadata;
+}
+//# sourceMappingURL=figma.d.ts.map

package/dist/providers/figma.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma.d.ts","sourceRoot":"","sources":["../../src/providers/figma.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,EACX,MAAM,UAAU,CAAC;AAyBlB,qBAAa,aAAc,YAAW,kBAAkB;IACtD,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAU;IAEjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,MAAM,EAAE,mBAAmB;IAgBjC,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAiBpD,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAiDpD,WAAW,IAAI,OAAO,CAAC,YAAY,CAAC;IAwC1C;;;;OAIG;YACW,0BAA0B;CA+BzC"}

package/dist/providers/figma.js

@@ -0,0 +1,179 @@
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { logger } from "@nebutra/logger";
+import { defaultTokensDir, defaultTokensStudioDir, readTokenSets, validateDtcgTree } from "../io";
+// =============================================================================
+// Figma Provider — Figma + Tokens Studio
+// =============================================================================
+// Architecture (matches the legacy `.tokens-studio/config.json` setup):
+//
+//   Figma (Tokens Studio plugin) ──► GitHub branch ──► repo (DTCG JSON)
+//                              ▲                             │
+//                              └─── pull from main ──────────┘
+//
+// The plugin owns the git transport. This provider:
+//   - validates that the Tokens Studio config + DTCG tree are well-formed
+//   - "pull" reads the DTCG files the plugin already wrote to git
+//   - "push" is a dry-run scaffold for the Figma Variables REST API
+//     (PATCH /v1/files/:file_key/variables) — the user must opt in by
+//     providing FIGMA_PERSONAL_ACCESS_TOKEN + FIGMA_FILE_ID and removing
+//     the early-exit guard.
+//
+// All Tokens Studio metadata that previously lived in `.tokens-studio/` is
+// still consumed from disk so the existing designer onboarding does not break.
+// =============================================================================
+const FIGMA_API_ROOT = "https://api.figma.com";
+export class FigmaProvider {
+    name = "figma";
+    tokensDir;
+    tokensStudioDir;
+    personalAccessToken;
+    fileId;
+    githubRepo;
+    githubBranch;
+    constructor(config) {
+        this.tokensDir = config.tokensDir ?? defaultTokensDir();
+        this.tokensStudioDir = config.tokensStudioDir ?? defaultTokensStudioDir();
+        this.personalAccessToken =
+            config.personalAccessToken ?? process.env.FIGMA_PERSONAL_ACCESS_TOKEN ?? undefined;
+        this.fileId = config.fileId ?? process.env.FIGMA_FILE_ID ?? undefined;
+        this.githubRepo = config.githubRepo ?? process.env.FIGMA_GITHUB_REPO ?? undefined;
+        this.githubBranch = config.githubBranch ?? process.env.FIGMA_GITHUB_BRANCH ?? "main";
+        logger.info("[design-sync:figma] Provider initialised", {
+            tokensDir: this.tokensDir,
+            hasToken: Boolean(this.personalAccessToken),
+            hasFileId: Boolean(this.fileId),
+        });
+    }
+    async pull(options = {}) {
+        // Tokens Studio plugin already wrote DTCG files to git on `pull`.
+        // We just re-read them from disk and (optionally) validate Tokens
+        // Studio metadata so the result mirrors what the plugin would emit.
+        const sets = await readTokenSets(this.tokensDir);
+        const filtered = filterSets(sets, options.themes);
+        await this.assertTokensStudioMetadata();
+        return {
+            sets: filtered,
+            written: false,
+            provider: "figma",
+            pulledAt: new Date().toISOString(),
+            summary: `figma: read ${filtered.length} DTCG token set(s) (Tokens Studio plugin owns the git transport)`,
+        };
+    }
+    async push(options = {}) {
+        // Pre-flight: validate DTCG before attempting any remote call.
+        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:figma] DTCG validation failed for ${set.relativePath}:\n  - ${errors.join("\n  - ")}`);
+            }
+        }
+        const credsReady = Boolean(this.personalAccessToken && this.fileId);
+        const explicitDryRun = options.dryRun ?? false;
+        const dryRun = explicitDryRun || !credsReady;
+        if (dryRun) {
+            logger.warn("[design-sync:figma] push skipped (dry-run scaffold)", {
+                reason: credsReady ? "explicit dryRun" : "missing credentials",
+                sets: sets.length,
+            });
+            return {
+                pushed: false,
+                sets: sets.map((s) => s.relativePath),
+                provider: "figma",
+                pushedAt: new Date().toISOString(),
+                summary: credsReady
+                    ? `figma: dry-run — would PATCH ${sets.length} set(s) to ${FIGMA_API_ROOT}/v1/files/${this.fileId}/variables`
+                    : "figma: dry-run — FIGMA_PERSONAL_ACCESS_TOKEN or FIGMA_FILE_ID not set",
+                dryRun: true,
+            };
+        }
+        // Real push placeholder — kept guarded until the user opts in.
+        // The integration will call the Figma Variables REST API:
+        //   PATCH /v1/files/:file_key/variables
+        //   X-Figma-Token: <personalAccessToken>
+        // See https://www.figma.com/developers/api#variables
+        throw new Error("[design-sync:figma] live push to Figma Variables REST API is not yet implemented. " +
+            "Use { dryRun: true } or unset FIGMA_PERSONAL_ACCESS_TOKEN until the integration is wired up. " +
+            "See packages/design/design-sync/DESIGN.md for the rollout plan.");
+    }
+    async healthcheck() {
+        const detected = [];
+        const missing = [];
+        if (this.personalAccessToken)
+            detected.push("FIGMA_PERSONAL_ACCESS_TOKEN");
+        else
+            missing.push("FIGMA_PERSONAL_ACCESS_TOKEN");
+        if (this.fileId)
+            detected.push("FIGMA_FILE_ID");
+        else
+            missing.push("FIGMA_FILE_ID");
+        if (this.githubRepo)
+            detected.push("FIGMA_GITHUB_REPO");
+        if (this.githubBranch)
+            detected.push(`FIGMA_GITHUB_BRANCH=${this.githubBranch}`);
+        let tokensStudioOk = true;
+        let tokensStudioMessage = "";
+        try {
+            await this.assertTokensStudioMetadata();
+        }
+        catch (error) {
+            tokensStudioOk = false;
+            tokensStudioMessage = error.message;
+            missing.push("tokens-studio metadata");
+        }
+        const ok = missing.length === 0 && tokensStudioOk;
+        return {
+            ok,
+            provider: "figma",
+            message: ok
+                ? "figma: credentials present + Tokens Studio metadata valid"
+                : `figma: not ready — ${[
+                    missing.length > 0 ? `missing ${missing.join(", ")}` : "",
+                    tokensStudioMessage,
+                ]
+                    .filter(Boolean)
+                    .join("; ")}`,
+            detectedEnv: detected,
+            missingEnv: missing,
+        };
+    }
+    /**
+     * Assert that `.tokens-studio/{config,metadata,themes}.json` exist + parse.
+     * The plugin refuses to load the design system if any of these are missing
+     * or malformed; surfacing the failure here prevents silent drift.
+     */
+    async assertTokensStudioMetadata() {
+        const required = ["config.json", "metadata.json", "themes.json"];
+        const errors = [];
+        try {
+            const info = await stat(this.tokensStudioDir);
+            if (!info.isDirectory()) {
+                throw new Error(`${this.tokensStudioDir} is not a directory`);
+            }
+        }
+        catch (error) {
+            throw new Error(`[design-sync:figma] Tokens Studio metadata directory missing at ${this.tokensStudioDir}: ${error.message}`);
+        }
+        for (const file of required) {
+            const path = join(this.tokensStudioDir, file);
+            try {
+                const raw = await readFile(path, "utf8");
+                JSON.parse(raw);
+            }
+            catch (error) {
+                errors.push(`${path}: ${error.message}`);
+            }
+        }
+        if (errors.length > 0) {
+            throw new Error(`[design-sync:figma] Tokens Studio metadata invalid:\n  - ${errors.join("\n  - ")}`);
+        }
+    }
+}
+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/providers/git-only.d.ts

@@ -0,0 +1,11 @@
+import type { DesignSyncProvider, GitOnlyProviderConfig, HealthStatus, PullOptions, PullResult, PushOptions, PushResult } from "../types";
+export declare class GitOnlyProvider implements DesignSyncProvider {
+    readonly name: "git-only";
+    private readonly tokensDir;
+    private readonly tokensStudioDir;
+    constructor(config: GitOnlyProviderConfig);
+    pull(options?: PullOptions): Promise<PullResult>;
+    push(options?: PushOptions): Promise<PushResult>;
+    healthcheck(): Promise<HealthStatus>;
+}
+//# sourceMappingURL=git-only.d.ts.map

package/dist/providers/git-only.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-only.d.ts","sourceRoot":"","sources":["../../src/providers/git-only.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,kBAAkB,EAClB,qBAAqB,EACrB,YAAY,EACZ,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,EACX,MAAM,UAAU,CAAC;AAalB,qBAAa,eAAgB,YAAW,kBAAkB;IACxD,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;IAEpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;gBAE7B,MAAM,EAAE,qBAAqB;IAQnC,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAapD,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAmCpD,WAAW,IAAI,OAAO,CAAC,YAAY,CAAC;CAmC3C"}

package/dist/providers/git-only.js

@@ -0,0 +1,104 @@
+import { stat } from "node:fs/promises";
+import { logger } from "@nebutra/logger";
+import { defaultTokensDir, defaultTokensStudioDir, readTokenSets, validateDtcgTree, writeTokenSet, } from "../io";
+// =============================================================================
+// Git-Only Provider — DTCG-only, no design tool
+// =============================================================================
+// This is the zero-config default for indie hackers, AI-driven dev workflows,
+// and any team that does NOT use a design tool. It treats the local
+// `packages/design/design-tokens/tokens` directory as the single source of truth.
+//
+// `pull` simply re-reads the DTCG files (a no-op refresh).
+// `push` validates + re-serialises (formats) the DTCG files in place.
+// =============================================================================
+export class GitOnlyProvider {
+    name = "git-only";
+    tokensDir;
+    tokensStudioDir;
+    constructor(config) {
+        this.tokensDir = config.tokensDir ?? defaultTokensDir();
+        this.tokensStudioDir = config.tokensStudioDir ?? defaultTokensStudioDir();
+        logger.info("[design-sync:git-only] Provider initialised", {
+            tokensDir: this.tokensDir,
+        });
+    }
+    async pull(options = {}) {
+        const sets = await readTokenSets(this.tokensDir);
+        const filtered = filterSets(sets, options.themes);
+        return {
+            sets: filtered,
+            written: false,
+            provider: "git-only",
+            pulledAt: new Date().toISOString(),
+            summary: `Read ${filtered.length} DTCG token set(s) from ${this.tokensDir}`,
+        };
+    }
+    async push(options = {}) {
+        const all = await readTokenSets(this.tokensDir);
+        const sets = filterSets(all, options.themes);
+        // Validate every set before re-serialising — fail closed on bad DTCG.
+        for (const set of sets) {
+            const errors = validateDtcgTree(set.tokens);
+            if (errors.length > 0) {
+                throw new Error(`[design-sync:git-only] DTCG validation failed for ${set.relativePath}:\n  - ${errors.join("\n  - ")}`);
+            }
+        }
+        const dryRun = options.dryRun ?? false;
+        if (!dryRun) {
+            for (const set of sets) {
+                await writeTokenSet(this.tokensDir, set);
+            }
+        }
+        return {
+            pushed: !dryRun,
+            sets: sets.map((s) => s.relativePath),
+            provider: "git-only",
+            pushedAt: new Date().toISOString(),
+            summary: dryRun
+                ? `Validated ${sets.length} DTCG file(s) (dry-run, no files modified)`
+                : `Reformatted ${sets.length} DTCG file(s) under ${this.tokensDir}`,
+            dryRun,
+        };
+    }
+    async healthcheck() {
+        const detected = [];
+        const missing = [];
+        try {
+            const info = await stat(this.tokensDir);
+            if (info.isDirectory()) {
+                detected.push("tokensDir");
+            }
+            else {
+                missing.push("tokensDir (not a directory)");
+            }
+        }
+        catch {
+            missing.push("tokensDir (does not exist)");
+        }
+        try {
+            const info = await stat(this.tokensStudioDir);
+            if (info.isDirectory()) {
+                detected.push("tokensStudioDir");
+            }
+        }
+        catch {
+            // tokens-studio dir is optional for git-only mode
+        }
+        const ok = missing.length === 0;
+        return {
+            ok,
+            provider: "git-only",
+            message: ok
+                ? `git-only ready — DTCG source dir found at ${this.tokensDir}`
+                : `git-only misconfigured — missing: ${missing.join(", ")}`,
+            detectedEnv: detected,
+            missingEnv: missing,
+        };
+    }
+}
+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/providers/memory.d.ts

@@ -0,0 +1,17 @@
+import type { DesignSyncProvider, DesignTokenSet, HealthStatus, MemoryProviderConfig, PullOptions, PullResult, PushOptions, PushResult } from "../types";
+export declare class MemoryProvider implements DesignSyncProvider {
+    readonly name: "memory";
+    private sets;
+    readonly pullCalls: PullOptions[];
+    readonly pushCalls: PushOptions[];
+    constructor(config: MemoryProviderConfig);
+    pull(options?: PullOptions): Promise<PullResult>;
+    push(options?: PushOptions): Promise<PushResult>;
+    healthcheck(): Promise<HealthStatus>;
+    /**
+     * Replace the in-memory set list — useful in tests for asserting how
+     * the provider responds to different remote states.
+     */
+    replaceSets(sets: DesignTokenSet[]): void;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/providers/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/providers/memory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,EACX,MAAM,UAAU,CAAC;AAWlB,qBAAa,cAAe,YAAW,kBAAkB;IACvD,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAElC,OAAO,CAAC,IAAI,CAAmB;IAC/B,SAAgB,SAAS,EAAE,WAAW,EAAE,CAAM;IAC9C,SAAgB,SAAS,EAAE,WAAW,EAAE,CAAM;gBAElC,MAAM,EAAE,oBAAoB;IAKlC,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAYpD,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAcpD,WAAW,IAAI,OAAO,CAAC,YAAY,CAAC;IAU1C;;;OAGG;IACH,WAAW,CAAC,IAAI,EAAE,cAAc,EAAE,GAAG,IAAI;CAG1C"}

package/dist/providers/memory.js

@@ -0,0 +1,65 @@
+import { logger } from "@nebutra/logger";
+// =============================================================================
+// Memory Provider — in-memory test fixture
+// =============================================================================
+// Used in unit tests and CI dry-runs where touching the filesystem or
+// hitting a remote API would be wasteful. Tracks `pull`/`push` calls so
+// tests can assert behaviour.
+// NOT for production.
+// =============================================================================
+export class MemoryProvider {
+    name = "memory";
+    sets;
+    pullCalls = [];
+    pushCalls = [];
+    constructor(config) {
+        this.sets = config.initialSets ?? [];
+        logger.info("[design-sync:memory] Provider initialised (test fixture only)");
+    }
+    async pull(options = {}) {
+        this.pullCalls.push(options);
+        const sets = filterSets(this.sets, options.themes);
+        return {
+            sets,
+            written: false,
+            provider: "memory",
+            pulledAt: new Date().toISOString(),
+            summary: `memory: returned ${sets.length} in-memory token set(s)`,
+        };
+    }
+    async push(options = {}) {
+        this.pushCalls.push(options);
+        const filtered = filterSets(this.sets, options.themes);
+        const dryRun = options.dryRun ?? false;
+        return {
+            pushed: !dryRun,
+            sets: filtered.map((s) => s.relativePath),
+            provider: "memory",
+            pushedAt: new Date().toISOString(),
+            summary: `memory: ${dryRun ? "dry-run" : "applied"} ${filtered.length} set(s)`,
+            dryRun,
+        };
+    }
+    async healthcheck() {
+        return {
+            ok: true,
+            provider: "memory",
+            message: "memory provider always healthy (test fixture)",
+            detectedEnv: [],
+            missingEnv: [],
+        };
+    }
+    /**
+     * Replace the in-memory set list — useful in tests for asserting how
+     * the provider responds to different remote states.
+     */
+    replaceSets(sets) {
+        this.sets = [...sets];
+    }
+}
+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/providers/penpot.d.ts

@@ -0,0 +1,21 @@
+import type { DesignSyncProvider, HealthStatus, PenpotProviderConfig, PullOptions, PullResult, PushOptions, PushResult } from "../types";
+export declare class PenpotProvider implements DesignSyncProvider {
+    readonly name: "penpot";
+    private readonly tokensDir;
+    private readonly tokensStudioDir;
+    private readonly apiUrl;
+    private readonly token;
+    private readonly fileId;
+    private readonly teamId;
+    constructor(config: PenpotProviderConfig);
+    pull(options?: PullOptions): Promise<PullResult>;
+    push(options?: PushOptions): Promise<PushResult>;
+    healthcheck(): Promise<HealthStatus>;
+    /**
+     * Reserved for future use — exposes the configured tokens-studio directory
+     * so consumers (e.g. CI workflows) can attach Penpot-side metadata mirrors.
+     */
+    getTokensStudioDir(): string;
+    private credsReady;
+}
+//# sourceMappingURL=penpot.d.ts.map

package/dist/providers/penpot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"penpot.d.ts","sourceRoot":"","sources":["../../src/providers/penpot.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,oBAAoB,EACpB,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,EACX,MAAM,UAAU,CAAC;AAmBlB,qBAAa,cAAe,YAAW,kBAAkB;IACvD,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAElC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;gBAEhC,MAAM,EAAE,oBAAoB;IAelC,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IA0BpD,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IA8CpD,WAAW,IAAI,OAAO,CAAC,YAAY,CAAC;IAyB1C;;;OAGG;IACH,kBAAkB,IAAI,MAAM;IAI5B,OAAO,CAAC,UAAU;CAGnB"}