wazap-mcp 0.9.0

package/dist/connect.js

@@ -0,0 +1,222 @@
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, join, resolve } from "node:path";
+import { defaultDataDir } from "./config.js";
+import { WazapError } from "./errors.js";
+import { say } from "./logger.js";
+function claudeDesktopFile() {
+    if (process.platform === "darwin") {
+        return join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    if (process.platform === "win32") {
+        return join(process.env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+    }
+    return join(homedir(), ".config", "Claude", "claude_desktop_config.json");
+}
+export const CLIENTS = [
+    {
+        name: "claude-code",
+        describe: "Claude Code",
+        file: () => null,
+        format: "command",
+        keyPath: [],
+        next: "Run `claude mcp list` to confirm.",
+    },
+    {
+        name: "claude-desktop",
+        describe: "Claude Desktop",
+        file: claudeDesktopFile,
+        format: "json",
+        keyPath: ["mcpServers", "whatsapp"],
+        next: "Restart Claude Desktop.",
+    },
+    {
+        name: "cursor",
+        describe: "Cursor",
+        file: () => join(homedir(), ".cursor", "mcp.json"),
+        format: "json",
+        keyPath: ["mcpServers", "whatsapp"],
+        next: "Reload the Cursor window.",
+    },
+    {
+        name: "codex",
+        describe: "Codex CLI",
+        file: () => join(homedir(), ".codex", "config.toml"),
+        format: "toml",
+        keyPath: ["mcp_servers", "whatsapp"],
+        next: "Restart Codex.",
+    },
+    {
+        name: "vscode",
+        describe: "VS Code",
+        file: () => join(process.cwd(), ".vscode", "mcp.json"),
+        format: "json",
+        keyPath: ["servers", "whatsapp"],
+        extra: { type: "stdio" },
+        next: "Written to ./.vscode/mcp.json for this workspace. Reload the VS Code window.",
+    },
+    {
+        name: "gemini",
+        describe: "Gemini CLI",
+        file: () => join(homedir(), ".gemini", "settings.json"),
+        format: "json",
+        keyPath: ["mcpServers", "whatsapp"],
+        next: "Restart the Gemini CLI.",
+    },
+];
+export const CLIENT_NAMES = CLIENTS.map((client) => client.name).join(", ");
+export const CONNECT_HINT = `Next: wazap connect claude-code   (or ${CLIENTS.slice(1)
+    .map((client) => client.name)
+    .join(", ")})`;
+export function isNpxPath(binPath) {
+    return /[\\/]_npx[\\/]/.test(binPath);
+}
+const PATH_NAMES = process.platform === "win32" ? ["wazap.cmd", "wazap"] : ["wazap"];
+export function onPath(pathEnv, exists = existsSync) {
+    return pathEnv
+        .split(delimiter)
+        .filter(Boolean)
+        .some((dir) => PATH_NAMES.some((name) => exists(join(dir, name))));
+}
+/**
+ * How the client should launch wazap, from how it was launched now: through
+ * npx, as a global binary on PATH, or straight from a checkout that is on
+ * neither. A checkout written as `wazap` would point the client at a command
+ * that does not exist.
+ */
+export function launcher(binPath, pathEnv, exists) {
+    if (isNpxPath(binPath))
+        return { command: "npx", args: ["-y", "wazap-mcp"] };
+    if (onPath(pathEnv, exists))
+        return { command: "wazap", args: [] };
+    return { command: "node", args: [resolve(binPath)] };
+}
+export function mcpEntry(config) {
+    const entry = launcher(process.argv[1] ?? "", process.env.PATH ?? "");
+    if (config.dataDir !== defaultDataDir())
+        entry.args.push("--data-dir", config.dataDir);
+    if (config.readOnly)
+        entry.args.push("--read-only");
+    return entry;
+}
+const WRITERS = {
+    command: runClientCommand,
+    json: writeJsonEntry,
+    toml: writeTomlEntry,
+};
+export function runConnect(config) {
+    const name = config.args[0] ?? "";
+    const spec = CLIENTS.find((client) => client.name === name);
+    if (!spec) {
+        throw new WazapError("INVALID_ID", `Unknown client "${name}".`, `Pick one of: ${CLIENT_NAMES}`);
+    }
+    WRITERS[spec.format](spec, mcpEntry(config), config.dryRun);
+}
+/** Null only when the file is absent; an unreadable file must never be overwritten. */
+function readTextOrNull(file) {
+    try {
+        return readFileSync(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw new WazapError("INVALID_ID", `${file} cannot be read.`, "Fix its permissions or move the file aside, then run this again.");
+    }
+}
+function setIn(doc, keyPath, value) {
+    let node = doc;
+    for (const key of keyPath.slice(0, -1)) {
+        const child = node[key];
+        if (child === null || typeof child !== "object" || Array.isArray(child))
+            node[key] = {};
+        node = node[key];
+    }
+    node[keyPath[keyPath.length - 1]] = value;
+}
+function writeJsonEntry(spec, entry, dryRun) {
+    const file = spec.file();
+    const current = readTextOrNull(file);
+    let doc = {};
+    if (current !== null && current.trim() !== "") {
+        let parsed;
+        try {
+            parsed = JSON.parse(current);
+        }
+        catch {
+            throw new WazapError("INVALID_ID", `${file} is not valid JSON.`, "Fix the JSON or move the file aside, then run this again.");
+        }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new WazapError("INVALID_ID", `${file} is not a JSON object.`, "Fix the JSON or move the file aside, then run this again.");
+        }
+        doc = parsed;
+    }
+    const value = { ...spec.extra, command: entry.command, args: entry.args };
+    setIn(doc, spec.keyPath, value);
+    apply(spec, file, `${JSON.stringify(doc, null, 2)}\n`, current, dryRun, JSON.stringify(value, null, 2));
+}
+function writeTomlEntry(spec, entry, dryRun) {
+    const file = spec.file();
+    const current = readTextOrNull(file);
+    const header = `[${spec.keyPath.join(".")}]`;
+    const args = entry.args.map((arg) => JSON.stringify(arg)).join(", ");
+    const block = `${header}\ncommand = ${JSON.stringify(entry.command)}\nargs = [${args}]\n`;
+    apply(spec, file, spliceTomlTable(current ?? "", header, block), current, dryRun, block.trimEnd());
+}
+/** Replace the table under `header`, from its header line to the next one, or append it. */
+function spliceTomlTable(text, header, block) {
+    const lines = text.split("\n");
+    const start = lines.findIndex((line) => line.trim() === header);
+    if (start === -1) {
+        const base = text.trimEnd();
+        return base === "" ? block : `${base}\n\n${block}`;
+    }
+    let end = start + 1;
+    while (end < lines.length && !lines[end].trimStart().startsWith("["))
+        end++;
+    // Blank lines and comments just above the next header introduce that table.
+    while (end > start + 1 && /^\s*(#|$)/.test(lines[end - 1]))
+        end--;
+    const merged = [...lines.slice(0, start), ...block.trimEnd().split("\n"), ...lines.slice(end)].join("\n");
+    return merged.endsWith("\n") ? merged : `${merged}\n`;
+}
+function apply(spec, file, next, current, dryRun, shown) {
+    if (dryRun) {
+        say(`${spec.describe}: would write ${file}`);
+        say(shown);
+        say(`Next: ${spec.next}`);
+        return;
+    }
+    if (next === current) {
+        say(`${spec.describe}: ${file} already has this entry.`);
+        say(`Next: ${spec.next}`);
+        return;
+    }
+    mkdirSync(dirname(file), { recursive: true });
+    if (current !== null && !existsSync(`${file}.bak`))
+        copyFileSync(file, `${file}.bak`);
+    writeFileSync(file, next);
+    say(`${spec.describe}: wrote ${file}`);
+    say(shown);
+    say(`Next: ${spec.next}`);
+}
+function runClientCommand(spec, entry, dryRun) {
+    const argv = ["mcp", "add", "whatsapp", "--", entry.command, ...entry.args];
+    const shown = `claude ${argv.join(" ")}`;
+    if (dryRun) {
+        say(`${spec.describe}: would run`);
+        say(shown);
+        say(`Next: ${spec.next}`);
+        return;
+    }
+    const result = spawnSync("claude", argv, { stdio: "inherit" });
+    if (result.error !== undefined) {
+        say("`claude` is not on PATH. Run this yourself where Claude Code is installed:");
+        say(shown);
+        process.exit(1);
+    }
+    if (result.status !== 0)
+        process.exit(result.status ?? 1);
+    say(`${spec.describe}: registered the whatsapp MCP server.`);
+    say(`Next: ${spec.next}`);
+}

package/dist/doctor.js

@@ -0,0 +1,114 @@
+import { accessSync, constants, statSync } from "node:fs";
+import { readLinkedAccount } from "./auth-state.js";
+import { WAZAP_VERSION, paths } from "./config.js";
+import { lockHolder, lockPid } from "./lock.js";
+export const MARK = { ok: "✓", fail: "✗", info: "–" };
+const UPDATE_TIMEOUT_MS = 2_000;
+const MIN_NODE_MAJOR = 20;
+const CHECKS = [checkNode, checkDataDir, checkLock, checkCredentials, checkWrites, checkUpdate];
+export async function runChecks(config) {
+    const checks = [];
+    for (const check of CHECKS)
+        checks.push(await check(config));
+    return checks;
+}
+export function checkLine(check) {
+    return `${MARK[check.state]} ${check.name}: ${check.detail}${check.fix ? ` — ${check.fix}` : ""}`;
+}
+function checkNode() {
+    const version = process.versions.node;
+    const major = Number.parseInt(version.split(".")[0], 10);
+    return major >= MIN_NODE_MAJOR
+        ? { name: "node", state: "ok", detail: version }
+        : { name: "node", state: "fail", detail: `${version} is too old`, fix: `install Node ${MIN_NODE_MAJOR} or newer` };
+}
+function checkDataDir(config) {
+    const dir = config.dataDir;
+    let stat;
+    try {
+        stat = statSync(dir);
+    }
+    catch {
+        return { name: "data dir", state: "info", detail: `${dir} does not exist yet (login creates it)` };
+    }
+    if (!stat.isDirectory()) {
+        return { name: "data dir", state: "fail", detail: `${dir} is not a directory`, fix: "move it aside or use --data-dir" };
+    }
+    const mode = stat.mode & 0o777;
+    if (process.platform !== "win32" && mode !== 0o700) {
+        return {
+            name: "data dir",
+            state: "fail",
+            detail: `${dir} is mode ${mode.toString(8).padStart(4, "0")}, not 0700`,
+            fix: `run \`chmod 700 ${dir}\``,
+        };
+    }
+    try {
+        accessSync(dir, constants.W_OK);
+    }
+    catch {
+        return { name: "data dir", state: "fail", detail: `${dir} is not writable`, fix: "fix its ownership or permissions" };
+    }
+    return { name: "data dir", state: "ok", detail: `${dir} (0700, writable)` };
+}
+function checkLock(config) {
+    const lockFile = paths(config.dataDir).lockFile;
+    const alive = lockHolder(lockFile);
+    if (alive !== null)
+        return { name: "lock", state: "ok", detail: `held by a running server (pid ${alive})` };
+    const recorded = lockPid(lockFile);
+    if (recorded !== null) {
+        return { name: "lock", state: "info", detail: `stale (pid ${recorded} is gone); the next start reclaims it` };
+    }
+    return { name: "lock", state: "info", detail: "none" };
+}
+function checkCredentials(config) {
+    const authDir = paths(config.dataDir).authDir;
+    try {
+        const account = readLinkedAccount(authDir);
+        return account === null
+            ? { name: "credentials", state: "info", detail: "no account linked yet" }
+            : { name: "credentials", state: "ok", detail: `readable (${account.number})` };
+    }
+    catch (err) {
+        const wazap = err;
+        return { name: "credentials", state: "fail", detail: wazap.message, fix: wazap.fix };
+    }
+}
+function checkWrites(config) {
+    return {
+        name: "writes",
+        state: "ok",
+        detail: `${config.readOnly ? "off" : "on"} (${config.sources.readOnly})`,
+    };
+}
+/** Version comparison over the numeric release fields; prereleases sort as their release. */
+export function isNewer(candidate, current) {
+    const parts = (version) => version.split(/[.\-+]/, 3).map((piece) => Number.parseInt(piece, 10) || 0);
+    const [a, b] = [parts(candidate), parts(current)];
+    for (let i = 0; i < 3; i++) {
+        if ((a[i] ?? 0) !== (b[i] ?? 0))
+            return (a[i] ?? 0) > (b[i] ?? 0);
+    }
+    return false;
+}
+async function checkUpdate() {
+    if (process.env.WAZAP_NO_UPDATE_CHECK === "1") {
+        return { name: "update", state: "info", detail: "update check skipped (WAZAP_NO_UPDATE_CHECK=1)" };
+    }
+    try {
+        const response = await fetch("https://registry.npmjs.org/wazap-mcp/latest", {
+            signal: AbortSignal.timeout(UPDATE_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            return { name: "update", state: "info", detail: `update check skipped (registry answered ${response.status})` };
+        }
+        const { version } = (await response.json());
+        return isNewer(version, WAZAP_VERSION)
+            ? { name: "update", state: "info", detail: `${version} is out (running ${WAZAP_VERSION})`, fix: "run `npx wazap-mcp@latest`" }
+            : { name: "update", state: "ok", detail: `${WAZAP_VERSION} is current` };
+    }
+    catch {
+        return { name: "update", state: "info", detail: "update check skipped (offline)" };
+    }
+}

package/dist/errors.js

@@ -0,0 +1,48 @@
+export class WazapError extends Error {
+    code;
+    fix;
+    constructor(code, message, fix) {
+        super(message);
+        this.name = "WazapError";
+        this.code = code;
+        this.fix = fix;
+    }
+}
+export const RELINK_FIX = "Run `npx wazap-mcp login`";
+export const RESET_FIX = "Run `npx wazap-mcp logout` then `npx wazap-mcp login`";
+/** What an agent should do about each code. Rendered by the `learn` tool. */
+export const ERROR_GUIDE = {
+    NOT_LINKED: "No WhatsApp account is linked. Tell the user to run `npx wazap-mcp login`; do not retry.",
+    SESSION_EXPIRED: "The account was unlinked from the phone. Tell the user to run `npx wazap-mcp login`; do not retry.",
+    SESSION_CORRUPT: "Stored credentials are unreadable. Tell the user to run `npx wazap-mcp logout` then `npx wazap-mcp login`.",
+    NOT_CONNECTED: "The socket is still connecting or reconnecting. Call get_status, wait, retry once.",
+    SYNC_IN_PROGRESS: "History sync has not finished. Retry in a few seconds; earlier messages may be missing until then.",
+    INVALID_PHONE: "The number is not in international format. Ask the user for a number with a country code, e.g. +40722123456.",
+    INVALID_ID: "The id is not a WhatsApp chat, contact or group id. Use an id exactly as returned by another tool.",
+    NOT_ON_WHATSAPP: "That number has no WhatsApp account. Do not retry; confirm the number with the user.",
+    CHAT_NOT_FOUND: "No such chat is known. Call list_chats or search_contacts to get a valid chat_id.",
+    MESSAGE_NOT_FOUND: "No such message is loaded. Use a message_id from read_messages or search_messages.",
+    CONTACT_NOT_FOUND: "No such contact is known. Call search_contacts first.",
+    GROUP_NOT_FOUND: "No such group is known, or the id is not a group id (it must end in @g.us).",
+    NOT_A_PARTICIPANT: "The linked account is not in that group. Do not retry.",
+    NOT_ADMIN: "The linked account is not an admin of that group, so this action is refused. Do not retry.",
+    GROUP_ANNOUNCEMENT_ONLY: "Only admins may post in that group. Do not retry.",
+    MEDIA_UNAVAILABLE: "The media expired on WhatsApp's servers or was never synced. Do not retry; ask the sender to resend.",
+    FILE_NOT_FOUND: "The local path does not exist on the machine running wazap. Check the path with the user.",
+    FILE_TOO_LARGE: "The file exceeds WhatsApp's 100 MB limit. Send a smaller file.",
+    URL_FETCH_FAILED: "The URL could not be fetched. Check it, or download the file first and pass file_path.",
+    TEXT_TOO_LONG: "The text exceeds WhatsApp's limit. Split it into several messages.",
+    EDIT_WINDOW_EXPIRED: "WhatsApp only allows editing within 15 minutes of sending. Send a correction instead.",
+    RETRACT_WINDOW_EXPIRED: "WhatsApp only allows deleting for everyone within 2 days. Do not retry.",
+    NOT_OWN_MESSAGE: "This action only works on messages the linked account sent. Do not retry.",
+    READ_ONLY: "wazap runs read-only, so writes are refused. Tell the user to restart without WAZAP_READ_ONLY.",
+    RATE_LIMITED: "Too many writes too fast. Wait the number of seconds in the fix, then retry once.",
+    TIMEOUT: "WhatsApp did not answer in time. Retry once; if it fails again, call get_status.",
+    WHATSAPP_ERROR: "WhatsApp rejected the operation. Read the message; do not blindly retry.",
+};
+/** Any thrown value as a WazapError, so no tool ever surfaces a raw error. */
+export function asWazapError(err) {
+    if (err instanceof WazapError)
+        return err;
+    return new WazapError("WHATSAPP_ERROR", err instanceof Error ? err.message : String(err));
+}

package/dist/ids.js

@@ -0,0 +1,50 @@
+import { WazapError } from "./errors.js";
+const PHONE_EXAMPLE = "Use international format, e.g. +40722123456";
+/** Digits of a phone number in international format, or INVALID_PHONE. */
+export function normalizePhone(input) {
+    const digits = input.trim().replace(/^\+/, "").replace(/[\s\-().]/g, "");
+    if (!/^\d+$/.test(digits) || digits.startsWith("0") || digits.length < 8 || digits.length > 15) {
+        throw new WazapError("INVALID_PHONE", `"${input.trim()}" is not a phone number in international format.`, PHONE_EXAMPLE);
+    }
+    return digits;
+}
+export function isGroupId(jid) {
+    return jid.endsWith("@g.us");
+}
+/**
+ * Canonicalize anything a caller may pass as a chat id.
+ * Individuals become `<digits>@s.whatsapp.net`, groups stay `<id>@g.us`.
+ * A `@lid` is translated through `lidToPn` when the mapping is known; without
+ * one the lid is kept, because it still addresses the chat.
+ */
+export function resolveChatId(input, lidToPn) {
+    const trimmed = (input ?? "").trim();
+    if (!trimmed)
+        throw new WazapError("INVALID_ID", "Empty chat id.", "Pass an id from list_chats or search_contacts");
+    const at = trimmed.lastIndexOf("@");
+    if (at === -1)
+        return `${normalizePhone(trimmed)}@s.whatsapp.net`;
+    const user = trimmed.slice(0, at).split(":")[0];
+    const domain = trimmed.slice(at + 1).toLowerCase();
+    if (domain === "g.us") {
+        if (!/^[\w.@-]+$/.test(user))
+            throw new WazapError("INVALID_ID", `"${trimmed}" is not a valid group id.`);
+        return `${user}@g.us`;
+    }
+    if (domain === "lid") {
+        const mapped = lidToPn?.(`${user}@lid`);
+        if (mapped)
+            return `${digitsOrThrow(mapped, trimmed)}@s.whatsapp.net`;
+        return `${user}@lid`;
+    }
+    if (domain === "s.whatsapp.net" || domain === "c.us") {
+        return `${digitsOrThrow(user, trimmed)}@s.whatsapp.net`;
+    }
+    throw new WazapError("INVALID_ID", `"${trimmed}" is not a WhatsApp id.`, "Expected a phone number, <digits>@s.whatsapp.net or <id>@g.us");
+}
+function digitsOrThrow(value, original) {
+    const digits = value.split("@")[0].split(":")[0];
+    if (!/^\d+$/.test(digits))
+        throw new WazapError("INVALID_ID", `"${original}" is not a WhatsApp id.`);
+    return digits;
+}

package/dist/index.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { BANNER } from "./banner.js";
+import { runGreet, runLogin, runLogout, runServe, runStatus } from "./cli.js";
+import { WAZAP_VERSION, parseCli, pickDefaultAction } from "./config.js";
+import { CLIENT_NAMES, runConnect } from "./connect.js";
+import { runConfig } from "./settings.js";
+import { WazapError } from "./errors.js";
+import { say } from "./logger.js";
+const USAGE = `${BANNER}
+
+Usage:
+  wazap [serve] [--http] [--host <host>] [--port <port>]   Run the MCP server (default: stdio)
+  wazap login [--phone +40722123456] [--qr]                Link a WhatsApp account
+  wazap connect <client> [--dry-run]                       Register wazap with an MCP client
+  wazap config [writes on|off]                             Show the effective settings, or allow/refuse writes
+  wazap status [--live] [--json]                           Check the install, the session and the server
+  wazap logout                                             Unlink and delete local credentials
+
+Clients for wazap connect: ${CLIENT_NAMES}.
+
+Options:
+  --data-dir <path>   Where wazap keeps its data (default ~/.wazap, or $WAZAP_DATA_DIR)
+  --read-only         Refuse every write; the write tools are not registered at all
+  --http              Serve Streamable HTTP instead of stdio
+  --host <host>       HTTP bind address (default 127.0.0.1)
+  --port <port>       HTTP port (default 8766)
+  --phone <number>    Phone number in international format, for login
+  --qr                Log in by QR code instead of a pairing code
+  --dry-run           With connect: print what would be written, and write nothing
+  --live              With status: reach WhatsApp for real, then close the connection
+  --json              With status: print the whole report as one JSON object on stdout
+  --writes            Allow the agent to write, without login asking
+  --no-writes         Keep the agent read-only, without login asking
+  -y, --yes           Do not ask anything at the end of login
+  -h, --help          Show this help
+  -v, --version       Show the version
+
+Environment: WAZAP_DATA_DIR, WAZAP_READ_ONLY, WAZAP_SYNC_FULL_HISTORY, WAZAP_PERSIST_HISTORY,
+WAZAP_TRANSPORT, WAZAP_HOST, WAZAP_PORT, WAZAP_READ_TOKEN, WAZAP_WRITE_TOKEN, WAZAP_RATE_LIMIT,
+WAZAP_NO_UPDATE_CHECK.
+An optional <data-dir>/.env is loaded if present.`;
+async function main() {
+    const invocation = parseCli();
+    if (invocation.kind === "help") {
+        say(USAGE);
+        return;
+    }
+    if (invocation.kind === "version") {
+        say(WAZAP_VERSION);
+        return;
+    }
+    const { config } = invocation;
+    switch (config.command) {
+        case "serve":
+            if (pickDefaultAction(config, process.stdin.isTTY === true, process.stderr.isTTY === true) === "greet") {
+                await runGreet(config);
+                return;
+            }
+            await runServe(config);
+            return;
+        case "login":
+            await runLogin(config);
+            return;
+        case "connect":
+            runConnect(config);
+            return;
+        case "config":
+            runConfig(config);
+            return;
+        case "status":
+            await runStatus(config);
+            return;
+        case "logout":
+            await runLogout(config);
+            return;
+    }
+}
+main().catch((err) => {
+    if (err instanceof WazapError) {
+        say(err.message);
+        if (err.fix)
+            say(err.fix);
+    }
+    else {
+        say(err instanceof Error ? err.message : String(err));
+    }
+    process.exit(1);
+});

package/dist/lock.js

@@ -0,0 +1,42 @@
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+/** Pid recorded in the lock file, whether or not that process is still alive. */
+export function lockPid(lockFile) {
+    let pid;
+    try {
+        pid = Number.parseInt(readFileSync(lockFile, "utf8").trim(), 10);
+    }
+    catch {
+        return null;
+    }
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+/** Pid of the live process holding the lock, or null if free (missing or stale). */
+export function lockHolder(lockFile) {
+    const pid = lockPid(lockFile);
+    if (pid === null)
+        return null;
+    try {
+        process.kill(pid, 0);
+        return pid;
+    }
+    catch (err) {
+        // EPERM means the pid exists but belongs to another user, so it is alive.
+        return err.code === "EPERM" ? pid : null;
+    }
+}
+export function writeLock(lockFile) {
+    mkdirSync(dirname(lockFile), { recursive: true, mode: 0o700 });
+    writeFileSync(lockFile, `${process.pid}\n`, { mode: 0o600 });
+}
+/** Remove the lock, but only if it is still ours. */
+export function releaseLock(lockFile) {
+    try {
+        if (Number.parseInt(readFileSync(lockFile, "utf8").trim(), 10) !== process.pid)
+            return;
+        unlinkSync(lockFile);
+    }
+    catch {
+        /* already gone */
+    }
+}

package/dist/logger.js

@@ -0,0 +1,16 @@
+/**
+ * stdout is the MCP JSON-RPC channel, so every human-readable line goes to
+ * stderr. Anything else on stdout corrupts the protocol stream.
+ */
+const PREFIX = "[wazap]";
+export function log(...args) {
+    console.error(PREFIX, ...args);
+}
+export function logError(context, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`${PREFIX} ERROR (${context}):`, message);
+}
+/** CLI output for a human at a terminal. Also stderr, for the same reason. */
+export function say(...args) {
+    console.error(...args);
+}