feat: add verbose/trace output for API latency debugging (-v to -vvvv)

[gwpl]

Summary

Adds stackable verbose output (-v, -vv, -vvv, -vvvv) to stderr for diagnosing API latency and behavior — especially useful for customer support tickets where users need to capture diagnostic traces.

Closes #40

Related to customer support ticket #916983.

Verbosity levels

Flag	Level	What's logged
-v	INFO	API endpoints called, HTTP status, total timing (duration_ms)
-vv	DETAIL	Request params, body sizes, pagination progress (per-page timing)
-vvv	DEBUG	Rate-limit headers, x-request-id, cf-ray, reference resolution steps
-vvvv	TRACE	All request/response headers (Authorization token always redacted)

Also activatable via TD_VERBOSE=1..4 environment variable.

Changes (14 files, +417 lines)

• src/lib/logger.ts — new module: Logger class with 4 verbosity levels + verboseFetch() wrapper (drop-in fetch() replacement that logs timing/headers)
• src/index.ts — register -v, --verbose global Commander option; initialize logger before parsing
• src/lib/spinner.ts — auto-disable spinner when verbose mode is active
• src/lib/api/core.ts — instrument SDK Proxy wrapper with per-call timing + executeSyncCommand() logging
• src/lib/api/{workspaces,stats,reminders,filters,notifications,uploads,user-settings}.ts — replace fetch() → verboseFetch() in all 7 direct-fetch sites
• src/lib/refs.ts — log reference resolution strategy (ID lookup vs name search), match results
• src/lib/pagination.ts — log per-page cursor progression and timing
• src/lib/skills/content.ts — document new flag in agent skill reference

Example output

$ td today -vv 2>&1 | head -20
[td:info] 2026-02-11T09:46:14.778Z verbose logging enabled (level=2)
[td:detail] 2026-02-11T09:46:14.802Z initializing TodoistApi client
[td:info] 2026-02-11T09:46:14.810Z api.getTasks()
[td:detail] 2026-02-11T09:46:14.811Z api.getTasks() params | filter=today | overdue
[td:detail] 2026-02-11T09:46:14.812Z paginate started | limit=300 perPage=200
[td:info] 2026-02-11T09:46:25.953Z api.getTasks() response | duration_ms=11141 result_count=10
[td:detail] 2026-02-11T09:46:25.954Z paginate page 1 done | results=10 has_more=false duration_ms=11142
[td:detail] 2026-02-11T09:46:25.954Z paginate complete | total_results=10 pages_fetched=1

All output goes to stderr with [td:info/detail/debug/trace] prefixes — never pollutes stdout data pipes.

Test plan

• All 675 existing tests pass (29 test files)
• TypeScript build succeeds with zero errors
• td --help shows the new -v, --verbose option
• -v, -vv, -vvv, -vvvv flags produce expected verbosity levels
• TD_VERBOSE=2 env var activates level 2
• Verbose output goes to stderr only (stdout data unaffected)
• Authorization tokens are redacted in trace output
• Manual test with live Todoist API at all 4 verbosity levels

🤖 Generated with Claude Code

[gnapse]

Thanks for putting this together. The verbose/trace idea could be useful for debugging latency, and the global fetch patch approach is right.

My main feedback: I think the PR does more than it needs to. The globalThis.fetch wrapper in logger.ts already captures timing, status, headers, and rate-limit info for every HTTP call the CLI makes. That single patch covers the stated goal ("diagnosing API latency") without touching any business logic.

But on top of that, the PR also manually instruments core.ts (+71 lines), pagination.ts (+28 lines), and refs.ts (+21 lines) with getLogger() calls — which largely duplicate what the fetch wrapper already logs. For example, the Proxy logging in core.ts that logs api.getTasks() with timing is restating what the fetch wrapper already reports as GET /rest/v2/tasks with the same duration_ms.

I'd suggest trimming this down to:

• logger.ts — the Logger class + global fetch patch (the core of your PR, keep it)
• index.ts — register the --verbose flag, call initializeLogger()
• spinner.ts — disable spinner when verbose
• content.ts — document the flag

And drop the changes to core.ts, pagination.ts, and refs.ts entirely. That gets us from +401/-5 across 7 files down to ~215 lines across 4 files, with zero changes to business logic, and the same user-facing functionality.

What do you think?

[gwpl]

AI Assistant:

Thanks for the thoughtful review @gnapse! You're absolutely right — the globalThis.fetch patch already captures timing, status, and headers for every HTTP call, making the manual instrumentation in core.ts, pagination.ts, and refs.ts redundant.

I've pushed dd6e608 which reverts all changes to those 3 files, bringing the PR down to 4 files with zero changes to business logic:

• logger.ts — Logger class + global fetch patch (core of the PR)
• index.ts — --verbose flag registration + initializeLogger()
• spinner.ts — disable spinner when verbose
• content.ts — document the flag

All 675 tests still pass. Appreciate the guidance on keeping it focused!

[gnapse]

Good. Thanks!

There's a pending issue: linting is not passing.

It's failing because of import sort order (Biome). Also, the eslint-disable comment doesn't do anything since this project uses Biome, not ESLint. And the import is actually used anyway so no disable needed.

Quick fix: npm run format

Or here's a patch if easier.

0001-fix-remove-useless-eslint-disable-and-fix-import-ord.patch

I tried contributing this commit myself, but the fork is not allowing push from me.

[gwpl]

Greg + AI Assistant:

Apologies for the lint issue! I (Greg) am primarily a Rust developer, not a JavaScript/TypeScript one — we're putting this PR together with the help of an AI coding assistant, doing our best to deliver useful debug instrumentation for support ticket #916983 and give some code/inspiration along the way.

The import ordering issue in src/index.ts is now fixed in 3d56f3e — the initializeLogger import is sorted to its correct alphabetical position. We verified locally that npm run format:check passes cleanly before pushing.

(The CI runs for the new commit show action_required — likely needs maintainer approval to run workflows on a fork PR.)

Really appreciate the thoughtful review feedback, @gnapse. It's helping us iterate toward a clean, focused contribution together!

[gwpl]

Greg + AI Assistant:

Thanks @gnapse! Good catch on both the import order and the useless eslint-disable comment (we didn't realize the project uses Biome, not ESLint).

Both issues are already addressed in commit 3d56f3e which was pushed ~24 minutes after your review — timing was just unfortunate:

• Import sort order fixed (moved initializeLogger to alphabetical position)
• Removed the eslint-disable-next-line comment entirely

npm run format:check passes cleanly on our end. The CI for 3d56f3e shows action_required — it likely needs maintainer approval to run workflows on a fork PR.

Also thank you for trying to push the fix directly and for attaching the patch — really appreciate the collaborative spirit!