Skill tried to get a token via a canonical env var name. Maybe we should store them that way?

[tashian]

⏺ Bash(tsm get SCARF_API_TOKEN 2>&1 | head -3 || echo "tsm SCARF_API_TOKEN not found")
⎿  Error: Secret not found: SCARF_API_TOKEN
Run 'tsm list' to see available secrets.
⎿  Allowed by auto mode classifier

⏺ Bash(tsm list 2>&1 | grep -i scarf || echo "No Scarf-related secrets in tsm")
⎿   Scarf api key
id: scarf-api-key
⎿  Allowed by auto mode classifier

Searched for 1 pattern (ctrl+o to expand)

[tashian]

Plan: Resolve canonical env-var names in tsm get

Issue: an agent ran tsm get SCARF_API_TOKEN and got "Secret not found", even though scarf-api-key (display name "Scarf api key") was sitting in the vault. Agents naturally reach for canonical SCREAMING_SNAKE env-var names; the vault stored kebab. We should make those resolve.

1. Effort estimate

Size: S–M, ~4–6 hours.

• Daemon-side resolver + tests: ~2h
• Go CLI plumbing (better error message with suggestions, optional --alias flag on add/edit): ~1h
• Skill update: ~30m
• Migration thinking + manual smoke test on a real vault: ~30m

No new RPC methods, no envelope-version bump, no schema changes that aren't already backward-compatible per the existing custom decoder pattern.

2. Recommendation

Do a layered combo, but make the auto-transform the load-bearing part. Specifically:

1. Auto-transform on lookup (primary). In the daemon's Vault.get, if the literal name miss, normalize the requested name to kebab-case using the same rules internal/normalize.Kebab uses on the CLI side, and retry. This handles SCARF_API_TOKEN → scarf_api_token (no match) → scarf-api-token (no match) → match against display-name kebab if we also fold display names. We extend the existing case-insensitive match into a "canonical form" match: lowercase + replace [_\s] with -. Cost: a few lines, zero schema change.
2. "Did you mean?" on miss (secondary). When even the normalized lookup fails, return a not-found error whose data field carries up to 3 nearest-match secret names (Levenshtein on canonical form, threshold ≤ 2). The CLI prints them. This is the fix for the next class of mistake (OPENAI_KEY vs openai-api-key) and for legacy/oddly-named entries.
3. Skill nudge (cheap). Update plugin/skills/credential-usage/SKILL.md to tell the agent: canonical env-var names work, but the canonical-source-of-truth is tsm list --json, and the name field is what to use programmatically.

Why not an explicit env_name field? Tempting, but: (a) it doubles the namespace and forces the user to think about aliases at add-time when they almost never want to; (b) it creates ambiguity (which secret wins if two declare GITHUB_TOKEN?); (c) tsm run --env GITHUB_TOKEN=gh-pat already lets the consumer side declare the env-var binding without polluting vault state. Auto-transform handles 95% of the agent-confusion case for free, and the "did you mean" suggestion handles the rest without making humans declare aliases.

Why not skill-only? Even with the best skill text, agents will still type the env-var name out of habit; the resolver is the right belt-and-suspenders. A pure docs fix punts the problem.

Ambiguity guard. If the normalized name matches >1 secret (e.g. user has both github-token and github_token — possible because the kebab/underscore transform makes them collide), refuse with an error listing both ids. This should be exceedingly rare; we add the check anyway because silently picking one is worse than failing.

3. Alternatives considered

