NOTEPLAN PLUGINS DEVELOPMENT GUIDE

# NOTEPLAN PLUGINS DEVELOPMENT GUIDE

## Build/Test Commands
- Build plugin: `npm run build <plugin-name>` or `npm run build:minified`
- Lint code: `npm run lint` or fix issues with `npm run lint-fix`
- Type check: `npm run typecheck`
- Run a test: `jest <test-file> --no-watch`

## Code Style Guidelines
- Use Flow for static typing
- No semicolons (enforced by ESLint/Prettier)
- Single quotes for strings
- Max line length: 180 characters
- Use template literals instead of string concatenation
- Use ES6+ features (const/let, arrow functions)
- Use async/await and handle promises properly (no floating promises)
- Follow existing naming patterns in the codebase
- Proper error handling with try/catch blocks
- Follow import order: external libs -> internal libs -> local files
- Keep code DRY and modular with clear function responsibilities
- Use JSDoc comments for public functions

## Common Helper Functions
The most frequently used functions in the codebase are:
- Logging: logDebug, logError, clo, logInfo, logWarn
- Note utilities: findNote, getParagraphs, getSelectedParagraphs, getTasksFromNote
- Date handling: getTodaysDateHyphenated, getDateStringFromCalendarFilename
- Configuration: getSettings, updateSettingsForPlugin
- UI interaction: showMessage, showMessageYesNo, displayTitle

When developing, check the helpers/ directory for existing utility functions before writing your own.

For JS/TS, please provide Flow (as appropriate) and JSDOC with all responses. If you are rewriting a full file, make sure to include all import statements also. Do not remove any console.logs or comments (or logDebug, clo, logInfo, logError statements).

**DO NOT EVER HARD-CODE JEST WORKAROUNDS INTO FUNCTIONS WE ARE TESTING**
When you run jest tests, always include the flag --no-watch at the end because my jest config by default watches

## Viewing Plugin Logs

Use `nplog` in `scripts/nplog/` to read NotePlan's plugin log; do not grep the raw log
file (`^JSLog:` and `| ERROR |` both silently match nothing, and the leading timestamp is
the flush time). `node scripts/nplog/nplog --json` emits NDJSON and exits 1 on errors.
See `scripts/nplog/README.md`.