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

[gnapse]

Summary

Three backward-compatible ergonomic improvements to reduce CLI friction for both humans and AI agents:

• Lenient ID handling: Accept raw IDs (e.g., 6QwcgwGW2H73WrVJ) everywhere without requiring id: prefix. requireIdRef() removed entirely, replaced by lenientIdRef(). resolveRef() auto-retries raw-ID-looking strings as direct lookups before failing.
• Implicit view subcommand: td project <ref> defaults to td project view <ref> via Commander's { isDefault: true }. Applied to project, task, workspace, comment, notification.
• 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.

Also adds first ADR at docs/decisions/001-lenient-cli-ergonomics.md.

Smoke tests (live account)

Feature	Command	Result
Raw ID	project view <raw-id>	Shows project details
Implicit view	project <raw-id>	Same output (no view needed)
Implicit view + numeric ID	workspace <numeric-id>	Shows workspace details
Implicit view on task	task <raw-id>	Shows task details
Flag alias --project	section list --project "<name>"	Lists sections
Flag alias --workspace	workspace projects --workspace <name> --limit 3	Lists workspace projects

Test plan

• 707 unit tests passing (15 new tests added)
• Type check clean
• Smoke tested against live Todoist account with real workspaces
• All id: prefix usage still works (backward compatible)
• Subcommand names still take priority over implicit view

[doist-bot]

This PR significantly enhances CLI ergonomics by introducing lenient ID handling, implicit view subcommands, and named flag aliases, leading to a more intuitive and efficient user experience. While these changes are a great step forward in improving usability, there are a few areas that could be refined to ensure consistent behavior, specifically regarding error handling for non-existent raw IDs, the proper resolution of section names containing digits, and the organization of certain unit tests.

_{Share Feedback • Review Logs}

[Copilot]

Pull request overview

This PR improves td CLI ergonomics by making references more forgiving (raw IDs), making view the default subcommand for several resources, and adding named flag aliases for positional “context” arguments.

Changes:

• Add lenientIdRef() and update ref resolution to accept raw ID-like strings (and retry raw IDs as direct lookups).
• Make view the default subcommand for project/task/workspace/comment/notification commands.
• Add named flag aliases (--project, --task, --workspace) alongside positional context args, with conflict detection; update docs and tests accordingly.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/lib/skills/content.ts	Updates CLI examples to reflect new flag-alias ergonomics.
src/lib/refs.ts	Introduces lenientIdRef() and raw-ID retry behavior in resolveRef().
src/commands/workspace.ts	Makes view default and adds --workspace alias for projects/users.
src/commands/task.ts	Uses lenientIdRef() and improves --section handling; sets view default.
src/commands/section.ts	Replaces strict ID parsing with lenientIdRef() and adds --project alias.
src/commands/reminder.ts	Replaces strict ID parsing with lenientIdRef() and adds --task alias.
src/commands/project.ts	Makes view the default subcommand.
src/commands/notification.ts	Makes view the default subcommand.
src/commands/label.ts	Refactors label update/delete to use shared resolver; adds raw-ID-like lookup.
src/commands/comment.ts	Uses lenientIdRef() and makes view default.
src/tests/workspace.test.ts	Adds coverage for implicit view and --workspace alias behavior.
src/tests/task.test.ts	Adds coverage for implicit view and updated --section semantics.
src/tests/section.test.ts	Adds coverage for --project alias and updated ref validation wording.
src/tests/reminder.test.ts	Adds coverage for --task alias and updated ref validation wording.
src/tests/refs.test.ts	Updates tests for lenientIdRef() and raw-ID retry behavior.
src/tests/project.test.ts	Adds coverage for implicit view behavior.
src/tests/notification.test.ts	Adds coverage for implicit view behavior.
src/tests/label.test.ts	Adjusts expectations after label resolver refactor.
src/tests/comment.test.ts	Adds coverage for implicit view and updated ref validation wording.
docs/decisions/001-lenient-cli-ergonomics.md	Adds ADR documenting the ergonomics decisions and tradeoffs.
AGENTS.md	Documents new ref parsing, implicit view defaults, and flag aliases for agents/devs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[scottlovegrove]

Just highlighting this as an example, given what this PR is for, should we have something to show that it can be done without the id: in here.

Comment applies to all affected commands.

[gnapse]

The way I see it is, the skill is focused in showing how things can be done. Not necessarily in showing ALL the ways that are supported. The id: prefix is preferred for the edge case in which a task name looks like an ID (unlikely, but still).