mutt-config-core

Pure configuration generator for Neomutt + Gmail + OAuth2.0

Features

• ✅ Zero dependencies - Pure JavaScript, no external packages
• ✅ Pure functions - No side effects, easy to test
• ✅ Fully tested - 24 test cases, 100% coverage
• ✅ Type-safe - JSDoc type definitions included
• ✅ i18n support - Japanese and English Gmail folders
• ✅ GPG ready - Pre-configured for GPG encryption

Installation

npm install mutt-config-core

Quick Start

const { generateMuttConfigs } = require('mutt-config-core');

const configs = generateMuttConfigs({
  email: '[email protected]',
  realName: 'Your Name',
  editor: 'nvim',
  locale: 'ja'  // or 'en'
});

console.log(configs.accountMuttrc);  // Account-specific config
console.log(configs.mainMuttrc);     // Main muttrc
console.log(configs.setupGuide);     // Next steps guide

API Reference

generateMuttConfigs(input)

Generates all necessary Neomutt configuration files for Gmail with OAuth2.0.

Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | email | string | Yes | Gmail address (must end with @gmail.com) | | realName | string | Yes | Your real name for email headers | | editor | string | Yes | Editor command (e.g., 'nvim', 'vim', 'emacs') | | locale | 'ja' \| 'en' | Yes | Gmail language setting | | gpgKeyId | string | No | GPG key ID (defaults to email address) |

Returns

{
  accountMuttrc: string,  // Account-specific configuration
  mainMuttrc: string,     // Main muttrc file
  setupGuide: string      // Step-by-step setup instructions
}

Example

const configs = generateMuttConfigs({
  email: '[email protected]',
  realName: 'John Doe',
  editor: 'nvim',
  locale: 'en',
  gpgKeyId: '[email protected]'  // optional
});

getConfigPaths(email)

Returns recommended file paths for configuration files.

Parameters

• email (string): Gmail address

Returns

{
  accountMuttrc: '.config/mutt/accounts/EMAIL.muttrc',
  mainMuttrc: '.config/mutt/muttrc',
  oauthTokens: '.local/etc/oauth-tokens',
  cacheHeaders: '.cache/mutt/headers',
  cacheBodies: '.cache/mutt/bodies'
}

GMAIL_FOLDERS

Gmail folder names for different locales.

{
  ja: {
    drafts: '下書き',
    sent: '送信済みメール',
    trash: 'ゴミ箱',
    allMail: 'すべてのメール'
  },
  en: {
    drafts: 'Drafts',
    sent: 'Sent Mail',
    trash: 'Trash',
    allMail: 'All Mail'
  }
}

Generated Configuration

The generated configuration includes:

• OAuth 2.0 authentication - Uses GPG-encrypted tokens
• IMAP/SMTP settings - Optimized for Gmail
• Performance settings - Caching and connection keepalive
• Folder macros - Quick navigation with gi, gt, gs, gd, ga
• Locale-specific folders - Correct folder names for Japanese/English

Prerequisites

Before using the generated configuration, ensure you have:

• Neomutt installed
• mutt-wizard installed
• Python 3 with mutt_oauth2.py
• GPG configured
• Google Cloud OAuth 2.0 credentials

See the generated setupGuide for detailed instructions.

Use Cases

CLI Tool

Perfect for building command-line setup tools:

const inquirer = require('inquirer');
const fs = require('fs').promises;
const { generateMuttConfigs, getConfigPaths } = require('mutt-config-core');

const answers = await inquirer.prompt([...]);
const configs = generateMuttConfigs(answers);
const paths = getConfigPaths(answers.email);

// Write configs to disk
await fs.writeFile(paths.accountMuttrc, configs.accountMuttrc);

Web Service

Generate configurations on-demand:

app.post('/generate-config', (req, res) => {
  const configs = generateMuttConfigs(req.body);
  res.json(configs);
});

Testing

Easy to test due to pure functions:

test('generates valid config', () => {
  const result = generateMuttConfigs({
    email: '[email protected]',
    realName: 'Test User',
    editor: 'vim',
    locale: 'en'
  });
  
  expect(result.accountMuttrc).toContain('[email protected]');
});

Development

# Install dependencies
npm install

# Run tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

Related Projects

• mutt-wizard - Script for easy Neomutt setup
• neomutt - Command line email client

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © a-lost-social-misfit

Author

Created by a-lost-social-misfit

Based on practical experience setting up Neomutt with Gmail OAuth2.0 on macOS.

Acknowledgments

• Inspired by the mutt-wizard project
• OAuth2 implementation based on mutt_oauth2.py

Returns:

• accountMuttrc (string): Account-specific configuration
• mainMuttrc (string): Main muttrc file
• setupGuide (string): Next steps guide

getConfigPaths(email)

Returns file paths for configuration files.

GMAIL_FOLDERS

Gmail folder names for different locales.

Development

# Run tests
npm test

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage

License

MIT