@zeph-to/hook-sdk 1.7.0 → 1.8.0

package/README.md

@@ -50,7 +50,10 @@ zeph notify --title "Hello" --json
 
 | Command | Description |
 |---------|-------------|
-| `install` | One-command setup: detect agents, save config, install plugins |
+| `install` | One-command setup: detect agents, save config, install rules + hooks + MCP |
+| `uninstall` | Remove Zeph from all detected agents (`--dry-run`, `--purge`) |
+| `verify` | Check installation health across detected agents (`--ping` for a live API call) |
+| `check-update` | Check whether a newer Zeph version is on npm |
 | `notify` | Send a push notification |
 | `list` | List recent push notifications |
 | `dismiss <id>` | Dismiss a push (or `--all`) |
@@ -60,13 +63,15 @@ zeph notify --title "Hello" --json
 
 | Flag | Description |
 |------|-------------|
-| `--title <text>` | Push title |
-| `--body <text>` | Push body |
+| `--title <text>` | Push title (default: `"Task done"`) |
+| `--body <text>` | Push body (default: `"<project> · <branch>"` if cwd is a git repo, else `"<project>"`) |
 | `--url <url>` | URL to include |
 | `--type <type>` | Push type: `note`, `link`, `file`, `hook` |
 | `--priority <p>` | Priority: `low`, `normal`, `high`, `urgent` |
 | `--device <id>` | Target device ID |
 
+The defaults are tuned for hook-driven invocations (e.g. Stop hooks calling `zeph notify --title "Task done"` without a body) — you'll see which project + branch finished without writing per-IDE wrappers. Pass `--body ""` explicitly to suppress.
+
 ### List Options
 
 | Flag | Description |
