Mirascope Registry Sync Tool Spec

Purpose

Enable consuming projects to maintain automatic synchronization with mirascope/ui as the single source of truth, departing from shadcn's "copy then own" philosophy in favor of "sync and stay current."

Core Philosophy

mirascope/ui is SoT: Components should stay in sync with upstream
Explicit tracking: Clear visibility into what comes from registry vs local code
Automated updates: Enable daily sync checks and PR automation
Selective sync: Only update components you've chosen to use

Architecture

Distribution

Sync tool ships as part of @mirascope/ui package
Consuming projects: bun add -D @mirascope/ui
CLI available as: bun mirascope-ui-sync (or npx mirascope-ui-sync)

File Organization (in consuming projects)

src/
├── components/ui/          # Local components  
├── registry/               # Synced from mirascope/ui
    ├── manifest.json      # Tracking file
    ├── ui/                # Registry UI components
    ├── blocks/            # Registry blocks
    └── lib/               # Registry utilities

Manifest File Format

{
  "registryUrl": "https://ui.mirascope.com",
  "components": {
    "button": {
      "version": "main",
      "lastSync": "2025-01-15T10:30:00Z",
      "files": ["src/registry/ui/button.tsx"]
    },
    "dialog": {
      "version": "main", 
      "lastSync": "2025-01-15T10:30:00Z",
      "files": ["src/registry/ui/dialog.tsx"]
    }
  },
  "lastFullSync": "2025-01-15T10:30:00Z"
}

Command Interface

`mirascope-ui-sync` (no args)

Reads manifest
Syncs all tracked components to latest
Updates manifest timestamps
Reports what changed

`mirascope-ui-sync only button dialogue`

Reads manifest
Syncs only named components to latest
Updates manifest timestamps
Reports what changed

`mirascope-ui-sync add button dialog`

Adds new components to manifest
Downloads component files
Installs any npm dependencies
Updates manifest

`mirascope-ui-sync remove button`

Removes component files
Updates manifest
(Optional) Warns about unused dependencies

`mirascope-ui-sync status`

Shows what's tracked
Shows last sync times
Checks for available updates (without applying)

Sync Process

Read manifest - determine what should be synced
Fetch registry - get latest component definitions
Download files - pull latest versions of tracked components
Install dependencies - run npm/bun install for new deps
Update files - overwrite existing registry files
Update manifest - record new sync timestamps
Report changes - show what was updated

Integration Points

Package.json Scripts

{
  "scripts": {
    "sync-registry": "mirascope-ui-sync",
    "sync-registry:check": "mirascope-ui-sync status"
  }
}

GitHub Actions Integration

Daily workflow runs mirascope-ui-sync status
If updates available, runs mirascope-ui-sync
Creates PR with changes and updated manifest
PR description shows which components were updated
Ideally: Create 1 PR per updated component (for clarity of testing)

Key Behaviors

Overwrite Strategy

Registry files are always overwritten on sync
No merge conflicts - mirascope/ui wins
Clear separation from local components prevents accidental modifications

Dependency Management

Sync tool installs npm dependencies (via bun) declared in registry
Doesn't remove dependencies (to avoid breaking local code)
Could warn about potentially unused registry dependencies

Error Handling

Network failures: retry with backoff
File permission issues: clear error messages
Invalid manifest: Fail noisily
Missing components in registry: skip with warning

Potential Future Enhancements

Version pinning: Pin components to specific commits/tags instead of "main"
Conflict detection: Warn if local modifications detected in registry files

teamdandelion/mirascope-ui-sync.md