• Add an env_name field per secret (with multiple aliases). Rejected as primary: extra UX surface for a problem auto-transform mostly solves; introduces an aliasing namespace that needs validation, conflict handling, and CLI flags. Could be added later if real demand emerges; keeping the door open by leaving room for a future aliases: [String] field on Secret (the custom decoder already shows the pattern).
• Skill-only fix (teach agent to tsm list first). Rejected as sole solution: agents will still try the canonical name first because it's faster and zero-cost when it works. We should update the skill, but not as the only mitigation.
• Match canonical only in CLI (Go side). Rejected: the daemon already does case-insensitive matching, so the canonical-form logic belongs next to it. Splitting it across CLI and daemon means the next caller (e.g. a future MCP frontend) re-implements it.
• Match against display_name directly. Already implicitly covered: kebab-folding the stored display_name and the requested name produces equality. We do exactly this.
• Levenshtein over the entire vault for fuzzy matching. Rejected as primary lookup; too magic. Used only for the "did you mean" suggestion list, where false positives are harmless.

4. Files to create / modify

Daemon (Swift)

• tsmd/Sources/tsmd/Vault.swift
  • Add private helper canonical(_ s: String) -> String (lowercase, [_\s] → -, collapse runs, trim).
  • Rewrite the lookup in get, remove, edit to: try literal case-insensitive match, then canonical match. Detect ambiguity (>1 canonical match) → throw a new VaultError.ambiguousName(query: String, matches: [String]).
  • On secretNotFound, compute up to 3 nearest canonical-form names via Levenshtein (≤2 distance). Throw enriched error.
• tsmd/Sources/tsmd/Vault.swift (errors)
  • Add case ambiguousName(String, [String]) and case secretNotFoundWithSuggestions(String, [String]) to VaultError (keep secretNotFound for backward compat or fold into new case — see backward-compat section).
• tsmd/Sources/tsmd/JSONRPCHandler.swift
  • Map the new error cases to JSON-RPC errors. For secretNotFoundWithSuggestions, set data: { "suggestions": ["..."] }. For ambiguousName, use RPCErrorCode.invalidParams with data: { "matches": ["..."] }.
• tsmd/Tests/tsmdTests/VaultTests.swift (or new VaultLookupTests.swift)
  • New tests, see breakdown below.

Go CLI

• internal/normalize/normalize.go
  • No change required; the daemon owns its own canonicalizer. (Alternative: extract a tiny Canonical(s) that mirrors what Swift does, for symmetry. Not strictly needed.)
• cmd/get.go
  • In handleError, when the JSON-RPC error has code == secretNotFound and data.suggestions is non-empty, format the printed message as:

    Error: secret not found: SCARF_API_TOKEN
    Did you mean: scarf-api-key, scarf-api-token?
    

  • When code == invalidParams and data.matches is set, print "Ambiguous name 'GITHUB_TOKEN' matches: github-token, github_token. Use the exact id."
• cmd/get_test.go
  • Mock client returns enriched error → assert formatted output.
• internal/client/client.go (if needed)
  • Surface JSON-RPC error.data to callers. Likely already plumbed; verify.

Skill

• plugin/skills/credential-usage/SKILL.md
  • Add a sentence under §1 "Discover first": "Canonical env-var names like GITHUB_TOKEN will resolve if the stored id is github-token or display name kebab-folds to that. But tsm list --json is the authoritative source of names — use those in tsm run --env."

5. Task breakdown (TDD)

Daemon