@@ -188,9 +193,11 @@ try {
 | Copilot CLI | Session end hook |
 | Cline | Rules file |
 
-## E2E Encryption
+## Encryption
+
+Push bodies are encrypted with AES-256-GCM. The wrapping key is derived via ECDH P-256 and synced across your own devices on first run so every device can read the same push. Toggle encryption in the Zeph app (Settings → Encryption); when disabled, the CLI sends plaintext. No configuration needed.
 
-Notifications are encrypted end-to-end by default (AES-256-GCM + ECDH P-256). Keys are synced with the server automatically. When encryption is disabled in the Zeph app, the CLI sends plaintext. No configuration needed.
+**Threat model honesty:** keys are persisted on the Zeph backend to enable cross-device sync, so this is *device-shared* encryption — not true end-to-end. It protects push contents from passive network observers and from a leaked database snapshot taken without the key store, but it does **not** protect against the Zeph backend itself (it has the keys it serves to your devices). A true E2E mode (per-device keypairs, server stores only public keys, no key escrow) is on the roadmap.
 
 ## Requirements
 

package/dist/agents.d.ts

@@ -0,0 +1,8 @@
+export interface Agent {
+    name: string;
+    id: string;
+    detected: boolean;
+}
+export declare const hasCommand: (cmd: string) => boolean;
+export declare const detectAgents: () => Agent[];
+//# sourceMappingURL=agents.d.ts.map

package/dist/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,KAAK;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,OAAO,CAAC;CACrB;AAID,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,OAOxC,CAAC;AAEF,eAAO,MAAM,YAAY,QAAO,KAAK,EASpC,CAAC"}

package/dist/agents.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectAgents = exports.hasCommand = void 0;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const HOME = (0, os_1.homedir)();
+const hasCommand = (cmd) => {
+    try {
+        (0, child_process_1.execSync)(`which ${cmd}`, { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+exports.hasCommand = hasCommand;
+const detectAgents = () => [
+    { name: 'Claude Code', id: 'claude', detected: (0, exports.hasCommand)('claude') },
+    { name: 'Cursor', id: 'cursor', detected: (0, fs_1.existsSync)((0, path_1.join)(HOME, '.cursor')) },
+    { name: 'Windsurf', id: 'windsurf', detected: (0, fs_1.existsSync)((0, path_1.join)(HOME, '.codeium')) },
+    { name: 'Gemini CLI', id: 'gemini', detected: (0, exports.hasCommand)('gemini') },
+    { name: 'Codex CLI', id: 'codex', detected: (0, exports.hasCommand)('codex') },
+    { name: 'Copilot CLI', id: 'copilot', detected: (0, fs_1.existsSync)((0, path_1.join)(HOME, '.copilot')) },
+    { name: 'Cline', id: 'cline', detected: (0, fs_1.existsSync)((0, path_1.join)(HOME, '.cline')) },
+    { name: 'Aider', id: 'aider', detected: (0, exports.hasCommand)('aider') },
+];
+exports.detectAgents = detectAgents;

package/dist/check-update.d.ts

@@ -0,0 +1,4 @@
+/** Semver-ish compare: returns true when `latest` is strictly newer than `current`. */
+export declare const isNewer: (latest: string, current: string) => boolean;
+export declare const handleCheckUpdate: (args: Record<string, string | boolean>) => Promise<number>;
+//# sourceMappingURL=check-update.d.ts.map

package/dist/check-update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-update.d.ts","sourceRoot":"","sources":["../src/check-update.ts"],"names":[],"mappings":"AAsBA,uFAAuF;AACvF,eAAO,MAAM,OAAO,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,OAQzD,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CA4C9F,CAAC"}

package/dist/check-update.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleCheckUpdate = exports.isNewer = void 0;
+const config_js_1 = require("./config.js");
+// Compares installed versions against the npm registry. Pure read-only —
+// never installs anything; just tells the user if a newer release exists.
+const PACKAGES = ['@zeph-to/hook-sdk', '@zeph-to/mcp-server'];
+/** Fetch the `latest` dist-tag version for a package from the npm registry. */
+const fetchLatest = async (pkg) => {
+    try {
+        const res = await fetch(`https://registry.npmjs.org/${pkg}/latest`, {
+            headers: { Accept: 'application/json' },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok)
+            return null;
+        const json = await res.json();
+        return json.version ?? null;
+    }
+    catch {
+        return null;
+    }
+};
+/** Semver-ish compare: returns true when `latest` is strictly newer than `current`. */
+const isNewer = (latest, current) => {
+    const norm = (v) => v.replace(/^v/, '').split('-')[0].split('.').map((n) => parseInt(n, 10) || 0);
+    const [a, b] = [norm(latest), norm(current)];
+    for (let i = 0; i < 3; i++) {
+        if ((a[i] ?? 0) > (b[i] ?? 0))
+            return true;
+        if ((a[i] ?? 0) < (b[i] ?? 0))
+            return false;
+    }
+    return false;
+};
+exports.isNewer = isNewer;
+const handleCheckUpdate = async (args) => {
+    const isJson = args.json === true;
+    // The hook-sdk's own installed version is known from package.json.
+    // mcp-server's installed version isn't reliably knowable from here
+    // (it's a separate package, often run via npx), so we only report its
+    // latest — the user compares against whatever they have.
+    const results = [];
+    for (const pkg of PACKAGES) {
+        const latest = await fetchLatest(pkg);
+        const current = pkg === '@zeph-to/hook-sdk' ? config_js_1.VERSION : null;
+        const outdated = !!(latest && current && (0, exports.isNewer)(latest, current));
+        results.push({ pkg, current, latest, outdated });
+    }
+    if (isJson) {
+        console.log(JSON.stringify({ results }, null, 2));
+        return results.some((r) => r.outdated) ? 0 : 0;
+    }
+    console.log('\n  Zeph — update check\n');
+    let anyOutdated = false;
+    for (const r of results) {
+        if (!r.latest) {
+            console.log(`    ?  ${r.pkg}: could not reach npm registry`);
+            continue;
+        }
+        if (r.current === null) {
+            console.log(`    •  ${r.pkg}: latest is v${r.latest}`);
+        }
+        else if (r.outdated) {
+            anyOutdated = true;
+            console.log(`    ⬆  ${r.pkg}: v${r.current} → v${r.latest} (update available)`);
+        }
+        else {
+            console.log(`    ✓  ${r.pkg}: v${r.current} (up to date)`);
+        }
+    }
+    if (anyOutdated) {
+        console.log('\n  Update with: npx @zeph-to/hook-sdk install\n');
+    }
+    else {
+        console.log('');
+    }
+    return 0;
+};
+exports.handleCheckUpdate = handleCheckUpdate;

package/dist/cli.js

@@ -6,11 +6,15 @@ const child_process_1 = require("child_process");
 const zeph_hook_js_1 = require("./zeph-hook.js");
 const errors_js_1 = require("./errors.js");
 const installer_js_1 = require("./installer.js");
+const uninstall_js_1 = require("./uninstall.js");
+const verify_js_1 = require("./verify.js");
+const check_update_js_1 = require("./check-update.js");
 const config_js_1 = require("./config.js");
 const PROJECT_DIR_VARS = ['CLAUDE_PROJECT_DIR', 'CURSOR_PROJECT_DIR', 'WINDSURF_PROJECT_DIR'];
+const detectProjectDir = () => PROJECT_DIR_VARS.reduce((found, key) => found || process.env[key], undefined) ?? process.cwd();
 const isMuted = () => {
     try {
-        const dir = PROJECT_DIR_VARS.reduce((found, key) => found || process.env[key], undefined) ?? process.cwd();
+        const dir = detectProjectDir();
         const raw = (0, child_process_1.execFileSync)('cksum', { input: dir, encoding: 'utf-8' });
         const hash = raw.split(' ')[0];
         return (0, fs_1.existsSync)(`/tmp/zeph-muted-${hash}`);
@@ -19,6 +23,21 @@ const isMuted = () => {
         return false;
     }
 };
+const detectBranchAndProject = () => {
+    const dir = detectProjectDir();
+    const project = dir.split('/').filter(Boolean).pop() ?? 'project';
+    let branch;
+    try {
+        branch = (0, child_process_1.execFileSync)('git', ['-C', dir, 'rev-parse', '--abbrev-ref', 'HEAD'], {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        if (!branch || branch === 'HEAD')
+            branch = undefined;
+    }
+    catch { /* not a git repo */ }
+    return { branch, project };
+};
 // ── Arg Parser ──────────────────────────────────────────────────
 const parseArgs = (argv) => {
     const result = {};
@@ -49,7 +68,10 @@ const printUsage = () => {
     console.log(`Usage: zeph <command> [options]
 
 Commands:
-  install         One-command setup: detect agents, save config, install plugins
+  install         One-command setup: detect agents, save config, install rules
+  uninstall       Remove Zeph from all detected agents
+  verify          Check installation health across detected agents
+  check-update    Check whether a newer Zeph version is available
   notify          Send a push notification
   list            List recent push notifications
   dismiss <id>    Dismiss a push notification (or --all)
@@ -76,6 +98,13 @@ Install options:
   --hook <hook-id>   Hook ID (non-interactive)
   --base-url <url>   Base URL (non-interactive)
 
+Uninstall options:
+  --dry-run          Preview what would be removed, change nothing
+  --purge            Also delete ~/.zeph/config.json (kept by default)
+
+Verify options:
+  --ping             Also make a live API call to confirm the key works
+
 Global options:
   --key <api-key>    API key (or set ZEPH_API_KEY env)
   --base-url <url>   API base URL (or set ZEPH_BASE_URL env)
@@ -122,9 +151,20 @@ const handleNotify = async (args) => {
         return 3;
     try {
         const sessionId = args.session || (0, config_js_1.resolvedEnv)('ZEPH_SESSION_ID') || undefined;
+        // When body isn't supplied (common case for hook-driven invocations like
+        // `zeph notify --title "Task done"`), auto-fill with branch + project so
+        // the user can tell which session finished without opening the app.
+        let title = args.title;
+        let body = args.body;
+        if (!body) {
+            const { branch, project } = detectBranchAndProject();
+            body = branch ? `${project} · ${branch}` : project;
+        }
+        if (!title)
+            title = 'Task done';
         const result = await hook.notify({
-            title: args.title,
-            body: args.body,
+            title,
+            body,
             url: args.url,
             type: args.type || 'hook',
             priority: args.priority || undefined,
@@ -267,6 +307,12 @@ const main = async () => {
         case 'install':
         case 'setup':
             return (0, installer_js_1.handleInstall)(args);
+        case 'uninstall':
+            return (0, uninstall_js_1.handleUninstall)(args);
+        case 'verify':
+            return (0, verify_js_1.handleVerify)(args);
+        case 'check-update':
+            return (0, check_update_js_1.handleCheckUpdate)(args);
         case 'notify':
             return handleNotify(args);
         case 'list':

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,UAAU,QAAyC,CAAC;AACjE,eAAO,MAAM,WAAW,QAAkC,CAAC;AAE3D,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAGlD,CAAC;AAEF,eAAO,MAAM,UAAU,QAAO,UAM7B,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,QAAQ,UAAU,KAAG,IAG/C,CAAC;AAEF,eAAO,MAAM,OAAO,QAOhB,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,UAAU,QAA2B,CAAC;AACnD,eAAO,MAAM,WAAW,QAAkC,CAAC;AAE3D,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAGlD,CAAC;AAEF,eAAO,MAAM,UAAU,QAAO,UAM7B,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,QAAQ,UAAU,KAAG,IAG/C,CAAC;AAEF,eAAO,MAAM,OAAO,QAOhB,CAAC"}

package/dist/config.js

@@ -2,8 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = exports.saveConfig = exports.loadConfig = exports.resolvedEnv = exports.CONFIG_FILE = exports.CONFIG_DIR = void 0;
 const fs_1 = require("fs");
+const os_1 = require("os");
 const path_1 = require("path");
-exports.CONFIG_DIR = (0, path_1.join)(process.env.HOME ?? '~', '.zeph');
+exports.CONFIG_DIR = (0, path_1.join)((0, os_1.homedir)(), '.zeph');
 exports.CONFIG_FILE = (0, path_1.join)(exports.CONFIG_DIR, 'config.json');
 const resolvedEnv = (key) => {
     const val = process.env[key];

package/dist/crypto.d.ts

@@ -1,7 +1,30 @@
 /**
- * E2E encryption for Hook SDK — self-contained ECDH P-256 + AES-256-GCM
- * Mirrors @zeph/crypto API but bundled inline (no external dependency).
- * Uses Web Crypto API (globalThis.crypto.subtle) — Node.js 18+.
+ * Device-shared encryption for Hook SDK — self-contained ECDH P-256 +
+ * AES-256-GCM. Mirrors @zeph/crypto API but bundled inline (no external
+ * dependency). Uses Web Crypto API (globalThis.crypto.subtle) — Node.js 18+.
+ *
+ * Threat model honesty (do not call this "E2E" without a footnote):
+ *
+ *   The Zeph backend persists the per-user private key in plaintext so it
+ *   can be synced down to a fresh device (fetchServerKeys / uploadServerKeys
+ *   below). That means the backend can decrypt any push body — this is NOT
+ *   end-to-end in the standard sense. What it gives you is:
+ *     • Protection against passive network observers
+ *     • Protection against a leaked DB snapshot taken without the key store
+ *     • Cross-device readability (all your devices share one keypair)
+ *   What it does NOT give you:
+ *     • Protection against the Zeph backend itself
+ *     • Forward secrecy — encryptPushBodyForSelf / encryptFileForSelf do
+ *       ECDH(self, self), which collapses to a static derived key. A single
+ *       device compromise (since all your devices share the same keypair)
+ *       lets the attacker decrypt every past push for which they have the
+ *       ciphertext. The per-message AES key is random, but its wrap key is
+ *       static, so wrapped keys are decryptable forever.
+ *
+ *   True E2E would require a per-device keypair (server stores only public
+ *   keys; senders wrap the message key once per recipient device public
+ *   key). That refactor is on the roadmap; until then, treat push bodies as
+ *   sensitive-but-not-secret.
  */
 /**
  * Initialize crypto: sync keys with server, then fallback to local/generate.

package/dist/crypto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0JH;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAsE5E,CAAC;AAqCF,eAAO,MAAM,UAAU,QAAO,aAAa,GAAG,IAAqB,CAAC;AACpE,eAAO,MAAM,YAAY,QAAO,MAAM,GAAG,IAA+B,CAAC;AAEzE;;;GAGG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EACtD,uBAAuB,MAAM,KAC5B,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB,CAeA,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,KACrD,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB,CAaA,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,MAAM,EACf,uBAAuB,MAAM,KAC5B,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CASlE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,MAAM,KACd,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAQlE,CAAC"}
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AA2JH;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAsE5E,CAAC;AAqCF,eAAO,MAAM,UAAU,QAAO,aAAa,GAAG,IAAqB,CAAC;AACpE,eAAO,MAAM,YAAY,QAAO,MAAM,GAAG,IAA+B,CAAC;AAEzE;;;GAGG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EACtD,uBAAuB,MAAM,KAC5B,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB,CAeA,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,KACrD,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB,CAaA,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,MAAM,EACf,uBAAuB,MAAM,KAC5B,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CASlE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,MAAM,KACd,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAQlE,CAAC"}

package/dist/crypto.js

@@ -1,13 +1,37 @@
 "use strict";
 /**
- * E2E encryption for Hook SDK — self-contained ECDH P-256 + AES-256-GCM
- * Mirrors @zeph/crypto API but bundled inline (no external dependency).
- * Uses Web Crypto API (globalThis.crypto.subtle) — Node.js 18+.
+ * Device-shared encryption for Hook SDK — self-contained ECDH P-256 +
+ * AES-256-GCM. Mirrors @zeph/crypto API but bundled inline (no external
+ * dependency). Uses Web Crypto API (globalThis.crypto.subtle) — Node.js 18+.
+ *
+ * Threat model honesty (do not call this "E2E" without a footnote):
+ *
+ *   The Zeph backend persists the per-user private key in plaintext so it
+ *   can be synced down to a fresh device (fetchServerKeys / uploadServerKeys
+ *   below). That means the backend can decrypt any push body — this is NOT
+ *   end-to-end in the standard sense. What it gives you is:
+ *     • Protection against passive network observers
+ *     • Protection against a leaked DB snapshot taken without the key store
+ *     • Cross-device readability (all your devices share one keypair)
+ *   What it does NOT give you:
+ *     • Protection against the Zeph backend itself
+ *     • Forward secrecy — encryptPushBodyForSelf / encryptFileForSelf do
+ *       ECDH(self, self), which collapses to a static derived key. A single
+ *       device compromise (since all your devices share the same keypair)
+ *       lets the attacker decrypt every past push for which they have the
+ *       ciphertext. The per-message AES key is random, but its wrap key is
+ *       static, so wrapped keys are decryptable forever.
+ *
+ *   True E2E would require a per-device keypair (server stores only public
+ *   keys; senders wrap the message key once per recipient device public
+ *   key). That refactor is on the roadmap; until then, treat push bodies as
+ *   sensitive-but-not-secret.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.encryptFileForSelf = exports.encryptFileForRecipient = exports.encryptPushBodyForSelf = exports.encryptPushBody = exports.getPublicKey = exports.getKeyPair = exports.initCrypto = void 0;
 /// <reference lib="dom" />
 const fs_1 = require("fs");
+const os_1 = require("os");
 const path_1 = require("path");
 // ─── Base64 helpers ───
 const toBase64 = (buffer) => {
@@ -79,7 +103,7 @@ const encryptFileContent = async (content, senderPrivateKey, recipientPublicKey)
     };
 };
 // ─── Key persistence (~/.config/zeph/keys.json) ───
-const KEYS_DIR = (0, path_1.join)(process.env.HOME ?? '~', '.config', 'zeph');
+const KEYS_DIR = (0, path_1.join)((0, os_1.homedir)(), '.config', 'zeph');
 const KEYS_PATH = (0, path_1.join)(KEYS_DIR, 'keys.json');
 const loadStoredKeys = () => {
     try {

package/dist/installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AAyNA,eAAO,MAAM,aAAa,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAmH1F,CAAC"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AA4RA,eAAO,MAAM,aAAa,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAoH1F,CAAC"}

package/dist/installer.js

@@ -3,12 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleInstall = void 0;
 const child_process_1 = require("child_process");
 const fs_1 = require("fs");
+const os_1 = require("os");
 const path_1 = require("path");
 const readline_1 = require("readline");
 const zeph_hook_js_1 = require("./zeph-hook.js");
 const config_js_1 = require("./config.js");
+const agents_js_1 = require("./agents.js");
 const templates_js_1 = require("./templates.js");
-const HOME = process.env.HOME ?? '~';
+const HOME = (0, os_1.homedir)();
 // ── Helpers ──────────────────────────────────────────────────────
 const ok = (msg) => console.log(`    + ${msg}`);
 const fail = (msg) => console.log(`    - ${msg}`);
@@ -21,15 +23,6 @@ const promptInput = (question) => {
         });
     });
 };
-const hasCommand = (cmd) => {
-    try {
-        (0, child_process_1.execSync)(`which ${cmd}`, { stdio: 'pipe' });
-        return true;
-    }
-    catch {
-        return false;
-    }
-};
 const writeFile = (filePath, content) => {
     (0, fs_1.mkdirSync)((0, path_1.dirname)(filePath), { recursive: true });
     (0, fs_1.writeFileSync)(filePath, content + '\n');
@@ -43,16 +36,41 @@ const mergeJsonFile = (filePath, patch) => {
     const merged = { ...data, ...patch };
     writeFile(filePath, JSON.stringify(merged, null, 2));
 };
-// ── Agent Detection ──────────────────────────────────────────────
-const detectAgents = () => [
-    { name: 'Claude Code', id: 'claude', detected: hasCommand('claude') },
-    { name: 'Cursor', id: 'cursor', detected: (0, fs_1.existsSync)((0, path_1.join)(HOME, '.cursor')) },
-    { name: 'Windsurf', id: 'windsurf', detected: (0, fs_1.existsSync)((0, path_1.join)(HOME, '.codeium')) },
-    { name: 'Gemini CLI', id: 'gemini', detected: hasCommand('gemini') },
-    { name: 'Codex CLI', id: 'codex', detected: hasCommand('codex') },
-    { name: 'Copilot CLI', id: 'copilot', detected: (0, fs_1.existsSync)((0, path_1.join)(HOME, '.copilot')) },
-    { name: 'Cline', id: 'cline', detected: (0, fs_1.existsSync)((0, path_1.join)(HOME, '.cline')) },
-];
+/**
+ * Write a Zeph rule into a SHARED agent rule file (Windsurf global_rules.md,
+ * Gemini GEMINI.md, Codex AGENTS.md) without clobbering the user's own
+ * content. The rule lands inside <!-- ZEPH:START/END --> markers; a re-run
+ * replaces just that block.
+ */
+const writeManagedRule = (filePath, rule) => {
+    let existing = '';
+    try {
+        existing = (0, fs_1.readFileSync)(filePath, 'utf-8');
+    }
+    catch { /* new file */ }
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(filePath), { recursive: true });
+    (0, fs_1.writeFileSync)(filePath, (0, templates_js_1.upsertManagedBlock)(existing, rule));
+};
+/**
+ * Add a `read:` entry to ~/.aider.conf.yml so Aider always loads the Zeph
+ * conventions file. Idempotent — skips if the path is already referenced.
+ * Aider's config is YAML; we do a minimal text-level append to avoid
+ * pulling in a YAML dependency (the SDK is zero-dep by design).
+ */
+const addAiderReadDirective = (confPath, conventionsPath) => {
+    let conf = '';
+    try {
+        conf = (0, fs_1.readFileSync)(confPath, 'utf-8');
+    }
+    catch { /* new file */ }
+    if (conf.includes(conventionsPath))
+        return; // already wired up
+    const marker = '# Added by Zeph';
+    const line = `${marker}\nread: ${conventionsPath}\n`;
+    const base = conf.replace(/\n*$/, '');
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(confPath), { recursive: true });
+    (0, fs_1.writeFileSync)(confPath, (base ? `${base}\n\n` : '') + line);
+};
 // ── Per-Agent Installers ─────────────────────────────────────────
 const injectMcpJson = (filePath) => {
     let data = {};
@@ -62,9 +80,14 @@ const injectMcpJson = (filePath) => {
     catch { /* new file */ }
     if (!data.mcpServers)
         data.mcpServers = {};
+    // Pass through env explicitly so the MCP server doesn't have to rely on
+    // process-env inheritance (which behaves differently per IDE — Cursor and
+    // Windsurf spawn the MCP from a graphical context that may not inherit
+    // shell env). Mirrors plugin/.mcp.json.
     data.mcpServers.zeph = {
         command: 'npx',
         args: ['-y', '@zeph-to/mcp-server'],
+        env: { ZEPH_API_KEY: '${ZEPH_API_KEY}' },
     };
     (0, fs_1.mkdirSync)((0, path_1.dirname)(filePath), { recursive: true });
     (0, fs_1.writeFileSync)(filePath, JSON.stringify(data, null, 2) + '\n');
@@ -119,6 +142,15 @@ const installWindsurf = () => {
     catch {
         fail('Hook install failed');
     }
+    try {
+        // Windsurf reads ~/.codeium/windsurf/memories/global_rules.md as always-on
+        // global rules. Managed-block append preserves the user's own rules.
+        writeManagedRule((0, path_1.join)(HOME, '.codeium', 'windsurf', 'memories', 'global_rules.md'), templates_js_1.WINDSURF_RULE);
+        ok('Rules added to global_rules.md');
+    }
+    catch {
+        fail('Rule install failed. Manual: add zeph rules to ~/.codeium/windsurf/memories/global_rules.md');
+    }
 };
 const installGemini = () => {
     try {
@@ -135,6 +167,14 @@ const installGemini = () => {
     catch {
         fail('Hook install failed');
     }
+    try {
+        // Gemini CLI loads ~/.gemini/GEMINI.md as global context every prompt.
+        writeManagedRule((0, path_1.join)(HOME, '.gemini', 'GEMINI.md'), templates_js_1.GEMINI_RULE);
+        ok('Rules added to GEMINI.md');
+    }
+    catch {
+        fail('Rule install failed. Manual: add zeph rules to ~/.gemini/GEMINI.md');
+    }
 };
 const installCodex = () => {
     try {
@@ -144,6 +184,14 @@ const installCodex = () => {
     catch {
         fail('Hook install failed. Manual: add zeph to ~/.codex/hooks.json');
     }
+    try {
+        // Codex CLI loads ~/.codex/AGENTS.md as global instructions.
+        writeManagedRule((0, path_1.join)(HOME, '.codex', 'AGENTS.md'), templates_js_1.CODEX_RULE);
+        ok('Rules added to AGENTS.md');
+    }
+    catch {
+        fail('Rule install failed. Manual: add zeph rules to ~/.codex/AGENTS.md');
+    }
 };
 const installCopilot = () => {
     try {
@@ -153,6 +201,15 @@ const installCopilot = () => {
     catch {
         fail('Hook install failed. Manual: add zeph to ~/.copilot/hooks/');
     }
+    try {
+        // Copilot CLI loads ~/.copilot/instructions/*.instructions.md globally.
+        // A dedicated file means no merge needed — overwrite is safe.
+        writeFile((0, path_1.join)(HOME, '.copilot', 'instructions', 'zeph.instructions.md'), templates_js_1.COPILOT_RULE);
+        ok('Rule file added');
+    }
+    catch {
+        fail('Rule install failed. Manual: add zeph rules to ~/.copilot/instructions/');
+    }
 };
 const installCline = () => {
     try {
@@ -163,6 +220,27 @@ const installCline = () => {
         fail('Rule install failed. Manual: add zeph to ~/.cline/rules/');
     }
 };
+const installAider = () => {
+    // Aider has no hooks; rules reach it via a conventions file loaded by the
+    // `read:` directive in ~/.aider.conf.yml. We keep the conventions file in
+    // ~/.zeph/ (our own dir — no conflict) and just wire the read directive.
+    const conventionsPath = (0, path_1.join)(HOME, '.zeph', 'aider-conventions.md');
+    try {
+        writeFile(conventionsPath, templates_js_1.AIDER_RULE);
+        ok('Conventions file added');
+    }
+    catch {
+        fail('Conventions install failed. Manual: save zeph rules somewhere readable');
+        return;
+    }
+    try {
+        addAiderReadDirective((0, path_1.join)(HOME, '.aider.conf.yml'), conventionsPath);
+        ok('read: directive added to ~/.aider.conf.yml');
+    }
+    catch {
+        fail(`Config wiring failed. Manual: add "read: ${conventionsPath}" to ~/.aider.conf.yml`);
+    }
+};
 const AGENT_INSTALLERS = {
     claude: installClaude,
     cursor: installCursor,
@@ -171,6 +249,7 @@ const AGENT_INSTALLERS = {
     codex: installCodex,
     copilot: installCopilot,
     cline: installCline,
+    aider: installAider,
 };
 // ── Test Connection ──────────────────────────────────────────────
 const testConnection = async (apiKey, baseUrl) => {
@@ -199,7 +278,7 @@ const handleInstall = async (args) => {
     console.log(`\n  Zeph v${config_js_1.VERSION}\n`);
     // 1. Detect agents
     console.log('  Detecting agents...');
-    const agents = detectAgents();
+    const agents = (0, agents_js_1.detectAgents)();
     const detected = agents.filter((a) => a.detected);
     for (const agent of agents) {
         if (agent.detected) {
@@ -251,11 +330,12 @@ const handleInstall = async (args) => {
             const labels = {
                 claude: 'Install Claude Code plugin',
                 cursor: 'Setup Cursor (MCP + hooks + rules)',
-                windsurf: 'Setup Windsurf (MCP + hooks)',
-                gemini: 'Setup Gemini CLI (MCP + hooks)',
-                codex: 'Setup Codex CLI (hooks)',
-                copilot: 'Setup Copilot CLI (hooks)',
+                windsurf: 'Setup Windsurf (MCP + hooks + rules)',
+                gemini: 'Setup Gemini CLI (MCP + hooks + rules)',
+                codex: 'Setup Codex CLI (hooks + rules)',
+                copilot: 'Setup Copilot CLI (hooks + rules)',
                 cline: 'Setup Cline (rules)',
+                aider: 'Setup Aider (conventions)',
             };
             console.log(`    ${step}. ${labels[agent.id] ?? `Install for ${agent.name}`}`);
             step++;

package/dist/templates.d.ts

@@ -1,5 +1,18 @@
+/** Cursor — written to ~/.cursor/rules/zeph.mdc (needs .mdc frontmatter). */
+export declare const CURSOR_RULE: string;
+/** Windsurf — appended into ~/.codeium/windsurf/memories/global_rules.md. */
+export declare const WINDSURF_RULE: string;
+/** Gemini CLI — appended into ~/.gemini/GEMINI.md. */
+export declare const GEMINI_RULE: string;
+/** Codex CLI — appended into ~/.codex/AGENTS.md. */
+export declare const CODEX_RULE: string;
+/** GitHub Copilot CLI — written to ~/.copilot/instructions/zeph.instructions.md. */
+export declare const COPILOT_RULE: string;
+/** Cline — written to ~/.cline/rules/zeph.md (no Stop hook). */
+export declare const CLINE_RULE: string;
+/** Aider — written to a standalone conventions file, loaded via .aider.conf.yml `read:`. */
+export declare const AIDER_RULE: string;
 export declare const CURSOR_HOOKS: string;
-export declare const CURSOR_RULE = "---\ndescription: \"Zeph notification rules\"\nalwaysApply: true\n---\n\nWhen you complete a coding task, call the zeph_notify MCP tool with a brief summary.\nUse zeph_prompt for user decisions (2-4 options). Use zeph_input for free-form text.\nDo not notify for trivial operations (file reads, simple searches).\n";
 export declare const WINDSURF_HOOKS: string;
 export declare const GEMINI_HOOKS: {
     hooks: {
@@ -18,5 +31,14 @@ export declare const GEMINI_HOOKS: {
 };
 export declare const CODEX_HOOKS: string;
 export declare const COPILOT_HOOKS: string;
-export declare const CLINE_RULE = "When you complete a coding task, call the zeph_notify MCP tool with a brief summary.\nUse zeph_prompt for user decisions (2-4 options). Use zeph_input for free-form text.\nDo not notify for trivial operations (file reads, simple searches).\n";
+export declare const ZEPH_MARK_START = "<!-- ZEPH:START \u2014 managed by @zeph-to/hook-sdk, do not edit between markers -->";
+export declare const ZEPH_MARK_END = "<!-- ZEPH:END -->";
+/**
+ * Return `existing` with the Zeph-managed block inserted or replaced.
+ * If the markers are already present, the content between them is
+ * swapped; otherwise the block is appended.
+ */
+export declare const upsertManagedBlock: (existing: string, rule: string) => string;
+/** Strip the Zeph-managed block from a shared file (for uninstall). */
+export declare const removeManagedBlock: (existing: string) => string;
 //# sourceMappingURL=templates.d.ts.map