Skip to content

feat(tui): add cloud sync settings screen #577

Description

@mgaldamez

Pre-flight Checks

  • I have searched existing issues and this is not a duplicate
  • I understand this issue needs status:approved before a PR can be opened

Problem Description

Cloud configuration is currently CLI/env-driven and invisible to TUI users:

  • Server URL: set via engram cloud config --server <url>
  • Token: set via ENGRAM_CLOUD_TOKEN, with cloud.json.token as an intentional fallback
  • Project enrollment: separate per-project CLI command

The TUI is the project's primary visual interface and currently has no entry point for cloud configuration.

Proposed Solution

Add a Cloud sync settings menu item to the Engram TUI dashboard with three sub-screens:

  1. Cloud Config: form to set the server URL plus a read-only token status line showing the active source (ENGRAM_CLOUD_TOKEN env var, cloud.json.token fallback, or not set). The TUI persists only the server URL; the token is never written by the TUI.
  2. Cloud Status: read-only view of server URL, connection health, last sync, pending mutations, and last error.
  3. Project Enrollment: list of local projects with enroll / unenroll toggles.

Before saving the server URL, the TUI pings the server's health endpoint and surfaces the result (reachable / unreachable / unauthorized). A 401 still persists the URL because server reachability and auth are independent concerns.

A small docs update is bundled: docs/engram-cloud/troubleshooting.md should explicitly document the cloud.json.token fallback as intentional, with the env var taking precedence. No code change required — the runtime already behaves this way (see issue #343).

Affected Area

  • TUI (screens, navigation, rendering)
  • Documentation (troubleshooting.md)

Alternatives Considered

  • Adding a masked token input and writing cloud.json.token from the TUI: rejected because the project philosophy keeps tokens out of disk where possible.
  • Removing the cloud.json.token fallback from resolveCloudRuntimeConfig: rejected as a breaking change for users who currently rely on it.
  • Implementing OAuth or browser login in the TUI: rejected — out of scope for a client-only change and would require server-side work.
  • Leaving cloud setup CLI-only: rejected — the TUI is the project's visual interface and the current flow is a discoverability / UX gap.

Implementation Plan

The change will land via 4 chained PRs against a tracker branch feat/tui-cloud-config (Feature Branch Chain):

  1. PR 1: TUI dashboard entry + sub-menu + docs update.
  2. PR 2: Cloud Config form + ping command + save flow.
  3. PR 3: Cloud Status view.
  4. PR 4: Project Enrollment toggles.

Each PR follows strict TDD, adds zero new dependencies, and stays under ~400 changed lines. Tests run with go test ./....

Additional Context

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions