[AI] Add option to 'Copy [budget] to future months' (#7420)

* [AI] Add 'Copy to future months' budget option

Adds a new per-category budget menu option that copies the current
month's budgeted amount to all future months that already exist in
the budget. Works for both envelope and tracking budget types, and
on both desktop (inline popover) and mobile (modal) views.

* [AI] Rename release note to PR #7420

* [AI] Skip empty budget months in copyToFutureMonths

Only copy the budget value to future months that already have a
non-zero budget set for the category. Months with no budget (zero)
are left untouched.

* [AI] Rename to 'Copy until year end', limit to tracking budget, add year-end cap

* [AI] Address CodeRabbit feedback: i18n undo notification, clarify docs

* [AI] Fix typecheck: branch dispatch by budgetType for proper modal narrowing

* [AI] Fix lint: add t to useCallback deps

.coderabbit.yaml

@@ -1,6 +1,6 @@
 issue_enrichment:
   auto_enrich:
-    enabled: false
+    enabled: true
 reviews:
   request_changes_workflow: true
   review_status: false

.dockerignore

@@ -1,8 +1,6 @@
-node_modules
-user-files
-server-files
-
-# Yarn
+**/node_modules
+.git
+.lage
 .pnp.*
 .yarn/*
 !.yarn/patches

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,4 +1,4 @@
-<!-- Thank you for submitting a pull request! Make sure to follow the instructions to write release notes for your PR — it should only take a minute or two: https://github.com/actualbudget/docs#writing-good-release-notes. Try running yarn generate:release-notes *before* pushing your PR for an interactive experience. -->
+<!-- Thank you for submitting a pull request! Make sure to follow the instructions to write release notes for your PR — it should only take a minute or two: https://actualbudget.org/docs/contributing/#writing-good-release-notes. Try running yarn generate:release-notes *before* pushing your PR for an interactive experience. -->
 
 ## Description
 

.github/actions/ai-generated-release-notes/create-release-notes-file.js

@@ -16,14 +16,19 @@ if (!token || !repo || !issueNumber || !summaryDataJson || !category) {
 const [owner, repoName] = repo.split('/');
 const octokit = new Octokit({ auth: token });
 
+const VALID_CATEGORIES = [
+  'Features',
+  'Bugfixes',
+  'Enhancements',
+  'Maintenance',
+];
+const GITHUB_USERNAME_RE =
+  /^[a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9])){0,38}$/;
+
 async function createReleaseNotesFile() {
   try {
     const summaryData = JSON.parse(summaryDataJson);
 
-    console.log('Debug - Category value:', category);
-    console.log('Debug - Category type:', typeof category);
-    console.log('Debug - Category JSON stringified:', JSON.stringify(category));
-
     if (!summaryData) {
       console.log('No summary data available, cannot create file');
       return;
@@ -34,26 +39,62 @@ async function createReleaseNotesFile() {
       return;
     }
 
-    // Create file content - ensure category is not quoted
+    // Normalize category - strip surrounding quotes and validate against allow-list
     const cleanCategory =
       typeof category === 'string'
         ? category.replace(/^["']|["']$/g, '')
         : category;
-    console.log('Debug - Clean category:', cleanCategory);
+
+    if (!VALID_CATEGORIES.includes(cleanCategory)) {
+      console.log(
+        `Invalid category "${cleanCategory}". Must be one of: ${VALID_CATEGORIES.join(', ')}`,
+      );
+      return;
+    }
+
+    // Validate author is a plausible GitHub username
+    const author = String(summaryData.author || '');
+    if (!GITHUB_USERNAME_RE.test(author)) {
+      console.log(
+        `Invalid author "${author}", aborting release notes creation`,
+      );
+      return;
+    }
+
+    // Normalize summary: collapse whitespace to a single line so it cannot
+    // introduce extra YAML frontmatter or break the markdown structure.
+    const cleanSummary = String(summaryData.summary || '')
+      .replace(/\s+/g, ' ')
+      .trim();
+    if (!cleanSummary) {
+      console.log('Empty summary, aborting release notes creation');
+      return;
+    }
+
+    // Validate PR number - must be a positive integer. The value comes from
+    // the GitHub API, but we harden it because it's used to build a file path
+    // and a commit message.
+    const validatedPrNumber = Number(summaryData.prNumber);
+    if (!Number.isInteger(validatedPrNumber) || validatedPrNumber <= 0) {
+      console.log(
+        `Invalid PR number "${summaryData.prNumber}", aborting release notes creation`,
+      );
+      return;
+    }
 
     const fileContent = `---
 category: ${cleanCategory}
-authors: [${summaryData.author}]
+authors: [${author}]
 ---
 
-${summaryData.summary}
+${cleanSummary}
 `;
 
-    const fileName = `upcoming-release-notes/${summaryData.prNumber}.md`;
+    const fileName = `upcoming-release-notes/${validatedPrNumber}.md`;
 
-    console.log(`Creating release notes file: ${fileName}`);
-    console.log('File content:');
-    console.log(fileContent);
+    console.log(
+      `Creating release notes file: ${fileName} (category: ${cleanCategory}, author: ${author})`,
+    );
 
     // Get PR info
     const { data: pr } = await octokit.rest.pulls.get({
@@ -75,7 +116,7 @@ ${summaryData.summary}
       owner: headOwner,
       repo: headRepo,
       path: fileName,
-      message: `Add release notes for PR #${summaryData.prNumber}`,
+      message: `Add release notes for PR #${validatedPrNumber}`,
       content: Buffer.from(fileContent).toString('base64'),
       branch: prBranch,
       committer: {

.github/actions/ai-generated-release-notes/generate-summary.js

@@ -25,8 +25,6 @@ try {
     process.exit(0);
   }
 
-  console.log('CodeRabbit comment body:', commentBody);
-
   const data = JSON.stringify({
     model: 'gpt-4o-mini',
     messages: [

.github/actions/ai-generated-release-notes/pr-details.js

@@ -39,6 +39,22 @@ async function getPRDetails() {
     console.log('- Base Branch:', pr.base.ref);
     console.log('- Head Branch:', pr.head.ref);
 
+    // Fetch all changed files to detect docs-only PRs
+    const files = await octokit.paginate(octokit.rest.pulls.listFiles, {
+      owner,
+      repo: repoName,
+      pull_number: issueNumber,
+      per_page: 100,
+    });
+
+    const changedFiles = files.map(f => f.filename);
+    const isDocsOnly =
+      changedFiles.length > 0 &&
+      changedFiles.every(file => file.startsWith('packages/docs/'));
+
+    console.log('- Changed Files:', changedFiles.length);
+    console.log('- Is Docs Only:', isDocsOnly);
+
     const result = {
       number: pr.number,
       author: pr.user.login,
@@ -47,11 +63,31 @@ async function getPRDetails() {
       headBranch: pr.head.ref,
     };
 
+    let eligible = true;
+    if (pr.base.ref !== 'master') {
+      console.log(
+        'PR does not target master branch, skipping release notes generation',
+      );
+      eligible = false;
+    } else if (pr.head.ref.startsWith('release/')) {
+      console.log(
+        'PR head branch is a release branch, skipping release notes generation',
+      );
+      eligible = false;
+    } else if (isDocsOnly) {
+      console.log(
+        'PR only changes documentation, skipping release notes generation',
+      );
+      eligible = false;
+    }
+
     setOutput('result', JSON.stringify(result));
+    setOutput('eligible', JSON.stringify(eligible));
   } catch (error) {
     console.log('Error getting PR details:', error.message);
     console.log('Stack:', error.stack);
     setOutput('result', 'null');
+    setOutput('eligible', 'false');
     process.exit(1);
   }
 }
@@ -60,5 +96,6 @@ getPRDetails().catch(error => {
   console.log('Unhandled error:', error.message);
   console.log('Stack:', error.stack);
   setOutput('result', 'null');
+  setOutput('eligible', 'false');
   process.exit(1);
 });

.github/actions/docs-spelling/excludes.txt

@@ -68,7 +68,6 @@ ignore$
 ^\Qsrc/\E$
 ^\Qstatic/\E$
 ^\Q.github/\E$
-(?:^|/)package(?:-lock|)\.json$
 (?:^|/)yarn\.lock$
 (?:^|/)(?i)docusaurus.config.js
 (?:^|/)(?i)README.md

.github/actions/docs-spelling/expect.txt

@@ -61,6 +61,7 @@ Dockerfiles
 Dominguez
 DUSSDEDDXXX
 DUSSELDORF
+ecf
 EDATE
 ENTERCARD
 Entra
@@ -126,6 +127,7 @@ Moldovan
 murmurhash
 NETWORKDAYS
 nginx
+nodenext
 OIDC
 Okabe
 overbudgeted
@@ -139,8 +141,6 @@ pluggyai
 Poste
 PPABPLPK
 prefs
-Primoco
-Priotecs
 proactively
 Qatari
 QNTOFRP
@@ -171,7 +171,6 @@ SWEDBANK
 SWEDNOKK
 Synology
 systemctl
-tada
 taskbar
 templating
 THB

.github/actions/release-notes/check/action.yml

@@ -9,7 +9,7 @@ runs:
         node-version: 22
     - name: Install dependencies
       shell: bash
-      run: yarn --immutable
+      run: yarn workspaces focus @actual-app/ci-actions
     - name: Check release notes
       env:
         PR_NUMBER: ${{ github.event.pull_request.number }}

.github/actions/release-notes/generate/action.yml

@@ -9,7 +9,7 @@ runs:
         node-version: 22
     - name: Install dependencies
       shell: bash
-      run: yarn --immutable
+      run: yarn workspaces focus actual @actual-app/ci-actions
     - name: Generate release notes
       shell: bash
       env:

.github/actions/setup/action.yml

@@ -52,8 +52,9 @@ runs:
       with:
         repository: actualbudget/translations
         path: ${{ inputs.working-directory }}/packages/desktop-client/locale
-      if: ${{ inputs.download-translations == 'true' }}
+        persist-credentials: false
+      if: ${{ inputs.download-translations == 'true' && !env.ACT }}
     - name: Remove untranslated languages
       run: packages/desktop-client/bin/remove-untranslated-languages
       shell: bash
-      if: ${{ inputs.download-translations == 'true' }}
+      if: ${{ inputs.download-translations == 'true' && !env.ACT }}

.github/workflows/ai-generated-release-notes.yml

@@ -18,6 +18,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
@@ -42,11 +44,7 @@ jobs:
           GITHUB_EVENT_ISSUE_NUMBER: ${{ github.event.issue.number }}
 
       - name: Check if release notes file already exists
-        if: >-
-          steps.check-first-comment.outputs.result == 'true' &&
-          steps.pr-details.outputs.result != 'null' &&
-          fromJSON(steps.pr-details.outputs.result).baseBranch == 'master' &&
-          !startsWith(fromJSON(steps.pr-details.outputs.result).headBranch, 'release/')
+        if: steps.pr-details.outputs.eligible == 'true'
         id: check-release-notes-exists
         run: node .github/actions/ai-generated-release-notes/check-release-notes-exists.js
         env:
@@ -56,7 +54,7 @@ jobs:
           PR_DETAILS: ${{ steps.pr-details.outputs.result }}
 
       - name: Generate summary with OpenAI
-        if: steps.check-first-comment.outputs.result == 'true' && steps.check-release-notes-exists.outputs.result == 'false'
+        if: steps.check-release-notes-exists.outputs.result == 'false'
         id: generate-summary
         run: node .github/actions/ai-generated-release-notes/generate-summary.js
         env:
@@ -65,7 +63,7 @@ jobs:
           PR_DETAILS: ${{ steps.pr-details.outputs.result }}
 
       - name: Determine category with OpenAI
-        if: steps.check-first-comment.outputs.result == 'true' && steps.check-release-notes-exists.outputs.result == 'false' && steps.generate-summary.outputs.result != 'null'
+        if: steps.generate-summary.outputs.result != 'null' && steps.generate-summary.outputs.result != ''
         id: determine-category
         run: node .github/actions/ai-generated-release-notes/determine-category.js
         env:
@@ -75,7 +73,7 @@ jobs:
           SUMMARY_DATA: ${{ steps.generate-summary.outputs.result }}
 
       - name: Create and commit release notes file via GitHub API
-        if: steps.check-first-comment.outputs.result == 'true' && steps.check-release-notes-exists.outputs.result == 'false' && steps.generate-summary.outputs.result != 'null' && steps.determine-category.outputs.result != 'null' && steps.determine-category.outputs.result != ''
+        if: steps.determine-category.outputs.result != 'null' && steps.determine-category.outputs.result != ''
         run: node .github/actions/ai-generated-release-notes/create-release-notes-file.js
         env:
           GITHUB_TOKEN: ${{ secrets.ACTIONS_UPDATE_TOKEN }}
@@ -85,7 +83,7 @@ jobs:
           CATEGORY: ${{ steps.determine-category.outputs.result }}
 
       - name: Comment on PR
-        if: steps.check-first-comment.outputs.result == 'true' && steps.check-release-notes-exists.outputs.result == 'false' && steps.generate-summary.outputs.result != 'null' && steps.determine-category.outputs.result != 'null' && steps.determine-category.outputs.result != ''
+        if: steps.determine-category.outputs.result != 'null' && steps.determine-category.outputs.result != ''
         run: node .github/actions/ai-generated-release-notes/comment-on-pr.js
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/autofix.yml

@@ -16,6 +16,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
         with:

.github/workflows/build.yml

@@ -19,35 +19,54 @@ concurrency:
   cancel-in-progress: ${{ github.ref != 'refs/heads/master' }}
 
 jobs:
+  setup:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Set up environment
+        uses: ./.github/actions/setup
+        with:
+          download-translations: 'false'
+
   api:
+    needs: setup
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
           download-translations: 'false'
       - name: Build API
-        run: cd packages/api && yarn build
+        run: yarn build:api
       - name: Create package tgz
         run: cd packages/api && yarn pack && mv package.tgz actual-api.tgz
       - name: Prepare bundle stats artifact
         run: cp packages/api/app/stats.json api-stats.json
       - name: Upload Build
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: actual-api
           path: packages/api/actual-api.tgz
       - name: Upload API bundle stats
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: api-build-stats
           path: api-stats.json
 
   crdt:
+    needs: setup
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
@@ -56,35 +75,48 @@ jobs:
         run: cd packages/crdt && yarn build
       - name: Create package tgz
         run: cd packages/crdt && yarn pack && mv package.tgz actual-crdt.tgz
+      - name: Prepare bundle stats artifact
+        run: cp packages/crdt/dist/stats.json crdt-stats.json
       - name: Upload Build
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: actual-crdt
           path: packages/crdt/actual-crdt.tgz
+      - name: Upload CRDT bundle stats
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: crdt-build-stats
+          path: crdt-stats.json
 
   web:
+    needs: setup
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
       - name: Build Web
         run: yarn build:browser
       - name: Upload Build
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: actual-web
           path: packages/desktop-client/build
       - name: Upload Build Stats
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: build-stats
           path: packages/desktop-client/build-stats
 
   cli:
+    needs: setup
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
@@ -96,20 +128,23 @@ jobs:
       - name: Prepare bundle stats artifact
         run: cp packages/cli/dist/stats.json cli-stats.json
       - name: Upload Build
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: actual-cli
           path: packages/cli/actual-cli.tgz
       - name: Upload CLI bundle stats
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: cli-build-stats
           path: cli-stats.json
 
   server:
+    needs: setup
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
@@ -117,7 +152,7 @@ jobs:
       - name: Build Server
         run: yarn workspace @actual-app/sync-server build
       - name: Upload Build
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: sync-server
           path: packages/sync-server/build

.github/workflows/check.yml

@@ -12,20 +12,40 @@ concurrency:
   cancel-in-progress: ${{ github.ref != 'refs/heads/master' }}
 
 jobs:
+  setup:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Set up environment
+        uses: ./.github/actions/setup
+        with:
+          download-translations: 'false'
   constraints:
+    needs: setup
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
           download-translations: 'false'
       - name: Check dependency version consistency
         run: yarn constraints
+      - name: Check tsconfig project references are in sync
+        run: yarn check:tsconfig-references
   lint:
+    needs: setup
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
@@ -33,9 +53,12 @@ jobs:
       - name: Lint
         run: yarn lint
   typecheck:
+    needs: setup
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
@@ -43,9 +66,12 @@ jobs:
       - name: Typecheck
         run: yarn typecheck
   validate-cli:
+    needs: setup
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
@@ -55,21 +81,36 @@ jobs:
       - name: Check that the built CLI works
         run: node packages/sync-server/build/bin/actual-server.js --version
   test:
+    needs: setup
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
           download-translations: 'false'
       - name: Test
         run: yarn test
+  check-gh-actions:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: zizmorcore/zizmor-action@71321a20a9ded102f6e9ce5718a2fcec2c4f70d8 # v0.5.2
 
   migrations:
+    needs: setup
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
         with:

.github/workflows/codeql.yml

@@ -23,13 +23,15 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@b1bff81932f5cdfc8695c7752dcee935dcd061c8 # v4.33.0
+        uses: github/codeql-action/init@c10b8064de6f491fea524254123dbe5e09572f13 # v4.35.1
         with:
           languages: javascript
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@b1bff81932f5cdfc8695c7752dcee935dcd061c8 # v4.33.0
+        uses: github/codeql-action/analyze@c10b8064de6f491fea524254123dbe5e09572f13 # v4.35.1
         with:
           category: '/language:javascript'

.github/workflows/count-points.yml

@@ -17,6 +17,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
         with:

.github/workflows/cut-release-branch.yml

@@ -1,6 +1,9 @@
-name: Generate release PR
+name: Cut release branch
 
 on:
+  schedule:
+    # 17:00 UTC on the 25th of each month
+    - cron: '0 17 25 * *'
   workflow_dispatch:
     inputs:
       ref:
@@ -11,22 +14,35 @@ on:
         description: 'Version number for the release (optional)'
         required: false
         default: ''
+      release-date:
+        description: 'Expected release date, YYYY-MM-DD (optional)'
+        required: false
+        default: ''
+
+permissions:
+  contents: write
+  pull-requests: write
 
 jobs:
-  generate-release-pr:
+  cut-release-branch:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
-          ref: ${{ github.event.inputs.ref }}
+          ref: ${{ github.event.inputs.ref || 'master' }}
+          persist-credentials: false
+
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
           download-translations: 'false'
+
       - name: Bump package versions
         id: bump_package_versions
         shell: bash
+        env:
+          INPUT_VERSION: ${{ github.event.inputs.version }}
         run: |
           declare -A packages=(
             [web]="desktop-client"
@@ -36,14 +52,15 @@ jobs:
             [cli]="cli"
             [core]="loot-core"
           )
+          declare -A new_versions
 
           for key in "${!packages[@]}"; do
             pkg="${packages[$key]}"
 
-            if [[ -n "${{ github.event.inputs.version }}" ]]; then
+            if [[ -n "$INPUT_VERSION" ]]; then
               version=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts \
                 --package-json "./packages/$pkg/package.json" \
-                --version "${{ github.event.inputs.version }}" \
+                --version "$INPUT_VERSION" \
                 --update)
             else
               version=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts \
@@ -52,16 +69,33 @@ jobs:
                 --update)
             fi
 
-            eval "NEW_${key^^}_VERSION=\"$version\""
+            new_versions[$key]="$version"
           done
 
-          echo "version=$NEW_WEB_VERSION" >> "$GITHUB_OUTPUT"
-      - name: Create PR
-        uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
+          echo "version=${new_versions[web]}" >> "$GITHUB_OUTPUT"
+
+      - name: Compute release date
+        id: release_date
+        shell: bash
+        env:
+          INPUT_DATE: ${{ github.event.inputs['release-date'] }}
+        run: |
+          if [[ -n "$INPUT_DATE" ]]; then
+            echo "date=$INPUT_DATE" >> "$GITHUB_OUTPUT"
+          else
+            # default to the 1st of next month
+            echo "date=$(date -d '+1 month' '+%Y-%m-01')" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create release branch and PR
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
         with:
           token: ${{ secrets.ACTIONS_UPDATE_TOKEN }}
           commit-message: '🔖 (${{ steps.bump_package_versions.outputs.version }})'
           title: '🔖 (${{ steps.bump_package_versions.outputs.version }})'
-          body: 'Generated by [generate-release-pr.yml](../tree/master/.github/workflows/generate-release-pr.yml)'
-          branch: 'release/v${{ steps.bump_package_versions.outputs.version }}'
+          body: |
+            Generated by [cut-release-branch.yml](../tree/master/.github/workflows/cut-release-branch.yml)
+
+            <!-- release-date:${{ steps.release_date.outputs.date }} -->
+          branch: 'release/${{ steps.bump_package_versions.outputs.version }}'
           base: master

.github/workflows/docker-edge.yml

@@ -37,6 +37,8 @@ jobs:
         os: [ubuntu, alpine]
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0
@@ -54,14 +56,14 @@ jobs:
           tags: ${{ env.TAGS }}
 
       - name: Login to Docker Hub
-        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
         if: github.event_name != 'pull_request' && !github.event.repository.fork
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Login to GitHub Container Registry
-        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
         if: github.event_name != 'pull_request'
         with:
           registry: ghcr.io
@@ -76,7 +78,7 @@ jobs:
         run: yarn build:server
 
       - name: Build image for testing
-        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7.0.0
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
         with:
           context: .
           push: false
@@ -93,7 +95,7 @@ jobs:
       # This will use the cache from the earlier build step and not rebuild the image
       # https://docs.docker.com/build/ci/github-actions/test-before-push/
       - name: Build and push images
-        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7.0.0
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
         with:
           context: .
           push: ${{ github.event_name != 'pull_request' }}

.github/workflows/docker-release.yml

@@ -29,6 +29,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0
@@ -58,13 +60,13 @@ jobs:
           tags: ${{ env.TAGS }}
 
       - name: Login to Docker Hub
-        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Login to GitHub Container Registry
-        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
         with:
           registry: ghcr.io
           username: ${{ github.repository_owner }}
@@ -78,7 +80,7 @@ jobs:
         run: yarn build:server
 
       - name: Build and push ubuntu image
-        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7.0.0
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
         with:
           context: .
           push: true
@@ -87,7 +89,7 @@ jobs:
           tags: ${{ steps.meta.outputs.tags }}
 
       - name: Build and push alpine image
-        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7.0.0
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
         with:
           context: .
           push: true

.github/workflows/docs-spelling.yml

@@ -79,12 +79,12 @@ jobs:
     steps:
       - name: check-spelling
         id: spelling
-        uses: check-spelling/check-spelling@main
+        uses: check-spelling/check-spelling@cfb6f7e75bbfc89c71eaa30366d0c166f1bd9c8c # main
         with:
           suppress_push_for_open_pull_request: 1
           checkout: true
           check_file_names: 1
-          spell_check_this: check-spelling/spell-check-this@prerelease
+          spell_check_this: check-spelling/spell-check-this@92453f59cac8985482dfc301a8ece4c6d7de8a0c # prerelease
           post_comment: 0
           use_magic_file: 1
           experimental_apply_changes_via_bot: 1
@@ -114,10 +114,10 @@ jobs:
     if: (success() || failure()) && needs.spelling.outputs.followup && github.event_name == 'push'
     steps:
       - name: comment
-        uses: check-spelling/check-spelling@main
+        uses: check-spelling/check-spelling@cfb6f7e75bbfc89c71eaa30366d0c166f1bd9c8c # main
         with:
           checkout: true
-          spell_check_this: check-spelling/spell-check-this@prerelease
+          spell_check_this: check-spelling/spell-check-this@92453f59cac8985482dfc301a8ece4c6d7de8a0c # prerelease
           task: ${{ needs.spelling.outputs.followup }}
           config: .github/actions/docs-spelling
 
@@ -131,10 +131,10 @@ jobs:
     if: (success() || failure()) && needs.spelling.outputs.followup && contains(github.event_name, 'pull_request')
     steps:
       - name: comment
-        uses: check-spelling/check-spelling@main
+        uses: check-spelling/check-spelling@cfb6f7e75bbfc89c71eaa30366d0c166f1bd9c8c # main
         with:
           checkout: true
-          spell_check_this: check-spelling/spell-check-this@prerelease
+          spell_check_this: check-spelling/spell-check-this@92453f59cac8985482dfc301a8ece4c6d7de8a0c # prerelease
           task: ${{ needs.spelling.outputs.followup }}
           experimental_apply_changes_via_bot: 1
           config: .github/actions/docs-spelling
@@ -156,7 +156,7 @@ jobs:
       cancel-in-progress: false
     steps:
       - name: apply spelling updates
-        uses: check-spelling/check-spelling@main
+        uses: check-spelling/check-spelling@cfb6f7e75bbfc89c71eaa30366d0c166f1bd9c8c # main
         with:
           experimental_apply_changes_via_bot: 1
           checkout: true

.github/workflows/e2e-test.yml

@@ -17,32 +17,80 @@ on:
 env:
   GITHUB_PR_NUMBER: ${{github.event.pull_request.number}}
 
+permissions:
+  contents: read
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
 jobs:
-  functional:
-    name: Functional (shard ${{ matrix.shard }}/5)
+  build-web:
+    name: Build web bundle
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        shard: [1, 2, 3, 4, 5]
     container:
-      image: mcr.microsoft.com/playwright:v1.58.2-jammy
+      image: mcr.microsoft.com/playwright:v1.59.1-jammy
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
           download-translations: 'false'
       - name: Trust the repository directory
         run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+      - name: Build browser bundle
+        # REACT_APP_NETLIFY=true flips isNonProductionEnvironment() on in the
+        # bundle so the "Create test file" button (used by every e2e beforeEach
+        # via ConfigurationPage.createTestFile()) is still rendered in a
+        # production build. Without it, e2e tests would time out waiting for
+        # a button that was tree-shaken out.
+        # --skip-translations keeps VRT screenshots deterministic by rendering
+        # source-code English instead of upstream Weblate en.json (which can
+        # drift between snapshot capture and test runs).
+        env:
+          REACT_APP_NETLIFY: 'true'
+        run: yarn build:browser --skip-translations
+      - name: Upload build artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: desktop-client-build
+          path: packages/desktop-client/build/
+          retention-days: 1
+          overwrite: true
+
+  functional:
+    name: Functional (shard ${{ matrix.shard }}/3)
+    runs-on: ubuntu-latest
+    needs: build-web
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3]
+    container:
+      image: mcr.microsoft.com/playwright:v1.59.1-jammy
+    env:
+      E2E_USE_BUILD: '1'
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Set up environment
+        uses: ./.github/actions/setup
+        with:
+          download-translations: 'false'
+      - name: Trust the repository directory
+        run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+      - name: Download web build
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: desktop-client-build
+          path: packages/desktop-client/build/
       - name: Run E2E Tests
-        run: yarn e2e --shard=${{ matrix.shard }}/5
-      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
-        if: always()
+        run: yarn e2e --shard=${{ matrix.shard }}/3
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: failure()
         with:
           name: desktop-client-test-results-shard-${{ matrix.shard }}
           path: packages/desktop-client/test-results/
@@ -53,19 +101,27 @@ jobs:
     name: Functional Desktop App
     runs-on: ubuntu-latest
     container:
-      image: mcr.microsoft.com/playwright:v1.58.2-jammy
+      image: mcr.microsoft.com/playwright:v1.59.1-jammy
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
           download-translations: 'false'
       - name: Trust the repository directory
         run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+      # Build tools are needed to rebuild native modules like better-sqlite3 used by the Desktop app, which is required to run E2E tests on the Desktop app.
+      - name: Install build tools
+        run: apt-get update && apt-get install -y build-essential python3
+
       - name: Run Desktop app E2E Tests
         run: |
+          yarn rebuild-electron
           xvfb-run --auto-servernum --server-args="-screen 0 1920x1080x24" -- yarn e2e:desktop
-      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         if: always()
         with:
           name: desktop-app-test-results
@@ -74,23 +130,35 @@ jobs:
           overwrite: true
 
   vrt:
-    name: Visual regression (shard ${{ matrix.shard }}/5)
+    name: Visual regression (shard ${{ matrix.shard }}/3)
     runs-on: ubuntu-latest
+    needs: build-web
     strategy:
       fail-fast: false
       matrix:
-        shard: [1, 2, 3, 4, 5]
+        shard: [1, 2, 3]
     container:
-      image: mcr.microsoft.com/playwright:v1.58.2-jammy
+      image: mcr.microsoft.com/playwright:v1.59.1-jammy
+    env:
+      E2E_USE_BUILD: '1'
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
           download-translations: 'false'
+      - name: Trust the repository directory
+        run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+      - name: Download web build
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: desktop-client-build
+          path: packages/desktop-client/build/
       - name: Run VRT Tests
-        run: yarn vrt --shard=${{ matrix.shard }}/5
-      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        run: yarn vrt --shard=${{ matrix.shard }}/3
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         if: always()
         with:
           name: vrt-blob-report-${{ matrix.shard }}
@@ -104,9 +172,11 @@ jobs:
     runs-on: ubuntu-latest
     if: ${{ !cancelled() }}
     container:
-      image: mcr.microsoft.com/playwright:v1.58.2-jammy
+      image: mcr.microsoft.com/playwright:v1.59.1-jammy
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
       - name: Download all blob reports
@@ -118,7 +188,7 @@ jobs:
       - name: Merge reports
         id: merge-reports
         run: yarn workspace @actual-app/web run playwright merge-reports --reporter html ./all-blob-reports
-      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         id: playwright-report-vrt
         with:
           name: html-report--attempt-${{ github.run_attempt }}
@@ -131,10 +201,12 @@ jobs:
           mkdir -p vrt-metadata
           echo "${{ github.event.pull_request.number }}" > vrt-metadata/pr-number.txt
           echo "${{ needs.vrt.result }}" > vrt-metadata/vrt-result.txt
-          echo "${{ steps.playwright-report-vrt.outputs.artifact-url }}" > vrt-metadata/artifact-url.txt
+          echo "${STEPS_PLAYWRIGHT_REPORT_VRT_OUTPUTS_ARTIFACT_URL}" > vrt-metadata/artifact-url.txt
+        env:
+          STEPS_PLAYWRIGHT_REPORT_VRT_OUTPUTS_ARTIFACT_URL: ${{ steps.playwright-report-vrt.outputs.artifact-url }}
       - name: Upload VRT metadata
         if: github.event_name == 'pull_request'
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: vrt-comment-metadata
           path: vrt-metadata/

.github/workflows/e2e-vrt-comment.yml

@@ -53,7 +53,7 @@ jobs:
 
       - name: Comment on PR with VRT report link
         if: steps.metadata.outputs.should_comment == 'true'
-        uses: marocchino/sticky-pull-request-comment@70d2764d1a7d5d9560b100cbea0077fc8f633987 # v3.0.2
+        uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v3.0.4
         with:
           number: ${{ steps.metadata.outputs.pr_number }}
           header: vrt-comment

.github/workflows/electron-master.yml

@@ -22,6 +22,7 @@ jobs:
     permissions:
       contents: write
     strategy:
+      fail-fast: false
       matrix:
         os:
           - ubuntu-22.04
@@ -30,6 +31,8 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - if: ${{ startsWith(matrix.os, 'windows') }}
         run: pip.exe install setuptools
       - if: ${{ ! startsWith(matrix.os, 'windows') }}
@@ -56,9 +59,11 @@ jobs:
 
           METAINFO_FILE="packages/desktop-electron/extra-resources/linux/com.actualbudget.actual.metainfo.xml"
           TODAY=$(date +%Y-%m-%d)
-          VERSION=${{ steps.process_version.outputs.version }}
+          VERSION=${STEPS_PROCESS_VERSION_OUTPUTS_VERSION}
           sed -i "s/%RELEASE_VERSION%/$VERSION/g; s/%RELEASE_DATE%/$TODAY/g" "$METAINFO_FILE"
           flatpak run --command=flatpak-builder-lint org.flatpak.Builder appstream "$METAINFO_FILE"
+        env:
+          STEPS_PROCESS_VERSION_OUTPUTS_VERSION: ${{ steps.process_version.outputs.version }}
       - name: Set up environment
         uses: ./.github/actions/setup
       - name: Build Electron for Mac
@@ -74,7 +79,7 @@ jobs:
         if: ${{ ! startsWith(matrix.os, 'macos') }}
         run: ./bin/package-electron
       - name: Upload Build
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: actual-electron-${{ matrix.os }}
           path: |
@@ -85,7 +90,7 @@ jobs:
             packages/desktop-electron/dist/*.flatpak
       - name: Upload Windows Store Build
         if: ${{ startsWith(matrix.os, 'windows') }}
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: actual-electron-${{ matrix.os }}-appx
           path: |

.github/workflows/electron-pr.yml

@@ -26,6 +26,7 @@ concurrency:
 jobs:
   build:
     strategy:
+      fail-fast: false
       matrix:
         os:
           - ubuntu-22.04
@@ -34,6 +35,8 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - if: ${{ startsWith(matrix.os, 'windows') }}
         run: pip.exe install setuptools
       - if: ${{ ! startsWith(matrix.os, 'windows') }}
@@ -65,56 +68,56 @@ jobs:
         run: ./bin/package-electron
 
       - name: Upload Linux x64 AppImage
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: Actual-linux-x86_64.AppImage
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-linux-x86_64.AppImage
 
       - name: Upload Linux arm64 AppImage
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: Actual-linux-arm64.AppImage
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-linux-arm64.AppImage
 
       - name: Upload Linux x64 flatpak
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: Actual-linux-x86_64.flatpak
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-linux-x86_64.flatpak
 
       - name: Upload Windows x32 exe
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: Actual-windows-ia32.exe
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-windows-ia32.exe
 
       - name: Upload Windows x64 exe
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: Actual-windows-x64.exe
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-windows-x64.exe
 
       - name: Upload Windows arm64 exe
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: Actual-windows-arm64.exe
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-windows-arm64.exe
 
       - name: Upload Mac x64 dmg
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: Actual-mac-x64.dmg
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-mac-x64.dmg
 
       - name: Upload Mac arm64 dmg
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: Actual-mac-arm64.dmg
           if-no-files-found: ignore
@@ -122,7 +125,7 @@ jobs:
 
       - name: Upload Windows Store Build
         if: ${{ startsWith(matrix.os, 'windows') }}
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: actual-electron-${{ matrix.os }}-appx
           path: |

.github/workflows/fork-pr-welcome.yml

@@ -25,7 +25,7 @@ jobs:
     if: github.event.pull_request.head.repo.full_name != github.repository
     steps:
       - name: Post welcome comment
-        uses: marocchino/sticky-pull-request-comment@70d2764d1a7d5d9560b100cbea0077fc8f633987 # v3.0.2
+        uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v3.0.4
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           number: ${{ github.event.pull_request.number }}

.github/workflows/i18n-string-extract-master.yml

@@ -15,6 +15,7 @@ jobs:
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           path: actual
+          persist-credentials: false
       - name: Set up environment
         uses: ./actual/.github/actions/setup
         with:
@@ -27,12 +28,23 @@ jobs:
       - name: Configure i18n client
         run: |
           pip install wlc
+      - name: Configure Weblate API credentials
+        env:
+          WEBLATE_API_KEY: ${{ secrets.WEBLATE_API_KEY_CI_STRINGS }}
+        run: |
+          # Write the API key to wlc's config file instead of passing it on
+          # the command line, so the secret doesn't appear in process listings.
+          mkdir -p "$HOME/.config"
+          umask 077
+          cat > "$HOME/.config/weblate" <<EOF
+          [keys]
+          https://hosted.weblate.org/api/ = ${WEBLATE_API_KEY}
+          EOF
 
       - name: Lock translations
         run: |
           wlc \
             --url https://hosted.weblate.org/api/ \
-            --key "${{ secrets.WEBLATE_API_KEY_CI_STRINGS }}" \
             lock \
             actualbudget/actual
 
@@ -40,7 +52,6 @@ jobs:
         run: |
           wlc \
             --url https://hosted.weblate.org/api/ \
-            --key "${{ secrets.WEBLATE_API_KEY_CI_STRINGS }}" \
             push \
             actualbudget/actual
       - name: Check out updated translations
@@ -49,6 +60,8 @@ jobs:
           ssh-key: ${{ secrets.STRING_IMPORT_DEPLOY_KEY }}
           repository: actualbudget/translations
           path: translations
+          # Need to be able to push back extracted strings
+          persist-credentials: true
       - name: Generate i18n strings
         working-directory: actual
         run: |
@@ -73,7 +86,6 @@ jobs:
         run: |
           wlc \
             --url https://hosted.weblate.org/api/ \
-            --key "${{ secrets.WEBLATE_API_KEY_CI_STRINGS }}" \
             pull \
             actualbudget/actual
 
@@ -82,6 +94,5 @@ jobs:
         run: |
           wlc \
             --url https://hosted.weblate.org/api/ \
-            --key "${{ secrets.WEBLATE_API_KEY_CI_STRINGS }}" \
             unlock \
             actualbudget/actual

.github/workflows/issues-feature-implemented.yml

@@ -25,6 +25,8 @@ jobs:
     steps:
       # This is not a security concern because we have approved & merged the PR
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
           node-version: 22

.github/workflows/netlify-release.yml

@@ -22,6 +22,8 @@ jobs:
     steps:
       - name: Repository Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
 
       - name: Set up environment
         uses: ./.github/actions/setup
@@ -34,10 +36,11 @@ jobs:
 
       - name: Deploy to Netlify
         id: netlify_deploy
+        env:
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_API_TOKEN }}
         run: |
           netlify deploy \
             --dir packages/desktop-client/build \
-            --site ${{ secrets.NETLIFY_SITE_ID }} \
-            --auth ${{ secrets.NETLIFY_API_TOKEN }} \
             --filter @actual-app/web \
             --prod

.github/workflows/nightly-theme-catalog-scan.yml

@@ -0,0 +1,47 @@
+name: Nightly theme catalog scan
+
+on:
+  schedule:
+    # 05:15 UTC daily — runs after the i18n extract job (04:00) and well
+    # before the nightly Electron/npm publishes (00:00 UTC the next day).
+    - cron: '15 5 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  validate-theme-catalog:
+    name: Validate custom theme catalog
+    runs-on: ubuntu-latest
+    if: github.repository == 'actualbudget/actual'
+    timeout-minutes: 10
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Set up environment
+        uses: ./.github/actions/setup
+        with:
+          download-translations: 'false'
+      - name: Validate themes
+        run: yarn workspace @actual-app/web validate:theme-catalog
+
+  notify-failure:
+    name: Notify Discord on failure
+    needs: validate-theme-catalog
+    if: failure() && github.repository == 'actualbudget/actual'
+    runs-on: ubuntu-latest
+    environment: nightly-alerts
+    timeout-minutes: 5
+    steps:
+      - name: Notify Discord
+        uses: sarisia/actions-status-discord@eb045afee445dc055c18d3d90bd0f244fd062708 # v1.16.0
+        with:
+          webhook: ${{ secrets.DISCORD_WEBHOOK_URL }}
+          status: Failure
+          title: Nightly theme catalog scan failed
+          description: The nightly scan failed. One or more themes may be broken, or the scan itself did not complete.
+          username: Actual Nightly
+          nofail: true

.github/workflows/publish-flathub.yml

@@ -54,8 +54,9 @@ jobs:
       - name: Verify release assets exist
         env:
           GH_TOKEN: ${{ github.token }}
+          STEPS_RESOLVE_VERSION_OUTPUTS_TAG: ${{ steps.resolve_version.outputs.tag }}
         run: |
-          TAG="${{ steps.resolve_version.outputs.tag }}"
+          TAG="${STEPS_RESOLVE_VERSION_OUTPUTS_TAG}"
 
           echo "Checking release assets for tag $TAG..."
           ASSETS=$(gh api "repos/${{ github.repository }}/releases/tags/$TAG" --jq '.assets[].name')
@@ -77,7 +78,7 @@ jobs:
 
       - name: Calculate AppImage SHA256 (streamed)
         run: |
-          VERSION="${{ steps.resolve_version.outputs.version }}"
+          VERSION="${STEPS_RESOLVE_VERSION_OUTPUTS_VERSION}"
           BASE_URL="https://github.com/${{ github.repository }}/releases/download/v${VERSION}"
 
           echo "Streaming x86_64 AppImage to compute SHA256..."
@@ -90,30 +91,35 @@ jobs:
 
           echo "APPIMAGE_X64_SHA256=$APPIMAGE_X64_SHA256" >> "$GITHUB_ENV"
           echo "APPIMAGE_ARM64_SHA256=$APPIMAGE_ARM64_SHA256" >> "$GITHUB_ENV"
+        env:
+          STEPS_RESOLVE_VERSION_OUTPUTS_VERSION: ${{ steps.resolve_version.outputs.version }}
 
       - name: Checkout Flathub repo
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           repository: flathub/com.actualbudget.actual
           token: ${{ secrets.FLATHUB_GITHUB_TOKEN }}
+          persist-credentials: false
 
       - name: Update manifest with new version
         run: |
-          VERSION="${{ steps.resolve_version.outputs.version }}"
+          VERSION="${STEPS_RESOLVE_VERSION_OUTPUTS_VERSION}"
 
           # Replace x86_64 entry
-          sed -i "/x86_64.AppImage/{n;s|sha256:.*|sha256: ${{ env.APPIMAGE_X64_SHA256 }}|}" com.actualbudget.actual.yml
+          sed -i "/x86_64.AppImage/{n;s|sha256:.*|sha256: ${APPIMAGE_X64_SHA256}|}" com.actualbudget.actual.yml
           sed -i "/x86_64.AppImage/s|url:.*|url: https://github.com/actualbudget/actual/releases/download/v${VERSION}/Actual-linux-x86_64.AppImage|" com.actualbudget.actual.yml
 
           # Replace arm64 entry
-          sed -i "/arm64.AppImage/{n;s|sha256:.*|sha256: ${{ env.APPIMAGE_ARM64_SHA256 }}|}" com.actualbudget.actual.yml
+          sed -i "/arm64.AppImage/{n;s|sha256:.*|sha256: ${APPIMAGE_ARM64_SHA256}|}" com.actualbudget.actual.yml
           sed -i "/arm64.AppImage/s|url:.*|url: https://github.com/actualbudget/actual/releases/download/v${VERSION}/Actual-linux-arm64.AppImage|" com.actualbudget.actual.yml
 
           echo "Updated manifest:"
           cat com.actualbudget.actual.yml
+        env:
+          STEPS_RESOLVE_VERSION_OUTPUTS_VERSION: ${{ steps.resolve_version.outputs.version }}
 
       - name: Create PR in Flathub repo
-        uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
         with:
           token: ${{ secrets.FLATHUB_GITHUB_TOKEN }}
           commit-message: 'Update Actual flatpak to version ${{ steps.resolve_version.outputs.version }}'

.github/workflows/publish-nightly-electron.yml

@@ -20,6 +20,7 @@ concurrency:
 jobs:
   build:
     strategy:
+      fail-fast: false
       matrix:
         os:
           - ubuntu-22.04
@@ -29,6 +30,8 @@ jobs:
     if: github.event.repository.fork == false
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - if: ${{ startsWith(matrix.os, 'windows') }}
         run: pip.exe install setuptools
 
@@ -83,49 +86,49 @@ jobs:
         run: ./bin/package-electron
 
       - name: Upload Linux x64 AppImage
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: Actual-linux-x86_64.AppImage
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-linux-x86_64.AppImage
 
       - name: Upload Linux arm64 AppImage
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: Actual-linux-arm64.AppImage
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-linux-arm64.AppImage
 
       - name: Upload Windows x32 exe
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: Actual-windows-ia32.exe
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-windows-ia32.exe
 
       - name: Upload Windows x64 exe
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: Actual-windows-x64.exe
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-windows-x64.exe
 
       - name: Upload Windows arm64 exe
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: Actual-windows-arm64.exe
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-windows-arm64.exe
 
       - name: Upload Mac x64 dmg
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: Actual-mac-x64.dmg
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-mac-x64.dmg
 
       - name: Upload Mac arm64 dmg
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: Actual-mac-arm64.dmg
           if-no-files-found: ignore
@@ -133,7 +136,7 @@ jobs:
 
       - name: Upload Windows Store Build
         if: ${{ startsWith(matrix.os, 'windows') }}
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: actual-electron-${{ matrix.os }}-appx
           path: |

.github/workflows/publish-nightly-npm-packages.yml

@@ -1,124 +0,0 @@
-name: Publish nightly npm packages
-
-# Nightly npm packages are built daily at midnight UTC
-on:
-  schedule:
-    - cron: '0 0 * * *'
-  workflow_dispatch:
-
-jobs:
-  build-and-pack:
-    runs-on: ubuntu-latest
-    name: Build and pack npm packages
-    if: github.event.repository.fork == false
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Set up environment
-        uses: ./.github/actions/setup
-
-      - name: Update package versions
-        run: |
-          # Get new nightly versions
-          NEW_CORE_VERSION=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts --package-json ./packages/loot-core/package.json --type nightly)
-          NEW_WEB_VERSION=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts --package-json ./packages/desktop-client/package.json --type nightly)
-          NEW_SYNC_VERSION=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts --package-json ./packages/sync-server/package.json --type nightly)
-          NEW_API_VERSION=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts --package-json ./packages/api/package.json --type nightly)
-          NEW_CLI_VERSION=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts --package-json ./packages/cli/package.json --type nightly)
-
-          # Set package versions
-          npm version $NEW_CORE_VERSION --no-git-tag-version --workspace=@actual-app/core --no-workspaces-update
-          npm version $NEW_WEB_VERSION --no-git-tag-version --workspace=@actual-app/web --no-workspaces-update
-          npm version $NEW_SYNC_VERSION --no-git-tag-version --workspace=@actual-app/sync-server --no-workspaces-update
-          npm version $NEW_API_VERSION --no-git-tag-version --workspace=@actual-app/api --no-workspaces-update
-          npm version $NEW_CLI_VERSION --no-git-tag-version --workspace=@actual-app/cli --no-workspaces-update
-
-      - name: Yarn install
-        run: |
-          yarn install
-
-      - name: Pack the core package
-        run: |
-          yarn workspace @actual-app/core pack --filename @actual-app/core.tgz
-
-      - name: Build Server & Web
-        run: yarn build:server
-
-      - name: Pack the web and server packages
-        run: |
-          yarn workspace @actual-app/web pack --filename @actual-app/web.tgz
-          yarn workspace @actual-app/sync-server pack --filename @actual-app/sync-server.tgz
-
-      - name: Build API
-        run: yarn build:api
-
-      - name: Pack the api package
-        run: |
-          yarn workspace @actual-app/api pack --filename @actual-app/api.tgz
-
-      - name: Build CLI
-        run: yarn workspace @actual-app/cli build
-
-      - name: Pack the cli package
-        run: |
-          yarn workspace @actual-app/cli pack --filename @actual-app/cli.tgz
-
-      - name: Upload package artifacts
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
-        with:
-          name: npm-packages
-          path: |
-            packages/loot-core/@actual-app/core.tgz
-            packages/desktop-client/@actual-app/web.tgz
-            packages/sync-server/@actual-app/sync-server.tgz
-            packages/api/@actual-app/api.tgz
-            packages/cli/@actual-app/cli.tgz
-
-  publish:
-    runs-on: ubuntu-latest
-    name: Publish Nightly npm packages
-    needs: build-and-pack
-    permissions:
-      contents: read
-      packages: write
-    steps:
-      - name: Download the artifacts
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          name: npm-packages
-
-      - name: Setup node and npm registry
-        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
-        with:
-          node-version: 22
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Publish Core
-        run: |
-          npm publish loot-core/@actual-app/core.tgz --access public --tag nightly
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Publish Web
-        run: |
-          npm publish desktop-client/@actual-app/web.tgz --access public --tag nightly
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Publish Sync-Server
-        run: |
-          npm publish sync-server/@actual-app/sync-server.tgz --access public --tag nightly
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Publish API
-        run: |
-          npm publish api/@actual-app/api.tgz --access public --tag nightly
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Publish CLI
-        run: |
-          npm publish cli/@actual-app/cli.tgz --access public --tag nightly
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/publish-npm-packages.yml

@@ -1,26 +1,55 @@
 name: Publish npm packages
 
-# # Npm packages are published for every new tag
+# Npm packages are published for every new tag and nightly schedule
 on:
   push:
     tags:
       - 'v*.*.*'
+  schedule:
+    - cron: '0 0 * * *'
+  workflow_dispatch:
 
 jobs:
   build-and-pack:
     runs-on: ubuntu-latest
     name: Build and pack npm packages
+    if: github.event_name == 'push' || (github.event.repository.fork == false)
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
 
       - name: Set up environment
         uses: ./.github/actions/setup
 
+      - name: Update package versions
+        if: github.event_name != 'push'
+        run: |
+          # Get new nightly versions
+          NEW_CORE_VERSION=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts --package-json ./packages/loot-core/package.json --type nightly)
+          NEW_WEB_VERSION=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts --package-json ./packages/desktop-client/package.json --type nightly)
+          NEW_SYNC_VERSION=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts --package-json ./packages/sync-server/package.json --type nightly)
+          NEW_API_VERSION=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts --package-json ./packages/api/package.json --type nightly)
+          NEW_CLI_VERSION=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts --package-json ./packages/cli/package.json --type nightly)
+
+          # Set package versions
+          npm version $NEW_CORE_VERSION --no-git-tag-version --workspace=@actual-app/core --no-workspaces-update
+          npm version $NEW_WEB_VERSION --no-git-tag-version --workspace=@actual-app/web --no-workspaces-update
+          npm version $NEW_SYNC_VERSION --no-git-tag-version --workspace=@actual-app/sync-server --no-workspaces-update
+          npm version $NEW_API_VERSION --no-git-tag-version --workspace=@actual-app/api --no-workspaces-update
+          npm version $NEW_CLI_VERSION --no-git-tag-version --workspace=@actual-app/cli --no-workspaces-update
+
+      - name: Yarn install
+        if: github.event_name != 'push'
+        run: |
+          # Required after nightly `npm version` updates workspace manifests.
+          yarn install
+
       - name: Pack the core package
         run: |
           yarn workspace @actual-app/core pack --filename @actual-app/core.tgz
 
-      - name: Build Web
+      - name: Build Server & Web
         run: yarn build:server
 
       - name: Pack the web and server packages
@@ -43,7 +72,8 @@ jobs:
           yarn workspace @actual-app/cli pack --filename @actual-app/cli.tgz
 
       - name: Upload package artifacts
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: ${{ !env.ACT }}
         with:
           name: npm-packages
           path: |
@@ -60,6 +90,9 @@ jobs:
     permissions:
       contents: read
       packages: write
+      id-token: write # Required for OIDC
+    env:
+      NPM_DIST_TAG: ${{ github.event_name != 'push' && 'nightly' || '' }}
     steps:
       - name: Download the artifacts
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -69,35 +102,26 @@ jobs:
       - name: Setup node and npm registry
         uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
-          node-version: 22
+          node-version: 24
+          check-latest: true
           registry-url: 'https://registry.npmjs.org'
 
       - name: Publish Core
         run: |
-          npm publish loot-core/@actual-app/core.tgz --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          npm publish loot-core/@actual-app/core.tgz --access public ${NPM_DIST_TAG:+--tag "$NPM_DIST_TAG"}
 
       - name: Publish Web
         run: |
-          npm publish desktop-client/@actual-app/web.tgz --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          npm publish desktop-client/@actual-app/web.tgz --access public ${NPM_DIST_TAG:+--tag "$NPM_DIST_TAG"}
 
       - name: Publish Sync-Server
         run: |
-          npm publish sync-server/@actual-app/sync-server.tgz --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          npm publish sync-server/@actual-app/sync-server.tgz --access public ${NPM_DIST_TAG:+--tag "$NPM_DIST_TAG"}
 
       - name: Publish API
         run: |
-          npm publish api/@actual-app/api.tgz --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          npm publish api/@actual-app/api.tgz --access public ${NPM_DIST_TAG:+--tag "$NPM_DIST_TAG"}
 
       - name: Publish CLI
         run: |
-          npm publish cli/@actual-app/cli.tgz --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          npm publish cli/@actual-app/cli.tgz --access public ${NPM_DIST_TAG:+--tag "$NPM_DIST_TAG"}

.github/workflows/release-notes.yml

@@ -3,6 +3,10 @@ name: Release notes
 on:
   pull_request:
 
+permissions:
+  contents: write
+  pull-requests: read
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
@@ -11,15 +15,37 @@ jobs:
   release-notes:
     runs-on: ubuntu-latest
     steps:
+      - name: Check if triggered by bot
+        id: bot-check
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { data: commit } = await github.rest.git.getCommit({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              commit_sha: context.payload.pull_request.head.sha,
+            });
+            const skip = commit.author.name === 'github-actions[bot]'
+              && commit.message.startsWith('Generate release notes');
+            console.log(`Head commit by "${commit.author.name}": ${commit.message.split('\n')[0]}`);
+            console.log(`Skip: ${skip}`);
+            core.setOutput('skip', String(skip));
+
       - name: Checkout
+        if: steps.bot-check.outputs.skip != 'true'
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
+          token: ${{ secrets.ACTIONS_UPDATE_TOKEN || github.token }}
+          # Need to be able to commit release notes after generation
+          persist-credentials: true
+
       - name: Get changed files
+        if: steps.bot-check.outputs.skip != 'true'
         id: changed-files
         run: |
-          git fetch origin ${{ github.base_ref }}
-          CHANGED_FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
+          git fetch origin ${GITHUB_BASE_REF}
+          CHANGED_FILES=$(git diff --name-only origin/${GITHUB_BASE_REF}...HEAD)
           NON_DOCS_FILES=$(echo "$CHANGED_FILES" | grep -v -e "^packages/docs/" -e "^\.github/actions/docs-spelling/" || true)
 
           if [ -z "$NON_DOCS_FILES" ] && [ -n "$CHANGED_FILES" ]; then
@@ -28,9 +54,17 @@ jobs:
           else
             echo "only_docs=false" >> $GITHUB_OUTPUT
           fi
+
       - name: Check release notes
-        if: startsWith(github.head_ref, 'release/') == false && steps.changed-files.outputs.only_docs != 'true'
+        if: >-
+          steps.bot-check.outputs.skip != 'true'
+          && startsWith(github.head_ref, 'release/') == false
+          && steps.changed-files.outputs.only_docs != 'true'
         uses: ./.github/actions/release-notes/check
+
       - name: Generate release notes
-        if: startsWith(github.head_ref, 'release/') == true
+        if: >-
+          steps.bot-check.outputs.skip != 'true'
+          && startsWith(github.head_ref, 'release/') == true
+          && github.event.pull_request.head.repo.full_name == github.event.pull_request.base.repo.full_name
         uses: ./.github/actions/release-notes/generate

.github/workflows/size-compare.yml

@@ -38,6 +38,7 @@ jobs:
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           ref: ${{ github.base_ref }}
+          persist-credentials: false
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
@@ -64,6 +65,13 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           checkName: cli
           ref: ${{github.base_ref}}
+      - name: Wait for ${{github.base_ref}} CRDT build to succeed
+        uses: fountainhead/action-wait-for-check@5a908a24814494009c4bb27c242ea38c93c593be # v1.2.0
+        id: master-crdt-build
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          checkName: crdt
+          ref: ${{github.base_ref}}
 
       - name: Wait for PR build to succeed
         uses: fountainhead/action-wait-for-check@5a908a24814494009c4bb27c242ea38c93c593be # v1.2.0
@@ -86,15 +94,22 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           checkName: cli
           ref: ${{github.event.pull_request.head.sha}}
+      - name: Wait for CRDT PR build to succeed
+        uses: fountainhead/action-wait-for-check@5a908a24814494009c4bb27c242ea38c93c593be # v1.2.0
+        id: wait-for-crdt-build
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          checkName: crdt
+          ref: ${{github.event.pull_request.head.sha}}
 
       - name: Report build failure
-        if: steps.wait-for-web-build.outputs.conclusion == 'failure' || steps.wait-for-api-build.outputs.conclusion == 'failure' || steps.wait-for-cli-build.outputs.conclusion == 'failure'
+        if: steps.wait-for-web-build.outputs.conclusion == 'failure' || steps.wait-for-api-build.outputs.conclusion == 'failure' || steps.wait-for-cli-build.outputs.conclusion == 'failure' || steps.wait-for-crdt-build.outputs.conclusion == 'failure'
         run: |
-          echo "Build failed on PR branch or ${{github.base_ref}}"
+          echo "Build failed on PR branch or ${GITHUB_BASE_REF}"
           exit 1
 
       - name: Download web build artifact from ${{github.base_ref}}
-        uses: dawidd6/action-download-artifact@1f8785ff7a5130826f848e7f72725c85d241860f # v18
+        uses: dawidd6/action-download-artifact@8305c0f1062bb0d184d09ef4493ecb9288447732 # v20
         id: pr-web-build
         with:
           branch: ${{github.base_ref}}
@@ -103,7 +118,7 @@ jobs:
           name: build-stats
           path: base
       - name: Download API build artifact from ${{github.base_ref}}
-        uses: dawidd6/action-download-artifact@1f8785ff7a5130826f848e7f72725c85d241860f # v18
+        uses: dawidd6/action-download-artifact@8305c0f1062bb0d184d09ef4493ecb9288447732 # v20
         id: pr-api-build
         with:
           branch: ${{github.base_ref}}
@@ -112,7 +127,7 @@ jobs:
           name: api-build-stats
           path: base
       - name: Download build stats from PR
-        uses: dawidd6/action-download-artifact@1f8785ff7a5130826f848e7f72725c85d241860f # v18
+        uses: dawidd6/action-download-artifact@8305c0f1062bb0d184d09ef4493ecb9288447732 # v20
         with:
           pr: ${{github.event.pull_request.number}}
           workflow: build.yml
@@ -121,7 +136,7 @@ jobs:
           path: head
           allow_forks: true
       - name: Download API stats from PR
-        uses: dawidd6/action-download-artifact@1f8785ff7a5130826f848e7f72725c85d241860f # v18
+        uses: dawidd6/action-download-artifact@8305c0f1062bb0d184d09ef4493ecb9288447732 # v20
         with:
           pr: ${{github.event.pull_request.number}}
           workflow: build.yml
@@ -130,7 +145,7 @@ jobs:
           path: head
           allow_forks: true
       - name: Download CLI build artifact from ${{github.base_ref}}
-        uses: dawidd6/action-download-artifact@1f8785ff7a5130826f848e7f72725c85d241860f # v18
+        uses: dawidd6/action-download-artifact@8305c0f1062bb0d184d09ef4493ecb9288447732 # v20
         with:
           branch: ${{github.base_ref}}
           workflow: build.yml
@@ -138,7 +153,7 @@ jobs:
           name: cli-build-stats
           path: base
       - name: Download CLI stats from PR
-        uses: dawidd6/action-download-artifact@1f8785ff7a5130826f848e7f72725c85d241860f # v18
+        uses: dawidd6/action-download-artifact@8305c0f1062bb0d184d09ef4493ecb9288447732 # v20
         with:
           pr: ${{github.event.pull_request.number}}
           workflow: build.yml
@@ -146,6 +161,23 @@ jobs:
           name: cli-build-stats
           path: head
           allow_forks: true
+      - name: Download CRDT build artifact from ${{github.base_ref}}
+        uses: dawidd6/action-download-artifact@8305c0f1062bb0d184d09ef4493ecb9288447732 # v20
+        with:
+          branch: ${{github.base_ref}}
+          workflow: build.yml
+          workflow_conclusion: '' # ignore the conclusion of the workflow, since we already checked it
+          name: crdt-build-stats
+          path: base
+      - name: Download CRDT stats from PR
+        uses: dawidd6/action-download-artifact@8305c0f1062bb0d184d09ef4493ecb9288447732 # v20
+        with:
+          pr: ${{github.event.pull_request.number}}
+          workflow: build.yml
+          workflow_conclusion: '' # ignore the conclusion of the workflow, since we already checked it
+          name: crdt-build-stats
+          path: head
+          allow_forks: true
       - name: Strip content hashes from stats files
         run: |
           if [ -f ./head/web-stats.json ]; then
@@ -168,10 +200,12 @@ jobs:
             --base loot-core=./base/loot-core-stats.json \
             --base api=./base/api-stats.json \
             --base cli=./base/cli-stats.json \
+            --base crdt=./base/crdt-stats.json \
             --head desktop-client=./head/web-stats.json \
             --head loot-core=./head/loot-core-stats.json \
             --head api=./head/api-stats.json \
             --head cli=./head/cli-stats.json \
+            --head crdt=./head/crdt-stats.json \
             --identifier combined \
             --format pr-body > bundle-stats-comment.md
       - name: Post combined bundle stats comment

.github/workflows/stale.yml

@@ -3,9 +3,12 @@ on:
   schedule:
     - cron: '30 1 * * *'
   workflow_dispatch: # Allow manual triggering
+permissions: {}
 
 jobs:
   stale:
+    permissions:
+      pull-requests: write
     runs-on: ubuntu-latest
     steps:
       - uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10.2.0
@@ -16,6 +19,8 @@ jobs:
           days-before-close: 5
           days-before-issue-stale: -1
   stale-wip:
+    permissions:
+      pull-requests: write
     runs-on: ubuntu-latest
     steps:
       - uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10.2.0
@@ -27,6 +32,8 @@ jobs:
           days-before-issue-stale: -1
 
   stale-needs-info:
+    permissions:
+      issues: write
     runs-on: ubuntu-latest
     steps:
       - uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10.2.0

.github/workflows/vrt-update-apply.yml

@@ -107,7 +107,7 @@ jobs:
             fi
 
             # Commit
-            git commit -m "Update VRT screenshots" -m "Auto-generated by VRT workflow" -m "PR: #${{ steps.metadata.outputs.pr_number }}"
+            git commit -m "Update VRT screenshots" -m "Auto-generated by VRT workflow" -m "PR: #${STEPS_METADATA_OUTPUTS_PR_NUMBER}"
 
             echo "applied=true" >> "$GITHUB_OUTPUT"
           else
@@ -116,6 +116,8 @@ jobs:
             echo "error=Patch conflicts with current branch state" >> "$GITHUB_OUTPUT"
             exit 1
           fi
+        env:
+          STEPS_METADATA_OUTPUTS_PR_NUMBER: ${{ steps.metadata.outputs.pr_number }}
 
       - name: Push changes
         if: steps.apply.outputs.applied == 'true'
@@ -133,12 +135,15 @@ jobs:
 
       - name: Comment on PR - Failure
         if: failure() && steps.metadata.outputs.pr_number != ''
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          APPLY_ERROR: ${{ steps.apply.outputs.error }}
+          PR_NUMBER: ${{ steps.metadata.outputs.pr_number }}
         with:
           script: |
-            const error = `${{ steps.apply.outputs.error }}` || 'Unknown error occurred';
+            const error = process.env.APPLY_ERROR || 'Unknown error occurred';
             await github.rest.issues.createComment({
-              issue_number: ${{ steps.metadata.outputs.pr_number }},
+              issue_number: parseInt(process.env.PR_NUMBER, 10),
               owner: context.repo.owner,
               repo: context.repo.repo,
               body: `❌ Failed to apply VRT updates: ${error}\n\nPlease check the workflow logs for details.`

.github/workflows/vrt-update-generate.yml

@@ -26,7 +26,7 @@ jobs:
       pull-requests: write
     steps:
       - name: Add 👀 reaction to comment
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             await github.rest.reactions.createForIssueComment({
@@ -44,11 +44,11 @@ jobs:
       github.event.issue.pull_request &&
       startsWith(github.event.comment.body, '/update-vrt')
     container:
-      image: mcr.microsoft.com/playwright:v1.58.2-jammy
+      image: mcr.microsoft.com/playwright:v1.59.1-jammy
     steps:
       - name: Get PR details
         id: pr
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             const { data: pr } = await github.rest.pulls.get({
@@ -63,15 +63,25 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           ref: ${{ steps.pr.outputs.head_sha }}
+          persist-credentials: false
+
+      - name: Trust workspace directory
+        run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+        shell: bash
 
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
           download-translations: 'false'
 
+      # Build tools are needed to rebuild native modules like better-sqlite3 used by the Desktop app, which is required to run VRT tests on the Desktop app and generate updated snapshots.
+      - name: Install build tools
+        run: apt-get update && apt-get install -y build-essential python3
+
       - name: Run VRT Tests on Desktop app
         continue-on-error: true
         run: |
+          yarn rebuild-electron
           xvfb-run --auto-servernum --server-args="-screen 0 1920x1080x24" -- yarn e2e:desktop --update-snapshots
 
       - name: Run VRT Tests
@@ -81,9 +91,6 @@ jobs:
       - name: Create patch with PNG changes only
         id: create-patch
         run: |
-          # Trust the repository directory (required for container environments)
-          git config --global --add safe.directory "$GITHUB_WORKSPACE"
-
           git config --global user.name "github-actions[bot]"
           git config --global user.email "github-actions[bot]@users.noreply.github.com"
 
@@ -113,7 +120,7 @@ jobs:
 
       - name: Upload patch artifact
         if: steps.create-patch.outputs.has_changes == 'true'
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: vrt-patch-${{ github.event.issue.number }}
           path: vrt-update.patch
@@ -124,12 +131,15 @@ jobs:
         run: |
           mkdir -p pr-metadata
           echo "${{ github.event.issue.number }}" > pr-metadata/pr-number.txt
-          echo "${{ steps.pr.outputs.head_ref }}" > pr-metadata/head-ref.txt
-          echo "${{ steps.pr.outputs.head_repo }}" > pr-metadata/head-repo.txt
+          echo "${STEPS_PR_OUTPUTS_HEAD_REF}" > pr-metadata/head-ref.txt
+          echo "${STEPS_PR_OUTPUTS_HEAD_REPO}" > pr-metadata/head-repo.txt
+        env:
+          STEPS_PR_OUTPUTS_HEAD_REF: ${{ steps.pr.outputs.head_ref }}
+          STEPS_PR_OUTPUTS_HEAD_REPO: ${{ steps.pr.outputs.head_repo }}
 
       - name: Upload PR metadata
         if: steps.create-patch.outputs.has_changes == 'true'
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: vrt-metadata-${{ github.event.issue.number }}
           path: pr-metadata/

.gitignore

@@ -42,6 +42,9 @@ bundle.desktop.js.map
 bundle.mobile.js
 bundle.mobile.js.map
 
+# Python virtualenv (Electron CI provisions one at the repo root for setuptools)
+.venv/
+
 # Yarn
 .pnp.*
 .yarn/*

.oxfmtrc.json

@@ -9,24 +9,14 @@
       "react",
       "builtin",
       "external",
-      "loot-core",
       ["parent", "subpath"],
       "sibling",
-      "index",
-      "desktop-client"
+      "index"
     ],
     "customGroups": [
       {
         "groupName": "react",
         "elementNamePattern": ["react", "react-dom/*", "react-*"]
-      },
-      {
-        "groupName": "loot-core",
-        "elementNamePattern": ["loot-core/**", "@actual-app/core/**"]
-      },
-      {
-        "groupName": "desktop-client",
-        "elementNamePattern": ["@desktop-client/**"]
       }
     ],
     "newlinesBetween": true

.oxlintrc.json

@@ -36,6 +36,9 @@
     "actual/prefer-const": "error",
     "actual/no-anchor-tag": "error",
     "actual/no-react-default-import": "error",
+    "actual/prefer-subpath-imports": "error",
+    "actual/enforce-boundaries": "error",
+    "actual/no-extraneous-dependencies": "error",
 
     // JSX A11y rules
     "jsx-a11y/no-autofocus": [
@@ -120,9 +123,6 @@
     "import/no-amd": "error",
     "import/no-default-export": "error",
     "import/no-webpack-loader-syntax": "error",
-    "import/no-useless-path-segments": "error",
-    "import/no-unresolved": "error",
-    "import/no-unused-modules": "error",
     "import/no-duplicates": [
       "error",
       {
@@ -160,7 +160,6 @@
     "react/no-danger-with-children": "error",
     "react/no-direct-mutation-state": "error",
     "react/no-is-mounted": "error",
-    "react/no-unstable-nested-components": "error",
     "react/require-render-return": "error",
     "react/rules-of-hooks": "error",
     "react/self-closing-comp": "error",
@@ -234,7 +233,7 @@
     "eslint/require-yield": "error",
     "eslint/getter-return": "error",
     "eslint/unicode-bom": ["error", "never"],
-    "eslint/no-use-isnan": "error",
+    "eslint/use-isnan": "error",
     "eslint/valid-typeof": "error",
     "eslint/no-useless-rename": [
       "error",
@@ -335,14 +334,9 @@
         ],
         "patterns": [
           {
-            "group": ["**/*.api", "**/*.web", "**/*.electron"],
+            "group": ["**/*.api", "**/*.electron"],
             "message": "Don't directly reference imports from other platforms"
           },
