zedx 0.9.0 → 0.10.0

package/README.md

@@ -1,6 +1,10 @@
-# zedx
+<div align="center">
 
-Scaffold [Zed Editor](https://zed.dev/) extensions and sync your settings across machines.
+<img src="./assets/zedx-logo.png" width="300" alt="ZedX Logo" />
+
+CLI toolkit for Scaffolding [Zed Editor](https://zed.dev/) extensions and syncing settings across machines.
+
+</div>
 
 ![screenshot](./assets/screenshot1.png)
 
@@ -13,7 +17,9 @@ npm install -g zedx
 brew install tahayvr/tap/zedx
 ```
 
-### Usage
+## Usage
+
+### Scaffolding an extension
 
 ```bash
 # Create a new extension
@@ -22,28 +28,77 @@ zedx create
 # Add a theme or language to an existing extension
 zedx add theme "Midnight Blue"
 zedx add language rust
+```
+
+### Supported extension types:
+
+1. **Themes** - Color schemes for the editor
+2. **Languages** - Syntax highlighting, indentation, and optional LSP support
+
+You can choose to include theme, language, or both when creating an extension.
+
+### Validation
 
+```bash
 # Validate extension config and show what is missing or incomplete
 zedx check
+```
+
+### Sync
+
+Sync your Zed config across machines using a private GitHub repo as the source of truth.
+
+**1. Link a repo (one-time setup)**
+
+```bash
+zedx sync init
+```
+
+Prompts for a GitHub repo URL (SSH or HTTPS) and a branch name (defaults to `main`). The repo is saved to `~/.config/zedx/config.json`. No files are synced yet.
+
+> [!NOTE]
+> `settings.json` and `keymap.json` are tracked. Extension sync is handled via the `auto_install_extensions` field within `settings.json`, which Zed uses to automatically download and install extensions.
+
+**2. Run a sync**
 
-# Bump extension version
+```bash
+zedx sync            # Sync local ↔ remote, prompts when both sides changed
+zedx sync --local    # Always keep local on conflict (no prompt)
+zedx sync --remote   # Always use remote on conflict (no prompt)
+```
+
+**3. Check sync state**
+
+```bash
+zedx sync status
+```
+
+**4. Auto-sync with an OS daemon**
+
+```bash
+zedx sync install    # Install and enable the daemon
+zedx sync uninstall  # Disable and remove the daemon
+```
+
+Installs a file-watcher that triggers `zedx sync` automatically whenever config files are saved. Supported platforms:
+
+| Platform | Mechanism                                              | Logs                                     |
+| -------- | ------------------------------------------------------ | ---------------------------------------- |
+| macOS    | launchd (`~/Library/LaunchAgents/dev.zedx.sync.plist`) | `~/Library/Logs/zedx-sync.log`           |
+| Linux    | systemd user units (`~/.config/systemd/user/`)         | `journalctl --user -u zedx-sync.service` |
+
+The daemon enforces a 30-second throttle on macOS to avoid rapid re-triggers. When a conflict is detected in daemon mode (no TTY), local always wins and a warning is logged.
+
+### Versioning
+
+Bump the extension version:
+
+```bash
 zedx version patch   # 1.2.3 → 1.2.4
 zedx version minor   # 1.2.3 → 1.3.0
 zedx version major   # 1.2.3 → 2.0.0
-
-# Sync Zed settings and extensions via a GitHub repo
-zedx sync init       # Link a GitHub repo as the sync target (run once)
-zedx sync            # Sync local and remote config (prompts on conflict)
-zedx sync --local    # Sync, always keeping local on conflict
-zedx sync --remote   # Sync, always using remote on conflict
-zedx sync status     # Show sync state between local config and the remote repo
-zedx sync install    # Install an OS daemon to auto-sync when Zed config changes
-zedx sync uninstall  # Remove the OS daemon
 ```
 
-### Supported extension types:
+### License
 
-1. **Themes** - Color schemes for the editor
-2. **Languages** - Syntax highlighting, indentation, and optional LSP support
-
-You can choose to include theme, language, or both when creating an extension.
+License is Apache-2.0. See [LICENSE](./LICENSE) for details.

package/dist/daemon.js

@@ -157,7 +157,7 @@ export async function syncInstall() {
     if (platform !== 'darwin' && platform !== 'linux')
         unsupportedPlatform();
     const zedPaths = resolveZedPaths();
-    const watchPaths = [zedPaths.settings, zedPaths.extensions];
+    const watchPaths = [zedPaths.settings, zedPaths.keymap];
     const zedxBin = resolveZedxBinary();
     p.log.info(`Binary:  ${color.dim(zedxBin)}`);
     p.log.info(`Watching:`);

package/dist/sync.js

@@ -37,76 +37,66 @@ async function withTempDir(fn) {
         await fs.remove(tmp);
     }
 }
-// Prepare settings.json for pushing to the repo by stripping auto_install_extensions.
-// That field is derived from extensions/index.json on pull, so storing it in the
-// remote would create stale/conflicting data across machines.
-async function prepareSettingsForPush(localSettingsPath, repoSettingsPath) {
-    const raw = await fs.readFile(localSettingsPath, 'utf-8');
-    const stripped = raw.replace(/\/\/[^\n]*/g, '');
-    let settingsObj = {};
-    try {
-        settingsObj = JSON.parse(stripped);
-    }
-    catch {
-        // If we can't parse it (e.g. complex comments), push as-is
-        await fs.ensureDir(path.dirname(repoSettingsPath));
-        await fs.copy(localSettingsPath, repoSettingsPath, { overwrite: true });
+// Before every push, reconcile auto_install_extensions in settings.json against
+// the live extensions/index.json so that:
+//   - newly installed extensions (present in index, missing from the list) are added as true
+//   - uninstalled extensions (absent from index, set to true in the list) are removed
+//   - entries explicitly set to false by the user are always preserved (user intent)
+async function reconcileAutoInstallExtensions(localSettingsPath, localExtensionsIndexPath, silent = false) {
+    if (!(await fs.pathExists(localExtensionsIndexPath)))
         return;
-    }
-    delete settingsObj['auto_install_extensions'];
-    await fs.ensureDir(path.dirname(repoSettingsPath));
-    await fs.writeFile(repoSettingsPath, JSON.stringify(settingsObj, null, 4), 'utf-8');
-}
-// Extension merge helper
-async function applyRemoteSettings(repoSettings, repoExtensions, localSettingsPath, silent = false) {
-    // Backup existing settings
+    let settingsObj = {};
     if (await fs.pathExists(localSettingsPath)) {
-        await fs.copy(localSettingsPath, localSettingsPath + '.bak', { overwrite: true });
-        if (!silent)
-            p.log.info(`Backed up settings to ${color.dim(localSettingsPath + '.bak')}`);
-    }
-    let settingsJson = await fs.readFile(repoSettings, 'utf-8');
-    // Merge auto_install_extensions from index.json into settings
-    if (await fs.pathExists(repoExtensions)) {
         try {
-            const indexJson = (await fs.readJson(repoExtensions));
-            const extensionIds = Object.keys(indexJson.extensions ?? {}).filter(id => !indexJson.extensions[id]?.dev);
-            if (extensionIds.length > 0) {
-                const stripped = settingsJson.replace(/\/\/[^\n]*/g, '');
-                let settingsObj = {};
-                try {
-                    settingsObj = JSON.parse(stripped);
-                }
-                catch {
-                    if (!silent)
-                        p.log.warn(color.yellow('Could not parse settings.json — skipping extension merge.'));
-                }
-                // Preserve any existing entries (e.g. false entries for "never install"),
-                // then add true for every extension recorded in index.json.
-                const existing = typeof settingsObj['auto_install_extensions'] === 'object' &&
-                    settingsObj['auto_install_extensions'] !== null
-                    ? settingsObj['auto_install_extensions']
-                    : {};
-                const autoInstall = { ...existing };
-                for (const id of extensionIds) {
-                    // Only set to true if there is no explicit user preference already
-                    if (!(id in autoInstall)) {
-                        autoInstall[id] = true;
-                    }
-                }
-                settingsObj['auto_install_extensions'] = autoInstall;
-                settingsJson = JSON.stringify(settingsObj, null, 4);
-                if (!silent)
-                    p.log.info(`Injected ${color.cyan(String(extensionIds.length))} extension(s) into ${color.dim('auto_install_extensions')}`);
-            }
+            const raw = await fs.readFile(localSettingsPath, 'utf-8');
+            settingsObj = JSON.parse(raw.replace(/\/\/[^\n]*/g, ''));
         }
         catch {
             if (!silent)
-                p.log.warn(color.yellow('Could not parse extensions/index.json — skipping extension merge.'));
+                p.log.warn(color.yellow('Could not parse settings.json — skipping extension reconciliation.'));
+            return;
         }
     }
+    let installedIds = [];
+    try {
+        const indexJson = (await fs.readJson(localExtensionsIndexPath));
+        installedIds = Object.keys(indexJson.extensions ?? {}).filter(id => !indexJson.extensions[id]?.dev);
+    }
+    catch {
+        if (!silent)
+            p.log.warn(color.yellow('Could not parse extensions/index.json — skipping extension reconciliation.'));
+        return;
+    }
+    const existing = typeof settingsObj['auto_install_extensions'] === 'object' &&
+        settingsObj['auto_install_extensions'] !== null
+        ? settingsObj['auto_install_extensions']
+        : {};
+    const installedSet = new Set(installedIds);
+    const reconciled = {};
+    // Keep all explicit false entries (user said "never install this")
+    for (const [id, val] of Object.entries(existing)) {
+        if (val === false)
+            reconciled[id] = false;
+    }
+    // Add every currently installed extension as true
+    for (const id of installedIds) {
+        reconciled[id] = true;
+    }
+    // Drop true entries for extensions no longer installed
+    // (already handled — we only re-add what's in installedSet above)
+    const added = installedIds.filter(id => !(id in existing));
+    const removed = Object.keys(existing).filter(id => existing[id] === true && !installedSet.has(id));
+    if (added.length === 0 && removed.length === 0)
+        return;
+    settingsObj['auto_install_extensions'] = reconciled;
     await fs.ensureDir(path.dirname(localSettingsPath));
-    await fs.writeFile(localSettingsPath, settingsJson, 'utf-8');
+    await fs.writeFile(localSettingsPath, JSON.stringify(settingsObj, null, 4), 'utf-8');
+    if (!silent) {
+        if (added.length > 0)
+            p.log.info(`Added ${color.cyan(String(added.length))} new extension(s) to ${color.dim('auto_install_extensions')}: ${added.join(', ')}`);
+        if (removed.length > 0)
+            p.log.info(`Removed ${color.cyan(String(removed.length))} uninstalled extension(s) from ${color.dim('auto_install_extensions')}: ${removed.join(', ')}`);
+    }
 }
 // zedx sync status
 export async function syncStatus() {
@@ -138,14 +128,18 @@ export async function syncStatus() {
             {
                 repoPath: path.join(tmp, 'settings.json'),
                 localPath: zedPaths.settings,
-                label: 'settings.json',
+                label: 'Settings',
             },
             {
-                repoPath: path.join(tmp, 'extensions', 'index.json'),
-                localPath: zedPaths.extensions,
-                label: 'extensions/index.json',
+                repoPath: path.join(tmp, 'keymap.json'),
+                localPath: zedPaths.keymap,
+                label: 'Key bindings',
             },
         ];
+        // Track per-file actions needed for the outro message
+        const toPush = [];
+        const toPull = [];
+        const toResolve = [];
         for (const file of files) {
             const localExists = await fs.pathExists(file.localPath);
             const remoteFileExists = remoteExists && (await fs.pathExists(file.repoPath));
@@ -155,10 +149,12 @@ export async function syncStatus() {
             }
             if (localExists && !remoteFileExists) {
                 p.log.warn(`${color.bold(file.label)}: ${color.green('local only')} — not pushed yet`);
+                toPush.push(file.label);
                 continue;
             }
             if (!localExists && remoteFileExists) {
                 p.log.warn(`${color.bold(file.label)}: ${color.cyan('remote only')} — not pulled yet`);
+                toPull.push(file.label);
                 continue;
             }
             const localContent = await fs.readFile(file.localPath, 'utf-8');
@@ -174,16 +170,34 @@ export async function syncStatus() {
             const remoteChanged = !lastSync || remoteMtime > lastSync;
             if (localChanged && !remoteChanged) {
                 p.log.warn(`${color.bold(file.label)}: ${color.green('local ahead')} — modified ${color.dim(localMtime.toLocaleString())}`);
+                toPush.push(file.label);
             }
             else if (remoteChanged && !localChanged) {
                 p.log.warn(`${color.bold(file.label)}: ${color.cyan('remote ahead')} — modified ${color.dim(remoteMtime.toLocaleString())}`);
+                toPull.push(file.label);
             }
             else {
                 p.log.warn(`${color.bold(file.label)}: ${color.yellow('conflict')} — both changed since last sync`);
+                toResolve.push(file.label);
+            }
+        }
+        const singleAction = [toPush, toPull, toResolve].filter(a => a.length > 0).length === 1;
+        const needsSync = toPush.length > 0 || toPull.length > 0 || toResolve.length > 0;
+        if (needsSync) {
+            if (singleAction && toPush.length > 0) {
+                p.outro(`Run ${color.cyan('zedx sync')} to push ${toPush.map(l => color.bold(l)).join(', ')} to remote.`);
             }
+            else if (singleAction && toPull.length > 0) {
+                p.outro(`Run ${color.cyan('zedx sync')} to pull ${toPull.map(l => color.bold(l)).join(', ')} from remote.`);
+            }
+            else {
+                p.outro(`Run ${color.cyan('zedx sync')} to resolve.`);
+            }
+        }
+        else {
+            p.outro('Everything is in sync.');
         }
     });
-    p.outro(`Run ${color.cyan('zedx sync')} to resolve.`);
 }
 // zedx sync init
 export async function syncInit() {
@@ -239,13 +253,13 @@ export async function syncSelect() {
     const allFiles = [
         {
             value: 'settings',
-            label: 'settings.json',
-            hint: 'Zed editor settings',
+            label: 'Settings',
+            hint: 'settings.json',
         },
         {
-            value: 'extensions',
-            label: 'extensions/index.json',
-            hint: 'Installed extensions list',
+            value: 'keymap',
+            label: 'Key bindings',
+            hint: 'keymap.json',
         },
     ];
     const selected = await p.multiselect({
@@ -283,7 +297,7 @@ export async function runSync(opts = {}) {
     };
     if (!silent) {
         console.log('');
-        p.intro(`${color.bgBlue(color.bold(' zedx sync '))} ${color.blue('Syncing Zed settings and extensions…')}`);
+        p.intro(`${color.bgBlue(color.bold(' zedx sync '))} ${color.blue('Syncing Zed config…')}`);
     }
     const config = await requireSyncConfig();
     const zedPaths = resolveZedPaths();
@@ -316,13 +330,13 @@ export async function runSync(opts = {}) {
                 key: 'settings',
                 repoPath: path.join(tmp, 'settings.json'),
                 localPath: zedPaths.settings,
-                label: 'settings.json',
+                label: 'Settings',
             },
             {
-                key: 'extensions',
-                repoPath: path.join(tmp, 'extensions', 'index.json'),
-                localPath: zedPaths.extensions,
-                label: 'extensions/index.json',
+                key: 'keymap',
+                repoPath: path.join(tmp, 'keymap.json'),
+                localPath: zedPaths.keymap,
+                label: 'Key bindings',
             },
         ];
         const files = selectedFiles
@@ -337,29 +351,27 @@ export async function runSync(opts = {}) {
                 log.warn(`${file.label}: not found locally or remotely — skipping.`);
                 continue;
             }
-            // Remote doesn't have it yet — push local
+            // Remote doesn't have it yet — first push.
+            // Bootstrap auto_install_extensions from local extensions/index.json so
+            // the synced settings.json is self-contained on a fresh machine.
             if (localExists && !remoteFileExists) {
                 log.info(`${file.label}: ${color.green('pushing')} (not in remote yet)`);
-                if (file.label === 'settings.json') {
-                    await prepareSettingsForPush(file.localPath, file.repoPath);
-                }
-                else {
-                    await fs.ensureDir(path.dirname(file.repoPath));
-                    await fs.copy(file.localPath, file.repoPath, { overwrite: true });
-                }
+                await reconcileAutoInstallExtensions(file.localPath, zedPaths.extensionsIndex, silent);
+                await fs.ensureDir(path.dirname(file.repoPath));
+                await fs.copy(file.localPath, file.repoPath, { overwrite: true });
                 anyChanges = true;
                 continue;
             }
             // Local doesn't have it — pull remote
             if (!localExists && remoteFileExists) {
                 log.info(`${file.label}: ${color.cyan('pulling')} (not found locally)`);
-                if (file.label === 'settings.json') {
-                    await applyRemoteSettings(file.repoPath, path.join(tmp, 'extensions', 'index.json'), file.localPath, silent);
-                }
-                else {
-                    await fs.ensureDir(path.dirname(file.localPath));
-                    await fs.copy(file.repoPath, file.localPath, { overwrite: true });
+                if (await fs.pathExists(file.localPath)) {
+                    await fs.copy(file.localPath, file.localPath + '.bak', { overwrite: true });
+                    if (!silent)
+                        p.log.info(`Backed up settings to ${color.dim(file.localPath + '.bak')}`);
                 }
+                await fs.ensureDir(path.dirname(file.localPath));
+                await fs.copy(file.repoPath, file.localPath, { overwrite: true });
                 continue;
             }
             // Both exist — compare content
@@ -377,27 +389,20 @@ export async function runSync(opts = {}) {
             const localChanged = !lastSync || localMtime > lastSync;
             const remoteChanged = !lastSync || remoteMtime > lastSync;
             if (localChanged && !remoteChanged) {
-                // Only local changed → push
+                // Only local changed → reconcile extensions then push
                 log.info(`${file.label}: ${color.green('pushing')} (local is newer)`);
-                if (file.label === 'settings.json') {
-                    await prepareSettingsForPush(file.localPath, file.repoPath);
-                }
-                else {
-                    await fs.ensureDir(path.dirname(file.repoPath));
-                    await fs.copy(file.localPath, file.repoPath, { overwrite: true });
-                }
+                await reconcileAutoInstallExtensions(file.localPath, zedPaths.extensionsIndex, silent);
+                await fs.ensureDir(path.dirname(file.repoPath));
+                await fs.copy(file.localPath, file.repoPath, { overwrite: true });
                 anyChanges = true;
             }
             else if (remoteChanged && !localChanged) {
                 // Only remote changed → pull
                 log.info(`${file.label}: ${color.cyan('pulling')} (remote is newer)`);
-                if (file.label === 'settings.json') {
-                    await applyRemoteSettings(file.repoPath, path.join(tmp, 'extensions', 'index.json'), file.localPath, silent);
-                }
-                else {
-                    await fs.ensureDir(path.dirname(file.localPath));
-                    await fs.copy(file.repoPath, file.localPath, { overwrite: true });
-                }
+                await fs.copy(file.localPath, file.localPath + '.bak', { overwrite: true });
+                if (!silent)
+                    p.log.info(`Backed up settings to ${color.dim(file.localPath + '.bak')}`);
+                await fs.copy(file.repoPath, file.localPath, { overwrite: true });
             }
             else {
                 // Both changed — resolve based on strategy
@@ -441,32 +446,25 @@ export async function runSync(opts = {}) {
                 if (resolution === 'local') {
                     if (!silent && conflict === 'prompt')
                         p.log.info(`${file.label}: ${color.green('keeping local, will push')}`);
-                    if (file.label === 'settings.json') {
-                        await prepareSettingsForPush(file.localPath, file.repoPath);
-                    }
-                    else {
-                        await fs.ensureDir(path.dirname(file.repoPath));
-                        await fs.copy(file.localPath, file.repoPath, { overwrite: true });
-                    }
+                    await reconcileAutoInstallExtensions(file.localPath, zedPaths.extensionsIndex, silent);
+                    await fs.ensureDir(path.dirname(file.repoPath));
+                    await fs.copy(file.localPath, file.repoPath, { overwrite: true });
                     anyChanges = true;
                 }
                 else {
                     if (!silent && conflict === 'prompt')
                         p.log.info(`${file.label}: ${color.cyan('applying remote')}`);
-                    if (file.label === 'settings.json') {
-                        await applyRemoteSettings(file.repoPath, path.join(tmp, 'extensions', 'index.json'), file.localPath, silent);
-                    }
-                    else {
-                        await fs.ensureDir(path.dirname(file.localPath));
-                        await fs.copy(file.repoPath, file.localPath, { overwrite: true });
-                    }
+                    await fs.copy(file.localPath, file.localPath + '.bak', { overwrite: true });
+                    if (!silent)
+                        p.log.info(`Backed up settings to ${color.dim(file.localPath + '.bak')}`);
+                    await fs.copy(file.repoPath, file.localPath, { overwrite: true });
                 }
             }
         }
         // 3. Commit + push if any local files were written to the repo
         if (anyChanges) {
             spinner.start('Pushing changes to remote...');
-            await git.add(['settings.json', path.join('extensions', 'index.json')]);
+            await git.add(files.map(f => path.basename(f.repoPath)));
             const status = await git.status();
             if (status.staged.length > 0) {
                 const timestamp = new Date().toISOString();

package/dist/types/index.d.ts

@@ -1,7 +1,8 @@
 export type ExtensionType = 'theme' | 'language';
 export interface ZedPaths {
     settings: string;
-    extensions: string;
+    keymap: string;
+    extensionsIndex: string;
 }
 export interface SyncConfig {
     syncRepo: string;

package/dist/zed-paths.js

@@ -4,26 +4,32 @@ export function resolveZedPaths() {
     const home = os.homedir();
     const platform = process.platform;
     if (platform === 'darwin') {
+        const configDir = path.join(home, '.config', 'zed');
         return {
-            settings: path.join(home, '.config', 'zed', 'settings.json'),
-            extensions: path.join(home, 'Library', 'Application Support', 'Zed', 'extensions', 'index.json'),
+            settings: path.join(configDir, 'settings.json'),
+            keymap: path.join(configDir, 'keymap.json'),
+            extensionsIndex: path.join(home, 'Library', 'Application Support', 'Zed', 'extensions', 'index.json'),
         };
     }
     if (platform === 'linux') {
         const xdgData = process.env.FLATPAK_XDG_DATA_HOME ||
             process.env.XDG_DATA_HOME ||
             path.join(home, '.local', 'share');
+        const configDir = path.join(home, '.config', 'zed');
         return {
-            settings: path.join(home, '.config', 'zed', 'settings.json'),
-            extensions: path.join(xdgData, 'zed', 'extensions', 'index.json'),
+            settings: path.join(configDir, 'settings.json'),
+            keymap: path.join(configDir, 'keymap.json'),
+            extensionsIndex: path.join(xdgData, 'zed', 'extensions', 'index.json'),
         };
     }
     if (platform === 'win32') {
         const appData = process.env.APPDATA || path.join(home, 'AppData', 'Roaming');
         const localAppData = process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+        const configDir = path.join(appData, 'Zed');
         return {
-            settings: path.join(appData, 'Zed', 'settings.json'),
-            extensions: path.join(localAppData, 'Zed', 'extensions', 'index.json'),
+            settings: path.join(configDir, 'settings.json'),
+            keymap: path.join(configDir, 'keymap.json'),
+            extensionsIndex: path.join(localAppData, 'Zed', 'extensions', 'index.json'),
         };
     }
     throw new Error(`Unsupported platform: ${platform}`);

package/package.json

@@ -1,11 +1,13 @@
 {
     "name": "zedx",
-    "version": "0.9.0",
-    "description": "Scaffold Zed Editor extensions and sync your settings across machines.",
+    "version": "0.10.0",
+    "description": "The CLI toolkit for Zed Editor.",
     "keywords": [
         "boilerplate",
         "extension",
         "scaffold",
+        "settings",
+        "sync",
         "zed",
         "zed-editor"
     ],