feat: lenient CLI ergonomics (raw IDs, implicit view, flag aliases) (#60)

Author: gnapse

AGENTS.md

@@ -47,7 +47,9 @@ src/
 
 ## Key Patterns
 
-- **ID references**: All explicit IDs use `id:` prefix. Use `requireIdRef()` for ID-only args, `isIdRef()`/`extractId()` for mixed refs (fuzzy name + explicit ID)
+- **Lenient ID handling**: Raw IDs (alphanumeric or numeric) are accepted everywhere without `id:` prefix. `lenientIdRef()` accepts `id:xxx` or raw ID-like strings, rejects plain text. `resolveRef()` auto-retries raw IDs as direct lookups before giving up. Use `isIdRef()`/`extractId()` for mixed refs (fuzzy name + explicit ID)
+- **Implicit view subcommand**: `td project <ref>` defaults to `td project view <ref>` via Commander's `{ isDefault: true }`. Same for task, workspace, comment, notification. Edge case: if a project/task name matches a subcommand name (e.g., "list"), the subcommand wins — user must use `td project view list`
+- **Named flag aliases**: Where commands accept positional args for context (project, task, workspace), named flags are also accepted (`--project`, `--task`, `--workspace`). Error if both positional and flag are provided
 - **API responses**: Client returns `{ results: T[], nextCursor? }` - always destructure
 - **Priority mapping**: API uses 4=p1 (highest), 1=p4 (lowest)
 - **Command registration**: Each command exports `registerXxxCommand(program: Command)` function

docs/decisions/001-lenient-cli-ergonomics.md

@@ -0,0 +1,26 @@
+# 001: Lenient CLI Ergonomics
+
+## Status
+
+Accepted
+
+## Context
+
+The CLI required strict `id:` prefix for all ID arguments (e.g., `id:6QwcgwGW2H73WrVJ`). This created friction for both human users (copy-pasting IDs from other tools) and AI agents (extra formatting step). Additionally, viewing a resource required spelling out the `view` subcommand, and some positional arguments had no named flag alternative, making them harder to use in scripts.
+
+## Decision
+
+Three ergonomic improvements, all backward compatible:
+
+**1. Lenient ID handling.** Accept raw IDs without `id:` prefix everywhere. `lenientIdRef()` replaces `requireIdRef()`. `resolveRef()` auto-retries raw-ID-looking strings as direct lookups before failing. Detection: `looksLikeRawId()` matches numeric strings or alphanumeric mix (no spaces, not pure alpha).
+
+**2. Implicit view subcommand.** `td project <ref>` defaults to `td project view <ref>` using Commander's `{ isDefault: true }`. Applied to project, task, workspace, comment, notification commands.
+
+**3. Named flag aliases.** Positional context arguments also accept named flags: `--project` (section list), `--task` (reminder list/add), `--workspace` (workspace projects/users). Error if both positional and flag are provided.
+
+## Consequences
+
+- `id:` prefix still works everywhere (backward compatible)
+- Subcommand names take priority over implicit view: a project named "list" requires `td project view list`
+- Skill content documents only canonical forms (explicit subcommands, `id:xxx`) to avoid encouraging collision-prone patterns
+- AGENTS.md documents the full picture including implicit behavior

src/__tests__/comment.test.ts

@@ -199,11 +199,11 @@ describe('comment delete', () => {
         mockGetApi.mockResolvedValue(mockApi)
     })
 
-    it('requires id: prefix', async () => {
+    it('rejects plain text references', async () => {
         const program = createProgram()
 
         await expect(
-            program.parseAsync(['node', 'td', 'comment', 'delete', 'comment-1', '--yes']),
+            program.parseAsync(['node', 'td', 'comment', 'delete', 'my-comment', '--yes']),
         ).rejects.toThrow('INVALID_REF')
     })
 
@@ -251,7 +251,7 @@ describe('comment update', () => {
         mockGetApi.mockResolvedValue(mockApi)
     })
 
-    it('requires id: prefix', async () => {
+    it('rejects plain text references', async () => {
         const program = createProgram()
 
         await expect(
@@ -260,7 +260,7 @@ describe('comment update', () => {
                 'td',
                 'comment',
                 'update',
-                'comment-1',
+                'my-comment',
                 '--content',
                 'New text',
             ]),
@@ -529,14 +529,31 @@ describe('comment view', () => {
         mockGetApi.mockResolvedValue(mockApi)
     })
 
-    it('requires id: prefix', async () => {
+    it('rejects plain text references', async () => {
         const program = createProgram()
 
         await expect(
-            program.parseAsync(['node', 'td', 'comment', 'view', 'comment-1']),
+            program.parseAsync(['node', 'td', 'comment', 'view', 'my-comment']),
         ).rejects.toThrow('INVALID_REF')
     })
 
+    it('implicit view: td comment <ref> behaves like td comment view <ref>', async () => {
+        const program = createProgram()
+        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+
+        mockApi.getComment.mockResolvedValue({
+            id: 'comment-123',
+            content: 'Test content',
+            postedAt: '2026-01-08T10:00:00Z',
+            fileAttachment: null,
+        })
+
+        await program.parseAsync(['node', 'td', 'comment', 'id:comment-123'])
+
+        expect(mockApi.getComment).toHaveBeenCalledWith('comment-123')
+        consoleSpy.mockRestore()
+    })
+
     it('shows full comment content', async () => {
         const program = createProgram()
         const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {})

src/__tests__/label.test.ts

@@ -240,12 +240,16 @@ describe('label delete', () => {
         const program = createProgram()
         const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
 
-        mockApi.getLabels.mockResolvedValue({ results: [], nextCursor: null })
+        mockApi.getLabels.mockResolvedValue({
+            results: [{ id: 'label-123', name: 'urgent' }],
+            nextCursor: null,
+        })
         mockApi.deleteLabel.mockResolvedValue(undefined)
 
         await program.parseAsync(['node', 'td', 'label', 'delete', 'id:label-123', '--yes'])
 
         expect(mockApi.deleteLabel).toHaveBeenCalledWith('label-123')
+        expect(consoleSpy).toHaveBeenCalledWith('Deleted: @urgent')
         consoleSpy.mockRestore()
     })
 

src/__tests__/notification.test.ts

@@ -278,6 +278,18 @@ describe('notification view', () => {
         vi.clearAllMocks()
     })
 
+    it('implicit view: td notification <ref> behaves like td notification view <ref>', async () => {
+        const program = createProgram()
+        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+
+        mockFetchNotifications.mockResolvedValue([createShareInvite()])
+
+        await program.parseAsync(['node', 'td', 'notification', 'id:notif-1'])
+
+        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('share_invitation_sent'))
+        consoleSpy.mockRestore()
+    })
+
     it('shows notification details', async () => {
         const program = createProgram()
         const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {})

src/__tests__/project.test.ts

@@ -186,6 +186,23 @@ describe('project view', () => {
         expect(mockApi.getProject).toHaveBeenCalledWith('proj-1')
     })
 
+    it('implicit view: td project <ref> behaves like td project view <ref>', async () => {
+        const program = createProgram()
+
+        mockApi.getProject.mockResolvedValue({
+            id: 'proj-1',
+            name: 'Work',
+            color: 'blue',
+            isFavorite: false,
+            url: 'https://...',
+        })
+        mockApi.getTasks.mockResolvedValue({ results: [], nextCursor: null })
+
+        await program.parseAsync(['node', 'td', 'project', 'id:proj-1'])
+
+        expect(mockApi.getProject).toHaveBeenCalledWith('proj-1')
+    })
+
     it('shows project details', async () => {
         const program = createProgram()
 

src/__tests__/refs.test.ts

@@ -2,8 +2,8 @@ import { describe, expect, it, vi } from 'vitest'
 import {
     extractId,
     isIdRef,
+    lenientIdRef,
     looksLikeRawId,
-    requireIdRef,
     resolveParentTaskId,
     resolveProjectId,
     resolveProjectRef,
@@ -47,19 +47,28 @@ describe('extractId', () => {
     })
 })
 
-describe('requireIdRef', () => {
+describe('lenientIdRef', () => {
     it('returns ID when valid id: prefix', () => {
-        expect(requireIdRef('id:123', 'task')).toBe('123')
-        expect(requireIdRef('id:sec-1', 'section')).toBe('sec-1')
+        expect(lenientIdRef('id:123', 'task')).toBe('123')
+        expect(lenientIdRef('id:sec-1', 'section')).toBe('sec-1')
     })
 
-    it('throws with formatted error for invalid ref', () => {
-        expect(() => requireIdRef('some-name', 'comment')).toThrow('INVALID_REF')
-        expect(() => requireIdRef('some-name', 'comment')).toThrow('Invalid comment reference')
+    it('accepts raw alphanumeric IDs', () => {
+        expect(lenientIdRef('6fmg66Fr27R59RPg', 'task')).toBe('6fmg66Fr27R59RPg')
+        expect(lenientIdRef('abc123', 'section')).toBe('abc123')
     })
 
-    it('includes hint in error message', () => {
-        expect(() => requireIdRef('abc', 'section')).toThrow('id:abc')
+    it('accepts raw numeric IDs', () => {
+        expect(lenientIdRef('12345678', 'task')).toBe('12345678')
+    })
+
+    it('throws for plain text names', () => {
+        expect(() => lenientIdRef('some-name', 'comment')).toThrow('INVALID_REF')
+        expect(() => lenientIdRef('Shopping', 'project')).toThrow('INVALID_REF')
+    })
+
+    it('throws for strings with spaces', () => {
+        expect(() => lenientIdRef('Buy milk', 'task')).toThrow('INVALID_REF')
     })
 })
 
@@ -181,6 +190,17 @@ describe('resolveTaskRef', () => {
         await expect(resolveTaskRef(api, 'nonexistent')).rejects.toThrow('not found')
         expect(api.getTask).not.toHaveBeenCalled()
     })
+
+    it('rethrows non-404 API errors from raw ID fallback', async () => {
+        const { TodoistRequestError } = await import('@doist/todoist-api-typescript')
+        const networkError = new TodoistRequestError('Service Unavailable', 503)
+        const api = createMockApi({
+            getTask: vi.fn().mockRejectedValue(networkError),
+            getTasksByFilter: vi.fn().mockResolvedValue({ results: [], nextCursor: null }),
+        })
+
+        await expect(resolveTaskRef(api, '6fmg66Fr27R59RPg')).rejects.toThrow('Service Unavailable')
+    })
 })
 
 describe('resolveProjectRef', () => {
@@ -246,6 +266,37 @@ describe('resolveProjectRef', () => {
 
         await expect(resolveProjectRef(api, 'nonexistent')).rejects.toThrow('not found')
     })
+
+    it('auto-retries id-like refs as direct ID lookup', async () => {
+        const api = createMockApi({
+            getProject: vi.fn().mockResolvedValue(projects[0]),
+            getProjects: vi.fn().mockResolvedValue({ results: [] }),
+        })
+
+        const result = await resolveProjectRef(api, '6fmg66Fr27R59RPg')
+        expect(result.id).toBe('proj-1')
+        expect(api.getProject).toHaveBeenCalledWith('6fmg66Fr27R59RPg')
+    })
+
+    it('auto-retries numeric refs as direct ID lookup', async () => {
+        const api = createMockApi({
+            getProject: vi.fn().mockResolvedValue(projects[0]),
+            getProjects: vi.fn().mockResolvedValue({ results: [] }),
+        })
+
+        const result = await resolveProjectRef(api, '12345678')
+        expect(result.id).toBe('proj-1')
+        expect(api.getProject).toHaveBeenCalledWith('12345678')
+    })
+
+    it('does not auto-retry plain text refs', async () => {
+        const api = createMockApi({
+            getProjects: vi.fn().mockResolvedValue({ results: projects }),
+        })
+
+        await expect(resolveProjectRef(api, 'nonexistent')).rejects.toThrow('not found')
+        expect(api.getProject).not.toHaveBeenCalled()
+    })
 })
 
 describe('resolveProjectId', () => {
@@ -333,6 +384,16 @@ describe('resolveSectionId', () => {
             'not found in project',
         )
     })
+
+    it('resolves raw ID-like string as section ID', async () => {
+        const sectionsWithNumericId = [...sections, { id: '99887766', name: 'Done' }]
+        const api = createMockApi({
+            getSections: vi.fn().mockResolvedValue({ results: sectionsWithNumericId }),
+        })
+
+        const result = await resolveSectionId(api, '99887766', 'proj-1')
+        expect(result).toBe('99887766')
+    })
 })
 
 describe('resolveParentTaskId', () => {
@@ -421,4 +482,13 @@ describe('resolveParentTaskId', () => {
             'not found in project',
         )
     })
+
+    it('accepts raw ID-like string without id: prefix', async () => {
+        const api = createMockApi({
+            getTasks: vi.fn().mockResolvedValue({ results: [] }),
+        })
+
+        const result = await resolveParentTaskId(api, '6fmg66Fr27R59RPg', 'proj-1')
+        expect(result).toBe('6fmg66Fr27R59RPg')
+    })
 })