Make credential resolution explicit and testable

[patosullivan]

Summary

This PR extracts credential/config resolution into explicit, injectable resolver and credential-flag layers, then updates ensureClient() to honor resolver-owned auth/cache policy instead of implicitly falling back to cached cookies.

The goal is to make auth behavior deterministic and testable without touching a developer's real env, home directory, cache, OpenClaw config, or a live ship.

What Changed

• Added scripts/credential-resolver.ts with explicit resolution metadata:
  • credential origin
  • auth kind
  • cache read/write permissions
  • provenance for mixed sources like --ship plus TLON_SKILL_DIR
• Added scripts/credential-flags.ts for top-level credential flag parsing and validation.
• Updated scripts/api-client.ts so ensureClient() consumes resolver metadata before reading/writing auth cache.
• Tightened cache validation for required fields, URL/ship matching, filename-to-ship matching, duplicate entries, and invalid JSON.
• Kept OpenClaw config JSON-only and removed stale .yaml resolution/docs behavior.
• Updated scripts/main.ts, README.md, and SKILL.md to document the implemented credential forms, resolution order, and cache-write policy.
• Expanded hermetic CLI coverage for credential flag validation and precedence.

Policy Decisions

• CLI credential flags beat ambient credential env/config.
• Valid CLI credential forms are:
  • --config <file>
  • --url <url> --cookie <cookie> with optional --ship and optional fallback --code
  • --url <url> --ship <ship> --code <code>
  • --ship <ship> for TLON_SKILL_DIR or targeted cache lookup
• Partial/conflicting credential flag sets fail locally instead of merging with ambient env.
• Provided-cookie flows do not copy that cookie into cache.
• Code login and code fallback may cache the fresh cookie.
• Explicit and file-backed credentials do not silently read unrelated cached cookies.
• Legacy OpenClaw JSON fallbacks are preserved:
  • ~/.clawdbot/moltbot.json
  • ~/.moltbot/moltbot.json

Tests

Validated locally:

bun test scripts/credential-flags.test.ts
bun test scripts/credential-resolver.test.ts
bun test scripts/api-client.test.ts
bun test ./tests/hermetic
npm run test:unit
npm run test:integration
npm run typecheck
npm run build:smoke
git diff --check

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f743124ed9

ℹ️ 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".

[arthyn]

wonder if we could keep these in sync with main.ts somehow

[arthyn]

the last option should maybe specify "when cached" or similar