@askthew/mcp-plugin 0.2.8 → 0.4.2

package/dist/install.d.ts

@@ -1,17 +1,27 @@
 export type SupportedHostType = "claude_code" | "codex" | "cursor";
 interface HostConfigInput {
     hostType: SupportedHostType;
-    token: string;
+    token?: string;
     apiUrl: string;
     serverName: string;
     clientId?: string;
     clientLabel?: string;
+    free?: boolean;
+    email?: string;
+    cwd?: string;
 }
 interface InstallHostConfigInput extends HostConfigInput {
     dryRun?: boolean;
     homeDirectory?: string;
     cwd?: string;
 }
+interface UninstallHostConfigInput {
+    hostType: SupportedHostType;
+    serverName?: string;
+    dryRun?: boolean;
+    homeDirectory?: string;
+    cwd?: string;
+}
 export declare function resolveSettingsPath(input: {
     hostType: SupportedHostType;
     homeDirectory?: string;
@@ -20,8 +30,23 @@ export declare function createServerEntry(input: HostConfigInput): {
     command: string;
     args: string[];
     env: {
+        ASKTHEW_SERVICE_NAME?: string | undefined;
+        ASKTHEW_APP_PATH?: string | undefined;
+        ASKTHEW_REPO_ROOT?: string | undefined;
         ASKTHEW_HOST_TYPE: SupportedHostType;
         ASKTHEW_SERVER_NAME: string;
+        ASKTHEW_REPO_NAME: string;
+        ASKTHEW_CLIENT_LABEL?: string | undefined;
+        ASKTHEW_CLIENT_ID?: string | undefined;
+        ASKTHEW_FREE_MODE: string;
+        ASKTHEW_API_URL: string;
+    } | {
+        ASKTHEW_SERVICE_NAME?: string | undefined;
+        ASKTHEW_APP_PATH?: string | undefined;
+        ASKTHEW_REPO_ROOT?: string | undefined;
+        ASKTHEW_HOST_TYPE: SupportedHostType;
+        ASKTHEW_SERVER_NAME: string;
+        ASKTHEW_REPO_NAME: string;
         ASKTHEW_CLIENT_LABEL?: string | undefined;
         ASKTHEW_CLIENT_ID?: string | undefined;
         ASKTHEW_INSTALL_TOKEN: string;
@@ -40,8 +65,23 @@ export declare function createHostConfigSnippet(input: HostConfigInput): {
                 command: string;
                 args: string[];
                 env: {
+                    ASKTHEW_SERVICE_NAME?: string | undefined;
+                    ASKTHEW_APP_PATH?: string | undefined;
+                    ASKTHEW_REPO_ROOT?: string | undefined;
+                    ASKTHEW_HOST_TYPE: SupportedHostType;
+                    ASKTHEW_SERVER_NAME: string;
+                    ASKTHEW_REPO_NAME: string;
+                    ASKTHEW_CLIENT_LABEL?: string | undefined;
+                    ASKTHEW_CLIENT_ID?: string | undefined;
+                    ASKTHEW_FREE_MODE: string;
+                    ASKTHEW_API_URL: string;
+                } | {
+                    ASKTHEW_SERVICE_NAME?: string | undefined;
+                    ASKTHEW_APP_PATH?: string | undefined;
+                    ASKTHEW_REPO_ROOT?: string | undefined;
                     ASKTHEW_HOST_TYPE: SupportedHostType;
                     ASKTHEW_SERVER_NAME: string;
+                    ASKTHEW_REPO_NAME: string;
                     ASKTHEW_CLIENT_LABEL?: string | undefined;
                     ASKTHEW_CLIENT_ID?: string | undefined;
                     ASKTHEW_INSTALL_TOKEN: string;
@@ -67,6 +107,12 @@ export declare function installHostConfig(input: InstallHostConfigInput): {
     wroteFile: boolean;
     nextStep: string;
 };
+export declare function uninstallHostConfig(input: UninstallHostConfigInput): {
+    settingsPath: string;
+    json: string;
+    removedServerName: string;
+    wroteFile: boolean;
+};
 export declare function sendInstallHeartbeat(input: HostConfigInput & {
     cwd?: string;
     fetchImpl?: typeof fetch;
@@ -77,7 +123,16 @@ export declare function installBehaviorInstructions(input: {
     dryRun?: boolean;
 }): {
     path: string;
+    paths: string[];
     wroteFile: boolean;
     content: string;
 };
+export declare function uninstallBehaviorInstructions(input: {
+    hostType: SupportedHostType;
+    cwd?: string;
+    dryRun?: boolean;
+}): {
+    paths: string[];
+    wroteFile: boolean;
+};
 export {};

package/dist/install.js

@@ -18,16 +18,21 @@ export function resolveSettingsPath(input) {
     return path.join(homeDirectory, ".claude.json");
 }
 export function createServerEntry(input) {
+    const scope = resolvePluginScope(input.cwd ?? process.cwd());
     return {
         command: "npx",
         args: ["-y", "--prefer-online", "@askthew/mcp-plugin@latest"],
         env: {
-            ASKTHEW_INSTALL_TOKEN: input.token,
             ASKTHEW_API_URL: input.apiUrl,
+            ...(input.free ? { ASKTHEW_FREE_MODE: "1" } : { ASKTHEW_INSTALL_TOKEN: input.token ?? "" }),
             ...(input.clientId ? { ASKTHEW_CLIENT_ID: input.clientId } : {}),
             ...(input.clientLabel ? { ASKTHEW_CLIENT_LABEL: input.clientLabel } : {}),
             ASKTHEW_HOST_TYPE: input.hostType,
             ASKTHEW_SERVER_NAME: input.serverName,
+            ASKTHEW_REPO_NAME: scope.repoName,
+            ...(scope.repoRoot ? { ASKTHEW_REPO_ROOT: scope.repoRoot } : {}),
+            ...(scope.appPath ? { ASKTHEW_APP_PATH: scope.appPath } : {}),
+            ...(scope.serviceName ? { ASKTHEW_SERVICE_NAME: scope.serviceName } : {}),
         },
     };
 }
@@ -124,7 +129,7 @@ export function mergeHostSettings(input) {
     };
 }
 export function formatInstallCommand(input) {
-    return [
+    const parts = [
         "npx",
         "-y",
         "--prefer-online",
@@ -132,17 +137,25 @@ export function formatInstallCommand(input) {
         "install",
         "--host",
         input.hostType,
-        "--token",
-        JSON.stringify(input.token),
         "--api-url",
         JSON.stringify(input.apiUrl),
         "--server-name",
         JSON.stringify(input.serverName),
-    ].join(" ");
+    ];
+    if (input.free) {
+        parts.push("--free");
+        if (input.email) {
+            parts.push("--email", JSON.stringify(input.email));
+        }
+    }
+    else {
+        parts.splice(7, 0, "--token", JSON.stringify(input.token ?? ""));
+    }
+    return parts.join(" ");
 }
 export function verificationNextStep(hostType) {
     const hostLabel = hostType === "claude_code" ? "Claude Code" : hostType === "cursor" ? "Cursor" : "Codex";
-    return `Refresh Ask The W to confirm the plugin shows Installed. Restart or reload ${hostLabel} if it is already open. On the next Ask The W setup check, choose Always allow if ${hostLabel} asks for tool permission. The installed project instructions tell the coding agent when to send updates automatically. list_mcp_resources/list_mcp_resource_templates may be empty for this tool-driven connector and are not failure signals.`;
+    return `Refresh Ask The W to confirm the plugin shows Installed. Restart or reload ${hostLabel} if it is already open. At the start of every new ${hostLabel} session in this repo, the installed project instructions tell the coding agent to send a setup_complete update before plan mode or exploration. Choose Always allow if ${hostLabel} asks for Ask The W tool permission. list_mcp_resources/list_mcp_resource_templates may be empty for this tool-driven connector and are not failure signals.`;
 }
 export function installHostConfig(input) {
     const settingsPath = resolveSettingsPath({
@@ -174,6 +187,8 @@ export function installHostConfig(input) {
         serverName: input.serverName,
         clientId: input.clientId,
         clientLabel: input.clientLabel,
+        free: input.free,
+        cwd: input.cwd,
     };
     const json = input.hostType === "codex"
         ? mergeCodexSettings({
@@ -197,6 +212,65 @@ export function installHostConfig(input) {
         nextStep: verificationNextStep(input.hostType),
     };
 }
+export function uninstallHostConfig(input) {
+    const settingsPath = resolveSettingsPath({
+        hostType: input.hostType,
+        homeDirectory: input.homeDirectory,
+    });
+    const serverName = input.serverName?.trim() || "askthew";
+    let json = "";
+    if (fs.existsSync(settingsPath)) {
+        const raw = fs.readFileSync(settingsPath, "utf8");
+        if (input.hostType === "codex") {
+            json = removeCodexTomlServer(raw, serverName);
+            if (serverName !== "askthew") {
+                json = removeCodexTomlServer(json, "askthew");
+            }
+            json = json ? `${json}\n` : "";
+        }
+        else {
+            const parsed = raw.trim() ? JSON.parse(raw) : {};
+            if (input.hostType === "claude_code") {
+                const cwd = path.resolve(input.cwd ?? process.cwd());
+                const existingProjects = isRecord(parsed.projects) ? parsed.projects : {};
+                const existingProject = isRecord(existingProjects[cwd]) ? existingProjects[cwd] : {};
+                const existingMcpServers = isRecord(existingProject.mcpServers) ? existingProject.mcpServers : {};
+                const nextServers = { ...existingMcpServers };
+                delete nextServers[serverName];
+                if (serverName !== "askthew")
+                    delete nextServers.askthew;
+                json = JSON.stringify({
+                    ...parsed,
+                    projects: {
+                        ...existingProjects,
+                        [cwd]: {
+                            ...existingProject,
+                            mcpServers: nextServers,
+                        },
+                    },
+                }, null, 2);
+            }
+            else {
+                const existingMcpServers = isRecord(parsed.mcpServers) ? parsed.mcpServers : {};
+                const nextServers = { ...existingMcpServers };
+                delete nextServers[serverName];
+                if (serverName !== "askthew")
+                    delete nextServers.askthew;
+                json = JSON.stringify({ ...parsed, mcpServers: nextServers }, null, 2);
+            }
+            json = `${json}\n`;
+        }
+        if (!input.dryRun) {
+            fs.writeFileSync(settingsPath, json, "utf8");
+        }
+    }
+    return {
+        settingsPath,
+        json,
+        removedServerName: serverName,
+        wroteFile: !input.dryRun,
+    };
+}
 export async function sendInstallHeartbeat(input) {
     const fetcher = input.fetchImpl ?? fetch;
     const scope = resolvePluginScope(input.cwd ?? process.cwd());
@@ -220,8 +294,41 @@ export async function sendInstallHeartbeat(input) {
     });
     return response.ok;
 }
-function behaviorInstructions(hostType) {
+function detectStackGuidance(cwd) {
+    const packagePath = path.join(cwd, "package.json");
+    if (!fs.existsSync(packagePath)) {
+        return [];
+    }
+    let manifest = {};
+    try {
+        manifest = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+    }
+    catch {
+        return [];
+    }
+    const deps = {
+        ...(manifest.dependencies ?? {}),
+        ...(manifest.devDependencies ?? {}),
+    };
+    const names = new Set(Object.keys(deps));
+    const guidance = [];
+    if (names.has("next")) {
+        guidance.push("- Next.js detected: after changing route handlers, server actions, middleware, or cache behavior, capture `verification_result` with the command/result.");
+    }
+    if (names.has("express") || names.has("@types/express")) {
+        guidance.push("- Express detected: after changing middleware, request validation, or response envelopes, capture `verification_result` with the command/result.");
+    }
+    if (names.has("vite") || names.has("@vitejs/plugin-react")) {
+        guidance.push("- Vite detected: after changing client entrypoints, env handling, or build config, capture `verification_result` with the command/result.");
+    }
+    if (names.has("openai") || names.has("@openai/agents") || names.has("@ai-sdk/openai")) {
+        guidance.push("- OpenAI SDK detected: after editing prompts, model calls, streaming/SSE, or schema-validated responses, capture `direction_change` for prompt choices and `verification_result` for checked outputs.");
+    }
+    return guidance.slice(0, 4);
+}
+function behaviorInstructions(hostType, cwd = process.cwd()) {
     const hostLabel = hostType === "claude_code" ? "Claude Code" : hostType === "cursor" ? "Cursor" : "Codex";
+    const stackGuidance = detectStackGuidance(cwd);
     return [
         ASKTHEW_INSTRUCTIONS_START,
         "",
@@ -229,29 +336,32 @@ function behaviorInstructions(hostType) {
         "",
         `This workspace uses the Ask The W Plugin. When working in this repo with ${hostLabel}, send compact Ask The W updates automatically with the MCP tool \`capture_session_signal\`.`,
         "",
+        "Startup update:",
+        `- At the start of every new ${hostLabel} session in this repo, before plan mode, exploration, or any normal reply, call \`capture_session_signal\` with \`kind: "setup_complete"\` if the tool is available.`,
+        `- If the tool is unavailable, tell the user to restart or reload ${hostLabel}; do not use \`list_mcp_resources\` or \`list_mcp_resource_templates\` as pass/fail checks.`,
+        "- If you realize later in the conversation that the startup call was missed, send it immediately with `metadata.recovered_missed_startup=true`.",
+        "",
         "Send an update:",
         "- after the user accepts or rejects product, architecture, or implementation direction",
-        "- after meaningful implementation changes",
+        "- before using tools that write files, after meaningful implementation changes",
         "- after tests, builds, lint, or other verification",
-        "- every 8-12 turns in long sessions",
         "- at the final summary",
+        ...(stackGuidance.length > 0 ? ["", "Stack-specific nudges:", ...stackGuidance] : []),
         "",
         "Keep updates compact: short summary, minimal evidence excerpts, files touched, commands run, and useful metadata. Do not send full transcripts. Redact obvious secrets before sending.",
         "",
-        "If this is the first session after install or reload, immediately send a `setup_complete` update with `capture_session_signal` before continuing. If the host asks for Ask The W tool permission, the user should choose Always allow if available.",
-        "",
         ASKTHEW_INSTRUCTIONS_END,
         "",
     ].join("\n");
 }
-function cursorBehaviorInstructions() {
+function cursorBehaviorInstructions(cwd = process.cwd()) {
     return [
         "---",
         "description: Ask The W Plugin capture rules",
         "alwaysApply: true",
         "---",
         "",
-        behaviorInstructions("cursor"),
+        behaviorInstructions("cursor", cwd),
     ].join("\n");
 }
 function upsertMarkedBlock(existing, block) {
@@ -265,21 +375,56 @@ function upsertMarkedBlock(existing, block) {
 }
 export function installBehaviorInstructions(input) {
     const cwd = path.resolve(input.cwd ?? process.cwd());
-    const instructionsPath = input.hostType === "claude_code"
-        ? path.join(cwd, "CLAUDE.md")
-        : input.hostType === "cursor"
-            ? path.join(cwd, ".cursor", "rules", "askthew.mdc")
-            : path.join(cwd, "AGENTS.md");
-    const block = input.hostType === "cursor" ? cursorBehaviorInstructions() : behaviorInstructions(input.hostType);
-    const existing = fs.existsSync(instructionsPath) ? fs.readFileSync(instructionsPath, "utf8") : "";
-    const next = input.hostType === "cursor" ? block : upsertMarkedBlock(existing, block);
-    if (!input.dryRun) {
-        fs.mkdirSync(path.dirname(instructionsPath), { recursive: true });
-        fs.writeFileSync(instructionsPath, next, "utf8");
+    const markdownBlock = behaviorInstructions(input.hostType, cwd);
+    const markdownTargets = [path.join(cwd, "CLAUDE.md"), path.join(cwd, "AGENTS.md")];
+    const writtenPaths = [];
+    let primaryPath = input.hostType === "claude_code" ? markdownTargets[0] : markdownTargets[1];
+    for (const instructionsPath of markdownTargets) {
+        const existing = fs.existsSync(instructionsPath) ? fs.readFileSync(instructionsPath, "utf8") : "";
+        const next = upsertMarkedBlock(existing, markdownBlock);
+        if (!input.dryRun) {
+            fs.mkdirSync(path.dirname(instructionsPath), { recursive: true });
+            fs.writeFileSync(instructionsPath, next, "utf8");
+        }
+        writtenPaths.push(instructionsPath);
+    }
+    if (input.hostType === "cursor") {
+        const cursorPath = path.join(cwd, ".cursor", "rules", "askthew.mdc");
+        if (!input.dryRun) {
+            fs.mkdirSync(path.dirname(cursorPath), { recursive: true });
+            fs.writeFileSync(cursorPath, cursorBehaviorInstructions(cwd), "utf8");
+        }
+        writtenPaths.push(cursorPath);
+        primaryPath = cursorPath;
+    }
+    return {
+        path: primaryPath,
+        paths: writtenPaths,
+        wroteFile: !input.dryRun,
+        content: markdownBlock,
+    };
+}
+export function uninstallBehaviorInstructions(input) {
+    const cwd = path.resolve(input.cwd ?? process.cwd());
+    const markdownTargets = [path.join(cwd, "CLAUDE.md"), path.join(cwd, "AGENTS.md")];
+    const touchedPaths = [];
+    for (const instructionsPath of markdownTargets) {
+        if (!fs.existsSync(instructionsPath))
+            continue;
+        const existing = fs.readFileSync(instructionsPath, "utf8");
+        const next = existing.replace(new RegExp(`\\n?${ASKTHEW_INSTRUCTIONS_START}[\\s\\S]*?${ASKTHEW_INSTRUCTIONS_END}\\n?`, "g"), "\n").trimEnd() + "\n";
+        if (!input.dryRun)
+            fs.writeFileSync(instructionsPath, next, "utf8");
+        touchedPaths.push(instructionsPath);
+    }
+    const cursorPath = path.join(cwd, ".cursor", "rules", "askthew.mdc");
+    if (input.hostType === "cursor" && fs.existsSync(cursorPath)) {
+        if (!input.dryRun)
+            fs.rmSync(cursorPath, { force: true });
+        touchedPaths.push(cursorPath);
     }
     return {
-        path: instructionsPath,
+        paths: touchedPaths,
         wroteFile: !input.dryRun,
-        content: next,
     };
 }

package/dist/install.test.d.ts

@@ -0,0 +1 @@
+export {};