inboxd 1.0.12 → 1.0.13

package/.claude/skills/inbox-assistant/SKILL.md

@@ -18,7 +18,10 @@ You are an inbox management assistant. Your goal is to help the user achieve **i
 
 ### Core Principles
 
-1. **Be proactive, not reactive** - After every action, suggest the next step. Don't wait for the user to ask "what now?"
+1. **Be proactive, not reactive** - After every action, **suggest** the next step. Don't wait for the user to ask "what now?"
+   - **Proactive means:** "I found 12 newsletters - want me to delete them?"
+   - **Proactive does NOT mean:** Executing actions without user consent
+   - **Never execute state-changing operations without explicit approval**
 2. **Prioritize by impact** - Tackle the most cluttered account first. Surface emails that need ACTION before FYI emails.
 3. **Minimize decisions** - Group similar items, suggest batch actions. Don't make the user review 50 emails individually.
 4. **Respect their time** - Old emails (>30 days) rarely need individual review. Summarize, don't itemize.
@@ -67,6 +70,42 @@ Use when: Heavy inbox (>30 unread), user wants thoroughness, language like "what
 
 ---
 
+## Inbox Zero Philosophy
+
+> [!NOTE]
+> "Inbox Zero" is a user preference, not a default goal.
+
+### What Inbox Zero Means
+
+Inbox Zero is a productivity philosophy where users aim to keep their inbox empty or near-empty. This is achieved by:
+- Acting on actionable emails immediately
+- Archiving reference emails
+- Deleting noise (newsletters, promotions, notifications)
+- Using labels/folders for organization
+
+### Agent Behavior
+
+**DO NOT** assume the user wants inbox zero unless they explicitly say so.
+
+| User Says | Interpretation |
+|-----------|----------------|
+| "Clean up my inbox" | Remove obvious junk, preserve the rest |
+| "Help me reach inbox zero" | Aggressive triage, archive/delete most |
+| "Triage my emails" | Categorize and recommend actions |
+| "Delete everything old" | User explicitly wants bulk cleanup |
+| "Check my emails" | Summary only, no state changes |
+
+### Default Behavior
+
+Unless the user says "inbox zero" or similar:
+1. **Preserve by default** - Keep emails unless clearly deletable
+2. **Suggest, don't execute** - "These 12 newsletters could be deleted" not "I'll delete these"
+3. **Ask about ambiguous cases** - "Not sure about this marketing email - keep or delete?"
+4. **Respect the user's system** - They may have reasons for keeping old emails
+5. **Never mark as read without asking** - Unread status is user's to-do list
+
+---
+
 ## Heavy Inbox Strategy
 
 When a user has a heavy inbox (>20 unread emails), use this optimized workflow:
@@ -290,6 +329,7 @@ To stop: `launchctl unload ~/Library/LaunchAgents/com.yourname.inboxd.plist`
 | `inbox restore --last N` | Restore last N deleted emails |
 | `inbox restore --ids "id1,id2"` | Restore specific emails |
 | `inbox mark-read --ids "id1,id2"` | Mark emails as read (remove UNREAD label) |
+| `inbox mark-unread --ids "id1,id2"` | Mark emails as unread (add UNREAD label) |
 | `inbox archive --ids "id1,id2" --confirm` | Archive emails (remove from inbox, keep in All Mail) |
 | `inbox deletion-log` | View recent deletions |
 
@@ -565,13 +605,29 @@ When user has job-related emails (LinkedIn, Indeed, recruiters) and wants to eva
 > [!CAUTION]
 > These constraints are non-negotiable.
 
+### Deletion Safety
 1. **NEVER auto-delete** - Always confirm before deletion, but adapt confirmation style to batch size
 2. **NEVER delete Action Required emails** - Surface them, let user decide
 3. **NEVER delete without --confirm flag** - Command will hang otherwise
 4. **Always remind about undo** - After every deletion, mention `inbox restore --last N`
