synctax 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to Synctax are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [2.0.0] — 2026-04-05
+
+### Initial Release
+
+**Synctax** — Universal Sync for the Agentic Developer Stack.
+
+#### Core Sync Engine
+- `synctax sync` — atomic push to all enabled clients with pre-sync snapshots and rollback on failure
+- `synctax pull --from <client>` — import a client's live config into master config
+- `synctax watch` — background daemon that auto-syncs on `~/.synctax/config.json` save (500ms debounce)
+- `synctax memory-sync` — copy source client's context/memory file to all other enabled clients
+- `--dry-run`, `--yes`, `--strict-env`, `--interactive` flags on sync
+
+#### Inspection & Diagnostics
+- `synctax status` — health overview: drift state, resource counts, env var resolution
+- `synctax diff [client]` — preview changes without writing; `--json` for machine-readable output
+- `synctax doctor [--deep]` — diagnose missing clients, broken paths, invalid env vars; `--deep` verifies MCP binary existence
+- `synctax validate` — schema validation, env var resolution, required PATH binary check
+
+#### Config Management
+- `synctax add <type> <name>` — add MCP server, agent, or skill interactively or via flags; `--from <url>` to import from URL/gist
+- `synctax remove [type] [name]` — remove a resource (interactive with `-i`)
+- `synctax move <type> <name>` — move resource between scopes (`--to-global`, `--to-local`, `--to-project`)
+
+#### Profile System
+- `synctax profile create <name>` — create a named resource filter profile
+- `synctax profile use <name>` — switch active profile and sync immediately
+- `synctax profile list` — list profiles with active marker
+- `synctax profile diff <name>` — preview changes before switching profiles
+- `synctax profile pull <url>` — import a profile from a URL
+- `synctax profile publish <name>` — export shareable profile (credentials automatically stripped)
+
+#### Backup & Portability
+- `synctax backup [--rollup]` — per-client zip backups; `--rollup` creates a combined archive
+- `synctax restore [--from <timestamp>]` — restore master config from backup
+- `synctax export <file>` — export master config to JSON (credentials stripped)
+- `synctax import <file>` — import master config from JSON
+- `synctax link` / `synctax unlink` — symlink memory/instruction files to a single source
+
+#### Interactive Fullscreen TUI
+- `synctax` (no args) — fullscreen dashboard with live status, diagnostics, quick actions, command palette
+- 16 built-in color themes: synctax, catppuccin, dracula, nord, tokyo-night, gruvbox, one-dark, solarized, rose-pine, monokai, cyberpunk, sunset, ocean, forest, ember, aurora
+- Keyboard-driven: number keys for quick actions, `/` for command palette, `t` for theme switcher, `?` for help
+
+#### 9 Supported Clients
+Claude Code, Cursor, GitHub Copilot (VS Code), GitHub Copilot CLI, OpenCode, Cline, Zed, Antigravity, Gemini CLI
+
+#### Security
+- Deny-wins permission merge: deny lists always override allow lists
+- Credentials never exported (stripped from all `export` / `profile publish` outputs)
+- Per-profile `.env` files (0600 permissions, never synced or published)
+- Path-traversal protection on all file operations
+- Atomic temp-file writes with rename for crash safety
+
+[2.0.0]: https://github.com/Kaos599/synctax/releases/tag/v2.0.0

package/README.md

