feat(figma): guard exports and verify write readback

[GarthDB]

Description

Add concurrency guards and readback verification to design-data figma export.

• Capture a lossless baseline, build an immutable payload, and re-check live state immediately before POST. Only collection variableIds ordering is normalized; mode order and all other metadata remain significant.
• Verify CREATE temporary-ID mappings, emitted metadata, scalar/color values, aliases and target IDs, plus unchanged unrelated/deprecated variables, modes and collections. Report verified success only after readback.
• On ambiguous transport failures, server errors or malformed POST responses, perform one read-only probe and return an actionable nonzero error. Disable mutation retries and redirects; do not echo credentials or API error bodies.
• Add explicit concurrency/readback bypass flags, configurable absolute numeric tolerance (default 1e-6), fresh-directory verification reports and a hidden loopback-only API override for offline tests.
• Include guard and mock-server tests, CLI help, SDK/roadmap documentation and a minor changeset for @adobe/design-data-tui, which distributes the CLI.

Related Issue

Bead spectrum-design-data-11k.25: Add concurrency guards and readback verification to Figma CLI writes.
Parent epic: spectrum-design-data-11k.

Motivation and Context

The previous export path fetched variables, built a payload, posted it and printed Done without checking concurrent edits or verifying the resulting file. This promotes the safeguards proven in the earlier publication scripts into the normal CLI path.

Typed snapshots omit API metadata such as collection isExtension and can round JSON floats. The guard therefore retains original number text locally with RawValue, while parsing typed mapping data from the same response bytes. A workspace-wide arbitrary_precision feature was rejected because it changed native MessagePack cache serialization and caused WASM parity failures; the final implementation preserves that compatibility.

The final GET and POST are not atomic, so a residual concurrency window remains and is documented. Collection/mode mutations are rejected rather than left unverified. Explicitly skipping readback produces an unverified write warning, not verified-success output.

How Has This Been Tested?

Validated locally on macOS using the repository's pinned Rust toolchain and pnpm 10.17.1:

• moon run :test sdk:lint sdk:fmt-check sdk:test-doc — passed; 35 tasks completed, including 1,543 passing Rust tests with 2 existing skips and the WASM parity suite.
• node tools/changeset-linter/src/cli.js check --fail-on-warnings — passed, no warnings or errors.
• git diff --cached --check — passed before committing.

Offline tests cover concurrent metadata/mode-order drift blocking POST, membership-only reordering, CREATE/UPDATE and temporary-ID remapping, aliases, preserved unrelated/deprecated state, numeric tolerance thresholds, readback mismatches and missing targets/mappings, ambiguous outcomes with exactly one POST, explicit bypass warnings, dry-run behavior, report reuse rejection and credential-safe diagnostics.

All Figma HTTP tests use a local loopback server. No shared Figma file was mutated, and no separate Figma library Publish was performed. Live writes still require separate explicit approval.

Screenshots (if appropriate):

Not applicable; CLI safety checks and offline HTTP behavior.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• I have signed the Adobe Open Source CLA.
• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[changeset-bot]

🦋 Changeset detected

Latest commit: 642864f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@adobe/design-data-tui	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

🧩 Component Schema Changes Report

No component schema changes detected.

This comment was automatically generated by the component schema diff tool. 🤖

[github-actions]

🎨 Token Changes Report

Tokens Changed (0)

Original Branch: main

---

This comment was automatically generated by the token diff tool. 🤖

[github-actions]

Run report for 642864ff

Total time: 2m 4s | Comparison time: 3m 46s | Estimated savings: 1m 42s (45.3% faster)

	Action	Time	Status	Info
⬛️	SetupProto(0.57.4)	0ms	Skipped
🟩	SyncWorkspace	7.5ms	Passed
🟩	SyncProject(sdk)	0.3ms	Passed
⬛️	SetupToolchain(node:20.17.0)	565.5ms	Skipped
⬛️	SetupToolchain(rust:1.88.0)	892.4ms	Skipped
🟩	SetupEnvironment(rust, sdk)	70.1ms	Passed
⬛️	InstallDependencies(rust, sdk)	7ms	Skipped
⬛️	SetupToolchain(pnpm:10.17.1)	464.2ms	Skipped
⬛️	SetupToolchain(javascript)	0ms	Skipped
⬛️	SetupEnvironment(javascript, sdk)	0.5ms	Skipped
🟩	RunTask(sdk:fmt-check)	587ms	Passed
🟩	InstallDependencies(javascript, sdk)	3.7s	Passed
🟩	RunTask(sdk:codegen-check)	74ms	Passed
🟩	RunTask(sdk:lint)	49.6s	Passed
🟩	RunTask(sdk:test-doc)	1m 30s	Passed
🟩	RunTask(sdk:test)	1m 59s	Passed

Changed files

.changeset/figma-write-verification.md
docs/token-studio-sunset.md
sdk/Cargo.lock
sdk/README.md
sdk/cli/Cargo.toml
sdk/cli/src/main.rs
sdk/cli/tests/cli_figma_write.rs
sdk/plugins/figma/Cargo.toml
sdk/plugins/figma/src/api.rs
sdk/plugins/figma/src/lib.rs
sdk/plugins/figma/src/write_guard.rs