@gramatr/mcp 0.13.128 → 0.13.130

package/dist/bin/install.js

@@ -15,9 +15,11 @@
  * Scope: Claude Code only in v1. Codex / Cursor / Gemini stay on `setup`
  * subcommands until follow-up.
  */
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { platform as osPlatform } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { buildConnectorInstructions, buildPromptSuggestion } from "../setup/web-connector.js";
 /** Sentinel pair carved into ~/.claude/CLAUDE.md. */
 export const GRAMATR_MD_START = "<!-- GRAMATR-START -->";
 export const GRAMATR_MD_END = "<!-- GRAMATR-END -->";
@@ -61,6 +63,27 @@ export function gramatrStopScriptPath(home) {
 export function gramatrTokenPath(home) {
     return join(home, ".gramatr.json");
 }
+/** Path to Claude Code slash-command directory. */
+export function claudeCommandsDir(home) {
+    return join(home, ".claude", "commands");
+}
+/**
+ * Resolve the claude_desktop_config.json path for the current platform.
+ * macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
+ * Windows: %APPDATA%\Claude\claude_desktop_config.json
+ * Linux: ~/.config/Claude/claude_desktop_config.json
+ */
+export function claudeDesktopConfigPath(home, platform = osPlatform()) {
+    if (platform === "darwin") {
+        return join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    if (platform === "win32") {
+        // gramatr-allow: C1 — Windows fallback for APPDATA when not present
+        const appData = process.env.APPDATA || join(home, "AppData", "Roaming");
+        return join(appData, "Claude", "claude_desktop_config.json");
+    }
+    return join(home, ".config", "Claude", "claude_desktop_config.json");
+}
 /** Resolve the bundled SessionEnd hook script source inside @gramatr/mcp. */
 export function resolveBundledSessionEndHookSource() {
     const here = fileURLToPath(import.meta.url);
@@ -224,9 +247,7 @@ export function mergeUserPromptSubmitHookIntoSettings(settings, home, removeLega
         }
     }
     // Add our entry. Preserve any non-gramatr UserPromptSubmit entries.
-    const ups = Array.isArray(hooks.UserPromptSubmit)
-        ? [...hooks.UserPromptSubmit]
-        : [];
+    const ups = Array.isArray(hooks.UserPromptSubmit) ? [...hooks.UserPromptSubmit] : [];
     const alreadyPresent = ups.some((e) => (e.hooks ?? []).some((c) => c.command === cmd));
     if (!alreadyPresent) {
         ups.push({
@@ -237,9 +258,7 @@ export function mergeUserPromptSubmitHookIntoSettings(settings, home, removeLega
     hooks.UserPromptSubmit = ups;
     // Add SessionEnd entry. Preserve any non-gramatr SessionEnd entries.
     const seCmd = buildSessionEndHookCommand(home);
-    const seEntries = Array.isArray(hooks.SessionEnd)
-        ? [...hooks.SessionEnd]
-        : [];
+    const seEntries = Array.isArray(hooks.SessionEnd) ? [...hooks.SessionEnd] : [];
     const seAlreadyPresent = seEntries.some((e) => (e.hooks ?? []).some((c) => c.command === seCmd));
     if (!seAlreadyPresent) {
         seEntries.push({
@@ -250,9 +269,7 @@ export function mergeUserPromptSubmitHookIntoSettings(settings, home, removeLega
     hooks.SessionEnd = seEntries;
     // Add SessionStart entry. Preserve any non-gramatr SessionStart entries (#2475).
     const ssCmd = buildSessionStartHookCommand(home);
-    const ssEntries = Array.isArray(hooks.SessionStart)
-        ? [...hooks.SessionStart]
-        : [];
+    const ssEntries = Array.isArray(hooks.SessionStart) ? [...hooks.SessionStart] : [];
     const ssAlreadyPresent = ssEntries.some((e) => (e.hooks ?? []).some((c) => c.command === ssCmd));
     if (!ssAlreadyPresent) {
         ssEntries.push({
@@ -263,9 +280,7 @@ export function mergeUserPromptSubmitHookIntoSettings(settings, home, removeLega
     hooks.SessionStart = ssEntries;
     // Add Stop entry. Preserve any non-gramatr Stop entries (#2476).
     const stopCmd = buildStopHookCommand(home);
-    const stopEntries = Array.isArray(hooks.Stop)
-        ? [...hooks.Stop]
-        : [];
+    const stopEntries = Array.isArray(hooks.Stop) ? [...hooks.Stop] : [];
     const stopAlreadyPresent = stopEntries.some((e) => (e.hooks ?? []).some((c) => c.command === stopCmd));
     if (!stopAlreadyPresent) {
         stopEntries.push({
@@ -353,11 +368,16 @@ export function upsertGramatrSection(existing, sectionBody) {
 export function stripGramatrSection(existing) {
     const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const re = new RegExp(`\\n*${escape(GRAMATR_MD_START)}[\\s\\S]*?${escape(GRAMATR_MD_END)}\\n*`, "m");
-    return existing.replace(re, "\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+    return (existing
+        .replace(re, "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trimEnd() + "\n");
 }
 function listMatching(dir, predicate) {
     try {
-        return readdirSync(dir).filter(predicate).map((n) => join(dir, n));
+        return readdirSync(dir)
+            .filter(predicate)
+            .map((n) => join(dir, n));
     }
     catch {
         return [];
@@ -401,6 +421,116 @@ function removeLegacyArtifacts(paths, dryRun) {
     }
     return { removed };
 }
+// ── legacy slash-command cleanup (#2490) ──────────────────────────────────
+/** Filenames in ~/.claude/commands/ known to be gramatr-flavored legacy. */
+const LEGACY_SLASH_COMMAND_FILENAMES = new Set([
+    "save-handoff.md",
+    "gramatr-restore.md",
+    "gramatr-compact.md",
+]);
+/**
+ * Heuristic: file content looks gramatr-flavored if it references retired
+ * daemon paths or the gramatr namespace.
+ */
+function isGramatrFlavoredSlashCommand(content) {
+    return (content.includes("~/.gramatr/.state/") ||
+        content.includes(".gramatr/.state/") ||
+        content.includes("~/.gramatr/bin/gramatr-hook") ||
+        content.includes(".gramatr/bin/gramatr-hook") ||
+        /\bgrāmatr\b/i.test(content) ||
+        /\bgramatr\b/i.test(content));
+}
+/**
+ * Scan ~/.claude/commands/*.md for legacy gramatr-flavored slash commands.
+ * Returns absolute paths of files that match.
+ *
+ * Match rules:
+ *   - Filename in LEGACY_SLASH_COMMAND_FILENAMES AND content gramatr-flavored.
+ *   - OR content references retired daemon paths (~/.gramatr/.state/, etc.).
+ *
+ * Non-gramatr slash commands are preserved.
+ */
+export function detectLegacySlashCommands(home) {
+    const dir = claudeCommandsDir(home);
+    let files;
+    try {
+        files = readdirSync(dir).filter((n) => n.endsWith(".md"));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of files) {
+        const path = join(dir, name);
+        let content = "";
+        try {
+            content = readFileSync(path, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const knownStale = LEGACY_SLASH_COMMAND_FILENAMES.has(name);
+        const refsRetiredPath = content.includes("~/.gramatr/.state/") ||
+            content.includes(".gramatr/.state/") ||
+            content.includes("~/.gramatr/bin/gramatr-hook") ||
+            content.includes(".gramatr/bin/gramatr-hook");
+        if (refsRetiredPath) {
+            out.push(path);
+            continue;
+        }
+        if (knownStale && isGramatrFlavoredSlashCommand(content)) {
+            out.push(path);
+        }
+    }
+    return out;
+}
+/** Remove the given slash-command files. Best-effort, returns removed paths. */
+export function cleanupLegacySlashCommands(home, dryRun = false) {
+    const matches = detectLegacySlashCommands(home);
+    if (dryRun)
+        return matches;
+    const removed = [];
+    for (const p of matches) {
+        try {
+            unlinkSync(p);
+            removed.push(p);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    return removed;
+}
+// ── client detection (#2472) ──────────────────────────────────────────────
+/**
+ * Detect which client this machine looks like:
+ *   - claude-code if ~/.claude/settings.json exists OR ~/.claude.json has mcpServers
+ *   - else claude-desktop if claude_desktop_config.json exists
+ *   - else claude-web
+ */
+export function detectClient(home, platform = osPlatform()) {
+    if (existsSync(claudeSettingsPath(home)))
+        return "claude-code";
+    const claudeJsonPath = join(home, ".claude.json");
+    if (existsSync(claudeJsonPath)) {
+        try {
+            const raw = readFileSync(claudeJsonPath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === "object" && parsed.mcpServers) {
+                return "claude-code";
+            }
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    // ~/.claude/ exists (even empty) → assume claude-code is being set up.
+    if (existsSync(join(home, ".claude")))
+        return "claude-code";
+    if (existsSync(claudeDesktopConfigPath(home, platform)))
+        return "claude-desktop";
+    return "claude-web";
+}
 // ── auth helpers ──────────────────────────────────────────────────────────
 export function hasValidToken(home) {
     const path = gramatrTokenPath(home);
@@ -418,17 +548,46 @@ export async function install(opts) {
     const log = opts.log ?? ((m) => process.stderr.write(`${m}\n`));
     const dryRun = !!opts.dryRun;
     const cleanLegacy = !!opts.cleanLegacy || !!opts.nonInteractive;
+    const platform = opts.platformOverride ?? osPlatform();
+    const client = opts.client ?? detectClient(opts.home, platform);
     const summary = {
+        client,
         hookScriptWritten: false,
         sessionEndScriptWritten: false,
         sessionStartScriptWritten: false,
         stopScriptWritten: false,
         settingsUpdated: false,
         claudeMdUpdated: false,
+        desktopConfigUpdated: false,
         legacyEntriesRemoved: 0,
         legacyFilesRemoved: [],
+        legacySlashCommandsRemoved: [],
         backups: [],
     };
+    // Dispatch to non-claude-code branches early.
+    if (client === "claude-web") {
+        summary.webInstructions = buildWebInstallInstructions(opts.mcpServerUrl);
+        log("[gramatr] claude-web detected — no local filesystem changes.");
+        log(summary.webInstructions);
+        return summary;
+    }
+    if (client === "claude-desktop") {
+        const cfgPath = opts.desktopConfigPathOverride ?? claudeDesktopConfigPath(opts.home, platform);
+        const updated = installClaudeDesktop({
+            configPath: cfgPath,
+            home: opts.home,
+            mcpServerUrl: opts.mcpServerUrl,
+            dryRun,
+            log,
+        });
+        summary.desktopConfigUpdated = updated.updated;
+        if (updated.backup)
+            summary.backups.push(updated.backup);
+        log(`[gramatr] claude-desktop ${dryRun ? "(dry-run) " : ""}config at ${cfgPath}`);
+        log("[gramatr] restart Claude Desktop after install to load the new MCP server.");
+        return summary;
+    }
+    // ─── claude-code path (legacy default — full hook + settings + CLAUDE.md) ──
     // 1. Hook script
     const hookSrc = opts.hookSourcePath ?? resolveBundledHookSource();
     const hookDst = gramatrHookScriptPath(opts.home);
@@ -571,28 +730,174 @@ export async function install(opts) {
             for (const p of res.removed)
                 log(`[gramatr] cleaned ${dryRun ? "(dry-run) " : ""}${p}`);
         }
+        // Also clean up legacy slash commands (#2490).
+        const removedCmds = cleanupLegacySlashCommands(opts.home, dryRun);
+        summary.legacySlashCommandsRemoved = removedCmds;
+        for (const p of removedCmds) {
+            log(`[gramatr] cleaned legacy slash command ${dryRun ? "(dry-run) " : ""}${p}`);
+        }
     }
     else {
         const legacy = detectLegacyArtifacts(opts.home);
         if (legacy.length > 0) {
             log(`[gramatr] note: detected ${legacy.length} legacy artifact${legacy.length === 1 ? "" : "s"}; rerun with --clean-legacy to remove`);
         }
+        const staleCmds = detectLegacySlashCommands(opts.home);
+        if (staleCmds.length > 0) {
+            log(`[gramatr] note: detected ${staleCmds.length} legacy slash command${staleCmds.length === 1 ? "" : "s"}; rerun with --clean-legacy to remove`);
+        }
     }
     return summary;
 }
+/**
+ * Build the claude-desktop mcpServers entry for gramatr. Uses HTTP transport
+ * since Desktop supports it and we get a free Bearer token from ~/.gramatr.json.
+ */
+export function buildDesktopMcpEntry(home, serverUrl = "https://api.gramatr.com/mcp") {
+    const token = readBearerToken(home);
+    const headers = {};
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    return {
+        type: "http",
+        url: serverUrl,
+        headers,
+    };
+}
+function readBearerToken(home) {
+    try {
+        const raw = readFileSync(gramatrTokenPath(home), "utf8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed.token === "string" && parsed.token.length > 0 ? parsed.token : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Merge gramatr entry into a claude-desktop config object. Returns the next
+ * object and whether a change was made. Idempotent.
+ */
+export function mergeDesktopConfig(current, entry) {
+    const servers = { ...(current.mcpServers ?? {}) };
+    const existing = servers.gramatr;
+    const same = existing && JSON.stringify(existing) === JSON.stringify(entry);
+    if (same)
+        return { next: current, changed: false };
+    servers.gramatr = entry;
+    return { next: { ...current, mcpServers: servers }, changed: true };
+}
+function installClaudeDesktop(opts) {
+    const entry = buildDesktopMcpEntry(opts.home, opts.mcpServerUrl);
+    const raw = readFileOr(opts.configPath, null);
+    const current = parseJsonOr(raw, {});
+    const { next, changed } = mergeDesktopConfig(current, entry);
+    if (!changed)
+        return { updated: false, backup: null };
+    const desired = JSON.stringify(next, null, 2) + "\n";
+    if (opts.dryRun)
+        return { updated: true, backup: null };
+    const backup = backupFile(opts.configPath);
+    atomicWriteFile(opts.configPath, desired, 0o600);
+    return { updated: true, backup };
+}
+/** Remove gramatr entry from claude-desktop config. */
+export function uninstallDesktopConfig(current) {
+    if (!current.mcpServers || !current.mcpServers.gramatr) {
+        return { next: current, changed: false };
+    }
+    const servers = { ...current.mcpServers };
+    delete servers.gramatr;
+    const next = { ...current };
+    if (Object.keys(servers).length > 0) {
+        next.mcpServers = servers;
+    }
+    else {
+        delete next.mcpServers;
+    }
+    return { next, changed: true };
+}
+// ── claude-web instructions (#2472) ───────────────────────────────────────
+/**
+ * Build the copy-paste instructions for claude-web. No filesystem writes.
+ * Combines connector steps with the canonical prompt suggestion block.
+ */
+export function buildWebInstallInstructions(serverUrl) {
+    const conn = buildConnectorInstructions({ serverUrl, target: "claude-web" });
+    const suggestion = buildPromptSuggestion("claude-web");
+    const lines = [];
+    lines.push("# gramatr — claude-web manual setup");
+    lines.push("");
+    lines.push("Claude Web (claude.ai) has no local install. Follow these steps:");
+    lines.push("");
+    for (let i = 0; i < conn.steps.length; i++) {
+        lines.push(`  ${i + 1}. ${conn.steps[i]}`);
+    }
+    lines.push("");
+    lines.push("Paste the following block into Settings > Profile > Custom Instructions:");
+    lines.push("");
+    lines.push("---");
+    lines.push(suggestion);
+    lines.push("---");
+    return lines.join("\n");
+}
 export async function uninstall(opts) {
     const log = opts.log ?? ((m) => process.stderr.write(`${m}\n`));
     const dryRun = !!opts.dryRun;
+    const platform = opts.platformOverride ?? osPlatform();
+    const client = opts.client ?? detectClient(opts.home, platform);
     const summary = {
+        client,
         hookEntryRemoved: false,
         claudeMdSectionRemoved: false,
         hookScriptRemoved: false,
         sessionEndScriptRemoved: false,
         sessionStartScriptRemoved: false,
         stopScriptRemoved: false,
+        desktopConfigUpdated: false,
+        legacySlashCommandsRemoved: [],
         tokenRemoved: false,
         backups: [],
     };
+    if (client === "claude-web") {
+        log("[gramatr] claude-web: no local state to remove. Disconnect the connector inside claude.ai.");
+        if (opts.purge) {
+            const tokPath = gramatrTokenPath(opts.home);
+            if (existsSync(tokPath)) {
+                if (!dryRun)
+                    unlinkSync(tokPath);
+                summary.tokenRemoved = true;
+            }
+        }
+        return summary;
+    }
+    if (client === "claude-desktop") {
+        const cfgPath = opts.desktopConfigPathOverride ?? claudeDesktopConfigPath(opts.home, platform);
+        const raw = readFileOr(cfgPath, null);
+        if (raw !== null) {
+            const current = parseJsonOr(raw, {});
+            const { next, changed } = uninstallDesktopConfig(current);
+            if (changed) {
+                if (!dryRun) {
+                    const bak = backupFile(cfgPath);
+                    if (bak)
+                        summary.backups.push(bak);
+                    atomicWriteFile(cfgPath, JSON.stringify(next, null, 2) + "\n", 0o600);
+                }
+                summary.desktopConfigUpdated = true;
+                log(`[gramatr] claude-desktop ${dryRun ? "(dry-run) " : ""}removed gramatr mcpServers entry`);
+            }
+        }
+        if (opts.purge) {
+            const tokPath = gramatrTokenPath(opts.home);
+            if (existsSync(tokPath)) {
+                if (!dryRun)
+                    unlinkSync(tokPath);
+                summary.tokenRemoved = true;
+            }
+        }
+        return summary;
+    }
     // 1. settings.json
     const settingsPath = claudeSettingsPath(opts.home);
     const settingsRaw = readFileOr(settingsPath, null);
@@ -675,6 +980,12 @@ export async function uninstall(opts) {
         summary.stopScriptRemoved = true;
         log(`[gramatr] Stop hook script ${dryRun ? "(dry-run) " : ""}→ removed ${stopHookDst}`);
     }
+    // 3e. Legacy slash commands (always cleaned during uninstall; #2490).
+    const removedCmds = cleanupLegacySlashCommands(opts.home, dryRun);
+    summary.legacySlashCommandsRemoved = removedCmds;
+    for (const p of removedCmds) {
+        log(`[gramatr] removed legacy slash command ${dryRun ? "(dry-run) " : ""}${p}`);
+    }
     // 4. token (only on --purge)
     if (opts.purge) {
         const tokPath = gramatrTokenPath(opts.home);
@@ -725,6 +1036,17 @@ function resolveHome() {
     // gramatr-allow: C1 — CLI entry point, reads HOME for config path
     return process.env.HOME || process.env.USERPROFILE || "";
 }
+function parseClientFlag(argv) {
+    for (const a of argv) {
+        if (a.startsWith("--client=")) {
+            const v = a.slice("--client=".length);
+            if (v === "claude-code" || v === "claude-desktop" || v === "claude-web")
+                return v;
+            process.stderr.write(`[gramatr] unknown --client value: ${v} (expected claude-code|claude-desktop|claude-web)\n`);
+        }
+    }
+    return undefined;
+}
 export async function runInstallCli(argv) {
     const home = resolveHome();
     if (!home) {
@@ -733,6 +1055,7 @@ export async function runInstallCli(argv) {
     }
     const opts = {
         home,
+        client: parseClientFlag(argv),
         cleanLegacy: argv.includes("--clean-legacy"),
         nonInteractive: argv.includes("--non-interactive") || argv.includes("--yes") || argv.includes("-y"),
         dryRun: argv.includes("--dry-run"),
@@ -753,6 +1076,19 @@ export async function runInstallCli(argv) {
     }
     const summary = await install(opts);
     process.stderr.write("\n[gramatr] install summary:\n");
+    process.stderr.write(`  client: ${summary.client}\n`);
+    if (summary.client === "claude-web") {
+        // Instructions already printed via log().
+        return 0;
+    }
+    if (summary.client === "claude-desktop") {
+        process.stderr.write(`  claude-desktop config: ${summary.desktopConfigUpdated ? "updated" : "up-to-date"}\n`);
+        if (summary.backups.length > 0) {
+            process.stderr.write(`  backups: ${summary.backups.length}\n`);
+        }
+        process.stderr.write("\n  Restart Claude Desktop to activate.\n");
+        return 0;
+    }
     process.stderr.write(`  hook script: ${summary.hookScriptWritten ? "written" : "up-to-date"}\n`);
     process.stderr.write(`  SessionEnd hook script: ${summary.sessionEndScriptWritten ? "written" : "up-to-date"}\n`);
     process.stderr.write(`  SessionStart hook script: ${summary.sessionStartScriptWritten ? "written" : "up-to-date"}\n`);
@@ -765,6 +1101,9 @@ export async function runInstallCli(argv) {
     if (summary.legacyFilesRemoved.length > 0) {
         process.stderr.write(`  legacy files removed: ${summary.legacyFilesRemoved.length}\n`);
     }
+    if (summary.legacySlashCommandsRemoved.length > 0) {
+        process.stderr.write(`  legacy slash commands removed: ${summary.legacySlashCommandsRemoved.length}\n`);
+    }
     if (summary.backups.length > 0) {
         process.stderr.write(`  backups: ${summary.backups.length}\n`);
         for (const b of summary.backups)
@@ -781,16 +1120,33 @@ export async function runUninstallCli(argv) {
     }
     const summary = await uninstall({
         home,
+        client: parseClientFlag(argv),
         purge: argv.includes("--purge"),
         dryRun: argv.includes("--dry-run"),
     });
     process.stderr.write("\n[gramatr] uninstall summary:\n");
+    process.stderr.write(`  client: ${summary.client}\n`);
+    if (summary.client === "claude-web") {
+        process.stderr.write("  (no local state — disconnect the connector inside claude.ai)\n");
+        if (summary.tokenRemoved)
+            process.stderr.write(`  token: removed\n`);
+        return 0;
+    }
+    if (summary.client === "claude-desktop") {
+        process.stderr.write(`  claude-desktop config: ${summary.desktopConfigUpdated ? "updated" : "not present"}\n`);
+        if (summary.tokenRemoved)
+            process.stderr.write(`  token: removed\n`);
+        return 0;
+    }
     process.stderr.write(`  hook entry: ${summary.hookEntryRemoved ? "removed" : "not present"}\n`);
     process.stderr.write(`  CLAUDE.md section: ${summary.claudeMdSectionRemoved ? "removed" : "not present"}\n`);
     process.stderr.write(`  hook script: ${summary.hookScriptRemoved ? "removed" : "not present"}\n`);
     process.stderr.write(`  SessionEnd hook script: ${summary.sessionEndScriptRemoved ? "removed" : "not present"}\n`);
     process.stderr.write(`  SessionStart hook script: ${summary.sessionStartScriptRemoved ? "removed" : "not present"}\n`);
     process.stderr.write(`  Stop hook script: ${summary.stopScriptRemoved ? "removed" : "not present"}\n`);
+    if (summary.legacySlashCommandsRemoved.length > 0) {
+        process.stderr.write(`  legacy slash commands removed: ${summary.legacySlashCommandsRemoved.length}\n`);
+    }
     if (summary.tokenRemoved)
         process.stderr.write(`  token: removed\n`);
     if (summary.backups.length > 0) {