-          {
-            "group": ["uuid"],
-            "importNames": ["*"],
-            "message": "Use `import { v4 as uuidv4 } from 'uuid'` instead"
-          },
           {
             "group": ["**/style", "**/colors"],
             "importNames": ["colors"],
@@ -376,7 +370,14 @@
       "files": ["**/*.test.{js,ts,jsx,tsx}", "packages/docs/**/*"],
       "rules": {
         "actual/no-untranslated-strings": "off",
-        "actual/prefer-logger-over-console": "off"
+        "actual/prefer-logger-over-console": "off",
+        "typescript/unbound-method": "off"
+      }
+    },
+    {
+      "files": ["packages/eslint-plugin-actual/lib/rules/__tests__/**/*"],
+      "rules": {
+        "actual/enforce-boundaries": "off"
       }
     },
     {
@@ -423,6 +424,16 @@
       "rules": {
         "eslint/no-empty-function": "off"
       }
+    },
+    // crdt enforces the repo's "TODO: enable this" typescript rules as errors
+    {
+      "files": ["packages/crdt/**/*"],
+      "rules": {
+        "typescript/no-misused-spread": "error",
+        "typescript/no-base-to-string": "error",
+        "typescript/no-unsafe-unary-minus": "error",
+        "typescript/no-unsafe-type-assertion": "error"
+      }
     }
   ]
 }

