inboxd 1.3.1 → 1.4.0

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

@@ -106,6 +106,69 @@ Unless the user says "inbox zero" or similar:
 
 ---
 
+## User Preferences
+
+- At the start of every session, read `~/.config/inboxd/user-preferences.md` and apply the rules to all triage/cleanup decisions.
+- The file is natural-language markdown. Keep it under 500 lines so it fits in context.
+- Manage it with `inboxd preferences` (view, init, edit, validate, JSON).
+
+### First-Time Onboarding (when file is missing)
+Offer to set up preferences once:
+1) People to **never auto-delete**
+2) Senders to **always clean up** (promotions, alerts)
+3) Specific workflows (e.g., summarize newsletters)
+4) Cleanup aggressiveness (conservative / moderate / aggressive)
+Save answers to `~/.config/inboxd/user-preferences.md`.
+
+### Tracking Onboarding
+
+After completing onboarding (or if user declines), add this marker to the end of the preferences file:
+
+```markdown
+<!-- Internal: Onboarding completed -->
+```
+
+**Before offering onboarding**, check if this marker exists. If it does, do NOT offer onboarding again—even if the file only contains template placeholders. This prevents annoying users who dismissed the initial prompt.
+
+### Learning from Feedback
+- **Auto-save explicit requests:** "Always delete LinkedIn alerts", "Never touch mom@family.com", "I prefer brief summaries".
+- **Confirm pattern suggestions:** "You keep deleting promo@site.com. Save a rule to clean these up?" Only suggest if the sender is active.
+- Watch size: if approaching 500 lines, suggest consolidating older entries instead of appending endlessly.
+
+### Preference File Format
+- Sections: `## About Me`, `## Important People`, `## Sender Behaviors`, `## Category Rules`, `## Behavioral Preferences`.
+- When updating, **append to existing sections** (bullets), don't overwrite user content. Include brief context ("why") to help future decisions.
+- Never delete the file; it lives outside the skill install path and must survive updates.
+
+### Smart Pattern Detection Window
+When suggesting new preferences from behavior:
+1) Only consider deletions from the last 14 days.
+2) Confirm the sender is still active (recent unread emails).
+3) Require 3+ deletions within the window.
+4) Skip if the sender already exists in preferences.
+
+### Reading the Deletion Log
+
+The deletion log is at `~/.config/inboxd/deletion-log.json`. Each entry:
+
+```json
+{
+  "deletedAt": "2026-01-08T10:00:00.000Z",
+  "account": "personal",
+  "id": "abc123",
+  "from": "sender@example.com",
+  "subject": "Email subject",
+  "labelIds": ["UNREAD", "INBOX"]
+}
+```
+
+Use `inboxd cleanup-suggest --json` for pre-analyzed patterns (recommended), or read the raw log with:
+```bash
+cat ~/.config/inboxd/deletion-log.json
+```
+
+---
+
 ## Heavy Inbox Strategy
 
 When a user has a heavy inbox (>20 unread emails), use this optimized workflow:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inboxd",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "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,15 +1,18 @@
 #!/usr/bin/env node
 
 const { program } = require('commander');
+const fs = require('fs');
 const { getUnreadEmails, getEmailCount, trashEmails, getEmailById, untrashEmails, markAsRead, markAsUnread, archiveEmails, unarchiveEmails, groupEmailsBySender, getEmailContent, searchEmails, searchEmailsCount, searchEmailsPaginated, sendEmail, replyToEmail, extractLinks } = require('./gmail-monitor');
 const { logArchives, getRecentArchives, getArchiveLogPath, removeArchiveLogEntries } = require('./archive-log');
 const { authorize, addAccount, getAccounts, getAccountEmail, removeAccount, removeAllAccounts, renameTokenFile, validateCredentialsFile, hasCredentials, isConfigured, installCredentials } = require('./gmail-auth');
 const { logDeletions, getRecentDeletions, getLogPath, readLog, removeLogEntries, getStats: getDeletionStats, analyzePatterns } = require('./deletion-log');
 const { getSkillStatus, checkForUpdate, installSkill, SKILL_DEST_DIR, SOURCE_MARKER } = require('./skill-installer');
 const { logSentEmail, getSentLogPath, getSentStats } = require('./sent-log');
