@mapctx/sync-engine (alpha)

Standalone npm package + CLI to sync local TASKS.md with GitHub Issues and GitHub Projects (v2).

Status: alpha. APIs, config keys, and sync behavior may change before 1.0.0.

Detailed operational guide: DOCUMENTATION.md.

Install

npm install @mapctx/sync-engine

Run with npx:

npx --yes --package @mapctx/sync-engine mapcs status

Release/maintainer process: see MAINTAINERS.md.

Use as library

import { pullCommand, pushCommand, statusCommand } from '@mapctx/sync-engine';

statusCommand({ configPath: 'mapcs.dev.json' });

CLI commands

• mapcs status
• mapcs pull
• mapcs push
• mapcs bootstrap --from <local|github>
• mapcs reconcile <task-id>
• mapcs reconcile --list

Common flags:

• --dry-run
• --force
• --accept <local|remote>
• --config <path>
• --tasks-file <path>

Important files

• Main config: mapcs.config.json
• Config template: mapcs.config.example.json
• Local sync state: .mapcs/state.json
• Conflict artifacts: .mapcs/conflicts/<task-id>.reconcile.md

Daily flow

mapcs pull
mapcs status
mapcs push

Safety rule: always run pull before push in the same session.

Bootstrap

Local-first (TASKS.md -> GitHub):

mapcs bootstrap --from local --dry-run --confirm
mapcs bootstrap --from local --confirm

Remote-first (GitHub -> TASKS.md):

mapcs bootstrap --from github --dry-run
mapcs bootstrap --from github

Reconciliation

mapcs reconcile --list
mapcs reconcile T-002
mapcs reconcile T-002 --accept local
mapcs reconcile T-002 --accept remote
mapcs push

GitHub auth scopes

To sync Issues and Projects v2, your gh token needs:

• repo
• read:project
• project

Refresh scopes:

gh auth refresh -h github.com -s repo,read:project,project
gh auth status

Dev quickstart

From packages/sync-engine/:

npm install
npm run build
node dist/cli.js status --config mapcs.dev.json
node dist/cli.js pull --dry-run --config mapcs.dev.json
node dist/cli.js push --dry-run --config mapcs.dev.json