.yarnrc.yml

@@ -6,4 +6,4 @@ enableTransparentWorkspaces: false
 
 nodeLinker: node-modules
 
-yarnPath: .yarn/releases/yarn-4.10.3.cjs
+yarnPath: .yarn/releases/yarn-4.13.0.cjs

AGENTS.md

@@ -281,7 +281,6 @@ Always run `yarn typecheck` before committing.
 - Avoid `any` or `unknown` unless absolutely necessary
 - Look for existing type definitions in the codebase
 - Avoid type assertions (`as`, `!`) - prefer `satisfies`
-- Use inline type imports: `import { type MyType } from '...'`
 
 **Naming:**
 
@@ -331,7 +330,7 @@ Always maintain newlines between import groups.
 
 ### Platform-Specific Code
 
-- Don't directly reference platform-specific imports (`.api`, `.web`, `.electron`)
+- Don't directly reference platform-specific imports (`.api`, `.electron`)
 - Use conditional exports in `loot-core` for platform-specific code
 - Platform resolution happens at build time via package.json exports
 
@@ -501,7 +500,7 @@ Icons in `packages/component-library/src/icons/` are auto-generated. Don't manua
 
 1. Check `tsconfig.json` for path mappings
 2. Check package.json `exports` field (especially for loot-core)
-3. Verify platform-specific imports (`.web`, `.electron`, `.api`)
+3. Verify platform-specific imports (`.electron`, `.api`)
 4. Use absolute imports in `desktop-client` (enforced by ESLint)
 
 ### Build Failures

CONTRIBUTING.md

@@ -1 +1,3 @@
 Please review the contributing documentation on our website: https://actualbudget.org/docs/contributing/
+
+If you plan to use AI tools when contributing, please also read our [AI Usage Policy](https://actualbudget.org/docs/contributing/ai-usage-policy).

bin/__tests__/validate-publish-imports.test.ts

@@ -0,0 +1,218 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  derivePublishImports,
+  validatePackage,
+} from '../validate-publish-imports.js';
+
+describe('derivePublishImports', () => {
+  it('prepends ./build/ to .js paths', () => {
+    const imports = {
+      '#account-db': './src/account-db.js',
+    };
+    expect(derivePublishImports(imports)).toEqual({
+      '#account-db': './build/src/account-db.js',
+    });
+  });
+
+  it('converts .ts extension to .js and prepends ./build/', () => {
+    const imports = {
+      '#migrations': './src/migrations.ts',
+    };
+    expect(derivePublishImports(imports)).toEqual({
+      '#migrations': './build/src/migrations.js',
+    });
+  });
+
+  it('converts .tsx extension to .js and prepends ./build/', () => {
+    const imports = {
+      '#component': './src/component.tsx',
+    };
+    expect(derivePublishImports(imports)).toEqual({
+      '#component': './build/src/component.js',
+    });
+  });
+
+  it('preserves wildcard patterns', () => {
+    const imports = {
+      '#accounts/*': './src/accounts/*.js',
+      '#services/*': './src/app-gocardless/services/*.ts',
+    };
+    expect(derivePublishImports(imports)).toEqual({
+      '#accounts/*': './build/src/accounts/*.js',
+      '#services/*': './build/src/app-gocardless/services/*.js',
+    });
+  });
+
+  it('handles multiple entries with mixed extensions', () => {
+    const imports = {
+      '#account-db': './src/account-db.js',
+      '#migrations': './src/migrations.ts',
+      '#app-gocardless/errors': './src/app-gocardless/errors.ts',
+      '#util/*': './src/util/*.ts',
+      '#scripts/*': './src/scripts/*.js',
+    };
+    expect(derivePublishImports(imports)).toEqual({
+      '#account-db': './build/src/account-db.js',
+      '#migrations': './build/src/migrations.js',
+      '#app-gocardless/errors': './build/src/app-gocardless/errors.js',
+      '#util/*': './build/src/util/*.js',
+      '#scripts/*': './build/src/scripts/*.js',
+    });
+  });
+
+  it('returns empty object for empty imports', () => {
+    expect(derivePublishImports({})).toEqual({});
+  });
+
+  it('throws error for non-string imports values', () => {
+    const imports = {
+      '#foo': './src/foo.js',
+      '#conditional': {
+        browser: './src/browser.js',
+        node: './src/node.js',
+      },
+    };
+    expect(() => derivePublishImports(imports)).toThrow(
+      'Unsupported imports target for "#conditional". Expected a string path.',
+    );
+  });
+
+  it('handles paths with /index.js suffix', () => {
+    const imports = {
+      '#util/title': './src/util/title/index.js',
+    };
+    expect(derivePublishImports(imports)).toEqual({
+      '#util/title': './build/src/util/title/index.js',
+    });
+  });
+});
+
+describe('validatePackage', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'validate-imports-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function writePackageJson(content: Record<string, unknown>) {
+    const filePath = path.join(tmpDir, 'package.json');
+    fs.writeFileSync(filePath, JSON.stringify(content, null, 2) + '\n');
+    return filePath;
+  }
+
+  it('skips packages with no publishConfig', () => {
+    const filePath = writePackageJson({
+      name: 'test-pkg',
+      imports: { '#foo': './src/foo.js' },
+    });
+    const { result, warnings } = validatePackage(filePath);
+    expect(result).toBeNull();
+    expect(warnings).toEqual([]);
+  });
+
+  it('skips packages with publishConfig but no publishConfig.imports', () => {
+    const filePath = writePackageJson({
+      name: 'test-pkg',
+      imports: { '#foo': './src/foo.js' },
+      publishConfig: { access: 'public' },
+    });
+    const { result, warnings } = validatePackage(filePath);
+    expect(result).toBeNull();
+    expect(warnings).toEqual([]);
+  });
+
+  it('warns when publishConfig.imports exists but imports does not', () => {
+    const filePath = writePackageJson({
+      name: 'test-pkg',
+      publishConfig: {
+        imports: { '#foo': './build/src/foo.js' },
+      },
+    });
+    const { result, warnings } = validatePackage(filePath);
+    expect(result).toBeNull();
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('orphaned');
+  });
+
+  it('returns no errors when publishConfig.imports matches', () => {
+    const filePath = writePackageJson({
+      name: 'test-pkg',
+      imports: {
+        '#foo': './src/foo.js',
+        '#bar': './src/bar.ts',
+      },
+      publishConfig: {
+        imports: {
+          '#foo': './build/src/foo.js',
+          '#bar': './build/src/bar.js',
+        },
+      },
+    });
+    const { result } = validatePackage(filePath);
+    expect(result).not.toBeNull();
+    expect(result!.missingKeys).toEqual([]);
+    expect(result!.extraKeys).toEqual([]);
+    expect(result!.wrongValues).toEqual([]);
+  });
+
+  it('detects missing keys in publishConfig.imports', () => {
+    const filePath = writePackageJson({
+      name: 'test-pkg',
+      imports: {
+        '#foo': './src/foo.js',
+        '#bar': './src/bar.ts',
+      },
+      publishConfig: {
+        imports: {
+          '#foo': './build/src/foo.js',
+        },
+      },
+    });
+    const { result } = validatePackage(filePath);
+    expect(result!.missingKeys).toEqual(['#bar']);
+  });
+
+  it('detects extra keys in publishConfig.imports', () => {
+    const filePath = writePackageJson({
+      name: 'test-pkg',
+      imports: {
+        '#foo': './src/foo.js',
+      },
+      publishConfig: {
+        imports: {
+          '#foo': './build/src/foo.js',
+          '#orphan': './build/src/orphan.js',
+        },
+      },
+    });
+    const { result } = validatePackage(filePath);
+    expect(result!.extraKeys).toEqual(['#orphan']);
+  });
+
+  it('detects wrong values in publishConfig.imports', () => {
+    const filePath = writePackageJson({
+      name: 'test-pkg',
+      imports: {
+        '#foo': './src/foo.ts',
+      },
+      publishConfig: {
+        imports: {
+          '#foo': './src/foo.ts',
+        },
+      },
+    });
+    const { result } = validatePackage(filePath);
+    expect(result!.wrongValues).toEqual([
+      { key: '#foo', expected: './build/src/foo.js', actual: './src/foo.ts' },
+    ]);
+  });
+});

