@askthew/mcp-plugin 0.2.8 → 0.4.0

package/dist/install.test.js

@@ -0,0 +1,237 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { formatInstallCommand, installBehaviorInstructions, installHostConfig, mergeHostSettings, resolveSettingsPath, sendInstallHeartbeat, verificationNextStep, } from "./install.js";
+test("mergeHostSettings preserves unrelated MCP servers and replaces askthew", () => {
+    const merged = mergeHostSettings({
+        existingSettings: {
+            theme: "dark",
+            mcpServers: {
+                github: {
+                    command: "github-mcp",
+                },
+                askthew: {
+                    command: "old-command",
+                },
+            },
+        },
+        hostType: "codex",
+        token: "token-123",
+        apiUrl: "https://askthew.example.com",
+        serverName: "askthew_workspace_a",
+    });
+    assert.deepEqual(merged.theme, "dark");
+    assert.deepEqual(Object.keys(merged.mcpServers ?? {}).sort(), ["askthew_workspace_a", "github"]);
+    assert.deepEqual(merged.mcpServers.askthew_workspace_a, {
+        command: "npx",
+        args: ["-y", "--prefer-online", "@askthew/mcp-plugin@latest"],
+        env: {
+            ASKTHEW_INSTALL_TOKEN: "token-123",
+            ASKTHEW_API_URL: "https://askthew.example.com",
+            ASKTHEW_HOST_TYPE: "codex",
+            ASKTHEW_SERVER_NAME: "askthew_workspace_a",
+        },
+    });
+});
+test("installHostConfig writes Claude Code local MCP settings and stays idempotent", () => {
+    const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-mcp-install-"));
+    const tempProject = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-claude-project-"));
+    const settingsPath = resolveSettingsPath({
+        hostType: "claude_code",
+        homeDirectory: tempHome,
+    });
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify({
+        projects: {
+            [tempProject]: {
+                mcpServers: {
+                    github: {
+                        command: "github-mcp",
+                    },
+                },
+            },
+        },
+    }, null, 2), "utf8");
+    const first = installHostConfig({
+        hostType: "claude_code",
+        token: "token-456",
+        apiUrl: "https://askthew.example.com",
+        serverName: "askthew_workspace_a",
+        clientId: "claude_code",
+        clientLabel: "Claude Code",
+        homeDirectory: tempHome,
+        cwd: tempProject,
+    });
+    const afterFirst = fs.readFileSync(settingsPath, "utf8");
+    const second = installHostConfig({
+        hostType: "claude_code",
+        token: "token-456",
+        apiUrl: "https://askthew.example.com",
+        serverName: "askthew_workspace_a",
+        clientId: "claude_code",
+        clientLabel: "Claude Code",
+        homeDirectory: tempHome,
+        cwd: tempProject,
+    });
+    const afterSecond = fs.readFileSync(settingsPath, "utf8");
+    const parsed = JSON.parse(afterSecond);
+    const projectServers = parsed.projects[tempProject].mcpServers;
+    assert.equal(first.settingsPath, settingsPath);
+    assert.equal(second.settingsPath, settingsPath);
+    assert.equal(afterFirst, afterSecond);
+    assert.deepEqual(Object.keys(projectServers ?? {}).sort(), ["askthew_workspace_a", "github"]);
+    assert.equal(projectServers.askthew_workspace_a.env.ASKTHEW_INSTALL_TOKEN, "token-456");
+    assert.equal(projectServers.askthew_workspace_a.env.ASKTHEW_CLIENT_ID, "claude_code");
+    assert.equal(projectServers.askthew_workspace_a.env.ASKTHEW_CLIENT_LABEL, "Claude Code");
+    fs.rmSync(tempHome, { recursive: true, force: true });
+    fs.rmSync(tempProject, { recursive: true, force: true });
+});
+test("installHostConfig writes Codex MCP servers to config.toml", () => {
+    const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-mcp-multi-workspace-"));
+    const settingsPath = resolveSettingsPath({
+        hostType: "codex",
+        homeDirectory: tempHome,
+    });
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, [
+        'model = "gpt-5"',
+        "",
+        "[mcp_servers.github]",
+        'command = "github-mcp"',
+        "",
+    ].join("\n"), "utf8");
+    installHostConfig({
+        hostType: "codex",
+        token: "token-a",
+        apiUrl: "https://askthew.example.com",
+        serverName: "askthew_workspace_a",
+        homeDirectory: tempHome,
+    });
+    installHostConfig({
+        hostType: "codex",
+        token: "token-b",
+        apiUrl: "https://askthew.example.com",
+        serverName: "askthew_workspace_b",
+        homeDirectory: tempHome,
+    });
+    const toml = fs.readFileSync(settingsPath, "utf8");
+    assert.match(toml, /\[mcp_servers\.github\]/);
+    assert.match(toml, /\[mcp_servers\.askthew_workspace_a\]/);
+    assert.match(toml, /\[mcp_servers\.askthew_workspace_b\]/);
+    assert.match(toml, /ASKTHEW_INSTALL_TOKEN = "token-a"/);
+    assert.match(toml, /ASKTHEW_INSTALL_TOKEN = "token-b"/);
+    fs.rmSync(tempHome, { recursive: true, force: true });
+});
+test("installHostConfig dry run returns merged JSON without writing a file", () => {
+    const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-mcp-dry-run-"));
+    const settingsPath = resolveSettingsPath({
+        hostType: "codex",
+        homeDirectory: tempHome,
+    });
+    const result = installHostConfig({
+        hostType: "codex",
+        token: "token-789",
+        apiUrl: "https://askthew.example.com",
+        serverName: "askthew_workspace_a",
+        homeDirectory: tempHome,
+        dryRun: true,
+    });
+    assert.equal(result.wroteFile, false);
+    assert.equal(fs.existsSync(settingsPath), false);
+    assert.match(result.json, /ASKTHEW_INSTALL_TOKEN/);
+    assert.match(result.json, /\[mcp_servers\.askthew_workspace_a\]/);
+    fs.rmSync(tempHome, { recursive: true, force: true });
+});
+test("installHostConfig writes Cursor global mcp.json", () => {
+    const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-cursor-mcp-"));
+    const settingsPath = resolveSettingsPath({
+        hostType: "cursor",
+        homeDirectory: tempHome,
+    });
+    installHostConfig({
+        hostType: "cursor",
+        token: "token-cursor",
+        apiUrl: "https://askthew.example.com",
+        serverName: "askthew",
+        homeDirectory: tempHome,
+    });
+    const parsed = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    assert.deepEqual(Object.keys(parsed.mcpServers ?? {}), ["askthew"]);
+    assert.equal(parsed.mcpServers.askthew.command, "npx");
+    assert.equal(parsed.mcpServers.askthew.env.ASKTHEW_HOST_TYPE, "cursor");
+    fs.rmSync(tempHome, { recursive: true, force: true });
+});
+test("formatInstallCommand emits the one-command guided install form", () => {
+    const command = formatInstallCommand({
+        hostType: "codex",
+        token: "token-abc",
+        apiUrl: "https://askthew.example.com",
+        serverName: "askthew_workspace_a",
+    });
+    assert.equal(command, 'npx -y --prefer-online @askthew/mcp-plugin@latest install --host codex --token "token-abc" --api-url "https://askthew.example.com" --server-name "askthew_workspace_a"');
+});
+test("verificationNextStep points users to every-session startup capture", () => {
+    const nextStep = verificationNextStep("codex");
+    assert.match(nextStep, /Refresh Ask The W/);
+    assert.match(nextStep, /every new Codex session in this repo/);
+    assert.match(nextStep, /before plan mode or exploration/);
+    assert.match(nextStep, /list_mcp_resources\/list_mcp_resource_templates may be empty/);
+});
+test("sendInstallHeartbeat pings Ask The W after config install", async () => {
+    const calls = [];
+    const ok = await sendInstallHeartbeat({
+        hostType: "codex",
+        token: "token-abc",
+        apiUrl: "https://askthew.example.com/",
+        serverName: "askthew",
+        cwd: process.cwd(),
+        fetchImpl: async (url, init) => {
+            calls.push({
+                url: String(url),
+                body: JSON.parse(String(init?.body ?? "{}")),
+            });
+            return new Response("{}", { status: 200 });
+        },
+    });
+    assert.equal(ok, true);
+    assert.equal(calls[0]?.url, "https://askthew.example.com/api/connectors/mcp/heartbeat");
+    assert.equal(calls[0]?.body.installToken, "token-abc");
+    assert.equal(calls[0]?.body.hostType, "codex");
+    assert.equal(calls[0]?.body.serverName, "askthew");
+    assert.equal(calls[0]?.body.clientId, "codex");
+});
+test("installBehaviorInstructions adds persistent Codex tracking rules without clobbering existing instructions", () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-agent-instructions-"));
+    const agentsPath = path.join(tempRoot, "AGENTS.md");
+    fs.writeFileSync(agentsPath, "# Existing instructions\n\nKeep this section.\n", "utf8");
+    const result = installBehaviorInstructions({
+        hostType: "codex",
+        cwd: tempRoot,
+    });
+    const contents = fs.readFileSync(agentsPath, "utf8");
+    assert.equal(result.path, agentsPath);
+    assert.match(contents, /# Existing instructions/);
+    assert.match(contents, /Ask The W Plugin/);
+    assert.match(contents, /capture_session_signal/);
+    assert.match(contents, /At the start of every new Codex session in this repo/);
+    assert.match(contents, /before plan mode, exploration, or any normal reply/);
+    assert.match(contents, /metadata\.recovered_missed_startup=true/);
+    assert.match(contents, /every 8-12 turns/);
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+test("installBehaviorInstructions creates Cursor rule file", () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-cursor-rules-"));
+    const result = installBehaviorInstructions({
+        hostType: "cursor",
+        cwd: tempRoot,
+    });
+    assert.equal(result.path, path.join(tempRoot, ".cursor", "rules", "askthew.mdc"));
+    assert.match(fs.readFileSync(result.path, "utf8"), /alwaysApply: true/);
+    assert.match(fs.readFileSync(result.path, "utf8"), /Ask The W Plugin/);
+    assert.match(fs.readFileSync(result.path, "utf8"), /At the start of every new Cursor session/);
+    assert.match(fs.readFileSync(result.path, "utf8"), /before plan mode, exploration, or any normal reply/);
+    assert.match(fs.readFileSync(result.path, "utf8"), /metadata\.recovered_missed_startup=true/);
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});

package/dist/lib/auth-magic-link.d.ts

@@ -0,0 +1,22 @@
+import type { CliCredentials } from "./free-tier-policy.js";
+export interface MagicLinkClientOptions {
+    apiUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function requestMagicLinkCode(input: {
+    email: string;
+    deviceLabel?: string;
+    apiUrl?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    requestId: string;
+    expiresAt: string;
+    devCode?: string;
+}>;
+export declare function verifyMagicLinkCode(input: {
+    requestId: string;
+    code: string;
+    apiUrl?: string;
+    fetchImpl?: typeof fetch;
+    telemetryOptOut?: boolean;
+}): Promise<CliCredentials>;

package/dist/lib/auth-magic-link.js

@@ -0,0 +1,43 @@
+import { credentialsPath, writePrivateJson } from "./paths.js";
+function baseUrl(apiUrl) {
+    return (apiUrl?.trim() || process.env.ASKTHEW_API_URL?.trim() || "https://app.askthew.com").replace(/\/$/, "");
+}
+async function requestJson(route, body, options) {
+    const fetcher = options.fetchImpl ?? fetch;
+    const response = await fetcher(`${baseUrl(options.apiUrl)}${route}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    const payload = await response.json().catch(() => null);
+    if (!response.ok) {
+        const message = payload && typeof payload === "object" && "error" in payload
+            ? String(payload.error)
+            : "Ask The W auth request failed.";
+        throw new Error(message);
+    }
+    return payload;
+}
+export async function requestMagicLinkCode(input) {
+    return requestJson("/api/cli/v1/magic-link/request", {
+        email: input.email,
+        deviceLabel: input.deviceLabel,
+    }, input);
+}
+export async function verifyMagicLinkCode(input) {
+    const verified = await requestJson("/api/cli/v1/magic-link/verify", {
+        requestId: input.requestId,
+        code: input.code,
+    }, input);
+    const credentials = {
+        email: verified.email,
+        userId: verified.userId,
+        cliToken: verified.cliToken,
+        cliTokenId: verified.cliTokenId,
+        accountStatus: verified.accountStatus,
+        apiUrl: input.apiUrl,
+        telemetryOptOut: input.telemetryOptOut,
+    };
+    writePrivateJson(credentialsPath(), credentials);
+    return credentials;
+}

package/dist/lib/free-tier-policy.d.ts

@@ -0,0 +1,19 @@
+export type McpMode = "paid" | "free" | "unauthenticated";
+export interface CliCredentials {
+    email?: string;
+    userId: string;
+    cliToken: string;
+    cliTokenId: string;
+    apiUrl?: string;
+    telemetryOptOut?: boolean;
+    accountStatus?: "new_dormant" | "existing_active";
+}
+export interface ModeResolution {
+    mode: McpMode;
+    installToken?: string;
+    cliCredentials?: CliCredentials;
+    reason: string;
+}
+export declare function loadCliCredentials(env?: NodeJS.ProcessEnv): CliCredentials | null;
+export declare function resolveMcpMode(env?: NodeJS.ProcessEnv): ModeResolution;
+export declare function isTelemetryOptedOut(env?: NodeJS.ProcessEnv, credentials?: CliCredentials | null): boolean;

package/dist/lib/free-tier-policy.js

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import { credentialsPath, readJsonFile } from "./paths.js";
+function clean(value) {
+    return String(value ?? "").trim().replace(/^['"]/, "").replace(/['"]$/, "");
+}
+export function loadCliCredentials(env = process.env) {
+    const explicitToken = clean(env.ASKTHEW_CLI_TOKEN);
+    if (explicitToken) {
+        return {
+            userId: clean(env.ASKTHEW_USER_ID) || "local",
+            cliToken: explicitToken,
+            cliTokenId: clean(env.ASKTHEW_CLI_TOKEN_ID) || "env",
+            apiUrl: clean(env.ASKTHEW_API_URL) || undefined,
+            telemetryOptOut: env.ASKTHEW_TELEMETRY === "off",
+        };
+    }
+    const creds = readJsonFile(credentialsPath(env));
+    if (!creds?.cliToken || !creds.userId || !creds.cliTokenId) {
+        return null;
+    }
+    return creds;
+}
+export function resolveMcpMode(env = process.env) {
+    const installToken = clean(env.ASKTHEW_INSTALL_TOKEN);
+    if (installToken) {
+        return {
+            mode: "paid",
+            installToken,
+            reason: "workspace_install_token",
+        };
+    }
+    const credentials = loadCliCredentials(env);
+    if (credentials?.cliToken) {
+        return {
+            mode: "free",
+            cliCredentials: credentials,
+            reason: "cli_free_tier_credentials",
+        };
+    }
+    if (clean(env.ASKTHEW_FREE_MODE) === "1" || clean(env.ASKTHEW_FREE_MODE).toLowerCase() === "true") {
+        return {
+            mode: "unauthenticated",
+            reason: fs.existsSync(credentialsPath(env)) ? "invalid_cli_credentials" : "free_mode_no_credentials",
+        };
+    }
+    return {
+        mode: "unauthenticated",
+        reason: "no_identity",
+    };
+}
+export function isTelemetryOptedOut(env = process.env, credentials = loadCliCredentials(env)) {
+    return env.ASKTHEW_TELEMETRY === "off" || credentials?.telemetryOptOut === true;
+}

package/dist/lib/local-store.d.ts

@@ -0,0 +1,99 @@
+export type SignalKind = "setup_complete" | "session_checkpoint" | "direction_change" | "implementation_update" | "verification_result" | "final_summary";
+export type DecisionStatus = "proposed" | "committed" | "shipped" | "abandoned";
+export interface LocalSignalInput {
+    sessionId: string;
+    sequence: number;
+    kind: SignalKind;
+    summary: string;
+    evidence?: unknown[];
+    filesTouched?: string[];
+    commandsRun?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface LocalSignal extends Required<LocalSignalInput> {
+    id: number;
+    capturedAt: string;
+}
+export interface LocalDecision {
+    id: string;
+    sessionId: string | null;
+    headline: string;
+    why: string | null;
+    status: DecisionStatus;
+    alignment: "aligned" | "orthogonal" | "conflicts" | "ambiguous" | null;
+    files: string[];
+    sourceSignalIds: number[];
+    rawContent: string;
+    createdAt: string;
+    updatedAt: string;
+    uploadedAt: string | null;
+}
+export interface LocalDecisionInput {
+    id?: string;
+    sessionId?: string | null;
+    headline?: string;
+    why?: string | null;
+    status?: DecisionStatus;
+    alignment?: LocalDecision["alignment"];
+    files?: string[];
+    sourceSignalIds?: number[];
+    rawContent: string;
+}
+export interface TelemetryOutboxRow {
+    id: number;
+    payload: Record<string, unknown>;
+    createdAt: string;
+    attempts: number;
+    lastAttemptAt: string | null;
+    deliveredAt: string | null;
+}
+export declare class LocalStore {
+    private readonly storePath;
+    private data;
+    private db;
+    private jsonMode;
+    private jsonPath;
+    private constructor();
+    static open(input?: {
+        path?: string;
+    }): LocalStore;
+    get usingJsonFallback(): boolean;
+    close(): void;
+    migrate(): void;
+    getMeta(key: string): string;
+    setMeta(key: string, value: string): void;
+    insertSignal(input: LocalSignalInput): LocalSignal;
+    listSignals(input?: {
+        sessionId?: string;
+        limit?: number;
+        uploaded?: boolean;
+    }): LocalSignal[];
+    getSignal(id: number): LocalSignal | null;
+    mostRecentSessionId(): any;
+    createDecision(input: LocalDecisionInput): LocalDecision;
+    updateDecision(id: string, patch: Partial<Omit<LocalDecision, "id" | "createdAt">>): LocalDecision | null;
+    deleteDecision(id: string): boolean;
+    getDecision(id: string): LocalDecision | null;
+    listDecisions(input?: {
+        status?: DecisionStatus;
+        limit?: number;
+        since?: string;
+        pendingUploadOnly?: boolean;
+    }): LocalDecision[];
+    enqueueTelemetry(payload: Record<string, unknown>): number;
+    listTelemetryOutbox(input?: {
+        undeliveredOnly?: boolean;
+        limit?: number;
+    }): TelemetryOutboxRow[];
+    markTelemetryAttempt(id: number, delivered: boolean): void;
+    stats(): {
+        signals: number;
+        decisions: number;
+        decisionsByStatus: Record<string, number>;
+        lastSessionId: string | null;
+        jsonFallback: boolean;
+    };
+    private openDatabase;
+    private persistJson;
+    private nextJsonId;
+}