-5. **Preserve by default** - When in doubt about classification, keep the email
-6. **Multi-Account Safety** - Always use `--account <name>` for `delete` and `analyze` commands
-7. **Respect user preferences** - If they say "don't list everything", remember and adapt
+
+### State Change Safety
+5. **Confirm before mark-read** - Marking as read can hide important emails. Confirm batch operations (3+ emails)
+6. **Remind about mark-unread undo** - After mark-read, mention: "To undo: `inbox mark-unread --ids \"id1,id2\"`"
+7. **Confirm before archive** - Archiving removes emails from inbox view. Always use `--confirm` flag
+8. **Never batch mark-read silently** - Show what will be marked read before executing
+
+### General Safety
+9. **Preserve by default** - When in doubt about classification, keep the email
+10. **Multi-Account Safety** - Always use `--account <name>` for `delete`, `mark-read`, `mark-unread`, and `archive` commands
+11. **Respect user preferences** - If they say "don't list everything", remember and adapt
+
+### Undo Commands Reference
+| Action | Undo Command |
+|--------|--------------|
+| Deleted emails | `inbox restore --last N` |
+| Marked as read | `inbox mark-unread --ids "id1,id2,..."` |
+| Archived | No CLI undo - must use Gmail web |
 
 ---
 
@@ -659,6 +715,82 @@ Reply with the number or describe which one.
 
 ---
 
+## Interaction Model
+
+> [!IMPORTANT]
+> This section defines how to present multi-step plans to users. Following this model prevents executing without user understanding.
+
+### Plan-Before-Execute Pattern
+
+When a task involves multiple actions, **always present the plan first**:
+
+1. **Announce the plan** - State what you intend to do in numbered steps
+2. **Wait for approval** - Ask "Should I proceed?" or "Ready to start?"
+3. **Execute incrementally** - Complete one step, report, then ask before next step
+4. **Summarize at end** - Show what was done with undo options
+
+### Example: Multi-Step Triage
+
+**Bad (executes without consent):**
+```
+Looking at your inbox...
+[Analyzes 47 emails]
+I've classified your emails. Here's the breakdown:
+- 12 newsletters (marked as read)
+- 8 LinkedIn alerts (deleted)
+- 27 remaining
+
+Done! To undo deletions: inbox restore --last 8
+```
+
+**Good (plan-first approach):**
+```
+Looking at your inbox...
+
+## Triage Plan for work@company.com (47 unread)
+
+I'll process your inbox in these steps:
+1. **Group by sender** - Find batch cleanup opportunities
+2. **Identify deletables** - Newsletters, job alerts, promotions
+3. **Surface action items** - Emails needing your response
+4. **Propose cleanup** - Show what I'd delete, get your OK
+
+Ready to start?
+```
+
+After user says "yes":
+```
+Step 1 complete. Found 3 high-volume senders:
+- linkedin.com (12 emails)
+- substack.com (8 emails)
+- github.com (6 notifications)
+
+Step 2: These 20 emails are cleanup candidates (newsletters + job alerts).
+Want me to list them, or proceed to Step 3 (find action items)?
+```
+
+### Confirmation Thresholds
+
+| Batch Size | Confirmation Approach |
+|------------|----------------------|
+| 1-3 emails | Inline confirmation, can proceed quickly |
+| 4-10 emails | Show summary, ask "Delete these 7?" |
+| 11-25 emails | Show categorized summary, ask "Proceed with cleanup?" |
+| 25+ emails | Present full plan, confirm before any execution |
+
+### State Changes Require Explicit Approval
+
+**Actions that modify email state (always confirm):**
+- `delete` - Always requires confirmation
+- `mark-read` - Confirm if batch (3+), mention undo
+- `archive` - Confirm always, warn about no CLI undo
+- `send` / `reply` - Requires `--confirm` flag
+
+**Read-only actions (no confirmation needed):**
+- `summary`, `analyze`, `search`, `read`, `accounts`
+
+---
+
 ## Feedback Loop
 
 If the user encounters a bug, friction point, or suggests a feature:
