@askthew/mcp-plugin 0.4.4 → 0.4.5

package/README.md

@@ -45,6 +45,24 @@ Free install is local-first: it generates `~/.askthew/identity.json`, writes MCP
 
 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
+
+Use `refresh` when you want the latest installed MCP config and instruction blocks without touching local identity or local data:
+
+```bash
+npx -y --prefer-online @askthew/mcp-plugin@latest refresh --host claude_code
+```
+
+`refresh` preserves `~/.askthew/identity.json` and `~/.askthew/store.sqlite`, reuses any existing email claim silently, rewrites the host MCP config, and rewrites the marked Ask The W blocks in `CLAUDE.md` and `AGENTS.md`. This is the recommended QA update path after a plugin publish.
+
+Use `uninstall` when you want to remove the plugin from a host:
+
+```bash
+npx -y @askthew/mcp-plugin@latest uninstall --host claude_code --keep-local-data --keep-auth
+```
+
+Without `--keep-local-data`, uninstall removes `~/.askthew`; without `--keep-auth`, it removes the local install identity. Uninstall does not clear npm's cache.
+
 ## Workspace Install
 
 Create a workspace token in Ask The W at `/decisions/settings/connectors`, then run the installer from your coding agent or terminal. Treat the token like a password; anyone with it can write compact source signals into that workspace.

package/dist/cli.js

@@ -22,6 +22,7 @@ function 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 uninstall --host <claude_code|codex|cursor> [--server-name <name>] [--dry-run] [--keep-local-data] [--keep-auth] [--keep-agent-instructions]",
         "  askthew-mcp identify --email <email> [--no-telemetry]",
         "  askthew-mcp identity status",
@@ -132,6 +133,16 @@ function parseInstallArgs(argv) {
 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,
@@ -229,6 +240,10 @@ async function main() {
         }
         return;
     }
+    if (command === "refresh") {
+        await runRefreshCommand(argv);
+        return;
+    }
     if (command === "identify") {
         await runIdentifyCommand(argv);
         return;
@@ -270,7 +285,7 @@ async function main() {
         return;
     }
     if (command === "upgrade") {
-        console.log("Open https://askthew.com/mcp to upgrade, then run `askthew-mcp upgrade --finalize`.");
+        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.");
         }
@@ -353,6 +368,76 @@ async function runUninstallCommand(argv) {
         console.log(config.json);
     }
 }
