fix(cli): unify settings.json + star-cache.json under ~/.config/tokscale on macOS

[yousiki]

Summary

Settings::config_path() (tui/settings.rs) and star_cache_path() (main.rs) called dirs::config_dir(), which returns ~/Library/Application Support/ on macOS. That left two pieces of TUI state stranded under Application Support while auth.rs, cursor.rs, antigravity.rs, and all four README variants documented ~/.config/tokscale/. macOS users following the docs edited a settings.json that tokscale never read.

This PR unifies the path on macOS + Linux and adds an env override.

• New crates/tokscale-cli/src/paths.rs::get_config_dir(): env override → macOS/Linux $HOME/.config/tokscale → Windows dirs::config_dir().join("tokscale") → .tokscale last-ditch fallback.
• Both call sites switched to it.
• Settings::load() reads the new path first, then falls back to the legacy ~/Library/Application Support/tokscale/settings.json on macOS only — so existing macOS users keep their theme / scanner / defaultClients after upgrade. save() always writes the new path; the next save makes the legacy file irrelevant.
• TOKSCALE_CONFIG_DIR env var added (mirrors TOKSCALE_HEADLESS_DIR semantics — any Ok value wins, no empty-string special case).
• All four README variants: added TOKSCALE_CONFIG_DIR row to env-var tables, and corrected the Windows-Specific Configuration section — settings.json lives at %APPDATA%\tokscale\ (the actual dirs::config_dir() default on Windows), not %USERPROFILE%\.config\tokscale\. Added the missing credentials.json row.

Out of scope (per the originating issue): auth.rs, cursor.rs, antigravity.rs already hardcode ~/.config/tokscale/ correctly and were left alone. Cache dirs and headless paths were also left alone.

Test plan

• cargo build -p tokscale-cli clean
• cargo clippy -p tokscale-cli --bin tokscale --tests clean (only pre-existing antigravity warnings)
• cargo test -p tokscale-cli --bin tokscale paths::tests:: — 2 passed
• cargo test -p tokscale-cli --bin tokscale tui::settings:: — 10 passed (incl. new macOS-gated load_falls_back_to_legacy_macos_path_when_new_path_missing)
• Full cargo test -p tokscale-cli — only the pre-existing test_data_loader_keeps_synthetic_gateway_messages_under_original_client failure (unrelated, reproduces on main)
• Fresh macOS install: bunx tokscale@latest tui creates ~/.config/tokscale/settings.json, not ~/Library/Application Support/
• TOKSCALE_CONFIG_DIR=/tmp/tk bunx tokscale@latest tui writes /tmp/tk/settings.json
• Existing macOS user with prior ~/Library/Application Support/tokscale/settings.json sees their prior settings on first launch after upgrading
• Windows behavior unchanged (%APPDATA%\tokscale\settings.json)

🤖 Generated with Claude Code

---

Summary by cubic

Unifies the TUI config and star cache on macOS under ~/.config/tokscale, matching Linux and the docs. Adds TOKSCALE_CONFIG_DIR to override the location and preserves existing macOS settings on upgrade.

• Bug Fixes

  • macOS now reads/writes ~/.config/tokscale/settings.json; no more ~/Library/Application Support/....
  • Settings::load() falls back to the legacy macOS path once, so existing theme/scanner/defaultClients are kept.
  • star-cache.json now lives in the same config dir; Windows behavior is unchanged.

• New Features

  • Added paths::get_config_dir() to centralize config-dir resolution across platforms.
  • Added TOKSCALE_CONFIG_DIR to override where settings.json is stored.
  • Updated READMEs: documented TOKSCALE_CONFIG_DIR, corrected Windows path to %APPDATA%\tokscale\, and added the missing credentials.json row.

^{Written for commit d8f5b9e. Summary will update on new commits.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
tokscale	Ignored	Preview	Apr 26, 2026 4:35pm

[junhoyeo]

Thanks for digging into this @yousiki! Real bug — the new defaultClients setting we just shipped in #464 was silently no-op on macOS for anyone who followed the README. Surgical fix, hermetic tests, graceful one-way migration that preserves existing macOS users' theme/scanner/defaultClients across the upgrade. Approving and squash merging into v2.1.0.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d8f5b9e1f6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cubic-dev-ai]

5 issues found across 7 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="README.md">

<violation number="1" location="README.md:518">
P3: README overstates `TOKSCALE_CONFIG_DIR` as absolute-only, but code accepts any string value verbatim (including relative paths).</violation>
</file>

<file name="README.ja.md">

<violation number="1" location="README.ja.md:501">
P2: `TOKSCALE_CONFIG_DIR` documentation is incomplete: it affects shared config files (including `star-cache.json`), not only `settings.json`.</violation>
</file>

<file name="crates/tokscale-cli/src/paths.rs">

<violation number="1" location="crates/tokscale-cli/src/paths.rs:28">
P2: Linux config resolution now ignores `XDG_CONFIG_HOME` by hardcoding `$HOME/.config`, which can break existing setups using non-default XDG config paths.</violation>
</file>

<file name="README.zh-cn.md">

<violation number="1" location="README.zh-cn.md:501">
P3: 文档将 `TOKSCALE_CONFIG_DIR` 描述为“绝对路径”是错误的；实现会原样接受环境变量值（包含相对路径），应改为“支持任意有效路径”或“建议使用绝对路径”。</violation>
</file>

<file name="crates/tokscale-cli/src/tui/settings.rs">

<violation number="1" location="crates/tokscale-cli/src/tui/settings.rs:148">
P2: `Settings::load()` falls back to legacy macOS settings even when `TOKSCALE_CONFIG_DIR` is explicitly set, which can override an intentional custom config directory with stale legacy data.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[yousiki]

Thanks for merging my PR! I really appreciate this community project, and I’m honored to have been able to contribute.