From e9796cbce3a5a6e0f211a8e9835d00df5cbb1bf4 Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Tue, 10 Mar 2026 12:16:02 -0400 Subject: [PATCH] docs: document S3 backend, auto-auth, and `:Pending done` command Problem: The S3 backend had no `:Pending s3` entry in the COMMANDS section, `:Pending auth` only mentioned Google, the `sync` config field omitted `s3`, `_s3_sync_id` was missing from the data format section, `:Pending done` was implemented but undocumented, and the README lacked a features overview. Solution: Add `:Pending s3` and `:Pending done` command docs, rewrite `:Pending auth` to cover all backends and sub-actions, update config and data format references, add `aws` CLI to requirements, and add a Features section to `README.md`. --- README.md | 19 +++++++++++- doc/pending.txt | 82 ++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 86 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 3448941..cff442d 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,27 @@ Oil-like task management for todos in Neovim, inspired by https://github.com/user-attachments/assets/f3898ecb-ec95-43fe-a71f-9c9f49628ba9 +## Features + +- Oil-style buffer editing: standard Vim motions for all task operations +- Inline metadata: `due:`, `cat:`, `rec:` tokens parsed on `:w` +- Rich date input: relative (`+3d`, `tomorrow`), weekdays, ordinals, custom formats, time suffixes +- Recurring tasks with automatic next-date spawning on completion +- Category and queue views with foldable sections +- Multi-level undo (up to 20 saves, persisted across sessions) +- Text objects (`at`/`it`/`aC`/`iC`) and motions (`]]`/`[[`/`]t`/`[t`) +- Omnifunc completion for `due:`, `cat:`, and `rec:` tokens +- Filters: `cat:X`, `overdue`, `today`, `priority`, `wip`, `blocked` +- Google Calendar one-way push via OAuth PKCE +- Google Tasks bidirectional sync via OAuth PKCE +- S3 whole-store sync via AWS CLI with cross-device merge +- Auto-authentication: sync actions trigger auth flows automatically + ## Requirements - Neovim 0.10+ -- (Optionally) `curl` for Google Calendar and Google Task sync +- (Optionally) `curl` for Google Calendar and Google Tasks sync +- (Optionally) `aws` CLI for S3 sync ## Installation diff --git a/doc/pending.txt b/doc/pending.txt index af6a663..f79961e 100644 --- a/doc/pending.txt +++ b/doc/pending.txt @@ -42,6 +42,7 @@ Features: ~ - Omnifunc completion for `cat:`, `due:`, and `rec:` tokens (``) - Google Calendar one-way push via OAuth PKCE - Google Tasks bidirectional sync via OAuth PKCE +- S3 whole-store sync via AWS CLI ============================================================================== CONTENTS *pending-contents* @@ -76,6 +77,7 @@ REQUIREMENTS *pending-requirements* - Neovim 0.10+ - No external dependencies for local use - `curl` is required for the `gcal` and `gtasks` sync backends +- `aws` CLI is required for the `s3` sync backend ============================================================================== INSTALL *pending-install* @@ -167,13 +169,34 @@ COMMANDS *pending-commands* Open the list with |:copen| to navigate to each task's category. *:Pending-auth* -:Pending auth - Authorize pending.nvim to access Google services (Tasks and Calendar). - Prompts with |vim.ui.select| to choose gtasks, gcal, or both — all - options run the same combined OAuth flow and produce a single shared - token file. If no credentials are configured, the setup wizard runs - first to collect a client ID and secret. - See |pending-google-auth| for full details. +:Pending auth [{backend} [{sub-action}]] + Authenticate a sync backend. Without arguments, prompts with + |vim.ui.select| when multiple backends have auth methods. With an + explicit {backend} name, dispatches directly: >vim + :Pending auth gcal + :Pending auth gtasks + :Pending auth s3 + :Pending auth gcal clear + :Pending auth gtasks reset + :Pending auth s3 profile +< + Google backends (gcal, gtasks): ~ + Both share a single OAuth flow with combined scopes. If no credentials + are configured (bundled placeholders in use), the setup wizard runs + first to collect a client ID and secret. Sub-actions: + `clear` Remove OAuth tokens (forces re-authentication). + `reset` Remove tokens and credentials (full reset). + See |pending-google-auth| for details. + + S3 backend: ~ + Runs `aws sts get-caller-identity` to verify AWS credentials. If the + profile uses SSO and the session has expired, runs `aws sso login` + automatically. Sub-actions: + `profile` Prompt for an AWS profile name. + See |pending-s3| for details. + + Auth is triggered automatically when running sync actions without valid + credentials. See |pending-sync-auto-auth|. *:Pending-gtasks* :Pending gtasks {action} @@ -207,6 +230,34 @@ COMMANDS *pending-commands* Tab completion after `:Pending gcal ` lists available actions. See |pending-gcal| for full details. + *:Pending-s3* +:Pending s3 {action} + Run an S3 sync action. An explicit action is required. + + Actions: ~ + `sync` Pull remote changes then push merged result. + `push` Upload the local store to S3. + `pull` Download the remote store and merge into local. + + Examples: >vim + :Pending s3 sync " pull then push + :Pending s3 push " upload local → S3 + :Pending s3 pull " download S3 → local +< + + Tab completion after `:Pending s3 ` lists available actions. + See |pending-s3| for full details. + + *:Pending-done* +:Pending done [{id}] + Mark a task as done without opening the buffer. {id} is the numeric task + ID. When {id} is omitted and the task buffer is open, the task under the + cursor is used. Recurring tasks spawn a new pending instance with the + next due date. >vim + :Pending done 5 + :Pending done +< + *:Pending-filter* :Pending filter {predicates} Apply a filter to the task buffer. {predicates} is a space-separated list @@ -862,9 +913,11 @@ Fields: ~ {sync} (table, default: {}) *pending.SyncConfig* Sync backend configuration. Each key is a backend name and the value is the backend-specific config - table. Built-in backends: `gcal`, `gtasks`. Both - ship bundled OAuth credentials so no setup is - needed beyond `:Pending auth`. + table. Built-in backends: `gcal`, `gtasks`, `s3`. + Google backends ship bundled OAuth credentials so + no setup is needed beyond `:Pending auth`. The S3 + backend delegates to the AWS CLI credential chain. + See |pending-gcal|, |pending-gtasks|, |pending-s3|. {icons} (table) *pending.Icons* Icon characters displayed in the buffer. The @@ -1424,10 +1477,11 @@ Task fields: ~ {order} (integer) Relative ordering within a category. Any field not in the list above is preserved in `_extra` and written back on -save. This is used internally to store the Google Calendar event ID -(`_gcal_event_id`) and Google Tasks IDs (`_gtasks_task_id`, -`_gtasks_list_id`), and allows third-party tooling to annotate tasks without -data loss. +save. This is used internally to store sync backend metadata: +- Google Calendar: `_gcal_event_id`, `_gcal_calendar_id` +- Google Tasks: `_gtasks_task_id`, `_gtasks_list_id` +- S3: `_s3_sync_id` (UUID for cross-device merge) +Third-party tooling can annotate tasks via `_extra` without data loss. The `version` field is checked on load. If the file version is newer than the version the plugin supports, loading is aborted with an error message asking