@askthew/mcp-plugin 0.2.7 → 0.4.0

package/dist/lib/tip-engine.js

@@ -0,0 +1,237 @@
+const severityRank = {
+    high: 0,
+    medium: 1,
+    low: 2,
+};
+export function analyzeLocalPatterns(input) {
+    const tips = TIP_PATTERNS.map((pattern) => pattern(input)).filter((tip) => Boolean(tip));
+    return tips
+        .sort((left, right) => severityRank[left.severity] - severityRank[right.severity] || left.id.localeCompare(right.id))
+        .slice(0, 3);
+}
+export const TIP_PATTERNS = [
+    highProposedStagnation,
+    verificationFailClusters,
+    highChurnNoDecision,
+    directionThrash,
+    unboundedDecision,
+    lateNightDecisions,
+    singleFileObsession,
+    verificationMissing,
+    implementationWithoutSummary,
+    repeatedDirectionChanges,
+    abandonedSpike,
+    noRecentDecisionWhy,
+    longSessionNoCheckpoint,
+    setupOnlySession,
+    commandsHeavySession,
+    filesWithoutSignals,
+];
+function highProposedStagnation({ decisions, now = new Date() }) {
+    const cutoff = now.getTime() - 3 * 24 * 60 * 60 * 1000;
+    const stuck = decisions.filter((decision) => decision.status === "proposed" && new Date(decision.createdAt).getTime() < cutoff);
+    if (stuck.length < 3) {
+        return null;
+    }
+    return {
+        id: "high_proposed_stagnation",
+        severity: "high",
+        tip: `${stuck.length} decisions are still proposed after more than 3 days. Block 30 minutes to commit or abandon the oldest ones.`,
+        alternative: "Timebox each new decision with an explicit deadline in `why`.",
+        evidence: stuck.slice(0, 5).map((decision) => decision.id),
+    };
+}
+function verificationFailClusters({ signals }) {
+    const verification = signals.filter((signal) => signal.kind === "verification_result").slice(-8);
+    const failures = verification.filter((signal) => /fail|failed|error|red|broken|timeout/i.test(signal.summary));
+    if (verification.length < 4 || failures.length < 3) {
+        return null;
+    }
+    return {
+        id: "verification_fail_clusters",
+        severity: "medium",
+        tip: `${failures.length} recent verifications failed. The fix is rarely the next blind attempt.`,
+        alternative: "Pause, write what specifically failed in a `direction_change` signal, then run a smaller test before the full suite.",
+        evidence: failures.slice(0, 5).map((signal) => `s_${signal.id}`),
+    };
+}
+function highChurnNoDecision({ signals, decisions }) {
+    const files = new Set(signals.flatMap((signal) => signal.filesTouched));
+    if (files.size < 12 || decisions.length > 0) {
+        return null;
+    }
+    return {
+        id: "high_churn_no_decision",
+        severity: "medium",
+        tip: `You touched ${files.size} files but logged 0 decisions in this window.`,
+        alternative: "Capture a single decision for the largest change - even one line of `why` beats none.",
+        evidence: [],
+    };
+}
+function directionThrash({ signals }) {
+    const changes = signals.filter((signal) => signal.kind === "direction_change");
+    if (changes.length < 4) {
+        return null;
+    }
+    return {
+        id: "direction_thrash",
+        severity: "high",
+        tip: `${changes.length} direction changes landed in one window. You may be switching approaches faster than evidence can settle.`,
+        alternative: "Pick one reversible path, write the stop condition, and only change course when that condition is met.",
+        evidence: changes.slice(0, 5).map((signal) => `s_${signal.id}`),
+    };
+}
+function unboundedDecision({ decisions }) {
+    const weak = decisions.filter((decision) => !decision.why || decision.why.trim().length < 12);
+    if (weak.length < 2) {
+        return null;
+    }
+    return {
+        id: "unbounded_decision",
+        severity: "medium",
+        tip: `${weak.length} decisions are missing a useful why, so future you will have to reconstruct the reason.`,
+        alternative: "Add one sentence: what tradeoff made this worth doing now?",
+        evidence: weak.slice(0, 5).map((decision) => decision.id),
+    };
+}
+function lateNightDecisions({ decisions }) {
+    const late = decisions.filter((decision) => {
+        const hour = new Date(decision.createdAt).getHours();
+        return hour <= 5 || hour >= 23;
+    });
+    if (late.length < 2) {
+        return null;
+    }
+    return {
+        id: "late_night_decisions",
+        severity: "low",
+        tip: `${late.length} decisions were logged late at night. That can be fine, but reread them when you're fresh.`,
+        alternative: "Mark late decisions as proposed first, then commit them after a daylight pass.",
+        evidence: late.slice(0, 5).map((decision) => decision.id),
+    };
+}
+function singleFileObsession({ signals }) {
+    const counts = new Map();
+    for (const signal of signals) {
+        for (const file of signal.filesTouched) {
+            counts.set(file, (counts.get(file) ?? 0) + 1);
+        }
+    }
+    const [file, count] = [...counts.entries()].sort((a, b) => b[1] - a[1])[0] ?? [];
+    if (!file || count < 6) {
+        return null;
+    }
+    return {
+        id: "single_file_obsession",
+        severity: "low",
+        tip: `One file came up in ${count} signals. It may be carrying too much responsibility.`,
+        alternative: "Before editing it again, name the responsibility you expect this file to own.",
+        evidence: [],
+    };
+}
+function verificationMissing({ signals }) {
+    const implementation = signals.filter((signal) => signal.kind === "implementation_update");
+    const verification = signals.filter((signal) => signal.kind === "verification_result");
+    if (implementation.length < 3 || verification.length > 0) {
+        return null;
+    }
+    return {
+        id: "verification_missing",
+        severity: "medium",
+        tip: `${implementation.length} implementation updates landed without a verification result.`,
+        alternative: "Run the smallest relevant check now and capture the result, even if it fails.",
+        evidence: implementation.slice(0, 5).map((signal) => `s_${signal.id}`),
+    };
+}
+function implementationWithoutSummary({ signals }) {
+    const terse = signals.filter((signal) => signal.kind === "implementation_update" && signal.summary.length < 30);
+    if (terse.length < 3) {
+        return null;
+    }
+    return {
+        id: "terse_implementation_updates",
+        severity: "low",
+        tip: `${terse.length} implementation updates are too terse to be useful later.`,
+        alternative: "Capture the change plus the reason in one sentence.",
+        evidence: terse.slice(0, 5).map((signal) => `s_${signal.id}`),
+    };
+}
+function repeatedDirectionChanges(input) {
+    return directionThrash(input);
+}
+function abandonedSpike({ decisions }) {
+    const abandoned = decisions.filter((decision) => decision.status === "abandoned");
+    if (abandoned.length < 3) {
+        return null;
+    }
+    return {
+        id: "abandoned_spike",
+        severity: "medium",
+        tip: `${abandoned.length} decisions were abandoned. That is useful learning, but only if the reason is captured.`,
+        alternative: "Add the rejection reason to each abandoned decision before moving on.",
+        evidence: abandoned.slice(0, 5).map((decision) => decision.id),
+    };
+}
+function noRecentDecisionWhy({ decisions }) {
+    const recent = decisions.slice(0, 5);
+    if (recent.length < 3 || recent.some((decision) => (decision.why ?? "").trim().length > 20)) {
+        return null;
+    }
+    return {
+        id: "no_recent_decision_why",
+        severity: "medium",
+        tip: "Your recent decisions have headlines, but not enough reasoning to explain the tradeoff.",
+        alternative: "For the next decision, write why the rejected option lost.",
+        evidence: recent.map((decision) => decision.id),
+    };
+}
+function longSessionNoCheckpoint({ signals }) {
+    if (signals.length < 10 || signals.some((signal) => signal.kind === "session_checkpoint")) {
+        return null;
+    }
+    return {
+        id: "long_session_no_checkpoint",
+        severity: "low",
+        tip: `${signals.length} signals landed without a checkpoint. The session may be hard to review later.`,
+        alternative: "Capture one checkpoint after each meaningful block of work.",
+        evidence: [],
+    };
+}
+function setupOnlySession({ signals }) {
+    if (signals.length !== 1 || signals[0]?.kind !== "setup_complete") {
+        return null;
+    }
+    return {
+        id: "setup_only_session",
+        severity: "low",
+        tip: "This session only has startup captured so far.",
+        alternative: "Capture a checkpoint after the first meaningful decision or verification.",
+        evidence: signals[0] ? [`s_${signals[0].id}`] : [],
+    };
+}
+function commandsHeavySession({ signals }) {
+    const commands = signals.reduce((total, signal) => total + signal.commandsRun.length, 0);
+    if (commands < 15 || signals.some((signal) => signal.kind === "direction_change")) {
+        return null;
+    }
+    return {
+        id: "commands_heavy_session",
+        severity: "low",
+        tip: `${commands} commands ran without a captured direction change. Make sure the command loop still has a clear target.`,
+        alternative: "Write the next expected result before running another broad command.",
+        evidence: [],
+    };
+}
+function filesWithoutSignals({ signals }) {
+    const files = new Set(signals.flatMap((signal) => signal.filesTouched));
+    if (files.size < 8 || signals.length >= 5) {
+        return null;
+    }
+    return {
+        id: "files_without_signals",
+        severity: "low",
+        tip: `${files.size} files appeared across only ${signals.length} signals. The capture trail is thin for the amount of movement.`,
+        alternative: "Add a checkpoint before the next edit so the review has a clear midpoint.",
+        evidence: [],
+    };
+}