@@ -0,0 +1,262 @@
+<p align="center">
+  <img src="assets/banner.svg" alt="Synctax" width="480">
+</p>
+
+<p align="center"><strong>Universal Sync for the Agentic Developer Stack</strong></p>
+<p align="center">Configure once. Sync your MCP servers, agents, skills, and permissions to every AI tool you use.</p>
+
+<p align="center">
+  <a href="https://github.com/Kaos599/Synctax/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Kaos599/Synctax/actions/workflows/ci.yml/badge.svg" /></a>
+  <img alt="version" src="https://img.shields.io/github/package-json/v/Kaos599/Synctax?color=brightgreen" />
+  <img alt="license" src="https://img.shields.io/github/license/Kaos599/Synctax?color=blue" />
+  <img alt="runtime" src="https://img.shields.io/badge/runtime-bun-orange" />
+  <img alt="clients" src="https://img.shields.io/badge/clients-9%20supported-lightgrey" />
+</p>
+
+<p align="center"><code>synctax sync</code> — one command, every AI tool in sync.</p>
+
+---
+
+## Why Synctax
+
+Every AI coding tool stores configuration in its own proprietary format. Claude Code reads `~/.claude/settings.json`. Cursor uses `~/.cursor/mcp.json`. Zed has `~/.config/zed/settings.json`. Cline, OpenCode, GitHub Copilot, and Gemini CLI each have their own layouts, their own field names, and their own ideas about where agents and skills belong.
+
+Add one MCP server and you are editing four JSON files by hand. Rename an agent and you are hunting through six different directories. Forget to update one client and your tools are silently out of sync for weeks.
+
+Synctax eliminates this. One master config at `~/.synctax/config.json`. One command to push it everywhere. Every resource — MCP servers, agents, skills, permissions, model preferences, prompts, memory files — translated into each client's native format automatically.
+
+---
+
+## Install
+
+**Prerequisites:** [Bun](https://bun.sh) v1.0+
+
+```bash
+git clone https://github.com/Kaos599/synctax.git
+cd synctax
+bun install
+bun ./bin/synctax.ts init
+bun ./bin/synctax.ts sync
+```
+
+After `init` completes its optional PATH setup, you can use the short form everywhere:
+
+```bash
+synctax init
+synctax sync
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Initialize master config and enable your installed clients
+synctax init
+
+# 2. Pull your existing config from whichever client you use most
+synctax pull --from cursor
+
+# 3. Add a new MCP server to master config
+synctax add mcp my-db --command npx --args "-y" "@modelcontextprotocol/server-postgres" --env DB_URL=\$MY_DB_URL
+
+# 4. Check for issues before writing
+synctax doctor
+
+# 5. Push everything to all enabled clients
+synctax sync
+```
+
+---
+
+## Commands
+
+### Core
+
+| Command | Description |
+|---------|-------------|
+| `synctax sync` | Pulls from your source client, shows a per-client diff, asks for confirmation, then writes to every enabled client atomically. Rolls back all clients on failure. Run this after any change to master config. |
+| `synctax pull --from <client>` | Imports a specific client's live config into master. Use this when you've added an MCP directly in Cursor or Claude Code and want master to reflect it. |
+| `synctax diff [client]` | Compares master against each client's live config and shows exactly what has been added, removed, or modified — without writing anything. Safe to run at any time. |
+| `synctax watch` | Starts a background daemon that watches `~/.synctax/config.json` and auto-syncs on every save (500ms debounce). Useful when editing master config directly. |
+| `synctax memory-sync` | Copies your source client's memory/context file (e.g. `CLAUDE.md`) to all other enabled clients in the current project directory. |
+
+### Inspection
+
+| Command | Description |
+|---------|-------------|
+| `synctax status` | Health overview across all clients — shows sync state, resource counts, and env var status at a glance. |
+| `synctax doctor [--deep]` | Diagnoses common issues: missing clients, broken config paths, invalid env vars. With `--deep`, also verifies each MCP command exists on PATH. |
+| `synctax validate` | Runs Zod schema validation on master config, checks env var references can resolve, and confirms required binaries are reachable before syncing. |
+
+### Config Management
+
+| Command | Description |
+|---------|-------------|
+| `synctax add <type> <name>` | Adds an MCP server, agent, or skill to master config interactively or via flags. |
+| `synctax remove [type] [name]` | Removes a resource. Use `-i` for interactive selection. |
+| `synctax move <type> <name>` | Changes the scope of a resource (`--to-global`, `--to-local`, `--to-project`). |
+
+### Profiles
+
+| Command | Description |
+|---------|-------------|
+| `synctax profile create <name>` | Creates a named profile with `--include` / `--exclude` resource filters. Each profile gets its own `.env` file for secrets. |
+| `synctax profile use <name>` | Switches to a profile and immediately syncs — swaps env context and filters, then pushes to all clients. |
+| `synctax profile list` | Lists all profiles with their filters and marks the active one. |
+| `synctax profile diff <name>` | Dry-run preview of what would change if you switched to this profile, without switching. |
+| `synctax profile pull <url>` | Downloads and imports a shared profile from a URL. Credentials are never included. |
+| `synctax profile publish <name>` | Exports a profile to a shareable JSON file with credentials automatically stripped. |
+
+<details>
+<summary>Safety &amp; backup commands</summary>
+
+| Command | Description |
+|---------|-------------|
+| `synctax backup` | Archives each enabled client's current native config files into a timestamped zip at `~/.synctax/backups/`. Run before risky changes. |
+| `synctax restore [--from <ts>]` | Restores master config from a backup. Uses most recent by default; pass a timestamp for a specific point in time. |
+| `synctax export <file>` | Exports the full master config to a portable JSON file (credentials stripped). |
+| `synctax import <file>` | Imports a master config from a JSON file. |
+| `synctax link` / `synctax unlink` | Creates symlinks so all client instruction files point to one canonical file, or restores them as regular files. |
+
+</details>
+
+### Sync Flags
+
+```bash
+synctax sync --dry-run        # Preview changes without writing
+synctax sync --yes            # Skip confirmation (for scripts, CI)
+synctax sync --strict-env     # Fail if env vars can't resolve
+synctax sync --interactive    # Select which resources to sync
+```
+
+---
+
+## Supported Clients
+
+| Client | MCP | Agents | Skills | Memory File |
+|--------|-----|--------|--------|-------------|
+| Claude Code | ✅ | ✅ | ✅ | `CLAUDE.md` |
+| Cursor | ✅ | ✅ | ✅ | `.cursorrules` |
+| GitHub Copilot | ✅ | ✅ | ✅ | `.github/copilot-instructions.md` |
+| GitHub Copilot CLI | ✅ | ✅ | ✅ | `.github/copilot-instructions.md` |
+| OpenCode | ✅ | ✅ | ✅ | `AGENTS.md` |
+| Antigravity | ✅ | ✅ | ✅ | `.antigravityrules` |
+| Cline | ✅ | — | — | `.clinerules` |
+| Zed | ✅ | — | — | `.rules` |
+| Gemini CLI | — | — | — | `.geminirules` |
+
+---
+
+## How Sync Works
+
+```
+synctax sync
+       │
+       ├─ 1. Pull from source client
+       │       Read live config → merge into master (deny-wins for permissions)
+       │
+       ├─ 2. Apply active profile filters
+       │       include/exclude lists trim the resource set
+       │
+       ├─ 3. Resolve env vault
+       │       $VAR references → real values from ~/.synctax/envs/<profile>.env
+       │
+       ├─ 4. Show diff preview per client
+       │       added / removed / modified resources listed before any write
+       │
+       ├─ 5. Confirm: "Apply these changes? [y/N]"
+       │
+       └─ 6. Atomic write to all enabled clients
+               temp-file → rename · file lock · rollback on failure
+```
+
+**Safety guarantees:**
+
+- Every client config is read before being written — Synctax fields are overlaid, not overwritten.
+- All writes go to a temp file first, then renamed atomically. A crash mid-write leaves the original intact.
+- If any client write fails, all clients that already received changes in this run are rolled back.
+- Permission merges use deny-wins logic: if a path appears in both allow and deny lists, it is denied.
+
+---
+
+## Env Vault
+
+Secrets never live in master config. Use `$VAR` references in config and store real values in a per-profile `.env` file that stays local.
+
+```json
+// ~/.synctax/config.json — safe to commit or share
+{
+  "mcps": {
+    "my-db": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres"],
+      "env": { "DB_URL": "$MY_DB_URL" }
+    }
+  }
+}
+```
+
+```bash
+# ~/.synctax/envs/default.env — stays local, never exported
+MY_DB_URL=postgres://user:pass@prod.db.internal:5432/app
+```
+
+When syncing, `$MY_DB_URL` is resolved to the real value before writing to each client. The reference string is what gets synced; the secret is what gets injected at write time.
+
+---
+
+## Fullscreen TUI
+
+Run `synctax` with no arguments to open the fullscreen dashboard.
+
+- Live status panel: connected clients, MCP counts, agent counts, drift indicators
+- Quick actions grid: bind common commands to number keys (1–9, 0)
+- Command palette: fuzzy-search all commands with `/` or `p`
+- Source selector: pick which client to pull from interactively
+- Diagnostics panel: warnings and config issues surfaced in real time
+- 16 built-in themes: `synctax`, `catppuccin`, `dracula`, `nord`, `tokyo-night`, `gruvbox`, `one-dark`, `solarized`, `rose-pine`, `monokai`, `cyberpunk`, `sunset`, `ocean`, `forest`, `ember`, `aurora` — press `t` to cycle
+
+---
+
+## Profiles
+
+Profiles are named resource filters that let you maintain different sync configurations for different contexts — work vs. personal, frontend vs. backend, client A vs. client B — without maintaining separate master configs. Each profile has its own `.env` file so secrets are scoped too.
+
+```bash
+# Create a work profile that only includes work-related MCPs and agents
+synctax profile create work --include my-db,github,jira-agent,code-reviewer
+
+# Switch to it (syncs immediately with the filtered resource set)
+synctax profile use work
+
+# Preview what switching to personal would change before committing
+synctax profile diff personal
+```
+
+---
+
+## Development
+
+```bash
+# Run all tests
+bun run test
+
+# Type-check (strict, no emit)
+bun run typecheck
+
+# Lint
+bun run lint
+
+# Run a single test file
+bunx vitest run tests/adapters.test.ts
+
+# Run the CLI directly
+bun ./bin/synctax.ts <command>
+```
+
+---
+
+## License
+
+MIT