Add CLI configuration diagnostics

.github/workflows/ci.yaml

@@ -63,10 +63,21 @@ jobs:
           "$native_root/bin/stack" check "$smoke_directory/diagram.stack"
           "$native_root/bin/stack" render "$smoke_directory/diagram.stack" -o "$smoke_directory/diagram.svg"
           test -s "$smoke_directory/diagram.svg"
-          "$native_root/bin/stack" completions bash | cmp distribution/generated/share/bash-completion/completions/stack -
-          "$native_root/bin/stack" completions zsh | cmp distribution/generated/share/zsh/site-functions/_stack -
-          "$native_root/bin/stack" completions fish | cmp distribution/generated/share/fish/vendor_completions.d/stack.fish -
-          "$native_root/bin/stack" manpage | cmp distribution/generated/share/man/man1/stack.1 -
+          release_target=x86_64-unknown-linux-gnu
+          archive_name="stack-v${expected_version}-${release_target}.tar.gz"
+          archive_id="github_release/github.com/stack-sh/cli/v${expected_version}/${archive_name}"
+          release_archive="$RUNNER_TEMP/$archive_name"
+          release_root="$RUNNER_TEMP/aqua-release"
+          expected_archive_checksum=$(ARCHIVE_ID="$archive_id" node -e 'const lock = JSON.parse(require("fs").readFileSync("tests/aqua/aqua-checksums.json", "utf8")); const entry = lock.checksums.find(({ id }) => id === process.env.ARCHIVE_ID); if (!entry || entry.algorithm !== "sha256") process.exit(1); process.stdout.write(entry.checksum)')
+          curl --proto '=https' --tlsv1.2 --fail --location --silent --show-error --output "$release_archive" "https://github.com/stack-sh/cli/releases/download/v${expected_version}/${archive_name}"
+          test "$(sha256sum "$release_archive" | cut -d ' ' -f 1 | tr '[:lower:]' '[:upper:]')" = "$expected_archive_checksum"
+          mkdir -p "$release_root"
+          tar -xzf "$release_archive" -C "$release_root"
+          released_share="$release_root/stack-v${expected_version}-${release_target}/share"
+          "$native_root/bin/stack" completions bash | cmp "$released_share/bash-completion/completions/stack" -
+          "$native_root/bin/stack" completions zsh | cmp "$released_share/zsh/site-functions/_stack" -
+          "$native_root/bin/stack" completions fish | cmp "$released_share/fish/vendor_completions.d/stack.fish" -
+          "$native_root/bin/stack" manpage | cmp "$released_share/man/man1/stack.1" -
       - name: Validate release supply chain
         run: |
           node --check scripts/create-supply-chain-smoke-fixture.mjs
@@ -105,6 +116,14 @@ jobs:
           COMP_CWORD=3
           _stack_completion
           test "${COMPREPLY[*]}" = "aws azure"
+          COMP_WORDS=(stack config g)
+          COMP_CWORD=2
+          _stack_completion
+          test "${COMPREPLY[*]}" = get
+          COMP_WORDS=(stack config get d)
+          COMP_CWORD=3
+          _stack_completion
+          test "${COMPREPLY[*]}" = default_icons_path
       - name: Run canonical formatter suite
         env:
           STACK_SPECIFICATION_DIR: ${{ github.workspace }}/.stack-specification
@@ -149,6 +168,10 @@ jobs:
           ./target/release/stack render --help
           ./target/release/stack update --help
           ./target/release/stack lsp --help
+          ./target/release/stack doctor --help
+          ./target/release/stack config --help
+          ./target/release/stack config path --help
+          ./target/release/stack config get --help
           ./target/release/stack icons --help
           ./target/release/stack completions --help
           ./target/release/stack completions bash | cmp distribution/generated/share/bash-completion/completions/stack -
@@ -158,6 +181,11 @@ jobs:
           ./target/release/stack icons list
           ./target/release/stack icons list aws s3
           ./target/release/stack icons import --help