bin/package-browser

@@ -4,20 +4,30 @@ ROOT=`dirname $0`
 
 cd "$ROOT/.."
 
-echo "Updating translations..."
-if ! [ -d packages/desktop-client/locale ]; then
-    git clone https://github.com/actualbudget/translations packages/desktop-client/locale
+SKIP_TRANSLATIONS=false
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --skip-translations)
+      SKIP_TRANSLATIONS=true
+      shift
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [ "$SKIP_TRANSLATIONS" = false ]; then
+  echo "Updating translations..."
+  if ! [ -d packages/desktop-client/locale ]; then
+      git clone https://github.com/actualbudget/translations packages/desktop-client/locale
+  fi
+  pushd packages/desktop-client/locale > /dev/null
+  git checkout .
+  git pull
+  popd > /dev/null
+  packages/desktop-client/bin/remove-untranslated-languages
 fi
-pushd packages/desktop-client/locale > /dev/null
-git checkout .
-git pull
-popd > /dev/null
-packages/desktop-client/bin/remove-untranslated-languages
 
-export NODE_OPTIONS="--max-old-space-size=4096"
-
-yarn workspace plugins-service build
-yarn workspace @actual-app/core build:browser
-yarn workspace @actual-app/web build:browser
-
-echo "packages/desktop-client/build"
+lage build:browser --to=@actual-app/web

bin/package-electron

@@ -51,13 +51,13 @@ fi
 
 export NODE_OPTIONS="--max-old-space-size=4096"
 
+yarn workspace @actual-app/crdt build
 yarn workspace plugins-service build
 yarn workspace @actual-app/core build:node
 yarn workspace @actual-app/web build --mode=desktop # electron specific build
 
 # required for running the sync-server server
-yarn workspace @actual-app/core build:browser
-yarn workspace @actual-app/web build:browser
+yarn build:browser
 yarn workspace @actual-app/sync-server build
 
 # Emit @actual-app/core declarations so desktop-electron (which includes typings/window.ts) can build

bin/run-vrt

@@ -28,5 +28,5 @@ echo "Running VRT tests with the following parameters:"
 echo "E2E_START_URL: $E2E_START_URL"
 echo "VRT_ARGS: $VRT_ARGS"
 
-MSYS_NO_PATHCONV=1 docker run --rm --network host -v "$(pwd)":/work/ -w /work/ -it mcr.microsoft.com/playwright:v1.58.2-jammy /bin/bash \
+MSYS_NO_PATHCONV=1 docker run --rm --network host -v "$(pwd)":/work/ -w /work/ -it mcr.microsoft.com/playwright:v1.59.1-jammy /bin/bash \
   -c "E2E_START_URL=$E2E_START_URL yarn vrt $VRT_ARGS"

bin/validate-publish-imports.ts

@@ -0,0 +1,216 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Derives publishConfig.imports from imports by:
+ * 1. Prepending ./build/ to each value path
+ * 2. Replacing .ts/.tsx extensions with .js
+ */
+export function derivePublishImports(
+  imports: Record<string, string | object>,
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(imports)) {
+    if (typeof value !== 'string') {
+      throw new Error(
+        `Unsupported imports target for "${key}". Expected a string path.`,
+      );
+    }
+    const withBuildPrefix = value.replace(/^\.\//, './build/');
+    const withJsExtension = withBuildPrefix.replace(/\.tsx?$/, '.js');
+    result[key] = withJsExtension;
+  }
+  return result;
+}
+
+export type ValidationResult = {
+  packagePath: string;
+  packageName: string;
+  missingKeys: string[];
+  extraKeys: string[];
+  wrongValues: Array<{ key: string; expected: string; actual: string }>;
+};
+
+/**
+ * Validates publishConfig.imports against imports for a single package.json.
+ * Returns null if the package should be skipped (no publishConfig.imports).
+ * Returns a ValidationResult if the package has both fields.
+ */
+export function validatePackage(packageJsonPath: string): {
+  result: ValidationResult | null;
+  warnings: string[];
+} {
+  const warnings: string[] = [];
+  const content = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+  const packageName: string = content.name ?? packageJsonPath;
+
+  const imports: Record<string, string | object> | undefined = content.imports;
+  const publishImports: Record<string, string> | undefined =
+    content.publishConfig?.imports;
+
+  // No publishConfig.imports → skip
+  if (!publishImports) {
+    return { result: null, warnings };
+  }
+
+  // Has publishConfig.imports but no imports → warn
+  if (!imports) {
+    warnings.push(
+      `${packageName}: orphaned publishConfig.imports (no imports field)`,
+    );
+    return { result: null, warnings };
+  }
+
+  const expected = derivePublishImports(imports);
+  const expectedKeys = new Set(Object.keys(expected));
+  const actualKeys = new Set(Object.keys(publishImports));
+
+  const missingKeys = [...expectedKeys].filter(k => !actualKeys.has(k));
+  const extraKeys = [...actualKeys].filter(k => !expectedKeys.has(k));
+  const wrongValues: ValidationResult['wrongValues'] = [];
+
+  for (const key of expectedKeys) {
+    if (actualKeys.has(key) && publishImports[key] !== expected[key]) {
+      wrongValues.push({
+        key,
+        expected: expected[key],
+        actual: publishImports[key],
+      });
+    }
+  }
+
+  return {
+    result: {
+      packagePath: packageJsonPath,
+      packageName,
+      missingKeys,
+      extraKeys,
+      wrongValues,
+    },
+    warnings,
+  };
+}
+
+export function fixPackage(packageJsonPath: string): boolean {
+  const raw = fs.readFileSync(packageJsonPath, 'utf-8');
+  const content = JSON.parse(raw);
+
+  if (!content.imports || !content.publishConfig?.imports) {
+    return false;
+  }
+
+  const expected = derivePublishImports(content.imports);
+
+  // Check if already correct
+  if (
+    JSON.stringify(content.publishConfig.imports) === JSON.stringify(expected)
+  ) {
+    return false;
+  }
+
+  content.publishConfig.imports = expected;
+  fs.writeFileSync(packageJsonPath, JSON.stringify(content, null, 2) + '\n');
+  return true;
+}
+
+function findPackageJsonFiles(): string[] {
+  const packagesDir = path.resolve(__dirname, '..', 'packages');
+  const entries = fs.readdirSync(packagesDir, { withFileTypes: true });
+  const results: string[] = [];
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const pkgPath = path.join(packagesDir, entry.name, 'package.json');
+      if (fs.existsSync(pkgPath)) {
+        results.push(pkgPath);
+      }
+    }
+  }
+  return results;
+}
+
+function resolvePackageJsonPaths(filePaths: string[]): string[] {
+  const packagesRoot = path.resolve(__dirname, '..', 'packages');
+  const seen = new Set<string>();
+  for (const filePath of filePaths) {
+    const resolvedPath = path.resolve(filePath);
+    let dir = path.dirname(resolvedPath);
+    while (dir.startsWith(packagesRoot + path.sep)) {
+      const candidate = path.join(dir, 'package.json');
+      if (
+        fs.existsSync(candidate) &&
+        candidate.startsWith(packagesRoot + path.sep)
+      ) {
+        seen.add(candidate);
+        break;
+      }
+      dir = path.dirname(dir);
+    }
+  }
+  return [...seen];
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const fixMode = args.includes('--fix');
+  const filePaths = args.filter(arg => !arg.startsWith('--'));
+
+  const packageJsonFiles =
+    filePaths.length > 0
+      ? resolvePackageJsonPaths(filePaths)
+      : findPackageJsonFiles();
+
+  let hasErrors = false;
+  const allWarnings: string[] = [];
+
+  for (const pkgPath of packageJsonFiles) {
+    if (fixMode) {
+      const fixed = fixPackage(pkgPath);
+      if (fixed) {
+        const name = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).name;
+        console.log(`Fixed publishConfig.imports in ${name}`);
+      }
+    } else {
+      const { result, warnings } = validatePackage(pkgPath);
+      allWarnings.push(...warnings);
+
+      if (result) {
+        const hasIssues =
+          result.missingKeys.length > 0 ||
+          result.extraKeys.length > 0 ||
+          result.wrongValues.length > 0;
+
+        if (hasIssues) {
+          hasErrors = true;
+          console.error(`\n${result.packageName}:`);
+
+          for (const key of result.missingKeys) {
+            console.error(`  Missing key: ${key}`);
+          }
+          for (const key of result.extraKeys) {
+            console.error(`  Extra key: ${key}`);
+          }
+          for (const { key, expected, actual } of result.wrongValues) {
+            console.error(`  Wrong value for ${key}:`);
+            console.error(`    expected: ${expected}`);
+            console.error(`    actual:   ${actual}`);
+          }
+        }
+      }
+    }
+  }
+
+  for (const warning of allWarnings) {
+    console.warn(`Warning: ${warning}`);
+  }
+
+  if (hasErrors) {
+    console.error(
+      '\npublishConfig.imports is out of sync. Run with --fix to auto-fix.',
+    );
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  main();
+}

bin/vitest.config.mts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    include: ['__tests__/**/*.test.ts'],
+    environment: 'node',
+  },
+});

lage.config.js

@@ -1,3 +1,5 @@
+const BUILD_OUTPUT_GLOBS = ['lib-dist/**', 'dist/**', 'build/**', '@types/**'];
+
 /** @type {import('lage').ConfigOptions} */
 module.exports = {
   pipeline: {
@@ -20,14 +22,22 @@ module.exports = {
       dependsOn: ['^build'],
       cache: true,
       options: {
-        outputGlob: ['lib-dist/**', 'dist/**', 'build/**'],
+        outputGlob: BUILD_OUTPUT_GLOBS,
       },
     },
+    // Not cached: the script stages files into public/ and build-stats/ that
+    // fall outside BUILD_OUTPUT_GLOBS, so a cache hit would skip the side
+    // effects.
+    'build:browser': {
+      type: 'npmScript',
+      dependsOn: ['^build'],
+      cache: false,
+    },
   },
   cacheOptions: {
     cacheStorageConfig: {
       provider: 'local',
-      outputGlob: ['lib-dist/**', 'dist/**', 'build/**'],
+      outputGlob: BUILD_OUTPUT_GLOBS,
     },
   },
   npmClient: 'yarn',

package.json

@@ -24,23 +24,21 @@
     "start:server-dev": "NODE_ENV=development BROWSER_OPEN=localhost:5006 yarn npm-run-all --parallel 'start:server-monitor' 'start'",
     "start:desktop": "yarn desktop-dependencies && npm-run-all --parallel 'start:desktop-*'",
     "start:docs": "yarn workspace docs start",
-    "desktop-dependencies": "npm-run-all --parallel rebuild-electron build:browser-backend build:plugins-service",
+    "desktop-dependencies": "npm-run-all --parallel rebuild-electron build:plugins-service",
     "start:desktop-node": "yarn workspace @actual-app/core watch:node",
     "start:desktop-client": "yarn workspace @actual-app/web watch",
     "start:desktop-server-client": "yarn workspace @actual-app/web build:browser",
     "start:desktop-electron": "yarn workspace desktop-electron watch",
-    "start:browser": "yarn workspace plugins-service build-dev && npm-run-all --parallel 'start:browser-*'",
+    "start:browser": "npm-run-all --parallel 'start:browser-*' 'start:service-plugins'",
     "start:service-plugins": "yarn workspace plugins-service watch",
-    "start:browser-backend": "yarn workspace @actual-app/core watch:browser",
     "start:browser-frontend": "yarn workspace @actual-app/web start:browser",
     "start:storybook": "yarn workspace @actual-app/components start:storybook",
     "build": "lage build",
-    "build:browser-backend": "yarn workspace @actual-app/core build:browser",
     "build:server": "yarn build:browser && yarn workspace @actual-app/sync-server build",
     "build:browser": "./bin/package-browser",
     "build:desktop": "./bin/package-electron",
     "build:plugins-service": "yarn workspace plugins-service build",
-    "build:api": "yarn workspace @actual-app/api build",
+    "build:api": "yarn build --scope=@actual-app/api",
     "build:cli": "yarn build --scope=@actual-app/cli",
     "build:docs": "yarn workspace docs build",
     "build:storybook": "yarn workspace @actual-app/components build:storybook",
@@ -54,38 +52,40 @@
     "playwright": "yarn workspace @actual-app/web run playwright",
     "vrt": "yarn workspace @actual-app/web run vrt",
     "vrt:docker": "./bin/run-vrt",
-    "rebuild-electron": "./node_modules/.bin/electron-rebuild -m ./packages/loot-core",
+    "rebuild-electron": "./node_modules/.bin/electron-rebuild -f -o better-sqlite3,bcrypt",
     "rebuild-node": "yarn workspace @actual-app/core rebuild",
     "lint": "oxfmt --check . && oxlint --type-aware --quiet",
     "lint:fix": "oxfmt . && oxlint --fix --type-aware --quiet",
     "install:server": "yarn workspaces focus @actual-app/sync-server --production",
     "constraints": "yarn constraints",
     "typecheck": "tsgo -p tsconfig.root.json --noEmit && lage typecheck",
+    "check:tsconfig-references": "workspaces-to-typescript-project-references --check",
+    "sync:tsconfig-references": "workspaces-to-typescript-project-references",
     "prepare": "husky"
   },
   "devDependencies": {
+    "@monorepo-utils/workspaces-to-typescript-project-references": "^2.10.3",
     "@octokit/rest": "^22.0.1",
-    "@types/node": "^22.19.15",
+    "@types/node": "^22.19.17",
     "@types/prompts": "^2.4.9",
-    "@typescript/native-preview": "^7.0.0-dev.20260309.1",
+    "@typescript/native-preview": "beta",
     "@yarnpkg/types": "^4.0.1",
-    "cross-env": "^10.1.0",
-    "eslint": "^9.39.3",
-    "eslint-plugin-perfectionist": "^5.6.0",
+    "eslint": "^10.2.0",
+    "eslint-plugin-perfectionist": "^5.8.0",
     "eslint-plugin-typescript-paths": "^0.0.33",
-    "html-to-image": "^1.11.13",
     "husky": "^9.1.7",
-    "lage": "^2.14.19",
-    "lint-staged": "^16.3.2",
-    "minimatch": "^10.2.4",
+    "lage": "^2.15.5",
+    "lint-staged": "^16.4.0",
+    "minimatch": "^10.2.5",
     "npm-run-all": "^4.1.5",
-    "oxfmt": "^0.32.0",
-    "oxlint": "^1.51.0",
-    "oxlint-tsgolint": "^0.13.0",
+    "oxfmt": "^0.44.0",
+    "oxlint": "^1.59.0",
+    "oxlint-tsgolint": "^0.20.0",
     "p-limit": "^7.3.0",
     "prompts": "^2.4.2",
     "ts-node": "^10.9.2",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
   },
   "resolutions": {
     "adm-zip": "patch:adm-zip@npm%3A0.5.16#~/.yarn/patches/adm-zip-npm-0.5.16-4556fea098.patch",
@@ -99,6 +99,10 @@
     "socks": ">=2.8.3"
   },
   "lint-staged": {
+    "packages/*/{package.json,tsconfig.json}": [
+      "ts-node ./bin/validate-publish-imports.ts --fix",
+      "yarn sync:tsconfig-references"
+    ],
     "*.{js,mjs,jsx,ts,tsx,md,json,yml,yaml}": [
       "oxfmt --no-error-on-unmatched-pattern"
     ],
@@ -114,5 +118,5 @@
     "node": ">=22",
     "yarn": "^4.9.1"
   },
-  "packageManager": "yarn@4.10.3"
+  "packageManager": "yarn@4.13.0"
 }

packages/api/README.md

@@ -3,3 +3,7 @@ npm install @actual-app/api
 ```
 
 View docs here: https://actualbudget.org/docs/api/
+
+## TypeScript
+
+`@actual-app/api` publishes TypeScript declarations. Consumers using TypeScript must set `moduleResolution` to `"bundler"`, `"nodenext"`, or `"node16"` in their `tsconfig.json`. Legacy `"node"` / `"node10"` / `"classic"` resolution is not supported in strict mode — the published declarations rely on package.json `exports` conditions that older resolvers don't honor.

packages/api/app/query.js

@@ -1,5 +1,5 @@
 class Query {
-  /** @type {import('loot-core/shared/query').QueryState} */
+  /** @type {import('@actual-app/core/shared/query').QueryState} */
   state;
 
   constructor(state) {

packages/api/methods.test.ts

@@ -1,12 +1,16 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
 
+import type { RuleEntity } from '@actual-app/core/types/models';
 import { vi } from 'vitest';
 
-import type { RuleEntity } from '@actual-app/core/types/models';
-
 import * as api from './index';
 
+declare global {
+  var IS_TESTING: boolean;
+  var currentMonth: string | null;
+}
+
 // In tests we run from source; loot-core's API fs uses __dirname (for the built dist/).
 // Mock the fs so path constants point at loot-core package root where migrations live.
 vi.mock(

packages/api/models.ts

@@ -0,0 +1 @@
+export type * from '@actual-app/core/server/api-models';

packages/api/package.json

@@ -1,11 +1,18 @@
 {
   "name": "@actual-app/api",
-  "version": "26.4.0",
+  "version": "26.5.0",
   "description": "An API for Actual",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/actualbudget/actual.git",
+    "directory": "packages/api"
+  },
   "files": [
     "@types",
-    "dist"
+    "dist",
+    "!@types/**/*.test.d.ts",
+    "!@types/**/*.test.d.ts.map"
   ],
   "main": "dist/index.js",
   "types": "@types/index.d.ts",
@@ -14,6 +21,11 @@
       "types": "./@types/index.d.ts",
       "development": "./index.ts",
       "default": "./dist/index.js"
+    },
+    "./models": {
+      "types": "./@types/models.d.ts",
+      "development": "./models.ts",
+      "default": "./dist/models.js"
     }
   },
   "publishConfig": {
@@ -21,29 +33,31 @@
       ".": {
         "types": "./@types/index.d.ts",
         "default": "./dist/index.js"
+      },
+      "./models": {
+        "types": "./@types/models.d.ts",
+        "default": "./dist/models.js"
       }
     }
   },
   "scripts": {
-    "build": "vite build",
+    "build": "vite build && tsgo --emitDeclarationOnly",
     "test": "vitest --run",
     "typecheck": "tsgo -b && tsc-strict"
   },
   "dependencies": {
     "@actual-app/core": "workspace:*",
     "@actual-app/crdt": "workspace:*",
-    "better-sqlite3": "^12.6.2",
-    "compare-versions": "^6.1.1",
-    "uuid": "^13.0.0"
+    "better-sqlite3": "^12.8.0",
+    "compare-versions": "^6.1.1"
   },
   "devDependencies": {
-    "@typescript/native-preview": "^7.0.0-dev.20260309.1",
-    "rollup-plugin-visualizer": "^6.0.11",
+    "@typescript/native-preview": "beta",
+    "rollup-plugin-visualizer": "^7.0.1",
     "typescript-strict-plugin": "^2.4.4",
     "vite": "^8.0.5",
-    "vite-plugin-dts": "^4.5.4",
     "vite-plugin-peggy-loader": "^2.0.1",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.2"
   },
   "engines": {
     "node": ">=20"

packages/api/tsconfig.json

@@ -15,9 +15,27 @@
     "rootDir": ".",
     "declarationDir": "@types",
     "tsBuildInfoFile": "dist/.tsbuildinfo",
-    "plugins": [{ "name": "typescript-strict-plugin", "paths": ["."] }]
+    "plugins": [
+      {
+        "name": "typescript-strict-plugin",
+        "paths": ["."]
+      }
+    ]
   },
-  "references": [{ "path": "../crdt" }, { "path": "../loot-core" }],
+  "references": [
+    {
+      "path": "../loot-core"
+    },
+    {
+      "path": "../crdt"
+    }
+  ],
   "include": ["."],
-  "exclude": ["**/node_modules/*", "dist", "@types", "*.test.ts", "*.config.ts"]
+  "exclude": [
+    "**/node_modules/*",
+    "dist",
+    "@types",
+    "*.config.ts",
+    "*.config.mts"
+  ]
 }

packages/api/vite.config.mts

@@ -3,7 +3,6 @@ import path from 'path';
 
 import { visualizer } from 'rollup-plugin-visualizer';
 import { defineConfig } from 'vite';
-import dts from 'vite-plugin-dts';
 import peggyLoader from 'vite-plugin-peggy-loader';
 
 const lootCoreRoot = path.resolve(__dirname, '../loot-core');
@@ -67,25 +66,22 @@ export default defineConfig({
     emptyOutDir: true,
     sourcemap: true,
     lib: {
-      entry: path.resolve(__dirname, 'index.ts'),
+      entry: {
+        index: path.resolve(__dirname, 'index.ts'),
+        models: path.resolve(__dirname, 'models.ts'),
+      },
       formats: ['cjs'],
-      fileName: () => 'index.js',
+      fileName: (_format, entryName) => `${entryName}.js`,
     },
   },
   plugins: [
     cleanOutputDirs(),
     peggyLoader(),
-    dts({
-      tsconfigPath: path.resolve(__dirname, 'tsconfig.json'),
-      outDir: path.resolve(__dirname, '@types'),
-      rollupTypes: true,
-    }),
     copyMigrationsAndDefaultDb(),
     visualizer({ template: 'raw-data', filename: 'app/stats.json' }),
   ],
   resolve: {
     conditions: ['api'],
-    extensions: ['.api.ts', '.js', '.ts', '.tsx', '.json'],
   },
   test: {
     globals: true,

packages/ci-actions/bin/release-notes-generate.mjs

@@ -34,6 +34,7 @@ const apiResult = await fetch('https://api.github.com/graphql', {
               node {
                 number
                 headRefName
+                body
               }
             }
           }
@@ -53,8 +54,63 @@ await collapsedLog('API Response', apiResult);
 const prData = apiResult.data.repository.pullRequests.edges[0].node;
 
 const version = prData.headRefName.split('/')[1].replace(/^v/, '');
-const today = new Date().toISOString().slice(0, 10);
+const slug = version.replace(/\./g, '-');
 const author = process.env.GITHUB_ACTOR || 'TODO';
+const commitMessage = `Generate release notes for v${version}`;
+
+const releaseDateMatch = (prData.body || '').match(
+  /<!-- release-date:(\d{4}-\d{2}-\d{2}) -->/,
+);
+const releaseDate = releaseDateMatch ? releaseDateMatch[1] : 'TODO';
+
+const botName = 'github-actions[bot]';
+const botEmail = '41898282+github-actions[bot]@users.noreply.github.com';
+
+await exec(`git config user.name '${botName}'`);
+await exec(`git config user.email '${botEmail}'`);
+
+const AUTOGEN_MARKER = '<!-- release-notes:auto-generated -->';
+
+await group('Prepare branch', async () => {
+  if (process.env.GITHUB_HEAD_REF) {
+    await exec(`git fetch origin ${process.env.GITHUB_HEAD_REF}`, {
+      stdio: 'inherit',
+    });
+    await exec(`git checkout ${process.env.GITHUB_HEAD_REF}`, {
+      stdio: 'inherit',
+    });
+  }
+
+  // recover deleted release note files from previous generation commits
+  const baseRef = process.env.GITHUB_BASE_REF || 'master';
+  await exec(`git fetch origin ${baseRef}`, { stdio: 'inherit' });
+  const { stdout: mergeBase } = await exec(
+    `git merge-base HEAD origin/${baseRef}`,
+  );
+  const base = mergeBase.trim();
+  const { stdout: genLog } = await exec(
+    `git log --grep='${commitMessage}' --format=%H ${base}..HEAD`,
+  );
+  const genCommits = genLog.split('\n').filter(Boolean);
+  console.log(
+    `Reversing upcoming-release-notes deletions from ${genCommits.length} prior generation commit(s)`,
+  );
+  const tmpDir = process.env.RUNNER_TEMP || '/tmp';
+  for (const sha of genCommits) {
+    const patchPath = join(tmpDir, `revert-${sha}.patch`);
+    try {
+      await exec(
+        `git diff --diff-filter=D ${sha}~1..${sha} -- upcoming-release-notes > ${patchPath}`,
+      );
+      const { size } = await fs.stat(patchPath);
+      if (size > 0) {
+        await exec(`git apply -R --3way ${patchPath}`, { stdio: 'inherit' });
+      }
+    } finally {
+      await fs.unlink(patchPath).catch(() => undefined);
+    }
+  }
+});
 
 const { notesByCategory, files } = await parseReleaseNotes(
   'upcoming-release-notes',
@@ -70,15 +126,17 @@ if (files.length === 0) {
 
 const highlights = '- TODO: Add release highlights';
 
-await group('Generate blog post', async () => {
-  const slug = version.replace(/\./g, '-');
-  const filename = `${today}-release-${slug}.md`;
-  const blogPath = join('packages/docs/blog', filename);
+const blogPath = join(
+  'packages/docs/blog',
+  `${releaseDate}-release-${slug}.md`,
+);
+const releasesPath = 'packages/docs/docs/releases.md';
 
-  const blogContent = `---
+await group('Generate blog post', async () => {
+  const template = `---
 title: Release ${version}
 description: New release of Actual.
-date: ${today}T10:00
+date: ${releaseDate}T10:00
 slug: release-${version}
 tags: [announcement, release]
 hide_table_of_contents: false
@@ -89,69 +147,109 @@ ${highlights}
 
 <!--truncate-->
 
-**Docker Tag: v${version}**
+**Docker Tag: ${version}**
+
+${AUTOGEN_MARKER}
 
 ${categorizedNotes}
 `;
 
+  let blogContent;
+  try {
+    const existing = await fs.readFile(blogPath, 'utf-8');
+    const idx = existing.indexOf(AUTOGEN_MARKER);
+    if (idx === -1) {
+      console.log(
+        `WARNING: ${blogPath} missing ${AUTOGEN_MARKER}, rewriting from template`,
+      );
+      blogContent = template;
+    } else {
+      blogContent =
+        existing.slice(0, idx + AUTOGEN_MARKER.length) +
+        '\n' +
+        categorizedNotes +
+        '\n';
+    }
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+    blogContent = template;
+  }
+
   await fs.writeFile(blogPath, blogContent);
   console.log(`Wrote ${blogPath}`);
 });
 
 await group('Update releases.md', async () => {
-  const releasesPath = 'packages/docs/docs/releases.md';
   const existing = await fs.readFile(releasesPath, 'utf-8');
 
-  const newSection = `## ${version}
+  const sectionRe = new RegExp(
+    `(^|\\n)## ${escapeRegExp(version)}\\n[\\s\\S]*?(?=\\n## |$)`,
+  );
+  const match = existing.match(sectionRe);
 
-Release date: ${today}
+  let updated;
+  if (match) {
+    const section = match[0];
+    const idx = section.indexOf(AUTOGEN_MARKER);
+    if (idx === -1) {
+      console.log(
+        `WARNING: section for ${version} in ${releasesPath} missing ${AUTOGEN_MARKER}, leaving as-is`,
+      );
+      updated = existing;
+    } else {
+      const newSection =
+        section.slice(0, idx + AUTOGEN_MARKER.length) + '\n' + categorizedNotes;
+      updated = existing.replace(section, newSection);
+    }
+  } else {
+    const newSection = `## ${version}
+
+Release date: ${releaseDate}
 
 ${highlights}
 
-**Docker Tag: v${version}**
+**Docker Tag: ${version}**
+
+${AUTOGEN_MARKER}
 
 ${categorizedNotes}`;
-
-  const updated = existing.replace(
-    '# Release Notes\n',
-    `# Release Notes\n\n${newSection}\n`,
-  );
+    updated = existing.replace(
+      '# Release Notes\n',
+      `# Release Notes\n\n${newSection}\n`,
+    );
+  }
 
   await fs.writeFile(releasesPath, updated);
   console.log(`Updated ${releasesPath}`);
 });
 
 await group('Remove used release notes', async () => {
-  if (process.env.GITHUB_HEAD_REF) {
-    await exec(`git fetch origin ${process.env.GITHUB_HEAD_REF}`, {
-      stdio: 'inherit',
-    });
-    await exec(`git checkout ${process.env.GITHUB_HEAD_REF}`, {
-      stdio: 'inherit',
-    });
-  }
   await Promise.all(
     files.map(f => fs.unlink(join('upcoming-release-notes', f))),
   );
 });
 