@@ -679,6 +811,10 @@ If the user encounters a bug, friction point, or suggests a feature:
 | Skipping pre-flight check | Tool may not be installed | Always run `inbox --version` first |
 | Forgetting `--account` flag | Ambiguity errors with multi-account | Always specify account |
 | Being passive after actions | User has to drive every step | Proactively suggest next step |
+| Executing mark-read on batch without confirmation | User loses unread status on important emails | Confirm 3+ emails, always mention undo |
+| Assuming user wants inbox zero | May delete emails user wanted to keep | Ask first, preserve by default |
+| Executing multi-step plan without presenting it | User doesn't know what happened or why | Use plan-before-execute pattern |
+| Auto-archiving "FYI" emails | User may want them visible in inbox | Archive only on explicit request |
 
 ---
 

package/CLAUDE.md

@@ -80,11 +80,25 @@ All user data lives in `~/.config/inboxd/`:
 
 ## Release Process
 
-1. Bump version in `package.json`
-2. Commit changes
-3. Create a GitHub Release (e.g., `gh release create v1.0.3`)
+**After merging a feature/fix PR to main, always release:**
+
+1. `npm version patch` (or `minor`/`major` as appropriate)
+2. Commit and push: `git add package*.json && git commit -m "chore: bump version to X.X.X" && git push`
+3. Create release with quality notes:
+   ```bash
+   gh release create vX.X.X --title "vX.X.X" --notes "$(cat <<'EOF'
+   ## What's New
+   - Feature 1: description
+   - Feature 2: description
+
+   ## Fixes
+   - Fix 1: description
+   EOF
+   )"
+   ```
 4. The `publish.yml` workflow will automatically test and publish to npm
-   - Note: `src/cli.js` dynamically imports version from `package.json` to ensure consistency
+
+Note: `src/cli.js` dynamically imports version from `package.json` to ensure consistency.
 
 ## AI Agent Integration
 
@@ -153,6 +167,8 @@ scripts/postinstall.js    # npm postinstall hint about install-skill
 | `inbox search -q <query>` | Search using Gmail query syntax |
 | `inbox send -t <to> -s <subj> -b <body> --confirm` | Send email (requires --confirm) |
 | `inbox reply --id <id> -b <body> --confirm` | Reply to email (requires --confirm) |
+| `inbox mark-read --ids "id1,id2"` | Mark emails as read |
+| `inbox mark-unread --ids "id1,id2"` | Mark emails as unread (undo mark-read) |
 | `inbox install-skill` | Install/update the Claude Code skill |
 
 ### Smart Filtering Options

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inboxd",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "CLI assistant for Gmail monitoring with multi-account support and AI-ready JSON output",
   "main": "src/cli.js",
   "bin": {

package/src/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 const { program } = require('commander');
-const { getUnreadEmails, getEmailCount, trashEmails, getEmailById, untrashEmails, markAsRead, archiveEmails, groupEmailsBySender, getEmailContent, searchEmails, sendEmail, replyToEmail, extractLinks } = require('./gmail-monitor');
+const { getUnreadEmails, getEmailCount, trashEmails, getEmailById, untrashEmails, markAsRead, markAsUnread, archiveEmails, groupEmailsBySender, getEmailContent, searchEmails, sendEmail, replyToEmail, extractLinks } = require('./gmail-monitor');
 const { getState, updateLastCheck, markEmailsSeen, getNewEmailIds, clearOldSeenEmails } = require('./state');
 const { notifyNewEmails } = require('./notifier');
 const { authorize, addAccount, getAccounts, getAccountEmail, removeAccount, removeAllAccounts, renameTokenFile, validateCredentialsFile, hasCredentials, isConfigured, installCredentials } = require('./gmail-auth');
@@ -1325,6 +1325,64 @@ async function main() {
       }
     });
 