+          config_smoke_root="$RUNNER_TEMP/stack-config-smoke"
+          test "$(XDG_CONFIG_HOME="$config_smoke_root" ./target/release/stack config path)" = "$config_smoke_root/stack/config.yaml"
+          test "$(XDG_CONFIG_HOME="$config_smoke_root" ./target/release/stack config get default_icons_path)" = "$config_smoke_root/stack/icons"
+          XDG_CONFIG_HOME="$config_smoke_root" ./target/release/stack doctor
+          test ! -e "$config_smoke_root"
       - name: Verify repository files
         run: |
           test -s README.md
@@ -168,6 +196,7 @@ jobs:
           test -s CONTRIBUTING.md
           test -s SECURITY.md
           test -s docs/language-server.md
+          test -s docs/configuration.md
           test -s docs/completions.md
           test -s docs/self-update.md
           test -s docs/publication-audit.md
@@ -232,6 +261,11 @@ jobs:
           test -s tests/specification-revision
           test -s tests/fixtures/render.stack
           test -s tests/snapshots/lsp-help.txt
+          test -s tests/snapshots/doctor-help.txt
+          test -s tests/snapshots/doctor-report.txt
+          test -s tests/snapshots/config-help.txt
+          test -s tests/snapshots/config-path-help.txt
+          test -s tests/snapshots/config-get-help.txt
           test -s tests/snapshots/update-help.txt
           test -s tests/update.rs
 

README.md

@@ -25,6 +25,8 @@ For a direct installation, download the archive for your target and its verifica
 
 ## Commands
 
+The command inventory below follows the current source tree. `stack doctor` and `stack config` were added after 0.4.0 and are not present in the published 0.4.0 binaries; they will become available through installation channels in a later release.
+
 ```text
 stack help
 stack help render
@@ -40,6 +42,10 @@ stack render arch.stack
 stack render arch.stack -o arch.svg
 stack update --check
 stack lsp
+stack doctor
+stack doctor --provider-pack .stack-icons
+stack config path
+stack config get default_icons_path
 stack icons list
 stack icons list aws s3
 stack icons import gcp --accept-terms
@@ -49,7 +55,7 @@ stack completions zsh
 stack manpage
 ```
 
-`stack help`, `stack -h`, and `stack --help` print top-level help. Use `stack help <COMMAND>` or `<COMMAND> -h` / `<COMMAND> --help` for command-specific usage and examples; nested icon help is available through `stack help icons <COMMAND>`. `stack version`, `stack -v`, `stack -V`, and `stack --version` print the same Cargo package version. Help and version output use standard output and exit with status `0`. Invalid arguments and unknown commands use standard error and status `2`; close command typos include a suggested command and the relevant help invocation.
+`stack help`, `stack -h`, and `stack --help` print top-level help. Use `stack help <COMMAND>` or `<COMMAND> -h` / `<COMMAND> --help` for command-specific usage and examples; nested help is available through `stack help config <COMMAND>` and `stack help icons <COMMAND>`. `stack version`, `stack -v`, `stack -V`, and `stack --version` print the same Cargo package version. Help and version output use standard output and exit with status `0`. Invalid arguments and unknown commands use standard error and status `2`; close command typos include a suggested command and the relevant help invocation.
 
 `stack init` creates `diagram.stack` from the versioned `hello-stack` template without prompting. Use `--template <ID>` to select any of the nine curated examples shared with the public Stack specification and Web gallery, and `-o` / `--output` to choose another file. Existing paths are never replaced unless `--force` is explicit; forced writes use the same atomic output behavior as rendering. Provider templates print the exact `stack icons import` commands needed for branded rendering and remain valid with deterministic fallback icons when packs are absent. The embedded catalog and source bytes are pinned by `tests/specification-revision`, and CI rejects drift from that public specification commit.
 
@@ -61,13 +67,15 @@ stack manpage
 
 `stack lsp` runs a native [Language Server Protocol 3.18 adapter](./docs/language-server.md) over standard input and output. It provides incremental document synchronization, versioned diagnostics, completion, hover, hierarchical document symbols, and whole-document formatting for `.stack` files. The adapter negotiates UTF-8, UTF-16, or UTF-32 positions and delegates language semantics and formatting to the pinned compiler and engine rather than reimplementing them. Standard output is reserved for framed JSON-RPC messages.
 
