@zeph-to/hook-sdk 1.7.0 → 1.8.0

package/dist/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,YAAY,QAOd,CAAC;AAEZ,eAAO,MAAM,WAAW,+TAQvB,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,sPAGtB,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,27 +1,178 @@
 "use strict";
 // ── Hook & Rule templates for each agent ─────────────────────────
+//
+// 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:
+//
+//   - 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.
+//
+// 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;
-const NOTIFY_CMD = 'npx @zeph-to/hook-sdk notify --title "Task done" 2>/dev/null || true';
-// ── Cursor ───────────────────────────────────────────────────────
+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';
+// ── 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"
+  })
+
+## zeph_ask is the DEFAULT after substantial work
+
+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 shape:
+  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"
+  })
+
+## 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
+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.
+
+## Sticky REMOTE mode
+
+The Ask Loop has two states — REMOTE and NORMAL — detected by scanning
+the conversation in reverse for whichever appears first:
+
+  (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.
+
+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}
+`;
+};
+// ── 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,
-            }],
+        stop: [{ command: NOTIFY_CMD }],
     },
 }, null, 2);
-exports.CURSOR_RULE = `---
-description: "Zeph notification rules"
-alwaysApply: true
----
-
-When you complete a coding task, call the zeph_notify MCP tool with a brief summary.
-Use zeph_prompt for user decisions (2-4 options). Use zeph_input for free-form text.
-Do not notify for trivial operations (file reads, simple searches).
-`;
-// ── Windsurf ─────────────────────────────────────────────────────
 exports.WINDSURF_HOOKS = JSON.stringify({
     hooks: {
         post_cascade_response: [{
@@ -30,7 +181,6 @@ exports.WINDSURF_HOOKS = JSON.stringify({
             }],
     },
 }, null, 2);
-// ── Gemini ───────────────────────────────────────────────────────
 exports.GEMINI_HOOKS = {
     hooks: {
         AfterAgent: [{
@@ -44,7 +194,6 @@ exports.GEMINI_HOOKS = {
     },
     hooksConfig: { enabled: true },
 };
-// ── Codex ────────────────────────────────────────────────────────
 exports.CODEX_HOOKS = JSON.stringify({
     version: 1,
     hooks: {
@@ -54,7 +203,6 @@ exports.CODEX_HOOKS = JSON.stringify({
             }],
     },
 }, null, 2);
-// ── Copilot ──────────────────────────────────────────────────────
 exports.COPILOT_HOOKS = JSON.stringify({
     version: 1,
     hooks: {
@@ -65,8 +213,40 @@ exports.COPILOT_HOOKS = JSON.stringify({
             }],
     },
 }, null, 2);
-// ── Cline ────────────────────────────────────────────────────────
-exports.CLINE_RULE = `When you complete a coding task, call the zeph_notify MCP tool with a brief summary.
-Use zeph_prompt for user decisions (2-4 options). Use zeph_input for free-form text.
-Do not notify for trivial operations (file reads, simple searches).
-`;
+// ── 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.0",
+  "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": [