+await group('Format generated files', async () => {
+  await exec(`yarn exec oxfmt ${blogPath} ${releasesPath}`, {
+    stdio: 'inherit',
+  });
+});
+
 await group('Commit and push', async () => {
   await exec(
     'git add upcoming-release-notes packages/docs/blog packages/docs/docs/releases.md',
     { stdio: 'inherit' },
   );
-  const name = 'github-actions[bot]';
-  const email = '41898282+github-actions[bot]@users.noreply.github.com';
-  await exec(`git commit -m 'Generate release notes for v${version}'`, {
-    stdio: 'inherit',
-    env: {
-      ...process.env,
-      GIT_AUTHOR_NAME: name,
-      GIT_COMMITTER_NAME: name,
-      GIT_AUTHOR_EMAIL: email,
-      GIT_COMMITTER_EMAIL: email,
-    },
-  });
+
+  try {
+    await exec('git diff --cached --quiet');
+    console.log('No changes to commit');
+    return;
+  } catch {
+    // there are staged changes
+  }
+
+  await exec(`git commit -m '${commitMessage}'`);
   await exec('git push origin', { stdio: 'inherit' });
 });
 
@@ -186,6 +284,10 @@ async function parseReleaseNotes(dir) {
   return { notesByCategory, files };
 }
 