+`stack config path` prints the selected `config.yaml` path without creating or reading the file. `stack config get default_icons_path` strictly reads the supported configuration and prints the effective icon-store path. `stack doctor` reports the CLI version, configuration path and source, configuration validity, effective icon-store source, and installed known-provider packs. It is read-only, emits actionable categories instead of configuration contents, exits `0` for healthy and warning-only reports, and exits `2` when it finds an operational problem. See the [configuration discovery and doctor contract](./docs/configuration.md).
+
 `stack update` is included in 0.4.0 for future receipted direct installations, with `--check`, exact-version selection, authenticated release-manifest and archive verification, and rollback-aware atomic replacement. It refuses Homebrew, Aqua, Cargo, and unknown ownership. The 0.4.0 release manifest does not activate `self-update`, and the documented manual installation creates no receipt, so the channel remains planned. See the [self-update contract](./docs/self-update.md).
 
 `stack completions <bash|zsh|fish>` and `stack manpage` generate deterministic shell integration and an offline roff manual from the CLI command metadata. The 0.4.0 release archives carry the exact generated files; Homebrew installs them into its managed completion and manual paths, while direct, Aqua, and future Cargo users can generate them into user-owned locations without modifying shell startup files. See the [completion and manual guide](./docs/completions.md).
 
 `stack icons list [PROVIDER] [QUERY]` searches the asset-free catalog by ID, product name, or category. The catalog currently contains 1,051 IDs: 305 AWS, 45 Google Cloud, 639 Azure, and 62 curated developer and collaboration tool icons. This command reads only metadata embedded in the CLI.
 
-`stack icons import <PROVIDER> --accept-terms` downloads the audited official archive set, verifies every complete SHA-256 before ZIP processing, reads allowlisted SVG entries with fixed size limits, sanitizes active and external content, preserves official colors and geometry, and writes the manifest, notice, and processed SVGs atomically. The default store is `$XDG_CONFIG_HOME/stack/icons`, falling back to `$HOME/.config/stack/icons`. `$XDG_CONFIG_HOME/stack/config.yaml` can set an absolute `default_icons_path`. Use `-o <DIRECTORY>` to put provider child directories below a project-local root. See [the provider icon guide](./docs/provider-icon-import.md) for configuration, project-local usage, sources, hashes, and rights.
+`stack icons import <PROVIDER> --accept-terms` downloads the audited official archive set, verifies every complete SHA-256 before ZIP processing, reads allowlisted SVG entries with fixed size limits, sanitizes active and external content, preserves official colors and geometry, and writes the manifest, notice, and processed SVGs atomically. The default store is `$XDG_CONFIG_HOME/stack/icons`, falling back to `$HOME/.config/stack/icons`. `$XDG_CONFIG_HOME/stack/config.yaml` can set an absolute `default_icons_path`. Use `-o <DIRECTORY>` to put provider child directories below a project-local root. See the [configuration contract](./docs/configuration.md) for discovery and diagnosis, and [the provider icon guide](./docs/provider-icon-import.md) for project-local usage, sources, hashes, and rights.
 
 | Result | Exit status |
 | --- | ---: |

distribution/generated/share/bash-completion/completions/stack

@@ -4,8 +4,8 @@ local current previous context words
 current="${COMP_WORDS[COMP_CWORD]-}"
 previous="${COMP_WORDS[COMP_CWORD-1]-}"
 context="${COMP_WORDS[1]-}"
-if [[ "$context" == icons && $COMP_CWORD -ge 3 ]]; then
-context="icons ${COMP_WORDS[2]-}"
+if [[ ( "$context" == icons || "$context" == config ) && $COMP_CWORD -ge 3 ]]; then
+context="$context ${COMP_WORDS[2]-}"
 fi
 case "$previous" in
 --template) words="hello-stack application-and-data groups-and-layout commerce-platform aws-serverless-checkout gcp-data-service azure-event-platform github-delivery-workflow mixed-provider-platform" ;;
@@ -15,7 +15,7 @@ case "$previous" in
 esac
 if [[ -z "$words" ]]; then
 if (( COMP_CWORD == 1 )); then
-words="init check fmt render update lsp icons completions manpage help version -h --help -v -V --version"
+words="init check fmt render update lsp doctor config icons completions manpage help version -h --help -v -V --version"
     else
       case "$context" in
         "init") words="--template -o --output --force -h --help" ;;
