Actual-sync CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Actual-sync is a self-hosted Node.js service that automates bank transaction synchronization for Actual Budget servers. It supports multiple budget instances, encrypted budgets, scheduling, multi-channel notifications, and a web dashboard with Prometheus metrics.

Commands

# Install git hooks (run once after cloning — also runs automatically via npm install)
git config core.hooksPath .githooks
# This installs a pre-push hook that runs npm test --coverage --ci before every push.

# Run all tests
npm test

# Run a single test file
npm test -- configLoader.test.js

# Run tests matching a name pattern
npm test -- --testNamePattern="should validate configuration"

# Watch mode for a specific file
npm run test:watch -- syncService.test.js

# Generate coverage report
npm run test:coverage

# Check for dead code (unused files/exports) with knip
npm run dead:check     # blocking (exit 1 on findings); CI runs this in the lint job
npm run knip           # report-only (always exit 0); for local diffing

# Report config that is written here but NOT YET IN EFFECT, because GitHub reads
# it only from the default branch (#204). Report-only, always exits 0.
# CI runs this in the lint job too (#211), so this is a convenience.
npm run drift:check

# Mutation testing — the verification bar here. Reintroduces each shipped
# defect one at a time and asserts the suite FAILS. Not in CI (it runs the
# whole suite once per mutation); run it before a release and after any
# change the catalog covers.
npm run test:mutation                       # all of them, full suite each
npm run test:mutation -- --fast             # only each mutation's hinted test file
npm run test:mutation -- --ticket '#177'    # one ticket's mutations
npm run test:mutation -- --list             # what is covered, without running anything
npm run test:mutation -- --recover          # restore a file after a hard kill

# Start the scheduled sync service
npm start

# Force immediate sync (all servers)
npm run sync

# Sync a specific server
npm run sync -- --server "ServerName"

# Validate config against schema
npm run validate-config

# List discovered bank accounts
npm run list-accounts

# View sync history
npm run history

# Regenerate docs/screenshots/* (Puppeteer, dev-only) and README metric badges
npm run screenshots
npm run badges:generate

# Bump version (updates VERSION + package.json + package-lock.json in sync;
# aborts if local version is behind the latest released tag). For a patch
# release you do not need this (the auto-release patch-bumps). Run it on
# `development` only to cut a MINOR or MAJOR release, which the auto-release
# then publishes as-is (see Git Workflow).
npm run version:bump -- minor   # or: patch / major