feat: Add modifyJSON for atomic operations in legacy utils.js

[bjcoombs]

Summary

• Adds modifyJSON() function for atomic read-modify-write operations
• Marks writeJSON() as deprecated with migration guidance
• Addresses part 2 of Clean up FileStorage resource leaks and legacy utils.js concurrency #1585 (legacy utils.js pattern)

Changes Made

scripts/modules/utils.js:

• Added modifyJSON(filepath, modifier, options) function that:
  • Reads the file inside the lock
  • Applies the modifier callback
  • Writes the result atomically
  • Prevents race conditions from stale reads
• Marked writeJSON() as @deprecated with guidance to use modifyJSON()
• Exported modifyJSON for use by callers

Technical Details

The new modifyJSON function follows the same pattern as @tm/core's TypeScript modifyJson:

// Before (race-prone):
const data = readJSON(filepath);
data.tasks.push(newTask);
writeJSON(filepath, data);

// After (atomic):
modifyJSON(filepath, (data) => {
    data.tasks.push(newTask);
    return data;
});

Test plan

• Format check passes
• CI checks

Related

• Closes part 2 of Clean up FileStorage resource leaks and legacy utils.js concurrency #1585
• PR fix: Ensure FileStorage.close() is called in export operations #1586 addresses part 1 (FileStorage cleanup)

Summary by CodeRabbit

• New Features
  • Added an atomic JSON modification utility to safely perform read‑modify‑write operations with integrated file-locking to prevent concurrent data corruption.
• Deprecated
  • Marked the previous JSON write helper as deprecated in favor of the new atomic modify flow.
• Chores
  • Exposed the underlying file-operations capability via the public API so consumers can use the atomic utility.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 048d71b

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds an atomic JSON modification utility modifyJSON to legacy scripts/modules/utils.js and exposes FileOperations from packages/tm-core public API; includes a changeset documenting the addition and marks writeJSON deprecated for atomic RMW usage.

Changes

Cohort / File(s)	Summary
Changeset Documentation \.changeset/add-modifyjson-utils.md``	Adds a changeset documenting a patch release that introduces the new modifyJSON utility.
Atomic JSON Modifier Utility \scripts/modules/utils.js``	Adds exported modifyJSON(filepath, modifier) that delegates to a shared FileOperations instance for atomic read-modify-write; adds lazy getFileOps() initializer and updates JSDoc (marks writeJSON deprecated for atomic RMW).
Public API Export \packages/tm-core/src/index.ts``	Exposes FileOperations from storage adapters in the tm-core public exports to enable cross-module atomic file operations.

Sequence Diagram(s)

(omitted — changes do not meet criteria for sequence diagram generation)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• #1585: Adds a modifyJSON callback-based API and shared file-ops — aligns with this PR's addition of modifyJSON and FileOperations export.

Possibly related PRs

• #1569: Modifies file-storage to call FileOperations.modifyJson, operating on the same atomic modification path as this PR.
• #1566: Introduces a modifyJSON utility and shared FileOperations usage — strong overlap with this PR.

Suggested reviewers

• Crunchyman-ralph

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding modifyJSON for atomic operations in legacy utils.js, which is the primary focus of all three file modifications.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Crunchyman-ralph]

some small change, please rebase and make sure the CI is passing.

Thanks for the awesome contribs!!!!

[Crunchyman-ralph]

Too verbose, changelog should be client-facing

[bjcoombs]

Done - simplified to: "Add modifyJSON function for safer file updates"

[Crunchyman-ralph]

you can import the typescript modifyJson into the javascript, so do that instead :D

[bjcoombs]

Done - now imports FileOperations from @tm/core and delegates to fileOps.modifyJson()

[bjcoombs]

I've addressed the feedback:

1. Simplified the changeset to be client-facing: "Add modifyJSON function for safer file updates"

2. Imported TypeScript modifyJson instead of reimplementing - The modifyJSON function in utils.js now wraps FileOperations.modifyJson from @tm/core:

   • Exported FileOperations from @tm/core
   • modifyJSON() is now a thin wrapper that delegates to fileOps.modifyJson()
   • Also marked writeJSON() as @deprecated with guidance to use modifyJSON()

The branch is rebased on latest main. Ready for re-review.

[bjcoombs]

I've addressed the feedback:

1. Simplified the changeset to be client-facing: 'Add modifyJSON function for safer file updates'

2. Imported TypeScript modifyJson instead of reimplementing - The modifyJSON function in utils.js now wraps FileOperations.modifyJson from @tm/core:

   • Exported FileOperations from @tm/core
   • modifyJSON() is now a thin wrapper that delegates to fileOps.modifyJson()
   • Also marked writeJSON() as @deprecated with guidance to use modifyJSON()

The branch is rebased on latest main. Ready for re-review.

[Crunchyman-ralph]

@bjcoombs rebase onto next and then lets merge!

[bjcoombs]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.