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

Sheet Purpose

DATA

Dropdown values, validations (don't modify)

TEMPLATE

Template duplicated for new modules

MODULES

Index with hyperlinks to module sheets

{module-name}

One sheet per module (e.g., business-partner )

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

Sheet Column YAML Field Notes

relationship

relationship.type

1:1 , N:1 , 1:N , N:N

master

relationship.modulePath

Module name only

subtype

arrayOptions.type

When type=array

values

Multiple enumOptions , decimals , or arrayOptions.enumOptions

hasAuth

hasOAuth

Header mapping

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)

• Create project in Google Cloud Console

• Enable Google Sheets API (APIs & Services → Library)

• Create Service Account (APIs & Services → Credentials)

• Download JSON key → save to credentials/service-account.json

• Share spreadsheet with service account email (Editor role)

Troubleshooting

Error Solution

The caller does not have permission

Share spreadsheet with service account email

Google Sheets API has not been enabled

Enable API in Google Cloud Console

Could not load credentials

Check credentialsPath in config

Skipped: X (empty or invalid)

Sheet missing headers or name /type columns

Pull shows "(no changes)" Idempotent - content unchanged, file preserved

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