@@ -24,12 +24,16 @@ words="init check fmt render update lsp icons completions manpage help version -
         "render") words="--provider-pack -o --notice -h --help" ;;
         "update") words="--check --version -h --help" ;;
         "lsp") words="-h --help" ;;
+        "doctor") words="--provider-pack -h --help" ;;
+        "config") words="path get help -h --help" ;;
+        "config path") words="-h --help" ;;
+        "config get") words="default_icons_path -h --help" ;;
         "icons") words="list import help -h --help" ;;
         "icons list") words="aws gcp azure simple-icons -h --help" ;;
         "icons import") words="aws gcp azure simple-icons --accept-terms -o -h --help" ;;
         "completions") words="bash zsh fish -h --help" ;;
         "manpage") words="-h --help" ;;
-        "help") words="init check fmt render update lsp icons completions manpage help version -h --help" ;;
+        "help") words="init check fmt render update lsp doctor config icons completions manpage help version -h --help" ;;
         "version") words="-h --help" ;;
         *) words="" ;;
 esac

distribution/generated/share/fish/vendor_completions.d/stack.fish

@@ -9,6 +9,8 @@ complete -c stack -n __stack_needs_command -a 'fmt' -d 'Format a file in place o
 complete -c stack -n __stack_needs_command -a 'render' -d 'Render standalone SVG to standard output or a file'
 complete -c stack -n __stack_needs_command -a 'update' -d 'Check for or install a verified direct-install update'
 complete -c stack -n __stack_needs_command -a 'lsp' -d 'Run the Stack language server over standard input and output'
+complete -c stack -n __stack_needs_command -a 'doctor' -d 'Diagnose CLI configuration and provider icon packs'
+complete -c stack -n __stack_needs_command -a 'config' -d 'Inspect effective read-only configuration'
 complete -c stack -n __stack_needs_command -a 'icons' -d 'List catalogs and import audited provider icon archives'
 complete -c stack -n __stack_needs_command -a 'completions' -d 'Generate bash, zsh, or fish completion source'
 complete -c stack -n __stack_needs_command -a 'manpage' -d 'Print the offline Stack CLI manual page'
@@ -42,6 +44,19 @@ complete -c stack -n '__fish_seen_subcommand_from update' -s 'h'
 complete -c stack -n '__fish_seen_subcommand_from update' -l 'help'
 complete -c stack -n '__fish_seen_subcommand_from lsp' -s 'h'
 complete -c stack -n '__fish_seen_subcommand_from lsp' -l 'help'
+complete -c stack -n '__fish_seen_subcommand_from doctor' -l 'provider-pack' -r
+complete -c stack -n '__fish_seen_subcommand_from doctor' -s 'h'
+complete -c stack -n '__fish_seen_subcommand_from doctor' -l 'help'
+complete -c stack -n '__fish_seen_subcommand_from config' -a 'path'
+complete -c stack -n '__fish_seen_subcommand_from config' -a 'get'
+complete -c stack -n '__fish_seen_subcommand_from config' -a 'help'
+complete -c stack -n '__fish_seen_subcommand_from config' -s 'h'
+complete -c stack -n '__fish_seen_subcommand_from config' -l 'help'
+complete -c stack -n '__fish_seen_subcommand_from config; and __fish_seen_subcommand_from path' -s 'h'
+complete -c stack -n '__fish_seen_subcommand_from config; and __fish_seen_subcommand_from path' -l 'help'
+complete -c stack -n '__fish_seen_subcommand_from config; and __fish_seen_subcommand_from get' -a 'default_icons_path'
+complete -c stack -n '__fish_seen_subcommand_from config; and __fish_seen_subcommand_from get' -s 'h'
+complete -c stack -n '__fish_seen_subcommand_from config; and __fish_seen_subcommand_from get' -l 'help'
 complete -c stack -n '__fish_seen_subcommand_from icons' -a 'list'
 complete -c stack -n '__fish_seen_subcommand_from icons' -a 'import'
 complete -c stack -n '__fish_seen_subcommand_from icons' -a 'help'
