Aurora Sheets Sync

When to Use

• User wants to sync YAML schemas to Google Sheets (push)
• User wants to sync Google Sheets to YAML schemas (pull)
• User mentions "sincronizar", "spreadsheet", "google sheets", "exportar schemas"
• Troubleshooting sync issues or configuration problems

Critical Patterns

1. Spreadsheet Structure

2. Module Sheet Format

• Row 1: Headers (read dynamically)
• Row 2+: Properties (one per row)
• Booleans: ✓ (CHAR 9989) = true, empty = false

3. Pull is Idempotent

Rule: If no content changes in spreadsheet, YAML files must NOT be modified.

// Content comparison before writing
if (normalizeYamlForComparison(existing) === normalizeYamlForComparison(new)) {
  // Skip write - preserves original formatting
}

4. Preserve Fields Not in Spreadsheet

Fields in YAML without spreadsheet columns are preserved on pull:

• relationship.singularName, relationship.aggregateName, relationship.modulePath
• relationship.key, relationship.field, relationship.avoidConstraint
• webComponent

5. Field Mappings

6. Array Format in YAML

Inline format [A, B, C]:

• enumOptions
• decimals
• defaultValue (when array)

Multi-line format (for readability):

• excludedOperations
• excludedFiles

7. Nullable and DefaultValue Rules

• nullable: If not checked (✓), defaults to false (never undefined)
• defaultValue: Wrapped in array [value] when type=array
• description: Format preserved even when field is renamed (matched by content)

Commands

# Navigate to tool directory
cd scripts/aurora-sheets-sync

# Install dependencies (first time)
npm install

# Push: YAML → Google Sheets
npx ts-node src/index.ts push --bc business-partner-portal
npx ts-node src/index.ts push --all
npx ts-node src/index.ts push --bc iam --dry-run

# Pull: Google Sheets → YAML
npx ts-node src/index.ts pull --bc business-partner-portal
npx ts-node src/index.ts pull --bc iam --no-backup
npx ts-node src/index.ts pull --all --dry-run

# Validate connection
npx ts-node src/index.ts validate --bc business-partner-portal

# List configured bounded contexts
npx ts-node src/index.ts list

Configuration

aurora-sheets.config.json

{
  "credentialsPath": "./scripts/aurora-sheets-sync/credentials/service-account.json",
  "boundedContexts": {
    "business-partner-portal": {
      "spreadsheetId": "1ABC123xyz...",
      "description": "Business Partner Portal"
    }
  },
  "backupsPath": "backups/aurora-schemas",
  "cliterPath": "cliter"
}

Google Cloud Setup (Quick Reference)

1. Create project in Google Cloud Console
2. Enable Google Sheets API (APIs & Services → Library)
3. Create Service Account (APIs & Services → Credentials)
4. Download JSON key → save to credentials/service-account.json
5. Share spreadsheet with service account email (Editor role)

Troubleshooting

Key Files

scripts/aurora-sheets-sync/
├── src/
│   ├── index.ts                    # CLI entry point
│   ├── sync/
│   │   ├── yaml-to-sheet.ts        # Push logic
│   │   └── sheet-to-yaml.ts        # Pull logic (idempotent)
│   └── transformers/
│       └── property-transformer.ts  # YAML ↔ Row conversion
├── credentials/
│   └── service-account.json        # Google credentials (gitignored)
├── CONTEXT.md                      # Technical documentation
└── README.md                       # User guide

Resources

• Technical Context: See CONTEXT.md
• User Guide: See README.md