@askthew/mcp-plugin 0.4.7 → 0.4.9

package/README.md

@@ -43,6 +43,8 @@ npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp install
 
 Free install is local-first: it generates `~/.askthew/identity.json`, writes MCP config and agent instructions immediately, and never requires an email code before local capture works. The email is an unverified claim used for upgrade onboarding only; data is keyed by the generated install ID, not email alone.
 
+Installer bookkeeping is separate from local capture data: install receipts live under `~/.local/state/askthew/install-receipts.json` by default, or `$XDG_STATE_HOME/askthew/install-receipts.json` when `XDG_STATE_HOME` is set. This lets `uninstall` remove host config and repo instruction blocks even after `~/.askthew` has been wiped.
+
 Telemetry is aggregate-only and opt-out. Ask The W does not receive code, file contents, file paths, file names, command text, summaries, or decision content in free mode telemetry. Aggregate summaries are signed by the local install identity and stored under the generated install ID. Opt out with `--no-telemetry`, `ASKTHEW_TELEMETRY=off`, or `askthew-mcp telemetry opt-out`.
 
 ## Refresh vs Uninstall

package/dist/cli.js

@@ -4,7 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { createAskTheWMcpServer } from "./index.js";
+import { createAskTheWMcpServer, runInitializeHandshake } from "./index.js";
 import { askTheWDataDir, ensureAskTheWDataDir, identityPath } from "./lib/paths.js";
 import { loadCliCredentials } from "./lib/free-tier-policy.js";
 import { describeFreeIdentity, tryRegisterFreeInstall } from "./lib/free-install-registration.js";
@@ -13,17 +13,21 @@ import { LocalStore } from "./lib/local-store.js";
 import { buildTelemetryPayload } from "./lib/telemetry.js";
 import { syncDryRun, uploadLocalStore } from "./lib/upgrade-sync.js";
 import { installPreCommitHook, localScopeKey, preCommitDecisionGap, stagedFiles, writeWeeklyDigest, } from "./lib/cli-actions.js";
