Skip to content

fix: onboard wizard does not mark optional Feishu credential fields (encrypt_key / verification_token) #84

Description

@wucm667

Summary

During raven onboard (Step 3, channel setup), configuring Feishu prompts for
four fields with no visible distinction between required and optional ones. Only
app_id and app_secret are actually needed for the WebSocket long-connection
mode; encrypt_key and verification_token are optional (event-subscription
encryption only). The wizard lists all four as "fill in", shows no "(optional)"
marker, and only shows the "empty to skip" hint on the first field, so users
believe every prompted field is mandatory.

This is the same class of setup-wizard confusion already tracked in #81.

Root cause (from reading the code)

  1. The field-spec model has no required/optional dimension. _flatten_fields
    in raven/config/update_channels.py emits only type, default,
    is_secret, description. Every channel field carries a Pydantic default
    (app_id: str = "", encrypt_key: str = "", ...), so nothing is "required"
    at the schema level, and no consumer can tell required from optional.

  2. The "(optional)" note lives in raven/config/schema.py as an inline #
    comment, not a Field(description=...). Pydantic does not read # comments,
    so finfo.description is empty and the Description column / prompt label show
    nothing.

  3. In _prompt_channel_fields (raven/cli/onboard_commands.py), the "empty to
    go back / skip" placeholder is gated on allow_back = idx == 0, so it only
    appears on the first field. Optional fields further down get no placeholder,
    even though empty-submit does skip them.

Suggested fix (two options, maintainer's call)

  • Option A (minimal): mark the optional Feishu fields as optional in the wizard
    label and surface the empty-to-skip hint on optional fields. Smallest scope.
  • Option B (structural): add a required/optional dimension to
    channel_field_specs, and render it consistently in both channels show and
    the onboard wizard. Larger scope; touches the config <-> cli contract and the
    related tests.

Happy to open a PR once you confirm the preferred direction.

Steps to reproduce

  1. Run raven onboard.
  2. Proceed to Step 3 (chat channel) and select feishu.
  3. Observe the field prompts.

Or, equivalently, raven channels show feishu shows the same underlying spec
table with no required/optional signal.

Expected behavior

  • Optional credential fields (encrypt_key, verification_token) are visibly
    marked as optional in the wizard prompt (e.g. an (optional) suffix).
  • The "empty submit to skip" affordance is discoverable on optional fields, not
    just the first field.
  • Ideally raven channels show <name> conveys the same required/optional
    distinction, so the CLI and the wizard stay consistent.

Actual behavior

  • The wizard prints Configuring feishu - fill in: app_id, app_secret, encrypt_key, verification_token with all four listed equally.
  • Prompt labels render as bare encrypt_key: / verification_token: with no
    optional marker.
  • The channels show feishu table has columns Flag / Type / Default / Secret? /
    Description, but no required/optional column, and the Description column is
    empty for every Feishu field.

Environment

  • OS: macOS
  • Shell: zsh
  • Raven: 0.1.2 (commit d7d1479)

Logs or screenshots

`raven channels show feishu`:


                                Channel: feishu
 Flag                  Type      Default   Secret?   Description
 --enabled             bool      False
 --app-id              str
 --app-secret          str                    v
 --encrypt-key         str                    v
 --verification-token  str                    v
 --allow-from          list      ['*']
 --react-emoji         str       THUMBSUP
 --group-policy        Literal   mention                Choices: open, mention

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    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