@nebutra/design-sync 0.1.0 → 0.1.2

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, "");
+        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/design-md.d.ts

@@ -0,0 +1,49 @@
+import type { LintReport } from "@google/design.md/linter";
+import type { DesignMdProviderConfig, DesignSyncProvider, HealthStatus, PullOptions, PullResult, PushOptions, PushResult } from "../types";
+export { type ImportReport, importFromDesignMd } from "../serialize/from-design-md";
+/**
+ * Derive the preview file path from the DESIGN.md path.
+ *
+ * Replaces a trailing `.md` extension with `.preview.html`;
+ * if the path does not end in `.md`, appends `.preview.html`.
+ *
+ * Examples:
+ *   "/repo/DESIGN.md"        → "/repo/DESIGN.preview.html"
+ *   "/repo/design/tokens.md" → "/repo/design/tokens.preview.html"
+ *   "/repo/DESIGN"           → "/repo/DESIGN.preview.html"
+ */
+export declare function previewHtmlPathFor(mdPath: string): string;
+/**
+ * Throw if the LintReport contains any error-severity findings.
+ * Warnings do not throw — they are surfaced in the push summary.
+ * Used as the fail-closed gate before writing a DESIGN.md.
+ *
+ * Fail-closed on either signal: error-severity findings in `findings[]`
+ * OR a non-zero `summary.errors` count.
+ *
+ * @param report - The LintReport returned by `lint(content)`.
+ * @param source - A human-readable label for the file (used in the error message).
+ * @throws When error-severity findings are present or `summary.errors > 0`.
+ */
+export declare function assertLintClean(report: LintReport, source: string): void;
+/**
+ * Dynamically imports the @google/design.md linter and runs it on `content`.
+ * Extracted as a named export so tests can verify the `[design-md]`-prefixed
+ * error thrown when the dynamic import or lint call itself fails.
+ *
+ * @throws When the linter import or invocation throws — error is wrapped with a
+ *   `[design-md] Lint gate failed to run on <label>:` prefix.
+ */
+export declare function runLintGate(content: string, label: string): Promise<LintReport>;
+export declare class DesignMdProvider implements DesignSyncProvider {
+    readonly name: "design-md";
+    private readonly tokensDir;
+    private readonly designMdPath;
+    private readonly designSystemName;
+    private readonly designSystemDescription;
+    constructor(config: DesignMdProviderConfig);
+    pull(options?: PullOptions): Promise<PullResult>;
+    push(options?: PushOptions): Promise<PushResult>;
+    healthcheck(): Promise<HealthStatus>;
+}
+//# sourceMappingURL=design-md.d.ts.map

package/dist/providers/design-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"design-md.d.ts","sourceRoot":"","sources":["../../src/providers/design-md.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAM3D,OAAO,KAAK,EACV,sBAAsB,EACtB,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,EACX,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,KAAK,YAAY,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAuBpF;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKzD;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAUxE;AAID;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CASrF;AAID,qBAAa,gBAAiB,YAAW,kBAAkB;IACzD,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAU;IAErC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAqB;gBAEjD,MAAM,EAAE,sBAAsB;IAcpC,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAuDpD,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAoEpD,WAAW,IAAI,OAAO,CAAC,YAAY,CAAC;CAyD3C"}

package/dist/providers/design-md.js