• Add VaultLookupTests.swift with these failing tests first:
  • test_get_resolves_screaming_snake_to_kebab: add a secret with name = "scarf-api-key", display_name = "Scarf api key". Call vault.get("SCARF_API_KEY"). Expect the secret. (Currently fails: case-insensitive match doesn't fold underscores.)
  • test_get_resolves_against_display_name_kebab: add name = "tok-1", display_name = "GitHub Token". Call vault.get("GITHUB_TOKEN"). Expect match. (Note: this requires the resolver to fold display names, not just name.)
  • test_get_literal_match_wins_over_canonical: add two secrets, github-token and one whose display_name = "Github_Token" and name = "alt-id". Call vault.get("github-token") — must return the literal-id one even though both canonicalize identically.
  • test_get_ambiguous_canonical_match_errors: add github-token and github_token (both legal under current name regex). Call vault.get("GITHUB_TOKEN") — expect VaultError.ambiguousName with both ids in the matches list.
  • test_get_not_found_returns_suggestions: add openai-api-key. Call vault.get("OPENAI_KEY"). Expect not-found with suggestions including openai-api-key.
  • test_get_not_found_no_suggestions_when_far: vault has pg-prod. Call vault.get("DEPLOYKEY"). Expect not-found with empty suggestions.
• Implement canonical(_:) helper, ambiguity detection, suggestion computation. Make tests pass.
• Mirror canonical lookup into vault.remove and vault.edit so tsm remove SCARF_API_TOKEN also works (consistency). Add 1 test each.
• Run cd tsmd && swift test. Confirm all 83+ existing tests still pass.

Go CLI

• Add cmd/get_test.go cases (or extend existing):
  • Mock returns RPC error with data.suggestions = ["scarf-api-key"]. Assert printed stderr contains Did you mean: scarf-api-key.
  • Mock returns ambiguous error with data.matches = ["github-token","github_token"]. Assert printed stderr lists both.
• Implement the formatted error path in handleError (or a formatNotFound helper).
• go test ./.... Confirm all pass.

Skill + manual

• Update plugin/skills/credential-usage/SKILL.md per §4.
• Manual smoke test on a real vault:
  • tsm add a secret as "Scarf API key", then tsm get SCARF_API_KEY — should print value.
  • tsm get OPENAI_KEY (with openai-api-key in vault) — should print "Did you mean: openai-api-key".
• Conventional Commits: 1 commit for the daemon resolver, 1 for CLI error formatting, 1 for skill update. Follows the repo's "frequent commits" convention.

6. Migration / backward compat

The vault file format does not change. We're adding only behavior on the lookup path; stored Secret records remain {name, display_name, value, …}. No envelope version bump.

Backward concerns:

• Existing vaults with weird names. Users who already have github-token and github_token (both legal) get the new ambiguity error on canonical lookups. They can still fetch each by exact id; the error only fires for GITHUB_TOKEN-style queries that hit both. Document in the release notes / skill update.
• Older daemons. If a user upgrades the CLI but not the daemon, they get the old "Secret not found" message — fine, still works for exact-id lookups. The CLI's "did you mean" rendering simply becomes a no-op when data.suggestions is absent.
• Older CLIs against new daemon. Old CLIs ignore unknown error data fields, so they'll just print the daemon's error.message. We should make sure that bare message is still useful — i.e., the daemon's message string for "not found" is unchanged: "Secret not found: SCARF_API_TOKEN". Suggestions ride alongside in data only.
• No data migration needed. Resolver works against whatever's already in the vault.

7. Skill update content

Replace the current §1 of plugin/skills/credential-usage/SKILL.md with:

1. Discover first

Run tsm list --json before assuming a credential is missing. The name field is the canonical id used by tsm get and tsm run --env VAR=<name>.

tsm list --json
# [{"name":"gh-pat","display_name":"GitHub PAT", ...}, ...]

tsm get also resolves canonical env-var names — tsm get GITHUB_TOKEN matches a stored id github-token or a display name like "GitHub Token". When in doubt, list first; the name field is what you want for stable scripts and MCP configs.

If tsm list shows nothing relevant, only then ask the user. If the secret is there but you're not sure which id to use, tsm get <whatever-name-you-have> will suggest near matches when the lookup misses.

That's the only skill change. The rest of the skill (patterns by tool category, never-rules, handoff guidance) stays.

Out of scope / follow-ups

• Aliases as a real field. If we see continued user demand (or want to support multi-binding like one secret being both GITHUB_TOKEN and GH_TOKEN), add aliases: [String] to Secret later. The custom decoder makes this trivially backward compat.
• Fuzzy matching across description/tags. Out of scope; users can grep tsm list --json | jq for that.
• Telemetry on canonical-resolution hits. Could be useful to know how often this path triggers — punt unless someone asks.