kind: llman.sdd.spec
name: "cli-experience"
purpose: "Describe llman CLI messaging, localization coverage, and stdout/stderr conventions."
valid_scope[2]: src/,tests/
requirements[10]{req_id,title,statement}:
  r1,Localized runtime messaging with documented exceptions,"Runtime prompts, status lines, and errors MUST use `t!` keys from `locales/app.yml` when a suitable key exists. When no localization key exists, commands MAY emit inline strings (for example: task count labels, on/off markers, separators, or generated export content)."
  r2,Locale is fixed to English,The CLI MUST set the locale to English at startup and use the `locales/app.yml` bundle.
  r3,Consistent stdout/stderr usage,"Normal command output and interactive prompts MUST go to stdout. Errors SHOULD be written to stderr; non-fatal notices MAY still use stdout."
  r4,"Consistent single-line formatting","Single-line messages MUST use a single consistent prefix or label; inline emoji or separators MAY be included but MUST avoid mixing unrelated prefixes."
  r5,Shell completion script generation,"The CLI MUST provide `llman self completion --shell <shell>` to emit a completion script to stdout for bash, zsh, fish, powershell, and elvish."
  r6,Install completion snippet into shell rc,"The CLI MUST provide `--install` to update the appropriate shell rc/profile file with a marked completion block for the selected shell."
  r7,Install output is copyable,"The `--install` command MUST print the exact snippet it applied so it can be copy/pasted."
  r8,Explicit confirmation for rc writes,"completion install MUST 在修改 shell rc/profile 文件前提示确认，且当用户拒绝时 MUST 不写入。若处于非交互环境，命令 MUST 拒绝写入并返回错误，除非显式提供 `--yes`；当提供 `--yes` 时 MUST 直接执行写入且不出现交互提示。"
  r9,Idempotent install block,The completion install MUST not create duplicate blocks and MUST update an existing block in place when present.
  r10,Unsupported shell handling,"The CLI MUST reject unsupported shell values with a non-zero exit code and show the supported shell list."
scenarios[14]{req_id,id,given,when,then}:
  r1,"localized-prompt-with-inline-formatting","",a command prompts the user or prints a status header,"the primary message text is resolved from `locales/app.yml` and any inline markers (emoji, bullets, separators) are embedded as literals"
  r1,"inline-only-content","",a command outputs generated content (such as exported markdown or file name labels),"the generated content may include hard-coded text that is not localized"
  r2,"cli-startup","",the CLI launches,the runtime locale is set to `en` and localization keys resolve against `locales/app.yml`
  r3,"operational-failure","",a command fails during execution,"the user-facing error is written to stderr"
  r3,"progress-output","",a command reports progress or results,the messages are written to stdout
  r4,"user-facing-label","","a single-line status or label is printed",the line uses consistent formatting and does not mix unrelated prefixes
  r5,"generate-bash-completion","","a user runs `llman self completion --shell bash`",the completion script is written to stdout and the command exits successfully
  r6,"install-completion-snippet","","a user runs `llman self completion --shell bash --install`",a marked completion block is added or updated in the bash rc/profile file and the command exits successfully
  r7,"install-output-is-printed","",a completion snippet is installed,the snippet is written to stdout
  r8,拒绝确认不会产生副作用,"",用户拒绝确认提示,不修改任何 rc/profile 文件
  r8,"非交互-install-未提供-yes","","命令在非交互环境运行，且包含 `--install` 但未提供 `--yes`",命令以非零退出，且不修改任何 rc/profile 文件
  r8,"非交互-install-提供-yes","","命令在非交互环境运行，且包含 `--install --yes`",completion block 被安装/更新，且命令成功退出
  r9,"existing-block","",the shell rc/profile file already contains a marked llman completion block,the block is replaced with the latest snippet and no duplicate block is added
  r10,"unsupported-shell-value","","a user passes `--shell tcsh`",the CLI reports the supported shells and exits with failure