@@ -0,0 +1,264 @@
+import { access, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { logger } from "@nebutra/logger";
+import { defaultTokensDir, readTokenSets, writeTokenSet } from "../io";
+import { importFromDesignMd } from "../serialize/from-design-md";
+import { serializeToDesignMd } from "../serialize/to-design-md";
+import { serializeToPreviewHtml } from "../serialize/to-preview-html";
+export { importFromDesignMd } from "../serialize/from-design-md";
+// =============================================================================
+// DesignMd Provider — AI-native DESIGN.md format (@google/design.md)
+// =============================================================================
+// The "design tool" here is a DESIGN.md file in the repo root (or a
+// configurable path). Push = repo DTCG → DESIGN.md (with official lint gate).
+// Pull = DESIGN.md → a `themes/<brand>.json` DTCG file in tokensDir.
+//
+// Why DESIGN.md?
+//   - Zero external dependencies at runtime (just a file in git)
+//   - AI-native: models can read/write DESIGN.md directly
+//   - Google's @google/design.md spec mandates lint rules (broken-ref, contrast)
+//   - Bridges the gap for indie hackers who want typed tokens without a design tool
+// =============================================================================
+/**
+ * Default DESIGN.md path: <cwd>/DESIGN.md
+ */
+function defaultDesignMdPath(cwd = process.cwd()) {
+    return join(cwd, "DESIGN.md");
+}
+/**
+ * Derive the preview file path from the DESIGN.md path.
+ *
+ * Replaces a trailing `.md` extension with `.preview.html`;
+ * if the path does not end in `.md`, appends `.preview.html`.
+ *
+ * Examples:
+ *   "/repo/DESIGN.md"        → "/repo/DESIGN.preview.html"
+ *   "/repo/design/tokens.md" → "/repo/design/tokens.preview.html"
+ *   "/repo/DESIGN"           → "/repo/DESIGN.preview.html"
+ */
+export function previewHtmlPathFor(mdPath) {
+    if (mdPath.endsWith(".md")) {
+        return `${mdPath.slice(0, -3)}.preview.html`;
+    }
+    return `${mdPath}.preview.html`;
+}
+// ─── Lint Gate ────────────────────────────────────────────────────────────────
+/**
+ * Throw if the LintReport contains any error-severity findings.
+ * Warnings do not throw — they are surfaced in the push summary.
+ * Used as the fail-closed gate before writing a DESIGN.md.
+ *
+ * Fail-closed on either signal: error-severity findings in `findings[]`
+ * OR a non-zero `summary.errors` count.
+ *
+ * @param report - The LintReport returned by `lint(content)`.
+ * @param source - A human-readable label for the file (used in the error message).
+ * @throws When error-severity findings are present or `summary.errors > 0`.
+ */
+export function assertLintClean(report, source) {
+    const errorFindings = report.findings.filter((f) => f.severity === "error");
+    if (errorFindings.length === 0 && report.summary.errors === 0)
+        return;
+    const count = errorFindings.length || report.summary.errors;
+    const detail = errorFindings
+        .map((f) => (f.path ? `  ${f.path}: ${f.message}` : `  ${f.message}`))
+        .join("\n");
+    throw new Error(`[design-md] Lint failed for ${source} — ${count} error(s):\n${detail}`);
+}
+// ─── Lint Runner ─────────────────────────────────────────────────────────────
+/**
+ * Dynamically imports the @google/design.md linter and runs it on `content`.
+ * Extracted as a named export so tests can verify the `[design-md]`-prefixed
+ * error thrown when the dynamic import or lint call itself fails.
+ *
+ * @throws When the linter import or invocation throws — error is wrapped with a
+ *   `[design-md] Lint gate failed to run on <label>:` prefix.
+ */
+export async function runLintGate(content, label) {
+    try {
+        const { lint } = await import("@google/design.md/linter");
+        return lint(content);
+    }
+    catch (err) {
+        throw new Error(`[design-md] Lint gate failed to run on ${label}: ${err?.message ?? String(err)}`);
+    }
+}
+// ─── Provider ────────────────────────────────────────────────────────────────
+export class DesignMdProvider {
+    name = "design-md";
+    tokensDir;
+    designMdPath;
+    designSystemName;
+    designSystemDescription;
+    constructor(config) {
+        this.tokensDir = config.tokensDir ?? defaultTokensDir();
+        this.designMdPath = config.designMdPath ?? process.env.DESIGN_MD_PATH ?? defaultDesignMdPath();
+        this.designSystemName = config.name;
+        this.designSystemDescription = config.description;
+        logger.info("[design-sync:design-md] Provider initialised", {
+            tokensDir: this.tokensDir,
+            designMdPath: this.designMdPath,
+        });
+    }
+    // ── Pull: DESIGN.md → tokensDir/themes/<brand>.json ──────────────────────
+    async pull(options = {}) {
+        // Graceful handling: if DESIGN.md does not exist, return an empty result.
+        let content;
+        try {
+            content = await readFile(this.designMdPath, "utf8");
+        }
+        catch {
+            logger.warn("[design-sync:design-md] DESIGN.md not found, returning empty pull result", {
+                designMdPath: this.designMdPath,
+            });
+            return {
+                sets: [],
+                written: false,
+                provider: "design-md",
+                pulledAt: new Date().toISOString(),
+                summary: `design-md: DESIGN.md not found at ${this.designMdPath} — no sets pulled`,
+            };
+        }
+        const { set, report } = importFromDesignMd(content);
+        if (report.warnings.length > 0 || report.missingRequired.length > 0) {
+            logger.warn("[design-sync:design-md] imported DESIGN.md has gaps", {
+                warnings: report.warnings.length,
+                missingRequired: report.missingRequired,
+            });
+        }
+        const dryRun = options.dryRun ?? false;
+        if (!dryRun) {
+            await writeTokenSet(this.tokensDir, set);
+            logger.info("[design-sync:design-md] pull wrote token set", {
+                relativePath: set.relativePath,
+            });
+        }
+        const missingCount = report.missingRequired.length;
+        const unmappedCount = report.unmapped.length;
+        const reportSuffix = missingCount > 0 || unmappedCount > 0
+            ? ` (missingRequired: ${missingCount}, unmapped: ${unmappedCount})`
+            : "";
+        return {
+            sets: [set],
+            written: !dryRun,
+            provider: "design-md",
+            pulledAt: new Date().toISOString(),
+            summary: dryRun
+                ? `design-md: dry-run — would write ${set.relativePath}${reportSuffix}`
+                : `design-md: wrote ${set.relativePath}${reportSuffix}`,
+        };
+    }
+    // ── Push: tokensDir → DESIGN.md (with official lint gate) ────────────────
+    async push(options = {}) {
+        const all = await readTokenSets(this.tokensDir);
+        // Serialize all sets into DESIGN.md content.
+        const content = serializeToDesignMd(all, {
+            ...(this.designSystemName !== undefined ? { name: this.designSystemName } : {}),
+            ...(this.designSystemDescription !== undefined
+                ? { description: this.designSystemDescription }
+                : {}),
+        });
+        // Compute a consistent, human-readable path label (relative preferred).
+        const mdLabel = relative(process.cwd(), this.designMdPath) || this.designMdPath;
+        // Run the official lint gate — fail closed on any error finding.
+        const lintReport = await runLintGate(content, mdLabel);
+        // Collect warnings for the summary (they don't block the write).
+        const warnings = lintReport.findings
+            .filter((f) => f.severity === "warning")
+            .map((f) => (f.path ? `${f.path}: ${f.message}` : f.message));
+        // Throw if any error-severity findings are present.
+        assertLintClean(lintReport, mdLabel);
+        // Compute the sibling preview path (before the write, so it's always defined)
+        const previewPath = previewHtmlPathFor(this.designMdPath);
+        const dryRun = options.dryRun ?? false;
+        if (!dryRun) {
+            await mkdir(dirname(this.designMdPath), { recursive: true });
+            await writeFile(this.designMdPath, content, "utf8");
+            logger.info("[design-sync:design-md] push wrote DESIGN.md", {
+                designMdPath: this.designMdPath,
+                sets: all.length,
+            });
+            // Generate and write the sibling visual preview
+            const previewHtml = serializeToPreviewHtml(all, {
+                ...(this.designSystemName !== undefined ? { name: this.designSystemName } : {}),
+            });
+            await writeFile(previewPath, previewHtml, "utf8");
+            logger.info("[design-sync:design-md] push wrote preview", {
+                previewPath,
+            });
+        }
+        else {
+            logger.info("[design-sync:design-md] push dry-run — lint passed, files NOT written", {
+                designMdPath: this.designMdPath,
+                previewPath,
+            });
+        }
+        const warnSuffix = warnings.length > 0 ? ` (${warnings.length} warning(s))` : "";
+        return {
+            pushed: !dryRun,
+            sets: dryRun ? [this.designMdPath] : [this.designMdPath, previewPath],
+            provider: "design-md",
+            pushedAt: new Date().toISOString(),
+            summary: dryRun
+                ? `design-md: dry-run — lint passed, would write ${mdLabel}${warnSuffix}`
+                : `design-md: wrote ${mdLabel} from ${all.length} DTCG set(s)${warnSuffix}`,
+            dryRun,
+        };
+    }
+    // ── Healthcheck ───────────────────────────────────────────────────────────
+    async healthcheck() {
+        const detected = [];
+        const missing = [];
+        // 1. Check tokensDir exists.
+        let tokensDirOk = false;
+        try {
+            const info = await stat(this.tokensDir);
+            if (info.isDirectory()) {
+                tokensDirOk = true;
+                detected.push("tokensDir");
+            }
+            else {
+                missing.push("tokensDir (not a directory)");
+            }
+        }
+        catch {
+            missing.push("tokensDir (does not exist)");
+        }
+        // 2. Check the @google/design.md lib is importable (it's a dep, should always be).
+        let lintLibOk = false;
+        try {
+            await import("@google/design.md/linter");
+            lintLibOk = true;
+            detected.push("@google/design.md");
+        }
+        catch {
+            missing.push("@google/design.md (lib not importable)");
+        }
+        // 3. List DESIGN_MD_PATH in detectedEnv when it's set (it's optional, not required).
+        const envPath = process.env.DESIGN_MD_PATH;
+        if (envPath) {
+            detected.push(`DESIGN_MD_PATH=${envPath}`);
+        }
+        // 4. Check the parent directory of designMdPath is accessible.
+        let mdDirOk = false;
+        const mdDir = dirname(this.designMdPath);
+        try {
+            await access(mdDir);
+            mdDirOk = true;
+            detected.push("designMdPath.parent");
+        }
+        catch {
+            missing.push("designMdPath.parent (not accessible)");
+        }
+        const ok = tokensDirOk && lintLibOk && mdDirOk;
+        return {
+            ok,
+            provider: "design-md",
+            message: ok
+                ? `design-md: ready — tokensDir found, lint lib present, designMdPath=${this.designMdPath}`
+                : `design-md: not ready — missing: ${missing.join(", ")}`,
+            detectedEnv: detected,
+            missingEnv: missing,
+        };
+    }
+}

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