+async function runRefreshCommand(argv) {
+    const parsed = parseInstallArgs(["--free", ...argv]);
+    const isPaidRefresh = Boolean(parsed.token && !argv.includes("--free"));
+    const options = {
+        ...parsed,
+        free: !isPaidRefresh,
+    };
+    const existingIdentity = loadLocalIdentity();
+    let freeIdentity = existingIdentity;
+    if (options.free && !options.dryRun && !freeIdentity) {
+        freeIdentity = ensureLocalIdentity({
+            emailClaim: options.email,
+            apiUrl: options.apiUrl,
+        });
+    }
+    const uninstall = uninstallHostConfig({
+        hostType: options.hostType,
+        serverName: options.serverName,
+        dryRun: options.dryRun,
+    });
+    const removedInstructions = uninstallBehaviorInstructions({
+        hostType: options.hostType,
+        dryRun: options.dryRun,
+    });
+    const install = installHostConfig(options);
+    const installedInstructions = options.installAgentInstructions
+        ? installBehaviorInstructions({
+            hostType: options.hostType,
+            dryRun: options.dryRun,
+        })
+        : null;
+    if (options.free && freeIdentity && !options.dryRun) {
+        await tryRegisterFreeInstall({
+            identity: freeIdentity,
+            deviceLabel: options.clientLabel ?? `${options.hostType} free refresh`,
+            repo: {
+                repoName: process.env.ASKTHEW_REPO_NAME,
+                repoRoot: process.env.ASKTHEW_REPO_ROOT,
+                hostType: options.hostType,
+            },
+            options: { apiUrl: options.apiUrl },
+        });
+    }
+    console.log(options.dryRun ? "Ask The W plugin refresh dry run complete." : "Ask The W plugin refresh complete.");
+    console.log(`Plugin package version: ${packageVersion()}`);
+    console.log(`Settings path: ${install.settingsPath}`);
+    console.log(`Removed instructions: ${removedInstructions.paths.join(", ") || "none"}`);
+    if (installedInstructions) {
+        console.log(`Installed instructions: ${installedInstructions.paths.join(", ") || installedInstructions.path}`);
+    }
+    if (options.free) {
+        console.log(freeIdentity
+            ? `Local identity preserved: ${freeIdentity.installId}`
+            : "Local identity would be created on a non-dry-run refresh.");
+        console.log("Local data preserved: ~/.askthew/store.sqlite");
+    }
+    else {
+        const heartbeatSent = install.wroteFile
+            ? await sendInstallHeartbeat(options).catch(() => false)
+            : false;
+        console.log(heartbeatSent ? "Paid workspace heartbeat sent." : "Paid workspace heartbeat not sent yet.");
+    }
+    console.log(`Next step: ${install.nextStep}`);
+    if (options.dryRun) {
+        console.log("");
+        console.log(uninstall.json);
+        console.log("");
+        console.log(install.json);
+    }
+}
 function argValue(argv, name) {
     const index = argv.indexOf(name);
     return index >= 0 ? argv[index + 1] : undefined;

package/dist/cli.test.js

@@ -138,6 +138,57 @@ test("free install ignores stale legacy credentials and writes local identity",
         fs.rmSync(fixture.root, { recursive: true, force: true });
     }
 });
+test("refresh rewrites host config and instructions while preserving local identity and data", () => {
+    const fixture = makeFixture();
+    try {
+        const install = runCli({
+            args: ["install", "--host", "claude_code", "--free", "--email", "founder@example.com", "--api-url", "http://127.0.0.1:9"],
+            cwd: fixture.project,
+            home: fixture.home,
+            dataDir: fixture.dataDir,
+        });
+        assert.equal(install.status, 0, install.stderr);
+        const beforeIdentity = JSON.parse(fs.readFileSync(path.join(fixture.dataDir, "identity.json"), "utf8"));
+        fs.writeFileSync(path.join(fixture.dataDir, "store.sqlite"), "keep me", "utf8");
+        const refresh = runCli({
+            args: ["refresh", "--host", "claude_code", "--api-url", "http://127.0.0.1:9"],
+            cwd: fixture.project,
+            home: fixture.home,
+            dataDir: fixture.dataDir,
+        });
+        assert.equal(refresh.status, 0, refresh.stderr);
+        assert.match(refresh.stdout, /plugin refresh complete/);
+        assert.match(refresh.stdout, /Local identity preserved/);
+        assert.match(refresh.stdout, /Plugin package version:/);
+        const afterIdentity = JSON.parse(fs.readFileSync(path.join(fixture.dataDir, "identity.json"), "utf8"));
+        assert.equal(afterIdentity.installId, beforeIdentity.installId);
+        assert.equal(afterIdentity.emailClaim, "founder@example.com");
+        assert.equal(fs.readFileSync(path.join(fixture.dataDir, "store.sqlite"), "utf8"), "keep me");
+        assert.match(fs.readFileSync(path.join(fixture.project, "CLAUDE.md"), "utf8"), /ASKTHEW_PLUGIN_INSTRUCTIONS_START/);
+        assert.match(fs.readFileSync(path.join(fixture.project, "AGENTS.md"), "utf8"), /ASKTHEW_PLUGIN_INSTRUCTIONS_START/);
+    }
+    finally {
+        fs.rmSync(fixture.root, { recursive: true, force: true });
+    }
+});
+test("refresh dry-run does not create a local identity", () => {
+    const fixture = makeFixture();
+    try {
+        const refresh = runCli({
+            args: ["refresh", "--host", "codex", "--dry-run"],
+            cwd: fixture.project,
+            home: fixture.home,
+            dataDir: fixture.dataDir,
+        });
+        assert.equal(refresh.status, 0, refresh.stderr);
+        assert.match(refresh.stdout, /refresh dry run complete/);
+        assert.equal(fs.existsSync(path.join(fixture.dataDir, "identity.json")), false);
+        assert.equal(fs.existsSync(path.join(fixture.home, ".codex", "config.toml")), false);
+    }
+    finally {
+        fs.rmSync(fixture.root, { recursive: true, force: true });
+    }
+});
 test("auth status reports missing local identity without pending-code guidance", () => {
     const fixture = makeFixture();
     try {

package/dist/index.js

@@ -1278,7 +1278,7 @@ export function createAskTheWMcpServer(options = {}) {
                 extra: {
                     tool: "review_session",
                     limit: 3,
-                    upgradeUrl: "https://askthew.com/mcp?utm_source=mcp-plugin&utm_medium=tool-nudge&utm_campaign=mcp-free&tool=review_session",
+                    upgradeUrl: "https://askthew.com/plugin?utm_source=mcp-plugin&utm_medium=tool-nudge&utm_campaign=mcp-free&tool=review_session",
                     cta: "Upgrade to review more than three sessions in the workspace dashboard.",
                 },
             });

package/dist/index.test.js

@@ -743,7 +743,7 @@ test("free decisions, recap, coach, and promote return human-readable compact ou
             assert.equal(response.ok, false);
             assert.equal(response.code, "free_tier_paid_feature");
             assert.equal(response.tool, "coach");
-            assert.match(response.upgradeUrl, /askthew\.com\/mcp/);
+            assert.match(response.upgradeUrl, /askthew\.com\/plugin/);
         }
     });
 });
