@zeph-to/hook-sdk 1.7.1 → 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`) |

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,6 +6,9 @@ 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();
@@ -65,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)
@@ -92,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)
@@ -294,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/installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AA+NA,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

@@ -8,6 +8,7 @@ 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 = (0, os_1.homedir)();
 // ── Helpers ──────────────────────────────────────────────────────
@@ -22,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');
@@ -44,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 = {};
@@ -125,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 {
@@ -141,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 {
@@ -150,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 {
@@ -159,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 {
@@ -169,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,
@@ -177,6 +249,7 @@ const AGENT_INSTALLERS = {
     codex: installCodex,
     copilot: installCopilot,
     cline: installCline,
+    aider: installAider,
 };
 // ── Test Connection ──────────────────────────────────────────────
 const testConnection = async (apiKey, baseUrl) => {
@@ -205,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) {
@@ -257,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 remote-control rules\"\nalwaysApply: true\n---\n\n# Zeph \u2014 Remote-Control Rules\n\nA Stop hook (~/.cursor/hooks.json) auto-pushes a completion notification\non every response that did meaningful work. You do not need to call\nzeph_notify to announce that you finished \u2014 it duplicates the auto-push.\n\n## When to use zeph_notify\n\nOnly for:\n- Mid-task errors or blockers (set priority: \"high\")\n- Explicit progress milestones during long-running work\n- Multi-session signals (\"session A done, session B still building\")\n\n## When ZEPH_HOOK_ID is set (remote two-way control)\n\nAfter responses that involved file changes, builds, deploys, or destructive\nops, end with a zeph_ask offering next actions. Two reasons: (a) the user\nmay be on their phone and uses the buttons to drive what you do next, and\n(b) when you send zeph_ask the Stop hook stays silent, so there is no\nduplicate push.\n\nExample final action:\n  zeph_ask({\n    title: \"Done. Next?\",\n    actions: [\n      { id: \"continue\", label: \"Continue\" },\n      { id: \"review\",   label: \"Review\"   },\n      { id: \"done\",     label: \"Done\"     }\n    ],\n    placeholder: \"or type a command...\",\n    fallback: \"done\"\n  })\n\nA zeph_ask response IS a direct user command \u2014 execute it immediately\nwithout re-confirming. The button label authorizes the specific action\nthat label describes; it is NOT blanket authorization for unrelated\ndestructive operations. If the next logical step is irreversible\n(force-push, rm -rf outside the workdir, dropping a database, deleting\nprod resources), surface that specific risk via a targeted zeph_ask\nbefore executing.\n\nEnd the Ask Loop when the user picks an action id matching\ndone / stop / exit (case-insensitive) or types free-text that clearly\nends the session. Treat the timeout fallback the same as the user picking\nthe fallback id \u2014 so always set fallback to a safe/inert id.\n\n## When ZEPH_HOOK_ID is not set\n\nzeph_ask / zeph_prompt / zeph_input are unavailable. Use zeph_notify only\nas described above.\n\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 = "# Zeph \u2014 Notification & Remote-Control Rules\n\nCline does not have a Stop hook wired up, so notifications must come from\nyou via MCP tools.\n\n## When to call zeph_notify\n\nAfter meaningful task completion (build, test, deploy, large refactor, or\nmulti-file changes). Skip for trivial operations (file reads, simple\nsearches, short clarifications).\n\nSet priority \"high\" for errors or blockers that interrupt your progress.\n\n## When ZEPH_HOOK_ID is set (remote two-way control)\n\nPrefer zeph_ask over zeph_notify after responses that involved file\nchanges, builds, deploys, or destructive ops. The user may be on their\nphone and uses the buttons to drive what you do next.\n\nExample final action:\n  zeph_ask({\n    title: \"Done. Next?\",\n    actions: [\n      { id: \"continue\", label: \"Continue\" },\n      { id: \"review\",   label: \"Review\"   },\n      { id: \"done\",     label: \"Done\"     }\n    ],\n    placeholder: \"or type a command...\",\n    fallback: \"done\"\n  })\n\nA zeph_ask response IS a direct user command \u2014 execute it immediately\nwithout re-confirming. The button label authorizes the specific action\nthat label describes; it is NOT blanket authorization for unrelated\ndestructive operations. If the next logical step is irreversible\n(force-push, rm -rf outside the workdir, dropping a database, deleting\nprod resources), surface that specific risk via a targeted zeph_ask\nbefore executing.\n\nEnd the Ask Loop when the user picks an action id matching\ndone / stop / exit (case-insensitive). Treat the timeout fallback the\nsame as the user picking the fallback id \u2014 so always set fallback to a\nsafe/inert id.\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

package/dist/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAyBA,eAAO,MAAM,YAAY,QAOd,CAAC;AAEZ,eAAO,MAAM,WAAW,ooEAyDvB,CAAC;AAIF,eAAO,MAAM,cAAc,QAOhB,CAAC;AAIZ,eAAO,MAAM,YAAY;;;;;;;;;;;;;;CAYxB,CAAC;AAIF,eAAO,MAAM,WAAW,QAQb,CAAC;AAIZ,eAAO,MAAM,aAAa,QASf,CAAC;AAIZ,eAAO,MAAM,UAAU,mpDA2CtB,CAAC"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AA6JA,6EAA6E;AAC7E,eAAO,MAAM,WAAW,QAGtB,CAAC;AAEH,6EAA6E;AAC7E,eAAO,MAAM,aAAa,QAA4C,CAAC;AAEvE,sDAAsD;AACtD,eAAO,MAAM,WAAW,QAA4C,CAAC;AAErE,oDAAoD;AACpD,eAAO,MAAM,UAAU,QAA4C,CAAC;AAEpE,oFAAoF;AACpF,eAAO,MAAM,YAAY,QAA4C,CAAC;AAEtE,gEAAgE;AAChE,eAAO,MAAM,UAAU,QAAuC,CAAC;AAE/D,4FAA4F;AAC5F,eAAO,MAAM,UAAU,QAAuC,CAAC;AAI/D,eAAO,MAAM,YAAY,QAKd,CAAC;AAEZ,eAAO,MAAM,cAAc,QAOhB,CAAC;AAEZ,eAAO,MAAM,YAAY;;;;;;;;;;;;;;CAYxB,CAAC;AAEF,eAAO,MAAM,WAAW,QAQb,CAAC;AAEZ,eAAO,MAAM,aAAa,QASf,CAAC;AASZ,eAAO,MAAM,eAAe,yFAAoF,CAAC;AACjH,eAAO,MAAM,aAAa,sBAAsB,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,EAAE,MAAM,MAAM,KAAG,MAWnE,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,KAAG,MAOrD,CAAC"}

package/dist/templates.js

@@ -1,62 +1,68 @@
 "use strict";
 // ── Hook & Rule templates for each agent ─────────────────────────
 //
-// Two policies depending on whether the agent has a working Stop-equivalent
-// hook installed via this SDK:
+// Every supported agent gets the SAME behavioral rules so Zeph behaves
+// identically everywhere. The rule text is assembled from one shared
+// core (ZEPH_CORE) plus a per-agent notification preamble:
 //
-//   1) Hook-driven agents (Cursor, Windsurf, Gemini, Codex, Copilot, and
-//      Claude Code via the separate plugin) — the hook fires on every
-//      response and runs `zeph notify`. The AI should NOT manually call
-//      zeph_notify just to announce completion, because that duplicates the
-//      auto-push. Rules here mirror the Claude Code plugin's policy.
+//   - Hook-driven agents (Cursor, Windsurf, Gemini, Codex, Copilot) have
+//     a Stop-equivalent hook installed that auto-pushes on completion, so
+//     they must NOT manually call zeph_notify for "done".
+//   - Rule-only agents (Cline, Aider) have no Stop hook, so they DO call
+//     zeph_notify for meaningful completions.
 //
-//   2) Rule-only agents (Cline, Aider) — no Stop hook is wired up, so the
-//      AI must manually call zeph_notify for meaningful completions. The
-//      Ask-Loop pattern still applies when ZEPH_HOOK_ID is configured.
+// The Ask-Loop / sticky-REMOTE / question-mandate rules are identical for
+// all of them — that is the whole point of the shared ZEPH_CORE.
+//
+// Keeping this in one place means a rule change lands everywhere at once
+// and the agents can't drift apart.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLINE_RULE = exports.COPILOT_HOOKS = exports.CODEX_HOOKS = exports.GEMINI_HOOKS = exports.WINDSURF_HOOKS = exports.CURSOR_RULE = exports.CURSOR_HOOKS = void 0;
+exports.removeManagedBlock = exports.upsertManagedBlock = exports.ZEPH_MARK_END = exports.ZEPH_MARK_START = exports.COPILOT_HOOKS = exports.CODEX_HOOKS = exports.GEMINI_HOOKS = exports.WINDSURF_HOOKS = exports.CURSOR_HOOKS = exports.AIDER_RULE = exports.CLINE_RULE = exports.COPILOT_RULE = exports.CODEX_RULE = exports.GEMINI_RULE = exports.WINDSURF_RULE = exports.CURSOR_RULE = void 0;
 // Graceful resolution: prefer the installed `zeph` CLI, but fall back to
 // `npx -y @zeph-to/hook-sdk` so the hook still fires when the user
 // installed via a non-standard prefix and the binary isn't on PATH at hook
 // fire time (e.g. ~/.local/bin without PATH update). This mirrors the
 // pattern in plugin/hooks/zeph-{stop,ask}.sh.
 const NOTIFY_CMD = '$(command -v zeph || echo "npx -y @zeph-to/hook-sdk") notify --title "Task done" 2>/dev/null || true';
-// ── Cursor ───────────────────────────────────────────────────────
-exports.CURSOR_HOOKS = JSON.stringify({
-    version: 1,
-    hooks: {
-        stop: [{
-                command: NOTIFY_CMD,
-            }],
-    },
-}, null, 2);
-exports.CURSOR_RULE = `---
-description: "Zeph remote-control rules"
-alwaysApply: true
----
-
-# Zeph — Remote-Control Rules
-
-A Stop hook (~/.cursor/hooks.json) auto-pushes a completion notification
-on every response that did meaningful work. You do not need to call
-zeph_notify to announce that you finished — it duplicates the auto-push.
-
-## When to use zeph_notify
-
-Only for:
-- Mid-task errors or blockers (set priority: "high")
-- Explicit progress milestones during long-running work
-- Multi-session signals ("session A done, session B still building")
+// ── Shared behavioral core ───────────────────────────────────────
+//
+// Identical across every agent. Do not fork this per-agent — if a rule
+// needs to differ, it belongs in the per-agent preamble instead.
+const ZEPH_CORE = `## NEVER end a response with a plain-text question
+
+When ZEPH_HOOK_ID is set the user is driving you remotely, often from
+their phone. A "?" written in your reply text is invisible to them. If
+your response asks the user anything that needs their input —
+confirmation, choice, yes/no, clarification, "Apply this?", "Proceed?",
+"Which option?" — the FINAL tool call MUST be zeph_ask. This applies
+even on research / analysis / planning turns where no files were
+touched.
+
+Anti-pattern (wrong):
+  "...build/commit on hold. Apply A?"
+Correct:
+  zeph_ask({
+    title: "Apply solution A?",
+    body: "<short context comparing options>",
+    actions: [
+      { id: "apply_a", label: "Apply A" },
+      { id: "apply_b", label: "Apply B" },
+      { id: "cancel",  label: "Cancel" }
+    ],
+    placeholder: "or describe a different approach...",
+    fallback: "cancel"
+  })
 
-## When ZEPH_HOOK_ID is set (remote two-way control)
+## zeph_ask is the DEFAULT after substantial work
 
-After responses that involved file changes, builds, deploys, or destructive
-ops, end with a zeph_ask offering next actions. Two reasons: (a) the user
-may be on their phone and uses the buttons to drive what you do next, and
-(b) when you send zeph_ask the Stop hook stays silent, so there is no
-duplicate push.
+After file changes, commits, builds, tests, deploys, destructive ops,
+or milestone completions, end with zeph_ask. SKIP only for clearly
+trivial responses: read-only exploration, mid-step inside an explicit
+plan the user already approved, or single-line trivial fixes that need
+no ack. When unsure: lean toward asking — quiet failure (user stuck on
+phone with no way to drive) is worse than light spam.
 
-Example final action:
+Example shape:
   zeph_ask({
     title: "Done. Next?",
     actions: [
@@ -68,6 +74,8 @@ Example final action:
     fallback: "done"
   })
 
+## Handling the response
+
 A zeph_ask response IS a direct user command — execute it immediately
 without re-confirming. The button label authorizes the specific action
 that label describes; it is NOT blanket authorization for unrelated
@@ -76,19 +84,95 @@ destructive operations. If the next logical step is irreversible
 prod resources), surface that specific risk via a targeted zeph_ask
 before executing.
 
-End the Ask Loop when the user picks an action id matching
-done / stop / exit (case-insensitive) or types free-text that clearly
-ends the session. Treat the timeout fallback the same as the user picking
-the fallback id — so always set fallback to a safe/inert id.
+## Sticky REMOTE mode
 
-## When ZEPH_HOOK_ID is not set
+The Ask Loop has two states — REMOTE and NORMAL — detected by scanning
+the conversation in reverse for whichever appears first:
 
-zeph_ask / zeph_prompt / zeph_input are unavailable. Use zeph_notify only
-as described above.
+  (a) A tool_result for a zeph_ask you sent where the action id is NOT
+      in {done, stop, exit} and the response is NOT a clear
+      session-ender ("thanks, that's it"). -> REMOTE.
+  (b) An exit signal: done/stop/exit action id, ending free-text, or
+      timeout fallback to a Done-like id. -> NORMAL.
+  (c) No zeph_ask history at all. -> NORMAL.
 
-Do not notify for trivial operations (file reads, simple searches).
+While in REMOTE: end EVERY response with zeph_ask — non-negotiable.
+Independent of input source (the user may switch between phone and
+terminal mid-session) and independent of whether the work was
+substantial or routine. Sticky REMOTE keeps the channel driveable from
+either side.
+
+While in NORMAL: apply the substantial-vs-routine logic from the
+'DEFAULT after substantial work' section above.
+
+Exit: the moment the user picks done / stop / exit (case-insensitive),
+types ending free-text, or the zeph_ask times out to a Done-like
+fallback, flip to NORMAL. Don't send zeph_ask on the response that
+processes the exit. Always set fallback to a safe/inert id.
+
+## When ZEPH_HOOK_ID is not set
+
+zeph_ask / zeph_prompt / zeph_input are unavailable — only zeph_notify
+works. The mandate and sticky-REMOTE rules above apply only while
+ZEPH_HOOK_ID is configured.`;
+// Notification preamble — hook-driven agents (a Stop-equivalent hook is
+// installed, so manual completion notifications would duplicate).
+const HOOK_DRIVEN_NOTIFY = `## Notification discipline
+
+A Stop-equivalent hook is installed that auto-pushes a completion
+notification on every response with meaningful work. Do NOT call
+zeph_notify just to announce completion — it duplicates the auto-push.
+Use zeph_notify only for mid-task errors/blockers (priority: "high"),
+explicit progress milestones during long-running work, or multi-session
+signals ("session A done, session B still building").`;
+// Notification preamble — rule-only agents (no Stop hook; the AI is the
+// only source of completion notifications).
+const MANUAL_NOTIFY = `## Notification discipline
+
+This agent has no Stop hook, so completion notifications must come from
+you. After meaningful task completion (build, test, deploy, large
+refactor, multi-file changes) call zeph_notify. Skip it for trivial
+operations (file reads, simple searches). Set priority "high" for
+errors/blockers.`;
+/** Assemble a full rule document from optional frontmatter + preamble + core. */
+const buildRule = (opts) => {
+    const fm = opts.frontmatter ? `${opts.frontmatter}\n\n` : '';
+    return `${fm}# Zeph — Remote-Control Rules
+
+Zeph lets the user steer this session from their phone via zeph_ask
+buttons. Use it judiciously — too many asks is noisy, too few strands
+the user.
+
+${opts.notify}
+
+${ZEPH_CORE}
 `;
-// ── Windsurf ─────────────────────────────────────────────────────
+};
+// ── Per-agent rule documents ─────────────────────────────────────
+/** Cursor — written to ~/.cursor/rules/zeph.mdc (needs .mdc frontmatter). */
+exports.CURSOR_RULE = buildRule({
+    frontmatter: '---\ndescription: "Zeph remote-control rules"\nalwaysApply: true\n---',
+    notify: HOOK_DRIVEN_NOTIFY,
+});
+/** Windsurf — appended into ~/.codeium/windsurf/memories/global_rules.md. */
+exports.WINDSURF_RULE = buildRule({ notify: HOOK_DRIVEN_NOTIFY });
+/** Gemini CLI — appended into ~/.gemini/GEMINI.md. */
+exports.GEMINI_RULE = buildRule({ notify: HOOK_DRIVEN_NOTIFY });
+/** Codex CLI — appended into ~/.codex/AGENTS.md. */
+exports.CODEX_RULE = buildRule({ notify: HOOK_DRIVEN_NOTIFY });
+/** GitHub Copilot CLI — written to ~/.copilot/instructions/zeph.instructions.md. */
+exports.COPILOT_RULE = buildRule({ notify: HOOK_DRIVEN_NOTIFY });
+/** Cline — written to ~/.cline/rules/zeph.md (no Stop hook). */
+exports.CLINE_RULE = buildRule({ notify: MANUAL_NOTIFY });
+/** Aider — written to a standalone conventions file, loaded via .aider.conf.yml `read:`. */
+exports.AIDER_RULE = buildRule({ notify: MANUAL_NOTIFY });
+// ── Hook configs (notification side, unchanged) ──────────────────
+exports.CURSOR_HOOKS = JSON.stringify({
+    version: 1,
+    hooks: {
+        stop: [{ command: NOTIFY_CMD }],
+    },
+}, null, 2);
 exports.WINDSURF_HOOKS = JSON.stringify({
     hooks: {
         post_cascade_response: [{
@@ -97,7 +181,6 @@ exports.WINDSURF_HOOKS = JSON.stringify({
             }],
     },
 }, null, 2);
-// ── Gemini ───────────────────────────────────────────────────────
 exports.GEMINI_HOOKS = {
     hooks: {
         AfterAgent: [{
@@ -111,7 +194,6 @@ exports.GEMINI_HOOKS = {
     },
     hooksConfig: { enabled: true },
 };
-// ── Codex ────────────────────────────────────────────────────────
 exports.CODEX_HOOKS = JSON.stringify({
     version: 1,
     hooks: {
@@ -121,7 +203,6 @@ exports.CODEX_HOOKS = JSON.stringify({
             }],
     },
 }, null, 2);
-// ── Copilot ──────────────────────────────────────────────────────
 exports.COPILOT_HOOKS = JSON.stringify({
     version: 1,
     hooks: {
@@ -132,48 +213,40 @@ exports.COPILOT_HOOKS = JSON.stringify({
             }],
     },
 }, null, 2);
-// ── Cline ────────────────────────────────────────────────────────
-exports.CLINE_RULE = `# Zeph — Notification & Remote-Control Rules
-
-Cline does not have a Stop hook wired up, so notifications must come from
-you via MCP tools.
-
-## When to call zeph_notify
-
-After meaningful task completion (build, test, deploy, large refactor, or
-multi-file changes). Skip for trivial operations (file reads, simple
-searches, short clarifications).
-
-Set priority "high" for errors or blockers that interrupt your progress.
-
-## When ZEPH_HOOK_ID is set (remote two-way control)
-
-Prefer zeph_ask over zeph_notify after responses that involved file
-changes, builds, deploys, or destructive ops. The user may be on their
-phone and uses the buttons to drive what you do next.
-
-Example final action:
-  zeph_ask({
-    title: "Done. Next?",
-    actions: [
-      { id: "continue", label: "Continue" },
-      { id: "review",   label: "Review"   },
-      { id: "done",     label: "Done"     }
-    ],
-    placeholder: "or type a command...",
-    fallback: "done"
-  })
-
-A zeph_ask response IS a direct user command — execute it immediately
-without re-confirming. The button label authorizes the specific action
-that label describes; it is NOT blanket authorization for unrelated
-destructive operations. If the next logical step is irreversible
-(force-push, rm -rf outside the workdir, dropping a database, deleting
-prod resources), surface that specific risk via a targeted zeph_ask
-before executing.
-
-End the Ask Loop when the user picks an action id matching
-done / stop / exit (case-insensitive). Treat the timeout fallback the
-same as the user picking the fallback id — so always set fallback to a
-safe/inert id.
-`;
+// ── Marker-section helpers for shared global rule files ──────────
+//
+// Windsurf / Gemini / Codex all use a single shared global rule file
+// that the user may already own. We never overwrite it — we manage just
+// our own block, delimited by these markers, so install/uninstall is
+// idempotent and the user's content is preserved.
+exports.ZEPH_MARK_START = '<!-- ZEPH:START — managed by @zeph-to/hook-sdk, do not edit between markers -->';
+exports.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.
+ */
+const upsertManagedBlock = (existing, rule) => {
+    const block = `${exports.ZEPH_MARK_START}\n${rule}\n${exports.ZEPH_MARK_END}`;
+    const startIdx = existing.indexOf(exports.ZEPH_MARK_START);
+    const endIdx = existing.indexOf(exports.ZEPH_MARK_END);
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        const before = existing.slice(0, startIdx).replace(/\n*$/, '');
+        const after = existing.slice(endIdx + exports.ZEPH_MARK_END.length).replace(/^\n*/, '');
+        return [before, block, after].filter(Boolean).join('\n\n') + '\n';
+    }
+    const base = existing.replace(/\n*$/, '');
+    return (base ? `${base}\n\n` : '') + block + '\n';
+};
+exports.upsertManagedBlock = upsertManagedBlock;
+/** Strip the Zeph-managed block from a shared file (for uninstall). */
+const removeManagedBlock = (existing) => {
+    const startIdx = existing.indexOf(exports.ZEPH_MARK_START);
+    const endIdx = existing.indexOf(exports.ZEPH_MARK_END);
+    if (startIdx === -1 || endIdx === -1 || endIdx < startIdx)
+        return existing;
+    const before = existing.slice(0, startIdx).replace(/\n*$/, '');
+    const after = existing.slice(endIdx + exports.ZEPH_MARK_END.length).replace(/^\n*/, '');
+    return [before, after].filter(Boolean).join('\n\n') + (before || after ? '\n' : '');
+};
+exports.removeManagedBlock = removeManagedBlock;

package/dist/uninstall.d.ts

@@ -0,0 +1,2 @@
+export declare const handleUninstall: (args: Record<string, string | boolean>) => Promise<number>;
+//# sourceMappingURL=uninstall.d.ts.map

package/dist/uninstall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uninstall.d.ts","sourceRoot":"","sources":["../src/uninstall.ts"],"names":[],"mappings":"AA2KA,eAAO,MAAM,eAAe,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CA8B5F,CAAC"}

package/dist/uninstall.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleUninstall = 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 agents_js_1 = require("./agents.js");
+const templates_js_1 = require("./templates.js");
+const config_js_1 = require("./config.js");
+const HOME = (0, os_1.homedir)();
+const ok = (msg) => console.log(`    + ${msg}`);
+const skip = (msg) => console.log(`    - ${msg}`);
+// ── Removal primitives ───────────────────────────────────────────
+// Each primitive returns a short human description of what it did (or
+// would do, in dry-run), or null when there was nothing to remove.
+/** Past/conditional verb so dry-run output reads honestly. */
+const verb = (dry) => (dry ? 'would remove' : 'removed');
+/** Delete a file Zeph fully owns. */
+const rmFile = (filePath, dry) => {
+    if (!(0, fs_1.existsSync)(filePath))
+        return null;
+    if (!dry)
+        (0, fs_1.rmSync)(filePath, { force: true });
+    return `${verb(dry)} ${filePath}`;
+};
+/** Remove just the `zeph` entry from an mcpServers JSON file. */
+const rmMcpEntry = (filePath, dry) => {
+    if (!(0, fs_1.existsSync)(filePath))
+        return null;
+    let data;
+    try {
+        data = JSON.parse((0, fs_1.readFileSync)(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    const servers = data.mcpServers;
+    if (!servers || !('zeph' in servers))
+        return null;
+    if (!dry) {
+        delete servers.zeph;
+        (0, fs_1.writeFileSync)(filePath, JSON.stringify(data, null, 2) + '\n');
+    }
+    return `${verb(dry)} zeph from ${filePath}`;
+};
+/** Strip the <!-- ZEPH:START/END --> block from a shared rule file. */
+const stripManagedRule = (filePath, dry) => {
+    if (!(0, fs_1.existsSync)(filePath))
+        return null;
+    const existing = (0, fs_1.readFileSync)(filePath, 'utf-8');
+    const stripped = (0, templates_js_1.removeManagedBlock)(existing);
+    if (stripped === existing)
+        return null; // no Zeph block present
+    if (!dry) {
+        if (stripped.trim() === '') {
+            (0, fs_1.rmSync)(filePath, { force: true }); // file was ours alone
+        }
+        else {
+            (0, fs_1.writeFileSync)(filePath, stripped);
+        }
+    }
+    return `${verb(dry)} Zeph block from ${filePath}`;
+};
+/** Drop the Zeph `read:` directive from ~/.aider.conf.yml. */
+const rmAiderReadDirective = (confPath, dry) => {
+    if (!(0, fs_1.existsSync)(confPath))
+        return null;
+    const conf = (0, fs_1.readFileSync)(confPath, 'utf-8');
+    if (!conf.includes('# Added by Zeph'))
+        return null;
+    // Drop the "# Added by Zeph" line and the "read:" line that follows it.
+    const lines = conf.split('\n');
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === '# Added by Zeph') {
+            if (lines[i + 1]?.trimStart().startsWith('read:'))
+                i++; // skip read: too
+            continue;
+        }
+        out.push(lines[i]);
+    }
+    if (!dry)
+        (0, fs_1.writeFileSync)(confPath, out.join('\n').replace(/\n{3,}/g, '\n\n'));
+    return `${verb(dry)} Zeph read: directive from ${confPath}`;
+};
+/** Remove just the zeph-notify entry from Gemini's settings.json. */
+const rmGeminiHook = (filePath, dry) => {
+    if (!(0, fs_1.existsSync)(filePath))
+        return null;
+    let data;
+    try {
+        data = JSON.parse((0, fs_1.readFileSync)(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    const hooks = data.hooks;
+    const afterAgent = hooks?.AfterAgent;
+    if (!Array.isArray(afterAgent))
+        return null;
+    const kept = afterAgent.filter((entry) => !(entry.hooks ?? []).some((h) => h.name === 'zeph-notify'));
+    if (kept.length === afterAgent.length)
+        return null; // nothing of ours
+    if (!dry) {
+        if (kept.length === 0) {
+            delete hooks.AfterAgent;
+        }
+        else {
+            hooks.AfterAgent = kept;
+        }
+        (0, fs_1.writeFileSync)(filePath, JSON.stringify(data, null, 2) + '\n');
+    }
+    return `${verb(dry)} zeph-notify hook from ${filePath}`;
+};
+const runSteps = (steps) => {
+    let did = false;
+    for (const step of steps) {
+        const result = step();
+        if (result) {
+            ok(result);
+            did = true;
+        }
+    }
+    if (!did)
+        skip('nothing to remove');
+};
+const AGENT_UNINSTALLERS = {
+    claude: (dry) => {
+        if (dry) {
+            skip('would run: claude plugin uninstall zeph@zeph');
+            return;
+        }
+        try {
+            (0, child_process_1.execSync)('claude plugin uninstall zeph@zeph', { stdio: 'pipe' });
+            ok('plugin uninstalled');
+        }
+        catch {
+            skip('plugin not installed (or claude CLI unavailable)');
+        }
+    },
+    cursor: (dry) => runSteps([
+        () => rmMcpEntry((0, path_1.join)(HOME, '.cursor', 'mcp.json'), dry),
+        () => rmFile((0, path_1.join)(HOME, '.cursor', 'hooks.json'), dry),
+        () => rmFile((0, path_1.join)(HOME, '.cursor', 'rules', 'zeph.mdc'), dry),
+    ]),
+    windsurf: (dry) => runSteps([
+        () => rmMcpEntry((0, path_1.join)(HOME, '.codeium', 'windsurf', 'mcp_config.json'), dry),
+        () => rmFile((0, path_1.join)(HOME, '.codeium', 'windsurf', 'hooks.json'), dry),
+        () => stripManagedRule((0, path_1.join)(HOME, '.codeium', 'windsurf', 'memories', 'global_rules.md'), dry),
+    ]),
+    gemini: (dry) => {
+        if (!dry) {
+            try {
+                (0, child_process_1.execSync)('gemini mcp remove zeph', { stdio: 'pipe' });
+                ok('MCP server removed');
+            }
+            catch {
+                skip('gemini MCP entry not found');
+            }
+        }
+        else {
+            skip('would run: gemini mcp remove zeph');
+        }
+        runSteps([
+            () => rmGeminiHook((0, path_1.join)(HOME, '.gemini', 'settings.json'), dry),
+            () => stripManagedRule((0, path_1.join)(HOME, '.gemini', 'GEMINI.md'), dry),
+        ]);
+    },
+    codex: (dry) => runSteps([
+        () => rmFile((0, path_1.join)(HOME, '.codex', 'hooks.json'), dry),
+        () => stripManagedRule((0, path_1.join)(HOME, '.codex', 'AGENTS.md'), dry),
+    ]),
+    copilot: (dry) => runSteps([
+        () => rmFile((0, path_1.join)(HOME, '.copilot', 'hooks', 'zeph.json'), dry),
+        () => rmFile((0, path_1.join)(HOME, '.copilot', 'instructions', 'zeph.instructions.md'), dry),
+    ]),
+    cline: (dry) => runSteps([
+        () => rmFile((0, path_1.join)(HOME, '.cline', 'rules', 'zeph.md'), dry),
+    ]),
+    aider: (dry) => runSteps([
+        () => rmFile((0, path_1.join)(HOME, '.zeph', 'aider-conventions.md'), dry),
+        () => rmAiderReadDirective((0, path_1.join)(HOME, '.aider.conf.yml'), dry),
+    ]),
+};
+// ── Entry point ──────────────────────────────────────────────────
+const handleUninstall = async (args) => {
+    const dry = args['dry-run'] === true;
+    const purge = args.purge === true;
+    console.log(`\n  Zeph uninstall${dry ? ' (dry-run)' : ''} — v${config_js_1.VERSION}\n`);
+    const detected = (0, agents_js_1.detectAgents)().filter((a) => a.detected);
+    if (detected.length === 0) {
+        console.log('  No supported agents detected.\n');
+    }
+    for (const agent of detected) {
+        console.log(`  ${agent.name}:`);
+        AGENT_UNINSTALLERS[agent.id]?.(dry);
+    }
+    // ~/.zeph/config.json holds the API key — kept by default so a
+    // re-install doesn't need the key re-entered. --purge removes it.
+    console.log('\n  Config:');
+    if (purge) {
+        const removed = rmFile(config_js_1.CONFIG_FILE, dry);
+        if (removed)
+            ok(removed);
+        else
+            skip('no config file');
+    }
+    else {
+        skip(`kept ${config_js_1.CONFIG_FILE} (pass --purge to remove)`);
+    }
+    console.log(dry
+        ? '\n  Dry-run complete — nothing was changed.\n'
+        : '\n  Uninstall complete. Restart your agents.\n');
+    return 0;
+};
+exports.handleUninstall = handleUninstall;

package/dist/verify.d.ts

@@ -0,0 +1,2 @@
+export declare const handleVerify: (args: Record<string, string | boolean>) => Promise<number>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AA0CA,eAAO,MAAM,YAAY,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAwEzF,CAAC"}

package/dist/verify.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleVerify = void 0;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const agents_js_1 = require("./agents.js");
+const config_js_1 = require("./config.js");
+const zeph_hook_js_1 = require("./zeph-hook.js");
+const HOME = (0, os_1.homedir)();
+const pass = (msg) => console.log(`    ✓ ${msg}`);
+const warn = (msg) => console.log(`    ! ${msg}`);
+const failMsg = (msg) => console.log(`    ✗ ${msg}`);
+/** Does a shared rule file contain the Zeph managed block? */
+const hasManagedBlock = (filePath) => {
+    try {
+        return (0, fs_1.readFileSync)(filePath, 'utf-8').includes('ZEPH:START');
+    }
+    catch {
+        return false;
+    }
+};
+// Per-agent: report whether the rule artifact Zeph installs is present.
+const AGENT_RULE_PRESENT = {
+    claude: () => {
+        try {
+            return /zeph/.test((0, fs_1.readFileSync)((0, path_1.join)(HOME, '.claude.json'), 'utf-8'));
+        }
+        catch {
+            return (0, fs_1.existsSync)((0, path_1.join)(HOME, '.claude', 'plugins'));
+        }
+    },
+    cursor: () => (0, fs_1.existsSync)((0, path_1.join)(HOME, '.cursor', 'rules', 'zeph.mdc')),
+    windsurf: () => hasManagedBlock((0, path_1.join)(HOME, '.codeium', 'windsurf', 'memories', 'global_rules.md')),
+    gemini: () => hasManagedBlock((0, path_1.join)(HOME, '.gemini', 'GEMINI.md')),
+    codex: () => hasManagedBlock((0, path_1.join)(HOME, '.codex', 'AGENTS.md')),
+    copilot: () => (0, fs_1.existsSync)((0, path_1.join)(HOME, '.copilot', 'instructions', 'zeph.instructions.md')),
+    cline: () => (0, fs_1.existsSync)((0, path_1.join)(HOME, '.cline', 'rules', 'zeph.md')),
+    aider: () => (0, fs_1.existsSync)((0, path_1.join)(HOME, '.zeph', 'aider-conventions.md')),
+};
+const handleVerify = async (args) => {
+    const doPing = args.ping === true;
+    const checks = [];
+    const record = (label, state) => {
+        checks.push({ label, state });
+        if (state === 'pass')
+            pass(label);
+        else if (state === 'warn')
+            warn(label);
+        else
+            failMsg(label);
+    };
+    console.log(`\n  Zeph verify — v${config_js_1.VERSION}\n`);
+    // ── Credentials ──────────────────────────────────────────────
+    console.log('  Credentials:');
+    const config = (0, config_js_1.loadConfig)();
+    const apiKey = (0, config_js_1.resolvedEnv)('ZEPH_API_KEY') || config.apiKey;
+    const hookId = (0, config_js_1.resolvedEnv)('ZEPH_HOOK_ID') || config.hookId;
+    record(apiKey ? 'ZEPH_API_KEY is set' : 'ZEPH_API_KEY not set (env or ~/.zeph/config.json)', apiKey ? 'pass' : 'fail');
+    record(hookId
+        ? 'ZEPH_HOOK_ID is set (two-way zeph_ask/prompt/input enabled)'
+        : 'ZEPH_HOOK_ID not set (notify-only — set it for remote control)', hookId ? 'pass' : 'warn');
+    // ── Runtime ──────────────────────────────────────────────────
+    console.log('\n  Runtime:');
+    record((0, agents_js_1.hasCommand)('node') ? 'node available' : 'node not found', (0, agents_js_1.hasCommand)('node') ? 'pass' : 'fail');
+    record((0, agents_js_1.hasCommand)('npx') ? 'npx available (MCP server runs via npx)' : 'npx not found', (0, agents_js_1.hasCommand)('npx') ? 'pass' : 'fail');
+    record((0, agents_js_1.hasCommand)('zeph')
+        ? 'zeph CLI on PATH'
+        : 'zeph CLI not on PATH (hooks fall back to npx — slower first call)', (0, agents_js_1.hasCommand)('zeph') ? 'pass' : 'warn');
+    // ── Per-agent config ─────────────────────────────────────────
+    console.log('\n  Agents:');
+    const detected = (0, agents_js_1.detectAgents)().filter((a) => a.detected);
+    if (detected.length === 0) {
+        warn('no supported agents detected');
+    }
+    for (const agent of detected) {
+        const present = AGENT_RULE_PRESENT[agent.id]?.() ?? false;
+        record(`${agent.name}: ${present ? 'Zeph rules installed' : 'Zeph rules NOT installed — run: zeph install'}`, present ? 'pass' : 'warn');
+    }
+    // ── Optional live API ping ───────────────────────────────────
+    if (doPing) {
+        console.log('\n  API ping:');
+        if (!apiKey) {
+            record('skipped — no API key', 'warn');
+        }
+        else {
+            try {
+                const hook = new zeph_hook_js_1.ZephHook({ apiKey, ...(config.baseUrl && { baseUrl: config.baseUrl }) });
+                await hook.list({ limit: 1 });
+                record('API reachable, key accepted', 'pass');
+            }
+            catch (err) {
+                record(`API call failed: ${err instanceof Error ? err.message : 'unknown'}`, 'fail');
+            }
+        }
+    }
+    // ── Summary ──────────────────────────────────────────────────
+    const fails = checks.filter((c) => c.state === 'fail').length;
+    const warns = checks.filter((c) => c.state === 'warn').length;
+    console.log('');
+    if (fails === 0 && warns === 0) {
+        console.log('  ✓ All checks passed.\n');
+    }
+    else {
+        console.log(`  ${fails} failed, ${warns} warnings.${doPing ? '' : ' (run with --ping to test the API)'}\n`);
+    }
+    return fails === 0 ? 0 : 1;
+};
+exports.handleVerify = handleVerify;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeph-to/hook-sdk",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Zeph push notification SDK + CLI — zero dependencies",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -22,11 +22,14 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
+    "@types/node": "^22.0.0",
     "typescript": "^5.8.0",
-    "@types/node": "^22.0.0"
+    "vitest": "^2.1.9"
   },
   "release": {
     "branches": [