+  program
+    .command('mark-unread')
+    .description('Mark emails as unread')
+    .requiredOption('--ids <ids>', 'Comma-separated message IDs to mark as unread')
+    .option('-a, --account <name>', 'Account name')
+    .action(async (options) => {
+      try {
+        const ids = options.ids.split(',').map(id => id.trim()).filter(Boolean);
+
+        if (ids.length === 0) {
+          console.log(chalk.yellow('No message IDs provided.'));
+          return;
+        }
+
+        // Get account - if not specified, try to find from configured accounts
+        let account = options.account;
+        if (!account) {
+          const accounts = getAccounts();
+          if (accounts.length === 1) {
+            account = accounts[0].name;
+          } else if (accounts.length > 1) {
+            console.log(chalk.yellow('Multiple accounts configured. Please specify --account <name>'));
+            console.log(chalk.gray('Available accounts:'));
+            accounts.forEach(a => console.log(chalk.gray(`  - ${a.name}`)));
+            return;
+          } else {
+            account = 'default';
+          }
+        }
+
+        console.log(chalk.cyan(`Marking ${ids.length} email(s) as unread...`));
+
+        const results = await markAsUnread(account, ids);
+
+        const succeeded = results.filter(r => r.success).length;
+        const failed = results.filter(r => !r.success).length;
+
+        if (succeeded > 0) {
+          console.log(chalk.green(`\nMarked ${succeeded} email(s) as unread.`));
+        }
+        if (failed > 0) {
+          console.log(chalk.red(`Failed to mark ${failed} email(s) as unread.`));
+          results.filter(r => !r.success).forEach(r => {
+            console.log(chalk.red(`  - ${r.id}: ${r.error}`));
+          });
+        }
+
+      } catch (error) {
+        if (error.message.includes('403') || error.code === 403) {
+          console.error(chalk.red('Permission denied. You may need to re-authenticate with updated scopes.'));
+          console.error(chalk.yellow('Run: inbox auth -a <account>'));
+        } else {
+          console.error(chalk.red('Error marking emails as unread:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
+
   program
     .command('archive')
     .description('Archive emails (remove from inbox, keep in All Mail)')

package/src/gmail-monitor.js

@@ -209,6 +209,34 @@ async function markAsRead(account, messageIds) {
   return results;
 }
 
+/**
+ * Marks emails as unread by adding the UNREAD label
+ * @param {string} account - Account name
+ * @param {Array<string>} messageIds - Array of message IDs to mark as unread
+ * @returns {Array<{id: string, success: boolean, error?: string}>} Results for each message
+ */
+async function markAsUnread(account, messageIds) {
+  const gmail = await getGmailClient(account);
+  const results = [];
+
+  for (const id of messageIds) {
+    try {
+      await withRetry(() => gmail.users.messages.modify({
+        userId: 'me',
+        id: id,
+        requestBody: {
+          addLabelIds: ['UNREAD'],
+        },
+      }));
+      results.push({ id, success: true });
+    } catch (err) {
+      results.push({ id, success: false, error: err.message });
+    }
+  }
+
+  return results;
+}
+
 /**
  * Archives emails by removing the INBOX label
  * @param {string} account - Account name
@@ -646,6 +674,7 @@ module.exports = {
   getEmailById,
   untrashEmails,
   markAsRead,
+  markAsUnread,
   archiveEmails,
   extractSenderDomain,
   groupEmailsBySender,

package/tests/gmail-monitor.test.js

@@ -132,4 +132,297 @@ describe('Gmail Monitor Logic', () => {
       }
     });
   });
+
+  describe('Mark As Read Logic', () => {
+    it('should mark email as read by removing UNREAD label', async () => {
+      const mockGmail = {
+        users: {
+          messages: {
+            modify: vi.fn().mockResolvedValue({ data: { id: 'msg123', labelIds: ['INBOX'] } })
+          }
+        }
+      };
+
+      const messageIds = ['msg123'];
+      const results = [];
+
+      for (const id of messageIds) {
+        try {
+          await mockGmail.users.messages.modify({
+            userId: 'me',
+            id: id,
+            requestBody: { removeLabelIds: ['UNREAD'] }
+          });
+          results.push({ id, success: true });
+        } catch (err) {
+          results.push({ id, success: false, error: err.message });
+        }
+      }
+
+      expect(results).toHaveLength(1);
+      expect(results[0].success).toBe(true);
+      expect(mockGmail.users.messages.modify).toHaveBeenCalledWith({
+        userId: 'me',
+        id: 'msg123',
+        requestBody: { removeLabelIds: ['UNREAD'] }
+      });
+    });
+
+    it('should handle errors during mark as read', async () => {
+      const mockGmail = {
+        users: {
+          messages: {
+            modify: vi.fn().mockRejectedValue(new Error('API Error'))
+          }
+        }
+      };
+
+      const messageIds = ['msg123'];
+      const results = [];
+
+      for (const id of messageIds) {
+        try {
+          await mockGmail.users.messages.modify({
+            userId: 'me',
+            id: id,
+            requestBody: { removeLabelIds: ['UNREAD'] }
+          });
+          results.push({ id, success: true });
+        } catch (err) {
+          results.push({ id, success: false, error: err.message });
+        }
+      }
+
+      expect(results).toHaveLength(1);
+      expect(results[0].success).toBe(false);
+      expect(results[0].error).toBe('API Error');
+    });
+
+    it('should handle multiple message IDs for mark as read', async () => {
+      const mockModify = vi.fn()
+        .mockResolvedValueOnce({ data: { id: 'msg1' } })
+        .mockResolvedValueOnce({ data: { id: 'msg2' } })
+        .mockRejectedValueOnce(new Error('Not found'));
+
+      const mockGmail = {
+        users: { messages: { modify: mockModify } }
+      };
+
+      const messageIds = ['msg1', 'msg2', 'msg3'];
+      const results = [];
+
+      for (const id of messageIds) {
+        try {
+          await mockGmail.users.messages.modify({
+            userId: 'me',
+            id: id,
+            requestBody: { removeLabelIds: ['UNREAD'] }
+          });
+          results.push({ id, success: true });
+        } catch (err) {
+          results.push({ id, success: false, error: err.message });
+        }
+      }
+
+      expect(results).toHaveLength(3);
+      expect(results[0]).toEqual({ id: 'msg1', success: true });
+      expect(results[1]).toEqual({ id: 'msg2', success: true });
+      expect(results[2]).toEqual({ id: 'msg3', success: false, error: 'Not found' });
+    });
+  });
+
+  describe('Mark As Unread Logic', () => {
+    it('should mark email as unread by adding UNREAD label', async () => {
+      const mockGmail = {
+        users: {
+          messages: {
+            modify: vi.fn().mockResolvedValue({ data: { id: 'msg123', labelIds: ['INBOX', 'UNREAD'] } })
+          }
+        }
+      };
+
+      const messageIds = ['msg123'];
+      const results = [];
+
+      for (const id of messageIds) {
+        try {
+          await mockGmail.users.messages.modify({
+            userId: 'me',
+            id: id,
+            requestBody: { addLabelIds: ['UNREAD'] }
+          });
+          results.push({ id, success: true });
+        } catch (err) {
+          results.push({ id, success: false, error: err.message });
+        }
+      }
+
+      expect(results).toHaveLength(1);
+      expect(results[0].success).toBe(true);
+      expect(mockGmail.users.messages.modify).toHaveBeenCalledWith({
+        userId: 'me',
+        id: 'msg123',
+        requestBody: { addLabelIds: ['UNREAD'] }
+      });
+    });
+
+    it('should handle errors during mark as unread', async () => {
+      const mockGmail = {
+        users: {
+          messages: {
+            modify: vi.fn().mockRejectedValue(new Error('Permission denied'))
+          }
+        }
+      };
+
+      const messageIds = ['msg123'];
+      const results = [];
+
+      for (const id of messageIds) {
+        try {
+          await mockGmail.users.messages.modify({
+            userId: 'me',
+            id: id,
+            requestBody: { addLabelIds: ['UNREAD'] }
+          });
+          results.push({ id, success: true });
+        } catch (err) {
+          results.push({ id, success: false, error: err.message });
+        }
+      }
+
+      expect(results).toHaveLength(1);
+      expect(results[0].success).toBe(false);
+      expect(results[0].error).toBe('Permission denied');
+    });
+
+    it('should handle multiple message IDs for mark as unread', async () => {
+      const mockModify = vi.fn()
+        .mockResolvedValueOnce({ data: { id: 'msg1' } })
+        .mockRejectedValueOnce(new Error('Not found'))
+        .mockResolvedValueOnce({ data: { id: 'msg3' } });
+
+      const mockGmail = {
+        users: { messages: { modify: mockModify } }
+      };
+
+      const messageIds = ['msg1', 'msg2', 'msg3'];
+      const results = [];
+
+      for (const id of messageIds) {
+        try {
+          await mockGmail.users.messages.modify({
+            userId: 'me',
+            id: id,
+            requestBody: { addLabelIds: ['UNREAD'] }
+          });
+          results.push({ id, success: true });
+        } catch (err) {
+          results.push({ id, success: false, error: err.message });
+        }
+      }
+
+      expect(results).toHaveLength(3);
+      expect(results[0]).toEqual({ id: 'msg1', success: true });
+      expect(results[1]).toEqual({ id: 'msg2', success: false, error: 'Not found' });
+      expect(results[2]).toEqual({ id: 'msg3', success: true });
+    });
+  });
+
+  describe('Archive Emails Logic', () => {
+    it('should archive email by removing INBOX label', async () => {
+      const mockGmail = {
+        users: {
+          messages: {
+            modify: vi.fn().mockResolvedValue({ data: { id: 'msg123', labelIds: ['CATEGORY_UPDATES'] } })
+          }
+        }
+      };
+
+      const messageIds = ['msg123'];
+      const results = [];
+
+      for (const id of messageIds) {
+        try {
+          await mockGmail.users.messages.modify({
+            userId: 'me',
+            id: id,
+            requestBody: { removeLabelIds: ['INBOX'] }
+          });
+          results.push({ id, success: true });
+        } catch (err) {
+          results.push({ id, success: false, error: err.message });
+        }
+      }
+
+      expect(results).toHaveLength(1);
+      expect(results[0].success).toBe(true);
+      expect(mockGmail.users.messages.modify).toHaveBeenCalledWith({
+        userId: 'me',
+        id: 'msg123',
+        requestBody: { removeLabelIds: ['INBOX'] }
+      });
+    });
+
+    it('should handle errors during archive', async () => {
+      const mockGmail = {
+        users: {
+          messages: {
+            modify: vi.fn().mockRejectedValue(new Error('Rate limit exceeded'))
+          }
+        }
+      };
+
+      const messageIds = ['msg123'];
+      const results = [];
+
+      for (const id of messageIds) {
+        try {
+          await mockGmail.users.messages.modify({
+            userId: 'me',
+            id: id,
+            requestBody: { removeLabelIds: ['INBOX'] }
+          });
+          results.push({ id, success: true });
+        } catch (err) {
+          results.push({ id, success: false, error: err.message });
+        }
+      }
+
+      expect(results).toHaveLength(1);
+      expect(results[0].success).toBe(false);
+      expect(results[0].error).toBe('Rate limit exceeded');
+    });
+
+    it('should handle multiple message IDs for archive', async () => {
+      const mockModify = vi.fn()
+        .mockResolvedValueOnce({ data: { id: 'msg1' } })
+        .mockResolvedValueOnce({ data: { id: 'msg2' } });
+
+      const mockGmail = {
+        users: { messages: { modify: mockModify } }
+      };
+
+      const messageIds = ['msg1', 'msg2'];
+      const results = [];
+
+      for (const id of messageIds) {
+        try {
+          await mockGmail.users.messages.modify({
+            userId: 'me',
+            id: id,
+            requestBody: { removeLabelIds: ['INBOX'] }
+          });
+          results.push({ id, success: true });
+        } catch (err) {
+          results.push({ id, success: false, error: err.message });
+        }
+      }
+
+      expect(results).toHaveLength(2);
+      expect(results[0]).toEqual({ id: 'msg1', success: true });
+      expect(results[1]).toEqual({ id: 'msg2', success: true });
+      expect(mockModify).toHaveBeenCalledTimes(2);
+    });
+  });
 });