feat(auth): add migrateLegacyAuth helper (4/4)

[scottlovegrove]

Stack position: 4 / 4 — base is #27 (feat/keyring-token-store-multi-account). Replaces the last part of #24.

Summary

Generic one-time helper that walks a v1 single-user keyring + plaintext config slot into the v2 multi-account UserRecordStore + per-user keyring slots. Builds on writeRecordWithKeyringFallback from #27 so the migration write path is the same as runtime set(): keyring → fallbackToken on SecureStoreUnavailableError, with rollback on upsert failure.

Best-effort throughout: identify-failure, keyring-write-failure, and upsert-failure all return a skipped status without touching the v1 state, so the consumer's runtime fallback can keep serving the legacy token until the next attempt. Default promotion, legacy keyring delete, and cleanupLegacyConfig are all best-effort outside the critical section.

stderr output uses a fixed phrase keyed off an internal SkipReason enum so consumer-supplied exception text (which may contain emails, paths, or auth diagnostics) can't leak into logs. The raw detail is still attached to MigrateAuthResult.reason for in-process callers.

Usage

import { migrateLegacyAuth } from '@doist/cli-core/auth'

await migrateLegacyAuth<Account>({
    serviceName: 'todoist-cli',
    legacyAccount: 'api-token',
    userRecords,
    loadLegacyPlaintextToken: async () => readConfig().api_token ?? null,
    identifyAccount: async (token) => fetchUser(token),
    cleanupLegacyConfig: async () => clearLegacyAuthFields(),
    silent: true,
    logPrefix: 'todoist-cli',
})

Test plan

• npm run type-check, npm run check, npm test (336 passing, +8 for migrate covering already-migrated / no-legacy-state / online keyring / plaintext fallback / fully-offline keyring / identify-failure / two privacy assertions)
• Smoke from a todoist-cli postinstall against a v1 install.

🤖 Generated with Claude Code

[doistbot]

This PR introduces the final piece of the multi-account auth migration by adding a helper to transition legacy single-user states into the new UserRecordStore. The implementation provides a thoughtful, best-effort fallback mechanism that gracefully handles runtime errors while aiming to protect sensitive user data. However, there are a few areas to refine, such as ensuring the migration is strictly idempotent to prevent stale tokens from triggering accidental re-logins if the initial cleanup fails. Additional adjustments are noted around tightening the return type with a discriminated union, running I/O cleanup operations concurrently, refining how unavailable keyrings are handled, and removing unreachable skip reasons or potentially sensitive log fields.

_{Share Feedback • Review Logs}

[scottlovegrove]

@doistbot /review

[doistbot]

This PR introduces a well-structured helper for migrating legacy single-user authentication states into the new v2 multi-account architecture. The best-effort design provides a robust upgrade path while successfully avoiding credential leakage in the logs. A few adjustments are needed to preserve existing default accounts during retries, safely catch synchronous errors in cleanup callbacks, and properly export the new skip reason types. Additionally, refining the legacy store instantiation, updating the README examples to include config paths, and adding tests for custom account mappings and legacy precedence will help ensure the migration logic is completely solid.

_{Share Feedback • Review Logs}

[doist-release-bot]

🎉 This PR is included in version 0.16.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