token: unlock with PIN, print + verify saved token, fix launcher warning

[marciogranzotto]

Release Note

bond token can now unlock the token with the Bond PIN, prints the token value when it saves one, and — when the token is locked but one is already saved locally — tells you whether that saved token is still valid, obsolete, or unreachable instead of leaving you to guess. The launcher no longer prints a pkg_resources deprecation warning on every run.

Why

• Until now the only way to get a token via bond token was for the Bond to already be unlocked (e.g. just after a reboot). Unlocking with the PIN was only possible through bond select --pin.
• bond token confirmed it saved a token but never showed the value.
• When the token was locked, bond token told the user "If this token is obsolete, you will need to set the new token" — pushing the work of figuring out obsolescence onto them, even though the CLI can just test it.
• The installed bond launcher printed a DeprecationWarning: pkg_resources is deprecated on every invocation.

What Changed

Four focused commits:

1. bond token --pin — wires the existing unlock_token() helper into the command. bond token --pin <pin> unlocks with the PIN; bond token --pin prompts for it.
2. Print the token value — update_token() now includes the token in its output, so every save path (bond token <token>, --pin, and the unlocked-grace-period path) shows the value.
3. Verify the saved token when locked — new check_stored_token() probes the saved token against an authenticated endpoint (devices) and reports valid / obsolete / unreachable. Per the Bond Local API v2 spec, every endpoint except /sys/version and /token requires the BOND-Token, so devices is a reliable probe (2xx = valid, 401 = obsolete).
4. Launcher fix — replaces the deprecated scripts=["bond/bond"] with a console_scripts entry point (bond=bond.app:main), eliminating the pkg_resources shim/warning. Extracts main() into bond.app and has __main__.py reuse it so bond and python -m bond share one code path. The bond/bond script is removed.

Testing Notes

• Verified bond token --pin <pin> against a real Bond — successfully unlocked and saved the token.
• Verified bond token (locked, with a valid saved token) against a real Bond — correctly reported the saved token as still valid.
• Exercised all dispatch paths and all four locked-token outcomes (valid / obsolete / unreachable / no saved token) with the network mocked.
• flake8 clean on all changed files; existing test suite passes.

Security Analysis

No new auth or transport behavior. The validity probe reuses the existing authenticated HTTP path and the locally-stored token; it sends one read-only GET /v2/devices. bond token now prints the token value to stdout, consistent with the CLI already printing stored tokens elsewhere (Bond Local API tokens are local-network credentials).

Agentic Engineering

• Model: Claude Opus 4.8 (1M context)

• Context: Bond Local API v2 docs (bondhome/api-v2, token/paths.yaml) were consulted to confirm which endpoints require the BOND-Token before choosing devices as the validity probe.

• Prompt: Kicked off with:

  "For unlocking a bond we need to use bond token which needs the token or for the bond to be unlocked. I want to make it possible to unlock with the pin too"

  then redirected with:

  "can you make bond token also print the token?"

  "we could try the actual token we have saved and tell the user if its obsolete or not"

  "can we fix this warning?" (the pkg_resources deprecation)

• Tool: org-knowledge MCP for the Bond API v2 endpoint-auth reference.

• Skill: superpowers:brainstorming for the initial design; commit and bond-dev:pr for delivery.