perf: show early spinner instantly and keep it running through all API calls

Start a "Loading..." spinner before the dynamic import so there's zero
silence after invoking a command. The spinner is adopted by each API
call's withSpinner (text updates seamlessly), released back on
completion so the next call re-adopts it, and auto-cleared via a
stdout interceptor the moment command output begins.

Also adds getTasksByFilter to the API spinner map so td today,
td upcoming, and td filter show get proper spinner coverage.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: scottlovegrove

src/__tests__/spinner.test.ts

@@ -1,12 +1,20 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { LoadingSpinner, withSpinner } from '../lib/spinner.js'
+import yoctoSpinnerFactory from 'yocto-spinner'
+import {
+    LoadingSpinner,
+    resetEarlySpinner,
+    startEarlySpinner,
+    stopEarlySpinner,
+    withSpinner,
+} from '../lib/spinner.js'
 
 // Mock yocto-spinner
 const mockSpinnerInstance = {
     start: vi.fn().mockReturnThis(),
     success: vi.fn(),
     error: vi.fn(),
     stop: vi.fn(),
+    text: '',
 }
 
 vi.mock('yocto-spinner', () => ({
@@ -29,6 +37,7 @@ vi.mock('chalk', () => ({
 describe('withSpinner', () => {
     beforeEach(() => {
         vi.clearAllMocks()
+        resetEarlySpinner()
         // Reset environment variables
         delete process.env.TD_SPINNER
         delete process.env.CI
@@ -43,6 +52,7 @@ describe('withSpinner', () => {
 
     afterEach(() => {
         vi.clearAllMocks()
+        resetEarlySpinner()
     })
 
     it('should handle successful operations', async () => {
@@ -140,6 +150,7 @@ describe('withSpinner', () => {
 describe('LoadingSpinner', () => {
     beforeEach(() => {
         vi.clearAllMocks()
+        resetEarlySpinner()
         // Reset environment variables
         delete process.env.TD_SPINNER
         delete process.env.CI
@@ -154,6 +165,7 @@ describe('LoadingSpinner', () => {
 
     afterEach(() => {
         vi.clearAllMocks()
+        resetEarlySpinner()
     })
 
     it('should start and stop spinner', () => {
@@ -197,3 +209,150 @@ describe('LoadingSpinner', () => {
         expect(mockSpinnerInstance.error).not.toHaveBeenCalled()
     })
 })
+
+describe('early spinner', () => {
+    const yoctoSpinner = vi.mocked(yoctoSpinnerFactory)
+
+    beforeEach(() => {
+        vi.clearAllMocks()
+        resetEarlySpinner()
+        mockSpinnerInstance.text = ''
+        // Reset environment variables
+        delete process.env.TD_SPINNER
+        delete process.env.CI
+        // Mock TTY as true by default
+        Object.defineProperty(process.stdout, 'isTTY', {
+            value: true,
+            configurable: true,
+        })
+        // Clear process.argv
+        process.argv = ['node', 'td']
+    })
+
+    afterEach(() => {
+        vi.clearAllMocks()
+        resetEarlySpinner()
+    })
+
+    it('should start and stop early spinner', () => {
+        startEarlySpinner()
+
+        expect(yoctoSpinner).toHaveBeenCalledWith({ text: 'Loading...' })
+        expect(mockSpinnerInstance.start).toHaveBeenCalled()
+
+        stopEarlySpinner()
+        expect(mockSpinnerInstance.stop).toHaveBeenCalled()
+    })
+
+    it('should not start early spinner when not in TTY', () => {
+        Object.defineProperty(process.stdout, 'isTTY', {
+            value: false,
+            configurable: true,
+        })
+
+        startEarlySpinner()
+        expect(yoctoSpinner).not.toHaveBeenCalled()
+    })
+
+    it.each([
+        ['--json', ['node', 'td', 'today', '--json']],
+        ['--ndjson', ['node', 'td', 'today', '--ndjson']],
+        ['--no-spinner', ['node', 'td', 'today', '--no-spinner']],
+    ])('should not start early spinner with %s flag', (_flagName, argv) => {
+        process.argv = argv
+
+        startEarlySpinner()
+        expect(yoctoSpinner).not.toHaveBeenCalled()
+    })
+
+    it('should not start early spinner in CI environment', () => {
+        process.env.CI = 'true'
+
+        startEarlySpinner()
+        expect(yoctoSpinner).not.toHaveBeenCalled()
+    })
+
+    it('should not start early spinner when TD_SPINNER=false', () => {
+        process.env.TD_SPINNER = 'false'
+
+        startEarlySpinner()
+        expect(yoctoSpinner).not.toHaveBeenCalled()
+    })
+
+    it('should be adopted by LoadingSpinner.start() — reuses instance and updates text', () => {
+        startEarlySpinner()
+        vi.clearAllMocks()
+
+        const spinner = new LoadingSpinner()
+        spinner.start({ text: 'Loading tasks...', color: 'blue' })
+
+        // Should NOT have created a new yocto-spinner
+        expect(yoctoSpinner).not.toHaveBeenCalled()
+        // Should NOT have called .start() again (already running)
+        expect(mockSpinnerInstance.start).not.toHaveBeenCalled()
+        // Should have updated the text
+        expect(mockSpinnerInstance.text).toBe('Loading tasks...')
+    })
+
+    it('should release back on stop — available for re-adoption by next API call', () => {
+        startEarlySpinner()
+        vi.clearAllMocks()
+
+        // First LoadingSpinner adopts the early spinner
+        const spinner1 = new LoadingSpinner()
+        spinner1.start({ text: 'Loading tasks...', color: 'blue' })
+        expect(yoctoSpinner).not.toHaveBeenCalled()
+
+        // stop() releases it back instead of actually stopping
+        spinner1.stop()
+        expect(mockSpinnerInstance.stop).not.toHaveBeenCalled()
+
+        // Second LoadingSpinner re-adopts the same instance
+        const spinner2 = new LoadingSpinner()
+        spinner2.start({ text: 'Checking authentication...', color: 'blue' })
+        expect(yoctoSpinner).not.toHaveBeenCalled()
+        expect(mockSpinnerInstance.start).not.toHaveBeenCalled()
+        expect(mockSpinnerInstance.text).toBe('Checking authentication...')
+
+        // Final cleanup via stopEarlySpinner actually stops it
+        spinner2.stop()
+        stopEarlySpinner()
+        expect(mockSpinnerInstance.stop).toHaveBeenCalledTimes(1)
+    })
+
+    it('should actually stop on fail even if adopted', () => {
+        startEarlySpinner()
+        vi.clearAllMocks()
+
+        const spinner = new LoadingSpinner()
+        spinner.start({ text: 'Loading tasks...', color: 'blue' })
+        spinner.fail('Request failed')
+
+        expect(mockSpinnerInstance.error).toHaveBeenCalled()
+        // Should not be released back — error terminates the spinner
+        stopEarlySpinner()
+        expect(mockSpinnerInstance.stop).not.toHaveBeenCalled()
+    })
+
+    it('should auto-stop when stdout is written to', () => {
+        startEarlySpinner()
+        expect(mockSpinnerInstance.start).toHaveBeenCalled()
+
+        // Simulate command output — spinner should auto-clear
+        process.stdout.write('output\n')
+        expect(mockSpinnerInstance.stop).toHaveBeenCalled()
+    })
+
+    it('should be cleaned up by stopEarlySpinner if never adopted', () => {
+        startEarlySpinner()
+        expect(mockSpinnerInstance.start).toHaveBeenCalled()
+
+        stopEarlySpinner()
+        expect(mockSpinnerInstance.stop).toHaveBeenCalled()
+
+        // Subsequent stop should be a no-op
+        vi.clearAllMocks()
+        stopEarlySpinner()
+        expect(mockSpinnerInstance.stop).not.toHaveBeenCalled()
+    })
+})

src/index.ts

@@ -2,6 +2,7 @@
 
 import { type Command, program } from 'commander'
 import packageJson from '../package.json' with { type: 'json' }
+import { startEarlySpinner, stopEarlySpinner } from './lib/spinner.js'
 
 program
     .name('td')
@@ -107,11 +108,21 @@ if (commandName && commands[commandName]) {
     const idx = program.commands.findIndex((c) => c.name() === commandName)
     if (idx !== -1) (program.commands as Command[]).splice(idx, 1)
     const loader = commands[commandName][1]
-    const register = await loader()
-    register(program)
+
+    startEarlySpinner()
+    try {
+        const register = await loader()
+        register(program)
+    } catch (err) {
+        stopEarlySpinner()
+        throw err
+    }
 }
 
-program.parseAsync().catch((err: Error) => {
-    console.error(err.message)
-    process.exit(1)
-})
+program
+    .parseAsync()
+    .catch((err: Error) => {
+        console.error(err.message)
+        process.exit(1)
+    })
+    .finally(() => stopEarlySpinner())

src/lib/api/core.ts

@@ -36,6 +36,7 @@ const API_SPINNER_MESSAGES: Record<string, { text: string; color?: 'blue' | 'gre
         updateSection: { text: 'Updating section...', color: 'yellow' },
         deleteSection: { text: 'Deleting section...', color: 'yellow' },
         quickAddTask: { text: 'Adding task...', color: 'green' },
+        getTasksByFilter: { text: 'Loading tasks...', color: 'blue' },
     }
 
 function createSpinnerWrappedApi(api: TodoistApi): TodoistApi {