Project Atlas AetherDev project hub
Atlas project production

google-sheet-sync

Provide a consistent, modern CLI with subcommands and config support Support download, upload, and sync with predictable, auditable outcomes Ensure CLI options override config values Deliver clear logging with basic rotation for auditability Enable safe dry-run workflows. list-sheets / describe validate API connectivity and metadata download writes a range to CSV upload overwrites or appends CSV rows into a range (optional header matching) sync updates rows by primary key, with configurable duplicate and missing-row policies clear wipes a configured range.

Type
Component
Lifecycle
Active
Last touched
2025-12-24
Visibility
Public

Purpose

Provide a consistent, modern CLI with subcommands and config support Support download, upload, and sync with predictable, auditable outcomes Ensure CLI options override config values Deliver clear logging with basic rotation for auditability Enable safe dry-run workflows.

Current state

CLI/config merge foundation implemented Logging with stdout + rotating file output implemented CSV parsing/writing helpers implemented download/upload/sync/list-sheets/describe commands implemented Last touched: 2025-12-24. Functionality and completeness: Core subcommands are implemented and documented; integration tests and CI are pending.

Next step

Add baseline automated tests to cover critical flows; Add CI pipeline for build/test/lint; Document deployment/runtime environment (or add Dockerfile); Document interfaces (CLI flags, API endpoints, file formats); Add structured logging and basic health checks.

Interfaces

Inputs
  • config.toml (auth, logging, retry, defaults), service-account JSON, CSV files
  • Configuration files (TOML/YAML/JSON/INI/CONF)
Outputs
  • CSV downloads, updated Google Sheet ranges, logs under the configured log dir
  • CSV files

Reality to Action trace

Reality Ingestion

Contributes in this stage.

Canonical Storage

Contributes in this stage.

Automation Engines

Not in scope.

Human Interfaces

Contributes in this stage.

Operational Adoption

Contributes in this stage.

Core workflow

TBD. Document the 5-10 steps that define the core workflow.

Operational notes

Constraints and scars

  • Relies on Google Sheets API quotas and range limits; large updates may require smaller batch sizes.

Reliability posture

Failure modes and safe behavior: Auth errors, range mismatches, or header mismatches abort without partial writes (dry-run recommended). Idempotency / retries / batching behavior: Batch updates with configurable size; retries with exponential backoff for transient API errors.

Observability

  • Logs: Rust logging framework detected (log/tracing/env_logger). Logs go to stdout and a rotating file under --log-dir. Each operation emits start/end events, row counts, and detailed error information.
  • Metrics/health checks: None built-in; use logs and dry-run for validation

Security and privacy

Treat service-account JSON and sheet IDs as sensitive; avoid committing them to git. Sensitive secret material detected in google-sheet-sync/priv_key.json; ensure it is excluded from docs and CI.

Dependencies

Upstream
  • Google Sheets API

Ownership

Owners

Josh Barton

Users

Josh Barton (owner)

google-sheet-sync

Architecture & Major Components

  • High-level diagram (text):

    • Entry/trigger -> core logic -> outputs (details per docs below)

  • Planned module layout (names subject to change):

  • src/main.rs: CLI entrypoint, config loading/merge, logging setup, dispatch

  • src/cli.rs: clap CLI definitions

  • src/config.rs: config structures, merge logic, validation

  • src/logging.rs: logger init, rotation config, structured fields

  • src/commands.rs: command handlers (download, upload, sync, list-sheets, describe)

  • Entry points: src/main.rs

  • Top-level folders: scripts, src, tests

  • src/ submodules: command handlers for download/upload/sync/clear, config parsing, logging setup

  • Key abstractions: Config + CLI override merge, batch update pipeline, header matching and key-based sync

Setup / Build / Run

  • Build system(s): Cargo.
  • Provide a service-account JSON key and share target sheets with that account.
  • Configure config.toml (or pass CLI flags) for sheet IDs, ranges, and logging.
  • Use --dry-run for uploads/syncs to validate changes before applying.