+function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
 function formatNotes(notes) {
   return Object.entries(notes)
     .filter(([_, values]) => values.length > 0)

packages/ci-actions/package.json

@@ -8,11 +8,12 @@
     "typecheck": "tsgo -b"
   },
   "devDependencies": {
-    "@typescript/native-preview": "^7.0.0-dev.20260309.1",
+    "@octokit/rest": "^22.0.1",
+    "@typescript/native-preview": "beta",
     "extensionless": "^2.0.6",
     "gray-matter": "^4.0.3",
     "listify": "^1.0.3",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.2"
   },
   "extensionless": {
     "lookFor": [

packages/ci-actions/src/versions/get-next-package-version.ts

@@ -60,7 +60,7 @@ function resolveType(
     currentDate.getFullYear() === 2000 + versionYear &&
     currentDate.getMonth() + 1 === versionMonth;
 
-  if (inPatchMonth && currentDate.getDate() <= 25) {
+  if (inPatchMonth && currentDate.getDate() < 25) {
     return 'hotfix';
   }
 

packages/cli/README.md

@@ -43,13 +43,16 @@ Configuration is resolved in this order (highest priority first):
 
 ### Environment Variables
 
-| Variable               | Description                                   |
-| ---------------------- | --------------------------------------------- |
-| `ACTUAL_SERVER_URL`    | URL of the Actual sync server (required)      |
-| `ACTUAL_PASSWORD`      | Server password (required unless using token) |
-| `ACTUAL_SESSION_TOKEN` | Session token (alternative to password)       |
-| `ACTUAL_SYNC_ID`       | Budget Sync ID (required for most commands)   |
-| `ACTUAL_DATA_DIR`      | Local directory for cached budget data        |
+| Variable               | Description                                           |
+| ---------------------- | ----------------------------------------------------- |
+| `ACTUAL_SERVER_URL`    | URL of the Actual sync server (required)              |
+| `ACTUAL_PASSWORD`      | Server password (required unless using token)         |
+| `ACTUAL_SESSION_TOKEN` | Session token (alternative to password)               |
+| `ACTUAL_SYNC_ID`       | Budget Sync ID (required for most commands)           |
+| `ACTUAL_DATA_DIR`      | Local directory for cached budget data                |
+| `ACTUAL_CACHE_TTL`     | Cache TTL in seconds (default: 60)                    |
+| `ACTUAL_LOCK_TIMEOUT`  | Budget-dir lock wait timeout in seconds (default: 10) |
+| `ACTUAL_NO_LOCK`       | Set to `1` to disable budget-dir locking              |
 
 ### Config File
 
@@ -59,7 +62,10 @@ Create an `.actualrc.json` (or `.actualrc`, `.actualrc.yaml`, `actual.config.js`
 {
   "serverUrl": "http://localhost:5006",
   "password": "your-password",
-  "syncId": "1cfdbb80-6274-49bf-b0c2-737235a4c81f"
+  "syncId": "1cfdbb80-6274-49bf-b0c2-737235a4c81f",
+  "cacheTtl": 60,
+  "lockTimeout": 10,
+  "noLock": false
 }
 ```
 
@@ -74,6 +80,11 @@ Create an `.actualrc.json` (or `.actualrc`, `.actualrc.yaml`, `actual.config.js`
 | `--session-token <token>` | Session token                                   |
 | `--sync-id <id>`          | Budget Sync ID                                  |
 | `--data-dir <path>`       | Data directory                                  |
+| `--cache-ttl <seconds>`   | Cache TTL; `0` disables caching (default: 60)   |
+| `--refresh`               | Force a sync on this call, ignoring the cache   |
+| `--no-cache`              | Alias for `--refresh`                           |
+| `--lock-timeout <secs>`   | Lock wait timeout (default: 10)                 |
+| `--no-lock`               | Disable budget-dir locking (use with care)      |
 | `--format <format>`       | Output format: `json` (default), `table`, `csv` |
 | `--verbose`               | Show informational messages                     |
 
@@ -92,6 +103,7 @@ Create an `.actualrc.json` (or `.actualrc`, `.actualrc.yaml`, `actual.config.js`
 | `schedules`       | Manage scheduled transactions  |
 | `query`           | Run an ActualQL query          |
 | `server`          | Server utilities and lookups   |
+| `sync`            | Refresh or inspect local cache |
 
 Run `actual <command> --help` for subcommands and options.
 
@@ -135,22 +147,32 @@ All monetary amounts are **integer cents** when passed as input (flags, JSON):
 
 - **Split transactions:** When summing or counting transactions, filter `"is_parent": false` to avoid double-counting. A split parent holds the total amount, and its children hold the individual parts — including both would count the total twice.
 
-- **Avoid rapid sequential requests:** Each CLI invocation opens a new server connection. Running queries in a tight loop (e.g. one per month) may trigger rate limiting or authentication failures. Instead, fetch all data in a single query with a date range filter and process locally:
+- **Rapid sequential requests:** The CLI caches the budget locally (see [Caching](#caching)), so read-heavy scripts no longer need a single-query workaround by default. For very chatty scripts, run `actual sync` once and then use a long `--cache-ttl` for reads:
 
   ```bash
-  # Good: single query for the full year
-  actual query run --table transactions \
-    --filter '{"$and":[{"date":{"$gte":"2025-01-01"}},{"date":{"$lte":"2025-12-31"}}]}' \
-    --limit 5000
-
-  # Bad: one query per month in a loop (may fail with auth errors)
-  for month in 01 02 03 ...; do actual query run ...; done
+  actual sync
+  actual --cache-ttl 3600 query run ...
+  actual --cache-ttl 3600 accounts list
   ```
 
 - **Uncategorized transactions:** `category.name` is `null` for transactions without a category. Account for this when filtering or grouping by category.
 
 - **No date sub-fields in AQL:** `date.month`, `date.year`, etc. are not supported as query fields. To group by month, fetch raw transactions with a date range filter and aggregate locally in a script.
 
+## Caching
+
+The CLI keeps a local copy of your budget so repeated commands don't hit the sync server on every call. Within the TTL (default `60` seconds), read commands (`list`, `balance`, `query run`, …) reuse the cached budget without a network round-trip. Write commands (`add`, `update`, `set-amount`, …) always sync with the server before and after the write.
+
+- `actual sync` — refresh the cache now.
+- `actual sync --status` — show how stale the local cache is.
+- `actual sync --clear` — delete the local cache; the next command re-downloads.
+- `--refresh` (or `--no-cache`) — force a sync on a single call.
+- `--cache-ttl <seconds>` — override the TTL for a single call (use `0` to disable caching).
+
+### Concurrency
+
+The CLI takes a shared lock for reads and an exclusive lock for writes on the per-budget cache directory. Many parallel reads are safe; writes serialize. If another CLI process is holding the lock, subsequent invocations wait up to `--lock-timeout` seconds (default `10`) before failing with an error. Pass `--no-lock` to opt out in trusted single-process setups.
+
 ## Running Locally (Development)
 
 If you're working on the CLI within the monorepo:

packages/cli/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@actual-app/cli",
-  "version": "26.4.0",
+  "version": "26.5.0",
   "description": "CLI for Actual Budget",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/actualbudget/actual.git",
+    "directory": "packages/cli"
+  },
   "bin": {
     "actual": "./dist/cli.js",
     "actual-cli": "./dist/cli.js"
@@ -11,6 +16,16 @@
     "dist"
   ],
   "type": "module",
+  "imports": {
+    "#cache": "./src/cache.ts",
+    "#commands/*": "./src/commands/*.ts",
+    "#config": "./src/config.ts",
+    "#connection": "./src/connection.ts",
+    "#input": "./src/input.ts",
+    "#lock": "./src/lock.ts",
+    "#output": "./src/output.ts",
+    "#utils": "./src/utils.ts"
+  },
   "scripts": {
     "build": "vite build",
     "test": "vitest --run",
@@ -19,15 +34,17 @@
   "dependencies": {
     "@actual-app/api": "workspace:*",
     "cli-table3": "^0.6.5",
-    "commander": "^13.0.0",
-    "cosmiconfig": "^9.0.0"
+    "commander": "^14.0.3",
+    "cosmiconfig": "^9.0.1",
+    "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {
-    "@types/node": "^22.19.15",
-    "@typescript/native-preview": "^7.0.0-dev.20260309.1",
-    "rollup-plugin-visualizer": "^6.0.11",
+    "@types/node": "^22.19.17",
+    "@types/proper-lockfile": "^4",
+    "@typescript/native-preview": "beta",
+    "rollup-plugin-visualizer": "^7.0.1",
     "vite": "^8.0.5",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.2"
   },
   "engines": {
     "node": ">=22"

packages/cli/src/cache.test.ts

@@ -0,0 +1,206 @@
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  CACHE_FILE_NAME,
+  decideSyncAction,
+  readCacheState,
+  writeCacheState,
+} from './cache';
+
+describe('readCacheState', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'actual-cli-cache-'));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('returns null when the file does not exist', () => {
+    expect(readCacheState(dir)).toBeNull();
+  });
+
+  it('returns null when the file is corrupt', () => {
+    writeFileSync(join(dir, CACHE_FILE_NAME), 'not json');
+    expect(readCacheState(dir)).toBeNull();
+  });
+
+  it('returns null when the file has the wrong version', () => {
+    writeFileSync(
+      join(dir, CACHE_FILE_NAME),
+      JSON.stringify({
+        version: 999,
+        syncId: 'a',
+        budgetId: 'b',
+        serverUrl: 'c',
+        lastSyncedAt: 1,
+        lastDownloadedAt: 1,
+      }),
+    );
+    expect(readCacheState(dir)).toBeNull();
+  });
+
+  it('returns the parsed state when the file is valid', () => {
+    writeFileSync(
+      join(dir, CACHE_FILE_NAME),
+      JSON.stringify({
+        version: 1,
+        syncId: 'a',
+        budgetId: 'b',
+        serverUrl: 'c',
+        lastSyncedAt: 1234,
+        lastDownloadedAt: 5678,
+      }),
+    );
+    expect(readCacheState(dir)).toEqual({
+      version: 1,
+      syncId: 'a',
+      budgetId: 'b',
+      serverUrl: 'c',
+      lastSyncedAt: 1234,
+      lastDownloadedAt: 5678,
+    });
+  });
+});
+
+describe('writeCacheState', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'actual-cli-cache-'));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('writes the state to the cache file', () => {
+    writeCacheState(dir, {
+      version: 1,
+      syncId: 'a',
+      budgetId: 'b',
+      serverUrl: 'c',
+      lastSyncedAt: 1,
+      lastDownloadedAt: 1,
+    });
+    const raw = readFileSync(join(dir, CACHE_FILE_NAME), 'utf-8');
+    expect(JSON.parse(raw).syncId).toBe('a');
+  });
+
+  it('is atomic: removes the tmp file after rename', () => {
+    writeCacheState(dir, {
+      version: 1,
+      syncId: 'a',
+      budgetId: 'b',
+      serverUrl: 'c',
+      lastSyncedAt: 1,
+      lastDownloadedAt: 1,
+    });
+    expect(existsSync(join(dir, `${CACHE_FILE_NAME}.tmp`))).toBe(false);
+  });
+
+  it('does not throw when the filesystem refuses the write', () => {
+    // Force ENOTDIR by pointing writeCacheState at a path whose parent is a
+    // regular file — no OS-specific pseudo-filesystem semantics needed.
+    const file = join(dir, 'not-a-dir');
+    writeFileSync(file, '');
+    expect(() =>
+      writeCacheState(join(file, 'nested'), {
+        version: 1,
+        syncId: 'a',
+        budgetId: 'b',
+        serverUrl: 'c',
+        lastSyncedAt: 1,
+        lastDownloadedAt: 1,
+      }),
+    ).not.toThrow();
+  });
+});
+
+describe('decideSyncAction', () => {
+  const base = {
+    state: {
+      version: 1 as const,
+      syncId: 'sync-1',
+      budgetId: 'bud-1',
+      serverUrl: 'http://s',
+      lastSyncedAt: 1_000_000,
+      lastDownloadedAt: 1_000_000,
+    },
+    config: { syncId: 'sync-1', serverUrl: 'http://s' },
+    now: 1_000_000,
+    ttlMs: 60_000,
+    mutates: false,
+    refresh: false,
+    encrypted: false,
+  };
+
+  it('returns "download" when state is null', () => {
+    expect(decideSyncAction({ ...base, state: null }).action).toBe('download');
+  });
+
+  it('returns "download" when syncId changed', () => {
+    expect(
+      decideSyncAction({
+        ...base,
+        config: { ...base.config, syncId: 'other' },
+      }).action,
+    ).toBe('download');
+  });
+
+  it('returns "download" when serverUrl changed', () => {
+    expect(
+      decideSyncAction({
+        ...base,
+        config: { ...base.config, serverUrl: 'http://other' },
+      }).action,
+    ).toBe('download');
+  });
+
+  it('returns "skip" for a read within the TTL', () => {
+    expect(decideSyncAction({ ...base, now: 1_000_000 + 30_000 }).action).toBe(
+      'skip',
+    );
+  });
+
+  it('returns "sync" for a read past the TTL', () => {
+    expect(decideSyncAction({ ...base, now: 1_000_000 + 61_000 }).action).toBe(
+      'sync',
+    );
+  });
+
+  it('returns "sync" for a write even when fresh', () => {
+    expect(decideSyncAction({ ...base, mutates: true }).action).toBe('sync');
+  });
+
+  it('returns "sync" when refresh is true', () => {
+    expect(decideSyncAction({ ...base, refresh: true }).action).toBe('sync');
+  });
+
+  it('returns "sync" when ttlMs is 0', () => {
+    expect(decideSyncAction({ ...base, ttlMs: 0 }).action).toBe('sync');
+  });
+
+  it('returns "sync" for encrypted budgets within the TTL', () => {
+    expect(decideSyncAction({ ...base, encrypted: true }).action).toBe('sync');
+  });
+
+  it('treats clock skew (negative age) as stale', () => {
+    expect(decideSyncAction({ ...base, now: 999_999 }).action).toBe('sync');
+  });
+
+  it('carries cached state on non-download actions', () => {
+    const decision = decideSyncAction({ ...base, mutates: true });
+    expect(decision).toEqual({ action: 'sync', state: base.state });
+  });
+});

packages/cli/src/cache.ts

@@ -0,0 +1,107 @@
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { isRecord } from './utils';
+
+export const CACHE_FILE_NAME = 'state.json';
+export const CACHE_VERSION = 1;
+export const META_ROOT_DIR = '.actual-cli';
+
+export type CacheState = {
+  version: typeof CACHE_VERSION;
+  syncId: string;
+  budgetId: string;
+  serverUrl: string;
+  lastSyncedAt: number;
+  lastDownloadedAt: number;
+};
+
+export function getMetaDir(dataDir: string, syncId: string): string {
+  return join(dataDir, META_ROOT_DIR, syncId);
+}
+
+function cachePath(metaDir: string): string {
+  return join(metaDir, CACHE_FILE_NAME);
+}
+
+function isCacheState(value: unknown): value is CacheState {
+  if (!isRecord(value)) return false;
+  return (
+    value.version === CACHE_VERSION &&
+    typeof value.syncId === 'string' &&
+    typeof value.budgetId === 'string' &&
+    typeof value.serverUrl === 'string' &&
+    typeof value.lastSyncedAt === 'number' &&
+    typeof value.lastDownloadedAt === 'number'
+  );
+}
+
+export function readCacheState(metaDir: string): CacheState | null {
+  let raw: string;
+  try {
+    raw = readFileSync(cachePath(metaDir), 'utf-8');
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  return isCacheState(parsed) ? parsed : null;
+}
+
+export function writeCacheState(metaDir: string, state: CacheState): void {
+  try {
+    mkdirSync(metaDir, { recursive: true });
+    const target = cachePath(metaDir);
+    // Unique tmp name per writer: concurrent shared-lock commands (encrypted
+    // budgets, --refresh, stale TTL) can both publish, and a shared tmp path
+    // lets the second writer's truncate destroy the first writer's bytes
+    // before either renames into place.
+    const tmp = `${target}.${process.pid}-${randomBytes(4).toString('hex')}.tmp`;
+    writeFileSync(tmp, JSON.stringify(state));
+    renameSync(tmp, target);
+  } catch {
+    // Cache persistence is best-effort. A read-only or unreachable dir must
+    // not crash the CLI; the next invocation simply won't find a cache.
+  }
+}
+
+export type SyncDecision =
+  | { action: 'download' }
+  | { action: 'skip'; state: CacheState }
+  | { action: 'sync'; state: CacheState };
+
+export type DecideSyncArgs = {
+  state: CacheState | null;
+  config: { syncId: string; serverUrl: string };
+  now: number;
+  ttlMs: number;
+  mutates: boolean;
+  refresh: boolean;
+  encrypted: boolean;
+};
+
+export function decideSyncAction({
+  state,
+  config,
+  now,
+  ttlMs,
+  mutates,
+  refresh,
+  encrypted,
+}: DecideSyncArgs): SyncDecision {
+  if (state === null) return { action: 'download' };
+  if (state.syncId !== config.syncId) return { action: 'download' };
+  if (state.serverUrl !== config.serverUrl) return { action: 'download' };
+  if (mutates || refresh || ttlMs === 0 || encrypted) {
+    return { action: 'sync', state };
+  }
+  const age = now - state.lastSyncedAt;
+  if (age < 0) return { action: 'sync', state };
+  if (age < ttlMs) return { action: 'skip', state };
+  return { action: 'sync', state };
+}

packages/cli/src/commands/accounts.test.ts

@@ -1,7 +1,7 @@
 import * as api from '@actual-app/api';
 import { Command } from 'commander';
 
-import { printOutput } from '../output';
+import { printOutput } from '#output';
 
 import { registerAccountsCommand } from './accounts';
 
@@ -15,11 +15,11 @@ vi.mock('@actual-app/api', () => ({
   getAccountBalance: vi.fn().mockResolvedValue(10000),
 }));
 
-vi.mock('../connection', () => ({
+vi.mock('#connection', () => ({
   withConnection: vi.fn((_opts, fn) => fn()),
 }));
 
-vi.mock('../output', () => ({
+vi.mock('#output', () => ({
   printOutput: vi.fn(),
 }));
 

packages/cli/src/commands/accounts.ts

@@ -1,9 +1,9 @@
 import * as api from '@actual-app/api';
 import type { Command } from 'commander';
 
-import { withConnection } from '../connection';
-import { printOutput } from '../output';
-import { parseBoolFlag, parseIntFlag } from '../utils';
+import { withConnection } from '#connection';
+import { printOutput } from '#output';
+import { parseBoolFlag, parseIntFlag } from '#utils';
 
 export function registerAccountsCommand(program: Command) {
   const accounts = program.command('accounts').description('Manage accounts');
@@ -14,26 +14,30 @@ export function registerAccountsCommand(program: Command) {
     .option('--include-closed', 'Include closed accounts', false)
     .action(async cmdOpts => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const allAccounts = await api.getAccounts();
-        const accounts = allAccounts.filter(
-          a => cmdOpts.includeClosed || !a.closed,
-        );
-        // Stable sort: on-budget first, off-budget second
-        // (preserves API sort_order within each group)
-        accounts.sort((a, b) => Number(a.offbudget) - Number(b.offbudget));
-        const balances = await Promise.all(
-          accounts.map(a => api.getAccountBalance(a.id)),
-        );
-        const output = accounts.map((a, i) => ({
-          id: a.id,
-          name: a.name,
-          offbudget: a.offbudget,
-          closed: a.closed,
-          balance: balances[i],
-        }));
-        printOutput(output, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const allAccounts = await api.getAccounts();
+          const accounts = allAccounts.filter(
+            a => cmdOpts.includeClosed || !a.closed,
+          );
+          // Stable sort: on-budget first, off-budget second
+          // (preserves API sort_order within each group)
+          accounts.sort((a, b) => Number(a.offbudget) - Number(b.offbudget));
+          const balances = await Promise.all(
+            accounts.map(a => api.getAccountBalance(a.id)),
+          );
+          const output = accounts.map((a, i) => ({
+            id: a.id,
+            name: a.name,
+            offbudget: a.offbudget,
+            closed: a.closed,
+            balance: balances[i],
+          }));
+          printOutput(output, opts.format);
+        },
+        { mutates: false },
+      );
     });
 
   accounts
@@ -49,13 +53,17 @@ export function registerAccountsCommand(program: Command) {
     .action(async cmdOpts => {
       const balance = parseIntFlag(cmdOpts.balance, '--balance');
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const id = await api.createAccount(
-          { name: cmdOpts.name, offbudget: cmdOpts.offbudget },
-          balance,
-        );
-        printOutput({ id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const id = await api.createAccount(
+            { name: cmdOpts.name, offbudget: cmdOpts.offbudget },
+            balance,
+          );
+          printOutput({ id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   accounts
@@ -81,10 +89,14 @@ export function registerAccountsCommand(program: Command) {
           'No update fields provided. Use --name or --offbudget.',
         );
       }
-      await withConnection(opts, async () => {
-        await api.updateAccount(id, fields);
-        printOutput({ success: true, id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.updateAccount(id, fields);
+          printOutput({ success: true, id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   accounts
@@ -100,14 +112,18 @@ export function registerAccountsCommand(program: Command) {
     )
     .action(async (id: string, cmdOpts) => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.closeAccount(
-          id,
-          cmdOpts.transferAccount,
-          cmdOpts.transferCategory,
-        );
-        printOutput({ success: true, id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.closeAccount(
+            id,
+            cmdOpts.transferAccount,
+            cmdOpts.transferCategory,
+          );
+          printOutput({ success: true, id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   accounts
@@ -115,10 +131,14 @@ export function registerAccountsCommand(program: Command) {
     .description('Reopen a closed account')
     .action(async (id: string) => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.reopenAccount(id);
-        printOutput({ success: true, id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.reopenAccount(id);
+          printOutput({ success: true, id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   accounts
@@ -126,10 +146,14 @@ export function registerAccountsCommand(program: Command) {
     .description('Delete an account')
     .action(async (id: string) => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.deleteAccount(id);
-        printOutput({ success: true, id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.deleteAccount(id);
+          printOutput({ success: true, id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   accounts
@@ -148,9 +172,13 @@ export function registerAccountsCommand(program: Command) {
         cutoff = cutoffDate;
       }
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const balance = await api.getAccountBalance(id, cutoff);
-        printOutput({ id, balance }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const balance = await api.getAccountBalance(id, cutoff);
+          printOutput({ id, balance }, opts.format);
+        },
+        { mutates: false },
+      );
     });
 }

packages/cli/src/commands/budgets.ts

@@ -1,10 +1,9 @@
 import * as api from '@actual-app/api';
 import type { Command } from 'commander';
 
-import { resolveConfig } from '../config';
-import { withConnection } from '../connection';
-import { printOutput } from '../output';
-import { parseBoolFlag, parseIntFlag } from '../utils';
+import { withConnection } from '#connection';
+import { printOutput } from '#output';
+import { parseBoolFlag, parseIntFlag } from '#utils';
 
 export function registerBudgetsCommand(program: Command) {
   const budgets = program.command('budgets').description('Manage budgets');
@@ -20,7 +19,7 @@ export function registerBudgetsCommand(program: Command) {
           const result = await api.getBudgets();
           printOutput(result, opts.format);
         },
-        { loadBudget: false },
+        { mutates: false, skipBudget: true },
       );
     });
 
@@ -30,40 +29,33 @@ export function registerBudgetsCommand(program: Command) {
     .option('--encryption-password <password>', 'Encryption password')
     .action(async (syncId: string, cmdOpts) => {
       const opts = program.opts();
-      const config = await resolveConfig(opts);
-      const password = config.encryptionPassword ?? cmdOpts.encryptionPassword;
       await withConnection(
         opts,
-        async () => {
+        async config => {
+          const password =
+            cmdOpts.encryptionPassword ?? config.encryptionPassword;
           await api.downloadBudget(syncId, {
             password,
           });
           printOutput({ success: true, syncId }, opts.format);
         },
-        { loadBudget: false },
+        { mutates: false, skipBudget: true },
       );
     });
 
-  budgets
-    .command('sync')
-    .description('Sync the current budget')
-    .action(async () => {
-      const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.sync();
-        printOutput({ success: true }, opts.format);
-      });
-    });
-
   budgets
     .command('months')
     .description('List available budget months')
     .action(async () => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const result = await api.getBudgetMonths();
-        printOutput(result, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const result = await api.getBudgetMonths();
+          printOutput(result, opts.format);
+        },
+        { mutates: false },
+      );
     });
 
   budgets
@@ -71,10 +63,14 @@ export function registerBudgetsCommand(program: Command) {
     .description('Get budget data for a specific month (YYYY-MM)')
     .action(async (month: string) => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const result = await api.getBudgetMonth(month);
-        printOutput(result, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const result = await api.getBudgetMonth(month);
+          printOutput(result, opts.format);
+        },
+        { mutates: false },
+      );
     });
 
   budgets
@@ -89,10 +85,14 @@ export function registerBudgetsCommand(program: Command) {
     .action(async cmdOpts => {
       const amount = parseIntFlag(cmdOpts.amount, '--amount');
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.setBudgetAmount(cmdOpts.month, cmdOpts.category, amount);
-        printOutput({ success: true }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.setBudgetAmount(cmdOpts.month, cmdOpts.category, amount);
+          printOutput({ success: true }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   budgets
@@ -104,10 +104,14 @@ export function registerBudgetsCommand(program: Command) {
     .action(async cmdOpts => {
       const flag = parseBoolFlag(cmdOpts.flag, '--flag');
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.setBudgetCarryover(cmdOpts.month, cmdOpts.category, flag);
-        printOutput({ success: true }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.setBudgetCarryover(cmdOpts.month, cmdOpts.category, flag);
+          printOutput({ success: true }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   budgets
@@ -121,10 +125,14 @@ export function registerBudgetsCommand(program: Command) {
     .action(async cmdOpts => {
       const parsedAmount = parseIntFlag(cmdOpts.amount, '--amount');
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.holdBudgetForNextMonth(cmdOpts.month, parsedAmount);
-        printOutput({ success: true }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.holdBudgetForNextMonth(cmdOpts.month, parsedAmount);
+          printOutput({ success: true }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   budgets
@@ -133,9 +141,13 @@ export function registerBudgetsCommand(program: Command) {
     .requiredOption('--month <month>', 'Budget month (YYYY-MM)')
     .action(async cmdOpts => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.resetBudgetHold(cmdOpts.month);
-        printOutput({ success: true }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.resetBudgetHold(cmdOpts.month);
+          printOutput({ success: true }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 }

packages/cli/src/commands/categories.ts

@@ -1,9 +1,9 @@
 import * as api from '@actual-app/api';
 import type { Command } from 'commander';
 
-import { withConnection } from '../connection';
-import { printOutput } from '../output';
-import { parseBoolFlag } from '../utils';
+import { withConnection } from '#connection';
+import { printOutput } from '#output';
+import { parseBoolFlag } from '#utils';
 
 export function registerCategoriesCommand(program: Command) {
   const categories = program
@@ -15,10 +15,14 @@ export function registerCategoriesCommand(program: Command) {
     .description('List all categories')
     .action(async () => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const result = await api.getCategories();
-        printOutput(result, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const result = await api.getCategories();
+          printOutput(result, opts.format);
+        },
+        { mutates: false },
+      );
     });
 
   categories
@@ -29,15 +33,19 @@ export function registerCategoriesCommand(program: Command) {
     .option('--is-income', 'Mark as income category', false)
     .action(async cmdOpts => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const id = await api.createCategory({
-          name: cmdOpts.name,
-          group_id: cmdOpts.groupId,
-          is_income: cmdOpts.isIncome,
-          hidden: false,
-        });
-        printOutput({ id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const id = await api.createCategory({
+            name: cmdOpts.name,
+            group_id: cmdOpts.groupId,
+            is_income: cmdOpts.isIncome,
+            hidden: false,
+          });
+          printOutput({ id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   categories
@@ -55,10 +63,14 @@ export function registerCategoriesCommand(program: Command) {
         throw new Error('No update fields provided. Use --name or --hidden.');
       }
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.updateCategory(id, fields);
-        printOutput({ success: true, id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.updateCategory(id, fields);
+          printOutput({ success: true, id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   categories
@@ -67,9 +79,13 @@ export function registerCategoriesCommand(program: Command) {
     .option('--transfer-to <id>', 'Transfer transactions to this category')
     .action(async (id: string, cmdOpts) => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.deleteCategory(id, cmdOpts.transferTo);
-        printOutput({ success: true, id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.deleteCategory(id, cmdOpts.transferTo);
+          printOutput({ success: true, id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 }

packages/cli/src/commands/category-groups.ts

@@ -1,9 +1,9 @@
 import * as api from '@actual-app/api';
 import type { Command } from 'commander';
 
-import { withConnection } from '../connection';
-import { printOutput } from '../output';
-import { parseBoolFlag } from '../utils';
+import { withConnection } from '#connection';
+import { printOutput } from '#output';
+import { parseBoolFlag } from '#utils';
 
 export function registerCategoryGroupsCommand(program: Command) {
   const groups = program
@@ -15,10 +15,14 @@ export function registerCategoryGroupsCommand(program: Command) {
     .description('List all category groups')
     .action(async () => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const result = await api.getCategoryGroups();
-        printOutput(result, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const result = await api.getCategoryGroups();
+          printOutput(result, opts.format);
+        },
+        { mutates: false },
+      );
     });
 
   groups
@@ -28,14 +32,18 @@ export function registerCategoryGroupsCommand(program: Command) {
     .option('--is-income', 'Mark as income group', false)
     .action(async cmdOpts => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const id = await api.createCategoryGroup({
-          name: cmdOpts.name,
-          is_income: cmdOpts.isIncome,
-          hidden: false,
-        });
-        printOutput({ id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const id = await api.createCategoryGroup({
+            name: cmdOpts.name,
+            is_income: cmdOpts.isIncome,
+            hidden: false,
+          });
+          printOutput({ id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   groups
@@ -53,10 +61,14 @@ export function registerCategoryGroupsCommand(program: Command) {
         throw new Error('No update fields provided. Use --name or --hidden.');
       }
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.updateCategoryGroup(id, fields);
-        printOutput({ success: true, id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.updateCategoryGroup(id, fields);
+          printOutput({ success: true, id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   groups
@@ -65,9 +77,13 @@ export function registerCategoryGroupsCommand(program: Command) {
     .option('--transfer-to <id>', 'Transfer transactions to this category ID')
     .action(async (id: string, cmdOpts) => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.deleteCategoryGroup(id, cmdOpts.transferTo);
-        printOutput({ success: true, id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.deleteCategoryGroup(id, cmdOpts.transferTo);
+          printOutput({ success: true, id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 }

packages/cli/src/commands/payees.ts

@@ -1,8 +1,8 @@
 import * as api from '@actual-app/api';
 import type { Command } from 'commander';
 
-import { withConnection } from '../connection';
-import { printOutput } from '../output';
+import { withConnection } from '#connection';
+import { printOutput } from '#output';
 
 export function registerPayeesCommand(program: Command) {
   const payees = program.command('payees').description('Manage payees');
@@ -12,10 +12,14 @@ export function registerPayeesCommand(program: Command) {
     .description('List all payees')
     .action(async () => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const result = await api.getPayees();
-        printOutput(result, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const result = await api.getPayees();
+          printOutput(result, opts.format);
+        },
+        { mutates: false },
+      );
     });
 
   payees
@@ -23,10 +27,14 @@ export function registerPayeesCommand(program: Command) {
     .description('List frequently used payees')
     .action(async () => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const result = await api.getCommonPayees();
-        printOutput(result, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const result = await api.getCommonPayees();
+          printOutput(result, opts.format);
+        },
+        { mutates: false },
+      );
     });
 
   payees
@@ -35,10 +43,14 @@ export function registerPayeesCommand(program: Command) {
     .requiredOption('--name <name>', 'Payee name')
     .action(async cmdOpts => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const id = await api.createPayee({ name: cmdOpts.name });
-        printOutput({ id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const id = await api.createPayee({ name: cmdOpts.name });
+          printOutput({ id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   payees
@@ -54,10 +66,14 @@ export function registerPayeesCommand(program: Command) {
         );
       }
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.updatePayee(id, fields);
-        printOutput({ success: true, id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.updatePayee(id, fields);
+          printOutput({ success: true, id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   payees
@@ -65,10 +81,14 @@ export function registerPayeesCommand(program: Command) {
     .description('Delete a payee')
     .action(async (id: string) => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.deletePayee(id);
-        printOutput({ success: true, id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.deletePayee(id);
+          printOutput({ success: true, id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   payees
@@ -87,9 +107,13 @@ export function registerPayeesCommand(program: Command) {
         );
       }
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.mergePayees(cmdOpts.target, mergeIds);
-        printOutput({ success: true }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.mergePayees(cmdOpts.target, mergeIds);
+          printOutput({ success: true }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 }

packages/cli/src/commands/query.test.ts

@@ -1,7 +1,7 @@
 import * as api from '@actual-app/api';
 import { Command } from 'commander';
 
-import { printOutput } from '../output';
+import { printOutput } from '#output';
 
 import { parseOrderBy, registerQueryCommand } from './query';
 
@@ -21,11 +21,11 @@ vi.mock('@actual-app/api', () => {
   };
 });
 
-vi.mock('../connection', () => ({
+vi.mock('#connection', () => ({
   withConnection: vi.fn((_opts, fn) => fn()),
 }));
 
-vi.mock('../output', () => ({
+vi.mock('#output', () => ({
   printOutput: vi.fn(),
 }));
 

packages/cli/src/commands/query.ts

@@ -1,10 +1,10 @@
 import * as api from '@actual-app/api';
 import type { Command } from 'commander';
 
-import { withConnection } from '../connection';
-import { readJsonInput } from '../input';
-import { printOutput } from '../output';
-import { isRecord, parseIntFlag } from '../utils';
+import { withConnection } from '#connection';
+import { readJsonInput } from '#input';
+import { printOutput } from '#output';
+import { isRecord, parseIntFlag } from '#utils';
 
 /**
  * Parse order-by strings like "date:desc,amount:asc,id" into
@@ -301,27 +301,31 @@ export function registerQueryCommand(program: Command) {
     .addHelpText('after', RUN_EXAMPLES)
     .action(async cmdOpts => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const parsed = cmdOpts.file ? readJsonInput(cmdOpts) : undefined;
-        if (parsed !== undefined && !isRecord(parsed)) {
-          throw new Error('Query file must contain a JSON object');
-        }
-        const queryObj = parsed
-          ? buildQueryFromFile(parsed, cmdOpts.table)
-          : buildQueryFromFlags(cmdOpts);
+      await withConnection(
+        opts,
+        async () => {
+          const parsed = cmdOpts.file ? readJsonInput(cmdOpts) : undefined;
+          if (parsed !== undefined && !isRecord(parsed)) {
+            throw new Error('Query file must contain a JSON object');
+          }
+          const queryObj = parsed
+            ? buildQueryFromFile(parsed, cmdOpts.table)
+            : buildQueryFromFlags(cmdOpts);
 
-        const result = await api.aqlQuery(queryObj);
+          const result = await api.aqlQuery(queryObj);
 
-        if (!isRecord(result) || !('data' in result)) {
-          throw new Error('Query result missing data');
-        }
+          if (!isRecord(result) || !('data' in result)) {
+            throw new Error('Query result missing data');
+          }
 
-        if (cmdOpts.count) {
-          printOutput({ count: result.data }, opts.format);
-        } else {
-          printOutput(result.data, opts.format);
-        }
-      });
+          if (cmdOpts.count) {
+            printOutput({ count: result.data }, opts.format);
+          } else {
+            printOutput(result.data, opts.format);
+          }
+        },
+        { mutates: false },
+      );
     });
 
   query

packages/cli/src/commands/rules.ts

@@ -1,9 +1,9 @@
 import * as api from '@actual-app/api';
 import type { Command } from 'commander';
 
-import { withConnection } from '../connection';
-import { readJsonInput } from '../input';
-import { printOutput } from '../output';
+import { withConnection } from '#connection';
+import { readJsonInput } from '#input';
+import { printOutput } from '#output';
 
 export function registerRulesCommand(program: Command) {
   const rules = program
@@ -15,10 +15,14 @@ export function registerRulesCommand(program: Command) {
     .description('List all rules')
     .action(async () => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const result = await api.getRules();
-        printOutput(result, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const result = await api.getRules();
+          printOutput(result, opts.format);
+        },
+        { mutates: false },
+      );
     });
 
   rules
@@ -26,10 +30,14 @@ export function registerRulesCommand(program: Command) {
     .description('List rules for a specific payee')
     .action(async (payeeId: string) => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const result = await api.getPayeeRules(payeeId);
-        printOutput(result, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const result = await api.getPayeeRules(payeeId);
+          printOutput(result, opts.format);
+        },
+        { mutates: false },
+      );
     });
 
   rules
@@ -39,13 +47,17 @@ export function registerRulesCommand(program: Command) {
     .option('--file <path>', 'Read rule from JSON file (use - for stdin)')
     .action(async cmdOpts => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const rule = readJsonInput(cmdOpts) as Parameters<
-          typeof api.createRule
-        >[0];
-        const id = await api.createRule(rule);
-        printOutput({ id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const rule = readJsonInput(cmdOpts) as Parameters<
+            typeof api.createRule
+          >[0];
+          const id = await api.createRule(rule);
+          printOutput({ id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   rules
@@ -55,13 +67,17 @@ export function registerRulesCommand(program: Command) {
     .option('--file <path>', 'Read rule from JSON file (use - for stdin)')
     .action(async cmdOpts => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const rule = readJsonInput(cmdOpts) as Parameters<
-          typeof api.updateRule
-        >[0];
-        await api.updateRule(rule);
-        printOutput({ success: true }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const rule = readJsonInput(cmdOpts) as Parameters<
+            typeof api.updateRule
+          >[0];
+          await api.updateRule(rule);
+          printOutput({ success: true }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   rules
@@ -69,9 +85,13 @@ export function registerRulesCommand(program: Command) {
     .description('Delete a rule')
     .action(async (id: string) => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.deleteRule(id);
-        printOutput({ success: true, id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.deleteRule(id);
+          printOutput({ success: true, id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 }

packages/cli/src/commands/schedules.ts

@@ -1,9 +1,9 @@
 import * as api from '@actual-app/api';
 import type { Command } from 'commander';
 
-import { withConnection } from '../connection';
-import { readJsonInput } from '../input';
-import { printOutput } from '../output';
+import { withConnection } from '#connection';
+import { readJsonInput } from '#input';
+import { printOutput } from '#output';
 
 export function registerSchedulesCommand(program: Command) {
   const schedules = program
@@ -15,10 +15,14 @@ export function registerSchedulesCommand(program: Command) {
     .description('List all schedules')
     .action(async () => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const result = await api.getSchedules();
-        printOutput(result, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const result = await api.getSchedules();
+          printOutput(result, opts.format);
+        },
+        { mutates: false },
+      );
     });
 
   schedules
@@ -28,13 +32,17 @@ export function registerSchedulesCommand(program: Command) {
     .option('--file <path>', 'Read schedule from JSON file (use - for stdin)')
     .action(async cmdOpts => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const schedule = readJsonInput(cmdOpts) as Parameters<
-          typeof api.createSchedule
-        >[0];
-        const id = await api.createSchedule(schedule);
-        printOutput({ id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const schedule = readJsonInput(cmdOpts) as Parameters<
+            typeof api.createSchedule
+          >[0];
+          const id = await api.createSchedule(schedule);
+          printOutput({ id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   schedules
@@ -45,13 +53,17 @@ export function registerSchedulesCommand(program: Command) {
     .option('--reset-next-date', 'Reset next occurrence date', false)
     .action(async (id: string, cmdOpts) => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const fields = readJsonInput(cmdOpts) as Parameters<
-          typeof api.updateSchedule
-        >[1];
-        await api.updateSchedule(id, fields, cmdOpts.resetNextDate);
-        printOutput({ success: true, id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const fields = readJsonInput(cmdOpts) as Parameters<
+            typeof api.updateSchedule
+          >[1];
+          await api.updateSchedule(id, fields, cmdOpts.resetNextDate);
+          printOutput({ success: true, id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   schedules
@@ -59,9 +71,13 @@ export function registerSchedulesCommand(program: Command) {
     .description('Delete a schedule')
     .action(async (id: string) => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.deleteSchedule(id);
-        printOutput({ success: true, id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.deleteSchedule(id);
+          printOutput({ success: true, id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 }

packages/cli/src/commands/server.ts

@@ -2,8 +2,8 @@ import * as api from '@actual-app/api';
 import { Option } from 'commander';
 import type { Command } from 'commander';
 
-import { withConnection } from '../connection';
-import { printOutput } from '../output';
+import { withConnection } from '#connection';
+import { printOutput } from '#output';
 
 export function registerServerCommand(program: Command) {
   const server = program.command('server').description('Server utilities');
@@ -19,7 +19,7 @@ export function registerServerCommand(program: Command) {
           const version = await api.getServerVersion();
           printOutput({ version }, opts.format);
         },
-        { loadBudget: false },
+        { mutates: false, skipBudget: true },
       );
     });
 
@@ -34,13 +34,17 @@ export function registerServerCommand(program: Command) {
     .requiredOption('--name <name>', 'Entity name')
     .action(async cmdOpts => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const id = await api.getIDByName(cmdOpts.type, cmdOpts.name);
-        printOutput(
-          { id, type: cmdOpts.type, name: cmdOpts.name },
-          opts.format,
-        );
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const id = await api.getIDByName(cmdOpts.type, cmdOpts.name);
+          printOutput(
+            { id, type: cmdOpts.type, name: cmdOpts.name },
+            opts.format,
+          );
+        },
+        { mutates: false },
+      );
     });
 
   server
@@ -49,12 +53,16 @@ export function registerServerCommand(program: Command) {
     .option('--account <id>', 'Specific account ID to sync')
     .action(async cmdOpts => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const args = cmdOpts.account
-          ? { accountId: cmdOpts.account }
-          : undefined;
-        await api.runBankSync(args);
-        printOutput({ success: true }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const args = cmdOpts.account
+            ? { accountId: cmdOpts.account }
+            : undefined;
+          await api.runBankSync(args);
+          printOutput({ success: true }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 }

packages/cli/src/commands/sync.test.ts

@@ -0,0 +1,124 @@
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { Command } from 'commander';
+
+import { CACHE_FILE_NAME, getMetaDir, writeCacheState } from '#cache';
+import { resolveConfig } from '#config';
+
+import { registerSyncCommand } from './sync';
+
+vi.mock('@actual-app/api', () => ({
+  init: vi.fn().mockResolvedValue(undefined),
+  downloadBudget: vi.fn().mockResolvedValue(undefined),
+  loadBudget: vi.fn().mockResolvedValue(undefined),
+  sync: vi.fn().mockResolvedValue(undefined),
+  shutdown: vi.fn().mockResolvedValue(undefined),
+  getBudgets: vi
+    .fn()
+    .mockResolvedValue([{ id: 'bud-disk-1', groupId: 'sync-1' }]),
+}));
+
+vi.mock('#config', () => ({
+  resolveConfig: vi.fn(),
+}));
+
+let dataDir: string;
+
+function metaDirFor(syncId: string) {
+  return getMetaDir(dataDir, syncId);
+}
+
+function program() {
+  const p = new Command();
+  p.exitOverride();
+  p.option('--sync-id <id>');
+  p.option('--data-dir <path>');
+  p.option('--format <fmt>');
+  p.option('--verbose');
+  registerSyncCommand(p);
+  return p;
+}
+
+describe('actual sync', () => {
+  let stdoutSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    dataDir = mkdtempSync(join(tmpdir(), 'actual-cli-sync-'));
+    vi.mocked(resolveConfig).mockResolvedValue({
+      serverUrl: 'http://test',
+      password: 'pw',
+      dataDir,
+      syncId: 'sync-1',
+      cacheTtl: 60,
+      lockTimeout: 10,
+      refresh: false,
+      noLock: true,
+    });
+    stdoutSpy = vi
+      .spyOn(process.stdout, 'write')
+      .mockImplementation(() => true);
+  });
+
+  afterEach(() => {
+    stdoutSpy.mockRestore();
+    rmSync(dataDir, { recursive: true, force: true });
+  });
+
+  it('runs a sync and prints the syncId', async () => {
+    writeCacheState(metaDirFor('sync-1'), {
+      version: 1,
+      syncId: 'sync-1',
+      budgetId: 'bud-disk-1',
+      serverUrl: 'http://test',
+      lastSyncedAt: 0,
+      lastDownloadedAt: 0,
+    });
+    await program().parseAsync(['node', 'actual', 'sync']);
+    const out = stdoutSpy.mock.calls
+      .map((c: unknown[]) => String(c[0]))
+      .join('');
+    expect(out).toMatch(/"syncId":\s*"sync-1"/);
+  });
+
+  it('--status prints cache info without syncing', async () => {
+    writeCacheState(metaDirFor('sync-1'), {
+      version: 1,
+      syncId: 'sync-1',
+      budgetId: 'bud-disk-1',
+      serverUrl: 'http://test',
+      lastSyncedAt: Date.now() - 5000,
+      lastDownloadedAt: Date.now() - 5000,
+    });
+    await program().parseAsync(['node', 'actual', 'sync', '--status']);
+    const out = stdoutSpy.mock.calls
+      .map((c: unknown[]) => String(c[0]))
+      .join('');
+    expect(out).toMatch(/"stale":\s*(true|false)/);
+    expect(out).toMatch(/"ageSeconds":\s*\d+/);
+  });
+
+  it('--status on no prior sync reports "never synced" and exits 0', async () => {
+    await program().parseAsync(['node', 'actual', 'sync', '--status']);
+    const out = stdoutSpy.mock.calls
+      .map((c: unknown[]) => String(c[0]))
+      .join('');
+    expect(out).toMatch(/"neverSynced":\s*true/);
+  });
+
+  it('--clear removes the cache file', async () => {
+    writeCacheState(metaDirFor('sync-1'), {
+      version: 1,
+      syncId: 'sync-1',
+      budgetId: 'bud-disk-1',
+      serverUrl: 'http://test',
+      lastSyncedAt: Date.now(),
+      lastDownloadedAt: Date.now(),
+    });
+    expect(existsSync(join(metaDirFor('sync-1'), CACHE_FILE_NAME))).toBe(true);
+    await program().parseAsync(['node', 'actual', 'sync', '--clear']);
+    expect(existsSync(join(metaDirFor('sync-1'), CACHE_FILE_NAME))).toBe(false);
+  });
+});

packages/cli/src/commands/sync.ts

@@ -0,0 +1,118 @@
+import { rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { Command } from 'commander';
+
+import { CACHE_FILE_NAME, getMetaDir, readCacheState } from '#cache';
+import type { CliConfig } from '#config';
+import { resolveConfig } from '#config';
+import { withConnection } from '#connection';
+import { acquireExclusive } from '#lock';
+import { printOutput } from '#output';
+
+type SyncCmdOpts = {
+  status?: boolean;
+  clear?: boolean;
+};
+
+async function requireSyncIdAndMeta(
+  opts: Record<string, unknown>,
+  flag: string,
+): Promise<{ config: CliConfig; meta: string }> {
+  const config = await resolveConfig(opts);
+  if (!config.syncId) {
+    throw new Error(
+      `Sync ID is required for sync ${flag}. Set --sync-id or ACTUAL_SYNC_ID.`,
+    );
+  }
+  return { config, meta: getMetaDir(config.dataDir, config.syncId) };
+}
+
+export function registerSyncCommand(program: Command) {
+  program
+    .command('sync')
+    .description(
+      'Sync the local cached budget with the server, print cache status, or clear the cache',
+    )
+    .option('--status', 'Print cache status without syncing', false)
+    .option(
+      '--clear',
+      'Delete the local cache; next command re-downloads',
+      false,
+    )
+    .action(async (cmdOpts: SyncCmdOpts) => {
+      const opts = program.opts();
+
+      if (cmdOpts.status) {
+        const { config, meta } = await requireSyncIdAndMeta(opts, '--status');
+        const state = readCacheState(meta);
+        if (state === null) {
+          printOutput(
+            {
+              neverSynced: true,
+              syncId: config.syncId,
+              ttlSeconds: config.cacheTtl,
+            },
+            opts.format,
+          );
+          return;
+        }
+        const rawAgeSeconds = Math.round(
+          (Date.now() - state.lastSyncedAt) / 1000,
+        );
+        const ageSeconds = Math.max(0, rawAgeSeconds);
+        printOutput(
+          {
+            neverSynced: false,
+            syncId: state.syncId,
+            budgetId: state.budgetId,
+            syncedAt: new Date(state.lastSyncedAt).toISOString(),
+            lastDownloadedAt: new Date(state.lastDownloadedAt).toISOString(),
+            ageSeconds,
+            ttlSeconds: config.cacheTtl,
+            stale: rawAgeSeconds < 0 || rawAgeSeconds > config.cacheTtl,
+          },
+          opts.format,
+        );
+        return;
+      }
+
+      if (cmdOpts.clear) {
+        const { config, meta } = await requireSyncIdAndMeta(opts, '--clear');
+        // Serialize with concurrent writers so we don't rm a half-written
+        // state.json that's about to be renamed into place.
+        const release = config.noLock
+          ? null
+          : await acquireExclusive(meta, {
+              timeoutMs: config.lockTimeout * 1000,
+            });
+        try {
+          rmSync(join(meta, CACHE_FILE_NAME), { force: true });
+        } finally {
+          await release?.();
+        }
+        printOutput({ cleared: true, syncId: config.syncId }, opts.format);
+        return;
+      }
+
+      await withConnection(
+        opts,
+        async config => {
+          const state = config.syncId
+            ? readCacheState(getMetaDir(config.dataDir, config.syncId))
+            : null;
+          printOutput(
+            {
+              syncedAt: new Date(
+                state?.lastSyncedAt ?? Date.now(),
+              ).toISOString(),
+              syncId: config.syncId,
+              budgetId: state?.budgetId ?? config.syncId,
+            },
+            opts.format,
+          );
+        },
+        { mutates: true },
+      );
+    });
+}

packages/cli/src/commands/tags.ts

@@ -1,8 +1,8 @@
 import * as api from '@actual-app/api';
 import type { Command } from 'commander';
 
-import { withConnection } from '../connection';
-import { printOutput } from '../output';
+import { withConnection } from '#connection';
+import { printOutput } from '#output';
 
 export function registerTagsCommand(program: Command) {
   const tags = program.command('tags').description('Manage tags');
@@ -12,10 +12,14 @@ export function registerTagsCommand(program: Command) {
     .description('List all tags')
     .action(async () => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const result = await api.getTags();
-        printOutput(result, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const result = await api.getTags();
+          printOutput(result, opts.format);
+        },
+        { mutates: false },
+      );
     });
 
   tags
@@ -26,14 +30,18 @@ export function registerTagsCommand(program: Command) {
     .option('--description <description>', 'Tag description')
     .action(async cmdOpts => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const id = await api.createTag({
-          tag: cmdOpts.tag,
-          color: cmdOpts.color,
-          description: cmdOpts.description,
-        });
-        printOutput({ id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const id = await api.createTag({
+            tag: cmdOpts.tag,
+            color: cmdOpts.color,
+            description: cmdOpts.description,
+          });
+          printOutput({ id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   tags
@@ -55,10 +63,14 @@ export function registerTagsCommand(program: Command) {
         );
       }
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.updateTag(id, fields);
-        printOutput({ success: true, id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.updateTag(id, fields);
+          printOutput({ success: true, id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   tags
@@ -66,9 +78,13 @@ export function registerTagsCommand(program: Command) {
     .description('Delete a tag')
     .action(async (id: string) => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.deleteTag(id);
-        printOutput({ success: true, id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.deleteTag(id);
+          printOutput({ success: true, id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 }

packages/cli/src/commands/transactions.ts

@@ -1,9 +1,9 @@
 import * as api from '@actual-app/api';
 import type { Command } from 'commander';
 
-import { withConnection } from '../connection';
-import { readJsonInput } from '../input';
-import { printOutput } from '../output';
+import { withConnection } from '#connection';
+import { readJsonInput } from '#input';
+import { printOutput } from '#output';
 
 export function registerTransactionsCommand(program: Command) {
   const transactions = program
@@ -18,14 +18,18 @@ export function registerTransactionsCommand(program: Command) {
     .requiredOption('--end <date>', 'End date (YYYY-MM-DD)')
     .action(async cmdOpts => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const result = await api.getTransactions(
-          cmdOpts.account,
-          cmdOpts.start,
-          cmdOpts.end,
-        );
-        printOutput(result, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const result = await api.getTransactions(
+            cmdOpts.account,
+            cmdOpts.start,
+            cmdOpts.end,
+          );
+          printOutput(result, opts.format);
+        },
+        { mutates: false },
+      );
     });
 
   transactions
@@ -41,20 +45,24 @@ export function registerTransactionsCommand(program: Command) {
     .option('--run-transfers', 'Process transfers', false)
     .action(async cmdOpts => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const transactions = readJsonInput(cmdOpts) as Parameters<
-          typeof api.addTransactions
-        >[1];
-        const result = await api.addTransactions(
-          cmdOpts.account,
-          transactions,
-          {
-            learnCategories: cmdOpts.learnCategories,
-            runTransfers: cmdOpts.runTransfers,
-          },
-        );
-        printOutput(result, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const transactions = readJsonInput(cmdOpts) as Parameters<
+            typeof api.addTransactions
+          >[1];
+          const result = await api.addTransactions(
+            cmdOpts.account,
+            transactions,
+            {
+              learnCategories: cmdOpts.learnCategories,
+              runTransfers: cmdOpts.runTransfers,
+            },
+          );
+          printOutput(result, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   transactions
@@ -69,20 +77,24 @@ export function registerTransactionsCommand(program: Command) {
     .option('--dry-run', 'Preview without importing', false)
     .action(async cmdOpts => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const transactions = readJsonInput(cmdOpts) as Parameters<
-          typeof api.importTransactions
-        >[1];
-        const result = await api.importTransactions(
-          cmdOpts.account,
-          transactions,
-          {
-            defaultCleared: true,
-            dryRun: cmdOpts.dryRun,
-          },
-        );
-        printOutput(result, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const transactions = readJsonInput(cmdOpts) as Parameters<
+            typeof api.importTransactions
+          >[1];
+          const result = await api.importTransactions(
+            cmdOpts.account,
+            transactions,
+            {
+              defaultCleared: true,
+              dryRun: cmdOpts.dryRun,
+            },
+          );
+          printOutput(result, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   transactions
@@ -92,13 +104,17 @@ export function registerTransactionsCommand(program: Command) {
     .option('--file <path>', 'Read fields from JSON file (use - for stdin)')
     .action(async (id: string, cmdOpts) => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        const fields = readJsonInput(cmdOpts) as Parameters<
-          typeof api.updateTransaction
-        >[1];
-        await api.updateTransaction(id, fields);
-        printOutput({ success: true, id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          const fields = readJsonInput(cmdOpts) as Parameters<
+            typeof api.updateTransaction
+          >[1];
+          await api.updateTransaction(id, fields);
+          printOutput({ success: true, id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 
   transactions
@@ -106,9 +122,13 @@ export function registerTransactionsCommand(program: Command) {
     .description('Delete a transaction')
     .action(async (id: string) => {
       const opts = program.opts();
-      await withConnection(opts, async () => {
-        await api.deleteTransaction(id);
-        printOutput({ success: true, id }, opts.format);
-      });
+      await withConnection(
+        opts,
+        async () => {
+          await api.deleteTransaction(id);
+          printOutput({ success: true, id }, opts.format);
+        },
+        { mutates: true },
+      );
     });
 }

packages/cli/src/config.test.ts

@@ -28,6 +28,9 @@ describe('resolveConfig', () => {
     'ACTUAL_SYNC_ID',
     'ACTUAL_DATA_DIR',
     'ACTUAL_ENCRYPTION_PASSWORD',
+    'ACTUAL_CACHE_TTL',
+    'ACTUAL_LOCK_TIMEOUT',
+    'ACTUAL_NO_LOCK',
   ];
 
   beforeEach(() => {
@@ -159,6 +162,125 @@ describe('resolveConfig', () => {
     });
   });
 
+  describe('cache options', () => {
+    beforeEach(() => {
+      process.env.ACTUAL_SERVER_URL = 'http://test';
+      process.env.ACTUAL_PASSWORD = 'pw';
+    });
+
+    it('defaults cacheTtl to 60 seconds', async () => {
+      const config = await resolveConfig({});
+      expect(config.cacheTtl).toBe(60);
+    });
+
+    it('reads cacheTtl from env', async () => {
+      process.env.ACTUAL_CACHE_TTL = '300';
+      const config = await resolveConfig({});
+      expect(config.cacheTtl).toBe(300);
+    });
+
+    it('prefers cacheTtl from CLI flag', async () => {
+      process.env.ACTUAL_CACHE_TTL = '300';
+      const config = await resolveConfig({ cacheTtl: 10 });
+      expect(config.cacheTtl).toBe(10);
+    });
+
+    it('rejects negative cacheTtl', async () => {
+      await expect(resolveConfig({ cacheTtl: -1 })).rejects.toThrow(/cacheTtl/);
+    });
+
+    it('rejects non-integer cacheTtl from env', async () => {
+      process.env.ACTUAL_CACHE_TTL = 'banana';
+      await expect(resolveConfig({})).rejects.toThrow(/ACTUAL_CACHE_TTL/);
+    });
+
+    it('defaults lockTimeout to 10 seconds', async () => {
+      const config = await resolveConfig({});
+      expect(config.lockTimeout).toBe(10);
+    });
+
+    it('reads lockTimeout from env', async () => {
+      process.env.ACTUAL_LOCK_TIMEOUT = '30';
+      const config = await resolveConfig({});
+      expect(config.lockTimeout).toBe(30);
+    });
+
+    it('defaults refresh to false', async () => {
+      const config = await resolveConfig({});
+      expect(config.refresh).toBe(false);
+    });
+
+    it('sets refresh when provided on CLI opts', async () => {
+      const config = await resolveConfig({ refresh: true });
+      expect(config.refresh).toBe(true);
+    });
+
+    it('sets refresh when --no-cache is passed (cliOpts.cache === false)', async () => {
+      const config = await resolveConfig({ cache: false });
+      expect(config.refresh).toBe(true);
+    });
+
+    it('does not set refresh when cliOpts.cache is true (flag absent)', async () => {
+      const config = await resolveConfig({ cache: true });
+      expect(config.refresh).toBe(false);
+    });
+
+    it('defaults noLock to false', async () => {
+      const config = await resolveConfig({});
+      expect(config.noLock).toBe(false);
+    });
+
+    it('sets noLock when --no-lock is passed (cliOpts.lock === false)', async () => {
+      const config = await resolveConfig({ lock: false });
+      expect(config.noLock).toBe(true);
+    });
+
+    it('leaves noLock false when cliOpts.lock is true (flag absent)', async () => {
+      const config = await resolveConfig({ lock: true });
+      expect(config.noLock).toBe(false);
+    });
+
+    it('parses ACTUAL_NO_LOCK=1 as true', async () => {
+      process.env.ACTUAL_NO_LOCK = '1';
+      const config = await resolveConfig({});
+      expect(config.noLock).toBe(true);
+    });
+
+    it('parses ACTUAL_NO_LOCK=true as true', async () => {
+      process.env.ACTUAL_NO_LOCK = 'true';
+      const config = await resolveConfig({});
+      expect(config.noLock).toBe(true);
+    });
+
+    it('throws on an invalid ACTUAL_NO_LOCK value', async () => {
+      process.env.ACTUAL_NO_LOCK = 'yes';
+      await expect(resolveConfig({})).rejects.toThrow(/ACTUAL_NO_LOCK/);
+    });
+
+    it('reads cacheTtl/lockTimeout/noLock from config file', async () => {
+      mockConfigFile({
+        serverUrl: 'http://file',
+        password: 'pw',
+        cacheTtl: 120,
+        lockTimeout: 5,
+        noLock: true,
+      });
+      const config = await resolveConfig({});
+      expect(config.cacheTtl).toBe(120);
+      expect(config.lockTimeout).toBe(5);
+      expect(config.noLock).toBe(true);
+    });
+
+    it('rejects non-number cacheTtl in config file', async () => {
+      mockConfigFile({
+        serverUrl: 'http://file',
+        password: 'pw',
+        cacheTtl: 'soon',
+      });
+      await expect(resolveConfig({})).rejects.toThrow(/cacheTtl/);
+    });
+  });
+
   describe('cosmiconfig handling', () => {
     it('handles null result (no config file found)', async () => {
       mockConfigFile(null);

packages/cli/src/config.ts

@@ -3,7 +3,7 @@ import { join } from 'path';
 
 import { cosmiconfig } from 'cosmiconfig';
 
-import { isRecord } from './utils';
+import { isRecord, parseBoolEnv, parseNonNegativeIntFlag } from './utils';
 
 export type CliConfig = {
   serverUrl: string;
@@ -12,6 +12,10 @@ export type CliConfig = {
   syncId?: string;
   dataDir: string;
   encryptionPassword?: string;
+  cacheTtl: number;
+  lockTimeout: number;
+  refresh: boolean;
+  noLock: boolean;
 };
 
 export type CliGlobalOpts = {
@@ -21,10 +25,29 @@ export type CliGlobalOpts = {
   syncId?: string;
   dataDir?: string;
   encryptionPassword?: string;
+  cacheTtl?: number;
+  lockTimeout?: number;
+  refresh?: boolean;
+  // Commander stores --no-foo flags under the positive key. Default true,
+  // false when the flag is passed.
+  cache?: boolean;
+  lock?: boolean;
   format?: 'json' | 'table' | 'csv';
   verbose?: boolean;
 };
 
+const stringKeys = [
+  'serverUrl',
+  'password',
+  'sessionToken',
+  'syncId',
+  'dataDir',
+  'encryptionPassword',
+] as const;
+
+const numberKeys = ['cacheTtl', 'lockTimeout'] as const;
+const booleanKeys = ['noLock'] as const;
+
 type ConfigFileContent = {
   serverUrl?: string;
   password?: string;
@@ -32,15 +55,15 @@ type ConfigFileContent = {
   syncId?: string;
   dataDir?: string;
   encryptionPassword?: string;
+  cacheTtl?: number;
+  lockTimeout?: number;
+  noLock?: boolean;
 };
 
 const configFileKeys: readonly string[] = [
-  'serverUrl',
-  'password',
-  'sessionToken',
-  'syncId',
-  'dataDir',
-  'encryptionPassword',
+  ...stringKeys,
+  ...numberKeys,
+  ...booleanKeys,
 ];
 
 function validateConfigFileContent(value: unknown): ConfigFileContent {
@@ -54,9 +77,30 @@ function validateConfigFileContent(value: unknown): ConfigFileContent {
     if (!configFileKeys.includes(key)) {
       throw new Error(`Invalid config file: unknown key "${key}"`);
     }
-    if (value[key] !== undefined && typeof value[key] !== 'string') {
+    const v = value[key];
+    if (v === undefined) continue;
+    if (
+      (stringKeys as readonly string[]).includes(key) &&
+      typeof v !== 'string'
+    ) {
       throw new Error(
-        `Invalid config file: key "${key}" must be a string, got ${typeof value[key]}`,
+        `Invalid config file: key "${key}" must be a string, got ${typeof v}`,
+      );
+    }
+    if (
+      (numberKeys as readonly string[]).includes(key) &&
+      (typeof v !== 'number' || !Number.isInteger(v) || v < 0)
+    ) {
+      throw new Error(
+        `Invalid config file: key "${key}" must be a non-negative integer`,
+      );
+    }
+    if (
+      (booleanKeys as readonly string[]).includes(key) &&
+      typeof v !== 'boolean'
+    ) {
+      throw new Error(
+        `Invalid config file: key "${key}" must be a boolean, got ${typeof v}`,
       );
     }
   }
@@ -83,6 +127,22 @@ async function loadConfigFile(): Promise<ConfigFileContent> {
   return {};
 }
 
+function parseNonNegativeIntEnv(
+  raw: string | undefined,
+  source: string,
+): number | undefined {
+  return raw === undefined ? undefined : parseNonNegativeIntFlag(raw, source);
+}
+
+function validateNonNegativeInt(value: number, name: string): number {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(
+      `Invalid ${name}: expected a non-negative integer, got ${value}`,
+    );
+  }
+  return value;
+}
+
 export async function resolveConfig(
   cliOpts: CliGlobalOpts,
 ): Promise<CliConfig> {
@@ -128,6 +188,37 @@ export async function resolveConfig(
     );
   }
 
+  const cacheTtl = validateNonNegativeInt(
+    cliOpts.cacheTtl ??
+      parseNonNegativeIntEnv(
+        process.env.ACTUAL_CACHE_TTL,
+        'ACTUAL_CACHE_TTL',
+      ) ??
+      fileConfig.cacheTtl ??
+      60,
+    'cacheTtl',
+  );
+
+  const lockTimeout = validateNonNegativeInt(
+    cliOpts.lockTimeout ??
+      parseNonNegativeIntEnv(
+        process.env.ACTUAL_LOCK_TIMEOUT,
+        'ACTUAL_LOCK_TIMEOUT',
+      ) ??
+      fileConfig.lockTimeout ??
+      10,
+    'lockTimeout',
+  );
+
+  const refresh = (cliOpts.refresh ?? false) || cliOpts.cache === false;
+
+  const flagNoLock = cliOpts.lock === false ? true : undefined;
+  const noLock =
+    flagNoLock ??
+    parseBoolEnv(process.env.ACTUAL_NO_LOCK, 'ACTUAL_NO_LOCK') ??
+    fileConfig.noLock ??
+    false;
+
   return {
     serverUrl,
     password,
@@ -135,5 +226,9 @@ export async function resolveConfig(
     syncId,
     dataDir,
     encryptionPassword,
+    cacheTtl,
+    lockTimeout,
+    refresh,
+    noLock,
   };
 }

packages/cli/src/connection.test.ts

@@ -1,24 +1,44 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
 import * as api from '@actual-app/api';
 
+import { getMetaDir, writeCacheState } from './cache';
 import { resolveConfig } from './config';
 import { withConnection } from './connection';
 
 vi.mock('@actual-app/api', () => ({
   init: vi.fn().mockResolvedValue(undefined),
   downloadBudget: vi.fn().mockResolvedValue(undefined),
+  loadBudget: vi.fn().mockResolvedValue(undefined),
+  sync: vi.fn().mockResolvedValue(undefined),
   shutdown: vi.fn().mockResolvedValue(undefined),
+  getBudgets: vi
+    .fn()
+    .mockResolvedValue([{ id: 'bud-disk-1', groupId: 'sync-1' }]),
 }));
 
 vi.mock('./config', () => ({
   resolveConfig: vi.fn(),
 }));
 
+let dataDir: string;
+
+function metaDirFor(syncId: string) {
+  return getMetaDir(dataDir, syncId);
+}
+
 function setConfig(overrides: Record<string, unknown> = {}) {
   vi.mocked(resolveConfig).mockResolvedValue({
     serverUrl: 'http://test',
     password: 'pw',
-    dataDir: '/tmp/data',
-    syncId: 'budget-1',
+    dataDir,
+    syncId: 'sync-1',
+    cacheTtl: 60,
+    lockTimeout: 10,
+    refresh: false,
+    noLock: true,
     ...overrides,
   });
 }
@@ -31,104 +51,182 @@ describe('withConnection', () => {
     stderrSpy = vi
       .spyOn(process.stderr, 'write')
       .mockImplementation(() => true);
+    dataDir = mkdtempSync(join(tmpdir(), 'actual-cli-conn-'));
     setConfig();
   });
 
   afterEach(() => {
     stderrSpy.mockRestore();
+    rmSync(dataDir, { recursive: true, force: true });
   });
 
   it('calls api.init with password when no sessionToken', async () => {
-    setConfig({ password: 'pw', sessionToken: undefined });
-
-    await withConnection({}, async () => 'ok');
-
+    await withConnection({}, async () => 'ok', { mutates: false });
     expect(api.init).toHaveBeenCalledWith({
       serverURL: 'http://test',
       password: 'pw',
-      dataDir: '/tmp/data',
+      dataDir,
       verbose: undefined,
     });
   });
 
   it('calls api.init with sessionToken when present', async () => {
     setConfig({ sessionToken: 'tok', password: undefined });
-
-    await withConnection({}, async () => 'ok');
-
+    await withConnection({}, async () => 'ok', { mutates: false });
     expect(api.init).toHaveBeenCalledWith({
       serverURL: 'http://test',
       sessionToken: 'tok',
-      dataDir: '/tmp/data',
+      dataDir,
       verbose: undefined,
     });
   });
 
-  it('calls api.downloadBudget when syncId is set', async () => {
-    setConfig({ syncId: 'budget-1' });
-
-    await withConnection({}, async () => 'ok');
-
-    expect(api.downloadBudget).toHaveBeenCalledWith('budget-1', {
+  it('first run: calls downloadBudget and writes cache state', async () => {
+    await withConnection({}, async () => 'ok', { mutates: false });
+    expect(api.downloadBudget).toHaveBeenCalledWith('sync-1', {
       password: undefined,
     });
+    expect(api.sync).not.toHaveBeenCalled();
   });
 
-  it('throws when loadBudget is true but syncId is not set', async () => {
-    setConfig({ syncId: undefined });
-
-    await expect(withConnection({}, async () => 'ok')).rejects.toThrow(
-      'Sync ID is required',
-    );
-  });
-
-  it('skips budget download when loadBudget is false and syncId is not set', async () => {
-    setConfig({ syncId: undefined });
-
-    await withConnection({}, async () => 'ok', { loadBudget: false });
-
+  it('skips sync on a read inside the TTL', async () => {
+    writeCacheState(metaDirFor('sync-1'), {
+      version: 1,
+      syncId: 'sync-1',
+      budgetId: 'bud-disk-1',
+      serverUrl: 'http://test',
+      lastSyncedAt: Date.now(),
+      lastDownloadedAt: Date.now(),
+    });
+    await withConnection({}, async () => 'ok', { mutates: false });
+    expect(api.loadBudget).toHaveBeenCalledWith('bud-disk-1');
+    expect(api.sync).not.toHaveBeenCalled();
     expect(api.downloadBudget).not.toHaveBeenCalled();
   });
 
-  it('does not call api.downloadBudget when loadBudget is false', async () => {
-    setConfig({ syncId: 'budget-1' });
-
-    await withConnection({}, async () => 'ok', { loadBudget: false });
-
-    expect(api.downloadBudget).not.toHaveBeenCalled();
+  it('syncs on a read past the TTL', async () => {
+    writeCacheState(metaDirFor('sync-1'), {
+      version: 1,
+      syncId: 'sync-1',
+      budgetId: 'bud-disk-1',
+      serverUrl: 'http://test',
+      lastSyncedAt: Date.now() - 10 * 60_000,
+      lastDownloadedAt: Date.now() - 10 * 60_000,
+    });
+    await withConnection({}, async () => 'ok', { mutates: false });
+    expect(api.loadBudget).toHaveBeenCalled();
+    expect(api.sync).toHaveBeenCalledTimes(1);
   });
 
-  it('returns callback result', async () => {
-    const result = await withConnection({}, async () => 42);
+  it('write command syncs before and after the callback, even when fresh', async () => {
+    writeCacheState(metaDirFor('sync-1'), {
+      version: 1,
+      syncId: 'sync-1',
+      budgetId: 'bud-disk-1',
+      serverUrl: 'http://test',
+      lastSyncedAt: Date.now(),
+      lastDownloadedAt: Date.now(),
+    });
+    await withConnection({}, async () => 'ok', { mutates: true });
+    expect(api.loadBudget).toHaveBeenCalled();
+    expect(api.sync).toHaveBeenCalledTimes(2);
+  });
+
+  it('--refresh forces a sync on a read inside the TTL', async () => {
+    setConfig({ refresh: true });
+    writeCacheState(metaDirFor('sync-1'), {
+      version: 1,
+      syncId: 'sync-1',
+      budgetId: 'bud-disk-1',
+      serverUrl: 'http://test',
+      lastSyncedAt: Date.now(),
+      lastDownloadedAt: Date.now(),
+    });
+    await withConnection({}, async () => 'ok', { mutates: false });
+    expect(api.sync).toHaveBeenCalledTimes(1);
+  });
+
+  it('encrypted budget forces a sync on a read inside the TTL', async () => {
+    setConfig({ encryptionPassword: 'secret' });
+    writeCacheState(metaDirFor('sync-1'), {
+      version: 1,
+      syncId: 'sync-1',
+      budgetId: 'bud-disk-1',
+      serverUrl: 'http://test',
+      lastSyncedAt: Date.now(),
+      lastDownloadedAt: Date.now(),
+    });
+    await withConnection({}, async () => 'ok', { mutates: false });
+    expect(api.sync).toHaveBeenCalledTimes(1);
+  });
+
+  it('invalidates cache when syncId changes', async () => {
+    writeCacheState(metaDirFor('sync-1'), {
+      version: 1,
+      syncId: 'OTHER',
+      budgetId: 'bud-disk-1',
+      serverUrl: 'http://test',
+      lastSyncedAt: Date.now(),
+      lastDownloadedAt: Date.now(),
+    });
+    await withConnection({}, async () => 'ok', { mutates: false });
+    expect(api.downloadBudget).toHaveBeenCalled();
+  });
+
+  it('skips budget work when skipBudget is true', async () => {
+    await withConnection({}, async () => 'ok', {
+      mutates: false,
+      skipBudget: true,
+    });
+    expect(api.downloadBudget).not.toHaveBeenCalled();
+    expect(api.loadBudget).not.toHaveBeenCalled();
+    expect(api.sync).not.toHaveBeenCalled();
+  });
+
+  it('throws when syncId is missing and skipBudget is false', async () => {
+    setConfig({ syncId: undefined });
+    await expect(
+      withConnection({}, async () => 'ok', { mutates: false }),
+    ).rejects.toThrow('Sync ID is required');
+  });
+
+  it('returns the callback result', async () => {
+    const result = await withConnection({}, async () => 42, {
+      mutates: false,
+    });
     expect(result).toBe(42);
   });
 
-  it('calls api.shutdown in finally block on success', async () => {
-    await withConnection({}, async () => 'ok');
+  it('calls api.shutdown on success', async () => {
+    await withConnection({}, async () => 'ok', { mutates: false });
     expect(api.shutdown).toHaveBeenCalled();
   });
 
-  it('calls api.shutdown in finally block on error', async () => {
+  it('calls api.shutdown on error', async () => {
     await expect(
-      withConnection({}, async () => {
-        throw new Error('boom');
-      }),
+      withConnection(
+        {},
+        async () => {
+          throw new Error('boom');
+        },
+        { mutates: false },
+      ),
     ).rejects.toThrow('boom');
-
     expect(api.shutdown).toHaveBeenCalled();
   });
 
-  it('does not write to stderr by default', async () => {
-    await withConnection({}, async () => 'ok');
-
-    expect(stderrSpy).not.toHaveBeenCalled();
-  });
-
-  it('writes info to stderr when verbose', async () => {
-    await withConnection({ verbose: true }, async () => 'ok');
-
-    expect(stderrSpy).toHaveBeenCalledWith(
-      expect.stringContaining('Connecting to'),
-    );
+  it('propagates sync errors on a stale read', async () => {
+    writeCacheState(metaDirFor('sync-1'), {
+      version: 1,
+      syncId: 'sync-1',
+      budgetId: 'bud-disk-1',
+      serverUrl: 'http://test',
+      lastSyncedAt: Date.now() - 10 * 60_000,
+      lastDownloadedAt: Date.now() - 10 * 60_000,
+    });
+    vi.mocked(api.sync).mockRejectedValueOnce(new Error('network'));
+    await expect(
+      withConnection({}, async () => 'ok', { mutates: false }),
+    ).rejects.toThrow('network');
   });
 });

packages/cli/src/connection.ts

@@ -1,30 +1,49 @@
-import { mkdirSync } from 'fs';
-
 import * as api from '@actual-app/api';
 
+import type { CacheState } from './cache';
+import {
+  CACHE_VERSION,
+  decideSyncAction,
+  getMetaDir,
+  readCacheState,
+  writeCacheState,
+} from './cache';
+import type { CliConfig, CliGlobalOpts } from './config';
 import { resolveConfig } from './config';
-import type { CliGlobalOpts } from './config';
-
-function info(message: string, verbose?: boolean) {
-  if (verbose) {
-    process.stderr.write(message + '\n');
-  }
-}
+import { acquireExclusive, acquireShared } from './lock';
+import type { Release } from './lock';
 
 type ConnectionOptions = {
-  loadBudget?: boolean;
+  mutates: boolean;
+  skipBudget?: boolean;
 };
 
+function info(message: string, verbose?: boolean) {
+  if (verbose) process.stderr.write(message + '\n');
+}
+
+async function resolveBudgetIdForSyncId(syncId: string): Promise<string> {
+  const budgets = await api.getBudgets();
+  const match = budgets.find(
+    b =>
+      typeof b.id === 'string' &&
+      (b.groupId === syncId || b.cloudFileId === syncId),
+  );
+  if (!match?.id) {
+    throw new Error(
+      `Could not resolve on-disk budget id for syncId ${syncId} after download.`,
+    );
+  }
+  return match.id;
+}
+
 export async function withConnection<T>(
   globalOpts: CliGlobalOpts,
-  fn: () => Promise<T>,
-  options: ConnectionOptions = {},
+  fn: (config: CliConfig) => Promise<T>,
+  { mutates, skipBudget = false }: ConnectionOptions,
 ): Promise<T> {
-  const { loadBudget = true } = options;
   const config = await resolveConfig(globalOpts);
 
-  mkdirSync(config.dataDir, { recursive: true });
-
   info(`Connecting to ${config.serverUrl}...`, globalOpts.verbose);
 
   if (config.sessionToken) {
@@ -48,17 +67,87 @@ export async function withConnection<T>(
   }
 
   try {
-    if (loadBudget && config.syncId) {
-      info(`Downloading budget ${config.syncId}...`, globalOpts.verbose);
-      await api.downloadBudget(config.syncId, {
-        password: config.encryptionPassword,
-      });
-    } else if (loadBudget && !config.syncId) {
+    if (skipBudget) return await fn(config);
+    if (!config.syncId) {
       throw new Error(
         'Sync ID is required for this command. Set --sync-id or ACTUAL_SYNC_ID.',
       );
     }
-    return await fn();
+
+    const meta = getMetaDir(config.dataDir, config.syncId);
+    let release: Release | null = null;
+    if (!config.noLock) {
+      release = mutates
+        ? await acquireExclusive(meta, {
+            timeoutMs: config.lockTimeout * 1000,
+          })
+        : await acquireShared(meta, {
+            timeoutMs: config.lockTimeout * 1000,
+          });
+    }
+
+    try {
+      const cachedState = readCacheState(meta);
+      const decision = decideSyncAction({
+        state: cachedState,
+        config: { syncId: config.syncId, serverUrl: config.serverUrl },
+        now: Date.now(),
+        ttlMs: config.cacheTtl * 1000,
+        mutates,
+        refresh: config.refresh,
+        encrypted: Boolean(config.encryptionPassword),
+      });
+
+      let state: CacheState;
+      if (decision.action === 'download') {
+        info(
+          cachedState === null
+            ? `Downloading budget ${config.syncId} for the first time...`
+            : `Re-downloading budget ${config.syncId} (cache invalidated)...`,
+          globalOpts.verbose,
+        );
+        await api.downloadBudget(config.syncId, {
+          password: config.encryptionPassword,
+        });
+        const budgetId = await resolveBudgetIdForSyncId(config.syncId);
+        const now = Date.now();
+        state = {
+          version: CACHE_VERSION,
+          syncId: config.syncId,
+          budgetId,
+          serverUrl: config.serverUrl,
+          lastSyncedAt: now,
+          lastDownloadedAt: now,
+        };
+        writeCacheState(meta, state);
+      } else if (decision.action === 'skip') {
+        const age = Math.round(
+          (Date.now() - decision.state.lastSyncedAt) / 1000,
+        );
+        info(`Using cached budget (synced ${age}s ago)...`, globalOpts.verbose);
+        await api.loadBudget(decision.state.budgetId);
+        state = decision.state;
+      } else {
+        info(`Syncing budget ${config.syncId}...`, globalOpts.verbose);
+        await api.loadBudget(decision.state.budgetId);
+        await api.sync();
+        state = { ...decision.state, lastSyncedAt: Date.now() };
+        writeCacheState(meta, state);
+      }
+
+      const result = await fn(config);
+
+      if (mutates) {
+        info(`Pushing changes for ${config.syncId}...`, globalOpts.verbose);
+        await api.sync();
+        state = { ...state, lastSyncedAt: Date.now() };
+        writeCacheState(meta, state);
+      }
+
+      return result;
+    } finally {
+      if (release) await release();
+    }
   } finally {
     await api.shutdown();
   }

packages/cli/src/index.ts

@@ -9,8 +9,10 @@ import { registerQueryCommand } from './commands/query';
 import { registerRulesCommand } from './commands/rules';
 import { registerSchedulesCommand } from './commands/schedules';
 import { registerServerCommand } from './commands/server';
+import { registerSyncCommand } from './commands/sync';
 import { registerTagsCommand } from './commands/tags';
 import { registerTransactionsCommand } from './commands/transactions';
+import { parseNonNegativeIntFlag } from './utils';
 
 declare const __CLI_VERSION__: string;
 
@@ -32,6 +34,22 @@ program
     '--encryption-password <password>',
     'E2E encryption password (env: ACTUAL_ENCRYPTION_PASSWORD)',
   )
+  .option(
+    '--cache-ttl <seconds>',
+    'Cache TTL in seconds (env: ACTUAL_CACHE_TTL; default: 60)',
+    value => parseNonNegativeIntFlag(value, '--cache-ttl'),
+  )
+  .option('--refresh', 'Force a sync on this call, ignoring the cache', false)
+  .option('--no-cache', 'Alias for --refresh')
+  .option(
+    '--lock-timeout <seconds>',
+    'How long to wait for another CLI process to release the lock (env: ACTUAL_LOCK_TIMEOUT; default: 10)',
+    value => parseNonNegativeIntFlag(value, '--lock-timeout'),
+  )
+  .option(
+    '--no-lock',
+    'Disable the budget directory lock (use with care, env: ACTUAL_NO_LOCK)',
+  )
   .addOption(
     new Option('--format <format>', 'Output format: json, table, csv')
       .choices(['json', 'table', 'csv'] as const)
@@ -50,6 +68,7 @@ registerRulesCommand(program);
 registerSchedulesCommand(program);
 registerQueryCommand(program);
 registerServerCommand(program);
+registerSyncCommand(program);
 
 function normalizeThrownMessage(err: unknown): string {
   if (err instanceof Error) return err.message;

packages/cli/src/lock.test.ts

@@ -0,0 +1,159 @@
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { acquireExclusive, acquireShared } from './lock';
+
+// In-memory stand-in for proper-lockfile. The real library spins up a
+// setTimeout loop to refresh lockfile mtimes; on some CI filesystems that
+// timer keeps Node's event loop alive even after tests complete, wedging the
+// test run. The mock behaves identically from our wrapper's perspective
+// (acquire, detect contention with ELOCKED, release) without touching the
+// filesystem or scheduling timers.
+const mockHeld = new Set<string>();
+
+vi.mock('proper-lockfile', () => ({
+  default: {
+    lock: vi.fn(
+      async (
+        file: string,
+        opts?: { lockfilePath?: string },
+      ): Promise<() => Promise<void>> => {
+        const key = opts?.lockfilePath ?? file;
+        if (mockHeld.has(key)) {
+          const err = new Error('Lock is already held') as Error & {
+            code?: string;
+          };
+          err.code = 'ELOCKED';
+          throw err;
+        }
+        mockHeld.add(key);
+        return async () => {
+          mockHeld.delete(key);
+        };
+      },
+    ),
+  },
+}));
+
+describe('acquireExclusive', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    mockHeld.clear();
+    dir = mkdtempSync(join(tmpdir(), 'actual-cli-lock-'));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('creates the directory if it does not exist', async () => {
+    const target = join(dir, 'nested', 'budget');
+    const release = await acquireExclusive(target, { timeoutMs: 1000 });
+    expect(existsSync(target)).toBe(true);
+    await release();
+  });
+
+  it('returns a release function that frees the lock', async () => {
+    const release1 = await acquireExclusive(dir, { timeoutMs: 1000 });
+    await release1();
+    const release2 = await acquireExclusive(dir, { timeoutMs: 1000 });
+    await release2();
+  });
+
+  it('rejects with a user-friendly error when another holder has the lock', async () => {
+    const release = await acquireExclusive(dir, { timeoutMs: 1000 });
+    await expect(acquireExclusive(dir, { timeoutMs: 100 })).rejects.toThrow(
+      /holding the budget/,
+    );
+    await release();
+  });
+});
+
+describe('acquireShared', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    mockHeld.clear();
+    dir = mkdtempSync(join(tmpdir(), 'actual-cli-lock-'));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('allows multiple concurrent shared holders', async () => {
+    const r1 = await acquireShared(dir, { timeoutMs: 1000 });
+    const r2 = await acquireShared(dir, { timeoutMs: 1000 });
+    const readers = readdirSync(join(dir, 'readers'));
+    expect(readers).toHaveLength(2);
+    await r1();
+    await r2();
+  });
+
+  it('removes the reader marker on release', async () => {
+    const release = await acquireShared(dir, { timeoutMs: 1000 });
+    await release();
+    const readers = readdirSync(join(dir, 'readers'));
+    expect(readers).toHaveLength(0);
+  });
+
+  it('rejects when an exclusive lock is held', async () => {
+    const releaseExclusive = await acquireExclusive(dir, { timeoutMs: 1000 });
+    await expect(acquireShared(dir, { timeoutMs: 100 })).rejects.toThrow(
+      /holding the budget/,
+    );
+    await releaseExclusive();
+  });
+
+  it('sweeps stale reader markers whose PIDs no longer exist', async () => {
+    const readersDir = join(dir, 'readers');
+    mkdirSync(readersDir, { recursive: true });
+    writeFileSync(join(readersDir, '-1-abc'), '');
+
+    const release = await acquireExclusive(dir, { timeoutMs: 1000 });
+    expect(readdirSync(readersDir)).toHaveLength(0);
+    await release();
+  });
+});
+
+describe('writer-reader interaction', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    mockHeld.clear();
+    dir = mkdtempSync(join(tmpdir(), 'actual-cli-lock-'));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('exclusive waits for active shared holders to release', async () => {
+    const readerRelease = await acquireShared(dir, { timeoutMs: 500 });
+
+    let writerAcquired = false;
+    const writerPromise = acquireExclusive(dir, { timeoutMs: 1000 }).then(
+      release => {
+        writerAcquired = true;
+        return release;
+      },
+    );
+
+    await new Promise(resolve => setTimeout(resolve, 150));
+    expect(writerAcquired).toBe(false);
+
+    await readerRelease();
+    const writerRelease = await writerPromise;
+    expect(writerAcquired).toBe(true);
+    await writerRelease();
+  });
+});

packages/cli/src/lock.ts

@@ -0,0 +1,149 @@
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import lockfile from 'proper-lockfile';
+
+export type Release = () => Promise<void>;
+
+export type AcquireOptions = {
+  timeoutMs: number;
+};
+
+const LOCKFILE_NAME = 'lock';
+const READERS_DIR_NAME = 'readers';
+const READER_POLL_INTERVAL_MS = 100;
+
+function lockfilePath(dir: string): string {
+  return join(dir, LOCKFILE_NAME);
+}
+
+function readersDir(dir: string): string {
+  return join(dir, READERS_DIR_NAME);
+}
+
+function ensureDir(dir: string) {
+  mkdirSync(dir, { recursive: true });
+}
+
+function retriesForTimeout(timeoutMs: number) {
+  return {
+    retries: Math.max(1, Math.floor(timeoutMs / 200)),
+    minTimeout: 100,
+    maxTimeout: 500,
+    factor: 1.5,
+  };
+}
+
+function errorCode(err: unknown): string | undefined {
+  if (err instanceof Error && 'code' in err) {
+    const { code } = err as { code?: unknown };
+    if (typeof code === 'string') return code;
+  }
+  return undefined;
+}
+
+function isLockedError(err: unknown): boolean {
+  return errorCode(err) === 'ELOCKED';
+}
+
+function lockedMessage(timeoutMs: number): string {
+  return `Another CLI process is holding the budget (waited ${Math.round(
+    timeoutMs / 1000,
+  )}s). Retry, or use a different --data-dir.`;
+}
+
+function pidIsAlive(pid: number): boolean {
+  if (pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return errorCode(err) === 'EPERM';
+  }
+}
+
+function readReaderNames(readers: string): string[] {
+  try {
+    return readdirSync(readers);
+  } catch (err) {
+    if (errorCode(err) === 'ENOENT') return [];
+    throw err;
+  }
+}
+
+function sweepStaleReaders(dir: string) {
+  const readers = readersDir(dir);
+  for (const name of readReaderNames(readers)) {
+    const pid = Number(name.split('-')[0]);
+    if (!Number.isFinite(pid) || !pidIsAlive(pid)) {
+      rmSync(join(readers, name), { force: true });
+    }
+  }
+}
+
+async function waitForReadersEmpty(dir: string, timeoutMs: number) {
+  const readers = readersDir(dir);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    sweepStaleReaders(dir);
+    if (readReaderNames(readers).length === 0) return;
+    await new Promise(resolve => setTimeout(resolve, READER_POLL_INTERVAL_MS));
+  }
+  throw new Error(lockedMessage(timeoutMs));
+}
+
+async function acquireGate(
+  dir: string,
+  timeoutMs: number,
+): Promise<() => Promise<void>> {
+  ensureDir(dir);
+  try {
+    return await lockfile.lock(dir, {
+      lockfilePath: lockfilePath(dir),
+      retries: retriesForTimeout(timeoutMs),
+      stale: 30_000,
+    });
+  } catch (err) {
+    if (isLockedError(err)) throw new Error(lockedMessage(timeoutMs));
+    throw err;
+  }
+}
+
+export async function acquireExclusive(
+  dir: string,
+  { timeoutMs }: AcquireOptions,
+): Promise<Release> {
+  const start = Date.now();
+  const release = await acquireGate(dir, timeoutMs);
+  try {
+    const remaining = Math.max(0, timeoutMs - (Date.now() - start));
+    await waitForReadersEmpty(dir, remaining);
+  } catch (err) {
+    await release();
+    throw err;
+  }
+  return () => release();
+}
+
+export async function acquireShared(
+  dir: string,
+  { timeoutMs }: AcquireOptions,
+): Promise<Release> {
+  const gate = await acquireGate(dir, timeoutMs);
+  let markerPath: string;
+  try {
+    const readers = readersDir(dir);
+    ensureDir(readers);
+    const markerName = `${process.pid}-${randomBytes(6).toString('hex')}`;
+    markerPath = join(readers, markerName);
+    writeFileSync(markerPath, '');
+  } catch (err) {
+    await gate();
+    throw err;
+  }
+  await gate();
+  return async () => {
+    rmSync(markerPath, { force: true });
+  };
+}

packages/cli/src/utils.ts

@@ -18,3 +18,29 @@ export function parseIntFlag(value: string, flagName: string): number {
   }
   return parsed;
 }
+
+export function parseNonNegativeIntFlag(
+  value: string,
+  flagName: string,
+): number {
+  const parsed = parseIntFlag(value, flagName);
+  if (parsed < 0) {
+    throw new Error(
+      `Invalid ${flagName}: "${value}". Expected a non-negative integer.`,
+    );
+  }
+  return parsed;
+}
+
+export function parseBoolEnv(
+  raw: string | undefined,
+  source: string,
+): boolean | undefined {
+  if (raw === undefined) return undefined;
+  const lower = raw.toLowerCase();
+  if (raw === '1' || lower === 'true') return true;
+  if (raw === '0' || lower === 'false') return false;
+  throw new Error(
+    `Invalid ${source}: "${raw}". Expected "true", "false", "1", or "0".`,
+  );
+}

packages/cli/vite.config.ts

@@ -32,5 +32,8 @@ export default defineConfig({
   plugins: [visualizer({ template: 'raw-data', filename: 'dist/stats.json' })],
   test: {
     globals: true,
+    include: ['src/**/*.test.ts'],
+    exclude: ['**/node_modules/**', '**/dist/**'],
+    testTimeout: 10_000,
   },
 });

packages/component-library/.storybook/manager-head.html

@@ -45,6 +45,27 @@
  -->
 
 <style>
+  /* Show logo icon next to brand title text */
+  .sidebar-header a[href='https://actualbudget.org'] {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    text-decoration: none;
+    font-weight: 700;
+    font-size: 16px;
+  }
+  .sidebar-header a[href='https://actualbudget.org']::before {
+    content: '';
+    display: inline-block;
+    width: 32px;
+    height: 32px;
+    min-width: 32px;
+    background-image: url('https://actualbudget.org/img/logo.webp');
+    background-size: contain;
+    background-repeat: no-repeat;
+    background-position: center;
+  }
+
   #storybook-explorer-searchfield {
     font-weight: 400 !important;
     font-size: 14px !important;

packages/component-library/.storybook/manager.ts

@@ -16,7 +16,6 @@ const theme = create({
   base: 'light',
   brandTitle: 'Actual Budget',
   brandUrl: 'https://actualbudget.org',
-  brandImage: 'https://actualbudget.org/img/actual.webp',
   brandTarget: '_blank',
 
   // UI colors
@@ -32,7 +31,7 @@ const theme = create({
 
   // Fonts
   fontBase:
-    '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+    '"Inter Variable", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Fira Sans", "Droid Sans", "Helvetica Neue", Helvetica, Arial, sans-serif',
   fontCode: 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace',
 
   // Text colors

packages/component-library/.storybook/preview.tsx

@@ -4,8 +4,11 @@ import type { Preview } from '@storybook/react-vite';
 
 // Not ideal to import from desktop-client, but we need a source of truth for theme variables
 // TODO: this needs refactoring
+// oxlint-disable-next-line actual/enforce-boundaries
 import * as darkTheme from '../../desktop-client/src/style/themes/dark';
+// oxlint-disable-next-line actual/enforce-boundaries
 import * as lightTheme from '../../desktop-client/src/style/themes/light';
+// oxlint-disable-next-line actual/enforce-boundaries
 import * as midnightTheme from '../../desktop-client/src/style/themes/midnight';
 
 const THEMES = {

packages/component-library/package.json

@@ -2,6 +2,9 @@
   "name": "@actual-app/components",
   "version": "0.0.1",
   "license": "MIT",
+  "imports": {
+    "#tokens": "./src/tokens.ts"
+  },
   "exports": {
     "./hooks/*": "./src/hooks/*.ts",
     "./icons/logo": "./src/icons/logo/index.ts",
@@ -44,25 +47,25 @@
   },
   "dependencies": {
     "@emotion/css": "^11.13.5",
-    "react-aria-components": "^1.15.1",
+    "react-aria-components": "^1.16.0",
     "usehooks-ts": "^3.1.1"
   },
   "devDependencies": {
-    "@chromatic-com/storybook": "^5.0.1",
-    "@storybook/addon-a11y": "^10.2.16",
-    "@storybook/addon-docs": "^10.2.16",
-    "@storybook/react-vite": "^10.2.16",
+    "@chromatic-com/storybook": "^5.1.1",
+    "@storybook/addon-a11y": "^10.3.4",
+    "@storybook/addon-docs": "^10.3.4",
+    "@storybook/react-vite": "^10.3.4",
     "@svgr/babel-plugin-add-jsx-attribute": "^8.0.0",
     "@svgr/cli": "^8.1.0",
     "@types/react": "^19.2.14",
-    "@typescript/native-preview": "^7.0.0-dev.20260309.1",
-    "@vitejs/plugin-react": "^6.0.0",
-    "eslint-plugin-storybook": "^10.2.16",
+    "@typescript/native-preview": "beta",
+    "@vitejs/plugin-react": "^6.0.1",
+    "eslint-plugin-storybook": "^10.3.4",
     "react": "19.2.4",
     "react-dom": "19.2.4",
-    "storybook": "^10.2.16",
+    "storybook": "^10.3.4",
     "vite": "^8.0.5",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.2"
   },
   "peerDependencies": {
     "react": ">=19.2",

packages/component-library/src/hooks/useResponsive.ts

@@ -1,6 +1,6 @@
 import { useWindowSize } from 'usehooks-ts';
 
-import { breakpoints } from '../tokens';
+import { breakpoints } from '#tokens';
 
 export function useResponsive() {
   const { height, width } = useWindowSize({

packages/component-library/vitest.web.config.ts

@@ -1,21 +1,7 @@
-import path from 'path';
-
 import react from '@vitejs/plugin-react';
 import peggyLoader from 'vite-plugin-peggy-loader';
 import { defineConfig } from 'vitest/config';
 
-const resolveExtensions = [
-  '.testing.ts',
-  '.mjs',
-  '.js',
-  '.mts',
-  '.ts',
-  '.jsx',
-  '.tsx',
-  '.json',
-  '.wasm',
-];
-
 export default defineConfig({
   test: {
     environment: 'jsdom',
@@ -23,8 +9,5 @@ export default defineConfig({
     include: ['src/**/*.web.test.(js|jsx|ts|tsx)'],
     maxWorkers: 2,
   },
-  resolve: {
-    extensions: resolveExtensions,
-  },
   plugins: [react(), peggyLoader()],
 });