@@ -910,7 +910,7 @@ test("free review_session markdown is capped and json is cursor-paginated with a
         assert.equal(capped.ok, false);
         assert.equal(capped.code, "free_tier_limit");
         assert.equal(capped.limit, 3);
-        assert.match(capped.upgradeUrl, /askthew\.com\/mcp/);
+        assert.match(capped.upgradeUrl, /askthew\.com\/plugin/);
     });
 });
 test("paid tools return canonical paywall envelope before transport in free mode", async () => {
@@ -943,7 +943,7 @@ test("paid tools return canonical paywall envelope before transport in free mode
             assert.equal(response.ok, false, toolName);
             assert.equal(response.code, "free_tier_paid_feature", toolName);
             assert.equal(response.tool, toolName, toolName);
-            assert.match(response.upgradeUrl, /askthew\.com\/mcp/, toolName);
+            assert.match(response.upgradeUrl, /askthew\.com\/plugin/, toolName);
             assert.equal(response.supportEmail, "support@askthew.com", toolName);
         }
     });

package/dist/lib/upgrade-nudge.js

@@ -20,7 +20,7 @@ export function paidFeatureNudge(tool) {
         tool,
         message: `${feature.label} ${feature.verb} a paid feature. See ${PRICING_URL}.`,
         pricingUrl: PRICING_URL,
-        upgradeUrl: `https://askthew.com/mcp?utm_source=mcp-plugin&utm_medium=tool-nudge&utm_campaign=mcp-free&tool=${encodeURIComponent(tool)}`,
+        upgradeUrl: `https://askthew.com/plugin?utm_source=mcp-plugin&utm_medium=tool-nudge&utm_campaign=mcp-free&tool=${encodeURIComponent(tool)}`,
         supportEmail: SUPPORT_EMAIL,
         cta: "Run: npx @askthew/mcp-plugin upgrade",
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askthew/mcp-plugin",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "private": false,
   "description": "Ask The W plugin connector for local-first coding-agent decisions, signals, and review.",
   "type": "module",