+const { getPreferencesPath, preferencesExist, readPreferences, writePreferences, validatePreferences, getTemplatePath } = require('./preferences');
 const readline = require('readline');
 const path = require('path');
 const os = require('os');
+const { spawnSync } = require('child_process');
 const pkg = require('../package.json');
 
 /**
@@ -1823,6 +1826,129 @@ async function main() {
       }
     });
 
+  program
+    .command('preferences')
+    .description('View and manage inbox preferences used by the AI assistant')
+    .option('--init', 'Create preferences file from template if missing')
+    .option('--edit', 'Open preferences file in $EDITOR (creates if missing)')
+    .option('--validate', 'Validate preferences format and line count')
+    .option('--json', 'Output preferences and validation as JSON')
+    .action(async (options) => {
+      try {
+        const prefPath = getPreferencesPath();
+        const templatePath = getTemplatePath();
+        const templateContent = fs.existsSync(templatePath)
+          ? fs.readFileSync(templatePath, 'utf8')
+          : '# Inbox Preferences\n';
+        let createdDuringRun = false;
+
+        const ensurePreferencesFile = () => {
+          if (!preferencesExist()) {
+            writePreferences(templateContent);
+            createdDuringRun = true;
+          }
+        };
+
+        // Handle init (create if missing)
+        if (options.init) {
+          ensurePreferencesFile();
+          if (!options.json) {
+            if (createdDuringRun) {
+              console.log(chalk.green('\n✓ Preferences file created from template.'));
+              console.log(chalk.gray(`  Path: ${prefPath}\n`));
+            } else {
+              console.log(chalk.yellow('\nPreferences file already exists.'));
+              console.log(chalk.gray(`  Path: ${prefPath}\n`));
+            }
+          }
+        }
+
+        // Handle edit (open editor)
+        if (options.edit) {
+          ensurePreferencesFile();
+          const editor = process.env.EDITOR || (process.platform === 'win32' ? 'notepad' : 'nano');
+          if (!options.json) {
+            console.log(chalk.gray(`Opening ${prefPath} with ${editor}...\n`));
+          }
+          const result = spawnSync(editor, [prefPath], { stdio: 'inherit' });
+          if (result.error) {
+            console.log(chalk.red(`Failed to open editor "${editor}": ${result.error.message}`));
+          }
+          return;
+        }
+
+        const exists = preferencesExist();
+        const content = exists ? readPreferences() : null;
+        const validation = validatePreferences(content);
+
+        if (options.json) {
+          console.log(JSON.stringify({
+            path: prefPath,
+            exists,
+            created: createdDuringRun,
+            lineCount: validation.lineCount,
+            valid: validation.valid,
+            errors: validation.errors,
+            warnings: validation.warnings,
+            content: content || '',
+          }, null, 2));
+          return;
+        }
+
+        if (options.validate) {
+          if (!exists) {
+            console.log(chalk.red('\nPreferences file not found.'));
+            console.log(chalk.gray('Create one with: inboxd preferences --init\n'));
+            return;
+          }
+
+          if (validation.valid) {
+            console.log(chalk.green('\n✓ Preferences file is valid.'));
+          } else {
+            console.log(chalk.red('\nPreferences file has issues:'));
+          }
+          console.log(chalk.gray(`  Path: ${prefPath}`));
+          console.log(chalk.gray(`  Lines: ${validation.lineCount}`));
+
+          if (validation.errors.length > 0) {
+            console.log(chalk.red('\nErrors:'));
+            validation.errors.forEach(err => console.log(chalk.red(`  - ${err}`)));
+          }
+          if (validation.warnings.length > 0) {
+            console.log(chalk.yellow('\nWarnings:'));
+            validation.warnings.forEach(warn => console.log(chalk.yellow(`  - ${warn}`)));
+          }
+          console.log('');
+          return;
+        }
+
+        // Default: display preferences or hint to init
+        if (!exists) {
+          console.log(chalk.yellow('\nNo preferences file found.'));
+          console.log(chalk.gray('Create one with: inboxd preferences --init'));
+          console.log(chalk.gray('Then edit with: inboxd preferences --edit\n'));
+          return;
+        }
+
+        if (validation.lineCount > 500) {
+          console.log(chalk.red(`\nPreferences file is too long (${validation.lineCount} lines). Please shorten below 500 lines.\n`));
+          return;
+        }
+
+        console.log(chalk.bold('\nInbox Preferences\n'));
+        console.log(content);
+        console.log(chalk.gray(`\nPath: ${prefPath}`));
+        console.log(chalk.gray(`Lines: ${validation.lineCount}\n`));
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red('Error managing preferences:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
+
   program
     .command('install-skill')
     .description('Install Claude Code skill for AI-powered inbox management')

package/src/preferences.js

@@ -0,0 +1,202 @@
+const fs = require('fs');
+const path = require('path');
+const { atomicWriteSync } = require('./utils');
+const { TOKEN_DIR } = require('./gmail-auth');
+
+const TEMPLATE_PATH = path.join(__dirname, 'templates', 'user-preferences-template.md');
+
+/**
+ * Returns the path to the user preferences file
+ * @returns {string}
+ */
+function getPreferencesPath() {
+  return path.join(TOKEN_DIR, 'user-preferences.md');
+}
+
+/**
+ * Ensures the config directory exists
+ */
+function ensureConfigDir() {
+  fs.mkdirSync(TOKEN_DIR, { recursive: true });
+}
+
+/**
+ * Checks if the preferences file exists
+ * @returns {boolean}
+ */
+function preferencesExist() {
+  return fs.existsSync(getPreferencesPath());
+}
+
+/**
+ * Reads preferences file contents
+ * @returns {string|null} File content or null if missing
+ */
+function readPreferences() {
+  if (!preferencesExist()) {
+    return null;
+  }
+  try {
+    return fs.readFileSync(getPreferencesPath(), 'utf8');
+  } catch (_err) {
+    return null;
+  }
+}
+
+/**
+ * Returns the line count of the current preferences file (or provided content)
+ * @param {string|null} content - Optional content to count lines from
+ * @returns {number}
+ */
+function getLineCount(content = null) {
+  const text = content !== null ? content : readPreferences();
+  if (!text) return 0;
+  return text.split(/\r?\n/).length;
+}
+
+/**
+ * Writes preferences to disk, creating a backup if the file already exists
+ * @param {string} content - Content to write
+ * @returns {{ path: string, backupPath: string|null }}
+ */
+function writePreferences(content) {
+  ensureConfigDir();
+  const prefPath = getPreferencesPath();
+  let backupPath = null;
+
+  if (fs.existsSync(prefPath)) {
+    backupPath = `${prefPath}.backup`;
+    try {
+      fs.copyFileSync(prefPath, backupPath);
+    } catch (_err) {
+      // If backup fails, better to abort than risk data loss
+      throw new Error(`Failed to create backup at ${backupPath}`);
+    }
+  }
+
+  atomicWriteSync(prefPath, content);
+  return { path: prefPath, backupPath };
+}
+
+/**
+ * Validates preferences content for basic safety rules
+ * @param {string|null} content - Content to validate (reads current file if null)
+ * @returns {{ valid: boolean, errors: string[], warnings: string[], lineCount: number }}
+ */
+function validatePreferences(content = null) {
+  const text = content !== null ? content : readPreferences();
+
+  if (!text) {
+    return {
+      valid: false,
+      errors: ['Preferences file not found or empty'],
+      warnings: [],
+      lineCount: 0,
+    };
+  }
+
+  const errors = [];
+  const warnings = [];
+  const lineCount = getLineCount(text);
+
+  if (lineCount > 500) {
+    errors.push(`Preferences exceed 500 lines (currently ${lineCount}). Consider consolidating rules.`);
+  }
+
+  const requiredSections = [
+    '## About Me',
+    '## Important People',
+    '## Sender Behaviors',
+    '## Category Rules',
+    '## Behavioral Preferences',
+  ];
+  const missingSections = requiredSections.filter(section => !text.toLowerCase().includes(section.toLowerCase()));
+  if (missingSections.length > 0) {
+    warnings.push(`Missing sections: ${missingSections.join(', ')}`);
+  }
+
+  if (!text.trimStart().toLowerCase().startsWith('# inbox preferences')) {
+    warnings.push('Missing top-level heading "# Inbox Preferences"');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    lineCount,
+  };
+}
+
+/**
+ * Appends content to a specific section, creating it if missing
+ * @param {string} sectionTitle - Section heading without hashes (e.g., "Important People (Never Auto-Delete)")
+ * @param {string} entry - Entry to append (bullet text)
+ * @returns {{ path: string, backupPath: string|null, createdSection: boolean }}
+ */
+function appendToSection(sectionTitle, entry) {
+  const prefPath = getPreferencesPath();
+  ensureConfigDir();
+
+  let content = readPreferences();
+  if (!content) {
+    content = fs.existsSync(TEMPLATE_PATH)
+      ? fs.readFileSync(TEMPLATE_PATH, 'utf8')
+      : `# Inbox Preferences\n\n## ${sectionTitle}\n`;
+  }
+
+  const lines = content.split(/\r?\n/);
+  const normalized = sectionTitle.trim().toLowerCase();
+  const sectionHeader = `## ${sectionTitle}`;
+
+  let sectionIndex = lines.findIndex(line => line.trim().toLowerCase() === `## ${normalized}`);
+  let createdSection = false;
+
+  if (sectionIndex === -1) {
+    // Append new section at end
+    if (lines[lines.length - 1].trim() !== '') {
+      lines.push('');
+    }
+    lines.push(sectionHeader, `- ${entry}`);
+    createdSection = true;
+  } else {
+    // Find insertion point (before next header or end of file)
+    let insertIndex = lines.length;
+    for (let i = sectionIndex + 1; i < lines.length; i++) {
+      if (lines[i].startsWith('#')) {
+        insertIndex = i;
+        break;
+      }
+    }
+
+    // Ensure a blank line before the append if needed
+    if (lines[insertIndex - 1] && lines[insertIndex - 1].trim() !== '') {
+      lines.splice(insertIndex, 0, '');
+      insertIndex++;
+    }
+
+    const bullet = entry.trim().startsWith('-') ? entry.trim() : `- ${entry.trim()}`;
+    lines.splice(insertIndex, 0, bullet);
+  }
+
+  const { backupPath } = writePreferences(lines.join('\n'));
+  return { path: prefPath, backupPath, createdSection };
+}
+
+/**
+ * Returns the template path (useful for CLI to bootstrap)
+ * @returns {string}
+ */
+function getTemplatePath() {
+  return TEMPLATE_PATH;
+}
+
+module.exports = {
+  getPreferencesPath,
+  preferencesExist,
+  readPreferences,
+  writePreferences,
+  validatePreferences,
+  appendToSection,
+  getLineCount,
+  getTemplatePath,
+};

