himalaya

The Cairn command tree is organized into three distinct groups:

1. Shared API: Cross-protocol commands (mailbox, envelope, flag, message, attachment) that behave consistently regardless of the backend. These run over an EmailClient and select a backend based on the --backend flag (preferring local over network backends).
2. Protocol-specific APIs: Commands specific to a backend (imap, jmap, gmail, msgraph, maildir, m2dir, smtp). These ignore the --backend flag and interact directly with the specific protocol's client.
3. Meta commands: Commands for configuration and utility (account, completion, manual).

Testing reports and operational QA documentation have been migrated from the docs/testing/ directory to the Cairn specification directory.

• Testing Reports & Index: Located at cairn/spec/testing/. The index file is cairn/spec/testing/README.md and includes the capability: testing spec frontmatter.
• Test Plans: The provider-test-plan.md is located within cairn/spec/testing/.

Use this directory to access the current truth regarding project coverage and the testing capability implementation.

To start the interactive configuration wizard, run the himalaya command without any subcommands. If a command is run and no configuration is found, the wizard will also be proposed.

Important Behavior:

• The wizard discovers an account and prints a ready-to-save TOML fragment to stdout.
• It writes nothing to disk automatically.
• Prompts are rendered on stderr, allowing you to redirect the generated configuration directly into a file using standard shell redirection.

The account discovery wizard has been updated to a two-step selection process:

1. Service Selection: The discovery list now displays one entry per service.
2. Authentication Selection: A second service-specific prompt allows you to choose the authentication method:
   • For IMAP + SMTP: Choose the appropriate SASL mechanism.
   • For JMAP: Choose the HTTP scheme.
   • For OAuth: This is now integrated into the API-token credential prompt rather than being a separate, non-functional option.

Note on IMAP/SMTP configuration: During the IMAP + SMTP flow, the wizard tests each protocol individually during configuration and will prompt you to decide if SMTP should share the same credentials as IMAP.

The wizard follows a service-first, then authentication-second flow:

1. Service Selection: The discovery list shows one entry per reachable service (e.g., IMAP + SMTP, JMAP, Gmail, Microsoft Graph).
2. Authentication Selection: After picking a service, you choose an authentication method. For IMAP, the wizard probes the server's live CAPABILITY to offer only supported SASL mechanisms (preferring modern ones over legacy LOGIN).
3. OAuth Integration: Himalaya does not perform OAuth 2.0 grants. Instead, OAuth is integrated into the API-token credential prompt. It offers:
   • OS keyrings: For tokens you have already generated.
   • OAuth token brokers: Such as Ortie, pizauth, or oama (these appear only if the service advertises OAuth support).

Himalaya v2 does not include built-in OAuth flows. To use OAuth 2.0, use a token broker (like pimalaya/ortie) to obtain an access token, then configure Himalaya to retrieve that token via a command that prints it to stdout.

• For JMAP: Point jmap.auth.bearer.token.command to the broker.
• For IMAP/SMTP: Route the bearer through a SASL mechanism that consumes a command-sourced password.

The authentication flow for IMAP and SMTP follows a specific testing sequence:

1. Test the IMAP connection first.
2. Prompt the user to decide if SMTP should reuse the same credentials.
3. If different credentials are required, re-run the SASL prompt for a distinct set.
4. Test the SMTP connection last.

Note: If a backend performs inline validation, the final account test is skipped.

The wizard accepts a single input prompt that determines the flow. You can provide one of the following:

• An email address or bare domain: Triggers parallel discovery via io-pim-discovery.
• A scheme:// server URL: Configures the service manually via the provided URL.
• A local folder path: Configures a local Maildir or m2dir folder.

Note: Discovery is time-bounded. If an endpoint is unreachable, the wizard will abandon that specific mechanism after a short deadline and fall back to manual entry to prevent stalling.