@@ -74,6 +89,8 @@ complete -c stack -n '__fish_seen_subcommand_from help' -a 'fmt'
 complete -c stack -n '__fish_seen_subcommand_from help' -a 'render'
 complete -c stack -n '__fish_seen_subcommand_from help' -a 'update'
 complete -c stack -n '__fish_seen_subcommand_from help' -a 'lsp'
+complete -c stack -n '__fish_seen_subcommand_from help' -a 'doctor'
+complete -c stack -n '__fish_seen_subcommand_from help' -a 'config'
 complete -c stack -n '__fish_seen_subcommand_from help' -a 'icons'
 complete -c stack -n '__fish_seen_subcommand_from help' -a 'completions'
 complete -c stack -n '__fish_seen_subcommand_from help' -a 'manpage'

distribution/generated/share/man/man1/stack.1

@@ -22,6 +22,8 @@ Commands:
   render     Render standalone SVG to standard output or a file
   update     Check for or install a verified direct\-install update
   lsp        Run the Stack language server over standard input and output
+  doctor     Diagnose CLI configuration and provider icon packs
+  config     Inspect effective read\-only configuration
   icons      List catalogs and import audited provider icon archives
   completions  Generate bash, zsh, or fish completion source
   manpage    Print the offline Stack CLI manual page
@@ -40,6 +42,8 @@ Examples:
   stack render arch.stack \-o arch.svg
   stack update \-\-check
   stack lsp
+  stack doctor
+  stack config get default_icons_path
   stack icons list aws s3
   stack completions zsh > _stack
   stack manpage > stack.1
@@ -183,6 +187,80 @@ Protocol:
 Examples:
   stack lsp
 .fi
+.SS "stack doctor"
+.nf
+Diagnose Stack CLI configuration and provider icon packs
+
+Usage:
+  stack doctor [\-\-provider\-pack <DIRECTORY>]
+
+Options:
+  \-\-provider\-pack <DIRECTORY>  Diagnose this icon\-store root instead of the effective default
+  \-h, \-\-help                   Print help
+
+Checks:
+  CLI version, config path and source, config validity, effective icon\-store
+  source, and installed known\-provider packs. The report never prints config
+  contents or unrelated environment variables.
+
+Examples:
+  stack doctor
+  stack doctor \-\-provider\-pack .stack\-icons
+.fi
+.SS "stack config"
+.nf
+Inspect effective read\-only Stack configuration
+
+Usage:
+  stack config <COMMAND>
+
+Commands:
+  path  Print the resolved config.yaml path without requiring the file to exist
+  get   Print one effective configuration value
+  help  Print this message or the help of a config subcommand
+
+Options:
+  \-h, \-\-help  Print help
+
+Examples:
+  stack config path
+  stack config get default_icons_path
+.fi
+.SS "stack config path"
+.nf
+Print the resolved Stack config file path
+
+Usage:
+  stack config path
+
+Options:
+  \-h, \-\-help  Print help
+
+The path is selected from absolute XDG_CONFIG_HOME first, then absolute HOME.
+The config file does not need to exist and is never created.
+
+Examples:
+  stack config path
+.fi
+.SS "stack config get"
+.nf
+Print an effective Stack configuration value
+
+Usage:
+  stack config get <KEY>
+
+Arguments:
+  <KEY>  default_icons_path
+
+Options:
+  \-h, \-\-help  Print help
+
+The value is resolved from config.yaml or the default icon\-store path. No file
+is created or changed.
+
+Examples:
+  stack config get default_icons_path
+.fi
 .SS "stack icons"
 .nf
 Manage local provider icon packs
@@ -289,18 +367,20 @@ Print top\-level or subcommand help
 Usage:
   stack help
   stack help <COMMAND>
+  stack help config <COMMAND>
   stack help icons <COMMAND>
 
 Arguments:
-  <COMMAND>  init, check, fmt, render, update, lsp, icons, completions,
-             manpage, help, or version
+  <COMMAND>  init, check, fmt, render, update, lsp, doctor, config, icons,
+             completions, manpage, help, or version
 
 Options:
   \-h, \-\-help  Print help
 
 Examples:
   stack help
   stack help render
+  stack help config get
   stack help icons import
 .fi
 .SS "stack version"