@nebutra/design-sync 0.1.0 → 0.1.2

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"}

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/serialize/from-design-md.d.ts

@@ -0,0 +1,80 @@
+/**
+ * DESIGN.md → DTCG theme importer
+ *
+ * Parse approach: programmatic via `lint()` from `@google/design.md/linter`.
+ * The `lint()` function parses the DESIGN.md content synchronously and returns
+ * a `DesignSystemState` with typed Maps for colors, rounded, spacing, and
+ * typography. We reshape that state into our DTCG naming convention:
+ *   - colors.<x>   → color.<x>    ($type: "color",      $value: hex string)
+ *   - rounded.<x>  → radius.<x>   ($type: "dimension",  $value: "<n><unit>" string)
+ *   - spacing.<x>  → spacing.<x>  ($type: "dimension",  $value: "<n><unit>" string)
+ *   - body font    → fontFamily.sans ($type: "fontFamily", $value: string)
+ *
+ * PROSE-COLOR FALLBACK: When @google/design.md extracts zero colors (e.g. the
+ * VoltAgent extended DESIGN.md format where colors are written as markdown prose
+ * rather than YAML front-matter), `extractColorsFromProse` is called to scrape
+ * labeled color literals of the form `**Label** (\`<value>\`)`.
+ *
+ * NEVER import `@google/design.md` (main entry — auto-runs CLI). Only the
+ * `@google/design.md/linter` subpath export is used here.
+ *
+ * All @google/design.md coupling is isolated in THIS file.
+ */
+import type { DesignTokenSet } from "../types";
+export interface ImportReport {
+    /** Human-readable strings noting content that has no structured DTCG equivalent. */
+    unmapped: string[];
+    /** Registry-required token keys absent from the produced tree (dot-path format). */
+    missingRequired: string[];
+    /** Non-fatal warnings encountered during import. */
+    warnings: string[];
+}
+export interface ImportResult {
+    set: DesignTokenSet;
+    report: ImportReport;
+}
+export interface ImportFromDesignMdOptions {
+    /**
+     * Override the slug used for `relativePath` and `name`.
+     * Takes precedence over the `name` field in the DESIGN.md front matter.
+     */
+    brandName?: string;
+}
+/**
+ * Extract color entries from DESIGN.md prose content (VoltAgent extended format).
+ *
+ * Looks for labeled color literals matching: `**Label** (\`<value>\`)`
+ * where `<value>` is a valid CSS color (hex, rgb, rgba, hsl, hsla, oklch).
+ *
+ * Also handles the `{colors.xxx} — #hex` variant (backtick-quoted or unquoted hex).
+ *
+ * Scoping: if a heading matching `/^#{1,3}\s+.*colou?r/i` exists in the
+ * document, extraction is limited to the content under that heading (up to
+ * the next same-or-higher heading). Otherwise the whole document is scanned.
+ *
+ * Effect labels (shadow, overlay, glow, gradient, elevation, blur, scrim) are
+ * excluded regardless of scoping — they describe visual effects, not palette colors.
+ *
+ * Token naming: labels are kebab-cased (`"Spotify Green"` → `"spotify-green"`).
+ * De-duplicates by token name (first wins). Capped at 48 entries.
+ *
+ * Returns a plain `Record<string, string>` mapping slug → raw CSS color string.
+ *
+ * @public — exported so tests can unit-test the helper directly.
+ */
+export declare function extractColorsFromProse(content: string): Record<string, string>;
+/**
+ * Parse a DESIGN.md document and produce a DTCG-compliant `DesignTokenSet`
+ * scoped to the `themes/` bucket (SSOT-safe — never overwrites core or semantic).
+ *
+ * The function is SYNCHRONOUS; it never reads from or writes to the filesystem.
+ *
+ * @param content - Raw DESIGN.md content (markdown + YAML front matter).
+ * @param options - Optional: `brandName` to override the slug.
+ * @returns `ImportResult` containing the token set and a diagnostic report.
+ * @throws If `@google/design.md` fails to parse the content, or if the produced
+ *         DTCG tree is invalid (invalid leaves). Empty input produces an
+ *         empty-but-valid tree and does NOT throw.
+ */
+export declare function importFromDesignMd(content: string, options?: ImportFromDesignMdOptions): ImportResult;
+//# sourceMappingURL=from-design-md.d.ts.map

package/dist/serialize/from-design-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-design-md.d.ts","sourceRoot":"","sources":["../../src/serialize/from-design-md.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,UAAU,CAAC;AAIhE,MAAM,WAAW,YAAY;IAC3B,oFAAoF;IACpF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oFAAoF;IACpF,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAg5BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO9E;AAsKD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,yBAAyB,GAClC,YAAY,CA0Td"}