package/dist/lib/upgrade-nudge.d.ts

@@ -0,0 +1,19 @@
+export declare const PRICING_URL = "https://askthew.com/pricing";
+export declare const SUPPORT_EMAIL = "support@askthew.com";
+export declare function paidDescription(description: string, mode: "paid" | "free" | "unauthenticated"): string;
+export declare function paidFeatureNudge(tool: string): {
+    ok: boolean;
+    code: string;
+    tool: string;
+    message: string;
+    pricingUrl: string;
+    upgradeUrl: string;
+    supportEmail: string;
+    cta: string;
+};
+export declare function toolJson(value: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/lib/upgrade-nudge.js

@@ -0,0 +1,30 @@
+export const PRICING_URL = "https://askthew.com/pricing";
+export const SUPPORT_EMAIL = "support@askthew.com";
+export function paidDescription(description, mode) {
+    if (mode !== "free") {
+        return description;
+    }
+    return `${description} (paid - ${PRICING_URL})`;
+}
+export function paidFeatureNudge(tool) {
+    return {
+        ok: false,
+        code: "free_tier_paid_feature",
+        tool,
+        message: "This lives in your Ask The W workspace. It becomes available after you upgrade - your local decisions and signals will sync up automatically.",
+        pricingUrl: PRICING_URL,
+        upgradeUrl: `https://askthew.com/mcp?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",
+    };
+}
+export function toolJson(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}

package/dist/lib/upgrade-sync.d.ts

@@ -0,0 +1,38 @@
+import type { CliCredentials } from "./free-tier-policy.js";
+import type { LocalStore } from "./local-store.js";
+export declare function syncDryRun(store: LocalStore): {
+    pending: {
+        signals: number;
+        decisions: number;
+    };
+    alreadyUploaded: {
+        signals: number;
+        decisions: number;
+    };
+};
+export declare function uploadLocalStore(input: {
+    store: LocalStore;
+    credentials: CliCredentials;
+    syncToken?: string;
+    apiUrl?: string;
+    fetchImpl?: typeof fetch;
+    dryRun?: boolean;
+}): Promise<{
+    pending: {
+        signals: number;
+        decisions: number;
+    };
+    alreadyUploaded: {
+        signals: number;
+        decisions: number;
+    };
+    ok: boolean;
+    dryRun: boolean;
+    uploaded?: undefined;
+} | {
+    ok: boolean;
+    uploaded: {
+        signals: number;
+        decisions: number;
+    };
+}>;

package/dist/lib/upgrade-sync.js

@@ -0,0 +1,60 @@
+export function syncDryRun(store) {
+    const pendingSignals = store.listSignals({ limit: 100000 }).filter((signal) => !store.getMeta(`signal_uploaded:${signal.id}`));
+    const pendingDecisions = store.listDecisions({ limit: 100000, pendingUploadOnly: true });
+    const alreadySignals = store.listSignals({ limit: 100000 }).length - pendingSignals.length;
+    const alreadyDecisions = store.listDecisions({ limit: 100000 }).filter((decision) => decision.uploadedAt).length;
+    return {
+        pending: { signals: pendingSignals.length, decisions: pendingDecisions.length },
+        alreadyUploaded: { signals: alreadySignals, decisions: alreadyDecisions },
+    };
+}
+export async function uploadLocalStore(input) {
+    if (input.dryRun) {
+        return { ok: true, dryRun: true, ...syncDryRun(input.store) };
+    }
+    const fetcher = input.fetchImpl ?? fetch;
+    const apiUrl = (input.apiUrl ?? input.credentials.apiUrl ?? process.env.ASKTHEW_API_URL ?? "https://app.askthew.com").replace(/\/$/, "");
+    const token = input.syncToken ?? input.credentials.cliToken;
+    const signalRows = input.store
+        .listSignals({ limit: 100000 })
+        .filter((signal) => !input.store.getMeta(`signal_uploaded:${signal.id}`));
+    const decisionRows = input.store.listDecisions({ limit: 100000, pendingUploadOnly: true }).reverse();
+    let uploadedSignals = 0;
+    let uploadedDecisions = 0;
+    for (const chunk of chunks(signalRows, 100)) {
+        await postChunk(apiUrl, token, fetcher, "signals", chunk);
+        for (const signal of chunk) {
+            input.store.setMeta(`signal_uploaded:${signal.id}`, new Date().toISOString());
+        }
+        uploadedSignals += chunk.length;
+    }
+    for (const chunk of chunks(decisionRows, 100)) {
+        await postChunk(apiUrl, token, fetcher, "decisions", chunk);
+        for (const decision of chunk) {
+            input.store.updateDecision(decision.id, { uploadedAt: new Date().toISOString() });
+        }
+        uploadedDecisions += chunk.length;
+    }
+    return { ok: true, uploaded: { signals: uploadedSignals, decisions: uploadedDecisions } };
+}
+async function postChunk(apiUrl, token, fetcher, kind, items) {
+    const response = await fetcher(`${apiUrl}/api/cli/v1/upgrade/sync`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({ uploadVersion: 1, kind, items }),
+    });
+    if (!response.ok) {
+        const body = await response.json().catch(() => null);
+        throw new Error(body?.error ? String(body.error) : `Upload failed for ${kind}.`);
+    }
+}
+function chunks(items, size) {
+    const result = [];
+    for (let index = 0; index < items.length; index += size) {
+        result.push(items.slice(index, index + size));
+    }
+    return result;
+}

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

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

package/dist/local-store.test.js

@@ -0,0 +1,37 @@
+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 { LocalStore } from "./lib/local-store.js";
+test("local store migrates, captures signals, decisions, and FIFO telemetry", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-store-"));
+    const store = LocalStore.open({ path: path.join(dir, "store.sqlite") });
+    const signal = store.insertSignal({
+        sessionId: "s1",
+        sequence: 1,
+        kind: "session_checkpoint",
+        summary: "Checkpoint",
+        filesTouched: ["src/app.ts"],
+        commandsRun: ["npm test"],
+    });
+    const duplicate = store.insertSignal({
+        sessionId: "s1",
+        sequence: 1,
+        kind: "session_checkpoint",
+        summary: "Checkpoint duplicate",
+    });
+    const decision = store.createDecision({
+        rawContent: "Use local SQLite for free-tier capture.",
+        sessionId: "s1",
+        sourceSignalIds: [signal.id],
+    });
+    const firstOutbox = store.enqueueTelemetry({ n: 1 });
+    const secondOutbox = store.enqueueTelemetry({ n: 2 });
+    assert.equal(signal.id, duplicate.id);
+    assert.equal(store.listSignals({ sessionId: "s1" }).length, 1);
+    assert.equal(store.getDecision(decision.id)?.headline, "Use local SQLite for free-tier capture.");
+    assert.deepEqual(store.listTelemetryOutbox().map((row) => row.id), [firstOutbox, secondOutbox]);
+    store.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+});

package/dist/scope.d.ts

@@ -5,4 +5,3 @@ export interface PluginScope {
     serviceName?: string;
 }
 export declare function resolvePluginScope(startDirectory?: string): PluginScope;
-export declare function resolveFunctionalAreaFromToml(startDirectory?: string): string;

package/dist/scope.js

@@ -15,7 +15,6 @@ function parseAskTheWToml(filePath) {
         repoRoot: readValue("repo_root"),
         appPath: readValue("app_path"),
         serviceName: readValue("service_name"),
-        functionalArea: readValue("functional_area"),
     };
 }
 function findRepoRoot(startDirectory) {
@@ -53,8 +52,3 @@ export function resolvePluginScope(startDirectory = process.cwd()) {
         ...(parsedConfig.serviceName ? { serviceName: parsedConfig.serviceName } : {}),
     };
 }
-export function resolveFunctionalAreaFromToml(startDirectory = process.cwd()) {
-    const cwd = path.resolve(startDirectory);
-    const parsedConfig = parseAskTheWToml(path.join(cwd, ".asktheworld.toml"));
-    return parsedConfig.functionalArea || "";
-}

package/dist/scope.test.d.ts

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

package/dist/scope.test.js

@@ -0,0 +1,32 @@
+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 { resolvePluginScope } from "./scope.js";
+test("resolvePluginScope derives repo and app path from cwd", () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-scope-"));
+    const repoRoot = path.join(tempRoot, "repo");
+    const appRoot = path.join(repoRoot, "apps", "landing");
+    fs.mkdirSync(path.join(repoRoot, ".git"), { recursive: true });
+    fs.mkdirSync(appRoot, { recursive: true });
+    const scope = resolvePluginScope(appRoot);
+    assert.equal(scope.repoName, "repo");
+    assert.equal(scope.repoRoot, repoRoot);
+    assert.equal(scope.appPath, "apps/landing");
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+test("resolvePluginScope respects explicit .asktheworld.toml values", () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-scope-config-"));
+    fs.mkdirSync(tempRoot, { recursive: true });
+    fs.writeFileSync(path.join(tempRoot, ".asktheworld.toml"), [
+        'repo_name = "main-platform"',
+        'app_path = "apps/decisions"',
+        'service_name = "decisions"',
+    ].join("\n"), "utf8");
+    const scope = resolvePluginScope(tempRoot);
+    assert.equal(scope.repoName, "main-platform");
+    assert.equal(scope.appPath, "apps/decisions");
+    assert.equal(scope.serviceName, "decisions");
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});

package/dist/tip-engine.test.d.ts

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

package/dist/tip-engine.test.js

@@ -0,0 +1,51 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { analyzeLocalPatterns } from "./lib/tip-engine.js";
+function signal(id, kind, summary = "ok") {
+    return {
+        id,
+        sessionId: "s1",
+        sequence: id,
+        kind,
+        summary,
+        evidence: [],
+        filesTouched: [`file${id}.ts`],
+        commandsRun: [],
+        metadata: {},
+        capturedAt: "2026-05-05T10:00:00.000Z",
+    };
+}
+test("tip engine is deterministic and sorts top severity first", () => {
+    const signals = [
+        signal(1, "direction_change"),
+        signal(2, "direction_change"),
+        signal(3, "direction_change"),
+        signal(4, "direction_change"),
+        signal(5, "verification_result", "failed"),
+        signal(6, "verification_result", "failed"),
+        signal(7, "verification_result", "failed"),
+        signal(8, "verification_result", "passed"),
+    ];
+    const decisions = [1, 2, 3].map((index) => ({
+        id: `d_${index}`,
+        sessionId: "s1",
+        headline: `Decision ${index}`,
+        why: "",
+        status: "proposed",
+        alignment: null,
+        files: [],
+        sourceSignalIds: [],
+        rawContent: `Decision ${index}`,
+        createdAt: "2026-05-01T10:00:00.000Z",
+        updatedAt: "2026-05-01T10:00:00.000Z",
+        uploadedAt: null,
+    }));
+    const first = analyzeLocalPatterns({ signals, decisions, now: new Date("2026-05-05T10:00:00.000Z") });
+    const second = analyzeLocalPatterns({ signals, decisions, now: new Date("2026-05-05T10:00:00.000Z") });
+    assert.deepEqual(first, second);
+    assert.equal(first.length, 3);
+    assert.equal(first[0]?.severity, "high");
+});
+test("tip engine stays quiet on empty input", () => {
+    assert.deepEqual(analyzeLocalPatterns({ signals: [], decisions: [] }), []);
+});

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@askthew/mcp-plugin",
-  "version": "0.2.7",
+  "version": "0.4.0",
   "private": false,
-  "description": "Ask The W MCP connector for capturing compact coding-agent session signals.",
+  "description": "Ask The W MCP connector for local-first coding-agent decisions, signals, and review.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,14 +11,8 @@
   },
   "files": [
     "README.md",
-    "dist/cli.d.ts",
-    "dist/cli.js",
-    "dist/index.d.ts",
-    "dist/index.js",
-    "dist/install.d.ts",
-    "dist/install.js",
-    "dist/scope.d.ts",
-    "dist/scope.js"
+    "dist/**/*.d.ts",
+    "dist/**/*.js"
   ],
   "keywords": [
     "askthew",
@@ -57,6 +51,9 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.3.0",
+    "better-sqlite3": "^11.10.0",
+    "nanoid": "^5.1.5",
+    "prompts": "^2.4.2",
     "zod": "^3.24.2"
   },
   "devDependencies": {