composer-sync

CLI daemon that mirrors a local folder tree to and from Composer.

Quick start

composer-sync login
composer-sync connect ~/notes --into <composerFolderId>
composer-sync watch ~/notes

Central-vault workflow

The central-vault pattern is the recommended setup for teams or individuals who want one canonical cloud-mirrored store and need to work on individual files from multiple project directories.

Concepts

• Vault root: a single folder connected to Composer via composer-sync connect. All synced files live here as real files in nested subdirectories. The daemon watches only this folder.

• Project symlinks: instead of copying vault files into each project, create symlinks that point from your project directory into the vault. Editing through a symlink edits the real vault file, which the daemon picks up on the next sync pass.

• Why symlinks must live outside the vault root: the daemon skips symlinks when scanning. Placing a symlink inside the vault root would cause it to be ignored. Place symlinks in project directories that are NOT under the vault.

Blessed layout

~/ComposerVault/          <- sync root (composer-sync connect here)
  projects/
    alpha/
      spec.md
      notes.md
  shared/
    brand-guidelines.md

~/work/project-alpha/     <- NOT the sync root
  spec.md -> ~/ComposerVault/projects/alpha/spec.md
  notes.md -> ~/ComposerVault/projects/alpha/notes.md

~/work/project-beta/
  brand-guidelines.md -> ~/ComposerVault/shared/brand-guidelines.md

Setting up the vault

# Connect the vault root to a Composer folder.
composer-sync connect ~/ComposerVault --into <composerFolderId>

# Seed files, then sync.
mkdir -p ~/ComposerVault/projects/alpha
echo "# Spec" > ~/ComposerVault/projects/alpha/spec.md
composer-sync once ~/ComposerVault

link: create project symlinks

composer-sync link ~/ComposerVault ~/work/project-alpha \
  --files projects/alpha/spec.md,projects/alpha/notes.md

This creates ~/work/project-alpha/spec.md and ~/work/project-alpha/notes.md as symlinks pointing into the vault. The command is idempotent: running it again with the same arguments skips already-correct symlinks.

If a real file already exists at a would-be link path, it is skipped and reported. The real file is never overwritten by link.

Constraint: projectDir must be outside vaultRoot. Passing a path inside the vault root is rejected with an error.

doctor: detect the atomic-save orphan hazard

Some editors (Vim, some GUI tools, Emacs with auto-save) write to a temporary file and then rename() it into place. On Linux and macOS, this rename() call replaces a symlink with a real file. The vault's copy is then stale or absent, and the daemon cannot see the edit (the real file is outside the vault).

Run doctor periodically or after editor sessions that touch linked files:

composer-sync doctor ~/ComposerVault ~/work/project-alpha

If any orphans are found the command exits 1 and prints the relink command to fix each one. Exit 0 means everything is healthy.

relink: restore a broken symlink with no data loss

composer-sync relink ~/ComposerVault ~/work/project-alpha projects/alpha/spec.md

Steps performed by relink:

1. Read the orphan content from the project directory.
2. Compare it with the vault file. If they differ (or the vault file is absent), write the orphan content into the vault first. No data is lost.
3. Remove the real file from the project directory.
4. Create the symlink from the project file to the vault file.

After relink, running composer-sync once ~/ComposerVault pushes any rescued content to Composer.

Many-roots alternative

If symlinks are inconvenient (e.g., on Windows or in containers), connect each project directory as its own sync root:

composer-sync connect ~/work/project-alpha --into <alphaFolderId>
composer-sync connect ~/work/project-beta --into <betaFolderId>

Each root runs its own manifest and sync cycle. Files are not shared between roots; sharing happens at the Composer folder level.

General symlink-follow-in (unsupported)

The daemon does not follow symlinks inside the vault root. Only the blessed vault layout (real files in the vault, symlinks in project dirs outside the vault) is supported. Support for general symlink traversal is deferred.

Commands

| Command | Description | |---------|-------------| | login | Sign in to Composer (opens a browser) | | logout | Sign out | | connect <folder> --into <folderId> | Connect a local folder and run an initial sync | | disconnect [<folder>] | Stop syncing a folder | | watch [<folder>] | Continuously sync both ways | | once [<folder>] | One sync pass (push local, pull remote) | | daemon <cmd> | Manage a background launchd service (macOS) | | mv <from> <to> | Rename/move a synced file, preserving its Composer identity | | link <vault> <dir> | Create project symlinks into the vault | | doctor <vault> <dir...> | Detect atomic-save orphan hazard | | relink <vault> <dir> <rel> | Restore a broken symlink, rescuing orphan content | | resolve <path> | Resolve a blocked conflict | | restore-to-device <path> | Restore a locally detached file from Composer | | status | Show sync status for all connected folders |

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | COMPOSER_APP_BASE | https://usecomposer.md | Composer server base URL | | COMPOSER_CONFIG_DIR | ~/.composer | Auth/token directory |