package/src/skill-installer.js

@@ -6,6 +6,7 @@
  * - Source marker: Only manages skills with `source: inboxd` in front matter
  * - Content hash: Detects changes without version numbers
  * - Backup: Creates .backup before replacing modified files
+ * - Never touches user config files (tokens, preferences) under ~/.config/inboxd
  */
 
 const fs = require('fs');

package/src/templates/user-preferences-template.md

@@ -0,0 +1,40 @@
+# Inbox Preferences
+
+<!--
+This file stores your inbox preferences. The AI assistant reads this
+at the start of each session to personalize how it manages your email.
+Keep it under 500 lines. Edit with: inboxd preferences --edit
+-->
+
+## About Me
+<!-- Describe your context: job role, interests, what emails matter to you -->
+<!-- Example entries (delete these and add your own): -->
+- Software engineer interested in AI/ML opportunities
+- Based in London, prefer remote-friendly roles
+- Active on GitHub, receive many notifications
+
+## Important People (Never Auto-Delete)
+<!-- Senders whose emails should NEVER be suggested for deletion -->
+<!-- Example: -->
+- partner@gmail.com - spouse, always important
+- hr@company.com - work-related
+
+## Sender Behaviors
+<!-- Rules for specific senders or domains -->
+<!-- Examples: -->
+- **LinkedIn job alerts** - When there are multiple, summarize the best matches for my profile and suggest deleting the rest
+- **GitHub notifications** - Keep PRs I'm tagged on, archive others after reading
+
+## Category Rules
+<!-- Rules for types of emails -->
+<!-- Examples: -->
+- Bank/Financial emails - Archive after viewing, never delete
+- Promotional emails older than 14 days - Can be auto-suggested for cleanup
+- Newsletters I haven't read in 30 days - Suggest unsubscribing
+
+## Behavioral Preferences
+<!-- How you want the AI to behave -->
+<!-- Examples: -->
+- I prefer brief summaries (2-3 sentences)
+- Always ask before deleting more than 10 emails at once
+- On busy days (>50 unread), prioritize action-required emails