-import { createHostConfigSnippet, formatInstallCommand, installBehaviorInstructions, installHostConfig, sendInstallHeartbeat, uninstallBehaviorInstructions, uninstallHostConfig, } from "./install.js";
+import { createHostConfigSnippet, defaultServerNameForTier, findInstallReceipts, formatInstallCommand, installBehaviorInstructions, installHostConfig, packageVersion, removeInstallReceipts, sendInstallHeartbeat, uninstallBehaviorInstructions, uninstallHostConfig, upgradePinnedHostConfig, writeInstallReceipt, } from "./install.js";
 function usage() {
     return [
         "Ask The W Coding Agent Connector",
         "",
         "Usage:",
-        "  askthew-mcp",
-        "  askthew-mcp install --host <claude_code|codex|cursor> --token <install-token> --api-url <url> --server-name <name> [--client-id <id>] [--client-label <label>] [--dry-run] [--no-agent-instructions]",
-        "  askthew-mcp install --host <claude_code|codex|cursor> --free [--email <email>] [--api-url <url>] [--server-name <name>]",
-        "  askthew-mcp refresh --host <claude_code|codex|cursor> [--free] [--token <install-token>] [--api-url <url>] [--server-name <name>] [--dry-run]",
+        "  askthew-mcp [stdio MCP server when stdin is piped]",
+        "  askthew-mcp --version",
+        "  askthew-mcp doctor [--server-entrypoint <path>]",
+        "  askthew-mcp install --host <claude_code|codex|cursor> --token <install-token> --api-url <url> [--server-name <name>] [--client-id <id>] [--client-label <label>] [--server-entrypoint <path>] [--dry-run] [--no-agent-instructions]",
+        "  askthew-mcp install --host <claude_code|codex|cursor> --free [--email <email>] [--api-url <url>] [--server-name <name>] [--server-entrypoint <path>] [--dry-run]",
+        "  askthew-mcp refresh --host <claude_code|codex|cursor> [--free] [--token <install-token>] [--api-url <url>] [--server-name <name>] [--server-entrypoint <path>] [--dry-run]",
         "  askthew-mcp uninstall --host <claude_code|codex|cursor> [--server-name <name>] [--dry-run] [--keep-local-data] [--keep-auth] [--keep-agent-instructions]",
+        "  askthew-mcp upgrade --host <claude_code|codex|cursor> [--server-name <name>] [--version <version>] [--dry-run]",
+        "  askthew-mcp upgrade --browser",
         "  askthew-mcp identify --email <email> [--no-telemetry]",
         "  askthew-mcp identity status",
         "  askthew-mcp auth login --email <email> [--no-telemetry]",
@@ -43,10 +47,12 @@ function parseInstallArgs(argv) {
     let token = normalizeInstallToken(process.env.ASKTHEW_INSTALL_TOKEN) || "";
     let apiUrl = process.env.ASKTHEW_API_URL?.trim() || "";
     let serverName = process.env.ASKTHEW_SERVER_NAME?.trim() || "";
+    let serverNameExplicit = Boolean(serverName);
     let dryRun = false;
     let installAgentInstructions = true;
     let free = false;
     let email = process.env.ASKTHEW_EMAIL?.trim() || "";
+    let serverEntrypoint = process.env.ASKTHEW_SERVER_ENTRYPOINT?.trim() || "";
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
         if (argument === "--dry-run") {
@@ -95,6 +101,7 @@ function parseInstallArgs(argv) {
         }
         if (argument === "--server-name") {
             serverName = next;
+            serverNameExplicit = true;
             index += 1;
             continue;
         }
@@ -103,6 +110,11 @@ function parseInstallArgs(argv) {
             index += 1;
             continue;
         }
+        if (argument === "--server-entrypoint") {
+            serverEntrypoint = next;
+            index += 1;
+            continue;
+        }
         throw new Error(`Unknown argument: ${argument}`);
     }
     if (!hostType) {
@@ -115,7 +127,7 @@ function parseInstallArgs(argv) {
         apiUrl = "https://app.askthew.com";
     }
     if (!serverName) {
-        serverName = "askthew";
+        serverName = defaultServerNameForTier(free);
     }
     return {
         hostType,
@@ -124,25 +136,17 @@ function parseInstallArgs(argv) {
         token,
         apiUrl,
         serverName,
+        serverNameExplicit,
         dryRun,
         installAgentInstructions,
         free,
         email: email || undefined,
+        serverEntrypoint: serverEntrypoint ? path.resolve(serverEntrypoint) : undefined,
     };
 }
 function normalizeInstallToken(token) {
     return String(token ?? "").trim().replace(/^['"]/, "").replace(/['"]$/, "");
 }
-function packageVersion() {
-    try {
-        const packagePath = fileURLToPath(new URL("../package.json", import.meta.url));
-        const parsed = JSON.parse(fs.readFileSync(packagePath, "utf8"));
-        return typeof parsed.version === "string" ? parsed.version : "unknown";
-    }
-    catch {
-        return "unknown";
-    }
-}
 function detectLoginEmail() {
     for (const value of [
         process.env.ASKTHEW_EMAIL,
@@ -182,6 +186,14 @@ async function main() {
         console.log(usage());
         return;
     }
+    if (command === "--version" || command === "-v" || command === "version") {
+        console.log(packageVersion());
+        return;
+    }
+    if (command === "doctor") {
+        await runDoctorCommand(argv);
+        return;
+    }
     if (command === "print-config") {
         const options = parseInstallArgs(argv);
         const snippet = createHostConfigSnippet(options);
@@ -189,6 +201,7 @@ async function main() {
         return;
     }
     if (command === "install") {
+        console.error(`Downloading @askthew/mcp-plugin@${packageVersion()}...`);
         const options = parseInstallArgs(argv);
         let freeIdentity = null;
         if (options.free && !options.dryRun) {
@@ -204,13 +217,30 @@ async function main() {
                 dryRun: options.dryRun,
             })
             : null;
+        const receipt = result.wroteFile
+            ? writeInstallReceipt({
+                hostType: options.hostType,
+                serverName: options.serverName,
+                settingsPath: result.settingsPath,
+                cwd: process.cwd(),
+                instructionPaths: instructions?.paths ?? [],
+                serverEntrypoint: options.serverEntrypoint,
+                packageVersion: packageVersion(),
+            })
+            : null;
         const heartbeatSent = result.wroteFile && !options.free
             ? await sendInstallHeartbeat(options).catch(() => false)
             : false;
         console.log(result.wroteFile ? "Ask The W plugin install complete." : "Ask The W plugin dry run complete.");
         console.log(`Settings path: ${result.settingsPath}`);
         if (instructions) {
-            console.log(`Agent instructions: ${instructions.paths?.join(", ") ?? instructions.path}`);
+            console.log(`${options.dryRun ? "Would update agent instructions" : "Agent instructions"}: ${instructions.paths?.join(", ") ?? instructions.path}`);
+        }
+        if (receipt) {
+            console.log(`Install receipt: ${receipt.hostType}/${receipt.serverName} at ${receipt.cwd}`);
+        }
+        else if (options.dryRun) {
+            console.log(`Would write install receipt: ${options.hostType}/${options.serverName} at ${process.cwd()}`);
         }
         console.log(`Install command: ${formatInstallCommand(options)}`);
         if (result.wroteFile) {
@@ -236,6 +266,7 @@ async function main() {
         console.log(`Next step: ${result.nextStep}`);
         if (!result.wroteFile) {
             console.log("");
+            console.log("Planned host config:");
             console.log(result.json);
         }
         return;
@@ -285,22 +316,24 @@ async function main() {
         return;
     }
     if (command === "upgrade") {
-        console.log("Open https://askthew.com/plugin to upgrade, then run `askthew-mcp upgrade --finalize`.");
-        if (argv.includes("--finalize")) {
-            console.log("Finalize will rewrite host config after a paid workspace token is available in the web app.");
-        }
+        await runUpgradeCommand(argv);
         return;
     }
     if (command) {
         throw new Error(`Unknown command "${command}".\n\n${usage()}`);
     }
+    if (process.stdin.isTTY) {
+        console.log(usage());
+        return;
+    }
     const server = createAskTheWMcpServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
 async function runUninstallCommand(argv) {
     let hostType;
-    let serverName = process.env.ASKTHEW_SERVER_NAME?.trim() || "askthew";
+    let serverName = process.env.ASKTHEW_SERVER_NAME?.trim() || undefined;
+    let serverNameExplicit = Boolean(serverName);
     let dryRun = false;
     let keepLocalData = false;
     let keepAuth = false;
@@ -336,6 +369,7 @@ async function runUninstallCommand(argv) {
         }
         if (argument === "--server-name") {
             serverName = next;
+            serverNameExplicit = true;
             index += 1;
             continue;
         }
@@ -344,14 +378,22 @@ async function runUninstallCommand(argv) {
     if (!hostType) {
         throw new Error("Usage: askthew-mcp uninstall --host <claude_code|codex|cursor> [--server-name <name>]");
     }
-    const config = uninstallHostConfig({ hostType, serverName, dryRun });
-    const instructions = keepAgentInstructions
-        ? null
-        : uninstallBehaviorInstructions({ hostType, dryRun });
+    const receipts = findInstallReceipts({ hostType, serverName });
+    const config = uninstallHostConfig({
+        hostType,
+        serverName: serverNameExplicit ? serverName : undefined,
+        dryRun,
+        cwds: Array.from(new Set([process.cwd(), ...receipts.map((receipt) => receipt.cwd)])),
+    });
+    const instructionCwds = Array.from(new Set([process.cwd(), ...receipts.map((receipt) => receipt.cwd)]));
+    const instructionPaths = keepAgentInstructions
+        ? []
+        : instructionCwds.flatMap((cwd) => uninstallBehaviorInstructions({ hostType, dryRun, cwd }).paths);
     const dataDir = askTheWDataDir();
     const hadLocalData = fs.existsSync(dataDir);
     const authFile = identityPath();
     const hadAuth = fs.existsSync(authFile);
+    const removedReceipts = dryRun ? receipts.length : removeInstallReceipts({ hostType, serverName });
     if (!keepLocalData && !dryRun) {
         fs.rmSync(dataDir, { recursive: true, force: true });
     }
@@ -366,11 +408,14 @@ async function runUninstallCommand(argv) {
         : config.foundConfigFile
             ? `No MCP server "${config.removedServerName}" found in host config.`
             : "No host config file found.");
-    if (instructions) {
-        console.log(instructions.paths.length > 0
-            ? `Agent instructions ${dryRun ? "would be removed from" : "removed from"}: ${instructions.paths.join(", ")}`
+    if (!keepAgentInstructions) {
+        console.log(instructionPaths.length > 0
+            ? `Agent instructions ${dryRun ? "would be removed from" : "removed from"}: ${Array.from(new Set(instructionPaths)).join(", ")}`
             : "No Ask The W agent instruction blocks found.");
     }
+    console.log(removedReceipts > 0
+        ? `${dryRun ? "Would remove" : "Removed"} ${removedReceipts} install receipt${removedReceipts === 1 ? "" : "s"}.`
+        : "No install receipts found.");
     console.log(keepLocalData
         ? "Local data kept."
         : hadLocalData
@@ -392,6 +437,9 @@ async function runRefreshCommand(argv) {
     const options = {
         ...parsed,
         free: !isPaidRefresh,
+        serverName: parsed.serverNameExplicit
+            ? parsed.serverName
+            : defaultServerNameForTier(!isPaidRefresh),
     };
     const existingIdentity = loadLocalIdentity();
     let freeIdentity = existingIdentity;
@@ -417,6 +465,17 @@ async function runRefreshCommand(argv) {
             dryRun: options.dryRun,
         })
         : null;
+    const receipt = install.wroteFile
+        ? writeInstallReceipt({
+            hostType: options.hostType,
+            serverName: options.serverName,
+            settingsPath: install.settingsPath,
+            cwd: process.cwd(),
+            instructionPaths: installedInstructions?.paths ?? [],
+            serverEntrypoint: options.serverEntrypoint,
+            packageVersion: packageVersion(),
+        })
+        : null;
     if (options.free && freeIdentity && !options.dryRun) {
         await tryRegisterFreeInstall({
             identity: freeIdentity,
@@ -436,6 +495,9 @@ async function runRefreshCommand(argv) {
     if (installedInstructions) {
         console.log(`Installed instructions: ${installedInstructions.paths.join(", ") || installedInstructions.path}`);
     }
+    if (receipt) {
+        console.log(`Install receipt: ${receipt.hostType}/${receipt.serverName} at ${receipt.cwd}`);
+    }
     if (options.free) {
         console.log(freeIdentity
             ? `Local identity preserved: ${freeIdentity.installId}`
@@ -456,6 +518,98 @@ async function runRefreshCommand(argv) {
         console.log(install.json);
     }
 }
+async function runDoctorCommand(argv) {
+    const serverEntrypoint = argValue(argv, "--server-entrypoint")?.trim();
+    const result = await runInitializeHandshake({
+        entrypoint: serverEntrypoint ? path.resolve(serverEntrypoint) : undefined,
+    });
+    const expectedVersion = packageVersion();
+    if (result.serverInfoVersion !== expectedVersion) {
+        throw new Error(`MCP initialize version mismatch: package.json=${expectedVersion} serverInfo.version=${result.serverInfoVersion ?? "missing"}`);
+    }
+    console.log("Ask The W MCP doctor passed.");
+    console.log(`Package version: ${expectedVersion}`);
+    console.log(`serverInfo.version: ${result.serverInfoVersion}`);
+}
+async function runUpgradeCommand(argv) {
+    if (argv.includes("--browser")) {
+        console.log("Open https://askthew.com/plugin to manage workspace upgrades.");
+        return;
+    }
+    let hostType = process.env.ASKTHEW_HOST_TYPE?.trim();
+    if (hostType !== "claude_code" && hostType !== "codex" && hostType !== "cursor") {
+        hostType = undefined;
+    }
+    let serverName = process.env.ASKTHEW_SERVER_NAME?.trim() || undefined;
+    let serverNameExplicit = Boolean(serverName);
+    let version = process.env.ASKTHEW_PIN?.trim() || packageVersion();
+    let dryRun = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        const next = argv[index + 1];
+        if (!next)
+            throw new Error(`Missing value for ${argument}.`);
+        if (argument === "--host") {
+            if (next !== "claude_code" && next !== "codex" && next !== "cursor") {
+                throw new Error(`Unsupported host "${next}". Expected claude_code, codex, or cursor.`);
+            }
+            hostType = next;
+            index += 1;
+            continue;
+        }
+        if (argument === "--server-name") {
+            serverName = next;
+            serverNameExplicit = true;
+            index += 1;
+            continue;
+        }
+        if (argument === "--version" || argument === "--pin") {
+            version = next;
+            index += 1;
+            continue;
+        }
+        throw new Error(`Unknown argument: ${argument}`);
+    }
+    if (!hostType) {
+        throw new Error("Usage: askthew-mcp upgrade --host <claude_code|codex|cursor> [--server-name <name>] [--version <version>] [--dry-run]");
+    }
+    const packageSpec = version.startsWith("@askthew/mcp-plugin@")
+        ? version
+        : `@askthew/mcp-plugin@${version}`;
+    if (!dryRun) {
+        const handshake = await runInitializeHandshake();
+        if (handshake.serverInfoVersion !== packageVersion()) {
+            throw new Error(`Refusing to upgrade pinned host config: MCP initialize returned ${handshake.serverInfoVersion ?? "missing"} but package.json is ${packageVersion()}.`);
+        }
+    }
+    const receipts = findInstallReceipts({
+        hostType,
+        serverName: serverNameExplicit ? serverName : undefined,
+    });
+    const result = upgradePinnedHostConfig({
+        hostType,
+        serverName: serverNameExplicit ? serverName : undefined,
+        packageSpec,
+        dryRun,
+        cwds: Array.from(new Set([process.cwd(), ...receipts.map((receipt) => receipt.cwd)])),
+    });
+    console.log(dryRun ? "Ask The W plugin upgrade dry run complete." : "Ask The W plugin upgrade complete.");
+    console.log(`Settings path: ${result.settingsPath}`);
+    console.log(`Pinned package: ${result.packageSpec}`);
+    console.log(result.upgradedServer
+        ? `${dryRun ? "Would update" : "Updated"} MCP server pin${result.upgradedServerNames.length ? `: ${result.upgradedServerNames.join(", ")}` : "."}`
+        : result.foundConfigFile
+            ? "No Ask The W MCP server pins needed an update."
+            : "No host config file found.");
+    if (dryRun && result.json) {
+        console.log("");
+        console.log(result.json);
+    }
+}
 function argValue(argv, name) {
     const index = argv.indexOf(name);
     return index >= 0 ? argv[index + 1] : undefined;

package/dist/index.d.ts

@@ -158,4 +158,11 @@ export interface AskTheWMcpServerOptions {
 }
 export declare function normalizeInstallTokenInput(token: string | undefined): string;
 export declare function createAskTheWMcpServer(options?: AskTheWMcpServerOptions): McpServer;
+export declare function runInitializeHandshake(input?: {
+    entrypoint?: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+}): Promise<{
+    serverInfoVersion?: string;
+}>;
 export {};