Multiplatform Note-Taking CLI Sync Tool

Project roadmap

1. 01

   Set up the multiplatform project

   ~2h

   Create a Gradle project with the Kotlin Multiplatform plugin and two targets, jvm and linuxX64 (with an executable binary), plus a commonMain source set. Add kotlinx.serialization and the Ktor client (with the CIO engine for JVM and the Curl engine for native). Print Hello from common code on both targets. Done when: both the JVM program and the native executable run and print the message.

2. 02

   Store notes locally

   ~2h

   Define a Note class (id, title, body, updatedAt and a deleted flag) with @Serializable. Declare expect functions for reading, writing, listing and deleting files in commonMain, and implement them with actual code: java.io.File on the JVM and okio (which supports both) or POSIX calls on native. Store each note as a JSON file in ~/.notes. Done when: notes saved by one build can be read by the other.

3. 03

   Build the commands

   ~1.5h

   Write the command handling in common code: add "title" "body", list, show ID, edit ID, delete ID (marking it deleted so the deletion can be synced) and sync. Parse the arguments with a small parser of your own (or kotlinx-cli), with clear usage and error messages. Done when: every command works on both targets.

4. 04

   Sync with the server

   ~2.5h

   Write (or reuse) a small REST server with GET /notes?since= and PUT /notes/{id}. In shared code, use the Ktor client to push notes changed since the last sync and pull notes changed on the server, saving the last sync time. Handle network errors with a clear message, and never lose local changes when a sync fails. Done when: notes added on one machine appear on another after sync.

5. 05

   Resolve conflicts

   ~1.5h

   When the same note changed on both sides since the last sync, keep the version with the newer updatedAt (last write wins), and save the losing version as a separate conflict copy so nothing is silently lost. Deletions win over older edits. Print a summary of what was pushed, pulled and in conflict. Done when: editing the same note on two machines produces a clear result and a conflict copy.

6. 06

   Test it

   ~1.5h

   Write tests in commonTest (run on both targets) for the note serialization, argument parsing and conflict resolution, and tests for the sync logic using Ktor's MockEngine. Done when: ./gradlew allTests passes.

Resources

• DocsKotlin Multiplatform documentation
• DocsKotlin Multiplatform: expected and actual declarations
• DocsKtor client engines
• Docskotlinx.serialization guide
• DocsOkio: multiplatform file system