package/tests/preferences.test.js

@@ -0,0 +1,78 @@
+import { describe, it, expect, beforeEach, afterAll, vi } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+describe('preferences module', () => {
+  const tempDir = path.join(os.tmpdir(), 'inboxd-preferences-test');
+  const originalTokenDir = process.env.INBOXD_TOKEN_DIR;
+  let getPreferencesPath;
+  let preferencesExist;
+  let readPreferences;
+  let writePreferences;
+  let validatePreferences;
+  let appendToSection;
+
+  beforeEach(async () => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+    fs.mkdirSync(tempDir, { recursive: true });
+
+    vi.resetModules();
+    process.env.INBOXD_TOKEN_DIR = tempDir;
+
+    const module = await import('../src/preferences');
+    getPreferencesPath = module.getPreferencesPath;
+    preferencesExist = module.preferencesExist;
+    readPreferences = module.readPreferences;
+    writePreferences = module.writePreferences;
+    validatePreferences = module.validatePreferences;
+    appendToSection = module.appendToSection;
+  });
+
+  afterAll(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+    if (originalTokenDir === undefined) {
+      delete process.env.INBOXD_TOKEN_DIR;
+    } else {
+      process.env.INBOXD_TOKEN_DIR = originalTokenDir;
+    }
+  });
+
+  it('uses INBOXD_TOKEN_DIR for preference path', () => {
+    expect(getPreferencesPath()).toBe(path.join(tempDir, 'user-preferences.md'));
+  });
+
+  it('writes preferences and creates a backup on overwrite', () => {
+    const initial = '# Inbox Preferences\nInitial content\n';
+    writePreferences(initial);
+    expect(preferencesExist()).toBe(true);
+
+    const updated = '# Inbox Preferences\nUpdated content\n';
+    writePreferences(updated);
+
+    const backupPath = `${getPreferencesPath()}.backup`;
+    expect(fs.existsSync(backupPath)).toBe(true);
+    const backupContent = fs.readFileSync(backupPath, 'utf8');
+    expect(backupContent).toContain('Initial content');
+
+    const current = readPreferences();
+    expect(current).toContain('Updated content');
+  });
+
+  it('flags files over 500 lines', () => {
+    const oversized = '# Inbox Preferences\n' + 'line\n'.repeat(501);
+    const result = validatePreferences(oversized);
+
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('500'))).toBe(true);
+  });
+
+  it('appends to existing sections using the template when missing', () => {
+    const result = appendToSection('Important People (Never Auto-Delete)', 'test@example.com - never delete');
+    const content = readPreferences();
+
+    expect(result.createdSection).toBe(false);
+    expect(content).toContain('## Important People');
+    expect(content).toContain('test@example.com');
+  });
+});